AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/00-系统设计/IIT Manager Agent 架构决策白皮书：极简主义的胜利.md

IIT Manager Agent 架构决策白皮书：极简主义的胜利

文档版本： V1.0

日期： 2026-02-03

面向对象： 开发团队、架构师、项目相关人员

核心议题： 为什么我们放弃了 MCP 和 Skills，选择了 Postgres + Service Class？

1. 我们的现状与挑战 (Context)

在做出任何架构决策之前，必须诚实地面对我们当前的约束条件。

• 团队规模：2 人（精英小队，但人力极其有限）。
• 技术栈：Node.js (Fastify) + PostgreSQL (Prisma) + Postgres-Only (pg-boss)。
• 业务场景：
  • 医疗垂直领域：对数据的准确性、安全性、合规性要求极高（GCP/FDA）。
  • 高并发写入：未来 100+ 项目，47 家中心同时录入 REDCap。
  • 实时响应：PI 在企业微信提问，期望秒级回复。
• 核心痛点：既要应对复杂的业务逻辑（不同项目的入排标准千差万别），又要保证系统的绝对稳定（医疗数据不能错），还要在有限的人力下快速交付。

2. 为什么我们放弃了 "Skills" 和 "MCP Server"？

这两个概念在 AI Agent 领域非常火，但经过深度评估，对于现阶段的我们来说，它们是**“屠龙之术”**。

2.1 放弃 "Skills" (作为独立框架)

通常所说的 Skills 往往指代复杂的 Agent 编排框架（如 LangChain 中的 Tools/Skills 概念），或者需要专门的解析器来处理的复杂 DSL（领域特定语言）。

• 问题所在：
  • 学习成本高：团队需要学习一套新的框架或语法。
  • 调试困难：一旦 Agent 不按套路出牌，很难追踪是 Prompt 写错了，还是框架解析错了。
  • 过度设计：对于绝大多数医疗质控逻辑（如 age > 18），用自然语言让 LLM 去猜，不如直接写代码判断来得准确、高效、省钱。
• 我们的替代方案：Postgres JSON 配置。
  • 我们将“技能”降维为数据。
  • hard_rules：用 JSON Logic 描述死规则，由 CPU 执行，100% 准确。
  • soft_instructions：用一段 Prompt 描述软逻辑，由 LLM 执行。
  • 本质：我们没有抛弃 Skills 的理念（将逻辑配置化），我们抛弃的是 Skills 的复杂实现。

2.2 放弃 "MCP Server" (Model Context Protocol)

MCP 是 Anthropic 推出的一种标准协议，用于连接 AI 和数据源。

• 问题所在：
  • 架构复杂度爆炸：引入 MCP 意味着我们需要维护独立的 Server 进程、处理进程间通信 (IPC/RPC)、处理网络延迟和断连。
  • 运维负担：对于 2 人团队，多维护一个服务就是多一份心智负担。
  • 牛刀杀鸡：我们的 Agent 和 REDCap Adapter 都在同一个 Node.js 进程里，直接调用函数只要几纳秒；如果走 MCP 协议，需要序列化->发送->接收->反序列化，性能损耗巨大且毫无必要。
• 我们的替代方案：Service Class (伪 MCP)。
  • 我们在代码层面定义一个统一的 ToolsService 类。
  • 它向外暴露标准的接口（就像 MCP 一样），但内部直接调用函数。
  • 本质：我们保留了 MCP 的接口思想（解耦、标准化），抛弃了 MCP 的通信协议。

3. 我们的架构：极简主义的工程实践

我们将这套架构命名为 "Postgres-Only + Service-First + SOP State Machine"。

3.1 架构全景图

graph TD
subgraph "核心优势：全在内存里，全在库里"
DB[(Postgres DB)]
NodeJS[Node.js 后端服务]

    DB \--\>|1. 加载配置 (Skills)| NodeJS  
      
    subgraph "Node.js 内部逻辑"  
        Engine\[QcEngineService\]  
        Engine \--\>|2. 执行| HardRule\[Engine A (CPU)\]  
        Engine \--\>|3. 思考| LLM\[Engine B (AI)\]  
          
        LLM \--\>|4. 调用| Tools\[ToolsService\]  
        HardRule \--\>|4. 调用| Tools  
          
        Tools \--\>|5. 执行| Adapter\[RedcapAdapter\]  
    end  
      
    Adapter \--\>|6. 请求| External((REDCap))  
end

3.2 核心组件解析

1. Skills as Data (数据化技能)
   • 实现：iit_skills 表中的 JSON 字段。
   • 优势：热更新。医生在后台改了配置，下一秒 Agent 就生效，无需重启服务。
2. Service as Tool (服务即工具)
   • 实现：ToolsService 类。
   • 优势：
     • 极速：函数调用，零延迟。
     • 稳定：利用 TypeScript 的类型检查，编译期就能发现错误。
     • 可控：我们可以轻松地在代码里加入重试、熔断、日志逻辑。
3. SOP State Machine (SOP 状态机)
   • 实现：通过 JSON 定义的流程图（Check A -> Check B）。
   • 优势：确定性。医疗流程不能随机应变，必须严格合规。状态机保证了 Agent 永远在轨道上运行。
4. Self-Correction Loop (自我修正回路)
   • 实现：在 SoftRuleEngine 中捕获工具调用错误，反馈给 LLM 重试。
   • 优势：大大提升了系统的鲁棒性，减少了因为 LLM "手滑" 导致的报错。

4. 为什么这套架构更适合我们？(SWOT 分析)

维度	Strengths (优势)	Weaknesses (劣势)	Opportunities (机会)	Threats (威胁)
效率	开发极快，复用现有 Node.js 代码。	不支持跨语言调用（目前也不需要）。	快速迭代，最快速度上线 MVP。	随着业务极其复杂，单一 Service 类可能变大。
稳定性	链路极短，没有网络开销，没有新进程。	强耦合在 Node.js 生态内。	极低的出错率，适合医疗场景。	无。
成本	零新增成本。不费服务器资源，不费 Token (Engine A)。	需自行维护 Service 代码。	将节省的 Token 成本转化为利润。	无。
扩展性	通过 JSON 配置即可支持新项目。	无法直接对接外部标准 MCP 工具。	形成行业壁垒：我们的 JSON 配置库就是核心资产。	如果未来 MCP 成为绝对主流，可能需要一层适配器。

5. 写给开发团队的话

兄弟们，我知道大家对新技术充满了热情，看到 "MCP"、"LangChain" 这样的词汇会觉得很兴奋。但在 IIT Manager 这个项目上，我们要克制。

1. 我们要的是“结果”，不是“概念”。用户不在乎你用的是不是 MCP，他们只在乎**“我问的问题能不能秒回”，“我的数据质控准不准”**。
2. 我们的护城河是“业务逻辑”，不是“胶水代码”。把精力花在编写更精准的 iit_skills 配置（JSON Logic + Prompt）上，这才是别人抄不走的壁垒。而 MCP 只是连接代码，谁都能写。
3. 简单就是力量。2 个人维护一套 Node.js + Postgres 系统，我们可以睡个安稳觉。如果引入了复杂的微服务和协议，我们的大部分时间都会花在修修补补上。

现在的架构，是我们在有限资源下，能做出的最优雅、最务实、最强大的选择。

让我们基于这套 V2.2 极简架构，全速推进 Phase 2 的开发！