# @agentskit/statechart 中文文档

规范地址：https://npmcn.com/package/%40agentskit/statechart/

版本：0\.3\.2
npm 元数据更新时间：2026-10-10T14:12:22.404Z
中文译文更新时间：2026-11-05T23:13:59.033Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/statechart
原文对照：https://npmcn.com/package/%40agentskit/statechart/?lang=original
项目主页：https://www.agentskit.io/docs/reference/packages/statechart
源码仓库：https://github.com/AgentsKit-io/agentskit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：174 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-07-13T16:28:45.136Z
- 最新版本发布：2026-10-10T14:12:22.059Z
- 近 30 天下载量：9773（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

AgentsKit 应用程序的决定性,可序列化的交互状态.

## 安装

```sh
npm install @agentskit/statechart
```

也可以使用：`pnpm add @agentskit/statechart`、`yarn add @agentskit/statechart`、`bun add @agentskit/statechart`

## README

# @ agentskit/ 状态图

简介 : `concise-package`

![AgentsKit](https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg)

**标记 :** `agentskit` • 妇女 `typescript` • 妇女 `ai-agents`

[![stability](https://img.shields.io/badge/stability-beta-yellow)](https://npmcn.com/package/docs/STABILITY.md)

决定性、可序列的交互状态 [探员Kit](https://www.agentskit.io/) 应用。 它是框架中立的,并且零运行时间依赖.

## 为什么

互动代理经验往往需要明确的状态,如等待投入、确认某项行动或完成某项任务等。 这个软件包赋予每个UI绑定和主机相同的小转换和快照合同,而不将它们与LLM提供商React相接, `ChatController`,或运行时执行引擎.

使用运行时流进行持久执行,DAG,工具,以及效果. 用于本地或主机管理的互动状态 .

## 已核实的证据

-   软件包元数据和测试在 `packages/statechart/`。 。 。 .
-   软件包指南 : [https://www.agentskit.io/docs/参考资料/packages/statechart](https://www.agentskit.io/docs/reference/packages/statechart)
-   稳定地图: [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)

## 安装

```bash
npm install @agentskit/statechart
```

## 使用量

```ts
import {
  createStatechartInstance,
  defineStatechart,
  serializeStatechart,
  transitionStatechart,
  type StatechartEvent,
} from '@agentskit/statechart'

type Context = { confirmed: boolean }
type Event = StatechartEvent<'confirm'> | StatechartEvent<'cancel'>

const parseContext = (input: unknown): Context => {
  if (
    input === null ||
    typeof input !== 'object' ||
    typeof (input as { confirmed?: unknown }).confirmed !== 'boolean'
  ) {
    throw new TypeError('invalid context')
  }
  return input as Context
}

const confirmation = defineStatechart<
  Context,
  Event,
  'waiting' | 'confirmed' | 'cancelled'
>({
  id: 'confirmation',
  version: '1',
  initial: 'waiting',
  parseContext,
  states: {
    waiting: {
      on: {
        confirm: {
          target: 'confirmed',
          reduce: (context) => ({ ...context, confirmed: true }),
        },
        cancel: { target: 'cancelled' },
      },
    },
    confirmed: {},
    cancelled: {},
  },
})

const initial = createStatechartInstance(
  confirmation,
  { confirmed: false },
  { instanceId: 'interaction-42', now: '2026-07-13T12:00:00.000Z' },
)

const result = transitionStatechart(
  confirmation,
  initial,
  { type: 'confirm' },
  { now: '2026-07-13T12:01:00.000Z' },
)

if (result.status === 'accepted') {
  const snapshot = serializeStatechart(result.instance)
  await yourStorage.save(snapshot)
}
```

主机提供身份证、时间戳、存储和事件交付。 这使得可复制的转换器和包可移植到浏览器、服务器、本地和终端运行时间.

## 合同

-   `defineStatechart` 验证目标并冻结信任的运行时间定义 .
-   `createStatechartInstance` 验证并冻结JSON相容上下文.
-   `transitionStatechart` 同步并返回 `accepted` 或者说 `rejected` 结果.
-   `serializeStatechart` 创建一个版本的 JSON 兼容快照 .
-   `restoreStatechart` 接受 `unknown`,验证元数据和上下文,从不信任序列化定义.
-   `notifyStatechartObserver` 单独提供完成的结果; 观察失败不能改变状态.

事件,上下文,和快照使用一个精确的JSON边界:稀有或装饰的阵列,存取器,符号,异地原型,以及非无限数字被拒绝而不引用取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取 敌对但有效的对象密钥, 如 `__proto__` 仍然是普通数据密钥。 观察者必须同步完成;返回的可处理器被隔离为打出故障.

背景验证通过 `parseContext`,因此应用程序可以使用任何验证库而不在此包中添加一个.

## 故意边界

此套件不执行动作,不坚持快照,调用代理或工具,不重试事件,不重复发送,不渲染组件,也不定义产品特定状态. 重复的事件遵循了当前状态的过渡表;交付一能属于主机.

见 [ADR-0020 (韩语)](https://npmcn.com/package/docs/architecture/adrs/0020-serializable-interaction-state.md) 所有权决定 [ADR-0027 (英语)](https://npmcn.com/package/docs/architecture/adrs/0027-statechart-beta-boundaries.md) 对于硬化的β边界.

## 许可证

麻省理工学院

## 快开始

```ts
import { createStatechartInstance, defineStatechart } from '@agentskit/statechart'

const toggle = defineStatechart({
  id: 'toggle',
  version: '1',
  initial: 'off',
  parseContext: () => ({}),
  states: { off: { on: { toggle: { target: 'on' } } }, on: {} },
})

const instance = createStatechartInstance(toggle, {}, {
  instanceId: 'toggle-1',
  now: '2026-07-17T12:00:00.000Z',
})

console.log(instance.state)
```

## 成熟性和相容性

-   稳定性: **β 语录** 看到了吗 [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)
-   **节点.js 20+** 财务报告和审定财务报表 **类型脚本** 严格模式
-   发表于 `@agentskit/statechart`

## 捐款

见 [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 单曲 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 如何适应生态系统

使用 [代理人Kit 书记官处](https://registry.agentskit.io/) 现成代理商和 [代理游戏本](https://playbook.agentskit.io/) 用于生产做法.

## 常见问题

### @agentskit/statechart 是什么？

AgentsKit 应用程序的决定性,可序列化的交互状态\.

### 如何安装 @agentskit/statechart？

在项目目录运行 npm install @agentskit/statechart，或使用 pnpm add / yarn add / bun add。

### @agentskit/statechart 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentskit/statechart 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @agentskit/statechart 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agentskit/statechart 可以商用吗？

@agentskit/statechart 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agentskit/statechart 的下载量有多少？

根据 npm 官方下载统计，@agentskit/statechart 在 2026/10/05 – 2026/11/03 这 30 天内被下载 9,773 次，日均约 326 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentskit/statechart 还在维护吗？

最新版本 0\.3\.2 发布于 2026/10/10（26 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/07/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。