本地工作区与 MCP

本地 AI 工作区是确定性、无模型的能力层：它为工具提供有边界的 Markdown 根目录、可检查索引与显式写权限，不暴露任意 shell 执行。整个流程不需要模型、API key、端点、向量服务或网络。

初始化、索引与审计

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

ai init 创建 wiki/ 与被忽略的 .silen/ai/ 缓存，不修改已有 MDX；ai index 重建可选的 .silen/ai/index.json 工作区快照；ai audit 检查链接、引用、生成产物与生产契约。快照缺失或过期只会成为提示，因为 MCP 搜索使用内存索引。

构建、审计与评测

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；它不会启动 MCP，也不会调用模型或网络。版本 1 在 topK 内使用单一路由与可选标题；版本 2 增加可选的 expected.maxRank。严格的 "schemaVersion": 3 要求同时提供 acceptable 与 forbidden 数组、两者至少包含一个目标，并显式设置 1 到 topK 之间的 maxRank。纯负例使用 acceptable: [] 与 maxRank: topK。

版本 3 在没有可接受目标时报告 matchedRank: null，并把禁止命中列入 forbiddenMatches。退出码 0 表示全部通过，1 表示检索预期失败，2 表示套件或输入无效；完整诊断 Top K 保持稳定的案例顺序。

Silen 仓库使用 pnpm site:ai-check 组合完整只读门禁，并把评测原始 JSON 保存到 artifacts/ai-eval/site-ai-eval.json。可选的 .silen/ai/index.json 快照仍是非阻断能力，不会替代生产搜索索引。

连接 MCP 客户端

从仓库根目录启动：

{
  "mcpServers": {
    "silen": {
      "command": "pnpm",
      "args": ["silen", "mcp", "docs"]
    }
  }
}

默认服务注册七个只读工具：guide、list、search、read、backlinks、citations、build。build 是有边界的预检，只读取 Markdown 输入与现有产物，不加载项目配置、不执行 MDX、不调用 Vite，也不写文件。

协议与结构化结果

该命令使用稳定的拆分版 TypeScript SDK v2。同一个 stdio 入口接受已验证的 legacy 2025-11-25 与 modern 2026-07-28 客户端；版本规则见官方协议版本指南。服务默认只读。每次成功调用都同时返回文本与经过 schema 校验的 structuredContent，每个工具都声明 outputSchema；不启用远程传输。

字符串结果的 guide 在 modern 客户端中保持原生字符串，在 legacy 客户端中由 SDK 兼容包装为 { result: ... }；对象结果工具在两个协议时代保持原有结构。

实验性 Skills over MCP

文件系统安装不依赖 MCP。明确支持 Resources 草案绑定的 Host 可以选择暴露同一份包内字节：

pnpm silen mcp docs --experimental-skills-over-mcp

该实验声明 io.modelcontextprotocol/skills，提供 skill://index.json，并把五个文件映射到 skill://silen-docs-readonly/ 下。它只使用本地 stdio 并保持只读；该实验默认关闭，不增加工具、脚本、订阅、网络传输或写权限；--allow-write 仍是独立的显式工具注册开关。

谨慎授权写入

pnpm silen mcp docs --allow-write

显式参数会增加 write、link、append。写入只接受工作区相对 .md/.mdx 路径，拒绝目录穿越和逃逸符号链接，使用原子替换，并限制为 2 MiB UTF-8；它不会增加 shell 工具。

只在边界明确的任务中授权可信本地客户端。修改后运行 audit 与站点构建，检查 Git diff，并在提交或部署前另行取得授权。

Ask AI 是独立能力，必须显式配置端点；没有端点时，Silen 不会输出控件及其 bundle。

客户端发现规则见 Agent Contract。