• 大型代码库的 Claude Code 最佳实践：构建层级化知识库
  • 引言
  • 核心原则：渐进式披露
  • 三级层级结构
    • 第一层：项目根目录（全局上下文）
    • 第二层：模块/领域（战略上下文）
    • 第三层：叶子节点/组件（战术上下文）
  • AI 友好内容的编写规范
    • 1. 明确而非习惯用语
    • 2. 使用"要/不要"列表
    • 3. 引用具体文件路径
    • 4. 保持精简
  • 层级化 vs 扁平化：对比
  • 实施步骤
    • 第一阶段：根目录
    • 第二阶段：核心模块
    • 第三阶段：复杂组件
    • 第四阶段：让 Claude 协助
  • 总结

大型代码库的 Claude Code 最佳实践：构建层级化知识库

摘要：在大型代码库中高效使用 Claude Code 的核心在于"渐进式披露"原则。通过构建三级层级化知识库，让 AI 在需要时获取恰到好处的上下文，避免 token 浪费和上下文混淆。

to English

引言

AI 辅助编程工具日益普及，开发者面临新挑战：如何在大型代码库中高效使用 Claude Code。在根目录放一个庞大的 README 并非良策——token 浪费、上下文混淆、维护困难。

本文介绍一种层级化知识库最佳实践，通过三级文档结构，让 Claude Code 在正确时机获取正确信息。

核心原则：渐进式披露

渐进式披露（Progressive Disclosure）：在根目录提供高层规则，随着 AI 深入子目录，逐步提供更具体的"为什么"和"怎么做"。

Claude Code 原生识别 CLAUDE.md 文件。我们将此模式扩展为层级化方法，让文档结构与目录树对齐。

三级层级结构

第一层：项目根目录（全局上下文）

文件位置：/CLAUDE.md

定位：项目"宪法"，定义技术栈、核心命令、不可违背的标准。

示例内容：

## 构建命令
- 生产构建：pnpm build
- 开发模式：pnpm dev

## 测试命令
- 单元测试：pnpm test:unit <文件>
- E2E 测试：pnpm test:e2e

## 代码规范
- 仅使用函数式组件
- 禁止 default exports
- 样式使用 Tailwind CSS

## 架构概述
- Next.js 单体仓库
- 共享逻辑位于 /packages/shared

第二层：模块/领域（战略上下文）

文件位置：/src/features/billing/CONTEXT.md

定位：解释代码无法揭示的业务逻辑和隐性数据流。

示例内容：

## 领域逻辑
本模块处理 Stripe 支付集成。

## 数据流
所有支付必须先触发 webhook-handler，再更新数据库。

## 安全要求
- 禁止在前端暴露 Secret_Key
- 使用 /api/stripe 中的代理进行后端调用

## 依赖关系
- 依赖 UserStore 进行税费计算
- 与 OrderService 双向同步

第三层：叶子节点/组件（战术上下文）

文件位置：/src/components/DataGrid/NOTES.md

定位：解释"陷阱"和技术债务。

示例内容：

## 性能注意事项
- 使用 react-virtualized 进行虚拟滚动
- 禁止移除 rowHeight 属性，否则在 Safari 上会崩溃

## 已知问题
- 排序切换与 API 存在竞态条件
- 解决方案：使用 isLoading ref 进行防抖

## 待重构
- [ ] 将排序逻辑提取为独立 Hook
- [ ] 替换已废弃的 componentWillReceiveProps

AI 友好内容的编写规范

1. 明确而非习惯用语

❌ 错误：Just run the tests
✅ 正确：Use npm run test

AI 对明确指令响应更好，避免开发者"行话"。

2. 使用"要/不要"列表

AI 对否定约束响应极佳：

## 类型规范
- ❌ 不要使用 'any' 类型
- ✅ 类型 truly 不明确时使用 'unknown'
- ✅ 优先使用 TypeScript 严格模式

3. 引用具体文件路径

让 AI 知道"真相"在哪里：

## 数据模型
- 主 Schema 定义在 /src/db/schema.ts
- 类型导出在 /src/types/index.ts

4. 保持精简

单个上下文文件不超过 50 行高密度信息。超过 10KB，AI 可能浪费过多 token。

层级化 vs 扁平化：对比

实施步骤

无需一次性完成。采用渐进式方法：

第一阶段：根目录

1. 创建 /CLAUDE.md
2. 定义技术栈、构建命令、代码规范

第二阶段：核心模块

1. 识别 3-5 个核心业务模块
2. 为每个模块创建 CONTEXT.md
3. 描述数据流、安全要求、依赖关系

第三阶段：复杂组件

1. 识别存在技术债务或"陷阱"的组件
2. 创建 NOTES.md 记录已知问题和解决方案

第四阶段：让 Claude 协助

使用 Claude Code 本身帮助生成文档：

# 让 Claude 分析模块并生成 CONTEXT.md
claude "Analyze the billing module and create a CONTEXT.md 
        that explains the data flow and security requirements"

总结

层级化知识库的核心价值：

1. 节省 token：AI 仅读取相关上下文
2. 提高精确度：特定规则作用于特定范围
3. 易于维护：小文件贴近代码，更新成本低
4. 可扩展：随项目增长自然扩展

实施时从根目录 /CLAUDE.md 入手，逐步向下扩展。记住：文档的价值在于被使用，而非被写完。

参考资料

• Claude Code 官方文档
• Progressive Disclosure in Software Design

• Best Practices for Large Codebases with Claude Code: Building a Level-Structured Knowledge Base
  • Introduction
  • Core Principle: Progressive Disclosure
  • The 3-Tier Hierarchy
    • Tier 1: Project Root (Global Context)
    • Tier 2: Module/Domain (Strategic Context)
    • Tier 3: Leaf/Component (Tactical Context)
  • Best Practices for "AI-Friendly" Content
    • 1. Be Explicit, Not Idiomatic
    • 2. Use "Do/Don't" Lists
    • 3. Reference Specific Files
    • 4. Keep It Small
  • Hierarchical vs. Flat: Comparison
  • Implementation Steps
    • Phase 1: Root Directory
    • Phase 2: Core Modules
    • Phase 3: Complex Components
    • Phase 4: Let Claude Help
  • Summary

Best Practices for Large Codebases with Claude Code: Building a Level-Structured Knowledge Base

Abstract: The key to efficiently using Claude Code in large codebases lies in the principle of "Progressive Disclosure." By building a three-tier hierarchical knowledge base, AI can access just the right amount of context when needed, avoiding token waste and context confusion.

中文版

Introduction

As AI-assisted programming tools become ubiquitous, developers face a new challenge: how to use Claude Code effectively in large codebases. Placing a massive README file at the root is far from optimal—it leads to token waste, context confusion, and maintenance difficulties.

This article presents a hierarchical knowledge base best practice, using a three-tier documentation structure to ensure Claude Code receives the right information at the right time.

Core Principle: Progressive Disclosure

Progressive Disclosure means providing high-level rules at the root, then offering increasingly specific "why" and "how" details as AI drills down into subdirectories.

Claude Code natively recognizes CLAUDE.md files. We can extend this pattern into a hierarchical approach, aligning documentation structure with the directory tree.

The 3-Tier Hierarchy

Tier 1: Project Root (Global Context)

File Location: /CLAUDE.md

Purpose: The "Constitution"—defining the tech stack, core commands, and non-negotiable standards.

Example Content:

## Build Commands
- Production build: `pnpm build`
- Development mode: `pnpm dev`

## Test Commands
- Unit tests: `pnpm test:unit <file>`
- E2E tests: `pnpm test:e2e`

## Code Style
- Functional components only
- No default exports
- Use Tailwind CSS for styling

## Architecture
- Next.js monorepo
- Shared logic in `/packages/shared`

Tier 2: Module/Domain (Strategic Context)

File Location: /src/features/billing/CONTEXT.md

Purpose: Explaining business logic and invisible data flows that code alone won't reveal.

Example Content:

## Domain Logic
This module handles Stripe integration.

## Data Flow
All payments must trigger the `webhook-handler` before updating the DB.

## Security
- Never expose Secret_Key to the frontend
- Use the proxy in `/api/stripe` for backend calls

## Dependencies
- Depends on UserStore for tax calculations
- Bidirectional sync with OrderService

Tier 3: Leaf/Component (Tactical Context)

File Location: /src/components/DataGrid/NOTES.md

Purpose: Explaining "gotchas" and specific technical debt.

Example Content:

## Performance
- Uses react-virtualized for virtual scrolling
- Do not remove the `rowHeight` prop or it will crash on Safari

## Known Issues
- Sorting toggle has a race condition with the API
- Workaround: use `isLoading` ref to debounce

## TODO
- [ ] Extract sorting logic into a standalone Hook
- [ ] Replace deprecated componentWillReceiveProps

Best Practices for "AI-Friendly" Content

1. Be Explicit, Not Idiomatic

❌ Wrong: Just run the tests
✅ Right: Use npm run test

AI models respond better to explicit instructions. Avoid developer "jargon."

2. Use "Do/Don't" Lists

AI models respond exceptionally well to negative constraints:

## Type Safety
- ❌ Don't use 'any' types
- ✅ Use 'unknown' if the type is truly ambiguous
- ✅ Prefer TypeScript strict mode

3. Reference Specific Files

Let AI know where "The Truth" lives:

## Data Models
- Master schema defined in `/src/db/schema.ts`
- Type exports in `/src/types/index.ts`

4. Keep It Small

Individual context files should be under 50 lines of high-density information. If a file exceeds 10KB, AI may waste too many tokens reading it.

Hierarchical vs. Flat: Comparison

Implementation Steps

You don't have to write all of this at once. Adopt a progressive approach:

Phase 1: Root Directory

1. Create /CLAUDE.md
2. Define tech stack, build commands, code conventions

Phase 2: Core Modules

1. Identify 3-5 core business modules
2. Create CONTEXT.md for each module
3. Document data flows, security requirements, dependencies

Phase 3: Complex Components

1. Identify components with technical debt or "gotchas"
2. Create NOTES.md documenting known issues and workarounds

Phase 4: Let Claude Help

Use Claude Code itself to help generate documentation:

# Ask Claude to analyze a module and generate CONTEXT.md
claude "Analyze the billing module and create a CONTEXT.md 
        that explains the data flow and security requirements"

Summary

The core value of a hierarchical knowledge base:

1. Saves tokens: AI reads only relevant context
2. Improves precision: Specific rules apply to specific scopes
3. Easy maintenance: Small files stay close to code, low update cost
4. Scalable: Grows naturally with the project

When starting, begin with /CLAUDE.md at the root, then expand downward. Remember: The value of documentation lies in being used, not in being finished.

References

• Claude Code Official Documentation
• Progressive Disclosure in Software Design

• 先睹为快
• 执行命令
• 总结

Linux shell script 是我最喜欢的脚本之一，历史悠久，底蕴深厚，shell script 几乎是内核的一部分，托 POSIX 标准的福，你可以在任何 Linux 系统中使用它。但是编写 shell script 体验并不太好，各种奇怪的语法、没有类型检查、孱弱的数组支持，有时候排查很久的问题，仅仅是错误的使用引号、或者多了一个空格。

我很喜欢造轮子，曾打算写一个高级语言，可以编译成 shell script 执行，即使是一些简单的语法糖，也能很大程度提升 shell script 用户的幸福感。前几天发现一个项目 Amber 已经做了这些工作，试用了下还不错，语法类似 Ecmas 或者 js，支持 Text、Num、Bool、Null 和 [] 数组，可以直接编译成 shell script，直接拿到任何 shell 中执行，没有任何移植性困扰。

先睹为快

参考官网的安装指导，只需要一行命令：

curl -s "https://raw.githubusercontent.com/Ph0enixKM/AmberNative/master/setup/install.sh" | bash

请确保你的系统已安装了 curl、bc， 安装以后就可以使用 amber 命令。 下面是一个简单的例子：

let fruits = ["apple", "banana", "grape"]

fun show_opt(fruits) {
    loop index, f in fruits {
        echo "{index}: {f}"
    }
}

show_opt(fruits)

将上面的代码保存为 test1.ab, 执行它

~/test $ amber test1.ab
0: apple
1: banana
2: grape

只要你有任何一种变成经验，很容易明白 amber 的基本语法。

上面的 amber 脚本等效的 shell 如何呢？我们可以将 amber 脚本编译为 shell 脚本。

amber test1.ab test1.sh

相比直接执行 amber 脚本，只需要增加一个参数指定编译输出的脚本文件名即可。test1.sh 看起来这样：

__AMBER_ARRAY_0=("apple" "banana" "grape");
__0_fruits=("${__AMBER_ARRAY_0[@]}");
function show_opt__0_v0 {
    local fruits=("${!1}")
    index=0;
for f in "${fruits[@]}"
do
        echo "${index}: ${f}"
        let index=${index}+1
done
};
show_opt__0_v0 __0_fruits[@];
__AMBER_FUN_show_opt0_v0__9=${__AMBER_FUN_show_opt0_v0};
echo ${__AMBER_FUN_show_opt0_v0__9} > /dev/null 2>&1

相比之下，amber 脚本真的是相当人性化。

执行命令

shell 最强大的能力在于可以方便的调用已安装的命令。amber 也具备这样的能力，而且提供了良好的异常处理能力。

基本语法是

$your cmd$ failed { exception handler }

两个 $ 之间可以是任何有效的 shell 命令，failed 是 amber 的关键字，表示指令的异常处理。

为了正常使用异常机制，异常所在代码要么位于 main block，要么在函数中。amber 可以指定 main 作为脚本入口。

main {
    let file_name = "1.txt"
    let cmd = "cat"
    let file_content = ${cmd} {file_name}$ failed {
        echo "{file_name} not exist"
        fail
    }

    echo file_content
    echo "done"
}

这段代码的尝试获取 1.txt 的内容，如果这个文件不存在就报错退出，否则打印文件内容。

指令可以是任何字符串，比如例子中的命令由 cmd 和 file_name 变量拼接生成。 的标准输出可以直接赋值给变量，获取指令输出非常方便。当使用 调用指令时，必须指定异常处理，可以通过 failed 关键字指明之后的代码块用作异常处理。fail 关键字用于抛出异常。

还有一种简化的一场处理方式，上面代码可以稍作调整:

    let file_content = ${cmd} {file_name}$?

相当于

    let file_content = ${cmd} {file_name}$ failed {
        fail status
    }

我很喜欢 ? 的设计，表示指令是不可靠的，出错时就停止。二者的区别是简写方式无法指定报错信息。

总结

目前我已用 amber 作为 Linux 下编写脚本的首选工具，感觉好用。好工具，好生活，拯救脱发。

• 共享内存的原理
• 抽象共享内存指针
• 动态扩展
• 总结

开发者通常为了提高内存使用效率，或者避免内存泄漏，需要将内存池化管理。稍复杂一点的系统，一般都会有自己的内存管理机制，我在研读源码的时候，比较习惯先看内存管理模块的实现，这块很见开发者的基本工和工程思想，颇有一叶知秋之感，一个内存管理一团乱麻的系统，注定不会是艺术品。 内存池的实现方法很多，但万变不离其宗，通常就是一次申请大块内存，进程再将其化整为零的重复使用，对于操作系统来说，只发生了少数几次内存分配调用，避免长时间运行后内存碎片化。当内存池耗尽时，可以再申请一大块内存入池，实现内存池扩容。比较常见的是进程私有内存池，共享内存如何实现池化呢？

共享内存的原理

我们通常认为的内存地址，实际上并不是物理内存上的位置。操作系统出于安全性和效率考虑，每个进程都有独立的虚拟地址空间，A 进程的 0X123 和 B 进程的 0X123 处的数据通常没有任何关系。

本文均以 X64/X86 架构为例。

Linux 系统中，所有进程看到的地址空间大体如图，低地址处通常为用户程序，高地址处为内核空间。这个地址空间在不同 CPU 下也有一些差异：

• 32bit 系统中，虚拟地址空间总大小 4G，其中 1G 为内核区域。
• 64bit 系统中，只使用了 48 位地址，因此虚拟地址空间总大小为 256T，通常 8T 为内核区域。

64bit 系统的的进程虚拟地址空间非常大，普通计算机只能用到其中一小部分，操作系统通过 MMU 将虚拟地址映射到真实的物理内存上，这样只需要很小内存，也能同时运行大量程序。

在虚拟内存中地址连续的页面，在物理内存上的地址是不确定的，甚至在不同时刻，相同的虚拟内存地址也会被映射到不同的物理地址。

如果把同一块物理内存映射到两个进程的虚拟地址会发生什么呢？

任何一方修改这块区域，另一方都能立刻看到，因为它们实际上是相同的物理内存。但是请注意，这块物理内存区域在两个进程的虚拟内存中的地址却不一定相同。除非两个进程有亲缘关系，一个进程从另一个进程完整的继承了共享内存的映射关系，否则一般来说，同一块共享内存在不同进程中的地址是不同的。

抽象共享内存指针

对于没有亲缘关系的进程们，同一块共享内存通常会映射到各自虚拟内存的不同地址。显然进程之间无法共享虚拟内存地址，我们需要一种通用方法，描述共享内存中的位置。其实内存地址本质上是指针到 0x00 的偏移，我们可以稍作修改，创造一个全新的概念 “共享指针”，它也是一个偏移，但其基准地址是这块共享内存的虚拟内存地址。

无论在哪个进程，我们都可以通过共享指针，即相对共享内存起始位置的 offset 定位到相同位置，就算各进程共享内存的映射地址（起始地址）不同也没所谓。

很容易得到这样的公式：

共享指针的在进程中的真实地址 = 共享内存基址 + 共享指针（也就是 offset）；
共享指针 = 共享指针的在进程中的真实地址 -  共享内存基址；

只要将共享内存中所有指针都改为 “虚拟指针”，那么所有进程都可以将 “虚拟指针” 转换为自己虚拟内存中的地址正确访问。

共享内存就可以被切一组 block，通过一些 “共享指针”，把空闲 block 管理起来。

动态扩展

Linux 系统常见的 3 中动态内存接口：

• POSIX

  • shm_open 函数创建。
  • ftruncate 设置大小。
  • 通过mmap 将其映射到进程的地址空间，返回一个指针。
  • munmap 解除映射。
  • shm_unlink 删除共享内存对象。

• System V

  • shmget 函数。
  • shmat 将共享内存段附加到进程的地址空间，返回一个指针。
  • shmdt 从进程的地址空间分离该共享内存。
  • shmctl 支持其他操作，如删除共享内存段。

• mmap 匿名内存映射

无论哪种方式，都无法自动调整共享内存大小，有没有可能创建可以动态调整大小的共享内存池呢？前一步我们已经可以将一块共享内存按 block 管理起来，我们只需要再多申请一块共享内存，把它切分后就是一些 block 了。当所有进程都可以看到第一块共享内存的时候，如何找到新增的共享内存呢？

我们只需要在每块共享内存的特定位置，比如开始处，保存下一个共享内存的挂载参数，SystemV 接口就保存 shm key 和 size，POSIX 就保存 name 和 size，用全 0 值表示结束。 逻辑与单向链表类似，只不过通过共享内存参数而非指针串联起来。

前面我们引入一层抽象：“共享指针”，以统一的形式对所有进程描述共享内存中的位置，实际上就是共享内存中的 offset。现在情况变得复杂一点，单纯依靠 offset 已经不足以定位共享内存中的位置，还需要区分是在哪个共享内存上。是时候让 “共享指针” 变得复杂一些。

如果你对网络地址比较熟悉，应该听说过 “子网掩码”，我们也可以将 “共享指针” 的地址空间划分为共享内存编号 + offset。

以 64 位地址为例，offset 只需占据 40 位就可以支持 1T 大小的单块共享内存，以目前的硬件内存价格来说，已经是相当充足了，剩下 24 位作为共享内存编号使用，支持管理 16M 个共享内存块，也相当富余。理论上说，“共享指针” 的这两部分构成比例，决定了管理较少但更大的共享内存块，或者更小但更多共享内存块。

比如一个 “共享指针” 如图，它指向位于 1 号共享内存起始位置之后 32Bytes 位置的一块区域。共享内存中记录这些 “共享指针”，像一般指针一样构建复杂的结构。所有进程只需将 “共享指针”转换为自己的虚拟内存地址，就可以正确访问。

总结

只要 shm 中全部使用 “共享指针”，就可以扫清多进程共享内存地址映射的不一致性障碍，以很小的代价移植常见的内存管理方案。

• 文件清单
• 使用要求
• 使用方法

文件清单

压缩包中包含：

• 可执行程序 EnglishWordCheck.ext
• 示例单词清单：english_words1.txt
• 示例 word 文档：sample.doc

使用要求

1. 单词清单文件

文件名自定，文件类型为 txt。可以为不同的大纲分别准备单词表。

内容为大纲单词，各单词以空格、tab、换行分割，空白数量不限。

连接符连载一起的单词 A-B 识别为一个单词。

不区分大小写。

例如以下几种都是可以的：

apple
banana
peach

apple   banana                   peach

apple   banana
                   peach

2. 检测文件

仅支持 docx。

工具会检查 doc 中所有英文单词是否属于 1 中定义的大纲词汇。

单复数、过去时、ing 等都会自动转换为基本形式比较。也就是说单词清单中词汇的所有事态、型格都会被认为属于大纲内词汇。

使用方法

按步骤选择词汇表、word 文档，点击 check 即可。

超纲词汇报表会输出在 word 文档同级目录，与 word 文档同名的 xlsx 文件中。

• 安装 GPT4All
• 安装模型
• 进阶
• 总结

今年 AI 发展迅速，尤其是 LLM 涌现出了爆款应用 “ChatGPT”，不会整两句 GPT 你都不好意思扫共享单车。但是由于 OpenAI 的服务限制，国内访问比较困难。再加上自己的问题多少会有一些隐私问题，如果让云厂商知道我账户里的好几千巨款，心里不踏实。信息放在云端远不如运行在本地放心。

感谢伟大的开源社区，Meta 开源了 Llama2 模型，据社区测评，在多数维度可以接近 ChatGPT 的效果。后来 Github 有热心大神开发了 llama.cpp，让 LLM 运行在本地 CPU 上成为现实。llama.cpp 项目的编译安装都非常简单，如果你是个程序员，会很熟悉 ./configure && make && make install 三部曲。从 llama.cpp 开始折腾还是需要点耐心，想快速尝鲜的话，推荐 GPT4All 这款应用。大概看了下，它应该就是 llama.cpp 的 UI 版。

安装 GPT4All

GPT4All 支持 Linux、Mac、Windows 平台，前往官网 https://gpt4all.io/index.html 下载安装适合自己平台的版本。

如果需要设置代理和本地缓存目录，请点击 Setting。点击下一步。

请浏览选择安装路径，因为我打算把模型文件下载到 GPT4All 子目录，一般一个中小型模型大约在 10G 左右，所以最好安装磁盘剩余空间充足。

点击下一步。

每个软件都有的许可协议，勾选同意，继续下一步。

点击 Install，正式开始安装。

安装过程需要十分钟左右，取决于你的网速。

安装完毕。

安装模型

GPT4All 内置了一些训练好的模型，可以通过 GPT4All 下载使用。

这里先说一下如何打开 GPT4All，Mac 下安装好后会看到这两个图标：

请点击右侧图表 gpt4all 启动。左侧为管理工具。

Windows 下开始菜单里似乎只有左边的 maintenance tool，GPT4All 的本体需要去安装目录/bing/ 下找 chat.ext。总之非常诡异，可能这就是所谓的 “工程师文化”，不管你用户的死活。

如果你顺利的找到 GPT4All 的启动图标，第一次启动会看到这个页面，提示你下载模型文件。这是因为 GPT4All 只是模型框架，需要模型文件作为初始化参数。

亲测 OpenOrca 还可以，其他部分模型准确度很差。

下载前，点击最下面的 Browse，重新选择模型保存目录，为了方便，请在 GPT4All 安装目录下新建 models 目录，并将其选定为模型下载目录。

点击 OpenOrca 的 download，耐心等待下载完毕。

下载完毕就可以进入对话，与 AI 畅聊。由于这些模型的训练输入主要是英语，所以对中文支持不怎么样。虽然是基于 CPU 实现推理，但也能达到 5 Tokens 每秒，还在可以用的程度。

进阶

前面提到 GPT4All 应该是 llama.cpp 的 UI 版，所以它也支持的模型类型和 llama.cpp 是一样。除了从 GPT4All 自带的模型库选择不多，我们也可以自己从 huggingface 找到大量训练好的模型，放到前面设置的模型下载目录 models，GPT4All 也可以加载运行。

注意，模型需为 gguf 格式。

huggingface 访问速度很慢，模型又动则七八 G，推荐一个国内镜像 https://hf-mirror.com/ 下载速度可达 MB/s。

总结

试用了三四个模型，包括一个国内某大学训练的中文模型，与 ChatGPT 还有很大的差距，应该是我的电脑能力有限，最多只能跑 7B 的 llama，再加上社区训练的模型数据量和调优没法和 OpenAI 匹敌，果然 AI 时代，数据为王。如果想在本地获得比较好的使用效果，还需要针对自己的需求继续调教模型。现阶段，个人使用还是推荐云厂商的 GPT 产品，数据更新及时，有超算支撑，使用体验更好。

• system 函数
• 总结

在上一实战案例中，展示了 bpftrace 最常规的用法：观察。利用 bpftrace 可以我们可以从内核层面，观察整个服务的任何函数调用状态。借助收集到的信息，辅助定位 bug。

最近几个月我都投入在一个分布式系统的开发，在做在线故障恢复时，需要根据一些触发条件模拟故障场景调试。这些场景都不太可能通过人工直接模拟，一般采用这些方法：

直接修改代码，在复合条件时 abort；

• 动态库注入；
• 利用 LD_PRELOAD 挟持函数，改变其默认行为；
• 利用一些测试框架。 但我们有 bpftrace，就有了新选择，无需编译，随编随用，不要太方便。

system 函数

bpftrace 提供了类似 C 中的 system 函数，用于执行 shell 命令。

前面我们提到，bpftrace 脚本会被编译为 ByteCode，交由内核中的 bpf VM 执行。内核是整个系统的中枢，容不得一点闪失，放任所有资源被用户脚本控制实在太危险了。如果希望通过 bpftrace 直接修改进程行为，显然是不为系统安全策略允许的（至少目前如此）。因此 bpftrace 需要在便利和安全之间权衡，结果就是绝大多数敏感资源都被 bpf VM 隔离，用户只能获得经过审查的，限制的能力。

虽然我们无法直接通过 bpftrace 影响进程的运行状态，但是 system 函数提供了通往 shell 的道路，我们可以借助 shell 实现目的。当然 bpftrace 出于安全考虑，system 函数的调用需要 root 权限，使用时还需为 bpftrace 传入 --unsafe 参数，表明我们要做一些 “危险” 的事。

回到我要处理的问题：在满足条件时，模拟进程故障，也就是杀死某些进程。下面是虚构的例子：

// killme.bpf
uprobe:/my/lib/path/mylib.so:killme {
    system("kill -9 %d", pid)
}

当 mylib.so 中的 killme 函数被调用时，我们就向这个进程发送 kill 信号杀掉它。

然后让我们启动 bpftrace ，静静等待事件被触发：

bpftrace --unsafe killme.bpf

很简单对吧，试想一下你甚至无需拥有这个库的源码，不需要繁杂的编译过程就可以轻松实现目的，真方便！

总结

system 函数为我们开了一个窗口，借助 shell 我们几乎可以轻松的实现任何目的。在我的实际应用中，甚至实现了多台机器之间通过 bpftrace 和网络彼此触发，构成复杂的消息网络（虽然有点过度使用，但很有意思）。

• leak.c
• 探测 leak 中的 malloc 调用
• 探测 malloc 的 size
• 探测 malloc 的返回值
• 探测 free 的地址
• 探测泄漏地址
• 准确定位内存泄漏

内存泄漏是 C 开发非常经典的问题，目前已经存在很多优秀的内存检测工具，比如强大的 Valgrind。

借助 ebpftrace 我们可以非常简单、直观的找到泄漏的位置，而且非常灵活，自己决定其中的细节。

文中我构建了一个 leak.c，其中同时存在正确释放的内存和泄漏的内存，模拟一些比较复杂的内存泄漏情况。通过 ebpftrace 对运行中的 leak 程序统计内存的申请和释放过程定位内存泄漏，也就是 probe 两个关键的接口调用：

• malloc
• free

这两个接口的实现在 libc 中，后面我们会找到 leak 连接的准确 libc.so 文件。

leak.c

#include <stdio.h>
#include <stdlib.h>
#include <curses.h>

char * wrapper1(){
    return malloc(8);
}

char * wrapper2(){
    // leak here
    char * p = wrapper1();
    return malloc(16);
}

int main(){
    char * p = NULL;
    for(int i = 0; i < 5; i ++){
        p = wrapper2();
        free(p);
    }

      /* wait */
    getchar();
    return 0;
}

代码非常简单，wrapper2 内调用 wrapper1 申请到的内存没有被返回，当然永远也不会被释放，发生了泄漏；而 wrapper2 自己 malloc 一块内存返回，并在 main 中被正确释放。

• wrapper1 中申请的内存泄漏了；
• wrapper2 中申请的内存没有泄漏；

只需要简单的编译即可使用：

gcc leak.c -o leak -g

我的工作路径是: /home/test

探测 leak 中的 malloc 调用

bpftrace 主要的 probe 类型：

• kprobe/kretprobe，内核探针
• uprobe/uretprobe，用户态探针

本文的目标是 leak 程序，一个用户态进程，显然应当使用 用户态探针：uprobe/uretprobe。

首先通过 uprobe 探测 malloc 调用。

bpftrace -e 'uprobe:/home/test/leak:malloc {printf("malloc call\n")}'

参数格式是 uprobe:可执行文件:函数名，看起来一切都没有问题，但是运行上面的指令会得到这样的输出：

No probes to attach

原因是在 /home/test/leak 中找不到符号 malloc，我们可以自己确认这一事实：

# nm leak | grep malloc
  U malloc@@GLIBC_2.2.5

可以看到 malloc 是一个链接自 GLIBC_2.2.5 的符号，并不是 leak 自身的符号，因此参数中可执行文件名应当改为 GLIBC_2.2.5 对应的 so 文件 (Linux 系统的动态链接库)，具体方法稍后介绍。

其实，前面的指令只要修改需要探测的函数名为 leak.c 中定义的函数，也可以正常工作，比如：

# bpftrace -e 'uprobe:/home/test/leak:wrapper1 {printf("wrapper call\n")}'
Attaching 1 probe...
wrapper call
.... 省略一些输出
wrapper call

只不过探测的是 leak 自身的函数：wrapper1，并不是我们关注的目标。

所以，uprobe 需要指定准确的可执行文件，和该文件中的一个符号（函数）。

需要注意 printf 中的换行符 \n，如果没有换行符，数据只会在缓存中，只能在 bpftrace 退出时打印出结果，如果希望实时看到输出，就不要忘记它。

让我们继续完成 malloc 的探测，系统中可能存在多个 GLIBC 库，我们必须找到 leak 程序连接的准确文件：

# ldd leak
linux-vdso.so.1 (0x00007ffc0afaa000)
libc.so.6 => /lib64/libc.so.6 (0x00007f55ea078000)
/lib64/ld-linux-x86-64.so.2 (0x00007f55ea43d000)

第二行即 leak 链接的 libc 动态库文件，将前面 bpftrace 参数中 “可执行文件” 替换为 /lib64/libc.so.6，再次尝试：

bpftrace -e 'uprobe:/lib64/libc.so.6:malloc {printf("malloc call\n")}'

屏幕立刻输出了大量内容，但 leak 还没有开始运行啊？！

其实这些输出是系统中其他进程调用 malloc 引起的，动态库在系统中被所有进程共享，显然我们只关心 leak 程序的 malloc 调用，其他的应当被忽略。

我们需要在此参数基础上，增加 filter，过滤掉无关进程引起的函数调用事件。

bpftrace 提供了系统变量 comm 表示可执行文件名 (进程名)，只需要在上述指令中增加 filter，只处理 comm =="leak" 的 malloc 调用事件：

# bpftrace -e 'uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{printf("malloc call\n")}'
Attaching 1 probe...

bpftrace 提示 Attaching 1 probe...，成功了，只有 leak 运行时才会触发输出。

不要关闭 bpftrace 所在终端，在另外一个终端运行 leak，在 bpftrace 所在终端会看到这样的输出：

# bpftrace -e 'uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{printf("malloc call\n")}'
Attaching 1 probe...
malloc call
.... 省略一些输出
malloc call
malloc call

成功探测到 leak 的 malloc 调用！

目前参数已经变得很长了，最好将它们放在一个脚本文件 trace.bt 中，便于编辑。

uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("malloc call\n");
}

再次运行它：

# bpftrace trace.bt

然后运行 leak 程序，会得到相同的结果。

探测 malloc 的 size

bpftrace 的 uprobe 和 kprobe 可以通过内置变量 arg0、arg1 ··· ··· 访问函数参数，对 trace.bt 稍作修改就可以打印 malloc 的参数：

uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("malloc(%d)\n", arg0);
}

malloc 的原型：

void *malloc(size_t size);

第一个参数是整数，直接按 C 语言风格输出就可以。

运行新的 trace.bt:

# bpftrace trace.bt 
Attaching 1 probe...
malloc(8)
malloc(8)
malloc(16)
.... 省略一些输出
malloc(8)
malloc(16)
malloc(1024)

可以看到 malloc 调用和对应的参数，最后一个 malloc(1024) 是 leak 自动创建输出缓冲区内存申请，其他的 malloc 都是 wrapper1 和 wrapper2 中的内存申请，参数与 leak.c 源码一致。

探测 malloc 的返回值

我们更关心的是 malloc 返回的内存地址，需借助 uretprobe 进行探测，函数返回值可通过内置变量 retval 访问。uretprobe 的 filter 与 malloc 参数探测时类似:

uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("malloc(%d)\n", arg0);
}

uretprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("addr = %p\n", retval);
}

再次运行 bpftrace：

# bpftrace trace.bt 
Attaching 2 probes...
malloc(8)
malloc(8)
addr = 0xb892a0
addr = 0xb892a0
malloc(16)
.... 省略一些输出
malloc(16)
addr = 0xb89340
malloc(1024)
addr = 0xb89360

此时 trace.bt 中定义了 2 个 probe，分别用于探测 malloc 申请的内存大小和返回的地址。

探测 free 的地址

目前已经可以准确捕获 leak 申请内存的大小和返回地址，下一步探测 free 了哪些地址，只需要对比 malloc 和 free 内存地址集合的差异，就能找到内存泄漏。

参考探测 malloc 的方法，探测 free 调用非常简单，free 的内存地址正好是其第一个参数，我们使用 uprobe 即可，下面继续扩展 trace.bt:

uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("malloc(%d)\n", arg0);
}

uretprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("alloc addr = %p\n", retval);
}

/* 探测 free 的地址 */
uprobe:/lib64/libc.so.6:free /comm == "leak"/{
  printf("free addr = %p\n", arg0);
}

运行 trace.bt:

# bpftrace trace.bt 
Attaching 3 probes...
malloc(8)
malloc(8)
alloc addr = 0x19e72a0
alloc addr = 0x19e72a0
malloc(16)
.... 省略一些输出
alloc addr = 0x19e7340
free addr = 0x19e7340
malloc(1024)
alloc addr = 0x19e7360

探测泄漏地址

现在已经获得了：

• malloc 的大小、地址;
• free 的地址；

只需计算二者地址集合的差，就可以得到泄漏的地址有哪些了。

bpftrace 底层使用的是 eBPF 的 map 作为存储结构，可以简单的看作 K-V 存储，比如：

# bpftrace -e 'BEGIN{@kv["hello"] = 1; @kv["world"] = 2 } END{delete(@kv["world"]); return;}'
Attaching 2 probes...
^C

@kv[hello]: 1

BEGIN 中 在 @kv 新增了 “hello”->1, 'world' ->2 两组值，END 通过 delete 方法移除了 @kv 中的 ‘world’->2。bpftrace 结束时自动输出 @kv, 其中只剩下 “hello”->1 一组值。

这里注意 3 点：

1. @kv 在多个 probe 之间共享；
2. 对 @kv[KEY]赋值 VALUE 即创建对应对 KEY-VALUE；
3. 调用 delete(@kv[KEY]) 函数删除 KEY-VALUE；

那么可以用一个 map @mem 保存 malloc 返回的内存地址，当发生 free 调用时，从 @mem 中删除释放的地址，最后 @mem 中剩余的就是泄漏的内存地址。

uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("malloc(%d)\n", arg0);
  @size = arg0;
}

uretprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("alloc addr = %p\n", retval);
  /* 
  @size 在第一个 probe 被赋值, 内存大小。
  @mem 中记录的是 内存地址 -> 内存大小
  */
  @mem[retval] = @size;
}

uprobe:/lib64/libc.so.6:free /comm == "leak"/{
  printf("free addr = %p\n", arg0);
  /* arg0 是 free 的内存地址，删除被 free 的地址记录 */
  delete(@mem[arg0])
}

可以看到这样的结果：

# bpftrace trace.bt 
Attaching 3 probes...
malloc(8)
.... 省略一些输出
alloc addr = 0x225b360
^C

@mem[36025120]: 8
@mem[36025056]: 8
@mem[36024992]: 8
@mem[36025024]: 8
@mem[36025088]: 8
@mem[36025184]: 1024

@size: 1024

可以看到 @mem 中记录了一些内存地址和它们的大小，这些大小都是 8，对比 leak.c 代码：

char * wrapper1(){
    return malloc(8);
}

char * wrapper2(){
    char * p = wrapper1();
    return malloc(16);
}

可知 wrapper1 中的 malloc 发生了泄漏，与预期一致。

准确定位内存泄漏

上一部分已经可以得到有价值结论：发生了内存，并且根据内存大小确定了发生泄漏的位置。

但更普遍的情况下，通过内存地址或内存大小，无法确认泄漏的位置，更可靠的方法是获得内存泄漏时的调用栈。

bpftrace 的内置函数 ustack 可以获得用户态程序当前调用栈，并且可以接受参数指定获取的栈深度，默认为获得最大深度栈。

前文 @mem 中记录的是内存地址->内存大小，我们将其修改为记录内存地址->栈:

uprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("malloc(%d)\n", arg0);
  @size = arg0;
}

uretprobe:/lib64/libc.so.6:malloc /comm == "leak"/{
  printf("alloc addr = %p\n", retval);
  /* 修改了这里 */
  // @mem[retval] = @size;
  @mem[retval] = ustack();
}

uprobe:/lib64/libc.so.6:free /comm == "leak"/{
  printf("free addr = %p\n", arg0);
  delete(@mem[arg0])
}

运行结果：

# bpftrace trace.bt 
Attaching 3 probes...
malloc(8)
.... 省略一些输出
alloc addr = 0x206a360
^C

@mem[33989280]: 
        wrapper1+14
        wrapper2+18
        main+35
        __libc_start_main+243
        0x5541f689495641d7
.... 省略一些输出
@mem[33989408]: 
        wrapper1+14
        wrapper2+18
        main+35
        __libc_start_main+243
        0x5541f689495641d7
@mem[33989472]: 
        _IO_file_doallocate+144

@size: 1024

可以看到泄漏的内存都是在 wrapper1+14 申请，已经成功定位内存泄漏的位置。

• 条件语句
• 循环

bpftrace 也提供了常见的流程控制语句：

• 条件语句
• 循环语句

如果你熟悉 C 或者 Java，它们看起来会相当眼熟。

条件语句

bpftrace 的条件语句与 C 语言完全一样：

if(condition){
  statements;        //A
} else {
  statements;        //B
}

当满足条件时执行 A 处语句，否则执行 B 处语句。当然也可能有以下更简单的形式，没有 else 部分：

if(condition){
  statements;        //A
}

statements;        //B

条件满足时执行 A 处语句，然后执行 B 处语句，否则跳过 A 处语句。

多个 if-else 也可能连接在一起：

if(condition){
  statements;        //A
} else if(condition){
  statements;        //B
} else if(condition){
  statements;        //C
} else {
  statements;        //D
}

下面是一个简单的例子：

#!/bin/env bpftrace
BEGIN{
        $score = $1;

        if($score >= 90){
                $rate = "A";
        } else if($score >= 80){
                $rate = "B";
        } else if($score >= 70){
                $rate = "C";
        } else if($score >= 60){
                $rate = "D";
        } else {
                $rate = "not passed";
        }

        printf("your rate: %s\n", $rate);
        exit();
}

$score 、$rate 都是局部变量，仅在当前 action 有效。$1 比较特殊，表示 bfptrace 脚本的参数，上面的代码可以保存为文件 if_else.bt，并赋予执行权限，直接在 shell 中运行。

# ./if_else.bt 40
Attaching 1 probe...
your rate: not passed

# ./if_else.bt 60
Attaching 1 probe...
your rate: D

# ./if_else.bt 80
Attaching 1 probe...
your rate: B

不要忘记最后一行exit()，它可以免去 ctl+c 的麻烦，立刻输出结果。

循环

bpftrace 支持一种最常见的循环形式：

while(condition){
  // do something
}

当然，也支持 continue 跳过当前循环剩余部分，break 提前结束循环，这与 C 语言完全相同。需要注意的是，如果用变量作为循环条件，应当初始化正确的值。

# bpftrace -e 'BEGIN{ $i = 0; while($i < 10){printf("i = %d\n", $i); $i++} exit();}'
Attaching 1 probe...
i = 0
i = 1
i = 2
i = 3
i = 4
i = 5
i = 6
i = 7
i = 8
i = 9

另外支持 unroll，用于执行确定次数的循环, 比如打印 5 次 hello。

# bpftrace -e 'BEGIN{ unroll(5){printf("hello\n");} exit()}'
Attaching 1 probe...
hello
hello
hello
hello
hello