背景

最近 MCP 又发大版本了，MCP 2026-07-28 规范。算下来这已经是第五个版本，也是改动最大的一次。

重点是以下内容：

• 这次到底改了什么?
• 社区怎么看?
• 旧版的痛点它堵了多少?
• 以及那个老生常谈的问题”MCP 是不是很浪费 token”新版是否有优化？

原文是 Anthropic 的 Bringing MCP 2026-07-28 to Claude，发布说明在 modelcontextprotocol.io。

一、无状态核心，这次最大的改动

MCP 的月 SDK 下载量今年已经破了 4 亿次，增长了 4 倍，基本坐稳了”AI Agent 接外部工具”的事实标准。
这次 2026-07-28 最大的区别是，是把协议核心从”双向有状态”改成了”请求/响应”的无状态模型。

说白了，以前 MCP 要靠 initialize 握手 + Mcp-Session-Id 把客户端和服务端绑在一个会话上。这带来一个很现实的麻烦：你想横向扩展远程 MCP 服务，就得上 sticky session、共享会话存储，或者专门搞个网关来解析 JSON 路由，部署成本一下就上去了。

无状态化之后，server 可以像普通 HTTP 服务一样直接丢到 Serverless / 边缘节点上，构建和扩展都简单不少。对做基础设施的人来说，这点比加什么新 feature 都实在。

配套的还有两块：

• 标准化扩展：MCP Apps（在对话里直接渲染交互式 UI）和 Tasks（长耗时任务）被纳入版本化扩展框架。以后想加能力不用动核心协议，走扩展就行。
• 授权强化：对齐生产级的 OAuth 2.0 / OIDC，能直接对接 Entra、Okta 这些企业身份系统，不用再搞变通方案。

Claude 这边也在跟着落地，连接器目录已经收了超过 950 个 MCP server，每天几百万人用。除了上面说的 Apps 和企业托管认证，还推了开发者可观测性仪表盘，以及一个研究预览性质的 MCP 隧道——把 Claude 连到私有网络里的 server，不用把内网服务暴露到公网。

二、社区态度：方向正确，代价不小

我翻了一圈技术社区，主流对无状态化是认可的，觉得这是 MCP 走向生产级部署的必经之路。能像普通 HTTP 服务一样水平扩展、部署到 Serverless，大家觉得这步走对了。Figma 在测试期就基于新规范在搭，原话大意是”用的人越多，我们的无状态架构越能跟着扩”。

但吐槽也不少，集中在一件事上：破坏性变更（Breaking Changes）。

这次一口气改了大概 6 处协议行为：

• initialize 握手没了；
• Mcp-Session-Id 被移除；
• 几个核心能力被废弃（resources/list、prompts/list、sampling 部分）；
• OAuth 要求显著收紧。

已经在跑远程 MCP server 的团队，得把”有状态会话”改造成”无状态 + 显式状态句柄”。网上一下冒出大量”迁移实战 / 避坑指南”，本身就说明落地的阵痛是真实的。OAuth 收紧虽然更安全，但旧实现基本得重写认证逻辑，这个工作量不少团队是避不开的。

社区情绪大概是这样：方向对，代价不小。无状态化大家服，但一次性塞进来这么多 breaking change，尤其是 OAuth 这块，怨言挺多。

三、旧版的痛点，新版堵了多少

我顺手把旧版 MCP 被人诟病的地方和新版对照了一下，做个表：

架构类的老问题（扩展性、认证、传输、复杂度）新版基本都堵上了。但安全这块要泼点冷水：协议层”明确不在协议层强制安全”，鉴权授权全靠各团队自己实现。新版靠 OAuth 2.1 / PKCE 部分缓解，但工具投毒（恶意指令藏在工具描述里）、提示注入、Rug Pull 这类 AI 语义层攻击，规范从根上防不了。之前出过的 CVE-2025-49596（MCP Inspector 未授权 RCE，CVSS 9.4）就是血的教训，这些还得靠网关、最小权限、供应链扫描、AI 检测做纵深防御。

所以准确的说法是：新版把”架构类”问题堵了，但”协议不强制安全 + AI 语义攻击”这类根因只是缓解，不是根治。

四、被吐槽”浪费 token”，新版到底管不管？

MCP 一直被人吐槽”工具定义全量灌进 context，还没说话就把窗口撑爆”。具体有两层膨胀：

• Tool Definition Bloat（最严重）：客户端一连接，就把所有工具定义（名字、描述、输入输出 JSON Schema）一把塞进上下文。企业场景 20 个 server × 20 个工具 = 400 个定义，光工具定义就能吃掉 10 万+ token。有开发者实测，连 7 个 server 还没输入就占了 67,300 token。
• Tool Result Bloat：多步工作流里大文件在工具间反复搬运，一份 5 万 token 的文档经”取回→注入→再塞进下一调用”能翻倍到近 10 万 token。

但关键是：2026-07-28 规范本身并没有从协议层解决 token 浪费。 它做的是无状态、OAuth、扩展框架，对 token 问题是中性甚至间接的。规范仍然要求 tools/list 返回全量工具目录，没有强制或提供”按需加载 / 分页 / 工具搜索”原语。

真正省 token 的，是规范之外、客户端和厂商层做的”渐进式披露（progressive disclosure）”机制，而且大多在 2026-07-28 之前就发了：

MCP.Directory 的梳理说得很直白：规范里对懒加载只字未提，客户端连上 server 就调 tools/list 拿全量目录拼进 system prompt，上面这些省 token 的手段全是客户端机制，不是协议变更。

所以结论要厘清：新版在 token 效率上是”顺带搭了便车”（核心概念面缩小、server 更轻量），但没从协议根上改。只要客户端不做渐进式披露，token 膨胀照旧。

五、CLI vs MCP：现在推荐用哪个？

最后聊个更落地的：MCP 和 CLI 到底怎么选。结论先放前面，这俩不是二选一替代，而是按”系统边界”分工的两种接口范式，生产环境大多 hybrid 一起用。

CLI（git / docker / kubectl / gh 这类）被推荐用于本地、单用户、开发者向的工具，相对 MCP 的好处很实在：

IBM 那篇对比给了一个我挺认同的心智模型：

• MCP：从预定义工具集里选，确定性、schema 驱动、一次性正确，”消除不确定性”。
• CLI：模型生成命令，靠”猜测→执行→观察→纠正”循环，”管理不确定性”。

不过 Scale Labs 做过一个受控实验，打破了”CLI 一定更优”的神话——同一套后端工具在 50 个长程任务上 1:1 对比，结论是接口强弱取决于模型和任务，前沿模型基本抹平了差距。还有一条很关键：别同时把两种接口都暴露给模型指望它自己选，实验里模型几乎都退回用 MCP，只有显式路由（批量检索走 CLI、精准读写走 MCP）才可靠。

给我的感觉是 CLI 适合个人、而 MCP 更适合企业使用。

背景

我们的 StarRocks 集群一直跑在 3.5 分支上，最近发现 PR #57371 只 backport 到了 3.4，3.5 没收到，导致 MV 从 inactive 切到 active 的时候走的是 force=true，也就是全量刷新。

于是我手动把这个修复 cherry-pick 到了我们的 3.5 分支，改掉 force=true 的问题之后发了版。发版本身没问题，但发版触发了 FE 滚动重启，重启过程中集群突然被打满——所有分区的物化视图都在对全历史分区做全量刷新。

排查之后发现是三个因素凑到一起：3.5.15 引入的异步 MV reload + 未修复的 force=true 激活路径 + 滚动重启时的 Leader 切换。

时间线

• 16:01 - 17:01：FE-2 上的周期刷新一直是 forceRefresh=false，只刷当天分区。
• 17:01 后：FE-2 停止刷新，开始进入滚动重启窗口。
• 17:07:59：FE-1 上的 MVActiveChecker 触发 ALTER MATERIALIZED VIEW ... ACTIVE，随后进入 refreshMaterializedView(..., FORCE=true, ...)。
• 17:09 - 17:15：FE-1 持续把 forceRefresh=true 传播到后续 batch task，开始刷历史分区。

问题在哪

异步 MV reload（3.5.15 引入）

FE 重启加载 checkpoint 镜像时，MaterializedView.onReload() 先把所有 MV 设为 active = false，然后提交异步任务去检查基表可用性，检查通过再恢复 active。这个异步检查可能耗时几分钟，这期间 MV 都处于 inactive 状态。

MVActiveChecker 补刀

MVActiveChecker 是一个后台守护线程，默认每 60 秒扫一次，看到 inactive 的 MV 就自动执行 ALTER MATERIALIZED VIEW xxx ACTIVE。重启后 grace-period map 是空的，没有任何退避，扫到就激活。

force=true（3.5 分支的老代码）

ALTER MATERIALIZED VIEW xxx ACTIVE 的代码里，激活后会调用 refreshMaterializedView(..., force=true, ...)。3.5 分支切出来的时候，社区刚好有一个把 force 改为 false 的 PR 合入了 main 分支，但 3.5 没收到 backport。

最近社区也发现了这个问题，有客户现场出现了 MV 全量刷新导致数据同步出现延迟，然后才 backport 到 3.5.21 这个版本上。

PR #76576 的说明里写得很清楚：

since 3.5.15 the async MV reload on FE restart makes this a serious regression: during image load onReload() sets active = false first and restores it asynchronously, leaving a minutes-long window in which MVs are transiently inactive. MVActiveChecker picks them up and runs ALTER MATERIALIZED VIEW xxx ACTIVE, and the activation path calls refreshMaterializedView(…, force=true, …) — so every FE leader restart triggers a FORCE full refresh of all async MVs.

所以触发链路是：

1
2

FE 重启 → async reload 设 active=false → MVActiveChecker 激活 
→ refreshMaterializedView(force=true) → 全量刷新

滚动重启放大

我们的 K8s 集群有 3 个 FE Pod，滚动更新逐个重启。每次当前 Leader 被重启，就会触发 failover，新 Leader 的 MVActiveChecker 再扫一遍所有 inactive 的 MV，又来一波全量刷新。也就是说，只要某一轮切换后的 Leader 还没拿到修复版代码，就可能再刷一波；实际波次数取决于 leader 切换路径和滚动顺序。

日志证据

日志里能看到 FE-2 先一直正常周期刷新，forceRefresh=false：

1
2
3

2026-07-23 16:01:09  FE-2  forceRefresh=false
2026-07-23 16:16:11  FE-2  forceRefresh=false
2026-07-23 17:01:09  FE-2  forceRefresh=false

随后 FE-1 在 17:07:59 接管并触发自动激活：

1
2
3
4

2026-07-23 17:07:59  MVActiveChecker Start to activate MV dws_trd_period_sales_offline_store
2026-07-23 17:07:59  LocalMetastore.executeRefreshMvTask() FORCE=true
2026-07-23 17:09:24  FE-1  forceRefresh=true
2026-07-23 17:15:54  FE-1  forceRefresh=true

这说明滚动重启窗口内，Leader 已经切到了 FE-1，且当时 FE-1 仍在执行未修复的激活逻辑。

代码位置

• fe/fe-core/src/main/java/com/starrocks/scheduler/MVActiveChecker.java
• fe/fe-core/src/main/java/com/starrocks/alter/AlterMVJobExecutor.java
• fe/fe-core/src/main/java/com/starrocks/server/LocalMetastore.java
• fe/fe-core/src/main/java/com/starrocks/scheduler/PartitionBasedMvRefreshProcessor.java

实际影响

我们集群里 MV 会做全历史分区全量刷新，CN 节点 CPU 打满，数据延迟数小时。

怎么规避

3.5.21 已经合了上面的 bugfix，force=true 改成了 force=false。但如果你在升级 到 3.5.21 或升级 后 还需要做 FE 重启，保险起见可以先关掉 MVActiveChecker：

1

ADMIN SET FRONTEND CONFIG ("enable_mv_automatic_active_check" = "false");

确认生效：

1

ADMIN SHOW FRONTEND CONFIG LIKE "%enable_mv_automatic_active_check%";

滚动重启全部完成后，确认集群稳定（Leader 不再切换、没有历史分区的刷新任务在跑），再打开：

1

ADMIN SET FRONTEND CONFIG ("enable_mv_automatic_active_check" = "true");

关闭期间不影响定时刷新和手动刷新，只影响”从 inactive 自动恢复 active”这一种场景，业务无感。

总结

这个问题本质上是三个因素碰到了一起：异步 reload 制造了 inactive 窗口、MVActiveChecker 在这个窗口里激活了 MV、激活路径又走的是 force=true。3.5.21 修了 force=true，但如果之后 FE 重启时异步 reload 还没完成，MVActiveChecker 仍可能先动手；只是刷新会变成增量，不再是全量。

所以升级前后的保险操作是：先关掉自动激活，等全部 FE 滚动完成且 Leader 稳定后，再重新打开。

参考链接：

• https://github.com/StarRocks/starrocks/pull/76576
• https://github.com/StarRocks/starrocks/pull/57371

额外再补充一下，现在 DS 感觉降智有点严重，整个问题的分析过程我分别交给了 DS v4 Pro 和 kimi2.7

kimi2.7 很快就定位到是滚动更新导致 leader 切换出现的问题，希望 DS 最近要发布的正式版

前两天发了一篇 Rewriting Bun in Rust 原文的翻译，内容有点多，这次我自己整理了一份精简版。

背景

一开始是因为在 X 上刷到 Bun 官方博客一篇《Rewriting Bun in Rust》，作者是 Jarred Sumner。看完挺震撼的——1 个工程师，用 CC（Claude Code）+ Claude Fable 5（重写那会儿还是预发布，现在订阅用户已经能正常用了），11 天把整个 Bun 从 Zig 重写成 Rust，落地 diff +100 万行，6,778 个 commit。

这篇是我读完之后按自己的理解整理的笔记，分几个部分讲清楚：
为什么要扔掉 Zig、
为什么选 Rust、
整个工作流是怎么搭的、
作者和 CC 各自干了什么、
怎么保证质量，
以及烧了多少钱。

顺带一提：Bun 在 2025 年 12 月被 Anthropic 收购了，作者现在也在 Anthropic。这次重写用的是 Claude Fable 5，重写那会儿（2026 年 5 月）还是预发布版，到截稿今天（2026-07-12）已经对订阅用户开放了。所以这文章多少带点「自家产品自家用了」的意味，但流程本身是真有东西的。

为什么要停止使用 zig

先说清楚一件事：作者没有「骂」Zig，反而一直强调没有 Zig 就没有 Bun。Bun 最初就是把 esbuild 的 JS/TS 转译器从 Go 逐行移植到 Zig 的产物，作者 2021 年写下第一行 Zig，一个人一年在奥克兰的出租屋里把 Bun 初版手搓出来。可以说 Zig 是 Bun 的恩人。

但问题出在「稳定性」上。Bun 的范围大得吓人——转译器、打包器、npm 兼容包管理、类 Jest 测试运行器、Node.js API（fs/net/tls 一堆）、HTTP/WebSocket 客户端，全塞在一个 runtime 里。这种规模 + Zig，结果就是一长串内存安全 bug。原文贴了一小撮，我挑几个有代表性的：

根因在哪儿？JavaScript 是带 GC 的语言，JavaScriptCore（以及 V8）对异常处理和 GC 有严格规则。而 Zig 跟 C 一样不替你管内存，没有构造函数/析构函数，清理工作要靠每个调用点显式写 defer。

这不是 Zig 的锅。其他 Zig 用户没这种 bug，是因为「把 GC 值和手动管理的值混在一起」本身就是个不常见的需求，没有哪门语言会专门为此设计。

对 Bun 来说，正确处理「GC 管的值」和「手动管的值」的生命周期，一直是稳定性问题的主要来源——最常见的是小内存泄漏，偶尔直接崩。每一处内存分配都得仔细 review：这些字节在哪释放？怎么保证只释放一次？JS 异常都检查了吗？这块内存是 GC 管的还是手动管的？

作者他们也做过不少防护：给 Zig 编译器打补丁加 ASAN、每次 commit 都开着 ASAN 跑测试、用 Fuzzilli 7×24 fuzz 运行时 API、一堆端到端内存泄漏测试。这已经比大多数项目做得多了。但还是堵不住。

说白了，可以一直一个个修下去，但用户指望着你，理应做得更好——从系统层面防止这类 bug 反复出现。于是有了换语言的念头。

为什么切换为 rust？

候选其实有三个：继续用 style guide 硬撑 Zig、换 C++、换 Rust。

为什么不是「继续用 Zig + style guide」？ 很多项目靠 style guide 回答这类问题，TigerBeetle 的 TigerStyle（一份 Zig 的 style guide）、Google 那份 31000 字的 C++ style guide 都是例子。style guide 的难处不在写，在执行——你怎么保证它被遵守？历史上只能靠 code review + linter 尽力而为。作者甚至想过在 Zig 里手搓一套受 Rust 启发的智能指针，但他自己都嫌弃：自制的智能指针比 Rust 体验更差，还换不来任何保证。

为什么不是 C++？ Bun 大约 20% 的代码本来就是 C++，还内嵌了 JavaScriptCore、uWebSockets、BoringSSL、SQLite 这些 C/C++ 库。换 C++ 是个合理选择，能拿到构造/析构函数，还能删掉一堆 extern "C" 包装。但内存问题上还是得靠 style guide + code review，即便有 ASAN，内存损坏和泄漏照样会发生。

为什么是 Rust？ 看回上面那份 bug 清单，很大一部分是 use-after-free、double-free、错误路径上「忘记释放」。在 safe Rust 里，这些都是编译错误，外加 Drop 这种类 RAII 的自动清理。

编译错误是比 style guide 更好的反馈回路。

一句话：Rust 把「靠人记」变成「靠编译器兜底」。

但重写在历史上都是个糟糕主意。去掉注释，Bun 有 535,496 行 Zig。换语言重写要一个小团队整整干一年，期间得冻结 bugfix、安全修复和功能开发。作者选了风险最低的做法——机械式移植，行为改动尽量少，用已有的那套测试套件。好在 Bun 自己的测试是用 TypeScript 写的，不依赖 runtime 的实现语言，这给了重写一个「不变量」可以对照。

这里有个关键判断：重写的样子要像把 Zig 转译成 Rust，先不过度追求地道 Rust。等 v1.4 发出去之后，再逐步减少 unsafe、改成更地道的写法。一步到位太贪，容易翻车。

整个切换的工作流是什么？

这部分是我觉得整篇文章最值得拆开看的地方。作者没有「给 Claude 一句 prompt 然后赌它能成」，而是搭了大约 50 个 dynamic workflow（CC 的动态工作流），在 11 天里持续跑。

工程师日常大量工作可以简化成一个循环：

1
2
3
4
5
6
7

// 伪代码
let task;
while ((task = todoList.pop())) {
  const result = task();
  const feedback = await Promise.all([review(result), review(result)]);
  await apply(feedback, result);
}

每个 workflow 都是这样的一个循环，分别干：生成移植指南、逐文件移植 .zig→.rs、修编译错误、修子命令、修测试、大重构。整体节奏大致是这样：

阶段	干什么
Prep	花 3 小时和 Claude 讨论模式映射，产出 PORTING.md（后来还上了 HN）；再跑一个 workflow 分析每个 struct 字段的生命周期，产出 LIFETIMES.tsv，并经对抗式 review
试运行	先只移植 3 个文件，验证流程
写代码	峰值每分钟约 1,300 行，6,502 个 commit
修编译错误	约 16,000 个错误，按 crate 分给 64 个 Claude
跑通	bun --version → bun test <file> → 全测试
CI 全绿	972 个失败测试文件 → 2 天后 23 个 → 最终 6/6 平台全绿

中间踩了一堆坑，作者原话叫「false starts」：

• Claude 们互相踩脚：一个跑 git stash，另一个跑 git stash pop，还有 git reset --hard。问题在于这几个命令都是对整个工作区 / index / stash 栈的全局性破坏操作，而一开始多个 Claude 共用同一份工作区。git stash 会把别人半成品的改动一起搁走，git stash pop 可能恢复出不相关的改动，git reset --hard 更狠——一个 agent 跑一下，仓库里所有其他 agent 没提交的活瞬间清零。结果就是丢活、冲突、状态错乱，agent 们互相把对方的工作撤销掉。下规则：只允许「针对特定文件的原子提交」（git add <具体文件> && git commit），禁止任何会全局改动工作区/index 的命令（git stash/reset --hard/checkout . 这类）。光禁还不够，后来又拆成 4 个独立 worktree 物理隔离，才真正解决。
• 太慢 → 拆成 4 个 worktree 分片，每个跑 16 个 Claude，峰值同时 64 个 Claude。
• Claude 把「让所有 crate 编译通过」理解成「用 stub 把报错函数糊过去」，还写长注释自圆其说。加规则：需要一整段注释论证 workaround 为什么没问题，代码就是错的——去修代码。
• 压测会把机器 TCP socket 耗尽、写几个 GB 到磁盘、spawn 上万个进程，debug 构建超时。用 systemd-run（cgroups）限制内存/CPU、隔离 pid 命名空间。机器还是几次跑光磁盘崩了。

作者担任的角色是什么？CC 担任的角色又是什么？如何搭配工作的？

这是我看这篇文章最想搞清楚的问题。结论是：作者不是只做 review 的人，他是架构师 + 流程设计者 + 监工 + 验收者；CC 是执行者（写代码 + 互相 review + 改代码）。

作者干的：

• 战略决策：选一次性全量重写而非增量、选机械式移植、定下「先像转译、之后再改地道」的总方针。这些 CC 不会替你拍板。
• 流程/workflow 设计：50 个 dynamic workflow 的循环结构是他搭的，每个 workflow 跑什么也是他定的。
• prompt 与规范制定：产出 PORTING.md、LIFETIMES.tsv，自己人工通读。
• 监工 11 天：原文——「most of those 11 days, I monitored workflows, manually reading the outputs to check for issues and bugs, and prompting Claude to edit the loop to fix things」。也就是人工读输出、发现问题、改 workflow 的 prompt 让 Claude 自己修。
• 处理翻车 + 改规则：上面那些 false starts 的规则都是他下的。
• 验收：合并前人工核实测试「确实在跑、没被跳过」，本地跑一堆命令试，然后才按合并键。还把 Zig 和 Rust 并排人工通读了大量代码。

CC 干的：

• 实际写代码（峰值每分钟约 1,300 行，落地 diff +1,009,272）。
• 修编译错误（约 16,000 个）。
• 修测试失败（本地 + CI 各平台）。
• 对抗式 review——注意，reviewer 也是 Claude，独立上下文窗口，1 个实现者配 2 个对抗式 reviewer。所以连 review 都大量是 Claude 审 Claude。

两人怎么搭配？核心是一句话：当出问题时，修掉生成代码的流程，而不是手工修代码。 作者修的是「过程」，具体代码交给 CC。

这种分工其实挺反直觉的。很多人用 Agent 是「让 Agent 写，我审」。作者反过来：让 Agent 写、Agent 审、Agent 改，自己只盯「流程」和「验收」。把人从执行链路里摘出来，专心做架构和决策。这个思路我个人觉得是这次重写最值得安利的部分。

对抗式 review 还有个设计细节很巧：拆分上下文窗口。写代码的 Claude 想让代码被接受（有「赶紧发出去」的偏向），审代码的 Claude 被要求「假定代码是错的，找它不工作的理由」。reviewer 只拿到 diff，看不到实现者的任何推理。1 个实现者 + 2 个以上对抗式 reviewer，实现者不审、reviewer 不写。原文举了一个真抓到的 bug：异步 uv_close 之前 Box 就 drop 了，先 UAF 再 double-free，编译能过、看着也没问题，但 reviewer 抓到了。

如何保证切换后的代码质量，如何做测试？

一个 +100 万行的 PR 怎么 review？你怎么建立信心去合并？作者给的答案是三件套：

1. 一套与语言无关、含上百万断言的测试。
2. 对抗式 code review。
3. 出问题时，修流程而不是手修代码。

测试这块是真扎实。测试用 TypeScript 写，所以不依赖 runtime 语言，重写前后用的是同一套。各平台的断言数：

合并前要求 100% 测试在所有平台的 CI 上都通过，作者还人工核实测试「确实在跑、没被跳过」——这一步很重要，Agent 偷懒跳测试是经典坑。

合并之后还在持续加码：

• 11 轮安全审查（Claude Code Security），处理了所有发现。
• 7×24 覆盖引导 fuzzing，覆盖每个解析器——JS、TS、JSX、CSS、JSON5、JSONC、TOML、YAML、Markdown、INI、Bun Shell、semver、.patch、CSS 颜色。fuzzer 找到 bug 自动发给 Claude 提 PR 复现+修复，人审。迄今跑了 1000 亿次，产出约 15 个 PR。
• Miri（在 CI 里覆盖越来越大的代码段）+ LeakSanitizer。
• unsafe 占比：约 4% 的 Rust 代码在 unsafe 块里（~13,000 个 unsafe 关键字 / ~780,000 行），其中 78% 只有一行——基本是一个来自 C++ 的指针或一次对 C 库的调用。

当然，重写不可能零回归，这次引入了 19 个已知回归，全部已修。多数来自「两门语言语法相同、语义不同」的坑，原文举的例子很值得记一下：

• debug_assert! 里的副作用：Zig 的 assert 是函数，参数每次都跑；Rust 的 debug_assert! 是宏，release 构建里整段被抹掉，连里面的 insert_stale 调用也没了，HMR 在某些场景挂了。debug 构建正常，所以一开始没发现。
• 奇数长度切片：Zig 的 reinterpretSlice 用 @divTrunc 忽略尾部奇数字节，bytemuck::cast_slice 直接 panic。
• 边界检查：Zig 的 ReleaseFast 去掉边界检查，Rust release 保留，于是原本不可达的越一 bug 被触发，Rust panic 而不是写越界。
• comptime 格式串：Zig 里 fmt 是 comptime，颜色标记在参数替换前就处理掉了；Rust 函数没有 comptime 参数，标记被改写到了参数上。

这些坑本质上都是「机械移植」的代价。语法看着一样，语义不一样，最容易懵逼。但也正因为有那套百万断言的测试兜底，才敢这么干。

效果上，Rust 版的 Bun 确实更好了：内存占用下降（修掉了每个可插桩的内存泄漏，Bun.build() 从每次泄漏约 3MB 变成趋于平稳）、二进制体积缩小约 20%（Linux/Windows）、性能快 2%–5%。

整体使用的模型、token、花费大约是多少？

没有 LLM 的时代要多少人干多久？ 作者自己的估算：3 个对代码库有完整 context 的工程师，干一年。而且这一年里没法改进 Node.js 兼容性、没法修 bug、没法修安全问题、没法加新功能。作者原话——「我们绝不会这么做」。现实的替代方案就是「什么都不做，一直修文章开头那些 bug」。

说白了，这次重写之所以能成，不是因为 Rust 比 Zig 好多少，而是因为 LLM 把「重写一年、冻结所有业务」这个成本，压到了「1 个人 11 天 + 16 万刀」。

16 万刀看着贵，但对比「3 个核心工程师一年全力投入、期间零业务推进」的机会成本，这笔账其实算得过。而且 Fable 5 现在已经对订阅用户开放，重度 CC 用户用订阅额度也能跑起来，这套流程会越来越香。

总结

读完这篇，我最大的感受不是「Rust 真好」或者「Zig 不行」，而是「一个工程师今天能做的，比前些年多得多」。

这是一些我总结的经验：

1. 人从执行链路里摘出来。让 Agent 写、Agent 审、Agent 改，人只盯「流程设计」和「验收」。这跟很多人用 Agent「让它写、我来审」的直觉是反的，但作者用 11 天 + 100 万行证明了这条路可行。
2. 修流程，不修代码。出问题改 workflow 的 prompt 和规则，而不是手修 diff。这是把「一次性修补」变成「系统性防止」的关键。
3. 对抗式 review + 拆分上下文窗口。实现者想合并、reviewer 想找茬，天然对立；reviewer 只拿 diff、看不到实现者推理。这套设计可以直接抄到自己的 CC workflow 里。
4. 语言无关的测试套件是重写的底气。敢机械移植，前提是有一套百万断言、跟实现语言无关的测试兜底。没有这个，谁也不敢合并 +100 万行 LLM 代码。
5. 机械移植 > 一步到位。先像转译、行为不变，之后再改地道。一步到位太贪，容易翻车。这个判断对任何「大重构」都适用。

当然也有它的特殊性：作者是 Bun 的创造者、对代码库有完整 context，重写那会儿用的还是 Fable 5 预发布版（现在已开放订阅），流程本身也踩了不少坑（互相踩脚、stub 糊编译错误、磁盘跑光）。不是随便谁来都能复刻。但方法论是通用的——流程设计 + 对抗式 review + 强测试兜底 + LLM 执行，这套组合拳，值得每个重度用 CC 的人认真琢磨。

不过说回国内，16 万刀换算过来是一笔不小的开支。最近还有个趋势挺值得警惕：一些老板看到别家公司对外宣传的「Agent 重写」「AI 替代工程师」成果，就也想在内部搞一套，想着用 Agent 替掉几个工程师来省钱。

但在我看来，这事没这么简单，至少得先想清楚几个问题：

1. 业务真的需要顶配模型吗？ 大部分业务说白了就是增删改查，拿最贵的模型去跑这种活，杀鸡用牛刀（简单来说都是增删改查）。
2. 舍得花这么多钱吗？ 16 万刀只是一次重写的 API 费，常态化跑起来账单只会更吓人，这笔账得先算清楚。
3. 指挥 AI 干活的人，能不能扛起来？ 这次能成的前提是作者本身就是 Bun 的创造者，对代码库有完整 context，能当好架构师 + 流程设计者 + 监工 + 验收者这几个角色。换成公司里一个对业务没那么熟的工程师来指挥，效果天差地别。
4. 内部怎么评估 AI 带来的效率提升？ 没有量化就只有感觉，而「我感觉快了」这种话，最后往往经不起对账。

很多老板自己都没想清楚，就被对外宣传裹挟着陷入深深的焦虑，一头扎进去搞 AI 替代，最终的效果往往适得其反——钱花了，人也没省下来，业务还可能被带歪。

让子弹飞一会，但这次子弹已经飞到 100 万行代码量级了。

背景

已经高强度的使用 claude code 大半年的时间了，积累了不少好用的 SKILLS 和工具，今天来整理一下分享给大家。

我安装了大约 70 几个 SKILLS，但常用的其实也不太多，下面介绍一些我个人觉得效果不错的。推荐使用我开发的 skilldeck 来管理本地的 SKILLS：

1
2

brew tap crossoverJie/skilldeck && brew install --cask skilldeck
xattr -cr /Applications/SkillDeck.app

常用 SKILLS

个人相关

agent-notifier

这是我自己做的一个 SKILL，主要用于 Agent 完成任务和等待任务时发出通知。虽然现在一些 terminal 已经支持通知了，比如 cmux、otty，但是它们都不能推送 IM，后面它们支持之后也就不再需要这个 SKILL 了。

kami

可以用于生成一切页面，包括网页、landing page、简历、PPT 等都可以帮你实现，同时它的 SKILL 编写过程也值得参考。

skilldeck 的项目主页

我的独立 app 的项目首页

整体来看页面都很和谐，配色属于我的审美。

ponytail

主要就是为了：懒，避免 AI 做过度设计、尽量简化代码。

它的核心原则：

1. 这东西真的需要存在吗？推测性的需求 → 跳过 (YAGNI)
2. 代码库里已经有了？复用已有的 helper/util/type
3. 标准库能做？用它
4. 原生平台特性覆盖？<input type="date"> 胜过 picker 库
5. 已安装的依赖能解决？用它，绝不为几行代码能搞定的事加新依赖
6. 能一行搞定？一行
7. 以上都不行 → 写最小可用代码

三个强度可选：

什么时候不能懒：

• 信任边界的输入校验
• 防止数据丢失的错误处理
• 安全措施、无障碍基础
• 用户明确要求的功能

skilldeck

配合我开发的 skilldeck 可视化 SKILLS 工具使用，可以在 Agent 里管理 SKILLS，同时数据也兼容 skilldeck，这样就也可以使用 skilldeck 的 GUI 能力。

web-access

web-access 是一个联网操作技能，让你能通过 Claude Code 访问和操作网页内容。

核心能力：

浏览器 CDP 模式是它的亮点，通过 CDP Proxy 直连你日常使用的浏览器，天然携带登录态，无需额外登录。可以：

• 创建新 tab 访问页面
• 执行 JS 读取/操控 DOM
• 点击、滚动、填写表单
• 截图捕获页面/视频帧
• 提取图片、视频等媒体资源

所有操作在后台 tab 进行，不影响你现有的浏览状态。

工作相关

generate-wiki

这是我在工作中沉淀下来的 SKILL，可以一键将自己的 Java + gRPC 项目生成一个静态 wiki 页面。

但要注意，这不是一个通用的方案，最好是 fork 过去根据自己的项目进行定制。

starrocks-upgrade

我在维护公司内部的 StarRocks 的时候，版本升级时往往拿不准对现有集群的影响，于是有了这个 SKILL。它可以在你升级之前通过源码对比不同版本之间的差异，给出风险点，具体使用过程和原理可以参考这篇文章。

同理，类似的软件版本升级都可以做一个 SKILL 工具。

常用工具

TUI

使用 /tui fullscreen 可以开启全屏模式，这样就可以使用鼠标来移动光标了，用起来更像是一个现代的文本编辑器，再也不用键盘方向键来移动光标了。同时也支持选中复制。

/tui 命令首次引入版本是 v2.1.110（2026年4月15日），但 fullscreen 渲染模式本身在更早的 v2.1.90 就已经存在了。

版本演进：

/tui fullscreen 的特性：

• 无闪烁渲染 (flicker-free)
• 更低内存占用
• 鼠标支持（点击选择菜单，Cmd+点击打开 URL）
• 选中即复制

statusLine

statusLine 是 Claude Code 原生提供的终端底部自定义状态栏接口。它不是一个固定样式的功能，而是允许你通过 JSON 传给脚本，脚本把想显示的文本输出到 stdout，Claude Code 再将结果显示在输入框下方、内置 footer 徽章上方。

使用方式很简单，直接输入 /statusline，用自然语言描述你想展示什么，例如”显示模型、当前目录、上下文百分比和进度条”。

你的 statusline.sh 可以自行组合：模型、当前目录、Git 分支、dirty 状态、上下文百分比、累计成本等。

当然你还可以直接使用 claude-hud，它是基于 statusLine 接口做的现成插件，替你实现并维护一套更完整的 statusLine 脚本和配置。示例：

1
2

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25%

还可选展示：

1
2
3

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code
▸ Fix authentication bug (2/5)

除了模型、目录、Git、上下文和额度，它还能从本地 transcript JSONL 中解析出工具活动、运行中的 subagent 与 Todo 进度，有些东西的。

总结

以上就是我目前常用的 SKILLS 和工具，SKILLS 这块主要分为个人和工作两类。个人相关的主要是提升日常开发体验，比如通知、页面生成、代码简化；工作相关的则更偏向特定场景，比如 wiki 生成、版本升级风险评估。

工具方面，TUI 的全屏模式让 Claude Code 的交互体验提升了一个档次，statusLine 则让终端底部的信息展示更加灵活。这些看似小的改进，用久了真的回不去。

如果你也有好用的 SKILLS 或工具推荐，欢迎交流。

以前学 linux 命令行，常见路线是记住一堆 grep、find、sed、awk，然后自己在代码库里定位问题、筛选文件、拼接命令。

但进入 Coding Agent 时代后，我觉得人和终端的分工变了。

代码搜索、读取配置、分析调用链、运行测试，这些工作本来就是 Agent 擅长的。面对一个仓库，Claude Code、Codex 之类的 Agent 会自己判断该用 rg、git diff、jq 还是别的工具；我不需要为了”指挥 Agent”而把这些命令全学一遍。

我更常用的，是另一类命令：

• 快速进入正确项目；
• 把准确的文件路径交给 Agent；
• 从大量文件里选出我想让它看的那个；
• 跑长任务时，避免 Mac 睡眠导致 Agent 中断。

下面是我目前最常用的一套。

1. realpath：跨项目引用文件时，给 Agent 一个准确的地址

用 Agent 的时候，大部分情况下你不需要操心路径——Agent 自己会 cd 进项目目录，该读什么文件它自己会找。

但有一个场景例外：你在 A 项目里工作，需要参考 B 项目的文件。

比如你正在 A 项目里做重构，想让 Agent 参考 B 项目里的一个实现。这时候你没法直接在 A 项目里 @ B 的文件，因为它们不在同一个仓库目录下。

我最常见的做法是：切到 B 项目的终端，realpath 一下目标文件，把绝对路径复制过来，告诉 Agent 去读。

1

realpath ~/Code/project-b/src/service/payment.go

输出：

1

/Users/aurora/Code/project-b/src/service/payment.go

然后回到 A 项目的 Agent 对话里：

请阅读 /Users/aurora/Code/project-b/src/service/payment.go，参考它的重试逻辑，帮我在 A 项目里实现类似的功能。

这样 Agent 就能跨项目读取文件，不受当前工作目录的限制。

我会把它封装成 rp

跨项目引用是高频操作，所以我做了一个小函数：输出路径、自动复制到剪贴板、再告诉我复制成功。

1
2
3
4
5
6
7

rp() {
  local p

  p=$(realpath "$@") || return
  printf '%s' "$p" | pbcopy
  printf 'Copied: %s\n' "$p"
}

放进 ~/.zshrc 后，重新加载：

1

source ~/.zshrc

之后切到 B 项目终端，只需要：

1

rp src/service/payment.go

终端会显示：

1

Copied: /Users/aurora/Code/project-b/src/service/payment.go

然后切回 A 项目的 Agent 对话，直接粘贴路径，告诉它要参考什么。

这比手动拼路径或者在两个终端之间来回切换要顺畅很多。

2. zoxide：不用记路径，只要记得项目大概叫什么

项目多起来以后，最烦的不是打开终端，而是进入正确目录。

传统方式可能是：

1

cd ~/Code/company/backend/payment-service

路径长、层级深，而且每个项目的目录结构不一样。更常见的情况是，你只记得项目大概叫 payment，但不记得它放在 ~/Code、~/Workspace 还是某个 worktree 目录下。

zoxide 的思路很简单：它会根据你的访问记录，为目录建立使用频率和最近访问的排序。

安装后，常见用法是：

1

z pulsar

它会跳到最符合 pulsar 的常用目录。

如果候选目录不止一个，可以使用交互模式：

1

zi

或者：

1

zi starr

然后通过模糊搜索选择目标目录。

对于日常 Agent 工作流，zoxide 的意义并不只是”替代 cd“，而是更快回答一个问题：

我应该在哪个项目、哪个 worktree 里启动这个 Agent？

比如你平时有：

1
2
3
4

~/Code/my-app
~/Code/my-app-fix-login
~/Code/my-app-refactor
~/Code/my-app-release

你不需要回忆完整路径，只需要：

1

zi my-app

选中正确工作区后，再启动 Agent。

对于经常并行处理多个项目、多个分支、多个 worktree 的人来说，这个体验很容易形成习惯。

3. fzf + fp：从文件列表中选中目标，并把绝对路径直接交给 Agent

fzf 是一个终端里的模糊选择器。

它可以用于命令历史、目录、Git 分支、进程列表等很多场景，但我自己最常用的用途只有一个：

当我知道”我想让 Agent 看一个文件”，但不想手动输入完整文件名时，用它选中并复制路径。

我给它配了一个 fp 函数，意思是 file path：

1
2
3
4
5
6
7
8
9
10

fp() {
  local file
  local path

  file=$(fzf) || return
  path=$(realpath "$file") || return

  printf '%s' "$path" | pbcopy
  printf 'Copied: %s\n' "$path"
}

使用时只需要在项目目录里输入：

1

fp

然后输入几个关键词，例如：

1

feature

fzf 会实时筛选文件。选中后按回车，完整绝对路径就已经进了剪贴板。

接下来可以直接对 Agent 说：

请阅读我刚刚复制的这个文件，先解释它的作用，再帮我确认是否存在兼容性风险。

这个流程特别适合下面几类场景：

• 你在 Finder、IDE 或终端中看到一个文件，但路径很深；
• 项目里有很多同名或近似命名的配置文件；
• 你知道文件名的一部分，但不想手动补完整；
• 你想精确限制 Agent 的阅读范围；
• 你准备让 Agent 修改一个文件，希望先明确告诉它目标路径。

给 fzf 开启 Shell 集成

如果你使用 zsh，可以把下面这行放进 ~/.zshrc：

1

source <(fzf --zsh)

重新加载配置：

1

source ~/.zshrc

除了 fp，这还会带来几个很实用的快捷键：

1
2
3

Ctrl-R：模糊搜索历史命令
Ctrl-T：选择文件或目录，插入当前命令行
Alt-C：选择目录并切换过去

但对我来说，fp 才是最贴近 Agent 协作的一个封装：

选中一个文件 → 转成绝对路径 → 自动复制 → 交给 Agent。

4. Otty 的保活机制：让长时间 Agent 任务不被 Mac 睡眠打断

AI Agent 任务经常比普通命令跑得久。

例如：

• 让 Agent 分析一个大型仓库；
• 跑完整测试集；
• 做跨模块重构；
• 生成升级兼容性报告；
• 等待多个子任务完成；
• 长时间运行 Claude Code、Codex 或其他本地 Agent。

这时一个很现实的问题是：Mac 可能进入显示器休眠或系统休眠，导致终端任务暂停，Agent 的执行也被打断。

如果你使用 Otty，可以开启它的：

1

Prevent Sleep While Processing

打开后，Otty 会在 Agent 正在处理任务时保持 Mac 唤醒；当 Agent 进入空闲状态后，又会自动释放这个保活状态。

这比手动执行一个长期保活命令更符合 Agent 工作流，因为它只在真正需要时保持机器唤醒。

我会把它理解为 Agent 任务的”运行保险”：

不是让 Mac 永远不睡，而是确保一个正在执行的重要任务不会因为系统休眠而半途停止。

尤其是晚上跑长任务、挂着多个 Agent、暂时离开电脑时，这个设置很值得打开。

一套很简单的 Agent 协作流程

这几个工具并不是替代 Agent，而是让你更好地把任务交给 Agent。

一个典型流程大概是这样：

1
2
3
4
5
6
7
8
9
10
11
12

# 1. 快速进入项目或 worktree
zi my-project

# 2. 找到你想让 Agent 重点看的文件
fp

# 3. 粘贴路径，告诉 Agent 要做什么
# 例如：
# 请检查 /Users/aurora/Code/my-project/configs/prod/app.yaml
# 重点分析生产环境风险，并给出最小修改方案。

# 4. 如果任务会很久，打开 Otty 的 Prevent Sleep While Processing

跨项目引用时，流程稍有不同：

1
2
3
4
5
6
7

# 1. 切到 B 项目终端，复制目标文件路径
rp src/service/payment.go

# 2. 回到 A 项目的 Agent 对话，粘贴路径
# 例如：
# 请阅读 /Users/aurora/Code/project-b/src/service/payment.go
# 参考它的重试逻辑，帮我在 A 项目里实现类似的功能。

我不再刻意学习的命令

像 rg、fd、jq、ast-grep 当然都是很好的命令行工具。

但在我的工作流里，它们更偏向 Agent 的执行工具，而不是我必须熟练掌握的工具。

我关心的是：

• Agent 在哪个目录运行；
• 它应该看哪个文件；
• 我如何快速把目标路径交给它；
• 多个项目之间怎样切换；
• 长任务能不能稳定跑完；
• 完成后我如何回到结果验证。

换句话说：

Agent 负责在仓库内部探索和执行；我负责把正确的项目、正确的目标和正确的约束交给它。

这也是我理解的 AI Coding Agent 时代终端分工。

终端不再只是”人手工敲命令的地方”，它更像是一个控制台：

• 用 zoxide 找到正确工作区；
• 用 fzf 从大量文件中选定目标；
• 用 realpath + pbcopy 把准确地址交给 Agent；
• 用 Otty 保证长任务不中断。

不需要掌握几十个复杂命令。

先把这几个高频动作做得足够顺手，就已经能明显改善和 Coding Agent 协作时的体验。

总结

AI Coding Agent 时代，人和终端的分工发生了变化。Agent 负责在仓库内部探索和执行，而我负责把正确的项目、正确的目标和正确的约束交给它。

这套工具链的核心思路就四个字：精准投喂。

不需要掌握几十个复杂命令，先把这几个高频动作做得足够顺手，就已经能明显改善和 Coding Agent 协作时的体验。

最近将终端从 Warp 切换到了 cmux，用了一段时间后，现在已经基本上满足我的所有需求，所以才有这篇安利的文章。

开始之前先回顾下自己的终端使用历史。刚开始工作那时候使用的是 Windows，用得最多的终端就是 xshell，后面切换到 macOS 之后自然就切换到了 mac 上用的最多的 iTerm2。

iTerm2 一直是我的主力终端，用了很多年，直到前些年 Warp 的出现。Warp 提供了 block 块、现代的文本编辑器（支持鼠标移动光标），用上之后就离不开它了。

但是随着这些年的迭代，Warp 功能越做越臃肿，加入了一些我完全不需要的 AI 功能。

加上近期频繁使用 Claude Code、Codex、OpenCode 这些 AI Agent，对终端的依赖性变得更高了。

原本我一开始是想自己做一个的——我其实就是想要一个简化版的 Warp，需要包含以下功能：

• Block 功能，特别是查看大量日志的时候非常有用
• 现代的文本编辑器，而不是每次都用方向键来移动光标
• AI Agent 的管理功能
  • Agent 完成时的通知、当前状态的查看
• 终端状态栏：显示当前路径、git status、git diff 等信息

我大概做了一周多的时间，达到了一个基本可用的版本，但很多细节都没做好。

受限于当时选择的技术栈 Tauri + Rust，一些体验上确实比不上 Swift 的原生开发效果。

于是就继续用 Warp，直到后面在社媒上看到了 cmux。

cmux

这是我目前使用 cmux 的截图。现在使用终端其实 90% 的时间都在和 Agent 打交道。

我会同时开启 N 个 Agent 来干活，其中又会将 Agent 按照业务进行分组，这时就得提到 cmux 的工作区和分屏功能了。

cmux 把结构分成 Window → Workspace → Pane → Surface → Panel。也就是说，一个工作区里可以有多个分屏，每个 Pane 里还能有多个 Surface，非常适合把主 Claude Code、测试命令、日志、浏览器、子 Agent 放在同一个 context 里。

而且 cmux 还集成了 Agent 通知——普通终端通知往往只告诉你「有进程需要输入」，但不知道是哪个 Agent、哪个项目、哪个分屏。cmux 的 Pane 会出现蓝色通知环，侧边栏 Tab 会亮起，还支持通知面板和 macOS 桌面通知。

通知的问题之前我写过一个 SKILLS 来解决，现在终端能原生通知就更好用了。

总结

如果你是 macOS 用户，还在使用 Warp 甚至是 iTerm2、自带终端的 Coding Agent 重度用户，非常推荐你来试试 cmux，一定会有新的发现。

I’ve been working on a cross-version upgrade of StarRocks (3.3 → 3.5) and hit quite a few pitfalls along the way. I previously wrote a post on StarRocks Upgrade Considerations documenting the manual upgrade process, but that was only for minor version upgrades (3.3.3 → 3.3.9).

Cross-major-version upgrades are an entirely different beast — between 3.3 and 3.5 there are 6000+ commits, hiding all kinds of incompatible changes: default config values changed, session variables modified, protocol fields removed… Manually reviewing each one is simply not feasible. Missing a single critical change could lead to a production incident.

So I thought: can AI help me do this job? After some iteration, I hand-crafted a StarRocks upgrade risk scanner using Claude Code (starrocks-upgrade skill). This article discusses its design principles.

Before upgrading now, I run the Skill first. It prompts you to input cluster information for downstream analysis:

After collecting that, it gathers commit diffs between the two versions, analyzes them, and generates an upgrade report highlighting potential risks, like this one:

We actually encountered this exact issue after the upgrade — having the report in advance made resolving it much easier.

Problem Domain: Why Upgrades Are So Hard

Let’s first clarify the core problem. The difficulty of cross-version StarRocks upgrades isn’t the “upgrade operation” itself — it’s not knowing what will happen before upgrading.

Incompatible Changes Are Hard to Spot

Default config value changes, session variable modifications, BE config tweaks between versions are often buried in thousands of commits. The traditional approach is to manually read Release Notes, but many behavioral changes aren’t documented in RNs at all.

Impact Scope Is Hard to Assess

A single config default change can have cascading effects through indirect call chains. For example, transform_type_prefer_string_for_varchar changing from false to true looks like just a default value tweak, but it indirectly causes materialized view invalidation through MV re-activation. This kind of indirect impact chain is virtually impossible to catch by eye.

Cluster-Specific Risks Can’t Be Quantified

Different clusters have different configurations (fe.conf/be.conf), deployment methods (K8s/VM), and scales (MV count, table count). Generic upgrade advice can’t cover risks specific to your cluster. The same default value change poses very different risks: if you’ve already overridden it in your conf, the risk is low; but if you happen to use the old default, the upgrade changes behavior directly.

Shortcomings of Existing Approaches

The PR-by-PR analysis is especially treacherous. A PR diff only shows the changed code snippet — you can’t see the class context or upstream/downstream call relationships. For the transform_type_prefer_string_for_varchar example, the PR diff merely modifies a default value in Config.java, but you can’t see that AnalyzerUtils.transformTableColumnType() reads this config, MaterializedViewAnalyzer calls it, and AlterJobMgr.reActivateMV() indirectly triggers MV re-parsing. This complete indirect impact chain is absolutely invisible from a PR diff alone.

Core Design Choice: Full Source Code Scanning

Based on the analysis above, the tool makes a fundamental design choice: it must run in the StarRocks source code root directory, rather than reading GitHub diffs PR by PR.

The reason is straightforward:

In short: no source context, no deep analysis.

Design Philosophy: Prefer False Positives Over False Negatives

The tool’s core design philosophy is prefer false positives over false negatives.

The reason is simple: the cost of upgrade risks is asymmetric. Missing an incompatible change could cause a production incident, while a false positive only adds manual verification work. So the tool employs a multi-layered scanning strategy: 11 specialized Scanners covering known risk patterns + per-commit Tier classification to ensure nothing is missed.

Overall Architecture

The tool’s workflow is divided into four phases. Here’s the big picture:

Phase 1: Data Collection

This is the foundation of the entire tool, implemented by starrocks_upgrade.py. It does quite a lot:

Git Commit Diff Collection

It uses git log branchA..branchB to get commits unique to the target branch, then classifies each commit. There’s a key optimization here — using custom delimiters (SOH/STX) to fetch all commit details in a single git log call, avoiding N+1 queries.

Commit Tier Classification

Not every commit needs deep analysis. The tool classifies commits into four tiers:

This way, HIGH/MEDIUM commits get deep analysis, while LOW/SKIP commits don’t waste resources.

11 Specialized Scanners

This is the most critical part of the tool, covering 11 dimensions of upgrade risk:

FE side:

• Config Scanner — scans @ConfField config changes in Config.java
• Session Variable Scanner — scans @VarAttr variable changes in SessionVariable.java
• System Variable Scanner — scans GlobalVariable.java
• Auth Scanner — scans AuthenticationManager.java, PrivilegeManager.java

BE side:

• BE Config Scanner — scans CONF_* macro definitions in config.h
• Storage Format Scanner — scans segment_format.h, tablet_meta.h

IDL/Protocol:

• Protocol Scanner — scans .thrift / .proto file changes
• Parser Scanner — scans StarRocksParser.g4, AstBuilder.java

Data/Types:

• Charset/Collation Scanner — scans Collation*.java
• Type System Scanner — scans ScalarType.java / Column.java
• MV Scanner — scans MaterializedView.java, MVRefreshParams.java

Every Scanner follows the same workflow:

Config Scanner’s State Machine Parsing

This deserves a closer look, since Config.java parsing is the most complex part of the tool.

Java annotations can span multiple lines:

1
2
3

@ConfField(mutable = true, comment = "Whether to prefer string type "
        + "for fixed length varchar column in materialized view creation/ctas")
public static boolean transform_type_prefer_string_for_varchar = true;

So the parser uses a line-by-line state machine approach:

The state machine tracks ( and ) pairing, concatenates multi-line annotations, then parses the mutable and comment attributes. Compared to simple regex matching, this approach correctly handles various edge cases.

BE Config Parsing

The BE side uses C++ macro definitions for configuration, requiring a completely different parsing approach:

1
2

CONF_Bool(datacache_auto_adjust_enable, "false")     // Not runtime-modifiable
CONF_mBool(lake_enable_alter_struct, "true")          // Runtime-modifiable (m prefix)

The regex CONF_(m?\w+)\((\w+),\s*"([^"]*)"\) extracts everything in one pass. Note that the m prefix indicates mutable — runtime-modifiable.

Cluster Config Conflict Detection

This is the feature I find most useful. The risk of the same default value change varies dramatically across scenarios:

This precise distinction is far more useful than vaguely saying “some config default changed.”

Deployment-Aware

The tool also generates deployment-specific risk alerts based on the cluster’s deployment method:

For example, in a K8s environment, FE Pod restarts trigger MV re-activation. If there are MV-related code changes, this could cause schema incompatibilities. In VM environments, the focus is more on upgrade order (BE first, then FE).

Phase 2: Commit Diff Analysis

Phase 1 saved the full diffs of HIGH/MEDIUM commits. Phase 2 is executed by AI Agents, using parallel subagents for deep compatibility analysis of commits.

Since cross-version diffs typically have a large number of commits (1361 HIGH tier commits for 3.3→3.5), sequential analysis is impractical. So commits are grouped by module, with 5-8 commits per group assigned to a parallel subagent:

Each subagent outputs structured analysis results: compatibility_impact, impact_type, severity, error_scenario, reproduction, rollback.

Phase 3: Deep Impact Analysis

All CRITICAL/HIGH level findings from Phase 2’s output + Phase 1’s Scanner results require further deep analysis. Each (or each batch of related) findings is assigned a parallel subagent that traces call chains via grep in the source tree.

This is one of the tool’s most distinctive designs — system lifecycle entry-point tracing. A config change may not be directly referenced by lifecycle code, but reaches it through an indirect call chain:

1
2
3
4

transform_type_prefer_string_for_varchar (Config)
  └─ AnalyzerUtils.transformTableColumnType() (direct caller)
       └─ MaterializedViewAnalyzer (indirect caller)
            └─ AlterJobMgr.reActivateMV() (system lifecycle entry: triggered on FE restart)

Without tracing this indirect path, you’d miss the critical risk of “MV re-activation failure after FE restart.”

Phase 4: Report Synthesis

All analysis results from Phases 1-3 are synthesized into a structured upgrade report.

The report’s core design principles:

1. INCOMPATIBLE CHANGES at the top: The most critical information comes first, sorted by CRITICAL > HIGH
2. Error scenarios categorized by trigger timing: After FE restart / After CN restart / Daily queries / During upgrade
3. Cluster-specific conflict detection: Only conflicts relevant to the user’s cluster configuration are shown
4. Actionable Upgrade Checklist: Every step is concrete and executable

Full Data Flow Diagram

Looking at Phase 1’s data flow as a whole makes it clearer:

Unified Impact Model

All Scanner findings use a unified four-dimensional impact model:

Every finding includes a four-dimensional assessment, making it easy to filter and aggregate by dimension.

Summary

The design philosophy of this tool can be distilled into these key points:

1. Source code is truth: All analysis is built on the complete source tree, not on PR diff snippets returned by GitHub API. No source context, no deep analysis.

2. Layered processing: Not every commit deserves deep analysis. The tier classification strategy ensures critical commits get deep analysis while low-risk commits don’t waste resources.

3. Specialized Scanners + AI Agent combination: Python scripts handle deterministic data collection and pattern matching (11 Scanners), while AI Agents handle uncertain deep analysis (call chain tracing, impact assessment). Each plays to its strengths.

4. Cluster-specific: Instead of generic advice, it cross-references the user’s actual fe.conf/be.conf to precisely identify cluster-specific risks.

5. Prefer false positives over false negatives: The cost of upgrade risks is asymmetric — the cost of a missed finding far outweighs a false alarm.

There are also limitations: Protocol/Parser Scanner precision is limited, indirect call chain tracing depends on AI Agent capability, runtime behavioral changes can’t be detected, and large repo performance is an issue (6000+ commits take 30+ minutes). These are areas for future improvement.

If you also maintain StarRocks clusters and frequently need cross-version upgrades, give this tool a try. At least in my case, it helped me discover several incompatible changes that weren’t mentioned in the Release Notes.

For large-scale projects like this, complex contextual analysis is exactly where LLMs excel — making them perfectly suited for this kind of previously manual labor-intensive work.

最近在搞 StarRocks 的跨版本升级（3.3 → 3.5），中间踩了不少坑。我之前也写过一篇 StarRocks 升级注意事项记录了手动升级的流程，但那只是针对小版本（3.3.3 → 3.3.9）的升级。

跨大版本升级完全是另一回事——3.3 到 3.5 中间有 6000+ 个 commit，里面藏着各种不兼容变更：配置默认值变了、Session Variable 改了、Protocol 字段删了……人工逐个审查根本不现实，漏一个关键变更就可能导致生产事故。

于是我就想：能不能用 AI 来帮我干这活？经过一段时间的迭代，我用 Claude Code 手搓了一个 StarRocks 升级风险扫描工具（starrocks-upgrade skill），这篇文章就来聊聊它的设计原理。

现在升级之前会先执行一次 Skill，它首先会让你输入一些集群信息方便后面做具体的分析：

收集完成之后便会收集差异版本之间的 commit 信息开始分析，最终生成一个升级报告，给出一些潜在的风险，比如这个：

我们在升级之后确实遇到了这个问题，提前有了这份报告之后解决起来自然也要轻松许多。

问题域：为什么升级这么难

先说清楚我们要解决的核心问题。StarRocks 跨版本升级的难点不在于”升级操作”本身，而在于升级前不知道会发生什么。

不兼容变更难以发现

版本间的配置项默认值变化、Session Variable 变更、BE 配置修改等，往往隐藏在几千个 commit 中。传统做法是人工阅读 Release Notes，但很多行为变更根本不会记录在 RN 里。

影响范围难以评估

一个配置项的默认值变化可能通过间接调用链产生连锁反应。比如 transform_type_prefer_string_for_varchar 从 false 变为 true，看起来只是改了个默认值，但它会通过 MV re-activation 间接导致物化视图失效。这种间接影响链靠肉眼根本发现不了。

集群特定风险无法量化

不同集群的配置（fe.conf/be.conf）、部署方式（K8s/VM）、规模（MV 数量、表数量）各不相同，通用的升级建议无法覆盖特定集群的风险。同样是默认值变了，你的集群如果已经在 conf 中覆盖了，风险就很低；但如果你用的恰好是旧默认值，升级后行为就直接变了。

现有方案的不足

特别是逐 PR 分析，这是最容易掉进去的坑。一个 PR 的 diff 只是变更的代码片段，你根本看不到变更所在的类与上下游调用关系。比如上面提到的 transform_type_prefer_string_for_varchar，PR diff 中只是修改了 Config.java 中的一个默认值，但你看不到 AnalyzerUtils.transformTableColumnType() 在读这个配置、MaterializedViewAnalyzer 调用了它、AlterJobMgr.reActivateMV() 又间接触发了 MV 重新解析——这条完整的间接影响链，只看 PR diff 是绝对看不出来的。

核心设计选择：源码全量扫描

基于上面的分析，工具做了一个根本性的设计选择：必须在 StarRocks 源码根目录下运行，而不是逐个 PR 读取 GitHub 上的 diff。

这个选择的原因很简单：

简单来说：没有源码上下文，就没有深度分析。

设计哲学：宁可误报也不漏报

这个工具的核心设计哲学是 prefer false positives over false negatives。

原因很简单：升级风险的成本是非对称的。漏报一个不兼容变更可能导致生产事故，而误报只是增加了人工验证的工作量。所以工具采用了多层级扫描策略：11 个专项 Scanner 覆盖已知风险模式 + 逐 commit Tier 分类确保无遗漏。

整体架构

整个工具的工作流分为四个阶段，先看一张全局视图：

Phase 1：数据收集

这是整个工具的基础，由 starrocks_upgrade.py 实现。它要做的事情很多：

Git Commit Diff 采集

通过 git log branchA..branchB 获取目标分支独有的 commits，然后对每个 commit 做分类。这里有个关键优化——使用自定义分隔符（SOH/STX）通过单次 git log 调用获取所有 commit 的完整信息，避免 N+1 查询。

Commit Tier 分类

不是所有 commit 都需要深度分析。工具把 commit 分成四级：

这样 HIGH/MEDIUM 的 commit 得到深度分析，LOW/SKIP 不浪费资源。

11 个专项 Scanner

这是工具最核心的部分，覆盖了升级风险的 11 个维度：

FE 侧：

• Config Scanner — 扫描 Config.java 中的 @ConfField 配置项变更
• Session Variable Scanner — 扫描 SessionVariable.java 中的 @VarAttr 变量变更
• System Variable Scanner — 扫描 GlobalVariable.java
• Auth Scanner — 扫描 AuthenticationManager.java、PrivilegeManager.java

BE 侧：

• BE Config Scanner — 扫描 config.h 中的 CONF_* 宏定义
• Storage Format Scanner — 扫描 segment_format.h、tablet_meta.h

IDL/协议：

• Protocol Scanner — 扫描 .thrift / .proto 文件变更
• Parser Scanner — 扫描 StarRocksParser.g4、AstBuilder.java

数据/类型：

• Charset/Collation Scanner — 扫描 Collation*.java
• Type System Scanner — 扫描 ScalarType.java / Column.java
• MV Scanner — 扫描 MaterializedView.java、MVRefreshParams.java

每个 Scanner 的工作模式都一样：

Config Scanner 的状态机解析

这里值得展开说说，因为 Config.java 的解析是整个工具中最复杂的部分。

Java 注解可能跨多行：

1
2
3

@ConfField(mutable = true, comment = "Whether to prefer string type "
        + "for fixed length varchar column in materialized view creation/ctas")
public static boolean transform_type_prefer_string_for_varchar = true;

所以解析器采用了逐行状态机模式：

状态机跟踪 ( 和 ) 的配对，将多行注解拼接后再解析 mutable 和 comment 属性。相比简单的正则匹配，这种方式能正确处理各种边界情况。

BE Config 解析

BE 端使用 C++ 宏定义配置，解析方式完全不同：

1
2

CONF_Bool(datacache_auto_adjust_enable, "false")     // 不可运行时修改
CONF_mBool(lake_enable_alter_struct, "true")          // 可运行时修改 (m 前缀)

正则 CONF_(m?\w+)\((\w+),\s*"([^"]*)"\) 一把就能提取出来，注意 m 前缀表示 mutable，可运行时修改。

集群配置冲突检测

这是我觉得最有用的功能。不同场景下同一个默认值变化的风险完全不同：

这种精确区分比泛泛地说”某个配置默认值变了”有用得多。

部署方式感知

工具还会根据集群的部署方式生成特定风险提示：

比如 K8s 环境下，FE Pod 重启会触发 MV re-activation，如果有 MV 相关代码变更，可能导致 schema 不兼容；VM 环境下则更关注升级顺序（BE 先 FE 后）。

Phase 2：Commit Diff 分析

Phase 1 保存了 HIGH/MEDIUM commit 的完整 diff。Phase 2 由 AI Agent 执行，利用并行 Subagent 对 commit 进行深度兼容性分析。

由于跨版本 diff 的 commit 数量通常很大（3.3→3.5 有 1361 个 HIGH tier commit），逐个串行分析不现实。所以按模块分组，每组 5-8 个 commit 分配给一个并行 Subagent：

每个 Subagent 输出结构化的分析结果：compatibility_impact、impact_type、severity、error_scenario、reproduction、rollback。

Phase 3：深度影响分析

Phase 2 的输出 + Phase 1 的 Scanner 发现中，所有 CRITICAL/HIGH 级别的发现需要进一步深度分析。每个（或每批相关的）发现分配一个并行 Subagent，在源码树中 grep 追踪调用链。

这是工具最独特的设计之一——系统生命周期入口追踪。一个配置变更可能不直接被生命周期代码引用，但通过间接调用链到达：

1
2
3
4

transform_type_prefer_string_for_varchar (Config)
  └─ AnalyzerUtils.transformTableColumnType() (直接调用方)
       └─ MaterializedViewAnalyzer (间接调用方)
            └─ AlterJobMgr.reActivateMV() (系统生命周期入口: FE 重启时触发)

如果不追踪这条间接路径，就会漏掉”FE 重启后 MV re-activation 失败”这个关键风险。

Phase 4：报告综合

将 Phase 1-3 的所有分析结果综合为一份结构化的中文升级报告。

报告的核心设计原则：

1. INCOMPATIBLE CHANGES 置顶：最关键的信息放在最前面，按 CRITICAL > HIGH 排序
2. 按触发时机分类报错场景：FE 重启后 / CN 重启后 / 日常查询 / 升级过程中
3. 集群特定的冲突检测：只有与用户集群配置相关的冲突才展示
4. 可操作的 Upgrade Checklist：每个步骤都是具体的、可执行的

数据流全图

把 Phase 1 的数据流串起来看会更清晰：

统一影响模型

所有 Scanner 的发现都使用统一的四维影响模型：

每个发现都附带四维评估，便于按维度筛选和汇总。

总结

这个工具的设计思路可以归结为以下几点：

1. 源码是真理：所有分析都建立在完整的源码树上，而不是 GitHub API 返回的 PR diff 片段。没有源码上下文，就没有深度分析。

2. 分层处理：不是所有 commit 都值得深度分析，Tier 分类的分层策略确保关键 commit 得到深度分析，低风险 commit 不浪费资源。

3. 专项 Scanner + AI Agent 的组合：Python 脚本做确定性的数据收集和模式匹配（11 个 Scanner），AI Agent 做不确定性的深度分析（调用链追踪、影响评估）。各取所长。

4. 集群特定：不是给出通用建议，而是结合用户实际的 fe.conf/be.conf，精确识别集群特定风险。

5. 宁可误报也不漏报：升级风险的成本是非对称的，漏报的代价远大于误报。

当然也有局限性：Protocol/Parser Scanner 精度有限、间接调用链追踪依赖 AI Agent 的能力、无法检测运行时行为变化、大仓库性能问题（6000+ commit 需要 30 分钟以上）。这些也是后续改进的方向。

如果你也在维护 StarRocks 集群并且经常需要跨版本升级，可以试试这个工具。至少在我这边，它帮我发现了好几个 Release Notes 里没提到的不兼容变更。

对于这种大型项目，存在复杂的上下文分析完全是现在 LLM 擅长的地方，非常适合拿来做这种以前的人工体力活。

相信现在 AI Coding 已经占据工作中大部分代码了，甚至很多人就直接交给 AI 来写，自己只做 review。

再有甚者 review 都不做了，直接全面交给 AI，自己只做产品经理提需求、验证功能逻辑是否正确——也就是现在很流行的 Vibe Coding。

前段时间我自己用 Vibe Coding 写了一个 macOS 原生的 APP，以此来判断 Vibe Coding 是否能让我在一个完全不熟悉的领域解决一个特定的问题。

项目地址：https://github.com/crossoverJie/SkillDeck/

SkillDeck 是一个 macOS 原生的 AI Agent Skills 管理工具，提供了统一仪表盘、Skills 市场浏览、一键安装更新、Agent 分配（symlink 管理）等核心功能，让多个 AI Agent 的 Skills 管理更直观。
详细介绍参考：skilldeck-intro

这个 APP 经过多轮迭代，已经能解决 skill 管理的一些问题了，所以我便着手开发自己的第一个 macOS 产品。

为什么要做 ClipShelf

想必大家在日常使用过程中都会用到「剪贴板」相关的 APP。在这之前，我一直使用的是 Paste APP。

当初选择它，主要是看中它的颜值比较高。

但它的售价并不便宜。类似的 APP 其实也蛮多的，还有一些开源替代方案，不过都或多或少缺一些我需要的功能。

由于之前已经验证了使用 AI Coding 可以解决我开发不熟悉领域的问题，所以这次我就想着不如自己做一个定制化的 APP，满足自己需求的同时也可以提供给有类似需求的人。

ClipShelf 功能点

说干就干。我花了一两个月的时间来开发这个 APP，给它命名为 ClipShelf，已经上架了 AppStore。

剪贴板管理器相关的常规功能都支持，在这基础之上，额外还支持局域网内部的剪贴板数据共享，这对使用非苹果生态的设备非常有用。

后续还会新增 OCR 截图直接翻译的功能，由于是自己可控的 APP，可以灵活地新增和调整功能。对这个 APP 感兴趣的朋友也欢迎给我提反馈。

兑换码

我为大家准备了 20 个兑换码，欢迎体验后给出反馈，也请大家在 App Store 帮我打个分或者留个评论。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=KHPTN7ATFN8TPMEH7A

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=KPA4ATAPLTYE6KE334

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=X8HJLKETFRW6AAL38T

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=WWELMTYTJPANJYHFXT

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=FA63KEPTLE3J6KTRF3

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=3FY7THPYFY3HLWLAFK

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=63LPL6EWRX4KN34R7F

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=ETFTFLNWY3X4XYW87A

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=J6438JMX4HRR63JNKJ

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=W7MF4L3W7WHKMPERL4

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=LW4NHJYFYPH7EM6RJ8

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=MT44PKNMMN6Y3L764W

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=PLHP3E86PEHF4MLJ4N

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=Y8KYAAMF7HH7JHJ3KN

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=RLH4A33RPXWYLY3TXW

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=KRET6TTJHLK67FY7FF

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=4W4T3AMPNEFR3LYFXJ

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=FA3HT3LKN4HEMYYWEN

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=7JX3RKTKRYPYLH6FYP

https://apps.apple.com/redeem?ctx=offercodes&id=6760993477&code=PRLYHYP7HA34TPYJH8

复制链接到浏览器里打开就可以直接兑换。已经兑换了的朋友请在评论区留言，以防其他人重复兑换。

如果确实刚需但没抢到兑换码，也可以加我微信 crossoverChen 私聊，我会单独发兑换码。

AI Coding 的理解

经过这两次 AI Coding 实践，我发现在 AI 时代更需要的是产品经理或者说项目 owner 这样的全局能力。

它不再需要我们像以前作为程序员一样，关注于某一个功能或者某一个代码架构的具体设计。我们交付的也不再是代码或者一个 package，而是一个完整的产品——这个完整的产品包含前期需求调研、UI 设计、编码开发、发布运维、市场推广、运营等一系列能力。

对于一个产品能否做成，编码能力反而是最弱的一环，更需要的是宣发能力、产品 UI 交互。而我们以前传统程序员的特有的编码能力被 AI 极大地磨平了，对产品经理来说是重大的利好。

当然，对于一个长生命周期的产品，或者说是一个复杂的大型软件架构来说，一个资深开发者的能力还是非常有必要的。

如果说你只让产品经理自己来维护调试 bug，那将非常灾难。在目前 AI 的能力下，复杂的系统仍然需要资深研发工程师。

但如果说我们只是解决某一个小的、具体领域的特定问题，使用 AI Coding 自己作为产品 owner 来进行发布迭代和市场运营，是完全足够的。

总结

后续我还会推出一些其他的 APP，大家敬请期待。

也会继续分享独立开发的一些经验，感兴趣的朋友可以持续关注，也欢迎加我微信进行探讨。

我创建了一个独立开发的交流群，感兴趣的朋友可以进群一起讨论。

最近我一直在折腾项目文档生成的事情。之前写过两篇关于 deepwiki 的文章：deepwiki-rag-principle 讲了 RAG 原理，deepwiki-optimize-line-number 聊了给代码加行号的优化。

经过几轮迭代，搞了两个优化：

• 代码加上行号前缀
• 基于 Proto 文件生成确定性目录

这两个优化背后其实是同一个思路：把确定的东西明确告诉 AI，不确定的才让 AI 来发挥。

LLM 擅长理解、归纳和总结，但精准计算和结构化数据生成这块确实不太行。分开处理，各取所长，效果就好很多了。

这些都是用开源的 deepwiki-open 来做的。

问题

虽然最终生成的内容效果还不错，但还有个让人头疼的问题：

需要为整个项目生成总结性的内容，比如项目架构、流程图、ER 图等。

这些数据得根据之前已经生成的内容来总结，但 deepwiki 的架构是每个页面独立生成的。而 ER 图这种，我们希望是基于已生成的内容再汇总生成。

在现有架构下实现这个比较困难，索性换个思路。

新方案

日常用 Claude Code（后面简称 CC）的时候发现，它可以精准定位到具体业务逻辑所在的代码片段，也能帮我们分析项目、提炼内容。

这不就是个完美的 Wiki 系统吗？直接让 CC 分析项目内容，生成静态页面，就能得到一个精准的 Wiki 了。

CC 也是通过一些内置 tools 来实现精准代码检索的，不需要 deepwiki 那种向量数据库，架构简单很多。

这里简单聊下 CC 的代码搜索原理。传统 RAG 方案会先把代码向量化存入数据库，然后通过语义相似度检索。但 CC 并没有走这条路，而是直接用了一套工具驱动（Tool-based）的检索机制：

这种设计的巧妙之处在于：LLM 不依赖向量化后的”模糊记忆”，而是像人类开发者一样，通过精确的工具调用来定位代码。比如要找某个函数定义，CC 可能会先 grep 找到候选文件，再用 Read 精读确认，最后用 LSP 验证引用关系——整个过程是确定性的、可解释的。

想了解更多细节可以参考 Anthropic 官方文档：Claude Code Overview

后续 repo 有更新，只需要让 CC 读取 git log 变更记录，自动更新修改的内容就行。

提炼 Skill

考虑内部项目众多，为了让其他项目也能复用这个能力，我把生成静态网站的过程写成了一个 Skill。其他项目只需要在 CC 里调用这个 Skill 即可。

目录结构大概长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

├── SKILL.md
├── skill.json
├── templates/
│   ├── page-architecture.md
│   ├── page-er.md
│   ├── page-features.md
│   └── page-service.md
└── wiki/
    ├── 01-系统架构.md
    ├── 02-核心功能.md
    ├── 03-ER图.md
    ├── index.html
    └── service/
        └── *.md

优缺点对比

deepwiki

优点：

• 可以一键生成整个项目，生成过程中不需要人工干预

缺点：

• 无法精准调整某个页面
• 对于需要汇总已生成数据的需求，架构无法满足

Claude Code 方案

优点：

• 可以精准调整每一个页面
• 数据可以做到非常精准

缺点：

• 无法一键生成结果，需要多轮对话调试
• 如果部署到服务器上，需要外部工具对 CC 进行管理

总结

其实这两个方案并不冲突，可以看成不同阶段的选择：

• 项目初期需要快速搭个文档框架 → deepwiki 一键生成
• 项目成熟需要精准可控的文档 → CC 方案慢慢打磨

CC 方案的核心优势在于可控性。虽然要多花点时间调试，但生成的内容质量确实更高，特别是涉及到跨文件关联分析的时候。

当然，CC 方案目前还不能完全自动化，这是最大的限制。不过随着 CC 生态的发展，相信后面会有更好的解法。让子弹飞一会。

最近我们在做一件非常危险的大事——把用了好几年的腾讯云企业版 Istio 服务网格迁移到社区开源版。

事情的起因是腾讯云突然宣布不再维护 Istio 服务网格了，后续也不会推出新版本。这就导致我们的网格一直停留在旧版本，进而连带着 k8s 这些基础组件也很难升级。可以说是血的教训：用托管服务一时爽，一旦厂商放弃维护，迁移成本还是得自己扛。

这事儿其实拖了很久，毕竟迁移涉及到的系统非常多，相当于要对「高速行驶的汽车更换轮胎」，稍有不慎就是车毁人亡。虽然已经测试验证的七七八八了，但一直不敢动手。

直到最近，我们利用 AI 对 Istio 关键代码进行了深入分析，从源头来确保迁移的可靠性——这也算 AI 在实际工程中的一个应用案例了。

迁移方案概览

我们采用的是双控制面并行 + 按 namespace 灰度迁移的策略，核心思路是：

1. 并行部署：在同一个集群里同时运行企业版和社区版两套控制面
2. 标签驱动：通过 namespace 的 istio.io/rev 标签决定 Pod 注入哪个版本的 sidecar
3. discoverySelectors：社区版控制面只感知打了特定标签的 namespace，实现隔离
4. 灰度切换：逐个 namespace 切换，随时可回滚

安装社区版控制面

首先安装社区版 Istio 控制面，指定一个独立的 revision 和 namespace：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  namespace: istio-1-16-5
spec:
  profile: minimal
  revision: istio-1-16-5
  meshConfig:
    enablePrometheusMerge: false
    accessLogFile: /dev/stdout
    # 关键：只感知带特定标签的 namespace
    discoverySelectors:
      - matchLabels:
          usergroup: istio-1-16-5
  values:
    global:
      istioNamespace: istio-1-16-5

discoverySelectors 是这次迁移的安全保证，确保社区版和企业版控制面不会互相干扰。

然后安装 IngressGateway：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  name: istio-public-api-ingressgateway
spec:
  profile: empty  # 不安装 CRD 或控制平面
  components:
    ingressGateways:
    - name: istio-ingressgateway
      namespace: istio-1-16-5
      enabled: true
      label:
        istio: oss-public-api-ingressgateway
  values:
    gateways:
      istio-ingressgateway:
        injectionTemplate: gateway
        runAsRoot: true

执行安装：

1
2

istioctl install -y -f istio-control-plane.yaml
istioctl install -f istio-gateway.yaml

使用 istioctl 工具安装

Namespace 切换流程

给要迁移的 namespace 打上标签：

1
2
3

labels:
  istio.io/rev: istio-1-16-5
  usergroup: istio-1-16-5

注意：标签打在 namespace 上之后，已有的 Pod 不会自动重启，需要手动 rollout restart 才会触发重新注入。

切换的核心机制是：MutatingWebhookConfiguration 根据 namespace 标签匹配。当 Pod 创建时，K8s API Server 会根据 namespace 的 istio.io/rev 标签路由到对应的 webhook，从而注入对应版本的 sidecar。

网关配置

Gateway CR 的 selector 与 Pod 标签做等值匹配：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
  name: istio-public-api-ingressgateway
  namespace: default
spec:
  servers:
    - port:
        number: 80
        name: http
        protocol: HTTP
      hosts:
        - '*.y7test.com'
  selector:
    istio: ingressgateway

迁移期间两套网关并存，各自连接自己的控制面：

DNS 切换时机：等新网关稳定后，修改 DNS 指向新 IP。TTL 期间两套网关同时承接流量。

关键源码验证

这次迁移最大的不同是，我们不只是「试试能不能跑」，而是深入到源码层面验证每个环节的可行性。

1. Sidecar 注入的 Revision 选择

注入由 MutatingWebhookConfiguration 的 namespaceSelector 决定。源码在 istioctl/pkg/injector/injector-list.go：

1
2
3
4
5
6
7
8
9
10
11
12
13

func getInjector(namespace *corev1.Namespace, hooks []admitv1.MutatingWebhookConfiguration) *admitv1.MutatingWebhookConfiguration {
    for _, hook := range hooks {
        for _, webhook := range hook.Webhooks {
            nsSelector, err := metav1.LabelSelectorAsSelector(webhook.NamespaceSelector)
            if err != nil { continue }
            // 关键：用 namespace 的当前标签做匹配
            if nsSelector.Matches(api_pkg_labels.Set(namespace.ObjectMeta.Labels)) {
                return &hook
            }
        }
    }
    return nil
}

结论：kubectl label ns <ns> istio.io/rev=self-1-16-5 修改标签后，新建的 Pod 会自动命中社区版的 webhook。

2. DiscoverySelectors 隔离机制

社区版 istiod 通过 discoverySelectors 决定感知哪些 namespace：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

func (d *discoveryNamespacesFilter) SelectorsChanged(
    discoverySelectors []*metav1.LabelSelector,
) (selectedNamespaces []string, deselectedNamespaces []string) {
    // 遍历所有 Namespace，匹配 selector 的入选
    for _, ns := range namespaceList {
        for _, selector := range selectors {
            if selector.Matches(labels.Set(ns.Labels)) {
                newDiscoveryNamespaces.Insert(ns.Name)
            }
        }
    }
    // ...
}

func (d *discoveryNamespacesFilter) Filter(obj any) bool {
    // 未配置 discoverySelectors 则允许所有
    if len(d.discoverySelectors) == 0 {
        return true
    }
    // 只处理选中 namespace 的资源
    return d.discoveryNamespaces.Contains(object.GetNamespace())
}

结论：标签变更实时生效，无需重启 istiod。

3. CA 根证书的自动下发

Namespace 入选后，NamespaceController 会自动将社区版 istiod 的 CA 证书写入该 namespace 的 istio-ca-root-cert ConfigMap：

1
2
3
4
5
6
7
8
9

func (nc *NamespaceController) insertDataForNamespace(o types.NamespacedName) error {
    meta := metav1.ObjectMeta{
        Name:      CACertNamespaceConfigMap,  // "istio-ca-root-cert"
        Namespace: ns,
    }
    // 写入自建 istiod 的根证书
    return k8s.InsertDataToConfigMap(nc.client, nc.configmapLister, meta,
        nc.caBundleWatcher.GetCABundle())
}

为什么关键：sidecar 的 pilot-agent 用这个证书验证 istiod 的 TLS 身份，证书对了才能建立 XDS 连接。

4. Sidecar 连接新 Istiod 的路径

注入模板中的 DiscoveryAddress 由 revision 和 namespace 计算得出：

1
2
3
4
5
6
7
8
9

func IstiodHost(ns string, revision string) string {
    istiod := "istiod"
    if isRevisioned(revision) {
        istiod = fmt.Sprintf("%s-%s", istiod, revision)
    }
    return fmt.Sprintf("%s.%s.svc", istiod, ns)
}

// 结果：istiod-self-1-16-5.istio-self.svc:15012

pilot-agent 启动时从挂载的 ConfigMap 读取根证书：

1
2
3
4
5

func (a *Agent) FindRootCAForXDS() (string, error) {
    // 默认路径：/var/run/secrets/istio/root-cert.pem
    rootCAPath = path.Join(CitadelCACertPath, constants.CACertNamespaceConfigMapDataName)
    // ...
}

结论：只要 webhook 注入正确，新 Pod 会自动连接到社区版 istiod，无需额外配置。

5. 跨控制面互通（ALLOW_ANY）

迁移期间，新 sidecar 可能需要访问旧 namespace 的服务。由于社区版 istiod 不感知旧 namespace，不会生成对应的 Cluster/Endpoint。此时流量会走 PassthroughCluster：

1
2
3
4
5
6
7
8
9
10
11

func buildOutboundCatchAllNetworkFiltersOnly(...) []*listener.Filter {
    var egressCluster string
    if util.IsAllowAnyOutbound(node) {
        // ALLOW_ANY 模式：未知流量直接透传到原始目标
        egressCluster = util.PassthroughCluster
    } else {
        // REGISTRY_ONLY 模式：未知流量丢弃
        egressCluster = util.BlackHoleCluster
    }
    // ...
}

结论：meshConfig.outboundTrafficPolicy.mode: ALLOW_ANY 确保迁移期间跨控制面的流量可以正常通行。

6. 网关路由隔离

新网关的路由只包含已迁移 namespace 的 VirtualService：

1
2
3
4
5
6
7
8

func (configgen *ConfigGeneratorImpl) buildGatewayHTTPRouteConfig(...) *route.RouteConfiguration {
    // ...
    for _, server := range servers {
        // PushContext 中的 VS 已经被 discoverySelectors 过滤过
        virtualServices = push.VirtualServicesForGateway(node.ConfigNamespace, gatewayName)
        // 旧 namespace 的 VS 不在其中 → 路由为空
    }
}

结论：新旧网关的路由天然隔离，不会出现流量错乱。

踩过的坑

证书不匹配

已经安装社区版 istio 后再安装企业版网关，启动失败，提示证书不匹配。原因是 sidecar 注入时使用了错误的 CA 证书。

证书不匹配错误

解决方案：手动修改企业版 deployment 的 label，使其匹配社区版的 revision。

503 错误

社区版网关出现 503，查看日志发现 upstream 连接失败。

503 错误及日志

解决方案：namespace 需要匹配 discoverySelectors 配置的 label，确保 istiod 能感知到该 namespace 的服务。

namespace 打上对应 label 后问题解决

不能用 --purge 卸载

安装社区版 istio 之后不能用 istioctl uninstall --purge 卸载，会把企业版的 CRD 也一并删掉。

解决方案：只能手动删除社区版相关的 deployment 和 webhook。

回滚失败

如果回滚到企业版失败，通常是社区版的 webhook 还在拦截请求。

解决方案：删除社区版的 MutatingWebhookConfiguration 和相关的 CRD。

迁移检查清单

迁移前

• 备份 CRD、namespace 标签、Gateway 配置
• 社区版 istiod 和网关启动并健康
• 确认 outboundTrafficPolicy: ALLOW_ANY 已配置
• 社区版 proxy-status 无 STALE

迁移单个 namespace

• 打上标签：istio.io/rev=self-1-16-5、usergroup=istio-1-16-5
• 确认 istio-ca-root-cert ConfigMap 已自动创建
• 滚动重启 deployment
• 验证 sidecar 连接新 istiod：istioctl proxy-status
• 验证跨命名空间调用正常
• 通过新网关访问该 namespace 服务正常

DNS 切换

• 新网关 External IP 稳定
• 修改 DNS 指向新 IP
• TTL 到期后监控新网关流量
• 保留旧网关至少 1 个 TTL 周期

迁移后

• 所有 namespace 的 proxy-status 显示新 istiod
• pilot_xds_push_errors_total 无增长
• 错误率与迁移前一致
• 旧网关流量降为 0 后下线企业版控制面

总结

这次迁移从筹备到最终执行拖了挺久，主要是涉及面广、风险高。但通过深入源码分析每个关键环节，我们对整个迁移过程有了更清晰的把控。

几个核心经验：

1. discoverySelectors 是隔离的关键：确保两套控制面互不干扰
2. Webhook 标签匹配决定注入版本：namespace 标签变更后要重启 Pod 才生效
3. ALLOW_ANY 保障灰度期间的互通：新 sidecar 可以访问旧服务
4. 网关路由天然隔离：新旧网关各自连接自己的控制面

当然，实际的迁移操作还是由我们人工来执行的，AI 在这个过程中主要提供了「理论支持」——帮我们快速定位源码逻辑、验证方案可行性。

这也让我感受到，AI 在复杂工程问题上的价值不只是「写代码」，更重要的是辅助理解复杂系统的工作原理，让我们在做高风险变更时更有底气。

毕竟，给高速行驶的汽车换轮胎，光靠胆子大是不够的，还得对汽车的每个零件都了如指掌。

参考链接：

• Istio 安装文档
• Sidecar 注入问题排查

上周末参加了一个我们重庆本地的一个 AI 分享会，分享了一些企业大模型与 Vibe Coding 的实战经验，现在把它整理成一篇 blog。

企业大模型应用实践

利用 AI 提高故障排查效率

首先是企业大模型的应用实践，我们利用现在的大模型结合可观测性来实现故障的自动分析。

最终可以实现的效果如下图所示，他可以直接分析当前 trace 下的所有链路、日志、指标、profile、内存布局，代码等信息整理在一起发给大模型，由大模型总结整理给出结论。

其实开发日常排查问题也是这样的过程，只是将它自动化了而已。

对可观测性有了解的朋友应该对这张图很熟悉，通过 trace_id 可以在日志系统里获取到日志、通过 trace 的时间戳也能获取到一个时间范围的指标监控数据。

本质上都是可以获取到这些结构化的数据，代码也是一样的，gitlab 也有相关的接口可以获取到代码信息。

这里的重点便是上下文可以给多少，给的越相关效果越好，目前我们也还在调试，给的信息多了可能也会导致大模型的幻觉。

重点：

• 尽可能能多的采集应用数据（trace、日志、指标、代码、profile 等信息）
• 上下文内容尽量聚焦
• 数据获取的方式可以直接使用基建数据的接口或者是 MCP（推荐有接口就通过接口获取）

定制属于自己的 deepwiki

去年下半年火过一段时间的一个项目：deepwiki，利用大模型将 github 上开源的项目做成一个可多次对话的 wiki，方便我们更好的理解项目；下图是 openclaw 的 deepwiki。
我们内部也有类似的需求，需要将所有的代码 repo 做成一个 deepwiki，方便新人或者不熟的同事快速了解一个项目。

可以确定的数据不要交给 AI 生成

我们是用一个开源的 deepwiki-open 系统来改造的，生成出来的代码行数和业务逻辑基本上对不上，经过分析发现是 LLM 自己估算的。

后续经过优化，我们自己将代码里的行号带上发送给大模型，这个问题就基本上被解决，重点是不要让大模型做逻辑计算，有现成的数据便让他直接读取。

根据自己的业务做定制大模型应用

由于 deepwiki-open 这个项目是一个开源通用的项目，所以他没法根据自己项目的情况做优化。

比如他为了更加通用，默认对代码的分割算法是 text 分割，也就是按照英文单词进行分割，因为有可能你的项目都不是代码，而是内部的纯文本知识库。

但是对于大量代码场景会导致分割的代码片段不连贯，比如一个完整的函数被分割成了多个 chunk，导致大模型理解困难。

而更好的方案应该是根据不同的编程语言选择不同的 AST（抽象语法树）进行分割

通用方案存在的问题：

• 代码分割不够精准，需要使用指定语言的 AST（抽象语法树）进行分割。
• 目录生成太随意，应该根据项目的特征（前端后端、python、Java、Golang）生成目录树。

这是没有经过优化的目录结构，非常通用（重新生成之后就会变化），适合放到任何项目里面。

而相对应的是针对我们项目背景优化的目录结构；这样一样便知道好坏。

至于是如何优化的？那又回到了刚才的提到的：可以确定的内容就不要交给 AI 生成。

这里的目录结构我们是确定的，无论怎么重复生成都是这个目录机构，对于我们的 Java 项目来说，我们希望目录结构可以根据对外提供的 grpc 生成，这样就可以系统的结构化的来理解整个项目。

至于目录结构是如何生成的，那也很简单，就是解析下 grpc 的 proto 文件，提取出接口声明，然后再遍历生成目录就可以了。

同样的道理，对于前端项目、或者是 Python 你项目，他们的关注点都不太相同，我们需要针对性的优化，不然就只能得到一个可用的玩具。

我的经验：

• 任何可以确认的内容，尽量直接告诉大模型，而不是让他进行推理
• 大模型应用要做定制优化，通用的方案只能作为玩具。

Vibe Coding 实战经验分享

接下来要分享的是我最近 Vibe Coding 的一些经验

首先是工具的推荐，我的工作流是好用的基座大模型+ Code Agent（Claude Code/copolit-cli) + Skills

好的大模型可以节约很多时间，推荐有条件的尽量使用 Claude 的 opus4.6

而 Code Agent 可以直接帮我们编写 编译 调试代码，直接做事情，再也不需要手动复制聊天窗口里的代码到 IDE 里面再手动运行了。

Skill 可以将自己常用的工作流整理成一个可复用的模块，也可以使用行业大佬整理的 Skill，相当于偷师了各种大佬的最佳实践。

以上三者结合起来真的可以将个人打造成以往的产研小团队。

我的常用工具：

• Claude Opus4.6 / Gemini3
• Claude Code / Copilot-CLI
• Skill：偷师行业大佬经验，或者复用自己已有的工作流

刚才的那个本地 Skill 管理工具就是我用 Claude Code vibe Coding 开发出来的，在 github 上也有一定关注度，也证明纯靠 vibe Coding 也是可以解决问题的。

下面是这段时间总结的一些 VibeCoding 经验：
开发一个具体 feature 的时候尽量聚焦一些，每次都使用独立的 context 以及 分支开发，这样不容易出现幻觉

完成一个功能之后记得提交代码，这样更方便回滚，尽量不要用自然语言让 AI 进行回滚，而是自己操作 git 进行回滚。

这又和刚才提到的，能确定的事情尽量别让 AI 去做。

AI coding 过程中，自己消耗大量 token 总结出来的内容，如果暂时用不上可以让它整理成一个文档，方便自己下次直接加载这份文档恢复上下文，避免再次分析消耗 token。

或者直接使用 claude –resume 恢复上下文

定期使用 /init 命令构建 claude.md，使得 Claude 的上下文更加准确

对于自己不熟的代码和领域，多让大模型写日志，方便他后续排查问题

在 claude.md 里声明单测优先，任何 PR 的创建都需要通过单测，尽可能的保证代码质量

多利用项目记忆以及全局记忆来约束大模型的行为，比如代码风格、输出的标准等。

经验总结：

• 一个 feature 一个 context，避免上下文过长
• 一个 feature 一个分支，尽量使用 git 命令回滚，而不是让 AI 进行回滚（容易出错，能确定的事情就尽量确定）
• 保存好消耗大量 token 总结的文档（复杂功能的代码分析），后续可以复用，也可以使用 claude resume 恢复之前的会话
• 定期使用 /init 命令初始化 claude.md
• 关键逻辑让大模型多写日志，方便后续让他排查问题
• 在 claude.md 里声明单测优先（TDD），任何 PR 的创建都需要通过单测，尽可能的保证代码质量
• 多利用项目记忆以及全局记忆来约束大模型的行为，比如代码风格、输出的标准等。

独立开发工具链

• Gemini 生成产品 PRD 文档
• 将 PRD 导入 https://stitch.withgoogle.com/ & pencil.dev 生成 UI 设计稿
• 将 UI 设计稿导出成 html，或者是 MCP 到 Figma
• 由 Claude Code 读取设计稿实现页面
• app logo 使用 superdesign MCP 生成 SVG

总结

正如 anthropic CEO 在之前的播客里提到：未来 software engineer 这个 title 真的会消失，取而代之的可能是 product manager 或者叫做 builder。

放到前两年我是不太信的，这几个月我充分使用 AI Coding 之后我信了，对大部分开发者来说既是挑战也是机遇。

最近在用 deepwiki-open 给内部的 Java 项目生成 wiki，发现一个很明显的问题：生成的 wiki 页面里引用的代码行号经常不准确，看起来是 LLM 根据上下文自己推算的。

比如一个函数明明在第 503 行，生成出来的 wiki 里可能标注成第 510 行甚至更离谱的数字。

之前我在 DeepWiki 一个常用 RAG 应用的开发流程 里分析过它的整体流程，本文主要聊聊我们在实际使用中遇到的两个问题以及对应的优化方案。

问题分析：LLM 为什么算不对行号

在我们的优化版本中，已经使用 tree-sitter 基于 AST 将代码进行拆分存入了本地的向量数据库。

第一版存储的 chunk 格式是这样的：

1
2
3
4
5
6
7
8
9
10

<file path="src/main/java/com/example/Client.java">
<chunk start_line="503" end_line="581">
package com.example;

import cn.hutool.core.util.ZipUtil;
import com.google.common.collect.Lists;
import com.google.protobuf.ByteString;
// ... 后面的代码
</chunk>
</file>

看起来我们已经告诉 LLM 这段代码从第 503 行开始到第 581 行结束了，但问题在于：chunk 内部的代码是原始文本，没有行号标记。

当 LLM 需要引用某个具体函数的行号时，它必须从 start_line=503 开始，自己数第几行是哪个函数。

这对 LLM 来说太难了——众所周知 LLM 不擅长数学计算，让它去数几十行代码然后算出 503 + 偏移量 = 实际行号，幻觉就不可避免了。

这就好比你让一个文科生做加法题还不让用计算器，虽然能算但准确率堪忧。

优化一：给代码加上行号前缀

既然 LLM 算不准，那最好的办法就是直接把结果给它，让它只需要”读”而不需要”算”。

改动思路

核心改动很简单，在把 chunk 内容发给 LLM 之前，给每一行代码加上实际行号前缀：

1
2
3
4
5
6

def _add_line_numbers(text: str, start_line: int) -> str:
    """给代码文本的每一行添加行号前缀"""
    return '\n'.join(
        f"{start_line + i}. {line}"
        for i, line in enumerate(text.split('\n'))
    )

优化前后对比

优化前发给 LLM 的数据：

1
2
3
4
5
6

<chunk start_line="503" end_line="581">
package com.example;

import cn.hutool.core.util.ZipUtil;
import com.google.common.collect.Lists;
</chunk>

优化后发给 LLM 的数据：

1
2
3
4
5
6

<chunk start_line="1" end_line="44">
2.
3. import cn.hutool.core.util.ZipUtil;
4. import com.google.common.collect.Lists;
5. import com.google.protobuf.ByteString;
</chunk>

LLM 现在要引用 ZipUtil 的导入行，直接看到前缀 3. 就知道是第 3 行，不需要做任何计算。

具体改动文件

一共改了 4 个文件：

1. api/websocket_wiki.py — 添加 _add_line_numbers() 工具函数，在构建 chunk 内容时加上行号前缀：

1
2
3
4
5

if start_line is not None and end_line is not None:
    numbered_text = _add_line_numbers(doc.text, start_line)
    doc_parts.append(
        f'<chunk start_line="{start_line}" end_line="{end_line}">\n{numbered_text}\n</chunk>'
    )

2. api/websocket_wiki.py 的 prompt 部分 — 更新 <line_number_rules> 指令，告诉 LLM 直接读取行号前缀而不是自己计算：

1
2
3
4
5

"<line_number_rules>"
"Each line in the code context is prefixed with its actual line number (e.g., '100. code here'). "
"When citing source lines, read the line numbers directly from these prefixes. "
"Do not count or calculate line numbers yourself. "
"</line_number_rules>"

Token 成本

每行增加约 4-6 个字符（比如 503. ），一个典型的 chunk 30-40 行，大概增加 150 字符。10-20 个 chunks 总共增加约 1500-3000 字符（约 500-1000 tokens），成本基本可以忽略。

优化二：基于 Proto 文件生成确定性目录

第二个问题是 wiki 的目录结构。

DeepWiki 默认的做法是把 repo 的目录树和 README 丢给 LLM，让它自由发挥来生成 wiki 目录（虽然有一些限制提示词，比如输出目录结构的大概要求）。这在通用场景下是合理的，但对我们的内部 Java 项目来说效果不好。

原因很简单：我们所有的业务都是围绕着 gRPC 接口来的，理想的 wiki 目录应该是按 Service 和 RPC 方法来组织的，而不是让 AI 自由发挥出一堆”Architecture Overview”、”Getting Started” 之类的通用章节。

改动思路

写代码读取 repo 里所有的 *.proto 文件，解析出所有的 Service 和 RPC 接口列表，然后直接构建出确定性的目录结构给前端，绕过 LLM 的目录生成步骤。

具体流程：

1. 扫描 repo 里所有 .proto 文件
2. 用正则解析出 package、service、rpc 定义
3. 构建固定格式的 WikiStructure JSON
4. 前端检测到 proto 文件存在时，调用这个接口替代 LLM 生成

核心代码：proto_parser.py

新增了一个 api/proto_parser.py 文件，主要做三件事：

扫描 proto 文件：

1
2
3
4
5
6
7
8
9
10
11

def find_proto_files(repo_path: str, excluded_dirs=None) -> List[str]:
    """遍历 repo 目录，返回所有 .proto 文件路径"""
    skip = set(DEFAULT_EXCLUDED_DIRS)  # 排除 vendor、node_modules 等
    proto_files = []
    for root, dirs, files in os.walk(repo_path):
        dirs[:] = [d for d in dirs if d not in skip]
        for f in files:
            if f.endswith(".proto"):
                proto_files.append(os.path.join(root, f))
    proto_files.sort()
    return proto_files

解析 proto 内容：

1
2
3
4

_RE_PACKAGE = re.compile(r"package\s+([\w.]+)\s*;")
_RE_RPC = re.compile(
    r"rpc\s+(\w+)\s*\(\s*(stream\s+)?(\w+)\s*\)\s*returns\s*\(\s*(stream\s+)?(\w+)\s*\)",
)

通过平衡大括号匹配来提取 service block，再用正则提取每个 RPC 方法的签名，包括方法名、请求类型、响应类型以及是否是 streaming。

构建 wiki 目录结构：

生成的目录包含 3 个固定章节 + 每个 Service 一个独立章节：

每个 RPC 方法的页面标题直接用方法签名，比如 GetOrder(GetOrderRequest) returns (GetOrderResponse)，非常清晰。

前端改动：page.tsx

在 src/app/[owner]/[repo]/page.tsx 里新增了一个检测逻辑：

1
2
3

// 检测 repo 是否包含 proto 文件
// 如果有，调用 /api/proto/wiki_structure 获取确定性目录
// 如果失败，fallback 到原来的 LLM 生成方式

前端的核心逻辑是：

1. 先尝试调用 proto 解析接口获取确定性目录
2. 如果 proto 接口返回了有效结构，直接使用（跳过 LLM 目录生成）
3. 并发生成每个页面的具体内容（最多 5 个并行请求）
4. 如果 proto 接口失败，fallback 到原来的 LLM 生成流程

这样做的好处是：目录结构 100% 准确，不会出现 LLM 瞎编目录的情况，同时还省了一次 LLM 调用的成本。

确定性 vs 不确定性：什么该交给 AI

这两个优化背后其实是同一个思路：把确定的东西明确告诉 AI，不确定的才让 AI 来发挥。

LLM 非常擅长理解、归纳和总结，但不擅长精确计算和结构化数据的生成。把它们分开处理，各取所长，效果就好很多了。

总结

这篇文章分享了我们在基于 DeepWiki 做内部项目 wiki 生成时的两个优化：

1. 行号前缀：给代码 chunk 的每一行加上实际行号，让 LLM 直接读取而不是自己推算，token 成本几乎可以忽略但准确率大幅提升。
2. 确定性目录生成：通过代码解析 proto 文件直接构建目录结构，绕过 LLM 的自由发挥，保证目录 100% 准确。

核心经验就一句话：需要定制自己的项目，尽量不要用通用的方案，不然就只是可用，但不精通。类似于现在的 OpenClaw，通用方案大家都能用，但真正好用的一定是针对你自己场景深度优化的。

对于确定的内容要明确告知 AI，不要让它自行发挥去推理，特别是和逻辑计算相关的，不然幻觉很严重。而不确定的、需要归纳总结的主观内容，则非常适合交给 AI 来输出。

#Blog

最近 OpenClaw 突然爆火，我的 SkillDeck 也乘热打铁支持了 OpenClaw 的 Skills 管理和 ClawHub 市场浏览安装功能。

这篇文章一方面介绍下 SkillDeck 的更新内容，另一方面也聊聊我对 OpenClaw 这波热度的一些看法。

安装命令：

1

brew tap crossoverJie/skilldeck && brew install --cask skilldeck

更新日志

支持更多 Agent

SkillDeck 现在一共支持了 10 个 AI coding agent，新增了以下几个：

加上之前就支持的 Claude Code、Codex、Gemini CLI、Copilot CLI、OpenCode，完整列表可以看：Supported Agents

支持 ClawHub 市场

这次比较大的更新是集成了 ClawHub 市场，可以直接在 SkillDeck 里浏览、搜索、安装 ClawHub 上的 Skills，不需要再手动 clone 或者用命令行装了。

主要功能：

• 侧边栏新增 ClawHub 入口，支持浏览和搜索
• 支持排序和筛选
• 一键安装到 OpenClaw 的 Skills 目录
• 安装时自动创建 symlink，不依赖 clawhub CLI

ClawHub 有 API 频率限制，如果触发了限流会自动降级为仅安装 SKILL.md 文件的模式，不影响基本使用。

OpenClaw 爆火背后的

OpenClaw 最近的热度确实夸张，但仔细想想，这波热度背后的推手其实挺有意思的：

1. 自媒体传播焦虑：每个科技自媒体都怕错过热点，一窝蜂涌上来输出「你还不知道 OpenClaw？」「不会用 OpenClaw 你就要被淘汰了」这类内容，焦虑感拉满。
2. AI 公司需要卖 token：OpenClaw 本质上是个疯狂消耗 token 的应用，每一次操作都在调大模型，AI 公司巴不得你 24 小时挂着跑。
3. 云厂商卖服务器：OpenClaw 需要部署、需要算力，云厂商的推广文章比谁都积极。
4. 甚至苹果还要卖 Mac mini：当然这是臆想，但你看各种「用 Mac mini 搭建 OpenClaw 私有部署」的教程确实很多。

网友们也是有才，发了不少梗图：

我理解的 OpenClaw

其实 OpenClaw 并不是什么全新的东西，之前昙花一现的豆包手机电脑版就是类似的思路——帮你自动化操作各种 app，本质上还是想解决人类「懒」的问题。

比如：

• 每天自动帮我在某个 app 签到
• 帮我每天写日报
• 自动查询某些网站帮我做信息汇总

这些说白了就是自动化功能，再结合 AI 可以理解我们模糊的语义，让你不用写精确的代码也能完成任务。并不是什么新奇的东西。

但其实很多人压根不知道自己装一个 openclaw 可以解决什么问题，大部分都是带着锤子找钉子，想着这么强一个工具我先装上，后面说不定就能拿来赚钱。

有这类需求的大概率在 openclaw 出现之前就自己写工具或者借助第三方实现了，如果等到现在都没有，那大概率你是没这个需求的。

目前为止 openclaw 最大的问题还是权限过大。

远程让 openclaw 拍照

现在网上已经有很多安全问题的案例了，比如很多人开了公网端口导致自己的电脑直接裸奔，任何人只要拿到了入口就可以让 OpenClaw 把电脑里的文件发出来，甚至拍照、录像都可以。

所以理想的方案还是之前苹果想做的那一套：各个 app 之间通过标准的 AI 可以识别的接口协议进行通信，而不是现在通过模拟点击、执行 shell 命令来绕过所有的权限校验。

只是这条路会影响这些 app 厂商的商业逻辑——用户不需要再打开他的 app 就可以进行消费，采集不到用户数据、用户也看不了广告等。

昨天还流行了一下午的抽象提示词攻击；在微信电脑版上根本不能直接发红包，也不能输入密码。

至于未来如何这还需要大厂之间继续进行博弈。

总结

我们不要过度关注现在 AI 带来的热度，就像去年初爆火的 DeepSeek，在现在养龙虾的热潮下已经没多少人讨论了；我认为到明年小龙虾也没啥人会继续讨论。

我们还是需要透过现象看本质，小龙虾背后依然是一个 AI Agent，和我们现在使用的 Claude Code、Codex 这些没有本质区别；只是它接入了很多 IM 通道，让普通人通过一个聊天窗口就可以指挥大模型去做很多具体的事情，让这个门槛看似降低了很多。

现在 Claude Code 已经更新了 loop 模式和 cron 模式，已经可以执行许多循环任务和主动执行任务，和 OpenClaw 更没什么区别了。

而且 OpenClaw 的代码复杂，接入的渠道很多，我们都知道代码量越多系统越复杂理论上出 bug 的几率也越大；所以之前也流行自己去裁剪自己的小龙虾，去掉一些不需要的渠道和代码。

归根结底，工具是拿来用的，不是拿来追的。与其焦虑「我是不是又错过了什么」，不如想想自己到底需要解决什么问题，再选合适的工具。

最近在同时用多个 AI coding agent的过程中，Skills 管理起来比较麻烦，

我日常在 Claude Code、Codex、Copilot CLI 之间切换，每个 Agent 的 Skills 存放在不同的目录下（~/.claude/skills/、~/.agents/skills/、~/.gemini/skills/、~/.copilot/skills/），安装一个 Skill 的流程大概是这样的：

1. 找到 Skill 的 GitHub 仓库
2. git clone 到本地
3. 手动创建 symlink 到对应 Agent 的 Skills 目录
4. 如果要装到多个 Agent，以上步骤重复 N 遍

卸载的时候也一样繁琐：删目录、清 symlink，漏了哪步就会留下残留。

当然也可以用命令行工具安装：

1

npx skills add https://github.com/github/awesome-copilot --skill git-commit

但这也只是解决了安装的问题，对所有 Agent 的 Skills 缺乏统一的可视化管理——装了哪些 Skill、哪些有更新、哪些该删掉，全靠自己记。

所以作为一个写过多年后端，但完全没碰过 Swift 和前端的人，我决定用 Claude Code 全程手搓一个 macOS 原生桌面应用来解决这个问题——这就是 SkillDeck。它不仅提供安装能力，还提供了统一的发现、更新、删除等全生命周期管理。

核心功能

统一仪表盘

三栏布局的 macOS 原生界面：左边是 Agent 列表和筛选，中间是 Skill 列表，右边是详情。支持按名称、描述、作者搜索，还能按 Agent 过滤和排序。

symlink 去重是一个比较实用的设计——同一个 Skill 通过 symlink 安装到多个 Agent 时，只会显示一次，不会在列表里看到重复项。

Skills 市场浏览

内置了 skills.sh 的排行榜浏览，支持 All Time、Trending、Hot 三种排序方式，还有搜索功能。看到喜欢的 Skill 可以直接一键安装，不用再手动 clone 了。

安装与更新

从 GitHub 安装只需要输入仓库地址（支持 owner/repo 格式），SkillDeck 会自动 clone、扫描可用 Skills、创建 symlink、更新 lock 文件。

更新检测也是一键的：会对比本地和远程的 tree hash，有变更就显示橙色角标，点一下就能拉取最新代码。

SKILL.md 编辑器

分栏设计：左边是表单 + Markdown 编辑区，右边是实时预览。改完 Cmd+S 保存，Esc 取消。

这个功能用的少，但也聊胜于无。

Agent 分配

每个 Skill 的详情页有一组 toggle 开关，控制这个 Skill 安装到哪些 Agent。打开就自动创建 symlink，关掉就自动删除，不用再手动跑命令了。

这样也不用每个 Agent 都去安装 skill，只保留一份。

文件系统监听

SkillDeck 会自动监听 Skills 目录的变化，所以如果你从 CLI 侧做了什么操作（比如用 claude skills add 安装了新 Skill），GUI 这边会自动刷新，不需要手动点刷新按钮。

目前支持的 Agent 和对应的 Skills 目录：

开发过程

整个项目从第一行代码到现在，全程都是用 Claude Code 开发的。

我自己的技术背景是 Java/Go/Python，Swift 之前一行都没写过，SwiftUI 和 macOS 平台开发更是零经验。但这次的体验让我感触很深——AI Coding 真的把跨语言开发的门槛拉低了很多。

开发节奏基本上就是一个循环：

1

提需求 → AI 实现 → 我测试 → 发现问题 → AI 修复 → 再测试

跟之前用 AI 搓 Skills 的流程差不多，但这次的复杂度高了不少——毕竟是一个完整的 macOS 桌面应用，涉及 UI 布局、文件系统操作、网络请求、并发处理等等。

我不需要先花几周系统学习 Swift 和 SwiftUI，遇到不懂的语法或 API 直接问 AI 就行。当然，这不代表可以完全当甩手掌柜——你得能看懂代码逻辑、能写清楚需求、能有效测试和反馈问题，AI 才能帮你持续推进。

说白了就是：你不需要会写 Swift，但你得会”验收”Swift 代码。能跑起来、功能正确、边界情况覆盖到，这些判断能力还是需要你自己具备的。

AI Coding 小 Tips

这段时间用 Claude Code 开发积累了一些经验，分享几个我觉得比较实用的 tips。

1. 每个功能新开一个 context

不要在一个超长的对话里做所有事情。每个功能开一个新的 context 会更聚焦，AI 不容易被之前的上下文带偏。

完成一个功能后记得 commit，这样如果 AI 后续改错了什么，你可以很方便地回滚到之前的状态。

尽量不要使用 AI 来回滚，不然会有不好的事情发生，血的教训。
精确的回滚还是交给靠谱的 git 工具来实现。

2. 大量 token 总结的内容保存成文档

有时候让 AI 做了一大堆分析（比如梳理项目架构、分析某个复杂模块的实现），这些内容当下可能用不上，但后面很可能会再用到。

我的做法是让 AI 把分析结果整理成文档保存到项目的 memory 目录，下次开新 context 的时候直接加载这个文档，不用重新消耗 token 再分析一遍。

3. claude --resume 恢复历史会话

如果你中途关掉了某个对话，后面又想继续，可以用 --resume 恢复：

1
2

claude --resume "hotkey"
claude --resume "架构"

它会搜索历史 session 的内容，列出匹配的会话让你选择。不过搜索不是百分百精准，有时候需要换几个关键词试试。

4. Session 保留策略

Claude Code 默认 30 天自动清理历史 session，可以在 ~/.claude/settings.json 里修改保留时间：

1

{ "cleanupPeriodDays": 90 }

所以 --resume 只适合短期内继续某个对话，不适合当作长期知识存储。长期需要保留的内容还是整理成文档更靠谱。

我建议还是使用刚才的方案，将你觉得消耗 token 的结论存储到专门的文档里，后期你需要使用的时候直接加载即可。

而不需要存放到 Claude Code 的系统提示词里，这样可能会浪费 token。

5. 用 CLAUDE.md 约束 AI 的开发规范

这个我觉得是最重要的一条。

把开发规范写进 CLAUDE.md，AI 每次开新对话都会自动加载这些规则，就像给团队新人定 code review 规范一样。我在项目里定了这些规则：

• Git 工作流：代码改动必须新建分支，禁止直接提交到 main
• 测试要求：每次代码修改都应包含对应的单元测试
• 提交确认：AI 不能自动 commit/push，必须等我确认
• PR 规范：每个 PR 必须包含「Manual Verification Required」（人工验证清单）和「Regression Checklist」（回归测试清单）

这里有一个关键区分：每个项目都通用的规则（比如分支策略、测试要求），可以放到 ~/.claude/CLAUDE.md（全局配置），所有项目自动生效，不用每个项目重复写。项目特有的规范才放到项目根目录的 CLAUDE.md 里。

总结

SkillDeck 解决的核心痛点就一个：让多个 AI Agent 的 Skills 管理更直观易用。从安装、更新、分配到删除，全部在一个 GUI 里搞定。

全程用 Claude Code 开发这个项目的感受是：跨语言开发的门槛被 AI 大幅拉低了。我一行 Swift 都不会写，但靠着 AI 辅助，从零产出了一个完整的 macOS 原生应用。当然前提是你得有基本的软件工程能力——需求拆解、测试验证、问题排查这些还是得自己来。

项目开源，MIT 协议，欢迎 star/issue/PR：GitHub | 项目主页

安装方式：

1

brew tap crossoverJie/skilldeck && brew install --cask skilldeck

#Blog

最近用 Claude Code、Copilot CLI 这类 AI Agent 工具的时候，有一个挺烦人的问题：让 AI 在后台跑任务，我总是会忍不住去查看他的执行状态，有时候比较复杂的任务可能会耗时十来分钟，每次来回切换非常浪费时间。

更惨的是有时候 AI 需要我授权某个操作（比如执行 shell 命令），我没注意到，它就一直卡在那里等。

所以我一直想找一个靠谱的通知方案。

灵感来源于播客「枫言枫语」，主播自力提到可以用 Hook 来实现 Agent 通知。

不过一开始我偷了个懒，让 AI 自己给方案。AI 给出的方案很”AI”：在 ~/.claude/CLAUDE.md 里加一段系统提示词，指示 LLM 任务完成后用 afplay 播放一个提示音。

1
2
3

## Task Completion Sound
When you complete a task, play a sound:
afplay /System/Library/Sounds/Glass.aiff

测试了几次发现这玩意不靠谱——有时候响，有时候不响，完全看 LLM 心情。

最终我还是回到了 Hook 方案，用各平台的 Hooks 系统实现确定性触发，并封装成了一个可复用的 SKILL。

最终的效果如下：

问题分析

为什么 LLM 提示词方案不靠谱？主要三个原因：

1. LLM 不会 100% 遵循附带操作类指令：LLM 对”生成文本”以外的操作指令（比如”运行 bash 命令”）本来就不太可靠，它可能觉得当前场景”不需要”播放声音就跳过了
2. 上下文压缩会丢失指令：长对话中，系统会自动压缩上下文，提示词的优先级会被降低甚至直接丢掉
3. LLM 对触发时机的判定不一致：什么算”任务完成”？LLM 每次的理解可能都不一样，导致触发行为不稳定

本质上，这是一个”软提示” vs “硬触发”的问题。用提示词去控制 LLM 行为，就像是”拜托你帮我做一件事”；而用 Hooks 就是”当这个事件发生时，自动执行这段代码”——确定性完全不同。

有点类似于现在的 LLM 和 Agent 的区别，Agent 是干活的，大模型是负责思考的。

确定的事情还是要交给确定的 Agent 去做。

agent-notifier 介绍

基于以上分析，我开发了 agent-notifier 这个 SKILL，用 Hooks 实现确定性通知。

功能概览

支持的 AI Agent 平台：

支持的通知渠道：

架构设计

核心思路是统一事件模型 + 并发多渠道分发：

1
2
3
4
5
6
7
8
9

各平台 Hook 触发
       ↓
  stdin JSON 输入（各平台格式不同）
       ↓
  notify.py 解析为统一事件：{platform, event, message}
       ↓
  读取 notify-config.json 配置
       ↓
  ThreadPoolExecutor 并发分发到所有启用的渠道

每个平台传过来的 JSON 格式不一样，比如 Claude Code 是 {"notification_type": "idle_prompt", ...}，Copilot CLI 是 {"hook_event_name": "sessionEnd", ...}。notify.py 会把这些不同的格式统一解析成 {platform, event, message} 三元组，然后根据配置分发到各个通知渠道。

一个关键设计：单个渠道发送失败不影响其他渠道。比如 Telegram 网络超时了，Sound 和 macOS 通知该响还是响。错误信息只输出到 stderr，不会中断流程。

核心设计决策：纯标准库、零依赖

整个 notify.py 只用了 Python 标准库，没有任何 pip 依赖：

• HTTP 请求用 urllib.request（发 Telegram、Slack、Discord）
• 邮件用 smtplib
• 播放声音用 subprocess 调系统命令
• 并发用 concurrent.futures

这意味着只要机器上有 Python，拿来就能用，不需要 pip install 任何东西。

开发过程

整个 SKILL 的开发也是和 AI 对话完成的，下面分阶段回顾。

阶段一：核心通知脚本 notify.py

这是最核心的部分，负责三件事：

1. 解析输入：从 stdin 读取各平台传过来的 JSON，识别平台类型和事件
2. 统一事件模型：不管哪个平台，统一解析为 {platform, event, message}
3. 多渠道发送：并发调用所有启用的通知渠道

比如 Claude Code 的 Hook 会通过 stdin 传入：

1

{"notification_type": "idle_prompt", "message": "Claude is waiting for your input"}

脚本解析后生成通知：**”✅ Task completed — waiting for your input”**，然后同时发到 Sound、macOS 通知中心、Telegram 等所有启用的渠道。

阶段二：配置与安装

光有核心脚本还不够，还需要让用户能方便地配置和安装。所以又搞了两个文件：

notify-config.json：配置模板，定义了所有渠道的开关和参数。默认只启用 Sound 和 macOS 通知，Telegram、Email 这些需要手动启用并填入凭据。

setup.py：交互式安装脚本，运行后会：

1. 自动检测你装了哪些 AI Agent 平台
2. 引导你配置通知渠道（要不要 Telegram？Bot Token 是什么？）
3. 自动在对应平台写入 Hook 配置
4. 发一条测试通知验证配置

阶段三：集成测试

代码写完了，关键是跑起来验证。

首先在 Claude Code 的 ~/.claude/settings.json 里配置 Hook：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/skills/agent-notifier/notify.py"
          }
        ]
      }
    ]
  }
}

然后手动测试：

1
2
3
4
5

# 模拟任务完成通知
echo '{"notification_type":"idle_prompt","message":"test"}' | python3 notify.py

# 模拟权限请求通知
echo '{"notification_type":"permission_prompt","message":"needs permission"}' | python3 notify.py

Sound 和 macOS 通知都正常。接着启用 Telegram，配好 Bot Token 和 Chat ID，再跑一次——Telegram 也收到了消息。

最后让 Claude Code 执行一个真实任务，然后等它跑完。果然，任务结束后 Telegram 弹出通知，Sound 也响了，搞定。

阶段四：修 bug 改文案

实际使用中发现一个问题：idle_prompt 的通知消息是 “Claude is waiting for your input”，但这个消息不够直观——我更想知道的是”任务完成了”，而不是”在等你输入”。

虽然本质上 idle_prompt 就是任务完成后等待输入的信号，但消息文案会影响用户感知。于是改成了：

• idle_prompt → “✅ Task completed — waiting for your input”
• permission_prompt → “🔐 Permission required”

改完之后再测，Telegram 消息一目了然，不用再猜它到底是什么状态了。

总结

这次开发最核心的观点就一句话：Hooks > 提示词。

凡是需要确定性执行的操作，都不应该用提示词去”请求”LLM 来做，而是应该用平台提供的 Hook 机制来保证。提示词适合控制生成内容的风格和方向，但不适合控制”是否执行某个操作”这类二元决策。

另外，对话式开发的体验依然很好。从最初的想法到最终可用的 SKILL，整个过程就是不断对话、测试、修复的循环。像 Telegram 消息文案不够直观这种问题，也是在实测中才发现的。

感兴趣的可以去 GitHub 仓库 看看源码，agent-notifier 在 skills/agent-notifier/ 目录下。

#Blog

最近上一篇文章里答应过要分享下我那三个 SKILLS 的创建过程，乘热打铁赶紧写出来。

上篇提到过我写博客的一个痛点：每次写完文章都要手动找封面图 → 上传图床 → 粘贴链接，这套流程走下来虽然不复杂，但每次都要做一遍确实烦。

所以我就想着把这个流程自动化掉，而且全程一行代码没写，完全和 AI 对话搞定。

Skills 介绍

先整体介绍一下最终产出的三个 SKILLS：

三个 SKILLS 之间存在依赖关系：

1

auto-blog-cover → cover-generator → image-uploader

auto-blog-cover 是最上层的入口，调用 cover-generator 生成图片，cover-generator 再调用 image-uploader 上传到图床。最终我只需要跑一条命令，整个流程就搞定了。

这里分成三个 skill 的好处是：更好的分层可以帮助其他用户选择合适自己的 skill，比如有些人可能只需要一个上传图片的 skill 而已。

计算机经典架构之一：遇事不决先分层😊。

image-uploader

这是最底层的基础 SKILL，负责把本地图片上传到图床，目前支持 sm.ms。

设计上用了抽象基类 BaseUploader，后期想接入腾讯云、阿里云这些只需要新增一个实现类就行：

1
2
3
4
5
6
7
8

class BaseUploader(ABC):
    @abstractmethod
    def upload(self, image_path):
        pass

class SmMsUploader(BaseUploader):
    API_URL = "https://sm.ms/api/v2/upload"
    # ...

token 配置支持三种方式，优先级从高到低：

1. 命令行参数 --token
2. 环境变量 SMMS_TOKEN
3. 配置文件 config.json

这个优先级设计是在对话中讨论出来的，一开始只有命令行参数，后来考虑到分享给其他人使用的场景才加上了环境变量和配置文件。

cover-generator

这个 SKILL 用 Pillow 生成渐变风格的封面图（1200x630），支持四种主题：

核心就是生成一个渐变背景，然后把标题和副标题居中渲染上去。加了 --upload 参数可以生成后直接调用 image-uploader 上传。

上传完成后会自动清理本地临时文件，上传失败还会自动重试最多 3 次。

auto-blog-cover

这是最终面向用户的 SKILL，把整个工作流串起来：

1. 读取 Markdown 文件，解析 frontmatter
2. 提取标题（支持手动传入覆盖）
3. 调用 cover-generator 生成封面并上传
4. 用正则替换更新 frontmatter 中的 banner_img 和 index_img

这里用正则替换而不是直接用 python-frontmatter 库回写，是因为后者会重排 YAML 字段的顺序，导致我博客的 frontmatter 格式被打乱。

使用起来很简单：

1
2
3
4
5

# 全自动模式
python3 skills/auto-blog-cover/auto_blog_cover.py /path/to/blog.md

# 手动指定标题
python3 skills/auto-blog-cover/auto_blog_cover.py blog.md --title "AI Evolution" --subtitle "From Function Call to MCP"

创建过程

整个创建过程就是和 AI 不断对话、迭代出来的，下面分阶段回顾下。

阶段一：从 image-uploader 开始

一开始我的需求很简单：我需要一个上传图片到 sm.ms 的工具。

我给 AI 提供了 sm.ms 的接口文档，然后让它帮我实现。AI 先问了我几个问题：用什么语言？做成什么形式？我选了 Python 脚本 + 独立 CLI 工具。

然后就是一个很有意思的讨论——token 怎么传递。

AI 一开始的方案是通过命令行参数传入：

1

python skills/image_uploader.py image.png --token YOUR_TOKEN

我提了一个问题：”token 如果从命令行中获取是否方便其他人使用这个 SKILLS？”

这一下就打开了思路，于是补充了环境变量和配置文件两种方式，形成了三级优先级的配置体系。

跑起来测试的时候，AI 直接从我的 .zshrc 里找到了 SMMS_TOKEN 环境变量（之前配好的），上传了一张壁纸验证通过。

阶段二：cover-generator 的诞生

接着我提了第二个需求：我想给博客文章生成封面图。

这里我不想直接调用类似于 Nano Banana 这里的专门文生图模型，就只需要一个简单背景+文字的图片即可；

所以 AI 给了我一个方案：算法生成艺术图 vs 文字+背景，本地用 Pillow 就能生成。

生成的图片效果还不错，简洁的渐变背景加上标题文字，虽然比不上专业设计，但作为博客封面还是够用了。

后来我又提了几个优化：

• 图片生成后要自动清理本地文件（不占存储）
• 上传失败要能重试

AI 都逐一实现了，加了 retry 逻辑和 finally 块里的清理代码。

阶段三：auto-blog-cover 串联一切

前两个 SKILLS 搞定后，我描述了一下我的实际工作流：

我会在 Obsidian 里写博客，写完之后打开 CLI，让它读取博客内容，调用 cover-generator 生成封面并上传，然后把图片地址更新到博客的 frontmatter 里。

AI 认为这个流程完全可以自动化，建议我再创建一个 SKILL 来串联。我觉得很有道理，一个独立的 SKILL 也方便其他有类似需求的人使用。

这中间有两个值得一提的坑：

中文乱码问题：第一次跑 auto-blog-cover 时，生成的封面图里中文全是乱码。原因是 Pillow 默认字体不支持中文。AI 把字体改成了 STHeiti Light（macOS 系统自带的中文字体），同时加了 Linux 和 Windows 的字体回退列表。

YAML 字段排序问题：一开始用 python-frontmatter 库回写文件时，它会把我的 YAML 字段重新排序。比如原来是 title → date → categories → tags → banner_img，回写后变成了按字母排序的 banner_img → categories → date → ...。AI 改用正则表达式直接替换字段值，这样就不会动其他字段的顺序了。

修复这两个问题后再跑了一次，效果完美——中文正常显示，frontmatter 格式完好。

迭代的节奏

回顾整个过程，基本上就是这样一个循环：

1

提需求 → AI 实现 → 我测试 → 发现问题 → AI 修复 → 再测试

每一轮对话都在不断完善功能、补全边界情况。从最初的单个上传脚本，逐步演化出三个分层的 SKILLS，整个过程非常自然。

总结

这次体验下来，最大的感受是：把重复性的工作流固化成 SKILLS 真的很香。

以前每次写完博客要手动配图、上传、粘贴链接，虽然每次也就几分钟，但积少成多也挺烦的。现在一条命令搞定，而且整个创建过程我确实一行代码没写，全程和 AI 对话完成。

对话式开发的好处在于：你不需要事先想好所有细节，可以边做边想、边测边改。像 token 配置方案、中文字体、YAML 排序这些问题，都是在实际使用中发现并解决的。

感兴趣的可以去 GitHub 仓库 看看源码，也欢迎提 issue 和 PR。

#Blog

最近 Claude 的 SKILLS 很火，忍不住也来体验了一下，发现确实是有些东西的；但也发现身边的一些同事对这些新出的概念总是很懵逼，所以便有了这篇文章。

从最早的 Function Call，到 MCP 协议，再到如今的 Agent Skills。

本文将从技术演进的角度，带你理解这些概念之间的关系，以及它们如何让 AI 从一个”只会说话的聊天机器人”变成真正能”动手做事”的智能助手。

再开始之前还是要澄清下大模型和 Agent 的关系，今天刷到一个视频觉得讲的非常浅显易懂：

所谓智能体就是把非智能的部分整合在一起，也就是说大模型帮我们做模糊自然语言的理解与决策，然后然后交给 agent 去调用一些非智能化的能力，比如：

• 把 word 转换成 PDF
• 编译运行代码
• 调用飞书的推送接口，把一些内容推送给你的机器人。

  这些能力可能是需要编码完成的，也可能是第三方提供的 API，不管是哪种都是一些确定的东西。

让大模型摆脱了只能在网页里做一个 chatbot，从而进化到可以真正干具体事情的能力（以往我们需要手动去复制大模型给的代码到本地进行编译运行，这些重复机械的步骤直接交给 agent 来运行）

比如现在流行的 claude code 他可以帮你修改代码，直接运行代码获取结果，充当你和大模型沟通的桥梁。

而最近大火的 openclaw 本质上也是一个 agent，只是相比于 claude code 多了 gui 界面，对接更多的工具（各种 IM），本质上他们没有任何区别。

发展历史

Function Call：让大模型学会”使用工具”

在 Function Call 出现之前，大模型只能做一件事：生成文本。你问它天气，它只能根据训练数据猜测；你让它查数据库，它只能编造一个”看起来合理”的答案。

2023 年，OpenAI 发布了 Function Calling 功能，这是大模型能力扩展的第一个里程碑。

核心思路：告诉大模型”你有哪些工具可以用”，当它判断需要使用工具时，输出一个结构化的 JSON 调用请求，由外部程序执行后再把结果返回给模型。

1
2
3
4
5
6
7

{
  "name": "get_weather",
  "arguments": {
    "location": "北京",
    "unit": "celsius"
  }
}

局限性：

• 每个应用都要自己定义和实现工具
• 工具之间没有统一标准，无法复用
• 工具定义需要全部放在 System Prompt 里，token 消耗大

MCP：建立统一的”工具接口标准”

2024 年，Anthropic 发布了 **MCP (Model Context Protocol)**，可以把它理解为 AI 工具的 RPC 协议。

解决的核心问题：让不同开发者写的工具，AI 都能听得懂、用得上。

MCP 的工作流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

MCP Client (Claude)                MCP Server (如数据库读取器)
     │                                  │
     │  1. 连接并发送 list_tools        │
     │ ──────────────────────────────▶  │
     │                                  │
     │  2. 返回工具列表                 │
     │  (query_db, search_files...)     │
     │ ◀──────────────────────────────  │
     │                                  │
     │  3. 用户提问，Claude 决定调用    │
     │     call_tool: query_db          │
     │ ──────────────────────────────▶  │
     │                                  │ ← 执行 SQL 查询
     │  4. 返回执行结果                 │
     │ ◀──────────────────────────────  │
     │                                  │
     ▼
Claude 整合结果，组织成回答

Agent Skills：从”工具”到”技能包”

2025 年 10 月，Anthropic 发布了 **Agent Skills**，这是在 MCP 基础上的进一步抽象。

时间线：

Skills 是什么：

“Skills are organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.”

可以把 Skills 理解为”分类后的系统提示词”，但它比传统的 System Prompt 更智能——按需加载，而不是全量加载。

Skills 的本质：提示词工程的进化

说到底，Skills 的本质还是前几年流行的提示词工程（Prompt Engineering）。

回想一下 2023 年 ChatGPT 刚火的时候，网上到处都是”万能提示词模板”、”让 AI 效率翻倍的 prompt 技巧”。那时候大家都在研究怎么写出更好的 System Prompt，让 AI 扮演各种角色：翻译官、程序员、文案专家…

Skills 做的事情本质上没变——**还是在告诉 AI “你是谁、你能做什么、你应该怎么做”**。

说的更好理解一点：可以把自己日常的一些固定流程固化为一个 SKILLS，比如我写博客需要为一篇文章配一个封面图，我之前的流程是：

• 写好文章后根据文章的内容想一个标题
• 根据这个标题去网上照一张合适的图
• 把图片上传到图床
• 然后把图床链接贴到博客的顶部

这些流程其实都是机械化的毫无智能而言，但是每次做法都是一样的；所以我将这些流程写到一个 SKILL.md 文档里。

让 AI 给我总结文章标题、生成配图、上传图床、然后粘贴到文章顶部。

这样我写好文章后，只需要对 Claude Code/Codex 这类 agent 说：把 /xx/xx/blog.md 配图。

之后 AI 就会自动加载我在 SKILL.md 里定义的流程进行处理。

同理，我们日常工作中这些繁琐的流程都可以抽象为一个个的 SKILL，想想是不是可玩性非常强。

区别在于：

• 以前：把所有提示词塞进一个巨大的 System Prompt，不管用不用得上都要带着
• 现在：把提示词拆分成独立的 Skill 文件，AI 自己判断什么时候需要加载哪个

所以如果你之前积累了很多好用的提示词模板，现在可以直接把它们改造成 Skills——加上 frontmatter 元数据，放到 ~/.claude/skills/ 目录下，就能让 Claude 按需调用了。

现状

Skills 与 MCP 的关系

用一个类比来说明：

• MCP是 RPC 接口协议”
• Skills 是”接口实现里的一个个具体的函数（函数的抽象级别需要定义好，不然维护性也不强）”

它们不是互相替代的关系，而是”协议”与”实现”的关系。一个 “GitHub Skill” 内部就是通过 MCP 协议去和 GitHub 服务器通讯的。

Skills 的两阶段加载机制

这是 Skills 设计中很精妙的部分——不会导致 token 激增。

工作原理：

1

用户请求 → Claude 匹配 skill descriptions → 只注入相关 skill 的完整内容

以 Obsidian skills 为例：

• 启动时：只加载 obsidian-markdown、obsidian-bases 的 name 和 description（约 100-300 tokens）
• 当你说 “帮我创建一个 Obsidian 笔记”：才加载 obsidian-markdown 的完整内容
• 如果不涉及 Obsidian：完整内容永远不会加载

匹配逻辑：完全由大模型决定

这里我其实有一个问题：谁来判断是否需要加载某个 Skill？

答案是：完全由大模型决定，不是客户端。

任何需要做模糊语义判断的地方都是大模型来处理、Agent 只做具体确定的事情。

1
2
3
4
5
6
7
8
9
10
11
12

Claude Code 客户端                    大模型
     │                                  │
     │  所有 skills 元数据              │
     │  (name + description)            │
     │ ──────────────────────────────▶  │
     │                                  │ ← 模型阅读、理解、判断
     │                                  │
     │  调用 Skill 工具                 │
     │ ◀──────────────────────────────  │
     │                                  │
     │  注入完整 SKILL.md 内容          │
     │ ──────────────────────────────▶  │

客户端做的事：收集元数据、打包发送、执行工具调用。

客户端不做的事：没有关键词匹配、没有正则、没有向量嵌入、没有意图分类器。

客户端做的越轻越能体现 AI 的特点，也跟通用。

由于完全依赖模型判断，存在不可靠性。skills 有可能没有被自动激活，模型会直接跳过它们，这就是大模型的概率问题，如果确定要使用某个 SKILL，可以用一下方案：

1. 直接使用 /skill-name 强制使用
2. 关键规则放在 CLAUDE.md 中（始终在上下文里）
3. 设置 disable-model-invocation: true 改为手动调用

Skills 的安装方式

目前有两种安装方式：

~/.claude/skills 目录是 Agent Skills 开放标准的本地实现。Agent Skills 已发布为开放标准（agentskills.io），不仅 Claude Code 支持，OpenAI Codex CLI 等其他工具也可以使用。

Skills 的存储层级

Skills 的存储架构类似于 Java 生态中的依赖管理体系，分为三个层级：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

┌─────────────────────────────────────────────────────────────────┐
│                    公共云端层 (Public Hub)                        │
│         类似 Maven Central / npm registry                        │
│         未来可能的 Anthropic Skills Hub                           │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    企业私服层 (Enterprise Hub)                    │
│         类似 Nexus 私服 / npm private registry                   │
│         公司内部的 MCP Server，统一管理员工通用技能                  │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    本地层 (Local)                                 │
│         类似本地 .m2 目录 / node_modules                          │
│         ~/.claude/skills/ 或项目内 .claude/skills/               │
└─────────────────────────────────────────────────────────────────┘

查找优先级：与 Maven 依赖解析类似，Skills 也遵循”就近原则”——本地 > 企业私服 > 公共 Hub。当同名 Skill 存在于多个层级时，优先使用本地版本。

未来

三阶段演进

基于当前的发展趋势，我认为 AI Agent 的能力扩展可能会经历三个阶段：

第一阶段：手动时代（现在）

用户需要手动配置 MCP Server、安装 Skills，感知强烈，门槛高。

第二阶段：发现时代（近未来）

通过 MCP 自动发现。可能会出现类似 npm 或 Docker Hub 的 Skill Registry：

• 配置文件里写："skills": ["@github/search", "@linear/issue-manager"]
• 启动时自动去地址获取 SKILLS，通过 MCP 协议下载技能定义
• 用户知道 AI 有这些能力，但不需要管背后代码

第三阶段：隐形时代（终极目标）

这是最值得期待的阶段：**Skills 彻底消失，变成大模型的”潜意识”**。

1. 海量技能池：云端存在数百万个 MCP 服务
2. 意图识别与自动路由：Claude 自动分析任务并拆解步骤
3. 即时加载：毫秒级自动调用对应 Skill，无需用户干预

**未来的 AI 就像”电力”**：100 年前你需要了解发电机的原理；现在你只需要插上插头。未来的大模型也会进化到——你只要说出需求，它会自动在后台调动千千万万个你从未听说过的”Skills”去帮你达成。

安全与信任

当 Skills 变得越来越自动化，安全问题会变得尤为重要：

公共仓库里的 Skill 需要经过：权限声明、运行时沙箱、代码审计与签名。这需要一个有信用背书的大厂（如 Anthropic，Google 等）来提供官方的审核与分发平台。

总结

从 Function Call 到 MCP 再到 Agent Skills，AI 能力扩展的演进遵循着一个清晰的流程：

1. Function Call：让大模型学会使用工具，但每个应用各自为战
2. MCP：建立统一的工具接口标准，实现生态复用
3. Agent Skills：在 MCP 基础上进一步抽象，实现按需加载、token 优化

这个演进过程的本质是：**让 AI 从一个”什么都懂一点但包袱很重”的聊天机器人，变成一个可以根据任务场景，随时调用不同工具来实现需求的关键，比如最近大热的 OpenClaw **

随着大模型的持续进步，这些基础设施最终会变得”隐形”——用户不再需要知道 Skills 的存在，只需要表达意图，AI 就能自动调用合适的能力来完成任务。

这才是 AI Agent 的终极形态。

最后接着写这篇文章的过程，我也编写了几个 SKILLS可以用于我在写文章的过程中自动生成文章的封面然后上传到图床。

有类似需求的朋友可以试用下。

当然这个 SKILLS 也是一行代码没写，全部交给 AI 生成的，感兴趣的再下一篇分享下相关流程。

#Blog

背景

因为最近在基于 RAG 对我们的 code repo 做 AI 分析，其中有一个非常核心的流程就是需要将我们的代码库里的源码进行分割，分割之后会作为 chunk 供 RAG 查询；然后再将查询到的 chunk 提交给 LLM 做分析。

目前我们所使用的 deepwiki-open对代码的分析使用的是最通用的 text_splitter:

分割方法也是最简单的按照 word 进行分割，普通场景下 text_splitter 够用，但对于我们这种存代码的场景就需要使用特殊的 Spitter 了；主要问题是它不理解语言结构，容易把函数/类等语义单元切断，导致检索召回片段不完整、上下文丢失。

算法对比

1. 基础文本切分

简介： 最原始的方法。不管代码逻辑，直接按字符长度或者空格硬切。就像切西瓜不管瓜瓤结构，每一刀切固定的厚度。

• 优点：简单，适用于所有文本项目
• 缺点：不适合代码项目，经常把一个完整的函数拦腰截断，大模型读起来云里雾里。

代码示例：

1
2

splitter = TextSplitter(**configs["text_splitter"])
document = splitter.split_text(code)

手搓 Tree-Sitter (参考Claude-context)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

it('should split Java code from external file', async () => {  
    const filePath = 'AppService.java';  
      
    if (fs.existsSync(filePath)) {  
        const code = fs.readFileSync(filePath, 'utf-8');  
        console.log(`Reading Java file from: ${filePath}`);  
        console.log(`File size: ${code.length} characters`);  
          
        const chunks = await splitter.split(code, 'java', filePath);  
          
        console.log(`Split into ${chunks.length} chunks`);  
        chunks.forEach((chunk, index) => {  
            console.log(`>>>>Chunk ${index}: ${chunk.content}\n`);  
            console.log(`Metadata:`, chunk.metadata);  
            console.log(`Content preview: ${chunk.content.substring(0, 100)}...`);        });  
    } else {  
        console.warn(`File not found: ${filePath}`);  
    }  
});

原本是 TS 写的，核心是使用 tree-sitter 做 AST 分析之后进行拆分，只是会在解析 AST 失败的时候使用 LangChainCodeSplitter 作为兜底。

这部分没有找到现成的开源方案，于是我就按照 ts 代码翻译了一份 Python 的版本：

1
2
3
4

splitter = AstCodeSplitter(chunk_size, chunk_overlap)  
chunks = splitter.split(code, "java", file_path)  
for i, chunk in enumerate(chunks):  
    print(f">>>>Chunk {i}: {chunk.content}\n")

总结

我们对同一个 Java 源码文件分别使用了 claude-context 和 text-splitter进行了对比。

最后我们选择了 benbrandt:text-splitter-rust 的版本（提供了 Python binding 库）。

但对某个代码 repo 分析的效果与许多因素有关，比如 LLM 大模型质量、Embeding 的质量、提示词是否合理；其中的 Code Splitter 算法只是较小的一个环节。

这类需求随着大模型的迭代也需要常用常新，后续也会继续迭代相关知识。
#Blog

原文链接：https://github.com/sweepai/sweep/blob/main/docs/pages/blogs/chunking-2m-files.mdx

最近在研究 Code Splitter 的算法，发现 llama_index 的代码分割使用的是 sweepai 的代码分割算法，同时还提供了一篇博客，也就有了这篇文章。

初始化任何向量存储都需要对大型文档进行切分（chunking）以进行高效搜索。

为什么不能直接对整个文件做嵌入（embed）？以我们主 API 的 endpoint 文件 为例：

1. 导入包
2. 常量声明
3. 辅助函数
4. 每个 webhook endpoint 的业务逻辑

如果我搜索 “GitHub Action run”，它应该匹配检查 “check_runs completed” 事件的那个 switch case 块（参见 代码片段）。但那只是 400 多行代码中的大约 20 行，即使是完美的搜索算法也只会把相似性视为 5%。如果我们把 400 行切成 20 个每个 20 行的块，就更容易匹配到正确的 switch case 块。

那我们如何产生 20 行的块？一个简单的办法是均匀地把 400 行切成每 20 行一块。

但是，这种方法行不通。语义上相关的代码不会被保留在一起，且会丢失上下文。例如，函数头可能会被和实现体分离。

我们当前的代码切分算法每天处理 200 万+ 文件，并且已经开源了！

约束 🚧

大多数用于 RAG（检索增强生成）的切分器按 token 数量做上限。为简化处理，我们决定使用字符数，上限设为 1500。

这是因为代码的平均 token 与字符比约为 1:5（300 tokens），而嵌入模型通常受 512 tokens 限制。进一步地，1500 字符大约对应 40 行，大致等同于一个小到中等大小的函数或类。

挑战在于尽可能接近 1500 字符，同时保证块在语义上保持一致且相关上下文被保留。

开箱即用的解决方案 📦

最简单的现成解决方案是 Langchain 的递归切分器（recursive chunker）。总体思路：

1. 用顶层分隔符拆分文本（先用 class，然后是 function 定义，然后是方法等）
2. 迭代每个区块并贪心地把它们串联直到超过字符限制。对于过大的区块，使用下一级分隔符递归切分。

示例伪代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

delimiters = ["\nclass ", "\ndef ", "\n\tdef ", "\n\n", "\n", " ", ""]
def chunk(text: str, delimiter_index: int = 0, MAX_CHARS: int = 1500) -> list[str]:
delimiter = delimiters[delimiter_index]
new_chunks = []
current_chunk = ""
for section in text.split(delimiter):
if len(section) > MAX_CHARS:
# Section is too big, recursively chunk this section
new_chunks.append(current_chunk)
current_chunk = ""
new_chunks.extend(chunk(section, delimiter_index + 1, MAX_CHARS)
elif len(current_chunk) + len(section) > MAX_CHARS:
# Current chunk is max size
new_chunks.append(current_chunk)
current_chunk = section
else:
# Concatenate section to current_chunk
current_chunk += section
return new_chunks

针对每种语言我们会使用不同的分隔符。

示例

完整示例文件请见：https://gist.github.com/kevinlu1248/ded3ea33dcd8a9bd08078f4c64eb9268

示例 #1

基于我们处理 GitHub Action 运行的 on_check_suite.py 文件。一个糟糕的切分把字符串拼接声明与其内容分开了。❌

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

...

def on_check_suite(request: CheckRunCompleted):
    logger.info(f"Received check run completed event for {request.repository.full_name}")
    g = get_github_client(request.installation.id)
    repo = g.get_repo(request.repository.full_name)
    if not get_gha_enabled(repo):
        logger.info(f"Skipping github action for {request.repository.full_name} because it is not enabled")
        return None
    pr = repo.get_pull(request.check_run.pull_requests[0].number)
    num_pr_commits = len(list(pr.get_commits()))
    if num_pr_commits > 20:
        logger.info(f"Skipping github action for PR with {num_pr_commits} commits")
        return None
    logger.info(f"Running github action for PR with {num_pr_commits} commits")
    logs = download_logs(
        request.repository.full_name,
        request.check_run.run_id,
        request.installation.id
    )
    if not logs:
        return None
    logs = clean_logs(logs)
    extractor = GHAExtractor()
    logger.info(f"Extracting logs from {request.repository.full_name}, logs: {logs}")
    problematic_logs = extractor.gha_extract(logs)
    if problematic_logs.count("
") > 15:
        problematic_logs += "

========================================

There are a lot of errors. This is likely a larger issue with the PR and not a small linting/type-checking issue."
    comments = list(pr.get_issue_comments())
    if len(comments) >= 2 and problematic_logs == comments[-1].body and comments[-2].body == comments[-1].body:
        comment = pr.as_issue().create_comment(log_message.format(error_logs=problematic_logs) + "

I'm getting the same errors 3 times in a row, so I will stop working on fixing this PR.")
        logger.warning("Skipping logs because it is duplicated")
        raise Exception("Duplicate error logs")
    print(problematic_logs)
    comment = pr.as_issue().create_comment(log_message.format(error_logs=problematic_logs))
    on_comment(
        repo_full_name=request.repository.full_name,
        repo_description=request.repository.description,
        comment=problematic_logs,
        pr_path=None,
        pr_line_position=None,
        username=request.sender.login,
        installation_id=request.installation.id,
        pr_number=request.check_run.pull_requests[0].number,
        comment_id=comment.id,
        repo=repo,
    )
    return {"success": True}

示例 #2

基于 LlamaIndex 的 BaseIndex.ts 文件（声明向量存储的 ABC）。糟糕的切分把类的方法实现与其头部分离了。❌

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

...

export class IndexDict extends IndexStruct {
  nodesDict: Record<string, BaseNode> = {};
  docStore: Record<string, Document> = {}; // FIXME: this should be implemented in storageContext
  type: IndexStructType = IndexStructType.SIMPLE_DICT;

========================================

getSummary(): string {
    if (this.summary === undefined) {
      throw new Error("summary field of the index dict is not set");
    }
    return this.summary;
  }

  addNode(node: BaseNode, textId?: string) {
    const vectorId = textId ?? node.id_;
    this.nodesDict[vectorId] = node;
  }

  toJson(): Record<string, unknown> {
    return {
      ...super.toJson(),
      nodesDict: this.nodesDict,
      type: this.type,
    };
  }
}

...

问题 🤔

然而，这个切分器存在严重问题：

1. 对 Python 效果不错，但对大括号密集的语言（如 JS）和基于 XML 的语言（如 HTML）会在不可预期的地方断开。
   • 此外，str.split 对这些更复杂的语法（如 JS、HTML）效果不好。
   • 例如，即使对 Python，也会把像 problematic_logs += \" 与其余字符串错误地分割。
2. 目前仅支持 16 种语言，不支持 JSX、Typescript、EJS 和 C#。
   • JSX/TSX 占我们用户群的大部分。
3. Langchain 会删除重要分隔符（比如 “def” 和 “class”）。

我们的解决方案 🧠

根本问题是用一系列的 str.split 和分隔符来近似所谓的“具体语法树（CST）”是太原始了。

为了解决这个问题，我们直接使用 CST 解析器。如何获得大量语言的 CST 解析器？幸运的是，库 tree-sitter 提供了标准化访问 113 种编程语言 CST 解析器的方式，并且速度快（用 C 写）且无额外依赖。

新的算法在高层上与 Langchain 类似，步骤如下：

1. 要对一个父节点进行切分，我们遍历其子节点并贪心地把它们打包在一起。对于每个子节点：
2. 如果当前 chunk 太大，将其加入结果列表并清空当前 bundle
3. 如果下一个子节点本身太大，则递归切分该子节点并把结果加入列表
4. 否则，将该子节点的文本拼接到当前 chunk
5. 对最终结果做后处理：把单行的 chunk 与下一个 chunk 合并
6. 这样保证不会出现过小（意义不大）的 chunk

示例伪代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

from tree_sitter import Node

def chunk_node(node: Node, text: str, MAX_CHARS: int = 1500) -> list[str]:
new_chunks = []
current_chunk = ""
for child in node.children:
if child.end_byte - child.start_byte > MAX_CHARS:
new_chunks.append(current_chunk)
current_chunk = ""
new_chunks.extend(chunk_node(child, text, MAX_CHARS)
elif len(current_chunk) + child.end_byte - child.start_byte > MAX_CHARS:
new_chunks.append(current_chunk)
current_chunk = text[node.start_byte:node.end_byte]
else:
current_chunk += text[node.start_byte:node.end_byte]
return new_chunks

示例

完整切分结果请见：https://gist.github.com/kevinlu1248/49a72a1978868775109c5627677dc512

示例 #1

基于我们的 on_check_suite.py 文件。正确的切分；在 if 语句之前做切分，而不是把 if 语句与其主体分开。✅

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

...

def on_check_suite(request: CheckRunCompleted):
    logger.info(f"Received check run completed event for {request.repository.full_name}")
    g = get_github_client(request.installation.id)
    repo = g.get_repo(request.repository.full_name)
    if not get_gha_enabled(repo):
        logger.info(f"Skipping github action for {request.repository.full_name} because it is not enabled")
        return None
    pr = repo.get_pull(request.check_run.pull_requests[0].number)
    num_pr_commits = len(list(pr.get_commits()))
    if num_pr_commits > 20:
        logger.info(f"Skipping github action for PR with {num_pr_commits} commits")
        return None
    logger.info(f"Running github action for PR with {num_pr_commits} commits")
    logs = download_logs(
        request.repository.full_name,
        request.check_run.run_id,
        request.installation.id
    )
    if not logs:
        return None
    logs = clean_logs(logs)
    extractor = GHAExtractor()
    logger.info(f"Extracting logs from {request.repository.full_name}, logs: {logs}")
    problematic_logs = extractor.gha_extract(logs)
    if problematic_logs.count("\n") > 15:
        problematic_logs += "\n\nThere are a lot of errors. This is likely a larger issue with the PR and not a small linting/type-checking issue."
    comments = list(pr.get_issue_comments())

==========

    if len(comments) >= 2 and problematic_logs == comments[-1].body and comments[-2].body == comments[-1].body:
        comment = pr.as_issue().create_comment(log_message.format(error_logs=problematic_logs) + "\n\nI'm getting the same errors 3 times in a row, so I will stop working on fixing this PR.")
        logger.warning("Skipping logs because it is duplicated")
        raise Exception("Duplicate error logs")
    print(problematic_logs)
    comment = pr.as_issue().create_comment(log_message.format(error_logs=problematic_logs))
    on_comment(
        repo_full_name=request.repository.full_name,
        repo_description=request.repository.description,
        comment=problematic_logs,
        pr_path=None,
        pr_line_position=None,
        username=request.sender.login,
        installation_id=request.installation.id,
        pr_number=request.check_run.pull_requests[0].number,
        comment_id=comment.id,
        repo=repo,
    )

示例 #2

基于 LlamaIndex 的 BaseIndex.ts 文件。我们的切分器正确地在导出的类和函数之间切分。✅

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

...

export class IndexDict extends IndexStruct {
  nodesDict: Record<string, BaseNode> = {};
  docStore: Record<string, Document> = {}; // FIXME: this should be implemented in storageContext
  type: IndexStructType = IndexStructType.SIMPLE_DICT;

  getSummary(): string {
    if (this.summary === undefined) {
      throw new Error("summary field of the index dict is not set");
    }
    return this.summary;
  }

  addNode(node: BaseNode, textId?: string) {
    const vectorId = textId ?? node.id_;
    this.nodesDict[vectorId] = node;
  }

  toJson(): Record<string, unknown> {
    return {
      ...super.toJson(),
      nodesDict: this.nodesDict,
      type: this.type,
    };
  }
}

========================================

export function jsonToIndexStruct(json: any): IndexStruct {
  if (json.type === IndexStructType.LIST) {
    const indexList = new IndexList(json.indexId, json.summary);
    indexList.nodes = json.nodes;
    return indexList;
  } else if (json.type === IndexStructType.SIMPLE_DICT) {
    const indexDict = new IndexDict(json.indexId, json.summary);
    indexDict.nodesDict = json.nodesDict;
    return indexDict;
  } else {
    throw new Error(`Unknown index struct type: ${json.type}`);
  }
}

...

算法其余部分 🤖

1. 依次遍历支持的语言列表，直到某个解析器成功解析代码
2. 对解析出的语法树根节点进行切分
3. 如果没有任何语言成功解析，则使用一个普通的切分器：每次取 40 行，并在块间保留 15 行重叠（覆盖），这种情况约占 0.1%

示例伪代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38