【免费下载链接】agent-scriptsScripts for agents, shared between my repositories.项目地址https://gitcode.com/gh_mirrors/ag/agent-scripts点击查看免费下载本文以agent-scripts仓库中 vm-lab 技能附带的 bootstrap-diagnostics.md 为核心依据系统讲解两类高发引导期故障的排查方法论Apple-VZ 克隆出现活动裸盘为空、以及 macOS 打包脚本在输出第一条进度前停滞。读完本文你将掌握一套先核验 CLI 契约、再只读取证、最后才执行窄范围回退的处置流程并能在不改动全局环境、不触碰他人 VM 与凭据的前提下完成可复现、可交接的故障诊断。总则把引导失败与产品失败严格分开文档开篇就确立了一条贯穿始终的边界原则引导bootstrap故障必须与产品故障分开处理。所谓引导故障指的是任务自己拥有的克隆或打包流程本身无法启动或无法产出的问题而不是被测 GUI 工具如 Peekaboo 类工具自身的缺陷。与之配套的证据纪律是原始日志、快照 ID、VM 名称、bundle 路径、宿主机清单等敏感素材一律存放在私有的任务证据目录中不进入对外输出对外只发布经过脱敏的结论sanitized conclusions例如磁盘零分配且缺少 GPT这类技术判定四条红线任何时候都不能突破绝不重置源快照、绝不去操作其他任务的 VM含恢复 VM、绝不访问继承的访客凭据、绝不削弱启动安全性。这条总则并非空泛要求而是整个诊断流程的操作前提因为引导故障诊断天然会触碰 VM 文件系统、进程与 shell 解释器一旦越界轻则污染证据重则破坏共享实验室环境。vm-lab 技能页 skills/vm-lab/SKILL.md 的 Safety Rules 也给出了同样口径只有任务自己拥有的克隆是可处置的源/黄金快照、恢复 VM 与别家 VM 一律保序不动。场景一Apple-VZ 克隆的活动裸盘为空事件背景克隆成功了却没有任何可引导内容文档记录了一起报告的 incident某个任务的 Apple-VZ 克隆无论走linked clone路径还是随后执行clone --unlink产出的活动裸盘.hds都呈现同样异常——逻辑大小为 128 GiB、分配字节数为零、没有 GPT 分区表而不可变的源快照本身是完整有内容的。关键点在于这属于任务方提供的 incident 陈述而不是在本仓库内新复现出的 Parallels 缺陷也不是厂商支持手册里的标准恢复流程。因此下文所有恢复动作都严格限定在窄范围回退之内读者切勿把它当成通用的.hds修复配方。先核对契约再决定是否重试面对克隆失败的第一反应不应是换参数猛试而是先核对当前安装的 Parallels CLI 版本及其契约。文档给出的三条命令prlctl --versionprlctl clone --helpprlctl snapshot-list --help文档以Parallels CLI 27.0.158670检查日期 2026-09-05为例说明从帮助文本能读出哪些契约clone --help文档化支持--linked [-i,--id]linked clone 需要快照 ID--unlink在帮助里的语义是创建一个与父快照解绑的新克隆不是原地修复现有 VM还提供--force-deep-copy选项。由此得出一个容易被忽略的结论选项名字听起来深拷贝解绑并不等于产出的引导盘一定可启动同理克隆命令成功退出也不等于启动盘内容完整。所以文档明确警告不要在未检查产物的情况下继续尝试更多 clone 变体。同时还要区分三种不同的失败类型VZ 活动 VM 数量上限、磁盘空间不足、缺少可引导盘——三者原因与处置完全不同绝不允许通过停掉别人的 VM 来腾容量。取证记录任务所属 VM 的精确身份对任务自己拥有的 VM动手前必须记录VM 的UUID、类型Apple-VZ、停止状态bundle 位置选中的快照 ID从 VM 配置和DiskDescriptor.xml中解析出的活动盘路径。文档特别强调不要用 glob 去挑最新最大的.hds而要利用已有的只读快照元数据解析出源盘 辅助状态auxiliary state这一精确配对。如果所有权、格式、谱系ancestry或配对关系存在任何歧义宁可停止也不要猜测。只读核验逻辑大小、分配量、分区结构三管齐下在确认目标镜像属于raw、standalone即不是任意的 Parallels delta/容器镜像之后把验证过的文件路径记为raw_hds并用两条命令做只读对比源不可变镜像单独另查stat -f logical_bytes%z allocated_blocks%b $raw_hds/usr/sbin/gpt -r show $raw_hds使用要点与陷阱文档均给出实测依据macOS 上stat的allocated_blocks单位是512 字节gpt -r以只读方式打开重点是看分区列表本身而不是只看退出码——文档记录一个合成的 128 GiB 全洞all-hole文件gpt -r返回 exit 0但输出只有一段未分区 extent稀疏分配本身是正常的linked child 或 APFS clone 天然稀疏仅凭稀疏就断言底层链坏了是错误的真正有用的判别标准是组合出现已确认 standalone 的 raw 镜像缺少 GPT 分配量为零 源快照有内容调查此症状时不要挂载源盘也不要尝试分区修复——两者都会污染只读证据。恢复边界被授权的盘 辅助文件复制只是窄范围回退文档强调优先选择受支持、已验证的克隆路径。报告的盘 辅助文件auxiliary复制做法是一份被严格限定范围的回退方案不是通用的.hds修复配方并且只允许在后续任务明确授权的前提下执行。完整的四步流程如下核验目标目标必须是停止状态、任务自己拥有的 standalone 克隆解析出真实路径并拒绝 symlink / hardlink / 指向源盘或其他 VM 的 backing 引用确认不可变快照稳定、所选 raw 盘自包含不是未决 delta 链中的一员。任何一项检查不过即停止。保留回滚把目标原有的活动盘和aux.bin存入任务自己拥有的回滚存储记录 descriptor 哈希、源快照/盘/辅助状态的标识为后续写时复制copy-on-write增长预留足够空闲空间。暂存副本在目标文件系统内分别对精确的源快照.hds和与之匹配的Snapshots/{id}.bin做独立的 APFS 副本在内容校验一致之后才替换目标的活动.hds与aux.bin保持DiskDescriptor.xml逐字节不变不得拿源盘当前的aux.bin顶替也不得混用快照 ID。复查后启动再次检查分配量/GPT、descriptor 哈希以及源身份/内容未变然后只启动任务自己的克隆独立验证正常启动注意启动成功绝不等于可以开始使用继承的凭据。一旦出现不匹配或持续引导失败停止并保留证据——不做源盘编辑、不做快照切换、不走安全绕过、不进入自动修复循环。文档还给出了cp -c的底层语义提醒macOS 的cp -c会请求clonefile(2)的写时复制语义但在跨文件系统或不受支持的 FS 上会回退为普通拷贝APFS 文件克隆不等于Parallels linked clone前者后续写入彼此私有硬链接完全不能替代。更关键的是通用手册只解释拷贝语义不解释 Parallels 的快照/辅助状态配对关系——该配对必须针对特定任务逐一验证。场景二打包进程在首个输出前停滞事件证据堆栈、日志与 handoff 之间的差距文档记录的现场证据包括保存下来的 macOS 进程采样sample中全部 893 个采样点都含嵌套的command_substitute帧末端落到do_redirections → heredoc_write → write原始打包日志为空handoff 还额外报告了16 KiB 管道已满与没有子进程——但文档明确指出这两项并没有被堆栈本身证明第二次日志推进到了Bundle ready且存在一个任务本地的bash → /bin/bash符号链接handoff 把成功归因于/bin/bashBash 3.2 PATH shim但日志没有保留确切的启动命令。这段记录示范了一个重要的诊断态度堆栈只能告诉你卡在 heredoc 写管道的某处不能告诉你这台主机为什么卡住更不能替代对当前脚本的实地检查。诊断 shell而不是诊断静默的产品对精确的任务所属的卡死 Bash PID文档要求把有界采样、进程/子进程状态、文件描述符信息全部留在私有证据里并且明确禁止三类动作按名称做sample bash、pkill bash、以及倾倒环境/凭据。设evidence_dir为全新的任务私有目录后四条取证命令ps -p $pid -o pid,ppid,state,etime,commpgrep -P $pidsample $pid 1 1 -file $evidence_dir/shell-sample.txtlsof -nP -p $pid解读时注意文档给出的证据学要点pgrep返回 exit 1 只代表那一刻没有匹配子进程不能当作整个停滞期间都没有要重复观察再下结论对管道而言lsof报告的是缓冲内容而不一定是容量因此要把两端与进程的证据都留下而不是一看到16384就断言管道满了要解析并记录实际的解释器/版本、脚本的shebang、以及经 PATH 解析出的子 shell对外分享诊断前要对路径和命令数据脱敏在涉及签名或凭据时避免不加限制的bash -x。文档还剖析了这类停滞的结构性原因incident 涉及的打包源码在输出第一条正常进度之前就进行了带 Python heredoc 的嵌套命令替换并调用裸bash以及带#!/usr/bin/env bash的辅助脚本。因此重定向停滞可以发生在预期的子进程出现、以及任何可见构建工作之前只把外层脚本换成/bin/bash并不能锁定全部后代进程。面对这类情况要检查当前脚本本身而不能仅凭堆栈推断具体卡在哪一行。底层机制Bash 5.3 的 heredoc 写管道文档引用 GNU Bash 5.3 的redir.c源码机制skills/vm-lab/references/bootstrap-diagnostics.md 的原始出处说明Bash 5.3 的here_document_to_fd可以在返回读描述符之前通过heredoc_write同步地把管道写满管道路径存在编译期的大小阈值且只在F_GETPIPE_SZ可用时才做运行期容量检查其他情况下会改用临时文件。这就解释了卡住的 heredoc 写入是一个有用的线索但不解释这台特定主机为何卡住。handoff 材料不足以推出任何被确认的 Parallels、Homebrew、Bash 或 macOS 厂商根因——这种区分线索与根因的克制正是本文档方法论的核心。仅限单次调用的回退方案PATH shim如果当前脚本及其后代支持 Bash 3.2那么可以对被授权的打包任务做一次仅限本次调用的重试保持同样的源码、构建/签名 guard、环境与参数保留正常工具 PATH但在前面临时插入一个 shim让裸bash与/usr/bin/env bash都解析到系统解释器。显式绝对解释器路径、以及会替换 PATH的子进程必须单独检查。从被授权的构建检出目录运行下面这条复合命令并带上原有脚本参数( shim$(mktemp -d ${TMPDIR:-/tmp}/vm-lab-bash.XXXXXX) || exit trap rm -f $shim/bash; rmdir $shim EXIT ln -s /bin/bash $shim/bash || exit PATH$shim:$PATH /bin/bash ./scripts/package-mac-app.sh )这条命令的要点用mktemp -d在${TMPDIR:-/tmp}下创建一次性目录trap ... EXIT保证结束时清理 shim 与目录把系统/bin/bash软链为$shim/bash并前置到PATH从而让裸bash与env bash都命中系统 Bash 3.2不产生任何持久 shell 配置Homebrew、全局 PATH、Codex 设置、源文件与构建 guard 全部保持原样。配套的禁令同样重要不要替换 Homebrew 的 bash 二进制、不要设置全局BASH_COMPAT、不要删掉验证/签名步骤。收尾时校验预期产物并保留退出状态与日志——到达第一条输出消息不等于打包成功。这条隔离解释器选择的思路在本仓库中也有同源实践release-mac-app 技能的入口 skills/release-mac-app/scripts/mac-release 使用#!/bin/bash -pshebang 并主动清除BASH_ENV/ENV/CDPATH/GLOBIGNORE其技能页 skills/release-mac-app/SKILL.md 明确要求直接执行mac-release以让特权 shebang 忽略启动钩子若必须显式指定解释器则用/bin/bash -p绝不用裸bash mac-release底层库 skills/release-mac-app/scripts/lib/mac_release.sh 的默认命令钩子使用env -u BASH_ENV bash -c目的同样是防止 shell 启动文件覆盖已导出的发布机密。这些设计都印证了 bootstrap 文档的核心判断解释器与启动环境的选择必须对每次调用显式可控。隔离探针2026-09-05 的复现检查结果文档记录了当天在隔离环境中做过的对照实验环境为macOS 26.6.225G83Homebrew Bash 5.3.15与系统 Bash 3.2.57均完成了合成 command-substitution heredoc 测试数据规模为 1,024 / 16,383 / 16,384 / 16,385 / 32,768 / 65,536 / 131,072 / 262,144 字节每种都带三秒超时已安装的 Homebrew 二进制 UUID 与保存的采样一致但停滞没有在这些隔离探针中复现。文档给出的解读非常克制这既不否定保存下来的堆栈证据也不证明生产打包流程是健康的。因此不要通过耗尽主机管道/资源的方式人为制造复现该次文档化检查没有启动或改动任何 VM也没有重跑打包。证据来源与证据边界文档在最后明确划定了证据范围这也应成为读者引用时的边界已核对的契约prlctl --version、prlctl clone --help、prlctl snapshot-list --helpmacOS 的stat(1)、stat(2)、gpt(8)、cp(1)、clonefile(2)、sample(1)、lsof(8)手册以及合成 raw 文件与写时复制检查对只读 GPT 行为与独立拷贝行为的确认。外部参考Parallels 开发者指南的 clone 章节说明了 linked/snapshot clone 选项但不构成Apple-VZ raw 盘水合hydration的保证也不是盘/辅助状态恢复规范安装版帮助额外记录了--unlink与--force-deep-copy。GNU Bash 5.3redir.c提供了here_document_to_fd/heredoc_write的源码机制但不证明本机构建的管道阈值或 incident 成因。OpenClaw 的scripts/package-mac-app.sh需要重新核对被测修订版与子解释器因为该链接跟随 main 分支而不是冻结的 incident 复现。未公开的素材私有 incident 产物仅用于检查堆栈、空/完成构建日志、任务本地符号链接与记录的 Apple-VZ VM 类型原始分配量/GPT 与盘/辅助复制证据未在限定范围内找到恢复细节被明确归因于所供 handoff原始产物与私有库存定位器故意不拷贝到公开文档中。小结一份可复用的引导故障处置清单综合文档全篇一套可复用的处置顺序可以概括为分域确认故障属于任务自己的克隆/打包引导流程而非产品缺陷素材进私有证据结论出脱敏报告守线不动源快照、不动他人 VM、不碰继承凭据、不削弱启动安全核契约prlctl --version 对应子命令--help确认当前版本下选项的真实语义再决定是否重试取证对克隆问题用statgpt -r做只读核验逻辑大小/分配量/GPT对打包停滞用ps/pgrep -P/sample/lsof锚定精确 PID 与后代限定回退克隆问题走核验→回滚存储→APFS 副本→复查启动四步打包问题走临时 PATH shim 系统 Bash 3.2的单次调用方案留证交接校验产物、保留退出状态与日志记录版本、UUID、快照 ID、解释器版本等可追溯标识只移交脱敏结论。这套方法的价值在于它把诊断动作与生产环境安全之间的张力化解为一套始终可审计、可回滚、可交接的规程——这正是 skills/vm-lab/references/bootstrap-diagnostics.md 在 vm-lab 技能体系skills/vm-lab/SKILL.md 的 Bootstrap Preflight 一节直接引用它中所承担的职责让每次引导排查既彻底又不越界。赞分享【免费下载链接】agent-scriptsScripts for agents, shared between my repositories.项目地址https://gitcode.com/gh_mirrors/ag/agent-scripts点击查看免费下载相关推荐repowise 故障排查完全指南从 doctor 诊断到索引修复与 Agent 联调repowise 故障排查完全指南从 doctor 诊断到索引修复与 Agent 联调 repowise doctor 、 repowise status 与VFS for Git 虚拟文件系统完全指南克隆、挂载、缓存配置与故障排查VFS for Git 虚拟文件系统完全指南克隆、挂载、缓存配置与故障排查 VFS for Git原 GVFSGit Virtual File Syste版本控制开发工具存储Valdi 安装故障排查指南nvm、交换空间与 valdi doctor 环境诊断Valdi 安装故障排查指南nvm、交换空间与 valdi doctor 环境诊断 Valdi 是一套跨平台 UI 框架其构建链路依赖 Node.js、Ba跨平台UI组件前端移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考