一个TOML文件锁定角色的秘密：Sol Advisor三个自定义Agent定义全解析-平芜编程栈

一个TOML文件锁定角色的秘密：Sol Advisor三个自定义Agent定义全解析

【免费下载链接】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 的多 Agent 协作工作流：主会话 Sol 负责架构与验收，而 Luna、Terra、Sol 审查员这三个自定义 Agent 的 TOML 定义文件则把"谁、用什么模型、以多强的推理"写死在文件里。这篇文章带你读懂 Sol Advisor 的三个 Agent 定义，搞懂"一个 TOML 文件锁定角色"背后的完整机制。🔐

Sol Advisor 是什么：一条三人流水线

如果你用过 AI 写代码，多半体验过"一个模型又当架构师又当程序员又当审稿人"的混乱。Sol Advisor 的做法是分角色流水线：主会话（Sol / High）当架构师，负责需求、规格和验收；实现与评审则交给三个用 TOML 锁定的原生自定义 Agent。

角色	模型（TOML 中写死）	推理强度	职责
🌙 Luna 实现员	`gpt-5.6-luna`	max	默认承担边界清晰的例行实现
🌍 Terra 实现员	`gpt-5.6-terra`	high	高风险 / 强判断工作的升级通道
☀️ Sol 审查员	`gpt-5.6-sol`	high + 只读沙箱	最终评审，只能给出`ship`/`fix-first`/`rethink`

三个角色分别对应三个文件，都放在 plugins/sol-advisor/agents/ 目录下：

sol-advisor-luna-implementer.toml
sol-advisor-terra-implementer.toml
sol-advisor-sol-reviewer.toml

核心秘密：为什么一个 TOML 文件就能"锁定"角色

每个 Agent 定义文件只有寥寥几行，核心就是下面这些字段（以 Luna 为例）：

name = "sol_advisor_luna_implementer" model = "gpt-5.6-luna" model_reasoning_effort = "max"

别小看这几行，它们各自承担一项"锁定"职责：

name是身份的身份证。主会话派发任务时必须写死agent_type: sol_advisor_luna_implementer这样的精确名称，名字对不上就启动不了对应角色。
model+model_reasoning_effort写死能力档位。角色一旦装好，模型和推理强度就由 TOML 决定，派发时不再附加任何"本次换个模型试试"的参数——想"临时换人"在机制上就不成立。
developer_instructions是岗位说明书。用一段固定指令写清角色的边界：能做什么、禁止做什么、遇到什么情况必须上报。

这就是标题里"锁定"的全部含义：角色不是靠约定，而是靠文件本身来保证的。

逐个拆解：三个 Agent 的定义全解析

🌙 Luna 实现员：例行任务的默认通道

打开 sol-advisor-luna-implementer.toml，description一句话定调："默认例行实现通道，处理有边界、已完全规格化的工作"。

它的指令里有三条很有分量的规矩：

只做规格内的活：执行主会话给出的五段式实现规格（目标、文件归属、接口、约束、验证），只碰自己名下的文件，不推翻别人并行的修改；
不许越级改架构：发现歧义、范围冲突或验证失败时，只许上报，不许自己重新设计；
误判必须喊停：如果修正一次后发现这活其实"需要强判断或高风险"，Luna 要返回信号让主会话升级到 Terra，而不是硬着头皮继续做。

一句话：Luna 是流水线上的"默认档"，快、稳、守边界。

🌍 Terra 实现员：明确的升级通道

sol-advisor-terra-implementer.toml 里description直接写明自己是"显式高复杂度升级通道"。和 Luna 不同，Terra 只有两条明确的入场券：

一开始就认定：主会话判断这活儿是强判断、高风险、影响面宽的（比如跨模块迁移）；
事后证明误判：Luna 修正一次后暴露出"这活根本不是例行活"。

指令要求和 Luna 一样守住接口与文件边界，但差异在于定位：Terra 不是"更勤快的人"，而是专门处理超出常规档位的工作。没有这两条入场券，Terra 不该上场——这也是"显式升级"（explicit escalation）的含义。

☀️ Sol 审查员：唯一带只读沙箱的验收官

sol-advisor-sol-reviewer.toml 是三个文件里最特殊的，因为它多了一个字段：

sandbox_mode = "read-only"

这行把审查员的沙箱直接钉在只读模式：它看不到修改权限，物理上就无法"顺手把代码改了"。配合指令里的两条铁律——

只许看，不许改：不许创建、修改、删除任何文件，评审基于全新上下文（fresh context）检查真实 diff 与验证证据；
只许给一个结论：ship（可以上线）、fix-first（小修后重审）或rethink（架构得重来）。一旦做了修复，旧结论立即作废，必须重新发起一次全新评审。

"评审员不许自己修自己审的东西"，这是整个流程里最能保证评审独立性的设计。

配套的验证机制：不通过就停线

"锁定"不只是写在文件里，Sol Advisor 还配了一整套验证动作，核心思想是任何一环对不上就停线，绝不悄悄降级：

逐字节校验：install-agents.sh 的--check模式会把本机安装的三个角色文件与官方模板逐字节比对，缺一、被改、版本旧都会报冲突；
派发前预检：编排技能 SKILL.md 要求在每次派发前确认三个agent_type名称都被原生识别，名字缺一个就停该通道；
运行时核对：spawn 后的元数据必须能指出选中的就是那个自定义角色；拿不到运行时信息时，可用 inspect-agent-runtime.sh 做只读核查。

完整的派发格式、五段式规格模板和评审返回结构，都写在 role-contracts.md 里，想深入可以直接读原文。

快速上手：3 步装好三个 Agent

添加插件：把 sol-advisor 仓库添加为 Codex 插件源后执行codex plugin add sol-advisor@sol-advisor；
安装角色模板：运行sh "$plugin_dir/scripts/install-agents.sh"，再跑一次--check做逐字节校验（三个角色文件不会随插件自动注册，必须单独安装，且它不会覆盖已有文件）；
开启新任务：原生 Agent 只在任务创建时发现，所以装完要新开一个 Codex 任务，主会话选择 GPT-5.6 Sol + High 推理，即可开始"Sol 计划 → Luna 实现 → Sol 评审"的完整流程。