coderlm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CodeRLM — Structural Codebase Exploration

CodeRLM — 结构化代码库探索

You have access to a tree-sitter-backed index server that knows the structure of this codebase: every function, every caller, every symbol, every test reference. Use it instead of guessing with grep.

The tree-sitter is monitoring the directory and will stay up-to-date as you make changes in the codebase.

你可以访问基于tree-sitter的索引服务，它了解此代码库的结构：每个函数、每个调用方、每个符号、每个测试引用。请使用它，而非通过grep猜测。

该tree-sitter服务会监控目录，当你在代码库中进行修改时，它会保持更新。

How to Explore

探索方法

Do not scan files looking for relevant code. Work the way an engineer traces through a codebase:

Start from an entrypoint. Every exploration begins somewhere concrete — an error message, a function name, an API endpoint, a log line. Use

search

grep

to locate that entrypoint in the index.

Trace the path. Once you've found an entrypoint, use

callers

to understand what invokes it and

impl

to read what it does. Follow the chain: what calls this? What does that caller do? What state does it pass in? Build a model of the execution path, not a list of files.

Understand the sequence of events. The goal is to reconstruct the causal chain — what had to happen to produce the state you're looking at. Trace upstream (what called this, with what arguments?) and sometimes downstream (what happens after, does it matter?).

Stop when you have the narrative. You're done exploring when you can explain the path from trigger to outcome — not when you've read every related file.

不要扫描文件来寻找相关代码。请按照工程师追踪代码库的方式操作：

从入口点开始。所有探索都始于具体的某个点——错误信息、函数名称、API端点、日志行。使用

search

或

grep

在索引中定位该入口点。

追踪路径。找到入口点后，使用

callers

了解哪些代码调用了它，使用

impl

查看它的具体实现。沿着链条追踪：谁调用了这个函数？调用方的功能是什么？它传入了什么状态？构建执行路径模型，而非文件列表。

理解事件序列。目标是重建因果链——要产生你所关注的状态，必须发生哪些步骤。向上游追踪（谁调用了这个函数，传入了什么参数？），有时也需要向下游追踪（之后会发生什么，是否重要？）。

形成完整逻辑后停止。当你能够解释从触发到结果的完整路径时，探索即可结束——而非读完所有相关文件。

What This Replaces

替代的传统方式

Without the index, you explore by globbing for filenames, grepping for strings, and reading entire files hoping to find relevant sections. That works, but it's wasteful and produces false confidence — you see code near your search term but miss the actual execution path.

With the index:

Symbol search instead of string matching — find the function, not every comment mentioning it
Caller chains instead of grep-and-hope — know exactly what invokes a function
Exact implementations instead of full-file reads — get the 20-line function body, not the 500-line file
Test discovery by symbol reference — find what tests cover a function, not by guessing test filenames

没有索引时，你需要通过通配符查找文件名、字符串grep、阅读整个文件来寻找相关部分。这种方法可行，但效率低下且容易产生错误的信心——你只能看到搜索词附近的代码，却遗漏了实际的执行路径。

使用索引后：

符号搜索替代字符串匹配——找到函数本身，而非所有提及它的注释
调用链替代盲目grep——准确了解哪些代码调用了函数
精确实现替代全文件阅读——获取20行的函数体，而非500行的文件
基于符号引用的测试发现——找到覆盖该函数的测试用例，而非猜测测试文件名

Prerequisites

前置条件

The

coderlm-server

must be running. Start it separately:

bash

coderlm-server serve                     # indexes projects on-demand
coderlm-server serve /path/to/project    # pre-index a specific project

If the server is not running, all CLI commands will fail with a connection error.

coderlm-server

必须处于运行状态。请单独启动它：

bash

coderlm-server serve                     # 按需索引项目
coderlm-server serve /path/to/project    # 预索引指定项目

如果服务未运行，所有CLI命令都会因连接错误而失败。

CLI Reference

CLI参考

All commands go through the wrapper script:

bash

python3 skills/coderlm/scripts/coderlm_cli.py <command> [args]

所有命令都通过包装脚本执行：

bash

python3 skills/coderlm/scripts/coderlm_cli.py <command> [args]

Setup

初始化

bash

cli init                                  # Create session, index the project
cli structure --depth 2                   # File tree with language breakdown

bash

cli init                                  # 创建会话，索引项目
cli structure --depth 2                   # 带语言分类的文件树

Finding Code

查找代码

bash

cli search "symbol_name" --limit 20       # Find symbols by name (index lookup)
cli symbols --kind function --file path   # List all functions in a file
cli grep "pattern" --max-matches 20       # Scope-aware pattern search

bash

cli search "symbol_name" --limit 20       # 按名称查找符号（索引查找）
cli symbols --kind function --file path   # 列出文件中的所有函数
cli grep "pattern" --max-matches 20       # 作用域感知的模式搜索

Retrieving Exact Code

获取精确代码

bash

cli impl function_name --file path        # Full function body (tree-sitter extracted)
cli peek path --start N --end M           # Exact line range
cli variables function_name --file path   # Local variables inside a function

Prefer
impl
and
peek
over the Read tool. They return exactly the code you need — a single function from a 1000-line file, a specific line range — without loading irrelevant code into context. Fall back to Read only when you need an entire small file.

bash

cli impl function_name --file path        # 完整函数体（tree-sitter提取）
cli peek path --start N --end M           # 精确行范围
cli variables function_name --file path   # 函数内的局部变量

优先使用
impl
和
peek
而非Read工具。它们会返回你需要的精确代码——比如从1000行文件中提取单个函数，或特定行范围——无需将无关代码加载到上下文。仅当需要完整的小文件时，才回退使用Read工具。

Tracing Connections

追踪关联

bash

cli callers function_name --file path     # Every call site: file, line, calling code
cli tests function_name --file path       # Tests referencing this symbol

These search the entire indexed codebase, not just files you've already seen.

bash

cli callers function_name --file path     # 所有调用位置：文件、行号、调用代码
cli tests function_name --file path       # 引用该符号的测试用例

这些命令会搜索整个已索引的代码库，而非仅你已查看过的文件。

Annotating

注释

bash

cli define-file src/server/mod.rs "HTTP routing and handler dispatch"
cli define-symbol handle_request --file src/server/mod.rs "Routes requests by method+path"
cli mark tests/integration.rs test

Annotations persist across queries within a session — build shared understanding as you go.

bash

cli define-file src/server/mod.rs "HTTP路由与处理器分发"
cli define-symbol handle_request --file src/server/mod.rs "按方法+路径路由请求"
cli mark tests/integration.rs test

注释会在会话的多次查询中保留——随着探索深入，逐步构建共享的理解。

Cleanup

清理

bash

cli cleanup                               # End session

bash

cli cleanup                               # 结束会话

Inputs

输入参数

This skill reads

$ARGUMENTS

. Accepted patterns:

```
query=<question>
```
(required): what to find or understand
```
cwd=<path>
```
(optional): project directory, defaults to cwd
```
port=<N>
```
(optional): server port, defaults to 3000

If no query is provided, ask what the user wants to find or understand about the codebase.

该工具会读取

$ARGUMENTS

。支持的模式：

```
query=<question>
```
（必填）：需要查找或理解的内容
```
cwd=<path>
```
（可选）：项目目录，默认为当前工作目录
```
port=<N>
```
（可选）：服务端口，默认为3000

如果未提供query，请询问用户需要查找或理解代码库的哪些内容。

Workflow

工作流程

Init —
```
cli init
```
to create a session and index the project.
Orient —
```
cli structure
```
to see the project layout. Identify likely starting points.
Find the entrypoint —
```
cli search
```
or
```
cli grep
```
to locate the starting symbol or pattern.
Retrieve —
```
cli impl
```
to read the exact implementation. Not the file. The function.
Trace —
```
cli callers
```
to see what calls it.
```
cli impl
```
on those callers. Follow the chain.
Widen —
```
cli tests
```
to find test coverage.
```
cli grep
```
for related patterns discovered during tracing.
Annotate —
```
cli define-symbol
```
and
```
cli define-file
```
as understanding solidifies.
Synthesize — Compile findings into a coherent answer with specific file:line references.

Steps 3–7 repeat. A typical exploration is: find a symbol → read its implementation → trace its callers → read those implementations → discover related symbols → repeat until the causal chain is clear.

初始化 — 执行
```
cli init
```
创建会话并索引项目。
定位 — 执行
```
cli structure
```
查看项目布局，确定可能的起始点。
找到入口点 — 使用
```
cli search
```
或
```
cli grep
```
定位起始符号或模式。
获取实现 — 执行
```
cli impl
```
读取精确的实现代码。不是整个文件，是函数本身。
追踪调用 — 执行
```
cli callers
```
查看哪些代码调用了它。对这些调用方执行
```
cli impl
```
，沿着链条追踪。
扩展范围 — 执行
```
cli tests
```
查找测试覆盖范围。使用
```
cli grep
```
搜索追踪过程中发现的相关模式。
添加注释 — 当理解逐步清晰时，执行
```
cli define-symbol
```
和
```
cli define-file
```
。
整合结果 — 将发现整理为包含具体文件:行号引用的连贯答案。

步骤3–7会重复进行。典型的探索流程是：找到符号 → 读取其实现 → 追踪调用方 → 读取调用方的实现 → 发现相关符号 → 重复直到因果链清晰。

When to Use the Server vs Native Tools

何时使用服务端 vs 原生工具

Task	Use server	Why
Find a function by name	`search`	Index lookup, not file globbing
Find code when name is unknown	`grep` + `symbols`	Searches all indexed files at once
Get a function's source	`impl`	Returns just that function, even from large files
Read specific lines	`peek`	Surgical extraction, not the whole file
Find what calls a function	`callers`	Cross-project search with exact call sites
Find tests for a function	`tests`	By symbol reference, not filename guessing
Get project overview	`structure`	Tree with file counts and language breakdown
Read an entire small file	Read tool	When you genuinely need the whole file

Default to the server. Use Read only when you need an entire file or the server is unavailable.

任务	使用服务端	原因
按名称查找函数	`search`	索引查找，而非文件通配
名称未知时查找代码	`grep` + `symbols`	一次性搜索所有已索引文件
获取函数源码	`impl`	仅返回该函数，即使来自大文件
阅读特定行	`peek`	精准提取，而非整个文件
查找调用函数的代码	`callers`	跨项目搜索，返回精确调用位置
查找函数的测试用例	`tests`	基于符号引用，而非猜测文件名
获取项目概览	`structure`	带文件数量和语言分类的树状结构
阅读整个小文件	Read工具	当确实需要完整文件时

默认使用服务端。仅当需要完整文件或服务端不可用时，才使用Read工具。

Troubleshooting

故障排除

"Cannot connect to coderlm-server" — Server not running. Start with
```
coderlm-server serve
```
.
"No active session" — Run
```
cli init
```
first.
"Project was evicted" — Server hit capacity (default 5 projects). Re-run
```
cli init
```
.
Search returns nothing relevant — Try broader grep patterns or list all symbols:
```
cli symbols --limit 200
```
.

For the full API endpoint reference, see references/api-reference.md.

"Cannot connect to coderlm-server" — 服务未运行。使用
```
coderlm-server serve
```
启动。
"No active session" — 先执行
```
cli init
```
。
"Project was evicted" — 服务达到容量上限（默认5个项目）。重新执行
```
cli init
```
。
搜索返回无相关结果 — 尝试更宽泛的grep模式，或列出所有符号：
```
cli symbols --limit 200
```
。

完整的API端点参考，请查看references/api-reference.md