Back to Details

harness-master

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Harness Master

Harness Master

Audit AI harness configuration quality, usage posture, and ecosystem options, then apply approved config fixes in the same session.
NOT for: creating agents (agent-conventions), building MCP servers (mcp-creator), generic application telemetry (observability-advisor), or generic code review without harness/config focus (review).
Input: harness names, level, or natural language. Modes: Audit, Discover (gap + bounded research), Usage, Apply/Install, Journal. Run 
scripts/discovery/classify_intent.py --args "$ARGUMENTS" --json
when mode is ambiguous.
审计AI Harness的配置质量、使用状态和生态系统选项，并在同一会话中应用已获批的配置修复方案。
不适用于： 创建Agent（遵循agent-conventions规范）、搭建MCP服务器（使用mcp-creator）、通用应用遥测（使用observability-advisor）或不聚焦Harness/配置的通用代码评审（使用review）。
输入： Harness名称、级别或自然语言。模式：审计（Audit）、发现（Discover）（缺口分析+限定范围研究）、使用情况（Usage）、应用/安装（Apply/Install）、日志记录（Journal）。当模式不明确时，运行
scripts/discovery/classify_intent.py --args "$ARGUMENTS" --json
。

Dispatch

调度规则

$ARGUMENTS
ModeFirst move
Empty
IntakeAsk for harnesses or 
all
, then ask for 
project
, 
global
, or 
both
all
IntakeAsk only for level
all <level>
/ 
<level> all
AuditDry-run all supported harnesses in deterministic order
<harness...>
IntakeResolve one or more harnesses, then ask only for missing level
<level>
IntakeResolve level, then ask only for missing harnesses
<harness...> <level>
/ 
<level> <harness...>
AuditRun dry-run review for the selected harnesses and level
apply approved
Apply ApprovedApply the last matching dry-run batch only if the user already approved it in this session
apply <harness...> <level>
/ 
apply <level> <harness...>
Apply ApprovedApply only if the same scope was already reviewed and approved in this session; otherwise rerun audit first
install <harness...>
Install GuidanceShow exact 
npx skills add ...
commands only; do not edit configs
discover
Discover fullW0 scans → scouts → ideate → report per 
references/discovery-pipeline.md
discover audit
/ 
audit gaps
Discover W0Gap report only; no scouts
discover resume
/ 
discover list
JournalLoad or list 
~/.agents/harness-master/discovery/
sessions
usage <harness|all> [level] [days]
Usage ReviewCollect safe aggregate usage/cost/token/tool signals; read-only
NL: missing skills / expand / find best X for harnessDiscover (inferred)Depth: full, focused, candidate, or compare — see discovery-pipeline.md
Natural language: "review/audit/check/tune <harness> config"AuditNormalize harnesses + level, then run dry-run review
Natural language: "review/analyze usage/cost/tokens/tools for <harness>"Usage ReviewNormalize harnesses + level, collect safe metadata only, and report optimization lanes
Natural language: "find/latest/best plugins/extensions/MCPs/skills for <harness>"Discover focusedW0 + category scouts + 
source_probe.py
; read-only
Natural language approval like "approved", "do it", "apply those changes"Apply ApprovedContinue only if the immediately preceding 
harness-master
review matches the scope and is still current
Requests to create agents or MCP serversRefuse + redirectRedirect to the correct specialized skill
Unsupported harness namesRefuse + clarifyList supported harnesses and ask the user to choose from that set
$ARGUMENTS
模式第一步操作
Empty
初始引导询问要评审的Harness或输入
all
，然后询问范围是
project
、
global
还是
both
all
初始引导仅询问范围级别
all <level>
/ 
<level> all
审计按确定顺序对所有支持的Harness执行试运行审计
<harness...>
初始引导解析一个或多个Harness，然后仅询问缺失的范围级别
<level>
初始引导解析范围级别，然后仅询问缺失的Harness
<harness...> <level>
/ 
<level> <harness...>
审计对选定的Harness和级别执行试运行评审
apply approved
应用已获批方案仅当用户已在本次会话中批准过匹配的试运行批次时，应用最后一次匹配的试运行结果
apply <harness...> <level>
/ 
apply <level> <harness...>
应用已获批方案仅当相同范围已在本次会话中完成评审并获批准时执行应用；否则先重新运行审计
install <harness...>
安装指导仅展示确切的
npx skills add ...
命令；不修改配置
discover
完整发现模式执行W0扫描 → 侦察 → 构思 → 按
references/discovery-pipeline.md
生成报告
discover audit
/ 
audit gaps
基础发现（W0）仅生成缺口报告；不执行侦察操作
discover resume
/ 
discover list
日志记录加载或列出
~/.agents/harness-master/discovery/
中的会话记录
usage <harness|all> [level] [days]
使用情况评审收集安全的聚合使用/成本/令牌/工具数据信号；仅只读操作
自然语言：missing skills / expand / find best X for harness推断发现模式深度：完整、聚焦、候选或对比 — 详见discovery-pipeline.md
自然语言："review/audit/check/tune <harness> config"审计标准化Harness和级别，然后运行试运行评审
自然语言："review/analyze usage/cost/tokens/tools for <harness>"使用情况评审标准化Harness和级别，仅收集安全元数据，并报告优化方向
自然语言："find/latest/best plugins/extensions/MCPs/skills for <harness>"聚焦发现模式执行W0 + 分类侦察 + 
source_probe.py
；仅只读操作
自然语言批准如"approved", "do it", "apply those changes"应用已获批方案仅当紧接的
harness-master
评审匹配当前范围且仍有效时继续执行
创建Agent或MCP服务器的请求拒绝并重定向重定向至对应的专用技能
不支持的Harness名称拒绝并澄清列出支持的Harness并要求用户从中选择

Empty-Args Handler

空参数处理

If the user invokes 
/harness-master
with no arguments:
  1. Ask which harnesses to review or whether to use 
    all
    .
  2. Ask for 
    project
    , 
    global
    , or 
    both
    .
  3. Explain that the first pass is always dry-run only.
如果用户调用
/harness-master
时未传入参数：
  1. 询问要评审的Harness或是否使用
    all
    。
  2. 询问范围是
    project
    、
    global
    还是
    both
    。
  3. 说明首次执行始终为试运行模式。

Input Normalization

输入标准化

  • Supported harnesses: 
    claude-code
    , 
    claude-desktop
    , 
    chatgpt
    , 
    codex
    , 
    cursor
    , 
    cursor-cli
    , 
    grok-build
    , 
    opencode
    , 
    perplexity-desktop
    , 
    cherry-studio
    , 
    lm-studio
  • Supported levels: 
    project
    , 
    global
    , 
    both
  • Supported research categories: 
    config
    , 
    plugin
    , 
    extension
    , 
    mcp
    , 
    skill
    , 
    all
  • Supported usage windows: positive day counts such as 
    7
    , 
    14
    , 
    30
    , or 
    days=14
    ; default to 
    14
    when absent
  • Harness aliases: 
    • claude
      , 
      claude-code
      -> 
      claude-code
    • claude-desktop
      -> 
      claude-desktop
    • chatgpt
      , 
      chatgpt-desktop
      , 
      openai-chatgpt
      -> 
      chatgpt
    • codex
      -> 
      codex
    • cursor
      , 
      cursor-editor
      , 
      cursor-desktop
      , 
      cursor-web
      , 
      cursor-cloud
      , 
      cursor-cloud-agent
      , 
      cursor-background-agent
      -> 
      cursor
    • cursor-cli
      , 
      cursor-agent
      , 
      cursor-agent-cli
      , 
      agent-cli
      , 
      agent
      -> 
      cursor-cli
    • grok
      , 
      grok-build
      , 
      grok-cli
      -> 
      grok-build
    • opencode
      , 
      open-code
      -> 
      opencode
    • perplexity
      , 
      perplexity-desktop
      , 
      perplexity-mac
      -> 
      perplexity-desktop
    • cherry
      , 
      cherrystudio
      , 
      cherry-ai
      , 
      cherry-studio
      -> 
      cherry-studio
    • lm-studio
      , 
      lmstudio
      , 
      lms
      -> 
      lm-studio
  • Level aliases: 
    • project
      , 
      repo
      , 
      local
      -> 
      project
    • global
      , 
      user
      -> 
      global
    • both
      , 
      all-levels
      -> 
      both
  • Split multiple harnesses on commas and whitespace.
  • If the user supplies both 
    all
    and named harnesses, ask which form they want.
  • Deterministic 
    all
    order: 
    claude-code
    , 
    claude-desktop
    , 
    chatgpt
    , 
    codex
    , 
    cursor
    , 
    cursor-cli
    , 
    grok-build
    , 
    opencode
    , 
    perplexity-desktop
    , 
    cherry-studio
    , 
    lm-studio
  • Unknown tokens are never guessed. Ask one focused clarification question.
  • 支持的Harness：
    claude-code
    , 
    claude-desktop
    , 
    chatgpt
    , 
    codex
    , 
    cursor
    , 
    cursor-cli
    , 
    grok-build
    , 
    opencode
    , 
    perplexity-desktop
    , 
    cherry-studio
    , 
    lm-studio
  • 支持的级别：
    project
    , 
    global
    , 
    both
  • 支持的研究分类：
    config
    , 
    plugin
    , 
    extension
    , 
    mcp
    , 
    skill
    , 
    all
  • 支持的使用周期：正整数天数，如
    7
    , 
    14
    , 
    30
    或
    days=14
    ；未指定时默认
    14
    天
  • Harness别名： 
    • claude
      , 
      claude-code
      -> 
      claude-code
    • claude-desktop
      -> 
      claude-desktop
    • chatgpt
      , 
      chatgpt-desktop
      , 
      openai-chatgpt
      -> 
      chatgpt
    • codex
      -> 
      codex
    • cursor
      , 
      cursor-editor
      , 
      cursor-desktop
      , 
      cursor-web
      , 
      cursor-cloud
      , 
      cursor-cloud-agent
      , 
      cursor-background-agent
      -> 
      cursor
    • cursor-cli
      , 
      cursor-agent
      , 
      cursor-agent-cli
      , 
      agent-cli
      , 
      agent
      -> 
      cursor-cli
    • grok
      , 
      grok-build
      , 
      grok-cli
      -> 
      grok-build
    • opencode
      , 
      open-code
      -> 
      opencode
    • perplexity
      , 
      perplexity-desktop
      , 
      perplexity-mac
      -> 
      perplexity-desktop
    • cherry
      , 
      cherrystudio
      , 
      cherry-ai
      , 
      cherry-studio
      -> 
      cherry-studio
    • lm-studio
      , 
      lmstudio
      , 
      lms
      -> 
      lm-studio
  • 级别别名： 
    • project
      , 
      repo
      , 
      local
      -> 
      project
    • global
      , 
      user
      -> 
      global
    • both
      , 
      all-levels
      -> 
      both
  • 多个Harness用逗号和空格分隔。
  • 如果用户同时提供
    all
    和指定Harness，询问用户选择哪种形式。
  • all
    的确定顺序：
    claude-code
    , 
    claude-desktop
    , 
    chatgpt
    , 
    codex
    , 
    cursor
    , 
    cursor-cli
    , 
    grok-build
    , 
    opencode
    , 
    perplexity-desktop
    , 
    cherry-studio
    , 
    lm-studio
  • 不猜测未知令牌。询问一个明确的澄清问题。

Grok Build (
grok-build
)

Grok Build (
grok-build
)

  • Instruction entry: 
    AGENTS.md
    -> 
    instructions/grok-global.md
    -> 
    instructions/global.md
  • Policy template: 
    config/grok-config.toml
    merged into 
    ~/.grok/config.toml
    via repo Grok platform adapter sync
  • Ownership: replace-owned (
    models
    , 
    mcp_servers
    , 
    plugins
    , 
    compat
    , 
    telemetry
    ) vs blend-owned (
    ui
    , 
    features
    , 
    session
    , 
    tools
    , 
    toolset
    , 
    subagents
    , 
    memory
    )
  • Skills: no native Skills CLI adapter; install/sync uses 
    claude-code
    alias + mirror to 
    ~/.grok/skills
    ; inventory also scans repo 
    .grok/skills
    (project scope)
  • Plannotator: CLI + skills + hooks (no Grok npm plugin). Install: 
    grok plannotator install
    (repo CLI). Policy: 
    config/grok-plannotator-hooks.json
    -> 
    ~/.grok/hooks/plannotator.json
    ; home shim maps 
    block
    -> 
    deny
    . Curated in 
    docs/src/authoring/skills/*.mdx
    . Contrast OpenCode 
    @plannotator/opencode@latest
    .
  • Env (not in TOML): 
    GROK_WEB_FETCH
    , 
    GROK_MEMORY
    , 
    GROK_SUBAGENTS
    , 
    GROK_LSP_TOOLS
    — document in 
    config/grok-env.sh
    ; verify with 
    /grok-delegate preflight
  • Cross-harness delegate: 
    /grok-delegate
    — native headless 
    grok -p
    / 
    -r
    / worktrees / leader for Codex/OpenCode task graphs (not config sync)
  • Isolated sync: repo stack sync with 
    --platforms grok --targets home
    (skips other harness home merges; includes Plannotator hook refresh)
  • 指令入口： 
    AGENTS.md
    -> 
    instructions/grok-global.md
    -> 
    instructions/global.md
  • 策略模板： 
    config/grok-config.toml
    通过仓库Grok平台适配器同步合并到
    ~/.grok/config.toml
  • 所有权： replace-owned（
    models
    , 
    mcp_servers
    , 
    plugins
    , 
    compat
    , 
    telemetry
    ）vs blend-owned（
    ui
    , 
    features
    , 
    session
    , 
    tools
    , 
    toolset
    , 
    subagents
    , 
    memory
    ）
  • Skills： 无原生Skills CLI适配器；安装/同步使用
    claude-code
    别名 + 镜像至
    ~/.grok/skills
    ；清单同时扫描仓库
    .grok/skills
    （项目范围）
  • Plannotator： CLI + skills + hooks（无Grok npm插件）。安装：
    grok plannotator install
    （仓库CLI）。策略：
    config/grok-plannotator-hooks.json
    -> 
    ~/.grok/hooks/plannotator.json
    ；本地垫片映射
    block
    -> 
    deny
    。在
    docs/src/authoring/skills/*.mdx
    中管理。对比OpenCode的
    @plannotator/opencode@latest
    。
  • 环境变量（不在TOML中）： 
    GROK_WEB_FETCH
    , 
    GROK_MEMORY
    , 
    GROK_SUBAGENTS
    , 
    GROK_LSP_TOOLS
    — 记录在
    config/grok-env.sh
    中；通过
    /grok-delegate preflight
    验证
  • 跨Harness代理： 
    /grok-delegate
    — 原生无界面
    grok -p
    / 
    -r
    / 工作区 / Codex/OpenCode任务图的领导者（非配置同步）
  • 隔离同步： 使用
    --platforms grok --targets home
    进行仓库栈同步（跳过其他Harness本地合并；包含Plannotator钩子刷新）

Cursor Agent CLI (
cursor-cli
)

Cursor Agent CLI (
cursor-cli
)

  • Binary: 
    agent
    (also 
    cursor-agent
    ). Skills CLI adapter remains 
    cursor
    (
    -a cursor
    ).
  • Instruction entry: 
    AGENTS.md
    + 
    CLAUDE.md
    + 
    .cursor/rules
    + 
    instructions/cursor-cli-global.md
    (thin 
    .cursor/rules/cursor-cli.mdc
    pointer)
  • Shared SSOT with editor: 
    .cursor/hooks.json
    , 
    .cursor/mcp.json
    , 
    .cursor/skills
    , 
    .cursor/agents
    , 
    ~/.cursor/{hooks,mcp,skills,agents}
    — rendered once by the Cursor adapter (
    harness="cursor"
    )
  • CLI-only: project 
    .cursor/cli.json
    permissions; user-owned 
    ~/.cursor/cli-config.json
    (sync SHALL NOT write it). Doctor: repo CLI 
    cursor-cli doctor
  • Plugins: 
    --plugin-dir
    and 
    agent plugin marketplace
    (operator-opt-in; never sync-add)
  • ACP / worktrees / worker: cite 
    cursor-acp
    ; 
    agent --worktree
    ; 
    agent worker
    is out of repo sync
  • Hooks: consume shared hooks.json + plugin hooks. Do not add 
    cursor-cli
    to hook-registry render lists
  • 二进制文件： 
    agent
    （也叫
    cursor-agent
    ）。Skills CLI适配器仍为
    cursor
    （
    -a cursor
    ）。
  • 指令入口： 
    AGENTS.md
    + 
    CLAUDE.md
    + 
    .cursor/rules
    + 
    instructions/cursor-cli-global.md
    （存在
    .cursor/rules/cursor-cli.mdc
    指针）
  • 与编辑器共享单一可信源： 
    .cursor/hooks.json
    , 
    .cursor/mcp.json
    , 
    .cursor/skills
    , 
    .cursor/agents
    , 
    ~/.cursor/{hooks,mcp,skills,agents}
    — 由Cursor适配器（
    harness="cursor"
    ）统一渲染
  • 仅CLI： 项目
    .cursor/cli.json
    权限；用户所有的
    ~/.cursor/cli-config.json
    （同步不得修改）。诊断：仓库CLI 
    cursor-cli doctor
  • 插件： 
    --plugin-dir
    和
    agent plugin marketplace
    （操作员选择加入；从不通过同步添加）
  • ACP / 工作区 / 工作进程： 参考
    cursor-acp
    ；
    agent --worktree
    ；
    agent worker
    不在仓库同步范围内
  • 钩子： 消费共享hooks.json + 插件钩子。不要将
    cursor-cli
    添加到钩子注册表渲染列表

Classification Gate

分类校验

  1. Parse 
    $ARGUMENTS
    into harnesses, level, 
    all
    , install intent, apply intent, and unresolved tokens.
  2. If unresolved tokens remain, ask a single clarification question before continuing.
  3. If the request is 
    discover ...
    , gap/missing/expand intent, or find-best-for-harness NL, run Discover (infer depth via 
    classify_intent.py
    or discovery-pipeline.md).
  4. If the request is 
    usage ...
    , run Usage Review only.
  5. If the request is 
    install ...
    , run Install Guidance only.
  6. If ad-hoc "find skill for X", redirect to 
    skill-router search
    or 
    npx skills find
    . If systematic skill/MCP expansion, stay in Discover. If create skill, redirect to skill-creator. If open-ended non-harness research, redirect to 
    /research
    .
  7. If the request is 
    apply ...
    or an approval phrase, run Apply Approved only if the matching dry-run review already exists in this session. Otherwise rerun audit first.
  8. If the request includes unsupported harnesses, refuse cleanly and list the supported set.
  9. If harnesses are missing and 
    all
    was not supplied (audit/usage), ask only for harnesses or 
    all
    .
  10. If the level is missing (audit/usage), ask only for 
    project
    , 
    global
    , or 
    both
    .
  11. Otherwise run Audit in dry-run mode.
  1. 将
    $ARGUMENTS
    解析为Harness、级别、
    all
    、安装意图、应用意图和未解析令牌。
  2. 如果存在未解析令牌，先询问一个明确的澄清问题再继续。
  3. 如果请求是
    discover ...
    、缺口/缺失/扩展意图，或“为Harness寻找最佳X”类自然语言，运行发现模式（通过
    classify_intent.py
    或discovery-pipeline.md推断深度）。
  4. 如果请求是
    usage ...
    ，仅运行使用情况评审。
  5. 如果请求是
    install ...
    ，仅运行安装指导。
  6. 如果是临时“为X寻找skill”，重定向至
    skill-router search
    或
    npx skills find
    。如果是系统性skill/MCP扩展，留在发现模式。如果是创建skill，重定向至skill-creator。如果是开放式非Harness研究，重定向至
    /research
    。
  7. 如果请求是
    apply ...
    或批准短语，仅当本次会话中已存在匹配的试运行评审时，运行应用已获批方案。否则先重新运行审计。
  8. 如果请求包含不支持的Harness，明确拒绝并列出支持的集合。
  9. 如果缺少Harness且未提供
    all
    （审计/使用情况），仅询问Harness或
    all
    。
  10. 如果缺少级别（审计/使用情况），仅询问
    project
    、
    global
    或
    both
    。
  11. 否则以试运行模式运行审计。

Classification Logic

分类逻辑

  1. Route explicit mode tokens first: 
    discover
    , 
    usage
    , 
    install
    , 
    apply
    , 
    resume
    , 
    list
    .
  2. Route gap/missing/expand/find-best NL to Discover depths (not Audit).
  3. Route complete harness/level scopes to Audit when config tune/fix intent and no discover signal.
  4. Route usage/cost/token NL to Usage Review.
  5. Route approvals to Apply Approved only when the immediately preceding dry-run audit matches the requested scope.
  1. 优先路由显式模式令牌：
    discover
    , 
    usage
    , 
    install
    , 
    apply
    , 
    resume
    , 
    list
    。
  2. 将缺口/缺失/扩展/寻找最佳类自然语言路由至不同深度的发现模式（非审计）。
  3. 当存在配置调优/修复意图且无发现信号时，将完整的Harness/级别范围路由至审计模式。
  4. 将使用/成本/令牌类自然语言路由至使用情况评审。
  5. 仅当紧接的试运行审计匹配请求范围时，将批准请求路由至应用已获批方案。

Workflow

工作流程

Mode A: Audit (default, dry-run first)

模式A：审计（默认，首次为试运行）

  1. Gate 0 — Discover surfaces
    • Run:
      bash
      uv run python scripts/discover_surfaces.py --repo-root . --level <level> --harness <canonical-harness> [--harness ...]
    • Parse the JSON output and classify each surface as 
      present
      , 
      missing
      , 
      generated
      , 
      merged
      , 
      repo-observed
      , or 
      blind-spot
      .
    • If the script cannot run, fall back to manual discovery with 
      Glob
      , 
      Read
      , and 
      Grep
      .
  2. Gate 1 — Inspect project context before recommending fixes
    • Read the repo's intent and operating model first: 
      README.md
      , 
      AGENTS.md
      , harness-facing project files, key manifests, CI/workflow signals, and repo-native orchestration logic when present.
    • In this repository, treat the repo-level harness sync script together with 
      config/tooling-policy.json
      and 
      config/sync-manifest.json
      as canonical context for managed/generated/merged harness surfaces.
  3. Gate 2 — Refresh latest official guidance
    • Read 
      references/latest-doc-sources.md
      .
    • Use 
      llms.txt
      first when available, then first-party docs, then canonical vendor repo docs, then web fallback only if needed.
    • If official docs are unavailable, enter degraded mode and lower confidence.
  4. Gate 3 — Audit each selected harness independently
    • Load 
      references/harness-surfaces.md
      , 
      references/harness-checklists.md
      , and 
      references/evidence-boundaries.md
      selectively for the selected harnesses only.
    • For 
      both
      , compare project/global precedence before recommending edits.
    • Mark generated surfaces explicitly. Prefer fixing the canonical source over directly editing generated output.
    • Treat missing native surfaces as evidence to assess, not automatic failure.
  5. Gate 4 — Report dry-run findings
    • Use the structure in 
      references/output-format.md
      .
    • Every finding must include severity, affected surface, evidence tag, why it matters for this project, and the correct home for the fix.
    • Show concrete patch previews when the correct change is clear.
    • Stop after the dry-run report and wait for explicit user approval.
  1. 校验0 — 发现配置面
    • 运行：
      bash
      uv run python scripts/discover_surfaces.py --repo-root . --level <level> --harness <canonical-harness> [--harness ...]
    • 解析JSON输出并将每个配置面分类为
      present
      、
      missing
      、
      generated
      、
      merged
      、
      repo-observed
      或
      blind-spot
      。
    • 如果脚本无法运行，回退至使用
      Glob
      、
      Read
      和
      Grep
      手动发现。
  2. 校验1 — 推荐修复前检查项目上下文
    • 先读取仓库的意图和运营模型：
      README.md
      , 
      AGENTS.md
      、面向Harness的项目文件、关键清单、CI/工作流信号，以及仓库原生编排逻辑（如果存在）。
    • 在本仓库中，将仓库级Harness同步脚本与
      config/tooling-policy.json
      和
      config/sync-manifest.json
      一起视为托管/生成/合并Harness配置面的标准上下文。
  3. 校验2 — 刷新最新官方指南
    • 读取
      references/latest-doc-sources.md
      。
    • 优先使用
      llms.txt
      （如果可用），然后是官方文档，再是标准供应商仓库文档，仅在必要时使用网络回退。
    • 如果官方文档不可用，进入降级模式并降低置信度。
  4. 校验3 — 独立审计每个选定的Harness
    • 针对选定的Harness，选择性加载
      references/harness-surfaces.md
      、
      references/harness-checklists.md
      和
      references/evidence-boundaries.md
      。
    • 对于
      both
      级别，在推荐修改前比较项目/全局优先级。
    • 显式标记生成的配置面。优先修改标准源而非直接编辑生成的输出。
    • 将缺失的原生配置面视为评估证据，而非自动判定为问题。
  5. 校验4 — 报告试运行结果
    • 使用
      references/output-format.md
      中的结构。
    • 每个发现必须包含严重性、受影响的配置面、证据标签、对本项目的影响，以及修复的正确位置。
    • 当明确知道正确修改内容时，展示具体的补丁预览。
    • 试运行报告后停止，等待用户明确批准。

Mode B: Apply Approved

模式B：应用已获批方案

  1. Apply only after an explicit approval gate.
  2. Approval is valid only when the immediately preceding 
    harness-master
    dry-run review in the same session already covered the same harness set and level.
  3. If the reviewed scope is stale, missing, ambiguous, or contradicted by new evidence, rerun Audit before editing.
  4. Restate the approved batch before making changes.
  5. Apply the smallest approved batch only. Do not broaden scope silently.
  6. If the approved remediation is an install step, use the exact 
    npx skills add ...
    guidance from 
    references/install-guidance.md
    .
  7. After edits, rerun surface discovery and targeted dry-run checks for the touched harnesses, then summarize remaining gaps.
  1. 仅在明确的批准校验后执行应用。
  2. 仅当本次会话中紧接的
    harness-master
    试运行评审已覆盖相同的Harness集合和级别时，批准才有效。
  3. 如果评审范围已过期、缺失、模糊或与新证据矛盾，先重新运行审计再编辑。
  4. 执行修改前重申已获批的批次。
  5. 仅应用最小的获批批次。不得静默扩大范围。
  6. 如果获批的修复是安装步骤，使用
    references/install-guidance.md
    中确切的
    npx skills add ...
    指导。
  7. 编辑后，重新运行配置面发现并对受影响的Harness执行针对性试运行检查，然后总结剩余缺口。

Mode C: Discover

模式C：发现

Read-only gap expansion and harness-bounded research. Load 
references/discovery-pipeline.md
and 
references/discovery/coordinator-contract.md
.
  1. Classify depth (full, focused, candidate, compare, w0only, ideate, journal).
  2. Run W0 scripts before any scouts when depth requires gaps.
  3. Use 
    source_probe.py
    and 
    candidate_score.py
    inside W2/W2b — not as separate user-facing modes.
  4. Block apply/install until user confirms; config fixes require Audit + 
    apply approved
    .
只读的缺口扩展和Harness限定范围研究。加载
references/discovery-pipeline.md
和
references/discovery/coordinator-contract.md
。
  1. 分类深度（完整、聚焦、候选、对比、仅W0、构思、日志）。
  2. 当深度要求分析缺口时，先运行W0脚本再执行任何侦察操作。
  3. 在W2/W2b中使用
    source_probe.py
    和
    candidate_score.py
    — 不作为独立的用户可见模式。
  4. 阻止应用/安装操作直到用户确认；配置修复需要先执行审计 + 
    apply approved
    。

Mode D: Usage Review

模式D：使用情况评审

Use this mode for 
usage
or natural-language requests to review token cost, quota, tool friction, MCP use, skill fit, plugin fit, context health, session attribution, or harness telemetry posture.
  1. Treat the entire mode as read-only. Do not edit files, install packages, create jobs, export raw sessions, print raw prompts, print raw traces, or mutate harness configs.
  2. Normalize harnesses, level, and usage window. Default missing window to 
    14
    days.
  3. Run surface discovery plus the safe usage probe:
    bash
    uv run python scripts/usage_probe.py --repo-root . --harness <canonical-harness> --level <level> --days <days> --json
  4. Load 
    references/usage-review.md
    , 
    references/evidence-boundaries.md
    , and 
    references/output-format.md
    .
  5. Use runtime tools such as 
    token_stats
    , 
    token_history
    , 
    token_export
    , 
    insights_collect
    , 
    agent_attribution
    , 
    quota_status
    , 
    gemini_quota
    , 
    workspace-summary
    , and 
    git-smart-status
    only when they match the requested harness and privacy class.
  6. Normalize findings into usage signals and score source coverage, privacy safety, cost/token posture, tool efficiency, MCP hygiene, skill fit, plugin fit, context health, approval safety, and recommendation actionability.
  7. Report recommendation lanes: 
    keep
    , 
    tune-config
    , 
    tune-skill
    , 
    tune-mcp
    , 
    tune-plugin
    , 
    tune-workflow
    , 
    instrument
    , 
    defer
    , or 
    do-not-change
    .
  8. If the user asks to apply a Usage Review recommendation, block the apply step and require a matching dry-run Audit plus explicit approval first.
此模式适用于
usage
或自然语言请求，用于评审令牌成本、配额、工具摩擦、MCP使用、skill适配、插件适配、上下文健康度、会话归因或Harness遥测状态。
  1. 整个模式为只读。不得编辑文件、安装包、创建任务、导出原始会话、打印原始提示、打印原始跟踪或修改Harness配置。
  2. 标准化Harness、级别和使用周期。未指定周期时默认
    14
    天。
  3. 运行配置面发现以及安全使用探针：
    bash
    uv run python scripts/usage_probe.py --repo-root . --harness <canonical-harness> --level <level> --days <days> --json
  4. 加载
    references/usage-review.md
    、
    references/evidence-boundaries.md
    和
    references/output-format.md
    。
  5. 仅当运行时工具匹配请求的Harness和隐私类别时，才使用
    token_stats
    、
    token_history
    、
    token_export
    、
    insights_collect
    、
    agent_attribution
    、
    quota_status
    、
    gemini_quota
    、
    workspace-summary
    和
    git-smart-status
    。
  6. 将发现标准化为使用信号，并对源覆盖范围、隐私安全性、成本/令牌状态、工具效率、MCP卫生度、skill适配、插件适配、上下文健康度、批准安全性和建议可操作性进行评分。
  7. 报告建议方向：
    keep
    、
    tune-config
    、
    tune-skill
    、
    tune-mcp
    、
    tune-plugin
    、
    tune-workflow
    、
    instrument
    、
    defer
    或
    do-not-change
    。
  8. 如果用户要求应用使用情况评审的建议，阻止应用步骤并要求先执行匹配的试运行审计 + 明确批准。

Scaling Strategy

扩展策略

ScopeStrategy
small1 harness and 1 level: inline review with one per-harness report
medium2-3 harnesses or one 
both
scope: review each harness independently, then add a short synthesis
large4+ harnesses or 
all
: batch discovery where possible, keep per-harness sections strict, then finish with cross-harness synthesis and ranked cleanup order
Discover (full/focused)Use Pattern F semantics: explore sources, score candidates, synthesize evidence, and stop before apply
Team-capable DiscoverUse Pattern E or nested waves for source-family scouts, with accounting for every dispatched scout
Usage reviewPrefer aggregate probes and runtime summaries first; avoid raw transcripts, raw traces, secret files, and message-table reads
范围策略
小型1个Harness和1个级别：内联评审，每个Harness一份报告
中型2-3个Harness或一个
both
范围：独立评审每个Harness，然后添加简短的综合分析
大型4个以上Harness或
all
：尽可能批量发现，严格保留每个Harness的独立部分，最后完成跨Harness综合分析并给出优先级清理顺序
发现（完整/聚焦）使用Pattern F语义：探索源、评分候选、综合证据，在应用前停止
团队级发现使用Pattern E或嵌套波进行源类别侦察，并记录每个已调度的侦察任务
使用情况评审优先使用聚合探针和运行时摘要；避免原始转录本、原始跟踪、机密文件和消息表读取

Latest-Doc Lookup Policy

最新文档查找策略

Use the most current authoritative guidance available:
  1. llms.txt
    or equivalent official index
  2. First-party docs pages for config, instructions, rules, MCP, and permissions
  3. Canonical vendor repo docs if first-party product docs are incomplete
  4. Web fallback only when the above are unavailable
Never claim 
latest
without evidence from a current source.
使用可用的最新权威指南：
  1. llms.txt
    或等效官方索引
  2. 配置、指令、规则、MCP和权限的官方文档页面
  3. 如果官方产品文档不完整，使用标准供应商仓库文档
  4. 仅当上述来源不可用时才使用网络回退
若无当前来源的证据，不得声称是“最新”。

Per-Harness Review Contract

每个Harness的评审约定

  • Review each harness independently before writing any synthesis.
  • Tag every finding as 
    verified-file
    , 
    verified-doc
    , 
    repo-observed
    , or 
    blind-spot
    .
  • Surface the authoritative, secondary, generated, and merged config surfaces for the selected level.
  • For 
    both
    , report project/global conflicts before recommending changes.
  • If a harness-specific native surface is not observable from the current session, mark it as a blind spot instead of inventing behavior.
  • 在撰写任何综合分析前，独立评审每个Harness。
  • 将每个发现标记为
    verified-file
    、
    verified-doc
    、
    repo-observed
    或
    blind-spot
    。
  • 展示选定级别的权威、次要、生成和合并配置面。
  • 对于
    both
    级别，在推荐修改前报告项目/全局冲突。
  • 如果当前会话无法观察到Harness特定的原生配置面，标记为盲点而非臆测行为。

Install Guidance Contract

安装指导约定

  • Load 
    references/install-guidance.md
    only when the user asks how to install 
    harness-master
    , or when missing skill availability is the actual root cause.
  • Default surfaced form:
    bash
    npx skills add <source> --skill harness-master -y -g --agent claude-code --agent codex --agent crush --agent cursor --agent opencode
  • Do not recommend install commands for native config problems.
  • Do not suggest project-local install by default. Mention 
    python scripts/install_skills.py --local --execute
    only if the user explicitly asks for project-local installation.
  • 仅当用户询问如何安装
    harness-master
    ，或缺失skill可用性是实际根本原因时，加载
    references/install-guidance.md
    。
  • 默认展示格式：
    bash
    npx skills add <source> --skill harness-master -y -g --agent claude-code --agent codex --agent crush --agent cursor --agent opencode
  • 不为原生配置问题推荐安装命令。
  • 默认不建议项目本地安装。仅当用户明确要求项目本地安装时，提及
    python scripts/install_skills.py --local --execute
    。

Validation Contract

验证约定

After changing this skill, run:
bash
python scripts/check.py
uv run python scripts/usage_probe.py --repo-root . --harness opencode --level both --days 14 --json
uv run python scripts/discover_surfaces.py --repo-root . --level both --harness claude-code --harness claude-desktop --harness chatgpt --harness codex --harness cursor --harness cursor-cli --harness grok-build --harness opencode --harness perplexity-desktop --harness cherry-studio --harness lm-studio
Completion criteria:
  • metadata and eval manifests validate
  • packaging remains portable
  • surface discovery smoke-check accepts every canonical harness
  • dry-run/apply behavior still requires approval before edits
  • Discover remains read-only and blocks apply until a matching audit is approved
  • usage review remains read-only, redacts sensitive sources, and blocks apply until a matching audit is approved
修改本技能后，运行：
bash
python scripts/check.py
uv run python scripts/usage_probe.py --repo-root . --harness opencode --level both --days 14 --json
uv run python scripts/discover_surfaces.py --repo-root . --level both --harness claude-code --harness claude-desktop --harness chatgpt --harness codex --harness cursor --harness cursor-cli --harness grok-build --harness opencode --harness perplexity-desktop --harness cherry-studio --harness lm-studio
完成标准：
  • 元数据和评估清单验证通过
  • 打包保持可移植性
  • 配置面发现冒烟测试接受所有标准Harness
  • 试运行/应用行为仍需批准后才能编辑
  • 发现模式保持只读，且需匹配审计获批准后才能执行应用
  • 使用情况评审保持只读，编辑敏感源，且需匹配审计获批准后才能执行应用

Cross-Harness Synthesis Contract

跨Harness综合分析约定

After all per-harness reviews, synthesize:
  • Shared issues across harnesses
  • Conflicting conventions or precedence rules
  • Duplicated instruction sources or MCP definitions
  • Generated-vs-canonical drift patterns
  • Highest-leverage cleanup order if the user wants a follow-up apply batch
完成所有单个Harness评审后，综合分析：
  • 跨Harness的共享问题
  • 冲突的约定或优先级规则
  • 重复的指令源或MCP定义
  • 生成源与标准源的漂移模式
  • 如果用户需要后续应用批次，给出最高优先级的清理顺序

Output Contract

输出约定

Every per-harness report must include:
  1. Harness
  2. Level
  3. Files Reviewed
  4. Docs Checked
  5. Project Context Summary
  6. Blind Spots
  7. Scorecard
  8. Findings
  9. Recommended Changes
  10. Proposed Patch Preview
  11. Confidence
Then add a cross-harness synthesis section when 2+ harnesses were reviewed.
每个Harness的报告必须包含：
  1. Harness
  2. 级别
  3. 已评审文件
  4. 已检查文档
  5. 项目上下文摘要
  6. 盲点
  7. 评分卡
  8. 发现结果
  9. 推荐修改
  10. 补丁预览建议
  11. 置信度
当评审2个以上Harness时，添加跨Harness综合分析部分。

Reference File Index

参考文件索引

FileContentRead When
references/workflow.md
Gate-by-gate audit/apply workflow, precedence rules, degraded mode, and approval gate detailsAudit, Apply Approved
references/latest-doc-sources.md
Official 
llms.txt
and docs URLs per harness, plus fallback order		Latest-doc refresh
references/harness-surfaces.md
Project/global surfaces, precedence, install agent names, generated/merged notesSurface interpretation
references/harness-checklists.md
Per-harness audit checklist and edge casesPer-harness review
references/evidence-boundaries.md
Evidence tags, blind-spot handling, and contradiction policyReporting findings
references/install-guidance.md
Exact 
npx skills add ...
commands, when to surface them, and anti-patterns		Install Guidance
references/output-format.md
Per-harness and cross-harness report templatesFinal output
references/discovery-pipeline.md
W0–W4 discover waves, depth inference, evidence vs contracts, redirectsDiscover
references/discovery/
Coordinator contract, scout templates, output formats, research integrationDiscover scouts and reports
references/ecosystem-research.md
Legacy source-family notes; prefer discovery-pipeline.md for dispatchDiscover W2 source planning
references/source-profiles.md
Source families, programmatic access, confidence roles, and degraded-source behaviorDiscover W2 source planning
references/usage-review.md
Read-only usage sources, privacy classes, scorecard, signal schema, and recommendation lanesUsage Review
data/research-sources.json
Machine-readable source registry for source planning and probe scriptsDiscover W2 source planning
Read only the references needed for the active step. Do not preload all references.
文件内容读取时机
references/workflow.md
按校验步骤划分的审计/应用工作流程、优先级规则、降级模式和批准校验细节审计、应用已获批方案
references/latest-doc-sources.md
每个Harness的官方
llms.txt
和文档URL，以及回退顺序		最新文档刷新
references/harness-surfaces.md
项目/全局配置面、优先级、安装Agent名称、生成/合并说明配置面解释
references/harness-checklists.md
每个Harness的审计清单和边缘情况单个Harness评审
references/evidence-boundaries.md
证据标签、盲点处理和矛盾处理策略发现结果报告
references/install-guidance.md
确切的
npx skills add ...
命令、展示时机和反模式		安装指导
references/output-format.md
单个Harness和跨Harness的报告模板最终输出
references/discovery-pipeline.md
W0–W4发现阶段、深度推断、证据与约定、重定向发现模式
references/discovery/
协调器约定、侦察模板、输出格式、研究集成发现侦察和报告
references/ecosystem-research.md
遗留源类别说明；优先使用discovery-pipeline.md进行调度发现W2源规划
references/source-profiles.md
源类别、程序化访问、置信度角色和降级源行为发现W2源规划
references/usage-review.md
只读使用源、隐私类别、评分卡、信号 schema 和建议方向使用情况评审
data/research-sources.json
用于源规划和探针脚本的机器可读源注册表发现W2源规划
仅读取当前步骤所需的参考文件。不要预加载所有参考文件。

Progressive Disclosure

渐进式披露

Load reference files as indicated by the active mode. Do not load all references at once; use the dispatch table, source plan, and final output needs to choose the smallest relevant set.
根据当前活动模式加载参考文件。不要一次性加载所有参考文件；使用调度表、源计划和最终输出需求选择最小的相关集合。

Canonical Vocabulary

标准词汇

These terms are canonical for 
harness-master
reports and should be used exactly.
Use these terms exactly throughout:
TermMeaningNOT
harness
One supported agent/runtime target
editor
, 
toolchain
level
project
, 
global
, or 
both
scope for the review
environment
project surface
Repo-local file or generated artifact used by a harness
global config
global surface
User-level harness config outside the repo
project file
dry-run
Findings + patch preview only; no edits
apply
approval gate
Explicit user consent required before edits
implied approval
blind-spot
A surface or behavior that is not observable in the current session
guess
repo-observed
Behavior inferred from the current codebase's real harness wiring
official-doc evidence
patch preview
Proposed diff or snippet shown before edits
applied change
canonical source
The file or config that should be changed instead of a generated output
generated surface
source plan
Read-only list of sources, URLs/commands, env vars, evidence fields, and failure modes
apply plan
candidate dossier
Normalized evidence bundle for one ecosystem candidate
endorsement
support tier
Adoption readiness class backed by evidence and validation state
popularity rank
quarantine
Candidate class for credential, proxy, destructive, offensive, or broad-permission risk
rejection without review
usage signal
Sanitized aggregate evidence about token, cost, quota, tool, MCP, skill, plugin, or workflow behavior
raw transcript
privacy class
Sensitivity class that determines whether a source can be collected, summarized, or must stay manual-only
permission bypass
这些术语是
harness-master
报告的标准词汇，应严格使用。
严格使用以下术语：
术语含义禁用术语
harness
一个受支持的Agent/运行时目标
editor
, 
toolchain
level
评审范围：
project
、
global
或
both
environment
project surface
Harness使用的仓库本地文件或生成工件
global config
global surface
仓库外的用户级Harness配置
project file
dry-run
仅展示发现结果+补丁预览；不修改
apply
approval gate
修改前需要用户明确同意
implied approval
blind-spot
当前会话中无法观察到的配置面或行为
guess
repo-observed
从当前代码库的实际Harness连接推断出的行为
official-doc evidence
patch preview
修改前展示的建议差异或片段
applied change
canonical source
应修改的文件或配置，而非生成输出
generated surface
source plan
只读的源列表、URL/命令、环境变量、证据字段和失败模式
apply plan
candidate dossier
一个生态系统候选者的标准化证据包
endorsement
support tier
基于证据和验证状态的采用就绪类
popularity rank
quarantine
存在凭证、代理、破坏性、冒犯性或广泛权限风险的候选类别
rejection without review
usage signal
关于令牌、成本、配额、工具、MCP、skill、插件或工作流行为的 sanitized 聚合证据
raw transcript
privacy class
决定源是否可收集、汇总或必须保持手动的敏感度类别
permission bypass

Critical Rules

关键规则

  1. Every new 
    harness-master
    run starts in dry-run audit mode.
  2. Never edit before explicit user approval.
  3. Apply Approved
    is valid only after a matching dry-run review in the current session.
  4. Ask only for missing inputs. Never re-ask resolved harnesses or levels.
  5. Always inspect project context before recommending harness changes.
  6. Always refresh latest official guidance before claiming a configuration is current or stale.
  7. Mark blind spots explicitly. Do not guess hidden or UI-only settings.
  8. Prefer edits to canonical sources over generated or merged outputs when this is clear from evidence.
  9. Every finding must carry an evidence tag: 
    verified-file
    , 
    verified-doc
    , 
    repo-observed
    , or 
    blind-spot
    .
  10. Show concrete patch previews whenever the correct edit is clear.
  11. Use 
    npx skills add ...
    only when installation is genuinely the right next step.
  12. Unsupported harnesses must be refused cleanly with the supported set listed.
  13. Ecosystem research is advisory and read-only. Never apply from a research report alone.
  14. Credentialed APIs are optional enrichments. Missing credentials lower confidence but do not block baseline source planning.
  15. GitHub GraphQL enriches known candidate repositories; use REST/search or code/file lookup for broad discovery.
  16. Usage Review is advisory and read-only. Never apply config changes, install tools, export raw sessions, or print raw prompts/traces from usage findings alone.
  17. Usage Review may use aggregate-safe and sanitized metadata sources, but secret files, credential values, raw transcripts, raw traces, and raw message-table bodies are out of scope.
  1. 每次新的
    harness-master
    运行都从试运行审计模式开始。
  2. 获得用户明确批准前不得修改。
  3. 仅当本次会话中存在匹配的试运行评审时，
    Apply Approved
    才有效。
  4. 仅询问缺失的输入。不得重复询问已解析的Harness或级别。
  5. 推荐Harness修改前必须检查项目上下文。
  6. 声称配置是最新或过时前必须刷新最新官方指南。
  7. 显式标记盲点。不得猜测隐藏或仅UI可见的设置。
  8. 当证据明确时，优先修改标准源而非生成或合并输出。
  9. 每个发现必须带有证据标签：
    verified-file
    、
    verified-doc
    、
    repo-observed
    或
    blind-spot
    。
  10. 当明确知道正确修改内容时，展示具体的补丁预览。
  11. 仅当安装确实是正确的下一步时，才使用
    npx skills add ...
    。
  12. 必须明确拒绝不支持的Harness并列出支持的集合。
  13. 生态系统研究仅为建议且只读。不得仅基于研究报告执行应用。
  14. 带凭证的API是可选的增强功能。缺少凭证会降低置信度但不阻止基线源规划。
  15. GitHub GraphQL可丰富已知候选仓库；广泛发现使用REST/search或代码/文件查找。
  16. 使用情况评审仅为建议且只读。不得仅基于使用发现结果执行配置修改、安装工具、导出原始会话或打印原始提示/跟踪。
  17. 使用情况评审可使用聚合安全和 sanitized 的元数据源，但机密文件、凭证值、原始转录本、原始跟踪和原始消息表内容不在范围内。