必须用copilot cli自动化同步代码与文档：通过copilot init选择docs-sync模式，配置sync-rules.yml定义映射规则，用copilot sync手动同步，设husky pre-commit钩子校验一致性，ai修改代码后自动提示同步。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在代码中修改了一个关键函数的参数或行为，但忘记同步更新项目根目录下的API.md文档时，团队新成员会基于过时的文档写出错误的调用方式，而AI助手也会重复输出失效的示例。这种逻辑与文档脱节的问题必须由自动化机制实时拦截。
配置Copilot CLI识别文档同步任务
在终端中进入项目根目录，执行 copilot init 启动初始化向导。
当提示选择“Use case”时，输入 docs-sync 并回车——这是chriscox/agent-skills技能库中专用于文档同步的预设模式，不是通用代码生成选项。
向导将自动检测是否存在 API.md、README.md 或 docs/ 目录，若未找到任一目标，CLI将直接退出并报错，不会创建空配置。
定义代码到文档的映射规则
在项目根目录下新建 .copilot/sync-rules.yml 文件，内容如下：
sources:
- path: "src/utils/**.ts"
doc_target: "API.md"
section: "## Utility Functions"
- path: "src/core/auth.ts"
doc_target: "SECURITY.md"
section: "### Authentication Flow"
每条规则必须包含 path（glob匹配）、doc_target（绝对路径或相对于根目录的路径）和 section（Markdown中已存在的标题锚点，不支持自动生成新标题）。
如果 doc_target 文件不存在，CLI在后续同步时会报错并中断，不会自动创建文件。
触发一次手动同步
方法一：在终端中运行 copilot sync --dry-run 查看将要修改的文档段落和对应代码变更范围。
方法二：直接执行 copilot sync，CLI会扫描所有 sources 中匹配的文件，提取 JSDoc 注释、函数签名、参数类型及返回值描述，按规则注入到目标文档指定 section 下。
方法三：在 VS Code 中右键点击任意 .ts 文件 → 选择 “Copilot: Sync to Docs”，该操作仅作用于当前文件，不触发全局扫描。
设置 Git 提交前自动校验
第一步：在项目根目录执行 npm install -D husky 安装 Husky。
第二步：运行 npx husky add .husky/pre-commit "copilot sync --verify-only" 创建预提交钩子。
第三步：编辑刚生成的 .husky/pre-commit 文件，在末尾添加 exit $? 保证校验失败时阻断提交。
这一步的关键在于 --verify-only 参数：它只比对代码与文档当前状态是否一致，不修改任何文件。若发现差异，命令返回非零退出码，Husky 会立即终止提交流程。
注意：此钩子不会检查未被 sync-rules.yml 覆盖的文件，也不会验证文档中手工添加的非同步内容。
响应 AI 生成的代码变更
当使用 copilot fix 或 copilot generate 修改了某个 sources 中声明的文件后，CLI 会自动在操作结束时弹出提示：“Detected code change in src/utils/date.ts — run ‘copilot sync’ to update API.md?”。
此时直接按回车即可触发同步，无需重新输入完整命令。
如果在弹出提示后关闭终端，下次执行 copilot status 会列出所有待同步的文件及其关联文档，状态显示为 out-of-sync。
