\n 中文 | English\n
\n\n> 本文档详细介绍 pi-maestro-flow 插件为 Pi Coding Agent 注册的所有工具、能力和使用方法。\n> Skills 为简要索引，完整定义请参阅 [Maestro Flow](https://github.com/catlog22/maestro-flow) 项目。\n\n---\n\n## 目录\n\n1. [安装与配置](#1-安装与配置)\n2. [核心工具](#2-核心工具)\n - [teammate — 多智能体调度](#21-teammate--多智能体调度)\n - [maestro — 知识感知调度](#22-maestro--知识感知调度)\n - [goal — 长时目标生命周期](#23-goal--长时目标生命周期)\n - [todo — 任务管理](#24-todo--任务管理)\n - [run-control — 工作流运行控制](#25-run-control--工作流运行控制)\n3. [智能工具](#3-智能工具)\n - [lsp — 语言服务器集成](#31-lsp--语言服务器集成)\n - [browser — 浏览器控制](#32-browser--浏览器控制)\n - [smart_search — 网络搜索与研究](#33-smart_search--网络搜索与研究)\n - [ffgrep / fffind — 快速搜索](#34-ffgrep--fffind--快速搜索)\n - [search_tool_bm25 — 工具发现](#35-search_tool_bm25--工具发现)\n4. [MCP 集成](#4-mcp-集成)\n5. [权限系统](#5-权限系统)\n6. [思考深度控制](#6-思考深度控制)\n7. [交互工具](#7-交互工具)\n - [ask-user-question — 结构化用户输入](#71-ask-user-question--结构化用户输入)\n - [plan-enter — 计划模式](#72-plan-enter--计划模式)\n8. [Agent 控制工具](#8-agent-控制工具)\n9. [运行时子系统](#9-运行时子系统)\n - [自动压缩](#91-自动压缩)\n - [GUI 子系统（UCL）](#92-gui-子系统ucl)\n - [TUI 界面组件](#93-tui-界面组件)\n10. [Agent 角色（27 个）](#10-agent-角色27-个)\n11. [Prompt 输入](#11-prompt-输入)\n12. [Skills 索引（68 个）](#12-skills-索引68-个)\n13. [知识系统](#13-知识系统)\n14. [工作流模式](#14-工作流模式)\n15. [配置参考](#15-配置参考)\n16. [故障排除](#16-故障排除)\n\n---\n\n## 1. 安装与配置\n\n### 前置条件\n\n| 组件 | 版本要求 |\n|------|---------|\n| Node.js | ≥ 22.19.0 |\n| [Pi Coding Agent](https://github.com/earendil-works/pi) | ≥ 0.74.0 |\n| [Maestro CLI](https://github.com/catlog22/maestro2) | ≥ 1.0.0（知识系统功能） |\n\n### 安装\n\n```bash\n# 安装（pi-maestro-teammate 作为依赖自动安装）\npi install npm:pi-maestro-flow\n\n# 验证\npi list\n# 预期输出: pi-maestro-flow@0.4.x, pi-maestro-teammate@0.4.x\n```\n\n### 插件注册的工具总览\n\n安装后，插件向 Pi 注册以下工具：\n\n| 来源包 | 工具 | 用途 |\n|--------|------|------|\n| pi-maestro-teammate | `teammate` | 多智能体调度（单任务/并行/DAG） |\n| pi-maestro-teammate | `teammate-send` | 向运行中的 Agent 发送消息 |\n| pi-maestro-teammate | `teammate-list` | 列出活跃 Agent |\n| pi-maestro-teammate | `teammate-watch` | 查看 Agent 输出 |\n| pi-maestro-teammate | `teammate-wait` | 等待 Agent 完成 |\n| pi-maestro-flow | `maestro` | 知识感知调度（explore/delegate/moa） |\n| pi-maestro-flow | `goal` | 长时目标生命周期管理 |\n| pi-maestro-flow | `todo` | 任务分解与跟踪 |\n| pi-maestro-flow | `run-control` | 工作流 Run 生命周期 |\n| pi-maestro-flow | `ask-user-question` | 结构化用户输入收集 |\n| pi-maestro-flow | `lsp` | 语言服务器协议集成 |\n| pi-maestro-flow | `browser` | Chromium 浏览器控制 |\n| pi-maestro-flow | `smart_search` | 网络搜索/深度研究/URL 抓取 |\n| pi-maestro-flow | `ffgrep` | FFF 快速字面内容搜索 |\n| pi-maestro-flow | `fffind` | FFF 快速模糊文件搜索 |\n| pi-maestro-flow | `search_tool_bm25` | BM25 工具发现 |\n| pi-maestro-flow | `plan-enter` | 进入计划模式 |\n\n---\n\n## 2. 核心工具\n\n### 2.1 teammate — 多智能体调度\n\n所有调用统一使用必需的非空 `tasks[]`。单 Agent 是一个 task，多 Agent 是多个 task。每项 `prompt` 都是字面任务文本，不加载 Prompt 模板。\n\n```javascript\nteammate({ tasks: [{\n agent: \"explorer\",\n taskType: \"explore\",\n prompt: \"FIND: 认证入口\nSCOPE: src/\"\n}] })\n\nteammate({\n agent: \"explorer\",\n model: \"provider/fast-model\",\n tasks: [\n { name: \"scan\", prompt: \"定位认证入口\" },\n { name: \"calls\", prompt: \"定位调用点\" },\n { name: \"review\", agent: \"analyst\", taskType: \"review\",\n model: \"provider/deep-model\", prompt: \"审查 {scan} 与 {calls}\" }\n ],\n concurrency: 2,\n background: false\n})\n```\n\n顶层 `agent/taskType/model/thinking/context/cwd/outputSchema/timeoutMs` 是 task 默认值，task 同名字段覆盖。未指定角色时默认 `general`。`{name}`/`{name.field}` 注入上游输出，`dependsOn` 只声明顺序。`background` 默认 `false`。\n\n模型优先级：task model > 顶层 model > taskType 映射 > 角色 model > 父 Pi 模型。taskType 只影响路由，不改变角色行为。Control Center 会自动合并内置类型、当前发现的内置/项目/用户 Agent YAML 类型及已有映射类型；自定义 Agent 可声明新的小写类型标识。\n\n### 2.2 maestro — 知识感知调度\n\n提供三个 action，连接外部 CLI 端点和知识系统：\n\n#### explore — 并行代码搜索\n\n```javascript\nmaestro({\n action: \"explore\",\n prompts: [\n \"FIND: 所有 JWT 验证中间件\\nSCOPE: src/middleware/\\nEXPECTED: file:line + 控制流摘要\",\n \"FIND: 所有 auth.login() 调用点\\nSCOPE: src/**/*.ts\\nEXPECTED: file:line 列表\"\n ],\n concurrency: 3,\n maxTurns: 6\n})\n```\n\n#### delegate — 任务委派到外部工具\n\n```javascript\nmaestro({\n action: \"delegate\",\n prompt: \"PURPOSE: 实现密码重置流程\\nMODE: write\\nCONTEXT: @src/auth/\",\n tool: \"claude\", // gemini | claude | codex\n mode: \"write\"\n})\n```\n\n#### moa — 混合智能体合成\n\n```javascript\nmaestro({\n action: \"moa\",\n prompts: [\"从安全和架构两个角度分析支付流程\"],\n preset: \"deep\"\n})\n// 跨多个模型并行分析，然后合成为统一报告\n```\n\n---\n\n### 2.3 goal — 长时目标生命周期\n\n为多轮自主工作提供持久化引擎：自动续行、Token 预算、压缩存活、独立验证。\n\n#### 模型侧操作\n\n```javascript\ngoal({ action: \"create\", objective: \"实现 JWT 认证模块\" })\ngoal({ action: \"create\", objective: \"实现 JWT 认证模块\", tokenBudget: \"100k\" })\ngoal({ action: \"get\" })\ngoal({ action: \"update\", objective: \"实现 JWT 认证 + 刷新令牌\" })\ngoal({ action: \"complete\", summary: \"所有模块已实现并通过测试\" })\n```\n\n#### 用户侧命令\n\n| 命令 | 效果 |\n|------|------|\n| `/goal status` | 查看当前 Goal |\n| `/goal create [--tokens 100k] <目标>` | 创建 Goal 并启动代理循环 |\n| `/goal stop` | 暂停，保存状态 |\n| `/goal resume [--tokens 200k]` | 恢复；可提高预算 |\n| `/goal clear` | 放弃并删除 Goal |\n\n#### 验证机制\n\n- 正常 `agent_end` 后自动触发独立验证\n- `pass` → 标记完成，清除 Goal\n- `fail` → 保持活跃，携带未满足需求启动下一轮\n- `inconclusive` → 保持活跃，等待用户 `/goal resume`\n\n#### Goal 面板\n\nGoal 存在时，输入编辑器上方渲染 `goal-panel`，显示：\n- 状态（ACTIVE / WAITING / VERIFYING / VERIFIED / STOPPED / BUDGET / BLOCKED / ERROR）\n- 目标描述、已用时间、循环次数\n- 显式配置的 Token 预算（未配置时不显示）\n\n---\n\n### 2.4 todo — 任务管理\n\n7 个操作，支持纯文本上下文和可选的 Pi Skill 执行：\n\n```javascript\n// 创建任务\ntodo({ action: \"create\", subject: \"实现用户认证\", description: \"JWT + 刷新令牌\" })\n\n// 带 Skill 绑定的任务\ntodo({\n action: \"create\",\n subject: \"代码审查\",\n skills: [{ name: \"quality-review\", role: \"primary\", args: \"--level deep\" }]\n})\n\n// 更新状态\ntodo({ action: \"update\", id: \"abc123\", status: \"completed\", summary: \"已完成认证模块\" })\n\n// 列出任务\ntodo({ action: \"list\", filter: { status: \"pending\" } })\n\n// 激活下一个待办任务\ntodo({ action: \"next\" })\n\n// 分配给 teammate\ntodo({ action: \"create\", subject: \"探索代码库\", assignee: \"explorer-1\" })\n```\n\n| 操作 | 说明 |\n|------|------|\n| `create` | 创建任务（subject 必填） |\n| `update` | 更新状态/摘要/上下文/技能 |\n| `list` | 按状态/成员过滤列出 |\n| `get` | 获取单个任务详情 |\n| `delete` | 删除任务 |\n| `clear` | 清除所有任务 |\n| `next` | 激活下一个待办任务，返回解析后的上下文 |\n\n---\n\n### 2.5 run-control — 工作流运行控制\n\n通过统一类型化 Shell 读取和控制规范化 Maestro Workflow Run：\n\n| Action | 类型 | 说明 |\n|--------|------|------|\n| `status` | 只读 | 读取当前 Session 快照 |\n| `brief` | 只读 | 加载 Run 恢复包 |\n| `prepare` | 只读 | 预览工作流步骤（不创建 Run） |\n| `check` | 只读 | 评估 Run 门控和完成指引 |\n| `next` | 写入 | 分配下一个链式 Run |\n| `done` | 写入 | 以裁决封印 Run（done / done-with-concerns / needs-retry / blocked） |\n| `edit` | 写入 | 修改未来链步骤（commands / after / replace / remove） |\n\n```javascript\nrun-control({ action: \"status\" })\nrun-control({ action: \"next\" })\nrun-control({ action: \"done\", runId: \"run-123\", verdict: \"done\", summary: \"完成\" })\nrun-control({ action: \"edit\", commands: [\"quality-review\"], after: \"current\" })\n```\n\n---\n\n## 3. 智能工具\n\n### 3.1 lsp — 语言服务器集成\n\n连接语言服务器，提供代码智能功能：\n\n| Action | 说明 |\n|--------|------|\n| `diagnostics` | 获取诊断信息（错误/警告） |\n| `definition` | 跳转到定义 |\n| `references` | 查找所有引用 |\n| `hover` | 悬停信息（类型/文档） |\n| `symbols` | 文件/工作区符号列表 |\n| `rename` | 重命名符号 |\n| `rename_file` | 重命名文件（更新引用） |\n| `code_actions` | 可用代码操作 |\n| `type_definition` | 跳转到类型定义 |\n| `implementation` | 查找实现 |\n| `status` | 语言服务器状态 |\n| `reload` | 重新加载 |\n| `capabilities` | 服务器能力 |\n| `request` | 原始 LSP 请求 |\n\n```javascript\nlsp({ action: \"diagnostics\", file: \"src/auth/login.ts\" })\nlsp({ action: \"definition\", file: \"src/auth/login.ts\", line: 42, symbol: \"validateToken\" })\nlsp({ action: \"references\", file: \"src/auth/login.ts\", line: 42, symbol: \"validateToken\" })\nlsp({ action: \"rename\", file: \"src/auth/login.ts\", line: 42, symbol: \"validateToken\", new_name: \"verifyToken\", apply: true })\nlsp({ action: \"symbols\", file: \"*\" }) // 工作区符号\n```\n\n插件还注册了 **LSP 自动诊断**：文件编辑后自动触发诊断检查。\n\n---\n\n### 3.2 browser — 浏览器控制\n\n通过 CDP 控制 Chromium，支持命名标签页、截图和页面内 JavaScript 执行：\n\n| Action | 说明 |\n|--------|------|\n| `open` | 打开/附加浏览器标签页 |\n| `close` | 关闭标签页（`all: true` 关闭全部） |\n| `run` | 在页面中执行 JavaScript |\n\n```javascript\n// 打开页面\nbrowser({ action: \"open\", url: \"http://localhost:3000\", name: \"app\" })\n\n// 执行 JS + 截图\nbrowser({\n action: \"run\",\n name: \"app\",\n code: \"await page.screenshot({ path: 'screenshot.png' }); return document.title;\"\n})\n\n// 设置视口\nbrowser({ action: \"open\", url: \"...\", viewport: { width: 1920, height: 1080 } })\n\n// 关闭\nbrowser({ action: \"close\", name: \"app\" })\nbrowser({ action: \"close\", all: true })\n```\n\n支持配置：\n- `app.path` — 自定义 Chromium/Chrome/Edge 路径\n- `app.cdp_url` — 连接已有浏览器 CDP 端点\n- `wait_until` — 导航等待策略（load / domcontentloaded / networkidle0 / networkidle2）\n- `dialogs` — 对话框处理（accept / dismiss）\n\n---\n\n### 3.3 smart_search — 网络搜索与研究\n\n外部信息检索 — 网络搜索、深度研究、URL 内容提取：\n\n| 模式 | 用途 | 关键参数 |\n|------|------|---------|\n| `search` | 快速查询 | `platform`, `validation` |\n| `research` | 多源深度研究 | `budget`（quick/standard/deep）, `validation`（strict） |\n| `fetch` | 提取已知 URL 内容 | — |\n| `route` | 路由诊断 | `router_mode` |\n\n```javascript\nsmart_search({ mode: \"search\", query: \"Express.js 中间件错误处理最佳实践\" })\nsmart_search({ mode: \"research\", query: \"JWT vs Session 认证对比\", budget: \"deep\", validation: \"strict\" })\nsmart_search({ mode: \"fetch\", query: \"https://docs.example.com/api/auth\" })\n```\n\n通过 `Alt+S` 或 `/smart-search-config` 打开配置界面。\n\n---\n\n### 3.4 ffgrep / fffind — 快速搜索\n\n基于 [FFF](https://github.com/fff-labs/fff) 的原生索引搜索，仅注册到根 Pi 会话：\n\n```javascript\n// 字面内容搜索\nffgrep({ pattern: \"validateToken\", context: 3, limit: 20 })\n\n// 模糊文件路径搜索\nfffind({ pattern: \"auth middleware\", limit: 10 })\n```\n\n---\n\n### 3.5 search_tool_bm25 — 工具发现\n\n按名称、描述和参数名搜索所有已注册工具，使用 BM25 加权排序：\n\n```javascript\nsearch_tool_bm25({ query: \"code search\", limit: 10 })\n```\n\n匹配的未激活工具会被自动激活。\n\n---\n\n## 4. MCP 集成\n\n插件内置完整的 MCP（Model Context Protocol）客户端，通过统一的 `mcp` 代理工具连接外部 MCP 服务器。\n\n> 设计原则：不将 MCP 服务器的数百个工具逐一注册到 Pi，而是通过单一 `mcp` 代理工具统一访问，保持 LLM 上下文精简。\n\n### 基本操作\n\n```javascript\n// 查看服务器状态\nmcp({ })\n\n// 列出服务器的工具\nmcp({ server: \"server-name\" })\n\n// 搜索工具（按名称/描述）\nmcp({ search: \"query\" })\nmcp({ search: \"pattern.*\", regex: true })\n\n// 查看工具详情和参数\nmcp({ describe: \"tool_name\" })\n\n// 连接服务器并刷新元数据\nmcp({ connect: \"server-name\" })\n\n// 调用工具\nmcp({ tool: \"tool_name\", args: '{\"key\": \"value\"}' })\nmcp({ server: \"server-name\", tool: \"tool_name\", args: '{\"key\": \"value\"}' })\n```\n\n### OAuth 认证\n\n```javascript\n// 启动手动 OAuth 流程，获取浏览器 URL\nmcp({ action: \"auth-start\", server: \"server-name\" })\n\n// 完成手动 OAuth\nmcp({ action: \"auth-complete\", server: \"server-name\", args: '{\"redirectUrl\":\"...\"}' })\n\n// 获取已完成 UI 会话的消息\nmcp({ action: \"ui-messages\" })\n```\n\n### 传输协议\n\n支持三种传输方式：\n- **stdio** — 本地进程通信（最常用）\n- **SSE** — Server-Sent Events HTTP 流\n- **Streamable HTTP** — 可流式 HTTP 传输\n\n### 高级特性\n\n| 特性 | 说明 |\n|------|------|\n| **元数据缓存** | 持久化工具/资源元数据缓存（7 天 TTL），避免重复连接 |\n| **NPX 解析** | 自动解析 `npx`/`npm exec` 二进制路径，避免 npm 父进程开销 |\n| **输出守卫** | 大输出自动截断（默认 50KB / 2000 行），完整输出写入临时文件 |\n| **Sampling** | 支持 MCP Sampling 请求（服务器请求 LLM 生成），需用户确认 |\n| **UI 会话** | 支持 MCP UI 资源（`ui://` 协议），在浏览器中渲染交互式界面 |\n| **UI 流式** | 支持 `eager` / `stream-first` 两种 UI 流式模式 |\n| **OAuth 提供者** | 完整 OAuth 客户端实现（注册、令牌存储、授权重定向） |\n| **配置导入** | 支持从 Cursor / Claude Code / Claude Desktop / Codex / Windsurf / VSCode 导入配置 |\n| **MCP 管理器** | TUI 管理界面（`/mcp` 命令），支持启用/停用/删除服务器 |\n| **资源工具** | MCP 资源自动转换为 `get_