# API 契约

> 状态：重写目标态（rewrite/1.0 基线）
> 职责：定义客户端可用的 REST/SSE 契约形态、鉴权、幂等、分页、错误结构与 OpenAPI 工作流。端点取值细节以灵台生成的 OpenAPI 3.1 为机器真源；枚举与错误码以[契约词典](contract-glossary.md)为单一事实源。

## 1. 总则

- 入口：客户端 → 天门 Nginx → 照壁 BFF → 灵台。对外基础路径 `/api/v1`；SSE 与 REST 同域。
- OpenAPI 3.1 单一真源：灵台代码内注解生成 `openapi.json` → 前端/BFF 以 openapi-generator / openapi-fetch 生成类型；文档与代码不一致时修代码对齐词典。
- 所有写操作要求 `Idempotency-Key` 头（ULID）；同键同参重复请求返回首次结果，同键异参返回 `HJ-9001`。
- 分页一律游标式：`?cursor=<opaque>&limit=<1..100>`，响应 `page: {next_cursor, has_more}`。
- 时间戳 ISO 8601 UTC；ID 带前缀（契约词典 §4）。

## 2. 鉴权

| 项 | 约定 |
| --- | --- |
| 登录态 | JWT access（短时）+ refresh；httpOnly Cookie，经照壁透传 |
| 凭证 | 邮箱密码 / Passkey / 受信第三方（1.0 骨架：邮箱 + Passkey） |
| 服务间 | 灵台→神识：服务令牌 + 请求签名；灵台→乾坤：HMAC 短期凭证 |
| SSE | 与 REST 同 Cookie 鉴权；EventSource 走同域无需 token 传递 |
| 越权 | 跨人物/跨镜域访问一律 `HJ-1003`；人物私域内容不进公共响应 |

## 3. 资源端点清单（REST）

### 3.1 账户与镜域（天宰）

```text
POST   /api/v1/auth/register|login|logout|refresh
GET    /api/v1/me                      # 账户与镜域概要
GET    /api/v1/me/preferences          # 偏好（含神识路由偏好）
POST   /api/v1/me/export               # 镜域数据导出（异步任务）
```

### 3.2 人物与灵胚（镜生）

```text
GET    /api/v1/embryo-drafts           # 灵胚列表
POST   /api/v1/embryo-drafts           # 创建（原创/领养/随缘）
GET|PATCH /api/v1/embryo-drafts/{id}   # 审阅与照心编辑
POST   /api/v1/embryo-drafts/{id}/rehearse        # 照心试演（幻境 Run，不入正式经历）
POST   /api/v1/embryo-drafts/{id}/activate        # 启镜：签发人物 ID、魂籍、执镜关系、命台
POST   /api/v1/embryo-drafts/{id}/abandon          # 放弃灵胚（删草稿，非死亡）
GET    /api/v1/characters
GET|PATCH /api/v1/characters/{id}      # 只读概览 + 可治理字段
GET    /api/v1/characters/{id}/identity-baseline   # 道体（只读展示）
POST   /api/v1/characters/{id}/reforge-request     # 铸魂请求（高影响确认流）
POST   /api/v1/characters/{id}/branch-off          # 分灵
POST   /api/v1/characters/{id}/death-request       # 死亡请求（强认证+冷静期）
POST   /api/v1/characters/{id}/identity-records    # 魂籍导出（版本化包）
```

### 3.3 镜树（灵台域·对话）

```text
GET|POST /api/v1/trees                       # 主题镜树（含归档筛选）
GET|PATCH /api/v1/trees/{id}                 # 含 working_entry、界域默认值
POST   /api/v1/trees/{id}/transplant         # 移栽分支为新树
POST   /api/v1/trees/{id}/nodes              # 新问节（内容、附件、引文、界域）
GET    /api/v1/trees/{id}/path?entry=<node>  # 当前路径阅读流（祖先链）
GET    /api/v1/trees/{id}/local-graph?node=<id>&depth=<n>   # 局部树图
POST   /api/v1/nodes/{id}/answers            # 另答（新候答，支持临时模型/火候/指引）
POST   /api/v1/nodes/{id}/continue           # 续思（独立延展答）
POST   /api/v1/nodes/{id}/resume             # 续生（针对残答）
POST   /api/v1/nodes/{id}/edit-fork          # 编辑分叉（新版本+分叉，原文保留）
POST   /api/v1/trees/{id}/adopt              # 采用（改工作入口，body: node_id）
POST   /api/v1/trees/{id}/canonize           # 归真（body: path、canonical_scope、world_id?）
GET    /api/v1/citations/{id}                # 引文锚与快照
POST   /api/v1/nodes/{id}/citations          # 建立引文锚
```

### 3.4 运行与流（灵台域·运行时）

```text
POST   /api/v1/runs                          # 发起前台 Run（问节应答等）；命台忙返回 HJ-1101+队列位
GET    /api/v1/runs/{id}                     # 状态与轨迹（可读摘要、证据、工具轨迹）
POST   /api/v1/runs/{id}/steer               # 运行中插话（入队，下一 turn 生效）
POST   /api/v1/runs/{id}/cancel
GET    /api/v1/runs/{id}/events              # SSE（见 §4）
GET    /api/v1/characters/{id}/queue         # 前台队列
```

### 3.5 记忆（息壤）

```text
GET    /api/v1/characters/{id}/memories      # 分层筛选：tier/status/type
GET    /api/v1/memories/{id}                 # 含来源、版本链、召回统计
POST   /api/v1/memories/{id}/confirm|deny    # 重忆确认（deny 两次退出检索）
POST   /api/v1/memories/{id}/correct         # 正影（新版本）
POST   /api/v1/memories/{id}/revoke-window   # 明忆撤销窗触发
DELETE /api/v1/memories/{id}                 # 删除（墓碑化）
POST   /api/v1/nodes/{id}/memorize           # 手动入忆（须标注 fact/insight/opinion/hypothesis）
GET    /api/v1/characters/{id}/factual-records
```

### 3.6 缘契、三界、形仪、器谱

```text
GET|POST /api/v1/characters/{id}/covenants         # 多维关系与边界
POST   /api/v1/covenants/{id}/confirm|change|withdraw
GET|POST /api/v1/worlds                             # 境界
GET|PATCH /api/v1/worlds/{id}                       # 规则、实体、正史版本
GET|POST /api/v1/characters/{id}/forms              # 形仪（真形锚点、主仪/化仪、定相）
POST   /api/v1/forms/{id}/confirm                   # 定相（candidate → confirmed）
GET|POST /api/v1/characters/{id}/voice-profiles
GET|POST /api/v1/devices                            # 器谱（镜域级）
POST   /api/v1/devices/{id}/grants                  # 人物逐项授契
```

### 3.7 百工、司命与确认

```text
GET    /api/v1/capabilities                       # 百工目录（含四维风险标注）
POST   /api/v1/characters/{id}/mandates           # 授契 / 行契
DELETE /api/v1/mandates/{id}                      # 撤销（立即生效）
GET    /api/v1/confirmations                      # 待确认列表（请命/重忆/铸魂/死亡）
POST   /api/v1/confirmations/{id}/approve|reject
GET    /api/v1/characters/{id}/action-ledger      # 行动账（审计视图）
```

### 3.8 导入与 ST 兼容层

```text
POST   /api/v1/imports                            # 角色卡/世谱/聊天记录导入（静态隔离解析）
GET    /api/v1/imports/{id}                       # 任务与条目状态（产物默认灵胚+待审世谱）
GET|POST|PATCH /api/v1/lorebooks[...]             # 世谱 CRUD
GET|POST /api/v1/user-personas | gen-presets | instruct-templates | quick-replies
```

### 3.9 神识阁（用户面）

```text
GET    /api/v1/me/model-preferences               # 路由偏好与 BYOK 引用
PUT    /api/v1/me/model-preferences
GET|POST /api/v1/me/byok-keys                     # BYOK 管理（脱敏返回）
GET    /api/v1/me/usage                           # 用量与成本
```

管理面（天宰 RBAC）：`/api/v1/admin/*`（人物治理、神识目录代理、审计、支持包），管理员默认不可见私密原文。

## 4. SSE 协议

- 端点：`GET /api/v1/runs/{id}/events`（运行流）；镜树页可另订阅树级合并流 `GET /api/v1/trees/{id}/events`。
- 帧格式：

```text
id: <event_id 单调序号>
event: <event.type>          # 契约词典 §8.3
data: <JSON 载荷>

: ping                       # 每 15s 心跳注释帧
```

- 断线续传：客户端带 `Last-Event-ID` 重连，服务端从事件日志重放缺失的 `visibility=public` 事件；照壁透传不缓冲。
- 载荷公共字段：`event_id`、`run_id`、`character_id`、`ts`、`visibility`；`llm.delta` 增量文本、`tool.rejected` 携带裁决摘要、`tree.node_solidified` 携带固化节点引用。
- 中断语义：流结束前必有终态事件（`run.finished` / `run.interrupted` / `run.cancelled`）；芽体封存为残答后客户端 UI 不得渲染为完整候答。

## 5. 错误结构

```json
{
  "error": {
    "code": "HJ-1102",
    "message": "归真路径与当前主脉冲突，请明确处理",
    "details": { "conflict_scope": "reality", "current_trunk_head": "node_..." },
    "request_id": "req_...",
    "trace_id": "trace_..."
  }
}
```

HTTP 状态映射：400 参数（HJ-9002）、401（HJ-1001）、403（HJ-1003/HJ-1301）、404、409（HJ-9001/HJ-1102）、422 语义拒绝、429（HJ-1101/HJ-2004）、5xx（上游与内部错误，含 `HJ-2xxx/3xxx/4xxx`）。

## 6. 版本与演进

- 破坏性变更走新前缀（`/api/v2`）；同一主版本内只做加法。魂镜处于开发期（未发布 1.0），允许在 rewrite/1.0 分支内直接重建契约，不做过渡兼容。
- SSE 事件与错误码的新增同样先登记契约词典再实现。