企业官网建设流程全解析

导读

RenderClassic是 ljg-classic「古文笺」技能中的核心渲染工具：它读取一份符合 InputSchema 的 classic JSON（原文 token + 彩色夹注 + 章节解读），输出完整 HTML、单张长图 PNG 与带哈希校验的 manifest，并可额外生成覆盖全高的重叠 QA 切片用于视觉验收。本文以 RenderClassic.help.md 为主干，结合 RenderClassic.ts 源码与 RenderClassic.test.ts 测试，讲清命令行参数、输入 JSON 约束、渲染前校验、渲染后 DOM 审计与 QA 切片机制，帮助你把一章古文可靠地渲染成可交付的 PNG 长图。

一、RenderClassic 是什么：一份 JSON 产出四种产物

RenderClassic位于 skills/ljg-classic/Tools/RenderClassic.ts，是一个由 Bun 直接执行的命令行工具，一次运行同时产出：

渲染流程固定为「校验 → 生成 HTML → 用 Playwright 无头 Chromium 加载 → DOM 审计 → 截整图 → 可选切重叠切片 → 写 manifest」。依赖在 package.json 中声明为playwright，工具本身不依赖任何远程截图服务。

二、命令行用法与参数详解

2.1 标准调用

bun Tools/RenderClassic.ts \ --input <classic.json> \ --output <classic.png> \ --html <classic.html> \ --width 1080 \ --slices-dir <qa-slices>

2.2 参数总表

运行bun Tools/RenderClassic.ts --help可查看当前参数（输出内容与 RenderClassic.ts 中printHelp一致）。

2.3 参数解析的底层逻辑

从 parseArgs 可以看出三点实现细节：

• --input与--output缺失即报错退出：源码直接抛"--input and --output are required; use --help for usage"。
• 宽度严格校验：Number.parseInt后必须满足整数且落在MIN_WIDTH = 720与MAX_WIDTH = 1600（见 RenderClassic.ts 常量定义）之间，否则抛--width must be an integer from 720 to 1600。
• 默认 HTML 路径推导：省略--html时，用output去掉扩展名后拼接.html，且所有路径都会先resolve成绝对路径，保证后续 Playwright 用file://URL 加载时路径一致。

三、输入 JSON：结构、字段与 heroImage 规则

渲染器读取 UTF-8 JSON，最小结构如下（完整字段说明见 InputSchema.md）：

{ "book": "道德经", "chapter": "第十六章", "heroImage": "assets/第十六章-意旨图.png", "heroAlt": "山谷晨雾中，万物从静处显出往复", "original": "致虚极，守静笃。", "source": "采用通行本；标点为本次整理", "passages": [ { "tokens": [ { "text": "致虚极", "note": "尽力使内心虚静", "tone": "word" }, { "text": "，", "punctuation": true }, { "text": "守静笃", "note": "彻底守住清静", "tone": "clause" }, { "text": "。", "punctuation": true } ] } ], "interpretation": [ "这一章先处理人的观看位置。心被眼前得失占满时，人只能跟着变化跑；把心放空并守住安静，才有机会看见变化重复出现的轨迹。" ] }

3.1 字段要求

3.2 内容不变量（校验的硬性前提）

1. 按 token 顺序拼接text，必须与original逐字一致；
2. punctuation !== true的 token 全部有非空note和合法tone；
3. interpretation不是逐句翻译列表，而是完整章节解读；
4. JSON 中不放 HTML；渲染器统一转义并控制样式；
5. heroImage与heroAlt成对出现；图片在渲染时编码为 data URL，HTML 不保留本地热链；
6. interpretation不得出现「解读边界」；边界条件写进自然段，不显示写作脚手架。

3.3 顶部意旨图（heroImage）规则

文档特别强调：heroImage只接受本地 PNG/JPEG/WebP，路径可为相对 JSON 文件的路径或绝对路径；渲染器会把它编码进 HTML，不保留文件热链。源码把这一规则落实为三道防线：

• 路径合法性：validateSpec用/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i拦截带协议（如https:）或//开头的路径，抛heroImage must be a local file path，见 RenderClassic.ts；测试 RenderClassic.test.ts 验证了远程 URL 与 data URI 都会被拒绝。
• 成对约束：heroImage存在时heroAlt必须为非空字符串；反之单独出现heroAlt会报错。
• 内嵌编码：readHeroDataUri按扩展名映射 MIME（.png→image/png、.jpg/.jpeg→image/jpeg、.webp→image/webp），检查文件存在且非空后转成data:image/...;base64,...，最终写入<figure class="hero">，见 RenderClassic.ts。因此产物 HTML 完全自包含、不依赖任何本地或远程图片资源。

四、渲染前校验：validateSpec 逐项过门

文档原文提到"渲染前会校验原文逐字回读、非标点注解覆盖、tone 枚举、顶部配图和章节解读禁词"，这些全部由 validateSpec 完成，顺序如下：

1. 顶层字段：book、chapter、original必须是非空字符串；passages与interpretation必须是非空数组。
2. hero 规则：本地路径、成对 alt、禁止 URL/data URI（见 3.3）。
3. token 级校验：punctuation若提供必须是 boolean；非标点 token 必须有非空text、非空note、合法tone；标点 token 不允许带note/pinyin/tone。
4. tone 枚举：VALID_TONES为{"word","clause","variant"}，非法值抛tone must be word, clause, or variant。
5. 换行处理：源码允许把换行作为{ "text": "\n", "punctuation": true }单独成 token（锁定底本可能含有意义的行界），同时禁止空格、制表符等空白标点，也禁止把换行夹在text里不拆分——见 RenderClassic.ts，测试 RenderClassic.test.ts 覆盖了这些拒绝分支。
6. 原文逐字回读：把所有 token 的text顺序拼接后与original严格比对，不一致即抛Original round-trip mismatch。测试 RenderClassic.test.ts 用修改original的方式验证了该门禁。
7. 注解覆盖：非标点 token 必须有note，缺注即抛note must be a non-empty string（见测试 RenderClassic.test.ts），从而保证"逐字注解"覆盖率 100%。
8. 章节解读禁词：任何解读段含「解读边界」即抛错（见 RenderClassic.ts），确保写作脚手架不泄漏到交付内容中。

五、渲染产物：HTML 结构、PNG 与 manifest

5.1 HTML 语义骨架

renderHtml（RenderClassic.ts）产出lang="zh-CN"文档，正文按以下顺序排布：

书名（.book，data-book） 章节（h1.chapter，data-chapter） 章节意旨图（可选，figure.hero，data-hero） 原文 + 彩色夹注（article.classic，每段 passage 含 token-unit） 章节解读（section.interpretation，data-interpretation，标题固定「章节解读」） 来源（footer.source，data-source）

夹注的渲染逻辑值得注意：

• 每个非标点 token 包成<span class="token-unit tone-word|tone-clause|tone-variant">bun install bunx playwright install chromium

  不得改用npm、npx、Python 排版脚本或远程截图服务。

  8.2 完整验收闭环

  RenderClassic 负责"渲染"，ValidateClassic 负责"复核"——后者重新解析 JSON、重读 PNG 与 manifest，校验 schemaVersion、路径、original、token/注解/解读统计、DOM 审计结果、字体范围、各文件哈希、hero 存在性与可见性、切片覆盖等是否仍与渲染时一致，成功时 stdout 输出status: "valid"：

  bun Tools/ValidateClassic.ts \ --input <classic.json> \ --png <classic.png> \ --manifest <classic.manifest.json>

  在实际工作流中（见 Workflows/AnnotateAndRender.md），每次渲染都在独占/tmp/ljg-classic.*工作区进行，生成{timestamp}--classic-{safe-name}.json / .html / .candidate.png / .candidate.manifest.json与assets/、qa-slices/；候选 PNG 只有通过 RenderClassic 渲染自检、ValidateClassic 复核和整图/切片目视读回后，才复制到$HOME/Downloads/交付，并对候选与最终 PNG 分别shasum -a 256确认一致。注意 RenderClassic 本身只负责渲染与审计，最终交付路径的复制与哈希比对由工作流步骤完成，这也是"渲染工具"与"交付流程"的职责边界。

  九、快速上手清单

  1. 按 InputSchema 准备classic.json，确保original与 token 拼接逐字一致、非标点 token 全部有note/tone；
  2. 可选配heroImage+heroAlt（本地 PNG/JPEG/WebP，相对 JSON 或绝对路径）；
  3. 运行bun Tools/RenderClassic.ts --input classic.json --output classic.png --html classic.html --width 1080 --slices-dir qa-slices；
  4. 确认 stdout 返回status: "rendered"及 png/html/manifest 路径与真实宽高；
  5. 用 ValidateClassic 复核产物一致性；
  6. 目视检查整图分层、顶部配图、中段夹注与底部完整性，长图用重叠切片逐段检查。

  依赖与脚本约定可在 package.json（bun test/bun render/bun validate三个脚本）与 RenderClassic.test.ts 中继续深入验证。

  赞分享

  【免费下载链接】ljg-skills

  项目地址：https://gitcode.com/gh_mirrors/lj/ljg-skills

  点击查看免费下载

  相关推荐

  • AhabAssistantLimbusCompany：彻底解放双手的智能游戏助手终极指南

    AhabAssistantLimbusCompany：彻底解放双手的智能游戏助手终极指南 你是否有过这样的经历？下班回家只想放松打游戏，却要面对一堆重复的日常任

  • 如何用 PDF.js 在 Node.js 里把 PDF 页面渲染为 PNG 图片？

    如何用 PDF.js 在 Node.js 里把 PDF 页面渲染为 PNG 图片？ 如果你想在 Node.js 环境下（而不是浏览器里）把 PDF 文件转成 P

    前端

  • dom-to-image 完整使用指南：用 JavaScript 把任意 DOM 节点渲染成 SVG/PNG/JPEG 图片

    dom to image 完整使用指南：用 JavaScript 把任意 DOM 节点渲染成 SVG/PNG/JPEG 图片 本指南以仓库根目录的 README

    前端
  上一篇：AI视频生成新手第一课：用Seedance2-Skill快速上手即梦Seedance 2.0提示词（完整指南）

  下一篇：agentic-awesome-skills 编码规范实战详解：覆盖 TypeScript、React、Node.js 与 API 设计的通用代码质量标准