DS Kanban

人、DS Bot 与普通 DSH 会话，共同维护同一张任务卡。

0.3.0-beta.1 是 M1 测试版，面向单个 DSH 安装者及其本地会话。普通会话无需安装 DS Bot。只参考 Kan 的功能需求，本项目没有引入 Kan 的源码或界面。

已有功能

• 多看板，自定义列、列排序、归档和恢复。
• 任务标题、目标、负责人、下一步、等待对象、完成摘要；编辑、移动、排序、归档和恢复。
• 人、Bot、普通会话读写同一份数据，保留创建者、负责人、实际操作者和来源会话。
• 看板级查看者、协作者、管理员。协作者可以维护别人创建的卡；会话身份由 DSH 提供，工具参数不能冒充身份。
• SQLite 事务保存、版本冲突检查、请求去重、旧版迁移、在线备份和导出。
• 明确完成才改变进度；暂停、退出、空闲、重启不会自动完成。指派负责人不启动执行。

检查清单、标签、搜索、附件、讨论、提醒、任务执行调度与多用户远程服务不属于此版本。

兼容要求

• 已验证：DeepSeek Harness 0.2.1-rc.5，Node 22.23.2，macOS arm64。
• Node 要求 >=22.13.0，使用内置 node:sqlite。
• DS Bot 为可选插件；已联调 0.1.4。未来宿主或 DS Bot 导航结构变更可能需要适配。
• API 依赖 DSH 的所有者认证，不要将插件单独挂到无认证的 HTTP 服务。

安装测试版

从 Releases 下载预构建 ds-kanban-0.3.0-beta.1.tgz，核对同页的 SHA256。

dsh plugin --profile desktop add /absolute/path/ds-kanban-0.3.0-beta.1.tgz

安装器会识别包内的 bundle 声明并启用插件。重启 DSH，在左侧打开「看板」。如果是 Web profile，把上述 desktop 改为 web；若设置了 DSH_HOME，配置和数据都在该目录下。

如果采用本地 link: 开发安装或旧配置而入口未出现，检查 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles 中是否有 "ds-kanban"，保留已有项目并避免重复添加。

首次体验建议用独立的 DSH_HOME，避免直接升级日常数据。该目录不会自动复制常用 profile 的模型凭证。

让普通会话或 Bot 参与

1. 让目标会话调用 kanban_list。它会登记真实身份，未授权时返回空看板。
2. 在界面的「成员」中选中该会话或 Bot，添加为「协作者」。
3. 再让它读取看板、创建或修改任务。界面轮询会显示结果。

权限按看板设置：查看者只读；协作者维护卡片；管理员还可管理列、看板和成员。安装者保留管理权。新建看板的人或会话为管理员，安装者也能管理该看板。

Bot 的不同对话分段及群会话使用同一个 Bot 身份，变更记录另外保留来源会话 ID。授权给 Bot 意味着该 Bot 的这些会话共享此权限。撤销成员后，旧成功请求重放也不能返回该看板内容。

工具与状态规则

kanban_list、kanban_create、kanban_update、kanban_move、kanban_manage 是五个工具。先读取 revision，修改时带 baseRevision 和唯一 requestId。同一网络重试必须复用原请求；冲突后读取最新内容、合并意图，并用新的请求标识提交。

• 转到完成列：提交本次实际结果 completion。
• 转到等待列：填写 waitingFor 和 waitingReason。
• 从完成列重开：填写 nextStep。
• 并发编辑发生冲突时，界面保留输入，先查看最新版本再继续编辑；不会自动覆盖。
• 归档卡仍占用所在列，防止删除列时把历史任务一起丢掉。

旧版升级

默认数据目录是 ~/.dsh/kanban。升级前退出旧版宿主并保留完整目录副本。首次打开时，插件将该目录中的 v1 board.json 导入 kanban-v2.sqlite：

• 原始 board.json 不修改，另外生成按 SHA256 命名的 board-v1-<sha256>.json。
• 卡片 ID、时间和全部原始字段保留；完整旧对象位于每张卡的 legacy 字段中。
• 历史卡进入独立的「历史看板 · 旧版导入」；旧完成标为「旧版完成 · 未确认」。填写真实完成摘要才移除该标记。
• 不默认把历史来源会话授权为看板成员，需管理员重新授权。
• 损坏文件、重复或缺失 ID 会中止迁移，原文件保持不变。不要删除原文件来掩盖迁移错误。
• 再次打开不会重复导入。新版本写入只进入 SQLite，不回写旧 JSON。

备份、导出与恢复

包内提供 scripts/data.mjs，也导出 ds-kanban-data 命令。以下示例使用绝对包路径以免依赖 PATH：

node /path/to/ds-kanban/scripts/data.mjs backup --home "$HOME/.dsh/kanban" --out /path/to/backup.sqlite
node /path/to/ds-kanban/scripts/data.mjs export --home "$HOME/.dsh/kanban" --out /path/to/export.json
node /path/to/ds-kanban/scripts/data.mjs restore --from /path/to/backup.sqlite --to /path/to/restored-kanban

备份支持运行中的数据库，包含已经提交到 WAL 的内容。输出文件必须不存在。恢复只创建全新目录，拒绝覆盖现用数据库；输出包括卡数、revision 和 SHA256。

切换恢复副本前，先备份、导出当前数据并退出 DSH。在 profile 的 cordis.patch.yml 添加或合并：

- id: kanban
  config:
    home: /absolute/path/to/restored-kanban

重启后核对卡片，再决定是否使用恢复副本。原目录始终保留；较新任务仍在切换前的备份/导出内。此版本没有两份数据的自动合并功能。

回退到 0.2.4 不会读取 SQLite。 直接安装旧包只会显示旧 board.json，升级后的新任务不会出现在旧版里。回退前必须备份、导出 v2 数据，保留 SQLite 目录；需要查看新任务时重新启用本版本或在独立 profile 中打开备份。不要把旧界面的缺卡误认为删除成功。

开发和检查

npm ci
npm test
npm run build
npm run check
npm pack

源码位于 src/client 与 src/host，client.js 是预构建客户端。自动测试涵盖真实 DSH ToolRuntime 注册、权限、三身份同卡、卸载、多进程冲突、失败回滚、迁移、备份恢复。真实模型、浏览器和安装验证结果另见 VALIDATION.md，不把合成测试等同于实机验收。

MIT License。依赖各自保留其原有许可。