需求文档

简介

增强 SDK 能力模型，使其能服务 benchmark、评测 harness、高级调试和外部集成场景。核心是三块能力：运行配置（SessionProfile + RunOptions）、会话级资产（Session Asset Store + Solution 绑定）、运行证据收集（trace 便捷封装）。后端补充必要的 API 扩展，Python SDK 重构为 resource-based 结构并与 TS SDK 概念、命名同步。

需求

需求 1 - Session Asset Store（会话级 Solution 资产上传）

用户故事： 作为 SDK 使用者，我想要上传自定义 solution bundle 到服务器作为临时资产，以便在创建 session 时绑定该 solution，而不需要先注册到全局 solution registry。

验收标准

  1. 当用户调用 POST /api/session-assets/solutions 上传 solution zip 时，系统应该校验 zip 内容（包含合法的 solution.yaml）、解压到 <data_dir>/session-assets/solutions/<user_id>/<asset_id>/，并返回 asset_id、solution_id、可用 roles 列表、expires_at
  2. 当 zip 文件超过大小限制时，系统应该返回 413 错误
  3. 当 zip 包含路径穿越（如 ../../etc/passwd）时，系统应该拒绝并返回 400 错误
  4. 当 zip 解压后总大小超过限制（zip bomb 防护）时，系统应该中止解压并返回 400 错误
  5. 当 zip 内缺少 solution.yaml 或格式不合法时，系统应该返回 422 错误
  6. 当 asset 超过 TTL（默认 24 小时）时，后台清理任务应该自动删除过期 asset 目录
  7. 上传的 asset 不应出现在 GET /api/solutions 的全局/个人 solution 列表中

需求 2 - Session 创建绑定 Solution Asset

用户故事： 作为 SDK 使用者，我想要在创建 session 时引用已上传的 solution asset 或已有的 registry solution，以便 session 使用指定的 solution 运行。

验收标准

  1. 当 POST /api/sessions 请求包含 session_solution_asset_id 和 biz_role_id 时，系统应该从 asset store 加载 solution、通过 session_solution 机制绑定到 session
  2. 当 session_solution_asset_id 对应的 asset 不存在或已过期时，系统应该返回 404 错误
  3. 当同时传入 session_solution_asset_id 和 solution_id 时，系统应该返回 422 错误（互斥）
  4. 当使用 ExistingSolutionRef（传入 solution_id + biz_role_id）时，现有的 solution 绑定流程应不受影响

需求 3 - compaction_ratio Session/Run 级覆盖

用户故事： 作为 benchmark 运行者，我想要在创建 session 或发送消息时指定 compaction_ratio，以便控制上下文压缩行为，而不依赖服务器全局配置。

验收标准

  1. 当 POST /api/sessions 请求包含 compaction_ratio 时，该 session 的所有 run 应默认使用此 ratio（覆盖全局配置）
  2. 当 chat:send 请求包含 compaction_ratio 时，本次 run 应使用此 ratio（覆盖 session 级默认值）
  3. 当未指定 session/run 级 compaction_ratio 时，系统应使用全局 config.compaction_ratio
  4. compaction_ratio 的取值范围、校验规则与全局配置一致（[0, 1)）

需求 4 - Python SDK Resource-Based 重构

用户故事： 作为 Python SDK 使用者，我想要使用与 TS SDK 概念一致的 resource-based API（如 client.sessions.create()、client.solutions.prepare()），以便在两种语言间切换时保持一致的心智模型。

验收标准

  1. BladeAgentClient 应暴露 sessions、solutions、runs（或 headless）三个 resource 属性
  2. 现有的扁平方法（如 client.create_session()、client.get_history()）应迁移到对应 resource 下
  3. 现有的扁平方法应保留为向后兼容的代理（调用新 resource 方法），但标记为 deprecated
  4. Python SDK 的 resource 命名、参数命名应与 TS SDK 保持概念对齐（如 Python sessions.create_with_profile() 对应 TS sessions.createWithProfile()）

需求 5 - SDK 统一能力：SessionProfile + RunOptions

用户故事： 作为 SDK 使用者，我想要通过 SessionProfile 设置 session 级默认参数，通过 RunOptions 设置 run 级覆盖参数，以便精确控制每次运行的行为。

验收标准

  1. SessionProfile 应支持以下字段：solution（ExistingSolutionRef 或 PreparedSolutionAsset）、skills（SkillBundle 列表）、model、compaction_ratio、enable_thinking、memory_enabled、disable_tools、env
  2. RunOptions 应支持以下字段：headless、output_schema、runtime_env、timeout_secs（Python）/ timeoutMs（TS）、trace、compaction_ratio、model
  3. Python SDK 应提供 client.sessions.create_with_profile(intent, profile) 方法
  4. TS SDK 应提供 client.sessions.createWithProfile({intent, profile}) 方法
  5. Python SDK 应提供 client.runs.run(session_id, message, options) 方法
  6. TS SDK 应提供 client.runs.run(sessionId, message, options) 方法
  7. 当 profile.skills 非空时，SDK 应在 session 创建后自动上传所有 skill bundle

需求 6 - SDK Solution 准备能力

用户故事： 作为 SDK 使用者，我想要通过一个方法将本地 solution 目录上传为 session asset，以便后续创建 session 时引用。

验收标准

  1. Python SDK 应提供 client.solutions.prepare(dir_path) 方法，自动打包目录为 zip 并上传，返回 PreparedSolution（含 asset_id、solution_id、roles、expires_at）
  2. TS SDK 应提供 client.solutions.prepareFromDirectory(dirPath) 方法，行为一致
  3. 两端 SDK 应提供 client.solutions.ensure_from_registry(registry_id) / ensureFromRegistry(registryId) 方法，封装现有 POST /api/solutions/ensure-from-registry

需求 7 - Trace 收集便捷封装

用户故事： 作为 benchmark 运行者，我想要在 run 完成后一次性收集 events、history 和最终结果，以便归档和分析。

验收标准

  1. Python SDK 应提供 client.runs.collect_trace(run) 方法，聚合调用现有 history + events API 并返回 RunTrace 对象
  2. TS SDK 应提供 client.runs.collectTrace(run) 方法，行为一致
  3. RunTrace 应包含：events（事件列表）、history（对话历史）、result（结构化结果，如有）、config_snapshot（本次 run 生效的配置快照）
  4. trace 收集不新增后端存储，完全基于现有 API 组合

需求 8 - 集成测试覆盖

用户故事： 作为开发者，我想要有端到端集成测试验证完整流程，以便确保不回归。

验收标准

  1. 应有 Python 集成测试覆盖完整流程：prepare solution → create session with profile → run → collect trace
  2. 应有 TS 集成测试（或 Python 测试同时验证 TS SDK 行为）覆盖关键路径
  3. 应有单元测试覆盖 session asset store 的安全校验：路径穿越、zip bomb、大小限制、TTL 过期
  4. 应有单元测试覆盖 compaction_ratio 的 session/run 级覆盖逻辑

需求 9 - 安全与运维

用户故事： 作为运维人员，我想要 session asset store 有完善的安全防护和自动清理机制，以便在生产环境中安全运行。

验收标准

  1. 上传 zip 的最大大小应有硬限制（默认 100MB）
  2. 解压后总大小应有硬限制（默认 500MB）
  3. 解压时应逐文件检查路径，拒绝任何包含 .. 或绝对路径的条目
  4. asset store 应有后台定时清理任务，删除超过 TTL 的 asset
  5. 每个用户的 asset 数量应有上限（默认 50 个），超出时拒绝新上传
  6. asset store 路径（<data_dir>/session-assets/）应在服务启动时自动创建