# Recursion and Examples

### Recursion safety

Because any dispatched agent may itself split its node further with this
same skill, every dispatch you make must carry enough information to keep
the recursion safe:

- **Carry a layer number.** If the task you are currently acting on (your own
  first turn, or a node dispatched to you) does not state a layer, you are
  layer 1. When you dispatch a node, append a line `层级：<your layer + 1>`
  to its `task` text, so the receiving agent knows its own layer.
- **Depth cap: layer ≥ 3 must do the work directly, never split further.**
  If the task you received states `层级：N` with `N ≥ 3`, do not use this
  skill's dispatch machinery at all — just do the work yourself. This bounds
  recursion to at most three levels deep and prevents an unbounded fan-out.
- **Never dispatch a node back to your own dispatcher.** The `callback_
  session_id` in the task you received identifies the agent that dispatched
  you (or, if you are layer 1, there is none). Exclude that agent from your
  own Step 1 inventory when choosing who gets your sub-nodes — dispatching a
  sub-node back to whoever dispatched you creates a wait cycle: they are
  already waiting on your report, and would then also be waiting on a report
  from you as their own sub-task.
- **Never just relay the task verbatim to one other agent.** Forwarding your
  entire node unchanged to a single agent is not splitting — either genuinely
  decompose it into distinct sub-nodes, or do it yourself.
- **Report only to your immediate dispatcher, never further up the chain.**
  You do not know (and must not guess) who is above your own dispatcher; your
  `report_dispatch_result` always targets the `callback_session_id` /
  `quoted_message_id` from the task you received, nothing else. See
  [closeout procedure](receipts-and-watchdogs.md#step-9--close-out-final-summary-and-reporting-up) for what a
  non-top-level agent reports.

## Example: three-node flow, two parallel + one sequential roll-up

Nodes: `写单测` (parallel, agent 分析师A) and `写文档` (parallel, agent
分析师B), then `合并汇总` (sequential, agent 统筹B, depends on both) —
both agents already existed and were found in Step 1's inventory.

Initial message (right after Step 4, before any dispatch has reported back):

````text
flow: task-flow-20260912-1 started 2026-09-12 14:00

```mermaid
flowchart TD
    A[分析师A: 写单测]:::running
    B[分析师B: 写文档]:::running
    C[统筹B: 合并汇总]:::pending
    A --> C
    B --> C

    classDef pending fill:#eee,stroke:#999,color:#333
    classDef running fill:#fff3cd,stroke:#d39e00,color:#7a5b00
    classDef done fill:#d4edda,stroke:#28a745,color:#155724
    classDef failed fill:#f8d7da,stroke:#dc3545,color:#721c24
```
````

After 分析师A's `[dispatch-result]` receipt (`status: completed`) arrives,
edit the same message:

````text
flow: task-flow-20260912-1 started 2026-09-12 14:00

```mermaid
flowchart TD
    A[分析师A: 写单测]:::done
    B[分析师B: 写文档]:::running
    C[统筹B: 合并汇总]:::pending
    A --> C
    B --> C

    classDef pending fill:#eee,stroke:#999,color:#333
    classDef running fill:#fff3cd,stroke:#d39e00,color:#7a5b00
    classDef done fill:#d4edda,stroke:#28a745,color:#155724
    classDef failed fill:#f8d7da,stroke:#dc3545,color:#721c24
```

- 分析师A: 新增 12 条单测，全部通过。
````

After 分析师B also completes, dispatch 统筹B (C now unblocked), mark it
`running` in the same edit, then once 统筹B's receipt arrives, do the final
edit (Step 9):

````text
flow: task-flow-20260912-1 done 2026-09-12 14:37

```mermaid
flowchart TD
    A[分析师A: 写单测]:::done
    B[分析师B: 写文档]:::done
    C[统筹B: 合并汇总]:::done
    A --> C
    B --> C

    classDef done fill:#d4edda,stroke:#28a745,color:#155724
```

- 分析师A: 新增 12 条单测，全部通过。
- 分析师B: 更新 README 与 API 文档。
- 统筹B: 合并两者改动，跑全量测试通过。
- 改动路径：`tests/foo_test.go`, `README.md`, `docs/api.md`
- 未完成项：无
````

### Branch: filling a gap by provisioning an agent (Step 2)

Same flow, but no existing agent fits `写文档` (the inventory in Step 1 found
nobody whose introduction mentions technical writing). `grix_egg_search` with
keyword `技术文档` finds a persona egg "文档助手". Before dispatching, use
`grix-admin`'s `create-and-connector-bind` to create a new local agent from
that egg, then dispatch `写文档` to it like any other node. The initial
diagram already reflects this — there is nothing different about the diagram
itself once the agent exists — but the **final summary** (Step 9) must call
it out:

```text
- 文档助手 (新建): 更新 README 与 API 文档。
- 新建/配技能 Agent：文档助手（agent_id=12345，来自蛋市场持久化人设蛋，建议主人确认是否保留）
```

### Branch: two-level recursion

顶层 Agent（层级 1）收到"重构 payment 模块并补齐单测和文档"，判断为需要拆分，
按 Step 1–4 拆成三节点：`重构核心逻辑`（agent 后端A）、`写单测`（agent 后端B，
依赖重构完成）、`写文档`（agent 分析师B，并行）。派 `重构核心逻辑` 时在 `task`
里附一行 `层级：2`。

```mermaid
flowchart TD
    A[后端A: 重构核心逻辑]:::running
    B[后端B: 写单测]:::pending
    C[分析师B: 写文档]:::running
    A --> B

    classDef pending fill:#eee,stroke:#999,color:#333
    classDef running fill:#fff3cd,stroke:#d39e00,color:#7a5b00
```

后端A（层级 2）收到 `重构核心逻辑` 任务后，自己判断这块本身也偏大（涉及三个
子模块，其中两个互不依赖），于是自己也调用本技能，在**自己的会话里**画自己
的子图，并派出两个层级 3 的节点（`task` 里带 `层级：3`）：

```mermaid
flowchart TD
    D[后端C: 重构子模块X]:::running
    E[后端D: 重构子模块Y]:::running
    F[后端A: 合并两子模块]:::pending
    D --> F
    E --> F
```

层级 3 的两个 Agent（后端C、后端D）各自收到任务时看到 `层级：3`，按硬规则
**只能直接做，不能再拆**——即使它们各自的那块看起来也能再分。两者都
`completed` 后，后端A（层级 2）合并子模块、跑通自己那张子图，然后**不会**把
子图原样贴回给顶层 Agent；而是用 `report_dispatch_result` 回给顶层 Agent（用
自己任务里的 `callback_session_id` / `quoted_message_id`），`detail` 里只放
折叠后的子图摘要：

`````text
[dispatch-result]
**status**:
```text
completed
```
**summary**:
```text
payment 模块核心逻辑重构完成，含两个子模块合并
```
**detail**:
- 子图（层级 3，均已完成）：
  - 后端C: 重构子模块X 完成，`payment/gateway.go`
  - 后端D: 重构子模块Y 完成，`payment/settlement.go`
  - 合并：两子模块整合并本地跑通，`payment/core.go`
**session**:
```text
<后端A 自己的工作会话 id>
```
[/dispatch-result]
`````

顶层 Agent 收到这条回执后，像处理任何普通节点回执一样，把 `重构核心逻辑`
标记 `done`，在自己那张（层级 1 的）图下追加一行结论——`detail` 里的子图摘要
被折叠进这一行，不会展开成顶层图里的额外节点：

```text
- 后端A: 重构核心逻辑完成（内部拆两个子模块+合并，均通过）。
```

随后 `写单测`（依赖重构完成）解除阻塞，正常派出；`写文档` 的进度独立更新。
