dsh-taskwatch

Read-only task monitor for DeepSeek Harness. A phone-friendly status page plus a GUI sidebar panel, covering sessions, background jobs, subagents, goal rounds, workflows and pending approvals.

DeepSeek Harness 的只读任务监控：一个适配手机的只读状态页，加一个 GUI 侧边栏面板， 覆盖会话、后台任务、子代理、目标轮次、工作流与待审批事项。

展开一个会话后，它的目标、待介入事项、后台任务、子代理与最近对话都在原地：

两张图里的会话、任务、对话全是演示用的假数据，不是任何真实会话。它们由 docs/demo.html 渲染——那个文件是 scripts/make-demo.mjs 从 lib/page.html 生成的，你可以直接用浏览器打开它，点着看，不需要装任何东西，也不会发出网络请求。

为什么需要它

DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 danger-full-access。把整个 GUI 暴露到公网，等于把一台能执行任意命令的机器的入口挂出去。

这个插件的做法是不暴露 GUI，另开一组窄接口：

• 读：把状态渲染成一份手机看得懂的页面，只放行这一条路径就够。
• 写：/taskwatch/chat/* 把 DSH 自己的会话运行时接到手机上 —— 直接对话、 逐字收回复、随时停止、切换会话与模型。写入口只有 4 条，全部列在下面。

采集面完全通过 ctx.get(...) 软读取服务，任何一个服务不存在都只会让对应的那一块 留空，不会让插件挂载失败。对话那一组同理：拿不到 sessionController 时只让这一个 功能返回明确错误，不影响只读页面。

采集面

区块	内容
需要你介入	等待中的 approval/request 与 user-questions/request
会话	运行/空闲、最后活动时间、该会话在跑的后台任务数、preset、是否仅日志
会话详情	点开后：目标、待介入事项、属于它的后台任务与子代理、最近对话
目标	phase、轮次 started/max、activation、阻塞原因
后台任务	id、label（多行命令已折成单行）、kind、status、生命周期时长、属主会话
子代理树	层级、深度、父会话、activity、mode
工作流	当前 phase、日志条数、已运行时长
采集诊断	采集过程中单项失败的原因（不静默吞掉）

HTTP 路由

读（GET）：

路径	类型	说明
/taskwatch	HTML	手机页：以对话为主，顶部状态条点开是任务详情
/taskwatch/data	JSON	全部状态的快照，带 ETag，未变化回 304
/taskwatch/session?id=&limit=	JSON	单个会话的最近对话（limit 上限 60，默认 20）
/taskwatch/chat/sessions	JSON	可对话的会话列表（不含子代理会话）
/taskwatch/chat/models	JSON	可选模型目录
/taskwatch/chat/titles?ids=	JSON	批量补会话标题（最多 20 个，宿主缓存 10 分钟）
/taskwatch/chat/page?...	JSON	往更早翻会话历史
/taskwatch/chat/stream?sessionId=	SSE	跟随一个会话：开场快照 + 增量事件 + 逐字输出
/taskwatch/manifest.webmanifest	JSON	PWA manifest
/taskwatch/sw.js	JS	service worker
/taskwatch/icon-192.png · /taskwatch/icon-512.png	PNG	图标

写（POST）—— 只有这 4 条：

路径	请求体	说明
/taskwatch/chat/send	{sessionId,text,mode?,timeZone?}	给会话发一条消息
/taskwatch/chat/cancel	{sessionId}	停止当前这一轮
/taskwatch/chat/create	{}	新建会话（不接受客户端指定工作目录）
/taskwatch/chat/model	{sessionId,provider,model}	切换该会话使用的模型

全部注册在 ctx.webServer 上，不代理 DSH 自身的 /api，也不转发任意路径。 写入口就只有上面 4 条 —— 契约测试会正面清点路由表，增删都会让构建失败 （早先那条断言写的是"源码里不出现 method === 'POST'"。加了 4 个写路由之后它 照样通过，是条假绿灯：它证明的是"没这么写"，不是"没有这个能力"）。

对话路由为什么这么薄

手机端要的「像 ChatGPT 一样对话」，DSH 内部本来就有 —— sessionController 提供 prompt / follow / cancel / list / create / page / modelCatalog / selectModel。所以这个插件一行 LLM 调用、一行流式解析都没写，只是把这几个方法 转成 HTTP。三个实测出来的坑记在这里：

• follow() 返回的本来就是为传输设计的 wire 帧（SessionWireEvent.data 是 JsonValue），可以安全地逐帧 JSON.stringify；不要去碰会话活对象。
• SSE 响应必须显式带 x-accel-buffering: no，否则 nginx 会把流式缓冲成一次性吐出。
• tool/result 帧的 callId 不在顶层，在 data.message.source.callId。 按顶层读会一直拿到 undefined，表现是每来一个工具结果就多插一张错卡。
• 会话标题只能从事件日志的 session/title 帧里取 —— SessionSummary 里没有 title 字段。分页语义也是实测的：throughSeq 超过会话 cursor 会报 past cursor N，而 N 正是需要的值，于是用错误信息一步重试。

手机页为什么这样排

要解决的是「小白点进来也看得懂」。所以页面不做仪表盘：顶部一行说人话的状态 （点开才是原来那张数据表），中间是对话，底部是输入框，数据表格收进抽屉。

两个具体决定：

• 工具调用翻译成人话。pwsh → 「运行命令」、grep → 「搜索内容」、subagent → 「派发子任务」。用户不需要知道 pwsh 是什么；卡片上还给一行命令/路径摘要，状态用 进行中 / 完成 / 失败三态。这是"看得懂进度"最关键的一处。
• 逐字输出只改一个节点。整页重建会让长会话每来一个字都重排一次。

页面为什么不做整页重建

页面每 3 秒轮询一次，但数据没变就完全不碰 DOM，只刷新右上角时间戳。首版是 root.innerHTML = h 全量重建，结果是每 3 秒把页面拆一次：展开的东西 3 秒后被抹掉， 滚动位置被打断，看起来像「不刷新」和「点不动」——那是同一个原因。

这里有个容易漏掉的坑：比较序列化结果时不能把 generatedAt 算进去。 它是每次采集 都不同的 Date.now()，带着它比较，签名就永远在变，「数据没变就不碰 DOM」实际上是 一句空话，页面照样每 3 秒整页重建。所以客户端算签名、服务端算 ETag 时都先把这个 字段归一化，两边保持同一套判据。

而「有东西在跑的时候」仍然要重画：画面上的时长要一直往上走。所以静止时就真的不碰 DOM，有运行中的会话、后台任务、子代理或工作流时才重画。

展开状态与对话缓存存在 JS 对象里，跨轮询保留；点击用事件委托挂在常驻容器上， 所以内层 DOM 重建也不会丢监听。对话按需懒加载，点开一次即缓存。

轮询在服务端和手机上各收一次口

页面每 3 秒轮询，而这个页面的主要用途是手机——最常见的状态是「揣在兜里、屏幕已熄」。 不处理的话，一个常驻后台的标签页会永远每 3 秒发一次请求。所以两头都做了收敛：

• 客户端：监听 visibilitychange，页面隐藏时 clearInterval 停止轮询，回到前台立刻 补一次请求。手机上省的是流量和电。
• 服务端：snapshot() 一次要问一圈服务（每个 agent 的 jobs、每个会话的 eventAt/title/goal、每个 agent 的 listDescendants）。现在同一份采集在 2 秒 TTL 内被复用，并发请求共用同一个 Promise 而不是各算各的——手机、桌面面板和 多个标签页同时开着时，这一层把开销从「每请求一次全量采集」压成「最多每 2 秒一次」。
• 带宽：/taskwatch/data 返回 ETag 并在未变化时回 304，手机上只交换一个头而不是 整份 JSON。

最后一条有个必须成对的地方：页面取数用的是 cache:'no-cache'，不能用 no-store。 no-store 会让浏览器根本不保存响应，也就永远不会带 If-None-Match 回来，服务端那段 304 会变成死代码。这两处因此都在契约测试里钉住了。

采集失败时不能伪装成正常

这是监控工具最危险的失败姿态，所以单独说清。

宿主采集异常时 /taskwatch/data 回的是 HTTP 200 + { "error": ... }。如果客户端 把这份载荷当数据用，画出来就是一块「全部为 0」的板子：0 个会话、0 个后台任务、 「当前没有等待中的审批或提问」。它看起来像「真的没有任务」，而不是「没读到」。

所以两半都显式处理 error 字段，把它当错误而不是数据：

• 手机页：tick() 先查 d.error，命中就只在页脚写「采集失败：…」并保留上一份 可用快照，绝不拿它去重画。
• GUI 面板：把 snap.error 视为错误，继续渲染上一份可用快照，并在顶部挂一条 「数据可能已陈旧（快照时间 HH:MM:SS）：…」的横幅。一次网络抖动同样只产生这条横幅， 而不是把整块面板清成空白 —— 监控面板的价值恰恰在于「断开时还能看到最后一帧」。

同一类问题的另一面是轮询的乱序：并发请求下，较早发出的响应完全可能晚回来。两半 都用一个自增序号只接受最新一次的结果，避免旧数据覆盖新数据。

/taskwatch/session 的两条限制

1. 只能读活着的会话。 ctx.sessions 是内存存储，get(id) 返回 undefined 时接口 会明确报错「这个会话不在内存里（已落盘但未加载的会话读不到）」，而不是返回一个 空的 messages —— 后者会让人误以为那个会话真的没说话。
2. 只读不写。 没有发送消息、批准审批、打断运行的入口。要做到那些，必须把 DSH 的 Web GUI 暴露出去，那是另一个量级的风险，本插件刻意不做。

消息只取叶子字段（role、text、工具名、时间），不把活的会话日志对象序列化出去。

GUI 面板

lib/client.js 注册一个侧边栏面板（sidebar.panellist），数据取自同源的 /taskwatch/data，不需要任何 host RPC。样式全部挂在插件自己的 fiber 上， 卸载即还原。

面板右上角有一个指向手机页的链接，方便直接把 /taskwatch 复制到手机上打开。

面板和手机页在轮询上是对称的：窗口不可见时 clearInterval 停止轮询，回到前台立刻 补一次请求。桌面这一半容易被忽略，但它的典型用法恰恰是「GUI 最小化、拿手机看」。

安装

dsh plugin --profile web add dsh-taskwatch

装完需要重启 dsh web：插件行来自 profile 的 bundle 图，而 client 侧模块元数据 按 specifier 缓存且没有失效路径，所以增删插件一律要重启才生效。

本包没有构建步骤：lib/ 是提交进仓库的、可直接运行的产物，客户端 bundle 就是 一个调用 window.__ModuleLoader__.load({ id, factory }) 的普通脚本。从源码安装不需要 任何构建授权（allowBuilds）。

本地开发时也可以直接指向工作副本：

dsh plugin --profile web add <你的绝对路径>/dsh-taskwatch

补丁里引用插件有两种写法，注意区别：bundle 自带的 cordis.patch.yml 用包名 （由 profile 的 node_modules 解析），而 profile 自带补丁里若写路径，必须是绝对路径 （相对路径是相对该补丁文件解析的，跨盘会失败）。

在外网 / 手机上访问（需要你自己叠一层）

本插件自己不做鉴权，只监听回环。 它提供的是「可被安全转发的只读源」，转发这一层 由你自己的隧道或反向代理负责。一个已验证可用的组合是：

手机 / 外网
  └─ HTTPS  <你的域名>                反向代理：TLS 终止 + basic auth
       └─ 隧道回到本机                 ssh -R，或任何等价隧道
            └─ 本机只读中继             校验应用层共享令牌
                 ├─ /taskwatch、/taskwatch/data、/taskwatch/session → DSH 的回环端口
                 └─ manifest / sw.js / 图标                          → 中继本地文件

配套的只读中继是刻意做成另一件事的，不属于本插件：它是几十行的零依赖 Node 脚本， 把白名单里的固定路径转发到 DSH 的回环端口，其余一律 404。想自己写的话，要点就四条：

1. 白名单硬编码，不要让上游路径可配置 —— 否则它就成了一个任意代理。
2. 只允许 GET/HEAD，不接受请求体，不转发 /api。
3. 自带一层共享令牌，定长比较（timingSafeEqual），并且不要把令牌转发给上游。
4. 转发时要带上查询串。这一点踩过坑：漏掉它时 /taskwatch/session 会返回 HTTP 200 但内容永远是「缺少 id 参数」——状态码看着完全正常，只是数据永远为空。

PWA 外壳由中继本地提供（而不是转发上游），这样它不随上游插件的版本变化而失效； 页面文件与插件共用同一份，避免两边漂移。

安全边界

• 写入口等于一台终端。一旦放行 /taskwatch/chat/send，能打开这个页面的人就能在 这台机器上驱动 agent —— 而 DSH 默认 danger-full-access。所以中继那一层必须 同时有 TLS、HTTP basic auth 和应用层令牌，三层缺一不可；/taskwatch/chat/* 能不转发就不转发。手机页默认只在已有会话上操作，新建会话也不接受指定工作目录。

• 手机上做的每一步都会落进该会话的日志，桌面上打开同一个会话就能看到全部经过 —— 这是"远程操作可追溯"的那一半。

• 插件的路由只在回环上监听，从不对外。

• 页面带 X-Robots-Tag: noindex, nofollow，响应带 nosniff。除 /taskwatch/data （见下）外一律 no-store。

• service worker 的作用域限定为 /taskwatch（注册时即指定，脚本也放在 /taskwatch/sw.js），不允许它有机会拦截主 GUI 的请求；/taskwatch/chat/* 在 fetch 里被显式放过，尤其不能让 SSE 被它包一层。

• 状态数据不会被离线复用：外壳可以离线打开，但 /taskwatch/data 与 /taskwatch/session 每次都必须回源。断网时返回一份显式的 offline: true 空快照并在 页面上明说 —— 对监控来说，看到过期状态比看到断连更危险。

  这里有一处刻意的例外值得说清：/taskwatch/data 用的是 no-cache + ETag，而不是 no-store。区别在于 no-cache 允许浏览器存一份副本，但每次都必须回源校验， 只有服务端确认「内容没变」才回 304 并复用。所以页面上永远不会出现未经校验的旧数据， 而每次轮询省下了整份 JSON 的传输。要复用的只是这一份刚被服务端确认过的字节。

已知限制

• 界面文案目前是中文，还没有做多语言。
• /taskwatch/session 只覆盖内存中的活跃会话（见上）。
• 服务没有鉴权，不要把它直接暴露到公网；请自行在前面加一层。
• 会话、任务、子代理各列表最多渲染 40 条（GUI 面板是 30 条，且不像手机页那样提示 「还有 N 条未显示」），避免长会话把页面拖慢。工作流列表目前没有上限——宿主只收 运行中的工作流，通常很小，但契约上没有上界。
• 单条消息文本超过 4000 字符会被截断。
• 手机页只能对话，不能审批。状态条会告诉你「有 N 件事在等你」，但批准/回答仍然 只能在桌面上做 —— 也可以直接在对话里让 agent 继续，那才是它的等价物。
• 子代理会话不出现在手机列表里。它们是宿主内部的干活会话（origin: subagent）， 没有父地址连日志都读不了（分页会报 subagent Sessions require their durable parent address），混进列表只会让"该点哪个"更难。
• 冷会话标题要现读一次事件日志（每个会话 1~2 次持久化读，实测约 0.5 秒/次）。宿主侧 缓存 10 分钟、手机侧缓存在 localStorage，所以只有第一次打开会话列表会花一两秒， 而且是每 4 个一批刷出来、不是干等到最后。
• 会话列表只补最上面 12 条的标题；再往下的仍显示目录名，滚动不会触发补取 （下次打开才会）。
• 手机页把会话 id 显示成前 10 位加省略号，但那只是排版：完整 id 仍在 data-sid 属性里，因为点击展开要用它。不要把短显示当成脱敏。
• 页面还没有设 CSP。它与 DSH Web GUI 同源，而后者没有鉴权且默认 danger-full-access，所以任何一次漏转义都等于一台能执行任意命令的机器的入口。 目前模型正文、工具提示、工具名、会话标题这四处要么走 textContent、要么经 esc()，也有契约测试钉着 —— 但要说清那条测试的能力边界：它是代理， 盯的是已知的四个入口，不等于"全页面无 XSS"。加一层 Content-Security-Policy （脚本用 sha256 hash 而非 unsafe-inline）会是更结实的纵深防御。这是本项目 最值得做的下一步加固。

开发

node scripts/check-bundle.mjs   # 客户端 bundle + 宿主契约 + 页面的测试（54 项）
node scripts/make-icons.mjs     # 重新生成图标（自实现 PNG 编码，零依赖）
node scripts/make-demo.mjs      # 生成 docs/demo.html（假数据，供截图与预览）

（check / icons / demo 也都有对应的 npm script。）

check-bundle.mjs 不只检查客户端：它还真的 import 宿主半边，断言 name / apply / inject 三个导出都在，并把 cordis.patch.yml、exports、 dsh 元数据一并核对。

为什么宿主也要钉住：Cordis 的 inject 决定框架等哪些服务就绪后才调用 apply。 webServer 的服务是在启动阶段之后才发布的，而 apply 在组合期就会被调用—— 只写 ctx.get('webServer') 软读会在那一刻拿到 undefined，于是整段路由注册被 静默跳过。现象是插件"装好了、也不报错，但 /taskwatch 一律 404"，极难定位。 （v1.0.0 正是踩了这个坑。）同理 kind:'prefix' 与 kind:'exact' 都合法，但 重复的 (kind, path) 会让 register() 抛错——所以路由路径也纳入断言。

scripts/make-icons.mjs 是手写 PNG 编码（Node 内置 zlib + 自实现 CRC32），满幅不透明 方形，图形落在中心 80% 安全区内，因此同一个文件既能当普通图标也能当 maskable。

scripts/make-demo.mjs 从 lib/page.html 生成演示页，只把取数逻辑换成一份固定 假数据。之所以是生成而不是手写：手写就意味着 CSS 与结构有两份副本，必然漂移，截图会 慢慢变成一张不像当前 UI 的图。README 里那两张图就是从生成物截的，所以只要 page.html 变了，重跑脚本再截一次就与实现一致。

许可证

Apache-2.0，见 LICENSE。