計(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 插件倉(cāng)庫(kù)其中的shunt插件能把大文件讀取、樣板代碼生成等重 I/O 工作委派給更便宜的 AiKA worker 模型批量讀取場(chǎng)景可省 82%~94% 的 token。本篇帶你讀完它的傳輸層核心 aika.sh僅 166 行重點(diǎn)講透三個(gè)設(shè)計(jì)一次一投one-shot的無(wú)狀態(tài)調(diào)用、ARG_MAX 載荷上限以及層層設(shè)防的錯(cuò)誤處理。shunt 是什么三層架構(gòu)一句話理清 shunt 采用從硬攔截到軟建議的三層結(jié)構(gòu)詳見(jiàn) plugins/shunt/README.md層職責(zé)代表文件Hooks硬門(mén)禁攔截對(duì)大文件的直接讀取強(qiáng)制走委派check-file-size、check-bash-readScripts傳輸層組裝請(qǐng)求、調(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è)腳本通過(guò)一行 source 復(fù)用. $(cd $(dirname $0) pwd)/lib/aika.sh一次一投為什么每次調(diào)用都無(wú)狀態(tài)文件頭部注釋把設(shè)計(jì)動(dòng)機(jī)寫(xiě)得非常直白aika.sh#L13-L16invoke-chat is ephemeral — nothing is kept server-sideinvoke-chat 是瞬時(shí)的——服務(wù)端什么都不保留。關(guān)鍵推理鏈?zhǔn)沁@樣的服務(wù)端不存任何對(duì)話狀態(tài)想跨調(diào)用帶上下文唯一辦法是調(diào)用方把舊內(nèi)容原樣重放對(duì)文件語(yǔ)料來(lái)說(shuō)重放整個(gè)文件恰恰是這個(gè)插件要避免的成本——如果每次追問(wèn)都要把大文件重新灌進(jìn) Claude 上下文省 token 就無(wú)從談起所以 shunt 干脆每次調(diào)用都獨(dú)立成立one shot per call追問(wèn)就把文件再發(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 # 追問(wèn)重發(fā)妙處在于重發(fā)文件是免費(fèi)的——文件只進(jìn) worker 模型的上下文永遠(yuǎn)不會(huì)進(jìn)入 Claude 的上下文。這個(gè)看似浪費(fèi)、實(shí)則最優(yōu)的取舍是 shunt 能省 90% token 的根基。ARG_MAX 載荷上限Linux 120KB 與 macOS 400KB 的由來(lái) ??aika:invoke-chat的輸入走命令行 argv 傳遞--input $payload。這意味著整份請(qǐng)求必須和進(jìn)程環(huán)境變量一起塞進(jìn)操作系統(tǒng)的ARG_MAX并且Linux單個(gè)參數(shù)還有MAX_ARG_STRLEN 128 KiB 的額外硬上限macOS無(wú)單參數(shù)上限但ARG_MAX總共 1 MiB還要和環(huán)境變量分。于是 aika.sh#L22-L27 按平臺(tái)設(shè)置了默認(rèn)載荷上限平臺(tái)SHUNT_MAX_PAYLOAD_BYTES默認(rèn)值原因Linux120000約 117 KB給 128 KiB 的單參數(shù)上限留安全余量其他macOS 等400000ARG_MAX 為 1 MiB扣除環(huán)境變量后仍有余量發(fā)送前shunt_invoke 會(huì)先量出 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í)也可通過(guò)環(huán)境變量SHUNT_MAX_PAYLOAD_BYTES主動(dòng)調(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)境問(wèn)題誤報(bào)為 Portal 錯(cuò)誤。第二道載荷體積檢查即上文所述的ARG_MAX預(yù)檢超限立刻返回并解釋原因。第三道stderr 隔離保護(hù) JSON 信封這是最容易被忽略的細(xì)節(jié)aika.sh#L118-L125成功調(diào)用時(shí)npx的安裝通知或 CLI 警告會(huì)打到 stderr——如果不隔離這些雜音就會(huì)污染 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)出來(lái)而不是傾倒原始 JSON。若錯(cuò)誤信息含timed out字樣aika.sh#L131-L135還會(huì)追加一條針對(duì)性提示調(diào)高SHUNT_TIMEOUT_SECONDS或把任務(wù)拆小。第五道m(xù)ode 守衛(wèi)拒絕靜默降級(jí) ??這是最有味道的一道。AiKA 的 mode 支持按名稱解析不區(qū)分大小寫(xiě)優(yōu)先你自己的 → 所在組 → 公開(kāi)也可用SHUNT_NAME_MODE_ID按 id 精確鎖定aika.sh#L100-L107。危險(xiǎn)在于名稱解析不到會(huì)直接失敗但一個(gè)過(guò)期的 mode_id 服務(wù)端只記警告——那一輪會(huì)無(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ò)誤信息會(huì)點(diǎn)名這個(gè)過(guò)期的變量提示 unset 后改按名稱解析。一句話寧可報(bào)錯(cuò)不要看起來(lái)對(duì)的錯(cuò)誤答案。此外 rc0 但 stdout 不是合法 JSON會(huì)被明確判定為傳輸問(wèn)題而非 mode 問(wèn)題aika.sh#L139-L144回答中.text為空同樣按錯(cuò)誤處理。如何驗(yàn)證傳輸層一個(gè)不連 Portal 的測(cè)試套件 transport-evals.sh 用打樁的 portal-clistub對(duì)aika.sh跑了 17 項(xiàng)斷言無(wú)需 Portal 實(shí)例、無(wú)需認(rèn)證、零 token 消耗。覆蓋點(diǎn)與設(shè)計(jì)嚴(yán)格一一對(duì)應(yīng)載荷原樣往返message逐字節(jié)一致、mode_name與mode_id互斥不發(fā)送 history——every delegation is one shot 由測(cè)試直接鎖死transport-evals.sh#L67-L68無(wú) mode 的回答必須失敗、過(guò)期鎖定要指向具體變量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 的啟動(dòng)方式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)簽包裹后流式寫(xiě)入臨時(shí)文件和 code-write剝除 markdown 圍欄后可直寫(xiě)磁盤(pán)以及端到端用例 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 插件倉(cāng)庫(kù)其中的shunt插件能把大文件讀取、樣板代碼生成等重 I/O 工作委派給更便宜的 AiKA worker 模型批量讀取場(chǎng)景可省 82%~94% 的 token。本篇帶你讀完它的傳輸層核心 aika.sh僅 166 行重點(diǎn)講透三個(gè)設(shè)計(jì)一次一投one-shot的無(wú)狀態(tài)調(diào)用、ARG_MAX 載荷上限以及層層設(shè)防的錯(cuò)誤處理。shunt 是什么三層架構(gòu)一句話理清 shunt 采用從硬攔截到軟建議的三層結(jié)構(gòu)詳見(jiàn) plugins/shunt/README.md層職責(zé)代表文件Hooks硬門(mén)禁攔截對(duì)大文件的直接讀取強(qiáng)制走委派check-file-size、check-bash-readScripts傳輸層組裝請(qǐng)求、調(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è)腳本通過(guò)一行 source 復(fù)用. $(cd $(dirname $0) pwd)/lib/aika.sh一次一投為什么每次調(diào)用都無(wú)狀態(tài)文件頭部注釋把設(shè)計(jì)動(dòng)機(jī)寫(xiě)得非常直白aika.sh#L13-L16invoke-chat is ephemeral — nothing is kept server-sideinvoke-chat 是瞬時(shí)的——服務(wù)端什么都不保留。關(guān)鍵推理鏈?zhǔn)沁@樣的服務(wù)端不存任何對(duì)話狀態(tài)想跨調(diào)用帶上下文唯一辦法是調(diào)用方把舊內(nèi)容原樣重放對(duì)文件語(yǔ)料來(lái)說(shuō)重放整個(gè)文件恰恰是這個(gè)插件要避免的成本——如果每次追問(wèn)都要把大文件重新灌進(jìn) Claude 上下文省 token 就無(wú)從談起所以 shunt 干脆每次調(diào)用都獨(dú)立成立one shot per call追問(wèn)就把文件再發(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 # 追問(wèn)重發(fā)妙處在于重發(fā)文件是免費(fèi)的——文件只進(jìn) worker 模型的上下文永遠(yuǎn)不會(huì)進(jìn)入 Claude 的上下文。這個(gè)看似浪費(fèi)、實(shí)則最優(yōu)的取舍是 shunt 能省 90% token 的根基。ARG_MAX 載荷上限Linux 120KB 與 macOS 400KB 的由來(lái) ??aika:invoke-chat的輸入走命令行 argv 傳遞--input $payload。這意味著整份請(qǐng)求必須和進(jìn)程環(huán)境變量一起塞進(jìn)操作系統(tǒng)的ARG_MAX并且Linux單個(gè)參數(shù)還有MAX_ARG_STRLEN 128 KiB 的額外硬上限macOS無(wú)單參數(shù)上限但ARG_MAX總共 1 MiB還要和環(huán)境變量分。于是 aika.sh#L22-L27 按平臺(tái)設(shè)置了默認(rèn)載荷上限平臺(tái)SHUNT_MAX_PAYLOAD_BYTES默認(rèn)值原因Linux120000約 117 KB給 128 KiB 的單參數(shù)上限留安全余量其他macOS 等400000ARG_MAX 為 1 MiB扣除環(huán)境變量后仍有余量發(fā)送前shunt_invoke 會(huì)先量出 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í)也可通過(guò)環(huán)境變量SHUNT_MAX_PAYLOAD_BYTES主動(dòng)調(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)境問(wèn)題誤報(bào)為 Portal 錯(cuò)誤。第二道載荷體積檢查即上文所述的ARG_MAX預(yù)檢超限立刻返回并解釋原因。第三道stderr 隔離保護(hù) JSON 信封這是最容易被忽略的細(xì)節(jié)aika.sh#L118-L125成功調(diào)用時(shí)npx的安裝通知或 CLI 警告會(huì)打到 stderr——如果不隔離這些雜音就會(huì)污染 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)出來(lái)而不是傾倒原始 JSON。若錯(cuò)誤信息含timed out字樣aika.sh#L131-L135還會(huì)追加一條針對(duì)性提示調(diào)高SHUNT_TIMEOUT_SECONDS或把任務(wù)拆小。第五道m(xù)ode 守衛(wèi)拒絕靜默降級(jí) ??這是最有味道的一道。AiKA 的 mode 支持按名稱解析不區(qū)分大小寫(xiě)優(yōu)先你自己的 → 所在組 → 公開(kāi)也可用SHUNT_NAME_MODE_ID按 id 精確鎖定aika.sh#L100-L107。危險(xiǎn)在于名稱解析不到會(huì)直接失敗但一個(gè)過(guò)期的 mode_id 服務(wù)端只記警告——那一輪會(huì)無(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ò)誤信息會(huì)點(diǎn)名這個(gè)過(guò)期的變量提示 unset 后改按名稱解析。一句話寧可報(bào)錯(cuò)不要看起來(lái)對(duì)的錯(cuò)誤答案。此外 rc0 但 stdout 不是合法 JSON會(huì)被明確判定為傳輸問(wèn)題而非 mode 問(wèn)題aika.sh#L139-L144回答中.text為空同樣按錯(cuò)誤處理。如何驗(yàn)證傳輸層一個(gè)不連 Portal 的測(cè)試套件 transport-evals.sh 用打樁的 portal-clistub對(duì)aika.sh跑了 17 項(xiàng)斷言無(wú)需 Portal 實(shí)例、無(wú)需認(rèn)證、零 token 消耗。覆蓋點(diǎn)與設(shè)計(jì)嚴(yán)格一一對(duì)應(yīng)載荷原樣往返message逐字節(jié)一致、mode_name與mode_id互斥不發(fā)送 history——every delegation is one shot 由測(cè)試直接鎖死transport-evals.sh#L67-L68無(wú) mode 的回答必須失敗、過(guò)期鎖定要指向具體變量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 的啟動(dòng)方式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)簽包裹后流式寫(xiě)入臨時(shí)文件和 code-write剝除 markdown 圍欄后可直寫(xiě)磁盤(pán)以及端到端用例 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），僅供參考