Pi Route (@cary222/pi-route)

Pi Coding Agent 的能力感知模式路由器与工作流编排器 (Capability-aware Mode Router)

English Documentation

什么是 Pi Route？

Pi Route 是一个位于其他 Pi 插件之前的能力感知模式路由器 (Capability-aware Mode Router)。当用户输入自然语言需求时，它能够：

1. 意图深度分类：覆盖方案规划 (Plan)、长任务执行 (Goal)、代码审查 (Audit)、官方/社区调研 (Research)、浏览器自动化 (Browser QA)、移动端开发 (Android)、安全审计 (Security) 等 11+ 种核心研发场景。
2. Runtime 能力权威校验：直接调用 pi.getCommands() 与 pi.getAllTools() 获取真实可用能力，拒绝仅依赖配置文件的虚假推断。
3. 情景预设方案 (Profile)：支持针对移动端 App 开发、Web 全栈、深度研究、安全审计等场景定制常用插件与工作流。
4. 探寻模式 (Explore Mode)：当缺少关键插件时，可安全检索 npm / Pi Packages 市场并呈现候选方案。
5. 平滑降级规划 (Fallback)：当用户拒绝安装插件或离线时，仅依赖当前本机已有能力生成降级工作流，并清晰列出能力损失与局限。
6. 一键填入命令：仅负责推荐、确认与将首条命令填入输入框（如 /plan、/goal），不替代专业插件执行具体长任务，保持各插件职责独立。

/route <您的自然语言需求>
       ↓
  意图分析与本机能力清单权威核验
       ↓
  生成最佳工作流：/plan → /goal → Browser QA → Android 验证 → /audit
       ↓
  用户确认 / 降级使用 / 无副作用取消
       ↓
  首条命令自动填入输入框

核心特性

• 权威能力校验：以 pi.getCommands() 为唯一权威，避免“安装了但被禁用”或“未加载”的误判。
• 纯领域核心 (Pure Domain Core)：业务逻辑与外部 I/O 及 Pi UI 彻底解耦，100% 独立可测试。
• 双路由策略：
  • preset（预设策略）：优先根据当前 Profile 与本机能力快速推荐，不主动访问外网。
  • explore（探寻策略）：结合全网与 npm 市场候选插件，给出最佳组合与安装建议。
• 降级工作流：拒绝安装时自动生成兜底方案，不虚构不存在的命令，不夸大普通提示词能力。
• 严格安全安装：使用参数数组的 execFile 执行 pi install，严格禁用 shell: true，屏蔽敏感环境变量并进行外网数据清理。
• 零副作用取消：在任何确认环节点击取消，不修改任何文件，不执行任何安装或指令。
• 双端呈现协议：支持终端交互式 TUI 视图，以及面向 RPC / Pi Web 的标准化 pi-route.ui.v1 事件协议。

安装与快速体验

从 Pi Packages / npm 安装

pi install npm:@cary222/pi-route

免安装临时体验

pi -e npm:@cary222/pi-route

本地源码开发安装

git clone https://github.com/earendil-works/pi-route.git
cd pi-route
npm install
npm run build
pi -e .

指令参考手册

| 指令 | 作用说明 | |---|---| | /route | 打开 Route Center 交互式控制中心 | | /route <需求描述> | 基于当前激活 Profile 分析需求并推荐工作流 | | /route --profile <id> -- <需求> | 临时指定 Profile 进行需求分析（不改变当前默认方案） | | /route explore -- <需求描述> | 进入探寻模式，检索 npm 市场候选插件与能力 | | /route profile list | 查看全部内置、全局及项目级场景 Profile | | /route profile create [名称] | 打开方案创建交互向导 | | /route profile use <id> | 切换当前会话生效的 Profile | | /route profile default <id> | 设置以后新会话的默认 Profile | | /route profile clone <id> [new-id] | 复制现有方案为新方案 | | /route profile edit <id> | 在编辑器中直接编辑方案 JSON 配置 | | /route profile delete <id> | 删除自定义方案（内置 general 受保护禁止删除） | | /route status | 查看当前可用命令、工具状态与插件清单 | | /route help | 查看帮助手册 |

使用技巧：在输入包含 profile 或 explore 等词汇的复杂英文或中文需求时，使用 -- 分隔符（如 /route --profile app-dev -- 修复登录页面）可确保参数解析万无一失。

内置场景方案 (Built-in Profiles)

1. 通用开发 (general)：标准全流程闭环开发（/plan 架构规划 → /goal 目标交付 → /audit 代码审计）。
2. App 开发 (app-dev)：专为 Android、iOS 与 Expo 跨端开发打造，集成 pi-android-cli、ADB 调试与 Logcat 实时日志。
3. Web 全栈 (web-fullstack)：专为前端与全栈开发打造，集成 pi-agent-browser-native 进行 DOM 树分析与自动化 QA。
4. 深度研究 (deep-research)：技术调研与文献综述，集成 pi-web-access 与 Feynman 跨平台多源交叉检索。
5. 安全审计 (security-audit)：代码安全扫描、CVE 漏洞核验与权限对抗审查，集成 pi-lens 与 Semgrep 规则库。

架构与安全

• 架构设计文档：参见 docs/architecture.md
• Security Policy：参见 docs/security.md
• Catalog 维护规范：参见 docs/catalog-maintenance.md
• Pi Web / RPC 协议对接：参见 docs/pi-web-integration.md
• 发布指南：参见 docs/publishing.md

开源协议

本项目采用 MIT 许可证。