@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/README.md

@@ -3,13 +3,13 @@
 **English** · [简体中文](./README.zh-CN.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)
 
-Plan before you act, delegate the work, keep the main checkout clean, and carry
-context across sessions. `my-pi-agent` is a single [Pi](https://pi.dev) package
-that adds sixteen extensions and two themes — install the pack, turn off what
-you do not want, and keep using Pi unchanged.
+`my-pi-agent` is a single [Pi](https://pi.dev) package that adds a curated set
+of extensions and themes to the agent you already use — install the pack, turn
+off what you do not want, and keep using Pi unchanged.
 
 ![A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar](assets/chrome.png)
 
@@ -20,7 +20,6 @@ you do not want, and keep using Pi unchanged.
 - [What you get](#what-you-get)
 - [Configuration](#configuration)
 - [Documentation](#documentation)
-- [Requirements](#requirements)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -52,28 +51,40 @@ Requires a working [Pi](https://pi.dev) installation.
 ```bash
 pi install npm:@gavin-hu/my-pi-agent                       # install from npm
 pi install git:github.com/gavin-hu/my-pi-agent             # install from git
-pi install git:github.com/gavin-hu/my-pi-agent@v0.8.0      # pin a release
+pi install git:github.com/gavin-hu/my-pi-agent@v0.13.0     # pin a release
 pi install ./ -l                                           # project-local (.pi/settings.json)
 pi -e .                                                    # try it for one run
 ```
 
+`git` on `PATH` is needed by [`worktree`](./extensions/worktree/) and
+[`rewind`](./extensions/rewind/); everything else degrades or disables cleanly,
+and `/bytefly doctor` names what is missing, including optional runtime pieces.
+Windows, macOS, and Linux all work, and the full check suite runs on each in CI.
+
 Then, from inside Pi:
 
 - `/bytefly [extension] [refresh]` opens the control center on Extensions, lists
-  every loaded extension with its runtime health, and enables or disables one.
+  every loaded extension with its runtime health, enables or disables one, and
+  clears a project override with `x`.
 - `/bytefly settings` opens the control center's Settings section: bytefly
-  startup TUI, desktop notifications, the transcript rail glyph, output padding,
-  and the hardware cursor, with `Space`/`Enter` to change a value and `Tab` for
-  Global/Project scope.
+  startup TUI, desktop notifications and their delivery method, the proactive
+  health check, the currency and cost precision, the transcript
+  rail glyph, output padding, and the hardware cursor, with `Space`/`Enter` to
+  change a value and `Tab` for Global/Project scope.
 - `/bytefly doctor [extension] [refresh]` prints the doctor report —
   `run_doctor`'s text — and checks that each enabled extension has what it needs
   at runtime.
 - `/settings` → **Theme** selects a theme.
 - `/plan <task>` starts a task in read-only planning mode.
 
+One thing the pack does on its own: once per interactive session, `bytefly` asks
+npm for the newest published version and marks the header when yours is older.
+Nothing about the session is sent, and `PI_OFFLINE` skips the request;
+[`docs/security.md`](./docs/security.md) covers the trust boundaries.
+
 ## What you get
 
-Sixteen extensions and two themes, grouped by what you are trying to do. Each
+Sixteen extensions, grouped by what you are trying to do, plus two themes. Each
 extension's own `README.md` has the full tool and command surface.
 
 ### Plan and delegate
@@ -110,8 +121,16 @@ extension's own `README.md` has the full tool and command surface.
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor` and `settings` subcommands), `run_doctor` | A themed header and width-adaptive footer, a two-row `You` nameplate on each user message, a rule between completed turns, a shared transcript notice, a tool block that leads with its call line and rails its result body two columns under it (the rail glyph is the `chrome.rail` setting), a live elapsed counter on Pi's working row, the `/bytefly` control center — an Extensions section that lists every extension with its health and enables or disables one, plus a Settings section with five curated preferences (`/bytefly settings`) — `/bytefly doctor` prints the doctor report, and an opt-in `notify` capability that raises OS notifications when a run or a background job finishes or the agent asks for input. DeepSeek is priced out of the box, and `bytefly.json` is the shared config document every extension reads. |
-| [`bytefly-dark`](./themes/bytefly-dark.json) / [`bytefly-light`](./themes/bytefly-light.json) | `/settings` → **Theme** | A GitHub-inspired dark palette and its light companion, with optional automatic light/dark switching. |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor` and `settings` subcommands), `run_doctor` | The visible layer: a themed header with a width-adaptive footer, a live elapsed counter on Pi's working row, and a transcript where every tool block leads with its call line and rails its result under it. `/bytefly` switches extensions and holds the curated settings; opt-in `notify` raises OS notifications when a run, a job, or a question needs you. `bytefly.json` is the config document every extension reads. |
+
+### Themes
+
+[`bytefly-dark`](./themes/bytefly-dark.json) is a GitHub-inspired dark palette
+and [`bytefly-light`](./themes/bytefly-light.json) its light companion, with
+optional automatic light/dark switching. Installing the pack does not change
+your theme: pick one through `/settings` → **Theme**, or set
+`"theme": "bytefly-light/bytefly-dark"` for switching. The screenshots in this
+README use `bytefly-dark`.
 
 ### Screens
 
@@ -144,9 +163,10 @@ one image per tool under [`assets/tools/`](./assets/tools).
 Most extensions need no configuration. Every setting lives in one shared
 document, `bytefly.json`, read from `<agent-dir>/bytefly.json` and merged with
 `<cwd>/.pi/bytefly.json` (project wins), under a top-level section named for the
-extension. Each extension's `README.md` lists its keys,
-[`docs/configuration.md`](./docs/configuration.md) indexes them, and
-[`assets/bytefly.schema.json`](./assets/bytefly.schema.json) validates the file.
+extension. Each extension's `README.md` covers the behaviour around its keys,
+[`docs/configuration.md`](./docs/configuration.md) indexes the sections, and
+[`docs/references/bytefly-config.md`](./docs/references/bytefly-config.md) lists
+every key with its type, default, and bounds.
 
 Every extension is on by default. To load the pack without some of them, set
 `PI_DISABLED_EXTENSIONS` to a comma- or whitespace-separated list of extension
@@ -167,19 +187,11 @@ stops the factories from registering; to drop the whole package, use Pi's
 | [Getting started](./docs/getting-started.md) | Requirements, install options, verifying the load, themes. |
 | [Extensions](./docs/extensions.md) | The full catalog of every extension and theme. |
 | [Configuration](./docs/configuration.md) | Config-file resolution, the per-extension index, environment variables. |
+| [Configuration reference](./docs/references/bytefly-config.md) | Every `bytefly.json` section and key, with its type, default, and bounds. |
 | [Architecture](./docs/architecture.md) | How the package, its extensions, and `lib/` fit together. |
 | [Development](./docs/development.md) | Local setup, checks, tests, cross-platform notes, and the release process. |
 | [Security](./docs/security.md) | Trust boundaries for the loopback and remote surfaces. |
-
-## Requirements
-
-- **Pi** — a working installation; `my-pi-agent` is a package, not a fork.
-- **OS** — Windows, macOS, and Linux; the full check suite runs on all three in
-  CI.
-- **git** on `PATH` for the `worktree` and `rewind` extensions; everything else
-  degrades or disables cleanly, and `/bytefly doctor` tells you what is missing.
-- Optional runtime pieces (for example a browser for HTML exports) are reported
-  per extension by `/bytefly doctor`.
+| [Roadmap](./ROADMAP.md) | Where the pack is going, grouped by the README's promises, with the evidence behind each item. |
 
 ## Contributing
 

package/README.zh-CN.md

@@ -3,12 +3,12 @@
 [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。
+`my-pi-agent` 是一个 [Pi](https://pi.dev) 包，在你已经使用的智能体之上新增一组精选
+扩展和主题 —— 安装整个包，关掉你不需要的部分，其余照常使用 Pi。
 
 ![一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏](assets/chrome.png)
 
@@ -19,7 +19,6 @@
 - [包含内容](#包含内容)
 - [配置](#配置)
 - [文档](#文档)
-- [环境要求](#环境要求)
 - [参与贡献](#参与贡献)
 - [许可证](#许可证)
 
@@ -48,27 +47,36 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 ```bash
 pi install npm:@gavin-hu/my-pi-agent                       # 从 npm 安装
 pi install git:github.com/gavin-hu/my-pi-agent             # 从 git 安装
-pi install git:github.com/gavin-hu/my-pi-agent@v0.8.0      # 固定到某个版本
+pi install git:github.com/gavin-hu/my-pi-agent@v0.13.0     # 固定到某个版本
 pi install ./ -l                                           # 仅项目本地（.pi/settings.json）
 pi -e .                                                    # 试运行一次
 ```
 
+`git` 需在 `PATH` 上，供 [`worktree`](./extensions/worktree/) 与
+[`rewind`](./extensions/rewind/) 使用；其余部分会优雅降级或禁用，
+`/bytefly doctor` 会指出缺少什么，包括可选的运行时组件。
+Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都会执行。
+
 然后在 Pi 中：
 
 - `/bytefly [extension] [refresh]` 打开控制中心的 Extensions 区，列出每个已加载扩展
-  及其运行时健康状况，并启用或禁用一个扩展。
-- `/bytefly settings` 打开控制中心的 Settings 区：bytefly 启动 TUI、桌面通知、
-  转录轨道字形、输出内边距和硬件光标；用 `Space`/`Enter` 修改，用 `Tab` 切换
-  Global/Project 作用域。
+  及其运行时健康状况，启用或禁用一个扩展，并用 `x` 清除项目级覆盖。
+- `/bytefly settings` 打开控制中心的 Settings 区：bytefly 启动 TUI、桌面通知及其
+  投递方式、主动健康检查、货币与费用精度、转录轨道字形、输出内边距和硬件光标；
+  用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project 作用域。
 - `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本），
   检查每个已启用扩展在运行时是否具备所需条件。
 - `/settings` → **Theme** 选择主题。
 - `/plan <任务>` 以只读规划模式开始一个任务。
 
+还有一件包会自行做的事：每次交互式会话启动时，`bytefly` 向 npm 询问最新发布
+版本，当你的版本较旧时在头部标出。不会发送任何会话内容，`PI_OFFLINE` 可跳过
+该请求；信任边界见 [`docs/security.md`](./docs/security.md)。
+
 ## 包含内容
 
-十六个扩展和两个主题，按你想达成的目标分组。每个扩展自己的 `README.md` 提供完整的
-工具与命令说明。
+十六个扩展，按你想达成的目标分组，外加两个主题。每个扩展自己的 `README.md`
+提供完整的工具与命令说明。
 
 ### 规划与委派
 
@@ -104,8 +112,15 @@ pi -e .                                                    # 试运行一次
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor`、`settings` 子命令）、`run_doctor` | 主题化头部与宽度自适应页脚、每条用户消息上方的两行 `You` 铭牌、已完成回合之间的分隔线、共享的转录通知、以调用行为标题并将结果正文挂在轨道下两列的工具块（轨道字形由 `chrome.rail` 设置）、Pi 工作行上的实时用时计数、`/bytefly` 控制中心——Extensions 区列出每个扩展及其健康状况并启用或禁用一个扩展，另有一个 Settings 区，提供五项常用偏好（`/bytefly settings`）；`/bytefly doctor` 打印 doctor 报告；以及可选的 `notify` 能力：当一次运行或后台任务结束、或智能体请求输入时发出系统通知。DeepSeek 开箱即定价，`bytefly.json` 是每个扩展都会读取的共享配置文档。 |
-| [`bytefly-dark`](./themes/bytefly-dark.json) / [`bytefly-light`](./themes/bytefly-light.json) | `/settings` → **Theme** | GitHub 风格的深色调色板及其浅色搭档，并支持可选的自动浅色/深色切换。 |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor`、`settings` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展并集中存放精选设置；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知。`bytefly.json` 是每个扩展都会读取的配置文档。 |
+
+### 主题
+
+[`bytefly-dark`](./themes/bytefly-dark.json) 是 GitHub 风格的深色调色板，
+[`bytefly-light`](./themes/bytefly-light.json) 是其浅色搭档，并支持可选的自动
+浅色/深色切换。安装本包不会改变你的主题：通过 `/settings` → **Theme** 选择，
+或设置 `"theme": "bytefly-light/bytefly-dark"` 以自动切换。本 README 的截图
+使用 `bytefly-dark`。
 
 ### 截图
 
@@ -136,9 +151,10 @@ pi -e .                                                    # 试运行一次
 
 大多数扩展无需配置。所有设置都在一个共享文档 `bytefly.json` 中，从
 `<agent-dir>/bytefly.json` 读取，并与 `<cwd>/.pi/bytefly.json` 合并（项目优先），
-位于一个以扩展名命名的顶层 section 下。每个扩展的 `README.md` 列出它的键，
+位于一个以扩展名命名的顶层 section 下。每个扩展的 `README.md` 说明其键位的行为，
 [`docs/configuration.md`](./docs/configuration.md) 为其建立索引，
-[`assets/bytefly.schema.json`](./assets/bytefly.schema.json) 校验该文件。
+[`docs/references/bytefly-config.md`](./docs/references/bytefly-config.md) 逐个列出每个键的
+类型、默认值和取值范围。
 
 每个扩展默认都开启。若要在加载整包时排除其中一些，把 `PI_DISABLED_EXTENSIONS`
 设为一个以逗号或空白分隔的扩展名列表（即 [`extensions/`](./extensions/) 下的目录
@@ -158,17 +174,11 @@ Pi 的 `--no-extensions`，或从你的设置中删除该包。
 | [快速开始](./docs/getting-started.md) | 环境要求、安装选项、验证加载、主题。 |
 | [扩展](./docs/extensions.md) | 所有扩展与主题的完整目录。 |
 | [配置](./docs/configuration.md) | 配置文件解析、按扩展索引、环境变量。 |
+| [配置参考](./docs/references/bytefly-config.md) | 列出 `bytefly.json` 的每个 section 与键，包括类型、默认值和取值范围。 |
 | [架构](./docs/architecture.md) | 包、各扩展与 `lib/` 如何协同。 |
 | [开发](./docs/development.md) | 本地设置、检查、测试、跨平台注意事项与发布流程。 |
 | [安全](./docs/security.md) | 回环与远程界面的信任边界。 |
-
-## 环境要求
-
-- **Pi** —— 需要一个可用的安装；`my-pi-agent` 是一个包，不是分叉。
-- **操作系统** —— Windows、macOS 和 Linux；完整检查套件在三者的 CI 上都会运行。
-- **git** 需在 `PATH` 上，供 `worktree` 和 `rewind` 扩展使用；其余部分会优雅降级或
-  禁用，`/bytefly doctor` 会告诉你缺什么。
-- 可选的运行时组件（例如用于 HTML 导出的浏览器）由 `/bytefly doctor` 按扩展报告。
+| [路线图](./ROADMAP.md) | 包的下一步方向，按 README 的承诺分组，并列出每条事项的依据。 |
 
 ## 参与贡献