用 SDD 规划 AI 浏览器插件：从网页提取、翻译到 Markdown 输出

想开发一个浏览器插件：阅读英文网页时，一键提取文章核心内容，调用 AI 翻译，再以 Markdown 展示并复制。这个想法看起来清晰，但如果立即让 AI 写代码，正文提取、模型接入、输出格式、浏览器权限和安全边界都会被迫由 AI 临场猜测。

本文根据一份项目规划笔记，梳理如何用 SDD 先定义 MVP、非目标、技术难点和 Git 回退策略，再进入编码。当前目录没有项目源码和运行结果，文中的实现方向运行未验证。

先把产品想法画成数据流

项目的核心链路可以先压缩成：

英文网页
→ 提取文章核心内容
→ 调用所选 AI 模型翻译
→ 以 Markdown 格式呈现
→ 一键复制

这条数据流比“开发一个翻译插件”更有价值，因为它暴露了四个需要独立设计的模块：

1. 网页正文提取；
2. AI 模型调用；
3. Markdown 处理和展示；
4. 浏览器界面与复制交互。

如果其中任一步没有定义，Agent 就只能自行选择方案。

为什么不能立即让 AI 写插件代码

一句需求通常没有回答下面的问题：

• 插件只处理文章页，还是处理所有网页？
• “核心内容”是否包含标题、图片、代码块和链接？
• 使用哪个模型，密钥如何配置？
• 是否需要在 DeepSeek、Qwen 等模型之间切换？
• 翻译结果是标准 Markdown，还是针对微信公众号做格式适配？
• 大段文本如何处理，是否采用流式输出？
• 哪些功能明确不进入第一版？

AI 可以生成一套看似完整的答案，但这些答案是隐藏假设，不是已经确认的需求。后续一旦改变关键假设，就可能同时影响数据结构、接口和界面。

第一步：在 proposal 中定义 MVP

规划笔记强调先回答“做什么”，再调研和验证需求，并明确返回格式与“不做什么”。

先写用户和场景

例如：

目标用户：需要阅读英文技术文章并整理中文 Markdown 的用户。
核心场景：用户在当前文章页点击插件按钮，获得可复制的中文 Markdown。

这只是需求表达示例，不代表最终产品已经确认。

再写最小闭环

根据现有材料，MVP 可以优先验证：

• 读取当前网页；
• 提取正文；
• 调用一个可用模型完成翻译；
• 显示 Markdown；
• 一键复制结果。

“模型自由切换”“微信公众号深度适配”“复杂流式界面”是否进入第一版，应由需求文档确认，而不是默认全部实现。

必须写非目标

非目标用于限制需求蔓延。例如首版可以考虑明确：

• 暂不支持整站批量翻译；
• 暂不提供在线内容管理后台；
• 暂不自动发布到微信公众号；
• 暂不承诺所有网页都能准确提取正文。

这些内容是规划方法示例，最终范围需要项目负责人确认。

第二步：调研三个关键技术问题

网页核心内容如何提取

网页通常包含导航、广告、推荐、评论等噪声。如果上游提取错误，后续 AI 翻译再准确也无法得到理想结果。

调研时至少要定义：

• 输入和输出的数据结构；
• 标题、段落、列表、代码块、图片和链接如何保留；
• 动态页面何时读取；
• 提取失败时怎样提示；
• 用哪些类型的网页作为验收样本。

如何建立模型兼容层

材料提出通过 OpenAI 兼容方式切换 Qwen 等模型。这一方向可以降低业务流程与供应商的耦合，但“兼容”不代表所有服务完全一致。

设计阶段仍需确认：

• 鉴权与配置方式；
• 请求和响应字段；
• 流式事件格式；
• 模型名称和能力差异；
• 超时、限流和错误处理；
• 密钥是否会暴露在浏览器端。

当前材料没有接口和安全设计，因此不能直接推断实现。

Markdown 如何适配目标场景

笔记提到 npm 包 marked，也提到微信公众号场景。marked 可能用于 Markdown 解析或渲染，但当前没有源码证明它的最终职责。

这里需要先区分：

AI 输出 Markdown 文本
≠ 浏览器预览 Markdown
≠ 复制到微信公众号后保持格式

三者可能需要不同处理，必须在 design.md 中明确输入、转换和输出边界。

第三步：把架构决策写进 design

一个最小设计至少应说明：

模块	职责	需要确认的问题
Content Script	读取当前页面内容	权限、加载时机、动态页面
正文提取层	去除噪声并保留文章结构	提取规则、失败策略
模型适配层	调用配置的 AI 模型	鉴权、兼容性、流式协议
Markdown 层	处理展示与复制格式	marked 的职责、目标格式
插件界面	发起操作并展示状态	布局、进度、错误提示

表中的模块是根据产品数据流进行的合理拆分，并非已经验证的项目实现。

第四步：用 task 拆成可验收任务

任务不应写成“完成整个插件”，而应拆成可以独立检查的结果：

1. 确认插件目标浏览器与扩展规范
2. 建立最小插件结构并显示操作界面
3. 读取当前页并返回原始内容
4. 实现正文提取并用样本页验收
5. 接入一个模型完成非流式翻译
6. 展示 Markdown 并支持复制
7. 抽象模型配置和切换能力
8. 验证异常流程与安全边界

实际任务顺序取决于最终设计，当前材料尚未提供正式 task.md。

Git 如何为 AI 编程提供回退点

规划笔记建议创建 Git 仓库，让 AI 生成结果可追溯、可回退。关键是根据文件状态选择操作，而不是遇到问题就执行破坏性命令。

当前状态	先查看	可考虑的操作	主要风险
修改未暂存	git diff	git restore <file>	丢弃指定文件修改
已暂存未提交	git diff --staged	git restore --staged <file>	只移出暂存区，不自动恢复内容
已提交且未共享	git log	按目标选择 reset 或新提交	可能改写本地历史
已提交且已共享	git log	通常优先 git revert	会新增反向提交

材料中出现的命令：

git restore .
git reset --hard

二者都可能丢失修改。执行前至少检查 git status、git diff 和提交历史，并优先指定具体文件。不要把“可回退”误解为“任何时候都能无损撤销”。

AI 会话为什么也要管理

聊天窗口中的讨论容易随着会话结束而丢失。把需求、决策、任务和验收条件写入文档并提交 Git，可以让后续会话读取相同上下文。

推荐链路是：

会话中调研与讨论
→ 把结论写入规范文档
→ 人工评审并提交 Git
→ 新会话按文档继续
→ 发现问题后更新文档和代码

会话负责探索，文档负责保存结论。

浏览器插件开工自检清单

• 目标用户和核心场景已经明确；
• MVP 与非目标已经写清；
• 网页正文提取的输入、输出和验收样本已定义；
• 模型接口、鉴权、流式协议和异常处理已确认；
• 浏览器端密钥与隐私风险已评估；
• Markdown 展示、复制和公众号适配已区分；
• 模块职责和数据流已经写入设计；
• 任务足够小，并具有验收结果；
• 已创建 Git 仓库和安全回退流程；
• Agent 当前允许修改的范围已经明确。

总结

这个插件的难点不只是“让 AI 翻译网页”，而是保证网页提取、模型调用、Markdown 处理和浏览器交互形成稳定闭环。

SDD 的价值，是在生成代码前先暴露这些决策：用 proposal.md 明确用户、MVP 和非目标，用 design.md 固化技术方案，用 task.md 拆出可验收步骤，再使用 Git 和文档管理 AI 生成过程。

下一步不是立即生成整个插件，而是先补齐正文提取、模型兼容、密钥安全和 Markdown 目标格式的验收标准。

说明：当前目录只有规划笔记，没有源码、完整规范或运行记录，本文中的技术拆分与示例运行未验证。