Rikugan子代理编排原理:多路隔离Subagent如何并行分析一个大二进制
Rikugan子代理编排原理:多路隔离Subagent如何并行分析一个大二进制
Rikugan 是一个运行在 IDA Pro 和 Binary Ninja 内部的逆向工程 Agent(AI 分析助手)。它最硬核的设计之一,就是子代理(Subagent)编排:主 Agent 像"总指挥"一样,把一个大二进制的分析任务拆成多条隔离的支线,让多个 Subagent 并行干活,最后只把"浓缩结论"汇总回来——父级上下文始终干净、不爆 token。
编排者(Orchestrator)并行派生多个子代理,各自独立分析后再汇总
为什么大二进制分析离不开子代理?
用 LLM 分析二进制时,有一个绕不开的瓶颈:上下文窗口。
反编译一个函数动辄几千行,一个中大型二进制的探索过程可能产生几十万 token 的原始输出(反编译代码、反汇编 dump、交叉引用列表)。如果全部堆在主对话里:
- 上下文很快被塞满,后面的分析质量断崖式下跌;
- 早期的关键发现被"冲淡",LLM 容易忘记;
- Token 成本随每轮对话反复重放而暴涨。
Rikugan 的解法借鉴了"多进程并行"的思路:让脏活在隔离的上下文里干,只把结果摘要带回主线。这套机制的核心代码只有两个文件:
- 子代理执行器:rikugan/agent/subagent.py
- 子代理编排器:rikugan/agent/subagent_manager.py
第一层:SubagentRunner——"同一个大脑,独立的工作台"
SubagentRunner(定义于 subagent.py)负责跑一个隔离的子代理,它的隔离策略非常克制:
| 资源 | 是否隔离 | 说明 |
|---|---|---|
| 工具注册表(60+ 分析工具) | ❌ 共享 | 子代理能调用全部反编译、xref、字符串等工具 |
| LLM Provider / 配置 | ❌ 共享 | 与父级同一个模型、同一份配置 |
| 会话(SessionState) | ✅ 全新 | 独立的消息历史和上下文窗口 |
| AgentLoop 实例 | ✅ 全新 | 子代理是一个完整的 Agent 循环,不是"函数调用" |
关键设计点有三处:
- 上下文隔离是"物理级"的:子代理拿到的是全新的
SessionState,它的反编译输出、工具调用日志全部留在自己的窗口里,父级完全看不到(见 subagent.py)。 - 回合上限 + 摘要指令:任务被自动加上前缀
<a href="https://link.gitcode.com/i/4946e0f6532cbd21bfbd2a91fca7ac30" target="_blank">SUBAGENT TASK — max N turns],并要求"结束时给出简洁结论,聚焦可执行结果,而不是过程"([subagent.py)。这从提示词层面就把子代理的输出压成了一份"报告"。 - 静默模式(silent):多路并行时,父级 UI 默认不转发每个子代理的文字和工具输出,只放行需要人工交互的事件——工具执行审批(
TOOL_APPROVAL_REQUEST)和用户提问(USER_QUESTION)(subagent.py)。这样屏幕不会被子代理刷屏,但安全门(script approval)依然有效。
子代理以独立卡片形式展示在会话中,进度、摘要一目了然
同一个任务可以被拆给多个子代理,各自独立返回结论
第二层:SubagentManager——并发调度与事件总线
SubagentManager(subagent_manager.py)是"编排中枢",它把单发子代理变成多路并行:
spawn()后台派生:每个子代理运行在独立的 daemon 线程中(线程名rikugan-subagent-xxxx),拿到 12 位 UUID 作为身份标识(subagent_manager.py)。派生立即返回 ID,父级不阻塞。- 父子树状结构:
SubagentInfo记录parent_id和children,可以表达"总指挥 → 分线 → 分线再拆分"的树形组织,UI 的 Agents 面板按树展示(subagent_manager.py)。 - 统一事件队列:所有子代理的生命周期事件——
subagent_spawned/subagent_progress(每回合)/subagent_completed/subagent_failed——都写入同一个线程安全队列,由主循环非阻塞地poll_event()消费(subagent_manager.py)。这就是 UI 上"多路进度条"的数据来源。 - 可取消:每个子代理持有一个
threading.Event作为取消信号,用户点取消即置位,后台线程在下一事件处退出并落CANCELLED状态(subagent_manager.py)。 - 状态机:
PENDING → RUNNING → COMPLETED / FAILED / CANCELLED五态,附带回合数、Token 用量、耗时,全部可在 SubagentInfo 中查到。
Rikugan 主面板:聊天、工具调用与子代理活动集中呈现在反汇编器内部
第三层:LLM 自己会"招人"——spawn_subagent 伪工具
最优雅的一点:决定何时拆分子任务的是 LLM 本身,不是写死的代码。
主 Agent 的工具集里内置了一个伪工具 spawn_subagent(schema 定义于 loop.py):
"Spawn an isolated subagent to handle a complex subtask. The subagent has its own context window… Use this to delegate research-heavy tasks (e.g. 'analyze all functions referencing the score string') without filling your own context with raw tool output."
也就是说,当你问"这个 IoT 固件的通信模块是怎么工作的"时,LLM 会自主判断:"字符串溯源这活儿量太大",于是调用 spawn_subagent(task=..., max_turns=...),处理逻辑在 _handle_spawn_subagent_tool:
- 新建
SubagentRunner跑任务,全程事件转发给 UI; - 子代理的完整对话被单独存档到
session.subagent_logs(可按 tool_call_id 检索,方便事后导出复盘); - 只有最终摘要作为工具结果回到父级上下文。
Research 模式(深度研究一个二进制、产出 Obsidian 风格笔记)也显式鼓励这种拆分,见 modes/research.py。
实战一:/modify 探索模式——"脏探索"整体外包
这是子代理机制最能体现价值的场景。/modify make this maze game easy 这类请求会进入探索模式(modes/exploration.py),其 Phase 1(EXPLORE)整体运行在一个子代理里(_run_phase1_subagent):
用户: /modify 把血量改成 999
└─ Phase 1: EXPLORE(隔离子代理)
├─ 反编译候选函数、追 xref、搜字符串……
├─ 每条发现通过 exploration_report 记入 KnowledgeBase
└─ 结束时返回 KnowledgeBase(不是原始输出!)
└─ 父级只收到 ~1-2KB 的结构化摘要
└─ Phase 2: PLAN → Phase 3: EXECUTE → Phase 4: SAVE
这里有个漂亮的"知识封装"设计:子代理不是回传一段散文,而是回传结构化的 KnowledgeBase——相关函数表、字符串引用、导入表、findings、hypotheses,由 kb.to_summary() 渲染成紧凑摘要注入父级(modes/exploration.py)。后续的计划、打补丁、保存审批全部在干净的父级上下文里进行。
类似 /modify 的多阶段工作流:探索结果经子代理压缩后,主线才能高效推进
实战二:批量重命名——每个函数一个 Subagent
大二进制里几百个 sub_40xxxx?Rikugan 的 Bulk Renamer"深度模式"为每个函数派生一个 SubagentRunner,用线程池并行做深度分析再给出重命名建议(bulk_renamer.py):
- 每个函数子代理先
decompile_function,再带着反编译代码 + 分析提示词独立判断语义; - 子代理不自己开线程,而是通过
mgr.register()注册到 SubagentManager 仅用于展示,状态由update_external()推进(subagent_manager.py)——这是"外部托管代理"的接入范例; - 结果:Agents 面板里看到一整排
agent_sub_401230 …并行动作,互不干扰。
子代理并行处理后的二进制:函数命名清晰,人工接手成本大降
类型化子代理与"Perks":给子代理配技能包
并非所有子代理都同质。SubagentManager 支持类型化子代理,不同类型的子代理在派生时会被注入不同的系统提示附录(_build_system_addendum):
network_recon:网络协议逆向专家,固定 30 回合上限,专职重建网络通信层(找 socket 导入 → 追调用者 → 识别 C2/加密 → 声明 C 结构体),见 agents/network_recon.py;report_writer:专职写结构化分析报告,见 agents/report_writer.py;custom+ Perks:通用子代理可以叠加"技能包",见 agents/perks.py。
Perks 是一组可选的强化指令,按需组合进提示词:
| Perk | 效果 |
|---|---|
deep_decompilation |
追调用链最多 3 层深,引用到的函数全部反编译 |
string_harvesting |
列出每个函数的所有字符串引用及交叉引用 |
import_mapping |
映射每个导入 API 的调用者及传参 |
memory_layout |
分析栈帧布局、全局变量、结构体字段偏移 |
hypothesis_mode |
先提出 3 个假设,再逐一用工具验证/证伪 |
network_recon 类型就是 import_mapping + string_harvesting + deep_decompilation 的预配置组合(network_recon.py)。这套机制让"派什么兵"变成了数据配置,而不是改代码。
技能系统配置界面:Skills 与子代理能力共同构成 Rikugan 的可扩展层
总结:三个设计让"并行"既快又稳
| 设计 | 解决的问题 | 源码位置 |
|---|---|---|
独立 SessionState 物理隔离 |
父级上下文不被原始输出污染 | subagent.py |
| 线程池 spawn + 统一事件队列 | 多路子代理真正并行,UI 进度实时 | subagent_manager.py |
| KnowledgeBase / 摘要回传 | 收敛信息密度,父级只拿结论 | exploration_mode.py |
再配上 max_turns 防失控、silent 模式防刷屏、threading.Event 防失控取消、"always allow scripts" 审批状态回同步父级(subagent.py),整条链路既有并行的速度,又保留了人工审批的刹车。
更完整的架构说明可参考仓库内的 ARCHITECTURE.md(Subagents 章节)与 DEVELOPMENT.md。如果你也在做"LLM Agent + 重型工具输出"的项目,这套"隔离上下文 + 结构化知识回传 + 事件总线"的三板斧,非常值得抄作业。






