跳到正文

AI-ready 文档

Silen 把 AI 访问视为文档构建的一部分，而不是事后补上的功能。默认输出是 确定、可检查的，并且不会调用模型。核心 AI-ready 文档流程不需要模型、API key、 端点、向量服务或网络。

Agent Contract

Silen 为 AI 提供一个带版本的发现入口，不需要为每一种客户端重复维护一份教程：

  • 操作本地项目时，先读取已安装包中的 @aicode-nexus/silen/agent/manifest.json。它会链接到准确的配置、CLI、 MCP、公开 TypeScript API，以及 agent/tasks/create-site.md 等任务手册。
  • 读取部署站点时，先访问 /.well-known/silen/manifest.json。当前官方站点的 地址是 /silen/.well-known/silen/manifest.json。
  • 在本地进行有边界的读取时，启动 pnpm silen mcp docs。除非用户显式添加 --allow-write，否则它始终只读。

Codex、Claude Code 与 Cursor 都应读取同一份 manifest，并使用同一个本地 MCP 命令。各客户端只保留轻量接入配置，API 真相始终由 Agent Contract 提供。

如果客户端不支持声明的契约版本，必须退回链接的公开 Markdown，并保持只读。

当前 manifest 与 API 使用 schemaVersion: 2，声明本地 stdio、已验证的 2025-11-25 与 2026-07-28 协议版本、空扩展集合，以及每个 MCP 工具的 outputSchema。

只读 Agent Skill

npm 包会从规范的中英文 read-site 与 audit-site 任务包确定性生成唯一的 silen-docs-readonly Agent Skill。包内路径是 dist/agent/skills/silen-docs-readonly，其中只有 SKILL.md 和四个按需读取的 参考文件，不包含脚本、资产、写任务、模型调用、凭据或隐含权限。

sh
pnpm silen ai skills ./agent-skills

该命令只创建 ./agent-skills/silen-docs-readonly；如果目录已经存在就直接失败， 不会覆盖。文件系统形式是受支持的可移植能力，并且可离线使用。

添加公开项目指令

只发布对所有站点访问者都安全的内容：

ts
export default defineConfig({
  ai: {
    contract: {
      instructions: '.silen/ai-public.md',
      tasksDir: '.silen/ai-tasks',
    },
  },
})

这些文件会成为显式公开的 Agent 指令。不要写入私有路径、密钥、内部端点或凭据。

面向 AI 的公开产物

每次生产构建都可以输出：

  • llms.txt，用于精简页面地图
  • llms-full.txt，用于完整可读内容
  • ai-index.json，用于结构化发现
  • 每个公开页面对应的干净 Markdown 路由

标记为 draft: true 或 ai: false 的页面会从这些产物中排除。

复制给 AI

默认主题允许读者复制干净的页面 Markdown，或复制带规范来源 URL 的 prompt-ready 版本。复制内容来自同一套构建产物，因此会和渲染页面保持一致。

本地 MCP 工作区

sh
pnpm silen ai init docs
pnpm silen ai index docs
pnpm silen ai audit docs
pnpm silen ai eval docs
pnpm silen mcp docs

MCP 服务使用拆分后的 SDK v2，并且默认只读。只有显式使用 --allow-write 启动时，写入工具才会出现；所有写入仍被限制在 Markdown 工作区内。成功调用会 同时返回文本和经过 schema 校验的 structuredContent，不启用远程传输。

无模型质量门禁

直接把生产搜索索引作为确定性的检索契约：

sh
pnpm silen build docs
pnpm silen ai audit docs
pnpm silen ai eval docs

ai eval 只读取已提交的 .silen/ai-evals.json 与构建生成的 .silen/dist/search-index.json，不会调用模型或网络。退出码 0、1、2 分别表示通过、检索失败、初始化或配置失败。

版本 1 保持完整 topK 匹配；版本 2 增加可选的 expected.maxRank，并报告 生效值与 matchedRank。严格的 "schemaVersion": 3 要求两个目标数组与显式 排名边界：

json
{
  "schemaVersion": 3,
  "topK": 5,
  "cases": [
    {
      "id": "install-quick-start",
      "query": "如何安装并启动站点？",
      "expected": {
        "acceptable": [
          { "route": "/zh/guide/", "heading": "快速开始" },
          { "route": "/zh/guide/cli-deployment/" }
        ],
        "forbidden": [{ "route": "/zh/draft-notes/" }],
        "maxRank": 1
      }
    }
  ]
}

acceptable 与 forbidden 都必须出现，每个数组可包含零到 20 个目标，但两者 不能同时为空。至少一个可接受目标必须在 maxRank 以内出现，所有禁止目标都不能 进入诊断 Top K。纯负例使用 acceptable: [] 与 maxRank: topK。未知字段、 重叠目标、空目标集合和非法边界都会成为初始化错误。版本 3 保持案例编写顺序， 并输出 matchedRank 与 forbiddenMatches；v1/v2 的 JSON 与人类可读输出保持 兼容。

本仓库使用 pnpm site:ai-check 一次完成构建、审计、评测和 source map 检查， 并把评测器的原始 JSON 保存到 artifacts/ai-eval/site-ai-eval.json，供 CI、Pages 与发布流程比较。

可重建的 .silen/ai/index.json 只是可选工作区快照。缺失或过期只会成为 audit 提示，MCP 搜索仍使用内存索引。

Ask AI

Ask AI 是可选的端点集成。Silen 不会把 provider key 放进生成站点：你的服务端 负责鉴权，并把一套小型 NDJSON 协议流式返回给主题。未显式配置端点时，Ask AI 控件及其 bundle 都不会出现。

返回 快速开始指南。