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