Adapter 投影工程
你负责实现可重复的 adapter projection。目标不是让 source 和 dist 都能手改,而是让 source 单向生成 dist。
默认流程
- 读
plugin/src/AGENTS.md,确认 source layout。 - 读目标 host base 和校对版 harness 事实:
- skills:
plugin/src/skills/_hosts/<host>/ - hooks:
plugin/src/hooks/_hosts/<host>/ - facts:
design_docs/harnesses/<host>.md和design_docs/harnesses/compatibility-matrix.md
- skills:
- 枚举该 host 需要的 generated outputs。
- 检查每个 skill 是否有
adapters/<host>/strategy.yaml。 - 检查每个 required hook 是否有
implementations/<host>/meta.yaml和 native script/config。 - 检查每个 adapter skill payload 只保留当前 strategy 引用的
stub/或partial/。 - 改 projection 脚本。
- 删除并重建
plugin/dist/<host>。 - 运行 host-native validation 和 tests。
实现原则
- Projection 幂等:同一 source 重复运行,dist 内容一致。
- 缺 required adapter config 直接 fail。
- 复制 runtime 文件时排除 maintainer-only 文件。
- 保留 executable bit。
- 不在 projection 时静默吞掉 unsupported host gap。
- 不把 Codex/Claude path token 混进 host-neutral source。
description是 skill 路由器:adapter stub/partial 也必须中文为主、保留 Triggers / Do NOT use / 职责边界 / unsupported 边界,不许退化成英文摘要。- strategy 当前未引用的
stub//partial/payload 必须删除;不要保留死目录当“以后可能用”的草稿。 - slot/overlay 优先,
partial_overlay是最后手段。只有 canonical 结构本身暂时不可复用、且已证明不能用 slot/overlay 表达时,才允许mode: partial_overlay;strategy 必须写allow_partial_overlay: true+partial_reason,并说明退回copy的路径。
何时用 slot/patch
使用 slot/placeholder:
- 同一 canonical 正文需要在不同 host 展开不同 path prefix。
- host 需要额外 frontmatter / sidecar,但方法论正文相同。
- host 只支持不同 command/path 语法。
使用 overlay:
- host 需要额外 metadata 文件。
- host 需要 wrapper script。
避免使用 partial_overlay:
- 只是某几段 host 指导不同 → 新增 slot + 两边 overlay。
- 只是 description / trigger 要按 host 改 → frontmatter slot 或 strategy-level description overlay。
- 只是某个 reference 不适用 → 把 reference 的 host 绑定段落 slot 化,或用 host-specific reference include;不要 fork 整个
SKILL.md。 - 解除 stub 时尤其不要先写一份大 partial 顶上——那是在 fork 方法论。先问“这段差异能不能成为 slot”。
使用 body patch 是最后手段;patch 必须可审计、可测试,并记录在 strategy。
验证
每次 projection 改动至少跑:
bash scripts/sync-plugin-dist.sh
bash run-tests.sh
Claude Code adapter 还要跑:
claude plugin validate plugin/dist/claude-code
如果改 Codex adapter,不要假设 ${CODEX_PLUGIN_ROOT};先写 probe 或使用 Codex 文档明确支持的路径策略。
知识 graph 的 compile 消费 / typed change 协议 → design_docs/skill-knowledge-graph + CLI;本 skill 只实现 projection 脚本本身。
