第三章　工具目录

本章覆盖第 11–14 章：智能编程与安全分析工具的参数速查、外部工具服务接入字段与工具权限策略。

第十一节 智能编程工具

[!ref] 详解见用户手册「智能编程工具」节。

11.1 工具一览

11.2 通用返回字段

读取 / 搜索类工具的返回都包含：

结果瘦身（省 token / 额度）：工作区工具的返回路径一律相对工作区根（relPath），错误串出口剥除根路径前缀（不外泄绝对根），去除重复 line_hashes，分页记账（next_offset 等）仅在 truncated=true 时才输出。

11.3 read

编码识别：优先按 BOM 判定；无 BOM 时识别 GBK / GB18030 / UTF-16 等常见编码，解码为 UTF-8 后交付。grep 走同一套解码。确属二进制的文件默认拒读（用 as_text 覆盖）。

11.4 write

11.5 patch

11.6 list

11.7 glob

11.8 grep

11.9 fs.exec / fs.exec.start

支持的 shell 语法（非无限制模式同样可用）：

• samples/ 只拦执行，不拦读取与作为参数传入。
• test.run / lint.run / sast.run 给出的命令走同一套护栏与同一个分词器。
• 路径口径：工作区内的绝对路径与相对路径走同一套判定，不再一律拒绝绝对路径。
• 白名单已含 cc 家族编译器（cc / gcc / clang 等）：写出通道（-o / -MF 等）圈禁工作区内，危险旗标前缀拦截。
• 命令名归一化（Windows）：大小写与 .exe 后缀不影响白名单判定；被策略拒绝时错误信息带上命令与规则上下文。
• 输出编码：Windows 下 GBK / UTF-16 输出在汇聚点统一归一为 UTF-8（fs.exec 与 fs.exec.tail 均覆盖）。
• 回显：结果中的命令按原样保留引号，不做空格重拼。
• Windows 批处理（.bat / .cmd）参数带专门的注入护栏。
• 工作目录不被劫持：工作区下的同名文件不会被解析成待执行程序。

11.10 fs.exec.tail / fs.exec.kill / fs.exec.list

本地后台会话上限：最多 16 个并发；单会话磁盘日志 256 MiB（溢出丢尾）；进程退出后日志可继续拉取，1 小时后 GC 回收；会话随 Interpreter 生命周期结束。

SSH 远端后台会话不受上述限制：状态与日志落在远端 <root>/.avlcode/sessions/，日志为完整文件（无 256 MiB 环形丢尾），且跨断线重连与应用重启存活（见 §22.4）。

11.11 web.bing / web.fetch

11.12 code.* — 代码智能工具组（基于 LSP）

位置参数对外 1-based（对齐 fs.read 行模式 / cat -n）；进 LSP 前由 interpret 层转 0-based。

能力降级：可选能力（implementation / type_definition / document_highlight / completion / signature_help / formatting 等）并非每个语言服务器都实现。是否支持按真实响应判定而非按 server 声明预判（避免声明缺失导致的误拒）；判定为不支持后跨会话缓存，同一 server 不再重复试探。

11.12.1 内置语言（24 门，按 ID）

go · ts · py · c（cpp） · rust · java · deno · eslint（js 增强） · lua · bash · yaml · php · ruby · vue · zig · dart · kotlin · clojure · elixir · haskell · fsharp · csharp · gleam · astro

每门语言绑定一个 LSP 命令（gopls / typescript-language-server / pyright-langserver / clangd / rust-analyzer / jdtls / …）；缺哪个按需自动下载（go install / npm 等），并显示安装进度。

11.12.2 用户配置文件 lsp.yaml / lsp.json

工作区根目录 .avlcode/ 或 ~/.avlcode/，按 lsp.yaml > lsp.yml > lsp.json 顺序取第一个存在的：

lsp:
  rust:
    disabled: true              # 禁用
  go:
    cmd: gopls                  # 覆盖启动命令
    args: ["-rpc.trace"]
    root_markers: ["go.mod", "go.work"]
  custom_lang:                  # 增加自定义 server
    extensions: [".myx"]
    cmd: my-langserver
    install_via: npm
    install_pkgs: [my-langserver]

热重载：文件 mtime/size 变更自动重读，不必重启工作区。服务器进程崩了 / SSH 掉线自动重启。

11.12.3 全库 RAG 检索与问答（code.search / code.ask）

非向量（零 embedding）符号级全库检索：BM25 + 标识符切分（驼峰 / 下划线 / 连字符）+ 中日韩二元切分（中文注释 / 中文提问同样能命中），纯本地、可离线。索引落 <base>/.avlcode/rag/symbols.jsonl（远程工作区仅内存），首建后按文件 mtime 增量同步（改 / 增 / 删）。仅索引定义类符号（函数 / 方法 / 类型 / 接口 / 常量等）。

索引文件数上限 4000（不可配）。超限时如实回报而非静默截断：结果里带 index_covers_all_files=false、files_not_indexed（未纳入索引的文件数）与 truncated_hint 可读提示，便于判断"没搜到"是真不存在还是没覆盖到。

code.search 参数

返回 hits[]（file / start_line / end_line / name / kind / score / why[]（命中的关键词）/ 可选 container·signature）、count、indexed_symbols、indexed_files；空结果给 hint。

code.ask 参数

模型：按「模型路由策略」在已启用且有 API Key 的澜砥系列模型中选（默认效果优先）；无可用澜砥模型时用当前会话的 provider / model（隐式注入）；本地模式下只用会话模型；两者都拿不到时报错。超时与输出上限跟随所选模型配置。检索片段会发给所选模型。

返回 answer + citations[]（file / start_line / end_line / name）+ hit_count + model + provider + routed（是否为路由选中的澜砥模型）；检索不到会直说、不编造。默认对扩展检索结果做结构感知智能重排（无需显式 expand）。

上限：索引文件数 ≤ 4000、全量构建超时 120s、每文件 ≤ 400 符号 / ≤ 4 MiB；结构重排取头部 8 条。增量刷新的作用域已修正（文件变更后不多刷、不漏刷）。

11.13 test.run — 测试运行 + 失败回灌

返回：failures[]（最多 50 条 {test, file, line, message}） + 一小段原始 tail；未知框架退回到退出码 + tail 兜底。plan（筹划）与 assess（评估）模式均禁用（执行测试会产生写副作用）。

11.13.1 自检门禁（opt-in，泛化的多检查器）

testgate.yaml 结构：

enabled: true
checks:                              # 检查器列表（可单选 / 组合）
  - name: test                       # test | diagnostics | lint | sast
    mode: block                      # block | report
    submode: changed                 # test: changed | full
    scope: changed                   # changed | workspace
  - name: lint
    mode: block
    submode: strict                  # lint: strict | lenient
    linters: [errcheck, govet]       # 子集（可选）
  - name: sast
    mode: report
    submode: quick                   # sast: quick | deep
    config: .semgrep.yml             # 离线规则（可选）
modes:                               # 按工作模式分别覆盖
  plan:    { enabled: false }
  prepare: { enabled: false }

11.13.2 CheckSpec 字段

11.13.2a testgen — 改动缺测试自动补（opt-in）

• 不在默认集：要显式把 testgen 加进 checks 才生效。
• 覆盖语言：Go / Python / JavaScript / TypeScript；其它扩展名（.c / .java 等）不判定。
• 测试文件本身与生成物跳过：避免「给测试写测试」「给 .pb.go 写测试」。
• 存在性查询：经 zMCP 网关 fs.glob 查测试文件存在性（SSH 远端也正确）。
• 3 次注入硬上限：复用 MaxTestGateRetries，误报最多纠缠 3 轮即停门禁。

11.13.2b judge — LLM 收尾自审（opt-in，默认 report）

• 独立 fresh-context 模型调用：复用 agentFacade.CompactSummaryStream；不带 agent 自己的对话历史，消除自我合理化偏见。
• 看什么：本轮目标 + diff，挑出机检抓不到的逻辑 / 语义 / 安全意图错。
• few-shot 提示 + 当轮诊断背景注入到 prompt，判断更准、误报更少。
• 门控：judge 在所有便宜检查器之后、且仅当 block 检查器全绿时才跑。
• 模型乱报 / JSON 脏 / 超时 → 非权威放行，绝不误拦。
• 返回结构：{ok: bool, issues: [{file, line, severity, confidence, message}]} — severity ∈ error / warning / info，confidence ∈ 0..1。block 模式下的 confidence / severity 阈值过滤为 Phase 2 计划。

11.13.3 lint.run — 静态检查（只读分析）

返回：findings[]（{file, line, rule, severity, message}），与 test.run 同形。golangci-lint v1 / v2 JSON 输出参数已自适应。只读分析，plan / assess 模式可用。

11.13.4 sast.run — 安全静态分析（只读分析）

返回：findings[] 同形。后端：semgrep。只读分析，plan / assess 模式可用。

11.14 tools.list / tools.describe / tools.load — 工具自省与按需加载

自省结果按本会话的实际可用性裁剪（受工具三态与分类延迟加载影响），返回的说明中会提示"表里看不见 ≠ 不存在，可先 tools.load"。这两个自省工具本身穿透子代理白名单恒可用，但输出仍按名单裁剪，且压不过用户设置的禁用清单。

11.14.1 工具分类延迟加载

默认开启（Settings.ToolLazyLoad，schema v9 起）。开关在智能体管理器 →「配置工具」Tab →「工具分类延迟加载」，不在设置页。

• 常驻分类：fs（读写 / glob / grep / exec）、tools（list / describe / load）、agent（委派 + EnterPlanMode / ExitPlanMode / TodoWrite）。
• 16 个可延迟分类：code / git / sec / vt / sbom / mcp / web / skill / test / lint / sast / market / plugin / gh / sys / time。
• 加载路径：① 隐式 —— 按新增 user 消息中的关键词预加载对应分类（中英关键词表）；② 显式 —— tools.load 点名加载。会话中途新连的 MCP 后端分类自动放行。
• 旁路：可见候选 ≤ 32 个时整表放行（子代理白名单模式通常走这条）。
• 开启时系统提示词会注入一段说明，告知助手工具表是有意精简的、可按需加载。
• 每个 MCP 服务可单独设置是否延迟（Settings.MCPLazyLoad，缺省跟随全局）—— 见 §13.1。

11.15 Python venv 自动感知

fs.exec / fs.exec.start 在工作区里跑 Python 相关命令时自动遵循工作区 venv：

机制：把首命令改写成 venv 里的绝对路径 + 注入 VIRTUAL_ENV / PATH。项目外发现缓存 5 分钟 / 探测超时 15 秒。全局关闭：AVLCODE_DISABLE_VENV_AUTODETECT=1。

pyright 语言服务（code.*）也接入 venv 感知，本地 + SSH 远端一致。

例外：SSH 远端的后台命令（fs.exec.start）不做 venv 感知 —— venv 探测靠本机目录结构，在远端会探到错误的本地路径。远端跑 Python 后台任务请显式指定解释器。