debug-my-harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diagnose harness misbehavior from the flight recorder — the local, append-only ledger at

.vigiles/runs.jsonl

that vigiles writes as your harness runs. It records what actually happened, so you debug from evidence instead of guessing.

从flight recorder（即vigiles在harness运行时写入的本地追加式账本

.vigiles/runs.jsonl

）中诊断harness的运行异常问题。该账本记录了实际发生的事件，让你能够基于证据而非猜测进行调试。

What's in the ledger

账本包含的内容

One JSON record per line, each with a

kind

hook

— a compiled-hook gate decision:

{event, decision: allow|deny|ask, mode: enforce|observe, rule, cmd, reason}

```
agent
```
— a subagent tool-contract decision:
```
{name, tool, allowed, reason}
```
(a
```
false
```
= the agent went outside its lane).
```
skill
```
— a skill activation:
```
{name, fired}
```
.
```
eval
```
— a measured metric:
```
{name, metric, value}
```
(e.g. trigger-rate recall/precision).

capability-diff

— a blast-radius change:

{pr, added, removed, widened}

每行一条JSON记录，每条记录包含

kind

字段：

hook

— 编译后的Hook网关决策：

{event, decision: allow|deny|ask, mode: enforce|observe, rule, cmd, reason}

。

```
agent
```
— 子Agent工具合约决策：
```
{name, tool, allowed, reason}
```
（
```
false
```
表示Agent超出了其权限范围）。
```
skill
```
— Skill激活记录：
```
{name, fired}
```
。
```
eval
```
— 度量指标记录：
```
{name, metric, value}
```
（例如触发率的召回率/精确率）。

capability-diff

— 影响范围变化记录：

{pr, added, removed, widened}

。

Instructions

操作步骤

Step 1: Read the ledger

步骤1：读取账本

Read

.vigiles/runs.jsonl

(JSONL — one record per line; tolerate a torn last line). If it's absent or empty, say so — there's nothing recorded yet; suggest running the harness (or

vigiles audit

) first. Do NOT fabricate records.

读取

.vigiles/runs.jsonl

文件（JSONL格式——每行一条记录；允许最后一行不完整）。如果文件不存在或为空，请告知用户目前没有任何记录，并建议先运行harness（或

vigiles audit

）。请勿编造记录。

Step 2: Answer the specific question, evidence-first

步骤2：以证据为优先，回答具体问题

Match the user's question to the ledger:

"Why did skill X stop firing / why does the wrong one run?" — count
```
skill
```
fires by name over time. If X's fire-rate dropped, look for a sibling that fired on the same kinds of prompts (a selection collision) and check their descriptions for overlap. Recommend differentiating or merging the descriptions.
"Why didn't my hook block that?" — find
```
hook
```
records for the event. A
```
decision: allow
```
on something that should be denied, or
```
mode: observe
```
(shadow, never blocks), or the absence of any record, tells you which. Recommend flipping
```
observe
```
→
```
enforce
```
or fixing the gate logic.
"Did a subagent misbehave?" — list
```
agent
```
records with
```
allowed: false
```
: the agent reached for a tool outside its declared contract. Point at the contract to tighten or widen.
"Is it getting worse?" — compare
```
eval
```
metric values (recall/precision) across runs; a downward trend is drift (often after a harness/model upgrade).

将用户的问题与账本记录匹配：

“为什么Skill X停止触发/为什么运行的是错误的Skill？” — 按名称统计不同时间点
```
skill
```
的触发次数。如果X的触发率下降，查找在同类提示下触发的其他Skill（即选择冲突），并检查它们的描述是否存在重叠。建议区分或合并这些描述。
“为什么我的Hook没有拦截该操作？” — 查找对应事件的
```
hook
```
记录。如果记录中
```
decision: allow
```
（本应拒绝的操作被放行）、
```
mode: observe
```
（影子模式，从不拦截），或者没有任何相关记录，即可确定原因。建议将
```
observe
```
模式切换为
```
enforce
```
模式，或修复网关逻辑。
“子Agent是否运行异常？” — 列出所有
```
allowed: false
```
的
```
agent
```
记录：这些记录表示Agent试图使用其声明合约之外的工具。建议调整合约以收紧或放宽权限。
“情况是否在恶化？” — 对比不同运行周期的
```
eval
```
指标值（召回率/精确率）；指标下降趋势表示出现漂移（通常发生在harness/模型升级后）。

Step 3: Recommend a fix, tied to the evidence

步骤3：基于证据提出修复建议

Prefer promoting an ignored-but-decidable rule from prose to a deterministic gate: a repeated

agent

violation or a rule the agent keeps breaking → a compiled hook or a tighter tool-contract (the

strengthen

skill can help). A description collision → differentiate the skill descriptions. Always cite the specific records you based the diagnosis on.

优先建议将被忽略但可明确执行的规则从文本描述转换为确定性网关：如果出现重复的

agent

违规或Agent持续违反某条规则→建议添加编译后的Hook或收紧工具合约（

strengthen

Skill可提供帮助）。如果存在描述冲突→建议区分Skill的描述。务必引用诊断所依据的具体记录。

Step 4: Offer the next step

步骤4：提供下一步操作建议

If the fix is a spec change, hand off to

edit-spec

. If it's promoting guidance to a linter rule, hand off to

strengthen

. If a behavioral claim needs measuring (does the skill fire now?), hand off to

test-harness

(

measureTriggerRate

如果修复需要修改规范，请转至

edit-spec

。如果需要将指导规则升级为检查器规则，请转至

strengthen

。如果需要验证行为变化（例如Skill现在是否触发？），请转至

test-harness

（使用

measureTriggerRate

）。