尧图网页设计 
完整剖析 portal-ai-plugins 的 shunt 三层架构Hooks 硬门禁、Scripts 管线与 Skills 引导如何协同【免费下载链接】portal-ai-plugins项目地址: https://gitcode.com/gh_mirrors/po/portal-ai-pluginsshunt是 portal-ai-plugins 项目内置的一款 I/O 分流插件它用Hooks 硬门禁拦截大文件读取用Scripts 管线把批量读文件和样板代码生成委派给更便宜的 AiKA 工作模型再用Skills 引导教会 AI 助手何时该调用。三者协同后大文件读取与代码生成可节省82%–94% 的 token。本文面向新手逐层拆解这套门禁—管线—引导的三层架构是如何协同工作的。 说明shunt 目前仅在 Claude Code 中可用且依赖同市场的 portal 插件提供的 Portal CLI。为什么需要 shunt大文件读取的隐藏成本AI 编程助手读源码时会把整个文件塞进上下文。文件越大token 消耗越高——在几十万行的单体仓库里一句这个服务是干什么的可能瞬间吃掉几万 token换来的却只是一小段摘要。plugins/shunt/README.md 中给出的基准数据测试环境为 16.2 万行 Java 单体仓库场景未用 shunt使用 shunt节省单个大文件4,014 行33,684 tokens5,737 tokens82%源码 测试对7,408 行75,990 tokens4,148 tokens94%多文件跨服务1,281 行16,221 tokens821 tokens94%shunt 的核心思想一句话不让主模型亲自读文件而是把读和写样板代码委派给廉价工作模型只把简洁的结构化答案喂回主模型。三层架构总览硬门禁、管线与引导各司其职shunt 的设计哲学是三层从硬约束到软建议层层递进互不越权。层级组件职责强制性第 1 层Hooks 硬门禁check-file-size、check-bash-read拦截大文件读取请求强制无法绕过第 2 层Scripts 管线bulk-read、code-write执行 AiKA 调用与输出清洗自动执行第 3 层Skills 引导bulk-reader/SKILL.md、code-writer/SKILL.md教会 AI 何时、如何调用脚本自愿引导钩子注册集中在 hooks/hooks.json两个PreToolUse钩子分别挂在Read与Bash工具之前每次工具调用前都会先过一遍检查。第 1 层Hooks 硬门禁——大文件读取的第一道拦截check-file-size在每次文件读取请求触发。文件超过 350 行且未指定读取区间时直接拦截并提示请改用 bulk-reader 技能把这次读取委派给 AiKA。以下情况则放行定向读取设置了 offset/limit——模型已经知道自己要读哪一段小文件350 行以内——委派开销比收益还大不存在的文件——交给读取工具自己报错。check-bash-read是防钻空子的后手模型若试图用cat、head、tail等命令读大文件同样会被拦截但带管道cat file | grep或重定向的命令属于定向读取放行。两个钩子共用同一个阈值参数SHUNT_MIN_LINES默认 350 行可配置。边界行为恰好 350 行放行、351 行拦截等都有对应的测试用例可参见 evals/hook-evals.json 与 evals/bash-hook-evals.json。第 2 层Scripts 管线——模型永远不亲手拼命令请求被 Hooks 拦截后下一步是把文件交给工作模型。这由 Scripts 层完成两个脚本职责清晰bulk-read批量读支持一次传多个文件。脚本把每个文件用 XML 标签包出清晰边界整体发给 AiKA 的bulk-reader模式回传的只有关键答案code-write生成样板代码生成测试、配置、文档字符串等。--reference是必填项——没有参照文件工作模型只能写出看起来对但不合项目风格的代码还可以用--target直接落盘。两条流水线的公共底座是 scripts/lib/aika.sh它封装了全部委派细节所有调用统一走 Portal CLI 的aika:invoke-chat动作不绑定任何特定环境任何开启 AiKA 的 Portal 实例都能用模式按名称解析优先用户自建模式其次群组模式最后公共模式名称有歧义时可用SHUNT_*_MODE_ID环境变量钉住某个具体模式每次调用都是一次性的工作模型不保存上下文追问就是带着文件再问一次——文件只发给廉价模型、永不进主模型上下文重发并不心疼内置负载上限Linux 默认约 120 KB、其他平台约 400 KB与超时默认 180 秒超限时报清晰错误并提示拆分批次而不是抛出晦涩的底层报错。这一层最值得品味的设计点主模型不从自然语言里拼 bash 管线它只按命名参数调用脚本——文件包装、发送、输出清洗全部藏在脚本内部模型侧零复杂度。第 3 层Skills 引导——告诉 AI什么时候该用Hooks 只管大文件读取这一种场景那 code-write 何时该主动使用这就是 Skills 层的分工。skills/bulk-reader/SKILL.md 给出明确适用条件需要读取超过 350 行的文件、跨 3 个以上文件提问、或总结大型 diffskills/code-writer/SKILL.md 则指出测试、配置、类型桩等80% 以上可从参照文件推导的生成任务。两份技能文件还附带使用纪律例如把答案中的行号用于编辑前先核实对 code-write 的产物人工审查那 5%–20% 需要深度判断的部分。Skills 是软层——它不能拦截只能引导。官方文档也坦承这一点code-writer 没有钩子强制只能靠模型自觉属于已知限制。三层如何协同一次完整委派流程以询问一个 1,200 行的服务文件为例流程如下模型先用Read工具尝试读取该文件Hookscheck-file-size拦截并反馈原因文件 1,200 行超过 350 行阈值请改用 /bulk-reader 技能委派这次读取模型按Skills的引导调用bulk-read --question 这个服务是做什么的 --paths src/Service.javaScripts把文件打包、调用 AiKA 的 bulk-reader 模式只回传几行结构化答案状态行附带估算 token 数全程 1,200 行源码从未进入主模型上下文。同样被设计进插件的还有不该委派什么调试需要主模型推理、精确编辑需要原文在上下文改用定向读取、小文件、架构决策。⚖️知道何时不委派和知道何时委派一样重要。快速上手安装与常用配置先安装同市场的 portal 插件提供 Portal CLI再安装 shunt然后在新会话中执行/portal:setup完成认证检查你的实例是否已有bulk-reader与code-writer两个 AiKA 模式——很多实例默认内置公共模式有则直接开用没有则用aika:create-mode创建完整模板见 plugins/shunt/README.md。常用配置均为环境变量写入.claude/settings.json的env块即可变量默认值作用SHUNT_MIN_LINES350读取拦截的行数阈值SHUNT_PORTAL_INSTANCECLI 默认指定 Portal 实例PORTAL_CLI_BINportal-cli 或 npx自定义 CLI 启动方式SHUNT_TIMEOUT_SECONDS180单次动作调用超时SHUNT_MAX_PAYLOAD_BYTES400000Linux 120000单次请求负载上限SHUNT_*_MODE_ID—名称有歧义时钉住具体模式如何验证内置的 51 条评测用例shunt 自带完整评测套件钩子路由、传输层管线、端到端技能场景共 51 条用例。不连接 Portal 实例也能在本地跑通前两层bash evals/run.sh配置好认证后追加--benchmark可实测 token 节省。评测脚本为 evals/run.sh基准场景定义在 evals/benchmarks.json端到端用例在 evals/evals.json测试用文件位于 evals/fixtures/。总结可借鉴的门禁—管线—引导组合shunt 三层架构给了AI 编程成本优化一个清晰的分层答案Hooks 硬门禁管绝对不能做什么——强制且不可绕过兜住最坏情况Scripts 管线管如何可靠地做——把所有脆弱细节打包、发送、清洗、报错封装在命名参数脚本里Skills 引导管什么时候该做——用自然语言描述适用场景与纪律提供主动判断。三层各干一件事硬约束 自动管线 软引导互补平均约90% 的 token 节省主模型上下文始终保持干净。如果你在大型代码库中高频使用 AI 编程助手这套思路值得直接借鉴。【免费下载链接】portal-ai-plugins项目地址: https://gitcode.com/gh_mirrors/po/portal-ai-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 完整剖析 portal-ai-plugins 的 shunt 三层架构：Hooks 硬门禁、Scripts 管线与 Skills 引导如何协同
完整剖析 portal-ai-plugins 的 shunt 三层架构Hooks 硬门禁、Scripts 管线与 Skills 引导如何协同【免费下载链接】portal-ai-plugins项目地址: https://gitcode.com/gh_mirrors/po/portal-ai-pluginsshunt是 portal-ai-plugins 项目内置的一款 I/O 分流插件它用Hooks 硬门禁拦截大文件读取用Scripts 管线把批量读文件和样板代码生成委派给更便宜的 AiKA 工作模型再用Skills 引导教会 AI 助手何时该调用。三者协同后大文件读取与代码生成可节省82%–94% 的 token。本文面向新手逐层拆解这套门禁—管线—引导的三层架构是如何协同工作的。 说明shunt 目前仅在 Claude Code 中可用且依赖同市场的 portal 插件提供的 Portal CLI。为什么需要 shunt大文件读取的隐藏成本AI 编程助手读源码时会把整个文件塞进上下文。文件越大token 消耗越高——在几十万行的单体仓库里一句这个服务是干什么的可能瞬间吃掉几万 token换来的却只是一小段摘要。plugins/shunt/README.md 中给出的基准数据测试环境为 16.2 万行 Java 单体仓库场景未用 shunt使用 shunt节省单个大文件4,014 行33,684 tokens5,737 tokens82%源码 测试对7,408 行75,990 tokens4,148 tokens94%多文件跨服务1,281 行16,221 tokens821 tokens94%shunt 的核心思想一句话不让主模型亲自读文件而是把读和写样板代码委派给廉价工作模型只把简洁的结构化答案喂回主模型。三层架构总览硬门禁、管线与引导各司其职shunt 的设计哲学是三层从硬约束到软建议层层递进互不越权。层级组件职责强制性第 1 层Hooks 硬门禁check-file-size、check-bash-read拦截大文件读取请求强制无法绕过第 2 层Scripts 管线bulk-read、code-write执行 AiKA 调用与输出清洗自动执行第 3 层Skills 引导bulk-reader/SKILL.md、code-writer/SKILL.md教会 AI 何时、如何调用脚本自愿引导钩子注册集中在 hooks/hooks.json两个PreToolUse钩子分别挂在Read与Bash工具之前每次工具调用前都会先过一遍检查。第 1 层Hooks 硬门禁——大文件读取的第一道拦截check-file-size在每次文件读取请求触发。文件超过 350 行且未指定读取区间时直接拦截并提示请改用 bulk-reader 技能把这次读取委派给 AiKA。以下情况则放行定向读取设置了 offset/limit——模型已经知道自己要读哪一段小文件350 行以内——委派开销比收益还大不存在的文件——交给读取工具自己报错。check-bash-read是防钻空子的后手模型若试图用cat、head、tail等命令读大文件同样会被拦截但带管道cat file | grep或重定向的命令属于定向读取放行。两个钩子共用同一个阈值参数SHUNT_MIN_LINES默认 350 行可配置。边界行为恰好 350 行放行、351 行拦截等都有对应的测试用例可参见 evals/hook-evals.json 与 evals/bash-hook-evals.json。第 2 层Scripts 管线——模型永远不亲手拼命令请求被 Hooks 拦截后下一步是把文件交给工作模型。这由 Scripts 层完成两个脚本职责清晰bulk-read批量读支持一次传多个文件。脚本把每个文件用 XML 标签包出清晰边界整体发给 AiKA 的bulk-reader模式回传的只有关键答案code-write生成样板代码生成测试、配置、文档字符串等。--reference是必填项——没有参照文件工作模型只能写出看起来对但不合项目风格的代码还可以用--target直接落盘。两条流水线的公共底座是 scripts/lib/aika.sh它封装了全部委派细节所有调用统一走 Portal CLI 的aika:invoke-chat动作不绑定任何特定环境任何开启 AiKA 的 Portal 实例都能用模式按名称解析优先用户自建模式其次群组模式最后公共模式名称有歧义时可用SHUNT_*_MODE_ID环境变量钉住某个具体模式每次调用都是一次性的工作模型不保存上下文追问就是带着文件再问一次——文件只发给廉价模型、永不进主模型上下文重发并不心疼内置负载上限Linux 默认约 120 KB、其他平台约 400 KB与超时默认 180 秒超限时报清晰错误并提示拆分批次而不是抛出晦涩的底层报错。这一层最值得品味的设计点主模型不从自然语言里拼 bash 管线它只按命名参数调用脚本——文件包装、发送、输出清洗全部藏在脚本内部模型侧零复杂度。第 3 层Skills 引导——告诉 AI什么时候该用Hooks 只管大文件读取这一种场景那 code-write 何时该主动使用这就是 Skills 层的分工。skills/bulk-reader/SKILL.md 给出明确适用条件需要读取超过 350 行的文件、跨 3 个以上文件提问、或总结大型 diffskills/code-writer/SKILL.md 则指出测试、配置、类型桩等80% 以上可从参照文件推导的生成任务。两份技能文件还附带使用纪律例如把答案中的行号用于编辑前先核实对 code-write 的产物人工审查那 5%–20% 需要深度判断的部分。Skills 是软层——它不能拦截只能引导。官方文档也坦承这一点code-writer 没有钩子强制只能靠模型自觉属于已知限制。三层如何协同一次完整委派流程以询问一个 1,200 行的服务文件为例流程如下模型先用Read工具尝试读取该文件Hookscheck-file-size拦截并反馈原因文件 1,200 行超过 350 行阈值请改用 /bulk-reader 技能委派这次读取模型按Skills的引导调用bulk-read --question 这个服务是做什么的 --paths src/Service.javaScripts把文件打包、调用 AiKA 的 bulk-reader 模式只回传几行结构化答案状态行附带估算 token 数全程 1,200 行源码从未进入主模型上下文。同样被设计进插件的还有不该委派什么调试需要主模型推理、精确编辑需要原文在上下文改用定向读取、小文件、架构决策。⚖️知道何时不委派和知道何时委派一样重要。快速上手安装与常用配置先安装同市场的 portal 插件提供 Portal CLI再安装 shunt然后在新会话中执行/portal:setup完成认证检查你的实例是否已有bulk-reader与code-writer两个 AiKA 模式——很多实例默认内置公共模式有则直接开用没有则用aika:create-mode创建完整模板见 plugins/shunt/README.md。常用配置均为环境变量写入.claude/settings.json的env块即可变量默认值作用SHUNT_MIN_LINES350读取拦截的行数阈值SHUNT_PORTAL_INSTANCECLI 默认指定 Portal 实例PORTAL_CLI_BINportal-cli 或 npx自定义 CLI 启动方式SHUNT_TIMEOUT_SECONDS180单次动作调用超时SHUNT_MAX_PAYLOAD_BYTES400000Linux 120000单次请求负载上限SHUNT_*_MODE_ID—名称有歧义时钉住具体模式如何验证内置的 51 条评测用例shunt 自带完整评测套件钩子路由、传输层管线、端到端技能场景共 51 条用例。不连接 Portal 实例也能在本地跑通前两层bash evals/run.sh配置好认证后追加--benchmark可实测 token 节省。评测脚本为 evals/run.sh基准场景定义在 evals/benchmarks.json端到端用例在 evals/evals.json测试用文件位于 evals/fixtures/。总结可借鉴的门禁—管线—引导组合shunt 三层架构给了AI 编程成本优化一个清晰的分层答案Hooks 硬门禁管绝对不能做什么——强制且不可绕过兜住最坏情况Scripts 管线管如何可靠地做——把所有脆弱细节打包、发送、清洗、报错封装在命名参数脚本里Skills 引导管什么时候该做——用自然语言描述适用场景与纪律提供主动判断。三层各干一件事硬约束 自动管线 软引导互补平均约90% 的 token 节省主模型上下文始终保持干净。如果你在大型代码库中高频使用 AI 编程助手这套思路值得直接借鉴。【免费下载链接】portal-ai-plugins项目地址: https://gitcode.com/gh_mirrors/po/portal-ai-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考