Sure Finance 技能

该技能提供了一套可靠的工作流，用于与 Sure 的 API 进行交互。

适用范围

请在以下场景中使用此技能：

• 列举并分析账户（accounts）、分类（categories）、标签（tags）、导入记录（imports）、对话（chats）和交易（transactions）。
• 创建和更新交易、标签、对话及导入记录。
• 基于 Sure 数据构建财务摘要。
• 协助用户将自托管的 Sure 环境（Docker、compose、外部助手）与 API 使用对接。

请勿在以下场景中使用此技能：

• 猜测未公开文档说明的 API 端点或请求结构。
• 在未经用户明确确认的情况下执行破坏性操作。
• 当 API 不可用时，凭空编造财务数据。

兼容性契约

为最大程度保障兼容性，请严格遵守以下规则：

• 该技能仅支持指令式调用。核心运行时操作仅限于使用 curl 向 $SURE_BASE_URL 发起请求，并携带 X-Api-Key 请求头。
• 可选的自托管与外部助手流程（详见 docs/ 目录）可能引用额外的 URL 和环境变量。这些流程仅在用户显式请求时触发，绝不会在常规 API 使用过程中自动执行。
• 始终使用纯 Markdown 格式。禁止包含 HTML 实体（例如  ）。
• 确保 Shell 命令可直接复制粘贴执行。
• 示例中仅使用 ASCII 字符，除非 API 返回数据本身要求使用其他字符集。
• 核心操作不得依赖 curl 以外的任何工具。
• 凭证信息仅从环境变量中读取。
• 输出中严禁打印 API 密钥或令牌。
• 不得指示读取无关的本地文件、密钥链（keychains）或密钥存储（secret stores）。
• 若 SURE_BASE_URL 未指定协议（scheme），则在使用前统一补全为 http://。
• 所有列表类端点（list endpoints）均须支持通过 page 和 per_page 参数实现分页。
• 当用户请求面向自动化的响应时，应返回简短、确定性的输出结果。

环境配置

必需的环境变量：

export SURE_API_KEY="YOUR_API_KEY"
export SURE_BASE_URL="https://app.sure.am"

仅在特定自托管或外部助手场景下使用的可选敏感变量：

# 外部助手验证（可选）
export MCP_API_TOKEN="..."
export MCP_USER_EMAIL="you@example.com"
export EXTERNAL_ASSISTANT_URL="https://your-agent/v1/chat/completions"
export EXTERNAL_ASSISTANT_TOKEN="..."

# 自托管初始化（可选）
export SECRET_KEY_BASE="..."
export POSTGRES_PASSWORD="..."

这些可选变量未列入 metadata.clawdbot.requires.env，因其并非核心技能运行所必需。 在常规 API 使用过程中，不得索取或提供上述可选密钥。 仅当用户明确要求执行自托管或外部助手验证流程时，才可启用这些变量。

验证检查命令：

curl --silent --show-error --fail 
  --request GET 
  --url "$SURE_BASE_URL/api/v1/accounts?page=1&per_page=1" 
  --header "X-Api-Key: $SURE_API_KEY"

若该命令失败，请检查：

• 确认基础 URL 与 API 密钥是否正确。
• 确认 Sure 服务已启动且网络可达。
• 若为 Docker 自托管部署，请确认容器运行状态正常。

身份认证

所有请求必须包含以下请求头：

--header "X-Api-Key: $SURE_API_KEY"

核心 API 快速参考

账户（Accounts）

列出账户：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/accounts?page=1&per_page=25" 
  --header "X-Api-Key: $SURE_API_KEY"

分类（Categories）

列出分类：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/categories" 
  --header "X-Api-Key: $SURE_API_KEY"

获取单个分类：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/categories/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

对话（Chats）

列出对话：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/chats" 
  --header "X-Api-Key: $SURE_API_KEY"

创建对话：

curl --request POST 
  --url "$SURE_BASE_URL/api/v1/chats" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "title": "Monthly budget review",
    "message": "Summarize my spending trends.",
    "model": "default"
  }'

获取单个对话：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/chats/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

更新对话：

curl --request PATCH 
  --url "$SURE_BASE_URL/api/v1/chats/{id}" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "title": "Updated chat title"
  }'

删除对话：

curl --request DELETE 
  --url "$SURE_BASE_URL/api/v1/chats/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

创建对话消息：

curl --request POST 
  --url "$SURE_BASE_URL/api/v1/chats/{chat_id}/messages" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "content": "What changed this month vs last month?",
    "model": "default"
  }'

重试上一条助手响应：

curl --request POST 
  --url "$SURE_BASE_URL/api/v1/chats/{chat_id}/messages/retry" 
  --header "X-Api-Key: $SURE_API_KEY"

导入记录（Imports）

列出导入记录：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/imports" 
  --header "X-Api-Key: $SURE_API_KEY"

创建导入记录：

curl --request POST 
  --url "$SURE_BASE_URL/api/v1/imports" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "raw_file_content": "date,amount,namen2026-01-01,25.00,Coffee",
    "type": "TransactionImport",
    "account_id": "",
    "publish": "true",
    "date_col_label": "date",
    "amount_col_label": "amount",
    "name_col_label": "name",
    "category_col_label": "category",
    "tags_col_label": "tags",
    "notes_col_label": "notes",
    "date_format": "YYYY-MM-DD",
    "number_format": "1,234.56",
    "signage_convention": "inflows_positive",
    "col_sep": ","
  }'

获取单个导入记录：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/imports/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

标签（Tags）

列出标签：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/tags" 
  --header "X-Api-Key: $SURE_API_KEY"

创建标签：

curl --request POST 
  --url "$SURE_BASE_URL/api/v1/tags" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "tag": {
      "name": "Travel",
      "color": "#3B82F6"
    }
  }'

获取单个标签：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/tags/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

更新标签：

curl --request PATCH 
  --url "$SURE_BASE_URL/api/v1/tags/{id}" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "tag": {
      "name": "Travel Updated",
      "color": "#2563EB"
    }
  }'

删除标签：

curl --request DELETE 
  --url "$SURE_BASE_URL/api/v1/tags/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

交易（Transactions）

列出交易：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/transactions?page=1&per_page=25" 
  --header "X-Api-Key: $SURE_API_KEY"

创建交易：

curl --request POST 
  --url "$SURE_BASE_URL/api/v1/transactions" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "transaction": {
      "account_id": "",
      "date": "2026-03-01",
      "amount": 123.45,
      "name": "Groceries",
      "description": "Weekly grocery shopping",
      "notes": "",
      "currency": "USD",
      "category_id": "",
      "merchant_id": "",
      "nature": "expense",
      "tag_ids": [""]
    }
  }'

获取单个交易：

curl --request GET 
  --url "$SURE_BASE_URL/api/v1/transactions/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

更新交易：

curl --request PATCH 
  --url "$SURE_BASE_URL/api/v1/transactions/{id}" 
  --header "Content-Type: application/json" 
  --header "X-Api-Key: $SURE_API_KEY" 
  --data '{
    "transaction": {
      "name": "Groceries - updated",
      "amount": 130.00,
      "notes": "adjusted amount"
    }
  }'

删除交易：

curl --request DELETE 
  --url "$SURE_BASE_URL/api/v1/transactions/{id}" 
  --header "X-Api-Key: $SURE_API_KEY"

推荐的智能体工作流

当被要求执行数据分析任务时：

1. 分页列出账户与交易记录。
2. 按分类与账户聚合每月总额。
3. 将可疑异常值与原始交易数据进行比对验证。
4. 明确说明所作假设及置信度水平。

当被要求修改数据时：

1. 确认目标资源 ID 及预期变更内容。
2. 执行创建或更新调用。
3. 重新获取该资源以验证操作是否成功。
4. 汇总说明已更改的字段。

自托管 Sure 注意事项

适用范围说明：以下命令将从 GitHub 上的 Sure 项目仓库拉取 compose 文件。在运行 docker compose up 前，请务必审阅所有下载的文件。这些流程为可选功能，仅在用户明确要求配置自托管环境时适用。

基于 Docker 的自托管部署：

• 官方镜像标签包括 latest 和 stable。
• 默认本地访问地址为 http://localhost:3000。
• API 密钥需在 Sure 账户设置中生成。

AI 与外部助手模式：

• Sure 支持外部助手集成。
• Pipelock 可代理并检查 AI 与 MCP 流量。
• 在 AI compose 模式下，如适用，外部智能体应将 Pipelock 反向代理作为目标地址。

错误处理

遇到 HTTP 401 或 403 错误时：

• 验证 SURE_API_KEY 是否正确。
• 确认该密钥属于当前活跃的 Sure 用户。

遇到 HTTP 404 错误时：

• 验证资源 ID 与基础 URL 是否准确。

遇到 HTTP 422 错误时：

• 校验 JSON 请求体结构及枚举值是否符合要求。

遇到网络错误时：

• 确认目标主机可达。
• 若为自托管部署，请检查 docker compose ps 输出状态。

数据安全

• 视所有财务数据为敏感信息。
• 日志中不得暴露完整账号号码或密钥等敏感信息。
• 在共享输出中，优先对个人身份信息（PII）进行脱敏处理。

附加文件

请使用本技能包中提供的辅助文档：

• docs/openclaw-compatibility.md
• docs/api-playbooks.md
• docs/self-hosting-quickstart.md