LangBot/docs/agent-runner-pluginization/PHASE1_QA_ACCEPTANCE_MATRIX.md

# Agent Runner 插件化 Phase 1 QA 验收矩阵

本文档用于指导测试 agent 验收 Phase 1：Agent Runner 插件化是否已经达到旧内置 runner 的对外效果。

Phase 1 的目标是让当前聊天 Pipeline 在选择插件化 AgentRunner 后，用户可感知行为与旧内置 runner 保持一致。Phase 2/EBA 不纳入本轮验收。

## 1. 验收边界

本轮必须验收：

- Pipeline 仍按现有消息入口运行。
- Runner 由插件提供，并通过 `AgentRunOrchestrator` 调用。
- `local-agent` 插件达到旧内置 local-agent 的主要行为 parity。
- 官方外部 runner 插件至少完成 smoke 验收。
- 旧 Pipeline 配置兼容，新配置可保存并生效。
- 权限裁剪、错误隔离、运行状态更新不破坏主流程。

本轮不验收：

- EBA EventBus。
- EBA EventRouter。
- 消息撤回、群成员加入、好友申请等非消息事件的真实接入。
- `action.requested` 平台动作执行。
- 新平台 API 权限模型。

上述非目标只允许检查协议预留是否存在，不允许作为 Phase 1 阻塞项。

## 2. 状态定义

测试 agent 只能使用以下状态：

| 状态 | 含义 |
| --- | --- |
| PASS | 按本矩阵步骤执行，所有通过条件满足，并记录证据。 |
| FAIL | 环境可用，但功能行为不满足通过条件。 |
| BLOCKED | 因缺少密钥、外部服务不可用、账号/OAuth 未完成、测试数据缺失等环境问题无法执行。必须写清阻塞原因。 |
| N/A | 当前插件或平台明确不支持该能力。必须引用 manifest capability、文档或配置说明。 |

不能使用“看起来正常”“大概通过”“未完全测试”等模糊状态。

## 3. 总体验收条件

Phase 1 可以关闭的最低条件：

- 所有 P0 case 必须 PASS。
- `local-agent` 的 P1 parity case 必须 PASS，除非该能力旧内置 runner 也不支持，此时可标 N/A。
- 官方外部 runner smoke case 至少对已具备凭据和服务的插件 PASS；缺凭据的插件可标 BLOCKED，但必须保留配置页面截图或日志说明。
- 没有会导致主聊天路径不可用、插件 runtime 崩溃、Pipeline 配置丢失、权限绕过的未解决 FAIL。
- 所有 FAIL/BLOCKED 都必须记录复现步骤、日志位置、截图或请求/响应摘要。

推荐测试前先运行：

```bash
uv run --frozen pytest tests/unit_tests/agent
```

Host 侧 agent runner 单测不通过时，不应进入 UI parity QA。

## 4. 证据要求

每个 case 至少记录：

- LangBot commit、SDK commit、相关 runner 插件 commit。
- Pipeline UUID/name、runner id、runner config 摘要。
- WebUI 截图或浏览器操作记录。
- 后端日志中对应 query id/run id 的关键行。
- 对外部 runner，记录外部服务响应摘要或错误码。

用户可见流程必须通过 WebUI 或真实消息平台验证。API/curl 只能作为诊断证据，不能单独让 UI case PASS。

## 5. P0 环境与主链路

| ID | 场景 | 步骤 | 通过条件 |
| --- | --- | --- | --- |
| P0-ENV-01 | LangBot 服务可用 | 启动后端和前端，打开 WebUI。 | WebUI 可登录/访问；后端无启动异常；插件系统按配置启用。 |
| P0-ENV-02 | 插件 runtime 可用 | 查看插件列表或后端日志。 | runtime 已启动；官方 runner 插件处于可用状态；无循环重启。 |
| P0-ENV-03 | Runner registry 可发现插件 runner | 打开 Pipeline AI runner 配置。 | runner 下拉列表来自插件 registry；至少能看到 `plugin:langbot/local-agent/default`。 |
| P0-ENV-04 | 默认 Pipeline 可创建 | 新建 Pipeline 或读取默认 Pipeline。 | 默认配置使用 `ai.runner.id` 与 `ai.runner_config`；默认 runner 可保存。 |
| P0-ENV-05 | 主聊天路径调用插件 runner | 使用默认 `local-agent` Pipeline 发送一条普通消息。 | 后端日志显示走 `AgentRunOrchestrator` / `RUN_AGENT`；用户收到正常回复；旧内置 runner 不应作为主路径执行。 |
| P0-ENV-06 | 单测基线 | 运行 `uv run --frozen pytest tests/unit_tests/agent`。 | 全部通过；若失败，必须先修复或记录为 P0 FAIL。 |

## 6. P1 local-agent parity

`local-agent` 是 Phase 1 的主验收对象。以下 case 需要和旧内置 local-agent 的用户可见行为对齐。

| ID | 场景 | 步骤 | 通过条件 |
| --- | --- | --- | --- |
| P1-LA-01 | 普通文本对话 | 绑定 `plugin:langbot/local-agent/default`，发送普通文本。 | 回复正常生成；conversation history 写入用户消息和助手消息。 |
| P1-LA-02 | 有效 prompt | 配置 system prompt，并通过 PromptPreProcessing 插件或现有预处理改变 prompt。 | runner 使用 host 处理后的 `ctx.prompt`，不是只读取静态 `ctx.config.prompt`；回复体现有效 prompt。 |
| P1-LA-03 | 历史消息 | 连续多轮对话，第二轮引用第一轮内容。 | runner 可读到历史 `ctx.messages`；第二轮能基于上下文回答。 |
| P1-LA-04 | 流式输出 | 使用支持流式的 adapter/WebUI，开启流式模型或流式 runner。 | UI 逐步更新；后端接收 `message.delta`；最终没有重复消息或空白卡片。 |
| P1-LA-05 | 非流式输出 | 使用不支持流式或关闭流式的路径。 | 只输出最终消息；不会创建异常流式卡片。 |
| P1-LA-06 | 工具调用 | 绑定一个可调用工具，提问触发工具。 | `ctx.resources.tools` 只包含授权工具；runner 能获取工具详情并调用；最终回复包含工具结果。 |
| P1-LA-07 | 工具权限裁剪 | 不绑定某工具，但让 runner 尝试调用。 | 调用被拒绝；错误不泄露未授权工具详情；Pipeline 不崩溃。 |
| P1-LA-08 | RAG 检索 | 绑定知识库并提问命中文档。 | `ctx.resources.knowledge_bases` 包含所选知识库；runner 可检索；回复引用或使用检索内容。 |
| P1-LA-09 | RAG 权限裁剪 | 不绑定知识库或绑定另一个知识库。 | 未授权知识库不可检索；错误可控。 |
| P1-LA-10 | rerank | 绑定 rerank 模型并启用知识库检索排序。 | runner 可通过授权 rerank 模型排序；无权限时不允许调用。 |
| P1-LA-11 | fallback model | 配置 primary 和 fallback，模拟 primary 失败。 | fallback 被调用；用户得到可用回复或明确失败提示；日志能区分 primary/fallback。 |
| P1-LA-12 | remove-think | 开启输出 `remove-think`，使用会产生 think 内容的模型。 | 用户最终回复不包含被移除的 think 内容；插件 runner 走 runtime metadata 或 API 参数保持旧行为。 |
| P1-LA-13 | 多模态图片 | 发送图片输入。 | `ctx.input.contents` / `ctx.input.attachments` 保留图片；支持视觉模型时可正常处理；不支持时错误提示可控。 |
| P1-LA-14 | 文件输入 | 发送文件或文件 URL。 | runner 可看到文件 attachment 摘要；支持文件处理时正常处理；不支持时不崩溃。 |
| P1-LA-15 | 会话状态 | runner 返回 `state.updated`，下一轮继续对话。 | state 被 host 接收并作用于下一轮；conversation id 等兼容旧行为。 |
| P1-LA-16 | 异常处理 | 让 runner 返回 `run.failed` 或抛异常。 | ChatMessageHandler 使用 Pipeline 的异常策略；用户提示符合配置；runtime 和后续请求不受影响。 |
| P1-LA-17 | 无输出保护 | runner 完成但不返回消息。 | 不产生空白成功回复；应按受控失败处理或明确记录缺陷。 |

## 7. P1 配置兼容与迁移

| ID | 场景 | 步骤 | 通过条件 |
| --- | --- | --- | --- |
| P1-CFG-01 | 读取旧配置 | 使用只包含 `ai.runner.runner = local-agent` 和旧 `ai.local-agent` 配置的 Pipeline。 | 能解析为 `plugin:langbot/local-agent/default`；旧配置值生效。 |
| P1-CFG-02 | 保存新配置 | 在 WebUI 修改 runner 和 runner config 后保存。 | 数据库存储 `ai.runner.id` 和 `ai.runner_config[id]`；刷新页面后不丢失。 |
| P1-CFG-03 | runner 切换 | 同一 Pipeline 从 local-agent 切到另一个官方 runner，再切回。 | 每个 runner 的绑定配置独立保存；切换不污染其它 runner config。 |
| P1-CFG-04 | 插件缺失 | 配置引用一个未安装或未启动的 runner。 | WebUI/后端给出可理解错误；Pipeline 不因 metadata 加载失败整体不可用。 |
| P1-CFG-05 | bound plugin 授权 | Pipeline 只绑定部分插件。 | 未绑定插件的 runner 不能执行；已绑定插件正常执行。 |

## 8. P1 权限与隔离

| ID | 场景 | 步骤 | 通过条件 |
| --- | --- | --- | --- |
| P1-AUTH-01 | 模型权限 | runner 尝试调用不在 `ctx.resources.models` 的模型。 | Host action 拒绝；错误包含 run/session 维度信息；不会调用实际模型。 |
| P1-AUTH-02 | 工具权限 | runner 尝试调用不在 `ctx.resources.tools` 的工具。 | Host action 拒绝；不会越权执行工具。 |
| P1-AUTH-03 | 知识库权限 | runner 尝试检索不在 `ctx.resources.knowledge_bases` 的知识库。 | Host action 拒绝；不会返回未授权知识库内容。 |
| P1-AUTH-04 | 存储权限 | manifest 未声明 storage 权限时访问 plugin/workspace storage。 | 访问被拒绝；普通插件非 AgentRunner 的兼容路径不受影响。 |
| P1-AUTH-05 | run_id 生命周期 | runner 结束后继续使用旧 run_id 调 host action。 | session 已注销；请求被拒绝。 |
| P1-AUTH-06 | 插件身份隔离 | A 插件 runner 的 run_id 被 B 插件使用。 | Host 拒绝 identity mismatch。 |

## 9. P2 官方外部 runner smoke

以下 case 是 smoke，不要求和 local-agent 一样覆盖全部能力。若缺少外部服务凭据，状态标 BLOCKED，并记录缺失项。

| ID | Runner | 步骤 | 通过条件 |
| --- | --- | --- | --- |
| P2-EXT-01 | `dify-agent` | 配置 chat/agent/workflow 中至少一种可用应用并发送消息。 | runner 可选、配置可保存、请求成功或外部服务错误被清晰返回。 |
| P2-EXT-02 | `n8n-agent` | 配置 webhook 和认证方式并发送消息。 | webhook 被调用；返回内容进入 LangBot 回复；认证失败时提示明确。 |
| P2-EXT-03 | `coze-agent` | 配置 Coze 应用并发送文本，若可用再测图片。 | 文本回复正常；多模态能力按 manifest/配置表现；思维链处理不污染最终回复。 |
| P2-EXT-04 | `dashscope-agent` | 配置 agent 或 workflow 并发送消息。 | 调用成功；失败时错误可控且不影响后续请求。 |
| P2-EXT-05 | `langflow-agent` | 配置 flow endpoint 并发送消息。 | 普通或 SSE 流式响应能归一为 LangBot 消息。 |
| P2-EXT-06 | `tbox-agent` | 配置 Tbox 应用并发送消息。 | 回复正常；多模态输入按插件能力处理。 |

## 10. P2 事件预留检查

这些只检查协议预留，不要求真实平台事件接入。

| ID | 场景 | 步骤 | 通过条件 |
| --- | --- | --- | --- |
| P2-EVT-01 | 消息事件名稳定 | 触发普通消息 runner。 | `ctx.trigger.type` 和 `ctx.event.event_type` 为 `message.received`；平台原始类型保存在 `ctx.event.event_data.source_event_type`。 |
| P2-EVT-02 | 非消息事件名预留 | 检查 host 侧保留事件名。 | `message.recalled`、`group.member_joined`、`friend.request_received` 作为稳定协议名存在。 |
| P2-EVT-03 | action.requested 预留 | 让测试 runner 返回 `action.requested`。 | Host 只记录日志，不执行平台动作，不影响主流程。 |

## 11. 退出标准

QA agent 完成后应输出一份报告，至少包含：

- 总状态：PASS / FAIL / BLOCKED。
- 每个 case 的状态表。
- 所有 FAIL 的复现步骤和建议归属仓库。
- 所有 BLOCKED 的环境缺口。
- 是否建议关闭 Phase 1，进入 Phase 2/EBA。

建议关闭 Phase 1 的条件：

- P0 全 PASS。
- P1 全 PASS，或只有旧内置 runner 同样不支持的 N/A。
- P2 外部 runner smoke 对可用凭据全部 PASS。
- 剩余问题均为 EBA 预留、外部服务凭据、或非阻塞体验问题。