feat(docs): 文档自动化同步机制 — 代码变更到文档的定时检测与更新

[Million-mo]

动机

代码持续演进，文档却经常滞后。当前完全依赖人工同步，导致：

• 新增/修改的公开 API 未及时反映到 docs/explanation/ 和 docs/reference/
• AGENTS.md 的 Context Loading 表格指向的文件偶尔失效
• openspec/changes/archive/ 下已归档的变更描述与当前代码实现逐渐偏离
• Diataxis 分类下偶尔混入不属该分类的内容，无人定期复核

issue #224 解决的是「文档应该放哪里」的组织问题；本 issue 解决的是「代码改了之后文档怎么跟上」的同步问题。两者互补。

目标

建立渐进式的文档自动化同步机制，分阶段降低人工负担：

1. 阶段一（低风险）：AI 定时扫描代码变更，开 Issue 报告差异，人工修复
2. 阶段二（中风险）：AI 直接提 PR，人工 review 后合并
3. 阶段三（可选）：低风险变更（如新增公开参数的列举）自动合并

技术方案

利用 OpenCode GitHub 集成（文档）实现定时触发。

阶段一工作流（建议先落地）

# .github/workflows/opencode-docs-sync.yml
name: Docs Sync Audit
on:
  schedule:
    - cron: "0 3 * * 1"  # 每周一凌晨 3 点 UTC
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      issues: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            对比最近 7 天的代码变更与当前文档，找出不一致：
            - 扫描 src/ 下变更的公开 API（新增/删除/重命名/签名变更）
            - 检查 docs/explanation/ 和 docs/reference/ 是否已反映这些变更
            - 检查 AGENTS.md Context Loading 表格指向的文件是否都存在
            - 检查 openspec/changes/archive/ 中近 7 天归档的变更是否已在文档中体现
            产出：开一个 Issue，按严重程度排序列出差异，每条包含：
            1. 代码变更位置（文件:行号）
            2. 对应文档位置（文件:行号）
            3. 具体差异描述
            4. 建议的修复方向
            标题格式：[Docs Sync] 本周代码-文档差异报告 YYYY-MM-DD
            如果没有发现差异，不开 Issue。

Prompt 设计要点

• 只报告事实性差异，不评论文档风格或措辞
• 严重程度分级：API 签名变更 > 交叉引用失效 > 描述与实现不符 > 分类归属错误
• 明确不触发同步的变更类型：内部重构、测试改动、性能优化、依赖升级、格式调整
• 输出结构化：每条差异独立编号，便于后续追踪和统计

依赖与前置条件

• 配置 ANTHROPIC_API_KEY 到仓库 Secrets
• 安装 opencode-agent GitHub App（或使用 GITHUB_TOKEN）
• 确认 API 成本预算（每次扫描约 $0.5-2，取决于变更量）
• issue docs: 统一文档管理体系 — 整合 OpenSpec、RFC、架构文档的分散问题 #224 的文档结构决议（影响扫描范围的定义）

验证标准

阶段一落地后，连续运行 4 周达到以下标准即视为稳定：

• 误报率 < 20%（人工确认无需修复的差异占比）
• 漏报率 < 10%（人工发现的明显差异中，AI 未报告的占比）
• 每次运行成本 < $5
• Issue 报告可读性好，维护者能在 10 分钟内判断是否需要修复

与 #224 的关系

#224 决定文档的最终归属位置，本 issue 假定归属已确定并聚焦于同步机制。建议 #224 先出结构决议，本 issue 的 prompt 再根据决议调整扫描范围。

相关

• docs: 统一文档管理体系 — 整合 OpenSpec、RFC、架构文档的分散问题 #224 — 文档管理体系整合（结构问题）
• 参考：OpenCode GitHub 集成文档
• 项目已有 documentation.yml 负责文档构建部署，本工作流只负责内容审查，不冲突