一條命令,插進正在進行的一輪 左邊一個終端裡用 harnessctl send fix-tests.jsonl 發起任務,再用同一條命令發出“先別跑整合測試”,事件檔案裡記下一條 accepted;一根強調色的線從終端連到中間的介面卡,再分成兩路,分別插進右邊兩個 agent 正在推進的進度條中段。 $ harnessctl send fix-tests.jsonl "修復失敗的測試" $ harnessctl send fix-tests.jsonl "先別跑整合測試" {"type":"accepted"}

在終端裡用 Claude Code 或 Codex 時,插話是很自然的事。它在跑測試,我們看到它跑的是一組用不著的整合測試,就直接敲一句“先別跑整合測試,只修單元測試”,回車。Claude Code 會把這句話放進佇列,等手頭的工具呼叫結束後讀到;Codex 也能把它 steer 進正在進行的這一輪。

可一旦想讓指令碼、定時任務或者另一個 agent 來驅動它們,事情就變了。發起還好辦,兩家都有非互動模式:

Terminal window
claude -p "修复 tests/ 下失败的测试" --output-format stream-json --verbose
codex exec --json "修复 tests/ 下失败的测试"

我們希望插話也是一條命令:

Terminal window
harnessctl send fix-tests.jsonl "修复 tests/ 下失败的测试" --cwd ~/repo
harnessctl send fix-tests.jsonl "先别跑集成测试,只修单元测试"

兩條命令一模一樣,也都很快返回。agent 說了什麼、做了什麼,這句話歸到了哪一次互動,要不要批准某條命令,全都寫進 fix-tests.jsonl。把 Codex 的介面卡換成 Claude Code 的,命令一個字不改。要做到這一點,得先回答幾個問題:

  1. 發起一次推理,兩家的差別有多大?
  2. 為什麼發起能用一條命令完成,插話卻不行?
  3. 兩家各自的插話機制差在哪裡,能不能收進同一套語義?
  4. 市面上有沒有現成的協議已經做了這件事?
  5. 如果沒有,這個協議該長什麼樣,介面卡能不能只是一包指令碼?

本文順著這幾個問題一層一層往下講,最後給出我們設計的協議 harnessctl,並在本機驗證它的 Codex 介面卡。


一、會話的發起

現象

上面兩條非互動命令長得差不多:給一段提示詞,拿回一串 JSON 事件,最後一條是結果。要接著聊,兩家也都有續上的辦法12:

Terminal window
# Claude Code:从 JSON 结果里取 session_id,再用 --resume 续上
sid=$(claude -p "开始审查这次改动" --output-format json | jq -r '.session_id')
claude -p "继续,重点看数据库查询" --resume "$sid"
# Codex:事件流的第一行是 {"type":"thread.started","thread_id":"0199a213-…"}
codex exec --json "开始审查这次改动"
codex exec resume 0199a213-… "继续,重点看数据库查询"

分析:一次性程序,加上磁碟上的會話

這兩種用法背後是同一個模型:一個程序只跑一輪。程序啟動,讀入提示詞,跑完這一輪(中間可能有幾十次工具呼叫),把結果寫到 stdout,然後退出。會話不在程序裡,而是以對話記錄的形式存在磁碟上,下一次 --resume 或 exec resume 時再讀回來。

所以“發起”和“續上”很容易統一。把本地 Agent 變成平臺上的 Bot 裡提到過,Multica 為 26 種 agent CLI 做適配時,把差異收斂到一個只有一個方法的介面裡3:

Go
type Backend interface {
Execute(ctx context.Context, prompt string, opts ExecOptions) (*Session, error)
}

要續上的會話 ID 放進 ExecOptions 就行。

可這個介面裡沒有“插話”。一次性程序跑起來以後,還有誰能跟它說話?


二、執行中會話的定址

現象

最直覺的做法是再 resume 一次:第一條 claude -p 還在跑,另開一個終端執行 claude -p --resume "$sid" "先别跑集成测试"。

這句話插不進去。第二個程序從磁碟上讀到的,是會話此刻儲存下來的樣子;它和第一個程序之間沒有任何通道,第一個程序正在跑的那一輪根本不知道有這句話。結果是同一段對話被兩個程序各自往下寫。(Claude Code 新近的後臺會話對這種情況做了特殊處理,第四節再講。)

原因

會話有 ID,但正在執行的那一輪沒有地址。插話的本質,是把一條訊息送進一個還活著的程序。命令列引數在程序啟動時就讀完了,之後能進去的只有 stdin 這一條管道,而這條管道握在啟動它的那個指令碼手裡。

兩家其實都留了長連線的入口。Claude Code 加上 --input-format stream-json 之後,claude -p 不再讀一次就結束,而是持續從 stdin 讀 JSON 訊息;Codex 的 app-server 是一個常駐程序,在 stdio 上跑 JSON-RPC。問題只在於,怎麼讓另一條命令也用上這條連線。

第一次嘗試:用命名管道留住 stdin

對 Claude Code,可以把 stdin 接到一個命名管道上,誰想插話,就往管道里寫一行:

Terminal window
mkfifo /tmp/fix.in
tail -f /tmp/fix.in | claude -p --input-format stream-json \
--output-format stream-json --verbose > /tmp/fix.out &
echo '{"type":"user","message":{"role":"user","content":"修复失败的测试"},"parent_tool_use_id":null}' > /tmp/fix.in
# 过一会儿,另一个脚本:
echo '{"type":"user","message":{"role":"user","content":"先别跑集成测试"},"parent_tool_use_id":null}' > /tmp/fix.in

看起來已經是“一條命令插話”了,但很快會碰到三個問題:

  • 沒有回執。 echo 只要把位元組寫進管道就返回。這句話是插進了當前這一輪,還是排到了下一輪,甚至 claude 是不是早就退出了,寫入方都不知道。
  • 輸出沒人整理。 所有原始輸出都流進 /tmp/fix.out,想知道“我剛才那句話之後發生了什麼”,只能自己去翻。
  • Codex 用不了。 JSON-RPC 是一問一答。turn/steer 必須帶上當前這一輪的 expectedTurnId,這個 ID 要從 stdout 上讀出來;Codex 請求審批時,又是伺服器發給客戶端的一個請求,必須有人回應。單向的管道做不了這些。

解決:讓事件檔案充當會話的地址

回頭看這三個問題,它們指向同一件事:呼叫方和 agent 之間,缺一個雙方都找得到、又不隨程序消失的東西。

最簡單的這種東西就是一個檔案。於是協議這樣約定:呼叫方給出一個檔案路徑,對這個會話的每條命令都帶上同一個路徑;agent 的一切輸出,包括回答、工具進度、輸入的歸屬、要不要批准某條命令,都以一行 JSON 追加進這個檔案。

事件檔案的路徑就是會話的地址 左邊的呼叫方執行 harnessctl send、cancel、reply,每條命令都帶著同一個檔案路徑 fix-tests.jsonl;中間的 codex 介面卡包裡有 harnessctl、manifest.json 和 lib/runtime.py,執行時按需拉起一個執行程序和 codex app-server,這部分協議不管;介面卡把事件追加進右邊的 fix-tests.jsonl,裡面依次是 accepted、request、message、log、result;呼叫方用 tail -f 讀這個檔案。 呼叫方 · 任意指令碼 介面卡包 · codex 事件檔案 追加 tail -f 讀取,按完整行數推進 $ harnessctl send 發起 fix-tests.jsonl "修復…" $ harnessctl send 插話 fix-tests.jsonl "先別跑…" $ harnessctl cancel 打斷 fix-tests.jsonl $ harnessctl reply 審批 fix-tests.jsonl req-1 deny $ tail -f fix-tests.jsonl 包內容 24 KB harnessctl 入口 manifest.json 版本、依賴 lib/runtime.py 執行時 執行程序(按需啟動) → codex app-server ↻ 空閒回收,下次恢復 虛線:介面卡內部怎麼做, 協議不規定。 fix-tests.jsonl 只追加 accepted · R1 · in-1 accepted · R1 · in-2 log · text.delta request · pending request · replied message result · R1 · completed … 呼叫方只讀這一個檔案。
圖 1 · 每條命令都帶著同一個檔案路徑,agent 的一切輸出都追加進這個檔案;介面卡內部怎麼保活,協議不管

三個問題就都有了著落。回執是檔案裡的一行事件;檔案誰都能讀,斷開了也能從任意一行接著讀;Codex 需要的一問一答、Claude Code 需要的一條常開的 stdin,都關在介面卡裡面。

那個必須一直活著的程序並沒有消失,只是成了介面卡的內部實現,呼叫方看不到,協議也不規定。第六節會看到它在實現裡的樣子。

會話有了地址,接下來的問題是:介面卡收到一句“先別跑整合測試”,該怎麼交給 agent?兩家在這一步的做法相當不同。


三、插話語義的差異

Claude Code:訊息上的 priority

--input-format stream-json 模式下,往 stdin 寫的每一行都是一條使用者訊息。如果它在一輪還沒結束時到達,預設的優先順序是 next:Claude 在同一輪裡讀到它,時機是手頭正在跑的工具呼叫結束之後;如果這一輪先結束了,它就開啟下一輪4。

打斷走另一條線:寫一行 type 為 control_request、子型別為 interrupt 的訊息,Claude Code 回一個 control_response5。

Codex:帶前置條件的 turn/steer

Codex 的 app-server 把插話做成了一個獨立的 JSON-RPC 方法 turn/steer6。它的 expectedTurnId 引數是必填的,schema 裡的說明是:這是一個前置條件,和當前活動的那一輪對不上,請求就失敗7。打斷用 turn/interrupt,帶上 threadId 和 turnId。

我在本機用 codex-cli 0.165.0 實測了這幾種情況。沒有登入,所以模型請求會失敗,但輪次的開始、插話和打斷都照常發生:

→ {"method":"turn/steer","id":"in_11","params":{…,"expectedTurnId":"01a19675-9014-…",…}}
← {"id":"in_11","result":{"turnId":"01a19675-9014-71e2-b5f6-b6d450d616b6"}}
→ {"method":"turn/steer","id":"in_12","params":{…,"expectedTurnId":"wrong-turn",…}}
← {"error":{"code":-32600,"message":"expected active turn id `wrong-turn` but found `01a19675-9014-71e2-b5f6-b6d450d616b6`"},"id":"in_12"}
(这一轮结束之后再 steer)
← {"error":{"code":-32600,"message":"no active turn to steer"},"id":"in_6"}

同一句話在兩條線上

同一句插話在兩家線上的報文 左邊是 Claude Code 的 stdin 和 stdout:寫入一條帶 next 優先順序的使用者訊息“先別跑整合測試”後,沒有直接回應,之後才看到工具結果、助手回答和 result;打斷用 control_request interrupt,收到 control_response。右邊是 Codex 的 JSON-RPC:turn/steer 帶 expectedTurnId turn_7,立刻得到 turnId turn_7 的響應;打斷用 turn/interrupt,響應為空物件。 Claude Code · claude -p Codex · codex app-server stdin → / ← stdout NDJSON →user"修復失敗的測試" ←system/initsession_id 9c1e… ←assistanttool_use Bash →user"先別跑整合測試" · next (沒有直接回應) ←usertool_result · pytest ←assistant"好,先只修單元測試" ←resultsubtype success →control_requestsubtype interrupt ←control_responsesubtype success 請求 → / ← 響應與通知 JSON-RPC →turn/start"修復失敗的測試" ←turn/startedturn.id turn_7 ←item/startedcommandExecution →turn/steerturn_7 "先別跑整合測試" ←id:3 resultturnId turn_7 ←item/completedcommandExecution ←item/completed"好,先只修單元測試" ←turn/completedstatus completed →turn/interruptturn_7 ←id:4 result{} 虛線:Claude Code 不回應這條訊息, 它落在哪一輪只能看後面的事件。 Codex 當場回執;turn_7 若已結束, 這條請求直接報錯。
圖 2 · 同一句插話,Codex 當場告訴你它進了哪一輪,Claude Code 要從後續事件裡推斷(報文按官方文件和 schema 簡寫,不是抓包)

把圖 2 兩邊對照,差別集中在兩處。

回執。 Codex 當場告訴你這句話進了哪一輪;Claude Code 對這條訊息不作任何直接回應。--replay-user-messages 會把收到的訊息回顯到 stdout,能確認“收到了”,但不說明落在哪一輪。

競態。 插話的那一刻,這一輪恰好結束了怎麼辦?Claude Code 的 next 會自動順延成下一輪;Codex 則直接報錯 no active turn to steer,由客戶端決定怎麼辦。

這兩處差異,都得在協議裡有個交代。動手設計之前,先看看是不是已經有人做了。


四、現有方案的調研

ACP:協議有了,插話還沒進標準

最接近的是 ACP(Agent Client Protocol),Zed 牽頭的編輯器與 agent 之間的協議。它基於 JSON-RPC,agent 通常作為子程序跑在 stdio 上:session/new 建會話,session/prompt 發起一輪,session/cancel 打斷8。Claude Code 和 Codex 都有 ACP 介面卡,codex-acp 內部啟動的就是 Codex 的 app-server。

但 ACP v1 裡沒有往正在執行的一輪追加輸入的請求。兩家的介面卡先各自實現了一個預標準擴充套件 _session/steering9,把它寫進標準的提案還沒有合併10。10 月底合併的 PR #2627 規定,agent 忙的時候也要接受 session/prompt,但收到後是插進當前一輪還是排到下一輪,由 agent 自己決定11。

ACP 本身也不是“一條命令”的形態,它需要一個持續的連線。

acpx:ACP 的命令列客戶端

acpx 補的正是這一層。它是 ACP 的無頭命令列客戶端,內建了 claude、codex 等幾十個 agent 的配置12:

Terminal window
acpx codex sessions new --name backend
acpx codex -s backend "修复 API 分页的 bug"
acpx codex -s backend --no-wait "顺便把测试补上"
acpx codex cancel -s backend

只是 --no-wait 的語義是排到下一輪,不是插進當前這一輪。文件說得很直接:“ACP has no request that adds input to a prompt that is already running”13。給 acpx 加 steer 子命令的 issue 還開著14。

審批方面,acpx 在非互動模式下會直接拒絕需要人工批准的請求15,沒有事後用另一條命令批准的辦法。

廠商自己的守護程序

兩家廠商也各自做了後臺託管,但都不是給指令碼插話用的。

Claude Code 的後臺會話。 claude --bg "任务" 把會話交給一個 supervisor 程序託管,claude stop <id> 停止16。對執行中的後臺會話執行 claude --resume <id> "提示词",提示詞會作為下一輪發過去;但只要帶了管道或重定向,它就什麼都不發,以狀態碼 1 退出17。

Codex 的常駐 app-server。 本機的 codex-cli 0.165.0 裡,codex app-server 多了 daemon 和 proxy 兩個子命令。一次性的命令可以經 proxy 連上常駐服務,但連上之後說的仍是完整的 JSON-RPC。

其他方案

coder/agentapi 用一個記憶體裡的終端模擬器,把 Claude Code、Codex 等包成 HTTP 介面,靠發按鍵模擬插話,效果取決於各家 TUI 的行為,專案也已不再維護18。A2A 是服務之間的 agent 通訊協議19,AG-UI 是 agent 和前端介面之間的事件協議20,MCP 是 agent 呼叫工具的方向21,都不是“驅動一個編碼 agent 會話”的形態。

誰能用一條命令做什麼
方案覆蓋兩家一條命令發起一條命令打斷一條命令插進當前一輪
ACP 協議本身是,經介面卡否,需要常駐連線介面卡擴充套件 _session/steering,未標準化
acpx是是是,cancel否,--no-wait 只排到下一輪
Claude Code 後臺會話只有 Claude Code是,--bg只有 stop,停掉整個會話否,--resume 發的是下一輪,且拒絕指令碼呼叫
Codex app-server daemon只有 Codex否,要經 proxy 說完整的 JSON-RPC協議裡有 turn/steer,但不是一條命令
coder/agentapi是是,HTTP靠發按鍵,取決於各家 TUI;已停止維護
A2A / AG-UI / MCP不是驅動編碼 agent 會話的形態

核實於 2026-11-01。“一條命令”指一次性的 shell 呼叫,不需要呼叫方自己維持連線。

表 1 · 最右一列沒有一個“是”:發起和打斷都有人做了,插進當前一輪的那條命令還沒有

結論是:沒有現成的協議同時滿足“跨 Claude Code 和 Codex、一條命令發起、一條命令在進行中插話”。最接近的是 acpx,它缺三樣東西:插進當前一輪的命令、插話的回執,以及脫離終端的非同步審批。

那就自己設計一個。


五、協議的設計

我們設計的這個協議叫 harnessctl,實現開源在 AgentUse 倉庫22。設計時只守一條原則:呼叫方只說自己要什麼,怎麼做到都是介面卡的事。 落下來就是三樣東西:四條命令、一個事件檔案、一個獨立的介面卡包。

四條命令

harnessctl send <events.jsonl> [<prompt>] [--cwd DIR] [--model MODEL]
harnessctl cancel <events.jsonl>
harnessctl status <events.jsonl>
harnessctl reply <events.jsonl> <request_id> [<answer>]

send、cancel、reply 受理後很快返回,成功時 stdout 為空,結果都看事件檔案。status 輸出一行 JSON,講的是這段對話的狀態(idle、running、awaiting_reply、cancelling、failed),不是程序的狀態。正文可以從 stdin 傳,多行提示詞不用再操心 shell 轉義:

Terminal window
printf '%s' "$prompt" | "$A" send fix-tests.jsonl --cwd ~/repo

發起和插話是同一條 send,呼叫方不用先判斷會話在不在、這一輪結束了沒有。這些判斷它也做不好,因為狀態在它讀到的下一刻就可能變了。

退出碼 0 只表示已受理,不代表模型讀過這句話,更不代表任務成功。命令如果超時,這句話可能已經被受理了,所以不能盲目重發,要先讀事件檔案。

事件檔案的路徑就是會話

規範化之後的絕對路徑是會話的唯一身份,協議裡沒有另外的 session ID。第一次 send 自動建立事件檔案,並把介面卡、cwd、model 繫結到這個地址上。之後可以省略它們;傳了不同的值就報錯。想換工作區,就換一個事件檔案。

send:由介面卡決定投遞

第三節那些差異,全部在這裡消化。兩個介面卡收到同樣的兩條命令,做法不同,但都遵守同一條規則:只公佈確認過的歸屬。

同一條 send 在兩個介面卡的事件檔案裡 兩個介面卡都收到兩條 send。Codex 介面卡在內部發 turn/steer,拿到原生回執後寫 accepted,第二句話 in-2 和第一句 in-1 同屬 run R1,一個 result 同時覆蓋兩句;如果原生回覆這一輪已結束,in-2 改屬新的 run R2。Claude Code 介面卡沒有可靠回執,把 in-2 排進內部佇列,分配 R2,R1 結束後才提交,兩個 run 各有一個 result。 Codex 介面卡 · 有原生回執 Claude Code 介面卡 · 沒有輪次回執 命令與事件,從上往下 fix-tests.jsonl $ send"修復測試" acceptedR1 · in-1 $ send"先別跑整合測試" 內部 turn/steer → result.turnId acceptedR1 · in-2 message"已修復單元測試" resultR1 · [in-1, in-2] 或者:原生回 no active turn,這一輪剛結束 acceptedR2 · in-2 resultR2 · [in-2] 命令與事件,從上往下 fix-tests.jsonl $ send"修復測試" acceptedR1 · in-1 $ send"先別跑整合測試" 忙:證明不了歸屬,放進介面卡的佇列 acceptedR2 · in-2 message"已修復測試" resultR1 · [in-1] R1 結束後,才把 in-2 寫進 stream-json message"好,只修單元測試" resultR2 · [in-2] 虛線:介面卡內部發生的事,不進關鍵事件。 R1、R2 代表介面卡分配的 UUID;兩側的呼叫方寫的命令完全相同。
圖 3 · 呼叫方不選投遞方式:Codex 介面卡拿到回執才公佈歸屬,Claude Code 介面卡證明不了歸屬,就排到下一個 run(Codex 的 run 歸屬來自實測,正文內容和 Claude Code 一側按程式碼流程示意)

Codex 介面卡在內部發 turn/steer,拿到回執後才寫 accepted,這句話歸入當前這次互動。如果原生回的是這一輪剛結束,就分配新的 run_id,開啟下一輪23。

Claude Code 介面卡沒有可靠的輪次回執,忙的時候就先留在自己的佇列裡,這一輪結束後再提交24。代價很直接:在 Claude Code 上,send 目前做不到“工具呼叫結束就讀到”的插話,要等這一輪結束。我們寧可晚一點,也不在檔案裡寫一個證明不了的歸屬。

所以這個協議不保證一句話落在哪裡,只保證事後告訴你它落在了哪裡。想立刻換方向,就先 cancel 再 send。cancel 打斷當前執行,清空還沒處理的輸入,但保留對話歷史;已經發生的工具副作用撤銷不了。

事件:能不能丟

事件只有五種,按能不能丟分成兩層25:

五種事件
型別內容可靠性
accepted完整輸入、input_id、確認的 run_id校驗、加鎖、fsync 之後,send 才返回成功
message完整正文快照,同一 message_id 整條替換關鍵,校驗、加鎖、fsync,不能靠丟日誌丟棄
request審批或提問的 pending、replied、expired 快照
result一個 run 的終態(completed、cancelled、failed)、input_ids、輸出和計量
log流式片段、工具進度、原生回執、程序診斷可丟、可合併、可限流,寫失敗不影響工作結果
表 2 · 前四種足夠重建全部業務狀態,所以第五種可以隨便丟

分層的標準是:把所有 log 都刪掉,業務狀態能不能完整重建? 所以流式片段只能放進 log,正文一定要有一條完整的 message;致命錯誤一定要進 result,不能只寫一條日誌。原生報文也只允許出現在 log 裡,換一個 agent,呼叫方讀到的關鍵事件結構不變。

一句話的結局也不用自己拼。run_id 由介面卡分配,result.input_ids 直接列出這次結果覆蓋了哪幾句話。下面三行來自本機實測,第二行就是插話,它和第一句共用一個 run_id:

JSON
{"type":"accepted","run_id":"fd923206-…","input_id":"bb5fd1b9-…","text":"修复 tests/ 下失败的测试"}
{"type":"accepted","run_id":"fd923206-…","input_id":"97b7e1dd-…","text":"先别跑集成测试,只修单元测试"}
{"type":"result","run_id":"fd923206-…","input_ids":["bb5fd1b9-…","97b7e1dd-…"],"status":"failed","output":"","usage":null,"cost_usd":null,"error":"unexpected status 401 Unauthorized…"}

審批:也是一行事件加一條命令

agent 需要外部決定時,檔案裡出現一條 pending 的 request:

JSON
{"type":"request","ts":"…","run_id":"550e8400-…","request_id":"req-1","state":"pending","kind":"permission","message":"执行 npm test?"}

呼叫方可以過一會兒再用另一條命令回答,提問類請求也一樣:

Terminal window
"$A" reply fix-tests.jsonl req-1 deny
printf '%s' '{"q1":"Go"}' | "$A" reply fix-tests.jsonl req-2

到兩家原生呼叫的對映

harnessctl 命令到兩家原生呼叫
harnessctlClaude Code · stream-jsonCodex · app-server
send
首次claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages --permission-prompt-tool stdio,寫一條使用者訊息codex app-server --listen stdio://,initialize、thread/start、turn/start
回收後續上同上,加 --resume <session>thread/resume、turn/start
正在忙介面卡內部排隊,這一輪結束後再寫使用者訊息turn/steer 帶 expectedTurnId;這一輪剛結束就改為下一輪
其他
cancelcontrol_request · interruptturn/interrupt;還沒拿到 turn id 時先記下,拿到後再發
reply · 審批control_response,behavior: allow / denyJSON-RPC 響應,decision: accept / decline
reply · 提問AskUserQuestion 的 updatedInput.answersitem/tool/requestUserInput 的 answers

status 只查介面卡自己的狀態,不需要對映。

表 3 · 每條命令在兩家都找得到對應的原生呼叫,差異全部收在介面卡裡(讀自兩個後端模組)

協議裡已經沒有程序了。可第二節說過,必須有一個活著的程序握著原生連線。它去哪了?


六、參考實現:執行程序

按需啟動,空閒回收

答案是每個地址一個執行程序,由 send 按需拉起。它持有原生連線、佇列和待回覆請求26:

一句插話在 Codex 介面卡內部走過的路 harnessctl send 經本機 IPC 把話交給執行程序;執行程序向 codex app-server 發 turn/steer,收到 result.turnId 後,把 accepted 校驗、加鎖、fsync 寫進 fix-tests.jsonl,send 這才以 0 退出。恢復標識、繫結配置和執行鎖放在旁邊的 fix-tests.jsonl.d 目錄。呼叫方用 tail -f 讀事件檔案。 介面卡內部 · 一個事件檔案地址 本機 IPC 退出碼 0 turn/steer result.turnId 校驗 → 加鎖 → fsync $ harnessctl send "先別跑整合測試" lib/runtime.py _worker 佇列 · run_id · 待回覆請求 原生連線 · 完整正文 執行程序 · 按需啟動,空閒回收 codex app-server fix-tests.jsonl 公開 accepted · R1 · in-2 … $ tail -f fix-tests.jsonl.d/ 私有 config.json 繫結 cwd、model native.json 原生恢復標識 runtime.lock 失聯檢測 虛線:執行程序屬於實現,協議裡沒有它。send 等到原生回執才寫 accepted,不等模型回答。
圖 4 · 常駐的是一個按需啟動的執行程序;插話的歸屬由原生回執確認之後,才寫進事件檔案

命令和執行程序之間走本機 socket,但 socket 只出現在實現裡,換掉它不影響任何呼叫方。這正是把“每個動作一條命令”作為協議邊界的好處。

回收。 沒有活動執行、待處理輸入和待回覆請求時,執行程序空閒約 60 秒後退出,下一次 send 接著原來的上下文繼續。所以協議不需要“關閉”這個動作。

失聯。 執行程序被 kill -9 之後,下一條命令能透過檔案鎖發現它沒了。這時介面卡把還沒有結果的輸入記成 failed,但不重放:它們可能已經執行了一半,再跑一遍可能重複產生副作用。

介面卡還是“一包指令碼”。Codex 的包打出來約 24 KB,只依賴 Linux 和 Python 3.9 以上的標準庫,以及使用者自己裝好並登入的 codex。代價是程式碼量約 1100 行,大頭是執行程序;目前也只支援 Linux。

實測

我們從打好的 tar.gz 解壓,用本機 codex-cli 0.165.0 跑了一遍。沒有登入,所以模型請求會以 401 失敗,但輪次的開始、插話、打斷、回收和恢復都照常發生:

Terminal window
$ A=./codex/harnessctl
$ "$A" send fix.jsonl "修复 tests/ 下失败的测试" --cwd repo # 168 ms,含拉起运行进程
$ "$A" status fix.jsonl
{"state": "running", "run_id": "fd923206-…", "queued": 0, "requests": [], "cwd": "/tmp/hc-run4/repo", "model": null}
$ "$A" send fix.jsonl "先别跑集成测试,只修单元测试" # 134 ms,已拿到原生回执

接著試了幾種邊角情況:

  • 換一個 --cwd 再 send:退出碼 2,cwd is bound to this event path。
  • 空閒 72 秒後:執行程序已退出。再 send,175 ms 返回,還是同一個 thread。
  • 執行中 kill -9 執行程序:下一次 status 補寫一條 failed 的 result(Runtime lost; input outcome is uncertain)。再 send 恢復同一個 thread,舊輸入沒有重放。
  • 執行中 cancel:這句話得到一條 cancelled 的 result,狀態回到 idle。

倉庫自帶的 29 個測試也全部透過,它們用一個假的後端驅動兩個介面卡。

還沒有驗證的:真實的審批路徑(未登入時模型不會去執行命令,request 和 reply 只在假後端上跑過),以及真實的 Claude Code(本機沒有安裝,這一側來自讀程式碼和假後端測試)。

拿來用

Terminal window
git clone --depth 1 https://github.com/memory-co/agentuse.git
python3 agentuse/harnessctl/package.py --adapter codex --output-dir ./dist
mkdir -p ~/.harness && tar xzf dist/harnessctl-codex-*-linux.tar.gz -C ~/.harness
~/.harness/codex/harnessctl status /tmp/none.jsonl # 退出码 4:地址不存在,说明入口可用

七、回到起點

回到開頭那兩條命令:

Terminal window
A=~/.harness/codex/harnessctl
"$A" send fix-tests.jsonl "修复 tests/ 下失败的测试" --cwd ~/repo
"$A" send fix-tests.jsonl "先别跑集成测试,只修单元测试"

兩條命令都在零點幾秒內返回。第二句話在 Codex 上併入同一個 run_id,在 Claude Code 上排到下一個 run_id,事件檔案都如實記下了。把 A 換成 Claude Code 介面卡的路徑,其餘一個字不改。


小結

  1. 發起一次推理,兩家差別大嗎? 不大。兩家都是一個程序跑一輪,會話存在磁碟上。
  2. 為什麼插話做不到一條命令? 正在執行的那一輪沒有地址,而插話要把訊息送進一個活著的程序。
  3. 怎麼給執行中的會話一個地址? 用一個事件檔案的路徑,一切輸出都追加進這個檔案。
  4. 兩家的插話差在哪? Claude Code 沒有輪次回執;Codex 當場回執,這一輪結束了就報錯。
  5. 有現成的協議嗎? 沒有完全滿足的。發起和打斷都有人做了,一條命令插進當前一輪還沒有。
  6. harnessctl 怎麼設計? 四條命令 send、cancel、status、reply,由介面卡決定投遞,只公佈確認過的歸屬;四種關鍵事件足夠重建業務狀態,log 可以丟。
  7. 那個常駐程序去哪了? 變成每個地址一個按需啟動的執行程序,空閒回收,失聯時不重放。它只是實現細節,協議裡沒有它。

參考資料

參考資料

  1. Run Claude Code programmaticallyClaude Code Docscode.claude.com ↗--output-format json 取 session_id 再 --resumehttps://code.claude.com/docs/en/headless ↩

  2. Codex non-interactive modeOpenAI Developersdevelopers.openai.com ↗codex exec --json 的事件型別,codex exec resumehttps://developers.openai.com/codex/noninteractive ↩

  3. server/pkg/agent/agent.goMultica 原始碼收藏github.comhttps://github.com/multica-ai/multica/blob/main/server/pkg/agent/agent.go ↩

  4. Agent SDK reference - TypeScriptClaude Code Docscode.claude.com ↗SDKUserMessage.priorityhttps://code.claude.com/docs/en/agent-sdk/typescript ↩

  5. claude-agent-sdk-python · query.pyGitHubgithub.com ↗control_request / control_response 信封,interrupt 與 can_use_tool 兩種子型別https://github.com/anthropics/claude-agent-sdk-python/blob/main/src/claude_agent_sdk/_internal/query.py ↩

  6. Codex App ServerOpenAI Developersdevelopers.openai.com ↗JSON-RPC 2.0,線上省略 "jsonrpc":"2.0";turn/steer、turn/interrupthttps://developers.openai.com/codex/app-server ↩

  7. codex app-server generate-json-schema 的輸出本機 codex-cli 0.165.0 生成。TurnSteerParams.expectedTurnId:“Required active turn id precondition. The request fails when it does not match the currently active turn.”;CommandExecutionApprovalDecision 取值 accept / decline 等 ↩

  8. ACP · Prompt TurnAgent Client Protocolagentclientprotocol.com ↗https://agentclientprotocol.com/protocol/v1/prompt-turn ↩

  9. codex-acp · Session steeringGitHubgithub.com ↗預標準擴充套件 _session/steering,claude-agent-acp 也實現了同名擴充套件https://github.com/agentclientprotocol/codex-acp/blob/main/docs/steering.md ↩

  10. RFD: steer and queue prompts sent while the Agent is workingGitHubgithub.com ↗截至 2026-11-01 仍為 openhttps://github.com/agentclientprotocol/agent-client-protocol/pull/1261 ↩

  11. docs(protocol): define prompts sent during active workGitHubgithub.com ↗2026-10-29 合併https://github.com/agentclientprotocol/agent-client-protocol/pull/2627 ↩

  12. openclaw/acpxGitHubgithub.com ↗https://github.com/openclaw/acpx ↩

  13. acpx · PromptingGitHubgithub.com ↗“ACP has no request that adds input to a prompt that is already running”https://github.com/openclaw/acpx/blob/main/docs/prompting.md ↩

  14. acpx #836: Support the adapters' `_session/steering` extensionGitHubgithub.com ↗截至 2026-11-01 仍為 openhttps://github.com/openclaw/acpx/issues/836 ↩

  15. acpx · PermissionsGitHubgithub.com ↗https://github.com/openclaw/acpx/blob/main/docs/permissions.md ↩

  16. Manage multiple agents with agent viewClaude Code Docscode.claude.com ↗claude --bg、claude agents --json、claude stop,以及 supervisor 程序https://code.claude.com/docs/en/agent-view ↩

  17. Resume a running background sessionClaude Code Docscode.claude.com ↗帶管道、重定向或 --output-format json 時什麼都不發,以狀態碼 1 退出https://code.claude.com/docs/en/sessions ↩

  18. coder/agentapiGitHubgithub.com ↗https://github.com/coder/agentapi ↩

  19. A2A Protocol SpecificationA2Aa2a-protocol.org ↗https://a2a-protocol.org/latest/specification/ ↩

  20. ag-ui-protocol/ag-uiGitHubgithub.com ↗https://github.com/ag-ui-protocol/ag-ui ↩

  21. Model Context Protocol SpecificationMCPmodelcontextprotocol.io ↗https://modelcontextprotocol.io/specification/2025-06-18 ↩

  22. harnessctl/2:本機 Harness CLI 協議memory-co/agentusegithub.com ↗協議規範,提交 91bb42dhttps://github.com/memory-co/agentuse/blob/91bb42d82160d226c7f5337565879ffcf384685b/harnessctl/README.md ↩

  23. harness/codex/lib/codex.pymemory-co/agentusegithub.com ↗STEER_WHILE_BUSY = True,只把 no active turn 和 expected active turn 當作競態https://github.com/memory-co/agentuse/blob/91bb42d82160d226c7f5337565879ffcf384685b/harnessctl/harness/codex/lib/codex.py ↩

  24. harness/claudecode/lib/claudecode.pymemory-co/agentusegithub.com ↗STEER_WHILE_BUSY = False;“replay is receipt, and result/echo ordering alone does not prove model consumption or turn”https://github.com/memory-co/agentuse/blob/91bb42d82160d226c7f5337565879ffcf384685b/harnessctl/harness/claudecode/lib/claudecode.py ↩

  25. harnessctl/2:五種公共 JSONL 事件memory-co/agentusegithub.com ↗https://github.com/memory-co/agentuse/blob/91bb42d82160d226c7f5337565879ffcf384685b/harnessctl/EVENT.md ↩

  26. harness/codex/lib/runtime.pymemory-co/agentusegithub.com ↗執行程序、佇列、失聯恢復https://github.com/memory-co/agentuse/blob/91bb42d82160d226c7f5337565879ffcf384685b/harnessctl/harness/codex/lib/runtime.py ↩