dsh-conversation-overview 1.4.1 → 1.5.0

package/README.md

@@ -8,8 +8,8 @@ DeepSeek Harness（DSH）插件：在对话/轨迹旁增加「概览」标签页
 
 ## 功能特性
 
-- **进展**：目标与任务计划进度；本轮关键步骤（可展开全部、展开查看命令与输出/耗时/错误、等待确认高亮、里程碑可置顶）；团队成员状态；双击待办生成重跑提示词；主代理/子代理可切换查看各自概览。
-- **产物**：生成/交付文件列表、按轮次的变更审阅入口、系统定位与「打开方式」；本轮结束可自动把结论作为 Markdown 文档开在新标签（计划内容亦有快照）。
+- **进展**：会话目标横幅（目标模式、自动续跑轮次/上限、阶段与受阻原因）与任务计划进度；本轮关键步骤（可展开全部、展开查看命令与输出/耗时/错误、等待确认高亮、里程碑可置顶，折叠窗口按「有门禁的步骤」取最近 6 条，不会把孤立审批留在顶部）；团队成员与子代理按对应待办归属；双击待办生成重跑提示词；主代理/子代理一键切到对方的概览。
+- **产物**：生成/交付文件列表、按轮次的变更审阅入口、系统定位与「打开方式」；本轮结束可自动把结论作为 Markdown 文档开在新标签（计划内容亦有快照，刷新后正文仍在）——文档页用与对话完全相同的排版组件渲染（字号阶梯、行高、图片、文件 chip 一致），文件链接点击即在侧边栏打开预览，外链走新标签。
 - **引用**：上下文注入、OpenViking 记忆（侧边栏内预览）、技能、文件与会话引用；类型筛选、隐藏常见项、排序（最近/类型/轮次/次数）。
 - **统计与时间轴**：轮次统计胶囊（用时/调用/命令/改动文件/失败，失败可点击查看详情）；打开时间轴拖到任意时间点，回看当时的进展、产物与引用。
 - **Markdown 预览**：结论与记忆文档支持 Mermaid 图渲染、代码块复制、脚注与自动换行。
@@ -38,7 +38,7 @@ CLI 安装后重启 `dsh` 生效（方式一/二安装后刷新浏览器页面
 
 安装后在「设置 → 会话概览」或插件行内配置中调整选项；对话页刷新即可看到「概览」标签页与右侧边栏入口。
 
-> 注意：若此前安装过开发版 `@local/dsh-conversation-overview`，请先移除它再安装本包——两者使用相同的插件行 id（`conversation-overview`）与插槽 key，不应同时启用。
+> 注意：若此前用 `link:` 装过本地开发副本（同名包指向你的工作目录），请先移除再安装本包——两者使用相同的插件行 id（`conversation-overview`）与插槽 key，不应同时启用。判断方法：`grep dsh-conversation-overview ~/.dsh/profiles/web/package.json`，出现 `link:/…` 即为开发版。
 
 **插件更新**：
 
@@ -78,14 +78,76 @@ CLI 安装后重启 `dsh` 生效（方式一/二安装后刷新浏览器页面
 
 ## 开发与测试
 
-包内无构建步骤：`index.js`（Host 侧，schemastery Config + 资源定位）与 `client.js`（浏览器侧，`window.__ModuleLoader__` 工厂格式）均为源文件直发。
+### 代码结构
 
-离线测试用真实会话日志（`session.v4.jsonl.zstd`）驱动折叠逻辑与设置表单断言：
+包内**没有构建步骤**，两个源文件直接就是发布物：
+
+| 文件 | 运行位置 | 职责 |
+| --- | --- | --- |
+| `index.js` | Host（Node） | schemastery 配置字段定义、`dsh-resource://` 资源定位与 Host 侧数据接口 |
+| `client.js` | 浏览器（Web UI） | 概览页/侧边栏 UI、会话事件折叠、标签页注册，以 `window.__ModuleLoader__` 工厂函数形式被加载 |
+
+改完文件后：Host 侧（`index.js`、`cordis.patch.yml` 的配置项）需要**重启 DSH** 才生效；纯客户端（`client.js`）**刷新页面**即可。
+
+### 本地调试安装
+
+```bash
+# 让 profile 直接引用本地目录（改完刷新即生效，不必反复装包）
+dsh plugin --profile web add link:/absolute/path/to/dsh-conversation-overview
+
+# 确认装的是开发版而不是 npm 版
+grep dsh-conversation-overview ~/.dsh/profiles/web/package.json   # 应看到 link:/…
+```
+
+### 运行测试
+
+测试脚本随包发布，无需构建、无需联网。它会在 Node 里用桩（stub）替代浏览器环境——`window`、`localStorage`、`React`——然后加载 `client.js`，对**真实会话日志**做一遍完整折叠并断言结果。
 
 ```bash
-node .scratch/test.mjs <path/to/session-a.jsonl.zstd> <path/to/session-b.jsonl.zstd>
+# 默认自动取本机最近的 2 个会话日志
+npm test
+
+# 或指定任意日志（可传多个，跨会话、跨工作区都行）
+node .scratch/test.mjs ~/.dsh/sessions/<workspace>/<session-id>/session.v4.jsonl.zstd \
+                       ~/.dsh/sessions/<workspace>/<other-session-id>/session.v4.jsonl.zstd
 ```
 
+- 依赖 **Node ≥ 20** 与 **`zstdcat`**（日志是 zstd 压缩的；macOS：`brew install zstd`）。
+- 会话日志位置：`~/.dsh/sessions/<工作区>/<session-id>/session.v4.jsonl.zstd`，每一轮对话都在里面。
+- 全部通过时输出 `ALL TESTS PASSED`，并列出实际检查了哪几个日志；任一断言失败会直接给出断言信息与所在行号。
+
+### 测试覆盖范围
+
+共 16 组、约 460 条断言，全部离线运行：
+
+| # | 覆盖内容 |
+| --- | --- |
+| 1 | `zh`/`en` 词典键完全对齐（少一个键就失败，避免界面出现原始 key） |
+| 2 | `apply()` 在 mock `ctx` 上注册了哪些标签页/插槽，以及每个配置开关的显隐效果 |
+| 3 | 用真实日志跑完整折叠：待办、关键步骤、产物、引用、统计、里程碑 |
+| 4 | 地址解析、助手提及、变更事件等纯函数 |
+| 5 | 文件类型分类与工作区变更聚合 |
+| 6 | OpenViking 预览与 Markdown 渲染 |
+| 7 | frontmatter、面包屑、引用排序 |
+| 8 | 按轮次折叠（`latest` / `all` 两种范围）与上下文快照 |
+| 9 | 全量引用识别（正文里出现过的资源是否都被收集） |
+| 10 | 关键步骤流与轮次导航轨的联动刻度 |
+| 11 | 「新标签打开」确实落到宿主自己的 Markdown 文档页 |
+| 12 | 「本轮结论」只在该轮结束后出现 |
+| 13 | 结论自动打开：只在观察到该轮实际运行后打开一次（刷新不会重开） |
+| 14 | 子代理相关界面只在真有子代理工作时出现（压缩里程碑不算） |
+| 15 | 文档标签刷新后仍能恢复正文（结论/计划快照镜像到 `localStorage`） |
+| 16 | 代理身份判定：`origin: "subagent"` 才是子代理，分叉/续聊会话算主会话 |
+
+> 这些断言同时充当回归护栏：改动 `client.js` 的折叠或显隐逻辑后先跑 `npm test`，比在浏览器里逐个点要快得多。
+
+## 版本更新
+
+- **1.5.0**：会话目标横幅（目标模式、自动续跑轮次/上限、阶段与受阻原因）；文档页改用与对话相同的 Markdown 组件与排版壳（文件 chip 点击开侧边栏预览、外链新标签、多段正文正确分段）；团队委派按 IDF 词重叠归属到对应待办；关键步骤折叠窗口按「有门禁的步骤」取最近 6 条；代理身份互跳对方概览；等待会话绑定期间不再出现空白概览。
+- **1.4.2**：补齐「开发与测试」文档，测试脚本随包发布（`npm test` 可直接运行）。
+- **1.4.1**：修复刷新后结论标签退化为失效空页；区分「分叉会话」与「子代理会话」，不再误显示子代理徽标。
+- **1.4.0**：结论标签页、Mermaid/Markdown 预览、步骤详情展开、计划快照、子代理角色导航。
+
 ## License
 
 MIT © 2026