1. 加新 Tool —— LLM 可调用的能力#

启动后 LLM 自动知道有这个 tool 可用。

Tool 的本质： Tool 是 LLM 可以主动调用的能力。LLM 读到消息后自己判断要不要调、调哪个、传什么参数。代码不做这个判断——没有 if/elif 消息分类，没有正则匹配。这也是为什么不需要 Parser——LLM 就是 parser。

2. 加新群画像 —— per-group 知识注入#

capabilities/memory/groups/新客户群.md → 新画像

系统处理这个群的消息时，自动加载画像注入 prompt。

画像告诉 LLM 这个群的特殊规律——谁说了算、门店叫什么、默认规格是什么。不同群的画像完全独立，互不影响。

3. 加新 Extension —— 数据管道中的变换环节#

capabilities/extensions/sanitizer.py → 新文件

Extension 是数据管道中的变换环节。它改数据本身——输入一种格式，输出另一种格式。数据必须经过它，它是处理链上的一环。

现在实现了 session_grouper.py（按天分段），规划的 Extension：

Extension 的设计原则： 纯函数，零 core 依赖。输入是什么、输出是什么，可以独立测试。不 import core/ 的任何东西。

4. 加新 Gateway —— 换数据入口#

Gateway 只做一件事：把原始数据转成 Message 对象。它不碰 core/，不碰 LLM。在 main.py 里换成新 gateway，整个系统就走新数据源了。

这意味着：从 JSON 文件 → 微信实时消息 → 钉钉 → 飞书，只换 Gateway，其余不动。

5. 换业务 —— 换 capabilities/ 目录#

如果不用来处理批发订单了，改成处理餐饮外卖、物流调度、客服工单：

• domain/models.py —— 换成新的领域模型
• tools/ —— 换成新的 tool
• context/business.md —— 换成新的行业知识
• memory/groups/ —— 换成新的客户画像

core/ 不动。8 个文件原封不动。

1. Skill —— 领域知识 + 操作流程的封装#

Skill 是 Pi 的核心扩展机制。一个 Skill 是一个完整的操作指南——什么时候触发、怎么做、注意什么。它不是代码，是一份结构化的 markdown。

1
skills/
2
├── order-review/SKILL.md    # "复核订单"技能
3
└── batch-import/SKILL.md    # "批量导入"技能

Skill 文件里包含：

• 触发条件 —— 用户说什么话时加载这个 skill
• 操作步骤 —— 第一步做什么、第二步做什么
• 知识参考 —— 相关的 business.md 片段、tool 用法
• 检查清单 —— 做完后验证什么

比如”复核订单”skill 会告诉 LLM：先查今天所有待审查订单 → 逐条跟原始消息比对 → 确认或修正。这些流程如果写在 role.md 里会很长，按 skill 按需加载才合理。

Skill 和 Tool 的区别： Tool 是一个原子操作（记录一笔订单），Skill 是一个多步骤流程（复核今天所有订单）。Tool 是代码，Skill 是 prompt。

2. Context —— 动态 prompt 片段#

Context 是在运行时动态注入的 prompt 内容。比如群画像是 per-group 的 context，每天的订单汇总可以作为当天的 context 注入。

1
context/
2
├── business.md       # 静态，行业知识（固定不变）
3
├── role.md           # 静态，角色设定（固定不变）
4
├── [运行时注入]
5
│   ├── 群画像        # 动态：per-group 知识
6
│   └── 今日汇总      # 动态：per-session 数据

这种设计来自 Pi 的 promptSnippet 机制——harness 控制 prompt 的拼接结构（什么放前面、什么放后面），tools/skills/memory 填充具体内容。每个模块只知道自己该贡献什么，不知道最终 prompt 长什么样。

3. EventBus —— 模块间松耦合通信#

模块之间不直接调用，而是通过事件总线间接通信。Tool A 记录了一笔订单后，发一个 order_recorded 事件。审查模块、审计模块、通知模块各自订阅这个事件，做自己的事。Tool A 不知道谁在监听，监听者也不知道谁发的。

Extension 和 EventBus 的区别：

• Extension 改数据（消息分段、脱敏），是数据管道的一部分
• EventBus 不改数据，是事后通知（“这件事发生了，谁关心谁处理”）

review_guard 表面看像 Extension（它要改订单状态），但本质是”收到 order_recorded 事件后执行一段逻辑”，属于 EventBus 订阅者，不是管道环节。

注意力 U 型分布#

斯坦福和 Meta 的论文 “Lost in the Middle” 发现，LLM 对长文本的注意力呈 U 型分布——开头和结尾注意力最高，中间最低。关键信息放中间时，准确率下降 20% 以上。

我们把不变的行业知识放最前面（先建立”这个行业的常识”），变动的消息放最后（LLM 最后读到、马上处理），中间放群画像（它才是理解上下文的关键知识）。

KV Cache 复用#

这是个工程优化。LLM 处理每轮对话时，要把所有历史 token 重新算一遍。但前面没变的部分，计算结果可以缓存复用。

排列规则：越不常变的放越前面。

• business.md 几乎永远不变，缓存利用率最高
• 消息每次都变，放最后

如果倒过来，消息放中间、群画像放最后，每次新消息进来，群画像的缓存就失效了，白白重算。

实际效果： 固定前缀（business.md + role.md + 群画像）大约 2500 token，消息平均 500-2000 token。前缀不变时，每轮省掉约一半的计算量。

简单记：不变的放前面，常变的放后面，最重要的放开头和结尾。

⚠️ 目前 agent loop 是单轮处理（一段消息一个 session，跑完就结束），所以 KV Cache 复用还没真正生效。等后续改成多轮交互式 gateway（LLM 和人来回对话），这个排列顺序的收益才会体现。