# pi-deepseek-route — DeepSeek V4 Flash 思维模式路由插件(pi 版)

[中文](README.md) | [English](README.en.md)

pi 生态的 **任务感知思维模式路由扩展**,专为 **DeepSeek V4 Flash** 设计:
按任务类型自动切换思考模式,非 Flash 模型**零干预**。

移植自 [dsh-routing-suite](https://github.com/yjh051108/dsh-routing-suite) 的
mode-boost v0.1.0——全部行为文本与阈值来自 2026-08-15 官方 API 实测
(`deepseek-v4-flash, reasoning_effort=max, n=2`,A/B 同场对比)。

## 特性

| 机制 | 说明 | 实测效果 |
|---|---|---|
| **Flash-only 门控** | 非 Flash 模型完全无感:不注入 persona、不收窄工具、不注入引导,`pi_router_*` 工具也从工具面隐藏 | — |
| **任务分类路由** | 按会话首条消息分三类:修复/维护 → spec(计划型,read-first);构建/开发 → react(执行型,write-first);模糊任务 → weak(模型自分类) | 弱路由区分度 +5.67 |
| **首轮锚定** | Flash 会话首轮只暴露分类匹配的核心工具,首个工具调用后恢复用户原配置 | 能力不损,轨迹稳定 |
| **近距离引导** | weak 带每条真实用户消息后注入一条引导:第 1-2 轮分类引导、第 3 轮起重分类(防风格稀释);简单任务快速收敛、复杂任务有向深度 | 多轮路由 63% → **94%** |
| **寒暄让位** | 问候/无任务消息不干预 | 避免 338 块思维链 |
| **deep-persona** | weak persona 内置"Think deeply first, then produce." | 收敛 88% → **100%** |
| **AI 自优化工具** | `pi_router_status` / `pi_router_mode` / `pi_router_subagent` | 模型自己调路由 |

更多实测:简单任务 3.5 步/6.5k 字符 → **1.0 步/1.2k**(零浪费),复杂任务
8.5 步/9.9k → **7.5 步/10.8k**(更深不绕圈),胡思乱想率 0.0–0.4%。

## 安装

```bash
# 推荐:npm 包(版本化,pi update 一键升级)
pi install npm:pi-deepseek-route

# 或 git 包(直接跟踪仓库最新)
pi install git:github.com/hisence999/pi-deepseek-route

# 临时试用,不安装(当前运行仅一次)
pi -e npm:pi-deepseek-route

# 项目级共享(写入 .pi/settings.json,团队 clone 后自动补装)
pi install -l npm:pi-deepseek-route
```

> 安装到用户目录可用 `pi list` 查看,`pi update npm:pi-deepseek-route` 单独升级该包,
> `pi update --all` 全量更新。npm 包需 Node ≥18。

**手动方式(备选)**:

```powershell
# 手动复制到全局扩展目录
$target = Join-Path $env:USERPROFILE '.pi\agent\extensions\pi-router'
New-Item -ItemType Directory -Force -Path $target
Copy-Item .\index.ts, .\core.ts $target
```

(仓库内 `install.ps1` 即上述手动方式的脚本化,适用于不便用 `pi install` 的场景。)

安装后重启 pi 或运行 `/reload`,Flash 模型会话自动生效,零配置。

## 使用

三个自优化工具(仅 Flash 会话可见):

| 工具 | 说明 |
|---|---|
| `pi_router_status` | 查看当前会话路由状态:模型门控、mode/band、persona、首轮工具面、override |
| `pi_router_mode` | 手动覆盖模式:`spec` / `weak` / `mixed`(陷阱,慎用) / `react`,0-100 或 0.0-1.0 数字,`auto` 恢复自动分类;持久化,resume 不丢 |
| `pi_router_subagent` | 用不同思维模式独立跑一个任务(独立 system prompt,不污染当前会话轨迹) |

## 工作原理

```
用户消息(Flash 模型)
  ├─ 寒暄/无任务 → 零干预
  ├─ spec(修复/维护)→ persona=计划型 + 首轮工具面 read-first
  ├─ react(构建/开发)→ persona=执行型 + 首轮工具面 write-first
  └─ weak(模糊任务)→ persona=模型自分类 + 首轮 bash+edit
       └─ 每条消息后注入引导:round 1-2 分类 / round 3+ 重分类
          简单任务 → 快速收敛 / 复杂任务 → 有向深度
首个工具调用(或 agent_settled)→ 恢复全量工具,此后不再干预工具面
```

- **缓存原则**:persona 同一会话内静态不变(除非 override),引导走消息层注入——system prompt 前缀只变化一次
- **状态持久化**:`pi.appendEntry` + 当前分支重建(`/tree` 切换安全),resume 不丢
- **工具恢复安全**:compare-and-set——只有工具面仍是本扩展收窄的 core 时才写回,不覆盖其他扩展的修改

### 已知限制与设计权衡

1. **agent_settled 提前放行首轮收窄**:原版 DSH 是"首个 tool/call 才恢复全量",
   本版加了 `agent_settled` 兜底(首轮未调工具也恢复,防卡死)。副作用:spec 模式
   下模型首轮纯文字计划(不调工具)时,第二轮工具面即全开。对 react 影响小
   (通常立刻动手),对 spec(计划型)略宽。
2. **多会话全局工具面**:`setActiveTools` 是 pi 全局 API。单会话(编码 agent 常态)
   无影响;自定义宿主同时跑多会话时,一个会话收窄/恢复可能短暂影响另一会话的
   工具面(compare-and-set 已尽量缓解:发现工具面被外部改动时不覆盖)。

## 验证

```bash
node verify.mjs     # 44 项逻辑测试(加载/门控/路由/引导/持久化/分支)
```

类型检查:`tsconfig.json` 使用 `types/pi-coding-agent.d.ts` 精简类型桩
(pi 的完整类型图在 tsc 下会实例化爆炸,故本地检查用桩;运行时由 pi
扩展加载器提供真实模块,扩展本身零 npm 依赖)。

## 与 DSH 版(mode-boost)的差异

| 维度 | DSH mode-boost | pi-deepseek-route |
|---|---|---|
| 形态 | cordis 宿主平面 bundle 插件 | pi extension(自动发现 + `/reload` 热重载) |
| 门控 | 所有模型(Pro/Flash 分支) | **仅 Flash**(非 Flash 零干预 + 工具隐藏) |
| 首轮工具面 | shell + str_replace_editor(RL 形状) | shell + edit(pi 无 str_replace_editor,近似) |
| 工具名 | dev_mode_status / dev_mode_set | pi_router_status / pi_router_mode |
| 状态持久化 | session.events 推导 | `pi.appendEntry` + 分支重建(tree 安全) |
| 工具恢复 | 首个 tool/call 后放行 | 首个 tool/call **或 agent_settled** 结束租约(compare-and-set 防覆盖) |

## License

MIT。致谢:yjh051108/dsh-routing-suite(实测数据与文本)、
xiaobright/modeltest(V4.1b 评测)、xiaobright/dsh-anchored-standard(锚定机制)、
[Linux.do 社区](https://linux.do)(开发者交流与灵感来源)。