从不覆盖用户文件的安装器剖析Sol Advisor install-agents.sh的fail-closed设计【免费下载链接】sol-advisorCodex-native architect orchestration with Luna and Terra implementation lanes and mandatory fresh Sol review.项目地址: https://gitcode.com/gh_mirrors/so/sol-advisorSol Advisor 是一个 Codex 原生的架构编排插件主会话由 Sol 负责规划与验收Luna 执行例行实现Terra 负责高风险升级最后再由一个全新的 Sol 评审把关。要驱动这套三角色流水线你需要先安装它自带的三个角色模板文件——而干这件事的正是 install-agents.sh。这个安装器最硬核的承诺只有一条宁可报错退出也绝不覆盖、篡改你的文件。本文带你完整拆解它的 fail-closed失败即关闭设计。为什么安装器不覆盖文件如此重要这三个角色模板sol-advisor-luna-implementer.toml、sol-advisor-terra-implementer.toml、sol-advisor-sol-reviewer.toml会被装进你用户自己拥有的 Codex agents 目录默认~/.codex/agents或CODEX_HOME/agents。这个目录里可能躺着你自己手写的 agent 配置、其他插件的文件甚至软链接。一个想当然的安装器随手cp -f过去就是一场灾难。所以 Sol Advisor 采用了安装器界的黄金法则fail-closed任何不确定、不安全、有差异的目标一律不动手只报告冲突。它不修改 Codex 配置、不调用 Codex 命令、不碰任何看起来不太对的文件。第一步给目标文件对号入座——6种状态分类整个设计的核心是 classify_current_or_legacy() 函数它给目标文件判定出 6 种状态之一状态含义安装器行为missing文件不存在✅ 安装current与模板逐字节相同✅ 跳过幂等legacy与历史 v0.2.0 模板的 SHA-256 精确匹配✅ 安全迁移替换unsafe是软链接或非普通文件 拒绝报告冲突unreadable无法计算校验和 拒绝报告冲突conflict内容既非当前版也非历史版 拒绝绝不覆盖关键在第 3 种它把 v0.2.0 老版本的两个模板文件的 SHA-256 摘要硬编码为不可变的历史指纹。只有当你的旧文件与老版本一个字节都不差时才认为这是可以安全升级的历史模板只要你手动改过一个字符它就立刻降级为conflict安装器停下并报告而不是替你修复。三道防线预检 → 状态复核 → 安装后精确校验fail-closed 不是检查一次而是全程三关1️⃣ 预检先摸清所有文件再动第一刀安装器先逐个分类三个目标文件只要任何一个落入不可动状态就汇总报错并退出——此时一个字节都还没写。这保证失败是零副作用的不会出现装了一半的脏状态。2️⃣ 状态复核写之前再确认一遍进入写入阶段后same_state() 会重新分类每个文件确认它和预检时状态完全一致。这是防御TOCTOU检查与使用之间的时间差攻击/竞态如果文件在检查后被外部改动安装器立即中止并且明确告诉你后续文件均未再被修改。3️⃣ 安装后校验逐字节验收装完之后安装器再次比对三份文件与模板的字节一致性post-install exactness check任何偏差都会导致整个安装被判失败。原子写入连写一半都不允许看 install_missing() 的实现它没有直接cp到目标位置而是三步走用mktemp在同目录创建一个暂存文件把模板内容拷入暂存文件用ln同目录内的 rename把暂存文件变成目标文件名rename操作在文件系统上是原子的——目标位置要么是旧内容要么是完整的新内容不存在半截文件。历史模板的迁移replace_legacy_role()同样如此替换前还会二次确认文件仍是legacy状态否则清理暂存文件并失败退出。只读模式--check 让验证与安装分离安装器支持一个纯只读模式这也是日常使用中最推荐的用法sh $plugin_dir/scripts/install-agents.sh --check它只做分类和比对不创建、不替换、不删除任何东西只读校验逻辑。三个文件全部与模板逐字节一致时输出CHECK PASSED。Sol Advisor 的编排技能 SKILL.md 强制要求每次委托原生 agent 之前都要跑一次--check检查不过就停下该条实现通道、把安装器路径和冲突文件交给用户处理绝不允许用别的 agent 或模型绕过去。完整上手三步安装 一键体检# 1. 找到插件目录需要 jq plugin_dir$(codex plugin list --json | jq -r .installed[] | select(.pluginId sol-advisorsol-advisor) | .source.path) # 2. 安装三个角色模板幂等可重复执行 sh $plugin_dir/scripts/install-agents.sh # 3. 只读体检确认三份文件与模板逐字节一致 sh $plugin_dir/scripts/install-agents.sh --check安装器正常输出的三行结果也很直白INSTALLED新装、MIGRATED历史模板升级、ALREADY CURRENT已是最新。它还有一个 --target-dir 参数 支持自定义目标目录并拒绝把文件系统根目录当作安装目标。用测试锁住承诺verify.sh 的对抗性验证更值得学习的是上述每一个绝不覆盖的承诺都被 verify.sh 用对抗性用例钉死了 给目标文件追加一行modified→ 安装必须失败且目录快照前后完全一致零部分变更 把 Luna 文件换成软链接 → 安装拒绝且 Terra、Sol 也不会被顺带安装 写入伪造的历史 v0.2.0 模板含 SHA-256 指纹自校验→ 精确迁移成功✅ 干净安装后重跑 → 目录快照无任何变化幂等性证明⚠️ 对不存在的目录执行--check→ 必须失败且不得创建该目录这套测试本身就是 fail-closed 理念的最佳注脚安装器不仅要拒绝覆盖还要在拒绝时不留下任何半成品的痕迹。总结小脚本里的大工程观设计点用户得到的保证6 态分类 字节级比对你的修改永远不会被悄悄冲掉预检全部通过才写入失败 零副作用暂存 rename 原子替换永远看不到半截文件历史指纹精确迁移老用户可平滑升级且仅限原厂文件--check只读模式随时体检不碰一个字节verify.sh 对抗测试以上承诺持续可验证install-agents.sh 只有 260 多行却把信任用户文件这件事做到了近乎偏执的程度。对任何需要写用户目录的工具插件安装器、CLI 升级器、配置同步器来说它都是一份可以直接抄作业的 fail-closed 范本先分类、再预检、原子写、后验收任何一步不确定就停下来说话️【免费下载链接】sol-advisorCodex-native architect orchestration with Luna and Terra implementation lanes and mandatory fresh Sol review.项目地址: https://gitcode.com/gh_mirrors/so/sol-advisor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从不覆盖用户文件的安装器：剖析Sol Advisor install-agents.sh的fail-closed设计
从不覆盖用户文件的安装器剖析Sol Advisor install-agents.sh的fail-closed设计【免费下载链接】sol-advisorCodex-native architect orchestration with Luna and Terra implementation lanes and mandatory fresh Sol review.项目地址: https://gitcode.com/gh_mirrors/so/sol-advisorSol Advisor 是一个 Codex 原生的架构编排插件主会话由 Sol 负责规划与验收Luna 执行例行实现Terra 负责高风险升级最后再由一个全新的 Sol 评审把关。要驱动这套三角色流水线你需要先安装它自带的三个角色模板文件——而干这件事的正是 install-agents.sh。这个安装器最硬核的承诺只有一条宁可报错退出也绝不覆盖、篡改你的文件。本文带你完整拆解它的 fail-closed失败即关闭设计。为什么安装器不覆盖文件如此重要这三个角色模板sol-advisor-luna-implementer.toml、sol-advisor-terra-implementer.toml、sol-advisor-sol-reviewer.toml会被装进你用户自己拥有的 Codex agents 目录默认~/.codex/agents或CODEX_HOME/agents。这个目录里可能躺着你自己手写的 agent 配置、其他插件的文件甚至软链接。一个想当然的安装器随手cp -f过去就是一场灾难。所以 Sol Advisor 采用了安装器界的黄金法则fail-closed任何不确定、不安全、有差异的目标一律不动手只报告冲突。它不修改 Codex 配置、不调用 Codex 命令、不碰任何看起来不太对的文件。第一步给目标文件对号入座——6种状态分类整个设计的核心是 classify_current_or_legacy() 函数它给目标文件判定出 6 种状态之一状态含义安装器行为missing文件不存在✅ 安装current与模板逐字节相同✅ 跳过幂等legacy与历史 v0.2.0 模板的 SHA-256 精确匹配✅ 安全迁移替换unsafe是软链接或非普通文件 拒绝报告冲突unreadable无法计算校验和 拒绝报告冲突conflict内容既非当前版也非历史版 拒绝绝不覆盖关键在第 3 种它把 v0.2.0 老版本的两个模板文件的 SHA-256 摘要硬编码为不可变的历史指纹。只有当你的旧文件与老版本一个字节都不差时才认为这是可以安全升级的历史模板只要你手动改过一个字符它就立刻降级为conflict安装器停下并报告而不是替你修复。三道防线预检 → 状态复核 → 安装后精确校验fail-closed 不是检查一次而是全程三关1️⃣ 预检先摸清所有文件再动第一刀安装器先逐个分类三个目标文件只要任何一个落入不可动状态就汇总报错并退出——此时一个字节都还没写。这保证失败是零副作用的不会出现装了一半的脏状态。2️⃣ 状态复核写之前再确认一遍进入写入阶段后same_state() 会重新分类每个文件确认它和预检时状态完全一致。这是防御TOCTOU检查与使用之间的时间差攻击/竞态如果文件在检查后被外部改动安装器立即中止并且明确告诉你后续文件均未再被修改。3️⃣ 安装后校验逐字节验收装完之后安装器再次比对三份文件与模板的字节一致性post-install exactness check任何偏差都会导致整个安装被判失败。原子写入连写一半都不允许看 install_missing() 的实现它没有直接cp到目标位置而是三步走用mktemp在同目录创建一个暂存文件把模板内容拷入暂存文件用ln同目录内的 rename把暂存文件变成目标文件名rename操作在文件系统上是原子的——目标位置要么是旧内容要么是完整的新内容不存在半截文件。历史模板的迁移replace_legacy_role()同样如此替换前还会二次确认文件仍是legacy状态否则清理暂存文件并失败退出。只读模式--check 让验证与安装分离安装器支持一个纯只读模式这也是日常使用中最推荐的用法sh $plugin_dir/scripts/install-agents.sh --check它只做分类和比对不创建、不替换、不删除任何东西只读校验逻辑。三个文件全部与模板逐字节一致时输出CHECK PASSED。Sol Advisor 的编排技能 SKILL.md 强制要求每次委托原生 agent 之前都要跑一次--check检查不过就停下该条实现通道、把安装器路径和冲突文件交给用户处理绝不允许用别的 agent 或模型绕过去。完整上手三步安装 一键体检# 1. 找到插件目录需要 jq plugin_dir$(codex plugin list --json | jq -r .installed[] | select(.pluginId sol-advisorsol-advisor) | .source.path) # 2. 安装三个角色模板幂等可重复执行 sh $plugin_dir/scripts/install-agents.sh # 3. 只读体检确认三份文件与模板逐字节一致 sh $plugin_dir/scripts/install-agents.sh --check安装器正常输出的三行结果也很直白INSTALLED新装、MIGRATED历史模板升级、ALREADY CURRENT已是最新。它还有一个 --target-dir 参数 支持自定义目标目录并拒绝把文件系统根目录当作安装目标。用测试锁住承诺verify.sh 的对抗性验证更值得学习的是上述每一个绝不覆盖的承诺都被 verify.sh 用对抗性用例钉死了 给目标文件追加一行modified→ 安装必须失败且目录快照前后完全一致零部分变更 把 Luna 文件换成软链接 → 安装拒绝且 Terra、Sol 也不会被顺带安装 写入伪造的历史 v0.2.0 模板含 SHA-256 指纹自校验→ 精确迁移成功✅ 干净安装后重跑 → 目录快照无任何变化幂等性证明⚠️ 对不存在的目录执行--check→ 必须失败且不得创建该目录这套测试本身就是 fail-closed 理念的最佳注脚安装器不仅要拒绝覆盖还要在拒绝时不留下任何半成品的痕迹。总结小脚本里的大工程观设计点用户得到的保证6 态分类 字节级比对你的修改永远不会被悄悄冲掉预检全部通过才写入失败 零副作用暂存 rename 原子替换永远看不到半截文件历史指纹精确迁移老用户可平滑升级且仅限原厂文件--check只读模式随时体检不碰一个字节verify.sh 对抗测试以上承诺持续可验证install-agents.sh 只有 260 多行却把信任用户文件这件事做到了近乎偏执的程度。对任何需要写用户目录的工具插件安装器、CLI 升级器、配置同步器来说它都是一份可以直接抄作业的 fail-closed 范本先分类、再预检、原子写、后验收任何一步不确定就停下来说话️【免费下载链接】sol-advisorCodex-native architect orchestration with Luna and Terra implementation lanes and mandatory fresh Sol review.项目地址: https://gitcode.com/gh_mirrors/so/sol-advisor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
