@easbot/buddy

English | 中文

@easbot/buddy 是 EASBot 生态系统的 会话级以下 LLM 子系统，提供完整的宠物（Buddy）AI。设计目标是简化版的 Agent LLM —— 可以注入 system / prompt / tools / 编排，但不引入 session / messageId / bus 等重量级概念，也不依赖 @easbot/agent。

v0.1（独立成包） —— 原 @easbot/llm/buddy v0.5+ 从 @easbot/llm 拆分出来，独立成 @easbot/buddy workspace 包。所有业务 API、CLI、MCP server 行为完全兼容（仅包路径从 @easbot/llm/buddy 改为 @easbot/buddy）。

版本

v0.3.28

适用场景

• 需要一个独立的 LLM 子系统（buddy / critic / summarizer / persona / 任意 task-specific agent），但不想拉起完整 agent session
• 需要确定性属性 + 生成式属性 + 持续进化成长的虚拟角色（参考 Anthropic Claude Code CLI 的 buddy / companion 系统）
• 需要把 buddy 挂到主 agent（system 段注入 + 每 turn 反应触发），或者独立运行（CLI / MCP / 嵌入式 SDK）

核心特性

• 完整属性系统：Bones（确定性 hash-based roll）+ Soul（LLM 生成）+ Stats（累积式 growth + level-up）+ Memory（append-only 事件流）
• 反应触发器：速率限制（默认 45s）+ 去重 + @-mention 检测 + LLM streamText 生成反应文本 + ReAct 循环（可注入 tools）
• 提示词注入：injectBuddyContext(system, buddy) 把 "宠物在旁边..." 段 append 到主 agent 的 system 段
• 持续进化：每次 react / addressed / feedback 都触发 stats 累积；累计 100 growth 自动 level-up；soul 可通过 mutateSoul() 重新生成
• SQLite 持久化：复用 @easbot/database 的 DatabaseInterface；同时提供 InMemory 实现便于测试
• 独立 CLI：easbot-buddy 命令（status / hatch / react / inject / memory / mutate / init / doctor / mcp / help）
• MCP server：5 个 tool（buddy_status / buddy_hatch / buddy_react / buddy_inject / buddy_memory），可被任意 MCP client 接入
• 三层架构（v3.1）：database（L1 DB 层）+ services（L2 纯算法）+ operations（L3 op registry + zod schemas + trust gate），与 note / memory 包对齐
• i18n：zh-CN / en-US 双语，与 memory/note/codebase 三包模式对齐
• 独立 .easbot/buddy.json 配置：与 codebase/note/memory 子配置风格一致
• Adapter Registry：复用 @easbot/llm 的 IGlobalPathProvider 单例（buddy 内部 defaultDbPath() / cli.ts logDir 等），无需在 buddy 包再注册一份

快速上手

import { runBuddy } from '@easbot/buddy';
import { createInMemoryBuddyStorage } from '@easbot/buddy';
import { Provider } from '@easbot/llm';
import type { ModelMessage } from 'ai';

// 1. 准备 storage（生产用 createSqliteBuddyStorage）
const storage = createInMemoryBuddyStorage();

// 2. 解析语言模型
const modelInfo = await Provider.defaultModel();
const languageModel = await Provider.getLanguage(modelInfo);

// 3. 一行调用（自动 hatch + react + persist + evolve）
const messages: ModelMessage[] = [
  { role: 'user', content: '今天想搞个 TODO list app。' },
  { role: 'assistant', content: '好的，先列需求？' },
];

const result = await runBuddy({
  userId: 'user-1',
  storage,
  messages,
  abort: new AbortController().signal,
  languageModel,
});

console.log(result.reaction); // 短反应文本（≤ 100 字符）
console.log(result.buddy.stats); // 最新 stats
console.log(result.levelUp); // 本次是否升级

独立 CLI

@easbot/buddy 编译后自带 easbot-buddy bin：

easbot-buddy status
easbot-buddy hatch
easbot-buddy react --addressed
easbot-buddy inject
easbot-buddy memory --limit 10
easbot-buddy mutate --directive "变得傲娇一些"
easbot-buddy init --db-path /path/to/buddy.db
easbot-buddy doctor
easbot-buddy mcp
easbot-buddy --help

dev 模式（tsx 直接跑源码）：

pnpm --filter @easbot/buddy exec tsx src/cli.ts status
pnpm --filter @easbot/buddy exec tsx src/cli.ts hatch --rehatch
pnpm --filter @easbot/buddy exec tsx src/cli.ts react --transcript '[{"role":"user","content":"hi"}]'

MCP Server

easbot-buddy mcp \
  --user alice \
  --db-path /path/to/buddy.db \
  --model openai/gpt-4o

启动后会监听 stdio，导出 5 个 tool（buddy_status / buddy_hatch / buddy_react / buddy_inject / buddy_memory），可被任意 MCP client 接入。

演示

参考 packages/{note,memory}/examples/ 的三件套（test-.ts / debug-.ts / e2e-mcp-stdio.ts）， buddy 提供同模式 demo：

# 1. 配置 .env（cp 模板后填 MINIMAX_API_KEY）
cp examples/.env.example examples/.env

# 2. 跑 9 op 完整 demo
pnpm --filter @easbot/buddy exec tsx examples/test-buddy.ts

# 3. SQLite db 完整性检查
pnpm --filter @easbot/buddy exec tsx examples/debug-buddy.ts

# 4. E2E MCP 测试（先 build）
pnpm --filter @easbot/buddy build
pnpm --filter @easbot/buddy exec tsx examples/e2e-mcp-stdio.ts

输出 test-buddy.ts 会跑完整 init → status → hatch → inject → react × 3 → memory → mutate → doctor → config → sync 流程。

与 agent/session 的边界

| 维度 | @easbot/agent/session | @easbot/buddy | | ----------------------------- | ----------------------- | -------------------------------- | | 会话 ID | 必须 | 不需要 | | Message / Part | 必须 | 不需要 | | Permission / Compaction / Bus | 必须 | 不需要 | | Context Engine | 必须 | 不需要 | | Tool Builder | 必须 | 可选（直接传入 AI SDK tool） | | 一次调用相当于 | 一个 session | 一次 react |

目录结构（v3.1）

packages/buddy/
├── core/        领域算法（roll / soul / evolution / inject / react / react-tools / storage）
├── database/    L1 DB 层（BuddyDatabaseManager + schema migrations）
├── services/    L2 纯算法 service（9 op × 4 类，typed context + assertLanguageModelRequired）
├── operations/  L3 op registry + zod schemas + trust gate（OP_REGISTRY + executeOp）
├── format/      CLI / MCP 输出渲染
├── i18n/        zh-CN / en-US 双语（locales/* + translator + config）
├── commands/    CLI 端（每个 cmd 独立文件，复用 services executeOp）
├── mcp/         MCP stdio server
├── examples/    buddy-demo.ts（独立演示）
├── cli-handler.ts  主调度入口（遍历 commands/* 派发）
├── cli.ts        独立 CLI bin 入口
├── config.ts     配置加载（zod schema + XDG 兜底）
├── types.ts      业务类型（5 档 rarity / 18 个 species / 5 维 stat）
├── interfaces.ts Adapter Registry（与 @easbot/llm 共享单例）
└── index.ts      聚合导出（推荐 namespace 入口 `Buddy.*`）

安装

pnpm add @easbot/buddy @easbot/llm ai zod

Provider 来自 @easbot/llm；如果你已经接好了 LLM，可以省略 ai 的依赖（@easbot/buddy 已 peerDependencies-style 透传）。

开发命令

pnpm --filter @easbot/buddy dev              # tsup watch 模式
pnpm --filter @easbot/buddy build            # 产线构建（产物到 dist/）
pnpm --filter @easbot/buddy test:run         # 跑全部单测
pnpm --filter @easbot/buddy test:coverage    # 覆盖率
pnpm --filter @easbot/buddy type-check       # tsc --noEmit
pnpm --filter @easbot/buddy lint             # biome check
pnpm --filter @easbot/buddy lint:fix         # biome 自动修
pnpm --filter @easbot/buddy format           # biome format
pnpm --filter @easbot/buddy publish:npm      # 发布（Unix）
pnpm --filter @easbot/buddy publish:npm:win  # 发布（Windows PowerShell）

详细规范

详见 .easbot/knowledge/docs/dev/llm-buddy-module/：

• alignment.md
• spec.md
• design.md
• tasks.md
• review.md — v2 PASS baseline
• review2.md — v3 重构评审

决策日志

详见 docs/decisions/0091-buddy-three-layer-ops-refactor.md — 即 v3.1 三层重构（database / services / operations）的决策记录。