# Cloud Skills 指南

在连接的 agent 之间编写、审核、发布和渐进式召回可复用的过程性技能。

- Canonical: https://docs.xmemo.dev/zh/docs/guides/cloud-skills
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: bff532eedc870bca9f5f7c7413891d20ab5e233fb9fdcccd4e6d38b38aba2d9e
- Edition-Digest: a83ddb3a4ada8a1e80c52890ef4c6d41bb6bb93f23efc66cd91694a14a42b93d
- Source-Revision: sha256:2ed8d0fb7f3432c8695de21a099b7ce6fd715f59effbe3a2bb60822a68e1af34

## 用户目标

在连接的 agent 之间编写、审核、发布和召回可复用的过程性技能（例如运行手册、核对清单和标准操作程序），无需手动复制粘贴、重复的每 agent 配置或引起上下文窗口膨胀。

## 可用性与前提条件

Cloud Skills 目前在 Memory Console (https://xmemo.dev/me#skills) 中处于 Preview 状态。在编写或召回技能之前，请确保您的环境满足以下要求：

- 功能启用：当您的账户启用了过程性 Cloud Skills 时处于活动状态。
- 工作区选择：个人空间 (https://xmemo.dev/me#skills) 存储私有技能。团队空间 (https://xmemo.dev/me?space=<team_id>#skills) 在经过身份验证的团队成员之间共享技能，并提供基于角色的治理。
- Agent 令牌作用域：Agent 召回需要 skills:read 或 memory:read 作用域。技能创建和修订版本发布需要 skills:write 或 memory:write 作用域。
- 支持的客户端配置文件：MCP 工具 recall_cloud_skill 和 save_cloud_skill 在 cursor-plugin 和 ordinary-full 客户端配置文件中提供；通用的公共界面和聊天界面不直接提供技能编写工具。

## 1. 导航到 Memory Console 中的 Cloud Skills

打开 Memory Console 并选择 Cloud Skills 部分：

- 个人空间：打开 https://xmemo.dev/me#skills 以管理您的个人过程性运行手册。
- 团队空间：打开 https://xmemo.dev/me?space=<team_id>#skills 以管理共享的组织技能。
- 控制台界面：面板显示技能列表、搜索栏 ("Search skills by name, slug, or keywords...") 以及主要操作："New Skill" 和 "Import Skill"。

## 2. 编写过程性技能和声明的组件

点击 "New Skill" 打开技能编写模态框。配置技能元数据、根指令和组件资源：

- Skill Name：输入 "Incident Response Checklist"（必填字段）。
- Slug：输入小写标识符 "incident-response-checklist"（1–64 个字母数字字符或连字符）。
- Description：输入 "Standard operating procedure for triaging and resolving high-severity production incidents."。
- Instructions：用 markdown 编写根过程性指导（限制为 64 KiB UTF-8）。
- Components：添加包含事件问卷且类型为 template 的模板组件 templates/triage-template.md。

```markdown
# Incident Response Checklist

When a high-severity production alert triggers:
1. Identify the impacted service and declare an incident channel.
2. Verify service error rates and recent deployment events.
3. Complete the triage questionnaire at `templates/triage-template.md`.
4. Apply documented mitigation or initiate canary rollback.
5. Record timeline events and assign follow-up action items.
```

## 3. 审核并发布技能修订版本

保存技能修订版本并观察发布在个人和团队空间中的表现：

- 个人发布：在个人工作区中，带有发布意图的保存会将修订版本 v1 直接转换为 "Published"，使其可立即被授权的 agent 发现。
- 团队审核工作流：在团队工作区中，保存会创建状态为 "proposed" 的修订版本 v1。在团队所有者或管理员发布修订版本之前，团队成员可以审核指令、检查组件 diff 并测试执行。
- 草稿暂存：如果未勾选发布意图，修订版本将保持在 "Draft" 状态，以便进行私密编辑和测试，而不会暴露给 agent 发现。

## 4. 验证 agent 渐进式召回

连接的 agent 根据需要在三个渐进式层级中查询和检索已发布的技能，以节省上下文预算：

- 第 0 层（发现）：Agent 按任务查询进行搜索，并在没有完整指令的情况下接收轻量级描述符。
- 第 1 层（根指令）：Agent 使用技能 slug 召回根指令和组件清单。
- 第 2 层（固定资源）：Agent 通过提供从第 1 层返回的确切 revision_id 来检索声明的模板组件。

```text
# Level 0: Discover relevant skills by task query
recall_cloud_skill(query="incident response")

# Level 1: Retrieve root instructions and component manifest
recall_cloud_skill(slug="incident-response-checklist")

# Level 2: Retrieve pinned component resource without resource tearing
recall_cloud_skill(
  slug="incident-response-checklist",
  revision_id="<revision-id-from-level-1>",
  resource="templates/triage-template.md",
)
```

## 5. 更新程序并验证修订版本不可变性

当操作要求发生变化时，更新技能以创建新的不可变修订版本：

- 打开技能详情：在控制台中，选择 "Incident Response Checklist" 并点击 "New Revision"。
- 修改指令：在回滚之前添加强制性的金丝雀验证步骤。
- 保存新修订版本：保存内容会将修订版本计数器递增至 v2，生成新的不可变 revision_id 和 canonical_hash。
- 修订版本固定保护：固定到修订版本 v1 的进行中 agent 工作流将继续读取 v1 资源而不会撕裂，而新的第 1 层查询会自动解析已发布的 v2 修订版本。

## 可观察结果

成功的 Cloud Skill 创建和发布会在控制台和 agent 界面上产生可观察的变化：

- 控制台状态徽章：技能卡片显示 "Published" 徽章、活动修订版本标签（例如 v1 或 v2）和组件数量。
- 资源管理器：详细信息视图显示声明的 templates/triage-template.md 组件，并带有语法预览和复制操作。
- Agent 召回封装：第 1 层返回带有 instruction_body、revision_id 和 resources 列表的类型化根响应。第 2 层返回确切的组件文本。
- 导出可用性：在详细信息视图中，点击 "Export" 可下载包含 SKILL.md、清单元数据和声明组件的 Source Capsule ZIP 归档。

## Agent 可以访问的内容

Agent 和人类用户在严格的身份验证和能力边界下运行：

- 客户端配置文件：MCP 工具 recall_cloud_skill 和 save_cloud_skill 契约化地在 cursor-plugin 和 ordinary-full 配置文件中提供；通用的公共和聊天客户端配置文件不公开它们。
- 作用域强制执行：Agent 使用带有 skills:read 或 skills:write 作用域的 API 密钥或 OAuth 令牌进行身份验证。作用域限定为个人记忆的令牌无法检查团队技能，除非显式绑定到该团队。
- 草稿和提议保护：Agent 无法在第 0 层查询发现中发现或召回草稿修订版本、等待审核的提议修订版本或已归档的技能。
- Prompt 可执行指导：连接的 agent 将过程性指令直接解释为 prompt 上下文；技能不会在主机上自动执行代码。

## 共享与生命周期边界

Cloud Skills 在个人运行手册与协作团队资产之间保持明确的租户隔离：

- 空间边界：个人技能 (/me#skills) 对创建者私有。团队技能 (?space=<team_id>#skills) 与经过身份验证的团队成员共享。
- 团队审批：团队修订版本在从 proposed 状态转换到 published 状态之前需要所有者或管理员审核。
- 归档与删除：归档技能 (DELETE /v1/skills/{skill_id}) 会禁用 agent 发现并将其从活动列表中隐藏，同时保留不可变修订版本历史。
- 修订版本不可变性：修订版本是内容寻址的不可变快照；保存更新会创建新修订版本，而不是覆盖现有记录。
- 候选者审核横幅：当存在候选者时，控制台可以显示带有 Promote 和 Dismiss 操作的候选者横幅；候选者需要人工审核。

## 故障恢复

使用以下补救步骤诊断并解决常见的 Cloud Skill 问题：

- 资源召回错误 (REVISION_PINNING_VIOLATION)：第 2 层资源请求需要显式的 revision_id。如果省略，服务器将拒绝请求以防止资源撕裂。修复方法：传递第 1 层响应中返回的 revision_id。
- 未找到技能 (SKILL_NOT_FOUND)：验证 slug 是否完全匹配，以及查询是否在正确的工作区中执行（个人对比团队 ?space=<team_id>）。
- 访问被拒绝 (403 Forbidden)：检查 agent 令牌是否包含 skills:read（用于召回）或 skills:write（用于保存），以及经过身份验证的用户是否属于目标团队。
- 团队修订版本保持提议状态：查询团队技能的 agent 将接收当前发布的修订版本，直到团队所有者或管理员审核并发布提议的修订版本。
- 运行时不可用 (503)：如果您的部署环境中禁用了 Cloud Skills 子系统或未进行配置，则返回此错误。

## 相关参考

有关概念架构、工具参数和团队协作，请参阅相关文档：

- Cloud Skills 概念：/docs/concepts/cloud-skills 了解三层架构、组件模型和修订版本固定。
- recall_cloud_skill 参考：/docs/tools/recall-cloud-skill 了解参数模式和响应格式。
- save_cloud_skill 参考：/docs/tools/save-cloud-skill 了解编写参数和组件上传格式。
- Memory Console：/docs/guides/memory-console 了解 Web 控制台布局、空间选择和设置。
- Teams：/docs/capabilities/teams 了解团队工作区协作和角色权限。

## 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 不会每次启动都重新生成它。