Hermes Agent原生不内置协同过滤模块，需通过Surprise库集成实现推荐能力：先隔离环境安装兼容版本，再开发适配器桥接ACP数据流，结合离线训练+FastAPI在线服务，将结果注入ACP响应并联动技能白名单校验。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望为Hermes Agent扩展个性化推荐能力，但缺乏现成的协同过滤或矩阵分解支持，则可能是由于其原生架构未内置推荐系统模块。以下是将Surprise库集成至Hermes Agent环境并实现端到端推荐流程的实操步骤：
一、确认Surprise兼容性与依赖隔离
Surprise要求Python 3.8+且不兼容PyTorch 2.4+的某些ABI版本，直接全局安装易引发Hermes Agent核心组件（如hermes-cli、ACP transport层）运行异常。需通过虚拟环境或容器化方式实现运行时隔离，确保推荐模块与主Agent进程互不干扰。
1、创建独立Python虚拟环境：
python3 -m venv /opt/hermes-surprise-env
2、激活环境并升级pip：
source /opt/hermes-surprise-env/bin/activate && pip install --upgrade pip
3、安装Surprise指定兼容版本（避免与Hermes依赖冲突）：
pip install scikit-learn==1.3.2 numpy==1.24.4 surprise==1.1.3
4、验证Surprise基础功能：
python -c "from surprise import SVD; print('Surprise loaded successfully')"
二、构建推荐数据桥接适配器
Hermes Agent默认使用JSON-RPC或ACP协议传输会话上下文，而Surprise仅接受pandas DataFrame或内置Dataset格式。需开发轻量级Adapter类，将用户交互日志（如session/prompt事件流）实时转换为Surprise可识别的trainset对象，并支持增量更新。
1、在Hermes Agent插件目录下新建surprise_adapter.py文件：
mkdir -p ~/.hermes/plugins/recommender && touch ~/.hermes/plugins/recommender/surprise_adapter.py
2、定义数据映射逻辑：将ACP session.new事件中的user_id、tool_id、duration_ms字段映射为rating=duration_ms/1000，timestamp字段转为Unix时间戳作为额外特征
3、实现load_from_dataframe方法，调用surprise.Dataset.load_from_df()并传入三列DataFrame（user、item、rating）
4、注册该Adapter为Hermes CLI子命令：
hermes plugin register --name recommender --module surprise_adapter --entrypoint init_recommender
三、配置模型训练与在线服务模式
Surprise模型训练耗时长且内存占用高，不可在Hermes ACP子进程中同步执行。应采用离线训练+在线预测双模架构，训练结果序列化为.pkl文件，由独立FastAPI微服务加载并提供REST接口供HermesGrain调用。
1、编写train_surprise_model.py脚本，加载历史session日志CSV，调用SVD().fit()完成训练
2、将训练好的model对象与algo object一起保存：
import pickle; with open('/opt/hermes/models/svd_v20260417.pkl', 'wb') as f: pickle.dump({'model': trained_algo, 'dataset': trainset}, f)
3、部署轻量FastAPI服务监听8001端口，暴露POST /predict 接口，接收{“user_id”: “u123”, “n”: 5}请求参数
4、在HermesGrain中配置HTTP客户端指向该服务地址，于session/prompt响应前插入recommendation call
四、注入推荐结果至ACP会话流
Surprise输出为(item_id, predicted_rating)元组列表，需将其结构化嵌入Hermes ACP协议的session/prompt响应体中，使前端ExecutorAvatar能识别并渲染为“相关工具建议”卡片。必须复用现有ACP消息schema，禁止新增字段或修改协议版本。
1、修改StdioAcpTransport的response_handler，在原始prompt response字典中添加recommendations键
2、填充recommendations值为JSON数组，每个元素含id（对应tool_id）、score（保留小数点后两位）、reason（固定字符串“基于您近期使用行为推荐”）
3、确保recommendations数组长度≤3，超出部分截断并记录warn日志
4、重启Hermes ACP子进程使变更生效：
hermes service restart --force
五、启用技能白名单联动机制
Surprise可能推荐未授权启用的Skills（如curl、shell_exec），需强制校验推荐项是否存在于Hermes Agent当前启用的Skills白名单中。若不匹配，自动降权至次优候选或返回空数组，防止越权调用。
1、在surprise_adapter.py中引入hermes.config.get_enabled_skills()接口获取运行时白名单
2、对每个predicted item_id执行in操作判断：
if item_id not in enabled_skills: skip_recommendation = True
3、启用白名单校验开关：
hermes config set recommender.whitelist_check true
4、触发一次冷启动推荐测试：
hermes recommend --user u999 --n 3 --force-refresh
