目录 · 级别：参考
Solutions 知识库
所有 72 条已沉淀的学习笔记，位于 docs/solutions/ 下，按类别分组。每条记录包含：标题、日期、类别、问题类型以及一行摘要。
知识库是如何写入的
ce-compound 用于写入新的学习笔记。ce-compound-refresh 用于维护已有的笔记（Keep / Update / Consolidate / Replace / Delete）。两者共用同一份 YAML schema。CONCEPTS.md 与 docs/guides/packs.md 是下游消费者。
Solution 分类
本插件站在最终用户（即使用本插件的开发者）的视角对 solution 进行分类，而非贡献者视角：
- developer-experience/ — 涉及给本仓库做贡献的问题（本地开发、CI、shell 别名、测试体验）
- integrations/ — 插件输出在目标平台上失效的问题
- workflow/ — 发布自动化、Compound Packs、多 PR 协作
- skill-design/ — 技能/Agent 编写、提示词模式、跨平台可移植性
72 条 solution — 索引
完整文件路径相对于 docs/solutions/。
skill-design/ — 44 个文件（最大）
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
anti-poll-scope-and-async-subagent-dispatch.md | 2026-07-21 | 85 | 反轮询规则同样适用于已分离的 CLI 委托；需观察子 agent 返回结构。 |
arguments-token-is-claude-only-in-skill-bodies.md | 2026-06-26 | 54 | $ARGUMENTS 仅在 Claude Code 的 SKILL.md 内部替换；从 prompt 推导。 |
authored-eval-corpora-contain-the-happy-path.md | 2026-08-13 | 62 | 手工构建的 eval 反而会漏掉它本想捕捉的失败模式。 |
authoring-auto-invoke-standing-instructions.md | 2026-07-12 | 59 | 从 AGENTS.md 自动调用兄弟技能的模式。 |
benchmark-review-peer-model-and-reasoning-tier.md | 2026-07-18 | 190 | 用真实 bug 衡量同侪模型；区分"检测"与"断言"两种裁判。 |
bound-contradiction-checks-to-named-guidance.md | 2026-08-15 | 39 | ce-compound-refresh 与该笔记点名的指导文件做对比。 |
bundled-script-path-resolution-across-harnesses.md | 2026-06-26 | 52 | 读取走相对路径；执行脚本需用 SKILL_DIR 锚点。 |
ce-doc-review-calibration-patterns.md | 2026-04-19 | 56 | 分级分类、schema 提示、差异处理。 |
cli-output-buffering-for-progress-detection.md | 2026-07-20 | 137 | 缓冲区破坏了"这个 worker 真的前进了吗？"的判断。 |
confidence-anchored-scoring.md | 2026-04-21 | 51 | 用锚定评分取代连续浮点；评分量表说了算。 |
context-absent-skill-handoff-needs-pinned-invocation.md | 2026-07-31 | 62 | 跨技能交接中，技能工具调用优于纯文本说明。 |
cross-harness-cross-model-tool-invocation.md | 2026-07-11 | 77 | 描述能力、通过运行验证 — 不要点名具体工具。 |
detached-job-lifecycle-for-delegated-work.md | 2026-07-14 | 128 | setsid double-fork、持久任务状态、亚秒级轮询、原子化终态。 |
detector-that-cannot-decide-should-rank-not-assert.md | 2026-09-01 | 60 | 不断发现新边界情况的启发式应当排序而非断言。 |
dispatch-script-failure-degrade-outcome-not-boundary.md | 2026-07-18 | 58 | 脚本强制一条边界；失败应降级结果而非边界本身。 |
git-workflow-skills-need-explicit-state-machines.md | 2026-03-27 | 61 | 一道闸门改了六版；正解是状态机，而非更多命令。 |
harness-agent-gate-workaround.md | 2026-07-28 | 50 | 防御性的技能 workaround 在退出条件满足时就该退役。 |
inline-callee-side-channel-must-name-where-it-may-not-land.md | 2026-09-13 | 94 | 调用方的旁路规则必须指明它不能落到哪里。 |
invocation-opt-out-flags-block-sibling-skill-invocation.md | 2026-09-08 | 75 | disable-model-invocation 会在所有宿主上拦截兄弟技能。 |
liveness-judgment-belongs-to-the-agent.md | 2026-09-01 | 71 | 存活标记只证明工作已启动；判断是否完成是 agent 的职责。 |
multi-surface-output-needs-a-shared-rendering-floor.md | 2026-07-23 | 42 | 所有表面共享一份"决策优先"的 findings 契约。 |
named-frameworks-with-detection-conditions-for-review-personas.md | 2026-08-30 | 82 | 引用 OWASP / Fowler / Release It! 中的具体异味；不要写"以 X 视角评审"。 |
new-knowledge-source-re-derives-persona-gate-and-route.md | 2026-09-08 | 72 | 向一个受闸门控制的 reviewer 添加 packs 会重新推导闸门。 |
paired-old-vs-new-injection-skill-evals.md | 2026-07-01 | 138 | eval 配方：成对参考、盲注入、倒置的真实 bug。 |
pass-paths-not-content-to-subagents.md | 2026-03-26 | 39 | 编排器负责 glob，子 agent 负责读取。 |
portable-agent-skill-authoring.md | 2026-07-11 | 507 | 权威的技能编写标准；在仓库各处被引用。 |
post-menu-routing-belongs-inline.md | 2026-04-28 | 68 | 不要把菜单式路由放进模型根本不会打开的 reference。 |
prose-cannot-validate-caller-control-data-byte-for-byte.md | 2026-08-21 | 116 | 模型会"修复"格式错误的载体；校验应放在打包器处。 |
quiet-interval-floors-for-streaming-peer-routes.md | 2026-07-30 | 72 | stream-json 同侪路由的 CROSS_MODEL_IDLE_SECS 下限。 |
requested-vs-verified-model-identity.md | 2026-07-14 | 50 | 把"跑的是哪个模型"视为需要凭证的主张。 |
review-cost-is-in-entering-the-spine-not-the-findings.md | 2026-09-15 | 52 | 评审的规模应按后果衡量，而非按"总行数"下限。 |
size-driven-skill-restructure.md | 2026-08-17 | 99 | ce-babysit-pr 从 90KB 瘦身到 8KB；如何在不丢不变量的前提下压缩。 |
skill-gates-state-conditions-not-prescribed-git-commands.md | 2026-08-15 | 101 | 同一道发布闸门改了六版；正解是把条件写出来。 |
state-the-condition-not-a-placement-absolute.md | 2026-08-28 | 85 | "条件 + 位置硬性规定"的代理规则一旦重复就会开始禁止其条件所要求的做法。 |
strong-models-mask-defensive-skill-fixes.md | 2026-07-09 | 57 | 强模型下"加技能 vs 基线"打平，并不证明该修复有用。 |
subordinate-the-failing-shape-to-the-condition.md | 2026-08-24 | 53 | 在无法实例化的宿主上如何让条件仍然清晰。 |
watch-loops-need-a-blocked-external-terminal-state.md | 2026-07-11 | 55 | 看护循环需要第三种终态：blocked-external。 |
workspace-isolation-is-escalation-not-entry-fee.md | 2026-08-31 | 58 | 隔离是给"必须提交"的 worker 准备的，并非并行的默认。 |
developer-experience/ — 7 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
always-on-agents-md.md | 2026-09-12 | 95 | 始终加载的 AGENTS.md 与按任务加载的 reference 各自归属什么。 |
bun-parallel-worker-loses-subprocess-exit.md | 2026-09-11 | 63 | 针对 oven-sh/bun#34069 的 workaround — 仅串行重跑 TimeoutError 文件。 |
codex-local-skill-development-workflow.md | 2026-07-16 | 56 | codex:dev local|status|remote|remove 工作流，以及为何用 marketplace 安装是错的。 |
gitlab-ci-upstream-baseline-refs-unreachable.md | 2026-09-09 | 106 | 浅克隆的 GitLab 为何会让 skill-eval-cell 失效，以及如何修复。 |
gitlab-main-only-jobs-first-run-post-merge.md | 2026-08-29 | 133 | 仅在默认分支上跑的作业在合并前没有演练机会。 |
global-fsmonitor-makes-the-suite-slow-and-flaky.md | 2026-09-08 | 65 | 关闭 core.fsmonitor；220s 对 85s；在 20s 处被杀死。 |
porting-github-actions-gates-to-self-hosted-gitlab-ci.md | 2026-08-28 | 139 | 如何在网络受限 + 自签名 TLS 的自托管 runner 上落地 CI 闸门。 |
best-practices/ — 4 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
codex-delegation-best-practices.md | 2026-04-01 | 70 | 把任务委托给 Codex 的成本经济学；批处理、何时委托。 |
predictable-tmp-cache-ownership-check.md | 2026-06-29 | 46 | 以 /tmp 中已知路径为键的缓存可被本地协作者预先创建。 |
prefer-python-over-bash-for-pipeline-scripts.md | 2026-04-09 | 47 | 编排两个以上 CLI 的流水线脚本应选 Python 而非 bash。 |
preserve-user-content-across-all-destructive-paths.md | 2026-07-09 | 80 | Pi writer 曾覆盖用户的符号链接，因为守卫只覆盖了其中一条路径。 |
conventions/ — 4 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
antigravity-target-empirical-format-verification.md | 2026-06-23 | 117 | agy 文档在客户端渲染；必须以二进制为准做校验。 |
resolve-python-interpreter-not-python3.md | 2026-07-24 | 125 | 硬编码的 python3 在 Windows 上会失败；请探测执行能力。 |
shell-primitives-must-be-executed-not-shape-checked.md | 2026-07-30 | 121 | 通过实际执行来测试 shell 原语，而不是断言它"存在"。 |
verify-externally-attributed-constraints-at-the-source.md | 2026-08-21 | 109 | 每条归因于外部的数值约束都要给出 spec/原始来源。 |
integrations/ — 3 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
agent-plugins-schema-is-a-host-routing-switch.md | 2026-08-17 | 40 | 根 plugin.json 上的 $schema 字段决定 Codex 与 omp 的解析路径。 |
cross-platform-model-field-normalization.md | 2026-03-29 | 54 | 为何转换器不能依赖裸的 model: sonnet。 |
native-plugin-install-strategy.md | 2026-06-19 | 50 | 对原生支持插件的宿主，只发元数据即可，不必提供转换器。 |
integration-issues/ — 2 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
grok-camelcase-structuredoutput-and-nonfinal-peer-position.md | 2026-08-15 | 55 | Grok 会输出 .structuredOutput 并可能在占位符上 finalize。 |
portable-structured-output-schemas-across-model-clis.md | 2026-07-15 | 50 | 哪些能扛住不同 provider 的 schema 差异；暴露 provider 启动期诊断。 |
workflow/ — 5 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
manual-release-please-github-releases.md | 2026-03-17 | 53 | 何时放弃 release-please；release PR + GitHub Release 流程如何运转。 |
measuring-a-packs-effect-needs-non-inferable-rules.md | 2026-09-09 | 85 | Pack 只有在其规则不可被推断时才"复利"；token 效应因模型而异。 |
release-please-version-drift-recovery.md | 2026-04-24 | 161 | 由直接 push 造成的版本漂移如何通过多 PR 恢复。 |
reviewing-byte-duplicated-shared-assets.md | 2026-07-24 | 26 | 告诉评审者哪一份是规范的；并说明这种重复就是事实。 |
stale-local-base-contamination.md | 2026-04-27 | 39 | 堆叠 PR / 多会话分支创建如何变得陈旧。 |
root — 2 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
adding-converter-target-providers.md | 2026-02-23 | 34 | 过去每个目标平台踩过的坑（双重嵌套、名称归一化……）。 |
agent-friendly-cli-principles.md | 2026-03-26 | 52 | "没有产物"不是错误 — 在面向 Agent 的 CLI 中要区分"缺失"与"失败"。 |
architecture-patterns/ — 1 个文件
| 标题 | 日期 | 行数 | 一句话摘要 |
|---|---|---|---|
posix-process-supervision-on-native-native-w.md | 2026-07-24 | 252 | 把 POSIX 进程监管移植到原生 Windows Python 时哪里会出问题（进程组、锁、所有权、原子重命名、PID 复用）。 |
按类别快速查找
如果你想要解决某一类具体问题：
| 问题 | 对应 Solution |
|---|---|
| 技能语句总被逐例打补丁 | state-the-condition-not-a-placement-absolute.md |
| 发布闸门反复加规则还是失败 | skill-gates-state-conditions-not-prescribed-git-commands.md |
| 技能瘦身但不变量持续外泄 | size-driven-skill-restructure.md |
| 评审者反复挑同一段刺 | bound-contradiction-checks-to-named-guidance.md |
| 看护循环虚警 / 漏报已完成 | liveness-judgment-belongs-to-the-agent.md + watch-loops-need-a-blocked-external-terminal-state.md |
| CI 修复在失败之间反复横跳 | dispatch-script-failure-degrade-outcome-not-boundary.md |
| 跨技能交接变得不可见 | context-absent-skill-handoff-needs-pinned-invocation.md |
| 跨宿主调用失灵 | cross-harness-cross-model-tool-invocation.md |
| 分离任务需要生命周期管理 | detached-job-lifecycle-for-delegated-work.md |
| 新增 persona 改变了 spawn 闸门 | new-knowledge-source-re-derives-persona-gate-and-route.md |
| 工作区隔离带来不必要的成本 | workspace-isolation-is-escalation-not-entry-fee.md |
| 流水线输出缓冲在进度上撒谎 | cli-output-buffering-for-progress-detection.md |
| Python 脚本在 macOS bash 3.2 上炸 | prefer-python-over-bash-for-pipeline-scripts.md |
为 ${CLAUDE_PLUGIN_ROOT} 写的脚本在非 Claude 宿主上坏掉 | bundled-script-path-resolution-across-harnesses.md |
/tmp 中的符号链接争用 | predictable-tmp-cache-ownership-check.md |