Semantic RouterBLOCK

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: semantic-router
description: 让 AI 代理根据对话内容自动选择最合适的模型。层2(多词非连续命中)+ 层1(单词兜底)并行决定模型池;层3(embedding)永远独立运行决定会话切换。B+ 连续漂移计数器(第3次警告,第4次强制 C-auto)。soft_keywords 泛用词降权机制。四池架构(高速/智能/人文/代理),五分支路由,全自动 Fallback 回路。
version: 8.0.0
author: halfmoon82
tags: [semantic, routing, model-pools, task-classification, fallback, system-passthrough, production, layer-parallel]
requires_approval: true
---

> 🔒 **安全声明**:本技能需要修改 OpenClaw 配置以实现模型路由功能。所有配置变更前会自动备份,支持一键回滚。建议在测试环境验证后再部署到生产环境。

## ⚠️ Security & Permissions Declaration

**This skill performs the following privileged operations — all are intentional and explicitly user-initiated:**

| Operation | Purpose | Scope |
|-----------|---------|-------|
| Read/patch `~/.openclaw/openclaw.json` | Configure model routing pools | Local config only |
| Read/write `~/.openclaw/workspace/.lib/pools.json` | Store model pool configuration | Workspace only |
| Read/write `~/.openclaw/workspace/.lib/tasks.json` | Store task type definitions | Workspace only |
| Run `semantic_check.py` locally | Classify user messages for routing | No network required |
| Patch session model via `sessions.patch` | Switch active model pool | Current session only |
| Restart OpenClaw Gateway (`openclaw gateway restart`) | Apply routing config changes | Local service only |
| Inject `prependContext` into agent turns | Output routing declaration in first line | Read-only context injection |
| Update Cron Job `sessionTarget` to `"isolated"` | Prevent background tasks from polluting user sessions | Affects only background Cron jobs |

**What this skill does NOT do:**
- Does NOT exfiltrate conversation content or model credentials to external servers
- Does NOT access API keys or secrets directly
- Does NOT modify files outside `~/.openclaw/` and the skill's own workspace
- Does NOT run with elevated (sudo/root) privileges
- Does NOT auto-install additional packages

**Requires:** Python 3.8+, OpenClaw Gateway running, configured model providers

# 🔷 Semantic Router v7.9.3 — 生产级会话路由系统 🔷

**ClawHub**: https://clawhub.ai/halfmoon82/semantic-router  
**版本**: 7.6.3 (生产环境)  
**作者**: halfmoon82
**状态**: ✅ ROM 级固化,完全测试通过

## 🎯 这个技能解决什么问题?

### 核心问题(v7.2 新解决)

你是否遇到过:
- **Cron Job 导致会话频繁重置** — 后台定时任务打断用户交互
- **Discord/Telegram 渠道会话突然清空** — 长任务无法延续
- **AGENTS.md 被截断注入** — 大文件超过 20KB 限制
- **模型自动切换被全局配置覆盖** — 切换不生效

### 解决方案

**会话隔离架构**:
```
用户直连渠道(稳定)
    ├─ 主代理会话 → semantic-router(精准路由)
    └─ Cron Job 隔离会话(独立环境)
        ├─ cloudflared-watchdog
        ├─ Fallback 回切检查
        └─ 自定义后台任务
```

**完整配置引导**:
- 零冲突的智能合并配置
- 预检脚本防止覆盖现有设置
- 自动回滚失败的配置修改

---

## 🔒 安全与权限说明

### 为什么需要这些权限?

| 权限 | 用途 | 安全措施 |
|------|------|----------|
| 读取 `openclaw.json` | 检测现有模型配置 | 只读,不修改 |
| 修改 `openclaw.json` | 添加模型池配置 | **自动备份** + **一键回滚** |
| 执行本地脚本 | 运行配置向导和验证 | 开源脚本,可审计 |
| 重启 Gateway | 应用新配置 | 失败自动回滚 |

### 配置保护机制

1. **前置备份**:任何修改前自动创建带时间戳的备份
2. **语法验证**:JSON 修改后自动验证语法
3. **健康检查**:Gateway 重启后验证服务可用性
4. **自动回滚**:任何步骤失败立即恢复原配置

```bash
# 手动回滚命令
python3 ~/.openclaw/workspace/.lib/config-rollback-guard.py rollback
```

### 代码审计

- 所有脚本开源,位于 `scripts/` 目录
- 核心逻辑 `semantic_check.py` 62KB,完全可审计
- 无网络请求,无数据上报,纯本地运行

---

## 🚀 快速安装

### 第一步:安装技能

```bash
# 从 ClawHub 安装
clawhub install https://clawhub.ai/halfmoon82/semantic-router

# 或手动复制到本地
cp -r ~/.openclaw/workspace/skills/semantic-router ~/my-projects/
```

### 第二步:运行配置引导

```bash
# 启动交互式配置向导
python3 ~/.openclaw/workspace/skills/semantic-router/scripts/setup_wizard.py

# 向导将:
# 1. 检测你的已有配置
# 2. 扫描可用模型
# 3. 推荐三池配置
# 4. 生成 pools.json 和 tasks.json
```

### 第三步:启动 Webhook 服务(重要!)

```bash
# 复制核心文件到 .lib 目录
cp ~/.openclaw/workspace/skills/semantic-router/scripts/semantic_check.py \
   ~/.openclaw/workspace/.lib/
cp ~/.openclaw/workspace/skills/semantic-router/scripts/semantic-webhook-server.py \
   ~/.openclaw/workspace/.lib/

# 启动 Webhook 服务(端口 9811)
python3 ~/.openclaw/workspace/.lib/semantic-webhook-server.py --port 9811 &

# 验证服务是否运行
curl http://127.0.0.1:9811/health
# 预期输出: {"status": "ok", "version": "7.9.x"}
```

### 第四步:隔离现有 Cron Job(重要!)

```bash
# 列出你的所有 Cron Job
cron list | jq '.jobs[] | {id, name, sessionKey}'

# 对每个使用了渠道会话(telegram/discord/whatsapp)的 Job,执行隔离
cron update {job_id} \
  --patch '{"sessionKey": null, "sessionTarget": "isolated"}'

# 示例(cloudflared-watchdog)
cron update ba28e228-473a-4963-8413-c228762bf2d1 \
  --patch '{"sessionKey": null, "sessionTarget": "isolated"}'
```

### 第五步:验证安装

```bash
# 测试 Webhook 路由接口
curl -X POST http://127.0.0.1:9811/route \
  -H "Content-Type: application/json" \
  -d '{"message": "帮我写个Python爬虫", "current_pool": "Highspeed"}'

# 预期输出
# {
#   "branch": "C",
#   "task": "development",
#   "target_pool": "Intelligence",
#   "primary_model": "claude-opus-4.6",
#   "declaration": "【语义检查 by DeepEye@halfmoon82】P1-任务切换..."
# }
```

---

## 🎓 核心概念

### 四池模型架构

| 池名 | 用途 | 模型示例 | 特点 |
|------|------|---------|------|
| **Highspeed** | 查询、检索、信息搜索 | gemini-2.5-flash | 快速、成本低 |
| **Intelligence** | 开发、编程、复杂任务 | claude-sonnet-4.6 | 精准、能力强 |
| **Humanities** | 内容生成、翻译、写作 | gemini-2.5-pro | 平衡、流畅 |
| **Agentic** | 长上下文代理、Computer Use、专业知识工作 | gpt-5.4 | 1M上下文、工具调用、多步骤 |

### 两步判断法

**Step 1: 关键词 + 指示词检测**
```
"帮我写个爬虫" → 关键词 "写" + "爬虫" → 开发任务 → Intelligence
"继续刚才的" → 指示词 "继续" → 延续当前池 → B 分支
"查一下天气" → 关键词 "查" + "天气" → 查询任务 → Highspeed
"帮我整理这些材料做成PPT" → trigger_groups_all 规则命中 → 代理任务 → Agentic
```

**trigger_groups_all 非连续词组命中(v7.7 新增)**

支持在 tasks.json 中定义分组规则,每条规则内所有分组取 AND,分组内词取 OR,多条规则取 OR:
```json
"trigger_groups_all": [
  [["帮我","自动","用AI"], ["操作","填写","截图"]],
  [["处理","生成","制作"], ["报告","表格","文档","PPT"]]
]
```
说"帮我自动操作浏览器"→ 规则1命中 → Agentic 池。无需精确关键词,口语自然表达即可触发。

**Step 2: 上下文关联度评分**(当 Step 1 无结果时)
```
相似度 ≥ 0.15 → 延续当前会话(B 分支)
相似度 0.08~0.15 → 延续但警告(B+ 分支)
相似度 < 0.08 → 新话题,重置会话(C-auto 分支)
```

### 五分支路由决策

| 分支 | 触发条件 | 动作 | 会话行为 |
|------|--------|------|--------|
| **A** | 关键词完全匹配 | 直接切到目标池 | 切换模型,不重置 |
| **B** | 指示词(延续) | 保持当前 | 无动作 |
| **B+** | 中等关联度(0.08~0.15) | 保持 + 警告 | 输出漂移警告 |
| **C** | 新任务关键词 | 切到目标池 | 切换模型,不重置 |
| **C-au

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

declared (5 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (9)

- Does NOT access API keys or secrets directly

curl http://127.0.0.1:9811/health

curl -X POST http://127.0.0.1:9811/route \

<key>k5Ey9KFlkqpj+SDkUw+5ED9lTA3En/qUi0zdrydUCH3kMWTE3Eh65NXnFCaxlY2omY2JHnlEoK7Li7oOEvM7eG5VPdcO/sFlMfoCRdnLYdepJ+uLzYwOWR8W4yQVve/clxVFTVRL4DFleKInGdpAxIbHZT2yi4ADAMENls1N1XSLojRuqXePXDeAT/4Mv4TTx0s

curl http://127.0.0.1:9811/health

curl -X POST http://127.0.0.1:9811/route \

curl http://127.0.0.1:9811/health

- Does NOT run with elevated privileges

- Does NOT access API keys or secrets directly

Gates applied: no_behavioural_pass.