@gavin-hu/my-pi-agent

中文文档
0.27.0发布于 2026/11/14MITES Module构建来源已验证近 30 天下载 7809

个人 Pi 定制,被包装为 Pi 包: 工作树隔离并倒带快照, 问, 待办, 目标, 计划, 服务, 子代理, 工作, 手表, 网络访问, 文件浏览, 文件打开, 文件读取, 内存, 上下文, 会话布克, 板, 团队, wechat, 和 b

中文使用文档
文档目录15 节
  1. 目录
  2. 为什么选择这个包
  3. 安装
  4. 包含内容
  5. 规划与委派
  6. 保护你的工作
  7. 连通外部世界
  8. 界面与维护
  9. 技能
  10. 主题
  11. 包会自行做的事
  12. 配置
  13. 文档
  14. 参与贡献
  15. 许可证

my-pi-agent

English · 简体中文

CI npm license: MIT built for Pi

my-pi-agent 是一个 Pi 包,在你已经使用的智能体之上新增一组精选 扩展、技能和主题 —— 安装整个包,关掉你不需要的部分,其余照常使用 Pi。

本页是目录与安装说明。每个功能在 docs/extensions/ 下都有自己的页面, 写清按键、命令以及应有的效果。

一个运行 Pi TUI 的终端窗口:bytefly 头部标出 Pi 与 bytefly 的版本、三行按键提示、带名板的消息及其回答与编辑差异(位于竖线内)、两个后台任务完成的通知(一个通过的测试任务与一个失败的构建任务)、回合分隔线、目标与待办栏、夹在两条横线之间且已输入半句的输入框,以及两行页脚(上下文指示、按价目计算的费用、模型名)

目录

为什么选择这个包

Pi 提供一个精简而锐利的内核。这个包是在其之上的一层,面向希望智能体先思考、 再安全行动的人:

  • 先规划,再执行。 只读模式把一次任务变成一份可审阅的计划文件,智能体随后 按步骤执行。
  • 委派与并行。 专职子智能体运行在各自的 Pi 进程里,耗时构建交给后台任务, 同一仓库上的多个会话通过共享总线协作。
  • 绝不搞乱检出区。 隔离只需一条命令:任务切到自己分支的 git worktree 中, 每次提示的首次改动都会生成快照,因此一次糟糕的回合只需一个 /rewind 就能回退。
  • 跨会话记忆。 持久笔记以纯 Markdown 保存,可读、可改、可纳入版本控制。
  • 连通网络与文件。 在会话内搜索、抓取、浏览、打开和读取文档与表格,还可通过桥接 在微信里直接回答当前会话。

安装

需要一个可用的 Pi 安装。

pi install npm:@gavin-hu/my-pi-agent                        # 最新发布版
pi install git:github.com/gavin-hu/[email protected]      # 固定版本

git 需在 PATH 上,供 worktree 与 rewind 使用;其余部分会优雅降级或禁用, /bytefly doctor 会指出缺少什么,包括可选的运行时组件。 Windows、macOS 和 Linux 均可运行,完整检查套件在每个平台上都会执行。

一切都是可选的,且可独立开关。没有任何东西被分叉,也没有写入任何已安装的 Pi 文件: Pi 通过 package.json 里的 pi manifest 发现这些资源,因此 该包能像其他包一样随 Pi 一起升级。

然后在 Pi 中:

  • /bytefly 打开控制中心:一次会话会改动的十六项设置、每个已加载的扩展与技能及其 复选框,以及指出运行时缺项的 doctor 报告。
  • /plan <任务> 以只读规划模式开始一个任务。
  • /skill:init 通过内置的简短访谈和先审阅的计划,创建或更新 Pi 实际读取的指令文件。

包含内容

21 个扩展、3 个随包技能,以及 2 个主题,按它们所服务的工作分组。 每个扩展在 docs/extensions/ 下的页面提供完整的工具与命令说明,并以能力表开头。

规划与委派

扩展工具与命令说明
planplan, /plan, --plan只读规划:模型先调研,计划经你批准后才写入任何内容。
subagentsubagent, /agents把任务委派给运行在自己 Pi 进程中的专职智能体 —— 单个、并行、链式或在后台。
todotodo, /todos持久任务列表,同一时刻一项进行中,以一行式 widget 显示。
goalgoal, /goal持久会话目标,保存在 widget 中,并在每个回合前重述。
questionquestion向你提出带标签选项的结构化问题,并等待回答。
jobjob, /jobs在后台运行长时 shell 命令;查看日志、等待或结束它们。
watchwatch, /watch跟踪文件或命令输出,匹配到行时提醒你,或把该行交给智能体。
session-bussession, /sessions(屏幕)协调同一仓库上的并行会话:对等会话、简短消息、收件箱与路径声明。
serve—本会话唯一的 loopback 服务,/board、/browse 与 plan review 共用一个端口。
boardboard、/board每个仓库一块共享看板,卡片发运前需要两次签名。
teamteam、/team看板上的 lead 轮次:assign、offer、reclaim、claim、ask —— 不启动任何进程。
context/context显示上下文窗口的去向,并从报告中触发压缩。

保护你的工作

扩展工具与命令说明
worktreeworktree, /worktree (screen), /worktree enter|exit|prune, --worktree在隔离的 git worktree 里、在独立分支上工作;内置工具会跟随。
rewind/rewind, ↺ N 状态标记在每次提示的首次改动前生成快照,可恢复代码、对话或两者。
memorymemory, /memory跨会话的持久笔记,以可读、可改、可纳入版本控制的 Markdown 保存。

连通外部世界

扩展工具与命令说明
web-accessweb_search, web_fetch搜索网络并把页面抓取为可读文本,支持分页、find 与 SSRF 检查。
file-browse/browse以工作目录为根的回环只读浏览器,带 Markdown 预览与快速打开。
file-readread_doc在进程内从本地 PDF、DOCX、DOC、ODT、RTF 或 XLSX 提取文本,支持分页。
file-open/open, open_path用操作系统原生应用打开或定位文件/目录。
wechat/wechat, send_wechat把一段微信聊天桥接到实时会话:入站消息进入,回答流式返回。

界面与维护

扩展工具与命令说明
bytefly/bytefly(doctor、settings、skills、update、upgrade 子命令)、run_doctor可见的那一层:头部、页脚、转录块、设置界面、通知 —— 以及每个扩展都会读取的配置 bytefly.json。

技能

按需加载的随包工作流:每个技能的名称和描述会提供给模型,只有任务匹配时才加载完整说明(/skill:<name> 可强制加载)。

技能说明
init通过交互式访谈与先审阅的计划,创建或更新 Pi 实际读取的指令文件。
refactor审计重复代码、过大模块、耦合与结构漂移,并把你选定的重构带到完成。
next从本次会话建议接下来做什么;会话为空时则基于代码树。

主题

bytefly-dark 是 GitHub 风格的深色调色板, bytefly-light 是其浅色搭档,并支持可选的自动 浅色/深色切换。安装本包不会改变你的主题:通过 /settings → Theme(或 /bytefly settings → Theme)选择, 或在 Pi 的 settings.json 中把 "theme" 设为 "bytefly-light/bytefly-dark" 以自动切换。上方的截图 使用 bytefly-dark。

截图来自 assets/screens/,各扩展位于 docs/extensions/ 下的页面在需要展示其效果时使用它们。 工具是一张画廊图 assets/screens/tool-renderings.png: bun run capture:tools 重新生成它,bun run capture:tool-pngs 则把每个工具一张的 PNG 写入 assets/tools/。

包会自行做的事

每次交互式会话启动时,bytefly 询问 Pi 的包管理器哪些已配置的包有更新,并用主题化 notice 提示 pi update --extensions;Pi 自身的新版本则提示 pi update。不会发送 任何会话内容,PI_OFFLINE 可跳过检查 —— bytefly 页面 说明头部的版本标记与缓存, docs/security.md 说明信任边界。

配置

大多数扩展无需配置。所有扩展设置都在一个共享文档 bytefly.json 中,从 <agent-dir>/bytefly.json 读取,并与 <cwd>/.pi/bytefly.json 合并(项目优先), 位于一个以扩展名命名的顶层 section 下。每个扩展在 docs/extensions/ 下的页面说明其键位的行为, docs/configuration.md 则给出解析规则、设置界面操作方式, 以及每个 section 的键、类型、默认值和取值范围。

所有扩展默认都开启。若要在加载整包时排除一些扩展,在 PI_DISABLED_EXTENSIONS 中列出它们的名字(即 extensions/ 下的目录名):

PI_DISABLED_EXTENSIONS=todo,job pi -e .

该变量只会阻止这些工厂注册,具体规则见 配置;若要移除整包,请使用 Pi 的 --no-extensions,或从你的设置中删除该包。

文档

指南内容
文档站点浏览器版本:首页、安装与配置,以及覆盖每个扩展页面的侧边栏。
安装添加本包、固定版本、升级与移除。
配置解析规则与设置界面;configuration-reference.md 列出 bytefly.json 每个键的默认值与取值范围。
扩展文档每个扩展一页:它做什么、如何上手,以及参考部分;每个工作流各配一篇教程。
工具与命令本包注册的每个工具、斜杠命令与界面,按名称列出,并指向拥有它的页面。
安全回环与远程界面的信任边界。
参与贡献本地设置、分支流程、检查项与发布流程。

参与贡献

欢迎贡献。请先阅读 CONTRIBUTING.md,了解设置、worktree 分支流程以及改动必须通过的检查。AI 编码智能体应阅读 AGENTS.md。

许可证

MIT

版本与发布记录

@gavin-hu/my-pi-agent 共发布 30 个版本,首次发布于 2026/10/15;过去 12 个月发布了 30 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.27.0latest2026/11/141 天前
0.26.02026/11/114 天前
0.25.12026/11/079 天前
0.25.02026/11/069 天前
0.24.02026/11/0213 天前
0.23.02026/10/3115 天前

关于 @gavin-hu/my-pi-agent 的常见问题

@gavin-hu/my-pi-agent 是什么?

个人 Pi 定制,被包装为 Pi 包: 工作树隔离并倒带快照, 问, 待办, 目标, 计划, 服务, 子代理, 工作, 手表, 网络访问, 文件浏览, 文件打开, 文件读取, 内存, 上下文, 会话布克, 板, 团队, wechat, 和 b

如何安装 @gavin-hu/my-pi-agent?

在项目目录运行 npm install @gavin-hu/my-pi-agent,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:typebox(*)、@earendil-works/pi-ai(*)、@earendil-works/pi-tui(*)、@earendil-works/pi-agent-core(*)、@earendil-works/pi-coding-agent(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gavin-hu/my-pi-agent 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gavin-hu__my-pi-agent 是否存在。

@gavin-hu/my-pi-agent 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gavin-hu/my-pi-agent 可以商用吗?

@gavin-hu/my-pi-agent 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gavin-hu/my-pi-agent 的下载量有多少?

根据 npm 官方下载统计,@gavin-hu/my-pi-agent 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,809 次,日均约 260 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gavin-hu/my-pi-agent 还在维护吗?

最新版本 0.27.0 发布于 2026/11/14(1 天前);至今共发布 30 个版本,其中过去 12 个月发布了 30 个;首次发布于 2026/10/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。