企业官网建设流程全解析

本文基于 packages/trueforge-sdk/reference.md 官方 API 参考，全面梳理@truefoundry/trueforge-sdk的全部资源分组与调用方式。TrueForge 是一个开源 Agent Harness（运行时层），负责把 LLM 变成可工作的 Agent；该 SDK 是接入 TrueForge Agent Harness Server 的官方 TypeScript 客户端，服务端自托管、执行 Agent 回合并通过 Server-Sent Events（SSE）流式下发事件。阅读完本文，你将掌握：客户端如何初始化与鉴权、Agent/Session/Turn 生命周期管理、MCP 服务器授权与工具枚举、Sandbox 环境与调度器操作、Catalogs 与 Settings 两套配置投影，以及分页、流式消费、二进制下载、重试与超时等进阶用法，可直接写出可运行的生产级调用代码。

一、SDK 定位与客户端结构

@truefoundry/trueforge-sdk是 TrueForge 项目为 Agent Harness Server 提供的 TypeScript API 客户端。服务端是一个自托管运行时：它接收 Agent 回合（turn）请求，执行 LLM 推理与工具调用，并通过 Server-Sent Events 把回合事件实时推送给客户端。SDK 的所有方法签名、请求/响应类型与行为描述均以 reference.md 为准，代码本体由 Fern 自动生成。

从 Client.ts 的源码结构可以看出，TrueForge客户端类采用惰性初始化的 getter 模式组织资源分组，构造时只保存标准化后的选项，首次访问某个分组时才创建对应的子客户端：

客户端初始化与鉴权

根据 README.md 与 BaseClient.ts，最小初始化方式如下：

import { TrueForge } from "@truefoundry/trueforge-sdk"; const client = new TrueForge({ baseUrl: "YOUR_BASE_URL", token: "YOUR_TOKEN" }); const response = await client.sessions.createTurnStream("session_id", {}); for await (const item of response) { console.log(item); }

鉴权设计如下：

• 服务端启用认证时，通过token选项传递 ID token，SDK 会以Authorization: Bearer请求头发送；服务端未启用认证时，返回独立的默认身份，无需 token。
• 从normalizeClientOptionsWithAuth（BaseClient.ts）的源码可见，auth选项支持四种形态：传false关闭鉴权（使用NoOpAuthProvider）、传函数（返回认证请求头）、传AuthProvider对象、或传 Bearer 认证选项；未显式配置时默认使用BearerAuthProvider。
• SDK 还会自动附加X-Fern-Language、X-Fern-SDK-Name、X-Fern-SDK-Version、User-Agent、X-Fern-Runtime等标识头。

二、Agents：Agent 注册表的完整生命周期

client.agents负责租户内已配置 Agent 的管理。所有 Agent 拥有不可变 ID（immutable id），且name一旦创建不可更改。

列出 Agent

按名称排序返回租户已配置的 Agent，可选的agent_name参数按子串过滤。返回值为可分页响应：

const pageableResponse = await client.agents.list(); for await (const item of pageableResponse) { console.log(item); } // 或手动逐页迭代 let page = await client.agents.list(); while (page.hasNextPage()) { page = await page.getNextPage(); } // 也可以直接访问底层响应 const response = page.response;

参数：request（TrueForge.ListAgentsRequest，可选）、requestOptions（AgentsClient.RequestOptions，可选）。

创建 Agent

按名称创建 Agent 并分配不可变 ID。若name已被占用则失败；名称创建后不可修改：

await client.agents.create({ description: "description", manifest: { model: { name: "name" } }, name: "name" });

参数：request（TrueForge.CreateAgentRequest，必填）、requestOptions。从示例可见 Agent 清单（manifest）至少包含model.name字段，即绑定一个已配置的模型 FQN。

读取、更新与删除

// 按不可变 ID 获取单个 Agent await client.agents.get("agent_id"); // agent_id: string — Immutable agent identifier // 更新现有 Agent await client.agents.update("agent_id", { manifest: { model: { name: "name" } } }); // 删除 Agent await client.agents.delete("agent_id");

三个方法均接受agent_id（string，不可变 Agent 标识符）与可选requestOptions；update额外接受TrueForge.UpdateAgentRequest。

三、Auth 与 Server：身份与能力探针

当前身份查询

client.auth.me()返回已认证调用者的身份信息（type、tenant_id、subject、roles），包裹在{ data }中：

await client.auth.me();

行为细节（源自 reference.md 的描述）：当浏览器 OIDC 启用时type为oidc-connected，否则为default；服务端启用认证时需要有效的id_tokencookie 或Authorization: Bearertoken，否则返回 401；认证关闭时返回 standalone 默认身份。

运行时能力上报

client.server.getCapabilities()报告该租户可用的可选运行时能力（optional runtime capabilities）：

await client.server.getCapabilities();

四、MCP Servers：面向 Composer 的精简投影与 OAuth 授权

client.mcpServers提供“slim chat projection”（精简聊天投影）：相比 Settings 下的完整配置，这里只返回名称/URL 级别的信息，供 Composer 界面使用，并携带实时 per-userauth_status。

列出与获取

// 已配置 MCP 服务器的精简 name/url 列表 await client.mcpServers.list(); // 单个 MCP 服务器（含实时 per-user auth_status） await client.mcpServers.get("name"); // name: string — MCP server name

授权与取消授权

// 返回当前认证状态；需要 OAuth 时包含授权 URL await client.mcpServers.authorize("name"); // 断开该 MCP 服务器的 OAuth，返回更新后的服务器及 auth_status await client.mcpServers.deleteAuthorization("name");

authorize可接受可选的TrueForge.AuthorizeMcpServersRequest（其中的return_to为授权完成后的落地路径）；deleteAuthorization对不使用存储 OAuth token 的服务器是无操作（no-op）。

枚举工具

// 返回给定 MCP 服务器暴露的全部工具（非分页），即 MCP tools/list 调用的结果 await client.mcpServers.listTools("name");

五、Models 与 Skills：Composer 侧的精简列表

// 已配置模型的精简 FQN 列表 await client.models.list(); // 已配置技能的精简 name/description 列表 await client.skills.list(); // 单个技能的版本列表 await client.skills.listVersions({ name: "name" });

models.list()与skills.list()无需参数，直接返回列表；skills.listVersions需要TrueForge.ListVersionsSkillsRequest（含name）。

六、SandboxEnvironments：沙箱环境管理

沙箱环境是 Agent 执行代码的运行容器。该分组围绕manifest.name作为业务键展开。

列出

返回租户默认环境 + 当前认证主体创建的自定义环境：

const pageableResponse = await client.sandboxEnvironments.list(); for await (const item of pageableResponse) { console.log(item); } let page = await client.sandboxEnvironments.list(); while (page.hasNextPage()) { page = await page.getNextPage(); }

创建与创建或替换

// 按 manifest.name 创建，名称已被占用则失败；需要已配置的 sandbox provider await client.sandboxEnvironments.create({ manifest: { name: "name" } }); // 按 manifest.name 创建或整体替换 await client.sandboxEnvironments.createOrUpdate({ manifest: { name: "name" } });

create使用TrueForge.CreateSandboxEnvironmentRequest；createOrUpdate使用TrueForge.UpdateSandboxEnvironmentRequest。两者都要求租户已配置 sandbox provider。

获取与删除

// 按名称获取；租户默认环境任何租户成员可读，自定义环境归属创建者 await client.sandboxEnvironments.get("name"); // 按名称删除；若有任何 Agent 仍引用该环境则失败 await client.sandboxEnvironments.delete("name");

七、Schedules：定时调度与运行

调度器允许为既有 Agent 按 cron 表达式定期触发任务。

创建与立即运行

// 为既有 Agent（按名称）创建调度，活动状态时立即加入首个 pending run await client.schedules.create({ agentName: "agent_name", manifest: { cron: "cron", task: "task" }, name: "name" }); // 立即用调度任务启动一次运行；不会替换或推进 cron pending run await client.schedules.createRun({ scheduleId: "schedule_id" });

查询、更新与删除

// 按 ID 获取调度（最新在前） await client.schedules.get("schedule_id"); // 替换 name 与 manifest；status/cron/timezone 变化时会替换或丢弃 pending run await client.schedules.update("schedule_id", { manifest: { cron: "cron", task: "task" }, name: "name" }); // 删除调度及其全部运行，幂等 await client.schedules.delete("schedule_id");

列出调度与运行

// 列出租户全部调度，最新在前（分页） const pageableResponse = await client.schedules.list(); for await (const item of pageableResponse) { console.log(item); } // 列出某调度的运行，按 scheduled_for 最新在前；创建者或其 Agent 的管理员可见 const runs = await client.schedules.listRuns("schedule_id"); for await (const item of runs) { console.log(item); }

八、Sessions 与 Turns：核心执行链路（含 SSE 流式）

Sessions 分组是 SDK 的核心：它管理会话、创建并执行回合、消费事件流、下载沙箱产物。回合事件通过 SSE 流式下发，这是 TrueForge Agent Harness 的核心交互模式。

会话创建与读取

// 创建会话：agent 可以是 { name }（命名注册表绑定）或 { spec: AgentSpec }（内联定义） // 命名会话在创建时快照 agent 名称，每次回合解析最新 Agent // 响应使用 { type: "reference", name, id } 或 { type: "inline", spec } await client.sessions.create({ agent: { name: "name" } }); // 按 ID 获取会话；创建者、绑定命名 Agent 的管理员或共享会话的任意租户成员可见 await client.sessions.get("session_id");

会话更新、删除与取消

// 更新：可选 title、metadata、shared；仅内联会话可更新 agent（{ spec: AgentSpec }），命名会话拒绝 // 空 body 是合法 no-op，会刷新 updated_at；仅创建者可更新 await client.sessions.update("session_id"); // 删除会话及其全部 turns、events 与内部状态；仅创建者可删，幂等 await client.sessions.delete("session_id"); // 取消会话正在运行的最后一个回合；仅创建者可取消 await client.sessions.cancel("session_id");

创建回合并流式执行（SSE）

// stream 为 true（默认）时返回 SSE 事件流 // stream 为 false 时立即返回 state.status: "running"，执行在后台继续 // previous_turn_id 默认 "auto"（链到会话最后一个回合），传 "none" 开启新根 const response = await client.sessions.createTurnStream("session_id", {}); for await (const item of response) { console.log(item); } // 非流式版本：立即返回回合对象 await client.sessions.createTurn("session_id", {});

注意：仅会话创建者可创建回合。createTurnStream返回core.Stream<TrueForge.TurnStreamingEvent>，可用for await...of直接消费。

回合查询与事件

// 获取单个回合 await client.sessions.getTurn("session_id", "turn_id"); // 列出会话事件：{ turn_id, event }，沿活动回合分支、最新在前 // 每个回合包含 turn.created、内容事件（model.message、tool.call、…）、终态时 turn.done // 流式增量事件不包含在内；用 page_token 向更早事件向后分页 const events = await client.sessions.listEvents("session_id"); for await (const item of events) { console.log(item); } // 列出某回合的分页持久化事件（默认按插入顺序） const turnEvents = await client.sessions.listTurnEvents("session_id", "turn_id"); for await (const item of turnEvents) { console.log(item); } // 向回合写入事件（仅创建者可写），例如用户侧 MCP 认证继续 await client.sessions.createTurnEvent("session_id", "turn_id", { events: [{ type: "user.mcp_auth_continue" }] }); // 列出会话回合（默认最新在前，token 分页） const turns = await client.sessions.listTurns("session_id"); for await (const item of turns) { console.log(item); }

订阅实时 SSE 流与断线续传

// 订阅某回合的实时 SSE 流；仅创建者可订阅 // 传 after_sequence_number 可在断线后续传（不含该序号，重放该序号之后的事件） const response = await client.sessions.subscribeToTurn("session_id", "turn_id"); for await (const item of response) { console.log(item); }

沙箱文件下载（二进制）

// 下载该回合所在沙箱中的文件；路径来自 assistant 的 sandbox_artifacts 块；仅创建者可下载 await client.sessions.downloadSandboxFile("session_id", "turn_id", { path: "x" });

downloadSandboxFile返回core.BinaryResponse，可调用stream()、arrayBuffer()、blob()、bytes()四种方式消费，详见下文“二进制响应”一节。

九、Catalogs：出厂预设（发现优先）

Catalogs 分组提供 TrueForge 随产品内置的预设清单，仅用于发现（discovery-only）：拿到内容后需复制到PUT /settings/...才能实际生效。这是典型的“预设-配置”分离设计。

// MCP 服务器预设 await client.catalogs.mcpServers.list(); // 模型提供商预设；包含带 supported_reasoning_efforts 的 custom 哨兵条目 await client.catalogs.modelProviders.list(); // 沙箱提供商预设 await client.catalogs.sandboxProviders.list(); // 技能预设 await client.catalogs.skills.list(); // 网页搜索提供商预设 await client.catalogs.webSearchProviders.list();

各 Catalogs 分组的方法与资源一一对应，命名遵循client.catalogs.<resource>.list()约定。

十、Settings：租户配置的管理投影

Settings 分组暴露的是“settings / admin projection”：返回嵌套完整 manifest，并对密钥字段做脱敏处理。这是与 Composer 侧精简投影（mcpServers、models、skills）相对的管理视角。

Settings MCP Servers

// 已配置 MCP 服务器列表（含 auth_status；header 密钥已脱敏） await client.settings.mcpServers.list(); // 按 name 创建；auth.type 为 dcr 时执行 DCR 注册；header 密钥必须是真实值，脱敏且无存储值返回 400 await client.settings.mcpServers.create({ manifest: { description: "description", name: "name", type: "remote", url: "url" } }); // 按 name 创建或替换；真实密钥值设置/轮换，脱敏值保留现有（无现有则 400） await client.settings.mcpServers.createOrUpdate({ manifest: { description: "description", name: "name", type: "remote", url: "url" } }); // 获取单个（settings/admin 投影，嵌套实时 auth_status，header 认证值脱敏） await client.settings.mcpServers.get("name"); // 按 name 删除，同时删除其全部存储的 OAuth token；仍有 Agent 引用时拒绝 await client.settings.mcpServers.delete("name");

Settings Model Providers

// 全部已配置提供商（嵌套 manifest） await client.settings.modelProviders.list(); // 创建提供商（含 models）；知名类型用 type 作为 name（每种一个），custom 由调用方命名 // auth.api_key 必须是真实值；脱敏且无存储密钥返回 400 await client.settings.modelProviders.create({ manifest: { auth: { apiKey: "api_key" }, models: [{ modelId: "model_id", name: "name", properties: {} }], type: "alibaba" } }); // 创建或替换提供商；真实 api_key 设置/轮换，脱敏保留现有 await client.settings.modelProviders.createOrUpdate({ manifest: { auth: { apiKey: "api_key" }, models: [{ modelId: "model_id", name: "name", properties: {} }], type: "alibaba" } }); // 删除提供商及其声明的全部模型；仍有 Agent 使用其中任一模型时拒绝 await client.settings.modelProviders.delete("name");

从示例可见，提供商 manifest 由type（如alibaba，对应知名类型）、auth.api_key与models[]（每项含modelId、name、properties）组成；properties为模型附加属性对象。

Settings Sandbox Providers（单例）

// 获取租户唯一 sandbox provider；auth.api_key 已脱敏 await client.settings.sandboxProviders.get(); // upsert 该唯一提供商：创建或整体替换配置 await client.settings.sandboxProviders.createOrUpdate({ manifest: { auth: { apiKey: "api_key" }, autoArchiveIntervalInMinutes: 1, autoDeleteIntervalInMinutes: 1, autoStopIntervalInMinutes: 1, execTimeoutMs: 1, type: "daytona" } });

注意：与 MCP 服务器、模型提供商不同，沙箱提供商是租户单例（single configured provider），因此只有get与createOrUpdate，没有list/create/delete。其 manifest 包含生命周期治理参数：autoStopIntervalInMinutes（自动停止间隔）、autoArchiveIntervalInMinutes（自动归档间隔）、autoDeleteIntervalInMinutes（自动删除间隔）、execTimeoutMs（执行超时毫秒数）与type（如daytona）。

Settings Skills 与 Web Search Providers

// 全部已配置技能（嵌套 manifest，settings/admin 投影） await client.settings.skills.list(); // 按 name 创建技能；名称被占用则失败 await client.settings.skills.create({ manifest: { description: "description", name: "name", ref: "ref", type: "git", url: "url" } }); // 按 name 完整 upsert：创建或替换整个 manifest await client.settings.skills.createOrUpdate({ manifest: { description: "description", name: "name", ref: "ref", type: "git", url: "url" } }); // 按 name 删除；仍有 Agent 引用时拒绝 await client.settings.skills.delete("name"); // 网页搜索提供商（单例）：获取，api_key 脱敏 await client.settings.webSearchProviders.get(); // upsert 网页搜索提供商 await client.settings.webSearchProviders.createOrUpdate({ manifest: { auth: { apiKey: "api_key" }, type: "parallel" } });

技能 manifest 示例使用type: "git"+url+ref，说明技能可通过 Git 仓库挂载；网页搜索提供商是单例 upsert 模式，type示例为parallel。

十一、Internal 分组：为基础设施预留的接口

client.internal面向构建控制器、调度执行器等基础设施组件，普通应用一般不直接调用，但理解其用途有助于把握整体架构。

// 权限：返回所请求资源的已授权操作 await client.internal.listPermissions({ resourceIds: ["resource_ids"], resourceType: "agent" }); // 会话指标：列出可用图表 await client.internal.metrics.listCharts(); // 会话指标：取一张图（窗口 ≤24h 用小时桶，否则用每日 UTC 桶） await client.internal.metrics.getChartData({ agentId: "agent_id", startTimestamp: new Date("2024-01-15T09:30:00.000Z"), endTimestamp: new Date("2024-01-15T09:30:00.000Z"), chartName: "sessions_over_time" }); // 会话指标：按创建时间窗口聚合调用者的会话仪表 await client.internal.metrics.getMeters({ agentId: "agent_id", startTimestamp: new Date("2024-01-15T09:30:00.000Z"), endTimestamp: new Date("2024-01-15T09:30:00.000Z") }); // 沙箱环境构建：供构建控制器轮询待构建版本 await client.internal.sandboxEnvironments.listPending(); // 沙箱环境构建：注册或轮询快照构建并更新版本状态 await client.internal.sandboxEnvironments.progress({ environmentVersionId: "environment_version_id" }); // 调度执行：执行持久化的调度运行（用其保存的调度与 Agent） await client.internal.schedules.executeRun({ scheduleRunId: "schedule_run_id" }); // 会话：按 external_id 幂等 get-or-create await client.internal.sessions.getOrCreateByExternalId({ agent: { name: "name" }, externalId: "external_id" }); // Agent 代码示例：返回针对该 Agent 的 SDK 示例（TypeScript/Python，流式/非流式） await client.internal.agents.getCodeSnippets("agent_id");

十二、请求/响应类型与异常处理

SDK 将全部请求与响应类型导出为 TypeScript 接口，统一挂载在TrueForge命名空间下（README.md）：

import { TrueForge } from "@truefoundry/trueforge-sdk"; const request: TrueForge.ListPermissionsRequest = { ... };

API 返回非成功状态码（4xx/5xx）时抛出TrueForgeError的子类。错误对象的结构见 TrueForgeError.ts：除statusCode、body、rawResponse、cause外，还提供requestIdgetter（从rawResponse的x-request-id响应头读取），便于在服务端日志中追踪请求：

import { TrueForgeError } from "@truefoundry/trueforge-sdk"; try { await client.sessions.createTurnStream(...); } catch (err) { if (err instanceof TrueForgeError) { console.log(err.statusCode); console.log(err.message); console.log(err.body); console.log(err.rawResponse); } }

十三、流式、二进制与分页消费模式

SSE 流式响应

流式端点（如createTurnStream、subscribeToTurn）返回异步迭代器，用for await...of消费：

const response = await client.sessions.createTurnStream("session_id", {}); for await (const item of response) { console.log(item); }

二进制响应

BinaryResponse提供四种消费方式，响应体只能使用一次，必须二选一；可用bodyUsed判断是否已消费：

const response = await client.sessions.downloadSandboxFile(...); const stream: ReadableStream<Uint8Array> = response.stream(); // const arrayBuffer: ArrayBuffer = await response.arrayBuffer(); // const blob: Blob = response.blob(); // const bytes: Uint8Array = response.bytes(); const bodyUsed = response.bodyUsed;

各运行时落盘示例：

• Node.js（ReadableStream 最高效）：Readable.fromWeb(response.stream())+pipeline(nodeStream, writeStream)，或arrayBuffer()后writeFile(path, Buffer.from(arrayBuffer))，或blob()/bytes()后writeFile。
• Bun：Bun.write('path/to/file', stream)或直接写arrayBuffer/blob/bytes。
• Deno：stream.pipeTo(file.writable)，或Deno.writeFile(path, new Uint8Array(arrayBuffer))。
• 浏览器：URL.createObjectURL(blob)触发下载；或先stream.getReader()收集 chunks 再new Blob(chunks)。

二进制转文本：await new Response(stream).text()、new TextDecoder().decode(arrayBuffer)、await blob.text()或new TextDecoder().decode(bytes)。

分页

List 端点全部分页。SDK 提供迭代器直接遍历，也支持手动逐页与访问底层响应：

const pageableResponse = await client.agents.list(); for await (const item of pageableResponse) { console.log(item); } let page = await client.agents.list(); while (page.hasNextPage()) { page = await page.getNextPage(); } const response = page.response;

十四、进阶配置：重试、超时、中断与日志

以下选项既可在构造客户端时设置（BaseClient.ts 中的BaseClientOptions），也可在每次请求时通过requestOptions覆盖（BaseRequestOptions）。

额外请求头与查询参数

const client = new TrueForge({ ... headers: { 'X-Custom-Header': 'custom value' } }); const response = await client.sessions.createTurnStream(..., { headers: { 'X-Custom-Header': 'custom value' }, queryParams: { 'customQueryParamKey': 'custom query param value' } });

自动重试

SDK 内置指数退避自动重试，只要请求可重试且未超过重试上限（默认 2）就会重试。重试状态码取决于生成配置：

• legacy（当前默认）：重试 408（Timeout）、429（Too Many Requests）、全部 5XX（含 500）。
• recommended：重试 408、429、502（Bad Gateway）、503（Service Unavailable）、504（Gateway Timeout）。

用maxRetries请求选项覆盖：

const response = await client.sessions.createTurnStream(..., { maxRetries: 0 // 请求级关闭重试 });

超时与中断

默认超时 60 秒，用timeoutInSeconds覆盖；用abortSignal随时中断：

const response = await client.sessions.createTurnStream(..., { timeoutInSeconds: 30 // 覆盖为 30s }); const controller = new AbortController(); const response2 = await client.sessions.createTurnStream(..., { abortSignal: controller.signal }); controller.abort(); // 中断请求

访问原始响应

.withRawResponse()返回{ data, rawResponse }，可读取响应头：

const { data, rawResponse } = await client.sessions.createTurnStream(...).withRawResponse(); console.log(rawResponse.headers['X-My-Header']);

日志

import { TrueForge, logging } from "@truefoundry/trueforge-sdk"; const client = new TrueForge({ ... logging: { level: logging.LogLevel.Debug, // 默认 Info logger: new logging.ConsoleLogger(), // 默认 ConsoleLogger silent: false, // 默认 true，设为 false 启用日志 } });

logging属性：level（Debug/Info/Warn/Error）、logger（默认ConsoleLogger）、silent（默认true）。自定义 logger 只需实现logging.ILogger接口的debug/info/warn/error四个方法，可适配 winston 或 pino：

import winston from 'winston'; const winstonLogger = winston.createLogger({...}); const logger: logging.ILogger = { debug: (msg, ...args) => winstonLogger.debug(msg, ...args), info: (msg, ...args) => winstonLogger.info(msg, ...args), warn: (msg, ...args) => winstonLogger.warn(msg, ...args), error: (msg, ...args) => winstonLogger.error(msg, ...args), };

透传请求与自定义 fetch

对 SDK 尚未覆盖的端点，client.fetch可发起透传请求，同时继承 SDK 的鉴权、重试、超时与日志配置（实现见 Client.ts，相对路径会基于 baseUrl 解析）：

const response = await client.fetch("/v1/custom/endpoint", { method: "GET", }, { timeoutInSeconds: 30, maxRetries: 3, headers: { "X-Custom-Header": "custom-value" }, }); const data = await response.json();

在不支持内置 fetch 的运行时，可注入fetcher自定义底层 HTTP 客户端：

const client = new TrueForge({ ... fetcher: // 自定义实现 });

Subpackage Exports（按需引入）

package.json 通过exports字段暴露全量子包入口，允许打包器 tree-shake，显著减小 bundle 体积。每个资源分组都有对应子路径（如./agents、./auth、./server、./mcpServers、./models、./sandboxEnvironments、./schedules、./sessions、./skills、./catalogs/*、./settings/*、./internal/*）：

import { InternalClient } from '@truefoundry/trueforge-sdk/internal'; const client = new InternalClient({...});

运行时兼容性

官方声明支持：Node.js 18+、Vercel、Cloudflare Workers、Deno v1.25+、Bun 1.0+、React Native。注意 package.json 中engines.node标注为>=22（构建/开发环境要求），浏览器环境通过browser字段屏蔽 Node 内置模块。

十五、参考文档与进一步阅读

• 完整 API 参考（本文依据）：packages/trueforge-sdk/reference.md
• SDK 使用手册（安装、异常、流式、分页、进阶选项）：packages/trueforge-sdk/README.md
• 客户端类结构（资源分组懒加载与fetch透传实现）：packages/trueforge-sdk/src/Client.ts
• 客户端选项与鉴权归一化（BaseClientOptions、BaseRequestOptions、Bearer 认证）：packages/trueforge-sdk/src/BaseClient.ts
• 错误类型与requestId追踪：packages/trueforge-sdk/src/errors/TrueForgeError.ts
• 包发布配置与子包导出映射：packages/trueforge-sdk/package.json

若需了解服务端侧对应实现（路由、存储、权限模型），可继续查看 packages/trueforge/routes/sessionRoutes.ts、packages/trueforge/routes/agentRoutes.ts 以及 docs/api/use-agent.mdx 中的 API 快速上手文档。