企业官网建设流程全解析

如何证明Agent真的用对模型？Sol Advisor运行时证据检查器实战指南

【免费下载链接】sol-advisorCodex-native architect orchestration with Luna and Terra implementation lanes and mandatory fresh Sol review.项目地址: https://gitcode.com/gh_mirrors/so/sol-advisor

Sol Advisor 是一款面向 Codex 的架构师编排工作流插件：主会话由 Sol / High 负责规划，Luna / Max 实现常规任务，Terra / High 处理高风险升级，最后由一个全新的 Sol / High 复审。它最有意思的能力，是内置的运行时证据检查器（runtime evidence inspector）——一条本地只读脚本 inspect-agent-runtime.sh，能帮你"用数据说话"：证明某个子 Agent 运行时到底用了哪个模型、哪一档推理强度，而不是靠口头汇报。🔍

为什么"模型路由"需要运行时证据？

用过多 Agent 编排的同学可能都有过这样的困惑：

• 🤔 我要求 Agent 用"强模型"做关键任务，但 UI 里只显示了 Agent 名字，看不到实际模型；
• 🤔 子 Agent 汇报"完成了"，可它真的跑在预期模型上吗？还是悄悄降级了？
• 🤔 公开元数据里没有 model / effort 字段，我拿什么做验收依据？

Sol Advisor 给出的答案是三件套闭环：

1. 配置锁定：每个角色的模型和推理强度由角色 TOML 文件"钉死"，spawn 时不允许逐次覆盖；
2. 安装校验：用 install-agents.sh 的--check模式做非破坏性的字节级比对；
3. 运行时证据：用运行时证据检查器读取会话 rollout 文件，提取真实的路由字段——这就是本文的主角。

Sol Advisor 的三条角色泳道与模型锁定

Sol Advisor 把交付拆成三条原生角色泳道，每条泳道绑定固定的"模型 + 推理强度"组合：

这些"钉子"来自三个角色模板文件：

• sol-advisor-luna-implementer.toml：model = "gpt-5.6-luna"、model_reasoning_effort = "max"
• sol-advisor-terra-implementer.toml：model = "gpt-5.6-terra"、model_reasoning_effort = "high"
• sol-advisor-sol-reviewer.toml：model = "gpt-5.6-sol"，并且申请read-only沙箱

💡 关键设计：spawn 调用只写agent_type和fork_turns: none，从不附加逐次的 model 或 effort 覆盖。模型由角色文件决定，证据才有"标准答案"可以对照。

运行时证据检查器：只读、白名单、不猜测

检查器的实现非常克制（完整源码见 inspect-agent-runtime.sh），核心逻辑分三步：

第一步：精确定位会话文件。Codex 会把每个线程的对话写入rollout-*-<线程ID>.jsonl文件。检查器要求你传入一个标准小写 UUID 线程 ID，然后在会话目录（默认~/.codex/sessions，可用--sessions-dir指定）中查找文件名以该 ID 结尾的 rollout——必须恰好匹配一个文件，0 个或 2 个以上都会直接报错退出。

第二步：白名单字段提取。用jq从 rollout 中只抽取路由相关的元数据（角色、模型、推理强度、沙箱策略等），输出一个紧凑 JSON 对象。

第三步：一致性裁决。如果同一线程内出现冲突的模型、effort、沙箱策略或工作目录，或者 session 元数据与线程 ID 对不上——全部报错，绝不"猜一个"。

这正是它的设计哲学：fail-closed（失败即拒绝）。证据缺失、不一致、不可观察时，它宁可让你停下排查，也绝不推断一个"大概的"模型值。

最快上手：4 步拿到第一条运行时证据

第 1 步：找到已安装插件的路径。插件安装后，Codex 会记录它的来源路径：

plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')"

第 2 步：拿到子 Agent 的线程 ID。在编排流程中 spawn 子 Agent 后，公开元数据里会有它的原生线程 ID（一个 UUID）。

第 3 步：运行检查器：

sh "$plugin_dir/scripts/inspect-agent-runtime.sh" <native-subagent-thread-id>

第 4 步：对照下表验收。输出里的 model / effort 必须与角色锁定的值一致：

如果你的本地会话目录不在默认位置（比如一次性测试环境），加一个参数即可：

sh "$plugin_dir/scripts/inspect-agent-runtime.sh" --sessions-dir /absolute/path/to/sessions <native-subagent-thread-id>

输出长什么样？字段速查

一次成功检查会输出类似这样的 JSON（字段全部来自白名单）：

{ "thread_id": "11111111-1111-7111-8111-111111111111", "parent_thread_id": "00000000-0000-7000-8000-000000000000", "agent_role": "sol_advisor_luna_implementer", "model_provider": "openai", "model": "gpt-5.6-luna", "effort": "max", "sandbox_policy_type": "danger-full-access", "permission_profile_type": "disabled", "cwd": "/fixture" }

逐字段解读：

• 🧭agent_role / parent_thread_id：确认这个线程确实是目标角色、且挂在你预期的父会话下；
• 🎯model / effort：核心证据——模型与推理强度是否命中角色锁定值；
• 🔒sandbox_policy_type / permission_profile_type：对复审泳道尤其重要——角色文件申请了只读沙箱，但宿主环境可能放宽了权限，只有观察到的值才算数；
• 📂cwd：确认工作目录没有跑偏。

注意：输出是白名单的。rollout 里可能包含完整对话内容，但检查器只构造路由元数据对象，对话内容绝不会出现在输出里（仓库自带的 verify.sh 验证脚本甚至专门断言了"提示词内容不得泄漏"）。

检查器报错？读懂每一条失败信号

检查器的每一类报错都不是"程序坏了"，而是一条明确的验收信号：

这套"缺失、不一致、不可观察就停线"的规则，与 SKILL.md 中的验收门禁完全一致："Missing, inconsistent, unavailable, or unobservable routing stops that lane."（缺失、不一致、不可用或不可观察的路由证据会终止该泳道。）

什么时候必须跑证据检查？验收门禁流程

按 SKILL.md 和 role-contracts.md 的编排规范，证据检查是"spawn 之后、接受结果之前"的必做步骤：

1. 先读公开元数据（public spawn/details metadata）：它必须能标识出所选的自定义角色；若其中已暴露 model / effort，直接与角色锁定值比对；
2. 公开元数据缺字段时才用检查器兜底：当 model 或 effort 被省略、且本地 rollout 可读时，运行运行时证据检查器，其白名单输出是本地权威回退来源；
3. 两份证据并存时必须一致：公开元数据和本地 rollout 都给出值时，两者必须吻合，任何分歧都视为验收失败；
4. 复审泳道额外记录沙箱：捕获观察到的沙箱策略类型和权限配置类型；只有观察值确实是read-only时，才能宣称复审是"操作系统强制只读"的。

同时别忘了 spawn 前的两道前置检查：install-agents.sh --check证明三个角色文件与模板字节级一致，以及原生环境确实暴露了三个精确角色名。

常见问题 FAQ

Q：检查器能帮我修正或覆盖模型吗？不能。它是纯只读的"证据读取器"。模型和推理强度只能由角色 TOML 锁定，这也是为什么 spawn 时禁止携带逐次覆盖字段——一旦允许覆盖，证据标准答案就不存在了。

Q：为什么不让我直接 cat 那个 rollout 文件？直接读会看到整段对话（含敏感内容），且没有一致性裁决。检查器做了三件你手工做不好的事：按线程 ID 精确匹配唯一文件、只输出白名单路由字段、对缺失与冲突值做 fail-closed 报错。

Q：公开元数据已经显示了模型，还需要跑检查器吗？不需要。检查器定位是"公开细节缺字段时的本地回退"；两者都有值时则以"必须一致"为准。

小结

Sol Advisor 运行时证据检查器把"Agent 到底用没用对模型"从主观感觉变成了可复核的硬证据：

• 📌锁定：角色 TOML 钉死模型与推理强度，spawn 不覆盖；
• ✅校验：install-agents.sh --check保证安装副本与模板字节级一致；
• 🔍取证：inspect-agent-runtime.sh 从会话 rollout 中提取白名单路由字段，缺失或不一致即拒绝；
• 📖规则：SKILL.md 与 role-contracts.md 定义了"公开元数据优先、本地检查器兜底、两份证据必须一致"的完整门禁。

当你需要对外证明"这条交付链路确实运行在约定模型上"时，一次检查器的白名单输出，就是一份干净的运行时证据。✨

【免费下载链接】sol-advisorCodex-native architect orchestration with Luna and Terra implementation lanes and mandatory fresh Sol review.项目地址: https://gitcode.com/gh_mirrors/so/sol-advisor