# 需求文档-Skill Web 套壳系统（第一阶段）

## 1. 项目概述

### 1.1 项目背景
现有 `requirement-generator-v1` Skill 仅能通过 Claude Code CLI 调用，操作门槛较高。需要为其构建 Web 前端界面，实现本地浏览器访问和使用。

### 1.2 项目目标
在本地环境搭建 Web 界面，通过浏览器调用 `requirement-generator-v1` Skill，验证 Web 化可行性。

### 1.3 阶段定位
**第一阶段：本机 Web 界面测试验证**
- 运行环境：本地电脑（Windows/macOS）
- 用户范围：开发者本人
- 目标：验证技术方案可行性，为后续服务器部署提供参考

---

## 2. 功能需求

### 2.1 入口交互

| 需求项 | 描述 | 优先级 |
|--------|------|--------|
| 直接启动流程 | 用户打开 Web 页面后，点击"生成需求文档"按钮，直接进入 Skill 执行流程 | P0 |
| 无需触发词 | 不需要用户输入"生成需求文档"等自然语言触发词 | P0 |
| 无需二次确认 | 不需要像 CLI 那样弹出确认对话框（"是否进入 Skill？"） | P1 |

**设计说明**：
- 页面中央显示"生成需求文档"按钮
- 点击后立即进入 Skill 阶段 1（收集初始想法）

---

### 2.2 Skill 内交互

| 需求项 | 描述 | 优先级 |
|--------|------|--------|
| AskUserQuestion 支持 | 完整支持单选、多选、文本输入三种问答类型 | P0 |
| 实时响应 | 用户提交答案后，Skill 流程继续执行，无需刷新页面 | P0 |
| 多轮对话 | 支持阶段 3 的多轮访谈流程（连续多次提问） | P0 |
| CLI 主窗口级别可视化 | 还原 CLI 主窗口显示内容（工具调用、Assistant 回复等） | P0 |

**设计说明**：
- 问答界面模仿 Claude Code CLI 的交互形式
- 单选/多选：展示选项列表 + "Other"输入框
- 文本输入：展示文本框
- **只展示 CLI 主窗口的内容**（工具调用、Assistant 回复、AskUserQuestion 等）
- **不需要展示 Ctrl+o 才能看到的内容**（Agent 内部输出、思考过程、详细日志等）
- **不需要额外的进度条、阶段指示器等 UI 增强**
- **所有 AskUserQuestion 均由主窗口发起**（Sub-agent 无法直接发起用户交互，会返回问题给主窗口处理）

---

### 2.3 权限控制

| 需求项 | 描述 | 优先级 |
|--------|------|--------|
| 文件操作自动执行 | Write、Edit、Read 等文件操作自动执行，无需用户确认 | P0 |
| 文件写入位置 | 需求文档（`requirement.md`、`requirement_final.md`）写入项目根目录；中间数据写入 `temp/` 目录 | P0 |
| 会话结束后清理 | （可选）会话结束后提示是否清理临时文件 | P2 |

**设计说明**：
- 本阶段不需要权限配置界面
- 所有文件操作直接执行，无弹窗确认
- Skill 启动时会自动清空历史缓存文件（见 4.3 前置操作）

---

### 2.4 输出展示

| 需求项 | 描述 | 优先级 |
|--------|------|--------|
| 最终文档展示 | 流程结束后，显示生成的需求文档内容（Markdown 渲染） | P0 |
| 文件下载 | 提供"下载为 Markdown"按钮 | P0 |
| 文档文件识别 | 自动识别输出文档：`requirement_final.md`（阶段 6）或 `requirement.md`（阶段 4） | P1 |
| 不支持在线编辑 | 只能查看和下载，不能在 Web 界面中编辑文档 | - |

**设计说明**：
- 优先展示 `requirement_final.md`，若不存在则展示 `requirement.md`
- 使用 Markdown 渲染库（如 `marked.js` 或 `react-markdown`）

---

### 2.5 边界控制

| 需求项 | 描述 | 优先级 |
|--------|------|--------|
| 阶段 5 提示词包裹 | 用户输入被自动包裹为："请根据用户的输入: {用户输入} 来修改需求文档" | P0 |

---

## 3. 非功能需求

### 3.1 技术约束

| 约束项 | 说明 |
|--------|------|
| 模型调用 | 使用 Claude Code MAX 订阅 |
| Skill 复用 | 直接复用现有 `SKILL.md` 和 `agents/*.md`，不修改核心 Prompt |
| 文件系统依赖 | 依赖本地文件系统进行 Read/Write 操作 |
| Sub-agent 交互限制 | Sub-agent 无法使用 AskUserQuestion（v2.0.56+ 限制），用户交互统一由主窗口处理 |

---

## 4. 现有资源

### 4.1 Skill 目录结构

```
.claude/skills/requirement-generator-v1/
├── SKILL.md                 # 主流程定义（6 个阶段）
├── assets/                  # 项目类型配置
├── templates/               # 文档模板
├── references/              # 执行指南
└── temp/                    # 中间数据存储
```

### 4.2 相关 Agents

```
.claude/agents/
├── project_type_matcher.md  # 项目类型判断
├── req_writer.md            # 需求文档撰写
├── pm_reviewer.md           # 产品经理评审
├── dev_expert_reviewer.md   # 开发专家评审
├── ai_expert_reviewer.md    # AI 专家评审
├── domain_expert_reviewer.md # 领域专家评审
├── req_consolidator.md      # 需求整合（人工确认）
├── req_auto_consolidator.md # 需求整合（自动）
└── review_report.md         # 质量审查（自动修复，不与用户交互）
```

**注意**：`req_interviewer.md` 存在但未被调用，阶段 3 访谈由主窗口直接执行。

### 4.3 Skill 执行流程概要

| 阶段 | 步骤 | 执行者 | 使用工具 |
|------|------|--------|----------|
| **前置** | 清空历史缓存 | 主窗口 | Bash（rm） |
| **阶段 1** | 收集初始想法 | 主窗口 | 用户自然语言输入 |
| **阶段 2** | 判断项目类型 | 主窗口 + Sub-agent | Task（project_type_matcher）、AskUserQuestion |
| **阶段 3** | 执行访谈收集需求 | **主窗口** | Read（配置文件、指南）、AskUserQuestion（多轮）、Write（interview_result.json） |
| **阶段 4** | 生成需求文档初稿 | Sub-agent | Task（req_writer）→ Write（requirement.md） |
| **阶段 5** | 询问用户下一步 | 主窗口 | AskUserQuestion / 自然语言输入 |
| **阶段 6** | 多角色评审与文档优化（可选） | 见下方详细说明 | - |

**前置：清空历史缓存**

Skill 启动时先清空上一次执行的缓存文件：
```bash
rm -f requirement.md requirement_final.md
rm -f temp/interview_result.json temp/domain_role.md
rm -f temp/review_dev.json temp/review_pm.json temp/review_ai.json temp/review_domain.json
rm -f temp/consolidation_report.json
```

**阶段 6 详细工具使用**：

| 子步骤 | 说明 | 执行者 | 使用工具 |
|--------|------|--------|----------|
| 6.1 | 领域识别，生成领域专家角色定义 | 主窗口 | Read（requirement.md）、Write（temp/domain_role.md） |
| 6.2 | 并行调用四个评审 Agents | Sub-agent（×4） | Task（并行调用 4 个评审 Agent）→ Write（temp/review_*.json） |
| 6.3 | 询问用户决策模式 | 主窗口 | AskUserQuestion |
| 6.4a | 整合评审意见（人工确认） | Sub-agent + 主窗口 | **多轮调用** Task（req_consolidator）：init返回问题 → 主窗口AskUserQuestion → continue传入答案 → 循环直到completed |
| 6.4b | 整合评审意见（自动应用） | Sub-agent | Task（req_auto_consolidator）→ Write（requirement_final.md、consolidation_report.json） |
| 6.5 | 质量审查 | Sub-agent + 主窗口 | Task（review_report，**自动修复**）→ **返回待确认问题给主窗口** → 主窗口 AskUserQuestion |
| 6.6 | 输出最终总结 | 主窗口 | 无特殊工具 |

**关键技术约束**：Sub-agent（Task 调用的 Agent）无法使用 AskUserQuestion 工具（Claude Code v2.0.56+ 限制，GitHub Issue #12890）。需要用户交互的场景由主窗口处理。

---

## 5. 交付物

| 交付物 | 说明 |
|--------|------|
| Web 界面 | 可在浏览器中打开的 HTML 页面 |
| 启动脚本 | 一键启动前端/后端服务的脚本 |
| 技术文档 | 记录调用 Claude Code 的方法、文件路径规则等 |
| 测试报告 | 验证完整流程可执行性的测试记录 |

---

## 6. 成功标准

- [ ] 用户可以通过浏览器打开 Web 界面
- [ ] 点击"生成需求文档"按钮后，Skill 流程正常启动
- [ ] 可以正常回答 AskUserQuestion 的问题（单选/多选/文本）
- [ ] 完整走通阶段 1-6 的流程
- [ ] 最终能查看和下载生成的需求文档
- [ ] 临时文件正常写入本地 temp/ 目录