AI导哈

加密货币资讯推荐系统

一个面向加密货币资讯场景的推荐系统原型，通过多路召回、语义补召回、事件聚类和个性化排序，为用户提供事件级feed。

  • by qinshoudawang
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 qinshoudawang/crypto-mcp

使用说明

Followin-MCP

项目概览

这个项目可以理解成一条面向 crypto 资讯场景的事件级推荐原型：

  • 上游通过 Followin API + adapters.py 拉取原始内容
  • normalizer.py 把原始内容标准化成结构化 ContentItem
  • service.py 在 get_personal_feed 里先做显式多路召回，再做 semantic supplement
  • clustering.py 把多条内容并成同一事件的 EventCluster
  • ranking.py 用多信号 heuristic ranker + MMR rerank 生成个性化 feed

一句话总结：

一个面向 crypto 资讯场景的 Followin MCP 原型：将原始内容标准化成结构化 item，再通过多路召回、语义补召回、事件聚类和个性化排序，产出面向用户的事件级 feed。

目录结构

  • followin_mcp/ Python 包入口
  • followin_mcp/core/ 核心业务逻辑：adapter、model、normalizer、ranking、service
  • followin_mcp/mcp/ MCP server 入口
  • followin_mcp/demo/ 测试 agent 和 Web demo
  • scripts/start_dev.sh 本地一键启动脚本
  • web/ 前端静态资源

核心模块

  • followin_mcp/core/adapters.py Followin API 适配层
  • followin_mcp/core/models.py 数据模型
  • followin_mcp/core/taxonomy_rules.py taxonomy / 规则配置
  • followin_mcp/core/normalizer.py 原始内容标准化、实体抽取、事件类型识别
  • followin_mcp/core/clustering.py 事件聚类
  • followin_mcp/core/ranking.py 用户推荐排序与解释
  • followin_mcp/core/semantic_recall.py embedding 建索引、语义召回、item 相似度
  • followin_mcp/core/service.py 面向 MCP / 应用层的服务入口

请求处理时序

sequenceDiagram
    participant U as MCP client / agent
    participant M as mcp/server.py
    participant S as service.py
    participant A as adapters.py
    participant F as Followin API
    participant N as normalizer.py
    participant SR as semantic_recall.py
    participant C as clustering.py
    participant R as ranking.py

    U->>M: call tool
    M->>S: get_latest / search / get_personal_feed ...

    S->>A: fetch raw content
    A->>F: HTTP request
    F-->>A: raw payload
    A-->>S: raw items

    loop per raw item
        S->>N: normalize(raw)
        N-->>S: ContentItem\nentities / event_type / scores
    end

    S->>SR: enqueue normalized items
    SR-->>S: background indexing

    opt personal feed / semantic supplement
        S->>SR: recall(query, candidate pool)
        SR-->>S: semantic candidates / similarity
    end

    opt personal feed
        S->>C: cluster_same_event(items)
        Note over C: uses item embedding similarity
        C-->>S: EventCluster list
        S->>R: rank_for_user(user, clusters)
        Note over R: uses semantic_match_score
        R-->>S: ranked clusters
    end

    S-->>M: tool payload
    M-->>U: MCP response

处理链路

1. MCP 入口

  • mcp/server.py
    • 暴露 7 个 MCP tools
    • 把 MCP 入参转成 service.py 调用
    • 负责把 ContentItem / EventCluster 序列化成 MCP 返回结构

2. 原始内容获取

  • service.py -> adapters.py
    • get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics 直接透传上游分页能力
    • get_trending_feeds / search_content 直接返回当前快照结果
    • get_personal_feed 会先做显式多路召回和 semantic supplement，再走事件聚类和个性化排序

3. 内容标准化

  • normalizer.py
    • normalize(raw) 把单条原始内容转成 ContentItem
    • 实体抽取来源：
      • tag
      • chain keyword
      • project alias
      • token alias
      • topic alias
      • dynamic alias（轻量化实体发现 / 旁路NER）
    • 产出：
      • projects / tokens / chains / topics
      • entity_sources
      • entity_confidence(命中方式强度)
      • event_type
      • credibility_score(来源可信程度)
      • importance_score(预定规则计算)

4. 召回

  • 这里的“召回”指的是：
    • 先从更大的内容池里取出一批候选 ContentItem
    • 供后面的聚类、排序和分页使用
  • service.py 在 personal feed 里会先做显式多路召回：
    • latest
    • trending
    • project
    • search
  • 多路召回结果会先按 item.id 去重
    • 同一个 item 如果被多路命中，会优先保留 semantic match 更强、importance 更高、更新时间更近的那个版本

5. 事件聚类

  • clustering.py
    • 输入是 ContentItem 列表
    • 输出是 EventCluster 列表
    • 聚类目标是“同一事件”，不是同一项目或同一 topic
    • 主要信号：
      • 事件类型兼容性
      • 时间窗口
      • 带置信度权重的实体重叠
      • 标题相似度
      • 可选的语义相似度

6. 个性化排序

  • ranking.py
    • 输入是 EventCluster
    • 输出是按用户排序后的 cluster feed
    • 主要信号：
      • importance_score
      • freshness_score
      • follow_affinity_score
      • interest_match_score
      • semantic_match_score
      • source_quality_score
      • risk_boost_score
    • mute_penalty
    • 最后再做一层 MMR-style diversification rerank

7. Embedding

  • semantic_recall.py
    • normalized item 会先 enqueue 到异步 embedding worker
    • item embedding 存在本地 SQLite semantic_index.db
  • embedding 当前主要参与三件事：
    • service.py 在 personal feed 里基于当前 query 和候选池做 query-aware semantic recall / semantic supplement
    • clustering.py 把 item embedding similarity 作为聚类信号之一
    • ranking.py 通过 semantic_match_score 把语义匹配信号带入最终排序

Personal Feed

  • get_personal_feed 是当前唯一会话化的 feed tool
  • 主流程是：
    • 显式多路召回
    • semantic supplement
    • 事件聚类
    • 个性化排序
  • service.py 内部维护 FeedSessionState，主要保存：
    • pending_clusters
    • delivered_event_ids
    • delivered_item_ids
    • source_cursors
  • 返回结果包含：
    • ranked_clusters
    • 展开的 supporting items
    • next_cursor
    • has_more
  • 分页语义是：
    • 首次请求创建 feed session，并尽量把已排好序的 cluster 填进 pending_clusters
    • 当前页从 pending_clusters 头部取前 max_items 个 cluster
    • 已返回的 cluster / item 会记入 delivered 集合，避免后续重复
    • 后续“更多”优先继续消费剩余 pending_clusters
    • 当 buffer 低于 refill threshold 时，再触发下一轮召回、semantic supplement、聚类和排序来补 buffer

Tool 语义与上下文边界

当前这套 MCP tools 可以分成两类：

  • 内容查询工具
    • get_latest_headlines
    • get_trending_feeds
    • get_project_feed
    • get_project_opinions
    • get_trending_topics
    • search_content
  • 推荐工具
    • get_personal_feed

内容查询工具默认保持无状态：

  • get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics
    • 透传上游分页能力
    • 返回的是当前请求对应的一页结果
  • get_trending_feeds / search_content
    • 直接返回当前快照结果
    • 不维护额外的服务层分页状态

get_personal_feed 是当前唯一的状态化 tool：

  • service.py 会维护短生命周期的 FeedSessionState
  • 对外只暴露 feed session cursor
  • 服务端内部保存：
    • pending_clusters
    • delivered_event_ids
    • delivered_item_ids
    • source_cursors
  • 后续“更多”会优先继续消费 session 里的 pending_clusters

职责边界大致是：

  • tool / service 层
    • 提供内容获取、候选召回、聚类、排序和 feed session 管理
  • agent 层
    • 负责多轮对话中的工具选择和上下文承接
    • 例如继续上一批、展开上一条、基于上一轮结果追问

当前分页语义：

  • get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics
    • 返回上游原生 cursor 元信息
  • get_personal_feed
    • 返回 next_cursor 和 has_more
    • cursor 的语义是 feed session continuation，而不是普通列表翻页

当前使用到的技术 / 算法

  • Python + MCP (FastMCP)
  • Followin API adapter
  • 规则式实体抽取
    • alias matching
    • source tag matching
    • keyword rules
  • 事件分类
    • rule-based multi-signal scoring
  • 实体置信度
    • strong / medium / weak
  • 语义召回
    • OpenAI embedding
    • cosine similarity
    • SQLite 向量持久化
  • 聚类
    • greedy incremental clustering
    • confidence-weighted Jaccard overlap
    • title Jaccard similarity
    • item embedding similarity
  • 排序
    • heuristic linear ranker
    • MMR-style diversification rerank

与业界生产实现相比，原型还缺什么

召回 / 推荐系统能力

  • 推荐层还没有真正的 long-term / session user representation 分层
  • 还没有行为日志驱动的异步用户画像更新链路

内容理解

  • 当前已经有轻量化的实体发现 / 弱 NER（tag、alias、rule、LLM-assisted extraction），但还没有带 span offset 的通用在线 NER / entity linking 主链路
  • event taxonomy 仍偏冷启动规则系统，缺少标注数据驱动的校准
  • 当前 credibility_score 主要依赖上游提供的 source type / metadata；受数据边界限制，还没有更细的 source-level reliability 和 multi-source verification

聚类

  • 当前已经把 embedding similarity 作为聚类信号之一，但整体仍是启发式多信号聚类，还没有训练式的 pairwise classifier / merge model
  • 如果进一步演进到基于持久化 cluster store 的在线聚类体系，还需要补 cluster assignment，以及跨天演化、拆簇、合簇等 cluster lifecycle 能力

排序

  • 当前排序已经用到 embedding 驱动的 semantic_match_score，但主体仍是人工特征加权的 heuristic linear ranker，而不是 learned-to-rank
  • 推荐层还没有接入点击、停留时长、分享等行为特征
  • 推荐层当前只做了轻量 MMR diversification，还没有更系统的配额控制和业务约束

当前暴露的 MCP Tools

  • get_latest_headlines
  • get_trending_feeds
  • get_project_feed
  • get_project_opinions
  • get_trending_topics
  • search_content
  • get_personal_feed

Web Demo

如果你想更直观地测试“随机用户画像 + 多轮对话”，可以启动一个 Web demo：

python3 -m followin_mcp.demo.webapp

或者安装后：

followin-mcp-web

然后打开：

http://127.0.0.1:8000

这个 demo 支持：

  • 随机生成用户画像
  • 为当前画像创建一个 LangChain agent session
  • 在同一个 session 里保留多轮聊天上下文
  • 为支持分页的 tool 保留最近可用的 next_cursor 上下文
  • 展示每轮实际发生的一个或多个 tool 调用
  • 展示 tool 参数和返回结果卡片

运行前请确保 .env 中已经配置：

FOLLOWIN_API_KEY=your_api_key
OPENAI_API_KEY=your_openai_api_key

MCP Server

当前已经把以下能力暴露成 MCP tools：

  • get_latest_headlines
  • get_trending_feeds
  • get_project_feed
  • get_project_opinions
  • get_trending_topics
  • search_content
  • get_personal_feed

启动方式：

python3 -m followin_mcp.mcp.server

或者安装后使用：

followin-mcp-server

ACP Agent

如果你想把当前对话 agent 作为 ACP stdio agent 暴露给支持 ACP 的客户端，可以启动：

python3 -m followin_mcp.acp.server

或者安装后使用：

followin-acp-agent

当前 ACP wrapper 直接复用 FollowinChatAgent：

  • ACP session 对应一条 FollowinChatAgent 会话
  • prompt() 内部调用现有的 chat_stream()
  • assistant 文本按流式 chunk 回传给 ACP client
  • 用户画像默认读取 FOLLOWIN_ACP_PROFILE_JSON，未配置时使用一个内置默认画像

如果你要接到本地 acpx / OpenClaw，~/.acpx/config.json 可以先用最小配置：

{
  "agents": {
    "followin": {
      "command": "/path/to/python",
      "args": ["-m", "followin_mcp.acp.server"],
      "cwd": "/path/to/followin-mcp"
    }
  }
}

这里不需要额外写 env：

  • followin_mcp.acp.server 启动时已经会 load_dotenv()
  • 只要 cwd 指到项目根目录，就会读取仓库里的 .env

相关 MCP