treg shell 模式深度解析：基于 PATH shim 的团队 CLI 透明凭据注入

后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载导读treg shellShell mode是 treg 项目提供的一种透明 CLI 拦截机制打开一个子 shell 后团队成员可以像本地安装一样直接运行团队注册过的 CLIstripe、gh、neonctl等无需键入任何密钥、也无需手动执行treg run。本文以 docs/context/interface/shell.md 为骨架结合 src/treg/shell.py、src/treg/cli.py 及 tests/test_shell.py 源码级证据完整讲解其 PATH shim 原理、shim 脚本契约、会话生命周期、本地/服务端双路由--server-for、--proxy拦截叠加以及它为什么刻意停留在treg run的薄封装这一安全姿态。读完你将能理解并正确使用treg shell start/stop的全部参数并清楚它与treg command、treg serve这两扇前门之间的关系。核心机制PATH 上的影子 CLI而不是 shell 钩子treg shell的拦截方式有一个关键设计决策它不是 preexec/DEBUG trap 之类的 shell 钩子而是在PATH上放置影子 CLIshim。从源码看src/treg/shell.py 中start_session在$XDG_RUNTIME_DIR或$TMPDIR下创建私有会话目录session_base_dir()优先选择 Linux 的XDG_RUNTIME_DIR、macOS 的TMPDIR两者都是 0700 级且不被全局列举tempfile.mkdtemp(prefixtreg-shell-)创建后还会显式chmod 0o700为每个注册 CLI 在会话目录的bin/下写入一个 shim见下节以该目录排在PATH首位的方式启动$SHELL。这样这个命令是否注册过的判定就交给 shell 自身的名字解析免费完成输入stripe时最先命中我们的 shim从而被路由进 treg而ls、git没有对应 shim正常解析到系统真实二进制。整个过程没有任何 shell 钩子参与。shim 脚本契约shim_script/write_shims每个 shim 的实际内容shim_script生成形如#!/bin/sh # treg shell shim → tool stripe-tool (runs locally) # Generated by treg shell start; do not edit — it vanishes when the shell exits. exec env PATH$TREG_SHELL_REALPATH /path/to/treg run stripe-tool -- $这里有两个精妙之处对应测试 tests/test_shell.py 中test_shim_execs_treg_run_with_clean_path_and_verbatim_args验证的契约干净的$TREG_SHELL_REALPATH防止自递归它是 shim 目录被前置之前捕获的原始 PATH。treg run内部用shutil.which(bin)解析真实二进制时走的是这条干净 PATH因此永远不会解析到 shim 自身同时真实 CLI 得以正常运行。字面量--隔离参数--将 treg 自身的参数解析与用户参数隔离开_run_local随后剥离它最终真实 CLI 收到的正是用户原样输入的内容测试中验证了[run, stripe-tool, --, balance, --live]的精确 argv 透传退出码也原样返回。此外shim 内嵌了一段cobra__complete*旁路当第一个参数以__complete开头时gh及大多数 Go CLI 的 shell 补全调用直接exec真实二进制不经过 tregsrc/treg/shell.py 中shim_script的bypass分支case $1 in __complete*) exec /opt/homebrew/bin/gh $ ;; esac原因是补全属于本地 shell 元数据、不需要凭据若强行路由进 treg会逐键刷爆审计日志并消耗每日额度。测试 tests/test_shell.py 中test_completion_call_bypasses_treg_real_bin_runs通过真实 shell 验证gh __complete sta只命中真实二进制gh repo list才走treg run。哪些 CLI 会被影子化plan_shimsplan_shims(tools, server_for)src/treg/shell.py决定拦截清单保留每个带有cli.bin且cli.enabled为真的工具——cli.enabled是拥有者的本地运行显式 opt-in未启用的工具即使强行treg run也会 403为每个 shim 分配路由local或server见下文--server-for返回排序后的(bin, tool_name, route)条目列表与警告列表若两个工具争抢同一个 bin先到者胜bin 不是普通文件名含路径分隔符、.、..则跳过——shim 是我们要写入的文件绝不允许 bin 名逃出 shim 目录src/treg/shell.py 中os.sep/os.altsep检查。对应测试test_plan_shims_filters_and_sorts覆盖了未启用、无 bin、无 cli 配置、路径逃逸、重复 bin 等全部过滤分支。会话生命周期环境变量、信号与 teardownstart_session会向子 shell 发布四个环境变量src/treg/shell.py 顶部常量变量含义TREG_SHELL标记存在活跃会话阻止嵌套会话cmd_shell_start检测到它会直接拒绝TREG_SHELL_DIR私有会话目录shim 位于dir/binTREG_SHELL_REALPATH干净的原始 PATHshim 转交给treg run用TREG_SHELL_PIDtreg shell start进程 PIDtreg shell stop靠它发信号然后通过_run_subshell运行交互式子 shell退出时拆除会话目录_teardown用shutil.rmtree幂等清理——Phase 1 磁盘上没有任何凭据可擦每次调用treg run都现取 grant 且从不持久化。信号处理是正确性的关键_run_subshell父进程忽略SIGINT/SIGQUIT它们属于交互前台子进程而将SIGTERM/SIGHUP转为停止子进程。这样treg shell stop向TREG_SHELL_PID发信号和用户关闭终端SIGHUP两条路径都能回到 teardown不会留下孤儿 shell。可选的--ttl会启动一个 daemon 计时器N 分钟后自动关闭会话threading.Timer测试test_run_subshell_ttl_closes_the_session验证 1 秒计时器能终止一个要睡 30 秒的 shell。shell 适配方面_shell_argv针对 zsh写$ZDOTDIR/.zshrc与 bash--rcfile分别生成 rc 文件恢复用户原始环境、确保 shim 目录始终排在 PATH 首位并在提示符前加上(treg)标记zsh 的PROMPT、bash 的PS1。命令接线在 src/treg/cli.py 的cmd_shell_start/cmd_shell_stop进入前要求已登录treg login且TREG_SHELL未激活GET /tools拉取工具清单后交给plan_shims若既没有可运行 CLI 也未开--proxy则明确报错并提示注册入口treg upload clis或treg tool update name --local-run on。双路由--server-for与本地/服务端分层默认情况下每个被影子化的 CLI 都在本地运行treg run tool。而treg shell start --server-for stripe,render会把stripe、render路由到treg run --server——密钥完全不落在这台机器上输出流式返回。但仅限server_runnable的工具若请求的工具不支持服务端运行则回退本地并给出警告src/treg/shell.py 中plan_shims的 fallback 分支server_for既可按 bin 匹配也可按工具名匹配测试test_plan_shims_routes_server_for_runnable_tools与test_plan_shims_matches_server_for_by_tool_name分别验证。--ttl则给整个会话设下硬性时间上限。为什么服务端运行可行、而本地模式需要独立设计这取决于凭据注入方式auth_mechanism为env/argv的 CLI 可以由服务端持有密钥并注入见 docs/context/architecture/local-run.md因此server_runnable只对这两种机制成立config_fileCLI 自读~/.config与device机制只能本地运行。--proxy拦截的另一半必须强调treg shell的兄弟门treg commandcmd_with详见 docs/context/architecture/local-proxy.md对单条命令做同样的捕获且不需要子 shell——对多数人来说它才是默认入口。--proxy则用于这样一个会话团队的 CLI经 shim与裸 HTTPS 调用经代理要同时生效。两者的分工shim 捕获成员敲键盘输入的注册 CLIstripe balancetreg shell start --proxy额外捕获Agent 自行发起的 HTTPS 调用——来自一个从没听说过 treg 的脚本比如直接写api.stripe.com请求的程序。它目前是opt-in因为拦截是这套体系里第一个可能破坏 Agent 自身调用的功能证书固定型客户端会拒绝我们的 CA意外比一个显式开关更糟。实现细节cmd_shell_start→_start_local_proxysrc/treg/cli.py生成/加载机器级 CAensure_ca把 allow-list 种子直接复用为 shims 已经拉取过的工具清单——包括所有注册主机、甚至没有 CLI 的工具因此不产生第二次请求测试test_cmd_shell_start_seeds_the_allow_list_from_the_tool_listing验证 hosts 被小写化、排序、无 host 工具被跳过启动代理后交给start_session两样东西extra_env代理 URL 信任包与on_close退出时停止代理extra_env在 treg 自身变量之后应用并跳过PATH/TREG_SHELL*所以任何附加项都无法破坏名字解析或伪造嵌套会话测试test_extra_env_cannot_break_the_shims启动横幅_print_banner会列出被捕获的主机并声明其余流量原样直出——成员绝不能偶然发现自己被拦截测试test_the_banner_names_the_captured_hosts断言横幅中出现完整主机名与Every other address goes straight out--proxy-port可将代理移出默认端口18791--renew-ca强制重新生成 CA。CLI 参数一览src/treg/cli.py 解析器定义参数作用treg shell start启动 treg 子 shell--server-for a,b将指定工具路由到服务端运行密钥不上本机仅对server_runnable工具生效其余回退本地并警告--ttl MINN 分钟后自动关闭会话默认无限制--proxy同时捕获 Agent 自行发起的、发往注册 API 的 HTTPS 调用其余流量直出--proxy-port PORT--proxy监听端口默认 18791--renew-ca启动--proxy前重新生成本机 CAtreg shell stop离开 treg shell等价于exit/Ctrl-D命令同时以treg cli shell start|stop形式提供别名见 docs/context/interface/cli.md。阶段划分为什么没有内存驻留 Agent当前是Phase 1shim 直接调用treg run免费复用了完整的 local-run 链路——grant、deny、runner-proof、OAuth leaf、审计 → 计量/额度见 docs/context/architecture/local-run.md。原计划的Phase 2 内存驻留会话 Agent 被刻意放弃treg run的每次命令级专用用户隔离treg-run系统用户、sudo -u treg-run交接成员的同一 uid 无法读取另一个 uid 进程的/proc/pid/environ使每次调用结束后成员进程内不留任何凭据痕迹——这比一个长期持有 RAM 中凭据的 Agent 姿态更强。因此 shell 模式始终只是treg run之上的一层薄便捷层真正的安全保证存在于 local-run 沙箱隔离 egress 白名单 输出脱敏 deny 规则之中。这一决策在 src/treg/shell.py 模块 docstring 与_teardown注释中反复强调Phase 1 磁盘上没有任何凭据可擦treg run每次调用现取 grant、从不持久化。测试印证客户端契约被逐条锁定tests/test_shell.py 在无真实服务器、无真实厂商 CLI 的情况下用假treg与真实/bin/sh验证了本节全部核心断言shim 在干净 PATH 上以原样 argv 调用treg run tool -- …且退出码透传test_shim_execs_treg_run_with_clean_path_and_verbatim_argsserver 路由 shim 生成treg run --server tooltest_server_route_shim_execs_treg_run_server补全调用直达真实二进制test_completion_call_bypasses_treg_real_bin_runs会话 wiringshim 目录排在 PATH 首位、REALPATH干净无 shim 目录、--ttl分钟转秒、退出后会话目录被拆除test_start_session_wires_path_and_tears_downtreg shell stop在会话外报错、在会话内向控制器发SIGTERMtest_stop_signals_the_controller嵌套会话、未登录、无可运行 CLI 三种启动前置守卫test_cmd_shell_start_*。已知边界--proxy依赖cryptography编译型依赖位于[proxy]extra 而非基础安装缺库时会收到明确的安装提示pip install tools-registry[proxy]或按实际安装方式给出等价命令src/treg/cli.py 的ensure_proxy_dependency。证书固定pinning的客户端会拒绝 treg 的 CA 而单独失败当前没有按主机的永不拦截名单。Node 23 及更早版本的fetch()完全无视代理变量Node 24 才提供NODE_USE_ENV_PROXY这类调用会绕过捕获详见 docs/context/architecture/local-proxy.md。某些厂商 CLI如gh在发起任何网络请求前就自行完成认证因此仍需要treg run路径代理无法拦截。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐CubeSandbox 透明出网安全代理 CubeEgress 深度解析L7 域名过滤、凭证注入与访问审计CubeSandbox 透明出网安全代理 CubeEgress 深度解析L7 域名过滤、凭证注入与访问审计 本文围绕 CubeSandbox 在每台宿主机上部Agent 沙箱虚拟化云原生人工智能后端容器运行时终极指南如何利用TabNine AI代码补全识别团队编码风格模式终极指南如何利用TabNine AI代码补全识别团队编码风格模式 TabNine作为一款强大的AI代码补全工具不仅能显著提升开发效率还能通过分析补全数据帮开发工具AI 应用Impeccable Manual Edit Applier 全解析live manual_edit_apply 事件如何安全落盘到真实源码Impeccable Manual Edit Applier 全解析live manual_edit_apply 事件如何安全落盘到真实源码 在 ImpeccAI 技能前端CLIdsh-plugin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考