graphlemon_architecture.md 47.1 KB

Edit Raw Blame History


graphlemon 架构对齐文档
版本: v0.11（第 7.2 节决策：MVP 阶段只用 Claude Code ACP 一种执行后端，不考虑 Hermes CLI，Org Agent 落地为 Claude Code subagent 定义；第 10.1 节方案 A 可行性已通过 spike 实测确认；此前决策点见第 8 / 9 / 10.1 / 12.1 / 13.1 节）
日期: 2026-07-29
定位: 本文档用于对齐 Org Graph / Work Graph 双层架构的概念模型、边界与机制，作为后续 PRD / SDD / 任务拆解的上游依据。不含具体排期与代码级设计。


1. 项目目标
做一个软件项目的"黑灯工厂"（Lights-Out Software Factory）：给定一个目标（Goal），系统 7×24 小时自主完成规划、编码、验证、迭代的完整闭环，无需人工干预即可持续产出可用软件，并具备自我纠错、自我改进的能力（迭代到 skill / 流程本身，而不仅是迭代代码）。

自主性对应 Anthropic/行业常用的 Agent 自主性分级（Level 5 = 完全自主运行，人类只设定目标和护栏，不参与执行环节）。这意味着系统需要具备：


目标到任务的自主分解能力（Planning）
任务到产出的自主执行能力（Coding）
产出到质量判定的自主验证能力（Validate / Benchmark / Test）
失败到根因到改进的自主学习能力（Iterate，包括改代码，也包括改 skill / 流程本身）

2. 核心概念与术语


术语
定义


Org Graph（Organizer Graph）
固定的、由人预先设计的顶层多 Agent 主流程图。节点是"角色"（Planner / Coder / Validator），边是角色间的移交（handoff）与回退（loop-back）关系。一个 Org Graph 定义一类"工厂"（如 Dev Organizer）。等价于业界"Graph Engineering"语境下的角色图（role graph）——谁有权做什么、权限边界如何划分，必须慢变、可审计，不允许模型运行时自主调整（见下方"术语对照"）。


Work Graph
Org Graph 中某个节点 Agent 接到任务后，动态规划并生成的执行图。节点是"subagent + skill 的一次执行"，边支持串行、并行 fan-out/fan-in、循环（loop）。每次任务执行都重新规划、重新生成，不复用上一次的图实例（但可以复用/学习历史图的经验）。等价于业界"Graph Engineering"语境下的工作图（work graph）——任务怎么拆、怎么合可以现场灵活调整，允许快变（见下方"术语对照"）。


Org Agent
Org Graph 上的固定节点角色，例如 Planner Agent、Coder Agent、Validator Agent。每个 Org Agent 拥有一个"Planning Skill"，用于在接到任务时生成自己的 Work Graph。


Work Node
Work Graph 中的最小执行单元 = 一个 Subagent 实例 + 它调用的一个（或一组）Skill + 明确的输入/输出契约。


Skill
可复用的能力单元（提示词模板 + 工具集 + 产出规范），是 Work Node 执行任务时调用的"方法"。Skill 本身也是可被迭代的对象。


Fan-out / Fan-in
任务分解为多个并行子任务分派给多个 Subagent（fan-out），执行完成后合并/裁决为单一结果（fan-in）。


Reflection
Work Node 或调度子 Agent 在执行受阻/产出低质时，对已有产出与目标的差距进行自我评估并决定重试/改路径/升级人工介入的动作。


Supervisor（调度子 Agent）
存在于部分 Work Graph 中（当前明确用于 Coder 的 Work Graph），负责监控其余 Work Node 的运行状态、发现卡点、触发 reflection 或重新调度，直至该层任务完成。


Artifact
Work Graph 执行过程中产出的结构化产物，如 BRD、PRD、SDD、代码、测试报告、bug list。是节点间"共享结果数据"的载体。


Bug / Issue 溯源
Validator 发现问题后，向上追溯问题源头属于 Planning 阶段的哪个环节，还是 Coder 阶段的哪个环节，并进一步判断是"这次执行的偶发失误"还是"Skill 本身存在缺陷"。


Org-level Loop
Org Graph 层面的回退边：Validator → Planner，把验证阶段发现的问题作为新任务反馈给 Planner，驱动下一轮 Org Graph 循环。


术语对照（2026-08-05 补充）：《Loop Engineering 就凉了？一文看懂 Graph Engineering 的"新范式"》（docs/reference/graph-engineering-vs-loop-engineering-overview.md）提出一条治理红线——"工作图"（任务怎么拆怎么合，可以快变）vs "角色图"（谁有权改数据库、谁能绕过审批，必须慢变、可审计）。这条红线跟本文档 Org Graph（人工固定设计，架构变更需人工评审，见下方"关键设计原则 1"）/ Work Graph（每次任务动态生成，见"关键设计原则 2"）的边界是同一件事的两种命名：Org Graph ≡ 角色图，Work Graph ≡ 工作图——不是新概念，只是行业已经给这条边界起了名字。对照笔记见 docs/reference/graph-engineering-vs-loop-engineering-overview.diff-with-graphlemon.md §5。
3. 整体架构：两层图
┌─────────────────────────────────────────────────────────────┐
│                        Org Graph（固定）                      │
│                                                                │
│   ┌───────────┐      ┌───────────┐      ┌───────────┐        │
│   │  Planner   │ ───▶ │   Coder    │ ───▶ │ Validator  │        │
│   │   Agent    │      │   Agent    │      │   Agent    │        │
│   └───────────┘      └───────────┘      └─────┬─────┘        │
│         ▲                                       │              │
│         └───────────── bug / 迭代任务 ───────────┘              │
└─────────────────────────────────────────────────────────────┘
        │ 接到任务后各自触发            │                │
        ▼                              ▼                ▼
┌───────────────┐            ┌───────────────┐  ┌───────────────┐
│ Planner 的      │            │  Coder 的       │  │ Validator 的    │
│ Work Graph      │            │  Work Graph     │  │ Work Graph      │
│ (动态生成)       │            │  (动态生成)      │  │ (动态生成)       │
│ BRD→PRD→SDD     │            │ to-do 拆解→      │  │ validate/test/  │
│ →Benchmark      │            │ 编码→reflection  │  │ benchmark→      │
│ (含 fan-out)     │            │ (含 supervisor)  │  │ 根因溯源→bug记录 │
└───────────────┘            └───────────────┘  └───────────────┘


关键设计原则：


Org Graph 结构人工定义、代码级固定，改动 Org Graph 本身属于"架构变更"，需要人工评审，不由系统自主修改。
Work Graph 每次任务全新规划生成，不假设可复用上次的图结构，但规划过程可以参考历史 Work Graph 执行记录（作为 few-shot 或经验库输入）以提升规划质量。
两层图都是图（不是线性流程），因此都需要统一的图执行语义：节点状态机、边的条件、fan-out/fan-in 的合并策略、loop 的终止条件。
Org Agent 与 Work Node 中的 Subagent 复用同一套底层执行能力，区别只在于"图的层级"和"节点的职责范围"。

4. Org Graph 层设计（Dev Organizer 实例）
MVP 范围内的 Org Graph 固定为三节点：Planner → Coder → Validator，以及一条回退边 Validator → Planner。
4.1 节点职责与边界


节点
输入
输出
职责边界


Planner Agent
Goal（自然语言目标）或 Validator 回传的 bug/迭代任务
BRD、PRD、SDD、Benchmark & 测试用例集
只负责"定义要做什么、做到什么标准"，不写实现代码，不做验证执行。


Coder Agent
Planner 产出的 BRD/PRD/SDD
代码变更（commit/PR）、单元测试、Coder 自测报告
只负责"按规格实现并做第一层自测（reflection + 基础 test）"，不负责最终验收判定，不负责重新定义需求。


Validator Agent
Coder 产出的代码 + Planner 产出的 Benchmark/测试用例 + SDD/PRD
验收结论（通过/不通过）、bug list（含根因归属）、必要时的 Skill 迭代建议
只负责"判定是否达标 + 定位问题归属"，不直接改代码、不直接改需求文档，而是把问题结构化后交回 Org Graph 循环。


4.2 节点间数据契约（Artifact 规范）
为了让三个节点能"共享结果数据"，需要为每种 Artifact 定义 schema，至少包括：


BRD：目标、背景、成功标准（可衡量）
PRD：功能范围、用户场景、边界条件（做什么/不做什么）
SDD：架构方案、模块划分、接口约定、技术选型理由
Benchmark & 测试用例集：可执行的验收标准（不是文字描述，是可跑的测试/评测脚本或数据集）
Bug/Issue 记录：问题描述、复现步骤、根因归属（Planning 阶段 / Coder 阶段 / Skill 缺陷）、关联的原始 Artifact 版本


这些 Artifact 需要有版本和血缘关系（例如：本次代码是基于哪个版本的 SDD 写的，本次 bug 是针对哪个版本的代码和哪个版本的测试用例）。这是 Validator 做根因溯源的前提。
4.3 Org-level Loop（顶层回退机制）
Validator 完成一轮验证后：


若通过 → 本轮任务结束，等待/接收下一个外部 Goal。
若不通过 → 生成结构化 bug 任务，回传给 Planner。Planner 接到后需要判断：


这是需求理解错误（PRD/SDD 需要修订）→ 走完整的 Planner Work Graph 修订相关 Artifact。
这是纯实现错误、需求本身没问题 → 快速通道（已确认，见 8.2）：Org Graph 固定存在一条 Validator → Coder 的条件边，由 Validator 在 bug 记录中标注 route: fast_lane | full_replan 决定走向，Coder 直接消费 bug 记录中的修复指引，不需要 Planner 重新生成完整 BRD/PRD/SDD。

循环终止条件（已确认，见 8.3）：同一任务的 Org-level Loop 最多 3 轮。第 3 轮仍未收敛 → 该任务标记为 blocked_pending_human，触发人工升级通知，同时 Org Graph 调度器跳过该任务，优先执行队列中其他可并行的任务，不阻塞整体产出。

5. Work Graph 层：动态生成与执行机制
每个 Org Agent 拥有一个 Planning Skill，在接到任务时先生成本轮的 Work Graph，再按图执行。Work Graph 的生成本身也是一次 Agent 调用（用规划能力"画图"），产出应是结构化的图描述（节点、边、节点的 skill 绑定、fan-out/fan-in 策略、合并/验证规则），而不是自然语言计划。
5.1 Work Graph 的图元素

串行边：B 节点必须等 A 节点产出特定 Artifact 后才能开始。
Fan-out：一个节点的产出被拆解为多个独立子任务，分派给多个 Subagent 并行执行（各自可能调用不同 skill）。
Fan-in：多个并行分支的产出需要被合并/裁决为单一权威结果，需要定义合并策略（例如：加权综合、冲突时用哪个 Subagent 仲裁、或再起一个"合并 Agent"）。
Loop：节点或子图在未达标时重复执行，需要定义重试上限和"未达标"的判定条件。

5.2 Work Node 的构成
每个 Work Node = 1 个 Subagent + 1 个（或按需组合）Skill + 输入契约 + 输出契约 + 该节点自身的验证规则（"这个节点怎么算做完/做对了"）。
5.3 规划 → 执行 → 验证 → 交付 的通用生命周期
无论是 Planner、Coder 还是 Validator 的 Work Graph，都遵循同一个通用生命周期，这也是需要在 Graph Engine 中抽象出的公共能力：


Plan：Org Agent 调用 Planning Skill，结合任务输入和历史经验，生成 Work Graph 定义（节点、边、fan-out/fan-in、验证规则）。
Execute：Graph Engine 按依赖关系调度 Work Node 执行，支持并行、支持节点内 reflection 重试。
Merge/Verify：fan-in 节点合并结果；每个关键节点/整图完成后有一个验证步骤，判定"这个 Org Agent 的任务是否算完成"。
Handoff：验证通过后，将最终 Artifact 交付给 Org Graph，触发下一个 Org 节点。若验证不通过且重试耗尽，升级（reflection 升级为 Org 级别的异常，可能触发人工介入护栏）。

6. 三个 Org 节点的 Work Graph 详细设计
6.1 Planner 的 Work Graph
输入：Goal（或 Validator 回传的 bug 任务）
产出：BRD → PRD → SDD → Benchmark & 测试用例集


串行主干：BRD → PRD → SDD → Benchmark/测试用例（后者依赖前者的确定版本）。
Fan-out 候选点：


PRD 阶段：若目标涉及多个功能模块/多个用户场景，可 fan-out 让多个 Subagent 分别撰写各场景的 PRD 片段，再 fan-in 合并为完整 PRD，并做一致性检查（是否有相互矛盾的场景假设）。
SDD 阶段：若涉及多个技术方案候选（如"用状态机实现 vs 用简单二维数组实现贪吃蛇"），可 fan-out 生成多个方案由一个评审节点做技术选型裁决，再 fan-in。
Benchmark/测试用例阶段：功能测试、边界测试、性能 benchmark 可以分给不同 Subagent 并行生成，再 fan-in 汇总为统一测试集，并做覆盖率/冲突检查。

每一步的验证规则示例：BRD 是否包含可衡量的成功标准；PRD 是否覆盖 BRD 的每一条目标且无矛盾场景；SDD 是否对 PRD 每个功能点都有对应模块/接口；测试用例是否可执行、是否覆盖 PRD 的边界条件。
Planner Work Graph 整体完成的判定：四类 Artifact 齐备且通过各自的验证规则，且相互之间的引用关系（血缘）完整可追溯。
完成后，Planner Agent 将这一组 Artifact 交付给 Org Graph，触发 Coder 节点。

6.2 Coder 的 Work Graph
输入：BRD/PRD/SDD（+ 若是 bug 迭代任务，还包括 Validator 的 bug 记录）
产出：代码变更、单元测试、自测报告


Planning 阶段先生成 to-do list 并排序（依赖关系：哪些模块要先实现，哪些可以并行）。
每个 to-do 项对应一个或一组 Work Node，节点内部是一个"小闭环"：编码 → reflection（自我审查是否符合 SDD/PRD）→ 本地验证（unit test，必要时 integration test）→ 若不通过则在节点内重试，重试耗尽则标记为阻塞并上报。
Fan-out：相互无依赖的模块可并行分派给多个 Coder Subagent。
Supervisor（调度子 Agent）：是 Coder Work Graph 的常驻节点，职责是监控所有并行/串行 Work Node 的执行状态，发现卡点（例如某节点反复 reflection 失败、依赖阻塞）后介入——可以是重新调度、调整任务边界、或将问题升级为"需要 Planner 澄清需求"的信号（这是一个 Work Graph 内部节点触发 Org Graph 级别信号的例外通路，需要专门定义）。
Fan-in：各模块实现完成后，需要一个集成节点做整体 integration test，确认模块间接口按 SDD 约定对齐。
Coder Work Graph 完成判定：to-do list 全部完成，integration test 通过，自测报告生成。完成后交付给 Validator 节点。

6.3 Validator 的 Work Graph
输入：代码 + Benchmark/测试用例集 + PRD/SDD（用于溯源引用）
产出：验收结论、结构化 bug list（含根因归属）、必要时的 Skill 迭代建议


主干节点：执行功能测试 → 执行 benchmark → 汇总结果。可 fan-out（功能测试、性能 benchmark、边界/异常测试并行执行）。
根因溯源节点（核心机制）：出现失败项时，不止记录"哪里错了"，还要往上游追溯：


读取该功能点对应的 SDD/PRD/BRD 版本和 Coder 的实现记录（血缘追溯）。
判断失败属于哪一层：需求定义缺失/矛盾（Planning 问题）？规格清楚但实现不符（Coder 问题）？测试用例本身有误（Benchmark/测试用例问题）？
进一步判断是"这次执行的偶发失误"还是"背后的 Skill 存在系统性缺陷"（例如：某个 Skill 反复在同类任务上出现相同类型的问题，说明 Skill 的提示词/流程本身有缺口）。
若判定为 Skill 缺陷，生成 Skill 迭代建议（更新对应 Skill 的定义），确保"从根上解决问题，下次不再复现"，而不仅是修一次代码。

Bug list 结构化输出：问题描述、复现方式、根因归属（Planning / Coder / Skill）、关联 Artifact 版本、建议的处理路径（回给 Planner 修 PRD/SDD，还是直接给 Coder 修代码，还是先迭代 Skill 再重跑）。
Validator Work Graph 完成判定：所有测试/benchmark 项都有明确结论（通过或已归档为带根因的 bug），bug list 已结构化生成。完成后按 Org Graph 定义，将结果交付给 Org-level Loop（若不通过，回传给 Planner）。

7. 执行引擎与底层能力抽象
7.1 Graph Engine（自研）
由于两层图（Org Graph、Work Graph）共享同一套图执行语义，建议自研一个统一的 Graph Engine，核心能力包括：


图定义：节点、边、边的条件表达式、fan-out/fan-in 分组、loop 分组与终止条件。
状态机：每个节点具备 pending / running / reflecting / retrying / blocked / done / failed 等状态，图整体也有对应的聚合状态。
调度器：按依赖关系触发节点执行，支持并行节点的并发调度与资源限制（并发数、超时）。
Fan-in 合并策略：可插拔的合并/裁决逻辑（如仲裁 Agent、规则合并、投票）。
断点续跑与持久化：图执行状态、节点产出、图定义本身都需要持久化，支持从任意断点恢复（对 7×24 自主运行是硬需求，不能因为进程重启就丢失进度）。
可观测性钩子：每个节点的输入/输出/耗时/重试次数/reflection 记录都要可查询，这是 Validator 做根因溯源、也是人工审计"黑灯工厂"运行状况的基础。
Org 级别与 Work 级别复用同一套 Engine API，区别仅是节点内部绑定的执行体不同（Org 节点绑定 Org Agent，Work 节点绑定 Subagent+Skill）。

7.2 底层 Agent 执行器抽象层
节点的具体执行（调用 LLM、跑工具）需要通过一层执行器抽象（Executor Interface），Graph Engine 不直接绑定某个具体的底层 CLI/协议，而是面向接口编程。

执行后端范围（决策，2026-07-29，取代此前"双后端"框架）：MVP 阶段只实现并使用 Claude Code ACP（Agent Client Protocol）一种后端，不考虑 Hermes CLI 作为执行后端。此前设想的"Org Graph 层两后端一致、Work Graph 层两后端不对等"框架不再适用——不存在第二个后端,自然也不存在不对等问题。Executor Interface 的抽象层设计仍然保留(为未来接入其他 Agent 运行时留出扩展点),但 MVP 阶段只需要交付 Claude Code ACP 这一个实现,不需要再为"双后端一致性"做额外设计和测试。

Org Graph 层的具体落地方式：Planner/Coder/Validator 三个 Org Agent 直接实现为 Claude Code 的 project-scoped subagent 定义文件——目标项目仓库下的 .claude/agents/{planner,coder,validator}.md。这是 Claude Code 原生支持、每个 agent 独立配置的机制,完整覆盖 Hermes profile 原先的五个维度：


身份（对应 SOUL.md）：subagent 文件的 Markdown 正文就是系统提示词,是完全独立的人设定义(不叠加在主会话人设上)
memory：memory: project frontmatter 字段,对应目标项目 .claude/agent-memory/{planner,coder,validator}/,随项目 Git 历史版本化
skills：skills: 字段预加载技能全文,运行时还能通过 Skill 工具按需调用其他技能
tools：tools/disallowedTools 字段做精确白名单/黑名单,外加 mcpServers 字段挂载专属 MCP server
model（LLM 配置的一部分）：model 字段可按 agent 单独锁定,对应第 10 节"按节点分层选模型"；但供应商/API key 这部分不能做到 per-agent 独立——整个 Claude Code 进程共享同一份认证,这是和 Hermes profile"每个 agent 独立 LLM API config"的唯一差距点,MVP 阶段接受这个限制


触发方式：claude --agent planner -p "..."，让整个会话以该 agent 身份运行,语义上对应 Org Graph"三个固定角色"的设计,和 Work Graph 层已验证的 claude -p 调用方式（见第 10.1 节、A-1 spike）是同一套机制,c_org_node_trigger 的实现可以直接复用。
7.3 数据与产物存储（已确认，见 8.1 / 8.4）
Artifact、代码、Skill、Memory、Agent 人设文件全部纳入同一 Git 仓库管理，用目录区隔不同 Agent 的工作区和产物，所有变更都必须走 Git 提交（含系统自主变更），形成完整、可回滚的版本历史。参考目录结构：
graphlemon/
├── org/                    # Org Graph 定义（人工维护，变更需人工评审）
│   └── dev-organizer.graph.yaml
├── .claude/
│   ├── agents/              # 各 Org Agent 的 Claude Code subagent 定义（决策，2026-07-29，见 7.2 节）
│   │   ├── planner.md       # frontmatter: memory:project, skills:[...], tools:[...], model:...；正文迁移自 ~/.hermes/profiles/planning/SOUL.md
│   │   ├── coder.md         # 正文迁移自 ~/.hermes/profiles/code/SOUL.md
│   │   └── validator.md     # 正文迁移自 ~/.hermes/profiles/qa/SOUL.md + AGENTS.md（工作区权限契约折入 tools/disallowedTools）
│   ├── agent-memory/         # 各 Agent 的持久化 memory（memory:project 字段自动写入，随本仓库 Git 历史版本化）
│   │   ├── planner/
│   │   ├── coder/
│   │   └── validator/
│   └── workflows/            # Work Graph 执行层的动态工作流脚本（见第 10.1 节、03-C 3.5 节）
├── skills/                 # Skill 库（可被 Validator 触发的迭代改写，均走 git commit）
│   ├── write-brd/
│   ├── write-prd/
│   ├── write-sdd/
│   ├── write-benchmark/
│   ├── code-implement/
│   ├── code-reflect/
│   ├── run-test/
│   ├── run-benchmark/
│   └── root-cause-trace/
├── runs/                   # 每次任务的 Work Graph 执行记录与产物快照
│   └── <task_id>/
│       ├── brd.md / prd.md / sdd.md / benchmark/
│       ├── src/            # 本次任务对应的代码变更
│       ├── tests/
│       └── bugs/
└── src/                    # 项目主代码（最终交付代码的主干）


Skill 自主迭代（已确认，见 8.1）：允许系统在 Validator 判定 Skill 存在缺陷后自主改写对应 skills/* 目录下的定义并立即生效，但每次改动必须产生一次独立 Git 提交（commit message 需包含触发该次迭代的 bug/任务 ID），保证可追溯、可回滚。这是黑灯工厂自主性与风险控制的平衡点：不设人工审批卡点，但设"事后可审计、可一键回退"的安全网。
执行记录（Graph Engine 的节点状态转移、reflection 记录）建议独立于 Git 管理的 Artifact，用结构化存储（数据库/日志系统）承载，Git 只保留每个任务的最终产物快照（runs/<task_id>/），避免高频状态变更污染提交历史。

7.4 任务队列与并发调度（已确认，见 8.3 / 8.5）

系统需要维护一个任务队列而非单一任务指针：一个 Goal 分解出的多个可并行子任务、以及被 3 轮未收敛而"跳过"的任务，都需要作为队列中的独立条目被追踪，状态至少包括 queued / running / blocked_pending_human / done。
调度器在遇到 blocked_pending_human 的任务时不阻塞整体流水线，转而调度队列中其他 queued 且依赖已满足的任务继续执行。
多 Goal 并发（已确认，见 8.5）：架构上支持同时运行多个独立 Goal（多个 Org Graph 实例），并发数是一个可配置参数，在管理后台设置。MVP 阶段该参数默认设为 1（单任务串行），后续可直接调大，无需改架构。

7.5 预算与成本护栏（已确认，见 8.6）

护栏分两层：


平台层限额：依赖 Claude Code 自身的 coding plan 用量机制（5 小时滚动窗口 / 7 天窗口 / Opus 专属限额），执行器抽象层需要能识别额度耗尽的信号并向上传递。这一层的处理方式不是"暂停等人工"，而是"等待+自动重试"（决策，2026-07-29，详见 03-C 3.6/3.5 节、04-P）：Claude Code plan 额度是一个会在固定时间窗口后自然恢复的资源，属于自愈型阻塞，不应该占用人工介入的通道；只有等待超过合理上限仍未恢复时才升级为人工介入，防止真正的账单/账号问题被无限期静默等待掩盖。
手工配置层：管理后台允许人工设置额外的预算/额度上限（如按任务、按天、按 Goal 设置 token 或调用次数上限），超出后自动暂停对应任务并通知人工，行为与 Org-level Loop 的 blocked_pending_human 一致，复用同一套人工升级通知机制。这一层和上面的"平台层限额"是两回事：手工配置层是主动的预算控制（超限就该停下来问人），平台层限额是被动的资源约束（等它自己恢复就行），不能用同一套处理逻辑。


8. 已确认的架构决策
以下问题已与用户对齐，作为后续 PRD/SDD 的既定前提：


Skill 自主迭代边界（已确认）：允许系统自主改写 Skill 定义并立即生效，前提是所有变更（Skill、代码、Work Graph 产物、Memory、SOUL.md/AGENTS.md 等人设与运行契约文件）都必须通过 Git 提交留痕，形成完整版本记录，可追溯、可回滚。详见 7.3。
Org Graph 快速通道（已确认）：允许存在 Validator → Coder 的快速通道，由 Validator 在 bug 记录中判断并标注是否为"纯实现问题"从而决定是否绕过 Planner 的完整重新规划。详见 4.3。
循环终止与人工升级（已确认）：轮次上限设为 3 轮，超过未收敛则标记 blocked_pending_human、通知人工介入，同时调度器跳过该任务、优先执行队列中其他可并行任务。详见 4.3 / 7.4。
Artifact 与代码同仓库管理（已确认）：BRD/PRD/SDD/bug list 等 Artifact 与代码纳入同一 Git 仓库，用目录区隔不同 Agent 的工作区和产物。详见 7.3 的目录结构。
多任务并发（已确认）：架构支持多 Goal 并发运行，MVP 阶段并发数参数设为 1，可在管理后台调整。详见 7.4。
预算/额度护栏（已确认）：结合 Claude Code 自身的 plan 额度限制（等待+自动重试，非人工介入），以及管理后台的手工配置上限（主动预算控制，超限转人工介入），双层护栏，两层处理逻辑不同。详见 7.5。
Skill 库初始范围（已调研，方案见第 9 节）：MVP 只做开发全流程的 Dev Organizer（Planner / Coder / Validator 三个 Org Agent）。已读取本地 Hermes profile（~/.hermes/profiles/{code,planning,qa}），三者已针对同一条"飞书 Base 驱动的软件研发流水线"做了扎实的角色分工与人设定制，可作为人设与方法论蓝本直接复用；但其任务队列/状态机强耦合飞书多维表格 + lark-cli，且是"轮询认领任务"模式而非"动态生成 Work Graph 执行"模式，需要改造。具体映射和缺口见第 9 节。

9. 现有 Hermes Profile 复用与改造方案
对 ~/.hermes/profiles/{code, planning, qa} 的调研结论：三个 profile 不是换名字的同一个通用助理，而是已经围绕"飞书 Base 驱动的软件研发流水线"做了具体的角色分工，人设文件为 SOUL.md（qa 另有 AGENTS.md 补充运行契约），可直接作为 Planner/Coder/Validator 的人设与方法论蓝本。
9.1 角色映射与可直接复用的资产


Org Agent
对应本地 Profile
可复用人设
可复用 Skill（举例）
与本文档章节的对应关系


Planner
planning
SOUL.md：16 条根本原则（先调查后规划、事实/决策/假设分层、纵向拆分、依赖显式无环、失败关闭、动态 Runtime Graph 等），明确"不写业务代码"
planning-requirement-expansion（主方法）、project-brd-planning、project-prd-planning、project-sdd-planning、project-unit-decomposition、sdd-automation-runtime、sdd-generation-audit-hardening、review-blocker-verification 等约 20 个规划子技能
直接对应第 6.1 节 BRD→PRD→SDD→测试用例四步串行主干，比本文档原先设想的"从零设计"更成熟，project-unit-decomposition 可直接用作 fan-out 拆分依据


Coder
code
SOUL.md：单任务开发主流程人设——每轮认领一条需求叶子任务或 Bug，唯一事实源、写单测、证据回写描述，禁止跳过测试或自称 QA 通过
code-task-development（主方法：认领→实现→测单→证据回写）、code-agent-engineering、debugging-toolkit、software-planning-execution
对应第 6.2 节的 to-do 闭环（编码→reflection→本地验证），"证据回写"机制可直接作为 Coder Work Graph 每个节点的验证规则


Validator
qa
SOUL.md：独立、真实、可复核的验收者，只出 PASS/FAIL/INCONCLUSIVE 三态，Dev 证据只是线索必须独立复核；AGENTS.md：工作区权限契约（doc/ 只读、source/ 只读审计+执行测试）
qa-task-validation（主方法：风险驱动测试、双向可追溯矩阵、严格放行门）、unattended-agent-operations、software-quality
双向可追溯矩阵机制正好对应第 6.3 节的根因溯源节点，可直接复用作为 Validator 判定"Planning/Coder/Skill 归属"的方法论基础


三个 profile 目前共享的记忆结构（memories/MEMORY.md + USER.md，sessions/ 存原始请求日志）内容有重叠、未按角色隔离，不建议直接复用，需按第 7.3 节的 memory/{planner,coder,validator}/ 目录重新组织。

三个 profile 的 skills/ 顶层还挂载着大量与开发流程无关的通用/归档技能（.archive/、migration/、openclaw-imports/ 以及 apple、creative、feishu-lark、social-media 等个人助理类技能），不纳入 graphlemon，避免噪音。
9.2 需要改造的三个缺口

任务队列/状态机迁移（已确认，见 12.1）：现有机制强耦合"飞书多维表格 + lark-cli --as user"作为需求表/Bug 表和任务认领的唯一事实源。已确认完全替换为 Graph Engine 自研持久化（Git + 结构化存储，见 7.3/7.4 节），不再依赖飞书 Base，迁移时需要另做管理后台承载原来飞书 Base 提供的人工可视化能力。
从"轮询认领"改造为"图执行"：现有模式是"每轮 cron 认领一条任务"的轮询循环，SOUL.md 里虽提到"动态执行图"（Runtime Graph）但目前只是文字描述的原则，没有第 7.1 节所需的可执行 Graph/Node 结构化定义（节点、边、fan-out/fan-in、验证规则）。需要把这些 prose 原则转译为结构化 Work Graph 模板。
Skill 打包与去噪：需要把上表列出的专属 skill 从各 profile 中单独抽取，迁移到第 7.3 节定义的 graphlemon/skills/ 目录下，剥离掉归档/迁移/通用助理技能。

10. 对照《Graph Engineering with Claude: 14-Step roadmap》课程的映射与启发
用户提供的这份课程讲的是 Claude Code 原生的"动态工作流"（dynamic workflows）能力：Claude 把任务编排写成一段普通 JavaScript 脚本（agent() / parallel() / pipeline() 等原语），再生成一批子智能体去执行这段脚本，编排本身不消耗 token，因为它是代码，不是对话。这与我们对 Work Graph 的设想（动态生成、串行/并行/循环、节点=subagent+skill）高度同构，课程给出的是更具体、已经落地验证过的工程细节。逐条对照如下：


#
课程技法
一句话要点
对 graphlemon 的启发


1
Nodes are jobs, edges are what flows
边只在数据真正流动时存在，"然后"不等于边
检查我们 Planner/Coder/Validator 的 Work Graph 里是否有"顺序上的然后"被误画成边——真正的边必须是下一节点读取上一节点的输出


2
线性脚本是退化的图
对每条箭头问"下一步是否读取上一步的输出"，能拆的链要拆宽
重新审视 6.1 节 BRD→PRD→SDD→Benchmark 这条串行主干，看是否有环节其实互不依赖、可以拆成并行节点


3
给每个节点一个契约
有界输入、有界输出、恰好一个任务；用 JSON schema 强制校验，校验失败在工具调用层自动重试
直接补强第 5.2 节 Work Node 的"输入/输出契约"：应落到具体的 schema 校验机制，而不只是文字约定，这也是 4.2 节 Artifact schema 的落地方式


4
边是数据契约，且零 token
简单的合并/去重/过滤是纯代码，不该派生一个 Agent 去做
重要修正：我们 6.1/6.3 节设想的一些 fan-in 合并节点（PRD 片段合并、测试用例汇总）未必都需要"一个 Agent 仲裁"，简单聚合应该是确定性代码边，只有真正需要判断力的合并才值得用 Agent


5
Fan-out 用 parallel()
是一个屏障；单个 thunk 失败 resolve 为 null 而不拖垮整批
呼应第 7.1 节需要的"节点失败隔离"机制，.filter(Boolean) 式的失败降级可以直接作为 Graph Engine 的默认行为


6
Fan-in 在屏障处
仅当某阶段真正需要全部结果时才用屏障
给第 5.1 节的 Fan-in 补充一条明确判断标准，避免不必要的屏障拖慢 Work Graph


7
菱形拓扑：split → work → merge
fan out → reduce(代码) → synthesize(Agent) 是标准形状
这正是我们 Planner/Coder/Validator 三者 Work Graph 里反复出现的模式，可以直接把"菱形"作为我们 Work Graph 模板的标准命名


8
条件路由：判断用 Agent，路由用代码
分类交给智能体，走哪条边由确定性代码决定
我们的"快速通道"机制（Validator 打 fast_lane/full_replan 标签，Org Graph 用代码路由）已经隐含这个原则，应在文档里显式化


9
Edge 上挂 verifier：对抗式 / 多视角 / 评审团
三种具体的验证模式，比"验证"两个字可操作得多
直接可用于 6.3 节 Validator 的根因溯源节点：多视角差异化校验（正确性/安全/可复现性）与我们"判断问题属于 Planning/Coder/Skill 哪一层"是同构的，可以把归因判断设计成一次多视角校验


10
节点隔离：git worktree
并行写文件的 Agent 用独立 git worktree 避免互相踩踏，再干净合并
6.2 节 Coder Work Graph 的遗漏点：多个 Coder Subagent 并行改代码时需要 worktree 隔离，这也和我们 8.1 节"一切走 Git 提交"的决策直接衔接


11
循环要收敛：loop-until-dry
连续 K 轮无新发现才停止；去重要对比"全部见过的"而非"已确认的"
对 4.3 节"3 轮上限"是一个有价值的补充方案：像 Validator 做"未知规模缺陷扫描"这类任务，用 loop-until-dry 比固定轮次更合理，值得作为新的开放点


12
按节点分层选模型
有界重复的节点用便宜模型，综合/裁决节点用贵模型
应补进第 7.5 节预算护栏：Graph Engine 的 agent() 级别调用要支持按节点指定模型，这是控制成本的关键杠杆


13
拓扑即成本延迟：pipeline() 优先于 parallel()
默认流式无屏障，只有真正需要全量结果时才上屏障
补强第 7.1 节 Graph Engine 核心能力：明确区分"屏障并行"和"流式并行"两种原语，而不是笼统的"并行"


14
让 Claude 自己画图：动态工作流 / self-routing
描述目标，Claude 自己生成编排脚本；可保存为 .claude/workflows/ 里版本化、按名复用的脚本
对第 7.1 节"自研 Graph Engine"决策的重大启发，见下方新开放问题


10.1 关键决策：Work Graph 执行层复用 Claude Code 原生动态工作流（已确认）
第 14 条技法说明一个重要事实：Claude Code 本身已经内置了一套 node/edge/state 的图执行机制（agent()/parallel()/pipeline() 原语、schema 契约、条件路由、edge 上挂 verifier、loop-until-dry、按节点分层模型、.claude/workflows/ 版本化脚本），这套东西和我们设想的"Org Agent 先 Planning 再生成 Work Graph 再执行"的核心机制高度重合，而且已经是 Claude Code 里可用的产品能力，不需要从零建。

已确认：方案 A——Work Graph 执行层直接复用 Claude Code 原生动态工作流（仅限 Claude Code ACP 后端）。graphlemon 自己的 Graph Engine 只负责 Org Graph 层的编排、跨 Org Agent 的持久化任务队列（第 7.4 节）、Git 版本化的 Skill 库（第 7.3 节）、7×24 断点恢复。Work Graph 内部的 fan-out/fan-in/loop/verifier 直接用 Claude Code 写的 JS 编排脚本执行，直接拿到"零 token 编排""按节点分层模型"等现成优化，开发量显著小于完全自研。

由此产生的架构含义（已落到第 7.2 节执行器抽象层的设计里）：最初设想这一段是在讨论"两个后端在 Work Graph 层不对等"，但 2026-07-29 已决策 MVP 阶段只用 Claude Code ACP 一种后端（见 7.2 节），这个问题不再存在——Work Graph 的执行体就是 Claude Code 原生的 agent()/parallel()/pipeline() 编排脚本，Org Graph 层的执行体是 Claude Code 的 subagent 机制（.claude/agents/*.md），两层都在同一个后端上，不需要处理跨后端一致性问题。Executor Interface 的抽象设计仍然保留，是为未来扩展留的口子，不是当前要解决的问题。

第 10 节表格里那些具体设计准则（数据契约用 schema、简单聚合用零 token 代码边、菱形拓扑、loop-until-dry、按节点分层模型、pipeline 优先于 parallel、worktree 隔离并行写入）在方案 A 下大部分会直接由 Claude Code 的动态工作流原生提供，我们只需要在 Planning Skill 生成编排脚本时遵循这些准则即可，不需要自己实现底层机制。

方案 A 的可行性已通过实测确认（2026-07-29）：agent()/pipeline() 编排脚本可通过 claude -p（非交互式）调用，无人值守完成、返回结构化可解析结果，验证了本节决策的前提成立。详见 spikes/a1-dynamic-workflows/ 与 SDD 03-C-控制与接口.md 3.5 节的具体实现契约。
11. MVP 范围建议

Org Graph：Planner → Coder → Validator 三节点 + Validator → Planner 回退边，固定实现。
场景：以"贪吃蛇游戏"一类边界清晰、无外部依赖的小型任务作为打通全链路的验收场景。
验收标准：


Planner 能自主产出结构化的 BRD/PRD/SDD/测试用例集，且四类 Artifact 通过一致性/覆盖率校验。
Coder 能依据 SDD 自主完成编码，通过 Coder 自测（unit + integration test）。
Validator 能自主运行 Benchmark/测试用例，对不通过项完成根因归属（Planning/Coder/Skill 三类之一），生成结构化 bug list。
完整跑通至少一次 Org-level Loop（引入一个人为植入的 bug，验证系统能自主定位根因并驱动 Planner/Coder 完成修复闭环）。
Graph Engine 支持断点恢复：在执行中途中断进程后，能从持久化状态恢复继续执行。
执行器抽象层验证 Claude Code ACP 后端可用（MVP 阶段唯一后端，见 7.2 节 2026-07-29 决策），接口设计上预留未来接入其他底层引擎的能力，但不要求 MVP 阶段实现第二个后端。
Claude Code plan 额度耗尽时，系统能自动等待并重试，不误判为需要人工介入的错误（见 7.5 节、03-C 3.6 节）。


12. 补充确认的决策
12.1 飞书 Base / lark-cli 任务队列的去留（已确认）
本地 Hermes profile 现有的 code/planning/qa 三个 Agent 都以飞书多维表格为需求表/Bug 表的唯一事实源，用 lark-cli --as user 认领和回写任务状态。已确认：完全替换为 Graph Engine 自研持久化，不再依赖飞书 Base，任务队列、状态机、bug list 全部落在 Git 仓库 + 结构化存储（第 7.3/7.4 节）。原来飞书 Base 提供的人工可视化看板能力，需要在管理后台（第 8.5 节已提到的并发数配置界面）里一并补齐，作为后续 PRD 的一个明确子需求。
13. 人机交互控制台（Admin Console / Control Plane）
之前第 8.5 节把这块简化成了"管理后台设置并发数"，实际需求比这大得多：需要一个真正给人用的控制台，管理系统涉及的全部功能/数据/流程/图，提供实时看板看到任务动态运行过程，并且让人能选文件夹建项目、发起任务、反馈 bug、提出目标、检查执行过程。这是黑灯工厂的"驾驶舱"，不是一个可有可无的配置页面，值得作为与 Org Graph Engine、Work Graph Engine、Skill/Artifact 存储并列的第四个核心子系统。
13.1 关键决策（已确认）

目标项目是独立代码空间：graphlemon 从"只服务自己开发自己"升级为通用工厂平台——人选择一个本地文件夹（新建或已有 Git 仓库）作为"目标项目"，Planner/Coder/Validator 在这个目标项目里工作，产出的代码直接落在该文件夹本身。graphlemon 平台自己的仓库只保留平台资产：Org/Work Graph 引擎、Skill 库、Agent 人设（agents/、skills/，见 7.3 节），不含任何目标项目的业务代码。
MVP 只需单个目标项目：数据模型里引入 project 实体（为将来多项目预留），但 MVP 阶段管理后台不需要做"项目列表/切换"这层完整交互，用户选一次文件夹跑起来即可，精力优先投入实时看板和人机交互本身。
实时看板用 WebSocket 推送：节点状态变化、Artifact 产出、bug 记录、Org-level Loop 路由决策、预算用量更新都需要真正的推送，不是轮询刷新。
原始执行日志在控制台内直接可看，本地落盘 + 定时清理（已确认，修正原方案）：原先设想的"日志不重复存储、深链回底层引擎会话记录"已被推翻。改为：Work Node 执行时的完整会话日志实时落盘到 graphlemon 平台自己的本地日志文件夹（不纳入 Git、不与目标项目仓库混在一起，因为需要定期清理），控制台可直接查看（运行中的节点支持实时滚动查看，已完成的节点支持静态查看），并提供可配置的保留天数，到期自动清理。
控制台载体形态：本地 Web 应用 + 本地后端代拉系统对话框（已确认）：控制台前端是普通网页，不做 Electron/Tauri 桌面应用。"选择文件夹"这类需要真实系统路径的操作，由本机常驻的后端进程（本来就要跑 git/执行器调用）代为拉起 OS 原生文件夹选择对话框（macOS 用 osascript、Windows/Linux 用对应平台的原生方案），把选中的绝对路径返回给前端，不依赖浏览器 File System Access API（该 API 在 Safari/Firefox 不支持，且拿到的是沙箱化的文件句柄而非可直接给后端 git init/agent() 调用使用的真实路径）。

13.2 目标项目内的目录约定
为了让目标项目的代码和 graphlemon 生成的规划类产物（BRD/PRD/SDD/Benchmark/Bug 记录）都能随目标项目自身的 Git 历史一起演进（呼应第 8 节决策 1"一切纳入 Git 版本化"），目标项目文件夹内新增一个隐藏子目录：
<目标项目文件夹>/
├── .git/
├── .graphlemon/              # graphlemon 在该项目内生成的规划类产物，随项目自身仓库一起提交
│   └── runs/<task_id>/
│       ├── brd.md / prd.md / sdd.md / benchmark/
│       └── bugs/
├── src/                       # 目标项目自己的正常源码目录（graphlemon 不规定具体结构，尊重目标项目原有约定）
└── ...（目标项目原有的其他文件）


graphlemon 平台自己的持久化（task/work_graph_run/work_node_execution/execution_event 等运行时状态，见后续 SDD）仍然是独立于目标项目 Git 历史的结构化存储，只是其中的字段会指向 project.target_folder_path 下的具体文件路径。

原始执行日志的存放位置（第 13.1 节决策 4）：与上面两类都不同，Work Node 执行时的原始会话日志既不进目标项目的 Git 仓库（会污染项目提交历史），也不进 graphlemon 平台仓库（体量大、需要定期清理，不适合 Git 版本化管理）。落在 graphlemon 平台自己的本地日志目录（如 ~/.graphlemon/logs/<project_id>/<task_id>/<run_id>/<node_exec_id>.jsonl），由独立的保留策略（可配置天数）定时清理，与 Git 版本化的 Artifact/Skill/Agent 人设是两套不同生命周期的存储。
13.3 控制台核心能力（对应用户提出的诉求逐条落实）


用户诉求
落地方式


选择文件夹、创建项目
项目创建页：本地文件夹选择器 + 校验（是否已是 Git 仓库，不是则询问是否初始化）→ 写入 project 实体


开始任务 / 提出目标
目标提出入口：表单输入 Goal 描述，直接调用创建任务的接口，进入 Org Graph


反馈 bug
独立于 Validator 自动生成的人工 bug 提交入口，产出的 bug 记录带 source=human 标记，进入 Validator 做归因确认后再路由


实时看板，看到动态任务运行过程
WebSocket 推送的 Org Graph 三节点实时状态 + Work Graph 节点级图可视化（按状态着色，随执行实时刷新）


检查过程
深入到单个 Work Node 的输入/输出契约、reflection 记录、重试次数、原始执行会话日志（本地落盘，控制台内直接查看，运行中实时滚动、已完成静态查看，定期清理不长期占用磁盘）


管理所有功能/数据/流程/图
Artifact 浏览器（按项目/任务筛选查看 BRD/PRD/SDD/代码/测试报告/bug）、Skill 库浏览与审计、Org/Work Graph 结构可视化


具体的页面清单、字段、接口、实时事件契约在 SDD 的 02-V-界面与交互.md、03-C-控制与接口.md 中细化（本次讨论后已同步更新）。


本文档为讨论稿，尚未包含具体的接口定义、数据 schema 字段级设计和排期计划，待架构方向对齐后再展开细化。