第15部分：智能体的可替换性
智能体的可替换性是指能够由另一个智能体或在另一个IDE中继续推进流程，而不会丢失项目记忆。在SDD中，这是一个自然的目标：如果意图记录在Markdown文件中，流程被规范为技能和命令，那么具体的智能体就成为可替换的执行环境。
今天你使用Qwen Code CLI。明天团队的一部分可能使用Codex、Claude Code、Gemini CLI、Cursor、Kiro或GitHub Spec Kit。依赖单一工具界面做出的决策越少，流程就越稳健。
什么应该独立于智能体
README.md
QWEN.md / AGENTS.md
specs/
mission.md
tech-stack.md
roadmap.md
YYYY-MM-DD-feature/
requirements.md
plan.md
validation.md
CHANGELOG.md
tests/
package.json 脚本如果这些文件清晰易懂，另一个智能体就能继续工作。
QWEN.md 和 AGENTS.md
Qwen Code 使用 QWEN.md，但也能读取 AGENTS.md。如果你想要可移植性，就将 AGENTS.md 作为通用契约，让 QWEN.md 成为一个轻量级的指向文件。
AGENTS.md:
# 智能体指令
本仓库使用SDD。
- 没有功能规格说明，不要实现产品功能。
- 规划前请先阅读 specs/mission.md、specs/tech-stack.md 和 specs/roadmap.md。
- 每个功能分支必须包含 specs/YYYY-MM-DD-feature-name/。
- 将修改限制在活跃规格说明的范围内。
- 合并前运行 npm test 和 npm run typecheck。
- 不要在仓库中存储密钥。QWEN.md:
请先阅读 @AGENTS.md。
Qwen Code 注意事项：
- 在规划、实现和检查之间使用 /clear。
- 通过 @file 引用规格说明。
- 使用 ! 命令进行本地验证。技能的可移植性
Qwen Code 的技能使用 SKILL.md。这种格式类似于智能体技能的通用约定：Markdown 指令加上可选的脚本和模板。即使另一个智能体在其他地方存储技能，内容也是可以迁移的。
迁移时：
.qwen/skills/feature-spec/SKILL.md可以复制到另一个智能体的技能目录中，只需调整工具相关的细节。流程的本质保持不变：在路线图找到阶段，询问边界、决策和上下文，创建 requirements.md、plan.md 和 validation.md。
MCP 作为外部工具层
MCP 允许连接外部工具和数据源。在 Qwen Code 中，MCP 通过 settings.json 或 qwen mcp add 进行配置。
通过 stdio 的本地 MCP 示例：
{
"mcpServers": {
"projectTools": {
"command": "node",
"args": ["./tools/mcp-server.js"],
"timeout": 15000
}
}
}命令示例：
qwen mcp add --transport http docs http://localhost:3000/mcp
qwen mcp安全规则：不要"以防万一"地连接MCP。每个工具都会扩大智能体的行动面。
ACP 和 IDE
Agent Client Protocol（ACP）用于让智能体和客户端/IDE能够标准地交互。Qwen Code 支持通过 ACP 模式与 JetBrains 配合工作：
{
"agent_servers": {
"qwen": {
"command": "/path/to/qwen",
"args": ["--acp"],
"env": {}
}
}
}即使你使用CLI，理解这个方向也很有用：流程应该存在于仓库中，而界面应该是可替换的。
历史注记：2026年初，JetBrains 2025.3+ 迁移到了 ACP v2（prompt.turn），而 Qwen Code 一度只支持 v1，导致集成中断（issue QwenLM/qwen-code#1502）。兼容性在2026年通过 PR #1521 恢复。如果与 JetBrains 的集成突然失效，首先要检查的是 Qwen Code 版本和 IDE 版本：它们必须使用相同版本的 ACP。
GitHub Spec Kit 作为外部 SDD 框架
GitHub Spec Kit 提供了一个更正式的流程：描述意图、规划、拆分为任务、实现。它不绑定特定智能体，可以与各种写代码的智能体配合工作。你不一定非要在 AgentClinic 中采用它，但了解你的手动的SDD循环与这个通用方向一致是有价值的：
意图 → 规格说明 → 计划 → 任务 → 实现 → 验证如果团队想要更多标准化，可以将你的 .qwen/skills/feature-spec 与 Spec Kit 进行比较，决定是否需要一个单独的框架。
可替换性验证
进行一个实验：
/clear
假设你是一个没有聊天历史的新智能体。
阅读 @AGENTS.md、@QWEN.md、@specs/mission.md、@specs/tech-stack.md 和 @specs/roadmap.md。
告诉我，项目中下一步安全的行动是什么。
不要修改文件。如果回答正确，说明项目记忆是有效的。
实践
- 创建
AGENTS.md。 - 让
QWEN.md成为仅针对 Qwen Code 的简短文件。 - 检查功能规格技能是否包含绑定到 Qwen Code 的多余细节。
- 只为真正需要的工具描述 MCP。
- 运行"新智能体"验证。
检查问题
- 哪些工件使流程可移植？
- 为什么技能最好不要绑定到单一界面？
- MCP 什么时候有用，什么时候只会增加风险？