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

6.1

Record what happened, not what the agent said記下發生了什麼,不是 agent 說了什麼记下发生了什么,而不是 agent 说了什么

This chapter assumes you have used an AI coding agent, such as Copilot in agent mode. Nothing else.

讀這一章,你需要用過 AI 寫程式的 agent,例如 agent 模式的 Copilot。不需要別的。

读这一章,只需要用过一个写代码的 AI agent,比如 Copilot 的 agent 模式。别的都不需要。

The Knowledge經驗分享经验分享

In one sentence

An agent's summary can be wrong; a log can be checked. Record every call (one line each, without its arguments) and every refusal, and when something fails, read the trace.

一句話

agent 的總結可能是錯的,紀錄可以查。每一次呼叫記一行(不記參數),每一次拒絕也記下來;出了問題,就去讀軌跡。

一句话

agent 自己写的总结可能是错的,日志却可以核对。记下每一次调用(每次一行,不含参数)和每一次拒绝;出了问题,就去读轨迹。

For leaders

  • The decision: require that every agent task leaves a record written by code, and decide who reads it and when.
  • The risk: the agent's own summary is then the only account of what happened, and a summary can be wrong. In the one run I read closely (one run, not a pattern), the agent's own account said nothing about the handover that cost the most.
  • The cost of doing it right: one small program that writes a line per tool call, plus someone's time to read the record when a run fails. Mostly setup time.
  • Ask the team: "For the last task that mattered, show me what the agent did from the record, not from its summary."

給主管

  • 要做的決定:要求每個 agent 任務都留下由程式寫的紀錄,並決定誰在什麼時候讀它。
  • 風險:不這樣做,agent 自己的總結就是唯一的說法,而總結可能是錯的。在我仔細讀過的那一次運行裡(只有一次,不是通則),agent 自己的說法,沒有提到花得最多的那次交接。
  • 做對的成本:一個小程式,每次工具呼叫寫一行;再加上運行失敗時,有人花時間讀紀錄。大多是設定的時間。
  • 可以問團隊:「上一個重要的任務,請你用紀錄,不是用 agent 的總結,告訴我它做了什麼。」

写给管理者

  • 要拍板的事:要求每个 agent 任务都留下一份由代码写的记录,并决定谁来读、什么时候读。
  • 风险:否则 agent 自己的总结就成了对发生过什么的唯一说法,而总结可能是错的。在我仔细读过的那一次运行里(只是一次,不是规律),agent 自己的说法对花得最多的那次交接只字未提。
  • 做对的代价:一个小程序,每次工具调用写一行;再加上运行失败时有人花时间去读记录。主要是搭建的时间。
  • 可以问团队:“拿最近一个重要的任务,给我看 agent 做了什么,要从记录里看,不要看它的总结。”

The problem

At the end of a task the agent writes something like: "I changed three files, ran the tests, and they pass." That is a story about what happened, told by the one who did it. Most of the time it is right. When it is wrong, you cannot tell from the story alone.

Three words first.

  • A log is a list of what happened, written down at the moment it happened, one line per event.
  • A trace is the log of one run, read from the first call to the last: what the agent did, in order.
  • A record is any such written-down fact that you can look at later. In this chapter, "record" means something the agent did not write.

The idea is simple. When a fact matters, get it from a record that code wrote, not from the agent's own words. I used this idea first in Use subagents sparingly. There I read the records of the runs to see where the extra money in the three-role team went. In the one run I read closely (so this is one run, not a pattern), the agent's own account said nothing about the handover that cost the most. And a later chapter, Make a pass count, rests on the same thing: the checker's answer is saved by code, not by the agent.

So the question is what to record, who writes it, and how to read it when a run goes wrong.

問題

任務結束時,agent 會寫類似這樣的話:「我改了三個檔案,跑了測試,都通過。」這是做事的那一方講的、關於發生了什麼的故事。多半是對的。錯的時候,光看這個故事,你分辨不出來。

先交代三個詞。

  • 日誌(log)是一份清單,記下發生的事,在事情發生的當下寫,每件事一行。
  • 軌跡(trace)是一次運行的日誌,從第一次呼叫讀到最後一次:agent 依序做了什麼。
  • 紀錄是任何這類寫下來、以後可以回頭看的事實。在這一章裡,「紀錄」指的是不是 agent 寫的東西。

想法很簡單。一件事重要的時候,要從程式寫的紀錄去查,不要聽 agent 自己怎麼說。我第一次用這個想法,是在 慎用子 agent。我讀了那些運行的紀錄,看三角色團隊多花的錢花到哪裡去。在我仔細讀過的那一次運行裡(所以是一次,不是通則),agent 自己的說法,沒有提到花得最多的那次交接。後面的 讓「通過」可信 也建立在同一件事上:檢查者的答案由程式存下來,不是由 agent 存。

所以問題是:記什麼、誰來寫、運行出錯時怎麼讀。

问题

任务结束时,agent 会写类似这样的话:“我改了三个文件,跑了测试,通过了。”这是干活的人讲的、关于发生了什么的一个故事。多数时候它是对的。它错了的时候,光看这个故事,你看不出来。

先说三个词。

  • 日志,是发生了什么的清单,在事情发生的当下写下,一件事一行。
  • 轨迹,是一次运行的日志,从第一次调用读到最后一次:agent 按顺序做了什么。
  • 记录,是任何这样写下来、之后可以回头看的事实。在这一章里,“记录”指的是不是 agent 写的东西。

想法很简单。一个事实要紧的时候,就从代码写的记录里拿,不要拿 agent 自己的话。我最早用这个想法,是在慎用子 agent里。我读了那些运行的记录,看三个角色的团队多花的钱去了哪里。在我仔细读过的那一次运行里(所以这是一次运行,不是规律),agent 自己的说法对花得最多的那次交接只字未提。后面的一章,让“通过”可信,也建立在同一件事上:检查者的回答由代码保存,不由 agent 保存。

所以问题是:记什么,谁来写,运行出错时怎么读。

How it works

The log is written by code that the agent does not control

A hook is a small program that the tool runs at fixed moments, for example just before each tool call, where it can refuse a command before it runs, and just after. (Hooks says how they work and where they have gaps.) A hook is a good place to write the log, for two reasons. It runs on every call, so nothing depends on the agent remembering to write something down. And the agent's tools do not write the log, the hook does; the files that hold it can be put out of the agent's reach like any other protected file (Guard the files that hold the rules). This holds only while the hook sees the call and the fence holds. See the gaps in Costs below.

What each line holds is a choice. In my setup there is one line per hook call:

  • The event: before a call, after a call, a prompt, the agent stopping.
  • The kind of tool: read, edit, run a command, start a subagent.
  • The result: let through, or refused, and which rule refused it.
  • The time it took.
  • The skills used. Using a skill is one tool call, so it shows up for free.

What the log leaves out is as deliberate as what it keeps. It does not record the arguments of a call or the text of the prompts, because those can hold code or secrets. The exception is a call that was refused or needed a person's confirmation: for that one, the path and the command are recorded, cut to a fixed length. The reason is simple. When something was refused, the one thing you will want to know is what the agent tried. The logs stay on the computer and are not put into git. Old ones can be deleted.

There is a middle way that I have not built: keep the light line for every call, and switch on a full record (arguments and all) only for refused calls, for one task you are debugging, or when a switch is on. That keeps the secrets out by default and still gives you something to replay when it matters. A full transcript of the run is better than any log for this, because it shows what the agent saw and said between the calls; the log tells you which transcript to open.

Reading a bad run

This is the part that earns the whole chapter. A run failed, or went strangely. You have the trace. What do you do with it?

  1. Start from the symptom, not from the start of the log. What was wrong with the result? Which file, which turn?
  2. Find the first refusal or failed call. A rule that refused something is a clue. A tool that failed and was retried is another. Many bad runs begin with one small refusal that the agent worked around in a way nobody wanted.
  3. Put the agent's account next to the record. Did it say it ran the tests? Is there a call that ran them? Did it say a file was untouched? Is there an edit of that file? Where the two disagree, believe the record.
  4. Look at where the time and usage jump. One prompt that took far longer than the others, or one turn that read the same files again, tells you where the run went off course.
  5. Decide which kind of problem it is. A missing rule? A rule the agent could not understand? A refusal message that did not say what to do instead? A step the model is simply bad at? The fix depends on the answer, and a trace is how you get to the answer instead of guessing.

For example, suppose the agent's last message says "the tests pass", and the log has no call that ran a test command. Step 3 catches that in a minute, and no amount of reading the message would.

Anthropic makes the same point about evaluations: "You won't know if your graders are working well unless you read the transcripts and grades from many trials." (Demystifying evals for AI agents)

Eight questions

Once the log exists, other records can grow around it. In my setup there are eight, and the clearest way to see why is to list the question each one answers. If you build only one thing, build the hook log, with the refusals in it.

THE QUESTION WHAT ANSWERS IT What happened on each call? the session log How many calls, refusals? stats over the logs Which knowledge files get read? a reading record What did a task do? Who approved? the task report Where did time and usage go? an analysis page Which task waits for me? the board Is the setup itself healthy? a health check Did behaviour change after edits? fixed scenarios
Eight questions, eight records. The first one, the log of every call, is what the others are built on.

I did not plan eight. Each was added because I kept asking the question and had no way to answer it. Two are worth a word, and the third is one line.

  • The reading record (of the knowledge base, see A knowledge base: an honest index of the code) answers "which knowledge-base files does the agent read, and which does nobody read?" It is the one exception to "a call that is let through records nothing about what it touched": it keeps file names only, and it can be switched off. A file that nobody reads is a candidate for deletion.
  • The health check is the odd one. It does not look at the agent. It looks at the setup: are all the files there, are the rule files valid, does the hook run (it runs it once, for real), when was it last called, and is the slowest recent call too close to its time limit? Its output has three grades: fine, warning (does not block), error (must be fixed). It finds problems after the fact; it cannot prevent them.
  • The fixed scenarios answer "did the behaviour change after I changed something?" That is the next chapters. The other four records are listed in the picture.

Tokens and time

A hook sees calls, not how many tokens the model read. In my setup the hook log records no tokens, on purpose: the platform keeps its own record of time and usage, and a second copy would drift. The page that shows where a task's time and usage went reads that platform record, and falls back to times from the hook log when it cannot. Whatever you read usage from, find out what it counts: the main conversation's number may not include the subagents' (Use subagents sparingly has the same warning).

When the recorder fails

The hook is software, and it will fail. In my setup, when the hook itself fails it lets the call through and writes the error into a separate file; the health check reminds me to look. That was a deliberate choice, and Build the enforcement layer like software says why it fits a coding harness and what to do where it does not. For a recorder it is easy to accept: a missed log line is a gap in the evidence, not an accident. But know it: a log with no lines in a period can mean "nothing happened" or "the recorder was down". The error file is how you tell them apart.

Test your own setup

Three questions:

  1. For the last agent task that mattered, can you say what it did from a record, not from its summary?
  2. If it had done something you did not want, would you have found out, and when?
  3. Does your record say what was refused, or only what succeeded?

A test you can run today, with no extra setup. Ask your agent to do a small task and to say at the end which commands it ran. Then look at your tool's own history of tool calls (where it shows is different in each tool, and I have not checked each). Compare the two lists. If they match, you have learned how much to trust the summary on this kind of task. If they do not, you have found out why you want a record.

原理

日誌由 agent 控制不了的程式來寫

hook 是工具在固定時刻執行的小程式,例如每次工具呼叫之前(這時它可以在指令執行前拒絕它),和之後。(Hooks:每次呼叫都會經過的執行點 講它怎麼運作、哪裡有缺口。)hook 很適合用來寫日誌,有兩個原因。它每次呼叫都會執行,所以不用靠 agent 記得寫下什麼。而且寫日誌的是 hook,不是 agent 的工具;放日誌的檔案,可以像其他受保護的檔案一樣,放到 agent 碰不到的地方(保護規則本身的檔案)。這只在 hook 看得到呼叫、圍欄守得住的時候成立。缺口見下面的「代價」。

每一行放什麼,是一個選擇。在我的設定裡,每次 hook 呼叫一行:

  • 事件:呼叫之前、呼叫之後、一個 prompt、agent 停下來。
  • 工具的種類:讀、改、執行指令、啟動子 agent。
  • 結果:放行,或拒絕,以及是哪條規則拒絕的。
  • 花了多久。
  • 用了哪些 skill。用 skill 就是一次工具呼叫,所以不用額外做就會出現。

日誌不記什麼,和它記什麼一樣是刻意的。它不記呼叫的參數,也不記 prompt 的文字,因為那些可能含有程式碼或機密。例外是被拒絕、或需要人確認的呼叫:這種呼叫會記下路徑和指令,並截成固定長度。理由很簡單。有東西被拒絕時,你唯一想知道的,就是 agent 想做什麼。日誌留在電腦上,不放進 git。舊的可以刪。

有一條折衷的路,我還沒做:每次呼叫都記輕的一行;只在被拒絕的呼叫、你正在除錯的某個任務、或開關打開的時候,才開啟完整紀錄(連參數都有)。這樣預設不會留下機密,需要時又有東西可以重播。為了這個目的,一次運行的完整對話紀錄比任何日誌都好,因為它顯示 agent 在兩次呼叫之間看到了什麼、說了什麼;日誌告訴你該打開哪一份。

讀一次出錯的運行

整章的價值在這一段。一次運行失敗了,或是怪怪的。你手上有軌跡。要拿它做什麼?

  1. 從症狀開始,不要從日誌的開頭開始。結果哪裡不對?哪個檔案、哪一輪?
  2. 找第一次拒絕或失敗的呼叫。一條規則拒絕了什麼,是一條線索。一個工具失敗後又重試,是另一條。很多壞掉的運行,起點都是一次小小的拒絕,agent 用沒人想要的方式繞了過去。
  3. 把 agent 的說法和紀錄放在一起看。它說跑了測試,有沒有一次呼叫跑了測試?它說某個檔案沒動,有沒有改過那個檔案的紀錄?兩者不一致的地方,相信紀錄。
  4. 看時間和用量在哪裡跳高。某一個 prompt 花的時間比其他的長很多,或某一輪又把同樣的檔案讀了一遍,就告訴你運行是在哪裡走偏的。
  5. 判斷這是哪一種問題。少了一條規則?一條 agent 看不懂的規則?一則沒說該改做什麼的拒絕訊息?還是模型單純不擅長的一步?怎麼修,取決於答案;有軌跡,你是找到答案,不是猜。

舉個例子:agent 的最後一則訊息說「測試通過」,日誌裡卻沒有任何一次呼叫執行過測試指令。第 3 步一分鐘就抓到,讀再多遍那則訊息也看不出來。

Anthropic 對評測也說過同樣的話:「你不讀很多次試驗的對話紀錄和評分,就不會知道你的評分器有沒有在好好工作。」(Demystifying evals for AI agents)

八個問題

日誌有了之後,其他紀錄可以圍著它長出來。在我的設定裡有八種,最清楚的看法,是列出每一種回答哪個問題。如果你只做一件事,就做 hook 日誌,並把拒絕記進去。

問題 誰來回答 每次呼叫發生了什麼? 工作階段紀錄 多少提示、呼叫、拒絕? 對紀錄做統計 哪些知識庫檔案被讀過? 讀取紀錄 這個任務做了什麼?誰批准? 任務報告 時間和用量花在哪? 分析頁 哪個任務在等我? 看板 設定本身健康嗎? 健康檢查 我改完之後,行為變了嗎? 固定情境
八個問題,八種紀錄。第一種,記下每次呼叫的紀錄,是其他幾種的基礎。

我沒有計畫要八種。每一種都是因為我一直在問那個問題,卻沒有辦法回答才加的。其中兩種值得多說一句,第三種只用一行帶過。

  • 讀取紀錄(知識庫的,見 知識庫:程式碼的誠實索引)回答「agent 讀了哪些知識庫檔案,哪些沒人讀?」它是「放行的呼叫不記它碰了什麼」這條的唯一例外:它只記檔名,而且可以關掉。沒人讀的檔案,是可以刪的候選。
  • 健康檢查是個特別的。它不看 agent,它看設定:檔案都在嗎、規則檔有效嗎、hook 能執行嗎(它真的執行一次)、上次呼叫是什麼時候、最近最慢的一次呼叫是不是太接近時間上限?它的輸出分三級:正常、警告(不擋)、錯誤(必須修)。它是事後發現問題,沒辦法預防。
  • 固定情境回答「我改了東西之後,行為有沒有變?」那是 固定的任務,用腳本打分 和後面幾章。其他四種紀錄,列在圖裡。

token 和時間

hook 看到的是呼叫,看不到模型讀了多少 token。在我的設定裡,hook 日誌刻意不記 token:平台自己有時間和用量的紀錄,再留一份只會對不上。顯示一個任務的時間和用量花在哪裡的那一頁,讀的是平台的紀錄,讀不到時就退回用 hook 日誌裡的時間。不管你從哪裡讀用量,都要先弄清楚它算了什麼:主對話的數字,可能不含子 agent 的(慎用子 agent 有同樣的提醒)。

記錄器壞掉的時候

hook 是軟體,會壞。在我的設定裡,hook 自己失敗時會放行這次呼叫,並把錯誤寫進另一個檔案;健康檢查會提醒我去看。這是刻意的選擇,把執行層當軟體來設計 說了為什麼它適合寫程式的 harness,以及不適合時該怎麼辦。對記錄器來說,這很容易接受:少一行日誌,是證據裡的一個缺口,不是一場事故。但要知道這件事:某段時間日誌沒有任何一行,可能表示「什麼都沒發生」,也可能表示「記錄器停了」。錯誤檔就是用來分辨這兩種的。

測你自己的設定

三個問題:

  1. 上一個重要的 agent 任務,你能不能用紀錄,而不是它的總結,說出它做了什麼?
  2. 如果它做了你不想要的事,你會發現嗎?什麼時候發現?
  3. 你的紀錄有沒有記被拒絕的,還是只記成功的?

今天就能跑的測試,不用額外設定。請你的 agent 做一件小任務,並在最後說出它執行了哪些指令。然後去看你的工具自己的工具呼叫歷史(顯示在哪裡,每個工具都不同,我沒有一一確認過)。比對兩份清單。如果一致,你就知道在這類任務上,可以多信任總結一點。如果不一致,你就知道為什麼需要紀錄了。

原理

日志由 agent 控制不了的代码来写

hook 是工具在固定时刻运行的一个小程序,比如在每次工具调用之前(它可以在命令运行之前拒绝它),以及之后。(hook 怎么工作、哪里有缺口,见 Hook:每次调用都会经过的执行点。)hook 是写日志的好地方,有两个原因。它在每次调用时都运行,所以不用指望 agent 记得写点什么。而且 agent 的工具不写日志,是 hook 写;存放日志的文件,可以像其他受保护的文件一样放到 agent 够不着的地方(见保护规则本身的文件)。这只在 hook 看得到这次调用、围栏也守得住的时候成立。缺口见下面的“代价”。

每一行装什么,是个取舍。在我的配置里,每次 hook 调用一行:

  • 事件:调用前、调用后、一个 prompt、agent 停下。
  • 工具的种类:读、改、运行命令、启动子 agent。
  • 结果:放行,还是拒绝,以及是哪条规则拒绝的。
  • 花的时间。
  • 用到的 skill。用 skill 本身就是一次工具调用,所以不用额外做什么就能看到。

日志不记什么,和它记什么一样是有意为之。它不记调用的参数,也不记 prompt 的文字,因为那些里面可能有代码或密钥。例外是被拒绝、或需要人确认的调用:这种调用会记下路径和命令,截成固定长度。理由很简单。出现拒绝的时候,你唯一想知道的就是 agent 试了什么。日志留在本机,不放进 git。旧的可以删。

有一条折中的路我还没搭:对每次调用保留那一行简短的,只在被拒绝的调用、你正在调试的某一个任务、或者开关打开的时候,才打开完整的记录(参数等全都记)。这样默认不留密钥,真需要时又有东西可以回放。这件事上,运行的完整对话记录比任何日志都好,因为它显示了调用之间 agent 看到了什么、说了什么;日志告诉你该打开哪一份对话记录。

怎么读一次糟糕的运行

整章的价值就在这一部分。一次运行失败了,或者跑得很奇怪。你手上有轨迹。怎么用它?

  1. 从症状开始,不要从日志开头开始。结果哪里不对?哪个文件,哪一轮?
  2. 找到第一次拒绝或失败的调用。拒绝了什么的规则是一条线索。失败后又重试的工具是另一条。很多糟糕的运行,都是从一次小小的拒绝开始,agent 绕了过去,绕的方式没有人想要。
  3. 把 agent 的说法放在记录旁边。它说跑了测试?有没有一次调用真的跑了测试?它说某个文件没动?有没有对那个文件的修改?两者不一致的地方,相信记录。
  4. 看时间和用量在哪里陡增。某一个 prompt 比其他的久得多,或者某一轮又把同样的文件读了一遍,就告诉你运行是在哪里偏离的。
  5. 判断是哪一种问题。缺了一条规则?一条 agent 看不懂的规则?一条没说该改做什么的拒绝信息?还是模型本来就不擅长的一步?怎么修取决于答案,而轨迹让你得到答案,而不是瞎猜。

比如,agent 最后一条消息说“测试通过了”,日志里却没有一次调用运行过测试命令。第 3 步一分钟就能抓出来,把那条消息读上多少遍也看不出来。

Anthropic 在评测上也说了同样的话:“除非你读了很多次试验的对话记录和评分,否则你不会知道你的评分器工作得好不好。”(Demystifying evals for AI agents)

八个问题

有了日志,别的记录就可以围着它长出来。我的配置里有八种,看清为什么,最好的办法是列出每一种回答的问题。如果你只做一样,就做 hook 日志,把拒绝记在里面。

问题 谁来回答 每次调用发生了什么? 会话日志 多少调用、拒绝? 对日志做统计 哪些知识库文件被读过? 读取记录 这个任务做了什么?谁审批? 任务报告 时间和用量花在哪? 分析页 哪个任务在等我? 看板 配置本身健康吗? 健康检查 我改完之后,行为变了吗? 固定场景
八个问题,八种记录。第一种,记下每次调用的日志,是其他几种的基础。

八种不是我规划出来的。每一种,都是因为我一再问同一个问题,又没有办法回答,才加上的。其中两种值得说一句,第三种一行就够。

  • 读取记录(针对知识库,见知识库:代码的诚实索引)回答“agent 读了知识库里的哪些文件,没人读的是哪些?”它是“放行的调用不记它碰了什么”这条规矩的唯一例外:它只记文件名,而且可以关掉。没人读的文件,是可以删的候选。
  • 健康检查比较特别。它不看 agent,它看配置本身:文件都在吗,规则文件有效吗,hook 能运行吗(它真的运行一次),上次被调用是什么时候,最近最慢的一次调用是不是离它的时间限制太近了?它的输出分三级:正常、警告(不拦截)、错误(必须修)。它事后发现问题,预防不了。
  • 固定场景回答“我改了什么之后,行为变了吗?”那是后面几章的内容。另外四种记录在图里列出了。

token 和时间

hook 看到的是调用,看不到模型读了多少 token。在我的配置里,hook 日志有意不记 token:平台自己有一份时间和用量的记录,再多一份会对不上。显示一个任务的时间和用量花在哪里的页面,读的是平台那份记录;读不到时,就退回到 hook 日志里的时间。不管你从哪里读用量,都要弄清它数的是什么:主对话的数字可能不含子 agent 的(慎用子 agent里有同样的提醒)。

记录器出故障时

hook 是软件,会出故障。在我的配置里,hook 本身出错时,会放行这次调用,并把错误写进单独的文件;健康检查会提醒我去看。这是有意的选择,把执行层当软件来设计讲了为什么它适合编程用的 harness,以及不适合的地方该怎么办。对记录器来说,它很容易接受:漏了一行日志,是证据里的一个缺口,不是事故。但要知道这一点:某段时间里日志一行也没有,可能是“什么都没发生”,也可能是“记录器挂了”。错误文件就是用来区分这两种情况的。

测一测你自己的配置

三个问题:

  1. 对最近一个重要的 agent 任务,你能根据记录,而不是根据它的总结,说出它做了什么吗?
  2. 如果它做了你不想要的事,你会发现吗?什么时候发现?
  3. 你的记录写了什么被拒绝了,还是只写了什么成功了?

今天就能做的测试,不用额外的配置。让 agent 做一个小任务,并在最后说出它运行了哪些命令。然后看你的工具自己有关工具调用的历史(在哪里看,每个工具不一样,我没有逐个查过)。把两份清单对一对。如果一致,你就知道了在这类任务上总结能信到什么程度。如果不一致,你就明白了为什么需要一份记录。

Costs and traps

Usage comes from a file that is not a public format. It may change under you, and then the page shows times only. This is a dependency on the platform: an update can make your usage numbers stop working, and I have not tested what mine does after one.

A log nobody reads is a cost with no benefit. Decide who reads it, and when. For me it is: when a run fails, and when I change a rule. Not every day. If a team keeps logs, also decide how long they stay, who may read them, and whether they can hold personal data. A log is an audit trail only if someone owns it.

A hook sees only what the platform shows it. Some actions happen outside the tool calls a hook can see. Then the log has a hole you cannot see from the log. (Hooks says what Copilot covers today.)

Leaving out arguments is a trade. It protects code and secrets in the log. The price is that you cannot replay a run from the log alone. For that you need the platform's own record, which you cannot count on keeping.

The log shows what happened, not whether it was right. A clean trace can still end in wrong code. That is what the checks in Let the agent check its own work and Fixed tasks, scored by a script are for.

代價和陷阱

用量來自一個不是公開格式的檔案。它可能在你不知道的時候改變,到時候那一頁就只會顯示時間。這是對平台的依賴:一次更新就可能讓你的用量數字失效,我沒有測過更新之後我的會怎樣。

沒人讀的日誌,是有成本、沒好處。決定誰讀、什麼時候讀。對我來說是:運行失敗的時候,和我改規則的時候。不是每天。如果團隊要留日誌,還要決定留多久、誰可以讀、能不能含個人資料。日誌要有人負責,才算稽核軌跡。

hook 只看得到平台給它看的。有些動作發生在 hook 看不到的工具呼叫之外。那時日誌有個洞,而你從日誌裡看不到這個洞。(Hooks:每次呼叫都會經過的執行點 說了 Copilot 今天涵蓋什麼。)

不記參數是一個取捨。它保護日誌裡的程式碼和機密。代價是,光靠日誌你沒辦法重播一次運行。要重播,需要平台自己的紀錄,而你不能指望它一直留著。

日誌顯示發生了什麼,不顯示對不對。一份乾淨的軌跡,仍然可能以錯的程式碼收場。這就是 讓 agent 能檢查自己的活 和 固定的任務,用腳本打分 裡的檢查要做的事。

代价和坑

用量来自一个不是公开格式的文件。它可能在你不知道的时候改掉,那时页面就只显示时间了。这是对平台的依赖:一次更新就可能让你的用量数字失效,更新之后我的会怎样,我没有测过。

没人读的日志,是有成本、没收益。决定谁来读,什么时候读。我的做法是:运行失败的时候,和我改规则的时候。不是每天。如果团队要留日志,还要决定留多久,谁可以读,能不能含有个人数据。日志只有在有人负责的时候,才是审计的依据。

hook 只看得到平台给它看的东西。有些操作发生在 hook 看不到的工具调用之外。这时日志里有个洞,而你从日志里看不出来。(Copilot 现在覆盖到哪里,见 Hook:每次调用都会经过的执行点。)

不记参数是一种取舍。它保护日志里的代码和密钥。代价是,光靠日志,你没法回放一次运行。要回放,得用平台自己的记录,而你没法指望它一直保留。

日志显示发生了什么,不显示对不对。一份干净的轨迹,最后仍可能得到错误的代码。让 agent 能检查自己的活和固定的任务,用脚本打分里的检查,就是管这个的。

When to delete it Industry practice

The hook that writes my log exists because I want one record format that I own and can read. If a platform gives you a trace of every tool call that you can export and the agent cannot change, use that and drop the hook. The same goes for the usage page: if the platform shows usage per task, drop the part that reads its session file.

The reasoning does not retire. When a fact matters, it should come from a record that was written by code and not by the one being judged. I would look again at the eight records if I found that I never open one of them.

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

寫我的日誌的那個 hook 存在,是因為我想要一種我自己擁有、自己讀得懂的紀錄格式。如果平台提供每次工具呼叫的軌跡,可以匯出、agent 又改不了,就用那個,把 hook 丟掉。用量那一頁也一樣:如果平台直接顯示每個任務的用量,就把讀它會話檔的那部分丟掉。

道理不會退役。一件事重要的時候,它應該來自程式寫的紀錄,不是來自被評判的那一方。如果我發現八種紀錄裡有一種我從來沒打開過,我會重新檢視這八種。

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

写我这份日志的 hook 之所以存在,是因为我想要一种我自己拥有、自己能读的记录格式。如果平台提供一份每次工具调用的轨迹,可以导出,agent 又改不了,就用那个,把 hook 去掉。用量页面也一样:如果平台按任务显示用量,就去掉读它会话文件的那一部分。

背后的道理不会退役。一个事实要紧的时候,它应该来自代码写的记录,而不是来自被评判的那一方。如果我发现八种记录里有哪一种我从来不打开,我会重新审视这八种。

Try it on your own setup

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

Find out what records exist of what AI agents do in this project and on this machine: the tool's own logs or transcripts, any hook or audit settings, and any reports. For each record, tell me where it is, what one entry holds, whether the agent itself could edit or delete it, whether it could contain secrets or personal data, and who can read it. Then say which of these questions I could answer from records alone and not from the agent's summary: what it ran, what it changed, what was refused. Do not change any files.

在你自己的環境試試

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

查一下這個專案裡、這台機器上,有哪些關於 AI agent 做了什麼的紀錄:工具自己的日誌或對話紀錄、任何 hook 或稽核設定、任何報告。對每一種紀錄,告訴我它在哪裡、一筆裡面放什麼、agent 自己能不能改或刪、可能含不含機密或個人資料、誰可以讀。然後說說,下面這些問題裡,哪些我可以只靠紀錄回答,不用靠 agent 的總結:它執行了什麼、改了什麼、什麼被拒絕。不要改任何檔案。

在你自己的环境里试试

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

找出这个项目里和这台机器上,有哪些关于 AI agent 所做之事的记录:工具自己的日志或对话记录、任何 hook 或审计设置,以及任何报告。对每一种记录,告诉我它在哪里,一条记录里有什么,agent 自己能不能编辑或删除它,它可能含有密钥或个人数据吗,谁可以读。然后说,下面这些问题里,哪些我只靠记录就能回答、不用看 agent 的总结:它运行了什么,它改了什么,什么被拒绝了。不要修改任何文件。

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

Copilot Harness writes the log with a hook, keeps the other seven records on top of it, and has a health check for the setup. The harness can show them to you from the inside, with a real log. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Record what happened, not what the agent said". Teach me how this harness records and reports (topic 12): what the session log holds and leaves out, where usage comes from, and what the health check looks at. Open a real log with me, and draw how the pieces fit together.

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

在 harness 裡探索

Copilot Harness 用 hook 寫日誌,在它上面再放另外七種紀錄,還有一個檢查設定的健康檢查。harness 可以用一份真的日誌,從裡面帶你看。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「記下發生了什麼,不是 agent 說了什麼」這一章。請教我這個 harness 怎麼記錄和回報(主題 12):會話日誌放什麼、不放什麼,用量從哪裡來,健康檢查看什麼。帶我打開一份真的日誌,並畫出這些部分怎麼接在一起。

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

在 harness 里探索

Copilot Harness 用一个 hook 写日志,在它之上还有另外七种记录,也有针对配置的健康检查。harness 可以从内部给你看这些,附一份真实的日志。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“记下发生了什么,而不是 agent 说了什么”这一章。请教我这个 harness 是怎么记录和报告的(主题 12):会话日志记什么、不记什么,用量从哪里来,健康检查看什么。和我一起打开一份真实的日志,并画出各部分是怎么拼在一起的。

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