AX Kit
UX 是人类的体验。代理体验（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 | 是 |
如果请求中没有指明命令且你无法推断，请展示此表格并询问用户想要哪个命令。 不要从菜单开始工作。
适用于所有命令的规则
这些规则的优先级高于参考文件。
- 编辑前确认。 需要获得用户两次同意。首先，就待修复的差距达成一致。然后阅读行动手册，并展示你将要修改的确切文件。只有在第二次同意之后才能进行编辑。
- 对在线站点保持只读。 仅发送读取数据的请求。不要创建账户、提交表单或购买任何东西。站点所有者可以用简单明了的语言批准例外。扫描器会发送一个
POST请求：一个server/discover请求到/mcp。该请求仅读取数据。 - 使用外部扫描器前需询问。 托管型扫描器会接收 URL。请先获得用户同意。
- 保护安全。 不要禁用机器人防护、为私有数据开放 CORS，或为了提升评分而暴露私有内容。每个行动手册都有安全说明。请遵守它们。如果人类页面有 CAPTCHA，请保留它。为代理添加单独的路径，例如来自 API 的密钥，并配备滥用控制措施。
- 尊重所有者的机器人策略。 阻止 AI 训练爬虫是一个有效的决定。除非用户要求，否则不要更改它。
- 检查标准的日期。 每个行动手册都包含一个“审核日期”。如果该日期超过 6 个月，请在实施前阅读主要来源。
- 如实报告。 展示评分、覆盖率以及每个扫描器未评估的检查项。不要将未评估的检查项显示为“通过”。
- 修复根本原因。 不要仅仅为了满足一项检查而添加文件。一个包含错误链接的
llms.txt比没有文件更糟糕。
七大支柱
这些支柱遵循代理的工作流程。早期支柱的失败会阻碍后续支柱。
| 支柱 | 问题 | 行动手册 |
|---|---|---|
| 可达性 | 代理能否获得响应？机器人策略是否明确？ | bot-access |
| 发现 | 代理能否找到存在的内容？ | llms-txt, sitemap-and-links, api-catalog, agent-discovery |
| 可读性 | 代理能否在无需浏览器的情况下理解内容？ | markdown-for-agents, server-rendering, structured-data |
| 可操作性 | 代理能否调用产品？ | openapi-quality, mcp-server, webmcp, api-design |
| 授权 | 代理能否在无人工干预的情况下获得访问权限？ | oauth-for-agents, self-serve-access |
| 恢复 | 代理在出错后能否自行纠正？ | errors-and-limits |
| 交易 | 代理能否付款？ | agentic-commerce |
每个行动手册对应一个文件 references/<name>.md。
配置文件
配置文件告诉扫描器哪些检查项适用。使用 --profile 指定配置文件。如果省略，扫描器会自动检测。
| 配置文件 | 目标 |
|---|---|
content | 营销网站、文档网站或博客 |
api | HTTP API |
webapp | 带有账户的 SaaS 应用 |
commerce | 电商商店 |
一个产品可能有多个表面。使用各自的配置文件扫描每个表面。
示例：将 example.com 作为 content 扫描，将 api.example.com 作为 api 扫描。
对于 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。审查检查项还有一个 rubric，包含 pass、partial、fail 和 evidence 成员。
在对话中或项目外部的临时目录中保留一份 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/ 目录中。每个行动手册都会指明其使用的模板。