# @google/jules-sdk 中文文档

规范地址：https://npmcn.com/package/%40google/jules-sdk/

版本：0\.2\.0
npm 元数据更新时间：2026-03-09T23:06:27.710Z
中文译文更新时间：2026-11-16T20:26:40.198Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40google/jules-sdk
原文对照：https://npmcn.com/package/%40google/jules-sdk/?lang=original
项目主页：https://github.com/google-labs-code/jules-sdk#readme
源码仓库：https://github.com/google-labs-code/jules-sdk

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

- 包体积（解压后）：562 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-01-23T21:51:06.606Z
- 最新版本发布：2026-03-09T23:06:27.558Z
- 近 30 天下载量：16958（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

官方 Jules 类型SDK

## 安装

```sh
npm install @google/jules-sdk
```

也可以使用：`pnpm add @google/jules-sdk`、`yarn add @google/jules-sdk`、`bun add @google/jules-sdk`

## README

# 朱尔斯·SDK

## 一个SDK在云中运行一队编码代理

管弦乐团复杂,由来已久的编码任务,与一款GitHub repo融合到一个麻黄云环境.

## 实例

-   [基础会议](https://npmcn.com/package/%40google/jules-sdk/examples/basic-session/README.md)
-   [高级会话](https://npmcn.com/package/%40google/jules-sdk/examples/advanced-session/README.md)
-   [代理工作流程](https://npmcn.com/package/%40google/jules-sdk/examples/agent/README.md)
-   [Webhook 整合](https://npmcn.com/package/%40google/jules-sdk/examples/webhook/README.md)
-   [GitHub 动作](https://npmcn.com/package/%40google/jules-sdk/examples/github-actions/README.md)

## 将工作发送给基于云的会话

```ts
import { jules } from '@google/jules-sdk';

const session = await jules.session({
  prompt: `Fix visibility issues in the examples/nextjs app.

  **Visibility issues**
  - White text on white backgrounds
  - Low contrast on button hover

  **Instructions**
  - Update the global styles and page components to a dark theme with the shadcn zinc palette.
`,
  source: { github: 'davideast/dataprompt', baseBranch: 'main' },
  autoPr: true,
});
```

## 监测代理的进展情况

```ts
import { jules } from '@google/jules-sdk';

const session = jules.session('<session-id>');

for await (const activity of session.stream()) {
  switch (activity.type) {
    case 'planGenerated':
      console.log(`${activity.plan.steps.length} steps.`);
      break;
    case 'progressUpdated':
      console.log(`${activity.title}`);
      // Check for code updates
      if (artifact.type === 'changeSet') {
        const parsed = artifact.parsed();
        for (const file of parsed.files) {
          console.log(`${file.path}: +${file.additions} -${file.deletions}`);
        }
      }
      break;
    case 'sessionCompleted':
      console.log('Session finished successfully.');
      break;
  }
}

// Get the pull-request URL once complete
const outcome = await session.result();
if (outcome.pullRequest) {
  console.log(`PR: ${outcome.pullRequest.url}`);
}
```

## 安装

```bash
npm i @google/jules-sdk
export JULES_API_KEY=<api-key>
```

## 核心特征

### 用编码代理运行云函数

Jules会话在云中运行,可以运行时没有GitHub寄存器. 我们称之为"无复会" 它们非常强大,因为它们像 预设的服务器功能。 Jules VM 带有预配置的图像,有Node.js,Python,Rust,Bun等许多运行时间和工具.

将上下文通过提示并让代理生成结果.

```ts
import { jules } from '@google/jules-sdk';
import { sql } from 'drizzle-orm';

const longDocumentsNobodyWantsToRead = await sql`SELECT * FROM documents`;
const userPrompt = process.argv[2];

const session = await jules.session({
  prompt: `You are a assistant that can read long documents and answer questions about them.

  ## The user's question
  ${userPrompt}

  ## The documents
  ${longDocumentsNobodyWantsToRead.map((e) => e.title).join('\n')}
  
  ## Answer Format
  Create a markdown response with the following sections:
  - Summary
  - Answer
  - Sources Cited
  `,
});

const result = await session.result();
const files = result.generatedFiles();
const answer = files.get('answer.md');
console.log(answer?.content);

// Call the script as CLI
// node index.js "Review the policies and explain to me delivery timelines like I'm 7 years old."
```

### 交互式会议

使用 `jules.session()` 用于您所观察的工作流程,提供反馈,并引导进程.

```typescript
const session = await jules.session({
  prompt: 'Refactor the user authentication module.',
  source: { github: 'your-org/your-repo', baseBranch: 'develop' },
});

console.log(`Session created: ${session.id}`);

await session.waitFor('awaitingPlanApproval');
console.log('Plan is ready. Approving it now.');
await session.approve();

const reply = await session.ask(
  'Start with the first step and let me know when it is done.',
);
console.log(`[AGENT] ${reply.message}`);

const outcome = await session.result();
console.log(`Session finished with state: ${outcome.state}`);
```

### 创建代理会话群

并行处理多个项目 `jules.all()`感觉就像 `Promise.all()` 但内置货币控制.

```javascript
const todos = ['Fix login bug', 'Update README', 'Refactor tests'];

const sessions = await jules.all(todos, (task) => ({
  prompt: task,
  source: { github: 'user/repo', baseBranch: 'main' },
}));

console.log(`Created ${sessions.length} sessions.`);
```

更多控制货币计数和错误处理.

```javascript
const sessions = await jules.all(largeList, mapFn, {
  concurrency: 10,
  stopOnError: false,
  delayMs: 500,
});
```

### 查询您的本地知识库

SDK 缓存在本地保存会话数据,并曝光用于过滤和投影所有会话的查询语言.

```typescript
// Find failed sessions
const failures = await jules.select({
  from: 'sessions',
  where: { state: 'failed' },
  limit: 10,
});

// Get recent agent messages with computed summaries
const messages = await jules.select({
  from: 'activities',
  where: { type: 'agentMessaged' },
  select: ['id', 'createTime', 'summary', 'artifactCount'],
  order: 'desc',
  limit: 5,
});


```

### 反应流

这个 `.stream()` 方法返回一个 `AsyncIterator` 观察特工的进展.

```typescript
for await (const activity of session.stream()) {
  switch (activity.type) {
    case 'planGenerated':
      console.log(
        'Plan:',
        activity.plan.steps.map((s) => s.title),
      );
      break;
    case 'agentMessaged':
      console.log('Agent says:', activity.message);
      break;
    case 'sessionCompleted':
      console.log('Session complete!');
      break;
  }
}
```

### 代码 diffs 与媒体艺术

活动可以包含文物: 代码变化 (:`changeSet`)或图像(`media`) (中文(简体) ).

```typescript
for (const artifact of activity.artifacts) {
  if (artifact.type === 'changeSet') {
    const parsed = artifact.parsed();
    for (const file of parsed.files) {
      console.log(`${file.path}: +${file.additions} -${file.deletions}`);
    }
  }
  if (artifact.type === 'media' && artifact.format === 'image/png') {
    await artifact.save(`./screenshots/${activity.id}.png`);
  }
}
```

### SDK 配置

默认 `jules` 实例查找环境变量 `JULES_API_KEY`。如果需要在代码中设置 API 密钥或创建多个实例,请使用 `with` 方法.

```typescript
import { jules } from '@google/jules-sdk';

// Multiple API keys
const customJules = jules.with({ apiKey: 'other-api-key' });

// Polling & timeouts
const customJules = jules.with({
  pollingIntervalMs: 2000,
  timeout: 60000,
});
```

### 处理错误

SDK 提供了继承自 `JulesError`。 。 。 .

```typescript
import {
  jules,
  JulesError,
  JulesNetworkError,
  JulesApiError,
  JulesRateLimitError,
  MissingApiKeyError
} from '@google/jules-sdk';

try {
  const session = await jules.session({ ... });
} catch (error) {
  if (error instanceof JulesError) {
    console.error(`SDK error: ${error.message}`);
  }
}
```

### 代理来源

每个代理会议都有一个 `source` 属性,用于定义会话中使用的源上下文。 这主要是一个 GitHub 寄存器,但会话也可以在没有源头的情况下运行,并且只使用在快取中传递的上下文.

```typescript
// List all connected sources
for await (const source of jules.sources()) {
  if (source.type === 'githubRepo') {
    console.log(`${source.githubRepo.owner}/${source.githubRepo.repo}`);
    console.log(`  Private: ${source.githubRepo.isPrivate}`);
  }
}

// Get a specific source
const myRepo = await jules.sources.get({ github: 'my-org/my-project' });
if (myRepo) {
  console.log(`Found: ${myRepo.id}`);
}
```

### API 概览

-   **核心 :**
    -   `jules`: 预初始化客户端.
    -   `jules.with(options)`: 创建自定义配置的新客户端.
    -   `jules.run(options)`: 创建自动会话.
    -   `jules.session(options)`: 创建或再水合交互式会话.
    -   `jules.all(items, mapFn, options)`:批处理.
-   **会话控制 :**
    -   `session.ask()`:发送消息并等待代理回复.
    -   `session.send()`:发火而忘之.
    -   `session.approve()`: 核准一项待决计划.
    -   `session.waitFor()`:暂停,直到会话达到特定状态.
    -   `session.result()`:等待最终结果.
-   **意见:**
    -   `session.stream()`: 所有活动的同步执行者.
    -   `session.history()`: 缓存活动流.
    -   `session.updates()`:活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活.
    -   `session.select(query)`:查询本地缓存.
    -   `session.info()`: 获取最新会话状态 .
-   **工艺:**
    -   `artifact.save()`: 保存到文件系统.
    -   `artifact.toUrl()`:获取数据URI.
    -   `artifact.parsed()`: 结构化 diff 解析变化ets.
-   **资料来源:**
    -   `jules.sources()`: 在所有相通源头上进行同步传动.
    -   `jules.sources.get(filter)`:通过标识获取特定源.

## 许可证

阿帕奇 - 2.0

> **说明:** 这不是官方支持的Google产品. 本项目没有资格参加 [Google 开源软件脆弱性奖励方案](https://bughunters.google.com/open-source-security)。 。 。 .

## 常见问题

### @google/jules-sdk 是什么？

官方 Jules 类型SDK

### 如何安装 @google/jules-sdk？

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

### @google/jules-sdk 支持 TypeScript 吗？

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

### @google/jules-sdk 支持 ESM 还是 CommonJS？

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

### @google/jules-sdk 可以商用吗？

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

### @google/jules-sdk 的下载量有多少？

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

### @google/jules-sdk 还在维护吗？

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

