Owner-Friendly Plugin Development

插件“装上了”不是终态。终态是：operator少做了一段机械劳动，同时仍看得懂系统正在做什么、为什么停了、怎样恢复，并且只在真正需要判断时被打扰。

为什么这是一个 Skill

F292 实战连续暴露了通用模型不容易从普通插件教程中得到的边界：公开契约与宿主权威必须分仓但不分叉；monorepo 能掩盖发布包缺依赖；enabled 不能冒充进程健康；认证与修复不能把裸命令甩给用户；真实效用只能由完整旅程证明。具体证据见 F292 case study。

使用边界

• Use：插件跨越 Settings 安装/授权、受监管 runtime、外部事件或数据、Host 路由、Needs Me 或持久用户状态。
• Not for：已有插件怎么配置（guide-interaction）、搭 Codex plugin bundle（plugin-creator）、纯 skill/MCP、一次性 API 脚本、已知内部 bug（debugging）。
• 灰例：无后台生命周期的无状态 transformer，通常只需现有 contract + tdd；只有它仍改变完整用户旅程或 authority boundary 时才加载本 skill。

1. 先冻结被删掉的人类劳动

先写一行 before / after，不先列 SDK 能力：

Before: 人找产物 → 下载/复制 → 找目标 → 补背景 → 请求处理
After: 产物自动出现 → 人只补机器不知道的判断 → 结果回到正确目标

同时冻结三件事：

• 终点：用户少做了哪几步，而不是系统多了哪些模块。
• 人类保留权：身份映射、缺失背景、目标、敏感授权等哪些选择必须由人确认。
• Non-goals：不顺手造新的总结器、事件总线、记忆副本或双向写回面。

设计前读现有插件 contract、catalog/registry、相邻长期集成和 ownership map。已有公共坐标就扩展它；不要在 Host 私造同义 resource，再安排一次迁移。

2. 画清 truth、authority 与 custody

跨边界优先传 bounded metadata + opaque source ref；大正文、secret、家庭记忆和目标句柄各留在自己的 authority domain。插件只报告 observation，不替 Host 作处置决定。

3. 把生命周期拆成五份真相

不要用一个 enabled 包打天下：

artifact: installed / verified / version
config:   incomplete / ready / invalid
auth:     disconnected / pending / connected / expired
intent:   disabled / enabled
live:     dormant / starting / running / degraded / crashed / stopped

关键规则：

• 安装、启动、授权是三件事；安装与 API boot 默认不得偷偷启动外部进程。
• enable 前实时验证 auth，不用缓存的 connected 猜测。
• 进程退出立即投影 crashed 或 stopped；重启若按契约 dormant，就诚实显示 dormant，不能保留“运行中”。
• timeout、abort、shutdown、输出上限与进程树清理都属于监督契约。
• 用户卡片同时展示“想让它运行吗”和“它现在真的在运行吗”，并给下一步动作。

4. 授权和恢复必须留在产品里

插件卡片是 setup、auth、health、repair 的唯一入口；不要让用户复制终端命令或裸 argv。

• Host 只启动 catalog 声明且完整性验证过的 runner；不接受第三方 manifest 自带任意命令面。
• 设备授权只允许供应商固定域名，opaque device secret 留在服务端，页面只显示验证 URL、用户码或 QR。
• 凭据留在既定用户凭据库；Host child env 使用 allowlist，不把 secret 变成插件环境变量。
• regrant、retry、manual import 都回到同一持久记录，不新造第二条流程。
• 每个 degraded state 都配一个具体动作；不能只给“发生错误”。

5. 保护operator的注意力

成功的后台工作应保持安静。Needs Me 只接两类东西：

1. 机器无法可靠决定的用户判断；
2. 需要用户动作才能恢复的失败。

同一来源的 redelivery/restart 必须 reconcile 到同一 durable record。用户可见工作流状态默认持久化；去重是“一个来源一个可见对象”，不是静默丢弃证据。

6. 发布的是运行闭包，不是源码幻觉

发布前从最终 packed artifact 证明：

• catalog pin、manifest、入口文件与 SRI 指向同一不可变字节；
• runtime 依赖在一个空白 consumer 中可解析，不能借 monorepo hoisting、全局安装或 symlink 假绿；
• 解包后的物理成员、入口启动和关键子命令都从发布物运行；
• PR CI 只验证候选，正式 publish 只由受保护分支与最小权限 workflow 触发；
• upgrade/rollback/uninstall 明确哪些配置、凭据和 durable user state 被保留或撤销。

7. 按 claim 选择证据

不要给整个插件贴一个“已测试”标签；逐条 claim 选择机制。完整 dogfood 至少覆盖 discovery → setup → auth → explicit enable → live work → attention/recovery → upgrade/uninstall 中与本插件有关的环节。

完成门

• Before/After 旅程由用户能感知的劳动变化定义。
• ownership map 没有重叠真相源；插件不能选择 Host 目标。
• installed/config/auth/intent/live 分开，所有失败状态诚实且可修复。
• 授权、regrant、诊断从产品入口完成，不要求用户抄命令。
• packed artifact 在 fresh consumer 中可运行，exact bytes 与发布 provenance 可追。
• 契约 claim、运行健康 claim、效用 claim 各有匹配证据。
• 至少一条真实旅程证明机械步骤消失；未 dogfood 就不能宣称产品完成。

Common Mistakes

和其他 Skill 的区别

• plugin-creator：搭 Codex plugin bundle；本 skill 设计有 Host 生命周期与用户旅程的产品插件。
• console-dev：落实 Settings/卡片 UI；本 skill 先定义入口、状态与权威。
• writing-plans / tdd：拆实现并保护行为；本 skill 给它们 journey、state 与 claim contract。
• opensource-ops：处理公共仓 issue/PR；本 skill 定义跨仓插件自身应交付什么。
• quality-gate：汇总交付证据；本 skill 定义插件特有的完成证据。

下一步

新产品能力先进入 feat-lifecycle；边界冻结后用 writing-plans，行为实现用 tdd，Settings 体验用 console-dev，公共仓交付用 opensource-ops，收口用 quality-gate。