csdn-cc-bioinfo

cc-bioinfo：一个能「自己跑完整生信分析」的本地 AI Agent 平台——架构拆解、核心工作流与上手

面向：做生信 / 临床科研的开发者、工程化爱好者、想把 AI Agent 用到真实科研流程里的人
关键词：AI Agent、生物信息学、本地部署、多用户隔离、MCP、可复现分析

大多数人用 AI 做生信，卡在同一个地方：AI 只会「纸上谈兵」地给你一段 R / Python 代码，真要跑，还得你自己装环境、配 conda、下数据、调报错、出图。对不会编程的临床医生和科研新手，这一步就是劝退线——统计和代码是那个「沉默的杀手」。

cc-bioinfo 想解决的正是这一段：它是一个本地可运行、面向生信 / 科研的 AI Agent 工作台，把「会写代码的通用 Agent」升级成「能在你自己的服务器上，真跑生信分析全流程、还能多用户团队共用」的平台——AI 自己建环境、装包、拉公开数据、跑分析、出图、写手稿。

本文从工程视角拆一下它的架构、两个核心工作流、防造假机制，以及怎么上手。末有 GitHub 与在线试用入口。

一、它和「直接让通用助手做生信」差在哪

一句话：通用助手给你「代码」，cc-bioinfo 给你「结果」。

它不是一个「聊天框套壳」，而是把「设计课题 → 真跑分析 → 诚实出稿」这条链路做成了可复现的工程流程。

二、整体架构（多用户形态）

先看多用户部署形态的分层（个人单机形态是它的简化版）：

![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=figures%2Fcsdn-arch.png&pos_id=img-AVtpRK8H-1786330972224

浏览器（登录态 / session） │ ▼ 反向代理（鉴权前置） │ 基于操作系统账户做身份校验 ▼ 每个登录用户 → 一个独立的用户级进程（各自的会话 / 设置 / 终端 / 记忆） │ 进程以该 Linux 用户身份运行，经 unix socket 通信 ▼ 真实运行环境（终端 + 沙箱 + conda）

几个关键设计点：

• 多用户隔离靠操作系统兜底：每个登录用户对应一个以其 Linux 账户身份运行的独立进程，通过 unix socket + 系统账户权限做隔离——不是「应用层用一个 userId 字段区分」那种软隔离，而是操作系统 UID / 文件权限这一层的硬隔离。团队共用一台服务器，各人的数据互不可见。
• 身份不信任客户端：用户身份一律由服务端从已认证会话解析，绝不采信前端传入的 userId，从机制上堵掉「猜个 id 就读别人数据」。
• 真实运行环境：OS 级沙箱（限制文件读写范围与网络）+ 浏览器内置终端（每用户独立、并发与空闲回收有上限）+ 分析工作流自动建 conda 环境。这是「真跑」的底座。

Agent 核心：流式状态机，不是经典 ReAct

平台的 Agent 循环没有走教科书式的 ReAct（想一步→做一步→再想），而是一个基于 AsyncGenerator 的流式状态机：一个主循环里跑「消息压缩 → 流式调用模型 → 决策点 → 工具编排 → 状态更新」，边生成边执行。配套的几个工程点，是长会话不退化的关键：

• 多级上下文压缩：从局部裁剪到整段折叠再到自动压缩，分级触发，控制上下文膨胀；
• 多种故障恢复策略：断流、超时、限流、子进程卡死等各有兜底，不是一崩到底；
• 工具并行策略：只读工具并行（有并发上限）、写入工具串行，兼顾速度和一致性；
• 多 Agent 编排：一个 coordinator 可以派生多个 worker 并行干活，支持 Teams 协作与 worktree 隔离，避免多个 Agent 互相踩文件。

其他工程特性（各一句话）

• Skills 系统（BYOS，Bring-Your-Own-Skill）：能力以 skill 插件形式扩展，条件激活；生信只是装上去的一个领域包，机制本身是通用的。
• MCP 集成：支持 stdio / SSE / HTTP / WebSocket 多种传输，工具运行时动态发现、并入统一工具池；内置 PubMed / 文献检索等。
• 第三方模型：可接入 Anthropic / OpenAI / DeepSeek / 本地 Ollama 等兼容模型，不锁死单一厂商。
• IM 接入：桌面端配置后，经独立 adapter 进程把会话桥接到飞书 / Telegram 等，远程对话（配对码有时效、一次性、失败限流）。
• 成本追踪：QueryEngine 累计 token / 花费，长任务花了多少心里有数。
• 质量门禁：统一入口一条命令（bun run verify），按改动影响面跑 policy / server / coverage 等；改生产代码必须带同区测试（Feature Quality Contract），coverage 只能涨不能降。
• 可观测性：内置 OpenTelemetry（traces / metrics / logs）。

三、两个核心工作流：bio-design 与 bio-analyze

这是 cc-bioinfo 做生信的「双引擎」。一个负责想清楚要做什么，一个负责真把它跑出来，中间用一份结构化交接单衔接：

![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/655db2c7175f4689bdb8c48d8c2bd2aa.png#pic_center

/bio-design 课题设计（对话式，不是一键生成） │ 产出 design.md + 结构化交接单（TOPIC.yml） ▼ /bio-analyze 读交接单 → 动态生成分析阶段 → 自动建 conda 环境 │ → 跑分析 / 出图 → 手稿 + 可复现包 ▼ /bio-design review 回看结果、修订设计，形成闭环

bio-design：科学思维的对话伙伴，不是流水线。
它不会闷头给你吐一份方案，而是在每个决策点停下来提问、等你回答（内部把步骤标成「检索 / 思考 / 对话」三种模式）。一条硬规则值得说：写进设计文档的所有文献 URL / ID 必须来自真实检索，不许用占位符编造；文献检索还内置了撤稿排除——避免把已撤稿的研究当证据。

bio-analyze：读交接单，动态生成流水线。
它不是固定几步，而是读完 TOPIC.yml 后按课题动态生成分析阶段（数量不定），一路走到出图、写稿、准备投稿。两个工程亮点：

1. 环境自动准备：conda-first 的决策树——有环境就复用，缺包即装，机器上没有 conda 就自举一个，连构建方式都找不到时强制去联网查。用户不需要预装 R / Python。
2. 可复现产物：产出里带environment.yml、R_session_info、run_all.sh、带 checksum 的数据来源清单——别人能照着复现，这是生信文章最该有、也最常缺的一环。

四、防造假：把「诚实」写进机制，而不是靠自觉

这是 cc-bioinfo 最该被工程同行看到的部分。AI 做科研最大的风险不是「跑不动」，是「为了让结果好看，偷偷 p-hack、放宽阈值、把弱结果吹成强结论」。它的对策是把约束前置并写死：

![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=figures%2Fcsdn-antifraud.png&pos_id=img-foOa5GYY-1786330972225

# 预注册硬约束（机制示意，非真实配置）hard_constraints:-id:pathway_gaterule:"目标通路的显著差异基因数 ≥ 3"fail_action:HARD_STOP# 不达标就停止该假设，禁止放宽阈值保命题-id:wording_ceilingrule:"分子对接类结论只能用 predict / suggest / indicate"forbidden:[prove,demonstrate,cause]# 禁止因果 / 确证式断言iron_rules:-禁止编造任何未真实跑出的数据-禁止把训练 / 泄漏数据当结果-禁止静默跳过步骤或偷换工具

配套还有两层：

• 状态机诚实记账：哪个分析阶段失败了、被归档了，如实写进workflow_state.yml，不抹掉重写成「一切顺利」；
• 决策日志：每个判断、每个坑记一条（严重度 + 现象 + 处置 + 状态），全程可审计。

一句话：它不保证你一定能出阳性结果，但保证不替你造假。这恰恰是敢把真实课题交给它的前提。

五、一个真实案例（脱敏）：它是怎么「诚实翻车又爬起来」的

平台归档里有多个「两个 AI 全程无人干预跑完」的真实课题。挑一个最能说明工程严谨性的（数值来自项目归档记录）：

课题：常用麻醉药七氟醚 × 心肌缺血再灌注损伤 × 铁死亡 的生信 + 分子对接。

• 撞预注册闸门，选择诚实失败而非放宽阈值：原定主通路在严格阈值下几乎跑崩（十几个目标基因只中一个）。预注册规则写死了「不达标就换路、禁止把阈值放宽到勉强过关」——于是它止损切换到另一条通路重跑，而不是 p-hack 保命题。原来那份阴性结果没删，归档成诚实记录。
• 弱结果用阳性对照定量框定：分子对接打分全是弱结合（没有一个过公认的强结合线）。它补了一个公认真抑制剂做阳性对照，一对比就把「弱」钉成了有意义的结论——不是流程有问题，是这个药本来就不靠高亲和力单靶点结合。定稿前还主动撤回了一处把对接打分越界换算成「亲和力差几百倍」的错误表述。
• 自愈能力（真实发生）：装包没有写权限 → 自动改装到用户库；下载超时 → 自动加长重试；一个进程自匹配导致死循环占满 CPU → 自主止损并改成有界循环；某绘图包编译失败 → 换等效包。这些都是它「看日志 → 猜原因 → 验证 → 修复」自己完成的。

同类归档里还有：颈动脉斑块单细胞 + 空间转录组（当场砍掉站不住的假设、把削帽程序如实归给免疫细胞）、CAVD vs 冠心病对比孟德尔随机化（他汀为何救不了瓣膜的靶点错配）、房颤→心衰蛋白中介 MR（扫了近两千个血浆蛋白、中介零命中、如实写成「直接机制」）等——共同点是：阴性 / 弱结果全都如实呈现，没有一处美化。

六、技术栈与部署

技术栈：Bun + TypeScript 为主；CLI 用 Ink（React 渲染终端 TUI，支持--print无头模式）；鉴权服务用 Go；生信分析侧 R ≥ 4.3 + Python ≥ 3.9（由分析工作流自动装）；文档站 VitePress；测试用 bun test / Vitest / Playwright。

部署形态：

1. 单机 / standalone（个人）：跑安装脚本选单机模式，浏览器本地访问，systemd user 服务托管。
2. 多用户 / multiuser（团队服务器，Ubuntu LTS + root）：安装脚本一路装好反代、TLS、鉴权服务、systemd，团队成员用各自系统账户登录，彼此隔离。
3. BYOS：自己写领域 skill 插件（plugin.json+SKILL.md），把平台改造成任意领域的 Agent 工作台。

七、诚实边界（已知限制，先说清楚）

promo 归 promo，几条得如实讲——这也是这个项目一贯的调性：

• 数据外发：如果你接的是云端模型（Anthropic / OpenAI / DeepSeek 的 API），对话内容会发给对应厂商；想让数据完全不出内网，请接本地 Ollama之类的本地模型。当前版本基于「数据敏感度」自动拦截外发的路由尚未完全实装，涉密数据请自行按上述方式控制，别默认它帮你拦住了。
• Computer Use（让模型截屏 / 操作 UI）：目前对 Linux 适配不完整，能力更完整的是桌面端场景。

把边界写在最显眼处，本身就是这个平台想传达的方法论：一个愿意告诉你「这条我还没做到」的工具，才值得你把真实课题交给它。

八、试一试

• 开源仓库（MIT）：https://github.com/tangmoogmoogtang-dotcom/cc-bioinfo
• 在线体验：https://www.cc-bioinfo.com —— 不用装环境、不用写代码，打开浏览器就能开一个课题，把你的数据 + 假设贴进去，看它能诚实地帮你跑到哪一步。