第 15 章 用 TypeScript 从零构造 mini-hermes(上):骨架与记忆

mini-hermes/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # 入口
│   ├── agent.ts          # 主循环
│   ├── llm.ts            # LLM 调用封装
│   ├── memory.ts         # 三层记忆
│   ├── skills.ts         # skill 加载 + 生成
│   ├── tools.ts          # 内置工具
│   ├── context.ts        # Prompt 构造
│   └── types.ts          # 类型定义
├── data/
│   ├── sessions.db       # SQLite(运行时创建)
│   ├── memory/           # 持久化笔记(运行时创建)
│   └── skills/           # 技能(运行时创建)
└── eval/
    └── basic.yaml        # 基础评估集(第 12 章提到过)

{
  "name": "mini-hermes",
  "type": "module",
  "dependencies": {
    "@anthropic-ai/sdk": "^0.30.0",
    "bun-types": "latest"
  },
  "scripts": {
    "start": "bun run src/index.ts",
    "eval": "bun run src/eval-runner.ts"
  }
}

cd mini-hermes
bun install
export ANTHROPIC_API_KEY=sk-ant-xxx  # 或者写到 .env
bun run start

// src/types.ts
 
export type Role = "user" | "assistant" | "tool_result";
 
export interface Message {
  role: Role;
  content: string | ContentBlock[];
  timestamp: number;
}
 
export type ContentBlock =
  | { type: "text"; text: string }
  | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
  | { type: "tool_result"; tool_use_id: string; content: string; is_error?: boolean };
 
export interface ToolDefinition {
  name: string;
  description: string;
  input_schema: {
    type: "object";
    properties: Record<string, unknown>;
    required?: string[];
  };
  execute: (input: Record<string, unknown>) => Promise<string>;
}
 
export interface Skill {
  name: string;
  description: string;
  triggerKeywords: string[];
  body: string;              // 完整的 SKILL.md 正文
  createdAt: number;
  lastUsedAt?: number;
  useCount: number;
  successCount: number;
  filePath: string;
}
 
export interface MemoryNote {
  path: string;              // 相对 memory/ 的路径
  content: string;
  tags: string[];
  updatedAt: number;
}
 
export interface Session {
  id: string;
  createdAt: number;
  messages: Message[];
}

// src/llm.ts
import Anthropic from "@anthropic-ai/sdk";
import type { Message, ContentBlock, ToolDefinition } from "./types";
 
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
export interface LLMCallOptions {
  model: string;              // e.g. "claude-3-5-sonnet-20241022"
  system: string;
  messages: Message[];
  tools?: ToolDefinition[];
  maxTokens?: number;
}
 
export interface LLMCallResult {
  content: ContentBlock[];
  stopReason: string;
  inputTokens: number;
  outputTokens: number;
  latencyMs: number;
}
 
export async function callLLM(opts: LLMCallOptions): Promise<LLMCallResult> {
  const start = Date.now();
 
  // 把我们的内部 Message 格式转换成 Anthropic SDK 需要的格式
  const apiMessages = opts.messages.map((m) => ({
    role: m.role === "tool_result" ? "user" : m.role,
    content: m.content as any,  // 简化:生产代码要做更严谨的类型转换
  }));
 
  // tools 转换成 Anthropic 需要的格式
  const apiTools = opts.tools?.map((t) => ({
    name: t.name,
    description: t.description,
    input_schema: t.input_schema,
  }));
 
  const response = await client.messages.create({
    model: opts.model,
    max_tokens: opts.maxTokens ?? 4096,
    system: opts.system,
    messages: apiMessages as any,
    tools: apiTools,
  });
 
  const latencyMs = Date.now() - start;
 
  // 把 response 的 content blocks 转成我们内部的格式
  const content: ContentBlock[] = response.content.map((block: any) => {
    if (block.type === "text") {
      return { type: "text", text: block.text };
    } else if (block.type === "tool_use") {
      return { type: "tool_use", id: block.id, name: block.name, input: block.input };
    }
    throw new Error(`Unknown content block type: ${block.type}`);
  });
 
  return {
    content,
    stopReason: response.stop_reason ?? "end_turn",
    inputTokens: response.usage.input_tokens,
    outputTokens: response.usage.output_tokens,
    latencyMs,
  };
}

// src/memory.ts
import { Database } from "bun:sqlite";
import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
import { existsSync } from "node:fs";
import path from "node:path";
import type { Message, Session, MemoryNote } from "./types";
 
const DB_PATH = "./data/sessions.db";
const MEMORY_DIR = "./data/memory";
 
let db: Database;
 
export async function initMemory() {
  await mkdir("./data", { recursive: true });
  await mkdir(MEMORY_DIR, { recursive: true });
 
  db = new Database(DB_PATH);
  db.exec(`
    CREATE TABLE IF NOT EXISTS sessions (
      id TEXT PRIMARY KEY,
      created_at INTEGER NOT NULL
    );
    CREATE TABLE IF NOT EXISTS messages (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      session_id TEXT NOT NULL,
      role TEXT NOT NULL,
      content TEXT NOT NULL,
      timestamp INTEGER NOT NULL,
      FOREIGN KEY(session_id) REFERENCES sessions(id)
    );
    CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts
      USING fts5(content, content='messages', content_rowid='id');
    CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
      INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
    END;
  `);
}
 
// ---------- 第一层:会话历史 ----------
 
export function createSession(): Session {
  const id = crypto.randomUUID();
  const createdAt = Date.now();
  db.prepare("INSERT INTO sessions (id, created_at) VALUES (?, ?)").run(id, createdAt);
  return { id, createdAt, messages: [] };
}
 
export function appendMessage(sessionId: string, msg: Message) {
  const contentStr = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
  db.prepare(
    "INSERT INTO messages (session_id, role, content, timestamp) VALUES (?, ?, ?, ?)"
  ).run(sessionId, msg.role, contentStr, msg.timestamp);
}
 
export function getSessionMessages(sessionId: string): Message[] {
  const rows = db
    .prepare("SELECT role, content, timestamp FROM messages WHERE session_id = ? ORDER BY id")
    .all(sessionId) as any[];
  return rows.map((r) => ({
    role: r.role,
    content: tryParseJson(r.content),
    timestamp: r.timestamp,
  }));
}
 
function tryParseJson(s: string): any {
  try {
    const parsed = JSON.parse(s);
    if (Array.isArray(parsed)) return parsed;
    return s;
  } catch {
    return s;
  }
}
 
// 跨会话检索:用 FTS5 做关键词搜索
export function searchAcrossSessions(query: string, limit = 10): Message[] {
  const rows = db
    .prepare(
      `SELECT m.role, m.content, m.timestamp
       FROM messages_fts fts
       JOIN messages m ON m.id = fts.rowid
       WHERE messages_fts MATCH ?
       ORDER BY rank
       LIMIT ?`
    )
    .all(query, limit) as any[];
  return rows.map((r) => ({
    role: r.role,
    content: tryParseJson(r.content),
    timestamp: r.timestamp,
  }));
}
 
// ---------- 第二层:持久化笔记 ----------
 
export async function listMemoryNotes(): Promise<MemoryNote[]> {
  const notes: MemoryNote[] = [];
  async function walk(dir: string, prefix: string) {
    if (!existsSync(dir)) return;
    const entries = await readdir(dir, { withFileTypes: true });
    for (const e of entries) {
      const full = path.join(dir, e.name);
      const rel = path.join(prefix, e.name);
      if (e.isDirectory()) {
        await walk(full, rel);
      } else if (e.name.endsWith(".md")) {
        const content = await readFile(full, "utf-8");
        const tags = extractTags(content);
        const stat = await Bun.file(full).stat?.();
        notes.push({
          path: rel,
          content,
          tags,
          updatedAt: stat?.mtimeMs ?? Date.now(),
        });
      }
    }
  }
  await walk(MEMORY_DIR, "");
  return notes;
}
 
export async function readMemoryNote(relPath: string): Promise<string | null> {
  const full = path.join(MEMORY_DIR, relPath);
  if (!existsSync(full)) return null;
  return readFile(full, "utf-8");
}
 
export async function writeMemoryNote(relPath: string, content: string) {
  const full = path.join(MEMORY_DIR, relPath);
  await mkdir(path.dirname(full), { recursive: true });
  await writeFile(full, content, "utf-8");
}
 
function extractTags(content: string): string[] {
  // 简化:从 frontmatter 或 content 里抓 #tag 模式
  const matches = content.match(/#[\w-]+/g) ?? [];
  return [...new Set(matches.map((t) => t.slice(1)))];
}
 
// ---------- 辅助:生成记忆的"快照"供 Prompt 使用 ----------
 
export async function buildMemorySnapshot(): Promise<string> {
  const notes = await listMemoryNotes();
  if (notes.length === 0) return "(当前无持久化笔记)";
 
  // 简化策略:把所有笔记的第一段(或前 200 字)拼起来
  const summaries = notes.map((n) => {
    const first = n.content.slice(0, 200).replace(/\n+/g, " ");
    return `- ${n.path}: ${first}...`;
  });
  return summaries.join("\n");
}

// src/tools.ts
import type { ToolDefinition } from "./types";
import { readFile, writeFile, readdir, mkdir } from "node:fs/promises";
import { existsSync } from "node:fs";
import path from "node:path";
 
const WORK_ROOT = "./data/workspace";
 
export const tools: ToolDefinition[] = [
  {
    name: "read_file",
    description: "读取 workspace 内某个文件的内容。只能读 ./data/workspace 下的文件。",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string", description: "相对 workspace 的路径" },
      },
      required: ["path"],
    },
    async execute(input) {
      const rel = input.path as string;
      const full = path.resolve(WORK_ROOT, rel);
      if (!full.startsWith(path.resolve(WORK_ROOT))) {
        return "Error: path escapes workspace";
      }
      if (!existsSync(full)) {
        return `Error: file not found: ${rel}`;
      }
      const content = await readFile(full, "utf-8");
      return content.length > 20000 ? content.slice(0, 20000) + "\n...(truncated)" : content;
    },
  },
  {
    name: "write_file",
    description: "写入文件到 workspace。会创建必要的父目录。只能写 ./data/workspace 下的文件。",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string" },
        content: { type: "string" },
      },
      required: ["path", "content"],
    },
    async execute(input) {
      const rel = input.path as string;
      const content = input.content as string;
      const full = path.resolve(WORK_ROOT, rel);
      if (!full.startsWith(path.resolve(WORK_ROOT))) {
        return "Error: path escapes workspace";
      }
      await mkdir(path.dirname(full), { recursive: true });
      await writeFile(full, content, "utf-8");
      return `OK: wrote ${content.length} bytes to ${rel}`;
    },
  },
  {
    name: "list_directory",
    description: "列出 workspace 内某个目录的内容",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string", description: "相对 workspace 的路径,默认根目录" },
      },
    },
    async execute(input) {
      const rel = (input.path as string) ?? ".";
      const full = path.resolve(WORK_ROOT, rel);
      if (!full.startsWith(path.resolve(WORK_ROOT))) {
        return "Error: path escapes workspace";
      }
      if (!existsSync(full)) return "Error: directory not found";
      const entries = await readdir(full, { withFileTypes: true });
      return entries
        .map((e) => (e.isDirectory() ? `[dir] ${e.name}` : `      ${e.name}`))
        .join("\n");
    },
  },
];

// src/context.ts
import type { Skill } from "./types";
import { buildMemorySnapshot } from "./memory";
 
export async function buildSystemPrompt(skills: Skill[]): Promise<string> {
  const memory = await buildMemorySnapshot();
  const skillsSection = buildSkillsSection(skills);
 
  return `你是 mini-hermes,一个会成长的个人 AI 助手。
 
## 你的记忆(持久化笔记)
 
${memory}
 
## 你当前可用的技能
 
${skillsSection}
 
## 行为准则
 
- 优先使用已有技能完成任务,而不是从零推理
- 如果用户的请求涉及重复性的多步操作,完成后可以建议把流程沉淀为新 skill
- 所有文件操作都在 ./data/workspace 下,不要尝试访问其他路径
- 写文件前先检查是否需要读已有内容
- 遇到错误不要慌,分析错误信息后再尝试
 
## 输出风格
 
- 直接、简洁、有判断
- 不要客套话
- 不要解释你"将要"做什么,直接做(除非是危险操作需要用户确认)
`;
}
 
function buildSkillsSection(skills: Skill[]): string {
  if (skills.length === 0) {
    return "(暂无自定义技能)";
  }
  return skills
    .map((s) => `### ${s.name}\n${s.description}\n\n触发关键词: ${s.triggerKeywords.join(", ")}\n\n(调用时请参考完整 SKILL.md,位于 ${s.filePath})`)
    .join("\n\n");
}

// src/agent.ts
import { callLLM } from "./llm";
import { buildSystemPrompt } from "./context";
import { tools } from "./tools";
import { loadSkills } from "./skills";
import { createSession, appendMessage, getSessionMessages } from "./memory";
import type { Message, ContentBlock, Session } from "./types";
 
const MODEL = "claude-3-5-sonnet-20241022";
const MAX_STEPS = 20;
 
export interface RunResult {
  response: string;
  steps: number;
  inputTokensTotal: number;
  outputTokensTotal: number;
  errored: boolean;
}
 
export class Agent {
  private session: Session;
 
  constructor(session?: Session) {
    this.session = session ?? createSession();
  }
 
  get sessionId(): string {
    return this.session.id;
  }
 
  async run(userInput: string): Promise<RunResult> {
    // 1. 记录用户输入
    const userMsg: Message = {
      role: "user",
      content: userInput,
      timestamp: Date.now(),
    };
    appendMessage(this.session.id, userMsg);
    this.session.messages.push(userMsg);
 
    // 2. 准备 system prompt 和 tools
    const skills = await loadSkills();
    const system = await buildSystemPrompt(skills);
 
    let inputTokensTotal = 0;
    let outputTokensTotal = 0;
    let steps = 0;
 
    // 3. 主循环
    while (steps < MAX_STEPS) {
      steps++;
 
      // 3a. 调 LLM
      const result = await callLLM({
        model: MODEL,
        system,
        messages: this.session.messages,
        tools,
      });
      inputTokensTotal += result.inputTokens;
      outputTokensTotal += result.outputTokens;
 
      // 3b. 记录 assistant 消息
      const assistantMsg: Message = {
        role: "assistant",
        content: result.content,
        timestamp: Date.now(),
      };
      appendMessage(this.session.id, assistantMsg);
      this.session.messages.push(assistantMsg);
 
      // 3c. 检查是否包含 tool_use
      const toolUses = result.content.filter(
        (b): b is Extract<ContentBlock, { type: "tool_use" }> => b.type === "tool_use"
      );
 
      if (toolUses.length === 0) {
        // 没有工具调用,说明 LLM 认为任务完成了
        const textBlocks = result.content.filter(
          (b): b is Extract<ContentBlock, { type: "text" }> => b.type === "text"
        );
        const response = textBlocks.map((b) => b.text).join("\n");
        return {
          response,
          steps,
          inputTokensTotal,
          outputTokensTotal,
          errored: false,
        };
      }
 
      // 3d. 执行所有 tool_use
      const toolResults: ContentBlock[] = [];
      for (const tu of toolUses) {
        const tool = tools.find((t) => t.name === tu.name);
        if (!tool) {
          toolResults.push({
            type: "tool_result",
            tool_use_id: tu.id,
            content: `Error: unknown tool ${tu.name}`,
            is_error: true,
          });
          continue;
        }
        try {
          const output = await tool.execute(tu.input);
          toolResults.push({
            type: "tool_result",
            tool_use_id: tu.id,
            content: output,
          });
        } catch (err: any) {
          toolResults.push({
            type: "tool_result",
            tool_use_id: tu.id,
            content: `Error: ${err?.message ?? String(err)}`,
            is_error: true,
          });
        }
      }
 
      // 3e. 把 tool_result 作为下一轮的输入
      const toolResultMsg: Message = {
        role: "tool_result",
        content: toolResults,
        timestamp: Date.now(),
      };
      appendMessage(this.session.id, toolResultMsg);
      this.session.messages.push(toolResultMsg);
 
      // 继续下一轮
    }
 
    // 4. MAX_STEPS 超出
    return {
      response: "(任务未完成:超出最大步数)",
      steps,
      inputTokensTotal,
      outputTokensTotal,
      errored: true,
    };
  }
}

// src/index.ts
import { initMemory } from "./memory";
import { Agent } from "./agent";
 
async function main() {
  await initMemory();
  const agent = new Agent();
 
  console.log("mini-hermes 启动。输入 exit 退出。");
  console.log(`session id: ${agent.sessionId}\n`);
 
  for await (const line of console) {
    const input = line.trim();
    if (input === "exit") break;
    if (!input) continue;
 
    try {
      const result = await agent.run(input);
      console.log(`\n${result.response}`);
      console.log(`\n[steps=${result.steps} in=${result.inputTokensTotal} out=${result.outputTokensTotal}]\n`);
    } catch (err: any) {
      console.error(`\nError: ${err?.message ?? err}\n`);
    }
  }
 
  console.log("bye");
}
 
main();

bun run src/index.ts

> 在 workspace 下创建一个 hello.txt 文件,写入 "hello from mini-hermes"

> 读一下 hello.txt 看看

console.log(`[step ${steps}] ${toolUses.length} tool use(s)`);
for (const tu of toolUses) {
  console.log(`  - ${tu.name}(${JSON.stringify(tu.input).slice(0, 80)})`);
}