HaHafeng
0c590854b5
Features: - Add V2.9 enhancements: Cron Skill, User Profiling, Feedback Loop, Multi-Intent Handling - Create modular development plan documents (database, engines, services, memory, tasks) - Add V2.5/V2.6/V2.8/V2.9 design documents for architecture evolution - Add system design white papers and implementation guides Architecture: - Dual-Brain Architecture (SOP + ReAct engines) - Three-layer memory system (Flow Log, Hot Memory, History Book) - ProfilerService for personalized responses - SchedulerService with Cron Skill support Also includes: - Frontend nginx config updates - Backend test scripts for WeChat signature - Database backup files Co-authored-by: Cursor <cursoragent@cursor.com>
118 lines
7.3 KiB
Markdown
118 lines
7.3 KiB
Markdown
# **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 的开发！ |