name: framework
description: Tesseron TypeScript SDK 快速参考思维模型 —— 核心抽象（app, action, resource, handler, ActionContext, transport, session, gateway）、每个使用者包的规范导入（`@tesseron/web`、`/server`、`/react`、`/core`、`/mcp`）以及最小可行应用模板。当用户开始 Tesseron 工作、连接第一个 action 或 resource、决定导入哪个使用者包、第一次编写 handler、或需要理清各部分如何配合时加载。触发条件：代码从 `@tesseron/*` 导入，调用 `tesseron.action(...)`、`tesseron.resource(...)`、`tesseron.connect(...)`、`useTesseronAction`、`useTesseronResource` 或 `useTesseronConnection`，以及宽泛的问题如“什么是 Tesseron”、“动作如何工作”、“从哪里开始”。对于权威规范 —— 确切的数据线格式、错误代码表、握手和恢复形状、完整协议行为 —— 请优先使用 `tesseron-docs` 技能，该技能查询实时 `@tesseron/docs-mcp` 服务器。本技能是速查表；`tesseron-docs` 是手册。

Tesseron 框架

Tesseron 是一个协议+SDK，它允许一个运行中的应用（目前支持浏览器标签页、Node 服务/CLI、Electron/Tauri 桌面应用；理论上，任何支持 WebSocket + JSON-RPC 2.0 的语言都可以）通过 WebSocket 向兼容 MCP 的 AI 代理（如 Claude Code、Claude Desktop、Cursor 等）暴露带类型前缀的动作和资源。代理无需通过自动化浏览器来驱动 UI，而是由应用直接告诉代理*它能做什么*。每次工具调用都会针对真实状态执行真实的处理函数——无需 DOM 抓取，无需截图分析。

本技能旨在向 Claude 介绍该框架，并根据任务需求引导其查阅相关的参考文件。

核心抽象

每个动作/资源都使用兼容 Standard-Schema 的校验器（Zod、Valibot、Typebox）进行输入/输出校验。

标准导入

// 浏览器
import { tesseron, BrowserWebSocketTransport, DEFAULT_GATEWAY_URL } from '@tesseron/web';

// Node（无头服务器、CLI、守护进程）
import { tesseron, NodeWebSocketTransport, DEFAULT_GATEWAY_URL } from '@tesseron/server';

// React（内嵌于组件中）
import { useTesseronAction, useTesseronResource, useTesseronConnection } from '@tesseron/react';

// 核心（协议类型、错误、传输接口——适用于自定义传输层/测试）
import type { ActionContext, Transport, WelcomeResult, ResumeCredentials } from '@tesseron/core';
import {
  TesseronError,
  TesseronErrorCode,
  SamplingNotAvailableError,
  ElicitationNotAvailableError,
  TimeoutError,
  CancelledError,
  ResumeFailedError,
} from '@tesseron/core';

不要从包内部导入（如 @tesseron/core/dist/... 或跨包的相对路径）。只有顶层导出才是公开 API 的一部分。

最小可行应用

import { tesseron } from '@tesseron/web';
import { z } from 'zod';

tesseron.app({
  id: 'my_todo',
  name: '我的待办应用',
  description: '一个由 Claude 通过 Tesseron 驱动的待办应用。',
});

const todos: Array<{ id: string; text: string; done: boolean }> = [];

tesseron
  .action('addTodo')
  .describe('向列表中添加一个新的待办事项。返回创建的待办事项。')
  .input(z.object({ text: z.string().min(1) }))
  .handler(({ text }) => {
    const todo = { id: crypto.randomUUID(), text, done: false };
    todos.push(todo);
    return todo;
  });

tesseron
  .resource('todos')
  .describe('所有当前的待办事项。')
  .output(z.array(z.object({ id: z.string(), text: z.string(), done: z.boolean() })))
  .read(() => todos);

const welcome = await tesseron.connect();
console.log(`认领码: ${welcome.claimCode}`);

在 Claude 中，用户随后输入 claim session <code>，应用的 addTodo 动作就会作为一个类型化的 MCP 工具出现。完整的可运行版本位于 examples/ 目录（包括 vanilla、React、Svelte、Vue、Express、Node）。

决策路由

根据任务选择对应的参考文件。每个文件仅在读取时加载。

当某个概念不清楚时，从用户的动词开始：*添加一个动作* → 动作，*推送一个实时值* → 资源，*让 LLM 选择某物* → 上下文（ctx.sample），*让用户确认* → 上下文（ctx.confirm / ctx.elicit），*我的会话在重新加载后失效* → 传输层（恢复）。

工作方式

除非项目另有说明，否则遵循以下默认规则。参考文件会对每一点进行更深入的阐述。

为 LLM 描述每个动作，而不是为开发者描述。 .describe(...) 字符串以及输入模式中的字段描述是代理决定何时调用动作以及传递什么参数的唯一提示。缺失或模糊的描述实际上等同于一个未使用的工具。

模式是运行时契约。 .input(schema) 在处理函数运行前进行校验；无效输入将被拒绝，并返回 InputValidation 错误，而不会调用处理函数。使用 Standard-Schema 校验器（Zod 最常见，Valibot 和 Typebox 也可用）。纯 TypeScript 类型不是运行时校验器。

为破坏性动作添加注解。 .annotate({ destructive: true }) 和 requiresConfirmation: true 可以让代理在调用前向用户显示确认信息。纯粹获取器上的 readOnly: true 有助于代理推理副作用。

将 ctx.signal 传递给每个可取消的异步操作。 fetch、子进程、数据库调用、长时间定时器——所有这些都应接受 signal: ctx.signal，以便网关发起的取消能够沿着调用栈传播。

对于耗时约 1–2 秒以上的操作，调用 ctx.progress(...)。 代理会向用户显示进度；不发出进度的处理函数看起来像卡住了。

在使用 sample 和 elicit 之前检查能力。 在不支持该能力的代理上调用它们会抛出 SamplingNotAvailableError / ElicitationNotAvailableError。ctx.confirm(...) 是例外——它在任何非接受情况下都会归约为 false，这对于破坏性操作来说是安全的默认值。

每次成功连接后持久化 {sessionId, resumeToken}。 每次成功恢复后，恢复令牌都会轮换，因此始终要写入最新的 WelcomResult 中最新的令牌。在重连失败（ResumeFailedError）时，回退到不带恢复选项的全新 connect()。

推送更新的资源在初始时发出一个值，然后返回一个清理函数。 subscribe((emit) => { emit(current); registry.add(emit); return () => registry.delete(emit); }) 这种形状是标准写法。缺少初始发出会导致第一次读取挂起；缺少返回值会导致订阅泄漏。

在 React 中，钩子会在挂载时注册一次，并在卸载时清理。 每次渲染时传递一个新的处理函数闭包——钩子会将其存储在 ref 中。不需要 useCallback / useMemo 包裹处理函数。将 useTesseronConnection(...) 放在应用根组件，而不是每个组件中。

当用户想要向项目中添加 Tesseron

委托给同级的 tesseron-dev 技能。它负责选择合适的 @tesseron/* 消费者包、使用项目现有的包管理器安装它，并在入口文件的模块作用域中插入标准的 Tesseron API（tesseron.app(...) + 一个动作 + 一个资源 + tesseron.connect()）。

项目创建本身（搭建 package.json、tsconfig.json、打包器配置、选择框架版本）超出了 Tesseron 的范围——用户应使用他们偏好的上游脚手架或特定框架的技能。无论项目是五秒前还是五年前创建的，tesseron-dev 的工作方式都一样。

当用户想要理解现有代码库

tesseron-explorer 技能会在收到针对 Tesseron 项目的“探索”、“映射”、“理解 X 如何工作”或“跟踪”等请求时自动触发。它会遍历代码库并生成一份紧凑的架构图（应用、动作、资源、上下文方法使用、传输层、React 钩子、会话生命周期、必读清单）。

对于小型项目（单个 main.ts 加一两个动作），直接读取文件通常比加载探索技能更快。

当用户想要审查

tesseron-reviewer 技能会在收到审查、审计、检查或验证 Tesseron 代码的请求时自动触发。它会针对用户指定的差异或路径运行，并返回一个带有置信度过滤的框架特定问题列表以及可立即应用的修复方案。它是对通用代码审查的补充；不要在主线程中重复其检查。

版本与兼容性

• TypeScript 5.7+（严格模式，推荐使用 noUncheckedIndexedAccess）。
• 服务器/网关进程需要 Node 20+（消费者可能可以在 Node 18 上运行，但 monorepo 测试基于 20+）。
• 协议版本 1.0.0。会话恢复（tesseron/resume）在 SDK v1.1 中添加。
• 包版本同步发布：@tesseron/core、/web、/server、/react、/mcp 版本锁定发布。请在次版本号内保持匹配。
• @standard-schema/spec ^1.0.0 是 @tesseron/core 唯一的运行时依赖。

反模式（在审查中要指出）

• 在 tesseron.app(...) 之前调用 tesseron.connect()——connect 会抛出异常。
• 在动作构建器的 .handler(...) 之后链接任何内容——.handler(...) 返回的是最终的 ActionDefinition，而不是构建器。这是一个静默错误。
• 在动作或资源上省略 .describe(...)——LLM 没有信号来选择工具。
• 将纯 TypeScript interface / type 传递给 .input(...)——这不是校验器。请使用 Zod / Valibot / Typebox。
• .subscribe(...) 没有返回清理函数——会导致订阅泄漏。
• .subscribe(...) 没有发出初始值——第一次读取会阻塞等待推送。
• 在没有 ctx.agentCapabilities.* 检查的情况下调用 ctx.sample(...) / ctx.elicit(...)——在不支持该能力的客户端上会抛出异常。
• 没有将 ctx.signal 传递给 fetch 或其他可取消操作——网关取消无法传播。
• 持久化了过期的 resumeToken——每次成功恢复后令牌都会轮换；过期的令牌会导致 ResumeFailedError。
• 存储 claimCode——它是一次性配对码，不是身份验证。用户粘贴后即可丢弃。
• 在整个代码库中硬编码 ws://localhost:7475 而非使用 DEFAULT_GATEWAY_URL。
• 在未设置 TESSERON_ORIGIN_ALLOWLIST 的情况下使用 TESSERON_HOST=0.0.0.0——会使网关暴露给任意来源。
• 在同一个应用中使用多个 useTesseronConnection(...) 钩子——每个都会创建独立的会话。
• 使用 useCallback / useMemo 包裹 useTesseronAction 的处理函数——没有必要，钩子会直接引用处理函数本身。
• 使用 error.code === -32006 这样的魔法数字检查，而不是 instanceof SamplingNotAvailableError。

如需更深入的指导，请加载上述相应的参考文件。对于代码审查运行，请委托给 tesseron-reviewer 子代理。