Files

T

2026-05-25 15:09:42 +08:00

13 KiB

Raw Blame History

产品需求文档：ZeekerWatchman （测试用例智能管理平台）

文档版本	修订日期	修订人	修订说明
V0.1	2026-05-22	-	初稿，整合核心架构与用户流程
V0.2	2026-05-22	-	细化 IR 规范与 Skill 接口，补充非功能需求
V1.0	2026-05-22	-	P2-P4 完成，更新实现状态、架构分层、3 阶段流水线、Chat Panel

1. 产品概述与愿景

1.1 产品愿景

将"产品需求文档（PRD）"到"可执行测试用例"的转换过程，从依赖人工经验的黑盒，升级为可解释、可迭代、可插拔的知识工程系统。

1.2 核心价值主张

输入：非结构化的 PRD 文本（.md, .txt, .docx, .pdf）
处理：AI 驱动的 3 阶段流水线：语义索引 → 逐单元 IR 提取 → 合并审计
输出：多格式测试用例（YAML / CSV / JSON），含完整审计报告
差异化：Agent 人格化、Skill 热插拔、Chat Panel 交互式编辑

2. 用户与核心场景

2.1 目标用户画像

测试架构师/资深 QA：定义测试策略，设计 Skill 包，审核 IR 与审计报告
测试工程师：上传 PRD，执行生成，通过 Chat Panel 微调并导出用例
开发工程师：查看 YAML 格式用例，集成到 CI/CD

2.2 核心用户故事

作为测试工程师，我希望上传 PRD 后自动生成 IR 并在思维导图中可视化确认
作为测试架构师，我希望将团队方法论打包成 Skill，一键切换
作为测试工程师，我希望通过右侧 Chat Panel 用自然语言修改 IR 内容和用例

3. 系统架构总览（实现后）

┌──────────────────────────────────────────────────┐
│           .zeekerwatchmen/ (Agent 灵魂)            │
│  ├── skills/{default,ecommerce}/  (热插拔 Skill)   │
│  ├── memory/                      (会话记忆)       │
│  └── soul/                        (人格/原则)      │
└──────────────────────────────────────────────────┘
                      ↓ 动态注入
┌──────────────────────────────────────────────────┐
│             Core (底座层 — 仅基础设施)              │
│  ├── llm_provider/    (DeepSeek/Qwen 客户端+路由)   │
│  ├── prompt/templates/ (宽泛框架级 prompt)          │
│  ├── personality/     (动态人格装配)                │
│  ├── reasoning/       (ReAct/LangGraph 编排)       │
│  └── utils/           (Logger, Diff, Export)       │
└──────────────────────────────────────────────────┘
                      ↓ 能力支撑
┌──────────────────────────────────────────────────┐
│           Services (业务层 — 领域逻辑 + 业务 prompt) │
│  ├── prompts/           (ir_step1/2 业务 prompt)   │
│  ├── prd_manager/       (Word/PDF 解析+图片分析)    │
│  ├── ir_engine/         (3 阶段流水线+验证+Diff)    │
│  ├── testcase_engine/   (用例生成+导出)             │
│  └── skill_manager/     (Skill 扫描+热加载)         │
└──────────────────────────────────────────────────┘
                      ↓ API 服务
┌──────────────────────────────────────────────────┐
│         Web UI (Next.js 左右分栏布局)              │
│  ┌──────────────────────┬────────────────────┐   │
│  │  左侧：主工作区        │  右侧：AI Chat      │   │
│  │  上传→IR可视化→用例    │  自然语言交互       │   │
│  │  思维导图+审计报告     │  操作左侧内容       │   │
│  └──────────────────────┴────────────────────┘   │
└──────────────────────────────────────────────────┘

3.1 分层原则

core/（底座层）：只有基础设施，不含业务逻辑。更新底座只改 core，不改 services
services/prompts/（业务 prompt）：所有领域相关的 prompt 模板放在此处
services/（业务层）：领域逻辑调用 core 的 LLM 接口，引用自己的 prompt

4. 核心功能详述（已实现）

4.1 Skill 热插拔体系 (`.zeekerwatchmen`)

soul/principles.yaml：5 条不可违背准则
soul/persona.yaml：Agent 人格定义（"Zeeker"）
skills/{name}/：每个 Skill 独立目录，含 skill.yaml + ir_schema.json + extract/gen_cases_prompt.j2
skills/default/：通用测试设计
skills/ecommerce/：电商后台（含 business_rules、data_consistency 等电商特有字段）
GET /api/skills 自动扫描，POST /api/skills/reload 热重载

4.2 PRD 解析 (`prd_manager`)

WordParser（services/prd_manager/word_parser.py）：直接遍历 document.body XML
- 类型化 blocks：{type: "para"|"table", index, text/headers/rows}
- 表格列结构：columns[{name, row, col, text}]
- 表头检测启发式：首行所有单元格 < 20 字符则视为表头
- [[IMAGE:rid]] 标记嵌入文本
- image_sources 含精确定位：{section, table, row, column, name}
ImageParser（services/prd_manager/image_parser.py）：Qwen VL 分析图片（类型+描述）
支持格式：.md / .txt / .docx / .pdf
Markdown 解析：# 标题 → sections，| 表格 → table blocks

4.3 3 阶段 IR 生成流水线 (核心升级)

PRD parsed JSON ──→ Stage 1 ──→ Stage 2 ──→ Stage 3 ──→ ir_final.json
                   语义索引    逐单元提取    合并审计     + audit_report.md

Stage 1：宏观语义索引

输入：完整 parsed PRD JSON（sections + image_analysis）
format_document_for_prompt()：渲染为 sections/blocks/tables/images 可读文本
Prompt 模板：services/prompts/ir_step1_semantic_index.txt
输出：{feature_name, concepts[], function_units[{unit_id, name, description, sources[]}]}
System prompt: "精确的 JSON 输出引擎" + 健壮 extract_json_from_response() + 3 次重试
失败降级：_fallback_semantic_index() 从段落/表格自动提取

Stage 2：逐功能单元 IR 提取

输入：semantic_index + parsed PRD
build_context_package()：为每个 function_unit 构建精准上下文包（texts + tables + images + conflicts）
Prompt 模板：services/prompts/ir_step2_extraction.txt
IR Schema：trigger{operator, conditions[{signal,operator,value,unit}]} + actions[{type,description,content}] + precondition
ThreadPoolExecutor(max_workers=3) 并行调用
输出：[{unit_id, rules[{description, trigger, actions, sources, priority}]}]

Stage 3：确定性合并与审计

rule_signature(rule)：SHA256(trigger.conditions + actions) 去重
merge_rules()：去重，合并 sources
assign_rule_ids()：格式 {FEATURE}-{TYPE}-FG-{NN}（SYS/UI/SDK）
_generate_audit()：章节覆盖、图片引用覆盖、优先级分布
_format_audit_report()：Markdown 格式审计报告

4.4 Chat Panel 交互式编辑

布局：左侧 380px 固定宽度 ChatPanel + 右侧 flex-1 主内容
状态桥：Zustand store (web/src/lib/store.ts) 在页面和 ChatPanel 间共享 PRD/IR/Testcases
后端 API：POST /api/chat — 接收 context + history，返回 reply + actions
Action 机制：
- {"action": "update_ir", "content": "..."} — 更新左侧 IR 编辑器
- {"action": "generate_cases", "ir_id": "..."} — 跳转生成用例
- {"action": "navigate", "page": "..."} — 页面跳转

4.5 思维导图可视化 (`web/src/components/MindMap.tsx`)

双格式兼容：YAML IR（features 树）和 JSON pipeline IR（rules 树）
SVG 递归渲染：节点矩形 + 贝塞尔曲线连接 + 优先级颜色标签
Hover 提示：鼠标悬停显示完整文本

4.6 测试用例生成与导出

规则→用例转换（_rules_to_cases()）：trigger.conditions → Given 子句，actions → Then 子句
导出格式：YAML / CSV / JSON，GET /api/testcase/export/{format}

4.7 LLM 模型配置

文本模型：DeepSeek (deepseek-chat / deepseek-v4-pro)，base_url: https://api.deepseek.com
图片模型：Qwen VL (qwen3-vl-plus)，base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
无 API Key 时自动降级为 Mock 模式

5. 技术栈

层	技术
后端框架	Python FastAPI + Uvicorn
LLM 客户端	OpenAI SDK（兼容 DeepSeek + Qwen DashScope）
LLM 模型	DeepSeek (文本) + Qwen VL (图片)
前端框架	Next.js 15 + React 19 (Pages Router)
样式	Tailwind CSS 3.4
编辑器	Monaco Editor (`@monaco-editor/react`)
状态管理	Zustand 5
文档解析	python-docx + PyPDF2
提示模板	Jinja2
校验	jsonschema + PyYAML

6. 里程碑与推进路径

阶段	核心任务	状态
P1	PRD 定稿与架构评审	✅ 完成
P2	代码框架搭建（脚手架、空壳运行、接口占位）	✅ 完成
P3	核心链条实现（DeepSeek+Qwen，PRD→IR→用例全流程）	✅ 完成
P4	热插拔改造（Skill 扫描/加载，电商 Skill 验证，左右分栏 Chat Panel）	✅ 完成
P5	体验打磨（动画、错误处理、性能优化、更多 Skill）	进行中

7. 项目结构（实现后）

zeekerWatchmen/
├── .zeekerwatchmen/              # Agent 灵魂：Skill/记忆/人格
│   ├── soul/                     # principles.yaml + persona.yaml
│   ├── skills/                   # default/ + ecommerce/
│   └── memory/                   # 会话记忆
├── server/                       # Python FastAPI 后端
│   ├── api/routes/               # prd.py, ir.py, testcase.py, skills.py, chat.py
│   ├── core/                     # 底座层（仅基础设施）
│   │   ├── llm_provider/         # base.py, router.py, mock_client.py
│   │   ├── prompt/templates/     # 宽泛框架级 prompt
│   │   ├── personality/          # loader.py (动态人格装配)
│   │   ├── reasoning/            # graph.py (LangGraph 占位)
│   │   └── utils/                # logger.py, diff.py, export_utils.py
│   ├── services/                 # 业务层
│   │   ├── prompts/              # 业务 prompt 模板
│   │   │   ├── ir_step1_semantic_index.txt
│   │   │   └── ir_step2_extraction.txt
│   │   ├── prd_manager/          # WordParser + ImageParser + service
│   │   ├── ir_engine/            # pipeline.py + generator + validator + diff
│   │   ├── testcase_engine/      # generator.py + exporter.py
│   │   └── skill_manager/        # service.py (Skill 扫描/热加载)
│   ├── main.py                   # FastAPI 入口
│   ├── config.py                 # 配置管理 (pydantic-settings + .env)
│   └── requirements.txt
├── web/                          # Next.js 前端
│   ├── src/
│   │   ├── components/           # Layout, UploadZone, IrWorkspace, MindMap,
│   │   │                         # TestCaseTable, ExportPanel, ChatPanel
│   │   ├── pages/                # index.tsx, ir-confirm.tsx, cases.tsx
│   │   ├── hooks/                # usePrd.ts, useIr.ts, useTestcases.ts
│   │   ├── lib/                  # api.ts, types.ts, store.ts
│   │   └── styles/               # globals.css
│   ├── package.json, tsconfig.json, next.config.js, tailwind.config.js
├── docs/                         # PRD.md, ARCHITECTURE.md
├── start.sh                      # 一键启动脚本
├── .env                          # 环境变量 (API Keys, 端口, 模型配置)
├── .gitignore
└── README.md

8. 一键启动

# Linux/WSL:
chmod +x start.sh && ./start.sh

# 访问 http://localhost:3000

start.sh 自动完成：依赖安装检查 → 后端启动 (8765) → 前端启动 (3000) → 输出访问地址。

13 KiB Raw Blame History Unescape Escape

产品需求文档：ZeekerWatchman （测试用例智能管理平台）

1. 产品概述与愿景

1.1 产品愿景

1.2 核心价值主张

2. 用户与核心场景

2.1 目标用户画像

2.2 核心用户故事

3. 系统架构总览（实现后）

3.1 分层原则

4. 核心功能详述（已实现）

4.1 Skill 热插拔体系 (.zeekerwatchmen)

4.2 PRD 解析 (prd_manager)

4.3 3 阶段 IR 生成流水线 (核心升级)

Stage 1：宏观语义索引

Stage 2：逐功能单元 IR 提取

Stage 3：确定性合并与审计

4.4 Chat Panel 交互式编辑

4.5 思维导图可视化 (web/src/components/MindMap.tsx)

4.6 测试用例生成与导出

4.7 LLM 模型配置

5. 技术栈

6. 里程碑与推进路径

7. 项目结构（实现后）

8. 一键启动

13 KiB

Raw Blame History

4.1 Skill 热插拔体系 (`.zeekerwatchmen`)

4.2 PRD 解析 (`prd_manager`)

4.5 思维导图可视化 (`web/src/components/MindMap.tsx`)