# @agents-dev/cli 中文文档

规范地址：https://npmcn.com/package/%40agents-dev/cli/

版本：0\.9\.3
npm 元数据更新时间：2026-11-02T16:21:39.232Z
中文译文更新时间：2026-11-05T18:02:46.035Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agents-dev/cli
原文对照：https://npmcn.com/package/%40agents-dev/cli/?lang=original
项目主页：https://github.com/amtiYo/agents#readme
源码仓库：https://github.com/amtiYo/agents

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，277 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.12\.0
- 运行依赖：6 个
- 首次发布：2026-02-07T16:48:22.914Z
- 最新版本发布：2026-11-02T16:21:38.942Z
- 近 30 天下载量：108681（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

一个配置来统治它们全部——同步MCP服务器,技能与AGENTS.md跨越了18个AI编码工具,并把它们作为代理插件包.

## 安装

```sh
npm install @agents-dev/cli
```

也可以使用：`pnpm add @agents-dev/cli`、`yarn add @agents-dev/cli`、`bun add @agents-dev/cli`

## README

# 代理人

**一个人物来统治他们.**  
多LLM开发实用标准层.

[![npm version](https://img.shields.io/npm/v/@agents-dev/cli?style=for-the-badge&logo=npm&logoColor=white&labelColor=0f172a&color=e11d48)](https://www.npmjs.com/package/@agents-dev/cli) [![downloads](https://img.shields.io/npm/dt/@agents-dev/cli?style=for-the-badge&logo=npm&logoColor=white&labelColor=0f172a&color=2563eb)](https://www.npmjs.com/package/@agents-dev/cli) [![node version](https://img.shields.io/node/v/@agents-dev/cli?style=for-the-badge&logo=node.js&logoColor=white&labelColor=0f172a&color=10b981)](https://www.npmjs.com/package/@agents-dev/cli) [![license](https://img.shields.io/badge/license-Apache%202.0-334155?style=for-the-badge&labelColor=0f172a)](https://www.apache.org/licenses/LICENSE-2.0)

[快速启动](https://npmcn.com/package/%40agents-dev/cli/#readme-quick-start) • 妇女 [一体化](https://npmcn.com/package/%40agents-dev/cli/#readme-supported-integrations) • 妇女 [图标](https://npmcn.com/package/%40agents-dev/cli/#readme-command-overview) • 妇女 [插件](https://npmcn.com/package/%40agents-dev/cli/#readme-agent-plugins) • 妇女 [财务问题](https://npmcn.com/package/%40agents-dev/cli/#readme-faq)

![agents start](https://npmcn.com/package/%40agents-dev/cli/docs/screenshot.jpg)

* * *

## 问题

指令趋同于 `AGENTS.md` 和技能凝聚在一起 `SKILL.md`. MCP 服务器配置没有. 每个工具都保存自己的文件,以自己的格式保存在自己的位置:

| 格式 | 工具 |
| :-- | :-- |
| 汤姆, `mcp_servers` 图表 | 编码( C)`.codex/config.toml`), Grok Building (英语:`.grok/config.toml`(中文(简体) ) |
| 乔森, `mcpServers` 键 | 克劳德代码和副驾驶CLI(`.mcp.json`),克洛德桌面(全球),双子星CLI(`.gemini/settings.json`),光标(`.cursor/mcp.json`),反重力(`.agents/mcp_config.json`), Devin桌面(全球), Devin CLI(`.devin/mcp_config.json`),朱尼(`.junie/mcp/mcp.json`),工厂机器人(`.factory/mcp.json`(中文(简体) ) |
| JSON,另一把钥匙 | 副驾驶 VS 代码 (`servers`),OpenCode和Kilo (英语:`mcp`),Amp (英语:`amp.mcpServers`页:1`context_servers`(中文(简体) ) |
| 也门 | 鹅 (:`extensions` 内 `~/.config/goose/config.yaml`(中文(简体) ) |

用手加一个服务器,你写了18次,然后看复制件散去.

`agents` 保持一个真相的来源 `.agents/` 并实现它 对于每一个工具你启用.

* * *

## 快速启动

```bash
# 1. Install
npm install -g @agents-dev/cli

# 2. Interactive setup — picks integrations, adds MCP servers, syncs everything
agents start

# 3. Re-sync whenever config changes
agents sync
```

`.agents/agents.json` 现在,是真理的唯一来源. `agents sync --check` 输出 `2` 当一个工具配置被漂移时,它就起到CI门的作用.

* * *

## 支持的整合

出十八种工具来. "验证"指工具自己的CLI被运行于此项目所写的文件中;其余则遵循供应商文件,如果某事被关闭则值得报告.

| 一体化 | `--llm` 编号 | 它写的MCP配置 | 技能 | 已验证 |
| :-- | :-- | :-- | :-: | :-: |
| 代码 | `codex` | `.codex/config.toml` (管理区块,处理项目信托) | 本地语言 | ✅ |
| 克劳德代码 | `claude` | `.mcp.json` 项目范围或CLI 本地/用户范围,加根 `CLAUDE.md` 包装 | 桥 | ✅ |
| 克劳德桌面 | `claude_desktop` | 全球 `claude_desktop_config.json`,只有 stdio 服务器 | —— 说 | ✅ |
| 双子座CLI | `gemini` | `.gemini/settings.json` | 桥 | ✅ |
| 光标 | `cursor` | `.cursor/mcp.json` + CLI 启用 | 桥 | ✅ |
| 副驾驶 VS 代码 | `copilot_vscode` | `.vscode/mcp.json` | 本地语言 | ✅ |
| 副驾驶CLI | `copilot_cli` | `.mcp.json`,或 `.github/mcp.json` | 本地语言 | ✅ |
| 反重力 | `antigravity` | `.agents/mcp_config.json` | 平面副本 | ✅ |
| Devin 桌面( Windsurf) | `windsurf`, (中文(简体) ), `devin_desktop` | 全球 `~/.codeium/windsurf/mcp_config.json` | 桥 | ✅ |
| 打开代码 | `opencode` | `opencode.json` (单位:千美元)`mcp`(中文(简体) ) | 本地语言 | ✅ |
| 朱妮 | `junie` | `.junie/mcp/mcp.json` | 桥 | ✅ |
| Grok 构建 | `grok` | `.grok/config.toml` (管理块,处理文件夹信任) | 本地语言 | ✅ |
| 倾角 | `amp` | `.amp/settings.json` (单位:千美元)`amp.mcpServers`(中文(简体) ) | 本地语言 | ✅ |
| 工厂机器人 | `droid`, (中文(简体) ), `factory` | `.factory/mcp.json` | 本地语言 | ✅ |
| 基罗 | `kilo`, (中文(简体) ), `kilocode` | `.kilo/kilo.jsonc` (单位:千美元)`mcp`(中文(简体) ) | 桥 | —— 说 |
| 开发CLI | `devin` | `.devin/mcp_config.json` | 本地语言 | ✅ |
| 齐德 | `zed` | `.zed/settings.json` (单位:千美元)`context_servers`(中文(简体) ) | 本地语言 | —— 说 |
| 鹅 | `goose` | `~/.config/goose/config.yaml` (单位:千美元)`extensions`(中文(简体) ) | 本地语言 | ✅ |

**技能专栏.** `bridge` 表示工具目录中的同义链接 `.agents/skills` (无符号链接的复制品). `native` 表示工具读取 `.agents/skills` 自己,所以没有创造. `—` 表示工具的项目级技能定位在此没有被执行.

**Grok 文件夹信任 .** Grok忽略了一个项目的MCP服务器及其技能 `grok inspect` 仅列出无。 信赖生活 `~/.grok/trusted_folders.toml`,从 `config.toml`。 。 。 . `agents doctor` 报告一个不信任的文件夹和 `agents doctor --fix` 记录信任.

**共享文件 .** `.mcp.json` 由克劳德代码和副驾驶CLI读取,所以 `agents` 都写过一次 仅针对其中一款的服务器仍然可见于另一款;同步表示而不是假装目标将其隔离.

**鹅的秘密.** Goose从环境中读取证书 `env_keys`,所以从不将值写入其配置中。 您的外壳中必须存在的变量同步列表 .

* * *

## 项目布局

```
your-project/
├── AGENTS.md                        ← Canonical instructions for all tools
├── CLAUDE.md                        ← Generated Claude wrapper (`@AGENTS.md`)
├── .agents/
│   ├── agents.json                  ← MCP servers, profiles, config (commit this)
│   ├── local.json                   ← Secrets & overrides (gitignored)
│   ├── mcp_config.json              ← Generated Antigravity workspace MCP
│   ├── skills/                      ← Reusable workflow definitions
│   │   └── my-skill/SKILL.md
│   └── generated/                   ← Auto-generated artifacts (gitignored)
│
│  ┌─── Generated by `agents sync` ───┐
├── .mcp.json                         │  Claude Code + Copilot CLI
├── .codex/config.toml                │  Codex
├── .grok/config.toml                 │  Grok Build
├── .gemini/settings.json             │  Gemini CLI
├── .cursor/mcp.json                  │  Cursor
├── .vscode/mcp.json                  │  Copilot VS Code
├── .amp/settings.json                │  Amp
├── .factory/mcp.json                 │  Factory Droid
├── .kilo/kilo.jsonc                  │  Kilo
├── .devin/mcp_config.json            │  Devin CLI
├── .zed/settings.json                │  Zed
├── opencode.json                     │  OpenCode
├── .junie/mcp/mcp.json               │  Junie
└── .claude/skills → .agents/skills   │  Skill bridges
```

> **基特战略.** 默认 `source-only` 模式,仅限 `.agents/agents.json`, (中文(简体) ), `.agents/skills/` 财务报告和审定财务报表 `AGENTS.md` 承诺:同步生成的每分每分 每分每分每分每分每分每分每分每分每分每分每分每分每分每分 单位 `commit-generated` 模式 `.gitignore`,所以一个克隆人可以在不安装此 CLI 的情况下获得工作工具配置. 这就是你的行为 `.mcp.json` 其余的团队.
> 
> 无论哪种方式,持有工具自身设置的文件(`.zed/settings.json`, (中文(简体) ), `.amp/settings.json`, (中文(简体) ), `.kilo/kilo.jsonc`和 `.github/mcp.json` 从未添加到 `.gitignore`:同步将其条目合并到它们中,然后将文件的其余部分,包括是否跟踪,留给您.

* * *

## 命令概览

### 设置同步( S)

| 命令 | 说明 |
| :-- | :-- |
| `agents start` | 交互设置:集成,MCP服务器,技能,先同步 |
| `agents init` | 脚手架 `.agents/` 没有向导 |
| `agents sync` | 重新生成并实现所有工具配置 |
| `agents sync --check` | 只读漂移检查, 退出 `2` 未同步时 |
| `agents sync --profile ci` | 在不更改活动配置的情况下同步一个配置文件 |
| `agents watch` | 自动同步打开 `.agents/` 变动 |

### 诊断

| 命令 | 说明 |
| :-- | :-- |
| `agents status` | 集成、 MCP 服务器、 文件状态、活探测器 |
| `agents doctor` | 验证配置并报告问题 |
| `agents doctor --fix` | 应用它能安全做的修正 |
| `agents update` | 检查 npm 的更新的 CLI |

### MCP 服务器

| 命令 | 说明 |
| :-- | :-- |
| `agents mcp add <name|url>` | 交互或从 URL 添加服务器 |
| `agents mcp import --file config.json` | 从 JSON/ JSONC 从批量导入 |
| `agents mcp list` | 列出已配置的服务器 |
| `agents mcp remove <name>` | 删除服务器 |
| `agents mcp test [--runtime]` | 验证定义, 可选择通过工具 CLIs |
| `agents mcp budget` | 连接到每个服务器并测量其上下文成本 |

### 简介

| 命令 | 说明 |
| :-- | :-- |
| `agents profile set ci --server docs --server git` | 创建或替换配置文件 |
| `agents profile use ci` | 激活配置文件并同步 |
| `agents profile use` | 清除配置文件, 回到每个服务器 |
| `agents profile list` | 显示配置和当前配置 |
| `agents profile remove ci` | 删除配置文件 |

### 插件

| 命令 | 说明 |
| :-- | :-- |
| `agents plugin export --name my-stack` | 构建代理插件 v1 软件包 `.agents` |
| `agents plugin validate <dir>` | 对照规格检查软件包 |
| `agents plugin import <dir>` | 在此工程中添加软件包的服务器和技能 |

### 技能和融合

| 命令 | 说明 |
| :-- | :-- |
| `agents skills list` | 列表中的技能 `.agents/skills/` |
| `agents connect --llm cursor,grok` | 启用集成 |
| `agents disconnect --llm codex` | 禁用整合 |
| `agents reset` | 删除已生成的文件, 保存 `.agents/` |
| `agents reset --hard` | 完全清理 |

### 全球模式

运行任何命令 `--global` (或 `-g`,或从 `$HOME`管理MCP服务器和整个机器的技能 `~/.agents/agents.json`数字 :

```bash
agents init -g
agents connect -g --llm opencode,codex,grok
agents sync -g
```

仅具有用户级配置(Claude Desktop, Devin Desktop, Goose)的工具,都用两种模式写在那里.

* * *

## 代理插件

[代理插件 1.0.0](https://agent-plugins.org/specification) 由 ChatGPT 和 Codex, Cursor, GitHub Copilot, Kiro 和 VS 代码所读取, 是技能和 MCP 服务器的供应商中立软件包格式 。 软件包是一个目录 `plugin.json`,一个 `mcp.json` (单位:千美元) `skills/` 文件夹,它接近什么 `.agents/` 已经搁置.

```bash
agents plugin export --name my-stack --plugin-version 1.0.0
```

```
dist/agent-plugin/
├── plugin.json      $schema, name, version, description
├── mcp.json         $schema, mcpServers
└── skills/          copied from .agents/skills
```

导出已读 `.agents/agents.json` 只是,从来没有 `local.json`:什么是舰只 `${VAR}` 来自已承诺文件的占位符,以及更改软件包需要的命令打印. `${PROJECT_ROOT}` 成为规格的 `${PLUGIN_ROOT}`。 。 。 .

向另一边走, `agents plugin import ./some-plugin` 在其插件名下添加软件包的服务器( n)`my-stack.docs`)所以您已经定义的任何东西都被替换.

* * *

## 预算

MCP服务器在代理做任何工作前的成本上下文:每个工具定义被加载到前面.

```bash
agents mcp budget
```

```
MCP context budget:
  everything              13 tools  ~  1916 tokens
  filesystem              11 tools  ~  1240 tokens
  broken                 error: spawn broken-server ENOENT

Servers        3
Tools          24
Estimated      ~3156 tokens of context
```

命令会讲MCP `2026-07-28` 直接从stdio和可流的HTTP上,所以数字来自服务器本身. 以握手订正方式建造的服务器(`2025-11-25` 因此这两个时代都起作用。 Token计数是从工具定义的大小来估计的,而不是由模型来测量. 添加 `--verbose` 每个工具的分解,以及 `--profile` 以衡量一个简介的成本.

其配置仍然包含未解决的服务器 `${VAR}` 被跳过而不是开始.

* * *

## MCP 服务器示例

```bash
# From a catalog URL
agents mcp add https://mcpservers.org/servers/context7-mcp

# stdio server
agents mcp add my-server --command npx --arg @my-org/mcp-server --arg /path/to/project

# HTTP server with a secret header
agents mcp add company-api --url "https://api.company.com/mcp" \
  --secret-header "Authorization=Bearer YOUR_API_TOKEN"

# Only for specific tools
agents mcp add ide-server --command ide-mcp --target cursor --target zed
```

服务器定义支持 `timeout`, (中文(简体) ), `connectTimeout`, (中文(简体) ), `tools`, (中文(简体) ), `disabledTools`, (中文(简体) ), `oauth`, (中文(简体) ), `headersHelper`, (中文(简体) ), `bearerTokenEnvVar` 财务报告和审定财务报表 `envFile`。每个字段只写为文档工具,同步表示当一个字段被丢弃给不支持它的目标时.

数值支持 `${VAR}` 财务报告和审定财务报表 `${VAR:-default}`附加时 `${PROJECT_ROOT}`。 。 。 .

* * *

## 警卫

|  | 什麽 | 何处 |
| :-- | :-- | :-- |
| 🔓 | 服务器定义、 团队配置 | `.agents/agents.json` —— 说 **承诺** |
| 🔒 | API 密钥、 符号、 秘密 | `.agents/local.json` —— 说 **带子** |

-   隐藏的值被移动到 `local.json` 改为: `${PLACEHOLDER}` 内 `agents.json` 当服务器被添加时.
-   `agents doctor` 警告 字面上的秘密 在犯罪配置.
-   信封密钥和信头名称在到达配置文件或外壳之前被验证.
-   `agents plugin export` 从不读 `local.json`。 。 。 .
-   配置此 CLI 不 gitignore 保存 `${VAR}` 来自 `agents.json`,该值是否来自 `local.json` 或从你的外壳。 Amp, Zed 和 Kilo 与工具自己的设置共享一个文件,以及 `.github/mcp.json` 是文件小组审查;同步列表中哪些变量可以导出,以便这些工具能够解决. `commit-generated` 基于同样的原因,模式保留了每个生成的配置中的秘密.
-   重写此 CLI 的配置会保留它拥有的权限, 因此您限制的文件 `0600` 保持这种方式.

* * *

## 团队工作流程

**领导制定项目:**

```bash
agents start
agents mcp add https://mcpservers.org/servers/context7-mcp
git add .agents/agents.json .agents/skills/ AGENTS.md && git commit -m "Add agents config"
```

单位 `source-only` 模式是团队所需要的一切:每个克隆运行 `agents sync` 财务报告和审定财务报表 获取本地工具配置。 切换 `syncMode` 改为 `commit-generated` 如果你愿意的话 承诺 `.mcp.json` 其余的提供给没有安装CLI的人.

**机上新成员 :**

```bash
git clone <repo> && cd <repo>
agents start        # keeps the committed config, writes local tool files
```

**CI: 爱奇艺**

```bash
agents sync --check  # exits 2 when a tool config drifted from .agents/
```

* * *

## 财务问题

**这能代替AGENTS.MD吗?**  
没有. `AGENTS.md` 保留每个工具读取的指令文件。 此 CLI 处理机器可读侧面( MCP 服务器、 技能、 每个工具配置) 并生成最小根 `CLAUDE.md` claude代码需要包装,因为Claude代码不读 `AGENTS.md`。 。 。 . **为什么克劳德代码使用 `.mcp.json` 现在?**  
项目范围是各小组的Anthropic文件的位置:它生活在存储器中,因此每个在它上工作的人都得到同样的服务器,在“承诺生成”模式下,它像任何其他文件一样受到审查。 在0.9.0之前,CLI在机器本地注册服务器 `~/.claude.json`其他人都看不见 设定 `integrations.options.claudeScope` 改为 `"local"` 旧行为; 从方案3升级的项目自动保留。 对于每个工程中可用的服务器,设置为 `"user"` (单位:千美元)`"global"` 是别名)并运行 `agents sync -g`. 新的家庭指导装置(`agents init -g` 或者说 `agents start -g`)默认为用户范围;正常寄存器默认为项目范围. 保留现有的明确选择。 见\[Claude MCP 范围(docs/agents-system.md#claude-mcp-scopes),用于迁移和清理. **我能用一个工具吗?**  
对 秘密分拆,漂移检查,插件导出和上下文预算都是用单一工具有用的. **期间发生的事 `agents sync`? 吗?**  
写着 `.agents/`合并 `local.json`,解析占位符,应用活性配置文件,使每个工具的格式和文件在原子上写入。 与工具自己的设置(Amp,Zed,Kilo,双子座,OpenCode,Goose)共享的文件被合并,因此设置CLI并不拥有生存能力. 跑道为一相. **我可以瞄准一个MCP服务器 只为特定的工具?**  
是的,还有 `"targets"` 在定义中或 `--target` 打开 `agents mcp add`。例外是 `.mcp.json`,Claude Code和Copilot CLI都读到: 该文件中的服务器对双方都可见,同步警告而不是暗示其他. **怎么样 `agents doctor` 检查?**  
缺少或无效的配置, 已执行文件中的字面秘密, 未解决的env vars, 生成文件中的漂移, Codex 项目信任, 无法解析的全局 Codex 配置, 已贬值 `sse` 运输,技能前题 与特工技能规格, 和技能桥梁状态. **我怎么从0.8.x升级?**  
运行任何命令. `.agents/agents.json` 从 schema 3 自动移到 4 , 而上一个文件保存为 `agents.json.v3.bak`。不需要其他条件.

* * *

## 文档

-   [`docs/agents-system.md`](https://npmcn.com/package/%40agents-dev/cli/docs/agents-system.md) - 同步、技能和生成文件如何工作
-   [`docs/EXAMPLES.md`](https://npmcn.com/package/%40agents-dev/cli/docs/EXAMPLES.md) - 项目设置
-   [`CONTRIBUTING.md`](https://npmcn.com/package/%40agents-dev/cli/CONTRIBUTING.md) ——开发工作流程
-   [`CHANGELOG.md`](https://npmcn.com/package/%40agents-dev/cli/CHANGELOG.md) ——发布历史

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://npmcn.com/package/%40agents-dev/cli/LICENSE) 财务报告和审定财务报表 [通知](https://npmcn.com/package/%40agents-dev/cli/NOTICE)。 。 。 .

## 常见问题

### @agents-dev/cli 是什么？

一个配置来统治它们全部——同步MCP服务器,技能与AGENTS\.md跨越了18个AI编码工具,并把它们作为代理插件包\.

### 如何安装 @agents-dev/cli？

在项目目录运行 npm install @agents-dev/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agents，可以用 npx agents 直接运行。

### @agents-dev/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agents-dev/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agents-dev/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agents-dev/cli 可以商用吗？

@agents-dev/cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agents-dev/cli 的下载量有多少？

根据 npm 官方下载统计，@agents-dev/cli 在 2026/10/05 – 2026/11/03 这 30 天内被下载 108,681 次，日均约 3,623 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agents-dev/cli 还在维护吗？

最新版本 0\.9\.3 发布于 2026/11/03（3 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。