@qwen-code/web-shell 0.25.1 → 0.25.2-nightly.20261016.b4614845f0

package/README.md

@@ -3,6 +3,24 @@
 Qwen Code Web Shell 是面向浏览器的 daemon 会话终端 UI，可以作为 React
 组件嵌入到其他项目中。
 
+## Managed 工作区与模型
+
+完整 Web Shell 在配置 `managedAgentProvider` 后，可在首页左侧会话栏切换“本地 / 托管”，Tab 位于“新任务”下方，主聊天区沿用现有交互。托管模式复用标准欢迎界面、输入框、对话和工具卡片、审批、停止按钮及侧栏；“新任务”和历史选择操作 Managed 会话。切换模式保留各自草稿和会话，后台任务继续运行。未配置 provider 时保持原首页。Java Vite 演示入口 `?managedProvider=java` 默认托管，`managed=0` 可明确选择本地，`managed=1&managedSession=...` 深链继续有效；直接打开本地会话链接时保持本地。
+
+已有 Managed 会话的工作区、相对目录、Agent 预设和环境状态在会话上下文中查看。模型和工作区仍由 Java 授权，界面复用不改变后端工具范围或审批策略。导出的 `ManagedAgentWebShell` 独立入口保持兼容。
+
+`ManagedAgentWebShell` 可通过 `enableWorkspaceBinding` 启用 Java 授权工作区列表，并通过 `modelPresets={[{ agentId: 'agent-model-a', label: 'Model A' }]}` 提供新建会话的模型预设。每个 `agentId` 必须由宿主预先发布为模型专属 AgentDefinition；服务端模型允许列表和定义中的工具、审批设置决定实际准入。浏览器不发布定义或传入模型凭证。模型预设名称是宿主展示数据；已有会话的初始 AgentDefinition 及工具、审批配置保留，模型选择由独立的 Java 会话接口管理。
+
+Java 新建页直接复用标准 Web Shell 的欢迎标题、输入框、原生模型菜单和工作区底栏。选择工作区、相对目录和模型后输入任务并发送，一次请求创建会话与首个 Turn；响应丢失保留冻结请求，已创建后的读回重试不会再次发送输入。旧 provider 的空创建能力保持兼容。更换工作区需新建会话；支持模型切换的会话可在空闲时选择服务端允许的模型，绑定工作区内切换目录仍使用已有修订校验流程。对话复用标准消息列表及输入框布局，保留 Managed 审批、取消、结果与未确认请求重试；不提供 daemon 附件、文件引用或斜杠命令。
+
+工作区查询返回 `capabilities.approvalModeSelection: true` 时，新任务按所选 Agent 查询审批策略，并复用输入框的策略菜单。Shell profile 支持 Ask Approval 与 Auto Edit，纯文件 profile 还可提供 Full Access；托管模式不提供 Classifier Approval 或 Plan。已保存的 AgentDefinition 只提供自身固定策略。选项加载失败或无效时暂停创建；更换模型会重新读取选项并保留草稿和工作区。明确选择的策略与会话创建请求一起固定保存，刷新后的重试沿用原策略；旧待确认请求继续省略策略。已有会话显示服务端保存的策略并禁用修改，需要新建任务才能更换。未宣告能力的旧服务端保留原行为。
+
+已有工作区托管会话的输入框优先显示服务端已确认的模型选择，其次显示最近成功主模型请求的实际模型；没有这些数据时只显示 Agent 身份。会话摘要返回 `capabilities.modelChange: true` 时，模型菜单从 `/session-models/query` 读取服务端允许列表，空闲时通过 `/session-models/change` 在同一会话内切换，后续消息使用新模型。活跃任务、审批、目录切换或未确认请求期间暂停切换。请求发送前保存会话、目标模型、修订和幂等键；响应不确定或刷新后继续确认原请求，读回后才更新选择，对话与草稿保留。旧服务端和不支持的会话保持只读模型控件。上下文浮层复用原生环形控件，显示最近成功请求的 prompt token 数、同一模型配置的窗口及剩余容量；切换后等待新模型观测，缺少有效计数时明确显示未知，不能用累计计费量推测。该浮层仅提供当前占用，不显示尚无托管接口支持的手动压缩或分类明细操作。本地模式保持原有模型切换与上下文功能。
+
+Java 工作区查询返回 `capabilities.workspaceCreation: true` 时，工作区菜单提供“新建工作区 → 从空目录开始”。输入名称后，服务端创建并登记独立的空目录、授权给当前用户，页面自动选中它并保留任务草稿与模型。创建请求在发送前保存在当前标签页；响应不确定时，关闭弹窗或刷新页面后仍可重试同一请求。该能力默认关闭，需要服务端配置 `qwen.managed-agent.runtime-broker.workspace-creation-root` 及相应的已验证 Workspace 执行依赖；浏览器不选择服务器路径。
+
+本地 Vite Java 演示可添加 `managedWorkspace=1`，或设置 `VITE_MANAGED_AGENT_WORKSPACE_BINDING=true`。`VITE_MANAGED_AGENT_MODEL_PRESETS` 为上述预设数组的 JSON；`VITE_MANAGED_AGENT_ACTOR_ID` 可通过 `X-Qwen-Actor-Id` 提供本地用户身份，同时进入存储隔离 scope。Java 列出当前用户已有授权的工作区，创建能力按上述服务端配置开启；本地演示需显式配置 `QWEN_MANAGED_AGENT_TRUSTED_ACTOR_HEADER=X-Qwen-Actor-Id`，该配置仅用于可信 loopback 环境。文件工具执行还需要 Java 文档中的 Workspace files、Session Store、Broker mounts 和 Harness Broker 连接配置。
+
 ## Managed 工具结果
 
 `ManagedAgentWebShell` 与 `createJavaManagedAgentProvider` 支持 Java O3 工具结果。
@@ -33,6 +51,44 @@ Shell 执行。卡片区分执行、捕获与交付状态，面板按固定版
 安装。关闭 `general.enableAutoUpdate`、旧服务、桌面 shell、不支持的安装及嵌入式
 服务不显示按钮。临时配对连接也不提供更新入口。使用自定义 `sidebar.footer.items` 时，通过 `update` 项控制此功能。
 
+## 工作区文件浏览
+
+独立页面右侧拓展区的「文件」入口打开只读浏览器：未选择文件时仅展示
+Pierre 目录树，点击文件后左侧显示内容、右侧保留目录树。Markdown、HTML 和图片沿用现有预览，文本源码由 Pierre File
+高亮展示；Markdown 和 HTML 可以切换预览与源码。目录按需加载，筛选仅覆盖
+已加载路径，不因筛选而读取目录；输入保留原文，零匹配时显示明确提示。刷新重新加载根目录和当前文件，并收起目录。窄面板可隐藏文件树。
+中间分隔线可拖动调整两列宽度，也支持键盘方向键；文件树底部保留留白。
+深层目录和长文件名可通过整棵树的横向滚动查看，不压缩名称。
+目录列表最多显示前 2,000 个条目，截断时有提示。符号链接不作为目录递归展开。
+切换页签保留目录展开、选中文件、源码模式、筛选及滚动位置。文件页签保存
+工作区归属，展开与选中状态不会跨页面刷新保存。不接入 Git，
+不编辑文件，也不自动把打开的文件加入对话上下文。文件右键菜单支持复制相对
+或绝对路径、下载、在独立页签预览 Markdown/HTML/图片，以及通过「引用」插入
+与输入框 `@` 选择文件相同的标签。仅当前工作区文件可引用，不自动发送消息。
+
+嵌入式宿主通过 `rightPanel={{ items: ['files', 'review', 'sideTask'] }}` 启用。
+此入口需要有效、可信且无歧义的 daemon 工作区归属。
+
+新建任务页的内置 `header` 只提供工作区级入口：右侧面板开关、启用时的
+Local Control，以及多主机位置。面板开关遵循 `header.items`，并在工作区确定后
+才显示；`rightPanel.items` 此时仅保留 `files`、`terminal` 和 `webPreview`，
+`review`、`sideTask`、`trajectory` 要等首条消息创建会话后才出现。
+自定义 `renderChatHeader` 的宿主在新建任务页仍不调用该渲染器。
+输入框没有显示工作区选择器时，精简 header 保留只读工作区图标。
+面板跟随输入框选择的工作区；各工作区草稿独立保存，刷新和会话切换后可恢复，
+首条消息创建会话时迁移面板并删除草稿。草稿与会话各保留最近 20 份面板存档，
+草稿不会挤占会话的额度。
+
+源码高亮支持 33 个常用语言键及 GitHub 浅色/深色主题，其他语言显示原文。
+语言清单维护于 [`pierre-resources.ts`](client/components/artifacts/pierre-resources.ts)，
+选择策略与补丁移除条件见[后续设计](../../docs/design/web-shell-files-followups.zh-CN.md)。
+文件树移除名称中的控制字符，保留普通空格；筛选同时支持显示名称和真实路径。
+修改 Pierre 补丁并重新应用后，开发时执行 `npm run dev -- --force` 清除预构建缓存。
+
+Excel（`.xlsx`）支持内联预览，也可通过右键「预览」在独立页签打开；重复打开同一文件复用页签，其他 Excel 格式仍仅支持下载。
+文件树源码预览在读取前限制为 4 MiB，更大的文件请通过右键菜单下载。
+导入失败仅在凭据可恢复的独立页面中提供重载；嵌入宿主或仅内存凭据时提供关闭文件，保留对话和宿主页面。
+
 ## 开发网页预览
 
 独立 Web Shell 的右侧面板提供「网页预览」。先通过终端启动开发服务器，
@@ -66,7 +122,8 @@ Artifact 发布的网页链接会在对应轮次留下产物卡片；开启网
 内容的记录不能自动还原；任意开发网站也不会自动打包成离线网页。
 
 嵌入式接入方通过 `rightPanel={{ items: ['review', 'sideTask', 'webPreview'] }}`
-开启入口。宿主 CSP 需要允许预览来源的 `frame-src`，同时用
+开启入口。新建任务页也可使用此入口；网页预览的草稿按输入框已选工作区保存，
+首条消息创建会话后随面板迁移。宿主 CSP 需要允许预览来源的 `frame-src`，同时用
 `frame-ancestors` 限制宿主页面只能被受信任的宿主嵌入，不能允许开发页面
 反过来嵌入宿主。预览容器会限制直接子页面跳转，但开发应用自己的后代
 iframe 仍需宿主的防嵌入策略保护。
@@ -168,14 +225,13 @@ Tailwind 或额外引入全局 CSS。
 
 ## 浏览器任务通知
 
-通过 `qwen serve` 打开的独立 Web Shell 可在 **Settings → UI → 浏览器任务通知**
-管理提醒。内置 `main.tsx` 显式设置默认开启；用户已保存的关闭选择优先。仅在用户点击后申请浏览器授权；偏好保存在当前浏览器站点，
+通过 `qwen serve` 打开的独立 Web Shell 可在 **Settings → UI → 任务通知**
+管理提醒。内置 `main.tsx` 显式设置默认开启；用户已保存的关闭选择优先。可在设置或审批／提问面板右上角的通知图标中授权；偏好保存在当前浏览器站点，
 不写入 daemon 或 workspace 设置，同源标签页之间同步。
 
-页面在后台或窗口失焦时，当前聊天及 Split View 中仍挂载的聊天在回合结束或失败后
-可以发送系统通知。取消回合、初次加载历史和前台已处理的回合保持静默。通知显示会话标题（最多 60 个 Unicode 码点）、回合状态，以及带“提问 / 回复”标签的本轮提问（最多 80 个码点）和回复（最多 120 个码点）纯文本摘录。
-标题显示 QwenCode · 会话名，尚未生成时使用本轮问题首行，两者均缺失时显示 QwenCode；业务文案不额外添加地址。通知携带 Qwen Code 图标，实际显示位置由浏览器和操作系统决定，不能替换 macOS 上 Chrome 自身的标志。摘要直接截取文本，不额外调用模型；提问或回复缺失时省略对应行，两者均缺失时只显示状态。失败时可显示本轮提问，不展示错误详情或部分回复。系统可能进一步截短通知正文。
-通知内容可能显示在系统通知中心或锁屏上，遵循系统的预览设置；点击通知尝试聚焦原窗口并在主聊天中打开对应会话，退出设置页或分屏；已在目标会话时不会重新加载。
+页面在后台或窗口失焦时，当前聊天及 Split View 中仍挂载的聊天在回合结束、失败、需要工具审批或等待 AskUserQuestion 回答时可以发送系统通知。取消回合、初次加载历史和前台已处理的回合或请求保持静默。工具审批和提问提醒只显示会话标题与待处理状态，不展示命令、路径、问题、选项或部分回复；同一请求只提醒一次，不影响后续回合结束提醒。快照重放不补发权限或提问提醒，包括断线期间错过的请求。回合结束通知显示会话标题（最多 60 个 Unicode 码点）、回合状态，以及带“提问 / 回复”标签的本轮提问（最多 80 个码点）和回复（最多 120 个码点）纯文本摘录。
+标题显示 QwenCode · 会话名；回合结束通知在会话名尚未生成时使用本轮问题首行，两者均缺失时显示 QwenCode。审批或提问提醒缺少会话名时只显示 QwenCode。业务文案不额外添加地址。通知携带 Qwen Code 图标，实际显示位置由浏览器和操作系统决定，不能替换 macOS 上 Chrome 自身的标志。摘要直接截取文本，不额外调用模型；提问或回复缺失时省略对应行，两者均缺失时只显示状态。失败时可显示本轮提问，不展示错误详情或部分回复。系统可能进一步截短通知正文。
+通知内容可能显示在系统通知中心或锁屏上，遵循系统的预览设置；点击通知尝试聚焦原窗口并在主聊天中打开对应会话，退出设置页或分屏；已在目标会话时不会重新加载。点击审批或提问提醒不会自动批准请求或提交答案。
 
 需要支持 Notifications API 的桌面浏览器以及 HTTPS 或可信的 localhost 环境。
 支持 Web Locks 且存储可用时，同源标签页协调去重；否则退化为页面内去重及相同 tag
@@ -198,7 +254,7 @@ Tailwind 或额外引入全局 CSS。
 
 传入 `{}` 时使用默认 `QwenCode` 名称和随包图标；名称和图标均可单独省略，空白值也回退默认。标题显示“应用名称 · 会话标题”。图片 URL 由浏览器直接加载，可使用 HTTPS CDN 地址；加载失败不保证自动回退到默认图标。
 
-`defaultEnabled` 默认 `false`；设为 `true` 时仅对没有保存通知偏好的浏览器站点默认开启。用户明确开启或关闭的选择优先，刷新后也保留；挂载后修改默认值不会覆盖当前选择。不传 `browserNotifications` 时保持嵌入入口原有行为，不接入通知。即使默认开启，也不会自动申请权限，用户仍需在 Settings → UI 中允许浏览器通知。修改品牌值不会重新加载当前会话。通知点击只导航所属实例，并遵守其当前锁定工作区。
+`defaultEnabled` 默认 `false`；设为 `true` 时仅对没有保存通知偏好的浏览器站点默认开启。用户明确开启或关闭的选择优先，刷新后也保留；挂载后修改默认值不会覆盖当前选择。不传 `browserNotifications` 时保持嵌入入口原有行为，不接入通知。仅挂载不会申请权限；首次出现审批或提问面板时，若权限尚未决定且没有明确保存关闭选择，会为此浏览器站点自动尝试一次授权。浏览器可能拦截没有用户手势的申请；面板右上角的通知图标可悬停或点击查看状态、手动授权，以及 macOS／Windows 系统设置指引。不会重复自动申请，刷新后也保留尝试记录；存储不可用时只在当前挂载实例内去重。网页无法检测系统通知是否开启。修改品牌值不会重新加载当前会话。通知点击只导航所属实例，并遵守其当前锁定工作区。
 
 低层 `WebShell` 的 daemon providers 由宿主管理，不支持这个配置属性；qwen serve 内置页面继续使用默认品牌。本配置仅影响通知，不改变侧边栏品牌、Chrome 来源地址或浏览器标志。
 
@@ -526,10 +582,12 @@ daemon 参数的完整含义和配置方式见
 <WebShell onContextUsageOpen={(sessionId) => openContextDetails(sessionId)} />
 ```
 
-此参数也适用于 `WebShellWithProviders`。提供回调后，composer hover 弹层的
-「查看明细」及页头上下文详情入口会将来源会话 ID 交给宿主，不再打开内置右侧
-面板或自动读取详情；分屏传入对应分屏的会话 ID。不提供回调则保留默认行为。
-直接点击上下文圆环生成 `/context` 快照、压缩操作和已保存面板的恢复不受影响。
+此参数也适用于 `WebShellWithProviders`。提供回调后，上下文圆环的点击、
+composer hover 弹层的「查看明细」、对话内上下文卡片的「查看明细」以及页头
+上下文详情入口都会将来源会话 ID 交给宿主，不再打开内置右侧面板或自动读取
+详情；分屏传入对应分屏的会话 ID。不提供回调则保留默认行为。压缩操作和已保存
+面板的恢复不受影响。内嵌的 side-task 面板本身就在右侧面板里，没有可用的详情
+入口，它的圆环点击仍会在该面板的对话中生成 `/context` 快照。
 
 宿主可以监听命令，也可以返回 `true` 接管对应操作：