如何编写Raven插件MemoryBackend契约与四源发现机制开发者完全指南【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/RavenRaven 是一个可信、持久、自我进化的多智能体生态系统而它的插件体系是扩展能力的关键你不需要修改任何宿主代码只要实现一套 MemoryBackend 契约、写一份插件清单就能把自己的记忆后端接入 Raven。本文是一份面向新手的完整指南带你快速吃透编写 Raven 插件的两把钥匙——MemoryBackend 契约与四源发现机制并给出一份可直接落地的开发清单 ️ 30 秒看懂契约 发现 免改动接入Raven 的插件框架只有两个核心部件部件位置作用MemoryBackend 契约raven/contracts/memory.py定义所有记忆插件必须实现的 8 个方法四源发现机制raven/plugins/discover.py从 4 个来源扫描插件清单按优先级去重理解这两个部件你就理解了整套插件架构。官方架构文档在 docs/memory-plugin-architecture.md建议作为进阶读物。 第一步读懂 MemoryBackend 契约契约是一个runtime_checkable的 Protocol见 raven/contracts/memory.py#L142-L332共8 个方法按热路径优先级排列方法何时被调用可以偷懒吗recall每一轮对话组装上下文时❌ 核心方法store每轮对话结束后持久化❌ 核心方法feedback技能被注入后回收信号✅ 允许空实现start/stop启动 / 关闭生命周期需幂等healthraven doctor诊断时可返回Nonedelete用户删除某条记忆时可返回Falserecall_session子代理运行后回读其记忆可返回[]规则一recall的双轨 XORrecall要求user_id与agent_id恰好设置一个raven/contracts/memory.py#L166-L191双轨后端如 EverOS把设置的那个 id 路由到对应存储——用户侧存情节/画像代理侧存案例/技能扁平后端如 mem0用user_id正常工作收到agent_id调用时直接返回[]。两个都没传、或都传了那是调用方的 bug你返回[]即可。规则二store只认显式 Falsestore返回bool表示这次写入是否落地。只有显式返回False才算写入失败——宿主会据此带退避重试而返回None等假值会被当作已落地。所以请谨慎处理返回值。另外metadata中有两个值得尊重的约定键flush: True对话已结束立即从切片中提取别等自己的提取周期user_id/agent_id仅代表本次调用为谁写入子代理场景不要当成默认身份。规则三失败契约——宿主会替你兜底但别依赖它宿主AgentLoop、TUI、网关、raven serve会把每次调用的异常当作丢失这一次调用recall计为无命中、store计为未落地、start失败则本会话没有长期记忆。能识别的失败超时、连接被拒应尽量自己捕获并降级返回空结果比抛异常更优雅。 第二步写好raven-plugin.toml清单清单是发现机制唯一的入口解析规则在 raven/plugins/manifest.py。最小可用的记忆后端清单长这样[plugin] id my-memory version 1.0.0 [[plugin.contributes.memory_backends]] name mybackend factory my_package.backend:make_backend三个容易踩的坑 ⚠️factory必须是module.path:callable格式写错会在启动时立刻报错这是好事好过激活时才炸后端name会成为技能命名空间技能 id 形如name/id所以不能含斜杠且local、hub两个名字被保留不能占用插件__init__.py必须保持空或极轻——entry-points 发现会通过资源解析导入它重依赖放这里会违背只读清单的承诺。参考一个真实成品plugins-dist/everos-memory/raven_everos/raven-plugin.toml它还展示了onboard引导向导步骤、tools注册代理工具和config_schema对plugins.config配置切片做入门类型校验三类可选贡献点。 第三步四源发现机制如何找到你PluginDiscovery.discover()会扫描4 个来源并按插件 id 去重raven/plugins/discover.py#L86-L108。来源即优先级数字大者胜出优先级来源位置适用人群4BUNDLED随 Raven 分发的内置目录第一方插件3USER~/.raven/plugins/id/本地放一个目录即用2PROJECT./.raven/plugins/id/及plugins.dirs配置的目录随项目提交1ENTRY_POINTSpip 包entry-points 组名raven.plugins第三方分发推荐两条关键设计内置遮蔽规则bundled user project entry_points内置插件永远不会被同名的本地/pip 副本悄悄盖掉不同 id 的插件则和平共处由配置项memory.backend决定激活哪一个只读清单永不导入发现阶段只解析 TOML绝不 import 后端代码。所以某个后端缺了重量级依赖lancedb、mem0ai也拖不垮其他后端工厂模块只有在你选中该后端时才被导入——默认自带不等于默认付出启动成本。选中的插件会收到一个 PluginContext配置切片 ServiceLocator 带插件前缀的 logger你的make_backend(ctx)工厂函数只需基于它返回一个结构上符合MemoryBackend的对象。身份 iduser_id/agent_id统一由宿主经ctx.services下发不要从自己的plugins.config切片里另读一份——两处存同一个值就是改了一边、读写永久分裂事故的根源。✅ 第四步上线前检查清单8 个方法齐全recall/recall_session遵守 XOR 规则neither/both 时返回[]store仅在明确失败时返回False传输/鉴权错误不抛异常start幂等且recall/store能容忍在start未完成时被调用答无命中/未落地即可stop可在start失败后安全调用health如实报告只有真故障才是missing按需启动、尚未运行应报ok加提示清单 id/version 齐全name不含斜杠、不占用保留名包__init__.py保持空/轻跑通测试再发布uv run pytest tests/test_memory_backend_protocol.py tests/test_memory_backend_contract.py -q契约测试与发现测试分别在 tests/test_memory_backend_contract.py 和 tests/test_everos_plugin_discovery.py可作为编写自家后端的活模板。 延伸阅读资料说明raven/contracts/memory.py契约全文注释即最佳实践raven/plugins/discover.py四源扫描与冲突消解实现raven/plugins/bootstrap.py发现 → 激活的一站式装配docs/memory-plugin-architecture.md完整架构设计与 mem0 接入示例掌握了契约与发现机制你离给 Raven 装上一个自己设计的记忆只差一个make_backend的距离 【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/Raven创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考