# ZeekerWatchman

测试用例智能管理平台 — 将 PRD 转化为可执行测试用例。

## 快速开始

```bash
./start.sh
```

自动安装依赖、启动后端 (8765) 和前端 (3000)。访问 http://localhost:3000。

### 手动启动

```bash
# 后端
cd server && pip install -r requirements.txt
PYTHONPATH=. uvicorn server.main:app --reload --port 8765

# 前端
cd web && npm install && npm run dev
```

### 环境配置

```env
# .env
ZEEKER_USE_MOCK=true          # 左侧流水线 Mock 开关
ZEEKER_CHAT_USE_MOCK=false    # 右侧 AI 助手 Mock 开关
DEEPSEEK_API_KEY=sk-xxx       # DeepSeek API Key
DASHSCOPE_API_KEY=sk-xxx      # Qwen VL API Key
```

Mock 模式可离线演示全部流程；填入真实 Key 后关闭 Mock 即可使用 LLM。

## 核心工作流

```
上传 PRD (.md/.txt/.docx/.pdf)
  → 3 阶段 IR 流水线 (语义索引 → 逐单元提取 → 合并审计)
    → IR 可视化确认 (YAML 编辑器 + 思维导图 + 审计报告)
      → 生成测试用例 (可编辑表格 + 手动/Chat 增删改)
        → 导出 YAML / CSV / JSON
```

## 架构

```
.zeekerwatchmen/    Agent 灵魂 (Skill/记忆/人格, 热插拔)
server/core/        底座层 (LLM 客户端/路由, 仅基础设施)
server/services/    业务层 (PRD 解析, IR 流水线, 用例引擎, Chat, prompt 模板)
web/                Next.js 前端 (左右分栏: 主工作区 + AI Chat Panel)
```

## 主要功能

**PRD 解析**
- .docx 解析: 类型化 blocks (para/table)、表头检测、`[[IMAGE:rid]]` 标记
- 图片分析: Qwen VL 识别流程图/架构图/UI 截图
- .md/.txt/.pdf 支持

**3 阶段 IR 流水线**
- Stage 1: 语义索引 — 全文档 → function_units + concepts
- Stage 2: 逐单元 IR 提取 — 精准上下文包 → 详细规则 (trigger/actions/precondition)
- Stage 3: 合并去重 + 审计报告 (覆盖率/优先级分布)

**IR 可视化**
- Monaco 编辑器 + SVG 思维导图 (按 section 分组, 多行自适应换行)
- 点击思维导图节点 → 编辑器定位对应行
- Audit Report 折叠面板

**测试用例**
- 表格支持行内编辑 (文本/下拉/textarea)
- 手动添加 + Chat LLM 增删改
- 导出 YAML / CSV / JSON (前端直出, 无需后端)
- ID 格式: `TC-{FEATURE}-{NNN}`, 自动分配不重复

**右侧 AI Chat Panel**
- 跨页面持久 (Zustand store)
- 页面感知 (IR/Cases/Home 不同上下文)
- 增量操作 (add/delete/modify) + 自动执行/确认双模式
- 选中行上下文传递 (说"这条"即操作选中条目)
- Session ID 自动刷新, 支持新建会话

**Skill 热插拔**
- `GET /api/skills` 自动扫描 `.zeekerwatchmen/skills/`
- `POST /api/skills/reload` 热重载
- 内置 default (通用) + ecommerce (电商) 双 Skill

**LLM**
- 文本: DeepSeek (`deepseek-v4-flash`)
- 图片: Qwen VL (`qwen3-vl-plus`)
- 独立 Mock 开关 (左侧流水线 / 右侧 Chat 分开控制)

## 项目结构

```
zeekerWatchmen/
├── .zeekerwatchmen/            # Agent 灵魂
│   ├── soul/                   # principles.yaml + persona.yaml
│   ├── skills/{default,ecommerce}/
│   └── memory/                 # 会话记忆
├── server/
│   ├── api/routes/             # prd, ir, testcase, skills, chat
│   ├── core/
│   │   ├── llm_provider/       # base, router, mock_client
│   │   ├── prompt/templates/   # 框架级 prompt
│   │   ├── personality/        # 动态人格加载
│   │   └── utils/              # logger, diff, export
│   ├── services/
│   │   ├── prompts/            # chat_system.md, ir_step1/2
│   │   ├── prd_manager/        # WordParser, ImageParser
│   │   ├── ir_engine/          # pipeline (3-stage), validator, diff
│   │   ├── testcase_engine/    # generator, exporter
│   │   └── skill_manager/      # Skill 扫描/热加载
│   ├── main.py, config.py
│   └── requirements.txt
├── web/
│   ├── src/
│   │   ├── components/         # Layout, UploadZone, IrWorkspace, MindMap,
│   │   │                       # TestCaseTable, PipelineProgress, ChatPanel
│   │   ├── pages/              # index, ir-confirm, cases
│   │   └── lib/                # api, types, store
│   └── package.json
├── docs/
│   ├── PRD.md
│   ├── ARCHITECTURE.md
│   ├── ir_schema.json          # IR JSON Schema
│   └── tc_schema.json          # Test Case JSON Schema
├── start.sh                    # 一键启动
├── .env
└── .gitignore
```

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/prd/upload | 上传 PRD 文件 |
| GET  | /api/prd/{id} | 获取 PRD 详情 |
| GET  | /api/ir/generate-stream | SSE 流式 IR 生成 |
| POST | /api/ir/generate | 同步 IR 生成 |
| PUT  | /api/ir/{id} | 更新 IR |
| GET  | /api/skills | 列出 Skill |
| POST | /api/testcase/generate | 生成测试用例 |
| POST | /api/chat | AI 对话 |