[RFC] Harness 如何使用 OpenViking 远程SKILLS，Vikingbot 实践

[yeshion23333]

RFC：VikingBot 使用 OpenViking 远程 Skill

• 状态： 提案
• 更新时间： 2026-08-04

1. 方案结论

OpenViking 负责保存、检索和鉴权，VikingBot 负责激活与执行。文本默认按 URI 远程读取；只有现有工具确实需要本地路径时，才物化 Skill 包。同版本文件可在权限隔离的主机缓存中短期复用，工具始终使用当前请求的独立沙箱副本。

决策	方案
新增 load_skill	不新增，继续使用 openviking_multi_read
Skill 是否必须下载	不必须，Markdown、说明和示例文本保持远程
何时下载	exec 命中包内文件，或工具声明了本地文件/目录参数时
下载到哪里	Bot 主机版本化缓存；复制到当前请求沙箱的临时目录执行
何时清理	请求副本在 Agent Turn 结束时删除；主缓存按 10 分钟空闲 TTL、LRU 和容量清理
是否配置物化模式	不配置；没有 default_materialize 和 materialize_mode，始终自动判定
谁执行	VikingBot 现有模型、Tool Registry 和沙箱
多 Skill 权限	所有已激活 Skill 的权限取交集，不由模型选择权限来源
子智能体	默认不启用；没有 OpenViking Tool 就不创建远程 Skill 运行时

2. Bot Harness 链路

2.1 模块连接

模块	职责
AgentLoop	每处理一条需要回复的普通用户消息，创建一个新的 SkillRuntimeContext，贯穿该消息的全部模型与工具迭代
ContextBuilder	合并本地 Skill 摘要和 OpenViking L0 摘要
模型	用现有 openviking_multi_read 选择并读取 SKILL.md
VikingMultiReadTool	读取正文，并把 (uri, content) 交给运行时激活
ToolRegistry	生成受限 Tool Schema；调用前执行权限、依赖和资源处理
SkillRuntimeContext	保存当前 Agent Turn 的候选、已激活 Skill、清单、锁、物化目录和使用记录
沙箱	承载临时 Skill 快照并执行原工具
Session / Trace / 事件	只保存脱敏结果和真实 skill_uri

这里的“请求”指一次用户消息对应的 Agent Turn，不是整个 Session，也不是只在 Session 第一条消息时创建。SkillRuntimeContext 不加入全局 SkillsLoader，不跨 Agent Turn、用户或子智能体共享。

2.2 一次请求的执行顺序

需要回复的普通用户消息
  ↓
读取或创建 Session
  ↓
创建新的 SkillRuntimeContext(request_id)
  ↓
find_skills(用户问题) → 只取 L0 摘要
  ↓
ContextBuilder 注入本地 + 远程 Skill 摘要
  ↓
模型调用 openviking_multi_read(SKILL.md)
  ↓
校验并激活 ActiveRemoteSkill
  ↓
下一次模型迭代使用刷新后的 Tool Schema
  ↓
ToolRegistry：校验 → 权限交集 → requires → 资源解析 → 原工具
  ↓
Session 保存用户消息、回答、脱敏工具结果和 skill_uri(s)
  ↓
按现有策略可选提交 OpenViking Session
  ↓
发布响应完成事件
  ↓
finally：关闭 SkillRuntimeContext
  ↓
删除请求级执行副本，关闭本次 OpenViking Client
  ↓
版本化主缓存继续保留，按空闲 TTL/LRU 清理

运行时只在以下条件同时满足时创建：

当前 Channel 开启 OpenViking Tool
AND OpenViking 连接可用
AND openviking_multi_read 已注册且未被禁用

因此 OpenViking Tool 是唯一能力开关，不再增加一套 Remote Skill 开关。

2.3 生命周期及与 Session 的关系

同一个 Session
├─ 用户消息 A → Runtime A → 多次模型/工具迭代 → close Runtime A
├─ 用户消息 B → Runtime B → 多次模型/工具迭代 → close Runtime B
└─ /new、Session 提交或删除不控制 Runtime 生命周期

生命周期节点	行为
创建	普通消息通过命令、Debug、need_reply 等前置分支后，在 Skill 发现前创建
复用	同一条消息产生的全部模型迭代、Skill 激活和工具调用共用一个 Runtime
正常结束	Session 保存和可选提交完成后，在响应返回前由 finally 调用 close()
异常结束	无论发现、模型、工具、Session 保存或事件发布在哪一步失败，仍由 finally 调用 close()
未创建	系统消息、命令、Debug、无需回复，或 OpenViking Tool 能力条件不满足时不创建

Runtime 与 Session 不同步结束：

数据	是否跨 Agent Turn 保留
Session 消息历史	保留，按现有 Session 策略保存或提交
脱敏工具结果、skill_uri(s)、解析后的工具参数	作为工具使用记录写入 Session
Skill 候选、已激活 Skill、权限交集、依赖检查结果和请求内锁	不保留，下一条消息重新建立
远程 Skill 正文	不写入持久化 Session
.vikingbot/remote-skills/<request-id>	close() 时删除，不等待 Session 结束
主机侧版本化文件缓存	可按权限域、Skill URI 和 revision 短期复用；不属于 Session 状态

/new、Session 提交、清空或删除是独立流程。它们不触发 Runtime 关闭；Runtime 已在每条消息处理结束时关闭。下一条消息即使复用同一个 Session，也必须重新发现并激活所需的远程 Skill；激活确认 revision 未变后，可以复用主机侧文件缓存。

3. 发现与激活

3.1 发现

本地 SkillsLoader ──────────────┐
                                ├─→ ContextBuilder
OpenViking find_skills(query) ──┘

规则	处理
查询内容	当前用户问题
返回内容	前 K 个 L0 摘要，不读取完整包
同名优先级	本地工作区 > OpenViking 用户 Skill > OpenViking 共享 Skill
显式 URI	直接按 URI 读取，不按名称重新选择
权限	复用 OpenViking ACL 和当前请求身份

远程摘要示例：

<skill source="openviking_user">
  <name>release-audit</name>
  <description>审计发布并生成风险报告。</description>
  <location>viking://user/u1/skills/release-audit/SKILL.md</location>
  <read_tool>openviking_multi_read</read_tool>
</skill>

3.2 激活

模型仍调用现有工具：

{
  "name": "openviking_multi_read",
  "arguments": {
    "uris": ["viking://user/u1/skills/release-audit/SKILL.md"]
  }
}

激活后生成请求内的 ActiveRemoteSkill：

数据	用途
root_uri / skill_md_uri	Skill 身份与相对引用基准
name / description	提示词与经验召回
allowed_tools	缩小当前 Bot 工具权限
metadata.vikingbot.requires	检查实际沙箱中的命令和环境变量
files	相对路径 → canonical URI；路径、URI、大小和哈希必须互相一致且不可重复
content_sha256 / revision	固定本次使用的内容快照
文件 size / sha256	下载后逐文件校验

激活只建立运行状态，不下载资源文件。

3.3 同批激活

模型可能在同一响应中同时发出“读 SKILL.md”和“执行脚本”。这批调用不能直接并行：后一个调用是基于激活前 Tool Schema 生成的。

同一模型响应
├─ 激活调用：先执行
└─ 其他调用：返回 SKILL_CONTEXT_UPDATED，不执行
                    ↓
下一次模型迭代重建 Tool Schema
                    ↓
模型按新 Schema 重试普通工具

如果任一激活失败，同批普通工具全部返回 SKILL_ACTIVATION_FAILED。结果仍按原 Tool Call 顺序返回模型。

4. 工具调用前处理

AgentLoop 确认工具在本次 Schema 中可见
  ↓
原工具参数校验
  ↓
所有已激活 Skill 的 allowed-tools 交集
  ↓
受约束 Bash 参数校验
  ↓
所有已激活 Skill 的 requires 检查
  ↓
Skill 资源解析；必要时物化并改写路径
  ↓
执行原工具

原工具只看到自己原本支持的参数；运行时不会向 Tool Schema 添加 _remote_skill_uri 等模型可控字段。

4.1 多 Skill 权限

有效工具 = Bot/Channel 当前可见工具
         ∩ Skill A 的 allowed-tools
         ∩ Skill B 的 allowed-tools
         ∩ ...

情况	结果
任一 Skill 不允许某工具	该工具不出现在下一轮 Tool Schema 中
每个 Skill 都允许该工具	工具可见，调用时逐个检查参数约束
多个 Skill 都声明 Bash(python *)	python ... 可以通过
一个允许 Bash(python *)，另一个允许 Bash(git:*)	没有命令同时满足，调用被拒绝
资源在多个 Skill 中同名	裸相对路径被拒绝，必须使用 canonical URI

这样模型无法通过选择某个 skill_uri 获得更宽权限。

4.2 Bash 约束

Bash(git:*)、Bash(python *) 等声明只允许一条简单命令。受约束命令拒绝：

;  &&  ||  |  <  >  换行  `...`  $(...)

同一个 Skill 内的多个 Bash 模式是“或”；多个已激活 Skill 之间仍是“且”。未声明参数约束的普通 Bash 不额外限制命令参数，但仍受 Bot、Channel 和沙箱策略约束。

4.3 运行依赖

metadata:
  vikingbot:
    requires:
      bins: [python3]
      env: [EXAMPLE_API_TOKEN]

• 在真正执行工具的沙箱内检查，不检查 Bot 宿主机。
• 在该 Skill 首次参与任务工具前检查，与是否下载文件无关。
• 环境变量只检查是否存在，不读取或记录值。
• VikingBot 不自动安装命令或依赖。

5. 资源解析与自动物化

5.1 资源类型

使用方式	处理
纯 Markdown 操作步骤	不下载
references/*.md、配置说明、示例文本	解析为 canonical URI，继续远程 read
python scripts/foo.py	物化整个 Skill 包并重写脚本路径
模板、模型、图片、二进制	工具需要本地文件参数时物化
纯 API / MCP / OpenViking Tool 编排	不下载

5.2 路径来源必须明确

已激活远程 Skill 后，本地文件参数和 exec 中的路径按以下规则处理：

输入	行为
canonical viking://... URI	必须属于已激活 Skill 且存在于清单
唯一命中的包内相对路径	物化对应 Skill 并改写
多 Skill 同名相对路径	返回 SKILL_RESOURCE_AMBIGUOUS
workspace:output/report.md	明确表示普通工作区相对路径，去掉前缀后传给原工具
普通绝对路径、HTTP URL、Data URL	原样传给原工具
其他像文件的裸相对路径	失败关闭，返回 SKILL_RESOURCE_NOT_FOUND

普通工作区文件推荐使用：

workspace:input/data.csv

调用方已经持有当前沙箱后端的原生绝对路径时也可直接传入；RFC 不约定统一的 /workspace 绝对路径。

禁止 ..、编码后的目录逃逸、跨 Skill 根引用，以及未激活 Skill 的辅助资源。

5.3 普通文件型工具

工具显式声明哪些参数消费本地文件或目录：

resource_inputs:
  path: local_file
  /files/*/workspace_path: local_file
  /pages/*/body_workspace_path: local_file

运行时只处理这些声明；嵌套参数使用 JSON Pointer 和 *。输出路径不声明为输入资源，因此不会被错误物化。

5.4 exec 示例

exec("python scripts/audit.py")
               ↓ 清单唯一命中
viking://user/u1/skills/release-audit/scripts/audit.py
               ↓ 工具需要本地路径
物化整个 Skill 包
               ↓
exec("python .vikingbot/remote-skills/<request-id>/<hash>/release-audit/scripts/audit.py")

Shell 执行失败后不自动补下载或重试，避免重复副作用。

5.5 物化目录与粒度

第一次需要本地文件时物化整个包，以保留相对导入、source、同目录配置和模板：

<request-sandbox>/
└─ .vikingbot/remote-skills/
   └─ <request-id>/
      └─ <sha256(root_uri)>/
         └─ <skill-name>/
            ├─ SKILL.md
            ├─ scripts/
            ├─ references/
            └─ assets/

• 同一请求内重复使用同一 Skill 时复用快照。
• 请求级执行副本位于沙箱 Workspace，只供本次 Agent Turn 使用。
• 未发生物化时，请求结束不会为了清理而启动沙箱。
• 发生过物化时，请求结束删除整个 <request-id> 目录。

5.6 版本化快照缓存

缓存目标是消除短时间内同一 Skill revision 的重复文件下载，同时不跳过当前请求的 ACL、激活和版本校验。

当前身份读取并激活 SKILL.md
  ↓ 获得 canonical root_uri + revision + manifest signature
查询主机缓存：<permission-scope, root_uri, revision>
  ├─ 命中
  │    ↓ 再次确认 manifest signature 未变化
  │ 逐文件校验缓存 size/sha256
  └─ 未命中
       ↓ 同键下载锁
     下载到 .partial 目录
       ↓ 逐文件校验 size/sha256
     再次确认 manifest signature 未变化
       ↓ 原子发布缓存快照
  ↓
复制到请求级沙箱目录
  ↓
工具执行；Agent Turn 结束删除请求副本
  ↓
主缓存按空闲 TTL、LRU 和容量清理

缓存分成两层：

层级	位置	是否直接交给工具	生命周期
版本化主缓存	<bot-data>/remote_skill_cache/	否	跨 Agent Turn，按 TTL/LRU 保留
请求级执行副本	<sandbox>/.vikingbot/remote-skills/<request-id>/	是	当前 Agent Turn，close() 删除

主缓存位于 Bot 数据目录，不在模型可见的沙箱 Workspace 内。工具获得的是独立请求副本，因此脚本写文件不会污染后续请求的缓存快照；远程沙箱命中缓存时仍需把本地主缓存写入该沙箱，但不会再次从 OpenViking 下载文件。

缓存键：

permission-scope = sha256(
  workspace_id + actor_peer_id + server_url + 当前连接的稳定身份与命名空间策略
)

cache-key = permission-scope
          + sha256(canonical root_uri)
          + sha256(revision)

• 不使用 Skill 名称作为身份，避免同名覆盖。
• 不跨 actor_peer_id 或 OpenViking 身份复用，避免 ACL 数据泄漏。
• API Key 有稳定账户/用户身份时不进入缓存键；只有无法得到稳定身份时才使用其哈希隔离。
• revision 变化会生成新条目；旧版本不再命中，等待 TTL/LRU 清理。
• TTL 只控制缓存保留时间，不允许跳过每个 Agent Turn 的 OpenViking ACL 和版本复查。
• 当前实现消除重复 download_bytes 文件传输，但仍执行 Skill 发现、SKILL.md 读取和 integrity manifest 查询。

6. 一致性、限额与并发

6.1 一致快照

OpenViking get_skill(include_integrity=true)
  ↓ 在 Skill 存储树锁内读取
SKILL.md 内容 + content_sha256 + 文件清单 + revision
  ↓
缓存命中：复查 manifest 后校验本地缓存
缓存未命中：下载并逐文件校验 size/sha256
  ↓
再次读取 revision/manifest signature
  ↓
一致：生成请求级执行副本；变化：删除未完成快照并拒绝执行

树锁保证一次 get_skill 响应内部的正文、清单和 revision 来自同一存储快照；物化前后复查用于覆盖激活、缓存读取或网络下载期间发生的更新。

6.2 双层限额

层级	文件/条目数	单文件	总大小	读取并发
OpenViking integrity API 硬上限	512	16 MiB	64 MiB	8
VikingBot 默认物化上限	128	8 MiB	32 MiB	下载按文件进行

实际允许值取两层中更严格的一层：

• 服务端先限制生成完整哈希清单的资源消耗；超限后不继续读取后续批次。
• Bot 在下载前检查声明值，下载中再按实际字节检查，防止伪造清单。
• 文件数包含 SKILL.md；目录不计入 Bot 的可下载文件数。
• 任一文件或总包超限都会清理未完成快照，原工具不会执行。

主机缓存另有独立总量护栏：

缓存项	默认值	淘汰方式
空闲 TTL	10 分钟	成功命中后刷新；到期立即不再命中，并在下一次缓存活动时惰性删除
最大快照条目	32	淘汰没有租约且最久未使用的条目
最大缓存字节数	256 MiB	按 LRU 淘汰直到回到上限内

一个快照的文件数和大小仍先受 max_files、max_file_bytes、max_total_bytes 限制。缓存容量不足只会导致条目更早淘汰，不会放宽单包限制。

6.3 RemoteSkillsConfig 的作用

该配置不是功能开关，也不决定“远程还是下载”；它只提供部署侧可调的检索和资源护栏：

配置	默认值	作用
discovery_limit	8	注入提示词的远程候选上限
score_threshold	0.35	发现结果最低相关度
discovery_timeout_seconds	2 秒	发现超时后回退本地 Skill
max_files	128	单个物化包最大文件数
max_file_bytes	8 MiB	单文件最大字节数
max_total_bytes	32 MiB	单个物化包最大总字节数
cache_idle_ttl_seconds	600 秒	主机缓存条目的空闲保留时间
cache_max_entries	32	主机缓存最大版本化快照数
cache_max_bytes	256 MiB	主机缓存最大总字节数

不提供 enabled、default_materialize 或 materialize_mode，避免和 OpenViking Tool 能力开关及自动资源判定产生两套语义。

6.4 请求内锁与缓存租约

锁	键	效果
激活锁	root_uri	同一 Skill 只激活一次
依赖检查锁	root_uri	同一 Skill 的 requires 只检查一次
物化锁	root_uri	同一请求只生成一个完整快照
缓存下载锁	permission-scope + root_uri + revision	同一 SandboxManager 内并发首次命中时只从 OpenViking 下载一次
缓存清理锁	缓存实例	串行执行 TTL/LRU/容量清理

前三个请求内状态随 SkillRuntimeContext 关闭；缓存下载锁和清理锁属于 SandboxManager 持有的主机缓存实例。缓存复制期间持有租约，TTL/LRU 不删除正在复制的条目；执行使用独立请求副本，不长期占用缓存租约。

7. 子智能体

Subagent 工具注册：include_viking_tools=False
              ↓
没有 openviking_multi_read
              ↓
不创建 SkillRuntimeContext
              ↓
不发现、不注入、不继承、不物化远程 Skill

主智能体不会把远程 Skill 快照或 skill_uris 传给 spawn。未来如果显式给子智能体开放 OpenViking Tool，应为每个子任务创建独立运行时，并完整复用本文的发现、权限、物化和清理规则。

8. 身份、隐私与记录

8.1 身份

• 发现、读取、完整性查询和下载始终复用当前请求的 openviking_connection。
• OpenViking 返回的 canonical URI 是 Skill 身份，名称只用于展示。
• ACL 仍由 OpenViking 执行，VikingBot 不复制权限模型。
• 缓存命中前仍用当前请求身份完成激活和 manifest 复查；缓存不能绕过权限撤销。
• 主缓存目录使用 0700、文件使用 0600，只对 Bot 运行账户开放；文件内容不进入模型、Session、事件或 Trace。

8.2 三种结果视图

视图	内容
模型视图	当前请求执行所需的完整恢复正文
Session / TOOL_RESULT 事件	省略正文，只保留状态和 skill_uri(s)
日志 / Trace	使用脱敏结果，不输出恢复后的远程 Skill 正文

模型视图只存在于当前请求的模型消息中。辅助资源远程读取、激活读取和混合读取只要关联到已激活 Skill，持久化视图就省略完整结果。

8.3 使用记录

skill_uri   = 首个关联 Skill，兼容原有单值消费者
skill_uris  = 本次工具调用关联的全部已激活 Skill
resolved_args = 资源解析后的实际参数

运行日志和请求内使用记录包含激活、远程资源读取、物化完成、cache=hit|miss|bypassed 和任务工具调用；不记录隐私正文、API Key 或环境变量值。

9. 失败处理

情况	行为
发现失败或超时	继续使用本地 Skill
SKILL.md 非法、名称与 URI 不一致	不激活
canonical root、清单 path/URI 映射不一致，或无完整性信息	不激活
同批激活失败	阻止同批全部普通工具
工具不满足全部 Skill 权限	从 Schema 隐藏或调用时拒绝
受约束 Bash 包含复合命令	拒绝执行
相对路径不存在、歧义或逃逸	不执行消费者工具
Skill 包或 integrity 请求超限	停止读取/下载，不执行原工具
沙箱缺少命令或环境变量	返回缺失项名称，不自动安装
下载期间 revision 或校验值变化	删除未完成快照，要求重新读取 Skill
缓存文件缺失或 hash 不一致	删除损坏条目并重新下载一次；再次失败则不执行原工具
主机缓存不可写	绕过缓存，按请求级物化执行，不影响 Skill 功能
TTL/LRU 清理失败	记录脱敏告警，不影响已经生成的请求级执行副本
请求副本清理失败	记录脱敏告警，后续请求不会把它当作缓存使用

[yeshion23333]

该方案已经实现：#4095