Skip to content

feat(skills): 落 issue #211 首批协作知识点 + 修 #209 遗留陈旧测试 - #214

Merged
PanQiWei merged 2 commits into
mainfrom
feat/issue-211-user-unknowns
Jul 28, 2026
Merged

feat(skills): 落 issue #211 首批协作知识点 + 修 #209 遗留陈旧测试#214
PanQiWei merged 2 commits into
mainfrom
feat/issue-211-user-unknowns

Conversation

@PanQiWei

@PanQiWei PanQiWei commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

把 issue #211 的第一批协作知识点落进 master-orchestrator-guide，顺带修掉四个从 #209 起就红着的陈旧测试。

两个 commit 无因果关系，只是恰好挡在同一道门前，可分别 revert。

fe01a7c7 — 落 #211 首批协作知识点

新增 module collab.unknowns（5 点 / 10 边）

落 references/user-unknowns.md，补的是「帮用户发现说不出口的未知」这一整个维度：

  • 四类未知作为 orchestrator 的内部分派轴——明确不作为对用户的话术
  • 按未知类型分派手法：扫描地形（连问题都提不出来）/ 造多方向的物（语言通道失效）/ 提问（知道自己没想清）/ 先建判断框架（连什么叫好都没有）
  • 提问纪律：一次一个，按会不会改架构排序，剩余未知不再改变方案形状即停
  • 用户没有判断框架时先建框架，不索要一份并不存在的 spec
  • 具体物优于散文描述；载体依赖 host，底线是真实代码 + 可跑样例

强化既有 module

  • verification.endpoint + verification.user-understanding：验收的第二个对象是「用户理解了没有」，按风险给理解材料，低风险不加仪式；它不替代端点验收，也不是事后追认授权的通道
  • planning.multi-layer + multilayer.deviation-notes：够格的大节点在派发契约里加一条偏离记录；留痕不能把该升级的语义变更变成既成事实

两处缝合（防第二真相源）

  • outside-in.md 明确与 user-unknowns.md 的分界：一个管已表述假设的证据强度，一个管哪些还没被表述出来；两轴正交
  • decomposition.md 的 Success predicate 改为优先给可执行验收物（会失败的测试 / 评分标准 / 真实样例），而非散文式验收描述

一处需要 reviewer 注意的改动

portfolio.json 的 atlas_max_tokens 2800 → 3000。

atlas 是每 module 一条的全局路由，尺寸随模块数线性增长。46 模块时仅余约 11 token，新增任何 module 都会溢出（SKG-BUDGET-ROUTER，实测 2849 > 2800）。已在干净基线上确认这不是既有失败。

这是把绊线往后挪了约 2.5 个 module，不是结构性解法——真正的解是 per-skill 分层 atlas，让常驻部分不随模块数增长。未在本 PR 处理。

验证

  • skill-knowledge check --stage K3 → ok，0 errors / 0 debts
  • skill-knowledge report → pass，0 diagnostics，graph hash ef7da7fb…
  • 图：47 module / 256 point / 418 edge（原 46 / 249 / 404）
  • 四 host dist 已投影；provider-guidance-runtime.json 经 scripts/regenerate-attestations.sh 官方入口重算
  • claude plugin validate plugin/dist/claude-code → Validation passed

8556b302 — 修 #209 遗留的四个陈旧断言

四条自 60bc0f13 (#209) 起就红，与同一个 commit 引入的代码/守卫互相矛盾，从未跑绿过。已在干净 HEAD worktree 上逐一确认与本 PR 无关。

两种失败模式：

  1. 测一个被有意移除的接缝（v4）
  2. 断言 knowledge/ 出现在 host 树里（v9 / v10 / v11）——与 AGENTS.md「禁止进入 dist/package/release」、cli-contract「repo-only knowledge/ 不进入 host 输出」、以及 CI 正在跑的 check-release-knowledge-boundary.mjs 三处相反

排除了产品回归：atlas 拓扑一直在产出，只是按设计作为 compiler-owned 后缀嵌在 skill-local Markdown 里（emit.mjs:398 用 routerPlan.atlas.path；emit.mjs:699 注释明写 "emitted only into accepted skill-local Markdown"）。atlasDistPath() 是永不触发的残留后备值。

修法是换成正确的证明，不是删断言——覆盖增强而非削弱，repo-only 边界现在在 live 树与 candidate 树两条路径上都有测试守了。

四个文件 18 个 case 已单独重跑全绿；静态扫两种失败模式确认家族封闭，无第五个。

测试与门的诚实边界

全套 run-tests.sh 未跑到完整绿。 本机一次全量约 90 分钟，且其中最贵的部分与本 PR 无关。绿的依据是：

检查 结果
四个曾红文件（18 case） 单独重跑 全绿
check --stage K3 / report 双绿，0 diagnostics
claude plugin validate ✔
四 host dist + attestation 已重算同步
静态扫两种失败模式 无第五个同族

未覆盖：tests/content/ 其余约 57 个文件在本 PR 下未重跑。风险是「main 上可能还有别的既有红」——那是既有状态，不是本 PR 引入，正是 #213 要解决的问题。

CI 的 build-and-check 会守它覆盖的那部分。

Refs #211
Refs #213

🤖 Generated with Claude Code

PanQiWei and others added 2 commits July 28, 2026 09:56
@PanQiWei @claude
feat(skills): 落 issue #211 首批协作知识点
fe01a7c 
把「帮用户发现说不出口的未知」这一族能力接进 master-orchestrator-guide，
并补上验收与派发两处的配套点。全部经知识图 typed 落地，四 host 已投影。

新增 module `collab.unknowns`（5 点 / 10 边），落 references/user-unknowns.md：
- 四类未知作为 orchestrator 的内部分派轴（不作为对用户的话术）
- 按未知类型分派手法：扫描地形 / 造多方向的物 / 提问 / 先建判断框架
- 提问纪律：一次一个，按会不会改架构排序，剩余未知不再改变方案形状即停
- 用户没有判断框架时先建框架，不索要并不存在的 spec
- 具体物优于散文描述；载体依赖 host，底线是真实代码 + 可跑样例

强化既有 module：
- verification.endpoint 增 `verification.user-understanding`：验收的第二个对象
  是「用户理解了没有」，按风险给理解材料，低风险不加仪式
- planning.multi-layer 增 `multilayer.deviation-notes`：够格的大节点在派发契约
  里加一条偏离记录；留痕不能把该升级的语义变更变成既成事实

两处缝合（防第二真相源）：
- outside-in.md 明确与 user-unknowns.md 的分界：一个管已表述假设的证据强度，
  一个管哪些还没被表述出来；两轴正交
- decomposition.md 的 Success predicate 改为优先给可执行验收物

portfolio `atlas_max_tokens` 2800 → 3000：atlas 是每 module 一条的全局路由，
尺寸随模块数线性增长；46 模块时仅余约 11 token，新增任何 module 都会溢出。

图快照：47 module / 256 point / 418 edge，`check --stage K3` 与 `report` 双绿。
provider-guidance attestation 已按官方入口重算。

Refs #211

Co-Authored-By: Claude <noreply@anthropic.com>
@PanQiWei @claude
fix(tests): 修正 #209 遗留的四个陈旧 skill-overlay 断言
8556b30 
这四条自 60bc0f1 (#209) 起就是红的——它们与同一个 commit 引入的代码/守卫
互相矛盾，从未跑绿过。CI 的 build-and-check 不包含 run-tests.sh，也不包含
这四个测试文件，所以 main 能在本地套件红的状态下保持 CI 全绿（见 #213）。

四条同属一个家族，两种失败模式：

**模式一：测一个被有意移除的接缝**

v4（skill-overlay-v3-skills-swap-commit）测 `projectAndPublishSkillsSurface`
的 legacy `beforePublish` 接缝——而同一个 PR 把它改成了显式拒绝（skills-only
一律扩成 full-host trusted publish）。改为钉住当前契约：拒绝必须发生在接缝能
运行之前，且被拒的请求必须是惰性的（live 字节不变、无新增残留）。host 级
collision/backup 覆盖仍由 v9 的 publishHostTree 系列承担，覆盖不丢。

**模式二：断言 `knowledge/` 出现在 host 树里**

v9 / v10 / v11 分别断言 live 树有 `knowledge/`、live 树有
`knowledge/atlas.md`、candidate 树有 `knowledge/atlas.md`。三者都与
repo-only 边界相反：AGENTS.md「本目录禁止进入 dist/package/release」、
cli-contract「repo-only knowledge/ 不进入 host 输出」、以及 CI 正在跑的
check-release-knowledge-boundary.mjs。

排除了产品回归的可能：atlas 拓扑一直在产出，只是按设计作为 compiler-owned
后缀嵌在 skill-local Markdown 里（emit.mjs:398 用 routerPlan.atlas.path，
emit.mjs:699 注释明写 "emitted only into accepted skill-local Markdown"）。
`atlasDistPath()` 是永不触发的残留后备值。dist 实证：SKILL.md 尾部带
`<!-- ccm:k:generated -->` 与 "## Back to atlas"。

因此把断言换成正确的证明，而非删除：
  assert.match(SKILL.md, /<!-- ccm:k:generated -->/)   // 拓扑确实 emit 了
  assert.ok(!exists(.../knowledge))                     // 且没落在禁区

净效果是覆盖增强——原来只证明「有个文件在」，现在证明「拓扑真的 emit 了
**且** 落在合规位置」；repo-only 边界在 live 树与 candidate 树两条路径上
现在都有测试守了。

四个文件 18 个 case 已单独重跑全绿。静态扫两种失败模式确认家族封闭，无第五个。

Co-Authored-By: Claude <noreply@anthropic.com>
@PanQiWei
PanQiWei merged commit 91e23d0 into main Jul 28, 2026
3 checks passed
@PanQiWei
PanQiWei deleted the feat/issue-211-user-unknowns branch July 28, 2026 11:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@PanQiWei