第 16 章 mini-hermes(下):让它自己写 Skill

---
name: create-daily-note
description: 在 workspace/notes/ 下创建按日期命名的笔记文件
triggerKeywords:
  - 创建今日笔记
  - 新建日记
  - daily note
---
 
## 步骤
 
1. 用 list_directory 确认 notes/ 目录存在,不存在则创建
2. 用 write_file 创建 `notes/YYYY-MM-DD.md`
3. 文件初始内容:标题行 + 空 "## 今天的事" 段落
4. 返回文件路径给用户

// src/skills.ts
import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
import { existsSync } from "node:fs";
import path from "node:path";
import type { Skill } from "./types";
 
const SKILLS_DIR = "./data/skills";
 
export async function loadSkills(): Promise<Skill[]> {
  if (!existsSync(SKILLS_DIR)) {
    await mkdir(SKILLS_DIR, { recursive: true });
    return [];
  }
 
  const skills: Skill[] = [];
  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
  for (const e of entries) {
    if (!e.isDirectory()) continue;
    const skillPath = path.join(SKILLS_DIR, e.name, "SKILL.md");
    if (!existsSync(skillPath)) continue;
 
    const body = await readFile(skillPath, "utf-8");
    const parsed = parseSkillMarkdown(body, skillPath);
    if (parsed) skills.push(parsed);
  }
  return skills;
}
 
function parseSkillMarkdown(content: string, filePath: string): Skill | null {
  // 简化的 frontmatter 解析:用 --- 做分隔符
  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
  if (!match) return null;
  const fm = match[1];
  const body = match[2];
 
  // 从 frontmatter 里抓几个字段(不做完整 YAML 解析,保持简单)
  const name = extractField(fm, "name");
  const description = extractField(fm, "description");
  const kwLine = extractField(fm, "triggerKeywords") ?? "";
  const triggerKeywords = parseList(fm, "triggerKeywords");
 
  if (!name || !description) return null;
 
  return {
    name,
    description,
    triggerKeywords,
    body: content,
    createdAt: Date.now(),
    useCount: 0,
    successCount: 0,
    filePath,
  };
}
 
function extractField(fm: string, key: string): string | undefined {
  const re = new RegExp(`^${key}:\\s*(.+)$`, "m");
  const m = fm.match(re);
  return m?.[1]?.trim();
}
 
function parseList(fm: string, key: string): string[] {
  // 支持两种格式:
  //   key:
  //     - item1
  //     - item2
  // 或
  //   key: [item1, item2]
  const blockMatch = fm.match(new RegExp(`^${key}:\\s*\\n((?:\\s+- .+\\n?)+)`, "m"));
  if (blockMatch) {
    return blockMatch[1]
      .split("\n")
      .map((line) => line.replace(/^\s*-\s*/, "").trim())
      .filter(Boolean);
  }
  const inlineMatch = fm.match(new RegExp(`^${key}:\\s*\\[(.+?)\\]`, "m"));
  if (inlineMatch) {
    return inlineMatch[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, ""));
  }
  return [];
}
 
export async function writeSkill(name: string, skillMarkdown: string): Promise<string> {
  const dir = path.join(SKILLS_DIR, name);
  await mkdir(dir, { recursive: true });
  const filePath = path.join(dir, "SKILL.md");
  await writeFile(filePath, skillMarkdown, "utf-8");
  return filePath;
}

// src/tools.ts (新增,不替换之前的)
import { writeSkill } from "./skills";
import { callLLM } from "./llm";
 
const REVIEWER_MODEL = "claude-3-5-sonnet-20241022";
 
const REVIEWER_SYSTEM = `你是一个 Agent skill 审查员。你的工作是评估一份新 skill 的 SKILL.md 草稿是否值得被写入系统。
 
你要检查:
1. 是否有清晰的 name 和 description
2. triggerKeywords 是否合理(不能太宽泛导致误触发,也不能太窄导致召回不到)
3. 正文步骤是否可执行(不能是空话)
4. 是否考虑了至少一种失败情况
5. 参数是否参数化(不能把一次性的具体值写死)
 
输出格式(严格遵守):
verdict: pass | fail
reason: <一句话说明原因>
 
如果 verdict 是 fail,reason 要具体指出问题所在,让 skill 的生成者可以改进。`;
 
export const proposeSkillTool: ToolDefinition = {
  name: "propose_skill",
  description:
    "当你完成一个任务并认为这个流程值得被沉淀为 skill 时调用。传入完整的 SKILL.md 内容。系统会审查并决定是否接受。",
  input_schema: {
    type: "object",
    properties: {
      name: { type: "string", description: "skill 的目录名,kebab-case" },
      skill_markdown: {
        type: "string",
        description: "完整的 SKILL.md 文件内容,包含 YAML frontmatter",
      },
    },
    required: ["name", "skill_markdown"],
  },
  async execute(input) {
    const name = input.name as string;
    const md = input.skill_markdown as string;
 
    // 基础格式检查
    if (!md.startsWith("---\n")) {
      return "Rejected: SKILL.md must start with YAML frontmatter";
    }
    if (!/^[a-z0-9-]+$/.test(name)) {
      return "Rejected: name must be kebab-case (lowercase letters, digits, hyphens)";
    }
 
    // 审查:调一次独立的 LLM
    const reviewResult = await callLLM({
      model: REVIEWER_MODEL,
      system: REVIEWER_SYSTEM,
      messages: [
        {
          role: "user",
          content: `请审查以下 skill 草稿:\n\n\`\`\`\n${md}\n\`\`\``,
          timestamp: Date.now(),
        },
      ],
      maxTokens: 500,
    });
 
    const reviewText = reviewResult.content
      .filter((b): b is Extract<ContentBlock, { type: "text" }> => b.type === "text")
      .map((b) => b.text)
      .join("\n");
 
    const verdictMatch = reviewText.match(/verdict:\s*(pass|fail)/i);
    const reasonMatch = reviewText.match(/reason:\s*(.+)/i);
    const verdict = verdictMatch?.[1]?.toLowerCase();
    const reason = reasonMatch?.[1]?.trim() ?? "未提供理由";
 
    if (verdict !== "pass") {
      return `Rejected by reviewer: ${reason}`;
    }
 
    // 写入文件
    const filePath = await writeSkill(name, md);
    return `Skill '${name}' accepted and written to ${filePath}. It will be available in the next conversation.`;
  },
};
 
// 导出时加入 tools 数组
export const tools: ToolDefinition[] = [
  // ... 之前的三个 tool ...
  proposeSkillTool,
];

// src/context.ts (修改行为准则部分)
 
return `你是 mini-hermes,一个会成长的个人 AI 助手。
 
## 你的记忆(持久化笔记)
 
${memory}
 
## 你当前可用的技能
 
${skillsSection}
 
## 行为准则
 
- 优先使用已有技能完成任务,而不是从零推理
- **完成任务后,如果这个任务看起来会被再次做(有明确的重复模式),主动调用 propose_skill 工具把流程沉淀为新 skill**
- 所有文件操作都在 ./data/workspace 下,不要尝试访问其他路径
- 写文件前先检查是否需要读已有内容
- 遇到错误不要慌,分析错误信息后再尝试
 
## 什么时候该主动 propose_skill
 
- 用户明确说了"以后 X 你就这样做" → 立即 propose
- 你完成了一个有 3+ 步骤的任务,且这些步骤和参数都是可泛化的 → 考虑 propose
- 用户第二次让你做几乎相同的事 → 强烈建议 propose
- 一次性的琐碎任务(比如"帮我看看这个文件") → 不要 propose
 
## propose_skill 的写法
 
写 SKILL.md 时注意:
- frontmatter 要有 name、description、triggerKeywords(列表)
- 正文要有"步骤"段落,每一步可执行
- 不要把具体参数写死(比如具体的文件名),用占位符
- 至少考虑一种失败情况
 
## 输出风格
 
- 直接、简洁、有判断
- 不要客套话
- 不要解释你"将要"做什么,直接做(除非是危险操作需要用户确认)
`;

bun run src/index.ts

> 帮我创建一个今日笔记:在 notes/2026-04-10.md 里写一个 H1 标题"2026-04-10 日记",然后一个"## 今天的事"的空段落。

> 对,下次我说"创建今日笔记"就按这个流程做,沉淀成 skill

cat data/skills/create-daily-note/SKILL.md

> 创建今日笔记

// src/feishu-gateway.ts
import crypto from "node:crypto";
import { Agent } from "./agent";
import { initMemory } from "./memory";
 
const APP_ID = process.env.FEISHU_APP_ID!;
const APP_SECRET = process.env.FEISHU_APP_SECRET!;
const VERIFICATION_TOKEN = process.env.FEISHU_VERIFICATION_TOKEN!;
const ENCRYPT_KEY = process.env.FEISHU_ENCRYPT_KEY; // 可选
const ALLOWED_USER_IDS = (process.env.FEISHU_ALLOWED_USERS ?? "").split(",").filter(Boolean);
const PORT = Number(process.env.PORT ?? 8080);
 
// 会话管理:同一个 user_id 共享一个 Agent 实例
const agents = new Map<string, Agent>();
 
async function getOrCreateAgent(userId: string): Promise<Agent> {
  if (!agents.has(userId)) {
    agents.set(userId, new Agent());
  }
  return agents.get(userId)!;
}
 
// 飞书 tenant token 获取
let cachedToken: { token: string; expiresAt: number } | null = null;
 
async function getTenantToken(): Promise<string> {
  if (cachedToken && cachedToken.expiresAt > Date.now()) {
    return cachedToken.token;
  }
  const res = await fetch(
    "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ app_id: APP_ID, app_secret: APP_SECRET }),
    }
  );
  const data = (await res.json()) as any;
  cachedToken = {
    token: data.tenant_access_token,
    expiresAt: Date.now() + (data.expire - 300) * 1000,
  };
  return cachedToken.token;
}
 
async function sendReply(chatId: string, text: string) {
  const token = await getTenantToken();
  await fetch("https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      receive_id: chatId,
      msg_type: "text",
      content: JSON.stringify({ text }),
    }),
  });
}
 
async function handleEvent(body: any) {
  // URL 验证(飞书在配置时会先发一次)
  if (body.type === "url_verification") {
    return { challenge: body.challenge };
  }
 
  const event = body.event;
  if (!event || body.header?.event_type !== "im.message.receive_v1") {
    return { code: 0 };
  }
 
  const sender = event.sender?.sender_id?.open_id;
  if (!sender) return { code: 0 };
  if (ALLOWED_USER_IDS.length > 0 && !ALLOWED_USER_IDS.includes(sender)) {
    console.log(`[gateway] ignoring message from non-allowed user: ${sender}`);
    return { code: 0 };
  }
 
  const messageType = event.message?.message_type;
  if (messageType !== "text") return { code: 0 };
 
  const contentJson = JSON.parse(event.message.content);
  const text = (contentJson.text ?? "").trim();
  if (!text) return { code: 0 };
 
  const chatId = event.message.chat_id;
  console.log(`[gateway] received from ${sender}: ${text}`);
 
  // 异步处理,立即返回 200 避免 webhook 超时
  (async () => {
    try {
      const agent = await getOrCreateAgent(sender);
      const result = await agent.run(text);
      await sendReply(chatId, result.response);
      console.log(`[gateway] replied (steps=${result.steps}, tokens=${result.inputTokensTotal}+${result.outputTokensTotal})`);
    } catch (err: any) {
      await sendReply(chatId, `出错了: ${err?.message ?? err}`);
    }
  })();
 
  return { code: 0 };
}
 
async function main() {
  await initMemory();
 
  Bun.serve({
    port: PORT,
    async fetch(req) {
      const url = new URL(req.url);
      if (url.pathname !== "/feishu/webhook") {
        return new Response("Not found", { status: 404 });
      }
      if (req.method !== "POST") {
        return new Response("Method not allowed", { status: 405 });
      }
 
      const body = await req.json();
      // 简化:省略了签名验证。生产代码必须加,见第 11 章
      const result = await handleEvent(body);
      return Response.json(result);
    },
  });
 
  console.log(`mini-hermes feishu gateway listening on :${PORT}`);
}
 
main();

"scripts": {
  "start": "bun run src/index.ts",
  "gateway": "bun run src/feishu-gateway.ts",
  "eval": "bun run src/eval-runner.ts"
}

export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=xxx
export FEISHU_VERIFICATION_TOKEN=xxx
export FEISHU_ALLOWED_USERS=ou_your_open_id
bun run gateway