banlanzs/dsh-web-enhanced

dsh-web-enhanced

English · 简体中文

DeepSeek Harness 的 Web 增强插件：任务看板（含 cron 定时执行）、Git 图谱、VSCode 式资源管理器（文件树 + 预览分栏）/变更面板、DeepSeek API 余额显示，以及纯文本模型的识图（图片理解）。

🔌 生态：仓库已打 #dsh · #dsh-plugin topics —— 欢迎被 @dsh-plugin 收录。

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

功能

| 功能 | 说明 |
|---|---|
| 任务看板 | 「工作区」视图里的任务看板标签页；任务按五列组织（待规划 / 待办 / 进行中 / 已完成 / 已失败）；卡片「执行」在宿主上开一个真实 DSH 智能体会话运行任务提示词，会话按部署的 agent preset 组合（因此拿得到 bash / read_file / write_file 等工具）并附着到任务绑定的项目上，完成后状态与结果自动回写；「查看会话」跳转到执行会话；每张卡片带内联编辑表单（title / prompt / cron / 状态列——done/failed 改回 planned/todo 即重开）；「已完成」列的卡片默认折叠为一行标题（点击展开），「已失败」不折叠，因为那一列的错误信息正是要看的东西；支持 5 字段 cron 定时（如 0 23  * ），到期自动运行，宿主重启后补跑并恢复中断任务。 |
| Git 图谱 | 「工作区」视图里的 Git 图谱标签页；分支泳道 + 提交历史以 SVG 渲染（首父连续泳道 + 合并横向连线）；分支下拉只筛选图谱显示的提交（全部分支 / 单分支），不切换仓库；点击任一提交展开详情：完整 hash、父提交、作者与邮箱、时间、提交正文，以及逐文件增删行数。顶部另有「未提交的改动」一行：空心虚线圆点画在 HEAD 所在泳道上并虚线连到 HEAD，展开后逐文件列出暂存 / 未暂存 / 未跟踪的增删行数（未跟踪文件的行数由宿主读文件数出，二进制或超限报 —）。未提交与历史提交里的每个变更文件都可以点击：在资源管理器预览侧打开该文件的 unified diff，提交以后也能回看。会话标题旁的分支切换器（titleCluster 行）才是真正的 checkout，与图谱筛选是两回事；切换前若工作区不干净会先问一句，并分开报「已跟踪 / 未跟踪」的条数。 |
| 长文本粘贴挂载 | 在输入框粘贴 2000+ 字符的纯文本时不再把草稿撑成一篇长文：插件在宿主处理前拦截粘贴，保存原文并插入一个 已粘贴文本 引用 chip（输入机像图片附件一样渲染）。输入卡上方的 dock 行列出 chip，点击弹窗预览 / 编辑 / 保存 / 移除；发送时由 codec 把 chip 还原为完整文本交给模型，移除 chip 同步删除草稿引用。内容存 localStorage，单条与总条数有界。 |
| 全局系统提示词 | 设置 → 插件 → Web 增强 → 全局提示词：一个开关 + 一段文本，保存进 dsh-web-enhanced-global-prompt settings 命名空间。宿主把它注册为全局 systemPrompt section（order 50——位于所选 Agent 模式的 persona 之后、工具说明之前），因此对所有模式、会话和子代理追加生效；text 每次装配实时读取，保存后下一轮请求立即生效、无需重启 dsh web，关掉开关或留空则不注入。（极简模式把 persona 声明为 complete、整段替换系统提示词，届时全局提示词不会追加。） |
| 工作区视图 | 会话顶部视图栏中的「工作区」标签页，与「对话」「轨迹」并列，内含资源管理器（VSCode 式布局：左侧文件树侧边栏、右侧打开文件的预览）/ 变更 / 任务看板 / Git 图谱四个面板。文件树侧边栏可一键收起/展开（状态持久化），支持整行展开、文件名搜索、点击在右侧打开预览；预览支持 markdown（含 GFM 表格、HTML 表格与行内 HTML）/ HTML（sandbox iframe）/ 代码 / diff（行级高亮 unified diff）/ CSV / 图片 / PDF / 文本 / Office（docx/xlsx，宿主侧结构化转换），且支持源码 / 分屏 / 预览三态与保存；变更页基于真实 git status，支持 stage / unstage / discard 与逐文件 diff。当前面板与展开的目录按工作区持久化。
| 对话节点导航条 | 对话流右缘等距节点串（每条 user 消息一节点）：激活药丸跟随阅读位置（视口内最顶 user 消息）、悬停/聚焦弹 6 行截断预览卡、点击平滑跳转、>11 节点滑动窗口、导航条上滚轮逐条切换、整条可点无需瞄准；.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:['']}))"
node -e "console.log(require.resolve('@deepseek-ai/dsh-typert-protocol',{paths:['/lib']}))"

两条路径必须完全一致。

然后启动：
sh
dsh --profile web

一键安装脚本

clone 后直接运行——脚本会检查前置（dsh / pnpm / 仓库可达），用公开 git URL 安装并提示重启：
sh
git clone https://github.com/banlanzs/dsh-web-enhanced.git
cd dsh-web-enhanced
./scripts/install.sh

更新

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

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

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

万一某次 update 没动（pnpm 对 git 依赖偶尔会啃缓存），退路依次是 --force，再不行才是 remove + add：
sh
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 能力失效）。改用打包重装来迭代：
sh
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-.tgz

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

发布到 npm。 本包以包名 dsh-web-enhanced 发布：
sh
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 增强 → 识图 里在线编辑，界面保存的值覆盖这些底值、立即生效）：

| key | 默认 | 含义 |
|---|---|---|
| cronIntervalMs | 30000 | 调度器最小触发间隔；定时器按最近一次待执行任务一次性布防，无任务时不布防 |
| balanceApiKeyEnv | DEEPSEEK_API_KEY | 余额查询的 API key 环境变量 |
| balanceCacheTtlMs | 60000 | 余额视图缓存时长 |
| balanceBaseUrl | https://api.deepseek.com | 余额端点基址 |
| balanceProviders | [deepseek-official] | 余额行只对这些模型渠道显示；渠道另配了 baseURL 时还要与端点同主机 |
| modelsDevUrl | https://models.dev/api.json | 会话花费估算拉取价格表的地址 |
| modelsDevCacheTtlMs | 21600000 | 价格表缓存时长（6 小时） |
| modelsDevTimeoutMs | 10000 | 价格表请求超时 |
| pricingProviderMap | {deepseek-official: deepseek} | 模型渠道 provider id → models.dev provider id |
| skipDirs | [node_modules] | 文件树/搜索与 mention 选择器跳过的目录（.git 恒跳过；文件浏览器不套用该过滤） |
| readMaxBytes | 1 MiB | 文本读取上限（超出截断标记） |
| writeMaxBytes | 2 MiB | 文件写入上限 |
| binaryMaxBytes | 5 MiB | 二进制预览（base64）上限 |
| gitOutputMaxBytes | 256 KiB | git 单流输出上限 |
| gitMaxCount | 100 | git log 行数上限 |
| gitWorkingMaxFiles | 300 | 未提交改动的文件数上限；也限定了最多读多少个未跟踪文件来数行数 |
| searchMaxDepth / searchMaxEntries | 8 / 200 | 文件搜索深度与条数上限 |
| officeMaxBytes | 5 MiB | Office（docx/xlsx）预览文件大小上限 |
| browseMaxEntries | 500 | mention 浏览器单层目录的条目上限 |
| pluginOpTimeoutMs | 300000 | 单次 pnpm 操作（update/remove）的超时 |
| profileDir | 空 | profile 目录；留空则从本模块位置向上探测。仅用于 profile 不在插件模块祖先链上的部署 |
| visionEnabled | true | 识图集成总开关 |
| visionPatchAdmission | true | 包装 llm.resolveModelInfo，让纯文本模型通过发送门禁与 read_image 门禁（可逆、卸载顺序安全） |
| visionProvider / visionModel | 空 | 指定用于转写的 DSH 模型渠道/模型；留空则从所有已配置渠道自动探测支持图片的模型 |
| visionHarnessModels | [] | 用户勾选的 DSH 模型池 [{provider, model}, …]，按序尝试后才轮到独立 API；非空时替代自动探测（钉选对仍最优先） |
| visionPrompt / visionMarker | 中文详尽描述提示词 / [图片内容描述] | 转写提示词，以及模型看到的图片替代标记 |
| visionBaseUrl / visionApiKey / visionEndpointModel | 空 | OpenAI 兼容 VLM 端点（如 DashScope 兼容模式）；key 依次回退 visionApiKeyEnv → VISION_API_KEY → DASHSCOPE_API_KEY。base URL 或模型任一为空则不启用该来源 |
| visionEndpointModels | [] | 独立端点的模型池；设置页拉取 /models 后多选保存。转写先试 visionEndpointModel（设了的话），再按池顺序逐个试 |
| visionApiKeyEnv / visionAnonymous | VISION_API_KEY / false | 端点密钥环境变量；true 时不带 Authorization 头（匿名/免费端点强制 20s 硬超时） |
| visionTimeoutMs / visionMaxTokens | 120000 / 4096 | VLM 请求超时与输出上限 |
| visionAutoLocalOllama | true | 启动时探测 visionLocalOllamaUrl；检测到本地 Ollama 后把它的第一个视觉模型加进转写链最前（图片不出本机） |
| visionLocalOllamaModel / visionLocalOllamaUrl | 空 / http://localhost:11434/v1 | 优先使用的 Ollama 模型（空则选第一个 vl/vision 模型）与其 OpenAI 兼容基址 |
| visionFallbackModels | [] | 有序回退链 {model, baseURL?, apiKey?, anonymous?, timeoutMs?}；每条可指向不同供应商，无密钥的非匿名条目自动跳过 |
| visionCacheLimit / visionCooldownMs | 200 / 60000 | 进程内转写缓存条数（按图片字节 SHA-256）与刚失败（429/超时）端点的冷却时长 |

架构要点

- 零仓库改动：客户端 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。

开发
sh
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：
sh
需要宿主构建：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 只做白名单渲染： 按结构解析，行内标签映射到对应元素，其余标签只保留文字。、内联 style、自定义元素不还原。
- mention 的项目内列表一次性列出宿主搜索上限（searchMaxEntries，默认 200）内的条目，并保持 skipDirs 过滤（默认 node_modules，.git 恒隐藏）：依赖目录正是几乎不会被引用的路径，列出来会把真正的项目文件挤出这批结果。每层遍历都是文件优先、再进子目录，因此根目录的 TODO.md 这类文档一定在批次内。弹层内的搜索是对这批结果的本地过滤，不是逐键重新查询。要越过上限、走到项目外、或进入被跳过的目录，用第一行的「浏览其他位置…」——它的浏览器不套用 skipDirs 过滤。
- mention 浏览器是应用内的文件管理器，不调系统对话框：宿主的 host.pickDirectory 只选目录且只在 native 能力下可用，浏览器的  出于安全也不给绝对路径。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 。
- 插件管理需要 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