v0.4.0

Changelog

All notable changes to this project will be documented in this file.

格式说明：

• Features / 新特性：新增能力、重要增强。
• Bugfixes / 缺陷修复：行为错误、并发问题、稳定性修复。
• Breaking Changes / 兼容性变更：可能影响现有代码的 API 或行为变更。

---

[0.4.0] - 2025-12-09

Features / 新特性

Observability & Telemetry

• 统一可观测性体系

  • 增强 gecko/core/telemetry.py：
    • 使用 opentelemetry-sdk>=1.38 推荐方式创建 Resource，支持 service.name、service.version、deployment.environment 等标准字段。
    • 新增 TelemetryConfig 配置项：batch_export_interval_ms、max_export_batch_size，可根据生产环境吞吐和延迟需求调优。
  • get_telemetry() 支持 自动初始化：首次调用时会创建默认 GeckoTelemetry 并立即 setup()，降低接入门槛。
  • Telemetry 与 logging 的 trace_id/span_id 通过 ContextVar 打通，保证日志与 Trace 关联一致。

• Metrics 指标体系

  • 引入轻量级指标模块 gecko/core/metrics.py（Counter/Gauge/Histogram）：
    • 支持高并发下的分片锁（shard-based locking）减少锁竞争。
    • 提供计时场景的上下文管理器，便捷记录接口耗时。
    • 支持导出 Prometheus 文本格式，便于对接监控系统。

• ExecutionStats 执行统计

  • 新增 gecko/core/engine/stats.py（或同名模块）：
    • 统一记录引擎执行维度的统计信息：total_steps、total_time、input_tokens、output_tokens、tool_calls、errors、estimated_cost。
    • 内部使用 threading.Lock 保证并发安全。
    • 提供 get_avg_step_time()、get_error_rate()、get_total_tokens() 等便捷方法。
  • 各 Engine 通过 Hook 在每步执行后更新统计，为后续成本监控与性能分析打基础。

Memory / 记忆系统

• HybridMemory：短期 + 长期混合记忆
  • 新增 gecko/core/memory/hybrid.py：
    • 基于 TokenMemory（短期上下文）与向量库（长期记忆）的组合设计。
    • get_history() 中并行执行短期与长期检索（asyncio.gather），在给模型的上下文中按照：
      System Prompt → Long-term Context(System) → Short-term History 的顺序拼装消息。
    • 长期检索使用 embedder.embed_query + vector_store.search(filters={"session_id": self.session_id})，保证多会话隔离。
    • archive_message() 仅归档长度大于一定阈值的消息，减少噪声数据写入向量库。
  • 在 gecko/core/memory/__init__.py 中导出 HybridMemory，可直接：
    from gecko.core.memory import HybridMemory 使用。

Workflow / 组合与工作流

• Workflow Engine DAG 并行与恢复能力增强

  • gecko/compose/workflow/graph.py：
    • 负责管理 Workflow DAG：节点/边维护、拓扑排序、并行层级构建。
    • 增强静态校验：环检测（cycle detection）、孤立节点检测，异常一律使用 WorkflowError 子类。
  • gecko/compose/workflow/engine.py：
    • 按层级并行执行 DAG（每一层使用 TaskGroup 并行）。
    • 引入 COW + Diff Merge 的上下文管理策略：
      • 并行节点使用 copy-on-write 视图，避免互相污染；
      • 执行结束后按“最后写入优先”策略合并变更。
    • 支持 Next(...) 动态控制流：
      • 节点返回 Next 指令可以覆盖默认拓扑路径，实现条件跳转与动态分支。
    • 支持断点恢复：
      • 可以从持久化状态恢复并从指定节点继续执行。

• Team 执行策略扩展（并行/赛马）

  • gecko/compose/team.py：
    • 新增 ExecutionStrategy：ALL 与 RACE 模式：
      • ALL：等待所有 Agent 成员执行完成（Map-Reduce 默认模式）。
      • RACE：赛马模式，取第一个成功结果，其它任务自动取消。
    • 新增 input_mapper，支持从一个输入生成多个子输入（Sharding）后分配给不同成员。
    • 为 RACE 模式引入 _winner_lock，保证并发场景下只有一个“获胜者”被选中。

Structure / 结构化输出

• 结构化输出自愈修复能力

  • 新增 gecko/core/structure/repair.py：
    • 提供基于 LLM 的 JSON 自修复功能：
      • 将「破损/不合法 JSON + 解析错误信息」作为 Prompt，交给模型生成修复后的结构化输出。
  • gecko/core/structure/engine.py 更新解析策略：
    • 结构化解析路径分为三层：
      1. 优先从 ToolCall 直接解析为结构化数据；
      2. 从文本中提取 JSON（json_extractor），再做 Pydantic 校验；
      3. 如仍失败，调用 repair 模块进行 LLM 自愈（有限次数）。

• JSON 提取器增强

  • gecko/core/structure/json_extractor.py：
    • 提供多策略 JSON 提取：正则、括号匹配、Markdown 代码块等；
    • 支持插件式扩展提取策略。

Resilience / 系统韧性

• 熔断器（Circuit Breaker）模块
  • 新增 gecko/core/resilience.py：
    • 实现通用熔断器，可包装模型调用或任意外部 IO。
    • 支持失败计数、半开窗口、冷却时间等配置。
    • 防止下游服务连续失败导致整系统被拖垮。

Models / Provider 适配

• 统一 Provider 异常体系

  • 新增 gecko/plugins/models/exceptions.py：
    • 引入 ProviderError 及其子类（RateLimit/Auth/ServiceUnavailable 等），统一继承自 ModelError。
    • 将模型服务相关错误统一编码为 ErrorCode，便于上层统一处理与监控。

• LiteLLM Driver 生产级化

  • gecko/plugins/models/drivers/litellm_driver.py：
    • 引入 tokenizer 预加载：优先使用 tiktoken，不可用时退回字符长度估算，提升 Token 计数精度。
    • 使用 gecko/core/resilience 的熔断器包装请求，增强对 LiteLLM / 模型代理不稳定的容错能力。
    • 将 LiteLLM 错误统一映射到 ProviderError 子类，填充 ErrorCode 和可重试信息。
    • 增加响应适配层，将 LiteLLM 输出转换为框架统一的响应结构。

---

Bugfixes / 缺陷修复

Concurrency / 并发安全

• ToolBox 统计并发问题修复

  • gecko/core/toolbox.py：
    • get_stats() 中改为在持有锁时对 self._tools 做快照（tool_names = list(self._tools.keys())），并在迭代时检查 name in self._execution_count，防止工具在统计过程中被移除引发 KeyError。

• 流式缓冲区完整性修复

  • gecko/core/engine/buffer.py：
    • 增强对流式 tool_calls 的索引和分片处理：记录 _max_tool_index，保证乱序/分片场景下的结果正确重组。
    • 增加 _max_content_chars 上限，防止异常长返回撑爆内存。
    • 引入 RLock 保护更新和构建逻辑，在多线程/异步混用场景下保持一致性。

Engine / Workflow 行为修复

• ReAct 引擎 Message 参数不兼容问题

  • gecko/core/engine/react.py：
    • 修复 Message.assistant(tool_calls=...) 与 Message 模型签名不一致导致的 TypeError。
    • 优先从 tool_calls 解析结构化结果，其次才回退到 content 文本解析，避免丢失 ToolCall 信息。

• Next 控制流透传问题

  • gecko/compose/workflow/executor.py：
    • 修复部分路径下 Next(...) 被当作普通返回值处理的问题，确保由 Executor 识别并作为控制流指令传回 WorkflowEngine。

• Workflow 图校验增强

  • gecko/compose/workflow/graph.py：
    • 增强环检测和孤立节点检测逻辑，并统一使用 WorkflowError 子类抛出，避免工作流在运行时才暴露拓扑问题。

Logging & Tracing

• 日志上下文一致性修复
  • gecko/core/logging.py 与 gecko/core/telemetry.py：
    • 统一使用同一组 ContextVar（trace_id_var、span_id_var、extra_context_var），确保日志和 OTEL trace 共享相同的 TraceId/SpanId。
    • 修复少量日志消息与 ImportWarning 文本中的小拼写问题。

其他稳定性修复

• DI 容器线程安全

  • gecko/core/container.py：
    • 使用 RLock 保护依赖注册和解析流程，修复多线程环境下潜在的状态竞争。

• 记忆系统执行器关闭

  • gecko/core/memory/__init__.py：
    • 确保 shutdown_token_executor 对外可见，避免在进程结束前遗留线程池或任务。

---

Breaking Changes / 兼容性变更

注意：0.4.0 版本在设计上尽量保持向后兼容，未主动引入显式的 API 破坏性调整。
下面列出的是潜在行为变更，可能会在极少数场景中影响已有系统行为。

• Telemetry 自动初始化行为

  • get_telemetry() 现在会在首次调用时自动创建并初始化默认 GeckoTelemetry 实例。
  • 如果已有代码在自定义 Telemetry 之前调用了 get_telemetry()，可能会导致实际使用的是默认配置。推荐做法：
    • 在应用启动阶段显式调用 configure_telemetry(...) 设置自定义配置。

• 结构化解析策略调整

  • StructureEngine 现在优先从 ToolCall 中解析结构化数据，其次才从文本 JSON 中解析，最后才通过 LLM 自愈修复。
  • 如果上层逻辑依赖于“始终从纯文本中解析”这一旧行为，结果可能略有差异（但通常是更合理的解析路径）。

• Workflow 并行与上下文合并行为

  • 引入 COW + Diff Merge 的上下文管理策略后，多个并行节点对上下文的写入冲突将按“最后写入优先”规则处理。
  • 如果之前依赖于共享可变对象的“非确定性行为”，现在可能会变得更稳定和可预测。

总体而言：未发现 API 层面的硬性 Breaking Change。若在升级 0.4.0 后遇到行为差异，建议重点检查：

• 是否依赖旧的 Telemetry 初始化方式；
• 是否依赖旧的结构化输出解析路径；
• 是否在 Workflow 中存在对并行写共享状态的特殊假设。

---

[0.3.1]

Summary / 概述

• 0.3.1 是在 0.3.0 基础上的小版本维护更新：
  • 对部分核心模块（Workflow Models、Memory、Storage 等）做了工程化整理；
  • 同步文档与版本元数据（gecko/version.py 中更新 __version__ 等）；
  • 为后续 0.4.0 的 Telemetry / Workflow / Memory 重构铺路。

该版本未引入已知的 Breaking Changes。

---

Notes

• 从 0.3.1 → 0.4.0 的升级建议：
  1. 在应用启动阶段显式调用 configure_telemetry()，而不是依赖默认自动初始化。
  2. 如有自定义 Workflow 或 Team 执行逻辑，建议补充集成测试，验证在并行执行、Next 跳转和断点恢复场景下行为符合预期。
  3. 如对结构化输出高度依赖，建议开启日志，观察 StructureEngine 的解析与修复过程，评估新策略的效果。