> ## Documentation Index
> Fetch the complete documentation index at: https://acp-docs.cxykevin.top/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP 代理注册表

**作者：** [@ignatov](https://github.com/ignatov)
**支持者：** [@benbrandt](https://github.com/benbrandt)

## 电梯演讲

ACP 需要一个单一的、受信任的代理注册表，以便客户端能够发现集成、了解它们的特性并自动配置它们。这个 RFD 提议（1）每个代理必须发布的规范清单格式，（2）一个专用的 `agentclientprotocol/registry` 仓库，维护者可以在其中贡献这些清单，（3）聚合并发布可搜索目录以供编辑器和其他客户端使用的工具。

## 现状

没有 ACP 兼容代理的规范列表。信息分散在自述文件或专有信息中，这使得：

* 让用户在 ACP 感知的客户端内直接发现代理变得困难
* 确保协议版本兼容性或功能覆盖
* 保持元数据一致（身份验证要求、托管模式、许可证等）

每个编辑器都构建自定义清单或抓取 GitHub，导致数据重复和过时。

## 代理清单格式（核心提案）

每个代理通过存储在注册表仓库中 `<id>/` 下的 `agent.json` 来宣传自己。JSONC 保持与 ACP 的 JSON 中心模式接近，同时在创作时保持对人类友好。除非另有说明，以下字段是必需的：

| 字段               | 描述                                                                                                                                                                            |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | 小写 slug，在注册表中唯一（也是文件夹名称）。                                                                                                                                                     |
| `name`           | 人类可读的标签。                                                                                                                                                                      |
| `version`        | 向用户显示的代理发布版本。                                                                                                                                                                 |
| `schema_version` | 清单模式的 semver。允许未来的破坏性更改。                                                                                                                                                      |
| `description`    | 代理功能和用途的描述。                                                                                                                                                                   |
| `homepage`       | 文档/营销的 URL。                                                                                                                                                                   |
| `repository`     | 源代码仓库 URL。                                                                                                                                                                    |
| `authors`        | 作者/组织名称数组（镜像 TOML 示例中的 `authors`）。                                                                                                                                            |
| `license`        | 许可证（字符串）。                                                                                                                                                                     |
| `capabilities`   | 实现的 ACP 方法名称数组（例如 `["terminal/new","files/read"]`）。                                                                                                                           |
| `auth`           | 身份验证的身份验证选项数组。这是模式中最复杂的部分。                                                                                                                                                    |
| `distribution`   | 将目标平台映射到下载/执行信息的对象。每个目标键遵循 `<os>-<arch>` 格式（例如 `darwin-aarch64`、`linux-x86_64`、`windows-x86_64`）。每个目标指定 `archive`（下载 URL）、`cmd`（可执行路径）、可选的 `args`（命令行参数数组）和可选的 `env`（环境变量对象）。 |

示例框架：

```jsonc theme={null}
{
  "id": "someagent",
  "name": "SomeAgent",
  "version": "1.0.0",
  "schema_version": "1",
  "description": "用于代码编辑的代理",
  "homepage": "https://github.com/example/someagent",
  "repository": "https://github.com/example/someagent",
  "authors": ["Example Team"],
  "license": "MIT",
  "capabilities": ["terminal", "fs/read", "fs/write"],
  "auth": [
    {
      "type": "api_key",
    },
  ],
  "distribution": {
    "darwin-aarch64": {
      "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip",
      "cmd": "./someagent",
      "args": ["acp"],
    },
    "darwin-x86_64": {
      "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip",
      "cmd": "./someagent",
      "args": ["acp"],
    },
    "linux-aarch64": {
      "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip",
      "cmd": "./someagent",
      "args": ["acp"],
    },
    "linux-x86_64": {
      "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip",
      "cmd": "./someagent",
      "args": ["acp"],
    },
    "windows-x86_64": {
      "archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip",
      "cmd": "./someagent.exe",
      "args": ["acp"],
      "env": {
        "SOMEAGENT_MODE_KEY": "",
      },
    },
  },
}
```

## 我们提议对此做什么

1. **清单规范**（上述）成为规范性的；我们发布 JSON Schema 和验证脚本，以便维护者可以在本地进行 lint 检查。
2. **注册表仓库** `github.com/agentclientprotocol/registry`：
   * 结构：`<id>/agent.json`，可选的 `icon.svg`（或主题特定变体的 `icon-light.svg` 和 `icon-dark.svg`），可选的 `README.md`。
   * 图标应为 SVG 格式以支持可伸缩性。如果提供主题特定图标，必须同时包含浅色和深色变体。
   * CI：验证清单，强制 slug 唯一性，检查资源大小，生成聚合产物。
3. **聚合输出**：
   * `registry.json`：所有代理的确定性列表，剥离 JSONC。
4. **分发和搜索**：
   * 客户端从固定的发布或 `https://agentclientprotocol.com/registry.json` 或 `https://registry.agentclientprotocol.com` 获取 `registry.json`。
   * 静态站点提供对功能、协议版本、部署、身份验证模型和标签的过滤。

## 美好的未来

* 代理维护者提交 PR 来更新他们的清单；CI 保持数据清洁。
* 编辑器/客户端可以通过获取一个 JSON 文件并在本地过滤来引导 ACP 支持。
* ACP 网站显示相同的数据供人类阅读，确保一致性。
* 协议版本不匹配立即可见；客户端可以警告或隐藏不兼容的代理。

## 实施细节和计划

**第 1 阶段——规范和仓库引导**

* 考虑身份验证选项。
* 最终确定 JSON Schema 和文档。
* 要求代理开发人员对规范提供反馈。
* 创建带有 CI（GitHub Actions）的注册表仓库，在 PR 上运行验证。
* 用一些参考代理种子化以证明工作流程。

## 修订历史

* 2025-11-28：初始草稿。
* 2025-12-16：次要更新。