zeekerWatchmen/docs/PRD.md

# 产品需求文档：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. 一键启动

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

# 访问 http://localhost:3000
```

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