OA0 = Omni AI 0

OA0 是一个探索 AI 的论坛

现在注册

已注册用户请登录

OA0 › 技能包 › jules-and-lobster：通过 Jules REST API 列出项目资源

jules-and-lobster：通过 Jules REST API 列出项目资源

deployment · 2026-02-15 10:24:24 · 3 次点击 · 0 条评论

名称： jules-api
描述： "通过 curl 使用 Jules REST API (v1alpha) 来列出代码源、创建会话、监控活动、批准计划、发送消息以及获取输出（例如 PR 链接）。当用户希望通过编程方式将编码任务委托给 Jules 时使用。需要设置 JULES_API_KEY 环境变量（从 https://jules.google.com/settings#api 获取）。"
env:
JULES_API_KEY:
required: true
description: "Jules 服务的 API 密钥。从 https://jules.google.com/settings#api 获取"
dependencies:
- name: curl
required: true
description: "用于向 jules.googleapis.com 发起所有 API 请求"
- name: python3
required: true
description: "jules_api.sh 脚本用于安全转义 JSON 字符串"
- name: node
required: false
description: "仅在使用 scripts/jules.js CLI 包装器时需要"
- name: jules
required: false
description: "Jules CLI 二进制文件，仅在使用 scripts/jules.js CLI 包装器时需要"

Jules REST API 技能

快速开始

# 0. 设置你的 API 密钥（必需 — 从 https://jules.google.com/settings#api 获取）
export JULES_API_KEY="your-api-key-here"

# 1. 验证可用代码源（预检）
./scripts/jules_api.sh sources

# 2. 创建一个需要计划批准并自动创建 PR 的会话
./scripts/jules_api.sh new-session \
  --source "sources/github/OWNER/REPO" \
  --title "添加单元测试" \
  --prompt "为认证模块添加全面的单元测试" \
  --branch main \
  --require-plan-approval \
  --auto-pr

# 3. 监控会话进度并批准计划
./scripts/jules_api.sh activities --session SESSION_ID
./scripts/jules_api.sh approve-plan --session SESSION_ID

注意： 使用你的 GitHub 用户名/组织名，而非本地系统用户名（例如 sources/github/octocat/Hello-World，而不是 sources/github/$USER/Hello-World）。

概述

此技能支持通过编程方式与 Jules REST API (v1alpha) 交互，将编码任务委托给 Google 的自主 AI 编码代理 Jules。它支持：

任务分配：使用特定提示创建新的编码会话
会话监控：实时跟踪会话状态和活动
计划管理：批准或审查生成的计划
消息传递：向活动会话发送后续消息
结果集成：从已完成的会话中获取 PR 链接和代码变更

开始之前

1. 获取 API 密钥

在 Jules Web 应用中创建 API 密钥：
- 访问：https://jules.google.com/settings#api
- 你最多可以同时拥有 3 个 API 密钥

在运行代理的机器上导出它：

export JULES_API_KEY="your-api-key-here"

2. 连接你的 GitHub 仓库

在 API 可以对 GitHub 仓库进行操作之前，你必须：
1. 通过 Jules Web UI 安装 Jules GitHub 应用
2. 授予 Jules 访问你希望其工作的特定仓库的权限

3. 验证仓库访问权限

# 列出可用代码源以验证访问权限并查看正确格式
./scripts/jules_api.sh sources

你将看到类似以下的条目：

{
  "sources": [
    {
      "name": "sources/github/octocat/Hello-World",
      "githubRepo": {
        "owner": "octocat",
        "repo": "Hello-World",
        "defaultBranch": { "displayName": "main" },
        "branches": [
          { "displayName": "main" },
          { "displayName": "develop" }
        ]
      }
    }
  ]
}

基础 URL 与认证

属性	值
基础 URL	`https://jules.googleapis.com/v1alpha`
认证头	`x-goog-api-key: $JULES_API_KEY`

所有请求均使用以下方式进行认证：

-H "x-goog-api-key: $JULES_API_KEY"

核心概念

资源

资源	描述
代码源	连接到 Jules 的 GitHub 仓库。格式：`sources/github/{owner}/{repo}`
会话	Jules 执行编码任务的工作单元。包含状态、活动和输出
活动	会话内的单个事件（计划生成、消息发送、进度更新等）

会话状态

状态	描述
`QUEUED`	会话等待开始
`PLANNING`	正在生成执行计划
`AWAITING_PLAN_APPROVAL`	等待用户批准计划
`AWAITING_USER_FEEDBACK`	需要用户输入才能继续
`IN_PROGRESS`	正在主动执行任务
`PAUSED`	临时停止
`COMPLETED`	成功完成
`FAILED`	遇到错误

活动类型

类型	描述
计划已生成	为任务生成了计划
计划已批准	计划已批准（手动或自动）
用户消息	用户向会话发送了消息
代理消息	Jules 发送了消息
进度更新	当前工作的状态更新
会话已完成	会话成功完成
会话失败	会话遇到错误

工作流程

选项 1：需要计划批准并自动创建 PR 的会话（推荐）

创建一个需要先批准计划再执行，并在完成时自动创建 PR 的会话：

./scripts/jules_api.sh new-session \
  --source "sources/github/octocat/Hello-World" \
  --title "修复登录 Bug" \
  --prompt "修复当邮箱为空时登录处理器中的空指针异常" \
  --branch main \
  --require-plan-approval \
  --auto-pr

推荐理由：
- 在 Jules 执行变更前，你可以审查并批准计划
- 完成后自动创建 PR
- 在自动化和人工监督之间取得平衡

选项 2：完全自动化的会话（无需计划批准）

对于非敏感仓库中的低风险或常规任务，可以跳过计划批准：

# 创建无需计划批准的会话（仅用于低风险任务）
./scripts/jules_api.sh new-session \
  --source "sources/github/octocat/Hello-World" \
  --title "修复 README 中的拼写错误" \
  --prompt "修复 README.md 第 5 行的拼写错误" \
  --branch main \
  --auto-pr

警告： 不使用 --require-plan-approval 时，Jules 将自动批准其自己的计划并执行变更。仅将此用于非关键仓库中的低风险任务。

选项 3：交互式会话

在活动会话期间发送后续消息：

# 创建会话
./scripts/jules_api.sh new-session \
  --source "sources/github/octocat/Hello-World" \
  --title "添加 API 端点" \
  --prompt "为用户管理添加 REST API 端点" \
  --branch main

# 发送额外指令
./scripts/jules_api.sh send-message \
  --session SESSION_ID \
  --prompt "同时为所有端点添加输入验证"

API 参考

代码源

列出代码源

列出所有已连接的 GitHub 仓库。

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources"

查询参数：
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| pageSize | 整数 | 30 | 返回的代码源数量 (1-100) |
| pageToken | 字符串 | - | 用于分页的上一个响应中的令牌 |
| filter | 字符串 | - | AIP-160 过滤器（例如 name=sources/source1） |

响应：

{
  "sources": [
    {
      "name": "sources/github/octocat/Hello-World",
      "githubRepo": {
        "owner": "octocat",
        "repo": "Hello-World",
        "isPrivate": false,
        "defaultBranch": { "displayName": "main" },
        "branches": [
          { "displayName": "main" },
          { "displayName": "develop" }
        ]
      }
    }
  ],
  "nextPageToken": "..."
}

获取代码源

按名称检索单个代码源。

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources/github/octocat/Hello-World"

在创建会话前使用此功能查看可用分支。

会话

创建会话

创建一个新的编码会话。

curl -sS "https://jules.googleapis.com/v1alpha/sessions" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -d '{
    "prompt": "为登录模块添加单元测试",
    "title": "添加登录测试",
    "sourceContext": {
      "source": "sources/github/octocat/Hello-World",
      "githubRepoContext": {
        "startingBranch": "main"
      }
    },
    "requirePlanApproval": true,
    "automationMode": "AUTO_CREATE_PR"
  }'

请求体字段：
| 字段 | 类型 | 必需 | 描述 |
|------|------|------|------|
| prompt | 字符串 | 是 | 给 Jules 的任务描述 |
| title | 字符串 | 否 | 会话的简短标题 |
| sourceContext.source | 字符串 | 是 | 代码源名称（例如 sources/github/owner/repo） |
| sourceContext.githubRepoContext.startingBranch | 字符串 | 是 | 起始分支 |
| requirePlanApproval | 布尔值 | 否 | 如果为 true，则暂停等待计划批准。推荐：对于生产仓库设为 true |
| automationMode | 字符串 | 否 | 设置为 AUTO_CREATE_PR 以自动创建 PR |

响应：

{
  "name": "sessions/31415926535897932384",
  "id": "31415926535897932384",
  "prompt": "为登录模块添加单元测试",
  "title": "添加登录测试",
  "state": "QUEUED",
  "url": "https://jules.google/session/31415926535897932384",
  "createTime": "2026-01-15T10:30:00Z",
  "updateTime": "2026-01-15T10:30:00Z"
}

列出会话

列出你的会话。

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=20"

查询参数：
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| pageSize | 整数 | 30 | 返回的会话数量 (1-100) |
| pageToken | 字符串 | - | 用于分页的上一个响应中的令牌 |

获取会话

按 ID 检索单个会话。

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"

响应在完成时包含输出：

{
  "name": "sessions/31415926535897932384",
  "id": "31415926535897932384",
  "state": "COMPLETED",
  "outputs": [
    {
      "pullRequest": {
        "url": "https://github.com/octocat/Hello-World/pull/42",
        "title": "添加登录测试",
        "description": "此 PR 添加了全面的单元测试..."
      }
    }
  ]
}

发送消息

向活动会话发送消息。

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:sendMessage" \
  -d '{"prompt": "同时添加集成测试"}'

使用此功能提供反馈、回答问题或给出额外指令。

批准计划

批准待处理的计划（仅在 requirePlanApproval 为 true 时需要）。

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan"

删除会话

删除一个会话。

curl -sS \
  -X DELETE \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"

活动

列出活动

列出会话的活动。

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?pageSize=30"

查询参数：
| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| pageSize | 整数 | 50 | 返回的活动数量 (1-100) |
| pageToken | 字符串 | - | 用于分页的上一个响应中的令牌 |

响应：

{
  "activities": [
    {
      "name": "sessions/123/activities/456",
      "createTime": "2026-01-15T10:31:00Z",
      "planGenerated": {
        "plan": "1. 分析现有代码\n2. 创建测试文件\n3. 编写测试..."
      }
    },
    {
      "name": "sessions/123/activities/457",
      "createTime": "2026-01-15T10:32:00Z",
      "progressUpdate": {
        "title": "编写测试",
        "details": "为认证模块创建测试文件..."
      }
    }
  ],
  "nextPageToken": "..."
}

活动可能包含带有代码变更的产物：

{
  "artifacts": [
    {
      "changeSet": {
        "gitPatch": {
          "unidiffPatch": "diff --git a/...",
          "baseCommitId": "abc123",
          "suggestedCommitMessage": "为登录添加单元测试"
        }
      }
    }
  ]
}

获取活动

按 ID 检索单个活动。

curl -sS \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities/ACTIVITY_ID"

脚本参考

jules_api.sh

scripts/jules_api.sh 脚本为常见的 API 操作提供了便捷的包装器。

用法：

# 列出代码源
./scripts/jules_api.sh sources

# 列出会话
./scripts/jules_api.sh sessions [--page-size N]

# 列出会话的活动
./scripts/jules_api.sh activities --session <id> [--page-size N]

# 向会话发送消息
./scripts/jules_api.sh send-message --session <id> --prompt "..."

# 批准计划
./scripts/jules_api.sh approve-plan --session <id>

# 创建新会话
./scripts/jules_api.sh new-session \
  --source "sources/github/owner/repo" \
  --title "..." \
  --prompt "..." \
  [--branch main] \
  [--auto-pr] \
  [--no-plan-approval]

标志：
| 标志 | 描述 |
|------|------|
| --source | 代码源名称（格式：sources/github/owner/repo） |
| --title | 会话标题 |
| --prompt | 任务描述或消息内容 |
| --session | 会话 ID |
| --branch | 起始分支（默认：main） |
| --auto-pr | 启用自动 PR 创建 |
| --require-plan-approval | 需要显式计划批准（默认） |
| --no-plan-approval | 跳过计划批准（仅用于低风险任务） |
| --page-size | 返回结果的数量 |

jules.js

scripts/jules.js 脚本包装了 Jules CLI 以用于编程。

用法：

node scripts/jules.js version
node scripts/jules.js list-repos
node scripts/jules.js list-sessions
node scripts/jules.js new --repo owner/repo --task "你的任务"
node scripts/jules.js pull --session SESSION_ID

常见错误模式

"Source not found" 或 "Repository not found"

原因： 仓库未连接或代码源名称格式不正确。

解决方案：
1. 运行 ./scripts/jules_api.sh sources 列出可用代码源
2. 确保你已为此仓库安装了 Jules GitHub 应用
3. 使用列表中的确切代码源名称（例如 sources/github/octocat/Hello-World）

"Missing J

技能包地址：https://github.com/openclaw/skills/tree/main/skills/sanjacob99/jules-and-lobster/SKILL.md

3 次点击 ∙ 0 人收藏

登录后收藏

目前尚无回复

0 条回复