开发者文档

RKT 协议 v1.0 — 完整参考手册

Manifest 结构

每个 Bundle 的核心是一个 manifest.json 文件，遵循 RKT 协议 v1.0 规范。当前阶段 Bundle 是最小交易单元（最小 = 1 Role + 0~N Kit）。

字段	类型	必须	说明
`rktVersion`	string	必填	协议版本（当前 "1.0"）
`id`	string	必填	唯一标识符（kebab-case）
`version`	string	必填	Bundle 版本（语义化版本）
`name`	string	必填	显示名称
`summary`	string	必填	一句话描述
`targetUser`	string	必填	目标用户
`roles`	Role[]	必填	角色定义数组（≥1）
`kits`	Kit[]	可选	能力包数组
`teams`	Team[]	可选	协作团队定义
`mode`	enum	可选	`single` \| `team`
`activationScope`	enum	可选	`session` \| `agent` \| `workspace` \| `global`
`rollbackProfile`	object	必填	回滚策略配置
`assertions`	Assertion[]	可选	契约测试声明
`author`	string	新增	发布者/作者
`tags`	string[]	新增	市场标签
`category`	string	新增	市场分类
`license`	string	新增	许可证（默认 MIT）

四大对象

Role 角色

{
  "id": "analyst",
  "label": "数据分析师",
  "purpose": "负责数据清洗和趋势分析",
  "description": "专注于金融数据的深度分析",
  "thinkingLevel": "deep",
  "isEntry": true,
  "responsibilities": ["数据清洗", "趋势分析"],
  "boundaries": ["不执行写操作"],
  "kits": ["data-kit", "chart-kit"],
  "input": { "type": "json", "schema": null },
  "output": { "type": "structured", "schema": null }
}

字段	类型	说明
`id` / `label`	string	必填唯一标识 / 显示名称
`purpose`	string	角色目的
`description`	string	新增详细描述
`thinkingLevel`	enum	新增 `none` \| `normal` \| `deep`
`kits`	string[]	新增可使用的 Kit ID 列表
`input` / `output`	object	输入输出规范 `{ type: text\|json\|file\|structured }`
`responsibilities`	string[]	职责列表
`boundaries`	string[]	边界声明（不做什么）
`isEntry`	boolean	入口角色（Team 中使用）
`tradable`	boolean	Phase 2 是否可独立交易

Kit 能力包

{
  "id": "web-search",
  "label": "网页搜索",
  "description": "实时网页搜索能力",
  "capabilities": ["关键词搜索", "实时新闻"],
  "riskLevel": "low",
  "runtime": "node",
  "entryPoint": "search.js",
  "toolBinding": { "type": "mcp", "config": { "server": "search-api" } },
  "permissions": [
    { "type": "network", "target": "https://api.search.com", "mode": "read" }
  ],
  "mirror": {
    "source": "roleos-mirror://official",
    "digest": "sha256:f1e2d3c4b5a6",
    "lockedAt": "2026-03-25T00:00:00Z",
    "autoUpdate": false,
    "clawHubRef": "web-search@1.0.0"
  }
}

字段	类型	说明
`id` / `label`	string	必填
`description`	string	新增能力描述
`capabilities`	string[]	必填能力标识符列表
`riskLevel`	enum	`low` \| `medium` \| `high` \| `critical`
`runtime`	enum	新增 `node` \| `python` \| `binary` \| `docker` \| `mcp-server`
`entryPoint`	string	新增入口文件
`toolBinding`	object	`{ type: mcp\|function\|http\|cli, config }`
`permissions`	array	新增 `[{ type, target, mode }]`
`mirror`	object	新增受控镜像策略（见下文）
`tradable`	boolean	Phase 2

Team 协作

{
  "id": "research-team",
  "label": "研究团队",
  "topology": "pipeline",
  "entryRoleId": "analyst",
  "concurrencyMode": "sequential",
  "members": [
    { "id": "analyst", "isEntry": true },
    { "id": "writer" }
  ],
  "handoffGraph": [
    { "source": "analyst", "target": "writer", "type": "sequential", "label": "分析完成" }
  ],
  "terminationRules": ["报告已生成"],
  "degradationStrategy": {
    "toolMissing": "skip",
    "permDenied": "escalate",
    "modelWeak": "fallback",
    "timeout": "retry"
  },
  "humanEscalation": { "enabled": true, "maxRetries": 3 }
}

字段	类型	说明
`id` / `label`	string	必填
`topology`	enum	新增 `single` \| `hierarchical` \| `pipeline` \| `parallel` \| `mesh`
`entryRoleId`	string	新增入口 Role ID
`concurrencyMode`	enum	新增 `sequential` \| `parallel` \| `mixed`
`members`	array	成员列表
`handoffGraph`	HandoffEdge[]	交接路线（见下文）
`terminationRules`	string[]	必填终止规则
`degradationStrategy`	object	增强细粒度降级 `{ toolMissing, permDenied, modelWeak, timeout }`
`humanEscalation`	object	`{ enabled, condition?, maxRetries? }`
`tradable`	boolean	Phase 2

🔒 Kit 受控镜像策略

Kit 挂载的 Skills 从 ClawHub 获取但版本哈希锁定，禁止热更新，确保 Bundle 功能稳定：

字段	类型	说明
`source`	string	镜像来源（如 `roleos-mirror://official`）
`digest`	string	内容哈希（`sha256:xxx`）— 版本锁定
`lockedAt`	string	锁定时间 ISO 8601
`autoUpdate`	boolean	默认 false — 禁止热更新
`clawHubRef`	string	ClawHub 对照源引用（如 `weather@1.2.0`）
`updateCheckInterval`	number	更新检查间隔（天）

⚠️ 为什么禁止热更新？ 第三方 Skills 的版本变化可能导致 Bundle 行为不可预测。RKT 通过 digest 哈希锁定确保安装时的 Skill 版本与开发时完全一致。Validator L4 会对 autoUpdate: true 发出警告。

Handoff 边定义

Team 的 handoffGraph 中每条边描述 Role 之间的交接方式：

字段	类型	必须	说明
`source`	string	必填	来源 Role/Kit ID
`target`	string	必填	目标 Role/Kit ID
`type`	enum	建议	`dispatch` \| `sequential` \| `parallel` \| `conditional` \| `fallback` \| `kit-attach`
`condition`	string	可选	条件表达式（conditional 类型）
`priority`	number	可选	优先级（fallback 排序）
`label`	string	可选	显示标签

6 层 Validator

层级	名称	检查内容
L1	包体结构	必填字段存在、rktVersion 有效
L2	语义对象	Role id 唯一、Kit capabilities 非空、runtime 枚举、thinkingLevel 枚举、handoff 边类型
L3	依赖兼容	协议版本兼容、Kit 依赖解析、mirror.digest 哈希校验
L4	权限隔离	Kit 风险等级审核、permissions 权限清单、autoUpdate 热更新警告
L5	运行时确定	rollbackProfile、activationScope、projectionPlan
L6	体验可转译	summary、description、author、Role 可读描述

版本演化

RKT 协议使用 Major.Minor 二段式版本号。

Minor 升级（1.0 → 1.1）：向后兼容，只新增可选字段
Major 升级（1.x → 2.0）：可能不兼容，需迁移工具 + 6 个月过渡期
Bundle 自身版本使用三段式语义化版本号（如 1.2.3）

🔮 Phase 2 升级路线

当前阶段 Bundle 是最小交易单元，所有对象已预留独立交易字段：

预留字段	类型	说明
`tradable`	boolean	是否可独立交易（当前默认 false）
`version`	string	独立版本号
`author`	string	作者/发布者
`tags`	string[]	市场标签

Phase 2 升级时，Role/Kit/Team 均可独立上架市场、独立更新版本、自由组合成新 Bundle。Bundle 从"最小交易单元"升级为"组合包"。

API — 激活 Bundle

POST /api/activate
Content-Type: application/json

{ "manifest": { ... } }

→ 200: { bundleName, workspace, filesCreated, ... }
→ 422: { error, validation: { ... } }

API — 验证 Bundle

POST /api/validate
{ "manifest": { ... } }
→ { valid, passedLevels, totalLevels, results, errors, warnings }

API — Shadow Runtime

POST /api/shadow-preview
{ "manifest": { ... } }
→ { preview: { headline, members, capabilities, risk, ... }, markdown }

CLI 命令参考

命令	说明
`roleos init`	初始化 ROLEOS + 检测 Runtime
`roleos start`	启动控制层
`roleos stop`	停止控制层
`roleos status`	查看 Bundle 和路由状态
`roleos install <id>`	安装 Bundle
`roleos uninstall <id>`	卸载 Bundle
`roleos login`	登录 roleos.ai

入门

协议规范

API 参考

CLI

更多