From 2054f1935b5d32b8b57982e3a6ca3a622d6ceabe Mon Sep 17 00:00:00 2001 From: zaurakworks Date: Sun, 16 Aug 2026 08:11:49 -0400 Subject: [PATCH] docs(aps): distinguish human overview from agent contracts --- docs/skills-overview.md | 28 +++++++++---------- .../references/method-registry/README.md | 2 +- .../cards/aps-bounded-research.md | 2 +- .../method-registry/cards/aps-roi-options.md | 2 +- .../method-registry/cards/premortem.md | 2 +- scripts/skills-overview.ts | 6 ++-- tests/workflow-routing.test.ts | 6 ++++ 7 files changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/skills-overview.md b/docs/skills-overview.md index eea9162..8f10322 100644 --- a/docs/skills-overview.md +++ b/docs/skills-overview.md @@ -3,8 +3,8 @@ # Skill 选型面 -写给负责人：每个 Skill 替你做什么、什么时候会用到、你怎么看出它在起作用， -以及它花掉多少复杂度预算。**行为的唯一来源仍是各自的 `SKILL.md`**，本页不承载行为。 +这是给人看的入口：每个 Skill 替你做什么、什么时候会用到、你怎么看出它在起作用， +以及它花掉多少复杂度预算。`SKILL.md` 是给 Agent 执行的行为合同，优先保证触发、硬门、分支和退出完整，不是按顺序阅读的教程；只有维护或审查行为时才需要下钻。 当前 12 个 Skill，共 208,420 字节，占复杂度预算 99.7%。 @@ -33,7 +33,7 @@ **什么会让它失效** GitHub 原生 sub-issue 关系、Project v2 字段写入语义或 Issue 关闭权限模型发生变化，使正文描述的建图与状态判定不再可执行。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 60.1 KB（占预算 29.5%）｜上次复核 2026-08-15｜正文 [`plugins/github-collaboration/skills/issue-workflow/SKILL.md`](../plugins/github-collaboration/skills/issue-workflow/SKILL.md) +所属 Plugin `github-collaboration` `0.3.18`｜体积 60.1 KB（占预算 29.5%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/github-collaboration/skills/issue-workflow/SKILL.md`](../plugins/github-collaboration/skills/issue-workflow/SKILL.md) ## adaptive-problem-solving @@ -45,7 +45,7 @@ **什么会让它失效** 方法登记面的证据等级分布与登记面 README 声明不符；或三端 description 可见预算的实测基线（2026-08-11 测得 1000 UTF-8 字节）被新的实测推翻。 -所属 Plugin `adaptive-problem-solving` `0.2.11`｜体积 22.0 KB（占预算 10.8%）｜上次复核 2026-08-15｜正文 [`plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md`](../plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md) +所属 Plugin `adaptive-problem-solving` `0.2.11`｜体积 22.0 KB（占预算 10.8%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md`](../plugins/adaptive-problem-solving/skills/adaptive-problem-solving/SKILL.md) ## orchestrated-collaboration @@ -57,7 +57,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｜正文 [`plugins/orchestrated-collaboration/skills/orchestrated-collaboration/SKILL.md`](../plugins/orchestrated-collaboration/skills/orchestrated-collaboration/SKILL.md) +所属 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) ## self-improvement @@ -69,7 +69,7 @@ **什么会让它失效** 入口、Skill、任务记录三个改进承载面之一消失或职责变更，使路由判据指向不存在的去向。 -所属 Plugin `self-improvement` `0.1.6`｜体积 16.3 KB（占预算 8.0%）｜上次复核 2026-08-15｜正文 [`plugins/self-improvement/skills/self-improvement/SKILL.md`](../plugins/self-improvement/skills/self-improvement/SKILL.md) +所属 Plugin `self-improvement` `0.1.6`｜体积 16.3 KB（占预算 8.0%）｜上次复核 2026-08-15｜Agent 行为合同（维护／审查时读取）[`plugins/self-improvement/skills/self-improvement/SKILL.md`](../plugins/self-improvement/skills/self-improvement/SKILL.md) ## pr-integration @@ -81,7 +81,7 @@ **什么会让它失效** 分支保护、合并策略或 force-push 的 lease 保护语义变化，使正文的分支维护步骤不再安全。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 15.6 KB（占预算 7.7%）｜上次复核 2026-08-15｜正文 [`plugins/github-collaboration/skills/pr-integration/SKILL.md`](../plugins/github-collaboration/skills/pr-integration/SKILL.md) +所属 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) ## issue-delivery @@ -93,7 +93,7 @@ **什么会让它失效** PR 创建、审阅请求或必需检查的语义变化，使交付前核对无法只从远端事实判定。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 15.2 KB（占预算 7.4%）｜上次复核 2026-08-15｜正文 [`plugins/github-collaboration/skills/issue-delivery/SKILL.md`](../plugins/github-collaboration/skills/issue-delivery/SKILL.md) +所属 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) ## objective-to-issues @@ -105,7 +105,7 @@ **什么会让它失效** 七类标题前缀闭集、两个 label 维度或经营总账 Project 的字段定义被负责人修改，使创建骨架的硬校验与实际仓库不符。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 13.0 KB（占预算 6.4%）｜上次复核 2026-08-15｜正文 [`plugins/github-collaboration/skills/objective-to-issues/SKILL.md`](../plugins/github-collaboration/skills/objective-to-issues/SKILL.md) +所属 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) ## operating-ledger-maintenance @@ -117,7 +117,7 @@ **什么会让它失效** agent-control/authority/10-operating-ledger.md 的事项结构或状态分级变化，使维护动作指向不存在的字段。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 11.5 KB（占预算 5.6%）｜上次复核 2026-08-15｜正文 [`plugins/github-collaboration/skills/operating-ledger-maintenance/SKILL.md`](../plugins/github-collaboration/skills/operating-ledger-maintenance/SKILL.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) ## resource-observability @@ -129,7 +129,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｜正文 [`plugins/resource-observability/skills/resource-observability/SKILL.md`](../plugins/resource-observability/skills/resource-observability/SKILL.md) +所属 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) ## issue-contract-compaction @@ -141,7 +141,7 @@ **什么会让它失效** GitHub 返回的时间标量精度或字段序列化形态变化，使「优先比较原始序列化标量」不再能区分真实变更。 -所属 Plugin `github-collaboration` `0.3.18`｜体积 8.6 KB（占预算 4.2%）｜上次复核 2026-08-15｜正文 [`plugins/github-collaboration/skills/issue-contract-compaction/SKILL.md`](../plugins/github-collaboration/skills/issue-contract-compaction/SKILL.md) +所属 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) ## knowledge-maintenance @@ -153,7 +153,7 @@ **什么会让它失效** agent-control/authority/01-knowledge.md 的两道准入门或可信门八项条件发生变化。 -所属 Plugin `knowledge-maintenance` `0.1.3`｜体积 6.3 KB（占预算 3.1%）｜上次复核 2026-08-15｜正文 [`plugins/knowledge-maintenance/skills/knowledge-maintenance/SKILL.md`](../plugins/knowledge-maintenance/skills/knowledge-maintenance/SKILL.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) ## grilling @@ -165,4 +165,4 @@ **什么会让它失效** 明示同意门被取消，或运行端改为按关键词自动进入长期盘问。 -所属 Plugin `grilling` `0.1.2`｜体积 3.9 KB（占预算 1.9%）｜上次复核 2026-08-15｜正文 [`plugins/grilling/skills/grilling/SKILL.md`](../plugins/grilling/skills/grilling/SKILL.md) +所属 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) diff --git a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/README.md b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/README.md index 0e38934..4b91e68 100644 --- a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/README.md +++ b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/README.md @@ -55,7 +55,7 @@ ## 当前来源水位 -- 关联 `agent-control#70` 的方法卡 schema、P1–P8 类型学、五层承载与 70-D1／70-D2 决定回执；核验时间：2026-08-11。 +- 旧仓 [Eridanus117/agent-control#70（方法模型与方法库的目标形态）](https://github.com/Eridanus117/agent-control/issues/70) 的方法卡 schema、P1–P8 类型学、五层承载与 70-D1／70-D2 决定回执；核验时间：2026-08-11。当前问题求解诉求已迁至 [zaurakworks/agent-control#4](https://github.com/zaurakworks/agent-control/issues/4)，两者编号不可互换。 - 仓内 APS `0.2.8`、`grilling` `0.1.0`、`self-improvement` `0.1.4`；首批登记面基线核验提交：`a11176fddc70c50f32984cfef9da18d8768370fa`。 - [关联 Eridanus117/agent-control#85（Premortem 方法卡实战）的证据升级评论](https://github.com/Eridanus117/agent-control/issues/85#issuecomment-5258420709)与[关联 Eridanus117/agent-control#86（关键假设检查方法卡实战）的自然任务评论](https://github.com/Eridanus117/agent-control/issues/86#issuecomment-5258418149)；本批只支持两张卡在原适用边界升为 M1。 - [关联 Eridanus117/agent-control#92（红队方法卡实战）的红队评论](https://github.com/Eridanus117/agent-control/issues/92#issuecomment-5258711541)与[收口回执](https://github.com/Eridanus117/agent-control/issues/92#issuecomment-5258729826)；本批只支持 `red-team-analysis` 在私域迁移链路只读安全审查边界升为 M1。 diff --git a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-bounded-research.md b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-bounded-research.md index 7e56982..ffc2cf3 100644 --- a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-bounded-research.md +++ b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-bounded-research.md @@ -36,7 +36,7 @@ ## 有效性证据 - 来源等级：本次直接验证；能力证据等级：M1 当前交付验收；适用环境：Agent 系统多来源研究。 -- 成功样本：关联 `agent-control#70` 的方法模型调研被负责人消费并形成 70-D1／70-D2 决定；失败样本：无系统记录；未知：跨领域稳定性。 +- 成功样本：旧仓 [Eridanus117/agent-control#70（方法模型与方法库的目标形态）](https://github.com/Eridanus117/agent-control/issues/70)的调研被负责人消费并形成 70-D1／70-D2 决定；失败样本：无系统记录；未知：跨领域稳定性。 ## 维护 - 失效条件：APS 证据分区或研究形状被替代；下次最少复核：下一次自然使用后核对成本与误触发。 diff --git a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-roi-options.md b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-roi-options.md index 4b32260..ae33da6 100644 --- a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-roi-options.md +++ b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/aps-roi-options.md @@ -37,7 +37,7 @@ ## 有效性证据 - 来源等级：本次直接验证；能力证据等级：M1 当前交付验收；适用环境：运行底座依赖的有界产品与实施取舍。 - 成功样本：[关联 Eridanus117/agent-control#112（Orca 依赖三方向 ROI）的交付评论](https://github.com/Eridanus117/agent-control/issues/112#issuecomment-5261062363)；样本摘要：在负责人点名使用本卡后，按父目标收益、建设维护成本、退出成本、供应链风险、可逆性、总周期、有用吞吐与负责人注意力比较上游优先、Fork 与后端抽象三方向，并以中高置信推荐维持上游优先、给出最强反方和两条可观察翻转路径；后续回执没有推翻三方向排序。 -- 失败样本：[关联 Eridanus117/agent-control#93（问题类型学首批真实样本校准）的样本 17](https://github.com/Eridanus117/agent-control/issues/93#issuecomment-5258734377)记录关联 #70（方法模型与方法库目标形态）虽具备完整选项、反方与翻转条件，却因把“渐进”当默认而给出错误推荐；[关联 Eridanus117/agent-control#112（Orca 依赖三方向 ROI）的决定回执](https://github.com/Eridanus117/agent-control/issues/112#issuecomment-5261160382)进一步确认，排序虽成立，把“不作决定也会继续”的维持现状推荐包装成负责人决定请求，仍会无谓占用负责人注意力。未知：本次排序在翻转条件出现后能否及时换路，以及不同底座或非平台取舍能否复现收益。 +- 失败样本：[关联 Eridanus117/agent-control#93（问题类型学首批真实样本校准）的样本 17](https://github.com/Eridanus117/agent-control/issues/93#issuecomment-5258734377)记录旧仓 [Eridanus117/agent-control#70（方法模型与方法库的目标形态）](https://github.com/Eridanus117/agent-control/issues/70)虽具备完整选项、反方与翻转条件，却因把“渐进”当默认而给出错误推荐；[关联 Eridanus117/agent-control#112（Orca 依赖三方向 ROI）的决定回执](https://github.com/Eridanus117/agent-control/issues/112#issuecomment-5261160382)进一步确认，排序虽成立，把“不作决定也会继续”的维持现状推荐包装成负责人决定请求，仍会无谓占用负责人注意力。未知：本次排序在翻转条件出现后能否及时换路，以及不同底座或非平台取舍能否复现收益。 ## 维护 - 失效条件：APS 的默认 ROI 目标或负责人决定边界改变；下次最少复核：首次命中 Fork／抽象翻转条件，或下一次完整字段与实际推荐发生分歧时，核对代理指标与决定价值门。 diff --git a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/premortem.md b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/premortem.md index 9afbcb2..f513e02 100644 --- a/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/premortem.md +++ b/plugins/adaptive-problem-solving/skills/adaptive-problem-solving/references/method-registry/cards/premortem.md @@ -2,7 +2,7 @@ ## 身份与来源 - `method_id`：`premortem`；版本：`0.1.1`；维护者：agent-plugins。 -- 来源：APS 路线 4 的轻量前置；外部结构由关联 `agent-control#70` 所核验的 CIA 结构化分析资料校准；许可／私域：独立改写，未复制来源原文；核验时间：2026-08-11。 +- 来源：APS 路线 4 的轻量前置；外部结构由旧仓 [Eridanus117/agent-control#70（方法模型与方法库的目标形态）](https://github.com/Eridanus117/agent-control/issues/70)所核验的 CIA 结构化分析资料校准；许可／私域：独立改写，未复制来源原文；核验时间：2026-08-11。 ## 目的与类型 - 要减少的未知／决定：在重要合同或方案实施前暴露最可能失败原因；主类型：P4；次类型：P5。 diff --git a/scripts/skills-overview.ts b/scripts/skills-overview.ts index cede2cb..3442797 100644 --- a/scripts/skills-overview.ts +++ b/scripts/skills-overview.ts @@ -64,8 +64,8 @@ export function render(): string { '', '# Skill 选型面', '', - '写给负责人：每个 Skill 替你做什么、什么时候会用到、你怎么看出它在起作用，', - '以及它花掉多少复杂度预算。**行为的唯一来源仍是各自的 `SKILL.md`**，本页不承载行为。', + '这是给人看的入口：每个 Skill 替你做什么、什么时候会用到、你怎么看出它在起作用，', + '以及它花掉多少复杂度预算。`SKILL.md` 是给 Agent 执行的行为合同，优先保证触发、硬门、分支和退出完整，不是按顺序阅读的教程；只有维护或审查行为时才需要下钻。', '', `当前 ${rows.length} 个 Skill，共 ${rows.reduce((s, r) => s + r.bytes, 0).toLocaleString('en-US')} 字节，` + `占复杂度预算 ${((rows.reduce((s, r) => s + r.bytes, 0) / budget) * 100).toFixed(1)}%。`, @@ -104,7 +104,7 @@ export function render(): string { `所属 Plugin \`${row.plugin}\` \`${manifest.pluginVersions[row.plugin]}\`｜` + `体积 ${(row.bytes / 1024).toFixed(1)} KB（占预算 ${row.share.toFixed(1)}%）｜` + `上次复核 ${life.suspect ? '**存疑**' : (life.lastVerified ?? '**从未**')}｜` + - `正文 [\`plugins/${row.plugin}/skills/${row.skill}/SKILL.md\`](../plugins/${row.plugin}/skills/${row.skill}/SKILL.md)`, + `Agent 行为合同（维护／审查时读取）[\`plugins/${row.plugin}/skills/${row.skill}/SKILL.md\`](../plugins/${row.plugin}/skills/${row.skill}/SKILL.md)`, '', ); } diff --git a/tests/workflow-routing.test.ts b/tests/workflow-routing.test.ts index 450da14..8d9d62d 100644 --- a/tests/workflow-routing.test.ts +++ b/tests/workflow-routing.test.ts @@ -2598,6 +2598,12 @@ assert.equal( renderSkillsOverview(), 'docs/skills-overview.md 与来源不一致：它是生成产物，请跑 node scripts/skills-overview.ts --write，不要手改', ); +assert.ok( + read(overviewPath).includes('这是给人看的入口') && + read(overviewPath).includes('`SKILL.md` 是给 Agent 执行的行为合同') && + read(overviewPath).includes('不是按顺序阅读的教程'), + '负责人选型面必须区分人类入口与 Agent 行为合同', +); // ---------- 9. README 的版本总览不能落后于 manifest ----------