Back to Details

sol-luna-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sol + Luna 分层子代理 Setup Skill

Sol + Luna 分层子代理配置Skill

Install: 
npx skills add Yuri-NagaSaki/subagent-skills -g -y

Repo: https://github.com/Yuri-NagaSaki/subagent-skills
Guide: https://catcat.blog/2026/08/sol-luna-layered-subagents-codex-claude-pi.html
安装命令: 
npx skills add Yuri-NagaSaki/subagent-skills -g -y

代码仓库: https://github.com/Yuri-NagaSaki/subagent-skills
指南文档: https://catcat.blog/2026/08/sol-luna-layered-subagents-codex-claude-pi.html

目标

目标

在不把密钥写入仓库的前提下，让项目具备：
  • 主会话 gpt-5.6-sol（领导）
  • 工人 gpt-5.6-luna（scout / worker / critic / tester）
  • 项目级配置可 git 共享
  • 可验证的冒烟结果
在不将密钥写入代码仓库的前提下，为项目实现以下能力：
  • 主会话代理 gpt-5.6-sol（领导角色）
  • 执行代理 gpt-5.6-luna（侦察/执行/审查/测试角色）
  • 项目级配置可通过Git共享
  • 可验证的冒烟测试结果

硬性安全规则

硬性安全规则

  1. 永远不要把 API Key、主机 IP、SSH 密码、私钥写进 
    config.toml
    、
    AGENTS.md
    、README、文章正文或 git commit。
  2. 密钥只用环境变量：
    OPENAI_API_KEY
    / 
    GATEWAY_API_KEY
    / 
    ANTHROPIC_API_KEY
    等。
  3. model_providers.*.env_key
    只写变量名。
  4. 大文件 
    models-v1.json
    默认 gitignore，用脚本生成。
  1. 绝对禁止将API密钥、主机IP、SSH密码、私钥写入
    config.toml
    、
    AGENTS.md
    、README、文章正文或Git提交记录。
  2. 密钥仅通过环境变量传递：
    OPENAI_API_KEY
    / 
    GATEWAY_API_KEY
    / 
    ANTHROPIC_API_KEY
    等。
  3. model_providers.*.env_key
    仅填写变量名称。
  4. 大文件
    models-v1.json
    默认加入gitignore，通过脚本生成。

前置

前置条件

  • Linux / macOS，Node.js 20+
  • 可访问的 OpenAI-compatible Responses 端点（
    wire_api = "responses"
    ）
  • 账号侧启用 
    gpt-5.6-sol
    与 
    gpt-5.6-luna
  • Linux / macOS操作系统，Node.js 20及以上版本
  • 可访问兼容OpenAI的Responses端点（配置
    wire_api = "responses"
    ）
  • 已在账号中启用
    gpt-5.6-sol
    与
    gpt-5.6-luna
    模型

标准流程（Agent 必须按序执行）

标准流程（Agent必须按顺序执行）

0. 探测

0. 环境探测

bash
node -v && npm -v
command -v codex || true
command -v claude || true
command -v pi || true
test -n "${OPENAI_API_KEY:-}" && echo "OPENAI_API_KEY=set" || echo "OPENAI_API_KEY=MISSING"
若缺少 Key：停止并要求用户 export，不要在对话外落盘明文。
bash
node -v && npm -v
command -v codex || true
command -v claude || true
command -v pi || true
test -n "${OPENAI_API_KEY:-}" && echo "OPENAI_API_KEY=set" || echo "OPENAI_API_KEY=MISSING"
若缺少密钥：停止操作并要求用户通过export设置，禁止在对话之外以明文形式存储密钥。

1. 安装 CLI

1. 安装CLI工具

bash
npm i -g @openai/codex @anthropic-ai/claude-code
bash
npm i -g @openai/codex @anthropic-ai/claude-code

可选

可选安装

npm i -g @earendil-works/pi-coding-agent
npm i -g @earendil-works/pi-coding-agent

或 curl -fsSL https://pi.dev/install.sh | sh

或使用curl安装

pi install npm:@kky42/pi-flow # 可选，需已装 pi
undefined
pi install npm:@kky42/pi-flow # 可选，需已安装pi
undefined

2. 全局个人默认（可选）

2. 全局个人默认配置（可选）

写入 
~/.codex/config.toml
（仅个人默认）：
  • model = "gpt-5.6-sol"
  • default_subagent_model = "gpt-5.6-luna"
  • [features] multi_agent = true
    ，
    multi_agent_v2 = false
    （配合 V1 catalog）
  • [model_providers.gateway]
    + 
    env_key = "OPENAI_API_KEY"
不要复制用户的真实 Key 进文件。
写入
~/.codex/config.toml
（仅作为个人默认配置）：
  • model = "gpt-5.6-sol"
  • default_subagent_model = "gpt-5.6-luna"
  • [features] multi_agent = true
    ，
    multi_agent_v2 = false
    （适配V1目录）
  • [model_providers.gateway]
    + 
    env_key = "OPENAI_API_KEY"
禁止将用户的真实密钥复制到文件中。

3. 项目级模板

3. 项目级模板配置

在项目根运行：
bash
bash /path/to/subagent-skills/scripts/bootstrap.sh "$(pwd)"
在项目根目录执行：
bash
bash /path/to/subagent-skills/scripts/bootstrap.sh "$(pwd)"

或安装 skill 后:

或安装Skill后执行:

bash ~/.claude/skills/sol-luna-setup/scripts/bootstrap.sh "$(pwd)"

bash ~/.claude/skills/sol-luna-setup/scripts/bootstrap.sh "$(pwd)"


会创建/更新：

```text
.codex/config.toml
.codex/agents/luna_{scout,worker,critic,tester}.toml
AGENTS.md
.claude/agents/luna-{scout,worker,critic}.md
CLAUDE.md
scripts/prepare-luna-catalog.sh
.gitignore 条目：.codex/models-v1.json、.env
保留用户已有无关配置；冲突时合并而非盲覆盖。

将创建/更新以下文件：

```text
.codex/config.toml
.codex/agents/luna_{scout,worker,critic,tester}.toml
AGENTS.md
.claude/agents/luna-{scout,worker,critic}.md
CLAUDE.md
scripts/prepare-luna-catalog.sh
.gitignore 条目：.codex/models-v1.json、.env
保留用户已有的无关配置；出现冲突时进行合并而非盲目覆盖。

4. 修复 Sol → Luna spawn（必做）

4. 修复Sol生成Luna代理的问题（必做）

症状：
text
Unknown model `gpt-5.6-luna` for spawn_agent.
Available models: gpt-5.6-sol, gpt-5.6-terra
原因：目录里 Sol/Terra 常为 multi-agent v2，Luna 为 v1，V2 过滤掉 Luna。
处理：
bash
bash scripts/prepare-luna-catalog.sh "$(pwd)/.codex/models-v1.json"
症状：
text
Unknown model `gpt-5.6-luna` for spawn_agent.
Available models: gpt-5.6-sol, gpt-5.6-terra
原因：目录中Sol/Terra通常为multi-agent v2版本，而Luna为v1版本，V2版本会过滤掉Luna。
处理方案：
bash
bash scripts/prepare-luna-catalog.sh "$(pwd)/.codex/models-v1.json"

将 model_catalog_json 设为该文件的绝对路径

将model_catalog_json设置为该文件的绝对路径

multi_agent_v2 = false

multi_agent_v2 = false

undefined
undefined

5. 验证（必须全部通过再宣称完成）

5. 验证（必须全部通过后方可宣告完成）

bash
undefined
bash
undefined

单模型（注意 </dev/null）

单模型验证（注意添加</dev/null）

codex exec --sandbox read-only -c 'model="gpt-5.6-sol"'
"Reply with exactly: SOL_SMOKE_OK" </dev/null
codex exec --sandbox read-only -c 'model="gpt-5.6-luna"'
"Reply with exactly: LUNA_SMOKE_OK" </dev/null
codex exec --sandbox read-only -c 'model="gpt-5.6-sol"'
"Reply with exactly: SOL_SMOKE_OK" </dev/null
codex exec --sandbox read-only -c 'model="gpt-5.6-luna"'
"Reply with exactly: LUNA_SMOKE_OK" </dev/null

多代理

多代理验证

codex exec --sandbox read-only
"按 AGENTS.md spawn luna_scout 只读说明仓库结构，输出以 SCOUT_DONE 开头" </dev/null
codex exec --sandbox read-only
"按AGENTS.md生成luna_scout代理，只读扫描仓库结构，输出以SCOUT_DONE开头" </dev/null

可选 Pi

可选Pi验证

export GATEWAY_API_KEY="${OPENAI_API_KEY}" pi --print --provider gateway --model gpt-5.6-sol --no-session --no-tools "Reply: PI_SOL_OK" pi --print --provider gateway --model gpt-5.6-luna --no-session --no-tools "Reply: PI_LUNA_OK"

Claude Code：

- 非 root 用户更稳妥
- 对 haiku 做一次 `claude -p` 冒烟；若网关 Anthropic 通道 502，记录为供应商问题，仍可提交 agents 文件
export GATEWAY_API_KEY="${OPENAI_API_KEY}" pi --print --provider gateway --model gpt-5.6-sol --no-session --no-tools "Reply: PI_SOL_OK" pi --print --provider gateway --model gpt-5.6-luna --no-session --no-tools "Reply: PI_LUNA_OK"

Claude Code验证说明：

- 使用非root用户更安全
- 对haiku模型执行一次`claude -p`冒烟测试；若网关Anthropic通道返回502错误，记录为供应商问题，仍可提交agents文件

6. 交付报告模板

6. 交付报告模板

markdown
undefined
markdown
undefined

Sol-Luna Setup Report

Sol-Luna配置报告

  • Host OS / Node / Codex / Claude / Pi versions:
  • Project path:
  • Files created:
  • Catalog fix applied: yes/no
  • SOL_SMOKE: pass/fail
  • LUNA_SMOKE: pass/fail
  • MULTI_AGENT SCOUT_DONE: pass/fail
  • Pi SOL/LUNA: pass/fail/skip
  • Secrets in git: none (confirmed)
  • Next user action:
undefined
  • 主机系统/Node/Codex/Claude/Pi版本:
  • 项目路径:
  • 创建的文件:
  • 是否应用目录修复: 是/否
  • SOL_SMOKE测试: 通过/失败
  • LUNA_SMOKE测试: 通过/失败
  • MULTI_AGENT SCOUT_DONE测试: 通过/失败
  • Pi SOL/LUNA测试: 通过/失败/跳过
  • Git中是否包含密钥: 无（已确认）
  • 用户下一步操作:
undefined

角色政策（写入 AGENTS.md）

角色政策（写入AGENTS.md）

角色模型权限
主会话 Solgpt-5.6-sol规划、审核、commit/PR
luna_scoutgpt-5.6-lunaread-only
luna_workergpt-5.6-lunaworkspace-write，禁止 commit
luna_criticgpt-5.6-lunaread-only 对抗审查
luna_testergpt-5.6-luna跑指定测试，返回证据
角色模型权限
主会话Solgpt-5.6-sol规划、审核、提交代码/PR
luna_scoutgpt-5.6-luna只读权限
luna_workergpt-5.6-luna工作区写入权限，禁止提交代码
luna_criticgpt-5.6-luna只读对抗审查权限
luna_testergpt-5.6-luna执行指定测试，返回验证证据

常见失败

常见问题与处理方案

现象处理
spawn 无 LunaV1 catalog + multi_agent_v2=false
codex 吞掉后续 shell
codex exec ... </dev/null
wire_api 报错使用 
responses
；确认网关实现 
/v1/responses
Claude root 拒绝 bypass换非 root 或降低 permission mode
工人写冲突降并发、按文件分区
密钥进 diff立即剔除、轮换密钥
现象处理方案
无法生成Luna代理使用V1目录+设置multi_agent_v2=false
codex阻塞后续shell命令添加
codex exec ... </dev/null
wire_api报错使用
responses
端点；确认网关实现
/v1/responses
Claude root用户拒绝绕过限制切换非root用户或降低权限模式
执行代理写入冲突降低并发、按文件分区执行
密钥出现在diff中立即移除、轮换密钥

参考文件

参考文件

Agent 行为准则

Agent行为准则

  • 先探测、再安装、再写项目文件、再修 catalog、再验证。
  • 展示关键 diff；不覆盖无关用户配置。
  • 验证失败时给出可执行修复，不要假装成功。
  • 用户若要求「只配置 Sol 和 Luna」：不要启用 Terra 作为默认，catalog 里可保留 Terra 条目仅用于兼容。
  • 先探测环境、再安装工具、再生成项目文件、再修复目录、最后执行验证。
  • 展示关键配置差异；不覆盖用户已有的无关配置。
  • 验证失败时提供可执行的修复方案，禁止伪造成功结果。
  • 若用户要求「仅配置Sol和Luna」：不要将Terra设为默认模型，目录中可保留Terra条目仅用于兼容。