dsh-super-kanban 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-05
+
+First public release. Super Kanban turns the sessions of a DeepSeek Harness
+workspace into a maintainable task board.
+
+### Added
+
+- **Automatic task analysis**: sessions are scanned on a schedule and turned
+  into tasks with goal, status, progress, priority, issues, next steps,
+  milestones and traceable evidence.
+- **Two analysis engines**: a zero-dependency rules engine that always works
+  offline, and an optional LLM engine that reuses the local DSH account quota
+  and degrades to rules when disabled, over budget or offline.
+- **Task detail drawer**: key facts first, editable status, subtasks, issues /
+  next steps, session context, artifacts and evidence with a direct jump back
+  to the source session.
+- **Session hand-off**: one-click "continue this task" prompt built locally
+  from the task context (no model call), inserted into the original session or
+  a new session in the same workspace.
+- **Subtask, artifact and goal tracking**: deterministic extraction from todo
+  snapshots, write/edit tool calls and presented deliverables, plus DSH session
+  goals when available.
+- **Dual presentation**: a full-page board panel and a compact right-sidebar
+  panel, with configurable entry visibility and a shortcut from the session
+  header.
+- **Manual task management**: create, edit, drag between columns, archive,
+  delete, relink sessions, lock fields so analysis never overwrites them.
+- **Local-first storage**: board state under the DSH home storage directory,
+  atomic writes, corrupt-file recovery and version migration.
+- **DSH-native visual language**: monochrome-first styling, a restrained type
+  scale, hairline borders and DSH design tokens for light and dark themes.
+
+### Changed
+
+- Analysis output and storage are budgeted: compact session digests, incremental
+  gating, per-scan and daily AI call limits, and capped evidence, key facts,
+  subtasks, artifacts and history.
+- Evidence and task payloads are trimmed for density; the board and drawer
+  prioritise "what matters now" over raw transcript dumps.
+
+### Security
+
+- The plugin runs locally inside DSH, reads session storage read-only, serves
+  its HTTP API to the authenticated owner only, and sends nothing to third
+  parties. When the LLM engine is enabled it calls the DeepSeek inference API
+  with the local DSH account token; tokens are never logged or persisted by the
+  plugin. See [SECURITY.md](./SECURITY.md).
+
+[Unreleased]: https://github.com/topmindspace/dsh-super-kanban/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/topmindspace/dsh-super-kanban/releases/tag/v0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TopMindSpace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# Super Kanban · 智能任务指挥台
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/topmindspace/dsh-super-kanban/actions/workflows/ci.yml/badge.svg)](https://github.com/topmindspace/dsh-super-kanban/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+一个**生长在 DeepSeek Harness 界面里**的 AI 任务看板：它读取你各个工作区的真实 DSH 会话，自动研判任务的目标、进度、完成情况与问题，也可以完全手动管理。每张任务卡都能追溯到具体会话与具体一句话。
+
+- **入口**：DSH 左侧栏「任务看板」，或在会话右侧栏打开紧凑形态
+- **数据**：只读扫描本机 DSH 会话；看板数据保存在本机，不出本机
+- **智能**：复用本机 DSH 已登录账号的模型额度，零配置；关闭后自动降级为本地规则分析
+
+![任务看板（浅色）](docs/screenshots/board-light.png)
+
+## 目录
+
+- [它解决什么](#它解决什么)
+- [功能特性](#功能特性)
+- [两种形态](#两种形态)
+- [安装](#安装)
+- [使用](#使用)
+- [AI 与隐私](#ai-与隐私)
+- [界面截图](#界面截图)
+- [兼容性](#兼容性)
+- [常见问题](#常见问题)
+- [开发与贡献](#开发与贡献)
+- [License](#license)
+
+## 它解决什么
+
+你在 DSH 里同时推进多个工作区、多个会话，任务状态散落在对话里：做到哪了？卡在哪？有没有交付？是不是已经不了了之？
+
+Super Kanban 把这些对话转成一张可持续维护的看板：
+
+| 能力 | 说明 |
+| --- | --- |
+| 🎯 目标识别 | 从会话里的真实请求提炼任务标题与目标，而不是把整段 prompt 当标题 |
+| 📈 进度判断 | 优先用会话中的 todo 完成率，结合交付物、轮次状态估算进度 |
+| ✅ 完成判断 | 综合最后一轮回复、交付物（present / 写文件）与用户是否继续提修改来判断完成 |
+| ⚠️ 问题识别 | 工具报错、用户否定/纠正、未解决的提问作为「问题」挂在卡片上 |
+| 🔗 可追溯 | 每张卡带来源工作区 / 会话 / 证据时间线，一键跳回原会话 |
+| 🤝 会话联动 | 「继续此任务」生成结构化提示词，确认后放入原会话或同工作区新会话输入框，不自动发送 |
+| ✅ 子任务与目标 | 子任务清单（可从会话待办导入、勾选自动回写进度）、任务目标、DSH Session Goal 追踪 |
+| 📦 产物跟踪 | 自动收集会话交付物与写出的文件，点击在 DSH 文档预览中打开 |
+| 🧾 关键事实优先 | 卡片只有 1 行关键事实；抽屉先看 3–6 条关键事实，完整证据默认折叠 |
+| ✍️ 手动维护 | 新建 / 编辑 / 拖拽换列 / 归档 / 删除 / 锁定字段；你改过的字段 AI 不再覆盖 |
+| 🔄 持续维护 | 首次约数秒完成扫描，之后按间隔增量扫描；新会话自动纳入，旧任务自动更新 |
+| 🧠 解释得清 | 每条研判带置信度与一句话理由，避免「黑箱改状态」 |
+
+## 功能特性
+
+### 双引擎分析：联网更准，离线也能用
+
+1. **采集（本机）**：读取 `workspace.json` 与各会话的 `session.v4.jsonl.zstd`，解析用户请求、AI 回复、工具调用、todo 快照、交付物、错误与轮次结束原因。
+2. **规则引擎（始终可用、零 token）**：本地规则从会话中提炼状态、进度、问题与证据，未登录、无网络或关闭 AI 时看板照常工作。
+3. **LLM 研判（可选联网）**：把压缩后的会话摘要发送到 DeepSeek 推理接口，返回结构化 JSON（任务、状态、进度、问题、证据、置信度、理由）。
+4. **合并（本机）**：按会话锚点合并进看板；用户锁定字段不覆盖；每次变化写操作历史。
+
+### Token 效率
+
+- 送模型的会话摘要（digest）压到 **≤1.5KB/会话**，只含最近变化与关键信号。
+- 输出结构化：关键事实 ≤6、证据 ≤8、`max_tokens` ≤2200，单个会话解析结果有明确上限。
+- **增量门控**：只在「用户消息增加 / 轮次结束 / 首次 / 手动重新研判」时调用模型；同一活跃 turn 内不重复分析，同一会话有最小间隔。
+- **预算可控**：设置里可配「单次扫描 AI 调用上限」与「每日上限」，超限自动降级规则引擎；设置页显示今日调用数与 tokens。
+- 反复全量扫描已分析的会话时，**0 次 AI 调用**。
+
+### 数据与隐私
+
+- 看板数据只写入本机 `~/.dsh/storages/super-kanban/`，无第三方服务器、无遥测。
+- 联网研判只发送**压缩摘要**：不发送完整会话原文、不发送文件内容、不发送账号凭证。
+- 所有 AI 功能可在设置中一键关闭，立即降级为本地规则分析。
+
+## 两种形态
+
+同一个看板支持两种打开方式：
+
+| 形态 | 怎么打开 | 特点 |
+| --- | --- | --- |
+| **全页主面板** | 左侧栏「任务看板」 | 四列完整看板 + 筛选 + 统计行，适合专注梳理 |
+| **右侧侧边栏** | 会话右上角看板图标，或会话右侧栏「+」工具列表里的「任务看板」 | 边聊边看板；宽度自适应：窄（单列 + 状态分段）/ 中 / 宽（四列） |
+
+- **右侧栏全屏**：右侧栏顶部的全屏按钮，面板铺满视口，仍可随时退出。
+- **互相切换**：全页看板「⋯ → 在右侧栏打开」；右侧栏看板「⋯ → 在全页面板打开」。
+- **入口偏好**：看板「设置 → 显示与入口」可选「两者（默认）/ 仅全局面板 / 仅会话右侧栏」，修改后刷新窗口生效。
+
+## 安装
+
+> 前置条件：已安装并至少打开过一次 DSH 桌面版（存在 `~/.dsh/profiles/desktop`），DSH 版本 `>= 0.2.1-rc.5 < 0.3.0`。
+
+### 方式 A：插件市场索引（推荐）
+
+> 「发现（Discover）」来自 DSH 的实验性插件市场能力：先在 **插件 → 实验性插件** 中启用 **插件市场 / Plugin market** 并按其提示重载 DSH。若你的 DSH 版本暂无该能力，请使用方式 B/C/D。
+
+1. DSH → **插件** → **发现（Discover）**
+2. **添加索引源**，粘贴：
+   `https://topmindspace.github.io/dsh-super-kanban/index.json`
+3. 在列表中找到 **Super Kanban** → **安装** → 启用
+4. 回到 DSH 窗口按 `Cmd+R` 刷新（必要时重启 DSH）
+
+> 市场索引在首个版本发布到 GitHub Pages 后生效；索引内容来自本仓库 `docs/`。
+
+### 方式 B：npm 包名
+
+DSH → 插件 → 添加插件 → 输入包名 `dsh-super-kanban`（可带版本，如 `dsh-super-kanban@0.3.0`）→ 安装 → 启用 → 刷新窗口。
+
+> npm 包在首个 Release 发布后可用。
+
+### 方式 C：Git 仓库
+
+插件 → 添加插件 → 粘贴仓库地址 `https://github.com/topmindspace/dsh-super-kanban` → 安装（DSH 会 pin 到具体 commit）→ 启用 → 刷新窗口。
+
+### 方式 D：本地目录 / 源码安装
+
+适合开发者和想跟进源码的用户：
+
+```bash
+git clone https://github.com/topmindspace/dsh-super-kanban.git
+cd dsh-super-kanban
+./install.sh -y       # 链接进默认 desktop profile 并在插件清单中登记
+```
+
+或在 DSH 插件页选择「本地目录」指向本仓库根目录。安装完成后刷新窗口，左侧栏出现「任务看板」。
+
+### 升级与卸载
+
+- **升级**：插件市场 / npm / Git 安装的，在插件页更新即可；源码安装的 `git pull` 后刷新窗口。
+- **卸载**：插件页移除，或源码目录执行 `./uninstall.sh -y`。
+- 卸载**不会删除**看板数据；彻底清空请删除 `~/.dsh/storages/super-kanban/`。
+
+更详细的安装、升级、排障说明见 [docs/INSTALL.md](docs/INSTALL.md)。
+
+## 使用
+
+1. 左侧栏点 **任务看板**（或会话右上角看板图标走右侧栏形态）。
+2. **看板**：四列——待办 / 进行中 / 受阻 / 已完成；列头显示数量与状态色。
+3. **卡片**：标题、来源工作区、最近活动时间、优先级、子任务进度。
+4. **详情抽屉**（点卡片打开）：
+   - 一句话状态摘要（点「编辑」可改字段）
+   - **关键事实**（3–6 条，来自会话的关键进展 / 决策 / 问题）
+   - **子任务**：勾选 / 新增 / 删除；「从会话导入待办」；进度自动回写
+   - **问题 / 下一步**
+   - **会话联动**：继续此任务 / 打开会话
+   - **产物**：点击在 DSH 右侧栏文档预览中打开
+   - 证据与历史（默认折叠）
+5. **筛选**：工作区、优先级、来源、标签、关键词搜索、显示归档。
+6. **扫描**：右上角扫描按钮立即增量扫描；扫描进度实时显示。
+7. **设置**：AI 开关、自动扫描、扫描间隔、初始扫描天数、AI 预算、显示与入口、排除工作区、导出 JSON。
+
+### 「继续此任务」怎么用
+
+1. 打开任意任务卡 → 抽屉里点 **「继续此任务」**；
+2. 弹窗里是一段已生成好的结构化提示词（任务目标 / 进度 / 关键事实 / 问题 / 下一步 / 来源会话），可直接编辑；
+3. 选 **原会话继续** 或 **同工作区新会话**；
+4. 点 **「放入会话」**：DSH 自动切到目标会话，并把提示词放进输入框——**不会自动发送**，你确认 / 修改后自己按发送即可。也可以「仅复制」或「AI 润色」提示词。
+
+> 提示词由本地模板拼装，**默认 0 token**；只有点「AI 润色」才会调用一次模型。
+
+### 手动与自动如何共存
+
+- 自动任务以来源会话为锚点，多次扫描持续更新同一张卡，不会重复建卡。
+- 你手动编辑并锁定的字段（默认编辑即锁定）AI 永不覆盖，可在详情里「解锁」交还给 AI。
+- 手动任务（来源=手动）不会被自动扫描改动。
+- 新建卡片可以不关联会话；关联后 AI 会在下次扫描时补全研判。
+
+### 快捷键
+
+| 按键 | 作用 |
+| --- | --- |
+| `/` | 聚焦搜索 |
+| `n` | 新建任务 |
+| `Esc` | 关闭当前浮层 / 抽屉 |
+| `Cmd+R` | 刷新 DSH 窗口（插件更新后需要） |
+
+## AI 与隐私
+
+### 数据流
+
+```
+DSH 会话（本机只读）
+        │  本机解析 / 规则引擎
+        ▼
+   本机看板存储 ──（可选）压缩摘要 ≤1.5KB ──► DeepSeek 推理接口
+        │                                          │
+        └──────────── 结构化 JSON 结果 ◄───────────┘
+```
+
+### 明确不上传的内容
+
+- 完整会话原文、文件内容、附件
+- 账号凭证 / token（凭证只在本机用于调用，不随请求内容发出）
+- 任何第三方服务器（无遥测、无统计上报）
+
+### 关闭 AI
+
+看板右上角「⋯ → 设置」→ 关闭「AI 联网研判」，立即生效。关闭后看板继续用本地规则引擎运行，功能不缺失，只是研判颗粒度更粗。
+
+### 成本
+
+默认增量扫描只分析**有变化的会话**，单次扫描 AI 调用默认上限 40 次，模型默认 `deepseek-flash`。日常没有新对话时几乎零消耗。你可以在设置中调低每日上限或完全关闭 AI。
+
+## 界面截图
+
+| 看板（浅色） | 看板（深色） |
+| --- | --- |
+| ![看板-浅色](docs/screenshots/board-light.png) | ![看板-深色](docs/screenshots/board-dark.png) |
+
+| 任务详情（浅色） | 任务详情（深色） |
+| --- | --- |
+| ![任务详情-浅色](docs/screenshots/drawer-light.png) | ![任务详情-深色](docs/screenshots/drawer-dark.png) |
+
+| 继续此任务弹窗 | 提示词放入原会话输入框 |
+| --- | --- |
+| ![继续此任务](docs/screenshots/continue-modal.png) | ![提示词放入会话](docs/screenshots/continue-placed.png) |
+
+| 右侧栏形态（窄） | 右侧栏全屏 |
+| --- | --- |
+| ![右侧栏形态](docs/screenshots/side-panel.png) | ![右侧栏全屏](docs/screenshots/side-fullscreen.png) |
+
+| 产物预览入口 | 设置 |
+| --- | --- |
+| ![产物](docs/screenshots/drawer-artifacts.png) | ![设置](docs/screenshots/settings-dual.png) |
+
+| 1280 宽窗口 | |
+| --- | --- |
+| ![1280](docs/screenshots/board-1280.png) | |
+
+> 以上截图来自一套完全虚构的演示数据（虚构工作区 / 会话 / 任务），不含任何真实用户或工作区信息。
+
+## 兼容性
+
+| 项 | 要求 |
+| --- | --- |
+| DeepSeek Harness | `>= 0.2.1-rc.5 < 0.3.0`（在 0.2.1-rc.5 桌面版验证） |
+| Node.js | `>= 22.19.0`（插件使用内置 `node:zlib` 的 zstd API） |
+| 平台 | macOS 桌面版已验证；其他桌面平台理论可用但未逐一验证 |
+| 第三方依赖 | 无（插件与工具脚本均为零依赖） |
+
+> 插件依赖 DSH 的第三方插件接口，DSH 大版本升级可能带来不兼容。升级 DSH 后如入口消失，先重装插件；看板数据不会丢失。
+
+## 常见问题
+
+**Q：左侧栏没有「任务看板」？**
+A：按 `Cmd+R` 刷新窗口；仍没有则重启 DSH。仍没有请查看 DSH 插件页的诊断信息（插件加载失败会提示原因）。
+
+**Q：卡片没有更新 / 一直是旧状态？**
+A：点右上角扫描按钮手动触发；或检查设置中的「自动扫描」是否开启。
+
+**Q：AI 判断错了怎么办？**
+A：点开卡片直接改字段（编辑即锁定）；也可以在卡片菜单里「重新研判」，让 AI 重新分析该任务的来源会话。
+
+**Q：不想让某些工作区进看板？**
+A：看板右上角「⋯ → 设置」→ 排除工作区（可多选）。
+
+**Q：会消耗我多少额度？**
+A：扫描时对**有变化的**会话各调用一次 `deepseek-flash`；看板设置页可查看今日调用数与 tokens。关闭 AI 后完全零额度。
+
+**Q：数据在哪里？卸载会丢吗？**
+A：`~/.dsh/storages/super-kanban/`（`state.json` / `sessions-cache.json` / `backups/`）。卸载插件不删除数据。
+
+**Q：能导出吗？**
+A：看板右上角「⋯ → 设置」→ 导出 JSON，下载 `super-kanban-YYYYMMDD.json`。
+
+## 开发与贡献
+
+- 零第三方依赖；`node --test` 测试；`scripts/` 下提供校验、隐私扫描与市场索引生成脚本。
+- 常用命令：
+
+```bash
+npm test              # 单元测试
+npm run validate      # 包清单、Cordis patch、文件与市场索引校验
+npm run check:privacy # 扫描个人路径 / 凭证 / 会话 id 等敏感内容
+npm run market:index  # 重新生成 docs/index.json
+```
+
+- 开发环境搭建、目录结构与调试方法见 [CONTRIBUTING.md](CONTRIBUTING.md) 与 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。
+- 架构说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)，接口契约见 [docs/CONTRACT.md](docs/CONTRACT.md)，视觉规范见 [docs/DESIGN.md](docs/DESIGN.md)。
+- 发布与分发流程（市场索引、npm、Git）见 [docs/MARKET.md](docs/MARKET.md)。
+- 安全问题请按 [SECURITY.md](SECURITY.md) 私下报告，不要开公开 issue。
+
+## License
+
+[MIT](LICENSE) © topmindspace