reference切分

reference 怎么切分

一句话判据:拆 reference 的收益 = 省下「这次任务用不到」的那部分 context。所以看加载分布——如果 90% 的任务都会把所有内容加载进来,拆了没收益,反而多一层跳转;只有长尾分布(多数任务只碰一小块)才值得拆。

📎 实例:飞书 lark-base 的 25 份 reference;本页是 设计指南/Skill设计 的子页。

---

判据:看加载分布,不看「内容多」

reference 的唯一目的是渐进披露:正文常驻,细节按需载入。所以拆不拆,只问一个问题:

这部分内容,是「几乎每次任务都要读」,还是「只有某类任务才读」?

加载分布	该怎么办
均匀(90% 任务都要读全部)	别拆。留在正文,或合成一份 reference。拆了每次还是全加载,白白多一层跳转、还要维护多文件
长尾(多数任务只碰 10%,少数任务碰另外的)	拆。按「会一起被加载」的块聚类,各成一份
单块巨大(一个主题就几十 KB)	拆出去。无论分布,巨块都不能进正文,否则一触发就吃满 context

核心不是「文件大就拆」,是「用不到的部分能不能不加载」。拆分换来的是 context 命中率,代价是跳转与维护成本——分布不长尾时,代价大于收益。

飞书 lark-base:25 份 reference 怎么切的

lark-base 一个 Skill,25 份 reference,从 1.4KB 到 55KB。切分轴是**「模型最容易猜错的高熵复杂结构」**,一个点一份:

reference	大小	什么任务才加载
formula-field-guide.md	55KB	只有建公式字段时
lark-base-workflow-schema.md	39KB	只有配 workflow steps 时
role-config.md	21KB	只有改角色权限 JSON 时
lark-base-data-query.md	20KB	只有做聚合 DSL 查询时
lark-base-cell-value.md	5KB	只有写记录、构造单元格值时

而 list / get / enable / disable 这类简单命令一份 reference 都没有——因为它们不复杂、不易错,正文一行带过即可。

25 份不是「base 知识很多所以拆 25 块」,是「base 有 25 个互不重叠、各自只被一类任务触发的高熵点」。一次「建公式字段」的任务,只加载 formula-field-guide.md 那 55KB,其余 24 份纹丝不动——这才是拆分的全部意义。

怎么切:三条具体法则

① 按「会一起被加载」聚类,一份一个 SSOT

每份 reference 是某个主题的唯一真源(single source of truth)。飞书正文里直接标注「steps JSON SSOT」「权限 JSON SSOT」——同一事实只在一处定义,正文和别的 reference 只引用不复制。聚类原则:总是被一起读的内容放一份;从不一起读的拆开。

② 入口(guide)与真源(schema)二次分层

同一主题常拆成两份,做 reference 内部的再一次渐进披露:

角色	后缀	何时读	飞书例
入口 / fewshot	*-guide.md	先读,学会怎么用	lark-base-workflow-guide.md
完整真源	*-schema.md / *.md	深入才读,字段全集	lark-base-workflow-schema.md

大多数任务读 guide 就够了;只有要构造完整复杂 JSON 时才下钻到 schema。data-query、role 都用了这个 guide + 真源 双层。

③ 命名带语义后缀,一眼知道是什么

*-guide(教程)· *-schema / *-json(结构真源)· *-sop(选路决策)· *-data-config(配置协议)。文件名即用途,模型在路由表里一看后缀就知道该不该读。

完整案例:+data-query 的「guide + 真源」双层

把上面三条法则连起来看一个真实的拆分。lark-base 的聚合查询能力,reference 拆成两份:

SKILL.md 正文只有一行路由(点名何时读哪份):

| 一次性聚合统计 | +data-query | 必读 …-data-analysis-sop.md 和入口
                  …-data-query-guide.md;完整 DSL 再读 …-data-query.md |

入口 lark-base-data-query-guide.md(2.8KB) —— 开头就声明自己的角色,并把真源指出去:

This guide is the entry point for `+data-query`. Use it for common
aggregation fewshots. For the complete DSL fields, operators, limits,
use lark-base-data-query.md as the DSL SSOT.

## 常用少样本
按分类字段计数:
lark-cli base +data-query --base-token <t> \
  --dsl '{"dimensions":[{"field_name":"Status"}],
          "measures":[{"field_name":"Status","aggregation":"count"}]}'

真源 lark-base-data-query.md(20KB) —— 完整 DSL 字段、算子、分页上限、响应结构、错误恢复。

加载分布是这样的:用户问「按状态统计有几条」→ 模型读 2.8KB 的 guide,照 fewshot 套一下 DSL 就够了,那 20KB 的 SSOT 纹丝不动。只有要写复杂多层 filter/嵌套聚合时,才下钻读 20KB。

如果不拆——把 20KB DSL 全塞进正文或一份文件——那么每一次 +data-query(哪怕只是数个数)都要吞下 20KB。拆成 guide+SSOT,就把「90% 的简单聚合」和「10% 的复杂 DSL」分到了两层,只为后者付 context。这就是 §判据 的「长尾才拆」落地。

别犯的两个错

错	为什么错
均匀加载还硬拆	每次任务都要读全部,拆完只是把一份变多份、多了跳转,context 没省
拆完正文不点名「何时读」	reference 拆得再好,正文不告诉模型「做 X 读 Y」,模型要么全读(没省)要么不读(做错)。触发机制见 设计指南/Skill设计/SKILL里如何调用CLI

自检清单

• 这份 reference 是「只有某类任务才读」(长尾)→ 该拆;还是「几乎每次都读」(均匀)→ 别拆?
• 拆出来的每份是否总被一起加载(内部高内聚)、与别份很少同时读(彼此低耦合)?
• 每份是不是某主题的唯一真源,别处只引用不复制?
• 高熵巨块(公式/DSL/权限 JSON)是否都已外置,没留在正文?
• 正文路由有没有点名「何时读哪份」?

---

配套:Skill 怎么切 → 设计指南/Skill设计/Skill切分;正文怎么调 CLI、怎么点名读 reference → 设计指南/Skill设计/SKILL里如何调用CLI;飞书全景 → 设计指南/Skill设计/飞书Skill设计实践。

← 返回 设计指南/Skill设计