# TWU - 测试工作流工具

基于 Claude Code 的纯 CLI 测试用例生成工具链。

**核心原则**：CLI 优先、文件驱动、分批生成、Git 纠偏、所有产物用 Markdown

## 快速开始

### 前置要求

**必需**：
- Python 3.11-3.13
- uv（Python 包管理器）

**安装 uv**：
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 pip
pip install uv
```

---

### 推荐：使用 init 脚本快速开始

```bash
# 1. 克隆 TWU
git clone git@github.com:chyax98/twu.git my-project
cd my-project

# 2. 安装依赖（一次性）
uv sync

# 3. 创建需求项目（自动创建目录结构、CLAUDE.md、README.md、.gitignore）
uv run scripts/init.py --name "需求1-用户登录"

# 4. 在需求目录中工作
cd "需求1-用户登录"
# 填写 CLAUDE.md，上传文档到 original-requirements/
# 在 Claude Code 中执行 /req-parse
```

**init 脚本功能**：
- ✅ 自动创建完整目录结构
- ✅ 复制 CLAUDE.md 模板
- ✅ 生成 README.md 和 .gitignore
- ✅ 提供清晰的下一步指引

---

### 或：手动创建（传统方式）

```bash
# 1. 克隆仓库
git clone git@github.com:chyax98/twu.git
cd twu

# 2. 安装依赖
uv sync

# 3. 手动创建目录
mkdir -p "需求1-用户登录"/{original-requirements,cleaned-requirements,clarified-requirements,test-case}
cp templates/CLAUDE.md "需求1-用户登录/CLAUDE.md"

# 4. 在需求目录中工作
cd "需求1-用户登录"
```

---

## 核心命令

```bash
/req-parse      # 解析需求文档
/req-test       # 生成需求问题清单
/req-merge      # 合并需求澄清，生成完备需求
/testcase-plan  # 生成测试规划
/testcase-gen   # 生成测试用例
```

## 跨平台支持

✅ **所有脚本均支持 Windows/macOS/Linux**

- 使用 Python + uv 确保跨平台一致性
- 自动处理路径分隔符差异
- 统一的依赖管理

## 目录结构

### 核心概念

TWU 采用 **单工具多需求** 的设计：
- ✅ 克隆一次 TWU 仓库
- ✅ 在根目录下创建多个需求子目录
- ✅ 所有需求共享 `.claude/` 配置

### 完整结构示例

```
twu/                           # TWU 根目录（克隆的仓库）
├── .claude/                   # ← TWU 核心配置（所有需求共享）
│   ├── commands/              #    5 个斜杠命令
│   ├── skills/                #    5 个技能实现
│   ├── hooks/
│   └── settings.json
├── scripts/                   # 辅助脚本
│   └── init.py
├── templates/                 # 模板文件
│   └── CLAUDE.md
├── pyproject.toml             # Python 依赖（所有需求共享）
├── 需求1-用户登录/             # ← 需求子目录（init 脚本创建）
│   ├── CLAUDE.md              #    业务背景（每个需求独立）
│   ├── original-requirements/ #    原始文档
│   ├── cleaned-requirements/  #    清洗结果
│   ├── clarified-requirements/#    完备需求
│   └── test-case/             #    测试用例
├── 需求2-订单管理/             # ← 另一个需求
│   └── ...
└── README.md
```

### 关键点

| 文件/目录 | 位置 | 说明 |
|----------|------|------|
| `.claude/` | TWU 根目录 | 所有需求共享，不需要复制 |
| `CLAUDE.md` | 每个需求子目录 | 每个需求独立的业务背景 |
| `pyproject.toml` | TWU 根目录 | 所有需求共享依赖配置 |
| 需求工作目录 | TWU 根目录下的子目录 | init 脚本自动创建 |

**详细说明**: 参见 [docs/目录结构说明.md](docs/目录结构说明.md)

---

### 推荐：多需求结构

```
my-project/                        # 你的项目
├── .claude/                       # TWU 配置（共享）
│   ├── commands/                  # 5 个斜杠命令
│   ├── skills/                    # 5 个技能定义
│   ├── hooks/                     # Hooks
│   └── settings.json
├── 需求1-用户登录/                 # 需求 1 工作目录
│   ├── CLAUDE.md                  # 业务背景
│   ├── original-requirements/     # 原始文档
│   ├── cleaned-requirements/      # 清洗结果
│   ├── clarified-requirements/    # 完备需求
│   └── test-case/                 # 测试用例
├── 需求2-订单管理/                 # 需求 2 工作目录
│   └── ...
└── pyproject.toml                 # 依赖配置（共享）
```

### 或：单需求结构

```
twu/
├── .claude/
├── original-requirements/         # 原始需求文档
├── cleaned-requirements/          # 清洗后的需求
├── clarified-requirements/        # 完备需求
├── test-case/                     # 测试用例
└── CLAUDE.md                      # 业务背景
```

## 依赖说明

核心依赖（已在 `pyproject.toml` 中声明）：
- **docling**: 文档解析（优先）
- **PyPDF2**: PDF 降级方案
- **python-docx**: DOCX 降级方案
- **openpyxl**: Excel 导出

## 架构说明

**TWU 采用 Claude Code Standalone 模式**：
- `.claude/commands/` - 5 个斜杠命令（/req-parse 等）
- `.claude/skills/` - 5 个技能定义（自动调用）
- `.claude/hooks/` - 会话结束 Hook
- `.claude/settings.json` - 配置文件

**路径设计**：使用 `$CLAUDE_PROJECT_DIR` 环境变量，支持从任意子目录执行命令

**不是 Plugin**：TWU 是完整的工作流工具链，直接在项目中使用。

---

## 常见问题

**Q: 没有 uv 怎么办？**
A: 可以使用 pip + venv 替代。

简单示例：
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install docling PyPDF2 python-docx openpyxl pyyaml
python .claude/skills/req-parser/scripts/parse_doc.py --input-dir ... --output-dir ...
```

强烈建议安装 uv（更快、更方便）：`pip install uv`

**Q: Windows 上如何使用？**
A: 安装 uv 后，所有命令都可以直接在 PowerShell/CMD 中运行。

**Q: 如何管理多个需求？**
A: 推荐使用一个 TWU 工程管理多个需求，每个需求一个子目录。

**Q: 可以从需求子目录执行命令吗？**
A: 可以！TWU 使用 `$CLAUDE_PROJECT_DIR` 环境变量，支持从任意子目录执行。

**Q: 如何更新 TWU？**
A: `git pull origin main` 获取最新版本。

**Q: DOCX 解析失败怎么办？**
A: 系统会自动降级到 python-docx，确保已执行 `uv sync` 安装依赖。

---

**仓库地址**：`git@github.com:chyax98/twu.git`