# Apprentice Agent Training

> 训练"操作员式智能体"的通用方法论——像训练操作员一样训练 Agent，让它像学徒一样学会操作软件（出图/建模/设计/办公/数据分析等）。 触发条件：需要教 Agent 使用/操作某个软件；新建"XX 智能体训练"类项目；要复用"技能驱动 + 质检闭环 + 评分迭代"这套架构； 听到"像训练操作员一样训练智能体""教 Agent 用软件"等表述时。

- Skill: `openclaw-cn-dev/apprentice-agent-training` (Agent Skill)
- Install (CLI): `npx get-skill add openclaw-cn-dev/apprentice-agent-training`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openclaw-cn-dev/apprentice-agent-training/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: openclaw-cn-dev (https://skillmd.com/u/openclaw-cn-dev)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/openclaw-cn-dev/apprentice-agent-training

---


# 操作员式智能体训练（Apprentice Agent）

> 核心理念（华哥 2026-08-16 提出）：**像训练操作员一样训练智能体**——不是给 Agent 硬编码"操作软件的代码"，而是给它「操作手册 + 练习考核 + 经验沉淀」，让它像学徒一样成长。
> 已落地参考：渔芯 `22-出图智能体训练`（69 tests、158 零件库、14 技能、评分 50→96.16）。

## 一、三层库（训练流水线）

| 库 | 作用 | 类比 | 产出 |
|----|------|------|------|
| 素材库 | 原始素材（图纸/视频/文档/案例/标准） | 教材 | 用户上传 + 系统采集 |
| 训练数据库 | AI 解析后的结构化训练数据 | 练习册 | 解析对 / 数据集 / 报告 |
| 技能库 | 训练最终产出的可执行技能 JSON | 操作手册 | 8 大类技能 |

管线：`素材上传 → AI解析 → 结构化训练数据 → Agent学习 → 执行验证 → 评分 → 固化为技能`

## 二、四层架构（从"该做什么"到"真正执行"）

```
理论知识层  标准/规则/原则（告诉 Agent「该做什么、为什么」）
     ↓
技能层      JSON 定义（声明 inputs/steps/tool，告诉 Agent「怎么做」）
     ↓
桥接层      统一桥接（解析技能 → 软件的原子操作）
     ↓
软件引擎    真正执行操作的软件（FreeCAD/CadQuery/Excel/PS…）
```

## 三、质检闭环（师傅带徒弟）

```
接收指令 → 画前检查(分析→拆分→选技能→查标准)
         → 执行技能(操控软件，逐步推送进度)
         → 画后评分(合规→尺寸→标准→修正建议)
         → 自动修正循环(达标? 交付 : 修正→再检查→循环)
```

评分门槛：**≥95 优秀直接交付 / 80-94 合格自动修正 / <80 重新执行**。

## 四、评分迭代（学徒精进 = 自进化反馈）

```
Agent 生成 → 评分 → 得分<阈值 → 分析薄弱规则
  → 生成 improvement_hints（如 {"add_dimensions":0.6, "add_centerlines":0.8}）
  → 注入下一迭代参数 → 评分单调提升，直到达标或触及上限
```

强度系数：`strength = max(0.3, 1.0 - score/max + 0.1*iteration)`（分越低越激进，迭代越多越激进）。

## 五、技能定义格式（通用 JSON 模板）

```json
{
  "id": "xxx",
  "name": "操作名",
  "tool": "软件标识",
  "category": "分类",
  "inputs": {"参数名": "默认值"},
  "steps": [
    {"action": "原子操作名", "params": {"x": "$参数名"}}
  ],
  "output": "输出格式"
}
```

- `id` 唯一，文件名 = `{id}.json`
- `$param` 变量引用，执行时替换为用户实际输入
- `steps[].action` 对应桥接层的方法名
- 技能按类别存放：`bridge / control / operate / rules / templates / principles / workflows / analysis`

## 六、三条铁律

1. **工具操作型 Agent**：每个 Agent 动作对应工程师/操作员的真实操作（`tool_draw_rect`、`tool_draw_bolt_group`…），日志完整可审计。不做"一次性黑盒生成整个文件"。
2. **技能回流**：每次成功经验固化成 JSON 技能，同步到团队共享仓库（GitHub 私仓），所有 Agent 开工前 `git pull` 学习最新技能。
3. **真流式**：让用户看到 Agent 操控工具的**过程**（逐步推送事件），不是黑盒等最终结果。用 `step_callback → Queue → Thread → SSE` 桥接同步 Agent 与异步响应。

## 七、通用化映射（出图 → 任意软件操作）

| 出图项目（已落地） | 通用化到任意软件 |
|--------------------|------------------|
| CAD 出图 | 任意软件操作（建模/设计/办公/数据分析/剪辑…） |
| FreeCAD/CadQuery/SolidWorks | 任意目标软件（Excel/Photoshop/Blender/浏览器…） |
| 15 步画图流程 | N 步操作流程 |
| GB/T 国标 / 材料参数 | 任意领域的规范/规则/知识 |
| 质检闭环 + 评分 | 任意质量闭环 |

## 八、新项目落地步骤（直接套）

1. **定软件**：明确要教 Agent 操作哪个软件，确认有没有可用的桥接方式（MCP / Python API / COM / 脚本）。
2. **建三层库**：建 `素材库/ 训练数据库/ 技能库/` 三个目录，定技能分类（8 类可裁剪）。
3. **写桥接层**：把软件的原子操作封装成统一方法（`new_doc` / `create_xxx` / `export`…），对应技能 JSON 的 `action`。
4. **定评分规则**：列出可量化的质量规则（图层/尺寸/规范/完整性…），写评分器（100 分制）。
5. **写质检闭环**：`pre_check → execute → post_check → auto_fix_loop` 四个 workflow 技能。
6. **训练第一批技能**：拿真实案例，AI 解析 → 生成技能 JSON → Agent 学习 → 执行 → 评分 → 入库。
7. **接自进化**：评分低时生成 `improvement_hints`，注入下一迭代，直到达标。
8. **技能回流**：cron 定期同步技能库到团队仓库，所有 Agent 开工前 pull。

## 关键陷阱

- **多领域 step 编号冲突**：不同领域操作步数不同时，先数清步骤数再分配槽位，否则编号共用。宁可合并相邻步骤，保证每个编号唯一。
- **假完成**：说"完成"前必须全链路验证（后端 → 桥接 → 输出文件 → 评分）。
- **假流式**：先跑完全部步骤再逐条 yield + sleep = 回放，不是实时过程。
- **GUI 软件在服务进程里打不开**：macOS GUI 需主线程事件循环，用独立桥接进程（HTTP server）转发，不在 uvicorn 后台线程里开窗口。

## ⚠️ P0 陷阱：自评分系统的结构性盲区（2026-08-25 实战发现）

> **这是 apprentice-agent 架构的元陷阱**——任何"自己生成 + 自己评分"的 Agent 系统都必须做"客户视角审计"，否则评分报告会自我欺骗。

### 陷阱本质

**Agent 自己写的评分规则，只检测"自己写的时候想到了的东西"**。如果实现偷懒（图层骗分、实体类型替代等），评分规则往往和实现**共同失明**——两者都用同一种错误视角看世界。

### 真实案例（22-出图智能体训练 v30，2026-08-25 审计发现）

**CLAUDE.md 宣称**："96.05/100 分，8 设备全部 ≥95 优秀"。

**ezdxf 实测**：8 个 DXF 文件全部 0 个真实 `DIMENSION` 实体，尺寸数字"1500/1100/800"画在 DIMENSION 图层但 `dxftype()` 是 `TEXT` 而非 `DIMENSION`。

**根因代码**（`quality_scorer.py:112-122`）：

```python
def _rule_dimensions(self, doc):
    msp = doc.modelspace()
    # ❌ 错把 DIMENSION 层上的 LINE+TEXT 当成"标注"算分
    dim_count = sum(1 for e in msp if e.dxftype() in ("LINE", "TEXT") and
                    "DIMENSION" in e.dxf.layer.upper())
    if dim_count >= 10: return 10  # 永远满分
```

**灾难性后果**：
- 发给车间 = 工程师必须手测每个尺寸，**无法投产**
- 评分 96 给了虚假信心，**50 天无人复查**

### 防御：客户视角审计 4 步法（强制）

**触发条件**：任何"Agent 自评分"系统（DXF / 文本 / 代码 / 表格 / 设计稿），交付前**必须**走 4 步。

```
1. 下游工具真打开    用最终用户会用的工具打开产物（ezdxf / SolidWorks / Word / Excel）
                    → 验证产物对下游工具"语义可用"，不是只"视觉可用"
2. 抽检自评指标     找 2-3 条评分规则，问"它检查的是实体的语义还是字符串/图层名？"
                    → 按"实体类型/语义"判定才可信，按"图层名/字符串模式"判定可疑
3. 反向验证         把明显错误产物喂给评分器，看评分是否下降到应得值
                    → 评分虚高 = 评分规则被骗
4. 跨项目数据一致性 同一编号（如 HW-002）在多套系统里命名/参数是否一致
                    → 跨系统冲突 = 集成时会画错
```

**反面教材**：CLAUDE.md 写的 96.05 + 90 tests passing，**全链路是 Agent 自证**。没有人用 ezdxf 真正打开过 8 张图。

### 修复模板（评分规则改写对照表）

| 检测对象 | ❌ 假阳性写法（图层名欺骗） | ✅ 真阳性写法（实体类型） |
|----------|------------------------|------------------------|
| 尺寸标注 | `dxftype() in ("LINE","TEXT") and "DIMENSION" in layer` | `e.dxftype().startswith("DIMENSION")` |
| 中心线 | `dxftype() == "LINE" and layer == "CENTER"` | `e.dxftype() == "LINE" and linetype == "CENTER"` |
| 标题栏 | `"图号" in e.text` | `e.dxftype() in ("TEXT","INSERT") and block_name == "TITLE"` |
| BOM 表 | `"BOM" in layer` | `e.dxftype() in ("INSERT","BLOCK") and block_name == "BOM"` |

**铁律**：评分规则**只接受实体的"语义身份"**（dxftype / 块名 / linetype），不接受"它被放在哪个图层"。

### 自评审计清单（cron 化推荐）

每个 apprentice-agent 项目每 30 天跑 1 次：
- [ ] 抽 5 个真实产出，用下游工具真打开
- [ ] 对比实测实体类型 vs 评分规则检测的实体类型
- [ ] 跨项目同一编号数据一致性比对
- [ ] 50 天静默 = 立即警报（参考 `24-16:00` 设计冲刺 5天节奏）

详见 `references/self-evaluator-audit.md`（ezdxf 审计脚本 + HW-001~008 实测数据 + 修复模板）。

