基于大语言模型的私有化AI健康助手：Open Health Agent设计与实践

1. 项目概述一个真正属于你的AI健康数据管家最近几年我自己的健康数据越来越“散装”了。体重秤的数据在App A里跑步机的记录在App B里偶尔在微信上跟朋友吐槽一句“昨晚又没睡好”这些碎片化的信息就像沙滩上的贝壳看着挺多但一阵浪打过来就全没了。更关键的是这些数据都躺在别人的服务器上隐私问题始终是悬在头顶的剑。我一直想找一个能自己掌控、能长期积累、并且能用AI帮我看出点名堂的工具但市面上的产品要么太重全家桶式健康管理平台要么太轻简单的日记App要么就是隐私不保。直到我开始动手搞这个项目——Open Health AgentOHA。它的核心目标非常明确帮你把散落在各处的健康数据统一收集到你自己的设备上永久保存并利用大语言模型LLM进行智能分析和主动关怀。这不是一个试图替代医生或专业医疗软件的工具而是一个专注于“数据主权”和“长期趋势”的个人健康数据伴侣。你可以把它想象成一个永远在线、绝对忠诚、且不断进化的私人健康秘书它的“大脑”AI模型可以更换和升级但所有的“记忆”你的健康数据都牢牢掌握在你自己手里。这个项目适合所有对个人健康数据有长期管理需求同时又注重隐私和自主权的朋友。无论你是健身爱好者想追踪训练效果是慢性病患者需要记录日常指标还是单纯想更了解自己的身体状态OHA都试图提供一个简单、私密且智能的起点。它的使用门槛被设计得很低——像聊天一样记录但背后的数据架构和AI能力却足够扎实能随着你的数据积累和AI技术的发展提供越来越有价值的洞察。2. 核心设计哲学为什么OHA要这么设计在动手写代码之前我花了很长时间思考这个系统的根基应该是什么。市面上很多健康类应用其设计逻辑是“功能驱动”或“服务驱动”而OHA选择了一条不同的路“数据与隐私驱动”。这决定了整个项目的技术选型和架构面貌。2.1 隐私优先数据不出你的门健康数据可能是我们最敏感的个人信息之一它包含了体重变化、睡眠习惯、用药记录甚至症状描述。把这些数据上传到第三方云端服务器意味着你将数据的控制权完全交给了服务提供商。数据泄露、服务器被黑、甚至公司政策变更导致服务关闭都是潜在的风险。因此OHA的第一个也是最重要的设计原则就是私有化部署。整个系统运行在你自己的电脑、NAS或者云服务器上。所有数据从你聊天记录里的一句“头疼”到AI分析生成的周报都存储在一个本地SQLite数据库文件中。这个.db文件你可以随意备份、加密、甚至物理隔离。没有数据会未经你的允许离开你的设备。这意味着你需要付出自己维护服务器的成本主要是电费和网络但换来的是对数据的绝对掌控。这是一种权衡但对于健康数据我认为这种权衡是值得的。2.2 永久保留为未来的AI保存今天的“真相”大多数应用为了性能和存储成本考虑会对历史数据进行归档、压缩甚至删除。但对于健康分析而言时间本身就是最重要的维度。单独看某一天的体重毫无意义但连续一年的体重曲线就能清晰反映生活方式的改变。更关键的是当前AI对健康数据的分析能力比如从一句“没精神”推断出可能与睡眠不足和饮食有关可能只是及格水平。但三年后更强大的AI模型或许能从同样的历史对话中提前识别出某种潜在健康风险的早期模式。所以OHA采用了**“原始消息永久存储永不删除”**的策略。所有你发送的原始文本、时间戳、通道信息都被完整保存。这些原始消息是“事实之源”Source of Truth。即使当前的分析提示词不够完美导致提取的数据有偏差未来我们也可以基于这些原始的、未经篡改的聊天记录用更好的模型和提示词重新分析一遍从而获得更准确的洞察。这相当于为你未来的健康AI保存了一份高质量的训练和推理素材。2.3 零硬编码用提示词而不是代码定义健康逻辑传统健康软件里充满了硬编码的逻辑BMI超过24就是超重每日饮水量要达2000毫升睡眠少于7小时就是不足。这些标准是普适的但未必是个性化的。一个健身运动员的“健康”BMI和一个办公室职员的“健康”BMI可能完全不同。OHA选择将所有这些判断逻辑都交给大语言模型通过提示词Prompt来驱动。代码层只负责最基础的基础设施如何存储数据、如何连接通信通道、如何调度任务。至于“从‘中午吃了排骨饭’这句话里提取热量和营养信息”、“判断用户最近一周睡眠趋势是否恶化”、“结合花粉季节和用户过敏史给出建议”这些全部由AI根据我们编写的提示词来完成。这样做带来了巨大的灵活性模型升级即能力升级当GPT-5、Claude-4发布时我只需要更换API的模型参数你的健康顾问就会立刻变得更聪明、更细致无需修改任何一行业务代码。迭代成本极低发现AI对某种症状的分析不准我不用发版更新客户端只需要优化一下对应功能的提示词所有用户的分析质量立刻得到提升。高度个性化理论上可以为不同用户配置不同的提示词集。例如为糖尿病患者强化血糖相关数据的关注度为孕妇调整体重增长的分析标准。2.4 统一入口从“随手记”到“全景图”最终目标是建立一个统一的健康数据枢纽。理想状态下Apple Health、小米运动、华为健康、甚至纸质体检报告OCR后的数据都能汇聚到OHA中。目前我们通过最自然的方式启动这个数据积累过程聊天。你不需要打开一个复杂的表单选择日期、填写数值。就像给朋友发消息一样告诉你的AI健康助手“昨晚睡了6个半小时但醒了两次”、“下午跑步5公里感觉有点喘”、“今天眼睛特别干”。AI会从中提取结构化信息并与历史数据关联。虽然当前版本主要支持手动聊天输入和Web界面但“多源数据汇聚”的架构已经预留这是未来扩展的核心方向。3. 技术栈选型与架构解析选择一个轻量、高效、现代的技术栈对于个人部署和维护的项目至关重要。OHA的每一个技术选型都围绕着“简单”、“快”和“够用”这三个原则。3.1 运行时与语言为什么是Bun和TypeScriptBun这是一个新兴的JavaScript运行时但它不仅仅是Node.js的替代品。我选择Bun的核心原因是它的“全家桶”特性和极致的启动速度。它内置了打包器、测试运行器、包管理器bun install的速度快得惊人并且原生支持TypeScript和JSX。对于OHA这样一个包含前端Vue和后端API服务的全栈项目使用Bun可以极大简化工具链bun run dev一条命令就能拉起前后端开发体验非常流畅。此外Bun的SQLite驱动性能也非常优秀直接满足了本项目核心的数据库需求。TypeScript在涉及数据模型如健康记录、用户档案和复杂AI交互逻辑的项目中类型安全不是奢侈品而是必需品。TypeScript能在编译期捕捉大量潜在的错误比如错误地给“体重”字段赋值一个字符串或者调用一个不存在的AI工具函数。这对于长期维护和团队协作如果未来有的话的价值是巨大的。Drizzle ORM与TypeScript的集成堪称完美能实现从数据库表结构到前端类型的端到端类型安全。3.2 数据层SQLite与Drizzle ORM的轻量组合数据存储是隐私优先原则的基石选择SQLite是自然而然的事。SQLite它是一个服务器进程只是一个磁盘文件。这意味着备份就是复制一个文件迁移就是移动一个文件无比简单。虽然它在高并发写入场景下可能不如PostgreSQL但对于个人或家庭级别的健康数据记录每秒几次写入顶天了它的性能绰绰有余。*.db文件的可移植性和自包含性完美契合“私有化部署”和“数据主权”的理念。Drizzle ORM这是一个新兴的ORM它的设计哲学是“如果它可以在SQL中完成就应该在SQL中完成”。与一些重度抽象、学习曲线陡峭的ORM不同Drizzle的API非常接近原生SQL同时提供了极佳的类型推导。它的schema定义方式清晰直观并且能生成高效的迁移文件。对于OHA这种表结构相对稳定但未来可能演进的项目Drizzle在类型安全和开发效率之间取得了很好的平衡。3.3 AI层通过pi-ai实现多模型无感切换AI能力是OHA的“大脑”但我不想把用户锁定在某一个特定的模型提供商如OpenAI上。一方面不同用户可能有不同的偏好和可访问性例如国内用户访问Claude可能不便另一方面多模型支持也是应对某个服务商API不稳定或价格变动的技术对冲。我选择了pi-ai这个库作为LLM的抽象层。它提供了一个统一的接口背后可以连接Anthropic、OpenAI、智谱、Google、Mistral等几乎所有主流的大模型API。在OHA的配置中你只需要设置LLM_PROVIDER和LLM_MODEL以及对应的API Key代码中的AI调用逻辑完全不用改变。这种设计使得“换脑子”变得异常简单。今天你用Claude-3.5 Sonnet觉得分析得很到位明天你想试试GPT-4o-mini看看成本只需要修改两行环境变量重启服务即可。实操心得在实际测试中不同模型对同一提示词的反应差异很大。例如在提取“中午吃了排骨饭”的营养信息时有的模型会直接估算热量和宏观营养素有的则会追问“排骨是红烧的还是清炖的饭吃了大概几两”。因此提示词的编写需要有一定的鲁棒性或者针对你主要使用的模型进行微调。项目目前主要使用智谱GLM模型进行开发和测试因其对中文语境和本土化健康概念理解较好。3.4 前后端与通信全栈的轻量组合后端框架 (Hono)这是一个为边缘计算设计的超轻量级Web框架。它的API设计优秀性能出色而且非常小巧。对于OHA这种API路由不算特别复杂的项目Hono比Express或Nest.js更简洁没有历史包袱与Bun的兼容性也极好。前端框架 (Vue 3 Vite)选择Vue 3是因为其组合式API对于构建复杂的交互界面如健康数据图表、聊天界面非常直观。Vite作为构建工具提供了闪电般的冷启动和热更新与Bun的开发模式契合。通信通道 (Channels)这是架构中一个关键抽象层。channels/目录下的适配器将不同的消息来源微信、QQ、WebSocket统一成内部可处理的“用户消息”。无论你从哪个入口发来“我头疼”后端处理逻辑都是一样的。这为未来接入更多平台如Telegram、Slack铺平了道路。3.5 核心架构目录解读看一下src/的核心目录结构就能理解OHA是如何组织的features/这是业务功能的核心。每个健康功能如diet饮食、sleep睡眠都是一个独立的模块包含自己的数据存储逻辑store、AI工具定义tools和专用的提示词prompt。这种模块化设计使得添加一个新健康数据类型比如“血糖”变得非常容易新建一个feature实现存储、工具和提示词即可。agent/与bot/这是AI智能体的核心调度系统。agent/负责管理所有可用的工具来自各个feature并根据AI的请求调用正确的工具。bot/则为每个连接的用户维护一个独立的AI智能体实例保存其会话状态和记忆实现多用户隔离。prompts/存放所有系统级的提示词例如AI的“核心人格”设定“你是一个专业、细心且鼓励式的健康顾问”、行为规则、以及各功能模块提示词的组装逻辑。heartbeat/与cron/这是实现“主动关怀”的引擎。heartbeat是一个定时触发的AI任务它会扫描用户近期状态由AI判断“用户已经三天没记录饮食了是不是该问候一下”或者“用户上周提到眼睛干涩今天花粉指数高需要提醒吗”。cron则处理更确定性的定时任务如“每晚9点提醒吃药”。这种架构确保了关注点分离数据流清晰消息从通道进入 - 路由到对应用户的Bot - Bot的Agent根据消息内容和历史决定调用哪些Feature的工具 - 工具执行存储数据或查询数据并返回结果 - Agent将结果格式化为自然语言回复 - 通过原通道返回给用户。4. 从零开始私有化部署与配置详解理论说了这么多现在我们来动手把你自己的OHA服务跑起来。整个过程大约需要15-30分钟。4.1 环境准备安装BunOHA的核心依赖是Bun。访问 bun.sh 官网根据你的操作系统选择安装方式。通常在Mac/Linux上一条命令即可# 使用 curl 安装 curl -fsSL https://bun.sh/install | bash安装完成后在终端输入bun --version验证。确保版本在1.0以上。4.2 获取代码与安装依赖接下来克隆项目仓库并安装依赖。依赖安装是Bun的强项速度非常快。# 克隆项目代码 git clone https://github.com/yaotutu/open-health-agent.git cd open-health-agent # 使用 bun 安装所有依赖 (包括前后端) bun install这个命令会读取package.json安装项目运行所需的所有Node模块。你会注意到这里没有分别运行npm install和npm run client-install因为Bun统一管理了前后端的依赖。4.3 关键一步配置环境变量OHA的所有配置都通过根目录下的.env文件管理。你需要创建这个文件并填入关键信息。# 在项目根目录复制提供的示例配置文件 cp .env.example .env # 然后编辑 .env 文件用文本编辑器打开.env文件以下是最关键的配置项# 服务器设置 PORT3001 # API服务端口可自定义 DB_PATH./data/oha.db # SQLite数据库文件路径建议保持默认 # 核心LLM配置 LLM_PROVIDERanthropic # 或 openai, zai, google 等 LLM_MODELclaude-3-5-sonnet-20241022 # 对应提供商的具体模型名 # 根据你选择的 LLM_PROVIDER设置对应的 API Key ANTHROPIC_API_KEYsk-ant-xxx... # 如果 PROVIDERanthropic # OPENAI_API_KEYsk-xxx... # 如果 PROVIDERopenai # ZAI_API_KEYxxx... # 如果 PROVIDERzai (智谱) # 心跳间隔毫秒默认15分钟检查一次用户状态 HEARTBEAT_INTERVAL_MS900000 # 日志级别 LOG_LEVELinfo关于LLM配置的深度解析这是整个项目能“智能”起来的核心。你需要一个LLM API的访问权限和相应的Key。对于国际用户Anthropic(Claude) 和OpenAI(GPT) 是成熟稳定的选择。在.env中设置LLM_PROVIDERanthropic然后将你在Anthropic控制台获取的API Key填入ANTHROPIC_API_KEY即可。模型名可以在提供商文档中查到。对于国内用户访问国际服务可能存在不便。智谱AIZ.ai是一个非常好的替代选择。它提供了对标GPT-4级别的GLM系列模型对中文支持原生优秀且API调用稳定。你需要注册智谱开放平台获取API Key然后设置LLM_PROVIDERzai和LLM_MODELglm-4或glm-5并将Key填入ZAI_API_KEY。项目作者主要使用此模型进行测试兼容性最有保障。其他提供商如Google Gemini、Mistral、Groq等理论上只需按格式配置即可使用但可能需要根据其API特性微调提示词。重要提示API Key是高度敏感信息务必确保.env文件不被提交到公开的Git仓库。项目中的.gitignore文件已经默认忽略了.env。4.4 启动服务与初始化数据库配置完成后启动服务就非常简单了。# 开发模式启动同时启动后端API和前端开发服务器 bun run dev第一次运行这个命令时会发生以下几件事Bun会启动后端Hono服务器运行在http://localhost:3001。Bun会同时启动Vite前端开发服务器运行在http://localhost:5173。后端服务会检查DB_PATH指定的SQLite数据库文件是否存在。如果不存在Drizzle ORM会自动根据代码中定义的Schema创建数据库和所有表结构。你会在项目根目录下看到一个新生成的data/文件夹里面包含oha.db文件。这个过程完全自动化无需你手动运行任何数据库迁移命令。只有当未来项目版本升级数据库表结构有变更时你才需要运行bun run db:push来同步Schema。4.5 绑定你的聊天渠道服务启动后打开浏览器访问http://localhost:5173。你会看到OHA的Web管理界面。这里也是你绑定聊天渠道的入口。方式一Web界面直接交互这是最简单的开始方式。在Web界面的聊天框中你就可以直接像使用ChatGPT一样与你的健康助手对话例如输入“记录一下今天体重70.5公斤”。所有记录会直接保存到本地数据库。方式二绑定微信功能更完整Web界面提供了微信绑定功能。点击“微信”标签页用手机微信扫描弹出的二维码。扫码后你的微信就成为了一个“机器人”好友。之后你可以直接在微信里像跟朋友聊天一样给它发送健康信息。这是最推荐的使用方式因为它无缝融入你的日常通讯记录成本最低。方式三绑定QQ Bot如果你更常用QQ过程类似。你需要先前往QQ开放平台申请一个机器人获得App ID和App Secret然后在Web界面的QQ标签页填入完成绑定。方式四通过WebSocket连接开发者/第三方集成对于开发者或者你想自己开发一个客户端可以直接连接ws://localhost:3001/ws这个WebSocket端点按照定义好的协议进行通信。这为深度定制打开了大门。绑定后的隐私提醒无论是微信还是QQ绑定过程只是建立了你的聊天工具与本地OHA服务之间的通信链路。所有消息内容都只在你的本地服务器和你的聊天工具之间传输不会经过任何第三方中转服务器。你的健康数据依然安全地躺在你的oha.db文件里。5. 核心功能实操像聊天一样管理健康服务跑起来了我们来实际体验一下OHA的核心功能。记住它的设计理念是“无感记录智能分析”所以你完全不需要学习任何复杂的操作。5.1 聊天式记录自然语言的力量打开你已绑定的微信找到你的OHA机器人尝试发送以下任意一条消息“早上称重71.2公斤。”“昨晚大概12点睡早上7点醒的中间好像醒了一次。”“午餐吃了一份鸡胸肉沙拉一杯美式咖啡。”“下午去健身房练了胸卧推4组感觉状态不错。”“今天鼻炎好像有点犯了鼻子不太通气。”发送后观察AI的回复。它不会只是简单地说“好的已记录”。你会看到类似这样的回复“已为你记录体重71.2公斤。对比三天前的70.8公斤略有上升最近饮食和运动有什么变化吗保持关注哦。”“记录到睡眠时长约7小时。你提到中途醒来一次最近睡眠连续性似乎有波动建议睡前减少屏幕时间试试看。”“已记录午餐鸡胸肉沙拉和黑咖啡。这是一顿高蛋白、低脂的优质午餐估算热量约350大卡。晚餐可以适当补充一些复合碳水。”“记录了一次胸部训练。力量训练有助于提升代谢和体能记得训练后及时补充蛋白质帮助肌肉恢复。”“已记录‘鼻炎’症状。当前是春季花粉季如果是过敏性鼻炎建议注意关窗外出可佩戴口罩。症状持续或加重请及时就医。”你会发现AI做了三件事信息提取与结构化从你的自然语言中准确识别出数据类型体重、睡眠、饮食、运动、症状和关键数值/描述。数据存储将这些结构化数据存入SQLite数据库对应的表中。上下文分析与即时反馈结合你有限的历史数据如果有的话给出一个简短、相关且有鼓励性的反馈或建议。这就是“聊天式记录”的精髓你以最自然的方式提供信息AI负责完成所有繁琐的结构化工作并即时给你一个正反馈形成记录的健康闭环。5.2 数据类型的深度解析OHA目前支持9大类健康数据每一类在数据库中都对应着精心设计的表结构以确保数据的可分析性。数据类型核心字段与设计考量身体数据weight(体重),body_fat_rate(体脂率),bmi(BMI)。BMI通常由系统根据体重和用户档案中的身高自动计算避免重复输入。饮食记录food_items(食物列表),calories(估算热量),protein/carbs/fat(宏量营养素),meal_type(早/午/晚/加餐)。AI会尝试从描述中估算营养值这对于非精确计量饮食已足够发现趋势。运动记录activity_type(运动类型),duration_minutes(时长),calories_burned(消耗),avg_heart_rate(平均心率),distance_km(距离)。类型和时长是核心其他字段AI会尽力从描述中提取或合理估算。睡眠记录sleep_duration_minutes(总时长),quality_score(自评质量),bedtime/waketime(时间点),deep_sleep_minutes(深睡时长)。时间点用于分析作息规律性。症状记录description(描述),severity(轻度/中度/重度),body_part(身体部位),related_record_ids(关联记录)。related_record_ids是一个强大设计例如AI可以将“运动后膝盖疼”的症状记录与之前“跑步10公里”的运动记录自动关联起来。用药记录medication_name(药品),dosage(剂量),taken_at(服用时间),is_stopped(是否停药)。支持标记停药对于追踪疗程非常重要。慢性病追踪condition_name(疾病名),status(活跃/缓解/稳定),diagnosed_date(确诊日期)。用于长期健康管理背景。健康观察observation(自由文本)。一个“杂物抽屉”记录任何不适合上述分类但又重要的信息如“今天心情很好”、“体检报告显示胆固醇偏高”。用户档案height,birth_year,gender,medical_history,allergies,dietary_preferences,health_goals。这是AI进行个性化分析的基石在Web界面中一次性配置好。实操心得如何让AI理解得更准初期使用AI的提取可能不够精确。你可以通过“微调”你的说话方式来引导它。例如模糊描述“中午吃了好多。”- AI可能无法记录任何具体数据。优化描述“午餐一碗米饭一份青椒肉丝一碗番茄蛋汤。”- AI更有可能识别出食物种类并进行粗略的热量估算。带数值描述“晚餐估计吃了600大卡左右主要是蔬菜和鸡肉。”- AI会直接记录你提供的热量估值并补充食物类型。记住我们的首要目标是养成记录的习惯数据的精确度可以随着AI模型的升级和你的描述优化逐步提高。即使最初只有“吃了排骨饭”这样的记录长期积累下来你也能看出“每周吃几次外卖”这样的模式。5.3 智能特性体验不止是被动记录OHA的“智能”体现在它的主动性上。1. 主动关怀Heartbeat这是由heartbeat/模块驱动的。服务启动后一个后台定时器默认每15分钟会触发“心跳”任务。这个任务会扫描所有用户最近一段时间比如24小时的活动记录。将用户状态如“最近一次记录是2天前”、“最近3条记录都提到疲劳”汇总给AI。由AI判断“这个用户已经两天没说话了是不是该发个消息问候一下鼓励他记录”或者“用户最近连续记录疲劳结合天气变化可以提醒他注意休息和保暖”。如果AI认为有必要它会生成一条关怀消息并通过绑定的通道微信发送给你。这彻底改变了传统App“等你来输入”的模式变成了一个会主动关心你的伙伴。这个判断逻辑完全由提示词控制你可以修改提示词来调整AI的“关怀敏感度”。2. 定时任务Cron对于规律性事件比如每日服药提醒OHA提供了标准的定时任务功能。你可以在Web界面或通过聊天未来计划设置“每天晚上9点提醒我吃降压药”。到点后AI会准时推送提醒。这比手机自带的闹钟更智能因为它是在对话上下文中提醒你可以直接回复“吃过了”或“今天忘了现在补上”AI会同步更新用药记录。3. 记忆系统OHA为每个用户维护着两种记忆长期记忆存储在数据库中包括你的用户档案、重要的健康事实如“对花粉过敏”、以及AI总结出的你的偏好如“不喜欢吃西兰花”。这些信息会在相关的分析中被持续引用。短期记忆/会话记忆由于LLM有上下文长度限制不可能把过去所有的聊天记录都塞进每次对话。因此OHA采用了“摘要”策略。当一次对话较长时AI会自动将之前的对话内容总结成一段简短的摘要在后续对话中将这份摘要和最近的几条消息一起送给AI从而保持对话的连贯性实现“它记得你刚才说过什么”。6. 深入原理提示词工程与Agent工作流OHA的“智能”并非魔法而是由精心设计的提示词和稳定的Agent工作流共同实现的。理解这部分你就能真正掌控你的AI健康助手甚至定制它。6.1 模块化提示词架构所有提示词都放在src/prompts/目录下采用模块化设计。system/存放核心系统提示词。最重要的是core.txt它定义了AI的“人设”和行为准则。例如“你是一个专业、细心、富有同理心且鼓励式的个人健康顾问。你的目标是帮助用户轻松记录健康数据并从长期视角提供温和、个性化的见解和建议。你绝不提供医疗诊断总是建议用户对于严重的健康问题咨询专业医生。你的语气应友好、自然像一位关心你的朋友。”这个核心提示词会在每次AI调用时被加载奠定了所有交互的基调。features/每个健康功能模块都有自己的提示词文件。例如diet.prompt.txt里包含了如何从用户消息中提取饮食信息、如何估算热量、如何给出饮食建议的具体指令。tools/这里定义了AI可以使用的“工具”的描述。当AI认为需要执行某个操作如“记录饮食”、“查询最近一周的睡眠”时它会根据这里的描述来匹配和调用后端实际实现的工具函数。这种模块化使得管理和迭代提示词变得非常清晰。如果你想优化饮食分析只需修改diet.prompt.txt如果你想调整AI的说话风格只需修改core.txt。6.2 Agent的思考与行动循环当用户发送一条消息“中午吃了排骨饭”后后台发生了什么消息接收与路由微信通道适配器收到消息将其转化为内部事件路由到对应用户的Bot实例。构造对话上下文Bot从数据库中加载该用户的近期对话历史摘要、长期记忆档案、偏好等连同用户的新消息一起组装成发送给LLM的“对话上下文”。AI思考与工具调用这个上下文被送入LLM。由于系统提示词中说明了“你可以使用工具”LLM会分析用户意图。它识别出这是一条“饮食记录”于是决定调用record_diet这个工具。它在回复中返回一个特殊的结构化数据指明要调用的工具名和参数如{“tool”: “record_diet”, “food_description”: “排骨饭”}。工具执行Agent解析AI的返回找到对应的record_diet工具函数位于src/features/diet/tools.ts并执行。这个函数会 a. 可能调用AI子过程利用diet.prompt.txt进一步提取排骨饭的细节数量、烹饪方式。 b. 将结构化数据食物“排骨饭”估算热量约650大卡餐次“午餐”存入diet_records表。 c. 可能查询用户最近的饮食记录计算一些简单统计。生成自然语言回复工具执行的结果成功记录、提取的数据、关联的统计被返回给Agent。Agent再次将这些结果作为新上下文请求LLM“用户说了‘中午吃了排骨饭’你已经调用了工具并记录了这些数据现在请生成一段给用户的友好回复。” LLM会生成如“已为你记录午餐排骨饭估算热量约650大卡。看起来是一顿丰盛的午餐晚餐可以搭配一些清淡的蔬菜哦。”的回复。回复发送与记忆更新最终的回复通过微信通道发送给用户。同时系统会将本轮完整的交互用户消息、AI思考、工具调用、结果、最终回复压缩摘要更新到用户的会话记忆中供下次对话使用。这个“接收 - 思考 - 调用工具 - 执行 - 生成回复”的循环是AI Agent典型的工作流。OHA的架构清晰地将这个流程实现出来并且每个环节都是可观察、可调试的。6.3 如何自定义与扩展理解了原理你就可以动手定制你的OHA了。1. 调整AI性格与规则直接修改src/prompts/system/core.txt。比如如果你希望AI更严谨、更少用感叹号或者增加一条“永远优先询问用户症状的持续时间”在这里修改即可。修改后重启服务生效。2. 优化现有功能假设你觉得AI对运动强度的判断不准你可以修改src/features/sport/sport.prompt.txt。在提示词中更详细地定义不同运动类型如“慢跑”、“高强度间歇训练”对应的强度系数或者提供更具体的描述示例。你甚至可以在工具函数sport/tools.ts中加入调用外部API如计算MET值的API来获取更精确的热量消耗。3. 添加一个新健康数据类型这是更高级的扩展。假设你想增加“情绪记录”。第一步在src/features/下创建mood目录。第二步在mood/下创建store.ts用Drizzle定义mood_records表字段如mood_type(开心/平静/焦虑等)、intensity、note。第三步在mood/下创建tools.ts实现record_mood和query_mood等工具函数。第四步在mood/下创建mood.prompt.txt编写如何从用户消息如“今天心情有点低落”中提取情绪数据以及如何分析情绪与睡眠、运动等关联的提示词。第五步在src/agent/tools.ts中注册这个新工具。第六步重启服务。现在你就可以对AI说“今天心情有点低落”它会自动记录并可能关联你最近的睡眠数据进行分析。这种扩展方式完全遵循了“数据提示词驱动”的原则无需修改核心调度代码。7. 常见问题、排查与优化指南在实际部署和使用中你可能会遇到一些问题。这里汇总了一些常见情况及解决方法。7.1 部署与启动问题Q1: 运行bun run dev时报错提示端口被占用。A1: 默认端口是3001后端和5173前端。你可以修改.env中的PORT变量来更改后端端口。前端端口修改需要在vite.config.ts中调整。或者先找出占用端口的进程并关闭它在Linux/Mac上用lsof -i :3001在Windows上用netstat -ano | findstr :3001。Q2: 启动成功但访问http://localhost:5173前端页面空白或报错。A2:检查后端API服务是否真的在运行。访问http://localhost:3001/health应该返回{status:ok}。检查浏览器控制台F12的Network标签看前端是否成功加载了JS资源或者是否有CORS错误。OHA的前后端在开发模式下通过Vite代理连接通常不会有CORS问题如果遇到请检查vite.config.ts中的代理配置。尝试清除浏览器缓存或使用无痕模式。Q3: 微信/QQ扫码绑定失败。A3:确保你的服务能被外网访问微信/QQ机器人需要回调你的服务器。如果你在本地电脑运行需要做内网穿透如使用ngrok、frp等工具将localhost:3001暴露到一个公网HTTPS地址并在对应的Bot配置中如pure-wechatbot的配置填写这个公网回调地址。检查日志查看服务启动时的日志确认微信/QQ通道的适配器是否成功初始化以及是否打印了正确的二维码或登录URL。确认依赖确保pure-wechatbot和pure-qqbot这些通道依赖已正确安装。7.2 AI功能相关问题Q4: AI回复慢或者经常超时。A4:网络问题首先检查你的服务器到LLM API服务如智谱、OpenAI的网络连接是否稳定。可以尝试用curl或ping测试。模型太大如果你使用的是GPT-4或Claude-3.5-Sonnet这类大型模型推理速度本身就会慢于小模型。可以尝试切换到更快的模型如GPT-4o-mini、Claude-3.5-Haiku或智谱的GLM-4-Flash。上下文过长如果用户的历史对话很长每次都会携带大量上下文会导致API调用缓慢且昂贵。OHA的摘要机制就是为了缓解这个问题。检查src/session/下的摘要逻辑看是否正常工作。提示词过于复杂过于冗长或复杂的提示词会增加AI的思考时间。尝试优化提示词使其更简洁、指令更明确。Q5: AI提取信息不准确比如把“散步”识别成“跑步”。A5:优化提示词这是最主要的手段。去对应的功能提示词文件如src/features/sport/sport.prompt.txt中增加更明确的示例和规则。例如明确写出“如果用户描述中包含‘慢走’、‘散步’、‘溜达’等词则运动类型为‘步行’如果包含‘快跑’、‘跑步’、‘慢跑’等词则类型为‘跑步’。”提供更明确的输入用户也可以调整表达方式如说“散步30分钟”而不是“走了半小时”。切换或微调模型不同模型的理解能力不同。可以尝试更换一个在中文或特定领域表现更好的模型。对于复杂场景可以考虑在调用工具前增加一个“澄清”步骤让AI先反问用户确认细节。Q6: 主动关怀Heartbeat没有触发。A6:检查配置确认.env中HEARTBEAT_INTERVAL_MS的值不是0或过大。默认900000毫秒15分钟是合理的。检查日志启动服务时日志中应该会打印“Heartbeat scheduler started”。在心跳触发时也会有相应的日志。查看日志级别是否设置为info或debug。理解触发逻辑主动关怀不是定时群发消息。它是AI基于对用户近期状态的分析后“决定”是否发送。如果用户最近记录很频繁AI可能认为不需要问候。你可以修改src/heartbeat/下的提示词降低AI发送关怀消息的“阈值”。7.3 数据与备份Q7: 数据库文件 (data/oha.db) 越来越大怎么办A7: SQLite数据库文件会随着使用增长这是正常的。由于OHA设计为“永不删除”原始数据文件会持续增大。你需要定期备份这个文件。手动备份直接复制oha.db文件到其他安全位置如加密云盘、外部硬盘。自动化备份可以写一个简单的脚本Shell或Python定期如每天复制数据库文件并压缩归档。由于SQLite在备份时允许读取可以在服务运行时直接复制但为了数据一致性建议在低峰期或短暂停止服务时进行。数据导出未来可以考虑开发一个数据导出功能将数据以CSV或JSON格式导出方便用其他工具分析。Q8: 我想迁移服务器如何操作A8: OHA的迁移极其简单得益于其“单文件存储”设计。在新服务器上按照“快速开始”步骤安装环境、克隆代码、安装依赖。将旧服务器上的整个data/目录或者至少是oha.db文件复制到新服务器的项目对应位置。将旧的.env配置文件复制到新服务器注意修改其中可能与环境相关的路径如果没改则不用动。在新服务器上运行bun run dev或bun run server启动服务。重新在Web界面绑定你的微信/QQ因为Bot的登录状态通常与本地存储的token有关迁移后需要重新登录。你的所有历史数据都完整地保存在oha.db文件中会随之迁移。7.4 安全与隐私强化Q9: 如何让我的OHA服务更安全A9: 私有化部署本身已是最大安全保障但你还可以服务器安全确保运行OHA的服务器系统及时更新补丁使用强密码关闭不必要的端口。网络隔离如果不需从外网访问仅在家庭内网使用那么风险极低。如果需要外网访问以便在外使用微信Bot务必使用HTTPS。可以通过Nginx反向代理并配置SSL证书来实现。数据库加密SQLite本身不提供加密。对于极度敏感的数据可以考虑使用支持加密的SQLite版本如SQLCipher但这需要修改代码中的数据库驱动。环境变量保护确保.env文件权限设置为仅当前用户可读chmod 600 .env并且绝不泄露其中的API Key。Q10: 我的API Key存在.env里安全吗如果泄露了怎么办A10: 在私有服务器上.env文件是相对安全的存储方式远好于将Key硬编码在代码中。但如果服务器被入侵Key仍会泄露。最佳实践是为OHA创建一个专用的API Key并设置使用限额如每月花费上限。定期轮换更换API Key。如果使用云服务商的LLM查看其控制台是否有IP白名单功能将Key限制为只能从你的服务器IP调用。一旦怀疑泄露立即在对应平台撤销旧的Key生成新Key并更新.env文件。8. 未来展望与进阶玩法OHA作为一个开源项目其生命力在于社区的扩展和个人的定制。除了基础的健康记录它的架构允许它向更多有趣的方向发展。1. 集成更多数据源这是最直接的扩展。可以开发“连接器”Connectors来同步其他平台的数据Apple Health / Google Fit通过导出XML或使用用户授权后的API将步数、心率、睡眠等数据定期同步到OHA。智能硬件通过厂商API如Withings、Garmin或蓝牙直接连接导入体脂秤、血压计的数据。电子病历/体检报告通过OCR技术识别体检报告图片结构化提取关键指标如血脂、血糖并记录。2. 更强大的分析与可视化当前的分析主要基于LLM的即时推理。可以引入时序数据分析使用简单的统计库如simple-statistics计算移动平均、环比变化等将结果提供给LLM让它的周报或总结更有数据支撑。基础图表在Web前端集成ECharts或Chart.js自动生成体重曲线图、睡眠质量趋势图等。关联性分析通过数据分析尝试发现症状与饮食、运动与睡眠之间的潜在关联例如“每次喝咖啡的第二天深睡时间减少”并提示用户注意。3. 个性化健康计划与干预基于长期数据AI可以扮演更积极的角色自动生成微习惯建议分析用户数据后提出“未来一周尝试每天提前15分钟睡觉”这样的具体、可执行建议。用药依从性追踪对于需要长期服药的用户AI不仅可以提醒还可以分析记录生成服药依从性报告。与智能家居联动通过Home Assistant或IFTTT等平台实现“当AI检测到用户连续晚睡自动调暗卧室灯光并播放助眠音乐”的场景。4. 模型微调与本地化部署对于高级用户可以探索提示词优化社区建立一个共享提示词库用户可以导入别人优化好的“饮食分析”、“运动建议”提示词模块。本地模型部署随着开源LLM如Llama、Qwen能力的提升可以将模型部署在本地显卡上实现完全离线的、零API成本的健康助手。这需要较强的硬件和技术知识但无疑是隐私的终极解决方案。Open Health Agent的旅程才刚刚开始。它从一个简单的想法出发——拿回自己健康数据的控制权并用AI让它产生价值。它的代码是开源的它的架构是开放的它的未来取决于每一个使用它、改进它的你。无论是提交一个Bug修复开发一个新的数据连接器还是只是分享你使用它管理健康的故事都是在共同构建一个更私密、更智能的个人健康未来。