集成
Silen 让集成保持显式：插件运行可信构建或客户端代码，分析在站点层配置，Ask AI 只访问你自己运营的端点。三者都不需要导入 Silen 内部文件。
插件
插件是 .silen/config.ts 中有序排列的工厂，用于 MDX 处理器、Vite 集成、页面元数据、head、客户端 setup 或构建后产物：
import { defineConfig } from '@aicode-nexus/silen'
import readingTime from './plugins/reading-time'
export default defineConfig({
plugins: [[readingTime, { wordsPerMinute: 250 }]],
})
每个插件必须有 name，配置多个实例时增加 id。钩子按配置顺序运行，失败信息会包含插件身份与钩子名称。完整说明见插件生命周期。
站点分析
分析与主题无关，只在生产构建中输出。可配置 Google、百度或有序的自定义 provider：
analytics: [
{ provider: 'google', id: 'G-XXXXXXXXXX' },
{ provider: 'baidu', id: 'site-id' },
]
Silen 上报初始页面和客户端路由变化，忽略仅 hash 变化。Google 用户应关闭 Enhanced Measurement 中的自动 history-change pageview，避免重复。自定义 provider 可加载外部或内联脚本并监听 silen:pageview。脚本是公开可信代码，不要放密钥。
Ask AI
Ask AI 是可选主题端点，不捆绑模型 provider：
themeConfig: {
ai: {
endpoint: '/api/ask'
}
}
Ask AI 请求
Silen 通过 HTTP POST 发送 Content-Type: application/json 请求。请求契约严格如下：
interface AskAiRequest {
route: string
selectedText?: string
messages: Array<{
role: 'user' | 'assistant'
content: string
}>
}
selectedText 是可选字段；读者未选择正文时应省略。messages 可以包含之前的 user 与 assistant 对话。具体请求示例：
{
"route": "/guide/",
"selectedText": "pnpm silen init docs",
"messages": [
{ "role": "user", "content": "如何开始？" },
{ "role": "assistant", "content": "先安装依赖。" }
]
}
Ask AI 响应
成功的流式响应必须使用 Content-Type: application/x-ndjson 或 Content-Type: application/ndjson。每行写入一个 JSON 对象。事件形状分别是文本 { type: 'text', value: string }、引用 { type: 'citation', title: string, url: string } 与错误 { type: 'error', message: string }：
{"type":"text","value":"Install with pnpm."}
{"type":"citation","title":"Quick start","url":"/guide/"}
{"type":"error","message":"Unable to answer."}
Silen 会向请求提供 AbortSignal，并在新请求取代旧请求或对话框关闭时触发 abort。把该信号与 HTTP 连接断开视为取消：停止上游 provider 工作并释放资源。
端点负责服务端鉴权。provider key 与原始 provider 错误必须留在服务端，只返回安全的公开错误。未配置端点时，不会生成 Ask AI 控件，也不会生成 Ask AI 客户端 bundle。