深枭自动化测试工具

作者个人站：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

deepowl about 与桌面客户端「⚙ 设置 → 关于」展示同一份信息（来源为 package.json）。

关于

这个项目由 CodeLife Leon 独立开发与维护。更多项目、各项目发版信息、赞赏与联系方式都在个人站：

• 个人站：https://softwarescience.top/
• 本项目主页：https://softwarescience.top/projects/deepowl
• 下载与发版：https://softwarescience.top/releases/deepowl
• 赞赏支持：https://softwarescience.top/sponsor（自愿，不影响任何版本的发布）

问题反馈与需求建议：优先在仓库提 Issue，也可以邮件 virgil_lgp@163.com。