如何编写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），仅供参考
企业数字化 ERP 产品动态
相关推荐
S7-200 PLC与组态王实现火灾报警及消防联动控制系统详解 先聊聊我为什么要写这套东西。做自动化项目这些年，被问得最多的一个问题就是：中小型楼宇、厂房的消防联动，能不能用一台 S7-200 PLC 加组态王做？我的答案一直很明确——能，而且这样做的人不少。火灾报警控制系统听起来… · 2026/9/26 4:00:29
asio与protobuf集成实战：C++网络编程序列化全流程 asio这系列写到第10篇，前面已经把TCP server/client、异步读写、buffer管理这些底层的骨架都搭起来了。但你真拿asio去写业务代码的时候，一个躲不开的问题马上就会冒出来：服务端和客户端之间那些结构体数据，到底怎么传才靠谱&… · 2026/9/26 4:00:29
牛奶生产线设备选型与工艺配置全解析 1. 整线设计与工艺思路拆解1.1 牛奶生产线到底在做什么收到不少朋友问牛奶全套加工设备的事，我发现很多人对"牛奶生产线"这个概念的理解比较模糊，以为就是几个不锈钢罐子加管道拼在一起。实际上一条完整的牛奶生产线，本质上是在做一… · 2026/9/26 4:00:29
健安干燥设备厂好不好，客户反馈怎么样 在工业制造迈向精细化与合规化的今天，干燥与灭菌早已不再是简单的热处理环节。对于制药企业而言，GMP认证的严苛标准让每一台接触物料的设备都必须经得起洁净与验证的考验;对于新材料、新能源领域的探索者来说，物料的热敏性、腐蚀性乃至无氧环… · 2026/9/26 5:58:22
老电脑绕过TPM 2.0安装Windows 11完整指南：Rufus与注册表方法 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/26 5:58:22
Scratch枪战游戏：事件驱动与状态管理教学实践 1. 为什么这个枪战游戏不是“玩具”，而是Scratch教学的分水岭Scratch编程里，90%的孩子做过“小猫走路”“钢琴弹奏”“角色变装”，但真正卡住进阶的，从来不是积木怎么拖——而是当项目规模超过20个积木、3个角色、2种状态切换时&a… · 2026/9/26 5:58:22
Redis、MongoDB 与 MySQL 数据建模对比实验 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/26 5:58:16
WorkBuddy国际版积分倍率实测：一周烧三万积分，教你省下70%额度 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/26 5:58:16
Claude Code 集成 LSP：为命令行 AI 编程代理装上代码导航地图 最近真刀真枪把 Claude Code 和 LSP 集成到一起用了一段时间，这套组合解决了不少项目里的老大难问题，觉得值得好好写一篇。先给结论：Claude Code 本身是一个跑在终端里的 AI 编程代理，它擅长的是读代码、改代码、执行命令… · 2026/9/26 5:58:09
数据库课后习题答案别硬背：当测试用例集刷，效率翻倍 简介：万常选版《数据库原理与设计》课后习题答案资源，覆盖第2至6章及第9章，适合正在学习关系模型、数据库建模、关系数据理论与模式求精的本科生、自学者作为复习与自测材料。压缩包共7个文件，含3个doc参考答案、2个sql示例脚本、… · 2026/9/26 0:00:21
OpenClaw 替代品？Hermes Agent 踩坑实录：macOS 飞书接入 TaoToken 配置 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/26 0:00:40
向下兼容与向上兼容：接口设计中的兼容性策略与工程实践 一次版本升级事故，是很多团队绕不过去的坎。线上环境里，服务端明明已经上线了新版接口，老的移动端还在照着旧文档传参数。请求一到网关，校验直接拒绝，用户操作失败，客服群炸了锅，开发群里开始互… · 2026/9/26 0:00:46
