上下文类型

基于对人类认知模式的简化映射与工程化思考，OpenViking 将上下文抽象为 资源、记忆、能力三种基本类型，每种类型在 Agent 中有不同的用途。

概览

类型	用途	生命周期	主动性
Resource	知识和规则	长期，相对静态	用户添加
Memory	Agent 的认知	长期，动态更新	Agent 记录
Skill	可声明的 agent 能动性配置（AgentDefinedContextType）	长期，静态	用户或系统添加

Resource（资源）

资源是 Agent 可以引用的外部知识。

特点

用户主动：由用户主动添加的资源类信息，用于补充大模型的知识，比如产品手册、代码仓库
静态内容：添加后内容很少发生变化，通常为用户主动修改
结构化存储：将按照项目或主题以目录层级组织，并提取出多层信息。

示例

API 文档、产品手册
FAQ 数据库、代码仓库
研究论文、技术规范

使用

# 添加资源
client.add_resource(
    path="https://docs.example.com/api.pdf",
    options={"reason": "API 文档"},
)

# 搜索资源
results = client.find(
    query="认证方法",
    target_uri="viking://resources/",
)

Memory（记忆）

记忆是 Agent 从交互和任务执行中学到的持久化知识。记忆存储在当前用户或 Peer 命名空间，不使用独立的 viking://agent/memories 目录。

特点

Agent 主动：由 Agent 主动提取和记录的记忆信息
动态更新：由 Agent 从交互中持续更新
个性化：针对特定用户和稳定 peer 学习记录

内置记忆类型

类型	默认位置	说明
profile	`~/memories/profile.md`	用户基本信息
preferences	`~/memories/preferences/`	按主题组织的用户偏好
entities	`~/memories/entities/`	人物、项目、组织等实体知识
events	`~/memories/events/`	决策、里程碑等事件记录
identity	`~/memories/identity.md`	助手的名称、形象、气质和自我介绍
soul	`~/memories/soul.md`	助手的核心原则、边界、风格和连续性
cases	`~/memories/cases/`	用于训练和评估的任务案例
trajectories	`~/memories/trajectories/`	可复用的任务执行轨迹
experiences	`~/memories/experiences/`	从执行结果中提炼的可复用经验

表中的 ~/... 使用家目录别名 viking://~，服务端会按认证身份将其展开为 viking://user/{user_id}/...。当记忆策略允许 Peer 记忆时，支持 Peer 的类型会写入 viking://user/{user_id}/peers/{peer_id}/memories/...。记忆类型可通过自定义模板扩展或调整。

Schema 定义的 memories/tools/ 和 memories/skills/ 类型已禁用。它们与存放在 viking://user/{user_id}/skills/{skill_name}/SKILL.md 下的独立 Skill 不同，后者仍然保留并受支持。

使用

from openviking_sdk import TextPart

# 记忆从会话中自动提取
session_info = await client.create_session()
session = client.session(session_id=session_info["session_id"])
await session.add_message(
    role="user",
    parts=[TextPart(text="我喜欢深色模式")],
)
commit = await session.commit()  # 启动后台记忆提取
task = await client.get_task(task_id=commit["task_id"])  # 轮询直到 task["status"] == "completed"

# 搜索记忆
results = await client.find(
    query="用户界面偏好",
    target_uri="viking://~/memories/"
)

Skill（技能 / AgentDefinedContextType）

技能（Skill）是 Agent 可以调用的能力，属于 AgentDefinedContextType 范畴。包括传统工作流定义、通信端点、工具配置和支付能力等。它们的共同特征是：定义了 agent 如何与外部系统交互，运行时定义相对静态，但调用经验会在 Memory 中更新。

特点

定义的能力：用于完成某项工作的工具定义
相对静态：运行时技能定义不变，但和工具相关的使用记忆会在记忆中更新
可调用：Agent 决定何时使用哪种技能

存储位置

viking://~/skills/{skill-name}/  # 默认存储路径
├── .abstract.md          # L0: 简短描述
├── .overview.md          # L1: 目录概览（生成后）
├── SKILL.md              # L2: 技能定义
└── scripts               # L2: 附加实现

viking://agent/skills/{skill-name}/  # 通过 --uri 覆盖，公开共享（account 全局）
├── .abstract.md          # L0: 简短描述
├── .overview.md          # L1: 目录概览（生成后）
├── SKILL.md              # L2: 技能定义
└── scripts               # L2: 附加实现

AgentDefinedContextType 子类型

AgentDefinedContextType 包含以下子类型，均存储于 viking://agent/ 作用域：

子类型	位置	说明
Skill	`agent/skills/`	传统工作流定义，如搜索、代码生成
Endpoint	`agent/endpoints/`	通信端点配置（a2a, anp 等）（规划中）
Tool	`agent/tools/`	工具配置（mcp 等）（规划中）
Payment	`agent/payments/`	支付能力配置（ap2 等）（规划中）

使用

# 添加技能（默认写入 viking://~/skills/）
await client.add_skill(
    data={
        "name": "search-web",
        "description": "搜索网络获取信息",
        "content": "# search-web\n...",
    },
)

# 通过 -p 指定写入全局 agent 技能根（公开共享）
ov skills add search-web -p viking://agent/skills

# 搜索用户技能
results = await client.find(
    query="网络搜索",
    target_uri="viking://~/skills/"
)

# 搜索全局 agent 技能
results = await client.find(
    query="网络搜索",
    target_uri="viking://agent/skills/",
)

统一检索

根据Agent的需求需求，支持对三种上下文类型统一搜索，提供全面信息：

# 跨所有上下文类型搜索
results = await client.find(query="用户认证")

for context in results.get("memories", []):
    print(f"记忆: {context['uri']}")
for context in results.get("resources", []):
    print(f"资源: {context['uri']}")
for context in results.get("skills", []):
    print(f"技能: {context['uri']}")