@gavin-hu/my-pi-agent 0.8.1 → 0.10.0

package/README.md

@@ -11,7 +11,7 @@ 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.
 
-![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/bytefly-chrome.png)
+![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)
 
 ## Contents
 
@@ -59,10 +59,11 @@ pi -e .                                                    # try it for one run
 
 Then, from inside Pi:
 
-- `/extensions` (an alias of `/bytefly`) lists every loaded extension with its
-  runtime health and enables or disables one.
-- `/doctor` opens the same screen, narrowed to one extension when named, and
-  checks that each enabled extension has what it needs at runtime.
+- `/bytefly [extension] [refresh]` opens the extension screen, lists every loaded
+  extension with its runtime health, and enables or disables one.
+- `/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.
 
@@ -105,9 +106,35 @@ extension's own `README.md` has the full tool and command surface.
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`, `/extensions`, `/doctor`, `run_doctor` | A themed header and width-adaptive footer, a rule between completed turns, the `/bytefly` extension screen (aliases `/extensions` and `/doctor`) that lists every extension with its health and enables or disables one, 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`](./extensions/bytefly/) | `/bytefly` (with the `doctor` subcommand), `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` extension screen that lists every extension with its health and enables or disables one (`/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. |
 
+### Screens
+
+<table>
+<tr>
+<td width="50%"><img src="assets/todo.png" alt="The /todos screen: a Todos title rule, a 3/7 completed summary, and the list with check, spinner, and circle glyphs" width="100%"></td>
+<td width="50%"><img src="assets/question.png" alt="The ask_user_question dialog: Auth and Scope tabs, a question, four numbered options with descriptions, and the navigation hint" width="100%"></td>
+</tr>
+<tr>
+<td width="50%"><img src="assets/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%"></td>
+<td width="50%"><img src="assets/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and the focused prompt's snapshot detail" width="100%"></td>
+</tr>
+</table>
+
+### Tool renderings
+
+Every tool block as the transcript draws it — the tool's own call line as the
+headline, then the result body two columns under it behind the transcript rail —
+each tool's own renderer (or bytefly's generic fallback): the user nameplate and
+a notice, Pi's built-ins, and every tool this package registers. The rail glyph
+is the `chrome.rail` setting.
+
+![A full-page reference of every tool block: the user nameplate, a notice, the turn rule, Pi's read, write, edit, bash, grep, find, and ls renderers, and every package tool — todo, goal, memory, job, watch, subagent, web_search, web_fetch, read_doc, open_path, run_doctor, send_wechat, ask_user_question, the plan tools, and the worktree tools](assets/tool-renderings.png)
+
+`bun run screenshot:tools` regenerates it; `bun run screenshot:tool-pngs` writes
+one image per tool under [`assets/tools/`](./assets/tools).
+
 ## Configuration
 
 Most extensions need no configuration. Every setting lives in one shared
@@ -146,9 +173,9 @@ stops the factories from registering; to drop the whole package, use Pi's
 - **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 `/doctor` tells you what is missing.
+  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 `/doctor`.
+  per extension by `/bytefly doctor`.
 
 ## Contributing
 

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 `my-pi-agent` 是一个 [Pi](https://pi.dev) 包，新增十六个扩展和两个主题 —— 安装
 整个包，关掉你不需要的部分，其余照常使用 Pi。
 
-![一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏](assets/bytefly-chrome.png)
+![一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏](assets/chrome.png)
 
 ## 目录
 
@@ -55,10 +55,10 @@ pi -e .                                                    # 试运行一次
 
 然后在 Pi 中：
 
-- `/extensions`（`/bytefly` 的别名）列出每个已加载扩展及其运行时健康状况，并启用
-  或禁用一个扩展。
-- `/doctor` 打开同一屏幕，指定扩展名时只显示该扩展，并检查每个已启用扩展在运行时
-  是否具备所需条件。
+- `/bytefly [extension] [refresh]` 打开扩展屏幕，列出每个已加载扩展及其运行时健康
+  状况，并启用或禁用一个扩展。
+- `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本），
+  检查每个已启用扩展在运行时是否具备所需条件。
 - `/settings` → **Theme** 选择主题。
 - `/plan <任务>` 以只读规划模式开始一个任务。
 
@@ -101,9 +101,34 @@ pi -e .                                                    # 试运行一次
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`, `/extensions`, `/doctor`, `run_doctor` | 主题化头部与宽度自适应页脚、已完成回合之间的分隔线、`/bytefly` 扩展屏幕（别名 `/extensions` 和 `/doctor`）——列出每个扩展及其健康状况并启用或禁用一个扩展；以及可选的 `notify` 能力：当一次运行或后台任务结束、或智能体请求输入时发出系统通知。DeepSeek 开箱即定价，`bytefly.json` 是每个扩展都会读取的共享配置文档。 |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor` 子命令）、`run_doctor` | 主题化头部与宽度自适应页脚、每条用户消息上方的两行 `You` 铭牌、已完成回合之间的分隔线、共享的转录通知、以调用行为标题并将结果正文挂在轨道下两列的工具块（轨道字形由 `chrome.rail` 设置）、Pi 工作行上的实时用时计数、`/bytefly` 扩展屏幕——列出每个扩展及其健康状况并启用或禁用一个扩展（`/bytefly doctor` 打印 doctor 报告）；以及可选的 `notify` 能力：当一次运行或后台任务结束、或智能体请求输入时发出系统通知。DeepSeek 开箱即定价，`bytefly.json` 是每个扩展都会读取的共享配置文档。 |
 | [`bytefly-dark`](./themes/bytefly-dark.json) / [`bytefly-light`](./themes/bytefly-light.json) | `/settings` → **Theme** | GitHub 风格的深色调色板及其浅色搭档，并支持可选的自动浅色/深色切换。 |
 
+### 截图
+
+<table>
+<tr>
+<td width="50%"><img src="assets/todo.png" alt="/todos 屏幕：Todos 标题线、3/7 完成摘要，以及带对勾、进行中和圆圈字形的列表" width="100%"></td>
+<td width="50%"><img src="assets/question.png" alt="ask_user_question 对话框：Auth 与 Scope 标签页、问题、四个带说明的编号选项，以及导航提示" width="100%"></td>
+</tr>
+<tr>
+<td width="50%"><img src="assets/job.png" alt="/jobs 屏幕：摘要行、带状态字形和耗时的任务行，以及焦点任务的命令、工作目录和最后一行输出" width="100%"></td>
+<td width="50%"><img src="assets/rewind.png" alt="/rewind 屏幕：从新到旧的提示行、标记有代码快照的菱形，以及焦点提示的快照详情" width="100%"></td>
+</tr>
+</table>
+
+### 工具渲染
+
+每个工具块都按转录中的样子绘制：工具自身的调用行作为标题，结果正文在其下方两列、
+由转录侧栏（rail）引出
+（每个工具自身的渲染器或 bytefly 的通用回退）——用户铭牌与通知、Pi 内置工具，以及本包注册的每个工具。
+侧栏字形由 `chrome.rail` 设置。
+
+![每个工具块的全页参考图：用户铭牌、通知、回合分隔线，Pi 的 read、write、edit、bash、grep、find、ls 渲染器，以及每个包内工具——todo、goal、memory、job、watch、subagent、web_search、web_fetch、read_doc、open_path、run_doctor、send_wechat、ask_user_question、plan 工具与 worktree 工具](assets/tool-renderings.png)
+
+`bun run screenshot:tools` 重新生成它；`bun run screenshot:tool-pngs` 在
+[`assets/tools/`](./assets/tools) 下为每个工具输出一张图。
+
 ## 配置
 
 大多数扩展无需配置。所有设置都在一个共享文档 `bytefly.json` 中，从
@@ -139,8 +164,8 @@ Pi 的 `--no-extensions`，或从你的设置中删除该包。
 - **Pi** —— 需要一个可用的安装；`my-pi-agent` 是一个包，不是分叉。
 - **操作系统** —— Windows、macOS 和 Linux；完整检查套件在三者的 CI 上都会运行。
 - **git** 需在 `PATH` 上，供 `worktree` 和 `rewind` 扩展使用；其余部分会优雅降级或
-  禁用，`/doctor` 会告诉你缺什么。
-- 可选的运行时组件（例如用于 HTML 导出的浏览器）由 `/doctor` 按扩展报告。
+  禁用，`/bytefly doctor` 会告诉你缺什么。
+- 可选的运行时组件（例如用于 HTML 导出的浏览器）由 `/bytefly doctor` 按扩展报告。
 
 ## 参与贡献
 

package/assets/bytefly.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/gavin-hu/my-pi-agent/main/assets/bytefly.schema.json",
   "title": "bytefly shared extension config",
-  "description": "One document, one top-level section per extension (bytefly owns price, notify, and doctor). Resolution is low to high: built-in defaults, <agent-dir>/bytefly.json, then <cwd>/.pi/bytefly.json (project wins). Unknown keys are ignored.",
+  "description": "One document, one top-level section per extension (bytefly owns price, notify, doctor, and chrome). Resolution is low to high: built-in defaults, <agent-dir>/bytefly.json, then <cwd>/.pi/bytefly.json (project wins). Unknown keys are ignored.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -25,6 +25,9 @@
     "doctor": {
       "$ref": "#/$defs/doctor"
     },
+    "chrome": {
+      "$ref": "#/$defs/chrome"
+    },
     "worktree": {
       "$ref": "#/$defs/worktree"
     },
@@ -67,6 +70,19 @@
       },
       "description": "Strings are trimmed; empty entries are dropped."
     },
+    "chrome": {
+      "type": "object",
+      "description": "bytefly's transcript chrome presentation.",
+      "additionalProperties": false,
+      "properties": {
+        "rail": {
+          "type": "string",
+          "maxLength": 1,
+          "default": "╎",
+          "description": "The transcript rail glyph, exactly one visible column. A wide, emoji, multi-character, empty, or control value falls back to ╎. The rail leads a tool result and a notice row; it is also drawn on the call frame for the two file-mutating tools (`edit`, `write`), whose call body carries the result. There is no status fill."
+        }
+      }
+    },
     "price": {
       "type": "object",
       "description": "bytefly's price calculation (the footer's cost bar).",