@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/docs/sdk/FILE_LAYOUT.md

@@ -1,31 +1,31 @@
-# SDK 文件布局
-
-```text
-claude-ai-workbench/
-├─ packages/                         # 可发布 SDK 源码
-│  ├─ contracts/                     # 公共类型、常量和输入标准化
-│  ├─ client/                        # 浏览器/Node REST + SSE Client
-│  ├─ core/                          # 终端状态机、上下文隔离、会话生命周期
-│  ├─ ui/
-│  │  ├─ ai-profile-settings.js      # AI Profile 默认入口
-│  │  ├─ ai-profile-settings.d.ts
-│  │  ├─ claude-terminal.js          # 产品级 Claude Code 终端入口
-│  │  ├─ claude-terminal.d.ts
-│  │  └─ theme.css
-│  └─ server/                        # REST/SSE Server 与 CLI
-├─ apps/
-│  ├─ ai-profile-settings-host/      # AI Profile 独立接入示例
-│  ├─ claude-terminal-host/          # 无调试面板的终端接入示例
-│  └─ minimal-test-host/             # 内部验收、故障注入和原始事件检查
-├─ docs/sdk/                         # 对外文档和 OpenAPI
-├─ scripts/                          # 校验与 SDK 打包
-└─ dist/sdk/                         # 自动生成的 tgz 与 SHA-256 manifest
-```
-
-## 边界规则
-
-1. 产品宿主只使用 `contracts`、`client`、`core`、`ui` 的公共入口，不复制组件源码。
-2. `claude-terminal` 不创建 Client、不写死 API 地址、不读取凭据；宿主注入 Client 和 `WorkbenchContext`。
-3. `minimal-test-host` 是内部 QA 工具，不是产品界面；运行指标、Raw SSE、故障注入不得进入终端组件。
-4. API Key 只通过 credential 接口或临时测试请求进入 Server，公开 Profile 永不返回明文。
-5. `dist/sdk/` 每次发布重新生成，不手工修改。
+# SDK 文件布局
+
+```text
+claude-ai-workbench/
+├─ packages/                         # 可发布 SDK 源码
+│  ├─ contracts/                     # 公共类型、常量和输入标准化
+│  ├─ client/                        # 浏览器/Node REST + SSE Client
+│  ├─ core/                          # 终端状态机、上下文隔离、会话生命周期
+│  ├─ ui/
+│  │  ├─ ai-profile-settings.js      # AI Profile 默认入口
+│  │  ├─ ai-profile-settings.d.ts
+│  │  ├─ claude-terminal.js          # 产品级 Claude Code 终端入口
+│  │  ├─ claude-terminal.d.ts
+│  │  └─ theme.css
+│  └─ server/                        # REST/SSE Server 与 CLI
+├─ apps/
+│  ├─ ai-profile-settings-host/      # AI Profile 独立接入示例
+│  ├─ claude-terminal-host/          # 无调试面板的终端接入示例
+│  └─ minimal-test-host/             # 内部验收、故障注入和原始事件检查
+├─ docs/sdk/                         # 对外文档和 OpenAPI
+├─ scripts/                          # 校验与 SDK 打包
+└─ dist/sdk/                         # 自动生成的 tgz 与 SHA-256 manifest
+```
+
+## 边界规则
+
+1. 产品宿主只使用 `contracts`、`client`、`core`、`ui` 的公共入口，不复制组件源码。
+2. `claude-terminal` 不创建 Client、不写死 API 地址、不读取凭据；宿主注入 Client 和 `WorkbenchContext`。
+3. `minimal-test-host` 是内部 QA 工具，不是产品界面；运行指标、Raw SSE、故障注入不得进入终端组件。
+4. API Key 只通过 credential 接口或临时测试请求进入 Server，公开 Profile 永不返回明文。
+5. `dist/sdk/` 每次发布重新生成，不手工修改。

package/docs/sdk/INTEGRATION.md

@@ -1,126 +1,126 @@
-# SDK 接入说明
-
-## 1. 安装
-
-```bash
-npm install @claude-ai-workbench/contracts@0.2.0 \
-  @claude-ai-workbench/client@0.2.0 \
-  @claude-ai-workbench/core@0.2.0 \
-  @claude-ai-workbench/ui@0.2.0
-```
-
-运行服务的机器另行安装：
-
-```bash
-npm install @claude-ai-workbench/server@0.2.0
-```
-
-## 2. 启动 Server
-
-```powershell
-$env:CLAUDE_AI_WORKBENCH_DATA_DIR = 'D:\data\claude-workbench'
-$env:CLAUDE_WORKBENCH_PORT = '5760'
-npx claude-workbench-server
-```
-
-Node.js 也可直接嵌入：
-
-```js
-const { createWorkbenchServer } = require("@claude-ai-workbench/server");
-const app = createWorkbenchServer({ dataDir: "D:/data/claude-workbench", serveHost: false });
-app.server.listen(5760, "127.0.0.1");
-```
-
-## 3. 接入 Claude Code 终端
-
-```js
-import "@claude-ai-workbench/ui/theme.css";
-import "@claude-ai-workbench/ui/claude-terminal";
-import { createClaudeWorkbenchClient } from "@claude-ai-workbench/client";
-
-const client = createClaudeWorkbenchClient({
-  apiBase: "http://127.0.0.1:5760/api/claude-workbench/v1",
-});
-const terminal = document.querySelector("#terminal");
-
-terminal.client = client;
-terminal.context = {
-  contextId: "project-42",
-  contextType: "project",
-  displayName: "知识库项目",
-  workspaceRef: "registered-workspace-42",
-  aiProfileId: "claude-sonnet",
-};
-
-terminal.addEventListener("terminal-error", ({ detail }) => console.error(detail));
-terminal.addEventListener("terminal-command", event => {
-  if (event.detail.command === "config") {
-    event.preventDefault();
-    openHostSettings();
-  }
-});
-window.addEventListener("beforeunload", () => {
-  terminal.destroy();
-  client.destroy();
-});
-```
-
-```html
-<claude-workbench-pane id="terminal"></claude-workbench-pane>
-```
-
-`workspaceRef` 是 Server 白名单中注册的工作区标识，不能由浏览器传入任意绝对路径。切换项目时只需重新赋值 `terminal.context`；Core 会中止旧请求、关闭旧 SSE，并隔离新旧上下文事件。
-
-快捷命令不是前端常量。Core 会调用 `GET /sessions/{sessionId}/commands`，从当前 Claude Code 运行时读取内置命令、Skills、Plugins 和 MCP 命令；输入 `/` 后可搜索，选中后仍可补充参数再发送。`terminal-command` 是可取消事件，宿主只在确实需要接管某个命令时调用 `preventDefault()`。
-
-图片默认支持点击选择、拖入和从剪贴板粘贴，格式为 JPEG、PNG、GIF、WebP；单张上限 10 MiB，一次最多 20 张且总计不超过 20 MiB。组件将 Base64 图片交给 Client，Server 验证真实文件签名并保存到产品数据目录的 `attachments/`，会话事件只保存可读取的附件 URL，不保存用户图片的 Base64 副本。宿主要使用自有文件选择器时可拦截：
-
-```js
-terminal.addEventListener("terminal-attach-request", async event => {
-  event.preventDefault();
-  const files = await openHostImagePicker();
-  await event.detail.addFiles(files);
-});
-```
-
-不使用 UI 时，可直接调用同一公共 API：
-
-```js
-const commands = await client.listCommands(sessionId);
-await client.send({
-  sessionId,
-  text: "说明这张图",
-  attachments: [{ name: "screen.png", mediaType: "image/png", data: base64 }],
-});
-```
-
-## 4. 接入 AI Profile UI
-
-```js
-import "@claude-ai-workbench/ui";
-import "@claude-ai-workbench/ui/theme.css";
-```
-
-```html
-<ai-profile-list id="profileList"></ai-profile-list>
-<ai-profile-editor id="profileEditor"></ai-profile-editor>
-```
-
-AI Profile UI 只发布 `profile-save`、`profile-test`、`profile-edit`、`profile-delete` 等 DOM 事件，宿主用 Client 完成持久化。测试连接不会保存；只有 `saveProfile` 和 `setCredential` 会写入产品数据目录。
-
-## 5. 不使用 npm 的浏览器接入
-
-按以下顺序加载静态文件：
-
-```html
-<link rel="stylesheet" href="/vendor/claude-workbench/ui/theme.css">
-<script src="/vendor/claude-workbench/client/index.js"></script>
-<script src="/vendor/claude-workbench/core/index.js"></script>
-<script src="/vendor/claude-workbench/ui/claude-terminal.js"></script>
-```
-
-加载后可使用全局函数 `createClaudeWorkbenchClient`、全局对象 `ClaudeWorkbenchCore` 和 `<claude-workbench-pane>`。
-
-## 6. 非 JavaScript 程序接入
-
-C++、C#、Java 等程序直接按 [openapi.yaml](openapi.yaml) 调用 JSON REST API。OpenAPI 相当于语言无关的接口头文件；UI 仍由 WebView 或浏览器宿主加载。
+# SDK 接入说明
+
+## 1. 安装
+
+```bash
+npm install @claude-ai-workbench/contracts@0.2.0 \
+  @claude-ai-workbench/client@0.2.0 \
+  @claude-ai-workbench/core@0.2.0 \
+  @claude-ai-workbench/ui@0.2.0
+```
+
+运行服务的机器另行安装：
+
+```bash
+npm install @claude-ai-workbench/server@0.2.0
+```
+
+## 2. 启动 Server
+
+```powershell
+$env:CLAUDE_AI_WORKBENCH_DATA_DIR = 'D:\data\claude-workbench'
+$env:CLAUDE_WORKBENCH_PORT = '5760'
+npx claude-workbench-server
+```
+
+Node.js 也可直接嵌入：
+
+```js
+const { createWorkbenchServer } = require("@claude-ai-workbench/server");
+const app = createWorkbenchServer({ dataDir: "D:/data/claude-workbench", serveHost: false });
+app.server.listen(5760, "127.0.0.1");
+```
+
+## 3. 接入 Claude Code 终端
+
+```js
+import "@claude-ai-workbench/ui/theme.css";
+import "@claude-ai-workbench/ui/claude-terminal";
+import { createClaudeWorkbenchClient } from "@claude-ai-workbench/client";
+
+const client = createClaudeWorkbenchClient({
+  apiBase: "http://127.0.0.1:5760/api/claude-workbench/v1",
+});
+const terminal = document.querySelector("#terminal");
+
+terminal.client = client;
+terminal.context = {
+  contextId: "project-42",
+  contextType: "project",
+  displayName: "知识库项目",
+  workspaceRef: "registered-workspace-42",
+  aiProfileId: "claude-sonnet",
+};
+
+terminal.addEventListener("terminal-error", ({ detail }) => console.error(detail));
+terminal.addEventListener("terminal-command", event => {
+  if (event.detail.command === "config") {
+    event.preventDefault();
+    openHostSettings();
+  }
+});
+window.addEventListener("beforeunload", () => {
+  terminal.destroy();
+  client.destroy();
+});
+```
+
+```html
+<claude-workbench-pane id="terminal"></claude-workbench-pane>
+```
+
+`workspaceRef` 是 Server 白名单中注册的工作区标识，不能由浏览器传入任意绝对路径。切换项目时只需重新赋值 `terminal.context`；Core 会中止旧请求、关闭旧 SSE，并隔离新旧上下文事件。
+
+快捷命令不是前端常量。Core 会调用 `GET /sessions/{sessionId}/commands`，从当前 Claude Code 运行时读取内置命令、Skills、Plugins 和 MCP 命令；输入 `/` 后可搜索，选中后仍可补充参数再发送。`terminal-command` 是可取消事件，宿主只在确实需要接管某个命令时调用 `preventDefault()`。
+
+图片默认支持点击选择、拖入和从剪贴板粘贴，格式为 JPEG、PNG、GIF、WebP；单张上限 10 MiB，一次最多 20 张且总计不超过 20 MiB。组件将 Base64 图片交给 Client，Server 验证真实文件签名并保存到产品数据目录的 `attachments/`，会话事件只保存可读取的附件 URL，不保存用户图片的 Base64 副本。宿主要使用自有文件选择器时可拦截：
+
+```js
+terminal.addEventListener("terminal-attach-request", async event => {
+  event.preventDefault();
+  const files = await openHostImagePicker();
+  await event.detail.addFiles(files);
+});
+```
+
+不使用 UI 时，可直接调用同一公共 API：
+
+```js
+const commands = await client.listCommands(sessionId);
+await client.send({
+  sessionId,
+  text: "说明这张图",
+  attachments: [{ name: "screen.png", mediaType: "image/png", data: base64 }],
+});
+```
+
+## 4. 接入 AI Profile UI
+
+```js
+import "@claude-ai-workbench/ui";
+import "@claude-ai-workbench/ui/theme.css";
+```
+
+```html
+<ai-profile-list id="profileList"></ai-profile-list>
+<ai-profile-editor id="profileEditor"></ai-profile-editor>
+```
+
+AI Profile UI 只发布 `profile-save`、`profile-test`、`profile-edit`、`profile-delete` 等 DOM 事件，宿主用 Client 完成持久化。测试连接不会保存；只有 `saveProfile` 和 `setCredential` 会写入产品数据目录。
+
+## 5. 不使用 npm 的浏览器接入
+
+按以下顺序加载静态文件：
+
+```html
+<link rel="stylesheet" href="/vendor/claude-workbench/ui/theme.css">
+<script src="/vendor/claude-workbench/client/index.js"></script>
+<script src="/vendor/claude-workbench/core/index.js"></script>
+<script src="/vendor/claude-workbench/ui/claude-terminal.js"></script>
+```
+
+加载后可使用全局函数 `createClaudeWorkbenchClient`、全局对象 `ClaudeWorkbenchCore` 和 `<claude-workbench-pane>`。
+
+## 6. 非 JavaScript 程序接入
+
+C++、C#、Java 等程序直接按 [openapi.yaml](openapi.yaml) 调用 JSON REST API。OpenAPI 相当于语言无关的接口头文件；UI 仍由 WebView 或浏览器宿主加载。

package/docs/sdk/README.md

@@ -1,21 +1,21 @@
-# Claude AI Workbench SDK
-
-SDK 由五个同版本 npm 包组成：
-
-| 包 | 职责 | 类比 C++ |
-|---|---|---|
-| `@claude-ai-workbench/contracts` | 公共数据类型与常量 | 公共头文件 |
-| `@claude-ai-workbench/client` | REST/SSE Client | 调用封装库 |
-| `@claude-ai-workbench/core` | 终端状态机与会话生命周期 | 无 UI 业务内核 |
-| `@claude-ai-workbench/ui` | AI Profile 与 Claude Terminal Web Components | UI 控件库 |
-| `@claude-ai-workbench/server` | REST/SSE 服务与 CLI | 后台服务进程 |
-
-API 固定使用版本前缀 `/api/claude-workbench/v1`。执行：
-
-```bash
-npm run sdk:check
-npm run sdk:pack
-npm run verify
-```
-
-详细接入见 [INTEGRATION.md](INTEGRATION.md)，文件职责见 [FILE_LAYOUT.md](FILE_LAYOUT.md)，语言无关接口见 [openapi.yaml](openapi.yaml)。
+# Claude AI Workbench SDK
+
+SDK 由五个同版本 npm 包组成：
+
+| 包 | 职责 | 类比 C++ |
+|---|---|---|
+| `@claude-ai-workbench/contracts` | 公共数据类型与常量 | 公共头文件 |
+| `@claude-ai-workbench/client` | REST/SSE Client | 调用封装库 |
+| `@claude-ai-workbench/core` | 终端状态机与会话生命周期 | 无 UI 业务内核 |
+| `@claude-ai-workbench/ui` | AI Profile 与 Claude Terminal Web Components | UI 控件库 |
+| `@claude-ai-workbench/server` | REST/SSE 服务与 CLI | 后台服务进程 |
+
+API 固定使用版本前缀 `/api/claude-workbench/v1`。执行：
+
+```bash
+npm run sdk:check
+npm run sdk:pack
+npm run verify
+```
+
+详细接入见 [INTEGRATION.md](INTEGRATION.md)，文件职责见 [FILE_LAYOUT.md](FILE_LAYOUT.md)，语言无关接口见 [openapi.yaml](openapi.yaml)。

package/docs/sdk/SESSION_EVENTS.md

@@ -1,13 +1,13 @@
-# Session activity subscriptions
-
-`GET /sessions/changes?contextId=<id>&after=<revision>` streams SSE session summaries. The client exposes `subscribeSessionChanges(contextId, callback, onError, { afterRevision })`. Embedded hosts may supply their existing EventSource-compatible WebSocket transport; standalone pages use native SSE.
-
-An initial `workbench/sessions-snapshot` contains `sessions` (including archived records) and `revision`. Subsequent `workbench/session-changed` messages contain `session`, `contextId`, and `revision`; `deleted: true` removes that session. Cursors outside the retained revision window produce `workbench/resync`. Re-read one full snapshot after that marker. Reconnection does not resend input.
-
-Session summaries include `tasks` and `backgroundTaskCount`. Task records use actual SDK task IDs, `parentSessionId`, optional `toolUseId`, `description`, `status`, `summary`, `usage`, and `lastToolName`. The per-session stream persists `claude/task-started`, `claude/task-progress`, `claude/task-updated`, and `claude/task-notification` events. Parent tool IDs distinguish child output from foreground output. Terminal task statuses cannot be reopened by late running events.
-
-`claude/turn-end` closes the foreground reply. For Claude SDK streaming input this may occur at `end_turn` before its aggregate `result`, which can wait for background tasks. The input queue and event reader remain alive while tasks run. When foreground and tasks are both idle, the query is collected after 30 seconds; the next input resumes the same native session. Changing provider/model while a task runs is rejected.
-
-Bound native agent tasks also persist evidence rows in the same journal: `claude/native-trace` (sanitized in-process hook facts), `claude/native-task-state` (ownership/status projections) and `claude/native-task-transcript` (a snapshot of a bound agent's transcript read through the SDK's public `getSubagentMessages` at a real terminal signal, or at the bounded turn-end sweep). Transcript rows carry `source: "sdk-public-read"`, fixed content-free `read` reason codes when a read cannot happen honestly, byte-bounded `chunk` markers, and normalized redacted entries/tool steps/usage - a snapshot read, never a claim of per-token streaming. These rows are part of the single-session stream's named event vocabulary: the standalone client subscribes to `claude/native-trace`, `claude/native-task-state`, `claude/native-task-transcript` and `claude/task-interrupted` like every other chat event, so SDK consumers receive the native facts in real time. They are additionally read back through the two read-only native-task history APIs (`GET /sessions/:id/native-tasks`, `POST /sessions/:id/native-tasks/history`), which page them without dispatching input.
-
-Set `inputOrigin: "agent-delegation"` explicitly when creating a Leader-dispatched session and on its input options. A delegated session cannot reclassify itself as human. Browser composers identify human input; unmarked legacy/API records remain unknown. This provenance follows the durable capture event key through the event bridge. No task is inferred from prose claiming that an agent is running. Drivers advertise `capabilities.backgroundTasks`; unsupported drivers show the limitation explicitly.
+# Session activity subscriptions
+
+`GET /sessions/changes?contextId=<id>&after=<revision>` streams SSE session summaries. The client exposes `subscribeSessionChanges(contextId, callback, onError, { afterRevision })`. Embedded hosts may supply their existing EventSource-compatible WebSocket transport; standalone pages use native SSE.
+
+An initial `workbench/sessions-snapshot` contains `sessions` (including archived records) and `revision`. Subsequent `workbench/session-changed` messages contain `session`, `contextId`, and `revision`; `deleted: true` removes that session. Cursors outside the retained revision window produce `workbench/resync`. Re-read one full snapshot after that marker. Reconnection does not resend input.
+
+Session summaries include `tasks` and `backgroundTaskCount`. Task records use actual SDK task IDs, `parentSessionId`, optional `toolUseId`, `description`, `status`, `summary`, `usage`, and `lastToolName`. The per-session stream persists `claude/task-started`, `claude/task-progress`, `claude/task-updated`, and `claude/task-notification` events. Parent tool IDs distinguish child output from foreground output. Terminal task statuses cannot be reopened by late running events.
+
+`claude/turn-end` closes the foreground reply. For Claude SDK streaming input this may occur at `end_turn` before its aggregate `result`, which can wait for background tasks. The input queue and event reader remain alive while tasks run. When foreground and tasks are both idle, the query is collected after 30 seconds; the next input resumes the same native session. Changing provider/model while a task runs is rejected.
+
+Bound native agent tasks also persist evidence rows in the same journal: `claude/native-trace` (sanitized in-process hook facts), `claude/native-task-state` (ownership/status projections) and `claude/native-task-transcript` (a snapshot of a bound agent's transcript read through the SDK's public `getSubagentMessages` at a real terminal signal, or at the bounded turn-end sweep). Transcript rows carry `source: "sdk-public-read"`, fixed content-free `read` reason codes when a read cannot happen honestly, byte-bounded `chunk` markers, and normalized redacted entries/tool steps/usage - a snapshot read, never a claim of per-token streaming. These rows are part of the single-session stream's named event vocabulary: the standalone client subscribes to `claude/native-trace`, `claude/native-task-state`, `claude/native-task-transcript` and `claude/task-interrupted` like every other chat event, so SDK consumers receive the native facts in real time. They are additionally read back through the two read-only native-task history APIs (`GET /sessions/:id/native-tasks`, `POST /sessions/:id/native-tasks/history`), which page them without dispatching input.
+
+Set `inputOrigin: "agent-delegation"` explicitly when creating a Leader-dispatched session and on its input options. A delegated session cannot reclassify itself as human. Browser composers identify human input; unmarked legacy/API records remain unknown. This provenance follows the durable capture event key through the event bridge. No task is inferred from prose claiming that an agent is running. Drivers advertise `capabilities.backgroundTasks`; unsupported drivers show the limitation explicitly.

package/docs/sdk/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Claude AI Workbench API
-  version: 0.13.2
+  version: 0.13.3
   description: Versioned local API for AI Profile, credential and Claude Code session management.
 servers:
   - url: http://127.0.0.1:5760/api/claude-workbench/v1
@@ -482,6 +482,7 @@ paths:
                     storeScope: { type: string, format: uuid }
                     contextId: { type: string, pattern: "^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$" }
                 requestId: { type: string, maxLength: 256, description: Caller-chosen idempotency key for this command within the scope. }
+                contextMode: { type: string, enum: [parent-snapshot], description: Freeze parent conversation context on first acceptance; retries reuse the private snapshot. }
                 text: { type: string, minLength: 1, maxLength: 200000, description: The command text. Trimmed server-side; the hash of the normalized command covers every execution-affecting choice. }
                 agentId: { type: string, description: Defaults to claude-code; agents without a reserved-identity driver answer 501 before anything is reserved. }
                 aiProfileId: { type: [string, "null"], description: Omitted inherits the parent's profile; null explicitly selects the agent's own login. }
@@ -1116,6 +1117,12 @@ components:
       type: object
       required: [delegation, phase, outcome, dispatch, child]
       properties:
+        context:
+          type: object
+          required: [mode, truncated]
+          properties:
+            mode: { type: string, const: parent-snapshot }
+            truncated: { type: boolean }
         delegation: { $ref: "#/components/schemas/DelegationCommandRecord" }
         phase: { type: string, enum: [reserved, child-created, child-create-failed, dispatching, dispatched, dispatch-unknown] }
         outcome: { type: string, enum: [not-started, not-dispatched, pending, dispatched, unknown] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/claude-ai-workbench",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Shared Claude Code terminal and Anthropic-compatible AI profile modules for local developer tools.",
   "type": "commonjs",
   "main": "src/index.js",

package/packages/client/README.md

@@ -1,29 +1,29 @@
-# @claude-ai-workbench/client
-
-浏览器和 Node.js 使用的 HTTP/SSE Client SDK。
-
-```js
-const { createClaudeWorkbenchClient } = require("@claude-ai-workbench/client");
-const client = createClaudeWorkbenchClient({ apiBase: "http://127.0.0.1:5760/api/claude-workbench/v1" });
-const profiles = await client.listProfiles();
-```
-
-浏览器也可直接加载 `index.js`，然后使用全局函数 `createClaudeWorkbenchClient`。
-
-## 原生任务历史（只读）
-
-```js
-const page = await client.listNativeTasks(sessionId, { storeScope, contextId });
-const ref = page.tasks.find((t) => t.taskRef)?.taskRef; // null = 尚未建立归属
-if (ref) {
-  let events = await client.loadNativeTaskHistory(sessionId, { taskRef: ref });
-  while (events.hasMore) {
-    events = await client.loadNativeTaskHistory(sessionId, { taskRef: ref, cursor: events.nextCursor });
-  }
-}
-```
-
-- `listNativeTasks` 必须传服务端身份（health 的 `taskIdentity.storeScope`）与该会话真实 `contextId`，逐项比对不符即 409。
-- `loadNativeTaskHistory` 需要列表页返回的完整 `NativeTaskRef`（含全部身份字段），不能缩成 taskId；cursor 只回传上一页的 `nextCursor`，不得自行构造。
-- 两个方法均为纯读取：不派发输入、不停止任务、不自动重试。响应中的 `incomplete`/`diagnostics` 如实反映日志扫描的已知缺口。
-- 失败抛出的 Error 带 `status` 与 `body`，服务器提供时还带 `code`（如 `SCOPE_MISMATCH`、`HISTORY_NOT_FOUND`、写失败闩锁的具体原因）与 `resync: true`（409：从任务列表重新同步）；503 表示历史暂不可读或写失败已闩锁，原文件保持不动。
+# @claude-ai-workbench/client
+
+浏览器和 Node.js 使用的 HTTP/SSE Client SDK。
+
+```js
+const { createClaudeWorkbenchClient } = require("@claude-ai-workbench/client");
+const client = createClaudeWorkbenchClient({ apiBase: "http://127.0.0.1:5760/api/claude-workbench/v1" });
+const profiles = await client.listProfiles();
+```
+
+浏览器也可直接加载 `index.js`，然后使用全局函数 `createClaudeWorkbenchClient`。
+
+## 原生任务历史（只读）
+
+```js
+const page = await client.listNativeTasks(sessionId, { storeScope, contextId });
+const ref = page.tasks.find((t) => t.taskRef)?.taskRef; // null = 尚未建立归属
+if (ref) {
+  let events = await client.loadNativeTaskHistory(sessionId, { taskRef: ref });
+  while (events.hasMore) {
+    events = await client.loadNativeTaskHistory(sessionId, { taskRef: ref, cursor: events.nextCursor });
+  }
+}
+```
+
+- `listNativeTasks` 必须传服务端身份（health 的 `taskIdentity.storeScope`）与该会话真实 `contextId`，逐项比对不符即 409。
+- `loadNativeTaskHistory` 需要列表页返回的完整 `NativeTaskRef`（含全部身份字段），不能缩成 taskId；cursor 只回传上一页的 `nextCursor`，不得自行构造。
+- 两个方法均为纯读取：不派发输入、不停止任务、不自动重试。响应中的 `incomplete`/`diagnostics` 如实反映日志扫描的已知缺口。
+- 失败抛出的 Error 带 `status` 与 `body`，服务器提供时还带 `code`（如 `SCOPE_MISMATCH`、`HISTORY_NOT_FOUND`、写失败闩锁的具体原因）与 `resync: true`（409：从任务列表重新同步）；503 表示历史暂不可读或写失败已闩锁，原文件保持不动。