# @qwen-code/web-shell Qwen Code Web Shell 是面向浏览器的 daemon 会话终端 UI，可以作为 React 组件嵌入到其他项目中。 ## 环境要求 - React：`^18.0.0 || ^19.0.0` - React DOM：`^18.0.0 || ^19.0.0` - `@qwen-code/webui`：`>=0.0.1` - `@qwen-code/sdk`：`>=0.1.8` - 浏览器环境需要能访问 Qwen Code daemon serve 的 HTTP 接口。 组件包会自动注入自身样式，样式已通过 CSS Modules 和组件作用域隔离； 接入方不需要额外引入全局 CSS。 ## 安装 ```bash npm install @qwen-code/web-shell ``` Peer dependencies 需要同时安装： ```bash npm install react react-dom @qwen-code/webui @qwen-code/sdk ``` ## 接入方式 WebShell 提供两种接入形态： ### 1. 独立接入（自带 Provider） 适合只需要嵌入一个终端视图的场景。组件内部自建 `DaemonWorkspaceProvider` + `DaemonSessionProvider`。 ```tsx import { WebShellWithProviders } from '@qwen-code/web-shell'; export function QwenCodePanel() { return ( { console.log('current session:', sessionId); }} theme="dark" language="zh-CN" /> ); } ``` ### 2. 共享 Provider 接入（纯消费者） 适合同一个 React 应用中多个视图共享同一个 daemon session 的场景（如 chat + terminal）。宿主自行提供 Provider，WebShell 只消费 hooks。 ```tsx import { DaemonWorkspaceProvider, DaemonSessionProvider, } from '@qwen-code/webui/daemon-react-sdk'; import { WebShell } from '@qwen-code/web-shell'; export function App() { return ( ); } ``` > **注意**：不要在已有 `DaemonSessionProvider` 下使用 > `WebShellWithProviders`，否则会创建嵌套的重复 Provider。 ## Props ### WebShellWithProviders 包含 `WebShell` 的所有 Props，加上 Provider 配置： | 属性 | 类型 | 说明 | | ----------- | -------- | ---------------------------------------------------- | | `baseUrl` | `string` | daemon API 地址，未传时使用 `window.location.origin` | | `token` | `string` | daemon API Bearer token | | `sessionId` | `string` | 要连接的 session id；未传或 `undefined` 时保持空页面 | ### WebShell | 属性 | 类型 | 说明 | | ------------------- | ------------------------------------------ | --------------------------------- | | `onSessionIdChange` | `(sessionId: string \| undefined) => void` | 当前 session id 变化或清空时触发 | | `theme` | `'dark' \| 'light'` | UI 主题，默认 `dark` | | `onThemeChange` | `(theme: WebShellTheme) => void` | `/theme` 命令切换主题后触发 | | `language` | `'en' \| 'zh-CN' \| 'zh' \| 'zh-cn'` | UI 语言 | | `onLanguageChange` | `(language: WebShellLanguage) => void` | `/language ui` 切换 UI 语言后触发 | ## 可选图表 Renderer `WebShell` 支持宿主通过 `customization.markdown.renderCodeBlock` 接管特定 fenced code block 的渲染。图表类场景可以注册内置的 `echarts-fulldata` renderer： ```tsx import { createEchartsFullDataRenderer } from '@qwen-code/web-shell'; window.echarts, resolveDataRef: async (ref, meta) => loadControlledChartDataset(ref, meta), }), }} />; ``` renderer 会把 `echarts-fulldata` code block 替换为图表卡片，并内置图表/数据 icon 切换；ECharts runtime 由宿主通过 `loadEcharts` 提供。若启用 `data.kind="ref"` envelope，数据只能通过宿主提供的 `resolveDataRef` 解析， renderer 不会自己读取 URL 或本地路径。 如果需要让模型主动输出 `echarts-fulldata` block，宿主应在自己的 skills 来源中 提供对应 skill，并且只在确认当前 Web Shell 宿主已经注册 renderer 时启用。 `@qwen-code/web-shell` 不内置或自动加载这个 skill；可从 `packages/web-shell/docs/examples/qwencode-viz/SKILL.md` 复制模板到宿主的 `.qwen/skills/qwencode-viz/SKILL.md`，或通过宿主自己的 skill 注入机制提供等价 说明。 `echarts-fulldata` 的 block body 可以是旧版纯 JSON ECharts option，也可以是 `{ "version": 1, "data": ..., "option": ... }` envelope。新版 inline envelope 使用 `data.dimensions: string[]` 和 `data.source` array-of-arrays；renderer 会先 normalize 成原生 ECharts option，并注入 `option.dataset`，再渲染图表和数据视图。 新版 ref envelope 必须使用受控 `artifact://` 或 `session-file://` ref，并提供 `data.format`（`csv` 或 `json`）和 `data.dimensions`，这些元信息会传给宿主的 `resolveDataRef(ref, meta)`。 宿主应使用 `JSON.parse` 解析，不能用 `eval`、`new Function` 或 script injection 执行模型生成内容。 ## 架构说明 ```text @qwen-code/sdk/daemon ← 协议层（SSE, REST, normalizer） @qwen-code/webui/daemon-react-sdk ← React adapter（Provider, hooks, store） @qwen-code/web-shell ← 终端 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`。 | | `/language` | 本地实现 + ACP 透传 | `/language ui ` 会切换 web-shell UI 语言并同步给 daemon；其他语言能力由 daemon 执行。包含 `ui`、`output` 子命令。 | | `/model` | 本地实现 + 部分透传 | 无参数打开模型弹窗；普通参数直接切换模型；`/model --fast ` 透传给 daemon。 | | `/plan` | 本地实现 | 切换到 `plan` approval mode，并可继续发送后续 prompt。 | | `/approval-mode` | 本地实现 | 打开审批模式弹窗或直接切换审批模式。 | | `/mode` | 本地实现 | web-shell 本地别名，用于切换审批模式。 | | `/mcp` | 本地实现 | 打开 MCP 管理弹窗。 | | `/skills` | 本地实现 + ACP 透传 | 无参数打开 skills 弹窗；带参数时透传给 daemon 执行。 | | `/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 ` | 本地实现 | 修改当前 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` | ACP 透传 | 列出后台任务。 | | `/insight` | ACP 透传 | 查看 insight 相关信息。 |