@qwen-code/web-shell 0.24.1-preview.0

package/README.md

@@ -0,0 +1,651 @@
+# @qwen-code/web-shell
+
+Qwen Code Web Shell 是面向浏览器的 daemon 会话终端 UI，可以作为 React
+组件嵌入到其他项目中。
+
+## 开发网页预览
+
+独立 Web Shell 的右侧面板提供「网页预览」。先通过终端启动开发服务器，
+再打开面板并输入当前浏览器可访问的 HTTP/HTTPS 地址。预览支持热更新、
+刷新、390px 手机宽度与桌面宽度切换，以及外部打开。
+
+面板内切换标签会保留页面运行状态。URL 和宽度模式按工作区与会话保存；
+重新打开整个面板、切换会话或刷新 Web Shell 后会从保存的入口 URL 加载。
+预览中的跨域页面导航不会同步到地址栏，刷新也会返回入口 URL。
+关闭预览不会停止开发服务器。
+
+Artifact 发布的网页链接会在对应轮次留下产物卡片；开启网页预览后，
+点击卡片「打开」可在右栏查看。普通 `record_artifact` 链接显示详情，
+可从详情外部打开。关闭页签不删除卡片，之后仍能从历史消息重新打开。手动输入的地址只保存为面板状态，不会新增对话记录。
+实时链接始终显示当前内容。
+
+需要保留当时的网页时，使用 `Artifact` 发布自包含 HTML：每次发布会额外
+保存一份独立的历史版本，包含内联样式、脚本、数据和内嵌资源。原消息的
+卡片打开当次保存的内容，关闭面板、刷新或重启 daemon 后仍可回看和交互，
+不依赖源文件、最新发布地址或开发服务器。重新打开会从交付时的初始状态
+开始，不保存用户在预览中的临时操作状态。
+
+历史版本文件保存在所属运行目录的 `artifacts/snapshots/` 中；原发布 URL
+仍更新为最新版。记录沿用会话产物的保留策略（默认最多 200 条，超过后
+可能淘汰旧记录），并非无限存档。淘汰、删除记录、回退历史或删除会话时，
+会释放该会话的快照引用；分支会话仍在使用的内容会保留，最后一个引用
+释放后才回收文件。持久化失败时不会提前删除历史文件。旧版没有引用信息
+的快照，以及落盘前崩溃或清理失败留下的文件会保守保留。仅开启会话记录的受管 ACP 会话保存快照，普通 CLI 发布
+不额外写入历史文件。删除运行目录、移动会话而未复制快照，
+或修改快照文件后会提示不可用，不会退回最新版。普通实时链接和过去未保存
+内容的记录不能自动还原；任意开发网站也不会自动打包成离线网页。
+
+嵌入式接入方通过 `rightPanel={{ items: ['review', 'sideTask', 'webPreview'] }}`
+开启入口。宿主 CSP 需要允许预览来源的 `frame-src`，同时用
+`frame-ancestors` 限制宿主页面只能被受信任的宿主嵌入，不能允许开发页面
+反过来嵌入宿主。预览容器会限制直接子页面跳转，但开发应用自己的后代
+iframe 仍需宿主的防嵌入策略保护。
+
+地址必须使用主机名或 IPv4，不能包含登录凭据，也不能指向 Web Shell 或
+daemon 自身。页面的防嵌入策略可能要求使用外部打开。远程开发目前需要
+浏览器可访问的地址或已有端口转发；预览不会自动把浏览器的 `localhost`
+转成远程 daemon 地址，也不会转发 daemon 凭据。
+
+## 环境要求
+
+- React：`^18.0.0 || ^19.0.0`
+- React DOM：`^18.0.0 || ^19.0.0`
+- `@qwen-code/sdk`：`>=0.1.8`
+- 浏览器环境需要能访问 Qwen Code daemon serve 的 HTTP 接口。
+
+组件包会自动注入自身的 CSS（包括 Tailwind 编译产物），接入方不需要配置
+Tailwind 或额外引入全局 CSS。
+
+### Browser Support Matrix
+
+- Chrome / Edge 111+
+- Firefox 128+
+- Safari / iOS 16.4+
+- Android System WebView 111+
+
+最低版本覆盖 Tailwind v4 的生成 CSS；JavaScript 构建目标单独设置为 ES2021。
+独立页面在不支持的浏览器显示升级提示，嵌入式组件由宿主保证该支持约定。
+此矩阵不是所有最低版本真机均已验证的声明。
+
+独立生产页面在 HTTPS 或可信 loopback origin 下注册 service worker。
+仅带内容哈希的构建资源使用 worker 缓存；manifest、公开图标、API、令牌和
+事件流不缓存。HTML 连接失败时显示 503 重试页，不支持离线会话。
+安装入口由浏览器决定，不保证自动弹出安装提示。
+
+## 浏览器任务通知
+
+通过 `qwen serve` 打开的独立 Web Shell 可在 **Settings → UI → 浏览器任务通知**
+管理提醒。内置 `main.tsx` 显式设置默认开启；用户已保存的关闭选择优先。仅在用户点击后申请浏览器授权；偏好保存在当前浏览器站点，
+不写入 daemon 或 workspace 设置，同源标签页之间同步。
+
+页面在后台或窗口失焦时，当前聊天及 Split View 中仍挂载的聊天在回合结束或失败后
+可以发送系统通知。取消回合、初次加载历史和前台已处理的回合保持静默。通知显示会话标题（最多 60 个 Unicode 码点）、回合状态，以及带“提问 / 回复”标签的本轮提问（最多 80 个码点）和回复（最多 120 个码点）纯文本摘录。
+标题显示 QwenCode · 会话名，尚未生成时使用本轮问题首行，两者均缺失时显示 QwenCode；业务文案不额外添加地址。通知携带 Qwen Code 图标，实际显示位置由浏览器和操作系统决定，不能替换 macOS 上 Chrome 自身的标志。摘要直接截取文本，不额外调用模型；提问或回复缺失时省略对应行，两者均缺失时只显示状态。失败时可显示本轮提问，不展示错误详情或部分回复。系统可能进一步截短通知正文。
+通知内容可能显示在系统通知中心或锁屏上，遵循系统的预览设置；点击通知尝试聚焦原窗口并在主聊天中打开对应会话，退出设置页或分屏；已在目标会话时不会重新加载。
+
+需要支持 Notifications API 的桌面浏览器以及 HTTPS 或可信的 localhost 环境。
+支持 Web Locks 且存储可用时，同源标签页协调去重；否则退化为页面内去重及相同 tag
+的通知替换。关闭网页、页面冻结或离开未挂载的聊天后不保证提醒。嵌入式组件不自动
+启用此能力；Channel 推送不在首版范围内。
+
+`WebShellWithProviders`（及别名 `StandaloneWebShell`）支持通过 `browserNotifications` 接入通知并配置名称和图标：
+
+```tsx
+<WebShellWithProviders
+  baseUrl="https://daemon.example.com"
+  sidebar
+  browserNotifications={{
+    defaultEnabled: true,
+    appName: 'DataAgent',
+    iconUrl: 'https://cdn.example.com/assets/dataagent.png',
+  }}
+/>
+```
+
+传入 `{}` 时使用默认 `QwenCode` 名称和随包图标；名称和图标均可单独省略，空白值也回退默认。标题显示“应用名称 · 会话标题”。图片 URL 由浏览器直接加载，可使用 HTTPS CDN 地址；加载失败不保证自动回退到默认图标。
+
+`defaultEnabled` 默认 `false`；设为 `true` 时仅对没有保存通知偏好的浏览器站点默认开启。用户明确开启或关闭的选择优先，刷新后也保留；挂载后修改默认值不会覆盖当前选择。不传 `browserNotifications` 时保持嵌入入口原有行为，不接入通知。即使默认开启，也不会自动申请权限，用户仍需在 Settings → UI 中允许浏览器通知。修改品牌值不会重新加载当前会话。通知点击只导航所属实例，并遵守其当前锁定工作区。
+
+低层 `WebShell` 的 daemon providers 由宿主管理，不支持这个配置属性；qwen serve 内置页面继续使用默认品牌。本配置仅影响通知，不改变侧边栏品牌、Chrome 来源地址或浏览器标志。
+
+## Tailwind 与 shadcn/ui
+
+Web Shell 已配置 Tailwind CSS v4 和 shadcn/ui。shadcn 的 token 仅用于新增的
+Tailwind/shadcn 组件；现有 CSS Modules 的主题色值保持不变。组件代码在仓库内，
+可直接修改。
+
+### 新增 UI 的约定
+
+- 新增通用 UI 或交互组件时，优先使用 shadcn/ui 已提供的组件，再根据 Web Shell
+  的需求修改生成到仓库中的源码。已有且稳定的 CSS Modules 组件不要求为了统一而
+  重写。
+- Tailwind class 使用标准的无前缀写法，例如 `flex gap-2`。发布构建会通过 PostCSS
+  将生成的选择器限制在 Web Shell root 和 portal root，并为全局动画、CSS property
+  注册增加 Web Shell 前缀，避免与接入方样式冲突。
+- shadcn 颜色必须使用 `background`、`primary`、`muted` 等语义 token，不要直接
+  引用 Web Shell 原有颜色变量。原有 CSS Modules 继续使用原来的 token，两套色值
+  各自维护。
+- Dialog、Popover、DropdownMenu、Tooltip 等包含 Portal 的组件，必须将内容挂载到
+  Web Shell 的 portal root。新增 shadcn 组件后，应参考现有 `dialog.tsx`，使用
+  `useWebShellPortalRoot()` 向 Radix Portal 传入 `container`。这样主题、旧 CSS
+  变量以及外部配置的 z-index 才能正确继承。
+- 保留组件上的 `data-web-shell-*` 属性和公开 CSS 变量。接入方可能通过这些属性或
+  `--web-shell-dialog-backdrop-z-index`、`--web-shell-popover-z-index`、
+  `--web-shell-tooltip-z-index` 等变量定制样式和层级。
+
+在 `packages/web-shell` 目录添加后续组件，例如：
+
+```bash
+npx shadcn@latest add button
+```
+
+生成后需要检查 diff。shadcn CLI 可能更新 `globals.css`、依赖或生成默认 Portal
+实现，不应覆盖现有的 CSS scope、语义 token 和 portal root 适配。组件默认仅供
+Web Shell 内部使用；没有明确的公共 API 需求时，不要从包入口导出。
+
+Tailwind 会在发布前编译并内联到 npm 包，接入方不需要安装或配置 Tailwind，也不
+需要额外引入 `globals.css`。
+
+## 可选 Shadow DOM 隔离
+
+宿主页面存在 `*`、`h2`、`button` 等全局规则时，可以按场景开启 Shadow DOM：
+
+```tsx
+import customShadowStyles from './web-shell-shadow.css?inline';
+
+<WebShellWithProviders
+  shadowDom={{
+    plugins: true,
+    portals: true,
+    styles: customShadowStyles,
+  }}
+/>;
+```
+
+- `plugins` 隔离所有插件管理页面主体，包括统一的 Plugins 页面，以及
+  `/extensions`、`/mcp`、`/skills` 等兼容入口打开的页面。
+- `portals` 统一隔离 Web Shell 的所有弹窗层，包括 Dialog、Drawer、Popover、
+  DropdownMenu、Select 和 Tooltip；插件页面发起的弹窗也由这个开关管理。
+- `styles` 会追加到每个启用的 ShadowRoot，供 render props 等业务自定义内容继续
+  使用 class 样式。内联样式和通过 Web Shell `style` 设置的 CSS 变量不需要迁移。
+- `--web-shell-portal-root-z-index` 控制 Shadow portal host 的整体层级，默认
+  `1000`。需要与宿主自己的全局浮层协调时，可以通过 Web Shell `style` 覆盖。
+- `shadowDom={true}` 是同时开启 `plugins` 和 `portals` 的简写。
+
+默认不开启，现有 Light DOM 接入行为不变。两个场景相互独立，例如
+`{ plugins: true, portals: false }` 会隔离插件页面主体，但所有弹窗仍挂载到原来的
+Light DOM portal root。
+
+Shadow 内部仍由原 React 树通过 portal 渲染，不会创建第二个 React root；props、
+context、事件、ref 和状态语义保持不变。开启后，宿主普通选择器不会匹配 Shadow
+内部节点，但宿主也无法再用普通选择器直接覆盖这些节点，所需定制样式应通过
+`shadowDom.styles` 传入。
+
+Web Shell 会在挂载 Shadow 内容前安装样式，并在浏览器支持时让多个 ShadowRoot
+复用已经解析的 constructable stylesheet，以避免页面首次进入时的无样式闪烁和
+重复解析 CSS。
+
+### 图标约定
+
+- 新增图标统一优先使用 `lucide-react`，不要为已有的常见图标重复编写 SVG。
+- 使用具名静态导入，确保 Vite/Rollup 可以按需打包：
+
+```tsx
+import { CheckIcon, XIcon } from 'lucide-react';
+```
+
+- 不要使用 `import * as Icons` 后按名称动态取图标，这可能把整个图标库打入产物。
+- 图标默认使用 `currentColor`，尺寸优先交给 shadcn 组件或 Tailwind class 控制，
+  避免在每个调用处重复添加颜色、margin 和 padding。
+- 只有 Lucide 没有对应图标或需要产品专属图形时，才新增自定义 SVG。
+
+## 安装
+
+```bash
+npm install @qwen-code/web-shell
+```
+
+Peer dependencies 需要同时安装：
+
+```bash
+npm install react react-dom @qwen-code/sdk
+```
+
+## 接入方式
+
+WebShell 提供两种接入形态：
+
+### 1. 独立接入（自带 Provider）
+
+适合只需要嵌入一个终端视图的场景。组件内部自建
+`DaemonWorkspaceProvider` + `DaemonSessionProvider`。
+
+```tsx
+import { WebShellWithProviders } from '@qwen-code/web-shell';
+
+export function QwenCodePanel() {
+  return (
+    <WebShellWithProviders
+      baseUrl="http://127.0.0.1:4170"
+      token="your-bearer-token"
+      sessionId="838e1811-9f84-4848-9915-d9a7f01ff5c6"
+      sessionContext={{ kind: 'standalone' }}
+      onSessionIdChange={(sessionId, _workspaceId, _workspaceCwd, context) => {
+        console.log('current session:', sessionId, context);
+      }}
+      onSessionCreated={async (sessionId) => {
+        await registerSession(sessionId);
+      }}
+      theme="dark"
+      language="zh-CN"
+    />
+  );
+}
+```
+
+### 2. 共享 Provider 接入（纯消费者）
+
+适合同一个 React 应用中多个视图共享同一个 daemon session 的场景（如
+chat + terminal）。宿主自行提供 Provider，WebShell 只消费 hooks。
+
+```tsx
+import {
+  DaemonWorkspaceProvider,
+  DaemonSessionProvider,
+  WebShell,
+  useWorkspace,
+} from '@qwen-code/web-shell';
+
+function SessionViews() {
+  const workspace = useWorkspace();
+  if (!workspace.capabilities) {
+    if (workspace.status === 'error') {
+      return (
+        <button
+          onClick={() => void workspace.refreshCapabilities?.().catch(() => {})}
+        >
+          Try again
+        </button>
+      );
+    }
+    return <p role="status">Loading workspace…</p>;
+  }
+  return (
+    <DaemonSessionProvider sessionId="...">
+      <ChatPanel />
+      <WebShell theme="dark" language="zh-CN" />
+    </DaemonSessionProvider>
+  );
+}
+
+export function App() {
+  return (
+    <DaemonWorkspaceProvider baseUrl="http://127.0.0.1:4170" token="...">
+      <SessionViews />
+    </DaemonWorkspaceProvider>
+  );
+}
+```
+
+恢复已有会话时，直接组合 Provider 的宿主需要像示例一样，等待首次 capabilities
+成功后再挂载 `DaemonSessionProvider`，并在它上方提供发现失败的重试入口。
+否则主工作区稍后确定时，会话上下文变化可能触发重复恢复。后续刷新失败会保留已知
+capabilities，此时应保持会话挂载。该等待只用于首次发现，不应屏蔽真正的工作区切换。
+
+> **注意**：不要在已有 `DaemonSessionProvider` 下使用
+> `WebShellWithProviders`，否则会创建嵌套的重复 Provider。
+
+### 3. 只读 ChatRecord JSONL
+
+`WebShellTranscript` 只接收已经投影完成的 blocks，不连接 daemon，也不提供 composer、
+审批或 session mutation。浏览器宿主可以逐行解析 JSONL，再通过 SDK 的 opt-in facade
+投影：
+
+> 只渲染 transcript 的宿主请从 `@qwen-code/web-shell/transcript` 子路径导入。包根会连带
+> `App`、daemon providers 和编辑器/终端相关代码，不要依赖 tree shaking 把它们摇掉。
+
+```tsx
+import { projectChatRecordsToDaemonTranscript } from '@qwen-code/sdk/daemon/transcript';
+import { WebShellTranscript } from '@qwen-code/web-shell/transcript';
+
+const records = jsonl
+  .split(/\r?\n/)
+  .filter((line) => line.trim())
+  .map((line) => JSON.parse(line) as unknown);
+const projection = projectChatRecordsToDaemonTranscript(records);
+
+<WebShellTranscript
+  blocks={projection.blocks}
+  theme="dark"
+  language="zh-CN"
+  style={{ height: 640 }}
+/>;
+```
+
+宿主应显示 `projection.diagnostics`，并在 `complete=false` 或 `truncated=true` 时提示
+历史可能不完整。组件需要一个可用高度；自定义 renderer 的副作用仍由宿主负责。
+
+## 拖入文件的默认行为
+
+通过 `fileDropAction` 指定拖入文件时的默认去向，适用于 `WebShell` 和
+`WebShellWithProviders`：
+
+```tsx
+<WebShellWithProviders fileDropAction="upload" fileUploadDirectory="uploads" />
+<WebShellWithProviders fileDropAction="attach" />
+```
+
+- `upload`：直接上传到工作区，并插入 `@文件` 引用。
+- `attach`：直接添加为当前消息的附件。
+- 不传：仅当上传和附件都可用时显示选择弹窗。
+
+只有一种方式可用时直接使用它，即使配置的默认去向是另一种；两种都不可用时
+不接收拖入文件。`fileUploadEnabled={false}` 只关闭工作区上传，不再关闭附件
+拖入或添加附件入口。上传仍受 daemon 能力、工作区信任及目标路径检查约束。
+修改默认去向或可用方式时，会关闭已经打开的选择弹窗；需要重新拖入文件。
+
+## 消息操作
+
+- 已完成的 assistant 消息支持复制；具备持久化 checkpoint 时还支持分支。
+- 终态 turn error 支持复制显示的错误文本。重试入口保持独立，错误轮次不支持分支。
+
+## Props
+
+### WebShellWithProviders
+
+包含 `WebShell` 的所有 Props，加上 Provider 配置：
+
+| 属性                   | 类型                                  | 说明                                                                                                                                           |
+| ---------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browserNotifications` | `WebShellBrowserNotificationsOptions` | 可选接入通知；`appName` 默认 QwenCode，`iconUrl` 默认内联 PNG（支持 CDN），`defaultEnabled` 默认 false；已保存偏好优先；不传时停用，不重建会话 |
+| `baseUrl`              | `string`                              | daemon API 地址，未传时使用 `window.location.origin`                                                                                           |
+| `token`                | `string`                              | daemon API Bearer token                                                                                                                        |
+| `sessionId`            | `string`                              | 要连接的 session id；未传或 `undefined` 时保持空页面                                                                                           |
+| `workspaceId`          | `string`                              | 已注册工作区 id，主要用于定位已有 session；不会注册或锁定工作区                                                                                |
+| `workspaceCwd`         | `string`                              | 已注册工作区路径，语义同 `workspaceId`；不会注册或锁定工作区，且优先于 `workspaceId`                                                           |
+| `sessionContext`       | `DaemonProductSessionContext`         | 显式产品上下文；standalone 或 Live 上下文不能同时传 `workspaceId`、`workspaceCwd` 或 `lockWorkspaceCwd`                                        |
+| `lockWorkspaceCwd`     | `string`                              | 锁定到指定工作区路径；未注册时自动持久注册，并隐藏其他工作区及添加、移除和选择入口                                                             |
+| `restartSseOnPrompt`   | `boolean`                             | 每次 prompt 被 daemon 接收后重建存活 SSE 流；流断开时提交 prompt 总会立即重建（与此开关无关）；默认关闭                                        |
+| `settings`             | `WebShellSettingsOptions`             | 可选。控制原生 `/settings` 页面的呈现；见 [原生设置呈现](#原生设置呈现)。                                                                      |
+
+### WebShell
+
+| 属性                       | 类型                                                                                                                                  | 说明                                                                                                                                           |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onSessionIdChange`        | `(sessionId: string \| undefined, workspaceId?: string, workspaceCwd?: string, sessionContext?: DaemonProductSessionContext) => void` | 当前 session、工作区或显式产品上下文变化时触发；standalone 和 Live 通过第四个参数上报                                                          |
+| `onSessionCreated`         | `(sessionId: string) => Promise<void> \| void`                                                                                        | 新 session 创建后触发；完成前会阻塞 session 初始化和 prompt 提交，最长等待 30 秒                                                               |
+| `theme`                    | `'dark' \| 'light'`                                                                                                                   | UI 主题，默认 `dark`                                                                                                                           |
+| `onThemeChange`            | `(theme: WebShellTheme) => void`                                                                                                      | `/theme` 命令切换主题后触发                                                                                                                    |
+| `onThemeResolved`          | `(theme: WebShellTheme) => void`                                                                                                      | 未提供 `theme` 且 shell 从 daemon 设置解析出主题时触发；仅供宿主同步文档外观，不应持久化为宿主偏好                                             |
+| `language`                 | `'en' \| 'zh-CN' \| 'zh' \| 'zh-cn'`                                                                                                  | UI 语言                                                                                                                                        |
+| `onLanguageChange`         | `(language: WebShellLanguage) => void`                                                                                                | `/language ui` 切换 UI 语言后触发                                                                                                              |
+| `onLanguageResolved`       | `(language: WebShellLanguage) => void`                                                                                                | 未提供 `language` 时，有效 UI 语言在未成为宿主偏好时触发，包括设置解析、乐观切换与回滚；仅供同步文档外观                                       |
+| `brand`                    | `WebShellBrand`                                                                                                                       | 产品品牌（名称与 Logo，`logo` 为 React 节点）；提供时整体取代 daemon 解析出的品牌，见下方「品牌（白标）」                                      |
+| `onBrandResolved`          | `(brand: WebShellResolvedBrand) => void`                                                                                              | 品牌解析完成后触发，载荷只含 `name` 与 `logoDataUri`（不含 `logo` 节点），供宿主应用到自己的文档；shell 自身从不写 `document.title` 或 favicon |
+| `onSlashCommand`           | `(command: WebShellSlashCommand) => boolean \| void`                                                                                  | 斜杠命令进入默认处理前触发；返回 `true` 时由宿主接管并跳过默认行为                                                                             |
+| `onSessionArtifactsChange` | `(change: WebShellSessionArtifactsChange) => void`                                                                                    | Session Artifact 初始恢复或变化后返回当前完整快照与 turn 投影                                                                                  |
+| `settings`                 | `WebShellSettingsOptions`                                                                                                             | 可选。控制原生 `/settings` 页面的呈现；见 [原生设置呈现](#原生设置呈现)。                                                                      |
+
+宿主可以通过 `onContextUsageOpen?: (sessionId: string) => void` 接管上下文
+详情的打开操作：
+
+```tsx
+<WebShell onContextUsageOpen={(sessionId) => openContextDetails(sessionId)} />
+```
+
+此参数也适用于 `WebShellWithProviders`。提供回调后，composer hover 弹层的
+「查看明细」及页头上下文详情入口会将来源会话 ID 交给宿主，不再打开内置右侧
+面板或自动读取详情；分屏传入对应分屏的会话 ID。不提供回调则保留默认行为。
+直接点击上下文圆环生成 `/context` 快照、压缩操作和已保存面板的恢复不受影响。
+
+宿主可以监听命令，也可以返回 `true` 接管对应操作：
+
+```tsx
+<WebShell
+  onSlashCommand={({ command, args, input }) => {
+    if (command !== 'deploy') return;
+    openDeployDialog({ environment: args, source: input });
+    return true;
+  }}
+/>
+```
+
+回调在主聊天和分屏聊天中都会触发，也可以在 daemon 断连时处理纯宿主操作。
+命令名后必须是空白或输入结束，因此 `/usr/local/bin/tool` 等绝对路径不会触发
+回调。如果回调抛出异常，Web Shell 会报告错误并继续执行默认命令流程。
+
+宿主需要同步 Session 产物时，可以监听完整快照：
+
+```tsx
+<WebShell
+  onSessionArtifactsChange={({
+    reason,
+    sessionId,
+    sequence,
+    artifacts,
+    artifactsByTurn,
+  }) => {
+    replaceSessionArtifacts({
+      reason,
+      sessionId,
+      sequence,
+      artifacts,
+      artifactsByTurn,
+    });
+  }}
+/>
+```
+
+`restore` 表示进入新 Session 后的首次恢复，可携带空快照；`change` 表示实时
+Artifact 变化、同 Session 重连对账发现的差异，或 transcript 补齐后的 turn
+归属变化。每次都返回完整 `artifacts` 和 `artifactsByTurn`，不提供增量。新 Artifact
+可能先于 turn 归属交付，归属稍后补齐时会再交付一份完整快照。回调会等待 transcript
+load/catch-up 结束；同 Session 短暂断线保留去重基线并主动对账，因此宿主应接受重复
+交付，但不需要从 SSE 时序推断遗漏。`sequence` 在每个新 Session 从 1 开始。宿主回调
+抛错不会影响 WebShell 内置 Artifact 面板与轮末渲染。
+
+嵌入宿主只展示普通任务会话时，可以隐藏 Sidebar 的“任务 / 频道”来源切换：
+
+```tsx
+<WebShellWithProviders sidebar={{ showSessionSourceSwitch: false }} />
+```
+
+隐藏后，Sidebar 的会话目录固定查询 `sourceType: "default"`；独立 WebShell 和未配置
+该选项的宿主仍默认展示来源切换。
+
+### 品牌（白标）
+
+独立部署（`qwen serve` 打开的 Web Shell）用 `settings.json` 换名换 Logo，嵌入宿主用
+`brand` 属性覆盖：
+
+```json
+{
+  "ui": {
+    "brand": {
+      "name": "QiuQiu Code",
+      "logoPath": "~/.qwen/brand/logo.svg"
+    }
+  }
+}
+```
+
+daemon 把该 SVG 读成 `data:image/svg+xml` URI，通过 `GET /brand` 下发。客户端始终以
+`<img>` 渲染它，绝不作为 markup 注入：作为图片加载的 SVG 不能执行脚本，注入的可以，而
+daemon 不净化它读到的文件。该配置只从 User / System / SystemDefaults 三层读取，工作区的
+`.qwen/settings.json` 无法改写品牌 —— 那份文件通常来自打开 shell 的人并未撰写的仓库。
+
+品牌名会替换 Sidebar 品牌行、Sidebar 底部版本 tooltip、欢迎页标题、About 面板的版本行
+标签，以及独立部署下的 `document.title`；Logo 会替换 Sidebar 标记与 favicon。它不会替换
+正文文案：本地化字符串里仍有若干处提到 Qwen Code，auth provider 标签也仍是 `Qwen OAuth`
+（那是身份提供方的名字，不是产品名）。
+
+嵌入宿主传 `brand` 时整体接管名称与 Logo。`logo` 可以是任意 React 节点，因为宿主拥有自己
+的文档与 CSP；宿主也拥有标签页标题和 favicon，shell 只在 standalone 入口写 `document`，
+嵌入时通过 `onBrandResolved` 把名称与 Logo URI 交回宿主自行处理。该回调只在品牌确定后、
+以及这两个值之一发生变化时触发，因此宿主可以直接传内联对象和内联函数，不会每次渲染都重放。
+名称为空字符串等同于未设置，回退到内置名称。
+
+优先级从高到低：`sidebar.branding.render`（整行替换，仍受支持）→ `brand` 属性 → daemon
+解析值 → 内置默认。
+
+```tsx
+<WebShellWithProviders
+  brand={{ name: 'QiuQiu Code', logo: <MyLogo /> }}
+  onBrandResolved={(brand) => {
+    document.title = `${brand.name || 'Qwen Code'} — My Host`;
+  }}
+/>
+```
+
+`Live` 会话分组默认不向嵌入宿主展示；此前版本会默认展示，依赖该分组的宿主升级时
+需要显式开启：
+
+```tsx
+<WebShellWithProviders sidebar={{ showLive: true }} />
+```
+
+锁定工作区时，可以自定义 Sidebar 文件夹行的内容：
+
+```tsx
+<WebShellWithProviders
+  lockWorkspaceCwd="/path/to/workspace"
+  sidebar={{
+    lockedWorkspace: {
+      render: (workspace, { expanded }) => (
+        <span>
+          {expanded ? '📂' : '📁'} {workspace.cwd}
+        </span>
+      ),
+    },
+  }}
+/>
+```
+
+自定义内容仍使用内置的展开、收起行为，`expanded` 会随状态更新；文件夹行右侧的内置操作不会渲染。
+未提供 `lockWorkspaceCwd` 时，该 renderer 不会执行。
+
+## 原生设置呈现
+
+嵌入方宿主可以在保留原生表单和模型选择器的前提下，隐藏单个原生设置项：
+
+```tsx
+<WebShellWithProviders
+  settings={{
+    excludeItems: ['setting:fast-model', 'setting:vision-model'],
+  }}
+/>
+```
+
+`WebShellSettingsOptions.excludeItems` 接受 `WebShellSettingItemId` 值。可导入 `WEB_SHELL_SETTING_ITEM_IDS` 获取受支持的只读列表。这些 ID 是经过整理的别名，而不是 daemon 的配置路径：`setting:language` 对应语言控件，`setting:fast-model` 对应快速模型选择器。即使内部 schema 路径变化，别名也保持稳定。新增的上游设置默认仍然可见；未知的运行时 ID 会被忽略。
+
+前端内置块有自己的 ID：`builtin:chat-width`、`builtin:browser-notifications`、`builtin:live-setup`、`builtin:local-control` 和 `builtin:model-management`。隐藏普通 Model 字段时，模型列表与选择仍然可用；如需隐藏模型管理块，需显式排除 `builtin:model-management`。浏览器通知与聊天宽度相互独立。既有的能力限制仍然适用。
+
+不传 `settings`、不传 `excludeItems` 或传入空列表，都会保持现有呈现。排除在两个设置作用域（工作区与用户）中都生效。被排空的分类会消失，分类导航回退到可用分类；排除全部条目则显示现有的空状态。从设置面板打开的选择器会在其来源条目被排除时关闭。
+
+**呈现限制不是访问控制。** 排除不会改写已保存的配置，也不限制 daemon 写入、斜杠命令、其他入口的模型管理或直接文件访问。该选项不提供白名单、作用域策略、字段覆盖或条目级深链。
+
+## Markdown 图表接入
+
+`WebShell` 已内置 `markdown-chart` renderer 和 ECharts 运行时。宿主只需将
+[`markdown-chart` skill](https://github.com/datafe/markdown-chart/tree/main/skills/markdown-chart)
+安装到 Qwen Code 的项目级或用户级 skills 目录；例如项目级安装结果为：
+
+```text
+.qwen/skills/markdown-chart/SKILL.md
+```
+
+安装 skill 后按原方式使用 WebShell，不需要额外安装或导入 ECharts，也不需要传入
+图表配置：
+
+```tsx
+<WebShellWithProviders baseUrl="http://127.0.0.1:4170" />
+```
+
+skill 默认输出 `data.kind="inline"` 的 canonical `markdown-chart` block。
+WebShell 负责严格 JSON 校验、流式渲染、ECharts 生命周期以及 Chart/Data
+切换；已经闭合的图表会立即渲染，只有末尾尚未闭合的 fence 显示 loading。
+
+只有需要支持 skill 输出 `data.kind="ref"` 时，宿主才需要提供受控的
+`resolveDataRef`：
+
+```tsx
+import {
+  createMarkdownChartRegistry,
+  WebShellWithProviders,
+} from '@qwen-code/web-shell';
+
+const chartRegistry = createMarkdownChartRegistry({
+  resolveDataRef: async (ref, context) =>
+    loadControlledChartDataset(ref, context),
+});
+const markdown = { chart: { registry: chartRegistry } };
+
+<WebShellWithProviders baseUrl="http://127.0.0.1:4170" markdown={markdown} />;
+```
+
+`resolveDataRef` 是 ref 数据的唯一读取入口；WebShell 不会自行读取 URL 或本地
+路径。默认只接受规范化的 `artifact://` 和 `session-file://` ref，将 ref
+规范化后交给 resolver，并在 30 秒后终止等待。`markdown` 及其中的 `chart`
+对象应在图表挂载期间保持引用稳定。
+Chart/Data 控件、无数据提示和错误提示默认跟随 WebShell 语言；需要覆盖个别
+文案时可在稳定的 `chart` 对象上提供 `labels`。
+协议和数据格式见
+[`markdown-chart`](https://github.com/datafe/markdown-chart)。
+
+## 架构说明
+
+```text
+@qwen-code/sdk/daemon         ← 协议层（SSE, REST, normalizer）
+@qwen-code/web-shell          ← React adapter（Provider, hooks, store）+ 终端 UI 组件
+```
+
+- `WebShell` 必须在 `DaemonWorkspaceProvider` 和 `DaemonSessionProvider` 之下使用。
+- `WebShellWithProviders` 是内置 Provider 的便捷 wrapper。
+- 同一个 React 树共享一个 `DaemonSessionProvider` 时只开一条 SSE。
+
+## 已支持的斜杠命令
+
+下面列出当前 web-shell 已支持的命令。支持方式分为两类：
+
+- **本地实现**：web-shell 前端直接打开弹窗、调用 daemon REST API，或切换本地状态。
+- **ACP 透传**：web-shell 将命令发送给 daemon，由 daemon/ACP 执行。
+
+| 命令             | 支持方式            | 说明                                                                                                                    |
+| ---------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `/help`          | 本地实现            | 打开帮助弹窗，支持键盘浏览命令和快捷键。                                                                                |
+| `/theme`         | 本地实现            | 打开主题选择弹窗；支持 `/theme light`、`/theme dark`。                                                                  |
+| `/settings`      | 本地实现            | 打开设置面板，管理工作区与用户级（`~/.qwen/settings.json`）配置；两个作用域均可编辑并写回对应的 settings.json。         |
+| `/language`      | 本地实现 + ACP 透传 | `/language ui <lang>` 会切换 web-shell UI 语言并同步给 daemon；其他语言能力由 daemon 执行。包含 `ui`、`output` 子命令。 |
+| `/model`         | 本地实现 + 部分透传 | 无参数打开模型弹窗；普通参数直接切换模型；`/model --fast <model>` 透传给 daemon。                                       |
+| `/plan`          | 本地实现            | 切换到 `plan` approval mode，并可继续发送后续 prompt。                                                                  |
+| `/approval-mode` | 本地实现            | 打开审批模式弹窗或直接切换审批模式。                                                                                    |
+| `/mode`          | 本地实现            | web-shell 本地别名，用于切换审批模式。                                                                                  |
+| `/mcp`           | 本地实现            | 打开 MCP 管理弹窗。                                                                                                     |
+| `/skills`        | 本地实现 + ACP 透传 | 无参数或 `detail`/`details` 打开 skills 弹窗；其他参数转换为直接 skill 命令（`/skills review` → `/review`）。           |
+| `/tools`         | 本地实现            | 打开 tools 弹窗，列表展示工具名称、启用状态和 `description`。                                                           |
+| `/memory`        | 本地实现            | 打开 memory 弹窗，支持 `show`、`refresh`、`add user`、`add project` 等分支。                                            |
+| `/agents`        | 本地实现            | 打开 agents 弹窗，支持 `manage`、`create user`、`create project` 等分支。                                               |
+| `/copy`          | 本地实现            | 复制最后一条 assistant 输出；支持 `code`、语言名、LaTeX、inline LaTeX 等选择器。                                        |
+| `/release`       | 本地实现            | 释放 live session 连接，不删除历史会话记录。                                                                            |
+| `/clear`         | 本地实现            | 清空当前 web-shell transcript store。                                                                                   |
+| `/new`           | 本地实现            | 创建新的 daemon session。                                                                                               |
+| `/reset`         | 本地实现            | 与 `/new` 一样创建新的 daemon session。                                                                                 |
+| `/rename <name>` | 本地实现            | 修改当前 daemon session 的展示名称。                                                                                    |
+| `/resume`        | 本地实现            | 无参数打开恢复会话弹窗；带 session id 时直接加载。                                                                      |
+| `/status`        | ACP 透传            | daemon 支持，包含 `paths` 子命令。                                                                                      |
+| `/auth`          | ACP 透传            | 连接 LLM provider。                                                                                                     |
+| `/bug`           | ACP 透传            | 提交错误报告。                                                                                                          |
+| `/compress`      | ACP 透传            | 通过摘要替换来压缩上下文。                                                                                              |
+| `/context`       | ACP 透传            | 显示上下文窗口使用情况，包含 `detail` 子命令。                                                                          |
+| `/diff`          | ACP 透传            | 显示工作区相对 `HEAD` 的变更统计。                                                                                      |
+| `/docs`          | ACP 透传            | 打开 Qwen Code 文档。                                                                                                   |
+| `/doctor`        | ACP 透传            | 执行安装与环境诊断，包含 `memory` 子命令。                                                                              |
+| `/export`        | ACP 透传            | 导出当前会话记录，包含 `html`、`md`、`json`、`jsonl` 子命令。                                                           |
+| `/goal`          | ACP 透传            | 设置目标，并持续工作直到条件满足。                                                                                      |
+| `/init`          | ACP 透传            | 分析项目并创建定制的 `QWEN.md`。                                                                                        |
+| `/stats`         | ACP 透传            | 显示统计信息，包含 `model`、`tools` 子命令。                                                                            |
+| `/summary`       | ACP 透传            | 生成当前会话摘要。                                                                                                      |
+| `/tasks`         | 本地实现            | 打开环境信息面板并刷新后台任务。                                                                                        |
+| `/btw`           | 本地实现 + ACP 透传 | daemon 支持侧边任务时新建侧边任务；否则发送一个不影响主对话的侧边问题。                                                 |
+| `/fork`          | 本地实现 + ACP 透传 | 启动共享当前上下文的后台智能体。                                                                                        |
+| `/insight`       | ACP 透传            | 查看 insight 相关信息。                                                                                                 |