headless-ghidra

Headless Ghidra — 全局协调器

此技能是整个技能系列的工作流协调器。它定义了 P0–P4 阶段顺序、 分派规则和工件交接点。 ghidra-agent-cli 仍是命令语法和 YAML 工件语义的参考工具。

必需的共享工具约定

• 对于受支持的工作区、元数据、Ghidra、Frida、进度、验证和门禁操作，必须使用共享接口 ghidra-agent-cli。
• 各阶段技能必须明确列出所用的 ghidra-agent-cli 子命令。
• 底层 Shell 脚本和 Java 辅助程序属于后端细节。当 CLI 已支持相应操作时，不得用它们取代 CLI 作为主要接口。
• 所有工作流工件都必须存放在 artifacts/<target-id>/ 下。
• YAML 工件必须通过 ghidra-agent-cli 创建、更新和验证。
• CLI 不得自动创建 Git 提交。
• 进行门禁转换前，相关工件必须已存在于磁盘上，并准备好供用户审阅。
• 所有 Ghidra 项目操作都必须通过 ghidra-agent-cli 执行。如果 CLI 缺少所需功能，请暂停并询问用户，然后再创建或运行新的 Ghidra 脚本。

流水线

P0 Intake → P1 Baseline+Runtime → P2 Third-Party → [P3 Metadata Enrichment → P4 Function Substitution]*

阶段	技能	用途	主要输出
P0	headless-ghidra-intake	初始化目标工作区、查找前置条件并定义范围	pipeline-state.yaml、scope.yaml、targets/<id>/ghidra-projects/
P1	headless-ghidra-baseline	运行 Ghidra 导入与分析、导出基线 YAML，并准备运行时观测数据	baseline/*.yaml、runtime/run-manifest.yaml、runtime/run-records/*.yaml、runtime/hotpaths/call-chain.yaml
P2	headless-ghidra-evidence	识别并记录第三方库及其原始源代码	third-party/identified.yaml、third-party/pristine/<library>@<version>/、third-party/compat/<library>@<version>/
P3	headless-ghidra-discovery	补充名称、签名、类型、常量、字符串和选定的热点元数据	metadata/*.yaml、metadata/apply-records/
P4	headless-ghidra-batch-decompile	通过应用元数据和 Ghidra 反编译来替换选定函数	substitution/next-batch.yaml、substitution/functions/<fn_id>/

共享工件约定

所有阶段都在以下活动工作区布局中进行：

targets/<target-id>/ghidra-projects/

artifacts/<target-id>/
├── pipeline-state.yaml
├── scope.yaml
├── intake/
├── baseline/
├── runtime/
│   ├── project/
│   ├── fixtures/
│   ├── run-manifest.yaml
│   ├── run-records/
│   └── hotpaths/call-chain.yaml
├── third-party/
│   ├── identified.yaml
│   ├── pristine/<library>@<version>/
│   └── compat/<library>@<version>/
├── metadata/
│   ├── renames.yaml
│   ├── signatures.yaml
│   ├── types.yaml
│   ├── constants.yaml
│   ├── strings.yaml
│   └── apply-records/
├── substitution/
│   ├── template/
│   ├── next-batch.yaml
│   └── functions/<fn_id>/
└── gates/

协调器将 pipeline-state.yaml 视为当前目标级状态记录，并依赖上述由各阶段管理的 YAML 工件进行交接。

协调器职责

1. 检测或恢复活动目标。
2. 读取 artifacts/<target-id>/pipeline-state.yaml。
3. 为当前阶段分派相应的阶段技能。
4. 在每次转换时运行 ghidra-agent-cli gate check --phase ...。
5. 仅在门禁通过后推进阶段状态。
6. 处理用户对话，例如恢复或重启、可选的 Frida 补充、批次确认、差异审阅和完成确认。

门禁策略

• P0–P4 是唯一的主要流水线转换。
• ghidra-agent-cli gate check 是所有流水线阶段（P0–P4）的权威门禁验证命令。旧版 gate-check.sh 已移除。

必需的 ghidra-agent-cli 命令

• ghidra-agent-cli context use
• ghidra-agent-cli context show
• ghidra-agent-cli context clear
• ghidra-agent-cli workspace state show
• ghidra-agent-cli workspace state set-phase
• ghidra-agent-cli gate check
• ghidra-agent-cli validate
• ghidra-agent-cli progress compute-next-batch
• ghidra-agent-cli progress show

严格禁止事项

• 不得自行执行分析工作。
• 除明确由其负责的状态更新外，不得直接编辑基线、证据、反编译或验证产物。
• 对于受支持的状态、进度、上下文、验证或门禁操作，不得绕过 ghidra-agent-cli。
• 不得使用 Ghidra 以外的反编译后端。
• 不得自动创建 Git 提交。
• 如果 CLI 不具备某项能力，不得创建或运行新的 Ghidra 脚本；应暂停并先询问用户。

后续技能路由

• P0 完成 → headless-ghidra-baseline
• P1 完成 → headless-ghidra-evidence
• P2 完成 → headless-ghidra-discovery
• P3 完成 → headless-ghidra-batch-decompile
• 所有选定函数的 P4 均完成 → 返回 P3，或结束

独立技能

以下技能在 P0–P4 流水线之外运行，可直接调用：

技能	用途	调用方式
headless-ghidra-analyze-function	按照严格的五步恢复顺序，对单个函数进行全面分析：类型 → 常量 → 虚函数表 → 函数身份 → 反编译。适用于在解读反编译结果之前，需要结合完整的类型、常量和虚函数表上下文，对某个特定函数进行全面分析的场景。	当用户要求“全面分析此函数”“结合完整上下文反编译 0x... 处的函数”，或请求对单个函数进行完整分析时调用。