set-up-machine

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Set up machine

配置机器

Make every coding-agent harness on the machine (Claude Code, Codex, opencode, Cursor's IDE and CLI) match three sources: the rule table,

rules.json

, which holds each global rule once as what it covers; the shared global instructions file,

~/.config/agents/AGENTS.md

, which every harness reads; and the user's workstation repo, named by the pointer

~/.config/agents/source.md

, from which the shared file's personal parts are generated (which tool fills each role, and the personal workflow lines) and the personal permissions, permission rows each harness carries alongside the rule table's. Codex also takes explicitly declared CLI defaults from that repository's

agents/codex.toml

, and every machine gets the skills and commands its

agents/installs.json

lists. Each harness also runs the pre-tool hook,

scripts/pre_tool_hook.py

, before every tool call, and keeps its memory off. Never remove or loosen an entry the table didn't produce: it's the user's. Harness formats change, so check the docs a harness reference links before writing; where they differ, follow the docs and name the difference in your report. Running the skill again is the audit: the same steps, ending with a diff that changes nothing.

让机器上的每个编码 Agent harness（Claude Code、Codex、opencode、Cursor 的 IDE 和 CLI）与三个来源保持一致：规则表

rules.json

，其中按规则所覆盖的含义只保存一次每条全局规则；共享全局指令文件

~/.config/agents/AGENTS.md

，每个 harness 都会读取它；以及用户的工作站仓库，由 pointer

~/.config/agents/source.md

指定。共享文件中的个人部分（每个角色由哪个 tool 填充，以及个人工作流行）和 personal permissions 均由此生成；每个 harness 会在规则表的权限行之外，携带个人 permissions 所定义的权限行。Codex 还会从该仓库的

agents/codex.toml

取得明确声明的 CLI 默认值；每台机器都会安装其

agents/installs.json

列出的 skills 和 commands。每个 harness 还会在每次 tool call 前运行 pre-tool hook

scripts/pre_tool_hook.py

，并保持 memory 关闭。绝不删除或放宽任何并非规则表生成的条目：它们属于用户。Harness 的格式会发生变化，因此写入前应检查各 harness reference 链接的文档；若文档存在差异，以文档为准，并在报告中说明差异。再次运行此 skill 即为 audit：执行相同步骤，最后得到一份没有任何变更的 diff。

Parameters

参数

```
<skills-repo>
```
: the user's own skills repo on GitHub, as
```
owner/repo
```
. Installed only when the workstation repo has no
```
agents/installs.json
```
.

```
<skills-repo>
```
：用户在 GitHub 上的个人 skills 仓库，格式为
```
owner/repo
```
。仅当工作站仓库没有
```
agents/installs.json
```
时才会安装。

Steps

步骤

Inspect. Find each harness on the machine, read its reference, then the non-secret configuration fields that reference needs. Leave credentials, authentication stores and runtime state unread. Read the shared file and the pointer too, and when the pointer names a workstation repo, read
```
references/workstation-repo.md
```
and the repository's
```
agents/instructions.md
```
,
```
agents/permissions.json
```
and
```
agents/installs.json
```
in its clone. For Codex, inspect the optional
```
agents/codex.toml
```
as its reference directs; use one resolved config home throughout setup and verification.
- When the pointer is missing: read
```
references/workstation-repo.md
```
  , then ask the user once which repository holds their personal setup and where it is cloned, or whether they have none. The diff writes the pointer, recording "none" too, so the next run doesn't ask.
- When the machine is remote or headless, such as a VPS: read
```
references/remote-machine.md
```
  first.
- When trying a change without touching the real machine: run the steps against a copy of the home folder in the project's
```
.scratch/
```
  , and check it with
```
verify.py --home <copy>
```
  . Start no harness there, since it would read the real login.
Propose one diff that brings each harness in line with the rule table, the shared file's shape and personal parts, the pointer, memory off, the hook wired, declared supported Codex defaults, and the installs: every skill and command
```
agents/installs.json
```
lists for this machine, each skill up to date. Give every harness found its own section, listing each gap its reference names and the hook's blind spots. Read
```
references/global-instructions.md
```
whenever a global instructions file is in the diff.
Work out what each harness should hold, from
```
rules.json
```
, the personal permissions, the shared file's shape and the harness's reference, and compare it with what the machine holds. Write the whole diff: per harness and file, the exact entries or a unified diff, each line marked:
- ```
added
```
  ,
```
tightened
```
  (a stricter entry added where it wins),
```
removed
```
  ,
```
updated
```
  (an installed skill behind its source);
- ```
present
```
  ,
```
wired
```
  (the hook),
```
found
```
  (the MCP tools a row matched);
- ```
stricter
```
  (the machine is stricter than the table: kept),
```
extra
```
  (neither the table's nor a personal permission's: kept),
```
ignored
```
  (an installed skill
```
agents/installs.json
```
  leaves out on purpose: kept, never installed or removed),
```
gap
```
  (what the harness can't express),
```
none
```
  (no such feature);
- ```
personal
```
  beside the mark of every entry a personal permission produced (
```
added, personal
```
  ;
```
present, personal
```
  ), so the user can tell those entries from the table's and never reads them as
```
extra
```
  ;
- ```
n/a
```
  (not applicable) for a personal permission whose tool this harness lacks, with why: nothing is written for it there.
Use
```
removed
```
only for memory files, a harness's own global file whose every line is already in the shared file (it becomes a link), and this skill's own wiring that points at an old script. An entry a dropped row, the table's or a personal one, left behind is
```
extra
```
, for the user to remove.
- When the workstation repo has
  agents/installs.json
  : the diff holds a line per entry that applies to this machine, and an
```
n/a
```
  line, with why, per entry that doesn't. The file is the whole list: install nothing it leaves out.
```
references/workstation-repo.md
```
  gives the format, the checks and the commands.
- Without the file, with a
  <skills-repo>
  value: the diff installs that repo's skills globally:
```
npx --yes skills add <owner>/<repo> -g -a codex -a claude-code -y
```
  , leaving out
```
-a claude-code
```
  when
```
~/.claude/skills
```
  is a link to
```
~/.agents/skills
```
  . It's
```
present
```
  once
```
~/.agents/.skill-lock.json
```
  records a skill from that source. With no value, it's a
```
none
```
  line.
Ask once for one approval of the whole diff. A change after that needs a new approval.
- When the diff holds only
  added
  and
  updated
  installs from
  agents/installs.json
  : write it without asking, since the user approved that list by writing it.
Back up every file the diff changes or removes. Before writing any file, copy each one into
```
~/.config/agents/backups/<UTC time as YYYYmmddTHHMMSSZ>/
```
, at its path relative to the home folder (
```
.claude/settings.json
```
). Copy a symlink as a link.
Write exactly the approved diff. Run any install command first, such as a skill the diff installs. If one fails, write nothing and report it. In JSON and TOML files, change only the keys the diff names and keep the rest. Write through a symlink to its target.
Verify with
```
scripts/verify.py
```
, then inspect again until the diff changes nothing: no
```
added
```
,
```
tightened
```
or
```
removed
```
line. Report the backup folder, what's wired, the gaps, and the stricter and extra entries. For Codex, distinguish persisted defaults from effective overrides and state how subsequent sessions pick up changes.
Run
```
python3 <this skill>/scripts/verify.py
```
(Python 3.9+, standard library only; it writes nothing). It passes when it prints
```
rules ok
```
, a
```
hook wired
```
line for every harness found, a
```
personal ok
```
or
```
personal none
```
line and no
```
personal FAIL
```
line, every
```
codex differs
```
line is a row codex.md says gets no rule, and declared Codex defaults match without a
```
config FAIL
```
line, or a
```
config n/a
```
line says Codex isn't installed. Report
```
config gap
```
and
```
config override
```
lines separately; they limit what the audit proves.

**检查。**在机器上查找每个 harness，阅读其 reference，然后阅读该 reference 所需的非机密配置字段。不要读取凭据、身份验证存储和运行时状态。还要读取共享文件与 pointer；当 pointer 指定某个工作站仓库时，在其 clone 中读取
```
references/workstation-repo.md
```
以及仓库的
```
agents/instructions.md
```
、
```
agents/permissions.json
```
和
```
agents/installs.json
```
。对于 Codex，按其 reference 的指引检查可选的
```
agents/codex.toml
```
；在设置和验证过程中始终使用同一个解析后的 config home。
- **pointer 缺失时：**读取
```
references/workstation-repo.md
```
  ，然后一次性询问用户：哪个仓库保存其个人设置、该仓库 clone 在哪里，或者是否没有这样的仓库。diff 会写入 pointer；即使答案为“none”也会记录下来，因此下次运行时不再询问。
- **机器是远程或无头环境，例如 VPS 时：**先读取
```
references/remote-machine.md
```
  。
- **需要在不触碰真实机器的情况下试用变更时：**针对项目
```
.scratch/
```
  中 home 文件夹的副本执行这些步骤，并用
```
verify.py --home <copy>
```
  检查。不要在那里启动任何 harness，否则它会读取真实登录信息。
**提出一份 diff。**让每个 harness 与规则表、共享文件的结构和个人部分、pointer、关闭 memory、hook 接线、已声明且受支持的 Codex 默认值以及 installs 保持一致：对于本机，纳入
```
agents/installs.json
```
列出的每个 skill 和 command，并确保每个 skill 均为最新版本。为找到的每个 harness 设置独立章节，列出其 reference 指出的每个 gap 以及 hook 的盲区。只要 diff 中包含全局指令文件，就读取
```
references/global-instructions.md
```
。
根据
```
rules.json
```
、个人 permissions、共享文件的结构和 harness 的 reference，确定每个 harness 应包含的内容，再与机器当前的内容进行比较。写出完整 diff：按 harness 和文件列出精确条目或 unified diff，每一行标记为：
- ```
added
```
  、
```
tightened
```
  （新增后成为更严格且优先生效的条目）、
```
removed
```
  、
```
updated
```
  （已安装的 skill 落后于其来源）；
- ```
present
```
  、
```
wired
```
  （hook）、
```
found
```
  （某一行匹配到的 MCP tools）；
- ```
stricter
```
  （机器比规则表更严格：保留）、
```
extra
```
  （既非规则表生成，也非个人 permission 生成：保留）、
```
ignored
```
  （被
```
agents/installs.json
```
  有意排除的已安装 skill：保留，绝不由该列表安装或删除）、
```
gap
```
  （harness 无法表达的内容）、
```
none
```
  （无此功能）；
- ```
personal
```
  紧挨着由个人 permission 生成的每个条目的标记（
```
added, personal
```
  ；
```
present, personal
```
  ），让用户能够区分这些条目与规则表生成的条目，而不会将它们误认为
```
extra
```
  ；
- ```
n/a
```
  （不适用），用于该 harness 缺少相应 tool 的个人 permission，并说明原因：因此不在其中写入任何内容。
仅在以下情况使用
```
removed
```
：memory 文件；某个 harness 自己的全局文件，且其中每一行都已存在于共享文件中（该文件将改为链接）；以及此 skill 自身指向旧脚本的接线。某个已删除行——无论是规则表中的行还是个人 permission 中的行——遗留下来的条目属于
```
extra
```
，由用户决定是否删除。
- **工作站仓库包含
```
agents/installs.json
```
  时：**diff 对每个适用于本机的条目保留一行，对每个不适用的条目保留一行
```
n/a
```
  并说明原因。该文件是完整列表：其中排除的内容一律不安装。
```
references/workstation-repo.md
```
  给出格式、检查项和命令。
- **不含该文件，但提供了
```
<skills-repo>
```
  值时：**diff 会全局安装该仓库的 skills：
```
npx --yes skills add <owner>/<repo> -g -a codex -a claude-code -y
```
  ；当
```
~/.claude/skills
```
  是指向
```
~/.agents/skills
```
  的链接时，省略
```
-a claude-code
```
  。一旦
```
~/.agents/.skill-lock.json
```
  记录了来自该来源的 skill，该项即为
```
present
```
  。没有该值时，标记为
```
none
```
  。
**一次性请求批准。**就整份 diff 请求一次批准。批准后如需变更，必须重新批准。
- **当 diff 仅包含来自
```
agents/installs.json
```
  的
```
added
```
  和
```
updated
```
  installs 时：**无需询问，直接写入，因为用户编写该列表即已批准它。
**备份。**备份 diff 修改或删除的每个文件。写入任何文件之前，先将每个文件复制到
```
~/.config/agents/backups/<UTC time as YYYYmmddTHHMMSSZ>/
```
，并保持其相对于 home 文件夹的路径，例如
```
.claude/settings.json
```
。符号链接应按链接复制。
**写入。**精确写入已批准的 diff。先运行任何安装命令，例如 diff 要安装的 skill。如果某个命令失败，不写入任何内容并报告失败。在 JSON 和 TOML 文件中，只改 diff 指明的键，保留其余内容。符号链接应写入其目标。
**验证。**运行
```
scripts/verify.py
```
，然后再次检查，直至 diff 不再产生任何变更：没有
```
added
```
、
```
tightened
```
或
```
removed
```
行。报告备份目录、已接线的内容、gaps，以及更严格和额外的条目。对于 Codex，区分持久化默认值与有效 overrides，并说明后续 session 如何获取这些变更。
运行
```
python3 <this skill>/scripts/verify.py
```
（Python 3.9+，仅使用标准库；不会写入任何内容）。当它输出
```
rules ok
```
、每个找到的 harness 都有
```
hook wired
```
行、有
```
personal ok
```
或
```
personal none
```
行且没有
```
personal FAIL
```
行、每个
```
codex differs
```
行所指的规则都是 codex.md 标明不接收规则的行，并且声明的 Codex 默认值匹配且没有
```
config FAIL
```
行，或者
```
config n/a
```
行说明未安装 Codex 时，即表示通过。分别报告
```
config gap
```
和
```
config override
```
行；它们会限制 audit 所能证明的范围。

Rule table

规则表

rules.json

holds each global rule once, by meaning, not in any harness's form. Each harness reference turns a row into that harness's entries; the hook and

verify.py

read it through

scripts/setupmachine/rules.py

, which refuses a malformed row. A workstation repo's

agents/permissions.json

holds personal permissions in the same format, which every harness, the hook and

verify.py

take alongside the table's (

references/workstation-repo.md

rules.json

按含义保存每条全局规则一次，而不是按任何 harness 的形式保存。每个 harness 的 reference 负责将一行转换为该 harness 的条目；hook 和

verify.py

通过

scripts/setupmachine/rules.py

读取它，而后者会拒绝格式错误的行。工作站仓库的

agents/permissions.json

使用相同格式保存个人 permissions；每个 harness、hook 和

verify.py

都会将它与规则表一起纳入处理（

references/workstation-repo.md

）。

A row

一行

Field	Holds
`id`	a stable kebab-case name
`level`	`deny` , `ask` or `allow-and-report` ; a personal permission may also be `allow`
`summary`	what the rule covers, shown in rejection messages
`match`	what it covers, in one of the three kinds below
`reason`	why the rule exists
`instruction`	for `deny` , what the agent does instead: an alternative, or "Stop, say why, and give the user the exact command; never work around it."; for `ask` and `allow-and-report` , how to go ahead
`samples`	`covers` : calls the row must catch; `leaves` : near misses it must let through. A shell command for a command row, a path for a file row, a tool name for an MCP row. `verify.py` checks them against the hook
`gap`	optional: what no harness can catch for the row ( `echo $TOKEN` ); every audit names it
`approver`	optional, on an `ask` row only: `user` when each call needs the user's own approval, which an automatic reviewer's or a remembered answer's doesn't replace

字段	含义
`id`	稳定的 kebab-case 名称
`level`	`deny` 、 `ask` 或 `allow-and-report` ；个人 permission 还可以是 `allow`
`summary`	规则涵盖的内容，显示在拒绝消息中
`match`	规则涵盖的内容，采用下面三种类型之一
`reason`	规则存在的原因
`instruction`	对于 `deny` ，说明 Agent 应改做什么：提供替代方案，或“停止操作，说明原因，并向用户提供准确的命令；绝不绕过它。”；对于 `ask` 和 `allow-and-report` ，说明如何继续
`samples`	`covers` ：该行必须拦截的调用； `leaves` ：该行必须放过的近似情况。command 行使用 shell 命令，file 行使用路径，MCP 行使用 tool 名称。 `verify.py` 会通过 hook 检查这些样本
`gap`	可选：该行中任何 harness 都无法拦截的内容（ `echo $TOKEN` ）；每次 audit 都要指出它
`approver`	可选，仅用于 `ask` 行：当每次调用都需要用户本人批准时设为 `user` ，自动 reviewer 或已记住的回答都不能替代用户本人批准

match

kinds

match

类型

match

object's keys say which kind it is:

Command:
```
program
```
, a bare name (
```
rm
```
) or a list of them, and optionally:
- ```
subcommands
```
  : alternative word lists after the program (
```
[["repo", "delete"], ["repo", "archive"]]
```
  );
- ```
flags
```
  : every flag group the command carries, each listing one flag's names without dashes, a one-letter name being the short flag (
```
["r", "R", "recursive"]
```
  );
- ```
operands
```
  : words right after the subcommand and flags (
```
["777"]
```
  ), or alternative word lists (
```
[["777"], ["a+rwx"]]
```
  );
- ```
any_operand
```
  : words any one of which may appear anywhere after the subcommand (
```
["main", "master"]
```
  );
- ```
arguments: "none"
```
  : the program with nothing after it (
```
env
```
  );
```
arguments: "flags"
```
  : with flags and nothing else (
```
declare -x
```
  );
- ```
files
```
  : globs one of its operands must match (
```
cat .env
```
  ), with an optional
```
except
```
  ;
- ```
variables
```
  : globs over the names of the variables an argument expands (
```
*TOKEN*
```
  covers
```
echo $API_TOKEN
```
  , not
```
echo '$API_TOKEN'
```
  ).
File:
```
paths
```
, globs relative to the project (
```
**/.env
```
), or starting
```
~/
```
or
```
/
```
;
```
access
```
,
```
read
```
or
```
write
```
; an optional
```
except
```
(
```
**/.env.example
```
). A
```
read
```
row covers writes too.
MCP tool:
```
server
```
and
```
tool
```
, case-insensitive regular expressions over the two parts of
```
mcp__<server>__<tool>
```
. Store the meaning (
```
mail
```
,
```
^(send|reply|forward)
```
), never one account's server ID, so the row matches on every machine and account.

一个

match

对象的键用于指明其类型：

Command：
```
program
```
，即一个裸名称（如
```
rm
```
）或一组名称，并可选包含：
- ```
subcommands
```
  ：位于 program 之后的备选单词列表（
```
[["repo", "delete"], ["repo", "archive"]]
```
  ）；
- ```
flags
```
  ：命令携带的每个 flag 组，每组列出一个 flag 的名称且不带短横线，单字母名称表示短 flag（
```
["r", "R", "recursive"]
```
  ）；
- ```
operands
```
  ：紧接在 subcommand 和 flags 之后的单词（
```
["777"]
```
  ），或备选单词列表（
```
[["777"], ["a+rwx"]]
```
  ）；
- ```
any_operand
```
  ：subcommand 之后任意位置都可能出现的单词（
```
["main", "master"]
```
  ）；
- ```
arguments: "none"
```
  ：program 之后没有任何内容（
```
env
```
  ）；
```
arguments: "flags"
```
  ：只有 flags，没有其他内容（
```
declare -x
```
  ）；
- ```
files
```
  ：某个 operand 必须匹配的 glob（
```
cat .env
```
  ），可附带
```
except
```
  ；
- ```
variables
```
  ：对参数所展开变量名称进行 glob 匹配（
```
*TOKEN*
```
  可覆盖
```
echo $API_TOKEN
```
  ，但不能覆盖
```
echo '$API_TOKEN'
```
  ）。
File：
```
paths
```
，相对于项目的 glob（
```
**/.env
```
），或以
```
~/
```
、
```
/
```
开头；
```
access
```
，即
```
read
```
或
```
write
```
；可选的
```
except
```
（
```
**/.env.example
```
）。
```
read
```
行也会覆盖写入操作。
MCP tool：
```
server
```
和
```
tool
```
，分别对
```
mcp__<server>__<tool>
```
的两个部分使用不区分大小写的正则表达式。保存含义（如
```
mail
```
、
```
^(send|reply|forward)
```
），而不要保存某个账户的 server ID，这样该行才能在每台机器和每个账户上匹配。

Spellings

拼写形式

A harness that matches a command's text catches only the spellings it lists, so give it one entry per way of writing a command row:

Programs: each program as typed, then as
```
/bin/<program>
```
and
```
/usr/bin/<program>
```
, except shell builtins (
```
.
```
,
```
source
```
,
```
set
```
,
```
export
```
,
```
declare
```
,
```
typeset
```
,
```
unset
```
,
```
eval
```
,
```
alias
```
), which have no path.
Flags: a one-letter name is a short flag (
```
-r
```
), a longer one a long flag (
```
--recursive
```
). Every order of the groups, every spelling in each group, as separate words; and, when every group has a one-letter name, the one-letter names clustered in every order (
```
-rf
```
,
```
-fr
```
,
```
-Rf
```
,
```
-fR
```
).
Order: program, then subcommand words, then flags, then operands (
```
git push --force
```
,
```
chmod -R 777
```
).
find
's options (
```
-delete
```
) are one-dash words written after the path, so no prefix entry catches them: a command row on
```
find
```
gets no native entry, a gap the hook covers on every harness.

Harness 只会拦截其明确列出的 command 文本，因此 command 行每一种写法都要提供单独条目：

**Programs：**每个 program 按用户输入的形式列出，然后是
```
/bin/<program>
```
和
```
/usr/bin/<program>
```
；但 shell builtins（
```
.
```
、
```
source
```
、
```
set
```
、
```
export
```
、
```
declare
```
、
```
typeset
```
、
```
unset
```
、
```
eval
```
、
```
alias
```
）没有路径。
**Flags：**单字母名称是短 flag（
```
-r
```
），较长的名称是长 flag（
```
--recursive
```
）。每种组排列顺序、每组中的每种拼写，都应作为独立单词列出；当每组都有一个单字母名称时，还要将单字母名称按每种顺序组合列出（
```
-rf
```
、
```
-fr
```
、
```
-Rf
```
、
```
-fR
```
）。
**顺序：**program、subcommand 单词、flags、operands（
```
git push --force
```
、
```
chmod -R 777
```
）。
find
的 options：（
```
-delete
```
）是写在路径之后的单短横线单词，因此任何带前缀的条目都无法拦截：
```
find
```
的 command 行没有原生条目，这个 gap 由 hook 在每个 harness 上覆盖。

Pre-tool hook

scripts/pre_tool_hook.py

(Python 3.9+, standard library only) is the hook every harness runs before each tool call. It reads

rules.json

, and the personal permissions through the pointer, and checks the call:

deny rows: it reads a command the way the shell runs it, and checks file tools, redirects and MCP tools too. It refuses the call, naming each refused part with its rule's reason and instruction.
allow-and-report rows: it writes one JSON line per call to
```
<report folder>/<date>.jsonl
```
, readable by the user alone; the harness's permissions decide.
ask rows: the harness's native ask entries do the asking. A row with
```
approver: "user"
```
is refused instead where the call shows that no one will ask the user: Claude Code in
```
auto
```
,
```
dontAsk
```
or
```
bypassPermissions
```
mode, Codex with approval policy
```
never
```
, and every call under Cursor and opencode, which can't promise a prompt (their references say why).
allow rows: it says nothing; the harness's native allow entries let the call run without a prompt.

A malformed personal file leaves the table's rows in force: the hook skips the personal permissions and

verify.py

reports the file.

scripts/pre_tool_hook.py

（Python 3.9+，仅使用标准库）是每个 harness 在每次 tool call 前运行的 hook。它读取

rules.json

，并通过 pointer 读取个人 permissions，然后检查调用：

**
```
deny
```
行：**它按照 shell 的执行方式读取 command，并检查 file tools、重定向和 MCP tools。它拒绝调用，并针对每个被拒绝的部分说明相应规则的原因和 instruction。
**
```
allow-and-report
```
行：**它会向
```
<report folder>/<date>.jsonl
```
为每次调用写入一行 JSON，仅用户可读；最终是否允许由 harness 的 permissions 决定。
**
```
ask
```
行：**由 harness 原生的 ask 条目负责询问。带有
```
approver: "user"
```
的行，在调用表明不会有人询问用户时会被直接拒绝：Claude Code 处于
```
auto
```
、
```
dontAsk
```
或
```
bypassPermissions
```
模式，Codex 的 approval policy 为
```
never
```
，以及 Cursor 和 opencode 下的每次调用；这些 harness 无法保证弹出提示（其 references 说明了原因）。
**
```
allow
```
行：**hook 不作任何提示；harness 原生的 allow 条目让调用无需提示即可运行。

个人权限文件格式错误时，规则表中的行仍然有效：hook 会跳过个人 permissions，并由

verify.py

报告该文件。

Wiring

接线

Each harness reference shows its wiring with

<script>

in place of the script's path. Replace it with the absolute path of

scripts/pre_tool_hook.py

in the installed skill (under

~/.agents/skills

~/.claude/skills

), never in a checkout or worktree, which can be deleted. If there is no installed copy, name the gap.

The wiring fails open (

[ -f <script> ] && … || true

, or the form a harness reference gives): if the script is gone, each call goes on under the native entries. Without it,

python3

would exit 2 on the missing script, which blocks every call.

The report folder is

~/.local/state/agents/reports

, or

report_dir

~/.config/agents/hook.json

每个 harness reference 都用

<script>

表示脚本路径。将其替换为已安装 skill 中

scripts/pre_tool_hook.py

的绝对路径（位于

~/.agents/skills

或

~/.claude/skills

下），绝不能指向 checkout 或 worktree，因为它们可能会被删除。如果没有安装副本，请指出该 gap。

接线采用 fail-open 行为（

[ -f <script> ] && … || true

，或 harness reference 给出的形式）：如果脚本消失，每次调用会依据原生条目继续执行。若没有

|| true

这样的 fail-open 兜底，脚本缺失时

python3

会以状态码 2 退出，从而阻止每次调用。

报告目录为

~/.local/state/agents/reports

，或

~/.config/agents/hook.json

中的

report_dir

。

What it can't see

无法看到的内容

Name these once in every audit:

a command inside a script file or another interpreter (
```
python -c
```
);
a command built from variables (
```
$cmd -rf x
```
);
an alias or function defined elsewhere;
an abbreviated long option (
```
--recur
```
);
a force push by refspec (
```
git push origin +main
```
);
a glob the shell expands (
```
cat .env*
```
);
an automatic reviewer, such as Codex's
```
auto_review
```
, answering an
```
approver: "user"
```
row, since the call's payload doesn't show the reviewer;
each row's own
```
gap
```
.

每次 audit 中都要指出以下盲区：

脚本文件内部的 command，或交给另一种解释器执行的 command（
```
python -c
```
）；
由变量拼出的 command（
```
$cmd -rf x
```
）；
在别处定义的 alias 或 function；
缩写的长 option（
```
--recur
```
）；
通过 refspec 执行的 force push（
```
git push origin +main
```
）；
由 shell 展开的 glob（
```
cat .env*
```
）；
自动 reviewer（例如 Codex 的
```
auto_review
```
）回答
```
approver: "user"
```
行，因为调用的 payload 不显示 reviewer；
每一行自身的
```
gap
```
。

References

参考文档

references/global-instructions.md: the shared file's shape, the roles table, what counts as personal workflow, moving a harness's own file, and why memory stays off.
references/rule-table.md: changing a row of the rule table, changing the hook's code and its tests, and adding a harness.
references/workstation-repo.md: the pointer, the workstation repo's layout, generating the shared file's personal parts from it, its personal permissions, and its installs list.
references/remote-machine.md: running agents on any remote or headless machine: signing in without a browser, per-machine settings, keeping sessions alive, and containing a misled agent.
- references/new-remote-machine.md: for a brand-new machine, first: the base it needs, done with the user as root, from key access, the dedicated user, keys-only SSH, the firewall, updates, swap and the docker group to the session host's integration, git credentials,
```
PATH
```
  over SSH and a headless browser.
One reference per harness, read for each harness found. Each says how the harness is found, where it keeps each setting, a row's native form with worked examples, the hook's wiring, and its gaps:
- references/claude-code.md: Claude Code.
- references/codex.md: Codex.
- references/opencode.md: opencode.
- references/cursor.md: Cursor's IDE and CLI.

references/global-instructions.md：共享文件的结构、角色表、哪些内容属于个人工作流、如何迁移 harness 自己的文件，以及 memory 始终关闭的原因。
references/rule-table.md：修改规则表中的一行、修改 hook 的代码及其测试，以及添加 harness。
references/workstation-repo.md：pointer、工作站仓库的布局、共享文件个人部分的生成方式、个人 permissions，以及 installs 列表。
references/remote-machine.md：在任意远程或无头机器上运行 agents：无需浏览器登录、每台机器的设置、保持 session 存活，以及控制被误导的 Agent。
- references/new-remote-machine.md：用于全新机器：首先完成机器所需的基础配置，由用户以 root 身份执行，依次包括密钥访问、专用用户、仅限密钥的 SSH、防火墙、系统更新、swap、用于 session host 集成的 docker group、Git 凭据、SSH 下的
```
PATH
```
  和无头浏览器。
每个 harness 都有一个 reference；针对找到的每个 harness 都要读取。每个 reference 说明如何发现该 harness、每项设置的存放位置、一行规则对应的原生形式及示例、hook 接线以及其 gaps：
- references/claude-code.md：Claude Code。
- references/codex.md：Codex。
- references/opencode.md：opencode。
- references/cursor.md：Cursor 的 IDE 和 CLI。

Scripts

scripts/verify.py: checks, without writing anything, that the rules work on this machine: each row's samples through the hook, and through Codex's own policy check; that the shared file carries the workstation repo's values; that Claude Code holds each personal permission's entries; and Codex defaults, installed support and override gaps at the resolved config home.
scripts/pre_tool_hook.py: the pre-tool hook every harness calls before each tool call.
references/opencode-plugin.js: the opencode plugin that calls the hook.

scripts/verify.py：在不写入任何内容的情况下，检查规则是否在本机生效：每行样本是否通过 hook 及 Codex 自身的 policy check；共享文件是否包含工作站仓库中的值；Claude Code 是否包含每条个人 permission 的条目；以及解析后的 config home 中的 Codex 默认值、已安装支持和 override gaps。
scripts/pre_tool_hook.py：每个 harness 在每次 tool call 前调用的 pre-tool hook。
references/opencode-plugin.js：调用该 hook 的 opencode 插件。

set-up-machine

Original

Translation

Set up machine

配置机器

Parameters

参数

Steps

步骤

Rule table

规则表

A row

一行

`match`
kinds

`match`
类型

Spellings

拼写形式

Pre-tool hook

Pre-tool hook

Wiring

接线

What it can't see

无法看到的内容

References

参考文档

Scripts

Scripts