Feat entity

[Meow711]

No description provided.

[github-actions]

优点

• EntityService 在保留原有 create/poll/report 工作流的基础上，补上了 handle 类型实体的分支处理，整体职责仍然集中在实体分析域内，接口形状相对统一（octoevo/mate/services/entity.py）。
• 新增了 HandleReport 模型，并且为 create_and_wait() 增加了 handle 场景测试，至少覆盖了“轮询完成后按 handle_analysis_id 取报告”这条主路径（octoevo/mate/models.py, tests/test_dashboard_api_contract.py）。
• 文档、示例和中英文 README 基本同步更新到了 entity 术语，减少了接口名和文档描述不一致的问题（README.md, README_cn.md, examples/product_analysis/example.py）。

问题

严重（必须修复）

1. 公开 SDK 接口被直接删除，形成未声明的 breaking change

• 文件：octoevo/mate/client.py, octoevo/mate/services/init.py, tests/test_dashboard_api_contract.py
• 问题是什么：PR 将 client.product 替换为 client.entity，并删除 ProductService 的公开导出；测试还显式断言 client 不再具有 product 属性。这不是内部重构，而是直接移除了现有用户可见 API。
• 为什么重要：这是 Python SDK 的公开兼容性破坏。任何现有代码中使用 client.product.create_and_wait(...) 或 from octoevo.mate.services.product import ProductService 的用户，升级后都会在运行时或导入时直接失败。
• 如何修复：至少保留一版兼容层，例如：
  • 在 Client 上继续暴露 self.product = self.entity
  • 保留 octoevo/mate/services/product.py 作为薄包装或别名，并标记弃用
  • 若确实要移除，必须配套新的 major 版本策略和明确迁移说明，而不是在当前改动里静默删除

重要（建议修复）

1. Codex review workflow 的并发组改成全局常量后，会导致不同 PR 之间互相取消

• 文件：.github/workflows/codex-review.yml
• 问题是什么：concurrency.group 从按 PR 编号隔离，改成了全局固定值 codex-review，同时 cancel-in-progress: true 保持开启。
• 为什么重要：这会让任意一个 PR 上的新 review 运行取消另一个 PR 正在进行中的 review。结果是仓库同一时间只能有一个 PR 拿到完整审查，其他 PR 会被静默打断，CI 自动审查能力明显退化。
• 如何修复：恢复按 PR 维度隔离，例如使用 codex-review-${{ github.event.pull_request.number }}；如果确实要限流，也应避免跨 PR 取消，可改为排队而不是取消。

2. 变更涉及 breaking change，但发布说明没有记录迁移路径或兼容性影响

• 文件：README.md, README_cn.md, RELEASES.md
• 问题是什么：文档全面改成了 client.entity，但没有任何位置说明 client.product/ProductService 已废弃或移除，也没有迁移示例。RELEASES.md 只是回写了历史 0.1.0 文案，没有新增当前版本的 breaking change 说明。
• 为什么重要：对于 SDK，这类接口名变更比实现细节更敏感。即使代码层面决定保留破坏性修改，也必须明确告知升级用户如何迁移，否则很容易造成无提示升级失败。
• 如何修复：增加本次版本的 release note，明确列出：
  • client.product -> client.entity
  • octoevo.mate.services.product.ProductService -> EntityService
  • 是否保留兼容别名、计划何时删除

3. 测试覆盖了新路径，但没有覆盖任何向后兼容回归场景

• 文件：tests/test_dashboard_api_contract.py
• 问题是什么：现有测试只验证“新接口存在”和“旧接口已不存在”，完全没有兼容层或弃用行为测试。
• 为什么重要：这意味着 PR 当前的测试方向是在固化 breaking change，而不是防止回归。对于 SDK 演进，这会让后续维护者很难判断是否仍需兼容老调用方式。
• 如何修复：如果预期兼容，增加测试断言 client.product is client.entity 或旧导入路径仍可用；如果预期不兼容，则应至少补充版本/文档层面的迁移保障，并在评审中明确这是有意的破坏性发布。

次要（可优化）

1. EntityService 和示例代码仍沿用 product 参数名，术语层面不一致

• 文件：octoevo/mate/services/entity.py, examples/product_analysis/example.py, README.md
• 问题是什么：外部文档已改成“entity analysis”，但方法签名和调用示例仍是 product=...。
• 为什么重要：这不会立刻导致 bug，但会持续制造认知负担，尤其是 handle 分支已经不是“product”语义了。
• 如何修复：后续可考虑引入更通用的请求模型/参数命名，例如 entity，同时保留 product 作为兼容别名一段时间。

建议

• 这次改动更像“API 重命名 + handle 报告支持”两个主题，建议拆分看待：先保证兼容性，再引入新语义和文档更新。
• 对 SDK 公共接口做重命名时，优先采用“兼容别名 + 弃用提示 + 发布说明”的渐进策略，不要一次性硬删除。
• tests/test_dashboard_api_contract.py 目前更偏 endpoint contract mock，缺少对迁移策略本身的约束；如果决定保留兼容层，应把它也纳入测试。
• 运行验证未执行；本次结论仅基于 PR diff、现有代码和测试的静态审查。

结论

可以合并吗？ 修复后可合并

理由： handle 报告支持本身方向合理，但当前 PR 同时引入了未声明的公开 API breaking change，并且 CI review workflow 还新增了跨 PR 互相取消的问题。这两个问题都会直接影响用户或仓库流程，不适合按现状合并。