---
title: CLI
description: 命令行接口——init、build、doctor、audit 和 mcp。
canonical_url: https://next-ai-ready.vercel.app/zh/docs/api-reference/cli
url: https://next-ai-ready.vercel.app/zh/docs/api-reference/cli
last_updated: 2026-08-01
updated: 2026-08-01
author: next-ai-ready 团队
summary: 命令行接口——init、build、doctor、audit 和 mcp。
topics: [api, reference]
---

# CLI

`next-ai-ready` 提供用于构建、验证、审计和运行 AI 就绪站点的 CLI 命令。

## 命令

### `next-ai-ready init`

在项目中脚手架化 handler 桩文件和配置。

```bash
npx next-ai-ready init
```

创建：

- `ai-ready.config.mjs` — 带占位值的站点配置。
- `app/%5Fai-ready/` — route handler 桩文件（一行 re-export）。
- `app/api/actions/[name]/route.ts` — action 执行端点。
- `app/api/mcp/[transport]/route.ts` — MCP 服务器端点。
- `actions/index.mjs` — 带 `ping` 健康检查的 starter action 文件。

使用 `--force` 覆盖已有文件。

### `next-ai-ready build`

扫描内容、编译语义图谱并产出所有产物。

```bash
npx next-ai-ready build
```

产出：

- `.next-ai-ready/graph.json` — SemanticGraph。
- `.next-ai-ready/actions.manifest.json` — 带 JSON Schema 的 action 清单。
- `public/llms.txt` — 全站 LLM 索引。
- `public/llms-full.txt` — 完整内容（含正文；frontmatter 有 `questions` 时追加 `## FAQ`）。
- `public/openapi.json` — OpenAPI 3.1 规范。
- `public/tools.json` — 工具定义。
- `public/.well-known/ai-plugin.json` — 插件清单。
- `public/robots.txt` — AI 爬虫策略。

使用 `--silent` 抑制控制台输出（CI 中有用）。

典型的 `package.json` 配置：

```json
{
  "scripts": {
    "build": "next-ai-ready build && next build"
  }
}
```

### `next-ai-ready doctor`

验证你的配置、action 暴露规则和路由接线。

```bash
npx next-ai-ready doctor
npx next-ai-ready doctor --score   # 0–100 就绪分数 + 优先修复建议
npx next-ai-ready doctor --json    # 机器可读报告（含 actionItems）
```

检查项包括：

1. **配置** — `ai-ready.config.mjs` 及必填的 `site.name`、`site.baseUrl`、`site.description`。
2. **Actions** — 公开/私有统计；公开 action 缺少 `whenToUse` 时警告。
3. **构建产物** — graph、OpenAPI、`package.json` 是否含 prebuild。
4. **路由桩文件** — `app/%5Fai-ready/*` 与 `next.config` 中的 `withAiReady()`。
5. **Robots** — `public/robots.txt` **或** `app/robots.ts`（`emit.robots: false` 时不会因缺少静态文件误报）。
6. **MCP** — 生产环境未设置 `NEXT_AI_READY_MCP_TOKEN` 时警告。
7. **内容质量** — `noai`、JSON-LD helper、`updatedAt` / `author` 覆盖率。

发现**错误**时以代码 1 退出。警告不会导致非零退出。

使用 `--score` 时会打印 **Top fixes**（如添加 prebuild、配置 MCP token、补充 frontmatter）。

在 CI 中使用：

```yaml
# .github/workflows/ci.yml
- run: npx next-ai-ready doctor --score
```

### `next-ai-ready audit <url>`

按照浏览器、爬虫和 AI Agent 实际收到的响应审计一个已部署页面。

```bash
npx next-ai-ready audit https://example.com/about
npx next-ai-ready audit https://example.com/about --json
npx next-ai-ready audit https://example.com/about --version 2 --json
npx next-ai-ready audit https://example.com/about --version 3 --json
```

100 分报告会检查 HTML、`llms.txt`、两种 sitemap、`robots.txt`、Markdown
内容协商、已知 AI User-Agent、显式 `.md` URL、canonical 与响应头、
frontmatter、JSON-LD、description、H1、浏览器 404 语义和 Agent Markdown
恢复。每项都会返回证据 URL 与明确说明。

浏览器和 Agent 的缺失页行为会被独立验证：浏览器式 HTML 请求必须返回
`404`，而请求 Markdown 的 Agent 应获得有用的 `200 text/markdown` 恢复文档。
审计也会接受符合标准的等价发现元数据，而不是强制某个框架专用的
`Vary`、`Link` 与 `Content-Location` 组合。

Audit v1 仍是默认版本，其 JSON 字段、分数计算和基于错误的退出行为保持不变；
Agent 缺失页恢复仍是权重为零的建议项，因此已有解析器和 CI 阈值无需调整。

使用 `--version 2` 可显式启用稳定的 `next-ai-ready.audit.v2` schema。它将同一组
线上检查拆分为五个独立评分维度：

| 维度                 | 总分权重 |
| ------------------ | ---: |
| `discovery`        |  20% |
| `content-citation` |  25% |
| `structured-data`  |  15% |
| `agent-access`     |  30% |
| `capabilities`     |  10% |

v2 中每个警告或失败项都会返回针对性的 `recommendation`，通过项则为 `null`。
顶层分数是五个维度分数的加权总和。在 CI 已明确采用新 schema 和评分规则之前，
应始终显式传入 `--version 2`。

使用 `--version 3` 可启用 `next-ai-ready.audit.v3` schema。它会分别报告
Agent Readability、Semantic/AEO Quality 与 Agent Capability，警告不再获得
部分分数，并将检查标记为 `external-standard` 或
`next-ai-ready-enhancement`。顶层兼容分数是本地 Readability 预检结果；
官方 Vercel 外部评分以仓库固定的 `pnpm audit:vercel:site` 命令为准。v3
有意只做更小的本地预检，并不重新实现官方全部 25 项检查。

对于缺失页，v3 在 Agent Readability 中只评估与 Vercel 一致的
`200 text/markdown` 行为；更严格的 `noindex` 与恢复链接要求会作为
Semantic/AEO Quality 中独立的 `next-ai-ready-enhancement`，不会造成相对
外部标准的假失败。

必需项失败时命令以代码 1 退出，因此 JSON 输出可作为部署后的 CI 门禁。
警告只降低分数，不会让 CI 失败。

### `next-ai-ready mcp`

通过 stdio 启动 MCP 服务器，供本地桌面客户端使用。

```bash
npx next-ai-ready mcp
```

选项：

| 标志               | 说明                           |
| ---------------- | ---------------------------- |
| `--no-resources` | 跳过基于 graph 的页面资源和发现工具（启动更快）。 |

配合 Claude Desktop 使用：

```json
{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": ["next-ai-ready", "mcp"]
    }
  }
}
```

## 退出码

| 代码  | 含义                       |
| --- | ------------------------ |
| `0` | 成功。                      |
| `1` | 错误（缺少配置、无效 action、构建失败）。 |
| `2` | 未知命令。                    |