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

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@geoly-ai/social-hub-cli` are documented in this file.
 
 Release workflow: `pnpm release:cli` → `pnpm publish:cli`.
 
+## [0.3.16] - 2026-08-10
+
+Add Arctic Shift archived comment bodies, reconstructable comment trees, filtered search, and comment-ID lookup to reddit-voc-volume.
+
+### Added
+
+- Reddit VOC 支持 Arctic 历史评论正文与评论树
+
 ## [0.3.15] - 2026-08-09
 
 评论样本精确 count 读口:GET /v1/system/subreddit-intelligence/comments/count + SDK countRedditCommentSamples + CLI intel comments-count(不封顶、无分页、拒绝 keyword;行级授权语义与 comments 列表一致)

package/dist/cmd-manifest.json

@@ -1,6 +1,6 @@
 {
-  "generatedAt": "2026-08-09T09:26:27.640Z",
-  "cliVersion": "0.3.15",
+  "generatedAt": "2026-08-11T01:41:10.558Z",
+  "cliVersion": "0.3.16",
   "commands": [
     "accounts",
     "accounts brand-bindings",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/social-hub-cli",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "type": "module",
   "description": "social-hub CLI for Social Ops Hub",
   "repository": {

package/skills/README.md

@@ -156,7 +156,7 @@ pnpm skills:check
 | [reddit-content-writing](reddit-content-writing)             | 主帖批量写作（9 主帖型 × 7 写作变体）                    |
 | [reddit-content-rewrite](reddit-content-rewrite)             | 约束保持的帖/评/标题修复改写                             |
 | [reddit-delivery-check](reddit-delivery-check)               | 阶段 5 交付 QA：覆盖/完整性/多样性/合规校验              |
-| [reddit-voc-volume](reddit-voc-volume)                       | VOC 声量采集 + Arctic 历史回溯 + Firecrawl 兜底          |
+| [reddit-voc-volume](reddit-voc-volume)                       | VOC 声量采集 + Arctic 历史帖子/评论树 + Firecrawl 兜底   |
 | [reddit-brand-risk-response](reddit-brand-risk-response)     | 品牌风险 triage/预防/聚合方向分析                        |
 | [reddit-subreddit-compliance](reddit-subreddit-compliance)   | subreddit 合规与板块适配检测（版规/发帖前风险）          |
 | [reddit-answers-research](reddit-answers-research)           | Reddit 官方 Ask AI 研究 → 提取引用帖取证                 |

package/skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "package": "social-ops-hub",
-  "cliVersion": "0.3.15",
+  "cliVersion": "0.3.16",
   "repository": "social-ops-hub",
   "publish": {
     "registry": "https://skill.sh",
@@ -152,7 +152,7 @@
     {
       "id": "reddit-voc-volume",
       "path": "reddit-voc-volume",
-      "description": "VOC 声量采集：关键词/品牌词搜索 + subreddit 扫描 + Arctic 历史回溯（全文不截断）+ Firecrawl 兜底"
+      "description": "VOC 声量采集：关键词/品牌词搜索 + subreddit 扫描 + Arctic 历史帖子/评论正文与评论树 + Firecrawl 兜底"
     },
     {
       "id": "reddit-brand-risk-response",

package/skills/reddit-matrix.lock.json

@@ -28,7 +28,7 @@
       "contentSha256": "234d7fd1d8f2db68444674c20418c836c1b2488305b20399114dec89a0de32fc"
     },
     "reddit-voc-volume": {
-      "contentSha256": "00e0675d6c77d5c08f3232fa7b6a7ecd8bea6d75b0ebeb67ae01254483695639"
+      "contentSha256": "45332556a0835a5c16386cb31550c04ea2447e2326a7a4ff15fd050f1ae91d55"
     },
     "reddit-brand-risk-response": {
       "contentSha256": "dbba80345ebe68818a25e7604dfaa6951c6bf0e4d785d5013be7a06b22ec5b7c"

package/skills/reddit-voc-volume/SKILL.md

@@ -1,20 +1,21 @@
 ---
 name: reddit-voc-volume
 description: |
-  获取 Reddit VOC 声量、历史帖文与公开 URL 证据：按关键词/品牌词搜索、指定 subreddit 扫描、批量链接汇总帖子量/评论量/score/子版分布，**按时间窗回溯 2005 年至今的历史帖子（正文全文，不截断）**，读取版规/wiki/subreddit 元数据，并通过 Social Hub 或自托管 Firecrawl 读取公开 About 页周访客/周贡献/周活跃用户兼容字段、Installed Apps、flair filters、通用 page_signals，以及**核验归档 score 与版规是否仍然现行**，输出结构化 JSON。
-  用户提到 Reddit VOC、品牌词/竞品讨论量、subreddit 声量、帖子评论量统计、舆情采样、批量 Reddit 链接、about/rules/wiki、版规、**历史帖子/往年数据/时间窗回溯/某年某月的帖子/长期趋势**、置顶帖/pinned/sticky/megathread、公开 About 页周指标、Installed Apps、flair filters、页面公开链接信号，或需要**建 subreddit baseline 卡/统计正文长度分布**时必须用本 skill。
+  获取 Reddit VOC 声量、历史帖文、**历史评论正文/完整评论树**与公开 URL 证据：按关键词/品牌词搜索、指定 subreddit 扫描、批量链接汇总帖子量/评论量/score/子版分布，**按时间窗回溯 2005 年至今的历史帖子（正文全文，不截断）**，按帖子 URL/ID 从 Arctic Shift 拉取归档评论树或筛选/ID 批查评论正文，读取版规/wiki/subreddit 元数据，并通过 Social Hub 或自托管 Firecrawl 读取公开 About 页周访客/周贡献/周活跃用户兼容字段、Installed Apps、flair filters、通用 page_signals，以及**核验归档 score 与版规是否仍然现行**，输出结构化 JSON。
+  用户提到 Reddit VOC、品牌词/竞品讨论量、subreddit 声量、帖子评论量统计、**历史评论/评论正文/评论树/thread replies**、舆情采样、批量 Reddit 链接、about/rules/wiki、版规、**历史帖子/往年数据/时间窗回溯/某年某月的帖子/长期趋势**、置顶帖/pinned/sticky/megathread、公开 About 页周指标、Installed Apps、flair filters、页面公开链接信号，或需要**建 subreddit baseline 卡/统计正文长度分布**时必须用本 skill。
   v2.12.28 起 reddit `.json` 直采已全部移除：搜索/帖子/about/版规/wiki 一律走 Arctic Shift 归档 API（`history` 模式 + Emergency Acquisition），正文不截断；归档 `score` 带 `score_status`，只有 `Backfilled`/`VerifiedLive` 可用于声量，`--verify-scores` / `--verify-rules` 用 Firecrawl 渲染页核验实时值。**置顶是 live 语义，本地已无采集途径，只能走 Social Hub**，取不到标 NotVisible，不得用归档 stickied 代替。
   **历史数据类意图直连 Arctic，不走 Hub-First**：历史帖子 / 往年数据 / 时间窗回溯 / 某年某月 / 长期趋势 / 建 subreddit baseline 卡需历史样本，一律直接路由到 `history` 模式(Arctic Shift 深度归档，权威源，正文不截断)，**不经 Hub-First 四级链路**——Hub 只有近实时缓存、不持有深度归档，历史查 Hub 是浪费且拿不到。仅「当下声量」类(`keyword` / `subreddit` 及证据类模式)才走 Hub-First。
-  Hub-First 链路(仅当下声量/证据类，不含 history)：`keyword` / `subreddit` 及证据类模式先查 Social Hub(voc-query/evidence-status)，缺口由 Hub 派发(dispatch-on-gap/evidence-fetch)并轮询 runs(partial 定向重派一次)；仅 Hub failed/timeout/unreachable 才进入本地 Emergency Acquisition，本地成功结果自动回灌 Hub(hot-posts-create/evidence-import)，coverage 满足但读不到 items 时输出 itemsUnavailable 而非假成功。不用于全站爬取、绕过登录墙或读取 mod 后台。
+  Hub-First 链路(仅当下声量/证据类，不含 history/comments)：`keyword` / `subreddit` 及证据类模式先查 Social Hub(voc-query/evidence-status)，缺口由 Hub 派发(dispatch-on-gap/evidence-fetch)并轮询 runs(partial 定向重派一次)；仅 Hub failed/timeout/unreachable 才进入本地 Emergency Acquisition，本地成功结果自动回灌 Hub(hot-posts-create/evidence-import)，coverage 满足但读不到 items 时输出 itemsUnavailable 而非假成功。不用于全站爬取、绕过登录墙或读取 mod 后台。
+  v2.12.31 新增 `comments`：默认 `/api/comments/tree` 拉取最多 25,000 条归档评论并保留层级；也支持 `/api/comments/search` 筛选及 `/api/comments/ids` 最多 500 ID 批查。该模式固定直连 Arctic，不走 Hub-First；归档通常滞后约 2 小时且无 uptime 保证，评论 `score` 不是实时值。
 ---
 
 # Reddit VOC 声量
 
-按**关键词**、**subreddit** 或 **Reddit URL 列表** 采样 Reddit 公开讨论声量和公开页面证据，输出统一 JSON。适合品牌词/竞品 VOC、子版讨论量、帖子互动汇总，以及 subreddit about/rules/wiki 的 DataAcquisition。
+按**关键词**、**subreddit**、**Reddit URL 列表**或**帖子历史评论**采样 Reddit 公开讨论声量和公开页面证据，输出统一 JSON。适合品牌词/竞品 VOC、子版讨论量、帖子互动汇总、历史评论正文分析，以及 subreddit about/rules/wiki 的 DataAcquisition。
 
 ## Arctic Shift 归档后端(v2.12.27)
 
-`history` 模式与缺省的 `--backend arctic-shift` 走 Arctic Shift 归档 API，不经
+`history` / `comments` 模式与缺省的 `--backend arctic-shift` 走 Arctic Shift 归档 API，不经
 reddit.com。**使用前读 [references/arctic-shift.md](references/arctic-shift.md)**，
 尤其是「能力边界」表：正文 / `num_comments` / `upvote_ratio` / 版规 / wiki 可用；
 **`score` 不可信**（实测约 1/3 归档行是发帖瞬间的陈旧值，逐条标 `score_status`，
@@ -32,13 +33,13 @@ reddit.com。**使用前读 [references/arctic-shift.md](references/arctic-shift
 
 **边界（勿把"近期"误判为历史）**：「最近一天 / 一周 / 一月、本周、本月、当前热度」仍是**当下声量**，走 `keyword` / `subreddit` Hub-First（Hub 侧另有 `--hub-time-window day|week|month` 覆盖近实时窗口）；只有上面那种绝对日期 / 跨年 / 早于 Hub 覆盖 / 历史基线的意图才进 `history`。长期趋势应**按月 / 年分桶多次查询**，不要把单次 `--limit` 样本当成完整总体。
 
-`history` 模式在脚本层就固定走 `arctic_search_posts`，**不接受 `--acquisition-policy`**（`history` 子命令未注册该参数，显式传入会直接报错退出），`provenance` 恒为 `arctic_shift`。对历史意图先撞 Hub 是错误引导——Hub 会返回近实时缓存空窗或缺口，既浪费一次派发轮询又拿不到深归档。
+`history` 模式在脚本层就固定走 `arctic_search_posts`；历史评论固定走 `comments`。两者都**不接受 `--acquisition-policy`**（子命令未注册该参数，显式传入会直接报错退出），`provenance` 恒为 `arctic_shift`。对历史意图先撞 Hub 是错误引导——Hub 会返回近实时缓存空窗或缺口，既浪费一次派发轮询又拿不到深归档。
 
 当下声量（`keyword` / `subreddit`）与证据类（rules/wiki/about/pinned/flair）仍按下节 Hub-First。Arctic 后端只是 `keyword` / `subreddit` 的 L3 Emergency Acquisition **实现**（证据 live 类的本地兜底是 Firecrawl，stickies 本地无有效采集路径），不改变 Hub 优先级——这些模式 Hub 可用时永远优先走 Hub。
 
 ## Hub-First 数据链路(v2.12.25,必读)
 
-> **例外:`history` 模式不适用 Hub-First。** 历史/时间窗/往年数据固定走 Arctic Shift 归档(见上节路由),不查 Hub、不派发、不读 acquisition-policy。本节只约束 `keyword` / `subreddit` 及证据类模式。
+> **例外:`history` 与 `comments` 模式不适用 Hub-First。** 历史/时间窗/往年数据及归档评论正文固定走 Arctic Shift 归档(见上节路由),不查 Hub、不派发、不读 acquisition-policy。本节只约束 `keyword` / `subreddit` 及证据类模式。
 
 **执行当下声量 / 证据类模式前,先读 [references/hub-first.md](references/hub-first.md)** 并按 acquisition-policy(缺省 hub-first)走四级链路:**Hub Cache → Hub Dispatch → Emergency Acquisition → Hub Write-back**。要点:
 
@@ -117,6 +118,16 @@ python3 "$VOC" flair-filters -r espresso \
 python3 "$VOC" history -r BuyItForLife --after 2024-01-01 --before 2024-03-31 --pretty
 python3 "$VOC" history "noise cancelling" -r headphones -r audiophile --after 2023-01-01 --pretty
 
+# 历史评论正文：默认完整树（最多 25,000），保留 parent_id/depth/tree_path/order
+python3 "$VOC" comments "https://www.reddit.com/r/example/comments/abc123/slug/" --pretty
+
+# 平面筛选（最多 100）：正文关键词、作者、时间、父评论；top 表示顶层评论
+python3 "$VOC" comments t3_abc123 --source search --body "battery life" \
+  --author example_user --after 2024-01-01 --parent-id top --sort asc --pretty
+
+# 按评论 ID 批查（最多 500；空格或逗号分隔）
+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
@@ -155,6 +166,7 @@ python3 "$VOC" links \
 | `keyword` | Hub-First 全站关键词 VOC | positional `query`；`--acquisition-policy hub-first/hub-only/self-first`；`--hub-poll-timeout-sec`；sort/time |
 | `subreddit` | Hub-First 子版内关键词 VOC | `-r/--subreddit` 可重复；同上 acquisition-policy/sort/time |
 | `links` | 批量 Reddit URL；支持帖子 permalink、subreddit about、about/rules、wiki 页面；可显式启用 Social Hub / Firecrawl 页面 fallback | URL 列表或 `--file`；`--fallback social-hub/firecrawl/auto` |
+| `comments` | **v2.12.31 新增。** 从 Arctic Shift 读取帖子历史评论正文；默认树模式，另有筛选搜索和评论 ID 批查 | positional 帖子 URL/ID；`--source tree/search`；`--body` / `--author` / `--after` / `--before` / `--parent-id`；`--ids` |
 | `stickies` | 从 subreddit hot listing 低频读取 `stickied=true` 置顶帖 | `-r/--subreddit` 可重复；`--limit` 控制 hot listing 读取数量 |
 | `about-page` | 用 Social Hub 或自托管 Firecrawl 渲染公开 subreddit About 页，提取 weekly visitors、weekly contributions、weekly active users 兼容字段、公开 Installed Apps | `-r/--subreddit` 可重复；`--provider social-hub/firecrawl/auto`；`--firecrawl-base-url` |
 | `page-signals` | 用 Social Hub 或自托管 Firecrawl 渲染任意公开 Reddit 页，统一解析页面 links/Markdown 里的公开信号 | URL 列表或 `--file`；`--provider social-hub/firecrawl/auto` |
@@ -163,6 +175,35 @@ python3 "$VOC" links \
 | `firecrawl-check` | 检查本地/self-hosted Firecrawl 服务和 Docker 状态 | `--firecrawl-base-url` |
 | `social-hub-check` | 检查 Social Hub CLI scrape fallback 是否可用 | 无 |
 
+### comments 模式支持范围
+
+`comments <post-url-or-id>` 固定直连 Arctic Shift 历史归档，不查 Hub、不派发，也不接受
+`--acquisition-policy`。默认 `--source tree` 调用 `/api/comments/tree`，默认和硬上限均为
+25,000 条；输出把嵌套树扁平为 `item_type=comment`，正文 `body` 不截断，并保留原始
+`link_id` / `parent_id` 以及 `depth` / `sibling_index` / `tree_order` / `tree_path` /
+`child_ids`。因此下游既可直接做 VOC 文本分析，也能确定性还原层级与原顺序。
+
+若 Arctic 因上限或宽深度折叠返回 `kind=more`，这些节点不会伪装成评论；它们原样进入
+`collapsed[]`（含 `parent_id` / `children` / `count` / 树坐标），同时
+`tree_complete=false`。请求失败或响应不是合法的 Arctic `data[]` 评论树时同样输出
+`ok=false`、`tree_complete=false`；只有请求成功、结构合法且 `collapsed_count=0`
+才能把当次结果视为完整树。
+
+- `--source search` 调 `/api/comments/search`，上限 100；支持 `--body`（Arctic FTS）、
+  `--author`、`--after`、`--before`、`--parent-id` 与 `--sort asc|desc`。
+- search 模式的 `--parent-id top` / `root` 会按 Arctic 契约显式发送空
+  `parent_id=`，只取顶层评论；普通值可传裸 ID 或 `t1_` fullname。tree 模式只接受
+  评论 ID，用于返回该评论下的子树。
+- `comments --ids ...` 调 `/api/comments/ids`，最多 500 个裸/t1_ 评论 ID，按请求顺序
+  输出；缺失 ID 进入 `missing_comment_ids` 并令 `ok=false`，不会静默丢失；该模式不接受
+  `--source search`，避免静默忽略来源选择。
+- tree/search 的 limit 越界、ID 类型错误（例如把 `t3_` 当评论 ID）、非 Reddit URL、
+  不兼容参数组合都会在发网络请求前明确报错并退出 2。
+
+Arctic 是免费第三方归档，通常滞后约 2 小时且无 uptime 保证。评论 `body` 适合历史
+VOC；`score_status=ArchivedSnapshot`、`score_realtime=false` 是硬边界，评论 score
+不得写成实时热度。大批量全站处理使用 Arctic 月度 dump，不要循环刷免费 API。
+
 ### links 模式支持范围
 
 `links` 不再只按帖子 permalink 解析。它会按 URL 类型分流：
@@ -344,7 +385,8 @@ Social Hub / Firecrawl 只能提供公开 HTML/Markdown 页面证据；不要把
 
 脚本内置硬上限，优先避免 IP 风控：
 
-- 默认 `--limit 10`，硬上限 **50**（更大值自动截断）
+- keyword/subreddit/links 默认 `--limit 10`，硬上限 **50**（更大值自动截断）；
+  `comments` 使用 Arctic 官方端点上限：tree **25,000**、search **100**、IDs **500**，越界直接失败
 - 默认 `--sleep-sec 6`，每次请求后 **+1.5–4.5s** 随机抖动
 - 默认 `--max-pages 1`，单次运行最多 **20** 个 HTTP 请求
 - 遇 **429** → 立即熔断，输出 `rate_limited: true`
@@ -472,6 +514,7 @@ Cookie **仅**用于减少公开页误判，不用于私密版/验证码。输
 - `score` 是 Reddit 展示分，≠ 纯点赞数；`upvote_ratio` 更有参考价值。
 - `flair_*` 来自 Reddit post JSON 的 `link_flair_*` 字段；无 flair 时字段保持 `null` 或空数组。帖子 item 还包含公开 JSON 中可见的 `flair_template_id`、`flair_filter_query`、`author_flair_text`、`author_flair_type`、NSFW/spoiler/gallery/video 等辅助字段。
 - `item_type=post` 是帖子；`item_type=subreddit_about` / `subreddit_rules` / `wiki_page` 是非帖子公开页面证据，`score` / `num_comments` 置 0 仅为 schema 兼容。
+- `item_type=comment` 来自 `comments`，`body` 为不截断的归档评论正文；`parent_id` 加树坐标可还原层级。其 `score_status=ArchivedSnapshot`、`score_realtime=false`，不得当实时热度。
 - `item_type=pinned_post` 来自 `stickies` 模式，只代表 hot listing 中公开可见的 `stickied=true` 帖子；可作为 Pinned/Sticky/Megathread 证据输入 `reddit-subreddit-compliance`。
 - `item_type=firecrawl_page` 是 Social Hub / Firecrawl 页面 fallback 结果，含 `markdown_excerpt`、`html_excerpt`、`metadata`、`page_provider` 和 `page_signals`；只在 `--fallback social-hub|firecrawl|auto` 且 JSON 抓取失败或解析不到目标内容时出现。
 - `item_type=subreddit_about_page` 是 `about-page` 的 Social Hub / Firecrawl 渲染结果，含 `weekly_visitors`、`weekly_contributions`、`weekly_active_users`、`weekly_active_users_source`、`installed_apps`、`installed_apps_status`、`flair_filters`、`page_signals`、`page_provider`，只能作为公开渲染 About 页证据。
@@ -516,8 +559,8 @@ py -3 -m pip install -r $Requirements
 
 ## 与相关 skill 的分工
 
-- **`reddit-link-engagement`**：单链 score/评论树
-- **`reddit-voc-volume`**（本 skill）：关键词/subreddit/批量链接的**声量汇总 JSON**
+- **`reddit-link-engagement`**：单链互动核验
+- **`reddit-voc-volume`**（本 skill）：关键词/subreddit/批量链接的**声量汇总 JSON**，以及 Arctic 历史评论正文/评论树
 - **`reddit-food-packaging-intel`**：餐饮包装 Reddit 批量采集落盘 CSV
 
 ## HandoffContract
@@ -544,4 +587,5 @@ py -3 -m pip install -r $Requirements
 ## 评测
 
 - Eval 定义：[`evals/evals.json`](evals/evals.json)
+- 归档评论离线单测：`python3 -m unittest discover -s tests -p 'test_*.py'`
 - 工作区：`<repo>/.cursor/skills/reddit-voc-volume-workspace/`

package/skills/reddit-voc-volume/matrix-contract.md

@@ -16,6 +16,8 @@
 - public rendered subreddit About page metrics from Firecrawl `about-page`
 - visible Installed Apps links from the public rendered About page
 - post/comment sample metadata
+- archived comment bodies and reconstructable thread hierarchy from Arctic Shift
+  (`comments`; `parent_id` plus tree coordinates; archive score is not live)
 - public subreddit rules/wiki/about/submit-text evidence
 - public pinned/stickied/megathread evidence from subreddit hot listings
 
@@ -23,6 +25,13 @@
 
 Search/subreddit/post samples are preference signals only. They must not be used as subreddit rules, account-gate proof, Installed Apps proof, or AutoModerator policy evidence.
 
+`comments` bodies are historical VOC / preference evidence only. Consumers may reconstruct
+the thread from `parent_id`, `depth`, `sibling_index`, `tree_order`, and `tree_path`. They must
+require `tree_complete=true` before describing a result as the complete thread; otherwise
+`collapsed[]` records the unexpanded IDs. Fetch failures and malformed tree payloads explicitly
+set `tree_complete=false` even when `collapsed[]` is empty. `score_status=ArchivedSnapshot` and
+`score_realtime=false` are binding: archived comment scores cannot support current-hot claims.
+
 `links` output for `subreddit_rules`, `wiki_page`, and `subreddit_about` can be used
 as public source evidence for `reddit-subreddit-compliance`. VOC still does not
 interpret compliance risk; compliance must do that.

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+回灌)。

package/skills/reddit-voc-volume/scripts/reddit_voc_volume.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Reddit VOC volume sampler — keyword / subreddit / links / stickies modes.
+Reddit VOC volume sampler — keyword / subreddit / links / comments / stickies modes.
 Strict rate limits; browser-like JSON requests; no bulk crawling.
 """
 from __future__ import annotations
@@ -42,6 +42,8 @@ RETRY_BACKOFF_SEC = (30.0, 120.0)
 ARCTIC_BASE_URL = "https://arctic-shift.photon-reddit.com"
 ARCTIC_MAX_LIMIT = 100  # 单次上限；文档另有 "auto"，但会随服务器负载浮动，不用
 ARCTIC_IDS_MAX = 500
+ARCTIC_COMMENT_TREE_MAX = 25_000
+ARCTIC_COMMENT_SEARCH_MAX = 100
 ARCTIC_DEFAULT_TIMEOUT_SEC = 60.0
 ARCTIC_MAX_RETRIES = 3
 ARCTIC_MIN_SLEEP_SEC = 2.0  # 作者要求 "a couple requests per second" 以内，取更保守值
@@ -143,7 +145,7 @@ SOCIAL_HUB_REQUIRED_SKILLS = ("social-hub-cli", "social-hub-shared")
 HUB_DEFAULT_POLL_TIMEOUT_SEC = 600.0
 HUB_POLL_BACKOFF_SEC = (5.0, 10.0, 20.0, 30.0)
 HUB_INTELLIGENCE_TIMEOUT_SEC = 30.0
-COLLECTOR_VERSION = "2.12.30"
+COLLECTOR_VERSION = "2.12.31"
 ACQUISITION_POLICIES = ("hub-first", "hub-only", "self-first")
 DEFAULT_FLAIR_FILTER_PAGES = ("", "hot", "new", "top")
 
@@ -3184,6 +3186,7 @@ def arctic_get(
     user_agent: str,
     timeout: float = ARCTIC_DEFAULT_TIMEOUT_SEC,
     tracker: "RequestTracker | None" = None,
+    keep_empty_params: set[str] | None = None,
 ) -> dict[str, Any]:
     """调用 Arctic Shift API，处理 429 限流与重查询超时。
 
@@ -3191,7 +3194,12 @@ def arctic_get(
     `{"error": "Timeout. Maybe slow down a bit"}` —— 那是查询代价过高而非
     限流，同样退避重试（实测跨 15 年的 aggregate 会稳定触发）。
     """
-    clean = {k: v for k, v in params.items() if v is not None and v != ""}
+    keep_empty_params = keep_empty_params or set()
+    clean = {
+        k: v
+        for k, v in params.items()
+        if v is not None and (v != "" or k in keep_empty_params)
+    }
     url = f"{ARCTIC_BASE_URL}{path}?{urllib.parse.urlencode(clean)}"
     last_err = ""
     # 预算按**逻辑请求**计一次，不按重试次数计：重试是同一次取数的补偿，
@@ -3277,6 +3285,306 @@ def arctic_search_posts(
     return [arctic_post_item(r) for r in rows if isinstance(r, dict)]
 
 
+_ARCTIC_BASE36_ID_RE = re.compile(r"^[0-9a-z]+$", re.I)
+
+
+def normalize_reddit_post_id(target: str) -> str:
+    """Extract a bare base36 post ID from a Reddit URL, ``t3_`` ID, or bare ID."""
+    raw = str(target or "").strip()
+    if not raw:
+        raise ValueError("post URL or post ID is required (unless --ids is used)")
+
+    # Full Reddit permalinks and redd.it short links. Reject lookalike hosts rather
+    # than accepting any URL that happens to contain `/comments/<id>`.
+    if "://" in raw:
+        parsed = urllib.parse.urlparse(raw)
+        host = (parsed.hostname or "").lower().rstrip(".")
+        if host == "redd.it" or host.endswith(".redd.it"):
+            candidate = parsed.path.strip("/").split("/", 1)[0]
+        elif host == "reddit.com" or host.endswith(".reddit.com"):
+            match = re.search(r"/comments/([0-9a-z]+)(?:/|$)", parsed.path, re.I)
+            candidate = match.group(1) if match else ""
+        else:
+            raise ValueError(f"unsupported post URL host: {host or '<missing>'}")
+    elif "/comments/" in raw:
+        match = re.search(r"/comments/([0-9a-z]+)(?:/|$)", raw, re.I)
+        candidate = match.group(1) if match else ""
+    else:
+        candidate = raw[3:] if raw.lower().startswith("t3_") else raw
+        if raw.lower().startswith("t1_"):
+            raise ValueError("expected a post ID (t3_), received a comment ID (t1_)")
+
+    candidate = candidate.strip().lower()
+    if not candidate or not _ARCTIC_BASE36_ID_RE.fullmatch(candidate):
+        raise ValueError(f"malformed Reddit post ID: {raw}")
+    return candidate
+
+
+def normalize_reddit_comment_id(raw_id: str) -> str:
+    """Normalize one comment ID to its bare base36 representation."""
+    raw = str(raw_id or "").strip()
+    if raw.lower().startswith("t3_"):
+        raise ValueError(f"expected a comment ID (t1_), received a post ID: {raw}")
+    candidate = raw[3:] if raw.lower().startswith("t1_") else raw
+    candidate = candidate.strip().lower()
+    if not candidate or not _ARCTIC_BASE36_ID_RE.fullmatch(candidate):
+        raise ValueError(f"malformed Reddit comment ID: {raw or '<empty>'}")
+    return candidate
+
+
+def parse_reddit_comment_ids(values: list[str] | None) -> list[str]:
+    """Parse comma- or whitespace-separated comment IDs, preserving first-seen order."""
+    ids: list[str] = []
+    seen: set[str] = set()
+    for value in values or []:
+        for token in str(value).split(","):
+            if not token.strip():
+                raise ValueError("malformed Reddit comment ID: empty value")
+            comment_id = normalize_reddit_comment_id(token)
+            if comment_id not in seen:
+                ids.append(comment_id)
+                seen.add(comment_id)
+    if len(ids) > ARCTIC_IDS_MAX:
+        raise ValueError(f"too many comment IDs: {len(ids)} (maximum {ARCTIC_IDS_MAX})")
+    return ids
+
+
+def normalize_comment_parent_id(parent_id: str | None, *, allow_top_level: bool = False) -> str | None:
+    """Normalize a parent comment ID; search uses an empty value for top-level comments."""
+    if parent_id is None:
+        return None
+    raw = str(parent_id).strip()
+    if raw.lower() in ("top", "root"):
+        if allow_top_level:
+            return ""
+        raise ValueError("--parent-id top/root is only valid with --source search")
+    return f"t1_{normalize_reddit_comment_id(raw)}"
+
+
+def arctic_comment_item(
+    row: dict[str, Any],
+    *,
+    depth: int | None = None,
+    tree_order: int | None = None,
+    sibling_index: int | None = None,
+    tree_path: list[int] | None = None,
+    tree_parent_id: str | None = None,
+) -> dict[str, Any]:
+    """Map an Arctic comment row without truncating its archived body."""
+    body = row.get("body")
+    body_text = body if isinstance(body, str) else ("" if body is None else str(body))
+    body_status = classify_body(body_text)
+    measurable = body_status not in ("Removed", "Deleted")
+    comment_id = str(row.get("id") or "").removeprefix("t1_").lower()
+    permalink = str(row.get("permalink") or "")
+    if permalink.startswith("/"):
+        permalink = f"https://www.reddit.com{permalink}"
+    item = {
+        "item_type": "comment",
+        "id": comment_id,
+        "name": str(row.get("name") or (f"t1_{comment_id}" if comment_id else "")),
+        "link_id": row.get("link_id"),
+        # Preserve Arctic's original edge exactly. `tree_parent_id` separately records
+        # the edge observed while traversing the nested tree, useful for consistency checks.
+        "parent_id": row.get("parent_id"),
+        "tree_parent_id": tree_parent_id,
+        "author": row.get("author"),
+        "created_utc": row.get("created_utc"),
+        "score": row.get("score"),
+        "score_status": "ArchivedSnapshot",
+        "score_realtime": False,
+        "subreddit": row.get("subreddit"),
+        "body": body_text,
+        "body_status": body_status,
+        "body_chars": len(body_text) if measurable else 0,
+        "body_words": len(re.findall(r"\S+", body_text)) if measurable else 0,
+        "body_truncated": False if measurable else None,
+        "permalink": permalink or None,
+        "retrieved_on": row.get("retrieved_on"),
+        "distinguished": row.get("distinguished"),
+        "is_submitter": row.get("is_submitter"),
+        "edited": row.get("edited"),
+        "depth": depth,
+        "tree_order": tree_order,
+        "sibling_index": sibling_index,
+        "tree_path": tree_path,
+        "source_fetch": "arctic_shift",
+    }
+    return item
+
+
+def _arctic_tree_children(replies: Any) -> list[dict[str, Any]]:
+    if replies in (None, ""):
+        return []
+    if not isinstance(replies, dict):
+        raise ArcticError("arctic_comments_tree_malformed_payload: replies must be a listing")
+    data = replies.get("data")
+    if not isinstance(data, dict):
+        raise ArcticError("arctic_comments_tree_malformed_payload: replies.data must be an object")
+    children = data.get("children")
+    if not isinstance(children, list) or any(not isinstance(child, dict) for child in children):
+        raise ArcticError("arctic_comments_tree_malformed_payload: replies.data.children must be object[]")
+    return children
+
+
+def flatten_arctic_comment_tree(payload: Any) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Flatten Arctic's Reddit-shaped comment tree while retaining exact tree coordinates."""
+    if not isinstance(payload, dict) or not isinstance(payload.get("data"), list):
+        raise ArcticError("arctic_comments_tree_malformed_payload: expected data[]")
+    roots = payload.get("data")
+    if any(not isinstance(node, dict) for node in roots):
+        raise ArcticError("arctic_comments_tree_malformed_payload: data must contain object nodes")
+    nodes = roots
+    items: list[dict[str, Any]] = []
+    collapsed: list[dict[str, Any]] = []
+    order = 0
+
+    def walk(children: list[dict[str, Any]], *, depth: int, path: list[int], parent_id: str | None) -> None:
+        nonlocal order
+        for sibling_index, node in enumerate(children):
+            kind = str(node.get("kind") or "")
+            data = node.get("data")
+            if not isinstance(data, dict):
+                raise ArcticError("arctic_comments_tree_malformed_payload: node.data must be an object")
+            node_path = [*path, sibling_index]
+            node_order = order
+            order += 1
+            if kind == "more":
+                child_ids = [
+                    normalize_reddit_comment_id(str(value))
+                    for value in (data.get("children") or [])
+                    if str(value or "").strip()
+                ]
+                collapsed.append(
+                    {
+                        "kind": "more",
+                        "id": data.get("id"),
+                        "parent_id": data.get("parent_id") or parent_id,
+                        "count": data.get("count"),
+                        "children": child_ids,
+                        "depth": depth,
+                        "tree_order": node_order,
+                        "sibling_index": sibling_index,
+                        "tree_path": node_path,
+                    }
+                )
+                continue
+            if kind != "t1":
+                raise ArcticError(f"arctic_comments_tree_malformed_payload: unexpected kind={kind or '<empty>'}")
+
+            replies = _arctic_tree_children(data.get("replies"))
+            item = arctic_comment_item(
+                data,
+                depth=depth,
+                tree_order=node_order,
+                sibling_index=sibling_index,
+                tree_path=node_path,
+                tree_parent_id=parent_id,
+            )
+            item["child_ids"] = [
+                str(child.get("data", {}).get("id") or "").removeprefix("t1_").lower()
+                for child in replies
+                if child.get("kind") == "t1" and isinstance(child.get("data"), dict)
+            ]
+            items.append(item)
+            current_parent = str(data.get("name") or (f"t1_{item['id']}" if item.get("id") else "")) or None
+            walk(replies, depth=depth + 1, path=node_path, parent_id=current_parent)
+
+    walk(nodes, depth=0, path=[], parent_id=None)
+    return items, collapsed
+
+
+def arctic_comments_tree(
+    post_id: str,
+    *,
+    parent_id: str | None = None,
+    limit: int = ARCTIC_COMMENT_TREE_MAX,
+    start_breadth: int | None = None,
+    start_depth: int | None = None,
+    user_agent: str,
+    tracker: "RequestTracker | None" = None,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    payload = arctic_get(
+        "/api/comments/tree",
+        {
+            "link_id": f"t3_{post_id}",
+            "parent_id": parent_id,
+            "limit": limit,
+            "start_breadth": start_breadth,
+            "start_depth": start_depth,
+        },
+        user_agent=user_agent,
+        tracker=tracker,
+    )
+    return flatten_arctic_comment_tree(payload)
+
+
+def arctic_search_comments(
+    post_id: str,
+    *,
+    body: str | None = None,
+    author: str | None = None,
+    after: str | None = None,
+    before: str | None = None,
+    parent_id: str | None = None,
+    limit: int = ARCTIC_COMMENT_SEARCH_MAX,
+    sort: str = "asc",
+    user_agent: str,
+    tracker: "RequestTracker | None" = None,
+) -> list[dict[str, Any]]:
+    payload = arctic_get(
+        "/api/comments/search",
+        {
+            "link_id": post_id,
+            "body": body,
+            "author": author,
+            "after": after,
+            "before": before,
+            "parent_id": parent_id,
+            "limit": limit,
+            "sort": sort,
+        },
+        user_agent=user_agent,
+        tracker=tracker,
+        keep_empty_params={"parent_id"} if parent_id == "" else None,
+    )
+    rows = payload.get("data")
+    if not isinstance(rows, list):
+        return []
+    return [
+        arctic_comment_item(row, tree_order=index)
+        for index, row in enumerate(rows)
+        if isinstance(row, dict)
+    ]
+
+
+def arctic_comments_by_ids(
+    comment_ids: list[str],
+    *,
+    user_agent: str,
+    tracker: "RequestTracker | None" = None,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    payload = arctic_get(
+        "/api/comments/ids",
+        {"ids": ",".join(comment_ids)},
+        user_agent=user_agent,
+        tracker=tracker,
+    )
+    rows = payload.get("data")
+    by_id = {
+        str(row.get("id") or "").removeprefix("t1_").lower(): row
+        for row in (rows if isinstance(rows, list) else [])
+        if isinstance(row, dict)
+    }
+    items = [
+        arctic_comment_item(by_id[comment_id], tree_order=index)
+        for index, comment_id in enumerate(comment_ids)
+        if comment_id in by_id
+    ]
+    missing = [comment_id for comment_id in comment_ids if comment_id not in by_id]
+    return items, missing
+
+
 def arctic_subreddit_rules(subreddits: list[str], *, user_agent: str) -> dict[str, list[dict[str, Any]]]:
     """替代 /about/rules.json（本机对 reddit.com 直连被拦时唯一可用途径）。"""
     names = [_clean_subreddit_name(s) for s in subreddits if s]
@@ -4571,6 +4879,43 @@ def main() -> int:
     )
     pl.add_argument("--pretty", action="store_true")
 
+    pc = sub.add_parser(
+        "comments",
+        help="读取帖子历史评论正文：默认 Arctic 评论树，也支持筛选搜索与评论 ID 批查",
+    )
+    pc.add_argument("target", nargs="?", help="Reddit post URL、t3_<post_id> 或裸 post ID；--ids 模式省略")
+    pc.add_argument(
+        "--source",
+        choices=["tree", "search"],
+        default="tree",
+        help="tree=评论树（默认，最多 25,000）；search=平面筛选（最多 100）",
+    )
+    pc.add_argument(
+        "--ids",
+        nargs="+",
+        metavar="COMMENT_ID",
+        help=f"按 t1_/裸评论 ID 批查，可用空格或逗号分隔，最多 {ARCTIC_IDS_MAX}",
+    )
+    pc.add_argument("--body", help="search only：评论正文关键词/FTS 查询")
+    pc.add_argument("--author", help="search only：作者")
+    pc.add_argument("--after", help="search only：起始时间（ISO 日期、epoch 或 Arctic offset）")
+    pc.add_argument("--before", help="search only：结束时间（ISO 日期、epoch 或 Arctic offset）")
+    pc.add_argument(
+        "--parent-id",
+        help="tree/search：父评论 ID；search 中 top/root 表示顶层评论",
+    )
+    pc.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="tree 默认/上限 25000；search 默认/上限 100；越界直接报错",
+    )
+    pc.add_argument("--sort", choices=["asc", "desc"], default=None, help="search only：按 created_utc 排序")
+    pc.add_argument("--start-breadth", type=int, default=None, help="tree only：Arctic 折叠宽度，必须 >=0")
+    pc.add_argument("--start-depth", type=int, default=None, help="tree only：Arctic 折叠深度，必须 >=0")
+    pc.add_argument("--user-agent", default=DEFAULT_UA)
+    pc.add_argument("--pretty", action="store_true")
+
     ph = sub.add_parser(
         "history",
         help="历史检索：按时间窗从 Arctic Shift 归档取帖（覆盖 2005-06 起至近实时）",
@@ -4601,6 +4946,174 @@ def main() -> int:
     psh.add_argument("--pretty", action="store_true")
 
     args = p.parse_args()
+    if args.mode == "comments":
+        try:
+            comment_ids = parse_reddit_comment_ids(args.ids) if args.ids else []
+            if comment_ids and args.target:
+                raise ValueError("provide either a post target or --ids, not both")
+            if comment_ids and args.source != "tree":
+                raise ValueError("--ids cannot be combined with --source search")
+            if not comment_ids and not args.target:
+                raise ValueError("post URL or post ID is required (unless --ids is used)")
+
+            filter_values = (args.body, args.author, args.after, args.before, args.sort)
+            if comment_ids and (any(value is not None for value in filter_values) or args.parent_id is not None):
+                raise ValueError("--ids cannot be combined with post/search/tree filters")
+            if comment_ids and (args.limit is not None or args.start_breadth is not None or args.start_depth is not None):
+                raise ValueError("--ids cannot be combined with --limit/--start-breadth/--start-depth")
+            if args.source == "tree" and any(value is not None for value in filter_values):
+                raise ValueError("--body/--author/--after/--before/--sort require --source search")
+            if args.source == "search" and (args.start_breadth is not None or args.start_depth is not None):
+                raise ValueError("--start-breadth/--start-depth are only valid with --source tree")
+            if args.start_breadth is not None and args.start_breadth < 0:
+                raise ValueError("--start-breadth must be >= 0")
+            if args.start_depth is not None and args.start_depth < 0:
+                raise ValueError("--start-depth must be >= 0")
+
+            post_id = normalize_reddit_post_id(args.target) if args.target else None
+            parent_id = (
+                normalize_comment_parent_id(args.parent_id, allow_top_level=args.source == "search")
+                if args.parent_id is not None and post_id is not None
+                else None
+            )
+            retrieval_mode = "ids" if comment_ids else args.source
+            maximum = ARCTIC_COMMENT_TREE_MAX if retrieval_mode == "tree" else ARCTIC_COMMENT_SEARCH_MAX
+            default_limit = ARCTIC_COMMENT_TREE_MAX if retrieval_mode == "tree" else ARCTIC_COMMENT_SEARCH_MAX
+            limit = default_limit if args.limit is None else args.limit
+            if retrieval_mode != "ids" and not 1 <= limit <= maximum:
+                raise ValueError(f"--limit must be between 1 and {maximum} for {retrieval_mode} mode")
+        except ValueError as exc:
+            pc.error(str(exc))
+
+        tracker = RequestTracker()
+        errors: list[str] = []
+        collapsed: list[dict[str, Any]] = []
+        missing_ids: list[str] = []
+        items: list[dict[str, Any]] = []
+        tree_fetch_succeeded = False
+        try:
+            if retrieval_mode == "ids":
+                items, missing_ids = arctic_comments_by_ids(
+                    comment_ids,
+                    user_agent=args.user_agent,
+                    tracker=tracker,
+                )
+            elif retrieval_mode == "search":
+                items = arctic_search_comments(
+                    post_id,
+                    body=args.body,
+                    author=args.author,
+                    after=args.after,
+                    before=args.before,
+                    parent_id=parent_id,
+                    limit=limit,
+                    sort=args.sort or "asc",
+                    user_agent=args.user_agent,
+                    tracker=tracker,
+                )
+            else:
+                items, collapsed = arctic_comments_tree(
+                    post_id,
+                    parent_id=parent_id,
+                    limit=limit,
+                    start_breadth=args.start_breadth,
+                    start_depth=args.start_depth,
+                    user_agent=args.user_agent,
+                    tracker=tracker,
+                )
+                tree_fetch_succeeded = True
+        except ArcticError as exc:
+            errors.append(f"arctic_comments_failed:{exc}"[:300])
+        if missing_ids:
+            errors.append(f"comment_ids_not_found:{','.join(missing_ids)}"[:300])
+
+        bodies = [item for item in items if item.get("body_status") == "Present"]
+        removed = [item for item in items if item.get("body_status") in ("Removed", "Deleted")]
+        notes = [
+            "Arctic Shift 是第三方历史归档源，通常滞后约 2 小时，且不保证可用性。",
+            "评论 body 适合历史 VOC；score 是归档快照而非实时值，不得用于当前热度判断。",
+        ]
+        if collapsed:
+            notes.append(
+                f"评论树含 {len(collapsed)} 个 kind=more 折叠节点；"
+                "tree_complete=false，collapsed[].children 保留尚未展开的评论 ID。"
+            )
+        fetched_at = utc_now_iso()
+        canonical_source = f"https://www.reddit.com/comments/{post_id}/" if post_id else None
+        fingerprint = hashlib.sha256(
+            json.dumps(
+                {
+                    "mode": "comments",
+                    "retrieval_mode": retrieval_mode,
+                    "post_id": post_id,
+                    "comment_ids": comment_ids,
+                    "body": args.body,
+                    "author": args.author,
+                    "after": args.after,
+                    "before": args.before,
+                    "parent_id": parent_id,
+                    "limit": None if retrieval_mode == "ids" else limit,
+                    "sort": args.sort or ("asc" if retrieval_mode == "search" else None),
+                    "start_breadth": args.start_breadth,
+                    "start_depth": args.start_depth,
+                },
+                ensure_ascii=False,
+                sort_keys=True,
+            ).encode("utf-8")
+        ).hexdigest()
+        out = {
+            "ok": not errors,
+            "mode": "comments",
+            "retrieval_mode": retrieval_mode,
+            "provenance": "arctic_shift",
+            "source_endpoint": f"/api/comments/{'ids' if retrieval_mode == 'ids' else retrieval_mode}",
+            "source_urls": [canonical_source] if canonical_source else [],
+            "post_id": post_id,
+            "link_id": f"t3_{post_id}" if post_id else None,
+            "requested_comment_ids": comment_ids,
+            "missing_comment_ids": missing_ids,
+            "filters": {
+                "body": args.body,
+                "author": args.author,
+                "after": args.after,
+                "before": args.before,
+                "parent_id": parent_id,
+                "sort": args.sort or ("asc" if retrieval_mode == "search" else None),
+            },
+            "count": len(items),
+            "tree_complete": tree_fetch_succeeded and not collapsed if retrieval_mode == "tree" else None,
+            "collapsed_count": len(collapsed),
+            "collapsed": collapsed,
+            "body_stats": {
+                "with_text": len(bodies),
+                "removed_or_deleted": len(removed),
+                "max_chars": max((int(item.get("body_chars") or 0) for item in bodies), default=0),
+            },
+            "items": items,
+            "archive_caveats": {
+                "estimated_lag": "about_2_hours",
+                "uptime_guaranteed": False,
+                "score_realtime": False,
+            },
+            "rate_limit": {
+                "requested_limit": len(comment_ids) if retrieval_mode == "ids" else limit,
+                "effective_limit": len(comment_ids) if retrieval_mode == "ids" else limit,
+                "http_requests": tracker.count,
+                "rate_limited": tracker.rate_limited,
+            },
+            "fetched_at": fetched_at,
+            "fetchedAt": fetched_at,
+            "fingerprint": fingerprint,
+            "runId": None,
+            "hubRunId": None,
+            "fallbackReason": None,
+            "writebackStatus": "not_applicable",
+            "notes": notes,
+            "errors": errors,
+        }
+        print(json.dumps(out, ensure_ascii=False, indent=2 if args.pretty else None))
+        return 0 if out["ok"] else 1
+
     if args.mode == "history":
         subs = [_clean_subreddit_name(s) for s in (args.subreddit or [])] or [None]
         items: list[dict[str, Any]] = []

package/skills/reddit-voc-volume/tests/test_archived_comments.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import json
+from pathlib import Path
+import sys
+import unittest
+from unittest import mock
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "reddit_voc_volume.py"
+SPEC = importlib.util.spec_from_file_location("reddit_voc_volume_under_test", SCRIPT)
+assert SPEC is not None and SPEC.loader is not None
+voc = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(voc)
+
+
+class ArchivedCommentTests(unittest.TestCase):
+    def run_main(self, *args: str) -> tuple[int, dict]:
+        stdout = io.StringIO()
+        with mock.patch.object(sys, "argv", [str(SCRIPT), *args]), contextlib.redirect_stdout(stdout):
+            code = voc.main()
+        return code, json.loads(stdout.getvalue())
+
+    def test_post_and_comment_id_normalization(self) -> None:
+        self.assertEqual(
+            voc.normalize_reddit_post_id("https://www.reddit.com/r/example/comments/AbC123/a_slug/"),
+            "abc123",
+        )
+        self.assertEqual(voc.normalize_reddit_post_id("t3_ABC123"), "abc123")
+        self.assertEqual(voc.normalize_reddit_post_id("https://redd.it/AbC123"), "abc123")
+        self.assertEqual(voc.normalize_reddit_comment_id("t1_DeF456"), "def456")
+        with self.assertRaisesRegex(ValueError, "comment ID"):
+            voc.normalize_reddit_post_id("t1_def456")
+        with self.assertRaisesRegex(ValueError, "unsupported post URL host"):
+            voc.normalize_reddit_post_id("https://example.com/comments/abc123")
+        with self.assertRaisesRegex(ValueError, "maximum 500"):
+            voc.parse_reddit_comment_ids([f"c{index:x}" for index in range(501)])
+
+    def test_tree_mode_flattens_body_and_preserves_hierarchy(self) -> None:
+        payload = {
+            "data": [
+                {
+                    "kind": "t1",
+                    "data": {
+                        "id": "root1",
+                        "name": "t1_root1",
+                        "link_id": "t3_post1",
+                        "parent_id": "t3_post1",
+                        "author": "alice",
+                        "body": "Root comment",
+                        "created_utc": 100,
+                        "score": 9,
+                        "subreddit": "example",
+                        "replies": {
+                            "data": {
+                                "children": [
+                                    {
+                                        "kind": "t1",
+                                        "data": {
+                                            "id": "child1",
+                                            "name": "t1_child1",
+                                            "link_id": "t3_post1",
+                                            "parent_id": "t1_root1",
+                                            "author": "bob",
+                                            "body": "Child comment",
+                                            "created_utc": 101,
+                                            "score": 3,
+                                            "subreddit": "example",
+                                        },
+                                    },
+                                    {
+                                        "kind": "more",
+                                        "data": {
+                                            "id": "more1",
+                                            "parent_id": "t1_root1",
+                                            "count": 2,
+                                            "children": ["hidden1", "hidden2"],
+                                        },
+                                    },
+                                ]
+                            }
+                        },
+                    },
+                }
+            ]
+        }
+        with mock.patch.object(voc, "arctic_get", return_value=payload) as get:
+            code, out = self.run_main("comments", "https://reddit.com/r/example/comments/post1/slug")
+
+        self.assertEqual(code, 0)
+        self.assertEqual(get.call_args.args[0], "/api/comments/tree")
+        self.assertEqual(get.call_args.args[1]["link_id"], "t3_post1")
+        self.assertEqual(get.call_args.args[1]["limit"], 25_000)
+        self.assertEqual([item["id"] for item in out["items"]], ["root1", "child1"])
+        self.assertEqual(out["items"][0]["child_ids"], ["child1"])
+        self.assertEqual(out["items"][1]["parent_id"], "t1_root1")
+        self.assertEqual(out["items"][1]["depth"], 1)
+        self.assertEqual(out["items"][1]["tree_path"], [0, 0])
+        self.assertEqual(out["items"][1]["body"], "Child comment")
+        self.assertFalse(out["items"][1]["body_truncated"])
+        self.assertFalse(out["tree_complete"])
+        self.assertEqual(out["collapsed"][0]["children"], ["hidden1", "hidden2"])
+        self.assertFalse(out["archive_caveats"]["score_realtime"])
+
+    def test_search_mode_forwards_supported_filters(self) -> None:
+        with mock.patch.object(voc, "arctic_get", return_value={"data": []}) as get:
+            code, out = self.run_main(
+                "comments",
+                "t3_post1",
+                "--source",
+                "search",
+                "--body",
+                "battery life",
+                "--author",
+                "alice",
+                "--after",
+                "2024-01-01",
+                "--before",
+                "2024-02-01",
+                "--parent-id",
+                "top",
+                "--limit",
+                "10",
+                "--sort",
+                "desc",
+            )
+
+        self.assertEqual(code, 0)
+        self.assertEqual(out["retrieval_mode"], "search")
+        self.assertEqual(get.call_args.args[0], "/api/comments/search")
+        params = get.call_args.args[1]
+        self.assertEqual(params["link_id"], "post1")
+        self.assertEqual(params["body"], "battery life")
+        self.assertEqual(params["author"], "alice")
+        self.assertEqual(params["parent_id"], "")
+        self.assertEqual(get.call_args.kwargs["keep_empty_params"], {"parent_id"})
+        self.assertEqual(params["limit"], 10)
+        self.assertEqual(params["sort"], "desc")
+
+    def test_ids_mode_restores_requested_order(self) -> None:
+        payload = {
+            "data": [
+                {"id": "second2", "body": "second", "link_id": "t3_post1", "parent_id": "t3_post1"},
+                {"id": "first1", "body": "first", "link_id": "t3_post1", "parent_id": "t3_post1"},
+            ]
+        }
+        with mock.patch.object(voc, "arctic_get", return_value=payload) as get:
+            code, out = self.run_main("comments", "--ids", "t1_first1,second2")
+
+        self.assertEqual(code, 0)
+        self.assertEqual(get.call_args.args[0], "/api/comments/ids")
+        self.assertEqual(get.call_args.args[1]["ids"], "first1,second2")
+        self.assertEqual([item["id"] for item in out["items"]], ["first1", "second2"])
+
+    def test_tree_failure_and_malformed_payload_are_never_reported_complete(self) -> None:
+        with mock.patch.object(voc, "arctic_get", side_effect=voc.ArcticError("upstream unavailable")):
+            code, out = self.run_main("comments", "post1")
+        self.assertEqual(code, 1)
+        self.assertFalse(out["tree_complete"])
+        self.assertIn("upstream unavailable", out["errors"][0])
+
+        with mock.patch.object(voc, "arctic_get", return_value={"data": {}}):
+            code, out = self.run_main("comments", "post1")
+        self.assertEqual(code, 1)
+        self.assertFalse(out["tree_complete"])
+        self.assertIn("arctic_comments_tree_malformed_payload", out["errors"][0])
+
+    def test_malformed_id_and_out_of_range_limits_fail_before_network(self) -> None:
+        with mock.patch.object(voc, "arctic_get") as get, contextlib.redirect_stderr(io.StringIO()):
+            with mock.patch.object(sys, "argv", [str(SCRIPT), "comments", "--ids", "t3_wrongkind"]):
+                with self.assertRaisesRegex(SystemExit, "2"):
+                    voc.main()
+            with mock.patch.object(sys, "argv", [str(SCRIPT), "comments", "post1", "--limit", "25001"]):
+                with self.assertRaisesRegex(SystemExit, "2"):
+                    voc.main()
+            with mock.patch.object(sys, "argv", [str(SCRIPT), "comments", "post1", "--parent-id", "top"]):
+                with self.assertRaisesRegex(SystemExit, "2"):
+                    voc.main()
+            with mock.patch.object(sys, "argv", [str(SCRIPT), "comments", "--ids", "comment1", "--source", "search"]):
+                with self.assertRaisesRegex(SystemExit, "2"):
+                    voc.main()
+        get.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()