- name
- devdocs-insights
- description
- DevDocs 洞察收集专家。收集来自 UI/UX 审查、文档调研、外部参考等的改进建议，经用户确认后转化为开发需求。支持外部资源获取和优化建议整理。
- allowed-tools
- Read, Write, Glob, Grep, AskUserQuestion, WebFetch
洞察收集
收集来自 UI/UX 审查、文档调研、外部参考等来源的改进建议，经用户确认后转化为开发需求。
语言规则
- 支持中英文提问
- 统一中文回复
- 使用中文生成文档
触发条件
- 用户完成 UI/UX 审查，有优化建议
- 用户调研了文档/方案，发现可借鉴点
- 用户发现外部参考（竞品、最佳实践）可借鉴
- 用户有改进想法需要转化为需求
核心理念
洞察来源
┌─────────────────────────────────────────────────────────────┐
│ 洞察来源 │
├─────────────────────────────────────────────────────────────┤
│ 🎨 UI/UX 审查 │ 界面问题、交互优化、视觉改进 │
├─────────────────────────────────────────────────────────────┤
│ 📄 文档调研 │ 技术方案、设计模式、架构参考 │
├─────────────────────────────────────────────────────────────┤
│ 🔍 外部参考 │ 竞品分析、行业最佳实践、开源项目 │
├─────────────────────────────────────────────────────────────┤
│ 💡 内部反馈 │ 用户反馈、团队建议、性能监控 │
└─────────────────────────────────────────────────────────────┘转化流程
洞察来源 确认阶段 输出阶段
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────────┐
│ 收集 │ → │ 用户 │ → │ 追加到 │
│ 建议 │ │ 确认 │ │ 需求文档 │
└─────────┘ └─────────┘ └─────────────┘
│
▼
部分确认 / 全部确认 / 拒绝核心原则：
- 建议必须经过用户确认才能转化为需求
- 保留建议来源的追溯性
- 区分优先级，避免需求膨胀
工作流程
1. 识别洞察来源
│
▼
2. 收集/整理建议
├── UI/UX 审查结果
├── 文档调研发现
├── 外部参考借鉴
└── 内部反馈汇总
│
▼
3. 结构化建议列表
├── 分类整理
├── 评估影响范围
└── 建议优先级
│
▼
4. 用户确认（AskUserQuestion）
├── 逐条确认
├── 批量确认
└── 调整优先级
│
▼
5. 转化为需求
├── 生成功能点 (F-XXX)
├── 生成验收标准 (AC-XXX)
└── 追加到 01-requirements.md
│
▼
6. 建议后续流程
└── 运行 /devdocs-system-design 或 /devdocs-dev-tasks输出文件
洞察记录（可选）
文件：docs/devdocs/05-insights.md
用于记录洞察来源和转化历史，便于追溯。
需求追加
确认的建议将追加到：docs/devdocs/01-requirements.md
建议结构
单条建议格式
### INS-001: <建议标题>
| 属性 | 内容 |
|------|------|
| **来源** | 🎨 UI/UX 审查 / 📄 文档调研 / 🔍 外部参考 / 💡 内部反馈 |
| **参考** | <来源链接或描述> |
| **现状** | <当前问题或不足> |
| **建议** | <改进建议> |
| **影响范围** | <涉及模块/功能> |
| **优先级** | P0 / P1 / P2 |
| **状态** | ⏳ 待确认 / ✅ 已确认 / ❌ 已拒绝 / 🔄 已转化 |
**预期收益**：
- <收益1>
- <收益2>建议列表格式
# 洞察收集：<主题>
**收集时间**：YYYY-MM-DD
**来源类型**：UI/UX 审查 / 文档调研 / 外部参考
## 建议汇总
| 编号 | 标题 | 来源 | 优先级 | 状态 |
|------|------|------|--------|------|
| INS-001 | <标题> | 🎨 | P1 | ⏳ |
| INS-002 | <标题> | 📄 | P0 | ⏳ |
## 详细建议
### INS-001: <标题>
...
---
## 确认结果
- [x] INS-001: 已确认 → F-XXX
- [ ] INS-002: 待确认
- [x] INS-003: 已拒绝（原因：...）来源类型处理
🎨 UI/UX 审查
**输入**：
- 用户提供截图/原型
- 用户描述交互问题
- 运行 /ui-skills 审查结果
**关注点**：
- 可用性问题
- 视觉一致性
- 无障碍性
- 响应式适配
- 交互流畅度
**示例建议**：
- INS-001: 按钮对比度不足，影响可读性
- INS-002: 表单缺少加载状态反馈
- INS-003: 移动端导航菜单难以点击📄 文档调研
**输入**：
- 技术文档链接
- 设计方案文档
- 最佳实践指南
**关注点**：
- 可借鉴的架构模式
- 更优的实现方案
- 性能优化技术
- 安全加固措施
**示例建议**：
- INS-004: 采用 React Query 替代手动状态管理
- INS-005: 引入乐观更新提升用户体验
- INS-006: 使用 Zod 进行运行时类型校验🔍 外部参考
**输入**：
- 竞品链接/截图
- 开源项目参考
- 行业报告
**关注点**：
- 竞品优势功能
- 行业通用模式
- 用户期望对齐
**示例建议**：
- INS-007: 参考 Notion 的拖拽排序交互
- INS-008: 借鉴 Linear 的快捷键系统
- INS-009: 采用类似 Figma 的实时协作模式💡 内部反馈
**输入**：
- 用户反馈记录
- 团队讨论结果
- 性能监控数据
**关注点**：
- 高频用户痛点
- 团队共识问题
- 性能瓶颈
**示例建议**：
- INS-010: 列表加载慢，需要分页或虚拟滚动
- INS-011: 搜索功能缺少高级筛选
- INS-012: 导出功能需要支持更多格式用户确认流程
使用 AskUserQuestion 进行交互式确认：
单条确认
建议 INS-001: 按钮对比度不足，影响可读性
来源：🎨 UI/UX 审查
优先级：P1
影响范围：全局按钮组件
是否确认转化为需求？
- 确认（转化为 F-XXX）
- 调整优先级后确认
- 拒绝（请说明原因）
- 稍后决定批量确认
以下建议待确认：
| 编号 | 标题 | 优先级 |
|------|------|--------|
| INS-001 | 按钮对比度不足 | P1 |
| INS-002 | 缺少加载状态 | P1 |
| INS-003 | 移动端导航问题 | P2 |
请选择：
- 全部确认
- 选择性确认（输入编号，如：1,2）
- 全部拒绝
- 逐条审查需求转化规则
转化映射
| 建议类型 | 转化为 | 说明 |
|---|---|---|
| 新功能建议 | F-XXX (新功能点) | 创建新的功能点 |
| 优化建议 | F-XXX (优化标记) | 标记为优化类型 |
| Bug 修复 | 直接触发 /devdocs-bugfix | 走 Bug 修复流程 |
| 技术改进 | F-XXX (技术债务) | 标记为技术改进 |
功能点格式
### F-XXX: <功能名称> [优化]
**来源**：INS-XXX (<来源类型>)
**优先级**：P0 / P1 / P2
**描述**：
<从建议转化的功能描述>
**验收标准**：
- AC-XXX: <可验证的标准1>
- AC-XXX: <可验证的标准2>编号规则
- 功能点编号：延续
01-requirements.md中的编号 - 验收标准编号：延续现有 AC 编号
- 建议编号：INS-XXX（仅在洞察文档中使用）
约束
收集约束
- [ ] 必须标明建议来源
- [ ] 必须评估影响范围
- [ ] 每条建议必须有明确的现状和改进点
- [ ] 外部参考必须提供来源链接
确认约束
- [ ] 所有建议必须经过用户确认才能转化
- [ ] 拒绝的建议必须记录原因
- [ ] 批量确认前必须展示完整列表
- [ ] 用户可以调整建议优先级
转化约束
- [ ] 转化后的需求必须可追溯到原始建议
- [ ] 必须生成可验证的验收标准
- [ ] 优化类需求必须标记 [优化] 标签
- [ ] 转化后更新建议状态为 🔄 已转化
避免需求膨胀
- [ ] 单次收集建议不超过 10 条
- [ ] 低优先级建议可标记为"待定"
- [ ] 鼓励用户聚焦核心改进
- [ ] 定期清理过期的待确认建议
Skill 协作
| 场景 | 协作 Skill | 说明 |
|---|---|---|
| UI/UX 审查来源 | /ui-skills | 审查结果可作为洞察来源 |
| 确认后设计 | /devdocs-system-design | 需要系统设计时触发 |
| 确认后开发 | /devdocs-dev-tasks | 直接进入开发任务 |
| Bug 类建议 | /devdocs-bugfix | 走 Bug 修复流程 |
| 需求更新 | /devdocs-sync | 同步文档状态 |
使用示例
示例一：UI/UX 审查后
用户: 我刚审查了登录页面，发现几个问题想优化
Agent: 好的，让我帮你收集这些优化建议。请描述发现的问题：
用户:
1. 密码输入框没有显示/隐藏切换
2. 忘记密码链接不够明显
3. 第三方登录按钮风格不统一
Agent: 已整理以下建议：
| 编号 | 标题 | 优先级 | 状态 |
|------|------|--------|------|
| INS-001 | 添加密码可见性切换 | P1 | ⏳ |
| INS-002 | 突出忘记密码链接 | P2 | ⏳ |
| INS-003 | 统一第三方登录按钮风格 | P2 | ⏳ |
请确认要转化为需求的建议（输入编号，如 1,2,3 或 "全部"）：
用户: 1,3
Agent:
✅ 已确认 INS-001, INS-003
已追加到 01-requirements.md：
- F-015: 密码可见性切换 [优化] (来源: INS-001)
- F-016: 统一第三方登录按钮 [优化] (来源: INS-003)
是否继续运行 /devdocs-dev-tasks 拆分开发任务？示例二：文档调研后
用户: 我看了这篇文章 https://example.com/react-patterns，想借鉴一些模式
Agent: 让我分析这篇文章并提取可借鉴的点...
[WebFetch 获取内容]
基于文章内容，整理以下借鉴建议：
| 编号 | 标题 | 参考章节 | 优先级 |
|------|------|----------|--------|
| INS-001 | 采用 Compound Components 模式 | 第3节 | P1 |
| INS-002 | 使用 Render Props 替代 HOC | 第5节 | P2 |
| INS-003 | 引入 Custom Hooks 复用逻辑 | 第7节 | P1 |
请确认要采纳的建议：命令选项
# 标准模式：交互式收集和确认
/devdocs-insights
# 从 URL 提取建议
/devdocs-insights --url <url>
# 从文件提取（如审查报告）
/devdocs-insights --file <path>
# 快速模式：直接输入建议列表
/devdocs-insights --quick下一步
确认建议并转化为需求后：
- 如需系统设计更新，运行
/devdocs-system-design - 如可直接开发，运行
/devdocs-dev-tasks - 运行
/devdocs-sync同步文档状态