菜单
用于将 Git 代码变更（git diff）同步更新到项目文档的工具。通过结构化分析代码改动，并生成最小化文档 patch，保持文档与代码一致性。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | sync-doc |
| description | 用于将 Git 代码变更（git diff）同步更新到项目文档的工具。通过结构化分析代码改动，并生成最小化文档 patch，保持文档与代码一致性。 |
| version | 1.2.0 |
| auto_trigger | false |
| trigger_events | ["manual"] |
sync-doc 是一个用于将 Git 代码变更自动同步到项目文档的技能（skill）。
它基于：
/sync-doc --since HEAD~4
或：
/sync-doc --since <commit>
如果当前代码已经 git add，但还没有 git commit，则直接执行：
/sync-doc
此时 skill 应读取 staged diff，并把这些尚未提交的改动同步到文档。
该 skill 用于解决以下问题：
| 参数 | 类型 | 说明 |
|---|---|---|
| since | string | git commit 或 ref（如 HEAD~4）；传入后显式指定同步范围，并覆盖 checkpoint 自动推导 |
| dry-run | boolean | 只输出 diff 不写入文档 |
| force | boolean | 忽略 checkpoint 的去重保护并强制执行，但成功后仍需写入新的 checkpoint |
sync-doc 必须先判断当前仓库中的代码变更状态，再决定 diff 来源。
支持三类输入源：
stage 但未 commit 的索引区改动stage 的工作区改动（unstaged）推荐判断顺序：
--since，忽略 checkpoint，直接读取提交区间 diff对应命令：
git diff <since>..HEAD
git diff --cached
git diff
状态探测建议：
git diff --cached --quiet
git diff --quiet
说明：
git diff <since>..HEAD：用于同步某个已提交区间git diff --cached：用于同步已经 git add 但尚未提交的改动git diff：用于同步尚未 stage 的 unstaged 改动输出作为唯一变更源，且一次执行默认只选择其中一种来源，避免重复计算和重复写文档。
当 staged 与 unstaged 同时存在时，默认行为必须是：
这样可以保持“用户已经准备提交的改动”和“仍在编辑中的改动”边界清晰。
将 raw diff 转换为结构化事件：
{
"file": "src/api/user.ts",
"type": "modify",
"hunks": [
{
"before": "...",
"after": "..."
}
]
}
识别影响的文档模块：
并且必须显式执行“代码路径 -> 文档路径”的目标发现规则，避免把正确内容写入错误文档。
推荐映射规则：
src/api/**、server/api/** -> /docs/api.mdsrc/components/**、ui/** -> /docs/components.mdsrc/features/**、app/**/feature/** -> /docs/features.mdsrc/core/**、src/lib/**、infrastructure/** -> /docs/architecture.md如果一个代码文件同时命中多个规则：
如果仓库中存在更明确的项目约定（如 README.md、CONTRIBUTING.md、docs/INDEX.md 中定义了文档映射关系），应优先使用项目约定覆盖默认映射。
LLM 输入：
生成规则：
输出：
- old section
+ updated section
应用前建议校验：
记录同步状态：
{
"source_type": "commit_range",
"last_synced_commit": "abc123",
"patch_hash": "sha256:xxx",
"affected_docs": ["docs/api.md"],
"timestamp": 1710000000
}
如果同步来源不是 commit range，则应记录来源快照，而不是伪造 commit：
{
"source_type": "staged",
"base_commit": "abc123",
"tree_hash": "def456",
"patch_hash": "sha256:xxx",
"affected_docs": ["docs/components.md"],
"timestamp": 1710000000
}
每次成功 sync 后记录：
commit_range / staged / unstaged）用于：
特殊要求：
HEAD，因为代码尚未提交同一输入必须保证：
多次执行结果一致（idempotent）
规则：
为了避免行为歧义，参数优先级必须固定如下：
--sincecheckpointstaged diffunstaged diff具体规则：
--since 时，不读取 checkpoint 决定范围，只可将 checkpoint 作为历史记录参考--since 且 checkpoint 可用时，应优先尝试增量同步--force 只跳过去重保护，不改变 diff 来源优先级git diff --cached --quiet 且 git diff --quiet 都为成功，且未传入 --since 时/sync-doc 执行结束后，应该输出结构化摘要，至少包含：
source_typebase_ref 或 sincecheckpoint 是否写入成功推荐输出示例：
sync-doc completed
source_type: staged
base_ref: HEAD
changed_code_files: 3
updated_docs:
- docs/api.md
- docs/components.md
checkpoint_written: true
manual_review: 1
skipped_files: 0
note: unstaged changes detected but not included in this run
当开启 --dry-run 时：
/docs
api.md
components.md
architecture.md
/.sync
checkpoint.json
events/
001.json
本 skill 不负责：
必须依赖：
为了覆盖最常见的使用习惯，推荐 /sync-doc 默认行为如下：
/sync-doc --since <ref>：同步指定提交范围/sync-doc 且存在 staged 改动：同步 staged 改动/sync-doc 且无 staged 但有 unstaged 改动：同步 unstaged 改动/sync-doc 且两者都没有：直接退出并提示这意味着在“用户改完代码，已经 stage，但还没 commit”的场景下，不需要额外参数，直接执行 /sync-doc 即可。