annotations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This skill is your guide for editing IDA databases through idasql. Use it whenever you need to annotate, rename, retype, comment, or otherwise modify decompiled output, disassembly, or type information. Every edit operation follows the Mandatory Mutation Loop (see

connect

Global Agent Contracts).

本技能是你通过idasql编辑IDA数据库的指南。当你需要添加注释、重命名、重新定义类型、添加说明或修改反编译输出、汇编代码或类型信息时，均可使用本技能。所有编辑操作均遵循强制变更循环（详见

connect

全局Agent协议）。

Trigger Intents

触发场景

Use this skill when user asks to:

add/edit comments (pseudocode, disassembly, function summaries)
rename symbols or local variables
apply types/enums/struct representations
create/update bookmarks for investigation workflow
make pseudocode read more like source
prepare decompiled code for side-by-side review against source
annotate a function end-to-end, not just add one comment

Route to:

```
decompiler
```
for analysis before editing
```
types
```
when declarations or struct models need construction
```
re-source
```
for recursive narrative/source recovery passes

当用户提出以下需求时使用本技能：

添加/编辑注释（伪代码、汇编代码、函数摘要）
重命名符号或局部变量
应用类型/枚举/结构体表示
创建/更新书签以优化调查流程
让伪代码更接近源代码风格
准备反编译代码以便与源代码进行并排审阅
对函数进行端到端注释，而非仅添加单条注释

Do This First (Warm-Start Sequence)

先执行以下步骤（预热启动流程）

sql

-- 1) Confirm target row/function before editing
SELECT * FROM funcs WHERE address = 0x401000;

-- 2) Inspect current comment state
SELECT ea, line, comment
FROM pseudocode
WHERE func_addr = 0x401000
LIMIT 30;

-- 3) Inspect existing disassembly comments
SELECT * FROM comments WHERE address BETWEEN 0x401000 AND 0x401100;

Interpretation guidance:

Never edit blind: validate exact row identity before mutation.
Prefer deterministic keys (
```
func_addr + ea
```
,
```
idx
```
,
```
slot
```
) over fuzzy name matches.

sql

-- 1) 编辑前确认目标行/函数
SELECT * FROM funcs WHERE address = 0x401000;

-- 2) 检查当前注释状态
SELECT ea, line, comment
FROM pseudocode
WHERE func_addr = 0x401000
LIMIT 30;

-- 3) 检查现有汇编代码注释
SELECT * FROM comments WHERE address BETWEEN 0x401000 AND 0x401100;

操作指导：

切勿盲目编辑：在执行变更前务必验证目标行的准确标识。
优先使用确定性键（
```
func_addr + ea
```
、
```
idx
```
、
```
slot
```
）而非模糊名称匹配。

Failure and Recovery

故障与恢复

Update appeared to "do nothing":
- Re-read target row, refresh decompile view, verify placement fields.
Wrong target mutated:
- Tighten predicate and re-run read-first step before retry.
Enum/struct rendering did not change:
- Confirm type/numform/union-selection support and target context.

编辑后看似无变化：
- 重新读取目标行，刷新反编译视图，验证位置字段。
错误修改了目标对象：
- 收紧查询条件，重新执行读取步骤后再重试。
枚举/结构体显示未变化：
- 确认类型/数字格式/联合选择的支持情况及目标上下文。

Handoff Patterns

技能移交规则

```
annotations
```
->
```
decompiler
```
when semantic meaning is unclear.
```
annotations
```
->
```
types
```
when edits imply missing declarations.
```
annotations
```
->
```
re-source
```
when function-level notes must become recursive campaign notes.

当语义含义不明确时，从
```
annotations
```
移交至
```
decompiler
```
。
当编辑操作暗示存在缺失声明时，从
```
annotations
```
移交至
```
types
```
。
当函数级注释需要转化为递归式全局注释时，从
```
annotations
```
移交至
```
re-source
```
。

Annotate a Function Contract

注释函数协议

Treat

annotate this function

as a full-function workflow, not a single comment operation.

Default behavior:

inspect the current decompilation and local/label state
apply types/prototypes that make the function read more like source
rename locals, globals, and labels when they materially improve readability
add targeted line comments where they help interpretation
always finish with exactly one repeatable function comment summary on
```
funcs.rpt_comment
```
refresh with
```
decompile(addr, 1)
```
and verify the result

Use narrower intents only when the user asks narrowly:

```
add a comment
```
-> comment only
```
func-summary
```
/
```
function summary
```
-> summary only
```
annotate this function
```
-> full cleanup plus summary

Why the summary is mandatory:

it orients a human reviewer immediately
it creates semantic/searchable program knowledge for later whole-program understanding

将“注释此函数”视为完整的函数处理流程，而非单一注释操作。

默认行为：

检查当前反编译结果及局部变量/标签状态
应用能让函数更接近源代码风格的类型/原型
当重命名局部变量、全局变量和标签能显著提升可读性时进行重命名
在有助于理解的位置添加针对性行注释
始终在
```
funcs.rpt_comment
```
中添加一条可重复的函数摘要注释
使用
```
decompile(addr, 1)
```
刷新并验证结果

仅当用户明确提出窄范围需求时执行对应操作：

“添加一条注释”仅执行注释操作
“func-summary”/“function summary”仅生成摘要
“注释此函数”执行完整清理并生成摘要

摘要为必填项的原因：

能让人工审阅者快速了解函数定位
为后续全程序理解创建可语义搜索的程序知识

Editing Function Comments

编辑函数注释

True IDA function comments live on

funcs

, not on

pseudocode

and not on the address-level

comments

table.

Use:

```
funcs.comment
```
for the regular function comment
```
funcs.rpt_comment
```
for the repeatable function comment

Default function-summary behavior:

treat singular

add function comment

UPDATE funcs SET rpt_comment = ...

use
```
funcs.comment
```
only when the user explicitly asks for a non-repeatable function comment
use a heading-style
```
pseudocode
```
block comment only when the user explicitly asks for a decompiler note/summary rather than a true function comment

Canonical SQL pattern:

sql

SELECT address, name, comment, rpt_comment
FROM funcs
WHERE address = 0x401000;

UPDATE funcs
SET rpt_comment = 'One-paragraph summary of what the function does, inputs/outputs, and key behavior.'
WHERE address = 0x401000;

真正的IDA函数注释存储在

funcs

表中，而非

pseudocode

表或地址级别的

comments

表。

使用规则：

```
funcs.comment
```
用于常规函数注释
```
funcs.rpt_comment
```
用于可重复的函数注释

默认函数摘要行为：

将单一的“添加函数注释”视为
```
UPDATE funcs SET rpt_comment = ...
```
操作
仅当用户明确要求非重复性函数注释时，使用
```
funcs.comment
```
仅当用户明确要求反编译器注释/摘要而非真正的函数注释时，使用标题风格的
```
pseudocode
```
块注释

标准SQL示例：

sql

SELECT address, name, comment, rpt_comment
FROM funcs
WHERE address = 0x401000;

UPDATE funcs
SET rpt_comment = '一段描述函数功能、输入/输出及关键行为的摘要。'
WHERE address = 0x401000;

Editing Decompiler Comments (Pseudocode)

编辑反编译器注释（伪代码）

The

pseudocode

table is the editing surface for decompiler comments. Use

decompile(addr)

to view; use the table to edit. For full table schema, see

decompiler

skill.

Important separation:

```
pseudocode.comment
```
edits Hex-Rays decompiler comments only.
```
pseudocode
```
writes never call
```
set_func_cmt()
```
.
Use
```
funcs.comment
```
/
```
funcs.rpt_comment
```
for true function comments.

Writable columns:

comment

comment_placement

. Placements:

semi

(after

block1

(own line above),

block2

curly1

curly2

colon

case

else

do

Anchor guidance:

Prefer a concrete pseudocode statement row, not a guessed function-entry row.
If an
```
ea
```
maps to multiple pseudocode rows (
```
{
```
, statement,
```
}
```
), resolve a unique non-brace anchor first.
Use
```
line_num
```
only to inspect candidate rows. Comment writes persist by
```
ea + comment_placement
```
; shared-
```
ea
```
rows need extra care, so do not assume every displayed shared-
```
ea
```
row is independently writable.

Inspect anchors before writing:

sql

SELECT line_num, ea, line, comment
FROM pseudocode
WHERE func_addr = 0x401000
ORDER BY line_num;

sql

-- The example UPDATEs below assume 0x401020 is an already resolved writable
-- non-brace anchor from the inspection query above; do not substitute func_addr.
-- Edit: Add inline comment to decompiled code
UPDATE pseudocode SET comment_placement = 'semi',
                      comment = 'buffer overflow here'
WHERE func_addr = 0x401000 AND ea = 0x401020;

-- Edit: Add block comment (own line above statement)
UPDATE pseudocode SET comment_placement = 'block1', comment = 'vulnerable call'
WHERE func_addr = 0x401000 AND ea = 0x401020;

-- Edit: Delete comments at a resolved unique anchor
-- Warning: comment = NULL currently clears all placements at that ea.
UPDATE pseudocode SET comment = NULL
WHERE func_addr = 0x401000 AND ea = 0x401020;

-- Read edited pseudocode with comments
SELECT ea, line, comment FROM pseudocode WHERE func_addr = 0x401000;

pseudocode

表是编辑反编译器注释的操作面。使用

decompile(addr)

查看内容；使用该表进行编辑。完整表结构详见

decompiler

技能。

重要区分：

```
pseudocode.comment
```
仅编辑Hex-Rays反编译器注释。
```
pseudocode
```
写入操作绝不会调用
```
set_func_cmt()
```
。
真正的函数注释请使用
```
funcs.comment
```
/
```
funcs.rpt_comment
```
。

可写入列：

comment

、

comment_placement

。注释位置选项：

semi

（位于

后）、

block1

（位于语句上方单独一行）、

block2

、

curly1

、

curly2

、

colon

、

case

、

else

、

do

。

锚点选择指导：

优先选择具体的伪代码语句行，而非猜测的函数入口行。
如果一个
```
ea
```
对应多个伪代码行（
```
{
```
、语句、
```
}
```
），先确定一个唯一的非大括号锚点。
仅使用
```
line_num
```
检查候选行。注释写入通过
```
ea + comment_placement
```
持久化；共享
```
ea
```
的行需要额外注意，请勿假设所有显示的共享
```
ea
```
行均可独立编辑。

写入前检查锚点：

sql

SELECT line_num, ea, line, comment
FROM pseudocode
WHERE func_addr = 0x401000
ORDER BY line_num;

sql

-- 以下UPDATE示例假设0x401020是从上述检查查询中确认的可编辑非大括号锚点；请勿替换为func_addr。
-- 编辑：为反编译代码添加行内注释
UPDATE pseudocode SET comment_placement = 'semi',
                      comment = '此处存在缓冲区溢出'
WHERE func_addr = 0x401000 AND ea = 0x401020;

-- 编辑：添加块注释（语句上方单独一行）
UPDATE pseudocode SET comment_placement = 'block1', comment = '易受攻击的调用'
WHERE func_addr = 0x401000 AND ea = 0x401020;

-- 编辑：删除已确认唯一锚点处的注释
-- 注意：comment = NULL会清除该ea处的所有位置注释。
UPDATE pseudocode SET comment = NULL
WHERE func_addr = 0x401000 AND ea = 0x401020;

-- 读取带有注释的编辑后伪代码
SELECT ea, line, comment FROM pseudocode WHERE func_addr = 0x401000;

Cleaning Up Orphan Decompiler Comments

清理孤立的反编译器注释

If the database contains stale decompiler comments that no longer attach to current pseudocode, use the orphan comment surfaces instead of trying to clear them through

pseudocode

Read-first pattern:

sql

SELECT func_addr, func_name, orphan_count
FROM pseudocode_v_orphan_comment_groups
ORDER BY orphan_count DESC
LIMIT 20;

SELECT ea, comment_placement, orphan_comment
FROM pseudocode_orphan_comments
WHERE func_addr = 0x401000
ORDER BY ea, comment_placement;

Delete-only mutation pattern:

sql

UPDATE pseudocode_orphan_comments
SET orphan_comment = NULL
WHERE func_addr = 0x401000
  AND ea = 0x401020
  AND comment_placement = 'semi';

Notes:

```
pseudocode_orphan_comments
```
is delete-only.
Non-empty writes are rejected.
Use the grouped surface for triage, then the precise table for cleanup.
After triage, switch to
```
WHERE func_addr = ...
```
on both surfaces for the fast path.

如果数据库中存在不再关联当前伪代码的过期反编译器注释，请使用孤立注释操作面，而非尝试通过

pseudocode

表清除它们。

先读取再操作的模式：

sql

SELECT func_addr, func_name, orphan_count
FROM pseudocode_v_orphan_comment_groups
ORDER BY orphan_count DESC
LIMIT 20;

SELECT ea, comment_placement, orphan_comment
FROM pseudocode_orphan_comments
WHERE func_addr = 0x401000
ORDER BY ea, comment_placement;

仅删除的变更模式：

sql

UPDATE pseudocode_orphan_comments
SET orphan_comment = NULL
WHERE func_addr = 0x401000
  AND ea = 0x401020
  AND comment_placement = 'semi';

注意事项：

```
pseudocode_orphan_comments
```
仅支持删除操作。
拒绝非空写入操作。
使用分组操作面进行分类筛选，再使用精确表进行清理。
分类筛选后，在两个操作面上均使用
```
WHERE func_addr = ...
```
以提升效率。

Function Summary (func-summary)

函数摘要（func-summary）

Use

function summary

and

func-summary

as equivalent intent.

Trigger contract:

If the user says
```
function summary
```
or
```
func-summary
```
, add or update exactly one repeatable function comment on
```
funcs.rpt_comment
```
.
If the user says
```
add function comment
```
(singular) without line-specific targets, treat it as a repeatable function comment update.
If the user explicitly asks for a decompiler heading note or pseudocode block comment, use
```
pseudocode.comment
```
with a resolved writable anchor instead.
Only add many line comments when the user explicitly asks for line-by-line/deep annotation.

Default behavior:

Write the summary to
```
funcs.rpt_comment
```
.
Use
```
funcs.comment
```
only when the user explicitly asks for a non-repeatable function comment.
Do not expand into line-by-line annotation unless the user explicitly asks for deep annotation.
When a function is being fully annotated, always add/update this summary as the last semantic step.

Length guidance:

Use one paragraph minimum when applicable.
For trivial wrappers/thunks, a shorter concise summary is acceptable.
Capture function role, key inputs/outputs, important state changes, and notable side effects when relevant.

Canonical SQL pattern:

sql

SELECT address, name, comment, rpt_comment
FROM funcs
WHERE address = 0x401000;

UPDATE funcs
SET rpt_comment = 'One-paragraph summary of what the function does, inputs/outputs, and key behavior.'
WHERE address = 0x401000;

Prompt examples:

```
function summary 0x401000
```
```
func-summary DriverEntry
```
```
func-summary this function
```

将

function summary

和

func-summary

视为相同触发意图。

触发协议：

如果用户说
```
function summary
```
或
```
func-summary
```
，在
```
funcs.rpt_comment
```
中添加或更新一条可重复的函数注释。
如果用户说“添加函数注释”（单数）且未指定行级目标，将其视为更新可重复函数注释。
如果用户明确要求反编译器标题注释或伪代码块注释，使用已确认的可编辑锚点更新
```
pseudocode.comment
```
。
仅当用户明确要求逐行/深度注释时，才添加多行注释。

默认行为：

将摘要写入
```
funcs.rpt_comment
```
。
仅当用户明确要求非重复性函数注释时，使用
```
funcs.comment
```
。
除非用户明确要求深度注释，否则不扩展为逐行注释。
当对函数进行完整注释时，始终将更新摘要作为最后一个语义步骤。

长度指导：

适用时至少使用一段文字。
对于简单的包装函数/跳转函数，可使用更简洁的摘要。
捕获函数角色、关键输入/输出、重要状态变化及相关副作用（如有）。

标准SQL示例：

sql

SELECT address, name, comment, rpt_comment
FROM funcs
WHERE address = 0x401000;

UPDATE funcs
SET rpt_comment = '一段描述函数功能、输入/输出及关键行为的摘要。'
WHERE address = 0x401000;

触发示例：

```
function summary 0x401000
```
```
func-summary DriverEntry
```
```
func-summary this function
```

Editing Disassembly Comments

编辑汇编代码注释

Read disassembly-level comments from the

comments

table:

sql

SELECT COALESCE(NULLIF(comment, ''), NULLIF(rpt_comment, '')) AS comment
FROM comments
WHERE address = 0x401000
LIMIT 1;

The

comments

table supports INSERT, UPDATE, and DELETE:

Table	INSERT	UPDATE columns	DELETE
`comments`	Yes	`comment` , `rpt_comment`	Yes

sql

INSERT INTO comments(address, comment) VALUES (0x401000, 'regular comment');
INSERT INTO comments(address, rpt_comment) VALUES (0x401000, 'repeatable comment');
UPDATE comments SET comment = 'updated comment' WHERE address = 0x401000;
DELETE FROM comments WHERE address = 0x401000;

Notes:

```
comments
```
edits address comments via
```
set_cmt()
```
.

funcs.comment

funcs.rpt_comment

edit true function comments via

set_func_cmt()

从

comments

表读取汇编级注释：

sql

SELECT COALESCE(NULLIF(comment, ''), NULLIF(rpt_comment, '')) AS comment
FROM comments
WHERE address = 0x401000
LIMIT 1;

comments

表支持INSERT、UPDATE和DELETE操作：

表名	INSERT	可更新列	DELETE
`comments`	支持	`comment` , `rpt_comment`	支持

sql

INSERT INTO comments(address, comment) VALUES (0x401000, '常规注释');
INSERT INTO comments(address, rpt_comment) VALUES (0x401000, '可重复注释');
UPDATE comments SET comment = '更新后的注释' WHERE address = 0x401000;
DELETE FROM comments WHERE address = 0x401000;

注意事项：

```
comments
```
表通过
```
set_cmt()
```
编辑地址注释。

funcs.comment

funcs.rpt_comment

通过

set_func_cmt()

编辑真正的函数注释。

bookmarks

书签

The

bookmarks

table supports full CRUD for editing marked positions:

Column	Type	Description
`slot`	INT	Bookmark slot index
`address`	INT	Bookmarked address
`description`	TEXT	Bookmark description

sql

-- List all bookmarks
SELECT printf('0x%X', address) as addr, description FROM bookmarks;

-- Edit: Add bookmark
INSERT INTO bookmarks (address, description) VALUES (0x401000, 'interesting branch');

-- Edit: Update bookmark description
UPDATE bookmarks SET description = 'confirmed branch' WHERE slot = 0;

-- Edit: Delete bookmark
DELETE FROM bookmarks WHERE slot = 0;

For canonical schema and owner mapping, see

../connect/references/schema-catalog.md

(

bookmarks

bookmarks

表支持书签标记位置的完整CRUD操作：

列名	类型	描述
`slot`	INT	书签槽索引
`address`	INT	书签地址
`description`	TEXT	书签描述

sql

-- 列出所有书签
SELECT printf('0x%X', address) as addr, description FROM bookmarks;

-- 编辑：添加书签
INSERT INTO bookmarks (address, description) VALUES (0x401000, '值得关注的分支');

-- 编辑：更新书签描述
UPDATE bookmarks SET description = '已确认的分支' WHERE slot = 0;

-- 编辑：删除书签
DELETE FROM bookmarks WHERE slot = 0;

完整表结构及所有者映射详见

../connect/references/schema-catalog.md

中的

bookmarks

部分。

Editing Local Variables (Rename, Retype, Comment)

编辑局部变量（重命名、重新定义类型、添加注释）

The

ctree_lvars

table is the editing surface for decompiler local variables. Writable columns:

name

type

comment

. For full table schema, see

decompiler

skill.

Local-variable edit guidance:

Inspect/select one deterministic
```
idx
```
, then update by
```
func_addr + idx
```
.

Use

UPDATE ctree_lvars SET name = ...

type = ...

, or

comment = ...

for local edits.

For old name-based workflows, first query the candidate rows by
```
func_addr + name
```
, choose one
```
idx
```
, then update by
```
idx
```
.

sql

-- Inspect current locals before renaming
SELECT idx, name, type, comment
FROM ctree_lvars
WHERE func_addr = 0x401000
ORDER BY idx;

-- Edit: Rename a local variable by index (canonical, deterministic)
UPDATE ctree_lvars SET name = 'buffer_size' WHERE func_addr = 0x401000 AND idx = 2;

-- Edit: Rename by current name after selecting one deterministic idx
UPDATE ctree_lvars SET name = 'buffer_size'
WHERE func_addr = 0x401000
  AND idx = (
    SELECT idx FROM ctree_lvars
    WHERE func_addr = 0x401000 AND name = 'v2'
    ORDER BY idx LIMIT 1
  );

-- Edit: Set local-variable comment by index
UPDATE ctree_lvars SET comment = 'points to decrypted buffer' WHERE func_addr = 0x401000 AND idx = 2;

-- Edit: Change variable type
UPDATE ctree_lvars SET type = 'char *'
WHERE func_addr = 0x401000 AND idx = 2;

ctree_lvars

表是编辑反编译器局部变量的操作面。可写入列：

name

、

type

、

comment

。完整表结构详见

decompiler

技能。

局部变量编辑指导：

检查/选择一个确定性的
```
idx
```
，然后通过
```
func_addr + idx
```
进行更新。

使用

UPDATE ctree_lvars SET name = ...

、

type = ...

或

comment = ...

进行局部编辑。

对于旧的基于名称的工作流，先通过
```
func_addr + name
```
查询候选行，选择一个
```
idx
```
，再通过
```
idx
```
进行更新。

sql

-- 重命名前检查当前局部变量
SELECT idx, name, type, comment
FROM ctree_lvars
WHERE func_addr = 0x401000
ORDER BY idx;

-- 编辑：通过索引重命名局部变量（标准、确定性方式）
UPDATE ctree_lvars SET name = 'buffer_size' WHERE func_addr = 0x401000 AND idx = 2;

-- 编辑：选择确定性idx后按当前名称重命名
UPDATE ctree_lvars SET name = 'buffer_size'
WHERE func_addr = 0x401000
  AND idx = (
    SELECT idx FROM ctree_lvars
    WHERE func_addr = 0x401000 AND name = 'v2'
    ORDER BY idx LIMIT 1
  );

-- 编辑：通过索引设置局部变量注释
UPDATE ctree_lvars SET comment = '指向解密后的缓冲区' WHERE func_addr = 0x401000 AND idx = 2;

-- 编辑：修改变量类型
UPDATE ctree_lvars SET type = 'char *'
WHERE func_addr = 0x401000 AND idx = 2;

Editing Decompiler Labels

编辑反编译器标签

Read the current labels first, then rename the exact label you observed. Prefer

label_num

identity over guessing from line text.

sql

-- Inspect labels before renaming
SELECT label_num, name, printf('0x%X', item_ea) AS item_ea
FROM ctree_labels
WHERE func_addr = 0x401000
ORDER BY label_num;

-- Rename deterministically by label number
UPDATE ctree_labels SET name = 'fail' WHERE func_addr = 0x401000 AND label_num = 12;

-- Equivalent UPDATE path
UPDATE ctree_labels
SET name = 'fail'
WHERE func_addr = 0x401000 AND label_num = 12;

先读取当前标签，然后重命名你所观察到的准确标签。优先使用

label_num

标识，而非通过行文本猜测。

sql

-- 重命名前检查标签
SELECT label_num, name, printf('0x%X', item_ea) AS item_ea
FROM ctree_labels
WHERE func_addr = 0x401000
ORDER BY label_num;

-- 通过标签编号确定性重命名
UPDATE ctree_labels SET name = 'fail' WHERE func_addr = 0x401000 AND label_num = 12;

-- 等效的UPDATE方式
UPDATE ctree_labels
SET name = 'fail'
WHERE func_addr = 0x401000 AND label_num = 12;

Editing Types (Create, Modify, Apply)

编辑类型（创建、修改、应用）

For type creation, member CRUD, enum values,

parse_decls()

set_type()

, and name writes via

names

funcs

, see

types

skill.

Quick apply patterns used in annotation workflows:

sql

-- Apply type to a function
UPDATE funcs SET prototype = 'void __fastcall exec_command(command_t *cmd);'
WHERE address = 0x140001BD0;

-- Apply via set_type function
SELECT set_type(0x140001BD0, 'void __fastcall exec_command(command_t *cmd);');

关于类型创建、成员CRUD、枚举值、

parse_decls()

、

set_type()

及通过

names

funcs

写入名称的操作，详见

types

技能。

注释工作流中常用的快速应用模式：

sql

-- 为函数应用类型
UPDATE funcs SET prototype = 'void __fastcall exec_command(command_t *cmd);'
WHERE address = 0x140001BD0;

-- 通过set_type函数应用类型
SELECT set_type(0x140001BD0, 'void __fastcall exec_command(command_t *cmd);');

Editing Operand Representation (Enum/Struct in Disassembly)

编辑操作数表示（汇编中的枚举/结构体）

The

instructions

table

operand*_format_spec

columns allow editing operand display:

sql

-- Edit: Apply enum representation to operand 1
UPDATE instructions
SET operand1_format_spec = 'enum:MY_ENUM'
WHERE address = 0x401020;

-- Edit: Apply struct-offset representation
UPDATE instructions
SET operand0_format_spec = 'stroff:MY_STRUCT,delta=0'
WHERE address = 0x401030;

-- Edit: Clear representation back to plain
UPDATE instructions
SET operand1_format_spec = 'clear'
WHERE address = 0x401020;

instructions

表的

operand*_format_spec

列允许编辑操作数显示方式：

sql

-- 编辑：为操作数1应用枚举表示
UPDATE instructions
SET operand1_format_spec = 'enum:MY_ENUM'
WHERE address = 0x401020;

-- 编辑：应用结构体偏移表示
UPDATE instructions
SET operand0_format_spec = 'stroff:MY_STRUCT,delta=0'
WHERE address = 0x401030;

-- 编辑：清除表示方式恢复为默认
UPDATE instructions
SET operand1_format_spec = 'clear'
WHERE address = 0x401020;

Editing Union Selection in Decompiled Code

编辑反编译代码中的联合选择

For union selection helpers (

set_union_selection*

get_union_selection*

), see

decompiler

skill.

关于联合选择辅助函数（

set_union_selection*

、

get_union_selection*

），详见

decompiler

技能。

Editing Number Format (Enum Rendering in Decompiled Code)

编辑数字格式（反编译代码中的枚举渲染）

Recommended: Retype the variable to an enum type — IDA's decompiler will then automatically render all constants using enum names:

sql

-- 1. Define the enum type (skip if it already exists)
SELECT parse_decls('typedef enum { DLL_PROCESS_DETACH=0, DLL_PROCESS_ATTACH=1 } fdw_reason_t;');

-- 2. Retype the parameter/variable
UPDATE ctree_lvars SET type = 'fdw_reason_t'
WHERE func_addr = 0x180001050 AND idx = 1;

-- 3. Verify
SELECT decompile(0x180001050, 1);

For per-operand numform control (

set_numform*

get_numform*

), see

decompiler

skill.

推荐方式： 将变量重新定义为枚举类型——IDA反编译器会自动使用枚举名称渲染所有常量：

sql

-- 1. 定义枚举类型（已存在则跳过）
SELECT parse_decls('typedef enum { DLL_PROCESS_DETACH=0, DLL_PROCESS_ATTACH=1 } fdw_reason_t;');

-- 2. 重新定义参数/变量类型
UPDATE ctree_lvars SET type = 'fdw_reason_t'
WHERE func_addr = 0x180001050 AND idx = 1;

-- 3. 验证
SELECT decompile(0x180001050, 1);

关于逐操作数数字格式控制（

set_numform*

、

get_numform*

），详见

decompiler

技能。

Mandatory Mutation Loop (For All Edits)

强制变更循环（所有编辑通用）

Follow the read -> edit -> refresh -> verify cycle defined in
connect
Global Agent Contracts.

遵循
connect
全局Agent协议中定义的读取 -> 编辑 -> 刷新 -> 验证循环。

Performance Tips for Batch Editing

批量编辑性能技巧

When editing many functions or annotations, keep these costs in mind:

decompile(addr, 1)
triggers a full re-decompilation (~50-200ms per function). When editing multiple items in the same function, batch all edits before the refresh:

sql

-- Good: structural typing first, then refresh, then naming cleanup
UPDATE ctree_lvars SET type = 'MY_CTX *' WHERE func_addr = 0x401000 AND idx = 0;
SELECT decompile(0x401000, 1);
UPDATE ctree_lvars SET name = 'ctx' WHERE func_addr = 0x401000 AND idx = 0;
UPDATE ctree_lvars SET name = 'size' WHERE func_addr = 0x401000 AND idx = 1;
SELECT decompile(0x401000, 1);  -- final refresh after cleanup

pseudocode
comment writes are lightweight — they persist to IDA's user comments store without triggering re-decompilation. You can write comments to many functions without calling
```
decompile(addr, 1)
```
between each.
ctree_lvars
type changes invalidate the decompiler cache — after changing a variable type, refresh before you trust
```
idx
```
/name-based cleanup. The decompiler may split locals or re-render expressions.
save_database()
can be costly on large databases. Batch all writes and save once at the end of an annotation campaign, not after each edit.

当编辑多个函数或注释时，请留意以下性能要点：

decompile(addr, 1)
会触发完整的重新反编译（每个函数约50-200毫秒）。当编辑同一函数中的多个项时，请先批量完成所有编辑再刷新：

sql

-- 推荐顺序：先设置结构类型，再刷新，最后清理命名
UPDATE ctree_lvars SET type = 'MY_CTX *' WHERE func_addr = 0x401000 AND idx = 0;
SELECT decompile(0x401000, 1);
UPDATE ctree_lvars SET name = 'ctx' WHERE func_addr = 0x401000 AND idx = 0;
UPDATE ctree_lvars SET name = 'size' WHERE func_addr = 0x401000 AND idx = 1;
SELECT decompile(0x401000, 1);  -- 清理完成后最终刷新

pseudocode
注释写入操作轻量——它们会持久化到IDA的用户注释存储中，不会触发重新反编译。你可以在多个函数中写入注释，无需在每次写入后调用
```
decompile(addr, 1)
```
。
ctree_lvars
类型变更会使反编译器缓存失效——修改变量类型后，在信任基于
```
idx
```
/名称的清理操作前请先刷新。反编译器可能会拆分局部变量或重新渲染表达式。
save_database()
在大型数据库上开销较大。批量完成所有写入操作后，在注释流程结束时保存一次即可，无需每次编辑后都保存。

Additional Resources

额外资源

For full cleanup workflows, bulk annotation patterns, and complete worked examples: references/annotation-workflows.md

完整清理工作流、批量注释模式及完整示例：references/annotation-workflows.md