@zeyue0329/xiaoma-cli 1.0.7 → 1.0.8

package/XiaoMa-Web/345/244/232/346/231/272/350/203/275/344/275/2230-1/351/241/271/347/233/256/345/274/200/345/217/221/345/256/214/346/225/264/346/214/207/345/215/227.md

@@ -0,0 +1,977 @@
+# XiaoMa-Web 多智能体 0-1 项目开发完整指南
+
+基于 XiaoMa-Web 通用 AI 代理框架的详细开发流程，从零开始创建项目到完整交付的每一步操作指南。
+
+## 🚀 前置准备
+
+### 环境初始化
+```bash
+# 1. 创建新项目目录
+mkdir my-project && cd my-project
+
+# 2. 初始化 npm 项目
+npm init -y
+
+# 3. 安装 XiaoMa-Web 框架
+npx xiaoma-web install
+# 或者使用 npm 命令
+npm run install:xiaoma
+
+# 4. 验证安装成功
+npm run list:agents
+# 预期输出：显示所有可用的智能体列表
+
+# 5. 创建必要的目录结构
+mkdir -p docs/prd docs/architecture docs/stories
+```
+
+**成功标准**：
+- ✅ 项目根目录下生成 `.xiaoma/` 配置目录
+- ✅ `npm run list:agents` 命令能正常显示智能体列表
+- ✅ docs 目录结构创建完成
+
+## 🎯 总体架构
+
+**双阶段开发模式**：
+- **规划阶段**（Web UI）：需求分析、产品设计、技术架构
+- **开发阶段**（IDE）：敏捷开发、代码实现、测试验收
+
+**核心智能体及其职责**：
+- `analyst`：业务分析师，负责需求调研和项目概要
+- `pm`：产品经理，负责 PRD 文档创建和维护
+- `ux-expert`：UX 专家，负责前端设计规范和 AI 提示词
+- `architect`：系统架构师，负责技术架构设计
+- `po`：产品负责人，负责文档验证和分片管理
+- `sm`：敏捷教练，负责故事创建和管理
+- `dev`：开发工程师，负责代码实现
+- `qa`：质量保证工程师，负责代码审查和质量控制
+
+## 📋 阶段一：项目规划（Web UI 环境）
+
+### 1.1 业务分析阶段
+**智能体**：`analyst`
+**输出文档**：`project-brief.md`
+
+**操作步骤**：
+```bash
+# 在 Web UI 中
+@analyst
+```
+
+**具体任务**：
+- 可选：头脑风暴会议（`brainstorming_session`）
+- 可选：市场调研（`market_research_prompt`）
+- 创建项目概要文档
+- **保存输出**：将 `project-brief.md` 复制到项目的 `docs/` 文件夹
+
+### 1.2 产品需求文档创建
+**智能体**：`pm`
+**输入依赖**：`project-brief.md`
+**输出文档**：`prd.md`
+
+**操作步骤**：
+```bash
+# 确保 project-brief.md 已保存到 docs/
+@pm
+```
+
+**具体任务**：
+- 基于项目概要使用 `prd-tmpl` 模板创建 PRD
+- **保存输出**：将最终的 `prd.md` 复制到项目的 `docs/` 文件夹
+
+### 1.3 用户体验设计
+**智能体**：`ux-expert`
+**输入依赖**：`prd.md`
+**输出文档**：`front-end-spec.md`
+
+**操作步骤**：
+```bash
+# 确保 prd.md 已保存到 docs/
+@ux-expert
+```
+
+**具体任务**：
+- 可选：用户研究（`user_research_prompt`）
+- 使用 `front-end-spec-tmpl` 创建 UI/UX 规范
+- **保存输出**：将 `front-end-spec.md` 复制到项目的 `docs/` 文件夹
+
+### 1.4 AI 前端代码生成（可选但推荐）
+**智能体**：`ux-expert`
+**输入依赖**：`front-end-spec.md`
+**输出**：v0 提示词
+
+**操作步骤**：
+```bash
+# 在完成前端规范后
+@ux-expert
+# 使用 generate-ai-frontend-prompt 任务
+```
+
+**具体任务**：
+- 生成适用于 v0、Lovable 等工具的 AI 前端提示词
+- 用户在外部工具中生成 UI 并下载项目结构
+- 为后续架构设计提供具体的项目结构参考
+
+### 1.5 系统架构设计
+**智能体**：`architect`
+**输入依赖**：`prd.md` + `front-end-spec.md`
+**输出文档**：`fullstack-architecture.md`
+
+**操作步骤**：
+```bash
+# 确保 PRD 和前端规范都已保存
+@architect
+```
+
+**具体任务**：
+- 可选：技术调研（`technical_research_prompt`）
+- 可选：审查生成的 UI 结构（如果使用了 v0/Lovable）
+- 使用 `fullstack-architecture-tmpl` 创建综合架构
+- 可能建议对 PRD 故事的修改或新增
+- **保存输出**：将 `fullstack-architecture.md` 复制到项目的 `docs/` 文件夹
+
+### 步骤 1.6：PRD 更新（条件触发）
+
+**使用智能体**：`pm`
+**执行环境**：Web UI (ChatGPT/Gemini)
+**触发条件**：架构师在步骤 1.5 中建议 PRD 变更
+**输入文件**：`docs/fullstack-architecture.md` + 架构师的修改建议
+**输出文件**：`docs/prd.md`（更新版）
+
+#### 详细操作步骤：
+
+1. **判断是否需要执行**
+   ```
+   # 检查架构师的反馈
+   如果架构文档包含以下内容，则需要更新 PRD：
+   - "建议修改用户故事..."
+   - "需要新增技术故事..."
+   - "某些功能在技术上不可行..."
+   ```
+
+2. **重新加载 PM 智能体**
+   ```
+   # 新会话或继续之前的会话
+   @pm
+   
+   # 提供架构师的反馈
+   架构师提出了以下修改建议：
+   [粘贴架构师的具体建议]
+   ```
+
+3. **执行 PRD 更新命令**
+   ```
+   # 命令序列
+   1. 请根据架构师的反馈更新相关的用户故事
+   2. 如需要，请添加新的技术故事
+   3. 请重新评估故事的优先级
+   4. 请生成更新后的完整 PRD 文档
+   ```
+
+4. **验证更新内容**
+   - [ ] 所有架构师的建议都已处理
+   - [ ] 新增的技术故事有清晰的验收标准
+   - [ ] 优先级调整合理
+   - [ ] 文档版本号已更新
+
+5. **保存更新的 PRD**
+   ```bash
+   # 备份原始 PRD
+   mv docs/prd.md docs/prd-v1.md
+   
+   # 保存新版本
+   echo "[更新后的 PRD]" > docs/prd.md
+   
+   # 记录变更日志
+   echo "PRD 更新：根据架构反馈调整" >> docs/changelog.md
+   ```
+
+**成功标准**：
+- ✅ 架构师的所有建议都已整合
+- ✅ PRD 与架构文档完全对齐
+- ✅ 没有技术不可行的故事
+
+**进入下一步的条件**：
+- PRD 更新完成
+- 与架构文档无冲突
+
+### 步骤 1.7：文档验证与批准
+
+**使用智能体**：`po`（产品负责人）
+**执行环境**：Web UI (ChatGPT/Gemini)
+**输入文件**：所有规划阶段文档
+**输出**：验证报告 + 批准状态
+
+#### 详细操作步骤：
+
+1. **准备所有文档**
+   ```
+   # 在 Web UI 中提供所有文档
+   以下是所有规划文档：
+   
+   1. Project Brief:
+   [粘贴 project-brief.md]
+   
+   2. PRD:
+   [粘贴 prd.md]
+   
+   3. Frontend Spec:
+   [粘贴 front-end-spec.md]
+   
+   4. Architecture:
+   [粘贴 fullstack-architecture.md]
+   ```
+
+2. **加载 PO 智能体**
+   ```
+   @po
+   ```
+
+3. **执行验证命令**
+   ```
+   # 主命令
+   请使用 po-master-checklist 对所有文档进行全面验证
+   
+   # 具体检查项
+   请验证：
+   1. PRD 与 Project Brief 的一致性
+   2. Frontend Spec 是否覆盖所有 PRD 功能
+   3. Architecture 是否支持所有业务需求
+   4. 文档之间是否有冲突或遗漏
+   ```
+
+4. **PO 验证清单**
+   ```
+   验证项目：
+   □ 业务目标对齐
+   □ 用户故事完整性
+   □ 技术可行性确认
+   □ 优先级合理性
+   □ 依赖关系清晰
+   □ 风险已识别
+   □ 时间线可实现
+   ```
+
+5. **处理验证结果**
+   ```bash
+   # 如果发现问题
+   # 场景 A：需要修改 PRD
+   返回步骤 1.2，使用 @pm 修改
+   
+   # 场景 B：需要调整架构
+   返回步骤 1.5，使用 @architect 调整
+   
+   # 场景 C：所有文档通过验证
+   echo "✅ 所有文档验证通过" >> docs/validation-report.md
+   echo "批准进入开发阶段" >> docs/validation-report.md
+   ```
+
+6. **最终确认**
+   ```bash
+   # 确认所有文档都在正确位置
+   ls -la docs/
+   # 应该看到：
+   # - project-brief.md
+   # - prd.md
+   # - front-end-spec.md
+   # - fullstack-architecture.md
+   # - validation-report.md
+   ```
+
+**成功标准**：
+- ✅ 所有文档相互一致
+- ✅ 没有功能遗漏或冲突
+- ✅ PO 正式批准进入开发
+- ✅ 所有文档已保存到 docs/ 目录
+
+**进入下一步的条件**：
+- PO 验证通过
+- 所有文档就绪
+- 准备切换到 IDE 环境
+
+### 步骤 1.8：环境切换准备
+
+**从 Web UI 切换到 IDE**
+
+#### 切换前检查清单：
+
+1. **文档完整性检查**
+   ```bash
+   # 在项目根目录执行
+   find docs -name "*.md" -type f | sort
+   
+   # 期望输出：
+   # docs/project-brief.md
+   # docs/prd.md
+   # docs/front-end-spec.md
+   # docs/fullstack-architecture.md
+   # docs/validation-report.md
+   ```
+
+2. **项目结构设置**
+   ```bash
+   # 根据架构决策设置项目结构
+   
+   # 选项 A：单仓库结构
+   mkdir -p apps/web apps/api
+   mv [前端代码] apps/web/
+   
+   # 选项 B：多仓库结构
+   # frontend repo: my-project-frontend/
+   # backend repo: my-project-backend/
+   # docs repo: my-project-docs/
+   ```
+
+3. **IDE 环境准备**
+   ```bash
+   # 安装 VS Code 或其他 IDE
+   # 安装必要的扩展
+   # - XiaoMa 扩展（如果有）
+   # - 语言相关扩展
+   
+   # 在 IDE 中打开项目
+   code .
+   ```
+
+4. **验证 XiaoMa 在 IDE 中可用**
+   ```bash
+   # 在 IDE 终端中
+   npm run list:agents
+   
+   # 确认可以看到开发阶段的智能体：
+   # - po (产品负责人)
+   # - sm (敏捷教练)
+   # - dev (开发者)
+   # - qa (质量保证)
+   ```
+
+**成功标准**：
+- ✅ 所有规划文档已保存
+- ✅ 项目结构已按架构设置
+- ✅ IDE 环境配置完成
+- ✅ 可以在 IDE 中访问智能体
+
+**进入开发阶段的标志**：
+- Web UI 阶段正式结束
+- 切换到 IDE 进行代码开发
+
+## 📝 阶段二：开发准备（IDE 环境）
+
+### 步骤 2.1：文档分片
+
+**使用智能体**：`po`（产品负责人）
+**执行环境**：IDE (VS Code/Cursor/WebStorm)
+**输入文件**：`docs/prd.md` 和 `docs/fullstack-architecture.md`
+**输出**：分片文档目录
+
+#### 详细操作步骤：
+
+1. **创建分片目录结构**
+   ```bash
+   # 在项目根目录执行
+   mkdir -p docs/prd/epics
+   mkdir -p docs/architecture/components
+   mkdir -p docs/stories
+   
+   # 验证目录创建
+   tree docs -d
+   ```
+
+2. **在 IDE 中加载 PO 智能体**
+   ```
+   # 在 IDE 的 AI 对话中
+   @po
+   ```
+
+3. **执行文档分片命令**
+   ```
+   # 命令 1：分片 PRD
+   请执行 shard-doc 任务，分片 docs/prd.md
+   将每个 Epic 保存到 docs/prd/epics/ 目录
+   
+   # 命令 2：分片架构文档
+   请分片 docs/fullstack-architecture.md
+   将模块保存到 docs/architecture/components/ 目录
+   ```
+
+4. **分片结果验证**
+   ```bash
+   # 检查分片后的文件
+   ls -la docs/prd/epics/
+   # 预期输出：
+   # epic-01-user-authentication.md
+   # epic-02-dashboard.md
+   # epic-03-data-management.md
+   # ...
+   
+   ls -la docs/architecture/components/
+   # 预期输出：
+   # api-design.md
+   # database-schema.md
+   # frontend-components.md
+   # ...
+   ```
+
+5. **创建分片索引文件**
+   ```bash
+   # 创建索引便于跟踪
+   echo "# 文档分片索引" > docs/shard-index.md
+   echo "## PRD Epics" >> docs/shard-index.md
+   ls docs/prd/epics/ >> docs/shard-index.md
+   echo "## Architecture Components" >> docs/shard-index.md
+   ls docs/architecture/components/ >> docs/shard-index.md
+   ```
+
+**分片规则**：
+- 每个分片文件不超过 500 行
+- 按逻辑单元分片（一个 Epic = 一个文件）
+- 保留引用关系和依赖信息
+- 每个分片文件包含完整上下文
+
+**成功标准**：
+- ✅ PRD 被分解为 3-8 个 Epic 文件
+- ✅ 架构文档被分解为模块化组件
+- ✅ 每个分片文件可独立理解
+- ✅ 分片索引文件创建完成
+
+**进入下一步的条件**：
+- 文档分片完成
+- 准备开始敏捷开发循环
+
+## 🔄 阶段三：敏捷开发循环（IDE 环境）
+
+### 3.1 故事创建
+**智能体**：`sm`（敏捷教练）
+**输入依赖**：分片文档
+**输出文档**：`story.md`
+
+**操作步骤**：
+```bash
+# 在新的聊天窗口中
+@sm → *create
+```
+
+**具体任务**：
+- 基于分片的史诗文档创建下一个故事
+- 故事初始状态为 "Draft"（草稿）
+- 为每个史诗重复此过程
+
+### 3.2 故事审查（可选）
+**智能体**：`analyst` 或 `pm`
+**输入依赖**：`story.md`
+**操作**：审查并批准草稿故事
+
+**操作步骤**：
+```bash
+# 如果需要故事审查
+@analyst 或 @pm
+# 注意：story-review 任务即将推出
+```
+
+**具体任务**：
+- 审查故事的完整性和对齐度
+- 将故事状态从 "Draft" 更新为 "Approved"
+
+### 3.3 故事实现
+**智能体**：`dev`（开发工程师）
+**输入依赖**：已批准的 `story.md`
+**输出**：实现文件
+
+**操作步骤**：
+```bash
+# 在新的聊天窗口中
+@dev
+```
+
+**具体任务**：
+- 实现已批准的故事
+- 更新文件列表记录所有变更
+- 完成后将故事标记为 "Review"
+
+### 3.4 代码审查（可选但推荐）
+**智能体**：`qa`（质量保证工程师）
+**输入依赖**：实现文件
+**操作**：审查实现质量
+
+**操作步骤**：
+```bash
+# 在新的聊天窗口中
+@qa → review-story
+```
+
+**具体任务**：
+- 高级开发审查，具备重构能力
+- 直接修复小问题
+- 为剩余问题留下检查清单
+- 更新故事状态（Review → Done 或保持 Review）
+
+### 3.5 解决 QA 反馈（条件触发）
+**智能体**：`dev`
+**触发条件**：QA 留下了未检查的项目
+
+**操作步骤**：
+```bash
+# 如果 QA 留下未完成项目
+# 在新的聊天窗口中
+@dev
+# 解决剩余问题
+# 返回 QA 进行最终批准
+```
+
+### 步骤 3.7：开发循环重复
+
+**循环流程**：
+```
+SM 创建故事 → Dev 实现 → QA 审查 → [修复] → 完成
+     ↓                                           ↑
+     ←←←←←←←← 下一个故事 ←←←←←←←←←
+```
+
+#### 循环管理：
+
+1. **故事进度跟踪**
+   ```bash
+   # 创建进度跟踪文件
+   cat > docs/sprint-progress.md << EOF
+   # Sprint 进度
+   
+   ## Epic-01: 用户认证
+   - [x] Story-001: 登录功能
+   - [ ] Story-002: 注册功能
+   - [ ] Story-003: 密码重置
+   
+   ## Epic-02: 仪表板
+   - [ ] Story-004: 数据展示
+   - [ ] Story-005: 图表组件
+   EOF
+   ```
+
+2. **切换到下一个故事**
+   ```bash
+   # 返回步骤 3.1
+   # SM 创建 Story-002
+   @sm
+   请基于 Epic-01 创建下一个故事 (Story-002)
+   ```
+
+3. **Epic 完成标准**
+   ```
+   当一个 Epic 的所有故事完成：
+   - 所有故事状态 = Done
+   - 所有验收标准通过
+   - 集成测试通过
+   → 进入下一个 Epic
+   ```
+
+**继续条件**：
+- 直到所有 Epic 完成
+- 直到 PRD 中所有故事实现
+
+## 🎉 阶段四：项目完成
+
+### 步骤 4.1：史诗回顾（可选但推荐）
+
+**使用智能体**：`po`
+**执行环境**：IDE
+**触发条件**：每个 Epic 完成后
+**输出文件**：`docs/retrospectives/epic-XX-retrospective.md`
+
+#### 详细操作步骤：
+
+1. **创建回顾目录**
+   ```bash
+   mkdir -p docs/retrospectives
+   ```
+
+2. **进行史诗回顾**
+   ```
+   @po
+   
+   Epic-01 已完成，请进行回顾：
+   - 验证所有故事是否满足原始需求
+   - 记录开发过程中的经验教训
+   - 识别可以改进的流程
+   - 评估质量和性能
+   ```
+
+3. **生成回顾报告**
+   ```bash
+   # PO 生成回顾后保存
+   echo "[回顾内容]" > docs/retrospectives/epic-01-retrospective.md
+   ```
+
+### 步骤 4.2：最终项目验证
+
+#### 完整性检查清单：
+
+1. **功能完整性验证**
+   ```bash
+   # 检查所有故事状态
+   find docs/stories -name "*.md" -exec grep -l "Done" {} \;
+   
+   # 运行完整测试套件
+   npm run test:all
+   npm run test:e2e
+   ```
+
+2. **文档完整性检查**
+   ```bash
+   # 验证所有必要文档存在
+   ls -la docs/
+   # 应包含：
+   # - 所有规划文档
+   # - 分片文档
+   # - 故事文档
+   # - 回顾文档
+   ```
+
+3. **代码质量最终检查**
+   ```bash
+   # 代码质量检查
+   npm run lint
+   npm run typecheck
+   npm run build
+   
+   # 安全扫描
+   npm audit
+   ```
+
+### 步骤 4.3：项目交付准备
+
+1. **生成项目报告**
+   ```bash
+   cat > docs/PROJECT-SUMMARY.md << EOF
+   # 项目完成总结
+   
+   ## 项目概述
+   - 项目名称：[项目名]
+   - 完成日期：$(date)
+   - 总 Epic 数：[数量]
+   - 总 Story 数：[数量]
+   
+   ## 交付物清单
+   - [ ] 前端应用
+   - [ ] 后端 API
+   - [ ] 数据库 Schema
+   - [ ] 部署脚本
+   - [ ] 测试套件
+   - [ ] 文档
+   
+   ## 技术栈
+   - 前端：[技术栈]
+   - 后端：[技术栈]
+   - 数据库：[数据库]
+   - 部署：[部署方案]
+   EOF
+   ```
+
+2. **创建部署指南**
+   ```bash
+   cat > DEPLOYMENT.md << EOF
+   # 部署指南
+   
+   ## 环境要求
+   - Node.js >= [版本]
+   - [其他要求]
+   
+   ## 部署步骤
+   1. 克隆仓库
+   2. 安装依赖
+   3. 配置环境变量
+   4. 运行部署脚本
+   EOF
+   ```
+
+**项目完成标准**：
+- ✅ 所有 PRD 故事实现完成
+- ✅ 所有测试通过
+- ✅ 代码质量检查通过
+- ✅ 部署文档齐全
+- ✅ 项目可以成功部署运行
+
+## 🛠️ 核心命令快速参考
+
+### 环境设置命令
+```bash
+# 项目初始化
+mkdir my-project && cd my-project
+npm init -y
+npx xiaoma-web install
+
+# 验证安装
+npm run list:agents
+npm run validate
+
+# 目录结构创建
+mkdir -p docs/prd docs/architecture docs/stories
+```
+
+### 阶段一：规划阶段（Web UI）
+```bash
+# 按顺序执行每个智能体
+@analyst              # 1. 创建 project-brief.md
+@pm                   # 2. 创建 prd.md (基于 project-brief)
+@ux-expert           # 3. 创建 front-end-spec.md + AI 提示词
+@architect           # 4. 创建 fullstack-architecture.md
+@pm                   # 5. 更新 PRD (如果架构师建议)
+@po                   # 6. 验证所有文档一致性
+```
+
+### 阶段二：文档分片（IDE）
+```bash
+# IDE 环境中
+@po                  # 分片 docs/prd.md 和 docs/fullstack-architecture.md
+# 结果：docs/prd/epics/ 和 docs/architecture/components/
+```
+
+### 阶段三：开发循环（IDE）
+```bash
+# 每个故事的完整流程
+@sm                  # 1. 创建故事 (基于 Epic)
+@analyst 或 @pm      # 2. 故事审查 (可选)
+@dev                 # 3. 实现故事
+@qa                  # 4. 代码审查
+@dev                 # 5. 修复反馈 (如需要)
+@qa                  # 6. 最终确认
+
+# 重复直到所有故事完成
+```
+
+### 阶段四：项目完成
+```bash
+# 项目验证
+npm run test:all
+npm run lint
+npm run build
+
+# 生成交付文档
+@po                  # 史诗回顾
+# 手动创建 PROJECT-SUMMARY.md 和 DEPLOYMENT.md
+```
+
+## ❓ 常见问题和故障排除
+
+### 环境问题
+
+**Q: `npm run install:xiaoma` 失败**
+```bash
+# 解决方案
+# 1. 确保 Node.js 版本 >= 16
+node --version
+
+# 2. 清理 npm 缓存
+npm cache clean --force
+
+# 3. 尝试替代安装方法
+npx xiaoma-web install
+```
+
+**Q: `npm run list:agents` 显示空列表**
+```bash
+# 解决方案
+# 1. 检查是否在正确目录
+ls -la | grep xiaoma
+
+# 2. 重新安装
+rm -rf .xiaoma
+npx xiaoma-web install
+
+# 3. 验证安装
+npm run validate
+```
+
+### 智能体使用问题
+
+**Q: 智能体不响应或响应错误**
+```bash
+# 排查步骤
+# 1. 确认智能体名称正确
+npm run list:agents
+
+# 2. 检查上下文是否提供充分
+# - Web UI: 确保粘贴了所有依赖文档
+# - IDE: 确保文件在项目目录中
+
+# 3. 重新开始对话
+# Web UI: 刷新页面
+# IDE: 重启 AI 对话
+```
+
+**Q: 文档生成不完整**
+```bash
+# 解决方法
+# 1. 分步骤要求生成
+# 2. 提供更具体的指令
+# 3. 检查模板是否正确加载
+
+# 示例：
+@pm
+请使用 prd-tmpl 模板，为以下项目概要创建完整的 PRD：
+[提供项目概要内容]
+请确保包含：用户故事、验收标准、优先级
+```
+
+### 工作流程问题
+
+**Q: 文档分片失败**
+```bash
+# 解决方案
+# 1. 检查源文档格式
+head -50 docs/prd.md
+
+# 2. 手动创建目录结构
+mkdir -p docs/prd/epics docs/architecture/components
+
+# 3. 逐个Epic手动分片
+@po
+请将以下 Epic 保存为独立文件：
+[粘贴单个 Epic 内容]
+```
+
+**Q: 故事创建没有遵循模板**
+```bash
+# 解决方法
+# 提供明确的模板格式
+@sm
+请按以下模板创建故事：
+
+# Story-XXX: [标题]
+## 状态
+- [x] Draft / [ ] Approved / [ ] In Progress / [ ] Review / [ ] Done
+
+## 故事描述
+As a [角色]
+I want [功能]
+So that [价值]
+
+## 验收标准
+- [ ] AC1: 具体的可测试标准
+- [ ] AC2: 具体的可测试标准
+
+## 技术任务
+- [ ] Task 1: 具体实现任务
+- [ ] Task 2: 具体实现任务
+```
+
+**Q: 代码质量检查失败**
+```bash
+# 常见问题及解决方案
+
+# Lint 错误
+npm run lint -- --fix
+
+# 类型错误
+npm run typecheck
+# 根据错误提示修复类型问题
+
+# 测试失败
+npm test -- --verbose
+# 检查失败的测试用例
+
+# 构建失败
+npm run build 2>&1 | tee build.log
+# 查看详细错误日志
+```
+
+### 性能优化
+
+**Q: 智能体响应慢**
+- 减少上下文长度
+- 分步骤执行复杂任务
+- 使用更具体的指令
+- 避免同时处理多个大文档
+
+**Q: 文档过多导致混乱**
+```bash
+# 组织建议
+# 1. 使用清晰的目录结构
+tree docs
+
+# 2. 创建索引文件
+echo "# 文档索引" > docs/README.md
+echo "## 规划文档" >> docs/README.md
+ls docs/*.md >> docs/README.md
+
+# 3. 定期清理过时文档
+find docs -name "*.md" -mtime +30
+```
+
+## 📊 流程决策指导
+
+### 何时使用完整流程
+- ✅ **生产就绪应用**：需要部署到生产环境
+- ✅ **多人协作**：团队成员 > 1
+- ✅ **复杂需求**：功能模块 > 5
+- ✅ **长期维护**：预期使用 > 1年
+- ✅ **企业级应用**：面向客户或内部重要系统
+
+### 简化流程选项
+- 🔹 **快速原型**：跳过 UX Expert，直接 PM → Architect
+- 🔹 **个人项目**：跳过 QA，Dev 自测
+- 🔹 **简单功能**：合并故事，减少分片
+
+### 文档传递最佳实践
+- 📋 每个阶段完成后，立即保存到 `docs/` 目录
+- 🔄 确保后续智能体可访问前置文档
+- 📱 Web UI ↔ IDE 环境切换时验证文档完整性
+- 📝 使用版本控制跟踪文档变更
+
+## 🔗 相关资源
+
+### 框架文件结构
+- **项目配置**：`xiaoma-core/core-config.yaml`
+- **工作流定义**：`xiaoma-core/workflows/greenfield-fullstack.yaml`
+- **智能体定义**：`xiaoma-core/agents/`
+- **模板库**：`xiaoma-core/templates/`
+- **任务库**：`xiaoma-core/tasks/`
+- **检查清单**：`xiaoma-core/checklists/`
+
+### 有用的命令
+```bash
+# 查看框架版本
+npm run version
+
+# 验证所有配置
+npm run validate
+
+# 平铺代码库（AI 分析用）
+npm run flatten
+
+# 升级框架版本
+npx xiaoma-web upgrade
+```
+
+### 进阶使用
+- 📚 **扩展包**：`expansion-packs/` - 领域特定扩展
+- 🎯 **自定义智能体**：修改 `agents/` 目录下的配置
+- 🔧 **自定义模板**：在 `templates/` 目录添加模板
+- 📋 **自定义任务**：在 `tasks/` 目录添加任务
+
+---
+
+## 📝 总结
+
+这套 **XiaoMa-Web 多智能体 0-1 项目开发完整指南** 提供了从零开始创建项目到完整交付的每一步详细操作指南。
+
+**核心特点**：
+- 🎯 **明确的角色分工**：每个智能体都有专门职责
+- 📋 **结构化流程**：每个步骤都有具体的命令和验证标准  
+- 🔄 **双阶段开发**：Web UI 规划 + IDE 开发
+- ✅ **质量保证**：内置代码审查和测试流程
+- 📊 **进度跟踪**：文档化的故事状态管理
+
+**适用场景**：
+- 新项目从 0 到 1 的完整开发
+- 需要规范化流程的团队协作
+- 复杂应用的结构化开发
+- 长期维护项目的质量保证
+
+通过遵循这个指南，你可以确保项目从需求分析到最终交付的每个环节都有专门的智能体负责，实现高效、高质量的项目开发。
+
+**下一步**：
+1. 根据你的项目需求选择合适的流程
+2. 准备必要的开发环境
+3. 开始执行 **步骤 0：前置准备** 
+4. 遇到问题时参考 **常见问题和故障排除** 部分
+
+祝你项目开发顺利！🚀