# Agent 原生

大多数工具是为坐在屏幕前的人设计的，之后才给 Agent 补上 API。Acahti 从另一端出发：队友在平台上能做的事，Agent 都应该能以自己的身份、按同样的规则去做；人则能看见并引导这些工作。

## Agent 是成员

- **自己的身份。** Agent 通过它所属成员的 OAuth 登录或个人访问令牌接入。它的提交带着实例在 `whoami` 中给出的 Git 身份，它触发的流水线以 head 提交的作者身份运行。
- **写在工作里。** 项目把 Agent 和人一起列为成员。待办有一个人类负责人，并可以指定一个 Agent 作为代理人（`delegate_login`）。
- **先有上下文，再写代码。** `project_context` 一次调用就能让 Agent 了解项目的未完成任务、决策和进行中的迭代；`planning_brief` 给出迭代的范围、风险和容量。

## 所有入口共用一套操作目录

Web 应用、`/mcp` 上的 MCP、`/acahti/v1` 上的 REST API 和 `acahti` CLI 都是同一套操作目录的客户端。应用里一个按钮能做的事，Agent 都能按名称调用，权限完全相同。

<ol class="planes" aria-label="所有入口背后的同一套操作目录">
<li><b>入口</b><ul><li>Web 应用</li><li>MCP<small>/mcp</small></li><li>REST<small>/acahti/v1</small></li><li>CLI<small>acahti</small></li><li>Aidy<small>应用内</small></li></ul></li>
<li><b>操作</b><ul class="bar"><li>一套操作目录<small>对每个调用者权限和结果都相同</small></li></ul></li>
</ol>

从本站安装一次 skill，就能连接任意实例；实例相关的一切都来自 `whoami`。参见[接入 Agent](agents.md) 和 [MCP 工具](mcp.md)。

## 为 Agent 准备的结果

Agent 读的每个 token 都有成本，所以结果按它的需要来组织：

- `checks_wait` 一次返回某个提交所有检查的状态快照，轮询直到检查结束。
- `pipeline_log` 不指定步骤时只返回失败步骤的日志，也可以只取最后几行。
- `inbox` 列出每个仓库最近一次失败或受阻的运行，以及 head 流水线已通过的未合并 PR。
- 每个操作及其参数都写在 [MCP 工具](mcp.md) 里，在 shell 里用 `acahti mcp tools` 也能列出。

```text
repo_get → branch_list → edit and push
                           ↓
                     checks_wait
                      ↙       ↘
           failed-step logs    green checks
                ↓                   ↓
            fix / rerun       review → pr_merge
```

## 对所有人都生效的规则

Agent 拥有真正的写权限，所以规则放在实例里：

- 只有 PR head 上最新的流水线通过时，`pr_merge` 才会成功。流水线通过表示已配置的检查全部通过。
- 流水线密钥只写入一次，之后不会再被取出，对人和 Agent 都一样。
- 需要放行的部署等待人来批准（`deploy_approve`）。
- 应用内的 Agent Aidy 会先展示它要做的每项改动，等你确认后再执行。

## 人始终在环中

人在看自己工作的地方就能看到 Agent 的工作：看板、追踪、通知，以及每个 PR 和流水线。追踪显示每条流程到了哪个阶段、停留了多久，卡住的 Agent 和卡住的同事一样一目了然。参见[追踪是主线](mainline.md)。