dsh-gated-workflow
invisiblezero/dsh-gated-workflow
带程序级门禁的四态工作流:讨论中拦写文件、实现中拦越界改动、验收打勾必须带证据。它的 HTTP 路由没有 DSH 的访问检查,浏览器里打开的网页可以调用它们。
安装
dsh plugin --profile web add github:invisiblezero/dsh-gated-workflowREADME
dsh-gated-workflow —— 带程序级门禁的 Agent 工作流状态机插件
给 DeepSeek Harness 的桌面版插件:工作区 = 一个项目,会话 = 一个 workflow 单元,每个会话走四态状态机(讨论 → 实现 → 验收),靠程序级门禁管住每一步——讨论中写不了文件、实现中出不了声明范围、验收的 ✓ 拿不到证据打不上——再把项目总览 / 决策 / 约束 / 坑沉淀进两层手册(项目手册 + 会话手册)。
- 仓库地址:https://github.com/InvisibleZero/dsh-gated-workflow
- 版本:
0.9.4(更新记录见 CHANGELOG.md) - 验证环境:DSH
0.2.2-rc.1(Windows 桌面版) - 开发手册:DEVELOPMENT.md(构建命令、宿主契约速查、踩坑清单 D-01 起)
- 项目历程:JOURNEY.md(从加法到减法:为什么先做树、又为什么拆掉)
- 许可证:MIT
这个插件解决什么问题
AI 的输出无法控制、不可审查。
- 它能一口气把整件事做完,你只能对着 diff 事后追认;
- 你让它"先给方案再动手",下一轮它就忘了;
- 说好的分步执行,实际是"一次跑完,然后祈祷";
- 真出了偏差想追责,只剩聊天记录里的一段话。
这个插件做了什么
- 会话有状态(讨论中 / 实现中 / 验收中 / 已完结),每个状态能做什么由代码判定,不靠模型自觉;
- 讨论中改不了文件——不是"请不要改",是写操作被门禁直接拒绝,它只能先把方案写进手册;
- 想进下一阶段只能请求——工具调用只负责校验和登记,状态切换要你点「同意」,时间线记下这一步是谁推的;
- 过程可回看——方案与验收留在两层手册里,每一步迁移带来源,不随对话滚走。
一句话:它不追求让 AI 多干活,而是让 AI 干的活可控制、可审查、可追责。
怎么用
入口:会话切换为「门禁工作流模式」
- 设置 → Agent 预设 → 「自定义」里新增「门禁工作流模式」预设。
- 打开会话,把模式切换成「门禁工作流模式」,插件即接管这个会话:输入框工具条出现状态徽标「● 讨论中」。
你会点哪些东西
- 状态徽标「● 实现中」:点开节点弹窗,看会话手册 / 项目手册 / 补充说明 / 时间线;
→:请求推进到下一状态;↩:返工,退回上一阶段;- 「实施 n/m」:看实施顺序的勾选进度(只读);
- 设置 → 门禁工作流:改 A 公共 + B/C/D 三态的操作细节和默认输入;每态下方有只读的「本阶段硬规则」,点「改写硬规则」才会解锁(改前有警告);底部「恢复出厂默认」一键还原。
常见疑问
- 为什么它改不了文件? 讨论中的写操作被门禁直接拒绝,仅能通过工具修改手册。
- 手册在哪?
<工作区>/.workflow/:项目手册.md+会话手册-<node_id>.md。通常由 AI 自己维护。
功能
1. 会话即项目单元(自动认领)
不需要任何"新建 workflow"的入口——打开任意会话,它自动成为 workflow 节点,输入框工具条里出现状态徽标。会话按它所在的工作目录自动归属到对应的项目(工作区)。
2. 四态状态机 + 返工
讨论中 ──▶ 实现中 ──▶ 验收中 ──▶ 已完结
▲ ▲ │
└──────────┴──────────┘ 返工(退回上一阶段)
- 返工是条件流转:实现中可以退回讨论中(方案要改);验收中可以退回实现中(小问题修补)或讨论中(方案错)。
3. 会话里的状态徽标
权限控件右侧的状态胶囊(如「● 实现中」):
- 点它 → 打开节点弹窗(会话手册 / 项目手册 / 补充说明 / 时间线);
- 右边的
→→ 推进到下一状态; - 可返工时出现
↩→ 选择退回哪个阶段; - 实现中还会出现「实施 n/m」胶囊,点开看实施顺序的勾选进度(AI 勾、只读);
- 推进成功后,把新状态的默认输入填进输入框(不自动发送)。
4. 操作细节 A / B / C / D(应用级全局)
设置 → 门禁工作流:
- A 公共:三态通用,每个节点都读;
- B/C/D:讨论中 / 实现中 / 验收中各自的专属细节 + 进入后默认输入;
- 硬规则(只读,可改写):讨论中的「收尾」、实现中的「分层纪律」、验收中的「验收工具与证据要求」(报备落 ✓/?、不能直勾、轮次失效)属于插件层硬规则,不放在可编辑的操作细节里;默认收起,点「展开」看全文,点「改写硬规则」会先给警告,覆盖值会被标出来;
- 恢复出厂默认:把 A/B/C/D 全部还原成出厂值,并清掉硬规则覆盖值;
- 改动 700ms 自动保存,没有保存按钮。
5. 节点级附加说明
节点弹窗里可以给某个会话加一段补充(全局 / 讨论中 / 实现中 / 验收中),纯增量、不覆盖全局。
6. 按状态注入上下文
通过 systemPrompt.context() 注入,每次装配重新求值、不写进聊天记录。按层挂载,不是一个字符串(order 130~170):
状态头(节点 / workflow / 当前状态 / 阶段边界) order=130 硬层
【本阶段硬规则】 order=140 硬层
全局操作细节 A order=145 硬层
当前状态的 B/C/D 细节 order=150 硬层
节点补充要求 order=155 软层(最先丢)
项目手册的约束 / 红线(≤300 字) order=160 软层
标签表(写项目手册条目时能选哪些标签,≤600 字节) order=162 软层(空表不注入)
项目手册路径 + 「需要背景时自己用文件工具读」的引导 order=165 软层
会话手册(方案全文 + 未勾清单 + 已勾条数) order=170 硬层
硬层永不裁(合计超过 8000 字节直接报错,而不是悄悄少一条规则);软层按优先级从低到高丢,丢了哪层、每层多少字节、剩余多少预算都会写进事件日志。
7. 两层手册 + 实施清单(AI 自留)
所有手册平铺在工作区根目录的 .workflow/ 下:
<你的工作区>/.workflow/
项目手册.md ← 项目总览 / 决策记录 / 约束 / 坑与防线 / 标签表(每工作区一份,跨会话延续)
会话手册-<node_id>.md ← 方案(自底向上 4 层)+ 实施顺序(每会话一份,AI 自己勾)
- 讨论中把已确认方案按「目标与验收 → 数据层 → 领域层 → 接口层 → 表现层」写进会话手册;每层写清完成标准与层间契约;
- 实现中按「实施顺序」连续落地:每完成一层,先按该层完成标准自检,用
workflow_check把证据写进清单,然后直接进下一层;只有方案有洞 / 自检失败且无法自修 / 超出方案范围 / 不可逆操作 / 需要外部资源时才停下来问人; - 项目手册由各会话在收尾时回写结论,是跨会话的共享记忆;
.gitignore若存在,自动补一行.workflow/。
8. 状态时间线
每次状态迁移记一条(时间 + 从哪来 + 到哪去),节点弹窗里可回看这个会话是怎么一步步走到现在的。
9. 程序级约束:门禁 + 工具网关
状态机是硬约束,所以它不靠提示词,靠 DSH 的两个机制落地:
- 写操作门禁(
tools.guard):工具派发前判定,返回理由即拒绝,理由会作为错误结果回给模型;讨论中拦write/edit/pwsh等宿主写工具; - 工具网关:5 个基础工具不再原生注册,模型只看到
workflow_tool_call/workflow_tool_add;目录(基础 5 条 + 本工作区别名)注入系统提示。
| 状态 | 宿主写工具 | 网关里的基础工具 |
|---|---|---|
| 讨论中 | 拒绝 | 可用;workflow_check 与验收类被目录阶段规则拒绝 |
| 实现中 | 允许 | 全部可用 |
| 验收中 | 允许 | 全部可用;workflow_verify_report / workflow_verify_check 只在验收中可用 |
| 已完结 | 允许 | 全部可用(返工带 reason) |
基础工具(目录里的名字):
workflow_advance { to, reason? } // 只请求、不切换:校验前置后等你点「同意」
workflow_manual { target, action, section?, content?, tags?, entry?, from?, to? }
// read / replace_section(会话手册「方案」、项目手册「标签表」)
// append_entry / update_entry / remove_entry(项目手册一条一写,必须带 tags)
// rename_tag { from, to }:合并或重命名标签,级联改写所有引用它的条目
workflow_check { item, done, evidence? } // 勾选「实施顺序」里已存在的条目;勾选必须带 evidence(怎么验的 + 结果)
workflow_verify_report { item, result, summary, anchors, command?, findings? } // 验收报备;锚点须在工作目录内
workflow_verify_check { item, done=false } // 只能撤勾;打勾只能靠 report
两个入口:
workflow_tool_call { name, args } // 用目录里的工具;目录外 / 阶段不符 / 参数不符 / 覆盖固定参数都会被拒,理由原样回给模型
workflow_tool_add { name, description, base_tool, sample_args, fixed_args?, allowed_states? }
// 别名 = 基础工具 + 固定参数;四关(类型 / 静态 / 样例 / 阶段继承)全过才登记,只登记、不执行
要点:
- 手册写入有闸门:会话手册「方案」≤1200 字、整本 ≤2000 字(按字符算,勾选证据
| 自检:…不计入);项目手册「约束 / 红线」≤300 字;项目手册的条目必须带标签(- [标签1|标签2] 正文),新标签自动登记进「## 标签表」(最多 30 条,满了用rename_tag合并,合并不占额度);路径由插件拼,模型传不了路径;写后超过 200KB / 64KB 也会拒绝; - 别名只登记、不执行:模型没有直接注册权;申请只写本工作区的
tool-aliases.json,四关全过立即生效,但不执行任何业务;不能挂别名(禁止链式),基础工具缺失或文件损坏时只让别名失效; - 审计与页面:每次调用 / 申请写一条账(trace / 阶段 / 条目 / 参数摘要 / 结果 / 耗时 / 拒绝分类),
GET /dsh-gated-workflow/tools可读;设置页「工具」页签只读展示目录与最近 50 条; - 「方案」与「实施顺序」进入实现中后都不许改写:方案要改只能返工回「讨论中」,实施顺序只能
workflow_check勾选;勾选时必须附evidence(这一层怎么验的、结果是什么),证据会写进清单行;条目文字不匹配会报错并列出可勾项; - 推进前置是"分步绝对"的落点:方案没写进手册 → 进不了实现中;清单没勾完 → 进不了验收中。人工点
→走同一套前置,被拒会把原因弹出来。进「已完结」前还会做一次跨态失效校验:required 型检查器跑完后工作目录又有源码改动,证据判过期、要求重跑再报备。 - 验收证据可看、可导出:节点弹窗新增「验收」页签,七项每项展示复跑命令 / 退出码 / findings / 最近一次检查器运行;页签里「导出验收报告」把证据链 + 状态时间线写成一份 markdown 落
.workflow/下(可进 git、可存档)。 - 门禁自身异常会告警:guard 抛异常(是「插件坏了」不是「模型被管住」)时仍按 fail-closed 拒绝,且状态徽标变红、悬停显示原因,避免「看不见却报告没问题的门禁」。
- 状态切换权在人手里:模型调
workflow_tool_call({ name: "workflow_advance", args: { to: ... } })只是"请求"——前置校验通过后,徽标旁出现请求 → 实现中 [同意] [拒绝],点了同意才真正切换(时间线记by: agent-request,人工点击记by: human)。请求 5 分钟没处理就作废,避免僵尸按钮。
安装
方式一:从 GitHub 安装(推荐)
# 1. 进入你的 DSH profile(默认叫 desktop)
cd ~/.dsh/profiles/desktop
# 2. 安装(用 DSH 自带的 pnpm,或系统 pnpm)
pnpm add github:InvisibleZero/dsh-gated-workflow#main
然后确认该目录下的 package.json 里,dsh.profile.bundles 数组包含 "dsh-gated-workflow"(pnpm 不会自动加,需要手动补):
{
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-gated-workflow"
]
}
}
}
方式二:本地开发(link 到源码目录)
# 1. 先构建出 dist(插件入口是 dist/host.js 与 dist/client-bundle.js)
cd <仓库目录>
pnpm install --node-linker=hoisted
pnpm build
# 2. link 进 profile
cd ~/.dsh/profiles/desktop
pnpm add link:<仓库绝对路径>
同样把 "dsh-gated-workflow" 加进 dsh.profile.bundles。
安装后怎么生效
| 改了什么 | 怎么生效 |
|---|---|
宿主半(dist/host.js、路由、注入逻辑) | 插件页把它关一次再开,或重启 DSH |
客户端半(dist/client-bundle.js、界面) | 页面 Ctrl+Shift+R 硬刷新 |
| 只改设置里的文案 | 立即生效 |
插件声明了两半:
- 宿主半:
package.json的dsh.bundle.patch→cordis.patch.yml,自动插入id: dsh-gated-workflow; - 客户端半:
dsh.client声明 +exports["./client"]指向dist/client-bundle.js。
仓库开发
pnpm install --node-linker=hoisted # 本环境沙箱需要平铺 node_modules
pnpm build # tsc 宿主 → esbuild 单文件 → tsc 客户端 → 打客户端包
pnpm smoke # 客户端冒烟:槽位注册是否正常
pnpm typecheck # 只做类型检查
构建产物:
dist/host.js:宿主半单文件(ESM)dist/client-bundle.js:客户端半单文件(lazy-CJS,由window.__ModuleLoader__加载)
目录结构
src/
├── host.ts # 宿主半入口:22 条 HTTP 路由(ensure-node/transition/node-manual/…)
├── host/
│ ├── workflow-repository.ts # workflow 快照、节点(会话)、两层手册读写
│ ├── workflow-state-context.ts # 按状态注入上下文(systemPrompt.context)
│ └── event-log.ts # 埋点:进程内日志 + 内存环(/events 读,带 trace)
├── schema/ # 数据模型(Zod):node / node-state / workflow / migration;hard-rules.ts 是硬规则常量(无依赖,客户端可引)
├── engine/state-machine.ts # 纯逻辑:当前状态 → 实际生效的操作细节
├── adapter/ # 端口与实现:json-storage(原子写)/ port
└── client/ # 浏览器半
├── dsh-plugin.tsx # 客户端入口(注册三个槽位)
├── workflow-embedded.tsx # 会话状态徽标(状态/推进/返工/实施清单)
├── workflow-dialogs.tsx # 操作细节设置页 + 节点弹窗(手册/时间线)
├── session-row-dot.tsx # 侧栏会话行尾状态点
├── node-state-color.ts # 四态配色(共享常量)
└── menu-anchor.ts # Menu 定位原语
已知限制
- 手册隔离是「约定级」:所有会话的工作目录都是工作区根,模型技术上能读到别人的
.workflow/*.md,只靠注入内容与提示语约束; - 项目手册并发写:多会话共享项目手册,后写覆盖先写(单人顺序使用时基本无感);
- 删工作区是软删除:只删「工作区记录 + workflow 快照」,文件夹、会话日志、
.workflow/笔记都留在磁盘上; - 自动认领依赖会话 cwd:会话的工作目录必须能定位到工作区,否则徽标不出现;
- 手册由 AI 自留,人只读:节点弹窗只展示、不提供编辑入口。
- 门禁在「讨论中」拦写操作、「实现中」做可选范围拦截:「实现中」若实施顺序条目声明了「| 范围:」,越界改动会被拦(保守版:拿不到明确路径的写操作,如 bash/pwsh 命令串,放行并留痕);「验收中」「已完结」改文件不拦,靠流程与最终验收兜底。
数据与配置放在哪
| 位置 | 内容 | 是否进 git |
|---|---|---|
插件目录 settings/ | 操作细节、应用设置(global-settings.json / app-settings.json) | ✅ 随插件 |
插件目录 tools/ | 开发期额外登记的扩展工具;出厂 5 个在代码里 | ✅ 随插件 |
用户目录 ~/.dsh/dsh-gated-workflow/ | workflow 快照、回收站、导出、事件日志 events.jsonl(append-only 审计) | ❌ 运行数据 |
工作目录 .workflow/ | 两层手册(项目 / 会话) | ❌ 项目自己的 |
工作目录 .workflow/evidence/ | 检查器产物(deps.json / contract.json 等) | ❌ 跑的时候生成 |
settings/ 与 tools/ 首次运行才会写文件,仓库里现在是空的(只有 .gitkeep)。
致谢
七项验收里的依赖检查、死代码扫描、测试证据判定、并发压测、命名扫描(封杀词 + 格式混用),分别交给 dependency-cruiser(MIT)、 knip(ISC)、 Vitest(MIT)、 autocannon(MIT)。
这四个工具随插件一起安装(dependencies),拉下插件即可用;插件只解析它们的产物,
不修改它们的代码——没有这些项目,这几项只能靠人肉判断。
完整署名与用途见 THIRD-PARTY.md。
相关文档
- DEVELOPMENT.md:构建命令、宿主契约速查、踩坑清单(D-01 起)
- HANDOFF.md:交接说明
- SPIKE.md:最初的技术验证记录