@alpacachen/dsh-kanban 1.3.7 → 1.5.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,12 +45,21 @@ export const inject = ['tools']
 // 旧文件在首次打开时自动沿迁移链升级，升级前原文件先备份。
 // ---------------------------------------------------------------------------
 
-export const SCHEMA_VERSION = 2
+export const SCHEMA_VERSION = 3
 export const LEGACY_VERSION = 0
 
 // 活动日志：追加式只读记录，随看板一起落盘；超过上限丢弃最旧事件，防止日志无界增长。
 const ACTIVITY_LIMIT = 5000
 
+// 输入长度上限：与工具 schema 描述、客户端编辑器（CardDialog）保持一致。
+// 超长输入在写入前被截断，并通过看板 warnings 通道发出一次性警告（见 clampText），
+// 因此 agent 与用户都能感知到内容被裁剪，而不是静默丢失。
+export const TITLE_LIMIT = 120
+export const NOTE_LIMIT = 2000
+export const LABEL_LIMIT = 20
+export const COLUMN_TITLE_LIMIT = 40
+export const COMMENT_LIMIT = 2000
+
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
 const strField = (v, fb) => (typeof v === 'string' && v ? v : fb)
 const normColor = (v) => (typeof v === 'string' && /^#[0-9a-fA-F]{6}$/.test(v) ? v.toLowerCase() : '#94a3b8')
@@ -104,6 +114,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 +201,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 +214,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 +480,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 })
@@ -496,6 +535,16 @@ export function apply(ctx) {
 
   // ---- 校验 / 查找 / 序列化 ----
   const str = (v, fb) => (typeof v === 'string' ? v : fb)
+
+  // 截断辅助：把输入裁到 limit 以内；一旦实际发生截断，就经看板 warnings 通道
+  // 发出一次性警告（同时写入宿主日志），避免内容被静默丢弃。
+  const clampText = (value, limit, field, board) => {
+    const s = str(value, '')
+    if (s.length <= limit) return s
+    warn(board, field + ' truncated to ' + limit + ' characters')
+    return s.slice(0, limit)
+  }
+
   const PRIORITIES = ['high', 'medium', 'low']
   const normPriority = (v) => (typeof v === 'string' && PRIORITIES.includes(v) ? v : undefined)
   const normColor = (v) => (typeof v === 'string' && /^#[0-9a-fA-F]{6}$/.test(v) ? v.toLowerCase() : undefined)
@@ -515,6 +564,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 +588,7 @@ export function apply(ctx) {
       title: c.title,
       label: c.label ?? null,
       priority: c.priority ?? null,
+      commentCount: c.comments.length,
     })),
   })
 
@@ -572,17 +630,18 @@ export function apply(ctx) {
       case 'addCard': {
         const col = findColumn(board, str(a.columnId, '')) || board.columns[0]
         if (!col) return result({ error: 'No list available' })
-        const label = typeof a.label === 'string' ? a.label.slice(0, 20) : undefined
+        const label = typeof a.label === 'string' ? clampText(a.label, LABEL_LIMIT, 'Label', board) : undefined
         if (label && !findLabel(board, label)) return result({ error: 'Label not found: ' + label })
         const card = {
           id: nextId('k'),
           columnId: col.id,
-          title: str(a.title, '').slice(0, 120) || 'Untitled card',
-          note: str(a.note, '').slice(0, 500),
+          title: clampText(a.title, TITLE_LIMIT, 'Title', board) || 'Untitled card',
+          note: clampText(a.note, NOTE_LIMIT, 'Note', board),
           label,
           priority: normPriority(a.priority),
           createdAt: new Date().toISOString(),
           createdBy: actor,
+          comments: [],
         }
         board.cards.push(card)
         record(board, {
@@ -603,7 +662,7 @@ export function apply(ctx) {
       case 'updateCard': {
         const card = findCard(board, str(a.id, ''))
         if (card) {
-          const nextLabel = typeof a.label === 'string' ? a.label.slice(0, 20) : undefined
+          const nextLabel = typeof a.label === 'string' ? clampText(a.label, LABEL_LIMIT, 'Label', board) : undefined
           if (nextLabel && !findLabel(board, nextLabel)) return result({ error: 'Label not found: ' + nextLabel })
           const before = {
             title: card.title,
@@ -611,8 +670,8 @@ export function apply(ctx) {
             label: card.label ?? null,
             priority: card.priority ?? null,
           }
-          if (typeof a.title === 'string') card.title = a.title.slice(0, 120) || card.title
-          if (typeof a.note === 'string') card.note = a.note.slice(0, 500)
+          if (typeof a.title === 'string') card.title = clampText(a.title, TITLE_LIMIT, 'Title', board) || card.title
+          if (typeof a.note === 'string') card.note = clampText(a.note, NOTE_LIMIT, 'Note', board)
           if (typeof a.label === 'string') card.label = nextLabel || undefined
           if (typeof a.priority === 'string') card.priority = normPriority(a.priority)
           const after = {
@@ -640,6 +699,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 > COMMENT_LIMIT) return result({ error: 'Comment exceeds ' + COMMENT_LIMIT + ' 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)
@@ -673,7 +750,7 @@ export function apply(ctx) {
       }
 
       case 'addColumn': {
-        const title = str(a.title, '').slice(0, 40) || 'New list'
+        const title = clampText(a.title, COLUMN_TITLE_LIMIT, 'List title', board) || 'New list'
         board.columns.push({ id: nextId('c'), title })
         record(board, { cardId: null, type: 'column_added', source: actor, meta: { column: title } })
         await save(workspace, session)
@@ -684,7 +761,7 @@ export function apply(ctx) {
         const col = findColumn(board, str(a.id, ''))
         if (col && typeof a.title === 'string') {
           const before = col.title
-          col.title = a.title.slice(0, 40) || col.title
+          col.title = clampText(a.title, COLUMN_TITLE_LIMIT, 'List title', board) || col.title
           if (col.title !== before) {
             record(board, { cardId: null, type: 'column_renamed', source: actor, field: 'title', from: before, to: col.title, meta: { column: col.title } })
           }
@@ -726,7 +803,7 @@ export function apply(ctx) {
       }
 
       case 'addLabel': {
-        const name = str(a.name, '').slice(0, 20)
+        const name = clampText(a.name, LABEL_LIMIT, 'Label name', board)
         if (!name) return result({ error: 'Label name required' })
         if (findLabel(board, name)) return result({ error: 'Label already exists' })
         board.labels.push({ name, color: normColor(a.color) || '#94a3b8' })
@@ -739,7 +816,7 @@ export function apply(ctx) {
         const name = str(a.name, '')
         const label = findLabel(board, name)
         if (!label) return result({ error: 'Label not found' })
-        const newName = str(a.newName, '').slice(0, 20)
+        const newName = clampText(a.newName, LABEL_LIMIT, 'Label name', board)
         if (newName && newName !== name) {
           if (findLabel(board, newName)) return result({ error: 'Label name already exists' })
           label.name = newName
@@ -1033,7 +1110,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 +1132,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 +1164,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,16 +1183,32 @@ 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.',
       parameters: {
         type: 'object',
         properties: {
-          title: { type: 'string', description: 'Card title (task name, concise and actionable)' },
+          title: { type: 'string', description: `Card title (task name, concise and actionable; max ${TITLE_LIMIT} chars)` },
           columnId: { type: 'string', description: 'Target list id; defaults to the first list (Todo)' },
-          note: { type: 'string', description: 'Note: background, acceptance criteria or breakdown details (optional)' },
-          label: { type: 'string', description: 'Label name (optional): e.g. New Feature, bug, Feedback' },
+          note: { type: 'string', description: `Note: background, acceptance criteria or breakdown details (optional; max ${NOTE_LIMIT} chars)` },
+          label: { type: 'string', description: `Label name (optional; max ${LABEL_LIMIT} chars): e.g. New Feature, bug, Feedback` },
           priority: { type: 'string', enum: ['high', 'medium', 'low'], description: 'Priority (optional): high=P0 / medium=P1 / low=P2' },
         },
         required: ['title'],
@@ -1125,9 +1225,9 @@ export function apply(ctx) {
         type: 'object',
         properties: {
           id: { type: 'string', description: 'Card id' },
-          title: { type: 'string', description: 'New title (optional)' },
-          note: { type: 'string', description: 'New note (optional)' },
-          label: { type: 'string', description: 'New label name (optional); pass empty string to clear' },
+          title: { type: 'string', description: `New title (optional; max ${TITLE_LIMIT} chars)` },
+          note: { type: 'string', description: `New note (optional; max ${NOTE_LIMIT} chars)` },
+          label: { type: 'string', description: `New label name (optional; max ${LABEL_LIMIT} chars); pass empty string to clear` },
           priority: { type: 'string', enum: ['high', 'medium', 'low', ''], description: 'New priority (optional): high=P0 / medium=P1 / low=P2; pass empty string to clear' },
         },
         required: ['id'],
@@ -1172,7 +1272,7 @@ export function apply(ctx) {
       description: 'Add a list (column) to the board. Use when a new workflow stage (e.g. Review, Blocked) is needed.',
       parameters: {
         type: 'object',
-        properties: { title: { type: 'string', description: 'List name' } },
+        properties: { title: { type: 'string', description: `List name (max ${COLUMN_TITLE_LIMIT} chars)` } },
         required: ['title'],
       },
       output: output(renderBoard),
@@ -1187,7 +1287,7 @@ export function apply(ctx) {
         type: 'object',
         properties: {
           id: { type: 'string', description: 'List id' },
-          title: { type: 'string', description: 'New name' },
+          title: { type: 'string', description: `New name (max ${COLUMN_TITLE_LIMIT} chars)` },
         },
         required: ['id', 'title'],
       },
@@ -1231,7 +1331,7 @@ export function apply(ctx) {
       parameters: {
         type: 'object',
         properties: {
-          name: { type: 'string', description: 'Label name (unique, e.g. Urgent, Refactor)' },
+          name: { type: 'string', description: `Label name (unique, max ${LABEL_LIMIT} chars; e.g. Urgent, Refactor)` },
           color: { type: 'string', description: 'Label color (optional): #rrggbb hex; defaults to gray' },
         },
         required: ['name'],
@@ -1248,7 +1348,7 @@ export function apply(ctx) {
         type: 'object',
         properties: {
           name: { type: 'string', description: 'Current label name' },
-          newName: { type: 'string', description: 'New name (optional)' },
+          newName: { type: 'string', description: `New name (optional; max ${LABEL_LIMIT} chars)` },
           color: { type: 'string', description: 'New color (optional): #rrggbb hex' },
         },
         required: ['name'],