asish-singh/agent-readiness-auditor

# Agent Readiness Auditor [](https://www.npmjs.com/package/agent-readiness-auditor) [](https://github.com/asish-singh/agent-readiness-auditor/actions/workflows/ci.yml) 一个命令行工具，用于扫描网站并评估其与自动化 AI agent 的协作能力，以及防御 AI agent 攻击的能力。 ## 解决的问题 AI 助理越来越多地代替用户访问网站：阅读页面、遵循页面上的指令并执行操作。这给网站所有者带来了两个实际问题： 1. **安全性。** 网页上可能包含对人类访客隐藏，但仍会被 AI agent 读取的文本。这些隐藏的文本可能携带旨在劫持 agent 的指令。这被称为间接 prompt 注入（indirect prompt injection）。 2. **机器可读性。** 网站通常是为人类视觉设计的。如果网站同时发布关于其内容和规则的机器可读信号，AI agent 的表现会更好。 标准的 SEO 工具衡量的是网站对搜索引擎的友好程度。而本工具衡量的是完全不同的东西：网站对 AI agent 的友好程度，以及它对 AI agent 的阅读是否安全。 ## 检查内容 该工具会获取指定的 URL 并运行五项检查，最终给出一个 0 到 100 的分数以及从 A 到 F 的字母等级。安全性被特意赋予最高权重，因为一个会劫持 agent 但易于阅读的网站，比一个仅仅难以阅读的网站更糟糕。 | 检查项 | 分值 | 检查内容 | |---|---|---| | 隐藏的 prompt 注入文本 | 40 | 对人类隐藏的文本（例如 `display:none` 或 `opacity:0`），其中包含诸如“忽略之前的指令”等劫持 agent 的短语。 | | `llms.txt` 文件 | 15 | 发布的为 agent 提供站点精简结构的文件。参见 [llmstxt.org](https://llmstxt.org)。 | | `robots.txt` 对 AI 爬虫的立场 | 15 | 针对 AI 爬虫（如 GPTBot 和 ClaudeBot）的明确允许或禁止规则。 | | 结构化数据 (JSON-LD) | 15 | 让 agent 直接理解页面内容的机器可读数据。 | | 问责链接 | 15 | 可访问的联系方式、隐私政策、服务条款或关于本站的链接。 | ## 输出示例 ``` $ npx agent-readiness-auditor example.com Agent readiness audit for https://example.com ✅ No hidden prompt-injection payloads (40/40) ⚠️ llms.txt present (0/15) ⚠️ robots.txt addresses AI crawlers (0/15) ⚠️ Machine-readable structured data (0/15) ⚠️ Accountability surface present (0/15) Score: 40/100 (40%) Grade D ``` 每一行显示了检查结果、分数，以及（当检查未完全通过时）建议的修复方法。 ## 快速开始 如果您安装了 [Node.js](https://nodejs.org) 18 或更高版本，您可以直接运行该工具，无需进行任何安装： ``` npx agent-readiness-auditor example.com npx agent-readiness-auditor example.com --json ``` 使用纯域名（`example.com`）或完整的 URL（`https://example.com`）。`--json` 标志会输出可供脚本使用的机器可读格式内容。 ## 从源码运行 如果您想修改代码或在本地副本中运行它： ``` git clone https://github.com/asish-singh/agent-readiness-auditor.git cd agent-readiness-auditor npm install npm run audit -- example.com # human-readable report npm run audit -- example.com --json # JSON output ``` 命令中的 `--` 用于将 URL 传递给工具本身，而不是传给 npm。 要从本地副本安装全局命令 `agent-audit`： ``` npm run build # compile TypeScript into dist/ npm link # register the global command ``` 然后您就可以在任何文件夹下运行 `agent-audit example.com` 了。如果之后想要移除它，请运行 `npm unlink -g agent-readiness-auditor`。 ## 从 GitHub Packages 安装 该包还作为带作用域的镜像 `@asish-singh/agent-readiness-auditor` 发布到了 GitHub Packages 上。对于大多数用户来说，直接使用上述的 npm 安装方式更为简单。只有在您的组织将其作为标准时才使用 GitHub Packages，因为即使对于公开包，它也需要身份验证。 要从中安装，请创建一个具有 `read:packages` 权限的 GitHub 个人访问令牌，然后将该作用域指向 GitHub registry： ``` 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 ``` ## 退出代码 该工具会设置其退出代码，以便在自动化 pipeline 中使用： - `0`：审计运行完成，未发现严重的安全故障。 - `2`：发现了严重的安全故障（例如，隐藏的 prompt 注入文本）。可使用此代码来中断构建（fail a build）。 - `1`：工具无法完成审计（例如，网站无法访问）。 ## 代码组织结构 每个检查项都独立存放在 `src/checks/` 目录下的文件中，并返回一个结构化的结果。所有检查都在 `src/audit.ts` 的一个列表中注册，总分由该列表计算得出，因此添加新的检查不需要修改评分逻辑。架构决策记录在 [`docs/adr/`](docs/adr/) 中，计划的工作列在 [`ROADMAP.md`](ROADMAP.md) 中。 ## 背景 该工具源于 [Agentic Web Governance Pack](https://github.com/asish-singh/agentic-web-governance-pack)，这是一套关于网站应如何对待 AI agent 的指导方针。本项目将其中几项指导方针转化为可运行和衡量的检查规则。 ## 许可证 MIT。请参见 [LICENSE](LICENSE)。

标签：AI代理, GNU通用公共许可证, LLMOps, MITM代理, Node.js, Web审计, 动态分析, 提示词注入检测, 暗色界面, 自动化攻击