安装方式

命令行安装

在项目根目录执行以下命令，完成 Skill 安装。

npx bzskills add BrainBlend-AI/tesseron --skill update-docs

ZIP 包安装

点击下方按钮下载 ZIP 包，并解压到本地 Skills 目录。

下载 ZIP 包 →

# 下载 update-docs.zip
unzip update-docs.zip -d ./skills

skill.md

name: update-docs
description: 在 `packages/**` 源码发生任何变更，导致 Tesseron 的公共表面（协议消息、导出的类型、action/resource 构建器 API、ActionContext 方法、传输层、gateway CLI 标志或 React hooks）发生变化时，使用此技能同步 `docs/src/content/docs/`，使 Starlight 站点与代码保持一致。触发条件包括“update the docs”、“sync docs”、“docs are stale after this change”，或当会话结束时存在公共表面的编辑但缺少相应的文档编辑。对于仅涉及测试、工具或内部重构且公共表面未变的变更，请勿触发。

更新 Tesseron 文档

保持 docs/src/content/docs/ 与 packages/** 中刚刚发生的更改保持一致。文档是已发布的 Starlight 站点以及 Tesseron 用户阅读的契约，因此这里的偏差对用户是可见的。

前置条件

最近对 packages/** 的编辑（使用 git diff / git diff --stat HEAD 查看变更集）。
文档树位于 docs/src/content/docs/。如果缺失，请停止并标记。

文档页面及其所属内容

页面	所属内容
`overview/index.mdx`（根目录的 `index.mdx`）	电梯演讲、英雄文案、顶级链接。极少变动。
`overview/architecture.mdx`	三进程模型图、协议边界描述。
`overview/quickstart.mdx`	五分钟上手路径：安装、声明一个操作、运行网关、看到 Claude 调用它。
`overview/why.md`	与浏览器自动化 / Playwright / 聊天小部件的定位对比。
`protocol/index.mdx`	单页协议概述。当新增顶级概念时更新。
`protocol/wire-format.mdx`	JSON-RPC 信封、方法名、id 规则。
`protocol/transport.md`	WebSocket URL、帧结构、来源允许列表、重连行为。
`protocol/handshake.mdx`	`tesseron/hello`、`welcome`、声明代码、`tools/list_changed`。
`protocol/actions.mdx`	操作声明、命名空间、调用 / 验证 / 返回。
`protocol/progress-cancellation.mdx`	`actions/progress`、AbortSignal、`actions/cancel`。
`protocol/sampling.mdx`	处理程序重新进入 agent 的 LLM。
`protocol/elicitation.mdx`	`ctx.confirm` 和 `ctx.elicit`。
`protocol/resources.mdx`	可读 / 可订阅的资源投影。
`protocol/errors.mdx`	每一个已定义的错误码及其触发条件。
`protocol/lifecycle.mdx`	会话状态机，挂起工作会发生什么。
`protocol/security.mdx`	来源强制、声明流程、信任边界。
`sdk/typescript/index.mdx`	安装、`packages/` 概览、第一个操作代码片段。
`sdk/typescript/action-builder.md`	`tesseron.action(...)` 流畅 API。
`sdk/typescript/standard-schema.md`	Zod / Valibot 等适配器管道。
`sdk/typescript/context.md`	`ActionContext` 方法：进度、采样、确认、引出、信号。
`sdk/typescript/resources.md`	`tesseron.resource(...)` 构建器、订阅契约。
`sdk/typescript/core.md`	`@tesseron/core` 导出、自定义传输扩展点。
`sdk/typescript/web.md`	`@tesseron/web` 浏览器适配器。
`sdk/typescript/server.md`	`@tesseron/server` Node 适配器。
`sdk/typescript/react.md`	`useTesseronAction`、`useTesseronResource`、`useTesseronConnection`。
`sdk/typescript/mcp.md`	`@tesseron/mcp` 网关 CLI、配置、来源允许列表。
`sdk/python/index.md`	计划中的 Python SDK——仅在路线图改变时更新。
`sdk/porting.md`	如何将 Tesseron 移植到另一种语言。
`examples/index.mdx`	示例应用表格。
`examples/<name>.md`	单个示例应用的逐步说明。

流程

第一步 - 检查变更集

一次性运行以下命令：

git status --short
git diff --stat HEAD
git diff HEAD -- packages/

重点关注导出的符号、公共类型、协议方法名、CLI 标志以及 packages 内的 .md/.mdx 代码片段。忽略 **/*.test.ts、**/*.spec.ts、/tests/、tsconfig*.json、biome*.json、.changeset/ 和 CI 配置下的更改——这些不需要文档更新。

第二步 - 将更改映射到文档页面

对于每个修改的公共表面，通过上表找到所属的文档页面。同时，使用 rg 在 docs/src/content/docs/ 中搜索已重命名/更改的符号，以捕获所有者表格遗漏的偶然提及：

rg --fixed-strings "oldSymbolName" docs/src/content/docs/

第三步 - 仅编辑受影响的页面

倾向于“编辑”而非“重写”。有针对性的编辑可保持 diff 可审查。
保留 frontmatter（title、description）。它们同时影响侧边栏和注入的文档索引。
保留 Starlight 组件不变：Diagram、Card、CardGrid、LinkCard、Code、Tabs 等。
不要在面向用户的散文中使用破折号（-）——使用 - 或句号。与项目风格一致。
仅在实际包边界发生变化时更新版本号/包导出。

第四步 - 如果页面焦点发生变化，更新 frontmatter 的 `description`

位于 .claude/hooks/inject-docs-index.py 的钩子从 description 字段派生注入的索引。如果某个页面的范围发生了实质性变化（例如，一个方法被提升或删除），请重写 description，使其保持为该页面现在所涵盖内容的一行摘要。

第五步 - 验证

cd docs && npx astro check

astro check 可捕获损坏的 frontmatter、错误的组件使用以及损坏的相对链接。如果构建已接入 CI，则依赖 CI；否则在本地运行。

第六步 - 报告

以项目符号列表结束你的轮次：

修改的包：packages/...
更新的文档：docs/src/content/docs/...
已审查但未更改的文档（以及原因）

不要更新的内容

.changeset/ 文件——由发布工作流维护，并非本技能职责。
仓库根目录的 README.md——手工保持同步；如果看起来过时，请在报告中提及，让用户决定。
docs/astro.config.mjs 中的 Starlight sidebar——仅当添加新页面或删除页面时才触及，即便如此，最好在报告中注明，以便用户确认排序。
自动生成的 TypeDoc / API 参考输出（如果有）。