第一次用 Atoms.dev 开发 Chrome 插件：从一句话到离线二维码工具

从一句话到离线插件

你第一次打开 Atoms.dev，最容易犯的错，不是不会写提示词，而是太快开始写提示词。

“帮我做一个二维码插件。”这句话看起来目标明确，实际上把运行环境、隐私边界、交付形式和验收标准都留给了 AI 猜。它可能给你一个网页，也可能引用 CDN，还可能为了“方便”申请并不需要的浏览器权限。

我是老李。今天不讲一堆抽象概念，我们直接做一个能在 Chrome 里加载的离线插件：输入文字生成二维码，选择图片识别二维码，断网也能使用。走完一次，你会同时摸清 Atoms.dev 的产品思路、Chrome 扩展的基本结构，以及 AI 项目怎样从“看起来能跑”走到“真的可验收”。

01、第一次用 Atoms，先别急着让它开工

先把产品说清楚

Atoms.dev 的官方流程很像一支在线产品团队：你先描述受众、功能和主要流程，它生成产品蓝图，再由多个 Agent 完成界面与代码，你可以预览、选中界面继续修改，最后导出工程。这个流程的优势是快，但输入越含糊，后面的返工越快。

所以，第一步不是写“做什么页面”，而是写清五个问题：

1. 它是谁用的？
2. 它在哪运行？
3. 哪些功能必须有？
4. 哪些事情绝对不能做？
5. 怎样证明它完成了？

这个案例的答案很简单：给开发者和普通用户使用；运行在 Chrome 扩展弹窗；支持生成与识别二维码；不上传图片、不访问网络、不申请权限；用“生成—识别—断网复测”证明可用。

注意最后两项。对 AI 编程来说，“不要做什么”和“如何验收”，往往比多写十条视觉描述更值钱。

02、把 Atoms.dev 理解成产品闭环，而不是代码补全

Atoms.dev 的工作方式

根据 Atoms.dev 的应用与网站构建说明，典型路径是“描述产品—查看计划—Agent 构建—预览迭代—发布”。它的帮助中心还提供完整代码与资源的 ZIP 导出，因此你不必把项目永远锁在在线编辑器里。

这和传统代码补全有一个明显区别：代码补全围绕“当前文件”工作，Atoms.dev 更强调“产品目标”。它会先整理页面、数据和任务，再组织 Agent 去实现。

但也要看清边界。Atoms.dev 的公开资料重点是 Web 与全栈应用，没有承诺一键发布 Chrome 插件。可靠做法是：让它生成符合 Manifest V3 的完整工程，导出代码，在本地构建，再去 chrome://extensions 加载。

这不是绕路，而是正确的责任分工：

03、为什么第一个案例要选离线二维码插件

为什么选离线二维码插件

好的入门案例应该“小而完整”。如果一开始就做登录、数据库、支付和后台，你很难分辨问题到底出在 Atoms、业务设计还是环境配置。

二维码插件只有两个核心能力：

• 生成：文字或网址进入本地编码器，输出二维码画布；
• 识别：图片进入本地解码器，输出其中的文本。

它又天然适合练工程边界。二维码图片可能包含地址、设备编号甚至内部信息，最稳妥的方案就是不上传。我们把 qrcode 和 jsQR 打进扩展包，不用 CDN，不调用后端，并且让 manifest.json 不声明 permissions 与 host_permissions。

这个案例还能让你一次认识 Chrome 扩展最小骨架：manifest.json 描述扩展，popup.html 提供弹窗，JavaScript 实现交互，构建工具把第三方依赖打进本地产物。功能不大，却覆盖需求、界面、依赖、隐私、构建和测试。

04、先看架构：数据必须留在浏览器里

离线二维码插件架构

Chrome 官方把 Manifest V3 定义为当前扩展平台，并明确禁止扩展执行远程托管代码。对本案例来说，最干净的架构就是：

用户输入 ──> qrcode ──> Canvas ──> 下载 PNG
本地图片 ──> jsQR ──> 识别文本 ──> 复制结果

整个链路没有服务器。qrcode 与 jsQR 在构建阶段被打进 popup.js；运行时即使网络断开，生成和识别也不受影响。

最小清单如下：

{
  "manifest_version": 3,
  "name": "离线二维码助手",
  "version": "1.0.0",
  "action": {
    "default_popup": "popup.html"
  }
}

请留意这里没有权限字段。Chrome 官方的安全建议和隐私指南都强调最小权限。能用普通文件选择器解决，就不要申请读取历史、标签页或网站内容。

05、完整实战：在 Atoms 中把约束写进第一条消息

二维码离线插件实战总览

进入 Atoms.dev 后，不要只说“做一个二维码工具”，直接粘贴下面这段：

请先输出产品蓝图，等我确认后再实现。开发一个 Chrome 离线扩展，使用 Manifest V3。弹窗宽约 430px，包含“生成二维码”和“识别二维码”两个页签。生成页可输入文字或网址、选择尺寸和容错级别、下载 PNG；识别页可选择或拖入 PNG/JPG/WebP 图片，展示识别结果并复制。所有处理必须在浏览器本地完成：不上传数据、不访问后端、不使用 CDN、不加载远程脚本；第三方运行时依赖必须打包进扩展；不要申请 permissions 或 host_permissions。请提供中文界面、构建命令、README 和可执行的验收测试。

蓝图出现后，先核对四件事：交付物是不是“扩展工程”而非普通网站；有没有生成与识别两条流程；有没有写明离线与零权限；有没有构建和验收任务。缺一项，就在蓝图阶段纠正，别等代码全部生成再返工。

如果它仍然给出普通网页，不要推倒重来，只补一条纠偏消息：“保留现有界面，但把交付形式改为可加载的 Chrome Manifest V3 扩展；入口是 action popup；删除服务端、登录、数据库和远程资源；输出 manifest、源码目录、构建目录与加载步骤。”这种局部纠偏比重新写一篇长提示更稳定，也更容易看出 Agent 到底改了什么。

界面预览通过后，再检查工程文件，而不是只看页面好不好看。manifest.json 决定 Chrome 能不能识别它；package-lock.json 决定别人能不能复现依赖；构建脚本决定源码能不能变成可加载产物；测试决定下一次修改会不会把主流程弄坏。对开发者来说，这四类文件比一张漂亮预览图更重要。

生成完成后，通过右上角 Share → Export 下载完整代码。官方帮助中心也说明了这一导出方式。如果你已有本地项目，还可以参考导入本地项目的方式上传压缩包继续迭代。

本案例的可运行代码放在案例代码/二维码离线助手。进入目录执行：

npm install
npx playwright install chromium
npm test

npm test 会先打包，再检查 Manifest V3、零权限和零远程地址，最后用 Chromium 加载扩展完成真实交互。

在 Chrome 手动体验时，打开 chrome://extensions，开启“开发者模式”，点击“加载已解压的扩展程序”，选择构建后的 dist/。这与 Chrome 官方的第一个扩展教程一致。

第一张图是文字生成二维码。它证明核心编码能力已在本地运行：

离线生成二维码

第二张图把刚生成的二维码作为图片重新上传，插件成功读回原文。它不是两个孤立按钮，而是一条完整闭环：

本地识别二维码

第三张图是在浏览器被设置为离线后再次生成。页面没有后端兜底，也没有 CDN 缓存侥幸通过：

Chrome 断网验收

这三张截图分别回答“能生成吗”“能识别吗”“断网还行吗”。到这里，案例才算从演示进入工程。

06、三个最佳实践，决定项目能不能继续开发

先写验收再写提示词

第一，提示词要写结果，不只写功能。“支持识别二维码”仍然偏抽象；“生成一张二维码，把它上传后能识别回原文”才是可测试的结果。先写验收，会倒逼 Agent 补齐图片输入、状态提示和错误处理。

把边界写成硬约束

第二，把安全边界写成可以检查的工程条件。“注意隐私”无法自动验收，“permissions 为空、没有 host_permissions、产物不包含远程脚本、断网测试通过”可以。AI 很擅长实现明确约束，不擅长替你定义风险偏好。

用闭环证明可用

第三，永远保留可重复的证据。截图适合给人看，测试断言适合防回归。案例里的 Playwright 测试会加载真实扩展、输入网址、生成二维码、上传图片、比对识别结果，再切换离线状态复测。以后让 Atoms 修改样式或增加功能，重新执行一次就知道有没有破坏主链路。

另外，导出后立刻把代码纳入 Git。每次只改一类问题：先功能，再样式，最后优化。Atoms.dev 支持继续对话和界面选择修改，但小步提交仍然是你找回稳定版本的安全绳。

07、照着这张清单，今天就能完成第一次交付

今天就按清单开工

第一次实践不用追求功能多，按下面顺序做：

• 在 Atoms.dev 写清用户、运行环境、两个核心功能和四条禁止项；
• 审核蓝图，确认交付的是 Manifest V3 扩展工程；
• 让 Agent 生成源码、README、构建脚本和自动化测试；
• 导出 ZIP，本地执行 npm install 与 npm test；
• 在 Chrome 的扩展管理页加载 dist/；
• 查看权限是否为零，手动走一遍生成和识别；
• 断开网络，再走一遍主流程；
• 提交 Git，再开始下一轮功能扩展。

想继续练习，可以按难度逐步增加：先做最近生成记录，但仍只用页面内存；再做自定义颜色与 Logo；最后才考虑需要权限的能力。每增加一个权限，都要写明用户收益、数据范围和失败兜底。

08、真正的快速上手，是先完成一个小闭环

Atoms.dev 能把产品设计、界面和代码实现压缩到同一个对话里，但它不会替你承担产品边界和验收责任。

最有效的入门方式，不是把所有功能一次说完，而是选择一个边界清楚的项目：先要求蓝图，再要求工程；先规定不能联网，再检查产物；先看到界面，再用测试证明它能工作。

当你能稳定交付这个离线二维码插件，再去做书签管理、网页摘录或开发者工具，框架不会变：描述目标、确认计划、导出代码、真实运行、证据验收。

一句话总结：AI 负责加速实现，你负责定义“完成”。

09、官方入口与关键概念

• Atoms.dev：应用与网站构建：了解从产品描述、计划到 Agent 构建与预览迭代的主流程。
• Atoms.dev：分享与导出：下载完整代码和资源 ZIP。
• Atoms.dev：导入本地项目：把已有工程带回 Atoms 继续开发。
• Chrome：Hello World 扩展：认识 Manifest、弹窗和“加载已解压扩展程序”。
• Chrome：Manifest V3：理解当前扩展平台与远程代码限制。
• Chrome：扩展安全建议：最小权限、内容安全策略与安全编码。

概念上，Manifest V3 是 Chrome 扩展清单与运行模型；popup 是点击工具栏图标后出现的小页面；bundle 是把源码与第三方依赖打进本地文件；零权限 是本案例不申请 permissions 与 host_permissions；断网验收 是让浏览器进入离线状态后重跑主流程。

从会用 Atoms 到能交付插件