# 让编程智能体调用这些命令


> 执行前先查[操作开放范围与兼容性](/zh/api/compatibility)。

`hbd --help --json` 里列出了 `hbd mcp serve` 的版本，可以把自己的命令交给同一台电脑上的智能体客户端，例如 Claude Code 或 Codex。客户端自己启动 `hbd mcp serve --stdio`，通过标准输入和标准输出与它通信，所以没有要连接的服务地址。Humanbased 不运行托管的 MCP 服务。

| 作用 | 命令 | 所需权限 |
| --- | --- | --- |
| 把这个版本的命令提供给本机的智能体客户端 | `hbd mcp serve --stdio` | — |

每条命令对应一个工具，工具名就是命令名，空格换成下划线：`campaign_list` 运行 `hbd campaign list`，`campaign_versions_inspect` 运行 `hbd campaign version show`。工具的参数就是这条命令自己的参数，名字不变，例如 `campaign-id`、`limit`、`idempotency-key`；返回的是 `--json` 打印的同一个信封。只有命令成功时，其中的 `error` 才是 `null`。

需要人亲自完成的命令不提供：登录和退出登录、撤销会话、执行已确认的发布。

## 接入客户端

每次调用使用的凭证，和你在终端运行同一条命令时一样：服务进程的环境里设了 `HB_API_KEY` 就用它，否则用 `hbd auth login` 为服务所用 profile 保存的会话。启动 `hbd mcp serve` 时给的 `--profile` 和 `--timeout` 对每次调用都生效。

Claude Code：

```sh
claude mcp add --transport stdio humanbased -- humanbased mcp serve --stdio
claude mcp get humanbased
```

Codex，写在 `~/.codex/config.toml`：

```toml
[mcp_servers.humanbased]
command = "humanbased"
args = ["mcp", "serve", "--stdio"]
default_tools_approval_mode = "writes"
```

## 确认会改动什么

标为只读的工具不改动服务器上的任何东西。其余工具会改动活动、发布提案、模板、提交的结论、Academy 课程草稿或对贡献者答案的打分、上传的文件，或本机的 profile。对它们的每次调用，Claude Code 都会先问你，即使它的权限模式原本会直接放行；Academy 课程命令、`files upload` 和 `campaign input import` 除外。智能体可以不问你就编写课程草稿、提交审核、给开放题打分、上传图片，或把本组织的数据集导入活动（经 MCP 只能导入草稿或暂停中的活动，运行中的活动由人在终端导入），所以对这几个命令，Claude Code 只在它自己的权限设置要求时才先问。设了 `default_tools_approval_mode = "writes"` 时，Codex 会在每个没标只读的工具运行前询问，这几个也一样。

已保存的 CLI 会话在登录时批准的组织内写入，无需再传 `--org`。使用 API Key 时，启动服务要加 `--org <组织 id>`、设置 `HB_ORG`，或在每次写操作中传 `org`。显式指定的组织与凭证不符时，写操作以 `ORG_MISMATCH` 被拒绝，请求不会发出。

## 文件、路径与等待

通过 MCP 运行时，`campaign init`、`template init` 和 `campaign plan` 不写文件：本该写出的文档放在 `data.artifact` 里返回。把它保存到你想要的位置，再把路径作为 `file` 传给 `campaign validate`，或作为 `plan` 传给 `campaign apply`。其他命令的 `--out` 原本会写出的内容，已经在 `data` 里。

标准输入用来传协议，所以文件参数写 `-` 会被拒绝，要给路径。相对路径从客户端启动服务时所在的目录算起。

通过 MCP 运行时，`files upload` 只收图片（PNG、JPEG、WebP、GIF、HEIC、HEIF、AVIF、TIFF 或 BMP），按文件开头的字节判断，不看文件名。其他文件在读其余部分、发出任何请求之前就会被拒绝。以 `campaign` 或 `cover` 类别上传的文件是公开的，拿到地址的人都能读。

`campaign records pull` 每次调用返回一页，内容就是命令自己输出的 JSON 文本，记录里的数字一位不差。读下一页时，把 `data.next_cursor` 作为 `cursor`、`data.subscription_id` 作为 `subscription` 传回去。要一次导出全部记录，在终端运行这条命令并加 `--all`。

服务一次只处理一个调用。任何调用等待服务端任务都不超过 45 秒，所以能在 Codex 默认给工具调用的 60 秒内返回（可用 `tool_timeout_sec` 调大）。

`dsa_consult` 在 DSA 受理问题后立即返回，运行 ID 在 `data.run_id` 里。之后用带 `wait` 的 `dsa_run` 跟进这次运行，每次最多跟进 45 秒。到时运行还没结束的话，返回的不是错误：`data.status` 是 `queued` 或 `running`，`data.cursor` 标出看到了哪里，附注里写明下一次调用，即把 `after` 设为 `data.cursor` 再调 `dsa_run`。带 `wait` 的 `campaign_apply` 到 45 秒时返回的是 `WAIT_TIMEOUT`：应用仍在进行，并没有失败；再调用一次就能继续跟进。

客户端取消调用时，正在读取或等待的调用立即停止。已经发出的写请求会执行完，因为它可能已经生效；之后不再发送任何请求。如果这次写操作带了 `idempotency-key`，用同一个键再发一次就能读回它的结果，不会重复执行。

客户端结束会话时，服务用同样的方式停下手上的调用，然后退出；还在排队的调用不会开始。
