SDD-Agent-Harness

SDD-Agent-Harness 是一个 Codex-like 本地 AI 开发 App。它用固定工作流、SDD 文档和 Harness 约束承载 AI 编程任务，让一次开发留下可审查、可验证、可回退的文档和证据。

固定流程：

Spec -> Plan -> Build -> Verify -> Report

工作流

每个任务线程固定经过五个节点。节点产物写入 .sdd/tasks/<task-id>/，运行证据写入 .sdd/runs/<run-id>/。

Node	核心职责
Spec	把用户目标转成可验收、可追踪的需求规格
Plan	把需求转成 Build 可执行合同
Build	在受控范围内生成代码变更和证据
Verify	用测试、扫描、审查和 Gate 验证变更
Report	输出最终报告和机器可读追踪关系

当前状态

当前仓库处于早期骨架阶段，已落地 runtime/executor 基础代码和完整 MVP 规格。

已实现：

apps/runtime-py   Python runtime：配置加载、CLI、workflow 占位节点
apps/executor-go  Go executor：本地 executor CLI 骨架
.sdd/config.yaml  固定五节点 workflow 配置
specs/            MVP 规格、计划、任务和验证说明

计划中的桌面 App、React UI、artifact writer、Gate/evidence writer 和 Agent Adapter 执行后端还在后续任务中。

快速验证

运行 runtime：

npm run runtime -- run --task TASK-001

预期输出：

SDD run started: TASK-001
Loaded workflow: spec -> plan -> build -> verify -> report

运行 executor：

npm run executor -- status

检查当前骨架：

npm run runtime:check
npm run executor:check

项目结构

.
├─ .sdd/config.yaml
├─ apps/
│  ├─ runtime-py/
│  └─ executor-go/
├─ docs/
│  ├─ overview.md
│  └─ reference-landscape.md
├─ specs/001-local-app-mvp/
│  ├─ spec.md
│  ├─ plan.md
│  ├─ tasks.md
│  └─ quickstart.md
└─ package.json

设计文档

面向用户的项目解释：

文件	作用
overview.md	解释项目目标、五节点工作流和每个节点的质量优化
reference-landscape.md	汇总可参考或可接入的开源项目、公开方法和 skill，并映射到五节点优化

当前版本的规格文档集中在 specs/001-local-app-mvp/：

文件	作用
spec.md	MVP 产品规格、五节点详细要求、实体和成功标准
plan.md	实现计划、目标架构和当前代码状态
tasks.md	分阶段实现任务清单
quickstart.md	当前骨架验证和目标 MVP 验证路径

下一步

优先把 runtime 从配置读取推进到真实产物生成：

1. 支持 --run 和 --goal 参数。
2. 创建 .sdd/tasks/<task-id>/ 和 .sdd/runs/<run-id>/。
3. 写入 run.json、events.jsonl 和五节点占位 artifacts。
4. 添加 Gate 记录、EvidenceRef 和 traceability skeleton。