适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：
crates/cheng-nodes/src/nodes/builtin/tools/code_index、crates/cheng-code-index/src
建立在已索引工作区之上的代码智能：跳转到定义、查找全部引用、在项目范围内检索符号。 它们回答的是 grep 回答不了的结构性问题 —— 引用查找返回的是调用点，而不是字符串匹配。 这些节点都依赖工作区索引，所以查询结果为空时先看 tools/code_index_status： 未建索引或索引过期，表现出来和”符号不存在”一模一样。
代码索引状态 — tools/code_index_status
报告工作区的代码智能索引状态（文件/符号/引用计数、生命周期、解析器版本），并可选地执行显式增量（重新）索引，阻塞或异步。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
reindex |
boolean | — | false |
在报告状态前运行（增量）工作区索引。默认 false：仅查询状态，从不隐式触发索引。 |
reindex_mode |
enum | — | null |
reindex=true 时：’blocking’（默认，等待完成）或 ‘async’（入队后台任务并立即返回任务 ID/状态；大工作区推荐 async）。 取值：blocking, async |
workspace_path |
string | — | null |
工作区根目录。省略时使用当前会话工作区（推荐）；显式路径必须位于绑定工作区内。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
error |
string | 操作失败时的错误信息 |
index_missing |
boolean | 索引是否缺失（尚无任何已索引文件） |
indexed_files |
integer | 已索引的文件数量 |
job_id |
string | 后台索引任务 ID（异步重索引或存在活跃任务时） |
job_state |
string | 后台索引任务状态：queued / running / completed / failed / cancelled |
lifecycle |
string | 索引生命周期状态：missing / queued / running / ready / stale / failed |
parser_version |
string | 已索引内容使用的解析器版本 |
reindexed |
boolean | 本次调用是否执行了（重新）索引（阻塞完成 / 异步已入队） |
report |
object | 本次索引运行的汇总（仅阻塞式重索引） |
stale |
boolean | 索引是否被标记为过期（如 grammar 版本变更/文件修改失效） |
total_references |
integer | 索引中的引用总数 |
total_symbols |
integer | 索引中的符号总数 |
workspace_id |
string | 工作区标识（server_local 为规范根路径；client_local 为客户端工作区标签） |
跳转定义 — tools/goto_definition
按符号名精确匹配查找工作区索引中的定义位置。返回名称标识符区间（精确跳转点）与定义整体区间。只读。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
symbol |
string | ✅ | — | 精确符号名（不含路径限定，如 ‘compute_total’ 而非 ‘util::compute_total’） |
workspace_path |
string | — | null |
工作区根目录。省略时使用当前会话工作区（推荐）；显式路径必须位于绑定工作区内。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
auto_reindex_triggered |
boolean | 是否因本次查询发现索引缺失而已安排异步重建 |
definitions |
array<object> | 定义位置列表（多义符号可能有多处定义） |
error |
string | 操作失败时的错误信息 |
found |
boolean | 是否找到至少一处定义 |
index_missing |
boolean | 索引是否缺失（需要先 code_index_status reindex=true） |
job_id |
string | 自动重建任务 ID |
job_state |
string | 自动重建任务状态（queued / running） |
stale |
boolean | 索引是否过期 |
查找引用 — tools/find_references
按符号名精确匹配查找工作区索引中的引用点（调用/类型引用/宏调用/import/标识符）。只读。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
kind |
string | — | — | 可选的引用种类过滤：call、type、macro、identifier、import |
limit |
integer | — | — | 最大返回引用数，默认 200，硬上限 2000 |
symbol |
string | ✅ | — | 要查找引用的精确符号名 |
workspace_path |
string | — | null |
工作区根目录。省略时使用当前会话工作区（推荐）；显式路径必须位于绑定工作区内。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
auto_reindex_triggered |
boolean | 是否因本次查询发现索引缺失而已安排异步重建 |
error |
string | 操作失败时的错误信息 |
index_missing |
boolean | 索引是否缺失（需要先 code_index_status reindex=true） |
job_id |
string | 自动重建任务 ID |
job_state |
string | 自动重建任务状态（queued / running） |
references |
array<object> | 引用位置列表 |
stale |
boolean | 索引是否过期 |
total |
integer | 返回的引用数量 |
truncated |
boolean | 结果是否被数量上限截断 |
工作区符号搜索 — tools/workspace_symbols
按子串（大小写不敏感）搜索工作区已索引的符号定义。索引缺失时异步预热并标注，不阻塞本次查询。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
limit |
integer | — | — | 最大返回符号数，默认 50，硬上限 500 |
query |
string | ✅ | — | 符号名查询（子串，大小写不敏感） |
workspace_path |
string | — | null |
工作区根目录。省略时使用当前会话工作区（推荐）；显式路径必须位于绑定工作区内。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
auto_reindex_triggered |
boolean | 是否因本次查询发现索引缺失而已安排异步重建 |
error |
string | 操作失败时的错误信息 |
index_missing |
boolean | 索引是否缺失（本次查询已请求异步预热） |
job_id |
string | 自动重建任务 ID（本地执行器没有持久任务 ID 时为 null） |
job_state |
string | 自动重建任务状态（queued / running） |
stale |
boolean | 索引是否过期（结果可能不完整/漂移） |
symbols |
array<object> | 命中的符号列表 |
total |
integer | 返回的符号数量 |
truncated |
boolean | 结果是否被数量上限截断 |
下一步
© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
暂无评论内容