内容
代理就绪度审计工具npm 版本](https://img.shields.io/npm/v/agent-readiness-auditor.svg)](https://www.npmjs.com/package/agent-readiness-auditor)
[](https://github.com/asish-singh/agent-readiness-auditor/actions/workflows/ci.yml)
一个命令行工具，用于扫描网站并评估其与自动化 AI 代理的协作程度以及防御能力。
## 该工具解决的问题
AI 助手越来越多地代表用户访问网站：读取页面、上的指示并采取行动。这为网站所有者带来了两个实际问题：
1. **** 网页中可能包含人类访问不到但 AI 代理可以读取的文本文本可能包含旨在劫持代理的指令。这被称为间接提示注入。
2. **机器可读性。** 网站通常是为人类眼睛设计的。代理在网站发布关于其内容和规则的机器可读信号时表现更好。
标准 SEO 工具衡量网站对搜索引擎的适用性。该工具衡量的是不同的东西：网站对 AI 代理的适用性以及它们对 AI 代理的安全性。
## 使用该工具进行的研究
[2026 年代理网络状态](reports/2026-state-of-the-agentic-web/) 使用该工具审计了七个类别中的 84 个知名网站第二版](reports/2026-state-of-the-agentic-web/second-edition.md) 使用更深入的九项检查审计。研究发现，没有一个被审计的网站在属性级别和多页面扫描下包含隐藏的提示注入内容，只有 13% 发布了 FAQ 结构化数据 AI 答案引用，没有一个网站宣传 MCP 端点，近五分之一的知名网站完全拒绝自动化访问，包括几家 AI 公司。数据和方法已发布，供任何人复制。
## 检查内容
该工具获取登陆页面、robots.txt、llms.txt 和站点地图，然后爬取几个关键页面并运行九项检查，产生 0 到 100 的分数和 A 到 F 的等级。安全性按故意加权最高，因为可读的网站可能劫持代理比简单难以阅读的网站更糟糕。
| 检查项目 | 分数 | 检查内容 |
| --- | --- | --- |
| 隐藏提示注入文本 | 40 | 代理劫持短语在人类无法看到的内容中，跨越每个爬取页面。检测 CSS 隐藏（`display:none`、`opacity:0`、屏幕外定位）、零宽度 Unicode 混淆、`alt`/`title`/`aria-label` 属性有效载荷和 HTML 注释。 |
| llms.txt 文件 | 12 | 发布的文件为代理提供网站的精选地图。参见 [llmstxt.org](https://llmstxt.org)。 |
| robots.txt 对 AI 爬虫的立场 | 12 | 对 AI 爬虫（如 GPTBot 和 ClaudeBot）的明确允许或禁止规则。 |
| 结构化数据（JSON-LD） | 12 | 机器可读数据，让代理可以直接理解页面内容| 责任链接 | 9 | 可达的联系、隐私、条款或关于链接。 |
| 站点地图 | 5 | 可达的 /sitemap.xml，以便爬虫可以发现整个网站。 |
| 可答性 | 5 | FAQ、QA 或 HowTo 结构化数据，内容形状 AI 答案引用最便捷。 |
| Meta robots | 5 | 没有意外的 `noindex`/`noai` 指令隐藏网站免受索引。 |
| MCP 信号 | 0 | 信息性：网站是否宣传 MCP 或面向代理的端点。在约定年轻时未评分。 |
## 示例输出
```
$ npx agent-readiness-auditor example.com
https://example.com 的代理就绪度审计
✅ 没有隐藏的提示注入有效载荷 (40/40)
⚠️ llms.txt 已存在 (0/12)
⚠️ robots.txt 涉及 AI 爬虫 (0/12)
⚠️ 机器可读的结构化数据 (0/12)
⚠️ 责任表面存在 (0/9)
⚠️ 站点地图存在 (0/5)
⚠️ 内容结构化为 AI 答案 (0/5)
✅ 没有意外的索引阻止 (5/5)
✅ 代理端点已宣传（信息性） (0/0)
分数：45/100（45%） 等级 D
```
每行显示、分数和（当检查未完全通过时）建议的修复。
## 快速入门
如果您已安装 [Node.js](https://nodejs.org) 18 或更高版本，您可以在一行中运行该工具而无需安装任何内容：
```bash
npx agent-readiness-auditor example.com
npx agent-readiness-auditor example.com --json
```
使用裸域名（`example.com`）或完整 URL（`https://example.com`）。`--json` 标志打印机器可读输出，以便在脚本中使用。
## 批量审计多个网站
批量模式读取一个文本文件，每行一个 URL（以 `#` 开头的行将被忽略），并一次审计几个。
```bash
agent-audit --batch sites.txt # 每个网站一份报告
agent-audit --batch sites.txt --csv # 每个网站一行 CSV
agent-audit --batch sites.txt --json # 结构化结果
```
CSV 有一列用于每个检查，这使其可以轻松打开在电子表格中或馈入分析。
## 在 GitHub Actions 中使用
该存储库同时作为 GitHub Action，因此任何项目都可以在每次推送或按计划审计其自己的网站，并在出现严重安全问题时失败构建。
```yaml
steps:
- uses: actions/setup-node@v4
with:
node-version: 20
- uses: asish-singh/agent-readiness-auditor@v0.4.1
with:
url: example.com
fail-on: safety # 或 "never" 以报告但不失败
```
无法访问的网站会产生警告，而不是失败，因为 CI 运行器上的机器人保护是一个，而不是安全问题。该存储库每周一在 [audit-site.yml](.github/workflows/audit-site.yml) 中使用该操作。
## 从 AI 助手（MCP）使用
审计工具附带了一个用于模型的服务器，这是让 AI 助手使用外部工具的标准，并且在 [官方 MCP](https://registry.modelcontextprotocol.io) 中列出。该工具的发现之一是，在 69 个知名网站中，没有一个宣传代理端点，因此审计工具将其自身保持在所衡量的标准上。连接后，您可以简单地要求您的助手为您审计一个网站。
对于 Claude Code，一条命令连接它。
```bash
claude mcp add agentuditor -- n agent-readiness-auditor mcp
```
对于，请将以下内容添加到配置文件的 `mcpServers`json
{
"agent-readiness-auditor "command": "npx",
"args": ["-y", "agent-readiness-auditor", "mcp"]
}
}
```
服务器公开一个工具，`audit_site它接受一个 URL 并返回与命令行相同的分数和发现。
## 从源码运行
要开发代码或从本地副本运行：
```bash
git clone https://github.com/asish-singh/agent-readiness-auditor.git
cd agent-readiness-auditor
npm install
npm run audit -- example.com # 人类可读报告
npm run audit -- example.com --json # JSON 输出
```
命令中的 `--` 将 URL 传递给工具，而不是 npm。
要从本地副本安装全局 `agent-audit` 命令：
```bash
npm run build # 将 TypeScript 编译为 dist/
npm link # 注册全局命令
```
然后，您可以从任何文件夹运行 `agent-audit example.com`。要稍后删除它，请运行 `npm unlink -g agent-readiness-auditor`。
## 从 GitHub Packages 安装
该软件包也发布到 GitHub Packages 作为作用域镜像，`@asish-singh/agent-readiness-auditor`。对于大多数人来说，上面的 npm 安装更简单。如果您的组织标准化了它，请仅使用 GitHub Packages，因为它需要身份验证甚至对于公共软件包也是如此。
要从中安装，请创建具有 `read:packages` 作用域的 GitHub 个人访问令牌，然后将作用域指向 GitHub 注册表：
```bash
echo "@asish-singh:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> .npmrc
npm install @asish-singh/agent-readiness-auditor
```
## 退出代码
该工具设置其退出代码，以便可以在自动化管道中使用：
- `0`：审计运行且未发现严重安全故障。
- `2`：发现严重安全故障（例如，隐藏的提示注入文本）。使用此方法使构建失败。
- `1`：工具无法完成审计（例如，网站无法访问）。
## 代码组织方式
每个检查都位于 `src/checks/` 下的单独文件中，并返回结构化结果。所有检查都在 `src/audit.ts` 中的单个列表中注册，总分数由此列表导出，因此添加新检查不需要更改评分逻辑。架构决策记录在 [`docs/adr/`](docs/adr/) 中，产品决策记录在 [`docs/decisions/`](docs/decisions/) 中，计划工作记录在 [`ROADMAP.md`](ROADMAP.md) 中，上市计划记录在 [`LAUNCH.md`](LAUNCH.md) 中。
## 背景
该工具源自 [Agentic Web Governance Pack](https://github.com/asish-singh/agentic-web-governance-pack)，这是一套关于网站如何应对 AI 代理的指南。该项目将其中几个指南转化为可以运行和衡量的检查。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
