# 乾坤袋

> 智能体可以直接调用、可信执行的工具层。

## 开始

大部分工具（free 级别）免注册即可直接调用，无需任何凭证。只有当需要持久化资源（文件存储、表格、长期记忆）或计费能力时，才需要注册：

1. [工具列表](https://tools.k6-12.com/api/tools/?channel=all)：GET，全部启用工具（名称、描述、标签、访问级别）；先按需求选工具
2. [操作列表](https://tools.k6-12.com/api/catalog/operations?toolCode=<code>)：GET，该工具的可调用操作；多动词工具（文件 / 表格 / 记忆）会展开成多条
3. [操作 schema](https://tools.k6-12.com/api/catalog/operations/<operationId>/schema)：GET，入参 JSON Schema
4. [当前授权](https://tools.k6-12.com/api/me/capabilities/)：GET，这张凭证能调什么、还差什么（需凭证）
5. [注册](https://tools.k6-12.com/api/auth/register/)：POST 用户名 + 密码，返回会话令牌（仅在需要持久化资源或计费能力时）
6. [登录](https://tools.k6-12.com/api/auth/login/password/)：已有账号 POST `identifier` + `password` 换回会话令牌；`identifier` 可填用户名、邮箱或手机号
7. [OpenAPI](https://tools.k6-12.com/api/openapi.json)：基础设施端点与统一错误结构
8. [MCP 端点](https://tools.k6-12.com/mcp/)：需要人工在客户端配置，HTTP 是首选接入面

注册或登录成功后，后续请求带 `Authorization: Bearer <token>`（会话令牌，或账户里签发的 `tk_` 开头的 API Key）。

选好操作后，按操作详情的 `invoke` 调用；多动词操作还要带上 `fixedBody.action`。

## 工具类别

- 存储与记忆：文件存储、表格存储、长期记忆笔记
- 图片：压缩、格式转换、拼接、九宫格、水印、EXIF、证件照、二维码 / 条形码
- 文档：PDF 合并、拆分、压缩、加密、签名、水印、元数据、信息查询、文字 / 图片 / 表格提取、转 Word / 图片、差异对比
- AI 生成与识别：OCR 文字识别、语音转文字、文本转语音、AI 生图
- 开发与文本：JSON / SQL 格式化、正则测试、简繁转换、拼音
- 安全与编码：加密解密、哈希、HMAC、密钥生成、Base64 / 编码转换
- 网络：IP 归属地查询

类别与工具会增删，以 `/api/tools/` 的返回为准。

## 调用

- 同步：`POST /api/tools/<code>/`，请求体即操作 schema
- 异步：`POST /api/jobs/<code>/`，返回 `taskRef` 与 `links`
- 查询任务：`GET /api/tasks/<taskRef>/`；等待：`.../wait/`；取结果：`.../result`
- 取产物：按任务详情里的 `outputs[].readWith` 调用，不要用网页的 `downloadUrl`
- 分页：工具列表用 `page` / `page_size`（默认且最大 200）；操作目录用 `cursor` / `limit`（默认 20、最大 50）
- 已知道要做什么但不知道选哪个工具时，可直接搜索：`GET /api/catalog/operations?q=<自然语言>`

## 约束

- 会产生重复副作用的操作支持 `Idempotency-Key`；超时重试请带同一个键
- 付费操作先看目录里的 `estimatedCost`，精确报价用 `quoteWith`
- 出错时读 `error.remediation`：`operationId` 是下一步可调用的操作
- 任务状态以 `queued/running/requires_action/succeeded/failed/cancelled` 为准