# Pi Route (`@cary222/pi-route`)

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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![npm version](https://img.shields.io/npm/v/@cary222/pi-route.svg)](https://www.npmjs.com/package/@cary222/pi-route)
[![Pi Package](https://img.shields.io/badge/Pi-Package-orange)](https://pi.dev/packages/@cary222/pi-route)

[English Documentation](README.md)

---

## 什么是 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 安装

```bash
pi install npm:@cary222/pi-route
```

### 免安装临时体验

```bash
pi -e npm:@cary222/pi-route
```

### 本地源码开发安装

```bash
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](docs/architecture.md)
- **Security Policy**：参见 [docs/security.md](docs/security.md)
- **Catalog 维护规范**：参见 [docs/catalog-maintenance.md](docs/catalog-maintenance.md)
- **Pi Web / RPC 协议对接**：参见 [docs/pi-web-integration.md](docs/pi-web-integration.md)
- **发布指南**：参见 [docs/publishing.md](docs/publishing.md)

---

## 开源协议

本项目采用 [MIT 许可证](LICENSE)。