以前学 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

language_names = ["python", "java", "cpp", "go", "rust", "ruby", "php"] # and more

# Installing the parsers
languages = {}
for language in LANGUAGE_NAMES:
   subprocess.run(f"git clone https://github.com/tree-sitter/tree-sitter-{language} cache/tree-sitter-{language}", shell=True)
  for language in LANGUAGE_NAMES:
      Language.build_library(f'cache/build/{language}.so', [f"cache/tree-sitter-{language}"])
  self.languages = {language: Language(f"cache/build/{language}.so", language) for language in LANGUAGE_NAMES}

def chunk(text: str, MAX_CHARS: int = 1500) -> list[str]:
# Determining the language
for language_name in language_names:
    language = languages[language_name]
    parser = Parser()
    parser.set_language(language)
    tree = parser.parse(bytes(text, "utf-8"))
    if not tree.root_node.children or tree.root_node.children[0].type != "ERROR":
        file_language = language
        break
    logger.warning(f"Not language {language_name}")

# Smart chunker
if file_language:
      return chunk_node(tree.root_node, text, max_chunk_size)

# Naive algorithm
  source_lines = file_content.split('\n')
  num_lines = len(source_lines)
  logger.info(f"Number of lines: {num_lines}")
  chunks = []
  start_line = 0
  while start_line < num_lines and num_lines > overlap:
      end_line = min(start_line + chunk_size, num_lines)
      chunk = '\n'.join(source_lines[start_line:end_line])
      chunks.append(chunk)
      start_line += chunk_size - overlap
return chunks

在 Sweep，我们目前安装了 Python、Java、C++、Go、Rust、Ruby、PHP、C#、嵌入式模板（ERB & EJS）、Markdown、Vue 和 TSX。另请注意：C++ 覆盖 C，TSX 覆盖 JS、JSX 和 TS。

陷阱 🕳️

不幸的是，tree-sitter 有时并不可靠，很多解析器由社区维护：

• TSX 解析器在无法解析时会挂起而不是返回错误
• 此外，tree-sitter 的核心用 C 写成。在我们的 serverless 生产环境中运行需要一套复杂的方法来缓存已编译的 C 二进制，移动到可执行目录，并使用 Python 包装器去调用它们
• 有些解析器在子节点之间留下空隙。我们通过合并（coalescing）解决了这个问题
• 没有一种解析器会在解析错误的语言时都以相同方式报错
• 有些解析器将根节点标记为 “ERROR”，而有些则把第一个 child 标为 ERROR

我们通过在遇到这些错误（例如 TSX 挂起或其他不可靠行为）时回退到朴素切分器来规避问题，并将 TSX 优先级放在最后。同时我们会优先尝试与文件扩展名相对应的语言解析器。

未来 🔮

这个算法现在已通过 https://github.com/jerryjliu/llama_index/pull/7100 集成到 LlamaIndex 中。

另一个问题是，文件中相距较远的代码片段可能仍然需要共享上下文。例如，一个类的方法可能需要类头的上下文，长函数也需要函数签名。一个可能的改进是采用类似以下的格式来保留上下文：

1
2
3
4

class Foo:
  ...
  def bar(self):
      pass

我们可以考虑使用 universal ctags 或类似工具以实现更简单、更通用的解析，或者在手工标注的切分上训练一个自定义的 spaCy sentencizer，但那可能有点过度设计。

deepwiki 介绍

这里我们还是以 deepwiki-open为例进行分析。

通过这个截图可以知道它的主要功能：一键把任意 GitHub/GitLab/Bitbucket 仓库生成“可浏览的交互式 Wiki”

• 支持 RAG 的问答，根据 repo 的现有内容进行问答。
• 支持多种模型（Google Gemini、OpenAI、OpenRouter、Azure OpenAI、本地 Ollama等）
• 支持 DeepResearch：多轮研究流程，自动迭代直至给出结构化结论（适合复杂问题）

使用

要使用也很简单，我们用一个兼容 openai 的 key 就可以使用了。

在 .env 里配置下相关环境变量：

1
2

OPENAI_API_KEY="xxcdxxe"  
OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

同时我们在 generator.json 里为 openai 新增一个你所使用的模型：

这样就可以在页面上选择这个模型了。

同时我们还需要再 embedder.json 配置一个 embedding 模型，这个你的 LLM 提供商也会提供：

注意这里的 batch_size 需要修改为模型支持的大小

然后我们便可以填入一个 repo 地址，系统会自动生成 wiki。

流程

官方提供了一个流程图如下：

这个流程图略显粗糙，我整理一版更细的的流程如下：

1. 获取 repo 信息（前端）
       1.1. clone repo，同时在本地生成 RAG。
       1.2. 根据目录结构树和 readme 拼接内容传递给 AI 生成 wiki 的目录结构： prompt

        1.2.1. 通过【目录结构树和 readme】 先到 RAG 里查询具体的文档，然后再拼接与 system_prompt 拼接成一个完整 prompt 生成目录结构

        1.2.2. 如果 repo 过大导致目录树和 readme 的内容超过 token 限制，则不会去 RAG 里查询具体的内容来拼接生成目录结构，只会根据目录树和 readme 来生成，这样的目录结构信息可能会不全。

2. 根据目录结构拼接 prompt 生成每个目录的具体内容：prompt（前端）
       2.1 根据前端提交的目录 prompt 执行 RAG 检索，找出需要查询的 document，根据 document 里的源码构建最终的发往 LLM 的 prompt（后端）
           3. 将文件分组，拼接成 context_text
       2.2. 与 system_prompt 拼接成一个完整 prompt（后端）

 4. 循环 2， 继续处理前端提交上来的目录结构 prompt。

生成本地本地向量数据库

第一步是 clone 我们指定的 repo，同时会读取该 repo 里的所有内容在本地生成一个向量数据库。

相关的关键代码：

Spitter

在生成向量之前我们还需要构建一个分词器，它用于将我们的文本切分为一个个 chunk，以便：

• 避免超出模型/嵌入接口的长度上限
• 提高检索命中率（更细粒度地召回与问题相关的片段）
• 减少无关上下文的干扰，提升回答质量

在 deepwiki 里的配置如下：

• split_by: “word”（按“词”维度切分）
• chunk_size: 350（单块目标长度，约等于几百个词）
• chunk_overlap: 100（相邻块的重叠长度，保证跨块语义连续）

可能新手对 overlap 的作用不太清楚，它的好处是：

• 代码或文档的关键信息可能跨越边界；设置 overlap 能让相邻块共享一部分上下文，减少“切断语义”的风险。

对他的配置也需要按需使用：

• 过大 overlap 会导致重复计算、存储和费用增加；过小可能丢失跨段语义。

普通场景下 text_splitter 够用，但对于我们这种存代码的场景就需要使用特殊的 Spitter 了；主要问题是它不理解语言结构，容易把函数/类等语义单元切断，导致检索召回片段不完整、上下文丢失。

embedding

这里有一个关键的 embedding 操作，他是将我们的文字、语音、视频等非结构化数据转换为一个向量；类似于下面的代码：

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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"  # 百炼服务的base_url
)

completion = client.embeddings.create(
    model="text-embedding-v4",
    input='衣服的质量杠杠的，很漂亮，不枉我等了这么久啊，喜欢，以后还来这里买',
    dimensions=1024, # 指定向量维度（仅 text-embedding-v3及 text-embedding-v4支持该参数）
    encoding_format="float"
)

print(completion.model_dump_json())

而模型返回的数据如下：

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

{ 
  "data": [
    {
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... 
        -0.0028842222
      ],
      "index": 0,
      "object": "embedding"
    }
  ],
  "model":"text-embedding-v4",
  "object":"list",
  "usage":{"prompt_tokens":23,"total_tokens":23},
  "id":"f62c2ae7-0906-9758-ab34-47c5764f07e2"
}

在 deepwiki 这个项目里，我们没有主动调用这个接口，而是由 AdalFlow 这个库在内部完成的。

也就是这行代码 db.transform(key="split_and_embed")

在 deepwiki 中我们只是简单将向量数据存放在了本地，实际生产使用时还需要将其存放到一个单独的向量数据库。

生成目录

然后就是与 AI 交互了，第一步是生成目录，类似于这样：

系统生成的提示词如下，其实就是把 repo 的目录结构树+readme 文件的内容与 system_prompt 拼接成一个完整的提示词告诉 LLM，让它返回一个项目的目录结构。

主要是以下的一些要求：

• 必须只返回 XML，根节点为 <wiki_structure>，以 </wiki_structure> 结束
• XML 必须语法有效、严格按指定结构
• 页面数量要求：
  • 综合模式（comprehensive）：8–12 个页面
  • 精简模式（concise）：4–6 个页面
• 内容语言由参数指定（英文、中文、日文等）
• 每个页面应聚焦代码库的一个具体方面（架构、特性、部署、前端/后端模块等）
• relevant_files 必须是仓库中的真实文件路径，用于后续生成具体页面内容

每个目录的具体详情页

目录生成完成之后就需要生成该页面的具体内容了，比如这个页面：

他的提示词如下：

其中的主要约束如下：

相关源文件清单（强制）

• 在最顶部的 
   中逐条列出所有用于生成内容的源文件，且至少 5 个。
• 每个文件以 Markdown 链接形式出现（已给出可点击的仓库文件 URL）。
• 若输入文件少于 5 个，模型需“补足更多相关文件”。
• Mermaid Diagrams（大量使用，强制规则）

总结就是：结构合理、层次分明，便于理解与导航点击。

总结

以上就是对 deepwiki 项目的分析，作为一个典型的 RAG 应用，掌握它的流程便可以举一反三来实现其他类似的 RAG 应用。

当然其中有许多需要调优的地方，比如模型的选择、Spitter 参数的配置、RAG 召回 top_k 的配置等等。

还要平衡好效果与成本。
#Blog

AI/LLM 大模型最近几年毋庸置疑的是热度第一，虽然我日常一直在用 AI 提效，但真正使用大模型做一个应用的机会还是少。

最近正好有这么个机会，需要将公司内部的代码 repo 转换为一个 wiki，同时还可以基于项目内容进行对话了解更具体的内容。

实际效果大概和上半年很火的 deepwiki 类似。

而我们是想基于开源的 deepwiki-open进行开发，提供的功能都是类似的。

在这个过程中我也从一个大模型应用开发的小白逐步理解了其中的一些关键概念，以及了解了一个大模型应用的运行原理。

LLM

LLM（Large Language Model，大语言模型）大家应该都比较熟悉了：

• 本质：一个通过海量文本训练出来的概率模型
• 能力：理解/生成文本、代码，做推理、对话等
• 特点：
  • 参数固定：训练完之后“记忆”是固化在参数里的
  • 知识有时间点：只知道训练截止前的数据（有知识截止时间）

可以把 LLM 当成一个“通用大脑”，但不一定知道最新的、你的私有数据。

目前的 AI 也就是大模型本质上还是概率预测，当你给它一段话（Prompt）时，它在后台做的事情是：“根据我读过的几万亿字，接在这段话后面，概率最高的下一个字（Token）是什么？”

所以大模型每次回答的内容可能不同，也不能 100% 的告诉你准确答案。

Token

大模型并不直接认识java、Rust 或者“编程”这些词。在模型内部，所有的文字都会先被转换成一系列数字。

• 字/词 ≠ Token：一个 Token 既不是一个字符，也不是一个单纯的单词。
• 灵活切分：
  • 常见的词（如 the, apple）通常对应 1 个 Token。
  • 罕见的词或长的复合词（如 microservices）可能会被拆分成几个 Token（如 micro + services）。
  • 中文通常比较特殊：一个常用的汉字可能是 1 个 Token，但不常用的汉字可能会占用 2-3 个 Token。

在做大模型应用开发的时候尤其需要注意 token 的用量，毕竟这是计费的标准。

还有一个是上下文窗口的限制，每个模型都会有最大 token 的限制（如 8k, 32k, 128k）。

如果你的 Prompt 加上模型的回复超过了这个限制，模型就会丢掉前面的记忆或者直接报错。

在日常开发估算中，可以大概估算一下这个比例：

• 英文文本：1000 Tokens ≈ 750 个单词。
• 中文文本：1000 Tokens ≈ 500 到 600 个汉字（随着模型词表的演进，现在的模型处理中文的效率在不断提升。）。
• 代码：代码中的空格、缩进和特殊符号都会消耗 Token。Python 等由于缩进较多，消耗通常比纯文本快。

也有相关的库可以帮我们计算 token：

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

  
# Choose encoding based on embedder type  
if embedder_type == 'ollama':  
    # Ollama typically uses cl100k_base encoding  
    encoding = tiktoken.get_encoding("cl100k_base")  
elif embedder_type == 'google':  
    # Google uses similar tokenization to GPT models for rough estimation  
    encoding = tiktoken.get_encoding("cl100k_base")  
else:  # OpenAI or default  
    # Use OpenAI embedding model encoding    
    encoding = tiktoken.encoding_for_model("text-embedding-3-small")  
  
return len(encoding.encode(text))

也可以通过 openai 的一个实例网站来可视化查看 token 的计算规则：

RAG

RAG 的全程是Retrieval-Augmented Generation（检索增强生成），他不是类似于 LLM 的模型，而是一种架构模式。

举个例子：
比如你问 ChatGPT 关于你们公司的某一个规章制度，大概率 ChatGPT 的训练语料是你没有你们公司的内部数据的。

所以他回复你的多半是瞎编的内容，或者直接告诉你不知道。

此时就需要 RAG 了，他可以在真正询问 LLM 之前先到内部的资料库里通过用户的问题将相关上下文查询出来，然后再拼接成一个完整的 prompt 发送给 LLM，让 LLM 根据你通过的数据进行回答。

这样能解决一下三个问题：

1. 幻觉问题：你问它一个它不知道的事情，它会一本正经地胡说八道。
2. 知识过时：大模型的知识停留在它训练结束的那一天。
3. 私有数据安全：你不能为了让 AI 懂你的业务代码，就把几百万行私有代码全发给模型提供商训练一个新模型，那太贵且不安全。

使用 RAG 时还需要额外考虑到数据清洗的步骤，比如我们这里的 repo wiki 的场景，我们需要把一些第三方库、编译后产生的 target 目录等不需要的内容排除掉。

避免在查询时带上这些内容，干扰最终的结果。

向量数据库

上文里提到 RAG 模式，需要一个非常关键的组件，那就是向量数据库。

我们先要在 RAG 里检索出相关的上下文就是在向量数据库里做查询，具体流程如下：

1. 把文档切块（段落级别）
2. 用一个 Embedding 模型 把每个块转成向量
3. 把这些向量存进 向量数据库
4. 用户提问时，也把问题转成向量
5. 用向量相似度检索出最相关的文档块
6. 把这些文档块 + 问题喂给 LLM，让它生成答案

简单来说就是将一些非结构化的数据（图片、视频、文字）通过Embedding 模型 转换成一串数字数组，即向量（例如：[0.12, -0.59, 0.88, ...]）。

查询的时候也会将查询内容转换为向量，然后返回在向量空间里相近的数据。

Q&A

此时也许你会有以下一些问题：

LLM + RAG + 向量数据库，是不是类似于用 LLM 训练私有化数据？这两者的效果是否类似？ 如果不同，区别在哪里？

LLM + RAG + 向量数据库：

• 本质是：

  不改模型参数，用检索到的外部资料来“喂”模型，让它查完再答。

• 你的数据在外部（向量数据库里），只是当作参考材料塞进 prompt。

在私有数据上训练（微调 / 预训练）：

• 本质是：

  用你的数据更新模型参数，让模型“记住”这些模式和知识。

• 你的数据被“烤进”模型权重里，调用时不需要再查这份数据。

总的来说使用 RAG 外挂私有化向量数据的成本更低，也更灵活。
对于一些更垂直的场景，可以考虑使用私有数据训练模型。

总结

总体下来的感受是 LLM 应用大部分的代码都是 prompt 提示词，普通 app 的主要内容是代码，而不同大模型应用的主要区别是提示词；反而代码大部分都是趋同的。

区别就是用了什么框架，但是共同的就是调用大模型 API，将传统的 request/reponse 的请求模式换为流式响应（大模型的响应很慢）。

在开发应用时，需要了解 System Prompt（系统预设角色）、User Prompt（用户提问）和 Few-shot（给模型几个例子引导它）。好的 Prompt 是让 RAG 结果准确的关键。

后续还需要更加完善 deepwiki-open：

• 优化 splitter，使用更适合代码分割的 splitter，比如 tree-sitter
• 将存储在本地的向量替换为一个独立的向量数据库
• 持续优化提示词，更加符合我们的项目背景

#Blog

最近在做持续剖析 Profile 与链路系统打通的工作，就查到了 grafana 在 24 年初写的这篇文章；觉得比较有参考意义，在这里分享给大家。

原文链接：https://grafana.com/blog/2024/02/06/combining-tracing-and-profiling-for-enhanced-observability-introducing-span-profiles/

在当今复杂的数据环境中，连续剖析（continuous profiling）已成为获取应用资源使用情况细粒度洞察的关键。Grafana Labs 现通过在 Grafana 10.3 中引入 Span Profiles 功能，将这工作持续推进。

Span Profiles 代表着剖析方法学上的一次重大转变，它让我们能够对追踪（tracing）和剖析（profiling）数据进行更深入的联合分析。传统的连续剖析是在固定时间区间内提供全局系统视角；相比之下，Span Profiles 可以对应用内部特定执行作用域（execution scope）进行更聚焦的分析，例如单个请求或某个特定的 trace span 分析它的 Profile。

这一转变带来了更精细的性能视角：通过将剖析数据与 trace 直接关联，帮助我们更全面地理解应用行为。由此，工程团队可以更高效地识别并解决性能瓶颈。

在我们于 Grafana Labs 内部采用这一集成的 “trace-to-profile” 方法的第一个月中，CPU 利用率提升了 4 倍，对对象存储的 API 调用减少了 3 倍，同时还降低了成本（详见下文）——因此，我们非常高兴能向社区推出这一特性！

与 Grafana Trace 视图集成：无缝体验

借助 Span Profiles，你可以在执行作用域内部挖掘具体的性能细节。比如，以前你只知道某个 span 花了 400ms，现在则能进一步了解：在这 400ms 里具体是哪部分代码在运行；从而更快的知道性能瓶颈

使用 Span Profiles 的 flamegraph 截图。

这种有针对性的方式，让你可以比以往更细粒度地剖析性能指标。通过聚焦于单个请求或单个 trace span，Span Profiles 为你提供了一扇直接洞察应用性能关键部分的窗口。

Span Profiles 与 Grafana trace 视图 的集成，为用户带来无缝体验：你可以轻松地从高层级的 trace 概览，切换到对某个具体 trace span 进行深入分析。

引入 Span Profiles 不仅是一次技术上的飞跃，同时也有非常可观的业务和投资回报（ROI）价值。

通过帮助团队更快地识别并解决性能问题，Span Profiles 减少了排障所需的时间和资源投入。这种效率的提升带来显著的成本节约，让 Span Profiles 成为既能优化应用性能，又能降低运维成本的有力工具。

Grafana Labs 内部的真实案例

为了更直观地展示 Span Profiles 的业务价值，下面是我们在 Grafana Labs 内部使用该特性的一个实际案例。

几个月前，Grafana Pyroscope 团队（Pyroscope 是支撑 Grafana Cloud Profiles 的开源连续剖析数据库）在数据库架构中新增了 compactor 组件，带来了显著的性能和成本收益。

compactor 会通过合并多个 block 来提升查询性能，并减少长期存储的使用。它在为每个租户将多个 block 压缩成单个优化 block 的过程中扮演关键角色，这不仅降低了存储成本，也加快了查询速度。

compactor 组件结构图。

然而，压缩过程本身非常复杂——包括竖向压缩、横向压缩以及拆分与合并（split-and-merge）策略等多个阶段——这些都带来了一些挑战，尤其是与性能瓶颈相关的挑战。例如，在密集的压缩操作期间，CPU 和内存使用可能会出现明显峰值，存储 IO 需求也会显著增加，从而可能影响整体系统稳定性。此外，在拥有大量租户的大规模集群中，管理和优化这些大规模压缩任务所需的资源也非常复杂。而这正是 Span Profiles 功能展现其独特优势的地方。

通过对每一次压缩运行进行详细剖析，Span Profiles 能够在 trace 视图中直接提供按函数维度划分的 CPU 使用情况。这种与 trace 视图相结合的细节信息至关重要：它不仅能指出压缩过程的哪个阶段出现了瓶颈，还能告诉你每一次压缩影响到了哪些用户。

展示不同压缩操作对用户影响的 flamegraph。

例如，我们发现由于符号信息的影响，一级（level 1）压缩是一个主要瓶颈；同时，我们也识别出每次运行中存在过度的 block 同步问题。有了这些数据，我们随之对压缩算法做出了有针对性的调整。改动带来的效果立竿见影：压缩时间减少了 4 倍，对对象存储的 API 调用量减少了 3 倍。

对象存储 API 调用量下降的仪表板截图。

如果只看 GET 请求的减少，节省就已经非常可观。以 Google Cloud Storage Class B/GET 的费用来计算，这些调整每月大约节省了 8,000 美元（计算方式为：0.0004 美元/次 GET 请求 * 每分钟节省 400 次请求 * 60 分钟 * 24 小时 * 31 天）。

Span Profiles 功能为应用剖析翻开了新篇章。通过在特定执行作用域上提供详细洞察，它彻底改变了性能问题的识别与解决方式。

如何开始使用 Span Profiles

Span Profiles 目前已经在 Grafana Cloud 和 Grafana 10.3 中提供。想要进一步了解这一特性，你可以参考我们的技术文档，以及以下入门资源：

• 配置 Pyroscope 以发送剖析数据
• 配置客户端包以将 trace 与 profile 关联：
  • Go
  • Ruby
  • Java
• 配置 Tempo 以发现已关联的 traces 和 profiles

更多关于 Span Profile 的具体使用案例会在继续更新。

#Blog

在 StarRocks 中审计日志记录了所有用户的查询和连接信息，理论上我们只需要对这些日志进行分析就可以得到相关的慢 SQL，高 CPU、高内存的 SQL 信息。

类似于这样的监控界面：

由于这些数据都是存放在日志文件里的我们想把他拿到 grafna 里展示的话得额外处理下。

结构化日志

默认情况下审计日志是以文本格式输出的，当然我们也可以使用一个审计插件，将审计日志写入到一张单独的表里供后续分析，也可以实现类似的效果。

具体使用可以参考官方文档：

这里我们选择一个更简单的方法，我们可以将日志输出为 JSON 格式，然后再将其结构化，为每个字段创建索引，存入到单独的日志服务里。

由于我们使用了云厂商的日志服务能力，只需要为这个日志文件（fe/log/fe.audit.log）配置一个采集服务，然后为其中的字段创建索引即可。

这样我们可以就可以通过云厂商提供的 grafna 插件将这里的日志作为一个数据源集成到 grafna 中。

之后就可以在 grafna 中直接使用云厂商提供的查询语法来查询我们刚才的审计日志了。

1

IsQuery:"true"|SELECT QueryId,Stmt,Time,CpuCostNs,MemCostBytes,ScanBytes,ScanRows,ReturnRows ORDER BY CpuCostNs DESC LIMIT 10

比如这样的查询语句含义是：限制为查询的 SQL（还有其他的 alter delete 等 SQL）、按照 CPU 耗时排序。

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

CREATE TABLE starrocks_audit_db__.starrocks_audit_tbl__ (
  `queryId` VARCHAR(64) COMMENT "查询的唯一ID",
  `timestamp` DATETIME NOT NULL COMMENT "查询开始时间",
  `queryType` VARCHAR(12) COMMENT "查询类型（query, slow_query, connection）",
  `clientIp` VARCHAR(32) COMMENT "客户端IP",
  `user` VARCHAR(64) COMMENT "查询用户名",
  `authorizedUser` VARCHAR(64) COMMENT "用户唯一标识，既user_identity",
  `resourceGroup` VARCHAR(64) COMMENT "资源组名",
  `catalog` VARCHAR(32) COMMENT "数据目录名",
  `db` VARCHAR(96) COMMENT "查询所在数据库",
  `state` VARCHAR(8) COMMENT "查询状态（EOF，ERR，OK）",
  `errorCode` VARCHAR(512) COMMENT "错误码",
  `queryTime` BIGINT COMMENT "查询执行时间（毫秒）",
  `scanBytes` BIGINT COMMENT "查询扫描的字节数",
  `scanRows` BIGINT COMMENT "查询扫描的记录行数",
  `returnRows` BIGINT COMMENT "查询返回的结果行数",
  `cpuCostNs` BIGINT COMMENT "查询CPU耗时（纳秒）",
  `memCostBytes` BIGINT COMMENT "查询消耗内存（字节）",
  `stmtId` INT COMMENT "SQL语句增量ID",
  `isQuery` TINYINT COMMENT "SQL是否为查询（1或0）",
  `feIp` VARCHAR(128) COMMENT "执行该语句的FE IP",
  `stmt` VARCHAR(1048576) COMMENT "SQL原始语句",
  `digest` VARCHAR(32) COMMENT "慢SQL指纹",
  `planCpuCosts` DOUBLE COMMENT "查询规划阶段CPU占用（纳秒）",
  `planMemCosts` DOUBLE COMMENT "查询规划阶段内存占用（字节）",
  `pendingTimeMs` BIGINT COMMENT "查询在队列中等待的时间（毫秒）",
  `candidateMVs` varchar(65533) NULL COMMENT "候选MV列表",
  `hitMvs` varchar(65533) NULL COMMENT "命中MV列表",
  `warehouse` VARCHAR(128) NULL COMMENT "仓库名称" 
)

审计数据里的信息非常丰富，可以组合出各种查询条件。

比如：

• 限制查询时间大于多少，可以只查询慢 SQL
• 根据内存占用排序
• 执行失败的 SQL

大家可以按需选择。

开源替换

如果没有使用云厂商，一些开源组件也能满足以上需求：

• 结构化存储日志
• 根据字段创建索引
• 类 SQL 查询
• 支持 grafna 数据源，方便做可视化