这里记录每周值得分享的科技内容，周五发布。

本杂志开源，欢迎投稿。另有《谁在招人》服务，发布程序员招聘信息。合作请邮件联系（yifeng.ruan@gmail.com）。

封面图

湖南益阳的和平签证主题博物馆，纪念二战时期何凤山博士救助犹太人。外立面的层层钢板象征签证文件，狭窄而棱角分明的入口给人一种压抑的感觉，进入后的空间逐渐走向释放和光明。（via）

脑腐状态

最近学到一个新词"脑腐"（brain rot）。

它就是字面意思。有些人看上去是正常的，但是大脑已经变异了，有些部分腐烂了。

根据介绍文章，"脑腐"的症状就是思考能力下降，难以长时间集中注意力，进行深入的推理和反思。

一遇到比较难、需要反复思考的问题，你就会烦躁，不仅是心理烦躁，还会生理烦躁，全身不安，不愿意多想，就希望赶快了结。

你有没有这个症状？如果有，就有"脑腐"的危险了。我感觉，我的大脑就有一点。遇到复杂的软件概念和算法，以前会仔细研究，直到搞懂为止，现在更可能看一眼就跳过去，不懂就不懂了，知道名字就可以了。

"脑腐"的主要原因是，网络平台上面那些夸张的"标题党"文章和短视频。它们的目标是吸引流量，在最短时间内引发阅读者/观看者的兴趣，感到满足。当你长期观看这些内容以后，大脑就被密集刺激，思维兴奋状态的维持时间越来越短，丧失了长时间深入思考的能力。

这就是为什么一个人看惯短视频以后，就离不开内容压缩了。一篇几千字的文章，他也会要求大模型生成总结；一部90分钟的电影，他也宁愿看几分钟的电影解说。

一旦"脑腐"了，难以长时间集中注意力进行思考，也就难以学习和处理高难度问题了。现在看上去，没有好的解决办法，因为现代人的时间越来越琐碎，内容碎片化是大趋势。

应对之策也许就是反过来，将学习和思考拆解成一系列短问题。比如，以后的学习不再是一厚本教材，而是几十个的系列短视频，每个用两三分钟解释一个知识点。只有这个时间长度，学生的思维才能保持专注。

权重有没有版权？

国产大模型一般是开源的，但是最近有所改变。

有的大模型闭源发布；有的只开源小参数版本，不开源大参数版本；有的不允许商用，除非得到许可。我就不点名了。

"黑客新闻"的一个读者，针对开源大模型修改许可证这件事，提出质疑：开源大模型可能无权设置许可证。

他的意思是，现在的开源大模型主要开源的是权重文件，以及配套的运行代码。所谓"权重文件"就是一个巨大的矩阵，表示各个 Token 在生成结果中出现的可能性。

权重是大模型的核心，而它来自于对海量语料的计算。这就是说，权重不过是计算结果，他认为，计算结果是没有版权的。

比如说，你写了一个程序，实现了一种更高效的根号2的算法。那么，这个程序是有版权的，但是计算结果根号2（1.414）是没有版权的。因为计算结果不过是机械过程的产物，不涉及人类创造力。

按照这种说法，权重根本没有版权，当然也就谈不上设置或修改许可证了。

我不是版权专家，不能确定这种说法对不对，但是听上去有道理。大家可以自己去问问大模型"计算结果有没有版权？"，看看大模型怎么回答。

科技动态

1、摄像头耳机

华盛顿大学的研究团队，开发出世界首个带有微型摄像头的无线耳机。

上图中，耳机底部的小凸起就是微型摄像头。

它的最大用途就是跟 AI 互动。你可以直接问："我手里的英文杂志的封面标题是什么意思"，耳机就会把摄像头图像，通过蓝牙发到手机，手机的大模型就会回答。

由于带宽限制，它只能拍摄低分辨率的黑白图像。长远来看，如果不需要显示模块，这种摄像头耳机要比 AI 眼镜更适合穿戴使用，因为很多人不喜欢长时间戴眼镜。

2、排行榜的 AI 歌手

最近，有人向苹果音乐商店 iTunes 上传了艾迪·道尔顿（Eddie Dalton）的歌曲。

这个歌手实际上并不存在，形象、声音、视频都是 AI 生成的，但是上传者没有披露。

结果，这些 AI 歌曲大受欢迎。iTunes 单曲榜前100名中，他居然占据了11席，有两首歌进入了前10名。

他的专辑在 iTunes 上也排名第三。

以前，有人说 AI 和机器人承担日常工作以后，人类可以从事艺术创作，比如唱歌、跳舞、画画、写作、拍视频......现在看上去，AI 也会跟人类争夺艺术工作。

3、经济舱座椅

长途飞行的经济舱座椅，非常不舒服，美联航想出了一种改进办法。

如果是一家三口，可以将座椅的坐垫卸下，从而一家躺在地上睡觉。

航空公司会提供枕头和毛毯，甚至还有床垫。

如果是单人旅客，你就需要同时购买三个相邻座位，好在这样还是比头等舱便宜。

我觉得，中国高铁可以考虑这种做法，某些没有卧铺的长途线路允许拆卸几排座位，让乘客躺在地上休息。

文章

1、Claude Code 的源码真相（英文）

前不久，Claude Code 源码泄漏，人们仔细研究以后，发现这些源码全部是 AI 生成的，质量不高。一个函数就长达3,167行，包含486个判断分支和12层嵌套，入口文件 main.tsx 大小为 785 KB。

作者得出结论，AI 编程流行后，代码泄露、供应链攻击、乱七八糟的生产代码，会成为新常态。

2、Chrome 浏览器原生支持技能（英文）

Chrome 官方宣布，支持在 Gemini 插件里面使用技能（skill），也就是一段预置的提示词，用来一键完成任务。这应该是浏览器以后的发展方向。

3、安卓会剥离照片的位置信息（英文）

本文指出一个容易忽视的点，那就是网页上传照片，安卓会自动剥离照片的位置信息。蓝牙或 QuickShare 分享照片也不行，除非你自己开发照片应用，或者用 USB 传输照片。

4、我的每月20美元技术栈（英文）

作者的网站每月产生1万美元收入，而运营成本仅为20美元，作者介绍他采用的技术栈。

5、你真的需要数据库吗？（英文）

本文提出，如果数据量不大，小型网站完全可以不用数据库，直接把数据保存在文件里面，无论是直接读文件、或者从内存查询，再或者二分法查询，速度都不慢。

6、自制软饮料（英文）

作者记录在家里自制可乐的过程，原来包含那么多化学品。

1、关于索引，你不知道的事（英文）

一篇数据库科普文章，通过实例介绍索引（index）的基本用法。

工具

1、DAVINCI RESOLVE 21

著名视频编辑软件"达芬奇"的新版本，加入了图像编辑，可以当作照片编辑软件了。

2、Phyphox

一个著名的老牌手机应用（支持 iPhone 和安卓），提供各种手机传感器的应用界面，由德国亚琛工业大学开发。

3、Material You NewTab

一个 Chrome 插件，用来定制新标签的主页。

4、ClipCascade

一个同步剪贴板的工具，可以将一台电脑的剪贴板自动同步到另一台电脑，不过需要安装它的服务端和客户端（支持 Windows、Linux、安卓）。

5、Gridea Pro

桌面静态博客写作客户端，不用设置服务器，零门槛建立自己的静态博客网站。（@Hao4Wang 投稿）

6、Recordly

开源的录屏与编辑工具，适用于制作演示、产品展示、教程、讲解视频等，可以录制整个屏幕或单个窗口，并直接进入编辑器。（@Hao4Wang 投稿）

7、水印

为图像和视频添加水印的网站，支持自定义模板。（@FurryR 投稿）

8、Input 0

免费开源的 macOS 语音输入工具，本地运行，支持大模型识别语音文本，并进行文本润色。（@Justin3go 投稿）

9、OpenToggl

开源的时间追踪工具，商业软件 Toggl 的替代品。（@CorrectRoadH 投稿）

AI 相关

1、OmniVoice Studio

视频配音的 AI 桌面应用，支持语音翻译和克隆，无需 API 密钥和云端服务，完全本地生成。（@Hao4Wang 投稿）

2、EVA

一个极简的 AI 编程智能体，仅需单个 Python 脚本，定位为低配版 Claude Code，可以参考它的实现。（@usepr 投稿）

3、claude-msync

一个命令行工具，导出 claude code 的记忆（memory），然后输入 Claude 客户端或其他 AI Agent。（@debugtheworldbot 投稿）

4、TokenTracker

生成本地的 Token 消耗统计报表，支持多种 Agent（Claude Code、Codex、Cursor、Gemini、Kiro、OpenCode、OpenClaw 和 Every Code）。（@mm7894215 投稿）

资源

1、中国卷烟博物馆

一个个人网站，收集各种国产品牌的卷烟。

2、2026世界新闻摄影大赛获奖作品

这个页面列出了世界新闻摄影奖今年一共70幅获奖作品，记录了去年的许多新闻事件。

上图是在四川绵阳的大熊猫公园王朗保护区，使用红外线感应相机拍摄到的野外大熊猫。

3、guide.world

这个网站收集世界各地的优秀游记散文，不过文章还不多。

图片

1、月球上的激光反射器

1971年，美国阿波罗14号飞船登陆月球后，宇航员将一个手提箱大小的白色设备，放在月球表面。

这是一个激光反射器，有点像镜子，可以将射来的激光反射回去。

它用来测量地球与月球的精确距离。地球向月球发射激光，被这面镜子反射回来，地球接收到反射的信号，通过时间差就能知道精确距离。

目前的测量精度已经达到了毫米级。科学家发现，月球正以每年3.8厘米的速度远离地球。

文摘

1、合同软件开发的糟糕现状

有些程序员是基于项目的合同工，不是正式的雇员。

这些程序员选择合同工，而不是稳定的全职工作，是因为想要灵活性和短期经济利益。灵活性指的是，工作时间可以自己安排，而且你可以同时签订多份合同。

可惜的是，现实情况是，公司雇佣了大量合同工，他们没有福利，解雇起来也容易得多，而且工资比全职员工低。

我知道这些，因为我干过好几次合同工。

除了薪酬和福利不如全职员工，你还根本没有带薪休假。如果生病了或者需要休息一天，就根本拿不到这一天的工资。

合同工还有一个问题，被告知的工作和最终实际分配的工作，往往存在重大差异。

我曾经面试了一个 Java 的后端职位，但实际情况是，我几乎没有编写或维护任何 Java 代码，而是被要求去写 React 代码，修复从另一个团队继承下来的有问题的 Jest 测试，以及极其缓慢的 Webpack 配置。

两个月后，我被解雇，理由是毫无根据的"绩效原因"。我知道这只是借口，我遇到了太多自己根本无法控制的问题。

我的另一次合同工经历，也是如此。我在团队里轮班待命，周六早上要值班却没有工资；我提交的工时表被断然拒绝，老板打电话问我为什么要加班。

后来我发现，我的雇主不愿意支付我加班费，再后来我被解除了合同，他们在电话里告诉我不胜任这项工作。

总之，现在的软件合同工有各种弊端，却得不到任何好处。如果有人能从合同工变成全职员工，那当然很好，但在我工作过的每家公司里，合同工都是二等公民。

言论

1、

哈佛大学2024-2025学年，成绩为 A 的作业比例约为60%，远远高于2005-2006学年的约25%，可见成绩膨胀有多严重。

-- 《华尔街日报》

2、

Claude Mythos 模型可以发现并利用系统漏洞，外部评测证实了这一点。但是，评测者也发现了一个残酷的事实：你花费的 Token 费用越多，它发现的漏洞就越多，系统也就越安全。

这意味着，你想要系统安全，就必须比攻击者花费更多的 Token。因此，安全行业变得像采矿的工作量证明，谁的投入多，谁就赢。

-- Simon Willison，著名开发者

3、

一年前，我经常收到代码质量低劣、甚至完全不知所云的 pull request，这让我怀疑提交者是不是用了 AI，所以代码才这么糟糕。

今年不同了，当我收到拼写错误、语法错误的低质量 pull request 时，我反而会怀疑贡献者是不是忘了使用 AI 来写代码，因为 AI 会显著提高代码质量的下限。

-- 《ClickHouse 的 AI 编程实践》

4、

当代战争进行时，政府通过表情包和玩偶动画进行宣传，这或许让人觉得匪夷所思，但这正是平台时代的体现。

将战争包装成娱乐性的视觉语言，会使得宣传更容易传播。社交媒体是一个开放的竞技场，最具吸引力的内容将获得最大的传播范围。

-- 《当病毒式传播成为信息》

5、

大模型意味着，Markdown 现在是一种可执行文件格式。你下载一个 Markdown 文件，你的大模型就多了一个新的第三方依赖项，它的任何修改都可能是注入攻击。

-- 《第三方依赖的冷却时间》

往年回顾

未来就是永恒感的丧失（#346）

xz 后门的作者 Jia Tan 是谁？（#296）

永不丢失的网络身份（#246）

掌机的未来（#196）

（完）

写在前面

掘金的同学们大家好呀，作者是 Varlet UI 的作者。掘金文章已经一年没更新了，去年跳槽到了一家创业公司负责前端架构工作，写文章这件事就一直搁置了。最近稍微缓过来了一点点（其实还是压力很大...），但不妨碍今天来给大家分享一下我们最新的开源项目 rattail。

先聊聊 Vite Plus

上个月 VoidZero 正式以 MIT 协议开源了 Vite+，它把 Vite、Vitest、Oxlint、Oxfmt、Rolldown、tsdown 统一收拢到了一个 vp 命令下面，一套工具链覆盖 dev、build、test、lint、fmt、pack 等所有工程化环节。作者第一时间就把 varlet 周边的项目迁移到了 Vite+ 上面试试水，迁移下来发现效果特别好。以前那些散落在各处的 eslint 配置、prettier 配置、lint-staged 配置、commitlint 配置可以统一收拢到一个 vite.config.ts 里面，项目根目录一下子干净了不少（以前打开根目录看到十几个 .xxxrc 文件的日子终于结束了）。而且因为工具链统一了，AI Agent 在理解项目配置的时候幻觉也少了很多。

公司项目迁移

既然体验这么好，作者就决定把公司内部的前端项目也都迁移到 Vite+ 上。迁移的过程中也让作者重新审视了一下 rattail，我们在 varlet 生态里积累了大量的工具函数、请求库、校验规则工厂、CLI 工具链，之前一直是分散在各个包里的，正好借这次机会做一次大整合，于是就有了 rattail 2.0——一个面向 Vite+、对 AI Agent 非常友好的前端工具链。140+ 工具函数、渐进式请求库、链式校验规则工厂、CLI 工具链、类型安全枚举，pnpm add rattail 一条命令全部拉齐。

目前作者也在公司项目中全面使用了 Vite+ + rattail 这套技术栈，体验下来非常舒服。另外值得一提的是，这次 rattail 2.0 的迁移和开发过程中，作者大量使用了 AI 辅助编程，包括工具函数的编写、单元测试的补全、文档的生成等等，效率提升非常明显。配合 rattail 提供的 Agent Skills，AI Agent 能够很好的理解项目上下文并正确使用 rattail 的 API，整个工作流跑下来还是相当丝滑的。后续在业务开发中也明显感觉到，因为 rattail 把工具函数、请求库、校验规则这些东西 all in one 了，AI 在生成代码的时候幻觉变得特别少，而且很会按照规范做事。

相关链接

• 官方文档: rattail.varletjs.org
• 仓库地址: github.com/varletjs/ra…

特性一览

• ⚙️ 面向 Vite+ 的开箱即用配置预设
• 🔧 CLI 工具链，支持发布、日志、Git Hooks、Commit Lint、API 生成
• 🧰 140+ 工具函数，覆盖通用、字符串、数字、数组、对象、数学等场景
• 🚀 基于 axios 的渐进式请求工具，支持 Vue 组合式 API
• 📏 链式校验规则工厂，适配任意 UI 框架
• 🏷️ 类型安全的枚举工具
• 🤖 提供 Agent Skills，帮助 AI 编程助手理解和使用 Rattail
• 🌲 可 Tree-shake，轻量，TypeScript 完整类型支持
• 💪 90%+ 单元测试覆盖率

下面作者挑几个有意思的能力展开聊聊。

Vite+ 配置预设

做过前端工程化的同学应该都有体会，每次新项目光配 eslint 和 prettier 这些东西就够喝一壶的了，配好了还得处理各种冲突。rattail 内置了面向 Vite+ 的开箱即用预设，一个 vite.config.ts 搞定 lint、format、staged、git hooks 等所有工程化配置。

import { lint, fmt, staged, clean, hook, defineConfig } from 'rattail/vite-plus'

export default defineConfig({
  lint: lint(),

  fmt: fmt(),

  staged: staged(),

  rattail: {
    clean: clean(),

    hook: hook(),
    
    api: {},

    release: {},

    changelog: {}
  },
})

之前作者为了配这些东西写了好几个配置文件，现在一个文件就够了（少写代码是第一生产力）。

CLI 工具链

安装 rattail 后会注册一个 rt 命令，覆盖了作者日常开发中最常用的几个场景。

# 清理产物
rt clean

# 安装 git hooks
rt hook

# 发布
rt release

# 生成 changelog
rt changelog

# 从 OpenAPI 生成 API 模块
rt api

这些命令都支持通过 vite.config.ts 中的 rattail 字段进行配置，也就是说项目根目录不需要再多出一堆 .xxxrc 文件了。这一点作者是比较在意的，毕竟谁也不想打开项目根目录看到十几个配置文件吧（有些项目根目录比 node_modules 还热闹）。

140+ 工具函数

lodash 大家都耳熟能详了，rattail 里的工具函数覆盖的场景和 lodash 类似，包括类型判断、数组、对象、字符串、数学、函数、集合、文件等分类，用法就不逐个列举了。和 lodash 不同的是，这些函数从第一天就是用 TypeScript 写的，类型推导是第一优先级，全部可 Tree-shake。除了 lodash 风格的工具函数以外，rattail 还内置了一些前端项目中常用的实用工具，比如 sumHash 计算哈希、uuid 生成唯一 ID、mitt 事件总线、duration 时间格式化、storage / cookieStorage 存储封装、copyText 复制文本、download 文件下载等等，省得同学们每次都要单独装一堆小包。更多的可以去文档里查看完整的 API 列表。

类型安全的枚举工具

这个是作者个人比较喜欢的一个工具。前端项目里到处都是枚举值，比如订单状态、用户角色之类的。一般我们用 enum 或者常量对象来管理它们，但是 label、description 这些配套信息就只能另外维护了。enumOf 把值和它的元信息放在一起管理，并且类型推导是完备的。

import { enumOf } from 'rattail'

const Status = enumOf({
  Pending: { value: 0, label: '待处理' },
  Active: { value: 1, label: '进行中' },
  Done: { value: 2, label: '已完成' },
})

Status.Pending        // 0
Status.Active         // 1
Status.values()       // [0, 1, 2]
Status.labels()       // ['待处理', '进行中', '已完成']
Status.label(Status.Pending) // '待处理'
Status.options()      // [{ value: 0, label: '待处理' }, ...]

// 直接丢给 select 组件的 options，再也不用手动维护了

前端项目里到处都需要枚举值和它对应的文案，以前每次都要写个 map 或者 switch，现在一个 enumOf 就够了。另外 enumOf 的 label 和 description 支持传入一个 getter 函数，配合 vue-i18n 之类的国际化方案可以很方便的实现多语言：

const Status = enumOf({
  Pending: { value: 0, label: () => t('status.pending') },
  Active: { value: 1, label: () => t('status.active') },
  Done: { value: 2, label: () => t('status.done') },
})

基于 axios 的渐进式请求工具

这个能力来自于作者之前开源的 @varlet/axle，现在通过 rattail/axle 直接引入。熟悉作者的同学可能看过之前介绍 axle 的文章，它在兼容 axios 的同时，天然支持 Vue3 Composition API。

import { createAxle } from 'rattail/axle'
import { createUseAxle } from 'rattail/axle/use'

const axle = createAxle({ baseURL: '/api' })
const useAxle = createUseAxle({ axle })

const [users, getUsers, { loading, error }] = useAxle({
  method: 'get',
  url: '/user',
  params: { current: 1, pageSize: 10 },
})

作者一直觉得前端请求库和 Vue 的响应式系统应该有更好的结合方式，axle 就是在这个方向上的一个尝试。如果你不喜欢 axle 也完全没问题，rattail 的其他能力和请求库是解耦的，换成你喜欢的方案就好。

OpenAPI 生成 API 模块

rt api 可以直接解析后端提供的 OpenAPI / Swagger schema 文件，自动生成类型安全的 API 调用代码，这个在实际项目里把工作流做通之后体验可太好了。

在 vite.config.ts 里配置好 schema 路径和输出目录：

import { defineConfig } from 'rattail/vite-plus'

export default defineConfig({
  rattail: {
    api: {
      input: './openapi.json'
    },
  },
})

执行 rt api 后会自动生成这样的代码：

import { api } from '@/request'
import { type paths } from './_types'

export type ApiGetUsers = paths['/users']['get']
export type ApiCreateUser = paths['/users']['post']
export type ApiGetUser = paths['/users/{uuid}']['get']
export type ApiUpdateUser = paths['/users/{uuid}']['put']
export type ApiDeleteUser = paths['/users/{uuid}']['delete']

export type ApiGetUsersQuery = ApiGetUsers['parameters']['query']
export type ApiGetUsersRequestBody = undefined
export type ApiGetUsersResponseBody = ApiGetUsers['responses']['200']['content']['application/json']
// ... 其他类型同理

export const apiGetUsers = api<
  ApiGetUsersResponseBody, ApiGetUsersQuery, ApiGetUsersRequestBody>('/users', 'get')
export const apiCreateUser = api<
  ApiCreateUserResponseBody, ApiCreateUserQuery, ApiCreateUserRequestBody>('/users', 'post')
export const apiGetUser = api<
  ApiGetUserResponseBody, ApiGetUserQuery, ApiGetUserRequestBody>('/users/:uuid', 'get')
export const apiUpdateUser = api<
  ApiUpdateUserResponseBody, ApiUpdateUserQuery, ApiUpdateUserRequestBody>('/users/:uuid', 'put')
export const apiDeleteUser = api<
  ApiDeleteUserResponseBody, ApiDeleteUserQuery, ApiDeleteUserRequestBody>('/users/:uuid', 'delete')

请求类型、响应类型全部从 schema 里提取，不需要手写。后端接口变了，重新跑一遍 rt api 就行，前后端的类型始终保持同步。这个工作流对 AI Agent 也特别友好，AI 可以直接基于生成的类型去写业务代码，不会出现参数类型对不上的问题。甚至 AI Agent 可以通过 api 定义的变化，推测出你接下来要写什么业务。默认使用 axle，也支持 axios 的预设，同时支持 自定义输出。

链式校验规则工厂

做表单的同学应该都写过类似 required、min、max 这些校验规则。不同的 UI 框架校验规则的格式还不一样，每个项目都要适配一遍。rattail 提供了一个链式校验规则工厂，写起来很流畅，并且可以适配任意 UI 框架。这种内联的声明式写法和 TailwindCSS 的思路类似，可读性和可迁移性都非常好，对 AI 也特别友好，AI 可以直接从模板里读懂校验意图，生成和修改规则的准确度很高。

以 Naive UI 和 Element Plus 为例：

<!-- Naive UI -->
<script setup lang="ts">
import type { FormItemRule } from 'naive-ui'
import { rulerFactory } from 'rattail/ruler'

const r = rulerFactory<FormItemRule>((validator, params = {}) => ({
  trigger: ['blur', 'change', 'input'],
  validator: (_, value) => validator(value),
  ...params,
}))
</script>

<template>
  <n-form :model>
    <n-form-item 
      path="name" 
      label="姓名"
      :rule="r().required('必填').min(2, '长度不正确').done()"
    >
      <n-input v-model:value="model.name" />
    </n-form-item>
  </n-form>
</template>

<!-- Element Plus -->
<script setup lang="ts">
import type { FormItemRule } from 'element-plus'
import { rulerFactory } from 'rattail/ruler'

const r = rulerFactory<FormItemRule>((validator, params) => ({
  validator(_, value, callback) {
    const e = validator(value)
    e ? callback(e) : callback()
  },
  trigger: ['blur', 'change', 'input'],
  ...params,
}))
</script>

<template>
  <el-form :model>
    <el-form-item 
      prop="email" 
      label="邮箱"
      :rules="r().email('必须是邮箱格式').done()"
    >
      <el-input v-model="model.email" />
    </el-form-item>
  </el-form>
</template>

AI Agent Skills

rattail 提供了一套 Agent Skills，说白了就是给 AI 写了一份"说明书"，让 AI Agent 知道 rattail 有哪些能力、怎么用，不用你每次都手动告诉 AI。作者觉得未来的开源库都应该考虑对 AI Agent 的友好度。

写在最后

rattail 的工具函数和能力大多来自前端社区的通用实践。感谢同学们能看到这里，但是希望 rattail 能够帮助到大家。项目基于 MIT 协议。如果在使用的过程中遇到任何问题，欢迎在 issue 里反馈给我们，同时也十分欢迎对项目有兴趣的同学给我们发 pull request。

支持我们的话留下一个 star 就好～

• 官方文档: rattail.varletjs.org
• 仓库地址: github.com/varletjs/ra…

给你一个整数数组 nums。

镜像对 是指一对满足下述条件的下标 (i, j)：

• 0 <= i < j < nums.length，并且
• reverse(nums[i]) == nums[j]，其中 reverse(x) 表示将整数 x 的数字反转后形成的整数。反转后会忽略前导零，例如 reverse(120) = 21。

返回任意镜像对的下标之间的 最小绝对距离。下标 i 和 j 之间的绝对距离为 abs(i - j)。

如果不存在镜像对，返回 -1。

示例 1：

示例 2：

示例 3：

提示：

• 1 <= nums.length <= 105
• 1 <= nums[i] <= 109

解法：双指针

考虑整数 x，假设我们把序列里的所有 x 变成红色，所有 reverse(x) 变成蓝色， 我们就可以枚举所有红色，看左边最近的蓝色在哪里。这一问题可以用双指针解决。

枚举序列中出现过的所有不同整数 x，取最小答案即可。复杂度 $\mathcal{O}(n)$。

参考代码（c++）

class Solution {
public:
    int minMirrorPairDistance(vector<int>& nums) {
        int n = nums.size();

        // 求 reverse(x)
        auto gao = [&](int x) {
            vector<int> vec;
            for (; x; x /= 10) vec.push_back(x % 10);
            int ret = 0;
            for (int y : vec) ret = ret * 10 + y;
            return ret;
        };

        // pos1 记录每种元素出现的所有位置
        // pos2 记录每种 reverse 出现的所有位置
        unordered_map<int, vector<int>> pos1, pos2;
        for (int i = 0; i < n; i++) {
            pos1[nums[i]].push_back(i);
            pos2[gao(nums[i])].push_back(i);
        }

        const int INF = 1e9;
        int ans = INF;
        for (auto &entry : pos1) if (pos2.count(entry.first)) {
            auto &vec1 = entry.second;
            auto &vec2 = pos2[entry.first];
            // vec1[i] 是当前枚举到的元素下标，vec2[j] 是大于等于 vec1[i] 的最近 reverse 的下标
            // 所以 vec2[j - 1] 就是小于 vec[i] 的最近 reverse 的下标
            for (int i = 0, j = 0; i < vec1.size(); i++) {
                while (j < vec2.size() && vec2[j] < vec1[i]) j++;
                if (j - 1 >= 0) ans = min(ans, vec1[i] - vec2[j - 1]);
            }
        }
        return ans < INF ? ans : -1;
    }
};

不会做怎么办

本题是双指针的简单应用，不会做本题的读者可以学习 灵神题单 - 滑动窗口与双指针 的“双序列双指针”一节。

枚举 $j$，同时用哈希表维护 $j$ 左边的 $\text{reverse}(\textit{nums}[i])$ 的最大下标，哈希表的 key 是 $\text{reverse}(\textit{nums}[i])$，value 是下标 $i$。

如果哈希表中有 $\textit{nums}[j]$，获取对应的下标 $i$，用 $j-i$ 更新答案的最小值。

⚠注意：请仔细读题，题目要求的是 reverse(nums[i]) == nums[j]，不是 reverse(nums[j]) == nums[i]，下标必须满足 $i<j$，不是对称的。

本题视频讲解，欢迎点赞关注~

###py

class Solution:
    def minMirrorPairDistance(self, nums: List[int]) -> int:
        last_index = {}
        ans = inf

        for j, x in enumerate(nums):
            if x in last_index:
                ans = min(ans, j - last_index[x])
            rev = int(str(x)[::-1])
            last_index[rev] = j

        return ans if ans < inf else -1

###py

class Solution:
    def minMirrorPairDistance(self, nums: List[int]) -> int:
        last_index = {}
        ans = inf

        for j, x in enumerate(nums):
            if x in last_index:
                ans = min(ans, j - last_index[x])

            # 计算 reverse(x)，不用字符串
            rev = 0
            while x > 0:
                x, d = divmod(x, 10)
                rev = rev * 10 + d
            last_index[rev] = j

        return ans if ans < inf else -1

###java

class Solution {
    public int minMirrorPairDistance(int[] nums) {
        int n = nums.length;
        int ans = n;
        Map<Integer, Integer> lastIndex = new HashMap<>(n, 1); // 预分配空间

        for (int j = 0; j < n; j++) {
            int x = nums[j];
            Integer i = lastIndex.get(x);
            if (i != null) {
                ans = Math.min(ans, j - i);
            }

            // 计算 reverse(x)，不用字符串
            int rev = 0;
            for (; x > 0; x /= 10) {
                rev = rev * 10 + x % 10;
            }
            lastIndex.put(rev, j);
        }

        return ans < n ? ans : -1;
    }
}

###cpp

class Solution {
public:
    int minMirrorPairDistance(vector<int>& nums) {
        unordered_map<int, int> last_index;
        int n = nums.size(), ans = n;

        for (int j = 0; j < n; j++) {
            int x = nums[j];
            auto it = last_index.find(x);
            if (it != last_index.end()) {
                ans = min(ans, j - it->second);
            }

            // 计算 reverse(x)，不用字符串
            int rev = 0;
            for (; x > 0; x /= 10) {
                rev = rev * 10 + x % 10;
            }
            last_index[rev] = j;
        }

        return ans < n ? ans : -1;
    }
};

###go

func minMirrorPairDistance(nums []int) int {
n := len(nums)
ans := n
lastIndex := make(map[int]int, n) // 预分配空间

for j, x := range nums {
if i, ok := lastIndex[x]; ok {
ans = min(ans, j-i)
}

// 计算 reverse(x)，不用字符串
rev := 0
for ; x > 0; x /= 10 {
rev = rev*10 + x%10
}
lastIndex[rev] = j
}

if ans == n {
return -1
}
return ans
}

复杂度分析

• 时间复杂度：$\mathcal{O}(n\log U)$，其中 $n$ 是 $\textit{nums}$ 的长度，$U=\max(\textit{nums})$。反转一个数字需要 $\mathcal{O}(\log U)$ 时间。
• 空间复杂度：$\mathcal{O}(n)$。

专题训练

见下面数据结构题单的「§0.1 枚举右，维护左」。

分类题单

如何科学刷题？

1. 滑动窗口与双指针（定长/不定长/单序列/双序列/三指针/分组循环）
2. 二分算法（二分答案/最小化最大值/最大化最小值/第K小）
3. 单调栈（基础/矩形面积/贡献法/最小字典序）
4. 网格图（DFS/BFS/综合应用）
5. 位运算（基础/性质/拆位/试填/恒等式/思维）
6. 图论算法（DFS/BFS/拓扑排序/基环树/最短路/最小生成树/网络流）
7. 动态规划（入门/背包/划分/状态机/区间/状压/数位/数据结构优化/树形/博弈/概率期望）
8. 常用数据结构（前缀和/差分/栈/队列/堆/字典树/并查集/树状数组/线段树）
9. 数学算法（数论/组合/概率期望/博弈/计算几何/随机算法）
10. 贪心与思维（基本贪心策略/反悔/区间/字典序/数学/思维/脑筋急转弯/构造）
11. 链表、树与回溯（前后指针/快慢指针/DFS/BFS/直径/LCA）
12. 字符串（KMP/Z函数/Manacher/字符串哈希/AC自动机/后缀数组/子序列自动机）

我的题解精选（已分类）

When you run a PostgreSQL database in production, you rarely want every application and every developer to connect as the postgres superuser. A clean setup gives each service its own login role with a scoped set of privileges, so a bug or a leaked password cannot touch unrelated data.

PostgreSQL handles this with roles. A role can represent a single user, a group, or both at the same time, and privileges are granted to roles rather than to raw login accounts. This guide explains how to create roles, set passwords, grant and revoke privileges, and clean up roles you no longer need.

Roles vs Users in PostgreSQL #

Historically, PostgreSQL had separate CREATE USER and CREATE GROUP statements. Modern versions replaced both with a single concept: the role. A role with the LOGIN attribute can connect to the server, which makes it a user. A role without LOGIN is typically used as a group that other roles inherit privileges from.

In practice, CREATE USER is still valid and is treated as a shortcut for CREATE ROLE ... LOGIN. We will use both forms in this guide.

Connecting to PostgreSQL #

All the commands below run inside the psql shell. On most systems you can open it as the postgres system user:

sudo -u postgres psql

You will see a prompt like this:

postgres=#

Every SQL statement ends with a semicolon. If you forget it, psql keeps waiting for more input.

Creating a Role #

The simplest form of CREATE ROLE takes just a name:

CREATE ROLE linuxize;

This role exists but cannot log in yet and has no password.

To create a login role with a password, use LOGIN:

CREATE ROLE linuxize_login WITH LOGIN PASSWORD 'strong_password_here';

The equivalent shortcut is:

CREATE USER linuxize_user WITH PASSWORD 'strong_password_here';

Both statements produce the same result. Use whichever form reads more clearly in your scripts.

Useful Role Attributes #

You can combine several attributes in a single CREATE ROLE statement. These are the ones you will reach for most often:

• LOGIN - The role can connect to the server.
• PASSWORD 'secret' - Sets the login password.
• SUPERUSER - Grants full access, equivalent to the postgres role. Use sparingly.
• CREATEDB - The role may create new databases.
• CREATEROLE - The role may create and modify other roles.
• INHERIT - The role automatically inherits privileges of roles it is a member of. This is the default.
• VALID UNTIL 'timestamp' - Expires the password at the given time.
• CONNECTION LIMIT n - Caps the number of concurrent connections for this role.

For example, to create a login role that can also create databases and is limited to ten concurrent connections:

CREATE ROLE app_owner WITH LOGIN PASSWORD 'strong_password_here' CREATEDB CONNECTION LIMIT 10;

Listing Existing Roles #

To see every role on the server, use the \du meta-command:

\du

 List of roles
Role name | Attributes
-----------+------------------------------------------------------------
app_owner | Create DB, 10 connections
linuxize |
postgres | Superuser, Create role, Create DB, Replication, Bypass RLS

The Attributes column tells you what each role can do. A blank column means the role has no special attributes beyond the defaults, such as NOLOGIN and INHERIT.

Changing a Role #

Use ALTER ROLE to change attributes, rename a role, or reset a password. To change the password:

ALTER ROLE linuxize WITH PASSWORD 'new_password_here';

To grant an additional attribute:

ALTER ROLE linuxize CREATEDB;

To remove one, prefix it with NO:

ALTER ROLE linuxize NOCREATEDB;

Creating a Database for the Role #

It is common to give each application its own database owned by its login role. Create the database and assign ownership in one statement:

CREATE DATABASE linuxize_app OWNER linuxize;

The owner of a database has full control over it, so the role can create tables, schemas, and other objects without any further grants.

Granting Privileges #

Privileges in PostgreSQL are granted at several levels: database, schema, table, column, sequence, and function. The syntax is consistent across levels:

GRANT privilege_list ON object_type object_name TO role_name;

Database-level Privileges #

To let a role connect to a database and create objects in it:

GRANT CONNECT ON DATABASE linuxize_app TO linuxize;
GRANT CREATE ON DATABASE linuxize_app TO linuxize;

CONNECT controls whether the role can open a session to the database. CREATE controls whether it can create schemas.

Schema-level Privileges #

To let a role create and use objects inside a schema:

GRANT USAGE ON SCHEMA public TO linuxize;
GRANT CREATE ON SCHEMA public TO linuxize;

USAGE is required for almost every operation inside the schema. CREATE lets the role add new tables, views, or functions.

Table-level Privileges #

Table privileges match the common SQL operations:

GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE orders TO linuxize;

To grant every available table privilege at once:

GRANT ALL PRIVILEGES ON TABLE orders TO linuxize;

To grant the same privileges on every existing table in a schema:

GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO linuxize;

This only affects tables that exist at the moment you run the command. Tables created later are not covered.

Default Privileges for Future Objects #

To cover tables created in the future, set default privileges:

ALTER DEFAULT PRIVILEGES IN SCHEMA public
 GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO linuxize;

From this point on, any new table created in public by the current role inherits the listed privileges for linuxize.

Revoking Privileges #

REVOKE is the mirror of GRANT and uses the same structure:

REVOKE INSERT, UPDATE, DELETE ON TABLE orders FROM linuxize;

To strip every privilege on a table:

REVOKE ALL PRIVILEGES ON TABLE orders FROM linuxize;

Revoking a privilege only affects the privileges you previously granted. Ownership is a separate concept: the owner of an object always keeps full control over it, regardless of grants.

Group Roles #

To manage privileges for a team, create a role without LOGIN and add members to it:

CREATE ROLE readonly;
GRANT CONNECT ON DATABASE linuxize_app TO readonly;
GRANT USAGE ON SCHEMA public TO readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly;

GRANT readonly TO linuxize;

linuxize now inherits every privilege granted to readonly. To remove the membership later:

REVOKE readonly FROM linuxize;

This pattern scales better than granting privileges role by role, because you change permissions in one place.

Deleting a Role #

To drop a role, use DROP ROLE:

DROP ROLE linuxize;

PostgreSQL refuses the command if the role still owns any objects or holds any privileges. To clean these up first, reassign the objects and drop dependent privileges in each database where the role owns objects:

REASSIGN OWNED BY linuxize TO postgres;
DROP OWNED BY linuxize;
DROP ROLE linuxize;

REASSIGN OWNED transfers ownership of objects owned by the role in the current database, and DROP OWNED removes any remaining privileges there. If the role owns objects in other databases, repeat the cleanup in each one before dropping the role.

Quick Reference #

Troubleshooting #

ERROR: permission denied for schema public
Grant USAGE on the schema: GRANT USAGE ON SCHEMA public TO role_name;. On PostgreSQL 15 and later, the public schema is no longer writable by default, so you may also need GRANT CREATE ON SCHEMA public.

ERROR: role "name" cannot be dropped because some objects depend on it
Reassign and drop the role’s objects first: REASSIGN OWNED BY name TO postgres; DROP OWNED BY name;, then run DROP ROLE name; again.

FATAL: password authentication failed for user
Check that the role has LOGIN and that the authentication method in pg_hba.conf matches the client (for example, md5 or scram-sha-256). Reload the configuration with SELECT pg_reload_conf(); after editing pg_hba.conf.

New tables are not visible to a read-only user
Grants on ALL TABLES IN SCHEMA only cover tables that exist at grant time. Set ALTER DEFAULT PRIVILEGES for the owning role so new tables inherit the read permissions automatically.

FAQ #

What is the difference between CREATE USER and CREATE ROLE?
CREATE USER is a shortcut for CREATE ROLE ... LOGIN. Both create the same kind of object. Use CREATE USER when you want a login account and CREATE ROLE when you are creating a group role without login.

Can a single role be both a user and a group?
Yes. A role with LOGIN can still be granted to other roles. Members inherit its privileges as long as INHERIT is set, which is the default.

How do I change the owner of an existing database?
Use ALTER DATABASE db_name OWNER TO new_owner;. The new owner gains full control over the database and its objects.

Do I need to restart PostgreSQL after creating a role?
No. Role changes take effect immediately. Only changes to pg_hba.conf or the main server configuration require a reload or restart.

Conclusion #

Roles are the single unit of access control in PostgreSQL. Give each application its own login role, group shared privileges into group roles, and use ALTER DEFAULT PRIVILEGES so future objects stay consistent with your current policy.

For related reading, see how to check the PostgreSQL version and the installation guide for your distribution under the PostgreSQL tag .

Bun v1.3.12 带来了内置无头浏览器自动化、终端 Markdown 渲染、进程内定时任务等新特性，同时在性能优化和兼容性方面取得了显著进展。本文将通过示例代码和实战指南，帮助开发者快速上手这些新功能。

大家好，我是 iDao。10 年全栈开发，做过架构、运维，也在落地 AI 工程化。这里不搞虚的，只分享能直接跑、能直接用的代码、方案和经验。内容包括：全栈开发实战、系统搭建、可视化大屏、自动化部署、AI 应用、私有化部署等。关注我，一起写能落地的代码，做能上线的项目。

一、Bun.WebView：内置无头浏览器自动化

Bun v1.3.12 引入了 Bun.WebView，这是一个内置的无头浏览器自动化工具，支持 WebKit 和 Chrome 两种后端，提供类似 Playwright 的 API。

主要特性

• 原生事件模拟：所有输入均以操作系统级别事件分发，无法被网站检测为自动化。
• 自动等待：支持选择器操作的自动等待，确保元素可见、稳定后再执行。
• 跨平台支持：WebKit 默认用于 macOS，Chrome 后端支持所有平台。

示例代码

以下代码展示了如何使用 Bun.WebView 进行页面导航、点击和截图：

await using view = new Bun.WebView({ width: 800, height: 600 });
await view.navigate("https://bun.sh");

await view.click("a[href='/docs']"); // 等待元素可点击并执行点击
await view.scroll(0, 400); // 模拟滚轮事件

const title = await view.evaluate("document.title");
const png = await view.screenshot({ format: "jpeg", quality: 90 });
await Bun.write("page.jpg", png);

二、Markdown 渲染：终端直接预览

Bun v1.3.12 支持直接在终端渲染 Markdown 文件，提供了两种方式：

1. 运行 bun ./file.md。
2. 使用 Bun.markdown.ansi() API。

示例代码

以下代码展示了如何使用 Bun.markdown.ansi() 渲染 Markdown：

const out = Bun.markdown.ansi("# Hello\n\n**bold** and *italic*\n");
process.stdout.write(out);

// 启用超链接
const linked = Bun.markdown.ansi("[docs](https://bun.sh)", { hyperlinks: true });
process.stdout.write(linked);

三、Bun.cron：进程内定时任务

Bun.cron 新增了回调函数支持，适合长时间运行的服务和容器。

示例代码

以下代码展示了如何使用 Bun.cron 定时执行异步任务：

Bun.cron("* * * * *", async () => {
  console.log("每分钟执行一次");
});

四、性能优化与新特性

URLPattern 性能提升

URLPattern.test() 和 URLPattern.exec() 的性能提升了最高 2.3 倍。

const pattern = new URLPattern({ pathname: "/api/users/:id/posts/:postId" });
pattern.test("https://example.com/api/users/42/posts/123");

Bun.stripANSI 和 Bun.stringWidth 的 SIMD 优化

Bun.stripANSI 和 Bun.stringWidth 的性能显著提升，处理速度最高提升 11 倍。

bun build 构建优化

修复了线程池问题，使低核机器上的构建速度提升了 1.43 倍。

五、Bug 修复与兼容性改进

• 修复了多个 Node.js 兼容性问题，例如 process.env 在某些情况下为空的问题。
• 改进了 Bun.serve 的 TCP_DEFER_ACCEPT 支持，降低了 HTTP 请求延迟。

六、升级指南与验证步骤

升级到 v1.3.12

运行以下命令升级到最新版本：

bun upgrade

验证新功能

验证 Bun.WebView 是否正常工作：

await using view = new Bun.WebView();
await view.navigate("https://example.com");
console.log(await view.title);

七、总结

Bun v1.3.12 带来了众多令人兴奋的新特性和性能优化，尤其是 Bun.WebView 和 Bun.cron 的引入，为开发者提供了更多可能性。通过本文的示例代码和实战指南，相信你已经掌握了这些新功能的使用方法。

关注 【iDao技术魔方】，获取更多全栈到AI可落地的实战干货。

用AI读源码这件事：前端视角的实战方法论，附Vue3 reactivity源码解读示范

读源码这件事，前端开发者应该不陌生。

学新框架要看源码、理解某个第三方库的行为要看源码、接手一个没人维护的老项目更要翻源码。但说实话，源码读到一半上下文丢了、函数调用链路追踪到后面找不到头绪、第三方库没有文档只能靠猜——这些场景应该每个人都遇到过。

这两年AI工具多了，我开始尝试用AI辅助读源码。一开始踩了不少坑，后来慢慢摸索出几个相对稳定的用法，今天把实际验证过的方法论配合真实代码讲清楚。

1. 先定位再提问：不要把整个文件丢给AI

这是最容易犯的错误——把几百行代码一股脑丢给AI问"这段是做什么的"。

AI的上下文窗口虽然长，但代码量大了之后它容易失焦，回复要么泛泛而谈、要么开始自己编一段你根本找不到出处的逻辑。更关键的是，这样浪费了上下文token，效果反而差。

正确的做法

用IDE的 Go to Definition / Find References 定位到核心函数，只把相关的片段丢给AI。

实战演示：用Vue3 reactive 源码

假设我想理解 Vue3 的 reactive 函数做了什么。先找到函数定义：

// vuejs/core/packages/reactivity/src/reactive.ts
export function reactive<T extends object>(target: T): Reactive<T>
/*@__NO_SIDE_EFFECTS__*/
export function reactive(target: object) {
  // 如果目标已经是readonly代理，直接返回
  if (isReadonly(target)) {
    return target
  }
  return createReactiveObject(
    target,
    false,
    mutableHandlers,
    mutableCollectionHandlers,
    reactiveMap,
  )
}

这段代码本身不到20行，包含的类型声明和接口定义加起来也就50行左右。

丢给AI的提问方式：

"请解读这个reactive函数的实现逻辑，重点关注：1）为什么第一步要判断isReadonly；2）createReactiveObject各参数的含义；3）false这个标记位的作用是什么？"

比这样问效果好很多：

"reactive函数是做什么的？"（太宽泛，AI会复述文档而非分析代码）

不要这样问：

"帮我分析整个reactive.ts文件"（上下文太散，AI容易乱编）

2. 追问链：连续追问形成探索链路

读源码不是做问答游戏，不是问一句答一句就结束了。好的使用方式是连续追问，每一轮都基于上一轮的回答延伸。

追问链的标准模板

第一轮：这个函数的入参是什么类型，它做了哪些初步判断？
第二轮：如果入参已经是响应式对象会怎样？走哪个分支？
第三轮：这个分支里的Proxy是在哪里创建的？
第四轮：Proxy的get handler里，为什么要做scheduler判断？

每一轮只问一个"深入一层"的问题，不要同时问多个相关但不同层次的问题——问多了AI会选最浅的回答你。

实战演示：用追问链追踪reactive的proxy创建

我：
reactive函数里的createReactiveObject做了什么？

AI：
createReactiveObject是创建响应式代理的核心函数...
它的第三个参数mutableHandlers是一个Proxy的handler配置对象...
它会拦截对象的get/set等操作来实现依赖收集和触发更新...

我：
那mutableHandlers在哪里定义的？

AI：
在reactive.ts同目录下的baseHandlers.ts中...
它定义了get、set、deleteProperty等handler...
核心逻辑在get函数里，涉及到isRef判断、嵌套reactive等内容...

我：
get handler里的isRef判断具体在哪个条件下触发？

AI：
当访问的属性值是一个ref对象时（通过isRef函数判断），
会自动解包ref并返回其内部值。这个逻辑在get handler中大约第15行附近...

这样一层层追问下去，你会获得一条清晰的追踪路径，而且每一步都有代码依据。

追问链的进阶技巧

① 给AI一个假设，让它验证或否定：

"我猜测对数组调用reactive时，会进入COLLECTION分支，请对照代码确认这个猜测，如果不对指出第一个分叉点在哪里。"

这种方式的好处是：你有猜测，AI不会泛泛而谈；如果你猜错了，修正过程本身就是深入理解。

② 告诉AI你读到这里"卡住了"：

"我在追踪proxy的创建流程，但在createReactiveObject的第四个参数那里卡住了——这个WeakMap的作用是什么？它和reactiveMap有什么区别？"

把"卡住"说出来，AI会针对你的具体断点给出分析，而不是重新泛泛概述。

3. 标注"不确定"：让AI帮你做验证性推理

读代码时经常会有这种感觉——"这里逻辑看起来奇怪"或者"这个条件判断可能有问题"。

这时候可以直接把你的不确定告诉AI：

"我不确定这里为什么需要判断 !isObject，如果传进来的是数组会怎样？" "这段代码里如果target是null会走哪个分支？" "这个else分支我觉得永远不会执行，请帮我确认。"

这种"不确定+具体猜测"的方式，比直接问"这段代码的逻辑是什么"效果好很多。

原因在于：你在引导AI做验证性推理——验证或否定你的猜测，而不是做描述性推理——把代码表面意思翻译成自然语言。前者能挖到深层逻辑，后者只是换了种表达方式。

实战演示

在reactive源码中有这样一段：

function getTargetType(value: Target) {
  return value[ReactiveFlags.SKIP] || !Object.isExtensible(value)
    ? TargetType.INVALID
    : targetTypeMap(toRawType(value))
}

可以这样问AI：

"我不确定这里为什么用 Object.isExtensible(value) 来判断是否是无效目标，如果一个普通对象但它的原型被锁定了（Object.preventExtensions），会不会被误判为INVALID类型？"

AI会带你去看 Object.preventExtensions 和 Object.isExtensible 的区别，结合这段代码的具体场景分析这是有意为之还是潜在问题。

4. 用"用户视角"理解第三方库的外部行为

这个技巧适合在理解一个库的API行为时使用，而不是追踪内部实现。

核心思路：让AI站在调用方的角度，从外向内追踪。

比如我想理解 vueuse 的 useLocalStorage 为什么在SSR时会失效，我会这样说：

"作为一个使用useLocalStorage的开发者，我在SSR环境下发现值不同步。请帮我追踪这个函数的实现，找到可能导致SSR场景下行为不一致的原因。"

从"用户视角"切入，AI会倾向于从暴露的API开始追踪，而不是陷入内部的工具函数。对于理解一个库的外部行为特别有用。

5. 结合IDE做交叉验证

AI说的内容不一定完全准确，特别是涉及复杂调用链时。交叉验证非常重要。

我的习惯是：

1. AI给出的关键结论，在IDE里用 Go to Definition 快速确认
2. 如果AI说的函数名在IDE里找不到，那说明AI在编造
3. 对于特别重要的结论，同时问两个不同的AI工具，看结论是否一致

这本质上是一种工程思维——不迷信单一信息源，用多个工具交叉核对。

总结

用AI读源码这件事，用对了确实能提升效率，但有几个前提：

• 你得对代码结构有基本的方向感，知道去哪找文件、找哪个函数
• AI是辅助工具，不是替代品，核心逻辑还是得自己理解
• 不要过度依赖，遇到关键逻辑最好在IDE里自己跑一遍
• AI的结论要交叉验证，不轻信

这些方法不一定多新颖，但都是我实际工作里反复验证过的。如果有更好的技巧，欢迎交流。

参考资料

1. Vue3 Core 源码 - reactivity 模块（MIT License）
2. Vue3 官方文档 - Reactive 响应式原理
3. MDN - Object.isExtensible
4. MDN - Proxy
5. Anthropic - Claude for Code（AI代码辅助工具相关研究）
6. GitHub Blog - Developer Experience

以上内容均为技术原理分享，源码引用遵守Vue3的MIT开源协议。

OpenSpec: 需求 → 结构化制品（proposal / spec / design / tasks），解决"做什么" Superpowers: brainstorming → worktree → plan → subagent → TDD → review → finish，解决"怎么做好" 本文档：二者如何结合，以及如何应对任务中断和上下文丢失

两套系统的关系

┌─────────────────────────────────────────────────────────┐
│                    OpenSpec (需求层)                      │
│                                                           │
│  explore → propose → continue → apply → verify → archive │
│     │          │                   │                      │
│  梳理需求   生成制品             逐任务实现               │
│             (proposal.md                                  │
│              design.md                                    │
│              tasks.md)                                    │
└─────────┬──────────────────────────┬────────────────────┘
          │                          │
          │ 制品 = 持久化的需求记忆   │ tasks.md = 进度跟踪
          │                          │
┌─────────▼──────────────────────────▼────────────────────┐
│                  Superpowers (工程层)                      │
│                                                           │
│  brainstorming → git-worktree → writing-plans             │
│       → subagent-driven-dev → TDD → code-review           │
│       → verification → finishing-branch                    │
│                                                           │
│  隔离工作区、子代理执行、测试驱动、代码审查、分支收尾      │
└─────────────────────────────────────────────────────────┘

简单理解：

• OpenSpec 管「需求到任务」的拆解和持久化
• Superpowers 管「任务到代码」的工程质量和执行效率
• 二者通过 磁盘上的 Markdown 文件 连接，这也是对抗 AI 遗忘的关键

完整流程（从产品文档到上线）

Phase 1: 需求梳理

有两条路径可选：

路径 A — OpenSpec Explore（推荐用于"只有截图+字段表"的场景）：

/opsx:explore

产品给了「供应商审核」的原型截图和字段文档：
[拖入截图]
[粘贴字段表]

Explore 模式是只读思考伙伴：

• 从截图提取页面结构、字段、操作按钮
• 从字段文档结构化数据模型
• 画 ASCII 图理清状态流转
• 不写代码，只输出理解

梳理清楚后自然过渡到 Phase 2。

路径 B — Superpowers Brainstorming：

直接告诉 AI 要做什么，Superpowers 自动进入 brainstorming 流程：

1. 探索项目现有结构
2. 一次问一个问题澄清需求
3. 提出 2-3 种方案 + 推荐
4. 分段展示设计，逐段确认
5. 写入 docs/superpowers/specs/ 并 commit

Phase 2: 生成结构化制品

使用 OpenSpec Propose 一步到位：

/opsx:propose supplier-review

开发 admin-portal 的「供应商审核」模块。
[截图 + 字段说明 + 业务规则]

自动生成：

openspec/changes/supplier-review/
├── proposal.md    ← 做什么、范围、能力列表
├── design.md      ← 文件结构、组件拆分、API 设计
└── tasks.md       ← checkbox 任务清单

或者，如果已经通过 Brainstorming 产出了设计文档，可以：

1. 将 docs/superpowers/specs/ 下的设计文档作为输入
2. 用 /opsx:propose 时附上，让 OpenSpec 制品与 Superpowers 设计保持一致

Phase 3: 工作区隔离

Superpowers 的 git-worktree 自动触发：

开始实现 supplier-review

Superpowers 会：

1. 创建 .worktrees/supplier-review 隔离工作区
2. 新建 feature/supplier-review 分支
3. 运行 pnpm install 安装依赖
4. 验证测试基线通过

为什么要隔离： 主工作区保持干净，多个功能可以并行开发互不干扰。

Phase 4: 逐任务实现

OpenSpec Apply + Superpowers Subagent 联合驱动：

/opsx:apply

执行引擎有两种模式：

模式 A — Subagent-Driven（推荐，大功能用）：

主 Agent（协调者，上下文最小化）
  │
  ├─ 读 tasks.md，提取 Task 1 的完整描述
  │
  ├─ 派发 Subagent 1 实现 Task 1
  │   └─ Subagent 遵循 TDD：写测试 → 红 → 实现 → 绿 → 重构
  │
  ├─ 派发 Spec Reviewer 检查是否符合 design.md
  │   └─ 不符合 → Subagent 修复 → 再审
  │
  ├─ 派发 Code Reviewer 检查代码质量
  │   └─ 有问题 → Subagent 修复 → 再审
  │
  ├─ tasks.md 中 Task 1 打勾 [x]
  │
  ├─ 派发 Subagent 2 实现 Task 2 ...
  │
  └─ 全部完成后 → Phase 5

模式 B — 直接执行（小功能用）：

/opsx:apply

AI 直接在当前会话中逐任务实现，每完成一个打勾。

Phase 5: 验证 + 收尾

/opsx:verify supplier-review

三维度检查：完整性 × 正确性 × 一致性

通过后，Superpowers 接管收尾：

实现完成，准备收尾

Superpowers finishing-a-development-branch 自动：

1. 运行全量测试
2. 提供四个选项：合并 / 创建 PR / 保留分支 / 丢弃
3. 清理 worktree

最后：

/opsx:archive supplier-review

任务中断与恢复（核心问题）

问题本质

┌──────────────────────────────────────────────┐
│           AI 的上下文窗口 (有限)              │
│                                                │
│  对话开始 ───────────────────── 对话结束/中断  │
│  记住一切           逐渐遗忘        全部丢失   │
└──────────────────────────────────────────────┘

AI 有两个致命限制：

1. 上下文窗口有限 — 长对话后期忘记前面内容
2. 会话不持久 — 关窗口 / 新对话 = 一切归零

解决方案：三层持久化

┌─────────────────────────────────────────────┐
│ 第 1 层：项目级永久记忆                       │
│                                               │
│ openspec/config.yaml                          │
│ ├── 技术栈、代码约定                          │
│ ├── 每次新对话 AI 自动读取                    │
│ └── 相当于"置顶备忘录"                        │
│                                               │
│ CLAUDE.md / .cursor/rules/                    │
│ └── IDE 自动注入的项目规则                    │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 第 2 层：功能级需求记忆                       │
│                                               │
│ openspec/changes/<name>/                      │
│ ├── proposal.md  → "这个功能是干嘛的"         │
│ ├── design.md    → "代码怎么组织"             │
│ └── tasks.md     → "做到哪了" (checkbox)      │
│                                               │
│ docs/superpowers/specs/<design>.md            │
│ └── Brainstorming 产出的设计文档              │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ 第 3 层：代码级状态记忆                       │
│                                               │
│ git worktree + branch                         │
│ ├── 分支名就是功能名                          │
│ ├── commit 历史就是实现进度                   │
│ └── worktree 路径就是工作区位置               │
└─────────────────────────────────────────────┘

中断恢复操作手册

场景 1：对话中途中断（关闭窗口 / 网络断开）

恢复方式： 新开对话，一句话搞定

/opsx:apply

AI 自动执行的恢复链：

1. openspec list → 找到活跃变更
2. 读 proposal.md → 恢复"做什么"
3. 读 design.md → 恢复"怎么做"
4. 读 tasks.md → 扫描 checkbox，定位到第一个 - [ ]
5. 从断点继续实现

场景 2：跨天开发（每天做一点）

完全相同，每天开工直接：

/opsx:apply supplier-review

场景 3：长对话上下文不够了（AI 开始"犯糊涂"）

症状： AI 忘记了之前的约定，代码风格不一致，重复问已回答过的问题

解决方式： 不要在旧对话中挣扎，直接新开对话

/opsx:apply supplier-review

新对话有全新的上下文窗口，从磁盘读取制品文件，比继续在被污染的旧对话中好。

场景 4：Subagent 执行到一半中断

Subagent 每完成一个 task 就在 tasks.md 中打勾并 commit。中断后：

/opsx:apply

主 Agent 读 tasks.md，跳过已完成的 [x]，从下一个 [ ] 继续派发 Subagent。

场景 5：需求变更（产品改了文档）

/opsx:explore supplier-review

产品说审核从一级改成两级，新流程截图如下：
[拖入新截图]

评估对 design.md 和 tasks.md 的影响。

确认后手动或让 AI 更新制品文件，再 /opsx:apply 继续。

上下文优化策略

策略 1：Subagent 隔离（Superpowers 核心能力）

主 Agent                    Subagent 1           Subagent 2
  │                             │                     │
  │ 只保留协调信息              │ 全新上下文           │ 全新上下文
  │ (tasks列表+当前进度)        │ (Task 1完整描述      │ (Task 2完整描述
  │                             │  + design.md片段)    │  + design.md片段)
  │                             │                     │
  │ 上下文消耗：极小            │ 上下文消耗：中等     │ 上下文消耗：中等

核心原理： 主 Agent 把任务的完整描述"打包"给 Subagent，Subagent 用全新上下文执行。执行完毕后 Subagent 的上下文被释放，不会污染主 Agent。

策略 2：制品文件 ＞ 对话记忆

实践建议： 当你在对话中做了重要决策，但还没到 propose 阶段时，让 AI 立刻写入文件：

把刚才讨论的结论写入 openspec/changes/supplier-review/notes.md

策略 3：config.yaml 是跨会话记忆

# openspec/config.yaml
context: |
  这里的内容，每次新对话 AI 都会读到。
  等于给 AI 的"永久记忆"。

适合写入：

• 技术栈版本号
• 代码约定（命名、目录结构、import 顺序）
• 团队特有术语
• 常见的坑（"Ant Design 的 Table 组件在 xx 情况下需要 yy"）

实战走查：一条完整链路（以"供应商审核"为例）

以下以组合 5（全链路） 为例，演示从零到上线的每一步。每步标注：你输入什么 → AI 内部做了什么 → 磁盘上产生/变化了哪些文件。

Step 0: 前置状态

d:\work\srm-frontend\
├── openspec/
│   └── config.yaml               ← 已存在，项目级上下文
├── apps/admin-portal/src/
│   ├── app/router.tsx             ← 已有路由定义
│   └── features/                  ← 功能域目录
└── ...

Step 1: 需求梳理（可选）

你输入：

/opsx:explore

产品给了「供应商审核」的原型截图和字段文档：
[拖入截图]
[粘贴字段表]

AI 内部动作：

1. 读取 openspec/config.yaml 获取项目上下文
2. 分析截图，提取页面结构、字段、按钮、状态流转
3. 以对话形式输出理解，提问澄清

磁盘变化： 无（explore 是只读模式）

产出： 对话中形成的共识（页面结构、数据模型、业务规则）

Step 2: 生成结构化制品

你输入：

/opsx:propose supplier-review

开发 admin-portal 的「供应商审核」模块。
包含：审核列表页（分页、筛选、批量操作）+ 审核详情页（审核表单、审批流）。
[截图 + 字段说明 + 业务规则]

AI 内部动作：

1. 读取 SKILL 文件 .codex/skills/openspec-propose/SKILL.md
2. 读取 openspec/config.yaml 中的 rules（proposal / design / tasks 的约定）
3. 扫描现有代码结构，了解项目约定
4. 一次性生成三个制品文件

磁盘变化（新增 3 个文件）：

+ openspec/changes/supplier-review/
+   ├── proposal.md       ← 功能概述、范围、能力列表
+   ├── design.md         ← 文件结构、组件拆分、接口设计、状态管理
+   └── tasks.md          ← 实现任务清单（checkbox 格式）

生成的 tasks.md 示例：

# Tasks: supplier-review

## Implementation Tasks

- [ ] Task 1: 注册路由和菜单项
  在 router.tsx 的 portalMenuTree 中添加「供应商审核」菜单...
- [ ] Task 2: 封装 API hooks
  创建 hooks/useSupplierReviews.ts，包含列表查询和审核操作...
- [ ] Task 3: 实现审核列表页
  创建 SupplierReviewListPage.tsx，包含 Table + 筛选条件...
- [ ] Task 4: 实现审核详情页
  创建 SupplierReviewDetailPage.tsx，包含审核表单...
- [ ] Task 5: 单元测试
  为列表页和详情页编写 React Testing Library 测试...
- [ ] Task 6: TypeScript 类型检查
  运行 pnpm exec tsc --noEmit 确保无类型错误...

Step 3: 生成精细实现计划（Superpowers writing-plans）

你输入：

请根据 openspec/changes/supplier-review/ 的制品，
用 writing-plans 生成实现计划。

AI 内部动作：

1. 读取 SKILL 文件 skills/superpowers/writing-plans/SKILL.md
2. 读取 proposal.md + design.md + tasks.md
3. 将每个 task 拆成 2-5 分钟粒度的步骤，包含具体代码块

磁盘变化（新增 1 个文件）：

+ docs/superpowers/plans/2026-04-16-supplier-review.md

生成的 plan 文件结构：

# Implementation Plan: supplier-review

## Task 1: 注册路由和菜单项

### Step 1.1: 添加菜单项到 portalMenuTree (2 min)
**File:** `apps/admin-portal/src/app/router.tsx`
**Action:** 在 portalMenuTree 的「供应商」children 中添加：
```tsx
{
  path: 'supplier-review',
  title: '供应商审核',
  icon: <AuditOutlined />,
  children: [
    { path: 'supplier-review/list', title: '审核列表', icon: <UnorderedListOutlined /> },
    { path: 'supplier-review/detail/:id', title: '审核详情', icon: <FileSearchOutlined /> },
  ],
}
```
**Verify:** `pnpm exec tsc --noEmit -p apps/admin-portal/tsconfig.app.json`
**Commit:** `feat(supplier-review): register routes and menu items`

### Step 1.2: 创建功能域目录 (1 min)
**Action:** 创建目录结构
```
src/features/supplier-review/
├── index.ts
├── components/
└── hooks/
```
...

## Task 2: 封装 API hooks
### Step 2.1: ...

Step 4: 创建隔离工作区（Superpowers git-worktree）

你输入：

用 subagent-driven-development 执行计划

AI 内部动作（自动触发 using-git-worktrees）：

1. git worktree add .worktrees/supplier-review -b feature/supplier-review
2. cd .worktrees/supplier-review && pnpm install
3. 运行测试基线验证

磁盘变化：

+ .worktrees/supplier-review/          ← 完整项目副本，独立工作区
  （git branch: feature/supplier-review）

Step 5: Subagent 逐任务执行

AI 内部动作（subagent-driven-dev 自动循环）：

主 Agent（协调者）
  │
  │ 读 plan 文件，提取 Task 1 的所有 Steps
  │
  ├─── 派发 Subagent 1 ─────────────────────────────────────────┐
  │    提示词包含:                                                │
  │    - Task 1 的完整描述 + 所有 Steps                          │
  │    - design.md 中相关片段                                    │
  │    - 项目约定 (从 config.yaml)                               │
  │                                                              │
  │    Subagent 执行:                                            │
  │    1. 创建 src/features/supplier-review/ 目录                │
  │    2. 写 router.tsx 菜单项                                   │
  │    3. 运行 tsc --noEmit 验证                                 │
  │    4. git commit                                             │
  │    └─ 返回: "Task 1 完成，创建了 3 个文件，tsc 通过"         │
  │                                                              │
  ├─── 派发 Spec Reviewer ──────────────────────────────────────┐
  │    提示词: 检查 Task 1 实现是否符合 design.md                │
  │    └─ 返回: "✓ 路由结构符合设计，菜单层级正确"               │
  │                                                              │
  ├─── 派发 Code Reviewer ──────────────────────────────────────┐
  │    提示词: 检查代码质量和项目约定                             │
  │    └─ 返回: "✓ 通过，建议：icon import 可以统一到一个文件"   │
  │                                                              │
  ├─── tasks.md / plan.md 中 Task 1 打勾 [x]                    │
  │                                                              │
  ├─── 派发 Subagent 2 → Task 2: API hooks ...                  │
  │    ...同样的 实现 → spec review → code review 循环           │
  │                                                              │
  ├─── 派发 Subagent 3 → Task 3: 列表页面 ...                   │
  ├─── 派发 Subagent 4 → Task 4: 详情页面 ...                   │
  ├─── 派发 Subagent 5 → Task 5: 单元测试 ...                   │
  ├─── 派发 Subagent 6 → Task 6: tsc --noEmit ...               │
  │                                                              │
  └─── 全部 [x] → 报告完成                                      │

每个 Subagent 完成后的磁盘变化：

# Task 1 完成后
+ apps/admin-portal/src/features/supplier-review/index.ts
~ apps/admin-portal/src/app/router.tsx                  ← 修改（加菜单项）
~ openspec/changes/supplier-review/tasks.md             ← Task 1 打勾 [x]

# Task 2 完成后
+ apps/admin-portal/src/features/supplier-review/hooks/useSupplierReviews.ts
+ apps/admin-portal/src/features/supplier-review/hooks/useSupplierReviewDetail.ts
~ openspec/changes/supplier-review/tasks.md             ← Task 2 打勾 [x]

# Task 3 完成后
+ apps/admin-portal/src/features/supplier-review/SupplierReviewListPage.tsx
+ apps/admin-portal/src/features/supplier-review/components/ReviewFilters.tsx
+ apps/admin-portal/src/features/supplier-review/components/ReviewTable.tsx
~ openspec/changes/supplier-review/tasks.md             ← Task 3 打勾 [x]

# Task 4 完成后
+ apps/admin-portal/src/features/supplier-review/SupplierReviewDetailPage.tsx
+ apps/admin-portal/src/features/supplier-review/components/ReviewForm.tsx
+ apps/admin-portal/src/features/supplier-review/components/ApprovalFlow.tsx
~ openspec/changes/supplier-review/tasks.md             ← Task 4 打勾 [x]

# Task 5 完成后
+ apps/admin-portal/src/features/supplier-review/SupplierReviewListPage.test.tsx
+ apps/admin-portal/src/features/supplier-review/SupplierReviewDetailPage.test.tsx
~ openspec/changes/supplier-review/tasks.md             ← Task 5 打勾 [x]

# Task 6 完成后（无新文件，只跑检查）
~ openspec/changes/supplier-review/tasks.md             ← Task 6 打勾 [x]

git 历史（在 feature/supplier-review 分支上）：

* feat(supplier-review): pass tsc --noEmit type check
* test(supplier-review): add unit tests for list and detail pages
* feat(supplier-review): implement review detail page with approval flow
* feat(supplier-review): implement review list page with filters
* feat(supplier-review): add API hooks with TanStack Query
* feat(supplier-review): register routes and menu items

Step 6: 验证

你输入：

/opsx:verify supplier-review

AI 内部动作：

1. 读取 SKILL 文件 .codex/skills/openspec-verify-change/SKILL.md
2. 对比三个维度：
   • 完整性：tasks.md 全部 [x] ✓
   • 正确性：代码能编译、测试通过 ✓
   • 一致性：实现与 design.md 一致 ✓
3. 输出验证报告

磁盘变化： 无（只读检查）

Step 7: 收尾

你输入：

实现完成，准备收尾

AI 内部动作（finishing-a-development-branch）：

1. 运行 pnpm test 全量测试
2. 运行 pnpm lint 代码检查
3. 展示四个选项让你选择：
   • [1] 合并到 main
   • [2] 创建 PR
   • [3] 保留分支
   • [4] 丢弃

假设选择 [2] 创建 PR：

git push -u origin feature/supplier-review
gh pr create --title "feat: 供应商审核模块" --body "..."

磁盘变化：

- .worktrees/supplier-review/       ← worktree 清理

Step 8: 归档

你输入：

/opsx:archive supplier-review

AI 内部动作：

1. 读取 SKILL 文件 .codex/skills/openspec-archive-change/SKILL.md
2. 将 openspec/changes/supplier-review/ 下的制品归档
3. 如有 delta spec，合并到主 spec

磁盘变化：

- openspec/changes/supplier-review/     ← 整个目录归档/移除
+ openspec/specs/supplier-review/       ← 主 spec 更新（如有）

完整链路文件时间线总览

操作                    新增文件                                   修改文件
─────────────────────── ────────────────────────────────────────── ──────────────────────────
Step 1: explore         (无)                                       (无)
Step 2: propose         openspec/changes/supplier-review/          (无)
                          proposal.md, design.md, tasks.md
Step 3: writing-plans   docs/superpowers/plans/                    (无)
                          2026-04-16-supplier-review.md
Step 4: git-worktree    .worktrees/supplier-review/ (完整副本)     (无)
Step 5: subagent 执行   src/features/supplier-review/              router.tsx
                          index.ts                                 tasks.md (逐个打勾)
                          SupplierReviewListPage.tsx
                          SupplierReviewDetailPage.tsx
                          *.test.tsx
                          components/*.tsx
                          hooks/*.ts
Step 6: verify          (无)                                       (无)
Step 7: finishing        (无)                                       worktree 清理
Step 8: archive         openspec/specs/ (如有)                     openspec/changes/ 移除

命令速查

OpenSpec 命令

Superpowers 自动触发的 Skills

执行组合策略

四个执行工具的定位

需求拆解层                          执行层
                               ┌────────────────────────────┐
/opsx:apply ──────────────────►│  直接执行（内置简单模式）     │
  读 tasks.md                   │  逐 task 在当前会话实现      │
  逐 task 实现                  └────────────────────────────┘

                               ┌────────────────────────────┐
writing-plans ────────────────►│  生成精细计划文件             │
  把 task 拆成                  │  (每步 2-5 分钟粒度)         │
  2-5 分钟的步骤                └──────────┬─────────────────┘
                                           │
                                 ┌─────────┴──────────┐
                                 ▼                    ▼
                        executing-plans      subagent-driven-dev
                        (批量执行+检查点)    (每 task 派子代理+双审)

组合 1：/opsx:apply（单独使用）

适合： 小功能、占位页替换、简单 CRUD

/opsx:propose supplier-review
/opsx:apply

AI 读 tasks.md，在当前对话中逐个实现，每完成一个打勾。

典型任务量： 3-5 个 task，单次对话能搞定

组合 2：/opsx:apply + subagent-driven-dev

适合： 中等功能，需要质量保证

/opsx:propose material-library
/opsx:apply                        ← AI 自动用 subagent 模式执行

主 Agent 读 tasks.md，每个 task 派一个全新 Subagent 实现，完成后再派 reviewer 审查：

主 Agent（协调，上下文极小）
  │
  ├─ Subagent → Task 1: 注册路由    → Spec Review ✓ → Code Review ✓ → [x]
  ├─ Subagent → Task 2: API hooks   → Spec Review ✓ → Code Review ✓ → [x]
  ├─ Subagent → Task 3: 列表页面    → Spec Review ✗ → 修复 → 再审 ✓ → [x]
  └─ ...

典型任务量： 5-15 个 task，跨 1-3 天

组合 3：writing-plans + executing-plans

适合： 需要极其精细控制的功能，或要交给别人/别的 AI 执行

先生成精细计划：

我要实现供应商审核模块，设计文档在 openspec/changes/supplier-review/design.md，
请用 writing-plans 生成实现计划。

产出 docs/superpowers/plans/2026-04-16-supplier-review.md，每个步骤精确到：

• 具体文件路径和完整代码块
• 运行命令 + 预期输出
• commit message

然后执行：

按 docs/superpowers/plans/2026-04-16-supplier-review.md 执行

executing-plans 批量执行，到检查点暂停让你审核。

典型场景： 团队协作、需要人工审批的关键模块

组合 4：writing-plans + subagent-driven-dev（最高质量）

适合： 大功能，质量要求高，需要全自动执行

我要实现供应商审核模块，设计文档在 openspec/changes/supplier-review/design.md，
请用 writing-plans 生成实现计划，然后用 subagent-driven-development 执行。

writing-plans 生成精细计划
  │
  ▼
subagent-driven-dev 执行
  │
  ├─ Subagent 实现 Step 1 (TDD: 写测试→红→实现→绿)
  ├─ Spec Reviewer 审查是否符合设计
  ├─ Code Reviewer 审查代码质量
  ├─ [x] Step 1 完成
  │
  ├─ Subagent 实现 Step 2 ...
  └─ ...

典型场景： 核心业务模块、不允许返工的功能

组合 5：/opsx:propose + writing-plans + subagent-driven-dev（全链路）

适合： 从零开始的大模块，完整走一遍

Phase 1: OpenSpec 生成需求制品
/opsx:propose supplier-review + 截图/字段文档

Phase 2: Superpowers 生成精细计划
请根据 openspec/changes/supplier-review/ 的制品，
用 writing-plans 生成实现计划

Phase 3: Subagent 执行
用 subagent-driven-development 执行计划

Phase 4: 验证 + 收尾
/opsx:verify supplier-review
finishing-a-development-branch
/opsx:archive supplier-review

选择决策树

你要做多大的功能？
│
├─ 很小（改个按钮/加个字段）
│   └─ 不用 OpenSpec 也不用 Superpowers，直接写
│
├─ 小（1-3 个组件）
│   └─ /opsx:apply 单独用                          ← 组合 1
│
├─ 中（一个完整页面模块）
│   │
│   ├─ 赶时间？
│   │   └─ /opsx:apply + subagent                  ← 组合 2
│   │
│   └─ 要求高？
│       └─ writing-plans + subagent                ← 组合 4
│
├─ 大（多个页面/跨模块）
│   └─ /opsx:propose + writing-plans + subagent    ← 组合 5
│
└─ 需要交接给别人执行？
    └─ writing-plans + executing-plans             ← 组合 3

中断恢复对照

所有组合的进度都通过 磁盘上的 checkbox 持久化，新对话一句话恢复。

FAQ

Q: OpenSpec 和 Superpowers 的 brainstorming/writing-plans 功能重叠了吗？

有部分重叠，但侧重不同：

• OpenSpec propose 生成的 tasks.md 是按功能域拆分的粗粒度任务（每个 task ≈ 5-15 分钟）
• Superpowers writing-plans 生成的 plan 是每步 2-5 分钟的精细粒度（含完整代码块和命令）

推荐：用 OpenSpec 管需求到任务的拆解，用 Superpowers 管每个任务内部的 TDD 执行。两层粒度互补而非冲突。

Q: 一定要用 Subagent 吗？

不一定。Subagent 的价值在于：

1. 隔离上下文 — 每个 task 用全新上下文，不被前面的对话污染
2. 双重审查 — spec reviewer + code reviewer 保证质量
3. 对抗遗忘 — 主 Agent 上下文消耗最小

如果功能很小（3 个以下 task），直接在当前对话执行即可（组合 1）。

Q: writing-plans 生成的计划和 OpenSpec 的 tasks.md 有什么区别？

tasks.md（OpenSpec）              plan.md（Superpowers）
┌──────────────────┐            ┌─────────────────────────────┐
│ - [ ] 注册路由    │            │ Step 1: 创建路由文件          │
│ - [ ] API hooks  │──细化──▶  │   创建 src/app/router.tsx     │
│ - [ ] 列表页面    │            │   添加以下代码：              │
│                  │            │   ```tsx                     │
│                  │            │   export const routes = ...  │
│                  │            │   ```                        │
│                  │            │   运行: pnpm exec tsc        │
│                  │            │   预期: 无错误                │
└──────────────────┘            └─────────────────────────────┘
粗粒度，描述"做什么"            精细粒度，描述"怎么做每一步"

选择建议：

• 只有 tasks.md 就够 → 组合 1 或 2
• 需要精确控制每一步 → 先 writing-plans 再执行 → 组合 3、4、5

Q: executing-plans 和 subagent-driven-dev 怎么选？

Q: 中断后有些代码写了一半怎么办？

git 状态就是证据：

• 有 commit → task 已完成，tasks.md 应该已打勾
• 有未 commit 的改动 → task 做了一半，新对话中让 AI 检查 git diff 后继续

Q: tasks.md 里的任务太粗/太细怎么办？

直接编辑文件。粒度标准：每个 task 能在一次 AI 对话中完成（约 5-15 分钟）。OpenSpec 不锁定制品格式，随时可修改。

Q: 能不能混用组合？

可以。例如前 3 个简单 task 用组合 1 直接做，后面复杂的 task 切到组合 2 用 subagent。OpenSpec 的 tasks.md 是唯一进度源，无论哪种组合都通过 checkbox 同步进度。

背景

上个月，我接手了一个新的 NFT 铸造平台前端开发。项目要求很简单：用户点击“连接钱包”按钮，弹出 MetaMask 授权，连接成功后显示用户地址和余额。作为有几年经验的 Web3 开发者，我心想这还不是手到擒来？直接上 ethers.js 这个老伙计，几行代码搞定。于是，我新建了一个 React 组件，信心满满地开始敲代码。没想到，就是这个看似基础的功能，让我在接下来的一天里，跟各种奇怪的报错和边界情况斗智斗勇。

问题分析

我最开始的思路非常直接：在组件挂载时，检查 window.ethereum 是否存在（即用户是否安装了 MetaMask），然后调用 ethereum.request({ method: 'eth_requestAccounts' }) 请求账户授权，最后用 new ethers.providers.Web3Provider(window.ethereum) 创建 provider 来读取链上数据。

第一版代码跑起来，点击按钮，MetaMask 确实弹出来了，授权也很顺利。控制台打印出了地址，我正准备庆祝，问题就来了。

1. 页面刷新后，登录状态丢失：用户需要重新点击连接。这体验太差了，我们的产品经理第一个不答应。
2. 切换 MetaMask 账户时，前端页面没反应：用户在钱包里换了账号，但我们的网站显示的依然是旧地址。
3. 切换网络时页面卡住：用户从以太坊主网切换到 Polygon，页面有时会卡死，需要手动刷新。

我意识到，我把问题想简单了。一个生产级的钱包连接，不仅仅是“弹出授权框拿到地址”，它必须是一个有状态、能响应变化、并且持久化的连接。我需要监听钱包的各种事件（账户变化、网络变化），并妥善管理这些状态，使其与 React 组件的状态同步。

核心实现

第一步：检测 Provider 与初始化状态

首先，我们不能假设用户一定装了 MetaMask。所以，检测 window.ethereum 是第一步，并且最好在组件生命周期早期进行。

这里有个坑：window.ethereum 的类型在 TypeScript 中是 any 或 unknown。为了更好的类型安全，我将其断言为 ethers.providers.ExternalProvider，但更严谨的做法是使用 ethers 提供的类型工具，或者直接检查必要的方法是否存在。

我决定在自定义 Hook (useWallet) 的初始化阶段完成检测和基础设置。

import { useState, useEffect, useCallback } from 'react';
import { ethers } from 'ethers';

// 声明全局的 ethereum 类型
declare global {
  interface Window {
    ethereum?: ethers.providers.ExternalProvider & {
      isMetaMask?: boolean;
      request: (args: { method: string; params?: any[] }) => Promise<any>;
      on: (event: string, callback: (...args: any[]) => void) => void;
      removeListener: (event: string, callback: (...args: any[]) => void) => void;
    };
  }
}

export const useWallet = () => {
  const [provider, setProvider] = useState<ethers.providers.Web3Provider | null>(null);
  const [signer, setSigner] = useState<ethers.Signer | null>(null);
  const [account, setAccount] = useState<string>('');
  const [chainId, setChainId] = useState<number>(0);
  const [isConnecting, setIsConnecting] = useState(false);
  const [error, setError] = useState<string>('');

  // 初始化：检查是否已连接
  useEffect(() => {
    const checkIfWalletIsConnected = async () => {
      if (!window.ethereum) {
        setError('请安装 MetaMask 钱包扩展！');
        return;
      }

      try {
        // 尝试获取已授权的账户
        const accounts = await window.ethereum.request({
          method: 'eth_accounts',
        });
        if (accounts.length > 0) {
          // 如果已有授权账户，直接初始化 provider 和 signer
          await initProviderAndSigner(accounts[0]);
        }
        // 获取当前网络ID
        const chainIdHex = await window.ethereum.request({ method: 'eth_chainId' });
        setChainId(parseInt(chainIdHex, 16));
      } catch (err) {
        console.error('初始化检查钱包连接失败:', err);
      }
    };

    checkIfWalletIsConnected();
  }, []);
}

eth_accounts 这个方法是关键，它不会弹出授权框，而是静默返回已被当前 DApp 授权的账户列表。如果列表不为空，说明用户之前已经连接过，我们可以直接恢复状态。这是解决“刷新后状态丢失”问题的核心。

第二步：实现连接与断开功能

连接功能就是主动弹出授权请求。这里要注意错误处理，特别是用户拒绝授权的情况。

const connectWallet = useCallback(async () => {
  if (!window.ethereum) {
    setError('请安装 MetaMask 钱包扩展！');
    return;
  }

  setIsConnecting(true);
  setError('');
  try {
    // 1. 请求账户授权，这会弹出 MetaMask 窗口
    const accounts = await window.ethereum.request({
      method: 'eth_requestAccounts',
    });
    // 2. 用获取到的第一个账户初始化
    await initProviderAndSigner(accounts[0]);
    // 3. 获取当前网络
    const chainIdHex = await window.ethereum.request({ method: 'eth_chainId' });
    setChainId(parseInt(chainIdHex, 16));
  } catch (err: any) {
    // 用户拒绝授权是最常见的错误
    if (err.code === 4001) {
      setError('您拒绝了钱包连接请求。');
    } else {
      setError(`连接失败: ${err.message}`);
    }
    console.error('连接钱包失败:', err);
  } finally {
    setIsConnecting(false);
  }
}, []);

const disconnectWallet = useCallback(() => {
  // 注意：ethers.js 和 MetaMask 没有真正的“断开连接”API。
  // 所谓的断开，只是清除我们本地应用的状态。
  setProvider(null);
  setSigner(null);
  setAccount('');
  setChainId(0);
  setError('');
  // 在实际项目中，你可能还需要清除 localStorage/SessionStorage 中的相关状态
}, []);

这里有个大坑：很多新手（包括当时的我）会寻找 disconnect 或 logout 方法。但实际上，MetaMask 的权限模型是“一次授权，持续有效”，直到用户在其钱包界面手动移除站点权限。所以前端的“断开”只是前端自己清空状态，下次用 eth_accounts 检查时，如果用户没移除权限，还是会拿到地址。这是一个重要的认知点。

第三步：监听钱包事件（关键！）

这是让应用“活”起来，响应外部变化的核心。我们需要监听 accountsChanged 和 chainChanged 事件。

// 初始化 provider 和 signer 的辅助函数
const initProviderAndSigner = useCallback(async (accountAddress: string) => {
  if (!window.ethereum) return;
  // 创建 Provider
  const web3Provider = new ethers.providers.Web3Provider(window.ethereum);
  setProvider(web3Provider);
  // 创建 Signer
  const web3Signer = web3Provider.getSigner();
  setSigner(web3Signer);
  setAccount(accountAddress);
}, []);

// 设置事件监听
useEffect(() => {
  if (!window.ethereum) return;

  const handleAccountsChanged = (accounts: string[]) => {
    console.log('accountsChanged 事件触发:', accounts);
    if (accounts.length === 0) {
      // 用户在所有界面断开了连接，或者切换到了一个没有权限的账户
      disconnectWallet();
      setError('请连接您的钱包账户。');
    } else if (accounts[0] !== account) {
      // 用户切换了账户
      initProviderAndSigner(accounts[0]);
    }
  };

  const handleChainChanged = (_chainId: string) => {
    // 注意：chainId 是十六进制字符串
    console.log('chainChanged 事件触发:', _chainId);
    // 当网络切换时，MetaMask 建议刷新页面，因为许多链上数据可能失效。
    // 但为了更好体验，我们可以只重置部分状态并重新获取链ID。
    window.location.reload();
    // 更优雅的做法：不刷新，只更新 chainId 并重新初始化 provider（可能需要新的 RPC 配置）
    // setChainId(parseInt(_chainId, 16));
    // initProviderAndSigner(account); // 重新初始化，因为网络变了
  };

  // 绑定监听器
  window.ethereum.on('accountsChanged', handleAccountsChanged);
  window.ethereum.on('chainChanged', handleChainChanged);

  // 组件卸载时清理监听器，防止内存泄漏
  return () => {
    if (window.ethereum) {
      window.ethereum.removeListener('accountsChanged', handleAccountsChanged);
      window.ethereum.removeListener('chainChanged', handleChainChanged);
    }
  };
}, [account, disconnectWallet, initProviderAndSigner]);

注意这个细节：chainChanged 事件的处理。早期文档和很多教程都建议直接 window.location.reload()，因为网络切换后，旧的 provider 实例可能指向错误的 RPC。虽然刷新简单粗暴，但体验不好。更优的方案是：更新 chainId，然后基于新的 chainId 创建一个新的 provider 实例（如果你配置了多链 RPC 的话）。我这里为了代码清晰，先用了刷新方案。

第四步：获取余额与完善 UI

有了 provider 和 account，获取余额就很简单了。但要注意异步操作和错误处理。

const [balance, setBalance] = useState<string>('0');

// 获取余额的函数
const fetchBalance = useCallback(async () => {
  if (!provider || !account) {
    setBalance('0');
    return;
  }
  try {
    const balanceWei = await provider.getBalance(account);
    // 格式化为 Ether 单位，保留4位小数
    const balanceEth = ethers.utils.formatEther(balanceWei);
    setBalance(parseFloat(balanceEth).toFixed(4));
  } catch (err) {
    console.error('获取余额失败:', err);
    setBalance('0');
  }
}, [provider, account]);

// 当 account 或 provider 变化时，重新获取余额
useEffect(() => {
  fetchBalance();
}, [fetchBalance]);

最后，将这些状态和方法暴露给组件，一个基础但健壮的钱包连接 Hook 就完成了。

完整代码

以下是一个整合了上述所有功能的 React 组件示例：

// WalletConnector.tsx
import React, { useState, useEffect, useCallback } from 'react';
import { ethers } from 'ethers';

declare global {
  interface Window {
    ethereum?: ethers.providers.ExternalProvider & {
      isMetaMask?: boolean;
      request: (args: { method: string; params?: any[] }) => Promise<any>;
      on: (event: string, callback: (...args: any[]) => void) => void;
      removeListener: (event: string, callback: (...args: any[]) => void) => void;
    };
  }
}

const WalletConnector: React.FC = () => {
  const [provider, setProvider] = useState<ethers.providers.Web3Provider | null>(null);
  const [signer, setSigner] = useState<ethers.Signer | null>(null);
  const [account, setAccount] = useState<string>('');
  const [chainId, setChainId] = useState<number>(0);
  const [balance, setBalance] = useState<string>('0');
  const [isConnecting, setIsConnecting] = useState(false);
  const [error, setError] = useState<string>('');

  const initProviderAndSigner = useCallback(async (accountAddress: string) => {
    if (!window.ethereum) return;
    const web3Provider = new ethers.providers.Web3Provider(window.ethereum);
    const web3Signer = web3Provider.getSigner();
    setProvider(web3Provider);
    setSigner(web3Signer);
    setAccount(accountAddress);
  }, []);

  const fetchBalance = useCallback(async () => {
    if (!provider || !account) {
      setBalance('0');
      return;
    }
    try {
      const balanceWei = await provider.getBalance(account);
      const balanceEth = ethers.utils.formatEther(balanceWei);
      setBalance(parseFloat(balanceEth).toFixed(4));
    } catch (err) {
      console.error('获取余额失败:', err);
      setBalance('0');
    }
  }, [provider, account]);

  const connectWallet = useCallback(async () => {
    if (!window.ethereum) {
      setError('请安装 MetaMask 钱包扩展！');
      return;
    }
    setIsConnecting(true);
    setError('');
    try {
      const accounts = await window.ethereum.request({ method: 'eth_requestAccounts' });
      await initProviderAndSigner(accounts[0]);
      const chainIdHex = await window.ethereum.request({ method: 'eth_chainId' });
      setChainId(parseInt(chainIdHex, 16));
    } catch (err: any) {
      if (err.code === 4001) {
        setError('连接请求被拒绝。');
      } else {
        setError(`连接失败: ${err.message}`);
      }
    } finally {
      setIsConnecting(false);
    }
  }, [initProviderAndSigner]);

  const disconnectWallet = useCallback(() => {
    setProvider(null);
    setSigner(null);
    setAccount('');
    setChainId(0);
    setBalance('0');
    setError('');
  }, []);

  // 初始化检查与事件监听
  useEffect(() => {
    if (!window.ethereum) {
      setError('未检测到 Web3 钱包。请安装 MetaMask。');
      return;
    }

    const checkInitialConnection = async () => {
      try {
        const accounts = await window.ethereum!.request({ method: 'eth_accounts' });
        if (accounts.length > 0) {
          await initProviderAndSigner(accounts[0]);
        }
        const chainIdHex = await window.ethereum!.request({ method: 'eth_chainId' });
        setChainId(parseInt(chainIdHex, 16));
      } catch (err) {
        console.error('初始连接检查出错:', err);
      }
    };

    const handleAccountsChanged = (accounts: string[]) => {
      if (accounts.length === 0) {
        disconnectWallet();
        setError('账户已断开。');
      } else if (accounts[0] !== account) {
        initProviderAndSigner(accounts[0]);
      }
    };

    const handleChainChanged = (_chainId: string) => {
      // 简单处理：刷新页面
      window.location.reload();
    };

    checkInitialConnection();

    window.ethereum.on('accountsChanged', handleAccountsChanged);
    window.ethereum.on('chainChanged', handleChainChanged);

    return () => {
      window.ethereum?.removeListener('accountsChanged', handleAccountsChanged);
      window.ethereum?.removeListener('chainChanged', handleChainChanged);
    };
  }, [account, disconnectWallet, initProviderAndSigner]);

  // 余额监听
  useEffect(() => {
    fetchBalance();
  }, [fetchBalance]);

  return (
    <div style={{ padding: '20px', border: '1px solid #ccc', borderRadius: '8px' }}>
      <h2>钱包连接状态</h2>
      {error && <p style={{ color: 'red' }}>错误: {error}</p>}
      
      {!account ? (
        <button onClick={connectWallet} disabled={isConnecting}>
          {isConnecting ? '连接中...' : '连接 MetaMask'}
        </button>
      ) : (
        <div>
          <p><strong>连接地址:</strong> {`${account.substring(0, 6)}...${account.substring(account.length - 4)}`}</p>
          <p><strong>网络 ID:</strong> {chainId}</p>
          <p><strong>余额:</strong> {balance} ETH</p>
          <button onClick={disconnectWallet} style={{ marginTop: '10px' }}>
            断开连接（前端）
          </button>
          <p style={{ fontSize: '0.8em', color: '#666', marginTop: '5px' }}>
            （注：需在 MetaMask 中移除站点权限才能完全断开）
          </p>
        </div>
      )}
      
      <div style={{ marginTop: '20px', fontSize: '0.9em', color: '#333' }}>
        <p>试试以下操作，观察页面变化：</p>
        <ul>
          <li>在 MetaMask 中切换账户</li>
          <li>在 MetaMask 中切换网络（如 Goerli 测试网）</li>
          <li>刷新页面</li>
        </ul>
      </div>
    </div>
  );
};

export default WalletConnector;

踩坑记录

1. window.ethereum 类型错误：在 TypeScript 中直接使用 window.ethereum 会报类型错误。我一开始用 (window as any).ethereum 粗暴解决，后来发现这不利于代码维护。最终通过扩展 global 接口提供了更精确的类型定义，并检查必要方法是否存在。
2. accountsChanged 事件在断开时触发空数组：我最初只监听新账户，没处理 accounts.length === 0 的情况。导致用户在 MetaMask 里断开连接后，我的应用界面还显示着旧地址。加上这个判断后，体验才正常。
3. 网络切换后 Provider 失效：这是我遇到最棘手的问题。用户切换网络后，旧的 provider 实例发出的请求可能仍发往旧的 RPC 节点，导致各种 UNSUPPORTED_OPERATION 或网络错误。我尝试过在 chainChanged 事件里创建新的 provider，但有时会碰到异步时序问题。最后，对于这个简单 demo，我采用了 MetaMask 官方早期文档推荐的页面刷新方案。在真实复杂项目中，需要结合项目状态管理库（如 Redux、Zustand）和自定义的多链 RPC 配置来更优雅地处理。
4. 余额显示单位问题：provider.getBalance() 返回的是 BigNumber 类型的 wei 单位。直接 toString() 会显示一长串数字。必须用 ethers.utils.formatEther() 进行单位转换。同时要注意转换后的精度显示，避免出现过多小数位。

小结

这次折腾让我彻底明白，一个稳定的钱包连接不仅仅是调用一个 API，而是一个需要持续维护状态、监听外部事件、并妥善处理各种边界情况的完整功能模块。虽然现在有 wagmi、RainbowKit 这样优秀的封装库，但理解其底层原理，亲手用 ethers.js 实现一遍，对于排查复杂问题和构建定制化需求依然至关重要。下一步，我可以在此基础上集成多链支持、钱包连接缓存（localStorage）以及更优雅的网络切换处理逻辑。

一、AI 编程的"甜蜜陷阱"

随着 AI 编程助手日趋智能，开发者往往在"无需动脑、不用写文档"的诱惑下上手，但随之而来的是输出无序、需求跑偏、维护困难等隐患——这正是所谓的"甜蜜陷阱"。

二、规范驱动开发

以"明确做什么、为什么做"为前提，引入结构化规范文档，让 AI 从"规范"而非零散提示中读取需求，从而输出更可控、更易维护的代码。

三、为什么选用 OpenSpec

OpenSpec 是一款轻量、灵活的 AI 辅助开发规范工具，具有以下核心优势：

• 轻量灵活：无刚性阶段门，随时迭代，避免繁文缛节
• 工具自由：支持 20+ AI 编码助手（如 Claude Code、Cursor、Windsurf 等）
• 可预测性：标准化文档模板，减少返工
• 组织有序：每个变更独立文件夹，便于管理与追溯

项目地址：gitcn.org/projects/10…

四、不用 spec 与用 OpenSpec 的对比

五、快速开始

5.1 安装要求

系统要求：Node.js 20.19.0+

# 全局安装
npm install -g @fission-ai/openspec@latest

# 或使用 pnpm / yarn / bun
pnpm add -g @fission-ai/openspec
yarn global add @fission-ai/openspec
bun install -g @fission-ai/openspec

5.2 初始化项目

# 进入项目目录
cd your-project

# 初始化 OpenSpec
openspec init

示例交互（向 AI 请求 config.yaml）：

我是项目新手，请帮我写 @openspec/config.yaml 一份标准可直接使用的配置文件。
项目说明：

• 类型：ELN/FCM 设备数据采集程序
• 语言：C#
• 内容：多设备通信、数据采集、协议解析、日志、配置、调试
  要求：YAML 语法正确、有中文注释、包含项目元信息、模块划分、阶段管理、文档归档、任务管理、AI 辅助……

5.3 配置工作流

默认模式（Core Profile）：4 个核心命令

扩展模式（Expanded Profile）：更多命令

# 切换到扩展模式
openspec config profile expanded
openspec update

六、OPSX 工作流详解

6.1 核心理念

以"行动"为中心，文档赋能但非强制，支持随时创建、实现、更新、归档。

6.2 核心工作流（Core Profile）

步骤 1：探索想法（可选）

/opsx:explore 如何为移动应用处理认证

步骤 2：创建变更

/opsx:propose add-dark-mode

自动生成文件结构：

openspec/changes/add-dark-mode/
├── proposal.md
├── specs/
├── design.md
└── tasks.md

步骤 3：实现任务

/opsx:apply

步骤 4：归档

/opsx:archive

6.3 扩展工作流（Expanded Profile）关键操作

七、项目配置

7.1 配置文件（openspec/config.yaml）示例

# openspec/config.yaml
context: |
  团队：后端组
  代码审查：至少 2 人批准
  部署：自动 CI/CD
  监控：Datadog 告警

rules:
  proposal:
    - 包含产品负责人批准
    - 识别依赖团队
  design:
    - 架构审查会议记录
    - 性能基准测试计划

八、文档模板参考

8.1 变更提案（proposal.md）

# 变更提案：{功能名称}

## 问题陈述
描述当前存在的问题或需求背景。

## 目标
明确变更要达成的目标（可衡量）。

## 范围
- 包含：需要实现的功能点
- 不包含：明确排除的内容

## 风险与回滚计划
- 潜在风险：列举可能的风险
- 回滚计划：风险发生时的回滚方案

8.2 需求规范（specs/）

• 场景描述、验收标准
• 推荐使用 Given/When/Then 格式

8.3 设计文档（design.md）

• 架构设计
• 接口定义
• 数据设计
• 安全与性能

8.4 实现任务（tasks.md）

# 实现任务：{功能名称}

## 任务列表

### 任务 1：组件开发
- [ ] 1.1 创建主题上下文提供者
  - 文件：src/context/ThemeContext.tsx
  - 测试：src/context/ThemeContext.test.tsx

## 完成标准
- [ ] 所有任务完成
- [ ] 测试通过
- [ ] 代码审查通过

九、命令参考

9.1 Core Profile

9.2 Expanded Profile

十、最佳实践

10.1 文档编写

• 注入项目上下文，保持简洁
• AI 初稿后人工审查
• 使用 Given/When/Then 编写场景
• 功能完成后及时归档

10.2 工作流选择

10.3 模型选择

推荐使用高推理能力模型：

• Claude Opus 4.5
• GPT-5.2

十一、团队协作

11.1 团队流程

产品经理 → 提案 → 技术负责人审查 → 开发实现 → 测试验证 → 归档

11.2 审查清单

提案审查：

• 问题陈述清晰
• 目标可衡量
• 范围明确
• 风险与回滚方案完整

设计审查：

• 架构合理
• 接口定义清晰
• 安全考虑充分
• 性能目标明确

十二、与 AI 工具集成

12.1 支持工具

支持 20+ 编码助手，包括：Claude Code、Cursor、Windsurf、Codex 等。

12.2 技能文件示例

---
name: openspec-propose
description: Create a new OpenSpec change proposal
---
# OpenSpec Propose Skill
# ... 技能内容

12.3 提示词技巧

十三、更新与维护

13.1 更新 OpenSpec

npm install -g @fission-ai/openspec@latest
openspec update

13.2 版本兼容

13.3 退出遥测

export OPENSPEC_TELEMETRY=0
export DO_NOT_TRACK=1

十四、故障排查

14.1 常见问题

14.2 性能优化（大项目）

openspec sync --incremental
openspec bulk-archive --before 2026-01-01

十五、总结

15.1 核心价值

• 可预测性：规范驱动，减少 AI 输出偏差
• 组织性：每个变更独立管理，清晰可追溯
• 灵活性：无强制流程，按需使用
• 工具自由：支持主流 AI 编码助手
• 轻量级：学习成本低，快速上手

15.2 适用场景

15.3 快速上手步骤

# 1. 安装
npm install -g @fission-ai/openspec

# 2. 初始化
openspec init

# 3. 创建第一个变更
/opsx:propose your-feature

加入社区：discord.gg/YctCnvvshC

参考资料

本文基于 OpenSpec v2.x 编写，功能与命令可能随版本更新而变化，请参考官方文档获取最新信息。

深入理解 HTTP 协议（含 Cookie 与 JWT）

1. 为什么需要 HTTP？

在 Web 环境中，客户端（如浏览器）与服务器需要交换信息。若没有统一规则，不同厂商的软件无法互操作。HTTP（HyperText Transfer Protocol，超文本传输协议）定义了：

• 请求的格式（方法、路径、头部、正文）
• 响应的格式（状态码、头部、正文）
• 资源定位方式（URL）
• 连接管理、缓存控制、状态保持等机制

简单来说：HTTP 是浏览器与服务器之间约定的“通信语言”，确保双方能准确理解对方意图。

2. HTTP 版本演进

每个新版本都在解决前一版本的核心瓶颈。

3. HTTP 报文结构

3.1 请求报文

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 18

{"name":"Alice"}

组成：

• 请求行：方法、请求目标、HTTP版本
• 头部字段：键值对
• 空行：分隔头部与正文
• 消息正文：可选

3.2 响应报文

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 27

{"id":1,"name":"Alice"}

组成：

• 状态行：HTTP版本、状态码、原因短语
• 头部字段、空行、正文（同上）

4. HTTP 方法（动作语义）

语义核心：GET 用于读取，POST 用于创建，PUT/PATCH 用于更新，DELETE 用于删除。

5. HTTP 状态码分类

速记：2xx 成功，3xx 去别处，4xx 你错了，5xx 它错了。

6. HTTPS 的安全机制

HTTP 是明文传输，存在窃听、篡改、冒充三大风险。HTTPS = HTTP + TLS/SSL，在 TCP 与 HTTP 之间增加安全层。

结论：HTTPS 比 HTTP 多了加密、认证、完整性保护三层机制。

7. HTTP 缓存机制

缓存可减少重复请求，提升性能。分为两类：

优先级：Cache-Control > Expires；服务器通常优先验证ETag，再验证 Last-Modified

流程图如下：

8. 一次完整的 HTTP 事务

从输入 URL 到页面展示（HTTP 相关部分）：

1. DNS 解析：域名 → IP 地址。
2. TCP 连接：三次握手建立连接。
3. 发送请求：浏览器构建 HTTP 请求报文，通过 TCP 发送。
4. 服务器处理：解析请求，执行逻辑，生成响应。
5. 返回响应：服务器发送 HTTP 响应报文。
6. 浏览器处理： 拿到 HTML 后开始关键渲染。
7. 连接管理：若 Connection: keep-alive，连接保持；否则关闭连接。

若为 HTTPS，则在 TCP 连接后增加 TLS 握手（证书验证、密钥协商）。

完整流程如下图：

HTTP 事务完成后，浏览器进入渲染流程（详见《深入理解浏览器渲染流程》），如下图所示：

9. 状态保持机制：Cookie 与 JWT

HTTP 本身是无状态协议——每个请求都是独立的。为了实现登录状态等功能，需要在请求之间传递身份标识。Cookie 和 JWT 是两种主流的解决方案。

9.1 Cookie

Cookie 是服务器通过 Set-Cookie 头部要求浏览器保存的文本。浏览器在后续同源请求中自动携带。

工作流程：

1. 服务器响应：Set-Cookie: sessionId=abc123; Path=/; HttpOnly; Secure
2. 浏览器保存该 Cookie。
3. 后续请求自动携带：Cookie: sessionId=abc123

常用属性：

优点：浏览器自动管理。
缺点：跨域支持复杂，有 CSRF 风险。（攻击者利用你已经在目标网站登录的登录状态，在别的恶意页面里，偷偷替你发起操作请求）

9.2 JWT（JSON Web Token）

JWT 是一种紧凑的令牌格式。服务器登录后返回加密签名字符串，客户端后续请求手动携带。

JWT 结构：xxxxx.yyyyy.zzzzz，三部分组成：

• Header：我是什么类型、用什么算法
• Payload：我带了什么数据（公开可见）
• Signature：我没被篡改（服务器密钥保证）

工作流程：

1. 用户登录，服务器验证成功后生成 JWT 并返回。
2. 客户端保存 JWT（通常存于 localStorage）。
3. 客户端在后续请求头部添加：Authorization: Bearer <JWT>
4. 服务器验证签名，读取用户信息。

优点：

• 无状态，易于水平扩展。
• 跨域友好。
• 自包含用户信息。

缺点：

• 无法主动注销（过期前始终有效）。
• 体积较大。
• 存于 localStorage 时易受 XSS 攻击。

9.3 Cookie vs JWT 对比

10. 跨域（CORS）

10.1 为什么会有跨域？

浏览器的同源策略（Same-Origin Policy）限制：协议、域名、端口三者任意一个不同，即为跨域。同源策略的目的是防止恶意脚本读取其他网站的数据（如窃取 Cookie、劫持登录状态）。

10.2 跨域解决方案

10.3 CORS 核心响应头

10.4 预检请求（OPTIONS）

什么是预检请求？

预检请求是在跨域的前提下，浏览器在发送非简单请求前，自动发起的一个 OPTIONS 请求，用于询问服务器是否允许实际请求。代码中无需手动编写。

简单请求 vs 非简单请求

注：application/x-www-form-urlencoded 是默认的普通表单类型，multipart/form-data 用于带文件上传的表单，text/plain 为纯文本格式；application/json 用来发送 JSON 格式数据，它不属于传统表单类型，是 Ajax 常用格式，属于非简单请求。

11. 总结

HTTP 定义了请求与响应的格式、方法、状态码、缓存规则。它本身无状态，因此引入 Cookie 和 JWT 维持用户状态。跨域问题由浏览器的同源策略引起，CORS 是标准的解决方案，其中预检请求用于保护非简单跨域请求的安全性。理解这些概念，就能处理跨域、缓存、安全、登录态管理等前端核心问题。

前端登录菜单加载性能优化总结

问题现象

登录后页面出现明显卡顿，接口返回约 900 条菜单权限数据，数据量不大但前端处理耗时明显，主线程被阻塞。

瓶颈分析

整个调用链路：获取菜单接口 → 扁平数组转树形结构 → 存储菜单状态 → 解析路由和权限

排查后发现有两处性能问题：

瓶颈一：扁平数组转树形结构 — O(N²) 复杂度

问题：内层递归函数对每个节点都遍历整个剩余数组查找子节点，加上 Array.splice() 从数组中间删除元素，整体时间复杂度为 O(N²)。

// 原实现（简化）
function arrayToTree(parent, level) {
  var k = list.length - 1;
  while (k >= 0) {
    if (parent.id === list[k].pid) {
      children.push(list[k]);
      list.splice(k, 1);        // O(N) 删除
      arrayToTree(list[k], level + 1); // 递归后又从头遍历
    }
    k--;
  }
}

优化：一次遍历建立 pid → children[] 的 Map 索引，递归时通过 Map 直接查找子节点，时间复杂度降为 O(N)。

// 优化后
var childrenMap = {};
items.forEach(function (item) {
  var pid = item[option.pid].toString();
  if (!childrenMap[pid]) childrenMap[pid] = [];
  childrenMap[pid].push(item);
});

function buildTree(parent, level) {
  var children = childrenMap[parent[option.id].toString()];
  if (!children) return;
  // 直接通过 Map 拿到子节点，无需遍历整个数组
}

瓶颈二：循环内反复触发框架级 API（动态路由注册 + 状态更新）

问题：这是最主要的瓶颈。递归遍历 900 个节点时，每遇到符合条件的节点就同步调用：

1. router.addRoute() — 每次调用都会触发路由匹配器重新编译，N 次调用相当于 O(N²) 的编译开销
2. store.commit() — 每次提交都用扩展运算符 [...oldArr, ...newArr] 创建新数组，随着累积数组越来越大，开销递增

// 原实现（简化）
data.reduce((pre, cur) => {
  // 每个节点都触发一次框架 API
  router.addRoute('layout', { ... });     // 重建路由匹配表
  store.commit('UPDATE_MENU', { ... });   // 展开合并数组
  if (cur.children.length) traverse(cur.children, ...);
}, []);

优化：先收集，后批量操作。遍历过程中只往普通数组/对象中 push 数据，遍历完成后统一执行副作用。

// 优化后
var pendingRoutes = [];
var pendingMenus = {};

function collect(data, ...) {
  // 遍历中只收集数据，不调用框架 API
  pendingRoutes.push({ ... });
  pendingMenus[key] = (pendingMenus[key] || []).concat(items);
}

collect(data, ...);

// 遍历完成后批量添加路由
pendingRoutes.forEach(route => router.addRoute('layout', route));

// 一次性合并菜单数据到状态树
Object.keys(pendingMenus).forEach(key => { ... });

优化效果

经验教训

1. 数据量不大 ≠ 不会慢：几百条数据看似不多，但 O(N²) 算法 + 循环内触发框架重计算，开销会被成倍放大
2. 注意框架 API 的隐性成本：router.addRoute 不是简单的数组 push，每次调用都有路由匹配器重编译的开销；store.commit 如果涉及数组展开合并，高频调用同样代价不小。应避免在循环中高频调用这类 API
3. 先收集后批量是处理这类问题的通用模式：把"遍历"和"副作用"分离，遍历阶段只做纯数据收集，副作用（路由注册、状态提交、DOM 操作等）统一在最后批量执行

最近在改老项目，将webpack迁移到vite提高下速度 首先来看下默认静态加载路由，我们只需要在router/index.js直接配置好就可以了

当然默认的情况 component: () => import('../views/HomeView.vue') 是这样的如果需要用@替代..需要在在vite.config.js中增加下配置

resolve: {
    alias: {
        '@': path.resolve(__dirname, 'src')
    }
},

在webpack中动态加载使用如下，就可以了

export const loadView = (view) => {
  if (process.env.NODE_ENV === 'development') {
    return (resolve) => require([`@/views/${view}`], resolve)
  } else {
    // 使用 import 实现生产环境的路由懒加载
    return () => import(`@/views/${view}`)
  }
}

但是在vite中语法就变了，require() 是 CommonJS 语法，Vite 不支持，需要用import.meta.glob来实现，下面是相对路径使用，相对路径使用要注意当前方法引入对应根目录的层级

//代码文件顶部增加
const modules = import.meta.glob('../views/**/*')
//然后定义loadView 方法
export const loadView = (view) => {
    return modules[`../views/${viewPath}.vue`]  // 使用相对路径
}

在这里比较推荐使用相对路径来实现

//代码文件顶部增加
const modules = import.meta.glob('/src/views/**/*')
export const loadView = (view) => {
    return modules[`/src/views/${viewPath}.vue`]  // 使用绝对路径
}

说明一下如果从后端获取的动态组件路径是带.vue文件名字的可以忽略

最后又完善了一下增加了一些模糊匹配规则

/src/views/${viewName}.vue
/src/views/${viewName}/index.vue
/src/views/${viewName}/${viewName}.vue

完整的loadView 方法

export const loadView = (view) => {
    // 统一处理：无论后端是否带 .vue，都确保有后缀
    const viewName = view.replace(/\.vue$/, '')
    const possiblePaths = [
        `/src/views/${viewName}.vue`,
        `/src/views/${viewName}/index.vue`,
        `/src/views/${viewName}/${viewName}.vue`,
    ]

    for (const path of possiblePaths) {
        // const loader = modules[path]
        if (modules[path]) {
            console.log('✅ 匹配组件:', path)
            return modules[path]
        }
    }
    console.error(`未找到页面组件: ${viewName}`)
    console.log('可用页面组件:', Object.keys(modules))
    return null
}

演示demo

原文 www.liweiliang.com/1204.html

Python 基础知识点技术说明文档

概述

本文档总结了 Python 编程中的核心概念，包括自定义迭代器、生成器、高阶函数、装饰器、上下文管理器、异常处理和异步编程。这些知识点是构建企业级应用的基石。

1. 自定义迭代器

定义

自定义迭代器需要实现 __iter__() 和 __next__() 方法。__iter__() 方法返回迭代器对象本身，而 __next__() 方法返回下一个元素，如果没有更多元素可供迭代，则抛出 StopIteration 异常。

示例代码

print("使用自定义迭代器:")
class MyIterator:
    def __init__(self, start, end):
        self.current = start
        self.end = end

    def __iter__(self):
        return self

    def __next__(self):
        if self.current >= self.end:
            raise StopIteration
        self.current += 1
        return self.current - 1

for num in MyIterator(0, 3):
    print(num)  # 输出 0, 1, 2

应用场景

• 自定义数据流处理，如分页数据加载。
• 企业级：大数据处理框架中的自定义数据源。

2. 生成器函数和表达式

生成器函数

生成器函数使用 yield 关键字来生成一个迭代器，每次调用 next() 时会从上次 yield 的位置继续执行，直到遇到 StopIteration 异常。

示例代码

print("\n使用生成器函数:")
def my_generator(start, end):
    current = start
    while current < end:
        yield current
        current += 1
for num in my_generator(0, 3):
    print(num)  # 输出 0, 1, 2

生成器表达式

生成器表达式是一种简洁的语法，用于创建生成器对象。它类似于列表推导式，但使用圆括号而不是方括号。

print("\n使用生成器表达式:")
squares = (x**2 for x in range(5))
for square in squares:
    print(square)  # 输出 0, 1, 4, 9, 16

应用场景

• 内存高效处理大数据集。
• 企业级：流式数据处理、日志分析。

3. 高阶函数

主要函数

• map(func, iterable): 对每个元素应用函数。
• reduce(func, iterable): 累积计算。
• filter(func, iterable): 筛选元素。
• zip(*iterables): 打包多个可迭代对象。
• enumerate(iterable): 添加索引。
• sorted(iterable): 排序（不修改原列表）。
• reversed(iterable): 反转。
• all(iterable): 所有元素为真。
• any(iterable): 至少一个元素为真。

示例代码

print("\n1. map() 函数:")
squared = map(lambda x: x**2, range(5)) # range(5) 生成一个迭代器，包含 0, 1, 2, 3, 4
print(list(squared))  # 输出 [0, 1, 4, 9, 16]

print("\n2. reduce() 函数:")
from functools import reduce
product = reduce(lambda x, y: x * y, range(1, 5)) # range(1, 5) 生成一个迭代器，包含 1, 2, 3, 4
print(product)  # 输出 24 (1*2*3*4)

print("\n3. filter() 函数:")
even_numbers = filter(lambda x: x % 2 == 0, range(10))
print(list(even_numbers))  # 输出 [0, 2, 4, 6, 8]

print("\n4. zip() 函数:")
list1 = [1, 2, 3]
list2 = ['a', 'b', 'c']
zipped = zip(list1, list2)
print(list(zipped))  # 输出 [(1, 'a'), (2, 'b'), (3, 'c')]
list3 = ['apple', 'banana']
list4 = ['Apple', 'Banana']
zipped_case = zip(list3, list4) # 输出 [('apple', 'Apple'), ('banana', 'Banana')]

# 如何输出[{apple:Apple}, {banana:Banana}]
zipped_case_dict = {k: v for k, v in zipped_case}
print(zipped_case_dict)  # 输出 {'apple': 'Apple', 'banana': 'Banana'}

print("\n5. enumerate() 函数:")
items = ['apple', 'banana', 'cherry']
for index, item in enumerate(items):
    print(index, item)  # 输出 0 apple, 1 banana, 2 cherry
    
print("\n6. sorted() 函数:")
numbers = [3, 1, 4, 1, 5]
sorted_numbers = sorted(numbers)
print(sorted_numbers)  # 输出 [1, 1, 3, 4, 5]
print(numbers)  # 输出 [3, 1, 4, 1, 5] (原列表未被修改)

print("\n7. reversed() 函数:")
numbers = [1, 2, 3, 4, 5]
reversed_numbers = reversed(numbers)
print(list(reversed_numbers))  # 输出 [5, 4, 3, 2, 1]

print("\n8. all() 函数:")
values = [True, True, False]
print(all(values))  # 输出 False
values = [True, True, True]
print(all(values))  # 输出 True

print("\n9. any() 函数:")
values = [False, False, False]
print(any(values))  # 输出 False
values = [False, True, False]
print(any(values))  # 输出 True

应用场景

• 函数式编程风格。
• 企业级：数据转换、聚合计算。

4. 装饰器

定义

装饰器是一种函数，它接受一个函数作为参数，并返回一个新的函数。装饰器可以用来修改或增强原函数的行为，而不需要修改原函数的代码。

示例代码

print("\n使用装饰器:")
def decorator(func):
    def wrapper(*args, **kwargs):
        print("这是装饰器的前置操作")
        result = func(*args, **kwargs)
        print("这是装饰器的后置操作")
        return result
    return wrapper
@decorator
def say_hello(name):
    print(f"Hello, {name}!")
say_hello("Alice")  # 输出装饰器的前置操作, Hello, Alice!, 装饰器的后置操作

企业级应用场景

• 日志记录：自动记录函数调用。
• 权限验证：检查用户权限。
• 性能监控：测量执行时间。
• 缓存：缓存结果。
• 重试机制：失败时重试。

5. 上下文管理器

定义

上下文管理器是一种对象，它定义了 enter() 和 exit() 方法，可以在 with 语句中使用。上下文管理器可以用来管理资源的获取和释放，例如文件操作、数据库连接等。

示例代码

print("\n使用上下文管理器:")
class MyContextManager:
    def __enter__(self):
        print("进入上下文管理器")
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        print("退出上下文管理器")
with MyContextManager() as manager:
    print("在上下文管理器中执行操作")

企业级应用场景

• 文件操作：自动关闭文件。
• 数据库连接：自动提交/回滚。
• 锁管理：自动释放锁。
• 网络连接：管理连接池。
• 临时资源：自动清理。

6. 异常处理

语法

异常处理是指在程序运行过程中捕获和处理错误，以避免程序崩溃。Python 使用 try-except 语句来进行异常处理。

示例代码

print("\n使用异常处理:")
try:
    result = 10 / 0  # 这会引发 ZeroDivisionError 异常
except ZeroDivisionError as e:
    print("捕获到异常:", e)

应用场景

• 错误恢复和日志记录。
• 企业级：健壮的错误处理策略。

7. 异步和协程

定义

异步编程是一种编程范式，它允许程序在等待某些操作完成时继续执行其他任务。Python 使用 async 和 await 关键字来实现异步编程. 处理高并发 I/O 任务的黄金标准库是 asyncio，它提供了一个事件循环和一套用于编写异步代码的工具。

示例代码

import asyncio
print("\n使用异步和协程:")
async def fetch_data(id):
    print(f"获取数据 {id} 开始")
    await asyncio.sleep(1)  # 模拟非阻塞的异步 I/O 操作
    print(f"获取数据 {id} 结束")
    return {"id": id, "data": "dummy"}

async def main():
    # 并发执行多个任务
    results = await asyncio.gather(
        fetch_data(1),
        fetch_data(2),
        fetch_data(3)
    )
    print(results)

asyncio.run(main())

应用场景

• 高并发 I/O 任务，如网络请求、文件 I/O。
• 企业级：Web 服务器、API 客户端、实时数据处理。

总结

直接硬吃干货

一个基于 Vue 2 和 Ant Design Vue 1.x 的可视化组件装修工具，支持拖拽排序、属性编辑和实时预览。

• github地址

功能特性

• 📱 移动端预览：支持自定义尺寸的移动端预览界面
• 🎨 组件编辑：实时编辑组件属性，所见即所得
• 📦 组件库：可扩展的组件库系统
• 🎯 拖拽排序：支持组件的拖拽排序功能
• 🔧 尺寸调整：可自定义预览区域尺寸，保持等比例缩放

技术栈

• Vue 2
• Ant Design Vue 1.x
• vuedraggable

目录结构

src/
├── components/
│   └── DecorationBuilder/          # 装修工具主目录
│       ├── bases/                  # 基础组件
│       │   ├── Editor/             # 属性编辑器
│       │   ├── Preview/            # 移动端预览组件
│       │   │   ├── components/     # 预览组件的子组件
│       │   │   │   ├── BrowserToolbar/ # 浏览器工具栏
│       │   │   │   └── SizeEditor/     # 尺寸编辑器
│       │   └── Selector/           # 组件选择器
│       ├── config/                 # 配置文件
│       │   ├── componentTypes.js   # 组件类型定义
│       │   └── settings.js         # 全局设置
│       ├── widgets/                # 自定义组件
│       │   ├── Banner/             # 轮播图组件
│       │   ├── News/               # 新闻列表组件
│       │   └── index.js            # 组件注册表
│       └── index.vue               # 装修工具主入口
└── utils/
    ├── componentUtils.js           # 组件相关工具函数
    └── index.js                    # 通用工具函数

graph TD
    A[DecorationBuilder] --> B[bases]
    A --> C[config]
    A --> D[widgets]
    A --> E[index.vue]
    
    B --> F[Editor]
    B --> G[Preview]
    B --> H[Selector]
    
    G --> I[components]
    I --> J[BrowserToolbar]
    I --> K[SizeEditor]
    
    C --> L[componentTypes.js]
    C --> M[settings.js]
    
    D --> N[Banner]
    D --> O[News]
    D --> P[index.js]

核心组件说明

1. DecorationBuilder (主入口)

• 文件：src/components/DecorationBuilder/index.vue
• 功能：整合预览、编辑器和选择器组件，管理组件数据和交互逻辑

2. Preview (预览组件)

• 文件：src/components/DecorationBuilder/bases/Preview/index.vue
• 功能：展示移动端预览界面，支持组件拖拽排序
• 子组件：
  • BrowserToolbar：浏览器工具栏，包含预览、添加组件、发布等功能
  • SizeEditor：尺寸编辑器，用于调整预览区域大小

3. Editor (属性编辑器)

• 文件：src/components/DecorationBuilder/bases/Editor/index.vue
• 功能：动态加载组件编辑器，允许编辑组件属性

4. Selector (组件选择器)

• 文件：src/components/DecorationBuilder/bases/Selector/index.vue
• 功能：展示所有可用组件，支持选择组件添加到预览区

配置文件说明

componentTypes.js

• 定义组件类型枚举和元数据
• 包含组件的显示名称、描述、图标等信息

export const COMPONENT_TYPES = {
  BANNER: 'banner',          // 轮播图
  NEWS_LIST: 'news-list'     // 新闻列表
}

export const COMPONENT_METADATA = {
  [COMPONENT_TYPES.BANNER]: {
    name: '轮播图',
    description: '支持多张图片轮播展示',
    icon: 'picture',
    category: '基础组件'
  }
  // ...
}

settings.js

• 全局配置文件，包含预览设置等

export const PREVIEW_SETTINGS = {
  MOBILE_WIDTH: 375,         // 默认移动端宽度
  MOBILE_HEIGHT: 812         // 默认移动端高度
}

组件工具函数

文件：src/utils/componentUtils.js

主要功能：

• getComponentMetadata()：获取组件元数据
• getAllComponentTypes()：获取所有组件类型
• getWidgetConfig()：获取组件配置
• getWidgetDefaultProps()：获取组件默认属性
• getWidgetPreview()：获取预览组件
• getWidgetEditor()：获取编辑组件

组件映射关系

数据格式说明

标准组件数据格式

[
  {
    "id": "1234567890",
    "type": "banner",
    "props": {
      "images": [
        { "url": "https://example.com/image1.jpg", "link": "" },
        { "url": "https://example.com/image2.jpg", "link": "" }
      ],
      "autoPlay": true,
      "interval": 3000,
      "dots": true,
      "arrows": false
    }
  },
  {
    "id": "0987654321",
    "type": "news-list",
    "props": {
      "title": "最新资讯",
      "news": [
        { "id": 1, "title": "新闻标题1", "date": "2026-04-16", "link": "" },
        { "id": 2, "title": "新闻标题2", "date": "2026-04-17", "link": "" }
      ],
      "showDate": true,
      "showArrow": true,
      "maxItems": 5
    }
  }
]

字段说明

• id：组件唯一标识符，由系统自动生成
• type：组件类型，对应 COMPONENT_TYPES 中的值
• props：组件属性，包含所有可配置的参数

数据来源

1. 默认数据：组件的初始默认属性来自各组件的 index.js 文件中的 defaultProps
2. 用户配置：用户在编辑器中修改的属性会覆盖默认属性
3. 保存/发布：最终的组件数据会以标准JSON格式保存或发布

使用方式

• 前端渲染：通过组件类型动态加载对应的预览组件，并传入props进行渲染
• 后端存储：可以将JSON数据存储到后端数据库中
• 页面加载：从后端获取JSON数据后，可以直接传递给DecorationBuilder组件进行渲染

添加新组件指南

以添加一个"轮播的通知公告"组件为例：

1. 创建组件目录和文件

在 src/components/DecorationBuilder/widgets/ 下创建新组件目录：

NotificationBanner/
├── index.js           # 组件配置文件
├── preview.vue        # 预览组件
└── editor.vue         # 编辑组件

2. 编写组件配置文件 (index.js)

import NotificationBannerPreview from './preview.vue'
import NotificationBannerEditor from './editor.vue'
import { COMPONENT_TYPES } from '../../config/componentTypes'

export default {
  type: COMPONENT_TYPES.NOTIFICATION_BANNER,  // 需要在componentTypes.js中定义
  Preview: NotificationBannerPreview,
  Editor: NotificationBannerEditor,
  defaultProps: {
    // 组件默认属性
    notifications: [
      { id: 1, content: '通知内容1' },
      { id: 2, content: '通知内容2' }
    ],
    autoPlay: true,
    interval: 2000
  }
}

3. 编写预览组件 (preview.vue)

<template>
  <div class="notification-banner">
    <!-- 轮播的通知内容 -->
  </div>
</template>

<script>
export default {
  name: 'NotificationBannerPreview',
  props: {
    component: {
      type: Object,
      required: true
    }
  }
}
</script>

<style scoped>
/* 组件样式 */
</style>

4. 编写编辑组件 (editor.vue)

<template>
  <div class="notification-banner-editor">
    <!-- 属性编辑表单 -->
  </div>
</template>

<script>
export default {
  name: 'NotificationBannerEditor',
  props: {
    component: {
      type: Object,
      required: true
    }
  }
}
</script>

5. 注册组件类型

在 src/components/DecorationBuilder/config/componentTypes.js 中添加组件类型：

export const COMPONENT_TYPES = {
  // ... 现有类型
  NOTIFICATION_BANNER: 'notification-banner'  // 新增通知公告类型
}

export const COMPONENT_METADATA = {
  // ... 现有元数据
  [COMPONENT_TYPES.NOTIFICATION_BANNER]: {
    name: '通知公告',
    description: '轮播展示通知内容',
    icon: 'bell',
    category: '基础组件'
  }
}

6. 注册组件

在 src/components/DecorationBuilder/widgets/index.js 中导入并注册新组件：

import BannerComponent from './Banner'
import NewsComponent from './News'
import NotificationBannerComponent from './NotificationBanner'  // 导入新组件

export const widgets = [
  BannerComponent,
  NewsComponent,
  NotificationBannerComponent  // 注册新组件
]

注意事项

1. 所有组件必须遵循相同的命名和目录结构
2. 新组件必须在 componentTypes.js 中定义类型和元数据
3. 预览组件和编辑组件必须正确导出
4. 默认属性应该在组件的 index.js 中定义

NativeWind v4 与 React Native UI Kit 样式隔离指南

1. 问题背景

在 Expo 或 React Native 项目中同时使用 NativeWind v4 和第三方 UI 库（如 react-native-chat-uikit）时，NativeWind 默认的全局注入机制会导致：

• 样式冲突：Tailwind 的基础样式（Preflight）污染 UI 库组件。
• 黑屏/显示异常：NativeWind 运行时尝试接管第三方组件的渲染，或因暗色模式逻辑注入错误的背景变量。

2. 深度隔离方案

第一步：编译层隔离 (Babel)

在 babel.config.js 中，确保 NativeWind 仅处理项目源码，完全跳过 node_modules。

修改前 (Standard NativeWind v4):

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
      "nativewind/babel",
    ],
  };
};

修改后 (Isolated Config):

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
    overrides: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/, // 核心：绝对禁止处理任何第三方库
        presets: ["nativewind/babel"],
      },
    ],
  };
};

第二步：物理层隔离 (Tailwind Config)

在 tailwind.config.js 中设置物理屏障，防止命名碰撞和自动主题注入。

修改前:

module.exports = {
  content: ["./app/**/*.{js,jsx,ts,tsx}", "./components/**/*.{js,jsx,ts,tsx}"],
  presets: [require("nativewind/preset")],
  theme: {
    extend: {},
  },
  plugins: [],
};

修改后:

module.exports = {
  prefix: 'tw-',           // 核心：强制所有自定义类名带前缀
  darkMode: 'class',       // 核心：锁定暗色模式为类触发，防止系统自动注入背景
  content: ["./app/**/*.{js,jsx,ts,tsx}", "./components/**/*.{js,jsx,ts,tsx}"],
  presets: [require("nativewind/preset")],
  corePlugins: {
    preflight: false,      // 禁用默认的全局重置样式
  },
  theme: {
    extend: {},
  },
  plugins: [],
};

第三步：样式层隔离 (Global CSS)

修改前:

@tailwind base;
@tailwind components;
@tailwind utilities;

修改后:

/* 仅保留工具类，彻底移除基础样式和组件样式的注入 */
@tailwind utilities;

3. 开发规范与验证

1. 类名编写： 在源码中编写类名时必须带上前缀：

   <View className="tw-flex-1 tw-bg-blue-500" />
   

2. 清理缓存（关键）： 修改配置后，必须强制清理缓存重启，否则旧的编译结果会导致隔离失效：

   npx expo start -c
   

   若仍有异常，请手动删除 node_modules/.cache 目录。

4. 方案优势

• 零侵入：无需修改第三方库源码。
• 高性能：Babel 跳过 node_modules 扫描，提升编译速度。
• 可预测：物理前缀和手动暗色模式控制确保了样式的绝对安全。

5. 核心原理倒推 (为什么这样做有效?)

5.1 解决“黑屏”：darkMode: 'class'

• 原理：NativeWind 默认通过系统媒体查询自动切换主题。当系统处于深色模式时，它会主动向所有 View 注入暗色背景变量。
• 真相：长按弹出的 ActionSheet/Modal 触发了这种自动注入。将其改为 'class' 后，NativeWind 失去了主动注入的权限，从而彻底杜绝了无故黑屏。

5.2 解决“逻辑干扰”：exclude: /node_modules/ (Babel)

• 原理：NativeWind 插件默认会重写 node_modules 里的代码以注入跨平台样式逻辑。
• 真相：这种重写往往会“劫持” UI Kit 内部组件的 Props，导致其内部状态（如 Modal 的显示隐藏）与样式转换逻辑冲突。物理隔绝 Babel 扫描是保证 UI Kit 原生逻辑运行的基石。

5.3 解决“样式冲突”：prefix: 'tw-'

• 原理：Tailwind 类名过于通用（如 flex, absolute），极易与 UI Kit 内部的样式或 Props 同名。
• 真相：这种重名会导致 NativeWind 误以为 UI Kit 的内部元素也是 Tailwind 组件。使用前缀建立了明确的边界，让 NativeWind “只管前缀样式”，互不干扰。