@geoly-ai/social-hub-cli 0.0.1 → 0.0.3

package/dist/version-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-info.d.ts","sourceRoot":"","sources":["../src/version-info.ts"],"names":[],"mappings":"AAaA,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,cAAc;;;;EAM7B"}

package/dist/version-info.js

@@ -0,0 +1,28 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+function readPackageVersion(modulePath) {
+    try {
+        const pkg = require(modulePath);
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function getCliVersion() {
+    return readPackageVersion("../package.json");
+}
+export function getSdkVersion() {
+    return readPackageVersion("@geoly-ai/social-hub-sdk/package.json");
+}
+export function getAuthzVersion() {
+    return readPackageVersion("@geoly-ai/social-hub-authz/package.json");
+}
+export function getVersionInfo() {
+    return {
+        cliVersion: getCliVersion(),
+        sdkVersion: getSdkVersion(),
+        authzVersion: getAuthzVersion(),
+    };
+}
+//# sourceMappingURL=version-info.js.map

package/dist/version-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-info.js","sourceRoot":"","sources":["../src/version-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,SAAS,kBAAkB,CAAC,UAAkB;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAyB,CAAC;QACxD,OAAO,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,kBAAkB,CAAC,uCAAuC,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,kBAAkB,CAAC,yCAAyC,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,UAAU,EAAE,aAAa,EAAE;QAC3B,UAAU,EAAE,aAAa,EAAE;QAC3B,YAAY,EAAE,eAAe,EAAE;KAChC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/social-hub-cli",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "description": "social-hub CLI for Social Ops Hub",
   "repository": {
@@ -12,15 +12,16 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "bin": {
     "social-hub": "./dist/index.js"
   },
   "dependencies": {
     "commander": "^12.1.0",
-    "@geoly-ai/social-hub-authz": "0.0.1",
-    "@geoly-ai/social-hub-sdk": "0.0.1"
+    "@geoly-ai/social-hub-authz": "0.0.3",
+    "@geoly-ai/social-hub-sdk": "0.0.3"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
@@ -28,7 +29,8 @@
     "vitest": "^2.1.8"
   },
   "scripts": {
-    "build": "tsc",
+    "copy-skills": "node ../../scripts/copy-skills-to-cli.mjs",
+    "build": "pnpm run copy-skills && tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }

package/skills/README.md

@@ -0,0 +1,89 @@
+# Social Hub Agent Skills
+
+本目录与 `@geoly-ai/social-hub-cli`、SDK、`@social-ops-hub/contracts` 同仓发布。Agent 通过 **`social-hub` CLI** 读写 Hub；Skill 只描述何时用哪条命令、权限与流程。
+
+## 安装 Agent Skills（推荐 CLI）
+
+Skills 随 `@geoly-ai/social-hub-cli` 一起发布（npm tarball 内置 `skills/`）。
+
+```bash
+# 交互式（选 agent、skill、install/update）
+social-hub skills tui
+
+# 或脚本化
+social-hub skills install --agent cursor --global --yes
+social-hub skills install --agent claude-code --project --yes
+social-hub skills install --agent codex --global --all --yes
+
+# 更新到当前 CLI 内置版本
+social-hub skills update --all --yes
+
+# 健康检查
+social-hub skills doctor --json
+
+# 无需全局安装
+npx @geoly-ai/social-hub-cli skills bootstrap
+pnpm dlx @geoly-ai/social-hub-cli skills list
+```
+
+支持 [skill.sh](https://skill.sh) 兼容的全部 agent（`social-hub skills list --agents`）。安装状态记录在目标目录下的 `.social-hub-skills.json`。
+
+## 发布到 skill 市场（skill.sh / Agent Skill Hub）
+
+1. 将本仓库推送到 GitHub（`skills/` 保持在仓库内）。
+2. 在 [skill.sh](https://skill.sh) 或 Agent Skill Hub 添加仓库 URL，选择要导入的 skill 目录（如 `skills/social-hub-cli`）。
+3. 用户安装示例（以市场 CLI 为准，名称可能为 `skill`、`skhub` 等）：
+
+```bash
+# 示例：从 registry 安装（具体命令以 skill.sh 文档为准）
+skill add <org>/social-ops-hub/social-hub-cli
+skill add <org>/social-ops-hub/social-hub-ops-runtime
+```
+
+每个 skill 为独立目录，内含 `SKILL.md`（YAML frontmatter 含 `name`、`description`）。
+
+## 本地开发安装（任意 IDE）
+
+| 方式 | 说明 |
+|------|------|
+| **CLI（推荐）** | `social-hub skills install --agent cursor` 或 `social-hub skills tui` |
+| **npx** | `npx @geoly-ai/social-hub-cli skills bootstrap` |
+| **项目内脚本** | `pnpm skills:install` → 默认 `.agents/skills/` |
+| **指定目录** | `SKILLS_INSTALL_DIR=~/.cursor/skills pnpm skills:install` |
+| **符号链接** | `social-hub skills install --symlink --dir <path>` |
+
+```bash
+# 默认：复制到 social-ops-hub/.agents/skills/
+pnpm skills:install
+
+# 安装到自定义目录（Cursor / Codex / Claude Code / 其他）
+SKILLS_INSTALL_DIR="$HOME/.config/your-agent/skills" pnpm skills:install
+
+# 校验 frontmatter 与 manifest
+pnpm skills:check
+```
+
+安装后**重启或重新加载**当前 IDE/Agent 的 skill 列表（各产品入口不同）。
+
+## Skill 列表
+
+| Skill | 用途 |
+|-------|------|
+| [social-hub-cli](social-hub-cli) | 总路由 + 命令速查 |
+| [social-hub-shared](social-hub-shared) | config、auth、doctor、context |
+| [social-hub-ops-runtime](social-hub-ops-runtime) | claim / complete / fail |
+| [social-hub-openclaw-context](social-hub-openclaw-context) | DB 聚合上下文 |
+| [social-hub-accounts](social-hub-accounts) | 账号 |
+| [social-hub-posts](social-hub-posts) | Reddit 帖 |
+| [social-hub-calendar-jobs](social-hub-calendar-jobs) | 日历与任务 |
+| [social-hub-publishing](social-hub-publishing) | 发布闭环 |
+| [social-hub-admin](social-hub-admin) | 系统/团队管理 |
+| [social-hub-intelligence](social-hub-intelligence) | 板块情报 |
+| [social-hub-migration](social-hub-migration) | 导入导出与 replay |
+
+清单见 [manifest.json](manifest.json)。与 API/CLI 对齐情况见仓库 `docs/cli-api-coverage.md`。
+
+## 版本
+
+- CLI / SDK / contracts 与 skills 使用同一 git tag 发布。
+- 各 `SKILL.md` 的 `metadata` 可声明 `cliVersion: ">=0.0.1"`（见 frontmatter）。

package/skills/manifest.json

@@ -0,0 +1,68 @@
+{
+  "version": 1,
+  "package": "social-ops-hub",
+  "cliVersion": "0.0.3",
+  "repository": "social-ops-hub",
+  "publish": {
+    "registry": "https://skill.sh",
+    "layout": "skills/<skill-id>/SKILL.md",
+    "note": "Import this GitHub repo on skill.sh; select skill subdirectories under skills/"
+  },
+  "skills": [
+    {
+      "id": "social-hub-cli",
+      "path": "social-hub-cli",
+      "description": "总路由：Hub CLI 触发词与领域 Skill 索引"
+    },
+    {
+      "id": "social-hub-shared",
+      "path": "social-hub-shared",
+      "description": "config、auth、doctor、permissions、context"
+    },
+    {
+      "id": "social-hub-ops-runtime",
+      "path": "social-hub-ops-runtime",
+      "description": "OpenClaw 任务 claim、heartbeat、complete、fail、skip"
+    },
+    {
+      "id": "social-hub-openclaw-context",
+      "path": "social-hub-openclaw-context",
+      "description": "DB-first 账号/任务上下文与板块候选"
+    },
+    {
+      "id": "social-hub-accounts",
+      "path": "social-hub-accounts",
+      "description": "账号 CRUD、品牌绑定、状态快照"
+    },
+    {
+      "id": "social-hub-posts",
+      "path": "social-hub-posts",
+      "description": "Reddit 帖快照、刷新、统计"
+    },
+    {
+      "id": "social-hub-calendar-jobs",
+      "path": "social-hub-calendar-jobs",
+      "description": "日历、调度任务、retry/cancel"
+    },
+    {
+      "id": "social-hub-publishing",
+      "path": "social-hub-publishing",
+      "description": "campaign 到 report 发布闭环"
+    },
+    {
+      "id": "social-hub-admin",
+      "path": "social-hub-admin",
+      "description": "settings、invites、members、api-keys"
+    },
+    {
+      "id": "social-hub-intelligence",
+      "path": "social-hub-intelligence",
+      "description": "板块情报 watchlists、hot posts、industry pools"
+    },
+    {
+      "id": "social-hub-migration",
+      "path": "social-hub-migration",
+      "description": "JSONL 导入导出、runbook replay"
+    }
+  ]
+}

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

@@ -0,0 +1,25 @@
+---
+name: social-hub-accounts
+description: >-
+  Social Hub 社交账号：social-hub accounts list/get/create/update/delete、brand-bindings、status-snapshots。
+  用户要查 Reddit 账号、改 handle、绑品牌、看账号状态快照、同步飞书账号字段时用本 skill。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-accounts
+
+```bash
+social-hub accounts list -t "$T" -n 50
+social-hub accounts get -t "$T" --id "<uuid>"
+social-hub accounts update -t "$T" --id "<uuid>" -j '{"workflowStage":"active",...}'
+social-hub accounts delete -t "$T" --id "<uuid>"    # 危险：需确认
+
+social-hub accounts brand-bindings list -t "$T" --account "<uuid>"
+social-hub accounts brand-bindings add -t "$T" --account "<uuid>" -j '{"brandId":"..."}'
+social-hub accounts brand-bindings remove -t "$T" --account "<uuid>" --brand "<brandId>"
+
+social-hub accounts status-snapshots list -t "$T" --account "<uuid>"
+```
+
+OpenClaw 执行前优先 `social-hub context account`（见 `social-hub-openclaw-context`），不要只读本地 `account-profiles/*.md`。

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

@@ -0,0 +1,36 @@
+---
+name: social-hub-admin
+description: >-
+  Social Hub 管理面：settings、invites、members、api-keys、agent-teams、users。
+  用户要改系统设置、发团队邀请、列成员、轮换 API Key 时用本 skill；高风险写操作需 --apply。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-admin
+
+## Settings（admin）
+
+```bash
+social-hub settings list
+social-hub settings get <key>
+social-hub settings set <key> --value "..." --dry-run
+social-hub settings set <key> --value "..." --apply
+```
+
+## Invites
+
+```bash
+social-hub invites list -t "$T"
+social-hub invites create -t "$T" --email user@example.com --role manager --dry-run
+social-hub invites create -t "$T" --email user@example.com --role manager --apply
+social-hub invites revoke -t "$T" --id "<inviteId>" --apply
+```
+
+## Members
+
+```bash
+social-hub members list
+```
+
+API Keys、users、agent-teams 等见 `social-hub-cli` 管理章节。

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

@@ -0,0 +1,25 @@
+---
+name: social-hub-calendar-jobs
+description: >-
+  发布日历与调度任务：social-hub calendar list、jobs list/create/batch/retry/cancel。
+  用户要排期、查 scheduled job、重试失败任务、取消任务时用本 skill；Agent 执行态回填优先 ops-runtime。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-calendar-jobs
+
+```bash
+social-hub calendar list -t "$T"
+social-hub jobs list -t "$T" --status scheduled
+social-hub jobs create -t "$T" -j '{"socialAccountId":"...","subreddit":"...","runAt":"..."}'
+social-hub jobs retry -t "$T" --job "<id>"
+social-hub jobs cancel -t "$T" --job "<id>"
+```
+
+遗留：`jobs agent-status` 仍可更新状态，但 OpenClaw 推荐：
+
+```bash
+social-hub ops claim-next -t "$T" --agent "<agentId>"
+social-hub ops complete|fail|skip ...
+```

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

@@ -0,0 +1,362 @@
+---
+name: social-hub-cli
+description: >-
+  Social Ops Hub 命令行 social-hub：账号、事件、日历、调度任务、Reddit 帖、报告、API Key、OpenClaw 回填等。
+  只要用户提到 social-hub、Social Ops Hub、Hub 写数据、查账号、发帖计划、permalink 回填、openclaw、
+  调度任务、团队 API Key、互动事件，或要在 Hub 里查/改运营数据，就应使用本 skill（即使用户没说 CLI）。
+  先读本 skill 做路由，再打开对应领域 skill（ops-runtime、openclaw-context 等）。
+metadata:
+  cliVersion: ">=0.0.3"
+  homepage: https://github.com/your-org/social-ops-hub/tree/main/skills
+---
+
+# Social Hub CLI
+
+`social-hub` 封装 Social Ops Hub REST API，供人工与 Agent 使用。配套领域 skill 与本目录同级（`skills/social-hub-*`）。
+
+## 安装 Skill
+
+- **推荐（CLI）**：`social-hub skills tui` 或 `social-hub skills install --agent cursor --global --yes`
+- **免全局安装**：`npx @geoly-ai/social-hub-cli skills bootstrap`
+- **更新已装 skill**：`social-hub skills update --all --yes`
+- **检查状态**：`social-hub skills doctor`
+- **同仓开发**：`pnpm skills:install`（或 `pnpm --filter @geoly-ai/social-hub-cli run build` 后使用内置 bundle）
+- **skill.sh / 公开市场**：从 [skill.sh](https://skill.sh) 导入本仓库 `skills/` 子目录（见 `skills/README.md`）
+
+## 领域 Skill 路由（先读子 skill）
+
+| 场景 | Skill |
+|------|--------|
+| 配置 / doctor / auth | `social-hub-shared` |
+| OpenClaw 领任务 / 回填 | `social-hub-ops-runtime` |
+| 账号/任务上下文（DB） | `social-hub-openclaw-context` |
+| 账号 CRUD | `social-hub-accounts` |
+| Reddit 帖 | `social-hub-posts` |
+| 日历 / jobs | `social-hub-calendar-jobs` |
+| 发布闭环 | `social-hub-publishing` |
+| settings / invites | `social-hub-admin` |
+| 情报 | `social-hub-intelligence` |
+| 导入导出 replay | `social-hub-migration` |
+
+`social-hub` 是 Social Ops Hub 的命令行工具，封装了全部 REST API。
+
+## 配置（环境变量）
+
+使用前需设置以下环境变量：
+
+```bash
+export SOCIAL_HUB_API_URL="http://localhost:3000"   # Hub API 地址，默认 localhost:3000
+export SOCIAL_HUB_API_KEY="soh_..."                 # API Key（除 health 外均必需）
+export SOCIAL_HUB_TEAM_ID="<uuid>"                  # 当前操作的 Team UUID（命令中用 $SOCIAL_HUB_TEAM_ID）
+```
+
+`health` 命令不需要 API Key。其他所有命令必须设置 `SOCIAL_HUB_API_KEY`。
+
+## 前置步骤：Build
+
+在 **本 monorepo 根目录** 首次使用或更新代码后，需先 build：
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+pnpm --filter @geoly-ai/social-hub-sdk run build
+pnpm --filter @geoly-ai/social-hub-cli run build
+```
+
+---
+
+## 初始化工作流（新环境冷启动）
+
+### 步骤 0：部署前置
+
+```bash
+# 1. 复制并填写环境变量
+cp .env.example .env
+# 至少填写：DATABASE_URL、REDIS_URL、API_KEY_PEPPER、JWT_SECRET
+
+# 2. 执行数据库迁移
+pnpm run db:migrate
+
+# 3. 初始化最小管理员种子（自动创建 moss team + admin 用户 + seed-cli API Key）
+SOCIAL_OPS_SEED_MODE=minimal-admin pnpm run db:seed
+# 控制台输出：
+#   admin@local.test / password123
+#   SOCIAL_HUB_TEAM_ID=<uuid>
+#   SOCIAL_HUB_API_KEY=soh_...
+
+# 4. 导出环境变量（或写入 .env）
+export SOCIAL_HUB_API_URL="http://localhost:3000"
+export SOCIAL_HUB_API_KEY="soh_..."          # 从上面控制台复制
+export SOCIAL_HUB_TEAM_ID="<moss-team-uuid>"  # 从上面控制台复制
+
+# 5. 验证 Hub 是否正常
+social-hub health
+```
+
+### 步骤 1：创建新团队（若需要独立 team）
+
+```bash
+# 使用 admin API Key 创建新团队
+NEW_TEAM=$(social-hub agent-teams create --slug javis --name "Javis Agent Team" | jq -r '.id')
+export T=$NEW_TEAM
+
+# 创建运营用户（密码直接设置，不需要 set-password 额外操作）
+social-hub users create -t $T -j '{"email":"ops@javis.local","password":"Ops2026!","name":"Javis Ops","role":"manager"}'
+
+# 为新团队创建 API Key（Web 登录后进入 API Keys 页面，或用 admin key）
+social-hub api-keys create -t $T -j '{"name":"javis-ops","role":"manager"}'
+# → 记录返回的 rawKey，后续操作换用该 Key
+
+export SOCIAL_HUB_TEAM_ID=$T
+export SOCIAL_HUB_API_KEY="soh_..."  # 上面新建的 Key
+
+# 确认团队列表
+social-hub agent-teams list
+```
+
+### 步骤 2：创建业务数据（Brand → Campaign → Account → Plan）
+
+```bash
+T=$SOCIAL_HUB_TEAM_ID
+
+# 创建品牌
+BRAND_ID=$(social-hub brands create -t $T -j '{"name":"My Brand","slug":"my-brand"}' | jq -r '.id')
+
+# 创建 Campaign
+CAMP_ID=$(social-hub campaigns create -t $T -j \
+  "{\"brandId\":\"$BRAND_ID\",\"name\":\"2026 Q3 Launch\"}" | jq -r '.id')
+
+# 添加 Reddit 账号
+ACCOUNT_ID=$(social-hub accounts create -t $T -j \
+  "{\"platform\":\"reddit\",\"handle\":\"u/my_ops_account\",\"credentialsRef\":\"vault:javis/main\"}" | jq -r '.id')
+
+# 创建内容草稿
+DRAFT_ID=$(social-hub drafts create -t $T -j \
+  "{\"campaignId\":\"$CAMP_ID\",\"title\":\"Launch Post\",\"body\":\"...\"}" | jq -r '.id')
+
+# 创建发布计划（自动生成 scheduled_jobs）
+social-hub plans create -t $T -j "{
+  \"campaignId\": \"$CAMP_ID\",
+  \"name\": \"Q3 Week 1\",
+  \"entries\": [{
+    \"socialAccountId\": \"$ACCOUNT_ID\",
+    \"subreddit\": \"LocalLLaMA\",
+    \"plannedAt\": \"2026-07-01T09:00:00Z\",
+    \"contentDraftId\": \"$DRAFT_ID\"
+  }]
+}"
+
+# 验证：查看日历和任务
+social-hub calendar list -t $T --status scheduled
+social-hub jobs list -t $T --status scheduled
+```
+
+---
+
+## 命令速查表
+
+### health & dashboard
+
+```bash
+social-hub health
+social-hub dashboard summary -t $T
+social-hub dashboard summary -t $T  # 支持 campaignId 过滤（通过 API 传参）
+```
+
+### 互动事件
+
+```bash
+social-hub events append -t $T --type comment --payload '{"permalink":"https://..."}'
+social-hub events list -t $T -n 20                   # 简单列表
+social-hub events list-full -t $T --account <uuid>   # 按账号过滤
+social-hub events list-full -t $T --type comment --result succeeded --from 2026-05-01T00:00:00Z
+social-hub events export-csv -t $T > events.csv
+social-hub events export-csv -t $T --account <uuid> --from 2026-05-01T00:00:00Z > filtered.csv
+```
+
+### 发布日历
+
+```bash
+social-hub calendar list -t $T --status scheduled
+social-hub calendar list-full -t $T --account <accountId> --status scheduled
+social-hub calendar patch -t $T -e <entryId> --body '{"status":"succeeded","permalink":"https://..."}'
+```
+
+### 调度任务
+
+```bash
+social-hub jobs list -t $T --status scheduled
+social-hub jobs list-full -t $T --account <accountId>
+social-hub jobs create -t $T -j '{"socialAccountId":"<uuid>","action":"engage","subreddit":"LocalLLaMA","runAt":"2026-05-07T09:00:00Z"}'
+social-hub jobs agent-status -t $T -i <jobId> -j '{"status":"succeeded"}'
+social-hub jobs agent-status -t $T -i <jobId> -j '{"status":"failed","lastError":"timeout"}'
+social-hub jobs retry -t $T -i <jobId>
+social-hub jobs cancel -t $T -i <jobId>
+```
+
+### 发布计划
+
+```bash
+social-hub plans list -t $T
+social-hub plans list -t $T --campaign <campaignId>
+social-hub plans create -t $T -j '{"campaignId":"<uuid>","name":"Q3 Week1","entries":[{"socialAccountId":"<uuid>","subreddit":"LocalLLaMA","plannedAt":"2026-07-01T09:00:00Z"}]}'
+social-hub plans cancel -t $T --plan <planId>
+```
+
+### 内容草稿
+
+```bash
+social-hub drafts list -t $T -n 20
+social-hub drafts create -t $T -j '{"campaignId":"<uuid>","title":"Test Post","body":"Content..."}'
+social-hub drafts get -t $T --draft <uuid>
+social-hub drafts update -t $T --draft <uuid> -j '{"status":"approved"}'
+social-hub drafts delete -t $T --draft <uuid>
+```
+
+### 报告库
+
+```bash
+social-hub reports list -t $T -n 20
+social-hub reports create -t $T -j '{"reportType":"campaign-digest","title":"5月报告","source":"manual","contentMarkdown":"# 报告..."}'
+social-hub reports ingest -t $T -j '{"reportType":"reddit-post-snapshot","source":"path/to/file.md"}'
+```
+
+### 账号管理
+
+```bash
+social-hub accounts list -t $T
+social-hub accounts list -t $T --status active
+social-hub accounts get -t $T --account <uuid>
+social-hub accounts create -t $T -j '{"platform":"reddit","handle":"u_example","externalId":"..."}'
+social-hub compliance risk-get -t $T -a <accountId>
+social-hub compliance risk-put -t $T -a <accountId> -j '{"riskLevel":"medium","notes":"..."}'
+```
+
+### 品牌与 Campaign
+
+```bash
+social-hub brands list -t $T
+social-hub brands create -t $T -j '{"name":"My Brand","slug":"my-brand"}'
+social-hub brands update -t $T --brand <brandId> -j '{"name":"New Name"}'
+social-hub campaigns list -t $T --brand <brandId>
+social-hub campaigns get -t $T --campaign <uuid>
+social-hub campaigns create -t $T -j '{"brandId":"<uuid>","name":"2026 Q2"}'
+social-hub campaigns update -t $T --campaign <uuid> -j '{"name":"2026 Q3"}'
+```
+
+### 板块情报
+
+```bash
+social-hub intelligence hot-posts -t $T --subreddit LocalLLaMA
+social-hub intelligence hot-posts -t $T --sort score -n 50
+social-hub intelligence dispatch -t $T -j '{"hotPostId":"<uuid>","socialAccountId":"<uuid>","action":"engage"}'
+social-hub intelligence kol-intents -t $T -n 20
+social-hub intelligence watchlists-list -t $T
+```
+
+### 团队与用户管理
+
+```bash
+social-hub agent-teams list
+social-hub agent-teams create --slug moss --name "Moss Agent Team"          # admin only
+social-hub agent-teams add-member -t $T --user <userId> --role manager      # admin only
+social-hub users list -t $T
+social-hub users create -t $T -j '{"email":"agent@example.com","password":"xxx","role":"manager"}'
+```
+
+### 通知渠道
+
+```bash
+social-hub notification-channels list -t $T
+social-hub notification-channels create -t $T -j '{"provider":"feishu","externalId":"https://open.feishu.cn/open-apis/bot/v2/hook/..."}'
+social-hub notification-channels test -t $T --channel <uuid>
+social-hub notification-channels delete -t $T --channel <uuid>
+```
+
+### API Key 管理
+
+```bash
+social-hub api-keys list -t $T
+social-hub api-keys create -t $T -j '{"name":"agent-key","role":"manager"}'
+social-hub api-keys rotate -t $T --key <uuid>
+social-hub api-keys delete -t $T --key <uuid>
+```
+
+---
+
+## 典型工作流
+
+### 工作流 1：Agent 执行完成后回填 Hub
+
+```bash
+T=$SOCIAL_HUB_TEAM_ID
+ENTRY_ID="<calendarEntryId>"
+PERMALINK="https://www.reddit.com/r/LocalLLaMA/comments/xxx/yyy/"
+
+# 1. 更新日历条目状态为 succeeded
+social-hub calendar patch -t $T -e $ENTRY_ID \
+  --body "{\"status\":\"succeeded\",\"permalink\":\"$PERMALINK\"}"
+
+# 2. 写入互动事件
+social-hub events append -t $T \
+  --type "post.published" \
+  --payload "{\"permalink\":\"$PERMALINK\",\"calendarEntryId\":\"$ENTRY_ID\"}"
+
+# 3. 查看该账号近期事件（验证写入）
+social-hub events list-full -t $T --account $ACCOUNT_ID -n 10
+```
+
+### 工作流 2：查看账号运营数据
+
+```bash
+T=$SOCIAL_HUB_TEAM_ID
+ACCOUNT_ID="<socialAccountId>"
+
+# 账号详情
+social-hub accounts get -t $T --account $ACCOUNT_ID
+
+# 近期事件
+social-hub events list-full -t $T --account $ACCOUNT_ID -n 20
+
+# 近期调度任务
+social-hub jobs list-full -t $T --account $ACCOUNT_ID --status scheduled
+
+# 关联发布日历
+social-hub calendar list-full -t $T --account $ACCOUNT_ID --status scheduled
+
+# 风险档案
+social-hub compliance risk-get -t $T -a $ACCOUNT_ID
+```
+
+### 工作流 3：情报热帖派发任务
+
+```bash
+T=$SOCIAL_HUB_TEAM_ID
+
+# 1. 查看热帖
+social-hub intelligence hot-posts -t $T --sort score -n 10
+
+# 2. 查看可用账号
+social-hub accounts list -t $T --status active
+
+# 3. 派发互动任务
+social-hub intelligence dispatch -t $T -j '{
+  "hotPostId": "<hotPostId>",
+  "socialAccountId": "<accountId>",
+  "action": "engage",
+  "runAt": "2026-05-07T09:00:00Z"
+}'
+
+# 4. 确认任务已创建
+social-hub jobs list -t $T --status scheduled -n 5
+```
+
+---
+
+## 注意事项
+
+- 所有命令输出均为 **JSON**，可管道传给 `jq` 处理：`social-hub accounts list -t $T | jq '.items[].handle'`
+- `DELETE` 端点（drafts delete、plans cancel、notification-channels delete）返回空响应（204），成功时打印 `OK`
+- `events export-csv` 和 `intelligence hot-posts-export` 输出 CSV 到 stdout，可直接重定向：`> output.csv`
+- 团队管理操作（`agent-teams create/update/add-member`）需要 **admin** 角色的 API Key
+- Session（Cookie）认证不在 CLI 支持范围内，始终使用 API Key
+