一、工作进展

本阶段我围绕 MetalCat 项目的 AI 能力初始化，完成了 LangChain 基础运行链路的搭建，并把它放到项目现有的前后端骨架之间，作为后续 Prompt 工程、输入解析和结构化输出的中间层。按照任务书中对本项目的定位，MetalCat 的核心交互不是传统页面点击，而是“对话即执行”；同时我在团队中的分工是 Prompt 工程，负责为各功能子 Agent 设计执行链路并提升任务拆解准确度，因此本阶段最需要先落地的不是复杂多 Agent 协作，而是一条稳定、可解释、可扩展的 LangChain 调用链。

参考项目任务书可知，系统后续需要承接身体数据看板、训练规划和执行、营养实验室、发现频道四个核心模块，还要支撑意图识别与调度中心、视觉识别链路以及 RAG 自动化管道。这决定了 AI 层不能只停留在“接入一个模型并返回一句回复”的程度，而必须从初始化阶段就开始考虑输出结构、错误回退、模块边界和后续接入方式。

本阶段的主要工作包括以下几项：

1. 明确 LangChain 在项目中的定位，不把它写成独立的聊天 demo，而是作为 MetalCat 智能中枢的执行链基础。
2. 初始化 Python 侧 LangChain 运行环境，确认最小模型调用链路可用。
3. 设计适合健身场景的 Prompt 模板，把训练记录、饮食分析、身体指标查询等场景纳入统一输入约束。
4. 设计结构化输出格式，避免前端和后端直接消费自由文本。
5. 梳理“用户输入 → Prompt 组装 → 模型理解 → 输出解析 → 结果分发准备”的完整处理路径。
6. 明确一期做什么、不做什么，避免在项目启动阶段过早陷入复杂多 Agent 编排。

初始化阶段的内容重点并不在“做出了多少业务功能”，而在于把本模块的角色、分层、技术选型和边界定清楚。Agent 架构模块负责同学已经先把文档驱动与工作流约束固定下来，前端开发模块负责同学则完成了应用壳、路由和全局对话区的初始骨架。这意味着我这一部分最适合补上的空缺，就是 AI 侧的“执行链底座”——既能承接后续业务请求，又不与前端、后端模块职责冲突。

二、详细内容

1. 为什么初始化阶段先写 LangChain，而不是直接写多 Agent

任务书里明确写到了本项目最终希望采用 multi-agent 架构，并通过自然语言驱动身体指标监控、训练规划、视觉营养识别和健身信息流推荐。这个目标没有问题，但从项目初始化的节奏来看，最先需要解决的不是“让多个 Agent 自动协商”，而是“先把一条最小可用的 AI 处理链路跑通”。

如果一开始就把重点放在复杂调度上，会遇到三个问题。

第一，前端和后端都还处在骨架期。前端当前完成的是页面信息架构、布局壳、全局对话区和请求层占位；后端也还处在服务接口和业务边界逐步成形的阶段。这个时候如果 AI 层直接假设所有模块接口已经稳定，就会把尚未确定的协议提前写死，后续返工成本很高。前端初始化博客中已经明确表达了一条原则：不为尚未稳定的协议过度设计实现。这条原则放到 AI 层同样成立。

第二，Prompt 工程的价值并不只是“写几句提示词”。对项目来说，更重要的是把自然语言请求整理成后续模块能够可靠消费的结构。只要这个结构没有固定下来，多 Agent 只是把不稳定性从一个节点扩散到多个节点。

第三，任务书中的验收指标其实已经暗示了 AI 初始化应该优先做的事情，例如意图识别准确率、复合动作指令解析能力、饮食识别结果的可确认与累加、根据用户兴趣标签做语义检索等。这些能力在工程上都依赖一条清晰的输入理解链，而这正是 LangChain 擅长承担的部分。

因此，本阶段的选择是：先用 LangChain 把“理解和组织”这一段做好，再把“自治和协同”放到后续迭代。

2. LangChain 在 MetalCat 中承担什么职责

在很多示例项目里，LangChain 容易被写成“调用大模型的一个壳”。如果按这个方式来做，文章内容会非常薄，因为它只能说明“库装好了，模型能回答问题”。这不符合项目博客的写法，也不符合团队当前的工程推进方式。参考已有博客的写法可以看出，初始化文章更强调角色定位、分层设计与技术权衡，而不是单纯贴出一段 demo。

在 MetalCat 项目中，我把 LangChain 的职责界定为四层。

2.1 自然语言理解层

用户不会严格按照接口字段来输入信息，更可能直接说：

• 今天练了胸，卧推 50kg 做了 4 组
• 中午吃了鸡胸肉和米饭，帮我记一下
• 看看我最近一周体重变化
• 今天摄入还差多少蛋白质

LangChain 在这里首先做的不是生成长篇回复，而是把这类自然语言归一化，判断它属于哪种请求类型，以及其中有哪些关键字段。

2.2 Prompt 编排层

同一个模型，在不同场景下需要不同约束。训练记录强调动作、重量、组数、部位；营养记录强调食物、分量、营养素；身体数据查询强调时间范围和指标类型。

如果把所有场景塞进同一个巨大 Prompt，后期可维护性会很差，也不利于排查错误。因此我在初始化阶段先把场景拆开，让 Prompt 模板先按业务职责分层，再通过 LangChain 统一组织调用。

2.3 结构化输出层

前端开发模块后续需要把 AI 输出结果映射到可视化组件，后端开发模块也需要把请求转换为具体服务调用。它们都不适合直接消费一大段自由文本。

因此初始化阶段就必须约束模型输出，例如固定为：

{
  "intent": "training_record",
  "confidence": 0.94,
  "entities": {
    "muscle_group": "chest",
    "exercise": "bench_press",
    "weight": "50kg",
    "sets": 4
  },
  "response_text": "已记录今天的胸部训练：卧推50kg，4组。",
  "target_module": "training"
}

这个设计的重点不在字段名字本身，而在于从初始化阶段就建立“模型输出是给系统消费的，不只是给人看的”这一原则。

2.4 结果分发准备层

任务书里已经把四个核心业务板块写得很清楚：身体数据看板、训练规划和执行、营养实验室、发现频道。
我在初始化阶段并不负责系统级调度中心本身，而是先把模型输出整理成稳定的结构，让后续系统能够根据结果继续分发处理。
这就意味着 LangChain 在项目中的位置更像“业务前的理解层”和“结果整理层”，而不是业务本身。

3. 为什么选 LangChain，而不是直接手写调用逻辑

这里只谈初始化阶段的权衡，不做过度拔高。

3.1 选择 LangChain 的原因

第一，项目后续场景不是单一问答，而是多个领域场景共享一个全局对话入口。LangChain 在 Prompt 模板、输出解析、Runnable 组合、链式组织上比手写裸调用更适合做中间层。

第二，后续要逐步接入 Parser、Router、Memory、Tool 调用时，LangChain 的抽象比从零重写更平滑。初始化阶段先用到的也许只有 PromptTemplate 和输出解析，但后续继续扩展时不需要推翻现有结构。

第三，团队项目需要协作。若 AI 逻辑全部散落在不同脚本中，后续调试时很难知道“是 Prompt 写错了、解析器坏了，还是路由规则不对”。LangChain 至少能把调用过程拆成更清楚的几个环节，便于定位问题。

3.2 没有选择直接上更重的 Agent 框架

Agent 架构模块负责同学的博客已经强调了文档驱动和流程约束的重要性。在这个背景下，我认为初始化阶段没有必要再引入一个更重、更抽象的 Agent 框架。原因主要有两点：

• 当前最需要解决的是输入理解和输出规范，而不是复杂自治。
• 框架层数越多，前期排查错误的路径越长；当接口和业务边界都还未稳定时，引入过深封装会降低可解释性。

3.3 也没有选择完全手写

完全手写模型调用当然可以做到，但会带来另外两个问题：

• 各个业务场景的 Prompt、解析、异常回退逻辑会快速重复。
• 后续一旦需要把一条链拆分为多个步骤，代码会变得零散。

所以这次不是为了“追新框架”而引入 LangChain，而是因为它在当前阶段刚好够用：抽象程度适中，能支持增长，又不至于把初始化阶段变成框架学习展示。

4. 初始化阶段我实际做了什么

4.1 搭建最小可运行环境

LangChain 初始化的第一步是把 Python 运行环境和基础依赖固定下来。此时目标不是把所有能力都接上，而是先验证“给定固定 Prompt，模型能够按预期返回结构化结果”。

这一步看起来简单，实际很关键。因为如果最开始就直接接多个场景、多个 Prompt 和多个解析器，一旦输出不稳定，很难判断错误来自哪里。

我在这一阶段采用“单链先通”的方式处理：

from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是 MetalCat 项目的 AI 助手，只负责解析用户请求并给出结构化结果。"),
    ("human", "{user_input}")
])

llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0)

chain = prompt | llm
result = chain.invoke({"user_input": "今天练了胸，卧推50kg做了4组"})
print(result)

这一段代码并不复杂，但初始化阶段的意义在于先把链路的“骨架”固定下来，再决定往上挂什么约束。

4.2 设计场景化 Prompt，而不是一个大一统 Prompt

从任务书内容看，MetalCat 至少涉及训练、营养、身体数据、发现频道四类核心业务。它们的语言特点不同，输出目标也不同。

如果把所有场景塞进同一个 Prompt，就会出现这样的问题：

• 模型容易在训练记录场景里输出营养建议。
• 模型容易在身体数据查询场景里生成一大段分析，反而遗漏关键字段。
• 一旦某个场景出错，很难只改这一部分而不影响其他场景。

所以我在初始化阶段先把 Prompt 按场景拆开，只保留一个统一外壳，例如：

SCENE_PROMPTS = {
    "training_record": "识别训练记录请求，提取动作、重量、组数、目标肌群。",
    "nutrition_record": "识别饮食记录请求，提取食物、分量、餐次、营养估计。",
    "body_query": "识别身体数据查询请求，提取指标类型、时间范围、查询目标。",
    "discovery_query": "识别发现频道请求，提取主题、目标、检索倾向。"
}

外壳负责统一输出格式，场景 Prompt 负责约束当前业务。这样做的好处是后续即使对训练场景持续打磨，也不会影响其他模块。

4.3 固定结构化输出，而不是只让模型“回答得像人”

如果把 AI 只看作聊天机器人，模型“说得顺不顺”当然很重要；但如果它是整个产品的自然语言入口，那么更重要的是“输出能不能被系统继续处理”。

因此我在初始化阶段就给输出增加了字段约束：

OUTPUT_SCHEMA = {
    "intent": "请求类型",
    "confidence": "模型对当前识别结果的置信度",
    "entities": "从用户输入中抽取出的关键参数",
    "response_text": "给用户看的自然语言反馈",
    "target_module": "后续应交给哪个业务模块"
}

这样的约束有两个直接收益：

• 前端模块后续可以根据 target_module 决定切到哪个页面或展示哪个面板。
• 后端模块后续可以根据 entities 组装服务请求，不必从自然语言里二次解析。

这一步和项目任务书里“对话即执行”的产品方向是一致的：对话不是终点，而是操作入口。

4.4 增加错误回退思路

初始化阶段我没有追求把每一种输入都识别对，而是先考虑一种更实际的情况：如果字段缺失怎么办。

例如用户只说：

今天练了胸

这句话只能确定它大概率属于训练场景，但动作、重量、组数都没有。

如果模型硬生成完整记录，就会把系统推向错误方向。因此我在 Prompt 设计里要求模型在字段不足时返回追问建议，而不是擅自补全。示意结构如下：

{
  "intent": "training_record",
  "confidence": 0.72,
  "entities": {
    "muscle_group": "chest"
  },
  "response_text": "已识别为训练记录，但还缺少动作、重量或组数信息。",
  "target_module": "training",
  "follow_up_question": "你今天做了哪些胸部动作？每个动作做了几组、多少重量？"
}

这一点看起来只是一个字段设计，但本质上是在初始化阶段就把“错误如何被优雅处理”纳入链路，而不是把所有异常都扔给前端或者后端。

三、总结

本阶段我完成的不是一个独立的聊天功能，而是 MetalCat 项目 AI 层的初始化底座：使用 LangChain 把自然语言理解、Prompt 编排、结构化输出和异常回退整理成一条可解释的处理链。这个工作与任务书中“对话即执行”的产品方向是一致的，也与我在团队中负责 Prompt 工程、优化执行链路和提升任务拆解准确度的职责相对应。

这次初始化里，我做出的几个关键选择如下：

1. 先使用 LangChain 固定单次请求处理链，而不是在项目启动阶段直接追求复杂多 Agent 协作。
2. 先把 Prompt 按业务场景拆分，再统一输出格式，保证后续可维护性。
3. 先约束结构化输出，再打磨自然语言表达，把 AI 结果真正变成系统可消费的数据。
4. 先把文本链路跑通，再为多模态识别、RAG 检索和后续服务接入预留扩展点。

这些选择背后的共同原则是：不在协议尚未稳定时过度设计实现，但要尽早把关键边界固定下来。对项目而言，LangChain 初始化的意义不在于“引入了一个框架”，而在于为后续训练记录、营养分析、身体数据查询和发现频道检索提供了一层稳定的 AI 执行中枢。

---