@panda-agent/panda-app-sdk 0.1.0 → 0.4.0

package/README.md

@@ -2,7 +2,53 @@
 
 Panda 智能应用 SDK — 在 iframe 或 Utility Process 中调用 Panda Desktop 提供的应用平台 API。
 
-SDK 为纯客户端 RPC 封装，**不包含** Panda Core 运行时。应用须在 Panda Desktop 中安装并运行。
+- **纯客户端 RPC 封装**，不包含宿主运行时；应用必须在 Panda Desktop 中安装并运行
+- 双入口：`browser`（iframe UI）/ `node`（Standalone / Headless 后端）
+- 当前版本：**0.4.0**
+
+本次平台变更新增 `conversation.create`：应用可创建**用户会话**（落盘后出现在主界面侧栏、用户可接手继续对话），`createForApp` 保持应用私有语义；`conversation.attach` 支持在会话未加载时按其记录工作区后台恢复后再绑定。使用这两个能力的应用需声明 `engines.pandaAppSdk: "0.4.0"`。
+
+上一版平台变更移除了 App 专有函数通道。旧 manifest 的 `agentFuncs`（包括空声明）和 `agent.funcs.receive` 不再支持，必须迁移到标准 MCP。没有兼容代发层；App UI、storage、普通 conversation 订阅和 Agent API 保留。
+
+Plugin 可声明 `mcpScope: "app"`（缺省 `"shared"`），App 私有 Agent 自动绑定 owning plugin 的实例 MCP。`invokeSubagent` 的 `allowedTools` 可进一步限制 builtin 精确 ID 或本 App MCP 的无歧义工具名，`readableFiles` 仅限制 `read_file` 的精确文件参数；它们不授予额外权限，不绕过 readonly、审批或资源边界。带策略字段的调用会先检查本轮新增的 `runtime.getHost().capabilities.invocationToolPolicy`，旧宿主缺少此位时拒绝派发，不回退为普通不受限 Agent；协商期间也可取消。`runtime.supports(version)` 仍只比较版本，不能代替此检查。
+
+App MCP 后台需要动态 endpoint 时，宿主新增通用可信环境 `PANDA_APP_INSTANCE_ID` 与 `PANDA_APP_MCP_DISCOVERY_FILE`。这不是 `.mcp.json` 的既有模板变量。发现文件只能由所属实例使用；transport key 不应进入 prompt、模型参数或 UI 状态。详细生命周期与实现边界见仓库设计文档。
+
+---
+
+## 目录
+
+- [安装](#安装)
+- [入口](#入口)
+- [快速开始](#快速开始)
+  - [示例 1：Session 应用前端](#示例-1session-应用前端)
+  - [示例 2：Standalone / Headless 后端](#示例-2standalone--headless-后端)
+  - [示例 3：能力检测（runtime.supports）](#示例-3能力检测runtimesupports)
+- [API 参考](#api-参考)
+  - [auth — 用户](#auth--用户)
+  - [model — 模型](#model--模型)
+  - [workspace — 工作区](#workspace--工作区)
+  - [artifacts — 制品](#artifacts--制品)
+  - [conversation — 会话](#conversation--会话)
+  - [session — 会话上下文与挂载](#session--会话上下文与挂载)
+  - [todo — 任务清单](#todo--任务清单)
+  - [memory — 会话记忆](#memory--会话记忆)
+  - [ingress — 消息提交](#ingress--消息提交)
+  - [agent — 智能体能力](#agent--智能体能力)
+  - [ui — 界面](#ui--界面)
+  - [storage — 存储](#storage--存储)
+  - [tools — 工具](#tools--工具)
+  - [runtime — 运行时与宿主](#runtime--运行时与宿主)
+  - [dialog — 原生对话框](#dialog--原生对话框)
+- [事件订阅参考](#事件订阅参考)
+- [应用类型对照](#应用类型对照)
+- [版本与兼容性](#版本与兼容性)
+- [高级用法](#高级用法)
+- [从零构建一个 Panda 应用](#从零构建一个-panda-应用)
+- [构建与发布 SDK](#构建与发布-sdk)
+- [示例演示](#示例演示)
+
+---
 
 ## 安装
 
@@ -14,41 +60,600 @@ npm install @panda-agent/panda-app-sdk
 
 | 子路径 | 运行环境 | 用途 |
 |--------|----------|------|
-| `@panda-agent/panda-app-sdk/browser` | iframe（Session / Standalone UI） | `PandaApp.connectIframe()` |
-| `@panda-agent/panda-app-sdk/node` | Utility Process（Standalone 后端 / Headless） | `PandaApp.connectUtilityProcess()` |
+| `@panda-agent/panda-app-sdk/browser` | iframe（Session / Standalone UI） | `PandaApp.connect()` |
+| `@panda-agent/panda-app-sdk/node` | Utility Process（Standalone 后端 / Headless） | `PandaApp.connect()` |
+
+使用 Vite / webpack / esbuild 将对应入口打进应用 bundle。
+
+### 启动就绪（0.3.0）
+
+应用 manifest 声明 `"engines": { "pandaAppSdk": "0.3.0" }` 后采用显式启动契约。宿主立即显示 Loading；有后台时等待后台和当前页面分别就绪，纯前端只等待前端，headless 只等待后台。未声明新契约的旧 App 保持旧启动路径，不以固定延时伪装 ready。
+
+`PandaApp.connect()` 同步创建 SDK 客户端，不代表就绪。后台在必需服务初始化后、前端在首个可用界面渲染后调用 `await app.ready()`。调用幂等，ACK 只确认当前这一端，不能等待整体 App 就绪。初始化期间的 SDK RPC 仍可使用。MCP client、登录与全部远端数据不属于首屏条件。
+
+前端示例：在 React 首屏 bootstrap 完成后的 effect 中调用 `app.ready()`；不要在模块加载时调用。页面刷新需要重新报告，切换会话隐藏保活页面则不重复初始化。SDK 在每份新文档中建立内部握手，宿主确认当前文档后接受 ready；页面自行刷新也会重新进入 Loading，旧文档的迟到 ready 不会完成新文档。该握手不增加公开 API，也不要求重启健康后台。宿主启动失败或超时提供重试/关闭。
+
+旧 `PandaApp.connectIframe()` 与 `PandaApp.connectUtilityProcess()` 标记 `@deprecated`，仍委托同一连接实现。初始化包路径继续使用 `/browser`、`/node`，不嗅探运行环境。
+
+---
 
 ## 快速开始
 
-### Session / Standalone 前端
+### 示例 1：Session 应用前端
 
 ```typescript
 import { PandaApp } from '@panda-agent/panda-app-sdk/browser';
 
-const app = PandaApp.connectIframe();
-const conv = await app.conversation.createForApp({ title: 'My task', ephemeral: true });
-await app.conversation.submitMessage(conv.conversationId, 'Hello');
+const app = PandaApp.connect();
+
+// 1. 创建应用私有会话（ephemeral：用完即焚）
+const conv = await app.conversation.createForApp({
+  title: 'My task',
+  ephemeral: true,
+});
+
+// 2. 订阅 turn / message 事件（Push 通道）
+const sub = await app.conversation.subscribe({
+  conversationId: conv.conversationId,
+  topics: ['turn', 'message'],
+  onEvent: (ev) => {
+    if (ev.type === 'message.streaming') { /* 流式更新 UI */ }
+    if (ev.type === 'turn.completed') { /* 完成 */ }
+  },
+});
+
+// 3. 提交消息 → Agent turn
+await app.conversation.submitMessage(conv.conversationId, '帮我写一份周报');
+
+// 4. 或阻塞等待本轮终态
+const turn = await app.conversation.awaitTurn({
+  conversationId: conv.conversationId,
+  timeoutMs: 60_000,
+});
+
+await sub.unsubscribe();
 ```
 
-使用 Vite / webpack 将 browser 入口打进前端 bundle。
+### 示例 2：Standalone / Headless 后端
 
-### Standalone / Headless 后端（`package/main.mjs`）
+`package/main.mjs`（Utility Process 入口，建议 esbuild 打成单文件）：
 
 ```typescript
-import { PandaApp, APP_UTILITY_READY } from '@panda-agent/panda-app-sdk/node';
+import { PandaApp } from '@panda-agent/panda-app-sdk/node';
 
-const app = PandaApp.connectUtilityProcess();
+const app = PandaApp.connect();
 
-process.parentPort.postMessage({
-  type: APP_UTILITY_READY,
-  appId: process.env.PANDA_APP_ID ?? 'unknown',
+// 初始化必要的本地存储、服务与处理器后，报告后台就绪。
+await app.ready();
+
+// 直接执行工具 / 调用模型
+const result = await app.tools.execute({
+  toolName: 'run_shell',
+  workspace: { kind: 'default' },
+  args: { command: 'echo ok', description: 'smoke' },
 });
+```
+
+### 示例 3：能力检测（runtime.supports）
+
+宿主（Panda Desktop）内置 SDK 版本可能落后于应用依赖的版本，用 `runtime.supports()` 在运行时判断：
+
+```typescript
+import { PandaApp } from '@panda-agent/panda-app-sdk/browser';
+
+const app = PandaApp.connect();
+
+if (await app.runtime.supports('0.2.0')) {
+  // 使用 0.2.0 引入的能力
+} else {
+  // 降级提示：请升级 Panda Desktop
+  console.warn('当前 Panda Desktop 版本过低，部分功能不可用');
+}
+
+// 也可以读取宿主环境与版本
+const host = await app.runtime.getHost();
+console.log(host.pandaVersion, host.appSdkVersion, host.platform);
+```
+
+---
+
+## API 参考
+
+> `PandaApp.connect()` 同步返回 SDK 客户端；`app.ready()` 和宿主调用返回 `Promise`。订阅事件处理函数同步注册为回调，订阅创建及宿主取消订阅为异步。invoke 失败时 reject，错误信息为宿主返回的 `[AppPlatform]` / `[panda-runtime]` 前缀错误。
+> 「所需权限」指应用 `panda-app.json` 的 `permissions` 中必须声明的权限；未授权调用会被拒绝。
+
+### auth — 用户
+
+#### `auth.getCurrentUser()`
+
+```typescript
+getCurrentUser(): Promise<AppUser | null>
+```
+
+返回当前登录用户；未登录时返回 `null`。
+
+`AppUser`：`{ id, username, email, displayName?: string | null, avatar?: string | null }`
+
+- 所需权限：`auth.read`
+
+### model — 模型
+
+#### `model.list(options?)`
+
+```typescript
+list(options?: { enabledOnly?: boolean; visibleOnly?: boolean; scene?: string }): Promise<ModelListItem[]>
+```
+
+列出可用模型（默认仅已启用且可见的模型）。`scene` 可过滤特定场景（如 `chat`）。
+
+`ModelListItem`：`{ id, displayName, providerName, description? }`
+
+- 所需权限：`model.read`
+
+#### `model.resolveForScene(request?)`
+
+```typescript
+resolveForScene(request?: { scene?: string; preferredModelId?: string }): Promise<ModelListItem | null>
+```
+
+按场景解析最高优先级模型；`preferredModelId` 指定偏好模型时优先返回。`scene` 缺省为 `chat`。
+
+- 所需权限：`model.read`
+
+#### `model.chat(request)`
+
+```typescript
+chat(request: ModelChatRequest): Promise<ModelChatResult>
+```
+
+非流式直调模型（适合工作流 LLM 节点等场景，不经过 Agent turn）。
+
+`ModelChatRequest`：`{ modelId?, messages: { role: 'system'|'user'|'assistant'; content: string }[], temperature?, maxTokens? }`
+
+`ModelChatResult`：`{ content, modelId, displayName? }`
+
+- 所需权限：`model.chat`
+
+### workspace — 工作区
+
+#### `workspace.list(request)`
+
+```typescript
+list(request: { limit: number; includeEphemeral?: boolean }): Promise<WorkspaceListItem[]>
+```
+
+最近工作区列表，按最近打开时间降序。`limit` 必填（1–100）。
+
+`WorkspaceListItem`：`{ workspaceId, displayName, path?, lastOpened?, firstAdded, bindingKind: 'real'|'ephemeral'|'unknown', registeredInProcess }`
+
+- 所需权限：`workspace.read`
+
+#### `workspace.ensureLocal(request)`
+
+```typescript
+ensureLocal(request: { path: string; touch?: boolean }): Promise<WorkspaceListItem>
+```
+
+将本地路径注册为工作区并返回其信息。`touch` 默认 `true`（更新最近打开时间）。
+
+- 所需权限：`workspace.bind`
+
+### artifacts — 制品
+
+工作区制品的只读访问（列表 / 快照 / 文本读取 / Data URL 读取）。
+
+```typescript
+list(request: ArtifactsListRequest): Promise<ArtifactsListResult>
+snapshot(request: ArtifactsListRequest): Promise<ArtifactsSnapshotResult>
+readText(request: ArtifactsReadRequest): Promise<ArtifactReadTextResult>
+readDataUrl(request: ArtifactsReadRequest): Promise<ArtifactReadDataUrlResult>
+```
+
+- `ArtifactsListRequest`：`{ workspace: WorkspaceRef, root?, path?, depth? }`（`depth` 递归深度 1–5）
+- `ArtifactsReadRequest`：`{ workspace: WorkspaceRef, root?, path }`
+- `WorkspaceRef`：`{ kind: 'id', workspaceId } | { kind: 'localPath', path } | { kind: 'default' }`
+- `ArtifactsListResult`：`{ entries: { path, size, mtime, kind: 'file'|'directory' }[], version }`
+- `ArtifactReadTextResult`：`{ path, content, byteLength, mtime }`
+- `ArtifactReadDataUrlResult`：`{ path, dataUrl, mimeType, byteLength, mtime }`
+
+- 所需权限：`files.read.workspace`（使用非会话工作区时另需 `workspace.bind`）
+
+### conversation — 会话
+
+会话是应用与 Agent 交互的核心对象。应用可以创建用户会话（`create`）或私有会话（`createForApp`）、绑定已有会话（`attach`）、提交消息并订阅事件。
+
+#### `conversation.create(options?)`
+
+```typescript
+create(options?: CreateConversationOptions): Promise<CreateConversationResult>
+```
+
+创建**用户会话**：会话归属用户，落盘后出现在主界面侧栏，用户可打开继续对话；应用自动获得该会话的读写绑定。
+
+`CreateConversationOptions`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `title?` | `string` | 会话标题；省略时由宿主生成默认标题 |
+| `selectedModelId?` | `string` | 指定模型；省略时沿用该工作区的模型选择与全局默认 |
+| `workspace?` | `WorkspaceRef` | 工作目录；省略时使用宿主默认工作区 |
+
+`CreateConversationResult`：`{ conversationId, title, workspaceId }`。`title` 回显实际标题；省略 `title` 时可能为空字符串（宿主默认标题已落盘，但那时会话还没有显式标题），需要固定标题时请显式传入。
+
+- 返回时保证会话已落盘（transcript 头与摘要），可被侧栏列出并在重启后恢复。
+- 不写入 `appOrigin`：不自动挂载应用私有 MCP 工具，也不改变应用主 Agent 选择；需要应用工具时请把应用挂到该会话（见 `session` 命名空间）。
+- session 呈现（`session.getContext().presentation === 'session'`）的实例不能调用：它只能操作被挂载的那个会话，新建的会话对它不可读写，调用会报 `conversation.create is not available to session tokens`。
+- 所需权限：`conversation.create`（使用 `localPath` 工作区时另需 `workspace.bind`）。
+
+重启 Panda 后应用需重新 `attach` 并 `subscribe`（token、会话绑定与订阅都是内存态）；建议应用用 `storage.global` 保存业务 ID 与 `conversationId` 的对应关系。
+
+#### `conversation.createForApp(options?)`
+
+```typescript
+createForApp(options?: CreateForAppOptions): Promise<CreateForAppResult>
+```
+
+创建应用私有会话。`CreateForAppOptions`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `title?` | `string` | 会话标题 |
+| `selectedModelId?` | `string` | 指定模型 |
+| `ephemeral?` | `boolean` | `true` 时创建用完即焚的临时会话（可被 `disposeForApp` 销毁） |
+| `workspace?` | `WorkspaceRef` | 关联工作区 |
+| `workspaceId?` | `string` | **已废弃**，请用 `workspace` |
+
+`CreateForAppResult`：`{ conversationId, title, ephemeral, workspaceId }`
+
+- 所需权限：`conversation.create`（使用工作区时另需 `workspace.bind`）
+
+#### `conversation.disposeForApp(conversationId)`
+
+销毁本应用拥有的 ephemeral 会话（非 ephemeral 或正忙时会失败；运行中的 turn 会先尝试取消）。
+
+- 所需权限：`conversation.create`
+
+#### `conversation.listForApp(workspaceId?)`
+
+```typescript
+listForApp(workspaceId?: string): Promise<unknown>
+```
+
+列出本应用创建的会话（可按工作区过滤）。
+
+- 所需权限：`conversation.read`
+
+#### `conversation.attach(conversationId)` / `conversation.detach(conversationId)`
+
+```typescript
+attach(conversationId: string): Promise<{ conversationId: string }>
+detach(conversationId: string): Promise<unknown>
+```
+
+将已有会话绑定/解绑到本应用（`attach` 后应用可读写该会话）。目标会话尚未加载时，宿主按其记录的工作区从磁盘恢复后再绑定，不切换主界面焦点。私有会话（`createForApp` 创建）只在此应用实例内可用：其他应用的私有会话会被拒绝，自己的私有会话也不能冷恢复，重启后请重新 `createForApp`。`attach` 所需权限：`conversation.read`。
+
+#### `conversation.submitMessage(conversationId, prompt)`
+
+```typescript
+submitMessage(conversationId: string, prompt: string): Promise<{ conversationId: string; accepted: boolean; deferred: boolean }>
+```
+
+向会话提交用户消息并触发 Agent turn。返回 `deferred: true` 表示会话忙，消息已入队稍后处理。
+
+- 所需权限：`conversation.write`
+
+#### `conversation.getMessages(conversationId)`
+
+获取会话消息快照（数组形式，非订阅）。
+
+- 所需权限：`conversation.read`
+
+#### `conversation.subscribe(options)`
+
+```typescript
+subscribe(options: ConversationSubscribeOptions & { onEvent?: AppEventHandler }): Promise<ConversationSubscription>
+```
+
+订阅会话事件流（Push 通道）。`ConversationSubscribeOptions`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `conversationId` | `string` | 会话 ID |
+| `topics?` | `AppEventTopic[]` | 事件主题，缺省 `turn` + `message`（见[事件订阅参考](#事件订阅参考)） |
+| `fromTurnId?` | `string` | 从指定 turn 开始回放 |
+| `includeMessagesOnTurnEnd?` | `boolean` | turn 结束时附带消息快照 |
+
+`onEvent` 回调接收 `AppEventEnvelope`：`{ topic, type, conversationId, turnId?, messageId?, timestamp, payload, isLast? }`。
+
+返回 `{ subscriptionId, unsubscribe: () => Promise<void> }`，用毕务必 `unsubscribe()`。
+
+- 所需权限：`conversation.read`
+
+#### `conversation.awaitTurn(options)`
+
+```typescript
+awaitTurn(options: { conversationId: string; turnId?: string; timeoutMs?: number }): Promise<unknown>
+```
+
+阻塞至指定 turn 到达终态（含 `uiMessages` 快照），适合「提交后等结果」的简化流程；超时 reject。
+
+- 所需权限：`conversation.read`
+
+### session — 会话上下文与挂载
+
+#### `session.getContext()`
+
+```typescript
+getContext(): Promise<SessionContext>
+```
+
+返回当前应用实例上下文：`{ appId, presentation: 'standalone'|'session'|'headless', conversationId?, workspaceId? }`。
+
+- 所需权限：隐式（有效会话 token 即可）
+
+#### `session.mount(conversationId, appId)` / `session.unmount(conversationId, appId)` / `session.listMounts(conversationId)`
+
+Session 应用挂载管理：把应用挂载到指定会话（同一 `conversationId + appId` 幂等）、解除挂载、列出会话已挂载应用。
+
+### todo — 任务清单
+
+#### `todo.get(conversationId)`
+
+```typescript
+get(conversationId: string): Promise<TodoSnapshot>
+```
+
+会话的任务清单快照。`TodoSnapshot`：`{ content, items: { id, content, completed, current }[] }`
+
+- 所需权限：`conversation.read`
+
+### memory — 会话记忆
+
+#### `memory.listSessionEntries(conversationId)`
+
+```typescript
+listSessionEntries(conversationId: string): Promise<MemorySessionEntries>
+```
+
+会话记忆条目列表。`MemorySessionEntries`：`{ conversationId, workspaceId?, workspacePath?, workspaceRealm?, entries: { filename, type: 'user'|'feedback'|'project'|'reference', description, modifiedAt }[] }`
+
+- 所需权限：`conversation.read`
+
+### ingress — 消息提交
+
+#### `ingress.submit(conversationId, prompt)`
+
+```typescript
+submit(conversationId: string, prompt: string): Promise<{ conversationId: string; status: string }>
+```
+
+向会话提交消息（与 `submitMessage` 同源，返回 `status`：`fired` / `deferred`）。
+
+- 所需权限：`conversation.write`
+
+### agent — 智能体能力
+
+#### `agent.invokeSkill(request)`
+
+```typescript
+invokeSkill(request: InvokeSkillRequest): Promise<InvokeSkillResult>
+```
+
+在指定会话中调用 Skill（应用只能调用自己声明拥有的 Skill）。
+
+`InvokeSkillRequest`：`{ conversationId, skillName, action, payload, displayText?, idempotencyKey?, projectRef? }`
+
+`InvokeSkillResult`：`{ conversationId, status: 'fired' | 'deferred' }`
+
+- 所需权限：`agent.invoke`
 
-// 使用 app.conversation / app.tools 等 API
+#### `agent.invokeSubagent(request)`
+
+```typescript
+invokeSubagent(request: InvokeSubagentRequest): Promise<InvokeSubagentResult>
+```
+
+在一次性临时会话中按 `subagentType` 同步执行子代理，返回结果载荷（适合工作流「子 Agent 节点」）。
+
+`InvokeSubagentRequest`：`{ subagentType, prompt, description?, model?, readonly?, workspace?, invocationId?, timeoutMs? }`（`timeoutMs` 默认 5 分钟；`invocationId` 可用于提前取消）
+
+`InvokeSubagentResult`：`{ content, outputPreview, outputFilePath?, workId, agentType, subTranscriptPath? }`
+
+- 所需权限：`agent.invokeSubagent`
+
+#### `agent.cancelSubagent(invocationId)`
+
+```typescript
+cancelSubagent(invocationId: string): Promise<{ cancelled: boolean; workId?: string }>
 ```
 
-`APP_UTILITY_READY` 为可选握手消息（宿主仅记录日志，不阻塞启动）。
+取消进行中的子代理执行。
+
+- 所需权限：`agent.invokeSubagent`
+
+### ui — 界面
+
+#### `ui.theme()`
+
+```typescript
+theme(): Promise<{ theme: 'light' | 'dark' | 'system' }>
+```
+
+宿主 UI 明暗主题偏好，内嵌应用据此跟随宿主。
+
+- 所需权限：`ui.theme`
+
+#### `ui.sessionSurface.getState()` / `ui.sessionSurface.show(options?)` / `ui.sessionSurface.collapse()`
+
+Session 面板（右侧会话面板）状态读取 / 展开 / 收起。
 
-建议用 esbuild 将 node 入口打成单文件 `main.mjs` 再随应用 zip 分发。
+`SessionSurfaceState`：`{ supported, mounted, visible, active, maximized }`
+
+`show(options?: { activate?: boolean; reason?: string })`
+
+### storage — 存储
+
+应用私有 KV 存储，值须为 JSON 可序列化数据（`AppJsonValue`）。
+
+```typescript
+global: {
+  get(key: string): Promise<AppJsonValue | undefined>
+  set(key: string, value: AppJsonValue): Promise<unknown>
+  delete(key: string): Promise<unknown>
+  list(prefix?: string): Promise<AppStorageListItem[]>
+}
+session: {
+  get(key: string): Promise<AppJsonValue | undefined>
+  set(key: string, value: AppJsonValue): Promise<unknown>
+  delete(key: string): Promise<unknown>
+  list(prefix?: string): Promise<AppStorageListItem[]>
+}
+```
+
+- `global`：应用级存储，跨会话共享
+- `session`：会话级存储，仅当前 Session 会话可用（非 Session 上下文会报错）
+- `AppStorageListItem`：`{ key, value }`
+
+- 所需权限：`storage.app`
+
+### tools — 工具
+
+不经过 Agent turn，直接调用宿主内置工具。
+
+#### `tools.list(request)`
+
+```typescript
+list(request: { workspace?: WorkspaceRef; workspaceId?: string }): Promise<Array<{ name: string; displayName: string; description: string; kind: string }>>
+```
+
+列出应用可用的工具（宿主按 denylist 过滤后的集合）。
+
+- 所需权限：`tools.execute`
+
+#### `tools.execute(request)`
+
+```typescript
+execute(request: {
+  toolName: string;
+  args?: Record<string, unknown>;
+  workspace?: WorkspaceRef;
+  workspaceId?: string;
+}): Promise<{
+  toolName: string;
+  workspaceId: string;
+  ok: boolean;
+  llmContent?: string;
+  error?: { message: string; type?: string };
+  displayData?: unknown;
+}>
+```
+
+直接执行工具。`ok: false` 时 `error` 携带失败信息。
+
+- 所需权限：`tools.execute`（安装授权后运行时不逐次确认）
+
+### runtime — 运行时与宿主
+
+#### `runtime.now()`
+
+```typescript
+now(): Promise<{ timestamp: number; iso: string; timeZone: string; utcOffsetMinutes: number }>
+```
+
+宿主当前时间与时区。
+
+- 所需权限：隐式（有效会话 token 即可）
+
+#### `runtime.getHost()`
+
+```typescript
+getHost(): Promise<{
+  platform: string; arch: string; osName: string; hostProduct: string;
+  shell: string; shellKind: string; homeDir: string;
+  pandaVersion: string; appSdkVersion: string;
+}>
+```
+
+宿主只读环境信息。`appSdkVersion` 与 npm 包版本对齐。
+
+- 所需权限：隐式
+
+#### `runtime.supports(requiredVersion)`
+
+```typescript
+supports(requiredVersion: string): Promise<boolean>
+```
+
+判断宿主 SDK 版本是否满足最低要求（`>= requiredVersion`）。用于调用新版 API 前的能力检测与降级提示（见[示例 3](#示例-3能力检测runtimesupports)）。
+
+- 所需权限：隐式
+
+### dialog — 原生对话框
+
+iframe 无法可靠触发系统下载/文件选择，宿主提供 **Electron 原生对话框 + token 保护 IO**：选择路径后凭 token 读写，路径不可绕过。
+
+#### 组合便捷方法（推荐）
+
+```typescript
+pickAndReadFile(options?: DialogPickAndReadFileOptions): Promise<DialogReadPickedFileResult | null>
+saveFile(options: DialogSaveFileOptions): Promise<string | null>
+```
+
+- `pickAndReadFile`：打开文件选择框并读取选中文件；取消返回 `null`。`DialogPickAndReadFileOptions` = `DialogShowOpenRequest & { encoding?: 'utf8'|'base64' }`
+- `saveFile`：选择保存路径并写入内容；取消返回 `null`，成功返回 `filePath`。`DialogSaveFileOptions`：`{ content, suggestedName?, defaultPath?, title?, encoding?, filters? }`
+
+#### 分步方法（需要更多控制时）
+
+```typescript
+showOpen(request?: DialogShowOpenRequest): Promise<DialogShowOpenResult>
+readPickedFile(request: DialogReadPickedFileRequest): Promise<DialogReadPickedFileResult>
+releasePick(pickToken: string): Promise<unknown>
+showSave(request?: DialogShowSaveRequest): Promise<DialogShowSaveResult>
+writeSaveFile(request: DialogWriteSaveFileRequest): Promise<DialogWriteSaveFileResult>
+```
+
+- `DialogShowOpenRequest`：`{ title?, defaultPath?, filters?, multiSelections?, openDirectory?, openFile? }`
+- `DialogShowOpenResult`：`{ canceled: true } | { canceled: false, filePaths, pickToken }`（`pickToken` 一次性，需凭它读取文件，读后 `releasePick` 释放）
+- `DialogReadPickedFileResult`：`{ filePath, encoding, content, byteLength }`
+- `DialogShowSaveRequest`：`{ title?, defaultPath?, suggestedName?, filters? }`
+- `DialogShowSaveResult`：`{ canceled: true } | { canceled: false, filePath, saveToken }`（`saveToken` 一次性）
+- `DialogWriteSaveFileResult`：`{ filePath, byteLength }`
+- 单次 token IO 有大小上限（50 MB）；`readPickedFile` / `writeSaveFile` 前务必先持有对应 token
+
+- 所需权限：`native.dialog.open`（打开/读取）；`native.dialog.save`（保存/写入）
+
+---
+
+## 事件订阅参考
+
+`conversation.subscribe` 的 `topics` 取值（白名单）：
+
+| topic | 事件 type 示例 | 说明 |
+|-------|----------------|------|
+| `turn` | `turn.started` / `turn.completed` / `turn.failed` / `turn.cancelled` | 轮次生命周期 |
+| `message` | `message.user_added` / `message.assistant_started` / `message.streaming` / `message.completed` / `messages.snapshot` | 消息与流式输出 |
+| `tool` | `tool.*` | 工具调用（需相应权限） |
+| `metrics` | `metrics.updated` | 上下文指标 |
+| `conversation` | — | 会话级事件 |
+
+事件包结构 `AppEventEnvelope`：
+
+```typescript
+{
+  topic: string;
+  type: string;              // 稳定公开名，如 'turn.completed'
+  conversationId: string;
+  turnId?: string;
+  messageId?: string;
+  timestamp: number;
+  payload: unknown;
+  isLast?: boolean;          // 流式最后一帧
+}
+```
+
+> 默认不暴露 `thinking` 类内容；流式 `message.streaming` 由宿主按 50ms 节流合并。
+
+---
 
 ## 应用类型对照
 
@@ -58,6 +663,32 @@ process.parentPort.postMessage({
 | `standalone` | UI 需要 | `runtime.processEntry` 需要 |
 | `headless` | 不需要 | 必须 |
 
+---
+
+## 版本与兼容性
+
+- 版本遵循 **semver**。`0.x` 阶段为快速演进期：**minor（如 0.1 → 0.2）可能包含新增 API**，破坏性变更会发布说明并给出迁移指引；进入 `1.0.0` 后承诺「稳定 API 不破坏」。
+- **manifest 声明最低 SDK 版本**：在应用 `panda-app.json` 中声明 `engines.pandaAppSdk`（格式必须为 `x.y.z`，语义等价 `>=`）：
+
+```json
+{
+  "id": "acme.demo",
+  "name": "Demo",
+  "version": "1.0.0",
+  "publisher": "acme",
+  "presentation": "session",
+  "runtime": { "packageEntry": "package/index.html" },
+  "engines": { "pandaAppSdk": "0.1.0" },
+  "permissions": ["conversation.create", "conversation.read", "conversation.write"]
+}
+```
+
+- **安装拦截**：当宿主 SDK 版本低于应用声明的 `engines.pandaAppSdk` 时，安装会被拒绝并提示升级 Panda Desktop。
+- **运行时检测**：即使安装了，也建议用 `runtime.supports()` 做能力检测（见示例 3），避免调用不存在的 API。
+- `runtime.getHost()` 返回的 `appSdkVersion` 与 npm 包版本对齐；发布新版 SDK 时宿主内置版本会同步更新。
+
+---
+
 ## 高级用法
 
 需要裸 `invoke`（例如共享验收脚本）时：
@@ -70,31 +701,113 @@ const app = createAppSdk(transport);
 const invoke = (path: string, args?: unknown[]) => transport.invoke(path, args);
 ```
 
-## 开发与构建（monorepo 内）
+---
+
+## 从零构建一个 Panda 应用
+
+1. **准备应用目录**（以下结构）：
+
+```
+my-app/
+├── panda-app/panda-app.json   # manifest（声明 id / 入口 / 权限 / engines）
+├── package/
+│   ├── index.html             # UI 入口（Session / Standalone）
+│   ├── src/…                  # 前端源码
+│   └── main.mjs               # Standalone / Headless 后端（esbuild 打包产物）
+└── resources/                 # 展示用图标、封面（可选）
+```
+
+2. **编写 manifest**（见[版本与兼容性](#版本与兼容性)示例），声明 `runtime.packageEntry`、`permissions`、可选 `engines.pandaAppSdk`。
+
+3. **安装 SDK 并编写代码**：
+
+```bash
+npm install @panda-agent/panda-app-sdk
+```
+
+4. **打包前端 bundle**：将 `browser` 入口打进 `index.html` 引用的 JS（Vite / webpack / esbuild 均可）；node 后端用 esbuild 打成单文件：
+
+```bash
+npx esbuild src/main.ts --bundle --platform=node --format=esm --outfile=package/main.mjs
+```
+
+5. **在 Panda Desktop 中安装**：打开「智能应用」→ 右上角「本地安装」→ 选择应用目录（或打包成 zip 选择压缩包）→ 授权权限 → 启用。
+
+---
+
+## 构建与发布 SDK
+
+> 以下步骤在 **monorepo 内** 的 `packages/app-sdk` 目录执行。
+
+### 1. 准备环境
 
 ```bash
 cd packages/app-sdk
 npm install
-npm run build          # 产出 dist/browser、dist/node
-npm run vendor-fixtures # 复制到 panda-desktop/fixtures/*/package/vendor/
-npm test
 ```
 
-修改 SDK 后需重新 `build` 并 `vendor-fixtures`，桌面 demo 才会更新。
+### 2. 本地构建（产出 `dist/browser`、`dist/node`）
+
+```bash
+npm run build
+```
+
+`build` 会：
+- esbuild 打包 browser / node 双入口（ESM，`es2022` 目标）
+- `tsc` 生成类型声明 `dist/*/index.d.ts`
 
-## 发布到 npm
+### 3. 产物自检
 
 ```bash
-cd packages/app-sdk
-npm run release:publish:dry-run   # 干跑
-npm run release:publish           # 发布到 @panda-agent（需 npm 组织权限）
-npm run release:publish:tester    # 先发 tester tag
+npm run verify-dist
 ```
 
-发布前会校验 `package.json` version 与 Core `PANDA_APP_SDK_VERSION` 一致。本包 `.npmrc` 指向 `registry.npmjs.org`（勿使用仓库根目录的 npmmirror 配置）。
+校验项：browser bundle 不得引用 `node:*` 内置模块；node bundle 必须包含 `parentPort` 传输；不发布 sourcemap；两个 bundle 均可直接 import。
+
+### 4. 单元测试
+
+```bash
+npm test          # = npm run build && vitest run
+```
+
+### 5.（monorepo 内）同步桌面内置 demo 的 vendor 拷贝
+
+```bash
+npm run vendor-fixtures
+```
+
+将 `dist` 复制到 `panda-desktop/fixtures/*/package/vendor/` 与内置插件目录，使桌面 demo 使用新 SDK。
+
+### 6. 打包 tarball（可分发 / 本地安装验证）
+
+```bash
+npm pack          # 触发 prepack → build + verify-dist，产出 *.tgz
+```
+
+### 7. 发布到 npm
+
+```bash
+npm run release:publish:dry-run    # 干跑，确认产物与校验通过
+npm run release:publish:tester     # 先发布到 tester tag 供内测
+npm run release:publish            # 发布到 latest（需 @panda-agent 组织权限）
+```
+
+发布前会自动校验：**SDK 版本与宿主声明的 SDK 版本必须一致**（仓库根 `node scripts/verify/check-app-sdk-version.mjs`）。升级 SDK 版本时，请同步更新宿主侧版本声明后一并发布，否则发布会被拦截。
+
+> 本包 `.npmrc` 指向 `registry.npmjs.org`，请勿使用仓库根目录的 npmmirror 配置。
+
+---
+
+## 示例演示
 
-## 版本
+仓库内置了可直接演示的示例应用（源码在 `panda-desktop/fixtures/`，已通过 `vendor-fixtures` 携带最新 SDK）：
 
-`runtime.getHost().appSdkVersion` 与 npm 包版本应对齐。发布时同步更新 Core 中 `PANDA_APP_SDK_VERSION`（`app-platform-runtime-types.ts`）。
+| 示例 | 类型 | 演示内容 |
+|------|------|----------|
+| `demo-hello-app` | Standalone | 全能力冒烟：上下文 / 工具直连 / 事件订阅 / 原生对话框，UI 上有「运行验收」按钮 |
+| `demo-session-app` | Session | 会话内挂载：创建会话、ingress 提交、事件流渲染 |
+| `demo-headless-app` | Headless | 无 UI 后端：UP 启动握手 + 会话 API |
+| `npm-sdk-test-app` | Standalone | 通过 npm 安装 SDK（非 vendor 拷贝）的独立应用示例 |
+| `memory-viewer-app` | Standalone | 会话记忆读取展示 |
 
-建议 Panda Desktop 版本不低于 SDK 发布说明中的最低宿主版本。
+演示步骤：Panda Desktop → 智能应用 → 本地安装 → 选择对应 fixture 目录（如 `panda-desktop/fixtures/demo-hello-app`）→ 授权 → 启用 → 从侧栏「应用」打开。