RFC: Skill Evolution Host APIs / Skill 自演进宿主接口 #5646

English

Summary

Add a P0 host contract that lets trusted extensions build Skill evolution workflows without giving each plugin its own unsafe filesystem and run-history implementation.

DeerFlow supplies bounded completed-run evidence, immutable candidate staging, validation, compare-and-swap publication, recovery, and rollback. A plugin supplies the learning policy, candidate generation, evaluation, and trigger strategy.

This RFC follows the Skill Self-Evolution proposal in #1865 and the extension direction in #5539. It does not include a learning plugin.

Problem

Existing extensions can read broad run history and call legacy Skill writers, but that is not sufficient for unattended evolution:

• A terminal run status does not prove all evidence was durably recorded.
• A plugin can race with human or legacy writes and silently overwrite them.
• A process crash between file replacement and database updates leaves ambiguous state.
• Plugin removal must not remove the host's ability to recover accepted publications.
• Candidate validation needs durable cost limits and must never activate staged content.

Proposed contract

Two optional extension dependencies are bound by the host to the real plugin source:

1. completed_run_evidence exposes owner-scoped, sealed snapshots with a fixed event watermark and bounded pagination.
2. skill_mutations exposes read, stage, inspect, check, commit, query, discard, and revert operations for explicitly granted owners, agents, operations, and existing Skill names.

Both dependencies default to unavailable. Operator-controlled grants are required; plugins cannot choose another plugin identity or use wildcard grants.

Key decisions

1. Candidate and publication are separate

Staging stores an immutable baseline and candidate outside Skill loading paths. The plugin may evaluate that exact bundle, but the host always performs current-policy validation before publication.

2. P0 updates existing Skills only

P0 may change only the body and description of an existing, enabled, user-custom SKILL.md. It cannot create, rename, delete, toggle, or modify support files. Creation has separate visibility, permission, shadowing, and rollback semantics and is deferred.

3. Publication uses asset CAS

Each managed Skill has an incarnation, monotonically increasing mutation sequence, and whole-package digest. Manual edits, support-file edits, enable changes, and delete/recreate invalidate stale candidates, including A→B→A changes.

4. Accepted writes are recoverable

Before replacing bytes, DeerFlow persists a PREPARED operation with before/after packages and reserved versions. Recovery classifies disk state:

• matches before → ABORTED;
• matches after → finalize APPLIED exactly once;
• matches neither → NEEDS_REPAIR, without overwriting possible human work.

Publication and derived-view readiness are separate states. A view failure does not turn committed bytes into an ordinary failed request.

5. Recovery belongs to the host

Startup and periodic recovery use persisted owner enrollment, independent of whether the originating plugin is still enabled or installed. One owner's filesystem/lock failure must not block Gateway startup or unrelated owners. Admin APIs can query and retry reconciliation but cannot force-overwrite.

6. Safety is bounded, not sandboxed

Static and model-based scans fail closed. File count, byte size, scan concurrency, hourly attempts, proposal lifetime, and rollback retention are bounded durably. Normal logs exclude candidate contents and raw model errors.

Python extensions remain trusted in-process code. These APIs reduce mistakes and constrain supported behavior; they do not isolate a malicious plugin or prove learning quality.

7. P0 automatic publication is single-host

Supported topology is POSIX single-host local storage: one Gateway process with SQLite, or same-host PostgreSQL workers sharing the same local Skill storage and file locks. Multi-node, NFS/CSI, and out-of-band filesystem writers are unsupported.

Compatibility and operations

• Existing extension dependencies and the older run-evidence reader remain compatible.
• The public extension API advances from 0.2.1 to 0.2.2.
• Schema changes are additive. All managed writers must be upgraded together before grants are enabled.
• Disabling a plugin stops new plugin work but keeps host recovery available.
• Do not downgrade while an operation is PREPARED or NEEDS_REPAIR.

Non-goals

• Learning strategy, reflection prompts, evaluator, background queue, or model choice.
• Skill creation/deletion/rename, support-file mutation, or enabled-state changes.
• Frontend review UI or plugin marketplace.
• Multi-node publication or hostile-plugin isolation.
• Automatic deletion of information already distilled from a deleted conversation.

Validation required

• Evidence isolation, sealing, fixed watermarks, retention invalidation, and deletion races.
• Human/legacy writer conflicts, A→B→A, idempotency, cancellation, and source deletion.
• Process termination at every durability boundary and repeated recovery.
• Plugin disable/removal, owner-local recovery isolation, and admin repair.
• SQLite regression coverage and live same-host PostgreSQL concurrency before enabling PostgreSQL publication.

Implementation PR: #5645

中文

结论

为可信插件增加 P0 Skill 自演进宿主契约，避免每个插件自行读取无界运行历史、直接写文件并处理崩溃恢复。

DeerFlow 负责有界任务证据、不可变候选、校验、CAS 发布、恢复和撤回；插件负责学习策略、候选生成、效果评估和触发方式。

本 RFC 承接 #1865 的 Skill Self-Evolution 目标和 #5539 的扩展方向，但不包含学习插件。

当前问题

现有插件能读取较宽泛的运行历史，也能调用旧 Skill 写接口，但不足以支撑无人值守演进：

• 运行状态结束不代表所有证据已可靠落盘。
• 插件可能与人工或旧写路径并发，静默覆盖新内容。
• 文件替换与数据库更新之间进程退出，会留下不确定状态。
• 插件卸载后，宿主仍必须能恢复已经接受的发布。
• 候选校验需要持久限额，且暂存内容不能被 Agent 加载执行。

宿主契约

宿主按真实插件来源绑定两个可选依赖：

1. completed_run_evidence：提供用户范围内、已封口、固定事件水位的有界证据快照。
2. skill_mutations：为明确授权的用户、Agent、操作和已有 Skill 提供读取、暂存、检查、提交、查询、丢弃和撤回。

两个依赖默认都不可用。授权由部署者配置；插件不能伪造其他插件身份，也不支持通配授权。

关键设计

1. 候选与发布分离

暂存阶段把基线和候选保存到 Skill 加载目录之外。插件可以评估这份精确内容，但正式发布前宿主始终按当前策略重新校验。

2. P0 只更新已有 Skill

P0 只能修改已存在、已启用的用户自定义 SKILL.md 的正文和描述。不支持创建、重命名、删除、启停和支持文件修改。创建涉及可见性、权限、同名遮蔽和撤回语义，留到独立阶段。

3. 发布使用资产级 CAS

每个受管 Skill 记录实例 ID、单调递增版本和完整包摘要。人工修改、支持文件变化、启停和删除重建都会使旧候选失效，包括 A→B→A。

4. 已接受的写入必须可恢复

替换文件前，DeerFlow 持久化 PREPARED 操作、前后包和预留版本。恢复时比较磁盘状态：

• 等于 before：记为 ABORTED；
• 等于 after：只完成一次 APPLIED；
• 两者都不等：进入 NEEDS_REPAIR，不覆盖可能存在的人工修改。

发布状态与派生视图就绪状态分离。视图失败不能把已经提交的文件伪装成普通失败。

5. 恢复属于宿主

启动和周期恢复依赖持久化的用户纳管状态，不依赖原插件仍被启用或安装。单个用户的文件或锁异常不能阻止 Gateway 启动，也不能影响其他用户。管理员接口只能查询和重试协调，不能强制覆盖。

6. 安全是有界控制，不是插件沙箱

静态和模型扫描失败即拒绝。文件数量、字节数、并发扫描、小时次数、候选有效期和撤回保留期都有持久限额。普通日志不记录候选正文和原始模型错误。

Python 插件仍是进程内可信代码。新接口用于防误用和约束受支持行为，不隔离恶意插件，也不证明学习效果。

7. P0 自动发布仅支持单宿主

支持 POSIX 单宿主本地存储：SQLite 单 Gateway 进程，或 PostgreSQL 同宿主 worker，共享同一份本地 Skill 存储和文件锁。不支持多节点、NFS/CSI 和绕过受管接口直接写文件。

兼容与运维

• 现有扩展依赖和旧运行证据读取接口保持兼容。
• 公共 extension API 从 0.2.1 升级到 0.2.2。
• 数据库迁移只新增结构。启用授权前，必须一起升级所有受管写进程。
• 停用插件会停止新的插件工作，但不会关闭宿主恢复。
• 存在 PREPARED 或 NEEDS_REPAIR 操作时不能降级。

不在本期范围

• 学习策略、反思 Prompt、评估器、后台队列和模型选择。
• Skill 创建、删除、重命名、支持文件修改和启停。
• 前端审核界面或插件市场。
• 多节点发布或恶意插件隔离。
• 删除会话时自动删除已经沉淀到 Skill 的信息。

验收要求

• 证据隔离、封口、固定水位、保留失效和删除并发。
• 人工/旧写路径冲突、A→B→A、幂等、取消和来源删除。
• 每个持久化边界的进程退出与重复恢复。
• 插件停用/卸载、单用户故障隔离和管理员修复。
• SQLite 回归；启用 PostgreSQL 发布前必须完成同宿主并发实测。

实现 PR：#5645