@felan-ai/session-protocol (英语)
Felan的运行时间中立会话协议 v1. 仅限无害环境管理的一揽子措施
假设类型、范围验证和JSON线框架。 独家
运行时间依赖是 [email protected]它进口了Node、Pi、Core探员、TUI,
ACP或平台API,并可在浏览器中直接运行.
01.0是首次公开发布. 0.2.0 加上 channel 源代码。 增加0.3.0个
远程团队主机身份 follow_up,客户端选择的远程会话ID
和自动化命令来源。 年长的读者拒绝这些合同,所以他们
正在打破未成年人。 发布后
docs/maintainers/releasing.md唯一的公共子路径是 .; 没有守护进程或配置文件
执行此处导出。 打破变化需要下一个未成年人;
兼容的校正保留在内 0.3.x. 线、存储行和不匹配控制
版本是独立的常数,最初 1。 。 。 .
边界 API
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个条目。 主机执行队列/后压、保留和套接字
平台限制.
pnpm --filter @felan-ai/session-protocol build
pnpm --filter @felan-ai/session-protocol type-check
pnpm --filter @felan-ai/session-protocol test
东道方的所有权、接纳、持久性、登记、经纪人、减少和 端到端的趋同测试仍然是单独的"故事1"出入口. 仅此一套 不执行守护进程或证明多进程执行安全.