Harness Engineering（AI驾驭工程）：AI时代程序员的核心工作不是写代码，而是设计规则、约束、反馈、调度体系，让AI安全、可靠、高效工作，同时持续修正AI错误。
本 skill 是 OpenClaw 的自省机制，记录所有被验证的错误和用户需求，形成错误台账，驱动模型进化，避免重复犯错。
| 功能 | 说明 |
|---|---|
| ------ | ------ |
| 错误记录 | 记录所有被验证的错误、幻觉、失误 |
| 功能请求跟踪 | 跟踪用户想要但当前没有的功能 |
| 自动触发 | Hook机制自动检测纠正词和命令失败 |
| 自动提升 | 将重要学习提升到workspace文件 |
| 统计面板 | 可视化错误统计（今日/本周/本月/全部） |
| 错误模式库 | 12种常见错误模式供参考 |
| 定期回顾 | 周期性回顾机制，持续优化 |
{"error_id":"HE-20260401-0001","timestamp":"2026-04-01T12:34:56+08:00","scene":"代码","error_type":"代码错误","question":"用户原始问题","wrong_answer":"错误回答摘要","correct_answer":"正确答案","reason":"错误原因","fix_status":"未修复","level":"中","source":"用户纠正","tags":["代码","Python"]}
{"feature_id":"FR-20260401-0001","timestamp":"2026-04-01T12:34:56+08:00","feature_name":"功能名称","user_context":"用户为什么需要这个功能","complexity":"简单|中等|复杂","status":"pending","priority":"低|中|高","source":"用户请求"}
重要学习、纠正、知识差距、最佳实践都记录在这里。
{"learning_id":"LRN-20260401-0001","timestamp":"2026-04-01T12:34:56+08:00","category":"correction|best_practice|knowledge_gap|simplify_harden","summary":"一句话描述","details":"详细上下文","suggested_action":"建议采取的行动","status":"pending|promoted|resolved","source":"conversation|error|user_feedback","pattern_key":"pattern.name","recurrence_count":1,"first_seen":"2026-04-01","last_seen":"2026-04-01","promoted_to":""}
| 学习类型 | 提升到 |
|---|---|
| --------- | -------- |
| 行为模式、沟通风格 | SOUL.md |
| 工作流程、自动化 | AGENTS.md |
| 工具使用、集成技巧 | TOOLS.md |
| 项目事实、约定 | MEMORY.md |
当用户发送以下内容时，立即记录：
错误纠正：
功能请求：
知识差距：
命令失败：
本 skill 实现了闭环自进化，通过以下三种机制确保错误不会重复：
原理：当学习记录的 recurrence_count >= 3 时，自动写入 workspace 文件
配置 Cron Job：
# 每2小时自动检查并提升
python3 "{SKILL_DIR}/scripts/promote.py" --action auto_promote
自动提升逻辑：
if recurrence_count >= 3:
if category == "correction":
promote to SOUL.md # 行为纠正
elif category == "best_practice":
promote to AGENTS.md # 最佳实践
elif category == "knowledge_gap":
promote to MEMORY.md # 知识更新
else:
promote to TOOLS.md # 工具技巧
原理：每次 session 启动时，自动读取错误台账摘要并注入到上下文
实现方式：通过 OpenClaw system event 触发
# 每次 session 启动自动执行
python3 "{SKILL_DIR}/scripts/inject_summary.py" --action session_start
注入内容格式：
【HarnessEngineering 错误台账摘要 - 最近5条】
1. [代码错误] 未指定文件编码导致乱码 (重复2次)
2. [逻辑错误] 条件判断遗漏边界情况 (重复3次) ⚠️ 需提升
3. [漏信息] 安装步骤漏写依赖安装
【已规避的错误模式】
- Python 3.12 未移除 GIL
- CSV 文件需使用 utf-8-sig 编码
原理：在生成回答前，自动查询错误台账，如果涉及相似问题则参考正确答案
实现方式：定义在 SKILL.md 中的强制规则，每次回答前必须执行
自检流程：
1. 用户提问 → 提取关键词
2. 查询 error_ledger.jsonl 中相似问题 (相似度 > 50%)
3. 如果找到相似错误：
- 提取 correct_answer 作为参考
- 在回答开头标注 "[⚠️ 规避历史错误: HE-xxxx]"
4. 如果 recurrence_count >= 3：
- 标记为"高频错误"，优先规避
5. 正常生成回答，但参考正确答案
示例：
用户问：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 → 错误摘要注入上下文 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 回答前 → pre_answer_check.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**（简洁）：
pnpm install
---
## 六、定期回顾机制
### 6.1 回顾时机
- 开始新的主要任务之前
- 完成一个功能之后
- 在有历史学习的领域工作时
- 每周活跃开发期间
### 6.2 回顾动作
1. **检查pending项** → `query_errors.py --status pending`
2. **解决已修复项** → 更新状态为 `resolved`
3. **提升适用学习** → 检查是否需要提升到workspace
4. **链接相关条目** → 添加 See Also 引用
5. **升级重复问题** → recurrence_count 增加
### 6.3 回顾脚本
python3 "{SKILL_DIR}/scripts/review.py" --action status
python3 "{SKILL_DIR}/scripts/review.py" --action high_priority
python3 "{SKILL_DIR}/scripts/review.py" --action full_review
---
## 七、功能请求跟踪
### 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 - 记录错误
python3 "{SKILL_DIR}/scripts/record_error.py" \
--scene <场景> \
--error-type <错误类型> \
--question <问题> \
--wrong-answer <错误回答> \
--correct-answer <正确答案> \
--reason <原因> \
--level <等级> \
--source <来源> \
[--tags <标签>]
### 8.2 record_learning.py - 记录学习
python3 "{SKILL_DIR}/scripts/record_learning.py" \
--category <类型> \
--summary <摘要> \
--details <详情> \
--suggested-action <建议> \
--source <来源> \
[--pattern-key <模式键>] \
[--priority <优先级>]
### 8.3 record_feature.py - 记录功能请求
python3 "{SKILL_DIR}/scripts/record_feature.py" \
--name <功能名称> \
--context <用户场景> \
--complexity <复杂度> \
--priority <优先级>
### 8.4 query.py - 查询台账
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 - 统计面板
python3 "{SKILL_DIR}/scripts/stats_panel.py" --period today
python3 "{SKILL_DIR}/scripts/stats_panel.py" --period week
python3 "{SKILL_DIR}/scripts/stats_panel.py" --period all --format json
### 8.6 promote.py - 提升学习
python3 "{SKILL_DIR}/scripts/promote.py" \
--learning-id LRN-20260401-0001 \
--target SOUL.md
python3 "{SKILL_DIR}/scripts/promote.py" --action check_candidates
### 8.7 update_status.py - 更新状态
python3 "{SKILL_DIR}/scripts/update_status.py" \
--type error \
--id HE-20260401-0001 \
--status resolved
python3 "{SKILL_DIR}/scripts/update_status.py" \
--type learning \
--id LRN-20260401-0001 \
--status promoted \
--promoted-to "SOUL.md"
### 8.8 export_report.py - 导出报告
python3 "{SKILL_DIR}/scripts/export_report.py" --output report.md
python3 "{SKILL_DIR}/scripts/export_report.py" --output report.json --format json
python3 "{SKILL_DIR}/scripts/export_report.py" --output report.md --from 2026-04-01 --to 2026-04-30
### 8.9 review.py - 定期回顾
python3 "{SKILL_DIR}/scripts/review.py" --action status
python3 "{SKILL_DIR}/scripts/review.py" --action high_priority
python3 "{SKILL_DIR}/scripts/review.py" --action full_review
---
## 九、检测触发词速查表
### 9.1 错误纠正触发词
英语：
中文：
### 9.2 功能请求触发词
英语：
中文：
### 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 文件（推荐）
#### 方法二：手动安装
cp -r harness-engineering/ ~/.qclaw/skills/
mkdir -p ~/.qclaw/skills/harness-engineering/data/
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 安装（待发布）
/install harness-engineering
---
### 12.2 快速命令参考
#### 错误记录
python3 "{SKILL_DIR}/scripts/record_error.py" \
--scene "问答" \
--error-type "事实错误" \
--question "用户问题" \
--wrong-answer "错误回答" \
--correct-answer "正确答案" \
--reason "错误原因" \
--level "高"
#### 学习记录
python3 "{SKILL_DIR}/scripts/record_learning.py" \
--category correction \
--summary "一句话摘要" \
--details "详细上下文" \
--suggested-action "建议行动" \
--priority high
#### 功能请求
python3 "{SKILL_DIR}/scripts/record_feature.py" \
--name "功能名称" \
--context "用户场景" \
--complexity "中等"
#### 查询台账
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
#### 统计面板
python3 "{SKILL_DIR}/scripts/stats_panel.py" --period today
python3 "{SKILL_DIR}/scripts/stats_panel.py" --period week
python3 "{SKILL_DIR}/scripts/stats_panel.py" --period all --format json
#### 自动提升
python3 "{SKILL_DIR}/scripts/promote.py" --action check_candidates
python3 "{SKILL_DIR}/scripts/promote.py" --action auto_promote
#### 定期回顾
python3 "{SKILL_DIR}/scripts/review.py" --action status
python3 "{SKILL_DIR}/scripts/review.py" --action high_priority
python3 "{SKILL_DIR}/scripts/review.py" --action full_review
#### 回答前自检
python3 "{SKILL_DIR}/scripts/pre_answer_check.py" --question "用户问题"
#### 错误摘要注入
python3 "{SKILL_DIR}/scripts/inject_summary.py" --action session_start
---
### 12.3 自动进化机制
#### Cron 定时任务（可选配置）
/cron add --name "harness-auto-promote" \
--schedule "every 2h" \
--task "python3 {SKILL_DIR}/scripts/promote.py --action auto_promote"
/cron add --name "harness-weekly-review" \
--schedule "cron 0 9 1" \
--task "python3 {SKILL_DIR}/scripts/review.py --action full_review"
---
### 12.4 初始化
Skill首次使用时会自动创建必要的数据目录和文件：
- `data/error_ledger.jsonl`
- `data/feature_ledger.jsonl`
- `data/learnings_ledger.jsonl`
- `data/error_index.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：记录 → 学习 → 提升 → 进化** 🔧
共 1 个版本