同步文档平台

文档同步是目标项目可选的能力（PRD C13 / P8）。启用后，文档成为一等产物：功能、结构、接口、命令或机制变化时，必须在同一任务中更新文档。本仓库自身已启用 docs-sync.json，内容在 docs/content，发布到共享平台。

目标项目契约

项目根目录的 docs-sync.json 显式启用：

{
  "schema": 1,
  "enabled": true,
  "project": "my-project",
  "contentDir": "docs/content",
  "platform": {
    "url": "https://docs.example.com",
    "tokenEnv": "DOCS_PLATFORM_TOKEN"
  },
  "sync": {
    "baseRef": "main",
    "tracked": ["src/**", "scripts/**"],
    "requireCoverage": true,
    "requireContentChange": true
  }
}

页面是普通 Markdown，frontmatter 声明实现范围：

---
title: Search
description: How search works.
sources:
  - src/search.ts
---

# Search

同步模型

• Coverage：sync.tracked 中每个文件必须被至少一个页面的 sources 匹配。
• Fingerprint lock：docs/sync-lock.json 记录页面与来源文件的 hash；代码变化后必须重新 review 并 stamp。
• Branch content rule：分支改 tracked 代码时必须改内容页；只更新锁不算。
• Integration gate：集成 runner 在项目 check 后执行 docs-sync check，失败不推进 main。
• Agent prompts：任务 brief、冲突/check-failure handoff 和 Paseo 插件 system prompt 都会注入文档规则。

命令

./scripts/docs-sync init --enable --project my-project --title "My Project"
./scripts/docs-sync check
./scripts/docs-sync stamp
./scripts/docs-sync build
./scripts/docs-sync publish
./scripts/docs-sync status

.dev 布局使用 ./.dev/scripts/docs-sync。

发布

发布是集成后的操作：

DOCS_PLATFORM_TOKEN=... ./scripts/docs-sync publish

平台按内容 hash 保存不可变版本；同一内容重复发布是幂等的。页面、搜索、llms.txt、llms-full.txt 和 AI 问答都读取当前发布版本。

共享 Fumadocs 平台

平台实现在 apps/docs，是像 Carseod 一样的共享服务：

• Next.js + Fumadocs UI 渲染 Markdown 页面；
• 多项目发布 API，Bearer project token 鉴权；
• /data/projects/<project>/versions/<sha256> 保存不可变内容，current.json 指向当前版本；
• 搜索与 AI 问答只基于当前发布快照；
• AI 通过 OpenAI-compatible 流式接口接入，未配置模型时文档和搜索仍可用，AI 返回 503。

部署、TLS、反向代理、模型、持久卷与备份要求见仓库中的 docs/docs-platform.md 和 deploy/docs-platform/。

边界

• 文档内容保存在目标项目 Git 中，平台不是编辑器。
• 发布文档不能静默修改 PRD.md / AGENTS.md。
• 文档平台与 Carseod 一样集中部署，不复制进每个目标项目。
• 发布内容是公开的；不要写 token、密钥或未脱敏数据。