前言¶
在 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。
