Agent21
Agent21 是一个项目级 AI 编程代理配置同步 CLI。团队只维护一套工程配置， 即可在 Claude Code、Codex CLI、Cursor、OpenCode、Pi、WorkBuddy 和 Qoder 之间同步使用：
AGENTS.md：项目指令.agents/skills/：项目 Skills.mcp.json：MCP 服务配置（可选）
Agent21 只管理当前项目，不修改用户的全局 Agent 配置。
当前版本：
0.1.3（Alpha）。建议先提交现有项目文件，再执行首次同步。
安装
需要 Python 3.11 或更高版本。
使用 uv（推荐）：
uv tool install agent21
使用 uv 安装后，更新到最新版本：
uv tool upgrade agent21
或使用 pip：
python -m pip install agent21
确认安装成功：
agent21 --version
快速开始
进入需要统一配置的项目：
cd /path/to/your/project
agent21 init --agents claude,codex,cursor,opencode,pi,workbuddy,qoder --mode auto --yes
init 会创建 Agent21 配置目录、缺失的 AGENTS.md 和 .agents/skills/，并复用
已有内容。可选的 .mcp.json 仅在项目已经提供时使用。
随后编辑项目的权威配置，并预览同步计划：
agent21 sync --dry-run
确认计划后执行同步，再检查项目健康状态：
agent21 sync
agent21 doctor
以后修改 AGENTS.md、.agents/skills/ 或 .mcp.json 后，重新运行
agent21 sync 即可。
常用命令
| 命令 | 用途 |
|---|---|
agent21 init |
在当前项目初始化权威配置和 manifest |
agent21 sync --dry-run |
校验并预览同步计划，不写入文件 |
agent21 sync |
将权威配置同步到已启用且本机可用的 Agent |
agent21 doctor |
只读检查配置、漂移、Skills、MCP、锁和中断事务 |
agent21 skill install <source> |
从本地目录或显式 Git URL 安装项目 Skill |
agent21 skill list |
列出 Agent21 管理的项目 Skills |
agent21 skill remove <name> |
删除未被修改的托管 Skill |
agent21 --help |
查看完整命令帮助 |
初始化时可以只启用团队实际使用的 Agent：
agent21 init --agents codex,cursor --mode auto --yes
同步模式支持：
auto：平台支持时使用符号链接，否则复制（推荐）copy：始终复制symlink：始终使用符号链接
初始化后也可以编辑 .agents/config.yaml 调整启用的 Agent、同步模式和权威源路径。
管理项目 Skills
本地 Skill 目录必须包含根文件 SKILL.md：
agent21 skill install path/to/my-skill
agent21 skill list
agent21 skill remove my-skill
也可以安装显式 Git URL，并按需指定名称：
agent21 skill install https://github.com/example/my-skill.git --name my-skill
Agent21 只复制并记录 Skill 内容，不执行 Skill 代码，也不保存 Git 凭证。
Agent 支持范围
| Agent | 项目指令 | Skills | MCP |
|---|---|---|---|
| Claude Code | 兼容同步 | 兼容同步 | 原生读取 .mcp.json |
| Codex CLI | 原生读取 | 原生读取 | 转换为 .codex/config.toml |
| Cursor | 原生读取 | 原生读取 | 转换为 .cursor/mcp.json |
| OpenCode | 原生读取 | 原生读取 | 转换为 opencode.json |
| Pi | 原生读取 | 原生读取 | 通过 pi-mcp-adapter 兼容读取 |
| WorkBuddy | 原生读取根 AGENTS.md |
映射到 .codebuddy/skills/ |
原生读取根 .mcp.json |
| Qoder | 原生读取 | 映射到 .qoder/skills/ |
原生读取根 .mcp.json |
Agent21 不会安装这些 Agent 或第三方扩展。Pi MCP 需由用户显式安装：
pi install npm:pi-mcp-adapter
Agent21 只检测 pi-mcp-adapter 是否可用，不执行它，也不会把“可检测”误报为已加载。
WorkBuddy 沿用腾讯 CodeBuddy 的项目配置目录，因此不依赖推测的 CLI 名称；显式启用后即可同步
.codebuddy/skills/。当根目录没有 CODEBUDDY.md 时，WorkBuddy 原生读取 AGENTS.md；若两者同时存在，
agent21 doctor 会报告 CODEBUDDY.md 遮蔽统一指令。其他已启用但本机找不到可执行文件的 Agent 会被标记为
skipped。
安全与冲突处理
- 不覆盖未由 Agent21 管理的冲突文件。
sync --dry-run在写入前展示已校验的计划。- 同步通过事务写入；失败时避免留下部分更新。
- manifest 记录托管产物及摘要，
doctor可发现手工修改造成的漂移。 - 诊断输出不会回显 MCP 密钥值，但
.mcp.json仍应按项目的凭证策略妥善管理。
遇到问题时，先运行：
agent21 doctor
agent21 --help
如果问题仍然存在，请在 GitHub Issues 提交可复现步骤； 安全问题请遵循 SECURITY.md，不要公开提交凭证或漏洞细节。
开发与贡献
README 面向 CLI 使用者。开发环境、测试设计、适配器验证和发布流程分别维护在：
项目采用 MIT License。
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file agent21-0.1.3.tar.gz.
File metadata
- Download URL: agent21-0.1.3.tar.gz
- Upload date:
- Size: 304.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
41cec939872f052e24fd17722560548d0c2ab7fa02949199f9ff75290518c25a
|
|
| MD5 |
589bb535224af7512aa0a21b365c34c0
|
|
| BLAKE2b-256 |
8841274acf5ae12b3f5d8bf72f481ba5147d81b45ebecd1dc70e62417bfd9841
|
Provenance
The following attestation bundles were made for agent21-0.1.3.tar.gz:
Publisher:
release.yml on jeweis/agent21
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
agent21-0.1.3.tar.gz -
Subject digest:
41cec939872f052e24fd17722560548d0c2ab7fa02949199f9ff75290518c25a - Sigstore transparency entry: 2408774265
- Sigstore integration time:
-
Permalink:
jeweis/agent21@a275d574e528ae8b523aaccb4b5308b1a105286f -
Branch / Tag:
refs/tags/v0.1.3 - Owner: https://github.com/jeweis
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@a275d574e528ae8b523aaccb4b5308b1a105286f -
Trigger Event:
push
-
Statement type:
File details
Details for the file agent21-0.1.3-py3-none-any.whl.
File metadata
- Download URL: agent21-0.1.3-py3-none-any.whl
- Upload date:
- Size: 41.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0a360b209f3de4ce38ef0b756138801a3104c4347151ae75b70c90a000d00e82
|
|
| MD5 |
14634ef41165fa21c5620e034189d2a7
|
|
| BLAKE2b-256 |
9062bf802d8792b218312057f549efee600cf01b5f9835a6bbe5fe03d5b9d8fc
|
Provenance
The following attestation bundles were made for agent21-0.1.3-py3-none-any.whl:
Publisher:
release.yml on jeweis/agent21
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
agent21-0.1.3-py3-none-any.whl -
Subject digest:
0a360b209f3de4ce38ef0b756138801a3104c4347151ae75b70c90a000d00e82 - Sigstore transparency entry: 2408774378
- Sigstore integration time:
-
Permalink:
jeweis/agent21@a275d574e528ae8b523aaccb4b5308b1a105286f -
Branch / Tag:
refs/tags/v0.1.3 - Owner: https://github.com/jeweis
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@a275d574e528ae8b523aaccb4b5308b1a105286f -
Trigger Event:
push
-
Statement type:
