Proposal: 可移植的 Evolved Skill 导入/导出协议

[JadeeeZh]

Hi @hetaoBackend —— 我看了 #1865 和已经合并的 #1874。DeerFlow 在自定义 Skill 生命周期上的设计，与我们在 EverOS 正在探索的 procedural memory 路线比较接近。不过相比于重复实现彼此已有的能力，我觉得更有价值的合作方向可能是 Skill 的可移植性（portability）。
不知道 DeerFlow 是否会考虑定义一个小而稳定的 evolved skill 导入/导出协议？例如包含 SKILL.md、provenance（来源信息）、version history（版本历史）、confidence（置信度）以及 promotion state（晋升状态） 等元数据，并提供一个 DeerFlow 与 EverOS 之间可往返（round-trip）的测试用例。
我们可以先把 schema 和测试约定出来，不需要 DeerFlow Core 依赖 EverOS。如果这个边界符合 DeerFlow 的发展方向，我们也很乐意通过 PR 的形式实现对应的 adapter。

[hetaoBackend]

感谢认可，也很高兴看到 DeerFlow 和 EverOS 在 procedural memory / evolved skill 方向上有相近的探索。这个合作方向我们觉得完全 OK：先定义一个小而稳定、且不要求 DeerFlow Core 依赖 EverOS 的导入/导出 contract，是一个很合理的边界。

欢迎你们先 propose 一版 contract/schema，以及对应的 round-trip 测试约定。我们可以基于具体 proposal 一起讨论字段、兼容性和演进方式，再进一步推进 adapter PR。期待合作！

[JadeeeZh]

@hetaoBackend 感谢确认方向并明确画出边界。按之前讨论的，我们（EverOS 侧）先给出 v0.1 的契约/schema，往返测试约定和逐字段的开放问题放在下方跟帖。

提案复用你们现有的 .skill（ZIP），在 skill 目录内新增一个可选的单文件 sidecar，承载 SKILL.md 表达不了的元数据（来历 / 改动历史 / 可信度 / 提升状态）。SKILL.md 逐字节不变，DeerFlow Core 不解析 sidecar，adapter 全部在边缘。

有两个前置需要确认下，如有理解偏差请指正：

1. 归档里的 dot-file 在安装时不会被过滤（should_ignore_archive_entry 只用于从解压目录顶层挑出 skill 根目录），所以 dot 前缀的 sidecar 放在 <skill_name>/ 内是安全的。
2. Core 目前似乎没有导出能力（routers/skills.py、installer.py、skill_storage.py 里没找到打包 .skill 的路径）。如果是这样，adapter 会顺带把导出做出来，sidecar 的附着也在导出时完成，Core 不需要对任意未知文件做任何承诺。

契约形态

不新增传输格式、不改归档结构、不碰 SKILL.md 的 frontmatter（因此 validation.py 的字段白名单完全不受影响）：

.skill (ZIP)
└─ <skill_name>/                # 也是 skills/{public,custom}/<skill_name>/
   ├─ SKILL.md                  # 必需、逐字节不变（有 fixture 覆盖）
   ├─ references/ scripts/ …    # 不改动
   └─ .skill-meta.json          # 新增：可选、单文件

sidecar 位置绑定，只标注它所在的那个目录，多 skill 包各带一份。dot 前缀对齐你们 custom/.history/ 的惯例，目录遍历器和 SKILL.md loader 会像跳过任何隐藏项一样跳过它。读取方用 stat() 探测即可，不需要任何标记位，所以 SKILL.md 不变这一点是无条件成立的。

Schema 速览（v0.1）

{
  "spec": "portable-evolved-skill",
  "spec_version": "0.1",

  "skill": {
    "id": "01K3F7QW8XJ2Y5N0ABCDEF",   // 不透明稳定标识
    "name": "fix-pg-migration",
    "tier": "public|custom|legacy",   // 对齐 SkillCategory 三态
    "body_hash": "sha256:…",
    "body_hash_algo": "sha256"
  },

  "provenance": {                      // 必需块
    "origin_system": "everos",
    "exported_at": "2026-07-24T09:00:00Z",
    "source_ref": "…",                                  // 可选
    "derived_from": [ { "id": "…", "system": "…" } ]     // 可选，血缘
  },

  "confidence": {                      // 可选、只读、仅参考
    "state": "known|unknown",
    "score_permille": 820              // 整数千分比，整个 manifest 禁用浮点
  },

  "promotion": { "state": "draft|custom|candidate|public|deprecated" },

  "version_history": {                 // 可选、有界确定性尾部
    "authoritative_store": "…",        // 声明权威全量日志在谁那儿
    "truncated": true,
    "entries": [ { "ts": "…", "action": "…", "author": "agent|human", "summary": "…" } ]
  },

  "x-everos": { }, "x-deerflow": { }   // 命名空间厂商扩展
}

必填核心只有 spec / spec_version / skill / provenance，其余全部可选；没有 sidecar 的普通 skill 依然 100% 有效，缺失永不报错。核心对象一律 additionalProperties:false + 封闭枚举，唯一的加法通道是 x-* 桶。

关于skill.id：我们加了一个不透明稳定标识，而不是只用 (tier, name) 复合键。主要是因为如果改skill名字会让基于名字的 derived_from 血缘链断掉，而且你们已经引入了用户隔离（storage/user_scoped_skill_storage.py、router 侧的 get_effective_user_id），同一个 (custom, name) 在不同用户下会各有一份。如果你们更希望身份就用 (tier, name)、映射表由 adapter 自己维护，也可以，我们可以讨论下。

信任边界（写成规范性规则）

这部分我们主动写严，因为协议搬运的是 agent 生成的可执行内容：

• 外部来源导入时，promotion.state 强制降为 custom，绝不接受 public 或 candidate，原值可保存在 x-deerflow 里以便恢复。
• confidence 只作只读展示，不参与任何加载或排序决策。跨系统口径不可比也无法核实，所以不给它任何有后果的权力。
• 各自的本地历史始终是唯一权威日志、只本地追加，绝不回灌外部历史。
• provenance 与 confidence 一律不绕过、不降级你们现有的静态扫描与 LLM 安全扫描。sidecar 是纯数据，照走现有 zip 防护。
• body_hash 只是漂移信号：不匹配时只发警告，绝不阻止安装、绝不改写 SKILL.md。 主体是权威，附带元数据对它没有否决权。

下一步

想我们一起先确认下范围与边界：这份契约是否落在你要保护的边界内（Core 零新增承诺、SKILL.md 不动、adapter 在边缘、无网络依赖）。字段层面的意见欢迎讨论，

Schema确定后我们可以再推进adapter PR，我们可以把 SPEC、schema、fixtures 和校验 CLI 整理成一个仓库请你们review。adapter 具体放哪里（e.g. 合进你们仓库、独立包、或者纯外部 CLI 操作/你们不接手代码）都可以之后再讨论

[dani1005]

Thanks @JadeeeZh & @hetaoBackend, excited for this collaboration! 🙌
我添加一些我们在EverOS测做设计时的思考，欢迎大家一起讨论

一些设计思考

1. 前向兼容只有一条路。 新字段先放在 x-everos / x-deerflow 这类厂商私有桶里，不进核心、不做兼容承诺。某个字段被证明普遍有用之后，再把它移入标准核心，这一步需要发布新的 schema 版本（0.1 → 0.2，每个版本一个独立 schema 文件，旧读取方继续用旧文件校验）。读取方按 spec_version 选 schema，遇到更高版本不硬失败，只校验已知核心、其余原样保留。这样「封闭小核心」和「旧读取方容忍新数据」就不再冲突。

2. 确定性，跨语言逐字节可复现。 manifest 用 RFC 8785 (JCS) 规范化；时间戳固定 YYYY-MM-DDThh:mm:ssZ（UTC、字面 Z、无小数秒）；所有字符串、路径、正文先做 NFC 归一。

整个 manifest 禁用浮点。 JCS 虽然规定了数字的序列化写法，但各语言实现是否严格照做不好保证（比如整数值的浮点，有的输出 1、有的输出 1.0），一处不一致就破坏逐字节可复现。所以 confidence 不写 0.82，而是用整数千分比写成 820。

3. body_hash 只覆盖正文。 hash = 去掉 frontmatter 后的正文，先做 NFC + CRLF→LF，不裁剪行尾空白（Markdown 硬换行就是行尾两个空格，裁掉会静默改变排版）。这样「只改元数据」不会误判漂移，真改了正文才触发。adapter 永不改写 SKILL.md。

4. 往返比较用掩码。 exported_at / origin_version / last_evaluated_at 每次导出必然变化，恒等性比较时排除，其余字段逐字段稳定。

往返测试约定

在 .skill 归档层面验证，不需要起 gateway、不需要跑 agent。export(import(X)) ≡ X，等价关系如下。

MUST

• SKILL.md 正文逐字节一致
• name / description / allowed-tools / required-secrets / secrets-autonomous 语义不变
• skill.id 不变
• 未知字段原样保留（x-* 内部，以及未来版本引入的核心字段）
• 支持文件树不变：同路径、同字节
• 无 sidecar 的普通 skill 往返后不得凭空长出 sidecar
• 声明了更高 spec_version 的包，必须能只靠 SKILL.md 成功导入，只发警告

SHOULD

• version_history 条目顺序不变、不丢失，未知 action 原样保留
• derived_from 每跨一个系统只加一跳，链保持无环
• 版本号非递减

MAY，明确许可的不一致

• 导入方可以把 confidence.state 置为 unknown 并清空分数，因为它无法核实其他系统的口径。若选择保留，则不得上调分数。
• 导入方可以下调 promotion.state。

坏输入必须降级而非失败。 sidecar JSON 损坏、历史文件末行截断、缺 id、spec 块类型不对，全部只发警告并照常安装 skill。绝不因为附带元数据有问题而拒绝一个本身正常的 skill。

Golden vectors。 6 套确定性生成的 fixture（最简 / 全字段 / 带 scripts / 长历史 / CJK+emoji+CRLF / 未知字段与未来版本号）checked in 到规范仓，两边跑同一套、输出必须一致。这是「互通」的实际保证，否则只能证明各自内部自洽。

与你们现有模型的对应

• version_history.action 对齐 skill_manage 的动作集：create / patch / edit / delete / write_file / remove_file，加上 gateway 的 rollback，另加 distill / import / promote 供互操作。权威全量日志仍留在各自原生存储（你们侧是 custom/.history/<name>.jsonl，每个 skill 一个文件），sidecar 只带确定性有界尾部：保留 create 加最近 N-1 条，按 (ts, seq) 升序，带 truncated 标记。
• skill.tier 直接对齐 SkillCategory 的 public / custom / legacy。legacy 我们理解为用户隔离迁移前的只读全局 skill（挂载在 /mnt/skills/legacy/），因此它是位置而不是信任级别，没有放进 promotion.state。
• promotion.state 映射 custom/ ↔ public/；draft / candidate / deprecated 是面向 Phase 3 的前瞻状态，只支持降为 custom/ 的实现把原值保存在 x-deerflow 里，可恢复。
• derived_from 对应 EverOS 的 skill ← cases ← trajectories 蒸馏链；你们侧没有原生槽位时原样透传即可。

开放问题

1. skill.id 是否需要，还是身份完全由 (tier, name) 决定？
2. confidence 是否值得进协议？它不可核实、跨系统口径不可比，而且我们已经规定它不参与决策。真正重要的是 provenance 和 version_history，那两个是客观事实。
3. version_history 的有界尾部保留 N 条，N 定多少合适？sidecar 体积和信息量之间的权衡想听你的经验。
4. sidecar 放在 <skill_name>/ 内部、用 dot 前缀，这个位置和命名你们是否接受？
5. 安全扫描把 sidecar 视为惰性数据（不解析内容语义，只受 zip 防护约束），这个定位对吗？
6. v0.1 我们把签名与资源完整性块整体推迟了（未签名永远合法）。如果你们对 skill 分发的真实性有更强要求，可以提前进 0.2 的讨论。