AiCore TypeScript Client

最小可用的 AiCore TypeScript SDK。

当前覆盖：

• GET /capabilities
• POST /tasks
• GET /tasks
• GET /tasks/{id}
• GET /tasks/{id}/detail
• POST /tasks/{id}/cancel
• POST /tasks/{id}/retry
• GET /tasks/{id}/assets/{assetType}/{sortOrder}/download
• GET /logs
• GET /access/quotas

刻意不覆盖：

• /governance/**
• 管理面 /access/tenant-overview
• 管理面 /access/api-key-audits
• 管理面 /access/api-keys
• 管理面 /access/api-keys/rotate
• 管理面 /access/api-keys/{id}/disable

这些口属于平台治理或管理面，不属于外部稳定接入契约。

Install

当前可以先作为仓库内子包使用，也已经补到“可打包验收”的状态：

cd packages/aicore-ts-client
npm install

Build

npm run build

build 现在会先做一次 generate:check。

也就是说，只要仓库里的 OpenAPI 快照和 SDK 生成类型不一致，构建会直接失败，不会再把漂移悄悄带进包里。

OpenAPI Generate

外部 SDK 的核心请求/响应类型，已经不再主要靠手写接口维护，而是从仓库里的外部契约快照自动生成：

• 输入源：docs/api/aicore-external-v1.openapi.json
• 生成结果：src/generated/external-openapi.ts
• 对外别名层：src/types.ts

常用命令：

npm run generate:types
npm run generate:check

适用规则：

• 改了正式对外 API，就先更新 docs/api/aicore-external-v1.openapi.json
• 然后执行 npm run generate:types
• 最后再跑测试和验包

如果只想确认仓库里有没有漂移，直接跑：

npm run generate:check

仓库根目录也有一条专门的回归脚本：

bash scripts/release/test-aicore-ts-client-generation.sh

Test

npm test

Package Check

先在子包里做最小自检：

npm run pack:check

再在仓库根目录跑统一打包验收：

bash scripts/release/test-aicore-ts-client-package.sh

如果要把它接进统一发布前检查，可以直接打开：

AICORE_RELEASE_RUN_SDK_PACKAGE_CHECK=true bash scripts/release/smoke-check.sh

如果要进一步确认“外部项目真的能装包、编译并调用”，可以再打开：

AICORE_RELEASE_RUN_SDK_EXTERNAL_CONSUMER_CHECK=true bash scripts/release/smoke-check.sh

这条检查会做一轮真实演练：

• 先把 SDK 打包成 tgz
• 再在临时独立项目里安装这个 tgz
• 跑一次 TypeScript 编译
• 最后连一个最小假服务，真实调用 getCapabilities / listTasks / getQuotaSnapshot

这两步通过后，至少能确认：

• 包清单已经不是 private
• 导出映射存在
• OpenAPI 生成类型没有漂移
• npm pack --dry-run 产物只带应该发布的文件
• 不会把 src/ 或 node_modules/ 一起带出去
• 外部接入方按正常方式安装后，类型和运行时都能工作

如果要直接对真实环境做一轮外部接入演练，也可以复用同一条脚本：

AICORE_SDK_CONSUMER_BASE_URL=https://api.aicore.eotoai.com \
AICORE_SDK_CONSUMER_API_KEY=replace_me \
AICORE_SDK_CONSUMER_MODE=read \
bash scripts/release/test-aicore-ts-client-external-consumer.sh

如果想补真实建单链路，再把模式切成 create：

AICORE_SDK_CONSUMER_BASE_URL=https://api.aicore.eotoai.com \
AICORE_SDK_CONSUMER_API_KEY=replace_me \
AICORE_SDK_CONSUMER_MODE=create \
bash scripts/release/test-aicore-ts-client-external-consumer.sh

read 模式会验证：

• getCapabilities
• listTasks
• getQuotaSnapshot

create 模式会继续验证：

• createTask
• getTaskDetail
• 下载地址获取

Version Policy

当前版本策略先固定成最简单、最能交班的一套：

• 修文案、补测试、不改对外行为：patch
• 新增正式对外接口或新增稳定字段：minor
• 删除外部能力、改参数语义、改返回结构：major

一句话：

• 不影响现有接入方就升小版本
• 会影响现有接入方就升大版本

Publish Flow

等后面真正接 npm registry 时，流程先固定成：

cd packages/aicore-ts-client
npm run release:prep
npm publish

现在仓库里还没接正式 registry 凭证，所以先做到“可打包验收、可随时接发布”。

release:prep 当前会统一做：

• 检查 package.json 当前版本是否已经写进 CHANGELOG.md
• 检查 OpenAPI 生成类型是否和仓库一致
• 跑 SDK 测试
• 跑打包验收
• 跑外部消费者安装/编译/调用演练

也就是说，后面要发版时，不再靠人自己记“这次到底少没少一步”。

Example

import { AiCoreClient } from "./dist/index.js";

const client = new AiCoreClient({
  baseUrl: "https://aicore.example.com",
  apiKey: "your-api-key"
});

const capabilities = await client.getCapabilities();
const created = await client.createTask(
  {
    business_line: "showa",
    source_system: "showa-api",
    task_type: "lyrics_generate",
    source_ref: "order_001",
    user_ref: "user_001",
    priority: "normal",
    input_payload: {
      prompt: "写一首关于深夜城市和旧爱的中文流行歌词"
    }
  },
  {
    idempotencyKey: "order_001_lyrics"
  }
);

const detail = await client.getTaskDetail(created.task_id);