From f6300a4b7384938997c09ac7bb7b742cfd99fc54 Mon Sep 17 00:00:00 2001 From: zaurakworks Date: Sun, 16 Aug 2026 21:52:23 -0400 Subject: [PATCH] fix: separate skill runtime and maintenance costs --- README.md | 4 +- docs/lifecycle.md | 26 ++++---- docs/skills-overview.md | 88 +++++++++++++------------- scripts/skills-overview.ts | 99 +++++++++++++++++++++-------- tests/workflow-routing.json | 16 ++--- tests/workflow-routing.test.ts | 110 ++++++++++++++++++++++++--------- 6 files changed, 222 insertions(+), 121 deletions(-) diff --git a/README.md b/README.md index 02ded39..32ba939 100644 --- a/README.md +++ b/README.md @@ -180,8 +180,8 @@ node plugins/orchestrated-collaboration/tests/verify-three-party-review.test.ts - 当前目标、授权和边界：读取本仓公开、自足且经负责人明确激活的 Issue／PR；没有明确合同则只做当前请求的最小范围； - 当前可安装内容：读取本 README 和对应 Plugin manifest； - `issue-workflow` 的三种模式、验收场景走读和当前证据等级：[`docs/issue-workflow-walkthrough.md`](docs/issue-workflow-walkthrough.md)； -- **每个 Skill 替你做什么、什么时候用、花掉多少复杂度预算：[`docs/skills-overview.md`](docs/skills-overview.md)**（生成产物，符合性测试钉住它不会漂）； -- 「装了才算数」的部署方式、Skill 的失效条件、最少复核、退役路径与复杂度预算：[`docs/lifecycle.md`](docs/lifecycle.md)。其中「必须声明失效条件与最少复核步骤」「数量与语料总量不得净增」由本仓 CI 强制； +- **每个 Skill 替你做什么、什么时候用，以及 L1／L2／L3 与递归维护面实测：[`docs/skills-overview.md`](docs/skills-overview.md)**（生成产物，符合性测试钉住它不会漂）； +- 「装了才算数」的部署方式、Skill 的失效条件、最少复核、退役路径与复杂度管理：[`docs/lifecycle.md`](docs/lifecycle.md)。其中「必须声明失效条件与最少复核步骤」「Skill 数量门」「分层体积必须递归、可复现」由本仓 CI 强制； - [方法资产模型](docs/asset-model.md)、[符合性检查](docs/conformance.md)、旧 Issue 和 `codex-work`：只作为历史或待核验材料，不默认指导新工作。 不要从旧交付顺序、私有历史或开放状态自行恢复工作。跨仓项目调用本仓 Plugin 时，以调用方公开合同和本仓当前可用接口的交集为边界。 diff --git a/docs/lifecycle.md b/docs/lifecycle.md index 447d339..1df54ff 100644 --- a/docs/lifecycle.md +++ b/docs/lifecycle.md @@ -80,22 +80,26 @@ git -C worktree add /<分支> -b <分支> ## 三、复杂度预算 -问题不是「Skill 太多」，是**加得动、减不动**。今天已有的体积断言全是逐个 Skill 的历史棘轮（`<= 22_848`、`<= 21_823`……），彼此不一致、还有重复，而且**没有任何总量**。 +问题不是「Skill 太多」，而是过去把两种不同成本压成了一个数字： -因此设两个总量上限，写进 `tests/workflow-routing.json` 的 `complexityBudget`，由 CI 强制： +- **运行上下文成本**取决于加载层。L1 description 常驻目录；L2 `SKILL.md` 只在选中后加载；L3 `references/` 只在正文明确路由后按需加载。 +- **维护复杂度**覆盖全部可执行语料、路由和验证面；Markdown 体积按 `SKILL.md` 加递归 `references/**/*.md` 计量。 -| 项 | 上限 | 依据 | -| --- | --- | --- | -| Skill 数量 | 13 | 原基线 12 且不留余量；负责人在 [`agent-control#57`](https://github.com/zaurakworks/agent-control/issues/57) 明确批准新增一个独立 `skill-maintenance`，只把本次上限提高到 13 | -| 语料总字节 | 209,000 | 基线总量 208,420，向上取整 | +两者分开管理： -**语料总量同时覆盖 `SKILL.md` 与 `references/`。** 只卡正文会直接导致把文字挪进 references——预算必须堵住这条洗白路径。 +| 项 | 处理 | 依据 | +| --- | --- | --- | +| Skill 数量 | 上限 13 | 原基线 12；负责人在 [`agent-control#57`](https://github.com/zaurakworks/agent-control/issues/57) 窄授权新增一个 `skill-maintenance` | +| 单项 L1 description | 上限 1000 UTF-8 字节 | 2026-08-11 普通 Codex、Orca Codex、Claude Code 三端可见性实测 | +| L2 主合同 | 实测报告，不设总字节上限 | 只在选择 Skill 后加载；逐项行为审阅决定缩减或退役 | +| L3 按需引用 | 递归实测报告，不设总字节上限 | 只有真实路由才进入运行上下文；嵌套引用仍属于维护面 | +| 递归维护面 | L2 + L3 实测报告 | 防止把正文搬进 references 冒充维护减法，但不冒充一次运行上下文 | -预算的对象是**会被当作 Skill 加载进 Agent 上下文的字节**。`docs/`（含本文）与 `README.md` 是写给人看的，不计入；它们的约束是别的——没人读的文档不会因为不占预算就变得有用。 +[`docs/skills-overview.md`](./skills-overview.md) 每次从源码生成上述分层事实。来源检查通过只证明计量和声明一致，不证明任一运行端已安装、触发或产生净收益。 -上限默认取实际值，不留余量：目的就是让「加」必须伴随「换」。撞上上限时的正确动作是给出被压缩或退役的对象，而**不是**把数字改大。提高上限是负责人决定，且必须在 Issue 里留下理由；[`agent-control#57`](https://github.com/zaurakworks/agent-control/issues/57) 是一次只增加一个独立维护 Skill 的窄例外，不授权未来继续提高数量或字节上限。 +原 `209000` 字节硬门已由 [`agent-plugins#16`](https://github.com/zaurakworks/agent-plugins/issues/16) 退役：它只扫描 `references/` 顶层 Markdown，漏掉嵌套方法卡；同时把 L2、L3 和维护面错误当成同一批上下文字节。把漏项补进旧上限只会得到更大的错误数字，不解决口径问题。 -逐 Skill 的既有棘轮保持原样：它们锁定的是具体版本的谈判结果，与总量预算目的不同，合并会丢掉信息。 +数量门继续要求「加」伴随「换」。移动文字只有在正文保留明确按需路由时才可能降低运行成本，且不降低维护复杂度；真正优化优先删除行为、状态机、依赖和重复调用者。逐 Skill 的既有棘轮暂保留为历史谈判记录，后续在对应 Skill 审阅中逐项裁决。 ## 四、写作判据 @@ -117,7 +121,7 @@ git -C worktree add /<分支> -b <分支> | 选型面不得与来源漂移 | 2 拦截 | CI 重新生成并逐字节比对 | | 必须声明失效条件与最少复核步骤 | 2 拦截 | CI 断言存在且非空 | | `suspect` 标记的结构完整性 | 2 拦截 | CI 断言同时有命中条件与日期 | -| 数量与语料总量不得净增 | 2 拦截 | CI 断言 `complexityBudget` | +| Skill 数量不得越过已授权上限；L1／L2／L3 与维护面必须可复现 | 2 拦截 | CI 断言 `complexityBudget` 并递归实测 | | 退役必须确认三处都不存在 | 3 生成 | `plugin_release retire` | | 复核到期提醒 | 3 生成 | `plugin_release check` 本地报告 | | 开发不在生产检出里做 | **4 文本** | 无（只影响漂移检测能否判定，不影响会话行为） | diff --git a/docs/skills-overview.md b/docs/skills-overview.md index b904710..1f9ddc5 100644 --- a/docs/skills-overview.md +++ b/docs/skills-overview.md @@ -4,25 +4,39 @@ # Skill 选型面 这是给人看的入口：每个 Skill 替你做什么、什么时候会用到、你怎么看出它在起作用， -以及它花掉多少复杂度预算。`SKILL.md` 是给 Agent 执行的行为合同，优先保证触发、硬门、分支和退出完整，不是按顺序阅读的教程；只有维护或审查行为时才需要下钻。 - -当前 13 个 Skill，共 208,913 字节，占复杂度预算 100.0%。 - -| Skill | 版本 | 体积 | 占预算 | 上次复核 | -| --- | --- | ---: | ---: | --- | -| [issue-workflow](#issue-workflow) | 0.3.18 | 60.2 KB | 29.5% | 2026-08-15 | -| [orchestrated-collaboration](#orchestrated-collaboration) | 0.2.6 | 21.2 KB | 10.4% | 2026-08-15 | -| [adaptive-problem-solving](#adaptive-problem-solving) | 0.2.12 | 19.0 KB | 9.3% | 2026-08-15 | -| [self-improvement](#self-improvement) | 0.1.7 | 16.0 KB | 7.8% | 2026-08-15 | -| [pr-integration](#pr-integration) | 0.3.18 | 15.6 KB | 7.7% | 2026-08-15 | -| [issue-delivery](#issue-delivery) | 0.3.18 | 15.2 KB | 7.4% | 2026-08-15 | -| [objective-to-issues](#objective-to-issues) | 0.3.18 | 13.0 KB | 6.4% | 2026-08-15 | -| [operating-ledger-maintenance](#operating-ledger-maintenance) | 0.3.18 | 11.5 KB | 5.6% | 2026-08-15 | -| [resource-observability](#resource-observability) | 0.2.4 | 9.7 KB | 4.8% | 2026-08-15 | -| [issue-contract-compaction](#issue-contract-compaction) | 0.3.18 | 8.6 KB | 4.2% | 2026-08-15 | -| [knowledge-maintenance](#knowledge-maintenance) | 0.1.3 | 6.3 KB | 3.1% | 2026-08-15 | -| [grilling](#grilling) | 0.1.2 | 3.9 KB | 1.9% | 2026-08-15 | -| [skill-maintenance](#skill-maintenance) | 0.1.0 | 3.8 KB | 1.9% | 2026-08-16 | +以及它在不同加载层和维护面上的实测体积。`SKILL.md` 是给 Agent 执行的行为合同，优先保证触发、硬门、分支和退出完整，不是按顺序阅读的教程；只有维护或审查行为时才需要下钻。 + +当前 13 个 Skill：L1 descriptions 7,703 字节；L2 主合同 149,332 字节；L3 按需 references 204,984 字节；递归维护面合计 354,316 字节。 + +L1 受每项 1000 UTF-8 字节可见性门约束；L2 只在选择 Skill 后加载；L3 只在正文明确路由后按需加载。三者不是同一个运行上下文预算。维护面递归计量全部可执行 Markdown，但不设置会诱导搬运文字的字节上限。 + +| Skill | 版本 | L1 描述 | L2 主合同 | L3 引用 | 维护面占比 | 上次复核 | +| --- | --- | ---: | ---: | ---: | ---: | --- | +| [adaptive-problem-solving](#adaptive-problem-solving) | 0.2.12 | 703 B | 8.6 KB | 123.4 KB | 38.2% | 2026-08-15 | +| [issue-workflow](#issue-workflow) | 0.3.18 | 658 B | 23.7 KB | 36.5 KB | 17.4% | 2026-08-15 | +| [orchestrated-collaboration](#orchestrated-collaboration) | 0.2.6 | 876 B | 21.2 KB | 28.9 KB | 14.5% | 2026-08-15 | +| [self-improvement](#self-improvement) | 0.1.7 | 673 B | 8.8 KB | 7.2 KB | 4.6% | 2026-08-15 | +| [pr-integration](#pr-integration) | 0.3.18 | 581 B | 15.6 KB | 0.0 KB | 4.5% | 2026-08-15 | +| [issue-delivery](#issue-delivery) | 0.3.18 | 554 B | 15.2 KB | 0.0 KB | 4.4% | 2026-08-15 | +| [objective-to-issues](#objective-to-issues) | 0.3.18 | 491 B | 13.0 KB | 0.0 KB | 3.8% | 2026-08-15 | +| [operating-ledger-maintenance](#operating-ledger-maintenance) | 0.3.18 | 749 B | 11.5 KB | 0.0 KB | 3.3% | 2026-08-15 | +| [resource-observability](#resource-observability) | 0.2.4 | 608 B | 5.6 KB | 4.1 KB | 2.8% | 2026-08-15 | +| [issue-contract-compaction](#issue-contract-compaction) | 0.3.18 | 481 B | 8.6 KB | 0.0 KB | 2.5% | 2026-08-15 | +| [knowledge-maintenance](#knowledge-maintenance) | 0.1.3 | 644 B | 6.3 KB | 0.0 KB | 1.8% | 2026-08-15 | +| [grilling](#grilling) | 0.1.2 | 351 B | 3.9 KB | 0.0 KB | 1.1% | 2026-08-15 | +| [skill-maintenance](#skill-maintenance) | 0.1.0 | 334 B | 3.8 KB | 0.0 KB | 1.1% | 2026-08-16 | + +## adaptive-problem-solving + +**它替你做什么** 问题求解治理：选方法、控成本、该退出就退出，别在一条路上耗死。 + +**什么时候用** 第一次实质路径选择、进展停滞、范围明显扩大或要交接验收时。 + +**你怎么知道它在起作用** 方向变了会明确说出来；没变就直接继续，不额外汇报。 + +**什么会让它失效** 方法登记面的证据等级分布与登记面 README 声明不符；或三端 description 可见预算的实测基线（2026-08-11 测得 1000 UTF-8 字节）被新的实测推翻。 + +所属 Plugin `adaptive-problem-solving` `0.2.12`｜L1 703 B｜L2 8.6 KB｜L3 123.4 KB｜递归维护面 132.0 KB（占总维护面 38.2%）｜Agent 行为合同（维护／审查时读取）[`plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md`](../plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md) ## issue-workflow @@ -34,7 +48,7 @@ **什么会让它失效** GitHub 原生 sub-issue 关系、Project v2 字段写入语义或 Issue 关闭权限模型发生变化，使正文描述的建图与状态判定不再可执行。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 60.2 KB（占预算 29.5%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/issue-workflow/SKILL.md`](../plugins/github-collaboration/skills/issue-workflow/SKILL.md) +所属 Plugin `github-collaboration` `0.3.18`｜L1 658 B｜L2 23.7 KB｜L3 36.5 KB｜递归维护面 60.2 KB（占总维护面 17.4%）｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/issue-workflow/SKILL.md`](../plugins/github-collaboration/skills/issue-workflow/SKILL.md) ## orchestrated-collaboration @@ -46,19 +60,7 @@ **什么会让它失效** 所选协调后端（当前 orca orchestration）的 Run／Task／Dispatch 语义或标准释放回执格式变化；或其唯一原则源 agent-control/authority/05-resource-operations.md 的资源投入原则变化，使 R1–R6 派发门失去依据。 -所属 Plugin `orchestrated-collaboration` `0.2.6`｜体积 21.2 KB（占预算 10.4%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/orchestrated-collaboration/skills/orchestrated-collaboration/SKILL.md`](../plugins/orchestrated-collaboration/skills/orchestrated-collaboration/SKILL.md) - -## adaptive-problem-solving - -**它替你做什么** 问题求解治理：选方法、控成本、该退出就退出，别在一条路上耗死。 - -**什么时候用** 第一次实质路径选择、进展停滞、范围明显扩大或要交接验收时。 - -**你怎么知道它在起作用** 方向变了会明确说出来；没变就直接继续，不额外汇报。 - -**什么会让它失效** 方法登记面的证据等级分布与登记面 README 声明不符；或三端 description 可见预算的实测基线（2026-08-11 测得 1000 UTF-8 字节）被新的实测推翻。 - -所属 Plugin `adaptive-problem-solving` `0.2.12`｜体积 19.0 KB（占预算 9.3%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md`](../plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md) +所属 Plugin `orchestrated-collaboration` `0.2.6`｜L1 876 B｜L2 21.2 KB｜L3 28.9 KB｜递归维护面 50.1 KB（占总维护面 14.5%）｜Agent 行为合同（维护／审查时读取）[`plugins/orchestrated-collaboration/skills/orchestrated-collaboration/SKILL.md`](../plugins/orchestrated-collaboration/skills/orchestrated-collaboration/SKILL.md) ## self-improvement @@ -70,7 +72,7 @@ **什么会让它失效** 入口、Skill、任务记录三个改进承载面之一消失或职责变更，使路由判据指向不存在的去向。 -所属 Plugin `self-improvement` `0.1.7`｜体积 16.0 KB（占预算 7.8%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/self-improvement/skills/self-improvement/SKILL.md`](../plugins/self-improvement/skills/self-improvement/SKILL.md) +所属 Plugin `self-improvement` `0.1.7`｜L1 673 B｜L2 8.8 KB｜L3 7.2 KB｜递归维护面 16.0 KB（占总维护面 4.6%）｜Agent 行为合同（维护／审查时读取）[`plugins/self-improvement/skills/self-improvement/SKILL.md`](../plugins/self-improvement/skills/self-improvement/SKILL.md) ## pr-integration @@ -82,7 +84,7 @@ **什么会让它失效** 分支保护、合并策略或 force-push 的 lease 保护语义变化，使正文的分支维护步骤不再安全。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 15.6 KB（占预算 7.7%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/pr-integration/SKILL.md`](../plugins/github-collaboration/skills/pr-integration/SKILL.md) +所属 Plugin `github-collaboration` `0.3.18`｜L1 581 B｜L2 15.6 KB｜L3 0.0 KB｜递归维护面 15.6 KB（占总维护面 4.5%）｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/pr-integration/SKILL.md`](../plugins/github-collaboration/skills/pr-integration/SKILL.md) ## issue-delivery @@ -94,7 +96,7 @@ **什么会让它失效** PR 创建、审阅请求或必需检查的语义变化，使交付前核对无法只从远端事实判定。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 15.2 KB（占预算 7.4%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/issue-delivery/SKILL.md`](../plugins/github-collaboration/skills/issue-delivery/SKILL.md) +所属 Plugin `github-collaboration` `0.3.18`｜L1 554 B｜L2 15.2 KB｜L3 0.0 KB｜递归维护面 15.2 KB（占总维护面 4.4%）｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/issue-delivery/SKILL.md`](../plugins/github-collaboration/skills/issue-delivery/SKILL.md) ## objective-to-issues @@ -106,7 +108,7 @@ **什么会让它失效** 七类标题前缀闭集、两个 label 维度或经营总账 Project 的字段定义被负责人修改，使创建骨架的硬校验与实际仓库不符。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 13.0 KB（占预算 6.4%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/objective-to-issues/SKILL.md`](../plugins/github-collaboration/skills/objective-to-issues/SKILL.md) +所属 Plugin `github-collaboration` `0.3.18`｜L1 491 B｜L2 13.0 KB｜L3 0.0 KB｜递归维护面 13.0 KB（占总维护面 3.8%）｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/objective-to-issues/SKILL.md`](../plugins/github-collaboration/skills/objective-to-issues/SKILL.md) ## operating-ledger-maintenance @@ -118,7 +120,7 @@ **什么会让它失效** agent-control/authority/10-operating-ledger.md 的事项结构或状态分级变化，使维护动作指向不存在的字段。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 11.5 KB（占预算 5.6%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/operating-ledger-maintenance/SKILL.md`](../plugins/github-collaboration/skills/operating-ledger-maintenance/SKILL.md) +所属 Plugin `github-collaboration` `0.3.18`｜L1 749 B｜L2 11.5 KB｜L3 0.0 KB｜递归维护面 11.5 KB（占总维护面 3.3%）｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/operating-ledger-maintenance/SKILL.md`](../plugins/github-collaboration/skills/operating-ledger-maintenance/SKILL.md) ## resource-observability @@ -130,7 +132,7 @@ **什么会让它失效** orca account list --json 的返回结构变化：顶层 ok、result.rateLimits.claude／codex 的 status 与 updatedAt，或 usedPercent／windowMinutes／resetsAt／rateLimitResetCredits 这些窗口字段不再按 Skill 正文描述提供。 -所属 Plugin `resource-observability` `0.2.4`｜体积 9.7 KB（占预算 4.8%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/resource-observability/skills/resource-observability/SKILL.md`](../plugins/resource-observability/skills/resource-observability/SKILL.md) +所属 Plugin `resource-observability` `0.2.4`｜L1 608 B｜L2 5.6 KB｜L3 4.1 KB｜递归维护面 9.7 KB（占总维护面 2.8%）｜Agent 行为合同（维护／审查时读取）[`plugins/resource-observability/skills/resource-observability/SKILL.md`](../plugins/resource-observability/skills/resource-observability/SKILL.md) ## issue-contract-compaction @@ -142,7 +144,7 @@ **什么会让它失效** GitHub 返回的时间标量精度或字段序列化形态变化，使「优先比较原始序列化标量」不再能区分真实变更。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 8.6 KB（占预算 4.2%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/issue-contract-compaction/SKILL.md`](../plugins/github-collaboration/skills/issue-contract-compaction/SKILL.md) +所属 Plugin `github-collaboration` `0.3.18`｜L1 481 B｜L2 8.6 KB｜L3 0.0 KB｜递归维护面 8.6 KB（占总维护面 2.5%）｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/issue-contract-compaction/SKILL.md`](../plugins/github-collaboration/skills/issue-contract-compaction/SKILL.md) ## knowledge-maintenance @@ -154,7 +156,7 @@ **什么会让它失效** agent-control/authority/01-knowledge.md 的两道准入门或可信门八项条件发生变化。 -所属 Plugin `knowledge-maintenance` `0.1.3`｜体积 6.3 KB（占预算 3.1%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/knowledge-maintenance/skills/knowledge-maintenance/SKILL.md`](../plugins/knowledge-maintenance/skills/knowledge-maintenance/SKILL.md) +所属 Plugin `knowledge-maintenance` `0.1.3`｜L1 644 B｜L2 6.3 KB｜L3 0.0 KB｜递归维护面 6.3 KB（占总维护面 1.8%）｜Agent 行为合同（维护／审查时读取）[`plugins/knowledge-maintenance/skills/knowledge-maintenance/SKILL.md`](../plugins/knowledge-maintenance/skills/knowledge-maintenance/SKILL.md) ## grilling @@ -166,7 +168,7 @@ **什么会让它失效** 明示同意门被取消，或运行端改为按关键词自动进入长期盘问。 -所属 Plugin `grilling` `0.1.2`｜体积 3.9 KB（占预算 1.9%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/grilling/skills/grilling/SKILL.md`](../plugins/grilling/skills/grilling/SKILL.md) +所属 Plugin `grilling` `0.1.2`｜L1 351 B｜L2 3.9 KB｜L3 0.0 KB｜递归维护面 3.9 KB（占总维护面 1.1%）｜Agent 行为合同（维护／审查时读取）[`plugins/grilling/skills/grilling/SKILL.md`](../plugins/grilling/skills/grilling/SKILL.md) ## skill-maintenance @@ -178,4 +180,4 @@ **什么会让它失效** Skill 的发现入口、版本声明、复杂度预算、生成物或发布／退役工具发生变化，使正文盘点面和 clean cutover 步骤不再覆盖真实运行路径。 -所属 Plugin `skill-maintenance` `0.1.0`｜体积 3.8 KB（占预算 1.9%）｜上次复核 2026-08-16｜Agent 行为合同（维护／审查时读取）[`plugins/skill-maintenance/skills/skill-maintenance/SKILL.md`](../plugins/skill-maintenance/skills/skill-maintenance/SKILL.md) +所属 Plugin `skill-maintenance` `0.1.0`｜L1 334 B｜L2 3.8 KB｜L3 0.0 KB｜递归维护面 3.8 KB（占总维护面 1.1%）｜Agent 行为合同（维护／审查时读取）[`plugins/skill-maintenance/skills/skill-maintenance/SKILL.md`](../plugins/skill-maintenance/skills/skill-maintenance/SKILL.md) diff --git a/scripts/skills-overview.ts b/scripts/skills-overview.ts index 3442797..0056bf8 100644 --- a/scripts/skills-overview.ts +++ b/scripts/skills-overview.ts @@ -3,7 +3,7 @@ // // 只有三句话是手写的（写在 tests/workflow-routing.json 的 skillOverview 里）： // 它替你做什么、什么时候用、你怎么知道它在起作用。其余全部推导——版本来自 -// pluginVersions，复核状态来自 skillLifecycle，体积与预算占比来自实测字节。 +// pluginVersions，复核状态来自 skillLifecycle，L1/L2/L3 与递归维护面来自实测字节。 // // **它是生成产物，不是手写文档。** 符合性测试会重新生成并与文件比对，因此 // 它不可能与来源漂移——这正是 docs/lifecycle.md 要防的东西，选型面自己也得守。 @@ -17,13 +17,10 @@ import { dirname, join } from 'node:path'; const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..'); const read = (path: string): string => readFileSync(path, 'utf8').replace(/^/, '').replace(/\r\n/g, '\n'); -const directories = (path: string): string[] => - readdirSync(path).filter((entry) => statSync(join(path, entry)).isDirectory()); type Manifest = { - skills: Record; + descriptionBudget: { maxUtf8Bytes: number }; pluginVersions: Record; - complexityBudget: { corpusMaxUtf8Bytes: number }; skillLifecycle: { entries: Record< string, @@ -37,26 +34,67 @@ type Manifest = { const manifest = JSON.parse(read(join(repoRoot, 'tests', 'workflow-routing.json'))) as Manifest; -/** SKILL.md 加它自己的 references/，与语料预算同一口径。 */ -function skillBytes(plugin: string, skill: string): number { - const root = join(repoRoot, 'plugins', plugin, 'skills', skill); - let total = Buffer.byteLength(read(join(root, 'SKILL.md')), 'utf8'); - const references = join(root, 'references'); - if (existsSync(references)) { - for (const file of readdirSync(references)) { - if (file.endsWith('.md')) total += Buffer.byteLength(read(join(references, file)), 'utf8'); +type SkillSize = { + description: number; + main: number; + references: number; + maintenance: number; +}; + +function markdownBytesRecursively(root: string): number { + if (!existsSync(root)) return 0; + let total = 0; + for (const entry of readdirSync(root)) { + const path = join(root, entry); + if (statSync(path).isDirectory()) { + total += markdownBytesRecursively(path); + } else if (entry.endsWith('.md')) { + total += Buffer.byteLength(read(path), 'utf8'); } } return total; } +function deliveredDescriptionBytes(skillBody: string): number { + const match = /^description:\s*[>|][-+]?\s*\n(?(?: {2,}.*(?:\n|$))*)/mu.exec(skillBody); + if (!match?.groups?.body) throw new Error('SKILL.md frontmatter 缺少可折叠 description'); + const delivered = match.groups.body + .split('\n') + .map((line) => line.trim()) + .filter(Boolean) + .join(' '); + return Buffer.byteLength(delivered, 'utf8'); +} + +function skillSize(plugin: string, skill: string): SkillSize { + const root = join(repoRoot, 'plugins', plugin, 'skills', skill); + const mainBody = read(join(root, 'SKILL.md')); + const main = Buffer.byteLength(mainBody, 'utf8'); + const references = markdownBytesRecursively(join(root, 'references')); + return { + description: deliveredDescriptionBytes(mainBody), + main, + references, + maintenance: main + references, + }; +} + export function render(): string { - const budget = manifest.complexityBudget.corpusMaxUtf8Bytes; - const rows = Object.entries(manifest.skills).map(([skill, spec]) => { - const bytes = skillBytes(spec.plugin, skill); - return { skill, plugin: spec.plugin, bytes, share: (bytes / budget) * 100 }; - }); - rows.sort((a, b) => b.bytes - a.bytes); + const rows = Object.entries(manifest.skills).map(([skill, spec]) => ({ + skill, + plugin: spec.plugin, + size: skillSize(spec.plugin, skill), + })); + const totals = rows.reduce( + (sum, row) => ({ + description: sum.description + row.size.description, + main: sum.main + row.size.main, + references: sum.references + row.size.references, + maintenance: sum.maintenance + row.size.maintenance, + }), + { description: 0, main: 0, references: 0, maintenance: 0 }, + ); + rows.sort((a, b) => b.size.maintenance - a.size.maintenance); const lines: string[] = [ '