AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/00-系统设计/IIT Manager Agent V2.2 落地实施指南：极简架构版 (融合 Moltbot).md

IIT Manager Agent V2.2 落地实施指南：极简架构版 (融合 Moltbot)

文档版本： V2.2 (Moltbot Enhanced)

日期： 2026-02-03

适用对象： 2人高效开发团队

核心原则： Postgres-Only, No New Components, Service-First, Proactive & Personalized

变更说明： 在 V2.1 基础上，借鉴 Moltbot (Clawbot) 的主动性与记忆机制，增加了用户偏好存储、每日早报 Skill 和自我修正回路。

1. 核心架构：回归本质 (The Pragmatic Architecture)

我们将“Brain-Hand-Tool”模型映射到现有的 Node.js + Postgres 技术栈上。

graph TD
subgraph "Layer 3: 数字化大脑 (The Brain)"
DB[(Postgres DB)]
DB -->|加载 Skills & Preferences| Engine[QcEngineService]

    subgraph "混合双引擎"  
        Engine \--\>|1. 执行 JSON Logic| Logic\[Engine A (硬规则)\]  
        Engine \--\>|2. 组装 Prompt (含偏好)| LLM\[Engine B (软指令)\]  
    end  
end

subgraph "Layer 2: 伪 MCP 接口层 (The Hand)"  
    LLM \--\>|3. 调用| Tools\[ToolsService (Class)\]  
    Logic \--\>|3. 调用| Tools  
      
    Tools \--\>|read\_data| Tool1\[RedcapAdapter\]  
    Tools \--\>|search\_doc| Tool2\[VectorSearchService\]  
    Tools \--\>|send\_msg| Tool3\[WechatService\]  
end

subgraph "Layer 1: 基础设施 (The Tool)"  
    Tool1 \--\> REDCap  
    Tool2 \--\> pgvector  
    Tool3 \--\> WeCom  
end

2. 数据层设计：Skills 即数据 (Skills as Data)

不再使用 OSS 存文件，直接使用 Postgres iit_schema 存储结构化配置。新增用户偏好表。

2.1 数据库 Schema

// schema.prisma

// 核心技能表
model IitSkill {
id String @id @default(uuid())
projectId String // 绑定项目 ID (如 PID=16)
formName String // 绑定表单 (如 demographics) 或 场景 (如 daily_briefing)

// 核心配置 (JSON 类型)
// 包含 hard_rules, soft_instructions, schedule (cron表达式)
config Json

isActive Boolean @default(true)
version Int @default(1)
updatedAt DateTime @updatedAt

@@unique([projectId, formName])
@@map("iit_skills")
@@schema("iit_schema")
}

// [New] 用户偏好表 (Moltbot 记忆机制)
model IitUserPreference {
id String @id @default(uuid())
userId String // 绑定企业微信 UserID
projectId String // 绑定项目

// 偏好配置 (JSON)
// 例如: { "report_style": "concise", "notification_time": "08:30" }
preferences Json

updatedAt DateTime @updatedAt

@@unique([userId, projectId])
@@map("iit_user_preferences")
@@schema("iit_schema")
}

2.2 JSON 配置范例 (Skill)

范例 1：质控 Skill

{
"description": "人口学表单质控",
"hard_rules": [
{
"field": "age",
"logic": { ">=": [{ "var": "age" }, 18] },
"message": "年龄必须 >= 18 岁"
}
],
"soft_instructions": [
{
"instruction": "检查备注字段。如果包含'无法签署知情同意'，请标记违规。",
"tools": ["read_clinical_data"]
}
]
}

范例 2：[New] 每日早报 Skill (Moltbot 主动性)

{
"description": "每日项目进展早报",
"schedule": "0 30 8 * * *", // 每天 08:30 触发 (pg-boss)
"soft_instructions": [
{
"instruction": "请统计昨天的入组人数、待处理质疑数。生成一段简报发给 PI。注意参考用户的 report_style 偏好。",
"tools": ["get_project_stats", "send_wechat_msg"]
}
]
}

3. 服务层设计：伪 MCP 实现 (Service-First)

不要引入 @modelcontextprotocol/sdk。创建一个标准的 Service 类来管理工具。

3.1 ToolsService.ts 实现规范

// backend/src/modules/iit-manager/services/ToolsService.ts

import { RedcapAdapter } from '../adapters/RedcapAdapter';
import { VectorSearchService } from '@/common/rag/vectorSearchService';

// 定义工具接口 (为了给 LLM 生成菜单)
export const TOOL_DEFINITIONS = [
{
name: "read_clinical_data",
description: "读取REDCap临床数据...",
parameters: { ... }
},
{
name: "update_user_preference", // [New] 更新偏好工具
description: "更新用户的偏好设置，如报告风格、通知时间。",
parameters: {
type: "object",
properties: {
key: { type: "string", description: "偏好键名，如 report_style" },
value: { type: "string", description: "偏好值，如 concise (简洁) 或 detailed (详细)" }
}
}
}
];

export class ToolsService {
constructor(
private redcap: RedcapAdapter,
private rag: VectorSearchService,
private prisma: PrismaClient
) {}

// 统一执行入口 (LLM 只认识这个)
async executeTool(name: string, args: any) {
switch (name) {
case 'read_clinical_data':
return this.redcap.exportRecords(args);

  case 'update\_user\_preference':  
    // \[New\] 实现记忆更新  
    return this.updatePreference(args);  
    
  case 'raise\_query':  
    return this.savePendingAction(args);  
      
  default:  
    throw new Error(\`未知工具: ${name}\`);  
}  

}
}

4. 业务层设计：混合引擎调度 (含自我修正)

4.1 执行逻辑 (The Pipeline)

// backend/src/modules/iit-manager/services/QcEngineService.ts

export class QcEngineService {

async runQualityCheck(projectId: string, formName: string, data: any, userId?: string) {
// 1. 加载 Skill 和 用户偏好
const skill = await prisma.iitSkill.findUnique({...});
const userPref = userId ? await prisma.iitUserPreference.findUnique({ where: { userId, projectId } }) : null;

if (\!skill) return;

// 2\. 运行 Engine A (硬规则)  
const engineA \= new HardRuleEngine();  
const hardErrors \= engineA.run(skill.config.hard\_rules, data);  
  
if (hardErrors.length \> 0\) {  
  await this.saveShadowState(hardErrors);  
  return;   
}

// 3\. 运行 Engine B (软指令) \- \[New\] 注入偏好 Context  
const engineB \= new SoftRuleEngine(this.llm, this.toolsService);  
  
// 将偏好注入 Prompt: "用户偏好简洁的报告，请不要废话。"  
const context \= {  
  ...data,  
  user\_preferences: userPref?.preferences  
};

// \[New\] 开启自我修正回路 (Self-Correction Loop)  
const softSuggestions \= await engineB.runWithRetry(skill.config.soft\_instructions, context, 3);  
  
if (softSuggestions) {  
  await this.saveShadowState(softSuggestions);  
}  

}
}

4.2 自我修正机制 (Self-Correction Loop)

借鉴 Moltbot，当工具调用失败时，不报错，而是让 LLM 重试。

// SoftRuleEngine.ts (伪代码)

async runWithRetry(instruction, context, maxRetries = 3) {
let history = [...];

for (let i = 0; i < maxRetries; i++) {
const response = await llm.chat(history);

if (response.hasToolCall) {  
  try {  
    const result \= await tools.executeTool(response.toolName, response.args);  
    history.push({ role: 'tool', content: result });  
  } catch (error) {  
    // \[New\] 捕获错误，喂回给 LLM  
    console.warn(\`Tool Error: ${error.message}\`);  
    history.push({   
      role: 'user',   
      content: \`工具调用失败: ${error.message}。请检查参数并重试。\`   
    });  
    continue; // 让 LLM 重新思考  
  }  
} else {  
  return response.content;  
}  

}
}

5. 实施路线图 (2人团队专属)

✅ Week 1: 基础建设 (Engine A)

1. 创建 iit_skills 和 iit_user_preferences 表。
2. 引入 json-logic-js 库。
3. 实现 QcEngineService 的基础骨架，只跑硬规则。

🚧 Week 2: AI 接入与主动性 (Engine B)

1. 创建 ToolsService，实现基础工具。
2. 实现 SoftRuleEngine 的 自我修正回路。
3. 里程碑：配置 daily_briefing Skill，利用 pg-boss 定时触发，早上 8:30 收到测试推送。

📋 Week 3: 界面与优化

1. 开发 Admin 页面 (JSON Editor) 编辑 Skill。
2. 完善影子状态 (Shadow State) 审核界面。

6. 多轮对话与开放式问答支持

6.1 核心策略：Intent Routing + General Skill

不要把所有逻辑都写死在质控里。我们增加一个特殊的 Skill：general_qa。

A. 配置 general_qa Skill

在数据库插入一条 formName = 'general_chat' 的记录：

{
"description": "通用问答与查询助手",
"soft_instructions": [
{
"instruction": "你是本项目的智能助手。你可以回答关于项目进度、患者数据、方案细节的问题。请根据用户意图调用工具。",
"tools": ["read_clinical_data", "search_protocol", "get_project_stats", "update_user_preference"]
}
]
}

6.2 代码实现：聊天入口 (ChatService.ts)

// backend/src/modules/iit-manager/services/ChatService.ts

export class ChatService {
constructor(
private qcEngine: QcEngineService,
private sessionMemory: SessionMemory
) {}

async handleUserMessage(userId: string, projectId: string, message: string) {
// 1. 获取历史对话 & 用户偏好
const history = await this.sessionMemory.get(userId);
const userPref = await prisma.iitUserPreference.findUnique({...});

// 2\. 加载通用 Skill  
const generalSkill \= await prisma.iitSkill.findUnique({  
  where: { projectId, formName: 'general\_chat' }  
});

// 3\. 构造 Prompt (包含 History \+ Skill \+ Preferences)  
const prompt \= \`  
  ${generalSkill.config.soft\_instructions\[0\].instruction}  
    
  \[User Preferences\]: ${JSON.stringify(userPref?.preferences || {})}  
    
  历史对话:  
  ${history.map(h \=\> \`${h.role}: ${h.content}\`).join('\\n')}  
    
  用户当前问题: ${message}  
\`;

// 4\. 调用 LLM (Engine B 逻辑复用，含自我修正)  
const response \= await this.qcEngine.runSoftAgent(prompt, generalSkill.config);

// 5\. 更新记忆  
await this.sessionMemory.add(userId, { role: 'user', content: message });  
await this.sessionMemory.add(userId, { role: 'assistant', content: response });

return response;  

}
}

7. Moltbot 理念借鉴总结

借鉴点	IIT Manager 落地实现	价值
主动性 (Proactivity)	每日早报 Skill：利用 pg-boss 定时触发 daily_briefing Skill，主动推送企微消息。	让用户感觉系统是活的，而不是被动的数据库。
记忆 (Memory)	用户偏好表：存储 report_style, notification_time 等，Prompt 动态注入。	提供千人千面的个性化体验。
自我修正 (Self-Correction)	重试回路：Engine B 在工具报错时，将错误信息回传给 LLM，允许其修正参数重试。	极大提升系统鲁棒性，减少人工运维。

结论：这就是 IIT Manager Agent 的最终形态。既有医疗的严谨（硬规则），又有个性化的温度（偏好记忆），还有极简的架构（Postgres-Only）。开干吧！