@alpacachen/dsh-kanban 1.8.0 → 1.9.0
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.
- package/README.md +2 -0
- package/README.zh.md +2 -0
- package/index.js +25 -8
- package/lib/client.js +23 -15
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -126,6 +126,8 @@ For `kanban_add_card` and `kanban_update_card`, the task description uses the ex
|
|
|
126
126
|
|
|
127
127
|
For due dates, `kanban_add_card` and `kanban_update_card` accept `dueDate` as a real calendar date in `YYYY-MM-DD` format. Omit it to keep the current date (new cards default to none); use `null` or an empty string to clear it. Dates have no time or timezone: a task due today becomes overdue the next local calendar day. Resolve phrases such as “this Friday” against the user's local date and confirm the concrete date instead of sending relative text or a UTC timestamp. Both `kanban_get` and `kanban_get_card` return the date and the board's `completedColumnId`.
|
|
128
128
|
|
|
129
|
+
Completion dates are recorded automatically when a card enters the configured completion list (including creation there). Reopening clears the date; completing again records a new timestamp. Edits, comments, same-list sorting, and column renames/reordering preserve it. Card details show the local completion time next to the due date; it is read-only. Both read tools return `completedAt` as a UTC ISO timestamp, or `null`. A completed card with `null` has an unknown completion time. Changing or clearing the completion list resets completion dates; existing cards in the newly selected list have unknown dates. Deleting a list applies the same completion rules to its automatic card moves. Schema v5 migration backs up the original file and leaves historical completion times unknown rather than guessing from truncated, title-based activity history.
|
|
130
|
+
|
|
129
131
|
Use `kanban_set_completed_column` with an existing `columnId` to designate the finished stage, or `null` to clear it. New boards use their default Done column; existing boards need an explicit choice. Completion follows the column ID through renames and reordering, and deleting that column clears the setting. Cards in the completion column keep their dates but are excluded from **Due today** and **Overdue** filters; moving them out resumes date checks. There are no automatic reminders or date-based reordering.
|
|
130
132
|
|
|
131
133
|
> Set the payment integration task's due date to this Friday, then show me unfinished tasks that are due today or overdue so I can decide what to tackle first.
|
package/README.zh.md
CHANGED
|
@@ -124,6 +124,8 @@ dsh --profile web --dump-config
|
|
|
124
124
|
|
|
125
125
|
`kanban_add_card` 和 `kanban_update_card` 的任务描述仍使用 `note` 字段,传入保留换行的 Markdown 原文,不传 HTML。任务详情会渲染标题、列表、表格和代码块。原文最多 2,000 字符,Markdown 标记和换行也计入长度,超出会截断并返回警告。修改已有描述前,应先调用 `kanban_get_card` 读取完整原文(`kanban_get` 只返回摘要)。传入 `note` 会替换整段描述;省略则保留原文,传空字符串则清空。评论仍为纯文本。
|
|
126
126
|
|
|
127
|
+
完成日期在卡片进入完成列时自动记录(包括直接在完成列创建),移出时清空,再次完成时记录新时间。修改内容、评论、同列排序和列改名/排序不影响完成日期。卡片详情在截止日期旁以本地时区只读展示;两个读取工具均返回 UTC ISO 时间戳 `completedAt` 或 `null`,已完成卡片的 `null` 表示时间未知。更换或清除完成列会重置完成时间,新完成列中已有卡片显示未知;删除列引发自动移动时也遵循进入/离开完成状态的规则。升级至数据格式 v5 时会备份原文件,历史完成时间保留未知,不依据可能被截断、按列名记录的活动日志推测。
|
|
128
|
+
|
|
127
129
|
`kanban_add_card` 和 `kanban_update_card` 可通过 `dueDate` 设置截止日期,值为真实有效的 `YYYY-MM-DD` 日期。省略则保留原日期(新卡片默认为无日期),传 `null` 或空字符串则清空。日期不含时间和时区:今天到期的任务到本地次日才算逾期。「本周五」等相对日期应由 Agent 按用户本地日期换算,并向用户确认具体日期,不要直接传相对文本或 UTC 时间戳。`kanban_get` 和 `kanban_get_card` 都会返回截止日期与看板的 `completedColumnId`。
|
|
128
130
|
|
|
129
131
|
使用 `kanban_set_completed_column`,传已有的 `columnId` 指定完成列,传 `null` 清除设置。新看板默认使用 Done,已有看板需要明确选择一次。设置跟随列 ID,改名和排序不影响;删除完成列会清除设置。完成列中的卡片保留日期,但不计入「今天到期」和「已逾期」筛选,移回其他列后恢复判断。暂不包含自动提醒和按日期自动排序。
|
package/index.js
CHANGED
|
@@ -11,11 +11,11 @@
|
|
|
11
11
|
* - Browser API: ctx.get('connection') registers the authenticated /api/kanban route.
|
|
12
12
|
*
|
|
13
13
|
* Per-workspace data model (disk files include schemaVersion):
|
|
14
|
-
* schemaVersion:
|
|
14
|
+
* schemaVersion: 5
|
|
15
15
|
* completedColumnId: string | null
|
|
16
16
|
* columns: [{ id, title }]
|
|
17
17
|
* labels: [{ name, color }] // name is the unique key and binds the color
|
|
18
|
-
* cards: [{ id, columnId, title, note, label, priority, dueDate, createdAt, createdBy,
|
|
18
|
+
* cards: [{ id, columnId, title, note, label, priority, dueDate, completedAt, createdAt, createdBy,
|
|
19
19
|
* comments: [{ id, content, source, createdAt }] }]
|
|
20
20
|
* activities: [{ id, ts, cardId, type, source, field?, from?, to?, meta? }] // append-only log
|
|
21
21
|
*
|
|
@@ -46,7 +46,7 @@ export const inject = ['tools']
|
|
|
46
46
|
// Back up old files before following the migration chain on first access.
|
|
47
47
|
// ---------------------------------------------------------------------------
|
|
48
48
|
|
|
49
|
-
export const SCHEMA_VERSION =
|
|
49
|
+
export const SCHEMA_VERSION = 5
|
|
50
50
|
export const LEGACY_VERSION = 0
|
|
51
51
|
|
|
52
52
|
// Append-only activity log persisted with the board; drop oldest events above the limit.
|
|
@@ -145,6 +145,12 @@ export const MIGRATIONS = {
|
|
|
145
145
|
completedColumnId: null,
|
|
146
146
|
cards: Array.isArray(data.cards) ? data.cards.map((card) => isObj(card) ? { ...card, dueDate: null } : card) : data.cards,
|
|
147
147
|
}),
|
|
148
|
+
4: (data) => ({
|
|
149
|
+
...data,
|
|
150
|
+
schemaVersion: 5,
|
|
151
|
+
// Truncated, title-based activity history cannot reliably recover completion times.
|
|
152
|
+
cards: Array.isArray(data.cards) ? data.cards.map((card) => isObj(card) ? { ...card, completedAt: null } : card) : data.cards,
|
|
153
|
+
}),
|
|
148
154
|
}
|
|
149
155
|
|
|
150
156
|
/**
|
|
@@ -235,6 +241,8 @@ export function validateBoard(data) {
|
|
|
235
241
|
if (!columnIds.has(c.columnId)) errors.push('card references missing column: ' + c.id)
|
|
236
242
|
if (c.label != null && !labelNames.has(c.label)) errors.push('card references missing label: ' + c.id)
|
|
237
243
|
if (c.dueDate !== null && !isDueDate(c.dueDate)) errors.push('card has invalid due date: ' + c.id)
|
|
244
|
+
if (c.completedAt !== null && (typeof c.completedAt !== 'string' || !Number.isFinite(Date.parse(c.completedAt)) || new Date(c.completedAt).toISOString() !== c.completedAt)) errors.push('card has invalid completion time: ' + c.id)
|
|
245
|
+
if (c.completedAt !== null && c.columnId !== data.completedColumnId) errors.push('incomplete card has a completion time: ' + c.id)
|
|
238
246
|
if (c.priority != null && !['high', 'medium', 'low'].includes(c.priority)) errors.push('card has invalid priority: ' + c.id)
|
|
239
247
|
for (const comment of c.comments) {
|
|
240
248
|
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) {
|
|
@@ -595,6 +603,7 @@ export function apply(ctx) {
|
|
|
595
603
|
label: c.label ?? null,
|
|
596
604
|
priority: c.priority ?? null,
|
|
597
605
|
dueDate: c.dueDate,
|
|
606
|
+
completedAt: c.completedAt,
|
|
598
607
|
createdAt: typeof c.createdAt === 'string' ? c.createdAt : null,
|
|
599
608
|
createdBy: typeof c.createdBy === 'string' ? c.createdBy : null,
|
|
600
609
|
comments: Array.isArray(c.comments)
|
|
@@ -623,6 +632,7 @@ export function apply(ctx) {
|
|
|
623
632
|
label: c.label ?? null,
|
|
624
633
|
priority: c.priority ?? null,
|
|
625
634
|
dueDate: c.dueDate,
|
|
635
|
+
completedAt: c.completedAt,
|
|
626
636
|
commentCount: c.comments.length,
|
|
627
637
|
})),
|
|
628
638
|
})
|
|
@@ -680,6 +690,7 @@ export function apply(ctx) {
|
|
|
680
690
|
createdBy: actor,
|
|
681
691
|
comments: [],
|
|
682
692
|
}
|
|
693
|
+
card.completedAt = col.id === board.completedColumnId ? card.createdAt : null
|
|
683
694
|
board.cards.push(card)
|
|
684
695
|
record(board, {
|
|
685
696
|
cardId: card.id,
|
|
@@ -778,7 +789,9 @@ export function apply(ctx) {
|
|
|
778
789
|
if (!card || !target) return result({ error: 'Card or list not found' })
|
|
779
790
|
const fromCol = findColumn(board, card.columnId)
|
|
780
791
|
const fromTitle = fromCol ? fromCol.title : String(card.columnId)
|
|
792
|
+
const changedColumn = card.columnId !== target.id
|
|
781
793
|
board.cards = board.cards.filter((c) => c.id !== card.id)
|
|
794
|
+
if (changedColumn) card.completedAt = target.id === board.completedColumnId ? new Date().toISOString() : null
|
|
782
795
|
card.columnId = target.id
|
|
783
796
|
const inCol = board.cards.filter((c) => c.columnId === target.id)
|
|
784
797
|
const toIndex = typeof a.toIndex === 'number' && Number.isFinite(a.toIndex)
|
|
@@ -787,7 +800,7 @@ export function apply(ctx) {
|
|
|
787
800
|
const anchor = inCol[toIndex]
|
|
788
801
|
if (anchor) board.cards.splice(board.cards.indexOf(anchor), 0, card)
|
|
789
802
|
else board.cards.push(card)
|
|
790
|
-
if (
|
|
803
|
+
if (changedColumn) {
|
|
791
804
|
record(board, { cardId: card.id, type: 'card_moved', source: actor, field: 'columnId', from: fromTitle, to: target.title, meta: { title: card.title } })
|
|
792
805
|
}
|
|
793
806
|
await save(workspace, session)
|
|
@@ -820,6 +833,8 @@ export function apply(ctx) {
|
|
|
820
833
|
const previousId = board.completedColumnId
|
|
821
834
|
if (previousId !== a.columnId) {
|
|
822
835
|
board.completedColumnId = a.columnId
|
|
836
|
+
// Changing the definition of done does not establish when existing cards finished.
|
|
837
|
+
for (const card of board.cards) card.completedAt = null
|
|
823
838
|
record(board, { cardId: null, type: 'board_completed_column_changed', source: actor, field: 'completedColumnId', from: previousId, to: a.columnId, meta: { fromColumn: findColumn(board, previousId)?.title ?? null, toColumn: findColumn(board, a.columnId)?.title ?? null } })
|
|
824
839
|
await save(workspace, session)
|
|
825
840
|
}
|
|
@@ -841,6 +856,7 @@ export function apply(ctx) {
|
|
|
841
856
|
for (const card of board.cards) {
|
|
842
857
|
if (card.columnId === id) {
|
|
843
858
|
card.columnId = fallback
|
|
859
|
+
card.completedAt = fallback === board.completedColumnId ? new Date().toISOString() : null
|
|
844
860
|
record(board, { cardId: card.id, type: 'card_moved', source: actor, field: 'columnId', from: deleted.title, to: board.columns[0].title, meta: { title: card.title } })
|
|
845
861
|
}
|
|
846
862
|
}
|
|
@@ -1142,7 +1158,7 @@ export function apply(ctx) {
|
|
|
1142
1158
|
(card.label ? '[' + card.label + '] ' : '') +
|
|
1143
1159
|
card.title +
|
|
1144
1160
|
(card.dueDate ? ' (due ' + card.dueDate + ')' : '') +
|
|
1145
|
-
(card.columnId === b.completedColumnId ? ' [completed]' : '') +
|
|
1161
|
+
(card.columnId === b.completedColumnId ? ' [completed; completedAt: ' + (card.completedAt || 'unknown') + ']' : '') +
|
|
1146
1162
|
(card.commentCount ? ' (' + card.commentCount + ' comments)' : ''),
|
|
1147
1163
|
)
|
|
1148
1164
|
}
|
|
@@ -1155,7 +1171,7 @@ export function apply(ctx) {
|
|
|
1155
1171
|
const tools = [
|
|
1156
1172
|
{
|
|
1157
1173
|
name: 'kanban_get',
|
|
1158
|
-
description: 'Read the current state of the current project (workspace) kanban board (all lists, labels, cards with dueDate, and completedColumnId). Due dates are local calendar dates, not UTC timestamps; a date becomes overdue the following day. Cards in completedColumnId are finished and excluded from due-today/overdue checks. Resolve relative dates using the user local date and confirm the concrete YYYY-MM-DD date. Call it before planning to understand existing content and avoid duplicate cards.',
|
|
1174
|
+
description: 'Read the current state of the current project (workspace) kanban board (all lists, labels, cards with dueDate and completedAt, and completedColumnId). Due dates are local calendar dates, not UTC timestamps; a date becomes overdue the following day. Cards in completedColumnId are finished and excluded from due-today/overdue checks. completedAt is the latest completion UTC timestamp; null on a completed card means unknown. Resolve relative dates using the user local date and confirm the concrete YYYY-MM-DD date. Call it before planning to understand existing content and avoid duplicate cards.',
|
|
1159
1175
|
parameters: { type: 'object', properties: {} },
|
|
1160
1176
|
output: output(renderBoard),
|
|
1161
1177
|
async execute(args, exec) {
|
|
@@ -1164,7 +1180,7 @@ export function apply(ctx) {
|
|
|
1164
1180
|
},
|
|
1165
1181
|
{
|
|
1166
1182
|
name: 'kanban_get_card',
|
|
1167
|
-
description: "Read one card's full details (title, raw Markdown description in note, label, priority, dueDate and comments), plus the board completion column ID from the current project (workspace) board by card id. Use kanban_get first to discover card ids; its summary omits note. Read this tool before editing an existing description to preserve its content and Markdown formatting.",
|
|
1183
|
+
description: "Read one card's full details (title, raw Markdown description in note, label, priority, dueDate, completedAt and comments), plus the board completion column ID from the current project (workspace) board by card id. completedAt is a system-managed UTC timestamp, cleared on reopening; null on a completed card means unknown. Use kanban_get first to discover card ids; its summary omits note. Read this tool before editing an existing description to preserve its content and Markdown formatting.",
|
|
1168
1184
|
parameters: {
|
|
1169
1185
|
type: 'object',
|
|
1170
1186
|
properties: {
|
|
@@ -1198,6 +1214,7 @@ export function apply(ctx) {
|
|
|
1198
1214
|
if (c.label) lines.push('Label: ' + c.label)
|
|
1199
1215
|
if (c.dueDate) lines.push('Due date: ' + c.dueDate + ' (local calendar date)')
|
|
1200
1216
|
lines.push('Completed: ' + (c.columnId === value.completedColumnId ? 'yes' : 'no'))
|
|
1217
|
+
if (c.columnId === value.completedColumnId) lines.push('Completed at: ' + (c.completedAt || 'unknown'))
|
|
1201
1218
|
if (c.note) lines.push('Note: ' + c.note)
|
|
1202
1219
|
if (Array.isArray(c.comments) && c.comments.length > 0) {
|
|
1203
1220
|
lines.push('Comments:')
|
|
@@ -1335,7 +1352,7 @@ export function apply(ctx) {
|
|
|
1335
1352
|
},
|
|
1336
1353
|
{
|
|
1337
1354
|
name: 'kanban_set_completed_column',
|
|
1338
|
-
description: 'Choose the one list that means completed for this board by its stable column id, or clear the setting with null. Cards in this list are excluded from due-today and overdue checks. Existing boards require an explicit choice; never infer completion from a list name or position. New boards default to Done.',
|
|
1355
|
+
description: 'Choose the one list that means completed for this board by its stable column id, or clear the setting with null. Cards in this list are excluded from due-today and overdue checks. Existing boards require an explicit choice; never infer completion from a list name or position. New boards default to Done. Changing this setting clears completion timestamps; cards already in the new completion list have unknown completion times.',
|
|
1339
1356
|
parameters: {
|
|
1340
1357
|
type: 'object',
|
|
1341
1358
|
properties: { columnId: { oneOf: [{ type: 'string' }, { type: 'null' }], description: 'Existing list id from kanban_get, or null to clear the completion column' } },
|