# dsh-taskflow 需求文档（PRD）

| | |
|---|---|
| 项目 | dsh-taskflow · AI 合同式任务看板 |
| 版本 | v0.3（实现收口稿） |
| 日期 | 2026-09-09 初稿 · 2026-09-15 收口 |
| 状态 | ✅ FR 全量收口 —— M1 真机复验过；M2 于 2026-09-15 收口（FR-12/13/14/15/16，FR-18 经裁决由任务级终检覆盖）；M3 于 2026-09-15 落地（FR-17 cron+webhook、FR-19 模板、FR-20 报表；file-watch 触发裁决不做）。待真机复验新批次 |
| 关联文档 | [`FUNCTIONS.md`](FUNCTIONS.md)（功能规格）、`../README.md`（项目简介） |

---

## 1. 背景与动机

### 1.1 DSH 执行语义层的现状

DeepSeek Harness 生态中，与「任务/目标」相关的既有能力各占一层：

| 能力 | 作用域 | 本质 | 缺什么 |
|---|---|---|---|
| `todo_write` | 单会话 | agent 自写自勾的临时清单 | 会话结束即过期，无验收语义 |
| `/goal` | 单会话 | 完成驱动循环：围绕一个不变目标自动续轮直到 complete/blocked | 无法跨会话、无组合视图、无人工验收门 |
| `dsh-schedule` | 单会话 | 会话事件日志上的 at/after/固定频率提醒 | 绑定会话生命周期，会话死了提醒就没了 |
| `dsh-task-board`（第三方） | 跨会话 | cron 作业发射器：到点把提示词发射进新会话 | 卡片是提示词字符串；无验收语义；状态列是展示位不是工作流；历史只有执行记录没有演进留痕 |

### 1.2 空缺层

上述能力之间缺了一层：**结构化的、跨会话存活的、可分解、可验收的工作对象**。用户对「任务看板」的直觉——我的事拆到什么程度了、哪些能跑、哪些卡住了、做出来的东西过没过验收——恰恰指向这一层，而现有任何单一能力都不提供。

### 1.3 现有 dsh-task-board 的评估结论（本项目动因）

对 `@linxin666/dsh-client-ui-task-board` 的中立评估得出三个结论，构成本项目的动因：

1. **名不副实**：五列看板是运行状态的展示位，不是工作流驱动器。无任务分解、无依赖、无优先级、无「agent 领卡改卡」语义。
2. **执行语义未超越 /goal**：一趟运行 = 投递一条提示词，所有差异化堆在「何时触发」这个运维维度；任务完成与否没有定义。
3. **完成不可信**：没有验收标准与完成证明的概念，跑完即结束，「done」没有含金量。

**结论：不修改现有插件，另起炉灶做一个真正符合看板直觉的新项目。**

---

## 2. 产品定位

### 2.1 一句话定位

> **人与 AI 之间的合同管理器**：AI 拆解、AI 实现、AI 举证；人来验收，通过才算 done，不通过打回继续迭代，全过程状态留痕。

### 2.2 核心理念（三条支点）

1. **验收标准让 done 可信** —— 卡片携带「怎么算做完」的可检验描述；完成不是 agent 自报，而是对照证据由人判定。
2. **AI 自主拆解与实现** —— 给目标（或不给，AI 自行判断），AI 负责任务到子任务的分解与逐个实现，人不在场也能推进。
3. **状态留痕** —— 每一次流转（拆解、开工、举证、验收、打回）都是一条带原因的不可变事件，看板可回放。

### 2.3 目标用户

- DSH（DeepSeek Harness）Web GUI 的个人用户（单用户本地部署，多人协作不在范围内）。
- 典型画像：希望把「一件的事」交给 AI 端到端完成，但**保留最终判断权**的人。

### 2.4 差异化声明（与最近竞品的边界）

- **对比 /goal**：goal 管单个会话内「怎么磨到完」，taskflow 管「一件事的结构、验收与全程留痕」。卡片运行时，会话内部照常可以用 goal——组合而非竞争。
- **对比 dsh-task-board**：不修改、不依赖、可共存。taskflow 的卡片是合同体（目标/验收/上下文钉脚/依赖），不是提示词容器；完成以「证据 + 人工判定」为准。

---

## 3. 核心用户旅程（主流程）

```
┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│ 创建任务 │ → │ AI 拆解 │ → │ 逐个实现 │ → │ 提交证明 │ → │ 人工验收 │
│ 验收可给 │   │ 成子任务 │   │ 各子任务 │   │ Evidence │   │ 通过/打回 │
│ 可不给   │   │         │   │         │   │         │   └────┬────┘
└─────────┘   └─────────┘   └─────────┘   └─────────┘        │
     ↑                                                  通过 ↓      ↓ 不通过
     │                                             ┌───────┐  回到「实现中」
     └───────────── 打回批语回流下一轮 ←────────────│ done  │  （迭代循环）
                                                   └───────┘
```

全程每一次状态变化都写入**事件历史**，任务详情页以时间线回放。

---

## 4. 用户故事

> 格式：US-xx｜作为\<角色\>，我想\<动作\>，以便\<价值\>。**验收要点**为该故事被认定完成的最小标准。

| 编号 | 用户故事 | 验收要点 | 优先级 |
|---|---|---|---|
| US-01 | 作为用户，我想快速创建一个任务，只写一句话描述也能开工 | 只填描述即可创建；验收标准留空时由 AI 在拆解阶段补全 | P0 |
| US-02 | 作为用户，我想在创建时可选给出完成目标/验收标准，约束 AI 的方向 | 给了就用我的，AI 不得擅自替换，只能细化 | P0 |
| US-03 | 作为用户，我想让 AI 自动把任务拆解成子任务（含依赖关系），拆完自动开工 | 拆解产物含子任务列表、各自建议验收、依赖关系；默认自动开始实现 | P0 |
| US-04 | 作为用户，我想在 AI 拆解后仍能查看和调整拆解结果（增删改子任务） | 拆解结果可视化呈现且可编辑；编辑后从编辑态继续执行 | P1 |
| US-05 | 作为用户，我想看到每个子任务的执行状态与所属会话，并能点进去围观 | 子任务卡可跳转到执行会话；会话运行中可实时打开 | P0 |
| US-06 | 作为用户，我想在子任务完成时收到「完成证明」，而不是一句「做完了」 | 证据至少含：变更摘要/diff、验证命令输出、对照验收标准的逐条自检 | P0 |
| US-07 | 作为用户，我想在验收页批准或打回；打回必须说明原因 | 批准一键完成；打回强制填写批语，批语回流为下一轮输入 | P0 |
| US-08 | 作为用户，被打回后我想让 AI 带着批语继续迭代，而不是从零开始 | 打回后子任务回到「实现中」，上下文（上轮证据/批语）注入下一轮 | P0 |
| US-09 | 作为用户，我想看到任务从创建到现在的完整状态时间线（谁、何时、从哪到哪、为什么） | 每次流转一条事件：时间、前后状态、操作者（人/AI/系统）、原因、关联引用 | P0 |
| US-10 | 作为用户，我想在看板上一眼看清所有任务的整体进展 | 多列看板、按状态分组、受阻标红、支持搜索与过滤 | P0 |
| US-11 | 作为用户，我想让有依赖的子任务自动排队：前序完成，后序自动就绪 | 依赖 DAG；前序 done 则后序 ready；前序打回则后序回退 | P1 |
| US-12 | 作为用户，我想限制同时运行的任务数，避免资源被打满 | WIP 上限可配；超出的就绪任务排队 | P1 |
| US-13 | 作为用户，我想对任务做归档、取消、搜索 | 归档只读可查；取消需二次确认；搜索覆盖标题/描述/子任务 | P1 |
| US-14 | 作为用户，界面要好看、跟手：跟随宿主深浅色主题，加载有骨架屏 | 零硬编码颜色、深浅色自动适配、加载/空态/错误态完整 | P0 |
| US-15 | 作为用户，我想在任务需要我验收时收到提醒，而不是反复刷页面 | 验收等待数角标 + 可选系统通知（浏览器通知/宿主事件） | P2 |

---

## 5. 功能需求清单（FR）

> 优先级：P0 = MVP 必须；P1 = 第二迭代；P2 = 增强。详细行为规格见 [`FUNCTIONS.md`](FUNCTIONS.md)。

| 编号 | 需求 | 说明 | 优先级 | 里程碑 | 状态（2026-09-15） |
|---|---|---|---|---|---|
| FR-01 | 任务创建 | 标题 + 描述；**验收标准可选**；上下文钉脚（工作区/预设/权限）可选，缺省用宿主默认 | P0 | M1 | ✅ |
| FR-02 | AI 合同补全 | 验收标准缺失时由 AI 生成建议稿；已给出时 AI 只能细化不能替换，差异可见 | P0 | M1 | ✅ |
| FR-03 | AI 任务拆解 | 独立拆解会话产出子任务列表（各自目标/建议验收/依赖）；拆解结果持久化为子任务卡 | P0 | M1 | ✅ |
| FR-04 | 自动执行 | 拆解完成后自动逐个实现就绪子任务（可配置关闭，改为人工放行） | P0 | M1 | ✅ |
| FR-05 | 执行引擎 | 每个子任务一个真实 DSH 会话；注入合同（目标+验收+上轮批语）；进度回写卡片 | P0 | M1 | ✅ |
| FR-06 | 完成证明 | agent 结束前必须提交 Evidence：变更摘要、验证输出、逐条自检；缺失则不得进入待验收 | P0 | M1 | ✅ |
| FR-07 | 人工验收门 | 审查页展示证据；批准 → done；打回 → 强制批语 → 回到实现中 | P0 | M1 | ✅ |
| FR-08 | 迭代循环 | 打回后携带批语与上轮证据重跑；迭代轮次计数；可设最大轮数 | P0 | M1 | ✅ |
| FR-09 | 状态历史 | 事件溯源：每次流转记录时间/前后状态/操作者/原因/引用；详情页时间线展示 | P0 | M1 | ✅ |
| FR-10 | 看板视图 | 多列看板（待办/进行中/待验收/已完成，受阻在列内标红）；搜索、过滤 | P0 | M1 | ✅ |
| FR-11 | 任务详情抽屉 | 合同全貌、子任务树、证据、时间线、会话链接五区布局 | P0 | M1 | ✅ |
| FR-12 | 依赖 DAG | 子任务/任务级依赖；前序 done 后序自动 ready；循环依赖拒绝 | P1 | M2 | ✅ 2026-09-15（守卫默认开；就绪判据=产物已存在 done/review；打回回退下游） |
| FR-13 | WIP 限制 | 并发运行上限，排队与队列可视化 | P1 | M2 | ✅ 2026-09-15（全局设置 1–8；提高即放行；等依赖/排队中 chip） |
| FR-14 | 批量验收 | review 列多选批准/打回 | P1 | M2 | ✅ 2026-09-15（批量操作模式：通过/打回（共用批语必填）/归档） |
| FR-15 | 归档/取消/搜索 | 归档只读；取消二次确认；全局搜索 | P1 | M2 | ✅（2026-09-12 归档单卡+批量；过滤器含已归档） |
| FR-16 | 通知 | 待验收角标；可选浏览器通知 | P2 | M2/M3 | ✅ 2026-09-15（角标 + 审批通知栏（超额）+ 浏览器通知 opt-in） |
| FR-17 | 触发器扩展 | cron / 文件变动 / webhook 触发建卡或放行 | P2 | M3 | ✅ 2026-09-15（cron 定时建卡 + token 门 webhook 建卡；file-watch 裁决不做：watcher 面与去抖复杂、单用户价值最弱，cron+webhook 已覆盖无人值守） |
| FR-18 | AI 预审 | 可选的第二会话对证据做独立复核，输出建议（不代替人判） | P2 | M3 | ⚖️ 2026-09-15 裁决关闭：任务级终检（2026-09-11）已实质覆盖——终检会话即「独立第二会话复核证据、产出对照建议」，人终批即最终判定；不重复实现 |
| FR-19 | 模板库 | 常用任务类型模板（含验收标准模板） | P2 | M3 | ✅ 2026-09-15（templates.json 播种 4 内置模板；创建抽屉 chip 预填/存为模板/两段式删除） |
| FR-20 | 报表 | 周期统计：吞吐、一次通过率、平均迭代轮次 | P2 | M3 | ✅ 2026-09-15（统计浮层：7/30 天吞吐、一次通过率、平均轮次、拆解采纳率，口径注脚同屏） |

---

## 6. 非功能需求（NFR）

| 编号 | 类别 | 需求 |
|---|---|---|
| NFR-01 | 外观 | **好看是硬性需求**：跟随宿主主题变量（深浅色自动适配），禁止硬编码颜色；克制的动效；骨架屏/空态/错误态三态完整；参考 skill-hub 0.3.11 的主题接入标准 |
| NFR-02 | 无障碍 | 全控件 `:focus-visible`；`role`/`aria-*` 齐全；尊重系统「减少动效」；点击区域 ≥ 24px |
| NFR-03 | 可靠性 | Host 权威数据（浏览器只是异步视图，关页面不影响执行）；ledger 原子写（临时文件+rename）；重启后确定性恢复（运行中的可观察接管，未启动的取消不重发） |
| NFR-04 | 一致性 | 变更返回全量带修订号快照；SSE 推送增量；重连/页面回前台拉全量 |
| NFR-05 | 性能 | ledger 有界（执行记录按任务截断保留）；百级任务、千级事件下详情抽屉打开 < 300ms；不因扫描阻塞宿主 |
| NFR-06 | 安全 | 权限确认门：执行权限高于会话默认（默认 read-only）必须人事先确认；action 白名单（无命令/可执行路径/shell 文本字段）；跨会话文本注入（批语/拆解结果）带来源声明包装；同源访问限制 |
| NFR-07 | 兼容 | dsh `0.1.2-rc.1+`；纯插件挂载，不改宿主源码；与 dsh-task-board 数据目录完全分离（`$DSH_HOME/taskflow/`）可共存 |
| NFR-08 | 可维护 | TypeScript；分层（protocol/host/client）清晰；核心逻辑测试覆盖；`typecheck`/`test`/`build` 三门禁全绿方可发布 |
| NFR-09 | 数据安全 | ledger 文件 0600；损坏文件移入 `.corrupt-*` 保留原始字节，不静默清空 |

---

## 7. 范围外（明确不做）

1. ❌ 通用项目管理：epic、迭代、燃尽图、多人协作、权限角色。
2. ❌ 提示词编排 / 多 agent 编导：属于 dsh workflow 工具的领域。
3. ❌ 修改 dsh 宿主源码或修改现有 dsh-task-board 插件。
4. ❌ 移动端专门适配（跟随宿主响应式即可，不做独立布局）。
5. ❌ 云端同步 / 多机分布式 ledger（单机单 Host）。

---

## 8. 里程碑

| 里程碑 | 内容 | 出口标准（验收清单） |
|---|---|---|
| **M0 文档** | 本 PRD + 功能文档，评审定稿 | 两文档评审通过 |
| **M1 MVP 核心闭环** | FR-01～11：创建（含 AI 补全）→ 拆解 → 实现 → 举证 → 验收/打回 → 时间线；单任务无依赖；看板基础版 | 主流程端到端可跑通：一个真实任务从一句话到 done（含一次打回迭代）；typecheck/test/build 全绿 |
| **M2 组合与效率** | FR-12～16：依赖 DAG、WIP、批量验收、归档/搜索、通知 | 多子任务依赖任务可自动推进；并发受限下排队正确 |
| **M3 触发与增强** | FR-17～20：cron/file/webhook 触发、AI 预审、模板、报表 | 无人值守场景（定时建卡→自动推进→等验收）可稳定运行 |

---

## 9. 成功指标

| 指标 | 定义 | 目标 |
|---|---|---|
| 拆解采纳率 | AI 拆解结果未经人工修改即执行的占比 | ≥ 70% |
| 一次验收通过率 | 子任务首轮证据直接被批准的占比 | ≥ 50% |
| 迭代收敛轮次 | 打回后到批准的平均轮次 | ≤ 2 |
| 证据完整率 | 进入 review 的卡证据三要素齐全的占比 | 100%（Host 强制） |
| 主观可用性 | 用户自评「比直接跟 AI 对话省心」 | 创建任务 30 秒内完成 |

---

## 10. 风险与开放问题

| # | 风险/问题 | 影响 | 缓解 |
|---|---|---|---|
| R1 | AI 拆解质量不稳定，拆得过粗/过细 | 执行混乱、验收困难 | 验收标准逐子任务强制；拆解结果可视化可编辑（US-04）；迭代轮数上限兜底 |
| R2 | 既当运动员又当裁判：证据由执行会话自产 | 自检流于形式 | 证据三要素强制 + 结构化对照；M3 引入独立 AI 预审；最终判定权始终在人 |
| R3 | Token 成本：拆解 + 多子任务多轮迭代 | 用量上升 | 迭代轮数上限；子任务会话复用策略；成本展示（会话 token 统计关联） |
| R4 | 与 dsh-task-board 共存时的用户困惑 | 概念混淆 | 文档与命名明确区隔；数据目录分离；不共享任何状态 |
| R5 | dsh 版本演进破坏 SDK 契约 | 升级失效 | peer 范围声明 + compatibility 清单（沿社区插件惯例） |
| Q1 | 拆解结果是否需要人工确认后才开工？ | 流程分叉 | 默认自动开工（用户明确要求）；提供「拆解后暂停」配置项 |
| Q2 | npm 包名 / 仓库最终命名 | 发布 | 暂定 `dsh-taskflow`，发布前查重后锁定 |
| Q3 | 证据中的 diff 是否内嵌展示 | UI 复杂度 | M1 用外链 + 摘要；M2 评估内嵌渲染 |

---

## 11. 术语表

| 术语 | 定义 |
|---|---|
| 合同（Contract） | 卡片的三个核心部分：目标（objective）、验收标准（acceptance）、上下文钉脚（context pins） |
| 验收标准（Acceptance） | 可检验的「怎么算做完」描述列表；缺失时由 AI 补全建议稿 |
| 子任务（Subtask） | 拆解会话产出的独立可执行工作单元，可带依赖 |
| 证据（Evidence） | 子任务完成时提交的证明包：变更摘要 + 验证输出 + 逐条自检 |
| 验收（Review） | 人对证据的判定：批准（→done）或打回（→实现中，附批语） |
| 打回（Reject） | 验收不通过；批语为下一轮执行的强制输入 |
| 事件（Event） | 不可变的状态流转记录，事件历史的原子单位 |
| 看板（Board） | 按状态分组展示全部任务的实时视图 |
| 钉脚（Pins） | 执行时强制应用的三元组：工作区 / Agent 预设 / 权限 |