刘耀文

一键配置高效终端：zsh + Oh My Zsh + powerlevel10k（零配置上手）

Fri, 03 Apr 2026 05:42:44 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/one-click-setup-zsh-oh-my-zsh-powerlevel10k

一、完整脚本，复制到bash终端运行

#!/usr/bin/env bash
set -e

echo "==> Setup zsh + Oh My Zsh + powerlevel10k"

# 1. zsh
if ! command -v zsh >/dev/null 2>&1; then
  echo "Install zsh..."
  brew install zsh
fi

# 2. oh-my-zsh
if [ ! -d "$HOME/.oh-my-zsh" ]; then
  echo "Install oh-my-zsh..."
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
fi

ZSH_CUSTOM=${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}

# 3. plugins
install_plugin () {
  if [ ! -d "$ZSH_CUSTOM/plugins/$1" ]; then
    git clone --depth=1 "$2" "$ZSH_CUSTOM/plugins/$1"
  fi
}

install_plugin zsh-autosuggestions https://github.com/zsh-users/zsh-autosuggestions
install_plugin zsh-syntax-highlighting https://github.com/zsh-users/zsh-syntax-highlighting

# 4. theme
if [ ! -d "$ZSH_CUSTOM/themes/powerlevel10k" ]; then
  git clone --depth=1 https://github.com/romkatv/powerlevel10k \
    "$ZSH_CUSTOM/themes/powerlevel10k"
fi

# 5. tools
if command -v brew >/dev/null 2>&1; then
  brew install fzf zoxide >/dev/null 2>&1 || true
  $(brew --prefix)/opt/fzf/install --all >/dev/null 2>&1 || true
fi

# 6. config
cat > ~/.zshrc <<'EOF'
export ZSH="$HOME/.oh-my-zsh"

ZSH_THEME="powerlevel10k/powerlevel10k"

plugins=(
  git
  zsh-autosuggestions
  zsh-syntax-highlighting
)

source $ZSH/oh-my-zsh.sh

command -v zoxide >/dev/null 2>&1 && eval "$(zoxide init zsh)"
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
EOF

# 7. default shell
if [ "$SHELL" != "$(which zsh)" ]; then
  chsh -s "$(which zsh)"
fi

echo "Done. Restart terminal or run: source ~/.zshrc"
echo "Run: p10k configure"

包含

zsh
Oh My Zsh
powerlevel10k
autosuggestions / syntax-highlighting
fzf / zoxide

使用

# 自动补全
git → 按 →

# 历史搜索
Ctrl + R

# 跳目录
z project

# git
gst / gco / gp

初始化主题

p10k configure

看完了？说点什么呢

不想再用 puppeteer 了，我写了个 Markdown 渲染引擎

Thu, 02 Apr 2026 08:48:26 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/markdown-rendering-engine-alternative-puppeteer

做过「Markdown → 图片」的，应该都踩过这个坑：

Markdown → HTML → 浏览器 → 截图

然后你就会遇到：

chromium 很重（部署麻烦）
分页不稳定（每次结果都可能不一样）
批量渲染性能很差
serverless 环境基本不好搞我最近有点受不了这套链路，就自己写了一个： marknative

核心思路（和常规方案完全不一样）

不走 HTML，不走 DOM，不走浏览器。

而是：

Markdown → AST → 自定义文档模型 → layout → 分页 → canvas 绘制

简单理解：

把“浏览器排版”这件事，自己实现了一套极简版本（只针对 Markdown）。

能干什么？

1. 直接输出 PNG / SVG

import { renderMarkdown } from 'marknative'

const pages = await renderMarkdown('# Hello')

await Bun.write('page-1.png', pages[0].data)

不需要：

puppeteer
headless chrome
截图

2. 天然支持分页（而且是稳定的）

默认就是：

1080 × 1440
类似卡片比例而且分页是 deterministic 的：
同一份 Markdown
任意环境
渲染结果一致

3. 适合批量生成内容

比如：

小红书卡片
技术文章配图
AI 自动生成内容图相比 puppeteer：
启动更快
内存更低
更容易横向扩展

这个方向值得做

本质上，这类需求其实是：

“结构化文本 → 可控排版 → 图像输出” 但浏览器：

太通用（为网页设计）
不可控（CSS + layout 太复杂）
成本太高而 Markdown 场景：
结构固定
可约束
非常适合做“专用排版引擎”

技术点（简单说几个有意思的）

用 micromark + mdast 做解析
自己实现 block / inline layout
用 skia-canvas 直接绘制
layout 和 render 完全解耦所以理论上可以
换 renderer（SVG / PDF / WebGL）
做自定义主题系统
做可视化编辑器（未来）

项目地址

👉 https://github.com/liyown/marknative

看完了？说点什么呢

Claude 风格的流式 UI，到底是怎么做出来的

Tue, 17 Mar 2026 15:55:50 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/20260317

claude 最近更新了交互是 UI，可以在聊天框流式输出可交互的页面 claude：

同时看到一个叫 Generative-UI-MCP 的项目，作者的想法很直接：用 MCP 协议把 Claude 能生成可交互 UI 这套东西复刻出来。

这个项目本身不复杂，但它把一件平时很难说清楚的事拆开了：Claude 这种交互式 UI，真正新在哪里；它为什么不像“AI 帮你写了一段前端代码”那么简单；以及它背后最先要解决的，到底是渲染问题，还是协议问题。

我后来又对着一段真实的 SSE 流式输出日志，把整个过程重新拆了一遍。两边对起来之后，会更清楚：Claude 风格的流式 UI，本质上不是“模型输出 HTML”，而是“模型持续输出一个宿主能够可靠消费的 UI 协议”。

这篇文章想讲的，就是这件事。

它是一个可持续交互UI 页面

Claude 这波交互式 UI / Artifacts，真正新的地方不是“AI 生成了一个页面”，那个早就有人做过了。新的地方在于：生成出来的东西还能继续用，还能继续跟模型交互，还能挂工具、更新状态。

这跟“AI 写了段前端代码，你复制出去跑”是完全不同的东西。

以前那种方式，模型是起点，生成完就结束了。现在这种方式，模型是这个 UI 会话里的持续参与者。用户在界面上的操作可以再回到模型，模型返回的新内容可以局部更新界面，来回转。

这个闭环大概长这样：

sequenceDiagram

actor U as 用户

participant UI as Widget UI

participant Host as 宿主 / Host

participant Tool as 工具 / API

participant LLM as 模型 / LLM



U->>UI: 点击、输入、操作

UI->>Host: emit(action, payload)



alt 前端可直接处理

Host->>UI: 更新本地状态

else 需要调工具

Host->>Tool: 调用业务接口

Tool-->>Host: 返回结果

Host->>UI: 局部更新

else 需要再问模型

Host->>LLM: 当前状态 + action

LLM-->>Host: 新内容 / 新 widget

Host->>UI: 增量插入或局部替换

end

这个循环跑得起来，才是真正的“交互式”。带几个按钮的 HTML 不叫交互式，事件能回流才叫。

一段真实的流式输出，能把这件事看得很清楚

如果看一段真实的 SSE 流式输出，会发现模型并不是一次性吐出一个完整页面，而是在流里持续输出不同类型的内容块，前端边收边拼，拼完再交给对应工具渲染。

拆开之后，大概是五步。

第一步：先加载 UI 生成规范

模型一开始并没有直接生成 widget，而是先调用了一个类似 visualize:read_me 的工具，输入参数非常短：


{

"modules": ["diagram", "interactive"]

}

这一步很关键。它说明模型在真正开始“画界面”之前，先去拿一份运行时 UI 规范。也就是说，生成不是裸奔的，模型先要知道这次该遵守什么规则。

第二步：工具返回一整套设计系统和流式输出约束

这份返回内容里，有几段特别关键。

先是模块说明：


Call read_me again with the modules parameter to load detailed guidance:

- `diagram` — SVG flowcharts, structural diagrams, illustrative diagrams

- `mockup` — UI mockups, forms, cards, dashboards

- `interactive` — interactive explainers with controls

- `chart` — charts, data analysis, geographic maps (Chart.js, D3 choropleth)

- `art` — illustration and generative art

然后是角色定义：


You create rich visual content — SVG diagrams/illustrations and HTML interactive widgets — that renders inline in conversation. The best output feels like a natural extension of the chat.

接着是它最关键的几条约束：


### Philosophy

- Seamless: Users shouldn't notice where claude.ai ends and your widget begins.

- Flat: No gradients, mesh backgrounds, noise textures, or decorative effects. Clean flat surfaces.

- Compact: Show the essential inline. Explain the rest in text.

- Text goes in your response, visuals go in the tool.

还有专门面向流式渲染的顺序规则：


### Streaming

Output streams token-by-token. Structure code so useful content appears early.

- HTML: ...
"

}

4. 工具渲染后的真实提示


Content rendered and shown to the user. Please do not duplicate the shown content in text because it's already visually represented.



[This tool call rendered an interactive widget in the chat. The user can already see the result — do not repeat it in text or with another visualization tool.]

看完了？说点什么呢

图像生成怎么突然把“写字”这件事做对了？

Sat, 14 Mar 2026 15:17:25 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/20260314

最近我有一个很直观的感受：
这一波图像生成模型，很多已经不再只是“能画出像字的东西”，而是真的开始把字写对了。

这件事其实挺值得停下来想一下。

因为如果你回头看前两年的生图效果，会发现一个很稳定的槽点：
画面氛围、构图、光影都已经很强了，但只要图里出现招牌、海报标题、包装文案、UI 文本，基本就会露馅。英文会串字母，中文会缺部件，小字更是一塌糊涂。这个问题当时严重到什么程度？严重到不少关于视觉文本生成的论文，开头第一段就在说：现在的文生图虽然整体 fidelity 很高，但只要把视线移到 text area，破绽就非常明显。 oai_citation:0‡arXiv

但最近不太一样了。

我自己看到的一些新结果，已经不只是“偶尔能写对几个字”，而是明显能感觉到：模型在处理标题、标语、场景里的招牌文字时，稳定性比以前高了一大截。于是我就有点好奇：这事到底是怎么被解决的？
难道真的是模型大了、数据多了，所以顺手把文字问题也学会了？还是说，研究界其实已经悄悄换了一套解题思路？

我去翻了一圈近两三年的论文之后，得到的结论还挺明确的：

文字问题不是靠 prompt engineering 慢慢磨出来的，也不是模型“顺便学会”的。它本质上是被单独拿出来，当成一个专门问题重新建模了。 oai_citation:1‡arXiv

这篇文章就想顺着这个好奇心，聊清楚三件事：

为什么图像生成一碰到文字就特别容易翻车；
最近这些方法到底是怎么解决的；
为什么我越来越觉得，这条路线最后会走向一种 glyph-first 的系统，而不是继续指望 prompt 自己长出排版能力。

先说最核心的一点：文字不是普通图像内容

我觉得理解这个问题，第一步不是去看 attention，也不是去看 OCR loss，而是先承认一件事：

文字和“云、树、衣服、墙面纹理”不是同一类对象。

普通图像内容大多是连续的。
云稍微糊一点，还是云；木纹稍微歪一点，也还是木纹。
但文字不是这样。文字是低容错的离散符号系统，一个字少一笔、错一个结构，可能立刻就不可读了。

这也是为什么早期很多模型会给人一种很微妙的感觉：
远看挺像，近看不对。
你会觉得“这里好像应该有字”，但认真一看，其实只是某种很像文字的纹理，不是可读的文字。

GlyphControl 在 2023 年就把这个问题讲得很直白：视觉文本生成不是普通 T2I 任务的自然延伸，必须引入额外的 glyph 条件信息，才能稳定生成准确文本。AnyText 也有类似判断：即便图像整体质量已经很高，一旦聚焦到文本区域，问题就会立刻暴露出来。 oai_citation:2‡arXiv

flowchart TD
    A[为什么文字特别难] --> B[文字是离散符号]
    A --> C[文字既有语义又有几何]
    A --> D[文字区域通常很小]
    A --> E[文字目标和背景目标并不一致]

    B --> B1[一笔错就可能不可读]
    C --> C1[不仅要知道写什么 还要知道长什么样]
    D --> D1[全图训练时容易被背景梯度淹没]
    E --> E1[背景追求自然连续 文字追求局部精确]

为什么以前的模型总是“像有字”，但又写不对？

如果只从模型结构上看，这个问题其实挺自然的。

传统文生图做条件注入，基本是这条路：

图像 latent / patch token 当 Query
文本 token 当 Key / Value
让图像在生成过程中不断去“读”文本条件

这个机制对普通语义对齐非常有效。
比如 prompt 里有 red car on snow，模型很容易学会：

哪些区域该看 car
哪些区域该看 snow
哪些局部更多受到 red 的影响

但问题在于，文本 token 提供的是语义，不是字形。

token “A” 并不是字母 A 的视觉结构，
token “春” 也不是“春”字的具体笔画排列。
所以如果系统只吃语义 token，它更容易学会的是：

这里应该有一段“文字感”

而不是：

这里必须是这个字符，而且要笔画对、边界清楚、相邻字符别打架

这也是为什么过去两三年的论文，几乎都在朝一个方向收敛：

别再只靠 semantic conditioning 了，要把文字从“语言提示”升级成“显式字形条件”。
GlyphControl 是这样，AnyText 是这样，FLUX-Text 是这样，TextPixs 也是这样。 oai_citation:3‡arXiv

flowchart LR
    A[仅有语义 token] --> B[告诉模型 这里应该有文字]
    B --> C[优点: 和普通 T2I 兼容]
    B --> D[缺点: 没告诉模型这个字具体长什么样]
    D --> E[结果: 容易生成伪字形/串字/错字]

    F[显式 glyph 条件] --> G[告诉模型 这里应该是这个字符形状]
    G --> H[附带位置/大小/区域信息]
    H --> I[结果: 可读性和可控性明显上升]

研究界是怎么一步步把这个问题拆开的？

如果把近几年的工作串起来看，我觉得它不是“某篇论文突然发明了一个神奇模块”，而是经历了一个挺清楚的演化过程。

第一阶段：先承认“文字生成”是一个独立问题

这一阶段最重要的，不是技术细节，而是问题被重新命名了。

GlyphControl 很关键的一点，是明确提出 visual text generation 需要 glyph-conditional control，而不是继续指望 character-aware text encoder 或更大的通用模型自己学会。论文还专门构建了 LAION-Glyph 数据集，并用 OCR-based metrics、CLIP score、FID 来评估结果。这个动作很重要，因为它等于在说：文字渲染已经值得有自己的一套 benchmark 和指标。 oai_citation:4‡arXiv

AnyText 则把这件事进一步系统化了。它不只是做文字生成，还把多语言文字生成和编辑放进同一个扩散框架里，并引入 AnyWord-3M 数据集和 AnyText-benchmark。论文里说得很清楚：文字区域的问题不能再被当成普通图像 fidelity 的附属现象，它需要独立建模。 oai_citation:5‡arXiv

换句话说，第一阶段真正发生的事是：

大家不再问“为什么模型还不会写字”，
而开始问“如果把写字当成一个专门任务，我们应该怎么表示它、训练它、评估它？”

第二阶段：从 semantic-first 走向 glyph-first

这是我觉得最关键的转折。

以前的做法，本质上是 semantic-first：
先给模型一个字符串的语义表示，然后希望它在图像空间里自己把字符外形“悟出来”。

但后来大家慢慢发现，这条路上限不高。
因为语义和字形根本不是一回事。你知道一个词的 meaning，不等于你就知道它在图上该怎么写。

所以 GlyphControl 的解法很直接：
不要只告诉模型“这里写 SALE”，还要把 SALE 的 glyph instruction 明确给它。这样用户不仅能控制文本内容，还能控制位置和大小。 oai_citation:6‡arXiv

AnyText 继续沿着这个方向往前走，它的设计里有两个特别重要的模块：

Auxiliary latent module：吃 glyph、position、masked image，生成跟文字相关的 latent feature；
Text embedding module：借助 OCR 模型去编码 stroke 信息，再把这些 embedding 和 caption embedding 融合起来。

这其实已经很能说明问题了：
真正有效的文字生成，不是再多喂一点 prompt，而是把字形、位置、区域这些原本没被好好表示的东西，变成模型能直接消费的条件。 oai_citation:7‡arXiv

我自己看到这里的时候，感受挺强的：
这已经不是“优化 prompt 理解”了，而是在重新定义输入空间。

flowchart TD
    A[从 prompt-only 到 glyph-first] --> B[阶段 1 只给字符串语义]
    A --> C[阶段 2 给 glyph + position + region]
    A --> D[阶段 3 再把这些条件深入注入 backbone]

    B --> B1[容易得到像文字的纹理]
    C --> C1[开始能控制字符内容/位置/大小]
    D --> D1[开始追求字符级稳定和场景一致性]

第三阶段：问题不只是“有没有 glyph”，而是“glyph 怎么进系统”

glyph conditioning 成为共识之后，研究重点就开始下沉。

大家不再争论“该不该给 glyph”，而是开始研究：

glyph 是当额外输入就够了吗？
还是应该更深地改 backbone？
训练目标是不是也得跟着变？

FLUX-Text 是我觉得很典型的一篇。
它不是那种特别花哨的“新世界观”，但它很实在。它的思路是：在 FLUX-Fill 这种强 base model 上，用比较轻量的 glyph 和 text embedding 模块增强文字理解与生成，同时尽量保留原有生成能力。更重要的是，它显式提出了 Regional Text Perceptual Loss，就是告诉你：文字区域必须被单独优化。 oai_citation:8‡arXiv

这一点其实特别重要。

因为文字区域通常很小，如果训练目标还是全图统一的，那么大部分梯度都来自背景。模型当然会更优先学“把图做漂亮”，而不是“把字写对”。FLUX-Text 的意思某种程度上就是：
你不能一边说文字很重要，一边在损失函数里继续拿它当背景噪声的一小块。 oai_citation:9‡arXiv

第四阶段：从“词级条件”继续下钻到“字符级绑定”

再往后，问题就会变得更细。

即使你给了 glyph，也不代表字符之间不会互相干扰。
很多时候模型出的问题不再是“完全不知道写什么”，而是：

相邻字符粘连
一个字符的结构跑到另一个字符那边去
整串文本看起来有大概的样子，但局部字符不稳定

这时候 TextPixs 这种工作就很有意思了。

它做了几件非常针对性的事：

双流编码：语义文本流 + glyph 视觉流
character-aware attention
OCR-in-the-loop feedback
attention segregation loss

这套东西的核心直觉很简单：
文字不是词级别对齐就够了，而是要字符级别地对齐。

普通 T2I 里，token 级控制通常已经足够。
但文字渲染不一样，字符是最终可读性的最小单位。如果字符之间的 attention 没有被稳定地分开，系统就很容易得到“这是一串字”的整体感觉，却写不对具体每个字。TextPixs 也直接把目标写得很清楚：解决 readable、meaningful、correctly spelled text 的问题。 oai_citation:10‡arXiv

flowchart LR
    A[词级/短语级条件] --> B[整体知道这里有一串文字]
    B --> C[问题: 字符边界不清 相互污染]

    D[字符级条件与注意力] --> E[每个字符更独立地绑定区域]
    E --> F[结果: 拼写更稳定 可读性更高]

第五阶段：也许模型不该负责“从头学拼写”，而该负责“把文字融合进场景”

翻到比较新的工作时，我最感兴趣的一条思路，其实不是单纯“准确率又涨了多少”，而是问题定义开始变了。

比如 TextFlux 的意思就很明显：
它强调的是 OCR-free DiT model for high-fidelity multilingual scene text synthesis，同时把重点放在 glyph accuracy 和 scene integration 上。 oai_citation:11‡arXiv

这背后有个挺大的范式变化：

旧问题：怎么让模型自己从语义里学会 spelling
新问题：怎么把可靠的字符表示自然地融进图像场景

我越来越觉得，后者可能才是更长期的方向。

因为如果你让一个通用图像模型同时承担两件事：

生成复杂视觉世界
还得像排版引擎一样精确输出字符

那它天然就有点拧巴。
但如果你把 spelling 这件事尽量结构化、显式化，让模型把重心放在融合——也就是风格、材质、光照、透视、边缘过渡——这条路反而更合理。

这也是为什么我现在会更愿意把这条研究线理解成：

不是“模型终于学会写字了”，
而是“系统终于不再把文字当普通纹理处理了”。

把这些方案压成一句话，其实就是三步

如果不展开细节，把这几年的路线浓缩一下，我觉得就是下面三步：

第一步：把文字从语义提示升级成字形条件

也就是从 prompt-only 走向 glyph-first。
这是 GlyphControl 和 AnyText 这类方法最早讲清楚的事。 oai_citation:12‡arXiv

第二步：把文字区域从整图里单独拎出来优化

也就是别让全图损失继续淹没文字区域。
FLUX-Text 这种 regional text loss 的思路很典型。 oai_citation:13‡arXiv

第三步：把控制粒度从词级推进到字符级，再进一步推进到场景融合级

TextPixs 代表字符级绑定这一步，后续一些工作则更强调 scene integration。 oai_citation:14‡arXiv

flowchart TD
    A[文字问题的主线解法] --> B[glyph-first]
    A --> C[region-first]
    A --> D[character-first]
    A --> E[integration-first]

    B --> B1[不只告诉模型写什么 还告诉它长什么样]
    C --> C1[文字区域单独加权优化]
    D --> D1[字符级注意力与约束]
    E --> E1[重点解决和背景如何自然融合]

我自己的感受：这可能是图像生成从“会画图”走向“能用”的一个拐点

我这次翻论文，最大的感受不是“原来某个模块这么 clever”，而是：

文字问题其实特别像一个分水岭。

过去很多视觉生成模型，主要解决的是“生成一张看起来不错的图”。
但只要场景变成海报、包装、UI、招牌、广告、知识卡片，评价标准就会立刻变化：

画面再美，字错了就没法用；
氛围再好，标题糊了就不能进生产流程；
文字编辑不稳定，就很难真正接入设计工作流。

所以文字渲染这件事，表面上看像个细节，实际上逼着整个系统往更工程化、更结构化的方向走。
它迫使模型回答一个过去可以回避的问题：

你到底是在生成“好看的视觉纹理”，
还是在生成“可被人类读懂和使用的信息”？

而最近这些论文给出的共同答案大概是：

如果你想生成的是后者，那就别再把文字当普通图像内容。

参考论文

[1] Yukang Yang et al., GlyphControl: Glyph Conditional Control for Visual Text Generation, NeurIPS 2023. 提出 glyph-conditional control，并构建 LAION-Glyph 与 OCR-based 评测。 oai_citation:15‡arXiv

[2] Yuxiang Tuo et al., AnyText: Multilingual Visual Text Generation and Editing, 2023/2024. 提出 auxiliary latent module、text embedding module，以及 AnyWord-3M / AnyText-benchmark。 oai_citation:16‡arXiv

[3] Rui Lan et al., FLUX-Text: A Simple and Advanced Diffusion Transformer Baseline for Scene Text Editing, 2025. 强调轻量 glyph/text embedding 与 text fidelity，并引入文字区域感知的优化思路。 oai_citation:17‡arXiv

[4] TextPixs: Glyph-Conditioned Diffusion with Character-Aware Attention and OCR-in-the-Loop Feedback for Accurate Text Rendering, 2025. 强调 dual-stream、character-aware attention、OCR-in-the-loop，以及字符级准确性。 oai_citation:18‡arXiv

看完了？说点什么呢

把经验写进仓库：关于 Skills 的一些想法

Wed, 11 Mar 2026 09:44:31 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/experience-skills-thoughts

把经验写进仓库

最近读 OpenAI 那篇讲 Skills 和 Agents SDK 的文章，脑子里一直在转一个很小的问题。

我们到底是在使用 AI，还是在把自己的工作方式，一点点整理成 AI 也能接住的东西。

以前总觉得，所谓“AI 提效”，核心是模型越来越强。它会写代码，会解释报错，会总结文档，也能把一段模糊的需求翻译成还算可用的实现。可真把它放进日常工程里，事情很快又会变得具体起来。

你会发现，问题常常不是它不够聪明，而是它不知道你们平时到底怎么做事。

同样是改完代码之后的“检查一下”，有人会顺手把 format、lint、test 全跑完，有人只会跑当前模块，有人记得补 typecheck，有人则默认 CI 会兜底。
同样是准备提 PR，有人会把改动背景、影响范围和验证方式写得很清楚，有人只留下一个简短标题，像往河里扔下一颗石头，剩下的涟漪全交给 reviewer 自己理解。

这些差别，看起来像是个人习惯。可如果往下想一层，它其实是一种没有被正式写下来的经验。

而 Skills 有意思的地方就在这里。

它不是让模型再多会一点东西，也不是再给 prompt 换一个更精致的名字。它更像是在说：如果一件事会一遍遍发生，如果它背后已经有了相对稳定的做法，那为什么不把它认真写下来，写进仓库，写成一种能被调用的能力。

这件事让我有点触动。因为它不是在追求一种更炫的智能感，反而是在做一件很朴素的事：把原本只存在于人脑子里的工作习惯，慢慢整理成系统的一部分。

Skill 像什么

如果只从表面看，skill 很容易被理解成“提示词模板”。

但我越来越觉得，它更像是一个很小的工作单元。
它知道自己该在什么时候出现，知道自己要完成什么，也知道哪些地方该交给模型判断，哪些地方该交给脚本执行。

OpenAI 的文章里提到，一个 skill 通常会有自己的说明文件，也可能带着脚本、参考资料，甚至一些辅助资源。换句话说，它并不是一句轻飘飘的“帮我做这个”，而是一套被稍微整理过的经验。

我很喜欢这种感觉。

因为很多时候，团队里的知识并不是没有，只是它们以一种很松散的形式存在着。它可能藏在某个资深工程师的习惯里，藏在某次 code review 的评论里，藏在一个只被提过一次的内部约定里。你问起来，大家都知道一点；真要写下来，又总觉得“这种事不是理所当然的吗”。

可一旦要交给 Agent，很多“理所当然”就突然变得不再理所当然了。

它不会天然知道，改了这几个目录意味着什么。
它不会天然知道，某一类改动是必须完整验证的，另一类改动却只需要最小检查。
它也不会知道，你们习惯怎样描述一次改动，怎样把上下文交代给下一个接手的人。

于是 skill 的意义开始变得清楚起来。
它不是替代经验，而是在保存经验。
不是制造新的流程，而是把原来那些靠默契维持的东西，慢慢落成可以复用的形状。

真正难的，不是写“做什么”，而是写“什么时候做”

我觉得 OpenAI 那篇文章里最值得反复想的一点，是它对 skill description 的强调。

一个 skill 是否真的有用，关键不是写得多完整，而是写得够不够准。
尤其是那个“什么时候该触发”的边界。

这件事听起来很细，可其实很像平时和人协作。
真正让一段协作顺畅起来的，从来不只是步骤本身，而是时机。

如果你只说“运行验证流程”，这当然没错，但几乎没什么帮助。
因为接下来最重要的问题都还没回答：

什么样的改动算需要验证？
只是改了文档呢？
只是重命名文件呢？
如果动到了测试或者构建链路，是不是就应该升级为完整检查？
这个动作是建议性的，还是必须性的？

当这些边界没被说清楚时，一个 skill 就很容易变得像一件摆设。它存在，但不稳定；偶尔会被调用，偶尔又会被忽略。最后的问题不在模型，而在于这个能力没有真正定义好自己出现的时刻。

我会觉得，写 skill 有点像在写一种很轻的制度。
制度不是靠语气强硬，而是靠边界清楚。
什么时候该发生，什么时候不该发生，什么属于例外，什么必须执行，这些东西一旦明确了，后面的流程反而会变简单。

仓库里其实一直缺一种“写给 Agent 的文档”

文章里还提到了 AGENTS.md。这个设定我也很喜欢。

它有一点像过去我们写给新同事的 onboarding 文档，只不过这次读者不是人，而是 Agent。

仓库有自己的脾气。
目录结构是怎么分的，哪里是核心路径，哪些约定看起来不显眼却不能碰，某些模块的测试为什么要这么跑，某些 API 的行为到底应该信源码还是信文档，这些都是仓库内部的语言。

平时这些东西靠人来理解，问题也不大。人会猜，会追问，会顺着上下文补全很多隐含信息。
但 Agent 不太一样。它当然会推理，可它最怕的是那些所有人都默认存在、却没有人认真写下来的东西。

所以 AGENTS.md 给我的感觉，不是又多了一份文档，而是终于出现了一种明确的载体，去承接那些“本来应该早就写清楚”的仓库共识。

如果说 AGENTS.md 更像总说明，那 skill 就更像一个个局部工作流。
前者回答“这里是一个什么样的地方”，后者回答“在这里，某件事该怎么做”。

再往下，还有 GitHub Actions 这种更确定的自动化兜底。
这样一层层看下来，会觉得这个结构其实很顺。

人负责形成经验。
文档负责表达经验。
skill 负责调用经验。
脚本和 CI 负责执行经验。

这和我过去想象的“AI 改变工程”很不一样。它没有特别戏剧化，反而很像软件工程一直以来最熟悉的路径：把不稳定的手工操作，慢慢整理成稳定的系统行为。

模型不需要什么都做

这篇文章里还有一个我很认同的判断：模型不应该负责一切。

这件事说出来很简单，但真正做的时候，太容易贪心了。
因为模型看起来什么都能处理，于是我们会不自觉地把理解、判断、执行、格式化输出，全部揉成一团交给它。

结果通常不会太好。

需要理解上下文、做比较、做总结、做判断的事，模型很擅长。
但需要按固定顺序执行命令、收集状态、输出可预期结果的事，本质上还是脚本更适合。

这个边界一旦想清楚，很多设计问题就会顺下来。

比如判断一个改动是不是行为变更，这种事要靠模型。它需要读 diff，理解意图，也理解周边上下文。
但“先跑哪些命令、失败了该怎么汇总、从哪里收集 git 状态和分支信息”，这些就该尽量交给脚本。

我一直觉得，好的系统不是把能力堆在一个点上，而是把职责分开。
模型负责那些本来就不确定的部分。
脚本负责那些应该尽量确定的部分。

Skill 之所以让我觉得它更接近“工程”，也在这里。它没有把模型想象成一个全能的主体，而是愿意承认：真正稳定的工作流，往往来自不同能力的合作，而不是单一能力的膨胀。

说到底，Skills 在整理的是“隐性经验”

我后来越想越觉得，Skills 最值得珍惜的地方，可能不是它能提升多少效率，而是它逼着团队去面对一件平时不太愿意面对的事：我们的很多工作，其实建立在隐性经验上。

这些经验平时并不显得稀缺。
因为总有人知道。
一个团队里，总会有一些人对仓库很熟，对流程很熟，对各种“虽然没写，但大家都这么做”的东西很熟。于是问题看起来总能被解决，流程看起来总能被跑通。

可一旦团队变大，项目变复杂，或者引入 Agent，这些隐性的部分就会立刻暴露出来。

因为 AI 不会自动继承团队默契。
它也不会天然理解某些“本来不用说”的规则。

于是很多以前能被熟人网络悄悄消化掉的问题，现在都必须被明说了：

什么是必须做的？
什么只是建议？
哪些步骤必须自动化？
哪些判断仍然需要人来做？
哪些知识应该写进仓库，而不是留在聊天记录里？

这让我觉得，Skills 表面上是在帮助 Agent，实际上也在帮助团队重新认识自己。
你们到底是怎样工作的。
哪些经验是可迁移的。
哪些流程值得固化。
哪些依赖于个人记忆的地方，早就该被替换掉了。

从这个角度看，它不是一个单纯的新功能，而像一次很安静的整理。

我会从什么地方开始

如果真要在一个仓库里慢慢把 skill 建起来，我大概不会一上来就做一个很大的系统。

我更愿意从那些已经足够重复、足够明确、而且失败成本又不低的事情开始。

比如验证流程。
这几乎是最自然的一类。改动之后该跑什么、顺序是什么、哪些情况需要附加检查、失败时怎么把结果说清楚，这些都很适合被整理成 skill。它高频、重复，而且一旦依赖记忆，就特别容易漏。

再比如 PR 的整理工作。
标题怎么起，改动怎么概括，影响范围怎么交代，验证方式怎么写得让 reviewer 不费力。这种事情本身不算难，但很消耗注意力。一个好的 draft 往往就能省掉很多来回解释。

还有文档核对。
OpenAI 在文章里提到，涉及平台或 API 行为时，他们会让 Agent 去查当前文档，而不是凭记忆回答。这个原则我很喜欢。因为变化快的东西最怕“我记得好像是这样”。把“先查文档再回答”变成一种默认动作，本质上是在给系统加一个很必要的约束。

再往后，可能是发版前检查。
这种流程不一定每天发生，但一旦出错，往往会让人很后悔。版本号、changelog、示例是否可运行、release note 草稿、breaking changes 的确认，这些都很适合被慢慢沉淀下来。

它们有一个共同点：都不是创造性的工作，而是重复性的工作。
也正因为如此，它们才更值得被写进仓库。

我为什么会对这件事有一点点乐观

这几年关于 AI 的讨论很多，热闹也很多。
可越往后，我反而越容易被一些安静的东西打动。不是模型又刷新了哪个 benchmark，不是 Agent 又完成了多复杂的任务，而是像 Skills 这种，看起来没有那么耀眼，却很接近真实工作现场的设计。

它让我觉得，AI 真正进入工程，不一定是靠一次 dramatic 的替代，而更可能是靠这种缓慢的渗透：先接住一个小流程，再接住一种工作习惯，再把一种原本只存在于经验里的做法，慢慢变成仓库的一部分。

这件事的迷人之处在于，它不是在制造新的神话，而是在保存那些原本就有价值的东西。

我们一直说，软件工程是在把手工经验系统化。
某种程度上，Skills 只是把这句话继续往前推了一步。

以前我们把经验写成文档，写成脚本，写成 CI。
现在，我们开始尝试把经验写成 Agent 也能理解和使用的能力。

我挺喜欢这种变化。

因为它让我第一次觉得，Agent 不是突然闯进工程体系里的一个外来者。
它更像一个新的参与者。
而一个新的参与者，最重要的不是“它能做多少事”，而是“我们愿不愿意认真把自己的工作方式告诉它”。

说到底，skill 不是在教模型怎么工作。
它是在逼我们先想清楚，自己到底是怎么工作的。

看完了？说点什么呢

给 OpenClaw 装上眼睛：ARM64 服务器无头浏览器实战指南

Wed, 04 Mar 2026 15:47:51 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/openclaw-arm64-1772639270

很多同学选择在服务器上部署 OpenClaw 作为个人 AI 助手，但默认情况下 OpenClaw 无法访问网页。这对于一个需要"上网冲浪"的 AI 助手来说无疑是最大的限制。

好消息是，通过配置无头浏览器（Headless Browser），我们可以让 OpenClaw 具备网页访问、截图、自动化操作等能力。本文将详细介绍在 ARM64 架构服务器上的完整配置过程。

为什么需要浏览器

OpenClaw 本身是一个 AI 助手框架，要让它真正"智能"地帮你做事，浏览器能力必不可少：

实时信息获取：天气、新闻、股票等
网页自动化：自动填表、点击操作、定时签到
内容截图：把网页截图发给你
爬虫能力：抓取特定网站内容

ARM64 的困境

市面上的 Chrome 浏览器只有 amd64 架构版本，而很多同学使用 Apple Silicon Mac 或 ARM 服务器（如腾讯云 Lighthouse）。这导致常规的 Chrome 安装方法行不通。

解决方案有两个：

使用 Snap Chromium：Ubuntu 自带，但配置麻烦
使用 Playwright Chromium：跨平台，兼容 ARM64

本文选择方案 2，因为它更可控。

技术栈

组件	作用	备注
Playwright	浏览器自动化框架	提供 Chromium 二进制
Chromium	无头浏览器	ARM64 兼容版本
CDP (Chrome DevTools Protocol)	浏览器调试协议	OpenClaw 通过它控制浏览器

完整配置步骤

1. 安装 Playwright Chromium

npx playwright install chromium

Playwright 会自动下载适配当前架构的 Chromium。

2. 安装中文字体

无头浏览器截图中文字体需要单独安装：

sudo apt-get install -y fonts-wqy-microhei fonts-wqy-zenhei
fc-cache -fv

3. 启动浏览器

我们需要让 Chromium 以 CDP 模式启动：

nohup ~/.cache/ms-playwright/chromium-1208/chrome-linux/chrome \
  --headless=new \
  --no-sandbox \
  --disable-gpu \
  --remote-debugging-port=18800 \
  --disable-dev-shm-usage \
  --disable-software-rasterizer > /tmp/chrome.log 2>&1 &

# 验证启动成功
curl -s http://127.0.0.1:18800/json/version

4. 配置 OpenClaw

编辑 ~/.openclaw/openclaw.json，添加/修改 browser 部分：

{
  "browser": {
    "enabled": true,
    "attachOnly": false,
    "headless": true,
    "noSandbox": true,
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "0000FF"
      }
    }
  }
}

5. 验证配置

openclaw browser status
openclaw browser screenshot

进阶使用

自动启动脚本

为了保证服务器重启后浏览器能自动启动，建议添加 systemd 服务：

[Unit]
Description=OpenClaw Headless Browser
After=network.target

[Service]
Type=simple
User=liuyaowen
ExecStart=/home/liuyaowen/.cache/ms-playwright/chromium-1208/chrome-linux/chrome --headless=new --no-sandbox --disable-gpu --remote-debugging-port=18800 --disable-dev-shm-usage
Restart=on-failure

[Install]
WantedBy=multi-user.target

浏览器 Profile 持久化

如果需要保持登录状态，可以指定用户数据目录：

--user-data-dir=/path/to/profile

这样浏览器会记住 Cookie 和会话，登录一次即可。

常见问题

字体仍然乱码

检查字体是否正确加载：

fc-list :lang=zh

如果为空，可能需要手动下载字体到 Chrome 可访问的目录。

CDP 连接失败

检查端口是否被占用：lsof -i:18800
查看浏览器日志：cat /tmp/chrome.log
尝试重启浏览器

截图空白

可能是页面还没加载完成，增加等待时间：

await page.waitForLoadState("networkidle");

效果展示

配置完成后，你可以：

让 AI 帮你查天气：直接截图当前天气发给你
自动签到：每天定时打开网页点击签到按钮
内容监控：监控某个网页变化后通知你
生成报表：自动打开管理后台截图生成日报

总结

本文详细介绍了在 ARM64 服务器上为 OpenClaw 配置无头浏览器的完整过程。虽然过程比直接安装 Chrome 复杂一些，但通过 Playwright + CDP 的组合，我们最终实现了：

✅ ARM64 兼容
✅ 中文字体支持
✅ OpenClaw 集成
✅ 自动化能力

如果你也有在服务器上运行 AI 助手的需求，不妨试试这个方案。

参考资源

看完了？说点什么呢

xMemory：超越RAG的智能体记忆

Fri, 27 Feb 2026 12:19:50 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/codenotes/xmemory-intelligent-agent-memory-beyond-rag

ICML 2025 最佳论文力作：xMemory 能否彻底解决 RAG 的记忆困境？

在大模型 Agent 蓬勃发展的今天，如何让 AI 记住跨越数十次会话的对话历史，已成为决定 Agent 实用性的关键因素。当我们与一个陪伴数月的 AI 助手交流时，我们希望它记得我们之前讨论过的项目偏好、了解我们的工作习惯、甚至记住某次聊天中提到的关键细节。然而，标准的检索增强生成（RAG）方法在面对这种「智能体记忆」场景时，却暴露出惊人的局限性。

被忽视的根本问题：RAG 与智能体记忆的「基因不兼容」

在深入 xMemory 之前，我们有必要先理解这场变革的核心背景。传统 RAG 的设计初衷是什么？它是为了在海量的互联网文档、企业的知识库、或者数百篇研究论文中进行检索而生的。在这些场景中，被检索的文本片段来自不同来源，彼此之间往往主题各异、视角多元。正因为如此，传统的「top-k 相似度检索」能够有效地从大量异质候选项中筛选出与当前查询最相关的不同信息。

但智能体记忆的场景与上述情况截然不同。当一个用户与 Agent 进行跨越数周甚至数月的多轮对话时，存储的记忆呈现出一种独特的结构：高度相关、高度冗余、并且在时间维度上紧密相连。举例来说，如果用户在一个月内多次讨论同一个项目，那么关于这个项目的所有对话片段在语义空间中会形成一团密集的「云」—— 它们彼此之间的相似度极高，但与用户当前查询相关的核心信息可能只占这团密云中的几个点。

这带来一个尴尬的局面：当使用标准的 top-5 或 top-10 检索时，返回的结果往往是同一个主题下的近重复片段。换句话说，RAG 系统辛辛苦苦找到的「最相关」上下文，其实只是在反复讲述同一件事，而真正需要的前后时间关联的证据链，反而被算法当作冗余内容「优化」掉了。

xMemory 论文的核心洞察正是这一点：标准 RAG 假设的是「异构文本库」，而智能体记忆本质上是「同构记忆流」。这种根本性的不匹配，不是简单的调参所能解决的。

xMemory 的核心思路：解耦与聚合

面对这一挑战，xMemory 提出了一个优雅而深刻的解决方案——「解耦到聚合」（Decoupling-then-Aggregation）。这个理念的核心思想是：与其在原始对话片段的层面挣扎，不如先对记忆进行结构化组织，然后再反转这个结构来驱动检索。

具体而言，xMemory 构建了一个四级层次记忆结构：

原始消息（Messages）：用户与 Agent 之间的实际对话轮次
会话片段（Episodes）：将连续的多轮对话压缩为概括性的摘要，捕捉一个完整的话题单元
语义单元（Semantics）：从会话片段中提取的可重用的长期事实，比如用户的姓名、工作单位、偏好习惯等
主题（Themes）：将相关的语义单元组织在一起，形成更高层次的概念聚合

这个层次结构的妙处在于，它将原本混杂在时间流中的信息进行了「解耦」——语义单元被单独提取出来，不再与原始对话轮次绑定；同时通过主题层的「聚合」，建立了语义单元之间的高层关联。这就像是把一滩浑浊的河水先进行沉淀和分层，然后再按需取用。

两阶段自适应检索：代表选择与不确定性感知

仅仅构建出层次结构还不够，关键是如何在这个结构上进行高效的检索。xMemory 采用了两阶段的自适应检索策略，正是我认为这篇论文最精彩的部分。

第一阶段：kNN 图上的查询感知代表选择

在主题层和语义单元层，xMemory 维护了一个 k 最近邻（kNN）图结构。当用户提出一个查询时，系统不是直接去原始对话中找最相似的片段，而是先在主题层进行「代表选择」——从多个相关主题中挑选出最能覆盖不同知识方向的代表节点。

这里的关键创新在于一个权衡公式：

i* = argmax [α × 覆盖增益 + (1-α) × 查询相关性]

系统会平衡两个目标：一方面要选择与当前查询语义相关的内容，另一方面要确保选中的内容能够覆盖记忆中的不同知识面，避免总是扎堆在某个密集区域。这个过程是迭代的——每选择一个节点，就更新其邻居的覆盖状态，直到达到某个覆盖率阈值。

第二阶段：不确定性自适应的证据包含

选中了相关的语义单元之后，下一步是决定要包含哪些具体的会话片段来作为「证据」。xMemory 的做法非常巧妙：它不是一股脑地把所有相关片段都塞进上下文窗口，而是基于「不确定性减少」的原则来进行筛选。

具体实现方式是：对于每个候选的会话片段，系统会评估它是否能减少语言模型对答案的预测不确定性。只有当额外包含某个片段能够显著降低答案的不确定性时，这个片段才会被纳入最终的上下文。这种方法天然地实现了「按需获取」的效果——与答案直接相关的细节会被保留，而冗余的近重复内容会被过滤掉。

实验结果：效率与质量的双赢

xMemory 在两个基准数据集上进行了充分验证：LoCoMo（多会话对话数据集，包含平均约 300 轮对话）和 PerLTQA（个人长期记忆问答）。

实验结果令人印象深刻：

在 Qwen3-8B 模型上，xMemory 将平均 BLEU 从 28.51 提升到 34.48，F1 从 40.45 提升到 43.98
在 GPT-5 nano 上，同样取得了从 36.65 到 38.71（BLEU）和 48.17 到 50.00（F1）的提升
最令人惊叹的是 token 使用效率：在 Qwen3-8B 上，token 消耗从 9103 降至 4711，减少了近一半！

这意味着 xMemory 不仅提高了答案质量，还同时降低了成本。对于需要长期运行、成本敏感的 Agent 应用来说，这无疑是一个极具吸引力的特性。

更深层的启示

读罢这篇论文，我不禁思考它对整个 Agent 领域的更深层启示。

首先，它揭示了一个重要的设计原则：「记忆的组织方式决定了检索的效率」。当我们设计 Agent 的记忆系统时，不应该仅仅关注如何存储和索引，更应该思考如何将知识「解耦」——把长期有效的通用事实与短期有效的对话上下文分离，把核心概念与细枝末节分离。这种分离本身就是一种智能。

其次，xMemory 的「两阶段检索」也暗示了一个更广泛的设计模式：用粗粒度的代表选择来控制搜索空间，然后再用精细的不确定性评估来筛选内容。这种「先粗后精」的策略，在许多需要高效利用有限资源的场景中都具有普适价值。

最后，这篇论文也提醒我们重新审视 RAG 的边界。RAG 是一个强大的范式，但它并非万能。当应用场景的特性与 RAG 的原始假设不匹配时，我们需要勇敢地进行定制化甚至重构，而不是削足适履地硬套。

结语

ICML 2025 的这篇论文，为智能体记忆这个前沿领域注入了一剂强心针。xMemory 用「解耦-聚合」的层次化思路和「代表选择-不确定性感知」的两阶段检索，成功地化解了标准 RAG 在同构记忆流场景下的困境。更难能可贵的是，它在提升答案质量的同时，还显著降低了 token 成本——这对于任何关注实际部署的工程师来说，都是无法忽视的诱惑。

如果你正在构建需要长期记忆的 AI Agent，或者对检索增强技术有更深的兴趣，这篇论文绝对值得一读。它不仅提供了一套可落地的技术方案，更重要的是，它展示了一种思考问题的方式——当你发现现有的方法论与问题本质不匹配时，不妨回到问题的源头，重新设计整个系统。

看完了？说点什么呢

认知红利：工作前几年如何真正拉开差距

Mon, 23 Feb 2026 07:29:57 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/20260123

在职场早期，很多人习惯用“多加班、多做项目、多报培训”来证明努力。但这些本质上都属于线性努力——当你与他人处在同一维度竞争时，结果只会出现有限差距。
真正能够拉开差距的，往往是认知升级带来的非线性成长。

结合实践经验，可以将关键认知总结为四个方面。

一、决策质量：成长的放大器

职场中的关键节点——是否跳槽、是否转行、选择城市、选择公司、是否创业——本质上都是决策问题。
一旦决策正确，其增益往往远大于日常努力。

1.1 要什么不重要，不要什么更重要

很多人误以为“选择越多越好”，希望主业、副业、投资同时推进。但人的注意力与心力是有限资源，分散意味着难以形成突破。
在上升期，更有效的策略是：阶段性聚焦，一个阶段只解决一个核心目标。

1.2 少做决策，做对决策

决策并非越多越好。频繁决策往往伴随高错误率，并容易陷入连锁反应。例如跳槽失误后急于离开，容易在焦虑中再次做出错误选择，形成循环。
因此，更优策略是：把自己放在稳定环境中，用时间换取更高质量的关键决策。

1.3 决策慢，是为了方向正确

重大决策前需要刻意设置“冷却期”，系统收集信息并推演后果。
典型方法包括：

向真实经历者咨询一手经验
评估成功概率与失败成本
判断新选择是否真正解决当前问题

方向正确时，慢反而是最快的路径；方向错误时，速度只会放大损失。

二、高目标与高底线：避免“及格主义陷阱”

脱离考试体系后，绝大多数人的工作标准完全由自我设定，容易滑向“完成任务即可”的交差逻辑。
这种及格主义会逐渐降低个人底线，最终形成能力天花板。

2.1 从“交付任务”到“理解目标”

真正的高标准工作方式是：

理解任务背后的业务目标
主动思考更优方案
用结果价值而非动作完成度衡量自己

2.2 用标杆替代自我感动

一个有效策略是：为自己设置行业标杆。
持续对齐行业优秀个体的标准，可以显著抬高自己的质量基线。当接近或超越当前标杆时，再引入新的标杆，形成阶梯式成长。

三、风险偏好：差距往往诞生于此

在同等起点下，不同发展结果往往来自风险选择差异。
多数人倾向保守，追求确定性；但竞争优势往往隐藏在他人不敢投入的机会区间。

3.1 风险的本质是机会筛选器

组织或大公司通常不会重仓高不确定性但潜在高回报的机会，这为个人提供了竞争空间。
适度承担风险，本质是在更低竞争密度的赛道中获取成长。

3.2 失败并非负收益

对具备复盘能力的人而言，失败具有长期正向价值：

提供认知样本
修正决策模型
提升风险评估能力

人生本身具备较强纠错能力，一次失败通常难以造成不可逆后果。

四、主体性：从受害者叙事到主角叙事

主体性决定了一个人如何解释世界，也决定了其行动边界。

4.1 主体性弱的典型表现

将结果归因于环境、关系或运气
对外部评价高度依赖
容易陷入情绪内耗与自我否定

这种状态会削弱行动力，并持续降低成长预期。

4.2 主体性强的核心特征

建立自我评价体系
将一切经历视为学习样本
对外部评价保持参考而非依赖

换句话说，是以“主角心态”理解世界：发生的事情都是素材，而非束缚。

认知升级，才是早期最大的杠杆

工作前几年真正拉开差距的，并非投入时长，而是：

用高质量决策放大努力
用高目标抬升能力下限
用风险选择获取非对称机会
用主体性构建稳定内核

努力决定下限，认知决定上限。当认知结构发生变化时，同样的努力会产生完全不同的结果。

看完了？说点什么呢

AT 分布式事务使用详解

Wed, 17 Dec 2025 12:30:08 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/20251217

一、AT 模式概述

AT (Automatic Transaction) 模式是 Seata 中最常用的分布式事务模式，它通过自动生成反向 SQL 来实现事务的回滚，对业务代码侵入性极小。

二、核心配置详解

1. 全局配置 (registry.conf)

# 注册中心配置
registry {
  type = "nacos"  # 支持 nacos、eureka、redis、zk、consul、etcd3、sofa
  
  nacos {
    application = "seata-server"
    serverAddr = "127.0.0.1:8848"
    group = "SEATA_GROUP"
    namespace = ""
    cluster = "default"
    username = "nacos"
    password = "nacos"
  }
}

# 配置中心
config {
  type = "nacos"
  
  nacos {
    serverAddr = "127.0.0.1:8848"
    namespace = ""
    group = "SEATA_GROUP"
    username = "nacos"
    password = "nacos"
    dataId = "seata-server.properties"
  }
}

2. 客户端配置 (application.yml)

seata:
  enabled: true
  application-id: order-service  # 应用唯一标识
  tx-service-group: my_test_tx_group  # 事务组名称
  
  # 自动数据源代理
  enable-auto-data-source-proxy: true
  data-source-proxy-mode: AT  # AT 模式
  
  # 客户端配置
  config:
    type: nacos
    nacos:
      server-addr: 127.0.0.1:8848
      group: SEATA_GROUP
      namespace: ""
      data-id: seata-client.properties
  
  # 注册中心配置
  registry:
    type: nacos
    nacos:
      application: seata-server
      server-addr: 127.0.0.1:8848
      group: SEATA_GROUP
      namespace: ""
      cluster: default
  
  # 客户端详细配置
  client:
    rm:
      # 异步提交缓存队列长度
      async-commit-buffer-limit: 10000
      # 一阶段结果上报 TC 重试次数
      report-retry-count: 5
      # 自动刷新缓存中的表结构
      table-meta-check-enable: true
      # 分支事务与其它全局回滚事务冲突时锁策略
      report-success-enable: false
      # 是否上报一阶段成功
      saga-branch-register-enable: false
      # saga json parser
      saga-json-parser: fastjson
      # 一阶段全局提交结果上报 TC 重试次数
      saga-retry-persist-mode-update: false
      # 默认false，ture会提升性能
      saga-compensate-persist-mode-update: false
      # TCC 资源自动清理时间（小时）
      tcc-action-interceptor-order: -2147482648
      
    tm:
      # 一阶段全局提交结果上报 TC 重试次数
      commit-retry-count: 5
      # 一阶段全局回滚结果上报 TC 重试次数
      rollback-retry-count: 5
      # 默认全局事务超时时间（毫秒）
      default-global-transaction-timeout: 60000
      # 降级开关，默认 false
      degrade-check: false
      # 服务自检周期（毫秒）
      degrade-check-period: 2000
      # 允许降级检查的最小业务并发数
      degrade-check-allow-times: 10
      # 自检失败后开启降级的持续时间（毫秒）
      interceptor-order: -2147482648
      
    undo:
      # 是否开启二阶段回滚镜像校验
      data-validation: true
      # 二阶段回滚镜像校验失败的处理方式
      log-serialization: jackson
      # undo 序列化方式：jackson、fastjson、kryo
      log-table: undo_log
      # 自定义 undo 表名
      only-care-update-columns: true
      # 是否只生成被更新字段的镜像
      compress:
        enable: true
        # 是否压缩 undo_log
        type: zip
        # 压缩类型
        threshold: 64k
        # 压缩阈值
    
    # 负载均衡配置
    load-balance:
      type: RandomLoadBalance  # 负载均衡类型
      virtual-nodes: 10  # 虚拟节点数

3. 服务端配置 (Seata Server)

# 存储模式
store.mode=db  # file、db、redis

# 数据库存储配置
store.db.datasource=druid
store.db.dbType=mysql
store.db.driverClassName=com.mysql.cj.jdbc.Driver
store.db.url=jdbc:mysql://127.0.0.1:3306/seata?useSSL=false
store.db.user=root
store.db.password=root
store.db.minConn=5
store.db.maxConn=30
store.db.globalTable=global_table
store.db.branchTable=branch_table
store.db.queryLimit=100
store.db.lockTable=lock_table
store.db.maxWait=5000

# 事务、日志存储配置
server.recovery.committingRetryPeriod=1000
server.recovery.asynCommittingRetryPeriod=1000
server.recovery.rollbackingRetryPeriod=1000
server.recovery.timeoutRetryPeriod=1000

三、使用示例

1. 数据库准备

每个业务库都需要创建 undo_log 表：

CREATE TABLE `undo_log` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `branch_id` bigint(20) NOT NULL,
  `xid` varchar(100) NOT NULL,
  `context` varchar(128) NOT NULL,
  `rollback_info` longblob NOT NULL,
  `log_status` int(11) NOT NULL,
  `log_created` datetime NOT NULL,
  `log_modified` datetime NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `ux_undo_log` (`xid`,`branch_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

2. 业务代码

@Service
public class OrderServiceImpl implements OrderService {
    
    @Autowired
    private OrderMapper orderMapper;
    
    @Autowired
    private AccountService accountService;
    
    @Autowired
    private StorageService storageService;
    
    /**
     * 全局事务发起者，使用 @GlobalTransactional 注解
     */
    @Override
    @GlobalTransactional(name = "create-order", rollbackFor = Exception.class)
    public void createOrder(Order order) {
        // 1. 创建订单
        orderMapper.insert(order);
        
        // 2. 扣减库存（远程调用）
        storageService.deduct(order.getProductId(), order.getCount());
        
        // 3. 扣减账户余额（远程调用）
        accountService.debit(order.getUserId(), order.getMoney());
        
        // 4. 更新订单状态
        order.setStatus(1);
        orderMapper.update(order);
    }
}

// 库存服务
@Service
public class StorageServiceImpl implements StorageService {
    
    @Autowired
    private StorageMapper storageMapper;
    
    @Override
    public void deduct(Long productId, Integer count) {
        // 直接执行业务逻辑，无需额外事务注解
        storageMapper.deduct(productId, count);
    }
}

四、底层实现原理

1. 核心组件架构

TC (Transaction Coordinator) - 事务协调器
├── 全局事务管理
├── 分支事务管理
└── 全局锁管理

TM (Transaction Manager) - 事务管理器
├── 全局事务开启
├── 全局事务提交
└── 全局事务回滚

RM (Resource Manager) - 资源管理器
├── 分支事务注册
├── 分支事务上报
└── 分支事务提交/回滚

2. AT 模式执行流程

第一阶段（执行业务 SQL）

// DataSourceProxy 代理数据源
public class DataSourceProxy extends AbstractDataSourceProxy {
    
    @Override
    public ConnectionProxy getConnection() throws SQLException {
        Connection targetConnection = targetDataSource.getConnection();
        return new ConnectionProxy(this, targetConnection);
    }
}

// ConnectionProxy 核心逻辑
public class ConnectionProxy extends AbstractConnectionProxy {
    
    @Override
    public void commit() throws SQLException {
        try {
            // 注册分支事务
            register();
        } catch (TransactionException e) {
            // 识别并处理异常
            recognizeLockKeyConflictException(e, context.buildLockKeys());
        }
        
        try {
            // 执行本地事务提交
            targetConnection.commit();
        } catch (Throwable ex) {
            // 上报事务执行失败
            report(false);
            throw ex;
        }
        
        // 上报事务执行成功
        report(true);
    }
}

// ExecuteTemplate 执行模板
public class ExecuteTemplate {
    
    public static  T execute(
            SQLRecognizer sqlRecognizer,
            StatementProxy statementProxy,
            StatementCallback statementCallback,
            Object... args) throws SQLException {
        
        // 1. 前置镜像：查询修改前的数据
        TableRecords beforeImage = buildBeforeImage(statementProxy, sqlRecognizer);
        
        // 2. 执行业务 SQL
        T result = statementCallback.execute(statementProxy.getTargetStatement(), args);
        
        // 3. 后置镜像：查询修改后的数据
        TableRecords afterImage = buildAfterImage(statementProxy, sqlRecognizer);
        
        // 4. 构造 undo_log
        prepareUndoLog(beforeImage, afterImage);
        
        return result;
    }
}

核心数据结构

// 前置镜像和后置镜像数据结构 public class TableRecords { private TableMeta tableMeta; private List rows; // 行数据 public static class Row { private List fields; public static class Field { private String name; // 字段名 private int keyType; // 主键类型 private Object value; // 字段值 } } } // Undo Log 结构 public class BranchUndoLog { private String xid; // 全局事务ID private long branchId; // 分支事务ID private List sqlUndoLogs; // SQL回滚日志 public static class SQLUndoLog { private String sqlType; // INSERT/UPDATE/DELETE private String tableName; // 表名 private TableRecords beforeImage; // 前置镜像 private TableRecords afterImage; // 后置镜像 } }
第二阶段（提交或回滚）

提交流程：

public class AsyncWorker implements ResourceManagerInbound { /** * 异步提交分支事务 */ public BranchStatus branchCommit(String xid, long branchId, String resourceId) { // AT 模式下，一阶段已经提交，二阶段只需删除 undo_log return asyncCommit(xid, branchId, resourceId); } private BranchStatus asyncCommit(String xid, long branchId, String resourceId) { // 加入异步删除队列 addToCommitQueue(xid, branchId, resourceId); return BranchStatus.PhaseTwo_Committed; } // 异步删除 undo_log private void deleteUndoLog(String xid, long branchId) { String sql = "DELETE FROM undo_log WHERE xid = ? AND branch_id = ?"; executeUpdate(sql, xid, branchId); } }
回滚流程：

public class UndoLogManager { /** * 回滚分支事务 */ public void undo(DataSourceProxy dataSourceProxy, String xid, long branchId) throws SQLException { Connection conn = dataSourceProxy.getConnection(); try { // 1. 查询 undo_log String selectSQL = "SELECT * FROM undo_log WHERE xid = ? " + "AND branch_id = ? FOR UPDATE"; BranchUndoLog branchUndoLog = selectUndoLog(conn, xid, branchId); if (branchUndoLog == null) { return; // 已经回滚或提交 } // 2. 数据校验 if (!dataValidation(conn, branchUndoLog)) { throw new SQLException("Data validation failed"); } // 3. 生成反向 SQL 并执行 for (SQLUndoLog sqlUndoLog : branchUndoLog.getSqlUndoLogs()) { AbstractUndoExecutor undoExecutor = UndoExecutorFactory.getUndoExecutor( dataSourceProxy.getDbType(), sqlUndoLog); undoExecutor.executeOn(conn); } // 4. 删除 undo_log String deleteSQL = "DELETE FROM undo_log WHERE xid = ? " + "AND branch_id = ?"; executeUpdate(conn, deleteSQL, xid, branchId); conn.commit(); } catch (Exception e) { conn.rollback(); throw e; } } /** * 数据校验：比对当前数据和后置镜像 */ private boolean dataValidation(Connection conn, BranchUndoLog branchUndoLog) { for (SQLUndoLog sqlUndoLog : branchUndoLog.getSqlUndoLogs()) { TableRecords afterImage = sqlUndoLog.getAfterImage(); TableRecords currentRecords = queryCurrentRecords(conn, afterImage); // 比对数据是否一致 if (!afterImage.equals(currentRecords)) { return false; // 数据被脏写 } } return true; } }
反向 SQL 生成逻辑

// UPDATE 反向 SQL public class MySQLUndoUpdateExecutor extends AbstractUndoExecutor { @Override protected String buildUndoSQL() { TableRecords beforeImage = sqlUndoLog.getBeforeImage(); // 根据前置镜像生成 UPDATE 语句 StringBuilder sql = new StringBuilder("UPDATE "); sql.append(sqlUndoLog.getTableName()).append(" SET "); // 设置字段值为前置镜像的值 List fields = beforeImage.getRows().get(0).getFields(); for (int i = 0; i < fields.size(); i++) { if (i > 0) sql.append(", "); sql.append(fields.get(i).getName()).append(" = ?"); } // WHERE 条件（主键） sql.append(" WHERE "); appendWhereCondition(sql, beforeImage); return sql.toString(); } } // DELETE 反向 SQL（生成 INSERT） public class MySQLUndoDeleteExecutor extends AbstractUndoExecutor { @Override protected String buildUndoSQL() { TableRecords beforeImage = sqlUndoLog.getBeforeImage(); // 根据前置镜像生成 INSERT 语句 StringBuilder sql = new StringBuilder("INSERT INTO "); sql.append(sqlUndoLog.getTableName()).append(" ("); // 字段列表 List fields = beforeImage.getRows().get(0).getFields(); for (int i = 0; i < fields.size(); i++) { if (i > 0) sql.append(", "); sql.append(fields.get(i).getName()); } sql.append(") VALUES ("); for (int i = 0; i < fields.size(); i++) { if (i > 0) sql.append(", "); sql.append("?"); } sql.append(")"); return sql.toString(); } } // INSERT 反向 SQL（生成 DELETE） public class MySQLUndoInsertExecutor extends AbstractUndoExecutor { @Override protected String buildUndoSQL() { TableRecords afterImage = sqlUndoLog.getAfterImage(); // 根据后置镜像生成 DELETE 语句 StringBuilder sql = new StringBuilder("DELETE FROM "); sql.append(sqlUndoLog.getTableName()); sql.append(" WHERE "); appendWhereCondition(sql, afterImage); return sql.toString(); } }
3. 全局锁机制

public class LockManagerImpl implements LockManager { /** * 获取全局锁 */ public boolean acquireLock(List rowLocks) { // 锁的粒度：表名 + 主键值 // 例如：order_table:1,2,3 String lockKey = buildLockKey(rowLocks); // 向 TC 申请全局锁 boolean result = transactionCoordinator.acquireLock( xid, branchId, resourceId, lockKey); if (!result) { // 获取锁失败，进入重试逻辑 return retryAcquireLock(rowLocks); } return true; } private String buildLockKey(List rowLocks) { // 格式：table1:pk1,pk2;table2:pk3,pk4 Map> lockMap = new HashMap<>(); for (RowLock rowLock : rowLocks) { lockMap.computeIfAbsent( rowLock.getTableName(), k -> new HashSet<>() ).add(rowLock.getPk()); } return lockMap.entrySet().stream() .map(e -> e.getKey() + ":" + String.join(",", e.getValue())) .collect(Collectors.joining(";")); } }
五、性能优化配置

seata: client: rm: # 异步提交优化 async-commit-buffer-limit: 10000 undo: # 只记录更新字段 only-care-update-columns: true # 压缩 undo_log compress: enable: true type: zip threshold: 64k
六、常见问题

脏写问题：通过全局锁和数据校验解决

性能问题：使用异步提交、undo_log 压缩

undo_log 膨胀：定期清理历史数据

-- 清理 7 天前的 undo_log DELETE FROM undo_log WHERE log_created < DATE_SUB(NOW(), INTERVAL 7 DAY);
AT 模式通过自动生成前后镜像和反向 SQL，实现了对业务代码零侵入的分布式事务解决方案，是 Seata 最推荐使用的模式。

看完了？说点什么呢

Koupleless 合并部署完整教程

Tue, 16 Dec 2025 13:10:56 GMT

该渲染由 marked 生成，可能存在排版问题，最佳体验请前往：https://liuyaowen.cn/posts/default/20251216

目录

Koupleless 简介

合并部署概述

环境准备

基座改造

模块改造

模块瘦身

部署与验证

常见问题与解决方案

最佳实践

生产环境部署

Koupleless 简介

Koupleless 是一种模块化的 Serverless 技术解决方案，它能让普通应用以较低的代价演进为 Serverless 研发模式，让代码与资源解耦，轻松独立维护，同时支持秒级构建部署、合并部署、动态伸缩等能力，为用户提供极致的研发运维体验。

适用场景

应用构建发布慢或 SDK 升级繁琐：传统应用构建发布需要 6-10 分钟，使用 Koupless 可降至 10 秒级

长尾应用资源浪费：企业 80% 的应用 CPU 使用率低于 10%，合并部署可显著降低资源成本

研发协作效率低：多人开发一个应用时，需要统一时间窗口发布， Koupless 支持模块独立迭代

中台应用难以沉淀业务资产：通过基座沉淀公共能力，模块实现具体业务逻辑

微服务演进成本高：支持应用在单体、模块化、微服务架构间平滑过渡

合并部署概述

什么是合并部署

合并部署是指将多个独立的应用（在 Koupless 中称为"模块"）部署到同一个 JVM 进程中，共享基座的资源和依赖，但保持代码和运行时的隔离。

合并部署的优势

节省资源：多个模块共享基座的内存（Metaspace 和 Heap），CPU 使用率有效提升

快速启动：模块构建产物从数百 MB 瘦身到几十 MB，启动时间大幅缩短

简化运维：统一管理多个模块，降低维护成本

灵活扩展：支持动态添加、移除模块，无需重启基座

架构原理

Koupleless 基于 SOFAArk 框架实现类隔离和合并部署：

基座（Base）：提供公共依赖和基础能力，如 SpringBoot 框架、中间件 SDK 等

模块（Biz）：业务功能模块，依赖基座提供的公共能力

类加载机制：模块优先从自己的 ClassLoader 查找类，找不到再委托给基座 ClassLoader

环境准备

前置条件

JDK 8 或更高版本

Maven 3.6+

SpringBoot 2.x 或 3.x

可用的 IDE（IntelliJ IDEA、Eclipse 等）

版本选择

当前 Koupleless 主要版本：

0.5.6 2.2.14
工具准备

下载 Arkctl 工具（用于模块部署）：

# Mac/Linux wget https://github.com/koupleless/koupleless/releases/download/arkctl-release-0.2.0/arkctl-darwin-amd64 mv arkctl-darwin-amd64 /usr/local/bin/arkctl chmod +x /usr/local/bin/arkctl # Linux wget https://github.com/koupleless/koupleless/releases/download/arkctl-release-0.2.0/arkctl-linux-amd64 mv arkctl-linux-amd64 /usr/local/bin/arkctl chmod +x /usr/local/bin/arkctl

基座改造

1. 添加依赖

在基座的 pom.xml 中添加 Koupleless 基座依赖：

0.5.6 2.2.14 com.alipay.sofa.koupleless koupleless-base-starter ${koupleless.runtime.version} com.alipay.sofa web-ark-plugin
2. 配置应用名

在 application.properties 或 application.yml 中配置应用名：

# application.properties spring.application.name=base-application
3. 配置基座构建插件

在 pom.xml 的 build 部分添加基座构建插件：

com.alipay.sofa.koupleless koupleless-base-build-plugin ${koupleless.runtime.version} add-patch ${baseAppName}-dependencies-starter 0.0.1-SNAPSHOT org.springframework.boot spring-boot-maven-plugin repackage
4. 生成依赖 Starter

执行以下命令生成基座的依赖 starter：

mvn com.alipay.sofa.koupleless:koupleless-base-build-plugin::packageDependency -f pom.xml
这个命令会生成一个 ${baseAppName}-dependencies-starter 的依赖包，模块项目可以将其作为 parent 来继承基座的所有依赖。

5. 启动基座

完成上述配置后，可以直接通过 IDE 或命令行启动基座：

mvn spring-boot:run

模块改造

1. 创建模块项目

模块可以是现有的 SpringBoot 应用，也可以是新创建的项目。建议使用 Maven 多模块结构管理多个模块。

2. 配置模块依赖

在模块的 pom.xml 中添加模块依赖和打包插件：

0.5.6 2.2.14 com.alipay.sofa.koupleless koupleless-app-starter ${koupleless.runtime.version} provided com.example base-application-dependencies-starter 0.0.1-SNAPSHOT
3. 配置打包插件

在模块的 pom.xml 中添加 SOFAArk 打包插件：

${project.artifactId} com.alipay.sofa sofa-ark-maven-plugin ${sofa.ark.version} default-cli repackage true ./target module1 /module1 true rules.txt org.springframework.boot spring-boot-maven-plugin repackage
4. 配置模块瘦身

下载自动排包配置文件 rules.txt，放在模块的 conf/ark/ 目录下：

# 创建目录 mkdir -p conf/ark # 下载配置文件 wget https://github.com/koupleless/samples/raw/master/springboot-samples/slimming/log4j2/biz1/conf/ark/rules.txt -O conf/ark/rules.txt
rules.txt 内容示例：

# 排除的依赖（groupId:artifactId:version） excludes=org.springframework.boot:spring-boot-starter-logging,commons-logging:commons-logging # 排除的 groupId excludeGroupIds=org.slf4j # 排除的 artifactId excludeArtifactIds=logback-classic
5. 开发模块代码

创建模块的业务代码，例如 REST Controller：

package com.example.module1.controller; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import org.springframework.context.ApplicationContext; @RestController @RequestMapping("/") public class SampleController { private static final Logger LOGGER = LoggerFactory.getLogger(SampleController.class); @Autowired private ApplicationContext applicationContext; @GetMapping("/") public String hello() { String appName = applicationContext.getApplicationName(); LOGGER.info("{} web test: into sample controller", appName); return String.format("hello to %s deploy", appName); } @GetMapping("/health") public String health() { return "OK"; } }
6. 配置应用名

在模块的 application.properties 中配置应用名：

spring.application.name=module1

模块瘦身

为什么要模块瘦身

模块瘦身可以：

减小模块包大小：从数百 MB 降低到几十 MB

减少内存占用：降低 Metaspace 占用，基座可以安装更多模块

加快启动速度：模块启动时间从分钟级降低到秒级

提高部署效率：小体积包更容易传输和部署

瘦身原理

模块瘦身的核心思想是：移除模块中与基座重复的依赖，让模块复用基座的类

通过以下方式实现：

继承基座依赖 starter：模块以 ${baseAppName}-dependencies-starter 作为 parent

自动排包：使用 rules.txt 配置文件排除不需要的依赖

依赖委托：模块依赖设置为 provided 作用域，委托给基座加载

配置方法

方法一：继承基座依赖 starter（推荐）

在模块的 pom.xml 中配置：

com.example base-application-dependencies-starter 0.0.1-SNAPSHOT
这样模块会自动继承基座的所有依赖，无需手动配置版本。

方法二：手动配置依赖作用域

在模块的 pom.xml 中，将基座已有的依赖设置为 provided 作用域：

org.springframework.boot spring-boot-starter-web provided
方法三：使用排除配置

在 sofa-ark-maven-plugin 中配置排除项：

org.springframework,org.slf4j spring-boot-starter-logging
验证瘦身效果

构建模块并查看包大小：

# 构建模块 mvn clean package # 查看构建产物 ls -lh target/*.jar # 瘦身前 -rw-r--r-- 1 user staff 250M 1 15 10:00 module1-1.0.0.jar -rw-r--r-- 1 user staff 180M 1 15 10:00 module1-1.0.0-ark-biz.jar # 瘦身后 -rw-r--r-- 1 user staff 250M 1 15 10:30 module1-1.0.0.jar -rw-r--r-- 1 user staff 15M 1 15 10:30 module1-1.0.0-ark-biz.jar
可以看到，瘦身后的 ark-biz.jar 从 180M 降低到 15M，效果显著。

部署与验证

1. 启动基座

首先启动基座应用：

cd base-application mvn spring-boot:run
或使用 IDE 启动主类。

2. 构建模块

在模块项目中执行构建：

cd module1 mvn clean package
构建成功后会生成两个 jar 包：

module1-1.0.0.jar：普通 SpringBoot fat jar，可独立运行

module1-1.0.0-ark-biz.jar：Koupleless 模块包，用于合并部署

3. 使用 Arkctl 部署模块

使用 Arkctl 工具将模块部署到基座：

# 部署模块 arkctl deploy target/module1-1.0.0-ark-biz.jar # 或者使用 curl 命令 curl -X POST http://localhost:1238/installBiz \ -H "Content-Type: application/json" \ -d '{"bizName":"module1","bizVersion":"1.0.0","bizUrl":"file:///path/to/module1-1.0.0-ark-biz.jar"}'
4. 验证部署

部署成功后，可以通过以下方式验证：

查看模块状态

arkctl status
输出示例：

Biz count: 1 bizName: module1 bizVersion: 1.0.0 bizState: ACTIVATED mainClass: com.example.module1.Module1Application webContextPath: /module1
访问模块接口

# 访问模块1的接口 curl http://localhost:8080/module1/ # 输出: hello to module1 deploy curl http://localhost:8080/module1/health # 输出: OK
查看日志

在基座控制台可以看到模块启动日志：

[INFO] Install biz: module1, version: 1.0.0, state: ACTIVATED [INFO] Module module1 started successfully
5. 部署多个模块

重复上述步骤部署 module2：

cd module2 mvn clean package arkctl deploy target/module2-1.0.0-ark-biz.jar
验证多模块部署：

# 查看所有模块 arkctl status # 访问不同模块 curl http://localhost:8080/module1/ curl http://localhost:8080/module2/
6. 卸载模块

# 卸载指定模块 arkctl uninstall --bizName=module1 --bizVersion=1.0.0 # 或者使用 curl curl -X POST http://localhost:1238/uninstallBiz \ -H "Content-Type: application/json" \ -d '{"bizName":"module1","bizVersion":"1.0.0"}'

常见问题与解决方案

1. 类冲突问题

问题描述：模块和基座存在相同类名的类，导致类冲突。

解决方案：

使用类隔离机制，模块优先加载自己的类

公共类下沉到基座，模块通过依赖委托复用

避免在模块和基座中定义相同包名和类名的类

2. 静态字段共享问题

问题描述：多个模块共享静态字段，导致数据混乱。

解决方案：

使用 StaticFieldMapWrapper 适配静态字段：

import java.util.concurrent.ConcurrentHashMap; import java.util.function.Supplier; public class StaticFieldMapWrapper { private final ConcurrentHashMap classLoaderTMap = new ConcurrentHashMap<>(); private Supplier getDefaultMethod; public StaticFieldMapWrapper(Supplier getDefaultMethod) { this.getDefaultMethod = getDefaultMethod; } public T getOrPutDefault() { T t = classLoaderTMap.get(Thread.currentThread().getContextClassLoader()); if (t == null && getDefaultMethod != null) { t = getDefaultMethod.get(); classLoaderTMap.put(Thread.currentThread().getContextClassLoader(), t); } return t; } }
3. Dubbo 兼容性问题

问题描述：模块中使用 Dubbo 泛化调用时出现问题。

解决方案：

确保 Dubbo 相关依赖下沉到基座

为 Dubbo 配置正确的 ClassLoader 切换

参考官方 adapter 仓库的解决方案

4. Nacos 线程过多

问题描述：每个模块启动时创建 Nacos 客户端，导致线程数过多。

解决方案：

在基座中缓存 Nacos 客户端：

private static final Map CONFIG_SERVICE_MAP = new ConcurrentHashMap<>(); public static ConfigService getConfigService(Properties properties) { return CONFIG_SERVICE_MAP.computeIfAbsent(properties, k -> { try { return NacosFactory.createConfigService(k); } catch (NacosException e) { throw new RuntimeException(e); } }); }
5. 模块启动顺序问题

问题描述：模块之间有依赖关系，需要按顺序启动。

解决方案：

在基座中配置模块启动顺序

使用依赖关系控制启动顺序

避免循环依赖

6. 内存泄漏

问题描述：模块卸载后，内存没有释放，导致 Metaspace 持续增长。

解决方案：

确保模块卸载时清理所有资源（线程池、连接等）

使用弱引用管理缓存

定期重启基座或进行内存整理

7. Spring 上下文冲突

问题描述：模块和基座的 Spring Bean 冲突。

解决方案：

使用不同的 Bean 名称

模块中使用 @Primary 注解明确优先级

避免模块和基座定义相同的 Bean

生产环境部署

1. 部署架构

生产环境推荐部署架构：

用户流量 -> Nginx/SLB -> 基座应用（K8s Pod） | +-> 模块1 +-> 模块2 +-> 模块3
2. K8s 部署配置

基座 Deployment

apiVersion: apps/v1 kind: Deployment metadata: name: base-application spec: replicas: 3 selector: matchLabels: app: base-application template: metadata: labels: app: base-application spec: containers: - name: base-application image: registry.example.com/base-application:1.0.0 ports: - containerPort: 8080 env: - name: MODULE_AUTO_INSTALL value: "true" - name: MODULE_OSS_ENDPOINT value: "oss-cn-region.aliyuncs.com" - name: MODULE_OSS_BUCKET value: "koupleless-modules" livenessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /ready port: 8080 initialDelaySeconds: 30 periodSeconds: 5 volumeMounts: - name: module-storage mountPath: /opt/modules volumes: - name: module-storage persistentVolumeClaim: claimName: module-pvc
模块发布流水线

# 模块 CI/CD Pipeline stages: - build - test - package - deploy build_module: stage: build script: - mvn clean compile test_module: stage: test script: - mvn test package_module: stage: package script: - mvn clean package - cp target/*.ark-biz.jar module.ark-biz.jar artifacts: paths: - module.ark-biz.jar deploy_module: stage: deploy script: # 上传模块到 OSS - ossutil cp module.ark-biz.jar oss://koupleless-modules/module1/${CI_COMMIT_SHA}.ark-biz.jar # 通知基座更新模块 - curl -X POST http://base-service:8080/install \ -H "Content-Type: application/json" \ -d '{"module":"module1","version":"'${CI_COMMIT_SHA}'"}'
3. 模块动态部署

方案一：OSS 监听模式

基座监听 OSS 目录变化，自动部署新模块：

@Service public class ModuleDeploymentService { @Autowired private OssClient ossClient; @Scheduled(fixedDelay = 5000) public void checkModuleUpdates() { // 检查 OSS 上的模块版本 List modules = getModuleList(); for (String module : modules) { String latestVersion = getLatestVersion(module); String currentVersion = getCurrentVersion(module); if (!latestVersion.equals(currentVersion)) { // 下载新模块 downloadModule(module, latestVersion); // 卸载旧模块 uninstallModule(module, currentVersion); // 安装新模块 installModule(module, latestVersion); } } } }
方案二：配置中心模式

通过配置中心控制模块部署：

# 配置中心配置 modules: module1: version: 1.0.0 enabled: true healthCheck: /health module2: version: 2.0.0 enabled: true healthCheck: /health
基座监听配置变化：

@NacosConfigListener(dataId = "modules.json") public void onModuleConfigChange(String config) { ModulesConfig modulesConfig = JSON.parseObject(config, ModulesConfig.class); // 对比配置差异 List changes = compareModuleConfig(modulesConfig); // 应用变更 for (ModuleChange change : changes) { switch (change.getType()) { case INSTALL: installModule(change.getModule()); break; case UNINSTALL: uninstallModule(change.getModule()); break; case UPDATE: updateModule(change.getModule()); break; } } }
下面把教程里没展开的两件事一次讲透：

静态合并部署（Static Packaged Deployment）——一次性把基座 + N 个模块打成一个可执行 Fat Jar，启动即“全员就位”；

端口隔离——让每个模块真的监听自己的端口，实现“进程内多 WebServer”。

方案三、静态合并部署（Static Packaged Deployment）

适用场景

上线流程极简，不允许运维侧再敲 arkctl deploy；

容器镜像只启一个进程，K8s liveness/readiness 探针直接探测基座即可；

模块版本固定，不需要热卸载/热加载。

打包思路
基座 pom 里把各模块的 ark-biz.jar 当资源一起打进 BOOT-INF/lib 目录；
基座启动时借助 SOFAArk 的 “static-biz” 机制，让这些 ark-biz.jar 随基座生命周期一起 install + start。

实操步骤
step-1 模块端正常 mvn package 得到 moduleX-1.0.0-ark-biz.jar
step-2 基座 pom 增加 profile（只在打静态包时激活）

static-pack com.example module1 1.0.0 ark-biz jar com.example module2 1.0.0 ark-biz jar
step-3 基座启动类加 @StaticBiz 注解（0.5.6+ 支持），告诉 SOFAArk 把 classpath 下所有 ark-biz.jar 静态安装：

@SpringBootApplication @StaticBiz // 关键 public class BaseApplication { public static void main(String[] args) { SpringApplication.run(BaseApplication.class, args); } }
step-4 打静态包

mvn clean package -Pstatic-pack
生成的 base-application-1.0.0-exec.jar 里同时包含 module1-ark-biz.jar & module2-ark-biz.jar；
java -jar base-application-1.0.0-exec.jar 启动后，arkctl status 能看到两个模块已经是 ACTIVATED，无需再 deploy。

让模块监听自己的端口

默认行为

所有模块与基座共用同一个嵌入式 Tomcat（端口 8080），仅靠 webContextPath 区分；

好处：节省线程、节省内存；

坏处：无法“端口级”隔离，也做不到“模块单独暴露管理口”。

Koupleless 0.5.6 开始支持 “多 WebServer 模式”，即每个模块可以起独立的 Netty/Tomcat，真正 bind 自己的端口。

模块端增加依赖

com.alipay.sofa web-ark-plugin multi-web provided

配置端口 & 上下文

# module1/application.yml server: port: 8081 # 模块独占 servlet: context-path: / # 可以为 / spring: application: name: module1

打包插件声明

com.alipay.sofa sofa-ark-maven-plugin module1 / true

部署验证
基座仍跑 8080，module1 会额外监听 8081，module2 可再配 8082，互不影响；
curl http://localhost:8081/ 直接返回模块 1 的响应，无需再加前缀。

注意

端口多占 n 个，内存/线程也会相应增加，按需权衡；

生产环境需在 K8s Service 里把 8081、8082… 也声明出来，或走 Istio 多端口即可。

参考资源

官方文档：https://koupleless.io/docs/

GitHub 仓库：https://github.com/koupleless/koupleless

示例代码：https://github.com/koupleless/samples

社区支持：https://github.com/koupleless/koupleless/issues

看完了？说点什么呢