)
portal-ai-plugins傳輸層源碼解讀aika.sh的一次一投設計、ARG_MAX載荷上限與錯誤處理細節(jié)【免費下載鏈接】portal-ai-plugins項目地址: https://gitcode.com/gh_mirrors/po/portal-ai-pluginsportal-ai-plugins是 Spotify Portal 的官方 AI 插件倉庫其中的shunt插件能把大文件讀取、樣板代碼生成等重 I/O 工作委派給更便宜的 AiKA worker 模型批量讀取場景可省 82%~94% 的 token。本篇帶你讀完它的傳輸層核心 aika.sh僅 166 行重點講透三個設計一次一投one-shot的無狀態(tài)調用、ARG_MAX 載荷上限以及層層設防的錯誤處理。shunt 是什么三層架構一句話理清 shunt 采用從硬攔截到軟建議的三層結構詳見 plugins/shunt/README.md層職責代表文件Hooks硬門禁攔截對大文件的直接讀取強制走委派check-file-size、check-bash-readScripts傳輸層組裝請求、調用 AiKA、清洗輸出bulk-read、code-writeSkills軟建議告訴 Claude 何時、如何調用腳本bulk-reader/SKILL.md、code-writer/SKILL.md所有委派最終都收斂到 Portal CLI 的同一個 actionaika:invoke-chat。共享管線就封裝在 aika.sh 中兩個腳本通過一行 source 復用. $(cd $(dirname $0) pwd)/lib/aika.sh一次一投為什么每次調用都無狀態(tài)文件頭部注釋把設計動機寫得非常直白aika.sh#L13-L16invoke-chat is ephemeral — nothing is kept server-sideinvoke-chat 是瞬時的——服務端什么都不保留。關鍵推理鏈是這樣的服務端不存任何對話狀態(tài)想跨調用帶上下文唯一辦法是調用方把舊內容原樣重放對文件語料來說重放整個文件恰恰是這個插件要避免的成本——如果每次追問都要把大文件重新灌進 Claude 上下文省 token 就無從談起所以 shunt 干脆每次調用都獨立成立one shot per call追問就把文件再發(fā)一遍bulk-read --question What does this service do? --paths src/Service.java bulk-read --question Which methods call the DB? --paths src/Service.java # 追問重發(fā)妙處在于重發(fā)文件是免費的——文件只進 worker 模型的上下文永遠不會進入 Claude 的上下文。這個看似浪費、實則最優(yōu)的取舍是 shunt 能省 90% token 的根基。ARG_MAX 載荷上限Linux 120KB 與 macOS 400KB 的由來 ??aika:invoke-chat的輸入走命令行 argv 傳遞--input $payload。這意味著整份請求必須和進程環(huán)境變量一起塞進操作系統(tǒng)的ARG_MAX并且Linux單個參數(shù)還有MAX_ARG_STRLEN 128 KiB 的額外硬上限macOS無單參數(shù)上限但ARG_MAX總共 1 MiB還要和環(huán)境變量分。于是 aika.sh#L22-L27 按平臺設置了默認載荷上限平臺SHUNT_MAX_PAYLOAD_BYTES默認值原因Linux120000約 117 KB給 128 KiB 的單參數(shù)上限留安全余量其他macOS 等400000ARG_MAX 為 1 MiB扣除環(huán)境變量后仍有余量發(fā)送前shunt_invoke 會先量出 JSON 載荷的字節(jié)數(shù)超限就提前失敗并給出可讀的錯誤而不是等到操作系統(tǒng)拋出晦澀的E2BIGError: request is 130512 bytes, over the 120000 byte limit. Send fewer or smaller files, or raise SHUNT_MAX_PAYLOAD_BYTES if there is headroom.實操建議文件太大時拆成小批次確認本機有余量時也可通過環(huán)境變量SHUNT_MAX_PAYLOAD_BYTES主動調高上限。錯誤處理細節(jié)五道防線層層攔截 ?傳輸層的健壯性集中體現(xiàn)在 shunt_invoke 的調用鏈上按執(zhí)行順序看有五道防線第一道預檢依賴shunt_preflight調用前先檢查jq和portal-cli是否存在aika.sh#L56-L70缺什么報什么并直接給出安裝命令避免把環(huán)境問題誤報為 Portal 錯誤。第二道載荷體積檢查即上文所述的ARG_MAX預檢超限立刻返回并解釋原因。第三道stderr 隔離保護 JSON 信封這是最容易被忽略的細節(jié)aika.sh#L118-L125成功調用時npx的安裝通知或 CLI 警告會打到 stderr——如果不隔離這些雜音就會污染 stdout 的 JSON 信封導致解析失敗。shunt 把 stderr 單獨重定向到臨時文件捕獲 stdout 后再合并處理response$(shunt_portal actions aika:invoke-chat --json \ --timeout-seconds $SHUNT_TIMEOUT_SECONDS \ --input $payload 2$stderr_file)第四道錯誤解包 超時線索調用失敗時shunt_report_error 用 jq 抽出 portal-cli 響應里的.error和.remediation兩個字段把錯誤 修復建議干凈地呈現(xiàn)出來而不是傾倒原始 JSON。若錯誤信息含timed out字樣aika.sh#L131-L135還會追加一條針對性提示調高SHUNT_TIMEOUT_SECONDS或把任務拆小。第五道m(xù)ode 守衛(wèi)拒絕靜默降級 ??這是最有味道的一道。AiKA 的 mode 支持按名稱解析不區(qū)分大小寫優(yōu)先你自己的 → 所在組 → 公開也可用SHUNT_NAME_MODE_ID按 id 精確鎖定aika.sh#L100-L107。危險在于名稱解析不到會直接失敗但一個過期的 mode_id 服務端只記警告——那一輪會無 mode運行在錯誤指令下產(chǎn)出一份看似正常的通用回答。shunt 的做法是檢查響應里的.mode.nameaika.sh#L146-L157若實際運行的 mode 為 none →視為失敗并丟棄回答若當時用的是SHUNT_..._MODE_ID鎖定錯誤信息會點名這個過期的變量提示 unset 后改按名稱解析。一句話寧可報錯不要看起來對的錯誤答案。此外 rc0 但 stdout 不是合法 JSON會被明確判定為傳輸問題而非 mode 問題aika.sh#L139-L144回答中.text為空同樣按錯誤處理。如何驗證傳輸層一個不連 Portal 的測試套件 transport-evals.sh 用打樁的 portal-clistub對aika.sh跑了 17 項斷言無需 Portal 實例、無需認證、零 token 消耗。覆蓋點與設計嚴格一一對應載荷原樣往返message逐字節(jié)一致、mode_name與mode_id互斥不發(fā)送 history——every delegation is one shot 由測試直接鎖死transport-evals.sh#L67-L68無 mode 的回答必須失敗、過期鎖定要指向具體變量stderr 噪聲不得污染響應、超載荷必須被拒絕且錯誤里帶出上限值。本地運行入口run.sh共 51 個 hook transport 用例bash evals/run.sh配置速查傳輸層相關環(huán)境變量一覽變量默認值作用SHUNT_MAX_PAYLOAD_BYTESLinux 120000 / 其他 400000argv 載荷上限超了就拒絕發(fā)送SHUNT_TIMEOUT_SECONDS180單次 action 調用的超時秒PORTAL_CLI_BINportal-cli否則npx覆蓋 portal-cli 的啟動方式SHUNT_PORTAL_INSTANCECLI 默認指定調用的 Portal 實例SHUNT_BULK_READER_MODE_ID/SHUNT_CODE_WRITER_MODE_ID—名稱歧義時按 id 鎖定具體 mode小結aika.sh 用 166 行展示了工程化委派的完整思路用一次一投換取上下文零污染用 ARG_MAX 預檢換取清晰報錯用五道防線換取絕不靜默出錯。想繼續(xù)深入可以順藤摸瓜看兩個調用方 bulk-read文件以file path...XML 標簽包裹后流式寫入臨時文件和 code-write剝除 markdown 圍欄后可直寫磁盤以及端到端用例 evals.json 與 token 節(jié)省基準 benchmarks.json?！久赓M下載鏈接】portal-ai-plugins項目地址: https://gitcode.com/gh_mirrors/po/portal-ai-plugins創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 portal-ai-plugins傳輸層源碼解讀：aika.sh的一次一投設計、ARG_MAX載荷上限與錯誤處理細節(jié)
portal-ai-plugins傳輸層源碼解讀aika.sh的一次一投設計、ARG_MAX載荷上限與錯誤處理細節(jié)【免費下載鏈接】portal-ai-plugins項目地址: https://gitcode.com/gh_mirrors/po/portal-ai-pluginsportal-ai-plugins是 Spotify Portal 的官方 AI 插件倉庫其中的shunt插件能把大文件讀取、樣板代碼生成等重 I/O 工作委派給更便宜的 AiKA worker 模型批量讀取場景可省 82%~94% 的 token。本篇帶你讀完它的傳輸層核心 aika.sh僅 166 行重點講透三個設計一次一投one-shot的無狀態(tài)調用、ARG_MAX 載荷上限以及層層設防的錯誤處理。shunt 是什么三層架構一句話理清 shunt 采用從硬攔截到軟建議的三層結構詳見 plugins/shunt/README.md層職責代表文件Hooks硬門禁攔截對大文件的直接讀取強制走委派check-file-size、check-bash-readScripts傳輸層組裝請求、調用 AiKA、清洗輸出bulk-read、code-writeSkills軟建議告訴 Claude 何時、如何調用腳本bulk-reader/SKILL.md、code-writer/SKILL.md所有委派最終都收斂到 Portal CLI 的同一個 actionaika:invoke-chat。共享管線就封裝在 aika.sh 中兩個腳本通過一行 source 復用. $(cd $(dirname $0) pwd)/lib/aika.sh一次一投為什么每次調用都無狀態(tài)文件頭部注釋把設計動機寫得非常直白aika.sh#L13-L16invoke-chat is ephemeral — nothing is kept server-sideinvoke-chat 是瞬時的——服務端什么都不保留。關鍵推理鏈是這樣的服務端不存任何對話狀態(tài)想跨調用帶上下文唯一辦法是調用方把舊內容原樣重放對文件語料來說重放整個文件恰恰是這個插件要避免的成本——如果每次追問都要把大文件重新灌進 Claude 上下文省 token 就無從談起所以 shunt 干脆每次調用都獨立成立one shot per call追問就把文件再發(fā)一遍bulk-read --question What does this service do? --paths src/Service.java bulk-read --question Which methods call the DB? --paths src/Service.java # 追問重發(fā)妙處在于重發(fā)文件是免費的——文件只進 worker 模型的上下文永遠不會進入 Claude 的上下文。這個看似浪費、實則最優(yōu)的取舍是 shunt 能省 90% token 的根基。ARG_MAX 載荷上限Linux 120KB 與 macOS 400KB 的由來 ??aika:invoke-chat的輸入走命令行 argv 傳遞--input $payload。這意味著整份請求必須和進程環(huán)境變量一起塞進操作系統(tǒng)的ARG_MAX并且Linux單個參數(shù)還有MAX_ARG_STRLEN 128 KiB 的額外硬上限macOS無單參數(shù)上限但ARG_MAX總共 1 MiB還要和環(huán)境變量分。于是 aika.sh#L22-L27 按平臺設置了默認載荷上限平臺SHUNT_MAX_PAYLOAD_BYTES默認值原因Linux120000約 117 KB給 128 KiB 的單參數(shù)上限留安全余量其他macOS 等400000ARG_MAX 為 1 MiB扣除環(huán)境變量后仍有余量發(fā)送前shunt_invoke 會先量出 JSON 載荷的字節(jié)數(shù)超限就提前失敗并給出可讀的錯誤而不是等到操作系統(tǒng)拋出晦澀的E2BIGError: request is 130512 bytes, over the 120000 byte limit. Send fewer or smaller files, or raise SHUNT_MAX_PAYLOAD_BYTES if there is headroom.實操建議文件太大時拆成小批次確認本機有余量時也可通過環(huán)境變量SHUNT_MAX_PAYLOAD_BYTES主動調高上限。錯誤處理細節(jié)五道防線層層攔截 ?傳輸層的健壯性集中體現(xiàn)在 shunt_invoke 的調用鏈上按執(zhí)行順序看有五道防線第一道預檢依賴shunt_preflight調用前先檢查jq和portal-cli是否存在aika.sh#L56-L70缺什么報什么并直接給出安裝命令避免把環(huán)境問題誤報為 Portal 錯誤。第二道載荷體積檢查即上文所述的ARG_MAX預檢超限立刻返回并解釋原因。第三道stderr 隔離保護 JSON 信封這是最容易被忽略的細節(jié)aika.sh#L118-L125成功調用時npx的安裝通知或 CLI 警告會打到 stderr——如果不隔離這些雜音就會污染 stdout 的 JSON 信封導致解析失敗。shunt 把 stderr 單獨重定向到臨時文件捕獲 stdout 后再合并處理response$(shunt_portal actions aika:invoke-chat --json \ --timeout-seconds $SHUNT_TIMEOUT_SECONDS \ --input $payload 2$stderr_file)第四道錯誤解包 超時線索調用失敗時shunt_report_error 用 jq 抽出 portal-cli 響應里的.error和.remediation兩個字段把錯誤 修復建議干凈地呈現(xiàn)出來而不是傾倒原始 JSON。若錯誤信息含timed out字樣aika.sh#L131-L135還會追加一條針對性提示調高SHUNT_TIMEOUT_SECONDS或把任務拆小。第五道m(xù)ode 守衛(wèi)拒絕靜默降級 ??這是最有味道的一道。AiKA 的 mode 支持按名稱解析不區(qū)分大小寫優(yōu)先你自己的 → 所在組 → 公開也可用SHUNT_NAME_MODE_ID按 id 精確鎖定aika.sh#L100-L107。危險在于名稱解析不到會直接失敗但一個過期的 mode_id 服務端只記警告——那一輪會無 mode運行在錯誤指令下產(chǎn)出一份看似正常的通用回答。shunt 的做法是檢查響應里的.mode.nameaika.sh#L146-L157若實際運行的 mode 為 none →視為失敗并丟棄回答若當時用的是SHUNT_..._MODE_ID鎖定錯誤信息會點名這個過期的變量提示 unset 后改按名稱解析。一句話寧可報錯不要看起來對的錯誤答案。此外 rc0 但 stdout 不是合法 JSON會被明確判定為傳輸問題而非 mode 問題aika.sh#L139-L144回答中.text為空同樣按錯誤處理。如何驗證傳輸層一個不連 Portal 的測試套件 transport-evals.sh 用打樁的 portal-clistub對aika.sh跑了 17 項斷言無需 Portal 實例、無需認證、零 token 消耗。覆蓋點與設計嚴格一一對應載荷原樣往返message逐字節(jié)一致、mode_name與mode_id互斥不發(fā)送 history——every delegation is one shot 由測試直接鎖死transport-evals.sh#L67-L68無 mode 的回答必須失敗、過期鎖定要指向具體變量stderr 噪聲不得污染響應、超載荷必須被拒絕且錯誤里帶出上限值。本地運行入口run.sh共 51 個 hook transport 用例bash evals/run.sh配置速查傳輸層相關環(huán)境變量一覽變量默認值作用SHUNT_MAX_PAYLOAD_BYTESLinux 120000 / 其他 400000argv 載荷上限超了就拒絕發(fā)送SHUNT_TIMEOUT_SECONDS180單次 action 調用的超時秒PORTAL_CLI_BINportal-cli否則npx覆蓋 portal-cli 的啟動方式SHUNT_PORTAL_INSTANCECLI 默認指定調用的 Portal 實例SHUNT_BULK_READER_MODE_ID/SHUNT_CODE_WRITER_MODE_ID—名稱歧義時按 id 鎖定具體 mode小結aika.sh 用 166 行展示了工程化委派的完整思路用一次一投換取上下文零污染用 ARG_MAX 預檢換取清晰報錯用五道防線換取絕不靜默出錯。想繼續(xù)深入可以順藤摸瓜看兩個調用方 bulk-read文件以file path...XML 標簽包裹后流式寫入臨時文件和 code-write剝除 markdown 圍欄后可直寫磁盤以及端到端用例 evals.json 與 token 節(jié)省基準 benchmarks.json?！久赓M下載鏈接】portal-ai-plugins項目地址: https://gitcode.com/gh_mirrors/po/portal-ai-plugins創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考