feature-design-recorder

name	feature-design-recorder
description	在 docs/designs/ 目录下用 markdown 文件记录计划开发的功能。当用户要求开发新功能、添加特性或修改现有功能时（如'为 xx 添加功能'、'开发 xx'、'实现 xx'）时调用。通过问答澄清需求并生成设计文档。全程中文，仅生成文档，不修改代码。

功能设计记录器

本 skill 帮助您在 docs/designs/ 目录下记录计划开发的功能，并通过「问答 → 方案对比 → 设计文档」的方式，把想法整理成可实施的设计。

项目背景

oss-browser 是一个阿里云 OSS 浏览器应用，采用 Electron + Vue 3 + TypeScript 构建：

• 主进程模块：src/main/modules/ — 核心业务逻辑、OSS 适配器、IPC 处理器
• 渲染进程钩子：src/renderer/hooks/ — Vue 组合式函数，封装 UI 逻辑
• IPC 通信：主进程与渲染进程通过 ipcRenderer.invoke / ipcMain.handle 通信

使用场景

当用户要求开发新功能、新增特性或修改现有功能时（例如："为上传添加 xxx"、"实现目录下载"、"优化文件列表性能"）：

1. 识别是「新增功能」还是「修改现有功能」
2. 通过多轮问答澄清需求与使用场景
3. 基于需求生成一个或多个可选实现方案
4. 列出每个方案涉及的主要代码位置（只记录，不修改）
5. 在用户选择最终方案后，根据复杂度和用户意愿决定是否生成设计文档

对话流程

1. 触发与意图识别

从用户输入中识别：

• 是新功能还是对现有功能的增强
• 涉及哪个模块（oss、upload、download、preview 等）
• 功能的目标用户和典型使用场景

2. 需求澄清的多轮问答

在生成任何设计文档之前，必须先通过多轮问答把需求问清楚：

• 目标与场景：
  • 这个功能主要解决什么问题？
  • 典型使用场景是什么？
• 调用方式：
  • 用户如何触发这个功能（按钮、菜单、右键、快捷键）？
  • 有哪些输入参数和可选配置？
• 输入与输出：
  • 数据来源是什么（用户选择、API 返回、本地文件）？
  • 期望的反馈形式是什么（进度条、Toast、文件下载）？
• 约束与边界：
  • 有无性能或并发方面的要求？
  • 是否需要兼容现有行为？
  • 错误情况希望如何处理？

收集完信息后，用中文对需求做一次总结，向用户回读确认，确认后才进入方案生成阶段。

3. 生成可选实现方案

每个方案需要包含：

• 接口设计
  • IPC 通道名称和参数结构
  • 前端调用方式（哪个 hook 或组件）
  • 后端处理函数签名
• 行为说明
  • 成功时的行为和 UI 反馈
  • 错误和异常情况下的处理
• 影响范围（设计层面）
  • 仅列出可能需要修改或新增的模块/文件，不做任何修改
  • 主进程模块位置：src/main/modules/<模块名>/
  • 渲染进程钩子位置：src/renderer/hooks/<类型>/
  • 组件位置：src/renderer/components/ 或 src/renderer/views/
• 优缺点
  • 可维护性
  • 对现有用户的影响
  • 实现复杂度

4. 用户选择方案并最终确认

• 引导用户从上述方案中选择一个，或提出调整意见
• 根据用户的选择和调整，整理出「最终实现方案」的描述
• 用户确认后，进入是否生成设计文档的判断

5. 是否生成设计文档

适合生成设计文档的场景（默认建议生成）：

• 新功能开发，涉及多个模块联动
• 涉及 IPC 通信协议变更
• 需要新增或修改核心业务逻辑

可以不生成设计文档的场景：

• 只在现有功能上增加一个简单参数或选项
• 只是改动 UI 文案或样式等简单修改

交互规则：

• 明确询问用户："本次功能是否需要生成设计文档？简单改动可以只在对话中约定，不创建文件。"
• 如果用户选择生成设计文档：按「文件内容结构」章节的模板生成文档
• 如果用户选择不生成设计文档：仅在当前对话中给出最终方案的清晰中文总结

无论是否生成设计文档，本 skill 都不会修改任何代码文件。

6. 开发确认

在设计文档生成完成（或最终方案确认）后，必须明确询问：

"是否需要立即按照此设计文档进行代码开发？"

• 如果用户同意：才可以进入开发阶段，开始修改代码。
• 如果用户不同意或未明确指令：任务结束，不进行任何代码修改。

注意：严禁在生成文档后不经询问直接开始写代码。

核心原则

⚠️ 设计阶段禁止修改代码

• 在方案设计和文档生成阶段，绝不修改任何源代码文件
• 仅在用户在「开发确认」环节明确同意后，方可进行代码开发
• 只创建文档文件，不触碰任何 .ts、.vue、.json 等代码文件（除非进入开发阶段）
• 如果用户在设计阶段要求修改代码，必须明确拒绝并说明先完成设计

项目代码组织规范

• 主进程业务逻辑：放在 src/main/modules/<模块名>/ 下，如 oss.service.ts、oss.repository.ts
• OSS 适配器：src/main/modules/oss/adapter/ 下，按云服务商命名（如 Ali/Impl.ts）
• 渲染进程钩子：src/renderer/hooks/service/ 存放业务钩子，src/renderer/hooks/common/ 存放通用工具钩子
• IPC 入口：src/main/modules/oss/oss.service.ts 处理来自渲染进程的 IPC 请求
• 命令式调用：通过 window.api.ipcRenderer.invoke('channel', data) 从渲染进程调用主进程

路径完整性要求

重要：设计文档中所有文件路径必须从项目根目录开始写完整路径，禁止写相对路径。

• ✅ 正确：src/main/modules/oss/adapter/Ali/Impl.ts
• ❌ 错误：Ali/Impl.ts
• ❌ 错误：./Ali/Impl.ts

这一要求适用于文档中所有出现文件路径的位置，包括但不限于代码块引用、修改点一览、方案对比中的路径列举。

语言要求

重要：全程使用中文生成文档

• 所有功能描述和文档内容必须使用中文
• 文件名中的英文描述除外（保持技术命名规范）
• plan 模式讨论和最终生成的 .md 文档都必须是中文
• 代码分析和建议也要用中文表达

文件命名规范

• 使用当前日期格式：YYYY-MM-DD
• 添加功能的简短英文描述
• 用连字符分隔单词

示例：

• 2026-05-03-directory-download.md
• 2026-05-03-batch-upload.md
• 2026-05-03-file-preview.md

文件内容结构

# 功能：[功能名称]

**日期**：[当前日期]
**状态**：计划中
**模块归属**：[涉及的主要模块，如 oss、upload、download]

## 背景 / Context

[问题背景、现状描述，以及为什么需要这个功能]

## 需求

- [从问答阶段整理出的功能需求]
- [典型使用场景]
- [输入输出要求]

## 方案对比

- 方案 A：[简要描述 + 适用场景 + 优缺点]
- 方案 B：[简要描述 + 适用场景 + 优缺点]
- 方案 C：[如有]

## 最终实现方案

- 选定方案：[A/B/C 或组合]
- IPC 通道设计：
    - 通道名：`ipc:xxx`
    - 参数结构：
- 前端钩子设计：
    - 位置：`src/renderer/hooks/service/useXxx.ts`
    - 导出接口
- 行为说明：
    - 正常流程
    - 错误处理
- 与现有功能的兼容性：
    - [如何避免破坏现有行为]

## 修改点一览（设计层面）

- 主进程：
    - [需要增加或修改的模块，仅列路径和职责]
    - 如 `src/main/modules/oss/oss.service.ts` 增加 xxx 方法
- 渲染进程：
    - [需要新增或调整的钩子/组件]
    - 如 `src/renderer/hooks/service/useXxx.ts` 新增钩子
- IPC 通道：
    - [新增或修改的 IPC 通道]
- 类型定义：
    - [如需新增或修改类型，如 `src/shared/types.ts`]

## 代码分析

[对现有代码结构的分析和建议，包含与本功能相关的模块关系、数据流向等]

## 备注

[额外的备注、风险、后续可扩展方向]

边界说明

如果用户试图让本 skill 修改代码：

• 明确告知本 skill 只负责功能设计和记录
• 建议用户使用其他适当的工具或 skill 来修改代码
• 坚持只创建文档文件的原则（除非已进入开发确认阶段）