9.0 KiB
9.0 KiB
API 契约
状态：重写目标态（rewrite/1.0 基线） 职责：定义客户端可用的 REST/SSE 契约形态、鉴权、幂等、分页、错误结构与 OpenAPI 工作流。端点取值细节以灵台生成的 OpenAPI 3.1 为机器真源；枚举与错误码以契约词典为单一事实源。
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 账户与镜域（天宰）
POST /api/v1/auth/register|login|logout|refresh
GET /api/v1/me # 账户与镜域概要
GET /api/v1/me/preferences # 偏好（含神识路由偏好）
POST /api/v1/me/export # 镜域数据导出（异步任务）
3.2 人物与灵胚（镜生）
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 镜树（灵台域·对话）
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 运行与流（灵台域·运行时）
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 记忆（息壤）
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 缘契、三界、形仪、器谱
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 百工、司命与确认
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 兼容层
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 神识阁（用户面）
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。 - 帧格式：
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. 错误结构
{
"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 事件与错误码的新增同样先登记契约词典再实现。