@geoly-ai/social-hub-cli 0.0.12 → 0.0.14

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

@@ -1,61 +1,94 @@
 ---
 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-ops-runtime`）。
+需要手动补快照时用 `create-snapshot` 或 `batch-upsert`。
 
-发帖成功后应通过 `social-hub ops complete --permalink ...` 写回任务链路（见 `social-hub-publishing` / `social-hub-ops-runtime`）。
+**维护 CRON / 手动维护**：OpenClaw `reddit-post-reply-maintenance` Step 4.7 在 profile 扫描后应 `batch-upsert` 更新 `score` / `commentsCount` / `viewCount`（曝光）；见 OpenClaw `hub-adapter.md` §5d 与 `references/cron-message-skeleton.md`。

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」就能替代。
 
 ## 安全规则