dsh-progress

Readme

# dsh-progress

![test](https://github.com/lsqace-del/dsh-progress/actions/workflows/test.yml/badge.svg)
![version](https://img.shields.io/github/v/tag/lsqace-del/dsh-progress?label=version)
![license](https://img.shields.io/badge/license-MIT-blue)

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）：

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

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

```bash
# 一次性：确保 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 dsh-progress
```

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

### 装不上排查

- 报 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`：pnpm 供应链「新发布包 24h 保护期」拦截（如 dshmarket 刚发新版）。在 profile 目录（`~/.dsh/profiles/<profile>/`）的 `.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/<profile>/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`：

```jsonc
{
  "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/protocol.md)（文件夹协议）、[docs/data-model.md](docs/data-model.md)（数据模型）、[VENDORING.md](VENDORING.md)（静态资源来源）、[CHANGELOG.md](CHANGELOG.md)。

## 已知限制（v1）

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

## 开发（本仓库维护者）

改动本插件、跑测试、诊断与发布的完整流程见 [docs/install-advanced.md](docs/install-advanced.md)（本机 file:+符号链接联调、五套测试、boot.log/access.log 诊断、GitHub/npm/市场发布）。