# SeaCloud TypeScript SDK Agent Entry

本文件是 `@seacloudai/sdk` 仓库的仓库级智能体入口。进入项目后先读这里，再按需读取 `README.md`、`README.zh-CN.md`、`docs/` 和 `skills/` 下的专项技能。

## 项目定位

`@seacloudai/sdk` 是 SeaCloud 生成 API 的 TypeScript SDK。它是代码 SDK，只暴露类型化的 JavaScript/TypeScript 方法并返回数据对象，不负责交互界面或凭据存储。

核心约束：

- `new SeaCloud({ apiKey })` 必须显式传入非空 `apiKey`。
- SDK 不能从环境变量读取、猜测或兜底 `apiKey`。
- 服务域名不能散落在资源方法里硬编码；统一由 `.env.prod` / `.env.local` 生成到 `src/core/default-base-urls.ts`，再由 `src/core/config.ts` 读取。
- 对外类型、运行时行为、README、docs、skills 和测试必须保持同步。

## 环境变量规则

本仓库的 env 文件只放服务地址覆盖值，不放真实 API key、token、账号密码或用户数据。

- SDK 内置公开生产服务端点；普通调用方只需要显式传 `apiKey`。
- 远程仓库只保留 `.env.prod`，用于生成 `src/core/default-base-urls.ts`，让公开默认构建、CI、发布前检查和 npm 包发布显式使用同一组生产端点。
- `.env.local` 只用于本机维护者开发，必须被 `.gitignore` 忽略，不能提交到远程仓库。
- 如果本地需要覆盖生产域名，自行创建 `.env.local`，并保持与 `.env.prod` 同一组 key。
- 如果要调整公开默认接口域名，优先改 `.env.prod`，再运行 `npm run generate:prod`，并同步配置层测试；不要直接在 `src/resources/`、`src/domain/` 或普通测试断言里写新域名。

固定 key：

```bash
SEACLOUD_LLM_BASE_URL=
SEACLOUD_QUEUE_BASE_URL=
SEACLOUD_MODEL_LIST_BASE_URL=
SEACLOUD_MODEL_SPEC_BASE_URL=
SEACLOUD_SKILLHUB_BASE_URL=
```

`SEACLOUD_SKILLHUB_BASE_URL` 必须是 SkillHub API 根路径，例如包含 `/api/v1`。资源层会在这个根路径后继续拼接 `/search`、`/skills` 等业务路径。

## 常用命令

```bash
npm install
npm run typecheck
npm test
npm run build
```

公开默认命令会通过 `scripts/generate-base-urls.mjs` 从 `.env.prod` 生成 `src/core/default-base-urls.ts`：

- `npm run build` 使用 `.env.prod`。
- `npm run typecheck` 使用 `.env.prod`。
- `npm test` 使用 `.env.prod`，先构建再执行 `node --test`。

维护者本地开发可以显式使用未入库的 `.env.local`：

```bash
npm run build:local
npm run typecheck:local
npm run test:local
```

发布前使用生产 env：

```bash
npm run build:prod
npm run test:prod
npm run release:check
```

`npm run release:check` 使用 `.env.prod` 执行类型检查、测试和 `npm pack --dry-run`。如果用户要求推送、发版或打 tag，必须先跑这个命令；不要在只完成本地代码修改时默认 push 或 tag。

## 目录职责

```text
src/
  client.ts              SeaCloud 门面和资源装配
  index.ts               对外导出
  core/                  运行时配置、HTTP 客户端、错误、版本
  domain/                模型别名、响应映射、任务结果归一化
  resources/             SDK 功能区资源类，不能硬编码服务域名
  types/                 按功能分组的公开类型
  utils/                 小型共享对象和 URL 工具
scripts/                 构建、发布和 env 加载辅助脚本
test/                    基于构建产物的 SDK 行为测试
docs/                    随包文档和操作说明
skills/                  面向 SDK 使用的项目本地智能体技能
dist/                    构建产物，不手工编辑
```

代码分层原则：

- `client.ts` 只负责门面、默认配置和资源装配。
- `core/config.ts` 是服务地址默认值和 env 覆盖读取的唯一入口；新增服务地址时同步补齐 env 文件、类型和测试。
- `resources/` 负责 SDK 方法语义和调用编排，只使用 `RuntimeConfig` 中的地址。
- `core/http-client.ts` 负责传输、超时、请求头、错误映射。
- `domain/` 负责业务规则、响应映射和任务结果归一化，不混入 HTTP 细节。
- `types/` 只放公开类型；新增公开返回结构时同步导出。

## 智能体技能入口

通用 SDK 使用指南：

- `skills/seacloud-sdk/SKILL.md`

按方法拆分的专项技能：

- `skills/seacloud-chat-send/SKILL.md`
- `skills/seacloud-run/SKILL.md`
- `skills/seacloud-models-list/SKILL.md`
- `skills/seacloud-models-get-spec/SKILL.md`
- `skills/seacloud-tasks-get/SKILL.md`
- `skills/seacloud-skills-find/SKILL.md`
- `skills/seacloud-skills-list/SKILL.md`
- `skills/seacloud-version/SKILL.md`
- `skills/seacloud-errors/SKILL.md`

如果任务是解释 SDK 用法、选择方法、初始化客户端、使用 `timeout` / `dryRun` 或处理错误，优先读取 `skills/seacloud-sdk/SKILL.md`，再进入具体方法技能。

## 变更准则

- 新增资源方法时，同时补齐 `src/resources/`、`src/types/`、`src/index.ts` 导出、README 示例或 API 表、测试。
- 改动请求或响应映射时，优先在 `domain/response-mappers.ts` 或对应资源中集中处理，不把映射逻辑散落到调用方。
- 改动参数校验时，保持 `dryRun` 路径也会走同样校验。
- 新增错误类型时，更新 `src/core/errors.ts`、公开导出和 `skills/seacloud-errors/SKILL.md`。
- 不手工修改 `dist/`；通过 `npm run build`、`npm test` 或发布检查生成。
- 不提交真实 API key、token、账号信息或可识别的用户数据。

## 验收清单

改动完成前检查：

- `npm run typecheck`
- `npm test`
- 若改动发布入口、包文件、env 规则或 release/tag 流程：`npm run release:check`
- README、docs 和相关 skills 是否仍与公开 API 一致