imjszhang/js-eyes/js-reddit-ops-skill

js-reddit-ops-skill

面向 reddit.com 的只读 + 仅改自身浏览器 URL的 skill。从 v3.0 起切到 PAGE_PROFILES + Bridges + Session 架构，参考 `js-wechat-mp-ops-skill` 的设计取舍：

• 数据获取：READ 数据优先走 reddit 公开 JSON 端点（*.json / oauth.reddit.com），与浏览器同源、复用 cookie；DOM 解析（lib/redditUtils.js）保留为兜底
• 双前端兼容：bridge 内 detectFrontend() 区分 shreddit（新版）/ old.reddit（旧版）；JSON 主路径与前端无关
• 安全分级：只做 READ + INTERACTIVE 两档，永不做 DESTRUCTIVE（不投票 / 不评论 / 不发帖 / 不订阅 / 不发私信 / 不举报）

依赖与前置

• Node.js 22+、JS Eyes 2.8.5+；JS Eyes Server 已启动（js-eyes server start）
• 浏览器扩展：已安装并连上 server
• 登录态（可选）：浏览器里已经人工登录 reddit.com（本 skill 不做任何登录自动化）；未登录可调 READ 公开内容；登录后可调 inbox / 个人 saved/upvoted 等 tab
• 任意 reddit.com tab 即可：READ 工具默认 navigateOnReuse=false / reuseAnyRedditTab=true，bridge 在任意 reddit.com tab 里 fetch 同源 JSON 端点；用户当前 tab 不会被切走
• Raw Eval：bridge 首次注入需要宿主设置 security.allowRawEval: true；JS Eyes 2.5+ 会把该设置同步到扩展，扩展存储中的显式 false 仍可强制关闭
• Chrome：要求 135+；Chrome 138+ 还需开启浏览器控制的 Allow User Scripts

安全红线（READ / INTERACTIVE / DESTRUCTIVE）

本 skill 的所有工具都会被归入以下三档之一。审计界线按「是否改 reddit 业务数据」而非「是否触网」来划：

READ（默认档）

纯读，不改任何 DOM、不改 URL、不触发任何业务写操作。

• 走 fetchRedditJson(path, params) 重放 reddit 公开 JSON 端点（GET，复用浏览器同源 cookie）
• DOM 路径仅作为 bridge 失败时的兜底，由 lib/redditUtils.js cheerio 解析提供
• 工具：reddit_get_post / reddit_session_state / reddit_list_subreddit / reddit_subreddit_about / reddit_search / reddit_user_profile / reddit_inbox_list / reddit_my_feed / reddit_expand_more

INTERACTIVE（v3.2+）

只改浏览器自己的 URL，不改 reddit 侧任何业务数据。实现硬约束：

• 仅 location.assign(newUrl)，禁止模拟点击任何 DOM CTA
• bridge 端 navigateLocation() 拒绝跨域 URL（必须是 *.reddit.com）
• 调用返回 {from, to, hint}，CLI 端 awaitBridgeAfterNav 重注 bridge + state 自校验
• skill.definition.js 里带 interactive: true / destructive: false
• 工具：reddit_navigate_post / reddit_navigate_subreddit / reddit_navigate_search / reddit_navigate_user / reddit_navigate_inbox / reddit_navigate_home

DESTRUCTIVE（永不做）

任何改 reddit 业务数据 / 触发账户变更的操作，从 v3.0 起一直不会做：

• 不投票 / 不评论 / 不发帖 / 不编辑 / 不删除
• 不 save / unsave / hide / report
• 不 follow / unfollow / subscribe / unsubscribe / block
• 不发送 / 删除 / 标记已读私信
• 不实现登录自动化 / 不注入 cookie / 不伪造 modhash / bearer token

如果未来真的要做，将在 skill.definition.js 里把该工具标记 destructive: true，并要求调用方显式 --confirm 走 Safe Default Mode consent 流程。

提供的 AI 工具

全部工具都是 optional: true（按需加载），入参详见 skill.definition.js::TOOL_DEFINITIONS。

内部踩点 CLI（不进 skill.definition.js，仅供本仓库开发者排查）

下面两条只在 CLI 暴露、不暴露给 AI tool 列表，用于改版后定位 DOM 结构变化或抓 XHR 形态：

这三条都不写 listener、不挂 hook，纯靠浏览器内置 buffer / 一次性 querySelector，可放心反复跑。

CLI

cd /path/to/js-eyes/skills/js-reddit-ops-skill
npm install
 
# 通路 + 登录态 + bridge 注入 + probe + state 一站诊断
node index.js doctor
 
# READ：帖子详情（v2.x 兼容入口，调用 lib/api.js::getPost，内部 bridge 主路径 + DOM 兜底）
node index.js post https://www.reddit.com/r/programming/comments/abc/title/ --depth 4 --limit 50 --pretty
 
# READ：subreddit 列表 / about
node index.js list-subreddit programming --sort hot --limit 25
node index.js list-subreddit programming --sort top --time-range week --limit 50
node index.js subreddit-about programming
 
# READ：搜索
node index.js search "node.js" --sort top --time-range week --limit 25
node index.js search "lockfile" --sub programming   # restrictSr=true
 
# READ：用户主页
node index.js user-profile spez --user-tab overview --limit 25
node index.js user-profile spez --user-tab submitted
 
# READ：收件箱（必须已登录）
node index.js inbox-list --box unread --limit 25
 
# READ：主 feed
node index.js my-feed --feed popular --sort hot
node index.js my-feed --feed all --sort top --time-range day
 
# READ：登录态
node index.js session-state
 
# READ：展开评论树 more 节点
#   1) 先 reddit_get_post 拿到 _kind:'more' 节点的 _children + parent 上下文
#   2) 再 reddit_expand_more 提交 link_id + children
node index.js post https://www.reddit.com/r/<sub>/comments/<id>/<slug>/ --pretty
node index.js expand-more t3_<id> "child1,child2,child3" --sort top --pretty
 
# INTERACTIVE：仅 location.assign，不模拟点击
node index.js navigate-subreddit programming --sort top --time-range week
node index.js navigate-post https://www.reddit.com/r/programming/comments/abc/title/
node index.js navigate-search "node.js" --sub programming
node index.js navigate-user spez --user-tab overview
node index.js navigate-inbox --box unread
node index.js navigate-home --feed popular
 
# 内部踩点（仅本仓库开发者用）
node index.js dom-dump --anchors --limit 80
node index.js xhr-log --filter "reddit\\.com/(api|svc|graphql)" --limit 200
 
# 业务脚本（README + 业务结果落 docs/_data/）
node scripts/aggregate-subreddit.js programming --sort hot --limit 10 --depth 3
node scripts/batch-post.js --file urls.txt --depth 3 --comment-limit 80
 
# 也可通过 js-eyes 统一入口
js-eyes skill run js-reddit-ops-skill doctor

DOM/API 双模式（v3.7.0+）

v3.7.0 把 6 个 page bridge 从"API-only（fetchRedditJson）"扩成"DOM/API 双 路径"，给每个 READ 命令多了一个 --read-mode dom|api|auto flag（v3.9 由 --mode 重命名而来；旧 --mode 抛错，与 visual-* 完全解耦）：

DOM 路径下每步真实操作都通过 __jse_visual.emit 发 dom_* 事件 （dom_navigate / dom_locate / dom_hover / dom_click / dom_type / dom_typed / dom_scroll / dom_wait / dom_extract）进 events.jsonl， 配合 v3.8.0 的截图链路，@js-eyes/visual-replay-hyperframes v0.6.0+ 直接用 真实 reddit 截图序列承载这些操作的视觉表现（鼠标 / 输入 / 滚动 / 点击都已被 浏览器真实绘制并截进 JPEG）。dom_* 事件主要给上游审计 / 调试 selector 漂移用， v0.5.x 那种合成端 cursor / typing / ripple / spinner / scroll 已下线（snapshot 主链路覆盖了同等视觉需求）。

response 里多 5 个字段方便上游审计：

{
  ok: true,
  readMode: 'dom',           // 实际跑通的档（v3.9 由 mode 改名）
  requestedReadMode: 'auto', // 用户请求的档（v3.9 由 requestedMode 改名）
  fallback: false,           // true = auto 模式从 dom fallback 到 api
  triedMethods: ['dom_search', 'api_search'],
  usedMethod: 'dom_search',
  // ...原有字段
}

支持矩阵（v3.7.0 完整覆盖）：

未实现 DOM 路径的命令仍然只走 api_*（向后兼容）。所有公开方法都同时挂 api_<name> 前缀别名，旧无前缀调用零改动继续工作。

selector 漂移诊断：

node skills/js-reddit-ops-skill/scripts/_dev-probe-dom.js --page subreddit
node skills/js-reddit-ops-skill/scripts/_dev-probe-dom.js --all

snapshot mode 录像（v3.8.0+）

v3.8.0 起 --visual-record <dir> 自动启用 PNG/JPEG 截图链路（默认 JPEG q=82 按浏览器实际视口 CSS 像素），每条命令边界落 1 帧到 <dir>/frames/<ts>.jpg， 对应 frame 事件随 events.jsonl 一并写出（含 viewport / when / frameRef）。

@js-eyes/visual-replay-hyperframes v0.6.0 据此把 composition.html 的 #stage 背景换成真实 reddit 截图序列（双缓冲 cross-fade 220ms）。bridge 录制时画在浏览器 里的 HUD/flash 浮层会随 captureScreenshot 一起被拍进 JPEG 像素，那是预期—— 合成端 (visual-replay-hyperframes) 默认不再额外叠一层 composition-side HUD/flash （避免双重画 HUD 的视觉冗余）。

v0.7.1：jse-replay 不再接受 --effects=hud,flash；请用 --plugin=@builtin/hud --plugin=@builtin/flash。

v0.6.0 breaking：--shell / --no-shell 已删；--effects=cursor|typing|click|ripple|spinner|scroll

报 unknown effect 退出 1。snapshot 模式截图自带 chrome 与 dom 操作的视觉表现，

这些 v0.5.x flag 已无对应渲染源。回退请用 0.5.2。

性能：每条命令额外 ~200-500 ms 等截图 + 写盘；典型 16 步深度调研 < 50 MB / 总耗时 < 5 min。

页面内视觉反馈（v3.5.0+）

reddit-ops 在调度边界自动给每个工具调用做"屏幕内演出"——这套层位于 @js-eyes/visual-bridge-kit，未来其它技能也能复用。bridge 业务函数零侵入。

post-2.7.0 architecture pivot：在线视觉反馈（HUD / flash / relation）保持不变；

离线 --visual-record 已切到 HTML 数据驱动模式：events.jsonl 不再带

viewport / anchor.rect / frameRef，而是按 hint.kind 在 after event 上挂 payload

（list/item/tree/global/navigation 五种 shape）。@js-eyes/visual-replay-hyperframes

按 payload 渲 reddit-style 卡片视频。详见

`docs/dev/visual-cookbook.md`。

`--redact-rect / --redact-selector / --redact-config / --visual-record-frames /

--visual-frames-throttle` 仍解析但不会下发，stderr 会打一行 deprecation 提醒。

# 默认开启：staged 详细级别，flash + HUD + 列表呼吸感 + 评论树 relation 线
node index.js list-subreddit AskReddit --limit 8
 
# 仅 HUD（不在页面 DOM 上画 flash overlay；v0.6.0 取代 --visual-mode hud）
node index.js search "nodejs" --no-visual-flash
 
# 关掉视觉，回到 3.4.x 的纯日志风格
node index.js my-feed --no-visual