portal-ai-plugins传输层源码解读aika.sh的一次一投设计、ARG_MAX载荷上限与错误处理细节【免费下载链接】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的无状态调用、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一次一投为什么每次调用都无状态文件头部注释把设计动机写得非常直白aika.sh#L13-L16invoke-chat is ephemeral — nothing is kept server-sideinvoke-chat 是瞬时的——服务端什么都不保留。关键推理链是这样的服务端不存任何对话状态想跨调用带上下文唯一办法是调用方把旧内容原样重放对文件语料来说重放整个文件恰恰是这个插件要避免的成本——如果每次追问都要把大文件重新灌进 Claude 上下文省 token 就无从谈起所以 shunt 干脆每次调用都独立成立one shot per call追问就把文件再发一遍bulk-read --question What does this service do? --paths src/Service.java bulk-read --question Which methods call the DB? --paths src/Service.java # 追问重发妙处在于重发文件是免费的——文件只进 worker 模型的上下文永远不会进入 Claude 的上下文。这个看似浪费、实则最优的取舍是 shunt 能省 90% token 的根基。ARG_MAX 载荷上限Linux 120KB 与 macOS 400KB 的由来 ⚙️aika:invoke-chat的输入走命令行 argv 传递--input $payload。这意味着整份请求必须和进程环境变量一起塞进操作系统的ARG_MAX并且Linux单个参数还有MAX_ARG_STRLEN 128 KiB 的额外硬上限macOS无单参数上限但ARG_MAX总共 1 MiB还要和环境变量分。于是 aika.sh#L22-L27 按平台设置了默认载荷上限平台SHUNT_MAX_PAYLOAD_BYTES默认值原因Linux120000约 117 KB给 128 KiB 的单参数上限留安全余量其他macOS 等400000ARG_MAX 为 1 MiB扣除环境变量后仍有余量发送前shunt_invoke 会先量出 JSON 载荷的字节数超限就提前失败并给出可读的错误而不是等到操作系统抛出晦涩的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.实操建议文件太大时拆成小批次确认本机有余量时也可通过环境变量SHUNT_MAX_PAYLOAD_BYTES主动调高上限。错误处理细节五道防线层层拦截 ️传输层的健壮性集中体现在 shunt_invoke 的调用链上按执行顺序看有五道防线第一道预检依赖shunt_preflight调用前先检查jq和portal-cli是否存在aika.sh#L56-L70缺什么报什么并直接给出安装命令避免把环境问题误报为 Portal 错误。第二道载荷体积检查即上文所述的ARG_MAX预检超限立刻返回并解释原因。第三道stderr 隔离保护 JSON 信封这是最容易被忽略的细节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两个字段把错误 修复建议干净地呈现出来而不是倾倒原始 JSON。若错误信息含timed out字样aika.sh#L131-L135还会追加一条针对性提示调高SHUNT_TIMEOUT_SECONDS或把任务拆小。第五道mode 守卫拒绝静默降级 ⚠️这是最有味道的一道。AiKA 的 mode 支持按名称解析不区分大小写优先你自己的 → 所在组 → 公开也可用SHUNT_NAME_MODE_ID按 id 精确锁定aika.sh#L100-L107。危险在于名称解析不到会直接失败但一个过期的 mode_id 服务端只记警告——那一轮会无 mode运行在错误指令下产出一份看似正常的通用回答。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逐字节一致、mode_name与mode_id互斥不发送 history——every delegation is one shot 由测试直接锁死transport-evals.sh#L67-L68无 mode 的回答必须失败、过期锁定要指向具体变量stderr 噪声不得污染响应、超载荷必须被拒绝且错误里带出上限值。本地运行入口run.sh共 51 个 hook transport 用例bash evals/run.sh配置速查传输层相关环境变量一览变量默认值作用SHUNT_MAX_PAYLOAD_BYTESLinux 120000 / 其他 400000argv 载荷上限超了就拒绝发送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 预检换取清晰报错用五道防线换取绝不静默出错。想继续深入可以顺藤摸瓜看两个调用方 bulk-read文件以file path...XML 标签包裹后流式写入临时文件和 code-write剥除 markdown 围栏后可直写磁盘以及端到端用例 evals.json 与 token 节省基准 benchmarks.json。【免费下载链接】portal-ai-plugins项目地址: https://gitcode.com/gh_mirrors/po/portal-ai-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考