dsh-taskboard 0.3.3 → 0.4.0

package/src/host/templates.ts

@@ -0,0 +1,143 @@
+/**
+ * Host-side task-template store (0.4.0): one JSON side file next to the
+ * ledger, seeded with the built-in templates on first load, mutated through
+ * the same atomic persist discipline as the ledger.
+ *
+ * Pure data, no Cordis deps — the routes layer owns it and tests drive it
+ * directly against a temp dir.
+ *
+ * @module dsh-taskboard/host/templates
+ */
+import { readFile } from 'node:fs/promises'
+import type { TaskTemplate } from '../shared/api.ts'
+
+/** The built-in templates seeded when the side file does not exist yet. */
+export const BUILTIN_TEMPLATES: ReadonlyArray<{ id: string; name: string; task: TaskTemplate['task'] }> = [
+  {
+    id: 'tpl-bugfix',
+    name: 'Bug 修复',
+    task: {
+      title: '修复：',
+      prompt: [
+        '修复以下问题并按序交接：',
+        '1. 复现问题（写最小复现步骤或测试）',
+        '2. 定位根因，说明为什么会发生',
+        '3. 修复并补回归测试',
+        '4. 运行相关测试套件确认无回归',
+      ].join('\n'),
+      urgency: 'urgent',
+      checklist: ['已复现并定位根因', '修复已提交到任务分支', '回归测试通过'],
+    },
+  },
+  {
+    id: 'tpl-release',
+    name: '发布检查',
+    task: {
+      title: '发布：',
+      prompt: '执行发布流程：版本号更新、构建、测试、变更记录，完成后按序交接（不要实际推送/发布，等用户确认）。',
+      urgency: 'normal',
+      checklist: ['版本号已更新（package.json 与版本常量同步）', '构建通过', '全部测试通过', '变更记录已写'],
+    },
+  },
+  {
+    id: 'tpl-patrol',
+    name: '例行巡检',
+    task: {
+      title: '巡检：',
+      prompt: [
+        '例行巡检：检查依赖更新、失败测试、明显代码问题与未处理的告警。',
+        '发现的问题逐条列出（严重度/位置/建议），小问题直接修复，大问题只报告不动手。',
+        '输出巡检摘要（用 {{lastComments}} 可回看上次巡检结论）。',
+      ].join('\n'),
+      urgency: 'relaxed',
+      execution: { mode: 'scheduled', cron: '0 9 * * 1' },
+    },
+  },
+]
+
+/** Mint a template id. */
+function newTemplateId(): string {
+  return `tpl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * The template store. NOT thread-synchronized like the ledger (template
+ * writes are rare, human-paced GUI operations; last-write-wins is fine).
+ */
+export class TemplateStore {
+  private templates: TaskTemplate[] | undefined
+  private loaded = false
+
+  /** @param file - absolute side-file path (next to the ledger). */
+  constructor(private readonly file: string) {}
+
+  /** Load once; a missing file seeds the built-ins; a corrupt file resets. */
+  private async ensure(): Promise<void> {
+    if (this.loaded) return
+    let parsed: TaskTemplate[] | undefined
+    try {
+      const raw = await readFile(this.file, 'utf8')
+      const value = JSON.parse(raw) as { templates?: unknown }
+      if (Array.isArray(value.templates)) {
+        parsed = value.templates.filter((t): t is TaskTemplate =>
+          typeof t === 'object' && t !== null && typeof (t as TaskTemplate).id === 'string'
+          && typeof (t as TaskTemplate).name === 'string' && typeof (t as TaskTemplate).task === 'object')
+      }
+    } catch { /* missing or corrupt → seed */ }
+    if (parsed === undefined) {
+      const now = Date.now()
+      parsed = BUILTIN_TEMPLATES.map((t, i) => ({ ...t, task: { ...t.task }, builtin: true, createdAt: now, updatedAt: now + i }))
+      try { await this.persist(parsed) } catch { /* best effort — the seed returns in-memory */ }
+    }
+    this.templates = parsed
+    this.loaded = true
+  }
+
+  /** Atomic persist (temp + rename), same discipline as the ledger. */
+  private async persist(templates: TaskTemplate[]): Promise<void> {
+    const { mkdir, writeFile, rename } = await import('node:fs/promises')
+    const { dirname, join } = await import('node:path')
+    await mkdir(dirname(this.file), { recursive: true })
+    const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`)
+    await writeFile(temp, JSON.stringify({ templates }, null, 2), 'utf8')
+    await rename(temp, this.file)
+  }
+
+  /** All templates (oldest first). */
+  async list(): Promise<TaskTemplate[]> {
+    await this.ensure()
+    return (this.templates ?? []).slice()
+  }
+
+  /**
+   * Create or replace a template by id (a body without id creates).
+   * @returns the stored template.
+   */
+  async upsert(input: { id?: string; name: string; task: TaskTemplate['task'] }): Promise<TaskTemplate> {
+    await this.ensure()
+    const templates = this.templates ?? []
+    const name = input.name.trim()
+    if (name.length === 0 || name.length > 60) throw new Error('模板名必须 1..60 字符')
+    const now = Date.now()
+    const existing = input.id !== undefined ? templates.find(t => t.id === input.id) : undefined
+    const stored: TaskTemplate = existing !== undefined
+      ? { ...existing, name, task: input.task, updatedAt: now }
+      : { id: input.id ?? newTemplateId(), name, task: input.task, createdAt: now, updatedAt: now }
+    const index = existing !== undefined ? templates.indexOf(existing) : -1
+    if (index >= 0) templates[index] = stored
+    else templates.push(stored)
+    await this.persist(templates)
+    return stored
+  }
+
+  /** Delete a template by id; returns whether it existed. */
+  async remove(id: string): Promise<boolean> {
+    await this.ensure()
+    const templates = this.templates ?? []
+    const index = templates.findIndex(t => t.id === id)
+    if (index < 0) return false
+    templates.splice(index, 1)
+    await this.persist(templates)
+    return true
+  }
+}

package/src/host/tools.ts

@@ -1,5 +1,5 @@
 /**
- * The eight `taskboard_*` agent tools. All writes require a calling agent
+ * The ten `taskboard_*` agent tools. All writes require a calling agent
  * session (ownership audit), carry optimistic-version checks, and enforce
  * the protocol gates in CODE, not in prompt text:
  *
@@ -8,6 +8,8 @@
  *   match the task's project (claim boundary)
  * - taking over a task held by another session is rejected
  * - `delete` for agent callers only sets the soft-delete marker
+ * - checklist items may be added/checked by agents, but checking never
+ *   completes the task (done stays user-only)
  *
  * OUTPUT CONTRACT (lesson: registry `createSuccessResult` renders
  * `output.render(args, value)` into `result.content`, and the loop feeds
@@ -21,23 +23,28 @@
 import type { WorkspaceRegistry } from '@deepseek-ai/dsh-workspace'
 import { defineTool } from './sdk.ts'
 import {
+  MAX_CHECKLIST_ITEMS,
   asIsolation,
   asStatus,
   asUrgency,
   canTransition,
+  checklistFromTexts,
   effectivePrompt,
   isClaim,
   isClaimedBy,
+  newChecklistItemId,
   newCommentId,
   newTaskId,
   normalizeBody,
   normalizeExecution,
+  normalizeExecutionReport,
   normalizeModel,
   normalizePrompt,
   normalizeTitle,
   summarize,
   syncClaim,
   type Actor,
+  type ChecklistItem,
   type TaskModel,
   type TaskRecord,
 } from '../shared/protocol.ts'
@@ -55,6 +62,7 @@ function taskLine(t: {
   executionMode: string
   commentCount?: number
   lastExecutionOutcome?: string
+  checklist?: { done: number; total: number }
   trashed?: boolean
 }): string {
   const parts = [
@@ -64,6 +72,7 @@ function taskLine(t: {
   if (t.blocked) parts.push('·受阻')
   if (t.executionMode === 'scheduled') parts.push('·定时')
   if (t.commentCount !== undefined && t.commentCount > 0) parts.push(`·评论${t.commentCount}`)
+  if (t.checklist !== undefined && t.checklist.total > 0) parts.push(`·清单${t.checklist.done}/${t.checklist.total}`)
   if (t.lastExecutionOutcome !== undefined) parts.push(`·上次执行${t.lastExecutionOutcome}`)
   if (t.trashed === true) parts.push('·已删')
   return parts.join(' ')
@@ -84,6 +93,16 @@ function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
   if (t.presetId !== undefined) lines.push(`执行模式: ${t.presetId}（未指定时为部署默认 preset）`)
   lines.push(`描述: ${t.description.length > 0 ? t.description : '（无）'}`)
   lines.push(`执行 Prompt: ${t.effectivePrompt ?? effectivePrompt(t)}`)
+  if (t.checklist !== undefined && t.checklist.length > 0) {
+    const done = t.checklist.filter(i => i.checked).length
+    lines.push(`验收清单 (${done}/${t.checklist.length}):`)
+    for (const item of t.checklist) {
+      const mark = item.checked ? '☑' : '☐'
+      const who = item.checkedBy === undefined ? '' : item.checkedBy === 'user' ? ' ·用户勾选' : ` ·agent ${String(item.checkedBy).slice(0, 24)}勾选`
+      const note = item.note !== undefined ? ` ·证据: ${item.note}` : ''
+      lines.push(`  ${mark} ${item.text}${who}${note}`)
+    }
+  }
   if (t.comments.length > 0) {
     lines.push(`评论 (${t.comments.length}):`)
     for (const c of t.comments) {
@@ -98,7 +117,8 @@ function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
     for (const e of t.executions) {
       const at = e.startedAt !== undefined ? new Date(e.startedAt).toISOString() : '?'
       const err = e.error !== undefined ? ` 错误: ${e.error}` : ''
-      lines.push(`  - [${e.trigger} ${at}] ${e.outcome}${err}`)
+      const report = e.report !== undefined ? ' [已交报告]' : ''
+      lines.push(`  - [${e.trigger} ${at}] ${e.outcome}${report}${err}`)
     }
   } else {
     lines.push('执行记录: 无')
@@ -359,6 +379,11 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         type: 'string',
         description: 'Agent preset the execution session is composed from (its tool set / persona); default = the deployment default preset. Optional.',
       },
+      checklist: {
+        type: 'array',
+        description: `Acceptance checklist (DoD) item texts (≤${MAX_CHECKLIST_ITEMS} × 200 chars); agents check them off at handoff, the user reviews.`,
+        items: { type: 'string' },
+      },
     },
     output: {
       schema: JSON_OUT,
@@ -379,6 +404,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       model?: { provider?: string; model?: string }
       isolation?: string
       presetId?: string
+      checklist?: string[]
     }, exec: unknown) {
       try {
         const { actor } = caller(exec as ToolRunContext)
@@ -395,6 +421,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         const model = args.model !== undefined ? checkModel(deps, args.model) : undefined
         const isolation = args.isolation === undefined ? undefined : asIsolation(args.isolation)
         const presetId = args.presetId?.trim() || undefined
+        const checklist = args.checklist !== undefined ? checklistFromTexts(args.checklist) : undefined
         const now = deps.now()
         const task: TaskRecord = {
           id: newTaskId(),
@@ -409,6 +436,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           model,
           ...(isolation !== undefined ? { isolation } : {}),
           ...(presetId !== undefined ? { presetId } : {}),
+          ...(checklist !== undefined ? { checklist } : {}),
           version: 1,
           createdAt: now,
           updatedAt: now,
@@ -666,5 +694,173 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     },
   })) as () => void)
 
+  // -------------------------------------------------------------- checklist
+  disposers.push(register(defineTool({
+    name: 'taskboard_checklist',
+    description:
+      `Manage the task's acceptance checklist (DoD). Actions: "add" (append item texts, ≤10 per call), `
+      + '"check" (mark an item done, with an optional evidence note), "uncheck" (reopen an item). '
+      + 'Checking items NEVER completes the task — done stays a user-only action. Requires ifVersion.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Task id.' },
+      action: { type: 'string', required: true, description: 'add | check | uncheck.' },
+      ifVersion: { type: 'number', required: true, description: 'Task version you read; fails on mismatch.' },
+      items: {
+        type: 'array',
+        description: 'Item texts to append (action=add only; 1..10 per call, 200 chars each).',
+        items: { type: 'string' },
+      },
+      itemId: { type: 'string', description: 'The checklist item id (action=check/uncheck).' },
+      note: { type: 'string', description: 'Evidence note recorded with the check (≤400 chars).' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { task?: { id?: string; version?: number }; checklist?: Array<Record<string, unknown>>; done?: number; total?: number }
+        if (v.task === undefined || v.checklist === undefined) return [{ type: 'text', text: '清单操作失败。' }]
+        const lines = v.checklist.map((i, index) => `${i.checked === true ? '☑' : '☐'} [${index + 1}] ${String(i.text)}${i.note !== undefined ? `（证据: ${String(i.note)}）` : ''} id=${String(i.id)}`)
+        return [{
+          type: 'text',
+          text: `任务 ${v.task.id} 验收清单 ${v.done ?? 0}/${v.total ?? 0} 已完成，当前 v${v.task.version}：\n${lines.join('\n')}`,
+        }]
+      },
+    },
+    async execute(args: {
+      id: string
+      action: string
+      ifVersion: number
+      items?: string[]
+      itemId?: string
+      note?: string
+    }, exec: unknown) {
+      try {
+        const { actor } = caller(exec as ToolRunContext)
+        const task = store.get(args.id)
+        if (task === undefined || task.trashedAt !== undefined) throw new ToolError(ERR.notFound, `no task ${args.id}`)
+        versionGuard(task, args.ifVersion)
+        if (task.status === 'archived') throw new ToolError(ERR.invalidTransition, 'archived tasks are immutable')
+        const next: TaskRecord = structuredClone(task)
+        const checklist: ChecklistItem[] = next.checklist === undefined ? [] : [...next.checklist]
+
+        if (args.action === 'add') {
+          const texts = args.items ?? []
+          if (texts.length === 0 || texts.length > 10) {
+            throw new ToolError(ERR.invalidInput, 'items must carry 1..10 texts per add call')
+          }
+          if (checklist.length + texts.length > MAX_CHECKLIST_ITEMS) {
+            throw new ToolError(ERR.invalidInput, `checklist may hold at most ${MAX_CHECKLIST_ITEMS} items (currently ${checklist.length})`)
+          }
+          checklist.push(...checklistFromTexts(texts))
+        } else if (args.action === 'check') {
+          if (args.itemId === undefined) throw new ToolError(ERR.invalidInput, 'itemId is required for check')
+          const item = checklist.find(i => i.id === args.itemId)
+          if (item === undefined) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`)
+          const note = args.note !== undefined && args.note.trim().length > 0 ? args.note.trim().slice(0, 400) : undefined
+          item.checked = true
+          item.checkedBy = actor.sessionId
+          item.checkedAt = deps.now()
+          if (note !== undefined) item.note = note
+        } else if (args.action === 'uncheck') {
+          if (args.itemId === undefined) throw new ToolError(ERR.invalidInput, 'itemId is required for uncheck')
+          const item = checklist.find(i => i.id === args.itemId)
+          if (item === undefined) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`)
+          item.checked = false
+          delete item.checkedBy
+          delete item.checkedAt
+          delete item.note
+        } else {
+          throw new ToolError(ERR.invalidInput, `action must be add | check | uncheck (got "${args.action}")`)
+        }
+
+        if (checklist.length > 0) next.checklist = checklist
+        else delete next.checklist
+        next.version = task.version + 1
+        next.updatedAt = deps.now()
+        next.updatedBy = actor
+        await store.mutate('task-updated', ledger => {
+          const i = ledger.tasks.findIndex(t => t.id === args.id)
+          ledger.tasks[i] = next
+          return [next]
+        })
+        const progress = next.checklist !== undefined
+          ? { done: next.checklist.filter(i => i.checked).length, total: next.checklist.length }
+          : { done: 0, total: 0 }
+        return json({ task: { id: next.id, version: next.version }, checklist: next.checklist ?? [], ...progress })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
+  // ------------------------------------------------------- execution report
+  disposers.push(register(defineTool({
+    name: 'taskboard_execution_report',
+    description:
+      'Submit the structured execution report for the task you are currently executing (summary / changed '
+      + 'files / how you verified / artifacts / remaining risk). Submit BEFORE moving the task to in_review; '
+      + 'a later submission overwrites the previous report. Commits and diffs are host-collected — do not repeat them.',
+    parameters: {
+      summary: { type: 'string', required: true, description: 'What was done (1..2000 chars).' },
+      changedFiles: {
+        type: 'array',
+        description: 'Files you changed (paths, ≤50 × 300 chars).',
+        items: { type: 'string' },
+      },
+      checks: {
+        type: 'array',
+        description: 'How the work was verified (e.g. test commands + outcomes, ≤50 entries).',
+        items: { type: 'string' },
+      },
+      artifacts: {
+        type: 'array',
+        description: 'Artifacts worth reviewing (build outputs, screenshots, docs, ≤30 entries).',
+        items: { type: 'string' },
+      },
+      risk: { type: 'string', description: 'Known remaining risks or follow-ups (≤2000 chars, optional).' },
+    },
+    output: {
+      schema: JSON_OUT,
+      render: (_args, value) => {
+        const v = value as { taskId?: string; executionId?: string; report?: { summary?: string } }
+        if (v.taskId === undefined || v.report === undefined) return [{ type: 'text', text: '报告提交失败。' }]
+        return [{
+          type: 'text',
+          text: `执行报告已记录到任务 ${v.taskId}（执行 ${v.executionId}）：${v.report.summary?.slice(0, 120) ?? ''}\n`
+            + '接下来：taskboard_comment_add 留交接评论，然后 taskboard_move 移至待验收 in_review。',
+        }]
+      },
+    },
+    async execute(args: {
+      summary: string
+      changedFiles?: string[]
+      checks?: string[]
+      artifacts?: string[]
+      risk?: string
+    }, exec: unknown) {
+      try {
+        const { sessionId } = caller(exec as ToolRunContext)
+        const report = normalizeExecutionReport(args)
+        // Locate the RUNNING execution this session owns — reports attach to
+        // the live run, so the agent never needs to know execution ids.
+        let taskId: string | undefined
+        let executionId: string | undefined
+        await store.mutate('execution-recorded', ledger => {
+          for (const task of ledger.tasks) {
+            const execution = task.executions.find(e => e.sessionId === sessionId && e.outcome === 'running')
+            if (execution !== undefined) {
+              execution.report = report
+              taskId = task.id
+              executionId = execution.id
+              return [task]
+            }
+          }
+          return undefined
+        })
+        if (taskId === undefined || executionId === undefined) {
+          throw new ToolError(ERR.forbidden, 'no running execution belongs to this session — the report can only be submitted while the taskboard execution session is still running')
+        }
+        return json({ taskId, executionId, report })
+      } catch (error) { fail(error) }
+    },
+  })) as () => void)
+
   return disposers
 }

package/src/index.ts

@@ -26,11 +26,15 @@ import { registerTaskboardRoutes } from './host/routes.ts'
 import { SchedulerService } from './host/scheduler.ts'
 import { dshHomePath } from './host/sdk.ts'
 import { TaskStore } from './host/store.ts'
+import { TemplateStore } from './host/templates.ts'
 import { registerTaskboardTools, workspaceFace } from './host/tools.ts'
 
 /** Ledger file name under the DSH home. */
 export const LEDGER_FILE = 'dsh-taskboard.json'
 
+/** Task-template side file name under the DSH home (0.4.0). */
+export const TEMPLATES_FILE = 'dsh-taskboard-templates.json'
+
 /** Cordis plugin name. */
 export const name = 'dsh-taskboard'
 
@@ -43,6 +47,7 @@ export const inject = ['tools', 'systemPrompt']
  */
 export function apply(ctx: Context): void {
   const store = new TaskStore({ file: dshHomePath(LEDGER_FILE) })
+  const templates = new TemplateStore(dshHomePath(TEMPLATES_FILE))
   const now = () => Date.now()
   // Global execution concurrency cap (DSH_TASKBOARD_MAX_CONCURRENT overrides).
   const maxConcurrent = Math.max(1, Number.parseInt(process.env.DSH_TASKBOARD_MAX_CONCURRENT ?? '', 10) || DEFAULT_MAX_CONCURRENT)
@@ -153,6 +158,7 @@ export function apply(ctx: Context): void {
           cancel: (taskId: string) => execution.cancel(taskId),
           modelProviders,
           git,
+          templates,
         })
         return () => disposeRoutes?.()
       })

package/src/shared/api.ts

@@ -56,6 +56,8 @@ export type CreateTaskBody = {
   isolation?: string
   /** Agent preset for execution sessions; omitted = deployment default. */
   presetId?: string
+  /** Acceptance checklist item texts (host mints ids, all unchecked). */
+  checklist?: string[]
 }
 
 /** Update-task request body (ifVersion mandatory). */
@@ -74,6 +76,8 @@ export type UpdateTaskBody = {
   isolation?: string
   /** Change the execution preset (takes effect on the next run). */
   presetId?: string | null
+  /** Replace the whole checklist (GUI owner surface); null clears it. */
+  checklist?: unknown
 }
 
 /** Move-task request body (ifVersion mandatory; the user MAY move to done). */
@@ -119,6 +123,56 @@ export type DiagnosticsResponse = {
   gitIgnoreSuggestions: GitignoreSuggestion[]
 }
 
+/** Fields a task template may prefill (0.4.0). */
+export type TaskTemplateSpec = {
+  title?: string
+  description?: string
+  prompt?: string
+  urgency?: string
+  execution?: { mode?: string; cron?: string }
+  model?: { provider: string; model: string }
+  isolation?: string
+  presetId?: string
+  /** Checklist item texts (host mints ids at create time). */
+  checklist?: string[]
+}
+
+/** One reusable task template (0.4.0). */
+export type TaskTemplate = {
+  id: string
+  name: string
+  task: TaskTemplateSpec
+  /** Seeded built-in templates (kept on load, deletable like any other). */
+  builtin?: boolean
+  createdAt: number
+  updatedAt: number
+}
+
+/** Templates listing response. */
+export type TemplatesResponse = { templates: TaskTemplate[] }
+
+/** Import dry-run response (0.4.0): every task classified, nothing written. */
+export type ImportPreviewResponse = {
+  plan: {
+    create: Array<{ id: string; title: string; status: string }>
+    overwrite: Array<{ id: string; title: string; status: string }>
+    invalid: Array<{ id?: string; reason: string }>
+  }
+}
+
+/** Import commit response. */
+export type ImportCommitResponse = {
+  mode: 'merge' | 'replace'
+  created: number
+  overwritten: number
+  replacedTotal?: number
+  /** The backup file written BEFORE a replace wiped the live ledger. */
+  backupFile?: string
+}
+
+/** Diff-viewer response (0.4.0). */
+export type DiffResponse = { diff: string; truncated: boolean }
+
 /** One task (full record) response. */
 export type TaskResponse = TaskRecord