Agentrepl.jl

🚀 AgentREPL.jl

AgentREPL.jl 是一個通過 MCP（模型上下文協議）為 AI 代理提供持久化 Julia REPL 的工具。它有效解決了 Julia 的 “首次執行時間（TTFX）” 問題，避免了每次調用 julia -e "..." 時的啟動、包加載和 JIT 編譯開銷，顯著提升了 AI 代理工作流的效率。

🚀 快速開始

選項 A：使用插件（推薦）

使用 AgentREPL 最簡單的方法是通過隨附的 Claude Code 插件：

claude /plugin add samtalki/AgentREPL.jl

這將提供：

• 自動配置的 MCP 服務器（無需手動設置）
• 斜槓命令：/julia-reset、/julia-info、/julia-pkg、/julia-activate
• Julia 開發的最佳實踐技巧

選項 B：手動 MCP 配置

claude mcp add julia-repl -- julia --project=/path/to/AgentREPL.jl /path/to/AgentREPL.jl/bin/julia-repl-server

使用 AgentREPL

啟動一個新的 Claude Code 會話。當 Claude 需要時，Julia MCP 服務器將自動啟動。 向 Claude 提出運行 Julia 代碼的請求，例如：

"Calculate the first 10 Fibonacci numbers in Julia"

Claude 將使用 eval 工具並顯示 REPL 風格的輸出：

julia> [fibonacci(i) for i in 1:10]

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

第一次調用可能需要幾秒鐘進行 JIT 編譯；後續調用將即時完成。

✨ 主要特性

解決 TTFX 問題

Julia 的 “首次執行時間（TTFX）” 問題嚴重影響 AI 代理工作流。每次 julia -e "..." 調用都會產生 1 - 2 秒的啟動、包加載和 JIT 編譯時間。AgentREPL 通過 MCP STDIO 傳輸提供持久化的 Julia 會話，Julia 進程保持活動狀態，因此只需支付一次 TTFX 成本。

與其他工具對比優勢

關鍵優勢

• STDIO 傳輸：不打開網絡端口，更安全，可註冊到 Julia General。
• 自動啟動：Claude Code 在需要時自動啟動 AgentREPL。
• 持久化狀態：變量、函數和已加載的包在多次調用之間保持有效。
• 真正的硬重置：工作子進程模型允許在不重啟 Claude Code 的情況下重新定義類型。
• 現代工作流：內置對 Pkg.test、Pkg.develop 和 Pkg.free 的支持。
• 簡單設置：使用插件無需配置，或通過一個命令進行手動設置。

📦 安裝指南

正式安裝

using Pkg
Pkg.add(url="https://github.com/samtalki/AgentREPL.jl")

開發安裝

Pkg.dev("https://github.com/samtalki/AgentREPL.jl")

💻 使用示例

基礎用法

# 計算前 10 個斐波那契數
julia> [fibonacci(i) for i in 1:10]

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

高級用法

# 定義斐波那契函數並計算前 10 個斐波那契數
julia> function fib(n)
           n <= 1 && return n
           fib(n-1) + fib(n-2)
       end
       [fib(i) for i in 1:10]

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

📚 詳細文檔

工具介紹

eval

在持久化會話中評估 Julia 代碼。輸出以熟悉的 REPL 風格格式化：

julia> x = 1 + 1

2

julia> x + 10

12

變量持久化！多行代碼也適用：

julia> function fib(n)
           n <= 1 && return n
           fib(n-1) + fib(n-2)
       end
       [fib(i) for i in 1:10]

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

打印輸出會顯示在結果之前：

julia> println("Computing..."); 42

Computing...
42

錯誤會被捕獲並顯示截斷的堆棧跟蹤：

julia> undefined_var

UndefVarError: `undefined_var` not defined
Stacktrace:
 [1] top-level scope
  ... (truncated)

特性：

• 變量和函數在多次調用之間保持有效。
• 一次加載的包保持加載狀態。
• 捕獲返回值和打印輸出。
• 捕獲錯誤並顯示堆棧跟蹤。

reset

硬重置：殺死工作進程並重新啟動一個新的進程。

Session reset complete.
- Old worker (ID: 2) terminated
- New worker (ID: 3) spawned
- All variables, functions, and types cleared
- Packages will need to be reloaded with `using`

這使得：

• 清除所有變量。
• 卸載所有包。
• 重新定義類型/結構體（軟重置無法實現）。
• 以全新的 Julia 狀態開始。 激活的環境在重置後保持不變。

info

獲取會話信息，包括工作進程 ID。

Julia Version: 1.12.2
Active Project: /home/user/MyProject
User Variables: x, fib, data
Loaded Modules: 42
Worker ID: 3

activate

切換活動的 Julia 項目/環境。

activate(path=".")
# Activated project: /home/user/MyProject
# Use `pkg(action="instantiate")` to install dependencies if needed.

activate(path="/path/to/OtherProject")
# Activated project: /path/to/OtherProject

activate(path="@v1.10")
# Activated shared environment: @v1.10

激活後，使用以下命令安裝依賴：

pkg(action="instantiate")

pkg

管理當前環境中的 Julia 包。

pkg(action="status")
# Package Status:
# Project MyProject v0.1.0
# Status `~/MyProject/Project.toml`
#   [682c06a0] JSON3 v1.14.0
#   [a93c6f00] DataFrames v1.6.1

pkg(action="add", packages="CSV, HTTP")
# Package add complete.

pkg(action="test")
# Test Summary: | Pass  Total
# MyProject     |   42     42

pkg(action="develop", packages="./MyLocalPackage")
# Development mode: MyLocalPackage -> ~/MyLocalPackage

pkg(action="free", packages="MyLocalPackage")
# Freed MyLocalPackage from development mode

操作：

log_viewer

打開一個終端，即時顯示 Julia 輸出。

log_viewer(mode="auto")
# Log viewer enabled.
# Log file: ~/.julia/logs/repl.log
# A terminal window should have opened.

log_viewer(mode="tmux")
# tmux session 'julia-repl' created. Attach with: tmux attach -t julia-repl

log_viewer(mode="file")
# Log file: ~/.julia/logs/repl.log
# Run manually: tail -f ~/.julia/logs/repl.log

log_viewer(mode="off")
# Log viewer disabled.

對於查看即時打印輸出非常有用，特別是對於長時間運行的計算。

配置

環境/項目管理

有三種方法可以設置 Julia 環境：

1. 運行時設置（推薦）：使用 activate 動態切換環境：

activate(path="/path/to/your/project")
pkg(action="instantiate")

2. 通過環境變量設置：在啟動前設置 JULIA_REPL_PROJECT：

JULIA_REPL_PROJECT=/path/to/your/project claude mcp add julia-repl -- julia --project=/path/to/AgentREPL.jl -e "using AgentREPL; AgentREPL.start_server()"

3. 在代碼中設置：直接傳遞給服務器：

AgentREPL.start_server(project_dir="/path/to/your/project")

激活的環境在 reset 調用後保持不變。

與其他工具的比較

與 Auton.jl 對比

Auton.jl 為人工參與的工作流提供 LLM 增強的 REPL 模式。

何時使用 Auton.jl：當你在 Julia REPL 中工作時需要 LLM 輔助，例如上下文感知建議、代碼生成和迭代優化。

何時使用 AgentREPL：當你希望 Claude Code 在更大的 AI 代理工作流中自主執行 Julia 代碼，而無需人工在 REPL 前操作。

與 ClaudeCodeSDK.jl 對比

ClaudeCodeSDK.jl 是一個從 Julia 調用 Claude Code 的 SDK。它與 AgentREPL 的方向相反。

何時使用 ClaudeCodeSDK.jl：當你想從 Julia 腳本或應用程序中以編程方式調用 Claude 時。

何時使用 AgentREPL：當你希望 Claude Code 在持久化會話中執行 Julia 代碼時。

與 ModelContextProtocol.jl 對比

ModelContextProtocol.jl 是 AgentREPL 所基於的 MCP 框架。它提供了創建 MCP 服務器的構建塊（MCPTool、MCPResource、mcp_server）。

何時使用 ModelContextProtocol.jl：當你想構建超越代碼評估的自定義 MCP 工具時。

何時使用 AgentREPL：當你希望在不編寫任何 MCP 代碼的情況下進行持久化 Julia 評估時。

與 MCPRepl.jl 對比

MCPRepl.jl 是一個啟發了 AgentREPL 的優秀包。主要區別如下：

何時使用 MCPRepl.jl：當你想與 AI 代理共享 REPL（可以看到彼此的命令）時。

何時使用 AgentREPL：當你希望自動啟動、不使用網絡端口或計劃通過 Julia 註冊表分發時。

與 REPLicant.jl 對比

REPLicant.jl 使用 TCP 套接字和自定義協議（非 MCP）。

何時使用 REPLicant.jl：當你使用 just 進行任務自動化時。

何時使用 AgentREPL：當你希望與 Claude Code 進行標準 MCP 集成時。

與 DaemonMode.jl 對比

DaemonMode.jl 是一個用於更快運行 Julia 腳本的客戶端 - 守護進程系統。

何時使用 DaemonMode.jl：對於一般腳本加速（如果使用較舊的 Julia 版本）。

何時使用 AgentREPL：對於現代 Julia 與 AI 代理的集成。

Claude Code 插件

claude-plugin/ 目錄包含一個現成的 Claude Code 插件，提供以下功能：

自動配置的 MCP 服務器

無需手動運行 claude mcp add。插件會自動配置 Julia MCP 服務器。

斜槓命令

最佳實踐技巧

包含的技巧教會 Claude：

• 在調用 eval 之前始終顯示代碼（以便顯示可讀的權限提示）
• 首次環境設置對話
• 何時使用硬重置與繼續執行
• 測試和開發工作流
• 錯誤處理模式

安裝

claude /plugin add samtalki/AgentREPL.jl

或者進行本地開發：

claude --plugin-dir /path/to/AgentREPL.jl/claude-plugin

詳情請參閱 claude-plugin/README.md。

🔧 技術細節

架構

AgentREPL 使用 工作子進程模型 通過 Distributed.jl 實現：

┌─────────────────────────────────────────────────────┐
│ Claude Code                                          │
│   ↕ STDIO (MCP)                                      │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AgentREPL MCP Server (Main Process)             │ │
│ │   ↕ Distributed.jl                              │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Worker Process (code evaluation happens here)│ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

為什麼使用工作子進程？

• reset 可以殺死並重新啟動工作進程以實現 真正的硬重置。
• 類型/結構體重定義可行（進程內重置無法實現）。
• 激活的環境在重置後保持不變。
• 工作進程在首次使用時延遲啟動，以避免 STDIO 衝突。

API 參考

導出函數

start_server(; project_dir=nothing)

使用 STDIO 傳輸啟動 AgentREPL MCP 服務器。 參數：

• project_dir::Union{String,Nothing}：可選的 Julia 項目路徑，用於在工作進程上激活。 示例：

using AgentREPL
AgentREPL.start_server(project_dir="/path/to/myproject")

環境變量

內部架構

對於擴展 AgentREPL 的開發者： 文件結構：

src/
  AgentREPL.jl           # 主模塊（導入、包含、導出）
  types.jl               # 狀態結構體（WorkerState, LogViewerState 等）
  formatting.jl          # 結果格式化，堆棧跟蹤截斷
  worker.jl              # 分佈式工作進程生命週期
  packages.jl            # Pkg 操作，項目激活
  logging.jl             # 日誌查看器功能
  tools.jl               # MCP 工具定義
  server.jl              # start_server 函數
  deprecated/
    tmux.jl              # 已棄用的 tmux 雙向 REPL

關鍵組件：

📄 許可證

本項目採用 Apache License 2.0 許可協議。詳情請參閱 LICENSE。

貢獻說明

歡迎貢獻代碼！請參閱 CONTRIBUTING.md 瞭解以下方面的指南：

• 設置開發環境
• 代碼風格和文檔標準
• 拉取請求流程
• 添加新功能

致謝

• ModelContextProtocol.jl - MCP 框架
• MCPRepl.jl - 靈感來源和先前工作
• REPLicant.jl - 替代方法
• Modern Julia Workflows - 最佳實踐指南

變更日誌

版本歷史和發佈說明請參閱 CHANGELOG.md。

安全說明

詳細的安全考慮請參閱 SECURITY.md。 簡而言之：

• STDIO 傳輸 = 無網絡攻擊面
• 代碼以用戶權限運行
• Claude 會話結束時進程終止
• 不防範惡意代碼（由 AI 決定運行內容）