aps-agent/docs/spec/protocol.md

# 客户端与服务端协议（v1）

> 契约本体在 `contracts/schemas/`（JSON Schema），TS 镜像在 `contracts/`，漂移由 `scripts/check-contracts.test.mjs` 卡。本文是给人看的同一份东西。

## 1 范围与所有权

服务端与客户端之间只认这一套接口。引擎协议（Pi 的 JSONL、Codex 的 app-server）只活在 `server/agent` 内部，客户端与 Core 都不感知——协议的所有权比协议的兼容性重要（架构设计 5.2）。

界面只依赖本文的事件模型：换引擎、换模型，事件不变。

## 2 版本与兼容规则

| 规则 | 说明 |
| --- | --- |
| 路径版本 | 前缀 `{PROTOCOL_PREFIX}` = `/v1`；改语义就换前缀，不原地改 |
| 事件版本 | 每个事件带 `v`，当前 `1`；字段只加不改不删 |
| 删除字段 | 先废弃（保留但不再填充）→ 下一个大版本再删 |
| 未知事件 | 客户端必须忽略不认识的 `type`，不能崩 |
| 未知字段 | 客户端必须忽略，不能因多字段报错 |

## 3 认证与身份

| 客户端 | 方式 | 说明 |
| --- | --- | --- |
| 浏览器 | `Cookie: ap_session=<httpOnly>` | 沿用现有 JMS 登录；服务端不把业务系统 token 下发给客户端 |
| 桌面端 | `Authorization: Bearer <desktop-token>` | 授权码 + 设备绑定换来的短期令牌（沿用现有授权方式） |

两者都由 `server/entry` 解析成同一个 Subject（用户 + 租户），再交给应用服务与 Core。首次调用的返回值就是 `MeResponse`。

## 4 端点

| 方法 | 路径 | 请求 | 响应 | 说明 |
| --- | --- | --- | --- | --- |
| GET | `/v1/health` | — | `HealthResponse` | 健康检查 |
| GET | `/v1/me` | — | `MeResponse` | 当前身份与客户端形态 |
| GET | `/v1/projects` | — | `ProjectListResponse` | 可见项目 |
| GET | `/v1/sessions` | `?projectId=` | `SessionListResponse` | 会话列表 |
| POST | `/v1/sessions` | `CreateSessionRequest` | `CreateSessionResponse` | 建会话；写操作必须建在项目会话（ADR-0003） |
| GET | `/v1/sessions/{id}` | `?limit=` | `SessionDetailResponse` | 会话详情与最近消息 |
| GET | `/v1/sessions/{id}/events` | `Last-Event-ID` 或 `?since=` | SSE 事件流 | 回放 + 实时，见第 5 节 |
| POST | `/v1/sessions/{id}/messages` | `SendMessageRequest` | `SendMessageResponse` | 发消息；返回受理，结果走事件流 |
| POST | `/v1/sessions/{id}/cancel` | — | `CancelResponse` | 取消当前运行 |
| GET | `/v1/capabilities` | `?sessionId=` | `CapabilitiesResponse` | 按身份过滤的能力清单 |
| GET | `/v1/executions/{executionId}` | — | `ExecutionReceipt` | 执行状态与回执 |
| POST | `/v1/approvals/{approvalId}` | `ApprovalDecisionRequest` | `ApprovalDecisionResponse` | 确认卡响应 |

## 5 事件流（SSE）

| 规则 | 说明 |
| --- | --- |
| 传输 | `text/event-stream`；`event:` 填事件 `type`，`data:` 填整条事件 JSON |
| 序号 | `seq` 在会话内单调递增，从 1 开始；客户端按它去重与排序 |
| 断点续传 | 客户端带 `Last-Event-ID`（或 `?since=`）重连，服务端从该序号之后回放 |
| 回放 | 回放与实时用同一格式，客户端不需要两套解析 |
| 心跳 | 无事件时按固定间隔发 `heartbeat`，用于探活与代理保活 |
| 顺序 | 同一会话的事件严格有序；不同会话之间不保证 |
| 敏感 | 事件里只有参数摘要（`argsDigest`、`paramsDigest`），没有凭据与参数明文 |

## 6 事件清单

| 事件 | 含义 | `data` 关键字段 |
| --- | --- | --- |
| `message.user` | 用户消息（多端与重连回放用） | `messageId`、`text` |
| `message.delta` | 助手增量文本 | `messageId`、`text` |
| `message.completed` | 一条助手消息结束 | `messageId`、`finishReason` |
| `tool.call` | 引擎请求调用能力 | `callId`、`capabilityId`、`argsDigest` |
| `tool.result` | 能力调用的回执 | `callId`、`executionId`、`status` |
| `execution.updated` | 执行状态变化 | `executionId`、`status`、`errorKind` |
| `approval.requested` | 需要用户确认 | `approvalId`、`capabilityId`、`paramsDigest`、`impactSummary`、`revision`、`expiresAt` |
| `approval.resolved` | 确认结果 | `approvalId`、`decision` |
| `run.state` | 当前运行状态 | `state`（`idle`/`running`/`cancelling`/`cancelled`） |
| `session.updated` | 会话标题或状态变化 | `title`、`status` |
| `error` | 错误 | `code`、`message`、`retryable` |
| `heartbeat` | 保活 | 空对象 |

`status` 取值统一为 `accepted` / `pending-confirmation` / `succeeded` / `failed`。

## 7 审批时序

1. 引擎请求写能力 → Core 判定需确认 → 落一条待确认动作（ADR-0003、架构设计 4.2）
2. 服务端推 `approval.requested`，客户端渲染确认卡（影响范围、参数摘要、目标版本、有效期）
3. 用户点批准 → `POST /v1/approvals/{id}`，带 `revision` 与 `idempotencyKey`
4. 服务端校验版本与有效期 → 推 `approval.resolved` → 执行 → 推 `execution.updated`
5. 版本过期或已执行 → 返回 `expired`，客户端提示重新确认；确认人是会话发起人本人

## 8 错误模型

| 位置 | 形状 | 说明 |
| --- | --- | --- |
| HTTP | `ErrorEnvelope` | 请求本身失败（鉴权、参数、找不到） |
| SSE | `error` 事件 | 运行中失败；`retryable` 表示可重试，客户端据此给"重试"按钮 |

## 9 幂等与取消

| 场景 | 规则 |
| --- | --- |
| 发消息 | 带 `idempotencyKey`；同一 key 重试不产生第二个 run |
| 审批 | 带 `idempotencyKey`；同一 key 只生效一次 |
| 取消 | 幂等：重复取消不报错；已结束的运行返回 `idle` |
| 结果未知 | 执行超时返回 `failed` 且 `errorKind = unknown`，由客户端提示查执行记录，不自动重试写操作 |

## 10 变更规则

改协议必须同时改三处，否则 `pnpm test` 会失败：

1. `contracts/schemas/*.json`（规范本体）
2. `contracts/events.ts` / `contracts/protocol.ts`（TS 镜像；第 4 节的端点表与 `ENDPOINT_SPECS` 由测试逐条比对）
3. 本文档（第 4、6 节的表）