从一份 JD 逆推出一个工业 Agent(Day 0 – S2 学习记录)
目标岗位:工业 AI Agent 开发(LangChain / Dify / Coze、全栈 POC、端到端交付) 产出:
industry-copilot—— 设备运维 Copilot,从「报警」到「工单闭环」
0. 我是怎么开始的
我把 JD 原文甩给 AI,要求三件事:先逆推落地流程 → 对话选项目 → 事无巨细带我一步步搭。
逆推出的结论是:JD 的三条职责其实等于三份交付物——
| JD 职责 | 交付物 |
|---|---|
| 工业需求转化为 Agent 需求 | 一页需求规格(任务拆解 + 数据契约 + 验收标准 + 哪些不给模型做) |
| 独立搭可演示原型、全栈 | 一个能跑的全栈 demo(后端 Agent + 知识库 + 工具 + 界面) |
| 优化并推动落地 | 一份评测报告 + 一份运维证据(成功率/失败归因/P95/单次成本) |
每一关都要留下一个数字或一张表,这是”像工程师”和”像学生”的分界线。
1. 六轮问答(原始问题 + 我的收获)
Q1:帮我逆推工业 Agent 的落地完整流程,先对话选项目,我要参与全流程、事无巨细、一步步验证,帮我选一个现在很常用的框架
收获
- 落地流程压成 8 个阶段:S0 场景 → S1 需求转化 → S2 数据底座 → S3 架构 → S4 敏捷开发 → S5 评测 → S6 工程化 → S7 交付。
- 最容易跳过、但最能加分的是 S1(需求规格) 和 S5(评测与失败归因)。
- 框架选 LangGraph:显式状态机、checkpointer 断点续跑、interrupt 做人工审核,能画出来给面试官看。LangChain 只当零件库(ChatOpenAI / Tool / Retriever),不套 Chain。
- 项目选 设备运维 Copilot:一题吃满 JD 三大场景(预测性维护 + 工业问答 + 复杂 Agent 工作流),演示效果最好。
- 交付形态选两段式:Streamlit 先出 POC,最后换 React,后端一行不改。
Q2:一件一件来,告诉我该在哪个文件夹里干活,最好在 VS Code 里跑
收获
- 只同步/打开
industry-copilot一个目录;E:\AIprogram底下有 20 多个无关文件,别当工作区。 - 三个 Windows 环境坑一次性解决:
UV_CACHE_DIR指到工作区(沙箱不让写用户目录)、PYTHONUTF8=1(否则中文乱码)、uv 自动选了 Python 3.14,必须钉回 3.12(3.13/3.14 上 chromadb/onnxruntime 轮子还不齐)。 - 解药是
uv.toml里写cache-dir,以后不用再设环境变量。
Q3:契约是什么?在哪个文件、怎么运行?下一步做什么?要注意什么?
收获
- 契约 =
app/schema.py里的DiagnosisCard(Pydantic)。它干的事是把”不可信的字符串”变成”可信的对象”。 - 契约在三个地方出现:定义(schema.py)、给模型的填写说明(prompts.py 的 SYSTEM_JSON)、执行点(
parse_card())。⚠️ 前两者是双写,改 schema 忘了改 prompt 会一直触发修复重试。 - 契约的校验规则本身是第一道防幻觉防线:
evidence不能为空、overall_risk=高时need_human_confirm必须 true。 - 写了
tests/test_contract.py(8 项,不花钱)证明契约真的会拦。
Q4:mock 是什么?怎么运行的?为什么不花钱也有结果?
收获
- mock 不是模型,是一个函数:
_chat_mock()里写死一段诊断文本,直接 return。 - 不花钱是因为根本没发网络请求——
chat()里if provider == "mock"就返回了,永远走不到_chat_deepseek()。 - mock 的三个指纹:
¥0.0000、几十毫秒、每次 token 数完全一样(同一个字符串)。 - 它验的是我的代码,不是模型能力。凡是”模型行为”的结论,mock 一个字都不能提供。
Q5:写 6 个工具 + 手册 + 工具契约;分析工业 Agent 数据物理注入的主要形式和坑;把传数据的链路完整给我
收获
- 6 个工具 = Agent 的”手”:查台账、查时序窗口、查相似工单、查手册、查备件、建工单。
- 四条设计原则:计算归代码、判断归模型;返回结构统一
{ok, data, error:{code,message,hint}};失败不抛异常(抛了模型就没机会换思路);有副作用的工具必须可审计可拦(一律 PENDING_CONFIRM)。 - 工具契约导出实测 836 tokens——工具不能无脑加,每轮对话都要重发。
- 物理注入 6 种形式:阈值越限、线性漂移、指数恶化、周期成分/倍频、冲击/包络、多通道耦合;第 7 种是工业里最常见的间歇性抖动。
- 链路 7 段:现场 → 采集 → 传输 → 存储 → 特征 → 服务 → 消费。关键在”特征→服务”之间会丢掉原始波形和频谱,所以只给 rms 的 Agent 必然漏检润滑类故障。
Q6:把这些整理成一篇简短的技术博客,作为学习记录
→ 就是这篇。
2. 今天真正落地的东西
| 层 | 文件 | 说明 |
|---|---|---|
| 模型层 | app/llm.py |
mock / deepseek 双轨,每次调用都带 token、延迟、成本 |
| 契约层 | app/schema.py |
DiagnosisCard,8 字段 + 6 条业务规则 |
| Prompt | app/prompts.py |
版本化(PROMPT_VERSION),改了就改号 |
| 工具层 | app/tools.py |
6 个工具 + 统一入口 + OpenAI function 导出 |
| 数据 | data/raw/ |
120 设备 / 69,120 行时序 / 500 报警 / 200 工单 / 5 手册 / 20 备件 |
| 脚本 | scripts/00…12 |
冒烟 / 输出策略实验 / 造数 / 造手册 / 工具验收 |
3. 我踩的 5 个坑(这段最值钱)
① uv 自动选了 Python 3.14,还写不进缓存目录
别急着装包,先 uv python list 看看用的谁。钉到 requires-python = ">=3.12,<3.13" + .python-version。
👉 环境的确定性,比版本的新更重要。
② 差点把 mock 的 ¥0.0000 当成实验结果
同样的脚本,mock 下耗时 0ms、成本 ¥0、token 守恒;真模型下 26 秒、2 967 tokens、¥0.024。
👉 看到”好得反常”的数字,先问一句:这是真模型跑的吗?
③ 断言只测”有没有抛异常”,测试就绿着骗我(犯了两次)
- 第一次:4 条 causes 的用例 PASS 了,但打印的理由是
rank 不连续——它本该被”最多 3 条”挡下。 - 第二次:
check_spare_parts("22216")返回 0 条也 PASS 了,因为只断言了”没报错”。 👉 只要断言问的是”有没有异常”而不是”结果对不对”,就一定会绿着错。
④ sparkline 各自归一化,图会骗人 健康设备 ±0.07 的噪声被放大成满屏跳动,看起来比故障设备还严重。 改成所有曲线共用 0~7 mm/s 纵轴后,噪声自然压平。 👉 给客户看的图,纵轴是道德问题,不是审美问题。
⑤ 我预判错了,被数据推翻 我以为”只有 prompt 约束”的 B 模式会挂,结果 DeepSeek 一次通过,和 C 只差 18% 成本。 修正后的结论:对短输出、单轮、听话的模型,prompt 约束就够;C 的价值不是”更省”,而是”更稳”——而”稳”必须用 20~30 条刁难样本证明,不能靠 1 次。 👉 预判可以被推翻,但必须用数据推翻,不能靠感觉。
4. 关键数字(可以直接写进简历)
| 指标 | 自由散文 | 结构化输出 | 改善 |
|---|---|---|---|
| 输出 tokens | 2 967 | 300 | ↓ 9 倍 |
| 单次成本 | ¥0.0240 | ¥0.0028 | ↓ 8.5 倍 |
| 延迟 | 26.2 s | 2.5 s | ↓ 10 倍 |
| 可入库 | ✗ | ✓ | — |
其他:契约自检 8/8、工具验收 18/18、工具契约 836 tokens、报警数据 77 真 / 423 噪 / 156 重复。
5. 下一步
S3:把 6 个工具装进 LangGraph 状态机——planner / tool_executor / reflector / finalize,条件边处理工具失败,checkpointer 支持断点续跑,高风险诊断用 interrupt 挂起等人确认。
跑完之后,输入一句”3 号冲压机振动报警”,Agent 应该自己走完: 查台账 → 查近 2 小时时序 → 判断 1X/2X 比值 → 检索手册阈值 → 查相似工单 → 查备件 → 出诊断单 → 高风险挂起等人确认。
那才是 JD 里”复杂 Agent 工作流”的意思。