@geoly-ai/social-hub-cli 0.0.11 → 0.0.13

package/skills/social-hub-events-observability/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: social-hub-events-observability
+description: >-
+  互动事件与可观测性：social-hub events append/list/batch/export-csv、dashboard summary、
+  audit list、reports list/create/ingest。用户要记事件、查运营总览、审计日志或报告库时用本 skill。
+metadata:
+  cliVersion: ">=0.0.12"
+---
+
+# social-hub-events-observability
+
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 `auth login` 并 `context use <team-id>`。
+
+## 互动事件
+
+```bash
+social-hub events append -t <team-id> --type comment --payload '{"permalink":"https://..."}'
+social-hub events list -t <team-id> -n 20
+social-hub events list-full -t <team-id> --account <uuid> --type post.published -n 100
+social-hub events batch -t <team-id> -j '{"items":[{"type":"comment","payload":{...}}]}'
+social-hub events export-csv -t <team-id> > events.csv
+```
+
+## 运营总览
+
+```bash
+social-hub dashboard summary -t <team-id>
+```
+
+## 审计日志
+
+```bash
+social-hub audit list -t <team-id> -n 50 [--type <prefix>] [--actor agent] [--account <uuid>]
+```
+
+## 报告库
+
+```bash
+social-hub reports list -t <team-id> -n 20
+social-hub reports create -t <team-id> -j '{"title":"Weekly","bodyMarkdown":"..."}'
+social-hub reports ingest -t <team-id> -j '{"source":"external","payload":{...}}'
+```
+
+## 相关 skill
+
+- 发布闭环：`social-hub-publishing`
+- 图谱追溯：`social-hub-graph-compliance`
+- 批量导出/回放：`social-hub-migration`（`export events-jsonl`、`runbook replay`）

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

@@ -0,0 +1,60 @@
+---
+name: social-hub-graph-compliance
+description: >-
+  账号图谱与合规风控：social-hub graph list/drilldown/v2-*、compliance sanctions-*、
+  risk-*、rule-caches-*。用户要查账号关联图谱、风险簇、制裁、风控配置或 subreddit
+  规则缓存时用本 skill。
+metadata:
+  cliVersion: ">=0.0.12"
+---
+
+# social-hub-graph-compliance
+
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 `auth login` 并 `context use <team-id>`。
+
+## 账号图谱（v1）
+
+```bash
+social-hub graph list -t <team-id> [--account <uuid>] [--edge <type>] -n 100
+social-hub graph drilldown -t <team-id> --account <uuid> -n 20
+```
+
+## 账号图谱（v2）
+
+```bash
+social-hub graph v2-ego -t <team-id> --node-ref <account-uuid> --node-type account -n 100
+social-hub graph v2-timeline -t <team-id> --node-ref <account-uuid> --node-type account --from 2026-01-01T00:00:00Z
+social-hub graph v2-explain -t <team-id> --edge-id <edge-uuid>
+social-hub graph v2-path -t <team-id> --source-ref <uuid> --source-type account --target-ref <uuid> --target-type account
+social-hub graph v2-clusters -t <team-id> --scope-ref <account-uuid> --min-risk 60
+social-hub graph v2-impact -t <team-id> --campaign-ref <campaign-uuid> --min-reuse 2
+```
+
+## 合规：制裁与风控
+
+```bash
+social-hub compliance sanctions-list -t <team-id> [--account <uuid>] [--sub <name>]
+social-hub compliance sanctions-create -t <team-id> -j '{"socialAccountId":"<uuid>","subreddit":"example","status":"blocked","reason":"..."}'
+
+social-hub compliance risk-list -t <team-id> -n 100
+social-hub compliance risk-get -t <team-id> -a <account-uuid>
+social-hub compliance risk-put -t <team-id> -a <account-uuid> -j '{"riskLevel":"medium","safeHoursStart":"08:00","safeHoursEnd":"22:00"}'
+```
+
+## Subreddit 规则缓存
+
+```bash
+social-hub compliance rule-caches-list -t <team-id> [--include-expired]
+social-hub compliance rule-caches-upsert -t <team-id> --sub example -j '{
+  "rulesMarkdown": "# Rules\n...",
+  "sourceUrl": "https://www.reddit.com/r/example/about/rules",
+  "expiresInDays": 30
+}'
+```
+
+## 相关 skill
+
+- 账号详情：`social-hub-accounts`
+- 互动事件追溯：`social-hub-events-observability`
+- Agent 上下文（含 risk/guardrails）：`social-hub-openclaw-context`

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

@@ -1,26 +1,91 @@
 ---
 name: social-hub-intelligence
 description: >-
-  板块情报：watchlists、hot posts、KOL intents、industry-pools、dispatch 等 social-hub intelligence 子命令。
-  用户要盯 subreddit、拉热帖、行业池、情报派发时用本 skill。
+  板块情报：watchlists、hot-posts、kol-intents、industry-pools、tier-rules、runs、
+  kol-profiles、fetch-by-*、insights/*、dispatch 等 social-hub intelligence 子命令。
+  用户要盯 subreddit、拉热帖、行业池、情报派发、分层规则或洞察分析时用本 skill。
 metadata:
-  cliVersion: ">=0.0.6"
+  cliVersion: ">=0.0.12"
 ---
 
 # social-hub-intelligence
 
 > **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
-> 确认已 auth login 并 `context use <team-id>`。
+> 确认已 `auth login` 并 `context use <team-id>`。
+
+## Watchlists 与行业池
 
 ```bash
 social-hub intelligence industry-pools-list -t <team-id>
-social-hub intelligence watchlists-list -t <team-id>
+social-hub intelligence watchlists-list -t <team-id> [--campaign <uuid>]
+social-hub intelligence watchlists-create -t <team-id> -j '{"subreddit":"technology","tags":["core"]}'
+social-hub intelligence watchlists-update -t <team-id> --id <uuid> -j '{"tags":["updated"]}'
+social-hub intelligence watchlists-delete -t <team-id> --id <uuid>
+```
+
+## 热帖
+
+```bash
 social-hub intelligence hot-posts -t <team-id> --subreddit technology --sort score -n 50
+social-hub intelligence hot-posts-create -t <team-id> -j '{ ... }'
+social-hub intelligence hot-posts-export -t <team-id> --subreddit technology > hot-posts.csv
+```
+
+## KOL
+
+```bash
 social-hub intelligence kol-intents -t <team-id> -n 20
-social-hub intelligence dispatch -t <team-id> -j '{ ... }'   # 写操作：确认 payload 与 --apply（若命令支持）
+social-hub intelligence kol-intents-create -t <team-id> -j '{ ... }'
+social-hub intelligence kol-profiles-list -t <team-id> [--platform reddit]
+social-hub intelligence kol-profiles-get -t <team-id> --id <uuid>
 ```
 
-账号可发帖板块优先用 Hub DB 查询，不要猜 subreddit：
+## Tier rules
+
+```bash
+social-hub intelligence tier-rules-list -t <team-id> [--tier T1] [--enabled true]
+social-hub intelligence tier-rules-create -t <team-id> -j '{"subreddit":"example","tier":"T1","entryMode":"organic","enabled":true}'
+social-hub intelligence tier-rules-update -t <team-id> --id <uuid> -j '{"enabled":false}'
+social-hub intelligence tier-rules-delete -t <team-id> --id <uuid>
+```
+
+## 抓取任务（异步 run）
+
+```bash
+social-hub intelligence fetch-by-industry -t <team-id> -j '{"mode":"all","industryKeys":["tech"],"sort":"hot","limitPerSubreddit":25}'
+social-hub intelligence fetch-by-tier -t <team-id> -j '{"mode":"all","tier":"T1","sort":"hot"}'
+social-hub intelligence fetch-by-keywords -t <team-id> -j '{"mode":"all","brandKeywords":["brand"],"competitorKeywords":["rival"]}'
+social-hub intelligence runs-list -t <team-id> [--dimension industry] [--status queued]
+```
+
+## Insights
+
+```bash
+social-hub intelligence brand-mention-radar -t <team-id> -j '{"keywords":["brand"]}'
+social-hub intelligence opportunity-map -t <team-id> -j '{"keywords":["topic"]}'
+social-hub intelligence sov -t <team-id> -j '{"brandKeywords":["brand"],"competitorKeywords":["rival"]}'
+social-hub intelligence sentiment-intent -t <team-id>
+social-hub intelligence campaign-lift -t <team-id> -j '{"keywords":["brand"],"campaignStartAt":"2026-01-01T00:00:00Z","campaignEndAt":"2026-02-01T00:00:00Z"}'
+social-hub intelligence snapshot-latest -t <team-id>
+social-hub intelligence snapshot-save -t <team-id> -j '{"payload":{"note":"manual snapshot"}}'
+```
+
+## 派发到调度任务
+
+```bash
+social-hub intelligence dispatch -t <team-id> -j '{
+  "hotPostId": "<uuid>",
+  "socialAccountId": "<uuid>",
+  "action": "engage",
+  "runAt": "2026-05-07T09:00:00Z"
+}'
+```
+
+`dispatch` 无 `--dry-run`/`--apply`；确认 payload 后再执行。
+
+## 板块候选（Hub DB）
+
+不要猜账号可发哪些 subreddit：
 
 ```bash
 social-hub query account-pools -t <team-id> --account <ref>

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

@@ -2,15 +2,15 @@
 name: social-hub-migration
 description: >-
   Hub 数据批量：export events-jsonl、export agent-context、runbook replay、openclaw-ingest。
-  用户要导出 JSONL、回放事件、迁移/对账时用本 skill；不包含工作区 shared 目录批量 sync（需人工决策）。
+  用户要导出 JSONL、回放事件、迁移/对账时用本 skill；不包含 agent 工作区目录的自动批量 sync。
 metadata:
-  cliVersion: ">=0.0.6"
+  cliVersion: ">=0.0.12"
 ---
 
 # social-hub-migration
 
 > **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
-> 确认已 auth login；导出/回放目标 team 用 `-t <team-id>`。
+> 确认已 `auth login`；导出/回放目标 team 用 `-t <team-id>`。
 
 ## 导出
 
@@ -19,6 +19,8 @@ social-hub export events-jsonl -t <team-id> -o events.jsonl -n 500
 social-hub export agent-context -t <team-id> --account <uuid> -o ctx.json
 ```
 
+事件 CSV 导出见 `social-hub-events-observability`（`events export-csv`）。
+
 ## Runbook 回放
 
 ```bash
@@ -30,6 +32,17 @@ JSONL 每行：`{"type":"comment","payload":{...}}`
 
 ## openclaw-ingest
 
-API 支持将工作区文档写入 `team_workspace_documents`；**不要**在本 skill 内自动化批量 sync 整个 `Javis-workspace/shared` 或 `Moss-workspace/shared`，除非用户明确要求并指定范围。
+将 agent 工作区文档写入 `team_workspace_documents`（需用户明确范围）：
+
+```bash
+social-hub openclaw-ingest -t <team-id> -j '{"mode":"dry-run"}'
+social-hub openclaw-ingest -t <team-id> -j '{
+  "mode": "apply",
+  "sourceRoot": "/path/to/agent-workspace",
+  "sourcePaths": { "guardrails": "shared/guardrails.md" }
+}'
+```
+
+**不要**在本 skill 内自动化批量 sync 整个 agent 工作区 `shared/`，除非用户明确要求并指定路径。
 
-运行时查询请用 `social-hub-openclaw-context`，不是解析 Markdown。
+运行时查询请用 `social-hub-openclaw-context`（Hub DB 真源），不是解析 Markdown。

package/skills/social-hub-openclaw-context/SKILL.md

@@ -1,17 +1,26 @@
 ---
 name: social-hub-openclaw-context
 description: >-
-  OpenClaw Agent 执行前上下文：social-hub context account/job、query account-pools、subreddit-candidates、
-  export agent-context。用户问账号能发哪些版、任务上下文、板块池、guardrails、数据是否过期时，
-  必须用 Hub DB 聚合接口，不要解析 Javis/Moss/Panda 工作区里的 shared/*.md。
+  OpenClaw Agent 执行前上下文：social-hub context account/job、query account-pools、
+  subreddit-candidates、export agent-context。用户问账号能发哪些版、任务上下文、板块池、
+  guardrails、数据是否过期时，必须用 Hub DB 聚合接口，不要解析 agent 工作区 Markdown。
 metadata:
-  cliVersion: ">=0.0.6"
+  cliVersion: ">=0.0.12"
 ---
 
 # social-hub-openclaw-context
 
 > **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
-> 确认已 auth login。所有 `-t <team-id>` 与授权 team 一致。
+> 确认已 `auth login`。所有 `-t <team-id>` 与授权 team 一致。
+
+## 与 shared 的分工
+
+| 命令 | 所在 skill |
+|------|------------|
+| `context list` / `use` / `current` | `social-hub-shared` |
+| `context account` / `context job` | 本 skill |
+| `query account-pools` / `subreddit-candidates` | 本 skill |
+| `export agent-context` | 本 skill（亦见 `social-hub-migration`） |
 
 ## 账号上下文
 
@@ -43,6 +52,12 @@ social-hub export agent-context -t <team-id> --account <uuid> -o /tmp/ctx.json
 
 ## freshness
 
-响应中 `freshness.needsRefresh === true` 时，应先刷新账号指标或情报，再执行发帖/评论。
+响应中 `freshness.needsRefresh === true` 时，应先刷新账号指标或情报，再执行发帖/评论：
+
+```bash
+social-hub accounts update -t <team-id> --account <uuid> -j '{"metricsUpdatedAt":"..."}'
+social-hub reddit refresh-all -t <team-id>
+social-hub intelligence fetch-by-industry -t <team-id> -j '{ ... }'
+```
 
 执行任务前配合 `social-hub-ops-runtime`；执行后 `ops complete` 回填 permalink。

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

@@ -4,25 +4,28 @@ description: >-
   OpenClaw / Agent 任务运行时：social-hub ops claim-next、claim、heartbeat、complete、fail、skip。
   用户要领任务、续租、心跳、回填 permalink、任务失败/跳过、避免改本地 Markdown 状态时必须用本 skill。
 metadata:
-  cliVersion: ">=0.0.6"
+  cliVersion: ">=0.0.12"
 ---
 
 # social-hub-ops-runtime
 
 > **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
-> 确认已 auth login 并 `context use <team-id>`。不要用环境变量传 team 或 API key。
+> 确认已 `auth login` 并 `context use <team-id>`。
 
-Hub DB 是执行状态的真源；不要用 `shared/reddit-account-status.md` 等文件记录任务结果。
+Hub DB 是执行状态的真源；不要用 agent 工作区 `shared/*.md` 记录任务结果。
 
 ## 推荐流程
 
 ```bash
-AGENT="javis"   # 或 moss / 你的 agentId
+AGENT="<agent-id>"
 
 social-hub ops claim-next -t <team-id> --agent "$AGENT"
+# 或指定 job：
+social-hub ops claim -t <team-id> --job <jobId> --agent "$AGENT"
+
 social-hub context job -t <team-id> --job <jobId>
 social-hub ops heartbeat -t <team-id> --job <jobId> --agent "$AGENT"
-# 执行 Reddit / 浏览器操作，并写 interaction events（见 social-hub-cli events）
+# 执行 Reddit / 浏览器操作，并写 interaction events（见 social-hub-events-observability）
 social-hub ops complete -t <team-id> --job <jobId> --agent "$AGENT" --permalink "https://reddit.com/..."
 ```
 
@@ -40,3 +43,5 @@ social-hub ops skip -t <team-id> --job <jobId> --agent "$AGENT" --reason manual_
 ## 并发
 
 同一账号同时只能有一个有效 lease；重复 claim 会被拒绝。`complete` 会原子更新 job 与关联 calendar（若 payload 含 calendarEntryId）。
+
+遗留路径 `jobs agent-status` 仅在未接 ops 链路时使用（见 `social-hub-calendar-jobs`）。

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

@@ -1,61 +1,92 @@
 ---
 name: social-hub-posts
 description: >-
-  Reddit 帖快照与数据：social-hub reddit list/stats/refresh/refresh-all/create-snapshot/batch-upsert 等。
-  用户要查帖表现、刷新 score、写入/更新帖快照、permalink 对应快照时用本 skill（命令组名为 reddit）。
+  Reddit 帖快照 CRUD 与批量写入：social-hub reddit list/stats/refresh/refresh-all/
+  create-snapshot/update/delete/batch-upsert。用户要查帖表现、刷新 score、写入或更新
+  外部来源帖快照时用本 skill（命令组名为 reddit）。不负责从飞书或其他系统取数。
 metadata:
-  cliVersion: ">=0.0.6"
+  cliVersion: ">=0.0.12"
 ---
 
 # social-hub-posts
 
 > **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
-> 确认已 auth login 并选定 team。
+> 确认已 `auth login` 并 `context use <team-id>`。
+
+## 职责边界
+
+| 做 | 不做 |
+|---|---|
+| Hub 内 Reddit 帖快照的查询、刷新、单条/批量写入 | 从飞书 Base、CSV、工作区 Markdown 读取并映射字段 |
+| 说明 `batch-upsert` 的 JSON item 字段与幂等行为 | team 路由、外部 ETL 脚本、来源系统鉴权 |
+| 删除/刷新前提示风险 | 用 `reddit import-feishu`（已废弃） |
+
+外部数据（飞书、表格、爬虫）应先在你自己的流程里整理成 JSON，再调用本模块命令写入 Hub。
 
 ## 查询与刷新
 
 ```bash
 social-hub reddit list -t <team-id> -n 20
 social-hub reddit stats -t <team-id> --campaign <uuid>
-social-hub reddit refresh-status -t <team-id> --id <snapshotId>
+social-hub reddit refresh-status -t <team-id>
+social-hub reddit refresh -t <team-id> --snapshot <snapshotId>
+social-hub reddit refresh-progress -t <team-id> --task <taskId>
 social-hub reddit refresh-all -t <team-id>
 ```
 
-## 写入帖快照（含飞书同步）
-
-**不要用 `reddit import-feishu`。** 飞书数据在本机用 `lark-cli` 读取，再用 Hub 写入命令同步。
+## 单条写入与更新
 
 ```bash
-# 本机读飞书 Base（示例）
-lark-cli base +record-list \
-  --base-token <baseToken> \
-  --table-id <tableId> \
-  --view-id <viewId>
-
-# 单条补录
 social-hub reddit create-snapshot -t <team-id> -j '{
-  "permalink": "https://www.reddit.com/r/.../comments/.../",
+  "permalink": "https://www.reddit.com/r/example/comments/abc/title/",
   "subreddit": "example",
+  "title": "Post title",
   "score": 0,
   "commentsCount": 0,
-  "source": "feishu"
+  "source": "manual"
 }'
 
-# 批量幂等 upsert（推荐；同一 teamId + permalink 重复执行只更新）
+social-hub reddit update -t <team-id> --snapshot <uuid> -j '{"score":42,"commentsCount":3}'
+social-hub reddit delete -t <team-id> --snapshot <uuid>   # 危险：确认用户意图
+```
+
+## 批量 upsert（外部来源帖快照）
+
+```bash
 social-hub reddit batch-upsert -t <team-id> -j '{
   "items": [
     {
-      "permalink": "https://www.reddit.com/r/.../comments/.../",
+      "permalink": "https://www.reddit.com/r/example/comments/abc/title/",
       "subreddit": "example",
       "title": "...",
       "score": 12,
       "commentsCount": 3,
-      "source": "feishu"
+      "source": "external",
+      "feishuRecordId": "recXXX",
+      "baseToken": "optional-base-token",
+      "tableId": "optional-table-id",
+      "viewCount": 100,
+      "brandRaw": "BrandName",
+      "rawPayload": { "custom": "fields" }
     }
   ]
-}'
+}' --dry-run
 ```
 
-多品牌/多 team：先 `social-hub agent-teams list` 建立品牌 → teamId 映射，再对每个 team 分别调用 `batch-upsert`（`-t` 为目标 team UUID）。
+### Item 字段说明
+
+- **必填（推荐）**：`subreddit`；有真实 Reddit 链接时带 `permalink`
+- **可选**：`title`、`score`、`commentsCount`、`postedAt`、`source`、`rawPayload`
+- **`feishuRecordId`**：飞书记录 ID。当输入来自飞书时，Hub 优先按 `(teamId, feishuRecordId)` 幂等；同一 permalink 对应不同飞书记录时，后续记录可能获得 `feishu.local` 占位 permalink
+- **无 permalink**：可只带 `feishuRecordId`（及 `baseToken`/`tableId`），Hub 会生成稳定占位 URL
+
+### 幂等与风险
+
+- 重复 `batch-upsert` 同一条外部记录应更新而非重复插入（取决于提供的幂等键）
+- `delete` 不可恢复；批量写入前先 `--dry-run` 查看计数
+- 不要用已废弃的 `reddit import-feishu`
+
+## 与发布链路的关系
 
-发帖成功后应通过 `social-hub ops complete --permalink ...` 写回任务链路（见 `social-hub-publishing` / `social-hub-ops-runtime`）。
+发帖任务成功后，优先通过 `social-hub ops complete --permalink ...` 回填（见 `social-hub-ops-runtime`）。
+需要手动补快照时用 `create-snapshot` 或 `batch-upsert`。

package/skills/social-hub-posts/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "social-hub-posts",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "查 team <team-id> 最近 20 条 Reddit 帖快照，并按 campaign <campaign-id> 看 stats 汇总。我已 auth login。",
+      "expected_output": "social-hub reddit list、reddit stats；不路由到飞书同步或 lark-cli",
+      "assertions": []
+    },
+    {
+      "id": 1,
+      "prompt": "我有一批外部 JSON 帖数据（含 permalink、subreddit、score、feishuRecordId recABC），要批量写入 Hub team <team-id>，先 dry-run 再 apply。",
+      "expected_output": "social-hub reddit batch-upsert --dry-run 然后正式 upsert；说明 feishuRecordId 幂等；不展开飞书取数流程",
+      "assertions": []
+    },
+    {
+      "id": 2,
+      "prompt": "刷新 team <team-id> 全部 Reddit 帖 score，并查看 refresh 任务进度。",
+      "expected_output": "social-hub reddit refresh-all、reddit refresh-status 或 refresh-progress",
+      "assertions": []
+    }
+  ]
+}

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

@@ -1,34 +1,98 @@
 ---
 name: social-hub-publishing
 description: >-
-  内容发布闭环：campaign → plan → draft → calendar → scheduled_job → events → reddit snapshot → report。
-  用户要从草稿到排期、执行任务、permalink 回填、避免 job 成功但 calendar 未更新时用本 skill。
+  内容发布闭环：brands、campaigns、plans、drafts、calendar、jobs、events、reddit snapshot、
+  reports。用户要从草稿到排期、执行任务、permalink 回填、避免 job 成功但 calendar 未更新时用本 skill。
 metadata:
-  cliVersion: ">=0.0.6"
+  cliVersion: ">=0.0.12"
 ---
 
 # social-hub-publishing
 
 > **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
-> 确认已 auth login 并 `context use <team-id>`。
+> 确认已 `auth login` 并 `context use <team-id>`。
 
 ## 事实源
 
 - **计划**：`calendar_entries`
 - **执行**：`scheduled_jobs`
-- 本地 Markdown 日历仅作导入/导出视图，不是运行时真源
+- agent 工作区 Markdown 日历仅作导入/导出视图，不是运行时真源
 
 ## 链路
 
 ```
-campaign → publishing_plan → content_draft → calendar_entry → scheduled_job
+brand → campaign → content_draft → publishing_plan → calendar_entry → scheduled_job
   → interaction_events → reddit_post_snapshot → op_report
 ```
 
-## Agent 推荐
+## 品牌与 Campaign
 
-1. 创建/查询 draft、plan、calendar、job（见 `social-hub-cli` 对应命令）
-2. `social-hub ops claim-next` → 执行 → `social-hub ops complete --permalink <url>`
-3. `complete` 原子更新 job + calendar（+ 可选 snapshot id）
+```bash
+social-hub brands list -t <team-id>
+social-hub brands create -t <team-id> -j '{"name":"My Brand","slug":"my-brand"}'
+social-hub brands update -t <team-id> --brand <uuid> -j '{"name":"Updated"}'
 
-失败时 `ops fail` / `ops skip`，并使用标准 `reason` 枚举（见 `social-hub-ops-runtime`）。
+social-hub campaigns list -t <team-id> [--brand <uuid>]
+social-hub campaigns create -t <team-id> -j '{"brandId":"<uuid>","name":"2026 Launch"}'
+social-hub campaigns get -t <team-id> --campaign <uuid>
+social-hub campaigns update -t <team-id> --campaign <uuid> -j '{"name":"Renamed"}'
+
+social-hub campaigns accounts list -t <team-id> --campaign <uuid>
+social-hub campaigns accounts assign -t <team-id> --campaign <uuid> --account <uuid>
+social-hub campaigns accounts remove -t <team-id> --campaign <uuid> --account <uuid>
+```
+
+## 草稿与计划
+
+```bash
+social-hub drafts list -t <team-id> -n 20
+social-hub drafts create -t <team-id> -j '{"campaignId":"<uuid>","title":"Launch","body":"..."}'
+social-hub drafts get -t <team-id> --draft <uuid>
+social-hub drafts update -t <team-id> --draft <uuid> -j '{"body":"..."}'
+social-hub drafts delete -t <team-id> --draft <uuid>
+
+social-hub plans list -t <team-id>
+social-hub plans create -t <team-id> -j '{"campaignId":"<uuid>","name":"Week 1","entries":[...]}'
+social-hub plans cancel -t <team-id> --plan <uuid>
+```
+
+## 日历与任务
+
+见 `social-hub-calendar-jobs`：
+
+```bash
+social-hub calendar list -t <team-id> --status scheduled
+social-hub jobs list -t <team-id> --status scheduled
+```
+
+## Agent 执行与回填
+
+优先 ops 链路（见 `social-hub-ops-runtime`）：
+
+```bash
+social-hub ops claim-next -t <team-id> --agent <agent-id>
+social-hub ops complete -t <team-id> --job <jobId> --agent <agent-id> --permalink "https://..."
+```
+
+手动回填（无 ops 时）：
+
+```bash
+social-hub calendar patch -t <team-id> -e <entryId> --body '{"status":"succeeded","permalink":"..."}'
+social-hub events append -t <team-id> --type post.published --payload '{"permalink":"..."}'
+```
+
+## 帖快照与报告
+
+```bash
+social-hub reddit create-snapshot -t <team-id> -j '{ ... }'    # 见 social-hub-posts
+social-hub reports list -t <team-id>
+social-hub reports create -t <team-id> -j '{"title":"Weekly","bodyMarkdown":"..."}'
+```
+
+## 决策：ops complete vs 手动 patch
+
+| 场景 | 推荐 |
+|------|------|
+| OpenClaw/Agent 刚执行完 scheduled job | `ops complete` |
+| 无 job、仅补 calendar 状态 | `calendar patch` + `events append` |
+| 外部已发帖、补 Hub 快照 | `reddit create-snapshot` 或 `batch-upsert` |

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

@@ -6,7 +6,7 @@ description: >-
   权限不足、或任何 Hub CLI 写操作前必须先读本 skill。Agent 日常凭证只用 auth login，
   不要用 SOCIAL_HUB_API_KEY 环境变量。
 metadata:
-  cliVersion: ">=0.0.6"
+  cliVersion: ">=0.0.12"
 ---
 
 # social-hub-shared
@@ -65,7 +65,9 @@ social-hub auth login --duration long
 ```bash
 social-hub auth whoami      # 同 auth status；含 role、teamId、visibleTeamIds
 social-hub auth status
-social-hub auth explain     # 当前 role 可用命令
+social-hub auth explain     # 当前 role 可用命令（本地 gate 表）
+social-hub permissions matrix -t <team-id>   # 团队权限矩阵（API）
+social-hub permissions explain               # CLI 命令与权限映射
 social-hub auth logout
 social-hub auth logout --revoke   # 同时撤销服务端 CLI token
 ```
@@ -75,7 +77,7 @@ social-hub auth logout --revoke   # 同时撤销服务端 CLI token
 多数命令需要 `-t <team-uuid>`。先持久化当前 team，示例里可直接引用：
 
 ```bash
-social-hub context use <team-uuid> [--label "moss"]
+social-hub context use <team-uuid> [--label "prod-team-a"]
 social-hub context current
 social-hub context list     # 含 authTeamId、visibleTeamIds
 ```
@@ -118,9 +120,11 @@ CLI 仍兼容 `social-hub auth login --api-key sk_live_…` 与 `SOCIAL_HUB_API_
 1. `social-hub doctor` — API 可达性、`/health/live`、auth context
 2. `social-hub auth whoami` — 确认 `role` 与 `teamId`
 3. `social-hub context current` — 确认 `-t` 与授权 team 一致
-4. `social-hub auth explain` — 当前 role 是否允许该命令
+4. `social-hub auth explain` — 当前 role 是否允许该命令（基于 CLI 本地 gate 表）
 5. 403 / permission denied — 换有权限的 Web 账号重新 `auth login`，或请 admin 调整成员角色
 
+CLI 对部分命令（含 admin 域 settings/invites/members、reddit/accounts 写操作）会**先本地 RBAC 预检**再调 API；`auth explain` 展示的是本地 gate 映射，**后端 `assertRuntimePermission` 仍是最终裁决**。
+
 admin 专属操作（如 `agent-teams create`）需要 **admin** role 的 CLI token，不是「随便创建一个 API Key」就能替代。
 
 ## 安全规则