深枭 DeepOwl 使用手册

DeepOwl 把「文档索引 → 需求分解 → 用例生成 → 夜间执行 → 报告」串成一条可无人值守的测试流水线。设计目标与架构说明见根目录 README.md。

1. 环境与安装

项	要求
运行时	Bun ≥ 1.1（首选）或 Node ≥ 22.5 / Deno ≥ 2.2（走 `node:sqlite`）
SQLite	需带 FTS5 与 `trigram` 分词器；Bun 与 Node 22+ 内置的 SQLite 均满足
浏览器	本机已安装 Edge 或 Chrome 即可，无需下载 Playwright 浏览器
依赖	`playwright-core`（已随仓库声明，`bun install` 即可）
图标	`ui/icon.svg` 为唯一设计源；`bun run scripts/make-icon.ts` 用本机 Edge 渲染成多尺寸 `src-tauri/icons/icon.ico`

bun install                     # 依赖走国内镜像（bunfig.toml 已配置 npmmirror）
bun link                        # 可选：把 `deepowl` 注册到全局 PATH
bun run bin/deepowl.ts doctor   # 环境自检：运行时 / FTS5 / 浏览器 / LLM / 配置

下文所有 deepowl <命令> 等价于 bun run bin/deepowl.ts <命令>（未执行 bun link 时用后者）。

配置：deepowl.config.json（deepowl init 可重新生成）。所有键都有默认值，环境变量优先级更高：

环境变量	作用
`DEEPOWL_LLM_BASE_URL` / `DEEPOWL_LLM_API_KEY` / `DEEPOWL_LLM_MODEL`	规划阶段使用的 OpenAI 兼容端点（`DEEPSEEK_API_KEY` 亦可）
`DEEPOWL_BASE_URL`	被测系统基址（`goto` 的相对路径基于它）
`DEEPOWL_BROWSER_CHANNEL` / `DEEPOWL_HEADLESS`	浏览器通道（`auto`/`msedge`/`chrome`）与无头开关
`DEEPOWL_DB` / `DEEPOWL_ARTIFACTS` / `DEEPOWL_DOC_ROOTS`	索引库、产物目录、文档根（逗号分隔）
`DEEPOWL_CRON` / `DEEPOWL_PLAN_FILE`	夜间调度 cron 与默认方案文件
`DEEPOWL_WECOM_WEBHOOK` / `DEEPOWL_WEBHOOK`	企业微信 / 通用 webhook 推送

2. 模块一：文档索引（非 RAG）

历史文档（Markdown / txt / HTML / docx / xlsx / pptx / PDF）统一转成 Markdown，按标题切分成片段，写入 SQLite 的 FTS5 全文索引（tokenize='trigram'，中文按 3 字符子串检索，BM25 排序）。 不涉及向量嵌入、不做语义检索。

deepowl docs index                  # 增量索引（按内容 sha256 判断，未变更则跳过）
deepowl docs index --rebuild        # 全量重建
deepowl docs search "登录 验收标准" --limit 5
deepowl docs read examples/requirements/login.md
deepowl docs read 账号锁定           # 也可用关键词定位文档

索引库：.deepowl/docs.db（含 documents/chunks 两张表 + chunks_fts 外部内容表）。
转换缓存：.deepowl/converted/<sha>.md，便于人工核对转换质量。
.docx/.xlsx/.pptx 由内置的零依赖 OOXML 解析器处理；解析失败或遇到 PDF 时回落到 markitme / markitdown / pdftotext（需自行安装，缺失时给出明确提示）。

2.1 作为 MCP 服务器接入 DSH

deepowl docs mcp-config --write     # 生成 .deepowl/mcp.json
deepowl docs mcp                    # stdio MCP 服务器（JSON-RPC 2.0）

暴露两个工具：search_docs {query, limit?, pathPrefix?}、read_doc {path, maxChars?}。把它注册进 DSH / 任意 MCP 客户端后，Agent 在写计划、拆需求时就能自动检索历史文档。

3. 模块二：需求分解与用例生成

deepowl plan --topic "登录" --title "登录功能测试方案"          # 按主题从索引里检索语料
deepowl plan --doc examples/requirements/login.md              # 指定索引内文档
deepowl plan --doc "D:\需求\支付与退款需求.docx" --title "支付方案"   # 直接指定/上传需求文档（无需先建索引）
deepowl plan --doc a.md --doc b.docx --doc c.pdf               # 多份文档一起作为语料
deepowl docs list                                             # 列出已索引文档（GUI 的勾选清单同源）

语料来源三种用法（可组合，--doc 给出时只用手动指定的文档）：

方式	说明
主题词检索	`--topic` 从索引中按 FTS5 检索相关片段，未命中回落到库里前 N 篇
勾选已索引文档	桌面客户端「② 测试方案 → 文档来源」里勾选（`deepowl docs list` 同源）
指定 / 上传文档	命令行 `--doc <路径>`，或桌面端「添加需求文件…」/ 直接粘贴路径；md / txt / html / docx / xlsx / pptx / pdf 都支持，索引里没有的会现场转换，因此临时拿到一份 Word 需求也能直接出方案

流程：从索引中取相关文档（plan.topDocs / 片段截断）→ 调用 LLM 产出三级结构（功能模块 → 测试项 → 验收标准，RequirementItem）→ 分批生成测试用例（PlannedCase）→ 计算需求追溯矩阵（covered / partial / missing）→ 落盘：

plans/<slug>.md：人类可读方案（测试范围、追溯矩阵、用例清单）+ 每个用例的 deepowl-case 围栏 JSON。
plans/<slug>.plan.json：机器可执行副本（TestPlan）。

用例步骤使用受控 DSL（goto/click/fill/press/select/expectText/expectVisible/expectUrl/wait/screenshot）， target 写页面上的可见文案（如「登录按钮」），不写 CSS 选择器——执行时由 DOM 快照解析成 locator，页面改版时更耐改。

4. 模块三：浏览器执行

bun run examples/demo-app/serve.ts                    # 启动演示应用（另一个终端）
deepowl run examples/test-plan.example.md             # 无头执行
deepowl run plans/login.plan.json --shards 4          # 分片并行（多个 context 同时跑）
deepowl run examples/test-plan.example.md --case TC-LOGIN-002 --headed

驱动：playwright-core + chromium，通道按 msedge → chrome → chromium 自动探测，本机有 Edge/Chrome 就零下载。
定位：每步先取 ARIA 快照（ariaSnapshot）解析出带 ref 的元素表，再按「精确 → 包含 → 关键词+角色」匹配目标文案，最终用 getByRole(role, { name }) 定位；匹配不到时抛错并列出候选元素，便于修正用例描述。
失败即整例重试（runner.retries），重试仍失败则截图留档到 artifacts/runs/<runId>/。
显式操作为主（click/fill/press）保证回归稳定；需要探索性验证时，把「让 Agent 自主操作」交给 DSH 的子代理（隐式操作），两者可并存。

5. 模块四：夜间调度

deepowl night                         # 立即跑一轮：执行 + 报告 + 推送
deepowl night --plan plans/x.md --case TC-A,TC-B   # 只跑指定用例（回归/调试子集）
deepowl daemon                        # 常驻进程，按 schedule.cron 到点触发
deepowl task install --start 02:00    # 注册 Windows 任务计划程序（免常驻）
deepowl task install --dry-run        # 只生成 XML 并打印注册命令，不动系统
deepowl task query

cron 为 5 段「分时日月周」；日与周同时限定时按 cron 语义取或。
Windows 任务计划：deepowl task install 生成 .deepowl/DeepOwl-Nightly.xml 并调用 schtasks /Create /F， XML 内已设置 StartWhenAvailable、WakeToRun、IgnoreNew。
执行机需保持登录但可锁屏：注销状态下浏览器自动化可能受限；这也是任务计划里带「锁屏不注销」说明的原因。

6. 模块五：报告与推送

deepowl report                      # 合并最近 5 次运行
deepowl report --run 20261002-020000
deepowl report --all --title "十月夜间回归汇总"

报告落 reports/nightly-<时间戳>.md，含：执行摘要（总数/通过/失败/跳过、通过率、分模块统计）、失败用例详情（用例ID｜失败步骤｜错误信息｜截图路径）、新增缺陷建议（按「失败动作 + 归一化错误签名」聚类）。

推送通道在 report.notify 配置：

"notify": [
  { "type": "wecom", "url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx", "timeoutMs": 10000 },
  { "type": "generic", "url": "https://your.jira-or-ci/hook", "timeoutMs": 10000 },
  { "type": "file", "dir": "reports/pushed", "timeoutMs": 10000 }
]

单个通道失败不会中断流水线（结果里记录原因）。

7. 产物与目录

artifacts/runs/<runId>/run.json   每次运行的完整结果（含每步状态、ref、耗时、截图）
artifacts/runs/<runId>/*.png      失败截图与显式 screenshot 步骤的产物
plans/<slug>.md|.plan.json        测试方案
reports/nightly-*.md              夜间报告
.deepowl/docs.db                  文档索引（FTS5）
.deepowl/converted/*.md           转换后的 Markdown 缓存

8. 常见问题

现象	处理
`配置有误：...`	按提示修正 `deepowl.config.json`；`deepowl doctor` 会打印解析后的关键项
检索不到中文	查询串 < 3 字符会退化为 LIKE 匹配；先确认已 `deepowl docs index`
LLM 调用报 `未配置 apiKey`	设置 `DEEPOWL_LLM_API_KEY`，或 `plan.llm.apiKey`
`未找到可用浏览器`	装 Edge/Chrome，或 `DEEPOWL_BROWSER_CHANNEL=msedge` 指定通道
元素定位失败	报错会给出候选快照元素：把用例 `target` 改成快照里的可见文案
夜间任务没跑	`deepowl task query` 看状态；确认执行机未注销、`StartWhenAvailable` 生效

9. 离线部署（制品包）

目标机没有 Bun、没有 npm、没有外网时，用 deepowl pack 打一个自包含离线包：

deepowl pack --zip                     # 产出 dist/deepowl-<版本>-win32-x64/ 与同名 .zip
deepowl pack --zip --with-browser      # 额外把本机 Edge/Chrome 目录打进包（无浏览器环境用）
deepowl pack --zip --with-gui          # 额外打进桌面客户端 DeepOwl.exe（需先 cargo build --release）
deepowl pack --out D:\pkg              # 指定输出目录
deepowl pack verify dist/deepowl-*     # 按 manifest.json 逐个 sha256 校验完整性

包结构：

deepowl-<版本>-<平台>-<架构>/
  deepowl.cmd            启动器（自带 runtime\bun.exe，可在任意项目目录里执行）
  deepowl.ps1            PowerShell 版启动器
  install.cmd            确认后把包目录加入「用户 PATH」，全局可用 deepowl
  uninstall.cmd          从 PATH 移除
  OFFLINE.md             离线安装与使用说明
  manifest.json          版本/平台/文件清单(sha256)
  runtime/bun.exe        Bun 运行时（目标机无需另装）
  app/                   本工具本体（bin/ src/ node_modules/ 配置与示例）
  browser/               --with-browser 时的浏览器副本

目标机操作：

:: 免安装：解压后在任意项目目录执行
D:\deepowl\deepowl.cmd doctor
D:\deepowl\deepowl.cmd docs index
D:\deepowl\deepowl.cmd run plans\test-plan.md

:: 或安装到 PATH（需重开终端生效）
D:\deepowl\install.cmd
deepowl doctor

要点：

启动器会设置 DEEPOWL_HOME 为包根目录：包内 app/deepowl.config.json 作为默认配置层（优先于内置默认值、低于目标机当前目录里的 deepowl.config.json 与环境变量）。索引库、artifacts/、reports/ 仍生成在执行命令时所在目录。
--with-browser 会把包内浏览器路径写入配置（runner.browserExecutablePath，相对包根解析）；也可用 DEEPOWL_BROWSER_EXECUTABLE_PATH 临时指定。
完全离线时不能用云端 LLM：把规划阶段指向本机 OpenAI 兼容端点，例如 set DEEPOWL_LLM_BASE_URL=http://127.0.0.1:8098/v1 + set DEEPOWL_LLM_MODEL=local（本地 llama.cpp 亦可）。
包内 node_modules 只含运行时依赖闭包（不含 typescript 等 devDependencies），因此包内不能跑 tsc。

10. 桌面客户端（GUI）

除 CLI 外还有一个 Windows 原生窗口程序（Tauri v2 / Rust，位于 src-tauri/，前端为仓库根 ui/ 的静态页面，不依赖 npm 包）。它是薄壳：所有能力仍由同一个 CLI 提供，GUI 负责把索引、方案、执行、报告串成可视化工作台。

cd src-tauri && cargo build --release      # 产物 src-tauri/target/release/DeepOwl.exe（首次编译较久）
cd .. && bun run bin/deepowl.ts pack --with-gui --zip   # 把 exe 一并打进离线包
D:/Develop/workspace/gitonline/CoderLife/DeepOwl/src-tauri/target/release/DeepOwl.exe   # 直接运行

界面分四个工作区：

工作区	能力
① 文档索引	建立/重建索引、关键词检索、点结果看文档原文
② 测试方案	文档来源（勾选已索引文档 / 「添加需求文件…」选择或粘贴任意需求文档路径）、按主题生成方案、列出并预览 `plans/*.md`
③ 执行监控	选方案、设分片、按用例 ID 过滤（逗号分隔多个，如 `TC-A,TC-B`），无头/可视化执行，实时日志 + 用例结果表（可打开失败截图），另有「夜间流水线」按钮（执行 + 报告 + 推送，同样受用例过滤约束）
④ 报告与产物	汇总最近运行生成报告、markdown 预览、打开报告目录
⚙ 设置	大模型端点（地址/模型/Key/超时/重试）配置与连通性测试、当前生效值来源、关于（版本/开发者/命名空间）

顶部可切换项目目录：.deepowl/、artifacts/、reports/、plans/ 都按该目录读写。
形态自动识别：exe 与 runtime/、app/ 同级（离线包）时用包内 Bun；在开发仓库里运行时用 PATH 中的 bun 与仓库 bin/deepowl.ts。
依赖系统 WebView2 运行时（Windows 11 内置；Windows 10 需先装一次 Evergreen Runtime）。
快捷键/自动化验证：GUI 的每个动作都等价于一条 CLI 命令，回归验证以 CLI 为准，GUI 只验证交互与呈现。

11. 模型端点配置

规划阶段（需求分解 / 用例生成）依赖 OpenAI 兼容端点。三种配置方式任选，优先级从低到高：内置默认值 ← 离线包默认配置（$DEEPOWL_HOME/deepowl.config.json）← 用户级设置 ← 项目 deepowl.config.json ← 环境变量。

# ① 桌面客户端「⚙ 设置」页：填地址/模型/Key，点「保存到用户设置」或「保存到项目配置」，再点「测试连接」
# ② 命令行
deepowl llm show                                   # 查看当前生效端点、来源与配置文件路径
deepowl llm set --base-url http://127.0.0.1:8098/v1 --model local
deepowl llm set --base-url https://api.deepseek.com/v1 --model deepseek-chat --api-key sk-xxx
deepowl llm set --clear-api-key                    # 清空 Key（本机端点可留空）
deepowl llm test                                   # 向端点发一次真实请求，打印往返耗时与模型回复
deepowl llm set --base-url ... --project           # 改为写进当前项目的 deepowl.config.json
# ③ 环境变量（临时覆盖，不落盘）
set DEEPOWL_LLM_BASE_URL=http://127.0.0.1:8098/v1 & set DEEPOWL_LLM_API_KEY= & set DEEPOWL_LLM_MODEL=local

用户级设置文件：%USERPROFILE%\.deepowl\settings.json（可用 DEEPOWL_USER_SETTINGS 改路径）。端点与 Key 属于「这台机器这个人」的信息，放这里就不会随项目仓库提交。
本机端点免 Key：baseUrl 指向 127.0.0.1 / localhost 时允许 apiKey 为空（离线 llama.cpp / Ollama / LM Studio 场景）。
deepowl doctor 的「LLM」一行会显示当前端点与 Key 是否已配置；deepowl about 显示版本、开发者与命名空间。

12. 自测

bun test            # 单元 + 集成测试（含真实 Edge 执行、真实 SQLite、真实 ZIP 解析）
bunx tsc --noEmit   # 类型检查