pi-tool

Pi 编码助手的 Web 管理工具。提供图形化界面管理会话、模型、MCP 和 Pi 配置。

功能

• 会话管理 — 浏览、查看、删除各项目的对话会话，支持批量删除
• 模型配置 — 可视化编辑 ~/.pi/agent/models.json
• MCP 管理 — 编辑 MCP 服务器配置
• 配置文件 — 编辑 Pi 的 settings.json，支持表单/源文件双模式
• Skills 管理 — 查看、临时禁用、启用、删除全局 Skills（~/.pi/agent/skills/）
• 扩展管理 — 查看、临时禁用、启用、删除扩展，支持本地目录扩展和 pi install 安装的包扩展

安装

# 全局安装
npm i -g pi-tool

# 或通过 npx 临时使用
npx pi-tool

# 本地开发
pnpm dev

使用

pi-tool                      # 启动 Web 服务器（默认端口 13579，自动打开浏览器）
pi-tool start                # 同上
pi-tool stop                 # 停止服务器
pi-tool restart              # 重启服务器
pi-tool status               # 查看服务器状态

pi-tool -p 8080              # 指定端口启动
pi-tool --port 8080 start    # 同上
pi-tool -h                   # 显示帮助
pi-tool -V                   # 显示版本

启动后浏览器打开 http://localhost:13579 即可使用管理界面。

Skills 管理

侧边栏点击"Skills 管理"进入，支持标签切换查看"已启用"/"已禁用"的 Skill。

临时禁用

将 Skill 目录从 ~/.pi/agent/skills/<name>/ 移动到 ~/.pi/agent/skills/.disabled/<name>/， Pi 不再读取。需要执行 /reload 使改动生效。

删除

直接删除 Skill 目录。不可撤销。

扩展管理

侧边栏点击"扩展管理"进入，支持标签切换查看"已启用"/"已禁用"的扩展。

扩展分两类管理：

本地目录扩展（~/.pi/agent/extensions/）

• 禁用：目录移动到 ~/.pi/agent/extensions/.disabled/<name>/
• 删除：直接删除目录

包扩展（通过 pi install 安装）

• 禁用：从 settings.json 的 packages 数组移除条目，记录到 pi-tool-state.json 以便恢复
• 删除：从 packages 数组移除（不保留记录）
• 启用：从 pi-tool-state.json 读取并还原到 packages 数组

操作后需要执行 /reload 或重启 Pi 使改动生效。

配置文件

侧边栏点击"配置文件"进入，支持两种编辑模式：

表单模式

以表单展示常用配置项（模型、界面、压缩、重试、Shell/终端、网络&会话），修改后点"保存"写入。

注意：表单保存会深度合并到现有配置，不会丢失未在表单中出现的配置（如 packages、planningWithFiles）。

源文件模式

直接编辑 JSON 源文件，支持：

• 语法高亮 — 键名、字符串、数字、布尔值、null 分色显示
• JSON 校验 — 保存前校验格式，非法 JSON 拒绝写入并提示错误
• 只读切换 — 可切换只读/编辑模式防止误改
• Ctrl+S 保存 — 快捷键保存

通过顶部下拉切换作用域（全局 ~/.pi/agent/settings.json / 项目 .pi/settings.json）。

开发

git clone <repo>
cd pi-config/tools/pi-tool
pnpm dev              # 免编译启动开发服务器（tsx 热加载）
pnpm build            # 编译 TypeScript 到 dist/
pnpm build && pnpm start  # 使用编译版本启动

技术

• 后端 — TypeScript + 纯 Node.js http 模块（零运行时依赖）
• 前端 — 纯 ES Module（无框架、无构建步骤）
• 语法高亮 — 基于 contenteditable + DOM 着色（无第三方高亮库）
• 发布 — tsc 编译为 JS，npm 包零运行时依赖