# @felan-ai/session-protocol 中文文档

规范地址：https://npmcn.com/package/%40felan-ai/session-protocol/

版本：0\.4\.3
npm 元数据更新时间：2026-11-13T12:31:33.354Z
中文译文更新时间：2026-11-14T13:53:55.168Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40felan-ai/session-protocol
原文对照：https://npmcn.com/package/%40felan-ai/session-protocol/?lang=original
项目主页：https://github.com/felan-ai/felan#readme
源码仓库：https://github.com/felan-ai/felan

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

- 包体积（解压后）：1.2 MB，88 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-15T08:12:05.257Z
- 最新版本发布：2026-11-13T12:31:32.900Z
- 近 30 天下载量：3983（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

浏览器兼容 Felan 会话协议 v1 合同和验证

## 安装

```sh
npm install @felan-ai/session-protocol
```

也可以使用：`pnpm add @felan-ai/session-protocol`、`yarn add @felan-ai/session-protocol`、`bun add @felan-ai/session-protocol`

## README

# @felan-ai/session-protocol (英语)

Felan的运行时间中立会话协议 v1. 仅限无害环境管理的一揽子措施 假设类型、范围验证和JSON线框架。 独家 运行时间依赖是 `typebox@1.1.38`它进口了Node、Pi、Core探员、TUI, ACP或平台API,并可在浏览器中直接运行.

01.0是首次公开发布. 0.2.0 加上 `channel` 源代码。 增加0.3.0个 远程团队主机身份 `follow_up`,客户端选择的远程会话ID 和自动化命令来源。 年长的读者拒绝这些合同,所以他们 正在打破未成年人。 发布后 [`docs/maintainers/releasing.md`](https://npmcn.com/package/docs/maintainers/releasing.md)唯一的公共子路径是 `.`; 没有守护进程或配置文件 执行此处导出。 打破变化需要下一个未成年人; 兼容的校正保留在内 `0.3.x`. 线、存储行和不匹配控制 版本是独立的常数,最初 `1`。 。 。 .

## 边界 API

```ts
import {
  JsonLineDecoder, encodeFrame, parseClientEnvelope, parseServerEnvelope,
} from '@felan-ai/session-protocol';

const decoder = new JsonLineDecoder();
for (const raw of decoder.push(bytesFromAuthenticatedTransport)) {
  const request = parseClientEnvelope(raw);
  // The host must still authorize, admit and execute the request.
}
decoder.finish(); // Reject a truncated final frame at EOF.

// Associate responses with the outstanding request before parsing their result.
const response = parseServerEnvelope(rawResponse, outstandingRequest.op);
const bytes = encodeFrame(response);
```

`ClientEnvelopeSchema`, (中文(简体) ), `ServerEnvelopeSchema`, (中文(简体) ), `SessionCommandSchema`, (中文(简体) ), `SessionSnapshotSchema`, (中文(简体) ), `SessionEventSchema`, (中文(简体) ), `InteractionSchema`, (中文(简体) ), `StoredEventRowSchema` 财务报告和审定财务报表 `StoredRequestRecordSchema` 有相应的公开 类型. `OperationSchemas`, (中文(简体) ), `ResultSchemas`, (中文(简体) ), `OperationParams<O>` 财务报告和审定财务报表 `OperationResult<O>` 提供输入的操作特定数据. `SessionCommand` 描述内部 `{op,params}` 命令,而不是第二个传送信封.

不仅使用运行时解析器 `Value.Check` 或类型脚本任务. `parseSchema` 校验有界的平地JSON,检查计划,条形不明 选项字段,不突变输入或计划,执行UTF-8/encode 字段限制。 联盟验证不跳过而选择直接匹配的分支 巢会受限. `JsonValueSchema` 标记边框扩展数据;其递归式JSON, 收集、原型和字节检查在解析器中运行,而不是循环类型框 计划 一个独立的 `Value.Check` 仅此边界是不够的. 专业解析器还额外检查了聚合物和跨战地变量. `parseServerEnvelope` 要求未完成的已接受回复操作: 使用 `re`,而不是重复 `op`。 。 。 . `parseOperationResult` 独立验证结果。 Schema 无法验证 推断哪个结果属于未解决的请求.

未知的操作/歧视值被拒绝 。 未知添加剂事件 类型作为限值JSON保留,必须推进修订工作,而不 发明出已知的行为. 一个畸形 **已经知道** 变化不能通过 未知变化分支。 要求的新行为需要明确的能力 谈判或一个新的协议版本。 配置是封闭的, 无秘密的 使用现有的65 CLI 选项名称加上范围化/默认模型和 思维设置; 配置路径和证书字段不是可扩展的 JSON . 主机仍然应用了每个设置的现有验证并重新加载规则.

## 业务和能力

`OPERATION_CATALOG` 宣布每个行动的范围, 突变、持久性类别和符合条件的客户类别. `hello` 谈判 实际可用的子集、 交互类型和可选的 UI 能力; 单是目录成员资格并不意味着存在或授权使用. Hello 能力名称和错误代码 接受有界限的未知字符串 向前兼容。 客户端忽略了未支持的广告操作; a 请求使用未知的操作仍然失败。 任择答复 字段,包括添加到空结果中,在使用前被剥去.

`ERROR_CODES` 输出已知代码, 使用 `KnownErrorCode` 他们的文字 工会: `invalid_request`, (中文(简体) ), `unsupported_operation`, (中文(简体) ), `protocol_mismatch`, (中文(简体) ), `unavailable`, (中文(简体) ), `authentication_required`, (中文(简体) ), `busy`, (中文(简体) ), `request_conflict`, (中文(简体) ), `stale_request`, (中文(简体) ), `expired`, (中文(简体) ), `not_found`, (中文(简体) ), `forbidden`, (中文(简体) ), `already_resolved`, (中文(简体) ), `storage_failure`, (中文(简体) ), `ownership_lost`, (中文(简体) ), `resync_required`, (中文(简体) ), `indeterminate`, (中文(简体) ), `request_capacity` 财务报告和审定财务报表 `target_mismatch`。 。 。 . `ProtocolError.code` 仍为界限 电线字符串使客户端能够用通用回落处理未来的代码.

-   主机 : `hello`, (中文(简体) ), `host.status`, (中文(简体) ), `sessions.list`, (中文(简体) ), `sessions.create`, (中文(简体) ), `session.import`, (中文(简体) ), `host.stop`, (中文(简体) ), `host.restart`, (中文(简体) ), `host.logs`。 。 。 .
-   会话约束/寿命 : `attach`, (中文(简体) ), `detach`, (中文(简体) ), `close`。 。 。 .
-   执行 : `prompt`, (中文(简体) ), `steer`, (中文(简体) ), `follow_up`, (中文(简体) ), `cancel`, (中文(简体) ), `set_model`, (中文(简体) ), `set_thinking`, (中文(简体) ), `compact`, (中文(简体) ), `fork`, (中文(简体) ), `command.invoke`, (中文(简体) ), `interaction.answer`, (中文(简体) ), `ui.action`, (中文(简体) ), `shell.execute`, (中文(简体) ), `session.reload`。 。 。 .
-   历史/设定: `session.rename`, (中文(简体) ), `session.tree`, (中文(简体) ), `session.branch.select`, (中文(简体) ), `session.entry.label`, (中文(简体) ), `session.clone`, (中文(简体) ), `session.export`, (中文(简体) ), `session.delete`, (中文(简体) ), `session.history`, (中文(简体) ), `queue.update`, (中文(简体) ), `config.get`, (中文(简体) ), `config.set`。 。 。 .
-   儿童执行检查/控制: `executions.list`, (中文(简体) ), `executions.read`, (中文(简体) ), `executions.steer`, (中文(简体) ), `executions.cancel`。 。 。 .
-   Root-scoped 进程面板 : `processes.list`, (中文(简体) ), `processes.read`, (中文(简体) ), `processes.write`, (中文(简体) ), `processes.stop`资源标识是权威参考, 从来没有PID。 任意过程输出/sdin/控制字节使用犬科碱基64; 抵消和读取/写出限制数解码字节.

操作资格不给TUI,ACP或无头标签分配特权. 客户端会商操作及其执行的 UI 词汇; 本地 TUI 构成部分仍然是当地客户。 非加太国家要求严格会议 政策明确。 客户类型只描述出处. 认证 主机指定主机、来源、会话约束和资源/控制 权力. `command.invoke` 用于注册 扩展/技能命令;内建有自己的打入操作. 失踪的处理者明确拒绝。 调试不取消,关闭或主机站.

## 通用UI 元素

当前通用词汇谈判 `ui.status`, (中文(简体) ), `ui.progress`, (中文(简体) ), `ui.document`, (中文(简体) ), `ui.view` 财务报告和审定财务报表 `ui.action`表格的谈判完全通过 页:1 `form` 交互类型,不是单独的UI能力. 表格声明已输入 投入和明确提交/取消行动。 意见和文件完成 限定数据和修订检查的行动; `ui.action` 识别元素, 修订、行动、可选项目和提交的数值。 可选择的提示 渲染但不能改变数据、动作、验证或结果.

提示可能包括可选 JSON `data`,而渲染器的有效载荷仅限于 `LIMITS.uiHintBytes` (128 KiB被编码为UTF-8 JSON). 只有客户才认得 提示 `id` 财务报告和审定财务报表 `version` 应该解释它。 发货人必须验证有效载荷 并回到不支持或不符合 形式。 提示数据永远不会改变字段,动作或回答验证.

文件/观点/进展行动: 与当前元素修订和会话绑定的宣告式ID `ui.action` 请求。 表单使用有界限的字段词汇(字符串、布尔、, 数字、 enum 和多选择),以及解析器对已声明的回答 字段和选择。 文档拒绝原始 HTML 和非 HTTP( S) 链接; 视图 验证项目字段和页数限制。 渲染器提示仍然是可选元数据 并且不授予资格或授权。 主机必须验证当前 元素、会话、修订和通过普通请求宣布的行动 承认.

可选 `hello.capabilities` 列表只描述用户界面词汇支持。 这个 无法确认本地主机状态; 认证的运输决定 主机属性 。 互动的可选性 `authority` 区分 `owner` 核准自 `local-console` 主办方同意。 主机执行当前的能力, 主要内容、附件、范围和政策,包括创建-美因主机提示。 现有颜色 批准范围为所有者会议; MCP 登录和安装提示 地方指挥机构。 东道主不得从客户索偿中推断出任何权威.

互动选择排出/重新开始 `deferrable: true`独立 他们的要求。 稍后对推迟会话的回答开始 a 继续转弯。 其他待决互动取消. 非加太客户请求 严格政策明确与 `requirePolicy: 'acp-strict'` 创建、导入或 附加; 客户类型不选择执行政策.

只有已注册守护进程显示在 `sessions.list` 或可恢复. 对会议发现来说,守护进程前记录没有改变,也看不见. 明确 `session.import` 从已验证的 JSONL 历史创建新的会话ID ; `session.export` 现保留。 每行列载 `revision`,所以一个 客户端可以关闭会话并提交 `session.delete` 没有恢复它. 在一次 Stale 修订拒绝后, 在重试前再次列出 .

获得接受 `steer` 财务报告和审定财务报表 `follow_up` 结果要么是 `{itemId}` 或者说 `{status: 'handled'}`从来没有两者。 这些是未公布的V1更正,现保留 首发合同评估的一部分.

`fork.from` 从源的完整存储用户信息选择器中选择, 包括不活动分支. `entry` 使用其条目标识; `position` 这是它的 零基选择器索引,而不是页历史偏移。 新的会务处 在该条目之前不更改源、重新提交文本或切换 客户的附属物.

`config.set` 使用锁定、无条件字段合并:无关字段活下来 最后一位成功的作家也在同一领域获胜。 无需修改. 运行时间解析器拒绝任何自己的过时 `params.expectedRevision` 在此之前 正常化和要求身份,而不是默不作声地丢弃CAS 期望。 分支、标签和删除操作也没有预期的修订. 本地主机支持全局配置字段和模型默认值, + 会话范围扩展覆盖 。 会议模式/思考变化 专用业务。 项目配置仍未确定.

故事1明确推迟目标 `queue.update`: 服务器拒绝作为 不可用,也不做广告。 现有观察的顺序和忠诚 仍然支持; 观察不保证原子编辑或选择 通知书。 此推迟不需要上游 SDK 更改或私有队列 工作间。 计划仍保留给单独谈判的未来 执行.

会话和进程列表光标是范围绑定的密钥,不是全天候 示意图. 不相干的活动不会使其失效。 删除光标 命令锚或不同的过滤器/根需要新的列表.

删除配置 CAS 更正未公布的初始 v1 合同; 否 版本凸起在此片中。 这对SemVer来说不是例外 已公布/消耗的软件包: 释放准备状态必须检查出口、行为、, 公布和使用前的明细表和包装的确切应用依赖性 释放的下一个未成年人 `0.x` 合同被打破.

## 请求、复审和结果

请求是 `{v:1,id,op,session?,params}`. 接受的答复总是 `{v:1,re,outcome:'accepted',result}`; 空结果为 `{}`被拒绝和 不确定的答复带有一个有限制的打出错误。 回来了 `runId` 表示允许/开始,未完成.

突变ID是UUIDv7. 其它身份证明不透明 非空字符串最多128个 UTF-8字节,包括遗留的 Pi ID. 请求的ID没有新鲜度窗口 . `requestRetainUntil` 保留记录7天 嵌入式时间戳和录取时间。 查找前将 UUID 拼写规范化 .

`canonicalRequestPayload` 比较标准化的语义数据,不包括 `id` 财务报告和审定财务报表 电线版. `compareRequestPayload` 区分同一/冲突/无法使用; 它不执行或重试任何东西。 东道方预备队事先请求能力 效果,持续意图/结果,并将模棱两可的发送视为 `indeterminate`限制保留100,000个记录/会话和1,000,000个/名称空间, 设有1 024个保留控制槽。 永远不要驱逐可以重试的记录 腾出空间. 罐装有效载荷可以接近框架限度;持久性层必须 预算保留字节, 而不是假设请求- 计数限制的磁盘 或内存使用。 (一) 仅摘要身份需要商定的存储行合同; 它不能无声地取代这个计划 `payload` 绳子.

## 环境和全权证书

所有会话都使用守护进程发射环境. 没有每个客户的捕捉, 提供/重新运作、环境处理或恢复 重新规定要求。 环境值不属于协议 请求、快照、事件、持久请求身份或诊断. 现有的单个流程工具环境参数是一个单独的特征; 此协议不删除它们或添加替换会话级 API.

证书设定和OAuth工作流程仍然使用其私人参考资料 已锁定的证书存储; 这些引用不提供会话 环境. `StoredRequestRecord.payload` 是犬科命令的有效载荷, 没有特定环境的替代身份.

验证无法检测故意放置在正常用户中的任意秘密 文本或扩展名。 生产者仍然负责对诊断进行消毒, 演示文稿和扩展数据. `encodeFrame` 是一个低等JSON编码器,不是 秘密洗涤器; 编码验证,仅授权信封.

## 快照和现场剪接

抓图包含会话/根/家长ID、修订、活动分支和被绑定 历史、模型/思维、排队ID、运行源、目录、政策和阻塞器、, 工具、互动、儿童、进程和申报性介绍。 没有 环境元数据、召回或运行时对象.

随附主机必须解剖获取修正 **财务报告和审定财务报表** 每个活动流的 安装订阅时完成前缀/后缀相抵。 发送快照 首先,然后修改R+1并仅在所捕获的相冲后再修改文本. 历史光标 被钉入被俘的视野 坚持修正/在粉丝出道前状态.

只有助手/思考文本没有修改 : `{v:1,session,stream:{message,id,kind,offset},text}`数字 分数,不是UTF-16单位或UTF-8字节. `classifyTextDelta` 检查进入的三角洲 相对于已经验证的还原器前缀而不重新扫描前缀 每个附件。 返回未知流 `start` 页:1 `gap` 否则; 明确标记呼叫者 `completed` 或者说 `completion_only` 晚点忽略的流 语句。 前缀冲抵必须与还原附件保持一致。 帮手 也区分了确切的重复,不变异还原器. 在一个缺口上, 请求 **最多一个** 每条溪流恢复快照。 缺失/超限前缀 变成 `completionOnlyStreams` (单位:千美元)`limit|lost`),没有编造文本. 忽略 稍后该流的三角塔, 直到权威完成的消息替换 它的瞬间。 仅当调用者保留后, 已完成的流会忽略后发文本 那个终极身份. 在会话期间开始的流 `LIMITS.activeStreams` 活动加 只完成的流保留到消息完成为止。 主机发送 没有三角洲或 `stream.completion_only` 通知它, 和已完成的消息 带有其文本.

所有其他有意义的变化都经过了修订. `classifyRevision` 区分 下一个/重复/差距。 高容量工具输出/状态 替换 `tool.updated`编号 :`presentation.updated` 变动 **在此之前** 指定 持久修改;它们从来不是文本流。 工具状态包括短跑 和完成/失效/中断状态。 替换已完成的信息和工具 以稳定身份识别的瞬间 无法弥补的差距/流出收益 `resync_required`, (中文(简体) ), 而不是编造的修改. `StoredEventRow` 是运输中性控制数据, 不是新的记录簿或执行记录.

## 相互作用和错配控制

相互作用是数据:范围、请求种类/类型、权威、时间戳、, 等待/延迟/最终状态、响应者和结果. `validateInteractionAnswer` 检查类型、提供身份证和申报的表格字段/行动。 经纪人 必须进一步强制执行主要资格、到期和原子第一胜者 语义学;坚持胜出者,在通知前继续. 断开连接 不回答/取消。 未事先暂停的推迟使用30分钟;直播 非序列式批准/ 授权操作在重新启动后需要新请求 .

分开 `CONTROL_VERSION=1` 语法支持认证的错配状态 排水/强制停止/重新启动. `BootstrapHelloSchema` 提取 在剥去未知字段时从完整的 hello 中初始版本不匹配 ; `ControlResponseSchema` 接受正广告协议版本 添加字段和提供二进制/正则, 犬根,实例和生命周期状态. `ControlRequestSchema` 拒绝 工作与环境转让。 附录和管理 标出完整的命名空间/内设/根部身份;主机必须验证. `DaemonTarget` 选择生产或明确隔离的固定命名空间; 概念化、根封存、同行认证和所有权是主机 责任,而非此软件包中的文件系统功能.

## 远程命令和频道来源

个人-东道方代币携带 `host.userId` 财务报告和审定财务报表 `felan.user_id`; 团队- 东道主符号 省略这些字段。 主机,而不是这些计划, 执行请求者的授权.

由源头运行的平台命令 `{ kind: 'web', user, command }`A. 索赔 `RemoteCommandRow` 可省略 `requester` 并携带 `automation: { source }` 或者说 `channel: { provider }`自动命令 `{ kind: 'automation', source }`· ; `AutomationSourceSchema` 将非空源限制为 256 UTF-8 字节. 频道 命令的使用 `{ kind: 'channel', provider, user?, command }` 运行中, 队列项目 和讯息. `ChannelProviderSchema` 限制 `provider` 改为 `^[a-z][a-z0-9_-]*$`,最多64个字节。 网络来源仍然需要 `user`。 。 。 .

`RemoteOperationSchema` 包含 `follow_up` 与 `PromptSchema` 参数和参数 不变 `{ itemId }` 或者说 `{ status: 'handled' }` 结果是当地的后续行动。 远程 `sessions.create` 接受可选小写 UUID `sessionId`; 辅助 主机广告 `sessions.create.session-id` 内 `capabilities.features`。 。 。 . 远程和地方 `sessions.create` 接受可选 `instructions` (最多为 `LIMITS.instructionsBytes`, 16 KiB),该词为: 根会话系统中的主机附件提示; 子会话没有 继承他们。 一个主机用这个广告 `capabilities.features: ['sessions.create.instructions']`· ; `REMOTE_FEATURES` 列出已知值。 特征是可选行为:平台依赖一个 只有当注册主机发布广告时,读者才会忽略未知值.

## 限制和核查

`LIMITS` 是权威数值表: JSON 深度 32, 64 KiB 结构 数据,8个活流/1个米B每/4个米B总计,64个KiB进程读取16个KiB 写出,256-entry/12 MiB页,32 MiB未发送字节,64个飞行请求和16个KiB会话指示. 64 KiB/1,024进入结构的JSON限制适用于: 结构化演示文稿数据、工具目录参数和组合工具 状态细节,不是记录有效载荷。 转写工具参数, 结果 细节和信件细节使用所附的12个 MiB 信件/页/页 即时预算和深度32;保留不截断,包括 收藏量大于1,024个条目。 主机执行队列/后压、保留和套接字 平台限制.

```sh
pnpm --filter @felan-ai/session-protocol build
pnpm --filter @felan-ai/session-protocol type-check
pnpm --filter @felan-ai/session-protocol test
```

东道方的所有权、接纳、持久性、登记、经纪人、减少和 端到端的趋同测试仍然是单独的"故事1"出入口. 仅此一套 不执行守护进程或证明多进程执行安全.

## 常见问题

### @felan-ai/session-protocol 是什么？

浏览器兼容 Felan 会话协议 v1 合同和验证

### 如何安装 @felan-ai/session-protocol？

在项目目录运行 npm install @felan-ai/session-protocol，或使用 pnpm add / yarn add / bun add。

### @felan-ai/session-protocol 支持 TypeScript 吗？

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

### @felan-ai/session-protocol 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @felan-ai/session-protocol 可以商用吗？

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

### @felan-ai/session-protocol 的下载量有多少？

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

### @felan-ai/session-protocol 还在维护吗？

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