为什么 Go 需要解释器? 编译语言做插件系统、脚本执行时常常被迫引入 Lua、Python 或 JavaScript。Yaegi 让你继续用 Go。

📋 目录

1. 问题背景
2. Yaegi 是什么?
3. 核心特性
4. 三大使用场景
5. 架构设计亮点
6. 快速开始
7. 实战案例
8. 性能表现
9. 适用场景与限制
10. 总结

问题背景

Go 是编译语言,这一特性带来了高性能,但也引入了一些限制:

传统 Go 的困境

核心矛盾: Go 的编译特性让动态扩展变得困难,开发者被迫引入其他语言或复杂架构。

典型案例

Traefik(云原生边缘路由器)需要插件系统让用户自定义路由逻辑:

1
2
3
4
5
6
7

传统方案:
方案1: Go plugin → 不稳定、版本兼容问题、Windows 不支持
方案2: Lua binding → 需要引入 C 库、性能开销、学习成本
方案3: 外部进程 → 通信开销、部署复杂、调试困难

Yaegi 方案:
直接在 Traefik 进程内解释执行 Go 代码 → 无通信开销、语言统一、部署简单

Yaegi 是什么?

Yaegi (Yet Another Elegant Go Interpreter) 是 Traefik Labs 开发的 Go 解释器:

关键数字

• GitHub Stars: 8,200+
• 许可证: Apache 2.0
• 语言: 纯 Go(仅标准库)
• 代码量: ~25K LOC(无外部依赖)
• 支持 Go 版本: 1.21 和 1.22
• Traefik 插件数量: 200+(使用 Yaegi)

核心定位

1
2
3
4
5

Yaegi 让 Go 代码可以在运行时解释执行,无需提前编译。
- 作为嵌入式解释器使用
- 执行 Go 脚本(shebang 支持)
- 作为动态插件系统
- 提供 REPL 交互环境

核心特性

1. 完整 Go 规范支持

支持 Go 语言规范的所有特性:

1
2
3
4
5
6
7
8
9

// 支持的特性
- 所有类型(bool, int, float, string, struct, interface...)
- 控制流(if, for, switch, select...)
- 函数(多返回值、闭包、递归...)
- 并发(goroutine, channel, select)
- 接口和类型系统
- 包管理和导入
- 反射(reflect 包)
- 错误处理

验证: Yaegi 可以解释执行自己(yaegi github.com/traefik/yaegi/cmd/yaegi)。

2. 纯 Go 实现

1
2
3
4
5
6
7

依赖树:
yaegi → Go 标准库 → 无

对比其他解释器:
gopher-lua → Lua C 库 → CGO → 外部依赖
go-python → Python C 库 → CGO → 外部依赖
otto → JavaScript → 自定义语法 → 学习成本

优势:

• 无 CGO,跨平台一致
• 无外部依赖,部署简单
• Go 开发者零学习成本

3. 安全控制

默认禁用危险包:

1
2
3
4
5
6

// 默认不导出
- unsafe 包(避免内存操作)
- syscall 包(避免系统调用)

// 需要显式启用
yaegi -syscall -unsafe -unrestricted script.go

4. 简洁 API

三个核心方法:

1
2
3

i := interp.New(interp.Options{})  // 创建解释器
i.Use(stdlib.Symbols)              // 注册标准库
i.Eval(`fmt.Println("Hello")`)     // 执行代码

三大使用场景

场景 1: 嵌入式解释器

在 Go 程序中嵌入 Go 解释器:

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

package main

import (
    "github.com/traefik/yaegi/interp"
    "github.com/traefik/yaegi/stdlib"
)

func main() {
    // 创建解释器
    i := interp.New(interp.Options{})
    i.Use(stdlib.Symbols) // 注册标准库
    
    // 执行代码
    _, err := i.Eval(`import "fmt"`)
    if err != nil { panic(err) }
    
    _, err = i.Eval(`fmt.Println("Hello Yaegi")`)
    if err != nil { panic(err) }
}

用途: 让用户通过 Go 代码自定义程序行为。

场景 2: 动态插件系统

编译时未知的功能,运行时加载:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// 主程序(main.go)
package main

import "github.com/traefik/yaegi/interp"

const pluginSrc = `
package plugin
func Process(data string) string {
    return "processed: " + data
}
`

func main() {
    i := interp.New(interp.Options{})
    
    // 加载插件代码
    _, err := i.Eval(pluginSrc)
    if err != nil { panic(err) }
    
    // 获取插件函数
    v, err := i.Eval("plugin.Process")
    if err != nil { panic(err) }
    
    // 转换为 Go 函数
    process := v.Interface().(func(string) string)
    
    // 调用插件
    result := process("test")
    println(result) // processed: test
}

优势:

• 插件即 Go 代码,无需学习其他语言
• 无进程间通信,性能好
• 部署简单,无需管理插件二进制

场景 3: Go 脚本执行

用 Go 写脚本,像 Python/Shell 一样:

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

#!/usr/bin/env yaegi
package main

import (
    "fmt"
    "os"
    "strings"
)

func main() {
    args := os.Args[1:]
    for _, arg := range args {
        fmt.Println(strings.ToUpper(arg))
    }
}

1
2
3

chmod +x script.go
./script.go hello world
# 输出: HELLO WORLD

优势:

• Go 语法,类型安全
• 无需编译步骤
• shebang 支持,像 Shell 脚本

架构设计亮点

Yaegi 的架构设计有几个独特之处:

1. AST Annotations 方式

不同于传统解释器直接解释 AST,Yaegi 采用”编译为操作树”方式:

1
2
3
4
5
6

传统解释器:
Source → AST → 直接遍历执行 → 结果

Yaegi:
Source → AST → 添加 annotations → 操作树 → 执行 → 结果
         (类型信息、符号绑定)

优势:

• 执行时携带完整类型信息
• 避免反复解析类型
• 性能更优

2. 虚拟栈机器

使用虚拟栈执行操作:

1
2
3
4
5
6

// 示例: a + b
操作序列:
1. Push a  // 栈: [a]
2. Push b  // 栈: [a, b]
3. Add     // 栈: [a+b]
4. Pop     // 栈: [], 返回 a+b

对比直接 AST 执行:

• 减少递归调用开销
• 更易优化
• 执行流程清晰

3. reflect.Value 操作

不创建新类型表示,直接用 reflect.Value:

1
2
3
4
5
6
7
8

// 传统解释器可能定义:
type IntValue struct { val int }
type StringValue struct { val string }
// 需要大量类型定义

// Yaegi 直接使用:
var value reflect.Value
// 统一操作,无需新类型

优势:

• 无需定义类型体系
• 与 Go 反射系统无缝集成
• 代码更简洁

4. ~25K LOC,无外部依赖

架构简洁:

1
2
3
4
5
6
7

文件结构:
interp/      (~20K LOC) - 解释器核心
stdlib/      (~3K LOC)  - 标准库包装
cmd/yaegi/   (~2K LOC)  - CLI 工具

依赖:
仅 Go 标准库 → 无 CGO → 无外部包

对比:

• gopher-lua: ~50K LOC + Lua C 库
• go-python: Python C 库 + CGO
• otto: ~40K LOC + 自定义 JS 类型

Yaegi 更轻量、更简洁。

快速开始

安装

1
2
3
4
5

# CLI 工具
go install github.com/traefik/yaegi/cmd/yaegi@latest

# Go 包
import "github.com/traefik/yaegi/interp"

REPL 模式

1
2
3
4
5
6
7

$ yaegi
> 1 + 2
3
> import "fmt"
> fmt.Println("Hello World")
Hello World
>

脚本执行

1
2
3
4
5
6
7
8

# 执行文件
yaegi script.go

# 执行包
yaegi github.com/some/package

# 启用 unsafe/syscall
yaegi -syscall -unsafe script.go

嵌入式使用

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

package main

import (
    "github.com/traefik/yaegi/interp"
    "github.com/traefik/yaegi/stdlib"
)

func main() {
    i := interp.New(interp.Options{})
    i.Use(stdlib.Symbols)
    
    // 执行多行代码
    i.Eval(`
        import "fmt"
        
        func greet(name string) {
            fmt.Println("Hello", name)
        }
        
        greet("World")
    `)
}

实战案例

案例 1: Traefik 插件系统

背景: Traefik 需要让用户自定义路由逻辑。

方案: 用 Yaegi 解释执行用户上传的 Go 插件。

1
2
3
4
5
6
7
8
9
10

// 用户上传的插件(plugin.go)
package traefik

import (
    "net/http"
)

func ModifyRequest(req *http.Request) {
    req.Header.Add("X-Custom", "value")
}

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

// Traefik 内部加载插件
i := interp.New(interp.Options{})
i.Use(stdlib.Symbols)

// 从用户仓库加载
i.Eval(pluginSrc)

// 获取插件函数
v, _ := i.Eval("traefik.ModifyRequest")
modify := v.Interface().(func(*http.Request))

// 在路由中调用
modify(request)

成果:

• Traefik 插件仓库有 200+ 插件
• 全部是 Go 代码
• 用户无需学习其他语言
• 插件部署零配置

案例 2: 配置文件增强

用 Go 代码表达复杂配置逻辑:

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

// config.go(解释执行)
package config

import "time"

// 动态计算超时时间
func GetTimeout() time.Duration {
    // 根据环境变量动态计算
    if isProduction() {
        return 30 * time.Second
    }
    return 5 * time.Second
}

// 动态路由规则
func ShouldRetry(status int) bool {
    return status >= 500 && status < 600
}

1
2
3
4
5
6

// 主程序加载
i := interp.New(interp.Options{})
i.Eval(configSrc)

timeout := getFunc("GetTimeout").(func() time.Duration)()
retryRule := getFunc("ShouldRetry").(func(int) bool)

优势:

• 配置有类型检查
• 可表达复杂逻辑
• 无需引入 DSL

案例 3: 测试脚本

快速编写测试脚本:

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

#!/usr/bin/env yaegi
package main

import (
    "fmt"
    "net/http"
    "time"
)

func main() {
    // 测试 API 响应时间
    start := time.Now()
    resp, err := http.Get("https://api.example.com/test")
    if err != nil {
        fmt.Println("ERROR:", err)
        return
    }
    
    elapsed := time.Since(start)
    fmt.Printf("Status: %d, Time: %v\n", resp.StatusCode, elapsed)
}

1
2
3

chmod +x test.go
./test.go
# 输出: Status: 200, Time: 123ms

性能表现

Benchmark 数据

来自 go-plugin-benchmark:

1
2
3
4
5
6
7
8
9

测试: Fibonacci(35)

编译执行:      ~1.0s
Yaegi 解释:    ~6-10x 慢

对比:
Lua (gopher-lua): ~5x 慢
Python:          ~50x 慢
JavaScript(otto): ~15x 慢

解读:

• Go 解释执行本身慢(解释器开销)
• Yaegi 相比编译慢 6-10x
• 但比 Python/JS 解释器快(Go 优化)

性能特点

适用场景

1
2
3
4
5
6
7
8
9
10

适合:
- 配置脚本(很少执行)
- 插件逻辑(偶尔调用)
- 原型验证(快速迭代)
- 工具脚本(启动快)

不适合:
- 高频计算(每秒 1000+ 次)
- 性能关键路径
- 实时系统

适用场景与限制

适用场景

已知限制

已修复问题

• 内存泄漏: 早期版本有泄漏,现已修复
• 泛型支持: Go 1.18+ 泛型逐步支持(持续改进)

对比矩阵

总结

Yaegi 的核心价值:

核心定位: Go 项目的动态扩展解决方案,让编译语言获得解释能力。

推荐使用:

1
2
3
4
5
6
7

插件系统 → Yaegi(语言统一、部署简单)
配置增强 → Yaegi(类型安全、逻辑表达)
脚本工具 → Yaegi(启动快、Go 语法)

高频计算 → 原生 Go(性能关键)
跨语言集成 → Lua/Python(生态需求)
生产插件 → go-plugin(HashiCorp 场景)

Yaegi 不是替代编译,而是补充动态能力。

延伸阅读

• Yaegi GitHub
• Yaegi 内部设计文档
• Traefik 插件文档
• Go Plugin Benchmark
• Yaegi 性能讨论

如果你需要在 Go 项目中加入插件、脚本或动态配置,不妨试试 Yaegi。毕竟,能继续用熟悉的语言,何必引入新的复杂度?

AI 编代码很快，但后端配置很慢。 PocketBase 用一个文件解决这个问题。

📋 目录

1. 问题背景
2. PocketBase 是什么？
3. 核心特性详解
4. 安装与快速开始
5. AI 编程时代的新价值
6. 实战示例
7. 适用场景与限制
8. 总结

问题背景

AI 编程工具（Claude Code、Cursor、Copilot）让写代码的速度提升了 10 倍，但后端开发仍然是个瓶颈：

传统后端的困境

现状： AI 写前端组件几秒钟，但配置后端环境要几个小时。

PocketBase 是什么？

PocketBase 是一个单文件 Go 后端，由 Goga 开发，核心理念：

Everything you need in one file.

关键数字

• GitHub Stars: 40,000+
• 许可证: MIT
• 语言: Go（单文件 ~15MB）
• 文件数量: 1 个可执行文件
• 启动时间: < 1 秒
• 内存占用: ~30MB

核心对比

1
2
3
4
5
6
7
8

传统方案                         PocketBase
Node.js + Express          →     pocketbase serve
MongoDB/PostgreSQL         →     内置 SQLite（可切换）
Socket.io 实时通信         →     内置实时订阅
JWT/OAuth 认证             →     内置用户系统
S3/MinIO 文件存储          →     内置本地存储
Prisma ORM                 →     自动生成 API
Docker Compose 部署        →     单文件部署

核心特性详解

1. 单文件架构

1
2
3
4
5
6
7

# 下载 + 运行，两步完成
wget https://github.com/pocketbase/pocketbase/releases/download/v0.23.0/pocketbase_0.23.0_linux_amd64.zip
unzip pocketbase_0.23.0_linux_amd64.zip
./pocketbase serve

# 打开 http://localhost:8090/_/ 
# 就有了一个完整的 Admin UI

一切都在一个文件里：

• Web 服务器
• 数据库（SQLite）
• Admin UI
• API 端点
• 实时 WebSocket
• 文件存储

2. 内置数据库 + 自动 API

定义一个 collection（类似数据库表），API 自动生成：

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

// 创建一个 posts collection：
// - title (text)
// - content (editor)
// - author (relation → users)
// - created (datetime)

// API 自动生成：
GET    /api/collections/posts/records      // 列表（支持分页、过滤、排序）
POST   /api/collections/posts/records      // 创建
GET    /api/collections/posts/records/:id  // 单条
PATCH  /api/collections/posts/records/:id  // 更新
DELETE /api/collections/posts/records/:id  // 删除

不需要写任何 API 代码。Collection 定义完，API 就可用。

3. 实时订阅（Realtime）

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

// 前端订阅 posts 变化
pb.collection('posts').subscribe('*', (e) => {
    if (e.action === 'create') {
        console.log('新文章:', e.record);
    }
    if (e.action === 'update') {
        console.log('文章更新:', e.record);
    }
    if (e.action === 'delete') {
        console.log('文章删除:', e.record.id);
    }
});

内置 WebSocket，无需 Socket.io、无需配置消息队列。

4. 用户认证系统

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

// 注册
await pb.collection('users').create({
    email: 'test@example.com',
    password: 'password123',
    passwordConfirm: 'password123'
});

// 登录
await pb.authWithPassword('test@example.com', 'password123');

// OAuth2 登录
await pb.authWithOAuth2({ provider: 'google' });

// 获取当前用户
const user = pb.authStore.model;

5. 文件存储

1
2
3
4
5
6
7
8
9

// 上传文件
const formData = new FormData();
formData.append('avatar', fileInput.files[0]);
formData.append('title', 'My Avatar');

await pb.collection('users').update('USER_ID', formData);

// 访问文件
const url = pb.files.getUrl(record, record.avatar, { thumb: '100x100' });

内置缩略图生成，无需配置 S3/MinIO。

6. Admin UI

打开 /_/ 路径，就有完整的后台管理界面：

• Collection 管理（类似数据库表的 CRUD）
• 用户管理
• 日志查看
• API 预览
• 设置配置

不需要写 Admin Dashboard，开箱即用。

7. 可扩展性

虽然是单文件，但支持 Go 扩展：

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

// main.go
package main

import (
    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/core"
)

func main() {
    app := pocketbase.New()
    
    // 自定义路由
    app.OnBeforeServe().Add(func(e *core.ServeEvent) error {
        e.Router.GET("/custom", func(c echo.Context) error {
            return c.String(200, "Custom endpoint")
        })
        return nil
    })
    
    app.Start()
}

当需要复杂业务逻辑时，可以写 Go 代码扩展。

安装与快速开始

下载安装

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

# macOS
brew install pocketbase

# 或直接下载
wget https://github.com/pocketbase/pocketbase/releases/download/v0.23.0/pocketbase_0.23.0_darwin_amd64.zip
unzip pocketbase_0.23.0_darwin_amd64.zip

# Linux
wget https://github.com/pocketbase/pocketbase/releases/download/v0.23.0/pocketbase_0.23.0_linux_amd64.zip

# Windows
winget install pocketbase

启动服务

1
2
3
4
5
6
7
8

# 开发模式（默认端口 8090）
./pocketbase serve

# 生产模式（绑定域名）
./pocketbase serve --http=0.0.0.0:8090

# 后台运行
./pocketbase serve --http=0.0.0.0:8090 &

前端集成

1
2
3
4
5
6

# JavaScript/TypeScript
npm install pocketbase

# 使用
import PocketBase from 'pocketbase';
const pb = new PocketBase('http://127.0.0.1:8090');

AI 编程时代的新价值

1. 让 AI 专注产品，而非基础设施

问题： Claude 写一个 Todo App 的前端只需 30 秒，但要配置 Express + MongoDB + JWT + Socket.io 可能要 10 分钟。

解决：

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

用户: "写一个实时聊天应用的前端"

AI: 
前端代码（React + Socket.io-client）... 

用户: "后端呢？"

AI: 
"传统方案：Express + Socket.io + MongoDB + JWT...
配置步骤：1. npm init... 2. npm install... 3. 配置 MongoDB...

用 PocketBase：
1. ./pocketbase serve
2. 在 Admin UI 创建 messages collection
3. 前端用 pb.collection('messages').subscribe()
完成。"

PocketBase 把后端配置从”10分钟”变成”10秒”。

2. AI 生成的代码更容易验证

传统后端复杂度高，AI 生成的 API 代码往往有问题：

• 数据库 schema 不匹配
• 认证逻辑错误
• 路由配置遗漏

PocketBase 模式：

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

AI: "我来帮你创建一个博客 API..."

用户: "用 PocketBase"

AI: 
"在 Admin UI 创建 posts collection：
- title: text, required
- content: editor
- author: relation → users
- status: select → draft/published

API 自动可用：GET /api/collections/posts/records"

验证：打开 /_/ → 创建测试数据 → 测试 API → 完成

AI 定义 schema → Admin UI 可视化验证 → API 自动可用。错误率更低。

3. 原型验证提速 10 倍

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

传统流程：
1. AI 生成前端（1分钟）
2. 手动配置后端（30分钟）
3. 调试集成（15分钟）
4. 部署测试（20分钟）
总计：66 分钟

PocketBase 流程：
1. AI 生成前端（1分钟）
2. pocketbase serve + Admin UI（1分钟）
3. 集成测试（5分钟）
4. 单文件部署（1分钟）
总计：8 分钟

创意验证周期从 1 小时变成几分钟。

4. 降低 AI 编程门槛

传统后端需要理解：

• RESTful API 设计规范
• 数据库 migrations
• 认证授权流程
• WebSocket 配置
• 文件存储策略

这些知识需要时间积累，新手 AI 编程时容易出错。

PocketBase 让 AI 编程者只需要理解：

• Collection（类似数据库表）
• Record（类似一行数据）
• subscribe（订阅实时更新）

抽象层次更高，出错概率更低。

实战示例

示例 1：实时 Todo List

AI 提示词：

1
2
3
4

用 React + PocketBase 写一个实时 Todo List：
- 登录/注册
- 创建/删除/完成 todo
- 实时同步（多用户看到即时更新）

PocketBase 配置（Admin UI）：

1. 创建 todos collection：

   • title (text, required)
   • completed (bool, default false)
   • user (relation → users)

2. 设置规则：

   • List/View: user = @request.auth.id（只能看自己的）
   • Create: user = @request.auth.id
   • Update/Delete: user = @request.auth.id

前端代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

import PocketBase from 'pocketbase';
import { useEffect, useState } from 'react';

const pb = new PocketBase('http://127.0.0.1:8090');

function TodoApp() {
  const [todos, setTodos] = useState([]);
  
  useEffect(() => {
    // 初始加载
    pb.collection('todos').getFullList().then(setTodos);
    
    // 实时订阅
    pb.collection('todos').subscribe('*', (e) => {
      if (e.action === 'create') setTodos(prev => [...prev, e.record]);
      if (e.action === 'update') setTodos(prev => prev.map(t => t.id === e.record.id ? e.record : t));
      if (e.action === 'delete') setTodos(prev => prev.filter(t => t.id !== e.record.id));
    });
    
    return () => pb.collection('todos').unsubscribe();
  }, []);
  
  const addTodo = async (title) => {
    await pb.collection('todos').create({ title, completed: false });
  };
  
  const toggleTodo = async (id, completed) => {
    await pb.collection('todos').update(id, { completed });
  };
  
  return (
    <div>
      {todos.map(todo => (
        <div key={todo.id}>
          <input type="checkbox" checked={todo.completed} onChange={() => toggleTodo(todo.id, !todo.completed)} />
          {todo.title}
        </div>
      ))}
      <button onClick={() => addTodo('New Task')}>Add</button>
    </div>
  );
}

总耗时： ~10 分钟（前端 + 配置 + 测试）

示例 2：AI 协作的博客系统

提示词：

1
2
3
4
5

用 Next.js + PocketBase 写一个博客：
- Markdown 编辑器
- 文章 CRUD
- 标签系统
- 评论功能（需登录）

PocketBase Collections：

AI 生成的代码：

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

// lib/pocketbase.ts
import PocketBase from 'pocketbase';
export const pb = new PocketBase(process.env.NEXT_PUBLIC_PB_URL);

// components/PostEditor.tsx
import { pb } from '@/lib/pocketbase';

export function PostEditor() {
  const savePost = async (data) => {
    await pb.collection('posts').create({
      ...data,
      author: pb.authStore.model.id
    });
  };
  
  return <Editor onSave={savePost} />;
}

// 实时评论订阅
pb.collection('comments').subscribe('*', (e) => {
  if (e.action === 'create' && e.record.post === postId) {
    setComments(prev => [...prev, e.record]);
  }
});

验证流程：

1. AI 生成前端 → 运行 Next.js
2. Admin UI 创建 collections → 测试数据
3. 测试 API → 调整 schema → 完成

适用场景与限制

适用场景

限制与注意点

建议： 原型/中小项目用 PocketBase；大规模用传统架构。

对比矩阵

总结

PocketBase 在 AI 编程时代找到了一个独特的位置：

核心价值：

1. 单文件部署 → 从配置基础设施变成”启动一个进程”
2. 自动 API → 从写 API 代码变成”定义 Collection”
3. 实时订阅 → 从配置 WebSocket 变成”调用 subscribe()”
4. 内置认证 → 从实现 JWT 变成”调用 authWithPassword()”

AI 编程革命：

传统模式下，AI 生成前端快，但后端配置慢。PocketBase 把后端配置变成”前端定义”，让 AI 可以端到端快速交付。

一个文件 = 一个后端。

在 AI 编程时代，这不再是梦想，而是现实。

推荐做法：

• 原型验证 → PocketBase
• 中小项目 → PocketBase + Go 扩展（如需）
• 大规模应用 → 传统架构，但原型阶段可用 PocketBase 快速验证

延伸阅读：

• PocketBase 官方文档
• PocketBase GitHub
• JavaScript SDK

60K+ Stars，一条 CLAUDE.md 文件解决 LLM 编码最头疼的三大问题。

📋 目录

1. 问题背景
2. Karpathy Guidelines 是什么？
3. 四大铁律详解
4. 安装配置
5. 实战案例
6. 最佳实践
7. 总结

问题背景

Andrej Karpathy 在 Twitter 上发过一条引发广泛讨论的帖子，总结了 LLM 编码助手最常见的三大问题：

问题 1：错误假设与隐藏困惑

“Models make wrong assumptions on your behalf and just run along with them without checking. They don’t manage their confusion, don’t seek clarifications, don’t surface inconsistencies, don’t present tradeoffs, don’t push back when they should.”

AI 常常在不确定的情况下自己瞎猜，然后一路跑下去，不会：

• 管理自己的困惑
• 寻求澄清
• 提出不一致之处
• 展示权衡方案
• 在该反对的时候反对

问题 2：过度复杂化

“They really like to overcomplicate code and APIs, bloat abstractions, don’t clean up dead code… implement a bloated construction over 1000 lines when 100 would do.”

AI 天生喜欢过度设计：

• 代码和 API 越来越臃肿
• 抽象越来越复杂
• 不清理死代码
• 100 行能解决的问题写出 1000 行

问题 3：随意修改无关代码

“They still sometimes change/remove comments and code they don’t sufficiently understand as side effects, even if orthogonal to the task.”

AI 有时会顺手改掉它不理解的东西：

• 修改或删除注释
• 改动与任务无关的代码
• 作为”副作用”引入意外变更

Karpathy Guidelines 是什么？

Karpathy Guidelines 是基于 Andrej Karpathy 观察提炼出的四条铁律，直接解决上述三大问题。

核心思想：不是让 AI 更聪明，而是给 AI 明确的行为约束。

四大铁律详解

1. Think Before Coding

核心：不要假设。不要隐藏困惑。展示权衡。

LLM 的天性是选一个解释然后一路跑下去。这条铁律强制它显式思考：

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

❌ 错误做法（隐藏假设）：
AI: 我来帮你添加用户认证...
    [直接开始写代码]

✅ 正确做法（显式思考）：
AI: 你提到"添加用户认证"，我需要澄清：
    1. 认证方式：JWT 还是 Session？
    2. 是否需要社交登录？
    3. 密码重置用邮件还是短信？
    
    推荐方案：
    - JWT：适合分布式部署
    - Session：适合单体应用，实现简单
    
    你的系统目前是单体，我推荐 Session。同意吗？

执行要点：

• 明确假设 - 不确定就问，不要猜
• 多方案展示 - 别偷偷选一个，展示 2-3 种方案
• 主动反对 - 有更简单的方案就说出来
• 停下来澄清 - 不清楚就问，不要假装明白

2. Simplicity First

核心：最小代码解决问题。不做投机性设计。

对抗 AI 的”过度设计冲动”：

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

❌ 错误做法（过度设计）：
AI: 我添加了一个配置系统：
    - 支持环境变量
    - 支持 JSON 文件
    - 支持远程配置中心
    - 支持热更新
    - 支持 schema 验证
    [总共 800 行代码]

用户: 我只是想改个数据库连接字符串...

✅ 正确做法（最小代码）：
AI: 我添加了环境变量配置：
    DATABASE_URL = os.environ.get('DATABASE_URL', 'default')
    [1 行代码]
    
    如果以后需要更多配置，到时候再加。

执行要点：

• 没有要求的功能不加
• 单次使用的代码不抽象
• 没有要求的”灵活性”不加
• 不可能发生的情况不处理
• 200 行能写成 50 行，就重写

检验标准：资深工程师看了会说”这也太复杂了”吗？如果会，就简化。

3. Surgical Changes

核心：只改必须改的。只清理自己产生的垃圾。

防止 AI “顺手优化”周边代码：

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

❌ 错误做法（顺手优化）：
任务: 添加日志记录
AI 改了：
    - 添加了日志 ✅
    - "顺便"重构了错误处理 ❌
    - "顺便"改了变量命名 ❌
    - "顺便"删除了"看起来无用"的注释 ❌
    - "顺便"格式化了整个文件 ❌

✅ 正确做法（手术式修改）：
任务: 添加日志记录
AI 只改了：
    - 添加了日志 ✅
    
    注意：看到 `old_function()` 可能无用，但不删除，因为不在任务范围内。

执行要点：

• 不”优化”邻近代码、注释、格式
• 不重构没坏的东西
• 匹配现有风格，即使你觉得更好的
• 注意到无关死代码 → 提示用户，不直接删

检验标准：每行改动都能追溯到用户的请求。

4. Goal-Driven Execution

核心：定义成功标准。循环直到验证。

把命令式任务转化为可验证的目标：

多步骤任务的规划模板：

1
2
3

1. [步骤] → verify: [检查点]
2. [步骤] → verify: [检查点]
3. [步骤] → verify: [检查点]

执行要点：

• 成功标准强 → AI 可以独立循环
• 成功标准弱（”让它工作”）→ 需要频繁澄清

Karpathy 原话：

“LLMs are exceptionally good at looping until they meet specific goals… Don’t tell it what to do, give it success criteria and watch it go.”

安装配置

方式一：Claude Code 插件（推荐）

1
2
3
4
5

# 1. 添加市场
/plugin marketplace add multica-ai/andrej-karpathy-skills

# 2. 安装插件
/plugin install andrej-karpathy-skills@karpathy-skills

方式二：CLAUDE.md 文件（项目级）

新项目：

1

curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md

现有项目（追加）：

1
2

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

方式三：Cursor

Cursor 版本在 .cursor/rules/karpathy-guidelines.mdc：

1
2

# 复制到你的项目
cp .cursor/rules/karpathy-guidelines.mdc your-project/.cursor/rules/

详见 CURSOR.md。

实战案例

案例 1：Think Before Coding

场景：添加缓存功能

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

你: 帮我给 API 加个缓存

AI（遵循铁律）:
    我理解你想添加缓存。让我先澄清：

    1. 缓存策略：
       - 内存缓存（适合单机，简单）
       - Redis（适合分布式，需要额外部署）
       
    2. 缓存粒度：
       - 整个响应？
       - 还是部分数据？
       
    3. 缓存失效：
       - TTL 自动过期？
       - 还是手动触发？
       
    你的 API 目前是单机服务，我推荐内存缓存 + TTL。
    同意这个方向吗？

没有铁律的情况：

1
2
3
4
5

你: 帮我给 API 加个缓存

AI（跳过思考）:
    [直接开始写 Redis 集成代码]
    [你发现：你根本不需要 Redis，浪费了半天]

案例 2：Simplicity First

场景：实现错误处理

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

❌ 过度复杂（无铁律）：
AI: 我创建了一个完整的错误处理系统：
    - 自定义 Error 类（BaseError, ValidationError, AuthError...）
    - 全局错误中间件
    - 错误日志服务
    - 错误上报到 Sentry
    - 错误重试机制
    [500 行代码]

用户: 我只是想让 API 返回正确的错误格式...

✅ 简洁设计（有铁律）：
AI: 我添加了简单的错误格式化：
    def format_error(e):
        return {"error": str(e), "code": "UNKNOWN"}
    [20 行代码]
    
    以后如果需要更多错误类型，再加。

案例 3：Surgical Changes

场景：修改配置文件

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

❌ 顺手优化（无铁律）：
任务: 添加新的环境变量
AI 改了：
    - 添加了新变量 ✅
    - "顺便"把所有变量名改成更"规范"的 ❌
    - "顺便"加了类型注释 ❌
    - "顺便"重组了文件结构 ❌
    
    结果：整个项目的环境变量引用都坏了

✅ 手术式修改（有铁律）：
任务: 添加新的环境变量
AI 只改了：
    - 添加了新变量 ✅
    
    保持原有变量名、格式、结构不变。

案例 4：Goal-Driven Execution

场景：修复登录 bug

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

❌ 命令式（弱目标）：
你: 修复登录失败的 bug
AI: 我改了代码，应该能工作了
    [没测试，假设已修复]

✅ 目标式（强目标）：
你: 修复登录失败的 bug

AI（遵循铁律）:
    目标: 让 `test_login_with_expired_token` 通过
    
    Step 1: 写复现测试 → verify: 测试失败 ✅
    Step 2: 分析根因 → verify: 找到 token 过期检查遗漏
    Step 3: 修复根因 → verify: 测试通过 ✅
    Step 4: 验证其他测试 → verify: 无新增失败 ✅
    
    完成：登录 bug 已修复，所有测试通过。

最佳实践

1. 检验是否生效

这些铁律生效时，你应该看到：

• diff 更干净 - 只有请求的改动，没有”顺手优化”
• 首次就简洁 - 不需要重写过度复杂的代码
• 先问后写 - 澄清问题出现在实现之前，而不是出错之后
• PR 更干净 - 没有 drive-by refactor 或”顺便改进”

2. 项目定制

铁律可以与项目特定规则合并：

1
2
3
4
5
6
7

## Karpathy Guidelines（来自插件）

## 项目特定规则

- 使用 TypeScript strict mode
- 所有 API 端点必须有测试
- 遵循 `src/utils/errors.ts` 的错误处理模式

3. 权衡：谨慎 vs 速度

这些铁律偏向谨慎。对于真正简单的任务（修复 typo、显而易见的一行改动），可以灵活处理。

目标：减少非琐碎工作的错误，不是拖慢简单任务。

4. 常见信号

当 AI 有这些想法时，警惕：

总结

Karpathy Guidelines 的核心价值：

不是让 AI 更聪明，而是给 AI 明确的行为边界。

如果你在使用 AI 编码助手时遇到过：

• AI 瞎猜需求，写出一堆你不需要的功能
• AI 顺手改了不该改的东西，引入 bug
• AI “修复”一个问题，又搞出两个新问题
• AI 说”应该能工作”，结果根本没验证

Karpathy Guidelines 可能就是你需要的——不是更好的 AI，而是更有纪律的 AI。

延伸阅读

• Karpathy Guidelines GitHub
• Andrej Karpathy 原推文
• Superpowers 入门指南
• Everything Claude Code
• Engram 持久记忆

一个会学习的 AI Agent —— 不是工具，是伙伴。

📋 目录

1. Hermes Agent 是什么？
2. 核心特性详解
3. 架构概览
4. 安装与使用
5. Hermes vs OpenClaw：全面对比
6. 为什么选择 Hermes？
7. 总结

Hermes Agent 是什么？

Hermes Agent 是由 NousResearch 开发的自进化 AI 代理框架。

与传统的 AI 助手不同，Hermes 的核心能力在于从交互中学习：它会把每次对话中获得的经验转化为可复用的技能，同时构建跨会话的用户画像，让你越用越懂你。

用一句话概括：

OpenClaw 是一个出色的 AI 自动化执行者；Hermes 则是一个会成长的 AI 学习伙伴。

关键数字

• GitHub Stars: 78,000+
• 许可证: MIT
• 主要语言: Python (93.3%)
• 内置工具: 40+
• 支持消息平台: 6+

核心特性详解

1. 闭环学习系统

这是 Hermes 最核心的差异化能力。

工作流程：

1

交互 → 记忆提取 → 技能创建 → 技能进化 → 用户画像构建

• Agent 策展的记忆：Hermes 会自动记录有意义的交互，周期性地进行摘要整理
• 自主技能创建：完成复杂任务后，自动把操作步骤封装为可复用的技能
• 技能自进化：技能在使用过程中持续自我优化
• FTS5 会话搜索：基于全文检索的跨会话记忆，配合 LLM 摘要实现深度上下文召回
• Honcho 用户画像：基于辩证对话的用户建模，随着交互深入不断修正对用户的理解

简单来说，你用得越多，它就越了解你的工作习惯、偏好和上下文。

2. 多平台消息集成

一个网关进程，统一接入所有消息平台：

• Telegram
• Discord
• Slack
• WhatsApp
• Signal
• CLI (本地终端)

支持语音备忘录转录和跨平台对话连续性——你在 WhatsApp 上开始的话题，可以在 Discord 上无缝继续。

3. 模型灵活性

Hermes 不绑定任何单一模型供应商，支持：

这意味着你可以随时切换模型、测试不同模型的表现，或者使用自己的私有模型。

4. 终端后端（6 种）

Hermes 支持在多种环境中执行任务：

• local — 本地直接执行
• Docker — 容器化隔离执行
• SSH — 远程服务器执行
• Daytona — 云端开发环境
• Singularity — HPC/科研环境
• Modal — Serverless 执行（支持持久化）

5. 调度与自动化

内置 cron 调度器，可以直接通过消息平台触发定时任务：

• 每日报告
• 自动备份
• 定期审计

6. 并行委派

Hermes 可以：

• 生成隔离子代理：并行处理独立工作流
• Python RPC 执行：直接在 Python 环境中运行脚本

7. 研究能力

对于研究者，Hermes 提供：

• 批量轨迹生成
• Atropos RL 环境支持
• 轨迹压缩（用于训练）

这让 Hermes 不仅是工具，也是研究 AI Agent 行为的平台。

架构概览

1
2
3
4
5
6
7

hermes-agent/
├── agent/          # 核心 Agent 逻辑
├── skills/         # 技能系统（程序化记忆）
├── tools/          # 40+ 工具实现
├── gateway/        # 消息平台网关
├── plugins/        # 插件系统
└── hermes_cli/     # CLI 接口

记忆系统

Hermes 的记忆分为两个层面：

1. 持久记忆：跨会话保存，构建用户画像
2. 技能系统：程序化记忆，符合 agentskills.io 开放标准

MCP 集成

Hermes 可以连接任意 MCP (Model Context Protocol) 服务器，扩展能力边界。

CLI 命令

1
2
3
4
5
6
7
8

hermes              # 启动交互式对话
hermes model        # 选择 LLM 提供商和模型
hermes tools        # 配置启用的工具
hermes config set   # 设置单个配置项
hermes gateway      # 启动消息网关
hermes setup        # 完整安装向导
hermes update       # 更新到最新版本
hermes doctor       # 诊断问题

安装与使用

一键安装

1

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

支持 Linux、macOS、WSL2，甚至 Android Termux。

从 OpenClaw 迁移

如果你已经是 OpenClaw 用户，Hermes 提供了迁移工具：

1

hermes claw migrate

自动导入：设置、记忆、技能、API Key，无缝切换。

Hermes vs OpenClaw：全面对比

这是本文的重点。让我们从多个维度来比较这两个框架。

基础信息对比

核心理念差异

Hermes：成长型伙伴

1

使用次数越多 → 了解你越多 → 技能越丰富 → 越有用

Hermes 把每次交互视为学习机会，技能可以自创建、自进化。

OpenClaw：全能执行者

1

安装越多 Skills → 能做的事越多 → 自动化能力越强

OpenClaw 强调即插即用的执行能力，社区有 5,400+ Skills 可选。

功能对比矩阵

场景推荐

选择 Hermes，如果你：

1. 希望 Agent 能学习你的习惯，越用越聪明
2. 需要中国模型支持（GLM 智谱、Kimi 月之暗面、MiniMax）
3. 需要多种执行环境（Docker、SSH、Serverless）
4. 做 AI Agent 研究，需要轨迹生成和训练数据
5. 喜欢 Python 生态
6. 从 OpenClaw 迁移，想要无缝切换

选择 OpenClaw，如果你：

1. 需要最多消息平台支持（20+，含 iMessage、Teams、WeChat）
2. 需要浏览器自动化（内置 Chromium 控制）
3. 需要 Canvas 可视化工作区
4. 需要语音唤醒和 Talk 模式
5. 需要多 Agent 路由（不同渠道路由到不同 Agent）
6. 喜欢 Node.js 生态
7. 需要成熟的 Skill 市场（ClawHub 5,400+ Skills）

一句话总结

OpenClaw 是一个功能丰富的”瑞士军刀”——能做的事多且广。
Hermes 是一个会成长的”学徒”——用得越多，越懂你。

两者不是竞争关系，而是互补关系。事实上，Hermes 提供了从 OpenClaw 的迁移工具，说明社区也在鼓励用户根据需求选择最合适的框架。

为什么选择 Hermes？

1. NousResearch 的学术背景

NousResearch 是一家专注于 AI 研究的机构，其 Hermes 系列模型 在开源社区有着良好的声誉。这意味着 Hermes Agent 不仅是一个工具，也融入了学术级的 Agent 研究能力。

2. 真正会”学习”的 Agent

大多数 AI Agent 的记忆只是简单的聊天记录存储。Hermes 的 Honcho 用户建模系统会：

• 构建跨会话的用户画像
• 通过辩证对话不断修正理解
• 提供 FTS5 全文检索 + LLM 摘要的混合搜索

3. 中国模型友好

如果你在国内使用，Hermes 原生支持：

• GLM (智谱) — z.ai 提供商
• Kimi (月之暗面) — Moonshot
• MiniMax

这在海外 AI Agent 框架中是比较少见的。

4. 灵活的执行环境

从本地到 Docker、从 SSH 到 Serverless，Hermes 让你在不同安全级别和性能需求下自由选择。

总结

Hermes Agent 代表了一种新的 AI Agent 范式：不是让 Agent 能做更多事，而是让 Agent 更懂你。

它的闭环学习系统、模型灵活性和研究能力使其在众多 AI Agent 框架中脱颖而出。如果你希望有一个越用越聪明的 AI 伙伴，Hermes 值得一试。

与 OpenClaw 的对比也说明了一个趋势：AI Agent 正在分化为不同的定位——有的偏向全能自动化，有的偏向个人学习和协作。选择哪个，取决于你最看重什么。

相关链接：

• Hermes Agent GitHub
• NousResearch 官网
• OpenClaw GitHub
• agentskills.io 开放标准

延伸阅读：

• Superpowers 入门指南：让 AI 助手真正成为你的编程伙伴
• Everything Claude Code 使用指南

我无法再忍受 Oh My Zsh 的速度了。 这是我决定切换到 Starship 的根本原因。

终端是开发者每天打交道最多的工具。一个快速、美观、高效的终端环境，能让开发体验提升好几个档次。这篇文章记录了我从 Oh My Zsh 到 Starship 的迁移过程，以及 Ghostty 终端的选择理由。

为什么放弃 Oh My Zsh？

用了五年 Oh My Zsh，它的生态和插件确实强大，但性能问题一直是个痛点：

测试对比（我的 MacBook Pro M3 Pro）：

1
2
3
4
5
6
7

# Oh My Zsh 启动时间
time zsh -i -c exit
# 0.85s - 1.2s

# Starship 启动时间  
time zsh -i -c exit
# 0.15s - 0.25s

5-8 倍的性能提升，这就是切换的最好理由。

最终方案：Ghostty + ZSH + Starship

整体架构

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

┌─────────────────────────────────────────────┐
│                  Ghostty                     │
│           (终端模拟器，渲染层)                │
│   - GPU 加速渲染                             │
│   - 透明背景 + 毛玻璃效果                    │
│   - 现代字体渲染                             │
└────────────────┬────────────────────────────┘
                 │
┌────────────────┴────────────────────────────┐
│                   ZSH                        │
│           (Shell，基础层)                    │
│   - 极简配置 (~80 行)                        │
│   - 只加载必要工具                           │
│   - 无框架，原生体验                         │
└────────────────┬────────────────────────────┘
                 │
┌────────────────┴────────────────────────────┐
│                 Starship                     │
│           (Prompt，展示层)                   │
│   - Rust 编写，极速渲染                      │
│   - 跨 Shell 兼容                           │
│   - 高度可配置                              │
└─────────────────────────────────────────────┘

为什么是 Ghostty？

之前用过 iTerm2、Alacritty、Kitty、Warp，最终选择 Ghostty 的原因：

Ghostty 由 HashiCorp 创始人 Mitchell Hashimoto 开发，追求开箱即用的最佳实践，配置简单但功能强大。

为什么是 Starship？

对比了 Powerlevel10k、Pure、Spaceship 后选择 Starship：

• ⚡ 极速：Rust 编写，渲染时间 < 10ms
• 🔧 配置简单：一个 TOML 文件搞定
• 🌍 跨平台：支持 Bash、Zsh、Fish、PowerShell
• 📦 开箱即用：无需复杂配置就能很好看
• 🎨 高度可定制：想怎么改就怎么改

我的配置分享

Ghostty 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# ~/Library/Application Support/com.mitchellh.ghostty/config

# 主题与字体
theme                          = Aura
font-family                    = Maple Mono NF CN
font-size                      = 15
font-thicken                   = true
font-feature                   = calt, cv01, cv03, ss01, ss02, ss03

# 窗口设置
window-height                  = 20
window-width                   = 100
window-padding-balance         = true 
window-save-state              = always

# 透明效果
background-opacity             = 0.97
background-blur                = true

# macOS 集成
macos-titlebar-style           = tabs
macos-option-as-alt            = true
macos-icon                     = xray

# Shell 集成
shell-integration              = zsh
shell-integration-features     = cursor,sudo,title

# 性能优化
scrollback-limit               = 4200
window-vsync                   = true

关键配置说明：

1. 字体选择：Maple Mono NF CN - 支持 Nerd Font 图标和中文
2. 透明度 0.97：微透明，既能看到背景又不影响阅读
3. macos-titlebar-style = tabs：紧凑的标签栏样式
4. shell-integration：启用 Ghostty 的 Shell 集成功能

ZSH 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42