CODRAX 使用与技术说明
推理确定，解释锚定。每条结论落到代码，每段推理可以复核。
确定性诚实，不是态度，是契约。
这份文档以怎么用为主：四条上手路径、八个典型使用场景（每个都带可照抄的问法和怎么读答案）、提问技巧；
末尾用一小节速览它内部怎么工作。想看完整机制设计的工程读者，请直接读仓库里的 docs/architecture.md。
一句话看懂 CODRAX
CODRAX 是一个代码分析 + Log/Trace 分析 + 变更提议工具。默认运行在读模式，
围绕可复核证据回答代码行为、崩溃根因、性能卡顿、默认配置、模块职责等问题，全程不碰源文件；
开启写模式后，由 Auto Pilot 在沙箱工作区（隔离出来的临时改动区，不直接动主仓）里
自动探索、应用、验证；计划 → 改动 → 验证 是它内部的三段。
可以把它当成什么
- 一个会读仓库、会追证据、会给引用的高级分析助手。
- 一个适合新人熟悉系统、线上排障、架构讲解的工程工作台。
不该把它当成什么
- 不是“模型直连仓库”的聊天壳。
- 不是靠文风自信来制造正确感的问答器。
一个正确预期
- 它承诺的不是“永远秒答”，而是“能证实的尽量证实，证不实的明确标边界”。
- 价值在于更稳地把复杂问题拆清楚。
四种使用形态
| 形态 | 适合什么 |
|---|---|
| 边问边查 | 交互控制台，适合摸清陌生系统、连续追问。 |
| 一次分析 | 单次请求 -r "…"，适合脚本和持续集成。 |
| 现场输入 | 挂日志或性能文件，先分诊再追代码。 |
| 安全改动 | 写模式先在沙箱验证，不直接改主仓。 |
安装与开始之前
真正开始提问之前，有三件事要先准备好：装好 codrax、配好大模型凭证， 然后进到你要分析的代码仓库里启动它。三步走完，就能问出第一个问题。
第一步 · 装好 codrax
从源码构建。需要 CGO 工具链（tree-sitter 语法解析）：macOS 先 xcode-select --install，Debian / Ubuntu 装 gcc musl-tools。
git clone https://github.com/hanchaoqun/codrax.git
cd codrax && make # 输出 ./codrax建议把 codrax 所在目录加进 PATH，这样在任何地方都能直接敲 codrax 启动：
echo 'export PATH="/path/to/codrax:$PATH"' >> ~/.bashrc # bash
echo 'export PATH="/path/to/codrax:$PATH"' >> ~/.zshrc # zsh
exec "$SHELL" -l第二步 · 配置 providers.yaml（连接大模型）
codrax 自己不含大模型，要连一个 OpenAI 兼容的 LLM 服务 —— OpenAI、DeepSeek、Qwen、本地 vLLM / Ollama 都可以。
把配置样例复制成 providers.yaml，放在和 codrax 可执行文件同一个目录下：
cp providers.yaml.example providers.yaml最小配置只需要填 4 个字段：
llm:
default:
provider: openai # 协议名；兼容服务都填 openai
api_key: "sk-xxx" # 你的 API key
model: "your-model-id" # 例如 gpt-4o-mini / deepseek-chat
base_url: "https://api.openai.com/v1"缺字段会怎样：这 4 个字段缺任何一个，codrax 启动时会直接报错并告诉你缺的是哪个 —— 它不会偷偷连任何公网地址。需要按 agent 分别换模型时，再加 agents: 段即可。
第三步 · 进入你的代码仓库再启动
⚠ 这一点最容易被忽略，但最关键
codrax 把「你启动它时所在的目录」当作要分析的代码仓库。它不会弹窗问你「要分析哪个项目」—— 默认分析的就是当前工作目录（等价 --repo .）。
所以正确用法是：先 cd 进你想分析的项目根目录，再运行 codrax。如果在别的目录启动，它就会去分析那个目录。
cd /path/to/your/project # ① 先进入你要分析的代码仓库
codrax # ② 再启动，它会索引「当前目录」这个仓库
启动后 codrax 会在当前目录建一个 .codrax/ 子目录，存放日志、对话记忆和缓存等运行产物。
读模式下它只读你的源码、从不修改；所有运行产物都集中在这一个隐藏目录里，一条 .gitignore 就能排除。
随后你就进入了交互控制台（REPL）：看到提示符 ❯❯ 之后，直接打字提问、回车即可。
/help 列出全部命令，/exit 退出。下一节会展开讲不同的使用路径。
快速上手：4 条路径
不用一次学全。先挑一条最贴近你当前需求的路径开始，其它三条用到再看。
路径一 · 交互控制台
直接对话式提问，适合陌生仓库摸底、连续追问、边看边缩小范围。控制台会自动保留上下文记忆。
codrax
# 然后直接提问：
订单状态为什么没有更新？
如果继续追查，下一步应该先看哪一层？路径二 · 单次请求
一条命令、一个答案，适合脚本、持续集成（CI）、批量分析，或只要一个明确结论就结束的场景。
codrax -r "退款单为什么会被重复创建？
如果证据不足请明确说明。"路径三 · 日志 / 性能现场分诊
把崩溃日志或性能 trace 作为附件喂进来。日志会先走日志分诊，性能现场会先走性能分诊—— 这里的“分诊”就是先把现场信息分类整理，再决定从哪里查起。
codrax --log crash.log -r "解释最可能根因"
codrax --htrace perf.trace -r "为什么这个页面会掉帧？"路径四 · 写模式 Auto Pilot
明确要改什么时用。描述目标即可，Auto Pilot 自动探索、拆批、应用、验证；低 / 中风险不打断，高风险才暂停审批，合回主仓仍需显式动作。所有写入只发生在沙箱工作区。
codrax --mode=write -r "修复回调幂等问题并补测试"
# 只想先看计划、不落地：显式用 plan 阶段
codrax --mode=write --write-phase=plan -r "修复回调幂等问题并补测试" --plan-out plan.json建议：把交互控制台当成探索工作台，把单次请求 -r 当成稳定分析入口。
多仓父目录下可用 --multi-repo=true 自动发现子仓，再用 --focus 固定本轮目标仓。
典型使用场景
下面八个场景覆盖了绝大多数日常用法，也是这份文档的主体。每个场景都给出三样东西： 你会怎么问（可以原样照抄的问法）、屏幕上会发生什么、怎么读答案。 例子里的文件名、函数名、仓库名都是占位符，换成你项目里的实际名字即可。
场景①接手陌生仓库，快速建立架构认知
你会怎么问
cd /path/to/repo && codrax
# 然后直接提问：
这个项目分几层？各模块的职责是什么？
要理解订单创建流程，先看哪几个文件？屏幕上会发生什么
首次启动会先索引仓库；提问后能看到任务列表和「正在…」过程行——它在读哪些文件、搜什么关键词都是透明的；最后是分层解释加一串 file:line 引用。
怎么读答案：先看它引用了哪些文件——那就是这个仓库的骨架清单。追问时直接指着答案里的名字继续问（「A 和 B 之间怎么交互？」），交互控制台会带着上下文记忆走，越问越窄。
场景②线上 panic / 异常日志定位
你会怎么问
codrax --log /tmp/panic.txt -r "这个 panic 哪来的？"
# 容器日志直接从管道喂进来：
kubectl logs pod/foo | codrax --log - -r "排查这个 crash"
# REPL 里附加后连续追问：
/log /tmp/panic.txt
这个 panic 哪来的？屏幕上会发生什么
附加成功后提示符带 [log] 粘性标签。日志先被解析成结构化栈帧和故障信号（panic / 异常 / traceback / sanitizer 报告等），再据此去仓里读真正相关的文件——不是把日志当一段普通文本。
怎么读答案：答案按「候选根因 / 已排除 / 仍缺证据」组织，栈帧对齐到当前代码行。两份日志对比用 --log a.log --log b.log；CI 构建路径和本地仓对不上时，用 --log-source-prefix /build/src/ 剥掉前缀再匹配。
场景③性能卡顿 trace 分析
你会怎么问
# 抓一段 trace（HarmonyOS 示例；Android 用 atrace）
hdc shell hitrace -t 5 graphic > /tmp/htrace.txt
# 提问尽量给足三要素：进程/线程名（或 pid/tid）+ 时间窗 + 想要的结论形态
codrax --htrace /tmp/htrace.txt -r "com.example.app 12345 主线程在 \
34579.472s 到 34579.476s 的短窗卡顿：主要等待来自哪条依赖/唤醒 \
关系？链上线程状态和调度资源背景是什么？只分析这份 trace，不读代码"
# REPL 里则先 /htrace 附加，再按同样方式追问：
/htrace /tmp/htrace.txt
RenderThread 在 34579.47s 到 34579.59s 内为什么掉帧？在等谁唤醒？屏幕上会发生什么
提示符带 [trace] 标签；性能现场先被分诊，自动抽出掉帧、阻塞、启动等关键信号。支持 HiTrace / atrace / systrace / perfetto 文本格式；二进制 HiTrace 先用 /htrace convert 转成文本。
怎么读答案：提问给足三要素——进程/线程名（或 pid/tid）、时间窗、想要的结论形态（在等谁 / 唤醒链 / 占比排名）——答案会明显更准；只说"为什么慢"也能跑，但系统要花更多轮先替你圈范围。答案会结合 runnable、D-state / IO、binder、频点和 perf 调用栈拆等待与唤醒链，指出卡顿最可能出在哪个阶段、还缺什么证据。前后两份 trace 对比也可以：在问题里分别点名两个文件即可。
场景④跨仓 workspace：找调用链与接口消费方
你会怎么问
cd ~/workspace && codrax # 父目录下多个独立 git 仓
/repos # 看发现了哪些子仓
/repos focus api-go-aabbccdd
/repos focus web-frontend-eeff0011
api-go 暴露的 /v1/user 接口在
web-frontend 哪些组件被消费？屏幕上会发生什么
启动 banner 会显示发现了几个子仓；/repos 列出各仓的语言和状态，focus 后提示符带 [focus:…] 标签。跨仓的接口消费方、调用链查询在被 focus 的子仓之间直接命中。
怎么读答案：只问单个子仓时不需要任何额外操作——问题里提到子仓名就会自动路由；跨子仓问题先把相关子仓都 focus 进来。注意：写模式必须 cd 进具体子仓运行，一次只改一个仓。
场景⑤配置 / 行为溯源
你会怎么问
codrax -r "config.yaml 里 timeout 字段的默认值是多少？"
# 或在控制台里连续追问：
这个值在哪里被读进来？
命令行参数能覆盖它吗？优先级是怎样的？屏幕上会发生什么
这类「精确值」问题走的是最严的路：必须找到唯一的定义与解析链才会给出具体数值，答案附定义处和覆盖点的引用。
怎么读答案：留意答案里「显式定义 / 推断 / 证据不足」的区分——提问时也可以直接要求它这样区分。查不到唯一定义时它会明确说，而不是报一个像样的数。
场景⑥数据文件盘点与核对
你会怎么问
codrax --mode=data -r "汇总当前目录 CSV 的
数值字段总和，只输出数字"
# 或描述规则让它去关联核对：
把 records.tsv 和 reference.jsonl 按共同键关联，
列出字段不一致的前 20 条，输出 Markdown 表格。屏幕上会发生什么
数据任务是独立的一条只读路径：系统先列出材料目录（路径、表头、行数、样例），再由受限的确定性执行器读文件算结果——清洗、过滤、去重、关联、汇总都可以，输出严格按你要求的格式。
怎么读答案：想核对就看随附的材料消费记录和对账摘要——哪些文件被读了、每条结果怎么来的都有账；完整审计产物落在 .codrax/data-audit/ 目录。
场景⑦写模式小修小补
你会怎么问
codrax --mode=write -r "修复回调幂等问题并补测试"
# REPL 里：单次写用 /write，持续写模式用 /mode write
/write 给 parseConfig 补上空值检查和对应测试屏幕上会发生什么
Auto Pilot 自动探索、拆小批次、应用、跑验证；低 / 中风险不打断，高风险暂停并显示计划、风险和差异，等你 /approve 或 /reject；验证失败会小批量自动重规划。全程只写隔离的沙箱工作区。
怎么读答案：整个过程主仓一直不动。确认没问题后 /merge 把改动收回主仓（需要 codrax.yaml 里 pipeline_keep_worktree_on_success: true 保留工作区）；只想先看计划不落地，用 --write-phase=plan。
场景⑧无头 / CI 单次提问
你会怎么问
codrax --request "main 函数定义在哪个文件？"
codrax -r "项目目录布局是怎样的？" > overview.md
# 结合管道做自动化排障：
kubectl logs pod/foo | codrax --log - -r "分析这次 crash"屏幕上会发生什么
一条命令、一个答案，跑完即退出，适合脚本和持续集成；输出重定向到文件即可归档。--repo / --branch 可以指定别处的仓库和分支。
怎么读答案：脚本化调用时，建议在请求里写明「如果证据不足请明确说明」——拿到的要么是带引用的结论，要么是一句诚实的边界说明，两者都可以直接进流程。
怎么提问效果最好
同样一个工具，问法不同，效果差别很大。这一节是“使用效果的分水岭”。
更推荐这样提问
- 是什么 + 由什么决定 + 失败边界在哪
- 请区分显式定义、推断补全和证据不足
默认超时时间到底是多少？
如果找不到，请明确说明是推断，
还是当前证据不足。更推荐这样阅读答案
- 先看它引用了什么文件，再看它怎么总结。
- 分清哪些是已证实的，哪些只是尽力推断的。
启动提示 → 任务列表 / 处理中
→ 系统决策推演 → 最终答案 + 引用不要只问“这是什么”，尽量问“它怎么工作、由什么决定、哪些情况会让它失效”。
如果是在多仓父目录提问，顺手说明目标仓，或先用 /repos 看清子仓列表。
机制速览：为什么答案可信
CODRAX 不是把问题直接丢给大模型。一句话的问题会先被编成结构化的「调查任务单」， 之后的调查顺序、停止条件、引用合法性和答案放行全部由确定性代码接管——模型交原料，系统定放行。 这一节只讲结论，够建立正确预期即可。
问题先被编成任务单
查什么、按什么顺序查、查到什么程度算够、答案必须长什么样，动手前先定下来；几条候选假设并列排查，各自带成立条件和打掉条件，谁先查不靠感觉。
只引用真正读过的内容
「搜到」不等于「读到」。允许引用的清单只来自真正打开过的文件，每条引用还要回到源码逐条核对落点——编造或对不上的引用进不了正文。
证据不足就停下
连续几轮没有新证据会强制扩大搜索，再不行就降级收尾：讲清「已证实 / 已排除 / 仍缺证据」，绝不把不确定包装成确定。「会停下」本身就是能力。
写模式受同一套边界
计划、改动、验证彼此隔离，所有写入只发生在沙箱工作区；风险分级决定要不要打断你，合并回主仓永远是你的显式动作。
想深入内部机制？流水线各阶段、假设规划、引用校验和答案验收规则的完整设计，都在仓库的 docs/architecture.md——工程读者请直接读它，这里不再展开。
写模式 Auto Pilot：能改，但不莽撞
写模式不是“放开让模型改文件”。日常主路径是 Auto Pilot：你描述目标，系统自动探索、拆成小批次、生成有界计划、在沙箱里应用、跑验证，失败按 typed 证据小批量 replan。
计划 → 改动 → 验证 仍是它内部的三段，每段权限都不同；所有写入只发生在独立沙箱工作区——主仓旁边一块临时隔离施工区，怎么改都不碰主仓当前版本。
风险分级审批 · 不是每次都拦
- 低 / 中风险：Auto Pilot 自动应用 + 验证，不打断你。
- 高风险：暂停并显示计划 / 差异，等你
/approve或/reject。 - critical：直接拒绝；合回主仓也始终需要显式动作。
执行边界 · 只能按计划落地
- 改动范围保护：计划没写的模块，执行时不能突然去改。
- 改动顺序保护：有依赖关系的改动必须按顺序落地。
- 跨仓写入保护：一次写模式只能改一个子仓。
验证阶段像工程流水线，不是聊天补救：会跑静态检查、预编译检查和测试工具探测；
run_tests 自动探测 12 类常见测试工具。验证失败时，Auto Pilot 把失败摘要、测试结果和嫌疑文件作为 typed 证据，
交给 controller 小批量 replan，再 apply 再 verify。成功后还可以保留沙箱工作区继续复核；想只看计划不落地，用 --write-phase=plan。