📝 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
This commit is contained in:
chenxin committed
commit
42513d13c6
37 files changed
+5795
No files matched your search
@@ -0,0 +1,132 @@
|
||||
# 运行观测契约
|
||||
|
||||
## 1. 聚合层次
|
||||
|
||||
```text
|
||||
Run
|
||||
└─ Turn
|
||||
├─ ModelCall attempt
|
||||
└─ ToolCall
|
||||
```
|
||||
|
||||
普通 Run API 返回状态、可见消息和聚合 usage；详细对象只通过诊断 API 返回。
|
||||
|
||||
## 2. `turn`
|
||||
|
||||
必需字段：
|
||||
|
||||
- `id`、`run_id`、可选 `parent_turn_id`；
|
||||
- `turn_index`、`status`、`started_at`、`ended_at`；
|
||||
- `input_message_ids`、`output_message_ids`；
|
||||
- `context_snapshot_id`、`plugin_snapshot_id`；
|
||||
- `finish_reason`、`error_code`、`trace_id`。
|
||||
|
||||
## 3. `model_call`
|
||||
|
||||
每次上游 attempt 单独记录：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `id`、`turn_id`、`attempt_index` | 关联和重试顺序 |
|
||||
| `provider`、`endpoint_id` | 实际上游 |
|
||||
| `logical_model`、`upstream_model` | 业务模型与实际模型 |
|
||||
| `request_started_at`、`first_token_at`、`completed_at` | 时间点 |
|
||||
| `latency_ms`、`time_to_first_token_ms` | 延迟 |
|
||||
| `input_tokens` | 未缓存输入 |
|
||||
| `cache_creation_input_tokens` | Provider 缓存写入 |
|
||||
| `cache_read_input_tokens` | Provider 缓存读取 |
|
||||
| `output_tokens` | Provider 输出 |
|
||||
| `reasoning_tokens` | 供应商明确返回时记录数量 |
|
||||
| `audio_*`、`image_*` | 适用且供应商返回时记录 |
|
||||
| `cache_hit` | `true` / `false` / `null` |
|
||||
| `cost_minor`、`currency`、`price_version` | 可重算成本 |
|
||||
| `request_id`、`upstream_request_id` | 本地与供应商请求关联 |
|
||||
| `finish_reason`、`error_type`、`error_code` | 结果 |
|
||||
| `usage_source` | provider / estimate / unavailable |
|
||||
|
||||
总输入：
|
||||
|
||||
```text
|
||||
total_input_tokens =
|
||||
input_tokens +
|
||||
cache_creation_input_tokens +
|
||||
cache_read_input_tokens
|
||||
```
|
||||
|
||||
`cache_hit=true` 仅当 `cache_read_input_tokens > 0`；供应商明确返回 0 时为 false；未提供相关字段时为 null。
|
||||
|
||||
上述公式定义的是 **Hunjing 标准化语义**。Adapter 必须先处理供应商差异：Anthropic 的 `input_tokens` 是未缓存部分，可直接映射；OpenAI 的 `input_tokens` 通常包含 `input_tokens_details.cached_tokens`，因此标准化时将后者映射到 `cache_read_input_tokens`，并将两者之差映射到本字段的 `input_tokens`。原始 usage 经脱敏后另存 `usage_raw_redacted`，便于核对，不能直接混加造成重复计数。
|
||||
|
||||
| 标准字段 | Anthropic | OpenAI |
|
||||
| --- | --- | --- |
|
||||
| `upstream_request_id` | `request-id` / error `request_id` | `x-request-id` |
|
||||
| `input_tokens` | `usage.input_tokens` | `usage.input_tokens - usage.input_tokens_details.cached_tokens` |
|
||||
| `cache_read_input_tokens` | `usage.cache_read_input_tokens` | `usage.input_tokens_details.cached_tokens` |
|
||||
| `cache_creation_input_tokens` | `usage.cache_creation_input_tokens` | 无对应字段时为 `null` |
|
||||
| `output_tokens` | `usage.output_tokens` | `usage.output_tokens` |
|
||||
|
||||
字段路径按具体 API 端点和 SDK 版本适配；表中缺失表示“该端点未返回”，不是数值 0。
|
||||
|
||||
## 4. 字段来源
|
||||
|
||||
### 供应商原生
|
||||
|
||||
供应商返回且 Adapter 原样标准化：
|
||||
|
||||
- 上游模型 ID；
|
||||
- request ID；
|
||||
- stop/finish reason；
|
||||
- input/output/cache/reasoning token（若存在）；
|
||||
- server tool usage（若存在）；
|
||||
- 供应商错误类型。
|
||||
|
||||
### 平台计算
|
||||
|
||||
- `latency_ms`、`time_to_first_token_ms`；
|
||||
- logical model、endpoint、attempt index；
|
||||
- 成本与价格版本；
|
||||
- cache hit 三态；
|
||||
- retry/fallback 关联；
|
||||
- Context 和 Plugin snapshot；
|
||||
- 业务 trace。
|
||||
|
||||
平台计算字段不能标记 `usage_source=provider`。
|
||||
|
||||
## 5. `tool_call`
|
||||
|
||||
字段：
|
||||
|
||||
- `id`、`turn_id`、`step_index`、`call_index`；
|
||||
- `tool_id`、`plugin_id`、`plugin_version`、`execution_backend`；
|
||||
- `arguments_redacted`、`arguments_hash`、`redaction_status`；
|
||||
- `result_redacted`、`result_size_bytes`、`is_error`；
|
||||
- `status`、`error_code`、`started_at`、`ended_at`、`latency_ms`；
|
||||
- `confirmation_id`、`policy_decision_id`；
|
||||
- `trace_id`、`idempotency_key`、`evidence_ids`。
|
||||
|
||||
常规表禁止保存 Authorization、密钥、签名 URL、文件原文和第三方高敏正文。
|
||||
|
||||
## 6. Context Manifest
|
||||
|
||||
ContextSnapshot 保存：
|
||||
|
||||
- 来源对象 ID 与版本；
|
||||
- 来源类型：system、character、message、memory、knowledge、tool result；
|
||||
- 每项估算或真实 token；
|
||||
- 采用、裁剪、压缩或拒绝原因；
|
||||
- 最终顺序和不可逆内容摘要；
|
||||
- cache breakpoint 位置与 Provider cache usage。
|
||||
|
||||
不保存隐藏 chain-of-thought。完整 Prompt 仅在用户明确生成敏感支持包时限期保存。
|
||||
|
||||
## 7. 普通与诊断响应
|
||||
|
||||
| 数据 | 普通 Run API | Summary | Detailed | Sensitive |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| 状态、可见消息 | 是 | 是 | 是 | 是 |
|
||||
| 聚合 token/cost | 是 | 是 | 是 | 是 |
|
||||
| Model attempt | 否 | 摘要 | 是 | 是 |
|
||||
| Tool 名、状态、耗时 | 否 | 是 | 是 | 是 |
|
||||
| 脱敏参数/结果 | 否 | 否 | 是 | 是 |
|
||||
| 受限敏感内容 | 否 | 否 | 否 | 额外确认 |
|
||||
| 隐藏推理 | 否 | 否 | 否 | 否 |
|
||||
Reference in new issue
Block a user