Passer au contenu principal
I

dsh-gated-workflow

invisiblezero/dsh-gated-workflow

A four-state workflow with program-level gates for DSH agents: discussion blocks file writes, implementation blocks out-of-scope edits, and verification requires evidence before checkmarks. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.

Installer

dsh plugin --profile web add github:invisiblezero/dsh-gated-workflow

README

dsh-gated-workflow —— 带程序级门禁的 Agent 工作流状态机插件

会话列表 / 四态状态机 + 门禁 / 两层手册

给 DeepSeek Harness 的桌面版插件:工作区 = 一个项目,会话 = 一个 workflow 单元,每个会话走四态状态机(讨论 → 实现 → 验收),靠程序级门禁管住每一步——讨论中写不了文件、实现中出不了声明范围、验收的 ✓ 拿不到证据打不上——再把项目总览 / 决策 / 约束 / 坑沉淀进两层手册(项目手册 + 会话手册)。


这个插件解决什么问题

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"
      ]
    }
  }
}
# 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。


相关文档

Plugins associés