---
name: docs-sync
description: 当任务修改了代码、协议、配置、UI、IPC、测试矩阵或运行方式时，执行文档同步与规则回写。适用于代码已完成、准备收尾，或复杂任务阶段结束时。不要用于纯分析且不改文件的任务。
---

# docs-sync

## 目标

在代码实现完成后，检查本次改动是否需要同步更新：

- `docs/` 下技术方案、执行清单、进度或说明文档
- `ltfp/docs/` 下测试矩阵、发布回滚说明
- 仓库根或模块级 `AGENTS.md` / `AGENTS.override.md`

## 触发条件

当满足以下任一条件时应执行本技能：

- 修改了协议、状态机、编解码、transport、协商、回退、兼容性逻辑
- 修改了 Agent / Bridge / Tauri 的交互行为
- 修改了配置项、默认值、构建发布行为
- 修改了管理台 UI、状态流、接口契约
- 修改暴露出新的长期规则、边界、验证要求或高风险注意事项

## 输入

执行本技能前，先明确以下信息：

1. 本次改动涉及哪些目录
2. 本次改动是否改变行为语义
3. 本次改动是否形成新的长期规则
4. 本次改动已做哪些验证
5. 本次改动有哪些未覆盖项

## 执行步骤

### 第一步：识别同步目标
根据改动目录，判断需要同步哪些文档：

- `ltfp/`：
  - `ltfp/docs/TestMatrix.md`
  - `ltfp/docs/ReleaseAndRollback.md`
  - 仓库根 `docs/` 下相关协议文档

- `agent-core/`：
  - Agent 生命周期、探测、事件、连接模型相关文档

- `cloud-bridge/`：
  - Bridge 技术方案、认证、SSE、管理后台、配置文档

- `apps/dev-agent/`：
  - Tauri 本地通信、UI 交互、连接模型文档

### 第二步：判断是否需要规则回写
若本次任务形成新的长期规则，则更新对应目录的：

- `AGENTS.md`
- `AGENTS.override.md`

长期规则包括：

- 新的高风险检查项
- 新的目录边界要求
- 新的默认验证步骤
- 新的禁止项
- 新的文档同步映射关系

### 第三步：回写内容
回写文档时，至少补充以下内容：

1. 本次改动的目标
2. 影响范围
3. 核心实现变化
4. 风险与兼容性影响
5. 已执行验证
6. 未覆盖验证
7. 后续建议或待办

### 第四步：避免无效回写
不要做以下事情：

- 只改标题不补实质内容
- 把文档写成空泛总结
- 没有新增长期规则却机械修改 `AGENTS.md`
- 明明无需同步，却为了“看起来完整”硬改文档

## 输出要求

完成后，在结果总结中明确列出：

- 本次更新了哪些文档
- 本次更新了哪些 `AGENTS.md` / `AGENTS.override.md`
- 哪些文档判断为无需更新，以及理由