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

4.8 KiB

Raw Blame History

运行观测契约

1. 聚合层次

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

总输入：

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 名、状态、耗时	否	是	是	是
脱敏参数/结果	否	否	是	是
受限敏感内容	否	否	否	额外确认
隐藏推理	否	否	否	否

4.8 KiB Raw Blame History Unescape Escape