@geoly-ai/social-hub-cli 0.3.43 → 0.3.45

package/skills/reddit-voc-volume/services/firecrawl/examples/o1_web_crawler/o1_web_crawler.py

@@ -1,152 +1,152 @@
-import os
-from firecrawl import FirecrawlApp
-import json
-from dotenv import load_dotenv
-from openai import OpenAI
-
-# ANSI color codes
-class Colors:
-    CYAN = '\033[96m'
-    YELLOW = '\033[93m'
-    GREEN = '\033[92m'
-    RED = '\033[91m'
-    MAGENTA = '\033[95m'
-    BLUE = '\033[94m'
-    RESET = '\033[0m'
-
-# Load environment variables
-load_dotenv()
-
-# Retrieve API keys from environment variables
-firecrawl_api_key = os.getenv("FIRECRAWL_API_KEY")
-openai_api_key = os.getenv("OPENAI_API_KEY")
-
-# Initialize the FirecrawlApp and OpenAI client
-app = FirecrawlApp(api_key=firecrawl_api_key)
-client = OpenAI(api_key=openai_api_key)
-
-# Find the page that most likely contains the objective
-def find_relevant_page_via_map(objective, url, app, client):
-    try:
-        print(f"{Colors.CYAN}Understood. The objective is: {objective}{Colors.RESET}")
-        print(f"{Colors.CYAN}Initiating search on the website: {url}{Colors.RESET}")
-        
-        map_prompt = f"""
-        The map function generates a list of URLs from a website and it accepts a search parameter. Based on the objective of: {objective}, come up with a 1-2 word search parameter that will help us find the information we need. Only respond with 1-2 words nothing else.
-        """
-
-        print(f"{Colors.YELLOW}Analyzing objective to determine optimal search parameter...{Colors.RESET}")
-        completion = client.chat.completions.create(
-            model="o1-preview",
-            messages=[
-                {
-                    "role": "user",
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": map_prompt
-                        }
-                    ]
-                }
-            ]
-        )
-
-        map_search_parameter = completion.choices[0].message.content
-        print(f"{Colors.GREEN}Optimal search parameter identified: {map_search_parameter}{Colors.RESET}")
-
-        print(f"{Colors.YELLOW}Mapping website using the identified search parameter...{Colors.RESET}")
-        map_website = app.map_url(url, params={"search": map_search_parameter})
-        print(f"{Colors.GREEN}Website mapping completed successfully.{Colors.RESET}")
-        print(f"{Colors.GREEN}Located {len(map_website)} relevant links.{Colors.RESET}")
-        return map_website
-    except Exception as e:
-        print(f"{Colors.RED}Error encountered during relevant page identification: {str(e)}{Colors.RESET}")
-        return None
-    
-# Scrape the top 3 pages and see if the objective is met, if so return in json format else return None
-def find_objective_in_top_pages(map_website, objective, app, client):
-    try:
-        # Get top 3 links from the map result
-        top_links = map_website[:3] if isinstance(map_website, list) else []
-        print(f"{Colors.CYAN}Proceeding to analyze top {len(top_links)} links: {top_links}{Colors.RESET}")
-        
-        for link in top_links:
-            print(f"{Colors.YELLOW}Initiating scrape of page: {link}{Colors.RESET}")
-            # Scrape the page
-            scrape_result = app.scrape_url(link, params={'formats': ['markdown']})
-            print(f"{Colors.GREEN}Page scraping completed successfully.{Colors.RESET}")
-     
-            
-            # Check if objective is met
-            check_prompt = f"""
-            Given the following scraped content and objective, determine if the objective is met.
-            If it is, extract the relevant information in a simple and concise JSON format. Use only the necessary fields and avoid nested structures if possible.
-            If the objective is not met with confidence, respond with 'Objective not met'.
-
-            Objective: {objective}
-            Scraped content: {scrape_result['markdown']}
-
-            Remember:
-            1. Only return JSON if you are confident the objective is fully met.
-            2. Keep the JSON structure as simple and flat as possible.
-            3. Do not include any explanations or markdown formatting in your response.
-            """
-        
-            completion = client.chat.completions.create(
-            model="o1-preview",
-            messages=[
-                {
-                    "role": "user",
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": check_prompt
-                        }
-                    ]
-                }
-                ]
-            )
-            
-            result = completion.choices[0].message.content
-            
-            if result != "Objective not met":
-                print(f"{Colors.GREEN}Objective potentially fulfilled. Relevant information identified.{Colors.RESET}")
-                try:
-                    return json.loads(result)
-                except json.JSONDecodeError:
-                    print(f"{Colors.RED}Error in parsing response. Proceeding to next page...{Colors.RESET}")
-            else:
-                print(f"{Colors.YELLOW}Objective not met on this page. Proceeding to next link...{Colors.RESET}")
-        
-        print(f"{Colors.RED}All available pages analyzed. Objective not fulfilled in examined content.{Colors.RESET}")
-        return None
-    
-    except Exception as e:
-        print(f"{Colors.RED}Error encountered during page analysis: {str(e)}{Colors.RESET}")
-        return None
-
-# Main function to execute the process
-def main():
-    # Get user input
-    url = input(f"{Colors.BLUE}Enter the website to crawl: {Colors.RESET}")
-    objective = input(f"{Colors.BLUE}Enter your objective: {Colors.RESET}")
-    
-    print(f"{Colors.YELLOW}Initiating web crawling process...{Colors.RESET}")
-    # Find the relevant page
-    map_website = find_relevant_page_via_map(objective, url, app, client)
-    
-    if map_website:
-        print(f"{Colors.GREEN}Relevant pages identified. Proceeding with detailed analysis...{Colors.RESET}")
-        # Find objective in top pages
-        result = find_objective_in_top_pages(map_website, objective, app, client)
-        
-        if result:
-            print(f"{Colors.GREEN}Objective successfully fulfilled. Extracted information:{Colors.RESET}")
-            print(f"{Colors.MAGENTA}{json.dumps(result, indent=2)}{Colors.RESET}")
-        else:
-            print(f"{Colors.RED}Unable to fulfill the objective with the available content.{Colors.RESET}")
-    else:
-        print(f"{Colors.RED}No relevant pages identified. Consider refining the search parameters or trying a different website.{Colors.RESET}")
-
-if __name__ == "__main__":
-    main()
+import os
+from firecrawl import FirecrawlApp
+import json
+from dotenv import load_dotenv
+from openai import OpenAI
+
+# ANSI color codes
+class Colors:
+    CYAN = '\033[96m'
+    YELLOW = '\033[93m'
+    GREEN = '\033[92m'
+    RED = '\033[91m'
+    MAGENTA = '\033[95m'
+    BLUE = '\033[94m'
+    RESET = '\033[0m'
+
+# Load environment variables
+load_dotenv()
+
+# Retrieve API keys from environment variables
+firecrawl_api_key = os.getenv("FIRECRAWL_API_KEY")
+openai_api_key = os.getenv("OPENAI_API_KEY")
+
+# Initialize the FirecrawlApp and OpenAI client
+app = FirecrawlApp(api_key=firecrawl_api_key)
+client = OpenAI(api_key=openai_api_key)
+
+# Find the page that most likely contains the objective
+def find_relevant_page_via_map(objective, url, app, client):
+    try:
+        print(f"{Colors.CYAN}Understood. The objective is: {objective}{Colors.RESET}")
+        print(f"{Colors.CYAN}Initiating search on the website: {url}{Colors.RESET}")
+        
+        map_prompt = f"""
+        The map function generates a list of URLs from a website and it accepts a search parameter. Based on the objective of: {objective}, come up with a 1-2 word search parameter that will help us find the information we need. Only respond with 1-2 words nothing else.
+        """
+
+        print(f"{Colors.YELLOW}Analyzing objective to determine optimal search parameter...{Colors.RESET}")
+        completion = client.chat.completions.create(
+            model="o1-preview",
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": map_prompt
+                        }
+                    ]
+                }
+            ]
+        )
+
+        map_search_parameter = completion.choices[0].message.content
+        print(f"{Colors.GREEN}Optimal search parameter identified: {map_search_parameter}{Colors.RESET}")
+
+        print(f"{Colors.YELLOW}Mapping website using the identified search parameter...{Colors.RESET}")
+        map_website = app.map_url(url, params={"search": map_search_parameter})
+        print(f"{Colors.GREEN}Website mapping completed successfully.{Colors.RESET}")
+        print(f"{Colors.GREEN}Located {len(map_website)} relevant links.{Colors.RESET}")
+        return map_website
+    except Exception as e:
+        print(f"{Colors.RED}Error encountered during relevant page identification: {str(e)}{Colors.RESET}")
+        return None
+    
+# Scrape the top 3 pages and see if the objective is met, if so return in json format else return None
+def find_objective_in_top_pages(map_website, objective, app, client):
+    try:
+        # Get top 3 links from the map result
+        top_links = map_website[:3] if isinstance(map_website, list) else []
+        print(f"{Colors.CYAN}Proceeding to analyze top {len(top_links)} links: {top_links}{Colors.RESET}")
+        
+        for link in top_links:
+            print(f"{Colors.YELLOW}Initiating scrape of page: {link}{Colors.RESET}")
+            # Scrape the page
+            scrape_result = app.scrape_url(link, params={'formats': ['markdown']})
+            print(f"{Colors.GREEN}Page scraping completed successfully.{Colors.RESET}")
+     
+            
+            # Check if objective is met
+            check_prompt = f"""
+            Given the following scraped content and objective, determine if the objective is met.
+            If it is, extract the relevant information in a simple and concise JSON format. Use only the necessary fields and avoid nested structures if possible.
+            If the objective is not met with confidence, respond with 'Objective not met'.
+
+            Objective: {objective}
+            Scraped content: {scrape_result['markdown']}
+
+            Remember:
+            1. Only return JSON if you are confident the objective is fully met.
+            2. Keep the JSON structure as simple and flat as possible.
+            3. Do not include any explanations or markdown formatting in your response.
+            """
+        
+            completion = client.chat.completions.create(
+            model="o1-preview",
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": check_prompt
+                        }
+                    ]
+                }
+                ]
+            )
+            
+            result = completion.choices[0].message.content
+            
+            if result != "Objective not met":
+                print(f"{Colors.GREEN}Objective potentially fulfilled. Relevant information identified.{Colors.RESET}")
+                try:
+                    return json.loads(result)
+                except json.JSONDecodeError:
+                    print(f"{Colors.RED}Error in parsing response. Proceeding to next page...{Colors.RESET}")
+            else:
+                print(f"{Colors.YELLOW}Objective not met on this page. Proceeding to next link...{Colors.RESET}")
+        
+        print(f"{Colors.RED}All available pages analyzed. Objective not fulfilled in examined content.{Colors.RESET}")
+        return None
+    
+    except Exception as e:
+        print(f"{Colors.RED}Error encountered during page analysis: {str(e)}{Colors.RESET}")
+        return None
+
+# Main function to execute the process
+def main():
+    # Get user input
+    url = input(f"{Colors.BLUE}Enter the website to crawl: {Colors.RESET}")
+    objective = input(f"{Colors.BLUE}Enter your objective: {Colors.RESET}")
+    
+    print(f"{Colors.YELLOW}Initiating web crawling process...{Colors.RESET}")
+    # Find the relevant page
+    map_website = find_relevant_page_via_map(objective, url, app, client)
+    
+    if map_website:
+        print(f"{Colors.GREEN}Relevant pages identified. Proceeding with detailed analysis...{Colors.RESET}")
+        # Find objective in top pages
+        result = find_objective_in_top_pages(map_website, objective, app, client)
+        
+        if result:
+            print(f"{Colors.GREEN}Objective successfully fulfilled. Extracted information:{Colors.RESET}")
+            print(f"{Colors.MAGENTA}{json.dumps(result, indent=2)}{Colors.RESET}")
+        else:
+            print(f"{Colors.RED}Unable to fulfill the objective with the available content.{Colors.RESET}")
+    else:
+        print(f"{Colors.RED}No relevant pages identified. Consider refining the search parameters or trying a different website.{Colors.RESET}")
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,87 @@
+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_links_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)
+POST_URL = "https://www.reddit.com/r/example/comments/abc123/slug/"
+
+
+class LinksFallbackTests(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_arctic_miss_uses_rendered_page_without_loading_browser_cookies(self) -> None:
+        with (
+            mock.patch.object(voc.CookieStore, "get", side_effect=AssertionError("browser cookies loaded")) as cookies,
+            mock.patch.object(voc, "arctic_post_by_permalink", return_value=None) as archive,
+            mock.patch.object(voc, "fetch_page_scrape", return_value={"markdown": "Public page"}) as page,
+            mock.patch.object(voc, "collect_subreddit_metrics", return_value=[]),
+            mock.patch.object(voc, "hub_writeback_items", return_value={"status": "pending"}),
+            mock.patch.object(voc, "sleep_with_jitter", return_value=0.0),
+        ):
+            code, out = self.run_main("links", POST_URL, "--fallback", "auto", "--sleep-sec", "0")
+
+        self.assertEqual(code, 0)
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["items"][0]["item_type"], "firecrawl_page")
+        self.assertEqual(out["errors"], [])
+        archive.assert_called_once()
+        self.assertEqual(page.call_args.kwargs["provider"], "social-hub")
+        cookies.assert_not_called()
+
+    def test_arctic_miss_without_fallback_reports_archive_not_json(self) -> None:
+        with (
+            mock.patch.object(voc.CookieStore, "get", side_effect=AssertionError("browser cookies loaded")) as cookies,
+            mock.patch.object(voc, "arctic_post_by_permalink", side_effect=RuntimeError("archive unavailable")),
+            mock.patch.object(voc, "collect_subreddit_metrics", return_value=[]),
+            mock.patch.object(voc, "hub_writeback_items", return_value={"status": "not_applicable"}),
+            mock.patch.object(voc, "sleep_with_jitter", return_value=0.0),
+        ):
+            code, out = self.run_main("links", POST_URL, "--fallback", "none", "--sleep-sec", "0")
+
+        self.assertEqual(code, 1)
+        self.assertFalse(out["ok"])
+        self.assertTrue(any("archive unavailable" in error for error in out["errors"]))
+        self.assertTrue(any("Arctic lookup failed" in note for note in out["notes"]))
+        cookies.assert_not_called()
+
+    def test_auto_fallback_tries_firecrawl_after_social_hub_failure(self) -> None:
+        def page_result(_url: str, *, provider: str, **_kwargs: object) -> dict:
+            if provider == "social-hub":
+                raise RuntimeError("render unavailable")
+            return {"markdown": "Public page"}
+
+        with (
+            mock.patch.object(voc.CookieStore, "get", side_effect=AssertionError("browser cookies loaded")) as cookies,
+            mock.patch.object(voc, "arctic_post_by_permalink", return_value=None),
+            mock.patch.object(voc, "fetch_page_scrape", side_effect=page_result) as page,
+            mock.patch.object(voc, "social_hub_unavailable_hint", return_value="Hub unavailable"),
+            mock.patch.object(voc, "collect_subreddit_metrics", return_value=[]),
+            mock.patch.object(voc, "hub_writeback_items", return_value={"status": "pending"}),
+            mock.patch.object(voc, "sleep_with_jitter", return_value=0.0),
+        ):
+            code, out = self.run_main("links", POST_URL, "--fallback", "auto", "--sleep-sec", "0")
+
+        self.assertEqual(code, 0)
+        self.assertEqual(out["items"][0]["page_provider"], "firecrawl")
+        self.assertEqual([call.kwargs["provider"] for call in page.call_args_list], ["social-hub", "firecrawl"])
+        cookies.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -155,6 +155,39 @@ social-hub brand-auth revoke --account <ref> --brand <brandKey> [-t <team-id>] [
 
 发布前三点 gate 语义见 [`../../docs/brand-mention-gate-operations.md`](../../docs/brand-mention-gate-operations.md)。
 
+## 板块限制（restrictions，系统级整板限制）
+
+整板 banned / private / quarantined / unavailable 的系统级限制。**一条限制会让全部 team 在该板块的写稿、排期、
+发布同时停下**，所以管理面只给 **admin**，并且只接受**不受限的登录**（`auth login` 的 CLI token 或网页 session）：
+API key、绑定 job/account 或带动作白名单的 CLI token **读写都 403**（权限资源 `systemSubredditRestriction`，
+override 只能收紧，manager 拿不到任何一格）。
+
+```bash
+# 读（系统级 admin 视图：list / fanout 必须显式 --system；不带 --system 走的是 team 只读路由，见下）
+social-hub restrictions list --system [--state provisional,verification_overdue] [--updated-since <iso>] [--subreddit <name>] [--limit 50] [--offset 0]
+social-hub restrictions get <id>                 # 含全量证据；list 只回证据摘要 evidenceSummary
+social-hub restrictions fanout <id> --system [--version <n>] [--outcome blocked] [--team-id <uuid>]
+#   全部 team 的扇出汇总计数 + complete + 回执明细。阶段 B（扇出 worker）上线前恒为空、complete:false —— 不是故障。
+
+# 写：一律 --dry-run 预览 / --apply 执行
+social-hub restrictions create --subreddit r/<name> --kind banned --evidence-level strong \
+  --reason "..." [--state provisional --expires-at <iso>] [--evidence '<json 数组>'] --apply
+#   默认直接 confirmed；provisional 必须带 --expires-at。已有活跃限制 → 409 details.code=RESTRICTION_EXISTS
+social-hub restrictions confirm <id> [--expected-version <n>] --apply   # provisional / verification_overdue → confirmed
+social-hub restrictions revoke <id> --reason "..." [--expected-version <n>] --apply   # 唯一的解封路径
+#   版本不符 → 409 VERSION_MISMATCH；状态不对 → 409 INVALID_STATE（都在 error.details.code）
+```
+
+状态机：`provisional`（已上报待复核，**照样拦**）→ 复核期限过了无人确认 → `verification_overdue`（**继续拦**）；
+admin `confirm` → `confirmed`；admin `revoke` → `revoked`（唯一不拦的状态，可再建新限制）。
+revoke **不会**恢复已经被拦成 `blocked` 的 job，需要人重新排期。
+
+**运营侧 agent 拉取状态（再去私信 admin）不走这里**：用 team 只读路由
+`restrictions list -t <team-id>` / `restrictions fanout <id> -t <team-id>`（`compliance:read`，manager 可用，
+受限 token 也放行；fanout 只含本 team 的回执），见 `social-hub-graph-compliance`。
+runner 侧的 `restrictions check` / `restrictions report` 同样见 `social-hub-graph-compliance`；
+执行链路上 409 `TARGET_BLOCKED` / `JOB_BLOCKED` 的识别与 agent 停止规则见 `social-hub-ops-runtime`。
+
 ## Agent teams
 
 ```bash

package/skills/social-hub-calendar-directives/SKILL.md

@@ -421,10 +421,23 @@ PATCH { "status": "succeeded", "permalink": "…", "executionToken": "<刚才那
 | `execution_token_not_expected`        | 初次抢占时带了 token                      | 代码 bug：抢占不该带 token                               |
 | `expected_revision_not_applicable`    | 终态回写带了 `expectedRevision`           | 代码 bug：去掉它                                         |
 | `revision_stale` / `revision_unknown` | 抢占时的版本钉子对不上                    | 同 preflight 同名 reason 的处置                          |
+| `target_blocked`                      | 目标板块/账号受限（见下）                 | 删 cron、安静退出。**不重试**、不回写终态                |
 
-⚠️ 这些都走 **HTTP 409**、`code = "EXECUTION_NOT_ACQUIRED"`、`details.reason` 取上表的值。
+⚠️ 这些都走 **HTTP 409**、`details.reason` 取上表的值；前六个的 `code = "EXECUTION_NOT_ACQUIRED"`。
 **按 reason 编程分流，别拿人类文案做子串匹配。**
 
+#### `target_blocked`：板块受限
+
+抢 `scheduled → running` 时，若目标板块已被系统级限制（整板 banned / private / quarantined / unavailable，
+含待复核的 provisional 与逾期未复核的 verification_overdue）或该账号在该板块有生效 sanction / bot_bouncer 名单，
+服务端拒绝抢占：HTTP 409，`error.code = "CONFLICT"`，
+`details = { code: "TARGET_BLOCKED", reason: "target_blocked", source, id, kind?, subreddit }`。
+
+- 识别看 `details.reason === "target_blocked"`（或 `details.code === "TARGET_BLOCKED"`），不看 message。
+- 你**没有**拿到 token，这一轮什么都没发生：删本机 cron、退出。**不要重试**——只有 admin 撤销限制才会解除。
+- 已经持有 token 的在途执行不受影响：终态回写照常放行（服务端只在抢占那一步判定）。
+- 条目随后会由服务端以 `cancel`（cancel reason `target_blocked`）广播撤销，按常规 cancel 处置即可。
+
 ## ack 时机（本 source 局部改写通用规则）
 
 通用 notifications skill 说"副作用完成后才 ack"——这条仍然成立，但**这个 source 的副作用是

package/skills/social-hub-calendar-jobs/SKILL.md

@@ -43,6 +43,20 @@ social-hub jobs retry -t <team-id> -i <jobId>
 social-hub jobs cancel -t <team-id> -i <jobId>
 ```
 
+## 🔴 板块受限：建/改排期被拒（409 `TARGET_BLOCKED`）
+
+目标板块受系统级限制，或该账号在该板块有生效 sanction / bot_bouncer 名单时，
+`jobs create` / `jobs batch` / `jobs retry`（以及建计划/排期、改期、切 delivery mode）会被拒：
+HTTP **409**，`error.code = "CONFLICT"`，`error.details = { code: "TARGET_BLOCKED", reason: "target_blocked",
+source, id, kind?, subreddit }`。
+
+- **按 `error.details.code` 识别，不要匹配 message。**
+- **不要重试、不要换个 runAt 再建**：重试只会拿到同一个 409。换一个目标板块，或跳过。解除路径看 `details.source`:`restriction` 只有 admin `restrictions revoke`;`sanction`(团队/账号级)由有权限的人把该 sanction 改为 lifted;`blocklist` 由 admin 维护（不是 agent 的事，报告即可）。
+- 已被拦下的 job 状态是 `blocked`（`lastError` 形如 `target_blocked:<source>:<id>`），是**永久终态**：
+  `jobs retry` 只接受 failed / cancelled，解封后要**新建** job。
+- 执行侧（heartbeat / complete / fail / skip）的受限语义与停止规则见 `social-hub-ops-runtime`；
+  自查与上报见 `social-hub-graph-compliance` 的 `restrictions check` / `restrictions report`。
+
 ## OpenClaw / Agent 运行时
 
 优先 ops 链路（见 `social-hub-ops-runtime`）：

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

@@ -46,6 +46,8 @@ social-hub version --json
 | 帖子发布前审核/优化（post-review）                           | `social-hub-post-review`            |
 | 事件 / dashboard / audit                                     | `social-hub-events-observability`   |
 | 图谱 / 合规 / 风控                                           | `social-hub-graph-compliance`       |
+| 板块限制拉取/自查/上报 restrictions list/fanout/check -t     | `social-hub-graph-compliance`       |
+| 板块限制管理 restrictions create/revoke/--system             | `social-hub-admin`                  |
 | settings / invites / members / api-keys                      | `social-hub-admin`                  |
 | brand-registry / brand-fit / trigger 注册表四眼 / brand-auth | `social-hub-admin`                  |
 | 飞书身份映射同步（告警 @ 谁）                                | `social-hub-admin`                  |

package/skills/social-hub-content-classification/SKILL.md

@@ -42,6 +42,10 @@ worker（单实例 cron）按 active spec 对缺当前 revision 成功 run 的
   这些 run 可能对应帖子的**旧 revision**。要判断某帖「当前」被分成什么，只能用
   `get-subject`（精确唯一键查询，proposed / missing 二态）。**不要拿 `recent` 的
   第一条当 latest 用。**
+- **`recent` 没有分页，返回的是截断后的一页**：`count` / `returned` 是**本页条数，不是总数**；
+  `truncated: true` 表示还有更多（服务端多取一条判定，精确），`selectionLimit` 是本次生效上限。
+  `--limit` 未到 200 时可以调大（上限 200）；**已是 200 仍 `truncated: true`，说明这个 recent 视图枚举不完余项**，
+  **不要自己拼 offset**——这个端点根本不接受分页参数。
 
 ## 读面
 

package/skills/social-hub-graph-compliance/SKILL.md

@@ -73,6 +73,48 @@ social-hub compliance rule-caches-upsert -t <team-id> --sub example -j '{
 }'
 ```
 
+## 板块限制：runner 自查与上报（`restrictions check` / `restrictions report`）
+
+整板限制（banned / private / quarantined / unavailable）存在系统级 `subreddit_restrictions`，
+**只有 admin 能直接建 / 确认 / 撤销**（见 `social-hub-admin`）。agent / runner 用下面这些 **team 级**入口：
+
+```bash
+# 拉取限制状态（compliance:read；manager 可用，受限 token 也放行）。Hub 不推送、不发群：
+# agent 按 --updated-since 增量拉取，自行私信 admin。
+social-hub restrictions list -t <team-id> [--state provisional,verification_overdue] [--updated-since <iso>] [--subreddit <name>] [--limit 50] [--offset 0]
+# → {items,total,limit,offset,hasMore}；每项带 state / expiresAt / lastVerifiedAt / createdBy / updatedAt / evidenceSummary（不含全量证据）
+social-hub restrictions fanout <restriction-id> -t <team-id> [--version <n>] [--outcome blocked]
+# → 只统计、只返回**本 team** 的回执（counts / receipts）；complete 按全局扇出判断；
+#   阶段 B（扇出 worker）上线前恒为空、complete:false —— 不是故障。
+# 缺省 -t 用当前 context 的 team；两者都没有会报错（不会改走 admin 面）。--system 是 admin 专用的系统级视图。
+
+# 动手前自查（compliance:read）。不带 --account 只判系统级；带上才同时判该账号的 sanction。
+social-hub restrictions check -t <team-id> --subreddit <name> [--account <accountId>]
+# → {"allowed":true,...} 或 {"allowed":false,"scope":"system|account","source":"restriction|blocklist|sanction",
+#    "id":"...","kind":"...","state":"provisional|confirmed|verification_overdue|null","expiresAt":...}
+# allowed:false = 本轮跳过这个目标，不要重试。
+
+# 发现受限时上报（compliance:create；写命令，需 --apply，可先 --dry-run）
+social-hub restrictions report -t <team-id> --subreddit <name> --account <accountId> \
+  --kind banned --evidence '[{"type":"banned_page","url":"https://www.reddit.com/r/<name>","observedAt":"<iso>"}]' \
+  --evidence-level strong --reason "banner: r/<name> has been banned" \
+  --expires-at <复核期限 iso> [--scope system] --apply
+```
+
+`report` 的落点（第一版刻意保守，**服务端封禁页解析器在阶段 C 才做**，现在信的是你的声明）：
+
+| 你传的                                       | 实际写入                                                                             | 响应                                                                     |
+| -------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `--scope system` + `--evidence-level strong` | 系统级 **provisional**（立即对全部 team 生效，要求 manager/admin；supervisor → 403） | `target:"system"`，`created:false` = 板块已有限制，原样返回现行行摘要    |
+| `--scope system` + `weak`                    | 降级为该 team+账号的 sanction                                                        | `target:"account"`，`downgraded:true`，`downgradeReason:"weak_evidence"` |
+| 缺省 / `--scope account`                     | 该 team+账号的 sanction（banned → `banned`，其余 → `restricted`）                    | `target:"account"`，`downgraded:false`                                   |
+
+- 证据至少一条、`--expires-at` 必填（复核期限）。provisional 过期**不会**解封，而是转 `verification_overdue` 继续拦，
+  只有 admin `restrictions revoke` 才解封。
+- 落 sanction 时**不会**把复核期限写成 sanction 过期（那会自动解封）；期限记在 reason 前缀和事件里。
+- 只有「整板对所有人都不可用」才用 `--scope system`。账号自己被 ban（「you've been banned from r/X」）用默认 account。
+- 执行链路上被拦（409 `TARGET_BLOCKED` / `JOB_BLOCKED`）的识别与停止规则见 `social-hub-ops-runtime`。
+
 ## 系统级板块黑名单（Bot Bouncer 等）
 
 与 **per-account** `sanctions-*` 不同：名单为 **系统级**（`/v1/system/subreddit-blocklists`），全 team 共享，表示 Reddit 平台客观事实（如 bot-bouncer 安装 sub），无需 `-t`。

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

@@ -259,11 +259,32 @@ watchlist 须显式传 `brandIds`。
 ```bash
 social-hub intelligence monitors-list [--enabled true|false] [--watchlist <uuid>]
 social-hub intelligence monitors-enable --watchlist <uuid> [--fetch-limit 100]
+social-hub intelligence monitors-update --watchlist <uuid> --fetch-limit 50   # 只改配置,不碰启停
 social-hub intelligence monitors-disable --watchlist <uuid> [--purge]
 social-hub intelligence monitors-run                      # 手工触发一轮(异步入队)
 social-hub intelligence monitor-runs-list [--status degraded] [-n 20]
 ```
 
+### 🔴 改抓取上限用 `monitors-update`,⛔ 不要用 `monitors-enable`
+
+`monitors-enable` 是个 **upsert**,它的 `DO UPDATE` 里写死了 `enabled = true` ——
+所以拿它去改一个**已停止**监听的 `--fetch-limit`,会把那个监听**静默重新启用**,
+该板块的新帖会立刻重新推给负责人。
+
+`monitors-update` 背后的 SQL 里**根本不出现 `enabled` 列**,所以它没有能力改启停:
+停止状态下改完仍是停止,启用状态下改完仍是启用。
+
+| 我要做的事          | 用哪个命令                          |
+| ------------------- | ----------------------------------- |
+| 加入监听 / 重新启用 | `monitors-enable`                   |
+| **只改抓取上限**    | `monitors-update`(启停状态原样不动) |
+| 停止监听(软停)      | `monitors-disable`                  |
+
+⚠️ `monitors-update` **不会创建**监听:该 watchlist 从没配置过监听时返回 404
+(要新建请显式用 `monitors-enable`)。
+⚠️ `--fetch-limit` 两个命令同一套边界:整数 1–100。
+⚠️ `sort` **没有任何写入面**,两个命令都不收 —— DDL 的 CHECK 只允许 `'new'` 一个值。
+
 **停止监听 = 软停**(`enabled=false`),保留观察 ledger,重启后已报告过的帖子不会重复报告。
 `--purge` 是另一个动作:**连历史观察一起硬删**,只有要删掉整个 watchlist 时才需要
 (monitor 配置对 watchlist 的外键是 RESTRICT,不先 purge 就删不掉)——purge 后重新监听
@@ -604,4 +625,6 @@ WebSocket `runs/ws` 为 watch 能力，不适合普通 CLI 批处理。
 
 ## 通用网页抓取
 
-本 skill 只覆盖**系统内部**的 Reddit 情报采集（落库 + 聚合，走 worker 直连 curl_cffi + 住宅代理）。若要**按任意 URL 临时抓取**（Reddit `.json` 走直连、HTML/普通网页走 Firecrawl），用独立的 **`social-hub-scrape`** skill（`social-hub scrape url …`）。
+本 skill 只覆盖**系统内部**的 Reddit 情报采集（落库 + 聚合）。worker 侧仍先试 `.json`（curl_cffi + 住宅代理），**但 `.json` 已被 Reddit 全面拦截**（2026-09-18 实测住宅代理同样 403）——真正出数的是封禁熔断器之后的 **Firecrawl 渲染兜底**（需 worker 配 `FIRECRAWL_BASE_URL`，`REDDIT_FIRECRAWL_FALLBACK_ENABLED` 不显式关即生效）。
+
+若要**按任意 URL 临时抓取非 Reddit 页面**（HTML/普通网页走 Firecrawl），用独立的 **`social-hub-scrape`** skill（`social-hub scrape url …`）。⛔ **不要用它抓 Reddit**：该端点的 `.json` 直连与 Firecrawl 渲染两条路都被拦（见该 skill 顶部红字）。