| name | devdocs-insights |
| description | Collect improvement insights from UI/UX reviews, document research, or external references, convert confirmed items into development requirements. Use when users have optimization suggestions, research findings, or want to improve based on external references. Triggers on keywords like "insights", "improvements", "optimize", "review findings", "research", "借鉴", "优化建议", "审查结果", "调研". |
| 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（仅在洞察文档中使用）
约束
收集约束
确认约束
转化约束
避免需求膨胀
Skill 协作
| 场景 | 协作 Skill | 说明 |
|---|
| UI/UX 审查来源 | /ui-skills | 审查结果可作为洞察来源 |
| 需求转化 | /devdocs-requirements | 被调用：洞察转化为需求 |
| 设计变更 | /devdocs-system-design | 触发：复杂改进需要设计调整 |
| 测试补充 | /devdocs-test-cases | 触发：改进建议需要测试覆盖 |
| 简单改进 | /devdocs-dev-tasks | 无架构变更，直接拆分任务 |
| 复杂改进 | /devdocs-feature | 有架构变更，走完整流程 |
| 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
/devdocs-insights --url <url>
/devdocs-insights --file <path>
/devdocs-insights --quick
下一步
确认建议并转化为需求后，根据改进复杂度选择路径：
路径选择
确认的改进建议
│
▼
评估是否涉及架构变更
│
├── 无架构变更（简单改进）
│ ├── UI 微调、配置修改、小功能
│ └── → /devdocs-dev-tasks 直接拆分任务
│
└── 有架构变更（复杂改进）
├── 新接口、数据模型变更、新模块
└── → /devdocs-feature 完整流程
└── system-design → test-cases → dev-tasks
架构变更判断
| 条件 | 是否架构变更 | 推荐路径 |
|---|
| 仅 UI/样式调整 | 否 | /devdocs-dev-tasks |
| 仅配置项修改 | 否 | /devdocs-dev-tasks |
| 新增 API 接口 | 是 | /devdocs-feature |
| 数据模型变更 | 是 | /devdocs-feature |
| 新增独立模块 | 是 | /devdocs-feature |
| 第三方服务集成 | 是 | /devdocs-feature |
使用 AskUserQuestion 确认
已确认 X 条改进建议，转化为需求。
检测到以下情况：
- INS-001: UI 按钮样式调整 → 无架构变更
- INS-003: 新增导出 API → 涉及架构变更
建议路径：
- INS-001 → /devdocs-dev-tasks（直接拆分任务）
- INS-003 → /devdocs-feature（完整流程）
是否按建议执行？[是/调整]
