# 数据分析运行时 + 子代理 · 测试用例文档 > 版本:2026-11-06 v1 > 被测对象:`docs/design/analysis-runtime-enhancement.md` 落地实现(分析工作区/产物、子代理档案与创建、后台任务、长报告落盘、SSE 隔离、前端执行流水、上传提取心跳) > 测试环境:本机 dev,PG/Redis/ES @`192.168.0.106`,后端 `http://127.0.0.1:8980/js/a`,前端 `http://localhost:3100`,DuckDB 案件库 > 测试账号:`admin / admin123`(开发环境默认) > 测试案件:新建「分析运行时测试-20261106」(owner=admin;至少 1 张可查表) > **测试口径:以当前代码为准。** 设计文档 §4.1(DB 绑定)、§4.3(会话并发 4)、§12(子代理默认关闭)为历史方案,现实现已不同;凡与 §1 偏差表冲突的断言,一律不判失败。 --- ## 1. 实现现状与设计文档偏差(先看这一节) | # | 设计文档描述 | 当前实现(测试以此为准) | |---|---|---| | D1 | §4.1 `agent_subagent_binding` / `agent.agent_role` / `delegate_description` | **未落地**;没有绑定表/字段,也没有绑定 CRUD 接口 | | D2 | §4.1 框架自动注册 `general-purpose`,继承父工具/技能/知识库 | **不使用**框架自动 GP。子代理档案 = `classpath:subagents/*.md`(`general-purpose` / `explore` / `python-worker`)+ 工作区 `cases/{caseId}/ai/agents/{agentRowId}/{userId}/subagents/*.md` 同名覆盖 | | D3 | §4.2 `SubagentDeclaration` + `subagentFactory` 装配 | 自定义 `SubagentSpawnTool` + 空条目 `DefaultAgentManager` + `SubagentDeliveryMiddleware`;每次 spawn 新建一次性 child,结束关闭 | | D4 | §4.3 同一会话最多 4 个子代理、绑定级上限 | **未实现并发闸门**;并发由模型调用节奏决定。用例不测「第 5 个排队」 | | D5 | §4.3 不开放 `agent_send` | 确认未注册;只暴露 `agent_spawn` + `task_output/task_cancel/task_list` | | D6 | §4.4/§5 任务注册表在内存、tool_events 轻量投影 | 已实现;投影 `alias/status/durationMs/summary`,alias 取入参 `subagent_type`,summary 跳过 Markdown 标题 | | D7 | §6.4 后台任务卡片在输入框上方轮询 | 后台任务行已并入该消息的 `ProcessTimeline`(1s 轮询;终态保留在流水里);**输入框上方没有浮条**,建议词后也没有卡片 | | D8 | §8.2 产物即时登记 | 已实现,但受 `analysis.artifact.immediate` 控制(默认 **false**);登记幂等去重,元数据含 `path / sourceTool / createdByUserId / sha256` | | D9 | §10 开关 | `subagent.enabled` 默认 **true**;`max-parallel-*` / `background.enabled` / `max-depth` 未实装;新增 `subagent.max-inline-result-chars`(12000)、`dm.upload.heartbeat-seconds`(5) | | D10 | §14 前端文件 `SubagentRunsPanel.vue` / `SubagentTaskBar.vue` | 两个文件已删除;子代理/后台任务行实际渲染在 `ProcessTimeline.vue`,状态在 `chatStream.ts` | | D11 | 设计文档未覆盖 | 上传提取心跳日志(`ExtractionHeartbeat`):开始 / 每 N 秒 / 结束,见 §4.9 | --- ## 2. 环境与前置 ### 2.1 依赖服务 | 项 | 值/要求 | |---|---| | PostgreSQL | `192.168.0.106:5432/zsjz-ai`,需 pgvector(平台表/会话/模型/RAG) | | Redis | `192.168.0.106:6379`(sa-token 登录、Agent 状态) | | Elasticsearch | `192.168.0.106:9200`(全文检索;本测试不依赖) | | Python | 项目内置解释器 `qingjian/system/python/python.exe`,需 pandas/duckdb/matplotlib/openpyxl/python-docx | | 模型 | 「模型管理」里至少一个可用对话模型(本测试用默认 DeepSeek) | ### 2.2 启动 ```bash # 后端(仓库根目录) mvn -pl ai-server -am clean compile mvn -pl ai-server spring-boot:run # 前端 cd ai-electron/frontend pnpm dev # http://localhost:3100 ``` ### 2.3 测试案件与数据 1. 新建案件「分析运行时测试-20261106」,并**打开案件**(重启后端后必须重新打开,否则案件 DuckDB 数据源是关闭状态)。 2. 案件内至少导入 1 个 CSV(如 `docs/ai-clean-e2e/fixtures/01*.xlsx`),确保 `list_tables` 有返回。 3. 进入「智能工作台」,用「通用专家」新建对话。 ### 2.4 开关基线 | 配置 | 基线值 | 用途 | |---|---|---| | `subagent.enabled` | `true`(默认) | 子代理用例 | | `analysis.workspace.enabled` | 测试时设 `true` | 持久工作区用例;默认 false 时走旧沙箱 | | `analysis.artifact.immediate` | 测试时设 `true` | 即时登记用例;默认 false 时由回合末扫描兜底 | | `subagent.max-inline-result-chars` | 测试时设 `800`,其余时间 `12000` | 长报告落盘用例 | | `dm.upload.heartbeat-seconds` | `1`(仅心跳用例) | 上传心跳用例;默认 5 | | `analysis.prompt.policy.enabled` | `true` | 提示词 | | `analysis.prompt.artifact-contract.enabled` | `true` | 提示词 | | `analysis.prompt.document-contract` | `false` | 提示词(未注册 office 工具) | 启动方式示例(环境变量覆盖): ```bash SUBAGENT_MAX_INLINE_RESULT_CHARS=800 \ ANALYSIS_WORKSPACE_ENABLED=true \ ANALYSIS_ARTIFACT_IMMEDIATE=true \ mvn -pl ai-server spring-boot:run ``` > 用例执行完请把环境变量恢复默认(尤其 `SUBAGENT_MAX_INLINE_RESULT_CHARS`),避免后续对话所有报告都被落盘。 --- ## 3. 测试分层 | 层 | 说明 | 执行方式 | 覆盖 | |---|---|---|---| | A | 确定性单测 | JUnit | 档案解析、工具白名单、投影、任务仓库、提示词、心跳日志 | | B | 后端 API | curl / 页面请求 | `/chat/tasks`、取消、停止会话、artifact 下载 | | C | 手工 UI | 浏览器 + 智能工作台 | 子代理行/后台任务行、SSE 隔离、刷新恢复 | | D | 回归 | Maven + `pnpm type:check` | 67 业务工具 + 7 基础工具、前端类型 | 结果标记:`PASS` / `FAIL` / `待执行`。所有用例默认「待执行」,执行后回填 §8。 --- ## 4. 测试用例 ### 4.1 AR · 分析运行时(工作区 / 产物) 前置:`analysis.workspace.enabled=true`,`analysis.artifact.immediate=true`。 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | AR-01 | 工作区目录创建 | 发一条会调用 `execute_python` 的消息(如「用 Python 打印 1+1」) | 生成 `cases/{caseId}/ai/analysis/{userId}/{sessionId}/` 下的 `work`、`outputs`、`runs` 三个目录;`runs/{execId}/` 下有 `main.py`、`meta.json` | 手工 | | AR-02 | `work` 跨调用复用 | 第一次执行 `open('a.txt','w').write('hi')`;第二次执行 `print(open('a.txt').read())` | 第二次 stdout 为 `hi`;`work/a.txt` 仍在 | 手工 | | AR-03 | `outputs` 即时登记 | 执行 `import pandas as pd; pd.DataFrame({'a':[1,2]}).to_csv('outputs/t.csv', index=False)` | 工具结果 JSON 含 `artifacts[]`,其中有 `fileName=t.csv`;`cases/{caseId}/ai/artifacts/` 出现 `agent_file_*.csv`;`path` 为 `cases/.../outputs/t.csv` | 手工(`registerFile` 无单测) | | AR-04 | 登记幂等去重 | 同一文件不改内容,连续执行两次生成同名 outputs 文件 | 两次返回相同 artifact `id`(或第二次不新增产物);产物栏不出现重复条目 | 手工(无 JUnit) | | AR-05 | 回合末扫描兜底 | 设 `analysis.artifact.immediate=false`,执行 AR-03 | 执行结果不含 `artifacts[]`;消息结束后产物栏仍出现该文件(`AgentArtifactScanner` 兜底) | 手工(ScannerTest 不覆盖 analysis outputs) | | AR-06 | 中间文件不登记 | 上述执行中在 `work/` 放一个 `.csv`,`outputs/` 不放 | 产物栏不出现 `work/` 文件 | `AgentArtifactScannerTest`(扫描器主体;analysis outputs 未覆盖) | | AR-07 | 运行记录 | 任一次 `execute_python` 后查看 `runs/{execId}/meta.json` | 含 `execId/caseId/userId/sessionId/exitCode/durationMs/stdoutChars/stderrChars/artifactIds/code/finishedAt` | 手工 | | AR-08 | stdout 截断落盘 | 执行 `for i in range(20000): print(i)` | stdout 保留头尾并带截断说明;`stdoutFullOutputPath` 指向 `runs/{execId}/stdout.log`(或旧模式 py-out 日志) | `PythonExecutorTest` | | AR-09 | artifact 元数据回读 | AR-03 后检查工具结果;用 `artifact.id` 调预览/下载;尝试用 `artifact.path` 读文件 | 元数据含 `path`(相对数据根)与 `id`;`id` 预览/下载可访问;`path` 是相对数据根路径(当前没有工具把数据根注入模型,模型直接按相对路径读会失败,见 §7) | 手工 | | AR-10 | 产物预览/下载 | 在产物栏点 CSV 预览/下载 | 预览返回表头+前 N 行;下载得到完整文件;跨案件 id 返回 404 | `ArtifactServiceTest` | | AR-11 | 永久保留 | 检查 `artifact.retain-days` 默认 0,重启后端后再次预览 | 文件仍可预览/下载,不被清理 | 手工 | | AR-12 | 工作区关闭回退 | `analysis.workspace.enabled=false` 重启,再执行 AR-01 | 使用 `cases/{caseId}/ai/python/sandbox/{execId}`;执行后 sandbox 被删除;产物仍进 py-out/产物栏 | 手工(无工作区分支单测) | ### 4.2 SA · 子代理档案与创建 前置:`subagent.enabled=true`;模型可用。 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | SA-01 | 内置档案加载 | 查看前端「子代理委派」稳定段/直接调用 `agent_spawn` | 可用 `subagent_type`:`general-purpose`、`explore`、`python-worker`;目录里带各自工具列表 | `SubagentProfileLoaderTest` | | SA-02 | 工作区覆盖 | 在 `cases/{caseId}/ai/agents/{agentRowId}/{userId}/subagents/` 放 `my-worker.md`(同名可覆盖内置) | 重新构建 agent(重启/驱逐池)后目录出现 `my-worker`;同名时工作区版本生效 | `SubagentProfileLoaderTest`(解析部分) | | SA-03 | `model` 字段被忽略 | 档案 frontmatter 写 `model: openai:gpt-4o` | 日志告警「不支持 model,已忽略」;子代理仍用父会话模型 | `SubagentProfileLoaderTest` | | SA-04 | `tools` 只能基础白名单 | 档案写 `tools: [list_tables, get_call_records]` | `get_call_records` 被丢弃;子代理只有 `list_tables` | `SubagentProfileLoaderTest` | | SA-05 | 档案 tools 全非法 | 档案写 `tools: [get_case_graph]` | 该档案被跳过(日志警告),不注册;不会静默放开全部工具 | `SubagentProfileLoaderTest` | | SA-06 | 创建时收窄工具 | `agent_spawn(subagent_type=python-worker, tools=[execute_python])` | 子代理只有 `execute_python`(无 list_tables/render_chart);工具结果/日志可验证 | 手工 + `SubagentPropertiesTest`(白名单) | | SA-07 | 工具越界报错 | `agent_spawn(subagent_type=explore, tools=[execute_python])` | 工具返回错误「tools 与档案「explore」不匹配;该档案可用工具:…」;不创建子代理 | 手工 | | SA-08 | 未知档案报错 | `agent_spawn(subagent_type=not-exist)` | 返回「未知 subagent_type: not-exist;可用:…」 | 手工 | | SA-09 | `task` 必填 | `agent_spawn(subagent_type=explore)`,不传 task | 返回「task 不能为空:子代理不继承当前对话,必须提供完整任务简报」 | 手工 | | SA-10 | 同步成功 | `agent_spawn(subagent_type=python-worker, task=«计算 1..100 求和»)` | 工具结果 `status: ok` + `duration_ms` + `reply:` 报告;父正文转述 5050 | 手工 + `AgentSpawnProjectionTest` | | SA-11 | 一次性运行实例(不继承对话) | 第一次 spawn 让子代理「记住口令 A 并回复已记住」;第二次 spawn 同 alias 问「上一轮的口令是什么」 | 第二次不知道 A(每次新 child,不继承对话/会话);注意 `work/` 文件按「父会话 + alias」目录保留,跨 spawn 可见,这是工作区设计,不判失败 | 手工 | | SA-12 | 不继承父能力 | 父专家绑定了知识库/技能,`agent_spawn(subagent_type=explore)` 后让子代理「检索知识库」 | 子代理没有 `search_knowledge`、没有业务工具、没有父专家技能;只能基础工具 | 手工 | | SA-13 | 不嵌套 | 在子代理任务里要求它「再 spawn 一个子代理」 | 子代理没有 `agent_spawn` 工具,无法嵌套 | 手工 | | SA-14 | ISOLATED 工作区 | SA-10 后检查磁盘 | 子代理目录 `cases/{caseId}/ai/analysis/{userId}/{父sessionId}/subagents/{alias}` 存在;不同 alias 目录不同 | 手工 | | SA-15 | 无 `agent_send` | 查看工具清单/尝试让模型发 `agent_send` | 工具列表无 `agent_send`;模型无法续聊子代理 | 手工 | ### 4.3 BG · 后台任务 前置:`subagent.enabled=true`。 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | BG-01 | 后台受理 | `agent_spawn(subagent_type=explore, timeout_seconds=0, task=«列出案件表名»)` | 工具结果 `status: accepted` + `task_id: task_...`;父回复立即结束,不等待 | `AgentSpawnProjectionTest`(accepted/task_id) | | BG-02 | 任务行进流水 | 观察消息执行流水 | 出现 `后台子代理 explore 运行中`,带已运行时长/取消按钮;汇总行含「1 个后台任务」;输入框上方无 `.ai-tasks` 浮条 | 手工 | | BG-03 | 轮询到完成 | 任务结束后观察 1s 内 | 同一行变为 `已完成`(或失败/已取消),耗时固定;不再显示为运行中 | 手工(`/chat/tasks`) | | BG-04 | 取消任务 | 运行中点「取消」 | `POST /chat/tasks/{id}/cancel?sessionId=` 返回 200;行变 `已取消`;后台不再执行 | `InMemorySubagentTaskRepositoryTest`(取消) | | BG-05 | 停止会话 | 运行中调用 `POST /chat/sessions/{id}/stop` | 当前父流被取消;`GET /chat/tasks` 不再返回该任务。注意:注册表清空后前端消息行可能停留在最后一次状态(见 §7),刷新后消失 | 手工 + 仓库 `cancelSession` 测试 | | BG-06 | 超时转后台 | 设 `timeout_seconds=1`,任务执行 `sleep 8` | 工具结果 `status: timeout_promoted` + `task_id`;任务继续后台执行;后续轮询到完成 | 手工 + `AgentSpawnProjectionTest` | | BG-07 | 下一轮交付 | 任务完成后,用户下一轮问「刚才的后台任务完成了吗?」 | 父 Agent 收到一次 `` 交付;转述结果;不插入 `task_result` 消息 | `InMemorySubagentTaskRepositoryTest`(findPendingDeliveries/markDelivered) | | BG-08 | 交付后释放 | 同上;再问一次 | 不重复交付(`markDelivered` 幂等;结果文本已释放) | 同上 | | BG-09 | 重启丢任务 | 后台任务运行中重启后端 | 内存任务/卡片消失;父历史消息仍在;用户重新发起(预期行为,不判失败) | 手工 | ### 4.4 LR · 长报告落盘 前置:`subagent.max-inline-result-chars=800`(重启后端)。 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | LR-01 | 未超限原样 | 子代理报告 <800 字符 | 工具结果 `reply:` 是原文,无 `` | `SubagentReportWriterTest` | | LR-02 | 超限落盘 | 子代理报告 >800 字符 | 工具结果含 ``、字符数/文件大小、`Full report saved to: `、头部预览;文件在 `runs/subagent-*.md`,内容与报告一致 | `SubagentReportWriterTest` | | LR-03 | 后台任务同样落盘 | `timeout_seconds=0` 且报告超限 | 任务完成交付的文本也是信封 + 路径;`task_output` 返回信封 | 手工 | | LR-04 | 关闭落盘 | `subagent.max-inline-result-chars=0` | 报告原样返回(可能很长);不写 `runs/subagent-*.md` | `SubagentReportWriterTest` | ### 4.5 SSE / 前端 前置:同步子代理与后台子代理各跑一次。 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | SSE-01 | 子代理事件不拼父正文 | 同步子代理运行中观察正文 | 父正文不出现子代理 token/思考;子代理内容只在执行流水行 | 手工(需对照 DB) | | SSE-02 | 子代理结果不落父消息 | 检查 `agent_message` 最新 assistant 行 | 只有父 Agent 总结;`content` 不含子代理完整报告 | 手工 SQL | | SSE-03 | intent/suggestions 隔离 | 子代理运行中观察 | 父消息的 intent/suggestions 不混入子代理的;子代理的 intent/suggestions 被丢弃 | 手工 | | SSE-04 | `agent_spawn` 投影 | 查看工具卡片 | 结果字段只有 `type=subagent, alias, status, durationMs, summary`;无完整报告 | `AgentSpawnProjectionTest` | | SSE-05 | summary 可读 | 同步成功/后台受理/落盘三种结果 | summary 不为「## 结论」;落盘时为「报告较长,已落盘」;后台为「已转入后台运行」 | `AgentSpawnProjectionTest` | | SSE-06 | 子代理行实时 | 同步子代理运行中 | 执行流水出现 `子代理 alias 调用 <耗时>`;完成后变 `已完成 <耗时>`,主 Agent 仍在输出时即可看到 | 手工 | | SSE-07 | 后台任务行位置 | 后台任务运行中 | 行在消息执行流水内;**不在「下一步分析方向」之后**;输入框上方无浮条 | 手工 | | SSE-08 | 刷新只恢复父消息 | 完成后刷新页面/重进会话 | 子代理行、后台任务行消失;只保留父消息与工具卡片投影 | 手工 | | SSE-09 | 停止生成 | 同步子代理运行中点「停止」 | 父流取消;子代理随父流取消(`inner.dispose`);落半截父消息/不落子代理消息 | 手工 | ### 4.6 ISO · 多用户隔离 前置:准备用户 A/B(或同一案件下不同登录态不可行时,用案件 A/B 验证案件级隔离);设计 §3.7 七条。 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | ISO-01 | A 不能查/取消 B 的任务 | A 登录调用 `GET /chat/tasks?sessionId=B会话`、`POST /chat/tasks/{B task}/cancel` | 查询返回空列表(不泄露);取消返回 404/403 | `SubagentTaskRegistryTest`(用户/案件/session 隔离) | | ISO-02 | A 不能按 artifact id 访问 B 的产物 | 用 B 的 artifact id 调 `/agent/artifact/preview` 或 `/agent/artifact/download` | 404(当前案件根解析不到) | `ArtifactServiceTest`(跨案件 404) | | ISO-03 | A 不能使用 B 的私有档案/技能 | A 的目录里看不到 B 的 `subagents/*.md`;A 的专家技能列表不含 B 的技能 | 工作区按 `{userId}` 分目录;技能仓库按 userId | 手工 | | ISO-04 | A 的子代理 Python 产物只进 A 的产物栏 | A 跑子代理生成 outputs;B 查看自己的产物栏 | B 看不到 A 的文件;A 的路径在 `analysis/{A userId}/...` | 手工 | | ISO-05 | 同案件不同用户/同 sessionId 不同用户/同 taskId 不同用户不能串 | 构造同 sessionId 查询 | 注册表 key = `userId + caseId + sessionId`;不同用户查不到 | `SubagentTaskRegistryTest` | | ISO-06 | 后台通知不注入别人会话 | A 的后台任务完成后,B 下一轮对话 | B 不收 A 的交付;A 下次对话才收 | `InMemorySubagentTaskRepositoryTest`(按会话)+ 手工 | | ISO-07 | 子代理 workspace 不落到父用户之外 | 检查磁盘 | 子代理目录在 `analysis/{父 userId}/{父 sessionId}/subagents/{alias}` | 手工 | ### 4.7 PR · 提示词 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | PR-01 | 稳定段顺序 | 单测/查看 system prompt | `expert → policy → tool-rules → output-contract → artifact-contract → rag → knowledge → delegation-policy → document-contract` | `PromptAssemblyTest` | | PR-02 | 无动态信息 | 同上 | 稳定段不含「当前案件/当前日期/已装备工具组」 | `PromptAssemblyTest` | | PR-03 | 委派目录 | `subagent.enabled=true` 且档案存在 | `delegation-policy` 含每个档案的 alias、描述、工具列表 | `PromptAssemblyTest` | | PR-04 | 关闭无委派 | `subagent.enabled=false` | 无 `delegation-policy`;无 `agent_spawn/task_*` 工具 | `PromptAssemblyTest` + 手工 | | PR-05 | 产物契约 | 默认配置 | 含 artifact-contract 文本(正文只给结论/文件名;长输出落盘;结果转述) | `PromptAssemblyTest` | ### 4.8 CFG · 开关与回归 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | CFG-01 | 子代理关闭 | `subagent.enabled=false` 重启 | 工具列表无 `agent_spawn` / `task_*`;无委派提示;对话与改造前一致 | 手工 | | CFG-02 | 工作区关闭 | `analysis.workspace.enabled=false` | `execute_python` 回退临时沙箱;无 `analysis/` 目录 | 手工(无工作区分支单测) | | CFG-03 | 即时登记关闭 | `analysis.artifact.immediate=false` | 工具结果无 `artifacts[]`;回合末扫描仍登记 outputs | 手工 | | CFG-04 | 业务工具回归 | 运行 agent 工具测试 | 67 业务工具 + 7 基础工具注册/描述/入参契约通过 | `AgentToolRegistryTest`、`ToolDescriptionContractTest`、`ToolSpecRequiredFieldContractTest` | | CFG-05 | 前端类型 | `cd ai-electron/frontend && pnpm type:check` | 无本次新增错误 | 命令 | ### 4.9 UP · 上传提取心跳(附:非本设计文档范围) 前置:`dm.upload.heartbeat-seconds=1`(或上传一个提取 >5s 的大文件,默认 5s)。 | 编号 | 场景 | 步骤 | 预期结果 | 自动化 | |---|---|---|---|---| | UP-01 | 开始/结束日志 | 上传任意表格文件 | 日志出现 `[upload] 开始提取: name=..., batchId=...` 与 `[upload] 提取结束: ..., costMs=...` | `ExtractionHeartbeatTest` | | UP-02 | 慢提取心跳 | 提取超过心跳间隔 | 每 N 秒出现 `[upload-heartbeat] 提取进行中: name=..., elapsed=...s(请求连接正常)` | `ExtractionHeartbeatTest` | | UP-03 | 间隔可配 | 设 `dm.upload.heartbeat-seconds=1` 后重复 UP-02 | 心跳频率变为 1s;恢复默认 5s 后频率恢复 | 手工 | --- ## 5. 自动化执行清单 ### 5.1 命令 ```bash # 后端:agent 全量 + 上传心跳 mvn -o -pl ai-server test \ -Dtest='com.zsjz.ai.module.agent.**,com.zsjz.ai.module.dm.service.ExtractionHeartbeatTest' # 前端类型检查 cd ai-electron/frontend pnpm type:check ``` 预期:agent 测试 **373 个通过**(13 个 skipped 为 live/manual 测试);`ExtractionHeartbeatTest` 1 个通过;命令合计 **374** 个;typecheck 无本次新增错误。 > 全量 `mvn test` 存在与本次无关的既有失败(如 `dm.pre.PreDataListenerMatchTest#lowCoverageVariantFallsThroughToAi` 及部分 eds 顺序相关用例),不要用它们判定本次失败;以 agent 子集为准。 ### 5.2 用例 → 测试类映射 | 用例组 | 测试类 | |---|---| | SA-01~05 | `SubagentProfileLoaderTest`(6) | | SA-04/06 + CFG-01 | `SubagentPropertiesTest`(4,白名单部分)、`SubagentSpawnToolSchemaTest`(1,参数 schema) | | SA-10 / BG-01 / BG-06 / SSE-04/05 | `AgentSpawnProjectionTest`(7,投影部分;spawn 实际调用手工) | | BG-04/07/08 / ISO-06 | `InMemorySubagentTaskRepositoryTest`(4) | | ISO-01/05 | `SubagentTaskRegistryTest`(5) | | LR-01/02/04 | `SubagentReportWriterTest`(3) | | PR-01~05 | `PromptAssemblyTest`(10) | | AR-08 | `PythonExecutorTest`(8,覆盖 stdout 截断/图产物;不含工作区分支) | | AR-10 | `ArtifactServiceTest`(10,覆盖 resolve/preview) | | AR-03/04 | 手工(`ArtifactService.registerFile` 无单测) | | AR-06 | `AgentArtifactScannerTest`(2,扫描器主体;不含 analysis outputs) | | AR-05 | 手工(analysis outputs 兜底扫描无单测) | | CFG-04 | `AgentToolRegistryTest`、`ToolDescriptionContractTest`、`ToolSpecRequiredFieldContractTest` | | UP-01/02 | `ExtractionHeartbeatTest`(1;UP-03 配置频率手工) | --- ## 6. 手工 UI 脚本(可直接复制提示词) ### 6.1 同步子代理 提示词: ```text 请用子代理完成这个计算:调用 agent_spawn,subagent_type 选择 python-worker, 任务是用 execute_python 计算 1 到 100 的和并打印结果。 任务简报要写清:案件「分析运行时测试-20261106」、目标 计算 1..100 求和、 期望输出 求和结果与计算方式。拿到子代理报告后,把结果转述给我。 ``` 预期: - 执行流水出现 `子代理 python-worker 调用 execute_python <耗时>` → `已完成 <耗时>`; - 汇总行 `已完成 · 1 个子代理 · 1 步工具调用 · Ns`; - 工具卡 `agent_spawn python-worker` 结果只有 `type/alias/status/durationMs/summary`; - 父正文给出 5050,且不出现子代理原始报告全文; - 输入框上方没有 `.ai-tasks` 浮条。 ### 6.2 后台子代理 提示词: ```text 测试后台子代理:调用 agent_spawn,subagent_type 用 explore,timeout_seconds 设为 0, 任务是列出当前案件的表名。拿到 task_id 后告诉我已提交即可,不要编造结果。 ``` 预期: - 工具结果 `status: accepted` + `task_id`; - 执行流水出现 `后台子代理 explore 运行中`,1s 轮询更新耗时; - **不在「下一步分析方向」后面**;输入框上方无浮条; - 任务完成后同一行变 `已完成`,汇总行 `1 个后台任务`。 下一轮追问「刚才的后台任务完成了吗?把表名清单转述给我」:父 Agent 收到一次交付并转述,DB 无 `task_result` 消息。 ### 6.3 长报告落盘 后端以 `SUBAGENT_MAX_INLINE_RESULT_CHARS=800` 重启,然后: ```text 测长报告落盘:调用 agent_spawn,subagent_type 用 python-worker, 任务是逐行打印 1 到 200 的平方(每行一个,print 出来),并在最终报告里列出这些结果。 同步等待即可。 ``` 预期: - 工具结果含 ``、`Full report saved to: <绝对路径>`、头部预览; - `cases/{caseId}/ai/analysis/{userId}/{sessionId}/runs/subagent-*.md` 存在且内容为完整报告; - 父 Agent 读取该文件后转述结论(不再把全文硬塞进上下文)。 ### 6.4 刷新/隔离检查 1. 完成一次同步子代理后刷新页面 → 子代理行消失,只保留父消息。 2. 查看 `agent_message` 最新 assistant 行 → `content` 无子代理完整报告,`tool_events` 只有 `agent_spawn` 投影。 3. 检查磁盘无 `sub-*` 子会话转录目录(子代理 `disableSessionPersistence`)。 --- ## 7. 未覆盖与待补 | 缺口 | 现状 | 建议 | |---|---|---| | artifact `path` 回读 | `path` 是相对数据根路径;当前没有工具向模型注入数据根,模型直接 `open(path)` 会失败(`id` 预览/下载正常,落盘报告给的是绝对路径) | 若要严格满足「模型按 path 回读」,在 `execute_python` 工具结果里补数据根/绝对路径提示 | | 停止会话后任务行不自动收敛 | `stopSession` 清空任务注册表;前端 `loadTasks` 拿不到条目时保留消息里的最后状态(可能停在「运行中」) | 前端在 stop 后把所有运行中任务行本地置为「已取消」,或后端保留取消态直到下一次轮询 | | `ArtifactService.registerFile` 无 JUnit | 幂等 dedupe、`createdByUserId`/`sha256` 只有手工覆盖(AR-03/04) | 补:同源文件重复登记、内容变化后重新登记、元数据字段 | | `AnalysisWorkspaceService` 无 JUnit | 只有手工用例 AR-01~07 | 补:目录创建、outputs 过滤/dedupe、meta 写入、maxScanFiles | | `SubagentDeliveryMiddleware` 无 JUnit | 手工 BG-07/08 | 补:delivery 一次、失败根因、markDelivered 幂等 | | SSE `source` 分流无 JUnit | 手工 SSE-01~03/06 | 补:模拟 source 事件断言父正文/落库不被污染 | | `/chat/tasks` API 无 MockMvc 测试 | 手工 ISO-01/05 | 补:三参数过滤、越权 404、取消 | | `SubagentSpawnTool` 实际调用无 JUnit | 只有 schema 测试 | 补:mock Agent/manager,断言 tools 交集、错误分支 | | 前端无 vitest/Playwright | 仅 `pnpm type:check` + 手工 | 若长期维护,建议引入 vitest 或 Playwright | | 设计文档正文未同步 | §4.1/§4.3/§12 仍是历史方案 | 建议后续单独回写设计文档,或以上表为准 | --- ## 8. 执行记录 | 日期 | 执行人 | 版本/提交 | 范围 | 结果 | 备注 | |---|---|---|---|---|---| | 2026-11-06 | | `7d6ceb23` | 全量 A 层 + 手工 C 层 | 待执行 | 基线实现 | | 2026-11-06~07 | ZCode 自动化 | `7d6ceb23` | 全量 A 层(374 通过)+ B/C 层三轮开关组合 | 52 PASS / 4 BUG / 5 观察 | 报告见 `analysis-runtime-subagent-test-report-20261107.md`;模型临时改用 GLM-4.6-e2e(本地 Ollama 不可达) | > 回填规则:每条用例在 §4 表格「自动化」列旁补 `PASS/FAIL`;FAIL 记录复现步骤、日志片段与提交号。