关于 synapse-docs
synapse-docs 是一项让 Synapse A2A 文档与代码变更保持同步的技能，面向维护该项目代码、配置和技能的开发者。它根据变更映射提出最小文档更新，并检查相关文件之间的一致性。
主要功能
- 01按代码变更定位受影响文档
- 02提出经用户批准的最小修改
- 03同步插件技能文件
- 04核对命令、API 和配置说明
适用场景
- 01更新 CLI 命令后同步使用指南
- 02修改配置项后核对设置文档
- 03变更插件技能后同步分发文件
- 04检查版本或功能更新涉及的文档
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/synapse-docs确认已加载。
附带文件references/code-doc-mapping.mdreferences/doc-inventory.md
详细介绍
Synapse 文档
此技能可确保 Synapse A2A 文档与代码更改保持同步。
此技能的触发时机
自动触发条件
- 核心模块中的代码更改 -
synapse/*.py、synapse/commands/*.py - 配置档案更改 -
synapse/profiles/*.yaml - 模板更改 -
synapse/templates/.synapse/* - 插件/技能更改 -
plugins/synapse-a2a/**/* - 配置更改 -
pyproject.toml（版本、依赖项、入口点）
手动调用
/synapse-docs- 运行完整的文档检查与更新
工作流
阶段 1：检测更改
修改代码时，请参阅 references/code-doc-mapping.md，确定受影响的文档。
快速参考 - 常见模式：
| 更改类型 | 主要文档 | 次要文档 |
|---|---|---|
| CLI 命令 | README.md、guides/usage.md | guides/references.md、CLAUDE.md |
| API 端点 | README.md、guides/references.md | guides/enterprise.md |
| 环境变量 | README.md、guides/settings.md | templates/.synapse/settings.json |
| 配置档案设置 | guides/profiles.md | CLAUDE.md |
| 技能内容 | plugins/*/SKILL.md | .claude/skills/、.agents/skills/（编辑 plugins/synapse-a2a/skills/，再通过 sync 分发） |
阶段 2：提出更新方案
对于每份受影响的文档：
- 阅读当前内容
- 找出需要更新的具体部分
- 提出必要的最小改动
- 将改动提交给用户审批
更新原则：
- 保持现有文档的风格和语气
- 仅更新受影响的部分
- 保持 README.md 简洁；详细内容放在 guides/ 中
- 确保相关文档之间保持一致
阶段 3：同步相关文件
更新主要文档后，检查是否需要同步：
技能同步：
plugins/synapse-a2a/skills/ → .claude/skills/
plugins/synapse-a2a/skills/ → .agents/skills/
模板一致性：
synapse/templates/.synapse/ should match documentation in guides/settings.md
阶段 4：验证一致性
运行一致性检查：
- CLI 命令 - 比较
README.md↔guides/usage.md↔guides/references.md - API 端点 - 比较
README.md↔guides/references.md - 端口范围 - 比较
README.md↔guides/multi-agent-setup.md↔CLAUDE.md - 环境变量 - 比较
README.md↔guides/settings.md↔templates/settings.json
文档类别
面向用户（高优先级）
| 文档 | 用途 | 更新频率 |
|---|---|---|
README.md | 第一印象、快速入门 | 每次功能更改时 |
guides/usage.md | 使用方法 | CLI/API 更改时 |
guides/settings.md | 配置参考 | 设置更改时 |
guides/troubleshooting.md | 问题解决 | 发现新问题时 |
面向开发者
| 文档 | 用途 | 更新频率 |
|---|---|---|
CLAUDE.md | Claude Code 开发指南 | 架构/测试更改时 |
guides/architecture.md | 内部设计 | 组件更改时 |
docs/*.md | 技术规格 | 设计更改时 |
插件/技能
| 文档 | 用途 | 更新频率 |
|---|---|---|
plugins/synapse-a2a/README.md | 插件安装 | 插件更改时 |
plugins/*/skills/*/SKILL.md | 技能说明 | 功能更改时 |
参考文件
如需查看详细的文档清单和代码到文档的映射，请参阅：
references/doc-inventory.md- 所有文档及其作用的完整列表references/code-doc-mapping.md- 源文件与文档之间的对应关系
特殊情况
版本更新
当 pyproject.toml 中的版本发生更改时：
- 在
CHANGELOG.md中添加发布说明 - 检查是否需要更新
README.md测试徽章 - 根据需要更新
plugins/synapse-a2a/.claude-plugin/plugin.json中的版本
新功能添加
对于重大新功能：
- 添加到
README.md功能表 - 在
guides/中创建或更新相关指南 - 如果影响开发工作流，则更新
CLAUDE.md - 如果创建了新指南，则将其添加到
guides/README.md导航中
弃用
弃用功能时：
- 在相关文档中标记为已弃用
- 如有需要，添加迁移指南
- 更新
CHANGELOG.md - 从
README.md快速入门示例中移除
评论
支持 Markdown