13. 进阶（二）：Agents / Skills / Memory

omicOS 的能力由三套可扩展系统组成：Agents（智能体）、Skills（技能）、Memory（长期记忆）。三者由云端统一管理、同步到本地。lab 及以上订阅可在自己的工作区里加塞或覆盖。本章讲这套机制。

13.1 订阅分层

omicOS 按订阅等级给功能分层，内部用一个 rank 数值比较：

等级	rank
community	0
plus	1
pro	2
lab	3
enterprise	4

未知或为空的等级名一律当作 0（community）。两个常用的分水岭：

rank ≥ 2（pro）：能开 Agent2Agent 对外端点（见第 9 章）。
rank ≥ 3（lab）：能用「工作区本地扩展」，也就是下面 13.2 / 13.3 讲的本地覆盖。

订阅状态由一个订阅令牌（JWT，存在 ~/.omicos/plan_token.jwt）承载。后台调度器在剩余有效期不足 25% 时自动续期。续期失败且令牌过期时降级到 community，付费功能被锁定，直到重新登录。

13.2 Agent 模板

Agent 是一个有特定角色、工具集和系统提示词的智能体。模板格式是 YAML frontmatter + Markdown 正文：

---
id: my_lab_qc
name: My Lab QC
description: 课题组定制的 QC agent
tier: lab
toolsets:
  - python_interpreter
  - file_manager
  - omicverse_lookup
skills:
  - qc_basic
---

You are a QC specialist...
（以下是完整的 system prompt 正文）

常见字段：id、name、description、toolsets、instructions、tier、skills、category、use_when、example_prompts。

Agent 的加载来源

基础花名册按以下优先级取第一个能用的目录：

OMICOS_TEMPLATES_DIR 指定的目录
<workspace>/config/agents/（存在时）
云缓存 ~/.omicos/cloud-agents/agents/——真实用户走的就是这条
兜底 <workspace>/.omicos/（通常是空的，此时会退化成占位的默认 agent，让配置问题暴露出来而不是静默）

在此之上，lab 及以上的用户可以叠一层工作区覆盖：<workspace>/agents/（或旧位置 <workspace>/.omicos/agents/）。

本地覆盖的生效规则

新 id → 追加到花名册末尾（多一个 agent）。
同 id → 本地 .md 覆盖云端版本，方便临时迭代某个 prompt。
community / plus / pro 用户即使写了文件也会被静默忽略——云端目录是唯一来源。
改文件后需重启 omicos serve / omicos cli 才生效；网页端的「刷新」只重新拉云端内容，不重读本地文件。

Agent 的 skill 白名单语义

agent 的 skills 字段控制它能看到哪些 skill：

空 / 缺省 = 全部 skill 可见（向后兼容，不是全部隐藏）。
["*"] = 显式通配，全部可见。
命名列表 = 仅列出的这些可见。
工作区本地 skill 始终绕过白名单，总是可见。

13.3 Skills

Skill 是可复用的能力单元。发现 skill 的根目录按优先级排列（靠前的在重名时获胜）：

OMICOS_SKILL_ROOTS 列出的目录（冒号 / 分号分隔）
云缓存 ~/.omicos/cloud-skills/skills/
<workspace>/skills/（lab+）
<workspace>/.omicos/skills/（lab+，旧位置）

不存在的目录会被静默跳过。

有两个曾经存在、现在已经取消的来源：Python 包 omicverse_skills 随 kernel 环境带进来的 skill 目录，以及跨项目的用户级 ~/.omicos/skills/。现在 skill 只有两个来源：云端目录，或工作区本地。~/.omicos 下只保留云缓存。

云同步会做哈希比对与清理，并带上订阅令牌做分层过滤。OMICOS_SKILLS_OFFLINE=1 可关闭同步、只用本地缓存。

13.4 Memory（长期记忆）

Memory 让智能体跨对话记住内容。它就是 ~/.omicos/memory/ 下的一堆纯 .md 文件（不需要 frontmatter，标题取首个非空行），按进程令牌同步到云端。

ls ~/.omicos/memory

预期输出：

project-conventions.md    rnaseq-pipeline-notes.md

工具：memory__list / memory__view / memory__create / memory__edit / memory__delete。
slug 命名规则：[a-zA-Z0-9_-]，长度 1–64；正文上限 64 KiB。
写入策略：本地写优先，云端尽力同步。OMICOS_MEMORY_OFFLINE=1 可关闭云同步。
可用 OMICOS_MEMORY_CACHE_DIR 换存放位置——注意那就是记忆本体所在，不是另一份副本。

13.5 同步节奏

内容	变量	默认	说明
agent / skill / model 目录	`OMICOS_CATALOG_SYNC_SECS`	600 秒	小于 30 的值不会被钳到 30，而是被丢弃并回退到 600
memory	`OMICOS_MEMORY_SYNC_SECS`	3600 秒	平时靠云端推送即时同步，这个间隔只是兜底；小于 60 同样丢弃回退

云端内容变动时会主动推送。在管理端改了 agent / skill，不用重启正在运行的 omicos。

13.6 工作区扩展门控小结

能力	谁能用
使用云端 agents / skills	所有用户（按订阅分层过滤）
在 `<workspace>/agents`、`<workspace>/skills` 放本地覆盖	仅 lab / enterprise（rank ≥ 3）
使用 / 写 memory	所有用户
开启 Agent2Agent 对外端点	pro 及以上（rank ≥ 2）

如果你是 community / plus / pro 用户，发现自己放的本地 agent 不生效，这是预期的——需要 lab 才能用工作区本地扩展。

13.7 R 语言支持

除了 Python，智能体也能跑 R（run_r_code，审批档位与 run_python_code 相同）。

R 运行时（r-base + IRkernel）不随主环境安装，而是按需装成一个 add-on：

环境自动化打开时（OMICOS_ENV_AUTO=1），第一次跑 R 而运行时缺失，会在后台启动安装（约 2–5 分钟），并提示你稍后重跑该单元格；安装脚本可重复执行，中途被打断也不会留下半成品。
每个 worker 同时最多只有一个后台安装在跑。
没开自动化时，会给出手动安装提示。

装的是环境内容（进当前 env），不是改你的系统 R。

13.8 后台任务

耗时分析放到后台任务里跑。任务从内核 fork 出去独立执行，占用写时复制内存副本。不卡对话，可单独监控和取消。运行中的后台任务在第二部分的运行时状态面板里可见。

13. 进阶（二）：Agents / Skills / Memory / R / 后台任务