dsh-web-enhanced

<div align="center">

English · 简体中文

</div>

> DeepSeek Harness 的 Web 增强插件：任务看板（含 cron 定时执行）、Git 图谱、VSCode 式资源管理器（文件树 + 预览分栏）/变更面板、DeepSeek API 余额显示，以及纯文本模型的识图（图片理解）。 > > 🔌 生态：仓库已打 #dsh · #dsh-plugin topics —— 欢迎被 @dsh-plugin 收录。

独立于 deepseek-harness 仓库开发与构建——本插件只消费官方发布的 @deepseek-ai/* 包与 Web 客户端既有槽位，不修改任何仓库源码。

功能

截图

由 scripts/e2e.mjs --capture 在真实 UI 上截图（无需模型 key）：

安装

插件是一个 bundle 组合包（dsh.bundle），已发布到 npm，安装进 Web profile：

# npm（推荐）
dsh plugin --profile web add dsh-web-enhanced

# GitHub（跟默认分支；update 重新解析分支头）
dsh plugin --profile web add github:banlanzs/dsh-web-enhanced

# 本地源码打包产物
dsh plugin --profile web add ./dsh-web-enhanced-<version>.tgz

lib/ 随仓提交，因此没有 prepare 步骤——安装无需工具链，也不会提示 allowBuilds。

> 要安装，不要 link:。 所有 @deepseek-ai/* 都是 peer 依赖，必须解析到 profile 提供的那一份。Node 解析符号链接包时以其真实路径为起点，所以 link: 安装的插件会在自己的 node_modules 里解析这些包——于是有了第二份 @deepseek-ai/dsh-typert-protocol。@Remote 装饰器把标记记录在该模块的私有状态里，持有另一份实例的 host 网关因此看不到任何 descriptor，/api/webEnhanced/* 全部返回 404，而客户端半仍能正常加载渲染（故障表现具有迷惑性）。怀疑安装有问题时这样验证： > > ``sh > node -e "console.log(require.resolve('@deepseek-ai/dsh-typert-protocol',{paths:['<profile>']}))" > node -e "console.log(require.resolve('@deepseek-ai/dsh-typert-protocol',{paths:['<plugin>/lib']}))" > `` > > 两条路径必须完全一致。

然后启动：

dsh --profile web

一键安装脚本

clone 后直接运行——脚本会检查前置（dsh / pnpm / 仓库可达），用公开 git URL 安装并提示重启：

git clone https://github.com/banlanzs/dsh-web-enhanced.git
cd dsh-web-enhanced
./scripts/install.sh

更新

不需要先卸载再装。 dsh plugin 是一个 pnpm 转发器：它把参数原样交给 profile 目录里的 pnpm 执行，再按已安装状态重新对齐 bundle 层列表。所以更新就是一条命令，然后重启 DSH：

# npm 安装：升级到 registry 上的最新已发布版本
dsh plugin --profile web update dsh-web-enhanced
dsh --profile web

要点：install 拉不到新提交，update 才行。 github:banlanzs/dsh-web-enhanced 这种没写 ref 的 spec 跟的是默认分支，但 pnpm 会把当时解析到的 commit 钉进 profile 的锁文件：

dsh-web-enhanced: github:banlanzs/dsh-web-enhanced
  → codeload.github.com/banlanzs/dsh-web-enhanced/tar.gz/<commit>

pnpm install 尊重锁文件、只会重装同一个 commit；update 会重新解析分支 HEAD 并改写锁文件。npm 依赖同理是按版本解析：update 才会移到新发布的版本；要从 Git 源切到 npm 源（或反过来），用显式 add 重写 spec，update 不会自动改写来源。

层列表按「已安装状态」而不是「依赖差异」对齐是刻意的：这样某个包在新版本里才开始声明 dsh.bundle 时，update 也能把它加进层栈。

万一某次 update 没动（pnpm 对 git 依赖偶尔会啃缓存），退路依次是 --force，再不行才是 remove + add：

dsh plugin --profile web update --force dsh-web-enhanced
# 仍然不动时的兜底：显式重装想要的来源
dsh plugin --profile web remove dsh-web-enhanced
dsh plugin --profile web add dsh-web-enhanced             # npm
# dsh plugin --profile web add github:banlanzs/dsh-web-enhanced   # git

开发迭代

本插件不能用 link:（见上文提示——它会复制一份宿主包，从而静默地让所有 host 能力失效）。改用打包重装来迭代：

cd dsh-web-enhanced
pnpm install
pnpm check       # 提交/发布前必跑：typecheck + 全部测试 + 重建 lib/
npm pack         # 产出的 tarball 用于冒烟安装
dsh plugin --profile web remove dsh-web-enhanced
dsh plugin --profile web add ./dsh-web-enhanced-<version>.tgz

开发门槛。 lib/ 是提交进仓库的构建产物——不要手改，每次提交或 npm 发布前必须跑 pnpm check（= rm lib + tsc -b --force + vitest run + tsdown），由 src/ 确定性重建 lib/（CI 的漂移门会核对二者）。check 会删除构建不再产出的文件，所以提交前务必看一眼 git status。

发布到 npm。 本包以包名 dsh-web-enhanced 发布：

npm login
pnpm check
npm publish --access public

npm 不允许覆盖已发布版本：先 bump package.json 的 version（并同步 CHANGELOG）。files 白名单只发布 lib/、cordis.patch.yml、双语文 README、CHANGELOG 与 LICENSE，发布前可用 npm pack --dry-run 核对 tarball。

Windows 上 tarball 安装需要真正的符号链接权限（pnpm 的 importPackage 步骤）。 若报 EPERM ... symlink，可开启开发者模式，或改用 npm / git 安装（不走该路径）。

配置

插件行 config 字段（均有默认值；vision* 各项也可以在 设置 → 插件 → Web 增强 → 识图 里在线编辑，界面保存的值覆盖这些底值、立即生效）：

架构要点

• 零仓库改动：客户端 UI 只注册到既有槽位——conversation.view（工作区视图标签页，内含文件/预览/变更/任务看板/Git 图谱 五个 tab）、shell.overlay（mention 文件浏览器浮层）、conversation.session.header.actions（会话标题旁 titleCluster 行里的分支切换器）、conversation.composer.dock（余额 + 本轮花费行），外加通过 ctx.commandUi.register 注册的两个客户端命令（+ 菜单里的文件 / 文件夹 mention）。未占用布局的 details 槽：那是已被 ui-conversation 的 DetailsPanel 占据的 single 槽，注册进去会顶掉工具详情列。
• 可选服务一律非注入读取：agentPresets、llm、settings、credentials、modelDirectories、commandUi、conversation 都用 ctx.get() 取，缺任何一个只让对应的那一小块降级，不会让插件入口卡住不启动。
• 识图走宿主的「模型可见表面」而不是改适配器：visionIntegration Cordis 服务可逆地包装共享 llm.resolveModelInfo（包装带标记，卸载时只有当前仍是自己的包装才还原，绝不误拆后来者的包装）。agent/pre-step 为含图消息计算描述并写入 session 表面替换（surfaceOp: replace）——模型推导历史读到文字，原文 append 的图片留在对话记录里；包装后的 session.deriveMessages 覆盖替换微任务落盘前的那一步请求，tools/post-execute 对 read_image 结果做同样替换。多模态判定始终读补丁前捕获的原始 resolver。转写引擎 VisionTranscriber 依次尝试 DSH 已配置的视觉模型（llm.stream）、本地 Ollama、OpenAI 兼容端点回退链（回退、内容哈希缓存、分类错误、冷却——这部分健壮性来自 dsh-vision-proxy）。
• 任务执行：agentPresets.resolve() 解析部署默认 preset → 写进 meta.agentPreset → 在 setup 里 mount（与宿主 ensureSession 同序），随后 workspace.attachSession 把会话记到项目上；之后 followup + whenIdle + sessions.flush，结果按 turn/end reason 回写。没有 preset 名册的部署照常运行，只是会话只带宿主根注册的工具。
• 手写 remote contribution：host 方法用 @Remote 装饰器（Typert SRC 模式，宿主网关自动发现 ctx.webEnhanced 服务）；客户端在 apply 里 ctx.remote.$mount() 手写的 src-json contribution，无需 typert 生成管线。
• 持久化：任务记录存 ctx.storageDomain 域 web_enhanced（JSON 后端），重启恢复 running → failed（host-restart）。
• 未提交改动只读不写：三条命令（diff --cached --numstat、diff --numstat、ls-files --others --exclude-standard）——git 算的是三个不同的 diff，没有哪一条能一次回答完。未跟踪文件根本没有 numstat，而唯一能让它有的办法是先入索引（那是改仓库），所以它的新增行数改由宿主侧有界读取数出；文件列表先截断再去读，因此几千个未跟踪文件不会变成几千次读盘。
• 路径安全：所有 fs/git 路径经工作区根校验（拒绝绝对路径、..、反斜杠）；单 ref 参数拒绝 - 开头、.. 范围与空白/通配（防止一个参数变成两个或变成选项）；git 输出有界收集；文件读有字节上限与二进制嗅探。Office 文件在宿主侧用 fflate 解包为有界结构化 blocks（标题/段落/列表/表格，≤ 2000 块、≤ 200×50 表格），绝不产出原始 HTML。
• 唯一的例外：fsBrowse。它列出任意绝对目录，不受工作区根约束——因为 mention 产出的只是一个路径字符串，而用户要的路径可能就在项目外。它只返回名称、类型与大小；读、写、预览仍然全部锁在工作区内。
• 插件管理不改宿主任何文件：设置页注册进既有的 settings.plugins.tab 槽；配置与清单走本插件自己的 Typert 网关，因此不需要像 DSH-vision 那样去改 apiproxy 的 settings 暴露白名单（那是改 node_modules 里的宿主发布产物，每次升级会被覆盖）。remove/update 只在 profile 目录里跑 pnpm、重写该 profile 的 dsh.profile.bundles——与 dsh plugin 完全同一条路径。也没有把 @deepseek-ai/dsh-app-boot（CLI 里这些例程的归属）写成 peer：它是 dsh 安装的依赖而非 profile 的依赖，那样恰好会在这段代码唯一运行的部署里解析失败。
• 预览安全：markdown / CSV / diff / Office / 表格全部渲染为 React 元素，从不 dangerouslySetInnerHTML。markdown 里的 HTML 走白名单映射到对应元素，未知标签只丢标记保留文字，script/style 连内容一起丢；javascript:/data: 链接降级为字面文本（data:image/* 的图片除外），HTML 文件预览进 sandbox="" iframe。

开发

pnpm install
pnpm run check   # typecheck + 全部测试 + 构建（400 个测试，2 个跳过）

构建产物：

• lib/index.js — node half：web-enhanced 函数插件（挂载 WebEnhancedGateway Typert 服务：task*/git*/fs*/balanceGet/pricingGet/modelRouteDescribe/deepseekRateGet/opencodeGoUsageGet/visionStatus/visionConfigGet/visionConfigSet/visionEndpointModels + cron 调度器 + 重启恢复，以及带 settings 命名空间的 VisionInterceptor 识图服务）
• lib/client.js — 浏览器 half：模块加载器闭包格式（window.__ModuleLoader__.load），由 dsh.client manifest 声明
• cordis.patch.yml — bundle 补丁：插入 web-enhanced 行（一个行同时承载 node 与 browser 两个 half）

真机 e2e（无模型 key）

真实链路全跑：临时 dsh web → 安装插件 → 浏览器打开工作区视图里的看板/图谱标签页、会话浮动面板与余额行，全程不 mock：

# 需要宿主构建：DSH_ROOT（默认 ~/.dsh/source/current）内先 pnpm run build
TARBALL_NAME="$(npm pack --silent)"
TARBALL_PATH="$PWD/$TARBALL_NAME"
TARBALL_SHA="$(sha256sum "$TARBALL_PATH")"; TARBALL_SHA="${TARBALL_SHA%% *}"
node scripts/e2e.mjs --smoke --install tarball --tarball "$TARBALL_PATH" --tarball-sha256 "$TARBALL_SHA" --port 3190
node scripts/e2e.mjs --capture --install tarball --tarball "$TARBALL_PATH" --tarball-sha256 "$TARBALL_SHA"   # 顺带刷新 assets/*.png

前置：PATH 上有 dsh/pnpm，以及主仓 web 构建产物（playwright 从主仓解析）。PASS 退出码 0；失败保留 e2e-fail-*.png 截图并打印 dsh-web.log 尾部。

已知限制

• 工作区为视图标签页而非并排列：激活时取代对话记录显示，而不是与其并排；它自身不拥有宽度与折叠状态。
• markdown 中的 HTML 只做白名单渲染：<table> 按结构解析，行内标签映射到对应元素，其余标签只保留文字。<details>、内联 style、自定义元素不还原。
• mention 的项目内列表一次性列出宿主搜索上限（searchMaxEntries，默认 200）内的条目，并保持 skipDirs 过滤（默认 node_modules，.git 恒隐藏）：依赖目录正是几乎不会被引用的路径，列出来会把真正的项目文件挤出这批结果。每层遍历都是文件优先、再进子目录，因此根目录的 TODO.md 这类文档一定在批次内。弹层内的搜索是对这批结果的本地过滤，不是逐键重新查询。要越过上限、走到项目外、或进入被跳过的目录，用第一行的「浏览其他位置…」——它的浏览器不套用 skipDirs 过滤。
• mention 浏览器是应用内的文件管理器，不调系统对话框：宿主的 host.pickDirectory 只选目录且只在 native 能力下可用，浏览器的 <input type="file"> 出于安全也不给绝对路径。Windows 上的盘符列表靠 26 次并发 stat 探测得到（Node 无原生绑定就拿不到盘符表），断连的网络盘符可能让这一步慢上一两秒；未映射为盘符的 UNC 共享（\\server\share）目前走不到。
• Office 预览为结构化视图：docx 的标题/段落/列表/表格与 xlsx 首个工作表可预览；内联样式（加粗/颜色）、图片与多工作表不保留。旧版 .doc/.xls 二进制格式不支持预览。
• 定时任务为 best-effort：tick 粒度 30s，宿主关机期间错过的窗口在启动时补跑一次，不留积压。
• 余额 key 与模型提供商同源（环境变量）；未配置时显示错误态而非报错。切到非 balanceProviders 的渠道时整行隐藏。
• 图谱泳道为简化算法（首父连续性），非 git 完整拓扑着色；提交详情的文件清单按首父 diff 统计，合并提交因此只显示它带进来的改动。
• 未提交改动行：未跟踪文件的行数由宿主读文件数出（git 对未跟踪路径没有 numstat，而生成 numstat 就得先入索引——那是修改仓库），二进制、超过 readMaxBytes 或读取时已消失的文件报 —；同一文件既暂存又继续改过会出现两行（那是 git 算的两个 diff）。HEAD 不在当前绘制范围内时该行置顶且不连线。
• 分支切换不做 stash，也不阻止脏切换：git 会把不冲突的改动带过去，冲突时自行拒绝；这里只是切换前告知并让你确认。
• 插件管理不重载运行中的进程：Cordis 在启动时组合层栈，所以 update/remove 描述的是下一次启动。同理它也不做 enable/disable——那要改的是 profile 的 cordis.patch.yml，与安装是两回事。
• 插件管理只看得到启动时所用的 profile：dsh --profile web 列的是 ~/.dsh/profiles/web 的依赖，装在别的 profile 里的插件不会出现。profile 目录就是 pnpm 的工作目录，跨 profile 操作会在一个此刻并未组合层栈的目录里跑 pnpm。要管别的 profile，用那个 profile 启动，或走 dsh plugin --profile <name>。
• 插件管理需要 PATH 上有 pnpm，且 profile 目录在本插件模块的祖先链上（正常安装即满足；源码检出或测试环境会显示「没有可管理的插件」而不是报错）。同时只允许一个 pnpm 操作在跑，第二个请求会被告知而不是排队。
• 识图至少需要一种转写源：DSH 里配置一个多模态模型、本地 Ollama、或独立识图 API。三者都没有时，发给纯文本模型的图片会被替换为占位描述而不是让整个回合报错，设置页的「识图」标签页会显示原因。该标签页同时就是这三者的配置入口，保存立即生效（vision* 静态配置作为底值保留）。转写质量取决于所选视觉模型的能力上限，不是插件的保证。
• 端点转写会把图片字节（base64、HTTPS）发给配置的 VLM 端点——除非端点是本机服务（如 Ollama），图片会离开本机。除进程内内容哈希缓存外不保存任何东西。DSH 模型路径在同一轮内按图片去重，但不跨轮缓存；端点路径按图片内容跨轮缓存。
• 不要再同时安装 DSH-vision（dsh-image-vision）：两个插件都会打发送补丁、都会对同一张图识别一次。本插件的补丁自身卸载顺序安全，但 DSH-vision 的卸载会还原它自己捕获的方法，仍可能覆盖后来挂上的包装。
• 暂未内置大图缩放（dsh-vision-proxy 里可选的 sharp 步骤）；端点收到的是原始字节，visionMaxTokens 仍会限制转写输出长度。

License

MIT