任务面板

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

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

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

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

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

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

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

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

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

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

快捷键：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）的完整字段：

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

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

典型用法：

• 「列出所有 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 个。