任务面板

「任务面板」是 Spark Work 内的全局看板（页面标题写的是「任务看板」）：按状态分列管理离散工单， 适合「需要多步处理、有验收标准、有执行 Agent」的工作项。任务可以直接派给 Agent 执行， Agent 完成后按约定回写状态。

1. 三个「新建任务」入口，别走错

界面上有三处名字很像的入口，行为完全不同：

入口	真实行为
左侧导航最上方的「新建任务」（带消息气泡图标）	不创建看板任务：清空当前会话进入一个全新对话。快捷键 Cmd/Ctrl+N 同效
快捷键 Cmd/Ctrl+B「快捷录入任务」	弹出全局任务快捷录入浮窗（浮窗标题也叫「新建任务」）：填正文、可粘贴图片、选项目 / 优先级 / 处理 Agent / 日期，按钮为「创建任务」和「创建并执行」
看板页右上角「新建任务」	进入整页创建表单（task-form-page，不是弹窗），字段最全

看板本身的入口是左侧导航里的「任务面板」（nav.board）。从任务卡片还可以 「立即执行」或右键「立即执行」，直接把它派给 Agent。

2. 状态列：6 个枚举，默认只显示 4 列

状态枚举是固定六项，列的固定顺序如下（这个顺序也是筛选下拉里的顺序）：

顺序	状态键	列名	颜色	默认可见
1	todo	📋 待办	灰#6b7280	是
2	in-progress	🔄 进行中	蓝#3b82f6	是
3	bug-fix	🐛 Bug 修复	红#ef4444	否
4	done	✅ 已完成	绿#10b981	是
5	accepted	🎯 已验收	紫#8b5cf6	否
6	closed	📦 已关闭	浅灰#9ca3af	是

默认可见列是todo / in-progress / done / closed四列——bug-fix与 accepted默认隐藏，所以在看板上「看不到 Bug 修复列」是正常的： 点工具栏的「面板」按钮，在弹出面板里勾选（或点「全选」）即可显示。选择结果存在 localStorage的board-visible-columns键下，下次打开自动恢复。

状态枚举不可自定义（不能加新列），但可以隐藏。列内卡片按sortOrder升序排列。

3. 创建任务：整页表单，项目和标题必填

创建 / 编辑都是整页视图（左侧有「返回看板」）。表单字段与真实约束：

字段	说明	必填
项目	决定任务派发时用哪个工作区（下拉来自工作区列表）	必填：未选项目时「创建任务」「立即执行」都是禁用状态
标题	一句话说清做什么	必填
描述	详细背景与上下文；在描述框里Ctrl/Cmd+V可直接粘贴图片成为附件	可选
附件	「上传图片/文件」可选多个文件；粘贴的图片走图片附件路径，可预览、可逐个移除	可选
状态	六个状态任选，默认todo	有默认值
优先级	low低 /medium中（默认）/high高 / urgent紧急	有默认值
负责人	下拉自 Agent 列表，可搜索、可清空（是给人看的归属字段）	可选
截止日期	日期选择器；过期且未完成时卡片上会标红	可选
处理 Agent	真正执行任务的 Agent；选项来自 Agent 列表 + 团队定义（团队显示为 [团队] 名称，值形如team:名称）	可选，但「立即执行」需要能解析出 Agent
测试 Agent	负责验收的 Agent，同样支持团队	可选
验收条件	完成的客观标准，会随任务一起写进派发提示词	可选
标签	逗号分隔的多个标签，卡片上最多显示 3 个（多出的显示+N）	可选

快捷键：Ctrl/Cmd+Enter提交，Esc返回看板。创建成功后卡片按 sortOrder落在对应列（新任务默认在同列末尾，步长 100）。

4. 派给 Agent：立即执行与自动执行

立即执行（表单顶部按钮，或卡片右键菜单）会做四件事：把任务状态改成 in-progress；用任务内容拼一段提示词（标题、描述、验收条件、处理 Agent、测试 Agent， 以及附件摘要，附件会作为会话附件一起发出）；创建一个标题为 [📋] <任务标题>的新会话并发起一轮对话；然后跳到对话视图。

派发提示词里明确要求 Agent 收尾时调用平台工具mcp__spark_platform__board_update 回写状态：全部完成写{ id, status: "done" }，遇到无法解决的问题写 { id, status: "bug-fix" }。

工具栏上的「自动执行」开关是另一套机制，规则如下：

• 最多并行2个todo任务；完成一个就补下一个。
• 每秒不轮询：以 1 分钟为兜底周期，另外订阅会话终态事件提前唤醒（唤醒前防抖 1.5 秒，留给 Agent 落最后一次状态回写）。
• 会话结束 8 秒后任务仍是in-progress，判定为「被中断」，自动重派。
• 会话持续运行超过45 分钟视为卡死：取消会话后重派。
• 同一个任务最多重派2次，之后不再重试，留在bug-fix 交给人处理。
• done/accepted/closed/bug-fix 都算「已完成」，自动执行不会再动它——包括尊重 Agent 自己给出的失败判定。
• 关闭开关只停止派发新任务与重启中断任务，已经在跑的会话任其跑完。

5. 拖拽改状态与排序

1. 按住卡片拖到目标列（拖拽时卡片会带半透明效果，落点有插入指示线）。
2. 松手后立即乐观更新界面，同时通过 IPC 持久化单个任务。
3. 拖到列内两张卡片之间 = 列内排序：新sortOrder取相邻两条的中点；拖到列的空白处 = 放到末尾。
4. 如果中点导致相邻间距小于 2，会自动把该列整列重排为0, 100, 200, …，避免精度耗尽。

不支持多选拖拽：进入选择模式后卡片不再可拖（选择模式只提供批量删除与导出）。 也没有「拖到 Bug 修复列时填写原因」这类弹窗。

6. 右键菜单与卡片上的操作

卡片右键只有四项：

• 打开详情：进入整页编辑视图。
• 立即执行：派给 Agent（同第 4 节）。
• 复制任务：按当前卡片内容新建一条，标题追加(副本)。
• 删除：软删除（弹确认框，说明「任务将移至回收站，可以恢复」）。

卡片正面还会显示：优先级徽标、标签数、项目名、描述、最多 2 张图片缩略图（多出的显示 +N）、文件数、负责人头像与名字、评论数、图片/文件数、截止日期（过期标红）、 状态色点。当状态是done时，卡片右下会出现🎯 验收按钮， 点一下直接把状态改成accepted——这是「已验收」列唯一的来源。

菜单里没有「永久删除」和「移动到…」；要永久删除请去回收站，要改状态请拖拽或改表单。

7. 评论与附件

评论字段为comments，每条包含 id / taskId / author / content / createdAt。 评论区只出现在编辑态（创建表单里没有）。可以新增、编辑、删除评论 （删除前有确认框），输入框提示「输入评论…（Ctrl+Enter 发送）」，作者为空时显示为「用户」。 评论正文是纯文本渲染：不解析 Markdown，也没有 @ 提及功能。

附件字段为attachments，每项含 id / type（image | file）/ name / path / previewPath?。 图片经主进程的粘贴 / 预处理通道落到看板附件目录，界面通过安全文件协议读取； 文件附件记录绝对路径。卡片正面只展示最多 2 张缩略图与数量（缩略图本身不弹预览，点卡片进入详情）；在创建 / 编辑页里点图片会打开预览浮层。

8. 回收站与永久删除

• 删除是软删除：写入deletedAt时间戳，卡片立刻从看板消失。
• 工具栏右侧的「回收站」按钮打开回收站面板，列出deletedAt 非空的全部任务，显示「删除于 <时间>」。
• 回收站里可以「恢复」（清空deletedAt）或「彻底删除」（确认后从存储中移除，并顺带清理该任务的附件文件）。
• 没有自动清理：不存在「30 天后自动删除」这类策略，也没有对应的设置项。回收站会一直保留到你自己处理。

9. 筛选、搜索与导入导出

• 搜索框：前端匹配标题、描述、负责人、项目、标签（子串、大小写不敏感）， 覆盖的范围比筛选下拉更广。
• 筛选下拉：只有三个维度——优先级、状态、项目（项目下拉来自工作区列表， 且会排除「不使用项目」）。条件生效时筛选按钮上会显示一个小圆点。
• 没有负责人筛选、标签筛选、排序方式切换；列内顺序固定按 sortOrder。
• 持久化范围：只有「显示哪些列」写进localStorage； 搜索词与筛选条件都是组件状态，切换视图或刷新后会重置。
• 导入导出：「导入导出」下拉里有「导入任务」「导出全部任务」「选择导出…」。 导出的是 JSON（含version、exportedAt与任务数组， 只导出未删除的任务，且不含评论与附件，默认文件名 tasks-YYYY-MM-DD.json）； 选择导出会进入选择模式，可「全选当前筛选结果」「导出选中」「删除选中」（批量软删）。 导入时选一个 JSON，校验结构后按状态批量建卡（未知状态会被计数并回落到待办）。

10. 数据存在哪、有哪些字段

持久化位置：任务不是存在 SQLite 里，而是主进程维护的本地 JSON 文件 ~/.spark-agent/board-tasks.json（附件在 ~/.spark-agent/board-attachments/）。 渲染层通过board:*IPC 通道读写，写入前会做自愈处理（清理指向不存在文件的附件）。 因为是单机单文件，任务面板没有多用户实时协作，也不会在多台设备间同步。

一条任务（BoardTask/TaskCard）的完整字段：

字段	类型	说明
id	string	任务 ID（新建时生成，Agent 回写状态要用它）
title	string	标题
description	string	描述
status	BoardTaskStatus	todo/in-progress/done/accepted /closed/bug-fix
priority	BoardTaskPriority	low/medium/high/urgent
assignee	string	负责人（人名或 Agent 名）
project	string	项目名（存储值经 ProjectSelect 归一）
tags	string[]	标签
dueDate	string	截止日期
processingAgent	string	处理 Agent（或team:名称）
acceptanceCriteria	string	验收条件
testAgent	string	测试 / 验收 Agent
comments	BoardComment[]	id / taskId / author / content / createdAt
attachments	BoardTaskAttachment[]	id / type / name / path / previewPath?
sortOrder	number	列内排序权重，步长 100
createdAt/updatedAt	string	ISO 时间戳
deletedAt	string | null	非空表示在回收站

11. 让 Agent 操作看板（真实工具名）

内置技能builtin:platform-manager提供 10 个看板工具，命名空间是 mcp__spark_platform__（注意工具名是board_*，不是 board_tasks_*）：

工具	关键参数
board_list	status/priority/assignee（模糊）/ project（精确）/query/includeDeleted（默认 false）
board_get	id
board_create	title（必填）+ 描述、状态、优先级、负责人、项目、标签、截止日期、处理 Agent、验收条件、测试 Agent、附件、sortOrder
board_update	id+ 要改的字段（附件是整体替换语义）
board_delete	id（软删除，进回收站）
board_batch_create/board_batch_update/ board_batch_delete	数组形式；批量更新每项包含id与要改的字段；批量删除传ids
board_restore	id（从回收站恢复）
board_permanent_delete	id（不可恢复；工具描述里要求先向用户确认）

典型用法：

• 「列出所有bug-fix状态的任务，按优先级排一下」
• 「把 backlog 里 P0 任务的截止日期推迟一周」（board_list+ board_batch_update）
• 「把这条任务标记成 done，并补一句验收条件」

注意：没有评论相关的平台工具（board_comment_*不存在）， Agent 只能改任务本体字段，评论要在界面上写。

12. 最佳实践

• 标题写动词短语：「实现 X」「修复登录报错」「跟进 Y 反馈」，便于搜索与扫读。
• 验收条件写客观可判定项：「CI 全绿 + 关键 e2e 通过」远好于「没问题」。它会随派发提示词一起给到 Agent。
• 项目字段别省：它决定任务派发到哪个工作区；没选项目连创建按钮都是禁用的。
• 一次执行一条主任务：自动执行最多并行 2 条，任务太小会让 Agent 频繁起会话，太大又会撞上 45 分钟的卡死判定。
• 失败任务留在bug-fix：自动执行会尊重这个判定、不再重派，适合放人工介入的队列。
• 定期清回收站：没有自动清理策略，长期不处理会一直占着 JSON 文件与附件目录。
• 用标签而不是把信息糊进标题：模块名 / 类型 / 紧急度都可以做标签，卡片上会显示前 3 个。

速查表

项目	内容
状态枚举	todo / in-progress / bug-fix / done / accepted / closed（列顺序同此）
默认可见列	todo / in-progress / done / closed（另两列需在「面板」里勾选）
列可见性存储	localStorage 键 board-visible-columns
优先级	low / medium（默认）/ high / urgent
持久化	~/.spark-agent/board-tasks.json（不是 SQLite）+ ~/.spark-agent/board-attachments/
必填字段	title 与 project（未选项目时创建按钮禁用）
任务字段	id / title / description / status / priority / assignee / project / tags / dueDate / processingAgent / acceptanceCriteria / testAgent / comments / attachments / sortOrder / createdAt / updatedAt / deletedAt
自动执行	并行上限 2；兜底轮询 1 分钟；45 分钟判卡死；最多重派 2 次
快捷录入	Cmd/Ctrl+B（浮窗，可「创建并执行」）
Agent 工具	mcp__spark_platform__board_list / get / create / update / delete / batch_create / batch_update / batch_delete / restore / permanent_delete
评论	只在编辑态可见；纯文本；Ctrl+Enter 发送；无 @ 提及
回收站	软删除（deletedAt）+ 手动恢复/彻底删除，无自动清理

上手清单：用任务面板跟踪一次功能上线

从建卡到派发、验收、归档

1. 左侧导航点「任务面板」进入看板
2. 点右上角「新建任务」，先选项目，再填标题、描述与验收条件
3. 选处理 Agent（可选测试 Agent），设置优先级与截止日期，需要时在描述框 Ctrl+V 粘贴图片
4. Ctrl/Cmd+Enter 保存，卡片落在 todo 列
5. 右键卡片「立即执行」（或打开「自动执行」开关让待办任务自动排队），任务转为 in-progress 并开始跑
6. 过程中在编辑页底部评论区同步进展、贴链接
7. Agent 把状态回写成 done 或 bug-fix；done 的卡片会出现 🎯 验收 按钮
8. 确认结果符合验收条件后点「验收」，任务进入已验收列；不再需要时拖到已关闭列归档
9. 误删的任务可在工具栏「回收站」里恢复或彻底删除

常见问题

为什么我看不到「Bug 修复」和「已验收」列？

这两列默认隐藏。默认可见列只有 todo / in-progress / done / closed 四列，点工具栏的「面板」按钮勾选 bug-fix 与 accepted（或点「全选」）就会显示，选择存在 localStorage 的 board-visible-columns 里。

侧栏的「新建任务」为什么没给我建看板任务？

侧栏「新建任务」（以及 Cmd/Ctrl+N）的行为是开一个全新对话，不是建任务。要建看板任务：用 Cmd/Ctrl+B 调出快捷录入浮窗，或到看板页点右上角「新建任务」打开完整表单。

能批量改状态吗？

看板界面上不能——选择模式只提供批量删除和导出，任务卡也不能多选拖拽。让 Agent 调 mcp__spark_platform__board_batch_update 可以按 id 数组批量改（每项包含 id 与要改的字段）。

回收站里的任务会自动清理吗？

不会。没有自动清理策略，也没有相关设置项；任务会一直留在回收站，直到你手动点「彻底删除」（会同时清理该任务的附件文件）。

任务面板支持多用户协作吗？

不支持。任务是单机存储的（~/.spark-agent/board-tasks.json），没有账号体系与实时同步，多台设备之间不共享。

「立即执行」之后任务会自己变成已完成吗？

不会自动完成。派发提示词要求 Agent 收尾时调用 mcp__spark_platform__board_update 把状态写成 done 或 bug-fix；自动执行开关只负责在会话中断 / 卡死时重派。done 之后还需要人在卡片上点 🎯 验收 才会进入已验收。