第 8 章 实操二 · 诉求智能分类器（场景 A）¶
本章定位： 实操单元 · 角色 = Delta · Prototype 阶段 · 模式 = AI 施工（opencode + gstack）· 场景 A——Delta 侧第一个施工实操（坡度第一级：一次 LLM 调用），教学点是"怎么让 AI 替你跑流程"。
前置： 实操一产出的《解决方案框架》场景 A；启动提示词、gstack 与工程纪律。
实验手册： 启动提示词参考答案（含 25 条测试样本）、gstack 安装速查、驱动指令完整写法、灵魂追问与讲师要点见《实验手册》
labs/lab2-classifier.md——本实操正文只保留"方法与验收"。
本章学习目标：
- 体验 Delta 施工：把场景 A 的方案翻译成一段高质量启动提示词（7 项信息块 + 流程纪律）；
- 让 Agent 按 gstack 八环节自动跑，学员在每个 checkpoint 把关/拍板；
- 验证"一次 LLM 调用做文本分类"是最简单的适用路径；
- 产出可运行系统 + 完整交付件，并写"演示级验收声明"、向坐席演示"转人工兜底"。
💡 一句话记住本实操： Echo（上轮）人脑挖需求→方案框架；Delta（本轮）把它翻译成启动提示词→Agent 跑 8 环节→你在 checkpoint 把关。 你不再手把手教 AI 写每行代码，而是把"客户需求"翻译成"AI 的语言"，并在关键节点做果断决策。
学习目标追踪（目标 → 活动 → 证据 → 验收）：
| 学习目标 | 对应活动 | 主要证据 | 对应 DoD |
|---|---|---|---|
| 体验 Delta 施工：方案框架→启动提示词 | 环节 1 写启动提示词 | 01-office-hours.md | 高质量启动提示词 |
| Agent 按 gstack 跑、checkpoint 把关 | 环节 2 注入并跟进八环节 | SPEC-决策记录.md | 八环节有产出、拍板有记录 |
| 验证"一次 LLM 调用"是最简路径 | 本实操全程 | SPEC 选型理由 | 分类系统可运行、验收达标 |
| 交付闭环 + 演示级验收声明 | 环节 3 验收与收尾 | qa-report.md、验收声明 | 向小王演示成功 |
| 交接经验给下一实操 | 环节 4 复盘沉淀 | retro.md + AGENTS.md 建议 | 交接行动项 |
8.1 知识背景¶
这一轮的方法定位： - 四层级金字塔：本实操落在第 1 层——提示词工程。一次 LLM 调用 + 一段好提示词就够，不需要 RAG（要检索）、不需要 Agent（要多步决策）。 - 选型三问：数据能否出域（教学数据先走 API、不强上本地）→ 能出域；选哪个档位（任务复杂度：模式匹配 → 分类，用第 1 层提示词；部署约束：单点简单）——共同指向"文本分类"。 - "从最简单开始"：能做分类就不上 RAG/Agent，用最低复杂度交付客户需要的价值。 - 低成本验证：分类是坡度第一级，先证明"AI 方案可行"、跑通"描述意图→AI 执行→人把关"闭环，再逐级升级。 - 数据不出域：本实操教学用 API；若客户数据不能出域，方案应切到本地模型/私有化，本实操的提示词/逻辑不变。
8.2 任务书¶
打开你组的《解决方案框架》，找到场景 A："诉求智能分类——把市民诉求自动分到对应委办局"。这轮就是照着它施工。
技术方案（已在实操一定）： 文本分类（不是 RAG、不是 Agent）——输入一句诉求、输出类别，一次调用即可。技术栈：opencode + gstack + DeepSeek + Streamlit。 验收口径（已在实操一定）： 自信区准确率 ≥85%，转人工比例 ≤30%（转人工不算错）。
最小工具契约（供后续复用）： 本实操产出的分类能力，后续会被封装成
classify_request工具——输入：诉求全文；输出：类别 + 置信度 + 是否建议转人工。实操四的路由工作流与 实操四B 会把它当作"工具"（可选辅助）而不是必经步骤来调用。迁移问题：实操四B 中，什么情况下该调用它、什么情况下该跳过它——这就是"分类是不是必经第一步"的 FDE 判断。做到"输入—输出契约清晰"，分类器才能真正成为可回注能力（呼应第 3 章能力回注"识别 → 抽象"）。
8.3 课前准备¶
- opencode（或其他 AI Coding 工具）已安装并启动
- 已通读《解决方案框架》场景 A 部分
- DeepSeek 官方 API key 已配置（
DEEPSEEK_API_KEY） - Python 3.11+
- 创建本实操目录
实操二-诉求分类/ - 安装 gstack（让 Agent 自装或手动克隆，命令见《实验手册》
labs/lab2-classifier.md附录 A）
8.4 演练流程¶
8.4.1 环节 1 · 写启动提示词¶
这不是让 AI 干的活，是你（Delta）的活。 你要把方案框架翻译成一段能让 Agent 开跑的 office-hours 启动信息。写得好不好，直接决定 AI 能不能按标准流程跑对。
Step 1：理清要交给 Agent 的 7 项信息（对照"7 项信息块"，从方案框架摘出场景 A 结论）：
| # | 信息块 | 从方案框架哪里找 | 本场景内容 |
|---|---|---|---|
| 1 | 背景与角色 | 你是谁、在给谁做 | "我是 FDE 团队的 Delta，为西岭市民服务平台施工场景 A" |
| 2 | 要做什么 | 场景 A 定义 | "市民诉求五分类系统：输入一句诉求，输出住建/人社/市监/城管/其他" |
| 3 | 输入输出 | 场景 A"解决什么" | "输入一句诉求文本，输出类别" |
| 4 | 技术选型（含理由） | 场景 A 选型 | "已选型文本分类，不用 RAG/Agent，一次调用即可" |
| 5 | 数据现状 + 测试集 | 场景 A 数据风险 | "无历史标注数据→走大模型零样本分类；测试集见后，写入 tests/test_cases.csv" |
| 6 | 验收口径 | 场景 A 成功衡量 | "自信区准确率 ≥85%，转人工 ≤30%（转人工不算错）" |
| 7 | 约束与边界 | 场景 A 风险与应对 | "API key 走环境变量不硬编码；不做 40+ 部门细分类" |
第 5、6 项最容易漏、写不好 Agent 会卡住或走错路线： - 数据现状：不写"没有历史标注数据"，Agent 可能默认走传统机器学习（TF-IDF+分类器要上千条标注）——那是死路。必须写"→ 走大模型零样本分类"。 - 验收口径：不写"转人工不算错"，Agent 可能把"转人工的样本算成错"——与"拿不准转人工"的设计自相矛盾。
Step 2：组装启动提示词，附上测试数据（25 条测试样本与启动提示词参考答案见《实验手册》labs/lab2-classifier.md 附录 D）。启动信息里写明："请把这些测试数据集写入 tests/test_cases.csv（含表头 id,text,label），施工时用它作为测试集，数据不得自行改动或重新生成。"
Step 3：用 7 个自查问题审查你自己的启动提示词（先自己写，别翻参考答案）：
| 自查问题 | 为什么问这个 |
|---|---|
| 1. 换一个完全不了解项目的人读，他能知道我在为谁、做什么吗？ | 缺背景，Agent 脑补客户场景 |
| 2. 他能知道输入/输出是什么吗？ | 缺 I/O，Agent 发明错误接口 |
| 3. 他能知道"为什么选文本分类不是 RAG/Agent"吗？ | 缺选型理由，Agent 又问你要不要用 RAG |
| 4. 他能知道数据什么情况（有没有标注、测试集在哪）吗？ | 缺数据现状，Agent 走传统 ML 死路 |
| 5. 他能知道"做出来怎么算成功"吗？ | 缺验收口径，Agent 自己发明验收 |
| 6. 他能知道有什么红线（不做的事）吗？ | 缺约束，Agent 自由发挥 |
| 7. 他能知道"按什么流程跑、产出什么"吗？ | 缺流程要求，Agent 不走 gstack |
某一条答不上来，就回到《解决方案框架》去查——你写不出某一项，往往不是"不会写"，而是"方案框架那部分还没吃透"。
8.4.2 环节 2 · 注入并跟进八环节¶
注入（不要直接丢一段话，要明确"走什么流程"）： 把启动提示词作为 /office-hours 输入，并附上"驱动指令"把流程纪律焊进去（完整写法见《实验手册》labs/lab2-classifier.md 环节 2）。核心 5 条：1）严格按 gstack 8 环节不跳步不打乱；2）每环节产出文件落盘；3）禁止全自动：走完一环停下汇报、获你许可才能流转；4）拍板点列选项列利弊，等你选；5）现在从 office-hours 开始。
跟进八环节，你的把关点：
| 环节 | Agent 会做什么 | 你的 checkpoint（必须把关） |
|---|---|---|
| office-hours | 追问数据、口径、兜底 | 回答；确认"值得做" |
| spec | 死磕 No-Go、数据模型、验收口径 | 审查 No-Go 具体吗；验收口径进 SPEC 了吗 |
| autoplan | 暴露两可决策等你拍板 | 真的拍板（门槛/兜底/UI），写回 SPEC |
| build | 按 SPEC 实现；先落盘 test_cases.csv 再施工 | 抽查没偏离 No-Go；确认测试集来自启动提示词、非 Agent 自编 |
| review | 两遍检查，P0–P3 分级 | 修 P0/P1；API key 没硬编码；.env 解析有 try/except 兜底；模型缺字段安全降级为"转人工" |
| qa | 真实浏览器跑核心流程 + 边界输入 | 五类都测；空文本/超长/口语/对抗；准确率达标 |
| ship | 版本+CHANGELOG+README+commit | 确认 .env 未入库 |
| retro | 复盘四点 | 摩擦写具体；有行动项 |
关键决策点（Agent 停下时你要拍板）：
- 验收口径：项目已定"自信区 ≥85% + 转人工 ≤30%"——别被改；
- 准确率门槛：快赢定位，85% 即可；
- 兜底策略：拿不准归"转人工"（不是归"其他"）；
- UI 取舍：面板阈值滑块按你的判断，但别卡在自动化测滑块上；
- No-Go：AI 想做任何"spec 明确不做"的事，拒绝。
自查追问： Agent 在 autoplan 停下问"准确率门槛定多少"——你不能说"你看着办"。为什么？因为 85% 够不够是业务决策（坐席能不能接受这个误分率），AI 不知道，只有你结合实操一的方案框架知道。决策权在人的原因，就在于人掌握 AI 没有的业务上下文。
8.4.3 环节 3 · 验收与收尾¶
Step 1 核对交付物：
实操二-诉求分类/
├── 01-office-hours.md
├── SPEC.md # 含失败模式 + No-Go + 数据模型 + 验收口径
├── SPEC-决策记录.md # autoplan 拍板记录
├── src/ # prompt / classify / evaluate / provider 等
├── streamlit_app.py # Web 验证面板
├── tests/test_cases.csv # ~25 条标注样本（每类≥5条）
├── review.md # 两遍审查 + P0-P3
├── qa-report.md # 测试报告（含边界输入）
├── VERSION / CHANGELOG.md / README.md
└── retro.md # 复盘
Step 2 模拟向坐席组长小王演示：
- 用她听得懂的话讲（别说"零样本分类"）；
- 演示"拿不准的转人工"这个兜底——"AI 分不准的会留给你判断，你不是被替代，是变成审核员"；
- 让她看到"错分会减少"。
自查追问： 向小王演示时，为什么"转人工兜底"是最好的切入点？——因为这是她最关心的"会不会被替代"的答案。方案设计时留的"转人工"，不只是技术兜底，更是给一线坐席的"角色定位"。
Step 3 写"演示级验收声明"（DoD）： 在 qa-report 或 retro 里写一句：
"本项目使用约 25 条测试样本，属演示级验收——结论仅证明方案在给定样本上可行，不宣称系统已达到生产可用。"
自查追问： 为什么必须写这句？——FDE 的第一戒律是不能夸大交付物。 25 条样本全对，不代表 1.2 万条真实诉求全对。你敢把"准确率 100%"写成交付报告吗？写了，就是埋雷。
8.4.4 环节 4 · 复盘沉淀¶
- 看 Agent 的 retro 产出（做得好/摩擦/未覆盖/行动项）。
- 手动追加两条对下一轮（场景 B RAG）有用的：
- 让 Agent 生成 AGENTS.md（项目硬约束、目录地图、验收命令、工具坑）——实操三开新会话时，这份文件让 AI 直接继承上下文；
- 写改进行动项交接："下一轮（场景 B RAG）开工前，我要先看这条经验：____"
衔接下一实操： 实操三开工时，新会话读实操二的 AGENTS.md + retro.md，就能继承"这个项目怎么跑、有哪些坑"——这就是 FDE 团队的经验回注（碎石路→铺装公路的微缩版）。
8.5 产出物清单与验收标准（DoD）¶
交付物： 见环节 3 Step 1 文件树（SPEC / 代码 / tests / review / qa-report / 版本 / retro）。
验收标准（DoD）：
- gstack 已安装；写了高质量 office-hours 启动提示词（含数据现状 + 验收口径）
- Agent 按 gstack 八环节跑完，每环节有产出文件
- 每次拍板都真的做了决策（不是"你看着办"）
- 验收口径写进 SPEC：自信区 ≥85% + 转人工 ≤30%
- 分类系统可运行、验收达标；测试样本每类 ≥5 条；测试集来自启动提示词、未自行改动
- .env 未入库，P0/P1 已修复
- 向小王演示成功（讲了"转人工"= 角色升级）
- 写了"演示级验收声明"
- retro.md 追加了 AGENTS.md 建议 + 交接行动项
（gstack 安装速查、启动提示词参考答案与 25 条测试样本、驱动指令全文、灵魂追问汇总见《实验手册》
labs/lab2-classifier.md附录。）
8.6 Echo Prototype 检查单¶
本章不是 Delta 单线活动：Prototype 结束时，Echo 至少完成一次检查（对照实操一的方案框架），产出可归因、可评分的个人记录。Delta 仍是施工主责——本检查单不把技术实操改成业务讨论课。
Echo 至少完成：
- 错分代价分级（每类分错分别是什么后果）；
- 置信度阈值与"转人工"策略确认（是谁拍板、依据什么）；
- 人工处理容量检查（转人工的量，坐席接得住吗）；
- 用户演示反馈（向小王演示后的反馈记录）；
- 是否满足原始业务需求的判断。
通用检查单（每条填一行）：
| 原需求 | 当前功能 | 证据 | 用户反馈 | 未满足项 | 阈值是否调整 | 下一步判断 |
|---|---|---|---|---|---|---|
| 场景 A 验收口径 | 分类 + 转人工兜底 | qa-report.md | 演示反馈 | 待填 | 是否调整及原因 | Go / 继续 / 回炉 |
反模式与红线¶
- 启动提示词没写"数据现状/验收口径"。 Agent 会走传统 ML 死路，或自己发明验收。
- 直接丢一段话给 Agent 而不指定流程。 Agent 不理解"你要它按什么纪律走"，会一口气全跑完，让你失去所有把关机会。
- 对拍板点说"你看着办"。 决策权必须在你（你掌握业务上下文）。
- 夸大小样本成果。 25 条全对 ≠ 真实可生产——必须写"演示级验收声明"。
- 向小王只讲技术、不展示"转人工=角色升级"。那会加剧她对被替代的恐惧，触发"业务不配合"风险。
🔺 技术侧红线首次闭环：本章你在 SPEC 里写死"转人工不算错"——这是"人做判断，AI 负责执行"在自动化边界的第一个落点，也是给一线坐席的"角色定位"（呼应第 4 章）。
本章小结¶
- Delta 施工第一步：把方案框架翻译成启动提示词（7 项信息块 + 附测试集 + 驱动指令）。
- 让 Agent 跑 gstack 八环节，你在每个 checkpoint 把关、拍板。
- 一次 LLM 调用即可做文本分类——"从最简单开始"。
- 交付闭环：可运行系统 + 完整交付件 + 演示级验收声明 + 向小王演示"角色升级"。
- 交接：生成 AGENTS.md + 改进行动项，供下一实操继承。
- 本体贡献：为"市民诉求"补充类别、置信度与人工兜底属性（业务本体的输入）。
动手自检：
- 我能独立写出含 7 项信息块 + 测试落盘指令 + 流程纪律的启动提示词吗？
- 我能说清"为什么这次是分类、不是 RAG/Agent"吗？
- 我能说清"为什么不能对拍板点说'你看着办'"吗？
- 我能说清"为什么要写演示级验收声明"吗？
练习与思考¶
- 基础： 默写 7 项信息块；说出"防 Agent 走死路"的两处关键写法（零样本、转人工不算错）。
- 进阶： 对照《实验手册》
labs/lab2-classifier.md附录 D 参考答案审查你的启动提示词，列出你漏了/多写了什么，说明各是什么类型的理解。 - 挑战（迁移练习）： 为分类系统加一个"provider 抽象"（用环境变量在 DeepSeek/硅基流动/GLM 间切换），验证"方案可替换"。
延伸阅读¶
- 见 FDE-101 https://www.cloudzun.com/fde-course/（第 16 章 AI FDE 落地：Delta 技术与场景）——AI 写码提速、代码审查纪律。
- gstack：
github.com/garrytan/gstack（八环节工作流）。 - opencode：AI Coding Agent（训练营演示同款）。
- 实验手册： 本实操测试集、启动提示词参考答案、gstack 安装速查见《实验手册》
labs/lab2-classifier.md（与训练营"实操二"同源）。 - 下一章： RAG 方法 · 答案可追溯（对比：为什么场景 B 用 RAG 而非分类）。