CLI 与部署

Silen 提供一组精简 CLI。通过项目包管理器运行，命令实现与 Agent Contract 就会始终匹配当前安装版本。

主要命令

pnpm silen init docs
pnpm silen dev docs --host 127.0.0.1 --port 5173
pnpm silen build docs
pnpm silen preview docs --port 4173

init <root> 写入起始配置与首页，不替换已有目标；dev [root] 启动基于 Vite 的开发服务；build [root] 校验并生成静态产物；preview [root] 提供包含路由与语言感知 404 的预览。服务命令支持 --host 和 --port，构建命令不会自动部署。

AI 工作区使用独立命令：

pnpm silen ai init docs
pnpm silen ai index docs
pnpm silen ai audit docs
pnpm silen ai eval docs
pnpm silen ai skills ./agent-skills
pnpm silen mcp docs

ai skills 必须指定父目录，只创建 silen-docs-readonly 且绝不覆盖；可选的 MCP Resource 暴露使用 pnpm silen mcp docs --experimental-skills-over-mcp，仍是实验能力 并默认关闭。

MCP 默认只读，只有可信用户显式加入 --allow-write 才会注册写工具。无模型的 ai eval 只读取 .silen/ai-evals.json 与 .silen/dist/search-index.json， CI 使用 --json；它不需要模型、API key、端点、向量服务或网络。

套件 "schemaVersion": 1 保持完整 topK 匹配；版本 2 支持逐案例 expected.maxRank，省略时默认等于 topK，并在保留完整诊断结果的同时 报告 matchedRank。

静态部署

把 docs/.silen/dist 的内容发布到任意静态托管，并让托管平台按生成结果提供 index.html 与资源。例如项目地址为 https://example.github.io/handbook/：

export default defineConfig({
  siteUrl: 'https://example.github.io',
  base: '/handbook/',
})

不要在 siteUrl 中重复 /handbook/。构建会组合 origin 与 base，用于 canonical、hreflang 与 x-default 语言替代、站点地图和基础 Open Graph/Twitter 元数据。Markdown 与 Agent Contract URL 仍是 base 相对路径。

上线前检查

仓库维护者只运行一个规范命令：

pnpm site:ai-check

它依次且只执行一次 site:build -> ai audit -> ai eval -> check:no-maps；pnpm site:check 只是兼容别名。Core CI、GitHub Pages 与 npm 发布都使用规范命令，audit 或评测失败会阻断部署和发布。

正式 .silen/ai-evals.json 使用 "schemaVersion": 3、显式 maxRank，以及必需的 acceptable 和 forbidden 目标数组。报告保留诊断 topK、稳定的 matchedRank 与禁止命中证据。只要评测器产出了有效 JSON， 每条工作流都会用 always 条件上传 artifacts/ai-eval/site-ai-eval.json，包括检索失败或后续 source map 检查失败的情况。

随后直接预览一个嵌套路由和一个不存在的路由，并检查 llms.txt 与 .well-known/silen/manifest.json。构建成功只证明文件已生成；直接访问才能 证明托管平台按预期 base 提供了它们。

Ask AI 仍然只通过端点接入；未配置端点时，不会出现控件或对应 bundle。

命令语法与排错见参考手册。