# 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：

```yaml
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

每个动态节点至少包含：

```yaml
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 返回：

```yaml
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. 固定串行骨架

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

```text
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：

```yaml
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 流水线的综合设计。