# Anon Tweet

> Anon Tweet 是一个匿名浏览 Twitter/X 推文与 Instagram 帖子的全栈应用，内置 AI 翻译（Google Gemini / DeepSeek）、截图导出与 Markdown 卡片导出。主要页面使用 HTML；后端为 /api/* 的 BFF 聚合接口，完整机器可读 API 规范见 /openapi.json。

## Key Pages

- [/](/): 首页 — 粘贴 Twitter/X 或 Instagram 链接开始匿名浏览
- [/search](/search): 推文搜索 — 高级语法快捷插入 + 热门/最新切换 + 分页加载
- [/tweets/{id}](/tweets/2032649981690261684): 推文详情（AI 翻译 / 截图导出）
- [/ins/{id}](/ins/DWlrun0AVbE): Instagram 帖子详情（AI 翻译 / 截图导出）
- [/article/{id}](/article/2032649981690261684): X 长文（Article）阅读页 — 块文档渲染 + 按块 AI 翻译（原文 / 双语 / 仅译文）
- [/bili](/bili): Bili 动态发布（隐藏自用入口）

## Backend API

- [/openapi.json](/openapi.json): OpenAPI 3.1 规范 — 全部后端接口的路径、参数、请求与响应描述

- [GET /api/tweet/get/{id}](/api/tweet/get/2032649981690261684): 拉取单条推文（DB 缓存 → Twitter 原文）
- [POST /api/tweet/get/{id}](/api/tweet/get/2032649981690261684): 旧式拉取推文（兼容旧客户端，内部不再内联 AI 翻译）
- [GET /api/tweet/list/{id}](/api/tweet/list/1460328522022621184): 拉取 List 时间线推文（EnrichedTweet 数组）
- [GET /api/tweet/replies/{id}](/api/tweet/replies/2032649981690261684): 拉取推文回复（{ tweets, nextCursor }，cursor 分页）
- [GET /api/tweet/search](/api/tweet/search?q=twitter): 推文搜索（q 必填，type/cursor/count 可选，支持 X 高级语法）
- [POST /api/tweet/set](/api/tweet/set): 保存推文实体编辑或文章按块译文（intent: updateEntities / updateArticleTranslations）
- [GET /api/ig/get/{id}](/api/ig/get/DWlrun0AVbE): 拉取 IG 帖子（简化版，不触发 AI 翻译）
- [POST /api/ig/get/{id}](/api/ig/get/DWlrun0AVbE): 拉取 IG 帖子（可启用 AI caption 翻译）
- [POST /api/ig/translate/{id}](/api/ig/translate/DWlrun0AVbE): IG caption AI 翻译或手动翻译（manualTranslation 直接写入）
- [GET /api/user/get/{username}](/api/user/get/meeeei.gt): 查询用户资料（DB 缓存）
- [GET /api/user/timeline/{username}](/api/user/timeline/meeeei.gt): 用户时间线（EnrichedTweet 数组）
- [POST /api/ai-test](/api/ai-test): AI 提供商连通性测试（apiKey + model）
- [POST /api/ai-translation](/api/ai-translation): 统一 AI 翻译端点（type: twitter / ins / article）
- [POST /api/ai-vision](/api/ai-vision): AI 视觉描述生成 / OCR 翻译 / 保存（三种严格互斥请求形态）
- [GET /api/proxy/image](/api/proxy/image?url=https%3A%2F%2Fscontent.cdninstagram.com%2Fv%2Ft51.2885-15%2Fphoto.jpg): 图片代理（解决 IG CDN CORS/CORP，url 白名单校验）
- [POST /api/bili-post](/api/bili-post): Bili 动态发布（隐藏自用入口，ENABLE_BILI 控制，需 Bili Cookie）

## Data Shapes

后端主要接口（搜索 / 获取推文）的出参是 EnrichedTweet 数组，字段对齐 react-tweet：

- EnrichedTweet: id_str（推文 ID）、text（推文文本）、url（完整链接）、lang（语言码）、created_at（ISO 8601 创建时间）、user（作者 TweetUser）、entities（实体 Entity[]）、visionInfo（可选，AI 视觉描述）、quotedTweet（可选，引用推文）、card（可选，预览卡片）、space（可选，X Space 卡片：标题/主播/收听人数/时长）、article（可选，X 长文卡片与块文档）
- TweetUser: id_str、name、screen_name、profile_image_url_https（头像）、verified、is_blue_verified
- Entity: type（text / hashtag / mention / url / media / symbol / media_alt / separator）、text、index（文本偏移）、href（多数类型带链接）、translation（手动翻译）、aiTranslation（AI 翻译）
- TweetArticle: id（文章 ID）、url、title、previewText（摘要）、plainText（纯文本兜底）、format（rich 表示带 blocks，plain 仅纯文本）、coverImage（封面）、publishedAt（epoch ms）、blocks（ArticleBlock[]，仅 rich）
- ArticleBlock: type（paragraph / heading / list-item / quote / markdown / divider / image / embed-tweet / link / unknown）、key（稳定块 ID）、runs（行内片段：文本 / 链接 / mention / hashtag，带回读偏移与样式）、text（markdown 块）、media（image 块）、tweetId（embed-tweet）、level / ordered（heading / 列表）
- SearchResponse / RepliesResponse: { tweets: EnrichedTweet[], nextCursor }（nextCursor 为 string 或 null，null 表示没有更多）

关键接口入参：

- GET /api/tweet/search: 必填 q（≤500 字符，支持 X 高级语法，如 (from:user) since:2025-01-01），可选 type=latest/top、cursor（分页游标）、count（默认 20）
- GET /api/tweet/get/{id}: 路径参数 id 为推文 ID（如 2032649981690261684），返回 EnrichedTweet 数组，AI 翻译存于 entities[].aiTranslation
- GET /api/tweet/replies/{id}: 可选 cursor 翻页，返回 { tweets, nextCursor }
- GET /api/ig/get/{id}: 路径参数 id 为 shortcode（或 username/story_id），未配置 INS_COOKIES 时返回空数组

## Machine Readable

- [/skills/anon-tweet/SKILL.md](/skills/anon-tweet/SKILL.md): Agent Skill — 匿名浏览 Twitter/X 与 IG 帖子的 API 使用指南（Agent Skills 规范，可导入 Claude Code / claude.ai）
- [/sitemap.xml](/sitemap.xml): XML 站点地图
- [/robots.txt](/robots.txt): 爬虫规则（Disallow /api/，llms.txt 与 openapi.json 不受限）