设置指南

本指南涵盖了你从零开始到完成 Imbrace SDK 集成所需的一切 — 安装、环境、凭证和服务 URL 覆盖。

---

系统要求

要求	最低版本
Node.js	18.0.0+
npm	8.0.0+
Python	3.9+
pip	23.0+

---

安装

TypeScript

从 npm 注册表：

npm install @imbrace/sdk
# 或
yarn add @imbrace/sdk
# 或
pnpm add @imbrace/sdk

Monorepo / 本地开发：

# 步骤 1 — 安装依赖并构建
cd ts
npm install
npm run build

# 步骤 2（可选）— 链接到全局，以在同一台机器上的另一个项目中使用
npm link

然后在你的外部项目中：

npm link @imbrace/sdk

验证：

import { ImbraceClient } from "@imbrace/sdk";
console.log("SDK loaded:", typeof ImbraceClient); // 'function'

Python

从 PyPI：

pip install imbrace
# 或
uv add imbrace

Monorepo / 本地开发（editable 模式）：

cd py
pip install -e ".[dev]"

[dev] 标志安装：pytest、pytest-asyncio、pytest-httpx、ruff、mypy。

验证：

from imbrace import ImbraceClient
print("SDK loaded:", ImbraceClient)

---

环境

名称	网关 URL	使用场景
develop	https://app-gateway.dev.imbrace.co	内部开发
sandbox	https://app-gateway.sandbox.imbrace.co	集成测试
stable	https://app-gatewayv2.imbrace.co	生产环境（默认）

通过 env 构造函数选项切换环境，或直接用 baseUrl 覆盖 URL：

TypeScript

const client = new ImbraceClient({ env: "sandbox" });

Python

client = ImbraceClient(env="sandbox")

---

配置凭证

创建 .env 文件

SDK 不会自动读取环境变量 — 你需要将凭证直接传递给构造函数。.env 文件是存储密钥的用户约定；使用 dotenv 或你的框架的环境变量加载器来读取它们。

# 凭证
IMBRACE_API_KEY=your_api_key_here
IMBRACE_ACCESS_TOKEN=your_jwt_token_here

# 组织 ID — 随每个请求发送
IMBRACE_ORGANIZATION_ID=your_org_id_here

# 可选：直接覆盖网关 URL
IMBRACE_GATEWAY_URL=https://app-gatewayv2.imbrace.co

获取 API Key

完整说明请参见获取 API Key。

---

初始化客户端

TypeScript

import { ImbraceClient } from "@imbrace/sdk";

// 服务端 — API Key
const client = new ImbraceClient({
  apiKey:         process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  env:            "stable",
});

// 客户端 — Access Token（例如来自之前的登录，或你自己存储的 token）
const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env:         "stable",
});

// 密码登录（POST /v1/login/sign_in）— 终端用户应用最常用的方式。
// 在一次调用中返回 { token: "login_acc_...", organizations: [...] }；用
// selectOrganization() 选择其中一个，SDK 会自动切换为该组织的 acc_ token。
const anon = new ImbraceClient({ env: "stable" });
const { organizations } = await anon.login("user@example.com", "password");
await anon.selectOrganization(organizations[0].id);

// OTP 登录流程（替代方案 — 用 email-OTP 体验替代密码）
await anon.requestOtp("user@example.com");
await anon.loginWithOtp("user@example.com", "123456");
// 令牌自动存储在客户端上

Python (sync)

import os
from imbrace import ImbraceClient

# 服务端 — API Key
client = ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
    organization_id=os.environ.get("IMBRACE_ORGANIZATION_ID"),
    env="stable",
)

# 客户端 — Access Token
client = ImbraceClient(
    access_token="eyJhbGci...",
    organization_id="org_xxx",
)

# 密码登录（POST /platform/v1/login/authenticate）— 终端用户应用最常用的方式。
# login() 返回用户所属的组织；选择其一后用 select_organization()
# 将短期 login_acc_ token 换成绑定组织的 acc_ token。
anon = ImbraceClient(env="stable")
res = anon.login("user@example.com", "password")
anon.select_organization(res["organizations"][0]["organization_id"])

# OTP 登录流程（替代方案 — 用 email-OTP 体验替代密码）
anon.request_otp("user@example.com")
anon.login_with_otp("user@example.com", "123456")

Python (async)

from imbrace import AsyncImbraceClient

async def main():
    async with AsyncImbraceClient(api_key="api_...") as client:
        me = await client.platform.get_me()
        print(me)

---

CLI 安装

# 全局安装
npm install -g @imbrace/cli

# 登录开始使用
imbrace login --api-key api_xxx...

其他安装方法请参见 CLI 安装，完整命令参考请参见 CLI 命令。

---

覆盖服务 URL

当微服务运行在不同地址时使用（例如本地开发、专用预发布环境）。

TypeScript

const client = new ImbraceClient({
  env: "develop",
  services: {
    aiAgent: "http://localhost:4000/ai-agent",
    dataBoard: "http://localhost:3001/data-board",
    channelService: "http://localhost:3002/channel-service",
  },
});

Python

client = ImbraceClient(
    env="develop",
    services={
        "ai_agent":       "http://localhost:4000/ai-agent",
        "data_board":     "http://localhost:3001/data-board",
        "channel_service":"http://localhost:3002/channel-service",
    },
)

所有有效的服务键：

Python 键	TypeScript 键	服务
gateway	gateway	App Gateway
platform	platform	Platform 服务
channel_service	channelService	Channel 服务
data_board	dataBoard	Data Board
backend	backend	旧版单体（/v1/backend）— 用于登录认证、模板以及少数尚未拆分出去的路由
ips	ips	IPS 服务
ai	ai	AI 服务
marketplaces	marketplaces	Marketplace 服务
file_service	fileService	文件服务
message_suggestion	messageSuggestion	消息建议服务
predict	predict	预测服务
workflow_engine	workflowEngine	工作流
ai_agent	aiAgent	AI Agent 服务

---

故障排除

Cannot find package '@imbrace/sdk'

包未链接。从 ts 重新运行：

npm link
cd /path/to/your-project && npm link @imbrace/sdk

dist/ 中文件报 ERR_MODULE_NOT_FOUND

包尚未构建：

cd ts && npm run build

ModuleNotFoundError: No module named 'imbrace'

cd py && pip install -e ".[dev]"

401 Unauthorized

API Key 过期或无效。请从 Imbrace 控制台生成新的 API Key，或参见 API Key 指南。

UserWarning: ImbraceClient: no credentials provided

未传入 api_key 或 access_token。如果是有意为之（例如仅登录流程），忽略此警告。否则请检查你的 .env 文件。