0 Fork 0

Files

T

chenxin 42513d13c6 📝 docs: 建立魂镜完整 1.0 设计文档体系

- 产品层：产品宪章与永久禁域、产品定义、完整 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

2026-09-09 21:07:14 +08:00

5.1 KiB

Raw Blame History

模型网关兼容 API

1. 边界

兼容网关提供模型推理协议，不是 Hunjing 角色或 Agent Runtime 的替代入口：

https://gateway.<deployment-domain>/openai/v1
https://gateway.<deployment-domain>/anthropic/v1

它可以接受工具定义并返回 tool call，但不会自动执行客户端工具。
它不读写 Character、Memory、Conversation、Community、DeviceGrant、Order 或 PluginInstallation。
需要 Hunjing 自动工具循环、多 Agent、审批和持久化时，调用 Native /v1/runs。

2. OpenAI-compatible 子集

1.0 支持：

GET  /openai/v1/models
POST /openai/v1/responses
POST /openai/v1/chat/completions
POST /openai/v1/embeddings
POST /openai/v1/images/generations
POST /openai/v1/audio/transcriptions
POST /openai/v1/audio/speech

认证：

Authorization: Bearer hjk_...

流式响应遵循对应 OpenAI SSE 子集；响应返回 x-request-id 和 Hunjing-Request-ID。未支持的请求字段返回明确 unsupported_parameter，不静默忽略会改变语义的字段。

3. Anthropic Messages-compatible 子集

1.0 支持：

GET  /anthropic/v1/models
POST /anthropic/v1/messages
POST /anthropic/v1/messages/count_tokens

认证和版本：

x-api-key: hjk_...
anthropic-version: <supported-version>

OAuth 客户端也可用 Authorization: Bearer。网关返回 request-id 和 Hunjing-Request-ID。anthropic-beta 只允许 Adapter 明确支持的值；未知 beta 返回 400，不透传到任意上游。

Messages Tool Use 保留 tool_use.id / tool_result.tool_use_id 关联；Thinking、cache、usage、stop reason 和 SSE block 必须按所声明兼容版本转换，无法无损映射时拒绝而非伪造。

4. 模型名与路由

请求 model 优先解析 Hunjing 逻辑模型，例如：

default-chat
fast-chat
reasoning-chat
vision-chat
embedding-default
image-default
speech-default

管理员可允许部分上游模型别名，但业务客户端不应依赖 Provider 密钥或 Endpoint。模型配置按固定顺序继承：平台硬边界 → 平台目录 → 用户偏好/BYOK → 角色覆写 → 会话临时选择；上层约束不可被下层覆盖，会话临时选择不持久化，切换模型不得改变角色身份。能力槽（chat、vision、ASR、TTS、image generation、embedding、rerank、safety 等）由逻辑模型声明。GET models 只返回当前调用主体获准、在其地区可用的模型和能力。

路由依次考虑：scope、地区、隐私级别、能力、上下文、工具/结构化输出支持、预算、健康、配额和优先级。

5. Header 策略

客户端 Header 默认不转发。Adapter 逐 Provider 声明 allowlist，例如：协议版本、项目/组织选择和特性开关。以下字段永不直接转发：

Hunjing 用户 Authorization/Cookie；
Hunjing-Diagnostic-Token；
客户端提交的上游 API key；
未登记 Provider beta；
baggage 中未批准的键；
Hop-by-hop Header。

上游凭据由 Secret Store 按 Endpoint 注入。常规日志只记录允许的 Header 名和不可逆摘要，不记录值。

6. 重试、故障转移和流提交

stateDiagram-v2
  [*] --> routing
  routing --> requesting
  requesting --> retrying : retryable before visible output
  retrying --> requesting
  requesting --> streaming : first visible event
  requesting --> completed : non-stream success
  streaming --> completed
  streaming --> failed : stream error
  requesting --> failed

只在首个用户可见事件前对安全的错误重试/故障转移。
首个可见事件后禁止切换 Provider 重新生成；当前流继续或明确失败。
每个 attempt 单独创建 ModelCall；SDK 自身重试也必须可观测。
429 遵循 Retry-After；上下文错误、认证、权限和内容拒绝不做同请求盲重试。

7. Usage 标准化

标准字段见 run-observability.md。关键差异：

Anthropic usage.input_tokens 表示未缓存输入，缓存创建/读取单列；
OpenAI usage.input_tokens 通常含 cached tokens，Adapter 计算未缓存差值；
Provider 未返回字段存 null，usage_source=unavailable；
平台估算必须标记 gateway_estimate，不能冒充 Provider usage；
成本由 Hunjing 价格版本计算，不信任上游返回成本；
流式 usage 可能只在末尾出现，流异常时允许部分 usage 或 unavailable。

8. BYOK 与 Service Account

兼容 API 只接受 Hunjing 凭据，不接受用户把 Provider Key 当认证凭据。
BYOK 通过 Native Secret/Endpoint 配置写入，常规读取只返回掩码和状态。
Service Account scope 可限制模型、能力、日/月预算、RPM/TPM、IP/来源和有效期。
同一个 API key 不跨 PersonalDomain/Workspace 自动访问。

9. 错误转换

兼容入口按目标协议返回错误 envelope，同时附：

Hunjing-Request-ID: request_01...
traceparent: 00-...

内部保留标准错误和 Provider 原错误类别。不得把 Provider 私密正文、Endpoint、密钥状态或其他租户信息暴露给兼容客户端。

5.1 KiB Raw Blame History Unescape Escape