VSCode 插件开发

mkdir md-wx-vscode
cd md-wx-vscode

git init

git clone <your-github-repository-url>

需求分析，以下是我的需求，请根据我的主要需求内容，完成需求分析，结果以 Markdown 格式写入 docs 目录下。

做一个 VS Code 插件，当在 markdown 文件中时，点击一个按钮打开 Markdown 预览窗口，能预览当前打开的这个 Markdown 文件内容，这个预览窗口使用 md-wx 组件来渲染 Markdown 源文件，当 Markdown 内容变化时预览窗口的内容也实时发生变化。

这个 md-wx 组件主要功能是将 Markdown 内容渲染为微信公众号样式，并且提供了一键复制功能。预览窗口直接使用这个组件渲染即可，你不需要自己实现。

以上优先级比较高，还有一个优先级为中的需求是，当用户在 Markdown 内粘贴图片时能以链接的方式插入到粘贴的位置，这里可以选择将图片上传到某个存储服务

<IMPORTANT>
目前只是需求分析阶段，当你完成需求分析文档后请立即停止任务，等待下一步指令。
需求分析文档中不要写技术实现，只描述需求。不要做任何的代码实现
</IMPORTANT>

# VS Code Markdown 微信公众号样式预览插件需求分析

## 1. 项目概述

本项目旨在开发一款 VS Code 插件，以提升 Markdown 文件在微信公众号文章排版场景下的编辑和预览体验。插件的核心功能是提供一个集成了 `md-wx` 组件的实时预览窗口，并支持图片粘贴上传，从而简化从 Markdown 到微信公众号文章的发布流程。

## 2. 核心需求 (优先级：高)

### 2.1 Markdown 实时预览

- **用户故事:** 作为一名内容创作者，当我在 VS Code 中编辑 Markdown 文件时，我希望能够点击一个按钮，立即打开一个预览窗口，实时查看 `md-wx` 组件渲染后的微信公众号样式效果。

- **功能描述:**
    - 在 VS Code 编辑器界面（例如，编辑器右上角工具栏）提供一个明确的图标按钮，用于开启/关闭 Markdown 预览窗口。
    - 预览窗口应与当前激活的 Markdown 编辑器关联。当切换到不同的 Markdown 文件时，预览窗口应自动更新内容。
    - 当 Markdown 文件的内容发生任何更改（如输入、删除、修改）时，预览窗口的内容必须实时、无延迟地同步更新，以反映最新的渲染效果。

### 2.2 集成 `md-wx` 渲染引擎

- **用户故事:** 我希望预览窗口的样式与微信公众号文章的最终样式完全一致，并且能够使用 `md-wx` 组件提供的一键复制功能，方便我将排版好的内容直接粘贴到微信公众号后台。

- **功能描述:**
    - 预览窗口的内容展示完全由 `md-wx` 组件负责渲染。
    - 插件需要完整支持 `md-wx` 组件的所有功能，特别是其独特的微信公众号主题样式和代码块样式。
    - `md-wx` 组件自带的“一键复制”功能需要在预览窗口中可用且功能正常，用户点击后能将渲染后的 HTML 内容复制到剪贴板。

## 3. 次要需求 (优先级：中)

### 3.1 图片粘贴自动上传与链接插入

- **用户故事:** 当我从本地文件系统或网络上复制一张图片并粘贴到 Markdown 编辑器中时，我希望插件能自动将图片上传到指定的图床服务，并将返回的图片 URL 以 Markdown 图片格式 `` 插入到我光标所在的位置。

- **功能描述:**
    - 插件需要能够监听到在 Markdown 文件中的粘贴操作。
    - 当检测到粘贴内容为图片时，触发图片上传流程。
    - 用户应可以配置图片上传的目标服务（例如，某个特定的图床或云存储服务）。
    - 上传成功后，将返回的图片链接自动格式化为 Markdown 语法，并插入到编辑器中。
    - 上传过程中应有状态提示（如“上传中...”、“上传成功/失败”）。

## 4. 非功能性需求

- **4.1 易用性:** 插件的各项功能应直观易用，用户无需复杂的配置即可上手。
- **4.2 性能:** 实时预览功能不应导致编辑器卡顿或性能下降。图片上传过程应在后台进行，不阻塞用户的正常编辑操作。
- **4.3 稳定性:** 插件运行应保持稳定，不能频繁出现错误或导致 VS Code 崩溃。

根据需求文档，完成技术架构设计文档，结果以 Markdown 格式写入 docs 目录下。

1. 设定清晰的目录结构规范。
2. 设定编码规范。
3. md-wx 是本地的一个组件，当前还未发布至 NPM 仓库，请先基于本地的方式进行调试，参考 md-wx 组件文档。
4. 注意 md-wx 之前是一个在浏览器端运行的组件，在 VS Code 插件中运行时，需要考虑该如何支持。

<IMPORTANT>
目前只是技术架构设计阶段，当你完成技术架构设计文档后请立即停止任务，等待下一步指令。
技术架构设计文档中不要写技术实现，只描述技术架构、方案。不要做任何的代码实现
</IMPORTANT>

# VS Code Markdown 微信公众号样式预览插件技术架构设计

## 1. 概述

本文档旨在为 “VS Code Markdown 微信公众号样式预览插件” 提供一套完整的技术架构方案。该方案基于需求文档中定义的功能，旨在确保插件的健壮性、可扩展性和可维护性。

## 2. 技术选型

- **核心框架**: [VS Code Extension API](https://code.visualstudio.com/api)
- **语言**: TypeScript
- **UI 框架 (Webview)**: React
- **Markdown 渲染**: `md-wx` (本地链接)
- **打包工具**: Webpack / Vite (用于打包 Webview 内容)
- **代码规范**: ESLint + Prettier

## 3. 架构设计

插件将采用经典的 VS Code 插件架构，分为 **Extension Host** 和 **Webview** 两部分。

- **Extension Host**: 运行在 VS Code 主进程之外的独立 Node.js 进程。负责处理插件的生命周期、命令注册、文件系统交互、Webview 面板的创建与管理等核心逻辑。
- **Webview**: 一个在 VS Code 编辑器内渲染 Web 内容的沙箱环境。它将用于承载 `md-wx` 组件，并负责实时预览 Markdown 内容。

### 3.1 通信机制

Extension Host 与 Webview 之间通过 `postMessage` API 进行双向异步通信。

- **Extension Host -> Webview**: 发送更新后的 Markdown 内容、配置信息等。
- **Webview -> Extension Host**: 发送用户操作事件（如请求复制内容）、图片粘贴事件等。

## 4. 目录结构规范

\`\`\`
.vscode/          # VS Code 调试与任务配置
src/
├── extension/
│   ├── extension.ts      # 插件主入口，负责激活、命令注册
│   ├── commands.ts       # 命令处理模块
│   └── previewPanel.ts   # Webview 预览面板管理
├── webview/
│   ├── index.tsx         # Webview React 应用入口
│   ├── App.tsx           # React 主组件，集成 md-wx
│   ├── styles/           # Webview 相关样式
│   └── vite.config.ts    # Webview 打包配置 (如果使用 Vite)
package.json      # 项目依赖与插件清单
tsconfig.json       # TypeScript 编译配置
.eslintrc.js      # ESLint 配置
.prettierrc.js    # Prettier 配置
\`\`\`

## 5. 核心功能实现方案

### 5.1 Markdown 实时预览

1.  **触发**: 监听 `vscode.workspace.onDidChangeTextDocument` 事件。
2.  **数据同步**: 当当前激活的 Markdown 文档内容变化时，通过 `postMessage` 将最新的文档内容发送到 Webview。
3.  **渲染**: Webview 中的 React 应用接收到新内容后，将其作为 `prop` 传递给 `md-wx` 的 `MarkdownRenderer` 组件进行重新渲染。

### 5.2 `md-wx` 组件集成与本地调试

- **挑战**: `md-wx` 是一个为浏览器环境设计的 React 组件，需要被打包后才能在 Webview 中运行。
- **方案**:
    1.  **本地链接**: 遵循 `api-usage.md` 中的指南，在本项目中通过 `npm link md-wx` 将本地的 `md-wx` 组件链接到 `node_modules` 中。
    2.  **Webview 打包**: 使用 Vite 或 Webpack 作为打包工具。创建一个独立的 `webview` React 项目，该项目 `import` `md-wx` 组件。打包工具会将 React、`md-wx` 及其依赖（包括 CSS）捆绑成一个或多个静态文件（JS, CSS）。
    3.  **资源加载**: Extension Host 在创建 Webview Panel 时，将打包后的静态资源路径转换为 VS Code 的 `vscode-resource:` URI 格式，并注入到 Webview 的 HTML 模板中。

### 5.3 图片粘贴与上传

- **方案**: 由于直接在 Webview 中监听粘贴事件并访问本地剪贴板图片数据存在限制，将采用 Extension Host 作为中转。
    1.  **命令注册**: 创建一个自定义的 `paste` 命令，并为其设置快捷键（如 `Cmd+V` / `Ctrl+V`），同时通过 `when` clause 上下文限定它只在 Markdown 文件中生效。
    2.  **图片处理**: 该命令的处理器将使用 Node.js 的 `child_process` 模块调用系统脚本（如 PowerShell for Windows, AppleScript for macOS）来读取剪贴板中的图片内容并保存为临时文件。
    3.  **上传与替换**: 将临时图片文件上传至用户配置的图床，获取 URL 后，将 `` 格式的文本插入到当前光标位置。

## 6. 编码规范

- **代码风格**: 遵循 Prettier 的默认规则，确保代码风格一致性。
- **代码质量**: 使用 ESLint，并开启推荐的 TypeScript 规则集，以捕捉潜在错误和不规范的写法。
- **命名**:
    - 变量和函数使用 `camelCase`。
    - 类和接口使用 `PascalCase`。
    - 私有成员使用 `_` 前缀。
- **注释**: 对复杂的逻辑、算法或重要的架构决策添加清晰的 JSDoc 注释。

## 7. 下一步

待此技术架构设计评审通过后，将进入编码实现阶段。首先搭建项目脚手架，并优先实现实时预览的核心功能。

任务拆分

根据需求文档、架构文档，完成任务拆分，结果以 Markdown 格式写入 docs 目录下。

根据优先级对任务按模块进行拆分，拆解要合理，每个模块完成后都能看到一些效果。这个拆分后的任务我们是让 AI 分步骤去实现的。

<IMPORTANT>
目前只是任务拆分阶段，当你完成任务拆分文档后请立即停止任务，等待下一步指令。
任务拆分文档中不要写技术实现，只描述任务拆分。不要做任何的代码实现
</IMPORTANT>

# VS Code 插件任务拆分

本文档根据需求与架构设计，将插件开发任务拆分为多个里程碑，旨在实现渐进式开发，确保每个阶段都有可验证的成果。

## 里程碑一：项目初始化与基础预览窗口

**目标：** 搭建项目骨架，跑通最基础的插件流程，能够手动打开一个空白的预览窗口。

- **任务 1.1：初始化项目**
  - 描述：使用 `yo code` 工具生成一个标准的 VS Code TypeScript 插件项目。

- **任务 1.2：规范目录结构**
  - 描述：根据 `technical_architecture.md` 文档，创建 `src/extension` 和 `src/webview` 等核心目录。

- **任务 1.3：实现预览命令**
  - 描述：在 `package.json` 中注册一个命令（如 `md-wx-vscode.showPreview`），并在编辑器右上角添加一个图标按钮来触发此命令。

- **任务 1.4：创建 Webview 面板**
  - 描述：实现 `previewPanel.ts`，编写一个能够创建和管理 Webview 面板的类。命令触发时，应能成功弹出一个包含静态 “Hello World” 内容的 Webview。

## 里程碑二：集成 `md-wx` 并实现实时预览

**目标：** 将 `md-wx` 组件集成到 Webview 中，并实现当 Markdown 文档内容变更时，预览窗口实时更新渲染效果。

- **任务 2.1：搭建 Webview React 环境**
  - 描述：将 `src/webview` 目录设置为一个独立的 React 项目，并配置 Vite 或 Webpack 进行打包，使其能够引入 `md-wx` 组件。

- **任务 2.2：集成 `md-wx` 组件**
  - 描述：在 Webview 的 React 应用中，引入 `md-wx` 组件，并能成功渲染一个固定的 Markdown 字符串。

- **任务 2.3：建立双向通信**
  - 描述：实现 Extension Host 与 Webview 之间的 `postMessage` 通信机制。Extension Host 能够向 Webview 发送消息。

- **任务 2.4：实现内容同步与实时预览**
  - 描述：监听 `vscode.workspace.onDidChangeTextDocument` 事件。当活动的 Markdown 文件内容发生变化时，Extension Host 将最新的完整内容发送给 Webview，Webview 接收后交由 `md-wx` 组件重新渲染。

## 里程碑三：核心功能完善

**目标：** 实现 `md-wx` 的核心交互功能，使用户体验闭环。

- **任务 3.1：实现“一键复制”功能**
  - 描述：在 Webview 中响应 `md-wx` 组件的复制事件，通过 `postMessage` 通知 Extension Host，由 Extension Host 调用 `vscode.env.clipboard.writeText` API 将渲染后的 HTML 内容写入系统剪贴板。

- **任务 3.2：优化窗口管理**
  - 描述：确保预览窗口与当前激活的 Markdown 编辑器正确关联。切换编辑器标签页时，预览窗口应自动更新为新激活文件的内容。

## 里程碑四：图片粘贴上传功能

**目标：** 实现次要需求中的图片粘贴自动上传功能，提升编辑效率。

- **任务 4.1：注册自定义粘贴命令**
  - 描述：创建一个自定义的 `paste` 命令，并配置快捷键，使其在 Markdown 文件中生效，覆盖默认的粘贴行为。

- **任务 4.2：实现剪贴板图片读取**
  - 描述：在命令处理器中，使用 `child_process` 调用系统脚本（如 AppleScript）来读取剪贴板中的图片数据，并将其保存为临时文件。

- **任务 4.3：实现图片上传（模拟）**
  - 描述：创建一个图片上传服务模块。初期可以是一个模拟实现，接收图片文件路径后，直接返回一个固定的占位符 URL。

- **任务 4.4：插入图片链接**
  - 描述：图片上传成功后，将返回的 URL 格式化为 `` 形式，并插入到当前光标所在位置。

## 里程碑五：配置与发布准备

**目标：** 增加可配置项，进行最终的润色和打包准备。

- **任务 5.1：添加用户配置**
  - 描述：允许用户在 VS Code 设置中配置图床信息（此阶段仅定义配置项，无需实现真实上传逻辑）。

- **任务 5.2：添加状态提示**
  - 描述：在图片上传过程中，通过 VS Code 的状态栏或信息提示，向用户反馈“上传中...”、“上传成功/失败”等状态。

- **任务 5.3：代码清理与文档完善**
  - 描述：审查和重构代码，添加必要的注释，并更新 README 文档，说明插件功能和使用方法。

- **任务 5.4：打包与测试**
  - 描述：执行最终的打包流程，生成 `.vsix` 安装文件，并进行手动安装测试，确保所有功能正常。

项目规则制定

根据架构文档，完成项目规则制定，这个规则是给 AI 看的，旨在让 AI 在当前项目开发中，能够按照规则来实现。主要包括代码风格、语言或框架、NPM 包管理、项目目录结构、项目规范等。结果以 Markdown 格式写入 ./trae/rules/project_rules.md 文件中。

项目开发规则应该更侧重于高层面的指导原则，而不是具体的实现细节。

以下是在别的项目中为 AI 设置的 “AI 助手任务执行规范“ 目的是让 AI 严格按照我们的规范来做，你可以将这个规范添加到我们的项目规范中。

## AI 助手任务执行规范

为确保开发过程的有序性和可控性，AI 助手必须严格遵循以下任务执行规范：

### 任务范围控制

- **严格按照任务拆分执行**: 必须严格按照 `docs/task_breakdown.md` 中定义的任务范围执行，不得超出指定任务的边界。
- **单一任务原则**: 每次只执行一个明确指定的任务（如"任务 1.1"、"任务 1.2"等），完成后等待用户确认再进行下一步。
- **禁止自动扩展**: 不得基于技术架构文档或其他文档自行扩展任务范围，如果需要扩展需要通知用户确认。

### 任务指令格式

用户应使用以下格式明确指定任务：

- **明确任务编号**: "请执行任务 X.X：[任务名称]"
- **范围限制**: "只完成任务 X.X 中列出的具体任务，不要超出范围"
- **停止指令**: "完成后等待我确认再进行下一步"

### 执行验收标准

- **任务完成确认**: 每个任务完成后，必须对照 `task_breakdown.md` 中的验收标准进行自检。
- **范围边界检查**: 确保所有创建的文件和代码都在指定任务范围内。
- **等待用户确认**: 任务完成后使用 `finish` 工具总结完成情况，等待用户确认后再进行下一个任务。

### 异常处理

- **任务描述不清晰**: 如果任务描述不清晰，应先询问具体范围而不是自行决定。
- **依赖关系处理**: 如果当前任务依赖其他未完成的任务，应明确指出依赖关系并等待用户指示。
- **超出范围的代码**: 如果发现已创建超出任务范围的代码，应主动询问是否需要清理。

# 项目开发规则

## 1. 核心目标

本项目的核心目标是开发一个 VS Code 插件，用于提供 Markdown 的微信公众号样式实时预览。所有技术决策和实现都应围绕提升内容创作者在微信生态下的写作与排版效率展开。

## 2. 技术栈与框架

- **语言**: 必须使用 **TypeScript**。
- **核心框架**: 严格基于 **VS Code Extension API**。
- **Webview UI**: 使用 **React** 构建。
- **Markdown 渲染**: 必须使用本地链接的 **`md-wx`** 组件。
- **打包工具**: Webview 部分的代码必须通过 **Vite** 或 **Webpack** 进行打包。

## 3. 代码风格与质量

- **格式化**: 所有代码提交前必须使用 **Prettier** 进行格式化。
- **静态检查**: 必须遵循 **ESLint** 规则，不允许存在任何 ESLint 错误。
- **命名规范**:
  - 变量和函数：`camelCase`
  - 类、接口、类型：`PascalCase`
  - 私有成员：`_` 前缀
- **注释**: 核心函数、复杂逻辑、公共 API 必须有清晰的 JSDoc 注释。

## 4. 项目目录结构

必须严格遵守 `technical_architecture.md` 中定义的目录结构。核心结构如下：

\`\`\`
src/
├── extension/      # Extension Host 逻辑
│   ├── extension.ts
│   ├── commands.ts
│   └── previewPanel.ts
├── webview/        # Webview React 应用
│   ├── index.tsx
│   └── App.tsx
package.json
...
\`\`\`

任何文件的创建或移动都必须符合此结构规范。

## 5. 依赖管理

- **`md-wx` 组件**: 必须通过 `npm link` 或等效的本地方式引入，严禁从 NPM 公共仓库安装。
- **NPM 包**: 添加新的 NPM 依赖前，应优先考虑 VS Code API 是否提供原生能力。若无，则选择流行度高、维护活跃的库。

## 6. 通信协议

Extension Host 与 Webview 之间必须通过 `postMessage` 进行异步通信。通信消息应定义明确的类型接口（Interface）。

## 7. AI 助手任务执行规范

为确保开发过程的有序性和可控性，AI 助手必须严格遵循以下任务执行规范：

### 7.1 任务范围控制

- **严格按照任务拆分执行**: 必须严格按照 `docs/task_breakdown.md` 中定义的任务范围执行，不得超出指定任务的边界。
- **单一任务原则**: 每次只执行一个明确指定的任务（如“任务 1.1”），完成后等待用户确认再进行下一步。
- **禁止自动扩展**: 不得基于技术架构文档或其他文档自行扩展任务范围。

### 7.2 任务指令格式

用户将使用以下格式明确指定任务：

- **明确任务编号**: "请执行任务 X.X：[任务名称]"

### 7.3 执行验收标准

- **任务完成确认**: 每个任务完成后，必须对照 `task_breakdown.md` 中的验收标准进行自检。
- **等待用户确认**: 任务完成后，总结完成情况并等待用户确认。

### 7.4 异常处理

- **任务描述不清晰**: 如果任务描述不清晰，应先询问。
- **依赖关系处理**: 如果当前任务依赖其他未完成的任务，应明确指出。