项目搭建、集成 md-wx 组件

从需求文档到可用的 VS Code 插件，本教程将带你走完一次完整的 AI 辅助开发之旅。我们将通过三个阶段的迭代，展示如何利用 AI 快速完成项目搭建与功能实现，并直面开发中遇到的各类 Bug，甚至是 AI 自身的“幻觉”，为你还原一个真实、高效的人机协作开发过程。

阶段一：项目搭建与基础功能开发

万事开头难，一个规范、完整的项目初始结构是后续高效开发的基础。在这一阶段，我们将引导 AI 完成项目创建、添加必要配置，并最终能够成功在本地进行调试。

1. 初始项目生成

我们首先向 AI 发出指令，要求它帮助我们初始化一个标准的 VS Code TypeScript 插件项目。

提示词：

阶段一：项目初始化与基础预览窗口

这是文档 [requirement_analysis.md] [technical_architecture.md]，只完成任务 [task_breakdown.md 5-20] “阶段一：项目初始化与基础预览窗口”的功能，不要超出范围。

AI 接收指令后，开始自动化地执行一系列任务，包括创建目录、生成配置文件等。

2. 发现并修复问题

AI 完成了第一轮任务，但经过审视，我们发现了一些常见但关键的疏漏：

• 缺少 README.md：项目没有提供任何关于如何运行和调试的说明，这对于新加入的开发者或者未来的自己都是一个障碍。
• 缺少 .gitignore：node_modules 这样的依赖目录没有被添加到忽略列表，这意味着它可能会被错误地提交到版本控制系统中，这是开发中的一个基本错误。

为了弥补这些缺陷，我们继续向 AI 发出明确的改进指令。

提示词：

写一个 README 文档，告诉我该怎么本地调试
添加 git 忽略文件

AI 迅速响应，为我们生成了详细的 README.md 文档和一份标准的 .gitignore 文件，使项目结构更加规范和完整。

3. 本地调试

现在，项目的基础设施已经准备就绪。我们可以参照 README.md 中的说明，开始进行本地调试，以验证我们的基础功能。

调试步骤详解：

1. 启动调试模式：在 Trae IDE 的左侧活动栏中，点击“运行和调试”图标。

2. 运行扩展：在顶部弹出的调试配置中，选择 "Run Extension" 并点击绿色的启动按钮（或直接按 F5）。

3. 打开测试项目：该操作会启动一个新的【扩展开发主机】窗口。在这个新窗口中，我们需要打开一个用于测试的项目文件夹。由于我们的插件功能与 Markdown 文件相关，请确保你打开的项目中至少包含一个 .md 文件。

4. 验证功能：打开任意 Markdown 文件。此时，根据我们的功能设计，你应该可以在编辑器的右上角看到一个预览图标。点击该图标，即可验证我们的 Webview 面板是否能被成功唤起。

4. 调试与修复：AI 辅助解决 Bug

在实际开发中，一帆风顺的情况很少见。接下来，我们将演示当遇到问题时，如何与 AI 协作快速定位并解决问题。

点击预览报错

当我们满怀期待地点击预览按钮时，却弹出了一个错误提示。

这个错误信息 command 'md-wx-vscode.showPreview' not found 指示我们注册的命令没有被正确找到。我们将这个错误截图并反馈给 AI，让它帮助我们分析和修复。

AI 分析后发现问题在于 package.json 中缺少了 publisher 字段，并缺少了 .vscode/launch.json 调试配置文件。它迅速为我们补全了这些信息并重新编译。修复完成后，我们再次进行调试，这次成功地看到了预览窗口。

解决编译警告

虽然功能已经可以正常预览，但在启动调试时，我们留意到了一个来自 preLaunchTask 的警告信息，这通常意味着代码中存在一些不规范的写法。

为了探究根源，我们点击“显示错误”按钮，查看更详细的 TypeScript 编译错误。

我们将这个详细的错误信息截图，并再次向 AI 求助，要求它修复这些 TypeScript 的严格模式警告。

AI 精准地定位到了问题所在：代码中存在未使用的变量。它通过在变量名前添加下划线 _ 的方式，向编译器表明这些是预留参数，从而消除了警告。

经过这一轮修复，我们的项目不仅功能正常，而且代码质量也更高，为后续的迭代开发打下了坚实的基础。

阶段二：集成 md-wx 并实现实时预览

在完成了项目的基础搭建后，我们进入了核心功能的开发阶段。我们的目标是集成一个名为 md-wx 的本地 Markdown 渲染组件，以实现微信公众号样式文章的实时预览。

1. 功能开发

我们向 AI 发出第二阶段的任务指令，要求它在现有项目的基础上，搭建 Webview React 环境，并集成 md-wx 组件。

提示词：

阶段二：集成 `md-wx` 并实现实时预览

这是文档 [requirement_analysis.md] [technical_architecture.md]，只完成任务 [task_breakdown.md 20-36] “阶段二：集成 `md-wx` 并实现实时预览”的功能，不要超出范围。

注意，md-wx 是一个本地的组件，需要使用 npm link md-wx 命令安装，组件文档参考 api-usage.md

AI 开始执行一系列复杂的任务，包括创建 webview 目录、配置 Vite 和 TypeScript 环境、安装依赖，并使用 npm link 链接本地的 md-wx 组件，最后将组件集成到 App.tsx 中。

2. 多轮调试与修复

首次尝试预览，我们遇到了一个典型的问题：页面空白。这在 Web 开发中很常见，通常意味着前端代码在渲染过程中遇到了错误。

排查思路与开发者工具

直接告诉 AI “页面白屏”当然是一种方法，但 AI 可能需要多次交互才能定位到根源。如果我们能提供更丰富的上下文，比如错误日志，就能极大地帮助 AI 提高效率。

幸运的是，VS Code（以及 Trae）本身是基于 Electron 构建的，这意味着我们可以像调试普通网页一样，使用强大的开发者工具来检查 Webview 中运行的内容。

如何打开开发者工具？

1. 点击顶部菜单栏的“帮助(Help)”。
2. 选择“切换开发人员工具(Toggle Developer Tools)”。

这会在编辑器右侧打开一个熟悉的窗口，包含 Console, Elements, Network 等面板，就像在 Chrome 中一样。

有了这个利器，我们就可以开始精准地排查问题了。

第一轮修复

我们向 AI 描述了白屏问题，并要求它添加日志来帮助定位。（这些日志是后面给 AI 看的）

提示词：

打开预览组件后没有正确的渲染到内容，看起来是没有获取到内容
当鼠标在 Markdown 源文件中点击后页面白屏
请检查问题并修复，适当的加一些日志

AI 在 previewPanel.ts 和 App.tsx 中添加了详细的日志。修复后再次预览，虽然页面上依然没有渲染出内容，但预览组件已经渲染了，并且开发者工具的控制台(Console)中已经打印出了许多有价值的日志信息。

第二轮修复

从日志中可以看到，扩展端(Extension Host)已经成功地将 Markdown 内容发送给了 Webview，但 Webview 端似乎没有正确接收或处理。我们将这个关键信息连同日志截图，再次反馈给 AI。

提示词：

页面上没有看到渲染的内容，请根据控制台日志查找问题根源
注意，你一定要使用我提供给你的组件，不要自己去实现这个预览组件

红色标注的内容，下面会讲到

这次，AI 精准地发现了问题所在：window.acquireVsCodeApi() 在 App.tsx 中被错误地多次调用。这个函数在 Webview 中只能被调用一次，并且应该在组件外部调用后，将其结果保存下来供整个应用使用。

AI 修复了这个问题，重新构建了 Webview 应用。

成功实现预览

经过两轮细致的调试和修复，我们再次运行插件，终于看到了期待已久的效果！Markdown 文档被成功地渲染成了微信公众号样式。

这个过程充分展示了人与 AI 协作解决问题的强大威力。开发者利用自己的专业知识和调试工具（如开发者工具）提供关键线索，AI 则利用其强大的代码理解和生成能力快速实施修复方案，大大缩短了从发现问题到解决问题的周期。

3. 最终修复

虽然内容成功渲染，但我们很快发现一个新的问题：预览窗口右上角的设置面板消失了。这意味着我们虽然能看到内容，但失去了主题切换、视图模式切换等核心交互功能。

深挖问题根源

我们查阅了 md-wx 组件的 API 文档 (api-usage.md)，发现它其实提供了两个组件：

1. MarkdownRenderer: 核心渲染组件，包含设置面板和所有交互功能。
2. Previewer: 纯预览组件，不包含编辑和设置功能。

显然，AI 在之前的某一步修复中，错误地将功能完整的 MarkdownRenderer 替换成了功能简化的 Previewer。

我们向 AI 明确指出这个问题，要求它换回正确的 MarkdownRenderer 组件。

提示词：

按照最新修改，使用 Previewer 组件进行内容渲染是可以的，但是 MarkdownRenderer 组件是存在的，并且也经过了验证，可以参考文档 api-usage.md

因为需要使用到 MarkdownRenderer 组件的设置面板，所以要用 MarkdownRenderer 这个组件，请你替换为 MarkdownRenderer 组件，并确保能正常使用

AI 接收指令后，将 App.tsx 中的组件换回 MarkdownRenderer，并使用了正确的 markdown 属性来传递内容，同时更新了 TypeScript 类型定义文件，最终成功地恢复了包含完整设置面板的预览功能。

4. AI 行为剖析

剖析 AI 的“幻觉”：为何会用错组件？

这是一个非常有趣的案例，值得我们深入分析。为什么在 API 文档明确指出存在 MarkdownRenderer 的情况下，AI 仍然会“自作主张”地换用 Previewer，甚至在其修复日志中声称 MarkdownRenderer 是“不存在的”？

根源在于类型定义（Type Definition）的缺失。

我们的项目是基于 TypeScript 的，而 md-wx 组件本身是一个纯 JavaScript 库，并未提供 .d.ts 类型声明文件。当 AI 在 TypeScript 环境中尝试使用一个没有类型定义的组件时，为了让代码通过静态检查、避免编译报错，它会做出自己的“推断”和“决策”。

1. 初次尝试与类型文件的“创建”：当 AI 第一次尝试集成 md-wx 时，它发现 MarkdownRenderer 没有类型定义。为了解决这个问题，它在我们的项目内部（src/webview/src/types/md-wx.d.ts）“凭空”创建了一个类型声明文件，但这个文件很可能只包含了最基础的、用于解决当前问题的类型信息，比如一个简单的 Previewer 组件定义。

2. 基于“错误”的修复：在后续修复白屏问题的过程中，AI 基于它自己创建的、不完整的类型文件进行逻辑推理。在它的“世界”里，md-wx 模块只导出了 Previewer 组件，因此它会得出结论——“MarkdownRenderer 不存在，应该使用 Previewer”，并将代码修改为它认为“正确”的 Previewer 用法。

3. 最终的人工校正：直到我们明确要求换回 MarkdownRenderer，AI 才重新审视了 API 文档和我们的指令，并更新了它自己创建的类型定义文件，加入了 MarkdownRenderer 及其所有 props 的完整声明，最终解决了问题。又把 Previewer 的类型定义删除了。

这个案例给我们的启示是，AI 虽然强大，但它的行为深度依赖于我们提供的上下文。在处理跨语言（如在 TS 中使用 JS 库）或类型信息不完整的场景时，AI 可能会为了“让代码跑通”而产生“幻觉”或做出不完全正确的决策。作为开发者，我们需要理解这种现象，并在关键时刻提供明确、强制的指令，引导 AI 走上正确的道路。理想情况下，更根本的解决方案是为 md-wx 组件本身提供完整的类型定义文件。我们后续也将会对 md-wx 组件进行修复。

阶段三：核心功能完善

经过前两个阶段的开发与调试，我们的插件已经具备了核心的实时预览功能。现在，我们进入最后一个开发阶段，目标是完善核心交互，并打磨最终的 UI 细节。

1. 实现“一键复制”功能

根据我们的需求文档，一个关键功能是让用户能够“一键复制”渲染后的 HTML 内容，以便轻松地粘贴到微信公众号等平台。

我们向 AI 发出第三阶段的任务指令。

提示词：

阶段三：核心功能完善

这是文档 [requirement_analysis.md] [technical_architecture.md]，只完成任务 [task_breakdown.md 38-46] “阶段三：核心功能完善”的功能，不要超出范围。

AI 开始在 App.tsx 和 previewPanel.ts 中添加实现复制功能所需的代码。

2. 修复复制功能并清理界面

功能添加后，我们立刻进行测试。当点击预览窗口右上角的“复制”按钮时，出现了两个问题：

1. 预览面板下方提示“当前没有活动的 Markdown 文档”。
2. 编辑器弹出一个错误，点击“显示错误”后可以看到详细的 TypeScript 类型错误，提示 ref 属性不存在。

我们将这两个问题截图，并附上详细的错误信息，再次向 AI 发出修复指令。

提示词：

一点复制后，内容就没有了 并且还有图中提示 “当前没有活动的 Markdown 文档”

还有一个问题是点击调试时有报错

不能将类型“{ ref: MutableRefObject<any>; markdown: string; theme: "sakura"; showSettings: true; enableCopy: true; enableThemeSwitch: true; enableViewModeToggle: true; onCopy: () => void; }”分配给类型“IntrinsicAttributes & MarkdownRendererProps”。
  类型“{ ref: MutableRefObject<any>; markdown: string; theme: "sakura"; showSettings: true; enableCopy: true; enableThemeSwitch: true; enableViewModeToggle: true; onCopy: () => void; }”上不存在属性“ref”。

AI 接收指令后，成功修复了 ref 的使用问题和复制的逻辑。但在此前修复过程中，它在界面上添加了一些用于调试的日志信息。这些信息对于最终用户是无用的，因此我们继续发出指令，要求它清理界面。

提示词：

预览面板直接展示预览组件的内容，把自己加的信息去掉，包括调试信息

经过清理，界面恢复了整洁。我们再次测试“一键复制”功能，这次一切正常！点击复制按钮后，可以将渲染好的内容完美地粘贴到微信公众号编辑器中。

3. 修复最终样式问题

在完成所有功能后，我们进行最后的视觉走查，发现一个细节问题：在 VS Code 的预览窗口中，代码块的每一行都有一个深色的背景，这影响了视觉体验。但在 Web 端直接打开或者粘贴到公众号后，这个背景又消失了。这通常意味着存在一些只在 VS Code Webview 环境下才会生效的特定样式覆盖。

我们向 AI 描述了这个样式问题，并要求它移除代码行的背景色。

AI 通过分析，最终定位到是 VS Code 默认主题的某个 CSS 变量影响了我们的组件样式。它通过添加一段简单的 CSS 代码覆盖了这个变量，彻底解决了问题。

最终，预览效果完美，与在 Web 端和公众号中完全一致。

4. 总结与展望

至此，我们从一个简单的想法开始，通过三个阶段的迭代开发，借助 AI 的力量，成功完成了一款功能完整、体验良好的 VS Code 微信公众号格式预览插件。

这个过程充分展示了现代 AI 辅助开发的强大潜力。我们不再需要逐行编写所有代码，而是将更多精力放在需求分析、功能设计和与 AI 的高效协作上。

下一步，我们将继续为这个插件增加更强大的功能，例如集成图床服务，实现粘贴图片时自动上传并替换链接。