dsh-progress

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

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

一句话安装（任意 DSH 桌面版）

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

# 一句话安装（与 dsh-biobench 同风格）
dsh plugin --profile desktop add dsh-better-sidebar github:lsqace-del/dsh-progress

（CLI 版 web profile 同样支持：dsh plugin --profile web add dsh-better-sidebar github:lsqace-del/dsh-progress，装完重启 dsh web。）

没有 dsh 命令也没关系，用安装脚本（会自动引导 dsh 命令 + 处理新 profile 的 pnpm 白名单）：

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

然后重启 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",
    "dsh-progress": "github:lsqace-del/dsh-progress"   // 或 npm 名 dsh-progress
  },
  "dsh": {
    "profile": {
      "bundles": [/* 原有内容… */, "dsh-better-sidebar", "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/市场发布）。