夜雨聆风OpenClaw Dev Workflow 插件深度解析
多智能体编排/规格驱动开发/10 步工作流/QA 质量门
从架构设计到源码实现+踩坑避坑+生产级实践
我是atyou, 今天教大家OpenClaw Dev Workflow 插件——一个基于 AI 的规格驱动开发工作流，集成多智能体编排、10 步工作流引擎、21 条代码质量规则和 Ship/Show/Ask 交付框架。
在 AI 辅助编程领域，大多数工具停留在「对话式编码」层面——你问一句，它写一行。但真正的工程化开发需要更严谨的流程：需求分析、方案设计、任务拆解、TDD 测试驱动、代码评审、质量门禁、自动化交付。
今天我将深度解析 @openclaw/dev-workflow 插件的完整架构。这是一个为 OpenClaw 设计的生产级开发工作流引擎，支持 Quick/Standard/Full 三种复杂度模式，内置 10 步工作流、多智能体编排系统、10 项 QA 质量门检查和 21 条代码质量规则。
我会从源码层面拆解每个模块的设计思路，并标注实际踩坑点，让你不仅能理解它的工作原理，还能在自己的项目中复用这些模式。
— — — — — — — — — —
一、架构总览：为什么需要规格驱动开发？
传统 AI 编码工具的痛点：缺乏结构化流程、没有质量保障、无法追溯决策。Dev Workflow 插件通过规格驱动（Spec-Driven）的方式解决这些问题。
Step 1规格驱动开发的核心思想
规格驱动开发的本质是「先设计后实现」：AI 在写代码之前，先生成提案（Proposal）、设计文档（Design）和任务列表（Tasks）。这确保每一步都有据可查，避免 AI 盲目编码。
工作流数据模型包含三个核心接口：WorkflowSpec（提案+设计+任务）、WorkflowContext（项目状态+决策记录）、WorkflowTask（单个任务的元数据）。
interface WorkflowSpec {
proposal:string;// 提案文档（Markdown）
design:string;// 设计文档（Markdown）
tasks:WorkflowTask[];// 任务列表
updatedAt:string;
}
图1：Dev Workflow 插件整体架构（作者自绘）
Step 2三种复杂度模式
插件根据任务复杂度提供三种模式，自动裁剪工作流步骤：
•Quick 模式 — 快速修复。跳过头脑风暴、技术选型、评审、测试、文档环节。适合单文件修改、bug 修复。
•Standard 模式 — 均衡模式。包含完整工作流但 TDD 不强制。适合大多数功能开发。
•Full 模式 — 生产级。强制严格 TDD（RED→GREEN→REFACTOR→VERIFY→COMMIT）、QA 质量门阻断式检查、技术选型环节。适合核心功能开发。
💡模式自动推荐 AgentOrchestrator.analyzeRequirement() 会通过子智能体分析需求复杂度，自动推荐匹配的模式。如果子智能体失败，降级为基于需求词数的启发式分析（词数>50=high=full，>20=medium=standard，否则=quick）。 |
— — — — — — — — — —
二、10 步工作流引擎：从需求到交付的完整链路
DevWorkflowEngine 是核心引擎，管理 10 个工作流步骤的执行。每个步骤通过 runStep() 方法包装，自动持久化上下文到 .dev-workflow-context.json。
Step 1Step 0: Analysis（项目分析）
工作流启动前，引擎首先分析项目上下文：检测 OpenSpec 目录、Git 状态、package.json 脚本、TypeScript 配置、顶层目录结构。
同时执行 BootstrapManager 检查项目基础设施（lint、test、typecheck 配置），以及 MemdirManager 初始化记忆系统并召回历史决策。
const analysis = await this.orchestrator.runAnalysis(projectDir);
// → "Project: name: dev-workflow, scripts: build, typecheck, test, lint."
// → Dirs: src, tests, dist. TS: true. OpenSpec: true. Git: clean."
📝踩坑记录 #1：Git 状态检测超时 runAnalysis() 中 git status --porcelain 设置了 10 秒超时。如果项目极大（如 monorepo），可能超时返回 "not-a-git-repo"。解决方案：对大项目增加 timeout 参数，或使用 git diff --quiet 替代。 |
Step 2Step 1: Requirement（需求分析）
子智能体分析需求的复杂度、预估影响文件数、识别受影响模块。输出 JSON 格式：{ complexity, estimatedFiles, affectedModules }。
Step 3Step 2: Brainstorm（头脑风暴）
Standard 和 Full 模式下执行。子智能体提出 3 种不同的实现方案，每种方案包含 pros 和 cons。结果存入 brainstormNotes 供后续步骤参考。
Quick 模式跳过此步骤直接进入规格定义。
Step 4Step 3: Spec（规格定义）
这是核心步骤。子智能体根据需求和头脑风暴笔记，生成完整的 WorkflowSpec：包含 proposal（提案）、design（设计）、tasks（任务列表）。
同时写入 openspec/changes/dev-workflow/ 目录下的 proposal.md、design.md、tasks.json，与 OpenSpec 规范兼容。
writeFileSync(join(openspecDir, 'proposal.md'), spec.proposal);
writeFileSync(join(openspecDir, 'design.md'), spec.design);
writeFileSync(join(openspecDir, 'tasks.json'), JSON.stringify(spec.tasks, null, 2));
💡任务元数据设计 每个 WorkflowTask 包含：id、title、description、difficulty（easy/medium/hard）、estimatedMinutes、dependencies（依赖任务 ID 数组）、files（影响文件）、shipCategory（ship/show/ask）。这些字段共同驱动后续的任务调度和交付策略。 |
Step 5Step 4: Tech Selection（技术选型）
仅 Full 模式执行。子智能体选择语言、框架、架构模式（如 modular-monolith、microservices）、设计模式（repository、factory、observer）。
Step 6Step 4.5: Plan Gate（计划闸门）
关键设计：在开发前设置闸门，等待用户审批。同时通过 PermissionManager.upgradeToWorkspaceWrite() 将权限从只读升级为可写。
这是安全设计——AI 在获得用户确认前不会修改任何文件。
this.permissionManager.upgradeToWorkspaceWrite();
// 权限升级后，AI 才能执行 git add/commit 等写操作
⚠️踩坑记录 #2：权限升级时机 Plan Gate 是权限升级的关键节点。如果跳过此步骤直接开发，PermissionManager.canWrite() 会返回 false，导致后续 git commit 被 pre-commit 钩子拦截。必须确保 Plan Gate 在 development 之前执行。 |
Step 7Step 5: Development（开发执行）
开发阶段首先创建 feature 分支（feature/
任务执行采用依赖拓扑排序：无依赖任务优先执行，有依赖任务等待依赖完成后执行。如果某个依赖失败，所有下游任务自动取消。
const independent = batch.filter(t => t.dependencies.length === 0);
const dependent = batch.filter(t => t.dependencies.length > 0);
const ordered = [...independent, ...dependent];
Step 8Step 6-8: Review → Test → Docs
Quick 模式跳过这三个步骤。Standard 和 Full 模式依次执行：
Step 6 Review：子智能体审查最近的 git diff 和 commit log，输出 APPROVE 或 REQUEST CHANGES。
Step 7 Test：自动检测测试框架（vitest/jest/pytest），执行测试套件。
Step 8 Docs：根据 spec 的 proposal 和 design 生成 docs/generated.md。
Step 9Step 8.5: GitHub 集成
Full 模式且开启 githubIntegration 时执行：自动创建 git tag（如 v0.1.0）、推送 tag 到远程、更新仓库描述、合并 feature 分支到 main。
通过 gh CLI 工具完成，需要预先 gh auth login。
execSync(`git tag -a ${tag} -m "Release ${tag}"`, { cwd: dir });
execSync(`git push origin ${tag}`, { cwd: dir });
execSync(`gh repo edit --description "${desc}"`, { cwd: dir });
📝踩坑记录 #3：GitHub 操作静默失败 runGitHubSteps() 使用 try-catch 包裹所有 gh 命令，失败时仅记录 "GitHub step skipped" 而不中断工作流。这意味着如果 gh 未安装或未认证，GitHub 集成步骤会静默跳过。建议在 CI 环境中增加前置检查。 |
Step 10Step 9: Delivery（交付）
交付阶段生成完整的 Delivery Report，包含：项目信息、模式、耗时、任务完成统计（ship/show/ask 分类）、分支信息、规格提案、决策日志、QA 质量门结果。
同时将决策记忆存入 MemdirManager 供未来工作流召回。
Tasks: 4/4 completed (ship:2 show:2 ask:0)
Branch: feature/dev-workflow-1712345678901
— — — — — — — — — —
三、多智能体编排系统：9 大核心方法
AgentOrchestrator 是多智能体编排的核心类，通过 runtime.subagent.run() 和 waitForRun() 管理子智能体生命周期。每个方法对应工作流中的一个智能体角色。
Step 1智能体角色矩阵
不同难度的任务分配给不同能力的模型：
智能体角色 | 方法 |
项目分析师 | runAnalysis() |
需求架构师 | analyzeRequirement() |
方案设计师 | brainstorm() |
技术负责人 | defineSpec() / selectTech() |
高级工程师 | executeTask() |
代码评审员 | runReview() |
测试执行器 | runTests() |
技术写手 | generateDocs() |
验证官 | VerificationAgent.verify() |
💡模型选择策略 selectAgent() 根据任务难度映射模型：easy→minimax-m2.5，medium→minimax-m2.5，hard→glm-5.1，extreme→qwen3。这意味着简单任务用低成本模型，复杂任务用高能力模型，实现成本优化。 |
Step 2子智能体执行模式
所有子智能体调用遵循统一模式：run() 启动 → waitForRun() 等待结果 → getSessionMessages() 提取输出 → JSON 解析。
每个方法都有 fallback 机制——如果子智能体失败（超时、网络错误、解析失败），返回默认值而非抛出异常。
const runResult = await this.runtime.subagent.run({
sessionKey,message: `Requirement: ${requirement}`,
extraSystemPrompt:systemPrompt, deliver: false,
});
const waitResult = await this.runtime.subagent.waitForRun({
runId:runResult.runId, timeoutMs: 120000,
});
// 提取 JSON 输出
const m = text.match(/\{[\s\S]*\}/);
if (m) return JSON.parse(m[0]);
📝踩坑记录 #4：JSON 解析失败 子智能体输出可能包含 Markdown 代码块包裹（```json ... ```）或额外文本。代码使用正则 /\{[\s\S]*\}/ 提取最外层 JSON 对象。但如果智能体输出多个 JSON 对象或格式不规范，解析会失败并触发 fallback。建议在 systemPrompt 中强调 "Return ONLY valid JSON"。 |
Step 3任务执行与 TDD 循环
executeTask() 是智能体编排中最复杂的方法。它根据模式构建不同的 TDD 提示：
Quick 模式："Write code and verify it works."——直接编码。
Standard 模式：标准 TDD 循环（RED→GREEN→REFACTOR→VERIFY→COMMIT）。
Full 模式：严格 TDD，强调 "DO NOT skip any step. Tests MUST fail first before implementation."
// Full 模式下的 TDD 提示词
1. RED: Write a failing test first that defines expected behavior
2. GREEN: Write the minimal implementation to make the test pass
3. REFACTOR: Simplify while keeping tests green
4. VERIFY: Run all tests to confirm no regressions
5. COMMIT: Prepare a Conventional Commits message
— — — — — — — — — —
四、Ship/Show/Ask 交付框架：安全交付的三档策略
Ship/Show/Ask 是 Google 提出的代码变更分类框架。Dev Workflow 将其实现为自动化的交付策略，每个任务根据其风险等级分配不同的交付方式。
Step 1三档策略详解
策略 | 行为 |
Ship | 直接提交，无需审批 |
Show | 提交但标记为需要异步评审 |
Ask | 先运行代码评审，评审通过后才提交 |
Step 2Ask 策略的评审流程
Ask 策略触发完整的评审流程：orchestrator.runReview() 分析最近的 git diff 和 commit log，子智能体输出评审意见。如果包含 "APPROVE"、"approve" 或 "looks good"，则自动提交；否则阻塞并记录评审意见。
case 'ask': {
constreview = await this.orchestrator.runReview(...);
if(review.includes('APPROVE') || review.includes('looks good')) {
this.gitCommit(commit,task.files);
this.context.decisions.push(`Ask→Approved:${commit}`);
}else {
this.context.decisions.push(`Ask→Blocked:${commit}`);
}
}
📝踩坑记录 #5：评审关键词匹配过于简单 当前实现使用字符串 includes() 匹配 "APPROVE"/"looks good"。如果评审员写 "APPROVED"（过去式）或 "LGTM"（常见缩写），匹配会失败导致变更被错误阻塞。建议改用正则 /approve|approved|lgtm|looks good/i 进行不区分大小写的匹配。 |
Step 3约定式提交自动生成
每个任务提交时，generateCommitMessage() 自动推断 Conventional Commits 格式：type(scope): description。
type 推断规则：包含 "test"→test，包含 "doc"→docs，包含 "fix"/"bug"→fix，包含 "refactor"→refactor，包含 "setup"/"config"/"init"→chore，默认→feat。
scope 从文件路径推断：src/components/Button.tsx → components。
// 推断结果示例
feat(components): add dark mode toggle
fix(auth): resolve token refresh issue
docs: update api reference
test(utils): add edge case coverage
— — — — — — — — — —
五、QA 质量门：10 项检查 + 21 条代码规则
QA Gate 是交付前的最后一道防线。QAGateTool 提供 10 项独立检查，每项检查自动检测项目配置并执行对应命令。
Step 110 项 QA 检查
检查项 | 检测逻辑 |
lint | 检测 ESLint/Ruff 配置，执行对应命令 |
format | 检测 Prettier 配置，执行 prettier --check |
tests | 自动检测 vitest/jest/pytest，执行测试 |
coverage | 执行覆盖率检查，阈值 80% |
typecheck | 检测 tsconfig/mypy，执行 tsc --noEmit |
simplify | 扫描文件行数（>500）和函数行数（>50） |
commits | 检查最近 10 次提交是否符合 Conventional Commits |
todos | grep TODO/FIXME/HACK/XXX 注释 |
docs | 检查 README.md 存在且内容 >50 字符 |
rules | 执行 21 条代码质量规则检查 |
Step 221 条代码质量规则
DEV_WORKFLOW_RULES 定义了 21 条规则，分为 error（阻断）和 warning（非阻断）两个级别：
•Error 级（6 条） — no-unused-vars、no-any-type、no-duplicate-code、no-debugger、no-hardcoded-secrets、no-global-mutation
•Warning 级（15 条） — prefer-const、no-console-log、explicit-return-types、no-magic-numbers、max-file-lines、max-function-lines、no-inline-styles、prefer-immutable、no-deep-nesting、meaningful-names、single-responsibility、no-commented-code、prefer-early-return、no-boolean-params、prefer-pure-functions
💡规则执行时机 规则不仅在 QA Gate 时检查，还会在 executeTask() 的 systemPrompt 中嵌入，指导子智能体在编码时遵守规则。这是「预防优于检测」的设计思想。 |
Step 3VerificationAgent：独立验证官
VerificationAgent 是一个独立的验证类，在每个任务完成后自动执行 lint、tests、typecheck 三项检查，生成 VerificationReport。
如果 qaGateBlocking 为 true 且验证失败次数达到 MAX_RETRIES（2 次），任务会被标记为失败并阻塞后续依赖任务。
interface VerificationReport {
taskName:string;
lint:CheckResult;// { passed, output, errors }
tests:CheckResult;
typeCheck:CheckResult;
verdict:'PASS' | 'FAIL';
issues:string[];
timestamp:string;
}
— — — — — — — — — —
六、高级特性：记忆系统、工作记忆、Feature Flags
除了核心工作流，插件还包含多个高级特性，提升跨会话协作能力和长期项目维护性。
Step 1Memdir 记忆系统
MemdirManager 管理项目级记忆，支持 initialize（初始化）、recall（召回）、remember（存储）、updateAging（老化更新）。
工作流启动时召回历史记忆，交付时将决策记录存入记忆。这实现了跨会话的知识传承——AI 下次启动时能记住之前的决策。
await this.memdirManager.initialize(projectDir);
const memories = await this.memdirManager.recall(projectDir, 'all');
// → Memory: recalled 3 entries
// 交付时存储决策
await this.memdirManager.remember(projectDir, {
type:'decision',
title:`Workflow decisions for ${projectId}`,
content:decisions.join('\n'),
tags:['workflow', projectId],
});
Step 2Working Memory 三层上下文
WorkingMemoryManager 实现三层上下文：Project（.dev-workflow.md）→ Task（docs/plans/
支持自动压缩：shouldCompact() 检测上下文大小，L1 压缩（精简当前步骤）和 L2 压缩（归档已完成任务）。
Step 3Feature Flags 生命周期管理
FeatureFlagManager 不仅管理运行时开关，还跟踪 feature flag 的完整生命周期：创建→启用→扫描代码位置→检测清理候选→标记废弃。
自动扫描源码中的 feature_flags.is_enabled()、useFeatureFlag()、process.env.FF_ 等模式，生成 docs/feature-flags.md 注册表。
interface FeatureFlagEntry {
name:string;
type:'release' | 'ops' | 'experiment' | 'permission';
status:'enabled' | 'disabled' | 'gradual' | 'deprecated';
plannedCleanup:string;// 计划清理日期
codeLocations:string[]; // 代码中的引用位置
}
📝踩坑记录 #6：Feature Flag 清理遗漏 detectCleanupCandidates() 仅检查 plannedCleanup 日期和 deprecated 状态。但如果 flag 的 plannedCleanup 设为 "TBD"（默认值），永远不会被标记为清理候选。建议在创建 flag 时强制设置 plannedCleanup 日期，或增加基于 lastReferenced 时间的自动过期检测。 |
Step 4Handover 交接文档
HandoverManager 在 session_end 钩子触发且 reason 为 handover 时生成交接文档。新会话启动时，session_start 钩子消费交接文档，恢复项目进度。
这解决了 AI 编码中最常见的上下文丢失问题——当你需要切换模型或中断会话时，进度不会丢失。
Step 5PermissionManager 权限管理
PermissionManager 实现最小权限原则：默认只读，Plan Gate 通过后升级为 workspace-write。pre-commit 钩子验证写入权限，before_tool_call 钩子检测危险操作（DROP、TRUNCATE、push --force、reset --hard、rm -rf）。
Full 模式下，before_tool_call 钩子会扫描工具输入中的危险操作关键词并记录警告。
— — — — — — — — — —
七、事件钩子系统：9 个生命周期钩子
插件注册了 9 个事件钩子，覆盖会话、步骤、任务、工具调用的完整生命周期。
Step 1钩子矩阵
钩子名称 | 触发时机 |
session_start | 会话开始 |
session_end | 会话结束 |
pre_step | 步骤执行前 |
post_step | 步骤执行后 |
post_task | 任务完成后 |
pre_commit | 提交前 |
before_tool_call | 工具调用前 |
after_tool_call | 工具调用后 |
task_completed | 任务完成 |
⚠️踩坑记录 #7：重复验证 post_task 和 task_completed 两个钩子都执行了 verificationAgent.verify()。这意味着每个任务会被验证两次，浪费执行时间。建议移除其中一个，或让 task_completed 钩子仅在特定条件下执行。 |
— — — — — — — — — —
八、源码架构与模块划分
插件采用清晰的模块化架构，16 个源文件分布在 12 个目录中。
Step 1目录结构
核心模块按职责划分：
src/
├── index.ts# 插件入口（defineChannelPluginEntry）
├── types.ts# 领域类型（187 行，21 条规则定义）
├── channel/# 频道插件定义 + 运行时单例
├── engine/# DevWorkflowEngine（564 行，10 步工作流）
├── agents/# AgentOrchestrator + VerificationAgent
├── tools/# 8 个工具（启动、状态、执行、规格、QA、Plan Gate、权限、后台任务）
├── hooks/# 9 个事件钩子（241 行）
├── feature-flags/# Feature Flag 生命周期管理
├── working-memory/# 三层工作记忆管理
├── handover/# 会话交接文档
├── bootstrap/# 项目基础设施检查
├── memdir/# 项目记忆系统
├── permissions/# 最小权限控制
├── background-tasks/# 后台任务管理
├── directory-templates/# 目录模板管理
└── utils/# 工具函数
Step 2依赖分析
插件的依赖极简：
dependencies:
@sinclair/typebox:0.34.49// JSON Schema 验证
zod:^3.24.0// 运行时类型校验
devDependencies:
typescript:^5.7.0
vitest:^3.0.0
oxlint:^0.15.0
openclaw:file:../../../openclaw// peer dependency
💡零外部 LLM 依赖 插件本身不依赖任何 LLM SDK。所有智能体调用通过 OpenClaw 的 runtime.subagent API 完成，这意味着插件是纯粹的「工作流编排层」，与具体模型解耦。这是优秀的设计——更换模型不需要修改插件代码。 |
— — — — — — — — — —
七、常见问题与排错
7.1子智能体超时怎么办？
症状：executeTask() 或 defineSpec() 报错 timeout
•检查 timeoutMs 设置：Full 模式任务执行超时为 600000ms（10 分钟），Standard 为 300000ms（5 分钟），Quick 为 180000ms（3 分钟）
•defineSpec() 超时为 180000ms（3 分钟），如果需求复杂可能不够
•解决方案：拆分需求为更小的规格，或增加 timeoutMs 参数
•检查网络连接和模型服务状态
7.2QA Gate 检查全部通过但交付仍然失败？
排查步骤：
•检查 .dev-workflow-context.json 是否被意外删除或损坏
•确认 git 仓库状态正常（git status）
•检查 feature 分支是否正确创建
•查看 decisions 日志中的错误信息
7.3如何在已有项目中启用 Dev Workflow？
安装步骤：
•pnpm add @openclaw/dev-workflow --workspace
•在 OpenClaw 配置中启用 dev-workflow channel
•通过 dev_workflow_start 工具启动工作流
•首次启动会自动执行 Bootstrap 检查项目基础设施
dev_workflow_start({
requirement:"添加用户认证模块",
projectDir:"/path/to/project",
mode:"full",
featureFlags:{ strictTdd: true, qaGateBlocking: true }
})
7.4如何自定义 21 条代码规则？
规则定义在 types.ts 的 DEV_WORKFLOW_RULES 常量中。目前不支持运行时自定义，但可以通过 feature flags 的 ruleEnforcement 开关启用/禁用全部规则。
•修改源码后需要 pnpm build 重新编译
•建议通过 PR 向项目提交自定义规则
•规则分为 error（阻断交付）和 warning（仅警告）两个级别
7.5工作流中断后如何恢复？
DevWorkflowEngine 通过 .dev-workflow-context.json 持久化上下文。重启后调用 initialize() 会自动加载已有上下文并恢复进度。
•检查 .dev-workflow-context.json 是否存在
•确认 currentStep 字段记录了中断位置
•HandoverManager 也可用于跨会话恢复
— — — — — — — — — —
八、安全建议
•永远不要将 API Key 或凭证硬编码在代码中（no-hardcoded-secrets 规则会检测）
•Feature Flag 注册表（docs/feature-flags.md）可能包含敏感信息，应加入 .gitignore
•.dev-workflow-context.json 包含项目决策和文件路径，团队共享时注意脱敏
•Plan Gate 的权限升级机制确保 AI 在用户审批前不会修改文件
•before_tool_call 钩子在 Full 模式下检测危险操作（DROP、TRUNCATE、push --force 等）
⚠️重要提醒 本文中出现的所有代码均为源码分析结果，不涉及敏感信息。在实际使用中，请遵循项目的安全规范和代码质量标准。 |
— — — — — — — — — —
总结
@openclaw/dev-workflow 插件的核心价值在于将 AI 编码从「对话式」升级为「工程化」：通过规格定义确保设计先行，通过多智能体编排实现角色分工，通过 QA 质量门保障代码质量，通过 Ship/Show/Ask 框架实现安全交付。
关键要点回顾：
•三种模式：Quick（快速修复）/ Standard（均衡）/ Full（生产级 TDD）
•10 步工作流：Analysis → Requirement → Brainstorm → Spec → Tech Selection → Development → Review → Test → Docs → Delivery
•多智能体编排：9 个角色，按难度自动选模型（minimax-m2.5 / glm-5.1 / qwen3）
•21 条代码规则：6 条 error 级 + 15 条 warning 级，编码时嵌入提示 + QA 时检测
•Ship/Show/Ask：三档交付策略，Ask 模式自动触发代码评审
•9 个事件钩子：覆盖会话/步骤/任务/工具调用全生命周期
— — — — — — — — — —
我是atyou, 您有什么感兴趣的主题，可以给我留言。让我们一起拥抱AI, 共同进步，享受美好生活。
参考文档：
•OpenClaw 官方仓库
•Conventional Commits 规范
•Ship/Show/Ask 框架（Google）
•TDD 红绿重构循环
