8.2 KiB
8.2 KiB
需求文档-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 启动时先清空上一次执行的缓存文件：
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/ 目录