SDD-Agent-WorkflowEngine

SDD-Agent-WorkflowEngine 是一个面向 VS Code 的本地 SDD Agent 工作流引擎。它以 Markdown 规格文档作为事实源，以固定工作流作为执行协议，以多 Agent 作为执行单元，在本地工作区完成产品设计、技术设计、UI/UX 设计、上下文收集、代码实现、审查、测试和文档回写。

当前阶段聚焦产品规格和技术方案沉淀，目标是建设一个可观察、可确认、可恢复的本地 AI 开发运行时。

核心目标

• 用 .sdd 文档管理需求、设计、上下文、验收和执行报告
• 用固定工作流串起设计、实现、审查、测试和文档回写
• 用多 Agent 分工执行不同节点任务
• 在每个节点执行前重新收集文档、代码、Git diff、Skill 和 RAG 上下文
• 在每个节点输出后执行格式、事实、Skill 和测试相关校验
• 在 VS Code 内展示节点状态、Agent 日志、工具调用、Git diff、测试输出和最终报告

核心闭环

---
config:
  theme: base
  themeVariables:
    fontFamily: "Inter, ui-sans-serif, system-ui"
    primaryTextColor: "#172033"
    lineColor: "#64748b"
---
flowchart LR
  A[SDD 文档] -->|提供事实源| B[固定工作流]
  B -->|调度节点| C[多 Agent 执行]
  C -->|产出实现| D[代码改动]
  D -->|进入质量检查| E[审查]
  E -->|通过审查| F[测试]
  F -->|通过验证| G[文档回写]
  G -->|沉淀结果| A

  classDef docs fill:#dbeafe,stroke:#2563eb,color:#172033
  classDef workflow fill:#dcfce7,stroke:#16a34a,color:#172033
  classDef agent fill:#fef3c7,stroke:#d97706,color:#172033
  classDef gate fill:#ede9fe,stroke:#7c3aed,color:#172033

  class A,G docs
  class B workflow
  class C,D agent
  class E,F gate

Loading

固定工作流

一期流程固定为：

---
config:
  theme: base
  themeVariables:
    fontFamily: "Inter, ui-sans-serif, system-ui"
    primaryTextColor: "#172033"
    lineColor: "#64748b"
---
flowchart LR
  A[任务] -->|解析任务| B[产品设计]
  B -->|明确验收| C[技术设计]
  C -->|定义方案| D[UI/UX 设计]
  D -->|补齐交互| E[上下文]
  E -->|生成上下文包| F[实现]
  F -->|提交改动| G[审查]
  G -->|审查通过| H[测试]
  G -->|发现问题| F
  H -->|测试通过| I[文档]
  H -->|测试失败| F

  classDef spec fill:#dbeafe,stroke:#2563eb,color:#172033
  classDef design fill:#dcfce7,stroke:#16a34a,color:#172033
  classDef context fill:#fef3c7,stroke:#d97706,color:#172033
  classDef exec fill:#fce7f3,stroke:#db2777,color:#172033
  classDef gate fill:#ede9fe,stroke:#7c3aed,color:#172033

  class A spec
  class B,C,D design
  class E context
  class F,I exec
  class G,H gate

Loading

节点	Agent	主要产物	职责
任务	文档 Agent	task-summary.md	解析任务输入
产品设计	产品 Agent	product-design.md	明确产品目标和验收口径
技术设计	技术 Agent	technical-design.md	生成技术方案、模块边界和风险
UI/UX 设计	UI/UX Agent	uiux-design.md	生成页面结构和交互说明
上下文	上下文 Agent	context-pack.md / context-pack.json	收集文档、Skill、RAG、代码和 Git diff
实现	实现 Agent	Git diff、implementation-summary.md	修改代码或生成补丁
审查	审查 Agent	review.md	检查质量、需求满足度和项目规范
测试	测试 Agent	test-report.md	推断并运行测试命令
文档	文档 Agent	execution-report.md	回写实现摘要、验收结果和遗留事项

核心机制

机制	作用
SDD 文档	.sdd 是任务事实源，保存任务、设计、上下文、审查、测试和报告
Skill	.skills/<skill-name>/SKILL.md 定义任务步骤、输出格式和检查清单
RAG	检索项目文档和 Skill 文档，为 Agent 补充上下文
上下文重置	每个节点执行前重新读取文档、Skill、RAG、Git diff、测试输出和运行产物
自动门禁	每个节点输出后校验格式、文档约束、Skill 检查清单、Git diff 和测试结果
本地执行器	提供文件读写、项目搜索、Git diff、命令执行和权限控制能力

技术架构

层	技术	职责
VS Code 插件	TypeScript	插件入口、命令、配置、Webview、本地进程管理
SDD 运行控制台	React	固定流程运行台、节点状态、日志、Git diff、报告
Agent 运行时	Python + LangGraph	工作流调度、Agent 编排、重试、回退、检查点
AI / RAG	OpenAI SDK + LangChain	模型调用、向量嵌入、文档检索、结构化输出
本地执行器	Go	文件读写、项目搜索、Git diff、命令执行、权限控制
存储	SQLite + 文件系统	运行状态、RAG 元数据、约束包、门禁结果、文档产物

数据目录约定

.sdd/
  config.yaml
  tasks/<task-id>/
    task.md
    task-summary.md
    product-design.md
    technical-design.md
    uiux-design.md
    context-pack.md
    context-pack.json
    implementation-summary.md
    review.md
    test-report.md
    execution-report.md
  runs/latest/
    run.json
    events.jsonl
    constraints/<node-id>.json
    gates/<node-id>.json

.skills/<skill-name>/SKILL.md

VS Code 插件形态

SDD-Agent-WorkflowEngine 以 VS Code 插件形式运行，主要包含：

• 活动栏入口
• 侧边栏中的任务、运行、Skills、RAG 视图
• 编辑器 Webview 中的 SDD 运行控制台
• Markdown 编辑器中的 SDD 文档编辑体验

SDD 运行控制台展示固定工作流节点状态、当前节点配置、绑定文档、Agent 日志、工具调用、Git diff、测试输出、门禁结果和最终报告。

配置示例

.sdd/config.yaml：

version: 1
model:
  provider: openai
  default: gpt-5.4
workflow:
  type: fixed-sdd
nodes:
  implementation:
    maxRetries: 2
    fileWriteMode: auto
    commandMode: ask
    skills:
      - react-ui
    rag:
      - project-docs
    gates:
      - schema
      - document
      - skill
      - fact

典型使用流程

1. 在工作区创建 .sdd/tasks/<task-id>/task.md
2. 在 VS Code 中启动 SDD 工作流
3. 运行时按固定节点生成产品、技术和 UI/UX 设计文档
4. 上下文 Agent 生成上下文包
5. 实现 Agent 修改文件或生成补丁
6. 审查 Agent 和测试 Agent 执行质量门禁
7. 文档 Agent 生成 execution-report.md

MVP 范围

• VS Code 插件
• .sdd 任务目录
• 固定 SDD 工作流
• SDD 运行控制台
• Skill 读取
• RAG 检索
• 上下文重置
• 自动门禁
• 本机文件修改和命令执行
• 审查/测试修复循环
• execution-report.md

文档

• 产品规格
• 技术设计