pi-2k 是 Pi Agent Harness(earendil-works/pi) 的个人 fork 工作区,在保留上游全部能力(编码 agent CLI、agent 运行时、统一多模型 API、TUI)的基础上,围绕"本地编码工作台"叠加了三块自定义内容:
- 桌面图形界面(GUI):
packages/gui,基于 Electron 的本地工作台,全程中文界面,直接驱动本机编码 agent。 - 专家团队(Expert Team):
.pi/agents/下 13 个专家 subagent(ask-matt 流程),由主 agent 编排完成访谈、规格、拆票、实现、审查等环节。 - pi-web 前端同步:
apps/pi-web子模块指向 fork(含斜杠命令词边界过滤修复),配合 GitHub Actions 定时同步上游。
在桌面应用里驱动本地编码 agent:发消息、看流式转录、查看工具执行过程、切换模型,全程中文界面。复用 coding-agent 的 --mode rpc 子进程 JSONL 通道,不引入 pi-server。
渲染进程 frontend(React + Vite,中文界面)
│ 前端协议(IPC JSON:请求/响应/事件)
主进程 bridge(Electron 主进程)
│ stdin/stdout JSONL
pi --mode rpc 子进程(coding-agent CLI)
- 前端协议是唯一测试接缝,
src/protocol/index.ts由 bridge 与 frontend 共享同一份类型定义。 - bridge 与 Electron 解耦,可用 stub 子进程独立测试。
- 详细设计见 docs/gui-design.md 与 docs/gui-spec.md,术语表见 CONTEXT.md。
星型协作架构:主 agent 是唯一与用户交互者,专家 subagent 只读、只判断、只执行,通过主 agent 转述与衔接。名册:
| agent | 职责 | 调用方式 |
|---|---|---|
| flow-router | 判流程、排专家、给闸门 | consult |
| griller | 访谈打磨,产问题清单 | consult |
| spec-writer | 线程 → spec | blocking |
| ticket-splitter | spec → 票 + blocking edges | blocking |
| implementer | 单票 TDD 实现 | blocking |
| spec-reviewer | 双轴审查(标准 + spec) | consult / spawn |
| bug-hunter | 难缠 bug:先建反馈环再修 | blocking |
| researcher | 主源调研,带引用笔记 | spawn |
| triager | 外来 issue → agent-ready 票 | blocking |
| handoff-writer | 会话 → 交接文档 | spawn |
| domain-modeler | 词汇审计、ADR 候选 | consult |
| architecture-scout | 架构勘察,deepening 候选 | consult |
| module-designer | 模块形状设计(trade-off) | consult |
完整的工具/模型配置、环境要求与已知坑见 .pi/agents/README.md。
apps/pi-web为子模块,指向 ag-jin/pi-web fork,附带斜杠命令面板词边界过滤修复(避免 "ask" 误匹配 "task")。scripts/sync-pi-web.mjs手动拉取上游并更新子模块指针;GitHub Actions 每日定时同步,有更新时自动开同步 PR。
scripts/install-pi-plugins.sh 复现本机 pi 插件清单(22 个 npm 插件 + mattpocock skills):
bash scripts/install-pi-plugins.shapps/pi-web pi.dev 前端子模块(fork,含斜杠命令修复)
packages/
agent agent 运行时(工具调用、状态管理)
ai 统一多提供商 LLM API
coding-agent 交互式编码 agent CLI
gui 桌面图形界面(Electron,中文)
protocol / client 远程控制协议与客户端
server / storage 服务端与存储
tui 终端 UI 库
evals 评测
docs/ GUI 设计/规格/交付报告等文档
.pi/agents/ 专家团队 subagent 定义
.pi/skills/ expert-team 编排协议等技能
scripts/ 构建、发布、同步、插件安装等脚本
.github/workflows/ pi-web 自动同步等 CI
环境要求:Node.js >= 22.19
# 克隆(含子模块)
git clone --recurse-submodules https://github.com/ag-jin/pi-2k.git
cd pi-2k
# 安装依赖(不运行生命周期脚本)
npm install --ignore-scripts
# 启动 GUI 开发模式
npm run gui:dev
# 或构建并启动、打包 macOS 应用
npm run gui:start
npm run gui:package使用专家团队需要先满足用户级环境要求(@narumitw/pi-subagents 扩展与 ~/.pi/agent/pi-subagents.json 配置),详见 .pi/agents/README.md。
- AGENTS.md:仓库规则(人机通用)
- CONTEXT.md:GUI 术语表(中文)
- CONTRIBUTING.md:贡献指南
- SECURITY.md:安全说明
- docs/gui-design.md、docs/gui-spec.md:GUI 设计与规格
- 上游文档:pi.dev、earendil-works/pi
MIT,继承上游 earendil-works/pi。