dsh-in-hand 0.0.0-stage → 1.5.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,417 @@
-# Temporary Holding Version
+# 掌上 DSH（dsh-in-hand）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**掌上 DSH（dsh-in-hand）** —— 手机端的 DeepSeek Harness，不用装 App。 它起初只是一份只读的**任务监控页**——让你在手机上
+瞄一眼 DSH 有几个任务在跑、有没有事在等你；后来接上了 DSH 自己的会话运行时，长成了手机浏览器里
+的 DSH 客户端：左上角会话列表、右上角新建对话、输入框上方是当前会话的实时指标（轮次 / 步数 /
+token 用量 / 缓存命中率 / 上下文占用），可以直接对话、逐字跟随输出、随时打断。
+
+没有 App：不需要原生代码、不需要打包、不需要上架、不需要装任何东西——浏览器打开，用「添加到
+主屏幕」就当一个 App 用（PWA，只要求 HTTPS 或 localhost）。
+
+A phone client for DeepSeek Harness with **no app to install**: a plain read-only task monitor
+that grew into the phone-side DSH client. Talk to your sessions from the phone, watch the reply
+stream in, interrupt whenever you want; it reuses the desktop GUI's design tokens and adds a live
+metrics row above the composer.
+
+![手机端对话页（亮色）](docs/screenshot-1.png)
+
+手机端不只是状态板：可以直接对话、逐字跟随输出、随时打断。连续的工具调用会折叠成
+一行「N 个步骤」，**失败的那一步永不隐藏**；助手回复支持轻量 markdown（标题、列表、
+行内代码、代码块），过宽的代码块会提示可以横滑。
+
+![会话抽屉（暗色）](docs/screenshot-2.png)
+
+会话抽屉、状态卡片、输入框等全部走客户端同一套 design token —— 上图的亮色与这图的
+暗色都是真值，不是猜的近似色。所以它看起来像客户端的一部分，而不是另一个 App。
+
+> 两张图里的会话、任务、对话**全是演示用的假数据**，不是任何真实会话。它们由
+> `docs/demo.html` 渲染——那个文件是 `scripts/make-demo.mjs` 从 `lib/page.html`
+> 生成的（`npm run demo` 重新生成），你可以直接用浏览器打开它，点着看，不需要装
+> 任何东西，也不会发出网络请求。契约测试会校验它与当前页面构建结果一致，防止它
+> 悄悄停在旧界面上。
+
+## 从任务监控长成手机端
+
+第一版只有「读」：一份只读页面，把 DSH 的会话、后台任务、子代理、goal、工作流与待批准
+渲染成手机上看得懂的样子。目的很朴素——不用坐到电脑前，也能知道它现在在干什么、有没有
+事在等你。
+
+后来发现同一组窄接口能接上 DSH **自己的**会话运行时，于是「写」只用了 4 条路由就够：
+对话、逐字收回复、随时停止、切换会话与模型。**读是监控，写是对话**——两者共用一套令牌和
+一条反向隧道，始终不碰 GUI。
+
+所以这里没有 App 可装：没有原生代码、没有打包产物、没有应用商店。手机上进一次「添加到主
+屏幕」，之后它就是一个图标；页面按请求读盘、壳由 Service Worker 换版，所以代码更新后下一次
+打开就会跟上。
+
+## 手机上怎么打开（不用装 App）
+
+1. 在跑 DSH 的电脑上启用本插件，让它监听一个本地端口（见下文各章节）。
+2. 电脑侧起一个**反向隧道 / 中继**，把那个端口映射到一个 **HTTPS** 地址。
+   PWA 的 Service Worker 只在 **HTTPS（或 localhost）** 下工作——纯 HTTP 能看页面，
+   但装不到手机桌面，也没有离线壳。
+3. 手机上打开那个 HTTPS 地址，首次用一次性**配对码**换一个长期令牌，之后自动续期；
+   用浏览器的「添加到主屏幕」就能当 App 用。
+
+> 反代与隧道属于部署细节，本仓库只负责 DSH 这一侧：域名 + nginx + `ssh -R` 可以，
+> Tailscale、Cloudflare Tunnel、ngrok 之类同样可以（它们都能免费给出 HTTPS）。
+> **自己的专属入口链接里带访问令牌，等于完整控制权，绝不要提交到本仓库。**
+
+> 两张图里的会话、任务、对话**全是演示用的假数据**，不是任何真实会话。它们由
+> `docs/demo.html` 渲染——那个文件是 `scripts/make-demo.mjs` 从 `lib/page.html`
+> 生成的（`npm run demo` 重新生成），你可以直接用浏览器打开它，点着看，不需要装
+> 任何东西，也不会发出网络请求。契约测试会校验它与当前页面构建结果一致，防止它
+> 悄悄停在旧界面上。
+
+## 为什么需要它
+
+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/file?id=` · `?path=` · `?info=1` | 二进制 / JSON | 交付文件：附件走 `id`，绝对路径走白名单根（图片 / PDF / 文本 / 视频）；`info=1` 只回元数据 |
+| `/taskwatch/chat/sessions` | JSON | 可对话的会话列表（**不含子代理会话**） |
+| `/taskwatch/chat/workspaces` | JSON | 新建对话可选的工作区（现有会话的 `cwd` + 固定候选 + 环境变量追加；只列真实存在的目录） |
+| `/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` | `{}` 或 `{workspace}` | 新建会话；`workspace` 必须命中 `/taskwatch/chat/workspaces` 列出的路径 |
+| `/taskwatch/chat/model` | `{sessionId,provider,model}` | 切换该会话使用的模型 |
+
+全部注册在 `ctx.webServer` 上，不代理 DSH 自身的 `/api`，也不转发任意路径。
+写入口就只有上面 4 条 —— 契约测试会**正面清点**路由表，增删都会让构建失败
+（早先那条断言写的是"源码里不出现 `method === 'POST'`"。加了 4 个写路由之后它
+照样通过，是条假绿灯：它证明的是"没这么写"，不是"没有这个能力"）。
+
+### 手机能选工作区，但选不了任意目录
+
+「在手机上新开一个对话」得能指定在哪个目录开工，否则只能落在部署默认值上。但
+`sessionController.create()` 收的是绝对路径（`cwd` / `workspaceId`）—— 直接透给公网
+客户端，等于把宿主的磁盘交出去。所以拆成两件事：
+
+- **选择权给手机**：`GET /taskwatch/chat/workspaces` 回候选清单，页面只负责挑；
+- **决定权留服务端**：`POST /taskwatch/chat/create` 拿客户端发来的字符串去清单里
+  **逐字比对**，命中才写进 `cwd`，否则直接报错。
+
+清单三个来源：现有会话的 `cwd`（你最近在哪儿干活，天然是你自己认过的目录）、
+环境变量 `DSH_TASKWATCH_WORKSPACES`（`;` 分隔，默认 `D:\Projects`，装到别处改它）、
+固定候选。不存在的目录用 `statSync` 过滤掉 —— 手机上少一个点进去才报错的入口。
+
+### 对话路由为什么这么薄
+
+手机端要的「像 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 正是需要的值，于是用错误信息一步重试。
+
+### 交付文件为什么按内容识别，而不是按扩展名
+
+手机端要能**直接看到**交付的图和 PDF（而不是只收到一个文件名），所以加了一条只读的
+`/taskwatch/file`。它的安全边界抽在 `lib/files.js` 里，配 36 项边界测试：目录穿越、
+同前缀兄弟目录、白名单外路径、realpath 复查（防符号链接逃逸）、`.svg`/`.html`/`.js`
+一律拒绝。
+
+一个真实验收抓到的教训值得写下来：宿主附件库是**内容寻址**的，模型产出的图落在
+`~/.dsh/attachments/v1/objects/<hash>` —— **名字就是哈希、根本没有扩展名**。
+最初只按扩展名判类型，于是最常用的那条路（"把刚生成的那张图发我"）被判成
+`unsupported-type` 直接 403。而演示页一切正常，因为它用的是 data URI 和有扩展名的
+路径 —— 这类「演示绿、真机红」的差异，只有端到端跑一次才会露出来。
+
+现在：有扩展名走快路；没有扩展名就读前 16 字节按魔数识别（PNG / JPEG / GIF / WebP /
+PDF / ZIP / MP4）。这是**按内容识别**，不是"按内容放行" —— html / svg / js 没有魔数，
+仍然走不通，白名单没有被放宽。
+
+### 手机页的动效为什么这么克制
+
+第 10 节「纸墨微动」：静态是一张纸，动起来像墨。位移 ≤3px、时长 120–320ms、
+曲线统一"起步快、末段收"，**每个动效都携带信息** —— 在跑 = 一圈墨环在转、
+完成 = 勾自己画出来、失败 = 顿一下、图 = 骨架纸纹后显影、新消息 = 浮标弹一下。
+不放光、不放烟花、不为动而动。
+
+两条硬约束写进了契约测试（不靠肉眼）：
+
+1. **入场动画必须由 JS 按"状态刚刚变化"加的类门控**。挂在会被整段重渲染的节点上，
+   每 3 秒轮询就重放一次，观感从"灵动"变"抽搐"。
+2. **"隐藏"只能挂在 JS 之后加的类上**。先藏内容、等 JS 显示是这类动效最常见的自伤：
+   JS 一旦不跑，图片就永远看不见。
+
+缩小动效时也不是简单全关：墨环变成静态描边、骨架图直接可见 —— 动效可以没有，
+状态语义不能丢。
+
+### 手机页为什么这样排
+
+要解决的是「小白点进来也看得懂」。所以页面**不做仪表盘**：顶部一行说人话的状态
+（点开才是原来那张数据表），中间是对话，底部是输入框，数据表格收进抽屉。
+
+两个具体决定：
+
+- **工具调用翻译成人话**。`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 最小化、拿手机看」。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-in-hand
+```
+
+装完需要**重启 `dsh web`**：插件行来自 profile 的 bundle 图，而 client 侧模块元数据
+按 specifier 缓存且没有失效路径，所以增删插件一律要重启才生效。
+
+本包**没有构建步骤**：`lib/` 是提交进仓库的、可直接运行的产物，客户端 bundle 就是
+一个调用 `window.__ModuleLoader__.load({ id, factory })` 的普通脚本。从源码安装不需要
+任何构建授权（`allowBuilds`）。
+
+本地开发时也可以直接指向工作副本：
+
+```sh
+dsh plugin --profile web add <你的绝对路径>/dsh-in-hand
+```
+
+补丁里引用插件有两种写法，注意区别：bundle 自带的 `cordis.patch.yml` 用**包名**
+（由 profile 的 `node_modules` 解析），而 profile 自带补丁里若写路径，必须是绝对路径
+（相对路径是相对该补丁文件解析的，跨盘会失败）。
+
+## 在外网 / 手机上访问（需要你自己叠一层）
+
+**本插件自己不做鉴权，只监听回环。** 它提供的是「可被安全转发的只读源」，转发这一层
+由你自己的隧道或反向代理负责。一个已验证可用的组合是：
+
+```
+手机 / 外网
+  └─ HTTPS  <你的域名>                反向代理：TLS 终止
+       └─ 隧道回到本机                 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 + 应用层令牌**，`/taskwatch/chat/*` 能不转发就不转发。手机页默认只在**已有**
+  会话上操作，新建会话也不接受指定工作目录。
+- **不要给那一层加 HTTP basic auth。** 这条是踩出来的：iOS Safari 在发起 service
+  worker 脚本请求（`/taskwatch/sw.js`）时**不附带** Basic 凭据，于是那个请求 401、
+  新 SW 永远装不上，手机就一直停在旧页面上 —— 而服务端一切正常，从外部完全查不出
+  异常。basic auth 也是三层里**最弱**的一层（一个可共享的静态口令，改一次要在所有
+  设备上重输）。要免密码登录，正确做法是让中继发一张**有时效的 cookie**（例如本机
+  显示的 6 位配对码换 30 天 cookie，并且每次访问滑动续期），而不是加一层口令。
+- 手机上做的每一步都会落进该会话的日志，桌面上打开同一个会话就能看到全部经过 ——
+  这是"远程操作可追溯"的那一半。
+- 插件的路由只在**回环**上监听，从不对外。
+- 页面带 `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`）会是更结实的纵深防御。这是本项目
+  最值得做的下一步加固。
+
+## 开发
+
+```sh
+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](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh bundle patch: 把本插件插进 profile 的层栈。
+- insert:
+    - id: dsh-in-hand
+      name: dsh-in-hand