Skip to main content

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.

作者： @ignatov 支持者： @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（环境变量对象）。
示例框架： 
{
  "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：次要更新。