参考
本页是紧凑的运行参考；解释与完整示例请阅读链接的指南。
配置
| 字段 | 默认值 | 用途 |
|---|---|---|
title | Silen | 站点标题 |
description | 空 | 页面元数据 |
lang | en-US | 默认 BCP 47 语言 |
base | / | 规范化部署路径 |
siteUrl | 未设置 | canonical HTTP(S) origin |
outDir | .silen/dist | 相对内容根的输出目录 |
onBrokenLinks | error | error、warn、ignore |
themeConfig | {} | 导航、语言、首页、搜索、Ask AI |
analytics | [] | 有序生产分析 provider |
plugins | [] | 有序可信插件 |
ai.* | 开启 | AI 文件、Markdown、索引、契约 |
base 必须以 / 开头，不含 query/hash 或穿越路径，并规范为结尾斜杠。siteUrl 只能是 origin，不含凭证、路径、query 或 fragment。
CLI
| 命令 | 作用 |
|---|---|
silen init <root> | 安全创建起始配置与首页 |
silen dev [root] | 启动开发，支持 --host、--port |
silen build [root] | 校验并生成静态产物 |
silen preview [root] | 预览产物，支持 --host、--port |
silen ai <init|index|audit|eval> [path] | 管理并评测本地 AI 工作区 |
silen ai skills <destination> | 无覆盖地写出包内 silen-docs-readonly Skill |
silen mcp [root] | 启动只读 MCP；可选 --allow-write 与实验性 --experimental-skills-over-mcp |
包内可移植 Skill 位于 dist/agent/skills/silen-docs-readonly。只有显式使用
--experimental-skills-over-mcp 时才会提供
skill://silen-docs-readonly/SKILL.md；默认 Agent Contract 仍是
extensions: []。
MCP 与 Agent Contract
本地 MCP 命令使用 SDK v2 与 stdio，验证 2025-11-25 和 2026-07-28。
默认提供七个只读工具，加入 --allow-write 后增加三个写工具；成功调用同时返回
文本与经过校验的 structuredContent，不启用远程传输。
Agent Contract manifest 与 API 使用 schemaVersion: 2。manifest 声明协议版本
和空扩展集合，API 为每个工具声明 outputSchema。
AI 评测套件
.silen/ai-evals.json 是严格 JSON。版本 1 在 topK 内匹配单一路由与可选
标题；版本 2 增加可选的 expected.maxRank。版本 3 使用以下严格结构：
| 字段 | 要求 |
|---|---|
schemaVersion | 精确整数 3 |
topK | 整数 1..20 |
cases | 1 到 500 个有序案例 |
expected.acceptable | 必需数组，包含 0 到 20 个不重复目标 |
expected.forbidden | 必需数组，包含 0 到 20 个不重复目标 |
expected.maxRank | 必需整数 1..topK；纯负例必须精确等于 topK |
| 目标 | 严格 { route, heading? }；route 以 / 开头 |
两个目标数组至少有一个非空。规范化后的重复、数组内部重叠、acceptable 与
forbidden 之间的重叠，以及未知字段都无效。版本 3 报告保留有序 cases、
matchedRank、forbiddenMatches 与完整诊断 Top K；v1/v2 行为保持兼容。
评测仍然只读且不依赖模型。
仓库维护者运行 pnpm site:ai-check；其精确稳定报告位于
artifacts/ai-eval/site-ai-eval.json。
排错
本地链接正常，部署后失败。 检查托管路径是否匹配 base、正文根相对链接是否包含挂载路径，以及托管是否按原样提供嵌套 index.html。
canonical 路径重复。 siteUrl 只写 origin，路径只写在 base。
语言切换进入 404。 在每个语言 root 下创建完全镜像的路由，并加入翻译后的导航。
构建报告重复路由。 删除 topic.mdx 或 topic/index.mdx 之一；二者指向同一路由。
pnpm 提示忽略 esbuild 构建脚本，且 Silen 随后构建失败。 执行 pnpm approve-builds esbuild，只批准该依赖，然后重新安装并重试。如果构建已经成功，则无需批准。
MCP 没有写工具。 这是安全默认值。只有用户明确授权有边界的写任务后，才加入 --allow-write。