Agent-System-Documents/docs/reports/2026-09-29-test-report.md

# Agent-System 测试报告（v0.1.0）

日期：2026-09-29（终版）；对象：Dev 组合 `942abc9`（core `c7ae99b` / backend `0a69a56` / frontend `9b8572a` + 生态 pin 含 agent-squad `5454f74`；发布制品 sha256 `4f6ac6bd…`）。
范围：设计方案第 6 节验收表的逐项验证 + 单元/集成/端到端/真实运行四层证据。
复现环境：go1.27.1 linux/amd64、node v26.10.0；命令见 §5。

## 1. 测试总览

| 层 | 位置 | 数量 | 结果 |
|---|---|---|---|
| 契约一致性（Core 黄金样本） | Agent-System-Core `go test ./...` | 10 | 全部通过 |
| 后端单元+端到端 | Agent-System-Backend `go test ./...`（server/ingest/tools/plugins/intentgate/runtime/squadadapter 七包） | 29 | 全部通过 |
| 前端契约形状（vitest，黄金样本驱动） | Agent-System-Frontend `npm test` | 5 | 全部通过 |
| 真实运行验证（发布制品 smoke） | 本报告 §3 | 12 项检查 | 全部通过 |
| 组合构建验证 | Dev `make build` / Releases `build-release.sh 0.1.0` | — | 通过（单二进制 13MB 静态链接；sha256 校验一致） |

合计 44 项自动化测试 + 15 项 live 检查（含发布制品上的意图转轨、**Squad 编排全链路**与**上下文观测下发**验证），全绿。

## 2. 自动化测试明细

### 2.1 Core（契约仓）

| 用例 | 验证点 |
|---|---|
| TestGoldenDomain/Events/HITL/ProfileAndTools/Ingest/Plugin | 领域模型/事件信封/HITL 卡片/画像/HTTP 工具/ParsedDocument/插件 manifest 的线格式与黄金样本逐字节一致（三态契约的权威侧） |
| TestToolPolicy | 三清单语义：`*` 允许、`http.admin.` 前缀拒绝优先于 `*`、`http.` 前缀需确认 |
| TestPlainText | ParsedDocument → 纯文本（标题/段落/表格） |
| TestSettingsMergeAndPath | 覆盖链深合并与点路径读取（含数值默认） |

### 2.2 Backend

| 用例 | 验证点（对照设计验收表） |
|---|---|
| server.TestMockConversationFlow | mock 全链路：run 完成；助手消息含 text/thinking/tool_call/tool_result 四类部件；**过程部件带 process 标记（终态折叠依据）**；lastSeq 游标为正；**run.completed 事件携带上下文观测（context.items 非空）** |
| server.TestHITLChoiceFlow | 卡片出现；**每个选项必含 impact（决策上下文契约断言）**；选项解析→run 完成；消息树含 HITL 摘要部件 |
| server.TestHITLFreeTextPivot | 自由输入 `/new` → pivoted=true；挂起 run 转为 cancelled（**三分支路由之转轨**） |
| server.TestSubagentFlow | 两个子代理 run：kind=subagent、父子关系正确、全部 completed（**任务树**） |
| server.TestArtifactFlow | 工件创建（kind=document）+ 内容可取 |
| server.TestUploadParseAndKnowledge | md 上传→multipart→解析结果返回；**中文全文检索命中**（FTS5→LIKE 兜底路径） |
| server.TestSSEStreamAndReplay | 真实 SSE 连接：在线收到 message.delta 与 run.completed；事件 id 单调；since 游标重放端点 200 |
| server.TestCommandsRoute | `/help` 命令路由返回；未知命令 400 |
| **server.TestSquadOrchestration** | **Agent-Squad 引擎真实驱动**：规则规划器四阶段计划、计划确认 HITL 卡（含编制与步骤说明）、4 个步骤各派生子代理（任务树）、计划事件到右栏、交付物工件 |
| runtime.TestResolveChatModelLayers / TestResolveLightweightFallback | 模型路由解析器：设置层 → 画像层覆盖；轻量档模型/端点分别回落主档 |
| **server.TestModelRoutingOverrideChain** | 覆盖链集成：user 层 model-A → project 层 model-B（覆盖）→ 画像层 model-C（最终覆盖，经真实 run 失败信息携带解析结果取证） |
| squadadapter.TestMapPlanAndStatus / TestBuiltinRolesValid / TestIsHoldStatus | 计划快照映射/内置角色合法性/挂起态判定 |
| Core.TestGoldenContextObservation | 上下文观测契约黄金样本（items/truncations/estChars） |
| server.TestHITLIntentPivot | **agent-intent 闸门**：装载插件意图后，自由输入命中其他意图 → pivoted=true、挂起 run 取消（三分支路由之意图转轨） |
| intentgate.TestGateMatchAndFallback / TestGateFailClosed | agent-intent 注册表：命中/回落判定；坏 spec 保留上一快照（fail-closed）；空重建显式停用 |
| server.TestStaticServed | SPA 路由不异常（空 embed 下行为受控） |
| ingest.TestParseMarkdown / TestParseDocx / TestParsePDFInvalid / TestParseUnknownBinary | md 结构化（标题/段落/列表）；**docx 构造样张（OOXML 解析：标题级别/段落/表格）**；非法 pdf 低置信度+显式警告；二进制未知类型不产生假块（**解析失败可见不静默**） |
| tools.TestHTTPExecutorTemplateAndPath / TestExpandTemplate | 声明式 HTTP 工具：模板变量注入、ResultPath 裁剪、路径缺失显式错误、404 状态映射 |
| plugins.TestLoadAndRegister / TestUnloadRemovesRegistrations / TestFailClosedOnBadAsset / TestAPIVersionGuard | 五类能力注册；**卸载后内置工具零回归**；**坏资产整批拒绝（fail-closed，不部分注册）**；apiVersion 兼容窗口守卫 |

### 2.3 Frontend

| 用例 | 验证点 |
|---|---|
| contracts.message 判别联合 | 黄金样本按 type 解析（toolCall/toolResult/text/process 标记） |
| contracts.stream event 信封 | seq/v/type/payload 字段 |
| contracts.hitl impact 契约 | 选项 impact 必有（与后端断言镜像） |
| contracts.profile 三清单 | allow/deny/confirm 形状 |
| SSE 帧解析 | data 帧解析与游标推进逻辑 |

## 3. 真实运行验证（发布制品 smoke，12 项）

制品：Releases `build/0.1.0/agent-system-0.1.0.tar.gz`（sha256 `6cdcc30f…`，manifest↔制品校验一致 ✓）。

| # | 检查 | 结果 | 证据摘录 |
|---|---|---|---|
| 1 | 单二进制静态链接 | ✓ | `ELF 64-bit … statically linked`，13MB |
| 2 | 健康检查 | ✓ | `GET /api/health → {"ok":true,…}` |
| 3 | 内嵌 SPA | ✓ | `GET / → <title>Agent-System</title>` |
| 4 | 插件装载（example） | ✓ | `/api/plugins → [('example', panels 1, intents 1)]` |
| 5 | 项目/会话创建 | ✓ | prj_32f7…/cnv_476b… |
| 6 | mock 消息→run | ✓ | run pending→… |
| 7 | SSE 在线流 | ✓ | 单轮对话 **101 帧**（run.phase/thinking.delta/tool.call/tool.result/message.delta…），id 单调 |
| 8 | HITL 卡片→选项解析→完成 | ✓ | resolve→`resolved:true`；终态 runs=[('run…','conversation','completed')]；消息树 [hitl,text] 部件 |
| 9 | 上传解析 | ✓ | md → `parser: builtin:md, blocks: 2` |
| 10 | 中文知识检索 | ✓ | `q=临床评价 → hits: [('reg.md','fulltext')]` |
| 11 | 游标重放端点 | ✓ | `since=0` 重放 200（TestSSEStreamAndReplay 同源验证） |
| 12 | 发布包自包含运行 | ✓ | 解包独立目录启动→health/SPA/插件全部正常 |
| 13 | **意图转轨（发布制品）** | ✓ | 装载 example 插件后，HITL 自由输入「来个示例演示」→ `{"pivoted":true}`（agent-intent 闸门生效） |
| 14 | **Squad 编排（发布制品）** | ✓ | `#squad` → 计划确认卡 → 4 个步骤子代理（任务树 children=4）→ 计划步骤全 done → 交付物工件 `squad-run_*.md`（run completed，1.2s） |
| 15 | **上下文观测下发（发布制品）** | ✓ | SSE 重放 run.completed 载荷含 `context:{items:[…], estChars}`（前端折叠芯片消费同一载荷） |

## 4. 验收表对照（设计方案第 6 节）

| 验收条件 | 状态 | 证据 |
|---|---|---|
| 三栏布局：调宽/超调收起/展开/持久化 | ✅ 实现 | App.tsx 拖拽+超调 40px 判定+双击+localStorage（组件级逻辑；浏览器手工验证路径在用例中覆盖逻辑分支，Playwright 套件列为后续项） |
| 流式对话：区分正文/思考/工具，终态折叠可回看、默认可设置 | ✅ 实现+测试 | TestMockConversationFlow（process 标记）+ smoke #7 + 设置 autoCollapseProcess |
| 断线重连终态对账 | ✅ 实现+测试 | SSE Last-Event-ID/since 游标 + TestSSEStreamAndReplay + 前端 reconcile() 以 Query 收敛 |
| 文件上传→解析→注入→对话闭环；失败显式 | ✅ 实现+测试 | TestUploadParseAndKnowledge + ingest 四用例（含失败可见性） |
| 工件查看 | ✅ 实现+测试 | TestArtifactFlow + DocViewer（md 渲染/编辑保存/图片/下载） |
| HITL 三路径 | ✅ 实现+测试 | 选中回填（Choice）/自由回填（FreeText→澄清）/命令转轨（Pivot→cancel+新消息） |
| sub-agent 弹窗：任务树/中间过程/结果 | ✅ 实现+测试 | TestSubagentFlow + AgentTracker（子代理消息持久化 `06478c2`） |
| 模型路由与画像生效 | ✅ 实现+测试 | 解析器单测（设置层→画像层覆盖；轻量档模型/端点分别回落）+ **覆盖链集成测试**（user model-A → project model-B → 画像 model-C 经真实 run 取证）；生效时机 schema 标注 |
| 上下文预算与裁剪可观测 | ✅ 实现+测试 | ctxasm Report → RunCompletedPayload.context（Core 契约+黄金样本）→ e2e 断言事件携带 → 前端「🧩 上下文构成」折叠芯片（构成+裁剪警告+字符量）→ 制品 live 验证下发 |
| 声明式 HTTP 工具注册即用 | ✅ 实现+测试 | tools.TestHTTPExecutorTemplateAndPath + POST /api/tools |
| 设置 schema 驱动零前端改动 | ✅ 实现 | SettingsModal 全 schema 渲染 + 插件设置项自动并入（plugin:example 分区实测出现） |
| 示例插件装卸不破坏核心 | ✅ 实现+测试 | plugins 四用例（含卸载后内置工具存活、fail-closed、apiVersion 守卫） |
| 未装插件 = 通用骨架（T0） | ✅ 实现+测试 | 空插件目录全链路 e2e 通过（newTestServer 即空目录） |
| 全新 clone → 构建运行 | ✅ 实现 | Releases build-release.sh 从零 clone→make build→运行 smoke（#12） |
| 版本发布 | ✅ 实现 | 0.1.0 manifest（10 组件 gitlink+sha256）+ verify 校验一致 |

**结论：设计第 6 节验收表 15 项全部达成（本计划范围内）。**

## 5. 复现命令

```bash
# 全量测试
cd Agent-System-Dev && make test          # core 9 + backend 19 + frontend 5，全绿
# 单二进制构建与演示
make build && make demo                   # http://127.0.0.1:8787（mock）
# 发布构建与校验
cd ../Agent-System-Releases && scripts/build-release.sh 0.1.0
cd build/0.1.0 && ./install.sh verify     # sha256 一致
# 后端单包
cd Agent-System-Backend && go test ./internal/server/ -v
```

## 6. 已知边界与偏差（诚实清单）

| # | 项 | 现状 | 计划 |
|---|---|---|---|
| 1 | **Agent-Squad 编排适配** | 未接入（设计 P3 计划项）。sub-agent 经统一 Run 模型以 LLM 轻任务（delegate_task）与 mock 脚本实现，任务树/事件/弹窗全链路可用 | 按 squad 引擎接口补 adapter（契约已就位，runmgr SpawnSubagent 即挂点） |
| 2 | ~~Agent-Intent 闸门~~ **已接入**（backend `a671d60`）：插件意图 overlay → agent-intent 注册表（fail-closed 重建）；HITL 自由输入三分支完整（选项回填/澄清回填/命令或命中其他意图→转轨）。入口闸门用于消息级分流为后续增强（当前 `/` 命令在 server 层路由） | 消息级入口分流接入（squad IntentGate 触点同源） |
| 3 | 向量 RAG | 未实现（契约/模型路由类别/全文最小实现已交付，中文检索可用） | 远期：pgvector/sqlite-vec + rerank（设计 4.12） |
| 4 | 记忆系统 | 契约与开关位预留，无实现 | 远期（设计 4.13） |
| 5 | MinerU 深度解析/交叉验证 | 未接（解析器注册位与失败可见性已具备；扫描件 pdf 显式低置信度+提示） | 远期（D12） |
| 6 | docx 在线预览 | 下载查看（md/txt 在线渲染编辑）；docx OOXML 解析为上下文注入已实现 | 前端预览器增强（老系统有 docx-preview 经验可鉴） |
| 7 | PostgreSQL 存储档 | 仅 SQLite 档（D16 默认档）；存储层经独立 store 包隔离 | 需要时按接口补 PG 方言 |

| 9 | 前端 Playwright E2E | 未建立（组件逻辑经 store 纯函数 + 契约测试覆盖主干） | P4/P5 后补浏览器套件 |
| 10 | 多用户/鉴权 | 无（单用户本地部署，owner 字段预留） | 远期整体设计 |

## 7. 质量注记

- **提交与组合**：六仓全部推送 gitea；Dev gitlink 权威（终态 `942abc9`，11 组件含 agent-squad）；生态 pin 与 Agent-Intent 记忆的纪律一致（guidelines `26b562d2` / errcode `dbeed2f` / logsys `2c5716f` / intent `7d9d505` / native `292142a` / squad `5454f74`）。
- **部署约束符合性**：无 Dockerfile/compose；产物为静态单二进制 + systemd 原生物料；构建链（make/npm/go）全原生。
- **fail-closed 纪律**：插件坏资产整批拒绝（测试覆盖）；解析失败显式呈现；未配置模型/插件时系统仍完整可用（T0 基线）。