Vacant MCP server
Commit Nov 15, 2026Provides an accountability layer for AI agents by running acceptance tests, gating delivery, and signing every step into a verifiable receipt.
Also known as cosmopig/Vacant
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Vacant MCP?
Vacant provides an accountability layer for AI agents by running acceptance tests, gating delivery, and signing every step into a verifiable receipt.
Summary generated from the project's README
About Vacant MCP server
Vacant acts as an accountability layer for AI agents by serving as a verification gate for their deliverables. Instead of acting as a framework or a mandatory wrapper, it functions as a receiving point that rejects any output lacking a verifiable receipt. It works by running user-defined acceptance tests and signing every step of the process into a hash chain, ensuring that every tool call and file modification is recorded for offline re-verification.
Developers can integrate Vacant with existing agents like pi, Claude Code, OpenCode, or Codex through a zero-configuration installation process. The system does not require API keys, environment variables, or model endpoints to function. It operates locally by adding hooks to the agent's configuration, allowing it to monitor the workspace and provide feedback if an agent claims completion but fails to meet specific requirements, such as missing files or failed test scripts.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecosmopig/vacant is public and reachablegithub.com/cosmopig/vacant ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/cosmopig/vacant ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubVacant
Vacant 不是套在 agent 外面的強制層,也不是另一個 agent framework。 它是收件口:沒有可驗證收據的交付,不被接受。 因為它只看交付物、不在乎 agent 怎麼跑,所以任何框架的產出都能套進來。
跑客戶自己的可執行驗收測資、依結果決定交或不交,把每一次嘗試(含失敗那幾次)簽進可離線
重驗的雜湊鏈。要讓它成為全機唯一出口,需要容器/ACL/egress policy——那是部署層的事,
不是 Vacant 的(vacant_network/controller.py:7-8 早就逐字寫著,只是從沒出現在對外文字裡)。
既有模式,不是我們發明的:供應鏈安全的 in-toto/SLSA/Sigstore 也是同一條 ——「沒有合法 attestation 的 artifact,在收件時被拒」。
裝了就用:零設定(0.9.0,v3.7)
pipx install vacant-network # 0.9.0 起就是零設定版。沒有 pipx:Ubuntu/Debian 用 `sudo apt install pipx`,macOS 用 `brew install pipx`
vacant install # 找到你機器上的 pi/Claude Code/OpenCode/Codex,各加一個掛鉤(可逆:`vacant uninstall`)
vacant dashboard --open # 選用:在本機看 Vacant 的每一個狀態(掛鉤在不在、記了哪些專案、每次退回與交件說明;只讀)
之後照常打開你的 agent。**不用寫契約、設定檔、金鑰、環境變數。**以 pi 為例,vacant install 只在 pi 自己的設定目錄放一個擴充檔
(extensions/vacant.ts),不換掉 agent、不包模型端點。
它做的事只有兩件:
- 全程記錄:每一步工具呼叫、讀了哪些檔、工作區前後改了什麼,簽進一條病歷(
~/.vacant/trace/)。過程中不插話; 沒有問題時,模型收到的每一通請求和沒裝時逐位元組相同。 - agent 說「做完了」那一刻查一次:只看紀錄,只在幾乎一定是真的問題時,在同一個工作階段裡退回請它補(人的一個要求內最多兩回合):
- 要求寫出的檔不存在(提示裡寫的、或你點名的說明檔裡寫的,例如
contract.md說「寫進solution.py」;v3.7) - 失敗的步驟被略過(測試腳本紅了、之後又跑出綠的,不算;v3.7)
- 說「測試通過」但紀錄對不上(任何測試腳本都認,例如
sh run_tests.sh;v3.7) - 文件裡的具體數值在這個任務讀過、跑過的東西裡都找不到(只在你有給資料時)
- 你點名的檔從沒被打開(你在請求裡已經整段貼了它的全文的,不算)
- 要求寫出的檔不存在(提示裡寫的、或你點名的說明檔裡寫的,例如
其他的只寫進交件說明(~/.vacant/trace/projects/<專案>/delivery.md:查了什麼、交件前改了什麼、還沒驗證的),
不送給模型、不寫進你的專案。它不判斷答案對不對——推理錯了但每一步都有根據的答案,它看不出來。
回合預算提醒(v3)預設關(v3.6 起;多交出來的答案錯的多於對的),要開用 vacant install --budget-reminder。
設計與各版裁決:decisions/DECISION_20260925_ZERO_CONFIG_DESIGN.md、
decisions/DECISION_20260926_ZERO_CONFIG_V3.md。
量到了什麼(真模型、照上面兩個指令安裝;條件一定要一起講)
| 批次 | 設定 | 沒裝 → 裝了 | 讀法 |
|---|---|---|---|
| DABstep 77 題 × 3(10-02,預註冊) | gemma-4-12b QAT、vLLM(Colab G4)、pi 0.87.1 --print、15 回合上限 |
42.0% → 53.2%(p=0.0028) | 差來自「agent 說做完卻沒寫答案檔」被退回、補寫(沒裝 42/231 跑、裝了 0);Vacant 把對的改成錯 0 次。⚠ 有 Vacant 那組和 09-26 在 GGUF 後端的成績幾乎一樣,變的是沒裝那組;題組是因為過去有效才選的,不是留出 |
| 任務導向 94 題 × 2(10-02,預註冊) | DABench/DataBench/Polyglot Python,同上但不設回合上限 | 72.3% → 75.0%(p=0.36) | 沒有量到差別;「說做完沒寫檔」只有 5/120 |
| 同上,換 GGUF+LM Studio(10-03,期中) | 人類自己的兩張 RTX 3090 | 119 → 124/188(p=0.37) | 沒有量到差別;「說做完沒寫檔」0 格 |
| 更早:DABstep 付費(09-25)、u274 hard 100 題(09-28)、Colab 程式題 920 題(09-28,v3.6.1) | 見各結論檔 | 都沒有量到差別 | v3.6.1 的誤退(跑過 run_tests.sh 還被退)在 v3.7 修掉:冒煙 0/23 |
⚠ 不能讀成「Vacant 讓 agent 做得更好」,也不能讀成「沒有用」:它補得到的是「說做完卻沒寫要求的檔」這一類;
這種情況多(例如有回合上限、某些推論引擎)才量得到差,少就量不到。錯在決定、或被時限切斷的,它看不到。
已知的限制:題目附的測試一直紅、agent 就說做完,不會被退回;真模型只量過 pi,而且都是 pi --print
(互動介面的流程用照劇本回答的模型驗過)。
結論檔:CONCLUSION_20261002_COLAB_DABSTEP_V37、
CONCLUSION_20261002_COLAB_TASK3_V37、
CONCLUSION_20261003_VACANTDEV_TASK3_INTERIM、
CONCLUSION_20260925_ZERO_CONFIG_DABSTEP、
CONCLUSION_20260926_ZERO_CONFIG_V3_LOCAL;
為什麼零設定大多量不到差、和過去的實驗比:docs/ZERO_CONFIG_EVAL_REPORT_2026-09-26.md。
接到你的 agent 上:pi/Claude Code/OpenCode/Codex(2026-09-24 起)
2026-09-24 的外部質疑報告說對了一件事:判了拒交不等於擋下交付,而模型通道也不是四個 agent
的共通點。這一版把收件口做成真的(vacant_network/intake/)、把它接到四個 agent 上
(vacant_network/adapters/),完全不需要看模型流量。裁決:
decisions/DECISION_20260924_UNIVERSAL_INTAKE.md。
vacant contract quick --deliverable report.md --input data/sales.csv \
--must "Recommendation" --total amount --lock
# 一行寫出人在意的事(除了「繳付物在、沒夾帶憑證檔」兩條底線,只有你寫的才是必要的檢查;--total 讀報告裡
# 'Total' 後面的那個數字,要別的字樣就寫 --total amount=合計;寫錯的欄名、讀不動的欄、總計列當場就說;
# --lock=釘住輸入、簽名)
# 要更多種檢查:vacant contract init …,再編輯 .vacant/contract.json 的 claims
# (存在、段落、數字重算、引用、你自己的命令、人工審查…),然後
vacant contract lock # 釘住原始資料/驗收套件的 sha256,owner 金鑰簽下這份契約
#(收件端只依被鎖過的契約放行;改了契約要重鎖)
vacant install # 在 pi/Claude Code/OpenCode/Codex 各自的設定裡加掛鉤+技能(可逆)
pi # 照常用你的 agent——命令列上沒有 vacant
vacant release # 收件端重驗一切、發布、讀回;不合格的版本不會被它寫進目的端
vacant task report # 每一個開過的任務的終態(含作廢、未決),分母不縮
也可以不裝任何掛鉤:vacant do <agent> --prompt "…" 在隔離工作區裡跑 agent 的 headless 模式,
結束後交進收件口;任何 CLI 用 vacant do --cmd '… {prompt} …';閉源服務或人工上傳走
vacant intake serve(HTTP,提交者給不了裁決)。
四個真 agent+照劇本回答的假模型(L-fake,Vacant 不碰模型流量),同一份非程式任務
(報告的段落、從釘住的 CSV 重算總數、引用要對得到來源且引文在委託者釘住的快照中逐字出現)——
ops/intake/evidence_20260924/SUMMARY.md:
| pi 0.87.1 | Claude Code 2.1.281 | OpenCode 1.18.32 | Codex 0.156.1 | |
|---|---|---|---|---|
錯的報告(總數 999)被 vacant release 寫進目的端? |
沒有 | 沒有 | 沒有 | 沒有 |
| 對的報告被收下、目的端讀回一致? | 是 | 是 | 是 | 是 |
| 交件前回饋送到模型手上(掛鉤)? | 是 | 是 | 否(opencode run 在第一個 idle 就結束;互動 TUI 與 vacant do 有,2026-09-25 量的,見可究責追緝那一節) |
是 |
契約禁止的 git push 被 agent 自己的掛鉤擋下、效果沒發生?(常駐安裝、vacant do 每一跑注入,兩條都量) |
是 | 是 | 是 | 是 |
| Vacant 技能的描述出現在模型收到的請求裡? | 是 | 是 | 是 | 是 |
| 解除安裝後、以及每一跑注入之後,使用者原本的設定逐位元不變? | 是 | 是 | 是 | 是 |
⚠ 這張表不能讀成:「agent 不會繞過」(掛鉤 agent 拆得掉,shell 能繞過字串規則——保證只在收件端)、
「Vacant 讓 agent 做得更好」(回饋後改對是劇本寫的,不是模型能力)、「真模型下成立」(本輪是 L-fake)、
「目的端只有這一條寫入路徑」(dir: 目的端在同一個帳號下是普通目錄;那要靠部署——另一個帳號、ACL、分支保護)。
這一輪是對抗審查修正之後跑的:五個審查鏡頭、60 條逐條重現,修正與沒修的都寫在裁決 §十一。
舊的模型通道常駐安裝仍在:vacant possess install 或 vacant install --observe-model,
但它從此不決定收件。
追到造成錯誤的那一步(可究責追緝,2026-09-24 起)
收件口只回答「這份交付合不合格」。有契約的專案,Vacant 另外把 agent 的每一步記進一條簽章鏈 (四個 agent 的原生掛鉤+Vacant 自己看工作區前後的差異,殼層寫的檔也歸得到那一步),驗收不過時:
- 定位:哪個檔、哪一行、哪個值;
- 追緝:是哪一步寫進去的 → 在重建出來的那一步前後狀態上重跑同一條驗收 → 那個值是從哪裡讀來的 (給定的輸入、子 agent 的回覆、指令輸出、自己寫的腳本、網頁、任務訊息);
- 回饋:回合結束時告訴 agent 位置、應有的值、第一次出現在第幾步——不提是誰(KS-1);
- 不被淹沒:agent 不再被要求繼續時,未解的問題以 Claude Code 的
systemMessage與報告交給人; - 後果:只有可證明的錯進行動者信譽(不 slash,人可以撤銷),輸入錯記在來源上,
沒被記錄的改動記成究責缺口、不怪任何人;路由只給人建議,或
vacant do --agent auto。
vacant trace show # 每一步:誰、什麼工具、寫了什麼;缺口
vacant trace report --check # 未解問題清單(每一條的等級、證據、那一步、來源)
vacant trace blame report.md:3 # 這個位置的值是哪一步、從哪裡來的
vacant flag report.md:2 "市長是 Alice" # 人指出錯處(owner 金鑰簽章;追緝;下一回合告訴 agent)
vacant trace actors # 每個 agent 設定:跑了幾次、過了幾次、幾筆可證明的錯
四個真 agent × 六個埋錯情境(L-fake)——
ops/accountability/evidence_20260924/README.md:
歸因 33/33(agent 憑空寫錯 ⇒ 可證明;輸入本來就錯 ⇒ 指到輸入那一行;腳本算錯 ⇒ 指到寫腳本那一步;
事後有人在外面改檔 ⇒ 缺口、不怪人;子 agent 算錯、主 agent 照抄 ⇒ 指到子 agent 那一步;抓回來的網頁本身就錯 ⇒ 指到網址、agent 不背);有位置的回饋在 Claude Code/Codex/pi 進了模型的下一次請求
(OpenCode run 沒有,既有邊界);回饋裡行動者識別 0/33。同樣的情境走 vacant do:25/25(OpenCode 也收得到回饋);
人直接開四個 agent 的互動介面打字(tmux 裡的真 TUI,含多回合):歸因、回饋到模型、人在畫面上看得到、改好後收下都是 16/16——OpenCode 的互動 TUI 也有交件前回饋。裁決:
decisions/DECISION_20260924_ACCOUNTABLE_TRACE.md。
⚠ 不能讀成:「Vacant 抓出所有錯」(讀取是下限、只有有紀錄的步驟)、「追緝一定正確」(值比對會被巧合騙; 所以只有重跑翻轉的「可證明」才接後果)、「真模型下產出更接近需求」(本輪是 L-fake; 那是 R536 預註冊的事,草稿待簽字)。
⚠ 裝之前先讀這一條:pip install vacant 裝到的不是這個專案
PyPI 上的 vacant(實測 2026-09-19 為 0.4.15,一個 7.5 MB 的
cp311-abi3-manylinux 原生 wheel)是別人的套件——它自己的 Summary 逐字是
"Python bindings for the vacant Rust engine — domain availability via authoritative
DNS"(作者 David Poblador i Garcia,github.com/alltuner/vacant)。
0.7.0 之前兩個名字都撞:它也佔用 vacant 這個 import 名、也裝一支叫
vacant 的指令,兩個套件寫到同一批路徑,實測四種安裝順序每一種都零錯誤訊息。
0.8.0 把 import 名改成 vacant_network(破壞性變更,見
CHANGELOG.md)。
修掉的與沒修掉的要分清楚:
| 0.7.0 以前 | 0.8.0 起 | |
|---|---|---|
import |
兩個套件共用 vacant/ 目錄,pip 逐檔覆蓋 ⇒ import vacant 可能拿到對方的碼 |
已修:目錄名 vacant_network/,兩邊不再共用任何模組 |
vacant 指令 |
後裝的蓋過先裝的 | 沒修,也修不掉——同名 console script 就是同一個檔案路徑 |
| 救法 | pip install --force-reinstall --no-deps vacant-network |
直接改用 vacant-network 指令或 python3 -m vacant_network |
pip install vacant-network # 本專案。⚠ 不是 vacant
python3 -c "import vacant_network; print(vacant_network.__version__)" # 判別式:印 0.8.0
vacant-network --help # 第二指令名,import 的是 vacant_network.cli,對方蓋不到
python3 -m vacant_network --help # 完全不經過 bin/,最後一條打不歪的路
套件名 vacant-network、主指令名 vacant、第二指令名 vacant-network、
import 名 vacant_network。 只有主指令名還跟對方共用。
Python 3.11+。 一條
pip install會拉進 30 個 wheel、60 MB——pyproject.toml宣告的 runtime 相依只有 3 個(cryptography/mcp/jsonschema),其餘是mcp拖進來的(pydantic/starlette/uvicorn/httpx…)。閘門與收據那條路 (vacant_network.vrun.*)用不到mcp,但目前沒有「只要閘門」的 extras,裝了就是全裝。從零開始、含卡住點的逐字安裝紀錄:
docs/INSTALL_LOG_20260919.md(原廠 Ubuntu 24.04,端到端 27 秒)。常見的坑整理在下面〈你可能會遇到〉。
前提句(任何交付成效宣稱都必須帶著它一起講) 整件事建立在『需求可以被編譯成可執行的驗收測資』。需求跑不起來的場合,這個機制沒有免費的 裁判,會退化成『問一個模型』,而那正是量出來很差的東西。 (逐字出自
DECISION_20260903_R440P_CONFORMANCE_GATE.md§五-1)
給 AI agent 的整合契約在 AGENTS.md(索引:llms.txt)。
本頁下半部 §給 AI 讀 是同一份契約的散文版。
30 秒:先看一次閘門判拒交
零設定、零模型端點、零 API key、零網路。
pip install vacant-network
vacant selftest # 先確認這份安裝是活的(端到端迴圈+兩條簽章鏈)
vacant demo gate # 再看閘門判一次拒交(判決;阻擋要靠下面的收件口)
vacant selftest 的逐字輸出(vacant-dev,Ubuntu 24.04/Python 3.12.3,0.3 秒):
端到端迴圈 : ✓(6 次呼叫無例外,4/6 答對)
expert 鏈驗 : ✓
requester 鏈驗: ✓
暫存目錄 : /tmp/vacant-selftest-_bqraq82
⚠ 4/6 不是判準、也不是效能數字(同一版在 macOS 上印 3/6)。selftest 驗的是
「端到端迴圈不丟例外」+「兩條簽章鏈驗得過」,答對幾題不算數。
不需要 clone。(2026-09-18 起:閘門的判斷層搬進套件了——同一份,不是複製;
ops/gain/r530/* 現在 re-export 到 vacant_network/vrun/*,R530 實驗跑的仍然是這一支。)
一隻假 agent 宣告它完成了,客戶的驗收說沒有(實跑輸出摘錄;家目錄縮成 ~,其餘逐字):
$ python3 -m vacant_network.cli run --workspace ~/.vacant-run/demo-gate/ws_vacant \
--suite ~/.vacant-run/demo-gate/tests_visible --run-dir ~/.vacant-run/demo-gate/receipts -- …
Done. I have created solution.py with add() and multiply().
All requirements are implemented and the code is ready to use.
[vacant run] RUN-ON 拒交(visible_fail) ws e5241309c23b→76c38272981f wire 0 通 收據 ~/.vacant-run/demo-gate/receipts
test_visible.py::check_mul — exception: ImportError: cannot import name 'mul' from 'solution' (~/.vacant-run/demo-gate/receipts/_frozen_RUN-ON/solution.py) [test_visible.py:7: from solution import mul]
agent 退出碼 :0 ← agent 自己說它成功了
客戶的驗收 :1/2 通過
裁決 :拒交(visible_fail)
vacant run 退出碼 :20 ← 退出碼反映裁決,不反映 agent 的說法
收據 :2 筆 Ed25519 簽章鏈
agent 說它做完了,客戶的驗收說沒有。 沒有 Vacant,上面那份 solution.py 已經交出去了。
畫面上每一個數字都是當場跑出來的:假 agent 是真子行程、閘門是 vacant_network/vrun/acceptance.py
那一支(R530 實驗跑的同一支)、那句 ImportError 是驗收 driver 當場抓到的例外原文、
20 是 vacant run 這個真子行程的退出碼。vacant_network/vrun/demo.py::_assert_not_a_performance 與
tests/test_demo_gate.py
擋著它不准退化成印死字串。收據當場用同一支驗章器驗過一次,你也可以自己再驗:
python3 -m vacant_network.vrun.verify_receipts --selftest # 先證明驗章器抓得到壞鏈
python3 -m vacant_network.vrun.verify_receipts --glob ~/.vacant-run/demo-gate/receipts
(clone 之後 python3 ops/gain/replay/verify_run_receipts.py … 是同一支——
那個路徑現在是 re-export,R460R/R529/R532 的鏈驗的就是它。)
還需要 clone 的部分(逐條寫出來,不含糊帶過)
vacant demo gate、vacant run、收據驗章都不需要。下面這些才需要:
| 需要 clone 的 | 為什麼不在 wheel 裡 |
|---|---|
ops/vacantrun/block_egress.sh(V3 出網封鎖)+ verify_egress_block.py |
要 root 一次的維運動作,不是產品功能;而且它改的是整台機器的網路規則 |
ops/vacantrun/selftest.py |
端到端自檢,會去讀 repo 的 runs/ |
ops/vacantrun/wrap_agent.sh(pi/Codex/OpenCode/Hermes 的接線) |
那幾個框架把 base url 寫在設定檔裡(Hermes 是一個 --provider custom 旗標),接線是一段 shell 不是產品功能;吃環境變數的框架(Claude Code、走內建 provider 的 OpenCode)零接線、不需要它。逐格實測見 docs/AGENT_COMPAT.md |
ops/gain/**、runs/** |
R529/R530/R532/R534 的 runner、題庫、隱藏驗收、judge、排程器與落盤資料。要重算實驗數字必須 clone(見下面〈從原始碼跑〉) |
examples/**、decisions/**、docs/** |
展件、裁決檔、規格文件 |
⚠ 不把頂層 ops 打進 wheel 是刻意的:PyPI 上 ops 是 Juju 的套件,
同名會在別人的 site-packages 裡安靜覆蓋檔案——那是很糟的失敗方式。
你自己的驗收:兩格都要跑過
vacant demo gate 演的是拒交格。只有拒交格是不夠的——一個永遠拒交的閘門跟
沒有閘門一樣沒用,所以交付格是規格的一部分,不是完整性。下面這一段零模型、零網路、
零 API key,假 agent 就是一行 printf,兩格只差它寫出來的東西。
逐字出自 vacant-dev 的 clean-room 跑
(docs/INSTALL_LOG_20260919.md §9–§11)。
# 客戶的驗收。⚠ 一定要放在工作區外——agent 改得到的驗收不是驗收。
mkdir -p ~/vacant-try/ws ~/vacant-try/tests_visible
cat > ~/vacant-try/tests_visible/test_visible.py <<'PY'
def check_add():
from solution import add
assert add(2, 3) == 5
def check_mul():
from solution import mul
assert mul(2, 3) == 6
PY
驗收檔的形狀(vacant_network/vrun/acceptance.py 的執行語意,不依賴 pytest):一個 .py
裡放一組零引數的 check_*(),每個函式一條 case、依定義順序跑,正常回傳=過、
丟任何例外=不過;或者只放一個 main(),整個檔案算一條。兩種寫法一個檔案裡只准有一種。
拒交格——假 agent 只寫了 add(),卻宣告完成:
$ vacant run --workspace ~/vacant-try/ws --suite ~/vacant-try/tests_visible \
--run-dir ~/vacant-try/receipts_refuse -- \
sh -c 'printf "def add(a, b):\n return a + b\n" > solution.py; echo "Done. solution.py is complete."'
Done. solution.py is complete.
[vacant run] RUN-ON 拒交(visible_fail) 1/1 次 ws 4f53cda18c2b→c18ac5771908 wire 0 通 收據 /home/user1/vacant-try/receipts_refuse
test_visible.py::check_mul — exception: ImportError: cannot import name 'mul' from 'solution' (/home/user1/vacant-try/receipts_refuse/_frozen_RUN-ON/solution.py) [test_visible.py:6: from solution import mul]
exit=20
交付格——同一份驗收、同一條指令,只有假 agent 寫出來的東西不一樣
(先 rm -rf ~/vacant-try/ws && mkdir -p ~/vacant-try/ws 換一個乾淨的工作區):
$ vacant run --workspace ~/vacant-try/ws --suite ~/vacant-try/tests_visible \
--run-dir ~/vacant-try/receipts_deliver -- \
sh -c 'printf "def add(a, b):\n return a + b\n\ndef mul(a, b):\n return a * b\n" > solution.py; echo "Done. solution.py is complete."'
Done. solution.py is complete.
[vacant run] RUN-ON 交付(visible_pass) 1/1 次 ws 4f53cda18c2b→bf906ec43e3b wire 0 通 收據 /home/user1/vacant-try/receipts_deliver
exit=0
兩格的 run_RUN-ON.json(逐字讀出來的,不是轉述):
accepted |
stop_reason |
agent_rc |
可見驗收 | vacant run 退出碼 |
|
|---|---|---|---|---|---|
| 拒交格 | false |
visible_fail |
0 | 1/2 | 20 |
| 交付格 | true |
visible_pass |
0 | 2/2 | 0 |
兩格的 agent_rc 都是 0:agent 兩次都說自己成功了。裁決的差別完全來自客戶
的驗收,不來自 agent 的說法。退出碼還有第三個:22=infra_void(基礎設施壞了,
既不判交付也不判拒交)。
驗這兩張收據(負控制先過):
$ python3 -m vacant_network.vrun.verify_receipts --selftest
selftest: PASS
$ python3 -m vacant_network.vrun.verify_receipts --glob ~/vacant-try/receipts_deliver
═══ 收據鏈驗證 /home/user1/vacant-try/receipts_deliver ═══
run 1 鏈 1 entries 2 驗過 2 失敗 0 壞鏈 0
run arm 條數 驗過 失敗 verdict rows chain_head
receipts_deliver RUN-ON 2 2 0 1 1 9a3abd1bd71c31cd… OK
總判:OK
--selftest 必須先跑:它證明這把尺抓得到壞鏈。沒過負控制的驗章器,
拿去驗真鏈只會得到一個沒有內容的 OK。
⚠ 上面那條 OK 的旁邊還有一個數字:這一跑的 requests_seen 是 0
(假 agent 不呼叫模型)。鏈驗得過,不代表該發生的事發生過——見〈誠實邊界〉第 21 條。
接上你自己的 agent
-- 後面照你平常怎麼跑 agent 就怎麼打,vacant run 不需要知道那是什麼框架:
vacant run --suite ../tests_visible -- <你平常怎麼跑 agent 就怎麼打>
⚠ 驗收目錄不可以在工作區底下(--suite 與 --run-dir 都會擋,SystemExit):agent 改得到的驗收不是驗收。要給 agent 看就另外複製一份進去。
觸發點在 agent 行程結束的那一刻(不是在 wire 上認「它宣告完成了」):那個訊號
100% 可靠、零協定知識、零 token 成本。退出碼 0=交付、20=拒交、22=infra_void。
完整用法與落盤形狀見 docs/VACANT_RUN.md。
「一個開關」的正確講法。 vacant run 把模型通道轉向到自己的 proxy,靠的是一份
環境變數名單(vacant_network/vrun/envmap.py:
OpenAI 家族/Anthropic 家族/OpenRouter/Groq/Together/DeepSeek/Ollama/LM Studio…)
——涵蓋大多數框架,用設定檔的框架要改設定檔。實測:pi
(@earendil-works/pi-coding-agent)的 provider baseUrl 寫在 models.json 裡,
內建 provider 的 baseUrl 甚至編進 bundle,環境變數在那條路上完全沒有作用。
那種框架用 --port 給一個固定埠,再把它的設定檔指過來。
⚠ 「我設了環境變數」不是被中介的證據,requests_seen 才是。 自檢:
vacant run --allow-no-suite --run-dir /tmp/vr -- <你的 agent 命令>
python3 -c "import json;print(json.load(open('/tmp/vr/run_RUN-ON.json'))['requests_seen'])"
# 非 0 ⇒ 模型通道真的經過 Vacant;0 ⇒ 沒被中介到(框架用設定檔,或那一跑根本沒呼叫模型)。
名單漏一個變數=那條路沒被中介,而且不會有任何錯誤訊息——這是 V0 已知的殘餘風險。
五個 agent 的接線(五個都有真模型證據,等級不可混講)
判準的單一真相是
docs/AGENT_COMPAT.md
——下表是它 §1 矩陣的摘要,沒有另寫一套判準,可複製貼上的完整接線在它的 §2。
證據等級:L-real=真模型真跑、拒交格與交付格都過、收據可重驗;
L-fake=假上游(mockup.py)只驗通道與閘門;L-none=沒量。
⚠ L-fake 不能寫成「這個 agent 可以用 Vacant」:假上游碰不到 SSE 分塊、
工具呼叫格式、逾時、上下文長度。
2026-09-19 的現況:五個 agent,五個都接通了、五個都有真模型證據。 矩陣裡不再有「完全沒量過」的 agent;仍然空著的兩格是同一個 agent 的另外兩條路, 不是另外兩個 agent。
| agent | 怎麼接 | 等級 | 拒交/交付 |
|---|---|---|---|
| Claude Code 2.1.278 | 環境變數 ANTHROPIC_BASE_URL ⇒ 零接線(已在 envmap 名單裡,launcher 自己注入) |
L-real(§9) | ✅ exit 20 / ✅ exit 0 |
| OpenCode 1.18.31 | 走內建 openai provider = 環境變數 OPENAI_BASE_URL ⇒ 零接線;指到本地模型必須改走設定(OPENCODE_CONFIG_CONTENT) |
L-real(§8;真模型那兩格走的是設定那條) | ✅ exit 20 / ✅ exit 0 |
| pi 0.85.1 | 設定檔:PI_CODING_AGENT_DIR 指到暫存目錄+寫一份 models.json。不吃 OPENAI_BASE_URL |
L-real(R535) | ✅ exit 20 / ✅ exit 0 |
Codex CLI(API key/自訂 provider)0.147.0=真模型那輪(vacant-dev)/0.153.2=假上游那輪(別台機器) |
設定:model_providers.<新 id>.base_url(-c 旗標或 config.toml;repo 出廠的 wrap_agent.sh codex 就夠,不必自己再寫)。不吃 OPENAI_BASE_URL |
L-real(§10) | ✅ exit 20 / ✅ exit 0 |
Hermes Agent 0.19.0(Nous Research,PyPI hermes-agent) |
一個 CLI 旗標 --provider custom;CUSTOM_BASE_URL(launcher 已內建)蓋得過 base_url,但蓋不掉 provider。兩句話都要講,見下面 |
L-real(§12)⚠ 從 L-none 直接跳到 L-real,中間沒有經過 L-fake | ✅ exit 20 / ✅ exit 0 |
Codex(codex login/ChatGPT 帳號) |
❌ 沒有辦法:模型通道是寫死的 wss://chatgpt.com/backend-api/codex/responses,HTTP 反向代理在那條路上不存在 |
L-none | 閘門照跑(觸發點在行程結束不在 wire 上),但逐字落盤在那條路上不成立 |
Codex × wire_api="chat" |
❌ 0.147.0 在載設定那一步就退掉,一通都沒送出 ⇒ requests_seen = 0 |
L-none(§11.1) | — |
⚠ Codex 的版本號兩個都對,不是筆誤:0.153.2 是 2026-09-18 假上游那一輪
(別台機器),0.147.0 是 2026-09-19 真模型那一輪(vacant-dev)。
引用時要連機器一起講。
⚠ Hermes 的 requests_seen = 6 裡有 2 通不是模型:它在第一通模型請求之前會探
GET /api/v1/models。模型通道是 4 通。
⇒ 接線的成本分成三級:吃環境變數的兩個(Claude Code、雲端模型的 OpenCode)零接線; Hermes 是一個 CLI 旗標;吃設定檔的兩個(pi、Codex)要寫一份設定——後面兩級是品質 比較差的附身。三個「輕」的都有前提,不寫出來就是誇大:
- ⚠ Claude Code 的零接線建在「上游自己會講 Anthropic Messages(
POST /v1/messages)」 這一個功能上。vacant_network/vrun/wireproxy.py是反向代理不是協定轉換器——它照 path 路由,不把/v1/messages改寫成/v1/chat/completions。實測那台 LM Studio 原生就吃/v1/messages(含 SSE 與tool_use)所以不需要 shim;換一個只講 OpenAI 的上游 (純 llama.cpp server、vLLM 預設)就必須自備轉換層,而那一層不是本 repo 的東西。 - ⚠ OpenCode 的零接線只對雲端模型成立。 內建
openaiprovider 拿到 models.dev 註冊表以外的模型 id(例如本地 LM Studio 的gemma-4-12b-it-qat)會在送出任何請求 之前就死在模型解析 ⇒requests_seen = 0——那是infra_void不是 0 分。 指到本地模型必須走設定路線。 - ⚠ Hermes 兩句話都要講,只講一句就會誤導(
AGENT_COMPAT.md§12.2 的結論):- 對全新環境:不是零接線。 只給
CUSTOM_BASE_URL、沒有選 provider ⇒ 死在No inference provider configured,requests_seen = 0。最小接線是一個 CLI 旗標--provider custom——比 pi/Codex/OpenCode 的「寫一份設定檔」都輕, 但不是零。 - 對已經設好自訂 provider 的使用者:是零接線。
CUSTOM_BASE_URL的優先序 高過他自己config.yaml裡的model.base_url(實測 D 格),vacant run包上去就轉向了,不必動他的~/.hermes/config.yaml。
- 對全新環境:不是零接線。 只給
那五段接線已經寫成一支 ops/vacantrun/wrap_agent.sh(pi | codex | opencode | claude | hermes 各一段,每段在 runtime 讀 $VACANT_RUN_PROXY,所以不必固定埠也
不必動使用者的設定檔)。
⚠ 它只在 repo checkout 裡,pip 裝的版本沒有它——見上面〈還需要 clone 的部分〉。
⚠ -- 之後要給絕對路徑:launcher 用 cwd=<workspace> spawn 子行程,相對路徑會
解析到工作區底下 ⇒ agent_spawn_failed/exit 22。
這三條要跟上面那一幕一起讀(不准淡化)
- proxy 單獨只有 L3。 它證明「這些 bytes 經過我」,不阻止 agent 自己開一條連線。
要「agent 逃不掉」必須再加出網封鎖
(
ops/vacantrun/block_egress.sh, 要 root 一次;那支只在 repo checkout 裡,見上面〈還需要 clone 的部分〉)。vacant_network/controller.py:7-8那句逐字適用:無法阻止同一 OS 使用者繞過本命令。 - 中介的是「模型通道」,不是 agent 的行為。 框架自己發起的動作——自動 lint、 git checkpoint、內建重試、本機工具呼叫——不經過模型通道,proxy 看不到也擋不到。 收據能說「模型通道上發生了什麼」與「工作區最後長這樣」,不能說「agent 做了什麼」。
- 驗收是單邊保證。
vacant_network/suitegauge.py:30-33逐字:擋得住已知壞解不證明涵蓋真需求。accepted=true只代表「客戶寫下來的那幾條過了」。 實測:R532 那 836 題裡閘門接受了 811 件,其中 120 件(14.8%)過了可見驗收卻沒過隱藏驗收。
其餘邊界(TOCTOU、Responses API + store:true 的落盤缺口、不走 HTTP 的模型、
Bedrock SigV4、為什麼不做透明 MITM)在
docs/VACANT_RUN.md §4,一條都沒有被省略。
函式庫 quickstart(不用 clone)
零模型呼叫、零網路。
from vacant_network.checks import run_python_check
from vacant_network.identity import Identity, PublicIdentity
from vacant_network.logbook import Logbook
# 1) 驗收:客戶的測試在 runner 行程,候選碼在另一個 worker 行程
tests = "assert solve([1, 2, 3, 4]) == 6\nassert solve([]) == 0\n"
good = "def solve(nums):\n return sum(n for n in nums if n % 2 == 0)\n"
cheat = "def solve(nums):\n import os; os._exit(0)\n" # 想偽裝成「測試全過」
print(run_python_check(good, tests, allowed_entry_points=("solve",))) # True
print(run_python_check(cheat, tests, allowed_entry_points=("solve",))) # False
# 2) 收據:每一次嘗試簽進 append-only 雜湊鏈
me, book = Identity.generate(), Logbook()
who = PublicIdentity(vacant_id=me.vacant_id, pub=me.pub)
book.append("attempt", {"draft": "sha256:aaa", "visible_ok": False}, me, ts_ms=1_700_000_000_000)
book.append("attempt", {"draft": "sha256:bbb", "visible_ok": True}, me, ts_ms=1_700_000_000_001)
book.append("shipped", {"accepted": True, "draft": "sha256:bbb"}, me, ts_ms=1_700_000_000_002)
print(book.verify_chain(who)) # True
# 3) 竄改中間那一筆 ⇒ 驗章失敗
import copy
from vacant_network.logbook import LogEntry
forged = Logbook([copy.deepcopy(e) for e in book.entries])
e = forged.entries[1]
forged.entries[1] = LogEntry(e.stream_id, e.branch_id, e.seq, e.prev_hash, e.ts_ms, e.type,
{"draft": "sha256:aaa", "visible_ok": True}, e.sig) # False -> True
print(forged.verify_chain(who)) # False
Vacant MCP questions
Can Vacant be used with existing AI agents?
Yes, it can be integrated with agents like pi, Claude Code, OpenCode, and Codex by adding hooks to their configuration.