一、缘起：一次“反直觉”的Vuex重构

几年前，我在维护一个多版本并行的SaaS项目时，踩到了一个经典的坑：两个不同版本的页面共用同一个Vuex Store，导致修改A版本的数据，B版本也跟着“抽风”。

当时的我，根本不懂什么是闭包，只知道“两个页面不该共享同一份数据”。于是，我凭着直觉写了一个“工厂函数”：

function createVersionStore() {
  return {
    state: { data: {} },
    mutations: { ... }
  };
}

// 为每个版本创建独立的Store实例
const storeV1 = new Vuex.Store(createVersionStore());
const storeV2 = new Vuex.Store(createVersionStore());

当时只觉得“这样就能隔离数据了”，完全没想到，这个“灵光一闪”的操作，竟然暗合了闭包最精髓的设计模式——函数工厂。

直到今天，当我彻底搞懂闭包后，才恍然大悟：原来当年那个“瞎猫碰死耗子”的解决方案，正是闭包在工程化开发中的最佳实践。

二、闭包到底是什么？

很多教程会把闭包讲得很玄乎，什么“函数套函数”“作用域链”“垃圾回收”……但对我来说，真正理解闭包，是从三个关键认知突破开始的：

认知突破1：闭包不是“刻意写的”，而是“自然形成的”
闭包的本质，是函数 + 函数被创建时的环境。只要一个函数能访问到它外部作用域的变量，闭包就自动形成了。

最经典的例子：

function outer() {
  let count = 0;
  return function inner() {
    count++;
    console.log(count);
  };
}

const counter = outer();
counter(); // 1
counter(); // 2

这里，inner函数“记住”了outer里的count变量，即使outer已经执行完毕。这就是闭包——函数带着它的“背包”（外部环境）去流浪。

认知突破2：闭包的“生死”由引用决定
闭包之所以能“长生不老”，是因为内部函数持有了外部变量的引用。只要内部函数还活着，外部变量就不会被垃圾回收。

但这也带来了内存泄漏的风险。比如：

function leak() {
  let bigData = new Array(1000000).fill('data');
  return function() {
    console.log('hello'); // 没用到bigData，但bigData仍被闭包持有
  };
}

const fn = leak();
// bigData永远无法被回收，除非fn = null

所以，闭包的“销毁”很简单：断开所有对内部函数的引用，垃圾回收器会自动清理。

认知突破3：闭包不是单例，每次调用都是“新实例”
这是我最容易混淆的点。很多人以为闭包是“全局共享”的，其实不然。

每次调用外部函数，都会创建一套全新的闭包环境。就像工厂生产产品，每次createCounter()都会生成一个独立的计数器：

const c1 = createCounter();
const c2 = createCounter();

c1(); // 1
c2(); // 1（互不干扰！）

这正是我当年Vuex方案的底层原理——用闭包实现数据隔离。

三、闭包的三大“陷阱”与破解之道

理解了原理，还要知道闭包在实际开发中的“坑”。

陷阱1：循环中的闭包（var的诅咒）

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 1000);
}
// 输出：3, 3, 3（而不是0,1,2）

原因：var是函数作用域，所有定时器共享同一个i。循环结束时i=3，所以都输出3。

解决方案：用let（块级作用域）或立即执行函数（IIFE）：

for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 1000);
}
// 输出：0, 1, 2

陷阱2：React Hooks的“闭包陷阱”
在React中，闭包会“记住”组件渲染时的状态快照：

function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => {
      console.log(count); // 永远是0！
      setCount(count + 1);
    }, 1000);
  }, []); // 依赖为空，只执行一次
}

原因：useEffect只在首次渲染时执行，闭包捕获的是count=0的快照。后续状态更新不会重新创建闭包。

解决方案：用函数式更新setCount(c => c + 1)，或把count加入依赖数组。

陷阱3：this指向丢失
闭包不保存this，只保存词法作用域：

const obj = {
  name: '张三',
  getName: function() {
    return function() {
      console.log(this.name); // undefined（this指向window）
    };
  }
};

obj.getName()();

解决方案：用箭头函数或that = this保存上下文。

四、闭包的终极真相：环境引用 vs 值快照

这是我最深的认知突破。

很多人（包括曾经的我）以为闭包捕获的是“变量的副本”，其实不完全对。

真相是：闭包捕获的是“环境的引用”，但对基本类型表现为“值快照”，对引用类型表现为“共享数据”。

• 基本类型（数字、字符串） ：闭包像是拍了一张“快照”，后续外部变化不影响闭包内的值。
• 引用类型（对象、数组） ：闭包持有的是“指针”，修改对象会影响所有持有该引用的闭包。

但关键在于：如果对象是在外部函数内部创建的，每次调用都会生成新对象，闭包之间依然隔离。

这正是我当年Vuex方案的精髓——用函数工厂生成独立的数据空间。

五、闭包的工程化价值：从理论到实践

闭包不是面试造火箭的玩具，而是解决实际问题的利器：

• 数据私有化：模拟私有变量，防止外部污染。
• 模块化开发：Vuex/Pinia的Store工厂、Webpack的模块系统，底层都是闭包。
• 函数柯里化：动态生成定制函数。
• 事件处理与回调：保存上下文状态。

最让我感慨的是，当年那个“不懂闭包”的我，凭着“不想写重复代码”的直觉，竟然写出了符合行业标准的解决方案。这说明，好的工程直觉，往往比死记硬背理论更重要。

六、结语：闭包不是魔法，是思维工具

闭包不是什么神秘的魔法，它只是JavaScript函数作用域的自然结果。理解闭包，不是为了应付面试，而是为了写出更健壮、更可维护的代码。

从“瞎猫碰死耗子”到“彻底通透”，我的闭包之旅告诉我：真正的掌握，不是记住定义，而是能在实际问题中识别并运用它。

希望我的经历，能帮你少走一些弯路。毕竟，闭包这东西，一旦通了，就再也回不去了。

互动话题：你在项目中用过闭包解决过什么实际问题？欢迎在评论区分享！

参考资料：MDN闭包文档、Vue/Pinia源码、JavaScript高级程序设计

作者：一个从Vuex工厂函数悟出闭包真谛的前端开发者

Tauri Android 打包原理与实战指南

基于 JoyaLand 项目的实际打包经验整理，记录原理、流程与踩坑解决方案。

一、Tauri Android 打包架构原理

1.1 整体架构

┌─────────────────────────────────────────────┐
│              JoyaLand Android App            │
├──────────────────┬──────────────────────────┤
│   前端层 (WebView) │   原生层 (Rust/JNI)      │
│  ┌────────────┐  │  ┌────────────────────┐  │
│  │ HTML/CSS   │  │  │  tauri-android     │  │
│  │ JavaScript │◄─┼─►│  (Kotlin/Java)     │  │
│  │ Canvas 2D  │  │  ├────────────────────┤  │
│  └────────────┘  │  │  libapp_lib.so     │  │
│                  │  │  (Rust 编译产物)    │  │
└──────────────────┴──────────────────────────┘
         ▲
         │ Vite 构建的静态资源
         │ (dist/ 目录)

Tauri Android 的核心思路：

• 前端：使用系统 WebView 渲染 HTML/JS/CSS（无需打包 Chromium）
• 后端：Rust 代码编译为 .so 动态库，通过 JNI 被 Kotlin/Java 调用
• 桥接：Tauri 的 IPC 机制连接前后端（命令调用、事件通知）

1.2 构建工具链

Vite (前端构建)
    ↓ 生成 dist/
Cargo (Rust 编译)
    ↓ 交叉编译 4 个 ABI 的 .so 文件
Gradle (Android 构建)
    ↓ 打包 APK/AAB
apksigner (APK 签名)
    ↓
最终 APK

1.3 支持的 Android ABI

二、环境准备

2.1 必要工具

2.2 Rust Android 编译目标

rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi
rustup target add i686-linux-android
rustup target add x86_64-linux-android

2.3 环境变量

# Windows PowerShell
$env:ANDROID_HOME = "D:\Android\Sdk"
$env:PATH += ";D:\Android\Sdk\platform-tools"

三、打包完整流程

3.1 初始化 Android 项目

npx tauri android init

执行后会：

1. 检测 ANDROID_HOME 环境变量，找到 SDK 路径
2. 自动检测并使用已安装的 NDK（如 D:\Android\Sdk\ndk\29.0.x）
3. 安装 4 个 Android Rust 编译目标（如未安装）
4. 在 src-tauri/gen/android/ 生成 Android Gradle 项目

生成的目录结构：

src-tauri/gen/android/
├── app/
│   ├── build.gradle.kts
│   ├── src/main/
│   │   ├── java/com/liupe/joyaland/generated/  ← Tauri 自动生成的 Kotlin 桥接代码
│   │   └── jniLibs/                            ← 编译好的 .so 文件（symlink）
│   └── proguard-rules.pro
├── buildSrc/                                   ← 包含自定义 BuildTask（调用 Cargo）
├── gradle/wrapper/
│   └── gradle-wrapper.properties               ← Gradle 版本配置
├── gradlew.bat                                 ← Gradle Wrapper 启动脚本
└── settings.gradle

3.2 构建 APK

$env:ANDROID_HOME = "D:\Android\Sdk"
npx tauri android build --apk

构建过程分为以下阶段：

阶段 1：前端构建

npm run build → Vite → dist/

• 执行 tauri.conf.json 中配置的 beforeBuildCommand
• 生成静态资源到 dist/ 目录

阶段 2：Rust 交叉编译（最耗时）

Cargo → 4 个 .so 文件

• 为每个 ABI 分别运行 cargo build --release --target <abi>
• 使用 NDK 中的交叉编译工具链（如 aarch64-linux-android24-clang）
• 首次编译需要 20-60 分钟，后续增量编译 1-5 分钟

编译产物位置：

src-tauri/target/aarch64-linux-android/release/libapp_lib.so
src-tauri/target/armv7-linux-androideabi/release/libapp_lib.so
src-tauri/target/i686-linux-android/release/libapp_lib.so
src-tauri/target/x86_64-linux-android/release/libapp_lib.so

阶段 3：Gradle 打包

gradlew assembleUniversalRelease → APK

• Gradle 调用 buildSrc 中的 BuildTask 触发各 ABI 的 Rust 编译
• Kotlin 代码编译（Tauri 桥接层）
• 资源合并、R8 代码压缩混淆
• 打包为 APK

输出位置：

src-tauri/gen/android/app/build/outputs/apk/universal/release/
    app-universal-release-unsigned.apk

阶段 4：APK 签名

# 1. 生成签名密钥（只需一次）
keytool -genkey -v -keystore joyaland-release.keystore `
  -alias joyaland -keyalg RSA -keysize 2048 -validity 10000 `
  -storepass <密码> -keypass <密码> `
  -dname "CN=JoyaLand, OU=Dev, O=liupe, L=Beijing, S=Beijing, C=CN"

# 2. 签名 APK
apksigner sign --ks joyaland-release.keystore `
  --ks-key-alias joyaland `
  --ks-pass pass:<密码> --key-pass pass:<密码> `
  --out JoyaLand-v1.0.0.apk `
  app-universal-release-unsigned.apk

⚠️ 重要：joyaland-release.keystore 文件必须妥善保管。发布到应用商店后，更新版本必须使用同一密钥签名，否则无法覆盖安装。

四、实际遇到的问题与解决方案

问题 1：ANDROID_HOME 未设置导致初始化失败

现象：

Error: ANDROID_HOME is not set

或自动探测到错误路径（C:\Users\xxx\AppData\Local\Android\Sdk），与实际使用的 SDK 路径不符。

原因：

• 系统环境变量未配置，或配置了不同路径的 SDK
• Tauri 会自动探测系统默认路径，不一定是用户实际使用的路径

解决方案：

# 每次打包前手动设置（临时）
$env:ANDROID_HOME = "D:\Android\Sdk"

# 或永久设置系统环境变量（推荐）
[System.Environment]::SetEnvironmentVariable("ANDROID_HOME", "D:\Android\Sdk", "User")

问题 2：Rust target 下载失败（文件重命名错误）

现象：

error: component download failed for rust-std-i686-linux-android: 
could not rename downloaded file from '...partial' to '...': 
系统找不到指定的文件。(os error 2)

原因：

• 文件已存在于缓存中，但 rustup 下载流程中遇到并发/临时文件问题
• 实际上 target 已经安装成功，只是报了错误

解决方案：

# 验证是否实际已安装
rustup target list --installed
# 如果列表中有目标，则忽略错误继续即可

问题 3：Gradle 网络超时（无法下载 gradle-8.14.3-bin.zip）

现象：

Downloading https://services.gradle.org/distributions/gradle-8.14.3-bin.zip
Exception in thread "main" java.io.IOException: ... failed: timeout

原因：

• 国内网络无法访问 services.gradle.org
• gradle-wrapper.properties 配置的是从网络下载 Gradle

解决方案：直接修改 gradlew.bat，绕过 Wrapper，调用本地已安装的 Gradle

修改 src-tauri/gen/android/gradlew.bat：

@if "%DEBUG%" == "" @echo off

if "%OS%"=="Windows_NT" setlocal
set DIRNAME=%~dp0
if "%DIRNAME%" == "" set DIRNAME=.
set APP_BASE_NAME=%~n0
set APP_HOME=%DIRNAME%
for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi

@rem 直接使用本地安装的 Gradle，跳过网络下载
set GRADLE_CMD=D:\tool\gradle-8.14\bin\gradle.bat

if not exist "%GRADLE_CMD%" (
  echo ERROR: Gradle not found at %GRADLE_CMD%
  exit /b 1
)

"%GRADLE_CMD%" %*

:end
if "%ERRORLEVEL%"=="0" goto mainEnd
:fail
if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
exit /b 1
:mainEnd
if "%OS%"=="Windows_NT" endlocal
:omega

问题 4：Kotlin 增量编译失败（不同盘符路径冲突）

现象：

java.lang.IllegalArgumentException: this and base files have different roots: 
C:\Users\xxx\.cargo\registry\...\tauri-2.10.3\...\ActivityCallback.kt 
and E:\WeChatProjects\JoyaLand\src-tauri\gen\android

原因：

• Kotlin 增量编译器要求所有源文件在同一个根路径下
• Tauri 的 Kotlin 源文件在 C 盘（Cargo 注册表），项目在 E 盘，跨盘符导致相对路径计算失败

解决方案：

• 此错误会自动 fallback 到非增量编译模式（Using fallback strategy: Compile without Kotlin daemon）
• 不影响最终 APK 生成，可以忽略

若要根本解决，可将整个项目放在与 Cargo 注册表相同的盘符下（如 C 盘）。

问题 5：Gradle 版本不匹配

现象：

• 本地安装 Gradle 8.14，但 gradle-wrapper.properties 要求 8.14.3
• 直接用 gradlew 会下载 8.14.3，网络超时失败

解决方案：

• 直接修改 gradlew.bat 调用本地 Gradle 8.14（见问题 3 的解决方案）
• Gradle 8.14 与 8.14.3 兼容，实际构建无影响

问题 6：JDK 版本过高导致警告

现象：

Kotlin does not yet support 24 JDK target, falling back to Kotlin JVM_22 JVM target
Java compiler version 24 has deprecated support for compiling with source/target version 8.

原因：

• 系统 JDK 版本为 24，Kotlin 最高支持 JVM 22 目标
• Android 项目的 sourceCompatibility 设置为 Java 8，JDK 24 已弃用此设置

影响：仅为警告，不影响 APK 构建，可正常使用。

根本解决（可选）：安装 JDK 17 或 JDK 21 并配置 JAVA_HOME。

问题 7：APK 为未签名版本，无法安装

现象：

• 构建完成后的 APK 文件名为 app-universal-release-unsigned.apk
• 直接安装到手机报错

解决方案：使用 apksigner 工具签名（见第三节阶段 4）

五、关键配置文件说明

tauri.conf.json（部分）

{
  "build": {
    "frontendDist": "../dist",
    "devUrl": "http://localhost:1420",
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build"
  },
  "app": {
    "windows": [{
      "width": 450,
      "height": 950,
      "resizable": false,
      "center": true
    }]
  }
}

gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
distributionPath=wrapper/dists
zipStorePath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME

在网络受限环境下，此文件的 distributionUrl 会导致超时。已通过修改 gradlew.bat 绕过。

六、常用命令速查

# 设置 Android SDK 路径（每次打包前执行）
$env:ANDROID_HOME = "D:\Android\Sdk"

# 初始化 Android 项目（只需一次）
npx tauri android init

# 构建 APK
npx tauri android build --apk

# 构建 debug APK（开发调试用）
npx tauri android build --apk --debug

# 签名 APK
$buildTools = "D:\Android\Sdk\build-tools\36.1.0"
& "$buildTools\apksigner.bat" sign `
  --ks joyaland-release.keystore `
  --ks-key-alias joyaland `
  --ks-pass pass:joyaland123 `
  --key-pass pass:joyaland123 `
  --out JoyaLand-v1.0.0.apk `
  app-universal-release-unsigned.apk

# 验证签名
& "$buildTools\apksigner.bat" verify --verbose JoyaLand-v1.0.0.apk

# 通过 ADB 安装到已连接设备
adb install JoyaLand-v1.0.0.apk

七、首次 vs 增量构建时间对比

Rust 编译缓存保存在 src-tauri/target/ 目录，体积较大（数 GB），请勿随意删除。

八、输出文件位置

上一篇我得出了一个结论：AI 在电商链路里真正有价值的地方，是认知负担最重和人工成本最高的两类场景。售后工单是后者的典型——规则明确、量大、重复，AI 来做意图识别再合适不过。

但写完那篇之后，我一直在想一个没展开的问题：

AI 做出判断之后，然后呢？

这个"然后"，大多数产品设计都跳过了。技术团队花了很多精力让模型的意图识别更准，却很少认真想：当 AI 已经判断出"这个客户想退货"，界面接下来应该发生什么？自动触发退货流程？等客服确认？还是让客户自己再按一次？

这条边界——什么时候 AI 该自己执行，什么时候必须等人——不是技术问题，是设计问题。

你有没有在这里停留，然后思考一下，下一步应该是什么样的？

从一个工单说起

想象这样一条售后消息：

"我上周买的外套，收到发现颜色和图片差太多了，能退吗？"

对一个训练充分的意图分类模型来说，这条消息的处理不难：退货意图，原因是色差，属于"货不对板"类目，符合平台退货政策。置信度 0.94。

好，模型判断完了。现在问题来了：

界面该做什么？

选项 A：直接自动发起退货申请，给客户发确认短信。
选项 B：在客服工作台标注"建议：退货申请（置信度 94%）"，等客服点击确认。
选项 C：给客户发一条消息："您是否需要申请退货？"，等客户自己确认。
选项 D：根据置信度动态决定——高于某个阈值自动执行，低于阈值转人工。

这四个选项，背后是四种完全不同的产品逻辑。没有哪个天然正确，但选哪个会直接影响：客户体验、客服工作量、出错之后谁来担责、以及商家对这套系统的信任程度。

工单的完整旅程：AI 介入的三个阶段

在讨论"自动执行还是人工确认"之前，先把一条工单从进来到处理完的完整路径摊开来看。

这张图里有几个细节值得注意：

第一，置信度和风险是两个独立维度，不能只看置信度高低；

第二，无论哪条路径，操作记录都是必须的，不是可选项；

第三，人工处理的结果应该回流到模型，这个闭环在很多产品里是缺失的。

四类工单，四种处置

把意图清晰度和出错风险交叉，能得到四种典型工单，每一种的正确处置方式都不一样：

第四类是最容易被忽视的。"退退退"这个词在字面上是退货意图，模型可能识别出高置信度的退货分类——但这条消息需要的不是触发退货流程，而是先安抚情绪。纯文本意图识别不等于理解语境，这是 AI 介入工单处理时最容易翻车的地方。

「 做了一个可以玩的版本，→ 在线体验 」

出错了，界面怎么兜底

AI 判断出错不是概率问题，是必然会发生的事。问题不是"怎么避免出错"，而是"出错之后系统怎么行动"。

常见的出错场景有三种：

场景一：自动执行了错误动作。 客户说"我想换个颜色"，AI 识别为退货并自动发起了退货申请。客户收到退货确认短信，困惑，打电话进来。这时候客服看到的界面应该是：清晰标注"系统于 10 分钟前自动发起退货申请"，一键撤销，同时自动生成一条道歉模板消息。如果这个撤销入口藏在三层菜单里，出错的代价就从"小麻烦"变成了"客户愤怒"。

场景二：置信度虚高，判断方向错了。 "我朋友说这个质量不好，我有点担心"——这条消息的关键词触发了模型的"质量投诉"分类，置信度 88%。但实际上客户只是在表达顾虑，还没有购买，根本没有工单可以处理。这类情况，界面的兜底方式是：在工作台显示判断依据（"触发词：质量不好"），让客服能快速理解为什么 AI 这么判断，并在纠正之后把这条记录标注为"误判样本"。

场景三：正确意图，错误时机。 客户下单后两小时内发消息"我想取消订单"，AI 正确识别为取消意图，自动触发取消流程——但这时候订单已经进入打包环节，取消会触发额外的仓储费用。AI 不知道订单状态，做了一个技术上正确但业务上错误的决定。这个场景说明：意图识别和动作执行之间，需要一层业务规则校验，不能让模型的输出直接触发操作。

我尝试建立一个判断框架

反复想这个问题之后，我觉得影响"自动执行 vs 人工确认"这条边界的，主要是三个变量：

1. 出错的代价有多高？

同样是退货场景，"误触发了一个客户不想退的退货申请"，代价是：客户困惑、需要撤销、产生额外沟通。麻烦，但可以修复。

换一个场景：AI 判断某个账号存在异常交易，自动冻结——如果判断错了，代价是：正常用户被误封，投诉升级，信任崩塌。不可轻易修复。

出错代价越高，越需要人工确认作为缓冲。 这个逻辑不复杂，但容易被"模型准确率已经很高了"这个理由绕过。准确率 99% 听起来很高，但如果每天处理一万条工单，就有一百条出错——这一百条落在真实用户身上，每一条都是一个完整的糟糕体验。

2. 可逆性如何？

自动执行之后，这个动作能撤销吗？

退货申请发出了，可以撤销。优惠券发出去了，不好收回。退款打出去了，追回来很麻烦。物流揽件指令发出去了，基本不可逆。

可逆性越低，越需要在执行前确认。 这和出错代价是两个维度——有些事出错代价不高，但就是无法撤销；有些事代价很高，但可以事后补救。两者叠加才是完整的风险评估。

3. 这个判断需要上下文吗？

有些工单，AI 光看消息文本就能判断得很准。但有些情况，真正的意图藏在文本之外：

• 客户历史上退过几次货了？
• 这个订单是否处于促销期，退货会触发特殊规则？
• 客服备注里有没有这个客户的特殊情况？

如果正确判断需要的上下文，模型当前不具备，那置信度数字本身就是虚高的——模型不知道自己不知道什么。这种情况，再高的置信度也不该触发自动执行。

用这个框架重新看那个工单

回到开头那条退货消息，套进三个变量：

• 出错代价：中等（触发了不该触发的退货申请，可以撤销，但产生摩擦）
• 可逆性：高（申请发出后客户可以主动取消）
• 上下文依赖：低（"颜色和图片差太多"意图明确，不需要额外信息）

这个组合，倾向于可以自动执行，但要给客户一个明确的撤销入口。客服不需要介入每一条，但系统要在操作后保留一个清晰的"撤销窗口"和操作记录。

换一条消息试试：

"我买的东西有点问题，你们怎么说？"

• 出错代价：不确定（不知道"问题"是什么，处理方式差异很大）
• 可逆性：取决于后续动作
• 上下文依赖：极高（"有点问题"几乎没有信息量）

这个组合，模型的置信度无论多高，都不该自动执行任何流程。正确的界面行为是：标注"意图不明确，建议人工介入"，并把可能的意图选项列出来，让客服快速选择而不是从头处理。

界面设计的几个具体含义

这个框架落到界面上，会带来几个具体的设计要求，是我觉得目前大多数产品做得不够的地方：

置信度要可见，但不能只是一个数字。

"置信度 94%"对普通客服来说没有意义。更有用的呈现是：把这个数字翻译成行动建议——"建议直接处理"、"建议确认后处理"、"建议人工介入"。数字留给系统日志，界面上给人看的是判断，不是概率。

自动执行之后，操作记录必须显眼。

如果 AI 自动触发了某个流程，这个动作不能藏在日志里。它应该在工作台上有明显的呈现："系统已自动发起退货申请 · 10分钟内可撤销"。人工覆盖的成本越低，越敢放权给 AI 自动执行。

人工覆盖不该是"报错"，是正常流程的一部分。

很多系统设计里，人工覆盖 AI 判断是一个"异常路径"——操作步骤多、界面不顺畅、有时候还要填理由。这个设计隐含了一个假设：AI 是对的，人工推翻是例外。

但实际上，人工覆盖是正常的。模型不可能永远对，边缘案例永远存在。界面应该让"我不同意这个判断"这个操作和"我同意"一样顺畅——一个点击，不需要解释，不需要走审批流。

商家后台的同一个问题

这个框架不只适用于售后工单，商家后台里同样存在大量"AI 已判断，然后呢"的设计问题。

比如 AI 检测到某个 SKU 的库存即将断货，预测三天内售罄——界面该做什么？

自动触发补货申请？发一条通知让运营确认？还是只在数据看板上标注一个预警色，等运营自己发现？

套进同样的框架：

• 出错代价：高（错误补货会导致积压或资金占用）
• 可逆性：低（补货指令发出之后，供应链已经启动）
• 上下文依赖：高（补货决策依赖当前促销计划、账期、仓库容量……这些数据模型不一定都有）

这个组合，答案很清晰：不该自动执行，应该是"高优先级提醒 + 一键确认" 。AI 做信息聚合和预测，人来做最终决策。界面的工作是把"确认"这个动作做得足够顺畅，减少决策摩擦，而不是代替决策。

还没想清楚的地方

置信度阈值该怎么定，谁来定？

我说的"高于某个阈值自动执行"，这个阈值应该是固定的系统参数，还是让商家自己配置？不同规模的商家、不同品类的商品，对出错的容忍度差异很大。把这个权力交给商家配置，是更诚实的设计，但也带来了新的认知负担——商家未必知道 94% 和 87% 的置信度在实际操作里意味着什么。

当 AI 频繁被人工覆盖，系统该怎么反应？

如果某类工单的 AI 判断被客服推翻的比例很高，这是一个明确的信号：要么模型在这个类目表现差，要么界面的行动建议设计有问题，要么这类工单本来就不适合 AI 介入。这个反馈机制，应该是自动的，而不是靠数据团队定期去看日志才能发现。

与这个系列的关系

第一篇建立了一个框架：AI 在哪两类场景真正有价值。这篇往前走了一步：当 AI 真的介入之后，界面的责任不是消失，而是变了——从"帮用户完成操作"，变成"在 AI 和人之间建立一个合理的权力分配机制"。

下一篇打算进入决策层，聚焦导购 Agent——那里的问题方向相反：不是"AI 判断了，人怎么接管"，而是"用户说不清楚自己要什么，AI 怎么开始"。

这篇是观察和思考的笔记，框架还很粗糙。如果你在做类似的产品或界面设计，欢迎交流——特别是那个阈值配置的问题，我还没想到好的解法。

你有没有想过，为什么刷新页面后，有些网站还能记住你的登录状态？为什么购物车里的商品关掉浏览器再打开还在？今天我们就来聊聊浏览器里的“记忆术”——本地存储。从简单的钥匙串localStorage，到能装下整个图书馆的IndexedDB，总有一款适合你。

前言

想象一下，你每次去网吧上网，都要重新登录所有账号、重新设置主题、重新添加购物车——是不是想砸电脑？还好，浏览器有“记忆功能”。它能在你的电脑里存点东西，下次再来时直接拿出来用。

这个“记忆功能”就是Web存储。今天我们就来盘点一下浏览器提供的几种存储方式：localStorage、sessionStorage、cookie，以及能存视频、存大文件的IndexedDB。看完你就能根据场景选对工具，再也不用担心数据“蒸发”了。

一、localStorage：永不过期的便利贴

localStorage是一个挂在window上的对象，它存的数据没有过期时间，除非你手动清除或者用户清理浏览器缓存，否则会一直待在那里。

基本用法

// 存数据（键值对，值必须是字符串）
localStorage.setItem('username', '张三');
localStorage.setItem('theme', 'dark');

// 取数据
const name = localStorage.getItem('username'); // '张三'

// 删除某条
localStorage.removeItem('theme');

// 全部清空
localStorage.clear();

// 获取存储数量
console.log(localStorage.length);

存对象怎么办？

localStorage只能存字符串，所以对象要先转成JSON：

const user = { name: '张三', age: 18 };
localStorage.setItem('user', JSON.stringify(user));

// 读取时解析
const stored = JSON.parse(localStorage.getItem('user'));

容量限制

大多数浏览器限制5MB~10MB，够存一些配置、用户信息、小量缓存。

特点总结

• 同步：操作是同步的，会阻塞主线程（但一般很快）。
• 同源：同一域名下所有页面共享（包括不同标签页）。
• 永久：除非手动清除。
• 仅客户端：不会自动发送到服务器。

二、sessionStorage：标签页关闭就消失的临时工

sessionStorage和localStorage的API一模一样，但生命周期不同：它只存在于当前标签页。关掉标签页，数据就没了。刷新页面还在，但新开标签页（即使是同一个网站）会得到一个新的sessionStorage。

// 用法完全一样
sessionStorage.setItem('tempData', '临时值');

适用场景：表单临时草稿、当前页面的中间状态、不希望跨页面共享的敏感信息。

三、cookie：老前辈，但有点“重”

cookie是最早的浏览器存储机制，但如今除了会话管理（登录态）和少量用户追踪，大部分场景已被localStorage替代。

特点

• 容量小：每个cookie 4KB 左右。
• 自动携带：每次HTTP请求都会把cookie发给服务器（增加带宽消耗）。
• 可设置过期时间。
• 可标记HttpOnly（禁止JS读取，防XSS）、Secure（仅HTTPS）、SameSite（防CSRF）。

// 设置cookie（繁琐）
document.cookie = "username=张三; expires=Thu, 18 Dec 2026 12:00:00 UTC; path=/";

// 读取cookie（需要自己解析）
console.log(document.cookie);

现在主流做法：用localStorage存非敏感数据，用httpOnly cookie存登录凭证。

四、IndexedDB：浏览器里的“小数据库”

如果你要存的东西很大（几百MB），或者需要复杂的查询、索引、事务，那么localStorage就不够用了。这时候请出IndexedDB——一个运行在浏览器里的非关系型数据库。

特点

• 容量大：通常250MB+，甚至更多（取决于浏览器）。
• 异步API：基于Promise或回调，不阻塞主线程。
• 支持索引、游标、事务。
• 可以存储File、Blob、ArrayBuffer等二进制数据。

快速上手

IndexedDB的API比较原始，不过我们可以封装一下。

// 1. 打开/创建数据库
const request = indexedDB.open('MyDatabase', 1);

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  // 创建一个对象仓库（类似表），指定主键
  const store = db.createObjectStore('users', { keyPath: 'id' });
  // 创建索引，用于快速查询
  store.createIndex('name', 'name', { unique: false });
};

request.onsuccess = (event) => {
  const db = event.target.result;
  console.log('数据库打开成功');
  // 后续增删改查都用这个db对象
};

request.onerror = (event) => {
  console.error('数据库打开失败', event.target.error);
};

增删改查

// 添加数据（在onsuccess里拿到db）
const transaction = db.transaction(['users'], 'readwrite');
const store = transaction.objectStore('users');
const addRequest = store.add({ id: 1, name: '张三', age: 18 });

addRequest.onsuccess = () => console.log('添加成功');
addRequest.onerror = (e) => console.error('添加失败', e.target.error);

// 查询
const getRequest = store.get(1);
getRequest.onsuccess = () => console.log(getRequest.result);

// 更新（使用put，如果存在则覆盖）
store.put({ id: 1, name: '李四', age: 20 });

// 删除
store.delete(1);

使用游标遍历

const range = IDBKeyRange.bound(1, 10); // id从1到10
store.openCursor(range).onsuccess = (e) => {
  const cursor = e.target.result;
  if (cursor) {
    console.log(cursor.value);
    cursor.continue(); // 继续下一个
  }
};

现代封装：localForage

原生IndexedDB API太啰嗦，推荐用localForage这个库，它提供了类似localStorage的简洁API，但背后自动选择IndexedDB、WebSQL或localStorage。

// 使用localForage
import localforage from 'localforage';

await localforage.setItem('user', { name: '张三' });
const user = await localforage.getItem('user');

五、四种存储方式对比

六、选型指南：到底用哪个？

• 简单键值对，少量数据：localStorage，比如用户偏好设置、主题、是否首次访问。
• 临时数据，只在一个页面用：sessionStorage，比如多步骤表单的暂存。
• 登录凭证：httpOnly cookie（安全）配合后端。
• 大量结构化数据、离线应用：IndexedDB，比如邮件客户端、笔记应用、缓存API数据。
• 需要与后端自动同步：cookie或Authorization头（用localStorage存token也行，但要注意XSS）。

七、避坑指南

1. localStorage 的同步阻塞

大量数据存取会阻塞UI，建议不要存超过几MB，或改用IndexedDB。

2. 隐私模式

Safari的隐私模式下，localStorage和IndexedDB可能不可用或容量极低，要写try-catch降级。

3. 序列化问题

localStorage存对象会丢失原型链、函数、Symbol、循环引用。用JSON.stringify前确保数据可序列化。

4. 安全提醒

永远不要把敏感信息（如密码、token）明文存在localStorage，因为任何JS都能读到（XSS攻击）。token建议用httpOnly cookie或短时效+refresh机制。

5. IndexedDB 版本升级

当修改数据库结构时，需要增加版本号，并在onupgradeneeded里处理旧数据迁移，否则会报错。

八、总结：存储就像选工具箱

• localStorage：日常杂货，随手放。
• sessionStorage：临时工，关窗走人。
• cookie：老古董，特殊场合用。
• IndexedDB：重武器，存大文件、复杂查询。

掌握了这些，你就可以在浏览器里随心所欲地存数据了。明天我们将继续前端工程化的旅程，聊聊Cookie与Session的区别，以及现代认证方案JWT。

如果你觉得今天的存储全家桶够实用，点个赞让更多人看到。我们明天见！

github.com/chenglou/pr…

认识pretext

它是一个通过计算可以得到文本的高度的库，prepare方法传入文本内容和字体大小可以计算出每个文字的排版，layout传入prepare、容器宽度和行高，返回整个容器高度和行数。这个库对于一些需要提前知道高度的场景非常有用。但是这个库只能在前端使用，因为涉及到了canva。

• prepare()：做一次性分析和测量
• layout()：只基于缓存结果做纯算术布局

官方文档明确说明，不要在同样的文本和配置上反复执行 prepare()。例如窗口宽度变化时，应该只重新执行 layout()。

场景：

• 虚拟滚动列表
• ai流式输出
• canvas 渲染

像不定高的虚拟列表的场景，通常需要高度占位，然后滚动后再缓存，有了这个库可以做到内容虚拟列表内容的提前精确计算。解决了滚动过快导致计算不准确的问题。

快速上手

1. 安装依赖

pnpm i @chenglou/pretext

2. App.tsx

import { prepare, layout } from '@chenglou/pretext'

const text = `
AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀AGI 春天到了. بدأت الرحلة 🚀‎
`

export default function App() {
  const prepared = prepare(text, '16px Inter', {
    whiteSpace: 'pre-wrap' // 'normal' | 'pre-wrap'
  })
  const { height, lineCount } = layout(prepared, 200, 20)
  return (
    <div style={{ display: 'flex' }}>
      <div style={{ lineHeight: '20px', width: '200px' }}>{text}</div>
      <div>
        <div>
          计算高度: {height}px, {lineCount} lines
        </div>
        <div>
          真实lines：
          {text.split('').length}
        </div>
      </div>
    </div>
  )
}

3. 效果

可以看到真实的dom高度和计算出来的dom高度一样

实现不定高虚拟滚动列表

import { useEffect, useMemo, useRef, useState } from 'react'
import { prepare, layout } from '@chenglou/pretext'

const fetchData = async () => {
  const response = await fetch('https://jsonplaceholder.typicode.com/posts')
  return response.json()
}

// 上下额外渲染的缓冲项数量，减少滚动时白屏
const BUFFER_COUNT = 5
// 文本排版和实际渲染统一使用的字号
const FONT_SIZE = 16
// 文本排版和实际渲染统一使用的字体
const FONT_FAMILY = 'Inter'
// 传给 pretext layout 的固定行高（px）
const LINE_HEIGHT = 20
// 每个 item 底部边框高度（对应 border-b 的 1px）
const ITEM_BORDER_Y = 1

// 在前缀和数组中找第一个 > target 的位置（upper bound）
const getFirstGreaterIndex = (arr, target) => {
  let left = 0
  let right = arr.length

  while (left < right) {
    const mid = (left + right) >> 1
    if (arr[mid] <= target) {
      left = mid + 1
    } else {
      right = mid
    }
  }

  return left
}

// 在前缀和数组中找第一个 >= target 的位置（lower bound）
const getFirstGreaterOrEqualIndex = (arr, target) => {
  let left = 0
  let right = arr.length

  while (left < right) {
    const mid = (left + right) >> 1
    if (arr[mid] < target) {
      left = mid + 1
    } else {
      right = mid
    }
  }

  return left
}

export default function Scroll() {
  const containerRef = useRef(null)
  const [screenHeight, setScreenHeight] = useState(0)
  const [textLayoutWidth, setTextLayoutWidth] = useState(200)
  const [scrollTop, setScrollTop] = useState(0)
  const [listData, setListData] = useState([])

  useEffect(() => {
    const container = containerRef.current
    if (!container) return

    const updateMetrics = () => {
      setScreenHeight(container.clientHeight)
      // 文本可用宽度应与真实渲染宽度一致，避免高度预估偏大或偏小
      setTextLayoutWidth(Math.max(1, container.clientWidth))
    }

    updateMetrics()

    const observer = new ResizeObserver(updateMetrics)
    observer.observe(container)

    return () => {
      observer.disconnect()
    }
  }, [])

  useEffect(() => {
    fetchData().then((res) => {
      setListData(
        res.map((item) => ({
          uid: item.id,
          value: item.body
        }))
      )
    })
  }, [])

  // 预计算每条文本在固定宽度下的排版高度，用于不定高虚拟列表
  const measuredList = useMemo(
    () =>
      listData.map((item) => {
        const text = String(item.value ?? '')
        const prepared = prepare(text, `${FONT_SIZE}px ${FONT_FAMILY}`)
        const { height, lineCount } = layout(
          prepared,
          textLayoutWidth,
          LINE_HEIGHT
        )
        const itemHeight = Math.ceil(height) + ITEM_BORDER_Y

        return {
          ...item,
          lineCount,
          textHeight: height,
          itemHeight
        }
      }),
    [listData, textLayoutWidth]
  )

  const totalItemCount = measuredList.length

  // 前缀和：prefixHeights[i] 表示前 i 项累计高度
  const prefixHeights = useMemo(() => {
    const result = new Array(totalItemCount + 1).fill(0)
    for (let i = 0; i < totalItemCount; i += 1) {
      result[i + 1] = result[i] + measuredList[i].itemHeight
    }
    return result
  }, [measuredList, totalItemCount])

  const containerHeight = useMemo(
    () => prefixHeights[prefixHeights.length - 1] ?? 0,
    [prefixHeights]
  )

  // 通过 scrollTop 在前缀和中二分定位当前顶部命中的 item
  const topIndex = useMemo(() => {
    if (totalItemCount === 0) return 0
    const hit = getFirstGreaterIndex(prefixHeights, scrollTop) - 1
    return Math.min(totalItemCount - 1, Math.max(0, hit))
  }, [prefixHeights, scrollTop, totalItemCount])

  const startIndex = useMemo(
    () => Math.max(0, topIndex - BUFFER_COUNT),
    [topIndex]
  )

  // 视口底部对应的结束索引，再加 buffer 做预渲染
  const endIndex = useMemo(() => {
    const viewportBottom = scrollTop + screenHeight
    const visibleEndIndex = getFirstGreaterOrEqualIndex(
      prefixHeights,
      viewportBottom
    )
    return Math.min(totalItemCount, visibleEndIndex + BUFFER_COUNT)
  }, [prefixHeights, scrollTop, screenHeight, totalItemCount])

  const renderedItems = useMemo(
    () => measuredList.slice(startIndex, endIndex),
    [measuredList, startIndex, endIndex]
  )

  // 当前渲染窗口整体向下偏移到 startIndex 的真实起点高度
  const offset = useMemo(
    () => prefixHeights[startIndex] ?? 0,
    [prefixHeights, startIndex]
  )

  const handleScroll = (e) => {
    setScrollTop(e.target.scrollTop)
  }

  return (
    <div
      ref={containerRef}
      className='w-60 h-160 border m-auto mt-10 relative overflow-auto'
      onScroll={handleScroll}
    >
      <div
        className='absolute top-0 left-0 right-0 w-full -z-1'
        style={{ height: `${containerHeight}px` }}
      ></div>

      <div
        className='w-full overflow-hidden'
        style={{
          transform: `translate3D(0, ${offset}px, 0)`,
          fontSize: `${FONT_SIZE}px`,
          fontFamily: FONT_FAMILY,
          lineHeight: `${LINE_HEIGHT}px`
        }}
      >
        {renderedItems.map((item) => (
          <div
            className='w-full border-b bg-amber-200'
            key={item.uid}
          >
            {item.value}
          </div>
        ))}
      </div>
    </div>
  )
}

原理

不用 DOM + CSS layout（如 line-height、white-space 等），用 Canvas API 自己测量文本 → 手动换行 → 计算高度

核心API：ctx.measureText，返回文本宽度

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

let text = ctx.measureText("Hello world");
console.log(text.width); // 56;

对比css的优势：

• 不参与 DOM layout
• 不受 CSS flow 影响

你可以：

• 精确测量每个字符串宽度
• 自己决定在哪里换行
• 自己累加高度

实现一个mini版

• 核心方法：

// Intl.Segmenter：它是浏览器内置的“文本切分器”
// 作用：把字符串切成“人眼看到的一个个字符单位”
// 例如："👨‍👩‍👧‍👦" 会被拆成 ["👨", "", "👩", "", "👧", "", "👦"]
const segmenter = new Intl.Segmenter('zh', {
  granularity: 'grapheme'
})

function tokenize(text) {
  const tokens = []

  // segment就是一个一个字符了，包含了中文、英文、emoji等
  for (const { segment } of segmenter.segment(text)) {
    if (/[\u4e00-\u9fff]/.test(segment)) {
      // 判断是中文字符
      tokens.push(segment)
    } else if (/\s/.test(segment)) {
      // 判断是否包含空白字符（空格、换行、制表符等）
      tokens.push(segment)
    } else {
      // 英文需要合并成词（优化）
      const last = tokens[tokens.length - 1]
      if (last && /[a-zA-Z0-9]/.test(last)) {
        tokens[tokens.length - 1] += segment
      } else {
        tokens.push(segment)
      }
    }
  }

  return tokens
}
function wrapText(text, maxWidth, ctx) {
  // 保存最终的分行结果
  let lines = []
  // 当前正在拼接的一行文本
  let currentLine = ''
  // 将文本进行分词，为了兼容中文
  const tokens = tokenize(text)

  // 逐字符尝试拼接，确保按真实渲染宽度换行
  for (let token of tokens) {
    if (token === '\n') {
      lines.push(currentLine)
      currentLine = ''
      continue
    }

    // 先假设把当前字符放进本行，再测量宽度
    const testLine = (currentLine + token).trimEnd()
    // 获取到当前行加上新字符的宽度
    const testWidth = ctx.measureText(testLine).width

    // 超过最大宽度时，当前字符需要换到下一行
    if (testWidth > maxWidth) {
      if (currentLine.length > 0) {
        // 当前行已有内容：先收集当前行，再让新行从当前字符开始
        lines.push(currentLine.trimEnd())
        currentLine = token.trimStart()
      } else {
        // 当前lines没有内容，但是单个字符宽度都超过 maxWidth
        // 这种情况下只能强制单字符成行，避免死循环
        lines.push(token)
        currentLine = ''
      }
    } else {
      // 没超宽：继续在当前行累积
      currentLine = testLine
    }
  }

  // 循环结束后，把最后一行（如果有内容）补进结果
  if (currentLine.length > 0) {
    lines.push(currentLine)
  }

  return lines
}

// 返回布局的文本信息
function layoutText(text, maxWidth, lineHeight, ctx) {
  const lines = wrapText(text, maxWidth, ctx)
  const totalHeight = lines.length * lineHeight

  const lineMetrics = lines.map((line) => ({
    text: line,
    width: ctx.measureText(line).width,
    height: lineHeight
  }))

  return {
    lines: lineMetrics,
    lineHeight,
    totalHeight
  }
}

• 使用：

const canvas = document.createElement('canvas')
const ctx = canvas.getContext('2d')

ctx.font = '16px Arial'

const result = layoutText(
    '你好啊，世界！我是一个前端开发，我会vue、react等技术。还有后端哦',
    120,
    20,
    ctx
)
console.log(result)

• 测试：

需要注意的是使用layoutText计算出来的lines和页面上的dom不一致的原因是因为浏览器排版布局和canvas布局是有差异的，但是总高度是一致的。

完整版代码

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <title>Document</title>
  </head>
  <style>
    div {
      font-size: 16px;
      font-family: Arial;
      width: 120px;
      line-height: 20px;
    }
  </style>
  <div>你好啊，世界！我是一个前端开发，我会vue、react等技术。还有后端哦</div>
  <!-- Hello world, this is a canvas layout demo. -->
  <body>
    <script>
      // Intl.Segmenter：它是浏览器内置的“文本切分器”
      // 作用：把字符串切成“人眼看到的一个个字符单位”
      // 例如："👨‍👩‍👧‍👦" 会被拆成 ["👨", "", "👩", "", "👧", "", "👦"]
      const segmenter = new Intl.Segmenter('zh', {
        granularity: 'grapheme'
      })

      function tokenize(text) {
        const tokens = []
        for (const { segment } of segmenter.segment(text)) {
          // segment就是一个一个字符了，包含了中文、英文、emoji等
          if (/[\u4e00-\u9fff]/.test(segment)) {
            // 判断是中文字符
            tokens.push(segment)
          } else if (/\s/.test(segment)) {
            // 判断是否包含空白字符（空格、换行、制表符等）
            tokens.push(segment)
          } else {
            // 英文需要合并成词（优化）
            const last = tokens[tokens.length - 1]
            if (last && /[a-zA-Z0-9]/.test(last)) {
              tokens[tokens.length - 1] += segment
            } else {
              tokens.push(segment)
            }
          }
        }

        return tokens
      }
      function wrapText(text, maxWidth, ctx) {
        // 保存最终的分行结果
        let lines = []
        // 当前正在拼接的一行文本
        let currentLine = ''
        // 将文本进行分词，为了兼容中文
        const tokens = tokenize(text)

        // 逐字符尝试拼接，确保按真实渲染宽度换行
        for (let token of tokens) {
          if (token === '\n') {
            lines.push(currentLine)
            currentLine = ''
            continue
          }

          // 先假设把当前字符放进本行，再测量宽度
          const testLine = (currentLine + token).trimEnd()
          // 获取到当前行加上新字符的宽度
          const testWidth = ctx.measureText(testLine).width

          // 超过最大宽度时，当前字符需要换到下一行
          if (testWidth > maxWidth) {
            if (currentLine.length > 0) {
              // 当前行已有内容：先收集当前行，再让新行从当前字符开始
              lines.push(currentLine.trimEnd())
              currentLine = token.trimStart()
            } else {
              // 当前lines没有内容，但是单个字符宽度都超过 maxWidth
              // 这种情况下只能强制单字符成行，避免死循环
              lines.push(token)
              currentLine = ''
            }
          } else {
            // 没超宽：继续在当前行累积
            currentLine = testLine
          }
        }

        // 循环结束后，把最后一行（如果有内容）补进结果
        if (currentLine.length > 0) {
          lines.push(currentLine)
        }

        return lines
      }

      // 返回布局的文本信息
      function layoutText(text, maxWidth, lineHeight, ctx) {
        const lines = wrapText(text, maxWidth, ctx)
        const totalHeight = lines.length * lineHeight

        const lineMetrics = lines.map((line) => ({
          text: line,
          width: ctx.measureText(line).width,
          height: lineHeight
        }))

        return {
          lines: lineMetrics,
          lineHeight,
          totalHeight
        }
      }
    </script>
    <script>
      const canvas = document.createElement('canvas')
      const ctx = canvas.getContext('2d')

      ctx.font = '16px Arial'

      const result = layoutText(
        '你好啊，世界！我是一个前端开发，我会vue、react等技术。还有后端哦',
        120,
        20,
        ctx
      )

      console.log(result)
    </script>
  </body>
</html>

pnpm 与 node_modules：硬链接、软连接（符号链接）、Junction 速记

本文说明在 pnpm 布局下，node_modules 里常见的 硬链接、软连接（符号链接）、以及 Windows 上的 目录联接（Junction） 各是什么、各出现在哪一层，方便对照记忆。

1. 三个关键词（先对齐名字）

日常口语里说的 「软连接」≈「符号链接」≈ symbolic link，和 硬链接 是两套不同机制。

2. 在 pnpm + Windows 下，大致对应关系

以本仓库为例（node_modules 顶层依赖如 axios）：

1. node_modules\axios（整包目录）

   • 常见类型：Junction（本机实测为 Junction，不是 SymbolicLink）。
   • 作用：和 「目录软链」 同类——整块包目录接到本项目内的
     node_modules\.pnpm\axios@<版本>\node_modules\axios\。
   • 记忆：软连接那一类思路（指路），只是 Windows 常用 Junction 实现目录指路。

2. node_modules\.pnpm\... 里的目录

   • 一般是普通目录结构（虚拟仓库布局），不是“整个文件夹是一个硬链接”。

3. .pnpm\...\包\ 下面的具体文件（如 README.md）

   • 常与全局 pnpm-store\v3\files\... 里对应内容互为 硬链接，多项目同版本时共享同一份磁盘数据。
   • 可用 fsutil hardlink list "<文件完整路径>" 查看是否有多条路径指向同一文件。

口诀：

• 目录级「软」：node_modules\包名 → Junction → 本项目 .pnpm\...（整块目录指路）。
• 文件级「硬」：.pnpm 内文件 ↔ pnpm-store 内文件（同内容、多路径名）。

3. 示意图

flowchart LR
  subgraph concepts["概念层"]
    SOFT["软连接 / 符号链接\n(及 Windows 目录 Junction)\n= 路径指路"]
    HARD["硬链接\n= 同一文件多个名字"]
  end

  subgraph project["本项目"]
    NM["node_modules/axios\n→ Junction（类软链）"]
    PNPM[".pnpm/axios@x.y.z/.../axios/\n真实目录树"]
    NM --> PNPM
  end

  subgraph store["全局 pnpm-store"]
    ST["v3/files/.../哈希文件"]
  end

  PNPM -->|"包内文件常与之硬链接"| ST

  SOFT -.->|"对应这种指路关系"| NM
  HARD -.->|"对应文件与 store"| PNPM

从外到内读一条路径：

node_modules/axios/README.md
        │
        │  Junction（目录级「软」思路：axios 文件夹指向 .pnpm 里那一包）
        ▼
.pnpm/axios@1.7.2/node_modules/axios/README.md
        │
        │  硬链接：与 pnpm-store/v3/files/... 常共享同一块数据
        ▼
pnpm-store/v3/files/.../（内容寻址，无友好文件名）

4. 本机如何自查

目录是不是「软」类链接（含 Junction / SymbolicLink）：

Get-Item "...\node_modules\axios" | Format-List LinkType, Target

• Junction 或 SymbolicLink：目录指路。
• LinkType 为空：多为普通目录。

文件是否有多条硬链接：

fsutil hardlink list "...\node_modules\.pnpm\axios@1.7.2\node_modules\axios\README.md"

多行输出表示多个路径名指向同一份文件数据。

5. 易混点

• 软连接 ≠ .lnk 快捷方式：.lnk 是壳层文件；软链/Junction 是文件系统层面的重解析，多数程序会跟随解析。
• 「node_modules 根下全是软链」不严谨：是顶层依赖包名那一级目录常为 Junction；不是根下每个零散文件各一条链。
• Linux/macOS 上 pnpm 可能多用 symbolic link；Windows 上常见 Junction，理解时都可归入「目录指路」这一类，与 硬链接（文件去重） 区分开即可。

文档随本仓库 pnpm 默认行为整理；实际以本机 Get-Item / fsutil 结果为准。

Python 速记手册（含可运行 Demo 01~11）

适合人群：

• 前端/全栈转 Python，需要“先跑起来”的最小路径
• 只想快速掌握：语法、JSON、文件、请求、写接口、脚本自动化、Excel

git地址在这里：https://gitee.com/mslimyjj/old-ling-python/tree/master/python-cheatsheet-demos

0. 快速开始（先跑起来）

建议在 python-cheatsheet-demos/ 目录中运行命令（相对路径/生成文件最直观）。

python 01_basics.py

Windows：没有 python 命令怎么办

如果你的环境里 python 命令不可用，可以使用 Python 官方“嵌入式版本”（无需安装、不污染系统环境）。

在 python-cheatsheet-demos/ 目录执行：

$ver='3.11.8'
$zip="python-$ver-embed-amd64.zip"
$url="https://www.python.org/ftp/python/$ver/$zip"
$dest="..\.python-embed"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Invoke-WebRequest -Uri $url -OutFile "$dest\$zip"
Expand-Archive -Force -Path "$dest\$zip" -DestinationPath $dest
& "$dest\python.exe" 01_basics.py

后续统一用它运行 demo：

& "..\.python-embed\python.exe" 05_requests_demo.py

一键安装依赖

如果你用系统 Python：

pip install -r requirements.txt

如果你用嵌入式 Python：

& "..\.python-embed\python.exe" -m pip install -r requirements.txt

1. Demo 01：基础语法（变量 / 条件 / 循环 / 函数）

文件：01_basics.py

name = "张三"      # str
age = 20           # int
is_ok = True       # bool
arr = [1, 2, 3]    # list  = JS Array
obj = {"a": 1}     # dict  = JS Object

print(name, age, is_ok, arr, obj)

if age > 18:
    print("成年")
elif age == 18:
    print("刚成年")
else:
    print("未成年")

for item in [1, 2, 3]:
    print("item:", item)

for i in range(10):
    print("i:", i)


def add(a, b):
    return a + b


res = add(1, 2)
print("add:", res)

运行：

& "..\.python-embed\python.exe" 01_basics.py

2. Demo 02：list / dict（前端最熟）

文件：02_list_dict.py

arr = [1, 2, 3]
arr.append(4)
last = arr.pop()
print(arr, "popped:", last)
print("len:", len(arr))
print("first:", arr[0])

user = {
    "name": "tom",
    "age": 20,
}

print("name1:", user["name"])
print("name2:", user.get("name"))
print("missing:", user.get("addr"))

user["addr"] = "北京"
print(user)

你可以把 list 当成 JS 的数组，把 dict 当成 JS 的对象。

运行：

& "..\.python-embed\python.exe" 02_list_dict.py

3. Demo 03：JSON（前后端交互必备）

文件：03_json_demo.py

import json

data = json.loads('{"name":"tom","age":20}')
print(data, type(data))

str_data = json.dumps(data, ensure_ascii=False)
print(str_data, type(str_data))

• json.loads：字符串 -> 对象
• json.dumps：对象 -> 字符串

运行：

& "..\.python-embed\python.exe" 03_json_demo.py

4. Demo 04：文件读写（批量处理神器）

文件：04_file_io.py

import json

with open("test.txt", "w", encoding="utf-8") as f:
    f.write("hello\n")

with open("test.txt", "r", encoding="utf-8") as f:
    content = f.read()
print("content:", content)

payload = {"name": "tom", "age": 20}
with open("data.json", "w", encoding="utf-8") as f:
    json.dump(payload, f, ensure_ascii=False, indent=2)

with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)
print("json:", data)

运行：

& "..\.python-embed\python.exe" 04_file_io.py

输出会读写当前目录的：

• test.txt
• data.json

5. Demo 05：requests（抓接口 / mock）

文件：05_requests_demo.py

import requests

res = requests.get("https://httpbin.org/get", params={"q": "test"}, timeout=10)
print("get status:", res.status_code)
print(res.json()["args"])

res = requests.post("https://httpbin.org/post", json={"username": "admin"}, timeout=10)
print("post status:", res.status_code)
print(res.json()["json"])

这个 demo 用 https://httpbin.org 作为测试服务，演示 GET/POST JSON。

运行：

& "..\.python-embed\python.exe" 05_requests_demo.py

6. Demo 06：FastAPI（快速写接口）

文件：06_fastapi_main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/api/user")
def get_user():
    return {"name": "tom", "age": 20}

安装依赖（如果还没装）：

pip install fastapi uvicorn

运行：

uvicorn 06_fastapi_main:app --reload

访问：

• http://localhost:8000/api/user
• http://localhost:8000/docs

7. Demo 07：小脚本（遍历目录 / 批量重命名）

文件：07_scripts_os.py

import os

for file in os.listdir("./"):
    print(file)

imgs_dir = "./imgs"
if os.path.isdir(imgs_dir):
    for i, file in enumerate(os.listdir(imgs_dir)):
        src = os.path.join(imgs_dir, file)
        dst = os.path.join(imgs_dir, f"img{i}.png")
        if os.path.isfile(src):
            os.rename(src, dst)
            print("renamed:", src, "->", dst)

运行：

& "..\.python-embed\python.exe" 07_scripts_os.py

注意：批量重命名会操作 ./imgs 目录下文件名，运行前确认目录存在并且文件可改名。

8. Demo 08：对接 AI（HTTP 调用套路）

文件：08_ai_call.py

import requests


def call_ai(prompt: str):
    res = requests.post(
        "http://localhost:8000/ai",
        json={"prompt": prompt},
        timeout=30,
    )
    res.raise_for_status()
    return res.json()


code = call_ai("生成一个Vue3按钮组件")
print(code)

这个 demo 会调用：POST http://localhost:8000/ai

如果你本地没有启动这个服务，会出现连接被拒绝（这属于正常现象）。

运行：

& "..\.python-embed\python.exe" 08_ai_call.py

9. Demo 09：抓取网页请求并保存到 send.txt

文件：09_capture_requests.py

import argparse
import re
import sys
from urllib.parse import urlparse


def _normalize_url(u: str) -> str:
    try:
        p = urlparse(u)
        if not p.scheme or not p.netloc:
            return u
        return p._replace(fragment="").geturl()
    except Exception:
        return u


def _looks_like_api(u: str) -> bool:
    low = u.lower()
    if any(x in low for x in ("/api", "/graphql", "/v1/", "/v2/", "/rpc")):
        return True
    if any(low.endswith(x) for x in (".json", ".xml")):
        return True
    return False


def _capture_with_playwright(url: str, timeout_ms: int, only_api: bool) -> list[str]:
    try:
        from playwright.sync_api import sync_playwright  # type: ignore
    except Exception as e:
        raise RuntimeError("missing_playwright") from e

    seen: set[str] = set()
    out: list[str] = []

    def on_request(req):
        u = _normalize_url(req.url)
        if only_api and (not _looks_like_api(u)):
            return
        if u not in seen:
            seen.add(u)
            out.append(u)

    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        context = browser.new_context()
        page = context.new_page()
        page.on("request", on_request)
        page.goto(url, wait_until="networkidle", timeout=timeout_ms)
        try:
            page.wait_for_timeout(1500)
        except Exception:
            pass
        context.close()
        browser.close()

    return out


def _extract_from_html(url: str, timeout_sec: int, only_api: bool) -> list[str]:
    import requests

    html = requests.get(url, timeout=timeout_sec).text
    candidates = set(re.findall(r"https?://[^\s\"'>]+", html))
    cleaned = [_normalize_url(u) for u in candidates]
    if only_api:
        cleaned = [u for u in cleaned if _looks_like_api(u)]
    cleaned.sort()
    return cleaned


def main(argv: list[str]) -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("url")
    parser.add_argument("--out", default="send.txt")
    parser.add_argument("--timeout", type=int, default=30)
    parser.add_argument("--only-api", action="store_true")
    parser.add_argument("--mode", choices=["auto", "playwright", "html"], default="auto")
    args = parser.parse_args(argv)

    url = args.url
    out_path = args.out
    timeout_sec = args.timeout
    only_api = bool(args.only_api)
    mode = args.mode

    urls: list[str] = []
    if mode in ("auto", "playwright"):
        try:
            urls = _capture_with_playwright(url, timeout_sec * 1000, only_api)
        except RuntimeError as e:
            if str(e) != "missing_playwright" or mode == "playwright":
                raise
            urls = []

    if (not urls) and mode in ("auto", "html"):
        urls = _extract_from_html(url, timeout_sec, only_api)

    with open(out_path, "w", encoding="utf-8") as f:
        for u in urls:
            f.write(u + "\n")

    print(f"saved {len(urls)} urls -> {out_path}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))

目标：给一个网页 URL，把它“页面里出现的 URL / 或页面运行时发出的请求”抓出来，写到 send.txt。

9.1 推荐模式：Playwright（最接近浏览器真实请求）

安装：

pip install playwright
python -m playwright install chromium

运行（只保留更像接口的 URL）：

python 09_capture_requests.py https://example.com --only-api --out send.txt

9.2 兜底模式：HTML 提取（抓不到 XHR/fetch）

如果你不安装 Playwright，脚本会自动降级为“从 HTML 源码中提取 URL”。

你也可以强制：

python 09_capture_requests.py https://example.com --mode html --out send.txt

参数速记：

• --mode playwright：强制用浏览器抓
• --mode html：只解析 HTML
• --only-api：只保留更像接口的 URL（包含 /api、/graphql、/v1/、/v2/、.json 等）

10. Demo 10：3 秒后“键盘输入” Helloween（不是 print）

文件：10_sleep_print.py

import time

from pynput.keyboard import Controller


time.sleep(3)
Controller().type("Helloween")

这个 demo 用 pynput 控制键盘：

• 等待 3 秒
• 向“当前获得焦点的窗口”键入 Helloween

使用方法：先把光标点到你想输入的位置（例如记事本/浏览器输入框），再运行脚本。

运行：

& "..\.python-embed\python.exe" 10_sleep_print.py

11. Demo 11：生成 user.xlsx（随机 10 个姓名）

文件：11_generate_user_excel.py

import os
import random

from openpyxl import Workbook


def random_cn_name() -> str:
    surnames = list("赵钱孙李周吴郑王冯陈褚卫蒋沈韩杨朱秦尤许何吕施张孔曹严华金魏陶姜戚谢邹喻柏水窦章云苏潘葛范彭郎鲁韦昌马苗凤花方俞任袁柳酆鲍史唐费廉岑薛雷贺倪汤滕殷罗毕郝邬安常乐于时傅皮卞齐康伍余元卜顾孟平黄和穆萧尹姚邵湛汪祁毛禹狄米贝明臧计伏成戴谈宋茅庞熊纪舒屈项祝董梁杜阮蓝闵席季麻强贾路娄危江童颜郭梅盛林刁钟徐邱骆高夏蔡田樊胡凌霍虞万支柯昝管卢莫经房裘缪干解应宗丁宣贲邓郁单杭洪包诸左石崔吉钮龚程嵇邢滑裴陆荣翁荀羊於惠甄曲家封芮羿储靳汲邴糜松井段富巫乌焦巴弓牧隗山谷车侯宓蓬全郗班仰秋仲伊宫宁仇栾暴甘钭厉戎祖武符刘景詹束龙叶幸司韶郜黎蓟薄印宿白怀蒲邰从鄂索咸籍赖卓蔺屠蒙池乔阴郁胥能苍双闻莘党翟谭贡劳逄姬申扶堵冉宰郦雍却璩桑桂濮牛寿通边扈燕冀郏浦尚农温别庄晏柴瞿阎充慕连茹习宦艾鱼容向古易慎戈廖庾终暨居衡步都耿满弘匡国文寇广禄阙东欧殳沃利蔚越夔隆师巩厍聂晁勾敖融冷訾辛阚那简饶空曾毋沙乜养鞠须丰巢关蒯相查后荆红游竺权逯盖益桓公万俟司马上官欧阳夏侯诸葛闻人东方赫连皇甫尉迟公羊澹台公冶宗政濮阳淳于单于太叔申屠公孙仲孙轩辕令狐钟离宇文长孙慕容司徒司空")
    given_chars = list("一乙二十丁厂七卜人入八九几儿了力乃刀又三于干亏士工土才下寸大丈与万上小口山巾千乞川亿个夕久么勺丸凡及广亡门义之尸弓己已子卫也女飞刃习叉马乡丰王井开夫天元无云专扎艺木五支厅不太犬区历尤友匹车巨牙屯比互切瓦止少日中贝内水冈见手午牛毛气升长仁什片仆化仇币仍仅斤爪反介父从今凶分乏公仓月氏勿欠风丹匀乌凤勾文六方火为斗忆计订户认心尺引丑巴孔队办以允予劝双书幻玉刊末未示击打巧正扑扒功扔去甘世古节本术可丙左厉右石布龙平灭轧东卡北占业旧帅归且旦目叶甲申叮电号田由史只央兄叼叫另叨叹四生失禾丘付仗代仙们仪白仔他斥瓜乎丛令用甩印乐句匆册犯外处冬鸟务包饥主市立闪兰半汁汇头汉宁它讨写让礼训必议讯记永司尼民出辽奶奴召加皮边发孕圣对台矛纠母幼丝式刑动扛寺吉扣考托老执巩圾扩扫地扬场耳共芒亚芝朽朴机权过臣再协西压厌在有百存而页匠夸夺灰达列死成夹轨邪划迈毕至此贞师尘尖劣光当早吐吓虫曲团同吊吃因吸吗屿帆岁回岂则刚网肉年朱先丢舌竹迁乔伟传乒乓休伍伏优伐延件任伤价伦份华仰仿伙伪自伊血向似后行舟全会杀合兆企众爷伞创肌朵杂危旬旨负各名多争色壮冲妆冰庄庆亦刘齐交次衣产决充妄闭问闯羊并关米灯州汗污江池汤忙兴宇守宅字安讲军许论农讽设访那迅尽导异孙阵阳收阶阴防如妇好她妈戏羽观欢买红驮纤级约纪驰巡")
    surname = random.choice(surnames)
    given_len = random.choice([1, 2])
    given = "".join(random.choice(given_chars) for _ in range(given_len))
    return surname + given


def main():
    wb = Workbook()
    ws = wb.active
    ws.title = "user"

    ws.append(["id", "name"])
    for i in range(1, 11):
        ws.append([i, random_cn_name()])

    out_path = os.path.join(os.path.dirname(__file__), "user.xlsx")
    wb.save(out_path)
    print("saved ->", out_path)


if __name__ == "__main__":
    main()

这个 demo 用 openpyxl 生成 Excel：

• 输出文件：user.xlsx
• Sheet：user
• 表头：id、name
• 数据：随机 10 个姓名

运行：

& "..\.python-embed\python.exe" 11_generate_user_excel.py

12. 你可以怎么用这套 demo

• 当成“Python 最小工具箱”：复制某个脚本改两行就能完成临时需求
• 当成“速记手册”：忘了 with open(...) / requests.get(...) 直接回来抄
• 当成“前端同学上手模板”：从 05/06/09 开始就能快速进入“接口 + 自动化”节奏

给你一个 m x n 的网格图，其中 (0, 0) 是最左上角的格子，(m - 1, n - 1) 是最右下角的格子。给你一个整数数组 startPos ，startPos = [startrow, startcol] 表示 初始 有一个 机器人 在格子 (startrow, startcol) 处。同时给你一个整数数组 homePos ，homePos = [homerow, homecol] 表示机器人的 家 在格子 (homerow, homecol) 处。

机器人需要回家。每一步它可以往四个方向移动：上，下，左，右，同时机器人不能移出边界。每一步移动都有一定代价。再给你两个下标从 0 开始的额整数数组：长度为 m 的数组 rowCosts  和长度为 n 的数组 colCosts 。

• 如果机器人往 上 或者往 下 移动到第 r 行 的格子，那么代价为 rowCosts[r] 。
• 如果机器人往 左 或者往 右 移动到第 c 列 的格子，那么代价为 colCosts[c] 。

请你返回机器人回家需要的 最小总代价 。

示例 1：

输入：startPos = [1, 0], homePos = [2, 3], rowCosts = [5, 4, 3], colCosts = [8, 2, 6, 7]
输出：18
解释：一个最优路径为：
从 (1, 0) 开始
-> 往下走到 (2, 0) 。代价为 rowCosts[2] = 3 。
-> 往右走到 (2, 1) 。代价为 colCosts[1] = 2 。
-> 往右走到 (2, 2) 。代价为 colCosts[2] = 6 。
-> 往右走到 (2, 3) 。代价为 colCosts[3] = 7 。
总代价为 3 + 2 + 6 + 7 = 18

示例 2：

输入：startPos = [0, 0], homePos = [0, 0], rowCosts = [5], colCosts = [26]
输出：0
解释：机器人已经在家了，所以不需要移动。总代价为 0 。

提示：

• m == rowCosts.length
• n == colCosts.length
• 1 <= m, n <= 105
• 0 <= rowCosts[r], colCosts[c] <= 104
• startPos.length == 2
• homePos.length == 2
• 0 <= startrow, homerow < m
• 0 <= startcol, homecol < n

一看到题目第一感觉是用dp，但是我dp一点都没看过呀，觉得一定做不出来，遂准备放弃。突然灵光一闪，好像只要讨论四个方向的情况回家就行（以startPos为原点）😂
这里是以homePos坐标减去startPos坐标得到：

• 第一象限：row＜0, col ＞0;
• 第二象限：row＜0, col ＜0;
• 第三象限：row＞0, col ＜0;
• 第四象限：row＞0, col ＞0;

/**
 * @param {number[]} startPos
 * @param {number[]} homePos
 * @param {number[]} rowCosts
 * @param {number[]} colCosts
 * @return {number}
 */
var minCost = function(startPos, homePos, rowCosts, colCosts) {
    let res = 0;
    if (startPos[0] === homePos[0] && startPos[1] === homePos[1]) {
        return 0;
    }
    
    let row = homePos[0] - startPos[0]; // 行差
    let col = homePos[1] - startPos[1]; // 列差
    if (row >= 0 && col >= 0) {
        for (let i = 0; i < row; i++) {
            res += rowCosts[startPos[0] + i + 1];
        }
        for (let j = 0; j < col; j++) {
            res += colCosts[startPos[1] + j + 1];
        }
    } else if (row >= 0 && col < 0) {
        for (let i = 0; i < row; i++) {
            res += rowCosts[startPos[0] + i + 1];
        }
        for (let j = 0; j < Math.abs(col); j++) {
            res += colCosts[startPos[1] - j -1];
        }
    } else if (row < 0 && col >= 0) {
        for (let i = 0; i < Math.abs(row); i++) {
            res += rowCosts[startPos[0] - i - 1];
        }
        for (let j = 0; j < col; j++) {
            res += colCosts[startPos[1] + j + 1];
        }
    } else {
        for (let i = 0; i < Math.abs(row); i++) {
            res += rowCosts[startPos[0] - i - 1];
        }
        for (let j = 0; j < Math.abs(col); j++) {
            res += colCosts[startPos[1] - j -1];
        }
    }
    
    return res;
};

思路：

• 由于给出的代价不为负，每多绕一段距离那么代价就更多一点，所以回家的路不需要拐弯抹角（直接朝着回家的方向走！）
• 由于不能走斜线，所以回家的路只有竖着走和横着走
• 那么，回家的代价就是模拟机器人竖着走到与家平行的位置的代价，再加上横着走到家的位置的代价

例子：
机器人在[1,0]这个位置，家在[2,3]这个位置
计算出机器人在家的左上方，所以机器人需要向朝着回家的方向走，即

• 向下竖着走：从[1，0]走到[2，0]代价是3
• 向右横着走：从[2，0]走到[2，1]代价是2，从[2，1]走到[2，2]代价是6，从[2，2]走到[2，3]代价是7
• 所有代价加起来是18

###java

class Solution {
    public int minCost(int[] startPos, int[] homePos, int[] rowCosts, int[] colCosts) {
        // 计算机器人到家的纵向和横向距离
        int disX = startPos[0] - homePos[0];    // 纵向距离
        int disY = startPos[1] - homePos[1];    // 横向距离
        
        int ans = 0;

        // 计算纵向距离的代价
        if(disX < 0){
            for(int i=startPos[0]+1;i<=homePos[0];i++){
                ans += rowCosts[i];
            }
        }
        else{
            for(int i=startPos[0]-1;i>=homePos[0];i--){
                ans += rowCosts[i];
            }
        }

        // 计算横向距离的代价
        if(disY < 0){
            for(int j=startPos[1]+1;j<=homePos[1];j++){
                ans += colCosts[j];
            }
        }
        else{
            for(int j=startPos[1]-1;j>=homePos[1];j--){
                ans += colCosts[j];
            }
        }
        return ans;
    }
}

脑筋急转弯：由于题目保证代价均为非负数，所以除了径直走以外，其它弯弯绕绕的策略都不可能更优，那么直接统计径直走的代价即可。

设起点为 $(x_0,y_0)$，终点为 $(x_1,y_1)$。

分别计算上下移动的代价，左右移动的代价，二者之和就是总代价。

• 上下移动的代价：如果 $x_0 < x_1$，那么从起点移动到终点，$x_0+1,x_0+2,\ldots,x_1$ 这些行都要访问到，移动代价为 $\textit{rowCosts}$ 的子数组 $[x_0+1,x_1]$ 的元素和。如果 $x_0 > x_1$，那么移动代价为 $\textit{rowCosts}$ 的子数组 $[x_1+1,x_0]$ 的元素和。
• 左右移动的代价：如果 $y_0 < y_1$，那么从起点移动到终点，$y_0+1,y_0+2,\ldots,y_1$ 这些列都要访问到，移动代价为 $\textit{colCosts}$ 的子数组 $[y_0+1,y_1]$ 的元素和。如果 $x_0 > x_1$，那么移动代价为 $\textit{colCosts}$ 的子数组 $[y_1+1,y_0]$ 的元素和。

代码实现时，不需要根据 $x_0$ 和 $x_1$ 的大小关系分情况讨论，而是计算 $\textit{rowCosts}$ 的子数组 $[\min(x_0,x_1), \max(x_0,x_1)]$ 的元素和，再减去多算的起点代价 $\textit{rowCosts}[x_0]$。对于 $y_0$ 和 $y_1$ 同理。

class Solution:
    def minCost(self, startPos: List[int], homePos: List[int], rowCosts: List[int], colCosts: List[int]) -> int:
        x0, y0 = startPos
        x1, y1 = homePos

        # 起点的代价不计入，先减去
        ans = -rowCosts[x0] - colCosts[y0]

        # 累加代价（包含起点）
        ans += sum(rowCosts[min(x0, x1): max(x0, x1) + 1])
        ans += sum(colCosts[min(y0, y1): max(y0, y1) + 1])

        return ans

class Solution {
    public int minCost(int[] startPos, int[] homePos, int[] rowCosts, int[] colCosts) {
        int x0 = startPos[0], y0 = startPos[1];
        int x1 = homePos[0], y1 = homePos[1];

        // 起点的代价不计入，先减去
        int ans = -rowCosts[x0] - colCosts[y0];

        // 累加代价（包含起点）
        int l1 = Math.min(x0, x1), r1 = Math.max(x0, x1);
        for (int i = l1; i <= r1; i++) {
            ans += rowCosts[i];
        }

        int l2 = Math.min(y0, y1), r2 = Math.max(y0, y1);
        for (int i = l2; i <= r2; i++) {
            ans += colCosts[i];
        }

        return ans;
    }
}

class Solution {
public:
    int minCost(vector<int>& startPos, vector<int>& homePos, vector<int>& rowCosts, vector<int>& colCosts) {
        int x0 = startPos[0], y0 = startPos[1];
        int x1 = homePos[0], y1 = homePos[1];

        // 起点的代价不计入，先减去
        int ans = -rowCosts[x0] - colCosts[y0];

        // 累加代价（包含起点）
        ans += reduce(rowCosts.begin() + min(x0, x1), rowCosts.begin() + max(x0, x1) + 1, 0);
        ans += reduce(colCosts.begin() + min(y0, y1), colCosts.begin() + max(y0, y1) + 1, 0);

        return ans;
    }
};

#define MIN(a, b) ((b) < (a) ? (b) : (a))
#define MAX(a, b) ((b) > (a) ? (b) : (a))

int minCost(int* startPos, int startPosSize, int* homePos, int homePosSize, int* rowCosts, int rowCostsSize, int* colCosts, int colCostsSize) {
    int x0 = startPos[0], y0 = startPos[1];
    int x1 = homePos[0], y1 = homePos[1];

    // 起点的代价不计入，先减去
    int ans = -rowCosts[x0] - colCosts[y0];

    // 累加代价（包含起点）
    int l1 = MIN(x0, x1), r1 = MAX(x0, x1);
    for (int i = l1; i <= r1; i++) {
        ans += rowCosts[i];
    }

    int l2 = MIN(y0, y1), r2 = MAX(y0, y1);
    for (int i = l2; i <= r2; i++) {
        ans += colCosts[i];
    }

    return ans;
}

func minCost(startPos, homePos, rowCosts, colCosts []int) int {
x0, y0 := startPos[0], startPos[1]
x1, y1 := homePos[0], homePos[1]

// 起点的代价不计入，先减去
ans := -rowCosts[x0] - colCosts[y0]

// 累加代价（包含起点）
for _, cost := range rowCosts[min(x0, x1) : max(x0, x1)+1] {
ans += cost
}
for _, cost := range colCosts[min(y0, y1) : max(y0, y1)+1] {
ans += cost
}

return ans
}

var minCost = function(startPos, homePos, rowCosts, colCosts) {
    const [x0, y0] = startPos;
    const [x1, y1] = homePos;

    // 起点的代价不计入，先减去
    let ans = -rowCosts[x0] - colCosts[y0];

    // 累加代价（包含起点）
    ans += _.sum(rowCosts.slice(Math.min(x0, x1), Math.max(x0, x1) + 1));
    ans += _.sum(colCosts.slice(Math.min(y0, y1), Math.max(y0, y1) + 1));

    return ans;
};

impl Solution {
    pub fn min_cost(start_pos: Vec<i32>, home_pos: Vec<i32>, row_costs: Vec<i32>, col_costs: Vec<i32>) -> i32 {
        let x0 = start_pos[0] as usize;
        let y0 = start_pos[1] as usize;
        let x1 = home_pos[0] as usize;
        let y1 = home_pos[1] as usize;

        // 起点的代价不计入，先减去
        let mut ans = -row_costs[x0] - col_costs[y0];

        // 累加代价（包含起点）
        ans += row_costs[x0.min(x1)..=x0.max(x1)].iter().sum::<i32>();
        ans += col_costs[y0.min(y1)..=y0.max(y1)].iter().sum::<i32>();

        ans
    }
}

复杂度分析

• 时间复杂度：$\mathcal{O}(|\textit{start}{\textit{row}} - \textit{home}{\textit{row}}| + |\textit{start}{\textit{col}} - \textit{home}{\textit{col}}|)$。
• 空间复杂度：$\mathcal{O}(1)$。Python 和 JS 把切片改成普通循环即可做到 $\mathcal{O}(1)$ 空间。

如果有负数代价呢？

本题是图论中的最短路问题。在有负数边权的情况下，可以用 Bellman-Ford 算法解决。需要注意的是，如果有负环，则最小代价为 $-\infty$。

专题训练

见下面贪心与思维题单的「§5.2 脑筋急转弯」。

分类题单

如何科学刷题？

1. 滑动窗口与双指针（定长/不定长/单序列/双序列/三指针/分组循环）
2. 二分算法（二分答案/最小化最大值/最大化最小值/第K小）
3. 单调栈（基础/矩形面积/贡献法/最小字典序）
4. 网格图（DFS/BFS/综合应用）
5. 位运算（基础/性质/拆位/试填/恒等式/思维）
6. 图论算法（DFS/BFS/拓扑排序/基环树/最短路/最小生成树/网络流）
7. 动态规划（入门/背包/划分/状态机/区间/状压/数位/数据结构优化/树形/博弈/概率期望）
8. 常用数据结构（前缀和/差分/栈/队列/堆/字典树/并查集/树状数组/线段树）
9. 数学算法（数论/组合/概率期望/博弈/计算几何/随机算法）
10. 贪心与思维（基本贪心策略/反悔/区间/字典序/数学/思维/脑筋急转弯/构造）
11. 链表、树与回溯（前后指针/快慢指针/DFS/BFS/直径/LCA）
12. 字符串（KMP/Z函数/Manacher/字符串哈希/AC自动机/后缀数组/子序列自动机）

我的题解精选（已分类）

欢迎关注 B站@灵茶山艾府

国家地名信息库

国家地名信息库链接： dmfw.mca.gov.cn

接口服务文档：dmfw.mca.gov.cn/interface.h…

正常程序中使用时，将数据缓存起来存入文件或者数据库，比调用接口更稳定。

//直接在浏览器控制台执行，可以测试接口结果
/* 接口说明
code不填时获取省级，填了时获取对应的区划和下级数据
maxLevel=1只获取一级数据 maxLevel=2获取两级数据 maxLevel=3获取三级数据
*/
//获取全国省市区三级，将近300KB数据接口会比较慢
var response=await fetch("https://dmfw.mca.gov.cn/9095/xzqh/getList?code=&maxLevel=3");
var data=await response.json();
console.log(data);

//只获取获取省级数据，速度比较快
var response=await fetch("https://dmfw.mca.gov.cn/9095/xzqh/getList?code=&maxLevel=1");
var data=await response.json();
console.log(data);

//获取湖北省 省、市、区 三级
var response=await fetch("https://dmfw.mca.gov.cn/9095/xzqh/getList?code=420000000000&maxLevel=3");
var data=await response.json();
console.log(data);

//获取武汉市 市、区县、乡镇街道 三级
var response=await fetch("https://dmfw.mca.gov.cn/9095/xzqh/getList?code=420100000000&maxLevel=3");
var data=await response.json();
console.log(data);

注意：当直接获取省市区三级数据时，以下城市只有两级:

1. 直辖市（如：北京、天津、上海、重庆）
2. 不设区的市（如：东莞、中山、儋州、嘉峪关）
3. 省直辖县级行政单位（如：济源、仙桃、琼海、胡杨河）

其他省市都有三级结构。

数据信息

统计局自2024年下半年起就不再公开统计用区划代码，改用国家地名信息库数据。

民政部公告相关链接：www.mca.gov.cn/n156/n186/i…

摘自民政部的公告：自2026年起，本栏目不再公布行政区划代码相关信息。请前往民政部门户网站首页的国家地名信息库版块查询相关信息。

已整合的开源库：github.com/xiangyuecn/…

开源库：已将四级数据整合到了单个csv文件中，同时提供标注拼音、坐标和四级边界范围。提供工具生成多级联动数据和代码，也支持将数据导入MySQL、MSSQL、PgSQL、Oracle等数据库中

【2026-04-03】国家地名信息库行政区划数据截止日期为2025年12月31日。

✨文章摘要（AI生成）

笔者分享了将 Harness Engineering 知识提炼为可复用 Agent Skill 的经验。在系统阅读了 Anthropic、OpenAI、Martin Fowler、LangChain 等来源的文章后，提炼出 Harness 设计的七个核心层：项目搭建、上下文工程、约束与防护、多 Agent 架构、评估与反馈、长时间任务、诊断。最终产出的 harness-engineering 技能覆盖三大场景——新项目搭建、Agent 行为诊断、持续改进，采用渐进式披露架构。定量评估显示有技能时断言通过率 100%，无技能时 83%。核心洞察：Agent 表现不好，80% 的原因不在模型，在 Harness。

为什么写这个

最近两年，笔者在使用各种AI编码助手（Claude Code、Cursor、Copilot等）的过程中，反复遇到一个问题：Agent时好时坏，虽然整体来说随着模型能力进步是向好的，但是向好的过程是曲折波动的。

有时候它写的代码完美契合项目风格，有时候它像个第一天入职的实习生——不知道项目结构、不遵守约定、还把之前商量好的决策忘得一干二净。

然后开始从 Prompt Engineering 中使用结构化、few shot、few example 等技巧，来让 AI 的输出更加稳定。 后面又使用 Context Engineering 来让 Agent 的上下文更加丰富，来让 Agent 的表现更加稳定。

最近几周，一个更系统的词汇出现了：Harness Engineering。

Agent表现不好，80%的原因不在模型，在Harness。 - Anthropic

什么是Harness？简单说：

• 模型 = CPU（算力本身）
• 上下文窗口 = RAM（工作记忆）
• Harness = 操作系统（调度、约束、反馈、文件系统——一切让CPU有效工作的基础设施）

你不会指望一个CPU在没有操作系统的裸机上高效运行。同理，你也不该指望一个模型在没有Harness的项目里稳定输出。

我学到了什么

笔者系统阅读了以下来源的文章：

• Anthropic — 构建高效Agent、多Agent研究系统、长时间运行Agent的Harness设计
• OpenAI — AGENTS.md设计模式、Context Engineering最佳实践
• Martin Fowler — Harness Engineering的工程哲学（"Relocating Rigor"）
• LangChain — Agent框架 vs 运行时 vs Harness的分类学
• philschmid — 2026年Agent Harness的重要性
• 独立开发者实践 — Hermes Agent的自演化、Vue Lynx的设计笔记驱动开发
• 学术论文 — 自然语言Agent Harness的形式化研究

读完之后，我发现这些文章虽然角度各异，但核心思想收敛到了七个层：

所以我做了个技能

读完这些文章，笔者意识到这些模式完全是可复用的。不管你的项目是React前端、Python后端还是Rust CLI工具——Harness的设计原则是通用的。

于是我把这些知识提炼成了一个 Agent Skill，名叫 harness-engineering。

它做什么

这个技能有三个核心使用场景：

场景一：新项目搭建

当你启动一个新项目，告诉Agent"帮我搭建Harness工程"，它会：

1. 评估你的项目类型、技术栈、团队规模
2. 创建 AGENTS.md（表of目录式的Agent导航文件）
3. 建立 docs/ 目录（架构、约定、数据模型等）
4. 配置约束层（lint规则、类型检查、pre-commit hooks）
5. 设置评估与反馈机制

场景二：Agent表现不佳时的诊断

这是最有意思的场景。当你开始抱怨——

• "它怎么又犯同样的错误？"
• "它根本不遵守我们的约定！"
• "它写的代码质量太差了"

这个技能会被触发，引导Agent去诊断Harness层的缺失，而不是怪模型：

场景三：持续改进

每次发现新的可复用Harness模式，更新到技能中，让它在其他项目中也能受益。

它怎么组织的

技能采用渐进式加载架构：

harness-engineering/
├── SKILL.md              # 入口文件（<60行），路由到具体参考文档
└── references/
    ├── 01-project-setup.md       # 项目搭建
    ├── 02-context-engineering.md  # 上下文工程
    ├── 03-constraints.md          # 约束与防护
    ├── 04-multi-agent.md          # 多Agent架构
    ├── 05-eval-feedback.md        # 评估与反馈
    ├── 06-long-running.md         # 长时间任务
    └── 07-diagnosis.md            # 诊断

SKILL.md本身非常精简——它就像一个路由器，根据当前场景指引Agent去读对应的参考文档。这遵循了Harness Engineering本身的原则：渐进式披露，按需加载。

几个让我印象深刻的模式

有几个模式特别触动笔者，感同身受，这里单独拿出来聊聊。

"给地图，不给手册"

这个观点从推文中看到。传统做法是给Agent写详细的分步指令（手册），但这让Agent变得脆弱——任何偏差都会导致它不知所措。

更好的做法是给Agent一张地图：

# 不好的写法（手册）
Step 1: 打开 src/auth/login.ts
Step 2: 找到 handleLogin 函数
Step 3: 在第42行添加...

# 好的写法（地图）
Auth系统在 src/auth/。登录流程：login.ts → validate.ts → session.ts。
限流中间件在 src/middleware/rateLimit.ts——参考它的模式。
每次修改auth都要在 src/auth/__tests__/ 里加测试。

地图让Agent能自主导航，手册让它成为脆弱的执行机器。

"每犯一次错，加一条规则"

这个模式来自多篇文章的交叉验证。核心思想：

1. Agent犯了一个错
2. 你修复了这个错
3. 然后你加一条规则，永远阻止这类错再次发生

这条规则可以是lint规则、类型约束、测试用例，或者只是文档中的一条约定。随着时间推移，Harness积累了越来越多的规则，Agent的错误率对已知模式趋近于零。

这其实就是Martin Fowler说的 "Relocating Rigor"——把人类通过Code Review、经验、直觉实施的质量把关，迁移到自动化检查中。Agent在被检查的边界内自由运行。

Harness = 数据集

这个观点来自Anthropic。每次Agent交互都是一个训练信号：

• 它尝试了什么
• 什么成功了
• 什么失败了
• 修复方案是什么

这些痕迹（traces）就是你的竞争优势。它们是让你的Harness随时间越来越好的数据——不是微调模型，而是优化操作系统。

技能评估：有没有用？

笔者遵循skill-creator的流程，对这个技能做了定量评估。设计了3组测试场景，每组跑with-skill和without-skill两个版本：

有技能的版本在所有场景下都通过了全部断言。无技能的版本在"新项目搭建"场景下缺失较多——它不知道要创建AGENTS.md、不知道docs/应该怎么组织、不会设置渐进式披露的上下文架构。

当然，17%的差距不算巨大。但关键是：有技能时Agent的输出一致且完整，无技能时看运气。对于一个工程实践类技能来说，一致性比偶尔的惊艳更有价值。

怎么安装

这个技能可通过 GitHub 安装：

npx skills add 10xChengTu/harness-engineering

安装后，当你在Claude Code、OpenCode或其他支持Skills的Agent中工作时：

• 启动新项目 → 技能自动触发，引导搭建Harness
• 遇到Agent质量问题 → 开始抱怨时技能会介入诊断
• 主动询问 → "帮我改进这个项目的Harness"

最后

Harness Engineering目前还是一个非常早期的领域。模型在变强，今天需要的约束明天可能就多余了——所以这个技能本身也遵循一个核心原则：为删除而构建。

如果你也在用AI Agent做开发，不妨试试给你的项目加上Harness。从最简单的开始——一个AGENTS.md文件、几条lint规则、一个progress.md。然后观察Agent的表现变化。

你大概率会和笔者有同样的感受：不是模型不行，是我们没给它一个好的工作环境。

本文涉及的所有参考文章和完整技能源码，均可在GitHub 仓库中找到。

Debian 13, codenamed “Trixie”, was released on August 9, 2025. It ships with Linux kernel 6.12 LTS, GNOME 48, KDE Plasma 6, GCC 14.2, Python 3.13, and over 14,100 new packages. Debian 13 will receive full support until August 2028, with Long Term Support (LTS) extending to June 2030.

This guide walks you through upgrading Debian 12 “Bookworm” to Debian 13 “Trixie” via the command line.

Prerequisites #

You need to be logged in as root or a user with sudo privileges to perform the upgrade. You can only upgrade to Debian 13 from Debian 12. If you are running an older Debian version, upgrade to Debian 12 first.

Back Up Your Data #

Before starting a major version upgrade, make sure you have a complete backup of your data. If you are running Debian on a virtual machine, take a full system snapshot so you can restore quickly if anything goes wrong.

Update Currently Installed Packages #

Before changing the source repositories, bring your existing Debian 12 system fully up to date.

Check whether any packages are marked as held back, which could interfere with the upgrade:

sudo apt-mark showhold

If there are held packages, either unhold them with sudo apt-mark unhold package_name or make sure they will not cause issues during the upgrade.

Refresh the package index and upgrade all installed packages:

sudo apt update
sudo apt upgrade

Perform a major version upgrade of the installed packages:

sudo apt full-upgrade

Remove automatically installed dependencies that are no longer needed:

sudo apt autoremove

Update the Sources List #

The upgrade works by pointing your APT repositories from bookworm to trixie.

Open /etc/apt/sources.list with your text editor and replace every instance of bookworm with trixie. You can also do this with a single sed command:

sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

If you have third-party repository files under /etc/apt/sources.list.d/, disable them before the upgrade. They may not be compatible with Debian 13 and can cause errors.

After editing, your /etc/apt/sources.list should look similar to this:

deb https://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware
# deb-src https://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware

deb https://deb.debian.org/debian/ trixie-updates main contrib non-free non-free-firmware
# deb-src https://deb.debian.org/debian/ trixie-updates main contrib non-free non-free-firmware

deb https://security.debian.org/debian-security/ trixie-security main contrib non-free non-free-firmware
# deb-src https://security.debian.org/debian-security/ trixie-security main contrib non-free non-free-firmware

You can find a full list of Debian mirror addresses on the official mirrors page .

Upgrade to Debian 13 Trixie #

Set the terminal output to English to make it easier to follow any prompts:

export LC_ALL=C

Update the package index with the new Trixie repositories:

sudo apt update

If you see errors related to third-party repositories, fix or disable them before continuing.

Run the initial upgrade. This upgrades packages that do not require installing or removing other packages:

sudo apt upgrade --without-new-pkgs

During the upgrade, you may be asked whether services should be automatically restarted:

Restart services during package upgrades without asking?

You may also see prompts about configuration files. If you have not made custom changes to a file, it is safe to accept the package maintainer’s version. If you have made changes, keep the current version to avoid losing your customizations.

Once the initial upgrade finishes, run the full upgrade. This installs new packages, removes obsolete ones, and resolves any remaining dependency changes between Debian 12 and 13:

sudo apt full-upgrade

The upgrade may take some time depending on the number of packages, your hardware, and your internet speed.

When it completes, clean up packages that are no longer needed:

sudo apt autoremove

Reboot your system to load the new kernel:

sudo systemctl reboot

Verify the Upgrade #

After the system boots, log in and check the Debian version :

lsb_release -a

No LSB modules are available.
Distributor ID: Debian
Description: Debian GNU/Linux 13 (trixie)
Release: 13
Codename: trixie

You can also verify the kernel version:

uname -r

The output should show a 6.12.x kernel.

Troubleshooting #

Third-party repository errors during apt update
Disable any third-party sources under /etc/apt/sources.list.d/ before the upgrade. Re-enable them one by one after the upgrade completes, checking that each repository supports Debian 13.

“Packages have been kept back” during upgrade
This is normal during the initial apt upgrade --without-new-pkgs step. The subsequent apt full-upgrade resolves these held-back packages by installing new dependencies or removing conflicting ones.

Services fail to start after reboot
Check the service logs with journalctl -xe and the service status with systemctl status service_name. Configuration file format changes between major versions are a common cause. Compare your config with the package maintainer’s version in /etc/*.dpkg-dist files.

Conclusion #

Your system is now running Debian 13 Trixie. Re-enable any third-party repositories you disabled, verify that your critical services are running, and consider adding trixie-backports to your sources if you need newer package versions. For a full list of known issues and detailed upgrade notes, see the official Debian 13 release notes .

背景

如果你的目标是学习 Agent 概念、测试架构设计、做技术调研，根本不需要付费 API。Ollama 可以让你在本地电脑上运行开源大模型，并且提供 OpenAI 兼容的 API 接口，主流 Agent 框架都能直接对接。

本文介绍如何用 Ollama 搭建一个完全本地化的 AI Agent 开发环境。无需 API Key，无需联网，无需任何费用。

三种方案怎么选

简单原则：先用 Ollama 验证想法、理解 Agent 运行机制。需要 Claude 级别推理能力时切换到 Agent SDK。上生产时申请 LLM Gateway API。

Ollama 是什么

Ollama 是一个开源的本地大模型运行工具，封装了 llama.cpp，提供简单的 CLI 和内置的 OpenAI 兼容 API 服务（http://localhost:11434）。核心特点：

• 支持 Llama、Qwen、Mistral、DeepSeek、Gemma、Phi 等主流模型系列
• GPU 加速：NVIDIA (CUDA)、Apple Silicon (Metal)、AMD (ROCm)
• 内置 Tool Calling / Function Calling 支持（需要模型本身支持）
• OpenAI 兼容 API — 改个 base_url 就能用，框架代码不用改
• CLI 管理模型：ollama pull、ollama run、ollama list

快速开始

第一步：安装 Ollama

macOS / Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows:

winget install Ollama.Ollama

验证安装：

ollama --version

第二步：拉取模型

Agent 开发需要支持 Tool Calling 的模型，推荐：

# 推荐：Qwen3.5 9B — 最新一代，原生视觉 + Tool Calling + Thinking，256K 上下文
ollama pull qwen3.5:9b

# 轻量替代：Qwen3.5 4B — 8GB 内存机器也能跑
ollama pull qwen3.5:4b

# 更强推理能力（需要 24GB+ 内存）：Qwen3.5 27B
ollama pull qwen3.5:27b

# MoE 选项 — 总参数 35B 但仅激活 3B，22GB 设备可运行
ollama pull qwen3.5:35b

硬件参考：qwen3.5:9b 约 6.6GB（大部分 16GB 机器轻松运行）。qwen3.5:4b 约 3.4GB（8GB 内存笔记本也行）。qwen3.5:27b 和 35b 需要 24GB+ 内存/显存。16GB 的 Apple Silicon Mac 可以流畅运行 9B 模型。

第三步：验证 API

Ollama 启动后自动提供 API 服务，测试一下：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5:9b",
    "messages": [
      {"role": "user", "content": "你好！"}
    ]
  }'

收到 JSON 回复就说明环境就绪。

使用 Ollama 构建 Agent

Ollama 的 OpenAI 兼容 API 意味着你可以无缝接入任何支持 OpenAI 格式的框架。以下是最常用的几种模式。

模式 A — 直接用 OpenAI SDK（最简单）

官方 OpenAI Python SDK 可以直接对接 Ollama，只需改 base_url：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # SDK 要求填写，但 Ollama 不校验
)

response = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "用3句话解释什么是 AI Agent。"},
    ],
)
print(response.choices[0].message.content)

模式 B — Tool Calling / Function Calling

Agent 开发的核心 — 让模型自主决定何时调用外部工具：

import json
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[{"role": "user", "content": "香港今天天气怎么样？"}],
    tools=tools,
)

msg = response.choices[0].message
if msg.tool_calls:
    for call in msg.tool_calls:
        print(f"模型要调用: {call.function.name}")
        print(f"参数: {call.function.arguments}")
else:
    print(msg.content)

模式 C — 完整 Agent 循环

一个最小化的 Agent 循环，展示完整流程：用户输入 → 模型推理 → 工具执行 → 模型综合回答：

import json
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 模拟工具实现
def get_weather(city: str) -> str:
    return json.dumps({"city": city, "temp": "28°C", "condition": "晴"})

def search_docs(query: str) -> str:
    return json.dumps({"results": [f"找到关于 '{query}' 的文档"]})

TOOL_MAP = {"get_weather": get_weather, "search_docs": search_docs}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "按关键词搜索内部文档",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        },
    },
]

def agent_run(user_input: str):
    messages = [
        {"role": "system", "content": "你是一个有帮助的助手，需要时使用工具。"},
        {"role": "user", "content": user_input},
    ]

    # 第一步：模型初次调用
    response = client.chat.completions.create(
        model="qwen3.5:9b", messages=messages, tools=tools
    )
    msg = response.choices[0].message
    messages.append(msg)

    # 第二步：如果模型请求调用工具，执行它
    if msg.tool_calls:
        for call in msg.tool_calls:
            fn = TOOL_MAP.get(call.function.name)
            if fn:
                result = fn(**json.loads(call.function.arguments))
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result,
                })

        # 第三步：模型综合工具结果生成最终回答
        final = client.chat.completions.create(
            model="qwen3.5:9b", messages=messages, tools=tools
        )
        return final.choices[0].message.content

    return msg.content

# 试试
print(agent_run("香港今天天气怎么样？"))
print(agent_run("帮我搜索 Agent 架构相关文档"))

这就是所有 Agent 框架背后的基本模式。理解了这个循环，就可以逐步构建更复杂的 Agent。

可选：LiteLLM 统一网关

大部分本地开发场景 Ollama 就够了。但如果你需要：

• 在多个模型之间路由（例如本地 Ollama + 云端备选）
• 添加日志、成本追踪、限流
• 用同一套代码测试多种模型后端

可以用 LiteLLM 作为 Ollama 前面的代理：

pip install litellm[proxy]

# 启动代理，指向本地 Ollama
litellm --model ollama/qwen3.5:9b --port 8000

然后应用指向 http://localhost:8000，代码还是标准 OpenAI SDK 格式，不需要任何改动。

当你的 Agent 代码不变但想通过配置而非代码来切换本地（Ollama）和云端（LLM Gateway）模型时，LiteLLM 很有用。

优势

1. 零成本：不需要 API Key，不产生 token 费用，不消耗订阅额度。本机硬件跑多少都行。
2. 完全隐私：数据完全在本地，不需要联网。用什么数据做实验都没有隐私顾虑。
3. 理解原理：直接使用开源模型，能真正理解 Tool Calling、上下文管理、Agent 循环是怎么运作的，不被商业 API 的抽象挡住。
4. 框架无关：Ollama 的 OpenAI 兼容 API 支持 LangChain、LlamaIndex、CrewAI、AutoGen、smolagents 等几乎所有主流框架。
5. 快速迭代：没有速率限制，没有网络延迟。启动模型、测试、调整、重复。

限制与注意事项

1. 模型能力差距：开源 8B–32B 模型在复杂推理、长上下文、精确 Tool Calling 上与 Claude Sonnet/Opus 有明显差距。工具参数生成和指令遵循的出错率更高。
2. Tool Calling 可靠性：并非所有模型的 Tool Calling 都一样好。Qwen3.5、Llama 3.3、GLM-4 支持最好。小模型（<9B）容易出现工具调用幻觉或参数遗漏。Agent 任务建议 temperature 设为 0–0.2。
3. 硬件要求：本地跑模型需要 CPU/GPU 和内存资源。8B 模型大部分机器没问题。32B+ 模型需要较强硬件（32GB+ 内存或 24GB+ 显存的独立显卡）。
4. 不适合生产：本方案用于开发、学习和研究。生产服务请使用 LLM Gateway API，有 SLA、计费和监控保障。
5. 无内置 MCP 支持：与 Claude Code 不同，Ollama 不原生集成 MCP Server。需要在 Agent 代码中自行实现 MCP 客户端逻辑，或使用支持 MCP 的框架。

从本地到生产

在本地用 Ollama 验证 Agent 设计后，切换到生产环境非常简单，因为 API 接口格式一致：

1. 切换到 Claude Agent SDK 做内部测试 — 只需更换认证方式，代码结构不变。
2. 切换到 LLM Gateway API 上生产 — 把 base_url 改成网关地址，api_key 填网关密钥。同样的 OpenAI SDK 代码，不同的端点。

# 本地开发（Ollama）
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 生产环境（LLM Gateway）
client = OpenAI(base_url="https://<gateway-url>/v1", api_key="your-gateway-key")

Agent 逻辑、工具定义、提示词完全不变。这就是基于 OpenAI 兼容 API 标准构建的核心好处。

Agent 开发推荐模型

运行 ollama list 查看已安装模型，ollama pull <model> 下载新模型。

参考资源

• Ollama 官网：ollama.com
• Ollama OpenAI 兼容 API：docs.ollama.com/api/openai-…
• Ollama Tool Calling：docs.ollama.com/capabilitie…
• Ollama 模型库：ollama.com/library
• LiteLLM 代理：docs.litellm.ai/docs/simple…
• Open WebUI（Ollama 的可选图形界面）：github.com/open-webui/…

为什么 Claude Code 要有指令（Commands）：本质是上下文管理

AI Coding 系列第 03 篇 · 上下文与 Commands

这篇想回答三个问题：

1. 为什么一开始很好用的 Claude Code，会在长会话里越来越"跑偏"？
2. 为什么有些纠正你明明说过很多次，它还是会回退？
3. 为什么 Claude Code 要用 /clear、/compact、/memory 这种命令，而不是全做成按钮？

如果你已经是高频用户，这篇不会提供很多新奇技巧，但会把这些现象背后的机制串成一套可操作的框架。对刚进入稳定开发阶段的用户，这比记住几个命令更重要。

先给结论

Claude Code 里的很多命令，看起来像快捷操作，实际上是在帮你管理三个东西：

1. Claude 现在看到了什么
2. Claude 接下来应该忘掉什么
3. 哪些规则不应该继续留在“会衰减的对话历史”里

如果只把 /clear、/compact、/memory 当成“方便一点的小功能”，你会低估它们的价值。它们真正解决的，是长会话里最常见、也最让人误判的协作问题：Claude 不是突然变差了，而是上下文开始劣化了。

你大概遇到过这种情况

开始一个新任务，头几轮对话质量很高——Claude 理解你的意图，给出准确的方案，代码风格和项目一致。

但聊着聊着，情况变了：它开始重提已经否掉的方案，重复犯你纠正过的错误，或者在一个局部问题上越绕越深，忘了你们最初要解决什么。

这不是 Claude 变笨了，也不是你的 Prompt 写差了。这是上下文劣化——一个有规律、可以预测、也可以干预的现象。

一个贯穿全文的真实场景

假设你在做一个登录模块，从头到尾大概会经历这样一条线：

1. 前期你和 Claude 一起讨论技术方案，聊过 Session、JWT、Redis、PostgreSQL，最后决定先用 PostgreSQL + JWT，把主流程跑通。
2. 接着你开始写代码，发现 Claude 老是顺手加 console.log，你纠正了它两次。
3. 做到一半你又决定把 ORM 从 Sequelize 换成 Prisma，因为前者在这个项目里太重。
4. 再往后，对话已经很长了，你只是问一个事务边界问题，Claude 却开始同时聊缓存、日志、前端错误提示和部署建议。

如果你不理解上下文管理，这整条链看起来像是：“Claude 前面挺聪明，后面越来越不靠谱。”

但如果从上下文角度看，这其实是四类不同问题叠在一起：

• 前面讨论过但已经否掉的方案，还残留在历史里
• 你纠正过的规则，还停留在会衰减的对话层
• 已经废弃的 Sequelize 路线，还在干扰后续回答
• 对话长度过大以后，Claude 的注意力开始发散

也正因为它们是四类不同问题，所以不能指望一个万能 Prompt 解决。你需要的不是“再说清楚一点”，而是把正确的动作放在正确的层级上：该 /compact 的时候压缩，该 /clear 的时候重开，该进 CLAUDE.md 的规则就不要继续留在聊天记录里。

为什么 Claude Code 用命令，而不是全做成按钮

刚接触 Claude Code 的人常问：为什么不把这些能力做成 GUI？为什么要用 /clear、/compact 这种命令？

因为 Claude Code 管理的不是"功能开关"，而是 Claude 此刻正在处理的内容。

举个对比：你在 VS Code 里点"开启 dark mode"，改的是软件的配置文件，和编辑器当前打开了什么文件没关系。但你在 Claude Code 里输入 /clear，清掉的是 Claude 脑子里正在处理的所有东西——之前讨论过的方案、做过的决策、来来覆去的对话，全部抹掉，让它重新认识你。这不是改配置，是在决定 Claude 此刻"知道什么、记得什么"。

命令形式在这里有几个优势：它可重复，你可以稳定复现同一种操作；它可传达，你可以直接告诉同事"先 /clear 再开始"；它也更容易固化成工作流，比如"任务切换先 /clear，长会话中途 /compact，提交前 /review"。对还在快速迭代的 AI 工具来说，命令也比 GUI 更容易快速交付新能力。

所以 Claude Code 的命令系统，本质上是一套让你主动管理 AI 工作现场的操控面板。

四种上下文劣化模式

模式一：早期探索污染后期决策

任务开始时，你和 Claude 在讨论方案，思路是发散的。"要不要用 Redis？""用 JWT 还是 Session？""这个表要不要拆？"——这些都是探索性的讨论，很多想法最终被否决了。

问题是：这些被否决的想法还留在上下文里，和最终确定的方案并排存在。Claude 看到的是一串讨论记录，它会对"用 Redis"和"不用 Redis"这两种可能性都保持某种权重。对话越长，早期探索的内容就越像已确认的决策。

例如：

你：认证这块先别上 Redis，先用 PostgreSQL 把主流程跑通。
Claude：好，先按 PostgreSQL 方案实现。
...
（十几轮后）
Claude：为了提高性能，建议把 session 放到 Redis。

你明明在第 5 轮确认了用 PostgreSQL，第 25 轮它开始建议你考虑一下 Redis 的方案。

模式二：纠正回退

你发现 Claude 用错了某个写法，纠正了它。它承认了，改对了。五轮之后，它犯了同样的错误。

这是因为"纠正"发生在对话的第 8 轮，而你现在在第 15 轮。纠正的内容在上下文里的位置越来越靠后，在 lost-in-the-middle 的注意力分布下，它的权重持续降低，直到 Claude 实际上已经"忘了"那次纠正，重新回到了训练数据里的默认行为。

例如：

你：不要用 console.log，用 logger.info。
Claude：好的，我改成 logger.info。
...
（五轮后）
Claude：这里我先加一个 console.log 方便排查。

你已经说了三次"不要用 console.log，用 logger.info"，但它还是偶尔会写 console.log。

模式三：废弃方案的幽灵

你尝试了一种实现方式，做到一半发现不对，放弃了，换了另一种方式。旧的代码删掉了，但关于旧方案的讨论还留在上下文里。

这段"废弃的历史"会持续影响 Claude 的输出——它可能在新方案里混入旧方案的逻辑，或者在你遇到问题时建议你回到旧方案，因为旧方案在它的上下文里看起来也是一个"被讨论过的合理选项"。

例如：

你：Sequelize 这条路不走了，切到 Prisma。
Claude：明白，后续都按 Prisma 来。
...
（后来你问一个查询问题）
Claude：你可以在 Sequelize 的 include 里这样写...

你已经换掉了 ORM，但 Claude 还在参考旧 ORM 的写法给你示例。

模式四：注意力发散

随着上下文增长，Claude 需要处理的信息量越来越大。注意力是有限的——分给了 A 就少给了 B。越是长对话，Claude 越难在某一个具体问题上保持高度聚焦。它的回答开始变得面面俱到但不够深入，或者在你问一个具体问题时夹带了很多你没问的背景讨论。

例如：

你：只看这个接口的事务边界，哪里可能有问题？
Claude：这个接口本身有事务问题。另外认证模块、日志方案、缓存策略、
      前端错误提示也建议一起调整...

任务越来越复杂，但 Claude 的回答越来越泛，不够犀利。

理解了劣化，命令就有了意义

这四种模式，对应的干预手段是不同的：

但这些命令本质上是不同类型的东西，可靠性和适用场景差别很大——这是大多数人没意识到的。

5 条最实用的决策规则

如果你只想带走最实用的部分，可以先记这 5 条：

1. 任务已经切换，就先 /clear。不要让上一个任务的残留背景继续污染当前任务。
2. 任务没切，但会话已经很长，就 /compact。而且最好写清楚“只保留哪些已确认决策”。
3. 同一条规则纠正两次以上，就别再聊了，直接写进 CLAUDE.md。
4. 你要复用的是“提示词流程”，就做成自定义 command；你要复用的是“带权限约束的能力”，就做成 skill。
5. 当 Claude 开始“什么都懂一点但什么都答不深”时，优先怀疑上下文过载，而不是先怀疑模型突然变差。

这 5 条的价值，在于它们能把“模糊感觉”迅速翻译成明确动作。真正影响协作质量的，不是你知不知道这些概念，而是你能不能在出现问题的当下做对动作。

Claude Code 命令的三种类型

第一类：CLI 状态操作命令

这些命令直接操作 Claude Code 进程的内部状态，不经过 AI 模型，执行的是确定性的代码逻辑。

/clear    → 直接清空内存里的对话历史数组
/cost     → 读取 token 计数器，格式化输出
/model    → 修改当前会话的模型配置
/memory   → 读取和展示 Memory 目录下的文件内容
/help     → 输出命令列表

关键特性：结果确定，不依赖 Claude 的理解。 /clear 必然清空，/cost 必然显示费用，不会因为你的 Prompt 写得好不好而有差异。这类命令是系统层面的操作，不是 AI 行为。

第二类：自定义 Slash Command（提示词模板）

这类命令存放在 .claude/commands/ 目录下，每个命令是一个 .md 文件。文件名就是命令名，文件内容就是命令触发时注入给 Claude 的提示词。

.claude/
  commands/
    review.md      → /review 命令
    pr-desc.md     → /pr-desc 命令
    standup.md     → /standup 命令

可以用 $ARGUMENTS 接收参数：

<!-- .claude/commands/review.md -->
对以下代码做专项 review，聚焦：$ARGUMENTS

检查顺序：
1. 安全漏洞（SQL 注入、权限校验缺失）
2. 边界条件和错误处理
3. 项目规范符合性（参考 CLAUDE.md）

每个问题标注严重等级：blocking / warning / suggestion

关键特性：本质上是一次对话，经过 AI 模型处理，结果有随机性。 你写的是提示词，不是程序——好的自定义命令写法和好的 Prompt 写法是一回事：具体、有约束、有明确的输出格式。

第三类：Skills（能力包触发）

Skills 比自定义命令更重，有完整的元数据配置：限制工具权限（allowed-tools）、指定触发条件（when_to_use）、选择模型（model）、设置上下文隔离（context: fork）。

---
name: security-audit
description: 安全审查
when_to_use: 审查代码安全漏洞时
allowed-tools:
  - Read
  - Grep
  - Glob
model: claude-opus-4-5
context: fork
---
对 ${target} 执行安全审查...

Skills 触发时，会在隔离的子上下文里运行，工具权限是物理隔离的（不是靠 Claude 自律），结束后把结果返回主会话。

关键特性：比自定义命令更结构化，工具权限有硬约束，可以和主会话隔离运行。 适合封装有副作用、需要权限控制的操作。第 05 篇会专门讲 Skills 的设计。

三类命令的选用原则

需要确定性结果，不想靠 Claude 判断 → 第一类 CLI 命令。清空上下文、查费用、切模型，这些操作不该有歧义。

想复用一套工作流程，不需要特殊权限控制 → 第二类自定义命令。把反复用到的提示词结构固化下来，/standup、/pr-desc、/review 这类日常命令都适合。注意：它还是提示词，不是代码。

封装有风险的操作，或者需要隔离运行 → 第三类 Skills。权限隔离只有 Skills 能做到。

两个值得停下来想的洞见

把命令类型和劣化模式放在一起，有两个反直觉的结论。

洞见一：在对话里纠正 Claude 是徒劳的——这是机制决定的，不是你说得不够清楚

模式二"纠正回退"的根本原因不是 Claude 不配合，而是你在用错误的工具纠正它。

在对话里说"不要用 console.log"，这条纠正被写进了"会随时间衰减的历史"——位置越来越靠后，注意力权重持续降低，最终必然回退。这不是偶然的，是 lost-in-the-middle 的机制决定的。

更重要的是，这件事其实很容易自己验证。你可以做一个小实验：

1. 在纯对话里告诉 Claude："不要用 console.log，用 logger.info。"
2. 继续推进几轮任务，再让它生成新代码。
3. 然后把同一条规则写进 CLAUDE.md，再重复一次类似流程。

大多数时候你会发现，两种方式的持久性差别非常明显。前者更容易回退，后者更稳定。这比单纯讲原理更有说服力，因为你能亲手看到规则所在层级不同，稳定性就不同。

真正有效的纠正只有一种：把规则从对话历史移进系统注入层。

# CLAUDE.md
- 日志统一用 logger.info/warn/error，禁止 console.log
- 所有异步函数必须有 try-catch，不依赖外层中间件捕获
- 禁止使用 any，类型必须明确

写进 CLAUDE.md 的规则，在每次对话开始时被系统自动注入，优先级高于对话历史，不会随对话长度衰减。这是 CLAUDE.md 存在的真实原因——不是"项目文档"，是绕过对话历史衰减的唯一可靠手段。

判断标准很简单：如果你对同一件事纠正了两次以上，就不该继续在对话里纠正，而应该把它写进 CLAUDE.md。

洞见二：/compact 不是无损压缩，它本身就是一次 AI 调用

很多人以为 /compact 是把历史"存档"了，实际上 Claude Code 在压缩时会调用模型生成摘要——这意味着压缩结果的质量，取决于 Claude 怎么理解这段历史。

这里不需要依赖源码猜。单从行为上你就能判断出来：/compact 不是简单的机械压缩，而是在"理解历史之后生成摘要"。

为什么这么说？因为如果它只是确定性的算法压缩，那么你补不补"保留说明"，结果应该差异很小；但实际使用中，空着用和带明确保留说明用，摘要质量往往差很多。这更像是模型在根据你的提示重新组织历史，而不是程序在做无损归档。

你在 /compact 后面附加的保留说明，本质上就是在告诉 Claude：哪些内容应该成为压缩后的锚点。有没有写、写了什么，会直接影响压缩后的摘要长什么样。

这有两个实际含义：

第一，/compact 不在第一类"确定性命令"里——尽管它看起来是内置命令，但压缩结果是 AI 行为，不是代码行为，存在质量差异。

第二，空着用和带保留说明用，结果可以差很多：

❌ /compact
   → Claude 自己判断什么重要，探索性讨论和已确认决策同等对待

✅ /compact 只保留已确认的决策：JWT 方案、Prisma 数据库表结构、
            错误处理用 AppError 类。探索阶段被否决的方案不需要保留。
   → Claude 围绕这些锚点生成摘要，后续对话里这些决策记得最清楚

如果你一直在空着用 /compact，本质上是在让 Claude 替你决定什么值得记住。

两个可以立刻自己验证的小实验

如果你想判断这篇文章讲的是不是“经验之谈”，最好的办法不是相信我，而是自己试一下。

实验一：同一条规则，留在对话里 vs 写进 CLAUDE.md

找一条你平时经常纠正的规则，比如：

不要用 console.log，用 logger.info

先只在对话里说这条规则，继续推进几轮任务，再让 Claude 生成新代码。然后把同一条规则写进 CLAUDE.md，重新开始一个类似任务，再观察它的稳定性。

你大概率会看到一个很明显的差别：
留在对话里的规则更容易回退；写进 CLAUDE.md 的规则更稳定。

这个实验最重要的启发不是“CLAUDE.md 很有用”，而是：规则所在的层级不同，稳定性就不同。

实验二：空着 /compact vs 带保留说明 /compact

找一段讨论过很多方案的长会话。先在类似场景里直接执行：

/compact

再换一次，在压缩时明确写：

/compact 只保留已确认的决策：JWT 方案、Prisma 表结构、错误处理规范。
探索阶段被否掉的方案不保留。

然后比较压缩后的后续表现。你通常会发现，后者更不容易把探索阶段的噪音继续带下去。

这个实验说明的不是“提示词可以调得更好”，而是：/compact 本身就在重新组织历史，所以你不该把它当成无脑归档。

完整视图：五类控制机制

把命令扩展到所有控制机制，共五类：

不经过 AI 的机制（CLI 命令、Hooks、快捷键）是确定性的，适合做强约束；经过 AI 的机制（自定义命令、Skills）有随机性，需要好的提示词设计，但表达能力更强。

这篇文章的边界

这里讲的现象，并不是 Claude Code 独有的怪癖，而是长上下文 AI 协作的一类共性问题。不同模型、不同客户端、不同版本，细节会有差别，但下面这几个事实不会变：

• 对话历史不是长期稳定记忆
• 早期探索内容会污染后续判断
• 留在对话层的规则会衰减
• 当上下文过长时，注意力一定会分散

所以这篇文章真正想讲的，不是“背命令表”，而是一个更底层的判断：

Claude Code 的核心问题，不是你会不会再写一个更长的 Prompt，而是你有没有把信息放在正确的层级上。

项目背景、长期规则、任务上下文、阶段性探索，这四种东西不应该混在一起管理。Claude Code 之所以有这些 Commands，本质上就是为了让你把它们拆开。

本篇实践任务

任务一： 找你最近一次“感觉 Claude 越来越糊涂”的会话，对照四种劣化模式，判断到底是哪一种在起作用，不要再笼统地归因于“模型变差”。

任务二： 检查你现在的 CLAUDE.md，有没有把“曾经在对话里纠正过不止一次”的规则写进去？把它们补进去，下次对话观察差异。

任务三： 做一次对照实验：一段长任务会话里分别试试“空着 /compact”和“带保留说明 /compact”，比较后续回答质量。

任务四： 在 .claude/commands/ 里创建一个你最常用操作的自定义 command，比如 /pr-desc 或 /standup，感受一下它和直接输提示词的区别。

下篇预告

第 04 篇：CLAUDE.md 完整指南——让 Claude 真正理解你的项目

你已经知道 CLAUDE.md 是"系统注入的长期记忆"，优先级高于对话历史，是纠正回退的唯一可靠手段。但写什么进去、怎么写才能真正影响 Claude 的行为而不只是让它"读到"，是另一个问题。下一篇专门讲这个。

AI Coding 系列持续更新。上下文劣化有规律，干预就有方法。

当 Three.js 遇上百万级点云，Web 内存与计算双双告急。我们用 C++ 扛起计算，用两种架构打通数据共享——同进程 N-API 与跨进程 gRPC+mmap，究竟谁更胜一筹？

引言

点云是三维世界中最原始、最直观的数据形式。一个中等规模的激光雷达扫描，动辄数百万乃至上亿个点。在 Electron 中直接使用 Three.js 加载 PLY/PCD 文件，往往瞬间耗尽内存，帧率跌至个位数。

根本原因在于：JavaScript 的单线程与 GC 压力，以及大块几何数据在 JS 堆中的双重拷贝。为了破局，业界普遍将计算密集、内存敏感的任务下沉到 C++，然后通过高效的数据共享机制将处理好的顶点数据传递给 Three.js。

本文将深入剖析两种架构方案：

1. 同进程 N-API：C++ 代码以 Node 原生模块的形式直接运行在 Electron 主进程或渲染进程中。
2. 跨进程 gRPC + mmap：C++ 作为独立后台服务，通过 gRPC 通信，通过 mmap 共享内存零拷贝交换数据。

我们不仅会对比优劣，更会给出核心代码实现，让你能真正落地到自己的项目中。

一、痛点与需求

以一个大点云项目为例：

• 点云文件：.las 格式，包含 2000 万个点，每个点有 XYZ、RGB、强度等属性。
• 需求：实时旋转/缩放，无卡顿；支持动态筛选（按强度、分类值）。
• 瓶颈：
  • JS 解析 2000 万个点 → 内存爆炸（每点至少 24 字节，仅位置就需要 480MB）
  • Three.js BufferGeometry 创建过程会再拷贝一次 → 内存翻倍
  • 主线程解析 + 渲染 → UI 冻结

因此，必须：

1. C++ 负责解析、滤波、LOD 生成。
2. C++ 与 JS 共享同一块内存，避免数据拷贝。
3. Three.js 直接消费共享内存中的顶点数据。

二、方案一：同进程 N-API（Node Addon）

2.1 架构图

┌─────────────────────────────────────────┐
│           Electron Main/Renderer        │
│  ┌───────────────────────────────────┐  │
│  │            React UI               │  │
│  └───────────────┬───────────────────┘  │
│                  │ 调用 N-API 导出函数   │
│  ┌───────────────▼───────────────────┐  │
│  │       C++ Addon (N-API)           │  │
│  │  - 点云解析                        │  │
│  │  - 滤波/采样                       │  │
│  │  - LOD 生成                        │  │
│  └───────────────┬───────────────────┘  │
│                  │ 返回 ArrayBuffer     │
│  ┌───────────────▼───────────────────┐  │
│  │       Three.js Renderer           │  │
│  │  BufferAttribute 直接引用 ArrayBuffer│
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

2.2 核心实现：C++ Addon 返回可转移的 ArrayBuffer

步骤 1：编写 C++ 点云解析函数

使用 N-API 创建 ArrayBuffer，填充顶点数据后返回给 JS。

#include <napi.h>
#include <vector>
#include <fstream>
#include "lasreader.hpp"  // LASlib 等

struct Point {
    float x, y, z;
    uint8_t r, g, b;
};

Napi::Value ParsePointCloud(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();
    std::string filepath = info[0].As<Napi::String>().Utf8Value();

    // 1. C++ 中解析点云，获取点数量
    LASreader* reader = LASreader::open(filepath.c_str());
    uint64_t num_points = reader->npoints;
    
    // 2. 计算内存大小（每个点 3*float + 3*uint8 = 12+3 = 15 字节，对齐到 16 字节）
    size_t buffer_size = num_points * sizeof(Point);
    
    // 3. 创建 N-API ArrayBuffer，内存由 C++ 分配（可使用 napi_create_external_arraybuffer 避免额外拷贝）
    void* data = malloc(buffer_size);
    Point* points = static_cast<Point*>(data);
    
    // 4. 填充数据
    size_t idx = 0;
    while (reader->read_point()) {
        points[idx].x = reader->point.get_x();
        points[idx].y = reader->point.get_y();
        points[idx].z = reader->point.get_z();
        points[idx].r = reader->point.get_r();
        points[idx].g = reader->point.get_g();
        points[idx].b = reader->point.get_b();
        ++idx;
    }
    reader->close();
    delete reader;

    // 5. 创建 ArrayBuffer，并绑定释放回调
    Napi::ArrayBuffer buffer = Napi::ArrayBuffer::New(env, data, buffer_size,
        [](Napi::Env env, void* finalize_data) {
            free(finalize_data);
        });
    
    // 6. 返回给 JS（同时可附带点数量等元数据）
    Napi::Object result = Napi::Object::New(env);
    result.Set("buffer", buffer);
    result.Set("numPoints", Napi::Number::New(env, num_points));
    return result;
}

Napi::Object Init(Napi::Env env, Napi::Object exports) {
    exports.Set("parsePointCloud", Napi::Function::New(env, ParsePointCloud));
    return exports;
}
NODE_API_MODULE(pointcloud_addon, Init)

步骤 2：React + Three.js 中消费 ArrayBuffer

// 在渲染进程中（确保 nodeIntegration 开启或通过 preload 暴露）
const addon = require('pointcloud-addon');

async function loadPointCloud(filePath) {
    const { buffer, numPoints } = addon.parsePointCloud(filePath);
    
    // 关键：将 ArrayBuffer 转为 Float32Array 和 Uint8Array 视图，但不复制数据
    const positions = new Float32Array(buffer, 0, numPoints * 3);
    const colors = new Uint8Array(buffer, numPoints * 12, numPoints * 3);
    
    // 创建 Three.js BufferGeometry
    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3, true));
    
    // 使用 PointsMaterial 渲染
    const material = new THREE.PointsMaterial({ vertexColors: true, size: 0.1 });
    const points = new THREE.Points(geometry, material);
    scene.add(points);
}

2.3 优缺点分析

关于 UI 阻塞的解决方案：

直接在渲染进程中调用 addon.parsePointCloud 会同步执行 C++ 代码，若解析耗时超过 16ms，页面就会掉帧。正确的做法是将解析任务放到主进程的 worker_threads 中执行，解析完成后通过 postMessage 将 ArrayBuffer 传回渲染进程（结构化克隆会转移所有权，依然零拷贝）。

javascript

复制下载

// 主进程中创建一个 worker 线程
const { Worker } = require('worker_threads');

const worker = new Worker(`
  const { parentPort } = require('worker_threads');
  const addon = require('pointcloud-addon');
  
  parentPort.on('message', (filePath) => {
    const { buffer, numPoints } = addon.parsePointCloud(filePath);
    // 直接转移 ArrayBuffer 所有权，无需拷贝
    parentPort.postMessage({ buffer, numPoints }, [buffer]);
  });
`, { eval: true });

worker.on('message', ({ buffer, numPoints }) => {
  // 通过 IPC 发送给渲染进程
  mainWindow.webContents.send('pointcloud-data', buffer, numPoints);
});

渲染进程收到后，直接使用 new Float32Array(buffer) 创建视图即可。这样 C++ 解析完全在后台线程，UI 永不阻塞。

注意：worker_threads 是 Node.js 的线程，不是 Web Worker。Web Worker 无法加载原生模块，因此不适用于此场景。

C++ addon 调用放在 worker_threads 中执行 能避免 程序崩溃吗？

不能！

为什么 worker_threads 也无法隔离崩溃？

即便将 C++ addon 调用放在 worker_threads 中执行，由于 worker 线程与主进程共享同一内存空间，原生代码的崩溃依然会连带杀死整个进程。Worker 线程的隔离是 JS 层面的，而非操作系统级的进程隔离。

三、方案二：独立 C++ 服务 + gRPC + mmap 共享内存

3.1 架构图

┌─────────────────────────┐         gRPC（控制面）        ┌─────────────────────────┐
│     Electron 主进程      │◄────────────────────────────►│    独立 C++ 服务         │
│  ┌─────────────────────┐ │                              │  - 点云解析              │
│  │  gRPC Client        │ │                              │  - 滤波/重采样           │
│  │  (Node.js)          │ │                              │  - LOD 生成              │
│  └──────────┬──────────┘ │                              │  - 写入 mmap             │
│             │ IPC         │                              └────────────┬────────────┘
│  ┌──────────▼──────────┐ │                                           │
│  │  Renderer (React)   │ │                              ┌────────────▼────────────┐
│  │  - Three.js         │ │   mmap 共享内存（数据面）     │   /dev/shm/pointcloud   │
│  │  - 读取 mmap 数据    │◄─────────────────────────────►│   (顶点 + 索引 + 元数据)  │
│  └─────────────────────┘ │                              └─────────────────────────┘
└─────────────────────────┘

3.2 核心实现：三步骤打通数据流

3.2.1 C++ 服务：解析点云并写入 mmap

使用 boost::interprocess 或 POSIX shm_open + mmap。为了跨平台，推荐使用 boost。

#include <boost/interprocess/shared_memory_object.hpp>
#include <boost/interprocess/mapped_region.hpp>
#include <atomic>

struct SharedPointCloudHeader {
    std::atomic<uint64_t> version{0};
    std::atomic<bool> ready{false};
    uint64_t num_points;
    uint64_t data_offset;  // 顶点数据起始偏移
};

class PointCloudServer {
public:
    void LoadAndShare(const std::string& las_path) {
        // 1. 解析点云到内存 vector
        std::vector<Point> points = ParseLAS(las_path);
        
        // 2. 计算总大小
        size_t header_size = sizeof(SharedPointCloudHeader);
        size_t data_size = points.size() * sizeof(Point);
        size_t total_size = header_size + data_size;
        
        // 3. 创建共享内存对象
        boost::interprocess::shared_memory_object shm(
            boost::interprocess::open_or_create,
            "pointcloud_shm",
            boost::interprocess::read_write
        );
        shm.truncate(total_size);
        
        // 4. 映射到本进程地址空间
        boost::interprocess::mapped_region region(shm, boost::interprocess::read_write);
        
        // 5. 写入 header
        SharedPointCloudHeader* header = static_cast<SharedPointCloudHeader*>(region.get_address());
        header->num_points = points.size();
        header->data_offset = header_size;
        header->version.fetch_add(1, std::memory_order_release);
        
        // 6. 写入顶点数据
        void* data_ptr = static_cast<char*>(region.get_address()) + header_size;
        memcpy(data_ptr, points.data(), data_size);
        
        // 7. 标记 ready
        header->ready.store(true, std::memory_order_release);
    }
    
    // gRPC 服务接口：返回共享内存名称和大小
    grpc::Status LoadModel(grpc::ServerContext*, const LoadRequest* req, LoadResponse* resp) {
        LoadAndShare(req->file_path());
        resp->set_shm_name("pointcloud_shm");
        resp->set_shm_size(total_size);
        resp->set_data_offset(header_size);
        return grpc::Status::OK;
    }
};

3.2.2 Electron 主进程：gRPC 调用获取元数据

// main.js 中
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const { ipcMain } = require('electron');

const packageDefinition = protoLoader.loadSync('pointcloud.proto');
const proto = grpc.loadPackageDefinition(packageDefinition);
const client = new proto.PointCloudService('localhost:50051', grpc.credentials.createInsecure());

ipcMain.handle('load-pointcloud', async (event, filePath) => {
    return new Promise((resolve, reject) => {
        client.LoadModel({ file_path: filePath }, (err, response) => {
            if (err) reject(err);
            else resolve({
                shmName: response.shm_name,
                shmSize: response.shm_size,
                dataOffset: response.data_offset
            });
        });
    });
});

3.2.3 渲染进程：通过 mmap-io 读取共享内存并传给 Three.js

// 渲染进程中（通过 preload 暴露的 API）
const mmap = require('@cathodique/mmap-io');
const fs = require('fs');

async function loadAndRender(filePath) {
    // 1. 通过 IPC 触发 C++ 服务加载
    const { shmName, shmSize, dataOffset } = await window.electronAPI.loadPointcloud(filePath);
    
    // 2. 打开共享内存（Linux /dev/shm，Windows 不同）
    const fd = fs.openSync(`/dev/shm/${shmName}`, 'r');
    const buffer = mmap.map(fd, mmap.PROT_READ, mmap.MAP_SHARED, shmSize, 0);
    
    // 3. 解析 header（前 24 字节）
    const version = buffer.readBigUInt64LE(0);
    const ready = buffer.readUInt8(8) === 1;
    const numPoints = Number(buffer.readBigUInt64LE(16));
    
    if (!ready) throw new Error('Data not ready');
    
    // 4. 从 dataOffset 位置读取顶点数据
    const pointSize = 32;  // 假设 Point 结构体大小
    const positions = new Float32Array(numPoints * 3);
    const colors = new Uint8Array(numPoints * 3);
    
    for (let i = 0; i < numPoints; i++) {
        const base = dataOffset + i * pointSize;
        positions[i*3] = buffer.readFloatLE(base);
        positions[i*3+1] = buffer.readFloatLE(base + 4);
        positions[i*3+2] = buffer.readFloatLE(base + 8);
        colors[i*3] = buffer.readUInt8(base + 12);
        colors[i*3+1] = buffer.readUInt8(base + 13);
        colors[i*3+2] = buffer.readUInt8(base + 14);
    }
    
    // 5. 创建 Three.js 几何体（注意：这里从 buffer 拷贝到了新 ArrayBuffer，可优化？见下文）
    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3, true));
    
    const points = new THREE.Points(geometry, new THREE.PointsMaterial({ vertexColors: true }));
    scene.add(points);
}

性能陷阱：上面代码中，positions 和 colors 是从 mmap buffer 中逐点读取并创建的新 Float32Array，这仍然存在一次拷贝。要实现真正的零拷贝，需要让 Three.js 直接使用 mmap 映射的原始 buffer。但 Three.js 的 BufferAttribute 只接受 ArrayBuffer 或 Buffer 视图，并且要求该内存生命周期与几何体一致。我们可以利用 SharedArrayBuffer 或者直接传递 mmap 得到的 Buffer 对象，只要保证在几何体销毁前不被 unmap。

// 零拷贝版本：直接使用 mmap 返回的 Buffer 创建 Float32Array 视图
const totalFloats = numPoints * 3;
const positionsView = new Float32Array(buffer, dataOffset, totalFloats);
const colorsView = new Uint8Array(buffer, dataOffset + totalFloats * 4, numPoints * 3);
geometry.setAttribute('position', new THREE.BufferAttribute(positionsView, 3));
geometry.setAttribute('color', new THREE.BufferAttribute(colorsView, 3, true));
// 注意：需要确保 buffer 在几何体使用期间一直保持映射，不能提前 unmap

3.3 优缺点分析

适用场景：点云规模极大（5000 万点以上），需要后台预处理、多任务排队，且对 UI 流畅度要求严苛。

四、核心问题：Buffer 如何从 C++ 共享到 Three.js？

无论哪种方案，最终目标都是让 Three.js 的 BufferAttribute 能直接访问 C++ 中分配的内存，避免复制。两种方案的技术本质：

• N-API 方案：C++ 通过 napi_create_external_arraybuffer 分配内存，JS 拿到 ArrayBuffer 后，Three.js 可直接创建 BufferAttribute。内存所有权归 JS（GC 时调用 free）。
• mmap 方案：C++ 与 JS 通过操作系统共享内存机制映射同一块物理内存，JS 侧通过 Buffer 或 SharedArrayBuffer 访问。内存所有权归 OS，双方均可读写。

技术细节对比

结论：对于绝大多数桌面端点云应用，N-API 方案已经足够，且更简单。只有当点云超过 4GB 或需要多进程同时访问时才考虑 mmap。

五、实战决策：我应该选哪种？

5.1 决策树

是否单点云超过 2GB？
├─ 是 → mmap 方案（突破 V8 堆限制）
└─ 否 → 是否需要支持多进程并发访问？
    ├─ 是 → mmap 方案
    └─ 否 → 是否可接受 C++ 模块崩溃导致 Electron 闪退？
        ├─ 是 → N-API 方案（最简单）
        └─ 否 → mmap 方案（进程隔离更安全）

5.2 混合方案：按需选择

实际项目中，可采用双模式：默认使用 N-API（性能最优），当检测到点云过大时，降级为独立服务模式。

async function loadPointCloud(filePath) {
    const fileSize = getFileSize(filePath);
    if (fileSize < 1e9) { // < 1GB
        return loadWithNapi(filePath);
    } else {
        return loadWithGrpcMmap(filePath);
    }
}

好的，我将把“如何实现内存释放”和“clear 如何触发调用”这两个回答整合成一篇完整的技术说明，保持逻辑连贯，避免重复。

六， 跨进程方案（gRPC + mmap）中的内存释放与触发机制

在 gRPC + mmap 架构中，共享内存的生命周期由 C++ 服务端和 Electron 客户端共同管理。内存释放不是单个操作，而是一套需要双方配合的流程。下面分两部分阐述：释放操作本身 和 释放的触发时机。

6.1、内存释放的三大步骤（“怎么释放”）

C++ 服务端需要依次执行以下三个系统调用，才能彻底销毁一块共享内存：

重要：shm_unlink 只是删除了共享内存的“名字”。即使调用了它，如果还有其它进程（如 Electron）仍然映射着这块内存，其内容依然有效。只有所有进程都执行了 munmap 并关闭了引用，操作系统才会回收物理内存。这保证了 Electron 使用期间数据的稳定性。

下面是一个典型的 clear() 方法实现：

#include <sys/mman.h>   // munmap, shm_unlink
#include <unistd.h>     // close

class SharedMemoryCache {
public:
    void clear(const std::string& shm_name) {
        // 1. 解除映射
        if (mapped_ptr) {
            munmap(mapped_ptr, shm_size);
            mapped_ptr = nullptr;
        }
        // 2. 关闭文件描述符
        if (shm_fd != -1) {
            close(shm_fd);
            shm_fd = -1;
        }
        // 3. 删除共享内存对象
        if (!shm_name.empty()) {
            shm_unlink(shm_name.c_str());
        }
        shm_size = 0;
    }
private:
    void* mapped_ptr = nullptr;
    int shm_fd = -1;
    size_t shm_size = 0;
};

Electron 侧也要解映射：
在 Node.js 中，使用 @cathodique/mmap-io 等库时，需要显式调用 mmap.unmap(buffer) 并关闭文件描述符。建议监听进程退出事件做兜底清理：

process.on('exit', () => {
    if (mmapBuffer) mmap.unmap(mmapBuffer);
    if (fd) fs.closeSync(fd);
});

6.2、clear() 的触发方式（“何时调用”）

C++ 服务端的 clear() 不会自动执行，必须由明确的逻辑触发。有三种主要方式：

Electron 主动请求释放（最推荐）

通过 gRPC 暴露 Release 接口，让 Electron 在不再需要某块共享内存时主动调用。

定义 proto：

service PointCloudService {
  rpc LoadModel(LoadRequest) returns (LoadResponse);
  rpc ReleaseModel(ReleaseRequest) returns (ReleaseResponse);
}
message ReleaseRequest { string shm_name = 1; }

Electron 调用（例如用户关闭点云窗口时）：

await window.electronAPI.releaseModel('pointcloud_shm');

C++ 服务实现：

grpc::Status ReleaseModel(grpc::ServerContext*, const ReleaseRequest* req, ReleaseResponse*) {
    SharedMemoryCache::instance().clear(req->shm_name());
    return grpc::Status::OK;
}

✅ 优点：释放时机精确，资源回收及时，无浪费。

C++ 服务内部自动触发

场景 A：加载新模型时自动替换
在 LoadModel 接口中，如果已有旧共享内存，先 clear() 再创建新的。

if (!current_shm_name.empty()) {
    SharedMemoryCache::instance().clear(current_shm_name);
}
// 然后创建新共享内存...

✅ 优点：无需额外 API，适合单模型应用（一次只打开一个点云）。

场景 B：LRU 缓存淘汰
当服务需要同时缓存多个点云时，可设置容量上限，超过后自动清理最久未使用的。

void evictIfNeeded() {
    if (cache_.size() > MAX_CACHE_COUNT) {
        auto oldest = cache_.begin();
        oldest->second->clear();
        cache_.erase(oldest);
    }
}

✅ 优点：多文档应用（如历史记录）下自动管理内存。

进程退出时自动清理（兜底机制）

在 C++ 服务的析构函数或 atexit 中遍历所有共享内存并调用 clear()。

SharedMemoryCache::~SharedMemoryCache() {
    for (auto& entry : all_caches_) {
        entry.clear();
    }
}

✅ 优点：即使 Electron 忘记调用 Release，正常退出时也能清理。
⚠️ 注意：进程被 kill -9 强制终止时不会执行，但操作系统最终会回收所有内存。

推荐组合策略

在实际项目中，建议采用混合触发，兼顾灵活性与安全性：

典型调用链路：

用户点击“关闭点云” 
  → React 调用 window.electronAPI.closeModel()
  → Electron 主进程通过 gRPC 调用 C++ 服务的 ReleaseModel
  → C++ 服务端执行 SharedMemoryCache::clear(shm_name)
      → munmap → close → shm_unlink
  → 共享内存被彻底销毁

通过清晰的释放操作和完善的触发机制，gRPC + mmap 方案既能提供高性能零拷贝数据共享，又能保证内存资源被安全、及时地回收。

七、总结与展望

在 Electron + Three.js 的大点云渲染场景中，将计算下沉到 C++，并实现零拷贝数据共享是性能突破的关键。本文提供的两种方案各有千秋：

• N-API 同进程方案：适合 1000 万点以下，追求极致简单和低延迟的项目。
• gRPC+mmap 跨进程方案：适合超大规模、要求进程隔离、支持后台队列的专业级应用。

未来，随着 WebGPU 的成熟和 SharedArrayBuffer 的普及，我们甚至可以直接在 C++ 中操作 GPU 缓冲区，进一步降低 CPU 开销。但就目前而言，这套混合架构已经能在普通消费级电脑上流畅渲染 5000 万点云。

如果你正在开发类似的桌面三维工具，希望这篇文章能帮你少走弯路。欢迎在评论区交流你的实践心得！

参考资料：

• Node-API 官方文档
• gRPC Node.js 快速开始
• Three.js 使用外部 ArrayBuffer 作为 BufferAttribute
• Boost.Interprocess 共享内存教程

如果你觉得这篇文章有帮助，欢迎点赞收藏👍 有问题可以在评论区交流！

作者：红波 | 专注智驾、机器人标注工具与可视化开发 | 技术栈：TS/Vue/WebGPU/WebGL/ThreeJS/Go/Rust

你是否在面试中被问过：JavaScript 的基本类型和引用类型存储在哪里？你是否遇到过页面越用越卡、内存持续飙高，却找不到原因？你是否理解闭包、浅拷贝、内存泄漏和栈堆的底层关系？

在前端开发中，栈（Stack）与堆（Heap）是 JavaScript 内存模型的核心基石，也是面试高频考点、性能优化的关键。很多同学只知其名，不知其理，导致在实际开发中踩坑无数。

今天，我们就结合你的核心知识点，从零到一吃透 JS 栈堆内存、垃圾回收、内存泄漏、闭包 等硬核知识点，全文逻辑闭环、内容详实，无论是面试还是实战优化都直接能用。

一、开篇三问：你真的了解 JS 内存吗？

在深入栈堆之前，我们先抛出三个灵魂问题，带着问题学习更有方向：

1. 为什么 let a = 1 和 let a = {} 赋值、拷贝的表现完全不同？
2. 为什么函数执行完，局部变量就消失了，而闭包变量能一直保留？
3. 为什么项目跑久了会卡顿？内存泄漏到底和栈堆有什么关系？

这三个问题的答案，全部藏在 JavaScript 的栈堆内存模型 里。接下来我们逐层拆解，从内存分类、存储规则、管理方式，到垃圾回收、内存泄漏，一次性讲透。

二、第一部分：JavaScript 内存模型 —— 栈与堆

在 JavaScript 中，引擎会把内存划分为 ** 栈内存（Stack）和堆内存（Heap）** 两部分，二者分工明确、各司其职，共同支撑 JS 代码的运行。

1. 栈内存（Stack）：系统自动管理的高速内存

栈内存是 JavaScript 中执行代码、存储简单数据的核心区域，它的管理方式完全由系统自动完成，开发者无需手动干预。

栈内存存储什么？

• 执行上下文（全局上下文、函数执行上下文）
• 基本数据类型（Number、String、Boolean、Null、Undefined、Symbol、BigInt）
• 函数调用记录（调用栈）
• 引用类型的内存地址（指针）

栈内存核心特点

1. 操作速度极快栈是 CPU 最友好的内存结构，读写只需要移动指针，效率远高于堆内存。
2. 内存空间连续栈内存是一块连续的存储空间，遵循 LIFO（后进先出） 原则，和数据结构中的栈完全一致。
3. 系统自动分配与释放函数执行时入栈，执行完毕后，栈内数据自动出栈销毁，不需要垃圾回收机制（GC） 参与。
4. 存储空间小、固定大小栈内存大小有限，不适合存储大型、复杂的数据。

一句话总结栈内存：小而快、自动管、存简单值 / 地址。

2. 堆内存（Heap）：GC 管理的动态内存

堆内存用于存储复杂、占用空间大的数据，它的管理方式和栈内存完全不同。

堆内存存储什么？

• 对象（Object）
• 数组（Array）
• 函数（函数的调用逻辑存在栈中，函数体本身存在堆中）
• 所有引用类型的真实数据

堆内存核心特点

1. 内存空间不连续堆内存是散乱分配的，动态申请空间，会产生内存碎片。
2. 操作速度较慢分配和回收都需要计算，读写效率低于栈。
3. 手动 / GC 自动管理底层语言（C/C++）需要 new 申请、delete 释放；JavaScript 不需要手动操作，由 GC（垃圾回收机制） 自动管理。
4. 存储空间大、动态大小可以存储任意大小的复杂数据。

一句话总结堆内存：大而慢、GC 管、存真实对象数据。

3. 栈与堆的协作关系

在 JavaScript 中，变量本身在栈中，而对象实际存在堆中，栈里存的是指向堆的引用地址。

举个最经典的例子：

// 基本类型：直接存在栈内存
let num = 100;
let str = "前端";

// 引用类型：栈存地址，堆存真实数据
let obj = { name: "掘金" };
let arr = [1, 2, 3];

执行这段代码时：

• 栈内存：存储 num、str 的值，存储 obj、arr 的堆内存引用地址
• 堆内存：存储 {name:"掘金"}、[1,2,3] 的真实数据

这就是 JS 内存最核心的规则：栈里存的是简单类型值 或 引用地址；堆里存的是对象的真实数据。

4. 栈与堆性能差异深度对比

• 栈快（只需要挪指针），堆慢
• 栈连续内存（LIFO，无需 GC），堆非连续（随机分配，需要 GC）
• 闭包，本该在栈释放的数据，被引用到了堆中

从生命周期来看：栈中的数据随着函数执行结束自动释放，而堆中的数据只要引用存在就不会被回收。

三、第二部分：数据结构中的栈与堆

除了内存模型，栈和堆也是数据结构中的常客，面试中经常会把「内存栈堆」和「数据结构栈堆」放在一起问，我们必须区分清楚。

1. 数据结构中的栈

栈是一种线性数据结构，严格遵循 LIFO（Last In First Out，后进先出） 原则。

• 只能从一端添加 / 删除数据（栈顶）
• 经典应用：函数调用栈、括号匹配、浏览器后退功能

它和内存中的栈内存规则完全一致，这也是栈内存得名的原因。

2. 数据结构中的堆

堆是一种非线性的树形数据结构，和内存中的堆完全不是一个概念！

数据结构中的堆分为两种：

• 大顶堆：父节点值 ≥ 子节点值
• 小顶堆：父节点值 ≤ 子节点值

堆常用于：优先队列、堆排序、TOP K 问题。

⚠️ 重要区分：

• 内存堆：存储引用类型，GC 管理
• 数据结构堆：排序、优先队列

面试中如果同时问到，一定要清晰区分二者，不要混淆。

四、第三部分：JS 垃圾回收机制（GC）—— 内存的 “清洁工”

堆内存需要垃圾回收机制来释放空间，GC 就是 JS 引擎的内存清洁工，负责把「不再使用的对象」清理掉，释放内存。

1. 对象可回收的核心标准：是否可达

GC 判断一个对象是否能被回收，只有一个标准：这个对象是否还能被访问到？（是否可达）

只要对象无法通过任何方式被访问，GC 就会标记它，并在合适时机回收内存。

我们用四个经典案例，彻底讲透「对象可达性」：

案例 1：局部对象 —— 自动回收

function fn(){
    let obj={a:1}  //会被回收
}
fn();

函数执行完毕，执行上下文出栈，obj 变量销毁，堆中对象无引用 → 不可达 → 被回收。

案例 2：全局引用 —— 不会回收

let globalObj;
function fn(){
    let obj={a:1}   //对象引用 n=1  不会释放
    globalObj=obj;  //对象引用 n=1+1
}
fn(); //n-1=1

函数执行完，局部变量 obj 销毁，但 globalObj 仍在引用，对象始终可达 → 不会被回收。

案例 3：循环引用

let a={};
let b={};
a.x=b;
b.y=a;
// 循环引用

a=null;
b=null;

老式引用计数算法会因计数不为 0 无法回收，造成泄漏；现代标记清除算法会判断不可达，正常回收。

案例 4：闭包

function outer(){
    let obj={a:1}
    return function inner(){
        console.log(obj)
    }
}
let fn=outer();

内层函数引用外层变量，导致 obj 一直可达，不会被回收。这就是闭包的本质：栈上本该释放的变量，被引用到了堆中，延长了生命周期。

2. 垃圾回收算法

（1）引用计数

• 被引用一次 +1，取消引用 -1
• 计数为 0 则回收
• 致命缺陷：循环引用无法回收
• 现已基本废弃

（2）标记清除（V8 主流）

• 从根对象（window/global）开始遍历
• 给可达对象打标记，未标记对象清除
• 解决循环引用问题
• 缺点：产生内存碎片

通俗理解：打扫卫生，哪些要断舍离呢？贴个标签，没贴的就扔掉回收。

五、第四部分：内存泄漏 —— 前端的 “隐形杀手”

内存泄漏是前端应用中的隐形杀手。本该被回收的内存，因被意外引用而无法释放，导致占用持续增长，最终引发页面卡顿甚至崩溃。

它不会立即导致应用崩溃，而是像慢性病一样，随着用户使用时间的延长，逐渐吞噬系统资源，最终导致卡顿、延迟，甚至浏览器标签页崩溃。

下面我们逐一梳理最常见的 9 种内存泄漏场景，并给出解决方案。

1. 定时器未清理

React / Vue 组件卸载了，但定时器没有取消。定时器内部函数引用了外部变量，变量被长期引用，无法释放。

解决方案：组件卸载时清除定时器。

2. 事件监听未移除

给 window、document、DOM 绑定事件后，组件销毁未解绑，回调函数长期驻留内存。

3. DOM 引用未释放

let el=document.getElementById('app')
document.body.removeChild(el);
// DOM 已删，但引用还在
el=null; // 必须手动切断

4. 全局变量 / 意外挂载到全局

• var 声明自动挂载 window
• 未声明直接赋值自动全局window 是根对象，永远可达 → 永不回收。

5. 闭包导致的内存泄露

不必要的长生命周期闭包，会让内部引用对象一直存活。

6. Map/Set 使用不当

Map/Set 是强引用，即使 key 对象设为 null，Map 依然持有引用，无法回收。

解决方案：使用 WeakMap、WeakSet，它们是弱引用，key 对象被回收时会自动移除对应项，不会造成泄漏。

7. 订阅发布者模式

只订阅不取消订阅，回调函数长期引用外部变量，造成泄漏。

8. Promise 一直不结束

Promise 永久 pending，内部持有大量引用无法释放。

9. 请求未中止，组件已卸载

请求发送后，组件提前卸载，回调仍持有引用。解决方案：使用 AbortController 中止请求。

六、第五部分：栈堆模型对实际开发的深层影响

栈堆不只是面试题，它直接决定了你代码的行为、性能和 Bug 来源。

1. 影响浅拷贝与深拷贝

• 基本类型赋值：拷贝栈值，相互独立
• 引用类型赋值：拷贝地址，共享堆数据

浅拷贝只复制一层地址，深拷贝重新开辟堆内存，完整复制所有结构。理解栈堆，你就彻底理解深浅拷贝的本质区别。

2. 影响闭包原理

闭包的核心就是：栈上的执行上下文销毁了，但变量被堆中的函数引用，因此保留在内存中。

3. 影响内存泄漏

绝大多数泄漏，本质都是：堆对象被意外长期引用，GC 无法回收。

4. 影响页面性能

• 栈内存几乎无性能压力
• 堆内存过多、频繁 GC → 主线程阻塞 → 页面卡顿

七、第六部分：面试满分回答模板（可直接背诵）

如果面试官问：说说 JS 中的栈和堆？

你可以这样回答：

在 JavaScript 中，内存分为栈内存和堆内存。栈主要存储执行上下文、基本类型值、以及引用类型的地址，由系统自动管理，内存连续、后进先出、速度极快，函数执行完自动释放。堆存储对象、数组、函数等复杂数据，内存不连续，需要垃圾回收机制管理，速度相对较慢。

变量存在栈中，对象真实数据存在堆中，栈保存堆的引用地址。垃圾回收主要通过标记清除算法，判断对象是否可达来决定是否回收。

内存泄漏通常是因为对象被意外长期引用，比如未清理定时器、事件监听、DOM 引用、循环引用、不当闭包、强引用 Map 等。实际开发中可以通过及时清理监听、使用 WeakMap、避免冗余闭包来避免泄漏。

这一段覆盖所有要点，逻辑清晰，面试官直接给高分。

八、总结

栈和堆核心区别在于存储内容和管理方式。

• 栈：执行上下文、基本类型、引用地址，系统自动管理，连续内存、LIFO、速度快、无碎片。
• 堆：对象、数组、函数真实数据，GC 管理，非连续、速度较慢、有碎片。

在 JS 中：变量本身在栈中，对象实际数据在堆中，栈存堆地址。 栈随函数结束自动释放；堆只有无引用时才被 GC 回收。

栈堆模型直接影响：深浅拷贝、闭包行为、垃圾回收、内存泄漏、页面性能。

理解栈堆，才算真正理解 JavaScript 的运行底层。

• robots[i] 是第 i 个机器人的位置。
• distance[i] 是第 i 个机器人的子弹可以行进的 最大 距离。
• walls[j] 是第 j 堵墙的位置。

每个机器人有 一颗 子弹，可以向左或向右发射，最远距离为 distance[i] 米。

子弹会摧毁其射程内路径上的每一堵墙。机器人是固定的障碍物：如果子弹在到达墙壁前击中另一个机器人，它会 立即 在该机器人处停止，无法继续前进。

返回机器人可以摧毁墙壁的 最大 数量。

注意：

• 墙壁和机器人可能在同一位置；该位置的墙壁可以被该位置的机器人摧毁。
• 机器人不会被子弹摧毁。

示例 1:

示例 2:

提示:

• 1 <= robots.length == distance.length <= 105
• 1 <= walls.length <= 105
• 1 <= robots[i], walls[j] <= 109
• 1 <= distance[i] <= 105
• robots 中的所有值都是 互不相同 的
• walls 中的所有值都是 互不相同 的