企业官网建设流程全解析

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具

导读

tests/canonical/evidence/issue-1450-20260715-162447-736593/pair-2/arm-x/workdir/.ouroboros/traces/auto_20b877d7935f/summary.md是 ouroboros 自动流水线（ooo auto）在一次真实运行结束后生成的 interview trace 摘要文件。它记录了本次会话的最终状态（blocked）、Seed 质量评审（QA）给出的revise判定与 0.72 分、反复 5 次修复仍未能通过的阻塞原因，以及 10 条契约决策的溯源分布。阅读本文后，你将掌握：trace 文件的生成原理与目录约定、每个字段的语义与源码出处、Seed QA 门控的完整判定流程（含修复、超时、咨询降级路径）、决策溯源（provenance）的等级划分与门控规则，以及如何把这份 trace 当作排查自动化任务的审计线索。

一、trace 是什么：一份由持久化状态投影出来的运行档案

1.1 生成位置与目录约定

summary.md位于.ouroboros/traces/<run_id>/目录下，其中run_id等于自动流水线的auto_session_id（本例为auto_20b877d7935f）。该目录的默认根路径由 trace_export.py 决定：<cwd>/.ouroboros/traces/<run_id>/，即从流水线执行时的工作目录（state.cwd）开始计算，可通过out_root参数覆盖。

该目录下会输出一组可 grep 的流文件（空流不生成文件）：

流文件的分类规则定义在 trace_export.py：事件类型名包含lateral/unstuck/stagnation的归入 lateral 流；包含timeout/fallback/failed/deadline/degraded/blocked等标记的归入 flags 流；携带ambiguity_score的事件无论类型名如何都进入 ambiguity 流。

1.2 投影而非存储：数据从哪来

trace 不是独立存储，而是一个projection（投影）。它从两个已存在的持久化源读取数据（见 trace_export.py）：

• SeedDraftLedger：保存访谈问题历史、每条已决策契约字段及其source/status/provenance，以及决策来源直方图；
• EventStore：保存访谈事件流（歧义度轨迹、lateral 建议，以及驱动层追加的超时/降级/生命周期事件）。

由于内容完全由持久化状态与已存事件推导而来，不含墙上时钟戳，因此重新导出是字节级幂等的（byte-idempotent）：每次导出都会确定性地覆写同样的内容。

trace 有两个入口：export_interview_trace（手动/A3-CLI 入口，可从AutoStore加载任意历史run_id重新投影）与best_effort_export_trace（流水线 finalize 钩子，任何失败只记录日志、绝不抛入运行流程）。后者的等待时间受TRACE_EXPORT_DEADLINE_SECONDS = 30.0硬性约束（trace_export.py），且文件系统写阶段运行在独立的 daemon 线程上，以保证 trace 生成延迟不会阻塞 CLI 返回终态结果。

1.3 为什么这是一个好的审计格式

每个 JSONL 行都通过type字段自描述，summary.md采用纯文本 markdown 列表，便于grep、脚本分析与 LLM 检索。这种"可 grep"的设计（A2 / run-metaharness 计划）让下游工具（MCP 信封、harness trace、attention_relay）能直接从结构化字段中读取结果，而无需解析英文散文。

二、逐字段解析 summary.md 的头部信息

本节以示例文件内容为骨架，逐项对应源码中 summary.md 的构建逻辑。

2.1 Status：终态与 stop reason

- Status: **blocked**

Status直接取自state.phase.value（AutoPipelineResult的终态阶段）。blocked表示流水线在进入 RUN 之前被某个门控中止。blocked之外常见终态还有complete（成功完成）与failed（内部失败）。

值得注意：在 grade_gate_terminals.py 中，grade 门控的终止码被定义为一组模块级常量：

• seed_grade_below_required：Seed 实际评级未达到要求的评级；
• seed_review_withheld_run：评审没有放行执行；
• degraded_seed_safety_blockers：降级 Seed 仍携带硬安全阻塞项。

这套类型化编码让下游消费者无需读散文即可区分"评级太低（应提高评级）"、"评级达标但评审未放行（提高评级是错误动作）"与"降级 Seed 仍带安全标记（需先解决标记）"三种完全不同的处置方向。本示例 trace 虽因 Seed QA 未通过而 blocked，但在outcome.json中会以stop_reason_code字段携带精确的编码。

2.2 Grade：确定性评级门

- Grade: A

Grade对应state.last_grade，即SeedReviewer对当前 Seed 的评级结果。评级排序定义在 grade_gate_terminals.py：{"A": 0, "B": 1, "C": 2}，grade_meets_required只有在实际评级优于或等于required_grade时才返回 True，未知评级一律视为不达标。

本示例评级为 A（最高档），说明 Seed 的契约质量本身达标——阻塞并非评级问题，而是下面的 Seed QA 判定。

2.3 Seed 标识与来源

- Seed: seed_4ea47f30d65d (origin: auto_pipeline)

Seed字段包含seed_id与seed_origin。origin 为auto_pipeline表示该 Seed 由自动流水线（访谈驱动 + 自动填充）合成，而非由用户在交互式 Seed 会话中手工创建。这在 seed_preflight.py 与 pipeline 的state.seed_origin.value中体现：不同来源的 Seed 走不同的前检路径。

2.4 Evaluate/QA：Seed QA 门的判定

- Evaluate/QA: verdict=revise score=0.72 passed=False

这是本文件信息量最大的字段之一，直接取自state.last_qa_*：

• verdict（判定）：revise——Seed 需要修改；
• score（得分）：0.72；
• passed：False——未通过。

这三个字段的写入点在 pipeline.py 的_run_seed_qa_gate：每次评估器返回后，state.last_qa_score/state.last_qa_verdict/state.last_qa_passed会被同步更新，并在下一次尝试前通过clear_seed_qa_verdict清空（防止上一次尝试的判定泄漏到下一次，seed_qa_advisory.py）。

2.5 Blocker：阻塞的完整叙事

- Blocker: Seed QA did not pass after 5 attempt(s): revise (score 0.72); differences: ...

Blocker来自state.last_error（在_build_outcome中由_clip(state.last_error)截断到 2000 字符，trace_export.py）。这一行同时携带了三个信息：

1. 尝试次数：5 attempt(s)——修复预算用尽。预算上限来自max(1, int(state.max_repair_rounds or 1))（pipeline.py）；
2. 差异（differences）：评审器列出的具体差距清单；
3. 建议（suggestions）：评审器给出的可操作修改方向。

示例中的三条差异与三条建议恰好构成了一个完整的 Seed 质量闭环：

这些字段在outcome.json中以qa.differences与qa.suggestions数组形式保留（各最多 5 条，见 seed_qa_advisory.py 的_MAX_EVIDENCE = 5）。

三、Counts：一次访谈的量表

## Counts - Questions: 1 - Decisions: 10 (promoted 10, rejected 0, gated 7) - Ambiguity points: 0 - Lateral records: 1 - Flags: 2

Counts 在 trace_export.py 中由各流长度与决策行统计计算得出：

• Questions：ledger 的question_history长度（含事件流中的interview.response.recorded响应事件，跨 provider 运行时问题历史稀疏时由后者补足）。本例为 1，说明本轮访谈问题轮次很少，大部分契约字段由自动填充完成；
• Decisions：decisions.jsonl中决策条目总数（10）。其中promoted（晋升，即状态非 WEAK/CONFLICTING/BLOCKED 的活跃条目）10、rejected（被否决/搁置，状态为_REJECTED_STATUSES）0、gated（受门控，即溯源属于MODEL_INFERRED或TIMEOUT_DEFAULT）7。promoted 与 rejected 的判定见 trace_export.py 与 trace_export.py；
• Ambiguity points：携带ambiguity_score的事件数。本例为 0，说明访谈中没有产生歧义度轨迹点；
• Lateral records：lateral 流条目数。本例为 1，说明修复过程中曾动用过一条横向思考记录（见下文"横向修复"）；
• Flags：flags 流条目数。本例为 2——结合 5 次修复与 advisory 路径，这两条 flag 很可能对应生命周期信号（如超时/降级标记）与端态状态标志。

特别需要解释gated 7的含义：_GATED_PROVENANCE（trace_export.py）只包含MODEL_INFERRED与TIMEOUT_DEFAULT两类溯源。10 条决策中有 7 条来自模型推断或超时默认，意味着这份 Seed 的大部分契约字段并非由用户直接确认，而是在自动填充机制下生成的模型最佳猜测——这正是 Seed QA 门控要重点审查的对象。

四、Decision provenance histogram：决策是如何做出的

## Decision provenance histogram - maintainer_policy: 2 - timeout_default: 7 - user_confirmed: 1

这是 trace 中最具审计价值的字段，它回答一个关键问题：Seed 里的每条契约字段，到底是用户说的、模型猜的、超时兜底的，还是维护者策略填的？

4.1 五种溯源等级

ledger.py 定义了DecisionProvenance（决策溯源）枚举，与描述"内容权威类型"的LedgerSource正交：

这个设计直接回应了 #1485 暴露的失败模式：超时默认的决策与用户确认的决策在过去无法区分，导致包含原始问题文本的降级 Seed 被静默执行。引入溯源轴后，model_inferred与timeout_default两类决策在成为可执行 Seed 前必须通过低歧义判据（见ouroboros.auto.grading），其余三类是接地/人类授权的，无条件通过。

4.2 溯源如何推导

LedgerEntry.effective_provenance（ledger.py）的规则：显式盖章的provenance字段优先；未盖章（旧会话、反序列化条目、未显式盖章的写入点）时，从source经_PROVENANCE_FROM_SOURCE映射推导（ledger.py）：

• USER_GOAL/USER_PREFERENCE/NON_GOAL/REPO_FACT/EXISTING_CONVENTION→user_confirmed；
• CONSERVATIVE_DEFAULT→maintainer_policy；
• INFERENCE/ASSUMPTION/AUTO_FILL_INFERENCE→model_inferred；
• 兜底默认_PROVENANCE_DEFAULT = MODEL_INFERRED——未盖章条目被视为模型猜测并接受低歧义筛选，既不让旧会话崩溃，也不让未盖章决策静默通过门控。

超时兜底与横向共识无法由source表达，因此在决策点被显式盖章（ledger.py）。

4.3 直方图怎么数

provenance_histogram（ledger.py）只统计活跃条目（状态非 WEAK/CONFLICTING/BLOCKED），即真正流入合成 Seed 的决策，并按溯源值字典序稳定排序。它被放到SeedMetadata.decision_provenance上，供 A2 trace 工件 grep 出"这份 Seed 的契约是如何拼装出来的、依赖多少条被门控的决策"。

本例直方图（timeout_default: 7占绝对多数）与 Counts 中gated 7完全对应，共同说明了这次自动填充的真相：这是一份高度依赖超时默认值拼装出来的 Seed——7 条契约字段在访谈未收敛时落入了确定性兜底，而兜底值显然不足以支撑一个明确的 CLI 契约。

五、Blocker 背后：Seed QA 门控的完整判定流程

Blocker 那句"Seed QA did not pass after 5 attempt(s)"背后，是_run_seed_qa_gate（pipeline.py）一次完整的门控循环：

1. 可选门：只有当seed_qa_evaluator被装配时该门才生效；未装配时 Seed 无条件进入下一阶段（pipeline.py）；
2. 逐次判定：每次尝试先清空旧判定、保存状态，再以 EVALUATE 阶段超时（_deadline_capped_timeout）调用评估器；
3. 瞬态重试：评估器超时或报错时，按_TRANSIENT_TOOL_ATTEMPTS次数与退避策略重试；重试期间若触碰流水线 deadline 则立即返回 deadline 结果（pipeline.py）；
4. 通过则继续：passed=True时先复查确定性评审门（grade gate），通过后标记进度进入 RUN 或 skip-run 完成（pipeline.py）；
5. 未通过且预算未耗尽：若判定请求歧义修复则直接 blocked（seed_qa_ambiguity_unrepairable）；否则调用_repair_seed_after_qa修复 Seed，重新评审（SeedReviewer），更新seed_artifact/seed_id/last_grade，进入下一轮（pipeline.py）；
6. 预算耗尽：走 advisory 路径——本例即第 5 次尝试后repair_budget_exhausted（pipeline.py）。

5.1 修复机制：机械回写与横向思考

_repair_seed_after_qa（pipeline.py）有两种修复手段：

• 机械回写（机械反馈回声）：_seed_with_seed_qa_feedback把 QA 的差异与建议编码为诊断约束回写进 Seed，再重新接受评审——但它只能复述差距，解决不了"缺一个绑定契约选择、缺一个章节"这类实质性阻塞；
• 横向修复（lateral repair）：装配了lateral_thinker时，先由select_persona_for_qa_failure基于反馈选择横向人格，再由该人格把已映射的修复约束转成一个具体决策并折叠进 Seed；若人格链耗尽、超时或插件委派失败，则回退到机械回写。修复过程记录在state.last_lateral_persona/state.last_lateral_approach_summary/state.last_lateral_text，并计入personas_invoked——这正是本示例 trace 中Lateral records: 1的来源。

注意_normalized_seed_qa_feedback会对反馈做清洗：剔除恢复转录文本（recovery transcript）与上下文块，避免把运行期杂讯写进 Seed（pipeline.py）。

5.2 咨询降级：不把 blocked 变成死胡同

当修复预算耗尽或反馈无法被映射时，_run_seed_qa_gate不会直接 dead-end，而是走_seed_qa_advisory_continue（pipeline.py）与publish_advisory（seed_qa_advisory.py）：

• 顺序保证：先让所有仍可阻塞的门（确定性 grade 门、流水线 deadline）发言，确认真正走在继续路径上，才发出SEED_QA_ADVISORY_EVENT（auto.seed_qa.advisory_override）——避免"宣称继续驱动"的证据被后续门控打脸；
• 事件负载：seed_qa_advisory_payload携带 schema_version、auto_session_id、seed_id、attempts、verdict、score、差异与建议（各至多 5 条）、reason 与裁剪后的 detail。reason区分真正的未通过判定（repair_budget_exhausted/seed_qa_feedback_unmapped）与评估器侧失败（evaluator_timeout/evaluator_error/evaluator_transient_error）；
• 判定移交：未解决的发现保留在state.last_qa_*上，由结果信封与事件继续暴露，真实裁决推迟到 run → evaluate 阶段——evaluate 依据执行证据判定，而非对 Seed 的静态阅读；
• 权限不削弱：修复后不再满足required_grade或不再被放行的 Seed，仍由grade_gate阻塞，而不是这条 advisory 路径。配套进度消息为Seed QA advisory (<reason>): <detail>; continuing with the current Seed（seed_qa_advisory.py）。

这套设计的核心契约写在其模块 docstring 中：Seed-QA 门是可选门，装配了评估器的流水线不得让会话比不装配时更糟——可以修复、注解、警告，但不得把本可以启动的运行带进死胡同。

5.3 超时与 deadline 的双重防护

• 评估器调用受asyncio.wait_for+ EVALUATE 阶段超时约束；
• 修复（含横向思考）同样受超时与 deadline 约束，超时抛TimeoutError直接返回 deadline 结果；
• 整个 trace 导出本身也有 30 秒 deadline，超时后 daemon 线程可能仍在后台完成写入，但调用方不受阻塞（见 1.2 节）。

六、测试验证：这条路径有测试吗

自动流水线的 Seed QA 路径在单元测试中有充分覆盖，可参见tests/unit/auto/下针对 pipeline、ledger 与 trace 的测试（共 69 个测试文件）。从测试目录结构看，可以确认以下行为存在对应的断言基础：

• tests/unit/auto/test_trace_export*.py（可在 tests/unit/auto 中检索）：验证 trace 流文件生成、字段语义与字节级幂等导出；
• tests/unit/auto/test_ledger*.py：验证effective_provenance推导、provenance_histogram只统计活跃条目、冲突解决优先级；
• tests/unit/auto/test_seed_qa*.py：验证 Seed QA 门控的通过/修复/咨询降级路径、修复预算耗尽与瞬态重试。

本文示例 trace 本身来自tests/canonical/evidence/issue-1450-20260715-162447-736593/pair-2/arm-x/workdir/，即 canonical 测试夹具中的真实运行产物——它是把 trace 解读与 QA 门控行为作为回归测试证据的典型样本。结合 seed_preflight.py 与 resume_routing.py 中出现的 seed_qa 引用，可以推断：恢复（resume）会话也会携带 Seed QA 判定继续，前检阶段同样关注 Seed 的 QA 状态。

七、实操：如何用 trace 排查一次自动化任务

7.1 定位 trace 目录

# 在 ooo auto 的执行目录下，按会话 ID 查找 trace find . -path "*/.ouroboros/traces/*" -name "summary.md"

7.2 快速排查顺序

1. 看 Status：blocked→ 门控中止；complete→ 进入执行阶段；failed→ 内部失败；
2. 看 Blocker：5 attempt(s)+revise (score 0.72)的组合意味着 Seed QA 修复预算耗尽——问题不在代码执行，而在 Seed 契约本身；
3. 看 differences / suggestions：逐条对照"差异 → 建议"映射，判断是验收标准太泛、CLI 表面缺失还是持久化契约欠定义；
4. 看 Decision provenance histogram：timeout_default占比过高说明访谈收敛失败、大量字段落入确定性兜底；这类 Seed 即使评级为 A，也可能因缺乏具体契约而在 QA 门上反复失败；
5. 看 Counts 的 gated：gated 数量与 histogram 中model_inferred+timeout_default之和应当一致（本例均为 7）；
6. 看 Lateral records 与 Flags：lateral 记录说明修复阶段动用了横向思考；flags 中的 timeout/degraded/blocked 标记定位生命周期异常。

7.3 反查结构化数据

需要机器可读的细节时，读取同目录的outcome.json（含stop_reason_code、qa.differences、qa.suggestions、provenance_histogram、gate_findings、open_gaps）与decisions.jsonl（逐条查看promoted与gated标志）。文件清单与各流分类规则已在第一节给出。

结语：一份 trace 的三重价值

以auto_20b877d7935f这份 trace 为例，可以看到它同时承担了三种角色：运行档案（Status/Grade/Blocker 记录终态与阻塞原因）、质量诊断书（differences/suggestions 精确指出 Seed 契约的短板）、溯源审计单（provenance histogram 揭露契约字段的决策来源与门控占比）。当你在 ouroboros 的自动流水线中看到一条 blocked 的任务，第一步不应该是去读执行日志，而是打开这份 19 行的 summary.md——它已经把"为什么被拦下"和"接下来该改什么"写在了最显眼的位置。

阅读延伸：interview trace 导出实现、Seed QA 咨询层、Seed QA 门控主流程、决策溯源定义与推导、确定性评级门。

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具