Progressive 结构

适用版本：StablEdge 0.4.4 及以上

普通 Skill 被加载时，整份正文一次性进入上下文。正文长、主题多时，这会占用大量上下文。Progressive 结构把正文切成带稳定 ID 的章节：加载时只返回一份“封面”，Agent 再按需读取具体章节。

什么时候用

• 正文有多个相对独立的主题，一次任务通常只用到其中一两个；
• 有几条规则无论做什么都必须遵守，需要始终放在封面上；
• 希望 Agent 引用章节时用稳定 ID，而不是依赖标题文字。

正文很短（几十行以内）、每次都要全文阅读的 Skill，保持普通结构即可。

开启方式

在 frontmatter 里加入 progressive 映射。下面是内置 xlsx Skill 的写法（摘自 builtin/xlsx/SKILL.md，description 省略）：

---
name: xlsx
description: "……"
progressive:
  always:
    - mandatory-rules
    - core-tools
---

只要 frontmatter 里出现 progressive 键，这个 Skill 就按 Progressive 规则解析。不需要始终展示的章节时，写 progressive: {} 即可。

章节 ID 语法

在 Progressive Skill 的正文里，每个二级、三级标题都必须在末尾带上 {#章节-id}：

## 强制规则 {#mandatory-rules}

……

## 核心工具 {#core-tools}

### 读取表格 {#read-sheet}

……

一个章节从它的标题开始，到下一个同级或更高级标题之前结束。所以二级章节包含它下面的所有三级章节；三级章节也可以单独读取。

progressive.always

progressive.always 是一个章节 ID 列表。列出的章节会直接放在封面上，Agent 加载 Skill 时就能看到，适合放必须遵守的硬性规则和最常用的入口。

• 必须是由非空字符串组成的列表，不能有重复项；
• 每个 ID 都必须在正文里真实存在；
• always 章节同时也会出现在章节索引里。

内置 plugin-creator 把三条规则类章节放在了封面上（摘自 builtin/plugin-creator/SKILL.md）：

progressive:
  always:
    - current-rules
    - engineering-constraints
    - forbidden-boundaries

always 的章节越多，封面越长，按需读取省下的上下文就越少。通常放一到三个即可。

按章节读取的原理

1. 加载封面：Agent 调用 skill 工具的 load 动作，得到封面。封面依次包含：一行如何读取章节的提示、附带文件清单（如有）、always 章节的完整内容，以及自动生成的“可按需读取的章节”索引（每项是 章节 ID — 标题，三级章节缩进显示）。
2. 读取章节：Agent 用 read_section 动作并传入 section_id，拿到对应章节的内容；可以用 offset 和 limit 只读其中一段行。
3. 标题兼容：没传 ID 时，也可以按标题文字查找（不区分大小写），但标题重复时会要求改用 ID。所以 ID 是唯一可靠的引用方式。

封面和章节按 Skill 目录内容缓存，目录里任何文件变化都会让缓存失效。

校验与降级

以下情况都算 Progressive 校验错误：

• progressive 不是映射，或 progressive.always 不是 ID 列表、有重复项；
• 二级或三级标题缺少 ID、ID 重复；
• always 引用了不存在的 ID；
• 正文里一个带 ID 的章节都没有；
• resources 声明有问题，见 声明资源。

出现这些错误时：

• 安装时：预览阶段直接拒绝，提示具体错误，Skill 不会被装上；
• 已在目录里的 Skill（例如手动编辑后）：Skill 仍能加载，但会退回为一次性返回整份正文，read_section 不可用。