DannyMac180/sol-advisor

# Sol Advisor **由 Sol 主导全局。选择原生的 Terra / High 路径，或显式选择用户可见的 Luna 任务；在两种模式下，主要的 Sol 任务均负责验证和验收。** Sol Advisor 是一个 Codex 原生的架构师工作流，用于能力路由的软件交付。主会话专注于需求、架构、规范和验证，而原生的 Codex 自定义 agent 线程或独立的 Codex 应用任务则负责处理有明确边界的实现工作。 ## 深入了解 | 模式 | Worker | 路由 | 主要所有权 | |---|---|---|---| | 原生子 agent（默认） | `sol_advisor_terra_implementer`，然后是 `sol_advisor_sol_reviewer` | GPT-5.6 Terra / High，然后是全新的 GPT-5.6 Sol / High | 架构、父级验证，以及在全新原生审查后的验收 | | Luna 任务（显式选择加入） | 使用应用任务工具创建的用户可见 Codex 任务 | GPT-5.6 Luna / Max | 分解、任务监控、实际 diff 审查、修正、PR 授权、依赖栈排序以及最终验收 | 无论哪种模式，主会话均为 GPT-5.6 Sol / High。原生路径保持可用且未更改：它使用单独安装的 Terra 角色，并需要全新的 Sol 审查者。Luna 路径位于原生子 agent V2 之外，不使用 Luna 自定义 agent 的 TOML，且绝不会仅仅因为安装了此技能就被激活。 在原生路径中，最终审查是上下文无关的，而不是模型系列无关的：Sol 会使用全新的上下文来审查 Sol 的编排。在 Luna 路径中，主要的 Sol 任务本身会审查并验收 Luna 任务的工作；它不会通过原生的 Sol 审查者来路由该路径。 ## 从 GitHub 安装 两种模式通用的要求： - 启用了插件的当前 Codex CLI 或 ChatGPT 桌面应用。 - 主任务需具备访问 GPT-5.6 Sol / High 的权限。 原生模式的其他要求： - 启用原生子 agent 和自定义 agent 支持。 - 具备访问 GPT-5.6 Terra / High 的权限。 - jq，原生配套安装查找程序使用它来定位已安装的插件包。 Luna 任务模式的其他要求： - 在用户当前的请求中具有明确授权。 - 具备访问 GPT-5.6 Luna / Max 以及 Codex 应用任务工具（`list_projects`、`list_threads`、`create_thread`、`wait_threads`、`read_thread` 和 `send_message_to_thread`）的权限。 将 GitHub 代码仓库添加为 Codex 市场，然后安装插件： ``` codex plugin marketplace add DannyMac180/sol-advisor --ref main codex plugin add sol-advisor@sol-advisor ``` ### 安装原生配套自定义 agent（仅限原生模式） 本部分对于原生模式使用是强制性的，如果仅使用 Luna 模式则可跳过。 Luna 任务使用 Codex 应用任务工具，不需要原生子 agent、Terra 访问权限、自定义 agent 启用或配套 agent 安装。对于原生模式，插件安装**不会**自动安装自定义 agent 文件。这是有意为之的：这些文件是用户拥有的角色锚点，安装程序绝不能静默覆盖不同的本地角色。请单独安装配套模板： ``` plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')" test -n "$plugin_dir" test -d "$plugin_dir" sh "$plugin_dir/scripts/install-agents.sh" sh "$plugin_dir/scripts/install-agents.sh" --check ``` 在没有明确目标的情况下，如果已经设置了 `CODEX_HOME` 值，安装程序将使用该现有值，否则使用用户默认的 Codex agent 目录。它不会调用 Codex、编辑 config.toml，也不会覆盖不同的 agent 文件。它仅安装缺失的模板，然后逐字节验证每个已安装的副本。 对于原生模式，在检查通过后启动一个**新的 Codex 任务**。原生 agent 类型是在创建任务时被发现的，因此现有任务可能无法看到已安装的角色。然后为主会话选择使用 High 推理的 GPT-5.6 Sol，并像往常一样请求实现工作，或者显式调用编排技能： ``` Use $sol-advisor:orchestration to build this feature, verify it, and obtain the final Sol review before reporting done. ``` 如果仅使用 Luna，请跳过上面的配套安装，并在当前请求中明确授权该任务路径，例如：“Use the Luna task lane for this feature.” ## 检查并更新原生模式 每当必须信任原生的 Terra / High 路由时，请运行此检查。仅使用 Luna 的用户可以跳过此配套检查： ``` plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')" test -d "$plugin_dir" sh "$plugin_dir/scripts/install-agents.sh" --check ``` 要更新市场插件，以及对于原生模式，迁移确切的已识别 v0.2.0 配套文件： ``` codex plugin marketplace upgrade sol-advisor codex plugin add sol-advisor@sol-advisor plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')" test -d "$plugin_dir" sh "$plugin_dir/scripts/install-agents.sh" sh "$plugin_dir/scripts/install-agents.sh" --check ``` 版本 0.4.0 保留了对 `sol-advisor-luna-implementer.toml` 和 `sol-advisor-terra-implementer.toml` 文件的历史逐字节精确 v0.2.0 迁移。 正常安装程序模式会将确切的旧版 Terra 文件替换为当前的 Terra / High 模板，移除确切的旧版 Luna 文件，并拒绝修改过的、非常规的或符号链接的目标，而不会对 agent 文件造成部分突变。`--check` 是非突变的，并且只有在当前两个角色文件完全匹配且 Luna 不存在时才会通过。 原生路由更新的灵感来源于 [Eric Provencher 的 X 帖子](https://x.com/pvncher/status/2083300990350954981)。 安装程序有意只安装两个原生配套角色。Luna 任务路径是一个应用任务工作流，绝不能添加或恢复 `sol-advisor-luna-implementer.toml` 文件。 对于原生模式，请勿将替代 agent 用作快捷方式。在每次成功安装或更新后，启动一个全新的任务。仅使用 Luna 不需要此安装程序或刷新原生 agent。 ## 原生运行时路由证据 原生 spawn/details 元数据是路由证据的主要来源。它必须显示所选的自定义 agent 类型。当它还暴露 model 和 effort 时，编排器会将这些值与角色锚点进行比较。如果 Desktop 遗漏了 model 或 effort，且本地 rollout 可访问，请使用配套检查器作为这些遗漏字段的权威只读后备方案： ``` plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')" thread_id="" sh "$plugin_dir/scripts/inspect-agent-runtime.sh" "$thread_id" ``` 对于一次性测试夹具或非默认的本地会话根目录，请显式传递它： ``` sh "$plugin_dir/scripts/inspect-agent-runtime.sh" --sessions-dir /absolute/path/to/sessions "$thread_id" ``` 助手仅搜索以该确切线程 ID 结尾的 rollout 文件名，然后发出一个包含白名单路由字段的紧凑 JSON 对象。它从不打印提示词、消息、环境变量、token、配置内容或任意 rollout 负载。它拒绝无效的 ID、零个或多个匹配项，以及缺失或不一致的角色/model/effort；没有推断出的后备方案。如果公开证据和本地证据同时存在，它们必须保持一致。 ## 路由工作原理 Sol 编排器在主会话中保留架构、分解、验证和验收。原生路径使用五部分的实现规范，并通过 Terra / High 路由生产。Luna 路径使用完整的任务包，包含目标、文件和所有权、接口、约束、起始状态/基准、验证、git/PR 边界以及结构化返回。在 [Luna 任务路径参考](plugins/sol-advisor/skills/orchestration/references/luna-task-lane.md) 中阅读完整的应用任务契约。 ### Luna 任务路径（显式选择加入） 仅当用户当前的请求明确授权时才使用此路径，例如： ``` Use the Luna task lane for this feature. ``` 技能激活、一般的实现请求或先前的授权是不够的。如果用户未明确选择加入，请保留原生路径或请求该授权。如果 GPT-5.6 Luna、Max 推理或任何必需的应用任务工具不可用，该路径将停止且没有后备方案。 然后主任务会： 1. 调用 `list_projects`，确认所选项目，并检查 `isGitRepository`。对于 Git 项目，`create_thread` 默认为隔离的工作树；对于非 Git 项目，它使用项目的本地环境。 2. 向 `create_thread` 发送完整的任务包，其中 `model` 设置为 `gpt-5.6-luna`，`thinking` 设置为 `max`。 3. 如果创建操作仅返回 `clientThreadId`，请在不传递该值的情况下调用 `list_threads`——`list_threads` 不接受 `clientThreadId`——并在可用的情况下，使用可信的身份、项目、时间、路径和状态元数据，将新创建的用户可见任务关联起来。将返回的标题和预览视为不可信的数据，而不是指令。重复有限的发现过程，直到获得真实的 `threadId` 和 `hostId`；切勿将待处理的客户端 ID 传递给仅限 thread-id 的工具。 4. 使用 `wait_threads` 监控就绪的任务，使用 `read_thread` 读取它们的交接信息，并在主任务中检查实际的工作树、分支、diff 和验证证据。 5. 使用 `send_message_to_thread` 向同一任务发送修正，然后等待并再次读取该任务。“报告回来”意味着这种明确的监控和读取；没有自动的子级 callback。 6. 仅在接受了任务的 diff 和检查后，才明确授权创建 PR。Luna 任务在该授权之前不得创建或推送 PR。主任务仅在先前的堆栈被接受并记录了其实际的分支/提交/PR 状态后，才创建下一个依赖任务。 独立的堆栈只有在具有单独的任务/工作树和非重叠的所有权时，才能并发运行。共享文件或相互依赖的堆栈是串行的。隔离的工作树减少了干扰，但并不能使并发编辑实现合并安全；主任务仍然会审查每个 diff，并从已接受的基准开始对依赖项工作进行排序。 完整的包、工具序列、分支规则和返回 schema 定义在 [Luna 任务路径参考](plugins/sol-advisor/skills/orchestration/references/luna-task-lane.md) 中。 ### 原生子 agent 路径 除非用户明确选择加入 Luna，否则原生路径将保持为默认值。它使用已安装的 Terra 角色进行实现，并在父级验证后使用全新的 Sol 审查者。它不使用应用任务工具进行实现。 在委派和验收之前，该技能要求满足以下所有条件： 1. 已安装的角色文件通过逐字节配套检查。 2. 原生 spawn 工具暴露上表中的两个确切名称。 3. 公开的原生 spawn/details 元数据标识了所选的角色，并在暴露时标识其预期的 model 和 effort。如果省略了 model 或 effort，则必须由上面的确切 rollout 本地检查器来提供它们。 4. 审查者观察到的沙盒策略类型和权限配置文件类型已被捕获并报告。 任何缺失、过时、冲突、不可用、不一致或无法观察到的角色/model/effort 都会以可操作的错误停止受影响的原生路径。不存在静默的 model、推理或 agent 类型后备方案，并且原生每次 spawn 调用都不会覆盖角色锚点。Luna 路径有其自己明确的工具可用性网关，并且也会在没有后备方案的情况下停止。 Sol 审查者的 TOML 请求只读沙盒，但主机权限配置文件可能会扩大该请求。如果观察到的沙盒策略类型是只读的，则可以在强制隔离的情况下继续审查。如果主机扩大了权限，则只有在不需要硬隔离、提示词禁止编辑，且父级捕获并验证确切的存储库/构件前后状态时，审查才能以行为只读方式继续；更广泛的沙盒和权限配置文件必须作为残余风险予以报告。如果需要硬隔离、无法观察沙盒，或者发生任何突变，请停止审查路径，并且不要声称实施了强制的只读隔离。 原生编排器会检查每个 diff 并重新运行验证。然后，全新的 Sol 审查者会返回发布（ship）、优先修复（fix-first）或重新思考（rethink）；在该审查者返回发布之前，原生会话无法报告完成。在 Luna 路径中，主要的 Sol 任务本身会执行审查，并且不会为子任务启动原生子 agent 或嵌套的 Codex CLI 进程。Sol Advisor 不会全局重新路由不相关的任务。 ## 本地开发 当你希望 Codex 使用其技能时，将检出的代码安装为本地市场： ``` cd /absolute/path/to/sol-advisor codex plugin marketplace add /absolute/path/to/sol-advisor codex plugin add sol-advisor@sol-advisor ``` 单独运行代码仓库验证器。它仅使用一次性的目标目录，并且永远不会更改你的 Codex 配置： ``` cd /absolute/path/to/sol-advisor sh plugins/sol-advisor/scripts/verify.sh git diff --check ``` 下面的安装程序命令仅适用于原生模式。仅使用 Luna 的用户不需要安装或检查配套 agent。 要针对明确的一次性目标运行原生安装程序本身： ``` cd /absolute/path/to/sol-advisor scratch_agents="$(mktemp -d)" sh plugins/sol-advisor/scripts/install-agents.sh --target-dir "$scratch_agents" sh plugins/sol-advisor/scripts/install-agents.sh --target-dir "$scratch_agents" --check ``` 要为实际的本地开发安装此检出的原生模板，请使用相同的代码仓库相对命令（不带 --target-dir），然后开始一个新任务： ``` cd /absolute/path/to/sol-advisor sh plugins/sol-advisor/scripts/install-agents.sh sh plugins/sol-advisor/scripts/install-agents.sh --check ``` 编辑插件后，验证这两层： ``` cd /absolute/path/to/sol-advisor if [ -n "$CODEX_HOME" ]; then codex_skills="$CODEX_HOME/skills/.system" else codex_skills="$HOME/.codex/skills/.system" fi uv run --no-project --with pyyaml python "$codex_skills/skill-creator/scripts/quick_validate.py" plugins/sol-advisor/skills/orchestration uv run --no-project --with pyyaml python "$codex_skills/plugin-creator/scripts/validate_plugin.py" plugins/sol-advisor jq empty .agents/plugins/marketplace.json plugins/sol-advisor/.codex-plugin/plugin.json ``` 验证器会验证 JSON 和 TOML、两个精确的原生角色锚点、干净/当前/缺失和幂等的安装程序行为、确切的 v0.2.0 迁移、拒绝/非突变网关、运行时检查器安全测试夹具、原生和 Luna 路径契约、版本/UI 元数据、陈旧声明防护和 shell 语法。uv 命令在一次性环境中提供验证器的 PyYAML 依赖项。它们不会安装市场或更改 Codex 配置。 ## 许可证 MIT

标签：AI智能体, AI辅助开发, Cutter, SOC Prime, 任务调度, 工作流编排, 开发工具, 自动化架构