Skip to content

feat(sdk): add structured turn output - #2506

Open
limityan wants to merge 1 commit into
GCWing:mainfrom
limityan:yanzhn/sdk-structured-output
Open

feat(sdk): add structured turn output#2506
limityan wants to merge 1 commit into
GCWing:mainfrom
limityan:yanzhn/sdk-structured-output

Conversation

@limityan

@limityan limityan commented Aug 25, 2026

Copy link
Copy Markdown
Collaborator

背景

外部应用拿到自然语言文本后,还需要自己猜测和解析格式,稳定性不足。这个 PR 在现有 SDK Host、Agent Runtime 和 provider adapter 上补齐单轮结构化结果,让应用可以给出 JSON Schema,并直接获得可机器处理的结果。

整体做法参考了 Codex 的 per-Turn output schema 和最终消息语义,同时按各 provider 官方协议映射:OpenAI Structured OutputsClaude Structured OutputsGemini Structured Outputs

主要变更

  • TypeScript QueryInput / TurnInput 增加 outputSchemaResult 增加 structuredOutput,并始终保留原始 outputText
  • Agent Runtime 增加单 Turn、provider-neutral 的 output schema 字段,通过已有调度、恢复和模型请求链传递,不增加第二套 Runtime 或 IPC。
  • 在已有 OpenAI Chat、OpenAI Responses、Anthropic、Gemini adapter 中映射官方结构化输出参数;自定义 request body 无法覆盖 SDK 指定的 schema。
  • SDK Host 协议升级到 v6,声明 structuredOutput capability;只接受 object-root schema,解析失败返回 typed failed Result。
  • 结构化查询只使用最后一次模型尝试的文本,避免工具调用前后的多轮文本被拼接;普通查询继续保留原有聚合行为。
  • TypeScript 生成式 wire validator 仅接受 JSON-compatible 的 Record<string, unknown> / unknown 值,继续保持 fail-closed。

范围与影响

  • 这是单轮结果契约,不包含自定义 tool、hook、Python SDK、NAPI/WASM、Host 进程模型调整或产品工作流。
  • npm 包仍为 0.0.0private: true;未发布 npm 或 PyPI,只支持当前本地/私有包使用方式。
  • 协议从 v5 升到 v6,本地 TypeScript SDK 与 Host 需要配套更新。当前尚无公开发布版本,因此无需兼容已发布客户端。
  • 总变更 860 additions / 82 deletions,主要跨越现有端到端调用链和对应测试,没有新增独立框架。

验证

  • cargo test --locked -p bitfun-sdk-host
  • cargo test --locked -p bitfun-sdk-host-app
  • cargo test --locked -p bitfun-core --features agent-runtime output_schema -- --nocapture
  • cargo test --locked -p bitfun-runtime-ports --features agent-api
  • cargo test --locked -p bitfun-ai-adapters provider_request_bodies_map_turn_output_schema
  • pnpm --dir sdk/typescript test
  • pnpm --dir sdk/typescript type-check
  • cargo check --locked --workspace --exclude bitfun-desktop
  • git diff --check
  • GitHub CI:三平台 CLI、三平台 Rust、Frontend、Shell 和最终 Rust / CLI 聚合门禁全部通过。

完整 cargo check --locked --workspace 在 Desktop build script 阶段因工作区缺少 src/mobile-web/dist 资源而中止;排除 Desktop 后的全 workspace check 已通过。CI 会创建所需资源目录,三平台 Rust Build Check 已完整通过。cargo fmt --all -- --check 仍会报告 main 上 5 个与本 PR 无关的既有格式差异,本 PR 修改的 Rust 文件已单独执行 rustfmt。

@limityan
limityan force-pushed the yanzhn/sdk-structured-output branch from e134f42 to baadffd Compare August 25, 2026 15:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant