read_code_context 用于需要理解具体行为的任务:先读取完整函数实现,遇到缺失的函数、常量或文件再补读。它按调用者给出的路径和符号工作,不解释自然语言任务,也不自动证明材料足以回答问题。
v0.5.0 起提供 SDK 与 MCP,v0.6.0 接入浏览器工作台。v0.7.0 增加 CLI 单次和 JSONL 会话;各入口可复用同一份版本化请求。
每个请求包含 1 至 32 个不同文件。每个文件在以下方式中选择一种:
{
"maxTokens": 4000,
"requests": [
{"path": "lib/response.js", "symbols": ["res.render"]},
{"path": "lib/application.js", "outline": true}
]
}| 字段 | 行为 |
|---|---|
symbols |
1 至 16 个不同名称,读取完整定义所在行。优先匹配限定名,例如 res.render、Session.prepare_request;简单名称必须唯一 |
ranges |
1 至 16 个 {startLine,endLine},从 1 开始、两端包含。合并重叠及相邻范围,保留原始 Unicode、CRLF 与行尾;越界失败 |
full: true |
读取完整文件,可用于不支持的语言或无法解析的源文件 |
outline: true |
只返回名称、限定名与行范围,用于定位,不返回实现 |
includeDependencies: true |
仅用于符号读取,递归添加同文件中唯一匹配的词法引用定义及常量,最多 64 个定义;默认关闭 |
当前源码的符号和 outline 支持 JavaScript(含 JSX)、TypeScript、TSX、Python、MoonBit(.mbt、.mbti)。MoonBit 限定名保留原上下文:例如 Point::render、Render::render、Render for Point::render,接口实现声明使用 impl Read for Point。先请求 outline 可获得实际名称;裸名称有多个候选时返回歧义,不猜接收者或 trait 映射。索引单文件上限为 8 MiB,解析超时为 200 ms,最多 4,096 个定义、每个定义 256 个词法引用;遍历另有节点、深度和总引用配额。超过索引限额返回 resource-limit,不会返回部分目录。完整限额及原生内存边界见 索引说明。名称重复时返回 ambiguous-symbol 和最多八个候选,不擅自选第一个。找不到名称返回 symbol-not-found。解析、资源或语言限制会明确报出;需要时调用者可另行选择 ranges 或 full。
词法依赖不是语义调用图。动态调用、别名、跨文件导入和局部遮蔽都可能影响解析;自动展开可能多带代码,也可能缺少行为依据。审计会列出同文件有多个候选的依赖,最多 32 个名称,并标记提示是否截短;源代码本身不会因此被截断。需要进一步判断时,指定正确文件及限定名补读。
符号读取会比较当前文件的完整正文与范围对象的精确 token 成本;全文对象更小时直接返回全文。显式 ranges 不扩大读取结果。多文件最终预算始终以整份 JSON 再计数,不假定各片段成本可加,也不承诺求出全局最小上下文。
let spec = @repomix.CodeContextSpec::from_json({
"maxTokens": 4000,
"requests": [
{ "path": "src/session.py", "symbols": ["Session.prepare_request"] },
],
})
let plan = @repomix.read_code_context(options, runtime, spec)
match plan.text {
Some(text) => /* 把精确计数的 JSON 交给模型 */ ignore(text)
None => /* 查看不含源码正文的审计 */ ignore(plan.audit)
}以上代码在已导入根 SDK 为 @repomix、已有 options 和 runtime 的异步函数中运行。
CodeContextSpec::from_json 校验严格字段、路径、数量、类型和最多 64 KiB 的规范化请求 JSON。非法描述抛出 InvalidCodeSpec,不读文件。路径必须是规范根相对字面路径,最多 4,096 UTF-8 bytes;符号最多 256 UTF-8 bytes。禁止绝对路径、空段、.、..、反斜杠、冒号和 NUL。
CodeContextPlan 返回:
status:complete、unavailable或over_budget。text:成功时为完整 JSON;任一要求不可提供或整份超预算时为None,不交付部分源码。tokens、bytes:实际交付 JSON 的精确计量;失败为 0。required_tokens:仅超预算时提供所需 token 数。audit:请求结果、读入字节、尝试次数、安全状态、匹配定义及依赖歧义。成功时同一审计已嵌入text,不需要再送一份给模型。security:沿用完整文件扫描的Passed/Excluded/Disabled。
JSON 使用固定 schemaVersion: 1,包含 files、audit、模板及不可信数据标识。maxTokens 限制完整 JSON,包括定位元数据和审计;不包括调用参数、协议包装、失败诊断或模型已有消息。SDK 的每次调用独立计量,累计额度由 SDK 调用方管理。
maxReadBytes 默认且最高 16 MiB,与主机实际源码读取限额取较小值;EOF/超额探测最多额外读一个字节。读取按请求顺序进行,已知有被排除的路径时不打开任何源码;执行中一项失败后不再读取后续文件。
启动已有只读服务,例如:
moon-repomix /path/to/repository --mcp --mcp-max-tokens 8000调用工具 read_code_context,首次参数:
{
"maxTokens": 6000,
"requests": [{"path": "lib/response.js", "symbols": ["res.render"]}]
}成功摘要返回 runId、本次 tokens、sessionTokens、remainingTokens、轮次和一个 code.json 资源 URI。先用 resources/read 读取实际 URI。若发现 app.render 的实现缺失,再调用同一个工具:
{
"continueFrom": "上次成功返回的 runId",
"requests": [
{"path": "lib/application.js", "symbols": ["app.render"], "includeDependencies": true}
]
}- 新会话的
maxTokens默认使用主机 cap,只能降低。续读必须省略maxTokens,沿用剩余额度。 - 一次会话最多三次成功读取,即首次读取加两次补读;每轮按完整 JSON 精确计费,重复返回的正文也再次计费。
- 成功生成一个资源,原子替换旧资源并更新累计用量。旧 URI 失效,客户端需要在补读前取得上一轮材料。
- 失败、超预算或提交前取消不替换资源、不消耗成功轮次及会话额度。失败诊断不在累计正文 cap 内,客户端需为它和协议消息另留额度。
- 用旧
runId、已释放资源,或已被其他成功任务/打包替换的会话续读,返回StaleCodeSession。额度用尽返回CodeBudgetExhausted;三轮后返回CodeRoundLimit。 - 请求更大的新会话是显式重新开始,不会让旧会话自动扩容。此限制约束一次读取会话,不是进程终身 token 配额。
- 资源最多 4 MiB,并受主机
--mcp-max-output-bytes限制。忙时返回Busy。
选择、include/ignore、白名单、符号链接与安全扫描沿用主机授权。文件必须先通过完整正文扫描,才生成片段或符号目录;不能用“只读安全函数”绕过文件别处的敏感内容。请求中的路径和名称、主机模板也经过扫描。
该入口固定返回 JSON,由请求选择内容,与 pack 的 style、压缩、全文例外和行号展示设置独立;header 和 instruction 文本仍按主机配置处理。远程源、Git diff/log、分卷配置、单份 token 预算、关闭文件正文输出和非 o200k_base 编码与此入口冲突,返回配置错误。
文件仍可能在不同读取轮次间改变;每轮重新检查和读取,不是仓库事务快照。客户端应结合返回的实现与行范围判断是否需要重新获取相关内容。
已有 plan_task_context 适合调用者已知必选文件和候选优先级的共享文件预算;本工具适合具体实现与依赖补读。两者都不以“预算内交付”承诺语义充分性。