@geoly-ai/social-hub-cli 0.3.44 → 0.3.46

package/skills/social-hub-intelligence/SKILL.md

@@ -50,9 +50,120 @@ social-hub intelligence comments-count [--post-id t3_xxx] [--subreddit espresso]
 评论正文与评论树在库(reddit*comment_samples);intent/sentiment 由标注 cron
 批量回写(需部署 REDDIT_COMMENT_REVIEW_LLM*\* key)。VOC 帖子任务默认不采评论,
 需要时对命中帖 comments-fetch,或用 coverage 的 needComments 判断缺口后派发。
+⚠️ 本列表只含 Hub 内现有评论样本(非归档,约 5.7 万条);历史/归档评论已迁至 CyberRedd(Hub 的
+`GET /v1/system/archive-observations?source=comments` 已退役,回 410 `ARCHIVE_SOURCE_RETIRED`)。
 口径注意:comments / comments-count 数的是**库内样本行数**(sampleMode=partial_sample),
 不是 Reddit 线程真实评论总数。
 
+## 公开库检索（只读，CyberRedd）
+
+Hub 代理读取外部数据服务 CyberRedd 的公开 Reddit 库，四条命令都在 `intelligence` 组下，
+三条数据命令需要 `subredditIntelDiscovery:read` 权限；`public-status` 不走该权限，仅 unrestricted admin 可用。
+
+```bash
+# 社区目录（哪些板块在公开库可读；分页用 nextCursor 原样回传）
+social-hub intelligence public-communities [--industry-keys a,b] [--tier-keys a,b] \
+  [--pool-kinds primary,secondary,experimental,excluded] [--has-profile true|false] [-n 50] [--cursor <token>]
+# 帖子检索（必须带板块，单次 ≤20 个；板块名小写、不带 r/）
+social-hub intelligence public-posts --subreddit espresso,coffee [--query "grinder"] \
+  [--window day|week|month|last_90d|last_360d|last_full_week | --from <iso> --to <iso>] \
+  [-n 25] [--cursor <token>] [--include-body]
+# 帖子计数（昂贵读；板块 ≤50 个；--query 与窗口都必填）
+social-hub intelligence public-post-count --subreddit espresso,coffee --query "grinder" \
+  (--window month | --from <iso> --to <iso>) [--type post|comment]
+# 开关/熔断/预算状态（仅 unrestricted admin）
+social-hub intelligence public-status
+```
+
+窗口：`--window` 与 `--from/--to` 互斥，`--from` 含、`--to` 不含，ISO 8601 带时区，跨度 ≤366 天。
+
+### 什么时候用，什么时候不用
+
+- **用**：按板块 + 关键词在公开库里找帖子、估算某词在某板块窗口内的帖子量、看哪些板块在公开库可读。
+- **不适用**：
+  - 热帖排行 / 按分数排序：用 `hot-posts`。检索结果固定按创建时间倒序。
+  - 评论：Hub 内评论只有约 5.7 万条自采样本；历史/归档评论已迁至 CyberRedd，但对方的评论列表读取
+    目前**尚未开放**，所以 `public-posts` 查不到评论正文。`public-post-count --type comment` 覆盖不完整，
+    不能当评论总量。
+  - 现抓：这是读对方已有的库，不会触发抓取；要最新内容用 `fetch-by-*` / `comments-fetch`。
+  - `reddit-voc-volume` 的历史模式仍直连 Arctic Shift，本节不改变它。
+
+### 与 Hub 关键词检索的语义差异
+
+Hub 现有 `--keyword` 是库内 ILIKE 子串匹配；公开库 `--query` 是对方的**全文检索**：
+无词干、不切 CJK（这是对方服务的行为，以 CyberRedd 的说明为准）。例如 `espress` 匹配不到 `espresso`，`espresso` 也不会自动匹配 `espressos`；
+中日韩文本不会被切词，不要指望子串命中。需要多个写法就分别查，或换整词。
+
+### 🔴 query 会发往外部数据服务
+
+`--query` 的原文会离开 Hub、发给 CyberRedd。Hub 只透传调用方显式输入的 query，
+后台作业与任何自动流程都不会替你发关键词。所以：
+
+- 不要把敏感词、未公开的品牌策略词、客户机密、内部项目名放进 `--query`。
+- 别因为"想顺便查一下"就把品牌词/竞品词批量塞进去；只查任务确实需要的词。
+
+### count 是昂贵读
+
+`public-post-count` 每次都消耗对方的成本和 Hub 的上游调用预算：
+
+- 禁止轮询、禁止循环重试同一组参数。
+- 必须带 `--query` 和窗口，板块 ≤50 个；本地会先拦，不会白发请求。
+- 超时（`PUBLIC_REDDIT_COUNT_TIMEOUT`）或范围过大（`PUBLIC_REDDIT_SCOPE_TOO_LARGE`）时，
+  先减少板块或按月切分窗口再查，不要原样重试。
+- 响应里 `exact=false` 时 `total` 一定是 `null`（Hub 不用部分和冒充总数）。
+  这表示"精确总数没有取到"，不是 0；逐板块的 `communities[].count` / `status` / `windowCovered`
+  里看各自覆盖情况，不要自己求和当总数。
+
+### 🔴 错误码 ≠ 没有数据
+
+命令失败时 stderr 打印 `[PUBLIC_REDDIT_*] 原因`，接着一行"这不是「没有数据」……"，**退出码 1**，
+stdout 没有结果。**agent 不得把失败当成空结果继续推理**（例如结论"该板块没有相关帖子"）。
+结果是未知，不是零。
+
+| 错误码                                                                                         | 含义                                                                                                                                           | 该怎么办                                                   |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `PUBLIC_REDDIT_DISABLED`                                                                       | 本次请求未启用：开关为 off、未配置、能力未开、demo 会话，或 shadow 模式下当前身份无权读取（细因只有 admin 在 `error.details.reason` 里能看到） | 不是没数据；找管理员，`public-status`（admin）可看开关     |
+| `PUBLIC_REDDIT_POLICY_DENIED`                                                                  | 上游策略拒绝（通常是准入/范围问题）                                                                                                            | 不是没数据；需管理员处理，不要换参数硬试                   |
+| `PUBLIC_REDDIT_AUTH_FAILED` / `PUBLIC_REDDIT_BAD_UPSTREAM_RESPONSE`                            | 上游凭据失效 / 响应无法解析                                                                                                                    | 需管理员处理                                               |
+| `PUBLIC_REDDIT_BUDGET_EXHAUSTED` / `_RATE_LIMITED` / `_DEGRADED` / `_UNAVAILABLE`              | 预算用完、限流、降级、不可用                                                                                                                   | 稍后再试，不要轮询；有 `Retry-After` 就遵守                |
+| `PUBLIC_REDDIT_COUNT_TIMEOUT` / `_SCOPE_TOO_LARGE`                                             | 计数超时 / 板块×窗口过大                                                                                                                       | 缩小板块或按月切窗口后分别查                               |
+| `PUBLIC_REDDIT_COMMUNITY_NOT_AVAILABLE`                                                        | 指定板块不在公开库可读范围（对方未准入该板块）                                                                                                 | **不代表该板块没有帖子**；只能说"公开库当前读不到这个板块" |
+| `PUBLIC_REDDIT_INVALID_WINDOW` / `_QUERY_REQUIRED` / `_INVALID_COMMUNITY` / `_INVALID_REQUEST` | 参数问题                                                                                                                                       | 按提示改参数                                               |
+| `PUBLIC_REDDIT_CURSOR_RESET` / `_CURSOR_MISMATCH`                                              | 游标失效 / 与查询条件不符                                                                                                                      | 去掉 `--cursor` 从第一页重来；翻页必须用同一组条件         |
+
+### 成功但结果为空，也要看 source 和 warnings
+
+成功响应里的 `source.excludedCommunities[]`（`communityId` + `reason`，当前实际只出现 `not_in_upstream_catalog`，
+契约另保留 `upstream_not_public`）列出**没被查询**的板块：是没查，不是查了没有。
+0 条结果时，`public-communities` / `public-posts` 的 stderr 会提示被排除的板块数
+（`public-post-count` 没有这条提示，要自己看响应），**空结果不代表这些板块没有数据**。
+
+- `excludedCommunities` 为空**不等于**所有板块都查了：`source.warnings` 里有 `CATALOG_PRECHECK_SKIPPED`
+  表示准入预检被跳过；有 `PARTIAL_COMMUNITY_COVERAGE` 表示只有部分板块计入。排除情况必须连 `warnings` 一起读。
+- count 的 `ALL_COMMUNITIES_EXCLUDED`：所有板块都被排除，会返回 `exact=false`、`total=null`、`communities=[]`，
+  这不是"0 个板块有数据"，而是一个都没查。
+- `WINDOW_UNRESOLVED`：`resolvedWindow` 的起止可能是空串，别当精确起止。
+- 另看 `source.dataCutoff`（数据截止时间）和 `source.cached`（是否来自进程内短缓存）。
+
+受限主体（非 unrestricted）只能读自己可见的板块，两条路径表现不同，都是限制，不是没数据：
+
+- `public-posts` / `public-post-count` 请求了授权范围外的板块：直接 **403**（`Subreddit not in visible scope`），
+  不是 `PUBLIC_REDDIT_*` 错误码，stderr 没有"这不是没有数据"那一行，但同样是失败，不是空结果。
+- `public-communities` 按可见范围过滤条目，过滤情况看 `source.warnings` 里的 `SCOPE_EMPTY` /
+  `RESULTS_FILTERED_BY_SCOPE`，**不进** `excludedCommunities`。出现后者时一页可能很短甚至为空，
+  `nextCursor` 仍有值：空页不等于翻到底，只有 `nextCursor` 为 `null` 才是翻到头。
+
+其它：`--query` 最长 200 字符；`-n` 上限 100（目录缺省 50，帖子缺省 25）；`--cursor` 是 Hub 令牌，
+绑定身份和查询条件，换人或换条件会得到 `CURSOR_MISMATCH` / `CURSOR_RESET`。
+结果里的 `intent`/`sentiment` 用的是 CyberRedd 的 `cyberredd_v1` 词表，与 Hub 评论样本的标注不是同一套，不要混用。
+
+### 数据使用边界
+
+- 公开库返回的内容**不得用于模型训练**（包括微调、蒸馏、评测集构造）。
+- 不要长期保存帖子正文；默认只返回摘录，`--include-body` 仅在任务确需正文时用，用完不落盘、不写回 Hub。
+- 不要把检索结果批量导出或回灌进 Hub（`*-import`、`handoff-create` 里只写结论与引用，不贴正文）。
+- 公开库内容不接入审核门、内容分类、舆情等 LLM 流程。
+
 ## Emergency Acquisition 回灌(矩阵 skill 自爬数据写回)
 
 ```bash

package/skills/social-hub-ops-runtime/SKILL.md

@@ -70,6 +70,50 @@ social-hub ops skip -t <team-id> --job <jobId> --agent "$AGENT" --reason manual_
 
 Hub 能保证：client 不能预置/篡改服务端字段、官方 worker executor 只收到冻结内容、complete 校验 hash/generation/pair、未 claim/错 holder/旧 generation 的 complete 被拒。**Hub 挡不住**：拿到 Reddit 会话的 agent 主动忽略 `executionContent`、自行输入别的正文，或用另一 token 重读草稿。真·强制依赖 agent（OpenClaw）遵守本契约——Hub 侧是「冻结 + 校验 + 审计漂移」，不是对平台写动作的物理拦截。
 
+## 🔴 板块受限拦截（409 `JOB_BLOCKED` / `TARGET_BLOCKED`）
+
+板块被系统级限制（整板 banned / private / quarantined / unavailable）或该账号在该板块有生效
+sanction / bot_bouncer 名单时，Hub **在服务端拦住执行**，并把 job 置为终态 `blocked`
+（`lastError` 形如 `target_blocked:<source>:<id>`）。你会看到的形状（HTTP **409**，AppError 信封）：
+
+```json
+{
+  "error": {
+    "code": "CONFLICT",
+    "message": "…",
+    "details": {
+      "code": "JOB_BLOCKED",
+      "reason": "target_blocked",
+      "source": "restriction",
+      "id": "<uuid>",
+      "kind": "banned",
+      "subreddit": "adhdliving"
+    }
+  }
+}
+```
+
+**识别方式：只看 `error.details.code`（`JOB_BLOCKED` / `TARGET_BLOCKED`）或 `details.reason === "target_blocked"`，
+不要匹配 `message`**（措辞随时会改）。CLI 命中时 stderr 直接输出上面这段 JSON（含 `details`），退出码 1；
+SDK 用 `getSubredditRestrictionBlock(err)`。
+
+| 调用                                 | 受限时的行为                                                                                      |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `ops claim-next`                     | **永远不会**返回 blocked job；没有可领的就照旧 `no_claimable_job`                                 |
+| `ops heartbeat`                      | 409 `JOB_BLOCKED` —— 这一单已被拦                                                                 |
+| `ops complete`（job 在排队时就被拦） | 409 `JOB_BLOCKED`（没有合法执行，没什么可回执的）                                                 |
+| `ops complete`（领到后才被拦）       | 只留一条 blocked 回执 + permalink 存档，**不会**把 job 改成 succeeded、不会标 published、不会重发 |
+| `ops fail` / `ops skip`              | 对已 blocked 的 job 是 **200 no-op**（不改状态）                                                  |
+
+**agent 停止规则（必须遵守）：**
+
+1. 命中即**本轮跳过这个目标**：停止对该 job 的一切后续动作（不续租、不发帖、不评论）。
+2. **不重试**：重试只会拿到同一个 409。解除路径看 `details.source`:`restriction` 只有 admin `restrictions revoke`;`sanction`(团队/账号级)由有权限的人把该 sanction 改为 lifted;`blocklist` 由 admin 维护（不是 agent 的事）。
+3. **不要再 `fail` / `skip` 重报**（它们是 no-op，只会制造噪音），也不要把它当 Hub 故障告警。
+4. 已被拦的 job 是永久终态：解封后也**不会**自动恢复，需要人重新排期（新建 job）。
+5. 动手前可以先自查：`social-hub restrictions check -t <team-id> --subreddit <name> --account <accountId>`，
+   返回 `allowed:false` 就直接跳过（用法见 `social-hub-graph-compliance`）。
+
 ## `--reason` 枚举（仅允许下列值）
 
 `ip_drift`, `env_start_timeout`, `login_expired`, `wrong_account_logged_in`, `reddit_connection_failed`, `rte_failed`, `subreddit_banned`, `bot_bouncer_blocked`, `rule_blocked`, `manual_intervention_required`, `unknown`

package/skills/social-hub-posts/SKILL.md

@@ -30,11 +30,15 @@ metadata:
 >
 > **分页**：`reddit list` / `list-full` 默认单页；加 `--all` 按每页 200 条自动翻页直到 `total`；或手动 `--offset <n>`。
 >
+> **账号类型筛选**：`reddit list` / `list-full` / `stats` 支持 `--account-type internal|external`（可逗号分隔，二者并集）。库里 `accountType` 是自由文本（内部 / 内部账号 / Internal / 代发 / 代发账号 … 都会按别名表归一后命中），**只开放内部、外部两项**；选了任一项后，代理(proxy)、海外兼职、未知与空值的帖都不命中，列表与统计口径一致。
+
 > **统计区间**：`reddit stats --range` 支持 `7|30|90|365|all`（`all` = 全部历史，与列表 total 一致）。
 
 ```bash
 social-hub reddit list -t <team-id> -n 20
 social-hub reddit list -t <team-id> --ops-status normal --post-type post
+social-hub reddit list -t <team-id> --account-type internal --aggregate --all
+social-hub reddit stats -t <team-id> --account-type external --aggregate --range 30
 social-hub reddit list-full -t <team-id> --brand <brand-uuid> -n 50
 social-hub reddit list -t <team-id> --aggregate --all
 social-hub reddit stats -t <team-id> --aggregate --range 30

package/skills/social-hub-publishing/SKILL.md

@@ -86,6 +86,18 @@ social-hub plans create -t <team-id> -j '{"brandId":"<uuid>","name":"Week 1","en
 social-hub plans cancel -t <team-id> --plan <uuid>       # 破坏性：先 list 确认 plan id
 ```
 
+## 🔴 板块受限（409 `TARGET_BLOCKED`）
+
+目标板块受系统级限制（整板 banned / private / quarantined / unavailable，待复核与逾期未复核的同样拦），
+或该账号在该板块有生效 sanction / bot_bouncer 名单时：
+
+- `drafts create` / `drafts update` **显式**把 subreddit 设为受限板块 → 409；改投别的板块、清空、读取都放行。
+- `plans create`、建排期 / 改期 / job 创建 → 409。
+- 形状：`error.code = "CONFLICT"`，`error.details = { code: "TARGET_BLOCKED", reason: "target_blocked", source, id, kind?, subreddit }`。
+  **按 `error.details.code` 识别，不要匹配 message；不要重试**——换板块或跳过。解除路径看 `details.source`:`restriction` 只有 admin `restrictions revoke`;`sanction`(团队/账号级)由有权限的人把该 sanction 改为 lifted;`blocklist` 由 admin 维护。
+- 事前自查：`social-hub restrictions check -t <team-id> --subreddit <name> [--account <accountId>]`（见 `social-hub-graph-compliance`）。
+- 执行侧（ops heartbeat / complete）的受限语义与停止规则见 `social-hub-ops-runtime`。
+
 ## 日历与任务
 
 调度列表与 patch 见 **`social-hub-calendar-jobs`**（本 skill 不重复展开 jobs 全量命令）。