Rikugan子代理编排原理:多路隔离Subagent如何并行分析一个大二进制

原创2026-11-02 23:03:061,988 阅读

Rikugan子代理编排原理:多路隔离Subagent如何并行分析一个大二进制

Rikugan 是一个运行在 IDA Pro 和 Binary Ninja 内部的逆向工程 Agent(AI 分析助手)。它最硬核的设计之一,就是子代理(Subagent)编排:主 Agent 像"总指挥"一样,把一个大二进制的分析任务拆成多条隔离的支线,让多个 Subagent 并行干活,最后只把"浓缩结论"汇总回来——父级上下文始终干净、不爆 token。

Rikugan子代理编排:编排者并行派生子代理分析二进制

编排者(Orchestrator)并行派生多个子代理,各自独立分析后再汇总


为什么大二进制分析离不开子代理?

用 LLM 分析二进制时,有一个绕不开的瓶颈:上下文窗口。

反编译一个函数动辄几千行,一个中大型二进制的探索过程可能产生几十万 token 的原始输出(反编译代码、反汇编 dump、交叉引用列表)。如果全部堆在主对话里:

  • 上下文很快被塞满,后面的分析质量断崖式下跌;
  • 早期的关键发现被"冲淡",LLM 容易忘记;
  • Token 成本随每轮对话反复重放而暴涨。

Rikugan 的解法借鉴了"多进程并行"的思路:让脏活在隔离的上下文里干,只把结果摘要带回主线。这套机制的核心代码只有两个文件:


第一层:SubagentRunner——"同一个大脑,独立的工作台"

SubagentRunner(定义于 subagent.py)负责跑一个隔离的子代理,它的隔离策略非常克制:

资源 是否隔离 说明
工具注册表(60+ 分析工具) ❌ 共享 子代理能调用全部反编译、xref、字符串等工具
LLM Provider / 配置 ❌ 共享 与父级同一个模型、同一份配置
会话(SessionState) ✅ 全新 独立的消息历史和上下文窗口
AgentLoop 实例 ✅ 全新 子代理是一个完整的 Agent 循环,不是"函数调用"

关键设计点有三处:

  1. 上下文隔离是"物理级"的:子代理拿到的是全新的 SessionState,它的反编译输出、工具调用日志全部留在自己的窗口里,父级完全看不到(见 subagent.py)。
  2. 回合上限 + 摘要指令:任务被自动加上前缀 <a href="https://link.gitcode.com/i/4946e0f6532cbd21bfbd2a91fca7ac30" target="_blank">SUBAGENT TASK — max N turns],并要求"结束时给出简洁结论,聚焦可执行结果,而不是过程"([subagent.py)。这从提示词层面就把子代理的输出压成了一份"报告"。
  3. 静默模式(silent):多路并行时,父级 UI 默认不转发每个子代理的文字和工具输出,只放行需要人工交互的事件——工具执行审批(TOOL_APPROVAL_REQUEST)和用户提问(USER_QUESTION)(subagent.py)。这样屏幕不会被子代理刷屏,但安全门(script approval)依然有效。

Rikugan子代理并行分析流程示意

子代理以独立卡片形式展示在会话中,进度、摘要一目了然

Rikugan子代理任务分派效果

同一个任务可以被拆给多个子代理,各自独立返回结论


第二层: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反分析面板与子代理总览

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:

  1. 新建 SubagentRunner 跑任务,全程事件转发给 UI;
  2. 子代理的完整对话被单独存档到 session.subagent_logs(可按 tool_call_id 检索,方便事后导出复盘);
  3. 只有最终摘要作为工具结果回到父级上下文。

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)。后续的计划、打补丁、保存审批全部在干净的父级上下文里进行。

Rikugan子代理驱动的二进制修改工作流

类似 /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 … 并行动作,互不干扰。

Rikugan二进制批量分析面板

子代理并行处理后的二进制:函数命名清晰,人工接手成本大降


类型化子代理与"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)。这套机制让"派什么兵"变成了数据配置,而不是改代码。

Rikugan技能与子代理配置界面

技能系统配置界面: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 + 重型工具输出"的项目,这套"隔离上下文 + 结构化知识回传 + 事件总线"的三板斧,非常值得抄作业。

登录后查看全文
Rikugan