jules

Jules 任务委派

将编码任务委派给 Google 的 Jules AI Agent，处理 GitHub 仓库。

环境变量

变量	必需	描述
JULES_API_KEY	用于 API 身份验证	来自 jules.google.com/settings 的 API 密钥

设置（在运行第一条命令前）

有两种身份验证方式。交互式使用请选择 方式 1，无头模式／Agent 使用请选择 方式 2。

方式 1：CLI（交互式）

1. 安装 CLI

which jules || npm install -g @google/jules

2. 检查身份验证

jules remote list --repo

如果失败 → 告知用户运行 jules login（无头模式下使用 --no-launch-browser）

方式 2：API 密钥（无头模式／Agent 使用）

1. 获取 API 密钥

从 jules.google.com/settings 获取密钥（每个账号限 3 个密钥）。

2. 设置环境变量

export JULES_API_KEY="your-api-key"

3. 验证

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

通用设置（两种方式均适用）

自动检测仓库

git remote get-url origin 2>/dev/null | sed -E 's#.*(github\.com)[/:]([^/]+/[^/.]+)(\.git)?#\2#'

如果不是 GitHub 仓库或不在 git 仓库中 → 向用户询问 --repo owner/repo

验证仓库已连接

检查仓库是否在 jules remote list --repo 中。如果不在 → 引导用户访问 https://jules.google.com

命令（CLI）

创建任务

jules new "Fix auth bug"                                   # Auto-detected repo
jules new --repo owner/repo "Add unit tests"               # Specific repo
jules new --repo owner/repo --parallel 3 "Implement X"     # Parallel sessions
cat task.md | jules new --repo owner/repo                  # From stdin

监控

jules remote list --session    # All sessions
jules remote list --repo       # Connected repos

获取结果

jules remote pull --session <id>         # View diff
jules remote pull --session <id> --apply # Apply locally
jules teleport <id>                      # Clone + apply

最新会话快捷方式

LATEST=$(jules remote list --session 2>/dev/null | awk 'NR==2 {print $1}')
jules remote pull --session $LATEST

命令（API）

创建任务

curl -s -X POST "https://jules.googleapis.com/v1alpha/sessions" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix auth bug",
    "prompt": "Fix the authentication timeout issue in src/auth.ts",
    "sourceContext": {
      "repository": "owner/repo",
      "branchName": "main"
    },
    "automationMode": "AUTO_CREATE_PR",
    "requirePlanApproval": false
  }'

关键字段：

• prompt — 任务描述（必需）
• sourceContext.repository — GitHub owner/repo（必需）
• sourceContext.branchName — 目标分支（默认为仓库默认分支）
• automationMode — 设置为 "AUTO_CREATE_PR" 以自动创建 PR；手动创建时省略
• title — 会话的显示名称
• requirePlanApproval — 设为 true，以便在执行前暂停并审核计划

列出会话

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

获取会话状态

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

轮询直至完成（API）

SESSION_ID="<id>"
while true; do
  STATE=$(curl -s -H "x-goog-api-key: $JULES_API_KEY" \
    "https://jules.googleapis.com/v1alpha/sessions/$SESSION_ID" \
    | python3 -c "import sys,json; print(json.load(sys.stdin).get('state','UNKNOWN'))")
  case "$STATE" in
    COMPLETED)
      echo "Done!"
      break ;;
    FAILED)
      echo "Failed. Check: https://jules.google.com/session/$SESSION_ID"
      break ;;
    *)
      echo "State: $STATE - waiting 30s..."
      sleep 30 ;;
  esac
done

智能上下文注入

在提示词中加入当前上下文，以获得更好的结果：

BRANCH=$(git branch --show-current)
RECENT_FILES=$(git diff --name-only HEAD~3 2>/dev/null | head -10 | tr '\n' ', ')
RECENT_COMMITS=$(git log --oneline -5 | tr '\n' '; ')
STAGED=$(git diff --cached --name-only | tr '\n' ', ')

创建任务时使用（CLI）：

jules new --repo owner/repo "Fix the bug in auth module. Context: branch=$BRANCH, recently modified: $RECENT_FILES"

创建任务时使用（API）：

curl -s -X POST "https://jules.googleapis.com/v1alpha/sessions" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"Fix the bug in auth module. Context: branch=$BRANCH, recently modified: $RECENT_FILES\",
    \"sourceContext\": {\"repository\": \"owner/repo\", \"branchName\": \"$BRANCH\"},
    \"automationMode\": \"AUTO_CREATE_PR\"
  }"

提示词模板

常见任务的快捷命令：

添加测试

FILES=$(git diff --name-only HEAD~3 2>/dev/null | grep -E '\.(js|ts|py|go|java)$' | head -5 | tr '\n' ', ')
jules new "Add unit tests for recently modified files: $FILES. Include edge cases and mocks where needed."

添加文档

FILES=$(git diff --name-only HEAD~3 2>/dev/null | grep -E '\.(js|ts|py|go|java)$' | head -5 | tr '\n' ', ')
jules new "Add documentation comments to: $FILES. Include function descriptions, parameters, return values, and examples."

修复 Lint 错误

jules new "Fix all linting errors in the codebase. Run the linter, identify issues, and fix them while maintaining code functionality."

审查 PR

PR_NUM=123
PR_INFO=$(gh pr view $PR_NUM --json title,body,files --jq '"\(.title)\n\(.body)\nFiles: \(.files[].path)"')
jules new "Review this PR for bugs, security issues, and improvements: $PR_INFO"

Git 集成（应用并提交）

Jules 完成后，将更改应用到新分支：

SESSION_ID="<id>"
TASK_DESC="<brief description>"

# Create branch, apply, commit
git checkout -b "jules/$SESSION_ID"
jules remote pull --session "$SESSION_ID" --apply
git add -A
git commit -m "feat: $TASK_DESC

Jules session: $SESSION_ID"

# Optional: push and create PR
git push -u origin "jules/$SESSION_ID"
gh pr create --title "$TASK_DESC" --body "Automated changes from Jules session $SESSION_ID"

轮询直至完成（CLI）

等待会话结束：

SESSION_ID="<id>"
while true; do
  STATUS=$(jules remote list --session 2>/dev/null | grep "$SESSION_ID" | awk '{print $NF}')
  case "$STATUS" in
    Completed)
      echo "Done!"
      jules remote pull --session "$SESSION_ID"
      break ;;
    Failed)
      echo "Failed. Check: https://jules.google.com/session/$SESSION_ID"
      break ;;
    *User*)
      echo "Needs input: https://jules.google.com/session/$SESSION_ID"
      break ;;
    *)
      echo "Status: $STATUS - waiting 30s..."
      sleep 30 ;;
  esac
done

AGENTS.md 模板

在仓库根目录创建此文件，以改进 Jules 的结果：

# AGENTS.md

## Project Overview
[Brief description]

## Tech Stack
- Language: [TypeScript/Python/Go/etc.]
- Framework: [React/FastAPI/Gin/etc.]
- Testing: [Jest/pytest/go test/etc.]

## Code Conventions
- [Linter/formatter used]
- [Naming conventions]
- [File organization]

## Testing Requirements
- Unit tests for new features
- Integration tests for APIs
- Coverage target: [X]%

## Build & Deploy
- Build: `[command]`
- Test: `[command]`

会话状态

状态	操作
Planning / In Progress	等待
Awaiting User F	在网页 UI 中回复
Completed	拉取结果
Failed	检查网页 UI

备注

• CLI 无法回复 → 使用网页 UI 回答 Jules 的问题
• CLI 无法取消 → 使用网页 UI 取消
• 仅支持 GitHub → 不支持 GitLab／Bitbucket
• AGENTS.md → Jules 会读取仓库根目录中的此文件以获取上下文
• API 与 CLI → 无头模式／Agent 自动化请使用 API（JULES_API_KEY）；交互式会话请使用 CLI