第四章　自動化與擴充

本章覆蓋第 14–19 章：技能系統、子任務與背景執行、計畫與待辦、歷史折疊這四類自動化能力，以及外掛擴充與隨行通訊兩條擴充途徑。

第十四節 技能（Skill）系統

技能（Skill）是一個由提示詞模板 + 元資料組成的小包，讓助手擁有"領域專家"能力。AVL Code 的技能系統相容業界主流格式，可以直接復用社區生態。

14.1 三層來源

工作區版本會覆蓋全域版本，方便不同專案使用不同口徑的同名技能。

工作區裡會被掃描到的目錄（同名時下面的覆蓋上面的）：

早期版本只掃描後三個目錄，把技能倉函式庫直接放在 skills/ 下會"怎麼都列不出來"；現在這條慣例已正式納入。

遠端工作區的技能同樣可用：SSH / 遠端工作區下的技能會被先完整快照到本機的私有臨時目錄，解析、驗章、渲染全部發生在這份不可變快照上 —— 校驗通過之後遠端再改也影響不到這一次呼叫，篡改只會讓驗章失敗。快照繼承本機全部護欄（拒符號鏈接與非普通文件、單目錄 256 個文件、單文件 4 MB、合計 16 MB、目錄深度 16，複製期間大小發生變化即拒）。技能裡的 ${SKILL_DIR} 指向真實目錄（遠端為工作區相對路徑），AI 讀得到配套資源。

技能沒列出來時，會告訴你為什麼：列技能的結果裡會帶上被隱藏的技能清單及原因（未簽章 / 驗章未過 / 解析失敗 / 快照失敗）與當前的簽章政策；按名字呼叫一個沒列出來的技能時，也會直接給出精確原因，而不是只說"沒找到"。這樣就不會再出現"AI 反復全函式庫搜尋找技能、最後得發生錯誤誤結論"的情況。

內置技能（開箱即用）：應用隨包內置一批技能（如 AI 引導式 skill-creator，幫你在引導下建立、完善自己的技能）。內置技能在啟動時自動物化，內容漂移會被自動覆蓋以保證一致；並通過構建期簽章 + 內置簽章錨點，在嚴格簽章政策下也能正常放行。設定 → 技能 面板會給它們標註「內置」徽標，便於與自建、第三方技能區分。

Agent Skills 相容加固：加強了對 Agent Skills（agentskills.io） 的相容 —— 改進跨用戶端的技能發現與解析容錯、補充工具名稱的翻譯映射，讓不同來源、不同命名習慣的技能都能被正確識別和呼叫。

14.2 雙軌觸發

• 使用者觸發：在輸入框敲 /技能名 參數1 參數2 → 渲染後注入到下一條上下文。
• 助手觸發：助手自主選擇並呼叫，結果作為工具回應回到對話流。

更主動的技能匹配：系統提示裡補上了當前可用技能清單，並強化「動手前先按用途匹配合適技能」的引導。結果是 AI 更傾向於在合適的任務上主動選用貼合的技能，而不是埋頭硬做或重復造輪子。

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 內置簽章工具，可生成金鑰、自簽憑證、對技能包整目錄簽章，並在載入時自動驗章 — 簽章失敗會被拒絕執行，確保從信箱、網盤獲取的技能不會帶毒。

統一簽章驗證政策開關：簽章政策與信任庫現集中在獨立的 設定 → 技能/外掛簽章 Tab（安全分組），一個開關同時管住技能和外掛 — 改成「跳過」即可允許裝未簽章的技能與外掛；切換時自愈歷史遺留的不一致狀態。

信任庫即放即生效：信任庫支持手動 / 自動重新載入，並可直接匯入根憑證 PEM — 投放憑證後即時生效，不再需要重新啟動應用。

「來源不可證實」由你決定：簽章政策為 warn 時，無法證實來源的技能 / 外掛改為彈出確認、由你選擇是否放行；而存在篡改證據的包仍然硬性攔截。拒絕或匯入失敗時會透出具體原因，不再是籠統報錯。

執行面與介面口徑一致：技能的實際執行面現在遵循你在設定裡選的簽章政策（此前執行面固定按最嚴的 strict 走，於是出現"系統提示裡說這個技能可用、真呼叫卻被拒"的幽靈能力）。政策改動即時生效、無需重新啟動。口徑是：warn 下未簽章放行，但簽章存在卻校驗未過（疑似篡改）仍然拒絕；政策文件缺失 / 不可讀 / 取值非法時一律按最嚴的 strict 處理。

14.6 偵錯

設定 → 技能 提供：

• 模板預覽（參數取代後的最終提示詞）
• 命令預處理結果
• 元資料校驗
• 適用模式的檢查

14.6.1 發佈前自查：market.check

新增內置只讀工具 market.check：按 AVL Code 應用商店（zMarket）的發佈契約校驗一個本機技能 / 外掛目錄，報告過 / 不過 + 原因 + 缺什麼（name slug、嚴格 semver 版本、source 形態、能力聲明、歸檔安全等）。純本機確定性校驗，不連網、不提交。建立 / 編輯技能後、發佈前先跑一遍按報告補齊即可。

• 參數：path（必填，待校驗目錄相對路徑，如 .avlcode/skills/my-skill）、kind?（skill/plugin/mcp/provider，缺省自動探測）、version?、source?、manifest?。
• 注意：.skill-sign 的簽章 ≠ zMarket 認可；本工具只查發佈契約形態，不代表執行階段安全稽核。

14.7 團隊共享

把技能放進團隊倉函式庫後，新成員只需把資料夾放到工作區指定路徑即可自動識別。配合簽章機制可形成"內部技能市場"。