Refresh
Refresh 是一个自托管的个人账号 feed API：用你自己的浏览器登录态，把 X/Twitter 、知乎、B 站推给你的内容采集成结构化资源，再通过网页、RSS 和 JSON API 消费。
它不是多用户托管服务，也不内置第三方账号凭据。登录态、抓取到的内容、媒体缓存和日志都属于本机运行态数据，不提交到仓库。
它做什么
使用你自己的登录态抓取平台推荐流：
隐私边界
仓库只放应用代码。以下运行态路径已被 git 忽略：
公开仓库前不要把运行态目录、截图、导出的 cookie 、本地环境变量文件或真实数据样例提交进来。
本地运行
依赖：
启动：
pnpm install
pnpm start
默认地址：
首次使用时打开 http://localhost:5173。如果账号未登录，页面会提示登录；登录过程发生在受管 Chrome profile （默认 profiles/main）里。
Chrome 启动与登录态
Refresh 不依赖外部浏览器自动化服务。后端需要访问平台时，会先检查本机 CDP：
http://127.0.0.1:${RADAR_CDP_PORT}/json/version
如果 CDP 不可用，后端会自动拉起一个有窗口的 Chrome / Chromium：
登录、扫码和抓取都使用这个同一个 profile 。不要把 profiles/ 提交到仓库。
Linux 服务器部署时需要有可用的图形桌面会话，因为平台登录通常需要可见窗口。scripts/start-k2-tmux.sh 会在 tmux 进程里补齐常见桌面环境变量：
如果检测到 WAYLAND_DISPLAY，后端启动 Chrome 时会默认追加 --ozone-platform=wayland。需要强制指定时可以设置：
export RADAR_CHROME_OZONE_PLATFORM=wayland
验证
bunx tsc --noEmit
./verify.sh
verify.sh 使用隔离的 mock 数据，不依赖真实平台登录态。
部署
Refresh 运行两个进程：
公网部署时，把公网地址放进环境变量，然后用反向代理或 tunnel 暴露 Vite 端口。
示例：
export REFRESH_PUBLIC_URL="https://refresh.example.com"
export SERVER_PORT=13001
export WEB_PORT=13002
scripts/start-k2-tmux.sh
scripts/start-k2-tmux.sh 会：
公网代理或 tunnel 指向：
http://127.0.0.1:${WEB_PORT}
后端通过 Vite proxy 访问，因此通常只需要暴露 Web 端口。
常用环境变量
[td]变量[/td]
[td]用途[/td]
[td]默认[/td]
PORT
后端端口
3001
RADAR_DATA_DIR
数据根目录
./data
RADAR_BASE_URL
RSS 媒体绝对地址
http://localhost:$PORT
RADAR_CDP_PORT
受管 Chrome CDP 端口
19223
RADAR_PROFILE_DIR
受管 Chrome profile 目录
./profiles/main
RADAR_CHROME_BIN
Chrome 可执行文件
自动探测
RADAR_CHROME_OZONE_PLATFORM
Chrome Ozone 平台，例如 wayland
检测到 WAYLAND_DISPLAY 时为 wayland
RADAR_PROXY
媒体下载代理
http://127.0.0.1:7890
REFRESH_API_TARGET
Vite 反代的后端地址
http://localhost:3001
REFRESH_ALLOWED_HOSTS
Vite 允许访问的 host ，逗号分隔
未设置
REFRESH_PUBLIC_URL
公网部署 URL ，供 scripts/start-k2-tmux.sh 使用
脚本必填
文档
[td]文件[/td]
[td]内容[/td]
AGENTS.md
当前架构、约定、API 速查、常见任务操作手册
docs/design.md
原始设计蓝图和设计取舍
docs/progress.md
实施日志、踩坑记录和后续候选项
