@alpacachen/dsh-kanban 1.2.0 → 1.3.0

package/README.md

@@ -62,6 +62,7 @@ The agent updates the board directly. You can then refine the plan in the UI, or
 
 - 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
@@ -88,6 +89,38 @@ A few more things you can ask:
 
 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
+  }),
+}
+```
+
+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`.
+
+Abnormal data never makes the board unusable:
+
+- **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:

package/README.zh.md

@@ -62,6 +62,7 @@ Agent 会直接更新当前看板。之后你可以在界面中继续调整，
 
 - 创建、编辑、删除卡片，并将卡片拖到其他列表
 - 为卡片补充备注、标签和 P0 / P1 / P2 优先级
+- 查看卡片的活动记录：创建时间与来源，以及标签、优先级、状态的变更历史
 - 创建、重命名、排序和删除列表
 - 创建标签并自定义颜色
 - 按优先级筛选整个看板
@@ -88,6 +89,38 @@ Agent 会直接更新当前看板。之后你可以在界面中继续调整，
 
 看板按工作区隔离，并通过 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-board-<workspaceId>.json.corrupt-<时间戳>`，看板以空板打开，并给出清晰提示。
+- **来自更新版本插件的文件**（`schemaVersion` 更高）：备份为 `kanban-board-<workspaceId>.json.unsupported-v<版本>` 且不改动原文件，避免降级插件破坏新数据。
+- 插件启动时会执行**全量校验扫描**：逐一检查看板文件（解析 + 版本 + 结构），损坏文件立即备份并汇总记录。
+
+迁移、损坏或版本超前的提示会同时出现在 Agent 工具结果（`warnings`）和「看板」标签页的提示横幅中。
+
 ## 工作原理
 
 `dsh-kanban` 使用标准的 DSH bundle 格式：