# Skill 操作

检查独立 Skill 的 operation catalog、所需 scope、确定性退出代码和 runtime 限制。

- Canonical: https://docs.xmemo.dev/zh/docs/skills/operations
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 6dd1506da83ca3c235a2b184eef2543b5c83a2510312e734028559bf4772ef75
- Edition-Digest: 5d4fd9bef7ad053d4a0988431237476258dda85cef0d3e0547d2314ddcb889c3
- Source-Revision: sha256:7b422494897f606128295ed70568337bc1353a0d7822638452970f4081f9e0ef

## 直接 HTTPS 操作与认证请求头

独立 Skill 通过 HTTPS 直接与 XMemo 通信。公开 REST 端点接受 Authorization: Bearer <token> 或 X-API-Key: <key> 请求头，而独立 Skill 运行时使用已解析 credential 自动将出站请求格式化为 Authorization: Bearer <token>。

- Skill 运行时传输：自动向发送到 https://xmemo.dev/v1/skill/operations 的所有请求注入 Authorization: Bearer <token>。
- REST API 灵活性：直接调用 REST 端点的独立 HTTP 客户端可以提供 Authorization: Bearer <token> 或 X-API-Key: <key>。
- 发现契约：运行时模型和操作端点可在 /.well-known/agent-discovery.json 和 /.well-known/memory-os.json 发现。

```http
# Skill runtime uses Bearer token authorization:
POST /v1/skill/operations
Authorization: Bearer <skill-token>
Content-Type: application/json

# Direct REST endpoints also accept X-API-Key:
GET /v1/memories/search?query=onboarding&limit=5
X-API-Key: <your-assigned-api-key>
```

## 按任务划分的完整命令清单

独立 Skill 软件包（v1.1.35）提供 32 条命令。以下列出了每条命令及其来自 help.mjs 的原样使用字符串和所需的授权 scope。

- 认证与设置：login --allow-plaintext, register --reason <unattended|declined> --allow-plaintext, logout [--revoke-environment-token], auth status [--verify], auth add --from-stdin --allow-plaintext, auth claim-status [--allow-plaintext], auth claim-confirm [--allow-plaintext], auth claim-deny [--allow-plaintext]。
- 记忆与搜索：read --id <id> [--offset <n>] [--limit <n>] [--bucket <bucket>] [--scope <scope>] (memory:read), update --id <id> [--content <text>] [--path <path>] [--metadata <json>] [--bucket <bucket>] [--scope <scope>] (memory:write), forget --id <id> [--reason <text>] --confirm (memory:delete or memory:write), remember (--content <text> | --content - | --file <path>) [--path <path>] [--metadata <json-object>] (memory:write), recall --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--expand-documents] [--compact] (memory:read), search --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--expand-documents] [--compact] (memory:read)。
- 知识上下文：recall-context --query <text> [--max_items <n>] [--max_tokens <n>] [--prefer_working <true|false>] [--include_knowledge <true|false>] (memory:read; opting into Knowledge with --include_knowledge true requires knowledge:read)。
- 任务连续性与快照：save-state --key <key> [--content <text>] [--ttl_seconds <0..604800>] (memory:write, alias: state-save), restore-state --key <key> (memory:read, alias: state-restore), state-save --key <key> [--content <text>] [--ttl_seconds <0..604800>] (legacy alias), state-restore --key <key> (legacy alias), restart-snapshot [--state_key <key>] [--session_id <id>] [--ttl_seconds <0..2592000>] (memory:write), restart-restore [--snapshot_id <id> | --source_session_id <id>] [--target_session_id <id>] (memory:read)。
- 任务待办事项：todo-add --content <text> (memory:write), todo-list (memory:read), todo-done --id <todo_id> (memory:write)。
- 财务账本与分析：expense-add --item <text> --amount <number> --currency <code> (ledger:write), ledger-list [--month <YYYY-MM>] [--from <date>] [--to <date>] [--currency <code>] [--category <name>] [--type <type>] [--min-amount <n>] [--max-amount <n>] [--limit <n>] [--offset <n>] (ledger:read), ledger-summary [--months <n>] [--currency <code>] [--type <type>] (ledger:read), overview (memory:read), activity [--limit <n>] (memory:read), stats [--scope <scope>] [--path <path>] [--bucket <bucket>] [--memory-type <type>] [--status <status>] [--source <src>] [--since <iso>] [--until <iso>] [--group-by <dims>] [--top-n <1..200>] [--team-id <id>] (memory:read)。
- 诊断与性能分析：doctor [--anonymous] (no scope required), profile [--status <later|never>] (no scope required)。

```bash
# Memory read and write operations:
node scripts/xmemo-skill.mjs remember --content "Production build uses node 22.22" --path "ops/build"
node scripts/xmemo-skill.mjs recall --query "build node version" --limit 3
node scripts/xmemo-skill.mjs read --id mem_01hxyz... --offset 0 --limit 1000
node scripts/xmemo-skill.mjs update --id mem_01hxyz... --content "Production build uses node 22.22.0 LTS"
node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm

# Context assembly with optional Knowledge inclusion:
node scripts/xmemo-skill.mjs recall-context --query "TLS root configuration" --include_knowledge true

# Task continuity and restart snapshots:
node scripts/xmemo-skill.mjs save-state --key active_task --content "Refactoring migration script"
node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928

# Ledger and analytics:
node scripts/xmemo-skill.mjs expense-add --item "Cloud hosting" --amount 120 --currency USD
node scripts/xmemo-skill.mjs overview
node scripts/xmemo-skill.mjs doctor
```

## 确定性退出代码

所有独立 Skill 命令在交互式和编程式执行中均遵循严格、确定性的退出代码。

- 代码 0（成功）：操作成功，返回了有效空结果集，--help 或 --version。
- 代码 1（用户错误）：参数验证错误、互斥参数、内容超过 524,288 字节、forget 缺少强制性 --confirm、输入文件缺失/不可读或 HTTP 4xx 响应。
- 代码 2（认证错误）：缺少 credential、token 已过期或无效、HTTP 401 Unauthorized、HTTP 403 Forbidden 或 doctor 认证验证失败。
- 代码 3（服务器/网络错误）：HTTP 5xx 响应、网络连接失败（ECONNREFUSED、ENOTFOUND、ETIMEDOUT）或响应负载超过安全上限（> 8 MiB）。

## 内容安全、文档存根与删除确认

独立 Skill 在发出网络请求前强制执行严格防护，以确保数据安全和客户端稳定性。

- 512 KiB 写入上限：记忆内容限制为 524,288 字节（MAX_MEMORY_CONTENT_BYTES）。超出此上限的输入在分发任何网络请求之前将立即以代码 1 退出。
- 互斥输入来源：remember 接受 --content <text>、--content -（管道标准输入）或 --file <path>。提供多个来源将在本地中止并退出，返回代码 1。
- 文档支持的记忆存根：当 recall 或 search 匹配到文档支持的记忆时，它会返回一个紧凑的单行存根（Document-backed memory: <title>）。传递 --expand-documents 可展开最多 3 个存根且总共最多 20,000 个字符，或使用 read --id <id> 进行定向分页读取。
- 强制确认保护：forget --id <id> --confirm 严格要求 --confirm。省略此标志将在本地中止并退出，返回代码 1，零网络请求。
- 全局执行选项：所有命令均接受 --json（原始 JSON 输出）、--terminal（在管道传输时保留人类可读格式）、--timeout-ms <ms>、--base-url <url> 和 --version。