EXIST-D/MedStatForge Agent Skills auf GitHub

README des Repositorys

Vollständige README anzeigen

# MedStatForge —— 个人 AI 知识库与医学统计助手 > **Med + Stat + Forge**：将私有文献、研究数据与统计方法“锻造”为可检索、可审阅、可确认、可复现的医学研究分析流程。 MedStatForge 是一个面向单个研究者本地部署的医学科研工作台。它将项目私有知识库、Agent、RAG、多文件数据盘点、医学统计 Skill、人工确认与结果交付连接为一条可追溯的工程链路；它不是仅输出文本答案的通用聊天工具。项目采用 Docker Compose 本地编排。除 Docker 外，部署者不需要在宿主机安装 Python、Node.js、R、SPSS、Stata、SAS 或医学统计 Skill。 --- ## 目录 - [核心功能](#核心功能) - [技术栈](#技术栈) - [系统架构](#系统架构) - [环境要求](#环境要求) - [快速开始](#快速开始) - [首次使用流程](#首次使用流程) - [常见问题](#常见问题) - [目录架构](#目录架构) - [开发约定](#开发约定) --- ## 核心功能 ### 1. 项目私有知识库与 RAG - 支持上传 PDF、DOCX、XLSX、CSV、Markdown、HTML、代码、问卷/量表说明等研究材料；资源在项目维度隔离。 - 对文本进行 Unicode 清洗、章节定位与 L1/L2/L3 三级父子分块；每个块保留文件、页码、章节、父块、根块和索引位置等元数据。 - 以本地 `BAAI/bge-m3` 稠密向量、Milvus BM25 稀疏向量、Hybrid Search 和 RRF 融合完成检索；模型或向量服务不可用时，Trace 会明确显示降级路径。 - 支持 L3 叶节点召回、父块自动合并、可选 rerank、一次查询改写、复杂问题子问题检索、证据质量评分与引用来源跳转。 - 方法结论绑定来源 chunk；证据不足、相互冲突或文献未报告时，会显示不确定性，而不会将推测包装为文献事实。 ### 2. 会话型研究 Agent - 以 LangGraph 主图编排项目上下文、复杂度路由、工具选择、RAG、回答合成与跨进程 HITL 恢复。 - 主 Agent 可按项目需要调用知识检索、MethodProfile、数据盘点、统计方案草稿、方法综合、复现映射与结果解释等工具。 - 会话、标题、消息历史、持久摘要、ProjectState、SessionState、Artifact Version 和待恢复 HITL 状态均可持久化。 - 浏览器通过 SSE 展示 token、工具调用、检索 Trace、路由、错误与人工审阅请求，研究者可回看研究过程与证据上下文。 - 模型不能调用统计执行或读取患者级原始数据；`confirm`、`execute`、R 运行和系统包管理不属于 Agent Tool。 ### 3. 文献方法综合与复现映射 - 从单篇或多篇论文提取结构化 MethodProfile：方法、软件、参数、样本、变量、缺失处理和报告要求均与证据关联。 - 对多篇论文做 map/reduce 综合，保留相互支持与相互冲突的来源，形成可审阅的 MethodSynthesis。 - ReproductionPlan 将文献要求映射到本项目数据中可获得的变量、待确认参数和不可复现限制；文献方法是可审阅参考，而非被硬编码的唯一方案。 ### 4. 多文件数据盘点与组合研究范围 - 支持 CSV/TSV/DAT/JSON、Excel、SPSS、Stata、SAS、R、Parquet/Feather/Arrow/ORC/Avro、SQLite、ARFF、HTML/XML 等常见研究数据格式。 - 原始文件保留在项目私有 Docker volume；执行前统一在容器内规范化为 UTF-8 `analysis.csv`。 - API 与模型只接收行数、列数、变量名、类型和缺失等聚合盘点，不接触患者级行值。 - 可建立数据文件夹、DataBundle 与组合分析范围，明确各文件的角色、连接键、基数、时间关系和变量概念。 - 多文件分析输出安全的连接审计与子运行结果，不会在网页、Agent 上下文或交付包中暴露合并后的行级数据。 ### 5. 医学统计 Skill、审阅与执行 - Redis Worker 调用固定快照的 `medical-analysis-orchestrator`，遵循 `inspect → recommend → validate → human confirm → execute` 流程。 - 统计方案页面由后端可用模块目录驱动，为不同统计模块提供动态、专用的变量绑定和参数表单。 - 方案哈希、变量绑定、人工确认、Redis 任务、Skill 输入、结果导入与解释均被审计；只有确认了当前方案哈希的任务才可执行。 - API 不直接运行 R，独立 Worker 才能执行经确认的医学统计任务；失败会保留可审阅状态与日志，不会伪造结果。 ### 6. 结果、制品与可持续扩展 - 结果与交付中心仅展示已通过质量门的安全汇总结果、表格、图形、报告和 ZIP 制品包。 - 重要研究对象采用 append-only Artifact Version，支持版本链、审阅和下载清单；不导出原始数据或患者级清洗数据。 - 后续新增 Agent、RAG 策略、统计模块或交付能力时，应在本节补充功能边界、输入输出与人工确认要求。 --- ## 技术栈 | 层级 | 使用技术 | 职责 | | --- | --- | --- | | 前端 | Vue 3、TypeScript、Pinia、Vite、Nginx | 研究助手、知识库、数据盘点、统计方案、审阅、运行与结果交付界面 | | API | FastAPI、SQLAlchemy 2、Pydantic | 项目边界、REST API、SSE、Agent 编排、RAG 路由、数据与制品契约 | | Agent | LangGraph、LangChain Tool Calling | 主图路由、工具调用、HITL、会话状态、复杂问题分解与回答合成 | | RAG | LangChain Loader、L1/L2/L3 分块、Milvus 2.5、BM25、RRF | 文档解析、混合检索、引用、证据判断与 Trace | | Embedding 与模型 | 私有 Docker `BAAI/bge-m3` 服务、OpenAI-compatible 对话模型 | 本地 1024 维语义向量；可选对话、改写、评分和科学写作 | | 状态与迁移 | PostgreSQL 16、Alembic | ProjectState、SessionState、Artifact Version、计划、运行与审计记录 | | 异步执行 | Redis 7、Python Worker | 已确认统计任务的队列消费、Skill 适配与结果导入 | | 医学统计 | 容器化 R 4.4、`medical-analysis-orchestrator` 快照 | 受控执行医学统计模块、产生图形、表格、报告和审计制品 | | 文档处理 | PDF/DOCX/XLSX/HTML 解析、私有 OCR 服务 | 文本提取、章节化、解析质量状态与扫描文献辅助处理 | | 基础设施 | Docker Compose、Milvus、etcd、MinIO、Docker named volumes | 本地服务编排、向量索引依赖与项目私有持久化 | --- ## 系统架构 ```text 研究者浏览器 │ http://127.0.0.1:5173 ▼ ┌───────────────────────────────────────────┐ │ Web 工作台 · Vue 3 / Nginx │ │ 研究助手 · 知识库 · 数据集 · 方案 · 审阅 │ └───────────────────────────────────────────┘ │ 同源 /api/ 与 SSE ▼ ┌──────────────────────────────────────────────────────────┐ │ API · FastAPI │ │ ProjectState / SessionState · LangGraph Agent · RAG · SSE │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ PostgreSQL Redis Queue Milvus Hybrid Search 项目/会话/制品已确认任务 Dense + BM25 + RRF Alembic 迁移 │ │ │ ▼ ▼ │ Redis Worker Embedding / OCR │ │ 私有 Docker 服务 │ ▼ │ medical-analysis-orchestrator │ R 4.4 统计执行与结果导入 ▼ 项目私有 Docker named volumes 原始资料 · 规范化数据 · 安全结果 · 交付制品 ``` 默认仅 `web` 映射到宿主机的 `127.0.0.1:5173`；API、PostgreSQL、Redis、Milvus、Embedding、OCR 和 Worker 位于 Compose 私有网络，不应额外暴露到公网。 --- ## 环境要求 | 项目 | 最低要求 | 建议与说明 | | --- | --- | --- | | 操作系统 | 兼容 Docker 的 Linux，或 Windows 11 + WSL2 | Windows 用户推荐使用 Ubuntu 24.04 WSL 环境执行命令 | | Docker | Docker Engine / Docker Desktop，支持 `docker compose` | Windows 请在 Docker Desktop 启用 WSL integration | | CPU | x86_64，支持 Docker 容器运行 | Embedding 默认使用 CPU；不要求 GPU | | 内存 | 8 GB 可用内存 | 文档解析、OCR、Embedding 和 R 分析并发时建议预留更多内存 | | 磁盘 | 至少 15 GB 空闲空间 | 包含镜像、数据库、Milvus 索引与约 2.3 GB BGE-M3 模型缓存 | | 网络 | 首次构建/模型下载期间可联网 | 后续镜像、模型及数据存储在 Docker named volumes 中 | | 对话模型 Key | 可选 | 配置 OpenAI-compatible Key 后启用模型驱动 Agent；不配置时使用明确标记的安全降级路径 | 宿主机无需安装 Python、Node.js、R、SPSS、Stata、SAS 或 Skill 运行环境，也不应将宿主机的这些环境挂载进容器。 --- ## 快速开始以下步骤适用于新的本地部署者。所有命令在项目目录所在的 Linux/WSL 终端执行。 ### 1. 获取源码 ```sh git clone https://github.com/EXIST-D/MedStatForge.git cd MedStatForge ``` 确认 Docker 可用： ```sh docker --version docker compose version ``` ### 2. 创建本地配置 ```sh cp .env.example .env ``` `.env` 仅供本机 Docker Compose 读取，已被 Git 忽略。若希望启用真实模型调用，编辑 `.env` 并填写自己的 OpenAI-compatible Key；不要将密钥写入源代码、镜像、`compose.yaml` 或 Git。 ```dotenv OPENAI_BASE_URL=https://api.deepseek.com OPENAI_API_KEY=请填写你自己的密钥 FAST_MODEL=deepseek-v4-flash GRADE_MODEL=deepseek-v4-flash AGENT_MODEL=deepseek-v4-flash ``` 不配置 Key 时，请保留 `OPENAI_API_KEY` 为空。知识库上传、文本清洗、分块、项目内检索、数据盘点、审阅状态与确认门仍会运行；模型相关步骤会清晰标记为未配置或降级，绝不会伪造模型输出。 ### 3. 构建项目内部基础镜像 ```sh sh scripts/bootstrap-internal-images.sh ``` 该脚本只构建 MedStatForge 自己使用的 Ubuntu 与 Node 基础镜像。之后的 API、Web、Worker、Embedding、OCR 和 R Skill 均在容器内运行，不依赖宿主机语言运行时。 ### 4. 启动全部服务 ```sh docker compose up --build -d ``` 首次启动会构建应用镜像，并由 `embedding` 服务下载 `BAAI/bge-m3`。模型缓存写入 Docker named volume，后续重启不会重复下载。 ### 5. 检查状态并打开工作台 ```sh docker compose ps docker compose logs -f api worker embedding ``` 当服务运行后，在浏览器打开 <http://127.0.0.1:5173>。如 Embedding 仍在下载，可先使用文件上传、解析、分块、词法检索、数据盘点和方案审阅；RAG Trace 会显示当前能力状态。 ### 6. 修改模型配置后的重启方式修改 `.env` 后重建并重启依赖模型配置的服务： ```sh docker compose up --build -d api worker ``` --- ## 首次使用流程 1. **创建项目**：建立一个研究项目。文献、数据集、会话、计划、运行和制品均以项目为边界隔离。 2. **上传知识材料**：在“知识库”上传论文、指南、量表、编码手册或研究代码，查看上传、解析、章节化、三级分块、父块入库和索引状态。 3. **上传研究数据**：在“数据集”上传一个或多个数据文件；按需要建立文件夹整理基线、随访、结局或量表资料。页面只显示安全的聚合盘点。 4. **声明数据包范围**：涉及多个文件时，在“数据包与组合方案”中明确文件角色、连接键、基数、时间关系和变量概念。系统不会擅自猜测或合并数据。 5. **提出研究问题**：在“研究助手”描述研究需求，或在“统计方案”中选择数据集、统计模块和变量绑定。 6. **审阅证据与方案**：核对引用来源、检索 Trace、方法综合、可复现映射、变量角色、缺失策略、分析参数、风险提示与待决事项。 7. **确认并执行**：研究者确认当前方案哈希后，Redis Worker 才会调用医学统计 Skill；Agent 与网页均不能跳过此门。 8. **审阅结果并交付**：在“结果与交付”查看导入结果、表格、图形、学术报告、Artifact Version 与安全 ZIP 交付包。 --- ## 常见问题 ### 首次检索较慢或显示 Embedding 未就绪？首次运行需要下载约 2.3 GB 的 `BAAI/bge-m3` 权重。执行 `docker compose logs -f embedding` 查看进度。服务未就绪时，系统会在 Trace 中显示词法或 hash 降级，不能将其视为语义向量检索已完成。 ### 未配置模型 Key 能否使用系统？可以。私有文献入库、文本清洗、三级分块、基础检索、数据盘点、统计方案审阅和人工确认门均可使用；需要模型生成、改写、评分或论文式写作的步骤会返回可解释的降级状态。 ### 为什么 Agent 不能直接执行统计分析？统计执行必须绑定已审阅的变量、模块、方法参数与方案哈希。研究者确认后，独立 Worker 才能调用 Skill，以避免自然语言对话绕过研究设计、审计和安全边界。 ### 原始患者级数据会被送给模型或出现在交付包中吗？不会。模型与 API 仅接收聚合盘点；原始文件、规范化数据和执行中间数据保存在项目私有 Docker volume。结果页与 ZIP 交付包只包含经过质量门的安全制品。 > 本节会持续收集真实部署与使用问题；如遇未覆盖情况，请先保留 `docker compose ps` 与相关服务日志，再提交问题描述。 --- ## 目录架构 ```text MedStatForge/ ├── apps/ │ └── web/ # Vue 3 前端工作台 │ └── src/ │ ├── components/ # Chat、知识库、数据、方案、审阅、运行、结果等页面组件 │ ├── stores/ # Pinia：项目、会话、知识、审阅与界面状态 │ ├── types/ # 前端接口与领域类型 │ └── utils/ # API、SSE、Markdown、图标等客户端基础设施 ├── services/ │ ├── api/ # FastAPI 后端、RAG、Agent、状态与 API 测试 │ │ ├── app/ │ │ │ ├── contracts/ # ProjectState、SessionState、SSE、制品等共享契约 │ │ │ └── specialist_agents/ # 方法、数据、方案、结果解释、写作等专门 Agent │ │ ├── migrations/ # Alembic 数据库版本迁移 │ │ └── tests/ # API、RAG、Agent、SSE 与 E2E 回归测试 │ ├── worker/ # Redis Worker 与容器化 R 统计运行时 │ ├── embedding/ # 私有 BGE-M3 Embedding HTTP 服务 │ └── ocr/ # 私有 OCR 与扫描文献辅助服务 ├── integrations/ │ └── medical-analysis-skill/ # 固定快照的医学统计 Skill、R 模块、模板与测试 ├── docker/ # 项目内部 Ubuntu / Node 基础镜像定义 ├── scripts/ # 基础镜像构建、维护与开发辅助脚本 ├── compose.yaml # 全部本地服务的 Docker Compose 编排 ├── .env.example # 不含真实密钥的环境变量模板 ├── .gitignore # 密钥、数据、制品、缓存与构建产物排除规则 ├── README.md # 项目简要总览 └── REMADE.md # 本部署、使用与工程说明 ``` 运行期 PostgreSQL、Redis、Milvus、MinIO、Embedding 模型、项目文件和结果制品存储在 Docker named volumes 中，不位于仓库目录，也不应提交到 Git。 --- ## 开发约定 ### 本地优先与项目边界 - 当前版本面向单个研究者本地部署；多用户认证、云端租户隔离和服务器治理不属于现阶段默认承诺。 - 项目是知识、数据、会话、方案、运行、结果和制品的隔离边界。新增功能不得跨项目读取资源。 ### Agent、RAG 与 Tooling 的职责分离 - Agent 负责对话理解、路由、工具选择、证据组织与审阅协作，不负责绕过确认门。 - RAG 负责来源可追溯的证据检索、引用和不确定性表达，不替代研究者的方法学判断。 - 医学统计 Skill 是可替换的专业 Tooling，负责接收已确认的最小执行输入并生成受审计制品；它不持有对话记忆或用户授权。 ### 状态、版本与执行安全 - 数据库结构变更必须通过 Alembic migration 实现，不应恢复使用 `create_all()` 修改已有数据库。 - 重要研究对象应记录 append-only Artifact Version；状态、审阅、HITL 与结果变更应可追踪、可恢复、可比较。 - 执行链路固定为：`inspect → recommend → validate → 人工确认方案哈希 → Redis Worker → execute → 导入结果`。 - API 不执行 R；只有 Worker 可以调用固定快照的医学统计 Skill。任何新增执行模块都必须延续此确认与审计边界。 ### 测试与持续维护 - 后端、前端、RAG、Agent、数据接入、Golden Evaluation 与 E2E/SSE 顺序回归均是功能变更的验证对象。 - 新增核心功能时，需要同步更新接口契约、回归测试，以及本说明的“核心功能”“目录架构”或“快速开始”。 - 不应将任何特定论文、测试数据或统计方法固化为全平台的唯一正确方案。 ### 机密、数据与公开发布 - 真实 API Key 只保存在未提交的 `.env`；真实文献、数据、结果、Docker volumes、模型权重、`node_modules`、虚拟环境与构建产物不得提交。 - 若密钥曾进入 Git 历史，必须在供应商侧撤销并轮换；删除文件或补充 `.gitignore` 无法清除历史泄露。 - MedStatForge 用于科研辅助和统计工程。研究者仍需对研究设计、方法前提、伦理合规、临床解释与最终学术结论负责。 --- 项目部署、使用与公开开发约定以本说明为准。

medical-analysis-orchestrator

Datenwissenschaftler

通用医学数据分析编排 Skill。用于读取 CSV、Excel、DAT、SPSS、Stata、SAS、JSON 等医学或问卷数据，先只读完成数据盘点、变量字典、质量报告和方法建议，再在用户确认研究问题、结局、变量、清洗规则和统计方案后，自动发现 R、按模块安装项目级依赖，执行常规比较与回归、缺失数据与多重插补、生存与纵向分析、诊断准确性、心理测量与结构方程、倾向评分、网络或贝叶斯网络分析，验证统一结果对象，并输出三线表 XLSX、由 R 生成且带 Source Data 的图形和指定中文格式的 Word…

Quellsprache: Chinesisch

2026-08-22

EXIST-D/MedStatForge

Mit einem KI-Assistenten installieren

README des Repositorys

Skills in diesem Repository

medical-analysis-orchestrator

README des Repositorys