同步 Agent 体系

目标是让 Agent 规则和路由准确指向当前仓库,不在 Agent 文件复制产品知识。 代码定义实现事实,doc/00–15 定义产品与架构语义;Agent 文件只维护 强制规则、工作流程、目录职责和渐进式披露入口。

1. 授权与边界

• 用户只要求检查、分析或报告时保持只读,不得修改或生成报告文件。
• 用户明确要求"同步"、"更新"或"修复"时,只修改 AGENTS.md、 AI-POLICY.md、.github/copilot-instructions.md、.agents/** 及 直接负责 Agent 校验的 CI/工具文件。
• 不修改产品代码、公开 API、doc/、README、测试或构建配置来迁就 Agent 描述;发现这些事实侧本身冲突时报告并交给对应任务。
• 公开 API、功能入口或文档结构变化必须同批使用 /sync-review;本 skill 只处理其 Agent 派生面,不得替代产品同步审计。
• 未经维护者明确命令不得升级版本,也不得提交、push、创建 PR、安装 skill、构建、运行测试或执行无关项目脚本。
• 保留维护者和其他 Agent 的工作树改动;写前重读目标文件、git status 和最新 diff,不得覆盖、回退、stash 或清理。

2. 建立事实基线

先读根 AGENTS.md、AI-POLICY.md、.agents/README.md、 REPO-REFERENCE.md、FEATURE-INDEX.md 与 .github/copilot-instructions.md,再从当前仓库反向验证:

• 顶层目录、include/vlink/、src/、modules/、cli/、绑定、示例 和测试的实际职责。
• doc/00–15 的现有文件、小节号、标题和功能归属。
• CMakeLists.txt、cmake/、tools/、.github/workflows/ 与 .github/scripts/ 的真实入口、选项和触发关系。
• .agents/skills/*/SKILL.md、agents/openai.yaml、引用文件及 .agents/README.md 的完整 skill 集合。
• 当前分支、HEAD、暂存区、工作树和未跟踪文件;增量任务还要检查指定 base 到 HEAD 的变化。

代码签名、目录和控制流以代码为事实;产品定位、能力边界和架构意图以 doc/ 为事实。两者冲突时不得擅自选择一侧,应报告待确认项。

3. 同步各派生面

3.1 根规则

AGENTS.md 只保留跨任务、稳定且不可协商的强制规则与路由指向。新增 规则必须有真实重复风险或维护者明确要求,不得塞入模块清单、API 说明、 命令示例或临时实现细节。检查编号、引用和分册职责是否连续一致。

3.2 路由与索引

• .agents/README.md:任务到分册的路由、分册清单、skill 清单和安装 说明与实际文件一致。
• REPO-REFERENCE.md:目录职责、文档章节、工程设施和相关仓库仍存在且 语义准确,不复制专题文档内容。
• FEATURE-INDEX.md:每个功能的代码入口和 doc/ 小节真实存在;新增、 删除、改名或拆分功能后同步入口,但不在索引解释完整机制。

3.3 规则分册

语言、测试、文档、CI/PR 和 AI 政策只记录仓库特有约束。规则变更需核对 上位边界与引用方,避免在 AGENTS.md、分册和 skill 中重复维护或互相 冲突。无代码证据或维护者决策时不得把个人偏好写成强制规则。 .github/copilot-instructions.md 只保留指向根规则、当前任务分册和 GitHub 原生智能体边界的最小入口,不得复制产品知识或整套 Agent 规则。

3.4 Skills

对每个 .agents/skills/<name>/ 检查:

• 目录名、frontmatter name 和触发型 description 一致。
• SKILL.md 的授权边界、工具命令、引用路径和实际工作流有效。
• agents/openai.yaml 的 display_name、short_description 与 default_prompt 匹配 skill,且 prompt 明确包含 $<name>。
• .agents/README.md 有且仅有一条对应入口;新增 skill 不附带无用的 README、模板或资源目录。
• 公开写入、发布、Issue、Discussion、PR、Release 和 CI dispatch 均有 明确授权与回读步骤,不得伪装身份、扩大权限或隐藏未执行验证。

3.5 Agent CI

.github/workflows/ci-agent-skills.yml 与校验脚本应覆盖 AGENTS.md、 AI-POLICY.md、.github/copilot-instructions.md、.agents/**、skill 安装入口、Issue/Discussion 回复授权契约及自身变化,权限保持 contents: read。 只校验结构、元数据、路由、关键授权/回读契约和占位符,不得自动发帖、 创建 Issue/Discussion、修改仓库设置或安装网络依赖。

4. 最小修改

先列出事实侧与过时派生面,再按依赖顺序修改:根规则 → 分册 → 路由/索引 → skill → CI 说明。只修当前证据支持的差异,不借同步任务重写整套规则、 重排无关内容或统一个人偏好。路径、标题和小节变化必须同时修复直接引用。

5. 验证

在用户授权范围内执行只读或 Agent 专用校验:

bash -n tools/install_skills.sh
bash -n .github/scripts/test-validate-agent-skills.sh
bash -n .github/scripts/validate-agent-skills.sh
PYTHONPYCACHEPREFIX="$PWD/build-ai/sync-agent/__pycache__" \
    bash .github/scripts/test-validate-agent-skills.sh
PYTHONPYCACHEPREFIX="$PWD/build-ai/sync-agent/__pycache__" \
    bash .github/scripts/validate-agent-skills.sh
git diff --check

新增或修改 skill 时,再用 skill-creator 的 quick_validate.py 校验目标 目录,并为该 Python 调用设置同一任务专属 PYTHONPYCACHEPREFIX;修改 workflow 时优先运行已安装的 actionlint,缺失时不得擅自安装,改用现有 YAML 解析器检查语法并如实报告未执行项。

最终逐文件回读 diff,说明同步依据、修改范围、无需变化的派生面、未执行 验证和仍待维护者确认的冲突。确认没有修改版本、产品行为或外部状态。