# SeaCloud SDK Agent / Skill 用法

这份说明用于 agent、大模型和自动化测试快速选择 `@seacloudai/sdk` 的公开能力。

## 推荐入口

```ts
import { getSeaCloudDocs } from "@seacloudai/sdk";

const docs = getSeaCloudDocs();
```

`getSeaCloudDocs()` 是离线入口，不需要 `new SeaCloud`，不需要 `apiKey`，也不会发起网络请求。agent 可以先读取 `docs.methods` 决定调用哪个 SDK 方法，再读取 `operationManual.content` 和 `agentSkillUsage.content` 获取参数说明。

## 技能路由

| 需求 | 方法 | Repo skill |
| --- | --- | --- |
| SDK 总览、初始化、timeout、dryRun、错误处理 | `getSeaCloudDocs()` / `new SeaCloud(options)` | `skills/seacloud-sdk/SKILL.md` |
| 文本对话 | `client.chat.send()` | `skills/seacloud-chat-send/SKILL.md` |
| 创建 queue 任务 | `client.run(modelId, params, options?)` | `skills/seacloud-run/SKILL.md` |
| 创建任务并等待最终结果 | `client.runSync(modelId, params, options?)` | `skills/seacloud-run/SKILL.md` |
| 查询任务状态 | `client.tasks.get(taskId, options?)` | `skills/seacloud-tasks-get/SKILL.md` |
| 查询任务结果 | `client.tasks.getResponse(taskId, options?)` | `skills/seacloud-tasks-get/SKILL.md` |
| 列出模型 | `client.models.list(options?)` | `skills/seacloud-models-list/SKILL.md` |
| 读取模型合约 | `client.models.getSpec(modelId)` | `skills/seacloud-models-get-spec/SKILL.md` |
| 搜索 SkillHub | `client.skills.find(query, options?)` | `skills/seacloud-skills-find/SKILL.md` |
| 列出 SkillHub | `client.skills.list(options?)` | `skills/seacloud-skills-list/SKILL.md` |
| 读取 SDK 版本 | `client.version()` | `skills/seacloud-version/SKILL.md` |

## 生成任务决策

- 用户只想创建任务并自己轮询：使用 `client.run(modelId, params, options?)`。
- 用户想拿到最终结果：使用 `client.runSync(modelId, params, options?)`。
- 用户已经有 task id 和 statusUrl：使用 `client.tasks.get(taskId, { statusUrl })`。
- 用户已经有 responseUrl：使用 `client.tasks.getResponse(taskId, { responseUrl })`。
- 需要人工检查模型参数时：使用 `client.models.getSpec(modelId)`；它读取 `model-contracts` 接口。
- `run()` 和 `runSync()` 默认读取模型契约，等价于 `contract: "auto"`：用契约规划 protocol、body mode、queue endpoint 和 headers；如果 `input_schema.required` 非空，只检查这些顶层必传字段是否存在；契约不可用时回退 raw queue。
- 只有显式传 `contract: "off"` 时，SDK 才完全跳过模型契约读取，直接把 `params` 作为 raw JSON 提交到 `/model/v1/queue/{modelId}`。
- SDK 的 `params` 始终是 JavaScript 对象；不要传字符串形式的命令参数。
- 人类开发者仍需要按模型语义传入 `params`；除 `input_schema.required` 顶层存在性检查外，模型业务参数的默认值、类型和互斥规则由接口校验，SDK 不会自动上传本地文件。
- 不要传 `onProgress`；后端生命周期接口没有可信进度，SDK 不伪造进度。

## 约束

- `new SeaCloud({ apiKey })` 必须显式传入 `apiKey`。
- SDK 不从环境变量读取 `apiKey`。
- SDK 不负责交互界面、配置文件发现或凭据存储。
- `getSeaCloudDocs()` 是帮助 agent 理解 SDK 用法的本地文档接口，不代表网络服务能力。