@konnga/dsh-hud 0.7.1 → 0.8.0

package/README.md

@@ -1,107 +1,125 @@
 # dsh-hud
 
-> DeepSeek Harness 的当前工作区面板：分支、ahead/behind、脏状态、改动清单与差异（全部只读），并告诉你**这个会话改过哪些文件**、**审到哪了**。
-> A read-only workspace Git panel for DeepSeek Harness — plus per-session change attribution and review progress.
+> 一个只读的工作区 Git 面板：分支、ahead/behind、改动清单与差异，外加「这个会话改过哪些文件、审到哪了、跑了什么工具」。
+> A read-only workspace Git panel for DeepSeek Harness, with per-session change attribution.
+
+![输入框上方的两枚胶囊：左边是 Git 状态，右边是工具与技能](docs/images/capsules.webp)
+
+*左：工作区名 · `git:(分支*)` · ahead/behind · 改动计数 · 本会话改过几个文件。右：每个工具的调用次数、正在跑什么、以及会话调用过哪些技能 —— 图中 `aihot ×1` 是红的，因为那次调用失败了。*
 
 ## 安装
 
-在桌面端「设置 → 插件 → 添加插件」里填包名 `@konnga/dsh-hud`。
+桌面端「设置 → 插件 → 添加插件」里填 `@konnga/dsh-hud`。
 
-本地开发时把 profile 的依赖指向仓库（改动即时可见；客户端代码仍需重启应用才重读）：
+本地开发时把 profile 的依赖指向仓库（改动即时可见；客户端代码要重启应用才重读）：
 
 ```json
 "@konnga/dsh-hud": "link:/path/to/dsh-hud"
 ```
 
-## 界面
+## 你会看到什么
+
+### 胶囊（输入框上方）
+
+```
+dsh-hud · git:(main*) ↑1 ↓2 M4 A1 ?1 │ ●3
+```
 
-### 胶囊（输入框上方那一行）
+- `dsh-hud` —— 工作区名（当前会话的目录名）。太长从中间省略，完整路径看悬停。
+- `git:(main*)` —— 分支。`*` 表示工作区不干净；detached 时是 `git:(detached abc1234)`。
+- `↑1 ↓2` —— 与上游的领先 / 落后（为 0 不显示）。
+- `M4 A1 ?1` —— 改动计数，只列非零项：`M` 修改 · `A` 新增 · `D` 删除 · `R` 重命名 · `C` 复制 · `T` 类型改变 · `?` 未跟踪 · `!` 冲突。
+- `●3` —— 本会话改过 3 个文件（没有就不显示）。
+
+点它开面板；悬停给出完整路径、上游与各类计数。**不在 git 仓库里也会显示**（只有工作区名 + `git:(非 git 仓库)`）。
+
+### 工具胶囊（同一行的右边，只在跑过工具后出现）
+
+```
+◐ bash: pnpm test 1.2s                                     ← 正在跑（秒数实时跳）
+✓ bash ×16 │ ✓ apply_patch ×6 │ skills: office-xlsx ×2 +2   ← 空闲
+```
 
-`⎇ feat/x* ↑1 ↓2 M4 A1 ?1 │ ●3`
+- 每个工具一个计数；前面的 `✓` / `✗` 是**它自己最近一次调用**的结果。
+- `skills:` 后面是会话调用过的**技能名**（不是"技能调了几次"—— 看得出是哪一个）。
+- 最多铺 3 个工具、2 个技能，其余收成 `+k`；悬停里有完整清单与最近几条的执行结果。
 
-- `⎇ 分支`：detached 时是 `detached <短oid>`；过长中段省略。
-- `*` 工作区不干净；`↑n` / `↓n` 与上游的领先 / 落后（为 0 不显示）。
-- 简写符只列非零项：`M` 已修改 · `A` 已暂存新增 · `D` 已删除 · `R` 重命名 · `C` 复制 · `T` 类型改变 · `?` 未跟踪 · `!` 冲突。
-- `│ ●n` 表示本会话改过 n 个文件（没有就不显示）。
-- 点胶囊开面板；悬停给出工作区路径、上游与各类计数。
+### 面板（点胶囊打开）
 
-### 面板
+![面板：左边是改动概览与本会话改了哪些、改动清单、最近提交、标签；中间是这次提交的明细；右边是差异](docs/images/panel.webp)
 
-标题栏可拖动（双击复位），`⟳` 刷新 · `⌖` 复位位置 · `✕` 收起。自上而下：
+*上图是「看某次提交」时的样子：左边是面板本身，中间是这次提交改了哪个文件，右边是差异。标题栏可拖动，`⟳` 刷新 · `⌖` 复位位置 · `✕` 收起。*
 
-1. **仓库路径 · 上游 · 短 oid**。
-2. **改动概览**：按类型分组的彩色计数，只显示非零项；干净时写「工作区干净」。
-3. **本会话改了哪些**：`本会话改过 3 个文件 · 另有 2 个可能相关 · 1 个已不在 git 现状里`，右边一排开关：
-   - `只看本会话改的`：清单只留本会话动过的文件（含「可能相关」）。
-   - `侧栏 常亮 / 悬停 / 关`：侧栏会话行上那枚状态标记的档位，**默认常亮**。
-   - `只看最近一轮`：只留最近一轮改过的文件（拿得到回合信息时才出现）。
-   - `已审 3/8` 与 `清空已审`：有已审标记时才出现。
-4. **改动清单**：每行 `标记 状态字母 路径`，重命名读作 `旧 → 新`。
-   - 行首三态：`●` 确定改过（经写文件 / 编辑工具）· `◐` 可能相关（从 shell 命令里看出来的，悬停给出那条命令）· `○` 与本会话无关。
-   - 行尾 `○` / `✓`：审阅标记 —— 点一下或按 `v` 切换；`✓` 变黄表示**改动已变，需要重看**。
-   - 点任意一行打开该文件的差异。
-5. **最近提交**：`短sha 标题 [HEAD] 相对时间`；点一行打开这次提交的明细，再点一次收起。
+1. **仓库路径 · 上游 · 短 oid**
+2. **改动概览** —— 按类型分组的彩色计数；干净时写「工作区干净」。
+3. **本会话改了哪些** —— 一行计数（`本会话改过 3 个文件 · 另有 2 个可能相关 · 1 个已不在 git 现状里`）加开关：`只看本会话改的`、`只看最近一轮`（拿得到回合信息时才出现）；有已审标记时还有 `已审 3/8` 与 `清空已审`。
+4. **改动清单** —— 每行 `标记 状态字母 路径`，重命名读作 `旧 → 新`。
+   - 行首：`●` 确定改过 · `◐` 可能相关（从命令里看出来的，悬停给出那条命令）· `○` 与本会话无关。
+   - 行尾：`○` / `✓` 是审阅标记 —— 点一下或按 `v` 切换；`✓` 变黄表示改动又变了，需要重看。
+   - 点任意一行看这个文件的差异。
+5. **最近提交** —— `短sha 标题 [HEAD] 2026-10-16 14:18`；点一行看这次提交，再点一次收起。
+6. **标签** —— `tag 名 短sha [HEAD] 时间`，新的在前；点一行看它指向的提交。仓库没有标签时会写一行「这个仓库还没有标签」。
+
+时间一律是**完整年月日 + 时分**（本地时区），提交与标签两处一样。
 
 ### 差异与提交明细
 
-- 打开差异后是两栏：左栏就是面板本身（一字不变），右边是差异。工具栏给出路径、`+新增 -删除`、`未暂存` / `已暂存` 页签、`自动换行`、`复制差异`、`✕`。
-- 点 hunk 头折叠那一段；拖右边缘调宽度（默认 470px，记住）。
-- 打开提交明细时是**三栏**（面板 │ 这次提交 │ 差异），并自动打开这次提交的第一个文件。`Esc` 或 `✕` 收起。
+- **看差异**：两栏 —— 左边还是面板，右边是差异。工具栏有 `未暂存` / `已暂存` 页签、`自动换行`、`复制差异`。点 hunk 头可折叠那一段。
+- **看提交**：三栏 —— 面板 │ 这次提交 │ 差异，并自动打开这次提交的第一个文件。`Esc` 或 `✕` 收起。
+- **两条抓握可以拖**：右边缘那条调差异栏宽度（默认 470px）；提交明细栏右边那条调提交明细栏（默认 240px）—— 路径被截断就往左拖。两条宽度都会记住。
 
-### 侧栏会话行上的状态
+### 侧栏会话行（悬停或点行尾 `⋯`）
 
-一条会话行的三处显示共用同一份数据，都是只读 —— **干净时也给标记**（空着和「没做这个功能」长得一样）：
+侧栏那一行本身没有标记；信息在按需展开处，都是文字：
 
-**常亮档（行首）永远有标记**，优先级：`●n` 本会话确定改过 → `◐n` 可能相关 → `!n` 工作区脏（两位以上收成 `+`）→ `?` 读取失败 → `✓` 工作区干净 → `—` 不在 git 仓库里。
-- **行尾动作条（悬停档）**：`!9 ◐1`；干净时是 `✓`。
-- **`⋯` 菜单与悬停卡片**：完整两行 —— 分支与上游、分类型计数（干净就写「工作区干净」），以及本会话改过几个、其中几个来自命令旁听（没有就写「本会话没有改动记录」）。
+```
+main* ↑0 ↓0 · 已修改 7 未跟踪 2
+本会话改过 3 个文件 · 命令旁听到 4 个可能改动的路径（1 个现在有差异）
+```
+
+干净时写明「工作区干净」「本会话没有改动记录」。
 
 ## 键盘
 
-**先在面板里点一下**（或 Tab 进去）才接管按键；点到面板外就交还。带 Cmd/Ctrl/Alt 的组合键与输入框里的按键一律不碰。
+**先在面板里点一下**（或 Tab 进去）才接管按键；点到面板外就交还。Cmd/Ctrl/Alt 组合键与输入框里的按键一律不碰。
 
 | 键 | 作用 |
 | --- | --- |
-| `↑` / `↓` | 在清单里上下移动选中行（只移动，不打开） |
+| `↑` `↓` | 上下移动选中行（只移动，不打开） |
 | `Enter` | 打开选中的那条 |
-| `[` / `]` | 上一个 / 下一个文件，并直接打开 |
-| `n` / `p` | 下一个 / 上一个 hunk（跳到折叠着的会展开它） |
+| `[` `]` | 上一个 / 下一个文件，并直接打开 |
+| `n` `p` | 下一个 / 上一个 hunk（折叠着的会展开） |
 | `Space` | 折叠 / 展开当前 hunk |
 | `v` | 把当前行标成「这一版我审过了」（再按取消） |
 | `r` | 重新读取 |
 | `Esc` | 退一层：先收右栏（差异 / 提交明细），再按才收面板 |
 
-打开提交明细时，`↑ ↓ Enter [ ]` 作用于明细那一栏的清单。
+看提交明细时，`↑ ↓ Enter [ ]` 作用于明细那一栏的清单。
+
+## 它不做什么
+
+- **只读**：不写 index、不动工作区与 git 配置，不执行 `add` / `commit` / `checkout` / `fetch`；不读文件内容，不显示凭证。
+- **归因是两档估计**：经写文件 / 编辑工具的算「确定改过」；从 shell 命令里认出来的算「可能相关」（`>` `>>` `tee`、`sed -i` / `perl -i`、`mv` / `cp` / `rm` / `touch` / `dd of=`、`git checkout|restore <路径>`）。**会漏也会多报**，所以永远标 `◐`，不冒充 `●`；其余命令只记进命令历史，不猜路径。
+- **记录不落盘**：会话改动与工具活动都活在宿主进程里，重启归零；每个会话会写明「自 … 起记录」。
+- **上限**：改动清单 200 条、单会话归因 500 个文件、标签 100 个、最近提交 10 条 —— 超出只计数并标 `truncated`。
+- **审阅签名用 `size + mtimeMs`**：`touch` 一下（内容没变）也会让「已审」失效 —— 宁可让你多看一眼。
+- **计数按文件算**：未跟踪不折叠目录（与编辑器一致）；同一个文件「既暂存又改动」算 1 条。
 
 ## 存在浏览器里的东西
 
 | 键 | 内容 |
 | --- | --- |
-| `dsh-hud.ui.v1` | 面板展开状态、拖动位置、宽度、开关（含侧栏档位） |
-| `dsh-hud.reviewed.v1` | 「已审」标记：按「工作区 + 文件」记下审过的那一版签名，最多 200 条 |
-| `dsh-hud.debug` | 自诊断最近 24 行（排查「界面没反应」用，可随手删） |
-
-## 已知边界
-
-- **只读**：不执行 `add` / `commit` / `checkout` / `fetch` 等任何写操作，不碰 index、工作区与 git 配置，不读文件内容、不显示凭证。
-- **归因分两档**：经写文件 / 编辑工具的算「确定改过」；shell 命令里认得出的算「可能相关」（`>` `>>` `tee`、`sed -i` / `perl -i`、`mv` / `cp` / `rm` / `touch` / `dd of=`、`git checkout|restore <path>`）。**会漏也会多报**，所以那一档永远是 `◐`，不冒充 `●`；其余命令只记进命令历史，不猜路径。
-- **不持久化**：记录活在宿主进程里，所以每个会话都带一个「自 … 起记录」的时刻。上限：单会话 500 个文件、32 个会话、命令历史 20 条。
-- **审阅签名**用 `size + mtimeMs`：`touch` 一下（内容没变）也会让「已审」失效 —— 宁可让人多看一眼。
-- **侧栏常亮格受产品限制**：行首只有 16px（所以只能两个字符），产品自己在那一格显示会话状态点时会让位；行尾没有给插件的座位，所以完整信息放在 `⋯` 菜单与悬停卡片里。
-- **性能**：面板轮询 8s、侧栏摘要 12s；git 读取按目录缓存，多个会话共用同一个目录只跑一次。
+| `dsh-hud.ui.v1` | 面板展开状态、拖动位置、两条拖出来的宽度、开关 |
+| `dsh-hud.reviewed.v1` | 「已审」标记（按工作区 + 文件记签名，最多 200 条） |
+| `dsh-hud.debug` | 最近 24 行自诊断 —— 排查「界面没反应」用，可随手删 |
 
 ## 开发
 
-```bash
-npm test                          # node --test test/*.test.mjs
-node --test test/diff.test.mjs    # 单个文件
-```
-
 - `lib/index.js`：宿主半（跑 git、提供 `/dsh-hud-rpc`）。
 - `lib/client.js`：浏览器半（**无构建步骤**，手写 JS，只依赖种子模块 `react`）。
-- `test/`：单测 + 一套假 window/document/React harness。
-- `docs/dock-slot-host.md`：把输入框上方那一行做成「可注册行内宿主」的提案（给上游看的）。
-- 发布：`npm publish` 会先跑全部测试（`prepublishOnly`）。
+- `npm test`：全部用例（`node --test test/*.test.mjs`）。
+- `docs/dock-slot-host.md`：把输入框上方那一行做成「可注册行内宿主」的提案，给上游看的。
+- **发版**：`npm run tag && npm publish`。`prepublishOnly` 先跑测试，再校验「版本号 ↔ git tag」（工作区要干净、`v<版本>` 要存在且指向 HEAD），对不上就发不出去。
 
 ## 许可