القائمة
用于将 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 即可。