开发文档发布与防漂移机制

单一事实来源

框架契约、标准示例、仓库维护的知识文章和验证流程以 Git 中的 Markdown 为唯一事实来源。scripts/generate-docs-page.mjs 将这些文件确定性生成到 worker/docs_page.js。

官网为了保留后台预览、版本历史和回滚能力，公开 HTML/Markdown 路由会读取 D1 中的已发布快照。因此只部署 Worker 不会自动覆盖既有正文；发布者必须显式运行 scripts/generate-docs-content-sync-sql.mjs，把 Git 构建内容写入 D1 的草稿、已发布版本、修订记录和审计记录。脚本保留导航等附加字段，不删除自定义运营文章。

可追溯清单

生成器同时输出 DOCS_MANIFEST，公开部署后由 /docs/manifest.json 返回。清单包含：

• 框架版本和契约版本；
• 仓库地址与 source_of_truth: git；
• 每篇公开文档的 Git 单一或组成源路径、HTML 路由、Markdown 路由、实际公开正文 SHA-256 和证据等级。

具体 Git commit 由发布提交和部署记录关联，避免把 commit 写入被该 commit 自身包含的生成文件而产生自引用。发布记录必须登记部署所用 commit。

修改和发布流程

1. 修改 Markdown、共享示例源或运行时；
2. 运行 pnpm run generate:amazon（修改 Amazon 共享逻辑时）和 pnpm run build:docs；
3. 运行 pnpm run verify，生成文件必须与源一致；
4. 提交源文件和 worker/docs_page.js，在发布记录登记 commit；
5. 经产品负责人确认后部署 Worker；
6. 生成文档快照 SQL 和 D1 安全分片，例如 node scripts/generate-docs-content-sync-sql.mjs --version 1.9.1 --output output/releases/1.9.1/docs-content-sync.sql --chunk-dir output/releases/1.9.1/docs-content-sync；逐个以 pnpm dlx wrangler d1 execute alexa_hub --remote --yes --file <分片> 执行，避免合并 SQL 过大触发 D1 重置保护；
7. 运行 pnpm run verify:docs-publication -- https://www.sellerfeeds.com，逐篇比较线上清单与 Markdown 内容哈希；
8. 验证开发入口能继续读取示例和知识文章。

Git 管理的文档不能只在后台直接改 D1；下一次同步会以 Git 正文覆盖。要修改契约必须走 Git、测试、review、Worker 部署和 D1 快照同步。新增临时运营文章可使用 D1，但一旦纳入长期开发知识，应迁移到 Git 并进入清单。

失败处理

• 生成器 --check 或 pnpm run verify 失败：不发布；先重新生成并审查差异。
• 线上 manifest 版本/哈希不同：说明部署版本或缓存不一致，不宣称文档已同步。
• Markdown 哈希与 manifest 不同：通常是漏执行 D1 快照同步；停止 AI 验收，生成并执行同步 SQL后重新核对。
• 平台知识证据升级：同步更新知识文章的日期、证据等级、fixture/测试和预期结果，不能只改结论文字。