太阳能路由器
- 作者仓库星标 1
- 作者仓库 Solar
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @Uhorizon-AI · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
{
"status": "success|failed",
"request_id": "string",
"provider_used": "codex|claude|gemini|agent|ollama",
"reply_text": "string",
"decision": {
"kind": "direct_reply|async_draft_proposal|async_draft_created|async_activation_needed",
"task_id": "string|null",
"priority_suggested": "high|normal|low|null"
},
"error_code": "string|null",
"error": "string|null"
}
# Solar Router
## Purpose
Single source of truth for all AI execution in Solar:
- **Provider selection and fallback** live only here.
- **Async routing policy** (`direct_reply` vs `async_draft_created`) lives only here.
- Used by solar-gateway (WebSocket/bridge) and solar-async-tasks (task execution).
## Operational boundary
Use this skill as infrastructure for Solar runtimes and controlled diagnostics. Do not use `solar-router` or provider CLIs as the normal path for work that is deferred, multiprovider, browser/MCP-dependent, network/auth/keychain-dependent, long-running, or likely to block the conversation.
For that work, create or propose a task through `solar-async-tasks`. When `solar-system` supervises `async-tasks`, approve/queue the task and let the system runtime execute it.
## Scope
- Accept JSON payload (router contract v3) on stdin; output structured JSON on stdout.
- Run the selected provider with `cwd=SOLAR_WORKSPACE` so all providers see `sun/`, `planets/`, and workspace `AGENTS.md`.
- Resolve `SOLAR_ROUTER_SYSTEM_PROMPT_FILE` and `SOLAR_ROUTER_RUNTIME_DIR` against `SOLAR_WORKSPACE` when relative.
- Codex default command includes `-C <repo-root>` and `--add-dir ~/.codex`.
- Persist conversation turns in runtime dir (JSONL) for continuity.
- Implement `DecisionEngine`: decide `decision.kind` based on `mode`, `channel`, and AI semantic output.
- Resolve JIT context from `metadata`: lookup agent/skills in planet → fallback to core → generate role inline if not found.
- Write audit log (`sun/runtime/router/audit.jsonl`) with `start`/`end` events per execution for traceability (including failed early-exit paths).
## Internal architecture
```
scripts/
run_router.py — thin entrypoint: stdin → route() → stdout + exit
router.py — all provider-agnostic logic (parse, validate, JIT, prompt, decision engine)
providers/
__init__.py — PROVIDERS dict, exports all adapters
base.py — BaseProvider: resolve_binary, get_cmd, prepare_env, clean_output, run
claude.py — static default_cmd
codex.py — build_default_cmd() with SOLAR_WORKSPACE + CODEX_STATE_DIR
gemini.py — prepare_env (GEMINI_* vars) + clean_output (ANSI strip, OAuth guard)
agent.py — build_default_cmd() with SOLAR_WORKSPACE
Automated tests live under `core/tests/skills/solar-router/` (framework-wide layout; see `core/AGENTS.md`).
```
**Layer contract:**
- `router.py` decides (context, prompt, policy, response shape).
- `providers/` executes (subprocess, env, normalization). No routing logic.
- `run_router.py` does I/O only. No logic.
## Required MCP
None
## Setup
```bash
# Configure router environment variables (SOLAR_ROUTER_*, timeouts, etc.)
bash core/skills/solar-router/scripts/onboard_router_env.sh
```
**Key environment variables:**
- `SOLAR_ROUTER_PROVIDER_PRIORITY` — Comma-separated provider list (e.g., `codex,claude,gemini,ollama`)
- `SOLAR_ROUTER_RUNTIME_DIR` — Where conversation history is stored (default: `sun/runtime/router`)
- `SOLAR_ROUTER_SYSTEM_PROMPT_FILE` — System prompt file path (default: `core/skills/solar-router/assets/system_prompt.md`)
- `SOLAR_ROUTER_CONTEXT_TURNS` — Number of conversation turns to include (default: `12`)
- `SOLAR_ROUTER_TIMEOUT_SEC` — End-to-end router timeout, including provider execution (default: `300`)
Optional command overrides:
- `SOLAR_ROUTER_CODEX_CMD`
- `SOLAR_ROUTER_CLAUDE_CMD`
- `SOLAR_ROUTER_GEMINI_CMD`
- `SOLAR_ROUTER_OLLAMA_CMD`
Ollama setup:
- `provider=ollama` always targets the local model named `solar`
- Build or refresh it with `bash core/skills/solar-router/scripts/setup_ollama.sh`
## Validation commands
```bash
# Validate skill structure
python3 core/skills/solar-skill-creator/scripts/package_skill.py core/skills/solar-router /tmp
# List configured providers (reads SOLAR_ROUTER_PROVIDER_PRIORITY)
bash core/skills/solar-router/scripts/list_providers.sh
bash core/skills/solar-router/scripts/list_providers.sh --exclude claude
bash core/skills/solar-router/scripts/list_providers.sh --exclude claude --format csv
# Diagnose router / preflight providers (native helper in this skill)
bash core/skills/solar-router/scripts/diagnose_router.sh --dry-run
bash core/skills/solar-router/scripts/diagnose_router.sh
# Full error output when a provider fails (e.g. 401, binary not found)
bash core/skills/solar-router/scripts/diagnose_router.sh --verbose
# Unit tests: router logic + provider adapters (centralized under core/tests; pytest runs unittest-style tests; no real AI calls)
uv run --project core/tests pytest core/tests/skills/solar-router -q
# Without uv: PYTHONPATH=core/skills/solar-router/scripts python3 -m unittest discover -s core/tests/skills/solar-router -p "test_*.py" -v
# Smoke tests: validate router contract v3, bridge delegation, execute_active.py JSON parsing
bash core/skills/solar-router/scripts/check_router.sh
# Live status: provider health, in-flight processes, last executions
bash core/skills/solar-router/scripts/status_router.sh
bash core/skills/solar-router/scripts/status_router.sh --last 20
```
## Router contract v3
### Input (stdin JSON)
```json
{
"request_id": "string",
"session_id": "string",
"user_id": "string",
"text": "string",
"channel": "telegram|n8n|async-task|other",
"mode": "auto|direct_only|async_only",
"provider": "codex|claude|gemini|agent|ollama|null",
"metadata": {
"agent": "agent-name|null",
"skills": ["planet:skill-name", "core-skill-name"],
"planet": "planet-name|null"
}
}
```
- `provider`: optional. If set, strict mode — no fallback. If fails → `error_code: provider_locked_failed`.
- `mode`: defaults to `auto`. `direct_only` always returns `direct_reply`. `async_only` requires `async-tasks` feature enabled.
- `channel`: used by `DecisionEngine` for semantic routing in `mode=auto`.
- `metadata.agent`: existing agent name from planet's `agents/`, or `null` for JIT role generation.
- `metadata.skills`: skill name format — `planet:skill` resolves to `planets/<planet>/skills/<skill>/SKILL.md`; unprefixed `skill` resolves to `planets/<metadata.planet>/skills/<skill>/SKILL.md` first (if `metadata.planet` is set), then falls back to `core/skills/<skill>/SKILL.md`. Only description is injected (on-demand).
- `metadata.planet`: planet that owns the task domain. Used for agent/skill lookup.
## Secure Invocation Protocol (Required)
To prevent JSON parsing errors (invalid control characters, unescaped newlines), always use one of these two methods when calling the router from an AI agent or shell:
### Method A: Temporary JSON File (Recommended for Agents)
1. Use `write_file` to create a temporary JSON file (e.g., `sun/runtime/router/request_<id>.json`).
2. Ensure the `text` field contains explicit `\n` for newlines.
3. Execute the router piping the file: `python3 core/skills/solar-router/scripts/run_router.py < sun/runtime/router/request_<id>.json`.
### Method B: Heredoc with Single Quotes (Shell)
Use a heredoc with `'EOF'` (single quotes) to prevent the shell from interpreting backslashes or special characters:
```bash
cat << 'EOF' | python3 core/skills/solar-router/scripts/run_router.py
{
"request_id": "my-id",
"text": "Line 1\nLine 2",
"channel": "other",
"mode": "direct_only"
}
EOF
```
### Critical Rules:
- **Prefer escaped newlines** (`\n`) inside JSON strings for portability.
- **Escape double quotes** inside the `text` string as `\"`.
- **Validate JSON** before sending if using a custom script.
### Output (stdout JSON)
```json
{
"status": "success|failed",
"request_id": "string",
"provider_used": "codex|claude|gemini|agent|ollama",
"reply_text": "string",
"decision": {
"kind": "direct_reply|async_draft_proposal|async_draft_created|async_activation_needed",
"task_id": "string|null",
"priority_suggested": "high|normal|low|null"
},
"error_code": "string|null",
"error": "string|null"
}
```
## DecisionEngine rules
1. `mode=direct_only` → `decision.kind=direct_reply` always.
2. `mode=async_only` + `async-tasks` enabled → `decision.kind=async_draft_created`.
3. `mode=async_only` + `async-tasks` disabled → `status=failed` + explicit error.
4. `mode=auto` + `channel=async-task` → `decision.kind=direct_reply` (already in queue).
5. `mode=auto` + `channel=telegram|n8n|other` → AI decides semantically via structured JSON output.
## Consumers
- **solar-gateway:** `run_websocket_bridge.py` and HTTP webhook bridge call the router with full v3 contract.
- **solar-async-tasks:** `execute_active.py` (via `execute_active.sh`) calls the router with `channel=async-task`, `mode=direct_only`.
## Runtime files
- `sun/runtime/router/conversations/<user_id>.jsonl` — conversation history per user (for context continuity).
- `sun/runtime/router/audit.jsonl` — audit log with one `start`/`end` record pair per execution. Fields: `router_id` (internal UUID), `request_id` (caller ref), `user_id`, `metadata`, `provider`, `status`, `jit_generated`, `duration_ms`.
## References
- `references/routing-policy.md` — provider priority, env keys, repo-context policy, v3 contract rules.
章节与文件索引
按说明文件中的顺序排列。
目的
运营边界
适用范围
内部架构
所需的MCP
文件/命令 -> direct_reply · async_draft_created · solar-router · solar-async-tasks · solar-system · async-tasks · cwd=SOLAR_WORKSPACE · sun/
内容校验值 -> 4fe0cf45ac19
当前原文的自动摘译,尚未人工审校。
目的
Solar 中所有 AI 执行的单一事实来源:提供商选择和后备仅在此进行。异步路由策略(
direct_replyvsasync_draft_created)仅存在于此。由solar-gateway(WebSocket/bridge)和solar-async-tasks(任务执行)使用。运营边界
使用此技能作为 Solar 运行时和受控诊断的基础设施。不要使用
solar-router或提供商 CLI 作为延迟、多提供商、依赖于浏览器/MCP、依赖于网络/身份验证/钥匙串、长时间运行或可能阻止对话的工作的正常路径。对于这项工作,通过solar-async-tasks创建或提出任务。当solar-system监督async-tasks时,批准/排队任务并让系统运行时执行它。适用范围
在 stdin 上接受 JSON 负载(路由器合约 v3);在 stdout 上输出结构化 JSON。使用
cwd=SOLAR_WORKSPACE运行选定的提供程序,以便所有提供程序都能看到sun/、planets/和工作区AGENTS.md。当相对时,解决SOLAR_ROUTER_SYSTEM_PROMPT_FILE和SOLAR_ROUTER_RUNTIME_DIR与SOLAR_WORKSPACE的关系。 Codex 默认命令包括-C <repo-root>和--add-dir ~/.codex。保留运行时目录 (JSONL) 中的对话以保持连续性。内部架构
层契约:
router.py决定(上下文、提示、策略、响应形状)。providers/执行(子进程、env、规范化)。没有路由逻辑。run_router.py仅进行 I/O。没有逻辑。所需的MCP
无