npm - @alpacachen/dsh-kanban - Versions diffs - 1.3.0 → 1.3.2 - Mend

@alpacachen/dsh-kanban 1.3.0 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -2,171 +2,105 @@
 # dsh-kanban
-**Plan with your AI. See the work move.**
+### Plan with AI. Move work forward visually.
-A shared kanban board for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), built for both people and agents.
+A collaborative kanban board where you and your AI agent plan, organize, and ship work together—without leaving DeepSeek Harness.
-[简体中文](README.zh.md) · English
+[![npm version](https://img.shields.io/npm/v/@alpacachen/dsh-kanban?color=5b8def&label=npm)](https://www.npmjs.com/package/@alpacachen/dsh-kanban)
+![DeepSeek Harness Plugin](https://img.shields.io/badge/DeepSeek%20Harness-Plugin-7c5cff)
+![License](https://img.shields.io/badge/license-MIT-22c55e)
-</div>
+[简体中文](README.zh.md) · **English**
-Turn a conversation into an actionable plan without copying tasks between your AI assistant and a project tracker. Ask the agent to break down a feature, prioritize a bug, or move finished work—the same changes appear instantly in the **Board** tab, where you can continue organizing everything by hand.
+</div>
 <p align="center">
   <img src="./image.png" alt="dsh-kanban board inside DeepSeek Harness" width="100%">
 </p>
-## Why dsh-kanban?
+## ✨ From conversation to action
+Stop copying AI-generated plans into a separate project tracker. Tell your agent what you want to build, and watch it turn the plan into cards, priorities, labels, and workflow updates on the **Board** tab.
-- **Plan in conversation** — 14 `kanban_*` tools let the agent create and manage cards, lists, and labels.
-- **Stay in control** — edit cards, drag work between lists, reorder your workflow, and filter by priority from the UI.
-- **Keep projects separate** — every DSH workspace gets its own board and persisted data.
-- **Feel at home in DSH** — the board follows the active language and theme, including dark mode.
-- **Install and go** — the browser bundle is prebuilt; no frontend toolchain or native build step is required.
+You can take over at any time—drag a card, refine a note, reorder a list—and the agent immediately works from the same board.
-## Quick start
+| 💬 Plan naturally | 🧭 Stay in control | ⚡ Start instantly |
+| --- | --- | --- |
+| Manage the board with 14 built-in `kanban_*` tools. | Edit, drag, prioritize, label, and filter from the UI. | Install the prebuilt plugin—no frontend setup required. |
+| **🗂️ Keep work separate** | **🌓 Feel at home** | **🤝 Share one source of truth** |
+| Every DSH workspace gets its own board. | Follows your DSH language, theme, and dark mode. | You and the agent always see the same tasks and status. |
-### 1. Install the plugin
+## 🚀 Get started
-Install the published npm package:
+### 1. Install
 ```sh
 dsh plugin --profile web add @alpacachen/dsh-kanban
 ```
-GitHub source checkouts are not a supported installation method because the generated browser bundle is created only by CI for the npm package.
-Restart `dsh web` after installation so the plugin bundle is loaded. To confirm that it was added successfully:
+Restart `dsh web` so the plugin bundle is loaded. You can confirm the installation with:
 ```sh
 dsh --profile web --dump-config
 ```
-The output should include a `dsh-kanban` layer.
+Look for a `dsh-kanban` layer in the output.
+### 2. Open your board
-### 2. Open the board
+Enter any workspace and choose the **Board** tab beside the conversation views. A fresh board starts with four familiar stages:
-Open a workspace and select the **Board** tab next to the conversation views. A new board starts with **Todo**, **In Progress**, **Review**, and **Done**.
+`Todo` → `In Progress` → `Review` → `Done`
-### 3. Plan with the agent
+### 3. Ask your agent to plan
-Try a prompt like:
+Try this:
-> Break the authentication feature into implementation tasks, add one card per step, and mark the security review as P0.
+> Break the authentication feature into implementation tasks, create one card per step, and mark the security review as P0.
-The agent updates the board directly. You can then refine the plan in the UI, or keep working through conversation.
+The cards appear directly on your board. Continue in conversation, or switch to the Board tab and shape the plan by hand.
-## What you can do
+## 🧩 Everything you need to keep work moving
-### From the Board tab
+### On the Board
 - Create, edit, delete, and drag cards between lists
 - Add notes, labels, and P0 / P1 / P2 priorities
-- View a card's activity history: when it was created and by whom, plus label / priority / status changes
-- Create, rename, reorder, and remove lists
-- Create labels and customize their colors
-- Filter the board by priority
-### From a conversation
-The plugin makes these tools available automatically in every workspace conversation:
-| Area | Tools |
-| --- | --- |
-| Board | `kanban_get` |
-| Cards | `kanban_get_card`, `kanban_add_card`, `kanban_update_card`, `kanban_delete_card`, `kanban_move_card` |
-| Lists | `kanban_add_column`, `kanban_rename_column`, `kanban_delete_column`, `kanban_move_column` |
-| Labels | `kanban_get_label`, `kanban_add_label`, `kanban_update_label`, `kanban_delete_label` |
+- Open a card's activity timeline to see when it changed, what changed, and whether you or the agent made the change
+- Track card creation, moves, title and note edits, label changes, and priority changes
+- Send any card to the agent in your current conversation or a new one
+- Create, rename, reorder, and remove workflow lists
+- Create color-coded labels for fast visual scanning
+- Filter the entire board by priority, or manually refresh it whenever needed
-A few more things you can ask:
+### Continue any card with your agent
-- “Summarize what is currently in progress.”
-- “Move ‘Fix login redirect’ to In Progress and set it to P0.”
-- “Add a Blocked list after In Progress.”
-- “Create a red Urgent label and apply it to the release card.”
-## Data and persistence
-Boards are isolated by workspace and stored through the DSH filesystem service as `kanban-board-<workspaceId>.json`. They survive browser refreshes and DSH restarts, and uninstalling the plugin does not delete existing board data.
-### Schema versioning and safe migration
-Persisted files carry a `schemaVersion` field (currently `1`). Files written by older versions (without a version field) are treated as `v0` and are **automatically upgraded the first time the workspace board is opened** — the pre-upgrade file is copied to `kanban-board-<workspaceId>.json.bak-v0` first, then the upgraded file is written back. Future format changes simply bump `SCHEMA_VERSION` and register a step-by-step migration function in `MIGRATIONS` (`index.js`).
-#### Adding a future format version (e.g. v2)
-Migration functions live in `MIGRATIONS` in `index.js` and are pure functions — they transform data only, never touch the filesystem or runtime state. Each step upgrades by exactly one version; `migrateBoard` chains them automatically, so a `v0` file walks `v0 → v1 → v2`. Backups and write-back are handled by the load pipeline.
-```js
-export const SCHEMA_VERSION = 2 // 1) bump the version
-export const MIGRATIONS = {
-  0: (data) => ({ /* existing v0 → v1, unchanged */ }),
-  1: (data) => ({
-    schemaVersion: 2, // 2) output must declare the new version
-    columns: data.columns,
-    labels: data.labels,
-    cards: data.cards.map((c) => ({ ...c, labelId: c.label ?? null })), // e.g. label → labelId
-  }),
-}
-```
+Open a card and choose **Chat with agent**. dsh-kanban carries its ID, title, label, and notes into either the current conversation or a fresh one, so the agent has the context it needs immediately. The content is inserted as an editable draft—it is never sent until you choose to send it.
-If the on-disk shape changes, update `validateBoard` in `index.js` and the client types in `src/client/lib/types.ts` accordingly, and extend the self-checks in `scripts/check-schema.mjs` / `scripts/check-pipeline.mjs`.
+### In conversation
-Abnormal data never makes the board unusable:
+The plugin automatically gives the agent these tools in every workspace:
-- **Corrupt/unparseable files** are backed up to `kanban-board-<workspaceId>.json.corrupt-<timestamp>` and the board opens empty, with a clear notice.
-- **Files from a newer plugin version** (higher `schemaVersion`) are backed up to `kanban-board-<workspaceId>.json.unsupported-v<version>` and left untouched, so no data is destroyed by a downgraded plugin.
-- At plugin startup a **validation scan** checks every board file (parse + version + structure), backs up any corrupt files, and logs a summary.
-Notices from migrations, corruption, or unsupported versions are surfaced both in the agent tool results (`warnings`) and as a banner in the Board tab.
-## How it works
-`dsh-kanban` uses the standard DSH bundle format:
-- `index.js` registers the agent tools and the `/api/kanban` browser endpoint.
-- Both interfaces share one data layer, so the agent and the Board tab always operate on the same board.
-- `cordis.patch.yml` adds the plugin to the selected DSH profile.
-- `lib/client.js` is the prebuilt web client loaded by DSH.
-The client is built with React, TypeScript, Tailwind CSS, shadcn/ui, Radix UI, and dnd-kit. React itself is provided by DSH, keeping the distributed bundle smaller and avoiding duplicate runtimes.
-## Development
-Requirements: Node.js and pnpm.
-```sh
-pnpm install
-pnpm build
-pnpm typecheck
-```
+| Area | Tools |
+| --- | --- |
+| **Board** | `kanban_get` |
+| **Cards** | `kanban_get_card`, `kanban_add_card`, `kanban_update_card`, `kanban_delete_card`, `kanban_move_card` |
+| **Lists** | `kanban_add_column`, `kanban_rename_column`, `kanban_delete_column`, `kanban_move_column` |
+| **Labels** | `kanban_get_label`, `kanban_add_label`, `kanban_update_label`, `kanban_delete_label` |
-For an unminified client bundle while debugging:
+## 💡 Things to ask your agent
-```sh
-node build.mjs --no-minify
-```
+> “Summarize what is currently in progress.”
-Project layout:
+> “Move ‘Fix login redirect’ to In Progress and set it to P0.”
-```text
-index.js              # Host plugin, tools, persistence, and HTTP endpoint
-cordis.patch.yml      # DSH bundle patch
-build.mjs             # Client build script
-src/client/           # React and TypeScript source
-lib/client.js         # Generated locally or by CI; included only in the npm package
-```
-## Contributing
+> “Add a Blocked list after In Progress.”
-Issues and pull requests are welcome. If you are planning a larger change, opening an issue first is a good way to align on the approach before implementation.
+> “Create a red Urgent label and apply it to the release card.”
-## Uninstall
+> “I'm a lawyer. Set up a board for my day-to-day casework, create the workflow stages and labels I’ll need, and keep them up to date as my work evolves.”
-```sh
-dsh plugin --profile web remove @alpacachen/dsh-kanban
-```
+You do not need to design the workflow first. Tell the agent your role, situation, or goal, and it can create suitable stages and labels—then keep refining them as you work.
 ## License

package/README.zh.md CHANGED Viewed

@@ -2,171 +2,105 @@
 # dsh-kanban
-**和 AI 一起规划，在看板上看到进展。**
+### 和 AI 一起规划，让每一步进展清晰可见。
-一个为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 打造、由你和 Agent 共同维护的项目看板。
+一块真正由你和 AI Agent 共同维护的项目看板——从想法、任务拆解到推进交付，全程无需离开 DeepSeek Harness。
-简体中文 · [English](README.md)
+[![npm version](https://img.shields.io/npm/v/@alpacachen/dsh-kanban?color=5b8def&label=npm)](https://www.npmjs.com/package/@alpacachen/dsh-kanban)
+![DeepSeek Harness Plugin](https://img.shields.io/badge/DeepSeek%20Harness-Plugin-7c5cff)
+![License](https://img.shields.io/badge/license-MIT-22c55e)
-</div>
+**简体中文** · [English](README.md)
-不用再把 AI 给出的计划手动搬进项目管理工具。让 Agent 拆解功能、调整优先级或推进任务，变更会立即出现在 **「看板」**标签页；你也可以随时接手，通过拖拽和编辑继续整理工作。
+</div>
 <p align="center">
   <img src="./image.png" alt="DeepSeek Harness 中的 dsh-kanban 看板界面" width="100%">
 </p>
-## 为什么是 dsh-kanban？
+## ✨ 从一句话，到一块能执行的看板
+不必再把 AI 生成的计划手动搬进项目管理工具。告诉 Agent 你想完成什么，它就能在 **「看板」** 标签页中拆分任务、创建卡片、设置优先级和更新进度。
-- **在对话里完成规划**：14 个 `kanban_*` 工具让 Agent 能直接管理卡片、列表和标签。
-- **一切仍由你掌控**：编辑卡片、跨列拖拽、调整工作流，或按优先级筛选任务。
-- **项目之间互不干扰**：每个 DSH 工作区都有独立看板，并自动持久化数据。
-- **自然融入 DSH**：界面跟随当前语言和主题，也支持暗色模式。
-- **安装后即可使用**：浏览器端已预构建，不需要额外配置前端工具链，也没有原生构建步骤。
+你也可以随时接手：拖动卡片、补充备注、调整列表。你和 Agent 始终面对同一块看板、同一份进度。
-## 快速开始
+| 💬 自然对话 | 🧭 随时掌控 | ⚡ 开箱即用 |
+| --- | --- | --- |
+| 通过 14 个 `kanban_*` 工具直接管理任务。 | 在界面中编辑、拖拽、标记和筛选卡片。 | 浏览器端已预构建，无需配置前端环境。 |
+| **🗂️ 项目隔离** | **🌓 原生体验** | **🤝 实时协作** |
+| 每个 DSH 工作区都有自己的独立看板。 | 自动跟随 DSH 的语言、主题与暗色模式。 | 你做的调整，Agent 立即可见；反之亦然。 |
-### 1. 安装插件
+## 🚀 三步开始使用
-从 npm 安装已发布的包：
+### 1. 安装
 ```sh
 dsh plugin --profile web add @alpacachen/dsh-kanban
 ```
-项目不支持从 GitHub 源码安装，因为生成的浏览器 bundle 只会由 CI 构建并放入 npm 包。
-安装后重启 `dsh web`，让插件 bundle 在启动时加载。可以通过下面的命令确认配置：
+安装后重启 `dsh web`，让插件 bundle 完成加载。你可以用下面的命令确认安装结果：
 ```sh
 dsh --profile web --dump-config
 ```
-如果安装成功，输出中会包含 `dsh-kanban` 配置层。
+如果输出中包含 `dsh-kanban` 配置层，就说明安装成功。
 ### 2. 打开看板
-进入任意工作区，在会话视图旁打开**「看板」**标签页。新看板默认包含 **Todo**、**In Progress**、**Review** 和 **Done** 四个列表。
+进入任意工作区，点击会话视图旁的 **「看板」** 标签页。新看板已经准备好四个常用阶段：
+`Todo` → `In Progress` → `Review` → `Done`
 ### 3. 让 Agent 开始规划
 试试这样说：
-> 把登录功能拆成具体的实现任务，每一步建一张卡片，并把安全审查标为 P0。
+> 把登录功能拆成具体的实现任务，每一步创建一张卡片，并把安全审查标为 P0。
-Agent 会直接更新当前看板。之后你可以在界面中继续调整，也可以留在对话里推进任务。
+任务会直接出现在看板中。你可以继续通过对话推进，也可以切换到看板，用拖拽和编辑完善计划。
-## 你可以做什么
+## 🧩 推进工作需要的能力，都在这里
 ### 在「看板」标签页中
 - 创建、编辑、删除卡片，并将卡片拖到其他列表
 - 为卡片补充备注、标签和 P0 / P1 / P2 优先级
-- 查看卡片的活动记录：创建时间与来源，以及标签、优先级、状态的变更历史
-- 创建、重命名、排序和删除列表
-- 创建标签并自定义颜色
-- 按优先级筛选整个看板
+- 打开卡片活动时间线，查看变更时间、具体内容，以及操作来自你还是 Agent
+- 追踪卡片创建、移动、标题与备注编辑、标签变化和优先级变化
+- 从任意卡片发起对话，在当前会话或新会话中让 Agent 接着处理
+- 创建、重命名、排序和删除工作流列表
+- 创建彩色标签，让不同任务一眼可辨
+- 按优先级筛选整个看板，也可以随时手动刷新
+### 从任意卡片继续与 Agent 协作
+打开卡片并选择 **「与 Agent 聊一聊」**，dsh-kanban 会把卡片 ID、标题、标签和备注带入当前会话或一个新会话，让 Agent 立即获得完整上下文。内容只会填入输入框作为可编辑草稿，由你确认后发送，不会自动提交。
 ### 在对话中
-插件会自动为工作区内的对话提供以下工具：
+插件会自动为每个工作区中的 Agent 提供以下工具：
 | 范围 | 工具 |
 | --- | --- |
-| 看板 | `kanban_get` |
-| 卡片 | `kanban_get_card`、`kanban_add_card`、`kanban_update_card`、`kanban_delete_card`、`kanban_move_card` |
-| 列表 | `kanban_add_column`、`kanban_rename_column`、`kanban_delete_column`、`kanban_move_column` |
-| 标签 | `kanban_get_label`、`kanban_add_label`、`kanban_update_label`、`kanban_delete_label` |
-你还可以这样使用：
-- 「总结一下目前正在进行的任务。」
-- 「把『修复登录跳转』移到进行中，并设为 P0。」
-- 「在进行中后面新增一个阻塞列表。」
-- 「创建一个红色的『紧急』标签，并加到发布卡片上。」
-## 数据与持久化
-看板按工作区隔离，并通过 DSH 文件系统服务保存为 `kanban-board-<workspaceId>.json`。刷新页面或重启 DSH 都不会丢失数据；卸载插件时，已有的看板数据也会保留。
-### 版本化与安全迁移
-持久化文件带 `schemaVersion` 字段（当前为 `1`）。旧版本插件写入的文件（无版本字段）按 `v0` 处理，在**该工作区看板首次打开时自动升级**——先复制出 `kanban-board-<workspaceId>.json.bak-v0` 备份，再写回升级后的文件。后续格式演进只需递增 `SCHEMA_VERSION` 并在 `MIGRATIONS`（`index.js`）里注册逐版本迁移函数。
-#### 新增一个格式版本（以 v2 为例）
-迁移函数写在 `index.js` 的 `MIGRATIONS` 注册表里，必须是**纯函数**——只做数据变换，不触碰文件系统或运行时状态。每步只升级一个版本，`migrateBoard` 会自动串联，v0 文件会依次走 `v0 → v1 → v2`；备份与写回由加载管线处理，无需手写脚本。
-```js
-export const SCHEMA_VERSION = 2 // 1) 递增版本号
-export const MIGRATIONS = {
-  0: (data) => ({ /* 现有 v0 → v1，保持不变 */ }),
-  1: (data) => ({
-    schemaVersion: 2, // 2) 输出必须声明新版本号
-    columns: data.columns,
-    labels: data.labels,
-    cards: data.cards.map((c) => ({ ...c, labelId: c.label ?? null })), // 例如 label → labelId
-  }),
-}
-```
-如果磁盘形状发生变化，同步更新 `index.js` 里的 `validateBoard` 与 `src/client/lib/types.ts` 的客户端类型，并在 `scripts/check-schema.mjs` / `scripts/check-pipeline.mjs` 中补充自检用例。
+| **看板** | `kanban_get` |
+| **卡片** | `kanban_get_card`、`kanban_add_card`、`kanban_update_card`、`kanban_delete_card`、`kanban_move_card` |
+| **列表** | `kanban_add_column`、`kanban_rename_column`、`kanban_delete_column`、`kanban_move_column` |
+| **标签** | `kanban_get_label`、`kanban_add_label`、`kanban_update_label`、`kanban_delete_label` |
-异常数据不会让看板不可用：
+## 💡 你可以直接这样说
-- **损坏/无法解析的文件**：备份为 `kanban-board-<workspaceId>.json.corrupt-<时间戳>`，看板以空板打开，并给出清晰提示。
-- **来自更新版本插件的文件**（`schemaVersion` 更高）：备份为 `kanban-board-<workspaceId>.json.unsupported-v<版本>` 且不改动原文件，避免降级插件破坏新数据。
-- 插件启动时会执行**全量校验扫描**：逐一检查看板文件（解析 + 版本 + 结构），损坏文件立即备份并汇总记录。
+> 「总结一下目前正在进行的任务。」
-迁移、损坏或版本超前的提示会同时出现在 Agent 工具结果（`warnings`）和「看板」标签页的提示横幅中。
+> 「把『修复登录跳转』移到进行中，并设为 P0。」
-## 工作原理
+> 「在进行中后面新增一个阻塞列表。」
-`dsh-kanban` 使用标准的 DSH bundle 格式：
+> 「创建一个红色的『紧急』标签，并加到发布卡片上。」
-- `index.js` 注册 Agent 工具和浏览器端使用的 `/api/kanban` 接口。
-- Agent 与「看板」标签页共享同一套数据层，双方看到的始终是同一块看板。
-- `cordis.patch.yml` 将插件加入指定的 DSH profile。
-- `lib/client.js` 是由 DSH 直接加载的预构建 Web 客户端。
+> 「我是一名律师，请帮我初始化一套适合日常办案的看板，根据工作流程创建阶段列表和常用标签，并随着工作变化持续帮我维护。」
-客户端使用 React、TypeScript、Tailwind CSS、shadcn/ui、Radix UI 和 dnd-kit 构建。React 由 DSH 提供，以减少发布体积并避免重复运行时。
-## 本地开发
-需要准备 Node.js 和 pnpm。
-```sh
-pnpm install
-pnpm build
-pnpm typecheck
-```
-调试时可以生成未压缩的客户端 bundle：
-```sh
-node build.mjs --no-minify
-```
-项目结构：
-```text
-index.js              # 宿主插件、Agent 工具、持久化与 HTTP 接口
-cordis.patch.yml      # DSH bundle 补丁
-build.mjs             # 客户端构建脚本
-src/client/           # React 与 TypeScript 源码
-lib/client.js         # 本地或 CI 生成，仅随 npm 包发布
-```
-## 参与贡献
-欢迎提交 Issue 和 Pull Request。如果准备进行较大的改动，建议先开一个 Issue 讨论目标和实现方式，避免重复工作。
-## 卸载
-```sh
-dsh plugin --profile web remove @alpacachen/dsh-kanban
-```
+不必提前设计好工作流。只需告诉 Agent 你的职业、场景或目标，它就能为你创建合适的阶段和标签，并在后续协作中持续调整。
 ## 开源许可