Skip to content

[Clear Room][CR-06] 分清通用工具观测与 ARMS 适配并统一框架标识 #32

Closed

Description

@Aias00

设计约束:以收益决定变更,破坏性变更需逐项论证

用户明确:技术独立是目标,改动幅度和破坏性不是目标。合理的现有概念、API、模块和实现可以保留;不能因为来自上游就要求删除、重命名或重写。新 API 包装旧引擎若只是表面换名不能证明技术独立,但也不以“零旧代码”作为验收指标。

每项破坏性变更在实施前必须完成以下决策记录:

  • 具体问题:现状如何影响职责、正确性、扩展性、依赖隔离或使用体验,附代码/用例/测试证据。
  • 方案比较:至少比较保留现状或兼容演进与破坏性调整,说明为何较小改动不足以解决问题。
  • 收益与成本:列出预期收益、受影响 API/消费者/配置/数据/观测、迁移工作量及回归风险;只有收益足以覆盖成本才采用破坏性方案。
  • 迁移与验证:明确目标版本、旧→新映射、升级步骤、必要的兼容期限或不兼容理由、回滚条件及有意义的行为验收。
  • 评审结论:记录采用、保留或推迟及理由;未形成结论前不实施对应破坏性调整。

不为追求与上游形式不同而修改成熟设计,不机械加前缀、迁包、拆模块或替换行业通用术语。技术独立通过自主架构决策、清晰契约、可控依赖和独立演进能力评估;重写仅用于解决已证实且值得付出迁移成本的问题。

本节是后续明确的约束;若下文历史规划含有无条件重写、删除旧路径或仅因上游来源而替换的表述,按本节执行并在设计阶段修订。

目标升级

本任务纳入 ARGI 独立架构与实现重设计:agentic-ai-java/argi#186 。原有名称与路径仅为现状证据,不要求沿用旧模块或 API。实施前等待目标架构评审,按新的职责与行为契约重新确定范围;必要时重写该能力并移除旧路径。仅改名或包装旧实现不足以证明设计问题已解决;是否替换由问题证据和成本收益决定。本文已有局部回归项仍需覆盖,若与新架构冲突,应更新验收标准并说明取舍。

总览:#30

证据:observation/argi-observation/.../tool/ArmsToolCallingObservation*;ArmsToolCallingObservationConvention.FRAMEWORK = "agentic ai"。

交付与验收:

  • 核实通用观测与 ARMS 约定的实际依赖,通用职责采用领域命名,厂商职责在明确适配边界保留 ARMS 名称。
  • 决定 ARGI framework 属性值及发布兼容策略,不预设 span/metric 名也必须变更。
  • 同步相关自动配置与 starter;验证默认及自定义 Convention/Context 的装配。
  • 使用输出断言验证 framework、span/metric 名及属性;避免意外改变基数和工具调用关联。
  • 提供 dashboard、查询与告警的属性映射和切换说明;未获取实际部署配置时明确待使用方核对项。

不混入 exporter 新功能或 Core #131 的链路追踪能力扩建。

依赖与执行边界

本系列的 Clear Room 指从当前职责和行为契约出发设计。目标名称以评审结论为准;允许有证据地保留现状。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions