> Harness EngineeringHarness EngineeringHarness Engineering The engineering outside the model模型之外的工程模型之外的工程

0.2

A minimal harness in 30 minutes30 分鐘搭一個最小 harness30 分钟搭一个最小 harness

This chapter assumes you have used Copilot in agent mode on a project of your own, and that you read the first chapter or know the word "harness".

讀這一章,你需要在自己的專案裡用過 Copilot 的 agent 模式,並且讀過 差距在模型外面,或至少知道「harness」這個詞。

读这一章,需要你在自己的项目里用过 Copilot 的 agent 模式,并且读过第一章,或者知道“harness”这个词。

The Knowledge經驗分享经验分享

In one sentence

Start with one page of rules, one skill and one hook that blocks dangerous commands. Add more only when a real pain asks for it.

一句話

先從一頁規則、一個 skill 和一個擋危險指令的 hook 開始。有真的痛點了,再加別的。

一句话

先从一页规则、一个 skill、一个拦截危险命令的 hook 开始。真遇到痛点了,再往上加。

For leaders

  • The decision: start with the smallest set (one page of rules, one skill, one blocking hook) and let each later part be approved by a real pain, not by a plan.
  • The risk: a big harness built in one go costs maintenance and you cannot tell which part helped. A rule is only a request; a hook is a rule the model cannot argue with, but it stops only the commands it recognizes.
  • The cost of doing it right: by my estimate about half an hour for one person who already has a project open. A team adds review of the rule and hook files, like code.
  • Ask the team: "Which part of our setup came from a real failure, and which came from a template?"

給主管

  • 要做的決定:從最小的組合開始(一頁規則、一個 skill、一個會擋指令的 hook),之後每加一部分,都要由真的痛點來批准,不由計劃來批准。
  • 風險:一次搭出來的大 harness,維護起來很貴,而且你分不出哪一部分有用。規則只是請求;hook 是模型沒辦法跟它爭的規則,但它只擋得住它認得的指令。
  • 做對的成本:我估計一個已經打開專案的人,約半小時。團隊要另外加上像審程式碼那樣審規則檔和 hook 檔。
  • 可以問團隊:「我們的設定裡,哪一部分來自真的失敗,哪一部分來自範本?」

写给管理者

  • 要拍板的事:从最小的一套开始(一页规则、一个 skill、一个拦截的 hook),后面每加一样,都由真实的痛点来批,不由计划来批。
  • 风险:一口气搭一个大 harness,维护成本高,你也说不清哪一部分起了作用。规则只是请求;hook 是模型争不过的规则,但它只拦得住它认得的命令。
  • 做对的代价:据我估计,对一个已经打开了项目的人,大约半小时。团队还要像审代码一样,审规则文件和 hook 文件。
  • 可以问团队:“我们的配置里,哪些部分来自真实的失败,哪些来自模板?”

The problem

When people hear "harness", many picture a big system: two approval gates, a task board, a knowledge base, reports. Then they either give up or build all of it in one go. Both are mistakes.

A big harness has a price. Every part is something to write, to keep true, and to debug when it misfires. And you cannot tell which part helped, because you added them all at once. Mine did not start big. It grew one pain at a time, and I have since removed parts that bought nothing (chapter 7.3).

So this chapter is about the smallest set that is worth having, in the order I would build it. By my estimate it takes about half an hour if you already have a project open in VS Code.

問題

很多人聽到「harness」,想到的是一個大系統:兩道門:人在哪裡批准、同時管十件事:並行的是任務、知識庫、報告。然後他們不是放棄,就是一口氣全搭起來。兩種都是錯的。

大 harness 是有代價的。每一部分都要寫、要保持是對的、出錯時要除錯。而且你分不出哪一部分有用,因為你是一次全加進去的。我的 harness 不是一開始就大的。它是一次一個痛點長出來的,後來我也拿掉了沒買到東西的部分(見 我砍掉了什麼,數據怎麼說)。

所以這一章講的是值得擁有的最小組合,以及我會怎樣排出搭的順序。如果你已經在 VS Code 裡打開了專案,我估計大約要半小時。

问题

很多人一听到“harness”,脑子里就是一个庞大的系统:两道审批关卡、任务看板、知识库、报告。然后他们要么放弃,要么一口气全搭出来。这两样都是错的。

大 harness 是有代价的。每个部分都要写,要保持准确,出了毛病还要排查。而且你分不清哪一部分起了作用,因为是一次全加上的。我的 harness 不是一开始就大的。它是一个痛点一个痛点长出来的,后来我还删掉了一些没换来任何东西的部分(我砍掉了什么,数据怎么说)。

所以这一章讲的是值得拥有的最小一套,按我会搭的顺序来讲。据我估计,如果你已经在 VS Code 里打开了项目,大约要半小时。

How it works

One page of rules One skill One hook a request a manual, read on demand a rule, enforced Then add only what a real pain asks for ignores rules bill too high says done, fails forgets chapter 4.1 chapter 1.1 chapter 5.4 chapter 3.2
  1. Start small: a page of rules, one skill, one hook. Each holds the agent harder than the one before.
  2. Then work. When something hurts, you will know which pain it is.
  3. Each pain has a chapter. Add the part that answers it, and nothing else.
A minimal harness grows by pain, not by plan.

Why this order

The three parts differ in how hard they hold the agent.

  1. Rules come first. They cost a few minutes and no code. They tell the agent what it cannot guess: how your project is built, what not to touch. A rule is a request, and the model may ignore it, but in my experience it does what is written most of the time.
  2. A skill comes second. A skill is a short manual for one kind of job. The agent sees only its name and a one-line description at first, and reads the full text when a request matches. You need it because some knowledge is too long to put in the rules page: if every procedure sat there, the agent would carry all of it in every conversation (chapter 3.3 explains why that is expensive).
  3. A hook comes last. A hook is a small program the platform runs at fixed moments, for example just before the agent runs a tool. It can say no, and the model cannot argue with it. Rules and skills are requests. The hook is the first part that is a rule you can rely on. It is third because it is code you must write and maintain, so it should be spent on the few things that must never happen.

Step 1: one page of rules (about 10 minutes)

Create one instruction file at the root of your project. VS Code and Copilot read files such as AGENTS.md or .github/copilot-instructions.md and give them to the agent in every conversation. Check the current VS Code docs for the exact names it accepts.

Write only what the model would get wrong or miss: your project's own commands, limits and traps. Do not write what it already knows, such as how to write a loop in your language. Shorter is better, because a long rules file is easy for the model to ignore. One line is worth adding early: the command to run after a change (the tests, the linter) and "do not say done until it passes". It is the cheapest check there is (chapter 5.4).

A good first page has five to ten lines. The real file in my setup is longer, but its core limits look like this:

Two core limits from the shipped rules page: look before you act, and keep the user's own changes.
- Look at the real files before you act. Do not guess a path, a command, a setting or how to test.
- Keep the changes the user already made. Do not touch unrelated files.

How to check it works. Open a new chat and ask a question that only your rules can answer, such as "How do I run the tests in this project?" If it answers from your rules, the file is loaded. If it guesses, check the file name and location.

Step 2: one skill (about 10 minutes)

Pick a job you explained to the agent more than once. A skill is a folder with a SKILL.md file. The top of the file has a name and a description, and the description matters most. It decides whether the agent finds the skill at all. A good description says what the skill does, when to use it, and which words a user might say.

The top of a real skill: the name and the description are what the agent sees first.
---
name: generic-code-standards
description: 'Check the code of a task against the company''s code standards and fix what does not comply. The standards are written by the company in .harness/standards/code-standards.md; this skill only reads them. Use before the promote dry-run of a task that changed code, or when the user asks to check or fix code style, naming or conventions. Keywords: code standards, coding conventions, style check, lint, naming rules, comply with the rules.'
type: workflow
specificTo: generic
---

Below that, write the steps, and then a short list of traps: the places where the agent usually goes wrong. Adding a trap each time you see it fail is the most useful habit I know for skills (chapter 3.4).

How to check it works. Type / in the chat and look for the skill's name. Then say a request that matches the description without naming the skill, and see whether the agent uses it. A skill the agent never picks is usually a description problem.

Step 3: one hook that blocks dangerous commands (about 10 minutes)

The terminal is the most powerful tool an agent has, so start there. Pick commands whose damage you cannot undo, such as recursively deleting a folder, or downloading a script and running it in one line.

The setup has two parts. A configuration file tells the platform which moments to call your program at. In my setup there is one file, and every moment points at the same program:

The configuration for the moment before a tool runs: it just names the program to call.
    "PreToolUse": [
      {
        "type": "command",
        "command": "python3 .harness/engine/hook.py",
        "windows": "python .harness/engine/hook.py",
        "bash": "python3 .harness/engine/hook.py",
        "powershell": "python .harness/engine/hook.py",
        "cwd": ".",
        "timeout": 30,
        "timeoutSec": 30
      }
    ],

Your program reads the call it is given. If the command matches a pattern you blocked, it answers with a refusal and a reason. The reason matters: the agent sees it, so write what to do instead, or the agent will try the same thing again (chapter 4.2). Here is one of my patterns. It is long because the same command can be spelled many ways:

One real refusal rule: recursive force-delete of the root, home or current folder, with a reason the agent can read.
      {
        "why": {"en": "it recursively deletes the root, the home folder or the current folder", "zh": "递归删除根目录、家目录或当前目录"},
        "pattern": "{cmd}rm\\s+(?:-[a-z]+\\s+)*-[a-z]*(?:r[a-z]*f|f[a-z]*r)[a-z]*\\s+(?:/|~|\\$home|\\*|\\.|\\.\\.)/?\\*?(?:\\s|$|[;&|])"
      },

This is a real file, and it is far bigger than you need on day one. Start with three or four patterns.

How to check it works. Do not test it with a command that is actually dangerous. First add a harmless test rule, for example one that refuses the command echo hook-test, and ask the agent to run it. You should see a refusal with your reason. Then remove the test rule.

Three traps I know from my own hooks:

  • If the hook program cannot start (for example, the interpreter is not found), the platform counts it as a refusal, and the agent cannot use any tool at all. The screen only says the hook errored. Test it once before you rely on it.
  • If the hook runs past its time limit, the platform lets the call through, with no notice. In my setup the limit is 30 seconds. This fails open: a slow hook is a hole, so keep the program fast.
  • Configuration is read when the window starts. After you change it, reload the VS Code window.

What a hook cannot do is just as important. It sees a call, not what the command does once it runs (chapter 2.2). A pattern list stops the common spellings of a dangerous command, not every spelling. It is a seat belt, not a sandbox.

How much harness do you need?

It depends on who is affected when the agent gets it wrong.

You are Probably enough Why
One person on your own project The three parts above You see every change, and mistakes cost you only
A small team on a shared repository The three parts, with the rules and hook files reviewed like code, plus a place to record what the agent did Others inherit the agent's mistakes, and "who changed the rules" becomes a question (chapter 7.4)
A large team, or code with compliance duties The above, plus approval points, counted checks and reports, as your risks require A mistake costs others, and you must show what happened

I guess most readers are in the first row. Two approval gates and a task board are not a starting point.

What to add next, by pain

Do not read the rest of the book front to back. Wait until something hurts, then go to the chapter that matches.

The pain Read
The agent ignores a rule, again and again 4.1
A command asked for approval a hundred times, and you click Allow without reading 4.2
It says "done" and the tests fail 5.4
Long chats get worse and it forgets 3.2
The bill is higher than you expected 1.1
You want to split work across agents 2.3
You cannot tell what it did 6.1

Did it get better?

Do not trust a feeling. Choose a few tasks you know the right answer to, run them before and after each change, and score them the same way. Chapter 2.3 shows one such comparison, and Part 6 covers the method. Even a rough version, five tasks and a list of what "right" means, beats a guess. Write the list of what "right" means before you run, and run each task a few times, because one run can be luck (chapter 6.4).

原理

一頁規則 一個 skill 一個 hook 是請求 說明書,用到才讀 是規則,會強制 之後只加真實痛點要求的東西 不聽規則 帳單太高 說做完卻沒過 會忘 第 4.1 章 第 1.1 章 第 5.4 章 第 3.2 章
  1. 從小的開始:一頁規則、一個 skill、一個 hook。後面的比前面的管得更緊。
  2. 然後開始工作。哪裡痛,你自己會知道是哪一種痛。
  3. 每種痛都有對應的章。只加能回答它的那一部分。
最小的 harness 按痛點長大,不按計畫長大。

為什麼是這個順序

這三部分,抓住 agent 的力道不一樣。

  1. 規則放第一。它只要幾分鐘,不用寫程式。它告訴 agent 它猜不到的事:你的專案怎麼建、哪些東西不要碰。規則是請求,模型可能不理,但依我的經驗,它大多數時候會照寫的做。
  2. skill 放第二。 skill 是為某一類工作寫的一份簡短手冊。agent 一開始只看到它的名字和一行描述,需求對上了才去讀全文。你需要它,是因為有些知識太長,放不進規則那一頁:如果每個流程都放在那裡,agent 每次對話都得背著全部(指令與 skill:只載入需要的 說明了為什麼這樣很貴)。
  3. hook 放最後。 hook 是平台在固定時刻執行的小程式,例如在 agent 執行工具之前。它可以說不,而且模型沒辦法跟它爭。規則和 skill 都是請求。hook 是第一個你可以靠得住的規則。它排第三,是因為它是你得寫、得維護的程式碼,所以要把它用在少數絕對不能發生的事上。

第 1 步:一頁規則(約 10 分鐘)

在專案根目錄建一個指令檔。VS Code 和 Copilot 會讀 AGENTS.md 或 .github/copilot-instructions.md 這樣的檔案,並在每次對話都交給 agent。它接受哪些確切的檔名,請查目前的 VS Code 文件。

只寫模型會弄錯或漏掉的:你專案自己的指令、限制和陷阱。不要寫它本來就知道的,例如在你的語言裡怎麼寫迴圈。越短越好,因為太長的規則檔,模型很容易不理。有一行值得早點加:改完之後要執行的指令(測試、linter),再加上「通過之前,不要說做完了」。這是最便宜的檢查(讓 agent 能檢查自己的活)。

好的第一頁有五到十行。我的設定裡,真正的檔案比這長,但它的核心限制長這樣:

出貨規則頁裡的兩條核心限制:動手前先看,並保留使用者自己的改動。
- Look at the real files before you act. Do not guess a path, a command, a setting or how to test.
- Keep the changes the user already made. Do not touch unrelated files.

怎麼確認它有用。打開新的對話,問一個只有你的規則才答得出的問題,例如「這個專案怎麼執行測試?」如果它照你的規則回答,檔案就載入了。如果它在猜,就檢查檔名和位置。

第 2 步:一個 skill(約 10 分鐘)

挑一件你對 agent 解釋過不只一次的工作。skill 是一個資料夾,裡面有一個 SKILL.md 檔。檔案開頭有名字和描述,描述最重要。它決定 agent 找不找得到這個 skill。好的描述會寫:這個 skill 做什麼、什麼時候用、使用者可能會說哪些詞。

真實 skill 的開頭:agent 最先看到的是名字和描述。
---
name: generic-code-standards
description: 'Check the code of a task against the company''s code standards and fix what does not comply. The standards are written by the company in .harness/standards/code-standards.md; this skill only reads them. Use before the promote dry-run of a task that changed code, or when the user asks to check or fix code style, naming or conventions. Keywords: code standards, coding conventions, style check, lint, naming rules, comply with the rules.'
type: workflow
specificTo: generic
---

下面寫步驟,再寫一份簡短的陷阱清單:agent 通常會出錯的地方。每看到它失敗一次,就加一條陷阱,這是我所知道對 skill 最有用的習慣(把團隊的做法寫成 skill)。

怎麼確認它有用。在對話裡輸入 /,找 skill 的名字。然後說一個符合描述、但沒點名這個 skill 的需求,看 agent 有沒有用它。agent 從來不選的 skill,通常是描述的問題。

第 3 步:一個擋危險指令的 hook(約 10 分鐘)

終端機是 agent 最強的工具,所以從這裡開始。挑那些損害無法復原的指令,例如遞迴刪除一個資料夾,或者下載一個腳本並在同一行執行。

設定有兩部分。一個設定檔告訴平台,在哪些時刻呼叫你的程式。在我的設定裡只有一個檔,每個時刻都指向同一個程式:

工具執行前那個時刻的設定:只是寫出要呼叫哪個程式。
    "PreToolUse": [
      {
        "type": "command",
        "command": "python3 .harness/engine/hook.py",
        "windows": "python .harness/engine/hook.py",
        "bash": "python3 .harness/engine/hook.py",
        "powershell": "python .harness/engine/hook.py",
        "cwd": ".",
        "timeout": 30,
        "timeoutSec": 30
      }
    ],

你的程式讀取收到的呼叫。指令對上了你擋掉的樣式,它就回一個拒絕和一個原因。原因很重要:agent 看得到,所以要寫該改做什麼,不然 agent 會再試同一件事(詢問不是限制)。這是我的其中一條樣式。它很長,因為同一個指令有很多種寫法:

一條真實的拒絕規則:對根目錄、家目錄或目前資料夾做遞迴強制刪除,並附上 agent 讀得懂的原因。
      {
        "why": {"en": "it recursively deletes the root, the home folder or the current folder", "zh": "递归删除根目录、家目录或当前目录"},
        "pattern": "{cmd}rm\\s+(?:-[a-z]+\\s+)*-[a-z]*(?:r[a-z]*f|f[a-z]*r)[a-z]*\\s+(?:/|~|\\$home|\\*|\\.|\\.\\.)/?\\*?(?:\\s|$|[;&|])"
      },

這是一個真實的檔案,比你第一天需要的大得多。先從三、四條樣式開始。

怎麼確認它有用。不要拿真的危險的指令來測。先加一條無害的測試規則,例如拒絕指令 echo hook-test,再請 agent 執行它。你應該會看到帶著你寫的原因的拒絕。然後把測試規則移除。

我自己的 hook 有三個陷阱:

  • hook 程式啟動不了(例如找不到直譯器),平台會當成拒絕,agent 一個工具也用不了。畫面上只會說 hook 出錯。依賴它之前先測一次。
  • hook 執行超過時間限制,平台會放行這次呼叫,而且不會通知。在我的設定裡,限制是 30 秒。這是失效時放行:慢的 hook 就是一個洞,所以要讓程式快。
  • 設定是在視窗啟動時讀的。改完之後,重新載入 VS Code 視窗。

hook 做不到的事,同樣重要。它看到的是一次呼叫,看不到指令執行起來會做什麼(Hooks:每次呼叫都會經過的執行點)。樣式清單擋得住危險指令的常見寫法,擋不住每一種寫法。它是安全帶,不是沙箱。

你需要多少 harness?

看 agent 出錯時,誰會受影響。

你是 大概夠了 為什麼
一個人,做自己的專案 上面三部分 每個改動你都看得到,錯了只有你付代價
小團隊,共用一個倉庫 三部分,規則檔和 hook 檔像程式碼一樣審,再加一個記錄 agent 做了什麼的地方 別人會承接 agent 的錯,而「誰改了規則」成了問題(落地與治理)
大團隊,或有合規責任的程式碼 上面這些,再依你的風險加上兩道門:人在哪裡批准、讓「通過」可信和報告 錯了要別人付代價,而你必須拿得出發生了什麼

我猜大多數讀者在第一列。兩道批准的門和任務看板,都不是起點。

接下來按痛點加什麼

不要從頭到尾讀完整本書。等到有地方痛了,再去讀對得上的那一章。

痛點 讀
agent 一次又一次不理一條規則 提示裡的規則只是請求
一個指令問過上百次要不要批准,你不看就按了允許 詢問不是限制
它說「做完了」,測試卻失敗 讓 agent 能檢查自己的活
長對話越來越差,它會忘事 長對話會變差
帳單比你預期的高 選模型:算的是每次成功的成本
你想把工作拆給幾個 agent 慎用子 agent
你說不清它做了什麼 記下發生了什麼,不是 agent 說了什麼

有變好嗎?

不要信感覺。挑幾個你知道正確答案的任務,每次改動前後各跑一遍,用同樣的方式打分。慎用子 agent 展示了一個這樣的比較,第 6 部講方法。就算是粗糙的版本,五個任務加一份「怎樣算對」的清單,也比猜強。這份清單要在跑之前寫好,而且每個任務要跑幾次,因為一次可能只是運氣(一次運行證明不了什麼)。

原理

一页规则 一个 skill 一个 hook 是请求 手册,用到才读 是规则,会强制执行 之后只加真实的痛点要求的东西 不听规则 账单太高 说做完了却没过 会忘事 第 4.1 章 第 1.1 章 第 5.4 章 第 3.2 章
  1. 从小处开始:一页规则、一个 skill、一个 hook。后面的比前面的管得更紧。
  2. 然后开始干活。哪里痛,你自己会知道是哪一种痛。
  3. 每种痛都有对应的章。只加能解决它的那一部分。
最小的 harness 按痛点长大,不按计划长大。

为什么是这个顺序

这三样东西,对 agent 的约束力度不同。

  1. 规则排第一。它只要几分钟,不用写代码。它告诉 agent 那些它猜不到的事:你的项目是怎么搭的,什么不能碰。规则是请求,模型可能不理,但按我的经验,写下来的东西它大多数时候都会照做。
  2. skill 排第二。skill 是针对某一类工作的一份简短手册。agent 一开始只看到它的名字和一行描述,需求对得上时才去读全文。你需要它,是因为有些知识太长,放不进规则页:每个步骤都堆在那里,agent 每次对话都得背着全部内容(指令与 skill:只加载需要的讲了为什么这很贵)。
  3. hook 排最后。hook 是平台在固定时机运行的一个小程序,比如 agent 运行工具之前。它能说不,模型争不过它。规则和 skill 都是请求。hook 是第一样你能靠得住的规则。它排第三,是因为它是你要写、要维护的代码,所以应该留给那几件绝对不能发生的事。

第 1 步:一页规则(约 10 分钟)

在项目根目录建一个指令文件。VS Code 和 Copilot 会读 AGENTS.md 或 .github/copilot-instructions.md 这样的文件,并在每次对话里交给 agent。它具体认哪些文件名,请查当前的 VS Code 文档。

只写模型会搞错或者会漏掉的东西:你项目自己的命令、限制和坑。别写它本来就懂的,比如在你用的语言里怎么写循环。越短越好,因为太长的规则文件,模型很容易忽略。有一行值得早点加:改完之后要运行的命令(测试、lint),再加上“通过之前不许说做完了”。这是最便宜的检查(让 agent 能检查自己的活)。

好的第一页有五到十行。我配置里的真实文件更长,但它的核心限制是这样的:

自带规则页里的两条核心限制:动手之前先看,保留用户自己的改动。
- Look at the real files before you act. Do not guess a path, a command, a setting or how to test.
- Keep the changes the user already made. Do not touch unrelated files.

怎么确认它生效了。开一个新对话,问一个只有你的规则才答得出的问题,比如“这个项目里怎么跑测试?”如果它按你的规则回答,说明文件加载了。如果它在猜,检查文件名和位置。

第 2 步:一个 skill(约 10 分钟)

挑一件你给 agent 解释过不止一次的活。skill 是一个文件夹,里面有一个 SKILL.md 文件。文件开头有名字和描述,最重要的是描述。agent 能不能找到这个 skill,全看它。好的描述会说明这个 skill 做什么、什么时候用,以及用户可能会说哪些词。

一个真实 skill 的开头:agent 最先看到的,是名字和描述。
---
name: generic-code-standards
description: 'Check the code of a task against the company''s code standards and fix what does not comply. The standards are written by the company in .harness/standards/code-standards.md; this skill only reads them. Use before the promote dry-run of a task that changed code, or when the user asks to check or fix code style, naming or conventions. Keywords: code standards, coding conventions, style check, lint, naming rules, comply with the rules.'
type: workflow
specificTo: generic
---

描述下面写步骤,再写一小段坑的清单:agent 通常会在哪些地方出错。每次看到它失败就加一条坑,是我知道的写 skill 最有用的习惯(把团队的做法写成 skill)。

怎么确认它生效了。在对话里输入 /,看有没有这个 skill 的名字。然后说一个符合描述、但不点名这个 skill 的需求,看 agent 会不会用它。agent 一直不选的 skill,通常是描述的问题。

第 3 步:一个拦截危险命令的 hook(约 10 分钟)

终端是 agent 手里最厉害的工具,所以从这里下手。挑那些造成的损害无法撤销的命令,比如递归删除一个文件夹,或者下载一个脚本、一行命令就运行。

这要分两部分。一个配置文件告诉平台,在哪些时机调用你的程序。在我的配置里只有一个文件,每个时机都指向同一个程序:

工具运行之前那个时机的配置:它只是写明了要调用哪个程序。
    "PreToolUse": [
      {
        "type": "command",
        "command": "python3 .harness/engine/hook.py",
        "windows": "python .harness/engine/hook.py",
        "bash": "python3 .harness/engine/hook.py",
        "powershell": "python .harness/engine/hook.py",
        "cwd": ".",
        "timeout": 30,
        "timeoutSec": 30
      }
    ],

你的程序读取收到的调用。如果命令符合你拦截的某个模式,它就回复一个拒绝,并附上原因。原因很重要:agent 看得到它,所以要写明应该改做什么,否则 agent 会再试同样的事(询问不是限制)。下面是我的一个模式。它很长,因为同一条命令有很多种写法:

一条真实的拒绝规则:对根目录、主目录或当前文件夹做递归强制删除,附上 agent 看得懂的原因。
      {
        "why": {"en": "it recursively deletes the root, the home folder or the current folder", "zh": "递归删除根目录、家目录或当前目录"},
        "pattern": "{cmd}rm\\s+(?:-[a-z]+\\s+)*-[a-z]*(?:r[a-z]*f|f[a-z]*r)[a-z]*\\s+(?:/|~|\\$home|\\*|\\.|\\.\\.)/?\\*?(?:\\s|$|[;&|])"
      },

这是个真实的文件,比你第一天需要的大得多。先写三四个模式就够了。

怎么确认它生效了。别拿真正危险的命令来测。先加一条无害的测试规则,比如拒绝命令 echo hook-test,然后让 agent 运行它。你应该看到一个带着你写的原因的拒绝。测完把这条测试规则删掉。

我自己的 hook 踩过三个坑:

  • hook 程序启动不了(比如找不到解释器),平台会把它当作拒绝,agent 一个工具也用不了。屏幕上只写着 hook 出错。在你依赖它之前,先测一次。
  • hook 运行超过时间限制,平台会放行这次调用,而且不提醒。在我的配置里,限制是 30 秒。这是故障放行:慢的 hook 就是个漏洞,所以让程序保持快。
  • 配置是在窗口启动时读的。改完配置,要重新加载 VS Code 窗口。

hook 做不到什么,同样重要。它看到的是一次调用,看不到命令运行起来之后做了什么(Hook:每次调用都会经过的执行点)。一份模式清单拦得住危险命令的常见写法,拦不住所有写法。它是安全带,不是沙箱。

你需要多大的 harness?

这取决于 agent 出错时,谁会受影响。

你是 大概够用的 原因
在自己的项目上单干的一个人 上面这三样 每处改动你都看得到,出错的代价只有你自己担
在共享仓库上的小团队 这三样,规则文件和 hook 文件像代码一样审,再加一个记录 agent 做了什么的地方 别人会承接 agent 的错误,而“谁改了规则”会成为一个问题(落地与治理)
大团队,或者有合规义务的代码 以上这些,再按你的风险需要加审批点、可计数的检查和报告 出错的代价由别人承担,而且你得拿得出发生了什么

我猜大多数读者属于第一行。两道审批关卡和一个任务看板,不是起点。

接下来按痛点加什么

别把这本书从头读到尾。等哪里疼了,再去读对应的章。

痛点 读
agent 一次又一次无视某条规则 4.1
一条命令弹了一百次审批,你不看就点“允许” 4.2
它说“做完了”,测试却是失败的 5.4
长对话越聊越差,它还忘事 3.2
账单比预想的高 1.1
你想把工作分给多个 agent 2.3
你说不清它做了什么 6.1

变好了吗?

别信感觉。挑几个你知道正确答案的任务,每次改动前后各跑一遍,用同样的方式打分。慎用子 agent给出了这样的一个对比,第 6 部分讲方法。哪怕是粗糙的版本,五个任务加一张“什么算对”的清单,也比猜强。“什么算对”的清单要在运行之前写好,每个任务要跑几次,因为一次运行可能只是运气(一次运行证明不了什么)。

Costs and traps

The first page of rules grows and goes stale. People add a line for every incident. After a while it is long, parts contradict each other, and the model ignores it. Cut it back from time to time and keep each rule in one place.

A hook gives false comfort. It stops what it recognizes. Do not describe it as "the agent cannot delete things". Describe it as "the agent cannot run these specific commands".

I have not tested every VS Code setting. File names, hook support and settings change between versions. The steps above work in my setup; check the current docs for yours.

代價和陷阱

第一頁規則會越長越舊。大家每出一次事故,就加一行。過一陣子它變長了,有的互相矛盾,模型就不理它。要不時刪減,每條規則只放在一個地方。

hook 會給人虛假的安心。它只擋它認得的。不要把它說成「agent 不能刪東西」,要說成「agent 不能執行這幾個特定的指令」。

VS Code 的設定,我沒有每一項都測過。檔名、hook 的支援和設定,不同版本之間會變。上面的步驟在我的設定裡行得通;你的請查目前的文件。

代价和坑

规则的第一页会越写越长,也会过期。每出一次事故,人们就加一行。过一阵它就很长了,有的互相矛盾,模型也就不理它了。时常删减一下,让每条规则只在一个地方。

hook 会带来虚假的安心。它只拦它认得的东西。别说“agent 删不了东西”,要说“agent 不能运行这几条具体的命令”。

我没有测过 VS Code 的每一项设置。文件名、hook 的支持情况和设置,在不同版本之间会变。上面的步骤在我的配置里能用;你的请查当前的文档。

When to delete it Industry practice

Every part of this starter set is on the list of things platforms are absorbing. When the platform's own permission system refuses the same dangerous commands out of the box, drop your hook. When it learns your project's commands by itself, shorten your rules page. Re-read your rules after every major model upgrade (chapter 6.5); lines written for an older model may be dead weight.

什麼時候可以刪掉 業界做法

這組入門的每一部分,都在平台正在吸收的清單上。等平台自己的權限系統,開箱就拒絕同樣的危險指令,就丟掉你的 hook。等它自己學會你專案的指令,就把你的規則頁縮短。每次大的模型升級之後,重讀你的規則(模型升級了,就要刪);為舊模型寫的行,可能已經是累贅。

什么时候可以删掉 业界做法

这套入门配置里的每一样,都在平台正在吸收的清单上。等平台自己的权限系统开箱就能拒绝同样的危险命令,就把你的 hook 删掉。等它自己学会了你项目的命令,就把你的规则页缩短。每次大的模型升级之后,都重读一遍你的规则(模型升级了,就要删);为旧模型写的那些行,可能已经成了累赘。

Try it on your own setup

No harness needed. Open your agent in your own repository and paste:

Check this repository against a minimal setup of three parts: one short page of rules, one skill, one blocking hook. For each part, say whether it exists, where, and whether it works. For the rules, list lines that are long, stale or contradict each other, and say which commands and limits the model could not guess are missing. For the hook, list which irreversible commands (such as recursive delete) nothing stops. Do not change any files.

在你自己的環境試試

不用裝 harness。在你自己的倉庫裡打開 agent,貼上:

用一個最小設定的三部分來檢查這個倉庫:一頁簡短的規則、一個 skill、一個會擋指令的 hook。每一部分都說明有沒有、在哪裡、能不能用。規則的部分,列出太長、過期或互相矛盾的行,並說明缺了哪些模型猜不到的指令和限制。hook 的部分,列出哪些不可逆的指令(例如遞迴刪除)沒有任何東西擋住。不要改任何檔案。

在你自己的环境里试试

不用装 harness。在你自己的仓库里打开 agent,粘贴:

对照一套三部分的最小配置,检查这个仓库:一页简短的规则、一个 skill、一个拦截的 hook。每一部分,说明它在不在、在哪、有没有用。对规则,列出又长、又过期或者互相矛盾的行,并指出缺了哪些模型猜不到的命令和限制。对 hook,列出哪些不可逆的命令(比如递归删除)没有任何东西拦着。不要修改任何文件。

Go deeper

延伸閱讀

延伸阅读

You can stop here: that is the whole idea. The next part shows where it runs, so you can look inside.讀到這裡就夠了,這就是整個想法。下一部分告訴你它在哪裡運行,可以進去看看。读到这里就够了,核心思路就是这些。下一部分告诉你它在哪里跑,可以进去看看。

In my practice (Copilot Harness)實作实战

Copilot Harness is my open-source harness for VS Code Copilot.

Repository: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

Get started: clone it, open it in VS Code, and type /harness-rookie-get-me-ready in Copilot Chat. You need Python 3.9 or later and git.

Copilot Harness 是我開源的 VS Code Copilot harness。

倉庫: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

開始:clone 下來,用 VS Code 打開,在 Copilot Chat 裡輸入 /harness-rookie-get-me-ready。需要 Python 3.9 以上和 git。

Copilot Harness 是我开源的 VS Code Copilot harness。

仓库: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

上手:把仓库 clone 下来,用 VS Code 打开,在 Copilot Chat 里输入 /harness-rookie-get-me-ready。需要 Python 3.9 及以上版本和 git。

Explore it in the harness

My own setup is the grown-up version of this chapter: a rules page, many skills, and a hook that guards every tool call. The harness can show you each one from the inside, and help you set up your own. After the setup above, type:

/harness-rookie-wondering I have read the chapter "A minimal harness in 30 minutes". Teach me how this harness does its rules page, its skills and its hook. Open the real files with me, show me how the hook refuses a command, and help me see what I could copy into my own project.

It teaches one small piece at a time, stops to ask if you are following, and opens the files with you.

在 harness 裡探索

我自己的設定,就是這一章的成熟版:一頁規則、很多 skill,以及一個守著每次工具呼叫的 hook。harness 可以從裡面把每一項展示給你看,也能幫你設定自己的。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「30 分鐘搭一個最小 harness」這一章。請教我這個 harness 怎麼做它的規則頁、skill 和 hook。每一項都帶我打開真實的檔案,讓我看 hook 怎麼拒絕一個指令,並幫我看出哪些可以抄進自己的專案。

它一次教一小塊,停下來確認你跟得上,然後和你一起打開檔案。

在 harness 里探索

我自己的配置,就是这一章的成熟版:一页规则、许多 skill,以及一个守着每次工具调用的 hook。harness 可以从内部带你逐个看,也能帮你配置你自己的。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“30 分钟搭一个最小 harness”这一章。请教我这个 harness 的规则页、skill 和 hook 是怎么做的。带我打开真实的文件,让我看 hook 是怎么拒绝一条命令的,并帮我看清哪些东西我可以抄进自己的项目。

它一次只教一小块,停下来确认你跟上了,再和你一起打开文件。