AVL Code 用户手册

适用版本：AVL Code v0.7.28-alpha 及以上 适用平台：Windows · macOS · Linux（含银河麒麟 Kylin / 统信 UOS） 文档定位：面向所有 AVL Code 用户的完整功能参考手册，覆盖从首次安装到日常使用、团队协作与高阶定制的全部能力。

目录

1. 产品简介
2. 下载、运行与系统要求
3. 账号、用量与计费
4. 工作区
5. 会话
6. 五种工作模式
7. 助手人设
8. 模型与参数
9. 工具体系总览
10. 智能编程工具
11. 安全分析工具
12. 外部工具服务接入
13. 工具权限与审批
14. 技能（Skill）系统
15. 子任务与后台执行
16. 计划与待办
17. 历史折叠（Compact）
18. 随行通讯
19. 插件与扩展
20. 全局设置
21. 主题与外观
22. 系统托盘与开机自启
23. 快捷键与命令
24. 升级、备份与同步
25. 卸载与数据清理
26. 故障排查与常见问题
27. 最佳实践
28. 安全与隐私
29. 附录 A：术语表
30. 附录 B：设置速查
31. 附录 C：内置命令清单

1. 产品简介

AVL Code 是一款由 安天 澜砥 团队推出的 AI 智能编程与安全分析桌面助手，全平台原生分发，开箱即用。它把"对话式 AI 助手"与"工程师真实工作台"无缝结合，让大模型不仅能回答问题，还能直接读写文件、跑命令、查日志、做安全分析、按计划推进任务。

1.1 适用人群

• 应用与系统开发工程师：希望让 AI 真正在自己的代码仓库里干活，而不只是在网页对话框里贴片段。
• 安全分析师 / 逆向工程师：希望在一个统一界面里完成样本基础分析、IOC 抽取、反汇编、反编译与规则匹配。
• DevOps / 运维工程师：希望让 AI 帮忙读日志、批改配置、整理脚本，并能受控调度。
• 团队 Leader / 项目经理：希望团队成员的 AI 工作流可被审计、被审批、可在群里协作。

1.2 核心价值主张

• 零配置开箱：登录后自动下发共享额度，无需手动配置 API Key。
• 本地优先：所有会话保存在本机，不上传第三方；断网不丢、重启可恢复。
• 国密合规：技能扩展包采用国密签名，与开源安全生态可互操作。
• 随行通讯：通过微信通道在手机上远程驱动桌面助手、接收审批卡片、与团队协作。
• 行业能力：内置一套面向二进制安全分析的只读工具组，可直接在样本上做基础研判。
• 工作流化：「筹划 / 准备 / 执行 / 评估」四阶段工作流，AI 像一位有自律的同事而不是一台只会回答的机器。

1.3 与同类产品的差异

AVL Code 与通用大模型对话工具的差异在于："它真的在你的电脑里干活"。

• 不只是给代码片段 — 直接编辑你的工程文件并让你 review 差异。
• 不只是给命令建议 — 直接执行命令并把输出贴回对话流。
• 不只是给方案 — 在筹划模式下用结构化计划与待办，逐步推进。
• 不只是单机 — 通过随行通讯把审批与进度推送到手机和团队群里。

2. 下载、运行与系统要求

2.1 系统要求

2.2 下载与运行（免安装）

AVL Code 免安装、下载即用 —— 没有安装向导。到官网下载页 www.avlcode.cn/#download 选择对应平台的构建后直接运行即可（内测版走 alpha 渠道，各平台链接恒为最新构建）：

• Windows / Linux：下载即运行，无需安装。
• macOS：建议把应用拖进 应用程序 文件夹再运行 —— 否则从「下载」/「桌面」直接运行时，检查更新会被系统 App Translocation 机制锁住（见 §26.7.2）。
• 国产化环境：银河麒麟 V10 SP1、统信 UOS V20 提供专门构建。

文档见 www.avlcode.cn/docs（用户手册 / 快速上手指南 / 参考手册）。

首次启动时会进行少量本地初始化，整个过程对用户透明，无需额外操作。

2.3 首次启动

启动后将看到主界面三大分区：

• 左侧栏：工作区列表 + 登录入口 + 设置入口。
• 中央会话区：会话标签页 + 消息流 + 输入框。
• 右侧浮层（按需弹出）：计划 / 待办、助手配置、审批弹窗等。

如果是首次启动，建议先点击左下角的「登录」按钮完成账号绑定（见第 3 章）。未登录状态下也可以用，但需要在 设置 → 模型 中手动配置 API Key。

2.4 命令行入口（高阶）

除桌面应用之外，AVL Code 还提供一组命令行入口，供希望脚本化或在远程服务器上协同使用的用户。命令行版本与桌面版共享同一份会话与配置，互相之间可以接力。命令行入口的具体获取方式与子命令清单见 设置 → 数据 → 命令行工具。

主二进制内置的 TUI 子命令（无需额外安装）：

3. 账号、用量与计费

AVL Code 推荐通过统一管理后台完成登录，登录这一步会自动为本机分配一份共享额度，无需手动配置 API Key。

3.1 登录方式

账户页未登录区分两段切换：手机登录（默认）| 密码登录。

三种方式得到的额度完全等价（取 key、状态同步一致），体验差异只在登录环节本身。

3.2 共享额度与个人额度

登录成功后，系统会自动为你分配一份共享额度。共享额度由组织统一管理、统一计费，个人无需关心余额；如果组织设有个人配额，会显示在 设置 → 账号 的点数余额面板上。

如果你希望使用自有的模型 API Key（例如个人订阅的 OpenAI / Anthropic / 阿里云模型服务），可以在 设置 → 模型 里添加，AVL Code 会优先使用你自己配置的 Key，自动回退到共享额度作为兜底。

3.3 用量监控

设置 → 账号 面板自动展示三档用量统计：

• 24 小时
• 7 天
• 30 天

每分钟刷新一次；如果你触发了某些异常，例如短时间内大量调用，点数余额面板上会以提示色高亮，方便定位异常。

3.3.1 配额提示按用量 / 重置时间分层

配额耗尽前的提示不再只有一档，而是按「当前用量百分比 + 距离重置时间」分层显示：

• 轻量提示：用量未紧、距重置还远 → 仅状态点变色，不打扰。
• 中度提示：用量近上限或重置时间即将到来 → 输入框上方信息条提示，可直接看到「剩余 N 点 · 还有 M 分钟重置」。
• 强提示：用量已近耗尽且重置仍远 → 横幅 / 卡片提示，附建议（切换备用 Provider / 续兑换码）。

提示文案会把重置时间用本地时区直观展示（如「今天 18:00 重置」），不再只说「即将耗尽」。

3.4 凭证过期

登录凭证有效期约 24 小时。

• 离过期不到 1 小时时，左侧栏状态点变为琥珀色。
• 过期后下一次操作会弹出"登录已过期"提示并自动跳到登录页。
• 重新登录不会丢失会话或配置。

3.4.1 兑换码与代金券

设置 → 账户 新增「兑换码」区块：

1. 输入兑换码 → 点「兑换」。
2. 结果就地反馈（成功 / 失效 / 已用过等 12 种情况都有明确的本地化提示）。
3. 下方可查看「我的用量点券」列表：面额、有效期、永久券（明确标注「永久」）。

3.5 退出登录

设置 → 账号 → 登出。退出后本机会清除登录凭证与共享额度的访问能力，但本地工作区、会话、技能、设置全部保留，下次登录后无缝继续。

4. 工作区

工作区（Workspace）是 AVL Code 的最小执行单位，每个工作区绑定一个本地目录与一组配置。

4.1 创建工作区

1. 左侧栏点击「+ 新建工作区」。
2. 选择本地路径（例如 ~/projects/my-app 或 ~/samples/2026-04-malware）。
3. 为工作区起一个简短名字，作为左侧栏与微信侧的快捷标识。

一个本地目录可以被多个工作区共享，例如同一个仓库可以分别创建"开发"与"安全审计"两个工作区，绑定不同的助手人设与工具策略。

4.2 工作区目录结构

每个工作区维护以下信息（用户无需直接操作，仅作了解）：

• 该工作区下所有的会话历史
• 工具开关与权限策略
• 助手人设到模式的绑定
• 接入的外部工具服务列表
• 随行通讯绑定关系
• 本工作区可见的技能扩展

所有这些都以工作区为单位独立保存，互不干扰。

4.3 切换、归档与删除

• 切换：左侧栏点击对应名字，或快捷键 ⌘1 ~ ⌘9（macOS）/ Ctrl+1 ~ Ctrl+9。
• 重命名：右键 → 重命名。
• 在系统文件管理器中查看：右键 → 在 Finder 中查看 / 在文件管理器中查看（按平台显示对应文案）。Header 顶部下拉菜单中也有相同入口，便于直接跳转到工作区的本地目录。
• 关闭其他工作区：右键 → 关闭其他工作区。一键保留当前焦点的工作区，关闭其他所有的，常用清场动作不再需要逐个关。
• 归档：右键 → 归档。归档后工作区从主列表移除，仍可在 设置 → 最近工作区 里恢复。
• 删除：右键 → 删除。删除会清空该工作区的会话与配置，但不会删除你的源代码或样本本身。删除前会有二次确认。

macOS 上的"打开工作区"系统对话框支持直接新建文件夹，无需先到 Finder 里建好目录再选。

4.4 项目指令（AGENTS.md）

在工作区根目录放一份 AGENT.md / AGENTS.md / CLAUDE.md（按此优先级取一份），里面写的项目约定会作为独立的「# 项目指令」块自动加进系统提示，AI 每轮都遵守你这个项目的规矩（代码风格、目录约定、禁忌项等）。

• 每轮重新读取：改了立即生效，不用重启。
• 子目录指令按需注入：AI 读写某个子目录下的文件时，会自动把那条路径上各级目录的 AGENT.md 一并带进来作为补充上下文（每会话每子目录只注入一次，不刷屏）。大仓库里不同模块各有规矩时尤其有用。
• 安全护栏：读取走工作区内路径校验 + 符号链接逃逸防御（解析真实路径后确认仍在工作区内），不会被符号链接带出工作区；超长文件按 UTF-8 字符边界安全截断并加截断标记，不会截出乱码。

4.4.1 内置 AGENTS.md 编辑器

不用切到外部编辑器：会话菜单 / 工作区菜单（侧栏 + Header 当前工作区）都新增了「编辑 AGENTS.md」入口，弹出内置编辑器：

• 编辑 / 预览（markdown 渲染）一键切换。
• 快捷键：Cmd/Ctrl+S 保存、Tab / Shift+Tab 缩进。
• 实时字数统计在副标题区。
• 未保存保护：有改动未存就关闭会先确认，避免误丢。
• 空状态给内置模板：从零开始时填入一份可直接改的 AGENTS.md 模板。
• 保存同样经符号链接逃逸校验，只写工作区根目录的 AGENTS.md。

4.4.2 SSH 远程工作区（远端零安装）

只要远端机器能 SSH 登录，就可以把它的目录当作工作区使用 — 远端什么都不用装，文件读写、命令执行、git 操作全部通过 SSH / SFTP 通道完成。

添加入口：左侧栏「添加远程工作区」对话框按协议分段（zWorkspace / SSH）。SSH 表单支持：

• 密码 / 私钥 / 私钥 + 口令 三种认证方式；私钥可用文件选择器挑选
• 远程根目录支持 ~（自动展开为远端家目录）；不允许指向 /，也不能经 .. 或 ~/.. 逃出家目录
• 「记住密码 / 口令」复选框：勾选则加密落盘长期保留；不勾选则只在本次运行期间有效 —— 连接期内保留以便重连，应用启动与退出时自动清除
• 已添加的连接右键 → 「编辑 SSH 连接」修改（复选框会按已存状态预填，避免误把已记住的凭据降级）

凭据安全：SSH 密码与私钥口令一律国密 SM4-GCM 加密落盘，与本机绑定，且每次保存使用随机盐。

首次连接要核对主机指纹：连接一台新主机时，对话框内会展开确认区块，列出该主机的 host:port 与 SHA256 密钥指纹，请与服务器方提供的指纹核对一致后再点「确认继续」。确认之前不会发送密码；确认后指纹才被钉住，之后连接自动校验。若已知主机的密钥发生变化，连接会直接失败而非静默接受 —— 这可能意味着中间人攻击，请先确认变更来源。

远端深度集成：

• 文件变更面板走远端 git（远端没装 git 时明确隐藏，不再报错堆红框）。
• 技能（Skills）/ 插件（Plugins）/ 钩子（Hooks） 在 SSH 工作区全部可用：技能从远端读取、插件人设写到远端 .avlcode/、hook 命令在远端执行。
• 文件威胁扫描（VirusTotal AI）对远端文件同样生效（经 SFTP 取字节后扫描）。
• fs.grep 在 SSH 下走远端系统 grep 提速。
• 计划 / 结果草稿等文件统一落远端，不再本地 / 远端两边脑裂。
• 后台长驻命令同样可用：可在远端启动长时间运行的命令（服务、构建、测试），随时拉取输出、列出在跑的任务、需要时终止。会话状态存在远端，断线重连、甚至应用重启后仍能列出并继续跟踪（本地工作区的后台会话则随应用退出结束）；终止时连同子进程一并收走。注意远端后台命令不做 Python 虚拟环境自动感知（venv 探测依赖本机目录结构），需要时请在命令里显式指定解释器。

安全收口：

• samples/ 子沙箱全链路走远端。
• sys.info 如实报远端身份。
• 右键菜单不提供「关闭并清除数据」 — 这个清理动作对本地工作区清的是自管数据，但对 SSH 工作区删的是远端服务器上的真实目录，误删不可挽回。普通「关闭工作区」保留；后端硬性拒绝该操作（即使绕过界面直接调用也拒），错误提示引导改用「移除工作区」（只清本地记录与已存凭据，不碰远端文件）。

连接失败的提示就近内联在对话框里并区分原因（密码错 / 不可达等），不再只弹一个含糊的 toast。

跨 OS 客户端（Windows 客户端连 Linux 远端，或反之）已彻底打通：远端命令不再注入本机环境变量（用远端登录 shell 自带环境），远端路径一律按 POSIX 文法构造。早期版本在 Windows 上连 Linux 时几乎每条命令都会报 bash: syntax error 或路径找不到，本版根治。

自定义名称重启不丢：给 SSH / 远程工作区改过名后，重启恢复时会读回你保存的名称，不再被自动派生的 SSH-<主机名> 覆盖。

4.5 同时活跃工作区上限 7

为防止一次性开太多工作区把内存 / 句柄打满，AVL Code 把"同时活跃"的工作区数量限制在 7。一旦达到上限：

• Sidebar 上的「+」与「打开远程工作区」按钮自动隐藏。
• 在 设置 → 最近工作区 中点开历史项也会被拒绝并提示原因；提示出现时 Settings 不会自动关闭，让你读完再决定。

需要继续加新工作区时，先在 Sidebar 上右键关一两个不再用的工作区即可。

4.6 最近工作区面板

设置 → 最近工作区 是一个独立 Tab，专门管理打开过的所有工作区：

• 搜索框始终显示，列表自适应滚动；命中词高亮。
• 置顶区 与 其他区 各自独立滚动，置顶项不会随下方列表滚动消失。
• 支持多选 + 顶部批量操作栏（批量删除 / 打开所选）。
• 批量打开改为「打开所选」（不再是「打开全部」），避免一不小心一次性打开太多；超过同时活跃上限时按前 N 项截断打开并明确告知。
• 删除走 inline 倒计时（武装-倒计时-确认两步式），不再弹原生 confirm。

4.7 工作区粒度的设置

下列设置都是按工作区独立的：

• 默认工作模式
• 五种模式各自指派的助手
• 工具开关与权限策略
• 模型选择与参数
• 接入的外部工具服务
• 随行通讯绑定

如果你希望把一份配置复用到新工作区，可以使用 设置 → 数据。

4.8 工作区与会话布局（侧边栏 / 顶部标签页）

工作区与会话的导航布局有两档，可在 设置 → 通用 → 工作区与会话布局 切换（Header 快捷菜单的「布局」滑块也能一键切，无需进设置页）：

顶部标签页模式的细节：

• 每个工作区一枚彩色 chip，当前工作区展示名称；点 chip 文字或 ▾ 都能开合下拉（最近会话 / 新建会话 / 新建例行程序）。
• 会话以标签呈现：点击切换；活动标签带 × 关闭按钮，鼠标中键或右键菜单「关闭标签」同效。关闭标签只是移出标签条，会话本身仍在，可从 chip 下拉或命令面板找回。
• 打开的标签会被记住，重启后自动恢复。
• 固定标签：右键菜单「固定标签」把常用会话钉在标签条前部，固定的标签不会被数量上限挤掉，并归入「已固定」分组；再次右键可取消固定。
• 拖拽重排：标签可直接拖动调整顺序。默认按最近更新时间排列，一旦拖动就转为手动顺序；右键菜单「按最近更新排序」可复位回默认。
• 标签条右端保留登录 / 设置 / 帮助与版本徽标；登录后会显示当前用户名（定宽显示，过长自动省略号截断，悬停可见全名）。

4.8.1 会话列表的排序与分组（侧边栏布局）

侧边栏的会话列表可以按你的习惯组织。点列表工具条上的滑块图标打开「排序与分组」菜单：

• 选手动拖拽排序时列表强制平铺不分组，可直接拖动会话调整次序。
• 排序与分组方式是全局偏好，手动排出来的顺序按工作区分别保存。
• 默认组合（最近更新 + 按时间分组）与以往行为一致，不动设置即可保持原样。

5. 会话

会话（Session）是一次连贯的对话上下文。

5.1 持久化

AVL Code 会把每一条消息持续追加到本地，断电、关机、重启都不会丢。每条消息都有时间戳与作者标识；工具调用、计划修改、审批结果也会以独立卡片形式记录，整条会话可作为完整的工程审计材料。

5.2 会话操作

• 新建：会话标签栏 → 新建，或快捷键 ⌘N / Ctrl+N。同一个工作区内最多只保留一条空白草稿：反复点 +、按 ⌘N、发 /new 都复用同一条，未发出第一条消息前不会进侧栏，避免堆出一串"新会话 1 / 2 / 3 …"幽灵草稿。
• 切换：点击标签页，或在微信里 /s <短id>，或在 命令面板（Cmd+K） 里搜会话标题。
• 重命名：标签页右键 → 重命名。
• 智能命名：未被手动改过名的会话，收到第一条 AI 回复后会自动让 LLM 起一个简短标题（默认开启，可在 设置 → 上下文 关掉）；手动改过名的会话永久豁免，不再被自动覆盖。重命名对话框里也有「智能命名」按钮，可随时点一下重新建议。
• 归档：标签页右键 → 归档。归档后从主列表消失，可在 会话档案 里恢复。
• 导出 / 分享：标签页右键 → 分享，可保存截图、保存 HTML、复制为 Markdown；「导出会话 (.zsession)」则把整条会话打包成可迁移的归档文件。导出的 HTML 与界面显示一致：跟随极简密度档（灰阶细行 + 同类调用合并计数，失败照常计入）、子代理以卡片呈现、用户消息气泡按来源分色。
• 复制为新会话：以本会话为起点新建分支，原会话不变。

右键即可唤起菜单：会话条目与上方两处标题栏的 ⋯ 菜单都可用鼠标右键直接唤起，不必瞄准 ⋯ 按钮；菜单贴近窗口底部时不再被裁切，右键也不会连带选中条目文字。

5.2.1 用户消息时间戳

自己发出的消息左侧有一个时间戳标签，点击在三种格式间循环：

不同会话各自记忆，互不影响。

5.3 消息组成

一条对话由若干"消息卡片"组成：

• 用户消息
• 助手回复（流式渲染，可中途打断）
• 工具调用（可折叠卡片，包含入参摘要、耗时、结果）
• 计划 / 待办更新（结构化展示，可独立修改）

5.3.1 代码块：语法高亮 + 一键复制

对话里的 fenced 代码块（```）渲染为带 header 的代码卡：

• 语法高亮：基于 highlight.js（lib/common），按语言着色；未知语言走朴素转义，不影响呈现。
• 语言标签：右上角显示该代码块的语言名（如 python / go / tsx）。
• 「复制」按钮：右上角一键把整段代码复制到剪贴板，不用手动框选；成功时按钮短暂变成「✓ 已复制」反馈。
• 行号 grid 保活：跨行 syntax span 内部按源行拆分后逐行配对，行号列与代码列始终对齐，不会因高亮而错位。

5.4 消息流控制

• 助手运行中，输入框右侧的发送键变成 停止 按钮 — 按下会同步终止主助手与所有派生子任务。
• 中途如果你想到补充内容，直接按 Enter 入队 — 这条会在当前自然结束后合并发出，不会打断当前回合。
• 助手输出的工具调用卡片可以单独点开 / 折叠 / 复制结果。
• 输入框按 ↑ / ↓ 可回溯历史输入，执行过的 / 斜杠命令也纳入历史（以规范化的 /<名> <参数> 形式），便于再次取用或改写。

5.4.1 复述意图：开工前先跟你对一遍目标

为避免「一上来就跑偏」，AVL Code 会在会话的第一条消息上做一道轻量确认：AI 先复述一遍它理解的目标、说说打算怎么做（多 Agent 模式下还会给一份「先拆任务 → 并行派子 Agent → 交还你验收」的分阶段计划），等你点头再动手。该功能默认开启，可在 设置 → 智能体 → 自省 关闭（开关：复述意图）。

• 确认就在消息流里完成，不是弹窗，样式和普通消息一致。
• 默认 60 秒后自动开始；鼠标悬停在确认条上会暂停倒计时，给你足够时间看。
• 确认条上有三个选择：
  • 确认开始 — 采纳 AI 的复述直接开干；
  • 修改 — 当场把复述改一改再发，目标和计划都能改；
  • 保留我的本意 — 不采纳 AI 的复述，直接用你最初那条消息继续。
• 点「取消」会把你最初那条消息原样放回输入框，不会丢，便于你补充或重写后再发。
• 只在该问的时候问：仅对你亲手输入的首条消息触发（自动 / 程序触发的不算），且只在这条开场消息比较短（30 字以内）或比较简单时才弹；写得够长够清楚（多行、带编号列表、或顿号 / 逗号等分隔符多于 3 个）就直接开干、不打扰。
• 想对某条消息手动重新对一遍意图：在该消息的操作菜单选「分析意图并从这里重新开始」即可（无视上面的触发条件，强制复述一次并从这里重开）；会先隐藏重启点之后的消息、把确认条放在其下方，便于你看清影响范围。
• 选择统计：确认 / 修改 / 保留本意 / 超时自动开始 / 取消各自的次数与字数会被记录，在 设置 → 智能体 → 自省 以表格呈现，便于你回看这道确认到底帮没帮上忙。

5.5 "正在生成"区块的视觉细节

• Token 数变化加滚动动效：流式过来的 token 计数不再硬跳，约 0.4 秒平滑插值到目标值；变化期间数字短暂变品牌蓝并微微上抬。系统设置「减少动画」时自动跳变不抖。
• 耗时按分级显示：60 秒以内仍是 5s / 12s 这样的简短表达；超过 1 分钟自动升级为 1m 30s；超过 1 小时升级为 2h 15m 30s。短任务零变化，只在长任务时升级单位。
• 上下文占用圆环按占用分档变色：显示当前上下文窗口占用比例的圆环会随占用分档变色 —— 达到 75% 变黄、达到 90% 变红，更醒目地提示已接近上下文上限（该续跑 / 折叠了）。

5.5.0 消息密度（正常 / 极简）

设置 → 通用 → 消息密度 提供两档（落盘字段 message_density，默认 detailed）；Header 快捷菜单「显示」分组的「信息量」滑块可一键切换，无需进设置页：

极简档下，过程内容自动归并计数：

• 连续工具调用结果合并成一行，带计数。
• 多段思考 + 工具调用合并成 「思考 N 次 · 工具 M 个」（数量变化带 pop 动效）。
• 还在执行、暂时没结果的工具调用合并成 「N 次工具调用尝试」。
• 汇总行里如果有失败，用浅红色标出 — 不刺眼但看得见。

切换档位时滚动位置稳定、不抖动；旧的「收敛」档（collapsed）自动迁移到「极简」。

5.6 滚动与跟随

• 生成期间默认自动跟随底部。
• 一旦你向上滚动查看历史，「跳转底部」按钮出现 = 视为你主动滚走，自动跟随停止。
• 生成中拖滚动条回看不再被钉住：AI 正在流式输出时，想往上拖动滚动条回看前文，过去常被自动跟随同帧拽回底部、像「拖不动」；现在主动上拖会同步松开自动跟随，让你正常上滚查看，需要时再回到底部继续跟最新输出。
• 你点「跳转底部」或自己手动回到底部时，跟随自然恢复。
• 已堵住滚轮事件与流式 chunk 同帧的微秒级竞态，不会再被反复打断。
• 整列表高频抖动修复：之前某些情况下消息列表会上下快速抖动 / 跳动 — 根因是个别消息的高度被反复重测。现在把已渲染过的高度缓存下来（包括高度为 0 的情况），列表不再来回弹跳，滚动更稳。
• 「跳转底部」一次到位：之前要点好几次才能真正到底；现在改为持续校准直到内容高度（scrollHeight）稳定，一次就能稳稳停在底部，长会话首次打开也不会出现「按钮按了像没反应」的多点情况。
• 快速重复点「发送」不再重发：加了同步的在途拦截，连点也只发一条。

5.6.2 长会话分页按需加载

打开很长的会话时先显示最近一段，往上滚动再分段加载更早的消息：

• 滚到顶端继续上滚 → 自动加载上一页，多页加载时居中显示进度提示。
• 底层做了行偏移索引（O(range) 不再 O(scan-from-line-1)）+ 多页之间按帧让步 + 去重，长会话的首次打开与上下滚动明显更快、更跟手。
• 会话目录的跳转对尚未加载进窗口的更早消息也能正确定位（自动先加载到该位置再滚过去）。
• 超大消息默认不再"显示折叠"：之前为了性能会把过长的单条消息折叠成摘要，现在默认完整展开，要折叠请到设置调整。

5.6.0 会话目录与一键跳转

会话标题左侧新增会话导航按钮（List 图标），鼠标点击展开一个目录 popover：

• 列出本会话每条用户提问 — 每条取「首个非空行」作为标题，自动折叠多余空白，超长截到 120 字符（带 …）。
• 点击某条 → 平滑滚动到该消息并关闭 popover。
• 高亮当前所在条（纯灰阶，朴素专业风）— 按当前视口内可见的用户消息实时判定，滚动时跟随刷新，末条也能正确选中，不再总停在第一条。
• 关闭方式：Esc / 点 popover 外 / 窗口 resize。
• 虚拟化安全：按 data-message-id 定位（占位消息也带该属性且占正确高度），长会话也定位准确。
• 仅在会话里有用户提问可跳转时才显示，空会话不出现。
• 用浏览器 Popover API（popover=manual + top layer）渲染，不依赖 z-index，不会被弹窗 / 抽屉等遮挡。

5.5.1 会话状态条：随窗口宽度换形态

文件变更 / 记忆 / 待办 / 计划 / 目标 / 引导 / 结果草稿 / 附加资料 / 建议任务 / 自检门禁 等状态条会按窗口宽度自动选择呈现形态：

• 窄屏 — 输入框上方横排：多条并列在输入框上方，宽度不够时自动换行（优先填满紧贴输入框的那行、再往上叠），各条间距收拢，非底行的标签还原成完整药丸，不再被挤出屏幕或相互遮挡。点开为向上弹出的浮层。
• 宽屏 — 消息区右上的纵向状态栈：窗口够宽时，这些条目改为在消息区右上纵向排列，不再占用输入框上方的空间。点开为右侧堆叠抽屉：不加遮罩、不挤压正文，以整个状态栈为锚，切换不同条目时抽屉位置保持稳定，并会按两侧可用空间自动选择向左或向右展开。窗口特别宽时抽屉槽位固定预留，开合抽屉不会让正文左右跳动。

信息量设为「极简」时恒用输入框上方的横排形态。切换形态只改变位置，不改变正文宽度。

5.6.1 会话附加目录：让 AI 临时访问工作区之外的文件夹

输入框「+」菜单新增两项：

典型用法：让 AI 参考另一个项目的代码、把产出写到指定目录、跨工程协作等。

附加前有确认对话框，明确说明授予的是只读还是读写权限；附加后出现 「附加路径」条（窄屏在输入框上方、宽屏在消息区右上，见 §5.5.1），展示当前会话的附加目录，可随时移除。

作用域与安全：

• 附加只对当前会话生效，其它会话不受影响。
• 随会话保存，重启后依然有效（后台自动重新生效，无需重新附加）。
• 放宽的只有文件读写口径（读 / 写 / 搜索 / 列举），其余安全策略不变。
• 附加目录下的搜索结果用绝对路径标注，来源一目了然。
• 会话身份由系统在调用链里注入，AI 自己无法伪造身份去冒用别的会话的附加权限。

统一的「附加资料」入口：会话附加的目录 / 文件与工作区的样本 / 附件已合并到同一个「附加资料」条统一管理，附加进度等状态实时可感知。两类语义清晰、各自处置：会话附加的项移除只是解挂、不删原文件；工作区样本 / 附件的删除走行内二次确认，不易误删。文件有变更会自动刷新（AI 改完文件后无需手动重载），目录按多层树状呈现看得更清楚，并自动忽略 macOS 的特殊文件（如 .DS_Store、__MACOSX/ 等）。本地工作区文件加入附加资料时状态显示为「已就绪」（不再用「上传 / 已上传」误导本地文件）——「上传」只留给真正外发的场景（如提交反馈、上传检测）；范围（scope）徽标也改为可读性更好的靛蓝配色。

5.7 消息内链接与文件路径可点

AI 回复里的链接和文件路径现在都能点：

• 工作区内的文件路径 → 点开后用系统文件管理器（Finder / 资源管理器）定位并选中该文件。
• 外部链接 → 用默认浏览器打开。
• 反引号内联代码里的路径（如 `src/main.go`）同样可点，与普通链接共用一套识别与定位逻辑；普通内联代码不受影响。
• 代码引用可点跳转（接地证据可核对）：AI 回答里引用的代码位置、以及工具结果里的「文件:行」现在都能点 — 带行号的工作区文件，点「查看」会打开源码预览并滚动到该行，不必自己去翻。这让 code.search / code.ask 等给出的 文件:行 证据「看得见、可核对」。
• 点击后就地弹出轻量浮动小工具条（主动作「查看 / 打开」+「复制」），非模态 — 点别处 / 滚动 / 按 Esc 即关。
• 工具条用浏览器 Popover API 渲染在顶层，从「关于」「发布说明」「更新」等弹窗里点链接也不会被遮挡。
• 路径识别更精准：只把带常见扩展名的字符串（如 src/main.go、README.md）认作可点路径；纯目录、无扩展名 / 未知扩展名的片段（如 a/b、/etc/hosts）不再被误标为可点。
• 仅 AI 回复生效：你自己发的消息里链接 / 路径不再可点，避免误触；只有助手回复里的链接和路径才会被识别与提供工具条。
• 安全：危险协议（非 http(s)）链接被拦截不放行；文件定位有工作区纵深校验，不会越界到工作区外。

5.7.1 文件预览抽屉

消息流里点文件链接，弹出的工具条在「查看 / 打开」「复制」旁多了 「预览」 按钮，就地看内容不必切到编辑器。

• 支持的文件类型远不止 Markdown：常见源码（Go / TypeScript / Python / Rust / Java / C·C++ / Ruby / PHP / Swift / Kotlin 等）、配置（YAML / TOML / JSON / INI / .env）、前端（HTML / CSS / Svelte / Vue / Astro）、脚本（sh / bash / ps1 / bat）、文本与数据（md / txt / csv / tsv / xml / sql / diff）、图片与常见二进制（png / jpg / svg / pdf / zip 等），以及 Dockerfile、Makefile、go.mod、.gitignore 这类没有扩展名的常见文件名。
• 源码带语法高亮，与消息流里的代码块同一套配色；正文特别大时（超过约 256 KB）不再着色，但行号与定位照常可用。文件路径前会按格式显示对应图标，一眼分辨类型。
• 二进制文件以十六进制转储呈现（十六进制 + 字符对照，最多 64 KiB），不再显示成乱码。远程工作区的二进制文件取不到原始字节，此时会明确说明而不是给出假内容。
• 可预览的范围：先在工作区内查找，找不到再匹配当前会话附加的目录 / 文件 —— 附加进来的文件同样能预览。不能预览的路径不会显示「预览」按钮，避免点了没反应。
• 呈现形态按窗口宽度自动选择：外侧空间足够时常驻为右侧侧栏（不收窄正文）；空间不足时退回浮层抽屉（宽 min(820px, 94vw)、不加遮罩），此时正文靠左侧留白避让，同样不被收窄。
• 在文件内查找：抽屉里可直接搜当前文件内容，命中处高亮，显示「第几处 / 共几处」，用「上一处 / 下一处」逐个跳转，可切换是否区分大小写。命中过多时只标出前若干处并给出提示。
• 大小：预览正文上限 1 MiB（超出自动截断并标注），适合速览；要保全文请用「另存为」。
• 「另存为」按钮（抽屉头部）：调系统保存对话框，用 64 MiB 大上限读取源文件保全文，写到你指定的位置；取消等于无操作。
• 代码块里单独一条文件路径（文件存在时）也能点开预览：渲染时异步校验该路径是否存在，存在才升级为可点，避免点到不存在的文件。

按 ↑ 在输入历史里回溯时，输入框左上角显示当前位置 N/N（最新 = 总数，最旧 = 1/N），不再"按了几次 ↑ 自己也不知道翻到哪了"。草稿态 / 空历史 / 越界一律不显示。

回溯到某条历史后直接键入或粘贴 → 自动离开历史态，改后内容当作最新草稿：之前在历史态修改会让人误以为"这条历史被改了"，本版明确语义 — 编辑即新草稿，原历史不动；再按 ↑ 仍先把当前草稿存起来，编辑内容不丢。

5.9 跨端接管

如果你已经绑定了微信通道：

• 手机上 /s <短id> 即可继续未完成的桌面会话。
• 桌面端会话也可以接管手机端发起的会话。
• 同一会话同时只允许一端"持有"，另一端会自动同步显示。

详见第 18 章「随行通讯」。

6. 五种工作模式

AVL Code 的助手体系核心是「工作模式」。每个工作区可以为五种模式分别绑定不同的助手人设。

6.1 模式总览

plan（筹划）是真正的只读模式：写文件、编辑、执行命令类工具一律禁用，连查看后台命令输出也不行 — 目的是让"想清楚"这个阶段保持纯净。这道限制作用在工具层，助手配置只能更严、不能放宽。

assess（评估）不写业务代码，但可以执行命令：为了真正完成验收，它可以跑测试、lint、SAST、生成 SBOM、做安全分析与情报查询，禁用的是写文件与编辑。如果你要的是"绝对不碰任何东西"，请用 plan。

6.2 切换模式

输入框下方的工作模式选择条提供五个圆形按钮，单击即切换。切换会自动：

1. 加载该模式绑定的助手人设。
2. 切换到该模式对应的工具开关集合。
3. 在会话流中插入一条"模式切换"分隔标记，便于回看。

6.3 模式之间的关系

五种模式不是孤立的；它们构成一个推荐工作流：

plan → prepare → execute → assess

auto 作为兜底模式，适合不需要严格阶段化的小任务。AVL Code 鼓励你先 plan、再 execute，因为筹划阶段的"只读"约束能防止 AI 急着改代码而搞错前提。

6.4 退出筹划

筹划模式完成后，点击对话区顶部的「退出筹划，进入执行」横幅，AVL Code 会自动切换到 execute 并把已确认的计划注入新一回合。

6.5 自定义模式行为

每种模式可独立配置：

• 默认助手
• 工具开关（哪些工具启用 / 询问 / 禁用）
• 模型与参数
• 自动接受 / 拒绝阈值（高阶）

在 设置 → Agents 中按工作区粒度调整。

7. 助手人设

助手人设（Persona）决定 AI 的"风格"与"边界"。

7.1 人设组成

每个助手包含：

• 名称：在面板与对话中显示的名字。
• 个性：一句话个性描述（如「严谨克制、注重可读性」）。
• 核心提示词：完整的系统提示词，决定助手的语言风格、专业领域与边界。

7.2 编辑助手

打开 设置 → Agents：

• 列表展示所有现有助手；
• 双击或点击「编辑」打开人设编辑器；
• 提示词推荐写成独立 Markdown 文件，便于版本管理与团队共享。

7.3 内置助手

AVL Code 内置 5 个对应五种模式的默认助手：自动、筹划、准备、执行、评估。它们之间的差异主要在于"对工具的态度"与"对答复深度的偏好"，可作为自定义的起点。

7.4 「有如神助」

输入框旁的小魔杖按钮可一次性指派一位助手（与当前模式无关），适合临时换个角度审视问题。下一条消息发送后会自动恢复模式默认助手。

7.5 团队共享人设

把人设的核心提示词存为 Markdown 文件后，可以放进团队仓库统一维护。新成员加入时，只需把文件放在工作区下指定目录即可自动识别。

8. 模型与参数

8.1 模型选择

设置 → 模型 列出所有可用模型：

• 共享额度下可见的模型（由组织决定）
• 你自己接入的模型（OpenAI / Anthropic / 阿里云通义 / 火山方舟 / 自建大模型服务等）

每个工作区可以指定默认模型；每次对话也可以临时切换。

8.1.1 Provider 协议

设置 → 提供商 编辑面板「类型」下拉支持三种协议：

「从 API 刷新模型」按钮会按所选协议自动派发，正常拉取对应模型列表。

Delta 端点自动安全降级：如果服务端暂未提供 Delta 接口（返回 404/405/501），本次会话会自动一次性回退到标准的 chat/completions 协议，对话不中断；真正的鉴权类错误（401/403）则照常报错，不会被降级掩盖。

统计面板会显示每次调用走的是哪种协议（OpenAI Chat / Anthropic Messages / AVL Delta）以及当时的客户端版本号；发生 Delta 自动降级时，元信息里也能看出来。所有发往模型服务的请求都带上了客户端版本、协议标识与一个类浏览器 User-Agent，便于网关侧日志与统计对账。

8.1.2 自定义请求头（仅限自己添加的供应商）

设置 → 提供商 编辑面板底部的「高级选项」可展开，对于你自己添加的（非内置）供应商，新增了「自定义请求头」编辑区：可增删多组 key / value，随每次发往该供应商的请求逐条带上，方便对接需要额外鉴权头、网关标识或特殊版本头的服务。

• 生效范围：OpenAI、Anthropic、AVL Delta（流式 + 非流式）四类请求路径全部生效。
• 顺序与覆盖：自定义头在内置头（鉴权 / User-Agent / anthropic-version 等）之后应用，可覆盖 Authorization / User-Agent 等默认头；如果你不希望覆盖，请避开同名 key。
• 防注入：自动跳过空 key，并拒绝 key / value 中含换行（CR/LF）的条目，防止请求头注入。
• 已知限制：自定义 Host 头不生效（Go HTTP 栈要求改 req.Host 而非头本身），如需改 Host 请通过反向代理实现。

内置供应商（AVL-Zero 等共享额度）不暴露此入口，仅自定义供应商可编辑。

8.2 参数

每个模型可调参数：

• Temperature：温度，0–1，控制随机性。
• Top-P：核采样上限，0–1。
• 最大输出 Token：单次回复长度上限；无硬性上限，可超出模型标称值，以上游实际限制为准。
• 流式：是否流式渲染（推荐开启）。

参数同样按工作区与模式分别保存。

8.2.1 模型作用域：全局一致 / 跟随会话

设置 → 模型 Tab 顶部提供分段开关，选择当前模型的作用范围：

「跟随会话」模式下若会话记的模型已失效（被删 / 下线），自动回落到全局选择，不会卡住。

复制会话 / .zsession 导入导出都自动带上模型字段，跨设备 / 跨人交接不丢。导出 .zsession 时一并打包子 Agent 工作记录 — 主对话里派出去的每个子任务当时怎么做的、调了什么也都会还原出来，跨机或发同事打开后排查 / 复盘更完整。

导入 / 重建更稳：修了「把会话导入到新建工作区后不显示、空白工作区却误报『已存在』」的问题（根因是写入目标错位 + 沿用原会话 ID 造成同 ID 跨工作区冲突），现在导入 / 重建都能正常完成。

8.2.2 未开启模型默认折叠

设置 → 模型 每个供应商分组默认只显示已开启的模型，不再被一长串没开的型号淹没；组底部有「展开 N 个未开启的模型」按钮，点开看全部、可再收起。

• 展开状态按供应商各自记忆（仅本次打开期间）。
• 搜索时自动绕过折叠：搜索命中的未开启模型照常显示，不会被藏住。
• 开关切换过程中行不闪跳。

8.2.3 模型 ID 中的斜杠原样保留

像 openrouter/free、openai/gpt-4o、anthropic/claude-3.5-sonnet 这类 OpenRouter / Cloudflare 等使用的 vendor/model 命名方式，斜杠是上游官方分隔符。AVL Code 现在原样保留 — 手动添加与刷新两条路径都不会把斜杠改成连字符。

此前若你添加这类模型遇到「模型不存在」的报错，刷新一次模型列表即可恢复（旧的坏条目会被换成正确的 ID）。

8.3 多供应商兜底

如果你接入了多个供应商，AVL Code 支持设置优先级与兜底：第一供应商失败 / 限流时自动切到第二供应商，避免单点。

8.4 上下文长度与折叠

不同模型上下文长度不同。AVL Code 会在接近上限时自动触发历史折叠（见第 17 章），把早期消息压缩为摘要，确保对话可以无限延续。

8.5 自修复循环：出错自动换思路

AI 遇到错误时会按错误类型自动换策略接着自愈，而不是一条道走到黑。这套机制始终开启、无需配置；自愈过程往对话里注入的结果型内部消息（auto_self_heal）不会显示在对话中，你看到的仍是干净的正常输出。上游报错会先分流来源（请求侧 / 网关 / 上游供应商）与类别（认证 / 限流 / 配额 / 余额 / 无可用通道 / 过载 / 服务端错 / 上下文超限 / 内容被安全过滤等），再对症选择修复策略：

即使服务端 5xx / 4xx 没有错误详情，也能凭状态码兜底走对应的自愈路径。除了上游报错，AI 自身产出的问题也会自愈：

• 回复被长度截断会自动从截断处续写（不重头来），默认最多 3 次。
• 思考绕圈（反复重复同一段推理）会被打断，提示直接给结论或采取下一步动作。
• 回复被内容安全过滤会换个表述自愈。
• 工具名不合规被上游拒绝时，会自动修正工具名后重试（几种上游措辞——包括散文式报错——都能识别）。
• 同一处检查 / 测试反复失败或待办长时间无进展时，会升级提示让 AI 换思路（如考虑回退本次改动重来），而不是反复撞墙；到达上限后停下交还给你。

网络抖动专门优化：网络瞬断 / 临时掉线时会自动等网络恢复再接着重试，而且这种「等网络回来」的等待不消耗重试次数——出门进电梯、Wi-Fi 抖一下这类情况不会平白把重试预算烧光。连接被重置、域名一时解析不了、握手中断等连接级瞬断也能被正确识别为网络问题，不再被笼统报成「模型出错」，省得你白去查上游配置。

自愈也会从历史里学习（见 §8.5.1）：每类自愈的成败会被记录，下次据此动态调整允许尝试的次数——历史上几乎没救回来的，少试两次就尽早交还给你；还能救的也不轻易放弃。

8.5.1 自愈次数随历史动态调整

自修复会参考过去的自愈成败记录（落盘在配置目录的 self-heal-stats.json），对每一类自愈动态调整本次允许的尝试次数：样本不足（< 5 次）时用默认上限；历史平滑成功率 < 20% 压到 1 次、20–50% 减 1 次、≥ 50% 用满默认。每类至少保留 1 次尝试，历史只会调低、不会调高于默认上限。

8.6 供应商自动备选（需确认）

当某个模型供应商持续不可用（无可用通道 / 上游过载 / 上游侧认证失败）时，AVL Code 不会静默切换、也不会卡住，而是挂起本轮并在输入框上方弹出一条切换确认条：

• 只会切到同一个模型的另一个已启用供应商（按配置顺序选第一个真正包含该模型的，绝不降级到别的模型）。
• 确认条文案形如「切换备用模型? 首选 {A} 暂时不可用,可改用 {B}(模型 {M})重试本轮」，并提示「⚠ 备用通道可能走你自己的 key（产生你的费用），或把内容发往不同上游」。
• 点「切换并重试」即用新供应商无缝接着跑；点「不用」则放弃本次切换。

9. 工具体系总览

工具（Tool）是 AI 在你电脑上"动手"的载体。

9.1 三类工具

• 智能编程工具：读写文件、跑命令、版本控制、查找等（详见第 10 章）。
• 安全分析工具：哈希、字符串、IOC、可执行格式解析、反汇编、规则匹配、流量元数据等（详见第 11 章）。
• 外部工具服务：连接外部系统的工具，如 Notion、内部 API、私有知识库等（详见第 12 章）。

9.2 工具开关

每个工具都可以设置为：

• 启用：直接放行。
• 询问：每次调用前弹窗审批。
• 禁用：直接拒绝。

入口在输入区模式滑块旁的齿轮（智能体管理器）→「配置工具」Tab，可按工作模式独立配置。三态真实约束运行：「禁用」在主代理与子代理两侧一并生效；「询问」接入实际确认流程，调用前暂停等你批准；卸载插件或外部工具服务时会一并清理残留的工具配置，盘上配置与实际可用工具保持一致。

工具列表更稳：工具列表拉取失败时自动退避重试，多次重试仍失败才提示；兜底工具表与内置工具同源生成，不会莫名少一截。

9.2.1 工具分类延迟加载（默认开启）

工具总数已过百，若每轮都把全部工具描述发给模型，既占上下文又拖慢响应。因此默认只携带常用的一小部分（二十余个），其余按分类在需要时才加载。

• 常驻分类：文件读写与搜索、命令执行、工具自省、子任务委派与待办规划 —— 这些几乎每轮都要用。
• 按需加载的分类（16 类）：代码理解、git、安全分析、威胁情报、SBOM、外部工具服务、联网检索、技能、测试、lint、SAST、插件市场、插件管理、GitHub、系统信息、时间。
• 两种加载方式：你的提问里出现相关词汇时自动预加载对应分类；助手也可以主动调用 tools.load 点名加载。中途新连上的外部工具服务会自动放行。
• 助手知道工具表是不全的：系统提示词里会说明这一点并给出分类目录，助手不会因为"表里没有"就认定某项能力不存在；查询自身可用工具时，返回结果也会提示"看不见 ≠ 不存在，可以先加载"。

开关：智能体管理器 →「配置工具」Tab →「工具分类延迟加载」。关掉后所有工具恒常驻。当可用工具本就不多（不超过 32 个）时，系统会直接整表放行，不做延迟加载。

若某个外部工具服务你用得很频繁，可以在同一面板里单独为它关闭延迟加载，让它的工具始终可用 — 见 §12.4。

9.3 工具命名空间

外部工具服务暴露的工具会被自动加上前缀（例如 notion.*），与内置工具区分，互不冲突。

9.4 工具调用的可视化

每一次工具调用都会以可折叠卡片形式显示在消息流中，包含：

• 工具名 + 入参摘要
• 执行耗时
• 结果（成功 / 失败 / 截断）

你可以独立查看每个工具调用的细节，便于审计与回溯。

9.4.1 Hook 执行过程可见

每次钩子（hook）执行都会在对话流里出现一条系统消息，渲染成类似工具调用的可折叠条（内容按 Markdown 显示），方便确认钩子到底跑没跑、跑了什么、是否影响了下一步动作 — 不再是黑盒。

9.4.1.1 工具执行空闲超时（默认 10 分钟）

给工具执行加了「空闲超时」兜底：某个工具或子任务长时间没有任何进展（没有 stream 输出 / 状态变化）时会被安全收尾，不再让整轮一直挂着干等。

• 触发条件：连续空闲 ≥ 默认 10 分钟。正常的长任务只要还在持续产出就不受影响。
• 豁免：子 Agent 家族单独走 §15.2.1 的空闲窗口 + 绝对兜底，不被这道 10 分钟空闲超时误杀。

9.4.1.2 重复调用提醒（疑似空转）

助手偶尔会陷入"用同样的参数把同一个工具反复调用"的循环 —— 它一直在动，所以空闲超时抓不到，但其实毫无进展，额度却在持续消耗。

• 连续 3 次同参调用同一工具即在工具结果里提示助手，请它换个思路；次数继续增加会逐级加重措辞。
• 会话列表上标记「疑似空转」，悬停可见已重复的次数与工具名；侧边栏与顶部标签页两种布局都会标记。同时发出通知，即使你切到别的会话也能第一时间发现。
• 重启应用后标记依然保留，不会因为重启而漏掉；等你在该会话发出新的一条消息后自动清除。
• 轮询类工具（等待子任务、拉取命令输出等）本就需要反复调用，不在此列。

9.4.2 轨迹面板（Trace）

会话顶部的统计气泡（StatsPopover）里和原「Stats」面板并列新增了 「轨迹」（Trace）面板：把 AI 一次运行里调用了哪些工具、按什么顺序、各自的输入输出与耗时摊开成时间线，方便回看它到底怎么一步步把活做完的，也方便排查「哪步走偏 / 烧在哪」。

每个步骤显示：

• 序号 / 角色 / 类型 / 来源 / 工具名
• 耗时、prompt / completion / total token 数、模型、finish reason
• 是否成功 / 错误信息 / 内容预览

顶部聚合卡显示这一次运行的：总步数、assistant 轮数、工具调用次数 / 失败数、错误数、门禁注入次数、token 用量、工具总耗时、墙钟时长、用到的模型清单；下面还有工具维度的统计表（每个工具的调用数 / 失败数 / P50 / P95 / 最长耗时）。

数据来自会话 JSONL 的服务端聚合（GetSessionTrace），按需打开 popover 时加载一次，不做实时轮询。

时间线步骤可点击跳转：点轨迹时间线上的某一步，会直接跳到消息流中对应的位置并定位过去，回看「哪步走偏 / 烧在哪」更方便。

9.5 让助手自己配置 MCP 服务

除了在设置面板里手动添加外部服务，助手还可以在对话里直接帮你配置 MCP server。AVL Code 提供 9 个 mcp.* 工具，常配合内置 mcp-admin 助手使用：

两步制（dry-run）：写类工具（add / remove / toggle / import）必须显式传 confirm=true 才会真正落配置；首次调用默认返回 dry-run 预览（完整命令行、路由、默认后端变更、冲突清单）让你审完再确认。这是没有 PreToolUse defer hook 时的兜底闸门 — LLM 单步不可直接做破坏。

密钥脱敏：所有读类工具返回的 authToken 一律只显示尾 4 位（其余字符以星号占位），环境变量值整体打码，避免在对话流里泄露凭证。

典型对话：

「帮我把 mcp-trends-hub@1.6.0 接进来。」

助手 → 调 mcp.add_server（dry-run）→ 返回预览 → 你确认 → 助手再调 mcp.add_server(confirm=true) → 落配置 → 用 mcp.test_server 真握手探活 → 报告 21 个 trending 工具可用。

10. 智能编程工具

下列工具默认在工作区目录范围内可用，互相协同支撑助手在你的代码仓库里"干活"。

10.1 读文件

支持按行或按字节读取，自动处理大文件分段。读取时会附带内容指纹，确保后续编辑基于"刚刚读过"的版本，防止并发覆写。

10.2 写文件 / 编辑

• 覆盖写：完整重写整个文件，会校验"读过"前提。
• 片段编辑：基于内容指纹做精确替换，AI 必须先读、再改，杜绝幻觉式覆盖。

10.3 目录列表 / 文件查找

• 列目录支持过滤、按时间排序。
• 支持通配符匹配文件名，自动跳过 .git / node_modules 等无关目录。

10.4 内容搜索

• 支持正则表达式、文件名通配过滤。
• 自动跳过二进制文件，启发式判断编码。

10.5 终端执行

• 同步执行：单次命令运行后等待完成，输出回到对话流。
• 后台执行：长任务（构建、压测）转后台，期间可拉取实时输出、随时停止。

每一次终端调用默认都受工具权限管控：可放行、可询问、可禁用。

10.6 版本控制

提供基础 Git 操作：仓库状态查询、新建 / 切换分支、新建仓库，以及暂存 / 提交 / 合并 / 变基等分支写操作；推送仍由助手通过终端执行类工具完成。这些操作默认与其他工具一致为「启用」（不额外弹询问）；对合并、推送等高风险操作，可在智能体管理器 →「配置工具」里按工作模式把对应工具设为「询问」或「禁用」（见 §13.1）。

10.7 网络检索（可选）

• web.bing：Bing RSS 端点搜索，返回标题 / 摘要 / URL。
• web.fetch：抓取指定 URL 并自动清洗为 Markdown / 文本 / HTML。

检索来源与内容均会作为引用卡片展示在消息流。

10.8 时间与上下文

• time.now：获取当前时间（含时区），方便助手为日志、TODO、文件名打标。
• TodoWrite：写入 / 更新待办列表，单次最多 50 条；详见第 16 章。

10.9 上下文截断

任何读取或检索类工具的单次返回都有"软上限 + 硬上限"，超出会自动截断并标注，方便助手分批续读，避免一次性灌爆模型上下文。

工具结果瘦身，更省额度：工作区工具的返回结果做了精简 —— 文件路径改为相对工作区根显示、错误信息剥除冗长的根路径前缀、去除重复的行哈希、分页记账仅在结果被截断时才输出。整体减少无谓的 token 占用，长任务更省额度（也不再把绝对根路径泄露到结果里）。

10.10 代码智能工具组（code.*，基于语言服务器）

新增一组让 AI 像 IDE 一样理解代码的工具：基于业界标准的 LSP（Language Server Protocol），把语言服务器的"找定义 / 找引用 / 重命名 / 编译诊断"等能力直接交给 AI 使用 — 做事更准、更省来回、不再靠正则猜。

位置参数对外 1-based（与读文件一致 / 同 cat -n），不必心算偏移。

按语言服务器实际支持情况自动降级：并非每门语言的服务器都实现了全部能力。是否支持以实际调用结果为准，而不是听服务器自报，避免它其实能做却被误判拒绝；判定出"不支持"后会记住，同一台服务器在后续会话里不再重复试探。

10.10.1 内置 22 门语言 + 按需自动下载

内置覆盖主流语言：Go、TypeScript / JavaScript、Python、C / C++、Rust、Java、Lua、Bash、YAML、PHP、Ruby、Vue、Zig、Dart、Kotlin、Clojure、Elixir、Haskell、F# / C#、Gleam、Astro 等 22 门。

• 缺哪门语言的服务器会按需自动下载（安全托管、带紧急开关），下载进度有 toast 提示。
• 设置 → 代码智能 / LSP 面板能看到正在运行的服务器与安装状态。

10.10.2 用 lsp.json / lsp.yaml 覆盖默认

工作区根目录或 ~/.avlcode/ 放一个 lsp.yaml（推荐，兼容旧 lsp.json）就能覆盖默认设置 — 改启动命令、改 root marker、禁用某门语言、增加自定义 server 都行。改完热重载、不用重启工作区；服务器进程崩了 / SSH 掉线自动重启。

10.10.3 远程工作区同样可用

LSP 在 SSH 远端启动：远端缺什么语言的服务器按需自动下载到远端，跨系统的路径与读写都已正确处理，远程工作区的代码智能与本地等同。

10.10.4 Python 虚拟环境（venv）自动遵循

AI 在工作区里跑 Python 相关命令时自动探测并使用工作区的虚拟环境，不必每次手动 activate：

• 覆盖：venv / .venv、conda（含 Windows 上 Scripts/python.exe 布局）、poetry（含项目目录之外的环境）、pipenv。
• 机制：把首命令改写成 venv 里的绝对路径，并注入 VIRTUAL_ENV / PATH，保持工具链一致；探测不到 venv 时零行为变化（命令原样执行）。
• 缓存：项目外的发现（poetry / pipenv）有 5 分钟缓存 + 15 秒探测超时，避免每轮都 fork。
• 逃生口：环境变量 AVLCODE_DISABLE_VENV_AUTODETECT 非空即全局关闭自动感知。
• pyright 语言服务也接入 venv 感知，本地和 SSH 远端都生效，代码智能里的类型推导走的就是你真实的 venv。

10.10.5 全库代码检索与问答（code.search / code.ask）

在「找定义 / 找引用」这种精确点查之外，新增两个全库语义检索工具，回答「登录逻辑在哪、怎么走的」这类问题：

特点：

• 纯本地、零向量 / 零 embedding，可离线（air-gap）：用 BM25 + 标识符切分（驼峰 / 下划线 / 连字符自动拆词）+ 中日韩二元切分（中文注释、中文提问同样能命中），不依赖任何模型或联网。
• 命中可解释：每条结果都给出 文件:行 和命中的关键词，看得清为什么是这条。
• 索引自动跟上：首次调用自动建索引；之后按文件 mtime 增量刷新（改 / 增 / 删自动更新）。本地索引落在工作区 .avlcode/rag/。建索引与启动语言服务的进度以单条原地更新的进度条显示（不再刷一屏 toast）。
• 超大仓库如实告知：索引最多覆盖 4000 个文件。超过时会明确告诉你有多少文件没被索引，而不是悄悄少搜一部分 —— 「没搜到」到底是真不存在，还是没覆盖到，一看便知。
• 结构感知重排：结合中心度与调用关系把「被调用更多 = 更核心」的符号排前（code.search 传 expand=true 显式启用；code.ask 现在默认就做这道智能重排，回答代码问题更聚焦相关内容）。增量刷新的作用域也已修正，文件变更后更准，不多刷、不漏刷。
• 远程也可用：SSH 远程工作区同样支持（远端枚举 / 读取，索引在内存）；code.ask 复用当前会话的模型。

这两个工具与上表的 code.*（LSP 精确查询）互补：精确定位用 code.definition / code.references，「这事在哪、怎么实现的」用 code.search / code.ask。

10.11 测试运行工具 test.run

AI 现在能自己跑测试、读懂失败、再回去修，形成「跑测试 → 看失败 → 改代码 → 再跑验证」的闭环。

• 自动识别测试框架：按项目文件判断 — go.mod → Go / pyproject.toml·pytest.ini → pytest / Cargo.toml → cargo / package.json → Node（vitest、jest）；也可手动指定 framework 或 command 完全覆盖。
• 结构化失败：跑完把输出解析成 failures[]（每条含 test 名 / 文件 / 第几行 / 错误信息），最多回灌 50 条 + 一小段原始 tail，不把整篇测试日志灌进对话 — 省 token。
• 未知框架兜底：解析失败时退回到退出码 + 末尾输出，保证至少能告诉你失败了什么。
• 范围限定：可传 path 限定（Go 包模式如 ./pkg/...、pytest 目录或文件、cargo 包名）。
• 远程也能用：本地 + SSH 远端工作区一视同仁。
• plan（筹划）模式禁用：跑测试 = 执行项目代码，会产生写副作用，与"只想不做"的定位冲突。assess（评估）模式可用 — 验收阶段本就需要实际跑一遍。

10.11.1 自检门禁（opt-in，四类检查器）

「自检门禁」是测试门禁的泛化：开启后 AI 每轮干完活后自动跑一组检查；如果有失败，把结构化失败信息回灌给它并强制接着修，直到全绿 — 不用你手动催「再跑下测试」。

六类检查器（可单选 / 组合）：

每个检查器都可调：

• mode：block（默认，注入失败强制修） / report（只通报不拦）
• submode：
  • test：changed（默认，只测改动的）/ full（全跑）
  • lint：strict（警告也算红）/ lenient
  • sast：quick（限大文件加速）/ deep（完整）
• scope：changed（默认，本轮改动文件）/ workspace（全库）
• path / linters / config：精细化覆盖

testgen / judge 不在默认集：要显式把 testgen / judge 加进 checks 才生效；前者只判 Go / Python / JS / TS 这些有明确测试约定的语言，跳过测试文件本身与生成物（如 .pb.go），共用门禁的 3 次注入硬上限。

judge 永不误拦：模型乱报 / JSON 脏 / 超时一律视为「非权威」放行；门禁里 judge 安排在所有便宜检查器之后、且仅当 block 检查器全绿时才跑（省一次模型调用，也不在客观失败上堆主观意见）。few-shot 示例 + 当轮诊断背景注入到 judge prompt，判断更准。

省开销：仅在本轮真正改过文件后才跑；没有编辑的轮次整组跳过。 结构化展示：失败在前端用结构化面板展示，不是一坨裸 JSON。 不会死循环：同会话连续注入硬上限（默认 3 次）— 撞到即停门禁、交回常规流程，避免 flaky / 不可修复的检查把 AI 困死；真正的用户介入立即清零。

10.11.2 「继承 + 覆盖」三级开关

会话菜单和工作区菜单显示的都是实际生效状态，所见即所得。

10.11.3 CheckGateStrip — 输入框上方的全参数编辑器

工作区开启自检门禁后，输入框上方会出现一条 CheckGateStrip：

• 一行 chip 显示每个检查器的当前生效态（mode / submode / scope）。
• 点 chip 展开全参数编辑器，可改 mode / submode / scope / path / linters / config / timeout，所改即时写入工作区配置。
• 关掉门禁后 Strip 隐藏，不挡视线。

10.11.4 工具安装状态

设置 → 代码测试与自检 页底部展示外部工具的安装状态（主进程 PATH 可见性）：

macOS GUI 进程的 PATH 可能不含 shell（.zshrc）里 pip / npm 装的路径，这里是主进程可见性的尽力探测；真正运行仍由工作区 interpreter 在工作区上下文跑，可能成功 — 不必拘泥于此处的 ✗。

10.11.5 lint.run 与 sast.run — 也可单独被 AI 调用

lint.run 与 sast.run 不只是自检门禁的后端，AI 也能在 plan / assess 等只读模式下直接调用做静态审计 — 它们是只读分析（不改源、不执行项目代码），不在 read-only 拒绝列表里。

lint.run：

• 自动识别 linter：go.mod → golangci-lint / .eslintrc·eslint.config → eslint / pyproject.toml·ruff.toml → ruff；也可 linter / command 手动覆盖。
• 结构化发现：findings[]（每条 {file, line, rule, severity, message}），与 test.run 同形。
• submode：strict（如 eslint 警告也算失败）/ lenient。

sast.run：

• 后端：semgrep（--config auto 默认，需联网拉规则；离线请用 config 指定本地 .semgrep.yml）。
• 结构化发现：findings[] 同形。
• submode：quick（限大文件加速）/ deep（完整）。

10.12 工具自省 tools.list / tools.describe / tools.load

AI 可以枚举自己当前可用的工具及其用法，减少「不知道有没有某个能力」的猜测：

列出的结果会按本会话实际可用的范围裁剪（受工具三态与分类延迟加载影响），并提示"当前表里看不见并不代表不存在，可以先加载对应分类"。

11. 安全分析工具

AVL Code 内置一组只读分析工具，适合在隔离样本目录上做基础研判。所有分析工具都按工具权限策略管控。

重要安全约束：在工作区下名为 samples/ 的子目录中，任何形式的执行类工具都被强制禁用且不可解除。这是为了防止误把样本当成可执行脚本跑起来。

11.0 把样本送进工作区

输入框左下角的「+」按钮提供最快捷的样本投放入口：

1. 点击 + → 系统弹出多文件选择对话框。
2. 选中一个或多个文件 → 自动落到当前工作区的 samples/ 子目录。
3. 输入区上方实时显示文件名 + 进度条 + 块计数；完成 1.5 秒后自动收起，失败保留 6 秒。
4. 完成后浮现 toast：「已添加 N 个样本到 samples/」。

注意事项：

• 可配置上限：默认 300 MiB，可在 设置 → 数据 → 附件 / 样本 中调整（1–4096 MiB），有「恢复默认」一键复位。
• 大文件分块上传：超过 4 MiB 的文件自动按 4 MiB 切片走追加写入，首块写入即占名解决同名冲突，规避单次 RPC 30 秒超时。
• 后端透明支持本地与远程工作区，无需关心目标盘符。
• 同名文件会按时间戳追加后缀，不会静默覆盖。
• 用户在系统对话框中点取消会被静默忽略，不报错。
• 没有活动工作区时按钮置灰，会以 toast 提示「没有活动工作区」。

随后即可在对话里直接让助手对刚添加的样本发起分析，例如「对刚才那个 PE 跑 hash + entropy + ioc_extract，给我一份初判」。

11.1 哈希、熵、十六进制

• 哈希：MD5 / SHA-1 / SHA-256 / 国密 SM3 等多算法。
• 熵：Shannon 熵（总体 + 分块），用于初判加壳 / 加密。
• 十六进制视图：以 hexdump 形式输出指定字节范围。

大文件完整覆盖：哈希 / 熵这类「单遍流式」算子完整覆盖整个文件（分块逐块计算、不限长度、内存占用恒定），返回的大小是真实大小。早期版本会把 >128 MiB 的样本静默截断到前 128 MiB 计算，导致哈希错误、VirusTotal 也查不到 — 本版根治。只读取部分内容的算子（sec.strings / sec.ioc_extract / sec.yara_scan 等）仍按原有上限工作。

11.2 字符串与 IOC 抽取

• 字符串：ASCII + UTF-16LE，可设最小长度。
• IOC 抽取：自动识别 IPv4 / IPv6 / 域名 / URL / 邮箱、哈希（MD5 / SHA-1 / SHA-256 / SHA-512）、路径（Windows / Unix），以及本版新增的 CVE 编号、Windows 注册表路径、MAC 地址、以太坊 / 门罗币 / 比特币等加密货币地址。
  • 先还原 defang 再提取：识别并还原 hxxp://、1[.]2[.]3[.]4、user[at]example[.]com、foo(dot)bar 等「去毒化」写法，分析师笔记 / 报告里的 IOC 不再漏抓。
  • 更精准、少误报：IP 走有效性校验并打标（private / loopback / link_local / multicast / cgnat 等），可选排除私网地址；域名按公共后缀校验（kernel32.dll 这类文件名不再误当域名）；MAC 不再被误判成 IPv6。
  • 结果更实用：按值去重并统计出现频次、附类型标签（含 defanged）；结果分页返回（与 sec.strings 一致）；可选输出 defang 形式（便于安全展示）与命中上下文片段。
  • 提取只是「候选指标」，不等于判黑 —— 用前请二次核实。

11.3 可执行格式解析

• PE 解析：节、导入表、导出表、资源、签名等。
• ELF 解析：节、段、符号、动态依赖等。
• Mach-O 解析：Load Command、节、签名等。
• Mandiant-style PE 导入哈希：用于聚类识别。

11.4 反汇编

线性反汇编，支持 x86 / x86_64 / arm / arm64 / ppc64；架构通常可由文件头自动嗅探。

11.5 反编译

通过自有的反编译能力把反汇编片段转成 C / Java 伪代码，结合 AI 解读后可直接给出更直观的逻辑摘要。

隐私提示：反编译会调用 AVL Code 的反编译模型；只在样本可外送的前提下使用。

11.6 流量元数据

• PCAP 元信息：总包数、起止时间、协议占比、Top-N 流。
• 流枚举（sec.pcap_stream_list）：列出 PCAP 中所有 TCP / UDP / ICMP 流并赋稳定 id。默认每页 200 条、最多 2000 条，可按 packets / bytes / first_ts（默认时间序）排序、按 offset 翻页 — id 始终是全局时间序编号，跨页跨排序都不变，可直接传给 sec.pcap_stream_extract。修了之前列十几万条流时一次性吐出几十 MB 把整轮卡住 / 假死的问题。
• 流载荷导出：把指定流的 L7 载荷 dump 到工作区路径，便于二次分析。
• 协议字段抽取：DNS 查询 / 应答、HTTP 请求 / 响应、TLS ClientHello SNI，以及协议级 IOC（IP 等）。

当前版本仅做单包检视，不做 TCP 重组。

11.7 规则匹配

• 支持业界主流 YARA 规则语法（含完整模块系统）。
• 默认安装为 stub 实现；如需完整规则集与模块支持，请联系内部分发渠道获取增强版本。

11.8 安全领域知识库 sec.ontology — 事实层 SSOT

给 AI 配的一个结构化事实库，把「谁依赖谁、什么暴露在外、谁有哪个 CVE」这类供应链 / 攻击面事实记录下来、长期持有；即使原始报告之后被对话折叠遗忘，这些结构化事实依然留存可查，并能做可达性推理（A 依赖 B、B 依赖 C → A 可达 C）。当前为 v1 本地工作区版本。

实体命名建议：pkg:lodash / svc:api / cve:CVE-2021-23337 等带类型前缀，便于跨类查询不冲突。

11.9 软件物料清单（SBOM）与供应链漏洞排查

sec.ontology 解决「把已知事实记下来」，而 sbom.* 这组工具解决「先把事实查出来」：它会扫描工作区里的依赖清单，理清「这个项目到底用了哪些第三方组件」，再对照漏洞库排查这些组件有没有已知漏洞、其中哪些真正会被你的代码触达。一共五个工具，都在对话里直接让助手调用即可，结果文件默认落到工作区的 .avlcode/ 目录。

sbom.generate — 生成物料清单

为项目生成 SBOM。自动识别主流生态与依赖清单：npm（package-lock.json / yarn.lock（含 yarn Berry）/ pnpm-lock.yaml（含 v5））、Go（go.mod）、Python（uv.lock / pdm.lock / poetry.lock / Pipfile.lock / requirements.txt）、Maven（pom.xml / gradle.lockfile / Bazel 的 maven_install.json）、Rust、Ruby、PHP、.NET（NuGet）、Swift、Dart、C/C++（conan）、conda、Elixir、CocoaPods、R、Haskell，以及本版新增的 Deno、Julia。默认输出 CycloneDX 1.5 JSON；可用 format 切换 spdx / dsdx / swid，加 -xml 后缀出 XML（如 cyclonedx-xml）、dsdx-tag 出 DSDX 原生 tag-value。输出可复现（不写时间戳 / 随机序列号、组件按固定顺序排）。缺某种清单就跳过该生态，全缺则得到 0 组件的空清单、不报错。

覆盖与精度增强（本版）：清单扫描递归子目录，缺锁文件时回退到清单文件解析；剔除把本项目自身误当第三方依赖的情况，正确处理 Go 的 replace / exclude，并加强版本比对保真（减少误报 / 漏报）。审计支持按生态逐一回退、补齐 Maven / Gradle / pip / Conda / Conan / npm 等精度提示、对未能审计的生态给出明确说明并附可利用性描述，便于判断风险优先级。

sbom.convert — 多格式枢纽，任意互转

支持 CycloneDX（JSON+XML）、SPDX（2.3）、DSDX、SWID 四大主流格式的读写，并能在它们之间任意转换（经一个规范化中间模型，N 读 + N 写而非两两组合）。input（待转文件）与 to（目标格式）必填，from 可自动嗅探。转换保留组件、purl、许可、哈希与依赖关系；目标格式不支持的字段会按规则丢弃（如 DSDX 无哈希）。对接不同上下游工具时不愁格式不一致。

sbom.audit — 排查已知漏洞

先生成清单，再逐个组件对照 OSV 漏洞库匹配，给出每条漏洞的严重度、CVE 编号、修复版本，并标注是否在 CISA KEV（已知被利用漏洞） 名单里。严重度按 CVSS v2 / v3 / v4 向量准确计算（critical ≥9 / high ≥7 / medium ≥4 / low）。mode 控制数据来源：auto（默认，本地有离线库就用离线、否则在线）/ online（api.osv.dev）/ offline（本地快照）。结果按最严重优先排序，KEV 漏洞永远置顶。

sbom.vex — 可利用性收敛，砍掉噪声

在 audit 基础上，用确定性的符号级可达性分析判断每个漏洞在你的代码里到底走不走得到，把「装了但根本没调用」的噪声收敛掉，输出标准 OpenVEX 文档。每条结论是 affected（确实受影响、要修）/ not_affected（用了但漏洞代码够不到）/ under_investigation（待查）/ fixed 之一，并附 not_affected 的机读理由。纯离线导入扫描即可用（air-gap 友好）；Go 凭 OSV 提供的受影响符号可直接收敛为 not_affected，其它生态可选 lsp_confirm（用语言服务器确认至少一处真实引用，默认关）或由 App 端的符号比对进一步收敛。结论按「还需处置的排前面」排序。

sbom.dbsync — 维护本地离线漏洞库（air-gap）

为 audit / vex 的离线模式同步本地 OSV 漏洞库。action：status（默认，纯本地、查看各生态记录数与新鲜度）/ sync（联网按生态拉取 OSV dump）/ import（用 zip_path + osv_eco 导入离线传入的 OSV zip，供完全隔离的环境使用）/ kev（刷新 CISA KEV 名录）。其中 13 种生态有 OSV 离线 dump 覆盖（conan / conda / CocoaPods 暂无离线库，可在线审计）。

隔离网（air-gap）用法：把数据源指向内部镜像（必要时配代理），再用 sync 或 import 填好本地库，此后 audit / vex 即可全程离线运行。相关源地址、代理、默认模式可在 设置 → 安全 → 供应链 / SBOM 配置；留空即用内置默认（直连公网）。该面板还展示每个生态的离线库记录数 / 新鲜度、KEV 条目数，并提供按生态多选同步与「同步 KEV」按钮。保存按钮为「测试并保存」：先校验地址 / 路径合法性、再按「默认审计数据源」探测可用性，不可用则拒绝保存；本地漏洞库路径等离线字段归入「离线漏洞库」区，保存时会把路径规范为绝对路径。另有「重置为默认」按钮一键把各字段清回内置默认（仅改表单，需再点「测试并保存」才生效，避免一键误清掉自定义镜像配置）。

11.10 云端威胁情报与哨兵扫描（VirusTotal / Google Threat Intelligence）

AVL Code 接入 VirusTotal / Google Threat Intelligence（GTI） 做云端威胁情报。整体分两条正交的轴，在 设置 → 安全 里配置：

• 威胁检测（能力）：配好一种检测方式后，Agent 就能调用扫描 / 情报工具做分析。
  • 云端检测服务（三选一）：VirusTotal AI · 免费托管（零配置即用，文件哈希与可疑文件会上传做公开分析、别名上公开排行榜）/ Google Threat Intelligence · 自带 API Key（用你自己的 key、结果不公开）/ 不使用云端。
  • 本地 YARA 规则（独立开关）：纯离线规则检测，可与云端同开，也可单独作离线用。
• 自动扫描拦截 · 哨兵（Sentinel）：开启后，Agent 读 / 写 / 执行文件时自动扫描并阻断恶意命中。

关键改进：检测能力与哨兵拦截解耦。只要配好云端后端或本地 YARA，相关扫描 / 情报工具就能直接被 Agent 调用——无需开启哨兵拦截。两轴互不牵连。

哨兵侧的哈希扫描工具（sec.vtai_*）：

全量情报工具（vt.*，独立门控，见 §11.10.1）：直查 VirusTotal / GTI 的 v3 API 做情报富化，与哨兵并存、独立开关。

11.10.1 vt.* 全量情报工具

在 设置 → 安全 → 「Google Threat Intelligence 全量情报工具」 开启后（需先配好可用的 API Key），Agent 可调用：

门控分级（设置 → 安全）：主开关启用（凭可用 key）→ 仅查询模式（默认开，只读、拦写 / 提交 / 上传）→ 启用收费功能（默认关，放开 Premium/GTI 端点，实际仍受 key 档位限制）→ 上传样本前确认（默认开，仅在关掉「仅查询」时出现）。响应经紧凑摘要（verdict / 检出比 / 名称 / 标签 / 链接等）避免占满上下文，raw=true 可取原始 JSON。密钥不可用会在启用环节即提示（不再等到调用才报错）。「恢复默认」按钮非破坏性——取消选用云端并关上传，但保留 API Key / VirusTotal AI 注册与全量情报工具配置。

11.11 数据可见性

所有分析结果都直接落到对话流，可独立查看 / 复制 / 导出。AVL Code 不会把样本本体上传到任何第三方；只有反编译会按需调用反编译模型（仅发相关反汇编片段），以及 vt.submit / sec.vtai_scan 上传（需你显式确认 / 开启）会把文件送往 VirusTotal 云端。

12. 外部工具服务接入

智能体管理器 →「配置工具」面板支持连接任意标准协议的工具服务（例如 Notion、内部 API、私有知识库）。

注意与 设置 → 提供商 区分：后者配置的是大模型供应商，与这里的外部工具服务是两回事。

12.1 添加一个外部服务

1. 输入区模式滑块旁的齿轮（智能体管理器）→「配置工具」→ 添加服务。
2. 选择通道：
   • Streamable HTTP（默认）/ SSE：填写接入地址（URL）+ 凭证 — 适合云端服务。现代 MCP 服务多用前者；两者填错时连接会自动协商回退，不必纠结选哪个。
   • stdio（本地进程）：填写要启动的命令行（如 npx -y @some/mcp-server） + 环境变量 — 直接在本机起一个子进程作为 MCP server，不必再要求对方提供 HTTP 地址，方便接 npm / pip 上现成的 MCP 实现。
3. 填写：
   • 名称：例如 notion。
   • 凭证：从对方平台获取的访问令牌（HTTP / SSE 通道）；或子进程要的环境变量（stdio 通道）。
4. 启用。

界面已重做：新建表单、后端详情、健康看板、安装确认弹窗整体改为更克制的数据表质感 — 技术信息用等宽字体披露、发丝级边框、状态圆点，整体更清爽专业。

12.1.1 远程 MCP 的 OAuth 登录

对于需要登录的远程 MCP 服务，新建流程内嵌OAuth 2.1 + PKCE 授权：

• 建的时候就能登录：授权入口放在「新建 MCP」流程里（不再藏在建好之后的详情），点「OAuth 授权」会跳浏览器走标准授权码 + PKCE 流程，本机回环回调收到 token 后自动落地。
• 自动续期：access token 在到期前用 refresh_token 在启动时 / 后台自动换新，授权成功后界面即时反馈并刷新状态，不必反复手动重连。
• public client（无 client_secret）和带 client_secret 的 confidential client 都支持；endpoint 可通过 .well-known 自动发现，也可手填。

12.1.2 安装确认弹窗：权限与依赖一目了然

装一个 MCP 后端 / 插件前，安装确认弹窗会把以下内容披露给你：

• 要披露的工具权限：会启用哪些工具、各自的允许 / 询问 / 禁用默认值。
• 声明的工作模式：permissionMode / allowed-tools 等约束（来自插件 manifest）。
• 对本机的依赖：如需要 node / python / git 等本机命令、操作系统、平台架构限制。
• 远程工作区下额外给出轻量提示，避免装上对方机器没有的依赖。

12.2 工具命名空间

外部服务暴露的工具会被自动加上前缀（例如 notion.search、notion.create_page），在工具列表里独立成组，互不冲突。

12.3 实时生效

新连上的外部服务下个回合即对助手可见，不必重开对话。这一特性让你可以在对话过程中随时增配服务。

开启工具分类延迟加载（默认开启，见 §9.2.1）时：会话进行中新连上的服务会直接可用，不用等助手主动加载；新开会话后才回到"用到时才加载"。

12.3.1 单独设置某个服务是否延迟加载

在智能体管理器 →「配置工具」Tab 里，每个外部工具服务都有一个「延迟加载该服务的工具」开关：

• 开启（默认）：该服务的工具不常驻，助手用到时才加载。
• 关闭：该服务的工具始终可用 —— 适合你高频使用的服务。

若全局的「工具分类延迟加载」已关闭，所有工具本就常驻，此开关暂不起作用，界面会直接说明。

助手在系统提示词里会被告知你接入了哪些外部服务，并附上每个服务的工具数量与几个示例工具名，因此即使工具暂未加载，它也知道该找谁。

12.4 异常处理

• 断连重试：后端断开会自动指数退避重试。
• 错误抽屉：错误信息会拼接服务端原始返回，便于定位是凭证过期、网络不通还是服务端故障。
• 就绪探测：连接建立后 AVL Code 会先做一次 ping，确保对端真正可服务再登记到工具列表。
• 后端一时缺席不再整体失效：某个后端暂时缺席 / 未就绪时，工具调用过去会返回「unknown tool」协议错误把工具整体拖垮；现在对未知工具做兜底处理，并在需要时按需重连、自愈，等后端就绪后自动恢复可用。

12.4.1 MCP 健康看板

MCP 配置 → 健康看板 按后端展示每个 MCP 的调用次数 / 失败率 / 响应耗时（P50 / P95），一眼看出哪个服务慢、哪个在报错；某后端最近一次失败的错误信息也会在该行展开，便于定位。

数据来自 MCP 网关的环形缓冲统计（最近一段时间窗口），实时刷新。

12.5 安全 — 凭据国密加密存储（VAULT）

• MCP 后端的鉴权令牌（HTTP Bearer AuthToken）和 stdio 子进程的环境变量整张 map 不再明文落盘，统一存进国密加密的凭据库（SM4-GCM + HKDF-SM3、与本机 machineID 绑定，跨机即失效）。
• OAuth refresh_token + 续期元数据同样进 VAULT，绝不入 zmcp.yaml 主配置、绝不入日志。
• 存量配置自动迁移：旧的明文凭据下次使用时被动迁移到 VAULT 加密存储，无需手工干预；machineID 不可达 / 变化时优雅降级（回退提示重输），不会神秘失败。
• 冷启动 401 修复：之前带鉴权的 HTTP MCP 服务在电脑 / 应用冷启动后第一次调用会报 401——根因是 zMCP 网关子进程的归档 key 错误使用了每次启动都变的临时 127.0.0.1:<端口> URL，而 App 父进程是按稳定的 workspaceID 落库，导致 Load 恒 miss、回退到「存量被动迁移已清空」的明文（即空字符串），最终发了个空 Bearer 头被后端拒绝。本版改为读写两端都用稳定的 workspaceID 当 key，冷启动后正常带凭据连上、无需手动重配。
• 凭证以加密形式存储在本机，不会随同对话内容上传到模型。
• 第三方 stdio 服务拿不到网关管理密钥：以标准输入输出方式启动的第三方 MCP 服务不再继承工具网关的管理密钥，第三方进程不会持有本不该拥有的网关管理权限。
• 可在智能体管理器 →「配置工具」中针对每个外部服务独立设置工具权限策略。

13. 工具权限与审批

AVL Code 通过工具权限策略对每一次工具调用做精细化管控。

13.1 三态权限

每个工具都可以设置为：

• 启用：直接放行。
• 询问：每次调用前弹窗审批。
• 禁用：直接拒绝。

可按工作模式独立配置；常见做法：execute 模式启用写工具，plan 模式禁用所有写工具。三态对子代理同样生效（禁用工具在子代理侧一并拿不到），插件 / 外部服务卸载后残留的工具配置会被自动清理。

13.2 调用前审批

当一个被标记为「询问」的工具即将执行时：

1. 桌面端弹出审批弹窗，展示工具名、入参与影响范围。
2. 你可以选择：
   • 允许（仅本次）
   • 始终允许：把"工具+参数模式"加入白名单。
   • 拒绝
3. 弹窗带 30 秒倒计时，超时未响应按「拒绝」处理。

13.2.1 无限制模式（高级）

输入区模式滑块右侧有一个盾牌开关，专给清楚自己在做什么的高级用户用。开启前先过一道风险确认弹窗（含 5 秒冷静期 — 确认按钮先禁用并倒计时「请仔细阅读风险提示 5s…」，归零才能点，期间按 Enter 也不触发），开启后红色危险态常驻提醒，关闭即时生效。

作用域：按会话独立、纯内存、重启即清，不会悄悄留着。

开启后解除三类日常摩擦：

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

• samples/ 沙箱隔离
• rm -rf 等破坏性命令的参数校验
• 危险注入黑名单（fork 炸弹 / 写 /etc / curl|sh / eval）
• http(s) 协议白名单

斜杠命令快捷开关 — 也可在输入框直接敲：

• /unrestricted（或中文别名 /无限）— 切换当前会话的无限制模式。开启时同样过 5 秒冷静期的风险确认弹窗，关闭即时生效。中文别名在命令菜单与 /help 里隐藏（避免重复行），但键入回车仍可执行。

无护栏区间的消息标识：无限制模式期间产生的连续消息会以浅色边框整体圈出，起止一目了然，事后回看能一眼分辨哪些内容是在无护栏状态下生成的；关闭开关后边框当场收口，模式未结束时不会提前打「结束」界标。子代理可按需递归继承该模式，继承产生的消息同样带标识。

13.3 白名单匹配

「始终允许」的匹配粒度可在 设置 → Hooks → 自动批准 中调整：

• 仅本次（最严）
• 同工具同参数
• 同工具任何参数
• 整个工作区放行（最松）

13.4 多端审批

同一条审批请求会同时出现在桌面弹窗与已绑定的远程通道（如微信）；首个应答生效，其余端的后续回复会被提示已应答。另有一条容易混淆的规则：拒绝 > 挂起 > 询问 > 允许 的优先级排序属于 Hook 层 — 同一次评估中多个 Hook 返回的权限决策按它合并，与多端应答无关。

13.5 远程审批

如果你已绑定微信通道，所有 询问 类审批都会同步推送到对应聊天，你可以在微信里用一行命令完成审批：

/approve <审批号>      # 允许本次
/always  <审批号>      # 始终允许
/deny    <审批号>      # 拒绝

桌面侧弹窗会同步消失，整条任务自动续跑。

13.6 留痕

审批决策不落独立审计存储：仅「始终允许」写入工作区级授权文件 hook-approvals.yaml（记录授权指纹与决策时间），可在 设置 → Hooks 查看与撤销；「仅本次允许」与「拒绝」只作用于当次调用，不留存记录。

14. 技能（Skill）系统

技能（Skill）是一个由提示词模板 + 元数据组成的小包，让助手拥有"领域专家"能力。AVL Code 的技能系统兼容业界主流格式，可以直接复用社区生态。

14.1 三层来源

工作区版本会覆盖全局版本，方便不同项目使用不同口径的同名技能。

内置技能（开箱即用）：应用随包内置一批技能（如 AI 引导式 skill-creator，帮你在引导下创建、完善自己的技能）。内置技能在启动时自动物化，内容漂移会被自动覆盖以保证一致；并通过构建期签名 + 内置签名锚点，在严格签名策略下也能正常放行。设置 → 技能 面板会给它们标注「内置」徽标，便于与自建、第三方技能区分。

Agent Skills 兼容加固：加强了对 Agent Skills（agentskills.io） 的兼容 —— 改进跨客户端的技能发现与解析容错、补充工具名称的翻译映射，让不同来源、不同命名习惯的技能都能被正确识别和调用。

14.2 双轨触发

• 用户触发：在输入框敲 /技能名 参数1 参数2 → 渲染后注入到下一条上下文。
• 助手触发：助手自主选择并调用，结果作为工具响应回到对话流。

更主动的技能匹配：系统提示里补上了当前可用技能清单，并强化「动手前先按用途匹配合适技能」的引导。结果是 AI 更倾向于在合适的任务上主动选用贴合的技能，而不是埋头硬做或重复造轮子。

14.3 技能包结构

每个技能就是一个文件夹，里面包含一份说明文件：

• 前置元数据：名称、用途、参数提示、可用工具、适用模式。
• 正文：真正的提示词模板，支持参数替换与小段命令预处理。

14.4 编写一个技能

下面是一个最小例子的概念图（具体语法以官方模板为准）：

name: code-review
description: 给一段代码做严肃 review，列出问题与改进建议
argument-hint: <文件路径>
allowed-tools: [读文件, 内容搜索]
work-modes: [plan, assess]
---
请审阅 $1，重点关注：
- 边界条件与错误处理
- 命名与可读性
- 与项目其他代码的一致性

放进 <工作区>/.config/skills/code-review/ 后，输入 /code-review src/utils/format.ts 即可触发。

14.5 签名与验签

发布给团队的技能包建议进行国密签名校验。AVL Code 内置签名工具，可生成密钥、自签证书、对技能包整目录签名，并在加载时自动验签 — 签名失败会被拒绝执行，确保从邮箱、网盘获取的技能不会带毒。

统一签名验证策略开关：签名策略与信任库现集中在独立的 设置 → 技能/插件签名 标签页（安全分组），一个开关同时管住技能和插件 — 改成「跳过」即可允许装未签名的技能与插件；切换时自愈历史遗留的不一致状态。

信任库即放即生效：信任库支持手动 / 自动重新加载，并可直接导入根证书 PEM — 投放证书后即时生效，不再需要重启应用。

「来源不可证实」由你决定：签名策略为 warn 时，无法证实来源的技能 / 插件改为弹出确认、由你选择是否放行；而存在篡改证据的包仍然硬性拦截。拒绝或导入失败时会透出具体原因，不再是笼统报错。

14.6 调试

设置 → 技能 提供：

• 模板预览（参数替换后的最终提示词）
• 命令预处理结果
• 元数据校验
• 适用模式的检查

14.6.1 发布前自查：market.check

新增内置只读工具 market.check：按 AVL Code 应用商店（zMarket）的发布契约校验一个本地技能 / 插件目录，报告过 / 不过 + 原因 + 缺什么（name slug、严格 semver 版本、source 形态、能力声明、归档安全等）。纯本地确定性校验，不联网、不提交。创建 / 编辑技能后、发布前先跑一遍按报告补齐即可。

• 参数：path（必填，待校验目录相对路径，如 .avlcode/skills/my-skill）、kind?（skill/plugin/mcp/provider，缺省自动探测）、version?、source?、manifest?。
• 注意：.skill-sign 的签名 ≠ zMarket 认可；本工具只查发布契约形态，不代表运行时安全审计。

14.7 团队共享

把技能放进团队仓库后，新成员只需把文件夹放到工作区指定路径即可自动识别。配合签名机制可形成"内部技能市场"。

15. 子任务与后台执行

复杂任务往往需要把工作拆给"子助手"。AVL Code 内置子任务调度能力，支持前台同步与后台并发两种模式。

15.1 派发子任务

助手在对话中可以调用一个「子助手」工具，把一段提示词派给独立的子任务执行，子任务完成后把结果合并回主对话流。这一过程对你是透明的，但你可以在工具调用卡片里看到每个子任务的详情。

15.1.1 子 Agent 继承外部 MCP 工具

派出去的子 Agent 自动继承你在工作区配好的外部 MCP 工具（之前子任务用不到这些外接工具，得回到主对话才行）：

• 机制：派发时经 /admin/routes + /admin/backends 解析本工作区所有外部后端的工具前缀（如 notion / memory / channels 等命名空间），通过环境变量 ZAGENT_MCP_INHERIT_PREFIXES 注入；子 Agent 的 ZAGENT_ALLOWED_TOOLS 白名单无条件穿透这些前缀。
• 覆盖范围：所有声明了 tools: 的子代理（plan / assess / prepare / mcp-admin 与用户自建）；所有工作模式统一（含 plan）。
• fail-safe：解析失败 → 返空 → 不继承，不影响子任务正常派发。

15.1.2 子任务模型 / 供应商匹配修复

之前在多供应商配置下，派出去的子任务沿用父会话的模型，但供应商恒取列表里的第一个，两者对不上时会报「模型不存在」起不来。本版改为供应商跟着继承的模型走 — 优先选真正包含该模型的那个供应商，子任务能稳定启动。

15.1.3 并行 fan-out：一次拆多路同时跑

除了一次派一个子任务，AI 还能用 AgentParallel 工具把一个任务一次拆成 2–16 条「腿」同时跑，每条腿是独立的 fresh-context 子 Agent、互不可见，全部完成后自动汇总结果返回。适合需要多路并发的活（如同时审好几个模块、并行检索多个来源），比一个个排队串行快很多。

• 每条腿各自带提示词、可单独指定子代理类型与模型；提示词需自包含（腿看不到主对话历史）。
• 并发上限 16 条（远低于后台任务总并发 64，单次 fan-out 不会霸占全部槽位）；不足 2 条请改用单个 Agent。
• 整体等待超时默认 600 秒、上限 1800 秒；到时未完成的腿返回 pending 并在后台继续，可用 TaskWait / TaskOutput 续跟。
• 单条腿失败 / 被拦不会拖垮整批，失败原因会一并随结果返回让 AI 自行处置。每条腿输出过长会截断（提示用 TaskOutput 取全文）。
• 执行期就能看到实时状态：并行子任务的调用卡片在执行期间即出现（不必等终态才冒出来），并实时反映各子任务的运行状态；停止后不再持续转圈，极简密度下结果块也不会被误折叠。

15.2 前台 vs 后台

• 前台：主助手等待子任务完成（默认 10 分钟超时），适合"必须等结果"的任务。
• 后台：子任务异步运行，主助手立刻得到一个任务编号，后续可主动拉取状态或停止该任务。后台任务有总数上限（防失控）和自动回收（终态超时清理）。

15.2.1 「空闲制」看门狗 + 绝对兜底

子任务超时改成「按空闲计时」：只要还在持续产出就不算超时，看门狗只针对真的卡住、长时间无任何输出的情形。再叠加一道绝对兜底（默认 60 分钟），防止极端死循环 / hang 把任务永远留在跑的状态。

• 空闲窗口：默认 15 分钟无输出 即超时（错误信息会明确写「子 Agent 空闲超时」）。
• 绝对上限：默认 60 分钟 强制结束（写「绝对兜底」）。
• 正常长任务不受影响：只要还在 stream 产出（包括思考段、增量字符）就一直续命。
• RunAgentToolBackground 后台路径不计执行超时（你显式把它放后台跑就接受它跑久）。

15.3 并发上限

为防止一次发起过多后台任务造成失控，AVL Code 会限制同时在跑的子任务数；超出后助手会被告知"先稍等再发起"，避免雪崩。

15.3.1 阻塞等待 — TaskWait 工具

主助手可以「一次调用、阻塞等待」后台任务 / 子代理跑完，不用再一轮一轮反复查询进度：

• 支持等「全部完成」或「任一完成」。
• 可设超时（默认 5 分钟、最长 30 分钟）；到点会如实返回「还在跑」让模型决定是否继续等。
• 等待期间只回状态与最终结果，不把中间过程灌回主对话，省上下文也更省 token。

15.4 终止

• 在桌面端，点击输入框右侧 停止 按钮会同步终止主助手与所有派生子任务。
• 在微信侧，发送 /stop 同样会触发级联终止。
• 子任务也能单独停止：子代理抽屉里每个正在跑的子任务都有独立的停止按钮，不必整轮一起停（对后台 / 并行 fan-out 的腿尤其方便；同步内联的子代理需停整轮）。

15.4.1 真实总消耗看得清（含子代理）

用量统计会把子代理（并行 / 子任务）的真实消耗也算进来：目标条（GoalStrip）与每轮结束的标识都显示真实总 token 消耗 + 工具调用次数，有子代理时还会拆出「自身 + 子代理」的构成。该统计按会话持久化，长会话看到的是全程真实总量（即使没设目标也照常累计）。

15.5 输出聚合

后台任务的中间日志可作为独立卡片在主对话流里展开查看；任务完成后会以一段精简摘要返回，避免淹没主线索。

15.5.1 AI 建议任务：一键拆分去做

AI 干活时如果顺手发现了分外但值得做的事（死代码、过期文档、确认存在的 TODO、安全隐患等），会在消息流里挂出一张「建议任务」卡片，而不是打断当前正事。

卡片上的执行按钮是个 split button：

• 主按钮一键：默认「开启新会话执行」。
• 展开 ▾ 还有 4 种方式：
  • 在新会话中执行（主按钮默认）
  • 在当前会话中执行
  • 复制到输入框
  • 复制到剪贴板

由你来决定怎么处置。已执行的建议会标记状态，AI 也可以撤回已经过时的建议。多条建议会聚合到输入框上方的一个条里统一管理。

15.6 例行程序：让 AI 按计划自动干活

「例行程序（Routine）」让你给某个工作区定一条指令，让 AI 按时自动或按需手动执行 — 比如每天早上拉取并总结昨日 issue。

新建入口：

• 工作区侧栏「新建例行程序」一键打开对话框（也支持从 Header 当前工作区进）。
• 表单字段：名称、指令内容、执行模式、模型（与正常对话同款选择器：模式色卡说明、模型搜索分组）、计划时刻。
• 写到一半自动暂存 — 中途跳去设置或 Agent 管理器调配置，回来自动重开并恢复已填内容。

计划方式：

时刻选择顺手：

• 时 / 分双列下拉（选中居中、选完分钟自动收起）；每小时一次模式下只露分钟列
• 周几用圆形单字字块，附「工作日 / 周末」一键预设
• 调度精度：30 秒 tick；hourly 跨日 / DST 用时间算术天然正确

统一管理：

设置 → 例行程序 Tab 按来源工作区分组：

• 启停开关（与其它设置页同款）
• 立即运行
• 查看最近运行痕迹
• 未打开的工作区有徽标提示并可一键打开
• 侧栏图标直达本工作区的例行程序列表
• 支持按名称 / 工作区搜索

运行行为：

• 每次运行会在对应工作区生成正常会话，过程与结果都可回看。
• 同一条例行程序运行中会自动跳过下一次触发，不会叠跑。

15.7 长程任务崩溃后可恢复

放到后台跑的长任务（即以 run_in_background 派发的子任务），其进度会实时落盘保存；应用意外退出 / 被杀 / 崩溃 / 升级打断后重新打开，能把没正常结束的任务找回来接着干，不必从头再来。

它怎么工作：

• 每个未结束的后台任务都以一份快照写到本机（跨工作区的全局目录）；任务正常走到 done / error / killed 终态时会删除该快照。所以重开后还留在盘上的，就是上次被中断、没跑完的任务。
• 启动时会异步扫描这些残留任务，先做一次「脏条目清理」——父会话已不存在、再也无法恢复的条目自动删掉；扫描不阻塞启动，没有残留就静默无感。
• 恢复并不是直接重启子进程，而是往原来的父会话里注入一句「之前委派的后台任务尚未完成，请继续或重新委派」，让主助手以「先派发」的方式接着完成——这一步对你可见，你能看到「正在恢复任务 X」。

你会看到什么（恢复横幅）：

• 有被中断的任务时，顶部出现一条恢复横幅，标题形如「N 个后台任务上次被中断」；没有就不显示。
• 每条任务旁有两个按钮：恢复（，注入续跑消息并从盘上移除该条）/ 忽略（从盘上删除，下次不再提示）。右上角还有「全部忽略」。
• 恢复成功后弹 toast「已恢复:将在原会话继续该任务」；失败则提示具体原因（如「原会话已不存在,已清除该恢复项」）。

自动恢复（可选，默认关）：

• 在 设置 → 智能体 → 自省 打开「自动恢复被中断的任务」开关，重启后会自动接着跑上次崩溃 / 被杀时未完成的后台任务，适合夜间无人值守的长任务。
• 为防「续跑消息风暴」，启动自动恢复每次最多 5 个，其余仍留在顶部横幅供手动恢复。
• 关闭该开关时（默认），所有被中断的任务都只在顶部列出，由你手动决定恢复或忽略。

16. 计划与待办

16.1 计划（Plan）

筹划模式下，助手通常会输出一段结构化计划：

• 总目标
• 阶段划分
• 每阶段的输入 / 输出 / 风险

计划以独立卡片浮层显示，可：

• 接受（进入执行）
• 修改（在线编辑后再交回助手）
• 拒绝（让助手重新规划）

16.2 待办（Todo）

执行过程中助手会动态维护一份待办清单，逐项标记进度：

• 待办
• 进行中
• 完成
• 跳过 / 失败

待办列表实时显示在右侧浮层，你可以随时补充 / 调整 / 删除条目。

16.3 跨折叠保留

历史折叠（见第 17 章）发生时，计划与待办的结构化状态完整保留，不会被压缩为模糊摘要。这意味着即使会话已经很长，AVL Code 仍然清楚"我在做什么、做到哪一步"。

16.4 Turn 终点 todo 督促

一轮收尾时（isGoalTurnFinalRecord 命中），如果待办清单仍有未完成项，AVL Code 会自动补一条隐藏 user 消息（source = auto_todo_nudge）督促 Agent 去核实进度：已完成的标 completed、未完成的续推、被阻塞的明说并停。

• 避免「活干了一半、待办还挂着却没人跟进」的情况。
• 与 goal 自动续转、compact nudge 同族，是 turn 终点的另一名新成员。
• 隐藏 user 消息：不进入正常对话流可见区，但 Agent 能读到并响应。

17. 历史折叠（Compact）

当上下文接近模型上限时，AVL Code 会自动把历史折叠为摘要，确保对话可以无限延续。

17.1 触发方式

• 手动：会话标签栏右键 → 折叠当前会话。
• 自动：助手在自身上下文接近上限时自动触发，不打断当前回合。

17.2 折叠后的可见性

折叠是只追加的：原消息物理保留，只是被标记为"对当前回合不可见"。你可以在消息流上点击折叠摘要展开查看原始内容。

17.3 保留的结构化信息

折叠摘要中至少保留：

• 当前计划与待办的最新状态
• 关键的工具执行结论
• 用户已确认的关键决策
• 上下文必需的事实（路径、版本号等）

17.4 多次折叠

长会话可能经历多次折叠；每次折叠都是叠加而非替换，最早的内容总能逐层回溯回去。

17.4.1 自动折叠被中止时显示真实原因

自动折叠（自动 compact）历史被中止时，聊天区会显示具体原因而不是笼统提示，方便你判断是配置、上下文还是其它情况导致；优雅中止 / 保留会话的既有行为不变。

17.4.2 上下文超限根治

某些场景下对话可能突然报错断流（上游返回 400），且自动压缩也救不回来。真因往往不是 token 统计低估，而是 单条工具结果太大 — 例如安全扫描 sec.* 一次吐出近 300 KB 的 strings 提取，几乎占满整个上下文窗口，两条背靠背就把下一次请求顶过窗口被上游直接拒绝（这种拒绝不返回用量，反应式压缩看不到、来不及触发）。

两层根治：

1. 工具结果钳制：每条工具结果先钳到一个安全大小（约为上下文窗口的 6%，按 UTF-8 字符边界安全截断并留「继续读取」标记），从源头消除「一步顶爆窗口」。
2. 发送前预估式护栏：以上一轮真实用量为锚 + 本地估算本轮新增；预判会超窗就提前走"压缩后继续"，不再白发一个注定被拒的请求。

17.4.3 自动压缩后可靠续跑

自动压缩历史后，AI 有时会停下来只回一句寒暄 / 报当前时间 / 反问「请问需要我做什么」，而不接着完成手里的活。本版做了一组改进让它可靠续跑：

• 续跑指令改为明确的指令式：直接要求依据压缩摘要里未完成 / 进行中 / 受阻的任务从下一步继续自主执行，不要只回寒暄或当前时间。
• 续跑那一轮不再在末尾注入时钟提示，避免弱模型把「当前时间」当成最新重点而忽略待办。
• 万一续跑还是停在反问上，自动补一记「继续」（复刻你手动敲「继续」的效果）把后续工作推完。
• 进度条复用手动 /compact 同款（带百分比 / 预计时间 / 实时字数），不再只有一个模糊的「处理中」指示。

17.4.4 思考型模型的压缩不再被误判超时

之前自动压缩对所有模型用同一个固定总时限，遇到 reasoning / extended-thinking 型模型时，模型在思考阶段没立刻吐 token 就被错杀，于是续跑前的摘要直接失败。本版把等待改为空闲看门狗：只要服务端还在持续产出（包括 thinking 段落），就继续等；只有真正一段时间无任何动静才超时。结果：思考型模型也能正常完成压缩摘要，对话不再被中途掐断。

17.4.5 纯空白回复不再被误判为"结束"

推理型模型有时会在思考中间态吐出只有换行 / 空格的片段。之前终止判定是「输出非空就算还在干活」，这种纯空白片段会被反向解读为"已结束"，整轮被提前掐断。本版把判定改为「按去空白后是否为空」 — 思考中间态的空白段不再误停，整段推理完整保留。

17.5 KV Cache 前缀缓存治理（性能）

上游模型服务按「前缀缓存」工作：系统提示 → 工具列表 → 对话历史 这一长串，只要靠前的字节没变就能命中缓存、跳过重算；一旦靠前位置有任何一字节变化，从该处往后的缓存全部作废、整段重算。

为让缓存在整段对话里持续保温，AVL Code 在三个"每轮都在变"的源头做了治理：

TUI 模式同步治理 — 命令行界面也把目标块改为行尾瞬态注入，桌面 / 终端两种使用方式的缓存表现一致。

效果：长对话、多轮工具调用场景下，命中缓存的比例显著提升 — 响应更快、token 成本更低。这条优化对用户透明，无需任何配置。

17.6 记忆宫殿（长期记忆）

AVL Code 内置「记忆宫殿」作为跨会话的长期记忆库。一段对话结束后，HookStop 会触发记忆候选抽取，落到当前宫殿的草稿盒（_pending/ 子目录）由你审阅；批准后才正式入库进入相应「房间」（Room）。命令面板里 /memorize <text> 直写一条、/memory 打开宫殿面板。

17.6.1 越用越聪明：召回加权与负反馈

记忆不再只按时间或匹配度排序：

• 召回 / 成效双计：每条记忆带 recall_count（被翻出来次数）与 success_count（用了之后这一轮顺利完成的次数），加权后常被命中又确实帮上忙的排得更靠前；老被翻出却没派上用场的慢慢沉底，不再干扰判断。
• 罕见词加权：检索时偏冷门 / 特征更强的词命中权重更高 — 更容易把真正相关的那一条翻出来，而不是被通用词淹没。
• 无关时少塞：与当前提问相关性弱的记忆不再一股脑注入，只保留你置顶（pinned）的几条 — 既省 token 又减少干扰。
• AI 自审的教训自动沉淀：自检门禁的 judge 检查器发现的问题（见 §10.11.1）会自动沉淀成记忆草稿进入待审区，下次遇到同类问题能直接复用。

17.6.2 冲突放「待审」，不硬覆盖

新记的内容与旧记忆矛盾（同 Subject + Predicate 但 Object 不同 — 典型如偏好 / 决策翻转）时，不直接覆盖，而是落到草稿盒并标 ConflictHint = 旧记忆 ID：

• 前端 MemoryReviewPanel 在该条上高亮显示「与旧记忆冲突」。
• 你可一键取代（旧记忆置过期）/ 保留旧的 / 驳回新的。
• 与 MergeHint（与旧记忆三元组高度重合 → 疑似重复、建议合并）互补：merge = 该合并，conflict = 该取代。

17.6.3 记忆健康看板

设置 → 记忆宫殿 → 健康看板 把每座宫殿的状况一屏摊开：

每一条都能直接跳到正式条目做置顶 / 编辑 / 删除；簇可一键合并。

17.6.4 自动反省（复盘学习，GRAI+KISS）

打开 *设置 → 智能体 → 自省 → 「自动反省（复盘学习）」*（默认关，因为会有一次 LLM 调用成本）后，多步任务收尾时会自动跑一次复盘：按 GRAI 框架回顾这一轮——目标（Goal）、结果（Result，读本次轨迹摘要 + 自愈统计）、归因（Analysis，5-WHY，优先看自己可控的原因）、洞察（Insight）——再把可行动的经验教训按 KISS 分类（保持 / 改进 / 停止 / 开始）沉淀下来，下次遇到类似情况能直接用上。

• 只在做过多步工作的任务收尾时触发：单轮问答不会触发；异步进行、不阻塞你继续用。
• 教训落到记忆宫殿的「待审草稿盒」（_pending，房间 scratch、类型 decision、不衰减），需你人工审批后才进入正式记忆库参与检索（每次最多 8 条，按标题去重）。
• 全程 fail-safe：记忆关闭 / 无 LLM / 解析失败都会静默跳过，绝不影响任务本身。

自动反省读取的「自愈统计」正是 §8.5.1 里那套自愈成败历史，二者共同构成经验学习闭环：自愈从历史学着调整尝试次数，复盘把教训沉淀供你审阅。

18. 随行通讯

「随行通讯」让你在通勤路上也能远程指挥桌面助手、收审批、与团队协作。

18.1 通道

• 微信通道：扫码登录，无需对方开发者账号。
• 预留飞书 / 钉钉等其他平台。

18.2 绑定

1. 设置 → 随行通讯。
2. 用微信扫码登录通道。
3. 在桌面端为目标工作区生成 6 位配对码（10 分钟内有效）。
4. 在微信单聊或群里发：/bind 123456。

绑定成功后，桌面会话与微信会话自动共享，重启后对话完整保留。

18.3 路由策略

入站消息按以下优先级路由（前者命中即停）：

1. /new [文本] 新建的会话
2. /s <短id> 显式切换的会话（行内 [s:<短id>] 前缀等价）
3. 上次活跃会话
4. 首次入站自动分配的兜底会话

工作区维度按 [ws:<工作区名>] 行内覆盖 > 绑定的工作区 > 全局默认工作区取值。

18.4 内置命令

18.5 行为细节

• 正在输入：助手处理中会用「输入中」做回执，不再发占位文本，免打扰。
• 自动分片：长回复自动分段，避开微信单条消息长度上限（默认最长不超过约 3800 字）。
• 跨端接管：手机上 /s <短id> 即可继续未完成的桌面会话，原消息流不丢。
• 主动推送：助手运行中可主动把中间结果推到群里或单聊，例如长任务的阶段性提交。

18.6 群协作

绑定到群以后：

• 多人都可向助手发消息；助手回复在群里所有人都能看见。
• 审批卡片所有人都能看到，谁先点击谁回写。
• 群里可以用 /sessions 查看所有正在跑的会话，便于团队 Leader 总览。

18.7 双向待处理徽标 + 入站停泊队列

设置 → 随行通讯 → 工作区绑定 每个绑定行会显示双向徽标（仅 >0 显示）：

入站停泊：以前对端在工作区关着时发消息，会被回弹「工作区未启动，请重新发送」；现在改为暂存 + 回执「已收到，打开后会自动处理，无需重发」。工作区就绪后自动投递（可在路由策略里关掉自动投递，改为绑定行上的「投递」按钮手动触发），也可「丢弃」。停泊队列 24h 硬过期，与出站 outbox 同口径；过期会写一条会话内可见记录。

18.8 关闭工作区的绑定管理

如果你已经把一个工作区关闭（在主界面移除/未打开），相关的随行通讯绑定不会立即丢失，但会显示「未打开」徽章，便于一眼分辨：

• 行内 「重新打开」按钮 — 一键把这个工作区重新加回主界面，恢复对话能力。
• 行内 「解绑」按钮 — 弹出确认对话框（项目内 ConfirmDialog，在设置面板之上正常显示）。点确认即立刻解绑，不再保留。

早期版本里这两个按钮在 WebView 下因为用了原生 confirm() 而失效；本版已修复。

18.9 安全

• 所有 IM 消息只在你绑定的会话和工作区内传递，不会泄露到陌生群。
• 配对码 10 分钟过期，过期后即使被截屏也无法再绑定。
• 你可以随时在 设置 → 随行通讯 中解绑某个对端，立即失效。

19. 插件与扩展

AVL Code 的能力还可以通过插件进一步扩展。

19.1 插件能做什么

• 一次性安装一组技能（skills）。
• 一次性安装一组钩子（hooks）。
• 接入一组外部工具服务（MCP server）。
• 提供专属的助手人设。
• 提供专属的工作区模板。

19.2 插件市场

设置 → 插件 面板分两层：

• 市场视图：可添加 / 切换插件源，浏览插件画廊（按分类、按已披露的能力筛选），一键 安装 / 启用 / 禁用。删除走行内二次确认（不弹模态），避免误删。
• 已装视图：列出当前账号已装插件，启停、卸载、查看版本与作者。两层之间通过面包屑返回。

19.2.1 兼容 Claude Code 插件

AVL Code 内置 CC 插件适配器，可直接消费社区 Claude Code 插件目录：

• 引用写法：github@claude-plugins-official（指向官方目录）、owner/repo 直接 git 拉取，都识别。
• 适配器把 CC 插件结构翻译成 AVL Code 原生格式，无需手工转换。

19.2.2 安装前确认弹窗

每次安装前弹确认弹窗，把以下信息一次摊开供你检视：

• 来源溯源：来自哪个市场、源代码仓库地址、版本号、作者、主页。
• 要执行的命令行：安装脚本会跑什么、装到哪。
• 能力清单：会注册哪些技能 / 钩子 / MCP server，分别需要哪些权限。
• 签名信息：是否有签名、签名是否通过校验。

看清楚再点「安装」，避免装到来路不明的插件。

来源可信一眼可辨：插件卡片的作者旁有来源可信盾牌（与插件商店同款标识），直观标示来源可信状态；模型提供方条目复用其所属插件的品牌图标，「插件」徽标为中性描边样式。

导入身份以签名清单为准：从 zip 导入插件时，插件名取自签名清单（manifest）而非 zip 文件名，文件名无法冒充插件身份；导入与既有插件同名的 zip 时不再静默复用旧目录，避免「导入成功」但内容未更新的假象。

19.2.3 检查更新与升级

插件装完之后也能跟上上游更新：

• 市场可回源刷新：已添加的市场源支持重新拉取（git 源重拉、本地源重新解析），刷新后市场视图会露出各插件的已装版本与「可升级」标记，可从市场行或卡片直接升级。
• 已安装插件「检查更新」：插件列表头提供「检查更新」入口，反查已装插件有没有更新；有更新的插件卡片显示「有更新」徽章与升级按钮。
• 升级更稳妥：版本比对以 semver 为主、差异兜底；升级前先清空插件目录避免旧组件残留；市场缓存采用原子换盘，失败可安全回退到旧缓存。
• 真实进度看得见：市场的安装 / 升级 / 预览 / 更新 / 添加操作显示行内进度条，解析 git clone 的真实下载进度实时反馈；更新 / 检查更新按钮为原地旋转的刷新图标。

19.2.4 开箱即用的典型插件目录

仓库自带 22 个典型插件，装上即用（均带官方品牌图标与签名清单）：

• 15 家模型提供方：DeepSeek、OpenRouter、OpenCode Zen、OpenCode Go、MiniMax、小米 MiMo（按量 / Token Plan 两款）、智谱、月之暗面 Kimi、通义千问、豆包、Ollama（本地）、硅基流动、阶跃星辰 StepFun，以及一个 OpenAI 兼容模板（照着改 Base URL / Key 即可接入任意兼容端点）。装上插件 → 填 Key → 即可在模型页选用，术语统一为「模型提供方」。
• 知乎工具集：接官方开放平台 API 的站内搜索 / 全网搜索 / 热榜工具。
• 4 个原生能力示范（安全分析主题）：工具集（sec-toolkit）、审计钩子（audit-guard-hooks）、通知通道（notify-channels）、安全分析技能（sec-analysis-skills），分别演示 tools / hooks / channels / skills 四类能力怎么写。
• 2 个 Claude Code 兼容格式示范：安全专家人设（agents + commands）、DevOps 套件（mcp + hooks），演示 CC 插件结构如何被适配器直接消费。

19.2.5 在对话里管理插件（插件管理工具组）

助手可以直接在对话里完成插件生命周期，对应四个工具：

安装 / 卸载等写入类操作走两步确认：第一步返回 dry_run 预览（能力清单、MCP 真实命令行、签名状态、来源溯源），你同意后才真正落地 — 与外部服务接入的确认闸同款。装 / 卸完成后插件面板实时刷新，无需手动同步。

19.3 启停

每个插件可在 设置 → 插件 中独立启停，停用后只是不再生效，配置仍然保留，可一键恢复。

19.3.1 工作区默认生效

全局安装的插件在每个工作区默认启用（可按需关掉）；通过市场装完即在当前工作区自动激活，不再出现「装了不生效」的歧义。

19.4 团队插件市场（可选）

组织管理员可以搭建内部插件市场，统一审核与分发。普通用户在 设置 → 插件 中切换市场源即可看到团队专属插件。

19.5 插件的技能 / 钩子真正生效

• 插件携带的技能会随安装复制进工作区，可通过 skill.list 看到、skill.invoke 调用；切换工作区、重开工作区、注册表重建之后依然在。
• 插件携带的 hook 脚本随安装就位，hook 根目录环境变量（CLAUDE_PLUGIN_ROOT）正确指向插件目录，SessionStart / 命中工具时的 hook 都能稳定触发。

19.6 产品公告

AVL Code 会展示官方公告：

• 未打开工作区时：在顶部以横幅形式显示。
• 打开工作区后：以全宽信息条的形式紧贴输入框上方显示。
• 点击横幅 / 信息条弹出详情层，普通公告与提醒按颜色区分。
• 支持逐条标记已读或一次性全部已读；已读状态本地记忆，不会反复打扰。

19.7 用户反馈

新增「意见反馈」入口，三处都能进：

• 设置 → 反馈 tab — 只展示「我的反馈」列表；标题右侧「新建反馈」按钮弹窗提交（在设置里打开不会自动截窗体）
• 顶部全局入口（图标为 ✉ 与问号组合）— 自动截当前窗口作附件
• Header 命令面板（Cmd/Ctrl+K）

填写：类别、内容、联系方式。登录后实名提交，未登录可匿名提交。

附件：

• 默认自动截取当前窗口作为附件，方便描述问题。可在 设置 → 反馈 → 提交反馈前自动截当前窗口 开关里关掉（默认开启；存量配置自动补开启）。关掉后从顶部喇叭入口打开反馈也只是空附件的弹窗。
• 也可加入自己的文件、会话导出、诊断报告。
• 每个附件自动预检大小：超限的自动跳过、不阻断提交。
• ≤ 1 MiB 的附件自动计算 SM3 摘要做去重，相同内容不会重复上传。
• 非图片附件（日志 / 文档 / 诊断报告等）会用口令为 infected 的加密 zip 包装后上传，避免被中间扫描误杀（与业界恶意样本传输惯例一致）。

提交过程：

• 提交时显示实时上传进度条。
• 网络抖动 / 服务端短暂不可用时指数退避自动重试；失败给出真实原因（不是笼统报错），并提供「重试 / 放弃」两个选项。
• 纯文字反馈正常提交：不带附件时不再多发空的附件字段，服务端不会再拒收。

「我的反馈」：查看每条反馈的处理状态与客服回复。

20. 全局设置

设置面板按 6 个分组组织（从「账号 / 桌面 / 服务」3 组重组而来 — 消化了过载的「服务」筐，每组最多 6 项）：

每一项的具体作用见对应章节。Sidebar 自动按组渲染，零组件改动。

21. 主题与外观

主题三档：system / light / dark。入口在 设置 → 通用 或当前工作区面板底部；Header 右上的快捷菜单把主题、布局（侧边栏 / 顶部标签页，见 §4.8）、「信息量」（消息密度，见 §5.5.0）与「语言」（滑块上显示为 简 / 繁 / EN，悬停可见完整语言名）四个滑块集中在一处，外观相关的高频切换不必进设置页。语言切换即时生效并保存，与 设置 → 通用 → 语言 同源（设置页按语言本名列出：简体中文 / 繁體中文 / English）。

• 浅色：纯灰阶，内容工作区清爽风格。
• 深色：高对比度配色，长时间使用更友好。
• 过渡动效：方向感知圆形涟漪过渡 — 从被点击的开关位置扩散到全屏。
• 自适应资源：图标与界面装饰会跟随主题自动切换。

如果你希望强制单一主题（例如团队规范），可在 设置 → 通用 中锁定。

首屏主题不再闪：之前主题预加载脚本被内容安全策略（CSP）拦掉，启动一瞬间会先以默认主题闪一下再切到你设定的主题；本版把预加载脚本抽到独立外部文件、CSP 放行，首屏即按设定主题渲染，不再闪烁。

Linux 切主题不再白屏冻死：部分 Linux 环境（如 Fedora 44 的 WebKitGTK）下切换深浅色主题会白屏卡死；本版针对该环境关闭主题切换的过渡动画，切换恢复正常。

22. 系统托盘与开机自启

22.1 最小化到托盘

设置 → 通用 → 最小化到系统托盘。开启后关窗 (⌘W / Alt+F4) 不再退出，而是隐藏到托盘并保留后台进程；托盘菜单提供：

• 显示窗口
• 设置
• 检查更新
• 退出

在 macOS 上首次开关托盘后可能提示"需重启生效"，按提示重启即可。

22.1.1 退出前的二次确认

有事情没做完时，退出会先问一句，避免辛苦跑了一半的工作白丢。四条退出途径都受这道确认保护：标题栏关闭按钮 / ⌘W、托盘菜单「退出」、⌘Q 与应用菜单。没有未完成的事情时直接退出，不会打扰你。

会被拦下的 9 种情况：

确认框提供三个选择：仍要退出、停止全部并退出、回到工作区（按拦下的原因给出对应说法）；点击遮罩等同取消。

22.2 开机自启

设置 → 通用 → 开机自启。开启后系统启动时会静默把 AVL Code 拉起到托盘，无需手动启动应用。

22.3 静默模式

托盘 + 自启同时启用时，AVL Code 默认走静默启动 — 不会弹出主窗口，仅在托盘里出现。需要主窗口时点击托盘图标即可。

22.4 记住窗口大小

设置 → 通用 → 记住窗口状态（默认开启）。开启时记住并还原你上次的窗口尺寸 / 最大化状态；关闭后启动一律用按屏幕自适应的默认尺寸并居中，退出也不再回写 — 「既不记录也不恢复」。存量配置自动补默认开启。

高分屏 / 缩放屏（如 1080p 开 125% / 150% 缩放）下，启动时会按当前屏幕可用区域自动收缩默认尺寸（高 ×0.90 / 宽 ×0.95）并居中；换到更小的屏时记忆尺寸也会被当前屏兜住，不跑出屏外。大屏仍保持 1400×900。

23. 快捷键与命令

23.1 桌面端键盘快捷键

当前版本仅绑定了少量快捷键，多数操作以界面按钮、右键菜单或命令面板（输入 /）触发。

23.1.1 命令面板（Cmd / Ctrl + K）

Header 顶部搜索框就是命令面板。按 Cmd+K（macOS）/ Ctrl+K 打开，可在一个搜索框里同时检索：

行为细节：

• 进入设置页时搜索自动收窄为只搜设置项，placeholder 文案与命令面板同步切换。菜单「视图 → 命令面板」是全量入口。
• 单行结果命中词高亮；标题过长时智能缩略 — 无命中走"中间省略"，有命中则围绕命中词开窗。
• ↑ / ↓ 选择，↵ 执行，Esc 关闭。

23.2 输入框命令

23.3 IM 端命令

详见第 18 章「随行通讯」。

24. 升级、备份与同步

24.1 升级

• 应用内升级（推荐）：托盘菜单 → 检查更新 → 一键替换。升级包带签名校验，验签失败会自动回滚。
• 手动升级：从官网下载页下载新版本构建，直接替换旧的运行（免安装），配置目录不动。
• 升级缓存目录干净化：升级时的临时安装包改放到隐藏的 cache 目录，不再在可见目录里留中间文件；升级失败 / 中断遗留的孤儿暂存文件会被自动清理，不需要你手动收拾。
• 升级弹窗的「发布说明」直接取自 RELEASE_NOTES.md（不再用 git 日志），只呈现面向用户的版本说明，不泄露提交元数据。
• 定期纳入组件安全更新：随版本升级第三方依赖（如 Go 的 x/crypto / x/net、MCP SDK 等）以纳入安全修复。

24.1.1 配置目录迁移到 avlcode（自动）

内部标识由 zcode 统一迁移为 avlcode：全局配置目录（如 ~/.config/avlcode/）、工作区内的 .avlcode 目录、AVLCODE_… 环境变量，以及相关 YAML 与 frontmatter 字段，都改用 avlcode 命名（SSH 远程工作区一并处理）。

• 自动且安全：在启动和打开工作区时自动迁移，过程有 toast 提示，不影响既有数据。
• 保留旧名双读回退：迁移期间仍能读到旧的 zcode / .zcode / ZCODE_…，老配置不会突然失效。
• 界面与对外输出里残留的「zCode」字样统一为「AVL Code」。
• 你一般无需任何操作；若曾在脚本里写死 .zcode/ 路径或 ZCODE_… 变量，建议改用 .avlcode/ / AVLCODE_…。

24.2 备份 v2 — .zbk 加密备份

设置 → 数据 Tab 内置三个对话框：创建备份 / 恢复 / 历史快照。

• .zbk 加密备份文件（AES-GCM）— 覆盖 14 类应用数据（含 plugins/ / ~/.avlcode/trust/ / 可选的 hook-outputs/）。
• 创建备份：选择类别 → 输入密码 → 落地 .zbk 文件。plugins / trust 默认勾选，跨机迁移不用重装；hook-outputs 默认不勾选，仅按需带走调试历史。
• 恢复：选择 .zbk → 输入密码 → 预览要还原的类别 → 确认。

旧 / 新备份双向兼容，.zbk 格式版本号不变。

24.3 历史快照（自动）

所有"破坏性操作"（单类清理 / 批量清理 / 全量重置）触发前都会自动落一个清理前快照（命名形如 auto-clean-<ts> 或 auto-fullreset-<ts>）。

• 历史快照面板支持深链定位：从某条破坏性操作的成功 toast 直接跳到对应快照行。
• 每个快照行都有「就近回滚」按钮，几乎不留痕。

24.4 存储占用与按类清理

设置 → 数据 → 存储占用 视图按 14 个备份类别 + 6 项非备份项（缓存 / 快照 / 元数据）展示真实占盘大小。聚合条与 du 字节级对齐：

• 单项 / 批量清理 — 含敏感数据的类别（plugins / providers / trust 等）操作前自动落 auto-clean-<ts> 快照可一键回滚。
• 「全量重置」会深度清 14 类应用数据 + 重置默认配置 + 自动落 auto-fullreset-<ts> 快照。

24.4.1 工作区菜单的「清除工作区全部文件」

工作区菜单的「清除数据」入口下新增了 「清除工作区全部文件」 危险选项 — 不仅删 AVL Code 自管的元数据（会话、todo、设置等），还真的把工作区目录里的全部文件清空。和其它破坏性按钮一样，inline 倒计时 + 武装确认，不可撤销，请确认这是一个临时 / 可重建的工作区再用。

24.5 破坏性操作的 inline 倒计时

所有破坏性按钮不再弹原生 confirm 弹窗，而是 GitHub 风格的"武装 → 倒计时 → 确认"两步式：

1. 第一次点击 — 按钮变红 + 显示 3 秒（全量重置 5 秒）倒计时。
2. 第二次点击 — 才真正执行。

全局只允许一个按钮处于武装态（点新的会自动解除旧的），点击空白处或 Esc 取消。成功反馈就近显示在原行 — ✓ 已释放 N · 回滚 · 关闭，不再弹全局 Toast。

设置内删除统一行内确认：设置面板里删技能 / 插件 / 账号 / Provider / 例行程序等的删除按钮全部统一为「就地行内二次确认」。修了之前点了删除毫无反应的根因 — 系统原生确认弹窗被应用内嵌的网页视图静默吞掉、直接当成「取消」；现在点了就有反馈，删得掉。

24.6 同步（实验性）

AVL Code 提供基于云端的数据同步能力（实验性）：在 设置 → 数据 → 同步 中开启后，登录账号下的多台设备可自动同步工作区与会话。同步只发生在你登录账号关联的设备之间。

24.7 数据脱敏

设置 → 数据脱敏 是一个外发场景的数据保护引擎 — 在内容离开本机之前对敏感字段自动做替换 / 遮掩。默认关闭（opt-in），配置落到 ~/.config/avlcode/redaction.yaml，主程序与子进程共用同一规则编译。

作用范围（按场景独立开关）：

规则类型：

内置 secrets 预设（presets.secrets，可选开）— 高置信度、低误报的常见凭据格式：

• AWS Access Key（AKIA…）
• GitHub PAT（ghp_…） / 其它 Token（gho_… / ghs_… / ghu_…）
• Slack Token（xox[baprs]-…）
• Stripe Live Key（sk_live_…）
• GCP API Key（AIza…）
• OpenAI Key（sk-…）
• PEM 私钥整块（-----BEGIN … PRIVATE KEY----- 到 -----END …，跨行）

命中反馈：触发脱敏的导出 / 写盘会弹一条 toast，告诉你命中了多少条、哪条规则，便于审计；每条替换都带规则 Label，可追溯不漏值。

导出脱敏覆盖代码块行首 IP 与嵌套 JSON：会话导出的脱敏改为对解码后的 JSON 文本值套用规则，修复了代码块中受 JSON 转义影响、行首 IP 未被遮掩漏脱敏的问题；并会递归下钻嵌套的 JSON 结构，覆盖工具调用的参数与结果里的敏感信息，避免深层字段被遗漏。

规则总开关关闭时所有场景一律放行原文，避免「开了之后不知道哪里少东西」的困惑；建议先在「常规」组的 redaction.yaml 写好规则、跑一遍小规模导出确认效果再上正式数据。

25. 卸载与数据清理

• 删除应用本体：macOS 拖到废纸篓；Windows 控制面板卸载；Linux 用包管理器移除或删除 AppImage。
• 彻底清理数据：设置 → 数据 → 数据目录 → 打开，关闭应用后删除整目录。会同时丢弃所有会话、技能、凭证，谨慎。
• 关闭自启：卸载前先在 设置 → 通用 中关闭开机自启，避免残留启动项。
• 撤销共享额度：登出账号即可使本机无法再使用共享额度；账号本身仍在管理后台保留。

26. 故障排查与常见问题

26.1 启动相关

• 应用无法启动：先看日志（设置 → 数据 → 打开日志目录；或在卸载并重装后再次尝试）。
• 应用启动后白屏：通常是系统自带网页视图组件版本过旧，参考第 2 章系统要求升级。

26.2 登录相关

• SSO 浏览器回跳后桌面端没有反应：通常是浏览器代理 / VPN 拦截了本地回调端口，关闭代理后重试。
• 登录后没有可用模型：设置 → 模型 中点「刷新」；或重新登录。

26.3 会话相关

• 会话突然不响应：点击 停止 按钮，再发新消息即可恢复。
• 会话历史似乎被截断：可能触发了历史折叠；点击折叠摘要展开即可看到原文。
• 错误："服务未就绪"：等待 30 秒；持续未恢复请打开 设置 → Hooks → 错误抽屉 查看具体原因。

26.4 工具相关

• 工具调用一直在转圈：通常是后台执行任务被模型调度但未拉取输出；点开任务卡片查看实时日志。
• 某工具被拒绝：检查智能体管理器 →「配置工具」中该工具在当前模式下的权限设置。
• 外部服务连不上：检查接入地址与凭证；查看错误抽屉里服务端原始返回。

26.5 安全分析相关

• 样本扫描返回空结果：默认安装可能未包含完整规则集，请联系内部分发渠道获取完整版本。
• 反编译耗时长：反编译涉及模型调用，复杂样本可能耗时数十秒甚至更久；可以让助手把任务转后台。

26.6 随行通讯相关

• 微信扫码后桌面端没反应：通讯通道初始化最长 30 秒，再次刷新二维码重试。
• 配对码失败：10 分钟过期；重新生成。
• 审批卡片在微信里没出现：检查通道是否还在线（设置中可看连接状态）。

26.7 性能相关

• CPU 占用高：若你启用了多个后台任务，注意并发上限；可在 设置 → Hooks 中查看在跑任务列表。
• 磁盘占用大：通常是会话历史或样本目录大；设置 → 数据 → 数据目录 中可看到具体大小，按需归档旧会话。

26.7.1 模型调用错误的精准提示

服务端返回的各类错误现在能精准归类，提示直接告诉你该怎么办，不再一律给笼统或误导性的信息：

未配置模型发送不再卡住：删除了正在使用的模型供应商后直接发送，过去会卡住；现改为在消息流内行内确认，引导你切换到可用模型再发。启动失败时也会复位运行状态，不再一直停在「运行中」。

26.7.2 macOS App Translocation 升级失败

如果你没把应用拖进 应用程序，直接从「下载」或「桌面」双击运行，点检查更新会被 macOS 的 App Translocation 机制锁住（应用被放进只读临时镜像运行）。本版已识别这种「只读位置」并快速失败给出明确引导：

「请退出应用 → 把它拖进『应用程序』文件夹 → 重新打开 → 再检查更新」

其它只读卷 / 受管目录等写盘失败也统一兜底成同样的友好提示。

26.7.2.5 Windows 后台进程稳定性

Windows 上的后台服务（zWorkspace / zMCP）做了系统性根治：

• 进程存活探测改用系统级句柄等待，不再把活着的子进程误判为已退出（mac / Linux 行为不变）。修了"每次重开工作区都启动一个、旧的变成孤儿进程"。
• GUI 程序下子进程 stderr 采集修复，启动失败诊断报告里的「原始错误」恢复有内容，根因判断更准。
• MCP 配置读写不再丢字段：之前在「配置工具」面板里增删 / 启停某个 MCP 后端时，保存可能意外把其它 stdio 后端的启动命令抹掉，导致下次 zMCP 因「缺命令」整个挂掉。
• 单后端故障不再拖垮整体：某个后端结构错误 / 连不上 / 被禁用时，zMCP 仍能起，坏的那个跳过并告警，其余照常可用。
• 后端连接异步化 + 有界重试：电脑重启 / 网络未就绪时，慢 / 不可达后端不再阻塞整个网关启动；后端在后台并发探活、有界次数重试，网络好了自动补连上。修了「重启后某个远程或局域网后端连不上就把整个工具网关拖垮、工具全用不了」。
• 应用退出兜底：用 OS 级进程组绑定，App 崩溃 / 强杀 / 升级时连带清理整棵进程树；子进程侧改用更可靠的父进程退出监听，不再残留孤儿进程。
• zAgent 崩溃日志完整保留：后台对话进程（zAgent）意外崩溃时捕获原生异常并把崩溃前的 stderr 完整保留，不再悄无声息退出（如「退出码 2」这类难查的情况）。日志齐了，疑难问题更快定位。写入人设或向子代理喂送数据遇到管道中断（broken pipe）时，也会上报 zAgent 的真实退出原因，而不是笼统的症状文案。

26.7.2.6 试用 / 授权过期锁界面可直接退出

试用过期 / 授权失效的全屏锁定界面底部常驻「退出应用」按钮 — 此前点关闭只是隐藏到托盘（等于没退出），现在任何状态都能干净退出进程。界面里的官网 / 主页链接为 avlcode.cn。

26.7.3 后台工作区服务启动失败自动诊断

后台工作区服务（zMCP）启动失败时，AVL Code 会在本机自动采集诊断信息（自连端口对比、进程存活探测等），直接在错误抽屉里给出根因结论 + 建议动作，无需任何手动操作。

• 同时落一份诊断报告文件（最多保留最近 20 份）。
• 「未找到 zWorkspace / zAgent 二进制」根因上浮：若启动时定位不到内置的 zWorkspace / zAgent 组件，不再只提示「未找到二进制」，而是把嵌入组件释放失败的真实根因一并上报，并附按平台区分的排查建议。（相关的：内置组件解压上限由 64 MiB 提升到 256 MiB，修复部分 Intel 机型因组件体积增长被安全护栏误拦、释放失败导致启动失败的问题。）
• 全程零操作、不外发数据。
• 这份诊断报告可一键作为「意见反馈」的附件带给我们，加速排查。

26.7.4 在线文档入口

随时需要查文档：

• 侧边栏「帮助」按钮：一键用系统默认浏览器打开 avlcode.cn/docs.html。
• macOS 帮助菜单 → 在线文档：同一目标地址，紧跟在「命令列表」后面。

26.8 日志

应用日志位置可在 设置 → 数据 → 打开日志目录 一键访问，崩溃栈也会同步出现在错误抽屉里，无需打开终端。

27. 最佳实践

27.1 总是先 plan，再 execute

筹划阶段的"只读"约束能防止 AI 急着改代码而搞错前提。即使是小任务，进入 plan → 让助手用 5 分钟列计划 → 退出筹划进入执行 — 整体效率反而更高。

27.2 把人设交给团队管

把助手的核心提示词放进团队仓库统一维护。新成员加入时即可自动获得团队共识的"AI 风格"。

27.3 高敏工具一律走"询问"

涉及生产环境、共享密钥、删除文件、推送代码的工具，建议设为询问模式，并把白名单粒度设为"同工具同参数"，确保每一次都被人确认。

27.4 善用历史折叠

不要因为对话太长就开新会话 — 折叠后早期上下文仍可展开，比"新会话从零开始"保留更多隐性知识。

27.5 并行不等于更快

后台子任务适合并行获取信息（同时读多个文件 / 跑多个搜索），但不适合并行修改同一文件 — 会有冲突。把"读"并行化、把"写"串行化。

27.6 用随行通讯做长任务

长测试 / 长扫描可以让助手转后台，再让它通过随行通讯把进度推到手机上 — 你可以离开座位继续做别的事。

27.7 用"有如神助"做对照

被某个助手绕进去的时候，临时用"有如神助"换一位风格完全不同的助手做"刺杀型 review"，往往能找出主线助手的盲点。

28. 安全与隐私

AVL Code 在设计上把用户数据当作"敏感数据"处理。

28.1 数据落地

• 所有会话历史保存在本地，不上传到任何第三方。
• 仅在你显式调用模型时，对应消息内容才会按所选模型供应商的协议传输到模型方。
• 反编译能力会按需向反编译模型发送相关反汇编片段；只有你主动调用相关工具才会触发。

28.2 凭证管理

• 登录凭证、模型 API Key、外部服务凭证都以受保护方式存储在本机。
• 模型供应商的 API Key 与外部服务凭证不会随对话内容上传到模型；只有调用对应工具时才作为头部送给对方服务。

28.3 样本目录的特殊保护

工作区下名为 samples/ 的子目录被强制视为"不可执行"区，任何执行类工具调用都会被无条件拒绝，这一策略不可解除。

28.4 审计

所有工具调用、所有审批结果、所有计划修改都以独立卡片记录在会话流中，可作为完整审计材料。

28.5 网络访问

• AVL Code 启动后会访问账号服务获取登录状态与共享额度。
• 访问模型供应商时按所选模型配置发起请求。
• 启用 SBOM 在线审计 / 同步时才会访问 OSV 漏洞库（api.osv.dev、OSV dump 存储桶）与 CISA KEV 名录；隔离网可改指内部镜像或走离线导入，全程不联网。
• 不会主动联网做用户行为埋点。

28.6 升级安全

升级包带签名校验，验签失败会自动回滚，避免被中间人替换。

29. 附录 A：术语表

30. 附录 B：设置速查

设置面板按 6 个分组组织（详见第 20 章）：

31. 附录 C：内置命令清单

31.1 输入框 Slash 命令

31.2 IM Slash 命令

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