前言¶
長期在 DSH 裏跑 Agent 和會話，你很難準確回答幾個樸素問題：客戶端開了多久、真正有操作的時間是多少、單次任務裏模型和工具各佔多少。靠目測或外部計時器，口徑往往和 DSH 自己的會話邊界對不上。
dsh-timespan 是維護者 qwayo 發佈在 DSH 插件生態裏的一款「記憶」類插件。它在 DSH 進程內記錄三類時長，用側欄入口和儀表盤展示，並支持在對話裏用只讀工具查詢；統計數據只寫本機存儲，不上傳。
這是什麼¶
dsh-timespan 面向已安裝 DSH（DSH Desktop 或帶 Web profile 的環境）的用戶。插件分成 Host（隨 DSH 運行的後臺）和 Client（頁面上的側欄、儀表盤與設置）。頁面只上報界面可見、窗口聚焦、會話任務起止等事件；在線、活躍、任務如何判定與彙總，由 Host 統一計算後寫入本機，刷新頁面或調用 Agent 工具時讀的是同一份數據。
項目託管於 GitHub：qwayo/dsh-timespan，npm 包名爲 @qwayo/dsh-timespan（資料中版本 0.1.1，許可證 MIT）。目錄頁見 skillhub.cn 上的 dsh-timespan。
三種時長分別指什麼¶
插件統計三類指標，彼此有明確邊界：
- 在線：DSH 從啓動到退出的全部時間，包含離開電腦的時間。
- 活躍：頁面可見且窗口聚焦，並在空閒閾值內有操作，或前臺會話正在執行任務的時間。
- 任務：一次任務從
turn/start到turn/end的耗時，拆成模型請求、工具執行、等待用戶和其他四部分。
資料說明：沒有單獨的「空閒時長」指標；任務時長不算活躍時長的一部分。啓用後只會回填歷史任務時長，不會補出在線和活躍的歷史。
核心功能¶
側欄與儀表盤¶
- 側欄有常駐入口，實時顯示你選定的時長類型（默認在線）和今日構成環；懸停約 200ms 顯示說明。
- 日 / 周 / 月儀表盤含概覽、趨勢、明細、設置；活躍主數字、趨勢圖、熱力圖可放大到獨立首屏頁，趨勢頁含時段分佈與趨勢分析。
- 工作區 → 會話明細：展示活躍時長、任務時長、最近活動與當前計時狀態；統計範圍可選今天、近 3 天、最近一週、近 30 天或全部（選「全部」時分批加載會話）。
Agent 工具與數據管理¶
- 只讀工具
timespan_stats：在對話裏按日 / 周 / 月或自定義日期查詢，與儀表盤同源。 - 支持導出 JSON / CSV；新備份格式爲
dsh-timespan-export，舊的chronoscope-export仍可導入，按 ID 去重。清空等破壞性操作會二次確認。 - 首次啓用時自動回填已有歷史會話的任務時長。
設置項（節選）¶
設置頁中的 dsh-timespan 分區包括：界面語言（默認中文，可切英文，僅影響本插件文案）、空閒閾值（1–15 分鐘）、周起始（週一 / 週日）、外觀與配色（默認跟隨系統）、數字格式（默認緊湊單位如 2h 48m）、子代理明細開關，以及側欄是否顯示狀態文字和常駐時長類型（默認在線）。
安裝與啓用¶
前置條件：DSH 已裝好，且當前會話可用 plugin_manager 工具（Standard 與 Creator 預設默認開啓）。安裝、更新、卸載交給 plugin_manager，不要手動改 profile 的 package.json，也不要自行跑 pnpm。
方式一：從 npm 安裝¶
在會話裏對 Agent 說：
幫我裝插件 @qwayo/dsh-timespan
需要固定版本時：
幫我裝插件 @qwayo/dsh-timespan@0.1.1
plugin_manager 會從 registry 拉取並默認啓用；提示需要重啓時，重啓 DSH 即可。
方式二：從 GitHub 安裝¶
在會話裏對 Agent 說：
幫我裝插件 github:qwayo/dsh-timespan
適合指定倉庫分支或 tag；同樣需要重啓 DSH 時按提示操作。
方式三：本地目錄（開發）¶
- 將倉庫放在固定路徑，記作
<倉庫本地路徑>。 - 在會話裏說：
用 plugin_manager 把 `<倉庫本地路徑>` 安裝爲當前 profile 的 bundle。
按返回值處理：application: applied 表示已激活；restart-required 則重啓 DSH；failed 則保留錯誤信息繼續排查。
也可直接讓 Agent 調用 plugin_manager，例如：
action: install_bundle
target: github:qwayo/dsh-timespan
裝好後覈對¶
- 左側欄出現 dsh-timespan 入口，默認顯示今日在線時長（可在設置中改爲活躍或任務）。
- 設置頁出現 dsh-timespan 分區。
- 對 Agent 說「用 timespan_stats 查一下今天的時長」，應能返回統計結果。
- 可用
plugin_manager的list_bundles/list_plugins確認 bundle@qwayo/dsh-timespan與插件行dsh-timespan已啓用。
從舊名 chrono-scope 升級：先移除 @local/chrono-scope bundle，再按上述方式安裝；存儲域仍爲 chrono_scope，歷史統計與設置不會丟失。
典型用法¶
在對話裏查今日統計¶
安裝並啓用後，可直接用自然語言讓 Agent 調用只讀工具，例如：
用 timespan_stats 查一下今天的時長
返回口徑與儀表盤一致。
在界面裏看週期與構成¶
- 點擊側欄 dsh-timespan 進入儀表盤。
- 切換日 / 周 / 月視圖，查看概覽、趨勢與明細。
- 在 工作區 → 會話明細 中選擇統計範圍，覈對單會話活躍與任務時長。
備份與遷移¶
在設置中使用導出 JSON 或 CSV；導入時使用插件提供的導入入口。資料註明新格式爲 dsh-timespan-export，舊 chronoscope-export 備份仍可導入。
適用場景與注意¶
適合誰：希望在 DSH 內閉環看清「掛機時長」「真正操作時長」「Agent 任務耗時構成」的開發者；需要在對話中讓模型引用同一套統計而不另建表格的用戶。
運行與權限：插件隨當前 DSH 進程運行，具備該進程對文件與會話事件的訪問能力。安裝前應查看 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的環境策略。
生態說明：DSH 社區插件目錄（如 skillhub.cn）爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；安裝方式以倉庫 README 中的 plugin_manager 爲準，不要憑插件名自行拼接未文檔化的 CLI。
技術側補充：運行時無第三方依賴、無需構建；倉庫使用 Node.js 24.16.0 開發與測試，engines 要求 node >= 24。持久化存儲域內部鍵名仍爲歷史遺留的 chrono_scope，對外項目名爲 dsh-timespan。
結尾¶
dsh-timespan 把在線、活躍、任務三種口徑放在同一套本機統計裏，用側欄、儀表盤和 timespan_stats 統一齣口，避免「界面一套數、對話另一套數」。若要查看元信息與配圖，可打開 目錄頁 或 GitHub README。
