imjszhang/js-eyes/js-zhihu-ops-skill

js-zhihu-ops-skill

面向知乎内容读取的 skill。v3.0 起按 PAGE_PROFILES + Bridges + Session 架构升级，支持回答、专栏、问题、搜索、用户、首页多个 profile，并保留 JS_ZHIHU_DISABLE_BRIDGE=1 旧脚本 fallback。

浏览器兼容性与登录

• 要求 Node.js 22+、JS Eyes 2.8.5+、已连接的浏览器扩展与运行中的 Server。
• 页面 bridge 需要宿主设置 security.allowRawEval: true；JS Eyes 2.5+ 会同步到扩展，扩展侧显式 false 仍可强制关闭。
• Chrome 要求 135+；Chrome 138+ 还需开启浏览器控制的 Allow User Scripts。
• 公开内容通常可匿名读取；搜索、连续分页或触发登录墙后的页面依赖浏览器已有登录态。本 Skill 不执行登录自动化。

安全分级

• READ：zhihu_get_answer、zhihu_get_article、zhihu_session_state、zhihu_get_question_answers、zhihu_search、zhihu_get_user、zhihu_get_user_answers、zhihu_get_user_articles。
• INTERACTIVE：zhihu_navigate_*。仅 location.assign 导航，不模拟点击、不改 DOM。
• DESTRUCTIVE：不引入。本文档不提供回答发布、评论、点赞、收藏、关注等能力。

提供的 AI 工具

CLI

node skills/js-zhihu-ops-skill/index.js answer "https://www.zhihu.com/question/1/answer/2" --pretty
node skills/js-zhihu-ops-skill/index.js article "https://zhuanlan.zhihu.com/p/123456" --pretty
node skills/js-zhihu-ops-skill/index.js session-state --pretty
node skills/js-zhihu-ops-skill/index.js doctor --pretty
node skills/js-zhihu-ops-skill/index.js records --last 5 --pretty
node skills/js-zhihu-ops-skill/index.js question-answers "https://www.zhihu.com/question/1" --limit 10 --max-pages 2 --pretty
node skills/js-zhihu-ops-skill/index.js search "大模型" --limit 10 --max-pages 2 --pretty
node skills/js-zhihu-ops-skill/index.js user "people-slug" --pretty
node skills/js-zhihu-ops-skill/index.js monitor init --pretty
node skills/js-zhihu-ops-skill/index.js monitor add search "大模型" --limit 10 --pretty

真实浏览器 Smoke

真实浏览器 smoke 是显式 opt-in 的本机验证，不会随 npm test 自动执行。运行前需要：

• js-eyes server 已启动，浏览器扩展可连接。
• 知乎相关域名已加入 egress allowlist：zhihu.com、www.zhihu.com、zhuanlan.zhihu.com。
• 浏览器里有可复用的知乎 tab，或允许脚本打开知乎页面。
• 当前登录态足以读取所选公开样本；遇到登录墙、验证码或页面结构漂移时 smoke 会失败并返回非零退出码。

npm run smoke:browser
npm run smoke:browser -- --only answer,search
npm run smoke:browser -- --samples path/to/local.samples.json
npm run smoke:browser -- --server ws://localhost:18080 --timeout-ms 120000
npm run verify:visual

默认样本位于 scripts/_dev/smoke-browser.samples.json，只包含公开 URL、slug 和关键词。可通过 --samples <path> 指向本机私有样本文件，但不要把 cookie、token 或账号私密信息写入样本。建议维护 sampleHealth 字段（minFilledFields / minListSampleCount / replaceStrategy / lastReviewedAt）并定期轮换失效公开样本，降低内容漂移导致的假失败。

READ 调度

知乎当前以 DOM 抽取为主，readMode 支持 auto|dom|api，默认 dom。api 暂不作为主路径，后续若接入稳定公开数据源再启用。

每次 READ 返回顶层包含 run、metrics、result、triedMethods、usedMethod、readMode、requestedReadMode、fallback、antiCrawlState。antiCrawlState 会区分 login_required、captcha_required 等页面阻断。

列表类 READ 工具（zhihu_get_question_answers、zhihu_search、zhihu_get_user_answers、zhihu_get_user_articles）支持 limit 与 maxPages：

• limit 是目标返回条数，默认 10，最多 100。
• maxPages 是 DOM 最大滚动轮次，默认 1，最多 20；它不是知乎业务页码，也不代表 API cursor 翻页。
• 返回结果会带 pageInfo，包含 requestedLimit、requestedMaxPages、returnedCount、scrollRounds、endedReason、duplicateSkipped 和 blockedReason。
• endedReason 统一为 limit / no_new_items / max_pages / blocked。
• 为降低风控风险，默认只读首轮 DOM；需要更多结果时显式提高 --max-pages，并配合 --timeout-ms。

Recording

js-zhihu-ops-skill 现已接入统一的 skill recording 底座，支持调用历史、结果缓存和调试记录。

• 默认记录模式跟随 js-eyes 全局配置中的 recording.mode
• CLI 可覆盖：
• --recording-mode off|history|standard|debug
• --debug-recording
• --no-cache
• --recording-base-dir /absolute/path
• --run-id custom-id

默认按技能分目录落盘到 ~/.js-eyes/skill-records/js-zhihu-ops-skill/，其中包含：

• history/：按月滚动的调用历史 jsonl
• cache/<toolName>：按工具维度区分的结构化缓存
• debug/：调试模式下的页面步骤、DOM 统计和结果快照

v3.0 新增 records 子命令，可查看最近 history 行。缓存命名空间改为工具名维度，旧 answer/article 脚本仍可通过 JS_ZHIHU_DISABLE_BRIDGE=1 使用。

Visual / 治理

CLI 支持 --visual、--visual-trace [path]、--visual-record [dir]，并会在 visual.traceFile / visual.recordDir 下写入事件与可选帧文件（开启 --visual-record 时）。知乎版治理包含：

• 登录墙、验证码、空白页、页面结构漂移的阻断识别。
• --rate-limit 或 JS_ZHIHU_RATE_LIMIT=1 启用单进程限流。
• 批量工具保守限制 limit / maxPages / timeoutMs，避免长跑触发风控。

Monitor 子系统

监控配置落在 ~/.js-eyes/skill-data/js-zhihu-ops-skill/monitor/config.json，可用 JS_ZHIHU_MONITOR_HOME 覆盖。支持 users、questions、searches 三类 target。

AI 工具只开放 list/status/add/remove/test，其中 add/remove 仅写 config，不发通知；test 是 URL dry-run，不写 state。长跑 daemon、主动通知和 webhook 发送不进入 AI 工具列表。

架构

skills/js-zhihu-ops-skill/
  SKILL.md
  package.json
  index.js                     委托 cli/index.js
  skill.definition.js          工厂化 + AI 工具表
  cli/index.js                 dispatcher（读 lib/commands.js）
  lib/
    config.js                  PAGE_PROFILES（answer/article/question/search/user/home）
    session.js                 主调度器（tab 选择 + bridge 注入）
    runTool.js                 READ 主管道（readMode + audit + history/cache/debug）
    commands.js                CLI 声明式映射
    toolTargets.js             工具参数 → URL
    runMonitor.js              monitor 工具定义与配置操作
    monitor/
      config.js
      dispatcher.js
      paths.js
    runtimeConfig.js           server/recording 配置
    @js-eyes/client-sdk        BrowserAutomation
    zhihuUtils.js              旧脚本 fallback 抽取器
  bridges/
    common.js                  DOM helpers + sessionState + blocker detect
    answer-bridge.js
    article-bridge.js
    question-bridge.js
    search-bridge.js
    user-bridge.js
    home-bridge.js
  scripts/
    zhihu-answer.js            fallback（JS_ZHIHU_DISABLE_BRIDGE=1）
    zhihu-article.js           fallback（JS_ZHIHU_DISABLE_BRIDGE=1）
  tests/                       node --test