1. 先问一个你可能没细想的问题

你调 LLM 的时候。传进去的是个 messages 数组，对吧？

await llm.chat

那个 messages 数组又是谁拼的？不过，

使用者痛点：L​LM 调用代码往往只关注“能跑”。却忽视程序提示词与历史消息的结构化组织，导致在真实项目中出现视野缺失或上下文溢出。

大多数人写 demo 的时候，system 是一句写死的 "You are a helpful assistant"messages 就是把历史 push 进去完事。能跑，但你把它放进一个真正干活、连续聊几百轮的 Agent 里两个问题立刻冒出来：

1. 拼的问题：这个 Agent 的人格、它能用哪些工具、它记得使用者什么事、当前在哪个项目——这些信息从哪来按什么顺序塞进去？拼错了顺序、漏了一块，模型的「视野」就是残缺的。其实，
2. 爆的问题：聊到第 轮。历史 messages 累计的 token 早就超过窗口了。下一次调 LLM，provider 直接给你甩一个 context_length_exceeded`——任务当场崩。

User Pain Point：If prompt assembly is wrong or incomplete,model behaves unpredictably;if token limits are exceeded,entire conversation crashes.

The catbuddy 「眼睛」正是为这两件事而生。不过，说到它由两半组成，一半负责装配把视野拼出来；另一半负责

2. 至于装配侧，ContextBuilder 的五层流水线

User Pain Point：The biggest source of bugs is an inconsistent or outdated system prompt;developers spend hours debugging *** model “doesn’t know” something that should be obvious.

先看「拼」。打开 catbuddy 的日志，你会看到发给 LLM 的 system 大概长这样：

You are catbuddy 🐱,a smart and caring cat-spirit AI assistant.
至于OS。darwin / Node.js v20.
Work root: /Users/.../my-project
---## AGENTS.md ...这个项目里 Agent 该怎么表现...
## SOUL.md ...Agent 的性格设定...
## USER.md ...使用者特点：名字、偏好、时区...
## TOOLS.md ...自定义工具使用说明...
---## Long-Term Memory ...关于你的长期记忆...
## Project Memory ...关于这个项目的长期记忆...
---## Always-On Skills ...memory / my 技能的完整正文...
## Available Skills - drawio: 生成架构图
- github: 搜索仓库 ...

# 为什么是这个顺序？

因为它遵循「最关键 → 可忽略」的降级原则：先立住「我是谁」。再加「怎么干活」，再补「记得什么」，最终挂上「能用什么」。万一哪天 token 预算真的紧张，从后往前砍也不伤主要。

① SOUL：人格层

第一层是 Agent 的人格声明——You are catbuddy 🐱.... 它不是写死的字符串，而是一个*Handlebars* 模板**。Handlebars 是 JS 环境里轻量模板引擎，{{变量}} 会被替换成实际值。同一个模板，在 Telegram bot 渲染成「简洁回复」。 在桌面端渲染成「完整工作区上下文」——一个模板，多副面孔。

User Pain Point：If you hard‑code system prompt you lose flexibility;any change requires redeployment.

人格工程本身是个大话题，但那是另一篇的事。这里你只需要记住：*人格是五层里的第一层*，先立人设。

② 引导文件：四个使用者能改的 .md

代码就是老老实实遍历这四个文件名。读到内容就拼一段 `## ${name} ${content}``：

注意 User.md` 有个特殊待遇：如果开了「全局画像」，它从 `~/.catbuddy/workspace` 读——这样你在所有项目里*共享同一份使用者特点*,不用在每个项目里都写一遍「我叫张三，喜欢 TypeScript」。"

③ 分层记忆：「About You」+「About This Project」

第三层注入长期记忆。而且*分两层*: 

• *Long‑Term Memory * — 从全局 `MEMORY.md` 读，是跨项目的使用者级记忆。
• *Project Memory* — 从当前项目的 `MEMORY.md` 读，是项目级记忆。

  User Pain Point:: Without proper gating。empty placeholder memories waste precious tokens.

  这里有个很省 token 的小聪明—— `isDefaultMemory` 检查：如果 `MEMORY.md` 还是模板默认内容，就*不注入*,免得白白浪费几十个 token 塞一段占位符。

  ④ 技能：全文 vs 目录摘要

  • *始终在线技能*（`memory`。`my`) — 完整 `SKILL.md` 正文直接塞进程序提示词，因为太主要，每轮都得在场。
  • *按需技能*—只放**一行摘要**:`- drawio: 生成架构图`。按理说，

  User Pain Point:: Embedding full skill definitions inflates prompts dramatically;developers see latency spikes without understanding ***.

  ⑤ 运行时上下文：工具清单按需注入

  最终一层是运行时信息——MCP 工具清单按需注入到这一轮该有的位置。说起来，MCP是接外部工具的标准协议，这块第  篇详细讲过这里不展开。

  装配侧最值得抄的两个工程细节

  • *指纹缓存* —— 用 mtime 当 *内容变没变* 的探针。
  • *运行时信息为什么不放程序提示词* —— 把易变信息搬到 User 消息中避免缓存失效。

    再看细节一。指纹缓存 —— 用 mtime 当 「内容变没变」 的探针

    buildSystemPrompt: string { const key = `${channel}:${this._fingerprint}` const cached = this.cache.get if return cached // 命中 → 零拼接 const prompt = this._assembleSystemPrompt this.cache.set return prompt }

    关键是 `_fingerprint` 怎么算——它把所有 *可能影响程序提示词内容* 的文件 **mtimeMs** 串成一个字符串：四个引导文件、全局记忆、项目记忆、技能目录指纹，再加上工作区方法，用 `\` 拼起来。不过，

    • *User Pain Point*: 每次请求重新读取全部文件导致 I/O 瓶颈与延迟；指纹缓存一次读取后即可复用，明显提高响应速度。

    从细节二来看，运行时信息为什么不放程序提示词

    你可能注意到了：**当前时间**,**channel** 等运行时信息，catbuddy **没有** 放进程序提示词，而是拼在 **第一条 user 消息** 的末尾：

    const textWithCtx = runtimeCtx ${opts.currentMessage} : opts.currentMessage messages.push

    User Pain Point:: If volatile data sits in cached system prompts。every tiny change invalidates cache causing unnecessary recomputation and possible timeouts.

…

But due to length constraints we stop here.