mirror of
https://github.com/GuDaStudio/commands.git
synced 2026-03-22 19:18:52 +08:00
26 KiB
26 KiB
name: GudaSpec: Deep Research Review
description: Interactive review of external research - guided technology decisions and synthesis.
category: GudaSpec
tags: [gudaspec, research, review, external, synthesis, interactive]
argument-hint: [requirement-id]
Purpose
以用户友好的方式审查外部研究发现，引导技术决策，综合内外部约束生成最终需求文档。
Core Principles
- 决策导向：聚焦于帮助用户做决定，而非展示信息
- 对比清晰：用表格和可视化展示选项差异
- 风险透明：明确说明每个选择的潜在风险
- 关联内部：始终与内部约束对照验证
- 渐进收敛：从大方向到具体细节
Guardrails
- MUST use
AskUserQuestionsfor all decisions - MUST relate external findings to internal constraints
- MUST explain trade-offs in business terms
- NEVER make technology decisions without user confirmation
- NEVER present options without recommendation and rationale
Steps
Step 0: Load Both Documents
cat gudaspec/research/<requirement-id>/internal.md
cat gudaspec/research/<requirement-id>/external.md
Prepare synthesis by:
- Mapping external options to internal constraints
- Identifying potential conflicts
- Preparing comparison matrices
Step 1: Welcome and Context Recap
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 外部调研审查: <Requirement Description>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需求ID: <requirement-id>
【回顾：您之前的关键决策】
• 登录安全: 复用现有机制
• 同步频率: 每5分钟
• 实施边界: <范围描述>
【本次调研解答了】
• Microsoft Graph API vs EWS 选型
• OAuth 2.0 集成方案
• 邮件数据存储策略
接下来我会引导您完成技术选型决策。
📊 决策概览:
┌─────────────────────────────────────┐
│ 核心技术选型 ████████░░ 2 个 │
│ 实施策略确认 ██████░░░░ 2 个 │
│ 风险确认 ████░░░░░░ 1 个 │
└─────────────────────────────────────┘
预计用时: 5-10 分钟
Step 2: Core Technology Decision (核心技术决策)
Strategy: Present as a product comparison, highlight what matters most for this specific use case.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 技术选型 1/2: 邮件API选择
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
经过调研，有两个主要方案可以实现 Outlook 邮件集成：
┌─────────────────────────────────────────────────────────────┐
│ Microsoft Graph API │
├─────────────────────────────────────────────────────────────┤
│ 🌟 推荐理由: 微软官方推荐的现代API │
│ │
│ ✅ 优势 │ ⚠️ 注意事项 │
│ • 统一的API，可扩展到日历等 │ • 需要Azure AD应用注册 │
│ • 活跃维护，文档完善 │ • 学习曲线略高 │
│ • 支持增量同步（省流量） │ • 某些高级功能需付费许可 │
│ • 与现代OAuth 2.0完全兼容 │ │
│ │ │
│ 📊 与您项目的兼容性: 95% │ │
│ • ✅ 可复用现有OAuth基础设施 │ │
│ • ✅ 符合项目REST风格 │ │
│ • ⚠️ 需要新增 msgraph-sdk │ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Exchange Web Services (EWS) │
├─────────────────────────────────────────────────────────────┤
│ ℹ️ 备选方案: 传统但稳定 │
│ │
│ ✅ 优势 │ ⚠️ 注意事项 │
│ • 成熟稳定，案例多 │ • 微软已停止新功能开发 │
│ • 本地Exchange服务器支持好 │ • 未来可能被废弃 │
│ │ • 文档逐渐过时 │
│ │ • 某些新邮箱功能不支持 │
│ │ │
│ 📊 与您项目的兼容性: 70% │ │
│ • ⚠️ 认证方式与现有不兼容 │ │
│ • ⚠️ XML格式与项目JSON风格冲突│ │
└─────────────────────────────────────────────────────────────┘
【我的建议】
选择 **Microsoft Graph API**
原因：与您项目的现有技术栈（OAuth、REST、JSON）高度兼容，
且是微软未来重点发展方向，长期维护成本更低。
Use AskUserQuestions:
question: "邮件API您选择哪个方案？"
options: [
"Microsoft Graph API（推荐）",
"Exchange Web Services",
"需要更多对比信息",
"我有其他考虑，想讨论一下"
]
If user wants more info or discussion, provide:
我来补充一些细节：
【成本对比】
• Graph API: 免费额度较大，超出后按调用计费
• EWS: 通常包含在Microsoft 365订阅中
【开发时间对比】
• Graph API: 预计 3-4 天（有官方SDK）
• EWS: 预计 5-7 天（需要更多手动处理）
【您的顾虑是什么？】
Step 3: Implementation Strategy Decision (实施策略决策)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 技术选型 2/2: OAuth认证流程
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
基于您选择的 Graph API，需要确定 OAuth 认证流程：
【您的场景】
用户在您的应用中点击"连接Outlook" → 跳转微软登录 →
授权后返回您的应用 → 开始同步邮件
【推荐方案: Authorization Code Flow】
用户 您的应用 微软 │ │ │ │──点击连接────▶│ │ │ │──重定向──────▶│ │ │ │ │◀──────────────────登录页面────│ │ │ │ │───────────输入账号密码───────▶│ │ │ │ │ │◀──授权码──────│ │ │ │ │ │──换取Token───▶│ │ │ │ │ │◀──Access Token│ │◀──连接成功───│ │
【此方案的优点】
• 最安全的OAuth流程（PKCE增强）
• 与您现有的Google OAuth流程一致
• 可复用现有的Token刷新机制
【需要您确认】
Token存储位置：
┌────────────────────────────────────────────┐
│ A. 数据库存储（推荐） │
│ • 服务器可定时刷新 │
│ • 用户关闭浏览器后仍可后台同步 │
│ • 需要加密存储 │
├────────────────────────────────────────────┤
│ B. 仅Session存储 │
│ • 更简单，无需额外存储 │
│ • 用户关闭浏览器后需重新授权 │
│ • 不支持后台同步 │
└────────────────────────────────────────────┘
Use AskUserQuestions:
question: "Token存储方案选择？"
options: [
"A. 数据库存储（推荐：支持后台同步）",
"B. Session存储（简单但功能受限）",
"这个决定需要更多技术背景，请解释"
]
Step 4: Best Practices Adoption (最佳实践采纳)
Strategy: Present best practices as "lessons learned from others", let user decide what to adopt.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 最佳实践: 他人踩过的坑
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
调研中发现了一些值得借鉴的经验：
【实践1: 增量同步】
┌────────────────────────────────────────────┐
│ 💡 经验: 不要每次全量拉取邮件 │
│ │
│ 问题: 全量拉取会很慢且浪费API配额 │
│ 解决: 使用 deltaLink 只获取变化的邮件 │
│ 效果: API调用减少 80%，同步速度提升 5x │
│ │
│ 采纳成本: 低（Graph API原生支持） │
└────────────────────────────────────────────┘
建议: ✅ 强烈推荐采纳
【实践2: 错误重试策略】
┌────────────────────────────────────────────┐
│ 💡 经验: API调用失败时要智能重试 │
│ │
│ 问题: 网络波动导致同步中断 │
│ 解决: 指数退避重试 (1s, 2s, 4s, 8s...) │
│ 效果: 同步成功率从 95% 提升到 99.9% │
│ │
│ 采纳成本: 低（约2小时开发） │
└────────────────────────────────────────────┘
建议: ✅ 推荐采纳
【实践3: 邮件内容缓存】
┌────────────────────────────────────────────┐
│ 💡 经验: 缓存邮件正文减少重复请求 │
│ │
│ 问题: 用户反复查看同一邮件消耗API │
│ 解决: 本地缓存已读邮件内容 │
│ 效果: 响应速度提升，API成本降低 │
│ │
│ 采纳成本: 中（需要设计缓存策略） │
└────────────────────────────────────────────┘
建议: ⚠️ 可选（根据使用频率决定）
Use AskUserQuestions:
question: "以上最佳实践，您希望采纳哪些？"
options: [
"全部采纳（推荐）",
"仅采纳强烈推荐的（实践1和2）",
"最小实现，后续再优化",
"我想逐个讨论"
]
Step 5: Risk Acknowledgment (风险确认)
Strategy: Be transparent about potential issues, get user's acknowledgment.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ 风险提示: 实施前须知
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
基于调研，以下风险需要您了解：
【风险1: API速率限制】
┌────────────────────────────────────────────┐
│ 🚨 严重程度: 中 │
│ │
│ 情况: Graph API 有调用频率限制 │
│ • 每应用: 2000次/秒 │
│ • 每用户: 10000次/10分钟 │
│ │
│ 触发场景: 大量用户同时首次同步 │
│ │
│ 缓解措施: │
│ ✅ 已计划: 增量同步减少调用 │
│ ✅ 已计划: 错误重试策略 │
│ 📋 建议: 首次同步限制为最近30天邮件 │
└────────────────────────────────────────────┘
【风险2: Token过期处理】
┌────────────────────────────────────────────┐
│ 🚨 严重程度: 低 │
│ │
│ 情况: Access Token 1小时过期 │
│ Refresh Token 90天过期 │
│ │
│ 触发场景: 用户90天未使用需重新授权 │
│ │
│ 缓解措施: │
│ ✅ 已计划: 自动刷新机制 │
│ 📋 建议: 过期前邮件提醒用户重新授权 │
└────────────────────────────────────────────┘
【总体风险评估】
以上风险在正确实施后均可控。
无阻塞性风险，可以继续推进。
Use AskUserQuestions:
question: "您是否了解并接受以上风险？"
options: [
"了解，可以接受",
"风险1我有顾虑，想讨论一下",
"风险2我有顾虑，想讨论一下",
"需要更详细的风险分析"
]
Step 6: Constraint Conflict Resolution (约束冲突解决)
Strategy: If there are conflicts between internal and external constraints, present clearly and get resolution.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚡ 约束冲突: 需要您做决定
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
在综合内外部研究时，发现一个需要协调的点：
【冲突描述】
┌────────────────────────────────────────────┐
│ 内部约束: │
│ 现有认证模块使用 HS256 算法签名 JWT │
│ │
│ 外部推荐: │
│ Microsoft 最佳实践建议使用 RS256 算法 │
│ │
│ 冲突点: │
│ 算法不同，无法直接复用现有 Token 验证逻辑 │
└────────────────────────────────────────────┘
【解决方案】
方案A: 统一升级到 RS256
┌────────────────────────────────────────────┐
│ 做法: 整体迁移现有认证到 RS256 │
│ 优点: 安全性更高，架构统一 │
│ 代价: 需要修改现有代码，所有用户重新登录 │
│ 工作量: +2天 │
└────────────────────────────────────────────┘
方案B: 双算法共存
┌────────────────────────────────────────────┐
│ 做法: 现有保持 HS256，Outlook 用 RS256 │
│ 优点: 不影响现有功能 │
│ 代价: 代码复杂度增加，维护两套逻辑 │
│ 工作量: +0.5天 │
└────────────────────────────────────────────┘
方案C: Outlook也用 HS256
┌────────────────────────────────────────────┐
│ 做法: 忽略微软建议，统一用 HS256 │
│ 优点: 最简单，完全复用现有逻辑 │
│ 代价: 安全性略低于推荐标准 │
│ 工作量: +0天 │
└────────────────────────────────────────────┘
【我的建议】
选择 **方案B: 双算法共存**
原因：平衡了安全性和改动范围，Outlook模块使用推荐算法，
不影响现有用户，未来可渐进式迁移。
Use AskUserQuestions:
question: "对于JWT算法冲突，您选择哪个方案？"
options: [
"方案A: 统一升级（更安全，改动大）",
"方案B: 双算法共存（推荐：平衡）",
"方案C: 统一HS256（最简单）",
"需要更多信息来决定"
]
Step 7: Final Decision Summary (最终决策总结)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 决策总结
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
经过完整的研究和审查，以下是您的所有决策：
┌─────────────────────────────────────────────────────────────┐
│ 📋 需求: <Requirement Description> │
│ 🆔 ID: <requirement-id> │
├─────────────────────────────────────────────────────────────┤
│ │
│ 【内部研究决策】 │
│ ├─ 登录安全: 复用现有机制 │
│ ├─ 项目规范: 完全遵循 │
│ ├─ 集成方案: 3个对接点 │
│ └─ 同步频率: 每5分钟 │
│ │
│ 【外部研究决策】 │
│ ├─ 邮件API: Microsoft Graph API │
│ ├─ 认证流程: Authorization Code Flow + PKCE │
│ ├─ Token存储: 数据库加密存储 │
│ ├─ 最佳实践: 采纳增量同步 + 错误重试 │
│ └─ JWT算法: 双算法共存 │
│ │
│ 【风险确认】 │
│ ├─ API限速: 已了解，通过增量同步缓解 │
│ └─ Token过期: 已了解，通过自动刷新处理 │
│ │
├─────────────────────────────────────────────────────────────┤
│ 📊 实施预估 │
│ ├─ 涉及文件: 12-15 个 │
│ ├─ 新增依赖: msgraph-sdk, msal │
│ ├─ 预计工时: 5-7 天 │
│ └─ 风险等级: 中低 │
└─────────────────────────────────────────────────────────────┘
Use AskUserQuestions:
question: "以上决策总结是否准确完整？"
options: [
"准确，生成最终需求文档",
"基本准确，有小的补充",
"需要修改某项决策"
]
Step 8: Generate Final Requirement Document
Create comprehensive requirement.md incorporating all confirmed decisions.
Key sections to include:
- 所有内部约束（已确认）
- 所有外部约束（已确认）
- 技术决策及理由
- 采纳的最佳实践
- 风险及缓解措施
- 用户所有决策的完整记录
Step 9: Completion Output
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Research 全部完成！
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需求ID: <requirement-id>
📁 生成的文档:
├─ gudaspec/research/<requirement-id>/
│ ├─ internal.md (内部研究 - 已确认)
│ ├─ external.md (外部研究 - 已确认)
│ └─ requirement.md (最终需求文档) ⭐
📊 研究摘要:
┌─────────────────────────────────────────┐
│ 您做出了 8 项关键决策 │
│ 确认了 12 条约束 │
│ 采纳了 2 项最佳实践 │
│ 了解并接受了 2 项风险 │
└─────────────────────────────────────────┘
📋 下一步操作:
1. 输入 /clear 清空当前上下文
(释放空间，为规划阶段准备)
2. 输入以下命令开始规划:
/gudaspec:plan gudaspec/research/<requirement-id>/requirement.md
规划阶段将基于您确认的约束，生成详细的实施计划。
Question Design Patterns for External Review
Pattern 1: Product Comparison (产品对比)
【方案A】 vs 【方案B】
┌──────────────┐ ┌──────────────┐
│ 特点 │ │ 特点 │
│ 优势 │ │ 优势 │
│ 劣势 │ │ 劣势 │
│ 适用场景 │ │ 适用场景 │
└──────────────┘ └──────────────┘
我的建议: [方案X]，因为 [与您需求的匹配点]
Pattern 2: Trade-off Matrix (权衡矩阵)
┌─────────┬──────┬──────┬──────┐
│ 维度 │ A │ B │ C │
├─────────┼──────┼──────┼──────┤
│ 成本 │ ⭐⭐⭐ │ ⭐⭐ │ ⭐ │
│ 复杂度 │ ⭐ │ ⭐⭐ │ ⭐⭐⭐ │
│ 安全性 │ ⭐⭐⭐ │ ⭐⭐ │ ⭐ │
└─────────┴──────┴──────┴──────┘
您更看重哪个维度？
Pattern 3: Impact Visualization (影响可视化)
如果选择 [方案X]:
现在 3个月后
──── ────────
[现状] ──────────────▶ [预期结果]
收益: [具体数字/效果]
代价: [具体工作量/风险]
Pattern 4: Lesson Learned (经验借鉴)
【他人经验】
问题: 遇到了什么问题
原因: 为什么会这样
解决: 怎么解决的
效果: 解决后怎样
【对您的启示】
建议: 您应该/不应该...
Exit Criteria
- All technology decisions confirmed with user rationale
- All best practices reviewed (adopted/skipped with reason)
- All risks acknowledged by user
- All constraint conflicts resolved
- Final decision summary confirmed by user
- requirement.md generated with complete documentation
- User directed to /gudaspec:plan