# @coresourceai/sdk 中文文档

规范地址：https://npmcn.com/package/%40coresourceai/sdk/

版本：0\.1\.9
npm 元数据更新时间：2026-07-22T21:49:15.833Z
中文译文更新时间：2026-11-10T19:04:45.282Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40coresourceai/sdk
原文对照：https://npmcn.com/package/%40coresourceai/sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：280 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-07-18T09:35:44.792Z
- 最新版本发布：2026-07-22T21:49:15.685Z
- 近 30 天下载量：4978（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

TypeScript SDK用于创建一发,代理,和saga Core Source代理.

## 安装

```sh
npm install @coresourceai/sdk
```

也可以使用：`pnpm add @coresourceai/sdk`、`yarn add @coresourceai/sdk`、`bun add @coresourceai/sdk`

## README

# 核心来源 SDK

从 TypeScript 创建并运行完整的 AI 代理 。 核心源管理执行, 证书、存储和流;您的应用程序提供了代理定义 快点.

## 安装

```sh
npm install @coresourceai/sdk
export CORESOURCE_API_KEY='your-api-key'
```

需要20号或更新的节点.

SDK使用过 `https://api.coresource.ai/v1/` 默认。 再来一次, 通过 `{ baseUrl: 'https://api.example.com/v1/' }` 改为 `createAgent()` 或者说 `new CoreSource()`,或设置 `CORESOURCE_API_URL`。 。 。 .

## 创建代理

```ts
import { createAgent } from '@coresourceai/sdk';

const agent = createAgent({
  // A saga plans and executes durable, multi-step research.
  type: 'saga',

  // The system prompt defines the agent's research method and quality bar.
  systemPrompt: `You are a rigorous deep-research agent. Decompose the question,
search broadly, prioritize primary sources, cross-check important claims, and
resolve conflicting evidence. Cite every material claim, distinguish established
facts from inference, state uncertainty explicitly, and deliver a clear,
evidence-backed final report.`,

  // Select the hosted model and use its highest reasoning-effort setting.
  model: 'deepseek/deepseek-v4-flash',
  effort: 'xhigh',

  // Declare the artifact the agent should produce and persist with the run.
  outputs: ['report.md']
});

try {
  const result = await agent.run('Validate the invoice-management benchmarks.');
  console.log(result.text);

  const report = result.artifacts.find((artifact) => artifact.name === 'report.md');
  if (report) console.log(await report.text());
} finally {
  await agent.close();
}
```

`createAgent()` 既同步又懒惰 它第一次发出网络请求时 你打电话 `run()` 或者说 `start()`。 。 。 .

开始一个 `agent` 或者说 `saga` 需要至少1 000美元的预付余额,除非 账户在企业计划中。 一个被拒绝的开始抛出 `InsufficientFundsError` 有代码 `InsufficientFunds`一发请求不 分配运行时间;它们使用正常的推算平衡检查.

Core Source有三种代理类型:

| 类型 | 用它来 |
| --- | --- |
| `one-shot` | 一个没有工具的模型响应 |
| `agent` | 具有工具、技能、文件或MCP的迭接工作 |
| `saga` | 计划、持久的多步骤工作 |

数值与 `AgentType.OneShot`, (中文(简体) ), `AgentType.Agent`,以及 `AgentType.Saga`。 。 。 .

## 一发

```ts
const answerer = createAgent({
  type: 'one-shot',
  systemPrompt: 'Answer clearly and concisely.',
  model: 'deepseek/deepseek-v4-flash'
});

const result = await answerer.run('Explain three-way invoice matching.');
console.log(result.text);
```

一发特工故意无用工具. `run()` 使一个同步 请求到 API 网关并直接返回模型响应 - 没有 管理运行时间、桥接会、运行投票或 `$1` 运行时间地板。 使用 `agent` 或者说 `saga` 当运行需要工具,文件,技能,MCP服务器,流出时 进步,或文物.

## 工具

主机能力,如网络搜索和主机MCP服务器完全执行 核心来源. 他们不需要回你的申请.

一个 SDK 托管的工具在您的进程中执行 。 模型称为普通工具 名称, 且 CoreSource 透明地将呼叫给注册处理器 :

```ts
const agent = createAgent({
  type: 'agent',
  systemPrompt: 'Use the available business data.',
  tools: [{
    name: 'lookup_invoice',
    description: 'Look up an invoice by ID.',
    inputSchema: {
      type: 'object',
      properties: { id: { type: 'string' } },
      required: ['id'],
      additionalProperties: false
    },
    handler: async (input, { signal }) => {
      signal.throwIfAborted();
      return lookupInvoice(String(input.id), { signal });
    }
  }]
});

const result = await agent.run('Summarize invoice INV-123.');
```

没有默认注册本地工具 。 当特工需要你的申请时 文件系统、 命令运行器或网络上下文, 明确添加基础目录 第一次运行前:

```ts
const codingAgent = createAgent({ type: 'agent' });
codingAgent.registerRuntimeTools();
```

目录包含 `file_read`, (中文(简体) ), `file_write`, (中文(简体) ), `file_edit`, (中文(简体) ), `glob`, (中文(简体) ), `grep`, (中文(简体) ), `web_fetch`,以及 `execute`。一个明确提供的 SDK 工具获得确切名称 碰撞。 主机搜索保留为 `web_search`。 。 。 .

### 图像理解

启用主机 `understand_image(image, prompt)` 通过选择一个 代理定义中可视能一发模型:

```ts
const visualAgent = createAgent({
  type: 'agent',
  systemPrompt: 'Inspect supplied images before drawing conclusions.',
  model: 'deepseek/deepseek-v4-pro',
  imageModel: 'makora/kimi-2.7-code'
});

const result = await visualAgent.run({
  prompt: 'Read the attached chart and explain its largest change.',
  files: ['./quarterly-chart.png']
});
```

图像模型是通过配置固定的;它不是代理可以使用的参数 变化。 主机运行时间读取运行本地图像并单独执行 通过 Core Source 调制一发请求。 图像从不需要 绕过你的SDK过程.

## 技能和MCP

技能字符串可以安装名称, 公开 `owner/repository/path` 参考文献, 或完整 GitHub 树 URL :

```ts
import { CoreSource, createAgent } from '@coresourceai/sdk';

const coresource = new CoreSource();

// Save the remote credential once. It is encrypted by CoreSource and never
// placed in the agent runtime or returned by a read/list API.
const researchMcp = await coresource.mcp.connect({
  name: 'Research',
  url: 'https://mcp.example.com/rpc',
  auth: { type: 'bearer', token: process.env.RESEARCH_MCP_TOKEN! }
});

const researcher = createAgent({
  type: 'saga',
  systemPrompt: 'Prefer primary sources and retain direct URLs.',
  skills: [
    'deep-research',
    'anthropics/skills/skills/pdf',
    'https://github.com/owner/repository/tree/COMMIT_SHA/path/to/skill'
  ],
  mcpServers: [{
    connectionId: researchMcp.id,
    alias: 'research'
  }],
  outputs: ['research.md']
});
```

用 API 密钥创建的连接默认为账户范围 。 连接 从一个经认证的用户会话中创建的默认是该用户的私人; 组织所有人可以明确选择组织范围.

主机MCP条目使用不透明的连接ID. 核心源注入远程 仅在其外出中继器、代理定义、运行、事件和 运行时配置从不包含它. OAuth 连接返回一个 `authorizationUrl` 打开一次 旋转静态证书 `coresource.mcp.connections.rotateCredential(...)` 并重新启动 OAuth 以 `coresource.mcp.connections.authorize(...)`。 。 。 .

对于 GitHub, 使用 Core Source 管理的 OAuth app 并有一个字段:

```ts
const github = await coresource.mcp.connect({
  name: 'GitHub',
  url: 'https://api.githubcopilot.com/mcp/',
  auth: { type: 'oauth', provider: 'github' }
});

// Send the user to GitHub once, then use github.id in mcpServers after the
// callback changes the connection status to "connected".
console.log(github.authorizationUrl);
```

一个组织可以自行注册GitHub App或OAuth App. 内容 客户端秘密是只写,并由CoreSource加密. 配置返回的内容 `callbackUrl` 在 GitHub 中,然后在创建连接时通过 ID 选择应用程序 :

```ts
const app = await coresource.mcp.oauthApps.create({
  name: 'Acme GitHub',
  provider: 'github',
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!
});

console.log(`Set the GitHub callback URL to ${app.callbackUrl}`);

const github = await coresource.mcp.connect({
  name: 'Acme GitHub',
  url: 'https://api.githubcopilot.com/mcp/',
  auth: { type: 'oauth', appId: app.id }
});
```

OAuth应用简介是组织层面的资源,需要所有者访问. 旋转 `coresource.mcp.oauthApps.rotateCredential(...)` 更新客户端 用于每个引用的连接,而不将该秘密复制到运行中.

要在您的应用程序中运行 MCP 客户端, 请打电话 `agent.registerMcpServer(...)` 在第一次比赛之前 本地技能捆绑也是 支持通过 `{ name, content, files }` 条目.

## 档案和文物

通过本地路径或内存文件运行 :

```ts
const result = await agent.run({
  prompt: 'Analyze the supplied invoices and write findings.md.',
  files: [
    './invoices.csv',
    {
      name: 'policy.txt',
      path: 'references/policy.txt',
      data: 'Escalate invoices above EUR 50,000.',
      mimeType: 'text/plain'
    }
  ],
  input: { country: 'DE', currency: 'EUR' }
});

for (const artifact of result.artifacts) {
  console.log(artifact.name, await artifact.text());
}
```

文件目的地是运行所管理输入区域内的相对名称. 储存 位置和运行时文件系统根不是公共 API 的一部分.

## 清流和取消

`run()` 等待最终结果. `start()` 立即返回为 `agent` 财务报告和审定财务报表 `saga`数字 :

```ts
const run = await agent.start('Validate the benchmarks.');

for await (const event of run.events()) {
  console.log(event.type, event.data);
}

const result = await run.result();

// When needed:
await run.cancel();
```

事件流包括状态,进度,日志,消息,工具活性,用法, 输出和终端结果事件。 事件ID可用于安全恢复. 投票结果没有默认全面超时,因此长距离跑可以继续 几天时间 过 `timeoutMs` 只有在打电话者有意要求等待期限时; 它永远不会取消运行.

## 人力投入

当代理打电话 `ask_user`,运行会持续暂停状态 `awaiting_input`。 。 。 . `run.result()` 立即带回问题 `run.resume()` 继续从检查站逃出:

```ts
const run = await agent.start('Prepare the launch plan and ask before choosing a date.');
let result = await run.result();

while (result.status === 'awaiting_input') {
  const action = result.requiredAction;
  if (!action) throw new Error('The run paused without a question.');

  console.log(action.question);
  const answer = await readAnswerFromYourUser();
  await run.resume(answer);
  result = await run.result();
}
```

对于请求/答复申请, `agent.run()` 可以处理每次暂停通过 一个回话:

```ts
const result = await agent.run('Prepare the launch plan.', {
  onInputRequired: async ({ question }) => {
    return readAnswerFromYourUser(question);
  }
});
```

无 `onInputRequired`, (中文(简体) ), `agent.run()` 返回已暂停的结果而不是 无限期等待。 运行可能要求输入不止一次;每个答案是 提交该运行和 执行恢复 从相同的持久状态.

## 编剧

以 `composeAgents`; 使用普通承诺进行平行 分支 :

```ts
import { composeAgents } from '@coresourceai/sdk';

const pipeline = composeAgents(researcher, {
  agent: createAgent({
    type: 'agent',
    systemPrompt: 'Turn the upstream evidence into an executive brief.',
    outputs: ['brief.md']
  }),
  prompt: ({ previous }) => ({
    prompt: `Write the brief from this upstream summary:\n\n${previous.text}`,
    inputs: previous.artifacts.map((artifact) => ({
      type: 'artifact',
      runId: previous.id,
      artifactId: artifact.id,
      path: `upstream/${artifact.name ?? artifact.id}`
    }))
  })
});

const { result, steps } = await pipeline.run('Research invoice automation.');

const [eu, us] = await Promise.all([
  euResearcher.run('Research EU benchmarks.'),
  usResearcher.run('Research US benchmarks.')
]);
```

人工交接可能时仍然是服务器侧. 如果下游剂使用 SDK托管工具,SDK透明地下载并重新将交接器装入 那个代理的 管理的输入集.

## 已保存的代理

使用 `CoreSource` 定义何时应可重新使用并在 服务器 :

```ts
import { CoreSource } from '@coresourceai/sdk';

const coresource = new CoreSource();

const saved = await coresource.agents.create({
  name: 'invoice-researcher',
  type: 'saga',
  systemPrompt: 'Validate claims using primary sources.',
  model: 'openai/gpt-5',
  skills: ['anthropics/skills/skills/pdf'],
  outputs: ['report.md']
});

const result = await saved.run('Validate these invoice-management benchmarks.');
const updated = await saved.update({ description: 'Primary-source invoice analyst' });
const versions = await updated.versions();
```

已保存定义支持创建、检索、列表、更新、删除、运行、永久 版本,以及版本被绑定的运行. 函数处理器和当地技能组合 进程本地化,因此无法保存; 使用 `createAgent()` 这些.

关于直接的 HTTP 示例和完整的请求计划,见 [核心源代码 HTTP API 指南](https://github.com/coresource-ai/sdk/blob/main/docs/hosted-api.md)。 。 。 .

## 常见问题

### @coresourceai/sdk 是什么？

TypeScript SDK用于创建一发,代理,和saga Core Source代理\.

### 如何安装 @coresourceai/sdk？

在项目目录运行 npm install @coresourceai/sdk，或使用 pnpm add / yarn add / bun add。

### @coresourceai/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @coresourceai/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @coresourceai/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @coresourceai/sdk 可以商用吗？

@coresourceai/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @coresourceai/sdk 的下载量有多少？

根据 npm 官方下载统计，@coresourceai/sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 4,978 次，日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @coresourceai/sdk 还在维护吗？

最新版本 0\.1\.9 发布于 2026/07/23（3 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/07/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。