一、工作进展

本阶段是项目博客（四）所述里程碑的直接延续，核心任务从「端到端打通」转向「链路可维护与可扩展」。四条分工如下：

后端开发模块对营养域做了一次结构性分层：将原先集中在路由文件中的业务逻辑、聚合计算、候选机制与数据访问拆为独立模块层，路由层退化为薄适配壳；同步补齐身体域的 Insight 生成入口，读取档案、当日记录与近期趋势，拼装预制模板交由大模型输出结构化建议；新增按记录主键的单条精确更新能力，与按日期批量改写并存，明确默认路径为窄语义更新。

前端开发模块将营养页从「列表外壳」彻底重做为六段式仪表盘：每日摄入总览、三大营养素比例、按餐次分组时间线、热量收支环、趋势折线图、营养快评卡片，各自独立组件、独立数据流；身体建议卡片从前端轮换示例改为调用后端真实 Insight 接口；两类 Insight 卡片统一为白底浅色样式，与整体仪表盘视觉一致；排查并修复前端全局超时配置导致的请求误断问题。

Agent 架构模块将父级编排从「单次补全 + 强制工具调用」升级为有界多轮循环：允许同一子域内在上限轮次内迭代——先查询类调用拿到明细列表与主键，再基于返回结构发起精确改写；系统提示词顶部声明多步能力与推理纪律，意图分类器补充域关键词防止跨域误路由。

Prompt 工程模块对三个子 Agent 的提示词进行了一轮大规模扩展：训练子 Agent 补全操作枚举与选型规则，营养子 Agent 加入估算义务与新接口说明，身体子 Agent 填充档案字段解读与记录操作指引；同步为身体域新建 Insight 预制模板，定义评分、摘要与分层要点的结构化输出形态。

二、详细内容

1. 营养域分层：从「路由即逻辑」到模块化

早期营养域的业务规则、聚合计算、候选机制与数据库访问全部集中在路由文件中，行数膨胀后维护成本陡增：改一条聚合逻辑需要在数百行路由代码里定位，新增接口需要理解全部上下文，多人协作时冲突面过大。

本轮将营养域拆为两层：路由层只负责参数提取、鉴权透传与响应封装，退化为薄适配壳；业务层独立为模块，承载记录的增删改查、候选状态机、明细与汇总的聚合刷新、以及跨模块的热量汇总写入。两层之间通过显式函数签名交互，不共享隐式状态。

分层的直接收益是路由文件体积大幅缩减，业务逻辑可独立测试；代价是多了一层调用关系，对于简单 CRUD 接口略显冗余。权衡后认为：营养域的业务复杂度已超过「路由即逻辑」的舒适区，分层是必要的结构投资。

2. 身体建议：从示例池到证据链驱动的 Insight

此前身体页的建议卡片由前端哈希轮换静态示例池，与用户当日体重、体脂、心率以及档案字段无任何耦合。短期能撑演示观感，长期等于透支信任。

本轮改为服务端生成：读取身体档案、当日身体记录（若存在）、以及近若干日历日的记录序列，一并拼装进预制模板，由大模型生成评分、摘要与分层要点数组。模板里写明缺数据时的降级策略——不能捏造未采集字段，档案不完整时仍可基于已有维度给出部分建议。

实现中遇到一个工程坑：模板既要承载占位符替换，又要向模型展示 JSON 示例，示例里的花括号与格式化占位符语法冲突。若不转义，运行时直接把示例字段当成占位变量解析会抛异常。处理方式是把示例花括号加倍转义——这不是模型能力问题，而是文案交付与字符串格式化耦合的典型坑。

3. 单条精确更新：窄语义作为默认路径

饮食明细按行存储，同一自然日内允许多条并存。此前只有「按日期批量改写」的宽语义更新——WHERE 条件为用户 + 日期，会把同日所有行一起改写。这对「用户只想改午餐那一行」的诉求而言，等价于危险默认值。

本轮新增按记录主键的单条 UPDATE，窄语义：只动一行，其余行历史保留不动。两类能力共存，但指南层明确默认心智收敛到后者——用户点名某种食物时，应先列举当日明细拿到主键候选，再发起单行改写。

后端侧在路由层新增独立端点，参数为记录主键与待更新字段的部分字典，不强制传全量字段。数据库层只 SET 非空字段，避免未传字段被意外清空。

4. 前端营养仪表盘：六组件拆分与数据流

营养页从单一大组件重做为六段式仪表盘，每段独立组件、独立数据请求、独立错误边界：

• 每日摄入总览：大块数字锚定当日总量，与目标值对比

• 三大营养素比例：碳水、蛋白质、脂肪的占比条

• 按餐次分组时间线：早餐/午餐/晚餐/加餐分组，每组内食物明细

• 热量收支环：摄入总量与训练消耗估算的差值可视化

• 趋势折线图：区间内明细在浏览器侧按日期聚合，接口面保持少而稳

• 营养快评卡片：手动触发，与对话 Agent 分流，避免每次进页面占用推理配额

趋势数据选在浏览器侧聚合的理由是规则足够直白——按日期字符串分组后对热量与三大营养素分别求和即可，不必为每一种图表组合再分叉一批聚合接口。代价是区间内明细条数很大时响应体积上升，用区间天数上限做护栏。

两类 Insight 卡片（营养快评与身体建议）统一为白底浅色底座，用色相区分品类——营养侧偏琥珀点缀、身体侧偏天蓝点缀。深色渐变卡片在原型阶段有科技感，但与白底浅阴影模块并列时产生频道割裂。

5. 超时策略：三套耗时不能共用一把尺

档案读取常在毫秒至数百毫秒级；Insight 串联推理可能出现数秒甚至更久的尾部延迟；聊天 SSE 在工具调用前后可能出现长时间无可写分包。

此前前端对所有请求套用同一短超时，Insight 被误判成「网络坏了」。排查后定位为环境配置中通用超时值过小。本轮修正为：通用 REST 接口保持常规超时，Insight 调用单独拉长容忍度，SSE 侧单独放宽空闲阈值。代价是真实掉线时用户稍晚才能察觉，后续用心跳或阶段性事件细化。

6. Agent 多轮循环：从「一次性猜完」到「先查后改」

早期路径允许模型在一轮补全里返回多个工具调用，后端顺序执行。隐含假设是「所有调用参数都能在同一轮补全里写完」。这对「用户口述了全部写入字段」成立，对「需要先查列表定位主键」不成立——标识符天然依赖上一轮返回。

本轮把「补全—若有工具则执行—结果写回—再补全」固化成显式迭代，设置最大轮次上限。上限不是为了卡业务，而是为成本、延迟与异常抖动兜底。每一轮仍然只允许当前意图绑定的那一个工具名称，多轮不等于允许多子域串烧。

系统提示词顶部声明多步能力与推理纪律：模型知道自己可以发起多轮调用，但也被约束不能在查询结果非空的前提下重复发起等价查询。意图分类器同步补充域关键词，降低「改热量却被路由到训练域」的概率。

7. 三个子 Agent Prompt 的大规模扩展

本轮对训练、营养、身体三个子 Agent 的提示词进行了总计超过一千行的扩展，是项目至今规模最大的一次 Prompt 迭代。

训练子 Agent：补全了操作枚举（记录维护、当日查询、计划调整、动作库查询等）与选型规则，把「用户可能要做什么」从模糊描述收敛为可判别的动作类型。

营养子 Agent：加入估算义务——四个计量维度必填，用户不说则由模型按常识与默认份量估算，用户说了则以用户为准；同步补充新接口（单条精确更新）的调用说明与决策树。

身体子 Agent：填充档案字段解读与记录操作指引，让模型理解每个身体指标的含义与合理范围。

三个子 Agent 的 Prompt 从「能用」走向「可维护」：规则写成可分节的拼装模板，避免单块超长 Prompt 牵一发而动全身。

三、总结

本阶段在项目层面的关键动作是「结构投资」：把前一阶段打通的链路从「能跑」升级为「可改可扩」。

三条阶段性结论：

结论一：分层是业务复杂度超过阈值后的必然选择，不是过度设计。 营养域从路由即逻辑到模块化，直接收益是可测试性与多人协作的冲突面缩小。

结论二：Prompt 工程的一等公民地位需要用代码管理的方式来维护。 三个子 Agent 提示词总计超千行扩展，分节拼装模板的组织方式决定了后续迭代的边际成本。

结论三：多轮循环是有界成本换来的确定性，但上限轮次与工具绑定规则必须显式声明。 没有约束的多轮会退化为无意义空转，有约束的多轮才能把「先查后改」从投机行为变为可靠链路。

下一阶段的自然延伸包括：为编排链路补齐耗时分布观测与抽样评测集，评估前端聚合在长区间下的体积压力，以及持续打磨子 Agent 输出与工具 Schema 的严格对齐。