03 — Agent 多工具集成与格式转换

Agent 多工具集成与格式转换

学习目标

本章将分析 Agency-Agents 如何支持 11 种 AI 编码工具。阅读本章后你将能够：

• 理解统一源格式到 11 种工具格式的转换映射
• 分析 Bash 转换管道的设计决策
• 评估多工具支持 vs 单一工具绑定的取舍

前置知识

本章涉及工具调用和格式转换的通用原理，建议先阅读：

• 工具调用协议与执行模型
• Agent 定义的多工具格式转换

下文假设你已理解上述概念，直接聚焦 Agency-Agents 的具体实现。

---

项目实践

11 款支持工具一览

Agency-Agents 通过 scripts/convert.sh 和 scripts/install.sh 两个脚本支持 11 种工具：

#	工具	集成方式	安装位置
1	Claude Code	原生 .md	~/.claude/agents/
2	GitHub Copilot	原生 .md	~/.github/agents/ + ~/.copilot/agents/
3	Antigravity	SKILL.md	~/.gemini/antigravity/skills/
4	Gemini CLI	SKILL.md + extension	~/.gemini/extensions/agency-agents/
5	OpenCode	项目级 .md	.opencode/agents/
6	OpenClaw	三分解 workspace	~/.openclaw/agency-agents/
7	Cursor	.mdc 规则	.cursor/rules/
8	Aider	CONVENTIONS.md	项目根目录
9	Windsurf	.windsurfrules	项目根目录
10	Qwen Code	SubAgent .md	.qwen/agents/
11	Kimi Code	YAML + prompt	~/.config/kimi/agents/

转换管道架构

install.sh 的自动检测策略

install.sh 对每种工具使用两层检测：

# 第一层：CLI 命令是否存在
detect_opencode() { command -v opencode >/dev/null 2>&1; }

# 第二层：配置目录是否存在
detect_claude_code() { [[ -d "${HOME}/.claude" ]]; }

为什么两层检测？ 有些工具可能已安装但未在 PATH 中（目录检测），有些工具在 PATH 中但用户尚未配置（命令检测）。两者结合提高检测准确率。

交互模式与并行安装

# 交互式选择（终端运行时默认）
./scripts/install.sh

# 非交互模式（CI/管道）
./scripts/install.sh --no-interactive

# 并行安装所有检测到的工具
./scripts/install.sh --parallel

交互模式下，install.sh 展示带进度条的多选界面，用户可以用空格选择/取消、回车确认。

OpenClaw 三分解模式

OpenClaw 是唯一使用三分解格式的工具——每个 Agent 被拆为三个文件：

文件	内容来源	目的
SOUL.md	Identity + Vibe	Agent 的身份和核心驱动力
AGENTS.md	Mission + Rules + Workflow	Agent 的行为能力和流程
IDENTITY.md	Experience + Memory	Agent 的经验背景和记忆模式

为什么三分解？ OpenClaw 的 workspace 设计将 Agent 的”灵魂”（人格）、“行为”（能力）和”身份”（经验）分离，使 LLM 在不同上下文中加载不同部分，优化 Token 使用。

---

问题与规避

合并型工具的上下文超限

问题：Aider 的 CONVENTIONS.md 和 Windsurf 的 .windsurfrules 将所有 160+ Agent 合并为单个文件，可能超过 800KB。

规避：这两个工具的设计本身就是读取单一大文件。用户需要在工具配置中设置更大的上下文窗口，或只复制需要的类别部分。

转换脚本的维护负担

问题：11 个转换器意味着当源格式变化时，需要确认 11 个转换器都正确适配。

规避：

• 所有转换器使用相同的 get_field / get_body 提取函数
• lint-agents.sh 在 CI 中校验所有 Agent 文件的 frontmatter 完整性
• 新增工具时只需添加一个新的 convert_{toolname} 函数

---

设计取舍

为什么选择 Bash？

考量	Bash	Python	Node.js
运行时依赖	✅ 无（系统自带）	❌ 需要 Python	❌ 需要 Node.js
YAML 处理	❌ 需要 awk	✅ PyYAML	✅ js-yaml
并发处理	⚠️ xargs -P	✅ asyncio	✅ Promise.all
平台兼容	✅ Linux/macOS/WSL	✅ 跨平台	✅ 跨平台

决策：零依赖 > 便利性。Bash 确保了任何用户克隆仓库后无需安装额外依赖即可运行。

统一转换 vs 工具原生

方案	优势	代价
统一转换	一份源文件，维护成本低	转换脚本可能落后于工具更新
工具原生	始终兼容工具最新版本	N 份源文件，维护成本高

Agency-Agents 对 Claude Code 和 Copilot 使用工具原生（直接复制 .md），对其他工具使用转换。这是一种渐进式策略——对原生兼容的工具零转换，对其他工具按需转换。

---

参考来源

• Agency-Agents Repository, commit 783f6a7
• scripts/convert.sh — 18,283 行格式转换脚本
• scripts/install.sh — 23,880 行安装脚本
• Agent 定义的多工具格式转换