knowledge-shared-api-and-runtime-schemas

Module Structure

该组件以 TypeBox schema 同时提供 TypeScript 静态类型、运行时输入验证和公开输出投影；Web 构建直接别名到 CLI 的 browser-safe API 源码，避免复制 DTO。

Directory Layout

• packages/cli/src/schema/index.ts — Runtime、Default、StringEnum 和 TypeBox 导出
• packages/cli/src/schema/validation.ts — clone、default、validate、clean 和结构化错误
• packages/cli/src/api/schemas.ts — Session、Task、消息、权限、模型和设置公共合约
• packages/cli/src/api/browserSchemas.ts — Browser 导航与交互的封闭输入 union
• packages/cli/src/api/teamSchemas.ts — Team 快照和写请求合约
• packages/cli/src/api/attachmentLimits.ts — 多表面共享的消息与附件上限
• packages/cli/src/api/promptCacheMetrics.ts — Provider cache 指标的安全派生与展示
• packages/cli/src/tools/validation/schemaToJson.ts — Provider function schema 清理
• packages/cli/web/vite.config.ts — Web @api 到 CLI API 源码的构建别名

Key Entry Points

• Runtime(schema) — 给 TypeBox schema 增加不可枚举的 parse / safeParse
• safeParseSchema(schema, value) — 返回 discriminated result，不抛异常
• parseSchema(schema, value) — 校验失败时抛 SchemaValidationError
• schemaToFunctionSchema(schema) — 生成不含 TypeBox runtime 注解的封闭 JSON Schema
• SessionSchema / CreateTaskRequestSchema / PermissionResponseSchema — 跨 Server/Web 高频公共合约

API Surface

Runtime Schema Helpers

• Runtime(schema) — 保留标准 JSON Schema 可序列化形状，并附加非枚举解析方法
• Default(schema, value) — 输入字段可省略，解析结果应用默认值
• StringEnum(values, options?) — 生成所有 pi-ai Provider 都能接受的字符串 enum JSON Schema
• safeParseSchema(schema, value) — 适合 HTTP 入口映射 4xx
• parseSchema(schema, value) — 适合可信内部边界和输出投影
• SchemaValidationError.issues — 提供解码后的字段路径、keyword、消息和原值

Shared Contracts

• SessionSchema — 公开 Session 身份、lineage、任务状态和资源选择，不包含内部 lease 对象
• CreateTaskRequestSchema / CreateTaskResponseSchema — Task 默认隔离、权限模式和准入状态
• SendMessageRequestSchema — 消息、模型、附件与 structured output 输入边界
• BrowserActionSchema — Browser 交互 discriminated union，显式禁止额外属性
• TeamSnapshotSchema — Team 成员和任务图的跨表面只读投影

Usage Examples

Hono 路由验证请求

const parsed = safeParseSchema(CreateTaskRequestSchema, body);
if (!parsed.success) {
  throw new BadRequestError('Invalid task request');
}