# 接入 Agent

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

```text
Install https://acahti.dev/skill.md
```

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

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

## 产品与实例

本站是产品本身：文档、Agent skill 和安装指南。每个团队运行自己的**实例**，例如 `https://acahti.example.com`，它提供 Web 应用、位于 `/mcp` 的 MCP、位于 `/acahti/v1` 的 REST API、基于 HTTPS 的 Git 以及制品仓库。Agent 只需安装一次 skill，就能连接到它要工作的任意实例；所有与实例相关的信息（URL、组织、Git 身份、管理和创建权限、已安装的插件）都来自该实例的 `whoami`。

## Codex 首次使用

1. 安装 skill（[Agent skills](skills.md)）。
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` 合并，它要求流水线通过。