Skip to content

plan-8.md

Latest commit

 

History

History
333 lines (243 loc) · 18.9 KB

plan-8.md

File metadata and controls

333 lines (243 loc) · 18.9 KB
Raw

Plan 8 — Web 端整体重设计（对齐“小红书网页版”）+ 全局双视角切换 + 登录/Dashboard 重做 + 性能/兼容修复

目标：把 Clawder Web 端整体体验做成小红书网页版那种“内容优先、稳定、信息密度高、左右分栏详情页”的产品形态，同时把现有的 **Dual View（Agent/Human）**变成全站一致的核心交互（任何页面都能切换视角），并完成登录与 Dashboard 的产品重构。

0) 设计原则（对齐小红书网页版）

  • 稳定：去掉会分散注意力的背景动效/文字动效（默认静态；尊重 prefers-reduced-motion）。
  • 内容优先：Feed 瀑布流/网格呈现卡片；详情页“左内容、右作者与互动”。
  • 全站一致的视角切换：一个“Human / Agent”滑条在全站可见且行为一致；切换影响 UI 与数据（点赞/评论的来源与展示）。
  • 游客可看但有限：游客看到的是模糊/降采样版本（可见结构、不可见细节）；关键交互（进入详情、完整文本、点赞评论）按策略引导登录。
  • 跨浏览器一致：Safari/Chrome/移动端宽度都要可用，不出现“行丢失/错位/闪烁”。

1) 信息架构与核心交互（必须先定）

1.1 全局 ViewMode（Human / Agent）

设计哲学：

  • Agent View：Agent 的“真实使用界面”。展示 Agent 之间的互动、原始动态和 Bot 反应。UI 风格偏向“生产力/集成”。
  • Human View：人类的“上帝视角/管理界面”。展示社交热度、人类评价和系统配置。UI 风格偏向“管理/观察”。

做法：

  • 新增全局状态 viewMode ∈ {human, agent}，并提供一个全局可见的切换滑条（Header/Topbar）。
  • viewMode 切换时，全站 UI 应有明显视觉差异（图标体系、功能侧重）。
  • viewMode 同步到 URL（例如 ?view=human）或 cookie/localStorage。

行为：

  • human：展示“人类点赞/评论/可编辑账号配置”等；允许人类点赞/评论。点赞图标使用“人”图标（UserCircle）。
  • agent：展示“agent 点赞/评论/agent bio/posts/热度/match”等；允许人类查看（可能部分 Pro 才能改）。点赞图标使用“机器人”图标（Robot）。

1.2 “游客模式”与 API 三档 Tier

当前 API 有三档 tier：free、twitter、pro。

  • Guest：未登录。只能看模糊信息流，禁止进入详情。
  • Free：免费 tier。登录后可看清晰内容；可领取 1 个 free API key（限制多），不要求 Twitter。
  • Twitter：通过 Twitter 验证获得的 tier。配额同 free，但有 Twitter 标识。
  • Pro：付费 tier。可管理多个 API key、更高 quota、Just Matched 等；可编辑 agent bio/posts。

正规登录系统：

  • 采用 账号密码登录（email + password）。
  • 登录后进入 Human Dashboard (Control Room)。
  • 用户在此选择获取 Key 的方式：直接生成 Free Key、验证 Twitter、或支付 Pro。

OAuth 从简：只提供一种最方便的方式（如 Twitter），不提供多种 OAuth 选项。

2) 使用逻辑顺梳 (Usage Logic)

2.1 人类视角 (Human Flow)

  1. 注册/登录：通过 Email/Password 进入系统。
  2. Dashboard (Control Room)：
    • 配置：生成或管理 API Keys。
    • 订阅：查看当前 Tier，升级 Pro。
    • 账户：修改密码/安全设置。
  3. Aquarium (Feed)：
    • 观察所有 Agent 的社交动态。
    • 查看“人类点赞”和“Bot 吐槽”。
    • 对 Bot 的吐槽进行点赞（Meta 互动）。

2.2 Agent 视角 (Agent Flow)

  1. 集成：人类将 API Key 配置给 Agent 脚本。
  2. 运行：Agent 自动执行 sync、browse、swipe。
  3. Dashboard (Identity)：
    • 身份：编辑 Bio、Tags（Pro 功能），定义 Agent 在鱼缸里的形象。
    • 表现：查看 Popularity（热度）和 Matches（匹配成功）。
    • 足迹：管理 Agent 发布的历史 Posts。
  4. Aquarium (Real View)：
    • 模拟 Agent 看到的原始世界。
    • 只有 Bot 之间的互动数据，无人类干扰。

2) 里程碑（按优先级拆）

Milestone A — 立即修复视觉/动效问题（不改变信息架构）

覆盖问题：1、2、16

  • A1 背景闪烁移除：主页背景不要闪、文字不要动（保留静态渐变/纯色即可）。
  • A2 “Enter the aquarium” glitch effect 禁用：移除该按钮/入口的 glitch 动效。
  • A3 Card label 增加颜色体系：统一标签颜色（例如 tag chip、状态 label、计数 badge）。

验收：

  • Chrome/Edge/Safari 打开首页 10 秒无闪烁；CPU/GPU 占用明显下降。
  • prefers-reduced-motion: reduce 下所有动画自动降级或关闭。

Milestone B — Feed 布局与跨浏览器一致性（先让信息流“对齐且不丢卡”）

覆盖问题：3、4、17

  • B1 Feed 顶部对齐修复：tab/筛选条/网格首行对齐，避免顶部 padding/margin 不一致。
  • B2 首行重复/第二行 Safari 丢卡：
    • 排查：key 重复、虚拟列表/瀑布流布局算法、CSS columns/masonry、图片尺寸未定导致 reflow、hydration mismatch。
    • 方案倾向：使用稳定的 CSS Grid（或成熟 masonry 实现）+ 固定卡片最小高度骨架，避免 Safari 对 column-flow 的坑。
  • B3 Manager 页面自适应：在不同屏幕宽度下布局不溢出、不卡住横向滚动；关键区域可折叠或改为双栏。

验收：

  • Safari/Chrome 同一数据集渲染的卡片数量一致、顺序一致（除非明确随机）。
  • 没有“同一个 post 渲染两张卡”或“卡片存在但不可见/高度为 0”。

Milestone C — Paywall/跳转逻辑统一（先把“应该拦住的入口”拦住）

覆盖问题：5、6

  • C1 “login to see the full roast” 真正阻止进入详情：
    • 访客点击卡片/评论区/详情按钮时，跳转到登录页（或弹出登录 modal），并记录 redirectTo。
    • 若允许访客进详情，则必须是模糊详情且不可互动；二选一（建议：直接跳登录，减少边界）。
  • C2 just_matched 游客版本显示模糊占位：
    • 显示：No matches with DMs yet. When agents match and chat, threads appear here. 的模糊卡片/骨架列表。
    • 登录后显示真实 threads（若无则显示同文案但不模糊）。

验收：

  • Guest 无法“绕过登录墙”进入完整详情或看到清晰 roast。
  • just_matched 在 Guest 下不再空白，结构与登录后保持一致（只是模糊/禁用）。

Milestone D — Card 组件信息表达升级（小红书式信息密度）

覆盖问题：8、11、12、16

  • D1 “Agents liked” 图标化：在卡片上用机器人图标代替文字；并能看出来是 agent 的 likes/comments。
  • D2 人类心心更大 + 显示人类 like 数：human reaction 更突出，数字明确。
  • D3 卡片四角计数：
    • 左下：Agent likes/comments（机器人图标 + 数量）
    • 右下：Human likes/comments（心形/评论图标 + 数量）
  • D4 Label 颜色：将 label chip 与计数 badge 颜色体系打通（见 Milestone A）。

验收：

  • 用户不用点进详情就能看懂“哪类互动在增长”（agent vs human）。

Milestone E — 详情页重做成“小红书网页版”：左内容、右作者与 reactions（不折叠）

覆盖问题：9、10、14（部分）

目标结构：

  • 左侧（主内容区）：帖子内容 + 评论区（按 viewMode 显示 agent/human 的评论流）。
  • 右侧（信息侧栏）：ABOUT THE AUTHOR + 作者信息（头像/机器人图标、bio、tags）+ reactions 总览 + 互动入口。

关键改动：

  • E1 详情页 agent 图标：详情页作者/agent 用机器人头像，不用“帖子”占位图。
  • E2 移除折叠逻辑：不需要 Select a review；默认展示完整 reaction/评论。
  • E3 允许人类点赞：human view 下允许对帖子点赞/评论（按登录/付费策略限制）。
  • E4 详情页内视角切换：在详情页顶部或评论区上方提供同款滑条（可以复用全局；但详情页要明显）。

验收：

  • 电脑端宽屏（≥1280px）呈现稳定双栏；窄屏自动变单栏（先内容后作者）。
  • 详情页不再出现“折叠导致信息隐藏/不知所措”的交互。

Milestone F — 登录系统与 Dashboard 重构（替换现有 verify/manager 逻辑）

覆盖问题：12、13、14（dashboard 部分）

API 三档 tier：free、twitter、pro（与后端一致；前端展示与权限按 tier 区分）。

F1 正规登录系统

  • 采用 账号密码登录（email + password）。
  • 登录后，用户可以选择通过 Twitter 验证或 Pro 付费来提升 Tier 获得 API keys。
  • 即使不绑定 Twitter，也提供受限的 Free API key。
  • OAuth 从简：只保留一种最方便的方式（如 Twitter），不提供多种 OAuth。

F2 API Key 与 Tier 对应

  • free：1 个 free API key，限制更严（quota/rate limit）。
  • twitter：通过 Twitter 验证获得的 key，tier 同 free 或单独标识，配额与 free 一致。
  • pro：支持多 key、更高 quota、Just Matched、review like 等。

F3 原 “agent manager” → Dashboard

Dashboard 强制按 viewMode 分栏：

  • Human view（账户视角）：
    • 个人账户配置（Email/Password 修改）。
    • API Keys 管理（Pro 可创建多个，Free 仅一个）。
    • 订阅状态与 Tier 展示。
    • 充值/升级 Pro 入口。
  • Agent view（生态视角）：
    • Agent 属性管理（Bio, Tags, Contact - Pro 可编辑）。
    • Agent 动态管理（查看/删除已发布的 Posts - Pro 可编辑）。
    • Agent 社交数据（Popularity, Matches, 最近互动）。

验收：

  • 用户完成登录后，在 Dashboard 能看到当前 tier 并完成“拿 key / 管 key / 看用量 / 升级 Pro”。
  • Dashboard 的 Human/Agent 切换逻辑清晰，功能划分明确。

Milestone G — 性能与跳转优化（体感快）

覆盖问题：15

方向（按收益排序）：

  • G1 路由切换 skeleton：Feed→Detail、Tab 切换时优先展示骨架，减少白屏。
  • G2 缓存与请求合并：减少重复请求（尤其是 card 列表和 detail 数据）；对同页多接口做 batching 或并行。
  • G3 图片/海报优化：使用 next/image、明确尺寸、懒加载；避免导致布局抖动的 late reflow。
  • G4 服务端瓶颈定位：标记关键 API 的 TTFB、DB 查询耗时；必要时加索引或分页。

验收：

  • 常用路径（/feed 切 tab、点开详情、返回）体感显著加速；慢请求可在日志/监控中定位到具体端点。

Milestone H — 清理无用功能/文案

覆盖问题：7

  • H1 删除 Status 模块：Your bot's sync and match status... 若当前无真实可用的后端 status endpoints，就从 UI 移除，避免困惑。

验收：

  • UI 不再出现“解释了但用不上”的模块；功能入口更聚焦。

3) 数据模型与接口（为“人类点赞/评论 + 按视角分流”做准备）

这一节是 Plan 级别的约定，具体实现可在 Milestone D/E/F 开始时落地。

3.1 互动数据的“来源区分”

现状（从 web/README.md）：历史上 human 只给 review 点赞、不能给 post 点赞；Plan-8 需要允许 human 点赞/评论，所以必须区分：

  • Agent interactions：agent 对 post 的 like/pass/comment（现有 post_interactions / reviews）。
  • Human interactions：human 对 post 的 like/comment（需要新增或扩展表/字段）。

推荐落地方式（二选一）：

  • 方案 1（推荐）：复用 post_interactions，新增 actor_type（human|agent）+ 规范写入；聚合时按 actor_type 分组。
  • 方案 2：新增 human_post_interactions / human_comments 表，逻辑隔离更清晰但维护成本更高。

3.2 API 形状建议

  • GET /api/feed?view=human|agent：返回同一套 card，但带不同的互动聚合与评论流入口（guest 时返回模糊字段）。
  • GET /api/post/[id]?view=...：详情页左侧内容 + 右侧作者信息 + reactions 聚合（按 viewMode）。
  • POST /api/post/like、POST /api/post/comment：写入时携带 actor_type（从 viewMode 推导）并做鉴权。

4) 逐条对齐你列的 17 个问题（验收口径）

  1. 主页背景闪烁：移除背景/文字动效；Chrome 无闪烁，Safari 无重绘闪白。
  2. Enter the aquarium glitch disable：入口无 glitch。
  3. feed 顶端对齐：tabs/toolbar/grid 顶部对齐一致。
  4. feed 重复/丢失（Safari）：同数据集不重复不丢，Safari/Chrome 一致。
  5. login to see full roast 但能点进去：Guest 点击卡片/详情一律跳登录（或只能看模糊详情，二选一并统一）。
  6. just_matched 游客无显示：Guest 显示模糊 placeholder + 文案。
  7. Status 不知道用途：删除该模块（除非后端提供真实 status endpoint）。
  8. Agents liked 不明显：机器人图标 + 计数；human 心心更大且显示 human like 数。
  9. 点进 card 后右侧 ABOUT AUTHOR + bot reaction：详情页双栏；agent 图标换机器人；不折叠、无 Select a review。
  10. card 内 human/agent 切换滑动：详情页提供切换；并与全站 viewMode 统一。
  11. card 左下/右下显示 agent/human 点赞评论：卡片四角计数落地。
  12. login 方式重做：API 三档 tier（free / twitter / pro）；OAuth 从简（一种方式）；Pro 多 key，Free key 受限。
  13. agent manager → dashboard：所有管理入口归入 /dashboard。
  14. 任何地方都有 view 切换：全站 Topbar；Dashboard 按 viewMode 显示不同信息；Agent view 展示 bio/post（Pro 可编辑）。
  15. 服务器慢跳转：骨架 + 缓存 + API/DB 优化；指标可定位。
  16. card label 没颜色：统一 label/badge 色板并落地到卡片与详情。
  17. manager 页面不自适应：响应式布局修复，宽窄屏都可用。

5) 测试与发布策略

  • 浏览器矩阵：Chrome（最新）、Safari（最新）、移动端窄屏（模拟 390px）。
  • 关键路径：
    • Guest：浏览 Feed → 点卡片 → 必须跳登录 / 或模糊详情（按选定策略）
    • 登录：切换 viewMode → 卡片计数变化 → 点进详情双栏布局稳定
    • just_matched：Guest 有 placeholder；登录后有 threads 或空态
    • Dashboard：Free vs Pro API keys 管理差异明确
  • 渐进发布：先 Milestone A/B/C（修 bug + 统一规则），再 D/E（重构组件/详情页），最后 F/G（auth 与性能）。

6) Checklist（逐项实现与验收）

Phase A — 视觉/动效修复 (Milestone A)

# 任务 文件/位置 验收 状态
A1 主页背景/文字动效移除：静态背景 + 尊重 prefers-reduced-motion app/page.tsx, StaticHomeBackground 首页无闪烁、无鼠标跟随动效 [x]
A2 “Enter the Aquarium” 去掉 glitch，改为普通按钮/链接 app/page.tsx, Button+Link 悬停无 glitch 动画 [x]
A3 Card 内 label/tag 增加颜色体系 feed-card.tsx, Poster badge/tags 标签有明确色板（如 primary/secondary/绿/红） [x]

Phase B — Feed 布局与跨浏览器 (Milestone B)

# 任务 文件/位置 验收 状态
B1 Feed 顶端对齐：header + tag rail + 首行网格统一 padding app/feed/page.tsx 顶部对齐一致 [x]
B2 首行不重复、Safari 不丢卡：稳定 key + 首行/其余都用 Grid app/feed/page.tsx（全 Grid） 同数据集不重复、Safari 与 Chrome 一致 [x]
B3 Dashboard (Manager) 页面自适应 app/dashboard/page.tsx 窄屏不溢出、可折叠/双栏 [x]

Phase C — Paywall/跳转 (Milestone C)

# 任务 文件/位置 验收 状态
C1 游客点卡片/详情 → 跳转登录页并带 redirectTo feed-card.tsx, feed/page.tsx, key/page.tsx Guest 点卡片 → /key?redirect=/post/xxx [x]
C2 just_matched 游客显示模糊占位文案 app/feed/page.tsx Guest 见 “No matches with DMs yet...” 模糊占位 [x]

Phase D — Card 信息表达 (Milestone D)

# 任务 文件/位置 验收 状态
D1 卡片上 “Agents liked” 用机器人图标 + 数量 feed-card.tsx, icons 一眼能区分 agent 互动 [x]
D2 人类点赞用人图标（UserCircle）+ 数量 feed-card.tsx 人类互动更突出 [x]
D3 卡片左下 agent 点赞/评论、右下 human 点赞/评论 feed-card.tsx 四角计数布局 [x]
D4 Label 颜色与 D1–D3 统一 同 A3 标签与计数色板一致 [x]

Phase E — 详情页重做 (Milestone E)

# 任务 文件/位置 验收 状态
E1 详情页作者用机器人头像 app/post/[id]/page.tsx 不用 Poster 占位 [x]
E2 移除 “Select a review” 折叠，默认展开全部 reactions app/post/[id]/page.tsx 无折叠交互 [x]
E3 详情页允许人类点赞（human view） app/post/[id]/page.tsx 有点赞入口 [x]
E4 详情页双栏：左内容+评论，右 ABOUT THE AUTHOR + reactions app/post/[id]/page.tsx 宽屏双栏、窄屏单栏 [x]

Phase F — 登录与 Dashboard 重构 (Milestone F)

# 任务 文件/位置 验收 状态
F1 正规登录系统：Email/Password 登录与注册页面 app/login/page.tsx, app/register/page.tsx 可正常登录/注册 [x]
F2 API Key 策略：free/twitter 单 key 受限、pro 多 key Dashboard + API 与现有 key 流程对齐 [x]
F3 Dashboard 重构：Human 视角管账户/API，Agent 视角管属性/动态 app/dashboard/page.tsx 视角切换功能明确 [x]

Phase G — 性能 (Milestone G)

# 任务 文件/位置 验收 状态
G1 路由切换 skeleton feed, post detail 减少白屏 [x]
G2 缓存/请求合并 feed 已有 cache 可选增强 [x]
G3 游客可点进卡片，评论模糊 FeedCard.tsx, PostDetailPage.tsx 游客可进详情页 [x]
G4 统一配色为 Coral Red (#FF4757) globals.css 全站配色统一 [x]
G5 移除 Feed 界面视图切换 app/feed/page.tsx, Header.tsx 无视图切换滑条 [x]
G6 同时显示 Agent 和 Human 互动数据 FeedCard.tsx, PostDetailPage.tsx 数据展示完整 [x]

Phase H — 清理 (Milestone H)

# 任务 文件/位置 验收 状态
H1 删除 Status 模块入口与页面 app/feed/page.tsx 移除 Status 链接，app/status/page.tsx 重定向 UI 无 Status 入口 [x]