refactor(docs): [SITE-AI-DOCS-01] make generation offline and translation draft based

2026-10-14 00:06:17 -08:00 · 2026-09-14 08:22:44 +08:00
1 parent 647f3e7f12
commit 078cd9ef72
@@ -0,0 +1,148 @@
+{
+  "task": "SITE-AI-DOCS-01",
+  "baseline": "647f3e7f12b1026f7d0de0830080d2d17b23d14d",
+  "node": "24.21.0",
+  "yarn": "1.22.22",
+  "scope": {
+    "corpusSources": 66,
+    "translatedSourceFilesChecked": 13,
+    "newTests": 12,
+    "actualTranslationCalls": 0,
+    "originalDocsUnchanged": true,
+    "playerRuntimeChanged": false,
+    "publicTypesChanged": false,
+    "lockUnchanged": true,
+    "newDependencies": 0
+  },
+  "logs": {
+    "targeted": {
+      "file": "refactor/.cache/ai-docs-targeted.log",
+      "sha256": "a583dd7b803b79f4978e821f4ccc5da20cc71aa937c2221cc35c3926c950f67a",
+      "exitCode": 0,
+      "pass": 18
+    },
+    "finalNewTests": {
+      "file": "refactor/.cache/ai-docs-tests-final.log",
+      "sha256": "004aac934d67c1afcf39bfb8df81a70b47800d3fcab5677671f999ca357f75a9",
+      "exitCode": 0,
+      "pass": 12
+    },
+    "baseline": {
+      "file": "refactor/.cache/ai-docs-baseline.log",
+      "sha256": "5141e44306af3f8ffb9394bd82052130f844b4646f0b6df90e3e35a7ef90ddd6",
+      "exitCode": 0,
+      "pass": 522
+    },
+    "ci": {
+      "file": "refactor/.cache/ai-docs-ci.log",
+      "sha256": "9e694e53f168ec66c0dec0534bf7cf864f04dd1a5cccb8ab57ab26d9a3731b79",
+      "exitCode": 0,
+      "pass": 50
+    },
+    "rootLint": {
+      "file": "refactor/.cache/ai-docs-root-lint.log",
+      "sha256": "ad86c4dffcbe4299d3562782b81dff61e3861c85f67ab1150c54d5ba087972e1",
+      "exitCode": 0
+    },
+    "finalTargetLint": {
+      "file": "refactor/.cache/ai-docs-target-lint.log",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "exitCode": 0
+    },
+    "finalTypes": {
+      "file": "refactor/.cache/ai-docs-types-final.log",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "exitCode": 0
+    },
+    "toolchain": {
+      "file": "refactor/.cache/ai-docs-toolchain.log",
+      "sha256": "b7128a2d927b05010f6af07089db147ec84f7c388d29f2d231e93184e5a7e005",
+      "exitCode": 0
+    },
+    "corpus": {
+      "file": "refactor/.cache/ai-docs-corpus.log",
+      "sha256": "e771bcea47e40862939d82de90baff765f8c679dd1b6d8414c6d767257e6543b",
+      "exitCode": 0
+    },
+    "finalRiskAndInventory": {
+      "file": "refactor/.cache/ai-docs-status-final.log",
+      "sha256": "bec1072cc3711bb89e98c717eda1b06c9f476ed0fd13f252238ceca6ff466caf",
+      "exitCode": 0,
+      "pass": 3
+    },
+    "generatedSourceWhitespace": {
+      "file": "refactor/.cache/ai-docs-whitespace.log",
+      "sha256": "068d10caf7b7d2719bfeafc79a704d91bcb7e19b05e2b8b495f106a380da2710",
+      "exitCode": 2
+    }
+  },
+  "sources": [
+    {
+      "file": "scripts/build-llm.js",
+      "sha256": "0de87f528ab5f27aef4a02fa7219818bc9d76797aa1a8015b8f54c4e168fa3d2"
+    },
+    {
+      "file": "scripts/trans-docs.js",
+      "sha256": "126fe0a92d441e065a5db1a69c0492931542c2b66a4f3c1f5b92051bc702d276"
+    },
+    {
+      "file": "scripts/tsconfig.docs.json",
+      "sha256": "381835bb07fc3245b6cbf6077ef74159d2fc75808bea5c074d6af0f9565612ea"
+    },
+    {
+      "file": "package.json",
+      "sha256": "400a1f3aa48f023099eaca0ab35dc686d4b4570f73861d6c3b8046d29fde25ed"
+    },
+    {
+      "file": "test/documentation-pipeline.test.js",
+      "sha256": "29e60c7a2a2f184486b85d1288c4abed6cd9e90cc830dbec347d56b3a3845afe"
+    },
+    {
+      "file": "scripts/documentation/cli.ts",
+      "sha256": "82026bc026adecd3c97b0ee5adbe5b25a4dd1e679b2a7fdecde3f18a96919af6"
+    },
+    {
+      "file": "scripts/documentation/corpus.ts",
+      "sha256": "f916f63822b9e53a26d2017c0004a576c1fbdf0af0f839c296c8e3d2a14bb2c1"
+    },
+    {
+      "file": "scripts/documentation/files.ts",
+      "sha256": "f445f39e96176a754590d6fb336f2df54ca7735cbc8b3b95057f4c2bb1fb3263"
+    },
+    {
+      "file": "scripts/documentation/markdown.ts",
+      "sha256": "8b0f690348ece7f645bc00ece144528656fed069c569e0ae204c773486c34264"
+    },
+    {
+      "file": "scripts/documentation/README.md",
+      "sha256": "fcf5085edb2e9a6dcdedb2515b3a8224ad5d0a940f6de189382da2d50b87b6ad"
+    },
+    {
+      "file": "scripts/documentation/remote.ts",
+      "sha256": "368ae90bea04b267392b6c85cd8a77f0f72986ca0f17eadb0b6c5655d8562f05"
+    },
+    {
+      "file": "scripts/documentation/translation.ts",
+      "sha256": "52dd973ae30341ebebe39c01011b87b0a5f37702297263f10a1417dad2dc10bd"
+    }
+  ],
+  "outputs": [
+    {
+      "file": "docs/llms.txt",
+      "sha256": "2dac26861645bdf8f449eb8a3b5e197ecf0bb93e124a4f038ef3d71e6783ad08"
+    },
+    {
+      "file": "docs/llms.manifest.json",
+      "sha256": "bb9b81870f74706965975b998ecf40a8c8496ad1d6cfe46d049de0d84212bbbf"
+    }
+  ],
+  "outputSha256Lf": "2dac26861645bdf8f449eb8a3b5e197ecf0bb93e124a4f038ef3d71e6783ad08",
+  "limitations": [
+    "No paid/remote translation or English quality acceptance",
+    "Caught apply failures can roll back; process crash/power loss is not a multi-file transaction",
+    "Concurrent writer conflicts are reported, not overwritten",
+    "No browser/device/full VitePress/remote CI/Pages/npm validation in this tool task",
+    "522 baseline tests preceded final risk/status updates, which receive targeted checks",
+    "git diff --check reports original English :::warning trailing space and generated bundle EOF separator; non-corpus source diff check passes. Original Markdown whitespace is intentionally preserved."
+  ]
+}
@@ -18126,11 +18126,11 @@
    },
    {
      "file": "scripts/build-llm.js",
-      "sha256Lf": "6159c455938c8a40bb3e570f8160d28aac6a1808ec428023d027f974791edb4e"
+      "sha256Lf": "0de87f528ab5f27aef4a02fa7219818bc9d76797aa1a8015b8f54c4e168fa3d2"
    },
    {
      "file": "scripts/trans-docs.js",
-      "sha256Lf": "c78c685c9d4145cfe7f4cbdc8c24773bba9ea4fa4c2f171b96ef42c269edd581"
+      "sha256Lf": "126fe0a92d441e065a5db1a69c0492931542c2b66a4f3c1f5b92051bc702d276"
    },
    {
      "file": "scripts/projects.js",
@@ -18200,6 +18200,30 @@
      "file": "scripts/editor-declarations/vast-sdk.ts",
      "sha256Lf": "6da9176284b7a697a922b90befa64263e016f12eef483793cc524bdfc028ad05"
    },
+    {
+      "file": "scripts/documentation/cli.ts",
+      "sha256Lf": "82026bc026adecd3c97b0ee5adbe5b25a4dd1e679b2a7fdecde3f18a96919af6"
+    },
+    {
+      "file": "scripts/documentation/corpus.ts",
+      "sha256Lf": "f916f63822b9e53a26d2017c0004a576c1fbdf0af0f839c296c8e3d2a14bb2c1"
+    },
+    {
+      "file": "scripts/documentation/files.ts",
+      "sha256Lf": "f445f39e96176a754590d6fb336f2df54ca7735cbc8b3b95057f4c2bb1fb3263"
+    },
+    {
+      "file": "scripts/documentation/markdown.ts",
+      "sha256Lf": "8b0f690348ece7f645bc00ece144528656fed069c569e0ae204c773486c34264"
+    },
+    {
+      "file": "scripts/documentation/remote.ts",
+      "sha256Lf": "368ae90bea04b267392b6c85cd8a77f0f72986ca0f17eadb0b6c5655d8562f05"
+    },
+    {
+      "file": "scripts/documentation/translation.ts",
+      "sha256Lf": "52dd973ae30341ebebe39c01011b87b0a5f37702297263f10a1417dad2dc10bd"
+    },
    {
      "file": "packages/artplayer-vitepress/browser/editor-loader.ts",
      "sha256Lf": "7cfdc82726d164d450b21680d950ec3f508482f1ab743febee473855248568e1"
@@ -18224,7 +18248,7 @@
    "build:i18n": "node ./scripts/build-i18n.js",
    "build:test": "node ./scripts/build-test.js",
    "build:all": "yarn ci:build && yarn lint",
-    "ci:build": "yarn build:types && yarn build all && yarn build:i18n && yarn build:ts && yarn build:test && yarn build:docs && yarn test:imports",
+    "ci:build": "yarn build:types && yarn build all && yarn build:i18n && yarn build:ts && yarn build:llm && yarn build:test && yarn build:docs && yarn test:imports",
    "build:types": "node scripts/build-types.mjs --write"
  },
  "siteManifest": {
@@ -0,0 +1,65 @@
+# SITE-AI-DOCS-01 离线文档与翻译草稿
+
+起点 `647f3e7f12b1026f7d0de0830080d2d17b23d14d`。从 SITE-03 拆出 LLM
+文档和翻译工具链，父任务保留 i18n/VitePress 编排、桌面 common.js UI 迁移。
+核心/插件运行时、公开类型、DOM/CSS、分发入口、版本及 yarn.lock 均未修改。
+
+## 实现及兼容
+
+- `scripts/documentation/` 以严格 TS 拆分 CLI、来源聚合、Markdown 保护、请求、
+  草稿调度/应用和文件操作。旧 build-llm.js/trans-docs.js 命令路径保留为 checked
+  JS 适配层。模块 README 记录数据流、状态、资源、命令、维护入口及限制。
+- 固定起点旧函数的隔离复现确认：翻译 main 在第一次请求前递归删除英文目录，
+  API 失败后人工维护页面消失；启发式 fence 修补破坏包含 `##`/`:::` 的合法
+  代码；最后一次 429 退出循环后返回 undefined。新流程不沿用这些缺陷。
+- build:llm 改为离线、确定顺序、保留 LF 归一后的源文本。输出仍为 docs/llms.txt，
+  增加来源/output SHA-256 清单。当前 66 个来源：13 英文 Markdown、实际加载的
+  22 编辑器声明、30 示例、1 VAST 类型 notices；不收入未加载的遗留 WebSR 声明。
+  原三组标题保留，增加 notices。完整源码替代远程摘要，内容体积变化有意为之。
+- trans:docs 默认只显示计划；只有显式 --remote 才读取 dotenv/key、请求原
+  DeepSeek endpoint/model。生成独立 ignored 草稿，不写英文目录。翻译范围保持
+  index/advanced/component/start，共 13 篇，没有顺便生成 Danmuku 英文页面。
+  老自动化需改为 --remote、复核草稿、--apply；这是内部维护命令的明确缺陷修正，
+  不涉及消费包 API。请求仍可能产生服务费用，本任务没有执行实际远程请求。
+- 保护并恢复代码/HTML/指令块，校验内联代码、链接和 Markdown 结构；分段有界，
+  不拆 UTF-16 代理对。无效响应拒绝而非修补。单 worker 失败中止并等待所有
+  worker；429/5xx/传输失败有界重试，认证/无效 JSON/空响应直接失败。计时覆盖
+  响应正文读取，finally 清理，失败 HTTP body 取消。
+- --validate 允许复核后修改草稿散文，但必须保持结构和源/目标指纹；它不证明
+  翻译质量。--apply 全集预检、逐文件复检、临近临时文件替换，捕获失败后逆序
+  恢复原始字节。过期源/目标、映射篡改、目录越界以及悬空链接均拒绝。未选中
+  的英文页面保留；并发作者改写时拒绝覆盖该文件并报告 aggregate error。
+- 回滚不是跨文件崩溃事务：原始字节只在进程内，断电/强杀可能部分应用；目录
+  检查也不是针对恶意并发文件系统攻击的沙箱。README 明确先保留 Git 状态、
+  失败后检查 diff 和草稿。这些限制不伪称为全局事务保证。
+
+## 工程与验证
+
+无新增依赖。使用 Node24.21.0/Yarn1.22.22、现有 TS5.9.3、glob13.0.6、
+dotenv17.2.4 和 Markdown 工具链。新增 check:llm 进入 ci:check，离线 build:llm
+在 ci:build 的 build:ts 后执行；trans:docs --remote 不进入 CI。文档模块进入
+根 lint/docs-tools 严格检查，测试进入 test:node，当前站点清单同步 TS 文件指纹。
+
+- 新增 12 项测试：旧缺陷复现、全部 13 篇实际源文件往返、保护标记/结构拒绝、
+  请求失败、并发取消/等待、复核应用、过期输入、路径篡改/链接、回滚及并发修改、
+  重试/认证/无效响应、离线可复现与默认不联网。真实 loopback HTTP 服务复现
+  headers 已到而 body 卡住，超时能够中止；服务/连接在 finally 关闭。
+- 连同编辑器生成、文档退出码、站点清单共 18 项通过；最后补充悬空链接拒绝后
+  12 项再次通过、目标 lint 和严格类型复验通过。CI 回归 50 项通过。
+- 根 lint 最终 0 error/1 既有生成声明 warning；一次新增 README 空行错误已修正。
+  工具链、只读来源一致性及计划/风险/站点清单检查通过。完整基线结果与源/产物
+  指纹见 [验证清单](../baselines/documentation-pipeline-validation.json)。
+- 全量 git diff --check 报告两处生成语料空白：英文 start/i18n.md 第 9 行原有
+  `:::warning ` 尾空格和语料末尾分隔空行。保留源文本是此输出的用途，没有
+  修剪 Markdown 或伪称全量空白检查通过；排除该生成语料后的源码检查通过。
+
+当前中英文 Markdown 文件与起点完全相同。没有调用 DeepSeek、应用真实翻译、
+验证英文语义质量、生成完整 docs/document、执行浏览器或设备/远端 CI/Pages/npm。
+既有播放器/插件验收仍由各自任务完成，本任务不扩大这些验收结论。
+
+## 交接与回退
+
+按独立任务提交，随后运行提交审计；无推送或发布。生成文件仅通过源码工具
+更新。回退本提交会恢复旧远程和删除行为，优先针对问题修复；若整体回退，应
+停用旧 trans:docs 自动调用以免重现数据丢失。下一步继续 SITE-03 剩余生成和
+桌面 UI，不改变 VAST 默认行为、Auto Thumbnail 首帧或其它开放问题的状态。
@@ -119,3 +119,10 @@ Pages 先调用同一检查/构建 workflow，成功后上传同一次运行生
 | npm 权限、trusted publisher、候选发布 | 未配置、未执行 | CI-03/CI-04 |

 参考：[GitHub Pages 自定义 workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)、[setup-node](https://github.com/actions/setup-node)、[actionlint 1.7.12](https://github.com/rhysd/actionlint/releases/tag/v1.7.12)。本轮已核对选用 Actions 的实际 action.yml 和发布 tag 对应 SHA；后续升级需重新检查。
+
+## SITE-AI-DOCS-01 文档生成补充
+
+`ci:check` 新增 `yarn check:llm`，只读校验 `docs/llms.txt` 和来源指纹清单。
+`ci:build` 在 `build:ts` 后运行离线 `build:llm`，不读取 API key 或请求模型。
+文档 TS 模块进入根 lint 和 docs-tools 严格类型检查，文档流程回归进入
+`test:node`。`trans:docs --remote` 不进入 CI；远端工作流运行结果仍待独立验收。
@@ -2,9 +2,9 @@

 > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。

-基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 241 项，范围 22 个包及工作区/示例。
+基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 242 项，范围 22 个包及工作区/示例。

-状态：todo 59 / doing 15 / blocked 0 / done 167 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 59 / doing 15 / blocked 0 / done 168 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。

@@ -35,7 +35,7 @@
 | artplayer-proxy-mediabunny | 1.2.0 | PKG-MB-01, PKG-MB-02, PKG-MB-03, PKG-MB-04, PKG-MB-05, PKG-MB-06, PKG-MB-07, PKG-MB-08, PKG-MB-09, PKG-MB-10 |
 | artplayer-tool-iframe | 1.1.0 | PKG-IFRAME-01, PKG-IFRAME-02, PKG-IFRAME-03, PKG-IFRAME-04, PKG-IFRAME-05, PKG-IFRAME-06 |
 | artplayer-tool-thumbnail | 4.4.0 | PKG-TOOL-THUMB-01, PKG-TOOL-THUMB-02, PKG-TOOL-THUMB-03, PKG-TOOL-THUMB-04, PKG-TOOL-THUMB-05, PKG-TOOL-THUMB-06 |
-| artplayer-vitepress | 1.1.0 | SITE-01, SITE-SMOKE-01, SITE-02, SITE-LOAD-01, SITE-03, SITE-04, SITE-05, SITE-06, SITE-07 |
+| artplayer-vitepress | 1.1.0 | SITE-01, SITE-SMOKE-01, SITE-02, SITE-LOAD-01, SITE-AI-DOCS-01, SITE-03, SITE-04, SITE-05, SITE-06, SITE-07 |

 ## 0 规划

@@ -384,7 +384,8 @@
 | SITE-SMOKE-01 | artplayer-vitepress, workspace<br>迁移示例生成器并验证真实就绪与清理 | SITE-01 | TS Markdown 解析/生成与浏览器运行模块；旧命令和 URL、稳定实例就绪 smoke、错误与资源清理 | 复现旧 malformed 死循环并保证有限失败；保留全部既有示例内容、生成确定且 check 只读；不再以 100ms 作为成功，验证原生就绪、异常、取消与清理；三浏览器检查，明确延迟交互与全部 233 示例仍需 EX-03 | M | done |
 | SITE-02 | artplayer-vitepress<br>整理声明与示例生成器 | SITE-01, ENG-04, ENG-06, SITE-SMOKE-01 | build-ts/build-test 生成链的可验证 TS 脚本 | 不靠字符串拼接掩盖声明错误，生成示例有真实断言或仅标 smoke；替换固定 100ms 成功判定，明确异步错误、清理和生成覆盖限制；坏代码块解析必须终止，覆盖 malformed 分支不推进 regexp 的回归 | M | done |
 | SITE-LOAD-01 | artplayer-vitepress, workspace<br>修复文档示例加载顺序与导航边界 | SITE-02 | 共享 TS loader、移动入口与 Run Code/语言路由，保留 URL 和使用方式 | 旧版复现 define 丢失和依赖乱序；真实浏览器验证成功/失败恢复、顺序、去重、编码/优先级及 localhost/127 路由和语言跳转；不以此替代 SITE-03 构建/翻译流程 | M | done |
-| SITE-03 | artplayer-vitepress<br>整理 i18n/文档/LLM 生成流程 | SITE-02, SITE-LOAD-01 | build-i18n/build-docs/build-llm/trans-docs 的任务边界和错误处理；桌面 common.js 自有 UI 的 TS 迁移与模块拆分 | 原命令兼容、生成可复现，翻译步骤不隐式运行远程服务；覆盖移动 loader 失败恢复 define、脚本依赖顺序、localhost/127.0.0.1 Run Code 目标和语言重定向；桌面剩余 UI 完成 TS 职责拆分并回归运行、导入与持久设置 | M | todo |
+| SITE-AI-DOCS-01 | artplayer-vitepress, workspace<br>重构可复现 LLM 文档与安全翻译草稿流程 | SITE-LOAD-01, SITE-02 | TS 离线文档聚合、显式远程翻译、草稿校验和可回退应用，保留命令与目标路径 | 默认不读密钥/调用网络；LLM 内容可复现并保留来源；旧翻译破坏性行为有复现；错误/限流/超时/结构损坏/过期/路径越界拒绝且英文文档不丢失；未执行付费翻译不计服务验收 | M | done |
+| SITE-03 | artplayer-vitepress<br>整理 i18n/文档/LLM 生成流程 | SITE-02, SITE-LOAD-01, SITE-AI-DOCS-01 | build-i18n/build-docs/build-llm/trans-docs 的任务边界和错误处理；桌面 common.js 自有 UI 的 TS 迁移与模块拆分 | 原命令兼容、生成可复现，翻译步骤不隐式运行远程服务；覆盖移动 loader 失败恢复 define、脚本依赖顺序、localhost/127.0.0.1 Run Code 目标和语言重定向；桌面剩余 UI 完成 TS 职责拆分并回归运行、导入与持久设置 | M | todo |
 | SITE-04 | artplayer-vitepress<br>交叉核对逐包持续维护的文档 | CORE-21, SITE-03, PKG-CHAPTER-04, PKG-AMBILIGHT-04, PKG-AUDIO-04, PKG-AUTO-THUMB-04, PKG-VTT-THUMB-04, PKG-HLS-04, PKG-DASH-04, PKG-MULTI-SUB-04, PKG-JASSUB-04, PKG-MASK-04, PKG-ASR-04, PKG-ADS-04, PKG-VAST-04, PKG-CAST-04, PKG-DPIP-04, PKG-CANVAS-04, PKG-IFRAME-04, PKG-TOOL-THUMB-04, PKG-DANMUKU-06, PKG-MB-08 | 已随实现更新的中文/英文 API、包内实现地图、旧 JS 示例及已知能力限制的全包核对 | 未把缺环境的能力写成已验证，静态核对不等待设备任务；最终 demo 仍由 EX-03 验收；按 SITE-01 声明成员/候选标题清单逐项语义核对，补齐缺失的双语插件说明和 Danmuku 英文入口 | M | todo |
 | SITE-05 | artplayer-vitepress<br>构建文档站和验证链接/示例 | SITE-04, EX-01, EX-02, SITE-07 | VitePress 构建、链接与嵌入 demo 检查 | 文档构建、链接、嵌入路径与声明注入通过；真实完整 demo 保留 EX-03 独立门槛；核对 ENG-PM-01 登记的搜索 peer 范围和真实搜索行为 | M | todo |
 | SITE-06 | artplayer-vitepress<br>文档站交付验收 | SITE-05 | 维护指南和站点变更记录 | 未手改 generated 目录，旧 URL 可用、部署与检查分离 | M | todo |
@@ -611,6 +612,7 @@
 - SITE-SMOKE-01: [记录](changes/2026-09-14-SITE-SMOKE-01-documentation-smoke.md) [记录](baselines/docs-smoke-validation.json) [记录](scripts/docs-smoke.test.mjs)
 - SITE-02: [记录](changes/2026-09-14-SITE-02-editor-declarations.md) [记录](baselines/editor-declarations-validation.json) [记录](changes/2026-09-14-SITE-SMOKE-01-documentation-smoke.md)
 - SITE-LOAD-01: [记录](changes/2026-09-14-SITE-LOAD-01-site-loading.md) [记录](baselines/site-loading-validation.json)
+- SITE-AI-DOCS-01: [记录](changes/2026-09-14-SITE-AI-DOCS-01-documentation-pipeline.md) [记录](baselines/documentation-pipeline-validation.json)
 - SITE-07: [记录](site-inventory.md) [记录](baselines/site-provenance.json)
 - EX-01: [记录](changes/2026-09-14-EX-01-react-consumer.md) [记录](baselines/react-consumer-validation.json) [记录](scripts/react-consumer.mjs)
 - EX-02: [记录](changes/2026-09-14-EX-02-vue-consumer.md) [记录](baselines/vue-consumer-validation.json) [记录](scripts/vue-consumer.mjs)
@@ -1,5 +1,22 @@
 # 进度与证据

+## SITE-AI-DOCS-01 文档工具完成
+
+将 build-llm/trans-docs 拆为严格 TS 模块，保留旧命令路径。离线 LLM 文件含
+66 个原始来源及指纹清单，生成/只读检查进入 CI；翻译默认只显示计划，显式
+远程操作先生成草稿，校验后应用，捕获写入失败时回滚并保护并发作者修改。
+已复现并修复旧工具先删英文、错误修补代码块及最后 429 返回 undefined。
+新增 12 项测试、目标组合 18 项、完整 baseline 522 项、CI 回归 50 项通过。
+严格类型、工具链和 lint 通过（根 lint 1 条既有 warning）；最终悬空链接修复
+后复跑新测试/目标 lint/类型。当前中英文源文档与起点一致，无远程翻译或
+发布。崩溃/断电不具备跨文件事务保证，英文质量与浏览器验收未计入本任务。
+见[变更](changes/2026-09-14-SITE-AI-DOCS-01-documentation-pipeline.md)和
+[证据](baselines/documentation-pipeline-validation.json)。当前 242 项：168 done、
+15 doing、59 todo。下一步 SITE-03 剩余 i18n/VitePress 编排和桌面 UI 迁移；
+VAST 默认行为、Auto Thumbnail 首帧及各包最终验收保持开放。独立本地提交并
+审计，无推送或发布。
+
+
 ## SITE-LOAD-01 示例加载与导航完成

 从 SITE-03 拆出共享 TS loader、移动入口与 Run Code/语言导航；恢复 define 原
@@ -255,3 +255,4 @@
 | AUTO-THUMB-CANVAS-01 | resolved / 已复现 | Private thumbnail canvas retains sheet dimensions after completion or cancellation while callbacks retain the element | PKG-AUTO-THUMB-07 |
 | EX-REACT-LIFE-01 | resolved / 已复现 | React getInstance exception leaks the constructed player | EX-01 |
 | EX-REACT-ENTRY-01 | resolved / 源码/产物事实 | React HTML references absent main.jsx instead of the existing TSX entry | EX-01 |
+| SITE-TRANS-DATA-01 | resolved / 已复现 | Translation deletes English before requests and repairs valid fences destructively; exhausted rate limits return undefined | SITE-AI-DOCS-01 |
@@ -5753,6 +5753,28 @@
      "compatibleResolution": "The HTML now loads main.tsx; the unchanged App call builds and loads controlled media in all six installed consumer browser profiles.",
      "closureCriteria": "Actual installed consumer and original App entry pass without changing the wrapper props, default configuration or effect dependency contract.",
      "resolutionRationale": "The HTML now loads main.tsx; the unchanged App call builds and loads controlled media in all six installed consumer browser profiles."
+    },
+    {
+      "id": "SITE-TRANS-DATA-01",
+      "title": "Translation deletes English before requests and repairs valid fences destructively; exhausted rate limits return undefined",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "SITE-AI-DOCS-01"
+      ],
+      "evidence": [
+        "refactor/changes/2026-09-14-SITE-AI-DOCS-01-documentation-pipeline.md",
+        "refactor/baselines/documentation-pipeline-validation.json",
+        "test/documentation-pipeline.test.js"
+      ],
+      "compatibleResolution": "Keep CLI paths and translation source scope; make default local, request into isolated drafts, validate and explicitly apply with caught-error rollback. Preserve player public APIs.",
+      "closureCriteria": "Frozen old-function tests reproduce deletion, fence damage and undefined 429; candidate tests retain existing English on failed/damaged/stale requests and verify reviewed apply, rollback, cancellation and bounded request/body lifetime.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-14-SITE-AI-DOCS-01-documentation-pipeline.md",
+        "refactor/baselines/documentation-pipeline-validation.json",
+        "test/documentation-pipeline.test.js"
+      ],
+      "resolutionRationale": "Twelve candidate regressions pass, including actual 13-file Markdown round-trip and local HTTP stalled body. No live translation was applied. Power loss and hostile concurrent filesystem mutation are explicitly outside transaction guarantees."
    }
  ]
 }
@@ -78,7 +78,7 @@ export function captureSiteInventory() {
    pages: demo.pages,
    baselinePaths: { examplesAdded: demo.examples.filter(row => !historical.examples.some(old => old.source === row.source)).map(row => row.source), examplesRemoved: historical.examples.filter(row => !demo.examples.some(now => now.source === row.source)).map(row => row.source), htmlAdded: demo.pages.filter(row => !historical.pages.some(old => old.source === row.source)).map(row => row.source), htmlRemoved: historical.pages.filter(row => !demo.pages.some(now => now.source === row.source)).map(row => row.source) },
    editorDeclarations: [...read('docs/assets/js/common.js').matchAll(/'\.\/assets\/ts\/([^']+\.d\.ts)'/g)].map(match => ({ file: `docs/assets/ts/${match[1]}`, exists: fs.existsSync(path.join(root, 'docs/assets/ts', match[1])), owner: 'SITE-02' })),
-    scripts: [...scriptFiles, 'scripts/build-site-assets.mjs', ...files('scripts/docs-smoke').filter(file => file.endsWith('.ts')), ...files('scripts/editor-declarations').filter(file => file.endsWith('.ts')), ...files('packages/artplayer-vitepress/browser').filter(file => file.endsWith('.ts'))].map(file => ({ file, sha256Lf: hash(read(file)) })),
+    scripts: [...scriptFiles, 'scripts/build-site-assets.mjs', ...files('scripts/docs-smoke').filter(file => file.endsWith('.ts')), ...files('scripts/editor-declarations').filter(file => file.endsWith('.ts')), ...files('scripts/documentation').filter(file => file.endsWith('.ts')), ...files('packages/artplayer-vitepress/browser').filter(file => file.endsWith('.ts'))].map(file => ({ file, sha256Lf: hash(read(file)) })),
    generationCommands: Object.fromEntries(Object.entries(json('package.json').scripts).filter(([name]) => /^(?:build:(?:types|ts|test|i18n|docs|llm|all)|ci:build)$/.test(name))),
    siteManifest: json('packages/artplayer-vitepress/package.json'),
    assets,
@@ -77,12 +77,13 @@ loadScript 暂时覆盖 window.define：桌面成功/失败均恢复，移动失
 | build:test | 中文 Run Code → docs/test/test.js | 排除 en/plugin/public/.vitepress；100ms done 只是 smoke，含生成时间戳；SITE-02 |
 | build:i18n | 核心语言源 → dist/i18n、compiled/i18n | 排除内置语言/发布辅助，逐包构建；SITE-03 |
 | build:docs | VitePress 源 → docs/document | 当前 npm 子进程只是运行脚本；SITE-03 统一 Yarn 编排 |
-| build:llm | 英文文档、编辑器声明、示例 → docs/llms.txt | 明确远程 DeepSeek 操作；SITE-03 |
-| trans-docs.js | 中文 Markdown → 英文 Markdown | 明确远程 DeepSeek 操作；SITE-03 |
+| build:llm | 英文文档、实际编辑器声明、示例、声明 notices → docs/llms.txt + manifest | SITE-AI-DOCS-01 离线可复现；check:llm 只读检查 |
+| trans-docs.js | 中文 Markdown → 草稿 → 经检查应用英文 Markdown | 默认只显示计划；显式 --remote 请求，--validate / --apply 分步处理 |

 build:test 的 malformed 分支在 continue 前不推进 regexp，存在同一坏块重复扫描的源码路径；
 SITE-02 必须加入可终止的坏文档反例。未运行该路径或把它计作已修复。
-build:all/ci:build 当前不调用远程翻译或 LLM。SITE-03 应保留这一边界。
+build:all/ci:build 不调用远程翻译；SITE-AI-DOCS-01 将离线 build:llm 纳入
+ci:build，将只读 check:llm 纳入 ci:check。远程草稿与英文质量复核仍单独执行。

 `scripts/projects.js` 明确排除 VitePress 的库构建；配置 base=/document/，输出到仓库 docs/document。
 Pages 工作流消费已验证的 docs artifact，部署与检查分离。manifest 未设 private，且没有
@@ -4168,6 +4168,27 @@
        "baselines/site-loading-validation.json"
      ]
    },
+    {
+      "id": "SITE-AI-DOCS-01",
+      "phase": "6 文档与消费者",
+      "title": "重构可复现 LLM 文档与安全翻译草稿流程",
+      "scope": [
+        "artplayer-vitepress",
+        "workspace"
+      ],
+      "dependsOn": [
+        "SITE-LOAD-01",
+        "SITE-02"
+      ],
+      "status": "done",
+      "risk": "M",
+      "deliverable": "TS 离线文档聚合、显式远程翻译、草稿校验和可回退应用，保留命令与目标路径",
+      "acceptance": "默认不读密钥/调用网络；LLM 内容可复现并保留来源；旧翻译破坏性行为有复现；错误/限流/超时/结构损坏/过期/路径越界拒绝且英文文档不丢失；未执行付费翻译不计服务验收",
+      "evidence": [
+        "changes/2026-09-14-SITE-AI-DOCS-01-documentation-pipeline.md",
+        "baselines/documentation-pipeline-validation.json"
+      ]
+    },
    {
      "id": "SITE-03",
      "phase": "6 文档与消费者",
@@ -4177,7 +4198,8 @@
      ],
      "dependsOn": [
        "SITE-02",
-        "SITE-LOAD-01"
+        "SITE-LOAD-01",
+        "SITE-AI-DOCS-01"
      ],
      "status": "todo",
      "risk": "M",