# VLCode-Lite 全量测试方案（2026-03-14）

## 1. 目标

本方案覆盖 VLCode-Lite 当前几乎全部核心能力，重点验证以下九类问题：

1. 核心文档、说明文、版本说明是否和代码一致。
2. 工作流 JSON、Prompt、DocCenter 路径、版本号是否存在错漏、冲突或漂移。
3. Tool 注册、执行、超时、状态回写是否可靠。
4. 工作流引擎能力是否完整，尤其是并行、暂停/恢复、从节点重跑、直接调用 Tool。
5. 主界面、工作流编辑器、元数据视图中的按钮与常见交互是否合理。
6. 前后端同步、SSE 广播、多窗口状态同步是否一致。
7. 自动弹出的对话消息、流式输出、工作流内部信息是否完整可见。
8. 常见用户交互是否顺手，哪里该优化。
9. 最重要的三条主场景：
   A. 从长文本生成 VL 项目、Meta 可视化、再编译。
   B. 对现有项目做 debug / 调整，简单问题走 Agent，复杂问题走 Meta + Workflow。
   C. 用 Meta + ID 生成测试工作流，自动跑、自动评估、自动闭环修复。

## 2. 今晚测试分层

### A. 静态一致性层

目的：先排除“文档、配置、工作流本体就错了”的低级问题。

执行：

- `node scripts/sync-versions.js`
- `node scripts/sync-doc-paths.js`
- `node scripts/sync-workflow-docs.js`
- `node test-workflow-seed-sync.js`
- 解析所有 `.vl-code/workflows/*.json` 与 `public/seed-workflows/*.json`

通过标准：

- 版本 dry-run 为 0 变更。
- Doc path dry-run 为 0 变更。
- DocCenter dry-run 全部 `unchanged`。
- 项目工作流与 seed 工作流一一一致。
- 全部 JSON 可解析。

### B. 模块与工具层

目的：验证工具注册、路由导出、核心模块装配、云端鉴权、编译结果处理等基础设施。

执行：

- `node test-modules.js`
- `node test-cloud-auth.js`
- `node test-dynamic-port.js`
- `node test-llm-provider-selection.js`
- `node test-workspace-create-project-route.js`
- `node test-import-clears-project-targets.js`
- `node test-project-context.js`
- `node test-project-profile-theme-seeding.js`
- `node test-empty-window-config.js`

覆盖点：

- 34+ tools 注册与 schema 暴露。
- Workspace 创建/切换/空窗口。
- 端口动态选择。
- Cloud 登录态安全脱敏。
- 项目骨架种子写入。

### C. 工作流引擎层

目的：验证工作流规范、运行链路、分支循环、文件写入、节点状态与 Tool 扩展。

执行：

- `node test-workflow-executor.js`
- `node test-workflow-executor-json-repair.js`
- `node test-workflow-json-guard.js`
- `node test-workflow-file-adapter.js`
- `node test-workflow-read-files.js`
- `node test-workflow-run-tool-step.js`
- `node test-workflow-status-tools.js`
- `node test-tool-workflow-state-sync.js`
- `node test-workflow-section-constraints.js`
- `node test-workflow-section-sequencing.js`
- `node test-workflow-service-filter-constraints.js`
- `node test-workflow-provider-pass-through.js`
- `node test-workflow-parallel-codegen.js`

重点检查：

- `Tool_*` 节点可直接打到本地 ToolRegistry。
- `pause / resume / executeFrom` 真能工作，不只是 UI 假按钮。
- 并行分支失败不会污染兄弟分支。
- `readFiles` 会注入到 LLM 上下文。
- 生成/调整/修复类工作流能真正落盘。

### D. 调整与编译层

目的：覆盖现有代码调整、编译、修复闭环。

执行：

- `node test-adjust-workflows.js`
- `node test-adjust-workflow-execution.js`
- `node test-compile-request-shape.js`
- `node test-compile-done-event.js`
- `node test-compile-report-persistence.js`
- `node test-vl-compile-warnings.js`
- `node test-compile-fix-workflow.js`
- `node test-orchestrator-fix-skill.js`

重点检查：

- `add-page / add-service / theme-customize / incremental-update` 路径正确。
- 编译 warning 不应误判成 hard fail。
- `.vl-code/last-compile.json` 必须稳定落盘。
- `/debug`、`/fix` 应优先进入正确工作流。

### E. 自动测试管线层

目的：验证 Meta 驱动测试生成、Playwright 执行、结果评估与修复建议。

执行：

- `node test-autotest-sdk-provider.js`
- `node test-autotest-metadata-selector-preference.js`
- `node test-autotest-nav-selector-fix.js`
- `node test-autotest-pagination-case-filter.js`
- `node test-autotest-runner-navigation.js`
- `node test-autotest-strict-vlid-fill.js`
- `node test-autotest-vlid-resolution.js`

重点检查：

- 选择器优先走 metadata / `vlid`。
- 导航步骤自动补全。
- 不可见分页控件会被剔除。
- Playwright 跳转与 reload 逻辑可靠。

### F. 前端视图与交互层

目的：验证主界面附属视图、SSE 映射、状态展示与多运行会话隔离。

执行：

- `node test-workflow-editor.js`
- `node test-metadata-viewer.js`

重点检查：

- Workflow Editor 可区分多次运行、`clientRunToken`、`runID`。
- 暂停态、重跑态、checkpoint 状态能正确映射。
- Metadata Viewer 对旧版 Meta 兼容。

## 3. 主场景测试矩阵

### 场景 A：长文本生成项目 → Meta → 编译

自动化基础：

- `test-vl-generate.js`
- `test-workflow-parallel-codegen.js`
- `test-workspace-create-project-route.js`
- 编译相关 4 个测试

今晚人工补跑：

1. 在测试项目目录选择一个空项目或新建 `*Test` 项目。
2. 输入长文本需求，分别走：
   - 普通对话生成
   - `parallel-codegen`
   - `meta-direct-codegen`
   - `3-file/6-file/9-file` 典型生成链
3. 打开 Meta Viewer 检查：
   - app / section / service / database / theme 结构完整
   - 连线与引用关系正确
4. 立即编译，确认：
   - compile SSE 完整
   - warning / error 分类正确
   - preview URL 落盘

### 场景 B：现有项目 debug / 调整

自动化基础：

- `test-adjust-workflows.js`
- `test-adjust-workflow-execution.js`
- `test-orchestrator-fix-skill.js`
- `test-tool-workflow-state-sync.js`

今晚人工补跑：

1. 对现有测试项目提出简单 bug 修复，确认 Agent 直接走修复路径。
2. 对较大调整走 `VLAdjust`：
   - add page
   - add service
   - theme customize
   - general incremental update
3. 检查 Meta 是否作为中间事实源参与调整。
4. 检查每一步是否有暂停点、审核点、可重跑点。

### 场景 C：Meta + ID 生成测试工作流并闭环

自动化基础：

- 全部 `test-autotest-*`
- `test-workflow-run-tool-step.js`
- `test-workflow-status-tools.js`

今晚人工补跑：

1. 从 Meta 提取页面、元素、服务关系。
2. 生成测试用例与测试工作流。
3. 执行自动测试。
4. 检查失败报告是否可映射回具体页面/控件/服务。
5. 用修复工作流回写，再复测一次。

## 4. 按钮与交互专项检查清单

以下项目当前自动化覆盖不完整，今晚建议人工点一遍：

- 主界面 `Compile`、`Flow`、`Preview`、`Cloud`、`Settings`。
- 左侧文件树展开/切换/右键菜单。
- 工作流编辑器 `Run / Pause / Resume / Abort / Rerun From`。
- 主窗口与副窗口职责分工：
  - 主窗口负责聊天、日志、编译信息。
  - 副窗口负责 Workflow DAG / Metadata Viewer。
- Pause 节点弹出的 approve / cancel 操作。
- 流式输出中：
  - token
  - thinking
  - tool_use
  - tool_result
  - file_written
  - checkpoint
  - pause/resumed
  是否都能看到，且不丢失。

## 5. 今晚推荐执行顺序

1. 先跑 `node scripts/sync-versions.js`
2. 再跑 `node scripts/sync-doc-paths.js`
3. 再跑 `node scripts/sync-workflow-docs.js`
4. 然后跑 `node scripts/run-node-tests.js`
5. 再做三条主场景的人工补跑
6. 每完成一类修复就单独提交一次

## 6. 版本管理与提交策略

建议按以下粒度提交，不要把所有东西揉成一个提交：

1. `workflow/runtime`: 工作流 JSON、执行器兼容、seed 对齐。
2. `tests`: 新增或修正自动化测试、跑批脚本。
3. `docs`: 测试方案、审计报告、核心说明修订。
4. `ui`: 前端交互、按钮、消息展示、多窗口同步修复。
5. `scenario-fixes`: 跑主场景时发现的真实问题。

每次提交都带：

- 影响范围
- 风险点
- 对应测试命令
- 若改了文档，明确说明改了哪些文档

## 7. 本轮已完成结果

截至 2026-03-14，本仓库已完成以下检查：

- `node scripts/sync-versions.js`：0 变更
- `node scripts/sync-doc-paths.js`：0 变更
- `node scripts/sync-workflow-docs.js`：DocCenter dry-run 全部 `unchanged`
- `node scripts/run-node-tests.js`：`42/42` 通过

本轮已额外补强：

- 新增统一测试入口：`scripts/run-node-tests.js`
- 新增工作流 seed 漂移测试：`test-workflow-seed-sync.js`
- 补上 `3-file-codegen` 的执行级回归
- 执行器兼容 `Component_ClearExisting`
- 修复 `test-workspace-create-project-route.js` 在 Node 25 下的监听时序问题

## 8. 当前仍建议人工确认的点

以下问题更适合今晚真人点一次界面确认：

- 主界面按钮语义是否真的合理
- 聊天区和副窗口的信息分工是否清楚
- 编译日志、工作流日志、Agent 对话是否有重复或缺失
- 多窗口真正同时打开时，UI 是否存在闪烁、错绑、状态覆盖
- Cloud 登录态切换时，主界面提示是否够明确