👷 每 3 天同步 DeepWiki Markdown 上下文

[cyfung1031]

Checklist / 检查清单

• Fixes mentioned issues / 修复已提及的问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

N/A — no issue is referenced by this maintenance change.

背景

让 coding agents 可以按需读取 DeepWiki 项目背景，同时避免把单个超大聚合文档塞进上下文。

本次改动

• 保留每 3 天运行一次和手动触发的 .github/workflows/sync-deepwiki.yaml。
• 移除 suwa-sh/deepwiki-to-md wrapper；workflow 直接使用官方无认证 DeepWiki MCP。
• workflow 内嵌全部实现，并拆成独立 Actions steps：prepare、fetch、analyze/split、validate、compare、write、commit。
• 每个阶段都向 $GITHUB_STEP_SUMMARY 写入状态、计数、路径、warning 或完整 failure diagnostics；no-change 运行也会明确记录 write/commit skipped。
• read_wiki_structure 是页面身份 authority；contents 必须一一对应。页面数量、标题、文件名和 index 层级由本次响应动态计算，没有固定页数假设。
• 生成 .deepwiki/index.md 和每个 structure 条目的小型 Markdown 页面；校验页面集合、标题、index 链接、.deepwiki 链接、仓库目标和片段。
• 删除 scripts/sync-deepwiki.mjs，没有新增 standalone 测试脚本。步骤共享的 embedded module 只在 $RUNNER_TEMP 生成。
• Pareto no-change fast path 在完整生成和验证后精确比较文件集合和 UTF-8 内容。无变化时写出 changed=false、report 和 summary，并跳过 write、reread、commit 和 push；write/commit 由 steps.compare.outputs.changed gating。
• 性能优化：analyze 将 checkout 文件清单按原始遍历顺序保存到 $RUNNER_TEMP；validate 和 changed-write 复用经过 version、checkout root、GITHUB_SHA 和路径约束验证的清单，避免重复递归扫描。changed path 从三次扫描降为一次，unchanged path 从两次降为一次。

实现考虑

• 两个 MCP 工具在同一协商 session 中顺序调用，工具错误分别收集后一起报告。
• 结构和 contents 解析错误、标题/数量不一致、未解析页面引用、仓库越界/缺失目标都会失败并汇总。
• no-change 判断只在全部响应、拆分、页面、index、链接和仓库目标验证通过后执行，不会绕过质量检查。
• 代码 fence 内文本保持原样；非法行号片段失败，历史行号超出当前文件长度为 warning。
• Actions step shell wrappers also append captured logs when an embedded command fails before it can produce its normal summary.
• The repository checkout remains frozen between analyze, validate, and write; only the later write step mutates .deepwiki, which is excluded from the inventory.

已知限制

• 为证明 wiki 没有更新，workflow 仍必须 fetch、解析、拆分和验证；优化省略的是文件替换、重新读取、commit 和 push。没有远端版本标识时，不能在验证前安全假设未变化。
• The inventory optimization relies on the workflow's frozen-checkout invariant; it intentionally fails on a missing, malformed, wrong-root, or wrong-revision manifest rather than using an incomplete file set.
• 真实 MCP 下载只在 GitHub Actions 执行。本地验证复用了已保存 cache，没有再次发起网络下载。
• workflow 通过 GITHUB_TOKEN 将刷新后的 .deepwiki 提交到 main，仓库规则必须允许写入。

参考

• DeepWiki MCP documentation
• MCP Streamable HTTP transport
• Pareto improvement

验证

• pnpm run lint — passed.
• pnpm run validate:yaml:all — passed.
• Embedded workflow extraction and node --check — passed.
• Split-step saved-cache changed simulation — fetch, analyze/split, validate, compare, and write all passed; 45 structure pages, 45 contents pages, 46 generated Markdown files, 0 hard problems, 10 historical line-range warnings.
• Split-step saved-cache unchanged simulation — changed=false; report, per-step summary, and explicit write/commit skipped sections were produced.
• Dynamic and failure simulations — dynamic 3-page response passed; invalid-link validation exited non-zero with all 6 problems listed and status marked failed.
• Inventory simulation — 1,257 repository files were saved once and reused; the post-optimization output was byte-for-byte identical to the pre-optimization output; stale revision was rejected with a summary.
• Full repository test suite from the prior implementation — 3,671 passed; 11 unrelated UI tests timed out at the repository's 850 ms threshold.
• git diff --check and commit checks — passed.

Screenshots / 截图

N/A — non-visual CI/documentation change.

[cyfung1031]

@CodFrm warning 部份已经回报至 deepwiki. 他们的人说了会跟进「行数没更新」的问题
warning 不影响。可以先合并