| 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. 触发与意图识别
从用户输入中识别：
- 是新功能还是对现有功能的增强
- 涉及哪个模块（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.md2026-05-03-batch-upload.md2026-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 来修改代码
- 坚持只创建文档文件的原则（除非已进入开发确认阶段）
