前言¶

在 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