跳转至

技能、记忆与扩展

本页面向使用者。实现扩展请继续读构建插件或 构建 Agent;连接已有产品请读Agent 集成。

指令、工具、记住的事实和 Agent 是不同类型的能力。应选择能补足当前任务缺口的最小扩展。

能力地图

组件 提供什么 不代表什么
Skill 可发现的操作过程,可附脚本和参考文件 新的运行时工具或无限制执行
SkillForge 检索本地技能、记忆中的经验和 Skill Hub 自动修改源代码
Memory Engine / EverOS 跨会话持久化与召回 所有历史消息永远在模型上下文中
MCP 服务 外部服务提供的工具、资源或 prompt 独立 Agent 会话
Plugin 工具、hook、服务、记忆后端等运行时贡献 与宿主进程隔离
专用 Agent 自身身份、配置、工具和会话行为 自动访问全部宿主工具或凭据
Playbook 命名的可复用过程或图 被 SkillForge 索引的 skill
Evolver 独立的、由基准驱动的 harness 改进评估 生产 Agent 在会话中改写自身代码

装配边界见架构,多 Agent 协作见DAG 编排。

发现与管理技能

先检查当前安装提供哪些能力:

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 与部署的 插件设置配置记忆。

应区分三个机制:

  1. 上下文组装决定本次模型调用看到什么,长历史可能被归档或压缩。
  2. 记忆存储和召回把选定知识保留到会话之外。
  3. 经验提炼由选用的记忆后端提供,通过该后端的插件设置配置。 宿主不使用 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 各有自己的信任与成本边界。