SOLUNA Codex Router

English

SOLUNA Codex Router 是一套適用於 Codex 的 Sol–Luna 工作路由與安全安裝工具。它讓 Sol 保留整體決策與整合責任，再將明確、可驗證的工作交給對應的 Luna 代理執行。

專案特色

• 受界定的 Sol–Luna 分工：Sol 負責任務拆解、風險判斷與結果整合；Luna 只執行固定範圍的工作。
• 四種代理 profile：命令檢查、精準修補、低耦合任務與唯讀研究，各自有清楚的使用邊界。
• 安全整合安裝：預設 V1 只更新 SOLUNA 管理的設定；值相同時不重寫，值不同時只修改對應欄位，並保留其他使用者內容。
• 可明確返回 V2：指定 --mode v2 會保留或安全回復 Codex 原始／目前預設 catalog，不建立額外支援目錄。
• 跨平台支援：Windows、macOS、Linux 與 WSL 均可透過 PowerShell 7 使用相同安裝流程。
• 完整生命週期指令：支援預設 V1 安裝、檢查、修復、解除安裝，以及明確的 V2 安裝／回復功能。

安裝

需求：Node.js 18 以上與 PowerShell 7（pwsh）。npm 套件沒有 postinstall，只有明確執行 install 時才會修改 Codex 檔案。

全域安裝（預設）

未指定路徑時，安裝會使用目前使用者的全域 Codex 位置：

• Codex 設定：$HOME/.codex
• 使用者技能：$HOME/.agents/skills

使用 npm 全域安裝 CLI：

npm install --global soluna-router@latest
soluna-router install

更新既有全域 CLI：

npm install --global soluna-router@latest

不安裝 CLI 也可以直接使用 npx；這仍然會安裝到上述全域 Codex 位置：

npx --yes soluna-router@latest install

安裝模式預設為 V1。直接執行 install 會啟用 V1 catalog 相容設定；若要保留或返回 Codex 的 V2／預設 catalog，請明確指定 V2：

soluna-router install
soluna-router install --mode v1
soluna-router install --mode v2

V1 會在路由檔案安裝完成後安全整合 config.toml、models-v1.json 與 Explorer 設定；相同的受管理值不會重寫，不同值只修改對應欄位。V2 會維持 Codex 原始／目前預設設定；若偵測到既有 V1 交易狀態，會安全回復受管理欄位並保留其他使用者設定。

Luna 代理的思考強度預設為 xhigh，可指定以下值：max、xhigh、high、medium、low。

soluna-router install --luna-reasoning-effort high

Luna Fast service tier 預設關閉；需要為 Luna 子代理啟用時，指定 true。關閉時指定 false，可用值只有 true 與 false：

soluna-router install --luna-fast-mode true
soluna-router install --luna-fast-mode false

PowerShell 腳本使用 -LunaFastMode true|false，此參數設定代理 profile 的 service_tier = "fast"，不會更換 Luna 模型 ID。

專案安裝（必須明確指定路徑）

只切換目前工作目錄不會改成專案安裝。必須同時指定：

• -UserHome：專案根目錄，放置專案的 .agents/skills
• -CodexHome：專案 Codex 目錄，通常是專案根目錄下的 .codex

npx --yes soluna-router@latest install `
  -UserHome "D:\Projects\demo" `
  -CodexHome "D:\Projects\demo\.codex" `
  --mode v1 `
  --luna-reasoning-effort medium

或直接執行安裝腳本：

pwsh -ExecutionPolicy Bypass -File .\install.ps1 `
  -UserHome "D:\Projects\demo" `
  -CodexHome "D:\Projects\demo\.codex" `
  -Mode V1 `
  -LunaReasoningEffort medium

Windows 也可以在原始碼或解壓縮的套件目錄執行：

.\一鍵安裝.cmd -LunaReasoningEffort medium -LunaFastMode false

專案安裝時兩個路徑都必須指定，避免 .codex 寫入專案、技能卻寫入全域使用者目錄。使用該專案時，請讓 Codex 使用相同的 CODEX_HOME：

$env:CODEX_HOME = "D:\Projects\demo\.codex"
codex

上述範例使用預設 V1；若要改用 V2，請指定 --mode v2 或 -Mode V2。未指定 -UserHome 或 -CodexHome 時，一律視為全域安裝。

PowerShell 安裝腳本也接受相同的 V1/V2 模式選擇：

pwsh -ExecutionPolicy Bypass -File .\install.ps1 -Mode V1
pwsh -ExecutionPolicy Bypass -File .\install.ps1 -Mode V2

安裝完成後，請完全關閉並重新啟動 Codex Desktop 與所有 Codex CLI 程序，再於新的 CLI session 執行一次：

/hooks

確認看到 SOLUNA route check 即表示路由 Hook 已載入。

CLI 指令

soluna-router install       安裝 SOLUNA 路由與代理設定，可指定 --mode、--luna-reasoning-effort、--luna-fast-mode、-UserHome、-CodexHome
soluna-router doctor        檢查安裝狀態
soluna-router repair        修復缺少的受管理檔案
soluna-router uninstall     移除 SOLUNA 受管理內容
soluna-router enable-v1     啟用 V1 相容模式
soluna-router return-v2     安全返回 Codex 原始／目前預設設定

npx 只代表不需全域安裝 CLI；若未指定 -UserHome 與 -CodexHome，安裝目標仍是全域 Codex 位置。