js-zhihu-ops-skill · v3.0.0 · 2026-05-06 · sha256 db75afd319682b1e
js-zhihu-ops-skill v3.0.0A
Immutable. This exact content is served forever at /api/v1/blob/db75afd319682b1e.
---
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.contract.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.js 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
```