@geoly-ai/social-hub-cli 0.0.2 → 0.0.4

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

@@ -0,0 +1,363 @@
+---
+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.4"
+  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`
+- **GitHub 最新**：`social-hub skills install --source github --repo geoly-ai/geoly-reddit --yes`
+- **更新已装 skill**：`social-hub skills update --all --yes`（可加 `--source github`）
+- **检查状态**：`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
+

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

@@ -0,0 +1,23 @@
+{
+  "skill_name": "social-hub-cli",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "我刚在本地部署好了 Social Ops Hub，openclaw-template 也初始化完了。我需要在 Hub 里注册一个新团队叫 javis，slug 也是 javis，然后给这个团队添加一个管理员用户，email 是 ops@javis.local，密码是 Javis2026!。完成后确认一下团队列表里有了这个团队。",
+      "expected_output": "使用 social-hub-cli skill，依次执行：social-hub agent-teams create、social-hub users create -t <newTeamId>、social-hub agent-teams list，输出各步骤的命令和 JSON 结果",
+      "assertions": []
+    },
+    {
+      "id": 1,
+      "prompt": "我的 Reddit 账号 u/example_user（id 是 abc123-...-uuid）刚刚在 r/LocalLLaMA 发了一个帖子，permalink 是 https://www.reddit.com/r/LocalLLaMA/comments/abc123/test_post/。对应的发布日历条目 id 是 def456-...-uuid。帮我把这个结果写进 Social Ops Hub：把日历条目标记为 succeeded，写入 permalink，同时记录一条 post.published 事件。最后查一下这个账号最近的互动事件确认写入成功。",
+      "expected_output": "执行 calendar patch（succeeded + permalink）、events append（post.published）、events list-full --account，输出每步的命令和结果",
+      "assertions": []
+    },
+    {
+      "id": 2,
+      "prompt": "帮我查一下 Social Ops Hub 里板块情报里 r/Entrepreneur 最近按分数排名的前 5 条热帖，然后选第一条，派发一个 engage 互动任务给账号 ghi789-...-uuid，运行时间设为明天上午 9 点（2026-05-07T01:00:00Z UTC）。任务派发完后确认一下调度任务列表里有这条新任务。",
+      "expected_output": "执行 intelligence hot-posts --subreddit Entrepreneur --sort score -n 5、intelligence dispatch（带 hotPostId/socialAccountId/action/runAt）、jobs list 确认，输出各步命令和结果",
+      "assertions": []
+    }
+  ]
+}

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

@@ -0,0 +1,25 @@
+---
+name: social-hub-intelligence
+description: >-
+  板块情报：watchlists、hot posts、KOL intents、industry-pools、dispatch 等 social-hub intelligence 子命令。
+  用户要盯 subreddit、拉热帖、行业池、情报派发时用本 skill。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-intelligence
+
+```bash
+social-hub intelligence industry-pools-list -t "$T"
+social-hub intelligence watchlists-list -t "$T"
+social-hub intelligence hot-posts -t "$T" --subreddit technology
+social-hub intelligence dispatch -t "$T" -j '{ ... }'   # 写操作注意 --apply
+```
+
+账号可发帖板块优先用：
+
+```bash
+social-hub query account-pools -t "$T" --account <ref>
+```
+
+WebSocket `runs/ws` 为 watch 能力，不适合普通 CLI 批处理。

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

@@ -0,0 +1,32 @@
+---
+name: social-hub-migration
+description: >-
+  Hub 数据批量：export events-jsonl、export agent-context、runbook replay、openclaw-ingest。
+  用户要导出 JSONL、回放事件、迁移/对账时用本 skill；不包含工作区 shared 目录批量 sync（需人工决策）。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-migration
+
+## 导出
+
+```bash
+social-hub export events-jsonl -t "$T" -o events.jsonl -n 500
+social-hub export agent-context -t "$T" --account "<uuid>" -o ctx.json
+```
+
+## Runbook 回放
+
+```bash
+social-hub runbook replay -t "$T" -f events.jsonl --dry-run
+social-hub runbook replay -t "$T" -f events.jsonl          # 实际 append events
+```
+
+JSONL 每行：`{"type":"comment","payload":{...}}`
+
+## openclaw-ingest
+
+API 支持将工作区文档写入 `team_workspace_documents`；**不要**在本 skill 内自动化批量 sync 整个 `Javis-workspace/shared` 或 `Moss-workspace/shared`，除非用户明确要求并指定范围。
+
+运行时查询请用 `social-hub-openclaw-context`，不是解析 Markdown。

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

@@ -0,0 +1,45 @@
+---
+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。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-openclaw-context
+
+## 账号上下文
+
+```bash
+social-hub context account -t "$T" --account A1 \
+  --expand pools,jobs,persona,risk,env,guardrails
+```
+
+`--account` 可为 UUID 或 handle（如 `A1`）。
+
+## 任务上下文
+
+```bash
+social-hub context job -t "$T" --job "<scheduledJobId>"
+```
+
+## 板块与候选
+
+```bash
+social-hub query account-pools -t "$T" --account A1 --limit 50
+social-hub query subreddit-candidates -t "$T" --account A1 --action publish_post
+```
+
+## 导出（给人看或离线审计）
+
+```bash
+social-hub export agent-context -t "$T" --account "<uuid>" -o /tmp/ctx.json
+```
+
+## freshness
+
+响应中的 `freshness.needsRefresh === true` 时，应先刷新账号指标或情报，再执行发帖/评论。
+
+执行任务前配合 `social-hub-ops-runtime`；执行后 `ops complete` 回填 permalink。

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

@@ -0,0 +1,40 @@
+---
+name: social-hub-ops-runtime
+description: >-
+  OpenClaw / Agent 任务运行时：social-hub ops claim-next、claim、heartbeat、complete、fail、skip。
+  用户要领任务、续租、心跳、回填 permalink、任务失败/跳过、避免改本地 Markdown 状态时必须用本 skill。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-ops-runtime
+
+Hub DB 是执行状态的真源；不要用 `shared/reddit-account-status.md` 等文件记录任务结果。
+
+## 推荐流程
+
+```bash
+export T="$SOCIAL_HUB_TEAM_ID"
+export AGENT="javis"   # 或 moss / 你的 agentId
+
+social-hub ops claim-next -t "$T" --agent "$AGENT"
+social-hub context job -t "$T" --job "<jobId>"
+social-hub ops heartbeat -t "$T" --job "<jobId>" --agent "$AGENT"
+# 执行 Reddit / 浏览器操作，并写 interaction events（见 social-hub-cli events）
+social-hub ops complete -t "$T" --job "<jobId>" --agent "$AGENT" --permalink "https://reddit.com/..."
+```
+
+失败或跳过：
+
+```bash
+social-hub ops fail -t "$T" --job "<jobId>" --agent "$AGENT" --reason rule_blocked --message "..."
+social-hub ops skip -t "$T" --job "<jobId>" --agent "$AGENT" --reason manual_intervention_required
+```
+
+## `--reason` 枚举（仅允许下列值）
+
+`ip_drift`, `env_start_timeout`, `login_expired`, `wrong_account_logged_in`, `reddit_connection_failed`, `rte_failed`, `subreddit_banned`, `bot_bouncer_blocked`, `rule_blocked`, `manual_intervention_required`, `unknown`
+
+## 并发
+
+同一账号同时只能有一个有效 lease；重复 claim 会被拒绝。`complete` 会原子更新 job 与关联 calendar（若 payload 含 calendarEntryId）。

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

@@ -0,0 +1,20 @@
+---
+name: social-hub-posts
+description: >-
+  Reddit 帖快照与数据：social-hub reddit list/stats/refresh/refresh-all/import-feishu 等。
+  用户要查帖表现、刷新 score、导入飞书表、permalink 对应快照时用本 skill（命令组名为 reddit）。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-posts
+
+```bash
+social-hub reddit list -t "$T" -n 20
+social-hub reddit stats -t "$T" --campaign "<uuid>"
+social-hub reddit refresh-status -t "$T" --id "<snapshotId>"
+social-hub reddit refresh-all -t "$T"
+social-hub reddit import-feishu -t "$T" -j '{ ... }'
+```
+
+发帖成功后应通过 `social-hub ops complete --permalink ...` 写回任务链路（见 `social-hub-publishing`）。

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

@@ -0,0 +1,31 @@
+---
+name: social-hub-publishing
+description: >-
+  内容发布闭环：campaign → plan → draft → calendar → scheduled_job → events → reddit snapshot → report。
+  用户要从草稿到排期、执行任务、permalink 回填、避免 job 成功但 calendar 未更新时用本 skill。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-publishing
+
+## 事实源
+
+- **计划**：`calendar_entries`
+- **执行**：`scheduled_jobs`
+- 本地 Markdown 日历仅作导入/导出视图，不是运行时真源
+
+## 链路
+
+```
+campaign → publishing_plan → content_draft → calendar_entry → scheduled_job
+  → interaction_events → reddit_post_snapshot → op_report
+```
+
+## Agent 推荐
+
+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）
+
+失败时 `ops fail` / `ops skip`，并写标准 `reason` 枚举。

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

@@ -0,0 +1,41 @@
+---
+name: social-hub-shared
+description: >-
+  social-hub 基础能力：config init/show、auth login、doctor、version、permissions、context list/use/current。
+  在跑任何 Hub 写操作前应先 doctor 或 auth；配置报错、连不上 API、team 不对、权限不足时优先用本 skill。
+metadata:
+  cliVersion: ">=0.0.1"
+---
+
+# social-hub-shared
+
+## 环境变量
+
+```bash
+export SOCIAL_HUB_API_URL="http://localhost:3000"
+export SOCIAL_HUB_API_KEY="soh_..."
+export SOCIAL_HUB_TEAM_ID="<team-uuid>"   # 或用 context use 持久化
+```
+
+## 常用命令
+
+```bash
+social-hub config init --api-url http://localhost:3000 --team $T
+social-hub auth login --api-key "$SOCIAL_HUB_API_KEY"
+social-hub auth whoami
+social-hub doctor
+social-hub version --json
+social-hub context use "$T"
+social-hub context current
+social-hub permissions matrix
+social-hub auth explain
+```
+
+## 排障顺序
+
+1. `social-hub health`（无需 Key）
+2. `social-hub doctor`（含 `/health/live` 与 auth context）
+3. 确认 `SOCIAL_HUB_TEAM_ID` 与 API Key 绑定 team 一致
+4. `social-hub auth explain` 查看当前角色允许的命令
+
+更完整命令表见同包的 `social-hub-cli` skill。