DeepSeek Harness 数据分析使用手册

1. 它是什么

DeepSeek Harness（下文简称 DSH）是一个以“工作区 + 工具调用”为核心的 AI 编程/分析环境。它不只是聊天，还能：

读取 workspace 中的 CSV、Excel、Python 文件；
运行 Python、shell 命令并返回真实结果；
直接创建、修改、检查文件；
搜索网络资料；
拆分后台子任务、并行执行；
记住一个长期目标并自动继续推进；
在复杂项目上运行由多个子代理组成的 workflow。

对本课程来说，DSH 是“数据分析第一版生成器 + 代码执行器 + 审查助手”，学生仍然是最终负责人。

1.1 Agent 是什么

Agent（智能体）= 大模型 + 工具 + 记忆 + 工作区。普通聊天机器人只能“说”，Agent 还能“做”：它会把你的目标拆成步骤，调用工具读文件、运行命令、修改代码，再把真实结果拿回来继续调整。

flowchart LR
    A[你提出目标] --> B[Agent 制定计划]
    B --> C[Agent 调用工具]
    C --> D[工具返回真实结果]
    D --> E{结果符合目标吗}
    E -- "不符合" --> B
    E -- "符合" --> F[Agent 汇报结果]
    F --> G[你审查并验证]

一句话记住：Agent 是执行者，不是负责人；你是负责人。 Agent 能做什么取决于工具权限和你的确认。

1.2 Web 界面分区

启动后浏览器打开 http://127.0.0.1:3080：

区域	作用
左侧会话栏	新建会话、切换历史会话、显示当前工作区
中部消息区	你与 Agent 的对话和工具执行记录
底部输入框	输入自然语言任务
工具行	显示 Agent 正在读取、编辑、运行什么；点击看详情
右上角状态	当前工作区、模型、安全模式
设置	配置 API Key、模型、工作区

第 01 周课程专门有一节“认识 Agent 与安全规则”，第一次使用前先读它。

1.3 安全纪律

DSH 运行命令前可能请求批准。学生必须看懂命令再同意，看不懂就让 Agent 解释或查看课程说明。
禁止让 DSH 执行 rm -rf、删除他人文件、上传密钥、访问未授权网站。
原始数据目录只读，所有输出写进 projects/ 或 output/。
API Key 只保存在 DSH 设置里，不写进代码、聊天内容或 GitHub。
AI 生成的每个结论都必须能在数据或代码里被指出：哪张表、哪个字段、什么计算、样本量多少。
课堂评分同时看过程和结果：报错记录、追问记录、验证说明比“AI 一次性生成的完美报告”更重要。

2. 启动与工作区

在课程环境里，Web GUI 地址通常是：

http://127.0.0.1:3080

命令行方式：

dsh web

启动后把“当前工作目录”设置为本仓库根目录，例如 /home/zhong/Documents/python-data-analysis。这样 DSH 可以直接看到 data/、01-*.md 到 08-*.md、scripts/ 和你的项目文件夹。

建议每个学生项目单独建一个目录：

projects/
  <学生姓名或学号>/
    raw/         原始数据（只读）
    scripts/     清洗、分析、建模代码
    output/      图表、CSV、HTML 报告
    report.md    最终结论

3. 常用工具与什么时候用

DSH 工具	在数据分析课中的用途
对话	描述任务、给上下文、追问结果
`read` / `glob` / `grep`	先读文件再下结论；搜索代码和数据文件
`bash`	运行 `python script.py`、`pytest`、`pip install`
`edit` / `write`	修改代码、保存 CSV/HTML 报告
`web_search`	查数据集来源、字段口径、最新文档
`/plan`	复杂任务先探索、先写完整方案，经确认再执行
`goal`	8 周结课项目等需要多轮推进的任务
`subagent`	把独立任务分给后台子代理，例如“审计数据”和“审查代码”并行
`workflow`	结课项目把多个子代理编排成阶段化流水线
`ask_user_question`	遇到口径不确定时，DSH 反过来向你确认

4. 数据分析的标准协作流程

1. 放好数据
   → 把原始 CSV/Excel 放入项目目录，不修改原始文件。

2. 先审计，不急着建模
   → 让 DSH 输出 shape、dtypes、缺失、重复、唯一值、可疑字段。

3. 定义问题与验收标准
   → 例如：平均价格最高的房型、行政区价格差异、价格预测误差要如何评价。

4. 要求最小可运行版本
   → “先给我能运行的 10 行代码，不要完整报告。”

5. 运行并反馈真实结果
   → 把报错、图表异常、与业务直觉不符的地方原样告诉 DSH。

6. 追问与钻取
   → 不要停在第一张图；问“哪个分组贡献了这个现象？”

7. 显式检查风险
   → 让 DSH 检查口径、缺失处理、目标泄漏、样本量、因果误读。

8. 沉淀为可复用文件
   → 保存 `clean.py`、`eda.py`、`report.md`，下次可以直接复用。

5. 第一个标准提示词

复制下面的内容到 DSH：

请把 `data/04-cleaning/telco_customer_churn.csv` 作为本次任务的数据，不要修改原文件。
任务：
1. 先读取文件，输出行数、列名、每列缺失数、重复行数、dtypes；
2. 列出你认为最需要优先处理的 3 个数据质量问题，每个问题给出判断依据；
3. 写一段 pandas 清洗代码，保存在 `projects/example/scripts/clean_telco.py`；
4. 运行清洗代码，输出清洗前后行数和缺失数对比。
约束：只用 pandas；代码要可读；每个结论都要能从我给你的数据中找到证据。

6. plan mode 怎么用

当任务超过“读一个文件”时，先让 DSH 进入 plan mode：

/plan 我要做一个电信客户流失迷你报告，先不要改文件，只做调查和方案。

DSH 会先探索数据、列出方案，并用 exit_plan_mode 请求确认。确认后再开始写代码。适合 Week 6 的迷你项目和 Week 8 的结课项目。

7. goal 怎么用

当你想让 DSH 跨多轮持续完成一个项目时：

请创建一个目标：
“完成《电信客户流失迷你报告》”
验收标准：
1. output/clean_telco.csv 存在；
2. output/dashboard.png 存在；
3. report.md 里有 3 个有数据依据的结论；
4. 每步都写明数据来源和局限。
请持续推进，直到目标完成或你遇到真正无法解决的问题。

DSH 会记录目标状态，完成一轮后自动继续。暂停、恢复、标记完成都可以在会话里直接要求。

8. subagent 怎么用

适合两个互不依赖的任务并行：

请同时启动两个后台子代理：
子代理 A：审计 `data/04-cleaning/telco_customer_churn.csv`，输出 `projects/example/audit.md`；
子代理 B：审查 `projects/example/scripts/clean_telco.py`，找出潜在 bug 和数据风险；
两个子代理都不要修改原始数据，完成后把结论汇总给我。

注意：子代理适合“独立、边界清楚”的任务。如果任务之间要反复同步口径，一开始就用子代理会让上下文管理更复杂。

9. workflow 怎么用

结课项目可以写成阶段化工作流，例如：数据审计 → EDA 与可视化 → 报告撰写。完整示例见 dsh/final-project-workflow.js。

DSH 的 workflow 会按脚本启动多个子代理，适合“规模明确、子任务可并行/可串联”的项目。使用规则：workflow 只用于 Week 8 或课程明确允许的练习，避免学生跳过验证。