AVL Code 用户手册

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

产品简介
安装、启动与系统要求
账号、用量与计费
工作区
会话
五种工作模式
助手人设
模型与参数
工具体系总览
智能编程工具
安全分析工具
外部工具服务接入
工具权限与审批
技能（Skill）系统
子任务与后台执行
计划与待办
历史折叠（Compact）
随行通讯
插件与扩展
全局设置
主题与外观
系统托盘与开机自启
快捷键与命令
升级、备份与同步
卸载与数据清理
故障排查与常见问题
最佳实践
安全与隐私
附录 A：术语表
附录 B：设置速查
附录 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 系统要求

macOS：12.0 Monterey 及以上，Apple Silicon 与 Intel 双架构都支持。
Windows：10 (1809) 及以上，64 位，需启用系统自带的网页视图组件。
Linux：Ubuntu 22.04 / Debian 12 / CentOS Stream 9 等较新发行版，64 位 x86 或 arm64。

硬件建议：

内存：8 GB 起步，16 GB 推荐。
磁盘：剩余 1 GB 以上（存放本地会话、技能与日志）。
网络：可访问账号服务与所选模型供应商的接口；首次启动需有联网用以获取模型列表。

2.2 安装

从内部分发渠道获取对应平台的安装包，按平台习惯安装：

macOS：AVL-Code-darwin-{arm64,amd64}.dmg，拖入 应用程序 即可。
Windows：AVL-Code-windows-amd64-installer.exe，双击运行向导。
Linux：AVL-Code-linux-{amd64,arm64}.AppImage 或 .deb，加执行权限运行，或包管理器安装。

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

2.3 首次启动

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

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

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

2.4 命令行入口（高阶）

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

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

命令	用途
`AVL-Code tui`	在终端里启动 AVL Code 的 TUI 版本，与桌面版共享同一份会话
`AVL-Code zagent-tui`	直接启动批处理对话 TUI，适合脚本化驱动

3. 账号、用量与计费

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

3.1 登录方式

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

方式	流程
手机号验证码（默认，最快）	输入手机号 → 收短信验证码 → 输入验证码登录。没有账号会自动注册，无需单独走注册流程。验证码 60 秒重发倒计时；触发风控时自动切出图形验证码（点图可刷新）
用户名 + 密码	设置 → 账号 → 密码登录 tab → 输入账号密码 → 提交
SSO 单点登录	设置 → 账号 → SSO 登录，自动打开浏览器完成认证，回跳后桌面端自动接收凭证

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

3.2 共享额度与个人额度

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

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

3.3 用量监控

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

24 小时
7 天
30 天

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

3.4 凭证过期

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

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

3.4.1 兑换码与代金券

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

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

3.5 退出登录

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

4. 工作区

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

4.1 创建工作区

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

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

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 加密落盘，并与本机绑定；首次连接按「记住首次指纹」（accept-new）校验远端主机身份。

远端深度集成：

文件变更面板走远端 git（远端没装 git 时明确隐藏，不再报错堆红框）。
**技能（Skills）/ 插件（Plugins）/ 钩子（Hooks）**在 SSH 工作区全部可用：技能从远端读取、插件人设写到远端 .zcode/、hook 命令在远端执行。
文件威胁扫描（VirusTotal AI）对远端文件同样生效（经 SFTP 取字节后扫描）。
fs.grep 在 SSH 下走远端系统 grep 提速。
计划 / 结果草稿等文件统一落远端，不再本地 / 远端两边脑裂。

安全收口：

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

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

4.5 同时活跃工作区上限 7

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

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

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

4.6 最近工作区面板

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

搜索框始终显示，列表自适应滚动；命中词高亮。
置顶区 与 其他区 各自独立滚动，置顶项不会随下方列表滚动消失。
支持多选 + 顶部批量操作栏（批量删除 / 批量打开）。
删除走 inline 倒计时（武装-倒计时-确认两步式），不再弹原生 confirm。

4.7 工作区粒度的设置

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

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

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

5. 会话

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

5.1 持久化

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

5.2 会话操作

新建：会话标签栏 → 新建，或快捷键 ⌘N / Ctrl+N。同一个工作区内最多只保留一条空白草稿：反复点 +、按 ⌘N、发 /new 都复用同一条，未发出第一条消息前不会进侧栏，避免堆出一串"新会话 1 / 2 / 3 …"幽灵草稿。
切换：点击标签页，或在微信里 /s <短id>，或在 命令面板（Cmd+K） 里搜会话标题。
重命名：标签页右键 → 重命名。
智能命名：未被手动改过名的会话，收到第一条 AI 回复后会自动让 LLM 起一个简短标题（默认开启，可在 设置 → 上下文 关掉）；手动改过名的会话永久豁免，不再被自动覆盖。重命名对话框里也有「智能命名」按钮，可随时点一下重新建议。
归档：标签页右键 → 归档。归档后从主列表消失，可在 会话档案 里恢复。
导出：标签页右键 → 导出，支持 Markdown / 纯文本，方便归档或分享。
复制为新会话：以本会话为起点新建分支，原会话不变。

5.2.1 用户消息时间戳

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

格式	例
相对时间	`刚才`、`3 分钟前`
会话内偏移	`+1m23s`（相对首条消息）
绝对时间	`14:32`

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

5.3 消息组成

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

用户消息
助手回复（流式渲染，可中途打断）
工具调用（可折叠卡片，包含入参摘要、耗时、结果）
计划 / 待办更新（结构化展示，可独立修改）
审批记录（成功 / 拒绝 / 挂起 / 由微信回写）

5.4 消息流控制

助手运行中，输入框右侧的发送键变成停止按钮 — 按下会同步终止主助手与所有派生子任务。
中途如果你想到补充内容，直接按 Enter 入队 — 这条会在当前自然结束后合并发出，不会打断当前回合。
助手输出的工具调用卡片可以单独点开 / 折叠 / 复制结果。

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

Token 数变化加滚动动效：流式过来的 token 计数不再硬跳，约 0.4 秒平滑插值到目标值；变化期间数字短暂变品牌蓝并微微上抬。系统设置「减少动画」时自动跳变不抖。
耗时按分级显示：60 秒以内仍是 5s / 12s 这样的简短表达；超过 1 分钟自动升级为 1m 30s；超过 1 小时升级为 2h 15m 30s。短任务零变化，只在长任务时升级单位。

5.6 滚动与跟随

生成期间默认自动跟随底部。
一旦你向上滚动查看历史，「跳转底部」按钮出现 = 视为你主动滚走，自动跟随停止。
你点「跳转底部」或自己手动回到底部时，跟随自然恢复。
已堵住滚轮事件与流式 chunk 同帧的微秒级竞态，不会再被反复打断。

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

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

入口	权限
附加目录（只读）	AI 可读取该目录下文件、列举、搜索；不能修改
附加目录（读写）	在只读基础上额外允许写 / 删 / 创建

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

附加前有确认对话框，明确说明授予的是只读还是读写权限；附加后输入框上方出现**「附加路径」条**展示当前会话的附加目录，可随时移除。

作用域与安全：

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

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

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

工作区内的文件路径 → 点开后用系统文件管理器（Finder / 资源管理器）定位并选中该文件。
外部链接 → 用默认浏览器打开。
反引号内联代码里的路径（如 `src/main.go`）同样可点，与普通链接共用一套识别与定位逻辑；普通内联代码不受影响。
点击后就地弹出轻量浮动小工具条（主动作「查看 / 打开」+「复制」），非模态 — 点别处 / 滚动 / 按 Esc 即关。
工具条用浏览器 Popover API 渲染在顶层，从「关于」「发布说明」「更新」等弹窗里点链接也不会被遮挡。
路径识别更精准：只把带常见扩展名的字符串（如 src/main.go、README.md）认作可点路径；纯目录、无扩展名 / 未知扩展名的片段（如 a/b、/etc/hosts）不再被误标为可点。
安全：危险协议（非 http(s)）链接被拦截不放行；文件定位有工作区纵深校验，不会越界到工作区外。

5.8 输入框历史回溯

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

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

5.9 跨端接管

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

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

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

6. 五种工作模式

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

6.1 模式总览

模式	默认行为	典型用途
auto（自动）	一站式回答，自由调用工具	简单任务、快速问答
plan（筹划）	只读：禁写文件 / 禁执行命令	设计方案、阅读代码、风险评估
prepare（准备）	整理需求、准备依赖与环境	项目初始化、清单生成
execute（执行）	写代码、跑命令、提交变更	真正干活
assess（评估）	只读：阅读结果、给出结论	验收、复盘、不再修改代码

plan 与 assess 是真正的只读模式：写文件、编辑、执行命令类工具被强制禁用（fs.write / fs.patch / fs.exec / fs.exec.start / fs.exec.kill / git.init），即使在 设置 → Hooks 中放行也不生效。这是为了让"思考阶段"与"复盘阶段"保持纯净 — 测试运行请放在 execute 阶段完成。

6.2 切换模式

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

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

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 协议

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

类型	适用场景
AVL Delta 兼容	内置 AVL-Zero 默认就用它；每轮只把"本轮新增内容"发给服务端，稳定历史不重复回传，配合前缀缓存治理进一步省流量、省 token、提速
OpenAI（兼容）	OpenAI 官方接口、阿里云通义、火山方舟、Kimi、Moonshot、DeepSeek、自建 OpenAI 兼容代理等
Anthropic	Claude 官方接口、Anthropic 兼容代理 — 用 `x-api-key` + `anthropic-version` 头，支持工具调用、流式、思考链（extended thinking）、重试

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

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

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

8.2 参数

每个模型可调参数：

Temperature：温度，0–1，控制随机性。
Top-P：核采样上限，0–1。
最大输出 Token：单次回复长度上限。
流式：是否流式渲染（推荐开启）。

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

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

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

作用域	行为
全局一致（默认）	所有会话共用一个「当前模型」，升级零感知
跟随会话	每个会话各自记住自己的模型，切到哪个会话就切回该会话上次用的模型；新建会话时快照当前全局选择作为起点，之后独立可改

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

复制会话 / .zsession 导入导出都自动带上模型字段，跨设备 / 跨人交接不丢。

8.2.2 未开启模型默认折叠

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

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

8.3 多供应商兜底

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

8.4 上下文长度与折叠

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

9. 工具体系总览

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

9.1 三类工具

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

9.2 工具开关

每个工具都可以设置为：

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

入口在 设置 → Hooks，可按工作模式独立配置。

9.3 工具命名空间

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

9.4 工具调用的可视化

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

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

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

9.5 让助手自己配置 MCP 服务

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

工具	用途
`mcp.list_servers`	列出当前所有 MCP server
`mcp.describe_server`	看某个 server 的详细配置（密钥脱敏）
`mcp.list_tools`	看某个 server 暴露的工具
`mcp.test_server`	用临时连接做真握手探活（30 秒预算），区分 `validate_args` / `connect` / `list_tools` / `ok` 四个阶段
`mcp.add_server`	新增（写类，两步制）
`mcp.remove_server`	删除（写类，两步制）
`mcp.toggle_server`	启停（写类，两步制）
`mcp.import_config`	批量导入；同时识别原生格式与 Claude Desktop 的 `{mcpServers:{...}}` 形态
`mcp.export_config`	导出当前配置（密钥脱敏）

两步制（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 操作：仓库状态查询、新建 / 切换分支、新建仓库。其它分支操作（合并、变基、推送等）由助手通过终端执行类工具完成；默认走"询问"通道，避免误推 / 误改。

10.7 网络检索（可选）

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

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

10.8 时间与上下文

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

10.9 上下文截断

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

11. 安全分析工具

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

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

11.0 把样本送进工作区

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

点击 + → 系统弹出多文件选择对话框。
选中一个或多个文件 → 自动落到当前工作区的 samples/ 子目录。
输入区上方实时显示文件名 + 进度条 + 块计数；完成 1.5 秒后自动收起，失败保留 6 秒。
完成后浮现 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 形式输出指定字节范围。

11.2 字符串与 IOC 抽取

字符串：ASCII + UTF-16LE，可设最小长度。
IOC 抽取：自动识别 IPv4 / IPv6 / 域名 / URL / 邮箱 / 哈希 / 路径等。

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 流。
流枚举：列出 PCAP 中所有 TCP / UDP / ICMP 流并赋稳定 id。
流载荷导出：把指定流的 L7 载荷 dump 到工作区路径，便于二次分析。
协议字段抽取：DNS 查询 / 应答、HTTP 请求 / 响应、TLS ClientHello SNI，以及协议级 IOC（IP 等）。

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

11.7 规则匹配

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

11.8 数据可见性

所有分析结果都直接落到对话流，可独立查看 / 复制 / 导出。AVL Code 不会把样本本体上传到任何第三方；只有反编译会按需调用反编译模型，且仅发送相关反汇编片段。

12. 外部工具服务接入

设置 → 提供商 面板支持连接任意标准协议的工具服务（例如 Notion、内部 API、私有知识库）。

12.1 添加一个外部服务

设置 → 提供商 → + 添加。
填写：
- 名称：例如 notion。
- 接入地址：服务方提供的 URL。
- 凭证：从对方平台获取的访问令牌。
启用。

12.2 工具命名空间

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

12.3 实时生效

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

12.4 异常处理

断连重试：后端断开会自动指数退避重试。
错误抽屉：错误信息会拼接服务端原始返回，便于定位是凭证过期、网络不通还是服务端故障。
就绪探测：连接建立后 AVL Code 会先做一次 ping，确保对端真正可服务再登记到工具列表。

12.5 安全

凭证以加密形式存储在本机，不会随同对话内容上传到模型。
可在 设置 → Hooks 中针对每个外部服务独立设置工具权限策略。

13. 工具权限与审批

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

13.1 三态权限

每个工具都可以设置为：

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

可按工作模式独立配置；常见做法：execute 模式启用写工具，plan 模式禁用所有写工具。

13.2 调用前审批

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

桌面端弹出审批弹窗，展示工具名、入参与影响范围。
你可以选择：
- 允许（仅本次）
- 始终允许：把"工具+参数模式"加入白名单。
- 拒绝
- 挂起（defer）：暂不决策，可由微信侧后续回写。

13.2.1 无限制模式（高级）

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

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

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

摩擦	开启后
工具批准	跳过批准弹窗（不再逐个 ask / 拒绝 / 延后），但操作仍会被审计记录
命令白名单	`fs.exec` 不再受命令白名单限制，任意命令可执行
网络访问	`web.fetch` / `web.bing` 不再过滤内网 / 环回 / 链路本地地址

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

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

13.3 白名单匹配

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

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

13.4 多端审批

并发的审批决策按 拒绝 > 挂起 > 询问 > 允许 聚合 — 任何一端拒绝即拒绝，任何一端挂起则保持挂起。

13.5 远程审批

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

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

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

13.6 审计

所有审批结果会作为独立卡片记录在会话流中，可作为完整审计材料导出。

14. 技能（Skill）系统

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

14.1 三层来源

层级	作用范围
全局	所有工作区可见
工作区	仅当前工作区可见
插件	由插件包安装提供

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

14.2 双轨触发

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

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 内置签名工具，可生成密钥、自签证书、对技能包整目录签名，并在加载时自动验签 — 签名失败会被拒绝执行，确保从邮箱、网盘获取的技能不会带毒。

14.6 调试

设置 → 技能 提供：

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

14.7 团队共享

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

15. 子任务与后台执行

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

15.1 派发子任务

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

15.2 前台 vs 后台

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

15.3 并发上限

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

15.3.1 阻塞等待 — TaskWait 工具

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

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

15.4 终止

在桌面端，点击输入框右侧停止按钮会同步终止主助手与所有派生子任务。
在微信侧，发送 /stop 同样会触发级联终止。

15.5 输出聚合

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

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

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

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

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

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

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

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

新建入口：

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

计划方式：

类型	行为
每天 / 工作日 / 每周某几天 + 指定时刻	到点自动触发一轮
不设计划（手动）	不自动跑；保存后立即触发一轮，按钮显示「运行一次」；之后需要时再点立即运行

时刻选择顺手：

时 / 分双列下拉（选中居中、选完分钟自动收起）
周几用圆形单字字块，附「工作日 / 周末」一键预设

统一管理：

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

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

运行行为：

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

16. 计划与待办

16.1 计划（Plan）

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

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

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

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

16.2 待办（Todo）

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

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

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

16.3 跨折叠保留

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

17. 历史折叠（Compact）

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

17.1 触发方式

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

17.2 折叠后的可见性

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

17.3 保留的结构化信息

折叠摘要中至少保留：

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

17.4 多次折叠

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

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

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

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

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

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

源头	治理
工具列表顺序	按工具名排序钉成确定顺序（之前 Go map 遍历是随机的，每轮顺序抖；治理收益最大、无条件每轮生效）
目标（goal）块 + 记忆召回	从系统提示前缀剥离，改为行尾瞬态注入（界面不可见、不落盘），只花当轮增量 token，不再牵连前缀缓存
项目指令（AGENTS.md）	特意保留在前缀 — 一次会话内稳定，留在前缀同字节重读不失效；编辑时才失效（正是期望行为）

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

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

18. 随行通讯

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

18.1 通道

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

18.2 绑定

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

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

18.3 路由策略

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

上次活跃会话
/s <短id> 显式切换的会话
/new [文本] 新建的会话
默认绑定的会话
配对码或工作区默认 fallback

18.4 内置命令

命令	用途
`/bind <code>`	绑定到工作区
`/ws <name>`	切换工作区
`/sessions`	列出最近会话
`/new [text]`	新建会话
`/s <短id>`	切到指定会话（≥4 字符前缀）
`/approve` / `/always` / `/deny <审批号>`	审批
`/stop` / `/resume`	停止 / 恢复
`/help`	帮助

18.5 行为细节

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

18.6 群协作

绑定到群以后：

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

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

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

徽标	含义
`↑ N 待发送`	出站发送失败 / 通道冷却积压的分片
`↓ N 待处理`	对端发来、工作区未打开时暂存的入站消息

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

18.8 关闭工作区的绑定管理

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

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

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

18.9 安全

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

19. 插件与扩展

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

19.1 插件能做什么

一次性安装一组技能。
接入一组外部工具服务。
提供专属的助手人设。
提供专属的工作区模板。

19.2 安装

设置 → 插件 → 浏览 → 选择插件 → 安装。安装后会自动应用到指定的工作区或全局。

19.3 启停

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

19.4 团队插件市场（可选）

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

20. 全局设置

设置面板按 tab 组织，与本手册章节大致对应：

账号：登录、用量、共享额度
模型：模型列表与默认参数
助手：五种模式各自的助手人设
工具：开关、权限策略、外部服务、白名单
技能：技能加载、签名、调试
随行通讯：通道登录、绑定、路由策略
插件：浏览 / 安装 / 启停 / 卸载
通用：主题、托盘、自启、语言
关于：版本信息、日志目录、数据目录、命令行工具入口

每一项的具体作用见对应章节。

21. 主题与外观

主题三档：system / light / dark。入口在 设置 → 通用 或当前工作区面板底部。

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

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

22. 系统托盘与开机自启

22.1 最小化到托盘

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

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

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

22.2 开机自启

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

22.3 静默模式

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

22.4 记住窗口大小

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

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

23. 快捷键与命令

23.1 桌面端键盘快捷键

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

操作	macOS	Windows / Linux
新建会话	⌘N	Ctrl+N
发送消息	⏎	Enter
换行	⇧⏎	Shift+Enter
关闭设置 / 弹窗 / 命令面板	Esc	Esc
弹出命令面板	输入 `/`	输入 `/`
命令面板 — 上 / 下选择	↑ / ↓	↑ / ↓
命令面板 — 执行	↵	Enter

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

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

分组	内容
会话	当前工作区下的所有会话（按时间倒序，过滤空白草稿）
命令	`/new` / `/clear` / `/compact` 等所有 Slash 命令
设置	18 个设置入口（账号 / 通用 / 记忆 / 插件 / Hooks / Agents / Skills / 随行通讯 / 上下文 / 工具 / …，外加「切换语言」「切换草稿纸背景」两个一键开关）
工作区 / 最近条目	双行展示，路径切分高亮

行为细节：

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

23.2 输入框命令

命令	用途
`/new`	新建会话
`/clear`	清空当前会话所有消息
`/copy`	复制最后一条 AI 回复
`/compact`	触发历史折叠
`/memorize <text>`	写入一条长期记忆
`/memory`	打开记忆宫殿面板
`/help`	列出可用命令
`/skill:<name> [args]`	触发技能

23.3 IM 端命令

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

24. 升级、备份与同步

24.1 升级

应用内升级（推荐）：托盘菜单 → 检查更新 → 一键替换。升级包带签名校验，验签失败会自动回滚。
手动升级：直接安装新版本安装包覆盖即可，配置目录不动。

24.2 备份 v2 — `.zbk` 加密备份

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

.zbk 加密备份文件（AES-GCM）— 覆盖 14 类应用数据（含 plugins/ / ~/.zcode/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.5 破坏性操作的 inline 倒计时

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

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

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

24.6 同步（实验性）

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

25. 卸载与数据清理

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

26. 故障排查与常见问题

26.1 启动相关

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

26.2 登录相关

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

26.3 会话相关

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

26.4 工具相关

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

26.5 安全分析相关

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

26.6 随行通讯相关

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

26.7 性能相关

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

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

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

HTTP	含义	提示
402	点数余额不足	「点数余额不足，前往服务页面充值」（不再当成可重试错误反复重试）
429	套餐额度用尽	「套餐额度已用尽，等配额刷新或升级套餐」（不再误判成限流）
401 / 403	鉴权失败 / 需要登录	「重新登录或重发 key」（不再让你去查配置）
—	输入超出 token 上限	归类为「上下文过长」并如实提示
503	当前模型暂无可用通道	「稍后重试或切换模型」
502 / 529 / overloaded	上游服务异常 / 繁忙	如实说明是上游问题（尤其上游鉴权失败时不再误导你去查自己的 key）
404	端点不存在	单独分类为 `endpoint_not_found_error`；提示「检查 Provider Base URL」（与"API JSON 返回的 404 模型不存在"分流）

26.7.2 macOS App Translocation 升级失败

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

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

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

26.7.3 在线文档入口

随时需要查文档：

侧边栏「帮助」按钮：一键用系统默认浏览器打开 avlcode.cn/docs。
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 启动后会访问账号服务获取登录状态与共享额度。
访问模型供应商时按所选模型配置发起请求。
不会主动联网做用户行为埋点。

28.6 升级安全

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

29. 附录 A：术语表

术语	含义
工作区（Workspace）	绑定一个本地目录与一组配置的执行单位
会话（Session）	一次连贯的对话上下文
工作模式	五种之一（auto / plan / prepare / execute / assess）
助手 / 人设（Persona）	决定 AI 风格与边界的提示词集合
工具	AI 可调用的能力（读文件、跑命令、查样本等）
技能（Skill）	提示词模板包，让助手有领域专家能力
子任务	助手派发给独立子助手执行的子工作
计划 / 待办	结构化任务清单，跨历史折叠保留
历史折叠	把早期消息压缩为摘要，原消息仍保留
审批	工具调用前的允许 / 拒绝 / 挂起决策
随行通讯	把 AI 助手接入 IM，让你在手机上指挥
共享额度	由组织统一管理 / 计费的模型调用额度

30. 附录 B：设置速查

设置面板共 11 个 tab，分 3 个分组：

分组	tab	作用
账号	账号	登录 / 用量 / 点数余额
桌面	通用	主题、托盘、开机自启、语言、字体、配置目录、检查更新
桌面	数据	存储空间、历史清空、数据目录、同步
桌面	记忆宫殿	长期记忆库
服务	提供商	LLM Provider 列表、凭证、模型刷新
服务	模型	默认模型、温度、最大 token、超时
服务	插件	插件市场 / 安装 / 启停 / 权限
服务	Hooks	工具调用前确认与自动批准
服务	Agents	助手人设与模式绑定
服务	技能	技能加载与签名
服务	随行通讯	微信 / 飞书 / 钉钉通道与配对码

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

31.1 输入框 Slash 命令

命令	用途
`/new [name]`	新建会话；可附名称
`/clear`	清空当前会话所有消息
`/copy`	复制最后一条 AI 回复
`/compact [keep N]`	触发历史折叠；可保留最近 N 条
`/memorize <text>`	写入一条长期记忆
`/memory`	打开记忆宫殿面板
`/help`	列出可用命令
`/skill:<name> [args]`	触发指定技能

31.2 IM Slash 命令

命令	用途
`/bind <code>`	绑定 IM 对端到工作区
`/ws <name>`	切换工作区
`/sessions`	列出最近会话
`/new [text]`	新建会话
`/s <短id>`	切到指定会话（≥4 字符前缀）
`/approve` / `/always` / `/deny <审批号>`	审批
`/stop` / `/resume`	停止 / 恢复
`/help`	帮助

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