@chainingintention/pi-web-cn 2.0.0 → 2.202610.1

package/docs/plugins.md

@@ -1,1060 +1,334 @@
-# PI WEB plugin API
+# 插件与 Pi 包
 
-PI WEB plugins are trusted browser-side ES modules that extend the PI WEB UI. They are intended for personal, team, and project-local customization, and simple enough for an LLM to create or modify directly.
+使用工作区工具、快捷操作和集成定制 PI WEB。可以安装现成的包，也可以让代理为具体工作流创建插件，无需修改 PI WEB 本身。
 
-Plugins can currently:
+本指南说明可实现的功能和使用方式；实现时请查阅[公开契约与示例](#agent-development)，不要把本页作为第二份 API 声明。
 
-- add action-palette commands;
-- add workspace tools/panels next to Files, Git, and Terminal;
-- add compact workspace-label items in the workspace list, panel header, and status bar;
-- call browser APIs and documented PI WEB plugin context helpers;
-- read workspace files and start workspace terminal commands through documented helpers;
-- serve their own static assets from the plugin directory.
+## 内置中文语言插件
 
-They do **not** run in the session daemon, do not get a server-side hook API, and are not sandboxed.
+`zh-cn` 随包提供且默认启用；在机器配置设置 `plugins["zh-cn"].enabled: false` 后恢复英文，无需额外语言文件。刷新网页、下次启动 CLI、重启服务后生效，详见[配置参考](config.md#chinese-language-plugin)。浏览器使用网关的语言，远端提示保持远端语言。
 
-## Pi packages, Pi extensions, and PI WEB plugins
+浏览器插件可通过激活上下文的可选 `translate(key, englishFallback, params)` 使用稳定消息键和命名参数；未提供翻译器或词条缺失时使用英文。语言插件以 `localizations` 贡献纯文本词典，不扫描 DOM 或注入 HTML。服务端激活上下文也可提供 `translate`，按所属机器配置格式化自有提示。旧插件 API 仍兼容；不要翻译用户输入、模型回复或代理转发的远端响应。Node 端只读取随包的 JSON 词典，不执行浏览器入口。
 
-**Pi packages** are distribution bundles managed by Pi (`pi install`, `pi remove`, `pi update`). A Pi package can provide Pi extensions, skills, prompt templates, themes, context/system prompt files, and/or PI WEB browser plugins. Many Pi packages do not include a PI WEB plugin.
+浏览器插件需要显式声明翻译类型时，可从公开入口 `@chainingintention/pi-web-cn/plugin-api` 使用 `import type` 导入 `Translator`、`TranslationParameters`、`TranslationMessages` 和 `LocalizationContribution`；服务端入口 `@chainingintention/pi-web-cn/server-plugin-api` 导出前两项。通过上下文调用翻译器，不要导入宿主内部的 `createTranslator` 或私有 `dist/` 路径。上下文的 `translate` 保持可选，兼容未提供该能力的旧宿主。
 
-**Pi extensions** are runtime modules loaded by the session daemon. They can register Pi tools, hooks, commands, and model providers. They are not PI WEB plugins.
+<a id="what-can-be-built"></a>
+## 可实现的功能
 
-**PI WEB plugins** are browser-side UI modules discovered from bundled, local, dev, and installed Pi-package sources. They cannot register model providers or server-side hooks. Enabling or disabling a PI WEB plugin is a PI WEB config task; installing, removing, or updating a Pi package is a separate Pi package-manager task.
-
-Use **Settings → Pi packages** to view configured Pi packages or install/remove/update a package. Enter only the package source, such as `npm:@scope/package`, a git/URL source, or a local path. PI WEB uses Pi's default package location, equivalent to `pi install <source>`, and does not ask for an install location.
+| 目标 | 插件功能 |
+| --- | --- |
+| 展示项目健康状态、服务链接、环境信息 | 工作区标签与面板 |
+| 添加仪表盘、文件查看器或项目工具 | 工作区面板、文件帮助方法与浏览器 UI |
+| 方便查找常用操作 | 操作面板命令与快捷键 |
+| 运行构建、测试或开发服务器 | 工作区终端命令 |
+| 定制外观 | 主题及明暗主题组合 |
+| 在聊天和文件中预览图表、文本格式 | 浏览器内容渲染器 |
+| 读取或修改工作区文件 | 列出、读取、写入、移动、删除及上传文件 |
+| 显示后端实时结果 | 浏览器入口与服务端入口之间的请求或流式通道 |
+| 保存插件自己的结果和偏好 | 持久化服务端插件目录 |
+| 发起 Pi 对话或与 Pi 扩展协作 | 宿主会话能力与会话内消息 |
+| 使用其他系统替代 Git 工作区发现 | 工作区提供器 |
 
-When machine federation is enabled, **Settings → Pi packages** targets the currently selected machine. The panel labels whether changes will run on the local/gateway machine or on a selected remote PI WEB machine. If an older or unavailable remote PI WEB server does not expose package-management routes, PI WEB reports the package management operation as unsupported or unavailable instead of silently falling back to the gateway.
+面板可支持直达链接和浏览器历史，并在文件变化或代理工作完成后刷新。文件和终端帮助方法始终针对面板所属机器与工作区，包括远端机器。
 
-Use **Settings → PI WEB plugins** to enable or disable discovered PI WEB browser plugins before the browser imports them. In a federated setup, this plugin enablement surface targets the currently selected machine and labels where changes are saved. If an older or unavailable remote PI WEB server does not advertise selected-machine settings support, PI WEB reports the plugin settings as unsupported or unavailable instead of silently falling back to the gateway.
+例如，可以请求代理创建“运行项目检查并显示结果的面板”“链接工作区预览部署的徽标”或“启动审查会话并保存结论的工具”。
 
-After installing, removing, or updating a Pi package, type `/reload` in each idle PI WEB session on the target machine to refresh ordinary Pi resources such as extensions, skills, prompt templates, themes, and context/system prompt files. Reload the browser page separately for newly discovered or changed PI WEB browser plugins. A provider-registering Pi extension follows a separate daemon-start policy; see [Pi extension provider baseline](https://pi-web.dev/config#pi-extension-provider-baseline).
+<a id="pi-packages-extensions-and-plugins"></a>
+## Pi 包、扩展与插件
 
-## PI WEB 中的 Pi 扩展对话框
+- **Pi 包**是可安装的分发包，可以包含扩展、技能、提示词模板、主题和 PI WEB 插件。
+- **Pi 扩展**定制代理的工具、命令、钩子、模型提供器及会话行为。
+- **PI WEB 插件**定制 Web 应用及工作区集成。
 
-运行在 PI WEB 会话守护进程中的 Pi 扩展可以通过 `ctx.ui.confirm()`、`ctx.ui.select()` 和 `ctx.ui.input()` 向用户提问。PI WEB 会报告 `ctx.hasUI === true`，并且这三种对话框方法确实可用：调用后会在会话记录中以内联方式显示对话框卡片，返回的 Promise 将以用户的实际回答结束，确认框返回布尔值，选择框返回所选项，输入框返回输入文本。
+一个包可包含上述三种定制。安装包与启用 PI WEB 插件是独立操作；禁用插件不会移除包里的 Pi 扩展、技能或提示词。
 
-- **可在钩子中使用，不经过提示词队列。** 回答通过独立的会话守护进程通道传递，因此运行中的 `tool_call` 钩子可以安全等待对话框；代理循环会等待钩子，并在收到回答后继续运行。支持在 `tool_call` 钩子中使用对话框进行工具授权确认。
-- **启动阶段的对话框可以回答。** 无论创建新会话还是打开已有会话，`session_start` 钩子发起的对话框都能在会话仍在启动时回答；对话框结束后启动流程继续。
-- **浏览器刷新后可恢复，最先提交的回答生效。** 浏览器刷新后会根据会话状态重新显示打开的对话框。同一会话打开多个标签页时，最先提交的回答会结束对话框，其他标签页随后显示结束状态。
-- **结束状态卡片会保留到用户关闭。** 已回答或已关闭的对话框会在会话记录中保留结果卡片。回答只会传给扩展，因此该卡片是这次交互唯一的可见记录。卡片属于浏览器本地状态：只有见过对话框打开的浏览器会显示它，切换会话或刷新页面后会清除。
-- **超时。** 扩展自身的 `timeout` 仍然生效，守护进程还提供 `extensionDialogsTimeoutMs` 安全超时（默认 5 分钟，设为 `0` 时永久等待；见[扩展对话框](https://pi-web.dev/config#extension-dialogs)）。最终期限取两者中较早的时间。没有回答就关闭的对话框会返回对应类型的取消值：确认框为 `false`，选择框和输入框为 `undefined`。
-- **中止和运行时替换。** 中止当前运行时，本轮运行中打开的对话框会立即以取消值结束。替换会话运行时（例如 `/reload` 或销毁会话）也会结束所有仍打开的对话框；新运行时的钩子可以重新打开对话框。扩展传入的 `AbortSignal` 同样有效，中止信号会关闭对话框并返回取消值。
-- **其他 UI 能力仍为空实现。** 除这三种对话框外，PI WEB 尚未实现 `ExtensionUIContext` 的其他方法（组件、状态、编辑器和 `custom`）。即使 `hasUI` 为 `true`，也不能仅凭它判断这些能力可用。
+代理行为放在 Pi 扩展中，Web UI 放在 PI WEB 插件中。需要两者协作时一起发布，通过已托管会话的连接通信。
 
-浏览器本地存在一个限制：新会话仍在创建时刷新页面，会丢失浏览器保存的待启动行，因此对话框卡片会消失。守护进程中的对话框仍会在期限到达时结束，会话创建完成后仍会出现在侧边栏中。
+<a id="how-plugins-work"></a>
+## 插件如何运行
 
-## Trust model
+包可以声明浏览器入口、服务端入口或双入口：
 
-Plugins run as JavaScript in the browser app. Treat them as trusted code:
+- **浏览器入口**贡献操作、面板、标签、主题与内容渲染器，使用宿主帮助方法访问文件、终端及提示词编辑器。
+- **服务端入口**运行在会话守护进程中，可为浏览器入口服务、存储插件数据、使用宿主能力或提供工作区。
+- **包内对等入口**连接同一插件的浏览器与服务端。宿主解析机器和工作区；插件不必拥有该工作区才能为其服务。
+- **能力**声明所需的宿主或插件功能。启动前必须满足指定版本的依赖。
 
-- they can call browser APIs;
-- they can read workspace files and start terminal commands through documented plugin helpers;
-- they can render arbitrary Lit templates/custom elements in plugin contribution areas;
-- they should not be installed from untrusted sources.
+在 `activate()` 中声明贡献，在 `start()` 中初始化依赖支持的工作，在 `dispose()` 中释放资源。长时间工作遵循 `lifetimeSignal`。简单浏览器插件仅需返回贡献。
 
-PI WEB's `/api/...` HTTP and WebSocket endpoints are internal implementation details. Plugin code should use the documented context helpers instead. Daring plugins can still reach private routes or runtime objects because they run in the browser, but those private surfaces are experimental: they may graduate into stable helpers, change shape, or disappear.
+<a id="scoped-discovery-and-backend"></a>
+### 作用域发现与后端
 
-## What to ask AI to build
+浏览器 API v5 的 `catalog` 固定到创建上下文时的机器，只读查询公开项目、工作区和会话投影，不返回 transcript 或内部会话路径。切换选择不会改变已保留 catalog 的目标；会话使用完整、区分大小写的精确 ID，不接受缩写。
 
-Humans should not need to hand-code plugins. Give an AI agent a concrete UI goal and ask it to create or modify a local plugin.
+可选 `backend` 指向同包配对的实际服务端入口：`backend.forScope({ kind: "machine" })`、`{ kind: "project", projectId }` 或 `{ kind: "workspace", projectId, workspaceId }` 返回请求/通道 peer。没有 session backend scope。宿主重新解析 authority，插件不传可信 cwd；机器与后端 revision 不匹配时拒绝，不静默使用网关同名后端。操作是否支持取决于实际 peer/capability，不由 API 版本单独保证。旧浏览器 v4 与服务端 v3 继续使用其原契约。
 
-Good plugin requests:
+服务端可声明 `PI_WEB_HOST_CATALOG_CAPABILITY` 获取目标宿主的公开 catalog；Pi 配套扩展通过公开服务端入口的 `createCompanionBackend(pi.events, pluginId)` 发现本地配对 backend，要求在 PI WEB 已托管事件总线上运行。普通宿主会话连接不开放管理会话，完整特权也不取消该边界。普通 catalog 排除当前配置的管理 root；它不替历史文件补写耐久 scope，曾更换管理 root 的遗留文件需人工隔离。
 
-- "Show a workspace badge with the dev server URL from `.env`."
-- "Add a workspace panel with links to logs, dashboards, and local services for this repo."
-- "Add an action-palette command that starts a standard code-review prompt."
-- "Show whether the current workspace is a git worktree, main checkout, staging env, or feature branch."
-- "Add a compact status badge based on a project health file or command output saved in the repo."
+<a id="styles-highlighting-and-display"></a>
+### 样式、高亮与显示文本
 
-Copy-paste prompt for creating a plugin:
+v5 `stylesheets` 贡献包含 `id`、HTTP(S) `url` 和可选 `order`（默认 `1000`，较小先加载，同序按限定贡献 ID）。使用模块相对 URL 生成 CSS 文件地址，文件内资产相对 CSS 地址解析；不支持内联 CSS 或运行时 `@import`。v5 主题使用样式表；需要共享样式的组件使用公开 `StylesheetIntegrationCapabilityV1` 注册 shadow root 或创建 Lit lifecycle controller，并在断开时释放。主题属于网关应用，浏览器设备偏好优先于网关默认值。
 
-```text
-Build a PI WEB plugin for this project.
-Goal: <describe the UI behavior>.
-Before coding, read the PI WEB plugin docs:
-https://pi-web.dev/plugins
-Full API reference:
-https://pi-web.dev/plugins.md
-Create it as a local plugin under ~/.pi-web/plugins/<plugin-id>.
-Use the appropriate extension points from the docs.
-Validate by checking /pi-web-plugins/manifest.json and explain how to reload/debug it.
-Do not modify PI WEB itself.
-```
+共享基础 UI 通过 `{ pluginId: "pi-web", id: "stylesheet-integration", version: 1, parse }` 声明依赖并在 `start` 中解析；组件使用 `createController(this, { sharedUi: true })` 或 `registerRoot(root, { sharedUi: true })`。省略 opt-in 只接收贡献样式，不接收共享按钮、选择器、工具栏、标签和文件行。宿主持有注入、排序与清理；原生事件、键盘交互、焦点与 ARIA 仍由消费者持有。共享 UI 不包含菜单、表单和对话框，插件不得深导入客户端私有样式。
 
-Copy-paste prompt for modifying a plugin:
-
-```text
-Improve the PI WEB plugin at <path>.
-Before coding, read the PI WEB plugin docs:
-https://pi-web.dev/plugins
-Full API reference:
-https://pi-web.dev/plugins.md
-Keep the plugin compatible with the documented v1 API.
-After editing, check the manifest endpoint and browser-console failure cases.
-```
+`stylesheet-integration` 能力可由支持的浏览器 v4/v5 入口声明，能力版本与入口版本独立；这不使旧入口获得 v5 专属的 `stylesheets` 贡献字段。
 
-## Canonical example: bundled Info plugin
+基础主题同步提供默认布局与控件表现，主题 CSS 可扩展配色与布局；基础规则在 `pi-web-base` cascade layer，普通未分层主题规则遵循 CSS cascade 覆盖。内部选择器、共享类和外观仍属实验性，不因能力版本而冻结；具体控件入口见[共享 UI 导航](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/docs/ui-primitives.md)。
 
-PI WEB ships a real bundled `info` plugin. Use it as the reference example because it is intentionally small while still exercising all core contribution types: an action, a workspace label, and a workspace panel.
+v5 `syntaxHighlighters` 返回有序、不重叠的 UTF-16 范围 token，不返回 HTML；宿主负责安全显示，插件遵守输入 `signal`。v5 内容渲染器还可提供 `title`、同步 `supports(request)`，并接收机器、语言和文件路径提示；正文仍是不可信输入，净化与清理要求不变。精确签名以公开声明为准。
 
-Bundled PI WEB plugins are developed as TypeScript in the repository, but their `package.json` metadata still points at built JavaScript because plugins are loaded by the browser as JS ES modules. `npm run dev:web` watches and rebuilds bundled plugin TS into `dist/pi-web-plugins/` during development, and `npm run build` emits the JS before packaging a release.
+Pi 的 Markdown transformer 链在 daemon 的浏览器投影阶段运行，仅对完成及历史的用户、assistant 文本和 thinking 派生 `displayText`；部分流式文本完成后才应用，文件预览不受影响。canonical 消息、持久化历史、模型输入、审计原文和实际 `thinkingLevel` 不变。“复制消息”和消息操作使用原文；代码围栏的 Raw/Copy 使用变换后的围栏源码。
 
-Source files:
+### 应用级面板与选择
 
-```text
-pi-web-plugins/info/package.json
-pi-web-plugins/info/pi-web-plugin.ts
-pi-web-plugins/info/infoInternals.ts
-```
+`applicationPanels` 与 `workspacePanels` 由同一个浏览器工具区域装配。前者依附当前机器，无需先选项目、工作区或会话；后者需要已选工作区。应用级面板获得当前机器与公开选择快照，`workspace` 和工作区终端按可用性提供。内置 Info 使用应用级面板；无工作区时仍可显示机器和 PI WEB 状态。
 
-`pi-web-plugin.ts` is the plugin skeleton: metadata plus contribution definitions. `infoInternals.ts` holds everything the bundled panel and action actually render, so you can ignore or replace it when copying the plugin.
+激活上下文的可选 `selection` 服务由宿主持有。`getSnapshot()` 返回独立的基本选择快照；`subscribe()` 在选择改变后通知，不做首次回调，面板关闭后仍可订阅。返回的取消函数可提前结束订阅，插件生命周期结束时统一清理。快照不包含内部会话文件路径、消息正文或整份应用状态。
 
-Built module:
+操作、应用级面板和工作区上下文的可选 `projects` 服务只读查询创建上下文时的机器：`listProjects()` 返回注册项目，`suggestDirectories(query)` 返回目录建议。保留的服务不会随之后的机器选择漂移；远端错误不会改查网关本机。旧宿主可能不提供这些可选服务。
 
-```text
-dist/pi-web-plugins/info/pi-web-plugin.js
-```
+### 提示上下文 chip
 
-Package metadata:
+`prompt.setChip({ id, label, text, onRemove? })` 将插件上下文暂存在该上下文捕获的机器和会话，作用域同时包含会话工作目录，不同工作区的同名会话不共享 chip；要求创建上下文时已有可用、非归档的会话。相同插件内的相同 `id` 替换内容与回调；`prompt.removeChip(id)` 可静默撤回。方法在旧宿主上可能不存在，不应从渲染回调中修改 chip。
 
-```json
-{
-  "name": "@pi-web/info-plugin",
-  "private": true,
-  "piWeb": {
-    "plugins": [
-      { "id": "info", "module": "pi-web-plugin.js" }
-    ]
-  }
-}
-```
+chip 由浏览器宿主持有，不是持久化会话数据；关闭面板、切换会话后仍保留各自内容，刷新页面后清除。发送时正文以空行分隔附加到消息，带 chip 的输入作为普通提示词而非斜杠或 shell 命令提交。只有服务端接受后才消费本次提交的版本，失败时保留以便重试，不删除发送期间的替换内容。用户移除和成功提交分别通知 `onRemove("user")` 与 `onRemove("submitted")`；程序撤回不通知。
 
-Module shape excerpt:
-
-```js
-export default {
-  apiVersion: 2,
-  name: "Info Plugin",
-  activate: ({ html, svg }) => ({
-    contributions: {
-      actions: [/* action definitions */],
-      workspaceLabels: [/* compact label definitions */],
-      workspacePanels: [/* panel definitions using html, optional icons using svg */],
-    },
-  }),
-};
-```
+### 从聊天打开工作区文件
 
-When copying the Info plugin, choose a new plugin id so it does not conflict with the bundled `info` plugin.
+聊天 Markdown 中的相对文件链接（包括 `./file`）和会话工作区内的绝对路径会在内置文件面板中打开。修饰键、新标签页点击或没有面板接受链接时仍使用下载 URL。文件访问仍经过服务端工作区包含检查。
 
-The Info panel doubles as an always-available PI WEB status view: it renders the host-provided `context.state.piWebStatus` (versions, installation, release state, machine, and workspace details) without issuing its own requests, and its action copies a plain-text diagnostics summary suitable for bug reports.
+工作区面板通过同步 `fileOpenQuery(context, path)` 选择是否接受链接。上下文属于该贡献，路径是解码后的工作区相对路径；返回如 `{ file: path }` 的导航查询，或返回 `undefined` 拒绝。钩子不能产生副作用。宿主按面板 `order`、标题顺序打开当前机器上第一个可见、启用且接受链接的面板，通过普通导航设置命名空间查询。面板从 `context.navigation.query` 读取选择，不需要依赖文件插件。
 
-PI WEB also ships an `updates` plugin that demonstrates dynamic `visible` and `badge` callbacks for tabs that only appear when the host has status messages or needs extra install visibility.
+### 面板与标签导航
 
-## Local plugin usage
+URL 的 `view` 选择响应式面板：`navigation`、`chat` 或 `workspace`。独立的 `tool` 参数按贡献 ID 选择工作区标签。打开工具设置 `view=workspace` 和对应 `tool`；切换聊天保留工具选择。`view` 不接受贡献 ID。浏览器插件用 `selectMainView("workspace")` 显示工作区但不改变标签，或用 `selectWorkspaceTool(panelId)` 选择并显示工具。
 
-This works with the production native-service install. PI WEB discovers plugins from `~/.pi-web/plugins/<plugin-package>/` on the web/API side; no PI WEB rebuild or session-daemon restart is required. If `PI_WEB_DATA_DIR` is set, use `$PI_WEB_DATA_DIR/plugins` instead.
+无效值留在 URL 中，不自动重定向。无效 `view` 显示警告，移动布局展示导航；双列布局保留导航，并展示有效请求工具，否则展示聊天；桌面保留常规列。有效工作区视图配无效工具时显示标签不可用，不选择其他标签，也不重复警告。省略参数使用默认值，不是错误。
 
-Symlink a plugin folder into PI WEB's local plugin directory:
+操作与工作区面板上下文提供完整目的地导航 `navigate(destination): Promise<void>`：
 
-```bash
-mkdir -p ~/.pi-web/plugins
-ln -s /path/to/plugin-folder ~/.pi-web/plugins/plugin-id
+```ts
+await context.navigate({
+  machineId: context.machine.id,
+  projectId: context.workspace.projectId,
+  workspaceId: context.workspace.id,
+  sessionId: sourceSessionId,
+  view: "chat",
+});
 ```
 
-Reload the PI WEB browser tab. PI WEB serves plugin modules with an mtime-based `?v=` cache buster. After editing a plugin, hard reload the browser if you do not see changes.
+所有字段都可省略：`machineId`、`projectId`、`workspaceId`、`sessionId`、`view` 及完整贡献 ID 的 `tool`。省略机器意味着调用时选中的机器。这不是路由补丁：省略字段使用宿主普通恢复默认值，不复制当前会话、工具或贡献查询；默认值可以恢复记忆中的会话。打开已知会话时提供项目和工作区作用域。宿主不会遍历查找 ID，也不会创建不存在的目的地。
 
-## Remote machine plugins
+Promise 在恢复完成时结束，也可在被较新导航取代时正常结束。缺失或不可用的目的地使用普通宿主 UI，不再额外拒绝 Promise。参数类型错误或无效 `view` 会在改变 URL/UI 前以 `TypeError` 拒绝。Captain's Log 用此接口打开结果记录的源会话。
 
-When [machine federation](https://pi-web.dev/machines) is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
+### 聊天与文件内容预览
 
-- actions, workspace panels, and workspace labels only appear while that machine is selected;
-- plugin file and terminal helpers run against that machine;
-- plugin code is loaded best-effort through the current gateway and cached for the browser page lifetime;
-- if the gateway and remote machine both have an enabled plugin with the same original id, `machineSpecific` metadata decides whether the gateway copy is reused or only the selected machine's copy can appear;
-- remote theme contributions are ignored for now because themes are app-wide;
-- mixed PI WEB versions across federated machines are best-effort and not guaranteed compatible.
+浏览器插件的 `contentRenderers` 提供 `id`、围栏 `languages` 或不含点的 `fileExtensions`，同步 `render(input)` 返回 Lit 模板。`renderMode` 默认为 `manual`，用户选择命名视图后才激活；`automatic` 可自动显示。v5 还可用 `title` 命名视图、同步 `supports(request)` 判断资格，并接收机器、语言和文件路径提示；旧 v4 输入不变。
 
-Remote plugin enablement is controlled by the remote machine's PI WEB plugin config. To edit or disable a remote machine plugin, select that machine and use **Settings → PI WEB plugins** when the remote server exposes selected-machine settings, or open that machine directly/update its config file.
+同一渲染器用于聊天围栏、文件 Markdown 围栏和独立文本文件，并遵循所属机器可用性。浏览器先发现 bundled 默认插件，再发现 installed 覆盖，各组内部顺序保持不变。匹配项保持插件发现顺序，最后一个匹配的 automatic 渲染器是默认；后来的 manual 渲染器不抢占自动默认。异步加载完成顺序不决定优先级，用户显式选择优先。每个渲染器与“源码”（Raw）是单行横向滚动的命名按钮，同时仅挂载所选预览，不使用选择器菜单。
 
-Plugin package metadata may set `machineSpecific: true` when the plugin's meaning is tied to the selected PI WEB machine:
+聊天按代码块在当前标签页记忆显式渲染器与源码选择：从最后一次显式选择起 **15 分钟**，最多 **128** 个最近选择块，作用域包含机器、会话、entry、part、块和精确源码。重新挂载不延长期限，源码变化或渲染器不可用时恢复默认；页面重载清除记忆。独立文件使用自己的浏览器源码/预览偏好，URL 模式优先，默认策略不自动变成用户偏好。
 
-- Omitted or `false`: use the gateway copy when the same plugin id is also present on a remote machine. This is best for portable UI plugins whose helpers already route through the selected machine.
-- `true`: the gateway copy only appears for the local machine. When a remote machine is selected, only that remote machine's copy can appear; if the remote machine does not expose the plugin, the plugin is hidden. This is best for plugins that report machine-local PI WEB status or depend on machine-local plugin code.
+Raw 始终提供未高亮源码，Copy 复制当前代码块源码，即使正在预览也不复制图形。未闭合围栏、截断及超过 **100,000 UTF-16 码元**的输入不渲染；文件另有内联字节限制。渲染失败回退源码；追加正文不重启未变的闭合块，切换视图中止旧工作。Mermaid 图形保持手动激活，代码高亮与图形预览是独立视图。
 
-For portable plugin assets, prefer URLs relative to the plugin module, for example:
+`input` 的 `signal` 和 `fail(error)` 用于生命周期及异步错误；断开或中止时清理，过期错误不影响新视图。正文不可信，保留聊天和文件各自的净化器，不执行源码或放宽策略。
 
-```js
-const url = new URL("./asset.json", import.meta.url);
-```
-
-If a remote plugin constructs absolute asset URLs, it should use the `pluginId` from `activate()` because PI WEB gives remote plugins a gateway-scoped runtime id. Hard-coded `/pi-web-plugins/<original-id>/...` URLs may point at the gateway instead of the remote machine.
+消费者在 `requires` 声明 `{ pluginId: "pi-web", id: "content-rendering", version: 1, parse }`，在 `start` 解析。`ContentRenderingCapability` 提供 `listRenderers(request)`、`renderText(request)` 和 `renderMarkdown({ machineId, text, truncated?, toSafeHtml, allowManualPreview? })`。列表按发现顺序返回 `{ id, label, renderMode }`，不调用渲染器。
 
-## Manage PI WEB plugins
+只有 `controls: "external"` 的 `renderText` 接受 `rendererId`，缺失或不可用时使用上述默认规则；内嵌控件自己拥有选择。消费者使用外部控件时自己提供视图选择、源码访问及移除预览。`allowManualPreview: true` 可授权手动预览，但不覆盖逐块 Raw 选择；文件与聊天各自持有用户意图，能力不持久化偏好。`renderMarkdown` 使用消费者可信净化器。精确签名见[公开浏览器契约](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/src/plugin-api.ts)。
 
-Open **Settings → PI WEB plugins** to review discovered bundled, local, dev, and Pi-package-supplied PI WEB plugins for the selected PI WEB machine. When the local machine is selected, this is the gateway plugin list; when a remote machine is selected, the list comes from that remote PI WEB server and includes disabled discovered plugins it exposes. PI WEB can disable any discovered selected-machine plugin before the browser imports it. Core app contributions such as the built-in command palette, base workspace tools, and themes are not managed through this plugin list.
+### 公开会话数据与消息操作
 
-This surface is only for PI WEB plugin enablement. To install, remove, or update Pi packages that may provide PI WEB plugins or other Pi resources, use **Settings → Pi packages**. In a federated setup, both the Pi packages panel and the PI WEB plugins panel target the selected machine; plugin enablement still writes the PI WEB `plugins` config key rather than changing Pi package-manager settings.
+会话快照中的 `metadata` 只包含主动发布的 UI-safe 命名空间数据，不暴露任意 custom entries。命名空间不构成权限或所有权隔离，插件须校验自己的 schema 并安全显示；旧宿主可省略该字段。服务端发布与浏览器读取都不应放入秘密。
 
-Plugin preferences are stored under the top-level `plugins` config key in the PI WEB config file:
+`messageActions` 默认针对持久 entry，调用时提供受保护的 `history.fork()`/`goBack()`；`target: "display"` 针对当前显示切片，可包含未持久化文本，但没有历史操作助手。两者提供的普通原文均排除 thinking/tool payload，不使用派生 `displayText`。可见性和可用性判断同步且无副作用，真正操作由调用上下文固定到原机器/会话；插件自己决定确认。
 
-```json
-{
-  "plugins": {
-    "workspace-tasks": {
-      "enabled": true,
-      "settings": {}
-    },
-    "info": {
-      "enabled": false
-    }
-  }
-}
-```
+### 会话与配套扩展
 
-Plugins are enabled by default. Set `enabled` to `false` to remove a plugin from `/pi-web-plugins/manifest.json` so the browser will not import or activate it on the next page load. The optional `settings` object is reserved for plugin-specific settings.
+服务端插件可创建普通、可见的 Pi 会话，可带初始提示词，也可不带。配套 Pi 扩展可与后端交换消息，使用 Pi API 执行代理工作。
 
-After changing plugin enablement, reload the PI WEB browser tab. Already-loaded plugin JavaScript is not unloaded from the current page.
+**会话一旦发布就属于用户。** 初始任务完成、浏览器关闭或发起插件销毁，都不会丢弃会话或停止用户后续工作；用户可以继续对话。
 
-## Built-in plugins
+消息连接只针对该机器已托管的会话，不自动打开已保存会话。发送成功不能证明配套扩展已安装或工作成功，集成必须自己报告进度与结果。连接不重放启动消息；关闭连接不停止代理。
 
-PI WEB ships core, discoverable plugins in the main `@chainingintention/pi-web-cn` npm package. No separate `pi install` step is required: update PI WEB, reload the browser tab, and the bundled plugins appear in `/pi-web-plugins/manifest.json`.
+### 存储与后台工作
 
-Built-in plugins can be managed from **Settings → PI WEB plugins** or with the top-level `plugins` config key.
+服务端插件获得独立于安装代码的持久化 `dataDirectory`，同一机器上该插件的各项目共享该目录。插件自己负责格式、迁移与清理，宿主不提供另一套存储 API。
 
-### Updates
+请求和通道有界，可能失败、超时或断开。发送成功不保证送达，宿主不自动重试不确定工作。长任务应自行持久化状态，让 UI 重连时不重复启动任务。
 
-**Plugin id:** `updates`
-**What it does:** adds a conditional **Updates** workspace tab with PI WEB update, restart, and installed-service guidance, plus a **Check for PI WEB Updates** action for the selected machine.
+### 工作区提供器
 
-While a browser tab is connected, PI WEB refreshes the selected machine's status every 15 minutes. npm release lookups are cached on that machine for six hours, so the automatic refresh normally contacts npm at most once in that window. Run **Check for PI WEB Updates** from the action palette to bypass both caches and check immediately. Operator settings that skip remote version checks, such as `PI_WEB_OFFLINE`, are still respected.
+提供器决定项目包含哪些工作区。主提供器可对它声明的项目替代内置 Git；Git 为后备，没有提供器认领时项目目录仍可作为工作区。
 
-Updates is enabled by default. It declares `machineSpecific: true` so the gateway Updates tab and action only appear for the local machine; while a remote machine is selected, that remote machine's Updates plugin is used if available. To hide it, disable `updates` in **Settings → PI WEB plugins** or set:
+声明冲突会明确报错；认领后失败不会静默把所有权交给另一提供器。提供器也可声明工作区删除能力，删除作为可见终端操作运行。
 
-```json
-{
-  "plugins": {
-    "updates": { "enabled": false }
-  }
-}
-```
+工作区发现必须在宿主会话服务启动前就绪。包同时需要提供器和会话功能时，在同一个包中声明两个插件入口，无需拆分分发包。
 
-### Workspace Tasks
+<a id="install-and-manage"></a>
+## 安装与管理
 
-**Plugin id:** `workspace-tasks`
-**Config file:** `.pi-web/tasks.json`
-**What it does:** adds a **Tasks** workspace tab for running configured shell commands in dedicated PI WEB terminals.
+在 **设置 → Pi 包** 安装、更新、移除 npm、git/URL 或本地来源的包；在 **设置 → PI WEB 插件** 启用/禁用集成，查看是否激活、是否需要重启。
 
-Workspace Tasks is enabled by default. To hide it, disable `workspace-tasks` in **Settings → PI WEB plugins** or set:
+可在[社区插件目录](https://pi-web.dev/community-plugins)搜索 npm 上的包，再复制 `npm:package-name` 到目标机器安装。目录由静态网页直接查询 npm，不是 PI WEB 服务端 catalog，也不会自动安装。社区包未经审查或背书，只安装可信作者的包；更多发布约定见目录的[分享插件](https://pi-web.dev/community-plugins#publish)。
 
-```json
-{
-  "plugins": {
-    "workspace-tasks": { "enabled": false }
-  }
-}
-```
+| 变更 | 后续操作 |
+| --- | --- |
+| 安装或编辑纯浏览器插件 | 刷新浏览器 |
+| 安装、更新、配置、启用、禁用服务端插件 | 重启目标机器会话守护进程，再刷新浏览器 |
+| 改变普通 Pi 扩展、技能或提示词 | 在每个空闲会话执行 `/reload` |
+| 改变注册模型提供器的扩展 | 遵循[提供器重启规则](https://pi-web.dev/config#pi-extension-provider-baseline) |
 
-Configure workspace tasks in `.pi-web/tasks.json`:
+**重启会话守护进程可能中断活跃会话和终端。** 先检查活跃工作，从它托管的会话之外重启。原生 systemd 用户服务：
 
-```json
-{
-  "version": 1,
-  "tasks": [
-    {
-      "id": "app.start",
-      "title": "Start app",
-      "group": "Development",
-      "description": "Start the local development server.",
-      "command": "npm run dev"
-    },
-    {
-      "id": "db.reset",
-      "title": "Reset DB",
-      "group": "Database",
-      "command": "go -C klingit-go run ./cli db reset",
-      "confirm": true
-    }
-  ]
-}
+```sh
+systemctl --user restart pi-web-sessiond
 ```
 
-Open a workspace, choose the **Tasks** tab, and click **Run** next to a task. Commands run in the workspace root because PI WEB creates the terminal for that workspace.
-
-Task fields:
-
-- `version`: must be `1`.
-- `tasks`: array of task definitions.
-- `id`: stable task id, matching `^[a-z][a-z0-9.-]*$`.
-- `title`: button label.
-- `command`: literal shell command sent to the terminal.
-- `description`: optional explanatory text.
-- `group`: optional group heading.
-- `confirm`: optional boolean. When true, the browser asks before dispatching the command.
-
-Review task configs before running them, especially in shared projects. Workspace Tasks runs trusted shell commands from your repositories.
+浏览器刷新、Web/API 重启或 Pi `/reload` 不激活服务端插件变更。重启前“期望”与“实际”状态可能不同；浏览器入口与实际服务端不匹配时会暂缓提供，不运行不兼容代码。
 
-### Relays
+多数插件默认启用，包可以默认关闭，设置可以覆盖。插件配置保存在普通 [PI WEB 配置](https://pi-web.dev/config)，不是安装文件里。
 
-**Plugin id:** `relays`
-**What it does:** adds a read-only **Relays** workspace tab for browsing the workspace's relays, plus an **Open Workspace Relays** action for the selected workspace that opens the same tab.
+### 本地开发
 
-A relay is a directory of markdown notes under `.pi-web/relays/<name>/` in the workspace root — the convention used by the Relay method for chaining agent sessions. The tab lists each relay's documents with `status.md`, `charter.md`, and `log.md` first (in that order), followed by any other files alphabetically, and opens `status.md` by default. Markdown documents render as sanitized HTML; other files render as preformatted text, and binary files have no preview. Truncated documents show a notice, and **Refresh** re-scans the workspace and reloads the open document.
+代理可在任意目录开发包，再链接到本地插件目录：
 
-Documents in subfolders are listed too. Folders appear as chips in the document strip, and expanding one inserts its files inline after it. Expanding a folder collapses its siblings at the same level, while collapsing the folder that contains the open document keeps the selection and highlights that folder. Relay trees deeper than five levels, larger than 200 documents, or containing more than 50 folders are listed partially with a notice.
-
-With several relays, a picker pre-selects the most recently modified one; a single relay opens directly. A workspace without `.pi-web/relays/` shows an empty state explaining the convention. The tab never creates, edits, or deletes relay files.
-
-Relays is enabled by default. To hide it, disable `relays` in **Settings → PI WEB plugins** or set:
-
-```json
-{
-  "plugins": {
-    "relays": { "enabled": false }
-  }
-}
+```sh
+mkdir -p ~/.pi-web/plugins
+ln -s /path/to/plugin-folder ~/.pi-web/plugins/my-plugin
 ```
 
-## Discovery and packaging
+设置 `PI_WEB_DATA_DIR` 时改用 `$PI_WEB_DATA_DIR/plugins`。无需重建 PI WEB，但包必须包含编译后的 JavaScript；宿主不编译任意已安装插件源码。
 
-PI WEB builds the gateway `/pi-web-plugins/manifest.json` from these sources:
+<a id="remote-machines"></a>
+## 远端机器
 
-1. Bundled plugins in the PI WEB package:
+安装与设置针对设置中选中的机器。远端服务端代码运行在远端，浏览器界面经网关显示。文件、终端、对等帮助方法保留机器作用域。机器专属插件使用该机器自身安装；便携的纯浏览器插件可复用网关副本。主题属于整个应用，远端主题贡献忽略。
 
-   ```text
-   pi-web-plugins/<plugin-package>/
-   ```
+此 API 迁移期间网关与目标一起升级，重启更新后的 Web/API 与相关会话守护进程，再刷新浏览器。混合版本会使远端插件（包括 Git）不可用，宿主不静默替换为网关后端。
 
-2. User-local plugins:
+<a id="included-tools-and-optional-packages"></a>
+## 内置工具与可选包
 
-   ```text
-   ~/.pi-web/plugins/<plugin-package>/
-   ```
+- **终端**提供终端和命令运行，是普通启动的必需插件，仅紧急安全启动可跳过。
+- **文件**提供文件浏览、预览、上传；禁用面板不移除其他插件的文件帮助方法。
+- **Git**发现工作区并显示状态/差异；禁用后保留项目目录工作区，除非其他提供器认领。
+- **Mermaid**默认手动模式，点击“渲染”预览 `mermaid` 围栏和 `.mmd`/`.mermaid` 文件。内置引擎在不透明来源、网络受阻的沙箱中本地运行，不发送源码给图表服务。交互链接和外部资源不可用。禁用后保持代码显示；纯浏览器插件只需刷新页面。
+- **信息**作为应用级面板显示 PI WEB 状态与可复制诊断，无需先选择工作区。
+- **更新**在需要时显示更新/重启建议，并提供手动检查。
+- **工作区任务**将项目命令显示为可运行操作。
 
-   Entries may be real directories or symlinks. This is the recommended development workflow.
-
-3. Installed Pi packages that expose PI WEB plugin metadata. Pi packages may be user or project scoped. Installing/removing/updating Pi packages is done from **Settings → Pi packages** (or Pi's package manager), not from the PI WEB plugin enable/disable list.
-
-Remote machines expose their own manifests through the gateway at `/api/machines/<machine-id>/pi-web-plugins/manifest.json`. Those plugin modules are rewritten to gateway-scoped asset URLs and registered under machine-scoped runtime ids so duplicate plugin ids on different machines do not collide.
-
-Plugin package directory names and plugin ids must be valid identifiers:
-
-```text
-^[a-z][a-z0-9.-]*$
-```
+### 工作区任务
 
-A package can expose one or more PI WEB plugin modules. There is exactly one supported `package.json` metadata shape:
+在项目创建 `.pi-web/tasks.json`：
 
 ```json
 {
-  "private": true,
-  "piWeb": {
-    "plugins": [
-      { "id": "review", "module": "dist/review.js" },
-      { "id": "dashboard", "module": "dist/dashboard.js", "machineSpecific": true }
-    ]
-  }
-}
-```
-
-Rules:
-
-- `piWeb.plugins` must be an array of objects.
-- Each entry must have an explicit `id` and `module`.
-- `id` must match `^[a-z][a-z0-9.-]*$`.
-- `module` must be a safe relative path inside the plugin package root.
-- `machineSpecific` is optional and must be a boolean; omit it for the default portable gateway behavior.
-- Duplicate plugin ids are not auto-renamed; later duplicates are skipped.
-- Legacy shortcuts such as `piWeb.plugin`, string entries in `piWeb.plugins`, `piWeb.id` fallback ids, and no-`package.json` fallbacks are not supported.
-
-### Manifest and assets
-
-The manifest contains each discovered plugin module. Current PI WEB releases emit `module` as a leading application-root reference:
-
-```json
-{
-  "plugins": [
-    {
-      "id": "my-plugin",
-      "module": "/pi-web-plugins/my-plugin/pi-web-plugin.js?v=1234567890",
-      "source": "local",
-      "scope": "local",
-      "machineSpecific": false
-    }
+  "version": 1,
+  "tasks": [
+    { "id": "app.start", "title": "启动应用", "command": "npm run dev" },
+    { "id": "db.reset", "title": "重置数据库", "command": "npm run db:reset", "confirm": true }
   ]
 }
 ```
 
-The browser maps leading application-root references into the current application base, so the same manifest works at the origin root or under a reverse-proxy path prefix. Keeping this output format also lets gateways from existing PI WEB releases consume plugins from an upgraded remote machine. For compatibility, federated gateways additionally accept explicit manifest-relative references such as `./my-plugin/pi-web-plugin.js` and legacy plugin-root-relative references such as `nested/pi-web-plugin.js`; all accepted forms are rewritten to deployment-portable, gateway-relative references.
+从“任务”标签运行工作区终端命令。任务可带 `description`；尤其共享仓库中，运行前检查命令。禁用插件只隐藏标签，不修改项目文件。
 
-`source` describes where the plugin came from (`bundled`, `local`, or the Pi package source). `scope` is `bundled`, `local`, `user`, or `project`. `machineSpecific` controls whether the gateway copy is valid for remote machines or only each selected machine's own copy can appear.
+### 中继
 
-At an origin-root deployment, a plugin's static assets are available under:
-
-```text
-/pi-web-plugins/<plugin-id>/<path-inside-plugin-root>
-```
+随包分发的 Relay 提供跨会话工作提示词和技能，并在只读“中继”标签展示 `.pi-web/relays/` 计划与进度，不从标签启动或编辑中继。
 
-Prefer module-relative asset URLs so they also work for remote machine plugins. For example, a built plugin module can reference an SVG shipped beside it:
-
-```js
-const iconUrl = new URL("./assets/icon.svg", import.meta.url);
-```
-
-The final installed plugin package must contain `assets/icon.svg` at that path relative to the final built module. PI WEB serves files that already exist in the package; it does not copy a source `public/` directory or apply Vite-style public-directory semantics. Configure the plugin build and package contents to emit or copy the asset into its final module-relative location.
-
-PI WEB prevents asset path traversal outside the plugin root. JavaScript, JSON, CSS, HTML, and SVG files get appropriate content types; unknown file types are served as octet-stream.
-
-## Plugin module shape
-
-The entry module must default-export a plugin object:
-
-```ts
-interface PiWebPlugin {
-  apiVersion: 2;
-  name: string;
-  activate: (context: PluginActivationContext) => PluginActivationResult;
-}
-
-interface PluginActivationContext {
-  apiVersion: 2;
-  pluginId: string;
-  runtimePluginId?: string;
-  html: typeof import("lit").html;
-  svg: typeof import("lit").svg;
-}
-
-interface PluginActivationResult {
-  contributions: PluginContributions;
-}
-```
+普通模式在当前 agent 配置未安装时自动安装 Relay；从 **设置 → Pi 包** 移除会被记忆，不静默重装，可从“可用包”恢复。单独禁用中继插件只隐藏标签，不移除代理资源。管理嵌入的 `relay` 与 `relay-runner` 模板同步继续限定在授权工作区，不改变普通启动的技能文件。
 
-Example:
-
-```js
-export default {
-  apiVersion: 2,
-  name: "My Plugin",
-  activate: ({ pluginId, html }) => ({
-    contributions: {
-      actions: [],
-      workspacePanels: [],
-      workspaceLabels: [],
-    },
-  }),
-};
-```
+<a id="workflows"></a>
+### 工作流（Workflows）
 
-`activate()` is called once when the UI loads the plugin. Keep it cheap: define contributions there, but move expensive or async work into actions, custom elements, or explicit user interactions.
+Workflows 随包提供 Pi 工作流提示词和工作树操作。普通 profile 缺少默认包时自动安装，用户移除会被记忆，可从“可用包”恢复；禁用浏览器插件不移除已安装的 Pi 提示词资源。
 
-Browser API v2 is a deliberate compatibility break. PI WEB rejects browser API v1 modules instead of silently adapting them. Migrate by setting `apiVersion: 2`, using `pluginId` for the stable package/provider identity, and using `runtimePluginId` when a host-qualified contribution id is required. The former `@chainingintention/pi-web-cn/plugin-api/unstable` path is no longer exported; rely on the documented stable helpers instead.
+工作树操作选择 base 与用途后，由目标机器重验项目、工作区和 Git base 再派发；仅在普通模式及所需能力可用时提供。创建工作树、发布会话与打开页面是独立结果，派发结果不确定或导航失败时不自动重试，先查看目标机器已有结果，避免重复工作树。实现示例见 [Workflows 包](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/tree/main/pi-packages/workflows)。
 
-The plugin id comes from `package.json`, not from the JavaScript module. Contribution ids are local to the plugin and PI WEB qualifies them internally as:
+### 试用 Captain's Log
 
-```text
-<plugin-id>:<local-contribution-id>
-```
+Captain's Log 是可选示例，将会话最近的助手回复改写为海盗风格简报，演示浏览器面板、后端和 Pi 配套扩展协作。
 
-For example, plugin `info` with action `workspace.show-path` becomes `info:workspace.show-path`.
+1. 在目标机器的 **设置 → Pi 包 → 可用包** 安装 **船长日志**。
+2. 在 **设置 → PI WEB 插件** 启用它。
+3. 安全时重启目标机器会话守护进程，再刷新浏览器。
+4. 选择会话，打开“船长日志”，点击“让船长来讲述”。
 
-## Contributions
+它随主包预构建发布，**默认不安装、不启用**，无需现场编译。读取源回复但不修改源会话，另建海盗会话；需要模型凭据，源文本会发给海盗会话的模型提供器，可能产生模型费用。已有结果会保存。守护进程重启后，可从“会话”打开已有海盗会话继续上下文。
 
-`activate()` returns a `contributions` object with any combination of these arrays:
+详见[船长日志使用指南](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/pi-packages/captains-log/docs/usage.md)。
 
-```ts
-interface PluginContributions {
-  actions?: PluginAction[];
-  workspacePanels?: WorkspacePanelContribution[];
-  workspaceLabels?: WorkspaceLabelContribution[];
-}
-```
+<a id="pi-extension-dialogs"></a>
+## Pi 扩展对话框
 
-### Actions
-
-Actions appear in the action palette. They can inspect app state and call UI/runtime helpers.
-
-```js
-actions: [
-  {
-    id: "copy-diagnostics",
-    title: "Copy PI WEB Diagnostics",
-    description: "Copy version, installation, and status details for this machine",
-    group: "Info",
-    run: async (context) => {
-      const version = context.state.piWebStatus?.components.web.runtimeVersion ?? "unknown";
-      await navigator.clipboard.writeText(`PI WEB ${version}`);
-    },
-  },
-]
-```
+Pi 扩展可请求确认、选择或文本输入；问题以内联方式展示，包括会话启动和工具等待阶段。刷新后仍可回答，多标签页最先回答生效。
 
-Action type:
+有效期限取扩展超时和[宿主超时](https://pi-web.dev/config#extension-dialogs)中较早者。中止工作或替换运行时关闭相关问题。已回答卡片属于浏览器本地状态，不保证刷新后保留。新会话尚在创建时刷新可临时丢失卡片，但守护进程中的问题仍有期限。
 
-```ts
-interface PluginAction {
-  id: string;
-  title: string;
-  description?: string;
-  shortcut?: string;
-  group?: string;
-  enabled?: (context: PluginRuntimeContext) => boolean;
-  disabledReason?: (context: PluginRuntimeContext) => string | undefined;
-  run: (context: PluginRuntimeContext) => void | Promise<void>;
-}
-```
+仅支持这三种对话框，不支持自定义编辑器或组件等其他 Pi UI；不要因为 `hasUI` 为真就假定所有 UI 可用。
 
-If an action is disabled and returns `disabledReason`, PI WEB can keep it visible in the action palette with that explanation instead of hiding it.
+<a id="agent-development"></a>
+## 代理开发
 
-Stable runtime context fields:
+给代理具体目标、数据来源及允许的动作：
 
-```ts
-interface PluginRuntimeContext {
-  state: {
-    selectedMachine?: PluginMachine;
-    selectedWorkspace?: Workspace;
-    selectedSession?: unknown;
-    piWebStatus?: PiWebStatusResponse;
-  };
-  prompt: PluginPromptEditor;
-  openActionPalette: () => void;
-  focusPrompt: () => void;
-  addProject: () => void | Promise<void>;
-  configureAuth: () => void | Promise<void>;
-  logoutAuth: () => void | Promise<void>;
-  selectWorkspaceTool: (tool: QualifiedContributionId) => void;
-  openTerminal: (options?: { terminalId?: string }) => void;
-  refreshFiles: () => void | Promise<void>;
-  refreshGit: () => void | Promise<void>;
-  checkForPiWebUpdates?: () => void | Promise<void>;
-  startSession: () => void | Promise<void>;
-  archiveSession: () => void | Promise<void>;
-  stopActiveWork: () => void | Promise<void>;
-}
+```text
+为此项目创建 PI WEB 插件。
+目标：<描述工作流和预期界面>。
+先读 https://pi-web.dev/plugins.md，再按当前安装的 PI WEB 版本
+查阅公开契约与示例。
+只使用受支持的插件 API，不修改 PI WEB，不调用私有路由。
+说明安装、权限或模型使用情况，以及刷新方式。
+验证行为，包括失败和清理。
 ```
 
-Notes:
+### 实现入口
 
-- `state` is a snapshot of current UI state when actions are built.
-- The stable state fields are `state.selectedMachine`, `state.selectedWorkspace`, `state.selectedSession`, and `state.piWebStatus`. `state.selectedMachine` identifies the currently selected machine. `state.piWebStatus` describes the currently selected machine's PI WEB runtime, or the gateway/local runtime when the local machine is selected.
-- Other `state` fields may exist at runtime, but they are private PI WEB internals that may graduate into stable helpers, change shape, or disappear.
-- `enabled` is evaluated when the action palette asks for actions.
-- `selectWorkspaceTool()` expects a qualified panel id such as `my-plugin:workspace.info`.
-- `openTerminal()` switches to the built-in terminal panel. Pass `{ terminalId }` to deep-link to a specific terminal.
-- Only fields documented here and declared in `plugin-api.d.ts` are stable public browser plugin API. Runtime-only fields and private HTTP routes are not compatibility surfaces.
+从符合目标的最小示例开始。以下源码链接跟随 `main`；对发布版开发时，**使用对应标签或已安装的公开声明**。
 
-### Prompt editor API
-
-The `prompt` helper on `PluginRuntimeContext` and `WorkspacePanelContext` provides stable access to the chat prompt editor:
-
-| Method | Description |
+| 需求 | 入口 |
 | --- | --- |
-| `insertText(text)` | Insert text at cursor position. When text is selected, replaces the selection. Focuses the editor first if not focused. |
-| `getText()` | Returns the full prompt text. |
-| `getSelection()` | Returns `{ start, end, text }` if text is selected, or `null`. |
-
-Usage:
-
-```js
-// Insert text at the cursor (e.g. a file mention)
-context.prompt.insertText("@file.txt");
-
-// Read the current prompt and selection
-const text = context.prompt.getText();
-const selection = context.prompt.getSelection(); // { start, end, text } | null
-```
-
-Use `focusPrompt()` on `PluginRuntimeContext` to move focus to the prompt editor. Workspace panels can call `context.prompt.insertText()` from explicit user interactions such as button clicks; panel contexts target the currently selected session's mounted prompt editor.
-
-#### Keyboard shortcuts
-
-- App-level keyboard shortcuts must be attached to actions. PI WEB does not support standalone plugin keyboard commands; contribute an action first, then add a `shortcut` if it needs a keybinding.
-- `shortcut` is the action's default keybinding. It is displayed in the action palette and handled by the global shortcut dispatcher when the action is enabled.
-- Use modified shortcuts such as `mod+shift+p`; plain letter shortcuts are intentionally ignored so normal typing is never captured.
-- Future PI WEB versions may allow users to override or disable action shortcuts by action id, so plugins should treat `shortcut` as a default rather than a guaranteed final binding.
-- Choose shortcuts carefully to avoid conflicts. There is no user-facing shortcut override or conflict resolver yet.
-- Local text input, terminal input, list navigation, and dialog keys such as Enter, Escape, and arrow keys do not need to be plugin actions unless they are app-level commands.
-
-### Workspace panels
-
-Workspace panels add tools next to built-in workspace tools. They render inside the workspace side panel on desktop and as mobile tabs on smaller screens.
-
-```js
-workspacePanels: [
-  {
-    id: "workspace.info",
-    title: "Info",
-    icon: svg`
-      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-        <circle cx="12" cy="12" r="9"></circle>
-        <path d="M12 10v6"></path>
-        <path d="M12 7h.01"></path>
-      </svg>
-    `,
-    order: 100,
-    visible: ({ workspace }) => workspace.isGitRepo,
-    render: ({ workspace }) => html`
-      <section class="toolbar"><strong>Info</strong></section>
-      <section class="viewer">
-        <p class="muted">${workspace.label}</p>
-        <p class="muted">${workspace.path}</p>
-      </section>
-    `,
-  },
-]
-```
-
-Panel type:
-
-```ts
-interface WorkspacePanelContribution {
-  id: string;
-  title: string;
-  icon?: TemplateResult;
-  order?: number;
-  visible?: (context: WorkspacePanelContext) => boolean;
-  badge?: (context: WorkspacePanelContext) => string | number | TemplateResult | undefined;
-  render: (context: WorkspacePanelContext) => TemplateResult;
-}
-
-interface WorkspacePanelContext {
-  machine: PluginMachine;
-  workspace: Workspace;
-  state?: PluginRuntimeState;
-  files: {
-    readFile(path: string): Promise<FileContentResponse>;
-    listFiles(path: string): Promise<FileTreeResponse>;
-    writeFile(path: string, content: string | Uint8Array, options?: WriteWorkspaceFileOptions): Promise<WriteWorkspaceFileResponse>;
-    deleteFile(path: string): Promise<DeleteWorkspaceFileResponse>;
-    moveFile(fromPath: string, toPath: string, options?: MoveWorkspaceFileOptions): Promise<MoveWorkspaceFileResponse>;
-  };
-  prompt: PluginPromptEditor;
-  terminal: {
-    open(options?: { terminalId?: string }): void;
-    runCommand(input: {
-      title: string;
-      command: string;
-      metadata?: Record<string, string>;
-      open?: boolean;
-    }): Promise<TerminalCommandRunHandle>;
-  };
-  host: {
-    requestRender(): void;
-  };
-}
-```
-
-`icon` is optional and is used in the compact mobile tab bar. Prefer an SVG rendered with the `svg` helper from `PluginActivationContext`; use `currentColor` so PI WEB themes can style it. If `icon` is omitted, mobile tabs fall back to initials from the panel title, or to the full title when initials collide.
-
-`machine`, `workspace`, `files`, `prompt`, `terminal`, and `host` are documented as stable for panel callbacks. The `files` helper supports `readFile`, `listFiles`, `writeFile`, `deleteFile`, and `moveFile` — see [Reading workspace files](#reading-workspace-files), [Listing workspace files](#listing-workspace-files), and [Writing workspace files](#writing-workspace-files). The `prompt` helper supports panel interactions that insert workspace context into the current prompt — see [Prompt editor API](#prompt-editor-api). Use `terminal.open()` to switch to the built-in terminal panel; pass `{ terminalId }` to deep-link to a specific terminal. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate panel callbacks such as `badge`, `visible`, or `render`.
-
-For compatibility, PI WEB still provides the old `context.openTerminal()` workspace-panel helper at runtime. It is deprecated, intentionally omitted from the public TypeScript declarations, and planned for removal in v2. Existing JavaScript plugins keep working, while typed plugins should migrate to `context.terminal.open()`.
-
-Useful workspace and machine shapes:
-
-```ts
-interface PluginMachine {
-  id: string;
-  name: string;
-  kind: "local" | "remote";
-}
-
-interface Workspace {
-  id: string;
-  projectId: string;
-  path: string;
-  label: string;
-  branch?: string;
-  isMain: boolean;
-  isGitRepo: boolean;
-  isGitWorktree: boolean;
-}
-```
-
-`machine.id` is included in panel contexts so plugins can keep caches machine-scoped. Do not infer the selected machine from global browser state.
-
-Use existing classes such as `toolbar`, `viewer`, `empty`, and `muted` for panel content when possible. Do not assume a panel owns the whole page; keep layout contained.
+| 浏览器贡献与帮助方法 | [plugin-api.ts](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/src/plugin-api.ts)，公开为 `@chainingintention/pi-web-cn/plugin-api` |
+| 服务端生命周期、对等入口、提供器与宿主能力 | [server-plugin-api.ts](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/src/server-plugin-api.ts)，公开为 `@chainingintention/pi-web-cn/server-plugin-api` |
+| 小型浏览器插件 | [信息](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/tree/main/pi-web-plugins/info) |
+| 独立浏览器/服务端包 | [工作区提供器示例](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/tree/main/examples/workspace-provider-plugin) |
+| 生产工作区提供器与配套 UI | [Git](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/tree/main/pi-web-plugins/git) |
+| 已托管会话、实时更新与 Pi 配套扩展 | [Captain's Log](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/tree/main/pi-packages/captains-log) |
+| 简单初始提示词工作流 | [工作区审查示例](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/tree/main/examples/session-bridge-plugin) |
+| 发现规则与诊断 | [插件目录](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/src/server/piWebPluginCatalog.ts) |
 
-### Workspace labels
+当前浏览器与服务端契约均为 **API v5**；宿主继续支持浏览器 **API v4** 和服务端 **API v3**，旧类型名兼容保留。catalog、作用域 backend 及 v5 贡献需使用对应 v5 入口，不将新功能直接塞进旧版本贡献。公开源码契约和已安装声明是签名、验证、限制与生命周期的依据。
 
-Workspace labels add compact inline metadata wherever PI WEB displays a workspace label: workspace list, workspace panel header, and status bar.
+- 在 `package.json` 的 `piWeb.plugins` 声明入口，参考独立示例的打包方式；同一包可含多个入口。
+- 仅使用公开包入口，内部路由、服务及 `dist/**` 导入不是受支持 API。
+- `browserRoot` 尽量窄，里面所有内容都对浏览器公开。包含所需依赖与资产，秘密放在之外。安装插件包限制为 **4,096** 项、**16 MiB**，不计 `.git`/`node_modules`。
+- 机器/工作区操作使用宿主帮助方法，插件资产使用模块相对 URL，不硬编码应用路径。
+- 面板没有重新挂载时也可能重复渲染。自己管理异步状态，组件生命周期清理连接、计时器与监听器。
+- 工作区发现与会话支持功能分离，代理行为放在 Pi 配套扩展，而不是导入宿主内部模块。
 
-Use them for short facts like project environment, local URL, branch status, container name, or health state.
+<a id="trust-and-recovery"></a>
+## 信任与恢复
 
-```js
-workspaceLabels: [
-  {
-    id: "dev-url",
-    order: 10,
-    visible: ({ workspace }) => workspace.path.includes("my-app"),
-    items: () => [{
-      type: "link",
-      text: "web:5173",
-      href: "http://localhost:5173",
-      title: "Open dev server",
-      target: "_blank",
-    }],
-  },
-]
-```
-
-Label contribution type:
-
-```ts
-interface WorkspaceLabelContribution {
-  id: string;
-  order?: number;
-  visible?: (context: WorkspaceLabelContext) => boolean;
-  items: (context: WorkspaceLabelContext) => WorkspaceLabelItem[];
-}
-
-interface WorkspaceLabelContext {
-  machine: PluginMachine;
-  workspace: Workspace;
-  state?: PluginRuntimeState;
-  files: {
-    readFile(path: string): Promise<FileContentResponse>;
-    listFiles(path: string): Promise<FileTreeResponse>;
-    writeFile(path: string, content: string | Uint8Array, options?: WriteWorkspaceFileOptions): Promise<WriteWorkspaceFileResponse>;
-    deleteFile(path: string): Promise<DeleteWorkspaceFileResponse>;
-    moveFile(fromPath: string, toPath: string, options?: MoveWorkspaceFileOptions): Promise<MoveWorkspaceFileResponse>;
-  };
-  host: {
-    requestRender(): void;
-  };
-}
-```
-
-`machine`, `workspace`, `files`, and `host` are documented as stable for label callbacks. The `files` helper supports `readFile`, `listFiles`, `writeFile`, `deleteFile`, and `moveFile` — see [Reading workspace files](#reading-workspace-files), [Listing workspace files](#listing-workspace-files), and [Writing workspace files](#writing-workspace-files). Include `machine.id` in any label caches that depend on workspace data. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate label `visible` or `items` callbacks.
+**仅安装可信插件。** 浏览器入口在页面内运行；服务端入口在守护进程内使用其文件系统、环境及进程权限，没有独立沙箱。阻塞或故障服务端代码可影响同一守护进程所有会话；超时只能帮助配合取消的工作，不能停止阻塞代码。管理嵌入继续保留独立认证、授权资源、能力与审计边界，不向插件放开普通模式能力。
 
-Items are sorted by `order` and then id. Return an empty array to render nothing. Keep callbacks synchronous and lightweight; start async work from the callback, return cached items, then call `host.requestRender()` when the cache changes.
+先在目标机器 **设置 → PI WEB 插件** 检查安装、启用、兼容和激活状态。浏览器失败看控制台，服务端失败在目标机器执行 `pi-web logs`。过期或需重启状态通常需要重启守护进程后刷新浏览器。
 
-#### Text items
-
-```js
-{ type: "text", text: "staging", title: "Staging workspace" }
-```
+UI 无法恢复时，在目标机器直接运行：
 
-#### Link items
-
-```js
-{
-  type: "link",
-  text: "web:5173",
-  href: "http://localhost:5173",
-  title: "Open dev server",
-  target: "_blank"
-}
+```sh
+pi-web plugins disable <plugin-id> --restart
+pi-web plugins safe-start show
+pi-web plugins safe-start set bundled-only --restart
+pi-web plugins safe-start set none --restart
+pi-web plugins safe-start clear --restart
 ```
 
-PI WEB renders the anchor and adds safe defaults such as `rel="noopener noreferrer"` for `_blank` links. `javascript:` and `data:` links are rendered as plain text instead of links.
-
-#### Render items
-
-Use render items when a label contribution needs custom UI, async data, or caching. Render items should stay compact and inline.
-
-```js
-class MyWorkspaceBadge extends HTMLElement {
-  set workspace(value) {
-    this._workspace = value;
-    this.textContent = value?.branch === "main" ? "main" : "branch";
-  }
-}
-
-if (!customElements.get("my-workspace-badge")) {
-  customElements.define("my-workspace-badge", MyWorkspaceBadge);
-}
-
-export default {
-  apiVersion: 2,
-  name: "My Plugin",
-  activate: ({ html }) => ({
-    contributions: {
-      workspaceLabels: [
-        {
-          id: "badge",
-          order: 10,
-          items: ({ workspace }) => [{
-            type: "render",
-            render: () => html`<my-workspace-badge .workspace=${workspace}></my-workspace-badge>`,
-          }],
-        },
-      ],
-    },
-  }),
-};
-```
-
-## Reading workspace files
-
-Workspace panels and workspace labels can read files through the documented `files` helper. PI WEB binds this helper to the callback's machine and workspace, so it works the same for local and federated machines.
-
-```js
-workspacePanels: [
-  {
-    id: "workspace.env",
-    title: "Env",
-    render: ({ files }) => html`
-      <my-env-viewer .files=${files}></my-env-viewer>
-    `,
-  },
-]
-
-class MyEnvViewer extends HTMLElement {
-  set files(value) {
-    this._files = value;
-    void this.load();
-  }
-
-  async load() {
-    try {
-      const file = await this._files.readFile(".env.example");
-      this.textContent = file.binary ? "Binary file" : file.content;
-    } catch (error) {
-      this.textContent = error instanceof Error ? error.message : String(error);
-    }
-  }
-}
-```
-
-Labels should use the same helper through a plugin-owned cache because `items()` itself must return synchronously:
-
-```js
-const envCache = new Map();
-
-function envKey(machine, workspace) {
-  return `${machine.id}:${workspace.id}:.env.local`;
-}
-
-function loadEnvLabel(context) {
-  const key = envKey(context.machine, context.workspace);
-  const cached = envCache.get(key);
-  if (cached !== undefined) return cached;
-
-  const pending = { status: "loading", label: undefined };
-  envCache.set(key, pending);
-  context.files.readFile(".env.local")
-    .then((file) => {
-      pending.status = "ready";
-      pending.label = file.content.match(/^DEV_URL=(.+)$/m)?.[1];
-      context.host.requestRender();
-    })
-    .catch(() => {
-      pending.status = "missing";
-      context.host.requestRender();
-    });
-  return pending;
-}
-
-workspaceLabels: [
-  {
-    id: "dev-url",
-    items: (context) => {
-      const cached = loadEnvLabel(context);
-      return cached.label === undefined ? [] : [{
-        type: "link",
-        text: cached.label,
-        href: cached.label,
-        target: "_blank",
-      }];
-    },
-  },
-]
-```
-
-The file response includes fields such as `path`, `content`, `truncated`, and `binary`. Be careful with sensitive files such as `.env`: plugins are trusted browser code, and file contents are exposed to the plugin.
-
-## Listing workspace files
-
-`files.listFiles(path)` lists the entries of a workspace directory. Pass `""` for the workspace root. Like `readFile`, PI WEB binds the call to the callback's machine and workspace, so it works the same for local and federated machines.
-
-```js
-const listing = await context.files.listFiles("src");
-for (const entry of listing.entries) {
-  // entry: { name, path, type: "file" | "directory" | "symlink", size?, modifiedAt? }
-}
-```
-
-The listing response includes `path`, `entries`, `scannedAt`, and `truncated`. When `truncated` is true, the server cut the listing short, so treat the entries as partial.
-
-`listFiles` rejects when the directory does not exist or cannot be read, matching `readFile` error behavior. When a directory is optional, catch the error and treat it as an empty listing:
-
-```js
-async function listSubdirectoryNames(context, path) {
-  try {
-    const listing = await context.files.listFiles(path);
-    return listing.entries.filter((entry) => entry.type === "directory").map((entry) => entry.name);
-  } catch {
-    return [];
-  }
-}
-```
-
-## Writing, deleting, and moving workspace files
-
-Workspace panels and workspace labels can write, delete, and move files through the documented `files` helper. Like `readFile`, PI WEB binds these helpers to the callback's machine and workspace, so they work the same for local and federated machines.
-
-### Writing files
-
-```js
-workspacePanels: [
-  {
-    id: "workspace.generate",
-    title: "Generate",
-    render: ({ files }) => html`
-      <button @click=${async () => {
-        const result = await files.writeFile("output/result.txt", "Generated content\n");
-        console.log("Wrote", result.path, result.size, "bytes");
-      }}>Generate</button>
-    `,
-  },
-]
-```
-
-### Binary writes
-
-Pass a `Uint8Array` for binary content such as images:
-
-```js
-const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]);
-await files.writeFile("screenshots/thumb.png", png);
-```
-
-### Options
-
-`files.writeFile` accepts an optional third argument:
-
-- `createDirs` (default `true`): create intermediate directories, like `mkdir -p`.
-- `overwrite` (default `true`): overwrite existing files. Set to `false` to throw if the file already exists.
-
-```js
-// Create only — throw if the file already exists
-await files.writeFile("config/new-config.json", jsonContent, { overwrite: false });
-```
-
-### Deleting files
-
-`files.deleteFile` removes a workspace file. It is idempotent: deleting a file that does not exist returns `{ existed: false }` instead of throwing.
-
-```js
-const result = await files.deleteFile("temp/cache.json");
-console.log(result.existed ? "File deleted" : "File did not exist");
-```
-
-### Moving files
-
-`files.moveFile` renames or moves a file within the workspace, like `mv`. The default is safe: it will not overwrite an existing target file.
-
-```js
-// Rename a file
-await files.moveFile("old-name.txt", "new-name.txt");
-
-// Move into a subdirectory (creates intermediate dirs by default)
-await files.moveFile("file.txt", "archive/file.txt");
-
-// Overwrite an existing target
-await files.moveFile("incoming.txt", "current.txt", { overwrite: true });
-
-// Move without creating intermediate directories
-await files.moveFile("file.txt", "deep/nested/file.txt", { createDirs: false }); // throws if dirs don't exist
-```
-
-`files.moveFile` accepts an optional third argument:
-
-- `createDirs` (default `true`): create intermediate directories for the target path.
-- `overwrite` (default `false`): overwrite the target file if it exists. The default is safer than `writeFile` because moving is a more destructive operation.
-
-### Error handling
-
-All file mutations share the same safety layer:
-
-- `overwrite: false` on `writeFile` or existing target on `moveFile` (default) throws if the file already exists.
-- Path traversal (e.g., `../../etc/passwd`) is blocked by the workspace safety layer.
-- Writing to or moving to a path that is a directory returns an error.
-- Deleting a directory returns an error.
-- Intermediate directory creation with `createDirs: false` fails if the parent directory does not exist.
-
-After any mutation (`writeFile`, `deleteFile`, or `moveFile`), the File Explorer updates automatically. No explicit `refreshFiles()` call is needed from plugin code. For label and badge updates, call `context.host.requestRender()` if the UI should reflect the change.
-
-### Security
-
-Plugins are trusted browser code. File writes go through the same path safety validation as reads — paths are resolved and checked to stay inside the workspace root.
-
-## Running workspace terminal commands
-
-Workspace panels can start terminal commands through the documented `terminal` helper. Commands run in the current workspace on the panel's machine.
-
-```js
-render: ({ terminal }) => html`
-  <button @click=${() => terminal.runCommand({
-    title: "Build",
-    command: "npm run build",
-    open: true,
-    metadata: { "my-plugin.task": "build" },
-  })}>Build</button>
-`
-```
-
-Review command strings carefully. They are trusted shell commands executed in the workspace terminal.
-
-## Private and experimental PI WEB APIs
-
-PI WEB's `/api/...` HTTP and WebSocket routes and runtime-only fields are private implementation details. They exist because plugins are trusted browser code, and because some capabilities may be evaluated there before they are designed as stable helpers.
-
-The stable browser API is the documented helper surface and the type-only `@chainingintention/pi-web-cn/plugin-api` export. The stable server API is the separate type-only `@chainingintention/pi-web-cn/server-plugin-api` export. The former browser `plugin-api/unstable` entry is not part of API v2 and is no longer exported. Code that deliberately depends on another private runtime surface must keep that dependency local and expect to revisit it after PI WEB upgrades.
-
-## Async data and caching
-
-PI WEB does not provide a plugin cache/invalidation framework. Keep host callbacks cheap:
-
-- simple contributions should be synchronous and cheap;
-- expensive or async work should live inside the plugin;
-- custom elements in `type: "render"` label items or panels are a good place to own async loading;
-- dedupe async reads/commands and avoid unbounded polling;
-- clean up intervals/event listeners in custom elements' `disconnectedCallback()`.
-
-## Agent implementation checklist
-
-If you are an AI agent building or editing a PI WEB plugin, follow this checklist:
-
-1. Create or update a plugin folder with `package.json` and a JavaScript module such as `pi-web-plugin.js`.
-2. Use the single supported package metadata shape: `piWeb.plugins` array with `{ id, module, machineSpecific? }` entries.
-3. Default-export `{ apiVersion: 2, name, activate }` from a browser module. Server modules use server-plugin API v1.
-4. Return `{ contributions: { actions, workspacePanels, workspaceLabels } }` from `activate()`.
-5. Use ids matching `^[a-z][a-z0-9.-]*$`.
-6. Use the activation context's `html` function for Lit templates.
-7. Keep `activate()` synchronous and cheap; return contribution definitions only.
-8. Add actions for command-palette operations.
-9. Add workspace panels for larger workspace UI.
-10. Add workspace labels for compact inline metadata.
-11. Return arrays from workspace label `items()`; return an empty array to render nothing.
-12. Use documented context helpers first: `files`, `terminal`, `host.requestRender`, `workspace`, `machine`, `state.selectedWorkspace`, `state.selectedSession`, `state.piWebStatus`, and `prompt`.
-13. Do not fetch PI WEB `/api/...` endpoints directly unless you intentionally accept private API churn; prefer documented helpers such as the paired workspace `backend` bridge.
-14. Treat plugins as trusted code and avoid reading or displaying secrets unless intentional.
-15. After local edits, tell the user to hard reload the browser and check the console for plugin errors.
-
-## Troubleshooting
-
-Check discovery:
-
-```bash
-curl http://127.0.0.1:8504/pi-web-plugins/manifest.json
-```
-
-Check a plugin module:
-
-```bash
-curl http://127.0.0.1:8504/pi-web-plugins/my-plugin/pi-web-plugin.js
-```
+- **disable** 禁止指定可选插件在下次启动加载，拒绝禁用必需终端。
+- **bundled-only** 排除外部服务端插件，保留内置工具及必需终端。
+- **none** 不导入任何服务端插件；诊断和项目目录工作区仍可用，但终端与依赖终端的工作流不可用。
+- **clear** 修复或移除故障包后恢复普通启动。
 
-Common issues:
-
-- invalid plugin id or contribution id;
-- missing default export;
-- missing browser `apiVersion: 2`, `name`, or `activate` function;
-- missing `package.json` or incorrect `piWeb.plugins` metadata;
-- legacy shortcuts such as `piWeb.plugin`, string plugin entries, or no-`package.json` fallback;
-- duplicate plugin ids; later duplicates are skipped rather than renamed;
-- entry module path points outside the plugin root or file does not exist;
-- browser cache not refreshed after editing;
-- plugin directory is not under `~/.pi-web/plugins` or symlinked there;
-- plugin throws during module import, `activate()`, `visible()`, `enabled()`, `items()`, or `render()`; check the browser console.
+安全启动持久保留直到清除。`--restart` 仅在识别到安全的已安装服务操作时重启，否则给出手动指引；配置在尝试重启前持久保存。命令离线编辑配置，不导入插件代码。自定义配置加 `--config /path/to/config.json`。有效 JSON 中不支持的 `serverPlugins.safeStart` 形状/值按 `none` 失败关闭；通过 `show`、`set` 或 `clear` 修复。重启前检查活跃工作。