xtrape-interaction-nodejs

@xtrape/interaction — Interaction Layer ↔ Platform 的接口定义:数据结构与 接口描述,不含实现。

来源拍板:xtrape-docs#199 的 D5 / D6 / D7 / D12 / D19 / D20,以及 xtrape-docs#276 的 R2–R9 六条裁定(R2/R3/R5/R6/R9 于 0.8.8、R4 展示词汇于 0.8.9 落地);本仓的概念合同要求见本仓 issue #1。 canonical 产品架构以 xtrape-docs 为准;本 README 与 canonical 冲突时,canonical 赢。

pnpm add @xtrape/interaction@^0.8.10

package version: 0.8.10      # 与 stack 版本对齐(docs#199 · D19,0.8.x 未冻结)

1. 它是什么

接口定义包:Zod schema、由其推导的 TypeScript 类型,以及描述这些形状含义的 注释。仅此而已。

它不是:

• 不是 SDK,不是客户端,不是服务端;
• 不是实现 —— 实现在各交互产品(Panel、Telegram、Exposure、CLI)与 Platform 一侧;
• 不形成 Service,也不形成 Worker。安装本包不会让任何进程变成被 Platform 注册、 管理或调度的对象;它没有注册握手、没有心跳、没有令牌、没有生命周期。

2. 与 @xtrape/contracts 的分工

| 包 | 承载的面 | 合法消费者 | | --- | --- | --- | | @xtrape/contracts | widget ↔ platform | platform-ce、@xtrape/connector(SDK)、各 Widget(demo、mcp-ops、anyapi-chatgpt …) | | @xtrape/interaction(本包) | interaction ↔ platform | Panel、Telegram、Exposure、CLI 等 Interaction Layer 表面;以及作为该面服务端一侧的 platform-ce |

两包互不依赖,这是 docs#199 · D20 的硬规则:

任何 Interaction Layer 都不应该依赖 contracts,他们应该依赖 xtrape-interaction。

• 本包 dependencies 里没有 @xtrape/contracts,源码里也没有任何一处 import 它 (有测试守着这两条);
• 反向同理:contracts 不依赖本包;
• 需要共享基础类型时,先设计共享方式,不得随手交叉 import。平台对象读模型的 归属已裁(docs#276 · R2 = 方案 1):本包定义 interaction-owned 只读投影 (src/platform-read.ts),与 contracts 的权威 wire 定义分别实现,即使形似 也互不依赖 —— 两者目的不同(权威 wire vs 消费者视图)。

xtrape-platform-ce 同时是两个包的消费者,这不违反 D20:它是 widget↔platform 与 interaction↔platform 两个面的服务端一侧,本来就要同时说两种话。规则约束的是 Interaction Layer 不得依赖 contracts。

3. Interaction Layer 是什么

canonical concepts/09-platform-object-model.md §3:

Interaction Layer 是 Platform 用来指称「用户、AI 系统与外部工具借以到达 Platform 的那些产品」的概念。当前的交互产品是 Panel、Exposure、 Telegram / Channels,以及未来的交互产品 —— 它们是并列的兄弟。

• 交互产品不得各自持有 registry、repository、authorization、runtime 状态的独立 副本;它们消费共享的 Platform 基础设施(Checkpoint、授权、调用、命令生命周期、审计);
• MCP 是真实协议,位于 Exposure 之下的一个投影,不是本层的伞名,也不与 Panel / Telegram 并列;
• Telegram 是独立交互产品,与 Exposure 并列,不是 Exposure 的投影;
• 不得用 Gateway 或 UX 作为本层的伞名。

拓扑基数(docs#199 · D18):Interaction Layer n : 1 Platform。

4. 调用链纪律:交互层不直接执行 Action

Device / Interaction Layer -> Checkpoint -> Resource -> Command -> Action

交互层做的是形成一个受治理的 Command,不是执行 Action。一次点击、一条 Telegram 消息、一个 MCP 调用,都要先经过 Checkpoint(不可变、schema 约束、受策略 治理的操作边界),由 Platform 解析出 Resource 并据 Checkpoint + Resource 作出授权 判定,才落成 Command;真正执行 Action 的是 Service 的 Worker。

因此本包里出现的 action 字样(如 ActionDisplayRowAction)描述的是呈现意图, 不是执行入口:action 字段是「要发起哪个 Action」的名字,不是「就地执行」的许可。

5. 对象模型边界:投影,不是权威

本包不定义 Platform 对象本身 —— Widget / Service / Worker / Capability / Action 的概念权威在 canonical concepts/09,widget↔platform 的 wire 权威在 @xtrape/contracts。

本包定义的是交互面看到它们的样子(docs#276 · R2):src/platform-read.ts 的 ServiceView / WorkerView / ActionView / CommandView / AuditEventView / ApprovalRequestView 是对真实读端点的消费者视角只读投影 —— 行为词汇开放、 响应 passthrough、只钉消费者真依赖的字段;保真由 platform 侧的 conformance 套件 负责。有测试守着「本包不导出 Platform 对象 schema 本名」(导出的是 *View)。

统一主体是 Account(docs#276 · R3):从任何交互产品(Panel / Telegram / Exposure / 未来 UX)进入的都是 canonical Account,经各自的 Device 接入; managed-access 面(src/access.ts)就是这个统一标准的会话与调用形状。旧的 User*(usr_ 合成 id、从未签发过的 csrfToken)已整体退役;管理面协议形状归 docs#276 的后续期。

版本(docs#276 · R5):本边界自带 interactionVersion(src/version.ts), 与 contracts 的 contractVersion 对称、各说各的边界 —— 每个顶层 interaction 文档(请求、响应、错误、列表信封)都携带它,没有未版本化的文档。

6. 非目标

• 不承担鉴权实现:本包描述会话与凭据引用的形状,不做口令校验、令牌签发、 限流、锁定 —— 见 docs/security-boundary.md; (操作员登录的管理面协议形状属 docs#276 后续期,本版不含);
• 不承担 MCP transport / session:那属 Xtrape Exposure;
• 不做渲染:展示信封只声明「这列是什么、这个字段怎么格式化」,具体渲染由交互产品 决定;
• 不含 HTTP 客户端、轮询循环、ID 生成、存储、业务流程。

7. 当前面

| 模块 | 内容 | | --- | --- | | src/version.ts | INTERACTION_VERSION / InteractionVersionSchema —— 本边界的 wire 版本(docs#276 · R5) | | src/envelopes.ts | HTTP 信封数据形状:ErrorEnvelopeSchema、ErrorCodeSchema(开放词汇)、ListQueryBaseSchema、TimeRangeQuerySchema、pagedSchema/Paged、listResponseSchema/ListResponse(R6;实现物如 HttpError/parseSort/paginate 两包都不收) | | src/platform-read.ts | Platform 对象读模型(R2 = 方案 1,UX 中立):六个端点族的 *View / *ListQuery / 版本化响应文档 | | src/access.ts | Managed access 与 governed invocation 面(统一标准的会话/发现/调用形状;全部文档携带 interactionVersion;含 arch/16 §6.1 的 device-authenticated 建立请求 —— 文档零凭据、.strict()) | | src/platform.ts | 平台进程自身:PlatformEdition/PlatformEditionSchema、PlatformVersionSchema(D6 由 System* 改名;PlatformHealth 已按 R9 退役) | | src/action-display.ts | Action 结果展示信封:ActionDisplayFormat / ActionDisplayVariant(开放词汇)及 Column / List / DetailField / Detail / RowAction / ShowWhen 各族 —— 含 R4 的 UX 中立超集(lockFields/submitLabel/variant/showWhen/showResult/sensitive/pre) |

已退役(docs#276):User* 全家与 UserSession(R3,统一主体 = Account)、 PlatformHealthSchema / DashboardSummarySchema(R9,两端皆无生产者)。

每个符号的中文含义、来源 file:line、改名依据,见 docs/migration.md;概念说明见 docs/concepts.md。

8. 开发

pnpm install
pnpm typecheck
pnpm test
pnpm build

运行时基线 Node 24(xtrape-docs reference/10-runtime-baseline.md)。