set-up-machine

设置机器

从 Harnesses 列出的来源，设置每个选定的 harness 和环境。将每个选定工具安装或更新到最新可用版本。再次运行此技能即为审计：检查配置和时效性，然后提出所需的更新。

来源

• 规则表，rules.json。
• 工作站仓库，<workstation-repo>，通过指针 ~/.config/agents/source.md 查找，该文件记录了仓库及其克隆位置。以下文件均为可选：
  • setup/instructions.md：工作约定、术语表、各工具承担的角色，以及个人工作流；
  • setup/permissions.json：个人权限，各 harness 随身携带的条目，与规则表中的条目并列；
  • setup/installs.json：每台机器都要安装的技能、插件和命令；
  • setup/harnesses.json：各 harness 的指令和声明配置所在位置。每个 harness 都可以有声明配置，例如其默认模型。

输出

• 共享全局指令文件，~/.config/agents/AGENTS.md，每个 harness 都会读取；其中的个人部分来自 setup/instructions.md。
• 对于 setup/harnesses.json 中指定了 instructions 文件的 harness，其Harness 指令：Cursor 的 ~/.cursor/rules/harness-instructions.mdc 和 Claude Code 的 ~/.claude/rules/harness-instructions.md，如 references/workstation.md > “Harness instructions file” 所述。
• 各 harness 的权限条目，来自规则表和个人权限。
• 工具调用前钩子，scripts/pre_tool_hook.py，在每次工具调用前运行。
• 指针，当其缺失或未记录任何内容时。
• 各 harness 的声明配置，来自 setup/harnesses.json 为其指定的 config 文件：仅将该文件设置的键合并到 harness 自身的配置文件中，其余键均保留为用户设置；如 references/workstation.md > “Declared config” 所述。
• setup/installs.json 为此机器列出的技能和命令，以及其中指定的各 harness 的插件：每个条目对应插件设置区域、插件包或独立 MCP 服务。
• 关闭每个 harness 的记忆功能。

每次运行的规则

• 重现安装选择、配置和步骤，而非软件版本快照。使用最新稳定版，或通过仓库分发代码的最新默认分支。此规则适用于 harness、技能、插件、软件包和命令行工具。
• 将已安装版本和源提交记录为审计证据，而非未来安装目标。将历史引用和依赖锁定文件与机器设置选择分开。
• 在判定安装已是最新状态前，检查当前上游来源。声明内容匹配或可执行文件已存在，只能证明其存在。无法检查时效性的情况应报告为 gap。
• 保留规则表未生成的所有条目，不作改动：这些条目属于用户。
• Harness 格式会变化：写入前检查 harness 引用链接的文档。如有差异，遵循文档并在报告中说明。

参数

• <skills-repo>：用户自己的 GitHub 技能仓库，格式为 owner/repo。仅当工作站仓库没有 setup/installs.json 时才安装。
• <workstation-repo>：用户用于个人 Agent 设置的仓库，通常为私有仓库，格式为 owner/repo。
• <path-to-workstation-repo>：该仓库的克隆位置，例如 ~/code/agent-setup。
• <session-host>：Agent 会话运行的位置，例如 herdr。实时检查会在此处启动每个 harness 的会话。

步骤

1. 检查。

   • **Harness 和工具：**查找每个选定项，将其已安装版本与最新源版本比较，并阅读其当前文档。保留其安装渠道。
   • **Harness 参考文档：**逐一阅读，然后读取其所需的非机密配置字段。不要读取凭据、身份验证存储和运行时状态。按照每个 harness 的参考文档检查其可选的 config。
   • **共享文件和指针：**读取两者。如果指针指向某个工作站仓库，则读取 references/workstation.md，然后读取 <path-to-workstation-repo> 中的 setup/instructions.md、setup/permissions.json、setup/installs.json 和 setup/harnesses.json，再读取 setup/harnesses.json 指向的每个文件。
   • **Codex 和 Pi：**在整个设置和验证过程中，使用一个解析后的 Codex 配置目录，以及一个解析后的 Pi Agent 文件夹。
   • **指针缺失时：**读取 references/workstation.md，然后向用户询问一次 <workstation-repo> 和 <path-to-workstation-repo>，或询问他们是否没有工作站仓库。diff 会写入指针，包括记录“none”的情况，因此下次运行时无需再询问。
   • **指针记录没有工作站仓库时：**按照 references/workstation.md 中无工作站仓库时的说明设置机器；如果用户现在指定了一个工作站仓库，则按照其中重写指针的说明操作。
   • **机器为远程或无头机器（例如 VPS）时：**先阅读 references/remote-machine.md。
   • **Harness 为 Grok Bot 时：**其指令应写入记忆，而不是文件。应用、协调和审计时，遵循 references/grok-bot/desktop.md > 'Instructions'。
   • **尝试更改但不触碰真实机器时：**在项目的 .scratch/ 中针对 home 文件夹副本执行这些步骤，并使用 verify.py --home <copy> 检查。不要在那里启动任何 harness，因为它会读取真实登录信息。

2. 提出一个 diff，使每个 harness 符合规则表、共享文件的结构和个人部分、指针、关闭的记忆功能、已接入的 hook、每个 harness 声明的配置，以及安装项：setup/installs.json 为这台机器列出的每个技能和命令，且每个选定的安装都为最新。将 harness 升级和插件更新也包括在内，而不只是补齐缺失的安装。为找到的每个 harness 单独设一节，列出其参考文档指出的每个差异和 hook 的盲点。只要 diff 中包含全局指令文件，就阅读 references/global-instructions.md。

   根据 rules.json、个人权限、共享文件的结构和 harness 的参考文档，确定每个 harness 应包含哪些内容，并与机器当前内容进行比较。写出完整 diff：按 harness 和文件列出精确条目或统一 diff，并为每行标注：

   • added；tightened，新增了更严格且优先适用的条目；removed；updated，已安装的 harness、技能、插件或工具版本落后于其最新源版本；
   • present；hook 的 wired；匹配到某一行的 MCP 工具的 found；
   • stricter：机器上的规则比表中更严格，予以保留；extra：既不属于规则表也不属于个人权限，予以保留；ignored：setup/installs.json 有意不列入的已安装技能，予以保留，绝不安装或删除；gap：harness 无法表达的内容；none：没有此类功能；
   • 对每个由个人权限生成的条目标注 personal，并放在其状态标记旁，例如 added, personal 或 present, personal，以便用户区分这些条目与规则表中的条目，且不会误认为它们是 extra；
   • n/a 表示不适用：对于某项个人权限，如果此 harness 不具备其对应的工具，则标注 n/a 并说明原因：此处不会写入任何内容。 仅对记忆文件、某个 harness 自己的全局文件（其每一行已包含在共享文件中，因此会变成链接），以及本技能中指向旧脚本的接线使用 removed。被删除的条目（来自共享表格或个人文件）若仍然留存，则属于 extra，应由用户移除。
   • 当工作站仓库中有 setup/installs.json 时： diff 会为每个适用于此机器的条目写一行，为每个不适用的条目写一行 n/a，并说明原因。该文件就是完整清单：其中未列出的内容一律不安装。references/workstation.md 介绍了格式、检查项和命令。
   • 没有该文件，但有 <skills-repo> 值时： diff 会全局安装该仓库的技能：npx --yes skills add <owner>/<repo> -g -a codex -a claude-code -y；如果 ~/.claude/skills 是指向 ~/.agents/skills 的链接，则省略 -a claude-code。按照 references/workstation.md 中的说明，将已安装技能的哈希与源仓库最新的默认分支进行比较。仅凭锁定文件中存在该技能，不能证明它是最新版本。没有值时，则写一行 none。

3. 只询问一次，请求对整个 diff 的批准。之后如有更改，必须重新请求批准。

   • **当 diff 仅包含来自 setup/installs.json 的 added 和 updated 安装项时：**无需询问，直接写入，因为用户通过编写该清单已批准这些内容。

4. 备份 diff 会更改或移除的每个文件。写入任何文件之前，先将每个文件复制到 ~/.config/agents/backups/<UTC time as YYYYmmddTHHMMSSZ>/ 中，路径应相对于主目录，例如 .claude/settings.json。符号链接应以链接形式复制。

5. 写入已批准的确切 diff。先运行任何安装命令，例如 diff 要安装的技能命令。如果某条命令失败，停止后续写入，并报告失败前发生的更改。升级后检查配置和防护规则是否兼容；若检查失败，应报告问题，而不是将旧快照设为目标状态。对于 JSON 和 TOML 文件，只更改 diff 指定的键，其余内容保持不变。通过符号链接写入其目标文件。

6. 验证：运行 python3 <skill-folder>/scripts/verify.py，其中 <skill-folder> 是此技能的安装目录。该脚本需要 Python 3.9+，仅使用标准库，且不会写入任何内容。满足验证中的要求即为通过。随后再次检查，直到 diff 不再有任何变化：没有待处理的 added、updated、tightened 或 removed 行。报告备份目录、已接入的内容、缺口，以及更严格的条目和额外条目。

   验证器检查的是已持久化的配置，而不是上游版本。在报告所有安装项均为最新版本之前，必须完成 Inspect 中的版本新鲜度检查。

7. 实时检查每个 harness，具体步骤见 references/live-check.md。在 <session-host> 中启动每个 harness 的真实会话，使用其默认模型，在临时文件夹中向每个 harness 提供相同的探测内容，并检查磁盘和屏幕。验证器证明文件正确；实时检查证明每个 harness 会按预期使用这些文件。通过步骤 2 到 6 修复每项 FAIL，然后重新检查该 harness。验证器和实时检查均通过后，即完成运行。

   • **当 <session-host> 无法启动某个 harness 的会话时：**将该 harness 的实时检查列为 gap。

验证

先输出两行全局结果，然后输出一个表格，再为每个 FAIL 和 gap 单元格输出一行详细信息：

setup  ok    <owner>/<repo>: the shared file matches setup/instructions.md
rules  ok    38 rows and 2 personal permissions, 197 samples

harness      instructions  guardrails    sandbox       plugins       skills        config
Claude Code  ok            ok            n/a           ok            ok            ok
Cursor       FAIL          ok            ok            ok            ok            ok

FAIL  Cursor instructions: ~/.cursor/rules/global-instructions.mdc is stale; generate it again

• **setup：**指针和每个 setup/ 文件均可读取，并且共享文件包含 setup/instructions.md 生成的内容。如果指针表明没有工作站仓库，则为 n/a。
• **rules：**每条规则表行和个人权限的每个样例，都会从钩子获得该行对应的答案。
• **每个已存在的运行框架各占一行。**每个单元格的值为 ok、FAIL、gap（运行框架无法执行该项或检查无法识别），或 n/a（不适用）。各列说明：
  • instructions：运行框架会读取共享文件、在 setup/harnesses.json 中指定时读取其自身的说明，并且记忆功能已关闭；
  • guardrails：钩子已连接到已安装的脚本，并且在运行框架支持原生规则时，每项个人权限都有对应的原生条目；
  • sandbox：运行框架的沙盒和审批设置：Cursor 的运行模式，以及已声明 Codex 配置中的沙盒和审批键；
  • plugins：setup/installs.json 中为此运行框架列出的每个插件均已安装并启用；
  • skills：setup/installs.json 列出的每项技能都位于此运行框架读取技能的文件夹中；
  • config：运行框架已声明配置中的每个键，在运行框架的配置文件中都有相同的值；未声明配置时为 n/a。这不属于 setup 项：默认模型不属于上述五项中的任何一项。

没有任何行或单元格为 FAIL 时，运行即通过；验证器随后以 0 退出。报告每一条 gap 行。每个运行框架参考文档中的“Verification”部分都会说明其对应行检查的内容。

规则表

rules.json 按含义保存每条全局规则一次，而不是以任何运行框架的格式保存。每行的各个字段、每种 match 类型及其拼写都见 references/rule-table.md。每份运行框架参考文档都会将一行规则转换为该运行框架的条目。钩子和 verify.py 通过 scripts/setupmachine/rules.py 读取相同的规则行；该脚本会拒绝格式错误的行。工作站仓库的 setup/permissions.json 以相同格式保存个人权限；正如 references/workstation.md > setup/permissions.json 所述，每个运行框架、钩子和 verify.py 都会将这些权限与规则表中的权限合并使用。

工具调用前钩子

scripts/pre_tool_hook.py 是每个运行框架在每次工具调用前运行的钩子。它需要 Python 3.9+，且仅使用标准库。它读取 rules.json，并通过指针读取个人权限，然后检查调用：

• deny 规则：它会按照 shell 执行命令的方式读取命令，并检查文件工具、重定向和 MCP 工具。它会拒绝调用，并针对每个被拒绝的部分，指出相应规则的原因和说明。
• allow-and-report 规则：每次调用都会写入一行 JSON 到 <report-folder>/<date>.jsonl，且仅用户可读取；具体权限由运行框架决定。
• ask 规则：由运行框架的原生 ask 条目负责发起询问。如果调用显示没有人会询问用户，则会拒绝带有 approver: "user" 的规则：Claude Code 处于 auto、dontAsk 或 bypassPermissions 模式时，Codex 的审批策略为 never 时，以及 Cursor 和 opencode 下的所有调用，因为它们无法保证会显示提示；详情见各自的参考文档。Cursor 完全没有 ask 列表，因此钩子会拒绝所有 ask 规则，无论是否设置了 approver。Pi 也没有 ask 列表，但其扩展可以询问：有 UI 时，钩子会列出 ask 规则，扩展会在 Pi 对话框中询问用户；没有 UI 时，钩子会拒绝所有 ask 规则，详情见 references/pi/cli.md > “Hook wiring”。
• allow 规则：钩子不作处理；运行框架的原生 allow 条目会允许调用在不显示提示的情况下运行。

个人权限文件格式错误时，规则表中的规则仍然有效：钩子会跳过个人权限，而 verify.py 会报告该文件。

接线

每个运行环境参考文档都用 <script> 代替脚本路径来展示接线方式。请将其替换为已安装技能中 scripts/pre_tool_hook.py 的绝对路径，路径应位于 ~/.agents/skills 或 ~/.claude/skills 下，绝不能位于可能被删除的检出目录或工作树中。如果没有已安装的副本，请注明这一缺失项。若脚本位于其他位置，verify.py 会判定接线失败。

接线采用失败开放模式，写作 [ -f <script> ] && … || true，或采用运行环境参考文档给出的形式：如果脚本不存在，每次调用都会继续通过原生入口执行。没有这段接线时，python3 会因脚本缺失而以状态码 2 退出，从而阻止所有调用。Pi 是例外：它没有底层原生入口，因此其扩展采用失败关闭模式，会拒绝每个无法由钩子检查的调用，具体说明见 references/pi/cli.md > “Hook wiring”。

<report-folder> 是 ~/.local/state/agents/reports，或 ~/.config/agents/hook.json 中的 report_dir。

限制

每次审计都必须列出以下限制：

• 脚本文件或其他解释器中的命令（python -c）；
• 由变量构造的命令（$cmd -rf x）；
• 在其他位置定义的别名或函数；
• 缩写的长选项（--recur）；
• 通过 refspec 强制推送（git push origin +main）；
• 由 shell 展开的通配符（cat .env*）；
• 自动审查器（例如 Codex 的 auto_review）回答 approver: "user" 行的情况，因为调用的负载不会显示审查者；
• 每一行自身的 gap。

运行环境

本技能设置的运行环境和环境配置清单。setup/harnesses.json、installs.json、verify.py --harness 和钩子的 --harness 使用 id；--env 和 setup/harnesses.json 中的 environments 使用环境配置。用户使用哪些配置取决于工作站仓库。

运行环境（id）	环境配置	参考文档
Claude Code（claude-code）	cli、desktop、cloud	查看 claude-code/index.md，了解 CLI 与桌面应用的共用配置；然后查看 cli.md、desktop.md、cloud.md
Codex（codex）	cli、desktop	查看 codex/index.md 了解共用配置，然后查看 cli.md 或 desktop.md
Cursor（cursor）	cli、desktop、cloud	查看 cursor/index.md，了解 CLI 与桌面应用的共用配置；然后查看 cli.md、desktop.md、cloud.md
Grok Bot（grok-bot）	desktop	grok-bot/desktop.md：指令存储在记忆中；权限、连接器、密钥和例程存储在应用中
opencode（opencode）	cli	opencode/cli.md
Pi（pi）	cli	pi/cli.md：钩子的扩展是唯一的执行机制

具有多个环境配置的运行环境，其文件为 references/<harness>/<env>.md 和 scripts/setupmachine/harnesses/<harness>/<env>.py。只有一个环境配置的运行环境，其文件为 references/<harness>.md 和一个模块。若要添加运行环境或环境配置，请按此处的方式添加一行，具体说明见 docs/design/set-up-machine.md > “Extensibility”。

参考资料

• references/global-instructions.md：共享文件的结构、角色表、协作约定和术语表、个人工作流的定义、迁移 harness 自身文件的方式，以及不启用记忆的原因。
• references/rule-table.md：规则行的字段、match 类型，以及 harness 需要的拼写形式。
• references/workstation.md：此技能从 workstation 仓库读取的内容：指针、setup/ 文件、setup/harnesses.json 指向的文件及其格式；如何根据这些文件生成共享文件中的个人部分和个人权限；安装列表；以及未配置安装时的运行方式。
• references/live-check.md：启动每个 harness 的真实会话、探测，以及读取其操作记录。
• references/remote-machine.md：在任意远程或无头机器上运行 Agent：不使用浏览器登录、每台机器的设置、保持会话运行，以及限制被误导的 Agent。
  • references/new-remote-machine.md：为全新机器准备基础环境：以 root 用户身份与用户一起完成，从密钥访问、专用用户、仅密钥 SSH、防火墙、更新、交换空间和 docker 组，到会话主机集成、git 凭据、通过 SSH 配置 PATH，以及无头浏览器。
• 每种 harness 环境各有一份参考资料，找到的每种环境都要阅读：Harnesses 表格中列出了它们。每页都包含相同的标题：存在检测、指令、护栏、沙盒、插件、技能、配置、钩子接线、限制、验证；页面不会重复其 harness 的 index.md 已涵盖的内容。如果页面中的事实经过版本检查或测试验证，末尾会附上 Notes，记录验证历史，确保上方各节只陈述当前事实。

脚本

• scripts/pre_tool_hook.py：每个 harness 在每次调用工具前都会调用的前置工具钩子。
• scripts/cloud_bootstrap.py：从 Claude Code 云环境的设置脚本运行；它会为 Agent 提供从 workstation 仓库设置会话的步骤，具体说明见 references/claude-code/cloud.md > 'Bootstrap'。
• scripts/verify.py：上述检查。它不会写入任何内容。
  • --home <folder>：检查 home 文件夹的副本；检测 harness 时只根据其文件夹判断，不检查 PATH 中的 CLI。
  • --grok-bot-rules：将规则表和个人权限打印为 Grok Bot 的 Auto-review 规则，具体说明见 references/grok-bot/desktop.md > 'Guardrails'。
  • --harness <harness> [--env <env>]：仅保留一个 harness 的规则行，或一个环境的规则行，例如 --harness cursor --env cloud。
  • --codex-trust-hash '<command>'：打印 Codex 对钩子命令所需的 trusted_hash，具体说明见 references/codex/index.md > 'Hook wiring'。
• scripts/setupmachine/：两个脚本共同使用的模块。harnesses/__init__.py 列出 ALL 中的所有环境。一个 harness 是一个包 harnesses/<harness>/，每种环境各有一个模块，共享代码位于其 __init__.py 中。
• references/opencode/opencode-plugin.js：调用钩子的 opencode 插件。
• references/pi/pi-extension.ts：调用钩子并向用户询问 ask 规则行的 Pi 扩展。