前言¶
在 DSH 中進行實驗跟蹤或項目管理時，需要同時兼顧甘特圖、畫板、週期管理和協作留言。手動維護這些分散的工具效率較低。dsh-progress 插件將原版單頁應用「進展.html」集成到 DSH 中，通過 Agent 工具和側邊欄界面提供統一的項目進度管理入口。數據存儲在會話項目目錄下，支持與界面共享。
核心功能¶
- 16 個 Agent 工具：提供從創建、更新到搜索、導出的全流程操作接口。
- 側邊欄集成：向
dsh-better-sidebar註冊「進度」Tab，通過 iframe 託管原版界面，保留地圖、看板、甘特、導出 Word/PPTX 等所有功能。 - 數據存儲：數據存儲在會話項目目錄的
.progress/progress.json（schemaVersion 3），附件存儲在.progress/files/，包文件存儲在.progress/package/。 - 導入導出：支持導出 JSON、Markdown、Word/PPTX 以及完整的項目文件夾包。
- 協作與搜索：支持協作留言與全局搜索，可查看安排、畫板和留言的上下文片段。
安裝與啓用¶
安裝推薦使用官方提供的安裝腳本，該腳本會自動處理網絡環境和 pnpm 的供應鏈保護策略。
1. 使用安裝腳本（推薦）¶
curl -fsSL https://raw.githubusercontent.com/lsqace-del/dsh-progress/main/scripts/install.sh | bash
安裝腳本默認使用 desktop profile，如需指定其他 profile（例如 web），請執行：
curl -fsSL https://raw.githubusercontent.com/lsqace-del/dsh-progress/main/scripts/install.sh | bash -s -- web
2. 使用 CLI 命令¶
如果網絡環境良好，可以使用 CLI 安裝。注意：npm 上存在同名無作用域包 dsh-progress（0.0.1），與本插件無關，請勿安裝。本項目 npm 包名爲 @lsqeon/dsh-progress。
dsh plugin --profile desktop add dsh-better-sidebar @lsqeon/dsh-progress
安裝完成後，需要重啓 DSH Desktop（或 dsh web）才能看到側邊欄的「進度」Tab。
Agent 工具清單¶
插件提供了 16 個 progress_* 系列工具，用於在對話中直接管理進度。
| 工具名 | 說明 |
|---|---|
progress_list |
列表篩選（狀態/項目/日期/模板/文本），返回命中行和總數 |
progress_get |
獲取單條完整詳情及當天畫板頁 |
progress_create |
新建安排（包含九步記錄字段） |
progress_update |
部分字段更新（含 starred/提醒） |
progress_delete |
刪除安排及其留言 |
progress_board |
畫板頁讀寫（get/set/addPage/deletePage/renamePage） |
progress_daily_record |
跨日安排的每日記錄讀寫 |
progress_search |
全局搜索（安排/畫板/留言，帶上下文片段） |
progress_overview |
概覽統計（逾期定義：非 done/paused 且 endDate<今天） |
progress_gantt |
獲取甘特數據（行、依賴邊、指標） |
progress_cycle |
週期範圍讀寫 |
progress_comments / progress_comment_add |
協作留言 |
progress_import |
導入項目數據/分享 HTML/JSON（按 id 合併） |
progress_export |
導出 json / teacher-html / markdown / package |
progress_info |
查看存儲路徑與統計信息 |
典型用法¶
- 在對話中管理：使用
progress_list查看當前安排，或使用progress_create快速新建任務。 - 可視化界面：通過側邊欄「進度」Tab 打開可視化界面，進行甘特圖拖拽或畫板編輯。
- 導出數據：在對話中調用
progress_export導出 JSON 或 Markdown 文件，或在界面中導出 Word/PPTX。
已知限制¶
- 併發編輯：界面與 Agent 工具併發寫同一文件時，可能因
storageRevision衝突導致未同步改動丟失（返回 409 錯誤）。 - 通知權限：提醒鬧鐘/通知在 iframe 內受瀏覽器權限策略影響，可能不可用。
- 導出格式：
progress_export的package爲服務端簡化版，與界面導出的完整包格式兼容但不逐字節相同。 - 路由規則：prefix 路由註冊必須不帶尾斜槓（例如
/progress，而非/progress/），否則靜態資源無法訪問。
注意事項¶
- 插件代碼通過 Electron 渲染進程頭
x-dsh-desktop-renderer訪問服務端，shell 環境直接請求會返回 403。 - 安裝時若遇到 pnpm 報錯，可檢查 profile 的
pnpm-workspace.yaml是否包含allowBuilds: node-pty: true。
