企业官网建设流程全解析

dotagents 是一款开源的 AI 工具配置管理工具，通过交互式 CLI 一键链接 Claude、Codex、Cursor 等 6 款 AI 编程工具。它把你分散在各家工具目录里的 hooks、commands、skills 和 AGENT/CLAUDE.md 规则文件统一收进一个.agents目录，再用符号链接自动同步给各工具——只写一次，处处生效。🚀

为什么需要 dotagents：告别六份重复配置

用过 Claude Code 的人都知道，配置文件散落在~/.claude/；Codex 用~/.codex/；Cursor 用~/.cursor/；Gemini 用~/.gemini/……想给多个 AI 工具共享同一套自定义命令和技能，只能手动复制多份，改一处、漏改五处是常事。

dotagents 的思路很简单：

• 单一数据源：.agents目录作为唯一可信来源（source of truth）
• 符号链接分发：为 Claude、Codex、Factory、Cursor、OpenCode、Gemini 自动建立 symlink
• 安全可回滚：任何覆盖操作前自动备份，随时可以 Undo

核心逻辑集中在 src/core/ 模块，入口交互在 cli.tsx。

一键启动：两条命令开始配置

dotagents 对新手非常友好，无需手动 clone 代码，直接通过包管理器运行引导式 CLI：

npx @iannuttall/dotagents

如果你使用 Bun 运行时（要求 Bun 1.3+），也可以：

bunx @iannuttall/dotagents

运行后进入彩色终端界面，全程只需选择 + 回车，不用背任何参数。

交互式流程：从工作区到链接完成只需 4 步

第 1 步：选择工作区（Global 或 Project）

CLI 首先让你选择作用范围：

路径解析逻辑在 paths.ts 中实现，Global 范围会读取~/.claude、~/.codex等用户目录，Project 范围则操作项目内的.claude、.codex等文件夹。

第 2 步：勾选要管理的客户端

多选界面默认全选 6 款主流工具：

Claude、Factory、Codex、Cursor、OpenCode、Gemini

还可以按需加入 GitHub Copilot、Ampcode 等。只勾选你实际在用的工具，dotagents 就只会为这些工具建立链接。

第 3 步：查看状态概览（Overview）

进入主菜单后，界面会显示一张状态表：每类资源（AGENTS.md、commands、hooks、skills）各自有多少已链接（Linked）、待链接（Need link）、冲突（Conflicts）。状态扫描由 status.ts 完成，链接计划由 plan.ts 生成。

第 4 步：应用变更（Apply changes）

选择 Apply 后，dotagents 会先打印一份Plan summary：迁移多少项、创建多少链接、冲突多少处、备份目录在哪，确认无误才动手。目标路径映射规则定义在 mappings.ts。

它到底链接了什么？

以全局范围为例，典型映射关系如下（来源 → 目标）：

• .agents/CLAUDE.md→~/.claude/CLAUDE.md
• .agents/AGENTS.md→~/.codex/AGENTS.md、~/.factory/AGENTS.md、~/.config/opencode/AGENTS.md
• .agents/commands→ 各工具的 commands/prompts 目录
• .agents/hooks→~/.claude/hooks、~/.factory/hooks
• .agents/skills→ Claude、Codex、Cursor、OpenCode、Gemini 的 skills 目录

几个值得知道的细节：

• Claude 优先使用CLAUDE.md，不存在时回退到AGENTS.md
• Codex 的 prompts 始终链接到.agents/commands
• skills 目录需要包含带name+descriptionfrontmatter 的SKILL.md，校验逻辑见 skills.ts
• Project 范围只链接 commands/hooks/skills，规则文件留给仓库根目录自行管理

内置迁移：老配置自动归位

如果你之前已经手动在各工具目录里建过文件，dotagents 会先扫描现有配置（migrate.ts），能自动迁移的直接复制进.agents；遇到"两个地方都有内容"的冲突，则弹出选择框让你决定以哪份为准，全程不会静默丢数据。

安全兜底：自动备份 + 一键撤销

这是 dotagents 让人敢随便跑的设计亮点：

1. 覆盖前必备份——被覆盖的文件/目录/符号链接会原样存入.agents/backup/<时间戳>/，并写入 manifest.json 清单（backup.ts）
2. 预检不通过不执行——preflight.ts 在真正动手前校验备份完整性
3. Undo last change——主菜单随时可选，自动还原最近一次备份、清理新建的链接（undo.ts）

所以"链接搞错了"这件事的代价只是按两下回车。

日常使用小技巧 💡

• 修复断链：重跑 dotagents，状态表里标黄/标红的项选 Apply 即可自动修复
• 新增工具：主菜单选 Change clients 重新勾选，再 Apply
• 只想看不动手：选 View status 查看只读详情，随时 Exit 退出
• 可重入：任何时候重新运行都安全，链接是幂等的

相关行为都有测试覆盖，可参考 linking.test.ts、migrate.test.ts、undo.test.ts。

项目结构速览

总结

dotagents 用一条命令 + 一个交互式 CLI，就把"多 AI 工具配置同步"这件烦心事变成了选选项的操作：统一.agents目录、符号链接分发、自动备份、一键撤销。如果你同时在用 Claude、Codex、Cursor 等工具，强烈建议花两分钟跑一次npx @iannuttall/dotagents，从此一份配置，处处生效。✅