agent-connector

agent-connector

将一个 MCP 部署到每个 Agent 宿主。

专注实现，而非分发。

使用 defineConnector() 一次编写服务和钩子，然后将其 install 到原生配置中——或将其 package 为真正的插件——覆盖检测到的每个 Agent 宿主：终端 CLI、IDE 扩展和桌面应用（Claude Code、Codex、Cursor、Copilot、Gemini、OpenCode、Warp、Zed 等）。

面向 Agent 的文档：llms.txt（路由图）· llms-full.txt（各宿主参考文档）· SKILL.md（Agent 技能）· 指南：发布 MCP 服务，让用户将其安装到每个 Agent 宿主。

数据一览。 所有数字均来自适配器注册表，或由每次运行时执行的测试测得；如果 README 与源码不一致，漂移测试会失败。

有适配器的 Agent 宿主	42 个——终端 CLI、IDE 扩展和桌面应用（覆盖情况）
每个宿主支持的界面	8 种——MCP 服务（41 个宿主）、记忆（41）、技能（36）、钩子（32）、命令（19）、子 Agent（16）、操作（9）、状态栏（4）
规范化的钩子事件	13 个，通过 3 种范式分发（json-stdio 覆盖 24 个宿主 · mcp-only 覆盖 10 个 · ts-plugin 覆盖 8 个）
生成的程序包格式	9 种宿主插件格式 + 2 种 MCP 标准制品（mcp-server-json、mcpb）
密钥后端	4 种——macOS Keychain、Linux Secret Service、Windows Credential Manager、可选的文件存储；stdio 服务 env 中的 ${secret:NAME} 永远不会进入宿主配置
OAuth 提供商预设	5 种——google、microsoft、github、bing-webmaster、posthog（另有通用预设）
已通过真实宿主二进制验证的宿主	42 个中有 29 个（其中 22 个通过模型工具调用端到端验证）；其余 13 个通过隔离 HOME 中的注册表安装测试框架验证
测得的占用	一个 135 行的 defineConnector() → 66 个宿主原生文件，覆盖 41 个宿主中的 6 种文件扩展名，安装在用户级作用域（项目级作用域为 63 个）——npm run measure:footprint
测试套件	174 个测试文件

适用对象。 agent-connector 面向 MCP 分发中的发布者：你已编写（或正在编写）MCP 服务，并希望通过自己的程序包 npx <your-package> install，让它自动安装到用户的 Agent 宿主中，同时提供钩子、技能和插件包。add-mcp 和 agent-install 等工具则面向最终用户：它们会将现有服务添加到一台机器上的各个 Agent 中。两者可以组合使用；agent-connector 是服务作者发布的工具。 **两类受众：**连接器开发者请从快速开始入手； 如果你已经在运行 Agent 宿主，只想查看令牌总量，可直接跳转到 usage。

• 快速开始 — 依赖 SDK、声明连接器并安装
• 发布 — 直接安装或发布为市场插件
• 一次性定义的内容 — 服务、钩子及其他界面
• 工作原理 — 单一主程序、按项目存储数据、钩子模式
• CLI — 快速了解所有命令
• 令牌遥测与用量 — 按工具遥测与无需连接器的 usage
• 发布到 MCP 生态系统 — 生成官方 MCP 标准制品
• 验证 — 如何证明平台覆盖契约

_{定义一次 → 作为自有品牌 CLI 发布 → 用户通过宿主的原生市场安装 → 用一条命令驱动所有 CLI。 重新生成此演示。}

快速开始

agent-connector 是一款供连接器开发者依赖的 SDK。将它添加到存放连接器的 软件包中，只需声明一次连接器，然后发布带有品牌标识的 MCP 软件包/可执行文件，例如 npx @acme/acme-db-mcp install — 它会部署到检测到的每个 Agent 宿主各自的原生 配置中。全局安装 @ken-jo/agent-connector 并非带有品牌标识的 MCP 生命周期路径；全局 CLI 指引仅适用于无需连接器的令牌用量报告。框架制品工具面向开发者，通常通过 npx @ken-jo/agent-connector ... --connector 运行。线性流程如下： 获取服务 → 声明服务 → 通过带有品牌标识的软件包安装。

0. 你需要先准备一个 MCP 服务文件。 以下配置指向 ./my-mcp-server.mjs，因此安装前该文件必须存在。还没有 MCP 服务？ 可将 examples/acme-db/acme-db-mcp-server.mjs （一个独立的约 35 行示例）复制为 ./my-mcp-server.mjs，或参阅 官方 MCP SDK 快速入门。

# 1. add agent-connector as a DEPENDENCY of your connector package
npm install @ken-jo/agent-connector

// 2. package.json — this is the user-facing package identity
{
  "name": "@acme/acme-db-mcp",
  "mcpName": "io.github.acme/acme-db",
  "bin": { "acme-db": "./bin.mjs" },
  "dependencies": { "@ken-jo/agent-connector": "^0.8.0" }
}

// 3. agent-connector.config.mjs — declare your server + hooks once
import { fileURLToPath } from "node:url";
import { defineConnector } from "@ken-jo/agent-connector/sdk";

const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

export default defineConnector({
  // package.json / npm metadata is the source of truth. The host alias/runtime
  // id and connector version are derived from name/mcpName/bin/version unless
  // you need a legacy or multi-instance alias. Host-native ids are generated
  // during install, so do not copy them back into defineConnector({ id }).
  server: {
    transport: "stdio",
    command: "node",
    args: [serverPath],
  },
  // hooks, telemetry, and more surfaces — see "What you define once" below
});

接线契约如下：

1. package.json 定义公开的产品标识（name、mcpName、bin、 version）。
2. bin.mjs 调用 createConnectorCli({ packageJson, connector })，确保所有 install/doctor/upgrade/uninstall 命令都使用开发者的品牌运行。
3. agent-connector.config.* 使用 defineConnector({ server, ...surfaces }) 描述实际的 MCP 启动方式或远程端点。
4. install 将这份声明渲染到每个检测到的宿主原生 MCP 配置中。对于 stdio 进程， 宿主会指向稳定的 agent-connector 主目录可执行文件，由它启动实际命令并测量 每种工具的流量。对于远程 HTTP 服务，在支持的情况下，宿主会收到对应的 URL；此时没有可封装的 stdio 进程。

命令边界

将两层命令分开：

层级	运行者	示例	用途
品牌 MCP 生命周期	MCP 包的用户	npx @acme/acme-db-mcp install、acme-db doctor --probe、acme-db upgrade、acme-db uninstall、acme-db telemetry report --by tool	安装、验证、更新、移除你的 MCP，并检查其遥测数据。
框架工具	MCP 包开发者	npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs	根据连接器配置生成宿主插件包和 MCP 分发产物。
无连接器的用户遥测	没有 MCP 包的 Agent-CLI 用户	npx @ken-jo/agent-connector usage report --by platform	以只读方式读取宿主 CLI 日志，统计整个对话的令牌总数。

如果命令用于操作编写完成后的 MCP，请优先使用品牌包／二进制文件。 如果命令用于构建框架分发产物，请使用框架 CLI。

MCP 服务启动示例

根据你要构建的 MCP 选择合适的 server 形式。封装包的标识仍来自 package.json；这些示例仅说明如何启动或连接实际的 MCP 服务。

形式	适用场景	最简启动命令
包运行器 MCP	MCP 以包的形式发布。	npx -y @acme/acme-db-mcp
本地服务进程 MCP	MCP 服务包含在你的包中。	node ./my-mcp-server.mjs
Python MCP	MCP 服务使用 Python 编写，且应在启动时解析运行时依赖。	uv run --with mcp ./my_mcp_server.py
基于 CLI 的 MCP	现有可执行文件提供 MCP 服务模式。	local-tools mcp serve
远程服务 MCP	MCP 托管在 HTTP 端点之后。	https://mcp.example.com/mcp

下面每个代码片段都是 defineConnector({ ... }) 的 server 字段；只有本地服务进程示例需要使用其中展示的 serverPath 辅助函数。

包运行器 MCP——应使用 npx 启动的已发布包：

server: {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@acme/acme-db-mcp"],
}

本地服务进程 MCP——打包的服务文件或二进制文件：

import { fileURLToPath } from "node:url";

const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

server: {
  transport: "stdio",
  command: "node",
  args: [serverPath],
}

Python MCP——通常通过 uv 运行，以便解析服务的依赖：

server: {
  transport: "stdio",
  command: "uv",
  args: ["run", "--with", "mcp", "./my_mcp_server.py"],
}

仅当运行时环境已由你的包或部署封装程序管理时，才直接使用 python ./my_mcp_server.py。

基于 CLI 的 MCP——现有可执行文件提供 MCP 模式：

server: {
  transport: "stdio",
  command: "local-tools",
  args: ["mcp", "serve"],
}

远程服务 MCP——托管的 MCP 端点：

server: {
  transport: "http",
  url: "https://mcp.example.com/mcp",
}

# 4. deploy under your branded MCP package/bin
npx @acme/acme-db-mcp detect            # which platforms are installed here?
npx @acme/acme-db-mcp audit             # catch package/bin/connector identity drift
npx @acme/acme-db-mcp install --dry-run # preview every change first
npx @acme/acme-db-mcp install           # write native config in each host

install 仅面向此机器上实际检测到的宿主（或显式指定的 --targets / connector.targets 列表），并与 /coverage 上显示的当前适配器注册表取交集——不存在“无条件安装到所有宿主”的方式。 @ken-jo/agent-connector 是底层框架依赖；请将其直接用于框架打包／调试，或无连接器的令牌遥测，不要将其作为面向用户的主要安装品牌。

发布：直接安装或市场插件

同一份定义，分发方式由你选择。

直接安装——你的品牌命令（acme-db install、npx @acme/acme-db-mcp install）会就地写入各宿主的原生 MCP、钩子和内容界面配置，无需向各平台市场单独提交或接受审核。这就是上文的快速入门方式。

在测试分发接入时，框架备用方案也可以直接安装连接器源：github:owner/repo、npm:@scope/package@version，或 archive: / 直接使用 .tgz / .zip 源。所有获取的源都会缓存到 ~/.agent-connector/sources/，且必须包含 agent-connector.config.*。 市场插件 — 框架的 package 命令可将连接器转换为真正的插件/扩展包（清单 + 捆绑的命令、Agent、技能、钩子、MCP），并以一个定义为准。这是框架工具，因此请使用 npx @ken-jo/agent-connector package --connector ... 运行。如果你已在全局安装框架 CLI，agent-connector package --connector ... 只是更简短的等效命令。钩子 + MCP 会保留遥测服务包装器，因此通过市场安装的连接器仍会报告其 stdio 服务的每个工具令牌用量。--format all 会生成 9 种主机格式——可移植、厂商中立的 Agent Plugins 1.0.0 包（默认），以及面向不支持该规范的主机的 8 种原生包：

格式	主机
agent-plugin	Agent Plugins 1.0.0（默认 — 一个包，单一事实来源）：Codex · GitHub Copilot CLI · VS Code / JetBrains Copilot · Kiro · Hermes · Cursor · OpenClaw · …
claude-plugin	Claude Code · OpenClaw · OMP
factory-plugin	Droid
gemini-extension	Gemini CLI
qwen-extension	Qwen Code
agy-plugin	Antigravity（CLI + IDE）
cursor-plugin	Cursor
kimi-plugin	Kimi CLI
npm-plugin	OpenCode · Kilo CLI · Pi

agent-plugin 是所有支持该规范的主机的单一事实来源。 它遵循开源的 Agent Plugins 规范 （由 Vercel 主导，与 AWS、Cursor、GitHub、Microsoft 和 OpenAI 共同维护）：包含根目录 plugin.json、mcp.json（stdio 和远程 streamable-http/sse 服务）以及任何兼容客户端都可安装的 skills/。钩子、斜杠 命令和子 Agent 不是可移植的 v1 组件，因此该包会按客户端扩展命名空间分别携带它们——com.github.copilot/（Copilot CLI、VS Code、JetBrains）和 com.openai/（Codex，通过清单的 extensions 区块接入）；客户端会忽略不属于自己的命名空间。Codex 和 GitHub Copilot CLI 的 install --method marketplace 驱动会 原样部署此包（已在 codex 0.149 + Copilot CLI 1.0.80 上实时验证），而 VS Code 会自动发现 CLI 安装的内容。规范禁止使用绝对 命令路径，因此该包会附带一个小型 bin/agent-connector.mjs 启动器， 在运行时解析运行环境（二进制文件所在的 home 目录 → PATH → npx）；无需全局 安装即可保留遥测数据。已弃用的 codex-plugin / copilot-plugin 名称仍可解析并生成此包。

两种官方 MCP 标准制品为可选项（它们需要 publish 区块，因此不会包含在 --format all 中）——mcp-server-json（MCP Registry 的 server.json）和 mcpb（一键安装的 MCPB 包）；请参阅 发布到 MCP 生态系统。

# emit every host format (mcp-server-json + mcpb are opt-in by name)
npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin
npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format gemini-extension --out ./ext   # or just one

# if you already keep the framework CLI globally installed, the same command is:
agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin

# e.g. Claude Code:  /plugin marketplace add ./dist-plugin/claude-plugin
#                    /plugin install <connector-id>@agent-connector
# e.g. Gemini CLI:   gemini extensions install ./dist-plugin/gemini-extension/<id>

嵌入路径注意事项。 大多数主机包会写入运行 package 的机器所用的绝对 home-bin 启动器路径，因此它们适用于在同一台机器/同一 home 目录上进行 本地安装。若要分发给多台机器，请使用 agent-plugin、npm-plugin 或 MCP 标准制品，或者在每台机器上重新运行 package。

让带有你品牌标识的 MCP 包驱动主机自身的安装流程，使用 install --method marketplace：

acme-db install --method marketplace

# framework fallback for local framework development/debugging only
npx @ken-jo/agent-connector install --method marketplace --connector ./agent-connector.config.mjs

• 功能 — 暂存软件包，在主机支持的情况下注册本地市场，然后运行主机的插件安装命令（对于 npm 插件主机，则写入本地 file:// 条目）；支持无头运行且具备幂等性。其他采用市场格式的主机会输出准确的手动命令。
• 主机支持情况 — 已在 Linux、Windows 和 macOS 上对 Claude Code、Codex、OpenCode、Kilo（CLI + ext）和 Antigravity（CLI + IDE）进行实时验证；Droid 和 Qwen Code 已随附驱动程序，但尚待在真实主机上验证；Gemini CLI 已弃用（正逐步转向 Antigravity——保留驱动程序以兼容现有安装）。
• 安全与回滚 — 若尝试通过两种方法安装同一连接器，安全检查会拒绝安装；uninstall --method auto 会撤销当前安装的方法；doctor 会检查注册信息是否存在偏差。

发布品牌化 CLI

连接器开发者可以发布自己的可执行文件，让用户无需输入 agent-connector。createConnectorCli({ packageJson, connector })（来自 @ken-jo/agent-connector/cli 导出）会从 package.json 获取可执行文件名称和版本，并以你的品牌提供所有子命令，完全委托执行并自动限定作用域至你的连接器——因此，用户无需全局安装框架，也无需在品牌化 MCP 安装、诊断或卸载命令中使用 --connector。完整且可运行的软件包示例见 examples/branded-cli。

#!/usr/bin/env node
// bin.mjs — every agent-connector subcommand, branded as `acme-db`
import { createConnectorCli } from "@ken-jo/agent-connector/cli";

// run() resolves to the exit code and never calls process.exit
process.exitCode = await createConnectorCli({
  // packageJson supplies public identity: name, mcpName, bin, version.
  packageJson: new URL("./package.json", import.meta.url),
  // connector supplies behavior: server, hooks, skills, telemetry.
  // These are two layers, not duplicate id/display-name inputs.
  connector: new URL("./agent-connector.config.mjs", import.meta.url),
}).run();

用户安装你的软件包后，acme-db 可执行文件就会出现在其 PATH 中，且每条命令都会限定至你的连接器（acme-db install ≈ agent-connector install --connector ./agent-connector.config.mjs）。自动限定作用域只是对同一个主目录二进制文件进行参数注入；serve 和 hook 仍会通过唯一的 ~/.agent-connector 主目录二进制文件执行，所有主机配置都会指向该文件。显式指定的 --connector / --connector-id 始终会覆盖注入的默认值。

只需定义一次的内容

单个 defineConnector({...}) 声明你的 MCP 服务及生命周期钩子，还可以选择定义其他界面——命令、技能、子 Agent、记忆、状态栏、操作，以及主机原生扩展接口。agent-connector 会将每种界面渲染为所有已检测主机的原生格式；若主机不支持，则会跳过并发出警告（绝不会静默丢弃）。

import { fileURLToPath } from "node:url";
import { defineConnector } from "@ken-jo/agent-connector/sdk";

// Resolve your server to an absolute path — host CLIs spawn it from their own CWD.
const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

export default defineConnector({
  server: {
    transport: "stdio",
    command: "node",           // or "npx", "python", etc. — whatever starts your server
    args: [serverPath],        // replace with your real server entrypoint
    env: { ACME_DB_DSN: "${env:ACME_DB_DSN}" },
  },
  hooks: {
    PreToolUse: {
      matcher: "acme_write",
      async handler(evt) {
        return evt.toolName === "acme_write"
          ? { decision: "ask", reason: "Confirm write" }
          : { decision: "allow" };
      },
    },
  },
  // telemetry is on by default
});

npx @acme/acme-db-mcp install 会将其转换为例如：

主机	写入内容
Claude Code	~/.claude.json → mcpServers.acme-db（以及写入 ~/.claude/settings.json 的钩子）
Codex CLI	~/.codex/config.toml → [mcp_servers.acme-db]（以及 ~/.codex/hooks.json）
Cursor	~/.cursor/mcp.json → mcpServers.acme-db（以及 ~/.cursor/hooks.json）

……每项配置中的钩子都指向同一个稳定的主目录二进制文件，因此一次更新即可在所有地方生效。

密钥环境变量引用（${env:VAR}）。 在 command / args / env / url / headers 的任意位置写入 "${env:VAR}"（或 "${env:VAR:-default}"），即可引用环境变量。

原生插值与安装时解析为字面值

对于支持原生插值的主机（Claude Code、Cursor、VS Code Copilot、 amp、codebuff），令牌会原样写入主机配置，并在运行时解析。其他主机均不支持原生插值，因此会在安装时将值解析为字面值；如果变量未设置且没有默认值，则会解析为空字符串；对于会解析为字面值的主机，install 会针对这种情况发出 warn。

**OS 密钥库密钥（`${secret:NAME}`）。** 在 stdio 服务的 `env` 中将 `"${secret:NAME}"` 写为值（基础 `server.env` 或 `platforms[].server.env` 覆盖项），即可引用用户通过 `secrets set NAME` 保存一次的密钥。该值绝不会进入主机配置：主机只会看到 `serve` 包装器的 `--secret-env NAME={secret:NAME}` 占位符（主机不会展开这种形式），而启动时，包装器会读取 OS 密钥库并将该值注入服务自身的环境变量中。引用的名称尚未设置（或读取结果为空）时，会中止启动并提示使用 `secrets set`，而不是以空值启动服务；引用周围文本中的 `${env:VAR}` 会在启动时由包装器展开，密钥值则不会；`install` 会针对每个缺失的名称发出警告，`doctor` 会报告 `: secrets` 检查。`${secret:…}` 在其他任何位置（`command` / `args` / `url` / `headers`、远程服务）都会被拒绝；名称必须匹配 `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`，值必须是非空字符串且长度不超过 8192 个字符，并且不支持 `:-default` 形式。

后端	OS	值的存储位置	说明
keychain	macOS	通过 /usr/bin/security 存储在登录钥匙串中：服务为 agent-connector/<connector-id>，账户为 <NAME>	锁定的钥匙串需要 GUI 会话（钥匙串访问或桌面登录）；agent-connector 不会替你运行 unlock-keychain。
secret-service	Linux	通过 secret-tool 存储在 freedesktop Secret Service（GNOME Keyring 及兼容守护进程）中	需要 D-Bus 和正在运行的守护进程；缺少其中任一项时，secrets check 会说明原因并提示使用 --backend file。
credential-manager	Windows	通过 PowerShell 存储在 Credential Manager 中：目标为 agent-connector/<connector-id>/<NAME>	受 OS 数据块限制，值最多为 2560 字节（1280 个 UTF-16 字符）。
file	任意	~/.agent-connector/secrets/file-store.json（目录权限为 0700，文件权限为 0600）	须主动选择，且为明文，未加密（--backend file 或 AGENT_CONNECTOR_SECRETS_BACKEND=file）：适用于没有密钥库的 CI 机器和无头主机。

除非 --backend 或 AGENT_CONNECTOR_SECRETS_BACKEND（keychain|secret-service|credential-manager|file|auto）另有指定，secrets set 会写入 OS 原生后端；每个名称所用的后端会记录在 ~/.agent-connector/secrets/<connector-id>.index.json 中（仅记录名称，绝不记录值），读取时会遵循该记录。值通过隐藏提示词或 --stdin 提供（没有 --value 标志，因此不会进入 shell 历史记录或进程列表），并且任何命令都不会打印值。 OAuth 登录（oauth.<key>）。 与 OAuth 2.0 API 通信的服务会在 oauth.<key> 下声明提供方——oauth: { google: { provider: "google", clientId: "1234-abcd.apps.googleusercontent.com", clientSecret: "${secret:google-client-secret}", scopes: ["https://www.googleapis.com/auth/webmasters.readonly"] } }——用户只需通过 auth login <key> 授权一次：可以使用浏览器本地回环流程（PKCE S256，在 127.0.0.1 上启动一个仅接受一次请求的监听器）；如果无法打开浏览器，且预设支持设备码，则会提示使用设备码。刷新令牌会以 oauth.<key>.refresh-token 为键，存储在连接器的操作系统密钥库命名空间中（与 secrets set 写入的存储相同），服务则通过从 SDK 调用 getAccessToken({ connectorId, key }) 来获取访问令牌：该方法会刷新令牌，在进程内存中缓存访问令牌，直到令牌过期前 60 秒，并存储轮换后的刷新令牌。延迟登录：如果没有已存储的登录信息，调用会在可以打开浏览器时自行执行登录；否则会安全地拒绝操作，并显示完整的 auth login 命令。因此，即使作为主机插件安装的连接器（未运行 install），也会在首次调用工具时登录。访问令牌仅保存在进程内存中，也只会输出到 auth token <key> 的 stdout；其他任何地方都不会打印令牌、授权码或客户端密钥，主机配置、软件包清单和非敏感元数据文件 ~/.agent-connector/oauth/<connector-id>.json 中也绝不会包含这些信息。install 会逐项警告缺失的登录信息，doctor 会报告 <id>: logins 检查项（两者都不会联网）。预设仅提供端点、参数和特殊行为——agent-connector 不附带客户端 ID：作者需向各提供方注册应用，或者让每位用户自行注册。开发者提供的配置：不带密钥的字面量 clientId（公共客户端）、仅用于 google 的字面量 clientSecret（Google 文档说明，已安装应用的客户端密钥不属于机密），或 tokenExchangeUrl——由开发者自行运营的 https 令牌交换服务，该服务持有客户端密钥，并将每个令牌请求转发给提供方（连接器会发送 client_id，绝不发送密钥；线协议约定见 llms-full.txt §2.2）；对于其他所有预设，clientSecret 必须是 ${secret:NAME} 引用。用户自行注册的配置：clientId: "${secret:NAME}" 和 clientSecret: "${secret:NAME}"——每位用户注册自己的应用，并通过 secrets set 存储这两项；install、doctor 和 auth login 会指出仍需运行的 secrets set 命令。${env:VAR} 客户端 ID 会在登录和刷新令牌时从进程环境中展开，但由主机启动的服务无法读取该变量（不会继承 shell 导出的环境变量）。examples/seo-connector 是一个可运行的三登录服务（Google Search Console、Bing Webmaster Tools、PostHog），展示了全部三种方式，并附带令牌交换服务示例；各提供方的注册表见 Operate guide。

预设	提供商	流程	备注
google	Google APIs（OAuth 2.0 / OpenID Connect）	loopback	添加 access_type=offline 和 prompt=consent，以便返回刷新令牌。flow: "auto" 绝不会回退到设备授权（Google 的有限输入授权不包含 Search Console 等 API 范围）；显式设置 flow: "device" 仍会运行该流程。接受字面值 clientSecret（Google 文档说明它不属于机密信息）。
microsoft	Microsoft identity platform（Entra ID 和个人账户）	loopback, device	options.tenant 用于选择租户（默认值为 common）；需请求 offline_access 范围，否则不会返回刷新令牌。公共客户端——仅需 clientId。
github	GitHub Apps 和 OAuth Apps	loopback, device	刷新令牌需要启用过期用户令牌（在应用设置中配置）或请求 offline_access 范围；否则登录会报告未返回刷新令牌。浏览器流程需要密钥：${secret:…}（用户注册）或 tokenExchangeUrl；设备流程不需要密钥。
bing-webmaster	Bing Webmaster Tools	loopback	重定向 URI 必须完全匹配（包括端口），因此请将 redirectPort 设为固定端口。Bing 的注册表单会拒绝点号后没有字母的重定向 URI（127.0.0.1 和 localhost 都无法通过检查），因此请将 redirectPath 设为带点号的路径，例如 /callback.html；不支持 PKCE，且文档所述的响应不包含 state（登录仅通过固定重定向 URI 绑定，因此必须设置 redirectPort）。需要密钥：${secret:…}（用户注册）或 tokenExchangeUrl。
posthog	PostHog	loopback	clientId 是应用的 Client ID 元数据文档的 URL，其中将 http://127.0.0.1/callback（不含端口）列为重定向 URI；使用 PKCE，不需要客户端密钥。options.region 可指定 us 或 eu；省略时，不区分区域的 issuer 会路由到正确的云端。仅需 clientId。
generic	任意 RFC 8414 / OpenID Connect 提供商	loopback, device	使用 issuer 进行发现，或显式指定 authorizationEndpoint + tokenEndpoint；设备流程需要 deviceAuthorizationEndpoint（可显式声明或通过发现获取）。按提供商要求提供密钥：无需密钥、${secret:…}（用户注册）或 tokenExchangeUrl。

原生钩子扩展选项。 规范化的 hooks API 涵盖 13 个跨平台事件；对于仅限宿主的事件（仅 Claude Code 就提供 30 个），可声明 platforms: { "claude-code": { nativeHooks: { TaskCompleted: { handler } } } }。

原始负载语义与约 14 个透传宿主

处理程序接收宿主的原始负载，其返回值会作为原样 JSON 回复 返回（仅支持退出码 0——不支持退出码 2 的阻止操作）。支持宿主原生透传的宿主： amp、claude-code、continue、copilot-cli、cursor、gemini-cli、hermes、jetbrains-copilot、kimi、 nemoclaw、omp、openclaw、opencode、qwen-code。其他宿主会跳过并发出警告。

宿主配置键补丁。 对于其他界面无法触及的宿主专属设置键，可声明 platforms: { "claude-code": { configPatch: [{ key, value, reason }] } }（目前仅适用于 Claude Code；其他宿主会跳过并发出警告，并提供准确的手动编辑说明）。

仅在缺失时设置 + 引用计数 + 拒绝名单语义

语义固定为：仅在缺失时设置 + 任何冲突都跳过并发出警告——绝不 覆盖，绝不深度合并。所有权通过持久化账本进行引用计数； 安全相关的键，以及 Agent Connector 模型视为一等界面的键，都会被明确拒绝。

### Memory、状态栏、操作和 SDK

• memory（与 AGENTS.md 标准保持一致）——将长期指导写入各宿主实际读取的记忆／规则文件。 采用 AGENTS.md 的宿主会使用标准文件；Claude Code → CLAUDE.md、Gemini CLI → GEMINI.md 等宿主特定例外，则依据各自的官方文档接入。写入采用精确的标记围栏和哈希戳管理区块——多个连接器可以共存，标记之外的字节绝不会被触碰，卸载时会精确移除对应区块。
• statusline（defineStatusline）——实时 HUD 渲染函数，宿主每次刷新状态时都会调用。SDK 支持顶层和按宿主配置的 render(ctx) 处理程序，以及 refreshInterval、respectUserColors、hideContextIndicator 和由框架强制执行的 maxLines 等 options。目前，它会为 Claude Code、Qwen Code 和 Antigravity CLI 注册由命令驱动的状态栏（仅在不存在时设置、引用计数、可撤销）；状态栏仅提供内置预设、而非由连接器拥有的命令的宿主仍会跳过并发出警告。运行时采用故障安全机制：发生任何错误时都会以代码 0 退出并输出空 stdout，确保 HUD 不会卡住宿主。
• actions（defineAction）——通过通用命令 agent-connector action <platform> <id> --connector <id> 调度的、可由用户调用的命名操作。操作可以声明 label、icon、placement、confirm，并可按宿主覆盖面向用户的元数据或 run(ctx)。install 会在 droid、hermes、kiro、nemoclaw、omp、openclaw、pi、warp 和 zed 上提供宿主端调用入口；适配器能力会说明该入口属于 exec 命令、exec 文件、手动 hook 面板、粘贴工作流、插件命令还是任务。其他宿主会跳过并发出警告。错误语义适用于用户触发的操作（未知 ID 或抛出异常时以代码 1 退出）。
• Connector SDK（@ken-jo/agent-connector/sdk、/sdk/test）——统一的创作接口重新导出了 defineConnector、完整的 define* 系列（defineHook、defineCommand、defineSkill、defineSubagent、defineMemory、defineStatusline、defineAction、defineConfigPatch、defineNativeHook）、内省辅助函数（hostsSupporting、capabilitiesOf、surfaceSupport），以及离线测试工具（simulate、explain、explainHooks）。它会运行真实的适配器解析→处理程序→格式化链路，让你在接触真实宿主之前就能回答“我的处理程序在宿主 X 上确实能正常工作吗？”面向 Agent 的指导内容特意拆分为一个精简的路由技能，以及 skills/agent-connector/references 下的专题参考文档。请参阅 docs/ARCHITECTURE.md。

工作原理

• 位于主目录的单一二进制文件。 运行时只需安装一次，位置在 ~/.agent-connector（可通过 AGENT_CONNECTOR_DATA_DIR 覆盖）。我们写入的每份宿主配置都只是指向该二进制文件的轻量引用。更新由用户明确发起并管理（agent-connector upgrade），绝不会静默自动更新。
• 保留各项目数据。 遥测数据／状态按稳定的项目标识（Git 远程地址或规范化路径）进行键控，按项目分区，并存储在主目录数据根目录下——即使运行 git clean 也会保留，并可供打开同一项目的不同宿主共享。
• 原生配置保持原样。 我们绝不迁移宿主自身的设置文件；只有框架所有的状态会存放在数据根目录下。
• 优先确保 Windows 正确运行。 不使用符号链接，也不作仅适用于 POSIX 的假设。

三种 Hook 范式，均已在已注册平台集中验证安装（参见 /coverage 和 docs/ARCHITECTURE.md）：

范式	平台
json-stdio（完整 Hook 分发）	CodeBuddy · Claude Code · Codex CLI · Cursor · VS Code Copilot · JetBrains Copilot · GitHub Copilot CLI · Gemini CLI · Qwen CLI · Kiro · Kimi CLI · Crush · Goose · Hermes · Droid (Factory) · OpenHands · Antigravity · Antigravity CLI · Continue · Amazon Q · Grok Build · Grok CLI · Devin CLI · Open Interpreter
mcp-only（仅注册 MCP）	Warp · Cline · Trae · Zed · Freebuff · Xum · Pi · Windsurf · Junie · Mistral Vibe
ts-plugin（生成的桥接模块）	OpenCode · MiMoCode · Kilo CLI · Kilo · OMP · NemoClaw · OpenClaw · Amp

添加平台 = 一条注册表条目 + 一个适配器。

CLI

命令	用途
detect	列出已安装的平台、范围、能力和钩子范式。
install [<source>] [--scope …] [--targets …] [--method …] [--dry-run] [--force]	渲染并写入 MCP、钩子和内容界面。<source> 可以是本地路径、GitHub/git、npm:<package>[@version] 或 .tgz/.zip/archive:。
uninstall [--targets …] [--purge] [--method …]	完全撤销——移除写入的所有内容；--purge 还会清除框架状态。
upgrade [--channel …]	重新渲染宿主配置、修复过时的指针并刷新主目录中的二进制文件（别名：update、sync）；清除所有 doctor 版本警告；绝不会静默自我更新。
doctor [--probe] [--heal] [--explain] [--json] [--dry-run]	按平台执行健康检查并提供修复方案，同时检查版本：将主目录中目标安装的版本以及每个连接器的渲染框架版本与正在运行的 CLI 进行比较（不一致 → 警告并建议运行 upgrade）。--probe 会执行实时 MCP 握手，--heal 会重新同步所有可修复的问题，--explain 会打印按 (host, event) 区分的钩子执行情况矩阵。
status	查看简要安装状态：哪些宿主上存在连接器（始终以 0 退出）。
secrets set|delete|list|check [<name>] [--backend keychain|secret-service|credential-manager|file] [--stdin] [--json]	将连接器以 ${secret:NAME} 引用的密钥存储到操作系统密钥库中：macOS Keychain（keychain）、Linux Secret Service（secret-service）、Windows Credential Manager（credential-manager），或选择启用的明文 file 存储。set 从隐藏提示或 --stdin 读取值（没有 --value 标志），list 显示名称、后端和是否存在，check 执行往返自检；绝不会打印任何值。
auth login|status|logout|token [<key>] [--device|--loopback] [--port <n>] [--json]	登录连接器在 oauth.<key> 下声明的 OAuth 2.0 提供方（预设：google、microsoft、github、bing-webmaster、posthog、generic）。login 会执行浏览器回环或设备码流程，并将刷新令牌存储到操作系统密钥库；status 显示键、提供方和是否存在（缺少登录信息不会导致失败）；logout 会在可行时向提供方撤销令牌并删除令牌；token 将新的访问令牌打印到标准输出——这是唯一会打印访问令牌的命令。
package [--format <fmt>|all]	生成宿主插件包，或生成 OFFICIAL 标准制品：mcp-server-json（注册表）· mcpb（一键安装包）。
audit [--strict]	安装前检查包身份：包名称/版本/bin、运行时依赖、连接器 ID/版本不一致，以及发布 files 覆盖范围。
action <platform> <id> [--connector <id>]	从 Shell 运行已声明的操作。
telemetry report [--by …] [--since …] [--connector <id>]	统计你自己的连接器所封装服务中每个工具的令牌占用量。仅适用于 Stdio 服务。
telemetry export [--format …] [--connector <id>]	导出你所封装服务的原始汇总记录。
usage report|export|leaderboard [--by …]	无需连接器。 以只读方式从各 Agent CLI 自身的日志中解析宿主原生的整段对话令牌总量。不会按单个 MCP 或工具细分。
leaderboard [--since …] [--connector <id>] [--scope …]	三种标注来源的排行榜，所需条件各不相同（🔌 MCP/插件 · 🛰️ 宿主原生轮次 · 🖥️ 宿主/用户）；不会对它们的计数求和。

hook 和 serve 也存在——它们是内部入口点，已写入的宿主配置会指向它们；请勿手动运行。完整的标志参考请见 文档网站 /docs/dev/cli · llms-full.txt §3（权威版本，由测试防止内容偏移）。

遇到问题？文档网站 /docs/dev/troubleshooting 页面介绍了如何读取 doctor 的输出及其退出代码、常见的 ConnectorConfigError 消息、仅支持 MCP 的宿主上出现“此处无法使用 hooks”的原因，以及 telemetry report 可能显示为空的原因。

Token 遥测与用量

两种彼此独立、绝不相加的 Token 成本视图：

• 针对你自己的服务的逐工具遥测（面向 MCP 开发者）。宿主不会向 MCP 服务报告逐工具用量，因此 agent-connector 会测量你自己的服务的字节数（传入的参数、传出的结果、工具架构），并在本地进行 Token 化——仅记录汇总计数，存储在本地，默认零外传。 逐工具遥测对 stdio 服务会自动启用；远程（http/sse/ws）服务会注册，但不会被包装（代理无法拦截远程传输）。使用 agent-connector telemetry report --by tool 查看。

• 无需 Connector 的用量（agent-connector usage）。已经在使用 Claude Code / Codex / Cursor，只想查看总量？usage 以只读方式读取本地 Agent CLI 会话日志，且绝不写入任何宿主配置——无需 Connector，也无需安装：

  npx @ken-jo/agent-connector usage report --by platform        # CLI/model/project/session/day
  npx @ken-jo/agent-connector usage leaderboard --by platform   # or --by model
  npx @ken-jo/agent-connector usage export --format csv --out usage.csv
  

  它会按 Agent 宿主 / 模型 / 项目 / 会话 / 天报告整个对话的总量。它不会按单个 MCP 服务或工具细分成本——Agent 宿主不会记录逐工具归因。

隐私与分词器。 默认分词器为 gpt-tokenizer（纯 JS，无需原生构建）——OpenAI/Codex 系列使用 o200k_base，Anthropic 使用有文档说明的近似算法；如果无法加载，则回退到 chars/4 启发式算法。每条记录都带有置信度标签。原始工具参数和结果绝不会被存储或传输。关闭方式：AGENT_CONNECTOR_TELEMETRY=0，或设置 telemetry: { enabled: false }。

发布到 MCP 生态

如果 MCP 标准已涵盖你服务的功能，agent-connector 会严格生成标准内容，让你已按标准完成的工作具备可移植性：

• package --format mcp-server-json → 官方 MCP Registry 的 server.json（架构 2025-12-11）。它描述的是你的实际上游服务（Registry 安装程序运行的服务），而非我们的遥测包装器。使用官方 mcp-publisher CLI 发布。
• package --format mcpb → 官方 MCPB（.mcpb，前身为 DXT）捆绑包的 manifest.json（manifest_version 0.3），可在 Claude Desktop 和任何 MCPB 宿主中一键本地安装，并通过宿主密钥链管理密钥（user_config）。

这两种格式都会读取 Connector 中的 publish 区块（你拥有的命名空间 + 已发布的包 + 作者）：

defineConnector({
  server: { transport: "stdio", command: "npx", args: ["-y", "@acme/acme-db-mcp"] },
  publish: {
    registryNamespace: "io.github.acme", // a namespace YOU proved ownership of
    packageName: "@acme/acme-db-mcp",     // your REAL published package
    author: { name: "Acme Inc" },
  },
});

我们写入的配置就是标准。 install 会以事实上的规范 mcpServers 格式写入每个宿主的原生 MCP 配置——stdio 使用 { command, args, env }，远程使用 { url, headers }。可流式传输的 HTTP 在规范中的传输标识为 streamable-http（Registry 的 server.json）；宿主配置通常使用 http。WebSocket（ws）不是 MCP 规范中的传输方式，标准制品会拒绝它。

按传输方式实现向前兼容。 serve 代理是字节透明的：它会原样转发每条 JSON-RPC 消息，只复制一份来统计 tools/call 往返。因此，较新的 MCP 功能可以不受影响地通过——包括 MCP Apps（官方 io.modelcontextprotocol/ui 扩展）和在 initialize 阶段协商的任意反向 DNS 扩展。Connector 所连接的服务只要已支持这些功能，就能部署到所有宿主，并保留当前的遥测能力，无需更改 agent-connector。

验证

完整的单 API 契约已通过已提交的注册表驱动安装往返测试工具，在当前平台注册表中通过安装验证。该工具会为每个适配器在隔离的 HOME 中执行真实的安装 → 卸载，并断言磁盘上的文件位置正确且没有残留。另有一个已提交的 scripts/verify-host.mjs 驱动程序，会从验证矩阵中安装真实的主机 CLI，并检查安装 → 文件位置 → 干净卸载；对于可在无头模式下运行的主机，我们会使用真实模型或已提交的本地模拟模型提供程序（scripts/README.md）端到端验证实时钩子分发和遥测。没有无头 CLI 的 IDE 扩展／GUI 编辑器则由安装往返测试工具覆盖。

实测占用。 可运行示例（examples/acme-db，共 135 行，通过 defineConnector() 声明了一个 MCP 服务、PreToolUse + SessionStart 钩子、一条状态行和一个操作）会通过自己的 bin 安装到隔离的 HOME 中，每个已注册主机各安装一次，并统计该磁盘上出现的文件——数字见上文的数据一览。每个主机都会在用户级或项目级作用域安装此示例。tests/docs/readme-footprint.test.ts 会在每次运行时测量占用；如果 README 中引用的数据不一致，测试就会失败；npm run measure:footprint 会输出相同的 JSON。

开发

npm install
npm run typecheck
npm run build
npm run dev -- detect     # run the CLI from source via tsx

# Tests: scope + single-fork (useful on low-RAM machines).
npm run test:single -- tests/adapters/<host>.test.ts

贡献

欢迎提交 PR，尤其是新增主机适配器，以及根据主机主要来源验证过的修复。请参阅 CONTRIBUTING.md，了解开发工作流、单分叉测试规范、适配器的先验证规则，以及新增主机检查清单。希望支持新的 Agent 主机？请提交主机适配器请求。

安全问题报告：请参阅 SECURITY.md。

许可证

Apache-2.0 © 2026 KenJo