前言¶
在 DeepSeek Harness（DSH）里做多会话协作时，常见两类问题：开发自测通过就被当成「做完」，缺少独立验收；派单、进度、卡点分散在各会话里，隔一天很难接上。dsh-flow 把「一条活怎么走完」收成一套工具：任务卡是文档正本，状态写在 YAML 头里，派单与投递由插件工具驱动，人和会话按卡推进即可。它与剧场插件 dsh-theater 无关，零依赖，不 import 核心包。
这是什么¶
dsh-flow 是维护者 KarBurKi 发布的 DSH 工作流类插件（社区目录：karburki/dsh-flow，源码：GitHub）。定位是跨会话流程编排：四个角色——统筹、预研、开发、测试——配合完成派单、实现、独立验收、需求比对、终审把关与归档，再回到起点处理下一条任务。
闭环路径可概括为：预研 → 统筹（建卡/拆解）→ 开发（做）与测试（验）→ 统筹（需求比对、终审；不过则再走开发）→ 统筹（汇总/归档）→ 下一轮。五个关键节点是派单、认领、回执、独立验收、终审；少一步就不算闭环。
角色与分工¶
| 角色 | 做什么 | 不做什么 |
|---|---|---|
| 统筹 | 拆解、建卡、派单、派验收、需求比对、终审、汇总、归档 | 不亲自实现；不替他人拍板 |
| 预研 | 提需求、预研说明、选型 | 不直接改实现 |
| 开发 | 认领、实现、自测、push、回执 | 不自验——自测通过不等于验收通过 |
| 测试 | 独立验收、出报告、报边界 | 不改开发代码；不接边改边验 |
插件强调三条不变量：卡是正本（状态与结论在卡上）；开发不自验；关闭任务需有通过的验收。更完整的八拍时序、状态转移与换平台映射见仓库内 docs/流程原理.md。
核心功能¶
状态机¶
当前 README 标注的状态机版本为 0.3.0，主路径如下：
pending → processing → blocked → waiting_verify → waiting_final → done
pending：等统筹flow_dispatch派单。processing：开发在手；可flow_submit交验，或flow_ask进入blocked。blocked：统筹flow_answer后回到processing。waiting_verify：测试验收；不通过退回processing；实现缺陷类累计满 3 次进入waiting_human，需统筹flow_dispatch放行。waiting_final：统筹flow_close归档，或flow_reject驳回（仅此状态可驳）。done：归档终态。
卡头 to_session 表示当前持有人；派单、交卡、验收都会更新投递目标。
工具一览¶
| 工具 | 作用 |
|---|---|
flow_roles |
登记或查看四角色对应的会话 id；action=set 可逗号分隔一次登记多会话 |
flow_start |
建任务卡，YAML 头含 from/to/type/ticket/status，初始 pending，投给统筹 |
flow_dispatch |
统筹派单；toSession 优先于角色名 to；同步卡头 to_session |
flow_submit |
开发交卡至 waiting_verify，自动选空闲测试；都忙则排队 |
flow_ask / flow_answer |
开发 blocked 提问，统筹答复后回开发 |
flow_verify |
测试写通过/不通过与报告；支持 dryRun:true 试算不改卡 |
flow_reject |
统筹在 waiting_final 终审驳回，退回原开发 |
flow_close |
归档至【归档区】按类型与年月目录，核对 SHA-256 |
flow_run |
按卡状态自动推进一步或多步，失败则停并说明 |
flow_status |
只读全局会话状态表，汇总活跃/待机 |
投递结果分三档：delivered、timeout、failed；超时按「视为送达」记账，明确失败则回滚卡头。派活登记写在 【文档区】\进度\派活登记.md，只追加不重写。
数据位置¶
- 插件配置：
~/.dsh/plugins/dsh-flow/config.json（工作区、任务卡目录、归档目录、角色会话 id）。 - 任务卡：
config.workspace+config.tasksDir（默认【文档区】\计划与任务；首次使用前须把workspace配成本机工作区路径）。 - 归档：
config.workspace+config.archiveDir，按<类型>\<YYYY-MM>分目录。
安装与启用¶
README 给出的方式是在 profile 中 link 本地插件目录，并重启 DSH（Host 启动时加载插件；改 lib/*.js 需重启，改 config.json 不必）。
1、确认插件目录已存在：~/.dsh/plugins/dsh-flow/。
2、在 profile 的 package.json 中挂上依赖与 bundle：
// ~/.dsh/profiles/<profile>/package.json
"dependencies": { "dsh-flow": "link:<home>/.dsh/plugins/dsh-flow" },
"dsh": { "profile": { "bundles": ["...", "dsh-flow"] } }
3、建立 junction（Windows PowerShell 示例）：
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\<profile>\node_modules\dsh-flow" `
-Target "$env:USERPROFILE\.dsh\plugins\dsh-flow"
4、重启 DSH。
5、登记四个角色（sessionId 须带 session- 前缀）：
flow_roles({ "action": "set", "role": "统筹", "sessionId": "session-abcdefgh-…" })
flow_roles({ "action": "set", "role": "开发", "sessionId": "session-abcdefgh-…" })
flow_roles({ "action": "get" })
预研、测试同理。只传 uuid 会报 session/not-found。
插件以当前 dsh 进程权限运行；安装前应自行查看仓库源码与许可证。DSH 社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
典型用法¶
分步与一键¶
需要逐步决策时用：flow_start → flow_dispatch → flow_verify → flow_close。卡已写好只想推进时用 flow_run；不确定卡在哪一步时，可先 flow_run 且 maxSteps: 1 看返回的 steps。
从预研建卡到派开发¶
预研会话建卡并投统筹：
flow_start({
"title": "视频录制插件",
"summary": "录屏录制",
"from": "预研",
"to": "统筹",
"requirement": "需要一个能把屏幕/会话录成 mp4 的插件：开始、停止、存到交付区。依赖尽量少。",
"criteria": "1) flow 工具能起录、停录；2) 产物是能播的 mp4；3) 空 PATH 能跑或写清依赖。"
})
统筹派给开发（README 完整案例中的一步）：
flow_dispatch({
"card": "任务卡_视频录制插件_录屏录制_NA_20261025.md",
"to": "开发",
"toSession": "<开发会话 id>",
"note": "按卡实现到 0.1.0，自测后 push，回执写在卡末"
})
开发完成后交卡、测试用 flow_verify 独立对照 criteria 验收、统筹终审后 flow_close 归档——README 中有从预研到归档的逐步说明，可按同一模式替换标题与路径复现。
适用场景与注意¶
适合已经在 DSH 里用多会话扮演不同职责、又希望流程不依赖人脑记忆的团队或个人。不适合把 dsh-theater 剧本流程与此插件混用；投递由本插件通过 agent.steer 与等待 turn/end 自行实现。
注意：手工建卡时卡头 to_session 常为统筹 id，交卡应传 flow_submit({ "session": "session-…" })；终审驳回会从交付记录取提交人，统筹登记 id 会被作废并记录在返回里（0.3.2 行为）。登记单写入失败不会阻断主流程，但会写 _dispatch-error.log，排查「登记单没写」时可先看该文件。
结尾¶
dsh-flow 把多会话协作收成「任务卡 + 状态机 + 工具派单/验收/归档」，用独立测试与终审约束「做完」的定义。若要安装说明与案例细节，以仓库 README 为准。
- 社区目录：https://www.skillhub.cn/plugins/KarBurKi/dsh-flow
- GitHub：https://github.com/KarBurKi/dsh-flow
