# 第 10 章：复杂实战案例（dsh 真实跑出来的）

> 本章目标：用两个**真实在 dsh 里跑完的复杂任务**，展示 dsh 在多步工具链下的实际能力、产出质量与耗时。
> **隐私声明**：两个案例全部使用**合成数据/自造代码**，不涉及任何真实业务数据或敏感信息。

## TL;DR（本章核心，30 秒版）

1. **案例 A（数据质量分析，186 秒）**：52 行脏数据 → 分析 → 清洗脚本 → 可视化 → 运行验证，52→35 行，所有问题归零
2. **案例 B（5-bug 修复 + 49 测试，94 秒）**：故意埋 5 个 bug 的计算器模块 → 全修复 → 49 个测试全过，覆盖边界/精度/异常
3. **dsh 的画像**：多步工具链自动编排、有判断力（主动说明数据权衡）、产物可追踪、耗时可控（94-186s）
4. **关键启示**：提示词把验收标准写清楚（如"运行验证"），dsh 会照着闭环——复杂任务建议明确"做什么 + 怎么验收"
5. **失败恢复**：本案例未触发；生产环境建议配 guard 超时 + 人工审批

<details><summary>本章导航</summary>
<!-- [fix] 链接健康检查：案例 A/B 锚点中 ` + ` 在 GitHub slug 里产生双连字符（--），原单连字符无法命中 -->
- [案例 A：数据质量分析 + 清洗 + 可视化（186 秒）](#案例-a数据质量分析--清洗--可视化186-秒)
- [案例 B：5-bug 代码修复 + 49 个测试（94 秒）](#案例-b5-bug-代码修复--49-个测试94-秒)
- [案例总结：dsh 在复杂任务上的画像](#案例总结dsh-在复杂任务上的画像)
- [案例 C：HTML 解析（Web 前端，约 3m18s）](#案例-chtml-解析web-前端约-3m18s)
- [案例 D：代码重构（软件工程，约 4m37s）](#案例-d代码重构软件工程约-4m37s)
- [案例 E：API 文档生成（文档，约 1m04s）](#案例-eapi-文档生成文档约-1m04s)
- [第二批案例画像](#第二批案例画像)
</details>

## 案例 A：数据质量分析 + 清洗 + 可视化（186 秒）

### 任务

给 dsh 一份含脏数据的合成 JSON（52 行：缺失值、类型错误、重复行、异常值 99999），要求：
1. 分析数据质量问题
2. 编写清洗脚本 `clean.py`
3. 编写可视化脚本 `visualize.py`（生成 `chart.png`）
4. 运行两个脚本验证

### dsh 怎么做的（工具链）

<!-- [style] 工具链示意代码块统一补 text 语言标签 -->
```text
read(sales_data.json) → write(clean.py) → bash(python clean.py)
→ write(visualize.py) → bash(python visualize.py) → read(输出) → 总结
```

### 产出与验证

| 产物 | 结果 |
|---|---|
| `clean.py` | ✅ 运行成功，52 → **35 行**，所有问题归零 |
| `visualize.py` + `chart.png` | ✅ 生成有效 PNG（1950×825） |
| 清洗策略 | 缺失金额中位数填充、异常值删除、去重、类型统一 |

![dsh 生成的销售额可视化（案例 A 产物）](./assets/case-chart.png)

### 输出要点（体现判断力，不是机械执行）

> - 中位数填充会在直方图产生 510 尖峰——插补的固有副作用，建议说明
> - 若 99999 是真实大额订单，建议改用 IQR/分位数法而非一刀切删除
> - 清洗后统计：N=35，均值 489.43，中位数 510，标准差 181.73

**dsh 不仅执行了任务，还主动说明了数据处理的权衡与假设**——这是 agent 工程层"会思考"的证据。

## 案例 B：5-bug 代码修复 + 49 个测试（94 秒）

### 任务

给 dsh 一个**故意埋了 5 个 bug** 的 Python 计算器模块，要求：找到所有 bug → 修复 → 编写完整单元测试 → 运行验证。

### 埋的 bug

1. `add` 误写为 `a - b`
2. `divide` 除零静默返回 0（应抛异常）
3. `factorial` 负数静默返回 -1（应抛异常）
4. `factorial` 的 `range(1, n)` 漏乘 n
5. `format_money` 未格式化为两位小数

### dsh 的修复 + 测试（验证：49 passed）

完整测试见 [case-test-calculator.py](./assets/case-test-calculator.py)——49 个用例覆盖：

| 函数 | 覆盖 |
|---|---|
| `add` | 正/负/零/浮点/精度/交换律 |
| `subtract` | 负结果/零边界/浮点 |
| `multiply` | 符号组合/乘零/浮点 |
| `divide` | 整除/符号/浮点/**除零必须抛 ZeroDivisionError** |
| `factorial` | 0!/1! 边界/已知值/**负数必须抛 ValueError** |
| `format_money` | 补零/四舍五入/**0.1+0.2 舍入**/负数 |

```bash
python -m pytest test_calculator.py -v   # 49 passed in 0.37s
```

### 观察：dsh 的表现

- **完整闭环**：读 → 修 → 写测试 → 跑测试 → 总结，无人工干预
- **修复质量**：5 个 bug 全修复且补了 docstring 说明
- **测试设计**：覆盖边界（除零/负数/精度），不是"能跑就行"

## 案例总结：dsh 在复杂任务上的画像

| 维度 | 表现 |
|---|---|
| 多步工具链 | ✅ 自动编排（读→写→跑→验证→总结） |
| 复杂任务耗时 | 94s-186s（同模型同网关，比 benchmark 简单任务慢但可控） |
| 产出质量 | ✅ 有判断力（数据权衡说明、测试边界设计） |
| 产物追踪 | ✅ 生成文件可在对话末尾直接打开 |
| 失败恢复 | 本案例未触发；生产建议配 guard 超时 + 人工审批 |

**给新手的启示**：dsh 处理"多文件、多步骤、要验证"的任务很顺手——这也是它作为 Agent 运行时的主要价值场景。复杂任务建议：提示词把**验收标准写清楚**（如"运行验证"），dsh 会照着闭环。

---

## 动手练习（检验你是否真懂了）

1. **理解题**：不看原文，说出案例 A（数据质量分析）的工具链顺序（read → write → bash → ...），以及最终产出是什么
   > 自查：参考本章"案例 A"的"dsh 怎么做的"段落
2. **理解题**：案例 B（5-bug 修复）里，dsh 补的 49 个测试覆盖了哪些边界情况？为什么"除零必须抛 ZeroDivisionError"是一个重要的测试点？
   > 自查：参考本章"案例 B"的测试覆盖表格
3. **动手题**：设计一个类似的"数据质量分析"任务：准备一份含脏数据的 CSV（至少 3 种问题：缺失值、类型错误、异常值），写提示词让 dsh 分析 + 清洗 + 可视化，记录耗时和产出
   > 自查：参考本章案例 A 的任务描述 + 产出验证表格
4. **动手题**：设计一个类似的"bug 修复"任务：写一个故意含 3 个 bug 的 Python 模块（如字符串处理、日期计算），让 dsh 找 bug → 修复 → 写测试 → 运行验证，记录耗时和测试通过率
   > 自查：参考本章案例 B 的任务描述 + "dsh 的表现"观察段落
5. **思考题**：案例 A 里 dsh "主动说明了数据处理的权衡与假设"（如中位数填充的尖峰副作用）。这个行为对"agent 工程层"的设计有什么启示？模型只是执行命令，还是真的有"判断力"？
   > 自查：参考本章案例 A 的"输出要点"段落 + 案例总结表格
6. **思考题**：本章结语说"提示词把验收标准写清楚，dsh 会照着闭环"。如果案例 A 的提示词只说"处理一下这个数据"而不说"运行验证"，dsh 的表现会有什么不同？
   > 自查：参考本章"给新手的启示"段落 + 案例 A 的工具链（含 bash 运行验证）

## 常见疑问 FAQ

**Q1：案例 A 耗时 186 秒，案例 B 耗时 94 秒，这个速度算快还是慢？**
取决于任务复杂度和模型档位。同模型同网关下，比 benchmark 简单任务慢但可控。关键不是绝对速度，而是"多步工具链自动编排 + 产出质量 + 无人工干预"的综合价值。如果想提速，参考第 6 章的推理档位策略 + 提速插件示例。

**Q2：案例里的"合成数据"是什么意思？为什么不用真实数据？**
隐私保护。本白皮书不涉及任何真实业务数据或敏感信息。合成数据是"故意构造的、不含真实信息的数据"，用于演示 dsh 的能力。你在自己环境里可以用真实数据，但要注意数据安全。

**Q3：如果 dsh 在复杂任务中"卡住了"（比如某步工具调用失败），怎么办？**
几种处理：① 看 dsh 进程日志，定位哪步失败；② 检查工具调用的输入是否正确（如文件路径、命令语法）；③ 配 guard 超时（`guard/*` 包），避免无限等待；④ 生产环境建议配人工审批（`interaction/*`），危险操作前确认。

**Q4：案例 B 的 49 个测试是 dsh 自动生成的，质量怎么样？**
质量不错。覆盖了边界（除零/负数/精度）、异常（必须抛特定异常）、常规（正/负/零/浮点）。但自动生成的测试可能漏掉"业务逻辑特有的边界"——建议人工 review 测试设计，补充领域特定的用例。

**Q5：我想让 dsh 跑一个"多文件、多步骤"的任务，提示词怎么写效果最好？**
三个原则：① 明确目标（"做什么"）；② 明确验收标准（"怎么算完成"，如"运行验证""49 个测试全过"）；③ 明确约束（"不能做什么"，如"不能删原始数据"）。参考本章两个案例的提示词结构。

**Q6：案例总结说"失败恢复本案例未触发"，那 dsh 的失败恢复能力怎么样？**
dsh 有 compaction（上下文溢出恢复）、guard（超时）、interaction（审批）等机制，但复杂场景的失败恢复还在演进中。生产环境建议：① 配 guard 超时避免卡死；② 配人工审批避免误操作；③ 长任务分步验证，不要"一口气跑完再检查"。具体配置参考第 8 章 8.5 节安全模型。

---

**附录 A**：[术语表与命令速查](./appendix-glossary.md)

## 扩展案例（第二批，三个功能领域）

> 完整执行报告见 [case-expansion-report.md](./case-expansion-report.md)，产物在 `docs/assets/`。全部合成数据。

### 案例 C：HTML 解析（Web 前端，约 3m18s）

**任务**：给定含表格+表单+图表的合成 HTML，编写零第三方依赖的解析脚本提取表格并输出 CSV。

**dsh 的表现**：
- **零依赖权衡**：主动选标准库 `html.parser`（而非 BeautifulSoup）
- **健壮性**：实现表格嵌套深度计数，防止越界
- **路径无关**：用 `__file__` 定位输入，不依赖运行目录

产物：[case-c-parser.py](./assets/case-c-parser.py)｜验证：输出 9 行×7 列 CSV，与源表逐字段一致

### 案例 D：代码重构（软件工程，约 4m37s）

**任务**：把约 200 行过程式订单脚本（含重复代码 `calc_order_total` / `calc_order_total_v2`）重构为 OOP + 职责分离，行为一致，测试验证。

**dsh 的表现**：
- **精准识别重复**：合并两份相同逻辑为 `Order.total()` 单一入口
- **SOLID 设计**：Product/Customer/Order（模型）+ OrderProcessor（查询）+ ReportGenerator（报告）
- **向后兼容**：保留模块级函数接口，可直接替换
- **测试深度**：17/17 PASS——不仅对比函数返回值，还对比**脚本级整体运行产物**（report.txt / orders.json）
- **沙箱感知**：发现 `tempfile.mkdtemp` 在沙箱下 0700 ACL 不可写，主动换方案

产物：[case-d-orders_refactored.py](./assets/case-d-orders_refactored.py) + [case-d-test_refactor.py](./assets/case-d-test_refactor.py)｜验证：**17/17 PASS**

### 案例 E：API 文档生成（文档，约 1m04s）

**任务**：给含 8 个函数的 Python 模块生成完整 Markdown API 文档（参数表/返回值/异常/示例/边界）。

**dsh 的表现**：
- **契约差异识别**：主动发现"文档声明"与"代码实现"的差异（如 `user_id` 字符集未强制校验），如实写入边界章节
- **防御式文档**：为每个函数标注调用陷阱（负数 limit、空 updates 行为）
- **ReadTheDocs 风格**：423 行，8 个函数全覆盖，示例含 doctest 风格

产物：[case-e-api.md](./assets/case-e-api.md)

### 第二批案例画像

| 维度 | 表现 |
|---|---|
| 跨领域能力 | ✅ Web/工程/文档三种任务都能闭环 |
| 工程意识 | ✅ 零依赖权衡、沙箱感知、向后兼容、契约差异识别 |
| 验证习惯 | ✅ 每个案例都运行验证（含脚本级产物对比） |
| 耗时 | 1-5 分钟/案例，复杂度越高越久 |

**总结**：dsh 在"要写代码 + 要验证"的工程任务上表现稳定，且**会做权衡（依赖/兼容/安全）**——这是 agent 从"能答"到"能干活"的分水岭。