AVL Code 参考手册

适用版本：AVL Code v0.7.28-alpha 及以上 适用平台：Windows · macOS · Linux（含银河麒麟 Kylin / 统信 UOS） 文档定位：以查询为目的、表格密集型的参考手册。每章按主题组织，按字段或键名罗列细节，便于在使用过程中按需翻查。

与配套手册的关系：日常使用请阅《AVL Code 用户手册》；初次安装请阅《AVL Code 快速上手指南》；本手册为前两者提供穷举式补充。

目录

1. 总览
2. 工作模式参考
3. 设置面板参考
4. 键盘快捷键参考
5. 输入框 Slash 命令参考
6. 随行通讯命令参考
7. 智能编程工具参考
8. 安全分析工具参考
9. 外部工具服务接入参考
10. 工具权限策略参考
11. 计划与待办状态参考
12. 技能（SKILL.md）格式参考
13. 助手人设参考
14. 模型 Provider 参考
15. 历史折叠（Compact）参考
16. 子任务与后台执行参考
17. 命令行入口参考
18. 主题与外观参考
19. 系统集成参考
20. 状态指示与提示参考
21. 错误信息参考
22. 数据与备份参考
23. 文件命名约定
24. 网络访问清单
25. 隐私与遥测参考
26. 升级与版本号参考
27. 附录 A：术语表
28. 附录 B：参数取值速查
29. 附录 C：常见正则与通配符语法
30. 附录 D：键值清单导出格式

1. 总览

本章给出"哪些东西可被查询"的总图，便于跳转到具体章节。

1.1 查询入口对照

1.2 阅读约定

• 表格中 — 表示"无 / 不适用"。
• 表格中 … 表示"省略，可参阅展开章节"。
• 单元格里的 code 等宽内容代表字面字符串（命令、字段名、文件名、正则、shell 等）。
• 「占位 ID」用 <…> 表示，例如 <workspace-id>。
• 「模式」列出现 — 表示该项不受工作模式影响。

2. 工作模式参考

2.1 模式一览

plan（筹划）是严格只读：只放行读取类工具（读文件 / 读代码 / 读 git / 安全分析 / 联网 / 技能 / 待办与规划本身），不含任何 fs.exec.*（fs.exec.tail、fs.exec.list 在筹划模式下同样不可用）。该限制与所绑定助手声明的工具取交集，助手只能更严、不能更松，配置面板无法放宽。

assess（评估）不写业务代码，但可以执行命令：放行读取类工具之外，还包括终端执行（fs.exec.*）、测试 / lint / SAST（verify.*）、SBOM 生成（sbom.*）、安全分析与威胁情报（sec.* / vt.*），以便真正完成验收与复盘。它禁用的是写文件与编辑（fs.write / fs.patch）。与筹划模式不同，评估模式的这一约束来自其绑定助手的工具声明 —— 若把评估模式改绑到别的助手，约束随之改变。

2.2 模式切换的副作用

2.3 推荐工作流

plan → prepare → execute → assess

各模式间的"退出"按钮显示在会话顶端横幅；点击会自动加载下一模式并把已确认产物（计划 / 准备清单 / 执行变更）注入新一回合。

3. 设置面板参考

设置面板共 22 个 tab，按 6 个分组组织（由旧的「账号 / 桌面 / 服务」3 组重组而来）。下表按界面顺序逐一列出，并标注作用粒度（G 全局 / W 工作区 / M 模式）与默认值。

3.0 设置面板分组

旧的「账号 / 桌面 / 服务」3 组（服务 12 项过载）重组为 6 组，每组最多 6 项，互斥领域 + 使用频率自上而下：

3.1 设置 → 账号

3.2 设置 → 通用

3.3 设置 → 最近工作区（独立 Tab）

3.4 设置 → 数据

3.5 设置 → 上下文

3.6 设置 → 记忆宫殿

3.7 设置 → 提供商

3.8 设置 → 模型

参数编辑收敛到唯一入口：以上模型参数统一在「参数配置」抽屉里编辑（从「模型」页或「模型提供方」对话框进入的是同一个面板），避免此前两处编辑面各存一份、互相覆盖导致设置被静默抹掉。保存时做窗口结构校验：输出上限 ≥ 上下文窗口会拒绝保存；输出上限超过窗口一半会给出提示（建议上下文窗口 ≥ 4 × 最大输出）。两处同时修改时以乐观锁校验，冲突会就近提示而不是无声覆盖。

3.9 设置 → 插件

典型插件目录：仓库自带 22 个开箱插件 — 15 家模型提供方（DeepSeek / OpenRouter / OpenCode Zen / OpenCode Go / MiniMax / 小米 MiMo 按量+Token Plan / 智谱 / 月之暗面 / 通义千问 / 豆包 / Ollama / 硅基流动 / 阶跃星辰 / OpenAI 兼容模板）+ 知乎工具集 + 4 个原生能力示范（tools / hooks / channels / skills）+ 2 个 CC 兼容格式示范（agents+commands、mcp+hooks）。 对话内插件管理：PluginSearch / PluginList / PluginInstall / PluginUninstall 四个工具可在会话中完成插件生命周期，写入类走 dry_run → confirm 两步确认（见 §7.1 注）。

3.10 设置 → Hooks

3.11 设置 → Agents

3.11.1 设置 → 自省（智能体组新页）

把「自主与自省」相关的三个开关集中到一处（tab id reflection，图标 Brain，隶属智能体组）。

这三项原在「通用」页，本版起迁入「自省」页。

3.12 设置 → 技能

签名校验、签名验证策略与信任库已迁至独立的 设置 → 技能/插件签名 Tab（安全分组，见 §3.17.1）。

3.13 设置 → 例行程序

调度参数：

运行行为：

• 每次运行在对应工作区生成正常会话，过程与结果可回看。
• 同一条例行程序运行中自动跳过下一次触发，不会叠跑。
• 手动模式（无计划）保存后立即触发一轮，按钮显示「运行一次」。

3.14 设置 → 随行通讯

3.15 设置 → 数据脱敏

落盘 ~/.config/avlcode/redaction.yaml；主程序与子进程共用 pkg/redact 引擎。

Rule 字段：

内置 secrets 预设清单：AWS Access Key（AKIA…）/ GitHub PAT (ghp_…) / GitHub Token (gh[osu]_…) / Slack Token (xox[baprs]-…) / Stripe Live Key (sk_live_…) / GCP API Key (AIza…) / OpenAI Key (sk-…) / PEM 私钥整块（含头尾与中间 base64，跨行）。

命中反馈：每次脱敏完成时弹一条 toast — 命中条数 + 命中规则 label 列表。

3.16 设置 → 供应链 / SBOM

为 sbom.audit / sbom.vex 配置漏洞库数据源与本地离线库。落盘 <config>/sbom.json；所有字段可留空，留空即回退到内置默认（直连公网），坏 / 缺 JSON 安全回退默认、绝不阻塞审计。后端绑定：SBOMGetSettings / SBOMSetSettings / SBOMSyncDB / SBOMOpenVulnDBDir / SBOMTestSettings。

保存按钮为「测试并保存」：先校验地址 / 路径合法性（URL 须 http/https、代理 http/https/socks5、路径无空字节），再经 SBOMTestSettings 按 default_mode 探测可用性（本地库路径可写性始终阻断式，离线模式跳过联网探测）；任一阻断项不可用则拒绝保存并列出原因。本地漏洞库路径等离线字段归入「离线漏洞库」区，测试时把相对路径规范为绝对路径回写。另有「重置为默认」按钮把各字段清回内置默认（仅改表单，不落盘，需再点「测试并保存」才生效）。

数据源（Data sources）：

离线库（Offline DB）： 按生态表格展示「生态 / 记录数 / 新鲜度（unknown / today / Nd ago）/ 来源」，并列出 KEV 条目数；提供按生态多选下拉（含筛选、全选 / 清空）驱动 同步（每生态独立进度条）与 同步 KEV 按钮。可同步的生态来自后端 SyncableEcosystems（13 个有 OSV 离线 dump 覆盖的生态）。

air-gap 提示：把上面各源指向内部镜像（必要时配代理），再用 sbom.dbsync sync 或离线 import 填好本地库，audit / vex 即可全程离线。

3.17 设置 → 安全（威胁检测 · 哨兵 · VT/GTI）

VirusTotal / GTI 云端威胁情报的配置页（tab id security）。落盘 <config>/vtai.yaml；密钥本机加密存储。检测能力与哨兵拦截解耦——配好后端 / YARA 即可让 Agent 调用扫描工具，无需开拦截。四段：

① 威胁检测

② 自动扫描拦截 · 哨兵（Sentinel）：单开关（合并 enabled+monitor），开启后 Agent 读 / 写 / 执行文件自动扫描、命中即阻断；未配置任一检测方式时置灰（capable = mode≠"" 或 yara_enabled）。

③ Google Threat Intelligence 密钥：API Key（本机加密，user_key 云端与 vt.* 共用；单填不启用任何功能）+ 自定义服务地址（默认 https://www.virustotal.com/api/v3，对接企业 / 内网镜像）。VirusTotal AI 免费托管后端也支持各自独立的自定义接入点（与 GTI 的地址相互独立）。显示名统一为全称 VirusTotal AI / Google Threat Intelligence。

④ vt. 全量情报工具*：主开关（无可用 Key 置灰）+ 子开关 仅查询模式（默认开）/ 启用收费功能（默认关）/ 上传样本前确认（默认开，仅「仅查询」关时出现）；启用后显示「当前有效：仅查询|读写 · 含收费|仅免费 · 自定义端点」摘要。

面板文案为硬编码简体，无 i18n；后端 Wails：GetVTAIState / SetVTAIMode / SetVTAIYaraEnabled / RefreshVTAIKey / GetVTAILeaderboard、GetVTFullToolsState / SetVTFullToolsPolicy / SetVTFullToolsAPIKey / SetVTFullToolsAPIBase；HasAPIKey 用 KeyUsable。

3.17.1 设置 → 技能/插件签名（独立 Tab）

签名验证策略与信任库从「安全」「技能」两页集中迁到此独立 Tab（安全分组，tab id signatures），一份策略同时管住技能与插件：

① 签名验证策略（三档，切换时自愈历史遗留的不一致状态）：

② 信任库：

拒绝 / 导入失败时透出具体原因（签名链、时间戳、篡改点），不是笼统报错。

4. 键盘快捷键参考

当前版本只列已绑定到键盘的快捷键。其它操作均通过界面按钮 / 右键菜单 / 命令面板（输入 /）触发。

4.1 全局

4.2 会话输入框

4.3 命令面板（输入 / 后）

5. 输入框 Slash 命令参考

5.1 通用命令

命令面板的两类命令行为分流：

• 无参命令（/clear、/help、/memory 等）— 选中即时执行。
• 带参命令（/goal、/compact、/memorize、/skill:<name> 等）— 选中后把 /命令 回填到输入框，等你补完参数再回车发送（与主流补全工具一致；避免之前"选中就立刻报『必须带参数』"的尴尬）。

5.2 触发技能

5.3 行为细节

• 命令行首必须以 / 开头，命令名忽略大小写。
• 命令与参数之间用空格分隔；含空格的参数请用 "双引号" 包裹。
• 命令面板（输入 / 弹出）支持 ↑ / ↓ 选择、↵ 执行、Esc 关闭。
• 已加载的技能会以 /skill:<name> 形式动态出现在命令面板里。

6. 随行通讯命令参考

6.1 命令清单

单条临时覆盖（前缀标签）

6.2 入站路由优先级

会话选择（按以下顺序匹配，前者命中即停）：

1. 明确的 /new [文本] 新建
2. 明确的 /s <短id> 切换（行内前缀 [s:<短id>] 等价）
3. 当前对端绑定的最近活跃会话
4. 首次入站兜底：按绑定 / 工作区 + 发送人稳定生成

工作区选择：[ws:<工作区名>] 行内覆盖 > 对端绑定的工作区 > 全局默认工作区；三者皆无时回执提示先 /bind。

6.3 出站节流

6.4 出站工具

下列工具可被助手主动调用，把信息推到 IM。

7. 智能编程工具参考

7.1 工具一览

7.2 通用返回字段

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

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

7.3 read

7.4 write

7.5 patch

7.6 list

7.7 glob

7.8 grep

7.9 fs.exec / fs.exec.start

7.10 fs.exec.tail / fs.exec.kill / fs.exec.list

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

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

7.11 web.bing / web.fetch

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

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

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

7.12.1 内置语言（22 门，按 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 等），并显示安装进度。

7.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 掉线自动重启。

7.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 参数

复用当前会话的 provider / model（隐式注入，未取到则回落 AVL-Zero）。返回 answer + citations[]（file / start_line / end_line / name）+ hit_count + model；检索不到会直说、不编造。code.ask 现在默认对扩展检索结果做结构感知智能重排（无需显式 expand），回答更聚焦。

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

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

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

7.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 }

7.13.2 CheckSpec 字段

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

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

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

• 独立 fresh-context 模型调用：复用 agentFacade.CompactSummaryStream；不带 agent 自己的对话历史 — 消除自我合理化偏见（这是 LLM-as-judge 区别于「让 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 计划。

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

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

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

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

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

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

7.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，缺省跟随全局）—— 见 §9.1。

7.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 后台任务请显式指定解释器。

8. 安全分析工具参考

8.1 适用约束

• 全部工具仅在当前工作区下名为 samples/ 的子目录中可用。
• 该子目录下 exec 类工具被强制禁用，且不可解除。
• 分析工具不修改样本本体；samples/ 目录本身可写入（样本投放、sec.pcap_stream_extract 的提取产物都会落盘）。

8.1.1 样本投放入口

后端透明支持本地与远程工作区。

8.2 工具一览（共 16 个）

8.3 sec.hash

8.4 sec.entropy

8.5 sec.strings

8.6 sec.ioc_extract

先自动还原 defang（hxxp://、1.2.3[.]4、evil[.]com、foo(dot)bar）再在可打印字符串上匹配（减二进制噪声）。IP 走 net.ParseIP 校验并打标（private/loopback/link_local/multicast/cgnat/unspecified），MAC 不再误判为 IPv6，域名按公共后缀校验（丢弃 kernel32.dll 之类）。按值去重、附 count 与 tags（含 defanged）。分页同 sec.strings（limit 与 byte_limit 取更紧者；truncated=true 时读 next_offset / per_kind_capped / hint 续取）。

可选 kinds：

提取是候选指标、非判黑结论，用前请二次核实。

8.7 sec.pe_parse / sec.elf_parse / sec.macho_parse

8.8 sec.disasm

8.9 sec.decompile

隐私提示：sec.decompile 会把反汇编片段送往反编译模型；只在样本可外送的前提下使用。

8.10 sec.pcap_info / sec.pcap_stream_list / sec.pcap_stream_extract / sec.pcap_extract

v1 仅做单包检视，不做 TCP 重组。

8.11 sec.yara_scan

8.12 sec.ontology.* — 安全领域事实层（v1 本地工作区）

实体命名约定：建议带类型前缀（pkg:lodash / svc:api / cve:CVE-2021-23337），便于跨类查询。SSOT 持久化：事实落到工作区，对话折叠不影响。

8.13 软件物料清单（SBOM）工具 — 供应链漏洞排查

sbom.* 是工作区工具（作用于项目的依赖清单，不限于 samples/），共 5 个。结果文件默认落到工作区 .avlcode/ 目录。配套设置见 §3.16。

8.13.1 sbom.generate

识别的生态（Ecosystem 常量）：go · npm（含 yarn Berry / pnpm v5）· cargo · pypi · maven · gem · composer · nuget · swift · pub · conan · conda · hex · cocoapods · cran · hackage · julia（本版新增；另新增 Deno 清单支持）。清单文件同前（npm/pypi/conan 多锁首个命中为准，maven 三种全读）。本版增强：清单扫描递归子目录、缺锁回退清单文件解析；剔除首方误报、正确处理 Go replace/exclude、版本比对保真；审计逐生态回退 + Maven/Gradle/pip/Conda/Conan/npm 精度提示 + 未审生态明示 + 可利用性描述。缺清单跳过该生态，全缺得 0 组件空清单（非错误）。输出确定性可复现（无时间戳 / 随机序列号、组件定序）。返回字段：format / encoding / component_count / ecosystems / bom_path / components（预览，最多 50）/ truncated。

8.13.2 sbom.convert

经规范化中间模型转换（N 读 + N 写）；保留组件 / purl / 许可 / 哈希 / 依赖关系，目标不支持的字段按规则丢弃（DSDX 无哈希、SWID 哈希不映射）。格式与编码矩阵：CycloneDX(1.5) JSON+XML、SPDX(2.3) JSON+RDF/XML、DSDX JSON+XML+native、SWID JSON+XML，均可读可写。

8.13.3 sbom.audit

对照 OSV 匹配；CVE 取首个 CVE-… 别名；KEV 取自 <config>/kev.json。严重度按 CVSS 向量计算：v2(AV:/AC:/Au:) / v3(CVSS:3) / v4(CVSS:4.0，官方 MacroVector 查表)；定级 critical ≥9 / high ≥7 / medium ≥4 / low >0；记录自带 GHSA 定性等级时以其为准。结果最严重优先、KEV 置顶。返回字段：source / components_scanned / vulnerable / total_vulns / by_severity / kev_count / report_path / findings（预览，最多 30）/ truncated。

8.13.4 sbom.vex

先跑 audit，再做确定性符号级可达性分析。状态：affected / not_affected / under_investigation / fixed；not_affected 带机读理由（vulnerable_code_not_present / vulnerable_code_not_in_execute_path / component_not_present / inline_mitigations_already_exist）。可达性扫描上限：≤4000 文件、≤256 KiB/文件，跳过 .git/node_modules/vendor/target/dist/build 等目录。Go 凭 OSV 受影响符号可直接收敛 not_affected；其它生态默认「用到即 affected、没用到即 under_investigation」（不擅自判 not_affected），可经 lsp_confirm 或 App 端符号比对进一步收敛。结论按 affected > under_investigation > fixed > not_affected 排序。

8.13.5 sbom.dbsync

13 个生态有 OSV 离线 dump 覆盖（SyncableEcosystems）；conan / conda / CocoaPods 暂无离线库（可在线审计）。import 缺 zip_path 或 osv_eco 报错。

8.14 云端威胁情报工具（VirusTotal / GTI）

两组工具、独立门控，均在 设置 → 安全 配置（见 §3.17）。

哨兵哈希扫描 sec.vtai_*（绑定「自动扫描拦截·哨兵」配置，用 vtGuard）：

全量情报 vt.*（full_tools 策略门控，与哨兵并存）：

full_tools 策略字段：enabled / query_only（默认开）/ enable_paid_features（默认关）/ confirm_sample_upload（默认开）/ api_base。Check() 顺序：未启用 → ErrDisabled；写 + 仅查询 → ErrQueryOnly；非 public 档 + 未开收费 → ErrPaidDisabled。档位（public/premium/gti）由 VT 远端 403 兜底。启用需 KeyUsable（密文可解密且非空），否则启用环节即报错。响应默认经 Summarize() 紧凑摘要（names cap 8、tags cap 12），raw=true 取原始。超时：api/lookup/hunt/submit 30s，download/feeds 5 分钟。

9. 外部工具服务接入参考

9.1 服务条目字段

每个外部服务条目包含：

凭据存储（VAULT）：credential / env / oauth.refresh_token 与续期元数据不入主配置文件、不入日志，统一进国密加密的凭据库（SM4-GCM + HKDF-SM3，machineID 绑定）；存量明文凭据下次使用时被动迁移。

9.1.1 OAuth 流程字段

9.1.2 健康看板字段

MCP 配置 → 健康看板 来源是 zMCP gateway 的 /admin/metrics 环形缓冲：

9.2 工具命名规则

9.3 错误抽屉条目

后端缺席兜底：某后端一时缺席 / 未就绪时，tools/call 过去会返回「unknown tool」协议错误；现对未知工具做兜底处理并按需重连自愈，后端就绪后自动恢复，不再因此整体不可用。

10. 工具权限策略参考

10.1 三态语义

三态对子代理同样生效：「禁用」在主代理与子代理两侧一并生效（子代理侧 fail-closed，工具直接不可见）；卸载插件 / 移除 MCP 后端时自动清理残留的工具配置键，盘上配置与实际可用工具保持一致。

10.2 决策聚合与多端应答

Hook 决策聚合：同一次评估中多个 Hook 返回的权限决策按下列优先级合并（前者胜）：

deny  >  defer  >  ask  >  allow

多端应答：审批弹窗与远程通道（微信等）同时收到同一请求时，首个应答生效；其余端的后续回复会被提示已应答。

10.3 白名单匹配粒度

10.4 远程审批回写

10.4.1 无限制模式（高级）

输入区模式滑块右侧盾牌开关；按会话独立、纯内存、重启即清。开启前有 5 秒冷静期。

始终保留的硬底线（不受开关影响）：

消息标识：模式期间产生的连续消息以浅色边框整体圈出（起止界标），关闭后当场收口；模式未结束不打「结束」界标。子代理可按需递归继承该模式，继承产生的消息同样带标识。

10.5 审批请求字段与留痕

审批弹窗（hook:ask 事件）携带的字段：

决策取值：deny（拒绝）/ allow_once（仅本次允许）/ always_allow（始终允许）。

留痕：仅「始终允许」会持久化 — 写入工作区级授权文件 hook-approvals.yaml（记录授权指纹与决策时间），可在 设置 → Hooks 查看与撤销；「仅本次允许」「拒绝」与超时只作用于当次调用，不落盘。

11. 计划与待办状态参考

11.1 计划（Plan）状态机

11.2 待办（Todo）状态

11.3 跨折叠保留

历史折叠发生时，下列字段始终原样保留在新摘要中：

• 计划当前状态（起草中 / 草稿就绪 / …）
• 计划的最新版本号与差异概要
• 待办列表的全部条目与其状态
• 用户已确认的关键决策（"接受了 v3 计划"）
• 上下文必需事实（路径、版本号）

12. 技能（SKILL.md）格式参考

12.1 文件结构

<skill-root>/
├── SKILL.md              # 必需。前置元数据 + 模板正文
├── README.md             # 可选。给人看的说明
├── examples/             # 可选。示例输入输出
└── …                     # 可选附加资源

12.2 前置元数据字段

SKILL.md 顶部使用 --- 分隔的 YAML 前置元数据，所有可识别字段：

12.3 正文模板

正文为标准 Markdown，支持下列扩展：

12.4 三层加载优先级

12.5 调用方式

12.6 内置技能

应用内置一批技能（如 skill-creator），启动时自动物化、内容漂移自动覆盖；通过构建期签名 + 内置签名锚点（trust ExtraSignerRoots），在严格签名策略下也放行。设置 → 技能 面板以「内置」徽标区分内置 / 自建 / 第三方。兼容 Agent Skills（agentskills.io）：跨客户端发现 / 解析容错 + 工具名翻译映射。

12.7 market.check（发布契约校验）

内置只读、确定性、离线工具，按 zMarket 发布契约校验本地技能 / 插件目录：

报告过 / 不过 + 原因 + 缺什么（name slug、严格 semver、source 形态、能力声明、归档安全等）。不联网、不提交。注：.skill-sign 签名 ≠ zMarket 认可；只查发布契约形态，非运行时安全审计。

13. 助手人设参考

13.1 人设字段

13.2 内置人设

13.3 模式 → 助手绑定

每个工作区维护一份 5 项映射（mode → persona id）：

mode_persona:
  auto:    builtin/auto
  plan:    builtin/plan
  prepare: builtin/prepare
  execute: builtin/execute
  assess:  builtin/assess

14. 模型 Provider 参考

14.1 Provider 字段

14.2 内置 Provider 占位

14.3 参数命名映射

15. 历史折叠（Compact）参考

15.1 触发方式

15.2 折叠摘要的字段

15.3 多次折叠

折叠是 append-only 的：每次折叠都新增一条节点而非替换；UI 上以"折叠摘要 →（展开）→ 原消息"层叠展示，可逐层展开到最早历史。

16. 子任务与后台执行参考

16.1 派发参数

16.2 BackgroundRegistry

16.3 子任务工具

16.3.1 AgentParallel 参数

少于 2 条会报错（改用 Agent），多于 16 条静默截断到前 16。每条腿作为真实后台任务派发、内部统一 Wait(all) 聚合；单腿输出超 8000 runes 截断（提示用 TaskOutput 取全文）。腿为叶子层、不可再嵌套 Agent / AgentParallel。v1 仅 all 模式。返回 ParallelResult（completed / num_ok / num_failed / num_pending / legs[] 等，永不抛错）。

渲染：调用卡片执行期即显示并随实时 store 反映各腿运行状态（停止后不再转圈）；极简密度下结果块不被工具组误折叠。

16.4 长程任务崩溃恢复

后台任务（run_in_background=true）的进度落盘到本机全局目录（每任务一份 JSON 快照）；走到终态（done / error / killed）即删除快照。

16.5 自修复循环参考

错误按来源（request / gateway / upstream）与类别分流后映射到 4 类修复策略，各有按会话计的尝试上限：

特例：upstream 来源的 auth_error 重判为 transient_fallback（某通道 key 失效而非用户凭据）；仍可重试的 terminal 救回为 backoff；5xx / 408 默认可重试，其它 4xx 终止。

网络抖动自愈：瞬断 / 临时离线时探测「离线 → 在线」再续跑，这段等待不计入重试预算；连接重置、DNS 暂时解析失败、握手中断等连接级瞬断细分为网络问题（而非笼统 llm_error），不误导你排查上游配置。

产出型自愈（MaxOutcomeHeal = 3）：回复被长度截断自动续写（truncated_continue）、推理绕圈打断（reasoning_loop）、内容过滤换述（content_filter）。门禁升级：同一处检查 / 测试失败或待办无进展达上限（测试门禁 3 次、无进展待办 2 次）时升级提示换思路。供应商备选通过 App.RespondProviderFallback 回写确认，前端为 SelfRepairFallbackBanner；后端事件 self_repair:fallback_confirm / _applied / _declined / self_repair:outcome。

16.6 经验学习闭环参考

17. 命令行入口参考

命令行版本与桌面版共享同一份会话与配置，互相之间可以接力。

17.1 主子命令

tui / zagent-tui 由主二进制内置，无需额外安装 zBoxFull 发行包。

17.2 通用参数

17.3 退出码

18. 主题与外观参考

18.1 主题三档

18.2 关键色（用户可感知）

18.3 字体

18.4 Header 快捷菜单（显示组滑块）

Header 右上快捷菜单集中四个外观滑块，与设置页同源同步：

18.5 会话状态条（strip）布局

会话状态条纳管文件变更、记忆、待办、计划、目标、引导、结果草稿、附加资料、建议任务、自检门禁共 10 类条目，按窗口宽度在两种形态间自动切换：

• rail 形态下展开为右侧堆叠抽屉：固定定位、无遮罩、不挤压正文，宽 680px；以整个 rail 为锚，切换不同条目时抽屉位置稳定，并按两侧可用空间自动选择向左或向右展开。
• 超宽窗口下固定预留抽屉槽位，「内容 + rail + 抽屉」整体居中，开合抽屉不会移动主内容。
• 切换布局只改变位置，不改变内容宽度。

19. 系统集成参考

19.1 系统托盘

19.2 开机自启

启动参数：--from-autostart，配合"最小化到托盘"走静默启动。

19.3 通知

19.4 在线文档入口

20. 状态指示与提示参考

20.1 左侧栏状态点

20.1.1 上下文占用圆环

显示当前上下文窗口占用比例的圆环按占用分档变色：

20.2 会话标签徽章

20.3 输入框右侧按钮

21. 错误信息参考

下表收录用户最常见的提示文案及其含义与处置建议。

22. 数据与备份参考

22.1 备份内容

22.2 备份与恢复

22.3 完整清理

关闭应用 → 删除应用本体 → 删除数据目录

数据目录包含登录凭证、会话历史、外部服务凭证；删除后不可恢复。

22.6.1 SSH 远程工作区协议

SSH 工作区与本地工作区的差异：

22.6.2 会话附加目录

22.7 项目指令（AGENTS.md）

工作区根目录放 AGENT.md / AGENTS.md / CLAUDE.md（按优先级取一份），自动作为系统提示里的「# 项目指令」块。

22.8 消息内链接与文件路径点击行为

点击后弹出非模态浮动工具条（主动作「查看 / 打开」+「复制」），用 Popover API 渲染在顶层，弹窗内点击同样不被遮挡。「查看」对带行号的源码走 PreviewSourceFile(target, line) 在代码视图定位到该行，让 code.search / code.ask 给出的 文件:行 证据可核对。

23. 文件命名约定

下表为用户可见的文件命名规则，方便手工脚本化处理（不要修改这些文件，除非显式说明可以）。

24. 网络访问清单

下表收录应用可能发起的网络请求，便于在受限网络环境中加白。

应用不会：

• 主动联网做行为埋点。
• 把样本本体上传到任何第三方（仅反编译会按需发反汇编片段）。
• 自动同步本地会话到云（除非显式启用同步开关）。

25. 隐私与遥测参考

25.1 默认行为

25.2 加密存储项

下列条目以受保护方式存储在本机：

• 登录凭证
• 模型 Provider API Key
• 外部工具服务 Bearer Token / 凭证
• 通道（微信 iLink）会话状态

25.3 会话内容

会话内容仅在本机持久化；只有你主动调用模型时才把对应消息按 Provider 协议发出。

26. 升级与版本号参考

26.0 配置目录品牌迁移（zcode → avlcode）

自 v0.6.30-alpha 起，内部标识统一由 zcode 迁移为 avlcode，启动 / 打开工作区时自动完成、有 toast 提示、保留旧名双读回退：

界面与对外输出里残留的「zCode」统一为「AVL Code」。脚本里写死过旧路径 / 旧变量的，建议改用新名。

26.1 版本号格式

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

26.2 升级路径

官网下载页按平台提供构建（Windows x64 / macOS 通用版·Apple 芯片版 / Linux x64·AppImage·Snap·WebKit4.1 / 银河麒麟 V10 SP1 / 统信 UOS V20），走 alpha 渠道、恒为最新构建。

26.3 升级签名

27. 附录 A：术语表

28. 附录 B：参数取值速查

28.1 默认上限

28.2 文件大小硬上限（工具读取）

28.3 退出码语义

29. 附录 C：常见正则与通配符语法

29.1 文件名通配（glob）

示例：

29.2 内容搜索（RE2）

不支持反向引用 \1、回溯前瞻 (?<=…) 等 PCRE 扩展。

30. 附录 D：键值清单导出格式

设置面板支持把当前所有设置导出为单一 YAML 文件，便于版本管理与团队同步。

30.1 顶层结构

version: 1
exported_at: 2026-07-28T08:00:00Z
exported_by: AVL Code v0.7.28-alpha
sections:
  account:        { … }
  models:         { … }
  personas:       { … }
  tools:          { … }
  skills:         { … }
  messaging:      { … }
  plugins:        { … }
  general:        { … }
  workspaces:     [ … ]

30.2 节字段速查

30.3 注意

• 凭证类字段在导出时不会写入；目标设备需重新登录或填写。
• 同步开关单独维护，不在导出范围内。

License：AVL Code Proprietary Software License — Copyright © 2024–2026 Antiy. All Rights Reserved. 文档版本：2026-07-28，对应应用版本 v0.7.28-alpha。