185 lines
9.6 KiB
Markdown
185 lines
9.6 KiB
Markdown
# 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}/death-cancel # 冷静期撤销
|
||
POST /api/v1/characters/{id}/death-finalize # 冷静期满后落定（确认短语强校验）
|
||
GET|POST /api/v1/characters/{id}/identity-records # 魂籍列表/导出新版本（版本化包）
|
||
GET /api/v1/characters/{id}/identity-records/{record_id} # 完整魂籍 payload
|
||
POST /api/v1/characters/{id}/identity-records/{record_id}/verify # 摘要+签名校验
|
||
POST /api/v1/characters/{id}/seat/acquire # 命台租约获取（冲突 HJ-1101 + seat.contested）
|
||
POST /api/v1/characters/{id}/seat/release # 命台租约释放
|
||
```
|
||
|
||
### 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} # 状态与轨迹（可读摘要、证据、工具轨迹）
|
||
GET /api/v1/runs/{id}/events # JSON 事件时间线（读模型，按 sequence 升序）
|
||
GET /api/v1/runs/{id}/stream # SSE 事件流（见 §4）
|
||
POST /api/v1/runs/{id}/steer # 运行中插话（入队，下一 turn 生效）
|
||
POST /api/v1/runs/{id}/cancel
|
||
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}/stream`（运行流；与既有前端约定一致）；`GET /runs/{id}/events` 为 JSON 事件时间线读模型；镜树页后续可另订阅树级合并流 `GET /api/v1/trees/{id}/stream`。
|
||
- 帧格式：
|
||
|
||
```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 事件与错误码的新增同样先登记契约词典再实现。
|