fleet-maintenance

设备维护

维护 Peter 的 Mac，同时保护状态不明确的本地工作。明确允许在活动会话期间更新软件包，但这可能会干扰正在升级的软件。使用 $remote-mac 进行资产清点和 SSH 操作，所有 Xcode 工作都使用 $xcode-sync。

期望状态

• 读取 ~/Projects/manager/fleet/inventory.json，了解所需软件和本地账户托管引用。更改其架构或采用软件包之前，先阅读 references/fleet-schema.md。
• 除非 Peter 明确更改模型，否则必须恰好保留两个配置：
  • full：日常使用的 Mac，配备完整的开发、通信、媒体和 Agent 工具集。
  • worker：精简型远程 Mac，主要运行 Codex、Claude、OpenClaw 节点和支持 Agent 的基础设施。
• 将配置策略视为 minimum：安装必需项，并报告额外项，但不要移除它们。绝不能默默将检测到的软件变为预期状态。
• 在 ~/Projects/manager/computers.yaml 中维护拓扑、SSH 路由和已交接状态。不要在此技能中重复记录实时拓扑。
• 将密码、恢复密钥和私钥保存在 1Password 中。清单中只存不透明的项目 ID。执行任何 op 命令之前，先调用 $one-password；软件包维护期间，pending 引用不算错误。
• 两个配置都必须使用由 ssh_mesh 指定的经典 OpenSSH 网状网络。管理器的集群设置文档负责维护规范的对等节点列表和实时验证结果。使用对称的 Tailscale TCP 22 授权规则和每台主机各自的 authorized_keys；macOS GUI Tailscale 客户端不能充当 Tailscale SSH 服务器。只分发公钥，私钥保留在各自主机上；使用 BatchMode=yes 和有限超时验证两个方向，并将离线或被提供商阻止的方向留待处理。
• 每台集群 Mac 都必须具备稳定的 1Password CLI 完整性基线。除非清单中为该主机记录了 requirement_exceptions 安全边界，否则必须配置基于文件的服务账户配置块。使用 scripts/op-profile-audit.sh 审计符合条件的主机；使用 scripts/op-profile-audit.sh --cli-only 审计令牌豁免的主机。只有在加载 $one-password 且已配置权限为 0600 的令牌文件后才能修复；绝不要在清单中打印或存储令牌。
• 每台集群 Mac 都必须具备 Agent 技能镜像。使用 scripts/agent-skill-links-audit.sh 审计；其 --repair 仅在两个规范仓库都存在时调用广泛的规范同步。同步会保留真实目录和文件，接受同目录的本地归属，并报告其他真实目标冲突。对于 reason=nested-self-link，通过绝对路径直接调用经过审查的同步负责方，并使用 --repair-nested-self-links --dry-run -- NAME...；然后省略 --dry-run，仅删除已验证的嵌套叶节点；保留真实的 Claude 技能目录和 Codex 反向链接。这项有限的循环检查并非详尽的图验证。有关范围，请参阅 references/fleet-schema.md；有关集群设置，请参阅 ~/Projects/manager/docs/fleet-setup.md。
• 每台集群 Mac 都必须使用共享的全局 Git 忽略文件。使用 scripts/global-gitignore-audit.sh 审计；--repair 会创建 ~/.config/git/ignore、保留无关条目、添加清单中的 macOS 元数据模式，并将 core.excludesFile 指向该文件。若已配置其他排除文件，则需要人工审查，以免丢弃现有规则。
• Claude Code 和 Claude Desktop 编码会话不得包含 AI 归属信息。使用 scripts/claude-attribution-audit.sh 审计 ~/.claude/settings.json；--repair 会保留无关设置，同时禁用提交脚注、拉取请求页脚和远程会话链接。
• 两个配置都必须安装官方 Codex 和 Claude Code CLI。软件包归属由配置中的 codex 和 claude-code Homebrew cask 决定；单独的 claude cask 对应 Claude Desktop，不能满足 CLI 要求。使用 scripts/agent-cli-audit.sh 审计版本和非交互式身份验证；使用 --live 执行有时限、无工具且不持久化的模型轮次。绝不要在 Mac 之间复制常规 Claude OAuth 凭据：通过 $anthropic 在每台主机上分别刷新凭据，并将钥匙串锁定、账户选择或离线等情况留待处理。
• 两个配置都必须将 Octopool 配置为 GitHub 缓存，设置 requirements.github_cache: "octopool"。仅安装软件包并不足够：scripts/octopool-audit.sh 必须验证非交互式环境和登录 zsh 都通过 Octopool shim 解析 gh、客户端登录具有完整的身份元数据，并且每个已配置的池身份都处于健康状态。使用 --repair 通过现有已认证且路径稳定的 GitHub CLI 登录、安装 zsh shim，并在需要时修复 macOS 登录 PATH 顺序；该操作绝不会安装软件包或打印凭据。 使用确定性配置文件工具：

node skills/fleet-maintenance/scripts/fleet-profile.mjs collect
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  plan --fleet ~/Projects/manager/fleet/inventory.json \
  --host mac-studio-sf --snapshot /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  diff --source /path/to/macbook-pro.json --target /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  brewfile --fleet ~/Projects/manager/fleet/inventory.json --host mac-studio-sf
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  validate --fleet ~/Projects/manager/fleet/inventory.json
skills/fleet-maintenance/scripts/agent-skill-links-audit.sh
skills/fleet-maintenance/scripts/global-gitignore-audit.sh --host mac-studio-sf
skills/fleet-maintenance/scripts/claude-attribution-audit.sh
skills/fleet-maintenance/scripts/agent-cli-audit.sh
skills/fleet-maintenance/scripts/octopool-audit.sh
skills/fleet-maintenance/scripts/op-profile-audit.sh

采集器快照是观测证据，而非配置。将审核后的快照存储在 ~/Projects/manager/fleet/snapshots/<host-id>.json 下。diff 会报告仅存在于源端的候选项；由 Peter 决定哪些项纳入 full。

安全约定

• 读取 ~/Projects/manager/computers.yaml；使用实时 Tailscale 状态，并按硬件 UUID 对主机去重。排除已移交和未知的设备。
• 并行审计主机；一次只修改一台主机。每次修改仓库或 Xcode 前，立即重新检查 Agent 活动情况。
• 跳过当前有用户进程的工作目录位于其中或存在 Git 锁的仓库。近期文件只是审计信号，不构成阻止条件。仅通过下文无冲突的快进流程，才允许处理存在未提交更改的工作树。
• 即使 Agent/服务正在运行，也允许更新 Homebrew 和全局 npm。这可能导致内存中的旧代码与已替换文件混用、后续导入或子进程出错，也可能使 Homebrew 终止并重新打开 cask 图形界面应用。接受此类软件包更新风险；切勿手动终止或重启服务。验证运行状况，并报告中断或待处理的重启。
• 日常维护期间，绝不重置、清理、贮藏、变基、切换分支、删除本地工作、推送、安装 macOS 更新或重启。
• 软件包更新前，先为角色关键服务创建快照。除非获得明确授权，否则不要重启 OpenClaw 网关或其他服务；之后使用相应服务所属的 skill 验证。
• 为每台主机保留操作日志。无法连接的主机应标记为待处理，不得标记为当前。

执行顺序

1. 确定主机的 full 或 worker 配置文件，采集观测到的清单，并运行软件包所有权预检。
2. 使用现有 Git/工具链同步符合条件的仓库。
3. 在每台符合条件且可连接的主机上更新 Homebrew 和全局 npm 软件包，无论是否有活跃 Agent/服务。
4. 验证每台主机所用的 macOS 稳定版/测试版轨道。
5. 通过 $xcode-sync 同步 Xcode。
6. 仅在明确要求本次运行清空废纸篓时才清空；执行已批准的软件包清理。
7. 重新审计磁盘、工具、软件包所有权、仓库、内存和角色关键服务。

预检

记录主机名、硬件 UUID、macOS、架构、运行时间、Tailscale 状态、所选 Xcode、可用字节数/百分比、废纸篓大小、Homebrew 前缀/版本、Node/npm 版本、正在运行的 Brew 服务、活跃的编码 Agent 进程，以及常驻内存异常值：

node skills/fleet-maintenance/scripts/fleet-profile.mjs collect
skills/fleet-maintenance/scripts/host-health-audit.sh 30
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'node --input-type=module - collect' \
  < skills/fleet-maintenance/scripts/fleet-profile.mjs
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s -- 30' \
  < skills/fleet-maintenance/scripts/host-health-audit.sh

报告每个常驻内存超过 30 GiB 的进程。不要仅因虚拟内存大小发出警报，不要合计相关进程，也不要自动终止进程。记录 PID、常驻内存 GiB、用户、可执行文件、角色，以及在第二次采样时内存是否仍高于阈值。

同时依据绝对容量和相对容量对启动磁盘空间分类：

• 健康：至少剩余 100 GiB 且可用空间占比为 15%
• 警告：剩余 50–100 GiB 或可用空间占比为 10–15%
• 严重：剩余少于 50 GiB 或可用空间占比低于 10%

警告或严重时，不要开始扩展 Xcode。未经明确批准，绝不要删除废纸篓、已被软件包管理器取代的构件，或 $xcode-sync 管理的 Xcode 路径以外的内容。

仓库同步

在每台主机上运行只读候选项审计：

skills/fleet-maintenance/scripts/repo-sync-audit.sh ~/Projects 3
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s -- "$HOME/Projects" 3' \
  < skills/fleet-maintenance/scripts/repo-sync-audit.sh

使用捆绑的更新程序应用审计通过的策略。它会重新检查安全性，以非交互方式获取更新，快进更新干净或无冲突的脏工作树，并隔离拒绝操作：

skills/fleet-maintenance/scripts/repo-sync-update.sh ~/Projects 3
ssh -o RequestTTY=no -o RemoteCommand=none HOST \
  '"$HOME/Projects/agent-scripts/skills/fleet-maintenance/scripts/repo-sync-update.sh" "$HOME/Projects" 3'

仅处理标记为 candidate 的行。立即在执行更改前重新检查分支、上游、Git 锁和活动进程的 cwd，然后：

git -C "$repo" fetch --prune
git -C "$repo" rev-list --left-right --count HEAD...@{upstream}

以非交互方式运行获取操作，并为每次操作设置时限（例如五分钟）。超时、身份验证失败或网络故障时，终止该获取操作，将仓库标记为待处理，然后继续。绝不能让某个过时或私有镜像阻塞主机、改写其远程地址，或在整个设备群维护期间提示输入凭据。

将计数解释为 ahead behind：

• 0 0：已是最新；无需操作。
• 0 N：检查 git log --oneline HEAD..@{upstream} 和 git diff --stat HEAD..@{upstream}。记录 HEAD 和工作树状态。运行 git merge --ff-only --no-autostash --no-overwrite-ignore @{upstream}。干净的工作树应当能够前进。脏工作树仅在 Git 能够保留所有本地更改且不发生重叠时才能前进；Git 拒绝时，标记为 skip-local-overlap，不要将其视为需要修复的错误。成功后，要求没有未合并条目、预期的上游提交位于 HEAD，并且之前的所有本地修改仍然存在。被拒绝后，要求 HEAD 未变、没有未合并条目，且工作树状态未变。
• N 0 或 N M：检查本地提交的主题和作者，以及 git diff --stat @{upstream}...HEAD；说明可能的意图并上报。绝不推送或改写历史。
• 已分离／无上游／获取失败：了解远程地址、分支、近期提交和工作树状态；上报并提供最精简且有用的决策信息。

不要推断过时的本地检出应与同级检出保持一致。每个可见检出都由用户管理。

绝不使用 pull 或 merge 解决冲突。绝不传入 --autostash、创建 stash、丢弃更改或暂存文件。非快进更新、检出覆盖警告、合并冲突或安全快照发生变化时，仅停止处理该仓库；继续执行设备群检查。

Homebrew

仅在 Homebrew 不存在时跳过。正在运行的 Agent／服务不会阻止软件包变更：

先将主机解析后的配置文件渲染为临时 Brewfile，然后运行 brew bundle check --verbose --file FILE。检查缺失的条目。brew bundle install --file FILE 可以安装或升级已声明的依赖项。绝不运行 brew bundle cleanup --force；在默认的 minimum 策略下，允许存在额外条目。只能通过明确获批的清理操作移除条目。

Homebrew 6 可能会拒绝未受信任的第三方 formula。如果发生这种情况，请确认每个 formula 已在解析后的设备群配置文件中声明，然后使用 brew trust --formula ... 仅信任这些确切的 formula 名称。绝不信任整个 tap，也绝不信任仅从远程 tap 中发现的 formula。使用 brew trust --json v1 记录最终信任列表，并继续使用同一个生成的 Brewfile。

brew update
brew outdated --json=v2
brew upgrade
brew services list
brew doctor

将 brew doctor 视为建议，不要盲目采纳其建议。比较操作前后的服务状态。成功验证后使用 brew cleanup --prune=30；仅在磁盘空间紧张且明确获批时，才使用更激进的清理方式。

如果升级替换了活动 Agent／服务所用的 Node、Git、Codex 或其他可执行文件，请接受后续导入或子进程可能会观察到新文件，并报告此风险。允许 Homebrew 以受控方式退出并重新打开 cask GUI 应用（可能会终止会话）；不要手动重启服务、修改 tap 或自动卸载软件包。

软件包归属

在对软件包进行更改前后运行 scripts/host-health-audit.sh。调查其中列出的归属候选项，以及重复的 launchd 标签/监听器、可执行文件版本不一致，以及 Homebrew formulae/casks、全局 npm、独立应用和应用捆绑 CLI 之间的冲突。

对于每个候选项，核实可执行文件的真实路径、软件包收据、服务定义、监听器、运行中的进程、依赖项、版本和预期主机角色。优先确定唯一的规范归属。只有在替代项运行正常、没有已安装软件包依赖该项，且当前请求授权修复时，才停用或卸载冗余归属项。切勿仅凭名称相同就推断存在冲突；formula/应用组合可能是有意配置的。

全局 npm 软件包

“更新 npm”指更新通过注册表安装的顶层全局软件包，而非项目依赖。切勿在此处更改代码库的 package.json 或锁文件。

1. 记录 node --version、npm --version、npm prefix -g 和 npm ls -g --depth=0 --json。
2. 运行 npm outdated -g --depth=0 --json；其非零退出状态可能表示存在可用更新。
3. 将每个注册表软件包更新到 name@latest。跳过链接、文件、Git、捆绑及归属不明确的软件包，并报告这些项。
4. 由其归属方更新 npm 本身：Homebrew 负责更新 Homebrew 安装的 Node/npm；仅在 npm 为自行管理的安装时，才使用 npm install -g npm@latest。验证更新后的 npm --version。
5. 重新盘点并对已更新的全局 CLI 进行冒烟测试。仅当私有软件包确实需要注册表身份验证时，才使用 $npm 和 $one-password；切勿暴露 npm 凭据。

即使全局软件包当前为正在运行的编码 Agent 或服务提供支持，也应执行主要版本更新。接受新旧文件混杂的风险；不要重启进程。单独对新安装的 CLI 进行冒烟测试，并报告失败或待重启事项。

macOS 维护路线

记录 sw_vers 产品版本/构建版本及当前 beta 种子计划注册状态。从当前权威 Apple 来源确认最新稳定版和当前 beta 构建版本；不要硬编码版本，也不要仅凭版本号推断维护路线。使用 softwareupdate --list 确认主机在其已配置的维护路线下实际收到的更新。

将每台 Mac 分类为最新、可更新、维护路线不明确、不受支持或不可达。保留其已配置的稳定版/beta 维护路线。常规维护不会切换维护路线、安装 macOS 更新或重启：准备好准确的更新，并在确认没有活跃的 Agent/服务且备份和磁盘状态充足后，申请维护时段。

Xcode

调用 $xcode-sync；不要重复实现其安装逻辑。从当前权威来源确认最新稳定版/beta/RC 版本，不要硬编码版本。在维护此处定义的规范稳定版/预发行版槽位及上一主版本保留策略时，保留每台主机所选的稳定版或预发行版维护路线。

验证产品构建版本、签名、首次启动状态、选择项、主机兼容性和可用空间。分别报告不受支持和不可达的 Mac。

模拟器整理是全机群必须满足的不变量，不是可选的磁盘清理。对每台可达的 Mac 运行 $xcode-sync 模拟器整理审计。没有 Xcode/simctl 的主机为“不适用”；装有 Xcode 的主机只有在 Apple 报告没有过时或不可用的运行时映像，且没有绑定到不可用运行时的设备时，才算最新。仅在检查是否有活跃的 Xcode 工作后才进行修复；规范操作会在模拟器设备处于启动状态时拒绝执行。

废纸篓和磁盘

每次运行都测量废纸篓大小。除非当前请求明确要求清空废纸篓，否则只读。获得同意后，仅在解析并验证路径后，清空当前用户主卷上的废纸篓：

trash="$HOME/.Trash"
home_real=$(cd "$HOME" && pwd -P)
trash_real=$(cd "$trash" && pwd -P)
if [[ "$trash_real" != "$home_real/.Trash" ]]; then
  printf 'refusing unexpected Trash path: %s\n' "$trash_real" >&2
  exit 2
fi
find "$trash_real" -mindepth 1 -maxdepth 1 -exec rm -rf {} +

切勿清空其他用户的废纸篓或外部卷宗上的废纸篓。之后重新检查磁盘容量；如果增长原因不明，应升级处理，而不要大范围删除缓存。

基线健康检查

在报告中包含以下只读检查；变更需要另行授权：

• 可用的 macOS/安全更新，以及是否建议重启
• 通过 mas outdated 检查 Mac App Store 应用的更新情况（仅当已安装 mas 时）
• 最近一次成功的 Time Machine 备份（仅当已配置时）
• SMART/存储警告，以及 diskutil 可获取的 APFS 卷健康信号
• 运行时间、时钟同步状态，以及笔记本电脑的电池健康状况/循环次数
• Tailscale 可达性/版本差异
• 失败的 Brew 服务，以及特定角色的 LaunchAgents/守护进程
• FileVault、防火墙、Gatekeeper 和 SIP 状态差异
• Developer ID 证书和重要 SSH 凭据的到期日期，绝不显示机密值

有用的可选维护项目：过期的软件包缓存/日志、废弃的容器/VM、未由 CoreSimulator 管理的旧设备支持文件、孤立的启动代理，以及占用大量空间的 Downloads。先审计；仅在范围明确授权后删除。

完成

返回一份主机矩阵，包含：可达性、Agent CLI 安装/认证/实时测试状态、Octopool shim/登录/池健康状态、Agent 技能链接状态、全局 Git 忽略状态、活跃/延后原因、磁盘使用情况（操作前/后）、清空 Trash 释放的空间、Brew/npm 变更、已拉取/最新/跳过/升级处理的仓库、Xcode 稳定版/预发布版构建及选定的轨道、备份/更新/服务警告，以及尚待用户决定的事项。