# Cloud Skills

渐进式召回可复用的版本化规程，并在已连接的 Agent 间解释结构化操作 Runbook。

- Canonical: https://docs.xmemo.dev/zh/docs/concepts/cloud-skills
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 049066d1073d736057a89262336d6fb1f3a45bde8716106959785c6f135bcab3
- Edition-Digest: f1826c0a3d1baf87c1b1eca8000ece6fc936f41729e3f740401d7ee3a9e52bc6
- Source-Revision: sha256:ed4540a74de987fd5125f372ab4ee2ea3f4d70303dedb8cef36a3395d3de069a

## 程序性记忆与 Skill 架构

Cloud Skills 在 XMemo 中提供用户编写的程序性记忆，使开发人员和团队能够将标准操作规程（SOP）、Runbook、清单和可复用 Prompt 直接保存到持久存储中。一旦保存，支持工具中的已连接 Agent 即可发现、召回并解释它们，无需为每个 Agent 独立安装或手动复制 Prompt。已存储的 Cloud Skill 与安装的 XMemo Skill 客户端运行时（@xmemo/skill，node scripts/xmemo-skill.mjs）截然不同，后者用作 Agent 端的连接桥梁。

- Preview 功能：Cloud Skills 目前在 Memory Console（#skills）中处于 Preview 状态。
- 身份与资产：每个 Skill 都有唯一的 skill_id、易读的 slug、名称、描述、所有者作用域（Personal 或 Team）以及资产状态（active 或 archived）。
- 不可变修订链：Skill 包含 SkillRevision 快照的仅追加（append-only）序列。每个修订版携带 revision_id、revision_number、instruction_body、canonical_hash 以及可选的类型化 SkillComponent 资源。
- 大小限制：根指令主体限制在 64 KiB UTF-8 以内。一个修订版最多可包含 50 个声明的组件，每个组件限制在 128 KiB 以内。
- 组件资源类型：组件声明明确的语义类型，包括 reference、example、template、document、artifact 和 script。

## 发布生命周期与团队审核

Cloud Skill 修订版通过结构化生命周期转换，以保护生产工作流并支持协同创作：

- draft：创作和私有暂存期间的初始修订版状态，尚未公开发布激活。
- proposed：在 Team 工作区内编写的修订版会转换为 proposed 状态，等待团队所有者或管理员的明确审核与激活。
- published：具备 Agent 发现资格和默认 Level 1 召回资格的有效修订版。每个 slug 在任何给定时间仅有一个修订版被指定为 published。
- deprecated：较旧或被取代的修订版可标记为 deprecated 以提示下线，同时保留历史可复现召回能力。
- 个人与团队发布区别：在个人工作区中，带有发布意图的保存会直接转换为 published。在团队工作区中，提议的（proposed）修订版可防止未经审核的规程变更修改 Agent 工作流。

## 渐进式召回：Level 0、Level 1、Level 2

已连接的 Agent 使用 Progressive Recall 按需召回技能，防止未使用的文档挤满 LLM 上下文窗口：

- Level 0（发现）：查询搜索返回与用户任务匹配的轻量描述符（slug、name、description），无需加载完整指令。
- Level 1（根召回）：召回指定 slug 的技能根指令和组件清单，默认使用已发布修订版并具备最新修订版回退能力。
- Level 2（资源召回）：召回单个声明的组件（例如清单模板或参考 Schema），要求调用者提供明确的 revision_id 以避免资源分歧（resource tearing）。

```text
recall_cloud_skill(query="incident response")  # Level 0: lightweight descriptors
recall_cloud_skill(slug="incident-response-checklist")  # Level 1: root instructions + manifest
recall_cloud_skill(
  slug="incident-response-checklist",
  revision_id="<revision-id-from-level-1>",
  resource="templates/triage-template.md",
)  # Level 2: one pinned resource component
```

## 固定 revision 可避免 resource tearing

当 Skill 更新时，XMemo 会创建下一个不可变修订版，而不是覆盖历史内容。Level 1 根召回提供根指令以及不可变的 revision_id 和组件清单。Level 2 资源请求要求调用者固定该确切的 revision_id。如果作者在 Agent 执行工作流时发布了新修订版，Agent 的固定读取仍会继续解析其开始时的确切快照，从而彻底消除资源分歧。

```json
{
  "kind": "root",
  "data": {
    "skill_id": "skill_inc_triage_01",
    "revision_id": "rev_v1_inc_triage",
    "revision_number": 1,
    "canonical_hash": "c7b14d8e9f2a4c10...",
    "resources": [
      {
        "logical_path": "templates/triage-template.md",
        "type": "template",
        "content_hash": "e3b0c44298fc1c14..."
      }
    ]
  }
}
```

## 导入、导出与创作界面

开发人员可以在 Web 控制台中交互式编写 Cloud Skills，或从标准分发包导入现有技能：

- 控制台创作：在 Memory Console（#skills）中使用 Markdown 编辑器和组件管理交互式创建技能。
- 软件包导入：导入标准 SKILL.md 文件（带有 YAML 前言）、多文件 ZIP 压缩包或通过 URL（ClawHub 或 GitHub）导入远程仓库。
- 修订版差异对比：通过词级 Diff 对比任意两个修订版之间的指令变更和组件修改。
- Source Capsule 导出：将任何 Skill 修订版导出为无损 Source Capsule ZIP 压缩包，包含 SKILL.md、组件资源和元数据清单。

## Agent 访问配置文件与 Sandbox 隔离

获授权的 Agent 在支持的客户端环境中通过契约化定义的 MCP 工具访问 Cloud Skills：

- 契约化 MCP 工具：工具 recall_cloud_skill（只读）和 save_cloud_skill（创作）在 cursor-plugin 和 ordinary-full 客户端配置文件中按契约公开（config/mcp-documentation-contract.json）。它们不会在 generic-public、chatgpt-public 或 claude-code 配置文件中公开。
- Prompt 可执行规程：大多数 Cloud Skills 都是标准操作规程，由 Agent 直接解释为 Prompt 指导而无需代码执行。
- Sandbox 执行边界：通过 execute_cloud_skill 进行的可选后端脚本执行是由 SandboxExecutionEngine 治理的高级服务端功能（目前未向任何客户端配置文件公开）。当本地缺乏 bubblewrap 容器隔离时，执行将以 SANDBOX_UNAVAILABLE 进行闭环失败处理（fail closed）。

## 可用性与生命周期边界

如果您的账户启用了程序性 Cloud Skills，则可以使用 Cloud Skill 功能。修订版是不可变的内容寻址快照，保存更改会创建新修订版而不会覆盖历史记录。当存在候选技能时，控制台会显示需要显式手动提升的审核横幅。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。