pi-web-ui 0.34.3 → 0.35.1

package/README.md

@@ -164,6 +164,99 @@ Options: `--port` (default 8787), `--cwd` (workspace), `--data-dir` (sessions),
 regenerates the config and restarts the service — that's how you change its
 port/cwd.
 
+## Plugins (UI extensions)
+
+Plugins are optional UI components (extra top-bar tabs backed by their own
+client view, optionally with a server-side entry and agent tools). They live in
+your **data-dir plugins folder** (`<dataDir>/plugins/<id>/`, default
+`~/.pi-web/plugins/`) — a plugin is simply a directory containing
+`manifest.json`, an optional server entry (`index.mjs`) and an optional view
+entry (`client/entry.mjs`). No plugin directories = no plugins, nothing shows
+up in the UI.
+
+### Plugin catalog
+
+These plugins ship in this repository (`dev/plugins/<id>/`) and can be installed
+straight from GitHub:
+
+| Plugin | What it does |
+| --- | --- |
+| 📬 [webmail](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/webmail) | IMAP inbox browsing / search / read / mark / delete + SMTP sending, new-mail notifications, and an optional "allow AI to manage my mailbox" switch (six `mail_*` agent tools). Auto-installs its npm deps on first activation. |
+| 🗄️ [db-client](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/db-client) | Database workbench: connection manager + schema tree for MySQL / PostgreSQL / SQLite / SQL Server / MongoDB / Redis — table structure, paginated data with sorting, SQL editor, and row editing. Drivers auto-install on first use. |
+| 📝 [vscode-editor](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/vscode-editor) | VS Code-like workbench: multi-root file tree (local + SSH hosts), CodeMirror multi-tab editor, Remote-SSH remote file browsing/editing, draggable multi-terminal panel (xterm.js), SFTP sync & upload/download to your computer. Auto-installs `ssh2`. |
+| 📬 [demo-mailbox](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/demo-mailbox) | Minimal example plugin demonstrating the server entry + client view + two-way message protocol. Doubles as the plugin test fixture — start here if you want to write your own. |
+
+Example — install the webmail plugin:
+
+```bash
+pi-web-ui install https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/webmail
+```
+
+Each plugin's directory in the repo has its own `README.md` with full feature
+lists, configuration and per-plugin caveats.
+
+### Installing
+
+From GitHub (any of these source forms):
+
+```bash
+pi-web-ui install owner/repo                                  # shorthand
+pi-web-ui install https://github.com/owner/repo               # full URL (.git optional)
+pi-web-ui install https://github.com/o/r/tree/dev/sub/dir     # branch + subdirectory inside the repo
+pi-web-ui install owner/repo#v1.2                             # pin a branch/tag (#suffix works on any form above)
+pi-web-ui install /path/to/plugin-dir                         # local directory (for development)
+```
+
+Useful options:
+
+- `--name <id>` — custom plugin id / directory name (defaults to the repo or
+  subdirectory name; letters/digits/`-`/`_` only).
+- `--force` — overwrite an existing installation. Your plugin's local
+  `config.json` (credentials etc.) is preserved across upgrades.
+- `--data-dir <dir>` — override the data dir (default `~/.pi-web`).
+
+The CLI clones the repo (shallow; falls back to a tarball download without
+git), locates the `manifest.json` (including inside subdirectories) and copies
+the plugin into `<dataDir>/plugins/<id>/`.
+
+**No git? No network?** You can also just copy a plugin directory into
+`~/.pi-web/plugins/` by hand — same result.
+
+### Updating
+
+Re-run `install` against the same source with `--force`:
+
+```bash
+# example: update the webmail plugin to the latest version in the repo
+pi-web-ui install https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/webmail --force
+```
+
+- The upgrade preserves the plugin's local `config.json` automatically.
+- Plugins that store other local state inside their directory (e.g. db-client's
+  `db-connections.json`, vscode-editor's `ssh-hosts.json`) are **not** covered
+  by that preservation — back those up before a forced reinstall.
+- Refresh the browser afterwards; no server restart needed.
+
+### Activating
+
+If the server is running, just **refresh the browser** — new plugins are picked
+up on attach without a restart. If it isn't, they load on next start. Each
+plugin appears as a tab (🧩 or its own icon) in the top bar.
+
+### Listing / disabling / uninstalling
+
+```bash
+pi-web-ui plugins             # list installed plugins (id / name / version / description)
+pi-web-ui uninstall <id>      # remove a plugin
+```
+
+- To temporarily hide a plugin without uninstalling, use the **Settings panel
+  (⚙) → UI plugins** switches — stored per client, purely visual, no restart
+  needed. Re-enable any time.
+- `uninstall` deletes the plugin directory; refresh the browser and its tab
+  disappears. Plugin configuration written inside the plugin dir is removed
+  too — back up `<dataDir>/plugins/<id>/config.json` first if you need it.
+
 ## Themes
 
 Each theme is a **complete standalone stylesheet** — a full copy of the bundled dark `web/src/styles.css` with a different palette (no CSS-variable extraction, no base file to include). Picking a theme swaps the whole file, so any theme works with every build.

package/README.zh-CN.md

@@ -159,6 +159,86 @@ pi-web-ui server unquiesce                  # 解除排空，恢复接收新工
 `--name`（自定义服务名）。重复执行 `server install` 并传入新选项即可重新生成配置
 并重启服务 —— 这就是修改已装服务端口/工作目录的方式。
 
+## 界面插件
+
+插件是可选的界面组件（顶栏多出一个 tab，背后是插件自己的视图，可带服务端入口和 AI 工具）。
+它们安装在**数据目录的 plugins 文件夹**（`<dataDir>/plugins/<id>/`，默认
+`~/.pi-web/plugins/`）—— 一个插件就是一个目录：`manifest.json` + 可选服务端入口
+（`index.mjs`）+ 可选视图入口（`client/entry.mjs`）。目录不存在 = 没有插件，界面上不会有任何痕迹。
+
+### 插件目录
+
+以下插件随本仓库发布（`dev/plugins/<id>/`），可直接从 GitHub 安装：
+
+| 插件 | 功能 |
+| --- | --- |
+| 📬 [网页邮箱 webmail](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/webmail) | IMAP 收件箱浏览/搜索/阅读/标记/删除 + SMTP 发信、新邮件通知，可选「允许 AI 管理邮箱」（六个 `mail_*` AI 工具）。首次激活自动补装 npm 依赖。 |
+| 🗄️ [数据库 db-client](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/db-client) | 数据库工作台：MySQL / PostgreSQL / SQLite / SQL Server / MongoDB / Redis 连接管理 + 库表树 —— 表结构、分页排序、SQL 编辑器、行编辑。驱动首次使用自动安装。 |
+| 📝 [编辑器 + SSH vscode-editor](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/vscode-editor) | 类 VSCode 工作台：多根文件树（本地 + SSH 主机）、CodeMirror 多标签编辑器、Remote-SSH 远程文件浏览/编辑、可拖拽多终端面板（xterm.js）、SFTP 同步与下载到电脑。自动安装 `ssh2`。 |
+| 📬 [示例邮箱 demo-mailbox](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/demo-mailbox) | 最小示例插件：演示服务端入口 + 客户端视图 + 双向消息协议，兼作测试夹具——想自己写插件从这里入手。 |
+
+安装示例（网页邮箱）：
+
+```bash
+pi-web-ui install https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/webmail
+```
+
+每个插件在仓库里的目录都带独立 `README.md`，含完整功能清单、配置说明与注意事项。
+
+### 安装
+
+从 GitHub 安装（支持以下任意源写法）：
+
+```bash
+pi-web-ui install owner/repo                                  # 简写
+pi-web-ui install https://github.com/owner/repo               # 完整 URL（.git 可省）
+pi-web-ui install https://github.com/o/r/tree/dev/sub/dir     # 指定分支 + 仓库内子目录
+pi-web-ui install owner/repo#v1.2                             # 指定分支/tag（#后缀对以上任意写法都适用）
+pi-web-ui install /path/to/plugin-dir                         # 本地目录直接安装（开发调试用）
+```
+
+常用选项：
+
+- `--name <id>` —— 自定义插件 id / 目录名（默认取仓库名或子目录名；仅限字母数字-`-`/`_`）。
+- `--force` —— 目标目录已存在时覆盖安装。插件本地的 `config.json`（凭据等）在升级时会原样保留。
+- `--data-dir <dir>` —— 覆盖数据目录（默认 `~/.pi-web`）。
+
+CLI 会浅克隆仓库（无 git 时回退 tarball 下载），定位其中的 `manifest.json`
+（包括仓库内子目录里的），然后把插件拷贝到 `<dataDir>/plugins/<id>/`。
+
+**没装 git？没有网络？** 直接把插件目录手工拷进 `~/.pi-web/plugins/` 也行——效果完全一样。
+
+### 更新
+
+对同一来源重新执行 `install` 并加 `--force` 即覆盖更新：
+
+```bash
+# 例：把网页邮箱插件更新到仓库里的最新版
+pi-web-ui install https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins/webmail --force
+```
+
+- 升级时会自动保留插件目录里的 `config.json`（账号凭据等）。
+- 存放在插件目录**其他位置**的本地数据不在保留范围内（如 db-client 的
+  `db-connections.json`、vscode-editor 的 `ssh-hosts.json`）——强制重装前请先备份。
+- 更新后刷新浏览器即可生效，无需重启服务。
+
+### 生效方式
+
+服务运行中只需**刷新浏览器**——新插件在 attach 时即被加载，无需重启；服务未运行则下次启动生效。
+每个插件会在顶栏出现一个 tab（🧩 或插件自带图标）。
+
+### 列出 / 停用 / 卸载
+
+```bash
+pi-web-ui plugins             # 列出已装插件（id / 名称 / 版本 / 描述）
+pi-web-ui uninstall <id>      # 卸载插件
+```
+
+- 想临时隐藏某个插件而不卸载：设置面板（⚙）→「界面插件」开关即可——按客户端持久化、纯 UI
+  隐藏，无需重启，随时可重新打开。
+- `uninstall` 会删除插件目录；刷新浏览器后 tab 即消失。写在插件目录内的配置文件也会一并删除——
+  如需保留请先备份 `<dataDir>/plugins/<id>/config.json`。
+
 ## 主题
 
 每个主题是**一份完整独立的样式表** —— 即内置深色 `web/src/styles.css` 的整份副本，只是配色不同（不做 CSS 变量抽取、不需要引入基础文件）。切换主题就是整文件替换，因此任何主题都能在所有版本上工作。