196 lines
7.9 KiB
Markdown
196 lines
7.9 KiB
Markdown
# 需求文档-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 | 中途退出后恢复进度的具体实现方式？ | 会话恢复 |
|
||
|
||
---
|
||
|