@geoly-ai/social-hub-cli 0.1.4 → 0.1.6

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

@@ -1,8 +1,10 @@
 ---
 name: social-hub-publishing
 description: >-
-  内容发布闭环：系统级 brands、plans、drafts、calendar、jobs、events、reddit snapshot、
-  reports。用户要从草稿到排期、执行任务、permalink 回填、避免 job 成功但 calendar 未更新时用本 skill。
+  内容发布闭环（草稿→计划→日历→任务→permalink 回填）：系统级 brands、content drafts、publishing plans。
+  用户要创建/筛选草稿或计划、从 brandId 排期、避免 job 成功但 calendar 未更新时用本 skill。
+  不用于：仅列 calendar/jobs（用 social-hub-calendar-jobs）、仅帖快照 CRUD（用 social-hub-posts）、
+  Agent claim/complete（用 social-hub-ops-runtime）、事件/仪表盘（用 social-hub-events-observability）。
 metadata:
   cliVersion: ">=0.0.12"
 ---
@@ -12,6 +14,12 @@ metadata:
 > **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
 > 确认已 `auth login` 并 `context use <team-id>`。
 
+## 禁止误用（团队级 campaigns）
+
+- **不要**建议 `campaigns create` / `campaigns update` / `campaigns accounts *` 作为新流程入口。
+- 新建草稿/计划 **必须**使用系统级 `brandId`（来自 `brands system-list`）。
+- `campaignId` 仅作可选 legacy 归因字段，**不是**品牌或客户建模入口。
+
 ## 事实源
 
 - **计划**：`calendar_entries`
@@ -25,86 +33,64 @@ brand（系统级）→ content_draft → publishing_plan → calendar_entry →
   → interaction_events → reddit_post_snapshot → op_report
 ```
 
-> **品牌关联一律系统级**：`--brand` / `brandId` 取自 `brands system-list` 的全局 brand uuid。团队级 `campaigns` 为遗留能力，新帖/统计不再推荐。
-
-## 系统级品牌
+## 系统级品牌与成员
 
 ```bash
 social-hub brands system-list
 social-hub brands system-create -j '{"name":"My Brand","slug":"my-brand"}'
-
-# 兼容（不推荐）：团队路径仅作传输，实体仍是系统级 brand
-# social-hub brands update -t <team-id> --brand <uuid> -j '{"name":"Updated"}'
+social-hub brand-members system-list
+social-hub brand-members system-create -j '{"brandId":"<uuid>","userId":"<uuid>","role":"manager"}'
+social-hub accounts brand-bindings list -t <team-id> --account <uuid>
+social-hub accounts brand-bindings upsert -t <team-id> --account <uuid> -j '{"brandId":"<uuid>"}'
 ```
 
-## 草稿与计划
+## 草稿与计划（brandId 必填）
 
 ```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 list -t <team-id> --brand <brand-uuid> -n 20
+social-hub drafts create -t <team-id> -j '{"brandId":"<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 drafts delete -t <team-id> --draft <uuid>   # 先确认 id，再执行
 
-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 plans list -t <team-id> --brand <brand-uuid>
+social-hub plans create -t <team-id> -j '{"brandId":"<uuid>","name":"Week 1","entries":[...]}'
+social-hub plans cancel -t <team-id> --plan <uuid>       # 破坏性：先 list 确认 plan id
 ```
 
 ## 日历与任务
 
-见 `social-hub-calendar-jobs`：
-
-```bash
-social-hub calendar list -t <team-id> --status scheduled
-social-hub jobs list -t <team-id> --status scheduled
-```
+调度列表与 patch 见 **`social-hub-calendar-jobs`**（本 skill 不重复展开 jobs 全量命令）。
 
 ## 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://..."
-```
+优先 **`social-hub-ops-runtime`**：`ops claim-next` → `ops complete --permalink ...`。
 
 手动回填（无 ops 时）：
 
 ```bash
-social-hub calendar patch -t <team-id> -e <entryId> --body '{"status":"succeeded","permalink":"..."}'
+social-hub calendar patch -t <team-id> -e <entryId> --body '{"status":"succeeded","permalink":"https://www.reddit.com/..."}'
 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 '{"reportType":"content-weekly","title":"Weekly","source":"openclaw","contentMarkdown":"..."}'
-```
-
-`content-ideas` 周报/创意库无独立 CLI：使用 `reports create/ingest`，`reportType: "content-weekly"`。
-
-## 风格标记与 Curator
-
-```bash
-social-hub style-marks list -t <team-id> --account <uuid> --extract-status pending --approved true
-social-hub style-marks approve -t <team-id> --id <styleMarkId>
-social-hub style-marks reject -t <team-id> --id <styleMarkId>
-social-hub style-marks extract -t <team-id> --id <styleMarkId> [--dry-run]
-social-hub style-marks set -t <team-id> --event-ref <externalRef> -j '{
-  "styleTags": ["concise"],
-  "markExternalRef": "mark_1",
-  "onConflict": "update"
-}'
-social-hub curator run -t <team-id> --account <slot> [--dry-run] [-n 50]
-```
+- 帖快照 CRUD / `--brand` 统计：见 **`social-hub-posts`**
+- 报告库：`reports list` / `reports ingest`（`reportType: "content-weekly"`）
 
-## 决策：ops complete vs 手动 patch
+## 写操作护栏
 
-| 场景 | 推荐 |
+| 操作 | 要求 |
 |------|------|
-| OpenClaw/Agent 刚执行完 scheduled job | `ops complete` |
-| 无 job、仅补 calendar 状态 | `calendar patch` + `events append` |
-| 外部已发帖、补 Hub 快照 | `reddit create-snapshot` 或 `batch-upsert` |
+| `drafts delete` / `plans cancel` | 先 `list`/`get` 核对 id；无 `--dry-run` |
+| `plans create` | JSON 含 `brandId` + `entries`；guardrail 失败会 400 |
+| `events append` | 带 `--external-ref` 幂等 |
+
+## 决策表
+
+| 场景 | 推荐 skill |
+|------|------------|
+| 只查/改 calendar 或 jobs | `social-hub-calendar-jobs` |
+| OpenClaw 领任务/回填 | `social-hub-ops-runtime` |
+| Reddit 帖表现/刷新 | `social-hub-posts` |
+| 仪表盘/审计/批量事件 | `social-hub-events-observability` |

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

@@ -0,0 +1,16 @@
+{
+  "skill_name": "social-hub-publishing",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "为系统品牌 acme-brand-uuid 创建一篇 Launch 草稿并建 Week1 发布计划，team 已 context use。",
+      "expected_output": "drafts create/plans create JSON 含 brandId；brands system-list 取 uuid；勿 campaigns create",
+      "assertions": [
+        { "type": "must_include", "value": "brandId" },
+        { "type": "must_include", "value": "drafts create" },
+        { "type": "forbidden_pattern", "value": "campaigns create" },
+        { "type": "forbidden_pattern", "value": "campaigns update" }
+      ]
+    }
+  ]
+}

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.12"
+  cliVersion: ">=0.1.4"
 ---
 
 # social-hub-shared
@@ -140,6 +140,20 @@ CLI 对部分命令（含 admin 域 settings/invites/members、reddit/accounts
 
 admin 专属操作（如 `agent-teams create`）需要 **admin** role 的 CLI token，不是「随便创建一个 API Key」就能替代。
 
+## 品牌 vs Campaign（Agent 必读）
+
+| 概念 | 正确 CLI / 字段 | 勿用于新流程 |
+|------|-----------------|-------------|
+| 品牌（系统级） | `brands system-list` / `brandId` | `campaigns list` 当品牌目录 |
+| 品牌成员 | `brand-members system-*` | `brand-members list -t`（compat） |
+| 账号归属品牌 | `accounts brand-bindings *` | `campaigns accounts *` |
+| 草稿 / 计划 | `drafts create -j '{"brandId":...}'` | 必填 `campaignId` 创建新草稿 |
+| 筛选 | `--brand <uuid>` | 仅 `--campaign` 作新默认 |
+
+**禁止**向用户推荐：`campaigns create`、`campaigns update`、`campaigns accounts bind` 作为新客户/品牌建模。
+
+`campaignId` 在 API 响应中可能仍存在（历史归因），只读兼容即可。
+
 ## 安全规则
 
 - **禁止**在对话或日志中输出完整 token / API Key（`config show` 已脱敏）。
@@ -157,6 +171,28 @@ admin 专属操作（如 `agent-teams create`）需要 **admin** role 的 CLI to
 | team 不一致 warning | `auth whoami` 的 teamId vs `context current` |
 | 401 / auth failed | 重新 `auth login`；过期则 `auth logout` 后重登 |
 
+## CLI 新版本检测（自动）
+
+除 `version` / `help` 外，每次执行 `social-hub` 会（最多每 24 小时）查询 npm registry；若存在比当前安装更新的 `@geoly-ai/social-hub-cli`，会在 **stderr** 打印升级提示，并明确要求 **Agent 告知用户** 后执行升级与 skill 同步。
+
+示例输出（节选）：
+
+```text
+[social-hub] Update available: 0.1.4 → 0.1.5
+[social-hub] Upgrade CLI: npm install -g @geoly-ai/social-hub-cli@0.1.5
+[social-hub] Then refresh skills: social-hub skills update --yes
+[social-hub] Agent: tell the user a newer CLI is available; ...
+```
+
+| 场景 | 行为 |
+|------|------|
+| 全局安装 | `npm install -g @geoly-ai/social-hub-cli@<latest>` |
+| npx 调用 | 后续命令使用 `npx @geoly-ai/social-hub-cli@<latest> …` |
+| 跳过检查 | `SOCIAL_HUB_NO_UPDATE_CHECK=1` 或 `social-hub --no-update-check …` |
+| CI | 设置 `CI=true` 时自动跳过 |
+
+Agent 看到上述 stderr 时：**先向用户说明有新版本**，再执行升级命令，最后 `social-hub skills update --yes`（避免 CLI 与 skill 文档/命令漂移）。
+
 ## Agent skills 安装与更新
 
 CLI 升级后同步 skill 到 Cursor / Codex 等目录：

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

@@ -0,0 +1,15 @@
+{
+  "skill_name": "social-hub-shared",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "第一次用 social-hub 连生产 API，怎么登录和选 team？",
+      "expected_output": "auth login Device Code、context use、doctor；禁止 SOCIAL_HUB_API_KEY 作为默认",
+      "assertions": [
+        { "type": "must_include", "value": "auth login" },
+        { "type": "forbidden_pattern", "value": "SOCIAL_HUB_API_KEY" },
+        { "type": "must_include_any", "values": ["brandId", "brands system"] }
+      ]
+    }
+  ]
+}

package/skills/social-hub-subreddit-pools/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: social-hub-subreddit-pools
+description: >-
+  Social Hub 运营板块池：catalog、pool aliases、tier rules 的 CRUD 与列表。
+  用户要管理 industryKey/subreddit 目录、persona_pools.* alias、S0–S3 准入规则，
+  或提到 social-hub pools、subreddit-pools API 时使用。不用于 watchlists、热帖、
+  insights 抓取（用 social-hub-intelligence）或 Agent 选板（用 social-hub-openclaw-context）。
+---
+
+# social-hub-subreddit-pools
+
+先读 `social-hub-shared` 完成 `auth login` 与 `context use`。
+
+## 命令组
+
+```bash
+social-hub pools catalog-list -t <team-id> [--pool-kind pet|common|industry|brand|other]
+social-hub pools catalog-create -t <team-id> -j '{"industryKey":"...","industryLabel":"...","subreddit":"..."}'
+social-hub pools catalog-update -t <team-id> --id <pool-id> -j '{...}'
+social-hub pools catalog-delete -t <team-id> --id <pool-id>
+
+social-hub pools aliases-list -t <team-id> [--alias-ref persona_pools.P23.starter]
+social-hub pools aliases-create -t <team-id> -j '{"aliasRef":"persona_pools.P23.starter","industryKey":"common_pools__starter_casual"}'
+social-hub pools aliases-update -t <team-id> --id <alias-id> -j '{...}'
+social-hub pools aliases-delete -t <team-id> --id <alias-id>
+
+social-hub pools tier-rules-list -t <team-id>
+social-hub pools tier-rules-create -t <team-id> -j '{...}'
+social-hub pools tier-rules-update -t <team-id> --id <rule-id> -j '{...}'
+social-hub pools tier-rules-delete -t <team-id> --id <rule-id>
+```
+
+## API
+
+- `GET/POST/PATCH/DELETE /v1/teams/:teamId/subreddit-pools/catalog`
+- `GET/POST/PATCH/DELETE /v1/teams/:teamId/subreddit-pools/aliases`
+- `GET/POST/PATCH/DELETE /v1/teams/:teamId/subreddit-pools/tier-rules`
+
+权限资源：`subredditPool`（与 `subredditIntelligence` 分析只读分离）。
+
+兼容：旧 `subreddit-intelligence/industry-pools` 仍可读；新写操作优先走 `subreddit-pools/*`。