Skill 正文该何时加载、压缩后如何恢复？Claude Code / Codex / OpenCode / Hermes 调研与 OpenPI 建议

[tt-a1i]

当前决定（2026-08-31，原生 Pi 方案）：复用 Pi 的 Skill 目录、模型按需读取、/skill:name 显式展开以及正常 Session 历史与压缩；不增加独立正文缓存、provider-only 上下文投影、压缩后补回正文或专门的重读入口保活机制。接受原生不保证压缩后全文保留的边界。详见决定、依据及对 #316 / #322 的影响。此前调研与候选建议保留为历史；方案已确定，但本次未修改 Issue 验收标准、PR 代码或合并状态。

---

更新说明（2026-08-31，第二轮调研）：已补查 Claude Code 的有界正文恢复，以及 Codex、OpenCode、Hermes 的长正文截断和续读边界。下文保留第一轮记录；其中“读取/注入正文”不应理解为任意长度都完整送达。当前建议调整为 A/B 并列比较，首次加载与压缩恢复分别验证，不再仅因实现更薄就优先 A。详见新发现、源码与建议修正。这不是已通过的 Decision，未修改 #316 验收标准或执行合并。

---

先说建议

建议先验证一个更薄的方案：$skill 负责准确指定 Pi 已发现的 Skill，模型通过 Pi 原生 read 读取正文，读取结果进入普通会话历史，压缩继续由 Pi 管理。

但这还不是已经确定的产品方案：

• 三家都有按需读取路径，也都有显式选择后直接加载正文的路径。不能用“别人都是 lazy loading”来否定自动注入。
• “正文已经发过一次”不等于“压缩后仍在上下文里”；反过来，可能丢失正文，也不等于必须把全文一直保留下来。
• 应比较薄引用方案与“显式选择时加入原生隐藏消息”的方案，再决定是否需要额外的压缩恢复机制。目前没有效果实验证明其中一个全面更好。

这里记录源码调研、对 OpenPI 的推论和建议验证项，供讨论，不是已通过的 Decision，也不是合并结论。

1. 我们到底在解决什么问题

背景是 #282、#316、#317，以及 PR #321、PR #322。用户需要在输入中方便、准确地指定 Skill，同时保留原始消息，不把聊天界面塞满 Skill 正文。

这里其实有三个独立问题：

1. 发现与选择：用户和模型怎样知道有哪些 Skill，怎样选中正确的那个？
2. 读取：选中之后，由程序加载正文，还是由模型调用工具读取？
3. 生命周期：正文被压缩或裁剪后，是依靠摘要、重新读取，还是继续保留全文？

Tab 补全解决第一个问题，不自动决定后两个问题。通过工具读取后，正文依然会进入模型上下文；按需读取改变的是时机、控制方式和生命周期，并不会消除真正使用正文所需的 token。

验收标准边界：#316 当前明确要求已知引用在提交后加入隐藏的、去除 frontmatter 的 Skill 正文，并要求每个不同 Skill 按引用顺序加载一次。只传引用再让模型读，不是对此验收标准的等价实现。如果采用薄方案，应先讨论并调整 #316，再修改实现与测试。现有贡献是在落实原要求，不能把我们后续提出的产品调整倒过来当成作者没有完成要求。

2. 调研范围

核查日期：2026-08-31。以下结论绑定源码版本，不代表所有已发布版本，也没有用文档宣传或模型自述代替实现证据。

项目	核查版本
OpenCode	dev / 9f69463f
Hermes Agent	main / 1f99a4b2
Codex	开源 main / a9519cbc
Pi	0.84.1 / 53fa77cc

没有运行三家的上游测试套件或模型效果对比；Codex 开源客户端也不能证明闭源服务端压缩器的内部行为。

3. 三家具体怎么做

项目	模型自行选择时	用户明确选择时	压缩/裁剪的关键区别
OpenCode V1	目录信息先进入提示，模型调用 skill 获取正文	Skill 斜杠命令直接展开正文	skill 工具结果免普通旧输出裁剪，但不免完整压缩
Hermes	名称/描述目录，模型调用 skill_view	斜杠命令加载正文；--skills 可预加载	部分被移除正文会留下重读标记；预加载正文走另一条持续附加路径
Codex	目录和位置，模型按需读文件或 skills.read	可解析的显式引用由程序读取正文，加入会话历史	核查的客户端路径未见已选正文全文强制恢复；不能外推服务端内部行为

OpenCode：普通裁剪保护，不等于全文跨压缩保留

V1 的目录包含名称、描述、位置；skill({name}) 做权限检查后返回正文、基准目录和部分辅助文件路径，结果进入会话工具记录。辅助文件正文没有一起递归加载。显式 Skill 命令则用 Skill 内容作为模板，直接展开到提交内容中。目录、读取工具、显式命令。

普通 pruning 保护 skill 结果；完整 compaction 则会把选中的旧历史转换成摘要输入，其中每条工具输出有 2,000 字符上限，没有 Skill 例外。后续上下文使用摘要与保留的近期历史，不能据此宣称 Skill 全文永久保留。裁剪保护、摘要序列化。

同一 HEAD 还存在独立 V2 core，目录和压缩路径不同，不能把 V1 的保护规则直接套过去。V2 目录、V2 压缩。

Hermes：恢复读取入口，而不总是恢复全文

普通路径是 skill_view 按需读取，结果进入工具历史；斜杠命令直接构造含正文的用户消息。--skills 预加载不同：正文进入 ephemeral_system_prompt，在 API 请求时附加到有效系统上下文中。这是持续注入，不能省略这个例外。工具、斜杠命令、预加载、请求投影。

压缩逻辑会保护部分近期/仍相关的 Skill 读取结果，但压力降级仍可能清掉正文。对于部分大正文，留下 SKILL_PRUNED 和 skill_view 重读指引，并在摘要漏掉这些标记时确定性补回；同时清空读取去重状态，避免重读只拿到“文件未变化”的短响应。重读标记恢复、读取状态重置。

这提供了一个有价值的参考：**允许正文离开上下文，但明确告诉模型它已经不在，并让重读真的可用。**不过不能宣称恢复无遗漏：小型降级结果可能只剩元数据、没有标记，工具结果规则也不能直接外推到斜杠展开消息。相关测试，已阅读、未执行。

Codex：按需读取与显式注入并存，正文进入原生历史

目录指引模型按需读取；显式选择则通过 load_skill_prompts 读取正文，生成包含名称、路径和正文的 <skill> 上下文片段。这些片段被写入会话 history 和 rollout，不只是发送给 provider 时临时叠加。目录指引、正文加载、插入历史、持久化。

本地压缩对历史生成摘要，保留一定的真实用户消息，并恢复初始上下文。Skill 正文片段被归类为上下文，不是需要原样保留的真实用户消息；恢复的 Skill 目录也不等于恢复已选正文。核查的客户端路径未发现强制重新注入已选全文，但这不是对远端压缩器内部的结论。本地压缩、片段分类、远端结果处理。

4. 回到 Pi 和当前 OpenPI 方案

Pi 0.84.1 已有两个原语：

• 目录提供名称、描述、路径，指引模型用原生 read 读取。
• /skill:name 直接读取并展开正文；原生 steer、followUp 也经过展开。

Pi 目录与读取指引、Pi 显式展开及追加输入。后者是比较基线，但不是保留任意行内原话与全部自定义消息路径的现成替代品。

#322 在本次核查的 e4731fc 中，把正文保存为当前运行内的不可变快照，只在 provider context 阶段叠加，而不加入普通历史。压缩成功、源消息确实被裁掉后，再关联到压缩摘要；运行结束时清理。

这个补丁保证了它定义的“本次运行及重试仍能看到同一份正文”合同。但需要承认：它修复的是当前投影设计产生的生命周期缺口；修复通过，不等于全文跨压缩保留这个产品要求已经被证明有价值。

这里也不能直接套用 #311 的工具生命周期讨论：运行时仍有权限的工具需要保持可调用，与某份 Skill 指令是否持续相关、是否必须保留全文，不是同一个不变量。

5. 建议比较的三个方案

方案	预期价值	代价与风险
A：准确引用 + Pi 原生读取	扩展更薄；普通工具历史可参与摘要；不另管正文生命周期	多一次读取调用；模型可能漏读；重读可能读到已更新文件
B：明确选择后，正文加入原生隐藏消息	初次正文可见性确定；省一次模型主动读取	立即占用上下文；仍可能被摘要；追加输入路径和隐藏显示需验证
C：当前运行内快照 + 压缩后重新关联	同一次运行/重试保持稳定正文	额外快照与关联状态；正文继续占用上下文；实际收益未测

建议先验证 A，并以 B 做对照；不要先把 C 当成必需条件。保持现有实现、只补全输入体验也可以作为对照基线，但不据此跳过当前生命周期疑问。

预期受益者有两类：用户能够准确指定 Skill、长任务中仍能得到正确指导；维护者减少与 Pi 重复维护的状态。后者是合理预期，前者必须用行为结果证明。

如果 A/B 在压缩后确实丢失关键指导，优先尝试有界的 Skill 身份/位置/重读提示，并验证重读可用，再讨论是否需要正文保留。不要因为 Hermes 有专门压缩器，就把它整套搬进 OpenPI。

这些边界应保持不变：Pi 负责发现、冲突、来源、Trust 和 Session；OpenPI 不自行扫描建立第二份 Skill 目录；Skill 正文、摘要、重读提示都不能授予工具权限。显式选定某个 Skill，也不应变成运行时替模型规定整套思考流程。

6. 需要什么证据再决定

先比较 A/B，固定 Skill、任务、Pi/OpenPI 版本和模型，至少覆盖：

• 普通输入、运行中 steering/follow-up，以及 TUI/RPC/print 等共享入口。
• 同名或未知引用、转义与标点、读取失败、取消、Session 恢复。
• 压缩成功/失败，源消息被保留/被裁掉，以及压缩后继续原任务。
• 正文含关键要求、摘要省略该要求时，模型能否找到正确 Skill、重新读取并遵守。
• 读取后文件更新/删除、权限或来源变化时，是否明确失败，而不是假称已加载。

分开记录三层证据：用户看到的原话、模型实际收到的内容、Session 持久化历史。效果比较记录漏读率、关键要求违反率、额外工具调用、延迟和有效输入 token；缓存命中与网络流量另记。

“测试里还含正文”证明的是可见性，不是正确完成任务；“调用了读取工具”也不证明读全或遵守。目前还没有这组模型效果对比，不宣称节省多少 token、提升多少成功率或零负面影响。

希望讨论先回答：

1. 显式 $skill 的合同应是“必须在第一次请求中提供正文”，还是“准确指定来源，要求模型在行动前读取”？
2. Skill 的有效期是本次运行、当前任务，还是跨轮次会话？不要让生命周期由实现偶然决定。
3. 压缩后只保留可重读入口是否足够？在什么失败证据下，才值得增加更强的恢复机制？

如果支持 A，先调整 #316 验收标准，再做最小实现和对照；如果坚持初次正文确定可见，就先验证 B 的 Pi-native 路径。本帖不宣布修改验收标准，也不宣布 #322 已合并。

相关讨论：能力发现与权限 #312、完整成本与效果证据 #313。

[liwen-aaa]

支持 A。理由不是"薄、省 token"，而是用户的显式选择本身就是可靠性来源：在 A 方案下，用户点名引用的 skill，模型漏读是可见的、可当场纠正的——这比自动注入更可靠，因为注入是否真正帮助任务是不可见的。

回应三问：

• Q1 在显式引用下是伪命题（用户能打出 $skill: 说明已知其存在，适用性判断是模型的事），合同取"指定来源 + 行动前必读"；
• Q2 有效期语义 = 当前任务，机制 = 正文进普通历史交 Pi 管压缩，只保证重读入口随摘要存活；
• Q3 重读入口是默认，仅在漏读致错、重读不可用、重读成本爆炸三类证据下再升级恢复机制。

至于 skill 生态——质量参差、没有统一规范、内化时间未知，现在为基准和规范做投入是不确定回报的。所以 A 先上，长短 skill 的差异、压缩后的恢复机制都留给真实使用中的失败证据再决定，现在不设计。不要让远期的不确定性绑架当下的合同。

[tt-a1i]

2026-08-31 补充：长 Skill 的加载边界，以及 Claude Code 的有界正文恢复

这一轮补查针对一个之前没有展开够的问题：不能假设所有 Skill 都有短小入口；单份正文很长、一次使用多份 Skill 时，究竟能否读全，压缩后又保留什么？

先更新我们的判断：**不再仅凭“实现更薄”优先 A。A（准确引用＋Pi 原生读取）与 B（显式选择后加入原生隐藏正文）应并列比较；压缩恢复另设维度，纳入“有界恢复正文”和“保留重读入口”两个参考方案。**这仍是建议，不是已经决定改实现，也不代表 B 已经被证明更好。

原帖保留为第一轮调研。下面增加新证据，并限定原帖中“读取/注入正文”的含义：loader 读到了全文，不等于经过所有输出边界后模型收到了全文。

1. Claude Code：不仅有渐进加载，还有正文恢复预算

官方文档明确描述：调用后，渲染后的 SKILL.md 作为一条消息进入会话并跨轮次保留；相同内容重复调用时只加“已加载”的短提示，内容改变时才再次加入正文。

压缩后的恢复规则是：

• 每个 Skill 取最近一次调用，重新附加到摘要之后。
• 每份只保留前 5,000 tokens。
• 所有恢复的 Skill 合计最多 25,000 tokens，优先最近调用的。
• 旧 Skill 可能被整个移除，长 Skill 的尾部可能被截去；需要全文时重新调用。

这不是“只留路径”，也不是“永远保住所有全文”，而是有界的正文恢复。官方生命周期、压缩后保留内容。

官方另建议主文件少于 500 行、细节拆到 supporting files。这是作者侧建议，不是已确认的 500 行运行时拒绝规则，更不能当成所有第三方 Skill 都满足的前提。普通 Read 的超长分页也是另一条工具合同，不能假设 Skill 调用必然经过它。编写建议、Read 行为。

证据边界：这里核对的是 2026-08-31 的官方文档，没有审计 Claude Code 闭源实现或运行模型实验。此前三家对照没有包括这项机制，不能据原帖推导出“成熟 Agent 都不恢复正文”。

2. Codex：需要按 Skill 来源限定“完整注入”

仍绑定原帖源码 a9519cbc：

• 普通 host Skill 加载分支读取正文，不应用该分支的 prompt 截断器；host Agent Plugin Skill 会应用，extension-contributed Skill 也有应用路径。
• 这些受限注入路径的正文上限是 8,000 UTF-8 字节，超限截断并发出警告。不是 8,000 tokens，也不是所有 Codex Skill 的统一上限。host 分支、extension 分支、上限及截断函数、常量。
• skills.read 则有真正的分页：按本次工具响应预算返回内容和 next_cursor，在 UTF-8 边界切页；连一页都放不下时返回错误。其最大响应预算常量为 512 KiB，包含序列化开销，实际请求预算可以更小。分页合同、分页实现、响应常量。
• executor/orchestrator 的资源读取还会拒绝超过 1 MiB 的内容；分页不等于无上限。此规则也不能外推到所有普通 host Skill。资源上限、executor 执行点、orchestrator 执行点。

因此，原帖“显式引用由程序读取正文”成立，但不能扩展成“任意来源、任意长度都保证全文注入”。我们也没有证据证明截断的显式注入一定会触发自动补读。

3. OpenCode V1：专用 Skill 工具也经过通用输出截断

在 9f69463f 的 V1 路径，skill 构造完整正文结果后，因为没有自己设置 metadata.truncated，仍会经过 Tool.wrap 的通用截断。原始结果、封装边界。

• 默认 2,000 行或 50 KiB，先达到哪个就按哪个截断；可配置。
• 超限将完整输出保存到文件，给模型预览、截断提示和路径。
• 提示模型分段读取、搜索，或在工具允许时委派处理；这并不强制主模型读完每一行。
• 显式 Skill 斜杠命令直接展开正文，绕过这个工具输出边界，但没有绕过总上下文预算。上限与恢复入口、默认常量、命令展开。

所以原帖所说的“免普通 pruning”只针对后续旧输出清理，不是免首次工具输出截断，也不是免完整 compaction。同 HEAD 的 V2 是另一条实现，以上数值不直接外推。

4. Hermes：整文件读取以后，还要经过输出预算

在 1f99a4b2，skill_view 自身整文件读取，没有 offset/limit 参数；之后才进入通用工具结果预算。读取、工具参数。

• 默认单结果上限最高 100,000 字符，同一 assistant turn 的总输出上限最高 200,000 字符；较小上下文会缩减，并有配置/豁免规则。
• 超限后尽量保存完整输出，返回约 1,500 字符预览及恢复路径。保存失败时明确报告全文未能保存，不能假称仍可完整恢复。
• 后续 read_file 自身还有行数、字符和单行长度限制；有路径、有续读参数，不等于任何形态的内容都能无损读全。预算与缩放、预览与恢复、保存失败路径、单行截断。

一个待验证边界：Skill 结果序列化为 JSON 后，正文里的换行可能变成转义字符，使保存文件成为长物理行。仅按行续读可能拿不到被截掉的行尾，需要读原文件或解码提取。这是源码推论，不是已跑通的复现或模型失败结论。序列化。

斜杠命令和预加载直接调用 loader、拼接正文，不经过上述工具结果保存边界；不能据此推断任意大正文都能安全注入。原帖关于部分正文丢失后的 SKILL_PRUNED 重读提醒仍成立，但它解决的是另一个生命周期阶段。直接加载、重读标记。

5. 怎么修正 OpenPI 的比较方式

“Skill 规模”至少拆为：目录里有多少份、单份正文多长、一次选中多少份。目录预算、单次工具输出上限、总上下文预算、压缩恢复预算不能混用；上面的行数、字符、字节、tokens 也不是可直接比较的同一单位。

建议把首次加载与恢复作为两条独立轴：

阶段	需要比较的方案	必须观察的事实
首次使用	A：原生读取；B：原生隐藏正文	完整/部分/失败能否区分；末尾关键要求是否真正到达模型
重复使用	去重、重读或重新加载	文件变化怎么处理；是否重复占用；是否误判已加载
压缩以后	原生摘要基线、重读入口、有界正文恢复	缺失是否可见；恢复路径是否可用；恢复预算与淘汰规则

对长正文，A 的续读步骤可能遗漏，B 则可能在注入阶段受限或挤占总上下文。短正文也不能直接判定 A 更好：B 可以省一次工具调用。没有从这轮源码和文档中得到“短的必选 A、长的必选 B”的统一规则。

“读取动作可观察”“内容完整进入上下文”“模型实际遵守要求”也应分开记录。调用成功不代表读全，正文在场不代表遵守；这两点对 A/B 都适用。

下一步如要验证，应包含没有精简入口的真实长 Skill，并把关键要求放在开头、中间、末尾，覆盖单页以内、需要多页、接近上下文预算、多 Skill 同时使用及压缩恢复。不需要先规范整个 Skill 生态，但也不能靠“所有 Skill 都会写得足够短”排除这些情况。至少建立完整/部分/失败的行为边界，再由失败证据决定是否增加恢复机制；具体预算不能照搬别家的数字。

**更新后的建议：A/B 都保留为认真比较的候选；B 有成熟实践依据，Claude 的有界恢复也值得作为对照，但这些都不是当前 #322 必须保留全文或应当合并的证明。**所有权仍优先归 Pi，不另建目录、权限或 Session 控制面。#316 的现有验收标准没有被本补充改动；如采用 A，仍需先调整“提交后注入隐藏正文”的合同。

本补充仅发布调研与建议。未运行模型效果对比，不宣称成功率、token 收益或零负面影响，也未修改 PR 实现或执行合并。

[tt-a1i]

2026-08-31 当前决定：按 Pi 原生机制收敛，不增加 Skill 正文生命周期

结合前面的调研和对原生 Pi 的核查，我们确定这一轮的实现边界：复用 Pi 的 Skill 发现、加载与 Session 生命周期，不额外保存正文、叠加 provider-only 上下文，或在压缩后自动补回正文。

前面的跨产品调研继续保留，供以后查证；其中“A/B 并列比较、另评估恢复机制”是当时的候选建议，已被本条当前决定替代。这是范围选择，不是实验已经证明某个方案效果最好。

1. “原生”具体指什么

核查基线是 Pi 0.84.1，源码固定在 53fa77cc：

• 模型自主选择：系统提示提供 Skill 的名称、描述和路径；模型需要使用时，通过普通 read 读取正文，工具结果进入正常历史。目录与读取指引。
• 用户显式调用：/skill:name 由 Pi 读取文件、移除 frontmatter，将正文及参数展开成用户消息；正常的 steering/follow-up 也支持展开。这不是“只发路径”，也不是 OpenPI 自己维护一份隐藏正文。原生展开与追加输入、普通消息持久化。
• 压缩与恢复：采用 Pi 的摘要加近期保留消息。正文所在消息若被摘要替代，默认不专门重新附加 Skill 全文；原始 Session 记录仍在，但不等于全文仍发给模型。上下文重建。

因此，这个决定不是简单地“选 A、反对任何正文注入”：原生 Pi 已同时提供按需读取和显式正文展开。我们选择复用这两条现成路径，不新增第三套正文状态管理。

2. OpenPI 不增加什么

• 不维护独立的 Skill 正文快照、缓存或运行内“已加载正文”状态。
• 不在 provider context 阶段额外投影一份不进入正常历史的正文。
• 不在 session_compact 后重新关联正文，也不移植别家的有界正文恢复预算。
• 不新增“重读提示或路径保证跨压缩存活”的专门机制。

输入候选、描述、Tab 补全可以作为界面便利，但不应因此建立独立加载和执行通道。原生斜杠调用不是任意行内 $skill、多引用及“原话不变＋隐藏正文”的自动等价替代；不能只换个入口名称，就声称原验收标准全部满足。

3. 为什么这样取舍，以及接受什么限制

OpenPI 的定位是 Pi-native capability layer。原生已经承担了加载、消息保存与压缩；目前没有模型效果证据证明 OpenPI 必须再维护全文恢复机制。选择原生基线，可以减少重复状态和随 Pi 升级需要额外维护的生命周期逻辑。这是设计判断，不是“其他产品的恢复机制没有价值”。

我们同时接受原生边界：

• 压缩后不保证正文逐字保留，也不保证模型一定会主动重读。
• 普通 read 有输出限制，需要时继续读取；显式展开绕过这道工具输出截断，并不绕过总上下文容量。读取边界。
• “调用了读取工具”“正文进入上下文”和“模型遵守指令”仍是不同证据，不能宣称零负面影响或已验证效果更优。

暂不把跨产品 A/B 效果比较作为接入原生能力的前置项目。如果真实使用出现可复现的关键指令丢失、重读失败或明显成本问题，再单独讨论是否需要扩展 Pi 的现有机制；现在不预先增加恢复层。

4. 对现有 Issue / PR 的影响与当前状态

后续应按这个决定收敛 #316 的验收标准和 #322 的实现、测试，撤掉独立正文投影及压缩后重新挂载逻辑。输入体验贡献可以独立评估，但不以保留额外正文生命周期为前提。

这是需求和方案边界的调整，不是把原先明确要求“隐藏正文”的实现倒过来判定为作者没有完成任务。

**本次仅更新 Discussion。**发布前核对，#316 仍要求“保留原话＋隐藏正文”；#322 仍为 OPEN，head 为 e4731fcc90af172b0dbed3325220d42f13cfb81c。本次没有修改 Issue 验收标准、PR 代码、review 或合并状态；上述实现收敛尚待执行。