# 需求文档-Skill Web 套壳系统

## 1. 项目概述

### 1.1 项目背景
现有 `requirement-generator-v1` Skill 仅能通过 Claude Code CLI 调用，操作门槛较高，不便于分享给其他用户使用。需要为其构建 Web 前端界面，降低使用门槛。

### 1.2 项目目标
将 `requirement-generator-v1` Skill 封装为独立的 Web 应用，实现通过浏览器访问和使用。

---

## 2. 需求范围

### 2.1 功能边界
- **包含**：封装 `requirement-generator-v1` 需求生成 Skill
  - Skill 内部使用的所有工具（文件读写、搜索等）
  - Skill 流程中的用户自然语言输入（如描述项目需求、回答访谈问题）
- **不包含**：不对外暴露 Skill 流程之外的通用 AI 能力
  - 用户不能跳出 Skill 流程，执行其他任意任务（如写代码、改 Bug 等）
  - 通过提示词包裹机制限制操作范围（见 3.6 节）

### 2.2 阶段划分

| 阶段 | 目标 | 运行环境 | 优先级 |
|------|------|----------|--------|
| 第一阶段 | 本机 Web 界面测试验证 | 本地电脑 | 高 |
| 第二阶段 | 服务器部署供他人使用 | 云服务器 | 中 |

### 2.3 各阶段需求汇总

**第一阶段：本机 Web 界面测试验证**

| 类别 | 需求项 |
|------|--------|
| 入口交互 | 点击按钮直接进入流程、无需触发词、无需确认 |
| Skill 内交互 | AskUserQuestion 支持（单选/多选/文本）、实时响应、多轮对话 |
| 权限控制 | 文件操作（Write/Edit）自动执行，无需确认 |
| 输出展示 | 流程状态展示、最终文档（`requirement_final.md`）查看/下载，不支持在线编辑 |
| 边界控制 | 通过提示词包裹机制限制操作范围（见 3.6 节） |
| 成本 | Claude Code MAX 订阅 |

**第二阶段：服务器部署供他人使用**

| 类别 | 需求项 |
|------|--------|
| 继承第一阶段 | 所有第一阶段功能 |
| 多用户支持 | 支持 5-10 人并发，会话和数据隔离 |
| 用户认证 | 需要登录/认证 |
| 多 Skill 入口 | 需求生成 Skill 作为其中一个入口，预留其他 Skill 入口（可扩展） |
| 历史记录 | 历史文档、对话记录、中间数据是否保存（待定） |
| 会话恢复 | 支持中途退出后恢复进度（待定） |
| 成本 | Claude Code MAX 订阅 |
| 模型适配 | 使用 Claude Code MAX，无需额外适配 |

---

## 3. 功能需求

### 3.1 入口交互

| 需求项 | 描述 |
|--------|------|
| 直接进入流程 | 用户点击前端按钮后，直接进入 Skill 执行流程 |
| 无需自然语言触发 | 不需要用户输入"生成需求文档"等触发词 |
| 无需进入确认 | 不需要像 CLI 那样点击确认才能进入 Skill |

### 3.2 Skill 内交互

| 需求项 | 描述 |
|--------|------|
| 问答交互支持 | 支持 Skill 执行过程中的 AskUserQuestion 交互（单选、多选、文本输入） |
| 实时响应 | 用户回答后，流程能够继续执行 |
| 多轮对话 | 支持 Skill 中的多轮访谈流程（如需求收集阶段的多轮提问） |

### 3.3 权限控制

| 需求项 | 描述 |
|--------|------|
| 文件操作自动化 | Write、Edit 等文件操作自动执行，不需要用户逐一确认 |
| 可配置性 | 权限确认行为可通过配置调整（预留能力） |

### 3.4 输出展示

| 需求项 | 描述 |
|--------|------|
| 流程状态展示 | 展示当前执行阶段（访谈中、文档生成中、评审中等） |
| 结果文件访问 | 流程结束后，用户可查看/下载最终版需求文档（`requirement_final.md`） |

### 3.5 多用户与历史记录（第二阶段）

| 需求项 | 描述 | 备注 |
|--------|------|------|
| 多用户并发 | 支持多人同时使用，需隔离各用户的会话和数据 | 初期规模：5-10 人 |
| 历史文档 | 保存历史生成的需求文档 | 待定 |
| 对话记录 | 保存用户与系统的交互过程（访谈问答等） | 待定 |
| 中间数据 | temp 目录下的 JSON 文件（访谈结果、评审记录等） | 待定 |

### 3.6 边界控制（提示词包裹机制）

| 需求项 | 描述 |
|--------|------|
| 适用阶段 | 阶段 5（初稿生成之后、进入多专家评审之前） |
| 机制说明 | 用户的自然语言输入被系统自动包裹为："请根据用户的输入: {用户输入} 来修改需求文档" |
| 安全保障 | 所有操作被限定在文档修改范围内，天然避免危险操作（如执行代码、系统命令等） |
| 实现方式 | 前端或后端在传递用户输入时自动添加包裹提示词 |

---

## 4. 非功能需求

### 4.1 成本控制

| 阶段 | 方案 |
|------|------|
| 第一阶段（本机测试） | Claude Code MAX 订阅 |
| 第二阶段（服务器部署） | Claude Code MAX 订阅 |

**成本约束**：
- 不接受 Anthropic Claude API 按量付费
- 使用 Claude Code MAX 订阅

### 4.2 技术约束

| 约束项 | 说明 |
|--------|------|
| 现有 Skill 复用 | 尽量复用现有 SKILL.md 和 agents/*.md 中的 Prompt 内容 |
| 最小化重写 | Skill 核心逻辑不重写，仅做必要的适配 |

---

## 5. 现有资源

### 5.1 Skill 目录结构

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

### 5.2 相关 Agents

```
.claude/agents/
├── project_type_matcher.md  # 项目类型判断
├── req_writer.md            # 需求文档撰写
├── req_interviewer.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         # 质量审查
```

### 5.3 Skill 执行流程概要

| 阶段 | 步骤 | 使用工具 |
|------|------|----------|
| **阶段 1** | 收集初始想法 | 用户自然语言输入 |
| **阶段 2** | 判断项目类型 | Task（project_type_matcher）、AskUserQuestion |
| **阶段 3** | 执行访谈收集需求 | Read（配置文件、指南）、AskUserQuestion（多轮）、Write（interview_result.json） |
| **阶段 4** | 生成需求文档初稿 | Task（req_writer）、Write（requirement.md） |
| **阶段 5** | 询问用户下一步 | AskUserQuestion（选择下一步操作）、自然语言输入（通过提示词包裹限定为文档修改） |
| **阶段 6** | 多角色评审与文档优化（可选） | 见下方详细说明 |

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

| 子步骤 | 说明 | 使用工具 |
|--------|------|----------|
| 6.1 | 领域识别，生成领域专家角色定义 | Read（requirement.md）、Write（temp/domain_role.md） |
| 6.2 | 并行调用四个评审 Agents | Task（dev_expert_reviewer、pm_reviewer、ai_expert_reviewer、domain_expert_reviewer）、Write（temp/review_*.json） |
| 6.3 | 询问用户决策模式 | AskUserQuestion |
| 6.4 | 整合评审意见，生成最终文档 | Task（req_consolidator 或 req_auto_consolidator）、AskUserQuestion（若参与确认模式）、Write（requirement_final.md、temp/consolidation_report.json） |
| 6.5 | 质量审查 | Task（review_report）、AskUserQuestion（确认业务问题）、Edit（修改文档） |
| 6.6 | 输出最终总结 | 无特殊工具 |

---

## 6. 第二阶段待定事项

| 序号 | 问题 | 分类 |
|------|------|------|
| 1 | 是否需要保存历史生成的需求文档？ | 历史记录 |
| 2 | 是否需要保存对话记录（访谈问答过程）？ | 历史记录 |
| 3 | temp 目录下的中间数据（JSON 文件）是否需要长期保存？ | 历史记录 |
| 4 | 中途退出后恢复进度的具体实现方式？ | 会话恢复 |

---