# 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/user-guide/)。 ![一个运行 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 ``` [用户指南](./docs/user-guide/) 介绍其余安装方式——git、固定版本、 仅项目本地安装，以及不写入任何内容的试用——还有适用性判断、首个工作流和移除方式。 `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、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 个扩展、4 个随包技能，以及 2 个主题，按 [路线图](./ROADMAP.md) 追踪的承诺分组； [用户指南](./docs/user-guide/) 按章节讲述同样的内容。每个扩展在 `docs/extensions/` 下的页面提供完整的工具与命令说明，并以能力表开头。 ### 规划与委派 | 扩展 | 工具与命令 | 说明 | |---|---|---| | [`plan`](./docs/extensions/plan.md) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `~/.pi/agent/plans/` 下（每个仓库一份，各 worktree 共享），你在写入任何内容前先批准。可在 TUI 中审阅，或在浏览器中打开以留下行内评论：页面会跟随计划文件实时更新，你也可以给每位同事各一个审阅链接，各自以绑定的名义评论。`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`、`researcher`、`tester`、`debugger`、`documenter`），运行在它自己的 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) | `ask_user_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（peer 会话、另一个 worktree、另一个 Pi）依然有自己的端口。`bytefly.json` 里的 `serve.port` 可以固定该端口，收藏的地址在重启后依然有效；共享 review 只为发起共享的那一个页面借用同一个网段上的一个地址。 | | [`board`](./docs/extensions/board.md) | `board`、`/board` | 每个仓库一块共享看板：一张卡片代表一个 feature，任何 session 都可以认领、移动、编辑、加注、完成、归档——已完成的卡片会离开看板进入 `archive/`，其注记与落地 commit 仍可读，长历史不再拖累每次读取——同一个看板在浏览器里以 **Board** 和 **Team** 两个 tab 实时显示。页面只读——写入只走工具——并以固定席位 `team-lead` 对外服务，因此第二个 session 打开的是同一张页面，而不是另起一个；把卡片交给队友由 `team` 负责，因为只有它能给对端发消息。卡片可以带上优先级、声明自己在等待哪几张卡片。步骤留在 owner 的 plan 和 `todo` 里，卡片就是 feature、它的 owner，以及解释它的历史。页面以 `/board` 挂在该 session 唯一的端口上，所以收藏时用 `serve.port`。 | | [`team`](./docs/extensions/team.md) | `team`、`/team` | 同一块看板上的 lead 轮次。`/team join