---
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`

## 文件内容结构

```markdown
# 功能：[功能名称]

**日期**：[当前日期]
**状态**：计划中
**模块归属**：[涉及的主要模块，如 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 来修改代码
- 坚持只创建文档文件的原则（除非已进入开发确认阶段）