宜博 / lemongraph

planning-runtime-graph.md 14.8 KB

Planning Runtime Graph 规范

1. 目的和边界

本规范定义 Planning Agent 如何把一次需求规划运行实例化为带依赖、并发、Barrier、质量门和失败路径的执行图。

需要区分两张图：

  1. Planning Runtime Graph：Planning Agent 调查、综合、拆分、审核和写入需求的执行图；
  2. Development Unit DAG：规划通过后，下游 Code Agent 实现 Development Units 的依赖图。

前者产出后者。不得把“Planning 内部并行调查”当成“Development Units 可并行开发”的证据。

当前 Hermes 没有由本 skill 自动创建的通用 DAG 引擎。本规范是主 Planning Agent 每轮必须执行的编排契约；短时节点可映射到 delegate_task，持久跨会话工作可映射到 Hermes Kanban。

2. 控制权

主 Planning Agent 是唯一 Graph Owner，负责：

  • 选择和认领唯一规划对象；
  • 生成和修订 Graph Manifest；
  • 事实分级、冲突仲裁和业务未知判断；
  • 关键方案、Unit 边界和依赖的最终决定；
  • 所有 Base 写操作和状态流转；
  • Barrier 汇合、质量门和最终成功声明。

Sub-agent 是 Node Executor，只负责边界明确的调查、分析、草拟或审核节点。它不得：

  • 自行扩大范围或改变原始需求；
  • 把建议写成事实或业务规则；
  • 认领、修改 Base、创建子任务或流转状态；
  • 直接决定 Planning 通过；
  • 假设自己拥有父会话历史、memory 或用户交互能力。

3. Graph Manifest

认领后、首次并行 fan-out 前，主 Agent 应在当前运行上下文中建立紧凑 Manifest：

graph_id: planning:<object-type>:<record-id>:<attempt>
object:
  type: requirement | bug
  id: <record-id>
  source_revision: <known revision or fetched-at marker>
mode: inline | durable
risk: low | medium | high | critical
features:
  external_integration: true|false
  data_migration: true|false
  security_privacy: true|false
  nonfunctional_risk: true|false
  cross_repo: true|false
  technical_unknown: true|false
nodes: [...]
edges: [...]
barriers: [...]
revision_cycle: 0

Manifest 是运行控制信息，不等同于用户需求正文，不机械写入 Base。若需求事实或范围发生实质变化，必须使依赖旧基线的节点结果失效并重新编译受影响子图。

4. Node Contract

每个动态节点至少包含：

id: F_REPO
kind: investigation | synthesis | decision | planning | audit | write | verify
purpose: <一个主要结果>
condition: <何时加入 Graph>
depends_on: [F_BASE]
executor: main | leaf-subagent | kanban-profile
skills: [planning-requirement-expansion, ...]
permissions: read-only | local-artifact-write | base-write
read_set: [records, docs, repo]
write_set: []
inputs:
  facts_baseline: <version>
  goal: <明确目标>
  context: <最小充分上下文>
output_schema: <结构化结果>
validation: <客观完成检查>
critical: true|false
retry_policy: <策略>
failure_route: block | revise | degrade | recompile

4.1 通用 Sub-agent 输出 Schema

Sub-agent 返回：

status: completed | blocked | failed
facts:
  - claim: <原子事实>
    evidence: <记录/文档/文件/命令引用>
    confidence: high | medium | low
decisions: []
assumptions:
  - statement: <假设>
    verification: <如何验证>
unknowns:
  - question: <未知>
    type: business | technical
    blocking: true|false
conflicts: []
risks: []
artifacts: []
coverage: <本节点覆盖了哪些问题>
limitations: []

如果任务需要其他格式，应在节点 context 中补充，但不能省略 status、evidence、unknowns、limitations。

5. 固定串行骨架

所有新需求至少具有以下主干：

S0 Select
 → S1 Claim
 → S2 Compile Initial Graph
 → [F* Investigation Fan-out]
 → B1 Evidence Merge
 → G1 Requirement Readiness
 → S3 Outcome / Scope
 → [A* Analysis Fan-out]
 → B2 Solution Synthesis
 → S4 Unit Decomposition
 → S5 Development Unit DAG
 → [D* Unit Contract Drafting]
 → [R* Independent Review Fan-out]
 → B3 Review Merge / Revision Loop
 → W1 Serialized Base Writes
 → [V* Read-back Verification]
 → G2 Release Gate
 → S6 Complete or Reject

以下主干节点必须串行或由 Barrier 隔开：

  • 唯一对象选择与认领；
  • 统一事实基线；
  • Readiness 决策；
  • 目标和范围冻结；
  • 总体方案综合；
  • Unit 最终边界和共享契约；
  • 整体依赖与覆盖裁决；
  • Base 写入协调；
  • 最终状态流转和成功声明。

6. 动态编译规则

6.1 始终加入

  • Base 当前记录和关联记录调查；
  • 事实/决策/假设/未知分类；
  • Readiness Gate；
  • 目标、范围、行为流；
  • 测试/验收设计；
  • Unit 分解、Dependency DAG、Coverage Matrix；
  • PL 自审、写入和回读。

6.2 条件子图

触发条件 加入的节点或子图
可访问代码仓库 仓库结构、同类实现、接口、数据模型、测试事实调查
外部系统/API 提供者/消费者、版本、错误、超时、幂等、限流、Mock 和契约测试分析
数据迁移/不可逆变化 历史数据、数据质量、回填/双写、校验、灰度、回滚和演练子图
权限/认证/支付/隐私 信任边界、授权、敏感数据、审计、重放/滥用和失败关闭审核
性能/容量/SLA 指标依据、负载模型、基准、资源上限和观测子图；无事实依据不虚构数值
跨仓库/多团队 仓库边界、版本协同、契约生产者和发布顺序子图；需要持久协作时考虑 Kanban
技术未知会改变方案 time-boxed Spike Unit 设计；若阻断当前方案则停止实现型 Unit 放行
业务未知 直接进入 Reject/待修改路径，不能创建 Spike 代替业务决策
Bug 复现、预期/实际、日志/代码/测试证据、根因/假设、FAIL_TO_PASS 和 PASS_TO_PASS 子图
简单低风险局部改动 跳过无关外部研究和专项风险节点，但不得跳过事实、验收、覆盖和自审门

Graph 不是在 Intake 时一次性永久冻结。B1 合并事实后可增删分析节点；B2 方案综合后可增删 Unit 草拟和审核节点。

7. 并发规则

只有同时满足以下条件的节点才可并行：

  1. 彼此没有未满足的数据依赖；
  2. 节点输入基于同一事实基线版本；
  3. 写集合为空或完全不重叠；
  4. 输出边界和 Schema 明确；
  5. 存在后续 Barrier 负责合并和冲突处理；
  6. 并行收益大于上下文构造和合并成本。

典型并行节点：

  • Base/文档、仓库、接口、测试、外部资料的只读事实调查；
  • 范围、系统/接口、测试证据和专项风险分析；
  • 边界已冻结且互不重叠的 Unit 契约草拟；
  • Coverage、Dependency/Interface、Testability、Security/Migration 独立审核；
  • 写入完成后的多记录回读。

不得并行：

  • 两个 Agent 写同一 Base 记录或同一交付文件；
  • 多个 Agent 独立决定同一业务规则或公共契约；
  • 事实基线未完成时提前设计依赖它的方案；
  • 共享契约未稳定时独立草拟相互依赖的消费者；
  • PL 审核尚未通过时提前流转状态。

7.1 Hermes 并发映射

  • 单次 delegate_task(tasks=[...]) 不超过当前 delegation.max_concurrent_children；当前默认/本会话上限为 3；
  • Graph 宽度更大时，按拓扑和优先级分批 fan-out，不自动修改 Hermes 配置；
  • 默认使用 leaf sub-agent，主 Agent 负责所有汇合；
  • 不为了“多 Agent”使用嵌套 delegation；只有明确需要二级自治且配置允许时才使用 orchestrator；
  • 并行 Agent 不得共享可变目录或同一目标文件。即使终端会话独立，也不能假设底层执行环境完全隔离。

8. Skill 与 Agent 选择

顺序是“先选节点，再选 Skill/Executor”，不是先加载很多 skill 再寻找用途。

节点 推荐 Skill Executor
全部 Planning 节点 planning-requirement-expansion main 必须加载
飞书/Base/云文档 feishu-lark main 或只读 sub-agent；写入仅 main
仓库事实、Issue/PR github 或项目专用 skill 只读 sub-agent
外部研究 research / gemini-deepresearch leaf sub-agent
测试和质量审核 software-quality leaf sub-agent 或 main
多 Agent 编排 autonomous-ai-agents / hermes-agent main

Sub-agent 没有父会话历史。节点 context 必须显式给出目标、事实基线、路径、范围、非目标、输出 Schema、证据要求和使用的 skill 名称。不得假设父 Agent 已加载的 skill 内容会自动进入子 Agent 上下文；需要时要求子 Agent 自行加载，并把关键不可缺失规则直接写入 context。

9. Barrier 与证据合并

并行结果不能直接拼接。每个 Barrier 执行：

  1. 检查每个关键节点是否 completed；
  2. 验证输出 Schema 和证据引用；
  3. 将 claim 分类为事实、建议、假设或未知；
  4. 去重同义结论；
  5. 检测事实、字段、接口、时序和范围冲突；
  6. 更新事实基线版本；
  7. 判断是否重编译后续子图。

9.1 来源优先级

发生冲突时不按 Agent 数量投票。一般优先级为：

  1. Base 当前记录、用户明确原始要求和直接系统事实；
  2. 仓库当前实现、测试、日志和一手接口资料；
  3. 官方标准或供应商文档；
  4. 可信行业资料；
  5. Sub-agent 推断或建议。

同级一手证据冲突且无法自行验证时，标为阻塞性未知，不选择“看起来合理”的一方。

9.2 B3 强制汇合检查

  • 原始要求 → 主验收 → Unit → 测试证据覆盖；
  • Unit 无重复、无空洞、无范围外工作；
  • Dependency DAG 无环；
  • 接口生产者/消费者字段、错误、版本和时序一致；
  • 权限、安全、迁移、回滚和观测与风险相称；
  • 每个 Unit 可由单个 Code Agent 独立理解和验证；
  • 不存在阻塞性未知。

10. 故障、重试和取消

10.1 读取或网络瞬时失败

  • 可重试的只读节点由主 Agent安全重试，默认最多 2 次并改变策略或来源；
  • 连续相同调用无新信息时停止盲目重试；
  • 关键事实仍不可获取则阻断；非关键支线失败必须在 limitations 中显式记录。

10.2 节点内容不合格

Schema 缺失、无证据或扩大范围不是瞬时失败。应修订节点输入或由主 Agent补查，不对相同 prompt 机械重跑。

10.3 写操作失败或结果未知

  • 先重新读取目标系统，判断副作用是否已经发生；
  • 使用记录 ID、父记录、标题/Unit key 和当前状态进行去重；
  • 未完成 reconciliation 前不得重复创建子任务或重复状态流转；
  • 状态字段最后更新，避免把半成品标为待开发；
  • 不能证明成功时报告失败，不伪造 ID 或结果。

10.4 部分失败

  • critical 节点失败：对应 Barrier 不通过；
  • optional 节点失败：只有在主 Agent确认不影响正确性且记录 evidence gap 后才能降级继续；
  • 不允许用成功节点的数量掩盖关键节点失败。

10.5 取消传播

  • 收到停止、任务切换或父会话取消后，不再启动新节点或写操作；
  • Hermes /stop、关闭或重置会取消活动 delegation，不能把未返回结果视为完成；
  • 如果源记录在运行期间被其他人修改，停止依赖旧版本的后续节点，回读并重新编译受影响子图。

10.6 修订循环

B3 不通过时回到最接近根因的节点，不总是从头重跑。自动修订循环必须有界；同一缺陷经过两次有实质差异的修订仍无法通过时，失败关闭并记录所需决策或证据。

11. 幂等和写入隔离

  • 一轮只持有一个规划对象；
  • Claim 是第一项写操作；
  • Base 写入只有一个 main writer；
  • 子任务创建前按父记录、现有子任务、标题/稳定 Unit 标识和责任边界重新查询去重；
  • 完整描述和关系写入成功后才更新最终状态；
  • 最终回读是成功判定的一部分，不是可选检查。

12. Inline、Kanban 和 cron 的选择

Inline + delegate_task

用于：一个 Planning run 内的短时调查、分析和审核；结果必须返回主 Agent 后才能继续。

限制：非持久；子 Agent 无用户交互和 memory；父进程消失时执行不能恢复；外部副作用必须由主 Agent验证。

Hermes Kanban

用于：

  • 工作必须跨会话或进程重启；
  • 需要不同持久 profile 多轮接力；
  • 需要人工 comment/block/unblock；
  • 需要 durable dependency、retry 和审计历史；
  • 下游 Development Unit 需要在隔离 worktree 中由多个 Code Agents 按 DAG 执行。

Kanban task 应使用 parent links 表示真实依赖、idempotency key 防止自动化重复创建，并由 dispatcher 在父任务完成后提升 ready 状态。

Cron

cron 负责定时触发一个新的、自包含的 Planning run。cron session 不能依赖当前聊天历史，也不能请求现场澄清；遇到业务未知必须写入待决策问题并失败关闭。不要在 cron run 中递归创建 cron。

13. Development Unit DAG 输出

规划通过前必须生成下游 DAG：

units:
  - id: U_CONTRACT
    depends_on: []
    evidence: contract-test
  - id: U_PRODUCER
    depends_on: [U_CONTRACT]
  - id: U_CONSUMER
    depends_on: [U_CONTRACT]
  - id: U_INTEGRATION
    depends_on: [U_PRODUCER, U_CONSUMER]

下游调度按拓扑层进行，同层 Unit 只有在代码工作区、接口和写集合隔离时才能并行。Planning Agent 只产出和审核 DAG，不在本工作区实现业务代码。

14. 最终 Graph 验收

一次 Planning Runtime Graph 只有满足以下条件才 completed：

  • 所有 critical 节点完成；
  • 所有 Barrier 已汇合并处理冲突；
  • Readiness 和 PL Review Gate 通过；
  • 原始要求、Unit 和测试证据可追溯；
  • Development Unit DAG 无环且生产者/消费者一致；
  • Base 写入由单一协调者完成；
  • 最终回读证明字段、描述、关系和状态正确。

否则终态是 blocked/rejected，不使用“部分完成”冒充可流转。

15. Hermes 官方依据

  • Subagent Delegation：website/docs/user-guide/features/delegation.md
  • Delegation Patterns：website/docs/guides/delegation-patterns.md
  • Kanban Multi-Agent Board：website/docs/user-guide/features/kanban.md
  • Configuration / Delegation：website/docs/user-guide/configuration.md
  • Prompt Assembly / Context Files：website/docs/developer-guide/prompt-assembly.md
  • 在线文档：https://hermes-agent.nousresearch.com/docs/

上述资料直接支持 delegation 的上下文隔离、并发上限、取消和非持久性，以及 Kanban 的持久任务、依赖、重试、幂等键和审计能力。动态 Graph Manifest、节点 Schema、Barrier 规则、来源仲裁和 Base 单写入策略是本 Planning 流水线的综合设计。