这是 subconscious-python SDK 的迁移指南,用于从 0.x 升级到 1.0。1.0 将 Python SDK 的响应类型与 API 传输格式对齐:响应模型改为 Pydantic BaseModel 而非 dataclass,字段与 Subconscious API 返回的 JSON 一一对应。
主要破坏性变更:Usage 变为扁平 Pydantic 模型(input_tokens、output_tokens、duration_ms),旧的 models 与 platform_tools 字段被移除;ModelUsage、PlatformToolUsage 整体删除;ReasoningNode 移除,改用 ReasoningTask;ReasoningTask.subtask 重命名为 subtasks,tooluse 由 List[Any] 改为 Optional[AgentToolUse];RunResult.reasoning 由 Optional[ReasoningNode] 改为 Optional[List[ReasoningTask]];Run 新增 Optional[RunError] 字段用于失败运行;Run、RunResult、Usage、RunError、ReasoningTask、AgentToolUse 均改为 Pydantic BaseModel;Engine 字面量扩展出 tim-edge、tim-oss-local、tim-1.5、tim-gpt-heavy-tc。新导出包括 AgentToolUse、RunError、ReasoningTask。
使用方式上,属性访问不变(如 run.run_id、run.usage.input_tokens),但 isinstance 检查与构造方式不同,应改用 pydantic.BaseModel 判断。常见替换:usage.models 改为 usage.input_tokens/output_tokens,platform_tools 直接删除,.subtask 改为 .subtasks,类型提示中的 ReasoningNode 改为 ReasoningTask,run.result.reasoning.title 改为 run.result.reasoning[0].title(现为列表),RunInput 的 reasoning_format 字段删除。
另外 reasoning_format(线上别名 reasoningFormat)已移除,带该字段的请求会被 API 拒绝,如需引导推理轨迹,应把它并入 instructions 或 answer_format。result.answer 在线上始终是字符串,SDK 会附加 parsed_answer 伴生字段,通过尽力而为的 json.loads 解析,类型为 Any,内容为空或非合法 JSON 时为 None,如需类型化实例可用自己的 Pydantic 模型校验。以上为公开资料整理,未提供的收费、平台等信息暂未说明。