即時編碼智慧體觀察

Name: Potato
Author: Potato

即時觀察編碼智慧體工作，支援暫停、回滾和分支。可選三種後端：本地模型用 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

agentic:
  enabled: true
  display_type: coding_trace
  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

agentic:
  enabled: true
  display_type: coding_trace
  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

agentic:
  enabled: true
  display_type: coding_trace
  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)
      keyboard_shortcut: "Space"

傳送指令

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

yaml

live_agent:
  controls:
    send_instructions:
      enabled: true
      placeholder: "Type instructions for the agent..."
      inject_as: system_message      # "system_message" or "user_message"
      keyboard_shortcut: "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
      keyboard_shortcut: "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
      keyboard_shortcut: "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
python -m potato.cleanup_sessions --older-than 7d

資料格式

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

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

task_name: "Live Coding Agent Observation"
task_dir: "."
 
data_files:
  - "data/coding_tasks.jsonl"
 
item_properties:
  id_key: id
  text_key: task_description
 
agentic:
  enabled: true
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified
    diff_context_lines: 3
    syntax_highlight: true
    show_line_numbers: true
    terminal_theme: dark
    file_tree:
      enabled: true
      position: left
      click_to_navigate: 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
        keyboard_shortcut: "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/"
output_annotation_format: "jsonl"

分支軌跡匯出

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

json

{
  "id": "task_001",
  "annotator": "observer_01",
  "root_branch": {
    "branch_id": "main",
    "steps": [
      {"step": 0, "type": "file_read", "file": "src/parser.py", "rating": "Good"},
      {"step": 1, "type": "edit", "file": "src/parser.py", "rating": "Incorrect"}
    ],
    "children": [
      {
        "branch_id": "branch_1",
        "branch_point": 1,
        "instruction": "Try a different approach -- use a try/except block instead",
        "steps": [
          {"step": 2, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 3, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      },
      {
        "branch_id": "branch_2",
        "branch_point": 1,
        "instruction": "Read the test file first to understand expected behavior",
        "steps": [
          {"step": 2, "type": "file_read", "file": "tests/test_parser.py", "rating": "Good"},
          {"step": 3, "type": "edit", "file": "src/parser.py", "rating": "Good"},
          {"step": 4, "type": "terminal", "command": "pytest", "rating": "Good"}
        ],
        "outcome": "Fully Complete",
        "children": []
      }
    ]
  },
  "branch_preference": "Branch B",
  "observation_notes": "Both branches solved the problem, but branch B produced cleaner code by reading the tests first."
}

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

bash

# Export as DPO preference pairs from branch comparisons
python -m potato.export \
  -i output/ \
  -f branching_dpo \
  -o results/branch_preferences.jsonl
 
# Export full trajectory trees
python -m potato.export \
  -i output/ \
  -f trajectory_tree \
  -o results/trajectory_trees.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

# Remove branches older than 7 days
python -m potato.cleanup_sessions --older-than 7d
 
# Remove all session branches
python -m potato.cleanup_sessions --all
 
# Dry run (show what would be deleted)
python -m potato.cleanup_sessions --older-than 7d --dry-run

另請參閱

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

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