agent-sync

name	agent-sync
description	管理 DicePP agent 配置同步、环境识别、首次接管、后续同步、工作目录检查、rules/skills 投影与平台差异处理。需要调整或排查 .codex、.claude 中的 agent rules、skills、Claude Linux settings/hooks，新增、移动、重命名、删除 agent skill/rule，检查环境是否暴露了错误技能，或汇报当前 agent 配置状态时使用。

Agent Sync

使用本技能处理 DicePP agent 配置的同步、接管、检查和汇报。

核心原则

• 先读取并遵循 docs/agent/sync.py 的 help 输出；具体命令、参数和配置格式以脚本为准。
• 以 docs/agent 为项目 agent 配置源目录，.codex 和 .claude 是同步后的工作目录。
• 不在本技能中复制具体命令或参数细节。
• 同步前先判断当前是首次接管、后续同步、环境切换还是故障排查。

场景判定

首次接管

适用于目标目录没有同步状态、存在旧链接脚本遗留、旧 docs/agent/skills 链接、手工创建的 skill，或无法确定 .codex / .claude 当前来源的情况。

处理重点：

• 读取 help 并检查当前本地环境配置。
• 汇报目标目录现状，包括规则文件、技能目录、旧链接、断链、未知内容和本地忽略项。
• 区分项目将同步的 skill、可能的开发者本地 skill、旧同步遗留和未知内容。
• 执行会改动目标目录的同步前，先向用户说明会写入哪些 rules、会同步哪些 skills、哪些目标目录内容不会被同步工具处理，以及是否会替换旧链接。
• 生产环境首次接管时，特别确认目标环境是 prod，且不会暴露开发专用 skills。

后续同步

适用于目标目录已有同步状态，只需要刷新 rules、同步新增或删除的 skill、或确认环境没有漂移的情况。

处理重点：

• 检查当前环境和同步状态是否一致。
• 同步 skills-common 与当前 skills-<env> 中的新增、移动、删除。
• 对 stale managed、broken managed 这类已同步项，可按脚本建议修复。
• 对 unknown 内容不要擅自删除；先判断是否是开发者本地 skill、历史遗留或错误暴露，必要时让用户决定是否加入本地 ignore 或迁回 docs/agent。
• 同步后再次检查并汇报结果。

环境切换

适用于开发/生产目录切换、.agent-env.json 变更，或显式指定 env 的情况。

处理重点：

• 确认当前目标环境和用户意图一致。
• 检查 prod 环境只暴露 common + prod skills，dev 环境暴露 common + dev skills。
• 若发现 prod 目标目录仍有 dev 同步 skills，先汇报风险，再按脚本能力清理。

故障排查

适用于 skill 未加载、规则未更新、链接断裂、同步状态异常、目标目录内容和 docs/agent 不一致的情况。

处理重点：

• 先收集 report/doctor 结果，再定位具体问题。
• 区分脚本可自动修复的问题和需要用户判断的问题。
• 修复后再次检查，并说明剩余风险。

汇报格式

最终向用户汇报时，使用以下结构；没有的项写“无”或省略该小节，不要把原始命令输出整段贴回。

环境：
- 当前 env：
- 目标：
- peer 路径：

已同步：
- rules：
- skills：

未同步但保留：
- 目标目录内容：
- 匹配的忽略规则：

发现的问题：
- 过期的已同步项：
- 断开的链接：
- 未知内容：
- 环境不一致：
- 其他：

本次处理：
- 写入/刷新：
- 新增/删除/替换：
- 未处理：

验证：
- doctor：
- 其他验证：

后续建议：
- ...

安全边界

• 首次接管或发现 unknown 内容时，不要直接清理；先向用户说明它们可能是个人 skill、旧工具遗留或错误暴露。
• “未同步但保留”表示目标目录中存在本次同步不处理的内容，通常是 .agent-env.json 中 ignore 规则匹配的个人/本地专用 skill；未匹配 ignore 的未知内容应作为问题汇报。
• 生产环境同步前，确认目标 env 为 prod，并确认暴露技能集合符合生产边界。
• 不把 .codex 或 .claude 中的临时内容当成项目事实来源；需要纳入项目时，应迁回 docs/agent 下对应目录。