AX Kit
UX 是人類的體驗。代理體驗 (Agent Experience, AX) 則是 AI 代理為使用者使用產品時的體驗。 代理沒有眼睛、對 CAPTCHA 毫無耐心，也沒有可以詢問的人類。它只能使用產品暴露給機器的部分。
此技能旨在改善網站、API、SaaS 應用程式或商店的代理層。 它實作了代理使用的標準，並透過掃描器來衡量結果。 分數是工作的回饋，而非目標。
設定
<skill-dir> 是包含此 SKILL.md 的目錄。請將工作目錄維持在使用者的專案中。
掃描器位於 <skill-dir>/scripts/ax.mjs。它需要 Node.js 18 或更新版本，且無其他依賴。
node <skill-dir>/scripts/ax.mjs scan <url> --profile <content|api|webapp|commerce> --json
如果 node 缺少或版本低於 18，請告知使用者。然後在無掃描器的情況下繼續執行操作手冊。
命令
在使用者的請求中找到命令。然後閱讀該命令的指南並遵循它。
| 命令 | 當使用者想要......時使用 | 指南 | 編輯程式碼 |
|---|---|---|---|
improve | 透過掃描、修復和驗證的循環來改善產品的代理體驗 | references/improve.md | 是 |
add <capability> | 實作單一功能，例如 llms-txt 或 mcp-server | references/add.md | 是 |
audit <url> | 取得完整的診斷報告，不做任何更改 | references/audit.md | 否 |
score <url> | 快速取得 AX 分數和主要差距 | references/score.md | 否 |
design | 在程式碼存在前審查計劃中的 API、網站或功能 | references/design.md | 否 |
ci | 為分數添加管線門檻和徽章 | references/ci.md | 是 |
如果請求未指明命令且您無法推斷，請顯示此表格並詢問使用者要哪個命令。\n請勿從選單開始工作。
適用於所有命令的規則
這些規則優先於參考文件。
- 在編輯前確認。 獲得使用者兩次同意。首先，就將要解決的差距達成一致。然後閱讀操作手冊，並顯示您將要確切更改的檔案。只有在第二次同意後才能編輯。
- 在即時網站上保持唯讀。 僅發送讀取資料的請求。不要建立帳戶、提交表單或購買任何東西。網站所有者可以以純文字批准例外。掃描器會發送一個
POST：向/mcp發送server/discover請求。該請求僅讀取資料。 - 在使用外部掃描器前先詢問。 託管掃描器會收到 URL。請先獲得同意。
- 保護安全。 不要停用機器人保護、為私人資料開放 CORS，或暴露私人內容以提高分數。每個操作手冊都有安全說明。請遵守它們。如果一個人類頁面有 CAPTCHA，請保留它。為代理添加單獨的路徑，例如來自 API 的金鑰，並附有濫用控制。
- 尊重所有者的機器人政策。 封鎖 AI 訓練爬蟲是有效的決定。除非使用者要求，否則不要更改它。
- 檢查標準的日期。 每個操作手冊都有一個「審查」日期。如果該日期已超過 6 個月，請先閱讀原始來源再實作。
- 報告真相。 顯示分數、覆蓋率以及掃描器未評估的每項檢查。不要將未評估的檢查顯示為通過。
- 修復根本原因。 不要僅為了滿足檢查而添加檔案。一個帶有錯誤連結的
llms.txt比沒有檔案更糟。
七大支柱
支柱遵循代理的旅程。早期支柱的失敗會阻礙其後的支柱。
| 支柱 | 問題 | 操作手冊 |
|---|---|---|
| 觸及 (Reach) | 代理能否獲得回應，且機器人政策是否明確？ | bot-access |
| 探索 (Discover) | 代理能否找到存在的內容？ | llms-txt, sitemap-and-links, api-catalog, agent-discovery |
| 閱讀 (Read) | 代理能否在無瀏覽器的情況下理解內容？ | markdown-for-agents, server-rendering, structured-data |
| 行動 (Act) | 代理能否呼叫產品？ | openapi-quality, mcp-server, webmcp, api-design |
| 授權 (Authorize) | 代理能否在無人協助下獲得存取權限？ | oauth-for-agents, self-serve-access |
| 恢復 (Recover) | 代理能否在錯誤後自行修正？ | errors-and-limits |
| 交易 (Transact) | 代理能否付款？ | agentic-commerce |
每個操作手冊都是檔案 references/<name>.md。
設定檔
設定檔告訴掃描器應套用哪些檢查。使用 --profile 指定設定檔。如果省略，掃描器會自動檢測。
| 設定檔 | 目標 |
|---|---|
content | 行銷網站、文件網站或部落格 |
api | HTTP API |
webapp | 具有帳戶的 SaaS 應用程式 |
commerce | 商店 |
一個產品可以有多個表面。使用各自的設定檔掃描每個表面。
範例：以 content 設定檔掃描 example.com，以 api 設定檔掃描 api.example.com。
對於 API，請提供能回應整個 API 的 URL。如果主機根目錄以 API 回應，請使用主機根目錄。如果 API 位於某個路徑下，例如 /api/v1，且主機根目錄提供其他內容，請使用該路徑。
掃描器會在主機的眾所周知位置以及您提供的 URL 旁邊尋找 API 描述。
如何讀取掃描器輸出
JSON 報告包含三個檢查類別。
| 類別 | 內容 | 對分數的影響 |
|---|---|---|
score | 對穩定標準的量測檢查 | 分數的全部 |
review | 需要判斷的檢查，例如「代理可以在無 CAPTCHA 的情況下取得 API 金鑰」 | 無。由您評估。 |
watch | 新興標準、舊有路徑和觀察 | 無 |
score是從 0 到 100 的經驗證下限。upperBound是如果每個未評估的檢查都通過時的分數。coverage顯示掃描器能夠評估的分數比例。超時會降低此比例。- 當
score和upperBound位於不同的評級區間時，grade為null。 - 當閘門失敗時，會設定
cap。當一個普通請求遇到機器人挑戰，或頁面在沒有 JavaScript 的情況下沒有內容時，閘門會失敗。上限為 59。 opportunities列出每次修復可以增加的分數，從大到小。它包含所有差距。文字輸出僅顯示前 8 項。- 每個檢查都有一個
playbook。這是指定修復方法的參考檔案。 - 帶有
blockedBy的檢查失敗是因為另一個檢查先失敗了。其狀態為fail，而不是not_assessed，因此不會降低覆蓋率。請先修復blockedBy中的檢查。 review列出適用於該設定檔的審查檢查。僅評估這些。
如果沒有 --json，掃描器會列印一份包含分數行和支柱行的簡短文字報告。對使用者使用文字報告，對您的工作則使用 JSON。
退出碼：0 正常，1 閘門失敗，2 使用錯誤，3 閘門不確定，4 無分數，5 內部錯誤。
node <skill-dir>/scripts/ax.mjs catalog --json 會列印目錄。其 checks 陣列的每個條目都有一個 bucket。審查檢查還有一個包含 pass、partial、fail 和 evidence 成員的 rubric。
將 JSON 報告保留在對話中，或保留在專案外的暫存目錄中。除非使用者要求，否則不要將其寫入專案。
有關公式，請閱讀 references/scoring.md。有關檢查清單，請閱讀 references/checks.md。
參考檔案
僅在條件成立時才讀取檔案。
| 檔案 | 何時讀取 |
|---|---|
| references/stacks.md | 您必須找出檔案、標頭或路由在專案框架中的位置 |
| references/standards.md | 您必須知道某個標準是穩定、新興還是舊有，或路徑是否已改名 |
| references/checks.md | 您需要了解檢查 ID 的含義，或審查檢查的評分標準 |
| references/scoring.md | 使用者詢問分數的運作方式 |
references/<playbook>.md | 您要實作或解釋該操作手冊的功能 |
常用檔案的範本位於 <skill-dir>/assets/。每個操作手冊都會命名其使用的範本。