connect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Additional Resources

额外资源

For canonical schema catalog: references/schema-catalog.md
For CLI reference, REPL commands, server modes, and runtime controls: references/cli-reference.md
For legacy parity tracking: references/legacy-parity-matrix.md
For optimization quality gate: references/optimization-checklist.md
For HTTP server guide: references/server-guide.md

标准架构目录：references/schema-catalog.md
CLI参考、REPL命令、服务器模式及运行时控制：references/cli-reference.md
旧版功能兼容性跟踪：references/legacy-parity-matrix.md
优化质量检查清单：references/optimization-checklist.md
HTTP服务器指南：references/server-guide.md

Quick Start CLI (Do This First)

CLI快速入门（优先执行）

Use these commands first to avoid guessing behavior or schema:

bash

undefined

先使用以下命令，避免出现预期外行为或架构问题：

bash

undefined

Single query

单次查询

idasql -s database.i64 -q "SELECT * FROM welcome"

Interactive REPL

交互式REPL

idasql -s database.i64 -i

Long-lived HTTP server for iterative analysis

用于迭代分析的长期HTTP服务器

idasql -s database.i64 --http 8081

Query over HTTP

通过HTTP执行查询

curl -X POST http://127.0.0.1:8081/query -d "SELECT name, size FROM funcs LIMIT 5"


Critical guardrails:
- Always provide `-s <db>` (`.idb` / `.i64`).
- Use `--write` when you want edits persisted on exit.
- Discover schema before writing queries:
  - REPL: `.schema <table>`
  - SQL: `PRAGMA table_xinfo(<table>);` (or `PRAGMA table_info(<table>);`)
- Start orientation with `SELECT * FROM welcome;`.

---

curl -X POST http://127.0.0.1:8081/query -d "SELECT name, size FROM funcs LIMIT 5"


重要注意事项：
- 务必提供 `-s <db>`（`.idb` / `.i64`格式）。
- 需要在退出时保存编辑内容时，使用 `--write` 参数。
- 编写查询前先查看架构：
  - REPL环境：`.schema <table>`
  - SQL语句：`PRAGMA table_xinfo(<table>);`（或 `PRAGMA table_info(<table>);`）
- 先执行 `SELECT * FROM welcome;` 来了解数据库概况。

---

Schema Catalog (Canonical)

标准架构目录

Canonical table/view formats live in

references/schema-catalog.md

Source of truth for column shapes and owner skill mapping.
Sourced from SQL metadata (
```
pragma_table_list
```
+
```
pragma_table_xinfo
```
).
Use this before assuming column names for less-common surfaces.
Legacy parity tracker:
```
references/legacy-parity-matrix.md
```
Optimization quality gate:
```
references/optimization-checklist.md
```

Manual refresh:

SELECT schema, name, type, ncol FROM pragma_table_list WHERE schema='main' ORDER BY type, name;

```
PRAGMA table_xinfo(<surface>);
```
Update
```
references/schema-catalog.md
```
owner mapping when surfaces change.

标准表/视图格式存于

references/schema-catalog.md

。

列结构与所属技能映射的权威来源。
源自SQL元数据（
```
pragma_table_list
```
+
```
pragma_table_xinfo
```
）。
在假设小众数据表面的列名前，先参考此文档。
旧版功能兼容性跟踪：
```
references/legacy-parity-matrix.md
```
优化质量检查清单：
```
references/optimization-checklist.md
```

手动刷新步骤：

SELECT schema, name, type, ncol FROM pragma_table_list WHERE schema='main' ORDER BY type, name;

```
PRAGMA table_xinfo(<surface>);
```
当数据表面变化时，更新
```
references/schema-catalog.md
```
中的所属技能映射。

Session Bootstrap Contract

会话启动约定

Use this exact startup flow before deep analysis:

Connect to database (
```
-s
```
,
```
-i
```
, or
```
--http
```
).
Run orientation query:

sql

SELECT * FROM welcome;

Validate key entities exist:

sql

SELECT COUNT(*) AS funcs FROM funcs;
SELECT COUNT(*) AS xrefs FROM xrefs;
SELECT COUNT(*) AS strings FROM strings;

Introspect schema for target surfaces before authoring complex SQL:

sql

PRAGMA table_xinfo(funcs);
PRAGMA table_xinfo(xrefs);

Route to domain skill using routing matrix below.

Never skip steps 2-4 when the user prompt is broad or ambiguous.

进行深度分析前，务必遵循以下启动流程：

连接至数据库（使用
```
-s
```
、
```
-i
```
或
```
--http
```
参数）。
执行概况查询：

sql

SELECT * FROM welcome;

验证关键实体是否存在：

sql

SELECT COUNT(*) AS funcs FROM funcs;
SELECT COUNT(*) AS xrefs FROM xrefs;
SELECT COUNT(*) AS strings FROM strings;

在编写复杂SQL前，先查看目标数据表面的架构：

sql

PRAGMA table_xinfo(funcs);
PRAGMA table_xinfo(xrefs);

根据下方的路由矩阵，路由至对应领域的技能。

当用户提示宽泛或模糊时，绝不能跳过步骤2-4。

Global Agent Contracts

全局Agent约定

These contracts apply across all idasql skills and should be treated as one shared agent behavior model.

这些约定适用于所有idasql技能，应作为统一的Agent行为模型遵循。

Read-First Contract

先读约定

Read current state first (
```
SELECT
```
) before writes (
```
INSERT
```
/
```
UPDATE
```
/
```
DELETE
```
).
Confirm target precision using stable identifiers (
```
address
```
,
```
func_addr
```
,
```
idx
```
,
```
label_num
```
).

执行写入操作（
```
INSERT
```
/
```
UPDATE
```
/
```
DELETE
```
）前，先读取当前状态（
```
SELECT
```
）。
使用稳定标识符（
```
address
```
、
```
func_addr
```
、
```
idx
```
、
```
label_num
```
）确认目标精度。

Anti-Guessing Contract

禁止猜测约定

Do not assume columns/types for long-tail surfaces.
Introspect via
```
.schema
```
or
```
PRAGMA table_xinfo(...)
```
before issuing uncertain queries.

不要小众数据表面的列/类型。
执行不确定的查询前，先通过
```
.schema
```
或
```
PRAGMA table_xinfo(...)
```
查看架构。

Mandatory Mutation Loop

强制变更循环

Read current state.
Apply mutation.
Refresh if needed (
```
decompile(..., 1)
```
for decompiler surfaces).
Re-read and verify expected change.

读取当前状态。
执行变更操作。
必要时刷新（针对反编译数据表面，使用
```
decompile(..., 1)
```
）。
重新读取并验证预期变更是否生效。

Performance Contract

性能约定

Always constrain high-cost surfaces (
```
xrefs
```
,
```
instructions
```
,
```
ctree*
```
,
```
pseudocode
```
) by key columns.
For decompiler surfaces, enforce
```
func_addr = X
```
unless explicitly asked for broad scans.

始终通过关键列限制高成本数据表面（
```
xrefs
```
、
```
instructions
```
、
```
ctree*
```
、
```
pseudocode
```
）的查询范围。
针对反编译数据表面，除非明确要求大范围扫描，否则必须加上
```
func_addr = X
```
约束。

Failure Recovery Contract

故障恢复约定

On
```
no such table/column
```
: introspect schema and retry.
On empty results: validate address range, table freshness (
```
rebuild_strings()
```
), and runtime capabilities.
On timeout: narrow scope, add constraints, paginate, or split query.

遇到
```
no such table/column
```
错误时：查看架构后重试。
遇到空结果时：验证地址范围、表的新鲜度（
```
rebuild_strings()
```
）及运行时能力。
遇到超时错误时：缩小查询范围、添加约束、分页或拆分查询。

Skill Routing Matrix (Intent -> Skill)

技能路由矩阵（意图→技能）

Use this deterministic mapping for initial routing:

User intent	Primary skill	Typical first query
"what does this binary do?" / triage	`analysis`	`SELECT * FROM entries;`
disassembly, segments, instructions	`disassembly`	`SELECT * FROM funcs LIMIT 20;`
xrefs/callers/callees/import dependencies	`xrefs`	`SELECT * FROM xrefs WHERE to_ea = ...;`
find functions/types/labels/members by name pattern	`grep`	`SELECT name, kind, address FROM grep WHERE pattern = 'main' LIMIT 20;`
strings/bytes/pattern search	`data`	`SELECT * FROM strings LIMIT 20;`
decompile/pseudocode/ctree/lvars	`decompiler`	`SELECT decompile(0x...);`
comments/renames/retyping/bookmarks	`annotations`	`SELECT ...` on target row before update
type creation/struct/enum/member work	`types`	`SELECT * FROM types LIMIT 20;`
breakpoints/patching	`debugger`	`SELECT * FROM breakpoints;`
persistent key/value notes	`storage`	`SELECT * FROM netnode_kv LIMIT 20;`
SQL function lookup/signature recall	`functions`	`SELECT * FROM pragma_function_list;`
live IDA UI context questions	`ui-context`	`SELECT get_ui_context_json();` (when available)
IDA SDK-only logic not in SQL surfaces	`idapython`	`PRAGMA idasql.enable_idapython = 1; SELECT idapython_snippet('print(...)');`
recursive source/structure recovery	`re-source`	start from function + recurse/handoff

When prompts span domains, execute in this order:

Orientation in
```
connect
```
Primary domain skill
Adjacent skills for enrichment (for example
```
xrefs
```
+
```
decompiler
```
+
```
annotations
```
)

使用以下确定性映射进行初始路由：

用户意图	主技能	典型初始查询
"这个二进制文件的功能是什么？" / 分类排查	`analysis`	`SELECT * FROM entries;`
反汇编、段、指令	`disassembly`	`SELECT * FROM funcs LIMIT 20;`
交叉引用/调用方/被调用方/导入依赖	`xrefs`	`SELECT * FROM xrefs WHERE to_ea = ...;`
按名称模式查找函数/类型/标签/成员	`grep`	`SELECT name, kind, address FROM grep WHERE pattern = 'main' LIMIT 20;`
字符串/字节/模式搜索	`data`	`SELECT * FROM strings LIMIT 20;`
反编译/伪代码/抽象语法树/局部变量	`decompiler`	`SELECT decompile(0x...);`
注释/重命名/重新类型定义/书签	`annotations`	更新前先对目标行执行 `SELECT ...`
类型创建/结构体/枚举/成员操作	`types`	`SELECT * FROM types LIMIT 20;`
断点/补丁	`debugger`	`SELECT * FROM breakpoints;`
持久化键值对笔记	`storage`	`SELECT * FROM netnode_kv LIMIT 20;`
SQL函数查找/签名查询	`functions`	`SELECT * FROM pragma_function_list;`
实时IDA UI上下文问题	`ui-context`	`SELECT get_ui_context_json();` （仅在可用时）
仅IDA SDK支持、未在SQL数据表面实现的逻辑	`idapython`	`PRAGMA idasql.enable_idapython = 1; SELECT idapython_snippet('print(...)');`
递归源码/结构恢复	`re-source`	从函数开始，递归处理/移交任务

当提示跨多个领域时，按以下顺序执行：

在
```
connect
```
技能中完成概况了解
调用主领域技能
调用相邻技能进行补充（例如
```
xrefs
```
+
```
decompiler
```
+
```
annotations
```
）

Cross-Skill Execution Recipes

跨技能执行方案

Recipe: Unknown binary triage -> suspicious function deep dive -> annotate

方案：未知二进制文件排查 → 可疑函数深度分析 → 添加注释

```
analysis
```
: identify candidates from imports/strings/call patterns.
```
xrefs
```
/
```
disassembly
```
: map call graph and call sites.
```
decompiler
```
: inspect logic and variable semantics.
```
annotations
```
: apply comments/renames/types with mutation loop.

```
analysis
```
：从导入项/字符串/调用模式中识别候选对象。
```
xrefs
```
/
```
disassembly
```
：绘制调用图和调用站点。
```
decompiler
```
：检查逻辑和变量语义。
```
annotations
```
：遵循变更循环添加注释/重命名/类型定义。

Recipe: String IOC -> reference graph -> patch

方案：字符串IOC → 引用图 → 补丁

```
data
```
: locate candidate strings and addresses.
```
xrefs
```
: map references to caller functions.
```
debugger
```
or
```
annotations
```
: patch or annotate specific sites.

```
data
```
：定位候选字符串及地址。
```
xrefs
```
：绘制调用函数的引用关系。
```
debugger
```
或
```
annotations
```
：对特定站点打补丁或添加注释。

Recipe: Type recovery from pseudocode

方案：从伪代码恢复类型

```
decompiler
```
: inspect lvars, call args, and ctree patterns.
```
types
```
: create/refine structs/enums and apply declarations.
```
annotations
```
: finalize naming/comments and verify rendered pseudocode.

```
decompiler
```
：检查局部变量、调用参数和抽象语法树模式。
```
types
```
：创建/优化结构体/枚举并应用声明。
```
annotations
```
：完成命名/注释并验证渲染后的伪代码。

UI Context Routing

UI上下文路由

For prompts like "what am I looking at?", "what's selected?", "what is on the screen?", "look at what I'm doing", or references to "this/current/that", use the dedicated

ui-context

skill.

ui-context

owns:

```
get_ui_context_json()
```
capture/reuse policy
temporal reference rules (
```
this
```
vs
```
that
```
)
response template, examples, and fallback messaging

Runtime caveat:

```
get_ui_context_json()
```
is plugin GUI runtime only, not idalib/CLI mode.
If unavailable, state that UI context is unavailable and continue with non-UI SQL workflows.

对于类似“我正在查看什么？”、“选中的是什么？”、“屏幕上显示的是什么？”、“看看我正在做的操作”或涉及“当前/这个/那个”的提示，使用专用的

ui-context

技能。

ui-context

负责：

```
get_ui_context_json()
```
的捕获/复用规则
时间参考规则（
```
this
```
与
```
that
```
的区分）
响应模板、示例及 fallback 消息

运行时注意事项：

```
get_ui_context_json()
```
仅在插件GUI运行时可用，idalib/CLI模式下不可用。
如果不可用，需说明UI上下文不可用，并继续使用非UI的SQL工作流。

welcome

Database orientation surface for quick session metadata. This is metadata-only and not a replacement for UI context capture.

Column	Type	Description
`summary`	TEXT	One-line database summary
`processor`	TEXT	Processor/module name
`is_64bit`	INT	1=64-bit database, 0=32-bit
`min_ea`	TEXT	Minimum address in database
`max_ea`	TEXT	Maximum address in database
`start_ea`	TEXT	Entry/start address
`entry_name`	TEXT	Entry symbol name (if known)
`funcs_count`	INT	Number of detected functions
`segments_count`	INT	Number of segments
`names_count`	INT	Number of named addresses
`strings_count`	INT	Current IDA string-list count

sql

SELECT * FROM welcome;

For canonical schema and owner mapping, see

references/schema-catalog.md

用于快速获取会话元数据的数据库概况数据表面。这仅包含元数据，不能替代UI上下文捕获。

列	类型	描述
`summary`	TEXT	数据库单行摘要
`processor`	TEXT	处理器/模块名称
`is_64bit`	INT	1=64位数据库，0=32位数据库
`min_ea`	TEXT	数据库中的最小地址
`max_ea`	TEXT	数据库中的最大地址
`start_ea`	TEXT	入口/起始地址
`entry_name`	TEXT	入口符号名称（若已知）
`funcs_count`	INT	检测到的函数数量
`segments_count`	INT	段的数量
`names_count`	INT	已命名地址的数量
`strings_count`	INT	当前IDA字符串列表的数量

sql

SELECT * FROM welcome;

标准架构及所属技能映射，请查看

references/schema-catalog.md

。

What is IDA and Why SQL?

什么是IDA，为什么使用SQL？

IDA Pro is the industry-standard disassembler and reverse engineering tool. It analyzes compiled binaries (executables, DLLs, firmware) and produces:

Disassembly - Human-readable assembly code
Functions - Detected code boundaries with names
Cross-references - Who calls what, who references what data
Types - Structures, enums, function prototypes
Decompilation - C-like pseudocode (with Hex-Rays plugin)

IDASQL exposes all this analysis data through SQL virtual tables, enabling:

Complex queries across multiple data types (JOINs)
Aggregations and statistics (COUNT, GROUP BY)
Pattern detection across the entire binary
Scriptable analysis without writing IDA plugins or IDAPython scripts

IDA Pro 是行业标准的反汇编与逆向工程工具。它分析编译后的二进制文件（可执行文件、DLL、固件）并生成：

反汇编代码 - 人类可读的汇编代码
函数 - 带有名称的已检测代码边界
交叉引用 - 谁调用了谁、谁引用了哪些数据
类型 - 结构体、枚举、函数原型
反编译结果 - 类C伪代码（需Hex-Rays插件）

IDASQL 通过SQL虚拟表暴露所有这些分析数据，支持：

跨多种数据类型的复杂查询（JOIN操作）
聚合与统计（COUNT、GROUP BY）
全二进制文件范围内的模式检测
无需编写IDA插件或IDAPython脚本即可实现可脚本化分析

Core Concepts for Binary Analysis

二进制分析核心概念

Addresses (ea_t)

地址（ea_t）

Everything in a binary has an address - a memory location where code or data lives. IDA uses

ea_t

(effective address) as unsigned 64-bit integers. SQL shows these as integers; use

printf('0x%X', address)

for hex display.

Address-taking SQL functions accept:

integer EA values (preferred for deterministic scripts)
numeric strings (
```
'4198400'
```
,
```
'0x401000'
```
)
symbol names resolved with
```
get_name_ea(BADADDR, name)
```
(global names)

Quoted numeric strings are for address-taking scalar functions. For table predicates, compare address columns to integer EAs such as

address = 0x401000

Examples:

sql

SELECT decompile('DriverEntry');
SELECT set_type('DriverEntry', 'NTSTATUS DriverEntry(PDRIVER_OBJECT, PUNICODE_STRING);');
SELECT (SELECT comment FROM comments WHERE address = 0x401000 LIMIT 1);

Read address comments from the

comments

table after resolving the target EA.

If a symbol cannot be resolved, SQL functions return an explicit error like:

Could not resolve name to address: <name>

Local label lookup that depends on a specific

from

context is not consulted by default (

BADADDR

resolution). Use explicit numeric EAs when needed.

二进制文件中的所有内容都有一个地址 - 代码或数据所在的内存位置。IDA使用

ea_t

（有效地址）作为无符号64位整数。SQL中显示为整数；可使用

printf('0x%X', address)

转换为十六进制显示。

接收地址的SQL函数支持：

整数EA值（确定性脚本优先使用）
数字字符串（
```
'4198400'
```
、
```
'0x401000'
```
）
通过
```
get_name_ea(BADADDR, name)
```
解析的符号名称（全局名称）

带引号的数字字符串用于接收地址的标量函数。对于表谓词，将地址列与整数EA比较，例如

address = 0x401000

。

示例：

sql

SELECT decompile('DriverEntry');
SELECT set_type('DriverEntry', 'NTSTATUS DriverEntry(PDRIVER_OBJECT, PUNICODE_STRING);');
SELECT (SELECT comment FROM comments WHERE address = 0x401000 LIMIT 1);

解析目标EA后，从

comments

表读取地址注释。

如果符号无法解析，SQL函数会返回明确错误，例如：

Could not resolve name to address: <name>

。

默认情况下，不依赖特定

from

上下文的局部标签查找（

BADADDR

解析）不会被调用。必要时使用明确的数字EA。

Functions

函数

IDA groups code into functions with:

```
address
```
/
```
start_ea
```
- Where the function begins
```
end_ea
```
- Where it ends
```
name
```
- Assigned or auto-generated name (e.g.,
```
main
```
,
```
sub_401000
```
)
```
size
```
- Total bytes in the function

There will be addresses and disassembly listing not belonging to a function. IDASQL can still get the bytes, disassembly listing ranges, etc. For single-EA disassembly (code or data), prefer

disasm_at(ea[, context])

over function-scoped queries.

IDA将代码分组为函数，包含：

```
address
```
/
```
start_ea
```
- 函数起始地址
```
end_ea
```
- 函数结束地址
```
name
```
- 已分配或自动生成的名称（例如
```
main
```
、
```
sub_401000
```
）
```
size
```
- 函数的总字节数

会存在不属于任何函数的地址和反汇编列表。IDASQL仍可获取这些字节、反汇编列表范围等。对于单个EA的反汇编（代码或数据），优先使用

disasm_at(ea[, context])

，而非函数范围的查询。

Cross-References (xrefs)

交叉引用（xrefs）

Binary analysis is about understanding relationships:

Code xrefs - Function calls, jumps between code
Data xrefs - Code reading/writing data locations, or data referring to other data (pointers)
```
from_ea
```
->
```
to_ea
```
represents "address X references address Y" Use table:
```
xrefs(from_ea, to_ea, type, is_code)
```
.

二进制分析的核心是理解关系：

代码交叉引用 - 函数调用、代码间跳转
数据交叉引用 - 代码读写数据位置，或数据引用其他数据（指针）
```
from_ea
```
->
```
to_ea
```
表示“地址X引用地址Y” 使用表：
```
xrefs(from_ea, to_ea, type, is_code)
```
。

Segments

段

Use table:

segments(start_ea, end_ea, name, class, perm)

Memory is divided into segments with different purposes. For example, a typical PE file, has these segments:

```
.text
```
- Executable code (typically)
```
.data
```
- Initialized global data
```
.rdata
```
- Read-only data (strings, constants)
```
.bss
```
- Uninitialized data

Of course, segment names and types can vary. You may query the

segments

table to understand memory layout.

使用表：

segments(start_ea, end_ea, name, class, perm)

。

内存被划分为不同用途的段。例如，典型的PE文件包含以下段：

```
.text
```
- 可执行代码（通常）
```
.data
```
- 已初始化全局数据
```
.rdata
```
- 只读数据（字符串、常量）
```
.bss
```
- 未初始化数据

当然，段名称和类型可能有所不同。可查询

segments

表了解内存布局。

Basic Blocks

基本块

Within a function, basic blocks are straight-line code sequences:

No branches in the middle
Single entry, single exit
Useful for control flow analysis Use table:
```
blocks(start_ea, end_ea, func_ea, size)
```
.

在函数内部，基本块是直线代码序列：

中间无分支
单入口、单出口
适用于控制流分析使用表：
```
blocks(start_ea, end_ea, func_ea, size)
```
。

Decompilation (Hex-Rays)

反编译（Hex-Rays）

The Hex-Rays decompiler converts assembly to C-like pseudocode:

ctree - The Abstract Syntax Tree of decompiled code
lvars - Local variables detected by the decompiler
Much easier to analyze than raw assembly

Core decompiler surfaces:

```
decompile(addr)
```
(PRIMARY read/display surface)
- Returns the entire function as one text block.
- Each output line is prefixed for address grounding:
  - Addressed line:
```
/* 401010 */ ...
```
  - Non-anchored line:
```
/*          */ ...
```
    (no address anchor for that line)
- Use this first when the user asks to "decompile", "show code", "show pseudocode", or "explain function logic".
```
pseudocode
```
table (structured/edit surface)
- Use for line-level filtering (
```
func_addr
```
  ,
```
ea
```
  ,
```
line_num
```
  ) and comment writes keyed by
```
ea + comment_placement
```
  .
- Resolve a writable pseudocode anchor first; do not assume
```
ea == func_addr
```
  .
- Not the preferred display surface for full-function code.
```
ctree
```
and
```
ctree_call_args
```
for AST-level analysis
```
ctree_lvars
```
for local variable rename/type/comment updates

Hex-Rays反编译器将汇编代码转换为类C伪代码：

ctree - 反编译代码的抽象语法树
lvars - 反编译器检测到的局部变量
比原始汇编代码更易于分析

核心反编译数据表面：

```
decompile(addr)
```
（主要读取/展示数据表面）
- 返回整个函数的文本块。
- 每行输出都带有地址前缀，用于定位：
  - 带地址的行：
```
/* 401010 */ ...
```
  - 无锚定地址的行：
```
/*          */ ...
```
    （该行无对应地址锚点）
- 当用户要求“反编译”、“展示代码”、“展示伪代码”或“解释函数逻辑”时，优先使用此函数。
```
pseudocode
```
表（结构化/编辑数据表面）
- 用于按行过滤（
```
func_addr
```
  、
```
ea
```
  、
```
line_num
```
  ），并通过
```
ea + comment_placement
```
  写入注释。
- 先解析可写入的伪代码锚点；不要假设
```
ea == func_addr
```
  。
- 不是展示完整函数代码的首选数据表面。
```
ctree
```
和
```
ctree_call_args
```
用于抽象语法树级别的分析
```
ctree_lvars
```
用于局部变量的重命名/类型/注释更新

Performance Rules

性能规则

CRITICAL: Constraint Pushdown

关键：约束下推

Some tables have optimized filters that use efficient IDA SDK APIs:

Table	Optimized Filter	Without Filter
`instructions`	`func_addr = X`	O(all instructions) - SLOW
`blocks`	`func_ea = X`	O(all blocks)
`xrefs`	`to_ea = X` or `from_ea = X`	O(all xrefs)
`pseudocode`	`func_addr = X`	Decompiles ALL functions
`ctree*`	`func_addr = X`	Decompiles ALL functions

Always filter decompiler tables by
func_addr
!

部分表拥有优化过滤器，可调用高效的IDA SDK API：

表	优化过滤器	无过滤器时
`instructions`	`func_addr = X`	O(所有指令) - 缓慢
`blocks`	`func_ea = X`	O(所有基本块)
`xrefs`	`to_ea = X` 或 `from_ea = X`	O(所有交叉引用)
`pseudocode`	`func_addr = X`	反编译所有函数
`ctree*`	`func_addr = X`	反编译所有函数

务必对反编译表添加
func_addr
约束！

Use Integer Comparisons

使用整数比较

sql

-- SLOW: String comparison
WHERE mnemonic = 'call'

-- FAST: Integer comparison
WHERE itype IN (16, 18)  -- x86 call opcodes

sql

-- 缓慢：字符串比较
WHERE mnemonic = 'call'

-- 快速：整数比较
WHERE itype IN (16, 18)  -- x86 call操作码

O(1) Random Access

O(1) 随机访问

sql

-- SLOW: O(n) - sorts all rows
SELECT address FROM funcs ORDER BY RANDOM() LIMIT 1;

-- FAST: O(1) - direct index access
SELECT address
FROM funcs
WHERE rowid = ABS(RANDOM()) % (SELECT COUNT(*) FROM funcs);

sql

-- 缓慢：O(n) - 对所有行排序
SELECT address FROM funcs ORDER BY RANDOM() LIMIT 1;

-- 快速：O(1) - 直接索引访问
SELECT address
FROM funcs
WHERE rowid = ABS(RANDOM()) % (SELECT COUNT(*) FROM funcs);

CTE-First Mutation Workflow

CTE优先的变更工作流

For instruction lifecycle edits, use a CTE to identify precise targets first, then mutate:

sql

WITH target AS (
    SELECT address
    FROM instructions
    WHERE func_addr = 0x401000
    ORDER BY address DESC
    LIMIT 1
)
DELETE FROM instructions
WHERE address IN (SELECT address FROM target);

SELECT make_code_range(address, end_ea) FROM funcs WHERE address = 0x401000;

This keeps mutation scope explicit and predictable for both humans and agents.

对于指令生命周期编辑，使用CTE先确定精确目标，再执行变更：

sql

WITH target AS (
    SELECT address
    FROM instructions
    WHERE func_addr = 0x401000
    ORDER BY address DESC
    LIMIT 1
)
DELETE FROM instructions
WHERE address IN (SELECT address FROM target);

SELECT make_code_range(address, end_ea) FROM funcs WHERE address = 0x401000;

这能让变更范围对人类和Agent都清晰可预测。

Summary: When to Use What

总结：场景对应工具

Goal	Table/Function
List all functions	`funcs`
Functions by return type	`funcs WHERE return_is_integral = 1`
Functions by arg count	`funcs WHERE arg_count >= N`
Void functions	`funcs WHERE return_is_void = 1`
Pointer-returning functions	`funcs WHERE return_is_ptr = 1`
Functions by calling convention	`funcs WHERE calling_conv = 'fastcall'`
Find who calls what	`xrefs` with `is_code = 1`
Find data references	`xrefs` with `is_code = 0`
Analyze imports	`imports`
Find strings	`strings`
Configure string types	`rebuild_strings(types, minlen)`
Instruction analysis	`instructions WHERE func_addr = X`
Recreate deleted instructions	`make_code(addr)` , `make_code_range(start, end)`
Create function at EA	`INSERT INTO funcs(address) VALUES (...)`
View function disassembly	`disasm_func(addr)` or `disasm_range(start, end)`
View decompiled code	`decompile(addr)`
UI/screen context questions	`ui-context` skill ( `get_ui_context_json()` , plugin UI only)
Edit decompiler comments	`Resolve writable anchor, then UPDATE pseudocode SET comment = '...' WHERE func_addr = X AND ea = Y`
AST pattern matching	`ctree WHERE func_addr = X`
Call patterns	`ctree_v_calls` , `disasm_calls`
Control flow	`ctree_v_loops` , `ctree_v_ifs`
Return value analysis	`ctree_v_returns`
Functions returning specific values	`ctree_v_returns WHERE return_num = 0`
Pass-through functions	`ctree_v_returns WHERE returns_arg = 1`
Wrapper functions	`ctree_v_returns WHERE returns_call_result = 1`
Variable analysis	`ctree_lvars WHERE func_addr = X`
Type information	`types` , `types_members`
Function signatures	`types_func_args` (with type classification)
Functions by return type	`types_func_args WHERE arg_index = -1`
Typedef-aware type queries	`types_func_args` (surface vs resolved)
Hidden pointer types	`types_func_args WHERE is_ptr = 0 AND is_ptr_resolved = 1`
Manage breakpoints	`breakpoints` (full CRUD)
Modify segments	`segments` (INSERT/UPDATE/DELETE)
Rename decompiler labels	`UPDATE ctree_labels SET name=... WHERE func_addr=... AND label_num=...`
Delete instructions	`instructions` (DELETE converts to unexplored bytes)
Recreate instructions	`make_code` , `make_code_range`
Bulk patch from file bytes	`load_file_bytes(path, file_offset, address, size[, patchable])`
EA to physical offset mapping	`bytes.fpos` on mapped byte rows ( `NULL` means no file offset)
Create types	`types` (INSERT struct/union/enum)
Add struct members	`types_members` (INSERT)
Add enum values	`types_enum_values` (INSERT)
Modify database	`funcs` , `names` , `comments` , `bookmarks` (INSERT/UPDATE/DELETE)
Store custom key-value data	`netnode_kv` (full CRUD, persists in IDB)
Entity search (structured)	`grep` skill + `grep WHERE pattern = '...'`

Remember: Always use

func_addr = X

constraints on instruction and decompiler tables for acceptable performance.

目标	表/函数
列出所有函数	`funcs`
按返回类型筛选函数	`funcs WHERE return_is_integral = 1`
按参数数量筛选函数	`funcs WHERE arg_count >= N`
无返回值函数	`funcs WHERE return_is_void = 1`
返回指针的函数	`funcs WHERE return_is_ptr = 1`
按调用约定筛选函数	`funcs WHERE calling_conv = 'fastcall'`
查找调用关系	`xrefs` 搭配 `is_code = 1`
查找数据引用	`xrefs` 搭配 `is_code = 0`
分析导入项	`imports`
查找字符串	`strings`
配置字符串类型	`rebuild_strings(types, minlen)`
指令分析	`instructions WHERE func_addr = X`
恢复已删除指令	`make_code(addr)` 、 `make_code_range(start, end)`
在指定EA创建函数	`INSERT INTO funcs(address) VALUES (...)`
查看函数反汇编	`disasm_func(addr)` 或 `disasm_range(start, end)`
查看反编译代码	`decompile(addr)`
UI/屏幕上下文问题	`ui-context` 技能（ `get_ui_context_json()` ，仅插件UI可用）
编辑反编译注释	先解析可写入锚点，再执行 `UPDATE pseudocode SET comment = '...' WHERE func_addr = X AND ea = Y`
抽象语法树模式匹配	`ctree WHERE func_addr = X`
调用模式	`ctree_v_calls` 、 `disasm_calls`
控制流	`ctree_v_loops` 、 `ctree_v_ifs`
返回值分析	`ctree_v_returns`
返回特定值的函数	`ctree_v_returns WHERE return_num = 0`
透传函数	`ctree_v_returns WHERE returns_arg = 1`
包装函数	`ctree_v_returns WHERE returns_call_result = 1`
变量分析	`ctree_lvars WHERE func_addr = X`
类型信息	`types` 、 `types_members`
函数签名	`types_func_args` （带类型分类）
按返回类型筛选函数	`types_func_args WHERE arg_index = -1`
支持类型别名的类型查询	`types_func_args` （表面类型 vs 解析后类型）
隐藏指针类型	`types_func_args WHERE is_ptr = 0 AND is_ptr_resolved = 1`
管理断点	`breakpoints` （完整CRUD操作）
修改段	`segments` （INSERT/UPDATE/DELETE）
重命名反编译标签	`UPDATE ctree_labels SET name=... WHERE func_addr=... AND label_num=...`
删除指令	`instructions` （DELETE会将其转换为未探索字节）
重建指令	`make_code` 、 `make_code_range`
从文件字节批量打补丁	`load_file_bytes(path, file_offset, address, size[, patchable])`
EA与物理偏移映射	已映射字节行的 `bytes.fpos` （ `NULL` 表示无文件偏移）
创建类型	`types` （INSERT结构体/联合体/枚举）
添加结构体成员	`types_members` （INSERT）
添加枚举值	`types_enum_values` （INSERT）
修改数据库	`funcs` 、 `names` 、 `comments` 、 `bookmarks` （INSERT/UPDATE/DELETE）
存储自定义键值数据	`netnode_kv` （完整CRUD操作，持久化于IDB）
实体搜索（结构化）	`grep` 技能 + `grep WHERE pattern = '...'`

注意： 针对指令和反编译表，务必添加

func_addr = X

约束以保证可接受的性能。

Error Handling

错误处理

No Hex-Rays license: Decompiler tables (
```
pseudocode
```
,
```
ctree*
```
,
```
ctree_lvars
```
) will be empty or unavailable
No constraint on decompiler tables: Query will be extremely slow (decompiles all functions)
Invalid address: Containing-function table lookups return no row; use a scalar subquery when you need a nullable scalar result
Missing function: JOINs may return fewer rows than expected

无Hex-Rays许可证： 反编译表（
```
pseudocode
```
、
```
ctree*
```
、
```
ctree_lvars
```
）将为空或不可用
反编译表无约束： 查询会极慢（反编译所有函数）
无效地址： 包含该地址的函数表查询将返回空行；需要可空标量结果时，使用标量子查询
函数缺失： JOIN操作返回的行数可能少于预期