快速上手指南

第一节 本书导读

AVL Code 是一款 AI 智能编程与安全分析桌面助手。它的文档共三本，分工明确：

建议的查阅路径：

1. 第一次使用 → 本书从头读到尾，边读边做。
2. 想深入某个功能 → 去用户手册对应章。
3. 只想查一个设置项 / 命令 / 参数 → 直接翻参考手册。

本书里的「指路框」长这样：

[!ref] 示例：该话题的完整说明见用户手册「工作区」节。

遇到指路框，表示这个话题在本书只讲到够用为止，详解在它指向的那一章。教程只在本书出现，详解只在用户手册，速查表只在参考手册——三本互不重复。

第二节 安装与登录（约 10 分钟）

2.1 下载运行（免安装）

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

[!warning] macOS 请务必把应用拖进 应用程序 文件夹再运行——否则从「下载」/「桌面」直接运行时，检查更新会被系统 App Translocation 机制锁住。

2.2 系统要求

2.3 首次启动

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

• 左侧栏：工作区列表 + 登录/账号 + 设置入口。
• 中央会话区：会话标签页 + 消息流 + 输入框。
• 右侧：计划 / 待办 / 审批等状态区块，按需出现。

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

2.4 登录账号（一键开箱）

登录这一步会自动为本机分配一份共享计费额度，无需手动配置 API Key。三种登录方式：

• 手机号验证码（默认，最快）：输手机号 → 收短信验证码 → 登录。没有账号会自动注册，无需单独注册流程。
• 用户名 + 密码：设置 → 账号 → 密码登录 tab。
• SSO 单点登录：设置 → 账号 → SSO 登录，自动打开浏览器完成认证后回跳。

登录成功后：

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

[!note] 想直接接 Claude 官方接口、OpenAI 兼容代理或自建大模型服务：设置 → 提供商 → + 添加，填入接入地址 + API Key。启用后 AVL Code 会优先使用你自己的 Key，自动回退到共享额度作为兜底。

[!ref] 三种 Provider 协议（AVL Delta / OpenAI / Anthropic）、自定义请求头与参数详解见用户手册「模型与参数」节；用量、兑换码与计费见用户手册「账号、用量与计费」节。

第三节 第一个工作区与第一次对话（约 10 分钟）

3.1 创建第一个工作区

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

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

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

[!ref] 目录结构、SSH 远程工作区、项目指令（AGENTS.md）、会话附加目录等详解见用户手册「工作区」节与「会话」节。

3.2 会话

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

• 新建会话：会话标签栏右键 → 新建，或 {{kbd:Cmd+N}}。
• 重命名 / 归档：标签页右键菜单。
• 历史折叠：上下文接近上限时自动把历史压缩为摘要；原消息保留可展开。

3.3 第一次对话

在输入框里用一句话描述你想让 AI 做的事，回车发送。运行中你会看到：

• 发送键变成「停止」按钮——按一下会同步终止主助手与所有派生子任务。
• 中途想到补充内容，直接回车入队——这条会在当前回合自然结束后合并发出，不打断当前回合。
• 每一次工具调用都以可折叠卡片显示在消息流中：工具名 + 入参摘要、执行耗时、结果（成功 / 失败 / 截断）。

[!tip] 开场第一句话偏短或含糊时，AI 会先复述意图（目标 + 计划）请你确认再动手；说得够清楚就直接开干。该行为默认开启、可关，详见用户手册「会话」节。

第四节 让 AI 真正干活：五种模式与工具审批（约 15 分钟）

4.1 五种工作模式

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

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

4.2 切换模式

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

[!ref] 每个助手的名称、个性与核心提示词都可自定义，还有临时指派助手的「有如神助」模式，详见用户手册「助手人设」节。

4.3 工具权限三态

AVL Code 对每一次工具调用做精细化管控。每个工具都可以设置为：

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

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

4.4 调用前审批

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

1. 桌面端弹出审批弹窗，展示工具名、入参与影响范围。
2. 你可以选择：
   • 允许（仅本次）
   • 始终允许（写入白名单）
   • 拒绝

[!warning] 审批弹窗带 30 秒倒计时，超时未响应按「拒绝」处理。

[!tip] 绑定微信通道后，审批卡片会同步推送到手机，可远程回复批准——见第五节任务五。

[!ref] 白名单匹配规则、多端审批与审批留痕详见用户手册「工具权限与审批」节；策略字段速查见参考手册「工具权限策略」节。

第五节 五个实战任务

五个任务相互独立，各自都是「前置条件 → 操作步骤 → 预期结果」的结构；按需挑着做即可。

5.1 任务一（编程）：给函数补上单元测试

前置条件：已登录；一个绑定了代码项目的工作区（第三节）。

操作步骤：

1. 切换到 plan 模式——此时所有写操作会被拒绝，AI 只读、只看、只想。
2. 在输入框发出需求（把路径与函数名换成你项目里真实存在的），例如：「帮我看看 src/utils/format.ts，提议给 formatDate 函数补几条单元测试，先列计划。」
3. 审阅计划：助手会给出计划 + 待办清单，你可以在计划浮层里 接受 / 修改 / 拒绝。
4. 接受后点击「退出筹划，进入执行」，AVL Code 会自动切到 execute 模式，助手真正调用读文件、改文件、跑命令等工具完成编辑与测试运行。
5. 完成后切到 assess，让助手阅读测试结果与日志、给出结论与改进建议——它不会再改你的代码，但可以实际跑测试来支撑结论。

预期结果：任务收尾时 AVL Code 用「通过」或「失败」横幅标记本次任务。

5.2 任务二（编程）：装一个技能，用 / 命令触发

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

前置条件：已登录。

操作步骤：

1. 设置 → 插件 → 市场，挑一个插件。安装前确认弹窗会摊开来源 / 命令行 / 能力 / 签名信息，审核后再装。
2. 安装后插件携带的技能与钩子默认在每个工作区自动激活（可按需关闭）。
3. 回到输入框，敲 / 弹出命令面板，或直接输入 /技能名 参数1 参数2 发送。

预期结果：你触发的技能渲染后注入到下一条上下文；助手也可以自主选择调用技能，结果作为工具响应回到对话流。

[!note] 技能有三层来源：全局 / 工作区 / 插件；工作区版本会覆盖全局版本，方便不同项目使用不同口径的技能。

[!tip] 外部 MCP 工具服务（HTTP / SSE 云端服务，或 npx 一类 stdio 本地进程）在智能体管理器 →「配置工具」→ 添加服务中接入，新连上的服务下个回合即对助手可见，不必重开对话。

[!ref] 技能包结构、签名验签与调试见用户手册「技能（Skill）系统」节；插件市场与开箱插件清单见用户手册「插件与扩展」节；外部服务的 OAuth 登录、凭据加密与健康看板见用户手册「外部工具服务接入」节。

5.3 任务三（安全分析）：投放样本，做一次基础研判

前置条件：已登录；一个样本工作区（如 ~/samples/2026-04-malware）；一个待分析的可执行文件。

操作步骤：

1. 点输入框左下角的「+」按钮，在系统文件对话框中选中样本——文件会直接落到当前工作区的 samples/ 子目录，输入区上方显示文件名 + 进度条。
2. 在对话里发：「对刚才那个 PE 跑 hash + entropy + ioc_extract，给我一份初判。」
3. 若相应分析工具被设为「询问」，在审批弹窗中允许。

预期结果：消息流中出现哈希、熵、IOC 抽取等只读分析工具的调用卡片，助手基于工具输出给出初判回复。

[!note] 样本默认上限 300 MiB（设置 → 数据 → 附件 / 样本 可调）；重名自动加时间戳后缀，不会静默覆盖。

[!ref] 完整安全分析能力（格式解析、反汇编、反编译、规则匹配、流量元数据、云端威胁情报与哨兵扫描）见用户手册「安全分析工具」节；各工具参数速查见参考手册「安全分析工具」节。

5.4 任务四（安全分析）：给项目做一次供应链体检（SBOM）

前置条件：一个包含依赖清单（如 package-lock.json / go.mod / requirements.txt）的项目工作区。

操作步骤：

1. 在对话里让助手为项目生成软件物料清单（sbom.generate）——自动识别 npm / Go / Python / Maven / Rust 等 16 种生态、22 种依赖清单。
2. 让助手继续排查依赖里的已知漏洞（sbom.audit）——对照 OSV / CVE / KEV 漏洞库，按 CVSS 严重度给出结论。
3. （可选）让助手做可达性收敛（sbom.vex）——用符号级可达性分析把「装了但根本没调用」的漏洞收敛掉。

预期结果：结果文件默认落到工作区的 .avlcode/ 目录；漏洞按最严重优先排序，KEV（已知被利用）漏洞永远置顶。

[!ref] 生态识别范围、离线 / air-gap 用法与 CycloneDX / SPDX / OpenVEX 输出格式见用户手册「安全分析工具」节。

5.5 任务五（日常协作）：绑定微信，在手机上指挥与审批

前置条件：桌面端已登录并有一个目标工作区；手机上的微信。

操作步骤：

1. 设置 → 随行通讯，用微信扫码登录通道。
2. 在桌面端为目标工作区生成一个 6 位配对码（10 分钟内有效）。
3. 在微信单聊或群里发：/bind 123456。
4. 绑定成功后直接发消息即可驱动桌面助手；遇到审批时，审批卡片会推送到聊天里，回复 /approve <审批号>（允许本次）/ /always <审批号>（始终允许）/ /deny <审批号>（拒绝）。
5. 手机上 /s <短id> 可继续未完成的桌面会话；/stop / /resume 暂停终止 / 恢复在跑任务。

预期结果：桌面会话与微信会话自动共享，重启后对话完整保留；在微信里完成审批后，桌面侧弹窗同步消失，整条任务自动续跑。

[!note] 长回复自动分段避开微信单条消息长度上限；助手处理中会用「输入中」做回执，不发占位文本。

[!ref] 完整命令表见参考手册「随行通讯命令」节；路由策略、群协作与安全边界见用户手册「随行通讯」节。

第六节 下一步去哪里

走完前五章，你已经完成了从安装登录到编程、安全分析、随行协作的第一轮完整体验。想继续深入时，按下表查：

三件常用的小事，一句话速览：

• 托盘与自启：设置 → 通用 可开启「最小化到系统托盘」（关窗不退出）与「开机自启」（开机静默拉起到托盘）。
• 主题与外观：主题三档 system / light / dark；Header 右上快捷菜单集中主题、布局（侧边栏 / 顶部标签页）、信息量（正常 / 极简）、语言（简 / 繁 / EN）四个滑块，不必进设置页。
• 升级 / 卸载 / 排障：应用内升级走托盘菜单 → 检查更新，升级包带签名校验、验签失败自动回滚；卸载删除应用本体即可，彻底清理需另删数据目录；遇到问题先开 设置 → 数据 → 打开日志目录。

[!ref] 详解分别见用户手册「系统托盘与开机自启」「主题与外观」「升级、备份与同步」「卸载与数据清理」「故障排查与常见问题」节。

附录：常见问题速查

只收录无法启动、无法登录这类让你用不了 AVL Code 的问题；其余故障请按上一节的指引查阅用户手册对应章节。

• 应用无法启动：先看日志（设置 → 数据 → 打开日志目录）；或重装后再试。
• 应用启动后白屏：通常是系统自带网页视图组件版本过旧，对照第二节系统要求升级（Windows：WebView2；Linux：webkit2gtk）。
• 「服务未就绪」提示：稍等几秒，子进程仍在初始化；持续 30 秒以上请打开 设置 → Hooks → 错误抽屉 查看具体原因。
• 登录后没有可用模型：设置 → 账号 → 强制刷新；或退出账号重新登录。
• 会话突然不响应：点击输入框右侧 停止按钮（会同步终止所有派生任务），再发新消息即可恢复。

[!ref] 更多排障（工具类、安全分析类、随行通讯类、性能类问题）见用户手册「故障排查与常见问题」节。

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