# my-pi-agent [English](./README.md) · **简体中文** [![CI](https://github.com/gavin-hu/my-pi-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/gavin-hu/my-pi-agent/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/%40gavin-hu%2Fmy-pi-agent)](https://www.npmjs.com/package/@gavin-hu/my-pi-agent) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![built for Pi](https://img.shields.io/badge/built%20for-Pi-5A4FCF)](https://pi.dev) `my-pi-agent` 是一个 [Pi](https://pi.dev) 包，在你已经使用的智能体之上新增一组精选 扩展、技能和主题 —— 安装整个包，关掉你不需要的部分，其余照常使用 Pi。 本页是目录与安装说明。每个功能在 [`docs/extensions/`](./docs/extensions/) 下都有自己的页面， 写清按键、命令以及应有的效果。 ![一个运行 Pi TUI 的终端窗口：bytefly 头部标出 Pi 与 bytefly 的版本、三行按键提示、带名板的消息及其回答与编辑差异（位于竖线内）、两个后台任务完成的通知（一个通过的测试任务与一个失败的构建任务）、回合分隔线、目标与待办栏、夹在两条横线之间且已输入半句的输入框，以及两行页脚（上下文指示、按价目计算的费用、模型名）](assets/screens/chrome.png) ## 目录 - [为什么选择这个包](#为什么选择这个包) - [快速开始](#快速开始) - [包含内容](#包含内容) - [配置](#配置) - [文档](#文档) - [参与贡献](#参与贡献) - [许可证](#许可证) ## 为什么选择这个包 Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，面向希望智能体*先思考、 再安全行动*的人： - **先规划，再执行。** 只读的规划模式把一次任务变成一份可审阅的计划文件，智能体 随后按步骤执行。 - **委派与并行。** 在各自的 Pi 进程中运行专职子智能体，把耗时构建交给后台任务， 让 watcher 盯住日志直到出现关键行，还能让同一仓库上的多个会话通过共享总线协作、 各自负责自己的一摊 —— 你继续把握主线。 - **绝不搞乱检出区。** 隔离只需一条命令：任务切到自己分支的 `git worktree` 中， 每次提示的首次改动都会生成快照，因此一次糟糕的回合只需一个 `/rewind` 就能回退。 - **跨会话记忆。** 持久笔记以纯 Markdown 保存，可读、可改、可纳入版本控制。 - **连通网络与文件。** 在会话内搜索、抓取、浏览、打开和读取文档与表格，还可通过桥接 在微信里直接回答当前会话。 一切都是可选的，且可独立开关。没有任何东西被分叉，也没有写入任何已安装的 Pi 文件： Pi 通过 [`package.json`](./package.json) 里的 `pi` manifest 发现这些资源，因此 该包能像其他包一样随 Pi 一起升级。 ## 快速开始 需要一个可用的 [Pi](https://pi.dev) 安装。 ```bash pi install npm:@gavin-hu/my-pi-agent # 最新发布版 pi install git:github.com/gavin-hu/my-pi-agent@v0.24.0 # 固定版本 ``` `git` 需在 `PATH` 上，供 [`worktree`](./docs/extensions/worktree.md) 与 [`rewind`](./docs/extensions/rewind.md) 使用；其余部分会优雅降级或禁用， `/bytefly doctor` 会指出缺少什么，包括可选的运行时组件。 Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都会执行。 然后在 Pi 中： - `/bytefly [extension] [refresh]` 打开控制中心的 Extensions 区：三个区共用一个 框架，头部横线的右端写着需要注意的事项（没有问题时为 `all clear`），一行 tab 标出各区的数量与写入作用域。它按名称列出每个已加载扩展及其复选框与至多一个 结论词，启用或禁用一个扩展，并用 `x` 清除项目级覆盖；`/` 过滤行，`!` 只保留 需要注意的行，`?` 显示全部按键。 - `/bytefly settings` 打开控制中心的 Settings 区：一次会话会改动的十五项设置按 Startup、Notifications、Session、Board、Price 五组排列，值对齐在同一列；用 `Space`/`Enter` 修改一项，用 `s` 切换 Global/Project 作用域。其余键都是 `bytefly.json` 编辑，见配置参考。 - `/bytefly skills` 打开控制中心的 Skills 区：每个 Pi 技能一行，带启用复选框与 至多一个结论词，`SKILL.md` 声明的描述显示在旁边的区块中，用 `Space` 在当前 作用域开关它。 - `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本）， 检查每个已启用扩展在运行时是否具备所需条件。 - `/bytefly update` 立即重跑包更新检查，报告可更新的包、本包版本与 release URL， 或跳过原因。 - `/plan <任务>` 以只读规划模式开始一个任务。 - `/skill:init` 通过内置的简短访谈和先审阅的计划创建或更新 Pi 实际读取的指令文件。 还有一件包会自行做的事：每次交互式会话启动时，`bytefly` 询问 Pi 的包管理器 哪些已配置的包有更新，抑制 Pi 自己的启动更新块，并用主题化 notice 列出它们 和 `pi update --extensions`；Pi 自身的新版本也由它绘制，提示 `pi update` 与 changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不会发送任何会话内容： Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自一次固定的 npm `latest` 请求，`PI_OFFLINE` 可跳过检查；信任边界见 [`docs/security.md`](./docs/security.md)。 ## 包含内容 22 个扩展、3 个随包技能，以及 2 个主题，按本 README 的承诺分组。 每个扩展在 `docs/extensions/` 下的页面提供完整的工具与命令说明，并以能力表开头。 ### 规划与委派 | 扩展 | 工具与命令 | 说明 | |---|---|---| | [`plan`](./docs/extensions/plan.md) | `plan`, `/plan`, `--plan` | 只读规划：一个工具的五个动作 —— `enter`、`write`、`exit`、`steps`、`cancel`。模型先调研，把计划保存到 `~/.pi/agent/plans/` 下（每个仓库一份，各 worktree 共享），你在写入任何内容前先批准。可在 TUI 中审阅，也可在浏览器里留下行内评论：页面跟随计划文件实时更新，穿着与 `/board`、`/browse` 相同的工具栏、控制栏和页脚，侧栏则按角色给事实 —— owner 看到决策说明与步骤进度，审阅者看到自己的署名与评论数 —— 每位同事各持一个审阅链接，以自己的名义评论。`init` 技能复用同一审阅流程来创建或更新项目的 `AGENTS.md`。 | | [`check`](./docs/extensions/check.md) | `run_check`, `/check` | 检测项目的测试、lint 或类型检查命令（或使用 `check.command`），在受监管的进程中运行，并把失败整理成可导航的 `file:line` 列表。 | | [`subagent`](./docs/extensions/subagent.md) | `subagent`, `/agents` | 把任务委派给专职智能体（`explorer`、`planner`、`reviewer`、`worker`），运行在它自己的 Pi 进程中 —— 单个、并行、链式或在后台运行；后台运行时在页脚显示数量，完成后发出提示。 | | [`todo`](./docs/extensions/todo.md) | `todo`, `/todos` | 持久任务列表（`pending` / `in_progress` / `completed`），配一行式 widget。 | | [`goal`](./docs/extensions/goal.md) | `goal`, `/goal` | 持久会话目标，保存在 widget 中，并在每个回合前重述。 | | [`question`](./docs/extensions/question.md) | `question` | 向你提出一个或多个结构化问题（带标签的选项外加自由填写的“其他”）并等待回答。 | | [`job`](./docs/extensions/job.md) | `job`, `/jobs` | 在后台运行长时 shell 命令；查看日志、等待或结束它们。 | | [`watch`](./docs/extensions/watch.md) | `watch`, `/watch` | 跟踪文件或命令输出，按模式匹配行，并提醒你或把匹配的行交给智能体。 | | [`session-bus`](./docs/extensions/session-bus.md) | `session`, `/sessions`（屏幕） | 在同一仓库的多个 Pi 会话之间协调：发现彼此、交换简短消息/事件、读取收件箱、编辑前声明路径；`/sessions` 是显示对等会话、未读邮件和路径声明的实时面板。本地、默认拉取式；收件箱监视需会话自行开启，空闲时会唤起本会话的一轮，从不创建智能体。 | | [`serve`](./docs/extensions/serve.md) | — | 每个 session 一个 loopback 服务：`/board`、`/browse` 和浏览器里的 plan review 都在它上面挂载路径前缀，而不是各自监听端口，因此一个 session 只有一个端口、一个 chip、一条关闭路径 —— 而第二个 session 依然有自己的端口。端口是项目自身的编号，由仓库 key 哈希到 `4780`–`5779`，因此收藏的地址在重启后依然有效；`bytefly.json` 里的 `serve.port` 可以覆盖它；共享 review 只为发起共享的那一个页面借用同一个网段上的一个地址。 | | [`board`](./docs/extensions/board.md) | `board`、`/board` | 每个仓库一块共享看板：一张卡片代表一个 feature —— 它的 owner、优先级、在等哪几张卡片，以及解释它的历史 —— 在 `backlog`、`plan`、`execute`、`blocked`、`done` 五条车道间移动。契约（`goal`、`acceptance`、`scopeOut`）写明本仓库 plan store 里的一份 plan，由 lead（`bytefly.json` 里的 `board.lead`，默认 `lead`，且不能是卡片持有者）或本人用 `/board approve` 签名之后，卡片才能进入执行；收尾要经过 `/board review` 抽检 —— 绕过闸门的收尾则用 `/board review --override ` 事后补签，记录上会写 `closed by instruction` —— `plan` 与 `execute` 受 WIP 上限约束，签名会通知卡片的 owner。已完成的卡片进入 `archive/`，其注记与落地 commit 仍可读。同一个看板在 `/board` 的页面上以 **Board** 与 **Team** 两个 tab 实时显示，只读 —— 写入只走工具 —— 以看板 lead 的席位对外服务，因此第二个 session 打开的是同一张页面；Team tab 会把 bus 没有记录的 owner 收成一行。步骤留在 owner 的 plan 和 `todo` 里。默认关闭：用 `PI_ENABLED_EXTENSIONS=board` 加载。 | | [`team`](./docs/extensions/team.md) | `team`、`/team` | 同一块看板上的 lead 轮次：`/team join