AVL Code 快速上手指南

适用版本：AVL Code v0.7.28-alpha 及以上 适用平台：Windows · macOS · Linux（含银河麒麟 Kylin / 统信 UOS） 文档定位：面向初次使用 AVL Code 桌面端的工程师与安全分析师，约 30 分钟可读完并完成第一次实战对话。

目录

1. 产品简介
2. 安装与首次启动
3. 登录账号（一键开箱）
4. 工作区与会话基础
5. 五种工作模式
6. 第一次对话：实战示例
7. 调用技能（Skill）与命令
8. 工具权限与审批
9. 接入外部工具服务
10. 随行通讯：在微信里指挥助手
11. 系统托盘与开机自启
12. 主题与外观
13. 升级、卸载与故障排查
14. 附录：键盘快捷键与设置项

1. 产品简介

AVL Code 是一款由 安天 澜砥 团队推出的 AI 智能编程与安全分析桌面助手，跨平台原生分发，开箱即用。

它面向两类核心使用场景：

• 智能编程助手：基于大模型的多轮对话式开发，覆盖代码读写、终端执行、版本控制、网络检索；还能像 IDE 一样理解代码（内置 22 门语言的语言服务器：找定义 / 找引用 / 看诊断 / 跨文件 rename / quick fix），不靠正则猜；能自己跑测试 / lint / SAST + 读懂失败 + 改完再验（test.run / lint.run（golangci-lint / eslint / ruff）/ sast.run（semgrep），可开「自检门禁」每轮自动跑四类检查、红了就接着修）；Python 命令自动遵循工作区 venv / conda / poetry / pipenv；支持「筹划 / 准备 / 执行 / 评估」四阶段工作流，让 AI 像一位有自律的同事而不是一台只会回答的机器。
• 安全分析助手：内置一组只读分析工具，可对样本目录中的二进制做哈希、字符串、IOC 抽取、可执行格式解析、反汇编、规则匹配、流量元数据提取等基础分析，并通过 AVL Code 自有的反编译引擎给出 C / Java 伪代码。还可接入 VirusTotal / Google Threat Intelligence 云端威胁情报，并有「哨兵」在读写文件时自动扫描拦截（详见用户手册 §11.10）。
• 供应链体检（SBOM）：一句话就能为项目生成软件物料清单（识别 npm / Go / Python / Maven / Rust 等 16 种生态、22 种依赖清单），对照 OSV / CVE / KEV 漏洞库排查依赖里的已知漏洞（CVSS v2/v3/v4 严重度、可离线 / air-gap 使用），还能用符号级可达性分析把「装了但根本没调用」的漏洞收敛掉，输出标准 CycloneDX / SPDX / OpenVEX 等格式（详见用户手册第 11 章、参考手册第 8 章）。

与同类产品相比，AVL Code 的差异点：

• 零配置开箱：登录后自动下发共享额度，无需手动填写 API Key。
• 本地优先：所有会话保存在本地工作区，断网不丢、重启可恢复。
• 自修复 + 越用越会：遇错自动换思路自愈、供应商不可用可一键切换备用、长任务并行 fan-out；任务收尾还能自动复盘把教训沉淀下来（详见用户手册 §8.5 / §15.1.3 / §17.6.4）。
• 开工前先对目标：开场第一句话偏短或含糊时，AI 会先复述意图（目标 + 计划）请你确认再动手；说得够长够清楚就直接开干，默认开启、可关（详见用户手册 §5.4.1）。
• 全库代码问答：用 code.search / code.ask 直接问「登录逻辑在哪、怎么走的」，纯本地、零向量、命中带 文件:行 可点跳转（详见用户手册 §10.10.5）。
• 国密合规：技能扩展包采用国密签名校验，可与开源安全生态互操作。
• 随行通讯：通过微信通道在手机上远程驱动桌面助手、推送审批卡片。

2. 下载运行与首次启动

2.1 下载运行（免安装）

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

macOS 建议拖进 应用程序 再运行（否则检查更新会被 App Translocation 锁住）。首次启动会做少量本地初始化，过程透明、无需额外操作。

2.2 启动与首屏

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

• 左侧栏：工作区列表 + 登录/账号 + 设置入口。
• 中央会话区：会话标签页 + 消息流 + 输入框。
• 右侧：宽屏时消息区右上是状态栈（计划 / 待办 / 附加资料等，点开为右侧抽屉）；窄屏时这些状态条改到输入框上方。助手配置面板、审批区块等按需出现。

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

2.3 系统要求

3. 登录账号（一键开箱）

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

3.1 三种登录方式

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

3.2 登录成功后会发生什么

1. 系统自动为账号分配一份共享额度。
2. 模型列表完成异步刷新，可立即开始对话。
3. 设置 → 账号 开始展示「24 小时 / 7 天 / 30 天用量」与点数余额（前缀 §），每分钟刷新一次。

到期提醒：当登录凭证离过期不到 1 小时时，左侧栏状态点会变为琥珀色，账号面板会显示快捷「登出再登」横幅。

3.3 自有模型（可选）

想直接接 Claude 官方接口、OpenAI 兼容代理或自建大模型服务，去 设置 → 提供商 → + 添加：

• 「类型」下拉三选：AVL Delta 兼容（每轮只传增量，最省）/ OpenAI（兼容代理）/ Anthropic（x-api-key + anthropic-version 头）
• 填入接入地址 + API Key
• 启用后 AVL Code 会优先使用你自己的 Key，自动回退到共享额度作为兜底
• Delta 端点不可用时本会话一次性回退 chat/completions，对话不中断；统计面板会显示每次调用走的协议与客户端版本
• 「高级选项」可加自定义请求头（多组 key/value），适合需要额外鉴权头 / 网关标识 / 特殊版本头的代理或网关；在内置头之后应用，可覆盖 Authorization / User-Agent 等

4. 工作区与会话基础

4.1 创建第一个工作区

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

操作步骤：

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

工作区创建后，会话历史、技能扩展、随行通讯绑定等都会以该工作区为单位独立保存，互不干扰。

4.2 一键投放样本

输入框左下角的「+」按钮可调起系统多文件对话框，把所选文件直接落到当前工作区的 samples/ 子目录，落地后立即可让助手发起分析（如哈希、IOC 抽取、PE 解析等）。

• 默认上限 300 MiB，可在 设置 → 数据 → 附件 / 样本 中调整（1–4096 MiB）。
• 大文件分块上传：>4 MiB 的文件自动按 4 MiB 切片走追加写入，输入区上方显示文件名 + 进度条 + 块计数。
• 重名自动加时间戳后缀，不会静默覆盖。

4.3 在系统文件管理器中查看

工作区菜单 / Header 顶部下拉提供「在 Finder / 文件管理器中查看」入口，一键跳到本地目录（macOS 显示 Finder，Windows / Linux 显示文件管理器）。

同时活跃工作区上限 7；右键工作区图标可一键「关闭其他工作区」清场。

4.4 项目指令（AGENTS.md）

在工作区根目录放一份 AGENT.md / AGENTS.md / CLAUDE.md（按优先级取一份），里面写的项目规矩会作为「# 项目指令」块自动注入每轮系统提示。改了立即生效，不用重启。

会话菜单 / 工作区菜单都有「编辑 AGENTS.md」入口，弹出内置编辑器（编辑 / 预览切换、Cmd/Ctrl+S 保存、未保存保护、空状态给模板）。

4.4.2 SSH 远程工作区

「添加远程工作区」对话框支持 SSH 协议 — 远端零安装，能 SSH 登录就能用。支持密码 / 私钥 / 私钥+口令三种认证；凭据国密 SM4-GCM 加密落盘 + 本机绑定。文件读写、命令执行、git、技能 / 插件 / hooks 全部在远端跑。

首次连接一台新主机时会让你核对主机指纹：对话框内会列出该主机的 SHA256 密钥指纹，与服务器方提供的核对一致后点「确认继续」才会真正连接（确认前不会发送密码）。密码可以选择不记住 —— 不勾选「记住密码 / 口令」时凭据只在本次运行期间有效，应用退出即清除。

安全提示：SSH 工作区右键菜单不显示「关闭并清除数据」 — 避免误删远端真实目录；如需移除请用「移除工作区」（只清本地记录与凭据）。

4.4.3 会话附加目录

输入框「+」菜单两项：「附加目录（只读）」/「附加目录（读写）」，把工作区外的文件夹临时附加到当前会话，让 AI 读取（或读写）那里的文件。附加只对当前会话生效，重启依然有效；输入框上方「附加路径」条可随时移除。

4.5 例行程序：让 AI 按时间表自动跑

工作区侧栏「新建例行程序」可以定一条指令让 AI 每天 / 工作日 / 每周某几天在指定时刻自动跑（也支持「立即运行」按需触发）。统一管理页：设置 → 例行程序。

4.6 消息内链接 / 路径可点

AI 回复里的链接和带扩展名的文件路径（包括反引号内联代码里的）都能点：

• 工作区内文件路径 → 系统文件管理器中定位
• 外部链接 → 默认浏览器打开
• 点击后就地弹出非模态浮动工具条（查看 / 打开 + 复制），点别处即关

4.7 会话（Session）

会话即一次连贯的对话上下文。AVL Code 会把每一条消息持续追加到本地，断电、关机、重启都不会丢。

常用会话操作：

• 新建会话：会话标签栏右键 → 新建，或快捷键 Ctrl/⌘ + N。
• 切换会话：点击标签页，或在微信里发送 /s <短id>。
• 重命名 / 归档：标签页右键菜单。
• 历史折叠：当上下文接近上限时，AVL Code 会自动把历史压缩为摘要；折叠后原消息仍然保留，可随时展开查看。计划 / 待办等结构化状态在折叠后依然完整可见。

5. 五种工作模式

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

两者的区别：plan 是严格只读，连命令都不能跑；assess 不写业务代码，但可以跑测试、lint、SAST、生成 SBOM，好让验收有实据。

5.1 切换模式

输入框下方的工作模式选择条提供五个圆形按钮，单击即切换。切换会自动加载该模式绑定的助手人设，并同步切换到该模式对应的工具开关集合。

5.2 编辑助手人设

打开 设置 → Agents，可对每个助手设置：

• 名称 — 在面板与对话中显示的名字。
• 个性 — 一句话个性描述（如「严谨克制、注重可读性」）。
• 核心提示词 — 完整的系统提示词；推荐在工作区目录里独立成文件以便版本管理。

小贴士：「筹划」模式默认会自动屏蔽所有写入与执行类工具，强制你"先想清楚再动手"。

5.3 「有如神助」模式

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

6. 第一次对话：实战示例

下面用一个最小例子走一遍完整流程：让 AVL Code 在你的项目里加上一段单元测试。

步骤 1：进入筹划模式

切换到 plan 模式 — 此时所有写操作会被拒绝，AI 只读、只看、只想。

步骤 2：发起需求

在输入框敲入：

帮我看看 src/utils/format.ts，提议给 formatDate 函数补几条单元测试，先列计划。

回车发送。可以看到：

• 输入框右侧的发送键变成「停止」按钮 — 运行中按一下会同步终止主助手与所有派生子任务。
• 中途如果你想到补充内容，直接 Enter 入队 — 这条会在当前自然结束后合并发出，不会打断当前回合。
• 右侧计划浮层与待办列表实时更新。

步骤 3：审阅计划

助手通常会给出一段计划 + 待办清单。你可以：

• 在计划浮层里 接受 / 修改 / 拒绝。
• 接受后点击「退出筹划，进入执行」按钮，AVL Code 会自动切到 execute 模式。

步骤 4：执行

execute 模式下，助手会真正调用读文件、改文件、跑命令等工具完成代码编辑与测试运行。每一次工具调用都会以可折叠卡片的形式显示在消息流中，包含：

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

步骤 5：评估

切到 assess，让助手阅读测试结果与日志、给出结论与改进建议。assess 不会改你的代码，但可以实际跑测试与检查来支撑结论，确保你能安心收尾。完成后 AVL Code 会用「通过」或「失败」横幅标记本次任务。

7. 调用技能（Skill）与命令

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

7.1 三层来源

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

7.2 双轨触发

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

7.3 技能包一瞥

每个技能就是一个文件夹，里面包含一份说明文件，前置元数据描述名称、用途、参数提示、可用工具与适用模式，正文则是真正的提示词模板，支持参数替换与小段命令预处理。

7.4 技能签名（可选）

发布给团队的技能包建议进行国密签名校验。AVL Code 内置签名工具，可生成密钥、自签证书、对技能包整目录签名，并在加载时自动验签——签名失败会被拒绝执行。签名验证策略与信任库集中在 设置 → 技能/插件签名（一份策略同时管技能与插件；导入根证书 PEM 即时生效）。

7.5 一键装一组：插件市场

如果某个项目要装一整组技能 / 钩子 / MCP server，可以走 设置 → 插件 → 市场 一键装：

• 兼容 Claude Code 插件：github@claude-plugins-official、owner/repo 等引用写法直接识别。
• 安装前确认弹窗：摊开来源 / 命令行 / 能力 / 签名信息让你审核后再装；插件卡片带来源可信盾牌，可信状态一眼可辨。
• 安装后插件携带的技能与钩子默认在每个工作区自动激活（可按需关闭）；hook 执行还会在对话流里出可折叠条，方便看清跑了什么。
• 开箱即用的典型插件：仓库自带 22 个插件 — 15 家模型提供方（DeepSeek、OpenRouter、智谱、月之暗面、通义千问、豆包、Ollama、硅基流动、阶跃星辰等，含 OpenAI 兼容模板）、知乎工具集、安全分析主题的能力示范。装上提供方插件、填个 Key 就能用对应模型。
• 对话里也能装：直接让助手「搜一下 / 装一下某插件」— 插件管理工具组（搜索 / 列出 / 安装 / 卸载）会先给出 dry_run 预览（能力 / 命令行 / 签名 / 来源），你确认后才真正落地。

8. 工具权限与审批

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

8.1 三态权限

每个工具都可以设置为：

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

入口在输入区模式滑块旁的齿轮（智能体管理器）→「配置工具」，可按工作模式独立配置。三态真实约束运行：「禁用」对主代理与子代理一并生效，「询问」会在调用前暂停等你批准。

8.2 调用前审批

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

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

8.3 审批桥接

如果你已经绑定了微信通道，审批卡片会同步推送到对应聊天，你可以在微信里回复：

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

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

9. 接入外部工具服务

智能体管理器 →「配置工具」面板支持连接任意标准协议的工具服务（例如 Notion、内部 API、私有知识库）。注意与 设置 → 提供商 区分：后者配置的是大模型供应商。

9.1 添加一个外部服务

1. 输入区模式滑块旁的齿轮（智能体管理器）→「配置工具」→ 添加服务。
2. 选择通道：
   • HTTP / SSE：填接入地址 + 凭证 — 适合云端服务。
   • stdio（本地进程）：填要启动的命令行（如 npx -y @some/mcp-server）+ 环境变量 — 不必要求对方有 HTTP 地址，可直接接 npm / pip 上现成的本地 MCP server。
3. 命名（例如 notion）。
4. 启用。

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

要登录的远程 MCP：新建流程内嵌 OAuth 2.1 + PKCE 授权 — 建的时候就能登录，token 过期前后台用 refresh_token 自动换新。所有凭据（HTTP token / stdio env / OAuth refresh）走国密加密的 VAULT 存储，绝不入主配置或日志；存量明文凭据下次使用时被动迁移。

9.2 实时生效

新连上的外部服务下个回合即对助手可见，不必重开对话。

9.3 健康看板

MCP 配置 → 健康看板：按后端显示调用次数 / 失败率 / P50 / P95，一眼看出哪个服务慢、哪个在报错；最近一次错误就近展开。

9.4 异常处理

后端断连后会自动重试；连接错误信息会在 设置 → Hooks → 错误抽屉里展示，方便定位是凭证过期、网络不通还是服务端故障。

10. 随行通讯：在微信里指挥助手

「随行通讯」让你在通勤路上也能远程指挥桌面助手。

10.1 绑定微信

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

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

10.2 内置命令

10.3 行为细节

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

11. 系统托盘与开机自启

11.1 最小化到托盘

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

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

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

11.2 开机自启

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

12. 主题与外观

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

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

布局、信息量与语言也能一键切（Header 右上快捷菜单集中四个滑块，不必进设置页）：

• 布局：工作区与会话导航在「侧边栏」与「顶部标签页」两档间切换 — 标签页模式下工作区与会话以顶部标签条呈现、内容区贴边展开，打开的标签重启后自动恢复；登录后标签条还会显示当前用户名。
• 信息量：消息密度「正常 / 极简」两档 — 极简档把工具调用等过程细节收敛为灰阶细行，消息流更紧凑，你的提问与 AI 正文照常完整显示。
• 语言：界面语言三档，滑块上显示为 简 / 繁 / EN（依次对应简体中文 / 繁體中文 / English，悬停可见完整语言名），点一下整个界面即时切换并自动保存。

13. 升级、卸载与故障排查

13.1 升级

• 应用内升级（推荐）：托盘菜单 → 检查更新 → 一键替换。升级包带签名校验，验签失败会自动回滚。
• 手动升级：从官网下载新版本构建直接替换运行（免安装），配置目录不动。

13.2 卸载

• 删除应用本体（macOS 拖到废纸篓；Windows 控制面板卸载；Linux 用包管理器移除或删除 AppImage）。
• 如需彻底清理，删除应用数据目录（设置 → 数据 中可一键定位），会同时丢弃所有会话与凭证，谨慎操作。
• 若开启过开机自启，可在 设置 中关闭后再卸载，避免残留启动项。

13.3 常见问题

• 「服务未就绪」提示：稍等几秒，子进程仍在初始化；持续 30 秒以上请打开 设置 → Hooks → 错误抽屉查看具体原因。
• 会话突然不响应：点击输入框右侧 停止按钮（会同步终止所有派生任务），再发新消息即可恢复。
• 登录后没有可用模型：设置 → 账号 → 强制刷新；或退出账号重新登录。
• 样本扫描返回空结果：默认安装可能未包含完整规则集，请联系内部分发渠道获取完整版本。

13.4 日志

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

14. 附录

14.1 常用键盘快捷键

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

14.2 关键设置入口速查

14.3 进一步阅读

• 产品官网与发布记录（请联系内部渠道获取最新链接）
• 技能扩展开发指南
• 随行通讯使用手册
• 安全分析能力图谱（可由销售/售前提供）

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