夜雨聆风过去，我们做文档站，默认只有一个读者：人。
AI Coding 普及之后，文档多了第二个读者：AI agent。于是，Silen 的第一阶段目标很明确：让同一份可信 MDX 同时生成给人阅读的页面，以及给 AI 使用的干净 Markdown、llms.txt、结构化索引和本地 MCP 工作区。
但当 AI 不再只是“读一下文档”，而是开始创建站点、迁移内容、维护链接、审计质量和准备部署时，新的问题出现了：
• AI 怎么知道当前安装版本到底支持哪些配置、CLI 和 API？ • Codex、Claude Code、Cursor 是否要各维护一份接入教程？ • AI 面对“创建、维护、审计、部署”时，应该按什么顺序执行？ • 哪些动作可以只读完成，哪些动作必须先得到明确授权？ • 团队需要阅读时长、站点地图、分析脚本或自定义页面数据时，是否只能修改框架内部代码？
Silen 0.1 稳定版给出的答案，是把文档工程再向前推进两层：Agent Contract 与公开插件系统。
截至 2026 年 7 月 15 日，npm 上的 @aicode-nexus/silen 已进入 0.1 稳定发布线，当前版本为 0.1.1。其中，Agent Contract、插件运行时、分析能力与相关质量门是在 0.1.0 稳定版中加入的；0.1.1 主要刷新稳定版 README，并将 changelog 一并带入仓库和 npm 包。
所以，这不是把 Alpha 后面的版本号简单删掉。
Silen 正在从“AI 可读的 React 文档框架”，变成一套让人类页面、AI 契约、插件扩展与本地执行边界共享同一可信源的文档工程。
从“第二个读者”到“可控的协作者”
上一阶段的核心问题是：AI 怎样读到正确内容？
网页主要为人设计。导航、主题按钮、客户端脚本和重复链接，对人是体验，对模型却可能是噪声。直接搜索仓库也不等于读对了：agent 能找到文件，却未必知道正式入口、页面顺序、公开边界和当前版本。
如果再维护一套独立的 AI 知识库，正文与 AI 版本又容易发生漂移。
Silen 原来的解法，是让 MDX 与 React 经过一次确定性构建，同时输出：
• 可在 hydration 前阅读的静态 HTML。 • 响应式主题与本地搜索。 • 与页面路由对应的 clean Markdown。 • 用于站点发现的 llms.txt。• 用于完整语料读取的 llms-full.txt。• 用于检索、分块和回链的 ai-index.json。• 默认只读、按需开放写权限的本地 MCP 工作区。
这解决了“读什么”。
0.1 稳定版继续解决“怎么做”：AI 先发现当前版本的契约，再读取准确的 API 与任务手册；需要操作本地项目时，通过受权限约束的 MCP 工作；团队需要扩展构建能力时，通过公开插件钩子接入，而不是依赖内部模块。
可以把新版 Silen 理解成四层：
1. 内容层：MDX 是人类页面和 AI 产物的共同可信源。 2. 契约层：manifest 告诉 AI 当前版本、公开资源、能力和任务边界。 3. 扩展层：插件把团队逻辑接入配置、MDX、Vite、页面数据和构建产物。 4. 执行层：MCP 负责有边界的本地读取与写入，提交和部署仍是单独授权。
真正重要的不是功能数量，而是这四层开始使用同一套确定性输入与版本边界。
Agent Contract：给所有 AI 客户端同一份说明书
一个 AI agent 要维护 Silen 项目，最不应该做的事情，是根据搜索结果猜 API。
今天读到的是最新版网页，项目里安装的可能是旧版本；博客里的配置可能来自 Alpha；不同编辑器插件又可能各自复制一套命令。最终看起来“都会用”，实际上每个客户端理解的 Silen 都不一样。
Agent Contract 解决的就是这类版本漂移。
第一层：包内契约，对应已安装版本
当 AI 操作本地 Silen 项目时，权威入口不是搜索引擎，而是已安装 npm 包中的：
@aicode-nexus/silen/agent/manifest.json0.1.1 包内 manifest 的 schemaVersion 为 1，并标记当前生成器版本。它继续链接到：
• agent/api.json：当前版本公开配置、CLI、MCP 与 TypeScript API 的机器可读描述。• 英文与中文 guide：给 agent 的框架级使用说明。 • 双语 task playbooks：按任务组织的执行手册。 • manifest 本身：资源位置、版本、任务和能力的发现入口。
“包内契约是已安装版本的权威来源”这句话非常关键。
当项目锁定 0.1.1 时，agent 就应该优先读取 0.1.1 包里的契约，而不是拿官网未来版本的用法直接修改当前项目。这样，AI 使用的配置项、命令和边界，能与实际依赖保持一致。
第二层：站点契约，对应已部署站点
当 AI 读取一个已部署站点时，关注点不同。它需要知道站点标题、base、语言、路由、已开启的 AI 产物、公开指令和可用能力。
Silen 在站点构建中定义的发现路径是：
/.well-known/silen/manifest.json如果站点部署在 /handbook/ 子路径下，发现地址也会跟随 base，成为：
/handbook/.well-known/silen/manifest.json这里要区分两种权威性：
• 包内 manifest 说明“这个项目安装的 Silen 版本能做什么”。 • 站点 manifest 说明“这个公开站点实际暴露了什么”。
一个面向本地工程，一个面向部署结果。AI 不必再从 HTML 导航、仓库结构或客户端专用说明中拼凑答案。
第三层：同一份契约服务多个 AI 客户端
Codex、Claude Code、Cursor 以及其他支持相应接入方式的客户端，应该读取同一份 manifest，并使用同一条 Silen MCP 命令。
这样做不是为了追求形式统一，而是减少三种真实成本：
• 不再为每个客户端复制一份可能过期的 API 表。 • 项目升级时，只需要让契约跟随包版本更新。 • 团队可以围绕同一套任务步骤和权限规则做测试、审计和复盘。
如果客户端不支持 manifest 声明的 schema 版本，Silen 也定义了保守降级路线：退回契约链接的公开 Markdown，并保持只读。
这比“尽量猜一个能跑的写法”更可靠。无法确认契约时，先读，不写；无法确认权限时，不扩大动作范围。
Agent Contract 也不是一张能保证模型绝对服从的魔法纸。它的价值，是给客户端提供版本化、可测试、可降级的操作描述，让错误更容易被发现，让权限更容易被检查。
六类任务手册：把“会做”变成“按边界做”
只有 API 列表还不够。
创建站点与维护站点，需要的不是同一组步骤；审计文档与部署文档，也不应该拥有同样的写权限。为此，Silen 0.1 在 Agent Contract 中提供六类内置任务手册：
• read-site：发现并读取站点内容。• create-site：从零创建 Silen 文档站。• migrate-content：迁移已有 Markdown/MDX 内容。• maintain-site：在现有站点中做最小范围维护。• audit-site：检查内容、链接、索引和构建状态。• deploy-site：准备并验证静态部署产物。
其中，read-site 与 audit-site 属于只读任务，不要求显式写授权；create-site、migrate-content、maintain-site 和 deploy-site 属于写任务，契约会声明需要明确授权。
这套设计把“能不能做”拆成了更清楚的层级。
例如，维护任务的推荐顺序不是直接批量改文件，而是：
1. 先通过只读 MCP 读取目标内容、引用和反向链接。 2. 确认写工具确实存在，并确认用户授权了本次写任务。 3. 只做满足目标所需的最小修改。 4. 重新读取修改结果。 5. 运行 audit 与 build。 6. 查看 Git diff，确认没有越界变化。 7. 未获得单独许可时，不提交、不推送、不部署。
同样，deploy-site 手册可以指导 agent 检查静态输出、base、资源路径和构建结果，但“准备好部署”不等于“已经获得向外部环境发布的授权”。
这是一处看似细小、实际很成熟的边界：写文件、提交 Git、推送远端、部署生产，是四个不同动作。
很多 AI 工作流的问题，不是模型不会改代码，而是把这些动作默认为一个连续权限。Silen 的任务契约主动把它们拆开，让客户端和团队都更容易建立可审计的操作习惯。
公开项目指令：可以定制，但必须按公开内容管理
框架级手册只能告诉 AI 如何使用 Silen，无法知道你的项目约定。
比如，某个团队可能要求“新页面必须有 owner”“迁移时保留旧 URL”“所有公开页面必须通过引用检查”。Silen 允许站点显式加入公开项目指令和自定义任务：
import { defineConfig } from '@aicode-nexus/silen'export default defineConfig({ ai: { contract: { enabled: true, instructions: '.silen/ai-public.md', tasksDir: '.silen/ai-tasks', }, },})这里有一条不能忽略的安全规则：这两个位置是公开构建输入。
不要在其中放入密钥、内网地址、本机绝对路径、私有仓库信息或只适合本地 agent 的指令。Silen 不会自动把 AGENTS.md、CLAUDE.md 或编辑器规则推断成公开契约，项目必须显式选择哪些内容可以发布。
这种“默认不猜、明确才公开”的规则，与 draft: true、ai: false 和 MCP 默认只读属于同一套产品判断：AI 能力应该建立在显式边界上，而不是建立在隐含扫描上。
插件系统：不改核心，也能扩展完整生命周期
Agent Contract 解决 AI 怎么发现和执行；插件系统解决团队怎么扩展 Silen 自身。
在早期版本里，如果团队需要阅读时长、特殊 MDX 转换、分析脚本、站点地图或额外构建元数据，最容易走向两条路：等待框架内置，或者直接依赖内部模块。
前者会让核心越来越重，后者会让升级变得脆弱。
Silen 0.1 开放了公共插件 runtime。插件可以是 .silen/config.ts 中定义的本地工厂，也可以是正常安装并显式 import 的 npm 包，不需要导入 Silen 内部文件。
一个最小插件可以这样写：
import { defineConfig, definePlugin } from '@aicode-nexus/silen'const readingTime = definePlugin( (_context, options: { readonly wordsPerMinute?: number }) => ({ name: 'reading-time', transformPageData(page, context) { const words = context.source .trim() .split(/\s+/u) .filter(Boolean).length const wordsPerMinute = options.wordsPerMinute ?? 250 return { data: { ...page.data, readingTimeMinutes: Math.max( 1, Math.ceil(words / wordsPerMinute), ), }, } }, }),)export default defineConfig({ plugins: [[readingTime, { wordsPerMinute: 250 }]],})definePlugin 主要提供类型推断与 API 可发现性，插件选项仍由插件自己拥有。插件按配置顺序执行，结果因此可以预测。
每个插件必须返回非空 name，并可通过 id 支持多实例。实例身份是 name:id，默认 id 为 default。如果两个插件实例身份重复，配置会失败，而不是悄悄覆盖；hook 抛错时，错误也会标出插件与具体 hook，方便定位。
这套身份和顺序规则很重要。插件系统最怕“装得上，但不知道谁先改、谁覆盖谁”。Silen 首版先把确定性做好，再谈更复杂的生态。
8 个有序 hook，覆盖从配置到构建产物
Silen 首版公开 8 个生命周期 hook：
1. config
在配置解析早期读取当前用户配置，并返回受支持的配置补丁。适合根据插件选项补充配置，但不能借此重写插件列表制造递归行为。
2. configResolved
配置完成校验后获得只读的 resolved config。适合做最终检查、准备后续阶段需要的状态，或在不修改配置的前提下建立集成信息。
3. extendMdx
向 MDX 编译链加入 Remark/Rehype 插件。适合自定义语法、标题处理、代码或链接转换，让 dev 与 build 使用同一套内容规则。
4. vite
接入标准 Vite 插件能力，处理模块解析、转换和构建集成。Silen 自己的 virtual:silen/* 命名空间仍由核心保护，插件不能冒充或覆盖框架内部虚拟模块。
5. clientModules
注册客户端扩展模块。模块可以提供 SSR-safe 的 wrapRoot，也可以提供仅在浏览器执行的 setup。
这里的边界非常具体：模块顶层与 wrapRoot 中不要直接访问 window 或 document；浏览器 API 应放在 setup。因为同一模块需要同时经过 SSR 与 hydration，SSR 安全不是建议，而是契约的一部分。
6. transformPageData
扩展页面数据。阅读时长、团队归属、内容等级、自定义检索字段，都可以从这里进入页面模型。
返回数据必须可以 JSON 序列化，因为它不只给某一个 React 组件使用，还会跨越服务端渲染、客户端 hydration、本地搜索和 AI 产物。
7. transformHead
向页面增加类型化的 head 节点，例如 metadata、canonical 或集成标签。它不开放任意最终 HTML 字符串替换，避免插件在最后一步绕过结构化边界。
8. buildEnd
只在生产 build 完成、核心输出已经安装到产物目录后执行。适合生成 sitemap、feed 或第三方集成元数据。
需要注意，buildEnd 可以写构建产物，也可能触发外部副作用。Silen 会为 hook 失败提供清楚归因，但不会自动回滚插件已经对外部系统做出的任意操作。插件作者仍需要自己设计幂等性与失败策略。
为什么插件系统也是 AI 能力
看到插件系统，很多人会把它归类为传统框架扩展：给页面加功能，和 AI 没有直接关系。
但 Silen 最值得关注的一点，恰恰是插件没有被做成只影响浏览器 UI 的“外挂”。
以 transformPageData 为例，一次扩展后的页面数据，会被四类消费者共同使用：
• SSR：生成完整静态 HTML。 • hydration：让客户端接管时使用同一份数据。 • search：让本地搜索读取一致的页面元数据。 • AI artifacts：让 Markdown、索引和相关机器可读产物共享同一页面模型。
假设团队写了一个插件，为每页增加 owner、productArea、stability 和 readingTimeMinutes。如果这些字段只出现在浏览器组件中，AI 仍然不知道页面归属和稳定性；如果只写入 AI 索引，人类页面又无法展示同样的信息。
Silen 的方向是：扩展一次，多端一致。
这会让插件生态与 AI 文档真正连接起来。插件不只是加一个统计脚本，也可以成为内容治理规则进入页面、搜索、索引和 agent 上下文的统一入口。
官方仓库已经提供三个源码级参考实现：
• reading-time：通过 transformPageData计算阅读时长。• sitemap：通过 buildEnd生成站点地图。• analytics-client：通过 clientModules注册浏览器端分析能力。
它们是可以整理成 npm 包的参考源码，但当前并不是已经独立发布的官方插件包。文章或项目中最好写“官方参考实现”，不要把它们描述成现成插件市场里的商品。
现在还不是插件市场，这反而要说清楚
0.1 提供的是插件契约、运行时、类型和示例，不是成熟插件生态的全部形态。
当前首版没有：
• 插件市场或在线安装器。 • 自动扫描已安装依赖并启用插件。 • presets 或插件 bundles。 • 由插件增加新路由或新内容类型。 • 由插件完全替换主题布局。 • 任意最终 HTML 字符串转换。
这意味着插件仍需要开发者显式安装、import 和配置。对于希望“一键安装几十个插件”的用户，它还不够成熟；但对于重视可追踪依赖、类型推断、执行顺序和升级边界的工程团队，这种起点更稳。
插件也继承了 MDX 的信任模型：Silen 面向可信工程源文件，不是用来直接执行不可信用户投稿的沙盒。引入第三方插件，本质上是在构建环境中执行第三方代码，依赖审核、版本锁定和供应链治理仍然不可省略。
20 分钟做一个 AI-ready、可扩展的文档站
理解新版最好的方式，不是一次迁移整个知识库，而是拿一个真实、可控的 docs/ 目录完成一条最小链路。
第一步：确认环境并安装
当前版本要求 Node.js：
^20.19.0 || >=22.12.0仓库使用 pnpm 10.34.0，React 与 React DOM 的 peer dependency 为 ^19.2.7。
安装并启动：
pnpm add -D @aicode-nexus/silenpnpm silen dev docs先让现有 Markdown/MDX 正常生成路由，确认导航、本地搜索、代码高亮和移动端阅读没有问题。
第二步：开启并检查 Agent Contract
在 docs/.silen/config.ts 中保留 AI 产物，并按需加入公开项目指令：
import { defineConfig } from '@aicode-nexus/silen'export default defineConfig({ title: 'My documentation', ai: { llmsTxt: true, llmsFullTxt: true, markdownRoutes: true, index: true, contract: { enabled: true, instructions: '.silen/ai-public.md', tasksDir: '.silen/ai-tasks', }, },})如果还没有经过公开性审查，就先不要配置 instructions 和 tasksDir。契约可以启用，但项目私有规则不应为了“让 AI 更聪明”被误发到公开站点。
第三步：加入一个本地插件
先从 reading-time 这类无外部副作用的插件开始。确认页面数据能在 SSR、客户端与构建产物间保持一致，再考虑 sitemap、analytics 或更复杂的 MDX 转换。
插件调试时重点检查：
• 插件 name:id是否唯一。• hook 顺序是否符合配置顺序。 • 页面数据是否可以 JSON 序列化。 • 客户端模块是否满足 SSR 安全。 • buildEnd 是否可重复执行，失败时是否会留下不完整外部状态。
第四步：构建、预览和审计
pnpm silen build docspnpm silen preview docspnpm silen ai audit docs如果部署在 GitHub Pages 子路径，记得设置 base，并检查 HTML、静态资源、Markdown 路由、llms.txt 与 contract 资源是否使用同一子路径。
审计时至少看五件事：
1. 草稿和 ai: false页面是否被排除。2. 页面标题、路由、链接和引用是否稳定。 3. llms.txt是否能让客户端发现主要入口。4. ai-index.json的分块、元数据和来源能否支持检索。5. 插件写入的页面数据与构建产物是否符合预期。
第五步：最后接入本地 MCP
{ "mcpServers": { "silen": { "command": "pnpm", "args": ["silen", "mcp", "docs"] } }}先让客户端通过 manifest 读取当前版本契约，再用 MCP 完成 list、search、read、backlinks 和 citations。只有当读取与引用质量稳定、团队明确授权写任务，并且保留 Git diff 评审时，再考虑开放写工具。
安全底座没有因为“能力更多”而后退
新版增加了 Agent Contract 与插件能力，但原有 AI 安全边界仍然保留。
公开 AI 产物仍然可控
Silen 的生产构建仍可以输出 llms.txt、llms-full.txt、clean Markdown routes 和 ai-index.json。这些产物在构建阶段确定性生成，默认不调用模型，也不需要 API key。
页面可以通过 frontmatter 排除：
draft: true或者：
ai: false这两个标记会让对应页面离开公开 AI 产物。团队仍然需要审查源内容与公开边界，不能因为有 manifest 就默认所有知识都适合发布。
MCP 仍然默认只读
默认启动：
pnpm silen mcp docs服务端只注册 7 个只读工具：
guidelistsearchreadbacklinkscitationsbuild其中 build 是安全预检：读取有界 Markdown 输入与已有产物，不加载项目配置、不执行 MDX、不调用 Vite，也不写文件。
只有显式运行：
pnpm silen mcp docs --allow-write才会增加 write、link、append 三个写工具。
即使开放写入，工具也只接受工作区相对的 .md 或 .mdx 路径，拒绝路径穿越和逃逸到工作区外的符号链接，使用原子替换，限制单次 UTF-8 内容大小，并且不提供任意 shell。
这与 Agent Contract 的任务授权形成了双重边界：契约告诉客户端“任务是否需要授权”，MCP 决定“写工具是否真的存在”。
Ask AI 仍是 endpoint-only
Silen 的 Ask AI 继续采用可选服务端 endpoint：
export default defineConfig({ themeConfig: { ai: { endpoint: '/api/ask' }, },})前端只向该 endpoint 发送当前路由、选中文本和消息历史；provider key 留在服务端，不进入 .silen/config.ts，也不进入静态客户端 bundle。
未配置 endpoint 时，Silen 不输出 Ask AI 按钮，也不会把相关客户端代码打进页面。
这再次强调了 Silen 的顺序：先把来源、路由、索引、契约和权限做好，再决定要不要加聊天界面。
哪些团队最值得现在试
多种 AI Coding 客户端并存的团队
团队成员同时使用 Codex、Claude Code、Cursor，不希望为每个客户端维护一套易过期的框架说明。Agent Contract 可以让它们从同一版本化入口开始工作。
React 项目、组件库与开发者产品
文档需要 MDX 与 React 交互能力，同时还要给 agent 提供准确的配置、命令、引用和版本边界。插件系统又允许团队加入自定义页面数据、分析与构建集成。
内部研发手册与工程规范
团队已经使用 Markdown/MDX，希望把网页阅读、本地搜索、AI 索引、CI 审计、MCP 维护和项目任务规则放进同一条工程链。
课程、知识库和需要结构化治理的文档
内容既要正式发布，也要被 AI 检索、引用和辅助学习；团队还需要通过插件增加 owner、难度、稳定性或课程模块等元数据。
哪些需求暂时不要硬上
如果你需要成熟 CMS、复杂权限后台、评论系统、多人非技术编辑与完整商业内容运营，Silen 仍不是这一类平台。
如果你依赖插件市场、一键在线安装、自动发现、插件新增内容类型或完整替换主题布局，0.1 的插件系统还没有走到那里。
如果内容来自不可信用户投稿，MDX 与构建插件的可执行能力意味着你需要额外隔离，不能把 Silen 本身当作安全沙盒。
如果文档目录本身缺少标题、归属、公开边界和维护责任，Agent Contract 也不会自动替团队完成知识治理。它能让规则更稳定地被发现和执行，却不能替你决定哪些内容正确、哪些内容过期。
一份更稳妥的采用清单
如果准备在真实项目里试用，可以按这个顺序推进：
1. 选一个真实但范围可控的 docs/目录。2. 先完成静态页面、路由、本地搜索和移动端检查。 3. 审查 draft: true、ai: false与公开内容边界。4. 从包内 manifest 验证当前安装版本的 API 与任务手册。 5. 构建站点契约，但只加入确认可公开的项目指令。 6. 让 AI 客户端先完成只读发现、搜索、引用和审计。 7. 从 reading-time 这类本地插件验证扩展链。 8. 检查插件数据是否同时进入 SSR、hydration、搜索与 AI 产物。 9. 只有在目标明确、工具存在、用户授权时才开放 MCP 写入。 10. 把写文件、Git 提交、远端推送和外部部署分别授权。
这条路径不要求一次替换所有文档基础设施，却能完整验证 Silen 最有价值的判断：同一份项目知识，是否可以稳定地服务人类读者、AI 客户端和团队自己的扩展逻辑。
最后
Silen 0.1 稳定版的意义，不只是多了几个 AI 功能，也不只是终于能写插件。
它开始回答一个更完整的问题：
当 AI 从文档的第二个读者变成协作者时，文档系统怎样同时提供可信内容、版本化说明、可扩展生命周期和明确权限？
Silen 的答案是：
• 用 MDX 维持人类页面与 AI 产物的同源。 • 用 Agent Contract 统一版本发现、API 与任务手册。 • 用插件 hook 承载团队自己的内容与构建扩展。 • 用默认只读 MCP 和显式授权控制本地执行。 • 用 audit、build 与 Git diff 把质量重新交回工程流程。
如果你的文档已经不只是“给人看”，而是正在成为 AI Coding 的项目上下文，可以从一个目录和一个本地插件开始：
pnpm add -D @aicode-nexus/silenpnpm silen dev docs先让内容成为可信源，再让契约、插件和 agent 围绕它协作。
参考资料
• Silen 官网：https://aicode-nexus.github.io/silen/ • Silen 中文 AI 指南：https://aicode-nexus.github.io/silen/zh/ai/ • Silen 中文插件指南：https://aicode-nexus.github.io/silen/zh/guide/plugins/ • Silen GitHub：https://github.com/AICode-Nexus/silen • npm 包：https://www.npmjs.com/package/@aicode-nexus/silen 
