chenxin
42513d13c6
- 产品层：产品宪章与永久禁域、产品定义、完整 1.0 范围与发布门、道家文化语言体系、指标与反指标 - 研究层：参考项目研究（deepseek-harness、pi、MemOS、模型网关）、灵台原生引擎研究（业界原生引擎架构理念与道家文化出处） - 架构层：系统、Agent 运行时（周天体系）、插件系统、灵台引擎（C++ 双形态）、媒体与设备、社区协作市场、前端富内容渲染、数据、记忆与知识 - 契约层：协议与稳定标识、API 总体约定、Native API、兼容网关、实时与 Webhook、内部端口、统一 ContentBlock 与流式（含分支对话交互态）、灵台 C ABI 与 gRPC Service、API 表面、HTTP 与事件、运行观测 - 决策：ADR-001 至 ADR-023（模块化单体、每 attempt 持久化、候选记忆、OAuth 2.1、灵台引擎、双形态部署、大周天演化、宪章、三界作用域、私箧与保全态、叩心、周天统一等） - 交付：WP-01 至 WP-15 实施 TODO 与设计阶段交接文档 - 工程：AGENTS.md 工程规则（含 C++/灵台规范）、CLAUDE.md 引用、.gitignore
171 lines
4.7 KiB
Markdown
171 lines
4.7 KiB
Markdown
# HTTP 与事件契约
|
||
|
||
## 1. 通用请求头
|
||
|
||
| 字段 | 方向 | 规则 |
|
||
| --- | --- | --- |
|
||
| `Authorization` | request | `Bearer <access-token>`；只经 TLS |
|
||
| `traceparent` | both | W3C Trace Context；服务边界传播并生成新 span |
|
||
| `tracestate` | both | 可选；不得包含 PII、密钥或业务正文 |
|
||
| `baggage` | both | 可选；仅传播登记的低敏、低基数键，不参与授权 |
|
||
| `Hunjing-Request-ID` | both | 调用方可提供；服务端缺失时生成；最多 64 个 `[A-Za-z0-9_-]` |
|
||
| `Idempotency-Key` | request | 创建 Run 和副作用操作使用；opaque，作用域和 TTL 由端点定义 |
|
||
| `request-id` / `x-request-id` | upstream response | 保存供应商原始 request ID，不用本地值覆盖 |
|
||
|
||
`Hunjing-Request-ID` 用于业务请求关联，不能替代 `traceparent` 的父子调用链。字段名大小写不敏感；文档使用固定大小写。新私有字段不使用 `X-` 前缀。
|
||
|
||
所有自定义字段为单值字段。重复字段、逗号列表、控制字符、空值或超长值返回 `400 invalid_request`，防止代理合并改变语义。
|
||
|
||
## 2. Header 转发
|
||
|
||
### Client → API
|
||
|
||
只读取本契约列出的字段。未知 `Hunjing-*` 字段忽略或拒绝，不自动进入插件上下文。
|
||
|
||
### API → Provider
|
||
|
||
仅允许 Adapter 白名单：供应商鉴权、版本、beta、content type、trace 和明确业务所需字段。禁止转发：
|
||
|
||
- 用户 `Authorization`；
|
||
- `Cookie`；
|
||
- `Hunjing-Diagnostic-Token`；
|
||
- 任意用户提交的供应商 API Key Header；
|
||
- Hop-by-hop fields；
|
||
- 未登记实验字段。
|
||
|
||
BYOK 密钥由服务端 Secret Store 注入。
|
||
|
||
## 3. 错误响应
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "permission_denied",
|
||
"message": "无权执行该操作。",
|
||
"trace_id": "trace_01...",
|
||
"details": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
稳定 `code`：
|
||
|
||
| Code | HTTP |
|
||
| --- | ---: |
|
||
| `invalid_request` | 400 |
|
||
| `authentication_required` | 401 |
|
||
| `permission_denied` | 403 |
|
||
| `not_found` | 404 |
|
||
| `conflict` | 409 |
|
||
| `payload_too_large` | 413 |
|
||
| `validation_failed` | 422 |
|
||
| `rate_limited` | 429 |
|
||
| `provider_error` | 502 |
|
||
| `provider_unavailable` | 503 |
|
||
| `provider_timeout` | 504 |
|
||
| `internal_error` | 500 |
|
||
|
||
错误消息不得含密钥、完整 Prompt、工具敏感参数或 Provider 原始正文。
|
||
|
||
## 4. SSE
|
||
|
||
事件 envelope：
|
||
|
||
```json
|
||
{
|
||
"id": "event_01...",
|
||
"type": "content.block.delta",
|
||
"run_id": "run_01...",
|
||
"turn_id": "turn_01...",
|
||
"sequence": 12,
|
||
"created_at": "2026-09-02T08:00:00Z",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
- `sequence` 在 Run 内单调递增。
|
||
- Block delta 为临时传输；`content.block.completed` 提供 Block 权威快照，`message.completed` 指向持久化 Message。
|
||
- HTTP 200 后仍可能发送 `error` 事件。
|
||
- 在首个用户可见 delta 发出前，Runtime 可按路由策略重试或故障转移；发出后不得切换上游重新生成另一条内容，只能继续当前流或明确失败。
|
||
- 重连使用 `Last-Event-ID`；若服务端无法重放，则客户端先拉取 Run 当前状态再继续流。
|
||
- 心跳不写业务数据库。
|
||
|
||
## 5. 稳定事件名
|
||
|
||
```text
|
||
run.queued
|
||
run.started
|
||
run.waiting_approval
|
||
run.completed
|
||
run.failed
|
||
run.cancelled
|
||
turn.started
|
||
turn.completed
|
||
model.request.started
|
||
model.request.completed
|
||
model.request.failed
|
||
model.cache.observed
|
||
message.started
|
||
content.block.started
|
||
content.block.delta
|
||
content.block.progress
|
||
content.block.completed
|
||
content.block.failed
|
||
content.block.cancelled
|
||
message.completed
|
||
tool.call.requested
|
||
tool.call.approval_required
|
||
tool.call.started
|
||
tool.call.completed
|
||
tool.call.failed
|
||
memory.candidate.created
|
||
memory.candidate.approved
|
||
memory.candidate.rejected
|
||
memory.created
|
||
memory.updated
|
||
memory.archived
|
||
memory.deleted
|
||
plugin.submitted
|
||
plugin.published
|
||
plugin.installed
|
||
plugin.activated
|
||
plugin.suspended
|
||
plugin.deactivated
|
||
plugin.removed
|
||
media.job.started
|
||
media.job.completed
|
||
media.job.failed
|
||
device.grant.created
|
||
device.grant.revoked
|
||
community.content.published
|
||
community.content.limited
|
||
community.content.removed
|
||
moderation.case.created
|
||
moderation.case.decided
|
||
workspace.member.added
|
||
workspace.member.removed
|
||
release.published
|
||
listing.published
|
||
order.created
|
||
order.paid
|
||
order.cancelled
|
||
payment.succeeded
|
||
payment.failed
|
||
refund.succeeded
|
||
dispute.opened
|
||
entitlement.granted
|
||
entitlement.revoked
|
||
ledger.entry.posted
|
||
settlement.created
|
||
settlement.paid
|
||
settlement.failed
|
||
```
|
||
|
||
事件 payload 只引用敏感对象 ID 和脱敏摘要；原文通过受保护资源 API 读取。支付和 Ledger 事件只能由交易内核产生，插件不能伪造或覆盖。
|
||
|
||
## 6. 幂等
|
||
|
||
- `POST /runs` 接受 `Idempotency-Key`，相同用户、端点和规范化请求体重复提交返回同一 Run。
|
||
- ToolCall 的幂等键由 Run、Tool definition、规范化参数和显式业务对象组成。
|
||
- 不缓存认证失败、审批拒绝和未知执行结果。
|