Skip to content

Latest commit

 

History

History
103 lines (86 loc) · 6.44 KB

architecture.md

File metadata and controls

103 lines (86 loc) · 6.44 KB

架构

ChipTrace 只维护一条生产数据路径:

Stock Codex
  ├─ OpenAI Responses ───────────────┐
  ├─ OTLP JSON logs/traces ─────────┼─> 18084 Cloud Gateway
  └─ required lifecycle Hooks ──────┘          │
                                                v
                                    Rust Relay -> WAL -> OSS Raw
                                                │
                                                v
                                       cloud-acceptance
                                                │
                         ┌──────────────────────┴───────────────────┐
                         v                                          v
              Buyer JSONL tar.gz                           OTLP / Langfuse

用户主机只运行未修改的 Stock Codex 和系统下发的原生配置。采集、可靠存储、 轨迹组装和采购验收全部在云端完成。Langfuse 是可选展示层,不是 Raw 事实源或采购准入器。

在线入口按事实来源隔离:/capture 与 /captures 只接受 18084 网关产生的当前版 api_snapshot;OTLP 与 Hook 入口先保存原始 envelope,再由服务器派生 Runtime 和生命周期 事实。历史 rollout、Registry 和其他生产者记录只允许从 sealed Raw 离线重放,不能在线写入。

权威事实

事实 来源
请求、响应、SSE、工具定义、模型调用、结果回传 18084 Responses Wire
工具真实参数、输出、调度状态、截断和耗时 Stock Codex codex.tool_result OTLP log
Shell 子进程退出或运行中状态 Stock Codex 固定结果头,独立 process_outcome
Session、Turn、中断、压缩和子代理生命周期 Stock Codex required Hook
模型路由、Provider 和 API Token Sub2API usage log

入口保留每个 HTTP envelope 的原始 UTF-8 字节、长度和 SHA-256。Canonical 只通过 session-id、thread-id、x-codex-turn-metadata、call_id、request ID 和 traceparent 精确关联。不同来源冲突、未来事件无法解析、工具输出截断或任务未闭合时, Raw 继续保留,但 Session 为 incomplete。

工具定义

云端 /models 为真实模型名 gpt-5.6-sol、gpt-6-astra 返回版本化模型能力,并将 tool_mode 固定为 direct。18084 网关验证 Provider 业务凭据,再用内部采集凭据读取 Relay 目录;业务凭据 不会传给 Relay。Stock Codex 因而在真实 Responses 请求中发送 JSON function tools 和完整 parameters;这份 Wire 是 Tool Schema 的唯一依据。运行时结果只能关联已有模型调用, 不能把内层执行改写为另一个模型调用。

完整性

以下条件相互独立,任何分数都不能补偿硬失败:

Raw committed
  AND raw bytes complete
  AND Responses protocol complete
  AND runtime complete
  AND Session root complete
  AND exact parent/call links complete
  AND Buyer v7 hard gates pass
  AND score >= 90
  = delivery ready

成功、失败、取消、重试和 open tail 都保留。Responses [DONE] 只表示传输 framing 结束; 模型终态、上游传输状态和客户端交付状态分别记录。

可靠性

18084 的 Wire Capture 先写云端网关磁盘 outbox,再异步送入 Rust Relay。OTLP 和 Hook 在 Relay durable ACK 后返回。Relay 和 Collector 使用确定性 Capture ID、WAL、ledger、重启 恢复、批量投递和有界背压;OSS 只接收 sealed Segment,并以 Manifest + Checkpoint 提交。

纯云端模式不能保证客户端断网后补发尚未到达云端的事件。因此 required SessionStart 在采集入口不可达时阻止任务开始;运行中缺失的 Session 保留作取证,但不会进入 Release。

Relay /health 分开报告传输健康与 ingest_coverage。来源新鲜度和 Turn Wire 只统计当前 Relay 进程观察到的 Wire、OTLP logs、OTLP traces 和 Hook 活动;当 Wire 持续活跃而任一 Runtime 来源缺失或相对 最新 Wire 落后超过 5 分钟时,状态为 degraded,并列出 missing_sources、stale_sources 和 source_lag_ms。如果 OTLP/Hook 在近 5 分钟仍有活动而 Wire 已停止或相对 Runtime 落后超过 5 分钟,也必须为 degraded,并把 wire 列入 stale_sources;Runtime 继续流入 不能掩盖 Wire 断流。complete 只表示四路当前同步,不代表任何 Session 已通过 Buyer 验收。 missing_sources 包含所有尚未观察到的来源,包括 Wire;Wire 从未到达而 Runtime 持续 流入时,会同时列入 missing_sources 和 stale_sources。runtime gate 的非零退出会附带 有界的来源名称,兼容旧 Relay 在 Wire 为 0 时遗漏缺失列表的诊断。 ingest_coverage.turn_capture_ready 只有在四路来源同步且存在近期成功的身份化 Turn Wire 时才为 true;它是进程级就绪信号,不代表任意特定 Session 已完整。wire_turn_coverage 独立统计有原生 Session/Turn、无上下文冲突的 Wire、其中 HTTP 2xx 的数量,以及无归属/冲突数量。这些计数按真实 durable ACK 累加,包含重复 ACK;批量中 冲突或失败的项不计入。成功证据的新鲜度仅由非重复的有归属 HTTP 2xx Capture 刷新, 403、无身份请求和历史重投不能维持该新鲜度。runtime health gate v3 同时校验该独立 证据与四源传输状态,缺少新统计的旧 Relay 不能通过。 该统计从 normalization 已解析的对象派生,只保留少量内存元数据,不改写 Raw 或其 SHA。 HTTP 2xx 也不证明 Responses 终态或客户端交付;门禁声明 session_delivery_claimed=false。 Session 是否可交付仍只由 cloud-acceptance 判定。 质量错误计数从持久 Delivery ledger 恢复。quality_errors_scope 必须为 durable_relay_state;quality_errors_current_process 单独报告本次进程新增值,避免重启 掩盖历史错误。每个端点还持久化固定、脱敏的 quality_errors_by_endpoint.*.reasons 原因码, 原因计数必须和端点总数及全局总数守恒;旧 ledger 无法恢复具体原因时只标记 legacy_unclassified。健康快照不会输出转换错误正文。Collector 和 Relay 的健康响应还包含 build.version 与 build.revision;部署门禁可以用 固定 Git revision 拒绝旧镜像继续接收或交接数据。