第二节下载、运行与系统要求

[!ref] 新手教程：分步安装与首次登录的手把手引导见快速上手指南「安装与登录」节；本节按平台给出系统要求、下载与运行方式的完整说明。

类别	要求
操作系统	Windows 10（1809）及以上；macOS 12.0 Monterey 及以上；主流 Linux 发行版（Ubuntu 22.04 / Debian 12 / CentOS Stream 9 及更新）
国产化操作系统	银河麒麟桌面 V10 SP1（Kylin-Desktop-V10-SP1-2503）；统信 UOS V20（Uos-Desktop-V20-1060）；银河麒麟 ARM64（V10 SP1 与 V11 各有对应构建）
处理器架构	x86-64（64 位）；macOS 同时支持 Apple Silicon（arm64）；国产化平台另有 ARM64（aarch64）构建
运行时依赖	Windows：系统自带 WebView2 运行时；Linux：`webkit2gtk`（4.0 / 4.1，按发行版选对应构建）；macOS：系统内置 WebKit，无需额外安装。Linux 的 DEB 包自带可重定位的 WebKit 4.1 运行时，目标机没有合适的 `webkit2gtk-4.1` 也能跑；目标机已装有时自动改用系统库（见 §27.1）
内存	最低 8 GB，推荐 16 GB
磁盘	最低 1 GB 可用空间，推荐 2 GB 以上（本地会话 / 技能 / 日志 / 代码索引）
显示	建议 1280 × 720 及以上分辨率
网络	首次启动需联网获取模型列表；日常需可访问账号服务与所选服务提供方接口（可离线使用的能力见相应章节）

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

平台 / 构建	运行方式
Windows x64	下载后直接双击运行（免安装、无向导）
macOS 通用版（Universal）	Intel 与 Apple 芯片通用；拖入应用程序后运行
macOS Apple 芯片版（arm64）	仅 Apple 芯片、体积更小；拖入应用程序后运行
Linux x64 通用	解压后直接运行
Linux AppImage	免安装单文件，加执行权限（`chmod +x`）后直接运行
Linux Snap	Snap 包（`snap install`）
Linux WebKit 4.1	面向较新发行版（依赖 `webkit2gtk-4.1`）
银河麒麟 V10 SP1	国产化专门构建（Kylin-Desktop-V10-SP1-2503，x86）
统信 UOS V20	国产化专门构建（Uos-Desktop-V20-1060）
银河麒麟 ARM64（压缩包）	国产化 ARM64（aarch64）免安装构建，解压后直接运行
银河麒麟 V10 ARM64（DEB）	国产化 ARM64 安装包（`avlcode_v10_<版本>_arm64.deb`），随包自带 WebKit 4.1 运行时

Windows / Linux：下载即运行，无需安装。
macOS：建议把应用拖进 应用程序 文件夹再运行 —— 否则从「下载」/「桌面」直接运行时，检查更新会被系统 App Translocation 机制锁住（见 §27.7.2）。
国产化环境：银河麒麟 V10 SP1、统信 UOS V20 提供专门构建；ARM64（aarch64）机器有独立的国产化 ARM64 渠道（压缩包 + V10 DEB 两种形态），升级检查也走这条独立渠道，不与 x86 混用。
Linux Wayland 会话：在 Wayland 下运行时窗口保持应用自绘的无边框外观，不会退回系统标题栏。

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

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

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

首启向导：每次启动时，只要没有可用的模型（例如尚未登录，内置 AVL-Zero 还没有 key），就会自动弹出三步向导：

步骤	内容
1. 登录	手机号登录（未注册的号码自动创建账号）；已登录时显示当前账号与可用点数，可「下一步」或「切换账号 / 重新登录」。已有自己的模型服务时点「转到手工配置」，向导暂离并打开设置 → 模型 → 服务提供方，关掉设置页即回到第 2 步
2. 创建项目 / 打开项目	有历史项目时默认列出「打开历史项目」；也可「新建项目」（名称默认 `Project_NN`，存放位置优先用上次新建时的目录）或「连接远程服务器（SSH）」
3. 发起首次会话	给出几个示例与「自己输入」；点示例只把文字填进输入框，不会自动发送

右上角 ×（或 {{kbd:Esc}}）为「跳过向导」；第 1 步可「跳过此步」，第 2 步可「稍后再说」。关闭只对本次启动有效，问题没解决下次启动还会弹。
想再走一遍：设置 → 账号 底部「首启向导」区块的「重新运行向导」，或命令面板里的「运行首启向导」。
Windows 存放位置默认取最后一个本机固定盘，自动排除 U 盘、移动硬盘、读卡器、网络盘等可移除介质，以及 BitLocker 锁定或未就绪的盘。项目所在盘被 BitLocker 锁定时，列表里该项置灰并标「BitLocker 已锁定」，点一下即调起系统的解锁对话框，解锁后自动打开该项目；标「驱动器未就绪」的盘暂不能打开。

不想用向导也可以直接点击左下角的「登录」按钮完成账号绑定（见第三节）。未登录状态下也可以用，但需要在 设置 → 模型 → 服务提供方 中手动配置 API Key。

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

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

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

终端版现在和桌面版是同一份数据，日常该有的都有：

会话直接写进桌面版的会话库 —— 终端里跑的对话，回桌面就能接着看、接着聊；/sessions 列最近会话、/resume <会话 ID> 切过去、{{kbd:F2}} 开新会话、启动时 -session <ID> 恢复指定会话。
上下文折叠（/compact）与会话目标（/goal）与桌面版同源，折叠快照跟着会话走。
登录与账户：/login（用户名密码 / /login phone <手机号> 短信验证码）、/sso、/logout、/usage 看用量、/redeem <兑换码>、/feedback <内容> 提反馈；启动时显示公告横幅。
Hook 与审批：工作区层 hooks 生效，需要批准时在终端里行内决策 —— y 本次允许 / a 永久允许 / n 拒绝（Esc 同 n，30 秒未选自动拒绝）。「永久允许」写进工作区的批准文件，与桌面端互认。
沙箱附加：/attach <路径> [ro|rw] 给本次会话附加工作区之外的目录 / 文件（缺省只读），/attach 无参数列出当前清单，/detach <路径> 解除。
终端版会自行拉起所需的工具链并在退出时回收，状态显示在底部状态栏。

[!ref] 完整的命令清单与参数见参考手册「命令行入口」节。

第二节 下载、运行与系统要求