v3.0.0 to v3.0.0

---

name: js-zhihu-ops-skill

description: 知乎内容读取 skill，提供回答与专栏详情读取能力。

version: 3.0.0

metadata:

openclaw:

emoji: "\U0001F4D8"

homepage: https://github.com/imjszhang/js-eyes

requires:

bins:

- node

---

# js-zhihu-ops-skill

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

## 安全分级

- **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 工具

| 工具 | 类型 | 说明 |

| ---- | ---- | ---- |

| `zhihu_get_answer` | READ | 读取知乎回答详情 |

| `zhihu_get_article` | READ | 读取知乎专栏详情 |

| `zhihu_session_state` | READ | 读取登录态、cookie 标记、登录墙/验证码状态 |

| `zhihu_get_question_answers` | READ | 读取问题页标题、描述和回答摘要列表 |

| `zhihu_search` | READ | 读取搜索结果 |

| `zhihu_get_user` | READ | 读取用户主页资料 |

| `zhihu_get_user_answers` | READ | 读取用户回答列表摘要 |

| `zhihu_get_user_articles` | READ | 读取用户文章列表摘要 |

| `zhihu_navigate_*` | INTERACTIVE | answer / article / question / search / user / home 导航 |

| `zhihu_monitor_*` | READ | list/status/add/remove/test 监控配置工具 |

## CLI

```bash

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 会失败并返回非零退出码。

```bash

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 工具列表。

## 架构

```text

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

```