hack/tools/scripts/llm-key-hunter/results/_cache/content/catlog22_pi-maestro-flow.json

{"repo": "catlog22/pi-maestro-flow", "files": {"docs/USAGE.md": {"46aeeda84c46a3cf39c8cde987f947c8e0a2ae3d": {"t": 1786068097.373375, "n": 26234, "h": "92063650db2646eb", "c": "# pi-maestro-flow 功能使用说明\n\n<p align=\"center\">\n  <strong>中文</strong> | <a href=\"USAGE_EN.md\">English</a>\n</p>\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_<name>` 工具 |\n| **同意管理** | 工具调用同意管理，支持自动批准配置 |\n\n### 配置\n\nMCP 服务器在 Pi 配置文件中定义（用户级或项目级）：\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@my/mcp-server\"],\n      \"env\": { \"API_KEY\": \"...\" },\n      \"enabled\": true,\n      \"excludeTools\": [\"dangerous_tool\"]\n    }\n  }\n}\n```\n\n---\n\n## 5. 权限系统\n\n插件实现了完整的工具调用权限控制，支持多种权限模式和细粒度规则。\n\n### 权限模式\n\n| 模式 | 行为 |\n|------|------|\n| `default` | 默认模式，危险操作需用户确认 |\n| `acceptEdits` | 自动接受文件编辑，其他操作仍需确认 |\n| `plan` | 计划模式，仅允许只读操作 |\n| `dontAsk` | 不询问，自动允许所有操作 |\n| `bypassPermissions` | YOLO 模式，跳过所有权限检查（可被配置禁用） |\n\n### 权限规则\n\n三种行为级别：\n\n| 行为 | 说明 |\n|------|------|\n| `allow` | 自动允许，不询问 |\n| `ask` | 每次询问用户 |\n| `deny` | 拒绝执行 |\n\n规则可配置在会话级（临时）或本地设置文件（持久）：\n\n```json\n{\n  \"permissions\": {\n    \"defaultMode\": \"default\",\n    \"allow\": [\"Bash(npm test)\", \"Bash(npm run *)\"],\n    \"ask\": [\"Bash(rm *)\"],\n    \"deny\": [\"Bash(rm -rf /)\"],\n    \"disableBypassPermissionsMode\": \"disable\"\n  }\n}\n```\n\n### 始终允许的工具\n\n以下工具在任何模式下都自动允许（只读或无副作用）：\n\n`Read`, `Grep`, `Glob`, `Ls`, `Find`, `ffgrep`, `fffind`, `ask-user-question`, `teammate`, `teammate-send`, `teammate-list`, `teammate-watch`, `goal`, `todo`, `plan-*`, `search_tool_bm25`\n\n### Teammate 子进程权限中继\n\nTeammate 子进程没有本地终端，权限请求通过 IPC 中继到父进程处理：\n- 父进程拥有实时模式、会话规则、钩子和持久化\n- 子进程的权限请求通过 `teammate_proxy_request` 转发\n- 父进程执行权限评估并返回 `allow_once` 或 `deny`\n\n---\n\n## 6. 思考深度控制\n\nTeammate 调度支持精细的思考深度控制，影响子进程 Agent 的推理深度。\n\n### 可用级别\n\n| 级别 | 说明 |\n|------|------|\n| `off` | 关闭扩展思考，最快响应 |\n| `minimal` | 最小思考开销 |\n| `low` | 低深度推理 |\n| `medium` | 中等深度（平衡速度和质量） |\n| `high` | 高深度推理 |\n| `xhigh` | 极高深度（最慢但最 thorough） |\n| `max` | `xhigh` 的别名 |\n\n### 使用方式\n\n```javascript\n// 顶层默认\nteammate({\n  thinking: \"high\",\n  tasks: [\n    { name: \"quick-scan\", agent: \"explorer\", prompt: \"...\", thinking: \"off\" },\n    { name: \"deep-analysis\", agent: \"general\", prompt: \"...\", thinking: \"xhigh\" }\n  ]\n})\n```\n\n### 优先级\n\n任务级 `thinking` → 顶层 `thinking` → `taskType` 映射 → Agent frontmatter → Pi 默认\n\n> 注意：不同模型支持的思考级别范围不同。例如 `deepseek/deepseek-v4-flash` 仅支持 `off` 和 `high`，而 `maestro-openai/gpt-5.6-sol` 支持全部级别。\n\n---\n\n## 7. 交互工具\n\n### 7.1 ask-user-question — 结构化用户输入\n\n通过键盘优先的 TUI 向导收集结构化用户答案：\n\n```javascript\n// 单选\nask-user-question({\n  questions: [{\n    question: \"选择哪种方案？\",\n    header: \"方案\",\n    options: [\n      { label: \"A: 微服务\", description: \"独立部署，松耦合\" },\n      { label: \"B: 单体\", description: \"简单直接，易调试\" }\n    ]\n  }]\n})\n\n// 多选\nask-user-question({\n  questions: [{\n    question: \"需要哪些功能？\",\n    multiSelect: true,\n    options: [\n      { label: \"认证\" }, { label: \"授权\" },\n      { label: \"审计日志\" }, { label: \"速率限制\" }\n    ]\n  }]\n})\n\n// 开放式\nask-user-question({\n  questions: [{ question: \"项目名称是什么？\" }]\n})\n```\n\n- 单次最多 4 个问题\n- 每个问题 2-4 个选项\n- 支持单选、多选、开放式\n\n---\n\n### 7.2 plan-enter — 计划模式\n\n进入持久化计划模式，加载当前会话的 `current.md` 草稿，激活计划专用工具：\n\n```javascript\nplan-enter()\n```\n\n**计划模式行为：**\n- 编辑/写入工具和文件变更命令被阻止\n- 读取/搜索/探索工具保持可用\n- 通过 `plan-update` 起草 Markdown 计划\n- 通过 `plan-status` 检查计划状态\n- `plan-confirm`（或 `/plan approve`）提交计划并恢复 Act 工具\n- `plan-exit` 放弃计划返回 Act 模式\n\n**切换方式：** `Alt+Shift+P` 或 `/plan` 切换 Plan/Act 模式。\n\n---\n\n## 8. Agent 控制工具\n\n管理运行中的 teammate Agent：\n\n```javascript\n// 列出所有活跃 Agent\nteammate-list({ view: \"all\" })     // all | active | named | roles\n\n// 查看 Agent 输出\nteammate-watch({ name: \"my-agent\", lines: 30 })\n\n// 等待 Agent 完成（事件驱动，避免轮询）\nteammate-wait({ name: \"my-agent\", timeoutMs: 60000 })\nteammate-wait({ waitMs: 5000 })  // 固定延迟\n\n// 向运行中的 Agent 发送消息\nteammate-send({ to: \"my-agent\", message: \"请也检查边界情况\", mode: \"follow_up\" })\n\n// 紧急修正（中断当前轮次）\nteammate-send({ to: \"my-agent\", message: \"停止当前方案，改用替代方案\", mode: \"steer\" })\n\n// 终止\nteammate-send({ to: \"my-agent\", mode: \"abort\" })\n```\n\n| 工具 | 用途 |\n|------|------|\n| `teammate-list` | 列出 Agent（active / named / all / roles） |\n| `teammate-watch` | 查看最近输出、工具活动、收件箱 |\n| `teammate-wait` | 事件驱动等待 Agent 完成或固定延迟 |\n| `teammate-send` | 发送消息（follow_up / steer / abort） |\n\n---\n\n## 9. 运行时子系统\n\n### 9.1 自动压缩\n\n插件实现了智能的上下文窗口管理，防止长会话溢出：\n\n| 特性 | 说明 |\n|------|------|\n| **自动修剪** | 上下文达到阈值（~70%）时自动修剪大型工具结果（≥4KB） |\n| **保留近期** | 始终保留最近 ~20K Token 的对话内容 |\n| **预留空间** | 预留 ~16K Token 给模型响应 |\n| **可重放工具** | `read`, `grep`, `glob`, `search`, `find` 的结果可安全修剪（需要时可重新执行） |\n| **压缩续行** | 压缩后自动注入续行提示，Agent 从中断点继续 |\n| **状态持久化** | 修剪状态持久化，跨会话保持 |\n\n### 9.2 GUI 子系统（UCL）\n\n统一通信层（Unified Communication Layer），通过 `PI_GUI=1` 环境变量启用：\n\n```bash\nPI_GUI=1 pi   # 启动带 GUI sidecar 的 Pi\n```\n\n| 特性 | 说明 |\n|------|------|\n| **工具发现** | `GET /tools` — 列出所有可用工具 |\n| **工具调用** | `POST /tools/:name` — 通过 HTTP 调用工具（带权限网关） |\n| **状态聚合** | `GET /state` / `GET /state/:sub` — 聚合会话状态 |\n| **变更事件** | SSE（Server-Sent Events）实时推送状态变更 |\n| **零侵入** | 未启用时无任何行为变化（无监听器、无发现文件） |\n\n### 9.3 TUI 界面组件\n\n插件注册了多个 TUI 覆盖层和面板：\n\n| 组件 | 触发方式 | 功能 |\n|------|---------|------|\n| **Goal 面板** | Goal 存在时自动显示 | 状态、目标、时间、循环次数、Token 预算 |\n| **Todo 覆盖层** | Todo 操作时 | 任务列表和状态 |\n| **Session 覆盖层** | `/maestro-session` | 工作流会话控制中心 |\n| **Maestro 面板** | Maestro 操作时 | 运行状态和进度 |\n| **Swarm 覆盖层** | `/swarm` | 蚁群优化状态、拓扑、指标 |\n| **模型映射覆盖层** | `Alt+M` / `/teammate-models` | 配置 taskType → 模型映射 |\n| **Smart Search 配置** | `Alt+S` / `/smart-search-config` | 搜索引擎和提供商配置 |\n| **MCP 管理器** | `/mcp` | MCP 服务器管理（启用/停用/删除/配置导入） |\n| **MCP 面板** | MCP 工具选择时 | 服务器工具浏览、搜索、调用 |\n| **MCP 设置面板** | 首次 MCP 配置时 | 引导式配置（导入/脚手架/仓库提示） |\n| **进度树** | Teammate 执行时 | Agent 执行进度可视化 |\n| **Attach 覆盖层** | Teammate 启动时 | 附加到 Agent 子进程 |\n| **状态栏** | 持续显示 | 当前模式、压缩状态、MCP 连接状态 |\n\n---\n\n## 10. Agent 角色\n\n### 内置角色\n\n| 角色 | 用途 | 边界 |\n|---|---|---|\n| `general` | 通用实现、分析和验证 | 读写与命令工具 |\n| `explorer` | 代码发现与调用链追踪 | 只读 |\n| `planner` | 架构与执行规划 | 只读，高 thinking |\n| `analyst` | 技术分析和审查 | 只读，高 thinking |\n| `research` | 项目架构知识与外部网络研究 | 只读，知识 CLI 与网络搜索 |\n| `verifier` | 无 acceptance commands 时的 Goal 备用验证 | 严格只读，结构化 fail-closed verdict |\n| `workflow` | 分解并派发依赖 DAG | 读取与 teammate 协作工具 |\n\n旧 `delegate`、`goal-verifier` 和 `coordinator` 不再是内置名称。Goal 优先运行 acceptance commands；仅在未声明 commands 时调用 `verifier`。项目自定义角色放在 `.pi/agents/*.md`，用户角色放在 `~/.agents/*.md`；内置名称不可覆盖。\n\n## 11. Prompt 输入\n\n`tasks[].prompt` 是必需的字面任务文本。Teammate 1.0 不发现 `.pi/prompts`，不提供 bundled Prompt 模板，也不支持 `promptArgs`、位置参数或模板名展开。可复用指令应由调用方或 Skill 生成后作为完整 prompt 传入。\n\n## 12. Skills 索引（68 个）\n\nSkills 是按需加载的能力包，通过 `/skill:name` 调用或由 Agent 自动加载。\n完整 Skill 定义和工作流详情请参阅 [Maestro Flow](https://github.com/catlog22/maestro-flow) 项目。\n\n### 编排与生命周期\n\n| Skill | 简介 |\n|-------|------|\n| `maestro` | 意图到链的规划器，自动路由到最优命令链 |\n| `maestro-next` | 统一开发意图入口，分类复杂度并路由到正确执行通道 |\n| `maestro-companion` | 小任务快速执行，最小化 Run 生命周期 |\n| `maestro-ralph` | 规范化 Session/Run 链上的闭环策略 |\n| `maestro-init` | 项目初始化，自动状态检测 |\n| `maestro-fork` | 创建/同步会话工作树，用于并行开发 |\n| `maestro-merge` | 合并工作树分支回主分支 |\n| `maestro-session-seal` | 封印当前会话，提取知识并推进 DAG |\n| `maestro-update` | 检测版本、预览变更、应用工作流升级 |\n| `maestro-help` | 命令帮助系统，搜索命令、浏览技能 |\n| `maestro-guard` | 管理编辑边界限制 |\n| `maestro-overlay` | 从自然语言创建/编辑命令覆盖层 |\n\n### 质量与测试\n\n| Skill | 简介 |\n|-------|------|\n| `quality-refactor` | 系统性技术债识别与安全削减 |\n| `security-audit` | OWASP Top 10 + STRIDE 安全审计 |\n| `insight-challenge` | 对代码质量发现进行对抗性审查 |\n| `delegation-check` | 检查工作流委派 Prompt 的内容分离违规 |\n\n### UI / 设计\n\n| Skill | 简介 |\n|-------|------|\n| `maestro-impeccable` | 前端 UI 设计、审计、打磨 |\n\n### 团队协作\n\n| Skill | 简介 |\n|-------|------|\n| `team-coordinate` | 通用团队协调，动态角色生成 |\n| `team-lifecycle-v4` | 完整生命周期：计划→开发→测试→审查 |\n| `team-review` | 3 角色代码审查管线：扫描→审查→修复 |\n| `team-testing` | 渐进式测试覆盖（Generator-Critic 循环） |\n| `team-quality-assurance` | 全闭环 QA（问题发现 + 测试） |\n| `team-brainstorm` | 统一头脑风暴团队 |\n| `team-arch-opt` | 架构优化 |\n| `team-perf-opt` | 性能优化（单/扇出/并行模式） |\n| `team-tech-debt` | 技术债识别与修复 |\n| `team-roadmap-dev` | 路线图驱动开发 |\n| `team-planex` | 计划-执行管线 |\n| `team-ultra-analyze` | 深度协作多角色调查 |\n| `team-issue` | 问题解决团队 |\n| `team-swarm` | ACO 蚁群智能多 Agent 探索 |\n| `team-adversarial-swarm` | 带对抗决策门的蚁群智能 |\n| `team-frontend` | 统一前端开发（含 ui-ux-pro-max 设计智能） |\n| `team-frontend-debug` | Chrome DevTools MCP 前端调试 |\n| `team-uidesign` | UI 设计团队：研究→令牌→审计→实现 |\n| `team-ui-polish` | 自动发现/修复 UI 问题 |\n| `team-motion-design` | 动画令牌系统、滚动编排、GPU 变换 |\n| `team-visual-a11y` | 视觉无障碍 QA（OKLCH 对比度、WCAG AA/AAA） |\n| `team-ux-improve` | 发现/修复 UI/UX 交互问题 |\n| `team-interactive-craft` | 原生 JS+CSS 交互组件（零依赖） |\n| `team-designer` | 团队 Skill 生成元技能 |\n| `team-executor` | 轻量级会话执行（恢复已有 team-coordinate 会话） |\n\n### 长时循环（Odyssey）\n\n| Skill | 简介 |\n|-------|------|\n| `odyssey` | 长时迭代循环，五模式（debug/improve/planex/review/ui） |\n| `maestro-odyssey` | 长时迭代循环，六模式（+security） |\n\n### 知识管理\n\n| Skill | 简介 |\n|-------|------|\n| `maestro-spec` | Spec 沉淀（意图驱动录入项目约束规则） |\n| `maestro-knowhow` | KnowHow 沉淀（意图驱动按类型捕获可复用知识） |\n| `maestro-knowledge` | 知识存储管理（意图驱动：audit/harvest/wiki/extractors/domain） |\n| `maestro-issue` | Issue 管理（意图驱动：报告/列出/关闭/关联 + 自动发现） |\n| `codify-to-knowhow` | 清单驱动的知识资产生成器 |\n\n### 学术写作（Scholar）\n\n| Skill | 简介 |\n|-------|------|\n| `scholar-ideation` | 研究构思（文献→缺口分析→规划） |\n| `scholar-writing` | 端到端学术论文写作（NeurIPS/ICML/ICLR 等） |\n| `scholar-review` | 系统性论文审查（自审 + Rebuttal） |\n| `scholar-rebuttal-pro` | 增强型 Rebuttal（协作分析 + 多视角） |\n| `scholar-experiment` | ML/AI 论文实验结果分析 |\n| `scholar-citation-verify` | 四层引用验证 |\n| `scholar-anti-ai-writing` | 去除学术文章中的 AI 写作模式 |\n| `scholar-latex-organizer` | 整理 LaTeX 模板为 Overleaf 可用结构 |\n| `scholar-publish` | 录用后会议准备（幻灯片/海报/宣传） |\n| `scholar-thesis-docx` | 创建/修订学位论文 Word 文档 |\n\n### 元 / 工具\n\n| Skill | 简介 |\n|-------|------|\n| `prompt-generator` | 生成/转换 Prompt 文件（GSD 风格质量门） |\n| `skill-generator` | 创建新 Skill 的元技能 |\n| `skill-iter-tune` | 迭代 Skill 调优（执行→评估→改进） |\n| `skill-simplify` | SKILL.md 简化（功能完整性验证） |\n| `skill-tuning` | 通用 Skill 诊断与优化 |\n| `workflow-skill-designer` | 编排器+阶段工作流 Skill 设计元技能 |\n| `swarm` | 蚁群优化状态投影 |\n\n### 学习\n\n| Skill | 简介 |\n|-------|------|\n| `learn` / `maestro-learn` | 引导式阅读、调查、模式提取、第二意见 |\n\n---\n\n## 13. 知识系统\n\n知识系统确保 Agent 在接触代码前拥有完整的项目上下文。\n\n### 强制知识门\n\n在任何代码访问或调度之前执行：\n\n```bash\n# 搜索（跨 spec、knowhow、domain、issue、session）\nmaestro search \"<查询>\" [--type spec|knowhow|domain|issue] [--code] [--kg]\n\n# 加载特定知识\nmaestro load --type <type> [--list] [--category <cat>] [--keyword <word>] [--id <id>]\n```\n\n### 查询规则\n\n```bash\n# ❌ 避免关键词堆砌\nmaestro search \"topology display frontend DetailedTopologySVG elk layout rendering\"\n\n# ✅ 使用聚焦查询\nmaestro search \"topology layout\"\nmaestro search \"DetailedTopologySVG\" --code\nmaestro load --type spec --category coding\n```\n\n### 知识类型\n\n| 类型 | 分类 | 用途 |\n|------|------|------|\n| `spec` | `arch`, `coding`, `debug`, `test`, `review`, `learning`, `ui` | 可复用约定和规则 |\n| `knowhow` | `compact`, `tip` | 任务特定模式和配方 |\n| `domain` | — | 项目术语表 |\n| `issue` | — | 跟踪的 Bug 和任务 |\n| `roadmap` | — | 里程碑和阶段规划 |\n\n### 知识生命周期\n\n```bash\n# 添加\n/maestro-spec \"coding: 使用 Result<T,E> — 服务方法必须返回 Result<T,AppError>\"\n/maestro-knowhow\n\n# 演化\nmaestro spec supersede SPEC-042 --by SPEC-089     # 替代旧规则\nmaestro spec conflict mark src/auth.ts 45 --note \"JWT vs session: 两者均有效\"\n\n# 维护\nmaestro spec health                                # 健康检查\nmaestro spec history SPEC-042                     # 查看历史\nmaestro search \"旧模式\" --include-deprecated       # 搜索全部\n```\n\n### 三轴正交\n\n| 轴 | 说明 |\n|----|------|\n| `confidence` | 人工/审计裁决 |\n| `status` | active / deprecated 生命周期 |\n| 时间衰减 | 自动新鲜度衰减 |\n\n---\n\n## 14. 工作流模式\n\n### 模式 1：门控 → 探索 → 实现\n\n```\n1. maestro search + load      → 知识门\n2. teammate (explorer × 2-3)  → 交叉搜索建立信心\n3. 定向读取                    → 验证单匹配结果\n4. teammate (delegate)         → 带完整上下文实现\n5. /skill:quality-review       → 验证\n```\n\n### 模式 2：计划 → 执行 → 验证\n\n```\n1. maestro search + load      → 知识门\n2. /skill:maestro-plan         → 创建执行计划\n3. /skill:maestro-execute      → 逐步执行 + 验证\n4. workflow-verifier           → 目标反向验证\n5. /skill:quality-test         → 验收测试\n```\n\n### 模式 3：并行审查 → 合成 → 修复 → 复审\n\n```\n1. teammate (reviewer × 3)    → 安全、性能、可维护性\n2. teammate (delegate)         → 合成发现\n3. teammate (delegate)         → 修复最高优先级问题\n4. teammate (reviewer × 3)    → 复审修复\n```\n\n### 模式 4：Odyssey 完整循环\n\n```\n1. /skill:odyssey-debug        → 考古 → 诊断 → 修复 → 泛化\n2. /skill:quality-test         → 验证修复\n3. /maestro-knowhow            → 持久化经验\n```\n\n### 模式 5：多阶段 DAG 管线\n\n```javascript\nteammate({\n  tasks: [\n    // 阶段 1: 并行研究\n    { name: \"api-research\", agent: \"workflow-external-researcher\", prompt: \"研究速率限制最佳实践\" },\n    { name: \"codebase-survey\", agent: \"explorer\", prompt: \"FIND: 所有 API 端点\\nSCOPE: src/api/\" },\n    // 阶段 2: 规划（研究 + 调查完成后）\n    { name: \"plan\", agent: \"workflow-planner\", prompt: \"整合 {api-research} + {codebase-survey} 制定计划\" },\n    // 阶段 3: 实现\n    { name: \"implement\", agent: \"workflow-executor\", prompt: \"执行 {plan}\" },\n    // 阶段 4: 验证\n    { name: \"verify\", agent: \"workflow-verifier\", prompt: \"验证 {implement} 是否满足 {plan}\" }\n  ]\n})\n```\n\n### Explorer 交叉搜索策略\n\n| 角度 | 任务 A | 任务 B |\n|------|--------|--------|\n| 定义 vs 使用 | 查找导出定义 | 查找导入和调用点 |\n| 正面 vs 缺失 | 查找正确实现 | 查找缺少约定的地方 |\n| 入口 vs 实现 | 查找路由或导出 | 查找内部逻辑 |\n\n**信心规则：**\n- ✅ 两个角度匹配 → 高信心，直接使用\n- ⚠️ 一个角度匹配 → 用 `rg` 或定向读取验证\n- ❌ 零匹配 → 换角度或结论目标不存在\n\n---\n\n## 15. 配置参考\n\n### 模型路由（`.pi/teammate-models.json`）\n\n```json\n{\n  \"global\": \"deepseek/deepseek-v4-pro\",\n  \"mappings\": {\n    \"explore\": \"deepseek/deepseek-v4-flash\",\n    \"analysis\": \"deepseek/deepseek-v4-pro\",\n    \"development\": \"deepseek/deepseek-v4-pro\",\n    \"review\": \"deepseek/deepseek-v4-flash\",\n    \"testing\": \"deepseek/deepseek-v4-flash\",\n    \"planning\": \"deepseek/deepseek-v4-pro\",\n    \"debug\": \"deepseek/deepseek-v4-pro\"\n  }\n}\n```\n\n通过 `Alt+M` 或 `/teammate-models` 交互式配置。\n\n### 项目级配置\n\n| 文件 | 用途 |\n|------|------|\n| `.pi/teammate-models.json` | 本项目的模型路由映射 |\n| `.pi/agents/` | 项目特定 Agent 定义 |\n| `.pi/settings.json` | Pi 设置覆盖 |\n\n### 全局配置\n\n| 文件 | 用途 |\n|------|------|\n| `~/.pi/agent/teammate-models.json` | 全局模型路由默认值 |\n| `~/.pi/agent/settings.json` | 全局 Pi 设置 |\n\n---\n\n## 16. 故障排除\n\n### Teammate 无法启动\n\n```\nError: Failed to spawn teammate process\n```\n\n**检查：** `which pi`、`node --version`（≥22.19.0）、`/teammate-models` 模型配置。\n\n### Explorer 无结果\n\n**修复：** 验证 `SCOPE` 路径存在，使 `FIND` 更具体，添加 `ATTENTION` 说明命名约定。\n\n### 知识门失败\n\n```\nmaestro: command not found\n```\n\n**修复：** `npm install -g maestro-flow`\n\n### 模型不可用\n\n```\nError: Model not found in authenticated catalog\n```\n\n**修复：** `/teammate-models` → 检查可用模型 → `/login` 认证。\n\n### Agent 挂起\n\n```javascript\nteammate-list({ view: \"all\" })                          // 检查状态\nteammate-watch({ name: \"stuck\", lines: 50 })            // 查看输出\nteammate-send({ to: \"stuck\", mode: \"abort\" })           // 终止\n// 带超时重试:\nteammate({ tasks: [{ agent: \"general\", prompt: \"...\", timeoutMs: 120000 }] })\n```\n\n### 长会话上下文溢出\n\n```bash\n/compact \"总结关键决策和当前状态\"\n# 或对重工作使用 fresh 上下文:\nteammate({ tasks: [{ agent: \"general\", context: \"fresh\", prompt: \"PURPOSE: 读取状态并继续\\n...\" }] })\n```\n\n---\n\n## 快速参考\n\n```bash\n# ─── 安装 ───\npi install npm:pi-maestro-flow\n\n# ─── 知识 ───\nmaestro search \"查询\" --code\nmaestro load --type spec --category coding\n\n# ─── 探索 ───\nteammate({ tasks: [{ agent: \"explorer\", taskType: \"explore\", prompt: \"FIND: ...\\nSCOPE: src/...\" }] })\n\n# ─── 分析 ───\nteammate({ tasks: [{ agent: \"analyst\", taskType: \"analysis\", prompt: \"分析目标并提供 file:line 证据\" }] })\n\n# ─── 实现 ───\nteammate({ tasks: [{ agent: \"general\", taskType: \"development\", prompt: \"实现目标并运行 focused tests\" }] })\n\n# ─── 审查 ───\n/skill:team-review src/ --level deep\n\n# ─── 完整循环 ───\n/skill:maestro-analyze → /skill:maestro-plan → /skill:maestro-execute → /skill:quality-review\n\n# ─── 调试 ───\n/skill:odyssey-debug \"问题描述\"\n\n# ─── Agent 控制 ───\nteammate-list({ view: \"all\" })\nteammate-watch({ name: \"agent\", lines: 30 })\nteammate-send({ to: \"agent\", message: \"...\" })\nteammate-send({ to: \"agent\", mode: \"abort\" })\n```\n"}}}}