AGENTS.md 同步器VictorTomaili/agent-cli

agent-cli

一个 AGENTS.md。所有 AI 编码工具。始终保持同步。

npm version
CI
node
license

快速开始 · 让你的 agent 安装它 · 支持的工具 · MCP 服务器 · dev-team · 贡献指南

问题所在

每个 AI 编码工具都想要自己的指令文件，放在自己的位置，用自己的名字：

~/.claude/CLAUDE.md          ~/.codex/AGENTS.md         ~/.gemini/GEMINI.md
~/.dsh/AGENTS.md             ~/.qwen/QWEN.md            ~/.pi/agent/AGENTS.md
.cursor/rules/.mdc          .windsurf/rules/.md       .clinerules/.md
.github/copilot-instructions.md          .junie/guidelines.md         …

手动保持它们同步，一周之内就会产生偏差。在一个文件里改了审查标准，忘了另外六个，你的 agent 们就会悄悄地互相矛盾。

核心理念

只写一个主文件。agent-cli 会在每个工具的原生配置位置写入一个小的指针存根，告诉该工具真正的文件在哪里。

~/AGENTS.md   ← 你唯一需要编辑的文件
│
┌────────────┬───┴───┬────────────┬─────────────┐
▼            ▼       ▼            ▼             ▼
~/.claude/    ~/.codex/  ~/.gemini/  .cursor/     …17 个工具
CLAUDE.md    AGENTS.md  GEMINI.md   rules/.mdc
└──────────── 指针存根，随时可重新生成 ────────────┘

你再也不用把同一段文字编辑两次。存根可以安全地重新生成——agent-cli 只会触碰它自己创建的文件，并且在覆盖之前会备份原生内容。

围绕这个主文件，它还管理一个大脑：身份和用户档案、模型别名、经验教训、子 agent 角色、委派交接、快照、一个 MCP 服务器，以及一个内置的技能管理器。

安装

npm install -g @victortomaili/agent-cli

Node.js ≥ 22（ESM）。安装全局 agent-cli 命令。

快速开始

agent-cli init      # 引导主文件，检测并链接已安装的工具，安装 hooks
agent-cli status    # 主文件状态 + 各目标的指针健康状况
agent-cli doctor    # 完整诊断（配置、指针、暂存更新、npm 新鲜度）
agent-cli edit      # 在 $EDITOR 中打开主文件

init 是幂等的，且从不提示——重新运行会修复任何缺失的内容，而不会触碰你已经编辑过的内容。它是唯一一个能把裸安装变成
可用的设置：它会为 master 播种，为每个检测到的工具写入指针存根，将 home 指针部署到 ~/AGENTS.md，安装 SessionStart 简要钩子，并设置捆绑的技能管理器。

让你的 agent 安装它

agent-cli 是为由 AI agent 驱动而构建的，因此你可以把整个设置交给一个 agent。
将下面的提示词复制到 Claude Code、Codex、Cursor、Gemini CLI 或任何具有 shell 访问权限的 agent 中——它会安装、配置、验证并回报，而你无需触碰任何东西。

在这台机器上为我端到端地安装并配置 agent-cli。它管理一个单一的
规范 AGENTS.md，并将其镜像到我已安装的每一个 AI 编码工具中。

执行以下操作：

1. 检查先决条件：node --version 必须 >= 22。如果更旧，请停止并告诉我。
2. 安装：npm install -g @victortomaili/agent-cli
3. 引导：agent-cli init
它是幂等的且从不提示，因此即使某些内容已存在也可以安全运行。
4. 阅读内置指南，以便你知道如何驱动它：agent-cli instructions
5. 验证：agent-cli doctor --json
退出码 2 表示发现问题，而非失败——读取 JSON 并修复它报告的内容。
重新运行 agent-cli init 以修复任何缺失的内容。
6. 向我展示 agent-cli status，并用通俗的语言告诉我：
- 我的哪些 AI 编码工具被检测到并已链接，
- 我的 master 文件现在位于何处，
- doctor 标记出的任何需要我决定的事项。

规则：
- 永远不要传递 --force——它会覆盖我现有的内容。
- 永远不要手动编辑指针存根；它们是生成的。
- 如果某个步骤失败，请向我展示实际错误，而不是绕过它。

然后运行 agent-cli prompt 并将其输出添加到你自己系统提示词中，以便你在本次会话的剩余时间里
始终了解我的设置。

提示： 设置完成后，agent-cli prompt 会为任何 agent 的系统提示词生成一个约 2 KB 的
状态感知块，而 agent-cli instructions 是完整的静态参考。两者都是为机器消费而编写的。

支持的工具

17 个目标，每个对应 src/targets/ 下的一个文件。agent-cli targets 会实时列出
它们及其安装和启用状态。

| 工具 | 全局 | 项目 |
| --- | --- | --- |
| Claude Code | ~/.claude/CLAUDE.md | CLAUDE.md |
| OpenAI Codex | ~/.codex/AGENTS.md | AGENTS.md |
| DeepSeek Harness | ~/.dsh/AGENTS.md | AGENTS.md |
| Gemini CLI / Code Assist / Antigravity | ~/.gemini/GEMINI.md | GEMINI.md |
| Qwen Code | ~/.qwen/QWEN.md | QWEN.md |
| pi coding agent | ~/.pi/agent/AGENTS.md | AGENTS.md |
| Cline / Roo Code | ~/.cline/rules/agent-cli.md | .clinerules/agent-cli.md |
| Cursor | — | .cursor/rules/agent-cli.mdc |
| Windsurf | — | .windsurf/rules/agent-cli.md |
| GitHub Copilot | — | .github/copilot-instructions.md |
| JetBrains Junie | — | .junie/guidelines.md |
| Trae | — | .trae/rules/agent-cli.md |
| Aider | — | CONVENTIONS.md |
| Zed AI | — | AGENTS.md |
| Warp | — | AGENTS.md |
| OpenCode | — | AGENTS.md |
| Goose (Block) | — | .goose/hints |

缺少你的工具？添加一个只需提交一个包含两个文件的拉取请求。

核心概念

- Master — 你编写的那一个文件：~/AGENTS.md（全局）或 .agents/AGENTS.md
（项目范围，位于仓库内）。
- Pointer stub — 由 agent-cli link 在工具的原生配置路径下生成的一个小文件。包含机器可读的元数据，以及一段人类可读的说明，用于将 agent 重定向到 master。可以安全地重新生成；只会触碰由 agent-cli 创建的文件。
- Target — agent-cli 知道如何指向的一个 AI 编码工具。agent-cli targets
会列出它们；agent-cli target enable  [--global|--project] 可以启用其中一个。
- 破坏前先备份 — 对已经包含你自己内容的目标执行
agent-cli link --target  --force 时，会先将其复制到 .agent-cli-backup-，并在 --json 信封的 backup 字段中显示该路径。

关键命令

| 领域 | 命令 |
|---|---|
| 指针同步 | link、unlink、status、target enable\|disable、where、pull |
| Master 内容 | edit、identity、soul、user、env、models、archetype |
| 子 agent 角色 | agents（list/show/new/edit/roster/delegate）、template install |
| 经验与记忆 | lessons、consolidate、memory、search |
| 大脑升级 | memory upgrade status\|plan\|prepare\|apply（LLM 驱动的 schema 迁移） |
| 大脑快照 | snapshot、restore、backups、sync（由 git 支持） |
| 会话生命周期 | session、day-start、session-start、brief、brief-hooks |
| 随附默认值更新 | update list\|stage\|diff\|apply\|clear、upgrade（--overwrite 会采用你修改过的文件的随附版本——但会先备份） |
| dev-team 插桩 | ledger start\|record\|end\|show\|clear、ledger --handoff 、team eval run\|report、retro record\|count\|mark |
| 技能 | skill setup\|refresh\|status\|list\|install\|enable\|disable |
| 诊断 | doctor、validate、config、stats、whoami、files、manifest、schema |
| 自动化 | hooks install（git hooks）、automation add\|list\|run、watch、serve（基于 stdio 的 MCP） |
| 外部 MCP 工具 | mcp servers\|enable\|disable\|tools\|call、mcp  --arg k=v |
| 供 LLM agent 使用 | instructions（静态指南）、prompt [--for ]（动态、感知状态） |

对其中任何命令都可以使用 agent-cli help ；使用 agent-cli --json manifest 获取完整的机器可读命令和退出码契约。

如果输入错误，它会建议最接近的匹配项——agent-cli statuz 会回复
Did you mean: agent-cli status, agent-cli stats?，因此 agent 可以自行纠正，而无需重新阅读 --help。

供驱动 CLI 的 LLM agent 使用

两个互补的命令——一个动态，一个静态：

- agent-cli prompt [--for ""] — 检查已安装工具、大脑状态和待处理操作，然后为系统提示词槽位生成一段量身定制的约 2 KB Markdown 块。
每个会话运行一次。 之后 agent 就知道哪些工具已链接、哪些 brain
字段缺失、什么处于待处理状态，以及该伸手去拿哪些命令。
- agent-cli instructions（别名 guide、for-llm）——静态的长篇
参考，每次运行都完全相同。用于在会话中途重读完整契约。

每轮循环：agent-cli --json brief --plan 获取带
可安全自动化标志的有序操作列表，agent-cli --json brief 获取状态快照。

正式契约——JSON 信封结构、退出码、幂等性保证、错误
分类法、原子写入与锁语义——见 docs/contract.md。
该文档就是规范；README、instructions、prompt 以及每个 --help 都服从
于它。

MCP（模型上下文协议）

agent-cli serve 通过 stdio 为任何 MCP 宿主启动一个 MCP 服务器——Claude Desktop、
VS Code、Cursor 等。JSON-RPC 2.0，换行分隔，无运行时依赖。

{
"mcpServers": {
"agent-cli": {
"command": "agent-cli",
"args": ["serve"]
}
}
}

VS Code 的 vscode-mcp 在 .vscode/mcp.json 中的 servers 键下使用相同的
command/args 结构；具体键名请查阅你的宿主文档。

默认只读。 6 个读取工具（brief、doctor、search、snapshot、status、
spect_status）、11 个资源（brain://——brain 文件、技能、目标、经验教训、当前
会话），以及 3 个提示（prompt://session-start、prompt://instructions、
prompt://brief-plan）。

写入受能力门控，而非版本门控。 这 10 个写入工具只有在
宿主于 initialize 期间通过
capabilities.experimental.agentCli.writeTools: true 选择加入后才会出现——必须是这个确切的布尔值；真值字符串
会失败关闭。未选择加入的宿主在 tools/list 中永远不会看到写入工具，并且如果它调用
其中一个，会得到 write_capability_required。宿主提供的 cwd 永远不会重定向写入
的落点。

完整接口——initialize 能力、11 个资源 URI 与载荷契约、
订阅投递契约、工具列表——见 docs/contract.md。

调用他人的 MCP 服务器

agent-cli mcp 是另一个方向：你已接入 Claude Code 和
pi 的服务器，可从 shell 调用。

agent-cli mcp servers                          # 所有已配置项及其信任状态
agent-cli mcp enable pi:web-search-prime       # 批准一个，一次
agent-cli mcp tools pi:web-search-prime        # 它暴露了什么
agent-cli mcp web_search --arg query="mcp spec"

定义从 ~/.claude.json、~/.pi/agent/mcp.json 以及项目的
.mcp.json 读取——在其所有者已经声明它们的地方声明一次。agent-cli 存储
引用和指纹，绝不存储副本，更不用说凭据。

在你启用之前什么都不会运行。 这些命令旨在由* agent
非交互式地运行，因此仅仅出现在配置文件中不足以让一个服务器
可执行——否则任何能写入 ~/.claude.json 的东西都会被下一个调用工具的 agent 执行代码。enable 是非交互式 CLI 无法提示的审批步骤，并且它会固定定义：之后更改命令、参数、url、环境变量或请求头，服务器都会被拒绝，直到有人重新批准它。

参数通过 --arg 传递，绝不要作为裸词。 mcp call search --query hi 无法工作——CLI 解析器会把 --query 当作它自己的选项，工具将接收不到任何内容。请使用 --arg k=v（可重复），或对于任何嵌套内容使用 --args-json / --args-file / --args-stdin。

生成的服务器获得的是白名单环境，而不是你的整个会话，HTTPS 是必需的且拒绝重定向，链路本地和元数据地址会被拒绝，并且服务器返回的每个字符串在到达你的终端之前都会经过凭据脱敏和控制字符剥离。信任模型在 docs/contract.md 中有详细说明。

dev-team 技能

捆绑的 dev-team 技能将任何 agentic CLI 宿主的主 agent 转变为虚拟软件公司的 orchestrator-agent：14 个按需角色人设加上固定的 orchestrator。

| 分组 | 角色 |
| --- | --- |
| 产品与设计 | product-manager、product-owner、business-analyst、ux-ui-designer |
| 工程与架构 | software-architect、tech-lead、frontend-dev、backend-dev、fullstack-dev、ai-ml-engineer |
| 运营与质量 | qa-engineer、devops-engineer |
| 管理 | project-manager、scrum-master |

该协议与宿主无关：

backlog item → every relevant role writes its own perspective (round 1)
→ perspectives shared for a second turn (round 2)
→ orchestrator synthesizes a master plan
→ decomposed into a dependency-aware task DAG
(blocking/parallel, per-task tool + model/thinking config)
→ dispatch, validate, deliver, support

在安装了 agent-cli 的宿主上，该协议是可观测的：每次完成的派发对应一行账本记录，每次交付对应一份持久化的回顾，以及自我改进循环阈值背后的一个真实数字（agent-cli team eval report）。每个观测步骤都是宿主可选的——在没有 agent-cli 的地方，协议会原样运行。

角色人设位于 seed/agents/（每个都通过 agent-cli agents validate）；协议位于 seed/skills/dev-team/（SKILL.md / ROLES.md / WORKFLOW.md）。两者都会在 agent-cli init 时部署到 ~/.agents/。

保持更新

有两个独立的东西会更新：

npm 包 ——

npm install -g @victortomaili/agent-cli@latest

agent-cli doctor 和会话启动简报会在有更新版本时告诉你。每个命令还会在 stderr 上输出一行提示（或在 --json 中输出 updateNotice 字段），以便 agent 可以自动做出反应。使用 --no-update-check 或 AGENT_CLI_NO_UPDATE_CHECK=1 选择退出。
随附的默认内容 — 现有 brain 中的种子文件和受管指令块，与包版本无关：

agent-cli update list          # 已暂存的内容
agent-cli update diff     # 应用前先审查
agent-cli upgrade              # 应用所有已暂存的内容
agent-cli upgrade --overwrite  # 同时替换你修改过的文件（会先备份）

发布后的典型流程：更新 npm 包，然后运行 agent-cli upgrade。

Brain schema 迁移 — 当某个版本为 IDENTITY.md / SOUL.md / USER.md 引入了新的结构化标签时，memory upgrade 命令树会引导 LLM agent 逐个文件完成迁移：

agent-cli memory upgrade status       # 你当前处于哪个 schema，还有什么待处理
agent-cli memory upgrade plan --json  # 迁移计划 + instructionsForAgent 操作指引
agent-cli memory upgrade prepare  # 备份文件，打印迁移规范
agent-cli memory upgrade apply    # 标记为已应用（递增 .schema-version）

文件会先备份到 ~/.agents/.upgrade-backups/-/，因此你可以回滚。

添加新的 AI 编码工具

node scripts/add-target.js  ""  [global] [project] [detect]

这会用文档中列出的字段生成 src/targets/.js，更新 src/targets/index.js 以导入并列出它，并打印后续步骤。运行 npm run check && npm test 并提交 PR —— 只需改动两个文件，脚手架会完成索引编辑，从而保持顺序正确，并避免 index.js 成为合并冲突的重灾区。（src/targets.js 是为向后兼容而保留的轻量再导出垫片。）

开发

git clone https://github.com/VictorTomaili/agent-cli.git
cd agent-cli
npm install
npm link            # 全局 agent-cli 由此检出提供支持

npm run check       # 对每个 src/.js 进行语法检查
npm test            # node --test test/.test.js

切勿将开发构建指向你真实的 brain。 每个命令和每个测试都会遵循 AGENT_CLI_HOME：

AGENT_CLI_HOME=$(mktemp -d) agent-cli doctor

CI 在 ubuntu × windows × Node 22 × 24 上运行 npm run check && npm test。

关于分层、不变量和约定，请参阅 CONTRIBUTING.md；
关于代码的组织方式，请参阅 ARCHITECTURE.md；
关于变更内容，请参阅 CHANGELOG.md；
如需报告漏洞，请参阅 SECURITY.md。

许可证

MIT © Victor Tomaili