# 第 5 章：dsh 能帮你做什么——应用场景全景

> 本章目标：抛开"如何开发 dsh"的视角，站在**使用者**角度，看 dsh 能在哪些日常场景真正帮到你。每个场景都有可复制的任务示例与真实耗时参考。

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

1. **dsh 是通用 Agent 运行时**：不只是编码助手——数据分析、文档生成、自动化、代码理解都能干
2. **五个核心场景**：日常编码 / 数据处理 / 文档知识 / 自动化运维 / 代码理解与重构
3. **用法一致**：一句话描述目标 + 写清楚验收标准，dsh 会自动编排工具链完成
4. **真实速度**：简单任务秒级、复杂多步任务 1-5 分钟（V4-Flash + high 档实测）
5. **提示词黄金法则**：告诉 dsh"完成的标准是什么"（如"运行验证通过"），比描述过程更有效

<details><summary>本章导航</summary>
- [5.1 场景总览](#51-场景总览)
- [5.1.1 高缓存命中率：dsh 的成本秘密武器](#511-高缓存命中率dsh-的成本秘密武器)
- [5.2 场景一：日常编码（最适合入门的场景）](#52-场景一日常编码最适合入门的场景)
- [5.3 场景二：数据处理与分析](#53-场景二数据处理与分析)
- [5.4 场景三：文档与知识工作](#54-场景三文档与知识工作)
- [5.5 场景四：自动化与运维（headless 是王牌）](#55-场景四自动化与运维headless-是王牌)
- [5.6 场景五：代码理解与重构](#56-场景五代码理解与重构)
- [5.7 让场景落地的三个提示词法则](#57-让场景落地的三个提示词法则)
- [5.8 我的第一个真实任务（15 分钟上手）](#58-我的第一个真实任务15-分钟上手)
- [5.9 行业视角：dsh 在不同领域的打开方式](#59-行业视角dsh-在不同领域的打开方式)
</details>

## 5.1 场景总览

| 场景 | 典型任务 | dsh 的工具 | 实测参考 |
|---|---|---|---|
| **日常编码** | 写函数、修 bug、补测试 | write / read / bash / grep | 5-bug 修复+49 测试：94s |
| **数据处理** | 清洗、分析、可视化、报告 | read / write / bash / python | 数据清洗+可视化：186s |
| **文档知识** | API 文档、教程、总结、翻译 | read / write | API 文档生成：1m04s |
| **自动化运维** | 批量处理、CI 任务、日志分析 | bash / headless | headless 脚本化 |
| **代码理解** | 重构、审查、技术调研 | grep / glob / read / bash | 代码重构：4m37s |

> 所有实测来自白皮书第 10 章真实案例（合成数据），详见 [benchmark](./benchmark.md)。

## 5.1.1 高缓存命中率：dsh 的成本秘密武器

**这是 dsh 生态最被低估的优势**。DeepSeek API 的 **context cache**（提示词缓存）：重复/相似的输入 token 按缓存价计费。实测（真实 dsh 会话统计）**缓存命中率可达 97%**。

**为什么 dsh 缓存命中率特别高**：

| 原因 | 说明 |
|---|---|
| 会话延续 | 同会话多轮对话，系统提示/技能目录/历史重复 → 命中 |
| 稳定的工具 schema | 每步请求携带相同的工具定义 → 命中 |
| Agent 工作负载特性 | 多步工具链反复携带相同上下文 → 命中率天然高 |

**成本影响（98% 缓存折扣）**：

| 计费项 | 未命中价 | 缓存命中价 | 折扣 |
|---|---|---|---|
| 输入（Flash） | $0.14/M | **$0.0028/M** | **98%** |
| 输入（Pro） | $0.435/M | $0.003625/M | 99%+ |

**实际意义**：一个长会话 Agent 任务，绝大部分输入 token 走缓存价——**实测中"50 步工具链任务、2.4M 输入 token"的成本远低于按未命中价计算的预期**。对高频/批量/长会话场景，这是数量级的成本优势。

> 怎么让缓存命中率更高：**保持会话延续**（不要频繁新开会话）、**稳定 prompt 前缀**（系统提示/技能目录不要反复变化）、批量任务放同一会话/同前缀。

## 5.2 场景一：日常编码（最适合入门的场景）

**典型任务**：
- 按需求写一个新函数/模块
- 修复 bug（定位 → 修改 → 验证）
- 补单元测试

**任务示例**（headless 一键跑）：

```bash
dsh --profile headless "审查 buggy_calculator.py：找出所有 bug 修复，写完整测试，运行验证全部通过"
# 实测：5 个 bug 全修复 + 49 个测试通过（94s）
```

**为什么 dsh 适合**：编码是工具链最完整的场景——读文件、写代码、跑命令、看结果，闭环顺畅。产物（改的文件）会在对话末尾直接可打开。

**提示词技巧**：一定要写"运行验证"——dsh 会照着闭环；只写"帮我修 bug"它会修完就停。

## 5.3 场景二：数据处理与分析

**典型任务**：
- 数据质量检查与清洗
- 统计分析
- 可视化（图表）
- 生成分析报告

**任务示例**：

```bash
dsh --profile headless "分析 sales_data.json 的数据质量（缺失/类型错/重复/异常），写清洗脚本+可视化脚本，运行验证，总结处理方案"
# 实测：52→35 行归零 + 图表 + 权衡说明（186s）
```

**亮点**（实测）：dsh 不仅执行，还会**说明权衡**——"中位数填充会产生尖峰""异常值是否该删取决于业务"——这是 agent 工程层"会思考"的直接证据。

## 5.4 场景三：文档与知识工作

**典型任务**：
- 从代码生成 API 文档
- 把笔记整理成结构化文档
- 总结长文、翻译

**任务示例**：

```bash
dsh --profile headless "为 user_module.py（8 个函数）生成完整 Markdown API 文档：参数表、返回值、异常、示例、边界情况"
# 实测：423 行 ReadTheDocs 风格文档（1m04s），主动识别"文档契约 vs 代码实现"差异
```

**亮点**（实测）：dsh 会**防御式写作**——标注调用陷阱（负数 limit 行为、空参数行为）、发现文档声明与实现不符的地方如实说明。

## 5.5 场景四：自动化与运维（headless 是王牌）

**典型任务**：
- 每天定时跑数据任务（日报、监控摘要）
- 批量文件处理（重命名、格式转换）
- CI 里的自动化检查

**任务示例**（脚本化）：

```bash
# cron 每天 8 点生成日报
dsh --profile headless "读取工作区 git log，生成中文日报" > daily-report.md

# 批处理：目录里所有 .txt 转 .md
dsh --profile headless "把 docs/ 下所有 .txt 转成 .md（保留结构）"
```

**为什么 headless 是王牌**：进程级工具（bash/文件/搜索）全可用 + 非零退出码即失败 + 输出可管道——**它是"能写进 CI 的 Agent"**。

## 5.6 场景五：代码理解与重构

**典型任务**：
- 把过程式代码重构为 OOP
- 全仓库代码审查
- 技术调研（"这个模块怎么工作的"）

**任务示例**：

```bash
dsh --profile headless "把 legacy_orders.py 重构为面向对象+职责分离，保持行为一致，写测试验证重构前后输出相同"
# 实测：17/17 测试通过，含脚本级产物对比（4m37s）
```

**亮点**（实测）：dsh 的工程意识——识别重复代码合并单一入口、保持向后兼容、**发现沙箱下 tempfile 权限问题主动换方案**。

## 5.7 让场景落地的三个提示词法则

1. **写验收标准，不写过程**：`"运行验证通过"` > `"写一个脚本"`——dsh 自己会编排步骤
2. **给上下文**：一句话说清背景（文件在哪、数据长什么样、目标读者是谁）
3. **一次一个任务**：复杂目标拆成多轮（每轮一个小闭环），比一次给巨型任务更可靠

## 5.8 我的第一个真实任务（15 分钟上手）

1. 建一个测试目录，放一个你手头的小文件（代码/数据/笔记）
2. 跑：`dsh --profile headless "总结这个文件，指出 3 个可改进点"`
3. 跑：`dsh --profile headless "给这个文件写一个测试/生成文档"`
4. 对比输出，感受 dsh 的"完成度"——它是不是只给了个大概？验收标准写清楚了吗？

---

## 动手练习

1. **场景识别**：给你手头的 3 个日常任务，判断各属于哪个场景（编码/数据/文档/自动化/理解）
2. **提示词对比**：对同一任务写两个版本提示词——一个"描述过程"、一个"写验收标准"，跑一遍对比结果
3. **headless 脚本化**：把"每日 git 日报"写成一行 cron/bash 命令，验证输出
4. **多步任务**：设计一个跨场景任务（如"读代码 → 生成文档 → 输出报告"），看 dsh 如何编排
5. **思考题**：什么场景 dsh 不适合？（提示：实时交互、需要人工审批的敏感操作）

## 常见疑问（FAQ）

- **Q：dsh 只是编码助手吗？** 不是——工具链（读/写/跑/搜）让它通用，数据处理/文档/自动化都验证过
- **Q：复杂任务会跑多久？** 实测 1-5 分钟（V4-Flash）；要更快可以降推理档（第 6 章）
- **Q：任务失败怎么办？** 看输出里的工具调用轨迹定位；多数是"验收标准不清晰"，重写提示词重跑
- **Q：能自动化运行吗？** 能——headless + 非零退出码 + 管道输出，可进 cron/CI
- **Q：安全吗？** 工具执行有沙箱与审批层；敏感操作建议人工确认（第 8 章安全模型）
- **Q：和直接用 Claude Code 有什么区别？** 同模型下能力接近，但 dsh 可自定义工具链/界面/插件（第 1 章矩阵）

---

**下一章**：[第 6 章：进阶与性能调优](./06-advanced.md)

## 5.9 行业视角：dsh 在不同领域的打开方式

> 同一套工具链，不同行业的用法。以下为通用场景（不含真实业务数据），合规敏感领域（医疗/法律）请务必人工审核。

### 金融与投研
- **任务**：财报摘要、研报要点提取、因子说明文档、投资备忘
- **示例**：`dsh --profile headless "读取这份财务数据，生成含同比/环比变化的摘要报告"`
- **dsh 优势**：数据处理管线顺手 + 高缓存命中（长报告会话便宜）

### 教育与学习
- **任务**：教案生成、题目解析、错题归纳、学习计划
- **示例**：`dsh --profile headless "把这章知识点整理成 10 道自测题（含解析）"`
- **dsh 优势**：文档生成 + 结构化为强项，可批量出题/归纳

### 销售与客服
- **任务**：FAQ 整理、话术生成、客户反馈归类
- **示例**：`dsh --profile headless "把 100 条客户反馈按问题类型归类并给出改进建议"`
- **dsh 优势**：批量文本处理 + 分类归纳

### 运营与内容
- **任务**：周报月报、数据看板说明、内容选题、SEO 摘要
- **示例**：`dsh --profile headless "读取本周数据文件，生成运营周报（含图表代码）"`
- **dsh 优势**：数据 + 文档 + 自动化的组合

### 研究与综述（学术/技术）
- **任务**：论文要点提取、技术调研、文献对比
- **示例**：`dsh --profile headless "对比这 3 篇论文的方法与结论，输出对比表"`
- **dsh 优势**：长文档处理 + 结构化输出（1M 上下文）

### ⚠️ 合规提醒
医疗诊断、法律意见、财务建议等**高风险场景**：dsh 输出需人工审核，不能直接用于决策——工具执行有沙箱，但**内容责任在使用者**。