# ai-test

**Repository Path**: mingwuda/ai-test

## Basic Information

- **Project Name**: ai-test
- **Description**: ai测试工具
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: codex/devloop-remote-ai-bridge
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-01
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 工程协作管理服务（Node.js）

一个纯 Node.js Web 服务，用于管理需求目录、需求流转、AI 自动测试、DevLoop 开发闭环和 AI Data Agent 数据开发 POC。平台支持 Gemini / OpenCode Serve 等模型引擎，覆盖从需求录入、用例生成与执行、开发实现、数据 SQL 生成验证到历史报告导出的多类 AI 工程协作场景。

## 1. 主要能力
- 需求管理：
  - 提供独立的需求管理页面
  - 支持新增、编辑、删除、查询需求
  - 支持上传需求文档并自动转换为 Markdown 后回填
- 用例管理：按需求查看、手工新增、编辑、删除
- AI 生成用例：
  - 默认走模型引擎（Gemini CLI / OpenCode Serve）
  - 用例数自动按需求复杂度估算
  - 同一需求二次生成会覆盖该需求下历史 AI 用例
  - 支持异步生成任务与进度查询（含流式日志）
  - 支持本地 Skill 包与上传 Skill Zip（含 `SKILL.md` + 依赖文件）
- 批量执行：
  - 执行链路固定为单机单并发（稳定优先）
  - 新增 `agent-gemini` 模式：由 Windows Node.js Agent 在本地拉任务并执行
  - 新增 `agent-script` 模式：先人工审核脚本，再由 Windows Agent 执行审核通过脚本
    - Gemini / OpenCode Serve 预设当前都统一生成并执行 Playwright 脚本
  - 默认 20 分钟超时（可配置）
  - 支持“快速执行模式”（默认开启，约束精简输出，但不强制指定模型）
  - 执行时主技能可选，不选也可直接执行
  - 样例导入用例（`sample-import`）禁止进入执行链路
  - 保存每条用例的执行状态、报告、Gemini 输出日志
  - 支持查看单条用例执行时的提示词与 Gemini 原始返回，便于排查
- 历史批次：
  - 查看历史执行批次及明细
  - 勾选多个批次导出真正 `.docx` 汇总报告
- 网络自检：
  - 检查网络环境变量、当前引擎真实调用
- DevLoop 开发闭环：
  - 需求澄清：AI 自动分析需求，生成验收标准，识别歧义点
  - 任务拆分：AI 学习代码结构，自动拆分开发任务
  - 开发流程管理：支持完整的开发、构建部署流水线、测试、诊断、修复、评审流程
  - 支持“用户本地 WebSocket Agent”：DevLoop 服务端负责任务编排，AI 命令在用户本机执行
  - 阶段出口检查：确保每个阶段完成质量
  - 人工干预机制：在必要时提供人工调整能力
  - 支持 OpenCode Serve 和 Gemini 双引擎

## 1.1 AI Data Agent POC

AI Data Agent POC 演示面向员工域的数据开发闭环：

```text
Requirement -> Requirement Plan -> SQL -> Doris execution -> repair loop -> rule tests -> final run trace
```

本地页面：

```text
http://127.0.0.1:8012/ai-data-agent.html
```

主页入口：

```text
http://127.0.0.1:8012/
```

主要 API：

- `POST /api/ai-data-agent/runs`
- `GET /api/ai-data-agent/runs/:runId`
- `GET /api/ai-data-agent/runs`

真实 Doris 演示环境变量：

- `DORIS_HOST`
- `DORIS_PORT`
- `DORIS_USER`
- `DORIS_PASSWORD`
- `DORIS_DATABASE`

可选 sqlglot 服务变量：

- `SQLGLOT_SERVICE_URL`：未设置时使用内置简单 SELECT 回退转换；设置后调用 Flask sqlglot 服务。

补充文档：

- 设计说明：[docs/superpowers/specs/2026-05-07-ai-data-agent-poc-design.md](docs/superpowers/specs/2026-05-07-ai-data-agent-poc-design.md)
- 实施计划：[docs/superpowers/plans/2026-05-07-ai-data-agent-poc.md](docs/superpowers/plans/2026-05-07-ai-data-agent-poc.md)
- Demo 用例：[docs/ai-data-agent-demo-cases.md](docs/ai-data-agent-demo-cases.md)

## 1.2 架构图
![AI 工程协作服务总架构图](docs/images/architecture-overview.svg)

Mermaid 源码：

```mermaid
flowchart LR
  user["用户 / 测试 / 开发 / 数据同学"]
  web["Web 工作台<br/>public/*.html + public/*.js"]
  server["Node.js 服务端<br/>src/server.js"]
  prompt["提示词配置<br/>/api/prompt-config"]
  db["本地状态存储<br/>data/app.sqlite"]
  artifacts["执行产物<br/>data/artifacts/"]
  skill["Skill 包<br/>Zip / SKILL.md / 依赖文件"]
  cli["模型引擎<br/>Gemini CLI / OpenCode Serve"]
  agent["Windows Agent<br/>agent/index.js"]
  playwright["Playwright 执行器<br/>plan / script runner"]

  user --> web
  web --> server
  web --> prompt
  prompt --> server

  server --> db
  server --> artifacts
  skill --> server

  server --> cli
  server --> playwright
  server --> agent
  agent --> cli
  agent --> playwright
  agent --> artifacts

  cli -. 生成用例 / 试跑探测 / 草稿生成 .-> server
  playwright -. 脚本测试 / 执行结果 / 截图 .-> server
  server -. 任务进度 / 日志 / 报告 .-> web
```

## 1.3 DevLoop 架构图（WebSocket Agent 模式）
![DevLoop WebSocket Agent 架构图](docs/images/devloop-websocket-agent-architecture.svg)

Mermaid 源码：

```mermaid
flowchart LR
  subgraph userB_zone["用户 B 本地环境"]
    userB["开发者 B"]
    agentB["WebSocket Agent B<br/>agent/ws-client.js"]
    cliB["本地 AI CLI<br/>Gemini / OpenCode"]
    repoB["本地代码仓库"]
  end

  subgraph server_zone["Node.js 服务端"]
    web["DevLoop 工作台<br/>public/devloop.html"]
    controller["DevLoop 控制器<br/>src/server/controllers/dev-loop-controller.js"]
    service["DevLoop 服务<br/>src/server/services/dev-loop-service.js"]
    handlers["阶段处理器<br/>src/server/services/dev-loop-stage-handlers/"]
    bridge["WebSocket 桥接器<br/>src/server/services/ai-websocket-bridge.js"]
    registry["Agent 注册表<br/>按 ownerId 隔离"]
    store["状态管理<br/>src/server/services/state-store.js"]
  end

  subgraph userA_zone["用户 A 本地环境"]
    userA["开发者 A"]
    agentA["WebSocket Agent A<br/>agent/ws-client.js"]
    cliA["本地 AI CLI<br/>Gemini / OpenCode"]
    repoA["本地代码仓库"]
  end

  userB -->|"访问工作台<br/>携带用户 B Token"| web
  userA -->|"访问工作台<br/>携带用户 A Token"| web

  web -->|"请求数据 / 阶段操作"| controller
  controller -->|"按 Token 解析 ownerId"| service
  service -->|"阶段推进"| handlers
  service -->|"AI 执行请求"| bridge
  service -->|"读写用户隔离状态"| store
  bridge -->|"注册 / 心跳 / 状态"| registry

  bridge -. "Token 认证 / ownerId 路由 / AI 执行请求" .-> agentB
  bridge -. "Token 认证 / ownerId 路由 / AI 执行请求" .-> agentA
  agentB -. "AI 执行结果" .-> bridge
  agentA -. "AI 执行结果" .-> bridge

  agentB --> cliB
  agentB --> repoB
  agentA --> cliA
  agentA --> repoA

  handlers -. "阶段结果" .-> service
  bridge -. "执行结果" .-> service
  service -. "状态变更" .-> controller
  controller -. "响应数据" .-> web

  style userA_zone fill:#fffde7,stroke:#d6c35a
  style userB_zone fill:#fffde7,stroke:#d6c35a
  style server_zone fill:#fffde7,stroke:#d6c35a
```

说明：
- 管理台负责需求、用例、脚本审核、历史批次与提示词配置。
- 服务端负责路由编排、任务状态管理、脚本生命周期、报告汇总与数据持久化。
- 模型引擎主要用于生成测试用例、试跑探测、脚本草稿与部分执行辅助。
- Playwright 是当前主执行链路，负责脚本测试、正式执行、截图和浏览器交互。
- Windows Agent 主要用于测试用例执行页中需要本机环境执行的 `agent-gemini` / `agent-script` 模式。
- **用户本地 WebSocket Agent**：用于 DevLoop 中的开发、诊断、修复阶段，把 AI CLI 命令放到用户本机执行。
- **多用户隔离机制**：WebSocket Agent 连接时通过 Token 绑定 ownerId，服务端按 ownerId 过滤 Agent 列表，确保用户只能使用自己本地连接的 Agent，避免跨用户串操作。
- DevLoop 系统负责 AI 辅助开发全流程，包括需求澄清、任务拆分、开发实现、构建部署流水线、测试诊断等阶段。

## 2. 项目结构
```txt
ai-test/
  public/                  # 前端页面（需求管理、AI 测试、DevLoop、AI Data Agent 等工作台）
    app.js                 # AI 测试工作台主流程与事件绑定
    devloop.html           # DevLoop 工作台页面
    devloop.js             # DevLoop 工作台主流程与事件绑定
    devhistory.html        # DevLoop 历史页面
    devhistory.js          # DevLoop 历史页面逻辑
    devtask.html           # DevLoop 任务页面
    devtask.js             # DevLoop 任务页面逻辑
    js/
      state.js             # 前端共享状态、DOM 缓存、CLI 预设
      api.js               # API 请求与提示工具
      script-review.js     # 脚本审核、试跑、测试、优化
      job-view.js          # 执行任务列表、详情、调试面板
      generation-status.js # 用例生成进度与自检结果渲染
      case-selection.js    # 用例批量选择、导入导出辅助
  agent/                   # Windows Node.js Agent（本地执行器）
  src/
    server.js              # 服务启动入口与依赖装配
    server/
      app-services.js      # 应用服务组装层，导出状态、任务、脚本、执行等服务能力
      config.js            # 路径、端口、默认模板、CLI 配置
      routes.js            # HTTP 路由编排、CORS、静态资源 fallback
      controllers/
        system-controller.js       # 健康检查、版本、提示词配置、Skill、自检
        agents-controller.js       # Agent 注册、心跳、认领任务、日志与结果回传
        requirements-controller.js # 需求、研发任务、研发批次
        cases-controller.js        # 用例、脚本生命周期、用例生成任务
        executions-controller.js   # 执行批次、停止、重跑、历史报告
        user-cases-controller.js   # 用户用例 Excel 导入导出
        dev-loop-controller.js     # DevLoop 核心控制器
      services/
        state-store.js             # 本地状态、运行时任务 Map、ID/时间工具
        prompt-service.js          # 提示词配置与模板渲染
        dev-job-service.js         # 研发任务拆分与研发批次执行
        script-service.js          # 脚本状态、草稿/探测/优化提示词与解析
        job-tracker-service.js     # 异步生成/脚本任务的内存进度跟踪
        case-generation-service.js # AI 用例生成主流程
        execution-service.js       # 用例执行编排、批次构建、Agent 任务载荷
        execution-helper-service.js # 执行报告、执行提示词与 Playwright 计划辅助
        network-service.js         # Gemini / OpenCode / Playwright MCP 自检
        sample-service.js          # 样例导入、版本读取、需求/用例 Markdown 解析
        user-case-import-service.js # 用户用例 Excel 导入辅助
        common-utils.js            # 通用文本与输出合并工具
        dev-loop-service.js        # DevLoop 核心服务
        dev-loop-stage-handlers/   # DevLoop 阶段处理器
          index.js                 # 阶段处理器入口
          pipeline-handler.js      # 构建部署流水线阶段处理器
          develop-handler.js       # 开发阶段处理器
          diagnose-handler.js      # 诊断阶段处理器
          done-handler.js          # 完成阶段处理器
          fix-handler.js           # 修复阶段处理器
          review-handler.js        # 评审阶段处理器
          split-handler.js         # 任务拆分阶段处理器
          test-handler.js          # 测试阶段处理器
          default-handler.js       # 默认阶段处理器
          mock-tool-adapter.js     # 调试模式工具适配器
      http-utils.js        # JSON / 文本响应与请求体解析
      static-files.js      # 静态资源服务
    modules/
      gemini.js            # CLI 调用与报告解析
      case-utils.js        # 用例生成/解析/规范化工具
      skill-pack.js        # Skill Zip 上传、解析、执行引擎
      report-docx.js       # 历史汇总与 docx 构建
      opencode-api.js      # OpenCode API 调用
      opencode-sdk.js      # OpenCode SDK 封装
      opencode-serve-manager.js # OpenCode Serve 管理
      agent-browser-runner.js # Agent 浏览器运行器
      playwright-executor.js # Playwright 执行器
      playwright-script-runner.js # Playwright 脚本运行器
      requirement-import.js # 需求导入工具
  data/app.sqlite          # SQLite 持久化数据（首次启动会从 data/db.json 迁移）
  VERSION                  # 当前版本号（格式：v主版本-发布日期）
  require.md               # 样例需求文件
  caseAll.md               # 样例用例文件
  docs/dev-loop-contract.md # DevLoop 契约文档
```

### 2.1 模块化边界
- `src/server.js` 只负责启动服务和组装依赖，避免继续堆叠路由细节。
- `src/server/app-services.js` 只负责组装 services，并统一导出给 controllers 使用。
- `src/server/routes.js` 负责统一 CORS、异常处理、controller 分发和静态资源 fallback。
- `src/server/controllers/*` 按业务领域承载 API 具体实现，主要负责请求解析和响应。
- `src/server/services/*` 承载状态、生成、脚本、执行、自检等服务逻辑，让控制器保持薄层。
- `src/server/config.js` 集中管理默认提示词模板、路径常量和 CLI 识别逻辑。
- `public/app.js` 保留 AI 测试工作台主流程；独立功能放入 `public/js/*`，按 `ai-test.html` 中的脚本顺序加载。
- `public/images/` 为需求内容中的运行时图片资源目录，默认不纳入 Git。

## 3. 环境要求
- Node.js 22.5+（当前存储层使用 Node 内置 `node:sqlite`）
- 已安装可用的 Gemini CLI（`gemini`）
- 如需使用 OpenCode Serve，请在本机启动服务并配置 `OPENCODE_SERVE_BASE_URL`
- 如需使用页面上的 OpenCode Serve 重启能力，可按需配置 `OPENCODE_SERVE_RESTART_COMMAND`；未配置时默认执行 `opencode serve --port <OPENCODE_SERVE_BASE_URL 端口>`
- 如需使用 OpenCode Serve 执行浏览器类用例，还需要在 OpenCode 环境中安装并启用 `chrome-devtools` 的 MCP Server；否则模型可能无法打开浏览器，或报 `Tool execution denied by policy`
- macOS / Linux / Windows（仅命令略有差异）

### Windows 额外说明
- 命令建议使用双引号包裹 Prompt 占位符，例如：
  - `MODEL_CLI_CMD=gemini --yolo -p "{{PROMPT}}"`
- Skill Zip 解压在 Windows 下会自动使用 PowerShell `Expand-Archive`，无需手工安装 `unzip`
- Skill 执行引擎支持 `python` / `python3` / `py` / `python.exe` / `py.exe`
- 若上传 Skill 出现 `spawn EPERM`：系统会自动回退 `powershell.exe -> pwsh.exe -> tar`，建议确认至少一种可执行

## 4. 安装与启动
### 4.1 安装服务端
在部署机器上安装依赖并启动 Web 服务：

```bash
cd /Users/xxxx/code/ai-test
npm install
npm run start
```

默认监听：
- `HOST=127.0.0.1`
- `PORT=8012`

如需修改端口：

```bash
HOST=127.0.0.1 PORT=8013 npm run start
```

服务启动成功后，默认 Web 根地址为 `http://127.0.0.1:8012/`。

如需生成不包含后端源码目录的运行入口，可在开发机执行：

```bash
npm run build:server
```

构建产物为 `dist/server.cjs`。目标机器运行时使用：

```bash
npm run start:dist
```

也可以一键生成发布用 Zip：

```bash
npm run package:release
```

输出文件为 `release/ai-engineering-copilot.zip`。该包不包含 `src/`、`scripts/`、`agent/` 和 `.git/`，解压后进入目录执行 `npm run start` 即可启动。

最小部署内容：
- `dist/server.cjs`
- `public/`
- `prompt-templates/dev-loop/`（DevLoop AI Prompt 模板，可直接编辑）
- `node_modules/`
- `package.json`
- `.env.local`（按环境配置）
- `data/`（用于 `app.sqlite`、执行产物和 Skill 包）

DevLoop Prompt 模板默认从 `prompt-templates/dev-loop/` 读取；如需放到其他目录，可通过 `DEV_LOOP_PROMPT_TEMPLATE_DIR` 指定。

### 4.2 服务端环境变量
建议在项目根目录创建 `.env.local`。服务启动时会自动加载 `.env.local` 与 `.env`。

```bash
MODEL_CLI_CMD=gemini --yolo -p {{PROMPT}}
# 兼容旧变量名（若已配置可继续使用）
GEMINI_CLI_CMD=gemini --yolo -p {{PROMPT}}

GENERATE_CASES_TIMEOUT_MS=600000
GENERATE_CASES_BATCH_SIZE=6
GENERATE_CASES_RETRY=4
GENERATE_CASES_RETRY_BASE_MS=3000

SKILL_RUNTIME_TIMEOUT_MS=60000

# 如需使用 OpenCode Serve
OPENCODE_SERVE_BASE_URL=http://127.0.0.1:4096
# 可选：自定义页面“重启 OpenCode Serve”按钮执行的命令
# OPENCODE_SERVE_RESTART_COMMAND=opencode serve --port 4096

# Playwright 浏览器启动优先级：
# 1) PLAYWRIGHT_EXECUTABLE_PATH
# 2) PLAYWRIGHT_BROWSER_CHANNEL
# 3) macOS 下自动尝试系统 Chrome / Chrome for Testing / Edge
# 4) Playwright bundled chromium
PLAYWRIGHT_BROWSER_CHANNEL=chrome
```

如果执行浏览器类任务时报错缺少 Playwright 浏览器，优先配置 `PLAYWRIGHT_EXECUTABLE_PATH` 或 `PLAYWRIGHT_BROWSER_CHANNEL=chrome`；如果没有系统浏览器，再执行 `npx playwright install chromium`。

### 4.3 推荐：用户本地 WebSocket Agent
推荐使用 WebSocket Agent 作为本地 AI 执行方式。它适合服务端部署在共享机器或内网机器上，但 AI CLI、浏览器、项目代码、账号和内部工具都在用户自己电脑上的场景。

WebSocket Agent 的特点：
- 由用户本机主动连接服务端，不需要服务端反向访问用户电脑。
- 连接时通过 Token 绑定 `ownerId`，服务端按用户隔离 Agent 列表。
- DevLoop 的开发、诊断、修复等阶段可以在用户本机调用 Gemini / OpenCode CLI。

#### 4.3.1 配置本地 Agent
在用户本机的项目根目录创建或更新 `.env.agent.local`：

```bash
AGENT_SERVER_BASE_URL=http://127.0.0.1:8012
AGENT_NAME=local-ws-agent-01
AGENT_WS_MODE=1

# 填服务端分配给当前用户的 Agent Token
AI_AGENT_WS_TOKEN=<Agent Token>

# 本机实际可用的 AI CLI 命令
AGENT_MODEL_CLI_CMD=gemini --yolo -p "{{PROMPT}}"
```

Windows 示例：

```bash
AGENT_SERVER_BASE_URL=http://127.0.0.1:8012
AGENT_NAME=win-ws-agent-01
AGENT_WS_MODE=1
AI_AGENT_WS_TOKEN=<Agent Token>
AGENT_MODEL_CLI_CMD=C:\\path\\to\\gemini.exe --yolo -p "{{PROMPT}}"
```

配置文件也可以放在 `agent/.env.agent.local`。Agent 启动时会优先读取 `agent/` 目录下的配置，再读取项目根目录配置。

#### 4.3.2 启动 WebSocket Agent
在用户本机执行：

```bash
npm run start:agent:ws
```

连接成功后可以看到：
- Agent 终端打印 `[agent-ws] connected`
- `GET /api/ai-ws-agents` 返回当前用户的在线 Agent

#### 4.3.3 启动排查
- 终端没有出现 `[agent-ws] connected`：检查 `AGENT_SERVER_BASE_URL` 是否指向服务端地址。
- 401 或反复断开：检查 `AI_AGENT_WS_TOKEN` 是否正确。
- AI 命令找不到：显式配置 `AGENT_MODEL_CLI_CMD`，不要依赖不确定的 PATH。
- Windows 上误用 `@wizard/gemini`：把 `AGENT_MODEL_CLI_CMD` 指向明确的 `gemini.exe` 路径。

相关接口：
- WebSocket：`/ws/ai-agent`
- 在线 Agent 列表：`GET /api/ai-ws-agents`

### 4.4 兼容：轮询 Windows Agent
轮询 Agent 是较早的本地执行方式。新接入 DevLoop 时优先安装和启动 WebSocket Agent。

启动方式：

```bash
npm run start:agent
```

Windows 也可以直接双击：

```bat
agent\start-agent.bat
```

轮询 Agent 的 `.env.agent.local` 示例：

```bash
AGENT_SERVER_BASE_URL=http://127.0.0.1:8012
AGENT_NAME=win-agent-01
AGENT_POLL_INTERVAL_MS=3000
AGENT_HEARTBEAT_INTERVAL_MS=10000
AGENT_MODEL_CLI_CMD=C:\\path\\to\\gemini.exe --yolo -p "{{PROMPT}}"
# 兼容旧变量名（若已配置可继续使用）
AGENT_GEMINI_CLI_CMD=C:\\path\\to\\gemini.exe --yolo -p "{{PROMPT}}"
```

说明：
- `AGENT_MODEL_CLI_CMD` 优先级高于服务端下发的 `geminiCommand`。
- Agent 本地产物目录为 `agent-data/artifacts/<jobId>/<taskId>/`。

相关接口：
- `GET /api/agents`
- `POST /api/agents/register`
- `POST /api/agents/:agentId/heartbeat`
- `POST /api/agents/:agentId/claim-next`
- `POST /api/agents/:agentId/jobs/:jobId/tasks/:taskId/logs`
- `POST /api/agents/:agentId/jobs/:jobId/tasks/:taskId/result`

## 5. 使用流程（推荐）
### 5.1 AI 测试用例使用指导
AI 测试工作台面向“录入需求 -> AI 生成测试用例 -> AI 执行用例 -> 查看报告”的自动测试流程。推荐入口为：

```text
http://127.0.0.1:8012/ai-test.html
```

#### 5.1.1 准备执行环境
开始执行用例前，先确认模型执行方式已经可用：

1. 服务端本机执行
   - 适合服务端机器可以直接访问被测系统、浏览器、账号和网络环境的场景。
   - 可使用 Gemini CLI 或 OpenCode Serve。
   - 如果使用 OpenCode Serve，请确认 `OPENCODE_SERVE_BASE_URL` 已配置并可访问。

2. Windows Agent 执行
   - 适合被测系统只能在 Windows 桌面、本地浏览器或内网环境访问的场景。
   - 在 Windows 机器上启动轮询 Agent：

```bash
npm run start:agent
```

   - 建议在 `.env.agent.local` 中显式配置 `AGENT_MODEL_CLI_CMD`，避免 Agent 误用错误的模型 CLI。

3. 执行模式选择
   - `gemini` / `opencode`：由服务端直接调用 AI CLI 执行用例。
   - `agent-gemini` / `agent-stepwise`：由 Windows Agent 在本机调用 AI CLI 执行用例。
   - `agent-script`：执行已审核通过或已固化的 Playwright 脚本，适合高频回归，不是首次执行的主路径。

#### 5.1.2 新增需求并生成用例
在 AI 测试工作台中新增需求，填写业务背景、入口页面、账号信息、验收点和需要覆盖的测试范围。

也可以直接调用接口创建需求：

- `POST /api/requirements`

如果需求来自文档，可以先打开需求池页面上传文件：

```text
http://127.0.0.1:8012/requirement.html
```

上传入口支持 `.md`、`.txt`、`.docx`、`.xlsx` 和文本型 `.pdf`。系统会把文件转换成 Markdown，并回填到“新增需求”弹窗，人工确认后再保存入库。当前暂不支持 `.doc` 和 `.xls`。

创建需求后，点击“AI 生成用例”。系统会创建异步任务，让 AI 根据需求内容生成结构化测试用例。

- `POST /api/cases/generate/start`
- `GET /api/cases/generate/jobs/:id`

生成规则：
- 生成数量会根据需求复杂度自动估算。
- 同一需求再次生成时，会覆盖该需求下旧的 AI 用例。
- 生成默认超时为 10 分钟，可通过 `GENERATE_CASES_TIMEOUT_MS` 调整。
- 生成后的用例可以在页面弹窗中人工编辑、补充或删除。

#### 5.1.3 选择用例并启动 AI 执行
在“用例管理”中勾选要执行的用例，然后点击执行。核心链路是：系统把用例整理成执行任务和提示词，交给 Gemini、OpenCode 或 Windows Agent，由 AI 按用例步骤真实操作被测系统并返回结果。

执行接口：

- `POST /api/executions`

执行前建议确认：
- 选中的用例不是样例导入用例，样例用例默认不允许执行。
- AI 执行机器可以访问被测系统。
- 登录账号、验证码处理方式、测试数据准备方式已经写在需求或用例中。
- 如果需要浏览器操作，执行机器已具备可用浏览器环境。
- 如果选择 Windows Agent，Agent 列表里能看到在线 Agent。

执行说明：
- 执行时可选择主技能包，不选择也可以执行。
- 执行默认超时为 20 分钟。
- 执行区默认开启“快速执行模式”。
- 执行阶段不再依赖页面填写“被测系统基础地址”，AI 会从需求和用例上下文中读取入口信息。
- 任务详情中可以查看单条用例的执行提示词、AI 原始返回、日志和结果。
- 执行线程池面板仅展示最近 2 次任务，完整记录请到历史页面查看。

#### 5.1.4 查看执行结果
启动执行后，可在执行列表查看批次状态和单条用例结果：

- `GET /api/executions`
- `GET /api/executions/:id`
- `GET /api/executions/:id/report`

重点查看：
- 执行状态：成功、失败、超时、异常中断。
- AI 原始返回：用于判断失败是业务缺陷、环境问题、账号问题还是提示词理解偏差。
- 单条用例日志：用于追踪 AI 实际执行到哪一步。
- 截图、附件或产物：用于人工复核失败现场。

#### 5.1.5 历史批次与报告导出
历史页面用于追踪完整执行记录，并导出 `.docx` 汇总报告。

- `GET /api/executions/history`
- `POST /api/executions/history/report`

报告通常用于：
- 给产品、测试或研发同步本轮测试结论。
- 归档测试批次、失败原因和执行证据。
- 对比多轮执行中的稳定性变化。

#### 5.1.6 可选：脚本化回归
页面探测、生成脚本草稿和脚本审核是辅助能力，适合把已经稳定的 AI 执行路径沉淀成可复用脚本。首次验证需求时，建议优先使用 AI 直接执行用例。

可选接口：
- `GET /api/cases/:id/script`
- `POST /api/cases/:id/script/probe`
- `POST /api/cases/:id/script/generate`
- `PUT /api/cases/:id/script/draft`
- `POST /api/cases/:id/script/approve`

脚本审核通过后：
- 脚本会保存到用例的 `scriptApproved`。
- 若后续执行成功，会自动固化到 `scriptReusable`。
- 选择 `agent-script` 执行模式时，会优先执行已审核通过或已固化的 Playwright 脚本。

#### 5.1.7 常见排查
- AI 执行失败但业务看起来正常：先查看单条用例的 AI 原始返回，确认是否缺少账号、入口、测试数据或断言口径。
- Windows Agent 没有任务：确认 Agent 已启动、服务端地址正确，并且页面选择了 Agent 执行模式。
- Gemini / OpenCode 命令找不到：在服务端或 Agent 的环境变量中显式配置模型 CLI 命令。
- 浏览器无法打开被测系统：确认执行机器网络、代理、证书和登录态，而不是只检查服务端网络。
- 执行结果不稳定：补充更明确的前置条件、测试数据、页面入口和验收标准，再重新生成或编辑用例。

### 5.2 DevLoop 开发闭环使用指导
DevLoop 面向“从需求到开发、构建部署、测试、诊断、修复、验收”的完整闭环。推荐入口为：

```text
http://127.0.0.1:8012/devloop.html
```

#### 5.2.1 首次使用前配置
打开 DevLoop 工作台后，先进入“配置”面板完成这些设置：

1. 生成自动化 Token
   - 点击“自动化 Token”区域的“一键生成 Token”。
   - 该 Token 用于 WebSocket Agent 鉴权，也用于多用户隔离。
   - 多人共用同一服务端时，每个人应使用自己的 Token。

2. 选择 AI 执行位置
   - `服务端本机执行`：AI CLI 在启动 Node 服务的机器上执行。
   - `用户本地 WebSocket Agent`：AI CLI 在用户自己的电脑上执行，适合访问本地代码、账号、浏览器和内部工具。

3. 配置 AI 引擎
   - 当前支持 `Gemini` 和 `OpenCode Serve`。
   - 开发、构建部署、诊断、修复阶段可分别配置 Skill 包和超时时间。
   - 使用 OpenCode Serve 时，建议先确认 `OPENCODE_SERVE_BASE_URL` 可访问。

4. 启动本地 WebSocket Agent（可选）
   如果选择“用户本地 WebSocket Agent”，在用户本机启动：

```bash
npm run start:agent:ws
```

`.env.agent.local` 示例：

```bash
AGENT_SERVER_BASE_URL=http://127.0.0.1:8012
AGENT_NAME=local-ws-agent-01
AGENT_WS_MODE=1
AI_AGENT_WS_TOKEN=<DevLoop 配置页生成的 Token>
AGENT_MODEL_CLI_CMD=gemini --yolo -p "{{PROMPT}}"
```

连接成功后，配置页的“指定 Agent”下拉框会出现对应 `AGENT_NAME`。

#### 5.2.2 创建 DevLoop
在 DevLoop 工作台左侧选择需求后，填写：

- DevLoop 标题
- 项目路径：必须填写本机真实代码仓库路径
- Git/SVN 地址
- Git 分支名称
- 流水线地址
- 健康检查 URL

点击“创建 DevLoop”后，系统会创建一条独立闭环记录。后续阶段状态、产物、日志、反馈和回流原因都会保存到 `data/app.sqlite`。

#### 5.2.3 阶段流程
DevLoop 当前阶段顺序为：

```text
需求澄清 -> 任务拆分 -> 开发实现 -> 构建部署 -> 测试 -> 问题诊断 -> 修复 -> 验收评审 -> 完成
```

1. 需求澄清
   - 点击“AI 需求诊断”。
   - AI 会分析需求、生成验收标准，并识别歧义点。
   - 如果出现澄清 Gate，先在页面回答问题，再继续诊断。
   - 验收标准确认无误后，点击“确认需求澄清并进入任务拆分”。

2. 任务拆分
   - 先点击“学习代码结构”，让 AI 读取项目结构并生成摘要。
   - 再点击“AI 任务拆分”，生成开发任务。
   - 人工确认任务后，点击“确认任务并进入开发”。

3. 开发实现
   - 进入开发阶段后，系统会自动创建 AI 开发任务。
   - 如果开发过程需要人工澄清，页面会显示输入框和提交按钮。
   - 如果 AI 卡住或服务重启导致任务丢失，可使用“人工检查后继续推进”继续当前阶段。
   - 使用 OpenCode Serve 时，系统会尽量复用 session；如果项目路径变更，会重启 Serve 并切换工作目录。

4. 构建部署
   - 进入构建部署阶段后，AI 会基于仓库地址、分支、流水线地址和开发产物调用流水线。
   - 如果配置了调试模式，可用 Mock 成功 / Mock 失败回流模拟阶段结果。
   - 构建部署完成后，确认进入测试阶段。

5. 测试、诊断、修复
   - 测试阶段可执行 AI 测试任务。
   - 测试失败后进入问题诊断，AI 会结合测试报告、开发输出和流水线日志分析原因。
   - 诊断确认后进入修复阶段，AI 根据诊断结论进行修复。
   - 修复完成后进入验收评审。

6. 验收评审
   - 页面提供“不通过原因”输入框，以及“回流”“验收通过”两个按钮。
   - 点击“验收通过”：DevLoop 进入完成阶段。
   - 点击“回流”：必须填写不通过原因，系统会回到开发实现阶段并自动启动 AI 开发。
   - 回流提示词只包含本轮最新不通过原因，不会混入历史人工反馈，也不会把历史开发任务重新带入提示词。

#### 5.2.4 OpenCode Serve 工作目录规则
OpenCode Server API 当前不支持在创建 session 时直接传 `cwd`。因此系统采用以下策略：

- DevLoop 开发阶段会把“项目路径”传给 OpenCode 调用链。
- 调用前系统会查询 OpenCode Serve 的 `/path`。
- 如果当前 Serve 工作目录与 DevLoop 项目路径不一致，系统会重启 OpenCode Serve，并以项目路径作为启动工作目录。
- 重启输出和 AI 执行日志中会显示工作目录，用户可以确认实际目录。

注意：
- OpenCode Serve 是共享服务。同一台机器上多个 DevLoop 如果指向不同项目路径，系统可能会切换 Serve 工作目录。
- 工作目录切换后不会复用旧 session，避免旧 session 指向错误项目。
- Windows 下默认使用 `start /D <项目路径>` 启动可见的 OpenCode Serve 窗口。

#### 5.2.5 回流规则
阶段失败或人工验收不通过时，可回流到较早阶段。常见回流目标是 `develop`：

- 回流会生成 `stage_feedback` 产物。
- 回流会创建反馈处理任务。
- 回流到开发阶段后，系统会自动启动开发 AI。
- 验收评审回流只把本轮“不通过原因”传给开发 AI，避免历史反馈干扰。

#### 5.2.6 常见排查
- 配置页看不到 Agent：确认本地终端出现 `[agent-ws] connected`，并确认 `AI_AGENT_WS_TOKEN` 与页面 Token 一致。
- 提示没有可用 Agent：当前 Token 下没有在线 Agent，或指定 Agent 已离线。
- OpenCode 操作了错误目录：查看重启弹窗或 AI 日志中的“工作目录”，确认是否等于 DevLoop 项目路径。
- OpenCode 浏览器工具不可用：确认 OpenCode 环境已安装并启用 `chrome-devtools` MCP Server。
- Windows `npm install` 卡在 SQLite：当前版本使用 Node 22 内置 `node:sqlite`，请确认 Node.js `>=22.5.0`。

#### 5.2.7 相关接口
- `GET /api/dev-loops`
- `POST /api/dev-loops`
- `POST /api/dev-loops/:id/start`
- `POST /api/dev-loops/:id/stop`
- `GET /api/dev-loops/:id/stages/:stage/exit-check`
- `POST /api/dev-loops/:id/stages/:stage/approve`
- `POST /api/dev-loops/:id/stages/:stage/complete`
- `POST /api/dev-loops/:id/stages/clarify/ai-diagnose`
- `POST /api/dev-loops/:id/stages/split/learn-codebase`
- `POST /api/dev-loops/:id/stages/split/ai-split`
- `POST /api/dev-loops/:id/stages/develop/ai-develop`
- `POST /api/dev-loops/:id/stages/pipeline/pipeline-job`
- `POST /api/dev-loops/:id/stages/test/test-run`
- `POST /api/dev-loops/:id/stages/diagnose/diagnose-job`
- `POST /api/dev-loops/:id/stages/fix/fix-job`
- `POST /api/dev-loop-config/token`
- `GET /api/ai-ws-agents`

## 6. 模型引擎与模型说明
### 6.1 当前模型由谁决定
本项目不在后端写死模型名，模型由以下项共同决定：
- `MODEL_CLI_CMD` / `GEMINI_CLI_CMD`（仅 Gemini CLI）
- 页面里当前选择的“生成引擎 / 执行引擎”
- OpenCode Serve 则通过 `OPENCODE_SERVE_BASE_URL` 指向服务地址

例如：
```bash
MODEL_CLI_CMD=gemini --yolo -p {{PROMPT}}
```

Windows 推荐写法：
```bash
MODEL_CLI_CMD=gemini --yolo -p "{{PROMPT}}"
```

如果希望调整 Gemini 的 CLI 命令模板，推荐在页面：
- `提示词配置 -> Gemini 预设命令`

### 6.2 常见命令
```bash
gemini --yolo -p "请只输出OK"
# OpenCode Serve 建议使用页面内置网络自检进行验证
```

### 6.3 OpenCode Serve 额外说明
如果执行引擎选择 `OpenCode Serve`，除了启动 `OPENCODE_SERVE_BASE_URL` 对应的服务外，还建议确认以下两项：

- OpenCode 环境里已安装并启用 `chrome-devtools` MCP Server
- OpenCode 当前会话对浏览器相关工具有调用权限

如果缺少这部分能力，常见现象包括：
- 页面能发起请求，但浏览器没有被拉起
- 调试日志里出现 `Tool execution denied by policy`
- 模型反馈无法执行 `browser_navigate`、`browser_run_code` 等浏览器工具

建议：
- 先在 OpenCode 自己的环境里单独验证浏览器能力是否可用
- 再回到本系统，点击页面上的“网络自检”确认 OpenCode Serve 可联通

#### OpenCode Serve 重启
执行线程池面板提供两类 OpenCode Serve 重启能力：

- 手动重启：点击“重启 OpenCode Serve”按钮，会先查找并停止当前机器上的 OpenCode Serve 进程，再重新启动服务。
- 自动重启：在“OpenCode每 N 个任务重启”中填写大于 `0` 的数字后，执行批次每完成 N 个 OpenCode 任务，且后面仍有待执行任务时，会先重启 OpenCode Serve，再继续后续任务。

默认值为 `0`，表示不自动重启。该配置只对执行引擎为 `OpenCode Serve` 的任务生效，Gemini 执行不受影响。

进程查找方式：
- Windows：按命令行匹配 `opencode` + `serve`，并按 `OPENCODE_SERVE_BASE_URL` 端口查找监听进程。
- macOS / Linux：按 `lsof -ti tcp:<port>` 查找监听进程，并按 `pgrep -f "opencode.*serve"` 查找命令进程。

默认启动命令：
```bash
opencode serve --port 4096
```

如果本机启动 OpenCode Serve 需要额外参数，建议使用自定义重启命令：
```bash
OPENCODE_SERVE_BASE_URL=http://127.0.0.1:4096
OPENCODE_SERVE_RESTART_COMMAND="opencode serve --port 4096"
```

Windows Agent 本地执行 OpenCode 任务时，也会接收页面上的自动重启配置，并在 Agent 所在机器上执行同样的重启逻辑。
- 如果是新环境，优先补齐 `chrome-devtools` MCP，再做用例执行验证

当前版本的 OpenCode 调试体验已做两层增强：
- 执行调试信息中会展示会话创建、请求发送、流式通道建立等阶段性提示
- 系统会尝试结合 OpenCode 的全局事件流和 `session/:id/message` 轮询，补抓当前会话的过程消息

因此在 OpenCode 执行用例时，调试面板里通常可以看到：
- 当前会话 `sessionId`
- 工具调用前后事件
- 权限请求事件
- 会话消息中的增量文本片段

如果仍然只能看到等待提示，通常说明当前这轮 OpenCode Serve 没有暴露出更多可读的中间文本，而不是系统前端卡死。

### 6.4 遇到 `daily quota exhausted`
报错示例：`TerminalQuotaError: You have exhausted your daily quota on this model.`

处理建议：
- 切换模型（可能立即恢复）
- 检查是否账号/项目总配额已耗尽
- 等待次日配额重置或提升配额

## 7. Skill 包说明
系统支持两类 Skill 包来源：

1. 本地 Skill 包：放在 `data/skill-packs/<skill-name>/SKILL.md`
2. 上传 Skill Zip：上传后会解压到 `data/skill-packs/<skillId>/content/SKILL.md`

推荐优先使用本地目录结构，便于人工维护和版本管理：

```text
data/skill-packs/
  main-web-test/
    SKILL.md
  login/
    SKILL.md
  excel-import/
    SKILL.md
```

注意：`data/skill-packs/SKILL.md` 不会被识别为技能包。系统只扫描 `data/skill-packs` 下的一级子目录，每个子目录内需要有 `SKILL.md`。

当前行为：
- 打开页面或调用 `GET /api/skills` 时，会主动扫描 `data/skill-packs`
- 生成用例时，可选择一个主技能，并将主技能文本规则注入到模型提示词
- 执行用例时，可选择一个主技能；若选择，则将主技能规则注入到执行提示词
- 主技能可以在 `SKILL.md` 中说明何时使用同目录库下的其他辅助技能
- 系统会把可用辅助技能清单作为白名单索引注入提示词，AI 只能读取清单中列出的 `skill-packs` 路径
- 当前主流程不会执行 `RUN:` / `READ:` 指令，也不会把 Skill 运行结果注入执行提示词

依赖文件注入规则：
- 会解析 `SKILL.md` 中的反引号路径和 Markdown 链接
- 仅注入 Skill 包目录内的 `.md`、`.txt`、`.json`、`.yaml`、`.yml` 文件内容

示例主技能：

```md
# Main Web Test

生成或执行登录相关测试时，参考 login 技能。
生成或执行 Excel 导入测试时，参考 excel-import 技能。
生成或执行权限校验测试时，参考 permission 技能。
```

## 8. 网络自检
接口：
- `GET /api/gemini/network-check`
- `GET /api/opencode/network-check`
- `POST /api/opencode/restart`

会检查：
- 网络环境变量（`HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` / `NO_PROXY`）
- CLI 真实调用

## 9. API 一览
- `GET /api/health`
- `GET /api/version`
- `GET /api/prompt-config`
- `POST /api/sample/import`
- `GET /api/skills`
- `POST /api/skills/upload`
- `GET /api/gemini/network-check`
- `GET /api/opencode/network-check`
- `POST /api/opencode/restart`
- `GET /api/requirements`
- `POST /api/requirements`
- `POST /api/requirements/parse-document`（上传需求文件并解析为 Markdown）
- `DELETE /api/requirements/:id`
- `GET /api/cases`
- `POST /api/cases`
- `PUT /api/cases/:id`
- `DELETE /api/cases/:id`
- `GET /api/cases/:id/script`
- `POST /api/cases/:id/script/generate`
- `POST /api/cases/:id/script/probe`
- `PUT /api/cases/:id/script/draft`
- `POST /api/cases/:id/script/approve`
- `POST /api/cases/generate`
- `POST /api/cases/generate/start`
- `GET /api/cases/generate/jobs/:id`
- `GET /api/executions`
- `POST /api/executions`
- `GET /api/executions/:id`
- `GET /api/executions/:id/report`
- `GET /api/executions/history`
- `POST /api/executions/history/report`

### 9.1 DevLoop API
- `GET /api/dev-loops`（获取 DevLoop 列表）
- `POST /api/dev-loops`（创建 DevLoop）
- `POST /api/dev-loops/bulk-delete`（批量删除 DevLoop）
- `GET /api/dev-loops/:id`（获取 DevLoop 详情）
- `POST /api/dev-loops/:id/start`（启动 DevLoop）
- `POST /api/dev-loops/:id/stop`（停止 DevLoop）
- `POST /api/dev-loops/:id/clarify`（生成验收标准）
- `POST /api/dev-loops/:id/next`（推进到下一阶段）
- `POST /api/dev-loops/:id/approve-tasks`（确认开发任务）
- `GET /api/dev-loops/:id/stages/:stage/exit-check`（检查阶段出口条件）
- `POST /api/dev-loops/:id/stages/:stage/approve`（确认阶段完成）
- `POST /api/dev-loops/:id/stages/:stage/complete`（完成阶段）
- `POST /api/dev-loops/:id/stages/clarify/ai-diagnose`（AI 需求诊断）
- `GET /api/dev-loops/:id/stages/clarify/ai-diagnose/:jobId`（获取诊断任务进度）
- `POST /api/dev-loops/:id/stages/split/learn-codebase`（学习代码结构）
- `GET /api/dev-loops/:id/stages/split/learn-codebase/:jobId`（获取代码学习任务进度）
- `POST /api/dev-loops/:id/stages/split/ai-split`（AI 任务拆分）
- `GET /api/dev-loops/:id/stages/split/ai-split/:jobId`（获取任务拆分进度）
- `POST /api/dev-loops/:id/gates/:gateId/resolve`（处理 Gate）
- `GET /api/dev-loop-config`（获取 DevLoop 配置）
- `PUT /api/dev-loop-config`（更新 DevLoop 配置，包含开发、构建部署、诊断、修复阶段 AI 配置）
- `POST /api/dev-loop-config/token`（生成自动化回调 Token）

## 10. 说明
- 数据默认保存在 `data/app.sqlite`；首次启动会自动从旧的 `data/db.json` 迁移
- 版本号保存在项目根目录 `VERSION` 文件中
- 版本号规则：`v主版本-发布日期`，例如 `v1.0.0-20260402`
- 每次提交前请先更新 `VERSION` 文件
- 导出的历史汇总为标准 `.docx` 文件
- 若你在同一机器跑多个实例，请确认端口不要冲突

## 11. 开发验证
重构或新增模块后，建议至少执行：
```bash
node --check src/server.js
node --check src/server/app-services.js
node --check src/server/config.js
node --check src/server/routes.js
node --check src/server/http-utils.js
node --check src/server/static-files.js
for f in src/server/controllers/*.js; do node --check "$f" || exit 1; done
for f in src/server/services/*.js; do node --check "$f" || exit 1; done
for f in src/server/services/dev-loop-stage-handlers/*.js; do node --check "$f" || exit 1; done
for f in src/modules/*.js; do node --check "$f" || exit 1; done
for f in public/app.js public/js/*.js public/devloop.js public/devhistory.js public/devtask.js; do node --check "$f" || exit 1; done
```

启动服务后可做基础冒烟：
```bash
HOST=127.0.0.1 PORT=8012 npm run start
curl -sS http://127.0.0.1:8012/api/health
curl -sS http://127.0.0.1:8012/api/version
curl -sS http://127.0.0.1:8012/ai-test.html
curl -sS http://127.0.0.1:8012/devloop.html
```