add design doc: multi-session-plugin-optimization
This commit is contained in:
Haitao Pan
parent
1e20c8e6ed
commit
2f8a047798
@ -0,0 +1,365 @@
|
||||
# openclaw-multi-session-plugins 架构优化建议
|
||||
|
||||
> 基于 OpenClaw 2026.6.1 原生能力，简化多会话插件设计
|
||||
|
||||
## 一、核心原则
|
||||
|
||||
**尽可能复用 OpenClaw 2026.6.1 原生的能力。** 插件只做 OpenClaw 原生不提供的事：逻辑隔离的多会话制品作用域管理。任务生命周期、会话管理、状态同步全部委托给 OpenClaw 原生机制。
|
||||
|
||||
## 二、当前问题全景
|
||||
|
||||
### 2.1 任务完成无法感知（核心痛点）
|
||||
|
||||
OpenClaw 任务执行完了，APP 侧还在"运行中"，制品也没同步。根因在于：
|
||||
|
||||
```
|
||||
APP 侧 polling → xworkmate.tasks.get → Bridge → ??? → OpenClaw
|
||||
↑
|
||||
这里断了
|
||||
```
|
||||
|
||||
**具体原因**：
|
||||
|
||||
1. **openclaw-multi-session-plugins 没有注册 `xworkmate.tasks.get` gateway method**。插件注册的方法只有 `xworkmate.artifacts.*` 和 `xworkmate.agents.run`，没有 task 查询接口。
|
||||
|
||||
2. **插件没有在 OpenClaw 原生 task-registry 中创建 TaskRecord**。OpenClaw 的 `task-registry.ts` 是任务状态的唯一权威来源（`TaskRecord { taskId, runId, status, requesterSessionKey, ... }`），但插件完全绕过了它，自己管理制品作用域，没有任何原生任务记录。
|
||||
|
||||
3. **SSE 流断开后的恢复路径脆弱**。APP 的 `_recoverTaskResultAfterStreamClosure` 和 `pollOpenClawTaskAssociationInternal` 都依赖 `xworkmate.tasks.get`，但这个方法在 OpenClaw 侧没有实现，只能靠 Bridge 自己维护状态。
|
||||
|
||||
### 2.2 expectedArtifactDirs 参数断裂
|
||||
|
||||
```
|
||||
APP (metadata.xworkmateTaskArtifactContract) → session.start params
|
||||
→ Bridge (转发) → Plugin scopedGatewayParams()
|
||||
↑
|
||||
这里丢失了 expectedArtifactDirs
|
||||
```
|
||||
|
||||
- `scopedGatewayParams()` 只映射 `sessionKey`, `runId`, `workspaceDir`, `artifactScope`
|
||||
- `expectedArtifactDirs` 不在映射中
|
||||
- `bridgeAgents.ts` 的 `runXWorkmateBridgeAgents()` 调用 `exportXWorkmateArtifacts` 时也没传这个参数
|
||||
- 虽然 Fix 0 在 `exportXWorkmateArtifacts` 中加了回退扫描逻辑（行 263-283），但这个逻辑永远不会被触发，因为参数从未到达
|
||||
|
||||
### 2.3 会话 Key 映射没有双向约定
|
||||
|
||||
- APP 使用: `draft:1780636411666238-3`
|
||||
- OpenClaw 使用: `agent:main:draft:1780636411666238-3`
|
||||
- 插件用 `safeScopeSegment()` 做单向规范化，但反向查询时无法从 OpenClaw session key 推导出 APP session key
|
||||
- 没有利用 OpenClaw 的 `SessionEntry.pluginExtensions` 存储双向映射
|
||||
|
||||
### 2.4 插件边界过于厚重
|
||||
|
||||
当前插件的职责混合了：
|
||||
- 制品作用域管理（合理的独特价值）
|
||||
- 通过 bridgeAgents 做 HTTP RPC 调用（应该委托给 Gateway 原生能力）
|
||||
- 隐式的任务状态追踪（没有利用原生 task-registry）
|
||||
- 会话上下文传递（绕过了原生 session store）
|
||||
|
||||
## 三、OpenClaw 2026.6.1 可复用的原生能力
|
||||
|
||||
| 原生能力 | 位置 | 可以替代的当前实现 |
|
||||
|---------|------|-----------------|
|
||||
| Task 注册与状态机 | `src/tasks/task-registry.ts` | APP 侧的 polling 循环、恢复逻辑 |
|
||||
| Task Flow 编排 | `src/tasks/task-flow-registry.ts` | bridgeAgents 的多代理编排 |
|
||||
| Session 持久化 | `src/config/sessions/store.ts` | 会话 key 映射、上下文存储 |
|
||||
| Plugin Extensions | `SessionEntry.pluginExtensions` | 零散的上下文传递 |
|
||||
| Session Key 解析 | `src/sessions/session-key-utils.ts` | `safeScopeSegment()` 字符串处理 |
|
||||
| Gateway 路由解析 | `src/routing/resolve-route.ts` | APP 侧的 routing 配置 |
|
||||
| Plugin API Facades | `src/plugins/api-facades.ts` | 直接操作底层 API |
|
||||
| Transcript 事件 | `src/sessions/transcript-events.ts` | SSE 流的手动管理 |
|
||||
| Compaction Checkpoint | `src/gateway/session-compaction-checkpoints.ts` | 制品快照 |
|
||||
|
||||
## 四、优化方案
|
||||
|
||||
### 4.1 核心改动：注册 xworkmate.tasks.get，对接原生 Task Registry
|
||||
|
||||
在 `index.ts` 的 `register()` 中新增 gateway method：
|
||||
|
||||
```typescript
|
||||
api.registerGatewayMethod("xworkmate.tasks.get", async (opts: GatewayRequestHandlerOptions) => {
|
||||
try {
|
||||
const params = scopedGatewayParams(opts.params);
|
||||
const runId = optionalString(params.runId);
|
||||
const sessionKey = optionalString(params.sessionKey);
|
||||
|
||||
// 1. 从 OpenClaw 原生 task registry 查询任务状态
|
||||
const taskRegistry = api.taskRegistry; // 通过 PluginRuntime 暴露
|
||||
let taskRecord = null;
|
||||
if (runId) {
|
||||
taskRecord = await taskRegistry.findByRunId(runId);
|
||||
}
|
||||
|
||||
// 2. 查询制品导出状态
|
||||
let artifactPayload = null;
|
||||
if (sessionKey && runId) {
|
||||
try {
|
||||
artifactPayload = await exportXWorkmateArtifacts({
|
||||
params: { sessionKey, runId, workspaceDir: params.workspaceDir },
|
||||
config: api.config,
|
||||
pluginConfig: api.pluginConfig,
|
||||
});
|
||||
} catch { /* artifacts optional */ }
|
||||
}
|
||||
|
||||
// 3. 合并返回
|
||||
const result: Record<string, unknown> = {
|
||||
sessionId: sessionKey,
|
||||
runId: runId,
|
||||
status: taskRecord?.status ?? (artifactPayload ? "completed" : "unknown"),
|
||||
...(taskRecord ? {
|
||||
taskId: taskRecord.taskId,
|
||||
startedAtMs: taskRecord.createdAt,
|
||||
runtimeBudgetMinutes: taskRecord.runtimeBudgetMinutes,
|
||||
} : {}),
|
||||
...(artifactPayload ? {
|
||||
remoteWorkingDirectory: artifactPayload.remoteWorkingDirectory,
|
||||
remoteWorkspaceRefKind: artifactPayload.remoteWorkspaceRefKind,
|
||||
artifactScope: artifactPayload.artifactScope,
|
||||
artifacts: artifactPayload.artifacts,
|
||||
warnings: artifactPayload.warnings,
|
||||
} : {}),
|
||||
};
|
||||
opts.respond(true, result, undefined);
|
||||
} catch (error) {
|
||||
opts.respond(false, undefined, {
|
||||
code: "TASK_GET_FAILED",
|
||||
message: error instanceof Error ? error.message : String(error),
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
同时在 `session.start` hook 中创建原生 TaskRecord：
|
||||
|
||||
```typescript
|
||||
api.registerHook("session.start", async (event: any) => {
|
||||
try {
|
||||
const params = scopedGatewayParams(event?.context ?? event);
|
||||
if (params.sessionKey && params.runId) {
|
||||
// 创建原生 TaskRecord（复用 OpenClaw task-registry）
|
||||
await api.taskRegistry.createTask({
|
||||
taskId: `xworkmate-${params.runId}`,
|
||||
runtime: "subagent", // 或新增 "xworkmate" runtime type
|
||||
requesterSessionKey: params.sessionKey,
|
||||
ownerKey: params.sessionKey,
|
||||
status: "running",
|
||||
runId: params.runId,
|
||||
});
|
||||
// 准备制品作用域
|
||||
await prepareXWorkmateArtifacts({ params, config: api.config, pluginConfig: api.pluginConfig });
|
||||
}
|
||||
} catch (e) {
|
||||
// best-effort
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**收益**：
|
||||
- 任务状态有原生 TaskRecord 作为权威来源，状态机由 OpenClaw 管理（queued → running → succeeded/failed）
|
||||
- APP 的 `pollOpenClawTaskAssociationInternal` 和 `_recoverTaskResultAfterStreamClosure` 直接查询到真实状态
|
||||
- 不再依赖脆弱的 SSE 流恢复逻辑
|
||||
|
||||
### 4.2 打通 expectedArtifactDirs 全链路
|
||||
|
||||
**Step 1 — Plugin 侧**：在 `scopedGatewayParams()` 中加入透传：
|
||||
|
||||
```typescript
|
||||
function scopedGatewayParams(params: Record<string, unknown>): Record<string, unknown> {
|
||||
const sessionScope = (getPluginRuntimeGatewayRequestScope() as XWorkmateGatewayRequestScope | undefined)?.sessionScope;
|
||||
const runScope = resolveRunScope({ sessionScope });
|
||||
if (!runScope) {
|
||||
return params;
|
||||
}
|
||||
return {
|
||||
...params, // ← 保留所有原始参数
|
||||
sessionKey: runScope.sessionKey,
|
||||
runId: runScope.runId,
|
||||
...(runScope.workspaceDir ? { workspaceDir: runScope.workspaceDir } : {}),
|
||||
...(runScope.artifactScope ? { artifactScope: runScope.artifactScope } : {}),
|
||||
// 透传 expectedArtifactDirs（不覆盖已映射的关键字段）
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
关键改动：从 `{ ...params, sessionKey, runId, ... }` 改为先展开 params，再覆盖关键字段。这样 `expectedArtifactDirs` 等附加参数自然透传。
|
||||
|
||||
**Step 2 — Bridge 侧**：在 `session.start` 参数中包含 `expectedArtifactDirs`：
|
||||
|
||||
```typescript
|
||||
// 从 xworkmateTaskArtifactContract metadata 中提取
|
||||
const artifactContract = request.metadata?.['xworkmateTaskArtifactContract'];
|
||||
const params = {
|
||||
sessionId: sessionKey,
|
||||
threadId: threadKey,
|
||||
taskPrompt: prompt,
|
||||
expectedArtifactDirs: artifactContract?.expectedArtifactDirs ?? ["assets/images", "reports", "video"],
|
||||
// ...其他参数
|
||||
};
|
||||
```
|
||||
|
||||
**Step 3 — APP 侧**：在 `gatewayTaskMetadataWithArtifactContractInternal` 中加入：
|
||||
|
||||
```dart
|
||||
'xworkmateTaskArtifactContract': {
|
||||
'version': 1,
|
||||
'sessionKey': sessionKey,
|
||||
'expectedArtifactDirs': ['assets/images', 'reports', 'video'],
|
||||
// ...existing fields
|
||||
},
|
||||
```
|
||||
|
||||
**收益**：Fix 0 的回退扫描逻辑真正生效，agent 写入 workspace 根的文件能被纳入 artifact scope。
|
||||
|
||||
### 4.3 利用 SessionEntry.pluginExtensions 做双向 Key 映射
|
||||
|
||||
```typescript
|
||||
api.registerHook("session.start", async (event: any) => {
|
||||
const params = scopedGatewayParams(event?.context ?? event);
|
||||
if (params.sessionKey && params.runId) {
|
||||
// 存储双向映射
|
||||
await api.session.state.setPluginExtension(
|
||||
params.sessionKey,
|
||||
"openclaw-multi-session-plugins",
|
||||
"xworkmate",
|
||||
{
|
||||
appSessionKey: params.appSessionKey, // ← APP 侧的 key
|
||||
appThreadId: params.threadId,
|
||||
expectedArtifactDirs: params.expectedArtifactDirs,
|
||||
artifactScope: artifactScopeFor(params.sessionKey, params.runId),
|
||||
}
|
||||
);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**收益**：
|
||||
- 无需在 session key 之间做脆弱的字符串推导
|
||||
- 任意方向查询 O(1)
|
||||
- 利用 OpenClaw 原生的 session store 持久化
|
||||
|
||||
### 4.4 简化 bridgeAgents 为纯 plugin 内部调用
|
||||
|
||||
当前 `bridgeAgents.ts` 通过 HTTP fetch 调用外部 bridge：
|
||||
|
||||
```typescript
|
||||
const bridgeResult = await callBridgeRPC({
|
||||
bridgeUrl,
|
||||
bridgeToken,
|
||||
body: { jsonrpc: "2.0", method: "session.start", params: {...} },
|
||||
});
|
||||
```
|
||||
|
||||
这导致 bridgeAgents 成为 HTTP 客户端而非插件逻辑。建议改为：
|
||||
|
||||
```typescript
|
||||
// 方案 A: 通过 OpenClaw 原生 subagent.run() 调度
|
||||
const result = await api.runtime.subagent.run({
|
||||
agentId: providerId,
|
||||
prompt: step.prompt,
|
||||
sessionKey: prepared.artifactScope,
|
||||
workspaceDir: prepared.artifactDirectory,
|
||||
});
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```typescript
|
||||
// 方案 B: 注册为原生 TaskFlow
|
||||
const flow = await api.taskFlows.create({
|
||||
syncMode: "managed",
|
||||
ownerKey: sessionKey,
|
||||
goal: taskPrompt,
|
||||
steps: steps.map(s => ({
|
||||
providerId: s.providerId,
|
||||
prompt: s.prompt,
|
||||
outputAs: s.outputAs,
|
||||
})),
|
||||
});
|
||||
```
|
||||
|
||||
**收益**：
|
||||
- bridgeAgents 不再需要独立的 HTTP 客户端
|
||||
- 复用 OpenClaw 的 subagent 调度和 task flow 编排
|
||||
- 状态同步自动由 task-registry 管理
|
||||
|
||||
### 4.5 用 Transcript Events 替代 SSE 流管理
|
||||
|
||||
OpenClaw 原生有 `transcript-events.ts`：
|
||||
|
||||
```typescript
|
||||
// 监听 transcript 更新事件，自动通知 APP 侧
|
||||
api.session.onTranscriptUpdate(params.sessionKey, (update) => {
|
||||
// 通过 Gateway push 通知 APP
|
||||
api.gateway.push("session.update", {
|
||||
sessionId: params.sessionKey,
|
||||
turnId: update.turnId,
|
||||
delta: update.delta,
|
||||
event: update.isComplete ? "completed" : "delta",
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**收益**：不依赖 Bridge 层的 SSE 连接稳定性，由 OpenClaw 原生事件系统驱动。
|
||||
|
||||
## 五、实施优先级
|
||||
|
||||
| 优先级 | 改动 | 涉及层 | 复杂度 | 收益 |
|
||||
|--------|------|--------|--------|------|
|
||||
| **P0** | 注册 xworkmate.tasks.get + 创建原生 TaskRecord | Plugin | 中 | 解决"任务完成无法感知"核心问题 |
|
||||
| **P0** | 打通 expectedArtifactDirs 全链路 | Plugin + Bridge + APP | 低 | 解决制品遗漏问题 |
|
||||
| **P1** | 利用 pluginExtensions 做 Key 映射 | Plugin | 低 | 消除会话 key 歧义 |
|
||||
| **P1** | session.start hook 中创建 TaskRecord | Plugin | 低 | 任务状态有权威来源 |
|
||||
| **P2** | bridgeAgents 使用原生 subagent.run | Plugin | 高 | 消除 HTTP 客户端依赖 |
|
||||
| **P2** | 用 Transcript Events 替代 SSE 管理 | Plugin + Bridge | 高 | 简化流管理 |
|
||||
|
||||
## 六、简化后的架构全景
|
||||
|
||||
```
|
||||
XWorkmate App (Flutter/Dart)
|
||||
│
|
||||
│ session.start (含 expectedArtifactDirs+metadata)
|
||||
▼
|
||||
xworkmate-bridge (Go) ── ACP JSON-RPC ── OpenClaw Gateway
|
||||
│ │
|
||||
│ xworkmate.tasks.get ◄────────────────┤
|
||||
│ (查询原生 TaskRegistry + artifacts) │
|
||||
│ │
|
||||
│ ┌─────────┴──────────┐
|
||||
│ │ openclaw-multi- │
|
||||
│ │ session-plugins │
|
||||
│ │ │
|
||||
│ │ 职责聚焦: │
|
||||
│ │ 1. artifact scope │
|
||||
│ │ 2. 原生 TaskRecord │
|
||||
│ │ 3. pluginExtensions │
|
||||
│ │ │
|
||||
│ │ 委托给原生: │
|
||||
│ │ - task-registry.ts │
|
||||
│ │ - session store │
|
||||
│ │ - transcript events │
|
||||
│ │ - subagent.run() │
|
||||
│ └─────────────────────┘
|
||||
│ │
|
||||
│ OpenClaw 原生基础设施
|
||||
│ (task-registry, session
|
||||
│ store, routing, ...)
|
||||
▼
|
||||
APP 侧 polling 简化:
|
||||
pollOpenClawTaskAssociationInternal
|
||||
→ xworkmate.tasks.get
|
||||
→ 原生 TaskRegistry.findByRunId(runId) ← 权威状态
|
||||
+ exportXWorkmateArtifacts() ← 权威制品
|
||||
```
|
||||
|
||||
## 七、参考 Case
|
||||
|
||||
用户提供的真实案例：
|
||||
|
||||
- OpenClaw URL: `https://openclaw.svc.plus/chat?session=agent%3Amain%3Adraft%3A1780636411666238-3`
|
||||
- APP 线程目录: `$HOME/.xworkmate/threads/draft-1780636411666238-3`
|
||||
|
||||
这说明 session key 的自然映射是：
|
||||
- OpenClaw session key: `agent:main:draft:1780636411666238-3`
|
||||
- APP session key: `draft:1780636411666238-3`
|
||||
|
||||
在优化后的架构中，这个映射存储在 `SessionEntry.pluginExtensions` 中，双向查询均为 O(1)。任务状态通过原生 `TaskRecord` 追踪，`xworkmate.tasks.get` 一次调用同时返回任务状态和制品列表。
|
||||
@ -0,0 +1,162 @@
|
||||
# Flutter 290 测试用例有效性分析
|
||||
|
||||
对照 `docs/cases/openclaw-gateway-e2e-regression/README.md` 的回归目标，对全库 36 个测试文件、290 个测试用例进行分类。
|
||||
|
||||
## 分析方法
|
||||
|
||||
每个测试按三个维度评估：
|
||||
|
||||
- **覆盖目标**：是否覆盖 README 列出的回归场景（5 并发隔离、artifact 同步、连接稳定性、错误码防御）
|
||||
- **代码路径**：是否测试真实生产代码路径（非 dead code、非纯 mock 自循环）
|
||||
- **维护成本**：测试的断言复杂度、setup 成本、对重构的敏感度
|
||||
|
||||
---
|
||||
|
||||
## 一、核心回归测试（与 README 直接对齐）— 124 个
|
||||
|
||||
这些测试直接覆盖 README 中 5 并发 E2E 场景的 App 侧验证点。
|
||||
|
||||
| 文件 | 测试数 | 覆盖点 |
|
||||
|------|--------|--------|
|
||||
| `test/runtime/assistant_execution_target_test.dart` | 69 | README 行 18：App 侧 5 个代表任务同时进入 running，复用各自 session/thread，不进入 queued。覆盖 OpenClaw gateway provider catalog、session 路由、skill 选择与隔离、消息发送（含 5 canonical prompts）、ACP 错误恢复、artifact guard、并发任务隔离、同一 prompt 不同 task 隔离 |
|
||||
| `test/runtime/gateway_acp_client_auth_test.dart` | 48 | README 行 136：`flutter test test/runtime/gateway_acp_client_auth_test.dart`。覆盖 ACP 响应解析、HTTP auth（token 来源优先级）、SSE transport、task snapshot recovery、连接诊断（502/handshake/connect timeout）、bridge unified RPC 路由 |
|
||||
| `test/runtime/desktop_thread_artifact_service_test.dart` | 3 | README 行 137：`flutter test test/runtime/desktop_thread_artifact_service_test.dart`。覆盖 artifact 快照隔离、历史文件拒绝、跨 thread 文件不可见 |
|
||||
| `test/runtime/acp_endpoint_paths_test.dart` | 4 | 覆盖 bridge endpoint 路径解析、拒绝 OpenClaw gateway 路径作为 ACP base——直接防御 README 中的 "invalid handshake" 和 endpoint 混乱 |
|
||||
|
||||
**结论：124 个测试全部有效且为核心回归资产，不可清理。**
|
||||
|
||||
---
|
||||
|
||||
## 二、重要辅助测试（与 README 验收标准间接对齐）— 70 个
|
||||
|
||||
这些测试覆盖 README 验收标准中的关键行为，但不直接测试 5 并发场景。
|
||||
|
||||
| 文件 | 测试数 | 覆盖点 |
|
||||
|------|--------|--------|
|
||||
| `test/runtime/app_controller_thread_workspace_binding_test.dart` | 24 | 测试污染清理、workspace SHA 验证、thread binding 完整性——防御 artifact 串到旧 thread（对应 README 验收标准：当前任务 artifact 不展示旧 run 文件） |
|
||||
| `test/runtime/assistant_connection_state_test.dart` | 17 | 连接状态解析、bridge readiness 判断、gateway capability 检测——对应 README 验收标准中的 "不出现 GATEWAY_CONNECT_FAILED" |
|
||||
| `test/runtime/bridge_runtime_cleanup_test.dart` | 6 | Bridge endpoint 固定、token 作用域——防御 endpoint 漂移导致 "ACP_HTTP_CONNECTION_CLOSED" |
|
||||
| `test/runtime/runtime_controllers_settings_account_test.dart` | 10 | 账号同步、bridge token 管理、managed bridge contract——防御 README 中的 auth failure 场景 |
|
||||
| `test/runtime/gateway_profile_cleanup_test.dart` | 3 | Gateway profile 归一化、token 清理——防御 profile 残留导致的连接错误 |
|
||||
| `test/runtime/gateway_runtime_bridge_skills_test.dart` | 2 | Skill 加载走 bridge 不走 legacy gateway connect——对应 README 验收标准中的任务隔离 |
|
||||
| `test/runtime/assistant_archived_tasks_test.dart` | 2 | 归档任务恢复——影响多任务管理体验 |
|
||||
| `test/runtime/assistant_model_display_test.dart` | 2 | 模型显示解析——影响 gateway 模式下的 UI 正确性 |
|
||||
| `test/features/assistant/assistant_artifact_sidebar_test.dart` | 5 | Artifact 侧栏刷新、OpenClaw no-artifact 空态、陈旧文件阻塞——直接对应 README 验收标准中的 "当前任务没有 artifact 时显示明确空态，不显示旧 run 文件" |
|
||||
|
||||
**结论：70 个测试全部有效，覆盖 README 验收标准的防御面，不可清理。**
|
||||
|
||||
---
|
||||
|
||||
## 三、UI 行为验证测试 — 52 个
|
||||
|
||||
这些测试验证 UI 组件的渲染和行为正确性，属于 widget test 范畴。即使不直接测试 gateway 逻辑，它们保证用户界面不退化。
|
||||
|
||||
| 文件 | 测试数 | 评估 |
|
||||
|------|--------|------|
|
||||
| `test/features/assistant/assistant_lower_pane_test.dart` | 13 | 有效：provider 下拉、execution target 切换、composer 状态、发送按钮状态。覆盖 gateway 模式下的 UI 交互 |
|
||||
| `test/features/assistant/assistant_task_progress_bar_test.dart` | 10 | 有效：running/queued/syncing/error 各状态显示。对应 README 中 "5 个任务应进入 running 或完成态" 的 UI 呈现 |
|
||||
| `test/features/settings/settings_account_panel_test.dart` | 9 | 有效：登录表单、MFA、sync 按钮状态。auth 流程的 UI 正确性 |
|
||||
| `test/features/assistant/assistant_connection_status_test.dart` | 7 | 有效：连接状态 UI 展示、gateway 就绪判断 |
|
||||
| `test/features/desktop/desktop_input_handler_test.dart` | 7 | 有效：键盘映射、坐标归一化。远程桌面功能 |
|
||||
| `test/features/app/sidebar_navigation_task_status_test.dart` | 5 | 有效：侧栏任务状态 chip（running/queued/finished/paused）。对应多任务管理 UI |
|
||||
| `test/features/assistant/assistant_page_session_binding_test.dart` | 5 | 有效：session 隔离 UI、消息不跨 session 显示。对应 README 的 task 隔离 |
|
||||
|
||||
**结论：52 个全部有效，覆盖 UI 层的正确性和体验。**
|
||||
|
||||
---
|
||||
|
||||
## 四、轻量功能性测试 — 18 个
|
||||
|
||||
这些测试覆盖小范围的功能逻辑，测试体量小但验证了真实生产路径。
|
||||
|
||||
| 文件 | 测试数 | 评估 |
|
||||
|------|--------|------|
|
||||
| `test/features/desktop/desktop_client_test.dart` | 5 | 有效：WebRTC 媒体流管理、ICE 连接状态 |
|
||||
| `test/features/settings/settings_about_bridge_metadata_test.dart` | 5 | 有效：bridge 版本/地址/状态展示 |
|
||||
| `test/features/settings/settings_archived_tasks_panel_test.dart` | 4 | 有效：归档任务面板渲染 |
|
||||
| `test/features/assistant/assistant_attachment_payloads_test.dart` | 3 | 有效：inline attachment 构建。对应 sendChatMessage 的附件功能 |
|
||||
| `test/runtime/file_store_support_test.dart` | 3 | 有效但轻量：chmod 平台判断。无外部依赖，维护成本极低 |
|
||||
| `test/features/app/app_shell_surface_test.dart` | 2 | 有效：App shell 基础渲染。Smoke test |
|
||||
| `test/features/assistant/assistant_task_model_cleanup_test.dart` | 2 | 有效：session key 精确匹配、fallback 标题 |
|
||||
| `test/runtime/go_runtime_dispatch_desktop_client_test.dart` | 1 | 有效但极轻量：dispatch resolver 单测 |
|
||||
|
||||
**结论：18 个全部有效，测试体积小、维护成本低、无清理必要。**
|
||||
|
||||
---
|
||||
|
||||
## 五、移动端平台测试 — 10 个
|
||||
|
||||
| 文件 | 测试数 | 评估 |
|
||||
|------|--------|------|
|
||||
| `test/features/mobile/mobile_assistant_page_test.dart` | 5 | 有效：mobile shell 渲染、composer 展示 |
|
||||
| `test/features/mobile/mobile_settings_page_test.dart` | 5 | 有效：mobile settings 页面渲染 |
|
||||
|
||||
**结论：10 个全部有效。虽然当前主力桌面端，但移动端代码路径仍存在且可能未来激活，保留。**
|
||||
|
||||
---
|
||||
|
||||
## 六、轻量配置/展示测试 — 4 个
|
||||
|
||||
| 文件 | 测试数 | 评估 |
|
||||
|------|--------|------|
|
||||
| `test/runtime/ui_feature_manifest_desktop_surface_test.dart` | 1 | 有效但轻量：desktop feature flag 解析 |
|
||||
| `test/runtime/ui_feature_manifest_mobile_surface_test.dart` | 1 | 同上 mobile 版本 |
|
||||
| `test/features/settings/settings_about_panel_test.dart` | 1 | 有效：about 面板渲染 |
|
||||
| `test/features/settings/settings_remote_desktop_panel_test.dart` | 1 | 有效：远程桌面配置面板 |
|
||||
|
||||
**结论：4 个全部有效，维护成本接近零。**
|
||||
|
||||
---
|
||||
|
||||
## 七、集成测试 — 2 个
|
||||
|
||||
| 文件 | 测试数 | 评估 |
|
||||
|------|--------|------|
|
||||
| `integration_test/desktop_navigation_flow_test.dart` | 1 | 有效：桌面端导航流程。需 IntegrationTestWidgetsFlutterBinding |
|
||||
| `integration_test/desktop_settings_flow_test.dart` | 1 | 有效：设置页面流程 |
|
||||
|
||||
**结论：2 个全部有效。集成测试启动成本高但覆盖端到端流程，不可替代。**
|
||||
|
||||
---
|
||||
|
||||
## 总表
|
||||
|
||||
| 分类 | 文件数 | 测试数 | 判定 |
|
||||
|------|--------|--------|------|
|
||||
| 核心回归（直接对齐 README） | 4 | 124 | ✅ 全部有效 |
|
||||
| 重要辅助（间接对齐 README 验收标准） | 9 | 70 | ✅ 全部有效 |
|
||||
| UI 行为验证 | 7 | 52 | ✅ 全部有效 |
|
||||
| 轻量功能性测试 | 8 | 18 | ✅ 全部有效 |
|
||||
| 移动端平台测试 | 2 | 10 | ✅ 全部有效 |
|
||||
| 轻量配置/展示 | 4 | 4 | ✅ 全部有效 |
|
||||
| 集成测试 | 2 | 2 | ✅ 全部有效 |
|
||||
| **合计** | **36** | **280**¹ | **0 个可清理** |
|
||||
|
||||
¹ 实际统计为 280 个 `test()`/`testWidgets()` 调用，与用户报告的 290 个有 10 个偏差，可能来自参数化测试展开或多出来的 group/setUp 计数。
|
||||
|
||||
---
|
||||
|
||||
## 分析结论
|
||||
|
||||
**290 个测试用例中，0 个是无效的或可以清理的。**
|
||||
|
||||
原因：
|
||||
|
||||
1. **每个测试都覆盖了真实的生产代码路径。** 没有任何测试是测试 dead code、已删除功能的残留、或纯 mock 自循环（mock 只 mock 自己）。
|
||||
|
||||
2. **测试密度合理。** 核心文件 `assistant_execution_target_test.dart`（69 个测试）和 `gateway_acp_client_auth_test.dart`（48 个测试）合计 117 个测试，覆盖的都是 README 中列出的关键回归场景——这恰恰是最高价值的测试。
|
||||
|
||||
3. **widget test 都在验证有意义的 UI 行为。** 没有任何测试是"渲染一个空页面然后 assert 它不为 null"这种低价值测试。
|
||||
|
||||
4. **测试之间的边界清晰。** 没有两个测试在测试完全相同的事情——即使有相似 setup，每个测试的断言路径是独特的。
|
||||
|
||||
5. **轻量测试维护成本极低。** 如 `file_store_support_test.dart`（3 个测试，35 行）、`assistant_task_model_cleanup_test.dart`（2 个测试，24 行）等文件体积小、无外部依赖、几乎不会被重构影响——清理它们节省的维护成本微乎其微，但删除会丢失防御面。
|
||||
|
||||
如果一定要从中挑出"最不关键"的测试（主观判断，不推荐删除），可以考虑：
|
||||
|
||||
| 文件 | 测试数 | 理由 |
|
||||
|------|--------|------|
|
||||
| `test/runtime/file_store_support_test.dart` | 3 | 纯函数式 chmod 平台判断，无 IO/无状态 |
|
||||
| `test/features/settings/settings_remote_desktop_panel_test.dart` | 1 | 单个 widget test，覆盖的远程桌面功能可能尚在早期 |
|
||||
|
||||
**但即使这 4 个测试，也建议保留**——它们不产生维护负担（极短、无 mock、不易碎），删除没有收益。
|
||||
Loading…
Reference in New Issue
Block a user