@alpacachen/dsh-kanban 1.3.7 → 1.4.0

package/README.md

@@ -27,7 +27,7 @@ You can take over at any time—drag a card, refine a note, reorder a list—and
 
 | 💬 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. |
+| Manage the board with 15 built-in `kanban_*` tools. | Edit, comment, 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. |
 
@@ -67,8 +67,9 @@ The cards appear directly on your board. Continue in conversation, or switch to
 
 - Create, edit, delete, and drag cards between lists
 - Add notes, labels, and P0 / P1 / P2 priorities
+- Exchange persistent card comments with the agent and see comment counts at a glance
 - 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
+- Track card creation, comments, 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
@@ -85,7 +86,7 @@ The plugin automatically gives the agent these tools in every workspace:
 | Area | Tools |
 | --- | --- |
 | **Board** | `kanban_get` |
-| **Cards** | `kanban_get_card`, `kanban_add_card`, `kanban_update_card`, `kanban_delete_card`, `kanban_move_card` |
+| **Cards** | `kanban_get_card`, `kanban_add_comment`, `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` |
 

package/README.zh.md

@@ -27,7 +27,7 @@
 
 | 💬 自然对话 | 🧭 随时掌控 | ⚡ 开箱即用 |
 | --- | --- | --- |
-| 通过 14 个 `kanban_*` 工具直接管理任务。 | 在界面中编辑、拖拽、标记和筛选卡片。 | 浏览器端已预构建，无需配置前端环境。 |
+| 通过 15 个 `kanban_*` 工具直接管理任务。 | 在界面中编辑、评论、拖拽、标记和筛选卡片。 | 浏览器端已预构建，无需配置前端环境。 |
 | **🗂️ 项目隔离** | **🌓 原生体验** | **🤝 实时协作** |
 | 每个 DSH 工作区都有自己的独立看板。 | 自动跟随 DSH 的语言、主题与暗色模式。 | 你做的调整，Agent 立即可见；反之亦然。 |
 
@@ -67,8 +67,9 @@ dsh --profile web --dump-config
 
 - 创建、编辑、删除卡片，并将卡片拖到其他列表
 - 为卡片补充备注、标签和 P0 / P1 / P2 优先级
+- 与 Agent 在卡片下持续评论，并在看板上快速查看评论数量
 - 打开卡片活动时间线，查看变更时间、具体内容，以及操作来自你还是 Agent
-- 追踪卡片创建、移动、标题与备注编辑、标签变化和优先级变化
+- 追踪卡片创建、评论、移动、标题与备注编辑、标签变化和优先级变化
 - 从任意卡片发起对话，在当前会话或新会话中让 Agent 接着处理
 - 创建、重命名、排序和删除工作流列表
 - 创建彩色标签，让不同任务一眼可辨
@@ -85,7 +86,7 @@ dsh --profile web --dump-config
 | 范围 | 工具 |
 | --- | --- |
 | **看板** | `kanban_get` |
-| **卡片** | `kanban_get_card`、`kanban_add_card`、`kanban_update_card`、`kanban_delete_card`、`kanban_move_card` |
+| **卡片** | `kanban_get_card`、`kanban_add_comment`、`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` |
 

package/index.js

@@ -7,14 +7,15 @@
  * 职责：
  *  - 按工作区（项目）隔离：boards 以 workspaceId 为键，每个工作区一块独立看板
  *  - 磁盘持久化：经 ctx.fs 写入 <workspace.path>/.dsh-kanban.json
- *  - 模型工具：经 ctx.tools.register 注册 14 个 kanban_* 工具
+ *  - 模型工具：经 ctx.tools.register 注册 15 个 kanban_* 工具
  *  - 浏览器数据层：经 ctx.get('webServer') 注册 /api/kanban 前缀路由
  *
  * 数据模型（每工作区，磁盘文件带 schemaVersion）：
- *   schemaVersion: 2
+ *   schemaVersion: 3
  *   columns: [{ id, title }]
  *   labels:  [{ name, color }]          —— 标签与颜色绑定，name 为唯一键
- *   cards:   [{ id, columnId, title, note, label, priority, createdAt, createdBy }]
+ *   cards:   [{ id, columnId, title, note, label, priority, createdAt, createdBy,
+ *               comments: [{ id, content, source, createdAt }] }]
  *   activities: [{ id, ts, cardId, type, source, field?, from?, to?, meta? }]  —— 追加式活动日志
  *
  * 数据安全：
@@ -44,7 +45,7 @@ export const inject = ['tools']
 // 旧文件在首次打开时自动沿迁移链升级，升级前原文件先备份。
 // ---------------------------------------------------------------------------
 
-export const SCHEMA_VERSION = 2
+export const SCHEMA_VERSION = 3
 export const LEGACY_VERSION = 0
 
 // 活动日志：追加式只读记录，随看板一起落盘；超过上限丢弃最旧事件，防止日志无界增长。
@@ -104,6 +105,20 @@ export const MIGRATIONS = {
       activities: [],
     }
   },
+  2: (data) => {
+    // v2 → v3：卡片新增评论数组；历史卡片默认没有评论
+    const src = isObj(data) ? data : {}
+    const pick = (arr) => (Array.isArray(arr) ? arr : [])
+    return {
+      schemaVersion: 3,
+      columns: pick(src.columns),
+      labels: pick(src.labels),
+      cards: pick(src.cards)
+        .map((c) => (isObj(c) ? { ...c, comments: [] } : null))
+        .filter(Boolean),
+      activities: pick(src.activities),
+    }
+  },
 }
 
 /**
@@ -177,8 +192,9 @@ export function validateBoard(data) {
 
   if (Array.isArray(data.cards)) {
     const seen = new Set()
+    const commentIds = new Set()
     for (const c of data.cards) {
-      if (!isObj(c) || typeof c.id !== 'string' || !c.id || typeof c.columnId !== 'string' || typeof c.title !== 'string') {
+      if (!isObj(c) || typeof c.id !== 'string' || !c.id || typeof c.columnId !== 'string' || typeof c.title !== 'string' || !Array.isArray(c.comments)) {
         errors.push('cards contain an invalid entry')
         break
       }
@@ -189,6 +205,17 @@ export function validateBoard(data) {
       if (!columnIds.has(c.columnId)) errors.push('card references missing column: ' + c.id)
       if (c.label != null && !labelNames.has(c.label)) errors.push('card references missing label: ' + c.id)
       if (c.priority != null && !['high', 'medium', 'low'].includes(c.priority)) errors.push('card has invalid priority: ' + c.id)
+      for (const comment of c.comments) {
+        if (!isObj(comment) || typeof comment.id !== 'string' || !comment.id || typeof comment.content !== 'string' || !comment.content.trim() || comment.content.length > 2000 || !['human', 'agent'].includes(comment.source) || typeof comment.createdAt !== 'string' || !comment.createdAt) {
+          errors.push('card comments contain an invalid entry: ' + c.id)
+          break
+        }
+        if (commentIds.has(comment.id)) {
+          errors.push('duplicate comment id: ' + comment.id)
+          break
+        }
+        commentIds.add(comment.id)
+      }
       seen.add(c.id)
     }
   }
@@ -444,7 +471,10 @@ export function apply(ctx) {
         }
       }
       for (const col of board.columns) bumpSeq(col.id)
-      for (const card of board.cards) bumpSeq(card.id)
+      for (const card of board.cards) {
+        bumpSeq(card.id)
+        for (const comment of card.comments) bumpSeq(comment.id)
+      }
       for (const act of board.activities) bumpSeq(act.id)
       if (board.columns.length === 0) {
         for (const title of DEFAULT_COLUMNS) board.columns.push({ id: nextId('c'), title })
@@ -515,6 +545,14 @@ export function apply(ctx) {
       priority: c.priority ?? null,
       createdAt: typeof c.createdAt === 'string' ? c.createdAt : null,
       createdBy: typeof c.createdBy === 'string' ? c.createdBy : null,
+      comments: Array.isArray(c.comments)
+        ? c.comments.map((comment) => ({
+            id: comment.id,
+            content: comment.content,
+            source: comment.source,
+            createdAt: comment.createdAt,
+          }))
+        : [],
     })),
     activities: Array.isArray(b.activities) ? b.activities.map((a) => ({ ...a })) : [],
   })
@@ -531,6 +569,7 @@ export function apply(ctx) {
       title: c.title,
       label: c.label ?? null,
       priority: c.priority ?? null,
+      commentCount: c.comments.length,
     })),
   })
 
@@ -583,6 +622,7 @@ export function apply(ctx) {
           priority: normPriority(a.priority),
           createdAt: new Date().toISOString(),
           createdBy: actor,
+          comments: [],
         }
         board.cards.push(card)
         record(board, {
@@ -640,6 +680,24 @@ export function apply(ctx) {
           : result({ error: 'Card not found: ' + str(a.id, '') })
       }
 
+      case 'addComment': {
+        const card = findCard(board, str(a.id, ''))
+        if (!card) return result({ error: 'Card not found: ' + str(a.id, '') })
+        const content = str(a.content, '').trim()
+        if (!content) return result({ error: 'Comment content required' })
+        if (content.length > 2000) return result({ error: 'Comment exceeds 2000 characters' })
+        const comment = {
+          id: nextId('m'),
+          content,
+          source: actor,
+          createdAt: new Date().toISOString(),
+        }
+        card.comments.push(comment)
+        record(board, { cardId: card.id, type: 'card_comment_added', source: actor, meta: { title: card.title } })
+        await save(workspace, session)
+        return result({ message: 'Comment added' })
+      }
+
       case 'deleteCard': {
         const id = str(a.id, '')
         const card = findCard(board, id)
@@ -1033,7 +1091,8 @@ export function apply(ctx) {
             '  - [' + card.id + '] ' +
             (card.priority ? '[' + card.priority + '] ' : '') +
             (card.label ? '[' + card.label + '] ' : '') +
-            card.title,
+            card.title +
+            (card.commentCount ? ' (' + card.commentCount + ' comments)' : ''),
           )
         }
       }
@@ -1054,7 +1113,7 @@ export function apply(ctx) {
     },
     {
       name: 'kanban_get_card',
-      description: "Read one card's full details (title, note, label, priority) by id from the current project (workspace) board. Use kanban_get first to discover card ids, then this tool to read a card's complete note and fields.",
+      description: "Read one card's full details (title, note, label, priority and comments) by id from the current project (workspace) board. Use kanban_get first to discover card ids, then this tool to read the complete card and comment history.",
       parameters: {
         type: 'object',
         properties: {
@@ -1086,6 +1145,12 @@ export function apply(ctx) {
             if (c.priority) lines.push('Priority: ' + c.priority)
             if (c.label) lines.push('Label: ' + c.label)
             if (c.note) lines.push('Note: ' + c.note)
+            if (Array.isArray(c.comments) && c.comments.length > 0) {
+              lines.push('Comments:')
+              for (const comment of c.comments) {
+                lines.push('  - [' + comment.createdAt + '] ' + comment.source + ': ' + comment.content)
+              }
+            }
           }
           return [{ type: 'text', text: lines.join('\n') }]
         },
@@ -1099,6 +1164,22 @@ export function apply(ctx) {
         return { ok: true, message: 'Card ' + String(args.id || '') + ' details', card: r.card, warnings: Array.isArray(r.warnings) ? r.warnings : [] }
       },
     },
+    {
+      name: 'kanban_add_comment',
+      description: 'Add a comment to a card in the current project (workspace). Use it to leave progress updates, decisions, questions, or review feedback.',
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Card id' },
+          content: { type: 'string', description: 'Comment text (1-2000 characters)' },
+        },
+        required: ['id', 'content'],
+      },
+      output: output(renderBoard),
+      async execute(args, exec) {
+        return runTool('addComment', args, exec)
+      },
+    },
     {
       name: 'kanban_add_card',
       description: 'Add a card to the current project (workspace) kanban board. Write feature breakdowns and plans to the board: one card per task step.',