# 实战 - AI 赋能的智能测试与质量保障

---

## 一、核心概念

### 1.1 SDD（Specification-Driven Development）

规格驱动开发，写规格文档（Spec），让规格 = 一等公民，代码只是规格的可执行表达。

**SDD 开发过程**：

```
写 Spec 文档 → 从 Spec 提取测试 → 按测试写代码
```

**优势**：规格可版本化、可校验、可被 AI 读取

### 1.2 TDD（Test-Driven Development）

铁律：没有先失败的测试，就没有生产代码。

**红-绿-重构循环**：

| 阶段 | 做什么 | 验证 |
|------|--------|------|
| **RED 红灯** | 写一个最小的失败测试 | 运行测试，看到 FAILED |
| **GREEN 绿灯** | 写最少的代码让测试通过 | 运行测试，看到 PASSED |
| **REFACTOR 重构** | 在测试保持绿灯的前提下优化代码 | 运行测试，仍然 PASSED |

**核心**：在看到一个失败的测试之前，你不能写任何生产代码。这个失败是扳机，确认你正在解决一个真实存在的问题，而不是臆想。

### 1.3 Harness Engineering：驭缰工程

> Agent = Model（模型） + Harness（缰绳）

Harness 是模型之外的一切，即：约束系统、反馈回路、工具环境、验证机制。

**人类设计约束 → AI 写代码 → 机器执行**（工程师的产出从代码变成了约束系统）

**工程演进**：

| 年份 | 阶段 |
|------|------|
| 2023 | Prompt Engineering 提示词工程 |
| 2025 | Context Engineering 上下文工程 |
| 2026 | Harness Engineering 驭缰工程 |

---

## 二、Harness 的三支柱

### 2.1 Inform（告知）

- AGENTS.md 导航文件、上下文工程
- 作用：AGENTS.md 项目导航入口

### 2.2 Constrain（约束）

- 架构边界、权限控制、自定义 Linter（代码检查器）
- 示例：`linters/check_report_structure.py`

### 2.3 Verify（验证）

- 自动化测试、类型检查、结构测试
- 示例：`validate_report()` + pytest 测试套件

---

## 三、核心机制

### 3.1 记录系统

一切决策、规范、计划都必须以版本化的文件提交到仓库。

> Spec 文档（`spec/research_spec.md`）就是这个记录系统的体现。报告的输出格式、约束条件 C1-C7、API 依赖——全部写在仓库里，而不是在脑子里。

### 3.2 AGENTS.md

- **概念**：是一份 50~100 行的目录页，告诉 Agent 去哪里找详细信息，而不是把所有信息堆在一起。
- **作用**：渐进式披露——Agent 从小入口开始，按需深入。
- **要点**：AGENTS.md 只有关键路标，不写具体规则（具体规则在 Spec 和 Linter 里）。

### 3.3 Lint 规则

- **概念**：Lint（或 Linter）是一种静态代码分析工具，在不运行代码的情况下扫描源代码，自动检测潜在错误。
- **要点**：Lint 错误信息里可以嵌入修复指令，文档会腐烂，Lint 规则不会。
- **类型**：自定义结构 Linter = 代码层面的校验 + 项目级的结构检查器

### 3.4 CI/CD 质量门禁

| 门禁 | 内容 |
|------|------|
| 第一道门 | 结构 Lint 检查 |
| 第二道门 | 单元测试 |
| 第三道门 | 集成测试 |

---

## 四、Ralph 实战

### 4.1 概念

Ralph = 一个 Bash 脚本编排器，反复启动 AI Agent，每次迭代清空上下文，让 Agent 在循环中自主完成任务。

人类唯一要做的就是写一份 PROMPT.md（任务描述文件），然后坐等结果。

### 4.2 Ralph 的信条

| 信条 | 原文 | 含义 |
|------|------|------|
| 信条1 | Fresh Context Is Reliability | 新鲜的上下文就是可靠性 |
| 信条2 | Backpressure Over Prescription | 用背压代替处方 |
| 信条3 | The Plan Is Disposable | 计划是用完即弃的 |
| 信条4 | Disk Is State, Git Is Memory | 磁盘是状态，Git 是记忆 |
| 信条5 | Steer With Signals, Not Scripts | 用信号引导，不用脚本控制 |
| 信条6 | Let Ralph Ralph | 让 Ralph 做 Ralph 的事 |

### 4.3 Ralph 帽子系统

每轮迭代只让 Agent 戴一顶帽子，专注做一件事：

```
Planner 规划者（拆解任务）
  → Builder 构建者（写测试+写代码）
    → Critic 审查者（独立验证）
      → Finalizer 终结者（确认完成）
```

### 4.4 实战流程

| 迭代 | 角色 | 任务 |
|------|------|------|
| 迭代1 | **Planner 规划者** | 读取 PROMPT.md，拆解任务为具体步骤，把计划写入 `scratchpad.md`（便签本），然后交给下一轮 |
| 迭代2 | **Builder 构建者** [TDD] | 严格遵循 TDD |
| 迭代3 | **Critic 审查者** | 独立重跑 pytest |
| 迭代4 | **Finalizer 终结者** | 确认所有 PROMPT.md 中的需求都已满足，输出 LOOP_COMPLETE 信号，循环终止 |

---

## 五、Hermes Agent 实战

### 5.1 闭环学习机制

```
接到任务 → 加载相关 Skill → 执行任务 → 自动创建新 Skill → 持久化记忆
```

### 5.2 与传统 Agent 的区别

| 特性 | 说明 |
|------|------|
| **自主创建技能** | 处理完复杂任务后，自动生成可复用的 Skill 文件 |
| **技能自我改进** | 每次使用 Skill 时，如果发现可以优化的地方，自动更新 Skill 内容 |
| **持久化记忆** | SQLite 数据库存储对话历史和研究成果，支持语义搜索，跨会话调用 |

### 5.3 四个软件开发技能

| 技能 | 对应支柱 | 说明 |
|------|----------|------|
| **test-driven-development** | TDD | 任务遵循 TDD |
| **writing-plans** | Inform | 任务开始前生成一份详细的实现计划 |
| **systematic-debugging** | Verify | 强制执行四阶段流程：先找根因，再动手修 |
| **subagent-driven-development** | 编排循环 | 每个步骤分配独立子 Agent，干净上下文，双阶段审查 |

---

## 六、三个概念的区别

| 概念 | 定位 | 说明 |
|------|------|------|
| **Harness Engineering** | 方法论（道） | 告诉你该怎么设计约束系统 |
| **Ralph** | 编排器（骨架） | 让 Agent 在循环中自主工作 |
| **Hermes Agent** | 完整产品（器） | 集编排、学习、记忆、多平台于一体 |

---

## 七、四个概念的递进关系

| 概念 | 定位 | 对应产物 |
|------|------|----------|
| **SDD 规格驱动** | 什么是对的 | `spec/research_spec.md` |
| **TDD 测试驱动** | 证明它是对的 | `tests/test_reporter.py` |
| **Harness 驭缰工程** | 保证它一直对 | `AGENTS.md` + `linters/` |
| **Agent 编排** | AI 自己做对 | Ralph / Hermes |

| 维度 | Harness Engineering | Ralph | Hermes Agent | Stock Research |
|------|---------------------|-------|--------------|----------------|
| **告知层 Inform** | AGENTS.md | PROMPT.md | Skills 技能系统 | AGENTS.md + Spec |
| **约束层 Constrain** | 自定义 Linter | 帽子系统（角色隔离） | 工具白名单 | `check_report_structure.py` |
| **验证层 Verify** | 自动化测试 | Critic 独立审查 | 约 3000 个测试 | 85 个测试 + CI/CD |
| **学习能力** | -- | -- | 自动创建/改进 Skill | -- |

---

## 八、Prompt 模板

### 写 Spec

```
我想撰写一个软件SPEC，需求是：
输入一个股票代码(如 "600519")，自动从多个维度联网搜索信息，
通过 Qwen 大模型进行分析，生成结构化深度研究报告。
使用到 akshare
方便后续进行测试和代码生成，给我SPEC即可
```

### TDD 开发

```
Step1，撰写一个SPEC
Step2，撰写测试用例
这里有C1-C7的约束，帮我先撰写测试代码（我打算用TDD的模式驱动开发，先不用开发）
测试代码放到 tests文件夹中，到时候实际代码会放到 src文件夹中
Step3，运行测试用例
运行测试用例，使用TDD 红-绿-重构循环
Step4，@research_spec.md 基于这个SPEC文档完成完整的项目，这里会用到 akshare 和 qwen大模型（可以使用环境变量中的 DASHSCOPE_API_KEY）
```

---

## 九、环境配置

### Python 包

- `pytest`

### 代码文件

| 文件 | 说明 |
|------|------|
| `stock-research/spec/research_spec.md` | Spec 文档 |
| `stock-research/AGENTS.md` | Harness 路标 AGENTS.md |
| `stock-research/ralph_demo.py` | Mini Ralph |
| [Ralph 官方库](https://github.com/snarktank/ralph/tree/main) | Ralph 官方仓库 |
| [Hermes Agent 官方库](https://github.com/NousResearch/hermes-agent) | Hermes Agent 官方仓库 |


class37-AI 赋能的智能测试与质量保障

# 实战 - HuggingFace 生态

---

## 一、技术基础

### 1.1 什么是 HuggingFace

- **AI 界的 GitHub**：找模型和数据
- **AI 界的 App Store**：提供了很多现成的 Pipeline

### 1.2 HuggingFace 的核心

| 组件 | 类型 | 说明 |
|------|------|------|
| **Transformers** | 库 | 提供统一的 Python 接口 |
| **Model Hub** | 网站 | 仓库，存放模型权重文件 |
| **Datasets** | 库 | 燃料库，下载数据集并自动处理成模型能读的格式 |

### 1.3 Transformer 模型三个流派

| 架构 | 能力 | 代表模型 | 应用场景 |
|------|------|----------|----------|
| **Encoder-Only** | 擅长理解和分析 | BERT | 文本分类、实体识别、搜索匹配 |
| **Decoder-Only** | 擅长生成 | GPT系列、Llama、Qwen | 聊天机器人、代码生成、创意写作 |
| **Encoder-Decoder** | 擅长转换 | T5、BART、GLM | 机器翻译、文本摘要 |

---

## 二、常用模型

### 2.1 NLP（自然语言处理）领域

#### 基础理解类（Encoder-Only）

- **BERT / RoBERTa**：文本分类、命名实体识别（NER）的首选经典
- **DistilBERT**：BERT 的轻量化版本，推理速度更快，适合端侧应用

#### 生成类（Decoder-Only / 大语言模型）

| 模型 | 来源 | 特点 |
|------|------|------|
| Llama 系列 | Meta | 最主流的开源大模型，适合对话、逻辑推理 |
| Qwen 系列 | 阿里 | 中文能力极强，开源社区的热门选择 |
| DeepSeek 系列 | 国产 | 近期极具性价比，常用于生成和思考任务 |
| GPT-2 | OpenAI | 轻量级，常作为教学文本生成的入门案例 |

#### 翻译与摘要（Encoder-Decoder）

- **T5 / FLAN-T5**：能够将所有 NLP 任务转换为"文本到文本"的格式
- **BART**：擅长文本纠错和长文档摘要

### 2.2 CV（计算机视觉）与多模态领域

- **ViT (Vision Transformer)**：图像分类的标杆
- **Stable Diffusion**：目前最火的开源图像生成模型
- **CLIP (OpenAI)**：连接文本与图像，常用于以图搜图或零样本分类

---

## 三、常用 Datasets

| 领域 | 数据集 |
|------|--------|
| 情感分析 | IMDb / Amazon Polarity |
| 问答系统 | SQuAD / CoQA |
| 大模型预训练 | FineWeb / C4 |
| 代码生成 | MBPP / CodeContests |
| 语音识别 | Common Voice |
| 中文特定 | CLUECorpusSmall |

---

## 四、核心组件

### 4.1 Tokenization

- **概念**：模型不认识汉字或英文单词，它只认识数字。Tokenizer 是人类语言和机器数字之间的桥梁。
- **要点**：不同的模型有专属的 Tokenizer，不能混用！用 BERT 的 Tokenizer 去处理数据喂给 GPT 模型，会报错或输出乱码

### 4.2 Token 的定义

- **概念**：Token 是大型语言模型处理文本的最小单位。需要将文本切分成一个个 Token，再将 Token 转换为数字（向量）进行运算。
- **要点**：分词方式的不同会直接影响模型的效率和对语言细节的理解能力。
- **查看工具**：[tiktokenizer](https://tiktokenizer.vercel.app/)

### 4.3 Model

| 类型 | 说明 |
|------|------|
| **AutoModel** (Base Model) | 只有大脑，输出隐藏状态（Hidden States），一堆高维向量 |
| **AutoModelForSequenceClassification** | 大脑 + 嘴巴，直接输出分类的分数 |

### 4.4 Pipeline

**概念**：Pipeline 是一个全自动的黑盒，自动完成三个步骤：

```
预处理 (Tokenizer) → 模型推理 (Model) → 后处理 (Post-processing)
```

---

## 五、常用任务（Task）速查

### NLP 常用任务

| 任务名称 | 功能 |
|----------|------|
| `sentiment-analysis` | 情感分析，判断文本褒贬 |
| `text-generation` | 文本生成，如写故事、续写代码 |
| `zero-shot-classification` | 零样本分类，无需训练即可根据自定义标签分类 |
| `question-answering` | 问答系统，根据给定的上下文回答问题 |
| `summarization` | 自动摘要，将长文浓缩为短句 |
| `translation_xx_to_yy` | 翻译任务，如 `translation_en_to_zh` |
| `ner` | 命名实体识别，提取人名、地名、组织名 |

### CV & 音频常用任务

| 任务名称 | 功能 |
|----------|------|
| `image-classification` | 图像分类 |
| `object-detection` | 目标检测，识别图中的物体并定位 |
| `automatic-speech-recognition` (ASR) | 语音转文字 |
| `text-to-speech` (TTS) | 文字转语音 |

---

## 六、国内使用 HuggingFace

### 方案 1：使用 HF-Mirror（镜像站）

```python
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
```

### 方案 2：使用 ModelScope（魔搭社区）

使用阿里的 ModelScope 下载文件，然后用 HuggingFace 加载。

---

## 七、微调（Fine-tuning）

### 7.1 预训练 vs 微调

| 阶段 | 比喻 | 说明 |
|------|------|------|
| **Pre-training（预训练）** | 大学通识教育 | 模型读了海量的维基百科、书籍，懂语法，懂成语 |
| **Fine-tuning（微调）** | 岗前专业培训 | 用特定领域的数据再训练，从"懂中文的毕业生"变成"懂医疗发票的审核员" |

> 预训练模型已经具备语言理解能力，微调只需要少量领域数据即可适应特定任务。

### 7.2 微调核心工具

#### Datasets（数据加载与清洗）

- **加载**：`load_dataset("csv", data_files="my_data.csv")`
- **Map 函数**：不是简单的 for 循环，而是支持多进程的并行处理
- **操作**：把文本列（Text）批量转换成数字列（Input IDs）

#### DataCollator（动态补齐）

- **痛点**：BERT 模型要求同一批（Batch）进来的数据长度必须一致
- **作用**：训练速度极大提升，显存占用大幅下降

### 7.3 Trainer API

| 维度 | 传统 PyTorch 写法 | HuggingFace Trainer |
|------|---------|---------|
| 代码量 | 50+ 行循环代码 | 实例化 1 个类 |
| 功能支持 | 需手写日志、保存、断点续训 | 开箱即用 (Checkpoints, Logging) |
| 硬件优化 | 需手动配置混合精度 (fp16) | 参数 `fp16=True` 即可 |
| 多卡训练 | 配置 DistributedDataParallel（极难） | 自动适配多卡 |

---

## 八、HuggingFace 要点总结

1. **模型**不仅仅是代码，它是一种能力
2. **数据集**不仅仅是文件，它是知识
3. **Pipeline** 则是将能力与知识打包好的一键服务（Pipeline 是最快的落地方式，Demo 阶段首选）
4. **Tokenizer** 的 padding 和 truncation 是批处理数据的关键
5. **AutoModelFor...** 系列封装了特定任务的头，微调时通常使用这一类模型

---

## 九、项目实战：垃圾邮件分类器

| 步骤 | 说明 |
|------|------|
| Step 1 | 准备环境与数据：下载模型、准备训练数据 |
| Step 2 | 数据预处理（Tokenization）：使用 BERT 的 Tokenizer 将文本转换为模型可理解的数字序列 |
| Step 3 | DataCollator 动态补齐：只补齐到当前批次中最长的长度，大幅提升训练效率 |
| Step 4 | 模型加载 |
| Step 5 | 评估指标定义 |
| Step 6 | 训练配置与执行：使用 Trainer API 简化训练流程 |
| Step 7 | 模型推理 |

---

## 十、环境配置

### Python 包

- `torch`
- `transformers`
- `modelscope`

### GPU

- CUDA v12.9.2

### 代码文件

| 文件 | 说明 |
|------|------|
| `2-文本生成.py` | HuggingFace Pipeline 使用 |
| `6-实现Pipeline.py` | 手写 Pipeline |
| `7-垃圾邮件分类器.py` | HuggingFace 微调 |
| `8-垃圾邮件分类器-Qwen.py` | 使用 LLM 模型 |
