文档接入 Agent
接入 Agent
为编码 Agent 提供 Acahti skill 和到实例的连接。可选 MCP、CLI 或编辑器插件。
Agent 需要两样东西：skill（技能），教它如何使用 Acahti；以及到你的实例的连接。
Install https://acahti.benchyard.com/skill.md
| 你的 Agent | 连接方式 |
|---|---|
| Claude Code、Codex 或其他 MCP 客户端 | 位于 <instance>/mcp 的 MCP，使用 OAuth 或个人访问令牌。不需要 CLI。 |
| Cursor 或 Codex，一次安装全部就绪 | 编辑器插件，内置 skill 和 MCP |
| Shell Agent、脚本或流水线任务 | CLI，配置主机地址和访问令牌 |
MCP 和 CLI 共用同一套目录。IDE 中的 Agent 用 MCP，Shell 中的用 CLI。安装 skill 的详细说明见 Agent skills。
Codex 首次使用#
- 安装 skill（Agent skills）。
- 添加实例的 MCP 服务器并完成认证。桌面环境优先使用 OAuth：
codex mcp add acahti --url https://acahti.example.com/mcp
codex mcp login acahti
或者在头像菜单 → 访问令牌中创建个人访问令牌，通过环境变量传入：
export ACAHTI_TOKEN=…
codex mcp add acahti --url https://acahti.example.com/mcp --bearer-token-env-var ACAHTI_TOKEN
- 让 Agent 调用
whoami和inbox。仅安装 skill 不代表连接成功。不要为 Codex 安装 CLI。
已有连接时直接复用，不要重复添加。
Benchyard 首次使用#
安装 skill 后提问：连接 Acahti 并检查我的身份和待办。Agent 会检查现有配置，只引导你完成缺少的步骤。仅安装无法启动引导，首次调用时才会开始。
- 打开实例的头像菜单 →「Access token」，创建个人令牌。
- 在 Benchyard 的 Secrets 中，将 ACAHTI_ROOT_URL 设为实例 URL，将 ACAHTI_TOKEN 设为该令牌。把这个密钥绑定到该实例的主机。每位成员使用自己的令牌。
- 让当前任务能读取这些变量。Agent 使用 CLI（仅在缺失时从 GitHub Packages 安装），并验证身份和收件箱。整个过程不涉及 localhost 回调。
# @acahti-ai/acahti 是 GitHub Packages 上的私有包，不在 registry.npmjs.org
echo '@acahti-ai:registry=https://npm.pkg.github.com' >> ~/.npmrc
# 使用对 acahti-ai 具有 read:packages 权限的 GitHub PAT 认证
npm install -g @acahti-ai/acahti
acahti whoami
acahti inbox
acahti mcp tools
acahti mcp call whoami
不要把令牌粘贴到对话中。Benchyard 中绑定主机的密钥占位符直接用于请求，不会复制到本地凭据文件。
Git 身份#
推送到 Acahti 的提交使用实例返回的身份：whoami.git_name 和 whoami.git_email，通过 whoami.setup_local 应用（仅写入本地 Git 配置）。推送到其他主机的提交保留各自的身份。skill 中有完整流程，包括合并、变基以及有多个远程仓库的情况。
每个 Agent 都要遵守的规则#
- 不要把令牌粘贴到聊天中。
- 不要使用
git config --global。 - 通过 HTTPS 从
<instance>/<org>/<repo>.git克隆。 - 只通过
pr_merge合并，它要求流水线通过。