Agentstow：把一份配置分发到十款 AI 编码代理

随着 Claude Code、Codex、Cursor、Windsurf 等 AI 编码代理不断涌现，开发者的本机配置开始变得碎片化：每个工具都有自己的 skills 目录、MCP 配置、指令文件和 hooks 规则，改一处就要同步多处。Agentstow 试图用一个统一的 Store 目录终结这种重复。

一份「真源」，分发到所有代理

Agentstow 的核心思想是「文件系统即状态」。它在 ~/.agents/ 下建立唯一存储目录，存放所有共享配置——包括 skills、slash commands、subagents、AGENTS.md 指令、MCP 服务器配置以及 hooks 脚本。

随后通过 agentstow sync 命令，把这些配置分发到用户本机已安装的十款代理目录中：能字节相同的地方用软链接，无法相同的地方则用键合并（key-merge）方式渲染。工具本身不维护任何状态文件，因为所有权信息全部可以从磁盘上读取。

例如，在 Store 中新增一个 research skill 后，~/.claude/skills/、~/.codex/skills/、~/.codex/skills/ 等位置都会出现指向同一文件的相对软链接，目录结构即便被移动或恢复也能保持一致。

两种同步机制：软链接与键合并

• 软链接：skills、指令、commands、subagents 等可以保持字节一致的配置，Agentstow 直接建立符号链接，「漂移」在结构上就不可能发生。
• 键合并：MCP 服务器和 hooks 嵌入在各代理自有文件中，且各工具格式互不兼容，因此采用渲染并键合并的方式。Store 中命名的条目会被覆盖写入，其它键（如 model、trust_level）保持原样不动。

对 opencode 和 oh-my-pi 这类已经原生读取 ~/.agents/ 的代理，Agentstow 不写入任何内容，避免重复。对于指向外部或断链的软链接，工具会按规则清理或保留为「Foreign」标记。

覆盖十款代理、六大配置族

根据官方支持矩阵，Agentstow 当前覆盖 Claude Code、Codex、opencode、pi、oh-my-pi、Gemini CLI、Cursor、Windsurf、Roo、Cline 等十款代理，分别处理 Agent Skills、Instructions、MCP、Commands、Subagents、Hooks 六大配置族。每个代理用最合适的方式接入：原生读取就跳过，能软链就软链，否则键合并。

通过 agentstow status 命令可以查看每个代理下的链接状态，区分「managed」「variant-identical」「foreign」等类型，并提示用户哪些项目需要处理。

安全性与边界

工具内置多重安全设计：

• 干跑模式（--dry-run）可在不修改磁盘的情况下预览所有改动。
• 每次写入采用临时文件 + fsync + 原子重命名，确保点文件结构稳定。
• ${env:VAR} 在同步时解析并在输出中脱敏，Store 内容可安全提交至版本控制。
• 提供 --json 输出和 CI 友好的退出码（0 干净、1 错误、2 有待处理），便于接入自动化流程。

需要明确的是，Agentstow 不做跨机器同步（建议用 git 或 chezmoi 管理 Store），也不做代理记忆同步——这两类问题需要更通用的冲突解决能力，作者将其留给既有生态处理。

安装与上手

Agentstow 提供 macOS 与 Linux 预编译二进制，可通过 npm install -g agentstow 安装，也可从源码编译（需 Rust 1.97+）。首次执行 agentstow init 会创建 Store 并扫描现有配置，提示哪些家族的哪些内容可以被接管。对于已经在多款 AI 编码代理之间疲于同步配置的开发者来说，这是一套定位明确的轻量级解决方案。