[!info] related notes

• 相关 MOC: AI MOC, Go MOC, 前端工程化 MOC, Agent MOC, Agent Evals MOC

BodySense 项目 MOC

从零到一搭建一个 AI 体态健康助手的知识地图。

从这里开始

1. BodySense 项目概览 — 项目全貌
2. 多服务架构 — 三服务为什么这样拆
3. L1 · BodySense Diagnosis Agent Architecture — 从 LLM 调用到 Evidence、DecisionAuthority、Replay、Eval/Promotion 的生产 Agent 心智模型
4. L2 · BodySense Treatment Vertical Slice — 只学习 Diagnosis 之外的增量：Proposal/Acceptance/Execution、Temporal Validity、Outcome Feedback
5. L3 · BodySense Consultation Streaming Architecture — StreamEvent Trust Boundary、ActiveTurn、durable recovery、interrupt/resume
6. L4 · BodySense Python Async / RAG Engineering — Event Loop blocking、Async Postgres Pool、Embedding 执行边界、Targeted RAG、Grounding/Faithfulness

当前推荐的差分学习路线

[!important] Knowledge Delta 原则 已经在前一阶段真正掌握的通用概念不重复开课。进入新模块时只问：这个场景新增了什么 domain invariant、authority boundary、runtime state 或 failure mode？

L1 Diagnosis
事实 / 推理 / Evidence / Authority / Durable History / Governance
        ↓ 已掌握，作为通用底座

L2 Treatment
新增：Action lifecycle + temporal authorization + real-world outcome feedback
        ↓

L3 Consultation
新增：Streaming projection + durable event recovery + interrupt/resume
        ↓

L4 Python Async / RAG
新增：Event Loop resource boundary + async DB lifecycle + embedding execution + targeted evidence + grounding

L1 · Diagnosis — 已完成

统一入口：BodySense Diagnosis Agent Architecture。

核心已掌握：

LLM Proposal
→ Runtime Verification
→ Evidence / Policy Facts
→ SafetyEnvelope
→ DecisionAuthority
→ Authorized Result
→ Immutable Analysis / DecisionTrace
→ Replay / Eval / Promotion

L2 · Treatment — 只学习新增内容

统一入口：BodySense Treatment Vertical Slice。

Diagnosis 中已经学过、在 L2 只做映射的内容：

• typed PydanticAI Agent；
• AgentConfiguration / LiteLLM；
• EvidenceGap / EvidenceBudget / EvidenceAttempt；
• Evidence Admissibility；
• deterministic policy / fail closed；
• DecisionTrace / Provenance / Replay；
• Eval / Shadow / Canary / Promotion。

真正新增的 5 个知识点：

1. Proposal、Acceptance 与 Execution Authority — can propose ≠ can accept ≠ has executed
2. Temporal Validity 与 Reauthorization — 合法生成不代表稍后仍合法接受
3. Treatment Aggregate 与 Immutable Revisions — mutable current aggregate + immutable plan history
4. Intervention → Outcome → BodyState Feedback Loop — Action → Observation → State Update → Review
5. Association vs Causation — after ≠ because of

L2 最终闭环：

BodyState / Diagnosis
→ Generate Proposal
→ Generation Authority
→ proposed TreatmentRevision
→ Acceptance Authority
→ accepted Treatment
→ durable Intervention
→ actual Outcome
→ new BodyState revision
→ review current Treatment
→ new revision if needed

L3 · Consultation Streaming — 只学习组合后的 Runtime 增量

统一入口：BodySense Consultation Streaming Architecture。

已有基础页直接复用：

• Web Streams 与增量文本解码
• TypeScript 静态类型与运行时校验
• React useReducer
• React Context 与状态管理边界
• TanStack Query 与 SSE 流式数据集成
• AbortController 与异步取消

真正新增/值得深挖的 4 个节点：

1. StreamEvent Trust Boundary — 网络 JSON 必须 unknown → validate → trusted StreamEvent
2. Active Turn State Machine — 当前流式 turn 的唯一投影、pure reducer、effects 分离
3. Durable SSE Recovery with after_seq — SSE transport 与 durable Event Log 分离，断线后 cursor catch-up
4. Agent Interrupt / Resume Lifecycle — ask_user 是 runtime interrupt，不是普通消息

L3 最终闭环：

Network bytes
→ runtime-validated StreamEvent
→ ActiveTurnReducer
→ ActiveTurnState
→ Streaming UI

             network drop
                  ↓
Durable Runtime Event Log
→ after_seq catch-up
→ same StreamEvent handlers/reducer
→ recovered projection

interaction.required
→ interrupted
→ answer
→ run.resumed
→ continue same run

[!warning] 当前真实实现缺口 packages/contracts 已有完整 StreamEvent 静态 union，但当前 live SSE 和 durable event API 的前端入口仍存在 as StreamEvent 类型断言，尚未形成真正的 runtime validation boundary。L3 笔记将其明确标为待补边界；另外 roadmap 要求理解 cancellation，但当前 Consultation feature 尚未发现完整的显式用户 cancel-run path，因此不要把概念目标误记为已实现能力。

L4 · Python Async / RAG Engineering — 工程执行与证据边界

统一入口：BodySense Python Async / RAG Engineering。

已有通用基础直接复用：

• Python 异步编程；
• asyncio 任务、超时与取消；
• RAG；
• RAG 知识库设计；
• L1 已掌握的 EvidenceGap / EvidenceAttempt / Admissibility / DecisionAuthority。

L4 真正新增/需要工程化掌握的 5 个节点：

1. Event Loop Blocking 边界 — async def ≠ non-blocking，同步 DB 与本地 encode 都可能占住 loop thread
2. KnowledgeLibrary Async Postgres Pool — lifespan-owned pool、短生命周期 connection lease、事务与 pgvector session setup
3. Embedding Async 执行边界 — remote API 用 native async；local transformer 用 bounded executor/semaphore，而不是伪 async
4. Targeted RAG 与 Evidence Provenance — Gap → acquisition → attempt → normalized Evidence → admissibility → resolved/unresolved
5. RAG Grounding / Faithfulness 校验 — 从动作名 substring checker 升级到 material claim grounding：provenance → admissibility → field-level semantic support → optional Judge

L4 最终闭环：

Agent decision needs evidence
        ↓
Typed EvidenceGap
        ↓
Targeted acquisition
        ↓
Async DB / Remote API / Bounded local embedding
        ↓
Normalized Evidence + provenance
        ↓
Admissibility
        ↓
Grounding / Faithfulness
        ↓
Resolved or unresolved Gap
        ↓
SafetyEnvelope / DecisionAuthority

L4 最重要的不等式：

async def
≠ non-blocking execution

await
≠ guaranteed suspension

pool
≠ faster SQL

retrieved evidence
≠ admissible evidence
≠ resolved gap

embedding similarity
≠ semantic support

grounded claim
≠ automatically authorized action

Diagnosis Agent 学习主线

[!important] 当前推荐入口 如果目标是理解 BodySense 这轮“从怎么调用模型，一路走到怎么证明 Agent 有资格上线并安全自动处理 case”的学习内容，先读统一总览，再按下面顺序下钻。

1. Typed Agent 与执行边界

• Diagnosis PydanticAI 执行边界 — constructor DI、Protocol、RunContext、Tool Calling、structured output、run-scoped evidence trail

2. Configuration / Eval / Model Gateway

• Diagnosis 模型治理与 Eval 生产闭环 — Configuration qualification、non-inferiority、Shadow/Canary/Promotion
• Agent Configuration Bundle — 真正的 qualification / promotion 单位
• Agent Model Capability Policy — REQUIRED / PREFERRED / OPTIONAL
• Eval 非劣性门槛 — Challenger 是否没有退化到不可接受
• Agent Configuration Interaction Effect — Model × Prompt 等组合效应
• Model Gateway — provider/retry/fallback 属于基础设施 mechanism

3. EvidenceGap 与受控取证

• Decision-Relevant Evidence Gap — 只为可能改变决策的未知信息继续取证
• Evidence Acquisition Policy — Gap → Channel → Budget → Attempt → Stop
• Agent Evidence Admissibility — retrieved ≠ admissible ≠ resolved

4. Durable Diagnosis Domain

• BodySense Diagnosis 的 Durable Domain Model — immutable Analysis、Candidate vs Hypothesis、Evidence/Gap/Attempt 的 durable 边界

5. Safety 与 Decision Authority

• Agent Safety Envelope — normal AUTO 的已批准运行域
• Deny-Overrides Policy Composition — hard blocker 不能被高 confidence 平均掉
• Agent DecisionAuthority — Proposal → Facts → deterministic policy → Authorized Result
• Fallback、Abstain 与 Escalate — 超出 normal AUTO 后的不同动作语义

6. Audit / Provenance / Replay

• Agent DecisionTrace — 为什么最终允许或阻断某个业务动作
• Configuration Provenance 与 Execution Provenance — intended/approved vs actually observed
• Historical Replay 与 Counterfactual Replay — 历史解释、新配置比较与 Current Re-analysis 的边界

7. Agent 稳定性与生产排障

• Agent Behavioral Contract — 允许 semantic variation，但 hard business invariants 必须稳定
• Agent Failure Attribution — 沿 Input→Reasoning→Evidence→Facts→Authority→Persistence→Delivery 找第一个 contract violation

最终心智模型

LLM Proposal
    ↓
Runtime Verification
    ↓
Evidence / Policy Facts
    ↓
SafetyEnvelope
    ↓
DecisionAuthority
    ↓
Authorized Result
    ↓
Immutable Analysis + DecisionTrace
    ↓
Replay / Eval / Promotion

以及四个循环：

A. Reasoning / Evidence
Reason → Gap → Acquire → Evidence → Reason

B. Authority
Facts → SafetyEnvelope → DecisionPolicy → Authorized Action

C. Longitudinal
BodyState Revision → New Immutable Analysis

D. Governance
Production → Trace/Replay → Eval → New Config → Qualification → Promotion

用项目学习五门语言

按“语言心智 → 典型代码 → 小任务 → 跨端交付”推进：

1. JavaScript 学习路线 — 从事件循环进入流式协议
2. TypeScript 学习路线 — 从 StreamEvent 契约学习联合、泛型与运行时边界
3. React 学习路线 — 从 Active Turn 状态机学习 Reducer、Context 与副作用
4. Go 学习路线 — 从运行时事件持久化学习 context、错误、Mutex 与批处理
5. Python 学习路线 — 从流式路由、Event Loop、DB/Embedding 资源边界学习 Pydantic、异步生成器与资源管理

流式问诊的细节入口：

• Web Streams 与增量文本解码
• NDJSON、SSE 与流式协议边界
• AbortController 与异步取消
• TypeScript 静态类型与运行时校验
• Zod 运行时 Schema 校验
• React useReducer
• React Context 与状态管理边界

第一批 React + TypeScript 教学走廊

先预测代码会怎样运行，再阅读实现；知识笔记负责解释机制，源码负责展示真实约束。

1. packages/contracts/src/stream-events.ts → 泛型、字面量类型、可辨识联合与运行时边界
2. apps/web/src/features/consultation/hooks/useSSEProcessor.ts → JSON.parse、不可信输入与当前类型断言缺口
3. apps/web/src/features/consultation/runtime/activeTurnReducer.ts → Reducer、事件收窄、幂等与失败策略
4. apps/web/src/features/consultation/context/ActiveTurnContext.tsx → 状态/操作 Context 拆分与引用稳定性
5. apps/web/src/components/ui/Button.tsx、Input.tsx → props 继承、ref 与 CVA 变体类型
6. apps/web/src/features/consultation/hooks/useConsultationSessionQuery.ts → useQuery、条件查询与 Suspense 的选型边界

项目设计

• 数据库设计 — ER 图、核心表结构、索引策略
• 认证完整流程 — 注册/登录/刷新/注销/密码重置
• 错误处理策略 — 统一错误模型、LLM 降级、用户友好信息
• API 设计规范 — RESTful、版本管理、分页排序
• 测试策略 — 测试金字塔、单元/集成/E2E、AI 输出测试
• 可观测性设计 — 结构化日志、Prometheus、Grafana、告警
• 性能优化策略 — 前端懒加载、后端缓存、AI 优化
• CI/CD 完整流程 — 代码提交、自动测试、自动部署、回滚

架构与设计

• 多服务架构 — 前端/Go/AI 服务的职责边界与通信
• 多服务 SSE 管道 — 端到端 SSE 透传全链路
• LLM Streaming 协议设计 — Delta / Append / State 三种协议模式、分层架构、工业级事件协议
• 前后端共享类型契约 — API 契约一致性
• Monorepo 工程组织 — pnpm + Nx 任务编排
• 会话与消息流设计 — 懒创建会话、分层 ID、SSE 事件协议、幂等与断线恢复

AI 服务能力

• Diagnosis Agent Architecture — 当前 Diagnosis North-Star
• Treatment Vertical Slice — Action/Acceptance/Outcome 的领域增量
• Consultation Streaming Architecture — 可恢复的流式 Agent runtime
• Python Async / RAG Engineering — Event Loop、DB Pool、Embedding、Targeted Evidence、Grounding
• Diagnosis PydanticAI 执行边界
• Model Gateway — 当前统一逻辑模型/Provider 机制入口
• Function Calling 流式累积 — SSE 中 tool_call 的增量拼接
• 咨询 Agent 工作流设计 — 意图分类→阶段推进→安全检测
• RAG 知识库设计 — pgvector 四层 schema + 向量检索
• 意图感知 RAG 重排 — 按意图 boost 检索结果
• Hashing Embedding 降级 — 零模型离线 embedding
• RAG Grounding / Faithfulness 校验 — 从检索命中升级到 material claim 的可追溯支持判断
• Red Flag 症状检测 — 医疗 AI 的安全底线
• OCR 文字识别管线 — 图片/PDF 文字提取

[!warning] 历史架构笔记 AI Gateway 模型路由器设计 记录的是旧 application-owned AIService → ModelRouter → ProviderAdapter 演进阶段。Diagnosis Agent Platform 完成后，仓库级 LLM 路由已经统一收口到 LiteLLM logical-model gateway；旧 Provider/ModelRouter 栈已退休。阅读该页时应把它当作历史演进证据，而不是当前 North-Star。

Context Engineering

• Context Engineering — 上下文不是聊天记录，而是模型完成任务所需的全部有效信息包
• Context Builder 模式 — 独立的上下文组装模块，产出本轮 LLM 调用所需的完整上下文包
• Context Contract 协议 — Go 与 Python AI Service 之间的上下文传递协议
• 问诊状态 Schema — 结构化状态对象，messages 是证据，state 是工作记忆
• 结构化信息采集 — ask_user_options 模式，比纯文本问答稳定得多
• 上下文窗口预算 — 分层策略：recent + summary + state + knowledge

Go 后端

• Gin HTTP 框架 — 路由分组、中间件、JSON 绑定
• Handler-Service-Repository 分层 — 三层职责与依赖方向
• Go 手动依赖注入 — main.go 组装依赖链
• JWT 认证中间件 — 双 token 策略、签名验证
• 数据库迁移 — 版本化 SQL、可回滚
• Redis 缓存实践 — token 黑名单、速率限制
• SSE 代理模式 — 透传 AI 服务流式响应
• 健康检查端点 — 依赖检查、Docker HEALTHCHECK

React 前端

• Feature-Based 目录结构 — 按功能组织前端代码
• React Router 路由与权限 — ProtectedRoute 路由守卫
• Zustand 全局状态 — 认证状态持久化
• TanStack Query 服务端状态 — API 数据缓存
• 前端 SSE 消费 — fetch + ReadableStream 流式消息
• AI 聊天 UI 设计 — 流式打字机、Markdown、工具调用展示
• SSE 流式 Markdown 渲染 — 流式场景不完整 Markdown 的闪烁/重解析问题、三种渲染方案选型、四层架构分层
• shadcn/ui 组件库 — 源码复制式组件库

部署与 DevOps

• BodySense 云原生实践 MOC — 云原生落地方案与待改进清单
• Docker Compose 开发环境 — 多容器编排
• Docker 多阶段构建 — builder + runtime 分离
• Caddy 反向代理 — 自动 HTTPS
• GitHub Actions CI — 多服务并行 CI
• release-please 自动版本 — Conventional Commits 自动发布
• Watchtower 自动部署 — 镜像更新自动重启

遇到的问题