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