版本与兼容

生态的地基是"接口不会半夜变"。所以版本策略必须先于功能定下来。

版本号

• core 使用 0.x，协议标识为 v0；
• 破坏性变更必须升 minor（0.1 → 0.2），并在 CHANGELOG 里写清楚迁移方式；
• 修复类变更走 patch，每周可发；
• 任何"语义悄悄改了但版本没变"的提交，一律回滚。

skill 声明协议版本

{
  "name": "downloads-cleanup",
  "version": "0.1.0",
  "protocol": "0",
  "entry": "./index.ts"
}

内核加载时校验 protocol：

• 完全匹配：正常加载；
• 主版本不匹配：拒绝加载，并在 UI 上提示"该 skill 需要更新"；
• 字段缺失：按当前版本处理，但打印弃用警告。

破坏性变更流程

1. 提 RFC（放在 rfcs/ 下），写清楚：改什么、为什么、影响哪些 skill、怎么迁移；
2. 至少 7 天讨论期；
3. 实现时同时提供兼容层或迁移脚本；
4. 发布时在 CHANGELOG 顶部给出"三步迁移指南"。

协议以数据形式冻结

spec/protocol-v0.json 是契约：动作种类、必填字段、断言种类、撤销种类、能力清单、日志字段、清单字段，以及五条不变式。packages/core/src/protocol.ts 里是同一份清单的运行时常量，scripts/protocol-freeze-test.ts 只要发现两边不一致就报错——包括"加了一个 kind 却忘了升版本"。

spec/fixtures/v0-legacy-sample.json 是冻结当天写下的黄金动作序列；scripts/compat-test.ts 会执行它、撤销它，并断言目录回到空。任何让这条测试失败的内核改动，按定义就是破坏性变更。

快照测试

每个 skill 在 CI 里跑两件事：

• 预览快照：固定输入必须产出固定计划（防止内核升级悄悄改变行为）；
• 回滚测试：执行后撤销，文件系统状态必须与执行前逐字节一致。

这是防止"内核升级把别人的 skill 搞坏"的最后一道闸。

弃用策略

• 标记 @deprecated 后至少保留两个 minor 版本；
• 弃用期间运行时打印一次警告，不阻断；
• 移除时必须提供 codemod 或迁移文档。

目录约定

rfcs/          提案
docs/          对外文档（本站）
CHANGELOG.md   变更记录

生态项目最贵的资产不是代码，是"别人敢不敢依赖你"。版本纪律就是这个资产本身。