@konnga/dsh-hud 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-hud contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# dsh-hud
 
-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.
+> DeepSeek Harness 的当前工作区面板：分支、ahead/behind、脏状态、改动清单与差异（全部只读），并告诉你**这个会话改过哪些文件**、**审到哪了**。
+> A read-only workspace Git panel for DeepSeek Harness — plus per-session change attribution and review progress.
+
+## 安装
+
+在桌面端「设置 → 插件 → 添加插件」里填包名 `@konnga/dsh-hud`。
+
+本地开发时把 profile 的依赖指向仓库（改动即时可见；客户端代码仍需重启应用才重读）：
+
+```json
+"@konnga/dsh-hud": "link:/path/to/dsh-hud"
+```
+
+## 界面
+
+### 胶囊（输入框上方那一行）
+
+`⎇ feat/x* ↑1 ↓2 M4 A1 ?1 │ ●3`
+
+- `⎇ 分支`：detached 时是 `detached <短oid>`；过长中段省略。
+- `*` 工作区不干净；`↑n` / `↓n` 与上游的领先 / 落后（为 0 不显示）。
+- 简写符只列非零项：`M` 已修改 · `A` 已暂存新增 · `D` 已删除 · `R` 重命名 · `C` 复制 · `T` 类型改变 · `?` 未跟踪 · `!` 冲突。
+- `│ ●n` 表示本会话改过 n 个文件（没有就不显示）。
+- 点胶囊开面板；悬停给出工作区路径、上游与各类计数。
+
+### 面板
+
+标题栏可拖动（双击复位），`⟳` 刷新 · `⌖` 复位位置 · `✕` 收起。自上而下：
+
+1. **仓库路径 · 上游 · 短 oid**。
+2. **改动概览**：按类型分组的彩色计数，只显示非零项；干净时写「工作区干净」。
+3. **本会话改了哪些**：`本会话改过 3 个文件 · 另有 2 个可能相关 · 1 个已不在 git 现状里`，右边一排开关：
+   - `只看本会话改的`：清单只留本会话动过的文件（含「可能相关」）。
+   - `侧栏 常亮 / 悬停 / 关`：侧栏会话行上那枚状态标记的档位，**默认常亮**。
+   - `只看最近一轮`：只留最近一轮改过的文件（拿得到回合信息时才出现）。
+   - `已审 3/8` 与 `清空已审`：有已审标记时才出现。
+4. **改动清单**：每行 `标记 状态字母 路径`，重命名读作 `旧 → 新`。
+   - 行首三态：`●` 确定改过（经写文件 / 编辑工具）· `◐` 可能相关（从 shell 命令里看出来的，悬停给出那条命令）· `○` 与本会话无关。
+   - 行尾 `○` / `✓`：审阅标记 —— 点一下或按 `v` 切换；`✓` 变黄表示**改动已变，需要重看**。
+   - 点任意一行打开该文件的差异。
+5. **最近提交**：`短sha 标题 [HEAD] 相对时间`；点一行打开这次提交的明细，再点一次收起。
+
+### 差异与提交明细
+
+- 打开差异后是两栏：左栏就是面板本身（一字不变），右边是差异。工具栏给出路径、`+新增 -删除`、`未暂存` / `已暂存` 页签、`自动换行`、`复制差异`、`✕`。
+- 点 hunk 头折叠那一段；拖右边缘调宽度（默认 470px，记住）。
+- 打开提交明细时是**三栏**（面板 │ 这次提交 │ 差异），并自动打开这次提交的第一个文件。`Esc` 或 `✕` 收起。
+
+### 侧栏会话行上的状态
+
+一条会话行的三处显示共用同一份数据，都是只读 —— **干净时也给标记**（空着和「没做这个功能」长得一样）：
+
+**常亮档（行首）永远有标记**，优先级：`●n` 本会话确定改过 → `◐n` 可能相关 → `!n` 工作区脏（两位以上收成 `+`）→ `?` 读取失败 → `✓` 工作区干净 → `—` 不在 git 仓库里。
+- **行尾动作条（悬停档）**：`!9 ◐1`；干净时是 `✓`。
+- **`⋯` 菜单与悬停卡片**：完整两行 —— 分支与上游、分类型计数（干净就写「工作区干净」），以及本会话改过几个、其中几个来自命令旁听（没有就写「本会话没有改动记录」）。
+
+## 键盘
+
+**先在面板里点一下**（或 Tab 进去）才接管按键；点到面板外就交还。带 Cmd/Ctrl/Alt 的组合键与输入框里的按键一律不碰。
+
+| 键 | 作用 |
+| --- | --- |
+| `↑` / `↓` | 在清单里上下移动选中行（只移动，不打开） |
+| `Enter` | 打开选中的那条 |
+| `[` / `]` | 上一个 / 下一个文件，并直接打开 |
+| `n` / `p` | 下一个 / 上一个 hunk（跳到折叠着的会展开它） |
+| `Space` | 折叠 / 展开当前 hunk |
+| `v` | 把当前行标成「这一版我审过了」（再按取消） |
+| `r` | 重新读取 |
+| `Esc` | 退一层：先收右栏（差异 / 提交明细），再按才收面板 |
+
+打开提交明细时，`↑ ↓ Enter [ ]` 作用于明细那一栏的清单。
+
+## 存在浏览器里的东西
+
+| 键 | 内容 |
+| --- | --- |
+| `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 读取按目录缓存，多个会话共用同一个目录只跑一次。
+
+## 开发
+
+```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`）。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# @konnga/dsh-hud — bundle layer.
+#
+# `name` 必须是**真实的包名**（改名时这里漏改过一次，结果整个插件加载不起来：插入找不到模块，
+# 组合树里就没有这条，界面上一片空白）。
+#
+# 宿主半（lib/index.js）在自己的 `ctx.webServer` 上注册 `/dsh-hud-rpc` 前缀路由，
+# 收发与 `/api` 相同的 Connection RPC 信封，并用 `connection.requestRejection`
+# 复用 Host/Origin + 浏览器会话围栏；浏览器半（lib/client.js，一个 dsh.client 行）
+# 通过 `ctx.connection.rpc.call("/dsh-hud-rpc", endpoint, { args })` 取数。
+#
+# 这里故意不写 `inject`：Cordis 读取的是模块自己导出的 `inject`
+# （`["webServer", "connection"]`），在行里重复一遍只会制造第二个需要同步的地方。
+- insert:
+    - id: dsh-hud
+      name: '@konnga/dsh-hud'