Dudu-0223
6cc45f22bd
* feat(subagent): disable interrupt tool by default * test(subagent): update remaining default tool inventories * fix: disable agent interruption in shipped configuration * test: configure interruption explicitly in custom preset fixture * test: update tool count in collapse display snapshots * docs: clarify agent interruption opt-in and verify preset controls * test: cover macOS CUA channel policy forwarding on every platform * test: move CUA coverage repair to a separate master change
19 KiB
description, kind
| description | kind |
|---|---|
| dsh 的浏览器 GUI：交互式聊天、模型与设置管理、会话历史，供运行 dsh web 表层的用户使用。 | package-bundle |
@deepseek-ai/dsh-web-app
English | 中文
桌面埋点遵循产品采集策略及其动态应用配置，不包含 Web 使用情况。
桌面埋点每 30 秒调度未满批次，exporter 超时为 15 秒，processor 超时为 20 秒。退出时允许 2 秒排空，随后取消待完成的请求和重试等待，避免埋点阻止 Host 退出。尚未发送完成的事件可能丢失。
概述
运行 dsh --profile web，获得浏览器内的聊天、模型与设置管理以及会话历史，并与其他 dsh 表层共用同一套模型访问、工具与安全默认值。启动时会打印带 token 的 URL，通常还会在默认浏览器中打开；SSH 会话和 --no-open 需要手动打开。你可以更改端口、允许额外 authority、绑定一个具体的本机 IP，并用自己提供的证书直接提供 HTTPS；通配地址会被拒绝。跨机访问使用剥离前缀代理后公告的 HTTP(S) URL、监听器 TLS，或非 loopback 绑定上的明文 HTTP。一次性的命令行任务应使用 headless 配置。
目录
使用本包
启动 GUI、打开浏览器，然后开始与 agent（智能体）对话。flag 用于微调本次调用。
Agent Teams UI 随本 bundle 加载。在模型与推理等级菜单中按 Session 开启；通过 Subagent 控件打开成员树，下方显示共享任务。
启动 Web GUI
dsh --profile web
dsh --profile web --no-open --port 8080
启动后你会看到 dsh web: 行，其根 URL 携带新的进程 token。除非 --no-open 或 SSH 会话抑制，否则默认浏览器会打开该 URL、取得签名 cookie，再重定向到不含认证参数的同一目录。页面加载且你可以与 agent 对话，就说明成功了。两种可预期的失败：前端未构建时，启动会以构建提示停止（checkout 中运行 pnpm run build）；浏览器无法打开时，stderr 会打印不含凭据的诊断，但服务器会继续运行——请自行打开已打印的启动 URL。
设置 → 模型显示 DeepSeek，使用 DEEPSEEK_API_KEY。默认模型为 deepseek-official / deepseek-flash（DeepSeek-V4.1-Flash）。DeepSeek 插件使用 Messages API。
已保存的模型选择覆盖组合默认值。设置卡接受兼容 Messages 的 API 地址与凭据引用。
配置
minimal agent preset 使用持久 Shell、read_image 工具和固定 persona，支持自动历史压缩以及会话空闲时的 /compact 命令。它复用 Host token meter，并拥有隔离的压缩后端。压缩配置与保留策略 沿用现有后端。图片读取复用 Host 文件系统和附件存储，要求模型支持图片输入；不加载文本读取、写入和编辑工具。
--host 与 --port 配置监听器；--tls-cert 与 --tls-key 让它直接提供 HTTPS；--public-url 指定 GUI 在剥离前缀的代理之后对外公告的公开 HTTP(S) 根，--trusted-host 则添加更多被接受的 authority。这些都在监听、信任与公开部署中说明，而这些 flag 设置的 tls 字段记录在载体的配置中：
| 字段 | 默认值 | 含义 |
|---|---|---|
openBrowser |
true |
启动后用默认浏览器打开；SSH 启动会抑制它 |
printUrl |
true |
启动时打印 dsh web: URL 行 |
surfaceContext |
true |
把 DSH_WEB_URL 暴露给 agent 的 shell 命令 |
publicUrl |
未设置 | 对外公告的 HTTP(S) 应用根；否则公告绑定地址 URL |
生成的配置目录列出了本运行时插件接受的字段及其 JSDoc。随发行版交付的组合插入 schedule 服务行与 ui-schedule 任务页面行，时钟读数与四个提醒工具则属于 standard、cordis 与 ptc 三个 preset。这三个 preset 的 tool-subagent 与 tool-subagent-fork 两行都 deny 这四个工具，因此被委派子 agent 的作用域不会列出它们。
standard、cordis 和 ptc 三个 preset 在各自的 tool-subagent-control 行中设置 config.interrupt: false。如需提供 interrupt_agent（也适用于 Team 模式），按迁移步骤覆盖相应 preset 声明；修改已禁用的 Host 行不会改变 preset 的工具。
监听、信任与公开部署
默认情况下 GUI 只监听 loopback，只接受本机的连接。只有 --host 会改变监听器：它接受一个具体的本机 IPv4 或 IPv6 地址，不接受通配地址。未启用 TLS 的非 loopback 监听器提供明文 HTTP，并在启动时警告，即使前置 HTTPS 的 --public-url 也不例外。Host/Origin 栅栏接受绑定 IP 本身；其他非 loopback authority 需要 --trusted-host，因此远端浏览器要么经由剥离前缀的代理访问 GUI，要么通过以可信主机名呈现的端口转发客户端访问。启动 token 交换与签名会话 cookie 认证每个 API 方法与 WebSocket 流。
同时传入 --tls-cert 与 --tls-key，监听器便以 HTTPS 而非明文 HTTP 提供服务。两者各指定一个相对进程工作目录解析的文件：证书文件包含完整证书链，密钥文件为不带口令的 PEM 私钥。它们属于同一个设置——只提供一个会报用法错误，两个都不提供则保持明文 HTTP 默认值。文件缺失、不可读、为空，或不是有效的证书与密钥对时启动失败；绝不回退到 HTTP。监听器运行期间不会重新读取这些材料，因此更换证书需要重新加载监听器或重启进程。DSH 不签发、不续期也不监视任何证书：没有 ACME 客户端、没有自签名兜底，也没有重定向监听器。浏览器使用自己的信任库与主机名匹配，因此浏览器不信任的证书，或其 subject alternative name 未覆盖你所访问 authority 的证书，会在页面加载前失败。默认端口仍为 3080，且 --tls-cert/--tls-key 不跟随 --public-url：监听器的证书覆盖浏览器实际访问的 authority。TLS 不改变授权模型：Connection 仍认证每个请求并仍校验 Host/Origin，且只要接收请求的监听器提供 HTTPS，它所签发的会话 cookie 就带 Secure。
容器可以绑定其 Pod 地址，并公告前置的 ingress：
dsh --profile web --no-open --host "$(hostname -i | awk '{print $1}')" --public-url https://app.example/ --trusted-host app.example
hostname -i 可能列出多个地址；--host 只接受一个，因此命令取第一个。fe80::1%eth0 这样的 zone ID 不能出现在 URL 中，因此公告根会剥离多余的 loopback zone，而非 loopback zone 则要求显式提供 --public-url。
未设置 --public-url 时，::ffff:127.0.0.1 这样的 mapped IPv6 回环绑定会公告其 IPv4 形式 127.0.0.1，让浏览器将其识别为本地可信来源。监听器仍使用配置的绑定地址。点分四段式的 IPv6 尾部表示该地址自身的低 32 位，与 listen 的读法完全一致：::0.0.0.1 属于 IPv6 回环并公告 [::1]，而 ::127.0.0.1 是非回环地址，并非 IPv4 回环。
--public-url 公告浏览器使用的 HTTP(S) 根——打印与打开的启动 URL、DSH_WEB_URL，以及 agent 运行时上下文中的 Web GUI URL。公告不授予任何信任：浏览器可见的 authority 还必须用 --trusted-host 点名。该 flag 不配置监听器、路由或 cookie 作用域，因为外部链路归代理所有：在反向代理之后发布 Web UI列出了这样的部署必须提供什么。
无论是公告 URL 还是浏览器信任栅栏都不保护端口本身，因此请把端口限制在可信代理或网络内。
打印的 URL 包含进程凭据，只应与预期用户分享。printUrl: false 无论是否配置 --public-url 都会抑制该行，凭据也绝不会出现在模型上下文或 DSH_WEB_URL 中。
通过 SSH 运行
通过 SSH 启动 dsh --profile web 时，URL 行仍会打印，但不会为你打开浏览器：本地转发地址由 SSH 客户端或编辑器持有。没有公告根时，打印的 URL 指向远端宿主机的绑定地址端点——绑定 loopback 时即 loopback——你通过自己的转发地址访问它。配置了 --public-url 时，打印的 URL 是带认证的公告根；浏览器交接仍被抑制，因为在远端宿主机上打开浏览器无法到达你的屏幕。
按会话的 agent 设置
每个浏览器会话选择一个随发行版交付的 preset（默认 standard）。Agent 预设设置页可更改默认项并编辑预设的子插件；保存结果持久化到 $DSH_HOME/profiles/web/cordis.patch.yml。只有 Host 提供可编辑的 profile 时，标准模式和 Creator 才会启用插件管理工具。
标准模式和创造模式包含 dsh-doc skill，用于 DSH 相关问题以及你要求的插件或预设工作。该 skill 引导 agent 查阅已安装版本的文档和源码。加载方式及其对上下文的影响参见模型体验。
打包的 skill 使用自定义 skill 根目录：同名的项目 skill 会覆盖打包的 skill，打包的 skill 又会覆盖同名的用户 skill。skill 目录中只保留优先级最高的一个条目，不会报错；参见 skill 根目录优先级。
理解实现
实现细节——点击展开
此 bundle 由一层五个文件的补丁和一个运行时胶水插件组成：cordis.patch.yml 承载宿主行和 preset 注册表，每个 presets/<id>.patch.yml 插入一条随发行版交付的 preset 声明，按 dsh.bundle.patch 列出的顺序应用。存储栈与投影缓存来自 dsh-base；Web 叠加层的工作区和消息反馈条目消费共享的 storageDomain 服务。补丁重述 base 有意省略的界面专用值，插入 Web 专用宿主条目和浏览器插件列表，再将 Agent 层移到预设后面。胶水插件负责 dist 服务、公告应用 URL、明文 HTTP 暴露警告、bash 变量和就绪通知。office-kit 条目为宿主消费者挂载一个延迟创建引擎的 Office 转换提供方，使用此 bundle 的 Desktop 组合也共享该提供方，转换后的文件保存在 $DSH_HOME/office-kit/outputs。standard 和 ptc 预设在所有 profile 中挂载 Office 工具，无论是否安装 Kit，并在加载 Office 技能后声明它们；minimal 预设不挂载它们。转换服务的 Remote 方法负责预览读取授权，Document Preview 负责 Office 查看器和客户端缓存。
skill-office 行在所有 profile 中从包内 assets 挂载 Office 技能。DSH_PRIMARY_RUNTIME 非空的 Desktop 还挂载内置依赖查询行，并选择 pythonEnvironment: 'workspace-dependencies'；其他 profile 以及没有主运行时的 Desktop 选择 pythonEnvironment: 'user'，并禁用依赖查询行。资源打包由 Desktop 应用负责。
patch 语义
patch 会替换目标行的整个 config，因此每个 Web 行都重述自己拥有的每个键：基础行上的 persona 前缀模板与 session-query-sqlite 值，随后 insert 添加 Web 宿主行、传输层与浏览器名录。webserver、web-runtime 与 connection 行都注入 webStartup 提供方并直接读取本次调用的取值；Connection 的被接受 authority 全部来自 ctx.webStartup.trustedHosts，Host/Origin 栅栏则独立于该列表接受监听器的绑定 IP。bundle 继承原生工具执行；PTC overlay 可切换部署执行器。base 以进程级挂载的按 agent 工具行在这里被禁用，由 preset 名录接管；每项宿主层与 preset 层归属决策的理由以行内注释写在 patch 里。
公告应用 URL
启动显示与浏览器交接接收附带启动 token 的公告根；agent 的运行时上下文与 DSH_WEB_URL 接收不含凭据的形式。根本身由监听、信任与公开部署定义。
就绪宣告
URL 行与浏览器交接都是就绪信号：监督方一观察到该行就发起 RPC，浏览器一打开就请求页面，因此两者只在 Loader 配置树结算、通过 required 启动检查且 Connection 认证可用后运行——在没有 Loader 的手工构建树中则立即运行。此时 client combo JavaScript 和 source map 仍未物化。可选插件失败不会阻止就绪宣告；required 启动失败或启动中途被释放的树不会宣告任何内容。
源码地图
| 文件 | 职责 |
|---|---|
src/index.ts |
web-app 粘合插件：dist 解析、公告应用 URL、bash 变量、URL 行、浏览器交接 |
src/public-url.ts |
公告根的校验与尾斜杠归一化；供本地导入的叶子模块，不属于包 API |
src/startup.ts |
web-startup 提供方：--host、--port、--tls-cert、--tls-key、--public-url、--trusted-host、--no-open、--help |
cordis.patch.yml |
Web patch：重述的基础值、Web 宿主行、浏览器名录、preset 注册表 |
presets/ |
每个随发行版交付的 preset（standard、ptc、minimal、cordis）各一条 @deepseek-ai/dsh-agent-preset 声明，各自一个补丁文件 |
tests/web-app.spec.ts |
dist index 锚定、公告 URL 发布与警告、bash 变量、就绪宣告发布 |
tests/startup.spec.ts |
在真实 Loader 树上的命令行解析 |
tests/public-url.spec.ts |
公告根的解析与归一化 |
tests/browser-open.spec.ts |
页面可达后的默认浏览器交接 |
进一步探索
当你想深入了解共享核心、浏览器重载流水线或已构建的前端时，阅读以下页面。
- 组合包索引——基于同一核心构建的表层。
- dsh-base——GUI 运行其上的共享核心。
- dsh-client-hmr——开发期间客户端插件变更如何重载。
- frontend-static——已构建的前端如何被服务。
- 生成配置目录——每个受支持配置字段及其源声明。
模型体验
DSH 文档 skill
模型看到什么
标准模式和创造模式的 skill 目录都列出 dsh-doc。skill 工具加载其指令，并引导 agent 查阅当前任务所需的参考资料。其他 preset 保留各自的 skill 来源。加载该 skill 不会修改工作区文件或 profile 设置。
Token 影响
preset 提供一条目录项。没有其他 skill 的会话还会收到目录的通用调用说明。skill 正文和参考文件仅在加载时进入上下文。
KV Cache 影响
目录在第一个步骤写入日志，在条目改变前保持不变。加载 skill 会追加工具输出，不改变工具 schema。
创造模式角色设定
模型看到什么
创造模式预设在共享的编码 Agent 描述句之后添加“You help the user customize DeepSeek Harness itself.”。插件实现和授权规则仍保留在按需加载的 dsh-doc skill 中。
Token 影响
创造模式请求增加一句固定文本。标准模式请求不变。
KV Cache 影响
该句在创造模式预设内保持稳定；切换到其他预设会改变角色设定前缀。
Web 运行时变量
模型看到什么
当 surfaceContext 为 true 时，DSH_WEB_URL 连同描述出现在受管 bash 环境中，每次调用时解析为上文「监听、信任与公开部署」定义的公告应用 URL。为 false 时不注册该变量。GUI 定位、实现 checkout 与当前 GUI URL 由本 bundle 挂载的 dsh-harness-dev-context 行提供。
Token 影响
两行受管环境变量；每个进程内保持恒定。
KV Cache 影响
无；该插件不贡献系统提示词文本。
Office 技能
模型看到什么
所有 profile 的技能目录都列出 Office 路由和三个 Office 创作技能。加载的 Python 技能末尾带一节 Python 环境说明：Desktop 上指引模型调用 load_workspace_dependencies；其他 profile 指引模型使用项目或用户已有的 Python。
Token 影响
每个初始目录包含四条目录摘要；仅在模型请求时加载技能正文。
KV Cache 影响
资源和配置不变时，内置 Office 摘要和各 Python 环境说明保持稳定；目录何时变化见 Office 技能。
已知限制与延期工作
这些限制告诉你在不常见的环境下会遇到什么——源码 checkout、SSH 会话或严格网络。它们是当前包约束，不是通用的浏览器对比或任务积压。
- 前端必须已构建——源码 checkout 需要先运行
pnpm run build；dist 缺失时启动会以构建提示停止，且没有从源码直接服务的回退路径。 - TLS 需自行启用且不代管——只有传入
--tls-cert与--tls-key（完整证书链与不带口令的密钥）时监听器才提供 HTTPS；DSH 从不获取、续期或监视证书，更换文件需要重新加载监听器或重启进程。浏览器必须信任该证书，其名称必须覆盖你所访问的 authority，且证书与--public-url相互独立。 - 未启用 TLS 时外部链路是明文 HTTP——请用终止 TLS 的代理保护它，不要在不受信任的网络上发送启动 URL。
- 只能观察到交接的启动——GUI 只报告浏览器被请求打开，而不是它确实打开了；之后的浏览器退出永远不会上报，打印的 URL 是你的手动回退路径。
- SSH 会话保留 URL 但跳过浏览器交接——没有公告根时，打印的 URL 指向远端宿主机的绑定地址；SSH 客户端或编辑器必须暴露并打开本地转发地址。
BROWSER覆盖只能来自环境——被发现的.env不能设置BROWSER；只有继承值能为自动交接选择可执行文件。- 不支持绑定所有网络接口——出于安全考虑，通配
--host（含 Linux 视为 IPv4 any 的 IPv4-mapped 形式）会在启动时被拒绝；请改为绑定本机某个接口的一个具体 IPv4 或 IPv6 地址。
开发备注
维护者的工作上下文——点击展开
无。
Web 组合包含账号 Remote 控制器和账号设置页面。