用 AI 高效开发浏览器插件：SDD 文档先行实战

文章目录

- 引言：一个浏览器插件要解决什么问题
- [SDD 之文档先行](#SDD 之文档先行)
- - 什么是「文档先行」
  - 从调研到方案：先聊清楚，再动手
- 项目准备
- - [版本控制：AI 写代码，你最该先建好的是 git](#版本控制：AI 写代码，你最该先建好的是 git)
  - 出现幻觉了怎么办：三档回退
- 管理AI会话
- 需求分析
- - 三步走：想清楚再做
  - [用 MVP 收敛范围](#用 MVP 收敛范围)
  - 「做什么」和「不做什么」同样重要
- 技术架构设计
- 新需求迭代
- 打扫？
- 全文总结
- 核心知识点复盘
- [常见问题 / 避坑指南](#常见问题 / 避坑指南)

引言：一个浏览器插件要解决什么问题

先交代背景。我们要做的是一个 Chrome 浏览器插件，核心功能一句话就能说清：

浏览英文网页时，一键提取文章核心内容 → 调用 AI 模型翻译 → 把结果以 Markdown 格式呈现 → 一键复制。

目标用户很明确：做大网红、公众号、内容搬运的人，他们经常需要快速读懂英文资料并转成可编辑的 Markdown 文案。所以这个工具的价值点在于「省事」------把「读英文 → 提炼 → 翻译 → 排版」这几步，压成「点一下」。

但真正值得讲的，不是这个插件本身，而是怎么用 AI 辅助、高效且可追溯地把它做出来 。这就是贯穿全文的主线：SDD（Spec-Driven Development，规范驱动开发）------文档先行。

SDD 之文档先行

什么是「文档先行」

传统开发是「想到哪写到哪，代码就是唯一产出」。而 SDD 的思路反过来：先写文档，把「要做什么、怎么做、为什么」想清楚，再让 AI 照文档写代码。

为什么这对 AI 辅助开发尤其重要？因为 AI（比如 Claude Code）的上下文是「一次性」的 ------你关掉窗口、换一个新会话，之前的讨论就没了。如果这些讨论只存在于聊天记录里，那等于什么都没沉淀下来。而文档是可记录、可共享的，它是 AI 协作的「锚点」。

所以第一步，就是写一份需求文档 proposal.md，回答「我们要做什么」。

从调研到方案：先聊清楚，再动手

写需求之前，要先调研和分析 ，尤其是识别出真正的难点。这个项目的难点很明确：「一键提取文章核心内容」。

为什么难？因为网页结构千奇百怪------有的是正文、有的是广告、有的正文藏在嵌套 div 里。如果自己写正则去抠正文，会累死还不准。这个难点的解法不是硬写，而是和 Claude Code 以及相应的 skill 聊一聊：让 AI 去搜资料、给方案，最终得到一个可落地的技术方案。

聊完之后，方案里会沉淀出几个关键技术决策：

AI 模型可配置 ：不写死某一家，而是用 OpenAI 兼容协议，这样 DeepSeek、通义千问（qwen）等都能无缝切换。
Markdown 渲染用 npm marked：一个通用、成熟的 Markdown 解析库，避免自己造轮子。
界面设计 ：一个按钮 + 布局（layout），翻译结果流式输出（像 ChatGPT 那样一个字一个字往外蹦，而不是干等几秒）。

这就是「文档先行」的价值：难点在文档阶段就被识别、被解决，而不是写到一半才发现卡住。

项目准备

版本控制：AI 写代码，你最该先建好的是 git

很多人用 AI 写代码，一上来就开干，结果写完发现改坏了，想回退都找不到「原来的样子」。所以在 AI 动手之前，第一件事是创建项目 + 初始化 git 仓库。

原因很简单：AI 生成的代码是需要「验收」的，而验收的前提是「能回退」。Vibe coding（氛围式/自由发挥式编程）最大的风险是------AI 可能「幻觉」，生成一堆看起来对、其实错的代码。有 git，你才敢让 AI 放手写；没 git，你只能祈祷它每次都写对。

一句话记住：版本控制让 AI 生成的代码「可追溯、可回退」。

出现幻觉了怎么办：三档回退

这是本节的核心重点 。AI 幻觉（改坏了）时，怎么安全地退回？关键在于搞清楚「你的改动现在处于 git 的哪个阶段」。git 里文件有三个区域：工作区 → 暂存区 → 仓库。不同的阶段，回退命令不一样：

第一档：改动还没 git add（只在工作区）

bash 复制代码

# 直接丢弃这次修改，恢复到上一次提交的样子
git restore .

第二档：已经 git add 了，但还没 commit（进了暂存区）

bash 复制代码

# 第一步：把文件从暂存区移出来（撤销 add，但保留工作区的改动）
git restore --staged .

# 第二步：再丢弃工作区的改动
git restore .

为什么要分两步？因为「暂存区」和「工作区」是两层。git restore --staged . 只把「暂存」这个动作撤销掉，文件内容还在；要彻底丢弃内容，还得再来一句 git restore .。

第三档：已经 commit 了（进了仓库）

bash 复制代码

# 把 HEAD 硬回退到上一个提交，工作区和暂存区一起被重置
git reset --hard HEAD^

HEAD^ 表示「上一次提交」。--hard 表示「连文件内容一起回退」，属于「重手」，用之前确认真的不要那些改动了。

易错点 ：很多人分不清这三档，上来就 git reset --hard，结果把没提交的改动也一并清了。正确的做法是先判断改动在哪个阶段，再选对应命令。

管理AI会话

这一节很短，但极其实用：做一件事，就开一个新会话（新上下文）。

为什么？AI 的「上下文」就是它当前记住的所有对话。上下文越长，AI 越容易「串台」------把上一个需求混进当前需求，或者记不住你真正要什么。

一个干净的做法是：每个独立的功能或文档，用一个新的 AI 会话 。比如写 proposal.md 开一个会话，写 task.md 再开一个。这样每个会话的上下文都是聚焦的，AI 的回答也更准。这也呼应了上一节------为什么文档这么重要？因为上下文带不走，但文档能带。

需求分析

三步走：想清楚再做

需求分析不是「大概想想」，而是有章法的三步：

第一步：清晰地定义我们要做什么。 一句话能说清目标，才算定义清楚。
第二步：分析和调研。 用 skill，或者和 Claude Code 多聊几轮，把难点、方案摸清。
第三步：花时间编写并验证需求。 把需求写下来，并且反复确认「这样写对吗」。

用 MVP 收敛范围

需求分析里最关键的一个词是 MVP（Minimum Viable Product，最小可行产品）。

它是什么意思？就是「先做一个最小的、能跑起来验证想法的版本」 ，而不是一上来就想着做完整。很多产品经理和开发者一上头就「许愿式」地列一堆功能，最后哪个都没做好。MVP 让你先跑通核心链路，再逐步加东西。

落到这个插件上，MVP 就是：能提取正文 → 能翻译 → 能以 Markdown 显示 → 能复制。至于「侧边栏」「popup 页面」这些，都是 MVP 之后的新需求（后文会讲）。

「做什么」和「不做什么」同样重要

好的需求文档，必须同时写清两件事：

做什么 ：详细举例说明，尤其要定义好返回格式（比如 AI 翻译完返回的是纯文本还是带格式的 Markdown）。
不做什么：明确划清边界，避免范围蔓延。

还有一个容易被忽略的点：「不是新的项目，我们得阅读」 。意思是------如果是基于已有代码开发，第一步是先把现有代码读懂，而不是上来就改。这在需求阶段就要意识到。

最后强调一遍文档的意义：文档可记录、可共享，vibe coding 一关窗口可能就没了 。而且写文档不能走过场，它是程序开发的必备流程，是「关键流程」而不是「形式主义」。

技术架构设计

选型决定成败

需求想清楚了，接下来是技术架构设计。这一节直接关系项目成败，尤其是技术选型。

一个正确的选型，能让后续开发事半功倍；反之，选错了方向，就会陷入泥潭。

那么选型靠什么？靠架构师的认知 + skill 。这里有个很现实的认知升级路径：技术难点（比如「网页主要内容怎么提取」），上网搜 + 借助 LLM 的分析能力，就能快速补齐 。换句话说，AI 时代，「架构师」的门槛被大大降低了------你不再需要记住所有技术细节，但你要会用 AI 去调研、对比、拍板。

两个关键选型决策

这个项目有两个选型尤其关键，值得单独讲：

1. 强调 OpenAI 兼容方式，方便切换 qwen 等模型

不要把自己的代码绑死在某一家的 SDK 上。正确做法是用统一的 OpenAI 兼容接口：

js 复制代码

// 统一的模型客户端，通过 baseURL 切换不同厂商
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: '你的-key',        // 换成不同厂商的 key
  baseURL: 'https://api.deepseek.com', // 换成 qwen 等厂商的地址即可
})

const result = await client.chat.completions.create({
  model: 'deepseek-chat', // 模型名也做成可配置
  messages: [{ role: 'user', content: '请翻译这段英文...' }],
  stream: true, // 流式输出，边生成边显示
})

这样，想从 DeepSeek 切到通义千问，只改 baseURL 和 apiKey，业务代码一行不动。这就是「可配置」带来的灵活性。

2. 格式用「微信 Markdown」

目标用户要发公众号，而公众号有自己的排版规范。所以翻译结果不能是「随便的 Markdown」，而是适配微信生态的 Markdown 格式 。渲染端用 npm marked 来做通用解析，再按微信的规则做适配。

架构设计的产出：四份文档

架构设计不是嘴上说说，要沉淀成文档。这个项目最终产出四份：

需求文档（proposal.md）
技术架构文档
页面布局（描述界面长什么样、按钮和流式输出怎么排）
任务拆解文档（task.md，把大需求拆成一个个可执行的小任务）

有了这四份，AI 才能「照单抓药」，一步一步把代码写出来。

新需求迭代

MVP 跑通后，需求会继续长出来。比如这个插件后来的新需求是：加一个「侧边栏」、考虑「popup 页面」怎么做。

迭代期的核心原则只有一条：修改更新到文档中，保持文档和代码生成的一致性。

什么意思？就是每次需求变了，先改文档，再让 AI 按新文档改代码 。这样文档和代码永远是「对得上」的。而且------git 可以同时跟踪软件代码版本和文档版本，代码和文档一起提交、一起回退，谁也甩不开谁。

打扫？

最后一件小事，但很重要：记得移除冗余代码。

AI 迭代多了，很容易留下「死代码」------旧方案没删干净、测试用的临时代码、注释掉的废代码。这些冗余会让项目越来越难读。所以每完成一轮迭代，顺手打扫一遍：删掉没用到的变量、函数、文件。

全文总结

这篇文章表面在讲一个浏览器插件，实际讲的是一套用 AI 高效、可追溯地做开发的方法论：

SDD 文档先行：先把需求、难点、方案写成文档，再让 AI 照文档写代码。
版本控制先行：AI 动手前先建 git，让幻觉可回退、可追溯。
管理 AI 会话：一个任务一个新上下文，保持聚焦。
需求分析三步 + MVP：想清楚「做什么、不做什么、返回格式」，先跑通最小版本。
技术架构设计：选型决定成败，用 OpenAI 兼容协议做可配置、用成熟库（marked）避免造轮子。
迭代与打扫：需求变化先改文档，代码和文档用 git 一起管理，顺手清冗余。

核心知识点复盘

概念	一句话解释	关键点
SDD	规范驱动开发，文档先行	文档是 AI 协作的锚点
proposal.md	需求文档	回答「做什么」
vibe coding	AI 自由发挥式编程	有幻觉风险，必须配 git
工作区/暂存区/仓库	git 的三层	回退前先判断改动在哪一层
git restore .	丢弃工作区改动	未 add 时用
git restore --staged .	撤销暂存	add 后、commit 前用
git reset --hard HEAD^	回退到上次提交	已 commit 时用
MVP	最小可行产品	先跑通核心链路
OpenAI 兼容	统一协议，换 baseURL 换厂商	模型可配置的关键
流式输出	边生成边显示	用 `stream: true`
task.md	任务拆解文档	把大需求拆小

一句话串起整个流程：

文档先行（proposal.md）→ git 建仓兜底 → 需求分析定 MVP → 架构设计定选型 → 拆成 task.md → AI 照单写代码 → 新需求改文档再改代码 → 打扫冗余。

常见问题 / 避坑指南

1. AI 改坏了代码，我直接 git reset --hard 对吗？

先别急。先判断改动在哪个阶段：

没 add：git restore .
add 了没 commit：git restore --staged . + git restore .
已经 commit：git reset --hard HEAD^

直接用 --hard 会把没提交的改动一起清掉，属于「重手」，用前务必确认。

2. 为什么一定要「文档先行」，不能直接让 AI 写代码？

因为 AI 的上下文是一次性的，关掉窗口就没了。如果不写文档，讨论的过程、定的方案、划的边界，全部丢失。文档让 AI 的产出「有据可依、可复盘、可共享」。

3. 为什么模型要「可配置」，直接写死一家不行吗？

写死一家，意味着将来换模型要改大量代码。用 OpenAI 兼容协议，切换厂商只改 baseURL + apiKey，业务代码零改动。这既是灵活性，也是「选型决定成败」的典型例子。

4. 提取「网页核心内容」为什么难，怎么解决？

网页结构千变万化，硬写规则抠正文会又累又不准。正确做法是先在需求阶段把这个难点暴露出来，借助 LLM 的分析能力调研现成方案（比如可读性算法、正文提取库、或直接让 AI 提取），而不是自己从零写。

5. 怎么理解 git 的「工作区 / 暂存区 / 仓库」三层？

工作区 ：你正在改的文件（没 add）。
暂存区 ：你 git add 了、准备提交的文件。
仓库：已经 git commit 的、有版本号的文件。

回退命令之所以分三档，就是因为它要「从哪一层退回去」。

6. 需求文档里最容易漏写什么？

最容易漏的是 「返回格式」和「不做什么」。返回格式不定清楚，AI 翻译完返回一堆无法解析的东西；「不做什么」不定清楚，需求就会像滚雪球一样无限扩张。