@geoly-ai/social-hub-cli 0.3.15 → 0.3.17

package/skills/reddit-voc-volume/references/arctic-shift.md

@@ -1,6 +1,6 @@
-# Arctic Shift 归档后端（v2.12.27 新增）
+# Arctic Shift 归档后端（v2.12.27；v2.12.31 增加评论正文）
 
-> **何时读本文件：** 使用 `history` 模式，或 Emergency Acquisition 落到
+> **何时读本文件：** 使用 `history` / `comments` 模式，或 Emergency Acquisition 落到
 > `--backend arctic-shift`（缺省）时。判断某个字段能不能用，以本文件的
 > 「能力边界」表为准。
 
@@ -31,6 +31,7 @@ failed 403`，去掉代理直连亦为 `403 Blocked`）。Arctic Shift 不走 re
 | 能力 | 可用性 | 说明 |
 |---|---|---|
 | 正文全文 / 长度分布 / 语料 | ✅ 全程 | baseline 卡长度维度的合法来源 |
+| 评论正文 / 评论树 | ✅ | `/api/comments/tree|search|ids`；保留 `parent_id`，适合历史 VOC |
 | `num_comments` | ✅ 有回填 | 可用于声量 |
 | `upvote_ratio` | ✅ 有回填 | 可用 |
 | 版规 `/api/subreddits/rules` | ✅ | 替代 `/about/rules.json` |
@@ -39,6 +40,28 @@ failed 403`，去掉代理直连亦为 `403 Blocked`）。Arctic Shift 不走 re
 | 此刻置顶 / 当前 hot | ❌ | 归档无 live 语义，走 Hub |
 | About 页周指标 / Installed Apps | ❌ | 渲染页专有，走 Social Hub / Firecrawl |
 
+### 评论端点（v2.12.31）
+
+| 端点 | 用途 | 硬上限 |
+|---|---|---:|
+| `/api/comments/tree?link_id=t3_<post_id>` | 读取帖子评论树；超限/宽深度折叠返回 `kind=more` | 25,000 |
+| `/api/comments/search?link_id=<post_id>` | 按 `body`、`author`、`after/before`、`parent_id` 筛选 | 100 |
+| `/api/comments/ids?ids=...` | 按裸/t1_ 评论 ID 批查 | 500 |
+
+Skill 入口统一为 `comments`。默认 tree；扁平 item 保留完整 `body`、原始
+`link_id` / `parent_id`，并补 `depth` / `sibling_index` / `tree_order` /
+`tree_path` / `child_ids`。`kind=more` 单独进入 `collapsed[]`；只要存在折叠节点，
+`tree_complete=false`，不得声称已经拿到完整评论树。请求失败或响应不是合法
+`data[]` 树时也必须 `ok=false`、`tree_complete=false`，不能因为 `collapsed=[]`
+误报完整。
+
+`parent_id` 语义按端点区分：tree 只接受裸/t1_ 评论 ID（取子树）；search 的
+`--parent-id top|root` 会显式发送空 `parent_id=` 以筛顶层评论，不能伪造成 t3_ post ID。
+
+评论数据也受本归档约束：最新通常滞后约 2 小时，服务无 uptime 保证；评论
+`score_status=ArchivedSnapshot` 且 `score_realtime=false`，只把正文用于历史 VOC，
+不要把 score 当当前热度。
+
 ### `score` 为什么不可信（v2.12.28 实测修正）
 
 **失真集中在新帖，不是旧帖。** 早期只抽老帖时看到的误差很小（归档 1 → 实时 1~6），
@@ -99,6 +122,13 @@ python3 "$VOC" history -r BuyItForLife --after 2024-01-01 --before 2024-03-31 --
 # 关键词 + 跨板块历史
 python3 "$VOC" history "noise cancelling" -r headphones -r audiophile --after 2023-01-01 --pretty
 
+# 帖子历史评论树（默认最多 25,000）
+python3 "$VOC" comments "https://www.reddit.com/r/example/comments/abc123/slug/" --pretty
+
+# 评论正文筛选 / ID 批查
+python3 "$VOC" comments abc123 --source search --body "battery life" --parent-id top --pretty
+python3 "$VOC" comments --ids t1_def456 ghi789 --pretty
+
 # Emergency Acquisition 显式指定后端（缺省已是 arctic-shift）
 python3 "$VOC" keyword "PLAUD recorder" --backend arctic-shift --pretty
 python3 "$VOC" keyword "PLAUD recorder" --backend reddit-json --pretty   # 旧的 .json + curl
@@ -112,13 +142,18 @@ python3 "$VOC" keyword "PLAUD recorder" --backend reddit-json --pretty   # 旧
 - `score_status_counts`：三态计数
 - `body_stats`：`with_text` / `max_chars` / `median_chars`
 - 每条 item：`score_status`、`archived_at_post_time`、`source_fetch="arctic_shift"`
+- `comments`：`retrieval_mode=tree|search|ids`、`tree_complete`、`collapsed[]`、
+  `body_stats`；每条评论含完整 `body`、`parent_id` 与树坐标，score 明标非实时
 
 ## 与 Hub 的关系
 
-**不是替代，是互补。** Hub 有 live 语义和可信 score，Arctic 有历史深度和全文。
+**不是替代，是互补。** Hub 有 live 语义和可信 score，Arctic 有历史深度、帖子全文和评论正文。
 Hub-First 的四级链路不变；Arctic 只替换 L3 Emergency Acquisition 的**实现**，
 不改变它在链路中的位置——Hub 可用时永远优先走 Hub。
 
+`comments` 是明确的历史归档读取例外：和 `history` 一样固定直连 Arctic，不先查 Hub、
+不派发、不接受 `--acquisition-policy`。
+
 
 ## 实时核验（v2.12.28）
 

package/skills/reddit-voc-volume/references/hub-first.md

@@ -2,13 +2,13 @@
 
 矩阵**当下声量 / 证据类** Reddit 公开数据消费遵循四级链路:**Hub Cache → Hub Dispatch → Emergency Acquisition → Hub Write-back**。本地采集(本 skill 的 Python 工具)正式定名 **Emergency Acquisition**——它不是与 Hub 并列的默认链路,只在 Hub 失败/离线且急用时启用。
 
-> **`history` 模式不在本链路内。** 历史/往年数据/时间窗回溯/长期趋势/建 baseline 卡的历史样本固定走 Arctic Shift 深度归档(权威源),**不查 Hub、不派发、不读 acquisition-policy**——Hub 只有近实时缓存、不持有深度归档,对历史意图先撞 Hub 是浪费且拿不到。历史意图请直接执行 `history` 模式,不要套用下述四级链路。
+> **`history` / `comments` 模式不在本链路内。** 历史帖子与归档评论正文固定走 Arctic Shift 深度归档(权威源),**不查 Hub、不派发、不读 acquisition-policy**——Hub 只有近实时缓存、不持有深度归档。历史帖子用 `history`，帖子历史评论正文/评论树用 `comments`，不要套用下述四级链路。
 
 前置:Social Hub CLI ≥0.2.10 已安装、`auth login`、`context use`(见 SETUP.md capability probe)。
 
 ## acquisition-policy
 
-acquisition-policy 作用于 `keyword` / `subreddit` 以及注册了该参数的证据类模式(`stickies` / `about-page` / `page-signals` / `flair-filters`);`links` 无此参数、按 `no_hub_dispatch_path` 例外处理,而 **`history` 模式根本不注册该参数(固定 Arctic,见上方例外框),显式传入会报错**。执行者按用户指定(缺省 `hub-first`)选择策略:
+acquisition-policy 作用于 `keyword` / `subreddit` 以及注册了该参数的证据类模式(`stickies` / `about-page` / `page-signals` / `flair-filters`);`links` 无此参数、按 `no_hub_dispatch_path` 例外处理,而 **`history` / `comments` 根本不注册该参数(固定 Arctic,见上方例外框),显式传入会报错**。执行者按用户指定(缺省 `hub-first`)选择策略:
 
 | 策略 | 行为 |
 |---|---|
@@ -30,7 +30,7 @@ python3 scripts/reddit_voc_volume.py subreddit "packaging leak" -r foodpackaging
 | 本 skill 模式 | 先执行的 Hub 查询 |
 |---|---|
 | search / subreddit(VOC 综合) | `social-hub intelligence voc-query --brand-keywords ... [--subreddits ...] [--need-comments] [--need-rules-evidence]`(不带 --dispatch-on-gap = 纯评估) |
-| 评论采样 | `social-hub intelligence comments --subreddit ... [--keyword ...] [--intent ...] [--sentiment ...]` |
+| 当下/Hub 评论采样 | `social-hub intelligence comments --subreddit ... [--keyword ...] [--intent ...] [--sentiment ...]`；帖子历史归档评论改走本 skill `comments`，不走本表链路 |
 | about-page / page-signals / flair-filters / rules / wiki / pinned / installed-apps | `social-hub intelligence evidence-status --subreddit ...` → 有 fresh 的用 `evidence-list --subreddit ... --type ... --fresh-only` 取正文/信号 |
 | 热帖 | `social-hub intelligence hot-posts [--subreddit ...] [--sort ...]` |
 | links(任意 permalink 详情) | L1 查 `hot-posts`(可能未采集过而未命中);**该模式无专用 L2 派发**——未命中时允许直接 L3(fallbackReason=self_crawl_forced 不需要,记 no_hub_dispatch_path),产出必须回灌 `hot-posts-create`(帖子)/`comments-import`(评论);rules/wiki/about 类 URL 仍按证据模式走 evidence-status/evidence-fetch |
@@ -59,7 +59,7 @@ python3 scripts/reddit_voc_volume.py subreddit "packaging leak" -r foodpackaging
 
 ## L4:Hub Write-back(回灌)
 
-Emergency Acquisition 的产出**必须**尝试回灌。`keyword` / `subreddit` 已自动逐帖调用 `hot-posts-create`;证据型本地 item 会调用 `evidence-import`。本地脚本当前不批量采评论正文,因此只有真实存在的评论 item 才可调用 `comments-import`,不得根据帖子 `num_comments` 伪造评论:
+Emergency Acquisition 的产出**必须**尝试回灌。`keyword` / `subreddit` 已自动逐帖调用 `hot-posts-create`;证据型本地 item 会调用 `evidence-import`。只有真实存在的评论 item 才可调用 `comments-import`,不得根据帖子 `num_comments` 伪造评论。注意：`comments` 是历史归档直读模式，不是 L3 Emergency Acquisition，当前输出明确为 `writebackStatus=not_applicable`，不会自动回灌 Hub：
 
 ```bash
 # 帖子 → hot-posts-create(逐条)
@@ -75,7 +75,7 @@ social-hub intelligence evidence-import -j '{"subreddit":"...","evidenceType":"r
 - `notVisible:true` 必须带 `visibilityEvidence`(页面明示不可见的原文片段),且不得与 content 同传。
 - 回灌失败:输出 `writebackStatus=failed` + 保留本地产物与重试指引(端点幂等,可安全重试);成功 `done`;Hub 离线暂存 `pending`。
 
-## 输出信封(所有模式,旧字段全保留)
+## 输出信封(Hub-First 模式,旧字段全保留)
 
 最终 JSON 在原有结构上**新增**(不修改不删除既有字段,旧下游无需改解析器):
 
@@ -95,6 +95,10 @@ social-hub intelligence evidence-import -j '{"subreddit":"...","evidenceType":"r
 }
 ```
 
+固定归档模式使用来源专属信封：`history` / `comments` 的
+`provenance=arctic_shift`、`runId/hubRunId=null`、`writebackStatus=not_applicable`；
+`comments` 另带 `archive_caveats`，归档 score 不得解释为实时值。
+
 **runId 语义(v2.12.23 起)**:`runId` 只指向产出当前 items 的 run;`hubRunId` 记录本次任务涉及的派发 run(含失败/超时的),两者不可混用。`itemsUnavailable=true` 时脚本 `ok=false`,执行者应改用 `social-hub intelligence hot-posts/comments/evidence-list` 直接读 Hub 记录,不得据此转本地采集(coverage 已满足,数据在 Hub)。
 
 **v2.12.23 起 evidence 模式同样脚本内编排**:`stickies`(pinned)/`about-page`(about)/`flair-filters`(flair)与 subreddit 范围的 `page-signals`(page_signals)默认执行 `evidence-status → fresh 读 evidence-list --fresh-only → 缺口派 evidence-fetch --types → runs 轮询(共享退避/硬超时/定向重派一次)→ 仅 failed/timeout/unreachable 才本地`。非 subreddit 范围的 page-signals URL 与 `links` 一样走 `no_hub_dispatch_path` 例外(允许直接 L3+回灌)。