xgo-organize-follows

关注整理助手 (Follow Organizer)

通过 XGo (xgo.ing) 开放接口整理 Twitter/X 关注用户 — 发现未分类用户、AI 分析推荐列表归属、批量执行分类。多阶段交互式工作流。

完整 API 参数详情见 references/api_reference.md。

认证

所有请求需要 X-API-KEY 请求头。从环境变量 XGO_API_KEY 读取密钥：

-H "X-API-KEY: $XGO_API_KEY"

若 XGO_API_KEY 未设置，提示用户配置。

接口地址：https://api.xgo.ing

工作流概览（6 个阶段）

阶段一（准备）→ 阶段二（获取未分类用户）→ 阶段三（深度分析）→ 阶段四（AI 匹配）→ 阶段五（确认）→ 阶段六（执行）

重要: 这是一个交互式多阶段工作流。阶段五需要等待用户确认后才能进入阶段六。阶段六包含写操作（addMember），执行前必须获得用户明确确认。

阶段一：准备（2 个并行请求）

获取关注统计和列表信息，了解整体情况。

# 1. 关注统计
curl -s "https://api.xgo.ing/openapi/v1/following/stats" \
  -H "X-API-KEY: $XGO_API_KEY"

# 2. 获取所有列表（含成员）
curl -s "https://api.xgo.ing/openapi/v1/list/all" \
  -H "X-API-KEY: $XGO_API_KEY"

并行执行。 输出准备报告：

## 关注整理 - 准备报告

- **总关注数**: 356
- **已分类**: 280 (78.7%)
- **未分类**: 76 (21.3%)
- **列表数**: 8

### 现有列表
| 列表名称 | 成员数 | 描述 |
|---------|--------|------|
| AI | 45 | AI 领域研究者 |
| Programming | 38 | 编程与开发 |
| 中文极客 | 32 | 中文科技博主 |
| ... | ... | ... |

准备分析未分类用户，是否继续？

等待用户确认后进入阶段二。

阶段二：获取未分类用户

从 following/list 分页获取所有关注用户，客户端过滤出未分类用户。

# 分页获取关注列表（每次 100 人，遍历所有页）
curl -s "https://api.xgo.ing/openapi/v1/following/list?page=1&size=100" \
  -H "X-API-KEY: $XGO_API_KEY"

# 若 totalPage > 1，继续拉取后续页
curl -s "https://api.xgo.ing/openapi/v1/following/list?page=2&size=100" \
  -H "X-API-KEY: $XGO_API_KEY"
# ... 以此类推

客户端过滤逻辑

速率说明: 若关注 500 人，需 5 页请求（size=100）。并行请求或顺序请求均可，远低于速率限制。

输出未分类用户概览后，询问用户要分析多少人（默认 20 人/批）。

阶段三：深度分析（每用户 3 个并行请求）

对每个未分类用户获取详细信息，用于 AI 匹配。

# 对每个用户并行执行 3 个请求:

# 1. 用户详情（简介、标签）
curl -s "https://api.xgo.ing/openapi/v1/user/info?userName=TARGET_USER" \
  -H "X-API-KEY: $XGO_API_KEY"

# 2. 最新原创推文（5条）
curl -s -X POST https://api.xgo.ing/openapi/v1/tweet/list \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $XGO_API_KEY" \
  -d '{"queryType":"user","userName":"TARGET_USER","sortType":"recent","tweetType":"ORIGINAL","currentPage":1,"pageSize":5}'

# 3. 最热原创推文（5条）
curl -s -X POST https://api.xgo.ing/openapi/v1/tweet/list \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $XGO_API_KEY" \
  -d '{"queryType":"user","userName":"TARGET_USER","sortType":"influence","tweetType":"ORIGINAL","currentPage":1,"pageSize":5}'

速率管理

阶段四：AI 匹配

基于阶段三 user/info 返回的 description（个人简介）和 tags（系统标签），以及推文内容，与现有列表进行匹配。

匹配逻辑

对每个未分类用户：

输出建议表

## 分类建议（共 20 人）

| # | 用户 | 简介摘要 | 推荐列表 | 置信度 | 理由 |
|---|------|---------|---------|--------|------|
| 1 | @user1 | AI researcher at... | AI | 高 | 简介含 AI/ML 关键词，推文讨论 LLM |
| 2 | @user2 | Full-stack dev... | Programming | 高 | 推文以编程技术为主 |
| 3 | @user3 | Crypto trader... | - (建议新建 "Crypto") | 中 | 现有列表无匹配，内容为加密货币 |
| 4 | @user4 | Random thoughts... | 跳过 | 低 | 内容过于杂乱，无明确主题 |
| ... | ... | ... | ... | ... | ... |

### 建议新建列表
- **Crypto** — 3 位用户匹配此类别

请确认、调整或跳过上述建议。输入方式：
- "确认全部" — 按建议执行
- "跳过 4, 7" — 跳过第 4、7 位用户
- "3 改为 Programming" — 将第 3 位用户改为 Programming 列表
- "调整后确认" — 修改后执行

阶段五：用户确认

必须等待用户明确确认后才能进入阶段六。 不得自动执行写操作。

用户可以：

阶段六：执行分类

根据确认后的建议，执行以下操作：

6.1 创建新列表（如有需要）

curl -s -X POST https://api.xgo.ing/openapi/v1/list/save \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $XGO_API_KEY" \
  -d '{"name":"Crypto","description":"加密货币和 Web3 相关","privateList":false}'

记录返回的 listId。

6.2 批量添加成员

对每个确认的 用户→列表 映射：

curl -s -X POST https://api.xgo.ing/openapi/v1/list/addMember \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $XGO_API_KEY" \
  -d '{"listId":"LIST_xxx","member":{"id":"USER_ID","name":"Display Name","userName":"username"}}'

member.id 为必填字段（来自阶段三 user/info 响应的 id 字段）。

执行策略

输出执行结果

## 分类执行结果

### 新建列表
- ✅ 已创建 "Crypto" (ID: LIST_xxx)

### 添加成员
- ✅ @user1 → AI
- ✅ @user2 → Programming
- ✅ @user3 → Crypto
- ⏭️ @user4 → 跳过
- ❌ @user5 → AI（失败：成员数超限）
- ... (共 N 个操作)

### 统计
- 成功：16
- 跳过：2
- 失败：2
- 未分类用户剩余：56 → 40

参数调整

根据用户输入调整：

错误处理

重要: 始终先检查 response.success 再处理 response.data。部分错误返回 HTTP 200 但 success: false — 不要仅依赖 HTTP 状态码。