即時編碼智慧體觀察

即時觀察編碼智慧體工作，支援暫停、回滾和分支。可選三種後端：本地模型用 Ollama、Anthropic API，以及 Claude Agent SDK。

v2.4.0 新增

靜態 trace 標註告訴你智慧體做過什麼，即時觀察則告訴你智慧體在人類引導下會怎麼做。Potato 的即時編碼智慧體模式讓標註者即時看著編碼智慧體幹活——讀檔案、改程式碼、跑測試——並隨時介入。你可以暫停智慧體、傳送新指令、回滾到之前的檢查點，或者把軌跡分叉出去嘗試別的思路。

這樣得到的標註資料比單純的靜態 trace 更豐富：完整的帶時間戳的軌跡、標註者的每一次介入、分支決策點，以及來自不同路徑的對比資料。這些資料可以直接用於訓練過程獎勵模型、偏好模型和指令遵循評估器。

環境要求

Python 3.10+
Git（檢查點系統基於 git 提交）
以下智慧體後端之一：
- Ollama 用於本地模型推理（無需 API key）
- ANTHROPIC_API_KEY 用於訪問 Anthropic API
- Claude Agent SDK 提供完整的 Claude Code 智慧體體驗

後端

Potato 支援三種執行編碼智慧體的後端。每種後端都在子程序中執行智慧體，並把它的動作即時推送到標註介面。

1. Ollama（本地模型）

在本地執行編碼智慧體，不需要 API key。Ollama 對開放權重模型的推理速度不錯，適合開發、測試，以及資料不能離開本機的場景。

安裝：

bash

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
 
# Pull a coding-capable model
ollama pull qwen2.5-coder:7b
 
# Or a larger model for better performance
ollama pull deepseek-coder-v2:16b

配置：

yaml

live_agent:
  enabled: true
  backend: ollama
  model: qwen2.5-coder:7b
 
  ollama:
    host: "http://localhost:11434"    # Ollama server URL
    temperature: 0.2
    num_ctx: 8192                     # context window size
    num_predict: 2048                 # max tokens per response
    keep_alive: "5m"                  # keep model loaded in memory
 
  # Agent capabilities
  tools:
    - read_file
    - edit_file
    - write_file
    - bash
    - glob
    - grep
  max_steps: 50
  step_timeout_seconds: 60

2. Anthropic API

通過 Anthropic API 使用 Claude 模型，編碼能力強並支援工具使用。需要 API key。

準備：

bash

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Or add to .env file
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

配置：

yaml

live_agent:
  enabled: true
  backend: anthropic
  model: claude-sonnet-4-20250514
 
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.2
    system_prompt: |
      You are a coding assistant working on a software project.
      Read files before editing them. Run tests after making changes.
      Explain your reasoning before each action.
 
  # Agent capabilities
  tools:
    - read_file
    - edit_file
    - write_file
    - bash
    - glob
    - grep
  max_steps: 100
  step_timeout_seconds: 120

3. Claude Agent SDK

Claude Agent SDK 提供完整的 Claude Code 智慧體體驗，包括自動工具編排、上下文管理和跨檔案推理。這是能力最強的後端，但需要先安裝 SDK。

準備：

bash

# Install the Claude Agent SDK
pip install claude-agent-sdk
 
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

配置：

yaml

live_agent:
  enabled: true
  backend: claude_agent_sdk
 
  claude_agent_sdk:
    api_key: ${ANTHROPIC_API_KEY}
    model: claude-sonnet-4-20250514
    max_turns: 100
    permission_mode: auto           # auto-approve tool use
    enable_thinking: true           # show extended thinking
 
  max_steps: 100
  step_timeout_seconds: 180

控制操作

標註介面提供四種控制操作，讓標註者引導智慧體的行為。

暫停 / 恢復

點選 Pause 會在兩步之間讓智慧體停下。它做完當前這一步後等待。標註者可以檢視當前狀態、檢查檔案，再決定是讓智慧體繼續還是介入。點選 Resume 讓它繼續執行。

yaml

live_agent:
  controls:
    pause_resume:
      enabled: true
      auto_pause_on_error: true      # pause when a command fails
      auto_pause_after_steps: 0      # pause after N steps (0 = disabled)
      key_value: "Space"

傳送指令

智慧體暫停期間，標註者可以傳送新指令來改變它的方向。當智慧體走上錯誤的路，或者標註者想測試它對引導的反應時，這一項很有用。

yaml

live_agent:
  controls:
    send_instructions:
      enabled: true
      placeholder: "Type instructions for the agent..."
      inject_as: system_message      # "system_message" or "user_message"
      key_value: "Enter"
      presets:
        - "Try a different approach"
        - "Read the error message more carefully"
        - "Check the test file for expected behavior"
        - "Revert your last change and try again"

指令會被注入智慧體的對話上下文。inject_as 決定它以系統訊息（權威指令）還是使用者訊息（對話式引導）的形式出現。

回滾

回滾會把項目恢復到之前的某個 git 檢查點。智慧體做的每一次檔案改動都會自動提交，所以標註者可以點選時間線上任意一個先前步驟，回到那一刻的確切狀態。智慧體的對話上下文也會同步截斷。

yaml

live_agent:
  controls:
    rollback:
      enabled: true
      show_checkpoint_diff: true     # show what will be undone
      require_confirmation: true     # "Are you sure?" dialog
      key_value: "Ctrl+Z"

分支與重放

分支重放把回滾和傳送指令結合起來：標註者回滾到某個檢查點，再發送不同的指令，從而生成一條分叉的軌跡。收集偏好資料時這很有用——你可以從同一個起點出發探索兩種不同做法，再比較結果。

yaml

live_agent:
  controls:
    branch:
      enabled: true
      max_branches: 5                # maximum branches from any checkpoint
      branch_naming: auto            # "auto" or "manual"
      compare_view: true             # side-by-side branch comparison
      key_value: "Ctrl+B"

分支對比檢視把兩條分支並排顯示，並高亮它們分岔的位置。標註者可以評價哪條分支的結果更好，從而產出用於 DPO 訓練的偏好對。

Git 檢查點系統

即時智慧體模式用 git 跟蹤每一次檔案改動，由此提供可靠的回滾、分支和完整的變更歷史。

工作方式

智慧體啟動前，Potato 建立一個名為 potato-session-{session_id} 的新 git 分支
每次檔案改動（編輯、寫入、建立、刪除）之後，Potato 自動提交併附上描述性的提交資訊
每個提交都被標記為一個檢查點，出現在時間線上
回滾通過 git checkout 把工作目錄恢復到任意檢查點
分支會從檢查點提交處建立一個新的 git 分支

配置

yaml

live_agent:
  git_checkpoints:
    enabled: true
    branch_prefix: "potato-session"
    commit_message_format: "Step {step}: {tool} {file_path}"
    auto_commit: true
    cleanup_on_complete: false       # delete session branches when done
    require_clean_working_dir: true  # fail if there are uncommitted changes

手動管理檢查點

bash

# List all Potato session branches
git branch | grep potato-session
 
# View checkpoints for a session
git log potato-session-abc123 --oneline
 
# Clean up old session branches
git branch --list 'potato-session-*' | xargs -r git branch -D

資料格式

即時編碼智慧體任務的輸入資料給出任務描述，以及可選的起始檔案或目錄：

json

{
  "id": "task_001",
  "task_description": "Fix the bug in src/parser.py where empty input causes a crash",
  "project_dir": "/path/to/project",
  "start_file": "src/parser.py",
  "test_command": "python -m pytest tests/test_parser.py -v",
  "context_files": [
    "src/parser.py",
    "tests/test_parser.py"
  ]
}

欄位	必填	說明
`id`	是	任務的唯一識別符號
`task_description`	是	智慧體要做什麼
`project_dir`	是	項目目錄的路徑
`start_file`	否	初始展示給智慧體的檔案
`test_command`	否	用於驗證修復的命令
`context_files`	否	預先載入進智慧體上下文的檔案

配置參考

一個即時編碼智慧體觀察任務的完整配置：

yaml

annotation_task_name: "Live Coding Agent Observation"
task_dir: "."
 
data_files:
  - "data/coding_tasks.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
instance_display:
  fields:
    - key: structured_turns
      type: coding_trace
      label: "Agent session"
      display_options:
        diff_view: unified
        terminal_theme: dark
        collapse_long_outputs: true
        max_output_lines: 50
        show_file_tree: true
        show_step_numbers: true
        show_reasoning: true
 
live_agent:
  enabled: true
  backend: anthropic
  model: claude-sonnet-4-20250514
 
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.2
 
  tools:
    - read_file
    - edit_file
    - write_file
    - bash
    - glob
    - grep
 
  max_steps: 100
  step_timeout_seconds: 120
 
  controls:
    pause_resume:
      enabled: true
      auto_pause_on_error: true
      key_value: "Space"
    send_instructions:
      enabled: true
      inject_as: system_message
      presets:
        - "Try a different approach"
        - "Read the error message carefully"
        - "Run the tests first"
    rollback:
      enabled: true
      require_confirmation: true
    branch:
      enabled: true
      max_branches: 5
      compare_view: true
 
  git_checkpoints:
    enabled: true
    branch_prefix: "potato-session"
    auto_commit: true
    cleanup_on_complete: false
 
annotation_schemes:
  # Per-step ratings during observation
  - annotation_type: trajectory_eval
    name: step_quality
    description: "Rate each agent step as you observe it"
    steps_key: agentic_steps
    correctness_options:
      - "Good"
      - "Acceptable"
      - "Unnecessary"
      - "Incorrect"
 
  # Overall task completion after agent finishes
  - annotation_type: radio
    name: task_completion
    description: "Did the agent complete the task?"
    labels:
      - "Fully Complete"
      - "Partially Complete"
      - "Failed"
 
  # Branch comparison (when branching is used)
  - annotation_type: radio
    name: branch_preference
    description: "Which branch produced a better result?"
    labels:
      - "Branch A"
      - "Branch B"
      - "Both Equal"
      - "Both Failed"
 
  # Notes on the observation
  - annotation_type: text
    name: observation_notes
    description: "Describe what you observed and any interventions you made"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
export_annotation_format: "jsonl"

分支軌跡匯出

標註者使用分支重放後，輸出會包含完整的分支樹。這種格式是為從對比軌跡中訓練偏好模型和過程獎勵模型而設計的。

json

{
  "prompt": "Fix the failing test in tests/test_parser.py",
  "chosen": "...the corrected trajectory...",
  "rejected": "...the original trajectory...",
  "trace_id": "task_001"
}

把分支軌跡匯出用於偏好學習：

bash

python -m potato.export \
  -c config.yaml \
  -f trajectory_correction \
  -o results/

這個匯出器接受配置檔案，並寫進你指定的目錄：trajectory_corrections.json、把修正後的路徑當作 SFT 目標的 trajectory_sft.jsonl，以及把分支對比當作 DPO 偏好對的 trajectory_dpo.jsonl。沒有單獨的軌跡樹格式，分支結構就裝在這些記錄裡面。

安全

即時智慧體執行在任務資料指定的項目目錄中，可以讀、寫和執行該目錄下的檔案。建議注意以下幾點：

沙箱隔離：面對不可信的程式碼或不可信的智慧體模型時，把 Potato 放進 Docker 容器或虛擬機器裡執行。智慧體可以執行任意 shell 命令，隔離很重要。
只讀模式：如果只想讓智慧體分析程式碼而不修改，停用 bash 和 write_file 工具。
網路限制：用 Docker 的 --network none 參數阻止智慧體發起網路請求。
資源上限：設定 max_steps 和 step_timeout_seconds，防止智慧體失控跑飛。

yaml

# Restricted tool set for analysis-only tasks
live_agent:
  tools:
    - read_file
    - glob
    - grep
  # No edit_file, write_file, or bash

故障排查

Ollama 未執行

text

Error: Connection refused at http://localhost:11434

啟動 Ollama 服務：

bash

ollama serve

確認它已在執行：

bash

ollama list

缺少 API Key

text

Error: ANTHROPIC_API_KEY environment variable not set

設定環境變數：

bash

export ANTHROPIC_API_KEY="sk-ant-..."

或者寫進項目的 .env 檔案，Potato 會自動載入 .env。

Git 未初始化

text

Error: Project directory is not a git repository

檢查點系統依賴 git。在項目目錄中初始化一個倉庫：

bash

cd /path/to/project
git init
git add -A
git commit -m "Initial commit"

智慧體陷入迴圈

如果智慧體反覆做同一個動作，它可能卡住了。當同一個工具呼叫帶同樣的參數重複 3 次時，Potato 會判定為迴圈並自動暫停智慧體。這個閾值可以配置：

yaml

live_agent:
  loop_detection:
    enabled: true
    threshold: 3                     # pause after N identical consecutive steps
    action: pause                    # "pause" or "terminate"

清理會話分支

時間久了，會話分支會越積越多，需要定期清理：

bash

# See what is there, newest last
git for-each-ref --sort=committerdate \
  --format='%(committerdate:short)  %(refname:short)' 'refs/heads/potato-session-*'
 
# Remove one session's branch
git branch -D potato-session-abc123
 
# Remove all of them
git branch --list 'potato-session-*' | xargs -r git branch -D

另請參閱

編碼智慧體標註 —— 標註靜態的編碼智慧體 trace
過程獎勵標註 —— 為 PRM 訓練收集逐步獎勵訊號
程式碼評審標註 —— GitHub PR 風格的程式碼變更內聯評審
智慧體標註 —— 通用的智慧體 trace 標註

有關實現詳情，請參閱源文件。