om-setup-agent-harness

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Setup Agent Harness

配置 Agent Harness

Configure the optional
agentHarness
section without changing the existing PR pipeline skills. Preserve the rest of
.ai/agentic.config.json
, store no secrets, probe every selected adapter, and leave repository-owned setup changes staged but uncommitted.
在不更改现有 PR pipeline skills 的情况下,配置可选的
agentHarness
配置段。保留
.ai/agentic.config.json
的其余内容,不存储任何 secret,探测每个选中的 adapter,并将仓库所属的设置变更保持为已暂存但未提交状态。

Arguments

Arguments

  • --check
    (optional) — validate and probe the current configuration without writing.
  • --preset <cross-model-jury|custom>
    (optional) — start from the bundled jury or an empty custom registry; default
    cross-model-jury
    .
  • --defaults
    (optional) — enable the detected members of the bundled cross-model jury without asking questions.
  • --no-output-style
    (optional) — do not install the optional Claude output style.
  • --no-hooks
    (optional) — do not install the prevention hooks into
    .claude/hooks/
    and
    .claude/settings.json
    .
  • --check
    (可选)——验证并探测当前配置,不写入任何内容。
  • --preset <cross-model-jury|custom>
    (可选)——以内置 jury 或空白 custom registry 为起点;默认为
    cross-model-jury
    。
  • --defaults
    (可选)——无需询问,直接启用检测到的内置 cross-model jury 成员。
  • --no-output-style
    (可选)——不安装可选的 Claude output style。
  • --no-hooks
    (可选)——不向
    .claude/hooks/
    和
    .claude/settings.json
    安装 prevention hooks。

Workflow

Workflow

ALWAYS check first: Apply
.ai/skills/om-setup-agent-harness/SKILL.md
when present; safety rules still win.
  1. Agentic setup — follow
    references/agentic-setup.md
    before any action: load approved configuration, apply local extensions and shared rules, and preserve the untrusted-content boundary.
**始终先检查:**如果存在
.ai/skills/om-setup-agent-harness/SKILL.md
,则应用该文件;安全规则仍然优先。
  1. Agentic 设置——在任何操作之前,按照
    references/agentic-setup.md
    执行:加载已批准的配置,应用本地扩展和共享规则,并保持不可信内容边界。

1. Detect available adapters

1. 检测可用适配器

Read
references/provider-catalog.md
and start from the bundled jury in
references/configuration-template.json
: Codex, DeepSeek, Kimi, GLM, and MiMo. Detect Claude as the host. Use the harness
probe
operation to check executable versions and credential availability without printing or copying credentials. The built-in DeepSeek and OpenCode Zen adapters may check their official local auth-store entries internally; the setup agent never reads or displays the key.
When no bundled provider is detected, say so plainly and lead with the bring-your-own-reviewer path from the provider catalog: any OpenAI-compatible endpoint or any locally installed CLI can be bound as a reviewer through the generic adapters — the bundled jury is a default, not a requirement. The only fixed element is Claude as the host. A user with no external provider at all still has a working
standard
profile (fresh Claude review only); offer that explicitly instead of failing, but only after explaining what the multi-model profiles would have added, so choosing it is an informed decision rather than a silent default.
读取
references/provider-catalog.md
,并从
references/configuration-template.json
中内置的 jury 开始:Codex、DeepSeek、Kimi、GLM 和 MiMo。
将 Claude 检测为 host。使用 harness 的
probe
操作检查可执行文件版本和凭据可用性,但不得打印或复制凭据。 内置的 DeepSeek 和 OpenCode Zen adapter 可以在内部检查其官方本地 auth store 条目;setup agent 绝不读取或显示 key。
当未检测到任何内置 provider 时,应直截了当地说明,并首先介绍 provider catalog 中的自带 reviewer 路径:任何 OpenAI-compatible endpoint 或本地安装的 CLI 都可以通过 generic adapter 绑定为 reviewer——内置 jury 是默认值,而非必需项。唯一固定项是 Claude 作为 host。完全没有外部 provider 的用户仍可使用可正常工作的
standard
profile(仅使用全新的 Claude review);应明确提供此选项,而不是直接失败,但必须先说明 multi-model profile 会增加哪些能力,使用户能够知情选择,而不是被静默地设为默认值。

2. Select roles and policy

2. 选择角色和策略

Unless
--defaults
is set, ask which detected models should act as workers, reviewers, or both; which are required; the desired concurrency, timeout, and retry policy (attempts, backoff, timeout escalation); and whether to enable the
high-assurance
profile. Offer every bundled model independently, then offer “add custom model” using the generic contracts in the provider catalog. Require command adapters for workers. Keep HTTP and built-in subscription/API presets review-only. Accept a worker only when its provider or OS sandbox demonstrably disables network, remote/tracker writes, and Git ref writes; record that mechanism in
workerSecurity
. Use only runtime-recognized audited adapters; version 1 supports
codex-workspace-write-sandbox
. A prompt-only promise or arbitrary adapter declaration is insufficient.
除非设置了
--defaults
,否则询问哪些检测到的模型应充当 worker、reviewer 或两者;哪些是必需的;期望的并发数、超时和重试策略(尝试次数、backoff、超时升级);以及是否启用
high-assurance
profile。应独立提供每个内置模型,然后使用 provider catalog 中的 generic contract 提供“添加自定义模型”选项。worker 必须使用 command adapter。HTTP adapter 以及内置的 subscription/API preset 均仅限用于 review。
仅当 worker 的 provider 或 OS sandbox 可证明已禁用网络、远程/tracker 写入和 Git ref 写入时,才接受该 worker;将该机制记录在
workerSecurity
中。仅使用运行时认可且经过审计的 adapter;version 1 支持
codex-workspace-write-sandbox
。仅靠 prompt 承诺或任意声明 adapter 都不足够。

3. Write the additive configuration

3. 写入增量配置

Build an
agentHarness
object from
references/configuration-template.json
and the user's choices. Remove unselected bundled models from the active profiles; do not delete custom models. Keep the
multi*
profiles on
all-required
with
requiredReviewers
recalculated to exactly the selected reviewer set; use advisory mode only when no reviewer is selected at all. If
high-assurance
is enabled, require a worker plus enough reviewers outside its model family for the configured risk and verification rules; do not silently weaken those rules. Detect the current Codex model from non-secret CLI configuration, but keep the shipped compatible default when that model fails a smoke review. Preserve every existing top-level config value. Resolve the installed
om-harness
skill (its directory sits beside this skill's own install directory; when it is absent, stop and ask the user to install the collection with
om-harness
included), then run
node <om-harness>/scripts/harness.mjs configure
against the working-tree config. Show the exact diff before staging it. Keep portable team bindings in the repository object; put personal executable paths or endpoints in the user-local overlay named by
OM_AGENT_HARNESS_CONFIG
, and do not stage that overlay.
Keep every selected advisor in the profile reviewer list. Under the shipped
all-required
policy every selected reviewer must complete (the runtime retries failures automatically); selecting a reviewer is a commitment to hear from it, never a best-effort hint.
Write only satisfiable profiles. Keep
standard
always; include
optimized
,
multi-optimized
, and
high-assurance
only when an audited worker is bound, and
multi
/
multi-optimized
only when at least one reviewer is selected. A wrapper that later requests a profile this configuration does not define reroutes back here instead of running with an empty jury.
根据
references/configuration-template.json
和用户选择构建
agentHarness
对象。从 active profile 中移除未选中的内置模型;不要删除自定义模型。将
multi*
profile 保持为
all-required
,并将
requiredReviewers
重新计算为恰好等于选中的 reviewer 集合;只有在完全未选择 reviewer 时才使用 advisory mode。
如果启用了
high-assurance
,则按照已配置的风险和验证规则,要求提供一个 worker,以及其 model family 之外足够数量的 reviewer;绝不能静默削弱这些规则。从非机密 CLI 配置中检测当前 Codex model,但如果该 model 未通过 smoke review,则保留随附的兼容默认值。保留每个现有的顶层配置值。
解析已安装的
om-harness
skill(其目录位于本 skill 自身的安装目录旁边;如果不存在,则停止并要求用户安装包含
om-harness
的 collection),随后针对 working-tree config 运行
node <om-harness>/scripts/harness.mjs configure
。暂存前显示准确的 diff。
将可移植的团队绑定保留在 repository 对象中;将个人可执行文件路径或 endpoint 放在由
OM_AGENT_HARNESS_CONFIG
指定的 user-local overlay 中,并且不要暂存该 overlay。
将每个选中的 advisor 保留在 profile 的 reviewer 列表中。在随附的
all-required
policy 下,每个选中的 reviewer 都必须完成(runtime 会自动重试失败);选择 reviewer 意味着承诺听取其意见,绝不能只是尽力而为的建议。
仅写入可实际满足的 profile。始终保留
standard
;仅在绑定了经过审计的 worker 时才包含
optimized
、
multi-optimized
和
high-assurance
,并且仅在至少选择了一个 reviewer 时才包含
multi
/
multi-optimized
。如果 wrapper 后续请求此配置未定义的 profile,则应重新路由回此处,而不是使用空 jury 运行。

4. Validate and smoke-test

4. 验证和冒烟测试

Run
validate-config
, then
probe
for every selected profile. Run one harmless structured review per selected advisor using the complete installed
om-code-review
rubric so a valid binary but expired subscription is reported correctly. This is an adapter smoke test, not an operational bound council; the wrappers supply the required fresh Claude artifact and exact-subject packet. A required unavailable model or failed review policy is blocking; an optional unavailable model is reported as skipped with its concrete smoke-test reason. For
high-assurance
, require
validate-config
to accept its packet policy and probe its full worker/reviewer readiness. Do not run a real worker against repository files during setup.
运行
validate-config
,然后对每个选中的 profile 执行
probe
。使用完整安装的
om-code-review
rubric,为每个选中的 advisor 运行一次无害的结构化 review,以便正确报告 binary 有效但 subscription 已过期的情况。这是 adapter smoke test,而不是实际运行的绑定 council;wrapper 会提供所需的新鲜 Claude artifact 和针对确切 subject 的 packet。
如果必需的模型不可用或 review policy 失败,则应阻止执行;如果可选模型不可用,则报告为已跳过,并附上具体的 smoke-test 原因。
对于
high-assurance
,要求
validate-config
接受其 packet policy,并探测 worker/reviewer 的完整就绪状态。设置期间不要针对仓库文件运行真实的 worker。

5. Install the optional Claude output style

5. 安装可选的 Claude output style

Unless disabled, copy
assets/claude-review-output-style.md
to
.claude/output-styles/om-harness-review.md
. Never overwrite a locally edited copy silently; show a diff and ask whether to replace, merge, or keep it.
除非已禁用,否则将
assets/claude-review-output-style.md
复制到
.claude/output-styles/om-harness-review.md
。绝不能静默覆盖本地编辑过的副本;显示 diff,并询问是替换、合并还是保留。

6. Install the prevention hooks

6. 安装 prevention hooks

Offer to install the structural stop-before-PR and test-freeze guards (default yes). Copy
guard.mjs
,
block-push-and-pr.sh
, and
freeze-tests.sh
from the installed
om-harness
skill's
hooks/
directory to
.claude/hooks/om-harness/
, keep them executable, and merge the
PreToolUse
entries from the sibling
hooks-settings-snippet.json
into
.claude/settings.json
without disturbing existing hooks. These are the preventive layer of the stage-only contract: the Bash guard is inactive until
capture
starts a run in the current worktree and denies
git push
and PR creation until successful
stage
or explicit
end-run
ends it. Other linked worktrees and ordinary publication workflows remain usable. Keep both hook executable paths quoted so installation works in directories containing spaces. The Edit/Write/MultiEdit/NotebookEdit guard denies test-file edits while a
.om-freeze-tests
sentinel is present. Never overwrite locally edited hook files or settings silently; show a diff and ask.
询问是否安装 structural stop-before-PR 和 test-freeze guards(默认 yes)。从已安装的
om-harness
skill 的
hooks/
目录将
guard.mjs
、
block-push-and-pr.sh
和
freeze-tests.sh
复制到
.claude/hooks/om-harness/
,保持它们可执行,并将同级
hooks-settings-snippet.json
中的
PreToolUse
条目合并到
.claude/settings.json
中,同时不干扰现有 hooks。
这些是 stage-only 合同的预防层:Bash guard 在
capture
于当前 worktree 中启动运行之前不生效,并禁止
git push
和创建 PR,直到成功执行
stage
或显式执行
end-run
结束运行。其他 linked worktree 和普通发布工作流仍可使用。
两个 hook 可执行文件路径都必须加引号,以确保在包含空格的目录中也能正常安装。当存在
.om-freeze-tests
sentinel 时,Edit/Write/MultiEdit/NotebookEdit guard 会拒绝编辑测试文件。绝不能静默覆盖本地编辑过的 hook 文件或设置;显示 diff 并询问用户。

7. Stage and report

7. 暂存并报告

Stage only
.ai/agentic.config.json
, the output-style file when created, and the hook files plus
.claude/settings.json
when the hooks were installed. Never commit, push, or publish. Print the readiness table defined in
references/provider-catalog.md
, the configured profiles, skipped adapters, and the staged paths. With
--check
, write and stage nothing.
仅暂存
.ai/agentic.config.json
、创建时的 output-style 文件,以及安装 hooks 时的 hook 文件和
.claude/settings.json
。绝不 commit、push 或 publish。打印
references/provider-catalog.md
中定义的就绪表、已配置的 profiles、跳过的 adapters 和已暂存的路径。使用
--check
时,不写入也不暂存任何内容。

Rules

Rules

  • Shared communication, marker, label, and safety rules:
    references/rules.md
    . They always apply.
  • Keep Claude as host, conductor, and final reconciler.
  • Require the operational wrappers to prove a new Claude review context; never configure the conductor's current context as its replacement.
  • Keep
    delivery.mode
    fixed to
    stage-only
    .
  • Keep secrets out of repository and user-local JSON; store only environment-variable names.
  • Never replace existing pipeline config values that the user did not ask to change.
  • Never install a worker binding whose command has not been confirmed to edit only the current worktree.
  • Never commit, push, open a pull request, or mutate tracker state.
Hook support requires Bash and Node on macOS, Linux, or WSL. Native PowerShell hook wiring is unsupported. Document that limitation during setup and block a staged run when the host cannot enforce publication permissions.
  • 共享的沟通、marker、label 和安全规则:
    references/rules.md
    。这些规则始终适用。
  • 保持 Claude 担任 host、conductor 和最终 reconciler。
  • 要求 operational wrappers 证明新的 Claude review context;绝不能将 conductor 的当前 context 配置为其替代项。
  • 将
    delivery.mode
    固定为
    stage-only
    。
  • 将 secrets 排除在 repository 和 user-local JSON 之外;只存储环境变量名称。
  • 绝不替换用户未要求更改的现有 pipeline config 值。
  • 绝不要安装其 command 尚未被确认只能编辑当前 worktree 的 worker binding。
  • 绝不 commit、push、创建 pull request 或更改 tracker 状态。
Hook 支持需要 macOS、Linux 或 WSL 上的 Bash 和 Node。不支持原生 PowerShell hook wiring。设置期间应记录此限制,并在 host 无法 enforcing publication permissions 时阻止 staged run。