@gavin-hu/my-pi-agent 0.0.0-stage → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavin Hu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# my-pi-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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)
+[![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.
+
+<img src="./assets/bytefly-chrome.png" alt="A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar" width="100%">
+
+## Contents
+
+- [Why this pack](#why-this-pack)
+- [Quick start](#quick-start)
+- [What you get](#what-you-get)
+- [Configuration](#configuration)
+- [Documentation](#documentation)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why this pack
+
+Pi ships a small, sharp core. This package is the layer on top for people who
+want the agent to *think first and work safely*:
+
+- **Plan, then execute.** A read-only planning mode turns a task into a reviewed
+  plan file that the agent then follows step by step.
+- **Delegate and parallelize.** Run specialist subagents in their own Pi
+  processes to explore, review, test, or implement while you keep the thread.
+- **Never wreck the checkout.** Work happens in an isolated `git worktree`, and
+  every prompt is snapshotted so a bad turn is one `/rewind` away.
+- **Remember across sessions.** Durable notes live in plain markdown that you
+  can read, edit, and version.
+- **Reach the web and your files.** Search, fetch, browse, open, and read
+  documents — all from inside the session.
+
+Everything is optional and independently toggleable. Nothing is patched or
+forked: Pi discovers the resources through the `pi` manifest in
+[`package.json`](./package.json), so the package upgrades with Pi like any
+other.
+
+## Quick start
+
+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 ./ -l                                           # project-local (.pi/settings.json)
+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.
+- `/settings` → **Theme** selects a theme.
+- `/plan <task>` starts a task in read-only planning mode.
+
+## What you get
+
+Sixteen extensions and two themes, grouped by what you are trying to do. Each
+extension's own `README.md` has the full tool and command surface.
+
+### Plan and delegate
+
+| Extension | Tools and commands | What it does |
+|---|---|---|
+| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | Read-only planning: the model investigates, saves a plan under `.pi/plans`, and you approve it before anything is written. Review in the TUI, or open it in a browser to leave inline comments. |
+| [`subagent`](./extensions/subagent/) | `subagent` | Delegate a task to a specialist agent (`explorer`, `planner`, `reviewer`, `worker`, `researcher`, `tester`, `debugger`, `documenter`) in its own Pi process — single, parallel, or chained. |
+| [`todo`](./extensions/todo/) | `todo`, `/todos` | A persistent task list (`pending` / `in_progress` / `completed`) with a one-line widget. |
+| [`goal`](./extensions/goal/) | `goal`, `/goal` | A persistent session objective, kept in a widget and restated before each turn. |
+| [`question`](./extensions/question/) | `ask_user_question` | Ask you one or more structured questions (labelled options plus free-form "Other") and wait. |
+| [`job`](./extensions/job/) | `job`, `/jobs` | Run long-lived shell commands in the background; inspect logs, wait, or kill them. |
+| [`watch`](./extensions/watch/) | `watch`, `/watch` | Tail a file or command output, match lines against patterns, and alert you or hand matching lines to the agent. |
+
+### Keep your work safe
+
+| Extension | Tools and commands | What it does |
+|---|---|---|
+| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree*`, `--worktree` | Work inside an isolated `git worktree` on its own branch; the built-in read/write/edit/bash tools follow, and cleanup refuses to throw work away. |
+| [`rewind`](./extensions/rewind/) | `/rewind`, `↺ N` status chip | Snapshot the repo on every prompt under `refs/pi/rewind` and restore code, conversation, or both. |
+| [`memory`](./extensions/memory/) | `memory`, `/memory` | Durable cross-session notes as human-editable markdown, injected into each run and managed through the `/memory` picker. |
+
+### Reach the world
+
+| Extension | Tools and commands | What it does |
+|---|---|---|
+| [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | Search the web (keyless DuckDuckGo by default, optional SearXNG or Brave) and fetch a page as readable text, with paging, `find`, per-hop SSRF checks, and optional PDF support. |
+| [`file-browse`](./extensions/file-browse/) | `/browse` | Start a loopback, read-only file browser rooted at the working directory, with Markdown preview and a fuzzy quick-open palette. |
+| [`document`](./extensions/document/) | `read_doc` | Extract text from a local PDF, DOCX, DOC, ODT, RTF, or XLSX in process, paged. |
+| [`file-open`](./extensions/file-open/) | `/open`, `open_path` | Open or reveal a file or directory in the OS-native application. |
+| [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | Bridge a WeChat chat to the live session over the Weixin iLink bot API; inbound text, images, and files become turns. |
+
+### Chrome and upkeep
+
+| 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-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. |
+
+## Configuration
+
+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.
+
+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
+names (the directory names under [`extensions/`](./extensions/)):
+
+```bash
+PI_DISABLED_EXTENSIONS=todo,job pi -e .
+```
+
+Names are compared case-insensitively and unknown names are ignored. This only
+stops the factories from registering; to drop the whole package, use Pi's
+`--no-extensions` or remove the package from your settings.
+
+## Documentation
+
+| Guide | What it covers |
+|---|---|
+| [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. |
+| [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 `/doctor` tells you what is missing.
+- Optional runtime pieces (for example a browser for HTML exports) are reported
+  per extension by `/doctor`.
+
+## Contributing
+
+Contributions are welcome. Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md) for
+the setup, the worktree branch flow, and the checks a change must pass. AI
+coding agents should read [`AGENTS.md`](./AGENTS.md).
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,153 @@
+# 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)
+[![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。
+
+<img src="./assets/bytefly-chrome.png" alt="一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏" width="100%">
+
+## 目录
+
+- [为什么选择这个包](#为什么选择这个包)
+- [快速开始](#快速开始)
+- [包含内容](#包含内容)
+- [配置](#配置)
+- [文档](#文档)
+- [环境要求](#环境要求)
+- [参与贡献](#参与贡献)
+- [许可证](#许可证)
+
+## 为什么选择这个包
+
+Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，面向希望智能体*先思考、
+再安全行动*的人：
+
+- **先规划，再执行。** 只读的规划模式把一次任务变成一份可审阅的计划文件，智能体
+  随后按步骤执行。
+- **委派与并行。** 在各自的 Pi 进程中运行专职子智能体来探索、审阅、测试或实现，
+  你继续把握主线。
+- **绝不搞乱检出区。** 工作发生在隔离的 `git worktree` 中，每次提示都会生成快照，
+  因此一次糟糕的回合只需一个 `/rewind` 就能回退。
+- **跨会话记忆。** 持久笔记以纯 Markdown 保存，可读、可改、可纳入版本控制。
+- **连通网络与文件。** 搜索、抓取、浏览、打开和读取文档 —— 全部在会话内完成。
+
+一切都是可选的，且可独立开关。没有任何东西被补丁或分叉：Pi 通过
+[`package.json`](./package.json) 里的 `pi` manifest 发现这些资源，因此该包能像
+其他包一样随 Pi 一起升级。
+
+## 快速开始
+
+需要一个可用的 [Pi](https://pi.dev) 安装。
+
+```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 ./ -l                                           # 仅项目本地（.pi/settings.json）
+pi -e .                                                    # 试运行一次
+```
+
+然后在 Pi 中：
+
+- `/extensions`（`/bytefly` 的别名）列出每个已加载扩展及其运行时健康状况，并启用
+  或禁用一个扩展。
+- `/doctor` 打开同一屏幕，指定扩展名时只显示该扩展，并检查每个已启用扩展在运行时
+  是否具备所需条件。
+- `/settings` → **Theme** 选择主题。
+- `/plan <任务>` 以只读规划模式开始一个任务。
+
+## 包含内容
+
+十六个扩展和两个主题，按你想达成的目标分组。每个扩展自己的 `README.md` 提供完整的
+工具与命令说明。
+
+### 规划与委派
+
+| 扩展 | 工具与命令 | 说明 |
+|---|---|---|
+| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `.pi/plans` 下，你在写入任何内容前先批准。可在 TUI 中审阅，或在浏览器中打开以留下行内评论。 |
+| [`subagent`](./extensions/subagent/) | `subagent` | 把任务委派给专职智能体（`explorer`、`planner`、`reviewer`、`worker`、`researcher`、`tester`、`debugger`、`documenter`），运行在它自己的 Pi 进程中 —— 单个、并行或链式。 |
+| [`todo`](./extensions/todo/) | `todo`, `/todos` | 持久任务列表（`pending` / `in_progress` / `completed`），配一行式 widget。 |
+| [`goal`](./extensions/goal/) | `goal`, `/goal` | 持久会话目标，保存在 widget 中，并在每个回合前重述。 |
+| [`question`](./extensions/question/) | `ask_user_question` | 向你提出一个或多个结构化问题（带标签的选项外加自由填写的“其他”）并等待回答。 |
+| [`job`](./extensions/job/) | `job`, `/jobs` | 在后台运行长时 shell 命令；查看日志、等待或结束它们。 |
+| [`watch`](./extensions/watch/) | `watch`, `/watch` | 跟踪文件或命令输出，按模式匹配行，并提醒你或把匹配的行交给智能体。 |
+
+### 保护你的工作
+
+| 扩展 | 工具与命令 | 说明 |
+|---|---|---|
+| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree*`, `--worktree` | 在隔离的 `git worktree` 里、在独立分支上工作；内置的 read/write/edit/bash 工具会跟随，清理时也不会丢弃工作。 |
+| [`rewind`](./extensions/rewind/) | `/rewind`, `↺ N` 状态标记 | 每次提示时在 `refs/pi/rewind` 下对仓库生成快照，可恢复代码、对话或两者。 |
+| [`memory`](./extensions/memory/) | `memory`, `/memory` | 跨会话的持久笔记，以可人工编辑的 Markdown 保存，注入每次运行，并通过 `/memory` 选择器管理。 |
+
+### 连通外部世界
+
+| 扩展 | 工具与命令 | 说明 |
+|---|---|---|
+| [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | 搜索网络（默认无密钥的 DuckDuckGo，可选 SearXNG 或 Brave），并把页面抓取为可读文本，支持分页、`find`、逐跳 SSRF 检查以及可选的 PDF 支持。 |
+| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览和模糊快速打开面板。 |
+| [`document`](./extensions/document/) | `read_doc` | 在进程内从本地 PDF、DOCX、DOC、ODT、RTF 或 XLSX 提取文本，支持分页。 |
+| [`file-open`](./extensions/file-open/) | `/open`, `open_path` | 用操作系统原生应用打开或定位文件/目录。 |
+| [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | 通过微信 iLink 机器人 API 把微信聊天桥接到实时会话；入站文本、图片和文件会变成回合。 |
+
+### 界面与维护
+
+| 扩展 | 工具与命令 | 说明 |
+|---|---|---|
+| [`bytefly`](./extensions/bytefly/) | `/bytefly`, `/extensions`, `/doctor`, `run_doctor` | 主题化头部与宽度自适应页脚、已完成回合之间的分隔线、`/bytefly` 扩展屏幕（别名 `/extensions` 和 `/doctor`）——列出每个扩展及其健康状况并启用或禁用一个扩展；以及可选的 `notify` 能力：当一次运行或后台任务结束、或智能体请求输入时发出系统通知。DeepSeek 开箱即定价，`bytefly.json` 是每个扩展都会读取的共享配置文档。 |
+| [`bytefly-dark`](./themes/bytefly-dark.json) / [`bytefly-light`](./themes/bytefly-light.json) | `/settings` → **Theme** | GitHub 风格的深色调色板及其浅色搭档，并支持可选的自动浅色/深色切换。 |
+
+## 配置
+
+大多数扩展无需配置。所有设置都在一个共享文档 `bytefly.json` 中，从
+`<agent-dir>/bytefly.json` 读取，并与 `<cwd>/.pi/bytefly.json` 合并（项目优先），
+位于一个以扩展名命名的顶层 section 下。每个扩展的 `README.md` 列出它的键，
+[`docs/configuration.md`](./docs/configuration.md) 为其建立索引，
+[`assets/bytefly.schema.json`](./assets/bytefly.schema.json) 校验该文件。
+
+每个扩展默认都开启。若要在加载整包时排除其中一些，把 `PI_DISABLED_EXTENSIONS`
+设为一个以逗号或空白分隔的扩展名列表（即 [`extensions/`](./extensions/) 下的目录
+名）：
+
+```bash
+PI_DISABLED_EXTENSIONS=todo,job pi -e .
+```
+
+名称比较不区分大小写，未知名称会被忽略。这只会阻止工厂注册；若要移除整包，请使用
+Pi 的 `--no-extensions`，或从你的设置中删除该包。
+
+## 文档
+
+| 指南 | 内容 |
+|---|---|
+| [快速开始](./docs/getting-started.md) | 环境要求、安装选项、验证加载、主题。 |
+| [扩展](./docs/extensions.md) | 所有扩展与主题的完整目录。 |
+| [配置](./docs/configuration.md) | 配置文件解析、按扩展索引、环境变量。 |
+| [架构](./docs/architecture.md) | 包、各扩展与 `lib/` 如何协同。 |
+| [开发](./docs/development.md) | 本地设置、检查、测试、跨平台注意事项与发布流程。 |
+| [安全](./docs/security.md) | 回环与远程界面的信任边界。 |
+
+## 环境要求
+
+- **Pi** —— 需要一个可用的安装；`my-pi-agent` 是一个包，不是分叉。
+- **操作系统** —— Windows、macOS 和 Linux；完整检查套件在三者的 CI 上都会运行。
+- **git** 需在 `PATH` 上，供 `worktree` 和 `rewind` 扩展使用；其余部分会优雅降级或
+  禁用，`/doctor` 会告诉你缺什么。
+- 可选的运行时组件（例如用于 HTML 导出的浏览器）由 `/doctor` 按扩展报告。
+
+## 参与贡献
+
+欢迎贡献。请先阅读 [`CONTRIBUTING.md`](./CONTRIBUTING.md)，了解设置、worktree
+分支流程以及改动必须通过的检查。AI 编码智能体应阅读
+[`AGENTS.md`](./AGENTS.md)。
+
+## 许可证
+
+MIT