# 接入 Agent

Agent 需要两样东西：**skill（技能）**，教它如何使用 Acahti；以及到你的实例的**连接**。

```text
Install https://acahti.benchyard.com/skill.md
```

| 你的 Agent | 连接方式 |
|---|---|
| Claude Code、Codex 或其他 MCP 客户端 | 位于 `<instance>/mcp` 的 [MCP](/docs/mcp/)，使用 OAuth 或个人访问令牌。不需要 CLI。 |
| Cursor 或 Codex，一次安装全部就绪 | [编辑器插件](/docs/plugin/)，内置 skill 和 MCP |
| Shell Agent、脚本或流水线任务 | [CLI](/docs/cli/)，配置主机地址和访问令牌 |

MCP 和 CLI 共用同一套目录。IDE 中的 Agent 用 MCP，Shell 中的用 CLI。安装 skill 的详细说明见 [Agent skills](/docs/skills/)。

## Codex 首次使用

1. 安装 skill（[Agent skills](/docs/skills/)）。
2. 添加实例的 MCP 服务器并完成认证。桌面环境优先使用 OAuth：

```bash
codex mcp add acahti --url https://acahti.example.com/mcp
codex mcp login acahti
```

或者在头像菜单 → 访问令牌中创建个人访问令牌，通过环境变量传入：

```bash
export ACAHTI_TOKEN=…
codex mcp add acahti --url https://acahti.example.com/mcp --bearer-token-env-var ACAHTI_TOKEN
```

3. 让 Agent 调用 `whoami` 和 `inbox`。仅安装 skill 不代表连接成功。不要为 Codex 安装 CLI。

已有连接时直接复用，不要重复添加。

## Benchyard 首次使用

安装 skill 后提问：**连接 Acahti 并检查我的身份和待办**。Agent 会检查现有配置，只引导你完成缺少的步骤。仅安装无法启动引导，首次调用时才会开始。

1. 打开实例的头像菜单 →「Access token」，创建个人令牌。
2. 在 Benchyard 的 Secrets 中，将 **ACAHTI_ROOT_URL** 设为实例 URL，将 **ACAHTI_TOKEN** 设为该令牌。把这个密钥绑定到该实例的主机。每位成员使用自己的令牌。
3. 让当前任务能读取这些变量。Agent 使用 CLI（仅在缺失时从 GitHub Packages 安装），并验证身份和收件箱。整个过程不涉及 localhost 回调。

```bash
# @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` 合并，它要求流水线通过。