pi-harness

中文 · English

pi-harness 是独立维护的 pi coding agent Web 与桌面界面。在浏览器或 Electron 窗口中使用 Agent 对话、文件树与预览、附件、终端、模型管理，以及内置的 SSH 节点工作台。

SSH 工作台让 macOS 或 Windows 上的本机 pi-harness 服务连接 Linux/macOS 节点：左侧按组管理节点，中间开多个 SSH 终端标签并通过 SFTP 浏览文件，右侧是各节点独立的 Agent 对话。Agent 使用当前选中的远端终端执行命令，输出在终端中可见。节点的实际操作权限由远端账号或容器决定。

快速开始

需要 Node.js 22.19.0 或更高版本，以及至少一个已配置的 pi 模型服务商（~/.pi/agent）。

npm install -g @youweichen/pi-harness
pi-harness                        # 打开 http://127.0.0.1:8787
pi-harness --port 9000 --cwd /path/to/project

不安装到全局也可以运行 npx @youweichen/pi-harness。升级后若使用开机自启服务，运行 pi-harness server restart，让服务端加载新版本。

版本与升级

正式版通过 npm install -g @youweichen/pi-harness@latest 安装，桌面安装包见 GitHub Releases。1.0.0 起 npm 包名为 @youweichen/pi-harness，命令为 pi-harness；旧包 @youweichen/pi-web-ui 不再更新，也不会自动迁移。旧版开机自启服务仍会启动旧包并占用同一端口，升级前先运行 pi-web-ui server uninstall 和 npm uninstall -g @youweichen/pi-web-ui，再安装新包；需要开机自启时重新运行 pi-harness server install（带上原来的 --port／--cwd）。可运行 npm view @youweichen/pi-harness dist-tags --json 核对 npm 标签。

SSH 节点工作台

1. 打开顶栏「SSH 节点」，点击左侧 ＋ 新增节点。填写分组、名称、地址、端口、用户名、认证方式和默认目录。
2. 选择密码、本机私钥路径或本机 SSH agent 认证。密码和私钥口令保存在本机加密存储中；导入、导出节点 JSON 不包含凭据。
3. 首次连接时核对远端主机密钥指纹，再选择信任。密钥变化会阻止连接；确认服务器换钥后，可在节点编辑窗口清除旧信任并重新核对。
4. 连接后打开终端标签。右侧 Agent 使用当前选中的标签，保留该 shell 的目录和环境；运行时锁定人工输入，命令及结果同时显示在终端和对话中。

节点资料分别保存在每台客户端，不自动同步。可从旧版 Remote-SSH 插件导入主机资料，旧配置不会被删除，凭据需要重新填写。SSH 工作台与本地项目终端相互独立。

详细步骤、密钥配置、SFTP、故障排查见 内置 SSH 节点工作台手册。Windows 用户如果还使用外部 Xshell，可参考 Xshell 与 SSH 连接手册。

其他功能

• 多项目与多对话、消息流式显示、文件树与预览、文件附件和编辑。
• 本地终端（xterm.js + node-pty）、Git 视图、模型及思考强度选择。
• 中文和英文界面、声音提醒、可选插件及 pi 扩展。
• CLI、开机自启服务、Docker 与 Electron 桌面版。

文档转换与 OKF Wiki

内置两个独立扩展，默认开启并可分别关闭。文档转换扩展把 PDF、CHM、Office、文本和源码转换为结构化 Markdown，保留原件、表格、代码、图片与来源定位。知识蒸馏扩展只接收 Markdown／证据包，由当前 Agent 提取候选、去重、核对版本与冲突，生成 OKF Wiki 草稿；实际人工复核后才标记为 stable。

/documents setup
/documents convert ./raw/技术说明.pdf
/okf ingest ./converted，输出到 ./knowledge
/okf review <jobId>

PDF 与 Office 解析需要单独的本机 Python 3.12 环境，首次运行 setup 会安装依赖并下载模型；可用 /documents cancel 取消、/documents doctor 检查。CHM 使用 /documents setup chm 准备轻量解析环境，不下载 OCR 模型。Markdown、文本和源码转换不需要 Python，知识扩展也不依赖转换运行时。旧 /pdf-md 命令仍兼容。知识整理使用当前会话选定的模型，自动生成的知识全部保留草稿，原文快照随知识目录保存。设置、恢复与资料移交见 文档知识扩展说明。

运行与部署

pi-harness server install   # macOS: launchd；Windows: 计划任务；Linux: systemd
pi-harness server status    # 也支持 start、stop、restart、uninstall

默认只监听 127.0.0.1。如果需要从其他设备访问，请参阅 部署手册 配置监听地址与 PI_WEB_TOKEN 鉴权；不要直接把未保护的 Web 界面暴露到公网。Docker 与环境变量也见 部署手册 和 环境变量列表。

桌面安装包在 GitHub Releases 提供。Electron 使用同一套服务端和界面，桌面版数据目录是 ~/.pi-web-desktop，CLI 默认是 ~/.pi-web；pi 的对话历史仍由 ~/.pi/agent 管理。安装包目前未签名。源码构建方式见 部署手册。

开发

npm ci
npm run dev            # 后端 :8788，Vite :5173
npm run typecheck
npm run build
npm test
npm run test:smoke

项目架构与测试规范见 docs/development.md。源码及问题反馈位于 youweichen0208/pi-harness。

English

pi-harness is an independently maintained web and Electron interface for the pi coding agent SDK. It includes chat, file browsing and editing, attachments, a local terminal, model management, and a built-in SSH node workbench with grouped hosts, multiple PTY tabs, SFTP files, and a separate Agent conversation for each node.

Two independent, default-enabled extensions handle document conversion and knowledge distillation. Use /documents convert <path> to produce Markdown and a portable evidence bundle from PDF, CHM, Office, text or source code; prepare PDF/Office with /documents setup, or CHM with /documents setup chm. Use /okf ingest <Markdown or bundle directory> to extract and cross-check candidates with the current Pi Agent. Generated Wiki knowledge remains draft until actual human review via /okf review <jobId>. Each extension has its own settings on|off command; the legacy /pdf-md alias remains available. See the document extensions guide.

Requires Node.js >= 22.19.0 and a configured pi model provider. Install with npm install -g @youweichen/pi-harness, then run pi-harness. See the SSH workbench guide, Xshell guide, and deployment guide.

License

MIT