快速上手指南

第一節 本書導讀

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。