🛒 SMZDM 好价提醒机器人

搜索结果
  ├─ 明确数值价格 ≤ max_price → 直接推送 → 查看详情 / 移除搜索词 / 清除价格阈值
  └─ 其他情况                  → 去重与预筛 → LLM 判断 → 好价反馈 / 配置快捷操作

价格阈值直推不会写入 Deal Memory，也不会用该结果训练偏好；即使本轮 LLM 服务异常，已命中阈值的商品仍会单独尝试投递。

_{当前推荐卡片：价值信号、推荐理由、好价反馈和配置快捷操作同时可见。}

价格阈值命中后直接推送 绕过 LLM 与 Deal Memory，按钮切换为“移除搜索词 / 清除价格阈值”。	完整的 `/search` 命令 查看、添加、精确删除、设置或清除阈值，以及带确认口令的全部清空。
双路判断不一致后的仲裁 展示差异商品、最终选择、争议原因和 Prompt 优化建议。	运行时模型路由 查看 filter / arbiter / draft 最终路由，切换模型、温度并发送测试。
两类反馈、三种配置动作 好价 / 不值进入反馈记忆；不再推荐、库存足够和关注会生成配置草案。	运行状态 查看轮询是否执行中，以及最近开始、完成和成功推送时间。

• 同时轮询综合榜各分类、热卖榜、热评榜、热搜榜，以及自定义关键词搜索；每个来源独立失败不会中断其他来源。
• 在调用 LLM 前先过滤去重记录，避免重复提醒和无效模型开销；默认去重窗口为 24 小时。
• 关键词可设置最高价。搜索结果价格命中阈值时直接推送，不进入 LLM，也不参与 Deal Memory 学习；卡片会改为提供“移除搜索词/清除价格阈值”操作。
• 可选数值预筛选，综合“值”票数、值率、评论和收藏减少低信号候选；也可配置评论数或值票数达到强信号条件时进入 LLM 复核。
• 每轮筛选前重新读取 preference.md、inventory.md 和关键词配置；临时读取失败时沿用上一次成功内容并发送节流告警。

• LLM 同时读取完整购物偏好和库存状态，返回推荐项、推荐理由、品类、决策上下文，以及“本身像好价但因个人条件跳过”的 near-miss。
• 默认使用一次筛选；开启双重判断后执行两次独立筛选。结果不一致时，仲裁 agent 会比较差异、选择更可信的判断并解释原因。
• 仲裁发现偏好规则存在歧义时，会尝试生成 preference.md 修改草案；只有用户在飞书确认后才会写入，无法形成安全草案时仅展示建议。
• near-miss 会在夜间汇总，帮助回查潜在漏推；条目较多时自动附加 Markdown 文件，发送成功后才清空当天记录。

• 开启 Deal Memory 后，LLM 推荐卡片提供“好价/不值”反馈；“不值”可补充原因，再次点击可取消或改判。
• 反馈按商品品类保存。达到最少样本数后，同品类的近期正反例会作为校准案例加入后续筛选，而不是把单次反馈直接固化成永久规则。
• 每日分析达到样本门槛的历史反馈，识别稳定偏好模式并生成配置修改草案；仍需用户确认。连续分析失败达到上限后暂停当天重试，不阻塞 near-miss 汇总。

• 使用企业自建应用的长连接收取消息与卡片回调，无需部署公网回调地址；支持私聊或群聊绑定通知目标。
• 自然语言修改 preference.md 或 inventory.md：先生成带定位、附近原文和增删预览的草案，可回复原预览继续修订，确认后再写入。
• 草案 24 小时后自动失效；应用前会备份原文件并写入审计日志。商品卡片上的“不再推荐/库存足够/关注”同样先生成草案，不会直接改配置。
• /search 系列命令管理关键词和价格阈值；/model 卡片可查看、测试和热切换 filter / arbiter / draft 的连接、模型与 temperature。
• 只有当前绑定用户可以解绑通知目标或操作卡片，重复消息事件会在进程内幂等处理。

• 长时间没有商品推送时发送心跳；启动、停止、重启、配置读取异常和连续轮询失败都会给出飞书提示。
• 好价卡片发送成功后才写入去重和待反馈记忆；部分卡片发送失败时只持久化已送达商品，后续仍可重试失败项。
• 卡片会按飞书组件数和消息体积限制自动拆分；图片上传失败时保留商品图片链接。
• 本地 workspace/ 分别保存运行状态、日志、配置审计和备份，便于排查与回滚。

需要 Python 3.9+。

git clone <repo-url> smzdm_notice
cd smzdm_notice
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
smzdm-notice setup

setup 会创建 .env、llm_models.json、preference.md、inventory.md 和 workspace/ 目录，已有文件不覆盖。

编辑 .env，填写以下必填项：

可选榜单：综合榜-全部、综合榜-电脑数码、综合榜-白菜、综合榜-食品生鲜、综合榜-运动户外、综合榜-家用电器、综合榜-服饰鞋包、综合榜-日用百货、综合榜-母婴用品、综合榜-家居家装、综合榜-办公设备、综合榜-个护化妆、综合榜-本地生活、综合榜-医疗健康、综合榜-图书文娱、综合榜-玩模乐器、热卖榜、热评榜、热搜榜。

SMZDM 配置： 安卓和 iPhone 的签名 key 可能不同，SMZDM_CLIENT_PLATFORM、SMZDM_APP_VERSION、SMZDM_SIGN_KEY 和 SMZDM_USER_AGENT 应来自同一平台和相近 App 版本。请自行从 GitHub 公开仓库的 SMZDM 签到、脚本或 bot 实现中查找当前可用的签名 key 和 UA，例如：

• https://github.com/Cat-zaizai/ZaiZaiCat-Checkin
• https://github.com/enwaiax/smzdm_bot
• https://github.com/hex-ci/smzdm_script

这些值可能随 SMZDM App 版本变化而失效；如果抓取接口返回签名、权限或请求异常，优先检查平台、版本、签名 key 和 UA 是否匹配且仍然有效。

可选配置：

偏好与库存： 编辑 preference.md 写购物偏好，编辑 inventory.md 写库存状态，两者会完整提供给 LLM。

Deal Memory： 设置 DEAL_MEMORY_ENABLED=true 后，推荐卡片会显示「好价/不值」反馈按钮。推送成功的 LLM 推荐会先进入待反馈记录，用户点击反馈后进入长期记忆；夜间汇总前会尝试更新历史决策校准和偏好学习建议。Deal Memory 是辅助功能，连续分析失败达到上限后会放弃当天分析并继续发送 near-miss 夜间汇总。

LLM 多模型路由： setup 会生成 llm_models.json 并默认启用多模型路由。JSON 中只保存 api_key_env，真实密钥继续放 .env，例如 LLM_DEEPSEEK_API_KEY=...。运行时必须有 llm_models.json。

配置分三层：connections 保存 OpenAI 兼容接口连接，defaults 保存默认 connection/model_id/request 参数，agents.filter/arbiter/draft 只写覆盖项；未配置的 agent（包括 draft）会继承 defaults。timeout_seconds/max_retries 可写在 defaults、connection 或 agent 上，优先级为 agent > connection > defaults。运行时内置默认 response_format={"type":"json_object"}，即使 JSON 里省略该字段也会发送；用户可用非空 response_format 对象覆盖。agent request 中字段值为 null 表示继承默认值，不会关闭默认 response_format。

request.extra_body 会按默认或 agent 覆盖原样透传给 OpenAI SDK，项目不校验 provider 字段含义。不同 provider 支持字段不同，例如 BigModel/智谱可用 {"do_sample":false} 降低随机漂移，或用 {"thinking":{"type":"disabled"}} 关闭 thinking；vLLM/SGLang 常见写法是 {"chat_template_kwargs":{"enable_thinking":false}}。

飞书发送 /model 会打开 LLM 模型路由管理卡片，可在卡片中查看当前默认配置和 filter/arbiter/draft 的最终路由，选择作用范围、选择已加载 connection、输入 model_id、设置 temperature、reset agent 覆盖并做测试调用。

热切只修改已加载 connection 下的 defaults 或 agents 覆盖项；新增或修改 base_url/provider/api_key_env、修改 .env 密钥后需要重启。写回使用唯一临时文件和原子替换；多实例同时热切时以后写入者为准。

搜索关键词： 可选创建 search_keywords.json：

{
  "keywords": [
    { "keyword": "AirPods Pro 2", "max_price": 1200 },
    { "keyword": "充电宝" }
  ]
}

关键词也可以完全通过飞书 /search 系列命令维护。max_price 表示“命中后绕过 LLM 直接提醒”的价格，不会过滤掉更高价商品；配置文件只接受带 keyword / max_price 字段的对象条目，重复关键词读取时自动去重。

使用飞书开放平台企业自建应用，长连接模式，无需公网回调。

1. 创建企业自建应用，添加「机器人」能力
2. 复制 App ID 和 App Secret，填入 .env
3. 申请权限：im:message:send_as_bot、im:resource、im:message.reactions:write、私聊 im:message.p2p_msg:readonly、群聊 im:message.group_at_msg:readonly；流式更新还必须开通 cardkit:card:write
4. 事件与回调选择「使用长连接接收事件」，订阅 im.message.receive_v1
5. 卡片回调开启「卡片回传交互」，SDK key 为 card.action.trigger
6. 保存并发布应用

启动后在飞书私聊或群聊 @机器人 发送 /bind 完成绑定。绑定前不会轮询。

卡片使用 JSON 2.0，建议接收端使用飞书 7.20 或以上版本。

流式更新必需权限： 在飞书开放平台的「权限管理」中开通「创建与更新卡片」（cardkit:card:write）。新增权限后需要重新发布应用版本，并确认租户管理员已完成授权，然后重启本服务。该权限用于创建 CardKit 卡片实体、实时更新模型输出并在完成后替换为可交互预览；未授权或 CardKit 调用失败时，机器人会自动回退到静态普通 2.0 卡片，不展示流式内容。

smzdm-notice doctor   # 检查环境配置
smzdm-notice run      # 启动

不在项目目录时加 --root /path/to/smzdm_notice。

也可以用自然语言发给机器人修改偏好或库存（如“某类耗材还剩 3 件”）。机器人会先发预览；可以点击确认/取消，也可以直接回复这张预览补充修改意见。商品卡片上的“不再推荐/库存足够/关注”也走同一套草案确认流程。

nohup（Linux / macOS）：

nohup .venv/bin/smzdm-notice run &

caffeinate（macOS，防止系统休眠）：

caffeinate -i .venv/bin/smzdm-notice run &

systemd（Linux）：

[Unit]
Description=SMZDM Notice Bot
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/smzdm_notice
ExecStart=/opt/smzdm_notice/.venv/bin/smzdm-notice run
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

pip install -e ".[dev]"
pytest -q
ruff check .
ruff format --check .
python -m pyright
tabnanny -q src tests

配置备份与 diff：

smzdm-notice save-config
smzdm-notice diff-config --list
smzdm-notice diff-config
smzdm-notice diff-config 1 2

• 本项目仅供个人学习研究使用，不得用于商业用途。
• 签名算法、签名 key 和 User-Agent 获取方式来源于 GitHub 公开仓库，数据获取方式可能涉及平台服务条款，使用者需自行评估合规性并遵守相关条款。
• 因使用本项目导致的账号风险、数据争议或其他任何损失，开发者不承担责任。
• 如相关平台提出异议，本项目将配合处理。

本项目代码由 AI 编写，开发者仅提供需求描述和方向指导。由于代码完全由 AI 生成，可能存在逻辑缺陷或不够优雅的实现。如果你在使用中遇到问题，或有改进建议，欢迎提 Issue 或 PR。