自动执行测试、精准发现问题｜作者个人站：https://softwarescience.top/projects/deepowl

深枭自动化测试工具

作者个人站：https://softwarescience.top/ · 本项目主页：https://softwarescience.top/projects/deepowl（版本、截图与下载都在那儿）

基于 DeepSeek Harness 构建桌面端自动化测试工具，这个想法在工程上完全可行。它的核心思路是：将 Harness 作为智能调度中枢，把“文档索引 → 需求分解 → 用例生成 → 夜间执行 → 浏览器驱动”串成一条自动化流水线。下面是一套可落地的技术方案。

一、整体架构设计

┌─────────────────────────────────────────────────────────┐
│                    DeepSeek Harness 主 Agent              │
│         (任务编排 / 子代理调度 / 上下文管理)                │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│ 文档索引  │ 需求分解  │ 用例生成  │ 测试执行  │ 报告生成    │
│ 插件      │ 插件      │ 插件      │ 插件      │ 插件        │
├──────────┴──────────┴──────────┴──────────┴─────────────┤
│              Cordis 插件契约层 (DSH 微内核)               │
├─────────────────────────────────────────────────────────┤
│   SQLite FTS5  │  Playwright  │  任务调度器  │  日志/报告  │
└─────────────────────────────────────────────────────────┘

DSH 采用微内核+Cordis 插件契约架构，内核负责任务调度、会话上下文管理、安全沙箱和模型通信，所有工具能力都封装成独立插件，支持按需加载。这意味着你可以把每个功能模块做成独立插件，按需组合。

Harness 内置了 subagent、workflow、ralph 等多 Agent 编排工具，无需额外安装即可让子代理并发执行独立任务。这正好适合“文档分析”和“用例生成”这类可并行的环节。

二、模块一：文档索引（非 RAG）

2.1 文档转换层

将历史文档（PDF、Word、Excel、PPT 等）统一转换为 Markdown。推荐使用 MarkItDown 或 markitme，它们支持 PDF、Word、Excel、图片、HTML 等格式转 Markdown，并保留结构化信息。markitme 还支持 --wiki 模式，能生成主 README 索引文件，包含目录、按文件分节以及基于关键词重叠的交叉链接。

2.2 索引与检索层

你明确要求非 RAG，也就是不做向量嵌入和语义检索，而是用全文索引来实现快速搜索。推荐方案：

方案	技术栈	特点
askdocs	Node.js + SQLite FTS5	按标题切分文件，索引到 SQLite，通过 MCP 协议给 Agent 提供搜索工具
docs-search	Python 标准库 + SQLite FTS	零依赖，毫秒级检索，支持增量重建
自建 FTS5	SQLite FTS5	完全可控，BM25 评分，支持中文分词

推荐用 askdocs 作为 MCP 工具接入 DSH——它正是为“让 Agent 搜索 Markdown 文档”而设计的。Agent 通过 search_docs 和 read_doc 两个工具就能完成文档检索，关键词搜索不需要嵌入向量，也不需要向量数据库。

在 DSH 会话中，可以将 askdocs 注册为 MCP 服务器，Agent 就能在写计划、分解需求时自动检索历史文档。

三、模块二：需求分解与测试用例生成

3.1 利用 DSH 的子代理进行需求分解

在 DSH 中创建一个 “测试规划师”子代理，给它配置：

系统提示词：要求它从 Markdown 文档中提取功能点，按“功能模块 → 测试项 → 验收标准”三级结构输出
可用工具：askdocs 的 search_docs 和 read_doc
输出格式：结构化的 Markdown 测试方案

DSH 的 subagent 工具可以在完全独立的上下文中运行子代理，不继承父会话历史，任务完成后返回结果。这正好适合“需求分解”这类需要专注分析的任务。

3.2 测试用例生成的提示工程

参考已有的 AI 测试用例生成实践，提示词可以这样设计：

角色：你是一名资深测试工程师。
任务：基于以下需求文档片段，生成测试用例。
要求：
1. 每个用例包含：用例ID、标题、前置条件、操作步骤、预期结果、优先级
2. 覆盖正常场景、边界条件、异常场景
3. 输出为表格格式
4. 引用文档来源（文件名 + 章节）

DSH 的 ralph 工具可以防止 Agent 在同一个思路上反复钻牛角尖——它每轮换一个新 Agent，配合结构化交接报告，适合用例生成这种需要迭代精化的场景。

3.3 测试方案的形成

将需求分解结果和用例生成结果合并为一份完整的测试方案：

# 测试方案：XXX功能模块

## 1. 测试范围
## 2. 需求追溯矩阵
| 需求ID | 需求描述 | 对应用例 | 覆盖状态 |
## 3. 测试用例清单
## 4. 执行计划（含夜间任务配置）

四、模块三：浏览器自动化驱动

4.1 DSH 浏览器插件选型

DSH 生态中已有多个成熟的浏览器自动化插件：

插件	能力	适用场景
dsh-browser-playwright	Playwright 驱动，快照 + ref 定位	确定性强的测试执行
dsh-bridge-browser	连接已有 Chrome 标签页，保留登录态	需要登录的业务测试
dsh-zcode-browser-use	无头模式 + 侧边栏镜像	夜间静默执行

推荐 dsh-browser-playwright，因为它使用 快照 + ref 定位（而非 CSS 选择器），确定性更强，token 消耗更少。它自动探测 chromium → chrome → msedge → edge 通道，本机有 Chrome 就零下载。

4.2 显式 vs 隐式操作

显式操作：click(ref)、fill(ref, text)、press(key) —— 确定性高，适合回归测试
隐式操作：让 Agent 理解页面语义后自主决定操作路径 —— 适合探索性测试

在夜间执行场景中，建议显式操作为主（稳定），隐式操作为辅（发现新问题）。

4.3 桌面应用测试

如果测试目标包含 Electron 桌面应用，Playwright 原生支持 Electron 测试，可以启动 Electron 应用并在主进程和渲染进程中进行操作。

五、模块四：夜间调度与执行

5.1 调度机制

DSH 支持 CLI / 无头模式，适合脚本化调度。夜间调度可以用：

Windows：任务计划程序（Task Scheduler）触发 dsh CLI 命令
macOS/Linux：cron job 触发
跨平台：用 Node.js 的 node-schedule 或 cron 库

# 示例：每天凌晨 2 点执行全量回归
0 2 * * * /usr/local/bin/dsh run --preset test-nightly \
  --input "执行夜间全量回归，读取 test-plan.md，运行所有 P1/P2 用例"

5.2 无头模式注意事项

Playwright 默认以无头模式运行。但需注意：

Windows 锁屏/注销时：无头模式可运行，但注销状态下浏览器自动化可能受限
建议：保持用户会话处于锁屏但未注销状态，或使用专用测试机

5.3 分片并行

对于大量用例，可以用 DSH 的 workflow 工具将用例分片，并行启动多个子代理同时执行。每个子代理拥有独立的浏览器会话，互不干扰。

六、模块五：报告与反馈

夜间执行完成后，DSH 自动生成结构化报告：

# 夜间回归测试报告 (2026-10-02 02:00 - 04:32)

## 执行摘要
- 总用例：156 | 通过：148 | 失败：6 | 跳过：2
- 通过率：94.9%

## 失败用例详情
| 用例ID | 失败步骤 | 错误信息 | 截图 |
|--------|---------|---------|------|

## 新增缺陷建议
（由子代理基于失败模式自动归纳）

报告可以保存为 Markdown 并推送到指定位置（邮件、企业微信、Jira 等）。

七、实施路线图

阶段	工作内容	产出
第 1 周	部署 DSH，安装 askdocs + dsh-browser-playwright，转换 3-5 份历史文档	可搜索的 Markdown 索引
第 2 周	配置“测试规划师”子代理，用 1-2 个需求做端到端验证	测试方案模板 + 首批用例
第 3 周	实现夜间调度脚本，用 Playwright 跑通 5-10 个用例	可运行的夜间流水线
第 4 周	接入报告生成，配置失败通知，优化用例覆盖率	完整闭环

关键风险与应对

风险	应对
文档格式不统一	markitme 的 `--human` 模式自动处理 frontmatter、TOC、交叉链接
用例生成质量不稳定	用 ralph 工具多轮迭代，每轮换新 Agent 评审
夜间执行环境不稳定	保持锁屏不注销；配置重试机制（`--retries=1`）
登录态过期	使用 dsh-bridge-browser 连接已有 Chrome 会话，保留 Cookie

这套方案的核心逻辑是：DSH 做编排，插件做能力，SQLite FTS5 做索引，Playwright 做执行。每个模块都可以独立开发和替换，不会牵一发而动全身。

八、本仓库的工程实现

方案已按上面的五个模块落地为一个可直接运行的 Bun/TypeScript 工程（SQLite FTS5 索引 + Playwright 执行， 非 RAG）。完整使用说明见 docs/USAGE.md。

bun install                     # 依赖走国内镜像（bunfig.toml 已配 npmmirror）
bun run bin/deepowl.ts doctor   # 环境自检：运行时 / FTS5 / 浏览器 / LLM / 配置

deepowl docs index              # ① 文档索引（md/txt/html/docx/xlsx/pptx/pdf → Markdown → FTS5）
deepowl docs search "登录"      #    检索；也可 deepowl docs mcp 作为 MCP 服务器给 DSH 用
deepowl plan --topic "登录"     # ② 需求分解 + ③ 用例生成 → plans/<slug>.md|.plan.json
deepowl plan --doc "需求.docx" #    也可直接指定/上传需求文档（md/txt/html/docx/xlsx/pptx/pdf，无需先建索引）

bun run examples/demo-app/serve.ts                 # 演示应用（另一个终端）
deepowl run examples/test-plan.example.md          # ④ 浏览器执行（快照 + ref 定位，分片并行）
deepowl night                                      # ⑤ 执行 + 报告 + 推送
deepowl task install --start 02:00                 #    或注册 Windows 任务计划程序
deepowl pack --zip                                 # ⑥ 打离线制品包（自带运行时/依赖，可离线再装）
cd src-tauri && cargo build --release              # ⑦ 桌面客户端（Tauri，产物 DeepOwl.exe）

方案模块	实现位置	关键命令
文档转换	`src/docs/convert.ts`（零依赖 OOXML 解析 + markitme/markitdown 兜底）	`deepowl docs index`
索引与检索	`src/docs/{chunker,indexer,search,reader}.ts`（SQLite FTS5 trigram + BM25）	`deepowl docs search`
MCP 工具面	`src/docs/mcp.ts`（`search_docs` / `read_doc`）	`deepowl docs mcp`
需求分解	`src/planner/{prompts,llm,decompose}.ts`	`deepowl plan`
用例生成	`src/planner/cases.ts` + 追溯矩阵 `src/planner/plan.ts`	`deepowl plan`
浏览器驱动	`src/runner/{refs,driver,executor}.ts`（ARIA 快照 + ref 定位）	`deepowl run`
夜间调度	`src/schedule/{cron,schedule,win-task}.ts`	`deepowl night` / `daemon` / `task install`
报告与推送	`src/report/{report,notify}.ts`	`deepowl report`
离线制品包	`src/pack/{pack,zip}.ts`（自带 Bun 运行时 + 依赖闭包 + 安装脚本 + sha256 清单，自研 ZIP 写入）	`deepowl pack --zip`
桌面客户端	`src-tauri/`（Tauri v2 / Rust 薄壳）+ `ui/`（静态前端，无 npm 依赖）	`cargo build --release` → `DeepOwl.exe`

与方案的几点工程取舍：

GUI 是薄壳：桌面客户端（Tauri v2 + 静态前端）不重复实现业务逻辑，只调用同一个 CLI 并呈现结果，因此一条命令行的回归修复同时惠及 CLI、MCP 与桌面端。
零浏览器下载：用 playwright-core + 自动探测本机 msedge/chrome 通道，装机即有 Edge 的机器开箱可跑。
中文检索不引分词器：FTS5 使用 trigram 分词器做 3 字符子串匹配 + BM25 排序，3 字符以下的查询自动退化为 LIKE，既满足「全文索引、非 RAG」，也不依赖 jieba 之类的分词组件。
用例双层表示：方案 Markdown 里的 deepowl-case 围栏 JSON 是执行器的唯一输入，人类可读部分可自由改写而不影响执行。

九、开发者

项	内容
开发者	CodeLife leon、omp
项目命名空间	`top.softwarescience`（桌面端 bundle identifier：`top.softwarescience.deepowl`）
许可证	Apache-2.0（见 LICENSE 与 NOTICE）
仓库	https://gitcode.com/CoderLife/DeepOwl