TypeScript SDK 设计

laya-client 是一个无依赖的 HTTP 客户端，用于自托管的 laya-serve 服务器。它使用 POST /v1/systemone 端点，不引入任何 Python 生产代码或服务器依赖。这个 npm 包从版本 0.1.0 起步，与 Python 的发布相互独立。

边界

组件	职责
`sdk/typescript`	问题/答案类型、预设、校验、原生 fetch、错误与取消
`laya/serve.py`	既有的 HTTP 端点、Bearer 认证、健康检查和请求上限
`laya/router.py`	checkpoint 选择、加载和推理路由
`laya/agent.py`	分词、PyTorch 推理和校准后的答案格式化
`laya/presets.py`	五套生成的 TypeScript 问题预设的来源

flowchart LR
    A[JavaScript or TypeScript application] --> B[laya-client]
    B -->|POST /v1/systemone| C[Existing Laya server]
    C --> E[Router and local checkpoint]

SDK 导出 predict 和一个 Laya 专用的 health 探针。它提供 ESM、CommonJS 和声明文件，并保留推断出的 question ID 和 choice 标签。当 JavaScript 或 TypeScript 应用通过 HTTP 与自托管的 Python laya-serve 通信时，用 laya-client。当推理必须在 JavaScript 内部通过它本地的 ONNX 运行时直接跑、不需要 Python 服务器时，用 laya-ts。

共享契约

请求包含 state 和 questions。除非为一次预测另外配置或提供，laya-client 会省略 model，让 laya-serve 自动选择一个本地 checkpoint。客户端级或逐调用的 model 可以选择一个本地 checkpoint。choice 标签数组在传输之前会被规范化成带 null 描述的映射。

响应保留 model、answers 和 token usage。Laya 的 routing 和答案 action 字段是可选扩展；Noul 的置信度也是可选的。Choice 和 Score 的置信度、分布，以及 Score 的档位说明仍是必需的。可选扩展在场时会被校验。

/v1/systemone 不暴露 Python 的独立路由方法，也不暴露 task 和 lang 覆盖。SDK 会拒绝这些遗留选项，而不是静默忽略它们。Laya 公开的 /health 返回 status、loaded 和 device。预测从不先探测健康。

FastAPI 的 detail 字符串和校验数组会保留为 LayaAPIError 的 messages/details。来自兼容后端的结构化错误信封也会被接受。请求有可配置的截止时间和调用方取消，且从不自动重试。

验证与发布

单元测试覆盖请求构建、所有答案形状、Laya 扩展、FastAPI 错误、JSON 校验、截止时间和取消。类型检查覆盖可选元数据、被拒绝的遗留方法/选项、推断出的答案类型，以及 ESM/CommonJS 消费者。实时集成测试用一个小型离线 checkpoint 启动未改动的 laya.serve 应用，把 SDK 的预测与直接 Python 推理对比，并演练路由、预设、认证和请求上限。CI 在 Node.js 22 和 24 上跑 SDK 检查。

极小的随机权重验证的是传输和数值一致性，不是预训练质量或性能。

设置、示例和 npm 发布见 SDK 指南。这个包会以 laya-client 这个名字发布。Python 的发布工作流不变。