前言¶

在 DSH（DeepSeekRuntime）里做智能体或插件开发时，会话往往按工作区项目散落：workspace.json、压缩转录、session_projcache 和归档缓存各管一块。官方侧栏能续接单个会话，但很难一眼看清「这个项目下有哪些会话、哪些在跑、待办聚在哪里」。社区插件 dsh-overview（中文界面名「全景概览」）把上述数据源只读聚合成侧栏入口和整页看板，按项目组织会话与待办，并补齐搜索、归档与删除等操作入口。

DSH 生态主张「一切皆插件」；SkillHub 目录 上的 zhileyo/dsh-overview 条目与 GitHub 上的实现文档（README 指向 AlwaysFyo/dsh-overview 及 CNB 镜像）均为社区维护，与 DeepSeek / 幻方无官方从属关系。安装前请自行审阅源码与 MIT 许可证；插件在 DSH 宿主进程权限下运行，会读取本机 ~/.dsh 下的工作区与会话数据。

这是什么¶

dsh-overview 是分类为「客户端」的 DSH 插件：以工作区项目为维度展示会话 / 任务仪表盘。当前 README 记载的版本为 v0.1.11，依赖 Node ≥ 20、DSH ≥ 0.2.0 且 < 0.3.0，通过 Cordis patch 注入 Web 客户端侧栏与整页 UI。

设计说明与 PRD 可在仓库 docs/design.md、docs/dsh-overview-prd.html（PRD v0.3）中查阅；UI 原型见 docs/dsh-overview-ui.html。

核心功能¶

下面按 README 已落地能力（第 1–4 步）归纳，不写未实现项。

数据层：四源只读聚合¶

src/model/ 聚合四类只读来源：

• workspace.json
• session.v4.jsonl.zstd
• session_projcache
• 归档缓存

归档以 workspace.json 的 global.archivedSessionIds 为准；归档缓存只补元数据。已归档会话仍可以是 live 会话。只存在于归档缓存、没有转录且宿主未标记归档的孤儿记录会被丢弃，避免「无标题」幽灵行。会话头按文件指纹缓存，并流式解压到首个换行即停止，以降低冷启动读取成本。

宿主 API 与会话删除¶

src/host/ 提供：

• GET /dsh-overview/state：首次请求触发构建，单飞避免并发重复扫描
• SSE /dsh-overview/events：25 秒心跳注释，订阅者断开即清理
• POST /dsh-overview/session/delete：同源校验、body ≤ 8 KiB、未知会话幂等返回 skipped

删除语义对齐 dsh-archive-manager：flush / detach live 会话 → 清投影缓存 → 仅级联 origin === 'subagent' 子会话 → 清 spill → 删除 jsonl 转录目录（校验路径所有权，拒绝符号链接）→ 成功后清归档缓存与 workspace 记账 → 广播 api-session/removed。

客户端 UI¶

src/client/ 提供侧栏「全景概览」入口、看板整页、项目详情（续接 / 归档 / 取消归档 / 永久删除）以及续接草稿注入。

「运行中」状态取自官方客户端会话快照 ctx.sessions.list 的 running、runningSubagentCount、pendingInteraction，与官方侧栏同源。README 说明：宿主 SessionStore.list() 在常驻 webServer 里恒为空，不能作为真源；/state.liveSessionIds 已移除。脱离 Web 客户端（例如 CLI）时，运行中状态会退化为 2 小时时间窗。

搜索与待办¶

顶栏搜索同时匹配项目名、会话标题、待办内容，结果按项目分组，命中会话可直接打开。详情页聚合项目内未完成待办（in_progress 优先），会话行显示待办数。缺少 projcache 标题的 live 会话用首条用户消息兜底（折叠空白、截断 60 字）。

测试与开发命令¶

仓库含 22 个单元测试（npm test），覆盖聚合规则、归档真相、删除安全边界、运行中真源、待办解析等。常用命令如下：

npm run snapshot                # 对真实 ~/.dsh 数据打印项目快照（--json / --project <词>）
npm test                        # 单元测试（node:test）
npm run check                   # TypeScript 类型检查
npm run build                   # 构建 lib/（tsdown + client bundle）
npm pack                        # 产出 tarball 供插件管理器安装

本地调试真实数据时，可用 npm run snapshot 对照看板聚合结果。

安装与启用¶

README 未给出 dsh plugin add github:... 一类一键命令；开发或更新插件时应打包 tarball，经插件管理器安装。不要用 link: / file: 直链项目目录——文档记录 pnpm 回滚可能沿目录联接删掉项目本体。

1. 在插件源码目录构建并打包：

npm run build && npm pack

产出 dsh-overview-<version>.tgz（当前 package 版本为 0.1.11）。

2. 使用 DSH 插件管理器安装该 tarball。README 示例表述为 plugin_manager install_bundle file:<绝对路径>.tgz；安装后需以新版本号发布，否则会报 already-installed。本机验证环境使用 profile desktop（~/.dsh/profiles/desktop）。

3. 安装后校验 node_modules/dsh-overview/lib 哈希，并刷新 Web 客户端页面，侧栏应出现「全景概览」。

改动插件后必须升版本再重复上述步骤。

典型用法¶

1. 在 DSH Web 客户端打开侧栏 全景概览，浏览按项目分组的会话列表与运行中标记。
2. 使用顶栏搜索定位项目、会话或待办；从结果直接进入对应会话。
3. 进入项目详情：续接会话、归档或取消归档、永久删除（走宿主删除 API，语义与归档管理插件一致）。
4. 维护插件或排查聚合问题时，在源码树执行 npm run snapshot（可加 --json 或 --project <词>）对照 ~/.dsh 真实布局。

适用场景与注意¶

适合：在同一 DSH 桌面 profile 下管理多个工作区项目、需要项目维度会话总览、待办聚合与归档 / 删除操作的开发者。

已知缺口（README 原文）：没有任何 user/message 事件的 live 会话仍只能显示「(无标题)」；无 Web 客户端时运行中判断不准确。

安全与信任：插件读取并可能删除会话转录与相关缓存，安装前请阅读 src/host/ 删除路径校验逻辑与许可证。仅安装你审阅过的 tarball 或可信来源构建物。

结尾¶

dsh-overview 把 DSH 工作区内的会话、归档与待办收到一张项目维度的仪表盘里，并通过宿主 API 与官方客户端快照对齐「运行中」状态。后续路线（P2/P3）包括集成测试、CI 构建、收藏与批量归档等，以仓库 README「后续步骤」为准。

• 目录页：https://www.skillhub.cn/plugins/zhileyo/dsh-overview
• GitHub：https://github.com/AlwaysFyo/dsh-overview（README 所列仓库；目录条目为 zhileyo/dsh-overview）
• CNB 镜像：https://cnb.cool/one-mugen/dsh-overview