BlackBeltTechnology/pi-agent-dashboard 源码：https://github.com/BlackBeltTechnology/pi-agent-dashboard # PI Dashboard CI（https://github.com/BlackBeltTechnology/pi-agent-dashboard/actions/workflows/ci.yml） npm（https://www.npmjs.com/package/@blackbelt-technology/pi-dashboard） 许可证：MIT（https://opensource.org/licenses/MIT） 一款 Web 仪表盘，可在任意浏览器（含移动端）中监控并与 pi（https://github.com/badlogic/pi-mono）代理会话交互。 官网： blackbelttechnology.github.io/pi-agent-dashboard（https://blackbelttechnology.github.io/pi-agent-dashboard）——动画演示、截图与安装指南。 更新日志： 见 CHANGELOG.md 获取发版说明。 发版流程： 见 docs/release-process.md 了解如何切版本。 ## 功能 - 实时会话镜像 —— 查看所有活跃 pi 会话，消息实时推送 - 双向交互 —— 在浏览器内发送提示与命令 - 工作区管理 —— 按项目文件夹组织会话，支持固定目录与拖拽排序 - 命令自动补全 —— 输入 / 触发命令下拉框并支持过滤 - 会话统计 —— Token 用量、费用、模型信息、思维等级、上下文占用条 - 耗时追踪 —— 运行中的操作实时计时，工具调用与推理块完成后显示最终耗时 - 移动端友好 —— 响应式布局，侧滑抽屉、触控靶区、移动端操作菜单 - 会话孵化 —— 从仪表盘启动新 pi 会话（默认 headless，也可走 tmux） - PromptBus 架构 —— 统一提示路由，支持多适配器（TUI、仪表盘、自定义）。交互式对话框（确认/选择/输入/编辑器/多选）刷新页面或重启服务器后依旧可用，首响应胜出并跨适配器自动关闭。 - 按需加载历史 —— 浏览历史会话，内容随 pi 会话文件惰性加载 - 集成终端 —— 全功能浏览器终端（xterm.js + node-pty），支持 ANSI 色、滚屏、保活 - pi-flows 集成 —— 实时流程执行仪表盘，含代理卡片、详情视图、流程图可视化、摘要、中止/自动控件。可在浏览器内启动流程并用 Flow Architect 设计新流程，Fork 决策与子代理对话框通过 PromptBus 转发。 - 强制终止升级 —— 两步 Stop 按钮（命令栏与运行工具卡均提供）：第一次软中止，第二次强制杀进程（SIGTERM → SIGKILL）。会话标记为“已结束”仍可恢复/分叉。重复工具调用（如健康检查循环）自动折叠并显示计数徽章。 - 可搜索选择框 —— 键盘导航选择器，实时过滤 OpenSpec 变更与流程命令 - 浏览器内供应商认证 —— 在设置页直接登录 Anthropic、OpenAI Codex、GitHub Copilot、Gemini CLI、Antigravity；其他供应商输入 API 密钥即可。凭据保存至 ~/.pi/agent/auth.json 并实时同步到运行中的会话。 - 包管理 —— 在仪表盘内浏览、安装、更新、卸载 pi 包。可搜索 npm 注册表中的 pi 扩展/技能/主题，支持 npm 或 git URL 安装，全局包在设置页管理，本地包按工作区管理。所有活跃会话在变更后自动重载。 - OpenSpec 集成 —— 在会话侧边栏浏览规范、查看归档历史、管理变更、创建新变更 - Diff 查看器 —— 并排与统一 diff 视图，带文件树导航，方便复查代理改动 - 编辑器集成 —— 在工具调用卡中一键用首选编辑器（VS Code、Cursor 等）打开文件 - Markdown 预览 —— 渲染 Markdown，支持搜索、mermaid 图、语法高亮 - 网络发现 —— 基于 mDNS 的本地仪表盘服务器自动发现；也可连接已知远程服务器 ## 架构 mermaid graph LR subgraph "每个 pi 会话" B[Bridge Extension] end subgraph "仪表盘服务器 (Node.js)" PG[Pi Gateway :9999] BG[Browser Gateway :8000] HTTP[HTTP / 静态文件] MEM[(内存存储)] JSON[(JSON 文件)] end subgraph "浏览器" UI[React Web 客户端] end B <-->|WebSocket| PG UI <-->|WebSocket| BG UI -->|HTTP| HTTP PG --- MEM PG --- JSON BG --- MEM 系统由三大组件构成： | 组件 | 位置 | 职责 | |———–|–––––|——| | Bridge Extension | packages/extension/ | 在每个 pi 会话内运行，转发事件、中继命令、自动启动服务器、托管 PromptBus。 | | Dashboard Server | packages/server/ | 内存聚合事件，元数据持久化到 JSON，为 Web 客户端提供服务，管理终端。 | | Web Client | packages/client/ | React + Tailwind UI，通过 WebSocket 实时更新。 | | Shared | packages/shared/ | TypeScript 类型、协议与工具，供所有包共享。 | 详见 docs/architecture.md 了解数据流、重连逻辑与持久化模型。 ## 入门 提供三种使用方式，由简到繁： ### 方案 A：Electron 桌面应用（独立版，零依赖） 从 GitHub Releases（https://github.com/BlackBeltTechnology/pi-agent-dashboard/releases）下载对应平台安装包： | 平台 | 下载 | |–––––|–––––| | macOS (Apple Silicon) | .dmg (arm64) | | macOS (Intel) | .dmg (x64) | | Linux (x64) | .deb 或 .AppImage | | Linux (ARM64) | .deb | | Windows (x64) | .exe (NSIS 安装器)、.zip 或绿色 .exe | | Windows (ARM64) | .zip 或绿色 .exe | 首次启动时，设置向导会引导你： 1. 选择模式： - Standalone —— 内置 Node.js，自动把 pi + 仪表盘 + openspec 装到 ~/.pi-dashboard/，无需系统 Node.js、npm 或构建工具。 - Power User —— 使用你已安装的 pi 与仪表盘。 2. 配置 API 密钥 —— 输入 Anthropic/OpenAI 密钥或通过浏览器 OAuth 登录。 3. 推荐扩展 —— 一键安装仪表盘配套精选 pi 扩展（见下方推荐扩展）。也可跳过，稍后到 Packages 标签管理。 4. 完成 —— 应用自动发现或孵化仪表盘服务器。 > 无需终端、无需 npm、无需 Node.js。 独立模式 Electron 应用完全自包含，内置 Node.js 运行时，内部孵化仪表盘服务器并管理全部依赖。系统托盘集成可后台常驻。 ### 方案 B：pi 包（CLI 用户推荐） 需先安装 pi（https://github.com/badlogic/pi-mono）（或 Oh My Pi（https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent））与 Node.js ≥ 22.18.0（或 ≥ 24.3.0）。旧版 Node 22.x / 24.x 受 nodejs/node#58515（https://github.com/nodejs/node/issues/58515）影响，会导致 Fastify 启动崩溃。 bash pi install npm:@blackbelt-technology/pi-dashboard pi 桥接扩展会在首次启动时自动运行仪表盘服务器，你将看到： 🌐 Dashboard started at http://localhost:8000 在任意浏览器打开 http://localhost:8000，所有活跃 pi 会话自动出现。 ### 方案 C：本地开发安装 bash git clone https://github.com/BlackBeltTechnology/pi-agent-dashboard.git cd pi-agent-dashboard npm install pi install /path/to/pi-agent-dashboard ## 推荐扩展 仪表盘与少量精选 pi 扩展深度集成——用于自定义工具渲染、Flow 仪表盘、anthropic-messages 协议兼容。向导的“推荐扩展”一步可一次性安装；后续也可在 Packages 标签或页面顶部横幅管理。 | 扩展 | 源码 | 状态 | 作用 | |—|—|—|—| | pi-anthropic-messages | [email protected]:BlackBeltTechnology/pi-anthropic-messages.git | 必需 | 在 Claude 模型 Anthropic OAuth / 9Router cc/* / pi-model-proxy 供应商上启用工具调用。无此扩展则工具调用回退到 Claude Code 内置 bash_ide 沙箱并失败。 | | @tintinweb/pi-subagents | npm:@tintinweb/pi-subagents | 强烈建议 | Agent 工具卡片 UI、子代理活动徽章、get_subagent_result / steer_subagent 渲染器。 | | pi-flows | [email protected]:BlackBeltTechnology/pi-flows.git | 强烈建议 | Flow 仪表盘、角色别名（@planning、@coding…）、subagent / flow_write / flow_results / agent_write / ask_user / skill_read / finish 工具。 | | pi-web-access | npm:pi-web-access | 强烈建议 | web_search、code_search、fetch_content、get_search_content。 | | pi-agent-browser | npm:pi-agent-browser | 可选 | browser 工具（打开、快照、点击、截图）。 | 权威来源：packages/shared/src/recommended-extensions.ts。描述、版本与安装状态在运行时通过 GET /api/packages/recommended 动态获取（网络失败时回退到离线描述）。 ### GitHub SSH 说明 pi-flows 与 pi-anthropic-messages 通过 pi install [email protected]:...（SSH）安装。若系统未配置 GitHub SSH 密钥，克隆会报“Permission denied (publickey)”错误。按 GitHub SSH 文档（https://docs.github.com/en/authentication/connecting-to-github-with-ssh）配置密钥，或若你的 fork 公开，可在清单中换成等效 HTTPS 地址。 ### 免安装快速体验 若只想在当前 pi 会话试用扩展，无需注册： bash pi -e /path/to/pi-agent-dashboard/packages/extension/src/bridge.ts ## 前置依赖 仅方案 B/C 需要（Electron 应用已全自动处理）。 | 依赖 | 原因 | 安装方式 | |———––|—–|———| | pi（https://github.com/badlogic/pi-mono） 或 Oh My Pi（https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent） | 被仪表盘监控的 AI 编码代理 | npm i -g @mariozechner/pi-coding-agent | | Node.js ≥ 22.18.0 | 仪表盘服务器运行时（旧版 22.x / 24.x 受 nodejs/node#58515（https://github.com/nodejs/node/issues/58515）影响） | nodejs.org（https://nodejs.org/） | | C++ 构建工具 | node-pty 原生模块需要 | Xcode CLI Tools（macOS）/build-essential（Linux） | ### 可选工具 | 工具 | 用途 | 何时需要 | |——|———|———––| | tmux | 在浏览器内以 tmux 窗口方式孵化新 pi 会话 | 当 spawnStrategy 为 "tmux" 时 | | zrok（https://zrok.io/） | 通过隧道将仪表盘暴露到公网（服务器启动时自动连接）。macOS 用 brew install zrok 安装并执行 zrok enable 注册——仪表盘读取 zrok 自有配置（~/.zrok2/environment.json），不存储密钥。使用预留共享实现重启后 URL 不变。 | 当 tunnel.enabled 为 true（默认）时 | ## 配置 配置文件：~/.pi/dashboard/config.json（首次运行自动生成默认值） 工具路径覆盖（可选，本机专用）：~/.pi/dashboard/tool-overrides.json——见下方工具解析与覆盖。 json { "port": 8000, "piPort": 9999, "autoStart": true, "autoShutdown": false, "shutdownIdleSeconds": 300, "spawnStrategy": "headless", "tunnel": { "enabled": true, "reservedToken": "auto-created-on-first-run" }, "devBuildOnReload": false, "openspec": { "pollIntervalSeconds": 30, "maxConcurrentSpawns": 3, "changeDetection": "mtime", "jitterSeconds": 5 } } OpenSpec 后台轮询（openspec 块）： | 键 | 默认值 | 范围 | 说明 | |—–|———|—––|———––| | pollIntervalSeconds | 30 | 5–3600 | 每个已知目录轮询 OpenSpec 更新的间隔 | | maxConcurrentSpawns | 3 | 1–16 | 所有目录并发 openspec CLI 调用上限 | | changeDetection | "mtime" | "mtime" \| "always" | mtime 跳过未变更提案的再轮询（稳态几乎零开销）；always 无条件轮询 | | jitterSeconds | 5 | 0–60 | 每目录相位偏移，避免所有轮询同时触发 | 可在运行时通过 设置 → 高级 → “Background polling (OpenSpec)” 或 PUT /api/config 热更新，无需重启服务器。成本模型见 docs/architecture.md。 ### 工具解析与覆盖 仪表盘对外部工具（pi、pi-coding-agent、openspec、npm、node、tsx、git、zrok、pi-dashboard）的解析统一通过 ToolRegistry。每个工具按顺序链式策略（覆盖 → 托管安装 → 裸导入/npm 全局 → PATH 搜索），并记录诊断轨迹说明每一步为何成功/失败。 查看与覆盖 —— 设置 → 常规 → 工具 展示每个工具的解析结果、来源与轨迹。可设置单工具覆盖路径、重新扫描单工具或全部，并导出完整诊断报告用于反馈。 覆盖文件 —— ~/.pi/dashboard/tool-overrides.json： json { "version": 1, "overrides": { "pi": { "path": "C:\\custom\\pi.cmd" }, "pi-coding-agent": { "path": "D:\\dev\\pi-coding-agent\\dist\\index.js" } } } 该文件独立于 config.json，避免机器特定路径随 dotfiles 同步到另一台主机。无效覆盖（路径不存在）会被记录在诊断轨迹，注册表自动回落到下一策略。 排障 —— 若仪表盘提示找不到 pi、openspec、npm 等，打开 设置 → 常规 → 工具，点击失败工具旁的箭头查看完整 tried[] 轨迹，然后 (a) 在 PATH/托管位置安装缺失工具，或 (b) 在行内路径输入框设置显式覆盖。点击 重新扫描 无需重启服务器即可生效。 排障：会话未归到固定文件夹 —— 自 v0.3+ 起，会话分组使用系统感知路径相等逻辑（platform/paths.ts）。即使固定时与会话上报的路径在尾部分隔符、分隔符风格或大小写（Windows/macOS）不同，也能正确归组。若仍看到同一文件夹出现两条目，极可能是不同 Windows 盘符（A:\Foo 与 B:\Foo 属于不同文件系统，不会合并）——这是预期行为，非 bug。若路径确实相同，请提 issue 并附上固定路径（设置 → 工具 → 导出诊断可见）与会话 cwd（/api/sessions 上报）。 ### Windows 会话持久性 行为变更：自 consolidate-windows-spawn-and-platform-handlers 版本起，Windows 上的 pi 会话在仪表盘服务器重启后依旧存活，与 macOS/Linux 行为一致。此前，杀死或重启仪表盘进程（任务管理器、Ctrl+C、/api/restart、崩溃）会导致所有 pi 会话被终止，因为子进程位于服务器的 libuv 随关随杀 Job Object 中。修复方案使用 detached: true 把子进程排除在父 Job 之外——相当于 Windows 版 Unix PGID 脱离。若你之前依赖“关闭仪表盘即清场”，请改用单会话 强制终止 动作（或通过 REST API POST /api/session/:id/force-kill）。 建议：安装 Windows Terminal（wt.exe），在 Windows 10/11 获得标签化交互会话。仪表盘优先使用 wt（在已有 WT 窗口新建标签，尊重默认配置文件——cmd/PowerShell/WSL/任意），其次回落到 WSL tmux，最后 headless 模式。Windows 11 已内置 Windows Terminal；Windows 10 需手动安装。