feat: X (Twitter) 机器人渠道 —— @提及派发任务并读取 thread 上下文(调研结论与实施计划)

[dashhuang]

使用场景 / Use case

为 Cindy 增加 X (Twitter) 机器人渠道:用户在 X 上 @bot 即可派发任务,bot 读取 thread 原始上下文,交给 desktop 侧 agent 执行,最后回帖结果 —— 与现有 Slack / Telegram bot 同一产品形态。

当前问题 / Current limitation

Cindy 目前支持 Slack、Telegram(hook server 路线)与飞书、Discord(用户自带 token 路线),尚无 X 渠道。

调研结论(2026-07)

X 平台能力对齐

• 实时 mention 推送可行:X Activity API (XAA) 的 post.mention.create 事件(filter by user_id),persistent HTTP stream(GET /2/activity/stream)或 webhook 交付,亚秒级。mention 属私有事件,需 OAuth 2.0 user context 授权。断线补偿 backfill_minutes 上限 5 分钟。
• thread 上下文可读:回复链上溯(referenced_tweets expansion)+ conversation_id 检索;conversation_id 仅覆盖最近 7 天(recent search 窗口)。
• 平台政策约束(X Developer Guidelines):
  • 回复 @提及属 user-initiated,允许;但每次交互最多 1 条回复;
  • AI 生成的回复需向 X 事先申请批准(Policy Support form),这是上线前置条件;
  • 必须开启 Automated 账号标签、bio 声明运营者、关联真人账号、支持 opt-out;
  • 2026-02 起自动化应用仅可回复先 @ / 引用了该 App 的帖子(与本产品形态天然一致)。
• 成本(pay-per-use,2026-02 起):读 post $0.005、发 post $0.015、含链接 $0.20;月读上限 200 万条。
• 输出限制:标准 280 字符;长推(25,000 字符)需 bot 账号有 X Premium;附件仅支持图片(/2/media/upload + media.write),不支持任意文件。
• 公开时间线无按钮组件,Slack 那套交互卡(权限审批 / 提问 / plan review)无法直接搬移。

已定产品决策

• API 成本由服务端统一承担,配 per-user 配额与全局熔断护栏。
• 单条回复优先:公开线一条长推收口(bot 账号购买 Premium,25,000 字符);仅在 agent 中途需要交互、产出超载或需要 slash 类操作时降级到 DM。
• ack 用点赞(like)而非回复,不消耗唯一回复名额。
• turn.progress 对 X provider 丢弃(无可编辑的进度载体;协议中本就是 latest-wins 帧,丢帧无害)。
• X 来源任务默认低交互权限模式(预置 allowlist),尽量避免中途交互。
• 7 天 conversation_id 窗口可接受,超窗不提示用户。

期望方案 / Proposed solution

走 hook server + provider-neutral 协议路线(与 Telegram 相同),不走用户自带 token 路线。理由:AI 回复审批发给单一官方 App、XAA 单 App 单 stream 需服务端扇出、webhook 需公网端点、pay-per-use 计费与断线补偿需要 always-on 服务端。

协议层(provider.bind.* / provider.prefs.* / HOOK_FEATURE_PROVIDER_*)已为多 provider 泛化,Telegram 已验证过此扩展路径。

实施顺序

1. 前置重构(本仓):apps/desktop/src/main/hook-control/manager.ts 中 telegram 专属的 transport / status / binding 状态目前是硬编码变量,先泛化为表驱动的 provider map,为第三个 provider 铺路;
2. 协议(cindy-protocol):HOOK_PROVIDERS 加 'x'、新增 feature 常量与测试;TaskSource.im 为开放集合,无需结构改动;
3. 服务端(独立仓,不在本仓边界):XAA 订阅管理、OAuth 绑定、thread 抓取与预算护栏、长推纯文本渲染(markdown 降级)、like ack、DM 兜底;
4. 客户端接线(本仓):config/endpoint*.json 加 xHookWsUrl、settings UI(HookConnectionsSection 等)、session source 枚举与图标(Light/Dark 双模式)、localDb schema。

外部前置依赖

• 向 X 提交 AI reply 审批申请(周期不可控,应先行启动);
• 与 X 政策渠道确认:对先 @ 过 bot 的用户发起 DM 是否符合 solicited 语义、数据使用条款适用范围。

已考虑的替代方案 / Alternatives considered

• 用户自带 X App token 本地直连(Discord 模式,lizi-im + im/shared 编排层):被否。AI 回复审批按 App 发放,不可能让每个用户自行申请;且 desktop 无公网端点、无法承担 always-on 的 stream 消费与计费管理。
• 轮询 mentions timeline 代替 XAA:被否。延迟高、读配额烧钱快,且 XAA 已提供亚秒级推送。
• 公开线多条回复 / 流式进度:被否。违反平台「每次交互最多 1 条回复」规则。

[dashhuang]

开始处理第一步:hook-control/manager.ts 的 provider 状态泛化重构(行为不变的前置 PR)。

[dashhuang]

实施顺序第 1 步(hook-control provider 状态表驱动泛化)已合入 main:#695(squash 为 8d4b7ab)。后续第 2 步为 cindy-protocol 增加 'x' provider 常量与测试。

[dashhuang]

进度更新(实施顺序第 3 步 · 服务端):

已完成

• 服务端仓已落地 x-hook-server 服务骨架(与 telegram-hook-server 平级的独立部署单元,仅共用 cindy-protocol wire contract),任务分支提交 43 文件 / +7,771 行,含 prisma schema + migration、Docker 构建与契约文档。能力面:desktop WS 接入(宣告 provider-bind-v1 / provider-prefs-v1 / session-picker-v1 / provider:x)、OAuth2 PKCE 绑定状态机(冲突换绑二次确认、state 只存 SHA-256)、XAA post.mention.create 消费(断线重连 + backfill ≤5min + event 去重)、thread 上下文组装(回复链上溯 + conversation_id 检索,预算上限)、markdown → X 纯文本渲染(25k 截断)、like ack、单条回复收口、per-user 日配额 + 全局月读预算护栏。
• 门禁已复核:typecheck / build 干净,vitest 7 文件 63 用例全绿(fake fetch / in-memory store,零真网络)。

待办与依赖(按阻塞程度排序)

1. cindy-protocol PR [Bug] 语音快捷键注册失败后错误保存新配置并注销旧快捷键 #16 需要 review/合并(checks 全绿)——服务端 PR 的 submodule bump 与客户端第 4 步接线都压在它后面;
2. X 账号线仍未启动(阻塞联调与上线,不阻塞开发):注册 bot 账号 → Premium → 开发者账号 + credits → OAuth app(client_id/secret)→ XAA 访问确认 → AI reply 事先审批提交(关键路径,周期不可控);
3. 服务端为「合并即部署」仓:合并前需备齐生产环境变量(OAuth 凭据、bot user id、bearer token、DB)并配置 activity 开关,凭据未就绪前以 feature gate 关闭态合入或保持 PR 待命;
4. 技术遗留:prisma store 尚无真实 PG 合同测试(memory store 为契约基准)、migration 未对真实库跑过 deploy、凭据列信封加密(KMS)为 TODO;
5. v1 范围明确不含:执行中交互的 DM 兜底渲染(interaction.request 现回退 desktop 默认语义,phase-2 做)、媒体出站、多 bot 账号。

服务端 PR 将在 #16 合并、submodule 可指向协议主干后开出。

[dashhuang]

服务端骨架 PR 已开出(内部仓 cindy-server#211,ready for review):x-hook-server 独立服务,gate 关闭态、未注册部署清单,合并对生产零影响。合并阻塞仅一项:cindy-protocol PR #16 合并后在该 PR bump submodule 指针并复跑门禁。

[dashhuang]

服务端第 3 步完成:x-hook-server 已合入主干 🎉

xindong/cindy-server#211 已于 2026-07-29 合并(31 批 review、150 条 threads 全部闭环,最终 292 个单测全绿)。要点:

• 独立部署的 x-hook-server(X mention → desktop 任务中继),与 telegram-hook-server 平级,仅共用 cindy-protocol wire contract('x' provider 常量已随协议仓 PR [Bug] 语音快捷键注册失败后错误保存新配置并注销旧快捷键 #16 合入,指针已 bump)。
• 默认关闭(X_HOOK_ENABLED gate),合并零生产影响;部署仓注册、建库、Secret 配置为上线前置,凭据就绪后再做。
• 可靠性设计:持久 outbox / 事件 inbox(世代围栏 + 认领续租)、write-ahead 预算结算、binding id 精确归属复验、lane 会话串行化等,细节见仓内 docs/x-hook-server.md。

下一步

• 第 4 步:客户端接线(desktop hook-control 增加 x provider,依赖已合入的协议常量)
• 外部前置(不变):@cindybot 账号注册 → Premium → 开发者账号 → OAuth app → XAA → AI reply 书面审批(关键路径)
• 部署前置:deployment-state 仓注册 + sh-dev 建库 + X_CREDENTIAL_ENC_KEY 等 Secret