「虚拟线程不就是 Java 版的协程吗」——这句话我在面试复盘里见过太多次，每次都想打断。

先把能站住的结论给出来：虚拟线程是 JDK 替你管理的线程，协程是编译器替你改写的函数。前者干的事是让「一个请求一个线程」重新变得便宜，后者干的事是让「一个函数可以在中间让出去」变成语言能力。它们在压测数字上经常被放进同一张图比较，但机制上没有血缘关系，混着答，面试官一追问第三层就会露馅。

我把这道题答过也被问过，下面按「机制 → 版本现状 → 什么时候真有用」的顺序拆开。

一、一句话答案，先背下来

• 虚拟线程解决的是线程太贵。
• 协程解决的是代码写不直。
• 两者都是 M:N，都是协作式让出，都不解决 CPU 不够。

最后一行我特意对齐了：两者都不是抢占式的。很多人以为协程是抢占式、虚拟线程是协作式，其实反过来也一样不成立，都是遇到挂起或阻塞点才换人。

二、调度：都在做 M 比 N，但谁在调度完全不同

虚拟线程的调度在 JVM 里。JEP 444 的表述很清楚：虚拟线程是由 JDK 而不是操作系统提供的轻量线程，运行时把它们挂载到载体线程上，阻塞时卸载，载体空出来给下一个虚拟线程用。这套调度器用的就是 ForkJoinPool 的工作窃取模型，载体线程数默认等于核数，可以用系统属性调。

协程的调度不在语言里，在库里。suspend 只是编译器约定的一个标记：带 suspend 的函数编译后多一个续体参数，挂起时把续体存起来返回，恢复时调 resume 继续跑。至于 resume 之后落到哪个线程，那是 Dispatchers 的事。

我的理解：虚拟线程把 M:N 藏在 JDK 内部，所以业务代码完全看不见；协程把 M:N 露在库的 API 上，所以你必须决定用哪个 Dispatcher。前者省心，后者可控，代价是协程这边一旦 Dispatcher 选错，比如把阻塞调用扔到只有核数个线程的 Dispatchers.Default 上，整条链就堵死了，而虚拟线程没有这个旋钮可拧。

三、栈怎么放：这条最能区分两者

平台线程的栈在本地内存里，先 reserve 一大块，用多少提交多少。线程数一上去，光是栈的预留和内核的调度开销就压住了天花板。

虚拟线程的栈在堆上，是一块可增长的栈块。挂载时把栈帧搬进载体线程的栈，卸载时再搬回来。能搬，意味着调用栈可以很深，也意味着栈本身就是 GC 能看见的对象。

协程没有「搬栈」这个动作。编译器把 suspend 函数切成若干个状态机，局部变量从栈帧变成状态机对象的字段。所以协程的调用栈深度其实是被状态机的形状决定的，中间隔一层普通函数还好，深递归加挂起会让状态机对象一层层叠起来。

这里我不太同意一种流行说法：「协程比虚拟线程更轻，因为协程没有栈」。字节层面没有统一裁判——协程的每个挂起帧都是一个对象，虚拟线程的栈块也是堆上的对象。真正的差别不在谁更轻，而在可以创建多少个，以及挂在阻塞调用上会不会占住载体线程。拿「轻量」当结论，面试官换个问法你就答不上来了。

四、阻塞语义与传染性：取舍都在这里

虚拟线程最大的卖点是它仍然阻塞。你写 socket.read()、Thread.sleep、connection.query，代码还是那个同步阻塞的样子，JDK 在底层把这些阻塞点改造成可卸载。这意味着已有的 Spring MVC 应用、已有的 JDBC 调用，换个 Executor 就能受益，签名一行不改。

协程刚好相反：阻塞必须显式。delay 而不是 Thread.sleep，阻塞 IO 要包进 withContext(Dispatchers.IO)。误用一次阻塞 API，协程不会让出，整个线程池被占住，而且不会有任何报错——这是协程最容易踩的坑。

传染性是同一个取向的两面：协程的 suspend 会顺着调用链一路上色，改一个底层方法，上面十层签名全要动；虚拟线程对上层完全透明，你不需要知道某个方法内部有没有阻塞。

我的判断：传染性不是缺点也不是优点，它是两种设计哲学的必然产物。Java 选了「不破坏二十年的存量代码」，所以必须做到透明，代价是阻塞语义只能靠运行时兜底；Kotlin 选了「让副作用显式化」，代价是函数着色。面试时把这一层说出来，比背「协程更轻」强得多。

五、三层调度模型长什么样

  flowchart LR    A[Java 业务代码] --> B[平台线程池\n一请求一线程]    A --> C[虚拟线程\n由 JDK 提供]    B --> E[OS 线程\n内核调度]    C --> F[载体线程 ForkJoinPool\nJVM 调度]    F --> E    K[Kotlin 业务代码] --> D[协程\n由库提供]    D --> G[编译器生成的状态机\n续体对象]    G --> H[Dispatchers 线程池\n库负责调度]    H --> E    E --> I[CPU 与系统调用]  

这张图想让你看见什么：不管你写的是平台线程、虚拟线程还是协程，最终都要落到 OS 线程上。三者的差别只在最上面那一段——是谁在把逻辑单元多路复用到更少的 OS 线程上。虚拟线程那一层的多路复用是 JVM 干的，协程那一层是编译期改造加库调度共同完成的，平台线程压根没有这一层。所以面试里说「虚拟线程减少了线程切换」，严格说减少的是用户态挂载卸载，不是内核上下文切换，因为载体线程数没变。

六、挂载、卸载与钉住的状态图

  stateDiagram-v2    [*] --> 新建    新建 --> 运行中 : 被调度器选中并挂载到载体    运行中 --> 运行中 : 纯计算 一直占着载体线程    运行中 --> 已卸载 : 遇到可卸载阻塞 例如 Socket 读    已卸载 --> 运行中 : 事件就绪 重新挂载到某个载体    运行中 --> 已钉住 : synchronized 内阻塞 或 native 回调阻塞    已钉住 --> 运行中 : 阻塞结束 载体才被释放    运行中 --> [*] : 任务结束  

这张图想让你看见什么：只有「已卸载」这一条边是免费的。虚拟线程的价值全部来自运行中到已卸载这一跳，跳到「已钉住」就等于退化成了平台线程，还多付了一份挂载的成本。JDK 21 的时候「运行中 → 已钉住」主要由 synchronized 里阻塞触发；JDK 24 之后这条边基本只剩 native 方法和 FFM 回调。面试官问「虚拟线程为什么会失效」，你指着这条边答就对了。

七、JDK 27 的现状：三件事必须核清楚

第一件，虚拟线程已经不是新东西了。 JEP 444 在 Java 21 正式交付，状态是 Delivered，虚拟线程是标准库的一部分，早就不是预览特性。从 21 到 27，它已经跨过了六个大版本。

第二件，钉住问题在 JDK 24 被 JEP 491 解决了。 JEP 491 的标题就是「Synchronize Virtual Threads without Pinning」，Release 是 24。它让阻塞在 synchronized 方法或语句里的虚拟线程释放载体线程，覆盖了 monitorenter 和 Object.wait，目标是「消除几乎所有虚拟线程被钉在平台线程上的情况」。剩余场景 JEP 491 也写明了：虚拟线程调用 native 方法，或者通过 Foreign Function & Memory API 进入本地代码，而那段本地代码又回调 Java 里的阻塞操作。观测手段保留并增强——JFR 事件 jdk.VirtualThreadPinned 继续存在，还会带上钉住原因和载体线程的标识；而 jdk.tracePinnedThreads 这个系统属性在 24 之后不再需要了。

第三件，JDK 27 不是 LTS。 这条是面试里最容易被抓的硬伤。JDK 27 在 2026-09-15 达到 GA，但它是非 LTS 的特性版本。Oracle 的官方路线图写得很直白：Java SE 8、11、17、21、25 是 LTS 版本，下一个计划中的 LTS 是 2027 年 9 月的 Java 29。所以「JDK 27 是下一个 LTS」这句话是错的，说错了比不说更扣分。

还有一个很多人不知道的点：JDK 27 里 Structured Concurrency 仍然是第七次预览，也就是 JEP 533。虚拟线程早就转正了，但它「最搭的那套结构化并发 API」到 27 还没定型。这个事实特别适合用来回答「虚拟线程现在还有什么没解决」——不是虚拟线程本身没解决，是围绕它的编程模型还在打磨。

我踩过的坑：最早在 21 上做压测，把一堆老 DAO 直接塞进虚拟线程执行器，结果吞吐比固定线程池还差，排查半天才发现 synchronized 包着远程调用，每个虚拟线程都把载体钉死，JFR 里 jdk.VirtualThreadPinned 刷屏。那次之后我的结论很朴素：上虚拟线程之前先跑一遍 JFR，看有没有钉住，比看任何博客都准。

八、两段代码，看清各自阻塞点在哪

Java 这边，虚拟线程的写法几乎不需要改变习惯：

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

import java.time.Duration;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class VirtualThreadDemo {
    public static void main(String[] args) {
        try (ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor()) {
            for (int i = 0; i < 10_000; i++) {
                int orderId = i;
                pool.submit(() -> {
                    Thread.sleep(Duration.ofMillis(50)); // 阻塞点：看起来是同步阻塞
                    System.out.println("done " + orderId);
                    return orderId;
                });
            }
        } // close 会等待所有任务结束
    }
}

这段代码在说明什么：Thread.sleep 是阻塞调用，虚拟线程在这里会被卸载，载体线程立刻去跑下一个任务。整段代码没有任何 suspend、async、回调，业务方法签名一个字没改——这就是「对上层透明」的实际含义。一万个任务只需要几个载体线程就能撑住，因为真正占着线程的时间接近于零。另外注意这里是每个任务新建一个虚拟线程，不是从池里借——JEP 444 原话就是虚拟线程便宜且充足、因此永远不该被池化。

Kotlin 这边，同一个语义必须靠挂起点来表达：

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

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking

suspend fun loadOrder(id: Int): Int = coroutineScope {
    delay(50) // 挂起点：不占线程
    println("done " + id)
    id
}

fun main() = runBlocking {
    val results = (1..10_000)
        .map { id -> async(Dispatchers.IO) { loadOrder(id) } }
        .awaitAll()
    println(results.size)
}

这段代码在说明什么：delay 是挂起函数，它让出线程的方式是把续体存进状态机然后返回；如果这里手滑写成 Thread.sleep，协程根本不认识这个阻塞点，线程照占不误，而且编译期不报错。另外 loadOrder 带 suspend 标记，任何调用它的上层函数也必须 suspend，这就是着色传染的现场证据。注意 async 那里显式指定了 Dispatchers.IO，因为默认的 Dispatchers.Default 线程数约等于核数，拿它跑阻塞调用等于自己给自己挖坑。

九、我的判断：什么场景虚拟线程真省钱

我的判断：虚拟线程真正省钱的场景只有一个特征——等待时间远大于计算时间，并且等待发生在 JDK 认识的阻塞点上。除此之外它更像「看起来美」：CPU 密集场景下它不比平台线程快，连接池打满的时候它只是把 Tomcat 的排队搬到了连接池的排队，本质没变，但监控指标变了，很多人这时候会误判成「虚拟线程没用」。真实情况是瓶颈转移了，你要做的是重新量一次 RT 分布，而不是换回平台线程。

反过来说，协程那边也别迷信。协程解决的是表达问题，它不会让你的下游变快，也不会自动帮你把阻塞调用改成非阻塞。这一点上两者完全平等：它们都在优化「线程太贵」，没有在优化「依赖太慢」。

十、面试里这样答，比背口号容易加分

顺序是边界、机制、版本、反例。

先给边界：「虚拟线程和协程解决的不是同一个问题，前者降低线程成本，后者改变代码表达方式，所以它们不是替代关系」。

再给机制：「虚拟线程由 JVM 调度，栈在堆上可搬运，阻塞对上层透明；协程靠编译器把 suspend 函数改写成状态机，由库的 Dispatcher 调度，阻塞必须显式挂在挂起点上」。

然后给版本：「虚拟线程 21 年由 JEP 444 转正，24 年 JEP 491 解决了 synchronized 钉住，剩下的钉住场景是 native 和 FFM 回调；JDK 27 已经 GA 但不是 LTS，LTS 是 8、11、17、21、25，下一个是 2027 年 9 月的 Java 29」。

最后给反例：「所以不能说虚拟线程是协程的 Java 实现，也不能说它让 CPU 密集任务变快，更不能说 27 是 LTS」。

这四步答完，追问基本就到顶了。

落地清单

1. 记死三个 JEP 号：444 虚拟线程、491 解除 synchronized 钉住、533 结构化并发第七次预览。
2. 记死版本定位：LTS 是 8、11、17、21、25，下一个 LTS 是 Java 29（2027-09），JDK 27 在 2026-09-15 GA 但不是 LTS。
3. 上线前先跑一遍 JFR，盯 jdk.VirtualThreadPinned，有钉住先改锁或升版本，别急着调参。
4. 判断要不要上虚拟线程，只问两个数：IO 等待占比，以及下游连接池上限。
5. 协程侧的论据只引官方文档里的 Continuation 与 suspend 语义，不编版本号。
6. 任何「虚拟线程更快」的结论，都补一句「在什么阻塞模型、什么依赖库版本下」，否则就是口号。

参考来源

• JEP 444: Virtual Threads（Java 21，Delivered）— https://openjdk.org/jeps/444
• JEP 491: Synchronize Virtual Threads without Pinning（JDK 24）— https://openjdk.org/jeps/491
• JDK 27 项目页（2026-09-15 GA，JEP 533 结构化并发第七次预览）— https://openjdk.org/projects/jdk/27/
• Oracle Java SE 支持路线图（LTS 为 8/11/17/21/25，下一个 LTS 是 Java 29，2027-09）— https://www.oracle.com/java/technologies/java-se-support-roadmap.html
• Oracle 虚拟线程官方指南（挂载卸载、钉住、JFR 事件 jdk.VirtualThreadPinned 默认阈值 20ms）— https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html
• Kotlin 协程基础（suspending functions、coroutine builders）— https://kotlinlang.org/docs/coroutines-basics.html
• Kotlin Continuation 接口文档（挂起点之后的续体）— https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-continuation/

先说结论：这次事故的重点不是“我把目录放错了”，而是一条看起来完全正确、而 Hexo 连一个字都不警告的 ignore 配置，静默地什么都没干。

我在 _config.yml 里按官方文档的风格写了 _posts/copilot/**，跑 hexo generate 一切正常、退出码 0、没有任何 warning、文章列表也不报错——而线上依旧挂着两篇我不认识的文章。等把源码翻出来才发现，自己同时踩了两个坑：一个是目录位置，一个是 Hexo 6.x 用绝对路径去做 ignore 匹配。第二个坑才是真正浪费时间的那个。

一、症状：一篇标题叫占位符的文章

事情是从一个奇怪的内链开始的。我在首页刷到一篇文章，标题显示成 {{title}} 这种字面量，点进去正文是空的，URL 是 /posts/pagelink.html。

顺着 URL 猜 abbrlink，.md 文件名可能被改过，但 front-matter 里的 abbrlink: pagelink 一定还在。全仓 grep 一次就定位到了：

1
2
3
4
5

# source/_posts/scaffolds/page.md
title: "{{title}}"
description: page默认模版
abbrlink: pagelink
date: "{{date}} {{time}}"

这不是文章，这是 hexo new page 用的页面模板。它的 title 就是占位符本身，date 也是占位符，所以渲染出来的文章标题永远是 {{title}}、发布时间永远是字符串 {{date}} {{time}}。它被当成普通文章送进渲染管线，于是诞生了 /posts/pagelink.html。

顺手查 Tag 页，又冒出来一个 /tags/copilot-conversation/，点进去是 /posts/0.html：

1
2
3
4
5
6
7
8

# source/_posts/copilot/copilot-conversations/agent__xxx.md
epoch: 1791876529103
mode: agent
backendId: codex
sessionId: 01a13429-cf08-7083-8213-2825df351b2f
tags:
  - copilot-conversation
abbrlink: '0'

这是 Obsidian Copilot 插件的对话归档，一整个目录 16 个 .md，front-matter 是插件自己写的元数据，abbrlink 还是 ‘0’——其中两个文件的 abbrlink 完全一样，于是它们在 db.json 里互相覆盖，16 篇污染最后只暴露成 1 篇。这个掩盖效应很要命：你看到的症状规模，远小于实际污染规模。

这里我不太同意“这就是点脏数据，删了就完事”的说法。 它已经不是脏数据了，它是污染：它进了 db.json、进了 Tag 索引、进了 sitemap、被静态托管同步到了线上、还被 CDN 缓存住。删源文件只能让下一次构建变干净，线上那几份副本得另外处理。

二、Hexo 凭什么决定“什么算文章”

先给总览。下面这张图是这次的完整问题链路，从目录一直走到你浏览器里看到的那个幽灵页面：

  flowchart LR  A[普通目录放进 source/_posts] --> B[readDirWalker 遍历目录]  B --> C{ignore 是否命中目录本身}  C -->|是| D[目录层剪枝 整棵子树跳过]  C -->|否| E{isHiddenFile 判定路径段首字符}  E -->|是 下划线或点| F[当作隐藏文件跳过]  E -->|否| G[注册为文章并渲染]  G --> H[写入 db.json 与 public]  H --> I[静态托管部署]  I --> J[自定义域名经 CDN 缓存]  J --> K[线上出现幽灵页面]  

这张图想让你看见什么：能不能变成“文章”，只由两个判定决定——ignore 匹配和 isHiddenFile。而“线上出现幽灵页面”在链条最末端，意味着你在前端犯的错，要先经过渲染、写库、部署、缓存四跳才变得可见；反过来，在前端删掉文件，也不会让末端立刻恢复。这条链路是不对称的，这是所有排查时间的来源。

之所以 source/posts/scaffolds/page.md 会被当文章，是因为 scaffolds 这个路径段既不以 开头、也不以 . 开头。判定就写在 node_modules/hexo/lib/plugins/processor/common.js 里：

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

// node_modules/hexo/lib/plugins/processor/common.js:19-21
function isHiddenFile(path) {
  return /(^|\/)[_.]/.test(path);
}

// :24-30
function isExcludedFile(path, config) {
  if (isTmpFile(path)) return true;
  if (isMatch(path, config.exclude)) return true;
  if (isHiddenFile(path) && !isMatch(path, config.include)) return true;
  return false;
}

这段代码在说明什么：正则 /(^|\/)[_.]/ 是按路径段匹配的，不是按文件名。所以 source/_posts/.obsidian/、.copilot/、.agents/、.trash/ 这些点开头的目录天然安全，名叫 .nopost 的目录也一样安全；而 scaffolds/、copilot/ 这种普通名字的目录天然不安全。我仓库里 _posts 下确实混着这两类目录，事故只是其中不安全的那一半发作了。

顺带一句：exclude 帮不上忙。官方文档在 exclude 的示例旁边就明写了 “posts/hello-world.md # Does not work”，要排除 _posts 里的东西只有两条路——给文件或目录名加 前缀，或者用 skip_render。

三、第二个坑：ignore 是拿绝对路径匹配的

我第一次的写法是这样的，很符合直觉：

1
2
3

ignore:
  - '_posts/copilot/**'
  - '_posts/scaffolds/**'

这段代码在说明什么：什么也没说明，因为它一条都不生效。hexo generate 不报错、不警告，页面照旧生成。静默失效，这是配置类事故里最难查的一类。

真正的判定在 node_modules/hexo/lib/box/index.js：

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

// :244-246
function isIgnoreMatch(path, ignore) {
  return path && ignore && ignore.length && isMatch(path, ignore);
}

// :248-263
function readDirWalker(base, results, ignore, prefix) {
  if (isIgnoreMatch(base, ignore)) return Promise.resolve();   // :249 目录级剪枝
  return Promise.map(readdir(base).catch(err => {
    if (err && err.code === 'ENOENT') return [];
    throw err;
  }), async path => {
    const fullpath = join(base, path);                        // :255 绝对路径
    const stats = await stat(fullpath);
    const prefixdPath = `${prefix}${path}`;
    if (stats.isDirectory()) {
      return readDirWalker(fullpath, results, ignore, `${prefixdPath}/`);
    }
    if (!isIgnoreMatch(fullpath, ignore)) {                   // :261 传的是 fullpath
      results.push(prefixdPath);
    }
  });
}

这段代码在说明什么：base 是 Box 的绝对路径（这个仓库是 /Users/youqi/u7_blog/source/_posts），fullpath = join(base, path) 更是绝对路径。所以第 261 行交给 micromatch 的永远是 /Users/youqi/u7_blog/source/_posts/copilot/x.md 这种整串，而 _posts/copilot/** 被 makeRe 编译成整串锚定的正则，开头就对不上，永不命中。

模式本身非法时 toRegExp 会 log.warn；但模式语法合法却匹配不到任何东西时，Hexo 一声不吭。这就是“配置写了、等于没写”的机制。

正确的写法必须用 **/ 前缀去吃掉那段绝对路径：

1
2
3
4
5

# _config.yml
# Hexo 6.x 的 ignore 是用「绝对路径」去匹配的，所以模式要带 **/ 前缀
ignore:
  - '**/_posts/copilot'
  - '**/_posts/scaffolds'

这段代码在说明什么：**/ 负责匹配掉 /Users/youqi/u7_blog/source/ 这段前缀，剩下的部分才和真实路径对齐。官方文档的 ignore 示例本身也是这个形态（**/foo、**/themes/*/foo），只是它没解释“为什么非要 **/”，我自己也没往那个方向想。

四、为什么 scaffolds 不带 /* 反而更狠

这里有个容易写反的方向问题：直觉上 **/_posts/scaffolds/* 比 **/_posts/scaffolds “更精确”，实际上前者弱得多。我在仓库里直接跑了 micromatch 验证（Hexo 6.3.0 依赖同一个库）：

1
2
3
4
5
6
7
8
9
10

const { isMatch } = require('micromatch');
const dir  = '/Users/youqi/u7_blog/source/_posts/scaffolds';
const file = dir + '/page.md';
const deep = '/Users/youqi/u7_blog/source/_posts/copilot/copilot-conversations/x.md';

isMatch(dir,  ['**/_posts/scaffolds']);    // true
isMatch(file, ['**/_posts/scaffolds']);    // false
isMatch(dir,  ['**/_posts/scaffolds/*']);  // false
isMatch(file, ['**/_posts/scaffolds/*']);  // true
isMatch(deep, ['**/_posts/copilot/*']);    // false   ← 深层文件挡不住

这段代码在说明什么：**/_posts/scaffolds 只匹配目录本身，一个文件都不匹配；**/_posts/scaffolds/* 只匹配直接子文件，目录本身不匹配。两者不是强弱关系，是打在完全不同的位置上。

差别之所以是质变，在于第 249 行那句 if (isIgnoreMatch(base, ignore)) return Promise.resolve();——一旦模式命中目录本身，整棵子树连 readdir 都不会发生。而只命中文件时，目录照样被进入、逐层递归，你必须为每一层深度各补一条模式。

我这次是运气好才暴露出来的：Copilot 的目录不止一层，copilot/copilot-conversations/.md 有 16 个，还有 copilot/skills/openartifacts-publish/SKILL.md 这种更深的。写 `**/_posts/copilot/` 能挡住第一层，深层照样漏，而且是那种“我明明配了 ignore 啊”的漏。

  flowchart TD  A[ignore 模式写在哪个层级] --> B[匹配到目录本身]  A --> C[只匹配到子文件]  B --> D[readDirWalker 第一行直接返回]  D --> E[整棵子树不再递归 深层文件全挡住]  C --> F[目录仍被进入 递归继续向下]  F --> G[必须为每一层深度各补一条模式]  G --> H[漏一层就漏一篇 且不报错]  E --> I[文章数从 79 回到 77]  

这张图想让你看见什么：同一个 ignore 选项，写在不同粒度上，走的是两条完全不同的代码路径——一条在进入目录前就返回，一条要在每个文件上反复判定。前者是 O(1) 剪枝，后者是 O(深度) 补丁。凡是“排除整个目录”的意图，就该让它命中目录本身。

五、修复与验证：从 79 到 77

改动只有 _config.yml 那两行（外加一份 .gitignore，下一节说），但验证要做全。我实际执行的是 hexo clean && hexo generate——不清缓存的话 db.json 里已有条目可能残留，这点我踩过：只跑 generate 时文章数没立刻回到预期。

对照文章必须一起验。只测 404 是有盲区的：如果把 ignore 写成 **/_posts，上面三个 URL 都会 404，看起来“修好了”，其实整站文章全没了。

事后再复核一次也有旁证：现在 db.json 里 Post 模型已经没有 pagelink、0.html、copilot 相关的任何 key，说明污染没有留在增量缓存里。

六、这里我不太同意“用 .gitignore 就够了”

出事后不止一个人跟我说：加 .gitignore 不就行了。我当时也这么想过，后来发现这个思路只对了一半。

.gitignore 和 hexo ignore 的边界完全不同：前者决定“哪些文件进仓库”，后者决定“哪些文件被 Hexo 扫描”。一个目录完全可以同时是“不该进仓库”和“会被 Hexo 扫描”的。我这仓库的实际情况正好把三种组合都占全了：

第三行是决定性的反例：scaffolds/page.md 是 hexo new page 要读的模板，把它塞进 .gitignore 等于把脚手架扔了；它必须被 git 跟踪，同时必须被 Hexo 忽略。所以 .gitignore 在这件事上不是“更彻底的方案”，它连这个问题的一半都覆盖不到。

我的判断：判定标准只有一条——除了 git 之外，还有谁会读这个目录。git 读完就没别人读，.gitignore 足够；Hexo 还要读一遍，就必须写 hexo ignore。真正的治本在更前面一层：非文章的东西，一开始就别放进 source/_posts。

七、三类东西永远不该放进 source/_posts

source/posts 在 Hexo 里不是一个“文件夹”，是一个输入队列：除 和 . 开头的路径段以外，一切都会被当文章。所以下面三类东西放进去，等于预约一次事故：

1. 模板与脚手架。scaffolds/、页面模板、任何带 {{title}}、{{date}} 占位符的文件。它们的正确位置是项目根的 scaffolds/，不是 source/_posts/scaffolds/。
2. 工具的本地数据目录。Obsidian Copilot 的对话归档、.obsidian/、.trash/、.nopost、各种插件缓存。这些目录归工具所有，它们的 front-matter 不是写给 Hexo 的，abbrlink 撞车是必然。
3. 别人系统的导出物。AI 会话记录、导出日志、抓取结果。它们的字段结构（sessionId、usage、epoch）根本不在 Hexo 的 schema 里，Hexo 只会用默认值把它们硬塞成一篇文章。

我踩过的坑：我曾经以为“文件名随便写、反正会被当成文章”是 Hexo 的宽容。它不是宽容，它是没有判断力——它没有能力区分“作者写的文章”和“恰好是 .md 的东西”，这个判断只能由目录结构来承担。

八、部署成功不等于线上生效

配置改完、generate 干净、本地 curl 200，我就以为结束了。结果刷新自定义域名，看到的还是旧页面。

第一次抓下来 92KB，页面里还有那段明文内容；隔一会儿再抓，123KB，变成新页面了。中间什么都没改。原因是自定义域名前面有一层 CDN，静态托管那边的文件已经更新，边缘节点还在吐旧副本。

  sequenceDiagram  participant L as 本地 clean 与 generate  participant R as git 仓库  participant H as 静态托管  participant C as 自定义域名 CDN  participant B as 我的浏览器  L->>R: 提交两条 ignore 与清理后的 public  R->>H: 触发构建并部署  H->>C: 回源取到新页面  C-->>B: 仍返回旧缓存 92KB  B->>C: 刷新后再次请求  C-->>B: 返回新页面 123KB  

这张图想让你看见什么：部署完成和线上生效之间隔着一次缓存失效，而且这次失效不会通知你。注意我是靠字节数变化（92KB 到 123KB）才确认拿到的是两份不同内容——状态码两次都是 200，只看 curl -I 看不出任何异常。

我的理解：验证“页面已消失”这件事，只看 HTTP 状态码不够，得同时看内容指纹（文件大小、或者一段特征字符串还在不在）。后来的做法是先 curl 拿正文 grep 那段特征文案，确认确实是新内容；拿不到再加查询串绕缓存，还是不行才去刷 CDN。

九、下次直接照做的清单

1. 把非文章目录挡在 source/_posts 之外：脚手架放项目根 scaffolds/，工具数据放到 source/ 之外的路径，这一步能消掉大部分事故。
2. ignore 一律用 `/前缀，并且匹配目录本身**：写‘/_posts/copilot’，不要写‘_posts/copilot/‘，也别画蛇添足加/*`。
3. 改完 ignore 必须 hexo clean 再 generate，并核对文章数的变化符不符合预期——数字不动就是没生效。
4. 验证要成对：被排除的 URL 验 404，同时挑一篇正常文章验 200，防止排除过头。
5. 线上验证看内容不看状态码：比对文件大小或 grep 特征字符串，避免把 CDN 旧缓存当成修复成功。
6. 同时需要 .gitignore 和 hexo ignore 时，想清楚是哪一个在起作用；scaffolds/ 这种必须入库又必须被忽略的目录，就是两者的分界线。

最后留一句自我提醒：这类配置坑的共同特征不是“配错了会报错”，而是“配错了什么都不发生”。对静默失败的东西，验证必须以数字变化为依据，而不是以“命令跑通了”为依据。

我今年被问得最多的问题，已经不再是”你怎么写提示词”，而是”你的 Agent 半夜挂了，第二天早上怎么把它恢复并解释清楚发生了什么”。

第二类问题是一个标准的后端问题：状态在哪、重试怎么幂等、日志怎么回放、权限怎么收口。所以先给结论：2026 年做 Agent 真正的壁垒不在 Prompt，而在 Harness。 Prompt 只是这个系统最上面那层接口，Harness 才是服务端。

一、先分层：Prompt 只是最薄的顶层

大部分团队卡住的地方，是把 Agent 当成一个”对话功能”接进系统，于是所有复杂度都堆在提示词里；而真正决定它能不能上生产的，是下面几层。

  flowchart LR  P[Prompt 层 指令与示例] --> C[Context 层 上下文与记忆装配]  C --> T[Tool 层 工具契约与参数校验]  T --> H[Harness 层 状态机 重试 沙箱 观测]  H --> R[Runtime 层 进程 配额 隔离]  R --> O[产物与轨迹日志]  O --> C  

这张图想让你看见什么：注意那条从”产物与轨迹日志”回到”上下文装配”的箭头。它表示一次执行的结果必须能被下一次上下文装配读到，否则你的 Agent 永远只有单轮智商。上面三层靠模型和写作能力，下面三层靠工程能力，而且下面三层决定了上面三层能不能稳定复现。

二、Harness 的六块，对应后端的六种老能力

我把 Harness 拆成六块。每一块我都写清”后端已有的能力可以直接平移什么”，因为这是我说”主场”的唯一依据。

上下文与记忆

上下文不是”越多越好”，而是”装配得越准越好”。这点和读模型拼装完全同构：同一个实体，列表页要 5 个字段，详情页要 40 个字段，你绝不会给列表页返回详情页的 DTO。Anthropic 在 2025-09-29 的《Effective context engineering for AI agents》里把上下文当成一种有限预算资源来管理，这个视角对后端来说几乎是无门槛的。

工具调用契约

这是我认为最被低估的一块。工具签名不是文档，是契约。参数必须可校验、错误必须可分类、返回必须可截断。模型上下文协议 MCP 在 2026-07-28 版规范 里明确用 JSON-RPC 2.0 承载消息，并区分 Host、Client、Server 三种角色——这就是一次典型的”把不确定的自然语言收敛成有边界的协议”。

状态机与重试

Agent 的一次任务不是一次调用，而是一条带分支的状态机：思考、选工具、执行、观察、再思考、收尾。后端做这件事有成熟范式，不需要发明新理论。

权限与沙箱

模型没有”意图可信”这回事。工具有多危险，就要有多重的沙箱。最小权限、白名单、超时、资源配额，这些在网关和容器层已经做完了，搬过来即可。

可观测性与回放

我踩过的坑在这里：我早期只记录最终的模型输出，结果线上一个工具偶发超时导致的任务失败，我复盘了三个小时——因为我不知道是第几次尝试、传了什么参数、错误码是什么。后来我把 trace 粒度下沉到”一次工具尝试”，并且把每次的入参、出参、错误分类、耗时全部落盘，问题五分钟就定位了。可回放不是锦上添花，它是 Harness 的第一性需求：没有回放，你连”这次改动是不是变好了”都无法判断。

成本控制

成本要按任务归因，不能只按天统计总量。一个 30 轮的重试循环，token 消耗可能是一次正常任务的 20 倍，而你在日报里看到的只是”今天用量涨了 15%”。

三、一次失败重试到底长什么样

上面说的是静态结构，真正让 Agent 从 demo 变成系统的，是失败路径。下面这张时序图是我认为每个 Agent harness 都必须能画出来的图。

  sequenceDiagram  participant U as 调用方  participant H as Harness  participant L as 模型  participant T as 工具服务  participant O as 观测与回放  U->>H: 提交任务与幂等键  H->>L: 装配上下文并请求下一步  L-->>H: 返回工具调用与参数  H->>H: 校验 schema 与权限白名单  H->>T: 携带幂等键执行  T-->>H: 返回超时  Note right of H: 只重试可重试错误 其余直接失败  H->>O: 记录一次尝试与错误分类  H->>T: 退避后重试 复用同一幂等键  T-->>H: 返回成功结果  H->>O: 落盘完整轨迹供回放  H-->>U: 返回结构化结果与轨迹引用  

这张图想让你看见什么：注意”复用同一幂等键”这一步。这是整个 harness 里最容易写错、也最能区分工程水平的地方——如果重试换了幂等键，下游就会执行两次，你的 Agent 会开始重复下单、重复发券、重复扣款。模型永远不该负责这件事，它只负责说”我要调这个工具”，剩下的语义由 harness 保证。

四、把”重试”写成有幂等键的状态机

光说抽象没用，下面是我在项目里用的一段骨架，语言是 Java，因为这套东西最终要落在服务端。

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
56
57
58
59
60
61
62
63
64

public final class ToolInvoker {

    public enum Outcome { OK, RETRYABLE, FATAL, EXHAUSTED }

    public record ToolCall(String name, String argsJson) {}
    public record ToolResult(String summary) {}

    public static class ToolException extends RuntimeException {
        public ToolException(String msg) { super(msg); }
    }
    public static class RetryableToolException extends ToolException {
        public RetryableToolException(String msg) { super(msg); }
    }
    public static class FatalToolException extends ToolException {
        public FatalToolException(String msg) { super(msg); }
    }

    public interface ToolClient {
        ToolResult execute(ToolCall call, String idempotencyKey, long timeoutMillis);
    }

    public interface TraceStore {
        void record(ToolCall call, int attempt, Outcome outcome, String detail);
    }

    private static final int MAX_ATTEMPTS = 3;

    private final ToolClient client;
    private final TraceStore trace;

    public ToolInvoker(ToolClient client, TraceStore trace) {
        this.client = client;
        this.trace = trace;
    }

    public ToolResult invoke(ToolCall call, String idempotencyKey) {
        RuntimeException last = null;
        for (int attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
            try {
                ToolResult result = client.execute(call, idempotencyKey, 30_000L);
                trace.record(call, attempt, Outcome.OK, result.summary());
                return result;
            } catch (FatalToolException e) {
                trace.record(call, attempt, Outcome.FATAL, e.getMessage());
                throw e;
            } catch (RetryableToolException e) {
                last = e;
                trace.record(call, attempt, Outcome.RETRYABLE, e.getMessage());
                backoff(attempt);
            }
        }
        trace.record(call, MAX_ATTEMPTS, Outcome.EXHAUSTED, String.valueOf(last));
        throw new ToolException("tool exhausted after " + MAX_ATTEMPTS + " attempts: " + call.name());
    }

    private void backoff(int attempt) {
        try {
            Thread.sleep(200L * (1L << (attempt - 1)));
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new ToolException("interrupted during backoff");
        }
    }
}

这段代码在说明什么：说明重试的核心不是循环，而是三件确定的事——错误被分成可重试和不可重试两类（fatal 立刻抛，不再浪费两次调用预算）、幂等键从调用方一路传到工具服务且全程不变（重试语义安全）、每一次尝试无论成败都写进 trace（可回放）。模型在这里完全没有出场机会，这正是我想强调的分工：模型负责决策，harness 负责语义安全。

五、我的判断：哪类团队现在做 Agent 是浪费

我的判断是：2026 年做 Agent 踩空最多的不是技术选型，而是前提不成立。下面两种团队，现在投入大概率是浪费。

第一种，数据边界不清的团队。 他们连”哪些数据可以出内网、哪些字段必须脱敏、哪些调用要审批”都答不出来，却已经在讨论多 agent 协作。这类团队做出来的东西，Demo 阶段惊艳，安全评审阶段直接死掉。边界不清的时候，任何 harness 都是给漏洞加速。

第二种，没有真实工具面的团队。 如果 Agent 能调用的”工具”，本质上只有搜索加总结，那它就不需要 harness，只需要一个更好的搜索框。Harness 的价值来自”真实副作用”：写库、发消息、下单、改配置。没有副作用，就没有幂等、没有权限、没有回滚，也就没有工程壁垒。

反过来，两类团队是刚需：一是已经有稳定内部平台和大量 API、正在被”人肉操作 SOP”拖住的团队；二是把 Agent 当成线上服务而不是功能点的团队，他们天然需要 SLA、trace、回放和预算。

六、这里我不太同意：模型跃迁会不会把 harness 吃掉

我不太同意”harness 只是过渡方案，模型一强就没了”这个流行说法，但我也不同意把它说成永久壁垒。我的理解是：模型变强会吃掉 harness 的”策略层”，但吃不掉”责任层”。

策略层指的是那些靠提示词技巧凑出来的自愈能力，比如让模型自己决定要不要重试、自己判断该不该相信工具返回。这部分确实会被吃掉，而且我认为应该被吃掉，因为它本来就不该由模型承担。

责任层吃不掉：幂等键写在哪、权限谁批、审计留存多久、出了问题由谁向业务方解释。这些是组织责任，不是推理能力。模型再强，也不会替你承担一次重复扣款的后果。

反例也要说清：如果某天模型能稳定输出带可验证契约的工具调用，并且平台层直接内建了重试与沙箱（这在 MCP 这类协议演进中是可见趋势），那么今天很多手写 harness 会退化成”配置”。所以”后端主场”这句话成立的条件是：你做的 harness 解决的是责任与可复现问题，而不是在替模型补智力。 如果只是后者，你的代码就是一层迟早要被删掉的胶水。

还有一个来自 Java 生态的现实提醒：JDK 27 于 2026-09-15 GA，它并不是 LTS——按 Oracle 官方路线图，LTS 只有 8、11、17、21、25，下一个是 2027 年 9 月的 Java 29。而 JDK 27 里的结构化并发还停在 JEP 533 第七次预览。这两件事放在一起说明：Agent harness 里最需要的”可取消、可超时、可收敛”的并发原语，在 JVM 上还没有定稿，你得自己包一层。这也是后端工程师的主场，但不是一个舒服的主场。

七、公开信号与待核项

可核实的公开信号，我按对本文论点的重要性排序：

• Oracle Java SE 支持路线图（更新于 2026-10-20）：LTS 为 8/11/17/21/25，下一个 LTS 是 2027 年 9 月的 Java 29。
• OpenJDK JDK 27 项目页：GA 日期 2026-09-15，特性包含 JEP 533 结构化并发第七次预览、JEP 534 紧凑对象头默认开启。
• MCP 规范 2026-07-28：基于 JSON-RPC 2.0，区分 Host/Client/Server；版本策略 明确版本号以”最后一次不兼容变更日期”命名。该修订取代上一版 2025-11-25。
• Anthropic《Building effective agents》（2024-12-19）：主张先用最简单的方案，workflow 与 agent 要区分，不要一上来就上自主循环。
• Anthropic《Effective context engineering for AI agents》（2025-09-29）：把上下文当作有限预算来管理。
• Spring AI 1.0 GA 发布（2025-05-20）：Java 生态有了正式版的 Agent 抽象，意味着后端不必从零拼装。

待核的两项，我不编：

1. “Agent 相关岗位占比”这类招聘数据——待核。 我没有可核查的一手来源，只看到二手转述，无法确认统计口径与样本，所以本文不引用任何招聘比例数字。
2. “模型跃迁能替代多少比例的手写 harness”——待核。 这需要同一批任务在新旧模型上的对照实验，我没有做过，公开资料也没有可对齐的基准，任何具体百分比我都不会写。

八、可执行清单

1. 先画你自己那条失败路径的时序图。如果画不出来，说明你的 Agent 还没有 harness，只有一个 while 循环。
2. 给每一个工具有副作用的调用加幂等键，并规定”重试不得换键”这一条硬规则。
3. 把错误分成 fatal 与 retryable 两类，fatal 立刻失败，别把重试当成”让模型再想想”。
4. 把 trace 粒度下沉到”一次工具尝试”，字段至少包含 attempt、入参摘要、错误分类、耗时。
5. 给每个任务设预算上限，超支降级而不是静默继续，并按任务归因统计成本。
6. 在动手前先回答三个问题：数据边界在哪、工具的真实副作用是什么、出问题谁负责。三个都答不上来，就先别做 Agent。

先给一个可能让你不舒服的结论：把向量检索塞进 Redis，2026 年真正的风险已经不是「性能够不够」，而是「你以为它解决了延迟问题，其实它主要解决的是运维拓扑问题」。延迟那一层，它当然有帮助，但帮助幅度远小于宣传口径；真正被改变的是你少维护一套系统、少一条同步链路、少一次「缓存与索引不一致」的排障。

这篇文章只做三件事：把 8.4 到底改了什么核清楚、把「什么情况下该塞、什么情况下是灾难」画出一条可执行的分界线、以及把我在真实项目里踩到的坑摆出来。

一、先把 8.4 到底改了什么核清楚

Redis 8.4 是 GA，不是 RC：v8.4.0，发布日期为 2025 年 11 月 18 日（官方 00-RELEASENOTES）。往前一版是 8.4-RC1（v8.3.240，2025 年 11 月 4 日），官方在 RC 的说明里明确写着「RC 是功能完整的预发布版，不适合生产使用」。所以如果你在某个公众号上看到 11 月就把 8.4-RC1 的数字当 GA 数字引用，那是不严谨的。

相对 8.2，和检索直接相关的变更只有这么几条，我按官方原文整理：

版本状态还有一层必须说清楚：本文写作时间是 2026 年 10 月，此时 Redis 已经有 8.6 GA（2026 年 2 月 10 日）、8.8 GA（2026 年 5 月 25 日）、8.10 GA（2026 年 7 月 29 日），最新补丁是 8.10.2（2026 年 9 月 17 日）。所以「8.4 之后」不是修辞手法，是事实。8.6 把向量集的 8bit 量化与二值距离计算做了 SIMD 向量化；8.8 给 FT.HYBRID 补上了 FT.PROFILE 支持，并新增「每分片少取候选」的 KNN 参数。这几条我只核到了 release notes 的条目，没有做性能复现，标为未复现，请不要引用成基准数据。

二、演化线：从「附挂模块」到「内核能力」

要理解边界为什么消失，得把 8.0 和 8.4 连起来看。

Redis 8.0（v8.0.0，2025 年 5 月）做的是归属上的合并：RediSearch、RedisJSON、RedisTimeSeries、RedisBloom 不再是独立模块，代码并入主仓库，许可改成 RSALv2 / SSPLv1 / AGPLv3 三选一，查询引擎第一次具备水平与垂直扩展能力。注意一个容易被忽略的细节：8.0 里 Vector set 是 beta，官方就是这么标的。

8.4 做的是能力上的合并：FT.HYBRID 把「一次查询里同时做关键词召回和向量召回，再融合打分」这件事搬进了服务端。这才是边界真正模糊的那一步——在此之前，混合检索的 RRF 融合是应用层的活，你得发两次 FT.SEARCH、拿两份结果、在自己代码里按位次算分、再截断。那不是架构问题，是一段谁都不愿意维护的胶水代码。

  stateDiagram-v2    [*] --> 纯缓存    纯缓存 --> 外挂模块 : 需要全文与向量检索    外挂模块 --> 内核一体 : Redis 8 合并模块    内核一体 --> 混合检索 : 8.4 提供 FT.HYBRID    混合检索 --> 检索引擎分家 : 内存成本或一致性越界    检索引擎分家 --> 纯缓存 : 检索迁出 只留缓存  

这张图想让你看见的是：这条演化线不是单向的，最后一条边是我加的，也是真实会发生的——当内存成本或者一致性要求越界时，团队会把检索迁回 Elasticsearch 或者 Postgres，Redis 退回纯缓存。我在两个团队里都见过这个回退，而且回退的成本比当初「顺手加一个索引」高得多，因为那时业务已经在依赖 Redis 的相关性排序了。

三、我的判断：分界线在哪里

我的判断是：把检索放进 Redis 是否成立，只由一条不等式决定——向量与索引常驻内存的规模，必须显著小于实例内存预算。我用的阈值是 30%，超过就该重新设计。

先算清楚量级，不要凭感觉。768 维 float32 单条向量是 768 × 4 = 3072 字节，约 3KB；这还没算哈希表头、文档正文、倒排索引和 HNSW 图结构。所以：

• 10 万条文档向量 ≈ 0.3GB 裸向量，加上文档与索引开销，实际按 0.6-1GB 估
• 100 万条 ≈ 3GB 裸向量，实际按 6-10GB 估
• 1000 万条 ≈ 30GB 裸向量，实际按 60GB 以上估

最后一行就是分界线。如果你的实例是 16GB 或 32GB，1000 万条 768 维全精度向量根本放不进去，唯一的出路是量化到 8bit（把每维 4 字节压到 1 字节，size 降到四分之一）或者二值量化，代价是召回率要重新调参。这里我不太同意「先上，不行再扩」的做法：向量索引的扩容和普通缓存的扩容不是一回事，主从全量同步、RDB 加载、索引重建这几步都是内存峰值场景，线上被打到 search-on-oom 的默认 RETURN 语义，你拿到的就是部分结果而不是错误——这种「安静的错误」比超时难查得多。

所以我把结论写成两条清单。

适合塞进 Redis 的情形

1. P99 要求 10ms 级别，且查询形态是「前置过滤 + top-k」，没有复杂排序
2. 向量条数在百万级以内，或愿意接受 8bit 量化并重新评估召回
3. embedding 模型只有 1-3 个，维度固定，不需要频繁重建索引
4. 数据可以接受最终一致：索引更新滞后几百毫秒对业务无感
5. 团队规模小，少一套 ES 集群带来的运维收益大于功能损失

不适合的情形

1. 需要多字段相关性调权、复杂聚合、跨索引 join：这是 Elasticsearch 的地盘，不是 Redis 的地盘
2. 写入强一致、要求「写完立刻能精确查到」：Redis 的索引更新和主从复制不提供这个保证
3. 数据量超过内存预算且必须全量在线：量化是缓兵之计，不是解决方案
4. 中文分词与词库治理需求重：查询引擎能分词，但自定义词典、同义词、停用词那一套工程化程度远不如 ES
5. 需要多租户隔离、细粒度权限、审计：这些是搜索平台的能力，不是缓存的能力

四、一段能跑起来的代码，比十页 PPT 有用

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

# 约定：$VEC 是序列化后的 768 维 float32 向量二进制，实际用客户端库或 redis-cli -x 传入
# 1. 建索引：文本字段 + 向量字段同文档，ON HASH
redis-cli FT.CREATE doc_idx ON HASH PREFIX 1 doc: SCHEMA \
  title TEXT WEIGHT 2.0 \
  tag TAG SEPARATOR , \
  emb VECTOR HNSW 6 TYPE FLOAT32 DIM 768 DISTANCE_METRIC COSINE

# 2. 纯向量召回：KNN 走 HNSW，必须 DIALECT 2
redis-cli FT.SEARCH doc_idx '*=>[KNN 10 @emb $vec AS score]' \
  PARAMS 2 vec "$VEC" SORTBY score DIALECT 2 RETURN 2 title score

# 3. 带前置过滤的召回：过滤写在查询里，不是拿回来再筛
redis-cli FT.SEARCH doc_idx '(@tag:{cache|redis})=>[KNN 10 @emb $vec AS score]' \
  PARAMS 2 vec "$VEC" SORTBY score DIALECT 2 LIMIT 0 10

# 4. 聚合：能算，但别指望它替代 OLAP
redis-cli FT.AGGREGATE doc_idx "*" LOAD 2 "@price" "@stock" \
  APPLY "@price*@stock" AS amount \
  GROUPBY 1 "@tag" REDUCE SUM 1 "@amount" AS total \
  SORTBY 2 "@total" DESC LIMIT 0 10 DIALECT 2

1
2
3
4
5

# redis.conf 里和这条边界直接相关的四项
io-threads 4
search-on-oom RETURN
search-default-scorer BM25STD
lookahead 16

这段代码在说明什么：第一段把「文档」和「向量」放在同一个 Hash 里，这才是「缓存与检索边界消失」的物理形态——一次写入、一份内存、一个 TTL，不需要再维护一条缓存到索引的同步链路。第二段和第三段的区别是关键：* 开头的纯 KNN 是全库召回再排序，而 (@tag:{...})=>[KNN ...] 是先过滤再召回，两者的召回质量和延迟差一个量级，很多人只写了第二种却以为自己在用第一种。第四段是边界提醒：FT.AGGREGATE 能做出 GROUPBY 和 APPLY，说明它「能算」，但它的执行模型是单机内存聚合，遇到高基数分组和多重 REDUCE 就会把内存打上去，别拿它替 OLAP。

那四行配置也各有代价：io-threads 调大提升吞吐但增加上下文切换，官方给的大于 30% 是在 4 核、10% SET / 90% GET 的缓存场景测的，检索场景别直接套用；search-on-oom RETURN 是默认值，它意味着宁可给部分结果也不报错，对检索场景我倾向于改成 FAIL，让错误显式暴露；search-default-scorer BM25STD 是 8.4 改的新默认值，升级后相关性排序会漂移；lookahead 默认 16，是命令解析预取深度。

五、写路径和读路径到底长什么样

  flowchart LR    subgraph WP[写路径]        A[业务写入] --> B[文档键 与 向量字段]        B --> C[索引增量更新]        C --> D[全文倒排]        C --> E[向量 HNSW 图]    end    subgraph RP[读路径]        F[查询请求] --> G[关键词召回]        F --> H[向量 KNN 召回]        G --> I[融合打分 RRF 或 LINEAR]        H --> I        I --> J[前置过滤 排序 分页]        J --> K[结果回写热点缓存]    end    D -.-> G    E -.-> H    K -.-> B    M[内存预算] -.-> D    M -.-> E  

这张图想让你看见什么：写路径只有一次写内存，读路径却分成两条召回再融合，而下面那个「内存预算」节点同时约束倒排和 HNSW 两份结构——你要付的是两份索引的内存，不是一份。很多容量评估漏掉的正是这里：算向量算得很仔细，忘了倒排索引在高基数字段上的膨胀，最后 OOM 的是文本索引而不是向量。

六、Redis 8.4 / Elasticsearch / pgvector 四个维度对比

先声明：下面不是同机 benchmark，是量级判断加成本结构判断。任何让你「一个数字定生死」的对比表都不可信。

我的理解是：这张表里真正稀缺的不是延迟，是「一致性模型」这一列没人写。Redis 给你的是最终一致加部分结果语义，ES 给你的是近实时（默认 1 秒刷新）加可调一致性，pgvector 给你的是事务级强一致。选型时先问「写入后多久必须精确可见」，这一问通常直接淘汰掉两个选项，比对比延迟有用得多。

顺带把两家的能力事实也核一下，避免用老印象选型：Elastic Stack 9.0 起，float 的 dense_vector 字段一律按 int8_hnsw 索引，bbq_disk 这类二值量化可以把大向量集的内存压下来，官方给的磁盘开销是 int8 约 25%、int4 约 12.5%、bbq 约 3.1%；pgvector 从 0.8.0（2024 年 10 月 30 日）起支持 iterative index scans，并改进了「带过滤条件时的代价估算与索引选择」——这一条恰好就是 Redis 里「前置过滤」问题的 Postgres 版答案。

七、我踩过的坑，和一处我不太同意的地方

我踩过的坑是 FT.HYBRID 的已知限制。官方在 8.4 的 release notes 里列得很直白：FT.HYBRID 的指标不出现在 FT.INFO 和 INFO 里；EXPLAINSCORE、SHARD_K_RATIO、YIELD_DISTANCE_AS、WITHCURSOR 在 FT.HYBRID 上不可用；COMBINE 之后用 FILTER 做后置过滤不可用；默认响应只给 key_id 和 score。这几条合起来意味着两件事：第一，你没法用 profile 定位一个慢的混合查询，只能靠二分法砍子句；第二，过滤必须前置到 SEARCH 和 VSIM 子句里，如果你按「先融合、再过滤」的直觉写，它会直接报不支持——而在 8.8 之前连 profile 都不给你。我第一次接这个命令时以为是语法写错，改了半天才在 release notes 的 known limitations 里找到答案。教训很朴素：新命令先读 known limitations，再读语法。

这里我不太同意「一个 Redis 顶掉 ES 加向量库」这类说法。它成立的前提是把检索需求压缩成「前置过滤加 top-k」，而这个压缩在真实业务里经常失败。反例很具体：商品搜索要按销量、好评、库存、上下架做多因子加权，还要支持类目聚合和价格区间统计，这类查询在 Redis 里要么写不出来，要么写出来是十几行 FT.AGGREGATE 的意大利面，改一次需求调一次分。更隐蔽的反例是内存——ES 允许你只把热数据放进内存、冷数据留在段文件里，Redis 不允许，你必须为全量数据付内存钱，而内存的单价是磁盘的几十倍。所以「边界消失」正确的说法是：边界从系统之间搬到了你的容量预算和一致性要求里，它没有消失，只是换了个地方收钱。

八、可以马上做的事

1. 先在 release notes 里核对你要用的版本状态和 known limitations，特别是 FT.HYBRID 那一串不支持项
2. 用「向量条数 × 维度 × 4 字节」粗算裸向量内存，再乘 2 当作含索引的估算值，和实例内存比一比，超过 30% 就准备量化方案
3. 把所有检索查询改成「前置过滤 + KNN」的写法，别用「全库 KNN 再筛」，两者召回率不是一个量级
4. 生产环境把 search-on-oom 从默认的 RETURN 改成 FAIL，让 OOM 显式暴露而不是返回部分结果
5. 升级到 8.4 之后，因为默认打分器变成 BM25STD，要做一次线上相关性 A/B，别默认「排序没变」
6. 给混合检索留一条退路：把「关键词召回」和「向量召回」的接口抽象出来，将来迁到 ES 或 pgvector 时只换实现

参考来源

• Redis Open Source 8.4 release notes（8.4 GA 与 8.4-RC1 日期、变更、known limitations）：https://github.com/redis/redis/blob/8.4.0/00-RELEASENOTES
• Redis Open Source 8.0 release notes（模块合并、三许可、Vector set beta）：https://github.com/redis/redis/blob/8.0.0/00-RELEASENOTES
• Redis 8.6 / 8.8 / 8.10 release notes（后续版本日期与 FT.HYBRID 增强）：https://github.com/redis/redis/releases
• FT.HYBRID 命令参数结构（SEARCH / VSIM / COMBINE RRF 与 LINEAR）：https://redis.io/docs/latest/commands/ft.hybrid/
• Elasticsearch dense_vector 与量化（9.0 起 float 按 int8_hnsw 索引、bbq 磁盘开销）：https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/dense-vector
• pgvector 0.8.0 changelog（iterative index scans、过滤时代价估算）：https://api.pgxn.org/src/vector/vector-0.8.0/CHANGELOG.md

先说一个可能让不少人意外的结论：你在 PG 19 宣传里看到的异步 IO，主干代码在 PostgreSQL 18 就已经落地了。PG 18 的 release notes 原话是「An asynchronous I/O (AIO) subsystem that can improve performance of sequential scans, bitmap heap scans, vacuums, and other operations」。PG 19 干的不是”从无到有”，而是把”谁来执行这些异步请求”做成自适应（新增 io_min_workers、io_max_workers、io_worker_idle_timeout、io_worker_launch_interval），再让 streaming reads 铺到更多路径上（hash 索引批量删除、GIN vacuum、bloom、pgstattuple）。

所以如果你的升级决策表上写着”等 PG 19 解锁 NVMe”，这张表的前提就已经错了：你该评估的是 PG 18 的能力边界，PG 19 只是在边界内把调度做得更细。

一、先把版本状态钉死：截至现在它还不是 GA

这一节必须写准，因为网上已经有一堆”PG 19 重磅发布”的文章在用 beta 的截图讲生产收益。

官方 RC 1 公告里有一段很关键的说明：11 月 12 日的例行更新会带大量修复，release team 决定把这些修复也并进 PG 19，因此 RC 2 会和 11 月更新同日发布，GA 计划到 11 月 19 日。另外 postgresql.org 的 roadmap 页面上仍写着 planned for October 2026，和新闻页的 11-19 口径不一致——看日期以最新新闻页为准，roadmap 页更新滞后。

结论：本文讨论的所有行为，均以 PG 19 RC 1 的文档与 release notes 为准，不是 GA 行为。生产上要上，等 GA 之后再看一个小版本更稳妥。

二、同步 IO 在 NVMe 上究竟浪费了什么

不是”延迟高”，恰恰相反，是延迟太低而无法被叠加。

用 Little’s Law 算一下就很清楚：并发请求数 = 吞吐 × 单请求延迟。假设一次 8kB 页读取的设备侧延迟约 100µs（企业级 NVMe 随机读的典型量级），那么单线程一次一个地读：

这是算术推演不是实测，但量级关系是对的：同步模型下，一块能跑几十万 IOPS、几 GB/s 顺序读的设备，被一个队列深度钉死在 1% 的利用率上。设备没吃饱，后端进程却在睡眠。

再看 PostgreSQL 的进程模型。一个连接一个 backend 进程，读页的路径是 ReadBuffer → smgrread → pread，读不到就睡，等 IO 完成再被唤醒。这个模型简单、可预测、可观测，是 PG 几十年来的优势，但它的代价就是：一次只能有一个在飞行中的请求。PG 17 及以前所谓的”异步”，其实只是 posix_fadvise WILLNEED 给内核提建议（effective_io_concurrency 控制的预读距离），真正读页时仍然是同步等待。

Linux 侧的答案是 io_uring：一对共享内存环形队列（提交队列 + 完成队列），一次系统调用批量提交多个请求，可以配 SQPOLL 内核线程轮询、可以注册固定缓冲区，从而真正表达”深度 N 的并发”。PG 19 的 io_method = io_uring 就是走它，但需要 —with-liburing 编译。

那为什么默认值不是它，而是 worker？我的理解是取舍而不是能力问题：worker 模式复用了 PG 已有的进程与共享内存体系，可观测、可移植（Windows 也能跑），出了问题是一群能 ps 出来的进程；io_uring 则对内核版本、构建依赖、容器 seccomp 策略都更挑剔。默认 worker 是”先让所有人能跑”的选择，不是”io_uring 更快所以默认它”。

三、三个层级的参数必须一起调，否则等于没开

很多人只改一个 effective_io_concurrency 就期待起飞，这是最典型的无效操作。下面这段配置和检查 SQL 是我现在给任何 PG 18/19 实例做基线时都会跑的。

1
2
3
4
5
6
7
8
9

# postgresql.conf —— 异步 IO 相关，注意 io_method 需要重启
io_method = worker                  # worker | io_uring | sync，只能启动时设置
io_min_workers = 4                  # 仅 worker 模式生效，默认 2
io_max_workers = 16                 # 仅 worker 模式生效，默认 8
io_worker_idle_timeout = 60s        # 默认 1min
io_worker_launch_interval = 100ms   # 默认 100ms
effective_io_concurrency = 32       # 1..1000，0 表示禁用异步请求，默认 16
maintenance_io_concurrency = 16     # 维护类操作的并发度
io_combine_limit = 128kB            # 请求合并上限，默认 128kB

1
2
3
4
5
6
7
8
9
10
11

-- 1. 核对自己实例上的真实取值
SELECT name, setting, unit, context
FROM pg_settings
WHERE name IN ('io_method', 'io_min_workers', 'io_max_workers',
               'io_worker_idle_timeout', 'io_worker_launch_interval',
               'effective_io_concurrency', 'maintenance_io_concurrency',
               'io_combine_limit', 'io_max_concurrency')
ORDER BY name;

-- 2. 看当前在飞行中的 I/O 句柄（PG 18 起提供）
SELECT * FROM pg_aios LIMIT 20;

1
2
3

-- 3. 用 IO 选项看预取队列与请求规模，IO 必须与 ANALYZE 同用
EXPLAIN (ANALYZE, BUFFERS, IO)
SELECT count(*), sum(amount) FROM orders WHERE created_at >= '2026-01-01';

这段代码在说明什么：第一段是”容量”，io_min_workers 与 io_max_workers 决定 worker 池能有多少个执行者，effective_io_concurrency 决定每个会话愿意保持多少个在飞行中的请求，io_combine_limit 决定相邻请求能不能合并成大 IO（默认 128kB 正好 16 个 8kB 块）；第二段是”事实”，pg_aios 是 PG 18 起才有的视图，列出当前使用的异步 I/O 句柄，升级后监控脚本在低版本实例上查它会直接报错；第三段是”证据”，EXPLAIN (ANALYZE, IO) 会输出预取队列的平均与最大距离、队列容量，以及已发请求总数、平均请求大小、I/O 等待次数、平均并发请求数——判断”异步到底生效没有”，看的就是平均并发请求数是否大于 1，以及队列是否被打满。

四、同步阻塞与异步队列的模型对比

  flowchart LR    A[查询发起 顺序扫描] --> B[本次需要读 1000 个数据页]    B --> C[同步模型 一次只发一个]    C --> C1[后端起一个 pread 然后睡眠]    C1 --> C2[队列深度 1 设备排队能力被浪费]    C2 --> E[NVMe 带宽利用率低 延迟无法叠加]    B --> D[异步模型 一次提交 64 个请求]    D --> D1[共享内存 IO 队列]    D1 --> D2[worker 进程池 或 io_uring]    D2 --> D3[完成队列 批量唤醒后端]    D3 --> F[NVMe 带宽利用率高 等待被重叠]  

这张图想让你看见什么：两条路径的差别不在”读得快不快”，而在同一个后端进程在被唤醒之前，能有多少个请求在设备里排队。左路真正的成本是”睡眠—唤醒”的次数，右路的成本转移到了队列管理与 worker 调度上——这也解释了为什么异步不是免费的：请求数越多，worker 越忙，上下文切换与共享内存竞争就越明显。

五、一次顺序扫描在异步模式下长什么样

  sequenceDiagram    autonumber    participant C as 客户端    participant B as 后端进程    participant S as IO 子系统    participant W as IO worker    participant D as NVMe 设备    C->>B: 发送 SELECT 全表扫描    B->>S: 提交首批预取请求 多个数据页    S->>W: 按队列分发    W->>D: 并发下发读请求    D-->>W: 第一批完成    W-->>S: 写入完成队列    S-->>B: 唤醒后端 交付数据页    B->>B: 过滤行 组装元组    B->>S: 补齐水位 继续提交    Note over B,W: 关键点 后端等待期间设备仍有请求在飞    B-->>C: 返回结果集  

这张图想让你看见什么：执行器的循环结构没有变（还是取行、过滤、返回），变的是”取下一批页”这个动作从阻塞变成了”提交 + 稍后收割”。所以真正的收益点落在”有大量连续页要读、且这些页不在 shared_buffers 里”的场景，一旦命中缓存，这张图的下半部分根本不会发生。

六、应用层能看到什么：受益与几乎无感的清单

七、我的判断：什么情况下这次升级才成立

我的判断是，PG 18/19 的异步 IO 值得升级的条件可以压成三条硬门槛，缺一条就先别升：

1. 瓶颈确实在 IO 等待上。看 pg_stat_io 与 pg_stat_database 里 blk_read_time 的占比，或者用 EXPLAIN (ANALYZE, IO) 看 I/O 等待次数与平均并发数。如果 CPU 常年 90%、IO 等待不到 10%，升级之后你只会觉得”重启了一次”。
2. 数据量大于 shared_buffers，且有稳定的扫描型负载。库能全塞进内存的实例，异步 IO 没有任何发挥空间。
3. 存储的并发能力大于你当前的并发度。NVMe 收益最大；SATA SSD 队列深度有限，收益打折；网络块存储要看带宽是否已经封顶。

这里我不太同意”没有 NVMe 就没必要升级”这个说法。异步 IO 的收益来自”把等待重叠起来”，而延迟越高的存储，单请求等待越长、可重叠的收益反而越大——远端块存储、云盘上确实能看到改善。但反过来也不成立：当带宽先撞墙时，加大队列深度只会把 p99 拖长，因为请求开始在设备侧排队，而不是在 CPU 侧。

反例也要说清楚，异步 IO 从来不是银弹：

• CPU 瓶颈。顺序扫描的每行开销（tuple deform、表达式求值）是纯 CPU。PG 19 虽然优化了行变形，但如果扫描节点的 CPU 时间是 IO 等待的 5 倍，IO 再快也没用。
• 行锁与事务。热点行更新，瓶颈在锁等待与 WAL 刷盘，异步 IO 完全不参与。
• 连接数放大。effective_io_concurrency 是每会话的乘数。1000 个活跃会话各配 32，理论上就是 3.2 万个在飞行中的请求，全部砸在同一块设备上，结果不是更快而是更抖。这是我见过最常见的反向优化。
• 单页点查。没有可重叠对象，队列深度永远是 1。

八、我踩过的坑

我踩过的坑里，最浪费时间的一个是：io_method 改了 ALTER SYSTEM SET 之后执行 pg_reload_conf 然后盯着 EXPLAIN 的输出怀疑人生。它在文档里写得很清楚——只能在服务器启动时设置，也就是必须重启 postmaster，reload 不生效。同理 io_max_workers 这类参数属于配置级，不是会话级，改完不重启的系统永远停在默认的 worker 池上。

第二个坑是”以为开了 io_uring 就更快”。io_uring 需要 —with-liburing 构建，发行版二进制包不一定带这个能力，容器里还可能被 seccomp 拦掉。顺序应该是：先 SHOW io_method 确认自己到底跑在哪种模式，再看平均并发数，别拿内核版本猜。

第三个坑是监控。pg_aios 是 PG 18 起才有的视图，一套采集脚本同时跑在 14/16/18/19 上时，查询会直接报错；这类新视图必须按版本分流，或者用 to_regclass 做探测。

九、如果你下周就要做决定，按这个顺序来

1. 先用 EXPLAIN (ANALYZE, BUFFERS, IO) 在一条最具代表性的慢查询上取基线，记录平均并发请求数、I/O 等待次数、队列容量三个数。
2. 确认存储类型：NVMe 才谈”吃满”，SATA SSD 与网络盘先确认带宽是否已封顶，别用队列深度掩盖带宽瓶颈。
3. 在测试实例上只改三件事：io_method（先留 worker）、io_max_workers、effective_io_concurrency，其余保持默认，做 A/B 对比。
4. 按会话数算一次并发预算：活跃会话数乘 effective_io_concurrency 不要超过设备能舒服承受的队列深度，超了就要压会话数或压并发度。
5. 生产升级时间点放在 PG 19 GA（计划 2026-11-19）之后，再留一个例行更新周期观察 pg_stat_io 与 p99。
6. 把监控里的 pg_aios 与 EXPLAIN 的 IO 采集按版本分流，别让新视图把老实例的采集打挂。

异步 IO 这件事，PG 18 已经把地基打完，PG 19 在做的是让地基上的调度更聪明。真正决定你能不能吃满 NVMe 的，还是”你的瓶颈是不是 IO 等待”这一个问题——这个问题答错了，版本号升到 20 也没用。

先说一个反常识的结论：Elasticsearch 9.5 里最像”向量库”的那部分改动，其实不是向量字段，而是一个索引模式。真正在变的也不是”ES 能不能做向量检索”——那件事 8.x 就做完了——而是 ES 愿不愿意为不同负载放弃同一套存储假设。9.5 的答案是：不愿意，所以它把假设拆成了多个可选的索引模式。

这意味着你的架构评审问题要换一个提法。以前的问题是”ES 的 kNN 够不够快”，现在的问题是”我到底需不需要第二个系统”。

一、先把事实对齐：哪些是 GA，哪些只是预览

这一节的每一条我都对过官方页面，因为把预览特性写成 GA 是这类文章最常见的错。9.5 于 2026 年 8 月 4 日发布 GA 公告，但发布内容里混着三种成熟度，必须分开看。

也就是说，”ES 变成列式数据库”这件事，官方自己写的是 technical preview（技术预览），不是 GA。我的判断是这一条必须写进方案 PPT 的风险栏：预览意味着可以试、不能承诺 SLA，也意味着映射层的语义还可能变——文档里 ignore_above 的行为就已经标成了”Planned”。

还有一个我核不实的地方，如实写”待核”：官方文档提到”9.6 及之后创建的索引默认开启 auto-calibration 并使用 iso_sizing profile”，说明 9.6 已经在推进；但我在 elastic.co 上没有检索到 9.6 的 GA 公告页，所以本文所有结论只绑定 9.5，9.6 的具体行为标为待核，不做推测。

二、先给一张图：9.5 把存储选择推到了索引层

  flowchart LR    W[写入请求] --> IM{选择索引模式}    IM -->|standard| S1[倒排索引加 doc values]    IM -->|columnar| S2[仅 doc values 单一存储]    IM -->|vectordb_document| S3[向量文件优先预加载]    S1 --> Q[查询层]    S2 --> Q    S3 --> Q    Q --> A1[全文检索]    Q --> A2[聚合与排序]    Q --> A3[kNN 近似检索]    A1 --> M[结果归并与重排]    A2 --> M    A3 --> M  

这张图想让你看见什么：9.5 之前，ES 的存储结构基本是固定的，你能调的只有字段级参数；9.5 之后，第一个分叉发生在”建索引的那一刻”，而且三条分支共用同一个查询层、同一套 API。这不是加了一个功能，是把一个原本隐式的架构决策显式化了。代价是它不可改：mode 只能在创建索引时设定，建完就不能改，选错的唯一出路是重建索引再 reindex。

三、列式存储省掉的不是索引，是”第二份数据”

很多人把列存理解成”把行存换成列存”，这个理解在 ES 这里会跑偏。按官方那篇讲列存原理的文章，Lucene 的 doc values 从 1.0.0 起就是列式结构，聚合和排序一直靠它。所以列式存储对 ES 不是新东西，它是从”辅助结构”升级成了”唯一结构”。

standard 模式下同一份字段值其实存了两遍：一遍进倒排索引（字符串）或 BKD 树（数值）用于过滤，一遍进 doc values 用于聚合排序。columnar 模式把前者默认关掉（index 映射属性默认为 false，文本字段例外，因为全文检索离不开分析链），只留 doc values，再补两个东西来救查询性能：doc values 的批量读取，和 doc values skipper。

skipper 是轻量跳表，存 min/max 之类的元信息，让范围查询能整段跳过文档。它的效果完全取决于数据在磁盘上的物理顺序，所以列式模式下 index sorting 不是可选项而是设计的一部分。logsdb_columnar 默认给 host.name 升序加 @timestamp 降序，逻辑很朴素：同一台机器的日志挨着放，run-length 和 delta 编码才有效。

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

curl -X PUT "localhost:9200/orders-columnar" -H 'Content-Type: application/json' -d'
{
  "settings": {
    "mode": "columnar",
    "sort.field": ["tenant.id", "@timestamp"],
    "sort.order": ["asc", "desc"]
  },
  "mappings": {
    "properties": {
      "@timestamp": { "type": "date" },
      "tenant.id":  { "type": "keyword" },
      "amount":     { "type": "double" },
      "status":     { "type": "keyword" },
      "message":    { "type": "text" }
    }
  }
}'

这段代码在说明什么：mode 与 sort.field 必须一起给。只写 mode 而不设计排序键，skipper 就退化成”还是得扫”，你会得到一个存储变小、但范围查询变慢的索引，然后误判”列存不行”。message 是 text，在列式模式下仍然默认建倒排索引——这正是 ES 相对纯列式数据库的取舍：它不愿意为了省空间牺牲全文检索，只在 logsdb_columnar 里把倒排索引压缩到只剩 message 一个字段。

四、收益边界：什么数据形态下反而不划算

这里我不太同意 Elastic 那篇公告里”zero changes to APIs, dashboards, or integrations”的说法。API 形状确实没变，但语义变了，而且是那种会在半夜炸出来的变。

第一，映射被强制拍平。列式模式下 object 和 passthrough 字段会被自动拉平，nested 只有受限支持，且 nested 之间不能套。原来靠 nested 表达一对多关系的订单明细、多标签文档，迁移过来要么改模型要么放弃。

第二，_source 不再是原文。列式模式只支持合成源和列式源，store: true、synthetic_source_keep 全部被拒，传统 stored source 不支持。官方写得很直白：columnar 用更小的存储换更低的还原保真度。如果你的下游有”取出原始 JSON 原样丢给别家系统”的逻辑，这一条就是硬阻断。

第三，doc_values: false 会直接报映射错误。以前为了省空间把不需要聚合的字段关掉 doc values，这个习惯在列式模式下会让建索引失败，多字段除外。

第四，高基数不是问题，但”既要全文又要过滤”的低基数标签字段是问题。低基数字符串用字典加 ordinal 编码，压缩率极好；高基数字符串走块压缩也能接受。真正难受的是那种”必须按它做精确过滤命中率极高、同时又必须参与全文相关性打分”的字段——列式模式默认不建倒排，过滤只能靠 skipper 跳段，效率和原来不在一个量级。

我踩过的坑就在这：拿一个”搜索加多维筛选”的电商索引试 columnar，存储降得很漂亮，但带筛选条件的关键词查询 P99 直接翻了几倍。结论是列存适合”分析型加日志型”负载，不适合”筛选密集型的交互式搜索”。前者是少数列、海量行、扫描为主；后者是宽表、随机命中、过滤条件五花八门。这个区分比”数据量大不大”有用得多。

五、VectorDB 索引模式：从”字段类型”变成”索引级承诺”

vectordb_document 是这个版本里我最看重的改动，因为它是 GA 的，而且它改变的是索引的默认假设而不是某个字段的参数。它做的事一句话能说完：把原本要你自己调的向量相关默认值全部预置好。

这张表说明一件事：向量检索的性能上限其实不在查询时，而在”段长什么样”。预加载和合并策略决定了查询时能不能不碰盘，所以把它们塞进索引模式，比让你在 6 个字段参数上试错要合理。

  sequenceDiagram    participant App as 应用服务    participant CO as 协调节点    participant SH as 数据分片    participant DS as doc values 与向量文件    App->>CO: kNN 请求 携带 topk 与过滤条件    CO->>SH: 分发到各分片 携带段级参数    SH->>DS: 用 skipper 元信息跳过不匹配文档区间    DS-->>SH: 返回候选文档区间    SH->>DS: 读取 bfloat16 向量做近似距离计算    DS-->>SH: 返回距离结果    SH->>SH: 段级 oversample 后重打分    SH-->>CO: 返回分片内 topk    CO->>CO: 归并排序并截断    CO-->>App: 返回最终 topk  

这张图想让你看见什么：kNN 在 ES 里从来不是”一步查完”，它是”过滤先缩范围、近似距离出候选、段内 oversample 重打分、协调节点归并”四段。列式模式和向量模式的默认值，作用点分别在第一段和第三段——skipper 决定前面能跳过多少文档，oversample 决定后面要重算多少。这也解释了为什么单独调一个 m 或 ef_search 常常没效果：它们不控制这两个真正决定成本的段。

关于 HNSW 调参经验能不能迁移，我的判断是”一半能迁移，一半会骗你”。能迁移的是形状：m 变大查得准内存也涨、int8 到 int4 到 bbq 是逐级更省更糙、m 在更新映射时只能不变或变大。会骗你的是绝对值：默认元素类型变成 bfloat16，量化位宽和 oversample 由自动校准按段决定，你在 8.x 上调出来的那套”m=32 加 int8 加 oversample 2.0”参数组合，换到 9.5 的 vectordb_document 上基准完全不同，照抄只会得到一个既没调优也没默认的组合。

还有一个坑必须说清：auto_calibrate 在 9.5 里只接受布尔值、默认关闭、且字段建好之后不能改。也就是说想用它，必须在建映射时就写上，否则只能 reindex。另外文档里有个容易漏掉的细节：合并后少于 10000 个向量的段不参与校准，回落到 3.0 倍默认 oversample。所以小索引上开了校准基本没感知，这不是它没生效，是样本不够。

六、我的判断：分界线现在该画在哪

  flowchart TD    subgraph T1[方案一 ES 一体化]    A[业务数据] --> B[单一集群]    B --> C[文本字段 走倒排索引]    B --> D[向量字段 dense_vector]    C --> E[同一请求内混合过滤加 kNN]    D --> E    E --> F[一次结果返回]    end    subgraph T2[方案二 ES 加专用向量库]    G[业务数据] --> H[Elasticsearch]    G --> I[向量库 Milvus 或 Qdrant]    I --> J[返回向量 ID 与距离]    J --> K[回查 ES 拿正文]    H --> K    K --> L[应用层归并两套分数]    end  

这张图想让你看见什么：两套方案的差别不在查询快慢，而在”一致性边界”和”分数可比性”。方案一里过滤和向量在同一个请求内完成，返回的是经过同一套打分的排名；方案二里你拿到的是两组不可比的分数，怎么融合是应用层的活，而且双写就意味着两边永远可能不一致。

我的判断是分界线可以按三个条件画，命中任意一个就该上专用向量库：

• 向量规模到了千万级以上，且要求过滤与向量在同一次判定内完成。ES 的 kNN 需要先过滤再算距离，过滤后的候选集很小、召回会掉；专用向量库普遍支持带过滤的图遍历，这类负载差距是结构性的。
• 需要多向量召回或稀疏加稠密混合的复杂管道。这不是 ES 不行，是编排逻辑写在应用层更清楚。
• 检索的更新频率远高于正文更新，或者向量由独立流水线版本化管理。

反过来，以下几类我明确不建议再引一个专用库：

• 向量规模在百万到几百万、QPS 在几十这个量级、过滤条件基本是固定的几个业务维度。这种规模 ES 一体化完全够，多引一个系统换来的是双写一致性、双份监控和一份新的值班说明书。
• 正文和向量必须同源同版本。一次 reindex 就能把两边拉齐，这在 RAG 里价值很高。
• 已经在用 ES 做日志或搜索，团队没有额外的运维带宽。这里代价不是钱，是人的注意力。

至于 pgvector：它确实不需要新系统，省掉了运维一个新集群的成本，HNSW 和 IVFFlat 两种索引也够用。但它的定位是”把向量放进既有 Postgres”，如果你已经有成熟的 Postgres 和事务需求，它是最省心的选择；如果检索同时要吃全文相关性和复杂聚合，你还是得回到 ES。这不是谁替代谁，是三个不同起点的最短路径不同。

七、可以马上做的事

1. 先用一个只读副本验证 columnar：选一个日志或指标索引，重建时同时给 mode 和 sort.field，比对存储占用、范围聚合延迟和你最常用的那种”带筛选的关键词查询”延迟。三个数字一起看，别只看存储。
2. 把 doc_values: false、store: true、nested、synthetic_source_keep 这几个关键字在现有模板里 grep 一遍，命中就是在给列存迁移埋雷。
3. 新建向量索引直接上 vectordb_document，并在映射里显式写 auto_calibrate: true——9.5 默认关且建后不可改，漏了就得 reindex。同时确认 _source 里没有向量（该模式强制排除），别让下游的取原文逻辑踩空。
4. 老索引先别急着全部切换。mode 不可逆，把”哪些索引是实验性的”写进命名规范里，比事后靠记忆区分安全。
5. 做一次选型复盘：把”要不要保留专用向量库”从技术偏好问题改成三个可测条件——向量规模、过滤与向量的耦合度、双写不一致的容忍度。前两个能量化，第三个问业务方。
6. 盯着 9.6。文档已经写了 9.6 起自动校准默认开启并用 iso_sizing 档位，但那部分标注仍是计划态，等 GA 公告出来再改方案。

八、最后压一句

9.5 真正在做的事，是把”搜索栈”和”向量库”这两个原本靠外部拼装的系统，用同一个索引模式机制塞进一个内核里。它没打算在所有维度赢过 Milvus 或 Qdrant，它打算赢的是”你不需要为了一件本来能顺手做完的事，再养一个系统”。判断自己属于哪一边，比判断哪个引擎 benchmark 更高更重要。

2025 年那份规范的回答是：不能。2026-07-28 这一版的回答是：所以我改。

这篇文章只做三件事：把 2026-07-28 这一版相对 2025-11-25 的真实改动核清楚；解释”无状态核心”到底把哪些东西搬了家；再给出我的判断——什么团队现在就该跟进，什么场景继续用旧版反而更省。

一、先说清楚这一版改了什么

我不打算凭印象写。判断依据是官方 changelog 与它引用的 SEP 原文。这一版的主线其实只有三条，其余都是配套。

• SEP-2575 Make MCP Stateless：删除 initialize / notifications/initialized 握手，把协议版本与能力协商改成”每个请求自带”。SEP 状态 Final，创建于 2025-06-18。
• SEP-2567 Sessionless MCP via Explicit State Handles：删除会话概念与 Mcp-Session-Id 头，跨调用状态改为服务端自签的显式句柄，作为普通工具参数由模型传递。创建于 2026-03-11，与 SEP-2575 互为补集。
• SEP-2322 Multi Round-Trip Requests：从”服务端反向发起 sampling/createMessage、roots/list、elicitation/create“改成”结果里携带问题、客户端重试原请求”。所有结果新增必填 resultType。

其余配套改动，我认为同样值得记住，因为它们直接决定了迁移成本：

还有一条容易被忽略但影响长期的：这一版同时确立了特性生命周期与弃用策略，弃用窗口不短于 12 个月，并把 Roots、Sampling、Logging 正式标记为废弃（SEP-2577、SEP-2596）。也就是说，这三个你熟悉的特性不是不能用，而是”新实现不该再加支持”。

二、无状态化意味着什么：四个落点搬家

“无状态”这三个字很抽象，落到代码上其实只有四个地方换了位置。

连接：从”先握手再干活”变成”每次请求自带上下文”。没有 initialize，也就没有”连接建立中”这个状态机。

会话 ID：以前 Mcp-Session-Id 是隐式的状态容器，购物车、浏览器实例、数据库事务都挂在它上面。SEP-2567 说得很直白：会话在生态里从未收敛出统一语义——有人按工具调用划分，有人按应用启动划分，几乎没人真的去恢复它，所以列表端点无法跨会话缓存。新做法是 create_basket() 返回 basket_id，后续 add_item(basket_id, ...) 自己带。

能力协商：以前一次握手定终身，现在每个请求的 params._meta 里带 io.modelcontextprotocol/protocolVersion、clientCapabilities，客户端宜带 clientInfo，服务端宜在结果 _meta 里回 serverInfo。版本不匹配返回 UnsupportedProtocolVersionError（错误码 -32022）。另外新增 server/discover，服务端必须实现，用来声明自己支持的版本、能力与身份——它是”提前选版本”和”stdio 上探测旧服务端”的双重入口。

流式传输：这是改动最狠的一块。HTTP GET 端点没了，resources/subscribe 也没了，取而代之的是 subscriptions/listen：一条长 POST 响应流，客户端显式声明订阅类型（toolsListChanged、promptsListChanged、resourcesListChanged、resourceSubscriptions），服务端确认后给每条通知打上 subscriptionId。而 notifications/progress、notifications/message 这类请求内通知，仍然只走它所属请求的那条响应流。

  flowchart LR    C[客户端 Agent] --> G[网关 鉴权 限流 路由]    G --> S1[MCP Server 副本 A]    G --> S2[MCP Server 副本 B]    G --> S3[MCP Server 副本 C]    S1 --> D[外部状态存储 Redis 或 DB]    S2 --> D    S3 --> D    S1 --> T[链路追踪 采集]    S2 --> T    S3 --> T    G --> L[统一访问日志]  

这张图想让你看见的是：网关和数据面之间多了一道”任意副本都能接住”的假设。旧模型里，客户端与副本 A 绑死，网关必须做会话粘滞；新模型里，请求只要自带版本、能力和业务句柄，副本是谁都无所谓，状态被推到外部存储，链路追踪也从”一条长连接里混着 N 个请求”变成”一次请求一条 trace”。

三、为什么向 HTTP 靠拢：四件在长连接里做不好的事

我不认为这是设计者偏爱 HTTP。更准确地说，是企业基础设施里的四件事，在有状态长连接上都很难做。

网关。网关的世界观是”无状态请求进、无状态响应出”，它靠路径、方法、头做路由和限流。会话模型下，你只能上会话粘滞或一致性哈希，副本负载不均、扩缩容时连接被打断，全是运维事故。SEP-2243 要求 POST 必带 Mcp-Method 与 Mcp-Name，本质是把”这次调用是什么”从 JSON body 提升到 HTTP 头——网关不用解析 body 就能按工具名限流、审计、熔断。

鉴权。会话 ID 不是身份凭证，它只是”我之前来过”。企业里要做的是每个请求校验 OAuth token、按 scope 授权、按租户隔离，并在中间件里统一拒绝。无状态后 MCP 才真正像一支普通 API 那样接入现有鉴权体系，这一版还顺手把动态客户端注册往 Client ID Metadata Documents 方向推。

水平扩容。状态在进程内存里，就意味副本不可随意杀；状态挪到 Redis 或数据库，副本才是”一次性”的。这一点对 Serverless 和弹性伸缩几乎是硬门槛。

可观测性。以前一条长连接上跑着几十个请求，日志要靠会话 ID 拼，采样器也分不清一次工具调用从哪到哪。现在 _meta 里带 traceparent、tracestate、baggage，一次调用天然就是一条 trace，慢查询能直接定位到具体工具。

  sequenceDiagram    autonumber    participant C as 客户端    participant S as 服务端    Note over C,S: 旧模型 有状态会话    C->>S: initialize 握手    S-->>C: 下发 Mcp-Session-Id 与能力    C->>S: tools/call 携带会话头    S-->>C: 结果依赖实例内存中的会话    Note over C,S: 新模型 无状态核心    C->>S: POST tools/call 带 _meta 版本与能力    S-->>C: result 带 serverInfo 与 ttlMs    C->>S: 再次调用 显式携带 basket_id    S-->>C: 任意副本均可处理  

这张时序图想让你看见的是：旧模型里”能力协商”是一次性投资，付一次、用很久；新模型里它变成了”每次调用都要付的税”。省掉的是会话状态与粘滞路由，多出来的是每请求的元数据、可能的 server/discover 往返，以及客户端自己承担的幂等与重试。

四、一段真实报文，比十页文档清楚

下面这段取自官方 Streamable HTTP 传输文档的请求示例，我原样保留（只删了无关注释）：

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

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_weather

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "Seattle, WA"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

这段报文在说明什么：同一个 /mcp 端点，同时服务 2025-11-25 和 2026-07-28 两代客户端，区分靠的不是连接状态，而是请求里的 MCP-Protocol-Version 头和 _meta 里的版本字段。三条原本属于”会话”的信息——协议版本、客户端身份、客户端能力——现在全部落在这一个请求体里。而 Mcp-Method、Mcp-Name 让网关在不读 body 的情况下就知道”这次要调用 get_weather”，可以直接按工具维度做配额。注意 clientCapabilities 是空对象也不影响调用，这正是无状态化的收益：缺什么能力就在这次请求里说清楚，服务端当场拒绝（MissingRequiredClientCapability，错误码 -32021），而不是等到某个后续调用才炸。

五、我的判断：谁该跟进，谁可以继续等

我的判断是：判断标准不是”你是不是 AI 团队”，而是”你的 MCP Server 有没有第二个副本、有没有第三个调用方（尤其是浏览器或第三方）”。

我的理解是，这一版真正卖的是一句话：协议不替你保管状态。它把”状态”从协议层赶到了应用层，同时把应用层的自由度也还给了你——你可以用 Redis、可以用数据库事务、也可以干脆什么都不存。代价是，那些原本靠会话”白嫖”的东西（列表结果、订阅生命周期、断点续传）现在都要你自己显式建模。

六、我踩过的坑，和我不太同意的地方

我踩过的坑：最容易犯的错是把 handle 当成”新名字的 session”。句柄在协议里没有生命周期语义——它只是服务端签发的字符串，什么时候过期、谁负责清理、能不能跨租户复用，全是你自己的事。如果照旧用一个全局 dict 存句柄，内存泄漏会原封不动地回来，只是换了个字段名。更隐蔽的问题是：句柄要作为工具参数进模型上下文，basket_id 这类短 ID 无所谓，但如果你把一坨 base64 编码的会话快照塞进去，token 成本和提示注入面都会上升。这一点协议没有给答案，属于工具设计者的取舍。

这里我不太同意：取消 SSE Last-Event-ID 与消息重投递，把”流断了怎么办”完全推给应用层。规范的说法很干脆——响应流断了，这次请求就丢了，客户端必须用新的 request id 重新发起。对只读查询这没问题；但对一个跑了十分钟的写入型工具，这是真实风险：断流意味着你可能既不知道它成没成功，又要再发一次。所以我的结论是，写操作工具必须自带幂等键，这不该是可选项。

另一处我保留意见的是 subscriptions/listen 的落地形态。它把推送收敛成”一条长 POST 响应流”，语义上比 GET 流清晰得多，但它终究还是一条长连接，仍然要过企业网关的空闲超时。很多网关默认 60 秒无数据就断，而列表变更通知可能几分钟才来一条。这条在规范层面无法解决，只能靠部署侧调参或加心跳——这也是我认为本版最难落地的一点。

我的判断（关于迁移节奏）：不要一次性切。先让服务端同时支持两代（规范里叫 dual-era），用日志统计”到底有多少调用真的读写了会话状态”，通常这个比例远低于你的直觉。把真正依赖会话的那几个工具改造成句柄式，剩下的请求天然就是无状态的，迁移面会突然变小。

七、今天就能动手的五件事

1. 在 MCP Server 入口加一列日志：method + _meta 里的协议版本 + 是否读写了进程内状态，先量化”会话依赖度”。
2. 把服务里所有会话作用域的字典列出来（购物车、事务、浏览器实例、临时文件），逐个改造成 create_xxx 返回句柄 + 显式过期策略。
3. 网关侧先把 MCP-Protocol-Version、Mcp-Method、Mcp-Name 做成透传 + 按工具名限流，这一步不依赖协议升级就能做。
4. 给写操作工具加 idempotency_key，因为”断流后重发”在无状态模型里是常态而不是异常。
5. 对照官方 changelog 逐条确认你的 SDK 是否支持 dual-era；在下结论前先看 SDK 自己的 release notes，不要只看博客。

八、待核清单

写技术文章最怕把”我记得”当”我知道”，以下三条我明确没核实完，先标出来：

• 各官方 SDK 的具体落地版本：我只核了规范文本与 SEP 状态，没有逐个核对 TypeScript、Python、Java、C#、Go SDK 的 release notes，因此”某个 SDK 从哪个版本开始支持 2026-07-28”待核。
• 这一版是否有独立的发布公告与确切发布日期：我核到的是以日期命名的 revision 2026-07-28 及其 changelog 与 schema 路径，未核到独立公告文，故不写”某月某日发布”。
• 主流云厂商托管 MCP 网关对 subscriptions/listen 的支持情况：未核，任何”已经支持”的说法都需要落到具体产品文档。

事实来源：modelcontextprotocol.io 的 2026-07-28 changelog、versioning 页、Streamable HTTP 传输页，以及 SEP-2575、SEP-2567 原文。

先说一个可能让你不太舒服的结论：Spring Boot 4 并没有给你的项目装上一个”编译期 NPE 检查器”。

真实的链路是这样的——Spring 把自家框架和整个 portfolio 的 API 契约，用 JSpecify 注解写进了 class 文件；然后，如果你（或者是你的调用方）在构建里挂了 NullAway，或者你写的是 Kotlin，这些契约才会在编译期变成错误。少了最后一环，mvn compile 依然一声不吭，该在运行时抛 NPE 的还是抛。

这个区别很关键：它决定了你要不要为这件事改构建、改代码、改团队习惯，也决定了你读到”Spring Boot 4 支持编译期空安全”这类宣传语时，该信几分。

一、JSpecify 不是 JSR-305 的续集，是一份能被机器执行的规范

JSpecify 1.0.0 在 2024 年 7 月 17 日发布到 Maven Central，正式定下四个注解：@Nullable、@NonNull、@NullMarked、@NullUnmarked，并承诺不再做不兼容变更。

四个里真正改变工作方式的是 @NullMarked。它的语义是”作用域内默认非空”：一个包、类或方法被标记后，里面所有类型使用处默认排除 null，例外必须显式写 @Nullable；@NullUnmarked 则把作用域退回 Java 原生语义，也就是”未知”。Spring 文档给出的典型用法是在 package-info.java 上打包级标记，一个项目几十上百个包，每个包一行，成本不高但收益是全局的。

和 Spring 的老做法对比，能看清它为什么值得换。Spring 从 5.0 起用 JSR-305 的元注解拼出 @NonNullApi / @NonNullFields，那套机制的问题很具体：JSR-305 本身早已休眠，注解的 @Target 指向声明而不是类型使用，依赖是”借来的”（split package 风险）。JSpecify 的注解是 @Target(ElementType.TYPE_USE) 且 @Retention(RUNTIME)——前者让它能标注 List<@Nullable String> 这一类位置，后者让它在 class 文件里留下来，才有了后半段”运行期读取”的可能。

表格最后一行是硬事实：Spring Framework 7 把 org.springframework.lang 下的 @Nullable、@NonNull、@NonNullApi、@NonNullFields 全部标为 deprecated，并建议迁移到 JSpecify。注意”建议”这个词——它没有在 7.0 里删掉，因为整个生态的迁移需要时间。

二、整条链路：注解 → 检查 → class 文件 → 运行期

先给一张全景图，后面每一节都是在这张图上放大某一个格子。

  flowchart LR    SRC[源码 注解声明] --> IDE[IDE 实时提示]    SRC --> JC[javac 编译]    JC --> EP[Error Prone 插件 NullAway]    EP -->|契约不满足| FAIL[构建失败]    EP -->|契约满足| CLS[class 文件 类型注解]    IDE --> CLS    JC --> KOT[Kotlin 调用方 编译期报错]    CLS --> RT[运行期 Nullness 查询]    RT --> DEC[参数解析 与 契约判断]  

这张图想让你看见的是”分叉”：同一份注解，往上走进 IDE 得到波浪线，往左走进 javac 得到构建错误，往下走进 class 文件在运行期被框架读回来。三条路彼此独立——你把 IDE 的检查关掉，不影响构建；你把 NullAway 从构建里摘掉，不影响运行期框架读注解。很多人以为这是一套联动机制，其实它是三个消费者共用一份输入。

三、到底是谁在编译期说话

这一环最容易含糊，我把它拆成五层分别看：

这里我不太同意”Spring Boot 4 能在编译期报空指针”这个流行说法（包括我自己的标题）。javac 不认识 @Nullable——它只把注解当成普通的类型注解写进 class 文件，不会因为你在 @NullMarked 包里有解引用就报错。真正报错的是挂在 javac 上的 Error Prone 插件，是编译流程里额外加的一道 lint 层。区别在哪？javac 的空性检查如果存在，会是全语言、不可绕过的基础语义；而 NullAway 是可选的、可配的、能一行配置关掉的静态分析。

这个区别不是文字游戏，它带来两个实际后果。第一，NullAway 默认只检查打了 @NullMarked 的包（NullAway:OnlyNullMarked=true，Spring 官方推荐的配置），因为全量检查老代码会产生海量告警，团队第一天就想关掉它。第二，”编译期报错”的覆盖范围取决于你的配置，而不是取决于你用了 Spring Boot 4——同一个仓库，A 组配了 NullAway，B 组没配，同样的 bug 在 A 组过不了构建，在 B 组上线后半夜报警。

边界我也说清楚：在 Kotlin 项目里，这句话是成立的。Kotlin 编译器直接读 JSpecify 注解并翻译成 Kotlin 的空类型，契约不满足就是编译错误，不需要任何插件。你现在能拿到的”最省事的编译期空安全”，其实来自 Kotlin 而不是 Spring。至于 Java 侧，Spring 官方措辞很克制：用支持 JSpecify 的 IDE 会得到警告，可选地接入 NullAway 在构建期强制。

四、Spring Framework 7 真正改变的是契约，不是你的编译结果

那 Spring 到底做了什么？它把”这个方法可能返回 null”从口头约定、Javadoc 注释、以及社区口耳相传的常识，变成了机器可读、可校验、可被工具链消费的声明。这是契约层面的变化，不是编译器的变化。

看一段前后对比。假设老代码里有一个查订单的服务，返回值可能为空，但从来没写清楚：

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

// 迁移前：契约只存在于作者脑子里
package demo.order;

import java.util.Optional;

public final class OrderService {

    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    // 调用方不知道这里可能返回 null，直接 order.title() 就炸
    public Order find(String id) {
        return repository.findById(id);
    }
}

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

// 迁移后：契约写在类型上，工具链能读
package demo.order;

import org.jspecify.annotations.Nullable;

public final class OrderService {

    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public @Nullable Order find(String id) {
        return repository.findById(id);
    }

    public String describe(String id) {
        Order order = find(id);
        return order == null ? "unknown" : order.title();
    }
}

配套的包级声明，一行文件解决整个包：

1
2
3
4

@NullMarked
package demo.order;

import org.jspecify.annotations.NullMarked;

这段代码在说明什么？三点。第一，@Nullable 是写在类型前面的（public @Nullable Order find），不是写在方法声明上——这是 TYPE_USE 注解的硬性语法，写错位置在 JSpecify 语义下是无效的。第二，迁移后 describe 里那个 order == null 判断不是可选的风格问题，而是 NullAway 认可的空值收敛：不写这个判断，构建期就会报错。第三，package-info.java 里的 @NullMarked 让这个包内”未标注 = 非空”，所以 OrderRepository 的返回值一旦被声明为 @Nullable，一路传到 describe 都会被追踪。

顺带说一个真实的坑：Assert.notNull() 这类断言方法不会自动让分析器”学会”收敛。Spring 给 Assert.notNull 加了 @Contract("null, _ → fail")，而 NullAway 需要你显式配置 NullAway:CustomContractAnnotations=org.springframework.lang.Contract 才认这个注解。不配，你会得到一堆”明明前面断言过了还报”的告警，然后开始怀疑工具。

五、几个坑，我踩过的

我踩过的坑集中在三处，都和「注解写了就完事」的直觉相反。

第一个坑：override 不继承注解。JSpecify 注解不会被继承，你在父类或接口上写了 @Nullable，子类实现必须自己再抄一遍，否则子类的实现按”非空”解释。如果父类来自外部依赖、根本没标，你会看到一堆 @SuppressWarnings("NullAway") // Overridden method does not define nullability。这类抑制注释会越积越多，是迁移期最大的隐性债务。

第二个坑：数组语法反直觉。在 @NullMarked 代码里，@Nullable Object[] 表示元素可空、数组本身非空；Object @Nullable [] 表示元素非空、数组可空；两个都写才是都空。我第一次迁移时写反过一次，编译期没报错——因为语义恰好自洽，只是和我的意图不同。这种”静默的错误契约”比报错更危险。

第三个坑：泛型的空性检查还不完整。Spring 文档里明确写了：泛型类型和泛型方法上的空性还没被 NullAway 完全支持；NullAway:JSpecifyMode=true 这个开关虽然能检查数组、可变参数和泛型的完整 JSpecify 语义，但官方标注它仍在开发中，且要求 JDK 22 以上。所以如果你的代码重度依赖泛型容器，别指望第一天上全量模式。

六、运行期那一段：class 文件里的类型注解怎么被读回来

JSpecify 注解是 RUNTIME 保留 + TYPE_USE，所以它们会作为类型注解留在 class 文件里。这就是 Spring 7 新增的 org.springframework.core.Nullness 枚举能工作的前提：它提供 forField、forParameter、forMethodParameter、forMethodReturnType 四个查询入口，返回 NON_NULL、NULLABLE、UNSPECIFIED 三种结果。官方 Javadoc 写得很清楚：完整支持 JSpecify、Kotlin 空安全和 Java 基本类型，对任意包的 @Nullable 都做务实检查；而 JSR-305 和 org.springframework.lang 的 @NonNullApi / @NonNullFields / @NonNull 不被支持。

  sequenceDiagram    participant Dev as 开发者    participant Build as javac 与 NullAway    participant Class as class 文件    participant Frame as Spring 运行期    Dev->>Build: 提交代码 或执行 mvn compile    Build->>Build: 在 NullMarked 作用域内做数据流检查    alt 契约不满足        Build-->>Dev: 构建失败 报出空性错误    else 契约满足        Build->>Class: 写入类型注解 与 参数注解        Class->>Frame: 启动或解析时反射读取        Frame-->>Dev: 按契约决定参数是否必填    end  

我的理解是：这一格才是 Spring 选 JSpecify 而不是自研注解的真正原因——它要的是能被工具链反复消费的元数据，而不是一份好看的文档。

这张时序图想让你看见”字节码”这一格为什么不能省。注解如果没有 RUNTIME 保留，链路在编译结束就断了，框架只能靠”猜”或者靠额外的元数据文件；正因为注解留在了 class 文件里，运行期才有机会把契约当成一等数据来用。至于 Spring 内部具体在哪些参数解析器里调用了 Nullness，我没有逐个核对调用点，这一段属于机制层面的推断——机制是确定的，调用点分布待核。

七、我的判断：它解决什么，不解决什么

我的判断是：这套东西真正的价值不在”抓 NPE”，而在”把契约变成可传递的资产”，外加 Kotlin 互操作。你自己写的代码，NullAway 只能看到你写了注解的部分；而 Spring 7 把上游几万个方法签名的空性标清楚了，你的分析器第一次能跨库推理——jdbcTemplate.queryForObject 到底会不会返回 null，以前靠试，现在靠注解。这是它最实际的一次性收益。

不解决的部分同样明确，我把它们列成清单，方便你在评审时直接引用：

• 反射与依赖注入：@Autowired 字段注入、@Value、Bean 后处理器设置的字段，NullAway 看不到，Nullness 也只是把契约读出来，不会替你把值填进去。
• 框架生成的代理：AOP 代理、CGLIB 子类上的方法，空性注解是否跟着走，取决于代理生成方式，别默认它一定可靠。
• 反序列化与外部数据：JSON 里的 null、数据库列、HTTP 请求体，注解只是声明，校验还得靠 Bean Validation。
• 容器与集合语义：Map.get 返回 null 是 API 契约的一部分，JSpecify 只能让你显式标注，不能把它变成 Optional。
• 你同事的代码：这是一个社会问题，不是技术问题。

落地成本我也算过一笔账，诚实说：中小项目几百个类的量级，接入 NullAway 到”构建能过”大约需要一到两周的集中清理，之后每周零星修；大项目如果历史代码里大量 @Nullable 缺失，前期噪音会非常劝退，务必先用 OnlyNullMarked=true 缩小战场，一个包一个包推进。

八、今天就能动手的清单

1. 升级前先确认基线：Spring Framework 7.0 与 Spring Boot 4.0 分别于 2025 年 11 月 13 日和 11 月 20 日 GA，先在一个非核心模块上升级，别全量铺开。
2. 把 org.springframework.lang 的 @Nullable / @NonNull 全量替换成 org.jspecify.annotations 版本，只改 import 和注解位置（注意挪到类型前面）。
3. 给自己最核心的一两个包加 package-info.java + @NullMarked，不要一次全加。
4. 接 NullAway 时先只开 OnlyNullMarked=true 和 CustomContractAnnotations=org.springframework.lang.Contract，JSpecifyMode 留到第二阶段。
5. 在 CI 里把 NullAway 设为阻塞：只警告不阻塞的检查，三个月后一定退化成没人看的日志。
6. 给团队写一页规则：override 必须复制注解、数组空性三种写法、以及 @SuppressWarnings 必须带理由注释。

待核与来源

• 待核：Kotlin 编译器从哪个具体版本开始完整支持 JSpecify 注解。Spring 文档只说明”Kotlin 中 JSpecify 注解会被自动翻译为 Kotlin 的空安全”，未给出起始版本；我也没有找到确切的版本号出处，因此不在文中写死。
• 待核：Spring 内部具体哪些参数解析器调用了 Nullness API。Javadoc 只描述了 API 能力，没有列出调用点。
• 有意不写：NullAway、Error Prone 插件的具体依赖版本号。这些版本迭代很快，写死在文章里第二天就可能过期，请以官方发布为准。

核验来源：

• JSpecify 1.0.0 发布公告（2024-07-17，四个注解正式化）→ https://jspecify.dev/blog/release-1.0.0/
• Spring Framework 7.0 GA（2025-11-13，comprehensive null safety through JSpecify）→ https://spring.io/blog/2025/11/13/spring-framework-7-0-general-availability
• Spring Boot 4.0.0 GA（2025-11-20，portfolio-wide null safety improvements with JSpecify）→ https://spring.io/blog/2025/11/20/spring-boot-4-0-0-available-now
• Spring Framework 参考文档 Null-safety 章节（NullAway 构建期检查、@NullMarked 包级用法、数组与泛型语法、老注解废弃）→ https://docs.spring.io/spring-framework/reference/core/null-safety.html
• Nullness 枚举 Javadoc（7.0 引入，四个查询方法与三种返回值）→ https://docs.spring.io/spring-framework/docs/7.0.10/javadoc-api/org/springframework/core/Nullness.html
• NullAway 官方仓库（Error Prone 插件、构建期开销）→ https://github.com/uber/NullAway
• JSpecify 注解源码（TYPE_USE + RUNTIME 保留）→ https://github.com/jspecify/jspecify/blob/main/src/main/java/org/jspecify/annotations/Nullable.java

2026 年 9 月 15 日，JDK 27 达到 GA。随后中文技术圈出现了一批标题几乎一样的文章，核心都写着同一句话：JDK 27 是 LTS。

这句话是错的，而且错得很有代表性，它把“两年一次的大版本”和“LTS”混成了一个词。Oracle 的 Java SE 支持路线图原文只列了五个 LTS：8、11、17、21、25，并明确写了下一个计划中的 LTS 是 2027 年 9 月的 Java 29。所以 27 只是一个功能版本，一年后就会被 28 取代。

但纠正标题不是这篇的目的。真正值得问的是另一件事：如果因为“27 不是 LTS”就跳过它，你会漏掉什么？

我的答案是：27 是 29 的预演带。等到 29 LTS 落地时，后量子优先的 TLS、G1 成为全环境默认、紧凑对象头默认开启，这三件事会一次性同时生效，而它们分别改的是你的协议握手、垃圾回收行为和对象布局。27 让你提前一年半，在真实流量和真实堆里把它们验一遍。

一、先把事实钉住：27 到底改了什么

JDK 27 是 JSR 402 的参考实现，一共 9 个 JEP，其中 4 个是正式特性（Final），4 个仍是预览，1 个还在孵化。

看完这张表你会发现一个规律：27 没有一门新语言特性转正，它的重量全压在“默认值”上。四个正式特性里，有三个是把某个东西改成默认，而不是新增一个 API。默认值才是升级事故的高发区，因为没有人会去读你没写的那个开关。

  flowchart LR    R[JDK 27 GA 2026-09-15] --> P[协议层]    R --> T[运行时默认值]    R --> L[语言与 API]    P --> P1[JEP 527 TLS 1.3 后量子混合密钥交换]    P --> P2[JEP 538 加密对象 PEM 编码 第三预览]    T --> T1[JEP 523 G1 全环境默认]    T --> T2[JEP 534 紧凑对象头默认]    T --> T3[JEP 536 JFR 数据脱敏]    L --> L1[JEP 533 结构化并发 第七预览]    L --> L2[JEP 531 惰性常量 第三预览]    L --> L3[JEP 532 基本类型模式 第五预览]    L --> L4[JEP 537 Vector API 第十二孵化]  

这张图想让你看见的是：27 的变更不是“多了一个功能”，而是三条独立的传导路径。协议层改的是你和别人握手的方式，运行时默认值改的是你自己的性能曲线，语言与 API 则大多还没定稿。升级评估必须按这三条路径分开做，混在一起讨论就会出现“这个版本好像没什么大变化”的错觉。

二、后量子密码：ML-KEM 和 ML-DSA 不是 27 才有的

这是最容易被误读的一点。很多文章写“JDK 27 引入后量子密码”，准确的说法应该是：JDK 27 让后量子密码第一次默认生效，但算法本身在 JDK 24 就已经进来了。

JEP 527 定义了三套混合组：X25519MLKEM768、SecP256r1MLKEM768、SecP384r1MLKEM1024。默认只开第一套，而且把它排在了客户端首选列表的第一位，完整默认顺序是 X25519MLKEM768、x25519、secp256r1、secp384r1、secp521r1、x448，再加三个 ffdhe 组。

注意 JEP 527 的两个非目标：不做纯 ML-KEM 的密钥交换，也不做 TLS 1.3 以外的版本。这说明 JDK 的策略是“先保命，不激进”——混合方案只要有一个算法没被攻破就是安全的，而纯后量子方案还得等更多密码分析。

下面这段代码是我用来确认本机 JDK 到底发了哪些组、协商成了什么。

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

import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLParameters;
import javax.net.ssl.SSLSocket;
import java.util.Arrays;

public class TlsGroupProbe {
    public static void main(String[] args) throws Exception {
        SSLContext ctx = SSLContext.getDefault();
        try (SSLSocket socket = (SSLSocket) ctx.getSocketFactory()
                 .createSocket("example.com", 443)) {

            SSLParameters params = socket.getSSLParameters();
            System.out.println("default groups = "
                + Arrays.toString(params.getNamedGroups()));

            // 只允许混合后量子组与传统 x25519，便于观察协商结果
            params.setNamedGroups(new String[] {
                "X25519MLKEM768", "x25519"
            });
            socket.setSSLParameters(params);
            socket.startHandshake();

            System.out.println("protocol = " + socket.getSession().getProtocol());
            System.out.println("cipher   = " + socket.getSession().getCipherSuite());
        }
    }
}

这段代码在说明什么：第一，后量子能力在 JDK 27 里是“看不见的默认值”，你不改一行代码就会带上 X25519MLKEM768 的 key share，打出来的默认组列表就是证据；第二，setNamedGroups 是显式开关，当你要验证“对端到底支不支持 PQC”时，把组裁到只剩两个，握手失败就说明对端不认识这个组，这比读文档可靠；第三，也是我提醒自己的地方——如果生产代码里有人手工 setNamedGroups 或设置了 jdk.tls.namedGroups，那 JDK 27 的默认值对你完全无效，你升级完会发现“没变化”，其实是被自己的配置挡住了。

三、为什么到 2026 年才认真做：成本在证书和协议层

我的判断是：后量子迁移更像当年 TLS 1.2 升 1.3，而不是 JDK 8 升 11。业务代码几乎不用动，工作量全部堆在证书链、中间设备和客户端矩阵上。

依据就在 JEP 里。JEP 497 在交付时明确写了不做 TLS、不做 JAR 签名，因为标准还没到位；JEP 527 又明确只做 TLS 1.3 的混合组。也就是说，密钥交换这一层现在有了，但“用 ML-DSA 签名的证书”这条链还在补：JDK 27 里 PEM 编码仍然只是第三预览，证书与签名的文本流转还没有完全固化。

  sequenceDiagram    participant C as TLS 客户端 JDK 27    participant S as 服务端 支持混合组    participant M as 中间设备 TLS 终止    C->>S: ClientHello 携带 X25519MLKEM768 与 x25519 两个 key share    S->>C: ServerHello 选中 X25519MLKEM768    Note over C,S: 会话密钥同时依赖 ML-KEM-768 与 X25519    C->>M: 同样握手 但中间设备只认识 x25519    M->>C: 回落到 x25519 没有后量子保护    Note over C,M: 观测点 必须记录实际协商组 而不是记录客户端支持组  

这张图想让你看见的是“升级 ≠ 生效”。JDK 升级只改变了客户端愿意提供什么，真正决定防护强度的是链路上最弱的那一跳。TLS 终止设备、七层网关、老版本的反向代理，任何一处只认 x25519，握手就会安静地退回传统算法，日志里不会报警。

所以这里有一个反直觉的代价：升级之后你的 ClientHello 变大了。混合组要同时传 ML-KEM 的封装公钥和 X25519 的 key share，单个握手包增加的数据量足以在某些 MTU 敏感或者有分片限制的老链路上出问题。我见过的情况是握手偶发超时，抓包才看出是 ClientHello 被拆包。如果你的业务里还有自建的长连接网关、有些老旧硬件负载均衡，这一点必须先测，不要等灰度。

反过来说，这个观点也有不成立的时候：如果你的服务是纯内部 mTLS、CA 和客户端都在自己手里、链路上没有任何 TLS 终止设备，那 PQC 迁移的成本确实很低，甚至可以一次推完。判断标准不是“我们有没有加密流量”，而是“链路上有几个我控制不了的 TLS 端点”。

四、虚拟线程：pinning 修好了，瓶颈换了个地方

虚拟线程在 Java 21 由 JEP 444 转正，当时最著名的问题就是 synchronized 会钉住载体线程。这个问题在 JDK 24 由 JEP 491 解决：在 synchronized 方法和语句里阻塞的虚拟线程现在会释放载体线程。JEP 491 同时覆盖了另一种情形——虚拟线程进入 monitor 竞争或调用 Object.wait 时，以前也是钉住的。

我踩过的坑正好在这里。JDK 21 时代排查 pinning，大家的肌肉记忆是加 -Djdk.tracePinnedThreads=full 看堆栈。到了 JDK 24 以后，JEP 491 明确说这个系统属性不再需要了，诊断入口变成 JFR 的 jdk.VirtualThreadPinned 事件，而且事件本身被增强了，会带上“为什么钉住”和“载体线程是谁”。我第一次在 JDK 25 上排查一个卡顿，加了这个参数、什么都没打出来，还以为问题消失了，实际上是那个开关已经不管事了。教训很朴素：升级 JVM 时，把诊断参数当作 API 一起做兼容性检查。

那现在还会钉住吗？会。JEP 491 保留了事件用于其他 pinning 场景，最典型的是虚拟线程调用 native 代码（无论是 native 方法还是 Foreign Function & Memory 回调），native 代码再回调进 Java 执行阻塞操作或等 monitor。这类问题靠升级 JVM 解决不了，只能靠替换实现或者把 native 调用挪到平台线程池。

我的理解是：虚拟线程解决的是“线程数量上限”，不是“吞吐上限”。一旦你把线程成本降到接近零，瓶颈会立刻平移到下游那几个有固定上限的资源上——数据库连接池、HTTP 客户端连接池、限流信号量、CPU 核数。给一个 20 个连接的池配上 10 万个虚拟线程，排队的位置只是从线程池搬到了连接池，而超时语义变了，p99 往往更难看。

  stateDiagram-v2    [*] --> 新建    新建 --> 运行中 : 启动    运行中 --> 阻塞 : 发起阻塞式调用    阻塞 --> 已卸载 : 让出载体线程    已卸载 --> 运行中 : 数据就绪 重新挂载    运行中 --> 钉住 : 进入 native 或 FFM 回调    钉住 --> 运行中 : native 返回    运行中 --> [*] : 任务结束  

这张图想让你看见的是 pinning 的位置变了。以前“阻塞就钉住”，现在只有“进入 native 边界”才会钉住，而且它是一条更隐蔽的路径：JFR 里出现 jdk.VirtualThreadPinned 时，你该去看的是 native 调用栈，而不是去搜代码里的 synchronized 关键字。

五、Loom 之后：结构化并发为什么还在第七次预览

JDK 27 里结构化并发（JEP 533）是第七次预览。对比一下：虚拟线程 21 转正，Scoped Values 在 25 由 JEP 506 转正，而结构化并发还在预览。这个时间差很说明问题。

我的理解是：卡住的不是运行时能力，而是 API 形状和错误语义。StructuredTaskScope 要同时回答好几个没有标准答案的问题：作用域关闭时是取消还是等待、异常怎么聚合、超时归谁管、和现有的 ExecutorService、Spring 的事务上下文、MDC 怎么共存。这些问题的每一个答案都会反过来影响 API 长什么样，所以它反复预览是可以理解的。

这里我不太同意一种流行说法：“用了虚拟线程，代码自然就更结构化。”这两件事是分开的。虚拟线程给的是调度能力，结构化并发给的是生命周期约束。没有后者，你写的还是 executor.submit 加一堆 Future.get，只是这些 Future 跑在更便宜的线程上，错误处理和取消传播该丢还是丢。而且因为它在第七次预览，你在生产里用它，就要接受每半年跟着预览 API 改一次代码的代价。我的建议是：框架和中间件作者现在就该跟，业务代码先用 Java 21 就稳定存在的结构化替代方案（作用域内的 try-with-resources 加显式取消）把边界画出来，等它转正再换。

六、我的判断：现在该不该升

先给结论，再给条件。

结论：2026 年下半年的生产默认版本仍然应该是 25 LTS；27 适合作为“29 LTS 的预演环境”，在非核心链路和压测环境里先跑起来。理由是 29 会把 G1 默认、紧凑对象头默认、PQC 优先这三件事一起带进 LTS，那时你没有“只改一个变量”的机会，而 27 给了你这个机会。

这个判断在什么情况下不成立：如果你的发布节奏是年更甚至更慢，团队没有余力维护第二套 JDK，那 27 对你没有收益，老老实实等 29。预演带的价值建立在“你确实会去做验证”这个前提上，不做验证的预演只是提前引入风险。

升级前必须验证的东西：

关于紧凑对象头，我多说一句：它的收益是实打实的堆占用下降，但代价是“你过去的性能观测口径全部变了”。用 JOL 量出来的对象大小、基于字段偏移写的序列化、把对象头当 12 字节来算的容量规划，全都要重算。这类变化不会让测试失败，只会让你的监控图表悄悄变形——我认为这是 27 最容易被忽略的部分，比 PQC 更需要提前打招呼。

七、今天就能做的六件事

1. 装一个 JDK 27，先只做一件事：跑上面那段 TlsGroupProbe，确认默认组列表第一位是不是 X25519MLKEM768。
2. 在预发环境开一次 JFR，重点看 jdk.VirtualThreadPinned 事件还有没有，以及 reason 字段指向哪里。
3. 用 openssl s_client 带上混合组，对你们最关键的外部依赖做一次探测，记下哪些对端会回落。
4. 盘点证书与 TLS 终止点数量，产出一张“我控制不了几跳”的表，这决定 PQC 的排期。
5. 在 CI 里加一个 25 与 27 双 JDK 的矩阵构建，先不求通过，只求把失败清单攒出来。
6. 把团队里所有“诊断类”启动参数列一份清单，逐个标注在 27 上是否仍然生效。

最后回到标题。27 不是 LTS，这不影响它值得被认真对待；真正会伤人的不是版本号写错，而是把“默认值变更”当成“没有变更”。后量子密码、G1、紧凑对象头，这三件事的共同点就是：你什么都不做，它们也会生效。

多 Agent、工具调用、Loop、RAG、Human-in-the-loop……一页简历读完，概念很密，项目到底做了什么却不太好找。

下面只是我最近的一点个人观察，不代表所有候选人，也不代表所有面试官。话可能有点直，但我想说的核心很简单：简历上的每一个亮点，最好都能接得住一句“为什么”。

英文可以写，但名词本身不算亮点

举个最近碰到的例子：Human-in-the-loop。

我看到这个词的时候愣了一下，问了才知道，候选人说的是在 Agent 处理过程中加入人工审核。解释的时候，明明可以用中文讲得很清楚，写在简历上却只剩下一个看起来很高级的英文概念。

我当时的第一反应是：加了一个人工审核环节，这就能单独当成亮点了吗？

仔细说，人工审核当然可能有设计难度。哪些操作必须先经过人确认？审核不通过以后，任务怎么继续？等人审核的时候，已经执行到哪一步的状态放在哪里？这些都是可以展开讲的东西。

可如果简历只写“引入 Human-in-the-loop 机制”，我看不出你具体解决了什么问题，也看不出你的贡献在哪里。

假设做的是一个内容发布助手，一句“生成结果先交给运营审核，通过后才能发布”，就能让我很快理解流程。接下来再讲为什么需要这个环节、你怎么实现它，技术细节才有落点。这个例子只是说明表达方式，实际写简历时，还是要对应自己真正做过的工作。

对我来说，满页术语却看不出具体做了什么，会降低继续读下去的兴趣。尤其是追问以后发现，候选人其实能把事情解释清楚，就更觉得可惜：本来可以直接展示的能力，被自己藏进了一串英文里。

英文术语可以让交流更准确，但不能替你说明工作量、难度和价值。

我理解求职压力，但经历包装确实越来越离谱

另一个感受，是简历包装这件事越来越严重。

一些 UP 主、自媒体作者会在社交平台分享自己的简历和项目经历。有人拿来参考表达方式，有人却直接把内容搬过去，改个公司、换段时间，就成了自己的实习产出。再和 AI 对话几轮，把项目背景、技术难点和面试回答都补齐，一段经历就这么“长”出来了。

我的评价很直接：把别人的经历写成自己的，这么做不道德。

但我也能理解求职者为什么焦虑。在一个大家都忙着包装的环境里，老老实实写自己做过什么，可能连自己都会担心：这样的简历，能拿到面试吗？看到别人靠包装获得机会，更容易产生“想活下去就得顺应环境”的想法。

这种压力是真实的，不能只用几句漂亮话就把它带过去。

只是，整理真实经历、把自己的贡献表达清楚，和直接编出一段实习，区别仍然很大。前者值得认真做，后者即使帮你换来一次面试，也会把后面的每一次追问都变成风险。

AI 可以帮你梳理项目、检查表达、模拟追问。它也很容易把一段故事补得十分完整。问题在于，这份完整来自生成，你自己有没有做过其中的判断、踩过其中的坑，是另外一回事。

先想清楚，公司为什么要做这个 Agent

有些简历越问越让人疑惑：技术方案写得很满，业务背景却像是临时补上去的。

找几个开源项目，再找几家业务看起来相似的公司，把项目套进一个实习背景里。表面上，技术和公司都有了，但中间缺了最关键的一段思考：这家公司为什么需要这个 Agent？

开源项目本身很适合学习。你能跑起来、读懂关键代码、做出自己的修改，再把理解讲明白，完全可以写成个人项目。如果确实在实习中基于开源项目继续开发，就要讲清实际业务背景、自己做了哪些改动，以及这些改动解决了什么问题。

谁会用它？用户原来怎么完成这件事？原来的方式到底哪里不好？为什么值得花人力和模型调用成本去做？Agent 给出结果以后，谁来使用这个结果，下一步发生什么？

这些问题串起来，才是我理解的业务闭环。

比如，一个系统能够读材料、检索信息、生成回答，到这里可以说明流程跑通了。但谁需要这份回答，回答怎么进入实际工作，结果出错时谁处理，仍然需要继续想清楚。

个人项目暂时没有真实用户，也没关系。可以明确说自己验证了什么、还有哪些假设没有验证。为了让经历显得完整，硬补一套并不存在的使用情况和效果数据，反而会让本来能讲清楚的部分也变得可疑。

我更想听到的是：你对这个场景有什么理解，为什么选择这种做法，亲手完成了哪部分，又知道它有哪些局限。

业务讲不明白，多几个 Agent 也救不了

现在有些简历的写法，让我想起 25、26 届校招里那种给项目堆微服务的劲头。

一个很小的项目，先把服务拆开，再加上各种组件。面试官问一句：“这么小的项目，为什么要用微服务增加成本？”就开始不好回答了。

这类问题，我自己以前也有过糊弄过去的时候。现在再看，问题其实一直都在：选择一个方案，总得有个说得通的理由。

换到 Agent 项目里也一样。拆了好几个 Agent，接了一堆工具，又加上循环和检索，架构图画出来很热闹。但为什么要这么拆？一个 Agent 能不能做？哪些步骤用固定流程更合适？多一轮调用，换来了什么，又多付出了什么？

这些都值得在写简历之前想一遍。

某个技术很热门，可以成为你学习它的理由。放进具体项目以后，还需要解释它和实际问题的关系。否则，面试官只要顺着设计往下问几层，前面背得再熟，也容易卡住。

所以，我对准备 Agent 求职的同学，最实际的建议是：把简历逐句过一遍。

看到“设计了”，就问自己为什么这样设计，有没有考虑过别的做法；看到“实现了”，就把输入、处理过程、输出和异常情况讲一遍；看到“优化了”，就说清原来哪里有问题，改了什么，凭什么判断有效。如果写了数据，还要知道数据从哪里来、怎么统计。

可以找人做模拟面试，也可以让 AI 按简历不断追问。回答卡住以后，回到代码和项目事实里找答案，再把表达整理清楚。后续参加真实面试时，也把被问住的问题记下来，持续修正自己的理解。

准备充分，不只是为每个问题背一段答案。更重要的是，你知道简历里哪些内容是自己做的，哪些决定是自己想过的，哪些地方还没有弄明白。

应届生不一定有机会做很大的项目。一个范围不大、来龙去脉讲得清楚的项目，在我这里一样有说服力。最怕的就是简历把期待拉得很高，一问为什么，回答却接不上。

最后，送给这些现象一句三十字锐评：

术语堆得再高，也填不满业务的空洞；简历包装再厚，也扛不住一句为什么。

这里按天记录工作内容、遇到的问题和当天的一点想法，方便月底回看。

2026/09/15 今天做了啥？ ✨

今天主要是在把 5 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成美容美体题库导入链路排查与热修提交，确认问题是 CP 对新工作表展示名识别不足、后端又要求覆盖旧根场景；已保留未知 key、重复 key 和 sceneId 不匹配的拦截，并将后端与 CP 的最小改动推送到热修分支。
• 定位预发导入 500 的根因，确认热修代码已部署，但数据库缺少 scene_tree_head 等场景树迁移表；故障发生在首次查表阶段，尚未进入删旧题库或写新题库，原有 68 题未被覆盖。Excel 解析预览已通过，覆盖范围为 32 个场景、27 个叶子场景、150 题。
• 完成正式生题失败分型：任务 47 的容量拒绝、任务 48 的 CONTEXT_SCHEMA_INVALID 已分别收敛。后者落在 questions.claimRefs 的结构化结果校验，相关 Schema/提示词的最小基线测试 16 条通过；同时识别出通用修复提示混入正式链路规则的回归风险，暂未合入。
• 梳理 QA-SC 任务 51 的执行状态和并发来源，确认任务不是卡死，而是单 Pod、实际并发 1 下按机会项串行执行；最终已进入 pending_review，不能据此误判为全成功。进一步确认基准 QA 的配置值 4 并未作用于 QA-SC 项目运行 Pod，配置源需要按项目环境重新对齐。
• 完成多仓未提交改动审计与分支基线整理，确认 72 个改动属于不同主题，不能整包提交；合并三个独立仓的最新 master 时已处理冲突并完成后端全 Reactor 编译，保留各仓原有未提交改动的边界。

🧩 困难/需要帮助

• 预发确认覆盖导入前，仍需确认 V37、V38 场景树迁移已按顺序落库，并回读 scene_tree_head、scene_tree_revision 等表；目前只能确认解析校验通过，不能确认安全导入。
• QA-SC 并发配置需要在项目级 SCM/运行实例重新核对并经滚动重建生效；不宜直接把长 Agent SDK 会话并发调到 10。
• 正式生题的 claimRefs 修复需要把正式链路专属提示与通用 analysis 修复提示拆开，再进行最小提交和回归验证。

💭 感想

今天主要是在把题库导入和正式生题两个问题从“页面现象”往真实的代码、数据迁移和运行配置上收敛。预览通过、Pod Ready、任务待审核都只是阶段信号，真正可放行仍要把迁移、配置来源和最终业务回读逐项补齐。

2026/09/16 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成题库画像主链升级，新增 qb-core-202609-v2 并切换生题链路；正式题目支持 customer_persona，兼容旧三项空画像与新四项解析，只投影当前机会绑定的唯一画像，旧版 v1 保持不变。
• 完成画像链路定向验证，165 项测试全部通过；全量基线为 2559 通过、124 跳过，69 个失败均收敛到旧 /draft 断言、过期 direct-context 契约和日志捕获，未混入本次验收。
• 对齐画像发布依赖，确认 applied_persona_id 必须先落库，发布顺序固定为“DDL → AI v2（兼容旧任务）→ Knowledge 写四项”，避免新链路早于数据结构启用。
• 收口商家经营助手方案与 Buzzy 项目材料，明确“Supervisor → 专项 Agent → Domain Skills → Business CLI → 经营系统/联网信息源”分层，补齐业务流程、任务路由和职责边界，避免把工具层误写成 Agent 或虚构底层实现。
• 补全 CLI 场景化回归评测口径，固定“CLI 变更 → 飞书评测机器人 → 经营场景矩阵 → Dubbo 重复调用 → 结构化结论”链路；指标聚焦关键断言一致率、场景覆盖和跨场景兼容风险。
• 整理并锁定 Buzzy 主线简历材料，移除 KFC/点餐残留；主简历 15 条亮点均满足字数限制，成品已设为不可变保护。

🧩 困难/需要帮助

• 画像上线前仍需 DBA 确认并落地 applied_persona_id 列，才能按既定顺序启用新链路。
• AI 仓全量基线仍有 69 个既存失败，需要与本次画像变更分开治理，避免验收口径混淆。
• 微信工作群正文尚未形成可可靠引用的工作证据，本次不据此补充具体群消息。

💭 感想

今天主要是在把画像生题、发布依赖和经营助手材料都往真实代码链路与可验证口径上收敛。画像功能已经完成兼容与定向验证，后续关键是守住 DDL 前置和历史基线噪音的边界。

2026/09/17 今天做了啥？ ✨

今天主要是在把 7 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成“题目治理→历史资料”在 Knowledge 与 CP 的 QA-SC 交付，补齐商家/文件名分页、资料历史、分析批次、独立问题与生成题目三类明细，并冻结资料版本和历史统计；发布后接口验证通过，浏览器端到端验收待补。
• 完成客户画像同步故障修复与真实回归，补齐 backend 与 QA March 的缺失 Key；同时对齐正式生题按冻结画像逐一判定、每个适用画像产出一题，并将 appliedPersonaId 下沉到题目。
• 推进任务 53 的正式生题排查，9 个独立问题中 7 个成功生成 29 道待审核题；已收敛 2 个失败项，其中一项为 DIRECT_SESSION_TIMEOUT，约 600 秒后终止。
• 定位商家后台“操作过于频繁”根因，滑块验证已通过，实际由上游 uic-captcha 的短信限频返回错误码 135900005，排除 PC 前端、backend 与 knowledge 的业务限流。
• 修复本地正式生题的 INVALID_PARAM 启动边界，补齐运行模式与操作人身份配置后恢复请求发起；问题不在题目生成参数本身，而在本地身份上下文不完整。
• 完成题目驳回重生的基础事务与幂等回执能力，重复驳回返回原回执；专项 7 项、旧链路 51 项及 AI 原基线 83 项验证通过，完整快照、重生任务和前台交互仍需继续补齐。
• 完成话术范例库草稿，沉淀 9 个行业共 180 条题目，并明确行业→场景两层路由、每场景最多 5 题、缺题不跨行业凑数以及读取失败/重试/审计规则；当前尚未接入正式生题主链。

🧩 困难/需要帮助

• 任务 53 仍有 2 个独立问题失败，已证实一项为 DIRECT_SESSION_TIMEOUT；需要继续确认另一项根因，并收敛超时重试与补偿边界。
• 历史资料接口已完成发布验证，但本机浏览器端到端访问曾超时；需要在可达 QA 链路补齐前端完整验收。
• 话术范例库仍是本地草稿，需要继续明确生产接入范围、版本冻结与 Good/Bad Case 治理节奏。

💭 感想

今天主要是在把题库治理从页面状态收敛到真实历史证据、冻结版本和发布接口，同时把登录、生题与短信限制问题下钻到上游服务和运行身份边界。主链方向已经比较明确，但任务超时、QA 前端可达性和范例库生产接入还需要继续按可回放、可验证的边界推进。

2026/09/21 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成正式生题任务 62（run 3810）逐项失败分析，确认 10 条机会均未进入 pending_review：7 条约 600 秒触发 DIRECT_SESSION_TIMEOUT、2 条约 552 秒触发 SDK_TIMEOUT、1 条因 CONTEXT_INVALID 被验收拦截；问题不是单一汇总状态能解释的“全部失败”。
• 梳理正式生题容量链路，确认不同 Context 会直接并发启动长耗时执行会话，缺少全局与 Pod 级背压；大批量提交会把会话同时压入同一运行单元，后续应按持久化任务、全局准入和已验证速率出队，而不是继续放大并发。
• 对齐 QA-SC 路由与配置时序，确认任务 62 经内部兼容网关访问 doubao-seed-2-1-pro，不能简单归因为协议不兼容；配置更新不会动态刷新已启动服务，run 3812 与截图请求的路由、Trace 时序仍需逐条闭环。
• 梳理“上传资料—分析会话 A—确认独立问题—正式生题会话 B”边界：上传不启动执行会话，B 不复用 A 的原始记录，而是读取已持久化的分析和证据后重新冻结 Context，明确了两段链路的输入与可复现口径。
• 完成题库资料分析页交互修复：修正主按钮文字被样式缓存覆盖的问题，阻断勾选历史资料后自动跳转“结果查看”，并增加“全选本页/取消本页”且保留跨页选择；契约测试 51/51 通过。
• 完成微店 AI 副店长的简历与方案材料梳理，明确调价安全闭环属于当前可支撑的能力，ERP 和真实电商接入仍是规划；评测指标统一按受控 Mock 口径表达，避免把方案写成线上事实。

🧩 困难/需要帮助

• 正式生题的安全并发阈值仍缺网关性能、CPU、数据库连接等运行指标，当前不能把瓶颈直接定责给单一运行单元或上游服务。
• run 3812、网关路由与 Trace 的时间关系尚未逐条对齐，需要补齐同一请求的链路证据后再判断配置是否生效。
• 全局准入和排队策略还需结合持久化任务的重试、租约和发布验证进一步确认，避免“忙碌”状态被误记为“生成中”。

💭 感想

今天主要是在把正式生题从“任务失败/执行慢”的笼统描述，收敛到逐机会超时、无背压准入和配置时序三层事实。页面交互和双会话职责也落到了可验证的规则上；方向已经明确，但容量阈值和路由证据还需要继续补齐。

2026/09/22 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成正式生题任务 67 的机会级复盘，确认 10 个独立问题均已终态、未产出待审核题；失败拆分为 6 条执行超时（含 DIRECT_SESSION_TIMEOUT、SDK_TIMEOUT）和 4 条结果校验拦截，避免再把 completedOpportunityCount 当成成功数。
• 推进正式生题 V5 收敛，服务端一次性组装冻结 ContextPack，模型改为单次结构化生成，不再在会话内逐个读取 Skill 或无限修复；引用改由 evidenceRef 回填冻结证据。任务 68 现场验证后，已将 max_turns 从 1 调整为 2，避免正常结构化终态被内部回合上限误杀。
• 补齐正式生题 SDK 可观测链路，记录 capacity_wait_ms、context/task/opportunity/attempt 关联和 session_key；同时确认旧 asset trace 只是组包审计，不能当作 SDK 调用，为后续区分排队、单次生成与校验耗时建立口径。
• 定位 CP 创建正式生题时的 400 包装链路，确认 Tether 到上游 Dubbo Provider 超时后返回纯文本 context deadline exceeded，CP 的 dubbo_invoke.js 将其按 JSON 解析才形成 400；当前进一步收敛到 wakeDispatch 在 Dubbo 请求线程逐条等待 Python 异步受理回执，而非 Node 自身超时。
• 完成“资料→独立问题→题库”技术链路及应用边界梳理：当前可用入口为 sellai-train-cp-admin，经 sellai-train-knowledge、sellai-train-ai 到 sellai-train-backend；商家后台的生题/审核代码尚未挂总路由，小程序 BFF 不参与该链路。
• 梳理 QA-SC 到 Prod 的发布范围，明确不复制 QA 业务数据；Question Case 最小主链只涉及 question_case 新表和 question 的 4 个围栏字段，Prod 还需按当前代码逐项补齐 SCM 与资源前置。

🧩 困难/需要帮助

• 任务 68 在新路径已生效时仍出现 SDK_MAX_TURNS_EXCEEDED；max_turns 已调整，但尚无本轮完整候选题落库成功证据，新增黑盒回归也受本机缺少 pytest 入口限制，需在项目环境验证。
• 当前 Backend migration 存在 V37/V38/V39 同号文件冲突，不能全量自动执行；需按确认功能拆成显式 DDL、逐表回读，并补齐首发保持关闭的 SCM 开关、AI 预算、cursor keyring 与最小 DB 权限。
• CP 400 目前只证明到 Tether/Provider deadline；仍需用同一请求的 CP URL、耗时与 TraceId 关联 Provider 记录，才能判定究竟慢在受理、Provider 还是下游依赖。

💭 感想

今天主要是在把正式生题从“生成慢、任务失败”的笼统现象，收敛到机会级终态、会话回合和冻结上下文三个可验证层面。V5 的方向已从让会话自己找资料、反复修复，转为服务端先固定输入、模型只生成、服务端确定性验收；接下来关键是用实际成功率和耗时验证改造，而不是只看链路已经切换。

2026/09/23 今天做了啥？ ✨

今天主要是在把 7 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成正式生题任务 71 的机会级复盘，确认 10 条机会均已终态、没有题目进入待审核：3 条 DIRECT_SESSION_TIMEOUT、4 条 CONTEXT_SCHEMA_INVALID、1 条 SDK_TIMEOUT，另有 2 条在 Knowledge Verdict 的 verify 阶段被拦截。
• 定位 V5 候选题验收拦截根因：QA-SC Knowledge 1bd441e3 将第 5 次调用固定校验为 allowed_card_evidence，实际成功回执为 generation_requirement；两次证据调用的返回数与引用数分别为 8/8、3/3，需求回执均为 1 条且无需引用。
• 完成 Knowledge 本地修复，AiOwnedV4TraceVerifier 已接受 V5 第 5 次 generation_requirement 回执，同时保留 V4 与记忆回执规则；定向 Maven 测试 10/10 通过。
• 完成 AI 服务会话时限与结构校验可观测性修复：首次调用和修复轮共享总时限，ContextPack 准备耗时纳入预算，日志补充稳定规则代号且不记录业务正文；目标分支定向测试 43 项通过、git diff --check 通过，当前未提交、未推送、未发布。
• 定位预发 pre/bjh AI 服务启动失败，新的 Pod 因 SCM 三项变量被注入空字符串而触发布尔/数值校验并进入 CrashLoopBackOff；旧 Pod 仍 Ready，应用汇总态存在误导风险。
• 定位 Backend 定时任务 SQL 报错，QA 的 sellai_train 尚未执行 V44，运行代码已使用缺失的 profile_rebuild_pending 字段；两个 March Key 缺失是独立配置问题，不能混为同一根因。
• 梳理 QA-SC 到 master 的二方包依赖与发布顺序，确认 6 个仓的 change 最新提交均已进入主干；代码合并状态不能替代实际 Pod 版本和运行验证。

🧩 困难/需要帮助

• 任务 71 的两个 Verdict 门禁问题已有本地修复，但其余 8 条超时/结构校验失败仍需按真实错误分型继续处理，不能把局部修复写成全量恢复。
• 预发需确认 SCM 三项配置的实际业务取值并修正空字符串，再验证新 Pod Ready；旧 Pod Ready 不能替代本次配置恢复验证。
• QA 需补齐 V44 迁移，并继续确认两个 March Key 的用途与配置边界，避免把数据库迁移缺失误判为配置问题。

💭 感想

今天主要是在把正式生题失败从统一失败态收敛到机会级、验收级和运行环境级的具体证据。修复边界已经更清楚，但配置恢复、迁移执行和真实回归还要分别闭环，不能靠单个成功信号下结论。

2026/09/25 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成 WeKnora 接入现状与三仓同名分支梳理，确认当前已落地的是“商家资料入库与解析”，从 WeKnora 检索内容并生成题目的后半段尚未接通。
• 对齐资料导入主链：CP 管理台负责文件直传七牛、资料登记和发起导入，浏览器不直连知识库；CP 再通过 Dubbo 调用 Knowledge，由 Knowledge 使用服务端配置调用 WeKnora API。
• 定位“基于 WeKnora 生题”入口的边界问题，CP 侧请求与 Knowledge 分支 Dubbo 入参目前不一致，现有代码不能据此认定生题链路已经可用。
• 核对 CP、Backend、Knowledge 三仓分支提交与改动范围，确认 Backend 同名分支未保留可合入的 WeKnora 实现，避免把无关功能一起带入目标分支。
• 推进 Knowledge 的 change 分支合入 WeKnora 资料导入提交，合并过程无冲突；当前仍在等待编译验证结果，不把合入本身当作可运行结论。
• 核实 CP 管理台合入基线，当前工作区干净且与远端一致，已按题库页面和 Node 接口两个方向检查潜在冲突，最终合入结果待回收。

🧩 困难/需要帮助

• 需要先对齐 CP“基于 WeKnora 生题”入口与 Knowledge Dubbo 的接口契约、入参和状态边界，否则资料导入完成后仍无法形成可控的检索生题闭环。
• 运行环境的配置、租户隔离和失败状态尚未联调验证；Knowledge 编译与 CP 合入的最终结果也需要补齐后再判断可发布性。

💭 感想

今天主要是在把 WeKnora 事项往真实分支、调用链和仓边界上收敛。资料入库方向已经比较清楚，但要形成业务闭环，关键还是补齐检索到生题的后半段，并把 CP 和 Knowledge 的接口契约一次对齐。

2026/09/30 今天做了啥？ ✨

今天主要是在把 4 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 确认今日可用证据仅指向“POS机门店绑定报错”排查线索；未留存可复核的门店、终端、报错时间或请求链路，暂不对根因下结论。
• 梳理该问题后续需要补齐的核对面：门店绑定关系、POS终端信息和报错发生时间；待取得实际工单或日志后再收敛责任链路。
• 确认现有记录中没有代码修改、配置变更、发布或修复验证的业务证据，相关状态均保留为待确认。
• 证据不足，今日只记录以上可确认事项，避免把排查意图写成问题已定位或已修复。

🧩 困难/需要帮助

• 目前缺少该报错对应的门店/终端标识、完整报错文案、发生时间和请求链路；补齐后才能判断是绑定数据、终端配置还是调用校验问题。

💭 感想

今天主要是在把 POS 机门店绑定报错先收敛到可核验的证据边界。现阶段信息不足，先把事实补全比提前判断根因更重要。

很多人第一次看到 Superpowers 这个词，会以为它是某个官方新功能，或者某个插件按钮。

但如果用大白话说，我理解里的 Superpowers 更像这样一件事：

它不是一个单点能力，而是一套把 AI 从“会聊天”升级成“会按流程干活”的增强方法。

也就是说，它关心的不是：

• 模型会不会写一段代码
• AI 能不能回答一个问题
• 它偶尔能不能给你一个还不错的建议

它真正关心的是：

• AI 能不能进入一个明确的工作流
• 能不能在不同阶段拿到不同上下文
• 能不能按规则调用工具、脚本和资料
• 能不能把一次经验沉淀成以后可复用的能力

这也是为什么我会把 Superpowers 放在 Skill扫盲 和 dev-skill 之间来讲。

• Skill 解释的是能力单元是什么
• Superpowers 解释的是这些能力怎么真正跑起来
• Agent Team 解释的是多个 AI 怎么协作
• dev-skill 解释的是这一整套能力怎么仓库化、工程化、治理化

  flowchart LR    classDef concept fill:#DBEAFE,stroke:#2563EB,color:#111;    classDef method fill:#FCE7F3,stroke:#DB2777,color:#111;    classDef infra fill:#DCFCE7,stroke:#16A34A,color:#111;    A["Skill<br/>能力单元"]:::concept --> B["Superpowers<br/>工作方法"]:::method    B --> C["Agent Team<br/>协作编排"]:::method    C --> D["dev-skill<br/>仓库与治理"]:::infra    B --> D  

一、为什么我会单独写一篇 Superpowers

因为很多人现在已经走到了同一个阶段：

• 会写 Prompt 了
• 会给 AI 喂上下文了
• 也开始接触 Rules、Skill、MCP、命令脚本这些东西

但真正一上手，还是经常会遇到几个很真实的问题：

• AI 回答得挺聪明，但不会自己走流程
• 每次都要重新解释项目背景，重复劳动很重
• 上下文一多就乱，关键资料反而被淹没
• 任务一复杂，AI 又退回成“会说不会做”

这时候你会发现，问题不是“模型不够强”，而是缺了一层工作方法。

Superpowers 讲的就是这一层。

它本质上是在回答一个问题：

如果我希望 AI 像一个真正的开发搭子，而不是一次性聊天机器人，我到底应该怎么组织它？

二、什么是 Superpowers

如果要我给它一个尽量接地气的定义，我会这样说：

Superpowers = 规则 + 技能 + 工具 + 路由 + 记忆 + 治理 的组合增强。

单独看这里面的每一项，其实都不新鲜。

• Rules 不是新概念
• Skill 也已经越来越常见
• 工具调用、命令执行、MCP 也都有人在用

但一旦你把它们组合起来，AI 的工作方式就会发生质变。

从“会答题”到“会做事”

没有 Superpowers 的时候，AI 更像一个临场发挥型选手：

• 你问什么，它答什么
• 你提醒一步，它走一步
• 你不提醒，它就不会主动进入正确流程

有了 Superpowers 以后，它更像一个带 SOP 的搭子：

• 先识别这是什么任务
• 再加载对应能力
• 再按约定顺序推进
• 需要工具时去调工具
• 做完后给出可复盘、可交付的结果

  flowchart TD    A["用户请求"] --> B["任务识别 / 路由"]    B --> C["加载相关 Rules / Skill"]    C --> D["读取 references / 执行 scripts"]    D --> E["产出结果并校验"]    E --> F["沉淀经验 / 更新知识"]  

这张图其实就已经说明了 Superpowers 的核心味道：

它不是让 AI 更会“说”，而是让 AI 更会“按流程推进任务”。

三、Superpowers 到底增强了什么

我把它拆成 5 个最关键的能力。

1. 任务路由能力

AI 最怕的一件事，就是一上来把所有信息都吞进去，然后开始“自由发挥”。

Superpowers 的第一步，不是立刻干活，而是先判断：

• 这是开发任务
• 还是排障任务
• 还是代码审查
• 还是写文档
• 还是查 JIRA、查日志、查链路

只有先分流，后面的上下文和工具才不会乱。

这也是为什么现在越来越多体系里，会把：

• skill description
• 路由器 skill
• 命令入口
• workflow orchestrator

这些东西放在最前面。

因为它们本质上是在帮 AI 做“任务分诊”。

2. 渐进式上下文加载能力

这一点和 Skill 是强相关的。

普通做法里，我们很容易把一大堆背景全部塞给 AI：

• 项目规范
• 业务背景
• 常见坑位
• 各类文档链接
• 一堆脚本说明

结果是：

• token 越来越贵
• 有用信息密度越来越低
• 真到关键任务时，上下文已经被冲散了

而 Superpowers 更像一层“按需读取机制”：

1. 先只让 AI 看到能力目录
2. 判断相关后再读 SKILL.md
3. 真要落地时再读 references/
4. 有脚本就直接执行，而不是让模型硬背

  flowchart LR    A["目录层<br/>name + description"] --> B["方法层<br/>SKILL.md"]    B --> C["资料层<br/>references/"]    B --> D["执行层<br/>scripts/ tools"]  

这一步一旦做好，AI 的行为会稳定很多。

3. 工具闭环能力

AI 真正有战斗力，不是因为它能“猜”，而是因为它能“查”和“做”。

所以 Superpowers 很重要的一环，就是把它和真实工具链接起来。

比如：

• 用 shell 查代码、跑测试、起服务
• 用脚本做统计、同步、校验
• 用 MCP 去读平台资源、文档、数据库、监控
• 用 Git 操作让结果真正落盘

你会发现，一旦 AI 不只是生成文本，而是能进入工具闭环，它就开始像一个执行系统了。

4. 多 Agent 协作能力

很多任务不是一个脑袋就能顺滑做完的。

比如一篇完整的技术文章，常常可以拆成：

• 一个 Agent 负责梳理主题结构
• 一个 Agent 负责搜集现有仓库和文章联动
• 一个 Agent 负责检查 Hexo 渲染和链接是否正常

这就是为什么我会把 Superpowers 和 Agent Team 放在同一条链路里。

它们不是同一个概念，但天然互补：

• Superpowers 解决“单个 Agent 怎么更会做事”
• Agent Team 解决“多个 Agent 怎么分工协作”

5. 治理和沉淀能力

这一层其实最容易被低估。

很多人会把一次成功的 AI 使用经验，当作“这次运气不错”。

但如果你想让它长期可复用，就得继续往后走：

• 把方法写成 Skill
• 把脚本放进 scripts/
• 把说明写进文档
• 把使用记录沉淀成统计
• 把常见入口做成标准工作流

从这个角度看，Superpowers 不是一招鲜，而是一套可以持续积累的能力系统。

四、它和 Skill、Rules、MCP、Agent Team 分别是什么关系

这一块特别容易混，我直接用一句话版本先讲：

• Rules：长期静态背景
• Skill：某类任务的能力说明书
• MCP / Tools：让 AI 能查、能做、能执行
• Superpowers：把上面这些东西真正组织起来的使用方法
• Agent Team：把多个 Agent 编排成协作流水线

一张图看懂它们的分工

  flowchart TD    A["Rules<br/>长期背景"] --> E["Superpowers<br/>组织与调度"]    B["Skills<br/>任务能力"] --> E    C["MCP / Tools<br/>查询与执行"] --> E    D["Memory / Repo<br/>知识与沉淀"] --> E    E --> F["单 Agent 稳定产出"]    F --> G["Agent Team 多角色协作"]  

如果非要说它们谁更底层，我会这么理解：

• Rules 负责“别跑偏”
• Skill 负责“这类事怎么做”
• Tool 负责“真干活靠什么”
• Superpowers 负责“把这几样按流程串起来”

所以 Superpowers 更像是一套编排思想，而不是单一组件。

五、真实使用里，我会怎么给 Claude Code / Codex 上 Superpowers

这一段是最偏实操的，也是最容易直接照着做的。

第一步：全局 Rules 只保留长期有效的信息

不要把所有操作细节都塞进全局 Rules。

全局层更适合放：

• 仓库基本背景
• 协作习惯
• 风格约束
• 安全边界
• 输出要求

一句话说就是：放长期有效、跨任务通用、每次都可能用到的东西。

第二步：把任务方法拆成 Skills

别把“如何做代码审查”“如何查日志”“如何写技术方案”全塞进一个大 Prompt。

把它们拆成独立 Skill 的好处是：

• 描述更清楚
• 触发更精准
• 可以挂对应脚本和参考资料
• 后续能独立演进

第三步：给常见任务做路由入口

比如：

• 日常开发走一个入口
• JIRA 闭环走一个入口
• 排障诊断走一个入口
• 文档写作走一个入口

这样 AI 不用每次从零猜你的意图。

第四步：能用脚本的地方，尽量别靠模型硬编

这是一个非常重要的经验。

如果某个动作本来就能脚本化，比如：

• 查询统计
• 生成模板
• 同步文件
• 执行标准检查

那就尽量让 AI 去调脚本，而不是自己现场“想象一个做法”。

这样稳定性会高很多。

第五步：把结果反向沉淀

每次遇到这些场景，都值得考虑是否沉淀：

• 某个提示词反复有效
• 某条执行顺序总是有用
• 某个脚本特别省事
• 某类问题总会重复出现

这时候最好的动作不是收藏聊天记录，而是把它升格成：

• Rules
• Skill
• Script
• Template
• 文档

  flowchart TD    A["一次成功任务"] --> B["提炼稳定做法"]    B --> C["写入 Skill / Script / Doc"]    C --> D["后续任务继续复用"]    D --> E["再次优化与治理"]  

这条闭环一旦转起来，AI 的成长就不再只靠记忆，而是靠外部化沉淀。

六、结合我自己的 dev-skill 仓库，Superpowers 是怎么落地的

如果只讲概念，Superpowers 很容易显得有点虚。

但放到我自己的 dev-skill 仓库里，它就会非常具体。

我现在更愿意把这个仓库看成一套“能力中台”：

• skills/dev/ 负责开发主流程
• skills/cr/ 负责代码审查和测试相关流程
• skills/zan/ 负责有赞内部平台能力接入
• skills/platform/ 负责安装、同步、统计、工作树等平台支撑
• skills/writing/ 负责文档、图表、PDF、方案协作

这其实就是把 Superpowers 变成了工程化结构。

它不是“很多 Skill 的堆叠”

更准确地说，它在做三件事：

1. 把高频任务拆成标准能力单元
2. 把能力单元接到真实脚本和平台上
3. 把使用过程继续纳入统计、治理和迭代

一条典型链路长什么样

比如一个“JIRA -> 排查 -> 改代码 -> CR”的闭环，大致可以是这样：

  flowchart LR    A["用户提需求 / 给出 JIRA"] --> B["路由到对应 workflow"]    B --> C["读取相关 skill 说明"]    C --> D["调用日志 / trace / jira / repo 工具"]    D --> E["产出修改建议或代码改动"]    E --> F["触发 review / test / 文档沉淀"]  

你会发现，这已经不是“问一句答一句”的玩法了。

它更像一条围绕 AI 构建的微型研发流水线。

七、哪些场景最值得用 Superpowers

如果你刚开始搭，不用一上来就全都做。

我更建议从这 4 类任务开始：

1. 高频重复任务

比如：

• 提交代码
• 起分支
• 写周报
• 查 JIRA
• 写技术方案模板

这类任务最适合先做标准化。

2. 容易出错的流程任务

比如：

• 多仓库联动提交
• 子模块提交顺序
• 发布前检查
• 排障链路分析

因为这些任务最需要“别漏步骤”。

3. 对上下文依赖很强的任务

比如：

• 业务问题排查
• 大型项目代码修改
• 架构文档补全

这类任务只靠临场对话很容易失真。

4. 适合长期积累的方法任务

比如：

• Code Review
• 技术文章写作
• 测试策略生成
• 知识沉淀与复盘

因为做得越多，后面的复用收益越高。

八、一个很重要的认知：Superpowers 不是魔法，是工程

我很想强调这一点。

很多人听到 Superpowers，容易下意识理解成：

有没有什么神奇配置，一开就能让 AI 突然变得特别厉害？

真实情况恰恰相反。

它更像软件工程：

• 你要拆分职责
• 要控制上下文
• 要规范输入输出
• 要把可自动化的部分外置
• 要给能力做版本化和治理

所以它不是“神秘技巧合集”，而是一套很朴素但很有效的工程方法。

说得再直白一点：

Superpowers 的核心，不是给模型加法术，而是给 AI 接流程、接制度、接工具、接沉淀。

九、如果你也想开始，可以直接照这个最小方案来

如果你不想一口气搞太重，我建议先从这个最小闭环开始：

1. 写一份简短但稳定的全局 Rules
2. 为 3 个最高频任务拆出独立 Skill
3. 每个 Skill 只挂最必要的文档和脚本
4. 给这 3 个任务各做一个清晰入口
5. 每周回看一次，补沉淀、删噪音、修描述

这个版本就已经足够有感知了。

你会明显感受到的变化

• AI 不再每次都要重头讲规则
• 它更容易走进正确工作流
• 产出结果更稳定
• 你自己也更容易复盘“为什么这次做得好”

十、最后一句话

如果用一句话总结我理解里的 Superpowers，我会这么说：

它是把 AI 从“聪明回答者”升级成“流程化执行者”的那套方法。

它不等于某个产品功能，也不等于某个单独 Skill。
它是一整套围绕：

• 上下文管理
• 能力路由
• 工具执行
• 经验沉淀
• 协作治理

建立起来的工作方式。

而一旦这套东西跑顺了，AI 才真的开始像一个能长期共事的开发 Agent。

延伸阅读

• 如果你想先理解 Skill 本身是什么，可以读 Skill扫盲：从提示词补丁到AI工作流，我如何用dev-skill把经验沉淀成能力系统。
• 如果你想看多 Agent 怎么串起协作，可以读 Agent Team使用教程：用Tmux分屏把多个AI串成自动协作流水线。
• 如果你想看这一套能力如何进一步仓库化、治理化，可以读 dev-skill仓库全景：一套技能体系如何把AI Coding变成团队基础设施。
• 如果你想继续往底层看 harness、memory、skill 的工程结构，可以读 Claude Code Harness深度分析：从RAG、Skill、Memory到企业Agent落地。

项目地址：GitHub · dev-skills · Gitee · dev-skill

我做这个项目的出发点很朴素：把自己在需求分析、开发、审查和测试里反复使用的方法，整理成能被 AI 工具识别、安装和组合调用的 Skill。

dev-skill 是一个个人维护、可以公开分享的轻量仓库。它不是提示词大杂烩，也不试图包装成万能的“AI 操作系统”；更像一个 DIY Agent Skills 工具箱：每个 Skill 有明确职责，既可以单独使用，也可以沿着一条研发工作流协作。

仓库源码、安装说明和每个 Skill 的具体约束，都以 GitHub 仓库 为准；也可通过 Gitee 镜像 访问。

一、它想解决什么问题

很多 AI Coding 的经验最初都很零散：

• 某个好用的提示词只留在聊天记录里；
• 同一套规则要在不同客户端重复配置；
• 需求、实现、审查之间缺少连续上下文；
• 工作流跑顺后，下一次又得从头解释一遍。

dev-skill 想做的，是把这些一次性的经验变成可复用、可安装、可迭代的能力单元。你可以把它理解为：

把“我平时怎么让 AI 帮我做研发”沉淀成一套能继续演进的项目资产。

它更适合希望把个人工作流整理清楚的开发者；仓库刻意不包含组织专用集成、私有凭据或生产数据，文档示例也使用中性命名，方便阅读和分享。

二、一张图看懂项目结构

dev-skill 目前不是一个庞大的平台，而是一套围绕研发过程组织起来的 12 个 Skill。它们大致分成四层：先把需求想清楚，再把工程上下文找全，然后进入实现，最后用审查和测试把风险收住。

  flowchart TB    subgraph DEV["Development：把需求变成可执行开发任务"]        BRAIN["brainstorming<br/>澄清目标、约束和方案选择"]        SCANNER["app-scanner<br/>扫描多应用工作区，提取业务能力"]        SDD["sdd-dev-workflow<br/>产出 requirements / design / plan / tasks"]        PAIR["ai-pair-programmer<br/>结对实现、修复、重构和验证"]    end    subgraph REVIEW["Review：把改动变成可放心交付的结果"]        AUTHOR["author-final-review<br/>审查单一作者最终态变更"]        CODE["code-review<br/>检查质量、安全、性能和架构风险"]        TEST["integration-test<br/>按风险生成集成测试用例"]        FULL["full-review<br/>汇总代码审查、影响面和测试设计"]        TEAM["team-cr<br/>准备多人 CR 会议讨论清单"]    end    subgraph VIS["Visualization：把复杂信息画清楚"]        DIAGRAM["diagram-creation<br/>生成流程图、架构图、时序图、路线图"]    end    subgraph PLATFORM["Platform：管理工作环境和使用统计"]        WORKTREE["git-worktree<br/>管理并行开发 worktree"]        TRACKER["skill-usage-tracker<br/>记录技能使用统计"]    end    BRAIN --> SDD    SCANNER --> SDD    SDD --> PAIR    PAIR --> AUTHOR    AUTHOR --> CODE    AUTHOR --> TEST    CODE --> FULL    TEST --> FULL    FULL --> TEAM    DIAGRAM -. "可插入任意阶段" .-> SDD    WORKTREE -. "隔离分支环境" .-> PAIR    TRACKER -. "记录每次 Skill 调用" .-> BRAIN  

这张图可以先当成项目地图：Development 负责把“我要做什么”变成“我知道怎么做”；Review 负责把“做完了”变成“风险可解释”；Visualization 和 Platform 则是横向能力，一个负责表达复杂关系，一个负责让工具链可维护。

三、12 个 Skill 分别做什么

为了让读者不用跳到仓库里翻目录，下面按真实仓库中的 Skill 逐个说明。

每个 Skill 都放在 skills/<分类>/<skill 名>/ 下，以 SKILL.md 说明触发条件、输入输出和执行边界；需要时还会携带脚本、参考资料或模板。这样的结构让“能力说明”和“实际工具”留在同一个可追溯的位置。

四、开发中哪些环节可以用到这些 Skill

光看 Skill 名字还不够直观，我们换成一个真实开发例子：给订单系统增加“优惠券抵扣”能力。

这类需求通常不会直接进入编码。它会经历需求澄清、影响面扫描、方案拆解、代码实现、测试设计、代码审查和团队评审几个阶段。dev-skill 的价值，就是把这些阶段拆开，每一步用合适的 Skill 接住。

  flowchart TD    START["需求例子<br/>订单系统支持优惠券抵扣"]    subgraph PHASE1["阶段 1：想清楚要做什么"]        BRAIN["brainstorming<br/>澄清优惠券规则、边界和验收口径"]        OUT1["产物<br/>哪些券可用、如何叠加、异常怎么处理"]    end    subgraph PHASE2["阶段 2：找到会被影响的代码"]        SCAN["app-scanner<br/>多应用场景下扫描订单、营销、支付等应用"]        SDD["sdd-dev-workflow<br/>结合真实代码证据整理方案"]        OUT2["产物<br/>requirements / design / plan / tasks"]    end    subgraph PHASE3["阶段 3：隔离环境并开始实现"]        WT["git-worktree<br/>为优惠券需求创建独立工作区"]        PAIR["ai-pair-programmer<br/>修改接口、领域逻辑、测试和配置"]        OUT3["产物<br/>可运行的代码改动与验证结果"]    end    subgraph PHASE4["阶段 4：把风险收住"]        AUTHOR["author-final-review<br/>先审查本次作者最终态变更"]        CODE["code-review<br/>检查兼容性、金额计算、安全和性能风险"]        TEST["integration-test<br/>生成 P0 / P1 集成测试用例"]        FULL["full-review<br/>汇总审查结论、影响面和测试覆盖"]    end    subgraph PHASE5["阶段 5：准备协作交付"]        DIAGRAM["diagram-creation<br/>画调用链、状态流转或优惠券计算流程"]        TEAM["team-cr<br/>整理多人 CR 会议讨论清单"]        TRACK["skill-usage-tracker<br/>记录技能使用，沉淀本地统计"]    end    START --> BRAIN --> OUT1 --> SCAN --> SDD --> OUT2    OUT2 --> WT --> PAIR --> OUT3    OUT3 --> AUTHOR --> CODE --> TEST --> FULL    FULL --> DIAGRAM --> TEAM    BRAIN -. "每次调用前记录" .-> TRACK    PAIR -. "每次调用前记录" .-> TRACK    FULL -. "每次调用前记录" .-> TRACK    classDef demand fill:#34495E,stroke:#2C3E50,color:#FFFFFF,stroke-width:2px    classDef discover fill:#E3F2FD,stroke:#1976D2,color:#0D47A1,stroke-width:2px    classDef build fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20,stroke-width:2px    classDef review fill:#FFF3E0,stroke:#F57C00,color:#E65100,stroke-width:2px    classDef collab fill:#F3E5F5,stroke:#8E24AA,color:#4A148C,stroke-width:2px    classDef output fill:#FAFAFA,stroke:#757575,color:#212121,stroke-width:1px    class START demand    class BRAIN,SCAN,SDD discover    class WT,PAIR build    class AUTHOR,CODE,TEST,FULL review    class DIAGRAM,TEAM,TRACK collab    class OUT1,OUT2,OUT3 output  

这张图背后的使用方式可以再翻译成大白话：

这里有一个我很看重的边界：实现不是自动越权发生的。 前面的 Skill 负责弄清需求、建立事实和产出方案；只有用户明确授权后，才进入代码修改与验证。

对开发者来说，这比“让 AI 一次性写完”更可控：每一步都有对应的上下文、检查点和产物。

五、如何安装并开始体验

项目通过 profile 管理默认安装清单。macOS / Linux 用户在仓库根目录依次执行：

make audit-skillsmake install-dry-runmake install

• make audit-skills：检查 Skill 数量、重名和职责重叠；
• make install-dry-run：预览同步计划，不修改任何文件；
• make install：正式同步 config/profiles/diy.skills 中定义的 Skill。

Windows PowerShell 5.1+ 可执行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 previewpowershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 install

安装器会检查每个 Skill 的 SKILL.md、补齐其 depends_on 依赖，并只处理当前机器上实际检测到的 Cursor、Claude Code 与 Codex 客户端。未安装的客户端会被安全跳过。

六、为什么更新能保持一致

仓库只维护一份 Skill 源码，客户端通过链接引用它：

• macOS / Linux 使用软链接；
• Windows 使用 Junction；
• 修改仓库内的 Skill 后，已链接的客户端可以直接读到新版本。

  flowchart LR    A["skills/<分类>/<skill><br/>唯一源码"] --> B["安装器"]    C["config/profiles/diy.skills<br/>默认安装清单"] --> B    B --> D["Cursor"]    B --> E["Claude Code"]    B --> F["Codex"]  

这避免了把同一份内容复制到多个工具目录后逐渐失控的问题。安装时若遇到同名冲突，也可以选择跳过、重命名或确认后覆盖；卸载只会移除该仓库创建的链接，不会删除 Skill 源码。

七、给想深入的人：它如何治理自己

一个 Skill 仓库能否长期维护，不只取决于写了多少能力，还取决于有没有把质量和边界放进流程。

• scripts/audit-skills 用于审计数量、重名与功能重叠；
• skill-usage-tracker 将本地使用统计写入 ~/usage_stats.json，可配合看板查看；
• 任何 Skill 执行前都要先记录使用，避免统计只靠人工回忆；
• 强制覆盖和删除源码属于高风险操作，推荐先使用 dry-run 核对影响范围。

我目前采用的安全同步顺序很简单：

审计 → dry-run → 处理冲突 → 安装 → 检查链接

这套流程不复杂，但能让工具箱在持续增加 Skill 时，仍保持来源清晰、更新可控、问题可回退。

八、从哪里开始

如果你第一次打开这个项目，建议这样浏览：

1. 先读 README，了解项目定位和安装方式；
2. 再看 skills/README.md，了解不同 Skill 的职责；
3. 选一个真实场景，再阅读对应 Skill 的 SKILL.md。

这篇文章讲的是项目本身；如果你想先理解 Skill 为什么不只是“提示词补丁”，可以继续读：

• Skill扫盲：从提示词补丁到AI工作流，我如何用dev-skill把经验沉淀成能力系统
• Superpowers使用指南：把Claude Code和Codex变成真正会按流程工作的开发Agent

也欢迎直接从 dev-skills GitHub 仓库 开始，按自己的工作流挑一个 Skill 试用。

这里按天记录工作内容、遇到的问题和当天的一点想法，方便月底回看。

2026/07/20 今天做了啥？ ✨

今天主要是在把 7 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 推进 POS 刷卡返回 0 排查，确认 posBankCardPay=1 只代表开关透出，真正发起还要看 retail-trade-core 支付链路是否带全 POS_BANK_CARD 和终端信息；当前重点收敛到发布状态、资产侧开关和支付参数透传边界。
• 推进 ONLINE-980193 门店 POI 问题排查，已从 JIRA 抽到 trace 和时间窗，但没有直接命中 app；后续需要继续用 trace 和关键词双向补证，把问题落到具体仓库和模块。
• 核查 OrderOperateOpenService.addRemark 类型异常，确认本地业务源码里没有直接调用点，问题更像发生在编译依赖、运行时 Dubbo 泛化或开放服务代理层；目前还需要方法签名和参数位置证据来判断是否为接口版本差异。
• 梳理 code-sentry 记忆召回链路，确认分析 run 里会做 pre_recall 和 evidence_enhanced 两次召回，命中的生效记忆会进入右侧“记忆召回”块，而不是 Timeline 里的独立步骤。
• 对齐 code-sentry 记忆展示和规则分层，明确记忆不应该只暴露底层字段，更要说明“什么情况下命中、命中后注入什么、分析时应该怎么用”；同时把“发布后错误不等于发布引入”沉淀成全局分析规则。
• 解析发布分析 prompt 的记忆注入方式，确认当前不是把整库全量塞入，而是先召回相关经验再完整注入；同时发现两条 NPE 经验与本次 PurchaseSuggestService 错误关联偏弱，后续要优化召回精度、去重和可观测性。
• 确认 GitLab 地址修改边界和本机 Git 提交身份，明确截图里改的是项目路径不是 Group 路径；当前仓库生效的提交名和邮箱来自全局 .gitconfig。

🧩 困难/需要帮助

• POS 刷卡和 ONLINE-980193 还缺更完整的 trace、app 映射和配置/发布侧证据，暂时只能把范围收敛到链路和模块，不能直接下最终根因。
• addRemark 类型异常还需要拿到运行时接口签名、依赖版本或 Dubbo 参数位置，才能确认是调用方传参问题还是 API 版本差异。
• code-sentry 记忆系统还要继续对齐案例记忆、全局规则和 prompt 注入的边界，尤其要避免弱相关记忆因为异常类型相似而带偏判断。

💭 感想

今天主要是在把几个问题往真实链路和判断口径上收，支付、JIRA、Dubbo 异常都不能只凭现象下结论，还是要回到 trace、配置、接口签名和发布前后对比。

code-sentry 这边的方向也更明确了，记忆不是越多越好，关键是命中条件、注入内容和使用方式要讲清楚。

2026/07/22 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 梳理 PLU 价格取值异常整改，确认 PRD/RFC 里的核心矛盾是 PC 不新增字段却要求后端保留 PLU 标签金额；当前口径收敛为 BCartService.addGoods/sync 统一承接 pluAmount，在商品价和重量就绪后做 <=1分 校验并写入购物车。
• 核查 prod 终端绑定消息消费，确认 customer_core_pos_terminal_change 由 retail-trademanager 的 PosTerminalBindConsumer 消费，09:42:52 和 09:43:10 两条 ALLOCATION_CHANGE 已命中接收日志，同窗口没有参数异常、处理失败或重试日志。
• 继续追 POS 终端绑定落库细节，确认首次 insert 触发 uniq_provider_sn 唯一键冲突属于幂等 upsert 分支，不等同于消费失败；后续重点放在冲突后的 select + update 是否把绑定状态更新到预期。
• 梳理飞书转发字段，确认实际请求体只有 deployer、templateData、feishuGroup、msgType 4 个顶层字段，业务字段都在字符串化的 templateData 里，其中 mrIid 是 GitLab MR 的项目内编号，多 MR 时会拼接展示。
• 完成 youzan-cli 使用方式梳理，确认它是覆盖商品、客户、订单、营销、店铺、企微、进销存等领域的 Node.js 命令行工具；首次使用链路是安装、授权、auth status 验证，再通过 --help 和 schema 找到具体查询或导出命令。
• 解释 JsonUtils.toJson 和 json2Bean 的边界，确认 toJson 是 Java 对象到 JSON 字符串的序列化，不会校验或修复字符串里的不规范 JSON；如果输入本身是 JSON 文本，更适合走反序列化或显式校验。

🧩 困难/需要帮助

• PLU 价格整改还需要继续对齐 PC、前端和后端的字段契约，尤其是 pluAmount 单位、isPlu 复用边界、>1分 时返回 CART_PRICE_ADJUST_ERROR 的一致性。
• 终端绑定消费层面已经没有失败日志，但唯一键冲突后的 select + update 落库结果还要继续用数据或 trace 证据确认，避免只停留在“消费者收到消息”这一层。
• 飞书转发字段已收敛到请求体和 templateData，后面还要和实际模板展示口径对齐，避免字段存在但卡片侧没有按预期使用。

💭 感想

今天主要是在把几个问题往真实代码链路和接口契约上收敛，POS 终端绑定和 PLU 价格都不能只看现象，还是要落到 topic、consumer、DTO 和金额校验点。

工具使用和飞书转发这两条更偏口径梳理，写清字段来源和使用边界后，后面排查会少很多来回确认。

2026/07/23 今天做了啥？ ✨

今天主要是在把 5 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成交班优惠计算问题分析，确认多出的 0.01 元来自订单 E20260718204921088300063 的统计口径，不是打印机或外设链路多收；retail-printer/retail-peripheral 只是格式化上游 couponPayAmount 后打印。
• 梳理交班统计链路，确认 retail-sync 负责交班期间逐单累计，retail-trademanager.getStaffShiftWorkDetail 负责读取并组装交班详情；其余 10 笔订单与支付流水一致，差异收敛到单笔抖音券核销金额与真实支付金额的 1 分偏差。
• 推进扫码点单禁用规格展示排查，确认 retail-trade-misc#searchV2 返回了 33 个 SKU，而扫码点单分组配置里的 hiddenGoodsSkus 为空数组，因此服务端没有按装修隐藏配置过滤规格。
• 明确扫码点单问题边界，当前只处理“后端为何返回禁用规格”，不合并 iPad 盘点问题；验收口径收敛为服务端响应中不再包含 disableStatus=1 的 SKU。
• 梳理 code-sentry 命名和域名方向，确认产品定位更接近“发布风险分析 + 代码审计工作台”，不适合继续围绕 monitor 命名，也要避开 Sentry 这类已有强品牌词。

🧩 困难/需要帮助

• 扫码点单还需要继续确认商品中心“禁用规格”和装修页“隐藏规格”的职责边界，尤其是 disableStatus=1 是否必须在 searchV2 服务端统一过滤。
• 交班优惠修复方案还要对齐抖音券核销金额、真实支付流水和交班统计三方口径，避免修 1 分差异时影响历史报表或其他券类型。
• code-sentry 命名还需要结合域名可注册性、商标风险和现有产品占用继续筛选，避免只从含义上判断。

💭 感想

今天主要是在把两个线上问题往真实数据口径和代码链路上收敛：扫码点单要分清商品禁用和装修隐藏，交班优惠要分清核销口径和支付流水。

这类问题看起来都是“展示不对”或“金额不对”，但最后都要落到具体接口、配置字段、订单和金额来源上，先把边界钉清楚比直接改代码更稳。

2026/07/25 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 推进满减送重复赠送排查，确认 JIRA 指向生产环境、两个 trace、两个店铺和 7 月 24 日时间窗；关键 trace 已命中 iOS RetailHD 8.51.1 调用 increaseQueryActivity(activityType=8, activityId=0)，并由 retail-ump.IncreaseQueryServiceImpl 返回活动 4365206090 的赠品能力开关信息。
• 核对 retail-ump 仓库和数据口径，确认远端是 retail-service/retail-ump.git，工作区干净；表结构里 ability_status 默认值是 1，且 (kdt_id, activity_id) 有唯一键，因此先排除“字段 DDL 默认写 0”这个方向。
• 梳理赠品能力开关的代码链路，已命中 PresentDetailQuery、PresentOperateHandler、DAO/MyBatis 和现有单测，问题边界从“重复赠送现象”收敛到活动开关默认值、创建继承逻辑以及总部/门店数据分布。
• 定位发布预警分析空结果，确认失败点不是 HTTP 或鉴权错误，而是成功响应后没有最终文本，或连续 12 轮调用耗尽仍没有结论；分析器目前固定只重试 1 次，所以会进入 Retry Exhausted。
• 验证跨应用错误日志抓取，确认 retail-trade-core 的 ERROR 和 yz-cardvoucher-biz 的 WARN 可以通过同一个 traceId 关联；但只查单应用不会自动展开跨应用日志，需要显式把 trace 传给后续分析链路。
• 梳理 ONLINE-981860 初步边界，确认问题发生在生产环境 retail-trade-misc、店铺 91106488，时间集中在 12:24-12:26，当前没有 traceId；已先把 JIRA 产物落到 .doc/20260725130355-ONLINE-981860/jira，后续用截图、店铺 ID 和稳定日志短语补证。

🧩 困难/需要帮助

• 满减送问题还需要继续直查目标记录、总部/门店整体分布和近期开关继承结果，才能把默认值、创建链路和实际重复赠送现象完全闭环。
• 发布预警空结果还缺线上 run 的原始节点和调用产物；当前账号能看到审计表结构，但 qatools 审计表为空，暂时不能把“调用耗尽”当作最终根因。
• ONLINE-981860 缺少 traceId，后面需要从附件截图、JIRA 评论和 12:24-12:26 的生产日志里继续补业务现象和调用链证据。

💭 感想

今天主要是在把满减送和发布预警两个问题往真实 trace、数据库默认值和代码分支上收敛，能确认的先写死，缺证据的地方先留边界。

跨应用日志这块也更清楚了：trace 能把链路串起来，但工具侧的补日志范围、数量和权限还是要讲清楚，不能只说“能查到”。

2026/07/26 今天做了啥？ ✨

今天主要是在把 5 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成 ONLINE-981928 深度分析，确认取餐状态本身已处理成功，真正断点在 retail-trademanager 获取小程序订阅模板时返回 132900009，后续又被伪模板 ID 放大成微信 40037 invalid template_id，所以顾客没有收到取餐提醒。
• 梳理 retail-trade-misc -> retail-trademanager -> msg-push -> wechat-push 的完整链路，确认 MessageClient#getMiniProgramTemplate 在失败时会兜底写入 Default-Mini-Program-Subscription-Template-ID，而 FreeBuyForMealTakeMessageHandler 又无条件继续发送，这是这次问题的关键代码点。
• 对照 JIRA 截图、trace 和评论，确认影响对象收敛到父店铺 160734909、子店铺 206598416、订单 E20260725181329036406197，模板范围是 1820 / order_state_meal_take，当前可以排除订单未完成和消息链路整体不可用。
• 输出了代码修改方案和验证计划，明确模板缺失时要在公共订阅消息链路直接阻断发送，补齐结构化日志，不再把模板配置缺口包装成“发送成功”。
• 整理了技术支持、商家和产品侧的对外口径，统一成“订单正常完成、模板查询失败、微信最终拒发”三层事实，避免只盯着表面消息成功。

🧩 困难/需要帮助

• 模板中心还没有直接补到 160734909/206598416 + 1820 + order_state_meal_take 的真实记录和授权状态，责任边界只能先停在“待补证”。
• 代码层还需要确认是否统一收紧伪模板兜底，避免后续其他订阅消息 handler 也沿用同类错误分支。

💭 感想

今天主要是在把问题往真实模板链路和配置边界上收，sendCount=1 这种上游成功信号不能直接等同于用户侧送达。

这类问题一旦把模板查询失败和微信回执拆开看，链路就清楚很多，后面要补的主要是模板中心证据和统一失败策略。

2026/07/27 今天做了啥？ ✨

今天主要是在把 7 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 推进拆条目金额错误排查，确认折扣条目单价 2.38、数量 1 时小计显示 6.38 的问题已在后端回包里出现，不是前端展示字段映射；当前范围收敛到 retail-trade-cart 拆条和营销回包重构条目链路。
• 完成 PLU 秤码金额差异分析和修复核对，确认 isPlu=true 且 PLU 金额与计算金额差异 <=1 分时应统一取 pluAmount，目标分支 8 个 *PluAmountTest 已通过；另一个 7.30 元标签价 trace 与商品中心 3.40 元/kg 算价差 11 分，属于条码秤和商品中心价格未对齐，不应走 1 分容差。
• 完成 ONLINE-981990 活动叠加异常分析，确认不是 EXCLUDED 配置失效，而是加价购 JS 先按普通商品原价判断门槛，随后又从整车商品里挑换购 SKU，导致被排除的清新蓝莓仍被打上 EXCHANGE_GOODS 并改成 5 元。
• 查明重开单门店日流水号逻辑，确认重开单分支在 SyncRetailDataProcessor#getSerialNo 里调用 queryCurrentSerialNo(kdtId)，只读取当天门店 Redis 计数器当前值，不会 +1；普通门店单才会走 addSerialNo(kdtId) 自增。
• 评审三方券/交班尾差修复方案，确认 1 分差异不是订单实收多收，而是旧接口用“单券金额 * 张数”表达不了 287.67/287.67/287.66 这类分摊尾差；后续要在 Provider 和两个 Consumer 的兼容字段、回退逻辑上一起收口。
• 确认 Case 记忆沉淀列表和算法观察页两个线上问题的修复状态，当前用户可见故障仍未修复：前者生产接口仍返回 HTML 500，后者页面只在 feature/release_memory 分支且仍硬编码 /api，放到 /reports 路径下会打到错误网关。
• 梳理 CLI 接入 MCP 的授权、店铺选择和会话隔离方案，明确 MVP 先走本地安全文件保存 token + 显式 selected_kdt_id；“输入手机号直接枚举全部可访问店铺”不是当前 token 模型天然提供的能力，先作为后续账号/授权中心能力处理。

🧩 困难/需要帮助

• PLU 和拆条金额治理还要继续对齐条码秤价、商品中心价、PC 透传字段和后端计算口径，尤其是 <=1 分取 pluAmount、>1 分阻断的边界要保持一致。
• ONLINE-981990 的修复还需要继续确认门槛判断、排除商品能否作为换购品、会员价后是否需要撤销换购计划这几个边界，避免只修当前蓝莓案例。
• 两个线上页面问题还缺最终部署版本和网关路径改造确认，目前只能明确“用户路径仍异常”，服务端根因还需要继续补证。

💭 感想

今天主要是在把几个金额和活动问题往真实代码链路、日志 trace 和数据口径上收。PLU、拆条、三方券尾差都不是简单“金额算错”，关键还是要分清标签金额、商品中心价、单值乘数量的表达能力和最终展示字段。

线上状态核验也要把用户可见故障和服务端根因分开写，能确认的先确认，缺部署和配置证据的地方不要提前下死结论。

2026/07/28 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成 PLU 会员价支付校验问题分析，确认支付侧 27.81 - 0.87 = 26.94 的总额口径本身没错，异常集中在 trade-core 商品行和订单聚合字段；计件 PLU 叠加会员价二次营销均摊时，标签金额被按单价和数量重新计算，少了 1 分，导致商品明细 26.93 和订单/支付 26.94 对不上。
• 梳理 retail-trade-cart 的 addGoods 改价字段链路，确认 pre 环境后端入参已经收到 pluAmount，问题不在 PLU 前缀或重量解析，而在 CartGoodsRequest.isChanged/changedPrice 与网关 changed_tag/change_price 之间的字段契约和绑定口径。
• 推进移动端订单报表缺失排查，当前主线已从刷卡支付状态机转到 pos-trade-order 和 pos-shift-daily-report；代码信号显示商品销售报表依赖 PcOrderItemPrice.totalPrice，没有价格对象时金额会降为 0，但还需要实单字段和报表落库证据继续闭环。
• 定位 Code Sentry Case 记忆未沉淀问题，确认不是飞书消息发送成功后就自动生成记忆，也不是 2a1c2867 修复后的写库链路仍失败；生产发送记录已能写入，当前根因收敛到发送数据被过短字段截断，随后被页面筛选条件过滤掉。
• 梳理重开单门店日流水号修复意图，确认旧逻辑在重开单时读取门店 Redis 当前流水号，可能拿到旧单之后新生成订单的流水号；新逻辑改为通过 reOrderNo 查询被重开的旧订单持久化数据，并复用旧单流水号。
• 核查 dev-skill 的 Windows 安装支持现状，确认当前安装入口仍是 make + bash 的 Unix-first 流程，不能算正式支持原生 Windows；方案已收敛到补 PowerShell 5.1+ 安装/卸载脚本，使用 Junction 降低普通用户权限要求，同时保留现有 macOS/Linux 流程。

🧩 困难/需要帮助

• PLU 金额治理还需要继续对齐 PC、网关、retail-trade-cart 和 trade-core 的字段契约，尤其是 pluAmount、isChanged/changedPrice 以及 1 分容差和大于 1 分阻断的边界。
• 移动端订单报表缺失还缺实单字段值、报表落库结果和过滤条件证据，暂时只能把可疑点收敛到价格对象缺失分支，不能直接定最终根因。
• Code Sentry 记忆列表还需要确认字段长度修复、历史数据回补和页面 API 读取同一数据源这几件事，否则用户侧看到的 0 记录还不能算完全闭环。

💭 感想

今天主要是在把 PLU 金额、报表缺失和 Case 记忆这些问题往真实 trace、字段契约和数据表筛选口径上收敛。

几个问题看起来都是“金额不对”或“页面没数据”，但真正要判断清楚，还是要一层层确认字段从网关到后端、从写库到页面是否都在同一个口径上。

2026/07/29 今天做了啥？ ✨

今天主要是在把 7 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成 ONLINE-981236 交班/日结三方券尾差修复，确认根因是旧接口只提供“单券金额 × 数量”，三张券真实支付金额 28767+28767+28766=86300 分被算成 86301 分；当前已在 retail-trade-misc 补 totalCouponPayAmount，retail-sync 和 retail-trademanager 改为消费新字段。
• 收敛三方券修复范围，明确 retail-trade-misc 负责按 buyerPayPrice 算准整组券实际支付总额，retail-sync 只替换 8 处旧乘法取值，retail-trademanager 只替换 1 处待支付金额取值；新字段为空时继续回退 couponPayAmount × count。
• 补强三方券链路观测，misc 记录映射不完整和查询异常，sync 记录精确金额命中数和旧逻辑回退数，trademanager 记录券明细为空及旧公式回退；同时确认不打印券码、不逐券刷日志，避免高频链路被噪音淹没。
• 推进 yz7/PLU 下单失败排查，确认不是购物车校验失败，而是下单阶段 retail-trade-cart 与 trade-core 两套计价口径不一致，零售应付 47.57 元、计价侧 47.48 元，相差 9 分后触发 RetailExtraPriceCalculator.checkPrice 金额一致性保护。
• 梳理 PLU 改动范围，确认问题边界在“改价事实、商品优惠、订单优惠”三层金额契约没有完全对齐；当前不能简单改通用 realPay 或全局优惠均摊，需要把 PLU 精确金额、改价金额和 PROS_DETAIL 重新均摊链路一起对齐。
• 推进 Code Sentry 发布告警记忆能力，确认 MySQL VARCHAR(2000) 和索引长度风险后，完成字段限额、超限压缩重试、人工编辑 400 明细返回、双召回 Top2 和 6000 字符注入控制；全量测试 49 个文件、233 个用例通过并推送远端 master。
• 补齐 dev-skill Windows 原生安装支持，新增 PowerShell 5.1+ 安装入口和安装器，覆盖 dry-run、install、uninstall、force、profile、客户端检测等常用流程；Windows 路径改为按用户目录解析，不硬编码用户名，README 也已同步更新并推送。

🧩 困难/需要帮助

• 三方券兼容回退场景仍可能复现旧尾差，需要继续确认 trade-misc-api 二方包发布、MR 合入和 QA 新单验证节奏。
• PLU 问题影响面偏中高风险，优惠券会在多个商品之间重新均摊，仍需要产品、营销、交易一起确认改价事实、商品优惠、订单优惠三层金额契约。
• Code Sentry 旧分支不能整分支合并，旧表结构和当前 VARCHAR-safe 方案有冲突，后续需要选择性迁移控制台、灰度策略和召回观测能力。

💭 感想

今天主要是在把几个问题往真实链路和字段口径上收，尤其是金额类问题，本质都是上游字段语义没讲清楚后被下游二次解释。这个方向比较明确，但后面还是要先把字段契约、回退边界和观测点定清楚，再做最小代码改动。

2026/07/30 今天做了啥？ ✨

今天主要是在把 7 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成拉卡拉 POS_BANK_CARD 支付拦截定位，确认 retail-trade-core 提示“当前 POS 机未绑定该门店”不是 SN 不存在，而是 retail_pos_terminal_bind 中 SN 00000104YP620300016136 绑定到 kdtId=159831351，未绑定到当前下单门店 201479448；支付前校验口径是当前 kdtId + deviceSn + is_deleted=0，rootKdtId 和收款归属不参与命中。
• 收敛拉卡拉支付渠道错误链路，确认另一条链路里 retail-trademanager.queryEnabledBind 已返回终端 usable=true、status=enabled，问题不在终端绑定，而是继续收敛到支付资产/渠道配置或 deepLinkInfo 生成链路。
• 完成 PLU 739/738 一分差修复和审计，已按“改价重算金额与 PLU 总价相差 <=1 分时取 pluAmount”的口径落到 ProductEntity；继续审计发现营销 JS、本地购物车和预约开单等路径仍可能重新按单价 × 重量计算，需要补齐 pluAmount 透传和统一一分校验。
• 推进 ONLINE-981236 三方券尾差 RFC 和只读评审，确认正式 RFC 已写好并推送 codex/ONLINE-981236-rfc；评审中进一步确认 totalCouponPayAmount 挂在通用 transferResp/queryCoupon 明细上，不是只影响抖音券，平台分支、组合支付和降级回退还要继续核对。
• 对齐 Code Sentry 双召回 MVP 和 005 迁移口径，明确不做灰度，改为新旧召回始终双跑、只用全局 active_algorithm 控制注入；005 已从六表收敛为三表，删除冗余字段和索引，统一 updated_at，聚焦测试 12/12 通过。
• 梳理 Code Sentry 召回观测和记忆沉淀页展示，完成分页列表、行内展开、应用/发布单/任务号/标题搜索，以及阶段和差异结果筛选；同时确认“分析”列只取简要分析，不再用建议动作兜底，避免页面语义混在一起。
• 补齐 POS workspace 文档和前端应用接入说明，README 已同步 20 个 submodule、retail-node-setting、retail-pc-prepaid 等前端应用职责，以及储值、拉卡拉终端、交班日结、打印等 skill 路由；make check-workspace 通过并已推送 master。

🧩 困难/需要帮助

• 拉卡拉问题还需要继续补齐资产侧分配对象、支付渠道配置和 deepLinkInfo 生成证据，尤其要把“总部收款”和“当前下单门店校验”两个口径分开，避免后续排查误判。
• PLU 金额链路仍要继续对齐 PC、网关、本地购物车和营销 JS，核心是所有入口都能稳定使用 pluAmount，并保持 <=1 分取标签金额、>1 分阻断的边界一致。
• Code Sentry 双召回目前更适合按 MVP 测试验证，生产前还需要确认 001-005 迁移执行、表结构/索引校验和线上 checksum 边界。

💭 感想

今天主要是在把拉卡拉和 PLU 两条链路继续往真实校验口径上收，很多问题不是“有没有配置”或“有没有金额”，而是谁作为当前门店、哪个字段能代表真实金额。

Code Sentry 这边也从大而全灰度收回到最小 MVP，先让表结构、页面展示和注入开关都变小变清楚，后面上线风险会更可控。

最近这段时间，我在 Codex 里反复做的一类事，不是单纯让 AI 写代码，而是把它丢进更真实的研发场景里：

• 看 JIRA
• 找 trace
• 查日志
• 理解业务链路
• 判断根因
• 必要时改代码
• 再做 CR 和验证

这件事越做越能说明一个问题：JIRA 排障不是一个问答题，而是一条会分叉、会失败、需要回环的工程链路。

如果只是把 JIRA 描述贴给模型，让它“分析一下”，它大概率能写出一段看起来很像结论的话。但只要 trace 不完整、日志不直接、业务上下文缺失，结论就很容易变成“语言上很顺，证据上很虚”。

所以我这轮更关注的不是 prompt 写得多漂亮，而是 agent harness 到底该怎么搭，才能让 AI 从“会猜”变成“会查、会问、会验证”。

一、这段时间主要做了什么

从最近的 Codex 对话记录看，主线其实很清楚：

这里面最关键的不是某一次具体 JIRA，而是整个思路发生了变化。

以前更像是：

1

JIRA -> 让 AI 分析 -> 生成结论

现在更像是：

1

JIRA -> 线索抽取 -> trace / 日志 / 代码 / 知识检索 -> 追问补证据 -> 根因假设 -> 验证 -> 修复 / 收口

这两者差别很大。

前者是“回答系统”，后者才更接近“排障系统”。

二、为什么 JIRA 排障不能只靠一个大 Prompt

JIRA 的难点在于，它经常不是信息充分的输入。

一个真实问题单里可能只有：

• 用户说某个按钮点了没反应
• 一张截图
• 一个时间点
• 一个店铺 ID
• 一个接口报错片段
• 或者只有一句“线上有问题，帮看下”

这时候如果模型直接输出结论，本质上是在补脑。

更合理的方式应该是先判断证据是否足够：

我这次看 Airbag 和 NVWA 的差异，最大的感受就是：

好的 harness 不会催着模型马上回答，而是会逼它先把证据链补齐。

这也是为什么我对“没有 trace 的 JIRA 怎么分析”这个问题很敏感。无 trace 并不代表不能分析，但它一定意味着流程要换挡：从“顺 trace 找根因”切到“先构造线索，再逐步缩小范围”。

三、一个更靠谱的 JIRA Agent Loop

我现在更倾向于把 JIRA 排障拆成一个 loop，而不是一条直线。

  flowchart TD    A["JIRA 输入"] --> B["抽取线索<br/>应用 / 时间 / 店铺 / trace / 关键词"]    B --> C{"证据是否足够？"}    C -- "足够" --> D["查 trace / 日志 / 代码"]    C -- "不足" --> E["生成追问或反查策略"]    E --> B    D --> F["形成根因假设"]    F --> G{"能否验证？"}    G -- "能" --> H["验证假设"]    G -- "不能" --> E    H --> I{"需要修复？"}    I -- "需要" --> J["改代码 / 补测试 / CR"]    I -- "不需要" --> K["输出结论与证据"]    J --> L["复查与收口"]    L --> K  

这里最重要的是两个判断点：

1. 证据是否足够
2. 根因是否可验证

很多 AI 排障失败，不是因为模型不会分析，而是因为系统没有给它这两个刹车点。
它会在证据不足时继续往前写，在验证没完成时提前收口。

我现在觉得，一个面向真实研发的 JIRA Agent，至少要有下面几种能力：

• 线索抽取能力：从问题单里抽出应用、接口、时间、店铺、错误码、traceId。
• 工具编排能力：按需调用 JIRA、日志、Trace、RDS、代码搜索、Dubbo 等工具。
• 证据分级能力：区分“日志事实”“代码事实”“业务推断”“待确认假设”。
• 追问能力：信息不足时不要硬编结论，而是生成最小追问。
• 回环能力：验证失败后回到前面补线索，而不是直接结束。

这就是我理解的 JIRA Agent Loop。

四、Airbag 给我的启发

Airbag 最值得学的地方，不是某个具体命令，而是它把 JIRA 排障拆成了更稳定的工程步骤。

我关注的几个点是：

• 它如何从 JIRA 里拿到 trace 线索
• 它如何判断关联仓库和应用
• 它如何把问题单、日志、代码上下文串起来
• 它如何避免只靠单轮 LLM 输出结论

这里面有一个特别重要的设计思想：

LLM 不应该独自承担所有判断，harness 要把可确定的工程动作先做掉。

比如：

• 能用 API 拿到的 JIRA 字段，不要让模型猜。
• 能用日志查询拿到的错误片段，不要让模型编。
• 能用代码搜索定位的类和方法，不要只让模型按关键词幻想。
• 能用测试集复跑的问题，不要只看一次输出好不好看。

这也是我后面看 NVWA 时最在意的地方：不是它能不能调用 Claude SDK，而是它有没有把“该查什么、怎么查、查不到怎么办、什么时候停下来问人”这些动作设计清楚。

五、NVWA 目前暴露的问题

这轮测试里，我对 NVWA 的直观感受是：它已经具备做 JIRA agent 的雏形，但问题也比较明显。

1. 结论容易来得太早

有些场景里，SDK 还没跑完，AI 就已经给出了“一句话总结”。这会带来一个很大的风险：

用户看到的是结论，但背后的 trace、业务知识和代码证据其实还没完成。

这类问题不是简单调高模型能力就能解决的，它需要 harness 在状态机上约束：

• 分析未完成时不能输出最终结论
• 工具调用失败时必须标记证据缺口
• 关键链路未验证时只能输出阶段性判断

2. 无 trace 场景需要单独流程

没有 trace 的 JIRA 不能走同一套模板。

它应该先进入“问题补全模式”：

• 识别业务对象
• 推断可能应用
• 按时间窗查日志
• 找接口、任务、消息、配置等可能入口
• 输出待确认字段

如果一开始就套“trace 分析模板”，最后很容易变成假装有证据。

3. Prompt 不能只写得更长

Prompt 优化当然有用，但我现在更倾向于把它拆成多段：

如果所有事情都塞进一个大 prompt，模型会更难遵守阶段边界。

六、我沉淀下来的几个原则

这轮实验之后，我对 JIRA / Trace 类 agent 有几个更明确的判断。

1. 先做证据链，再做表达

很多 AI 输出看起来“像那么回事”，但真正有价值的是背后的证据链。

所以报告结构应该优先包含：

• 结论
• 证据
• 推断
• 未验证点
• 下一步动作

而不是只给一个漂亮的摘要。

2. Harness 比模型更决定下限

模型决定上限，harness 决定下限。

一个好的 harness 会让模型少犯低级错：

• 不会在没查日志时假装查过
• 不会把猜测写成事实
• 不会跳过代码定位
• 不会忘记验证修复

这类稳定性，比单次回答惊艳更重要。

3. 排障 Agent 必须有“不会就问”的能力

真实工程里，信息不足是常态。

一个成熟 agent 不应该把“问用户补充信息”当成失败，而应该把它当成正常分支。关键是问得少、问得准、问得有依据。

比如不要泛泛地问“请提供更多信息”，而应该问：

• 这个问题发生的准确时间窗口是什么？
• 有没有店铺 ID、订单号或用户 ID？
• 线上环境是 prod、pre 还是 QA？
• 你看到的错误截图对应哪个操作入口？

这才是有用的追问。

4. 最终目标不是“会分析”，而是“能闭环”

我现在判断一个 JIRA agent 有没有价值，不看它能不能写一段很长的分析，而看它能不能闭环：

1. 找到线索
2. 查到证据
3. 定位根因
4. 判断是否要改
5. 改完验证
6. 输出可追溯结论

只完成前两步，最多算辅助排查。
能把后面也串起来，才更像真正的研发 Agent。

七、下一步我想怎么改

如果继续优化 NVWA / Airbag 这条线，我会优先做四件事。

1. 把 JIRA 集变成固定评测集

我已经开始把 6 月份的一批 JIRA 当作测试集。后面应该把它们按类型分层：

• 有 trace 且根因明确
• 无 trace 但有时间窗
• 只有业务描述
• 需要跨应用定位
• 需要代码修复
• 只需要业务解释

这样才能比较每次 prompt 和 harness 改动是不是真的变好。

2. 把输出拆成阶段产物

不要让 agent 一上来就生成最终答案。

更合理的是每个阶段都有结构化产物：

• 线索卡
• 检索计划
• 证据表
• 根因假设
• 修复建议
• 最终报告

这样人也更容易介入检查。

3. 给无 trace 流程单独建 skill

有 trace 和无 trace 是两类任务。
它们不应该共用同一个工作流。

无 trace JIRA 更像“问题侦查”，需要先从业务对象、时间窗、入口路径和应用归属里反推。

4. 把 CR 和验证接进同一条链路

排障不是找到根因就结束。

如果要改代码，后面必须继续接：

• 影响面分析
• 单元测试或集成测试
• 代码审查
• 复查日志
• 输出修复说明

这也是我为什么一直把 jira-one-click、jira-trace-fix-cr、author-final-review 这些东西放在一起看。它们本质上不是多个孤立工具，而是一条研发闭环的不同节点。

结尾

这段时间做 JIRA 和 Trace 自动化，最大的收获不是“AI 能不能帮我看问题”，而是我更清楚地看到了 agent harness 的价值。

排障这类任务天然复杂：输入不完整、证据分散、路径会分叉、结论需要验证。
如果只靠一个大 prompt，AI 很容易变成一个会写总结的猜测器。
如果把 JIRA、Trace、日志、代码、业务知识、追问和 CR 串成 loop，它才有机会变成真正能参与研发闭环的助手。

所以我现在对这类系统的判断标准也更直接：

不要看它能不能说出一个像样的结论，要看它能不能把证据一步步查出来，并且在证据不足时知道停下来。

这才是 JIRA Agent 真正该追求的方向。

这半年我越来越强烈地感觉到一件事：

AI Coding 真正的分水岭，已经不只是“模型够不够强”，而是“你有没有办法把合适的方法，在合适的时机交给它”。

很多人第一次接触 Skill，会觉得它只是另一种 Prompt 封装。
但如果你真的在 Claude Code、Codex、Cursor 这类工具里持续做开发，就会发现 Skill 解决的问题，比“保存几段提示词”要大得多。

它在解决的是：

• 如何减少每次都重复灌上下文
• 如何让 AI 在对的阶段进入对的工作流
• 如何把个人经验变成团队可以复用的能力
• 如何把分析、开发、审查、排障、文档这些动作串成闭环

这篇文章，我想把 Skill 这件事完整讲透，尽量做到既能扫盲，也能落地。

文章会分成四层：

1. Skill 为什么会出现
2. Skill 的核心原理和机制是什么
3. Skill 和 Rules / Commands / MCP 到底怎么分工
4. 结合我自己的 dev-skill 仓库，看看它在真实研发流程里能做什么

本文内容结合了我在 2026 年 6 月 9 日 的内部分享文档《门店后端AI学习分享-Agent Skill 工作流》，以及当前 dev-skill 仓库中的实际 Skill 设计与目录结构整理而成。

一、为什么会有 Skill

如果你经历过 AI Coding 从早期到现在的演进，会发现大家一直在解决同一个问题：

怎么把合适的信息，在合适的时机，放进模型的上下文里。

一开始最常见的做法，是写 Rules。

比如：

• 这个仓库的业务背景是什么
• 编码规范是什么
• 哪些坑不能踩
• 哪些目录不能乱改

这些东西一开始很有用，因为它能明显减少模型幻觉。

但问题也很快出现了：

• Rules 越写越长
• 很多规则只在特定任务下才相关
• 它们却会在每次对话里都被加载
• token 消耗会越来越高

尤其是在真实项目里，你很容易遇到这种情况：

• 查日志时不需要开发规范
• 画架构图时不需要数据库排障说明
• 写文档时不需要完整编码规则
• 只做链路分析时，不应该每次都把 2000 token 的开发 rules 带上

这就是 Skill 出现的背景。

Skill 的第一性价值

如果把它压成一句话，我会这样定义：

Skill 的本质，是把原来“总是加载”的静态上下文，改造成“按需加载”的动态上下文。

也就是说，Skill 不是单纯多了一个文件格式，而是在改变上下文管理方式。

它追求的是：

• 先只暴露极少量的索引信息
• 让 Agent 判断是否相关
• 真正需要时，再加载完整方法
• 更深的资料和脚本，继续延后到需要的时候再读或再执行

这就是它最关键的思想：渐进式披露。

二、什么是 Skill

通俗一点讲，Skill 可以理解成：

一份带名字、带描述、带操作说明、还能挂资源和脚本的能力模块。

它通常至少包含两层内容：

1. 元数据：name、description
2. 正文：SKILL.md 里的工作流、约束、步骤、触发条件

更完整一点的 Skill，还会带上：

• references/：参考文档、模板、补充说明
• scripts/：脚本、校验器、同步器、自动化工具
• assets/：图片、模板、静态资源

所以一个 Skill 不只是“告诉 AI 该说什么”，更像是：

给 AI 一份“这类任务应该怎么做”的可执行说明书。

三、Skill 的核心原理：渐进式披露

这是 Skill 最值得理解的地方。

很多人第一次听这个概念，会觉得有点抽象。
其实你可以把它想成翻一本手册：

• 平时只看目录
• 需要时再翻章节
• 实在要落地，再去查附录和工具

在 Skill 体系里，大致可以分成三层。

第一层：目录层

这一层通常就是 name + description。

它的特点是：

• 始终可见
• 很短
• token 消耗很低
• 作用是告诉 Agent：“现在有哪些能力可以选”

这一步本质上是在做能力发现。

第二层：章节层

这一层是 SKILL.md 的正文。

它的特点是：

• 只有在 Skill 被判断相关后才加载
• 主要描述 SOP、约束、流程、边界
• 让 Agent 知道“这类事应该怎么推进”

比如：

• 先检查项目上下文
• 再问澄清问题
• 再产出方案
• 再拆任务
• 最后才进入实现

第三层：附录层

这一层通常是：

• references/
• scripts/
• 模板文件
• 外部数据

它的特点是：

• 不是一开始就读
• 需要的时候才展开
• 有些内容甚至不用进上下文，直接执行脚本就行

这一步很关键，因为它让 Skill 的能力不再只停留在 Prompt，而是开始连接真实文件系统和自动化动作。

一张图看懂 Skill 的三层结构

  flowchart TD    A["元数据<br/>name + description"] --> B["SKILL.md 正文<br/>流程、约束、SOP"]    B --> C["references/<br/>模板、补充文档、案例"]    B --> D["scripts/<br/>校验、同步、查询、自动化执行"]    C --> E["按需继续加载"]    D --> F["按需执行，不必全进上下文"]  

这套设计的好处非常直接：

• 平时只花很少 token 看目录
• 触发后才读方法正文
• 复杂资源进一步延迟加载
• 脚本可以直接干活，减少模型硬记细节

如果你做过大项目，就会知道这件事有多重要。
因为上下文预算永远是稀缺资源。

四、Skill 和 Rules、Commands、MCP 到底有什么区别

这是最容易混淆的一组概念。

我现在更倾向于把它们看成同一条链路上的不同层。

1. Rules：静态长期背景

Rules 适合放这种内容：

• 仓库总原则
• 通用编码规范
• 业务红线
• 不变的团队约定

它的优点是稳定，缺点是会被反复加载。

2. Commands：手动触发的静态入口

Commands 更像是：

• 一段你希望随叫随到的固定操作模板
• 一条快捷工作流入口

比如：

• /openspec-proposal
• /openspec-apply

它解决的是“重复手动输入”的问题，但本质上仍偏静态。

3. MCP：真实工具与系统接入

MCP 的重点不是“告诉 AI 怎么想”，而是“让 AI 真能做事”。

它可以负责：

• 查日志
• 调数据库
• 调第三方 API
• 操作 GitHub、飞书、Jira
• 访问浏览器、桌面、文件系统

所以 MCP 更像工具层。

4. Skill：方法层与工作流层

Skill 的重点是：

• 什么时候该做什么
• 做这类事应该遵循什么顺序
• 该用哪些资源、哪些脚本、哪些 MCP

所以它更像方法层。

一句话区分

你可以这么记：

• Rules 负责长期背景
• Commands 负责快捷入口
• MCP 负责工具能力
• Skill 负责方法编排

Skill 和 MCP 不是替代关系

这一点特别重要。

很多人会问：

Skill 和 MCP 不都是“给 AI 增强能力”吗？

表面看像，但本质不同。

我更认同这个说法：

MCP 把 Claude / Codex 连接到数据和系统；Skill 教会它如何处理这些数据、何时调用这些系统。

也就是说：

• Skill 决定“怎么做”
• MCP 决定“能做什么”

两者组合起来，效果才最好。

  flowchart LR    U["用户任务"] --> S["Skill<br/>决定流程与方法"]    S --> M["MCP / Scripts / Tools<br/>执行真实动作"]    M --> R["结果返回"]    R --> S  

五、Skill 能做什么

如果只把 Skill 理解成“写作提示词模板”，会低估它很多。

在真实研发里，Skill 至少能覆盖下面几类事情。

1. 做需求澄清和方案设计

比如我仓库里的：

• brainstorming

它不是单纯让 AI 多问几个问题，而是把“需求澄清 -> 方案对比 -> 分段确认 -> 落文档”的流程固定下来。

2. 做开发流程编排

比如：

• sdd-intelligent-router
• sdd-dev-workflow
• dev-lifecycle

它们解决的是：

• 什么任务该快速直做
• 什么任务该走 Spec 驱动开发
• 技术方案、提案、实现、测试如何串起来

3. 做代码质量保障

比如：

• author-final-review
• code-review
• full-review
• integration-test

这里 Skill 不只是“帮你看看代码”，而是把影响面分析、代码质量审查、测试建议变成标准输出。

4. 做线上排障与系统查询

比如：

• zan-dev-flow
• zan-log-query
• zan-rds-ops
• zan-redis-query
• zan-apollo-query
• zan-dubbo-invoke

这些 Skill 已经非常接近“半自动排障助手”了。

5. 做文档与协同系统打通

比如：

• feishu-wiki-skill
• project-writer
• diagram-creation

它们能把文档读写、图表生成、Markdown 同步、图片分析这些动作接起来。

6. 做团队级协作与多 Agent 编排

比如：

• vibe-working-agent-team

它已经不是单点技能，而是在组织角色分工、tmux 分屏和交付节奏。

所以从结果上看，Skill 可以做的事情远比“一个提示词”丰富得多。

六、结合我的 dev-skill 仓库，Skill 是怎么落地成体系的

说抽象概念容易，但真正有意思的，是它怎么落地。

我自己的 dev-skill 仓库，核心定位非常明确：

一次维护，多端同步，把高频研发流程沉淀成可复用的 Skills，并统一分发到 Cursor、Claude Code、Codex，甚至 OpenClaw 兼容层。

1. 它不是“零散技能集合”，而是一个 source of truth

在这个仓库里，dev-skill 本身是技能源码仓。

也就是说：

• 日常开发在这里改
• 团队共享从这里同步
• 常用 Skill 通过 profile 安装
• 与其他分发仓通过脚本和 manifest 对齐

这很重要，因为 Skill 一旦多起来，如果没有“单一事实来源”，很快就会失控。

2. 它是分层组织的

仓库当前把 Skills 分成几类：

• skills/dev/：开发流程类
• skills/cr/：代码审查与测试类
• skills/writing/：文档与图表类
• skills/zan/：排障和内部工具链
• skills/lark/：飞书协同能力
• skills/helm/：技能治理类
• skills/platform/：安装、统计、团队协作等平台能力

这种分类不是为了好看，而是为了降低认知成本。
你看到目录，大致就知道能力落在哪一层。

3. 它支持跨工具同步

dev-skill 不是只服务一个 IDE。

当前这套仓库可以同步到：

• ~/.cursor/skills
• ~/.claude/skills
• ~/.codex/skills.union 与 ~/.codex/skills
• ~/.openclaw/skills

这意味着同一套 Skill 设计，可以在多个 Agent Harness 里复用。

这一点对团队推广特别关键，因为否则你会陷入：

• Cursor 一套
• Claude 一套
• Codex 再来一套

最后维护成本会非常高。

4. 它不是只管分发，还管治理

这是我很看重的一点。

仓库里不只是有业务 Skill，还有治理 Skill，比如：

• skill-usage-tracker
• skill-creator
• skill-publish
• knowledge-distiller
• auto-installer

这说明一件事：

Skill 系统一旦进入团队，就不只是“写几个好玩的 Prompt”，而是要进入完整的生命周期管理。

也就是：

• 怎么创建
• 怎么安装
• 怎么追踪使用
• 怎么发布
• 怎么沉淀经验

这是 Skill 从“玩法”走向“基础设施”的标志。

七、从几个代表性 Skill 看它的真实价值

这一段我想直接拿仓库里的 Skill 举例，因为这样比抽象定义更有说服力。

1. brainstorming：把“先想清楚”写成工作流

这个 Skill 的核心思想非常简单，但非常重要：

不要一上来就写代码。

它会要求 Agent：

1. 先看项目上下文
2. 一次只问一个关键问题
3. 给出候选方案和取舍
4. 分段展示设计并确认
5. 最后写成设计文档

这其实是在把优秀工程师的思考顺序显式化。

2. sdd-dev-workflow：把 Spec-Driven Development 做成可执行流水线

这个 Skill 更进一步。

它不只是“按方案开发”，而是把下面这些动作串起来：

• 找技术方案
• 提取能力点
• 匹配相关应用
• 创建 OpenSpec 提案
• 等待用户确认
• 按任务顺序实施开发

这已经不是单个 Prompt 能承担的事情了，而是完整的流程编排。

3. full-review：把代码审查做成组合技能

从仓库设计上看，full-review 不是一个孤立技能，而是把多个审查能力组合起来。

它通常会串联：

• 影响面分析
• 代码质量审查
• 测试建议生成

这说明 Skill 的价值不只是“单点能力”，还包括能力编排。

4. zan-dev-flow：把排障入口统一起来

这类 Skill 很适合内部研发场景。

用户不需要先自己决定：

• 该查日志
• 该查 Redis
• 该查 HBase
• 还是该查 Apollo

而是先从一个统一路由入口进去，再分发到原子能力。

这和前面说的 Skill 负责方法层，MCP 负责工具层 非常契合。

5. feishu-wiki-skill：Skill 不只是“会想”，还应该“会干”

这个 Skill 很有代表性，因为它不仅有说明文档，还有成体系的脚本：

• 读取 wiki/docx/bitable
• 下载并分析图片
• 把 Markdown 同步到飞书文档
• 渲染 Mermaid 后上传

这说明 Skill 最强的形态，不是纯文本，而是：

文档方法 + 资源说明 + 脚本执行 + 外部系统接入

6. vibe-working-agent-team：Skill 可以上升到多角色协作

这个 Skill 已经开始组织：

• 多角色分工
• tmux 多窗口
• Team Lead 协调
• PRD -> 方案 -> 开发 -> CR 的交付路径

它让我越来越确信一件事：

Skill 的上限，不是“某个任务怎么做”，而是“一个团队如何协作完成任务”。

八、Skill 的几种关键机制

如果你想真正写好 Skill，光知道概念还不够，还得理解它常见的机制设计。

1. 触发机制

Skill 一般有两种触发方式：

• 主动触发：用户点名 Skill
• 被动触发：用户只描述意图，由 Agent 判断该用哪个 Skill

这意味着 Skill 不只是“被调用”，还需要“可发现、可匹配”。

所以 name 和 description 往往特别重要。

2. 渐进式加载机制

这就是前面说的三层披露：

• 目录层
• 正文层
• 资源层

Skill 设计得越好，越不会一开始就把所有东西灌进上下文。

3. 组合与依赖机制

很多大 Skill 本身不会单干，而是组合别的 Skill。

比如仓库里的依赖关系就很典型：

• sdd-intelligent-router 会路由到 ai-pair-programmer 和 sdd-dev-workflow
• sdd-dev-workflow 本身依赖其他开发类能力
• full-review 会串起 review 与测试相关 Skill
• zan-dev-flow 会分发到日志、缓存、数据库等原子能力

这说明 Skill 系统并不是平铺的，而是一个图。

4. 资源外置机制

很多重要信息不适合都写进 SKILL.md。

更好的做法是：

• 流程放正文
• 长说明放 references/
• 自动化动作放 scripts/

这样既减少上下文噪音，也方便复用和维护。

5. 治理与观测机制

这个机制经常被忽略，但团队化后非常重要。

比如我的仓库里就有：

• skill-usage-tracker

它会记录：

• 哪个 Skill 被用了多少次
• 最近一次是什么场景
• 哪些 Skill 真正高频

这会反过来影响后续治理，比如：

• 哪些 Skill 值得继续打磨
• 哪些 Skill 应该合并
• 哪些 Skill 实际没人用

九、Skill 设计里，我觉得最有价值的几个经验

写到这里，我其实更想分享一些实践感受。

1. Skill 不是“把 Prompt 存起来”

真正好的 Skill，核心不是文案，而是：

• 决策顺序
• 任务边界
• 信息加载节奏
• 资源组织方式

Prompt 只是表层。

2. Skill 越贴近真实工作流，价值越大

最有价值的 Skill，往往不是那种“万能专家 Prompt”，而是：

• 需求澄清 Skill
• Spec 驱动开发 Skill
• 审查闭环 Skill
• 排障路由 Skill
• 文档同步 Skill

因为这些东西本来就在团队里高频出现。

3. Skill 的核心复利在于经验沉淀

这件事我现在越来越确定。

一个团队真正有复利的，不是每个人都临场发挥得多聪明，而是：

能不能把做过十次、踩过十次坑的事情，沉淀成第十一次可以直接复用的方法。

Skill 恰好就是这种经验的载体。

4. Skill 最终会走向“Prompt + Tool + Workflow + Governance”

如果只看现在，很多人会觉得 Skill 还处在早期。

但从趋势上看，我认为它一定会继续往这几个方向发展：

• 更强的自动触发
• 更清晰的依赖图
• 更成熟的 Skill 市场
• 更标准的治理与分发机制
• 更深的 MCP 和脚本联动

换句话说，Skill 不会停留在“方便写 Prompt”这个层面。

它更像是 Agent 时代的方法资产格式。

十、如果你要开始搭自己的 Skill 系统，我建议怎么做

最后给一个更务实的建议。

如果你准备在自己的团队里推广 Skill，我不建议一上来就做几十个。

更稳的路径通常是：

第一步：先找高频且稳定的任务

比如：

• 需求澄清
• 技术方案写作
• 代码审查
• 日志排障

这些任务的共同点是：

• 高频
• 有固定结构
• 容易标准化

第二步：先把方法写成 Skill，不要急着全自动

一开始最重要的，不是“写多厉害的脚本”，而是先把：

• 顺序
• 边界
• 输入输出

定义清楚。

第三步：再把资源和脚本往外挪

等 Skill 稳定后，再逐步补：

• references/
• scripts/
• 模板
• MCP 接入

第四步：最后再做治理

也就是：

• 安装
• 统计
• 发布
• 沉淀

这样做，系统会稳很多。

十一、最后一句话：我为什么觉得 Skill 值得认真做

因为它解决的不是一个“小技巧”问题，而是一个“AI 如何真正进入工作流”的问题。

过去很多人用 AI，像在和一个聪明聊天机器人对话。
但当你开始把：

• 规则
• 方法
• 工具
• 资源
• 治理

这些东西组合起来以后，AI 才会开始更像一个真正能协作的执行系统。

而 Skill，正是这条路上非常关键的一层。

它让我们第一次可以比较系统地回答这个问题：

怎么把个人经验，变成团队可复用、可维护、可组合、可演进的 Agent 能力。

这也是为什么我越来越愿意把 dev-skill 这种仓库，看成一种新的研发基础设施，而不只是“AI 时代的提示词收藏夹”。

延伸阅读

• 如果你想看一篇更偏实操的 Superpowers 使用说明，可以读 Superpowers使用指南：把Claude Code和Codex变成真正会按流程工作的开发Agent。
• 如果你想看多 Agent 和 tmux 分屏怎么落成协作流水线，可以读 Agent Team使用教程：用Tmux分屏把多个AI串成自动协作流水线。
• 如果你想看一次真实的分析、开发、审查闭环，可以读 Claude Code Agent Team协作全记录：3个AI如何串起需求、开发与审查闭环。
• 如果你想继续往底层理解 harness、memory、skill 的工程结构，可以读 Claude Code Harness深度分析：从RAG、Skill、Memory到企业Agent落地。

原始内容整理自飞书文档：Claude Code Agent Team 协作全记录。本文已按 Hexo 博客格式重构，并将飞书中的字符画流程图改写为 Mermaid。

三个 AI，一条心，从需求到代码到审查，全自动串联工作流。

这篇文章记录的是一次很典型、也很有代表性的多 Agent 协作实战：一个需求进来后，不再由单个 AI 从头干到尾，而是拆成三个角色分别负责分析、开发和审查，然后在 Team Lead 的协调下，串成一条完整闭环。

如果只看一句话，这次实验验证的是：

AI 真正有价值的地方，不只是“会写代码”，而是能不能把分析、实现、审查、修复和验证这一整条链路接起来。

一、先看全景

1. Team 角色分工

  flowchart LR    analyst["🟩 analyst<br/>需求分析专家<br/>brainstorming<br/>Tmux %2"]    developer["🟨 developer<br/>代码实现专家<br/>sdd-dev-workflow<br/>Tmux %3"]    reviewer["🟦 reviewer<br/>代码审查专家<br/>full-review<br/>Tmux %1"]    lead["🫵 Team Lead<br/>就是本 AI"]    lead --> analyst    analyst --> developer    developer --> reviewer    reviewer --> lead  

2. 一张表看懂这支 Team

二、这次任务是什么

用户原始需求非常直接：

“新增一个预约单完成以后会发 NSQ topic：booking_appointment_completed。进行消息推送。”

翻译成更业务化的话，就是：

预约做完了，要给商家发一个通知。

这看起来像一个小需求，但一旦往工程里落，就会立刻带出一串问题：

• 事件从哪里来
• 用哪条消费链路接
• 如何复用已有通知架构
• 是否会有重复消息
• 异常怎么兜底
• 配置降级怎么做
• 改完之后怎么确认没有副作用

也正因为如此，这种任务很适合用来验证多 Agent 串联工作流是否真的能跑通。

三、三类 Skill 是怎么配合的

1. brainstorming：先把需求想清楚

这是 analyst 的核心工具，重点不是直接产出代码，而是先把问题想清楚。

本次实战里，analyst 主要完成了三件事：

• 识别核心功能：预约完成通知推送
• 设计技术方案：复用现有消费者架构
• 发现 4 类风险：事务丢失、消息重复、异常处理、配置降级

2. sdd-dev-workflow：按规范把代码写出来

这是 developer 的核心工具，强调的是规范化和工程化，而不是“想到哪写到哪”。

本次实战里，developer 交付了这些结果：

• 创建 OpenSpec 提案，形成 13 个任务
• 实现预约完成消费者与订阅器
• 补充单元测试，新增 4 个用例

3. full-review：把质量关守住

这是 reviewer 的核心工具，目标不是“简单看一眼”，而是系统性地扫出问题。

本次实战里，reviewer 的产出是：

• 第一轮审查发现 1 个 High 和 2 个 Medium 问题
• 推动修复闭环继续向下执行
• 第二轮复审确认问题已解决
• 输出完整审查报告

4. 三个 Skill 放在一起，形成的不是功能集合，而是工作流

  flowchart TD    req["用户需求输入"] --> a["🟩 analyst<br/>brainstorming"]    a --> d["🟨 developer<br/>sdd-dev-workflow"]    d --> r["🟦 reviewer<br/>full-review"]    r --> check{"发现问题？"}    check -- "是" --> loop["进入修复闭环"]    check -- "否" --> done["🎉 交付完成"]    loop --> a  

这张图最关键的点在于：

• 需求不是直接丢给开发
• 开发完成不代表流程结束
• 审查结果会反向驱动修复
• 修复完成后还会再次回到审查

也就是说，这不是线性流水线，而是一条可以回环的链路。

四、完整协作流程是怎么跑起来的

第一幕：需求分析

流程的第一步，是由 Team Lead 把需求派发给 analyst。

analyst 启动 brainstorming 后，主要完成以下动作：

• 理解这次需求到底要解决什么问题
• 判断是否可以复用现有消费者架构
• 识别实现过程中的关键风险
• 输出一份结构化的需求分析结果

这一阶段的价值不在“写了什么文案”，而在于它把原本藏在人脑里的隐性判断显式化了。

第二幕：代码实现

拿到分析结果后，developer 启动 sdd-dev-workflow，正式进入开发阶段。

这一阶段不是直接开写，而是先：

1. 创建 OpenSpec 提案
2. 生成变更目录和任务清单
3. 跑 openspec validate --strict
4. 按任务顺序推进开发

随后才进入具体编码，实现：

• Scene.COMPLETED 枚举
• AppointmentCompletedConsumer
• AppointmentCompletedSubscriber
• 对应单元测试

第三幕：代码审查

开发完成后，任务切换到 reviewer。

reviewer 启动 full-review 后，并不是简单给一句“LGTM”，而是进行系统性审查，包括：

1. 代码质量
2. 安全性
3. 性能
4. 架构
5. 兼容性
6. 测试覆盖
7. 错误处理
8. 配置管理
9. 依赖管理
10. 文档完整性

第一轮审查结果并不完美，发现了：

• 1 个 High 问题：硬编码维护风险
• 2 个 Medium 问题：测试覆盖不足、摘要格式不匹配

这也是这次实验最有意思的地方：流程没有停在“发现问题”，而是继续往下走。

五、真正关键的部分：自动修复闭环

1. 闭环是怎么工作的

  flowchart LR    issue["发现问题 ❌"] --> confirm["analyst 确认问题 🤔"]    confirm --> repair["developer 修复问题 🔧"]    repair --> recheck["reviewer 复审 ✅"]    recheck --> pass{"通过了吗？"}    pass -- "否" --> confirm    pass -- "是" --> done["🎉 广播完成"]  

2. 这次闭环里具体修了什么

在这次实战中，修复动作主要包括：

• 给 Scene 枚举新增模板字段
• 消除 switch-case 的硬编码风险
• 补充缺失的单元测试用例
• 统一消息摘要格式

修完之后，再次触发 reviewer 复审，确认：

• High 问题已解决
• Medium 问题已解决

这才算真正结束。

3. 为什么这个闭环比“AI 写完代码就停”更有意义

很多 AI 开发演示，只展示“从需求到代码生成”这一段，看起来很顺，但真实研发里最容易出问题的，恰恰是后半段：

• 写完以后有没有遗漏
• 改动有没有隐藏风险
• 问题发现后谁来确认
• 修完以后谁来验证

这次流程最有价值的地方，就是把这些后续动作也纳入了自动串联。

六、一张图看完整执行路径

  flowchart TD    user["用户需求"] --> analyst["analyst<br/>需求分析"]    analyst --> plan["📄 技术方案"]    plan --> developer["developer<br/>代码实现"]    developer --> code["💻 7 个代码文件"]    code --> reviewer["reviewer<br/>代码审查"]    reviewer --> report["📋 审查报告"]    report --> problem{"发现问题？"}    problem -- "YES" --> fix["闭环修复"]    fix --> analyst    problem -- "NO" --> finish["🎉 完成"]  

如果把它抽象成一句话，就是：

analyst 负责想清楚，developer 负责写出来，reviewer 负责看仔细，而 Team Lead 负责让这条链路不停下来。

七、最终交付了什么

1. 代码交付物

2. 过程文档产出

OpenSpec 提案

1
2
3
4
5

retail-trade-event/openspec/changes/
└── add-appointment-completed-notification/
    ├── CHANGELOG.md
    ├── manifest.json
    └── tasks.md

代码审查报告

1
2
3
4
5
6
7

.doc/appointment-completed-feature/
└── full-review-20260303-120000.md
    ├── 一、基本信息
    ├── 二、变更说明 + 架构图
    ├── 三、影响面分析 + 调用链路图
    ├── 四、问题清单
    └── 五、集成测试用例清单

协作总结文档

1
2
3

memory/
├── agent-team-collaboration-report.md
└── agent-team-collaboration-story.md

八、这套工作流的几个亮点

1. 自动发现问题

不是人工 review 才能往后走，而是 reviewer 可以主动把问题抛出来，继续驱动后续链路。

2. 自动确认修复

发现问题后，不是直接让开发盲改，而是先由 analyst 确认问题成立，再把修复任务交给 developer。

3. 自动验证闭环

修复动作做完后，不是默认“应该没问题了”，而是重新交回 reviewer 做复审。

4. 人工干预被压到最低

这次流程里，人工更多是做启动和协调，而不是每一步手动盯进度。只要框架搭好了，后面就可以顺着链路自己往前滚。

九、这次实战的性能数据

十、最后总结一下

Team 分别做了什么

Team Lead 做了什么

• 搭团队：创建 3 个 Agent，并配置各自 Skill
• 分任务：把需求按分析、开发、审查分段派发
• 协调流：推动“发现问题 -> 确认 -> 修复 -> 复审”
• 写报告：沉淀过程与结果

最值得记住的一点

这次实验最酷的地方，并不是“AI 会写代码”。

真正值得记住的是：

当 brainstorming、sdd-dev-workflow、full-review 这些 Skill 被串成一条工作流后，AI 开始不再只是一个点状工具，而更像一个能持续推进任务的协作系统。

换句话说，这套 Team 的意义，不在于把某一次需求做完，而在于它证明了一件事：

发现问题、确认问题、修复问题、验证修复，这整条闭环，是可以被多 Agent 协作稳定接住的。

十一、下一步还能做什么

这支 Team 后面还可以继续用在：

• 新需求开发
• Bug 修复
• 性能优化
• 文档补齐

只要任务边界足够清楚，角色足够明确，Skill 足够稳定，这种多 Agent 串联模式就可以继续往更复杂的研发场景延伸。

生成时间：2026-03-03
Team：dev-collaboration
模式：tmux + agent collaboration
Team Lead：就是本 AI

如果要用一句话总结我上半年在 AI 小组做的事情，那不是“我学会了怎么让 AI 帮我写代码”，而是：我开始从 AI Coding 往 AI Workflow 走了。

这半年做的事情表面上很散：写 skills、搭工作流、做 JIRA 修复闭环、沉淀项目记忆、研究 Agent 协作、写分享文档、搞安装和推广。但如果往回看，会发现这些事情其实都在围绕同一件事打转：怎么让 AI 不只是补一段代码，而是真正参与研发过程，并且这套能力不只我自己能用，团队也能直接接起来用。

说白了，我现在越来越不信“AI Coding 提效”这种太轻飘飘的说法了。提效当然有，但如果只是快写两段代码，价值其实没那么大。真正值钱的，是它能不能把分析、定位、方案、改码、审查、验证这一整条链路跑通。单点提效谁都能吹，工作流跑不跑得通，才决定这玩意到底是不是生产力。

而且这半年我还有一个很直接的感受：做一个 demo 不难，做一个自己用着爽的东西也不难，难的是把它做成别人愿意装、愿意用、用一次没骂人、用第二次还想继续用的东西。 这也是为什么我后面越来越关注产品形态、稳定性、可复制性，而不是继续沉迷在“我又搞出一个新 skill”这种短期爽感里。

这篇文章就想复盘一下，我上半年在 AI 小组到底做了什么，想清楚了什么，沉淀了什么，又踩了哪些坑。

这组复盘可以怎么读

这次我把最近一段时间在 Codex 里的 AI 研发实践整理成 5 篇文章。它们不是孤立的笔记，而是从“我做了什么”到“系统该怎么搭”的一条线：

如果只想快速了解我这段时间具体干了什么，先读第 1 篇和第 2 篇。
如果更关心 Agent 工程怎么搭，建议接着读第 3 到第 5 篇。

先看结论 📌

如果只用一张表来概括这半年，我大概会这样总结：

一、上半年到底在干什么？ 🧩

半年主线速览 🗺️

1. 先把最高频的两类事情做成标准工作流 ⚙️

上半年我投入最多精力的，其实是两类非常高频的研发场景：

• 日常需求开发
• JIRA 修复 / 问题排查

围绕这两类场景，后面逐渐沉淀出了两条主链路：

• daily-one-click
• jira-one-click

这两条链路最重要的一点，不是“把 AI 接进来了”，而是开始让 AI 参与完整链路，而不是只在最后一步写代码。

以前大家聊 AI coding，很容易把注意力放在“这段代码生成得快不快、准不准”。但真干活的时候会发现，最耗时间的根本不是敲代码，而是前面的那一大坨：

• 需求到底在说什么
• 问题到底出在哪
• 日志怎么查
• 边界怎么定
• 方案怎么收敛
• 改完之后影响面怎么判断
• 最后怎么验证和收口

所以我后面的方向就越来越明确：不再盯着让 AI 帮我省一段代码的时间，而是想办法让它把整条研发流程跑得更顺。

这件事说起来像常识，但真做起来完全不是那么回事。因为你会发现，代码只是最后露在外面的那一层，前面那些分析、判断、切换上下文、对齐边界的动作，才是真正把人耗死的地方。AI 如果只能碰最后那 10%，那它再强也就那样。

2. 把个人经验从“我会”变成“别人也能直接用” 🔁

如果一套东西只有我自己会用，那它最多算个人技巧，不算真正的沉淀。

所以这半年我一直在做的另一件事，就是把自己的经验往 skills 和 workflow 上抽。把原来靠感觉、靠经验、靠多轮对话才能跑通的事情，尽量变成可以复用、可以安装、可以推广的能力资产。

到现在为止，已经陆续沉淀了 40+ 工程化 skills，覆盖的内容大概包括：

• JIRA 分析与修复
• 日志排查
• 技术方案编写
• 需求结构化
• 应用扫描
• Spec 驱动开发
• Code Review
• Agent 协作流程
• 项目记忆与上下文管理

这背后我自己的判断也变了。以前会更在意“这个能力我有没有”，现在更在意的是：

这个东西别人能不能拿起来就用。

如果不能，那它还是太依赖人，不够像产品。

而且我中间其实也踩过一个挺典型的坑：很容易沉迷在“再做一个 skill”这件事本身。 因为做 skill 有即时反馈，能跑起来就会很爽，看着数量涨也会有成就感。但后来回来一看，发现如果没有统一入口、没有场景边界、没有安装方式、没有配套说明，那很多 skill 本质上只是“作者自己最懂”的半成品。

所以我现在会更警惕那种“技能数量越来越多，看起来很繁荣，实际上别人根本接不住”的状态。

3. 从个人提效，慢慢走到产品思维 🧠

这是我上半年挺明显的一个变化。

一开始做这些东西的时候，还是会比较自然地从“怎么提高我自己的开发效率”出发。但越往后做，越会发现如果真想往组内推广、甚至做成更通用的 AI 产品，判断标准就得变。

不能只看“我自己用着爽不爽”，而要看：

• 够不够简单
• 稳不稳定
• 能不能复制
• 团队能不能低成本接起来
• 这个产品形态别人愿不愿意接受

比如我后面写《告别传统：用 Vibe Working 标准化日常开发和 JIRA 修复流程》，本质上就不是在介绍某个 skill，而是在试着把一套 AI 研发方式包装成团队可以理解、可以安装、可以快速见效的产品。

这件事对我影响挺大的。因为它让我慢慢意识到，做一个“能演示”的 AI 东西不算难，难的是把它做成别人真的愿意长期用的东西。

很多东西你自己用的时候会自动脑补，但别人不会。你知道下一步该点哪、该看哪、该怎么失败重试，不代表别人也知道。所以产品思维这件事，说难听点，就是别老拿自己的熟练度骗自己。

4. 开始补 Agent 最难的那一块：项目理解能力 🧭

如果说前面的工作是在解决“让 AI 会做事”，那我后面越来越在意的是另一件更底层的事情：

AI 到底怎么才能理解项目？

很多时候 AI 效果不好，不是因为它不会写代码，而是因为它根本不理解当前上下文：

• 不知道这个项目有哪些模块
• 不知道业务边界在哪里
• 不知道哪些文档是关键上下文
• 不知道哪些经验是已经达成的共识
• 不知道应该先调哪个 skill、看哪个文件、走哪条路径

所以我后面开始主动补这方面的东西：

• RAG
• 多层 memory
• 项目记忆
• 渐进式披露
• Agent 工程评估
• 多 Agent 协作方式

我现在会觉得，这些东西才是真正决定 AI 能不能从“会聊天、会补代码”往“能参与项目协作”升级的关键。

说得再直接一点，很多 AI 产品现在最烦人的地方，不是它笨，而是它老失忆。你今天刚教会它，明天又像新来的；你刚总结完一轮共识，下一轮它又从零开始问。这个问题不解决，模型再强都容易停留在“偶尔惊艳、长期难用”的阶段。

二、几个让我印象很深的真实案例 💡

1. daily-one-click：不是帮我写，而是帮我把开发链路搭起来 🛠️

daily-one-click 这条线，最开始我想解决的并不是“让 AI 直接产出代码”，而是日常开发里前面那一长串容易散、容易断、容易来回反复的工作。

以前一个需求过来，人脑里其实会自动做很多切换：先理解需求，再澄清范围，再整理 PRD 或方案，再分析影响应用，再决定用什么开发方式，最后才是写代码。问题在于，这一套东西如果不沉淀，永远只能靠人顶着干。

daily-one-click 想做的事情，就是把这条链路尽量标准化，让需求从“我知道要干什么”，变成“AI 和人都知道下一步该怎么推进”。

这件事带来的最大变化，不是省了几分钟，而是让我开始把“开发”看成一个可以被编排的流程，而不是只靠熟练工经验硬顶。

而且这条线还有个很现实的价值：它能把很多原本藏在脑子里的默认动作摊开。以前你觉得“这不就是正常开发流程吗”，但真要让 AI 跑、让别人复用的时候，才会发现所谓“正常流程”里其实藏了大量默认知识，不拆出来就永远传不下去。

2. jira-one-click / jira-trace-fix-cr：AI 真正能打的地方是排障闭环 🚨

如果说哪条线最能体现 AI Workflow 的价值，我觉得还是 JIRA 修复这条。

因为排障这件事本来就不是纯代码问题，它天然就是一条长链路：

• 先看 JIRA 在说什么
• 抓关键词、时间窗、环境、应用线索
• 找 traceId
• 查日志
• 顺着调用链看根因
• 判断是配置问题、代码问题还是数据问题
• 如果要改代码，再继续走修复、CR、验证

这里面随便断一环，后面都跑不起来。

所以我后面比较坚定的一点就是：AI 最值得用的地方，不是让它凭空生成一坨代码，而是让它参与这种本来就很依赖上下文和步骤感的排障闭环。

尤其是像 jira-trace-fix-cr 这种思路，核心不是“帮我分析一下”，而是尽量别停在分析层，而是一路往下走到修复和收口。这一点我现在挺看重的，因为只分析不落地，很多时候意义没那么大。

说白了，JIRA 这种场景太适合拿来检验 AI 到底是不是生产力了。因为这里没法靠花哨输出混过去，链路断了就是断了，根因没找对就是没找对，修不了就是修不了。它很残酷，但也很诚实。

3. Dev-Skill 仓库：沉淀 skill 不是目的，能安装、能复用才是目的 📦

上半年还有一条比较重要的线，就是 Dev-Skill 仓库。

一开始沉淀 skills 的时候，很容易陷入一种爽感：做出来一个能用，做出来两个也能用，数量涨得很快，成就感也很强。但后面我慢慢发现，skill 多不等于体系强。

如果这些 skill：

• 只有我知道怎么触发
• 只有我知道适合什么场景
• 只有我知道和别的 skill 怎么配合
• 别人装上以后还是不会用

那它本质上还是“个人能力外挂”，不是团队资产。

所以我后面越来越在意 Dev-Skill 仓库的另一面：

• 能不能安装
• 能不能统一维护
• 能不能被龙虾这类 Agent 直接消费
• 能不能形成迭代机制
• 能不能被团队拿去复用

这也是为什么我会越来越把“skill 仓库”看成一个产品，而不只是一个文件夹。

而且这里还有个反直觉的地方：东西越多，不一定越强，很多时候反而越乱。 后面我明显感觉到，workspace 里的 skill、本地 skill 一多，Codex 会出现误触发和不触发的情况，这其实已经和 skill 最开始想强调的“渐进式披露”打架了。所以我现在很明确，后面不能再无脑堆技能了，必须补路由。

4. 项目记忆：我越来越觉得这是决定 AI 上限的关键 🧠

还有一条我自己越来越笃定的线，就是项目记忆。

很多时候你会觉得 AI 这次回答不错、下次又不行，不稳定得很烦。再往下拆，最后会发现很多问题不是模型本身抽风，而是它每次都像重新入职。

它不知道：

• 你这个项目之前怎么做过
• 哪些结论已经讨论过
• 哪些约定其实是默认共识
• 哪些文件该优先看
• 哪些技能该先用，哪些不该碰

所以“让 AI 拥有项目记忆”这件事，在我看来不是锦上添花，而是决定它能不能真正进入生产环境的关键。轻量、渐进式披露、持续记忆，这几个词我现在越来越看重，也是因为它们更接近真实可用，而不是堆一个大而全的上下文把模型喂爆。

这个方向我现在甚至会觉得，比“再换一个更强模型”还重要。因为模型强了，只是上限高一点；但如果记忆、上下文、项目理解还是一塌糊涂，那它的可用性依然会反复横跳。

三、这半年我最大的几个认知变化 🔄

1. AI 的价值不在单点生成，而在流程打通 🔗

这是我现在最明确的一个判断。

单点编码提效当然有，但它的上限其实没那么高。真正有复利的，是把分析、定位、方案、改码、审查、验证这些环节串成一条链。

一旦链路能跑通，AI 带来的就不只是“快一点”，而是研发方式本身开始变化。

2. 做 AI 产品，核心不是功能多，而是“能被用起来” 🎯

这点在做推广和沉淀的时候体会特别深。

做一个 skill 不难，做十个也不算最难。真正难的是：

• 别人知不知道该用哪个
• 别人第一次用会不会卡住
• 安装门槛高不高
• 成本是不是够低
• 结果稳不稳
• 团队愿不愿意持续用

所以后面我越来越觉得，AI 产物要想推广，本质上得像产品，而不是像一堆功能说明书。

3. Skill 不能无脑膨胀，必须有路由 🚦

这是我最近感受很强的一点。

随着 workspace skill、个人本地 skill 越来越多，开始出现一个明显问题：skill 误触发和漏触发。

这和 skill 一开始主打的“渐进式披露”其实是相违背的。因为技能一多、命名一杂、边界一重叠，模型就容易：

• 调错 skill
• 该调的不调
• 多个类似 skill 之间犹豫
• 触发路径不稳定

所以我现在的判断是：不能靠无限堆技能解决问题，必须有一个类似路由器的东西，去解决技能选择和触发的问题。

不然 skill 体系越大，使用体验可能反而越差。

4. 做 Agent，自己也得不断补课 📚

“活到老学到老”这句话，我现在还挺有感触的。

龙虾出来以后，我越来越觉得自己不能只停留在代码和业务上。因为如果要真正做好 Agent 开发，很多知识都得补：

• RAG 怎么搭更合理
• memory 怎么分层
• Agent 工程怎么评估
• 多 Agent 协作怎么设计
• 什么样的上下文组织方式更稳定
• 什么样的技能设计更符合模型工作方式

这半年我不只是“做项目”，其实也在重新学习一套新的工程方法。

认知变化速览表 ✨

四、哪些东西值得继续沉淀？ 🌱

如果从“长期有复利”的角度看，我觉得下面这些最值得继续投。

1. 高频工作流 🔁

像日常需求开发、JIRA 修复这种高频且流程相对稳定的场景，最值得持续打磨。因为它们最容易形成团队级复用。

2. 技能仓库 🧰

技能仓库的价值不只是多，而是是否形成：

• 清晰分类
• 稳定调用
• 易于安装
• 可持续迭代
• 有使用反馈闭环

如果这几点能持续做好，它会是非常重要的 AI 能力资产。

3. 项目记忆 / 上下文体系 🗂️

这是我觉得最关键、也最容易被低估的一块。很多 AI 效果问题，最后都不是模型问题，而是上下文问题。

4. 路由与调度能力 🚦

skill 体系一旦做大，没有路由层肯定会出问题。这块后面非常值得专项沉淀。

5. 可分享的方法论文档 📝

以前总觉得“会做就行”，但现在越来越觉得，能讲清楚、能写出来、能让 AI 和人都能读懂，本身就是生产力。

五、哪些地方做得还不够好？ 🪫

当然也不是所有事情都很顺。

1. 技能膨胀带来的复杂度上升 📈

skills 越多，管理越难，触发越不稳定，用户也更难理解整体结构。

2. 产品形态还不够统一 🧱

有些东西已经像产品了，有些还停留在“高手工具”阶段。要推广，必须进一步收敛交互和入口。

3. 项目理解能力还不够强 🔍

虽然已经开始做项目记忆、RAG 和多层 memory，但离“真正理解项目”还有距离。

4. 经验沉淀速度还不够快 ⏳

很多有价值的经验，还是停留在具体对话和个别案例里，没有第一时间抽成可复用资产。

当前问题清单一览 ⚠️

六、我现在怎么理解这半年？ 🪞

如果回头看，我觉得这半年最重要的，不是做了多少个 skill，也不是写了多少篇文档，而是我对 AI 在研发里的位置有了更清晰的判断：

AI 不该只是一个“帮我写代码”的助手，而应该逐步成为一个能理解上下文、调用能力、参与协作、跑通流程的工作伙伴。

而要走到这一步，靠的不只是模型本身，还包括：

• 工作流设计
• skill 设计
• 路由与调度
• 记忆与上下文
• 产品化包装
• 团队推广方式

这些东西拼在一起，才有可能真正做出一个“能被持续使用的 AI 研发产品”。

七、下半年想继续往哪里走？ 🚀

下半年方向速览表 🗓️

接下来我更想继续做几件事：

1. 把工作流继续产品化
   让更多人能更低成本接入和使用。

2. 补强 skill 路由能力
   解决 skill 膨胀后的误触发、漏触发问题。

3. 继续做项目记忆
   让 AI 真正拥有长期上下文，而不是每次都从零开始。

4. 完善 Agent 工程方法
   不只做 demo，而是形成更稳定的开发范式。

5. 持续输出可分享内容
   把做过的事、踩过的坑、有效的方法讲清楚，变成团队和 AI 都能复用的知识资产。

结语 🌌

上半年这段探索让我越来越确定一件事：AI 的未来，不只是更强的模型，而是更像样的工作方式。

如果说以前我关注的是“AI 能不能帮我快一点”，那现在我更关心的是：

能不能把一套靠谱的 AI 工作方式沉淀下来，让它不依赖某一个人的经验，也能持续发生价值。

这件事可能比“写出一段漂亮代码”慢得多，也难得多，但我觉得更值得做。

这里按天记录工作内容、遇到的问题和当天的一点想法，方便月底回看。

2026/06/23 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成飞书文档读取失败问题复现，确认 docx 直链解析和读取脚本本身是通的，实际已经能读到目标文档内容，当前更像是使用侧入口、权限或上下文差异导致的表现不一致。
• 梳理技能同步到 Codex 的处理方向，先把当前技能包状态和本地同步入口对齐清楚，避免把 one-click-bundles 来源和 Codex 技能目录的同步方向弄反。
• 推进 POS workspace 第六阶段接收消息问题定位，围绕 allocateUserType、alt、KDT_ID/USER_NO 这组关键字把范围收敛到支付资产和商户号分配链路，为后续修正 alt 处理先把代码入口找实。
• 调整晚间日报自动化的产出方式，把原来只推飞书的链路扩成“飞书日报 + Hexo 月度工作记录”，后续每天会直接追加到当月文章并执行部署，减少手工整理。
• 对齐了今天的日程安排，下午的“对下 workspace 进展”和晚间的“美业学习第五场：美业门店客户运营实战拆解”是今天需要关注的主要日历事项。
• 检查了今天收件箱未读情况，当前未发现明显需要处理的未读邮件；但邮箱身份信息仍然返回为空，所以这块暂时还是按弱提醒处理，不直接下强结论。

🧩 困难/需要帮助

• POS workspace 的 alt 处理还需要继续结合具体代码改动和回归场景确认，重点是不要影响现有商户号分配链路。
• 飞书文档读取虽然已经能复现成功，但如果使用侧还在失败，需要继续补入口、权限和实际调用参数这几块证据。
• 邮箱 profile 返回主邮箱为空的问题还没彻底解决，重要未读邮件判断暂时不能当强结论。

💭 感想

今天主要还是在把几个问题往真实链路和明确结论上收。飞书文档读取这类问题，先分清脚本、权限和入口差异很重要；POS 的 alt 修正也是一样，先把代码链路找准，后面改起来才不容易把口径带偏。日报这边把飞书和博客两条产出链路理顺以后，后续记录也会稳一些。

2026/06/24 今天做了啥？ ✨

今天主要是在把 5 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成 2026-06-24 晚间日报 evidence 采集，确认统一 evidence 文件已生成；但今天只采到晚间日报线程和一次会话，缺少可复核的业务工作记录。
• 梳理历史日报和 6 月月度工作记录格式，确认飞书正文继续保持“工作内容 / 困难/需要帮助 / 感想”三段，博客小节继续按当天记录更新。
• 确认今天日报的写作边界：没有可靠的业务 threadName、userInputs 或 toolCalls 证据时，不强行补写项目进展，只记录能确认的事项和证据缺口。
• 准备当天日报文件，先把 evidence 摘要、历史口吻和发布流程对齐清楚，避免后续飞书和博客两边内容不一致。
• 对齐飞书推送和 Hexo 月报追加链路，当天小节按日期更新，避免重复追加；后续仍以统一 evidence 作为日报入口。

🧩 困难/需要帮助

• 今日 evidence 缺少业务会话、日历安排和邮件摘要证据，无法可靠补充具体项目进展或需要关注的事项。
• 后续需要确认工作记录来源是否覆盖“前一天下午六点到今天下午六点”的主要工作，否则日报容易只留下自动化链路本身。

💭 感想

今天主要是在把日报链路和证据边界先收稳。业务证据不足时不硬写进展，比写得完整但不可复核更重要；后面要优先补齐工作来源，日报才更有复盘价值。

2026/06/28 今天做了啥？ ✨

今天主要是在把 5 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成 2026-06-28 晚间日报 evidence 采集，确认统一证据文件已生成；但今天只采到“每日晚间简报与日报推送”线程和一次会话，缺少可复核的业务工作记录。
• 确认今日日报写作边界：historyItems 为 0，userInputs 为空，toolCalls 只有基础命令调用，因此不补写项目、JIRA、代码链路或业务口径结论，只记录可确认事项。
• 梳理 6 月历史日报和博客小节的稳定格式，确认飞书继续保留“工作内容 / 困难/需要帮助 / 感想”三段，博客继续按当天日期更新当月文章。
• 对齐当天日报发布链路，日报文件、飞书推送配置和 Hexo 月度工作记录仍统一使用同一份日报内容作为来源，避免两边口径不一致。
• 保守处理日历安排、重要未读邮件和今日注意事项补充；由于 evidence 没有提供可靠来源，今天不把这些信息写成明确提醒。

🧩 困难/需要帮助

• 今日 evidence 缺少业务会话、日历安排和邮件摘要证据，无法可靠补充具体项目进展或需要关注的事项。
• 后续需要确认工作记录来源是否覆盖“前一天下午六点到今天下午六点”的主要工作，否则日报容易只留下发布链路和证据缺口。

💭 感想

今天主要是在把日报的证据边界讲清楚。没有业务证据时不硬写具体进展，比写得完整但不可复核更重要；后面要优先补齐真实工作来源，日报才更有复盘价值。

2026/06/29 今天做了啥？ ✨

今天主要是在把 5 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成订单 E20260629105240032702006 流程核验，确认这笔单命中 QA 环境而非生产；当前链路收敛到 Android 离线/线下场景后的重开单、关闭旧单治理流程，不是普通完成支付单。
• 确认组合支付参数下传链路，OrderPayService#createPay 入参保留 COMBINE_PAY，以及 CASH_PAY、THIRD_PAY 两段支付明细，总金额和分段金额可以对齐，入口侧参数没有丢。
• 推进拉卡拉 POS 参数透传排查，确认入口 extra 中有 POS_INST=lakala、POS_FLAG=smart_pos、deviceName=LANDI A8S，后续支付通道侧也实际走到了拉卡拉。
• 完成订单 E20260629144044008302022 资产侧参数核验，确认 pay-trading-core 的统一收单支付请求 attachment 已带 POS_INST=lakala、POS_FLAG=smart_pos，和单纯的 lakala_code/lakala_msg 渠道返回字段区分开了。
• 重新生成编程语言趋势视频，确认中文界面、2560x1440、60fps 和约 30s 时长都符合目标参数，成片已输出到本地文件。

🧩 困难/需要帮助

• E20260629105240032702006 如果后续要作为支付成功样例使用，需要先确认离线订单、重开单和关闭旧单治理是否符合业务预期，避免按普通支付单口径判断。
• POS 参数透传目前主要基于 QA 链路证据确认，后续如果要推广到生产结论，还需要继续核对发布分支、环境配置和回归范围。

💭 感想

今天主要是在把 POS 支付相关问题往真实 trace 和上下游参数口径上收敛。几个结论都尽量没有停在入口参数，而是继续追到资产侧和通道侧确认，这样后面讨论时能少一些“应该有”的猜测。

2026/06/30 今天做了啥？ ✨

今天主要是在把 6 个重点事项往真实链路、明确口径和可落地结论上收，既有问题排查，也有流程和记录方式上的整理。

✅ 工作内容

• 完成拉卡拉 POS 银行卡一级支付方式口径梳理，确认这次核心是新增/识别 POS_BANK_CARD 一级支付表达，不是建行那类二级支付方式配置，后续排查要围绕主支付链路和下游展示统计展开。
• 梳理代码侧锚点，确认 PayWayEnum 已有 4132-4136 的 POS 银行卡支付枚举，PayToolUnifiedCashierEnum 已有 POS_BANK_CARD，mall-trade-seller 也存在按 POS 银行卡做订单筛选的逻辑。
• 推进订单 E20260630103921048102020 的拉卡拉透传核验，确认 QA 环境在 2026-06-30 10:39 左右有日志，主 trace 为 yz7-0a096140-1782787156045-602579；当前样例初看是“现金 + 微信条码”的混合支付，尚未直接看到 POS_BANK_CARD/POS_INST/POS_FLAG。
• 梳理 POS 上下文到资产请求的字段链路，确认重点要看 phasePayModels[].extension、PayRequest.bizExt、MultiPayRequest.outBizContext，其中 retail-trade-core 负责带入 POS 上下文，pay-trading-core 会合并到资产侧 PaymentParam。
• 推进拉卡拉支付方式页面影响面核查，确认测试点集中在展示、筛选、退款、小票、交班日结、报表和业绩分佣，不只是收银台发起支付本身。
• 梳理下游仓库当前差异，retail-sync 已出现 POS_BANK_CARD 支付族映射，但 retail-trademanager 暂未直接命中 POS_BANK_CARD/4132-4136 的业务逻辑，后续要区分“后端返回文案已支持”和“页面筛选项还需要补枚举”。

🧩 困难/需要帮助

• E20260630103921048102020 当前不像拉卡拉 POS 银行卡样例，后续如果要验证透传，需要换一个真正命中 POS_BANK_CARD/POS_INST/POS_FLAG 的订单继续追。
• 本地代码里 lakala/POS_INST 的直接命中还不多，可能和子仓分支、发布计划或环境代码不同步有关，需要继续确认发布分支和回归范围。
• 页面影响面还需要继续补齐 retail-trademanager、retail-finance-sales 等仓的筛选枚举、统计口径和展示文案证据，避免只按后端主链路下结论。

💭 感想

今天主要是在把拉卡拉 POS 银行卡这条线从概念往真实代码、日志和页面影响面上收敛。比较关键的判断是先把一级支付方式和二级支付配置分开，再去看字段有没有真正进入资产和下游页面；方向已经比较清楚，但样例订单和页面枚举还需要继续拿证据确认。