Harness Engineering - AI驾驭工程错题本

核心理念

Harness Engineering（AI驾驭工程）：AI时代程序员的核心工作不是写代码，而是设计规则、约束、反馈、调度体系，让AI安全、可靠、高效工作，同时持续修正AI错误。

本 skill 是 OpenClaw 的自省机制，记录所有被验证的错误和用户需求，形成错误台账，驱动模型进化，避免重复犯错。

---

一、核心功能概览

功能	说明
错误记录	记录所有被验证的错误、幻觉、失误
功能请求跟踪

跟踪用户想要但当前没有的功能 |
| 自动触发 | Hook机制自动检测纠正词和命令失败 |
| 自动提升 | 将重要学习提升到workspace文件 |
| 统计面板 | 可视化错误统计（今日/本周/本月/全部） |
| 错误模式库 | 12种常见错误模式供参考 |
| 定期回顾 | 周期性回顾机制，持续优化 |

---

二、存储结构

2.1 错误台账 (error_ledger.jsonl)

CODEBLOCK0

2.2 功能请求台账 (feature_ledger.jsonl)

CODEBLOCK1

2.3 学习台账 (learnings_ledger.jsonl)

重要学习、纠正、知识差距、最佳实践都记录在这里。

CODEBLOCK2

2.4 Workspace提升目标

学习类型	提升到
行为模式、沟通风格	INLINECODE0
工作流程、自动化

AGENTS.md | | 工具使用、集成技巧 | TOOLS.md | | 项目事实、约定 | MEMORY.md |

---

三、自动触发机制

3.1 检测触发词

当用户发送以下内容时，立即记录：

错误纠正：

• - "不对，应该是..."
• "错了，正确答案是..."
• "Actually, ..."
• "这样不对"
• "No, that's wrong..."
• "You're wrong about..."

功能请求：

• - "能不能..." / "Can you also..."
• "希望你能..." / "I wish you could..."
• "Is there a way to..."
• "为什么不能..." / "Why can't you..."

知识差距：

• - 用户提供了你不知道的信息
• 你引用的文档已过时
• API行为与你的理解不符

命令失败：

• - 命令返回非零退出码
• 异常或堆栈跟踪
• 超时或连接失败

3.2 记录流程

1. 1. 检测到触发词 → 立即记录
2. 生成唯一ID → HE-YYYYMMDD-XXXX / FR-YYYYMMDD-XXXX / LRN-YYYYMMDD-XXXX
3. 写入对应台账 → errorledger.jsonl / featureledger.jsonl / learnings_ledger.jsonl
4. 相似检测 → 检查是否有相似记录
5. 状态追踪 → 设置初始状态为"未处理"
6. 用户确认 → 回复用户已记录

---

四、自动进化机制（核心）

本 skill 实现了闭环自进化，通过以下三种机制确保错误不会重复：

4.1 定时自动提升（每2小时）

原理：当学习记录的 recurrence_count >= 3 时，自动写入 workspace 文件

配置 Cron Job：
CODEBLOCK3

自动提升逻辑：
CODEBLOCK4

4.2 错误摘要注入（Session 启动时）

原理：每次 session 启动时，自动读取错误台账摘要并注入到上下文

实现方式：通过 OpenClaw system event 触发

CODEBLOCK5

注入内容格式：
CODEBLOCK6

4.3 回答前自检（每次回答时）

原理：在生成回答前，自动查询错误台账，如果涉及相似问题则参考正确答案

实现方式：定义在 SKILL.md 中的强制规则，每次回答前必须执行

自检流程：
CODEBLOCK7

示例：

用户问：Python 3.12 有什么新特性？

自检结果：发现相似错误 HE-20260401-0001
- 错误类型：事实错误
- recurrence_count: 2
- correct_answer: "Python 3.12 未移除 GIL，只是提供了 sub-interpreter 支持"

回答：[⚠️ 规避历史错误: HE-20260401-0001]
Python 3.12 的主要新特性包括：
1. ... (参考正确答案是未移除GIL)

- 标记为"高频错误，需提升"
- 在回答中标注 "[高频错误，已记录]"

### 4.4 自动进化工作流图

┌─────────────────────────────────────────────────────────────┐
│ 自动进化闭环 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 用户纠正错误 → 记录到 error_ledger.jsonl │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Cron Job (每2小时) │
│ → promote.py --action auto_promote │
│ → recurrence_count >= 3 → 自动写入 workspace │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
SOUL.md AGENTS.md TOOLS.md
(行为) (工作流) (工具)
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Session 启动 → inject_summary.py → 错误摘要注入上下文 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 回答前 → preanswercheck.py → 查询相似错误 → 规避 │
└─────────────────────────────────────────────────────────────┘
│
▼
【闭环完成：错误不再重复】

### 4.5 关键脚本说明

| 脚本 | 用途 | 触发时机 |
|------|------|---------|
| `promote.py --action auto_promote` | 定时自动提升 | Cron (每2小时) |
| `inject_summary.py` | 错误摘要注入 | Session 启动 |
| `pre_answer_check.py` | 回答前自检 | 每次回答前 |

---

## 五、错误分类体系

### 4.1 按错误类型（9种）

| 类型 | 说明 | 示例 |
|------|------|------|
| **幻觉** | 编造不存在的事实、API、库函数 | 声称不存在的npm包 |
| **事实错误** | 与已知事实不符 | 错误的API参数、版本号 |
| **逻辑错误** | 推理过程或结论错误 | 条件判断错误、循环逻辑错误 |
| **漏信息** | 回答不完整，遗漏关键步骤 | 安装步骤漏写依赖安装 |
| **格式错误** | 输出格式不符合要求 | CSV格式错误、JSON格式错误 |
| **代码错误** | 代码无法运行或有bug | 语法错误、类型错误 |
| **安全问题** | 潜在的安全风险 | SQL注入风险、敏感信息泄露 |
| **重复犯错** | 同类错误再次发生 | 已记录的错误再次出现 |
| **态度问题** | 回答态度不当 | 过度道歉、不必要防御 |

### 4.2 按严重等级（4级）

| 等级 | 说明 | 处理优先级 |
|------|------|-----------|
| **严重** | 导致数据丢失、安全问题、系统崩溃 | 立即修复 |
| **高** | 影响核心功能，用户无法完成任务 | 当日修复 |
| **中** | 影响用户体验，但有替代方案 | 本周修复 |
| **低** | 小问题，不影响使用 | 记录并持续优化 |

---

## 五、自动提升机制

### 5.1 提升条件

当满足以下任一条件时，**自动提升**到workspace文件：

- `recurrence_count >= 3` (同类错误出现3次以上)
- 学习具有**广泛适用性** (跨多个场景)
- 用户明确说"记住这个" / "Save this as..."
- `status` 标记为 `promoted`

### 5.2 提升目标

| 学习类型 | 提升目标 | 示例 |
|---------|---------|------|
| 行为模式 | `SOUL.md` | "Be concise, avoid disclaimers" |
| 工作流程 | `AGENTS.md` | "Spawn sub-agents for long tasks" |
| 工具技巧 | `TOOLS.md` | "Git push needs auth configured first" |
| 重要事实 | `MEMORY.md` | "用户偏好XX" |

### 5.3 提升流程

1. **识别提升条件** → 检查recurrence_count或广泛适用性
2. **蒸馏为规则** → 将冗长描述简化为简洁规则
3. **写入目标文件** → 添加到对应section
4. **更新原记录** → 状态改为 `promoted`，记录提升目标

### 5.4 提升示例

**原始学习**（冗长）：
> 项目使用 pnpm workspaces。尝试 `npm install` 但失败了。
> 锁文件是 `pnpm-lock.yaml`。必须用 `pnpm install`。

**提升到 AGENTS.md**（简洁）：

markdown

Build & Dependencies

• - Package manager: pnpm (not npm) - use INLINECODE5

---

## 六、定期回顾机制

### 6.1 回顾时机

- 开始新的主要任务之前
- 完成一个功能之后
- 在有历史学习的领域工作时
- 每周活跃开发期间

### 6.2 回顾动作

1. **检查pending项** → `query_errors.py --status pending`
2. **解决已修复项** → 更新状态为 `resolved`
3. **提升适用学习** → 检查是否需要提升到workspace
4. **链接相关条目** → 添加 See Also 引用
5. **升级重复问题** → recurrence_count 增加

### 6.3 回顾脚本

bash

检查pending项数量

python3 "{SKILL_DIR}/scripts/review.py" --action status

列出高优先级项

python3 "{SKILLDIR}/scripts/review.py" --action highpriority

执行完整回顾

python3 "{SKILLDIR}/scripts/review.py" --action fullreview

---

## 七、功能请求跟踪

### 7.1 何时记录

用户表达想要但当前没有的功能时：
- "能不能加个XX功能"
- "Is there a way to do XX"
- "我希望你能XX"
- "This would be useful if..."

### 7.2 复杂度评估

| 复杂度 | 说明 |
|--------|------|
| **简单** | 现有代码修改即可实现 |
| **中等** | 需要新增文件或较大改动 |
| **复杂** | 需要架构调整或长期规划 |

### 7.3 功能请求处理

1. **记录到 feature_ledger.jsonl**
2. **评估复杂度**
3. **如果是简单功能**：可考虑直接实现
4. **如果是复杂功能**：标记为"规划中"，定期回顾

---

## 八、脚本接口

### 8.1 record_error.py - 记录错误

bash python3 "{SKILLDIR}/scripts/recorderror.py" \ --scene <场景> \ --error-type <错误类型> \ --question <问题> \ --wrong-answer <错误回答> \ --correct-answer <正确答案> \ --reason <原因> \ --level <等级> \ --source <来源> \ [--tags <标签>]

### 8.2 record_learning.py - 记录学习

bash python3 "{SKILLDIR}/scripts/recordlearning.py" \ --category <类型> \ --summary <摘要> \ --details <详情> \ --suggested-action <建议> \ --source <来源> \ [--pattern-key <模式键>] \ [--priority <优先级>]

### 8.3 record_feature.py - 记录功能请求

bash python3 "{SKILLDIR}/scripts/recordfeature.py" \ --name <功能名称> \ --context <用户场景> \ --complexity <复杂度> \ --priority <优先级>

### 8.4 query.py - 查询台账

bash

按关键词查询错误

python3 "{SKILL_DIR}/scripts/query.py" --type errors --keywords "编码"

查询学习

python3 "{SKILL_DIR}/scripts/query.py" --type learnings --category correction

查询功能请求

python3 "{SKILL_DIR}/scripts/query.py" --type features --status pending

查询未处理项

python3 "{SKILL_DIR}/scripts/query.py" --type all --status pending

### 8.5 stats_panel.py - 统计面板

bash

今日统计

python3 "{SKILLDIR}/scripts/statspanel.py" --period today

本周统计（带可视化）

python3 "{SKILLDIR}/scripts/statspanel.py" --period week

全部统计（JSON格式）

python3 "{SKILLDIR}/scripts/statspanel.py" --period all --format json

### 8.6 promote.py - 提升学习

bash

提升到指定文件

python3 "{SKILL_DIR}/scripts/promote.py" \ --learning-id LRN-20260401-0001 \ --target SOUL.md

检查可提升项

python3 "{SKILLDIR}/scripts/promote.py" --action checkcandidates

### 8.7 update_status.py - 更新状态

bash

标记为已解决

python3 "{SKILLDIR}/scripts/updatestatus.py" \ --type error \ --id HE-20260401-0001 \ --status resolved

标记为已提升

python3 "{SKILLDIR}/scripts/updatestatus.py" \ --type learning \ --id LRN-20260401-0001 \ --status promoted \ --promoted-to "SOUL.md"

### 8.8 export_report.py - 导出报告

bash

导出完整报告

python3 "{SKILLDIR}/scripts/exportreport.py" --output report.md

导出JSON格式

python3 "{SKILLDIR}/scripts/exportreport.py" --output report.json --format json

指定时间范围

python3 "{SKILLDIR}/scripts/exportreport.py" --output report.md --from 2026-04-01 --to 2026-04-30

### 8.9 review.py - 定期回顾

bash

检查状态概览

python3 "{SKILL_DIR}/scripts/review.py" --action status

高优先级项

python3 "{SKILLDIR}/scripts/review.py" --action highpriority

执行完整回顾

python3 "{SKILLDIR}/scripts/review.py" --action fullreview

---

## 九、检测触发词速查表

### 9.1 错误纠正触发词

英语：

• - "No, that's not right..."
• "Actually, it should be..."
• "You're wrong about..."
• "That's incorrect..."
• "The correct answer is..."

中文：

• - "不对，应该是..."
• "错了，正确答案是..."
• "这样不对"
• "你理解错了"
• "不是这样的"

### 9.2 功能请求触发词

英语：

• - "Can you also..."
• "I wish you could..."
• "Is there a way to..."
• "It would be nice if..."
• "This would be useful if..."

中文：

• - "能不能..."
• "希望你能..."
• "要是能...就好了"
• "能不能加个XX功能"
• "希望以后能支持..."

### 9.3 命令失败检测

当以下情况发生时自动记录：
- Exit code != 0
- 异常/堆栈跟踪出现
- Connection timeout
- Permission denied

---

## 十、文件结构

{SKILL_DIR}/
├── SKILL.md # 主文档
├── scripts/
│ ├── record_error.py # 记录错误
│ ├── record_learning.py # 记录学习
│ ├── record_feature.py # 记录功能请求
│ ├── query.py # 查询台账
│ ├── stats_panel.py # 统计面板 ⭐
│ ├── promote.py # 自动提升 ⭐
│ ├── update_status.py # 更新状态
│ ├── export_report.py # 导出报告
│ └── review.py # 定期回顾 ⭐
├── data/
│ ├── error_ledger.jsonl # 错误台账
│ ├── feature_ledger.jsonl # 功能请求台账 ⭐
│ ├── learnings_ledger.jsonl # 学习台账
│ └── error_index.json # 错误索引
└── references/
└── error_patterns.md # 错误模式库 ⭐

---

## 十一、优势功能保留

### 11.1 统计面板 ⭐

一键生成可视化错误统计报告：
- 按类型/等级/状态分布
- 高频错误TOP 5
- 修复率统计
- 支持今日/本周/本月/全部周期

### 11.2 错误模式库 ⭐

12种常见错误模式：
1. CSV文件编码错误
2. bat/cmd脚本中文乱码
3. Python文件读写编码错误
4. 换行符不一致
5. 路径分隔符问题
6. 文件未关闭导致资源泄漏
7. 文件覆盖未备份
8. 边界条件遗漏
9. 空值处理缺失
10. API参数错误
11. 敏感信息泄露
12. SQL注入风险

### 11.3 自动相似检测

记录时自动检查相似错误（相似度>50%会提示），避免重复记录。

---

## 十二、快速开始

### 12.1 安装方法

#### 方法一：导入 .skill 文件（推荐）

bash

1. 下载 harness-engineering.skill 文件

2. 在 OpenClaw 中导入：/skills install /path/to/harness-engineering.skill

#### 方法二：手动安装

bash

1. 复制 skill 目录到 ~/.qclaw/skills/

cp -r harness-engineering/ ~/.qclaw/skills/

2. 创建数据目录

mkdir -p ~/.qclaw/skills/harness-engineering/data/

3. 创建空数据文件

touch ~/.qclaw/skills/harness-engineering/data/error_ledger.jsonl touch ~/.qclaw/skills/harness-engineering/data/feature_ledger.jsonl touch ~/.qclaw/skills/harness-engineering/data/learnings_ledger.jsonl touch ~/.qclaw/skills/harness-engineering/data/error_index.json

#### 方法三：通过 ClawHub 安装（待发布）

bash /install harness-engineering

---

### 12.2 快速命令参考

#### 错误记录

bash python3 "{SKILLDIR}/scripts/recorderror.py" \ --scene "问答" \ --error-type "事实错误" \ --question "用户问题" \ --wrong-answer "错误回答" \ --correct-answer "正确答案" \ --reason "错误原因" \ --level "高"

#### 学习记录

bash python3 "{SKILLDIR}/scripts/recordlearning.py" \ --category correction \ --summary "一句话摘要" \ --details "详细上下文" \ --suggested-action "建议行动" \ --priority high

#### 功能请求

bash python3 "{SKILLDIR}/scripts/recordfeature.py" \ --name "功能名称" \ --context "用户场景" \ --complexity "中等"

#### 查询台账

bash

查询所有

python3 "{SKILL_DIR}/scripts/query.py" --type all

按关键词查询

python3 "{SKILL_DIR}/scripts/query.py" --type errors --keywords "Python"

查询未修复

python3 "{SKILL_DIR}/scripts/query.py" --type errors --status pending

#### 统计面板

bash

今日统计

python3 "{SKILLDIR}/scripts/statspanel.py" --period today

本周统计

python3 "{SKILLDIR}/scripts/statspanel.py" --period week

JSON 格式

python3 "{SKILLDIR}/scripts/statspanel.py" --period all --format json

#### 自动提升

bash

检查可提升项

python3 "{SKILLDIR}/scripts/promote.py" --action checkcandidates

自动提升（recurrence_count >= 3）

python3 "{SKILLDIR}/scripts/promote.py" --action autopromote

#### 定期回顾

bash

状态概览

python3 "{SKILL_DIR}/scripts/review.py" --action status

高优先级项

python3 "{SKILLDIR}/scripts/review.py" --action highpriority

完整回顾

python3 "{SKILLDIR}/scripts/review.py" --action fullreview

#### 回答前自检

bash python3 "{SKILLDIR}/scripts/preanswer_check.py" --question "用户问题"

#### 错误摘要注入

bash python3 "{SKILLDIR}/scripts/injectsummary.py" --action session_start

---

### 12.3 自动进化机制

#### Cron 定时任务（可选配置）

yaml

在 OpenClaw 中配置定时任务

/cron add --name "harness-auto-promote" \ --schedule "every 2h" \ --task "python3 {SKILLDIR}/scripts/promote.py --action autopromote"

/cron add --name "harness-weekly-review" \
--schedule "cron 0 9 1" \
--task "python3 {SKILLDIR}/scripts/review.py --action fullreview"
`` --- ### 12.4 初始化 Skill首次使用时会自动创建必要的数据目录和文件： - data/errorledger.jsonl - data/featureledger.jsonl - data/learningsledger.jsonl - data/errorindex.json ### 12.5 日常使用流程 1. **被用户纠正** → 调用 record_error.py 记录到错误台账 2. **用户请求功能** → 调用 record_feature.py 记录到功能请求台账 3. **学到了新东西** → 调用 record_learning.py 记录到学习台账 4. **每次回答前** → 自动调用 pre_answer_check.py 自检 5. **session 启动时** → 自动调用 inject_summary.py 注入摘要 6. **每2小时** → Cron 自动调用 promote.py 提升高频学习 7. **每周** → Cron 自动调用 review.py 回顾 8. **需要查看统计** → 运行 stats_panel.py ### 12.3 示例对话 **用户纠正**： > 你刚才说Python 3.12移除了GIL，这是错的。 **OpenClaw回复**： > 感谢纠正！Python 3.12确实没有移除GIL。 > > [自动调用 record_error.py] > > 已将此错误记录到错题本（HE-20260401-0002），后续回答涉及Python版本特性时会更加谨慎。 **用户请求功能**： > 能不能加个自动总结会议纪要的功能？ **OpenClaw回复**： > 这是个好建议！已记录到功能请求台账（FR-20260401-0001），我会持续关注相关实现方案。 --- ## 十三、注意事项 ### 13.1 隐私保护 - **不记录敏感信息**：密码、API密钥、Token等不记录 - **脱敏处理**：涉及个人信息时，用 * 替换 ### 13.2 存储管理 - 台账文件超过1MB时，建议归档 - 定期清理已解决/已提升的记录（可选） ### 13.3 性能考虑 - 查询时优先使用索引 - 大量记录时使用 --limit` 限制返回

---

记住：每个错误都是进化的机会，每个请求都是改进的方向。
Harness Engineering：记录 → 学习 → 提升 → 进化 🔧