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”、“actions 如何工作”、“我从哪里开始”。对于权威规范 — 确切的线缆格式、错误码表、握手和恢复形状、完整协议行为 — 请优先参考 `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 等）。智能体无需通过自动化浏览器来操作用户界面，而是由应用直接告知智能体*它能做什么*。每次工具调用都会针对真实状态执行真实处理程序——无需 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: 'My Todo App',
  description: 'A todo app driven by Claude through Tesseron.',
});

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

tesseron
  .action('addTodo')
  .describe('Add a new todo item to the list. Returns the created todo.')
  .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('All current todos.')
  .output(z.array(z.object({ id: z.string(), text: z.string(), done: z.boolean() })))
  .read(() => todos);

const welcome = await tesseron.connect();
console.log(`Claim code: ${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 让智能体在调用前向用户显示确认信息。对于纯 getter 方法，使用 readOnly: true 有助于智能体推理副作用。

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

对于持续时间超过约 1-2 秒的操作，调用 ctx.progress(...)。 智能体会向用户显示进度；不发出进度信号的处理程序看起来像是卡住了。

在调用 sample 和 elicit 之前检查能力（capability）。 如果智能体不支持该能力，调用它们会抛出 SamplingNotAvailableError / ElicitationNotAvailableError。ctx.confirm(...) 是一个例外——在任何非接受的情况下，它都会回退到 false，这对于破坏性操作来说是安全的默认值。

在每次成功连接后持久化 {sessionId, resumeToken}。 恢复令牌在每次成功恢复后会轮换，因此务必写入来自最新 WelcomeResult 的最新令牌。在重连失败时（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 技能会在收到诸如“探索”、“映射”、“理解 X 如何工作”或“追踪”等针对 Tesseron 项目的请求时自动触发。它会遍历代码库，生成一个紧凑的架构地图（应用、动作、资源、上下文方法使用情况、传输层、React 钩子、会话生命周期、必读列表）。

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

当用户希望进行审查时

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

版本与兼容性

• TypeScript 5.7+（严格模式，建议启用 noUncheckedIndexedAccess）。
• 服务器/网关进程需要 Node 20+（消费者可能 Node 18 可用，但单体仓库测试针对的是 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.sample(...) / ctx.elicit(...) 前没有检查 ctx.agentCapabilities.*——在不支持该能力的客户端上会抛出异常。
• 没有将 ctx.signal 转发给 fetch 或其他可取消操作——网关取消操作无法传播。
• 持久化了过期的 resumeToken——令牌在每次成功恢复后轮换；过期令牌会触发 ResumeFailedError。
• 存储了 claimCode——它是一次性配对码，不是认证凭据。用户在粘贴后即可丢弃它。
• 在代码库中硬编码 ws://localhost:7475，而不是使用 DEFAULT_GATEWAY_URL。
• 设置了 TESSERON_HOST=0.0.0.0 但没有设置 TESSERON_ORIGIN_ALLOWLIST——这会将网关暴露给任意来源。
• 在同一个应用中使用多个 useTesseronConnection(...) 钩子——每个都会创建自己的会话。
• 使用 useCallback / useMemo 包裹 useTesseronAction 的处理函数——不必要；该钩子本身会引用处理函数。
• 使用魔数 error.code === -32006 进行检查，而不是使用 instanceof SamplingNotAvailableError。

如需更深层次的指导，请加载上述相关参考文件。对于代码审查运行，请委托给 tesseron-reviewer 子智能体。