AGENTS.md 同步器 VictorTomaili/agent-cli

agent-cli

一份 AGENTS.md，搞定所有 AI 编程工具，永远保持同步。

快速开始 · 让你的智能体自己装 · 支持的工具 · 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-cli 往每个工具的原生配置位置写一个小的指针存根，告诉那个工具真正的文件在哪。

~/AGENTS.md ← 你唯一需要编辑的文件 │ ┌────────────┬───┴───┬────────────┬─────────────┐ ▼ ▼ ▼ ▼ ▼ ~/.claude/ ~/.codex/ ~/.gemini/ .cursor/ …17 tools CLAUDE.md AGENTS.md GEMINI.md rules/.mdc └──────────── pointer stubs, regenerated any time ────────────┘

同一段文字你永远不用写第二遍。存根可以放心重新生成——agent-cli 只会动它自己创建的文件，覆盖前还会先备份原生内容。

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

安装

npm install -g @victortomaili/agent-cli

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

快速开始

agent-cli init # bootstrap the master, detect + link installed tools, install hooks
agent-cli status # master state + per-target pointer health
agent-cli doctor # full diagnostic (config, pointers, staged updates, npm freshness)
agent-cli edit # open the master in $EDITOR

init 可重复执行，且从不提问——重跑一次会修好所有缺失的部分，不会碰你改过的内容。就是这条命令，把一次裸安装变成一套可用的安装流程：它会初始化主文件，为检测到的每个工具写入指针桩，把主目录指针部署到 ~/AGENTS.md，安装 SessionStart 简报钩子，并配置好内置的技能管理器。

让你的智能体来安装

agent-cli 天生就是给 AI 智能体驱动的，所以你可以把整套安装交给它。
把下面的提示词复制到 Claude Code、Codex、Cursor、Gemini CLI，或任何能访问 shell 的智能体——它会自动完成安装、配置、验证并回报结果，你什么都不用碰。

在这台机器上帮我完整安装并配置 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 编程工具，
- 我的主文件现在在哪里，
- doctor 标记出的、需要我决策的事项。

规则：
- 绝不传 --force——它会覆盖我已有的内容。
- 绝不手动编辑指针桩；它们是生成的。
- 如果某一步失败，把真实错误给我看，不要绕过去。

然后运行 agent-cli prompt，把它的输出加到你自己的系统提示词里，这样你在本次会话剩余时间里都能记住我的配置。

提示： 安装完成后，agent-cli prompt 会输出一段约 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 |

缺你的工具？加一个只要改两个文件的 pull request。

核心概念

- Master —— 你唯一要写的文件：~/AGENTS.md（全局）或 .agents/AGENTS.md（项目级，放在仓库里）。
- Pointer stub —— agent-cli link 在工具原生配置路径生成的小文件。里面有机器可读的元数据，也有一段给人看的说明，把智能体重定向到 master。可以放心重新生成；只有 agent-cli 自己创建的文件才会被改动。
- Target —— agent-cli 知道怎么指向的 AI 编程工具。agent-cli targets 列出全部；agent-cli target enable <id> [--global|--project] 打开其中一个。
- 先备份再覆盖 —— 对已经存有你自己内容的 target 执行 agent-cli link --target <id> --force，会先把它复制到 <path>.agent-cli-backup-<iso>，并在 --json 信封的 backup 字段里给出这个路径。

常用命令

| 领域 | 命令 |
| 指针同步 | link、unlink、status、target enable\|disable、where、pull |
| Master 内容 | edit、identity、soul、user、env、models、archetype |
| 子代理人格 | 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 <taskId>、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 钩子）、automation add\|list\|run、watch、serve（MCP over stdio） |
| 外部 MCP 工具 | mcp servers\|enable\|disable\|tools\|call、mcp <tool> --arg k=v |
| 给 LLM 智能体用 | instructions（静态指南）、prompt [--for <task>]（动态，感知状态） |

以上任意命令都可以 agent-cli help <command>；agent-cli --json manifest 给出完整的机器可读命令与退出码契约。

打错字它会提示最接近的匹配 —— agent-cli statuz 会回你 Did you mean: agent-cli status, agent-cli stats?，智能体不用重读 --help 就能自我纠正。

给驱动 CLI 的 LLM 智能体

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

- agent-cli prompt [--for "<task>"] —— 检查已安装的工具、大脑状态和待办动作，然后输出一段约 2 KB 的 Markdown，专门给 system-prompt 槽位用。
每个会话运行一次。 智能体随后就知道哪些工具已关联、哪些 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（Model Context Protocol）

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 # everything configured, and its trust state
agent-cli mcp enable pi:web-search-prime # approve one, once
agent-cli mcp tools pi:web-search-prime # what it exposes
agent-cli mcp web_search --arg query="mcp spec"

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

不启用就不运行。 这些命令本就该由智能体非交互式运行，所以仅仅出现在配置文件里，不足以让服务器可执行文件——否则任何能写 ~/.claude.json 的东西，都会被下一个调用工具的智能体执行成代码。enable 是非交互式命令行无法代劳的审批步骤，它还会把定义钉死：之后改动 command、args、url、env 或 headers，服务器就会被拒绝，直到有人重新审批。

参数一律走 --arg，不要写成裸词。 mcp call search --query hi 行不通——命令行解析器会把 --query 当成自己的选项，工具什么也收不到。用 --arg k=v（可重复），嵌套结构则用 --args-json / --args-file / --args-stdin。

派生出的服务器拿到的是白名单环境，而不是你整个会话；强制 HTTPS 并拒绝重定向；拒绝 link-local 和 metadata 地址；服务器返回的每个字符串在到达你终端之前，都会做凭据脱敏和控制字符剥离。信任模型见 docs/contract.md。

dev-team 技能

内置的 dev-team 技能，把任何 agentic CLI 宿主的主智能体变成虚拟软件公司的 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 的宿主上，协议是带埋点的：每次派发完成记一行台账，每次交付留一份复盘，Self-Improvement Loop 的阈值背后有真实数字（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 字段），方便智能体自动响应。用 --no-update-check 或 AGENT_CLI_NO_UPDATE_CHECK=1 关掉。
随版本发布的默认内容 —— 种子文件和托管指令块，写进你现有的 brain，与包版本无关：

agent-cli update list # what is staged
agent-cli update diff <ver> # review before applying
agent-cli upgrade # apply everything staged
agent-cli upgrade --overwrite # also replace files you changed (backed up first)

发布之后的典型流程：先更新 npm 包，再跑 agent-cli upgrade。

Brain schema 迁移 —— 某个版本为 IDENTITY.md / SOUL.md / USER.md 带来新的结构化标签时，memory upgrade 命令树会带着 LLM 智能体逐个文件走完迁移：

agent-cli memory upgrade status # what schema you are on, what is pending
agent-cli memory upgrade plan --json # the plan + an instructionsForAgent walkthrough
agent-cli memory upgrade prepare <id> # back up the file, print the migration spec
agent-cli memory upgrade apply <id> # mark applied (bumps .schema-version)

文件会先备份到 ~/.agents/.upgrade-backups/<ts>-<id>/，方便你回滚。

添加新的 AI 编程工具

node scripts/add-target.js <id> "<Display Name>" <docs-url> [global] [project] [detect]

这条命令会生成 src/targets/<id>.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 # global agent-cli backed by this checkout

npm run check # syntax-check every 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