技能、记忆与扩展¶
本页面向使用者。实现扩展请继续读构建插件或 构建 Agent;连接已有产品请读Agent 集成。
指令、工具、记住的事实和 Agent 是不同类型的能力。应选择能补足当前任务缺口的最小扩展。
能力地图¶
| 组件 | 提供什么 | 不代表什么 |
|---|---|---|
| Skill | 可发现的操作过程,可附脚本和参考文件 | 新的运行时工具或无限制执行 |
| SkillForge | 检索本地技能、记忆中的经验和 Skill Hub | 自动修改源代码 |
| Memory Engine / EverOS | 跨会话持久化与召回 | 所有历史消息永远在模型上下文中 |
| MCP 服务 | 外部服务提供的工具、资源或 prompt | 独立 Agent 会话 |
| Plugin | 工具、hook、服务、记忆后端等运行时贡献 | 与宿主进程隔离 |
| 专用 Agent | 自身身份、配置、工具和会话行为 | 自动访问全部宿主工具或凭据 |
| Playbook | 命名的可复用过程或图 | 被 SkillForge 索引的 skill |
| Evolver | 独立的、由基准驱动的 harness 改进评估 | 生产 Agent 在会话中改写自身代码 |
发现与管理技能¶
先检查当前安装提供哪些能力:
raven skill list
raven skill get --help
raven skill block --help
SkillForge 有四个来源:本地文件、通过配置的记忆后端召回的技能/案例、远程 Skill Hub 候选,以及工作目录所在仓库携带的项目技能。可用性取决于配置和服务连通性; 目录搜索命中不证明 bundle 已安装,也不证明所需工具存在。
搜索 Skill Hub 会把文字发出本机。该来源默认开启,使用共享目录
(https://skillhub.evermind.ai);配置可以在 skillForge.router.hub.endpoint
指定其他地址,RAVEN_SKILLHUB_URL 会同时覆盖对话检索和 SkillHub 页面的地址(被拒绝的
值会让该进程的对话检索直接关闭,而不是回落到共享目录)。开启期间,Raven 每次查找技能都会
把会话中的文字(消息本身,或模型据此写出的查询)发送到这个地址。可以用设置弹窗「技能」页
上的 Skill Hub 开关关闭,或把 skillForge.router.hub.enabled 设为 false;地址会保留,
重新打开时回到同一个目录。旧配置里显式的 null endpoint 表示保持关闭。两个方向都在下一次
搜索时生效,不需要重新加载。
检索到的技能以简短的名称/描述菜单出现在符合条件的轮次中,模型用 find_skill 搜索、
用 read_skill 读取正文。只有标记为 always 的技能常驻系统提示词。挑选技能不会让一轮
多出模型调用,不过查找时仍可能访问 Skill Hub,也不是每轮都会出现菜单。
技能目录¶
技能装在两个目录之一,取决于它是给用户用,还是给单个项目用:
- Agent home 的
skills/—— 用户级目录,即 agent home 下的skills/:默认~/.raven/workspace/skills,可由RAVEN_HOME以及raven agent、raven gateway、raven tui的--home选项改变位置。 - 项目的
.agents/skills—— 从本轮工作目录向上读到 git 根目录,途经的每一层各贡献 一个目录;两个目录出现同名技能时,以最近的目录提供的为准。工作目录之上没有 git 根目录 时,只读该目录本身。只识别扁平的<name>/SKILL.md布局;符号链接只有解析后的目标仍在 git 根目录内才算数。用户主目录、agent home 及其各层祖先目录永远不作为项目目录。
项目技能也以 project/<name> 出现在名称/描述菜单和 find_skill 的结果中,
read_skill / use_skill 按轮、按本轮自己的工作目录解析这些 id,因此两个 checkout
中的会话不会看到对方的项目技能。项目技能不论 frontmatter 怎么写都不会被注入系统提示词。
只有主 Agent 读取这些技能,子 Agent 不读取。该来源默认开启,可用
skillForge.projectSkills.enabled 关闭;两个方向都在下一次搜索时生效,不需要重启。
写入同一布局的安装器可以把技能装进项目:
gh skill install <owner>/<repo> skills/<name>/SKILL.md --dir .agents/skills
Bundle 下载有独立的同意设置:
{
"skillForge": {
"autoInstall": "prompt"
}
}
autoInstall 默认 auto;prompt 在交互式终端请求同意,没有 TTY 时表现为 off。
off 跳过 bundle 下载,但不禁止读取已通过检查的 skill 正文。需要禁用技能本身时
应使用 blocklist。执行前检查脚本;目录安全分数不是安全保证,当前策略也不会仅因缺少
分数就直接拒绝。成功安装记录在 <workspace>/skills/hub/installs.jsonl。
网页端设置弹窗的「技能」页负责技能和 Skill Hub 搜索的开关;页上的「新增」会把你带到会话里,并替你写好半句 请求——技能是让 Raven 在会话里安装的,受上面的同意设置约束。
记忆与学习边界¶
EverOS 是默认记忆后端插件,与 Raven core 独立发行,通过 Memory Engine 召回用户
上下文和 Agent 经验。用 raven plugins 检查当前后端,并通过 onboarding 与部署的
插件设置配置记忆。
应区分三个机制:
- 上下文组装决定本次模型调用看到什么,长历史可能被归档或压缩。
- 记忆存储和召回把选定知识保留到会话之外。
- 经验提炼由选用的记忆后端提供,通过该后端的插件设置配置。
宿主不使用
skillForge.extraction启动本地提炼管线。
SkillForge 负责技能检索、提供和下载包管理。宿主未实现反馈驱动的技能版本管理与退役。 可通过记忆后端存储的 case、skill 和健康状态检查保留了哪些经验。Harness 自进化由独立 Evolver 工具执行,并经过基准评估,先读 Evolver:使用与实验,实现细节见设计与实现。
从已完成任务到可复用知识¶
先决定什么需要保留:
| 信息 | 合适位置 | 如何确认 |
|---|---|---|
| 用户偏好或个人上下文 | 记忆后端 user track | 检查存储记录,在新会话测试召回 |
| Agent 经验或可复用案例 | 后端支持的 agent track | 查看后端实际返回的 case/skill |
| 已审核操作指令 | 本地 Skill | 阅读正文,检查所需工具 |
| 可重复多步骤执行 | Playbook | 校验并测试保存的图 |
| 来源文档与段落 | 知识库 | 核对索引和命中原文 |
| 失败运行证据 | Trajectory bundle | 回放并保留相关工件 |
EverOS 分别提供 user 与 agent 召回:用户记忆供应个人上下文,Agent case/skill 可作为
SkillForge 候选。希望连接的会话应保持预期 userId 和 agentId 稳定。
不同 Agent 身份或记忆后端不自动共享同一记忆集合。
可用不敏感偏好测试,例如“我喜欢先给简短清单,再写操作说明”。完成轮次, 检查可用的记忆视图/后端记录,再以同一身份开启新会话并询问相关问题。 确认记录和检索上下文,而不只相信模型说“我记得”。若在测试问题中再次写出偏好, 就不能证明发生了召回。
需要复用工作经验时,先完成并验证一个小任务,再检查后端是否记录有用的 case/skill。 若没有,显式编写审核本地 Skill,或创建 Playbook。 不要把每次成功回答都当成自动安装了新流程。
宿主记忆写入在轮次之外排队,有队列上限和重试。回答完成不意味着后端索引完成; 故障、队列限额和停机可能使数据未索引,或处于无法确认结果的 in-flight 状态。 记忆持久化不是完整 transcript 备份。
上下文压力不等于长期学习¶
Curator 为下一上下文窗口选择历史。压力较低时走不调用模型的 fast path; slow path 可消耗有限模型调用生成计划,无有效计划时使用确定性 fallback。 归档消息可在磁盘原样保存、后续取回,但不一定出现在每个 prompt 中。
轮内 Compaction 是另一机制:可以裁剪旧工具结果正文、总结 transcript 头部, 保留最近消息。默认关闭,不写长期记忆笔记。显式启用示例:
{
"agents": {
"defaults": {
"compaction": {
"enabled": true
}
}
}
}
请合并而不是覆盖其他 Agent 配置。Compaction 可调用本轮模型并产生费用, 不会扩大 provider 的真实上下文上限。Curator 和 compaction 都不能替代明确任务说明 或可重新读取的来源文件。
排查缺少召回或技能¶
| 现象 | 检查 |
|---|---|
| 新会话没有偏好 | 后端健康、索引完成情况、身份与召回相关性 |
| Skill 已列出但未使用 | 正文是否读取、所需工具、blocklist 和当前 Agent |
| 任务完成后没有新技能 | 后端实际提炼支持;skillForge.extraction 本身不启动宿主管线 |
| 长任务丢失细节 | 归档与当前窗口的区别、compaction、可重新读取的来源 |
| 模型成本增加 | 后端提炼、embedding 和 Curator slow path |
记忆视图可能暴露私有会话和推断偏好。应另行检查后端的删除与保留控制; 删除宿主 session 或屏蔽 skill 不证明所有后端记录也已删除。
扩展工具或构建 Agent¶
能力已由服务接口提供时使用 MCP。配置服务、核对工具列表与认证,再先测试只读操作,
最后才允许修改。raven plugin auth <server> 处理已配置 MCP 的 OAuth,不是任意
插件安装器。
网页端设置弹窗的「MCP」页负责开关、重试和授权已配置的服务;页上的「新增」会把你带到
会话里,由 Raven 从 PlugHub 目录接入服务;目录里没有的服务,要手改 config.json 的
tools.mcpServers。旁边的「插件」页列出 Agent 插件包,
它们会带来自己的技能和 MCP 服务。
需要进程内工具、hook、服务或记忆后端时使用 Raven plugin。声明式
raven-plugin.toml 列出贡献,代码运行于宿主信任域内。raven plugins 列出已安装
贡献。插件 Tool Gate 与平台 Permission Gate 是不同契约。
需要独立身份与执行配置时,使用 raven agents new <name> 创建专用 Agent 骨架。
先读 raven agents new --help;生成目录包含自己的 README。源码中的
agents/BUILDING.md 说明 launcher、配置、插件工厂及发现机制。运行状态不要写进
定义目录,要区分 Agent 的 state root、ACP home 与用户工作目录。
运行完整工作流¶
| 任务 | 入口 | 使用前确认 |
|---|---|---|
| 复用专业知识 | raven skill list |
正文、所需工具、下载同意策略 |
| 保留知识 | raven plugins 与记忆配置 |
后端健康和预期 user/agent 身份 |
| 连接工具服务 | MCP 配置、raven plugin auth --help |
凭据范围与实际工具可用性 |
| 协调 Agent | DAG 或 playbook | Roster 就绪、引用和共享上限 |
| 定时执行 | raven cron --help |
计划、接收方、权限和常驻宿主 |
| 启用主动行为 | 主动提醒与跟进 | 显式启用、打扰策略、成本 |
| 连接消息渠道 | raven channels --help |
发送者白名单、凭据、投递 |
| 诊断运行 | raven doctor、tracing、trajectory 工具 |
脱敏证据,而不只是握手成功 |
周期性或无人值守运行前,先读权限与安全和自托管。 模型上下文、记忆、下载的技能、子进程和远程 peer 各有自己的信任与成本边界。