进度管理 lsqace-del/dsh-progress

dsh-progress

test
version
license

DSH 插件：「进度」实验/项目进度管理。把单页应用「进展.html」原封不动搬进 DSH：

- agent 工具 progress_（16 个）：对话里直接管理安排、笔记、留言、搜索、概览、甘特、导入导出。
- 侧边栏界面：向 dsh-better-sidebar 注册「进度」tab，iframe 托管原版界面（地图/当天/看板/记录/甘特/展示导出 Word-PPTX/分享/主题/中英切换/提醒/留言全部保留），通过原版应用自带的「本地文件夹服务器」协议与插件同步。
- 数据：存在会话项目目录 .progress/progress.json（schemaVersion 3，与原版导出格式一致）；附件在 .progress/files/，界面生成的「项目文件夹」包在 .progress/package/。

安装（主推脚本，绕开 git 直连）

无代理网络下 github: 直装会因 git 拉取 GitHub 超时而失败，主推安装脚本（codeload tarball 下载 + 自动豁免 pnpm「新发布包 24h 保护期」+ 引导 pnpm）：

curl -fsSL https://raw.githubusercontent.com/lsqace-del/dsh-progress/main/scripts/install.sh | bash
指定 profile： ... | bash -s -- （默认 desktop）

CLI 一键（git 通道畅通的环境；已发布 npm 后也可用 npm 名，registry 通道更稳，可配 npmmirror）：

一次性：确保 dsh 命令可用（已装可跳过）
npm i -g @deepseek-ai/dsh

github 直装
dsh plugin --profile desktop add dsh-better-sidebar github:lsqace-del/dsh-progress
或 npm 名
dsh plugin --profile desktop add dsh-better-sidebar @lsqeon/dsh-progress

（CLI 版 web profile 同理：把 --profile desktop 换成 --profile web，装完重启 dsh web。）

⚠️ npm 上的无作用域 dsh-progress（0.0.1，发布者 dushaobindoudou）为他人占名包，与本项目无关，请勿安装；本项目 npm 包名为 @lsqeon/dsh-progress。
装不上排查

- 报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION：pnpm 供应链「新发布包 24h 保护期」拦截（如 dshmarket 刚发新版）。在 profile 目录（~/.dsh/profiles//）的 .npmrc 加一行 minimum-release-age=0 后重试（安装脚本已自动处理）。
- 卡住不动/超时：github: 直装走 git 拉 GitHub，无代理网络会挂。改用安装脚本或 npm 名安装。
- 报 pnpm not found：先 npm i -g pnpm。
- 装完看不到「进度」tab：重启 DSH Desktop（web profile 重启 dsh web），并确认 ~/.dsh/profiles//package.json 的 dependencies 含 dsh-progress、dsh.profile.bundles 已登记。

然后重启 DSH Desktop：

- 侧边栏「+」菜单出现「进度」tab，打开即原版界面（首次需设置访问密码）
- 新会话里 agent 可用 progress_ 工具（例如「列出进度安排」）
- 数据与界面共用同一份 .progress/progress.json，随项目目录走

说明：dsh plugin add 是官方 CLI 的插件管理命令（转发给 pnpm 并把声明了 dsh.bundle 的依赖自动加入 dsh.profile.bundles，日常可用 dsh plugin --profile desktop add/remove/update 管理）；dsh-better-sidebar 提供侧边栏 tab 宿主（peerDependencies >=0.12，默认不自动装 peers，所以一起写上）。运行时代码只 import 宿主自带的 @deepseek-ai/dsh-tools（所有 DSH 安装的 profiles/node_modules 层都有），无需其他 npm 依赖，也没有构建脚本。

手动安装（等价）：编辑 ~/.dsh/profiles/desktop/package.json：

{
"dependencies": {
"dsh-better-sidebar": ">=0.12.0",
"@lsqeon/dsh-progress": "github:lsqace-del/dsh-progress" // npm 名为 @lsqeon/dsh-progress },
"dsh": {
"profile": {
"bundles": [/* 原有内容… /, "dsh-better-sidebar", "@lsqeon/dsh-progress"]
}
}
}

然后在 profile 目录执行 pnpm install，重启 DSH Desktop。

卸载：从 dependencies 与 bundles 移除后 pnpm install 并重启。

架构

dsh-progress/
lib/index.js 服务端：progress_ 工具 + HTTP 路由 + 静态托管 lib/store.js 数据层：快照读写、修订冲突、导入合并、搜索、导出 lib/client.js 客户端：better-sidebar「进度」tab（iframe 挂原界面） lib/share-template.html 老师只读网页模板（源自 html查看器/index.html） static/ 原版界面原封不动：index.html(进展.html) / app.js / styles.css test/ 冒烟测试与排障脚本（不参与安装）

原版 app.js 在 http://127.0.0.1 页面下会自动走同源文件夹协议：

| 原版调用 | 插件实现 |
| GET /api/progress/load | 读 .progress/progress.json，返回 {found, snapshot} |
| POST /api/progress/save | 写快照 + 客户端生成的包文件；baseRevision 不一致 → 409 + 服务器快照 |
| POST /api/progress/upload | 附件落盘 .progress/files/，返回回读 URL |
| /progress/index.html 等静态 | 托管原版三件套；folder-data.js 动态注入会话 id |

会话解析：?session= 查询参数 → Referer（iframe 页面 URL 里的 ?session=）→ cookie。无会话时返回 501，原版应用自动退化为「仅本地存储」模式。

宿主适配要点（本仓库代码已按此实现）：

- prefix 路由必须不带尾斜杠注册（宿主匹配规则为 startsWith(prefix + '/')，/progress/ 会永不命中）；
- 界面请求通过 Electron 渲染进程头 x-dsh-desktop-renderer 过闸，静态页与 API 都在同一 webserver 下即可。

工具清单

| 工具 | 说明 |
| progress_list | 列表筛选（状态/项目/日期/模板/文本），rows=命中行、count=总数 |
| 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 | 导入 项目数据.json / folder-data.js / 分享 HTML / JSON（按 id 合并） |
| progress_export | 导出 json / teacher-html / markdown / package |
| progress_info | 存储路径与统计 |

Word/PPTX 演示导出由界面「展示导出」按钮提供（浏览器端），agent 工具不做（v2 可加）。

排障 FAQ

- 侧边栏 tab 界面空白：tab 顶部信息条可自诊断——「N 项 · …/progress.json」说明数据接口正常；「页面: HTTP xxx」说明静态路由状态（200 ✓ 正常）。空白最常见原因是 prefix 路由带尾斜杠（本插件已按无尾斜杠注册）。
- shell 里 curl 全部 403：DSH 桌面 Web 服务只放行 Electron 渲染进程（x-dsh-desktop-renderer 头），shell 请求一律 403 属预期；诊断请用插件目录 boot.log（每次服务端加载追加）与 access.log（每个到达插件的请求一行）。
- 安装时 pnpm 报 ERR_PNPM_IGNORED_BUILDS: node-pty：profile 的 pnpm-workspace.yaml 缺少 allowBuilds: node-pty: true（或仍是占位符）。scripts/install.sh 会自动修复；手动安装请自行补上。
- dsh plugin 报 pnpm 找不到：DSH Desktop 自带 pnpm 在 ~/Library/Application Support/DSH Desktop/runtime-commands/bin/pnpm，加入 PATH 即可；scripts/install.sh 会自动处理。
- 改动 lib/ 后不生效：服务端插件代码需重启 DSH Desktop；file: + 符号链接安装时改动即时可见（重启后）。

更多参考：docs/protocol.md（文件夹协议）、docs/data-model.md（数据模型）、VENDORING.md（静态资源来源）、CHANGELOG.md。

已知限制（v1）

- 界面与 agent 工具并发写同一文件：靠 storageRevision 冲突检测（409），窗口极小的并发编辑可能丢一次未同步改动。
- 提醒闹钟/通知在 iframe 内受浏览器权限策略影响，可能不可用。
- progress_export 的 package 是服务端简化版（安排.json/记录.md/项目数据.json/只读网页），与界面导出的完整包格式兼容但不逐字节相同。
- 未做多会话同目录写锁（进程内互斥已覆盖单实例场景）。

开发（本仓库维护者）本插件改动、测试运行、诊断与发布的完整流程见 docs/install-advanced.md（本机 file:+符号链接联调、五套测试、boot.log/access.log 诊断、GitHub/npm/市场发布）。