# AgentScope 2.0 兼容性尖峰基线

> 对应工单：`RC-BE-000`
> 日期：2026-09-05
> 候选版本：`agentscope==2.0.5`（PyPI 当前还有 `2.0.6` / `2.0.7.post1`；POC 通过前不把精确版本写入 lock）

## 结论（当前）

**条件 Go（安装 + 事件适配层） / 暂缓（真实模型评测与 uv.lock）**

- 本机 Python 3.12.10 可安装 `agentscope==2.0.5`。`uv pip install` 未降级现有 FastAPI / Pydantic / OpenAI SDK；新增 25 个包（含 `dashscope`、`typer`、`opentelemetry-exporter-otlp`）。
- 公开 API 已核对：`agentscope.event.EventType` 与本仓库 `ConversationReplica` 映射表一致；`agentscope.model.ChatModelBase` / `OpenAIChatModel` 存在。`RC-BE-007` 已用 `DeerFlowChatModelAdapter` 接 `AppConfig.models`。
- 单元测试覆盖 dict 事件与真实 AgentScope 事件对象两条路径。
- **尚未**把精确版本写入 `uv.lock`（按计划等纵向 POC 通过）。应用侧已声明可选 extra：`report-collaboration = ["agentscope==2.0.5"]`，不进入 harness 依赖。
- **业务终态不依赖 AgentScope Python 对象**：节点完成仍由 `TaskLedger` + 已校验成果物决定。

## 职责分界（已写入代码）

| 组件 | 做什么 | 不做什么 |
|---|---|---|
| AgentScope Core | 单成员 `reply_stream`、工具、TeamSay（`HINT_BLOCK`） | 不决定下一节点、不宣告 completed |
| `ConversationReplica` | 一对一镜像用户可见事件 | 不压缩为进度摘要 |
| DeerFlow 合同 / 状态机 | 合法迁移、成果物完成条件 | 不把 assistant 短消息当完成 |

## 事件映射（2.0.5）

| AgentScope | DeerFlow SSE |
|---|---|
| `REPLY_START` | `message.created`（空正文，立即出现成员气泡） |
| `TEXT_BLOCK_DELTA` | `message.delta`（同一 `reply_id` = `message_id`） |
| `THINKING_BLOCK_DELTA` | 默认丢弃；`emit_reasoning=true` 时才发公开 `reasoning_delta` |
| `HINT_BLOCK` | `team_message.created` + `completed`（TeamSay 全文） |
| `TOOL_CALL_START/DELTA/END` | `tool_call.*`，挂在同一条 ai 消息 |
| `TOOL_RESULT_START/TEXT_DELTA/END` | `tool_result.*`，`message_id=tool:{tool_call_id}` |
| `MODEL_CALL_*` | 内部遥测，默认不下发 |
| `REPLY_END` + interrupted | 补发所有未闭合 tool call 的 `tool_result.completed`，再 `message.completed` |

`node_run_id` 固定为 `${node_id}-attempt{attempt}`。并行成员共用 `phase_id`，各自 `agent_run_id`。

## 尚未覆盖（后续工单）

1. ~~`ChatModelBase` adapter 接 `AppConfig.models`（`RC-BE-007`）~~ **已完成**。
2. ~~工具 / 权限 allowlist（`RC-BE-008`）~~ **已完成**。
3. ~~TaskLedger 波次 + 受控运行器（`RC-BE-009`）~~ **已完成（脚本内核）**。真实成员内核与冒烟见 `RC-BE-017`；20 项标注评测与 20 次固定任务统计见 `RC-BE-018`。
4. 离线 wheelhouse 更新（独立发布仓库，不提交本业务仓）。

## Go 条件对照

| 条件 | 状态 |
|---|---|
| 结构化输出达到 POC 阈值 | 未测（需真实模型，`RC-BE-009`） |
| 取消在预算时间内生效 | 适配器可闭合 dangling tool；真实取消未测 |
| AgentScope 异常不会把任务误标完成 | 合同层已禁止：无 validated artifact 不能 completed |
| 业务恢复不依赖 AgentScope 对象 | 设计已冻结；`report_collaboration_*` 表与 store 已落地（`RC-BE-003`） |
| Python 3.12 + `agentscope==2.0.5` 可安装 | **通过**（本机 venv，未写入 lock） |