@jetcrab/pi-desk 1.1.1 → 1.1.5-dev

package/docs/pi-desk/README.md

@@ -0,0 +1,47 @@
+# Pi Desk 文档
+
+这里只说明 Pi Desk 相对原生 Pi 新增或不同的行为。Pi 的配置、模型、会话格式和扩展基础沿用官方资料，不在此重复维护。
+
+## 按任务查阅
+
+| 任务                                    | 资料                                                      |
+| --------------------------------------- | --------------------------------------------------------- |
+| 让 AI 管理 Pi Desk、安装或重载插件      | [管理命令](./commands.md)                                 |
+| 开发 Pi Desk 应用、面板、通知或消息视图 | [插件开发](./plugins.md)，含可直接加载的最小示例          |
+| 安装、启动或升级 Pi Desk                | [官网：安装与启动](https://pidesk.dev/docs/installation/) |
+| 配置模型并完成第一次对话                | [官网：开始对话](https://pidesk.dev/docs/quickstart/)     |
+| 从手机或其他设备访问同一服务            | [官网：远程访问](https://pidesk.dev/docs/devices/)        |
+| 使用 Docker 部署、升级或备份            | [官网：Docker](https://pidesk.dev/docs/docker/)           |
+| 排查启动、模型、会话或插件问题          | [官网：常见问题](https://pidesk.dev/docs/faq/)            |
+
+本目录及示例随当前 Pi Desk 版本分发；官网链接需要联网。已有官网说明先通过链接复用，不在本目录另存一份。
+
+## 需要原生 Pi 能力时
+
+优先读取会话系统提示所指向的已安装 Pi 文档和示例；下表路径相对那个 Pi 文档目录，不是当前工作目录或本目录。在线入口为 [Pi 官方文档](https://pi.dev/docs/latest)，版本差异以实际安装版本的文档和类型为准。
+
+| 主题                          | Pi 官方资料                                                   |
+| ----------------------------- | ------------------------------------------------------------- |
+| 配置作用域、设置与环境变量    | `configuration.md`、`settings.md`、`environment-variables.md` |
+| 模型、服务商与自定义 Provider | `models.md`、`providers.md`、`custom-provider.md`             |
+| 会话历史、上下文与压缩        | `sessions.md`、`session-format.md`、`compaction.md`           |
+| 原生工具、命令、事件与包      | `extensions.md`、`packages.md`                                |
+| Skills、提示模板与终端主题    | `skills.md`、`prompt-templates.md`、`themes.md`               |
+| MCP 与 codemode               | `mcp.md`、`codemode.md`                                       |
+| 嵌入 Pi、进程控制与终端 UI    | `sdk.md`、`rpc.md`、`json.md`、`tui.md`                       |
+| 原生权限与项目信任            | `security.md`                                                 |
+
+Pi Desk 的工作会话、界面操作和宿主管理与原生 Pi 命令不一定一一对应；这些差异归入下面的增量主题。
+
+## 待补充主题
+
+以下文件尚未创建，当前使用上面的已有资料。补充时只写右列范围，完成后加入任务导航。
+
+| 文件                 | 只补充的 Pi Desk 内容                                                                          |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `usage.md`           | 工作会话、固定与并排、界面分支/Fork、消息队列、文件/Git 和终端操作；多设备共享与本地状态的区别 |
+| `configuration.md`   | 宿主设置、项目默认模型、能力模式与配置生效范围；哪些变更需要重载                               |
+| `running.md`         | 主程序启动、桌面托管、服务与访问设备的区别，日志、数据位置、更新和重启影响                     |
+| `troubleshooting.md` | 按宿主启动、连接、模型接入、插件加载分层排查，定位日志与恢复入口                               |
+
+插件开发继续维护在 `plugins.md`；Session、通知和消息视图示例按实际需要加入 `examples/`，不预建空示例目录。

package/docs/pi-desk/commands.md

@@ -0,0 +1,76 @@
+# Pi Desk 管理命令
+
+本页说明宿主 `pidesk` 工具及结果语义；其他使用和开发资料见[文档入口](./README.md)。
+
+## 调用管理工具
+
+`pidesk` 是宿主 API 工具，不是任意 Shell。参数是命令 token 数组，不包含 `pidesk` 前缀，也不解析管道、重定向或 Shell 表达式：
+
+```json
+{ "args": ["--help"] }
+```
+
+当前命令以 `pidesk --help` 为准，各级命令均支持 `--help`，例如 `{ "args": ["plugins", "install", "--help"] }`。
+
+| 查询                  | args                                                     |
+| --------------------- | -------------------------------------------------------- |
+| 宿主版本              | `["--version"]`                                          |
+| 当前宿主环境与目录    | `["info"]`                                               |
+| 插件清单与维护状态    | `["plugins", "list"]`                                    |
+| 按各插件渠道检查更新  | `["plugins", "list", "--check-updates"]`                 |
+| 只检查跟随 dev 的插件 | `["plugins", "list", "--check-updates", "--tag", "dev"]` |
+| 插件详情              | `["plugins", "show", "<name>", "--scope", "global"]`     |
+
+`info` 可取得当前 `agentDir`；下文 `<AgentDir>` 表示这个实际目录，不假定默认位置。管理入口只支持全局范围，不支持项目级管理。
+
+## 区分接纳与完成
+
+- `mode: sync`：本次执行已经结束，直接使用返回结果。
+- `mode: async`：操作已经接纳，尚未完成；宿主会把最终结果插入本会话并唤醒模型。没有独立工作时结束当前轮，等待最终通知，不轮询、不重复提交。
+- 工具报错表示请求失败；已接纳、等待加载或等待重启都不能报告成已生效。
+- 批量操作每批返回一条最终汇总，逐项区分成功、未接纳、失败和等待重启；某项失败不代表其余项失败。
+
+## 安装、更新与重载
+
+| 操作                   | args                                                                          |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| 安装、更新或重装       | `["plugins", "install", "<name>", "--scope", "global"]`                       |
+| 批量安装或更新         | `["plugins", "install", "<name-1>", "<name-2>", "--scope", "global"]`         |
+| 安装并跟随 dev         | `["plugins", "install", "<name>", "--scope", "global", "--tag", "dev"]`       |
+| 安装指定 npm 版本      | `["plugins", "install", "<name>", "--scope", "global", "--version", "1.2.3"]` |
+| 重载已安装插件当前代码 | `["plugins", "reload", "<name-1>", "<name-2>", "--scope", "global"]`          |
+| 卸载包来源             | `["plugins", "remove", "<name-1>", "<name-2>", "--scope", "global"]`          |
+
+`install` 包含首次安装、更新和重装；目标版本已安装也会重装。`reload` 只重新加载本机现有码，不下载、不修改版本或渠道、不重启宿主，也不重载已有 Pi 会话；它不接受 `--version` 或 `--tag`。
+
+### 本地插件
+
+源码放在 `<AgentDir>/extensions/<name>/`。首次接入用 `install`；修改已安装插件后用 `reload`。有浏览器构建入口时先完成必要编译；原生 TypeScript 与 Pi Desk Node Entry 可由宿主直接加载，不必为本地验证发布 npm 或生成安装包。
+
+命令使用清单或固定目录中的名字，不传自定义路径；单文件扩展使用清单中的名字。本地来源不接受版本或渠道。同名来源冲突时先确认目标，不猜测。
+
+### npm 插件
+
+使用完整 npm 包名，例如 `@example/plugin`，不把版本拼在名字里。多个插件共用一次命令选择的标签或版本。
+
+- 省略版本和标签：新插件默认 `latest`，已有插件沿保存的更新渠道。
+- `--tag dev`：安装该标签指向的版本，并保存后续跟随渠道。
+- `--version 1.2.3`：只指定本次完整版本，不改变已有渠道；与 `--tag` 互斥，不从版本后缀猜渠道。
+- `list --check-updates` 不安装；附加 `--tag dev` 只筛选跟随 dev 的插件，不改变渠道。标签缺失或查询失败报告对应项错误，不回退 `latest`。
+- 只调整渠道而不安装：在插件管理界面多选后使用“设置渠道”。
+
+包文件与 Pi `settings.json` 由官方包管理器维护，不手动覆盖安装目录或包声明。`remove` 只卸载管理入口支持的包来源，不附带业务数据清理；裸扩展卸载不在此命令能力中，不以删除源码或新增禁用规则代替包卸载。
+
+## 让已有会话采用当前配置
+
+```json
+{ "args": ["session", "reload"] }
+```
+
+等同输入框“更多 → 重载 Pi 配置”：保留聊天历史与当前分支，重新加载 Pi 配置、Skills 和本机已安装插件的当前代码，不下载新版本。需要 npm 新版时先 `plugins install`，再按用户需要重载目标会话。
+
+接纳后结束当前轮；宿主等本会话完全空闲后重载，再通知并唤醒本会话。重载可能重建插件内存状态、使缓存失效，配置和工具声明变化也可能影响提示词缓存。
+
+插件管理只等待目标来源必要的在途调用，不冻结常规聊天。完成通知表示包和宿主能力已应用；新建会话使用最新工具配置，已有原生 Pi 会话不自动重载。Node/Browser 替换会重新挂载目标插件界面，旧调用可能失效；结果未知的副作用请求不自动重发。
+
+需要重启时按插件管理界面的维护流程处理，以最终结果为准。

package/docs/pi-desk/examples/local-application/browser/application.js

@@ -0,0 +1,106 @@
+import { createElement as h } from 'react'
+import { createRoot } from 'react-dom/client'
+import {
+  PluginButton,
+  PluginErrorBoundary,
+  PluginHostProvider,
+  PluginLoadingState,
+  PluginSection,
+  PluginSurface
+} from '@jetcrab/pi-desk-sdk/react/base'
+
+const application = {
+  mount({ container, host, signal }) {
+    const root = createRoot(container)
+    let disposed = false
+    let loading = false
+    let error = null
+    let message = null
+
+    async function readStatus() {
+      if (disposed || signal.aborted || loading) return
+      loading = true
+      error = null
+      render()
+
+      try {
+        const result = await host.piDesk.invokeGlobal('status-get', {})
+        // 视图关闭不取消服务端方法；旧视图不能使用迟到结果。
+        if (disposed || signal.aborted) return
+        if (typeof result.message !== 'string') {
+          throw new Error('服务信息格式不正确')
+        }
+        message = result.message
+      } catch (cause) {
+        if (disposed || signal.aborted) return
+        console.error('[本地应用示例] 读取服务信息失败', cause)
+        error = cause instanceof Error ? cause.message : String(cause)
+      } finally {
+        if (!disposed && !signal.aborted) {
+          loading = false
+          render()
+        }
+      }
+    }
+
+    function render() {
+      root.render(
+        h(
+          PluginHostProvider,
+          { host },
+          h(
+            PluginErrorBoundary,
+            null,
+            h(
+              PluginSurface,
+              {
+                style: {
+                  width: 'min(24rem, calc(100vw - 2rem))',
+                  maxWidth: '100%',
+                  boxSizing: 'border-box',
+                  padding: '1rem',
+                  display: 'grid',
+                  gap: '1rem',
+                  overflowWrap: 'anywhere'
+                }
+              },
+              h(
+                PluginSection,
+                { title: '服务信息' },
+                h(
+                  PluginButton,
+                  {
+                    variant: 'primary',
+                    disabled: loading,
+                    onClick: () => void readStatus()
+                  },
+                  '读取服务信息'
+                )
+              ),
+              h(
+                PluginLoadingState,
+                {
+                  loading,
+                  error,
+                  loadingLabel: '正在读取…',
+                  retryLabel: '重试',
+                  onRetry: () => void readStatus()
+                },
+                message === null ? null : h('p', { role: 'status', style: { margin: 0 } }, message)
+              )
+            )
+          )
+        )
+      )
+    }
+
+    render()
+    return () => {
+      if (disposed) return
+      disposed = true
+      root.unmount()
+    }
+  }
+}
+
+export default application

package/docs/pi-desk/examples/local-application/browser/entry.js

@@ -0,0 +1,9 @@
+export default function registerApplication(plugin) {
+  plugin.registerContribution('application', 'status', {
+    label: '本地应用示例',
+    title: '本地应用示例',
+    chrome: 'host',
+    icon: { type: 'builtin', name: 'plugin' },
+    load: () => import('./application.js').then((module) => module.default)
+  })
+}

package/docs/pi-desk/examples/local-application/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "local-application",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "piDesk": {
+    "entry": "./pi-desk.ts"
+  }
+}

package/docs/pi-desk/examples/local-application/pi-desk.ts

@@ -0,0 +1,11 @@
+import type { PiDeskPluginDefinition } from '@jetcrab/pi-desk-sdk/entry'
+
+const definition: PiDeskPluginDefinition = {
+  name: 'local-application',
+  setup(plugin) {
+    plugin.registerMethod('status-get', async () => ({ message: '插件服务已连接' }))
+    plugin.registerBrowserEntry('./browser/entry.js')
+  }
+}
+
+export default definition

package/docs/pi-desk/plugins.md

@@ -0,0 +1,119 @@
+# Pi Desk 插件
+
+管理操作见[管理命令](./commands.md)。Tool、Command、Pi Event 与 TUI 使用原生 Pi API；Pi Desk SDK 只补充宿主服务、会话通信和 Web 界面。
+
+## 选择运行位置
+
+| 运行位置        | 入口与能力                                                                     | 生命周期                                |
+| --------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
+| 原生 Pi         | Pi 包的扩展入口；Tool、Command、Event                                          | 当前 Pi 会话                            |
+| Pi Desk Global  | `package.json` 的 `piDesk.entry`；全局 Method、State、Push、通知、消息声明     | 服务进程中的插件实例                    |
+| Pi Desk Session | 原生扩展中 `bindSessionPlugin(pi, pluginName)`；会话 Method、State、Push、Task | 当前 AgentSession，分支数据随树导航重建 |
+| Browser Owner   | 轻量 Browser Entry；贡献注册、Push 与通知事件                                  | 当前浏览器页面中的插件实例              |
+| Browser View    | Contribution 的 `load()` → `{ mount }`                                         | 每次挂载，关闭或 Source 变化后释放      |
+
+同一个插件各入口使用同一稳定 `pluginName`；名字、方法、事件和 contributionName 使用 1～64 字符小写 kebab-case。Global 不依赖当前聊天窗口，Browser Owner 不代表后端任务 Owner。
+
+Session 精确绑定 `{ workId, sessionId, branchId }`。Source 来自 Target 或 `host.workSessions`，不自行拼装；旧 Source 返回 `409`，分支变化后重新查询。Application 的 `target.initialContext` 只是打开时的 Source/CWD，不是内部选择的权威状态。
+
+## 按需读类型
+
+系统提示提供当前 SDK 类型目录，其上一级是 SDK 根目录；从根目录 `package.json` 的 `exports` 找对应声明，不依赖仓库源码路径。常用类型文件相对 SDK 根目录如下：
+
+| 子入口                                  | 类型文件                                                                 | 使用时机                                                           |
+| --------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `/entry`                                | `dist/entry.d.ts`                                                        | `PiDeskPluginDefinition`、Node Host、Global Method、通知、消息声明 |
+| `/session`                              | `dist/session.d.ts`                                                      | `bindSessionPlugin`、Session Method、State、Push、Task             |
+| `/browser`                              | `dist/browser.d.ts`                                                      | Browser Factory、Contribution 定义、mount Target、Host 通信        |
+| `/react/base`                           | `dist/react-base.d.ts`，继续读其导出的 `react-ui.d.ts`、`react-log.d.ts` | 公共组件、Host Provider、ErrorBoundary、Hooks                      |
+| `/react/markdown`                       | `dist/react-markdown.d.ts`                                               | Markdown 消息界面                                                  |
+| `/errors`、`/settings`、`/capabilities` | 对应 `dist/*.d.ts`                                                       | 方法错误、共享地区设置、能力规则                                   |
+
+SDK 不重复定义原生 Pi Tool。只导入 Node 类型可用 `import type`，宿主 Jiti 会剥除类型；实际运行时导入 SDK 或其他 Node 包时，在该插件声明运行依赖，不借用另一插件的依赖。类型检查所需 SDK 可放开发依赖。
+
+## 最小本地应用
+
+四个文件组成一个可直接加载的本地演示，不独立发布：
+
+- [package.json](./examples/local-application/package.json)：`private: true`、ES Module、`piDesk.entry`，不需要安装依赖或编译。
+- [pi-desk.ts](./examples/local-application/pi-desk.ts)：普通对象定义一个 Global Method 并注册 Browser Entry。
+- [browser/entry.js](./examples/local-application/browser/entry.js)：同步注册应用元数据与动态 loader。
+- [browser/application.js](./examples/local-application/browser/application.js)：公共 React/UI、人工只读查询、加载与重试、mount/dispose。
+
+从本文所在目录取得示例文件，复制到 `pidesk info` 返回的 `<AgentDir>/extensions/local-application/`，保留层级。调用 `{ "args": ["plugins", "install", "local-application", "--scope", "global"] }`，等待最终通知后从应用入口打开“本地应用示例”，点击“读取服务信息”。修改后使用 `plugins reload local-application --scope global` 对应的 args。
+
+示例只查询一个真实 Global Method，不自动调用模型、写文件、访问外部网络或轮询。它没有原生 Pi 扩展，不添加空的 Native 入口。
+
+## Node 与会话能力
+
+Node Entry 默认导出普通 `PiDeskPluginDefinition` 对象即可，`definePiDeskPlugin()` 是可选包装。入口由宿主加载；异步初始化放 `async setup()`，不使用模块顶层 `await`。
+
+`registerBrowserEntry()` 最多一次，路径位于包内，文件名为 `entry.js`。无需自有资源时 `setup()` 不必返回清理；创建 Timer、Watcher、连接或子进程时返回 disposer，释放旧实例资源。Host 自动撤销注册；旧异步清理不得写入新实例。
+
+会话能力在真实原生扩展中绑定，不用 Node Global 冒充 Session：
+
+```ts
+import { bindSessionPlugin } from '@jetcrab/pi-desk-sdk/session'
+
+const plugin = bindSessionPlugin(pi, 'example-plugin') // pi 是原生 ExtensionAPI
+plugin.registerMethod('cwd-get', async (_input, context) => ({
+  cwd: context.extensionContext.cwd
+}))
+plugin.setState({ status: 'ready' })
+plugin.push('changed', {})
+```
+
+此处 `/session` 是运行时导入，插件需声明 SDK 运行依赖。Session State 仅当前会话内存，`setState()` 整体替换自身槽位，`null` 删除；不写 Pi JSONL。树导航从当前 `getBranch()` 重建分支数据，不重复注册会话方法。Task 用于报告真实后台任务，停止能力由任务 Owner 提供。
+
+Node `plugin.setState()` 则整体替换自身全局状态；Browser 通过 `host.globalState.getSnapshot()/subscribe()` 只读。两者不是同一槽位，均不得读写其他插件状态。宿主地区设置由 `host.settings.getSnapshot()/subscribe()` 只读，不另存权威副本。
+
+## Browser Entry 与懒界面
+
+Entry 默认导出普通同步函数即可；在函数返回前完成全部 `registerContribution(kind, name, definition)`。kind 支持 `application`、`composer-panel`、`settings-page`、`session-sidebar-tab`、`message-view`。Entry 只放元数据、loader、轻量页面状态和事件订阅；返回 disposer 清理自有订阅与资源。
+
+Entry 不静态引入 React、ReactDOM、UI、CSS 或大型实现，也不等网络或动态 import 后再注册。UI 放在 `load()` 的动态模块，导出 `{ mount({ container, target, host, signal }) }`；Lazy Module 顶层不启动副作用。
+
+浏览器资源只托管 Entry 目录内的 `.js` 模块图；相对 import 留在该目录内。宿主不托管独立 CSS、图片或字体。局部样式通过 Lazy JS 注入并限定自身容器，不修改全局 DOM 或依赖宿主内部目录。
+
+Lazy UI 可直接使用的 Host Runtime 白名单：
+
+```text
+react
+react/jsx-runtime
+react/jsx-dev-runtime
+react-dom
+react-dom/client
+@jetcrab/pi-desk-sdk/react/base
+@jetcrab/pi-desk-sdk/react/markdown
+```
+
+复用宿主 React 与 UI，不复制或打包第二套公共运行时。`/browser` 不在白名单中：普通函数无需包装；`copyBrowserText` 等 SDK Browser 运行函数需要构建时打入插件模块，不能原样留下裸 import。其他业务依赖也需构建为相对模块。无构建示例用 JS `createElement`；TSX、TypeScript 浏览器文件需要先编译为 JS。
+
+Application 使用 `chrome: 'host'` 让宿主负责 Dialog、标题、关闭、焦点、Escape、Loading/Error 和视口约束；内容自然决定尺寸，不替换工作台。React mount 使用 `createRoot`、`PluginHostProvider`、`PluginErrorBoundary` 和公共控件；disposer 调用 `root.unmount()`，释放自建 Listener、Timer、Observer、Object URL。宿主先 abort `signal`，迟到结果必须忽略。
+
+界面继承宿主明暗主题与字号，布局使用 `rem`、合理内边距和自身滚动；窄屏与触控可用，不以裁切或只靠 hover 隐藏必要操作。按钮、表单、加载/错误/重试优先复用 `/react/base`；需要 Markdown 时才加载 `/react/markdown`。
+
+## 通信、通知与后台
+
+Browser Method 示例：
+
+```ts
+const status = await host.piDesk.invokeGlobal('status-get', {})
+const cwd = await host.piDesk.invokeSession(source, 'cwd-get', {})
+await host.pi.prompt(source, { mode: 'auto', text: '请总结当前任务' })
+```
+
+这些调用限定当前插件或完整 Source。Method 输入/输出为 JSON Object，各不超过 2MB；Push 与状态槽位各不超过 64KB。`host.pi.prompt()` 返回接纳用的 `tempId`，不是模型完成或 durable 消息；不按正文、时间或位置猜测是否发送成功，结果未知不自动重播。Browser 不能直接调用 Pi Tool；通过 `host.pi` 使用原生 Prompt、Command、Bash、Interrupt 能力，不直接 fetch 宿主接口或自建 WebSocket。
+
+Method 调用没有 Browser 视图级取消参数；Global handler 的 `context.signal` 是 Node Owner 失效信号。关闭 UI 只释放展示，不停止后台任务。需要停止时调用真实 Owner 的明确停止方法；断线、超时和关闭不回滚副作用。
+
+Push 可丢失、不持久化、不 ACK、不重放，也不创建聊天消息。Entry ready、连接恢复 ready、视图 mount 时按需要查询 Method 建立权威基线；不要用页面轮询替代已有的宿主状态同步。
+
+- 当前页面轻提示：`plugin.notify({ level: 'success', title: '保存成功' })` 或 `host.notify()`，只在当前页面短暂展示，离线可错过。
+- 服务端全局通知：Node `plugin.notifications.publish({ level: 'success', title: '处理完成', event: { name: 'open-result', data: {} } })`；用返回 ID 调用 `update/delete`。Browser Entry 通过 `plugin.notifications.onEvent('open-result', handler)` 处理点击，成功后宿主删除通知。Node 未重启时重连可恢复；Node 重启或插件释放后清空，不持久化。
+
+消息适配需要时读 `/entry` 的 `declareMessage` 与 `/browser` 的 Message View 类型：Node 投影原始 Pi 消息，Browser 按最终 `viewKey + priority` 选择 View。首屏必需数据放 Summary，大内容按 Detail 获取；View 失败只影响相应消息，不自行解析 Pi 原始类型或切换到另一个低优先级 View。
+
+## 更新生效
+
+`plugins install/reload` 应用 Node/Browser 能力；目标插件活动视图重挂，旧 Browser Owner 失效。现有 Native 会话不自动重载，新 UI 可能连接旧会话方法，需兼容既有消息和方法数据；需要现有会话加载当前原生代码时使用 `session reload`。热加载无法处理的资源按宿主已有重启流程处理，不把重新挂载界面当作后端任务已停止。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetcrab/pi-desk",
-  "version": "1.1.1",
+  "version": "1.1.5-dev",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -19,6 +19,7 @@
   },
   "files": [
     "bin",
+    "docs/pi-desk",
     "next.config.ts",
     "package.json",
     "src",
@@ -110,7 +111,7 @@
     "build:plugin-host-runtime": "pnpm --filter @jetcrab/pi-desk-sdk build",
     "start": "node bin/pi-desk.js --no-open",
     "test:package": "node --test tests/l4-pi-desk-package.test.mjs",
-    "test:pidesk": "node --import tsx --test tests/l4-pidesk-command.test.ts tests/l2-plugin-commands.test.ts tests/l4-pidesk-session-reload.test.ts tests/l4-pidesk-runtime.test.ts tests/l4-pidesk-runtime-bundle.test.mjs tests/l4-pidesk-installed-runners.test.mjs tests/l4-pidesk-package-maintenance.test.ts tests/l4-pidesk-release-gate.test.mjs tests/l4-pi-global-runtime.test.mjs tests/l4-pi-desk-supervisor-cli.test.mjs",
+    "test:pidesk": "node --import tsx --test tests/l4-pidesk-command.test.ts tests/l2-plugin-commands.test.ts tests/l4-pidesk-session-reload.test.ts tests/l4-pidesk-runtime.test.ts tests/l4-pidesk-runtime-bundle.test.mjs tests/l4-pidesk-docs.test.mjs tests/l4-pidesk-installed-runners.test.mjs tests/l4-pidesk-package-maintenance.test.ts tests/l4-pidesk-release-gate.test.mjs tests/l4-pi-global-runtime.test.mjs tests/l4-pi-desk-supervisor-cli.test.mjs",
     "test:app-websocket": "pnpm build && node --import tsx --test tests/l2-chat-state.test.ts tests/l2-workbench-chat-repository.test.ts tests/l2-workbench-chat.test.ts tests/l2-workbench-layout.test.ts tests/l2-work-session-column-layout.test.ts tests/l2-work-session-update.test.ts tests/l1-app-websocket.test.mjs",
     "lint": "eslint .",
     "lint:production": "eslint . --ignore-pattern \"apps/desktop/**\" --ignore-pattern \"**/tests/**\" --ignore-pattern \"**/__tests__/**\" --ignore-pattern \"**/*.test.*\" --ignore-pattern \"**/*.spec.*\"",

package/src/client/l2_biz/pi-settings/hooks/l2-use-pi-settings.ts

@@ -40,6 +40,8 @@ function errorMessage(cause: unknown): string {
 
 export interface L2PiSettingsController {
   cwd: string | null
+  displayCwd: string | null
+  ready: boolean
   mcp: L2McpSettings | null
   editor: L2McpEditor | null
   setEditor: Dispatch<SetStateAction<L2McpEditor | null>>
@@ -54,7 +56,7 @@ export interface L2PiSettingsController {
   dialog: React.JSX.Element | null
   retry(): void
   navigate(action: () => void): Promise<void>
-  setCwd(cwd: string | null): void
+  setCwd(cwd: string | null): Promise<void>
   startManual(name: string | null, config?: L2McpServerConfig): void
   startInherited(name: string, config: L2McpServerConfig): void
   updateDraft(patch: Partial<L2McpDraft>): void
@@ -74,7 +76,9 @@ export function useL2PiSettings(
   const biz = useMemo(() => createL2PiSettingsBiz(clientId), [clientId])
   const { confirm, dialog } = useL4ConfirmDialog()
   const [cwd, setCwdState] = useState<string | null>(null)
-  const [mcp, setMcp] = useState<L2McpSettings | null>(null)
+  const [snapshot, setSnapshot] = useState<{ cwd: string | null; data: L2McpSettings } | null>(null)
+  const mcp = snapshot?.data ?? null
+  const displayCwd = snapshot ? snapshot.cwd : cwd
   const [editor, setEditor] = useState<L2McpEditor | null>(null)
   const [loading, setLoading] = useState(true)
   const [pending, setPending] = useState(false)
@@ -96,9 +100,11 @@ export function useL2PiSettings(
     confirmRef.current = confirm
     textRef.current = t
   }, [confirm, t])
+  const ready = snapshot !== null && snapshot.cwd === cwd && !loading && !loadError
   const dirty =
-    (editor?.kind === 'manual' && JSON.stringify(editor.draft) !== editor.initial) ||
-    (editor?.kind === 'json' && Boolean(editor.text))
+    ready &&
+    ((editor?.kind === 'manual' && JSON.stringify(editor.draft) !== editor.initial) ||
+      (editor?.kind === 'json' && Boolean(editor.text)))
 
   const discard = useCallback((): void => {
     setEditor(null)
@@ -113,9 +119,8 @@ export function useL2PiSettings(
       description: textRef.current('当前修改尚未保存。放弃后将保留已保存的配置。'),
       confirmLabel: textRef.current('放弃修改')
     })
-    if (leave) discard()
     return leave
-  }, [dirty, discard, pending, check?.loading])
+  }, [dirty, pending, check?.loading])
 
   useEffect(() => {
     onBeforeLeaveChange(beforeLeave)
@@ -123,14 +128,21 @@ export function useL2PiSettings(
   }, [beforeLeave, onBeforeLeaveChange])
 
   const load = useCallback(
-    async (signal: AbortSignal, currentEpoch: number): Promise<void> => {
+    async (signal: AbortSignal, currentEpoch: number, resetEditor = false): Promise<boolean> => {
       setLoading(true)
       setLoadError(null)
       try {
         const result = await biz.getMcp(cwd, signal)
-        if (!signal.aborted && epoch.current === currentEpoch) setMcp(result)
+        if (signal.aborted || epoch.current !== currentEpoch) return false
+        setSnapshot({ cwd, data: result })
+        if (resetEditor) setEditor(null)
+        return true
       } catch (cause) {
-        if (!signal.aborted && epoch.current === currentEpoch) setLoadError(errorMessage(cause))
+        if (!signal.aborted && epoch.current === currentEpoch) {
+          console.warn('[Pi Desk][MCP] 读取配置失败', { cwd, message: errorMessage(cause) })
+          setLoadError(errorMessage(cause))
+        }
+        return false
       } finally {
         if (!signal.aborted && epoch.current === currentEpoch) setLoading(false)
       }
@@ -142,12 +154,13 @@ export function useL2PiSettings(
     const current = new AbortController()
     controller.current = current
     const currentEpoch = ++epoch.current
-    void load(current.signal, currentEpoch)
+    void load(current.signal, currentEpoch, true)
     return () => current.abort()
   }, [load])
 
   const retry = (): void => {
-    if (controller.current) void load(controller.current.signal, epoch.current)
+    if (controller.current)
+      void load(controller.current.signal, epoch.current, snapshot?.cwd !== cwd)
   }
 
   const navigate = async (action: () => void): Promise<void> => {
@@ -158,8 +171,11 @@ export function useL2PiSettings(
     }
   }
 
-  const setCwd = (next: string | null): void => {
-    setMcp(null)
+  const setCwd = async (next: string | null): Promise<void> => {
+    if (next === cwd || !(await beforeLeave())) return
+    controller.current?.abort()
+    setError(null)
+    setNotice(null)
     setCheck(null)
     setLoadError(null)
     setLoading(true)
@@ -209,7 +225,7 @@ export function useL2PiSettings(
     onSaved: () => void
   ): Promise<boolean> => {
     const signal = controller.current?.signal
-    if (!signal || pending || check?.loading) return false
+    if (!signal || !ready || pending || check?.loading) return false
     const currentEpoch = epoch.current
     setPending(true)
     setError(null)
@@ -220,10 +236,8 @@ export function useL2PiSettings(
       onSaved()
       setCheck(null)
       setNotice('已保存。新会话使用新配置；已有会话需重载 Pi 配置。')
-      // 写入已经成功；重新读取失败时禁止继续以旧列表覆盖配置。
-      setMcp(null)
-      await load(signal, currentEpoch)
-      return !signal.aborted && epoch.current === currentEpoch
+      // 保留展示快照；重新读取完成前由 ready 阻止旧配置参与下一次写入。
+      return await load(signal, currentEpoch)
     } catch (cause) {
       if (!signal.aborted && epoch.current === currentEpoch)
         setError({
@@ -237,7 +251,7 @@ export function useL2PiSettings(
   }
 
   const saveEditor = async (testConnection = false): Promise<void> => {
-    if (!editor || !mcp || pending || check?.loading) return
+    if (!editor || !mcp || !ready || pending || check?.loading) return
     if (
       testConnection &&
       (editor.kind !== 'manual' || !editor.draft.enabled || mcp.projectTrusted === false)
@@ -288,7 +302,7 @@ export function useL2PiSettings(
   }
 
   const remove = async (name: string): Promise<void> => {
-    if (!mcp || !Object.hasOwn(mcp.local, name)) return
+    if (!mcp || !ready || pending || !Object.hasOwn(mcp.local, name)) return
     const restore = cwd !== null && Object.hasOwn(mcp.inherited, name)
     if (
       !(await confirmRef.current({
@@ -333,7 +347,7 @@ export function useL2PiSettings(
           config: shorthand ? { ...inherited, ...local } : (local ?? inherited),
           local: local ?? null,
           source:
-            cwd === null
+            displayCwd === null
               ? '全局'
               : local
                 ? shorthand
@@ -350,6 +364,8 @@ export function useL2PiSettings(
 
   return {
     cwd,
+    displayCwd,
+    ready,
     mcp,
     editor,
     setEditor,