安装方式

命令行安装

在项目根目录执行以下命令，完成 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 的公共表面（包括协议消息、导出类型、操作/资源构建器 API、ActionContext 方法、传输层、网关 CLI 标志或 React 钩子），请使用此技能同步更新 `docs/src/content/docs/`，以使 Starlight 站点与代码保持一致。触发器为“更新文档”、“同步文档”、“此次更改后文档已过时”，或当会话结束时存在对公共表面的编辑但未伴随文档编辑时触发。对于仅涉及测试、工具或内部重构且公共表面保持不变的情况，请勿触发。

更新 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`	5 分钟路径：安装、声明一个 action、运行 gateway、让 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`、claim code、`tools/list_changed`。
`protocol/actions.mdx`	Action 声明、命名空间、调用 / 验证 / 返回。
`protocol/progress-cancellation.mdx`	`actions/progress`、AbortSignal、`actions/cancel`。
`protocol/sampling.mdx`	Handler 重新进入 agent 的 LLM。
`protocol/elicitation.mdx`	`ctx.confirm` 和 `ctx.elicit`。
`protocol/resources.mdx`	可读 / 可订阅的资源投影。
`protocol/errors.mdx`	每个定义的错误代码及其触发条件。
`protocol/lifecycle.mdx`	会话状态机、挂起工作的处理方式。
`protocol/security.mdx`	来源强制、claim 流程、信任边界。
`sdk/typescript/index.mdx`	安装、`packages/` 概览、第一个 action 代码片段。
`sdk/typescript/action-builder.md`	`tesseron.action(...)` 流式 API。
`sdk/typescript/standard-schema.md`	Zod / Valibot 等适配器中间件。
`sdk/typescript/context.md`	`ActionContext` 方法：progress、sample、confirm、elicit、signal。
`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` gateway CLI、配置、来源允许列表。
`sdk/python/index.md`	计划中的 Python SDK——仅当路线图变更时更新。
`sdk/porting.md`	如何将 Tesseron 移植到其他语言。
`examples/index.mdx`	示例应用的表格。
`examples/<name>.md`	单个示例应用的逐步介绍。

流程

步骤 1 - 检查变更集

一次性运行以下命令：

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 配置下的变更——这些不需要文档更新。

步骤 2 - 将变更映射到文档页面

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

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

步骤 3 - 仅编辑受影响的页面

优先“编辑”而非“重写”。针对性编辑使差异易于审查。
保留 frontmatter（title、description）。它们同时为侧边栏和注入的文档索引提供内容。
保持 Starlight 组件完整：Diagram、Card、CardGrid、LinkCard、Code、Tabs 等。
不要在面向用户的散文中引入 em-dashes（—）——使用 - 或句点。符合项目风格。
仅当实际包边界发生变化时才更新版本号/包导出。

步骤 4 - 如果页面焦点发生变化，更新 frontmatter `description`

.claude/hooks/inject-docs-index.py 钩子从 description 字段派生注入的索引。如果页面的范围发生实质性变化（例如，某个方法被提升或删除），请重写 description，使其保持对页面现在内容的一句话总结。

步骤 5 - 验证

cd docs && npx astro check

astro check 会捕获损坏的 frontmatter、错误的组件使用和损坏的相对链接。如果构建已集成到 CI 中，依靠 CI；否则在本地运行。

步骤 6 - 报告结果

以项目符号列表结束你的回合：

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

不更新的内容

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