@geoly-ai/social-hub-cli 0.0.6 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/social-hub-cli",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "type": "module",
   "description": "social-hub CLI for Social Ops Hub",
   "repository": {

package/skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "package": "social-ops-hub",
-  "cliVersion": "0.0.4",
+  "cliVersion": "0.0.6",
   "repository": "social-ops-hub",
   "publish": {
     "registry": "https://skill.sh",

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

@@ -4,22 +4,27 @@ description: >-
   Social Hub 社交账号：social-hub accounts list/get/create/update/delete、brand-bindings、status-snapshots。
   用户要查 Reddit 账号、改 handle、绑品牌、看账号状态快照、同步飞书账号字段时用本 skill。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-accounts
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已通过 `social-hub auth login` 授权，并已 `social-hub context use <team-id>`。
+> 命令使用 `-t <team-id>`（来自 `social-hub context current`）；不要用环境变量传 API key。
+
 ```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 list -t <team-id> -n 50
+social-hub accounts get -t <team-id> --account <uuid>
+social-hub accounts create -t <team-id> -j '{"platform":"reddit","handle":"u/example",...}'
+social-hub accounts update -t <team-id> --account <uuid> -j '{"workflowStage":"active",...}'
+social-hub accounts delete -t <team-id> --account <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 brand-bindings list -t <team-id> --account <uuid>
+social-hub accounts brand-bindings add -t <team-id> --account <uuid> -j '{"brandId":"..."}'
+social-hub accounts brand-bindings remove -t <team-id> --account <uuid> --brand <brandId>
 
-social-hub accounts status-snapshots list -t "$T" --account "<uuid>"
+social-hub accounts status-snapshots list -t <team-id> --account <uuid>
 ```
 
 OpenClaw 执行前优先 `social-hub context account`（见 `social-hub-openclaw-context`），不要只读本地 `account-profiles/*.md`。

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

@@ -1,14 +1,18 @@
 ---
 name: social-hub-admin
 description: >-
-  Social Hub 管理面：settings、invites、members、api-keys、agent-teams、users。
-  用户要改系统设置、发团队邀请、列成员、轮换 API Key 时用本 skill；高风险写操作需 --apply。
+  Social Hub 管理面：settings、invites、members、agent-teams、users。
+  用户要改系统设置、发团队邀请、列成员、管理团队结构时用本 skill；高风险写操作需 --apply。
+  API Key 的创建/轮换属于管理员资源管理，不是 CLI 日常登录方式（见 social-hub-shared）。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-admin
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 `auth login` 且 role 满足操作要求（多数管理命令需 admin 或 manager）。
+
 ## Settings（admin）
 
 ```bash
@@ -21,10 +25,10 @@ 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
+social-hub invites list -t <team-id>
+social-hub invites create -t <team-id> --email user@example.com --role manager --dry-run
+social-hub invites create -t <team-id> --email user@example.com --role manager --apply
+social-hub invites revoke -t <team-id> --id <inviteId> --apply
 ```
 
 ## Members
@@ -33,4 +37,7 @@ social-hub invites revoke -t "$T" --id "<inviteId>" --apply
 social-hub members list
 ```
 
-API Keys、users、agent-teams 等见 `social-hub-cli` 管理章节。
+## 团队 / 用户 / API Key（管理员）
+
+- **团队与用户**：`agent-teams`、`users` 命令见 `social-hub-cli` 管理章节。
+- **API Key**（`social-hub api-keys *`）：仅用于集成/服务端密钥管理；**Agent 日常操作仍用 Device Code**，不要把新建 API Key 当作 CLI 登录步骤。

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

@@ -4,22 +4,31 @@ description: >-
   发布日历与调度任务：social-hub calendar list、jobs list/create/batch/retry/cancel。
   用户要排期、查 scheduled job、重试失败任务、取消任务时用本 skill；Agent 执行态回填优先 ops-runtime。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-calendar-jobs
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 auth login 并选定 team（`context use`）。下文 `-t <team-id>` 来自 `context current`。
+
 ```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>"
+social-hub calendar list -t <team-id>
+social-hub calendar list-full -t <team-id> --account <accountId> --status scheduled
+social-hub calendar patch -t <team-id> -e <entryId> --body '{"status":"succeeded","permalink":"..."}'
+
+social-hub jobs list -t <team-id> --status scheduled
+social-hub jobs list-full -t <team-id> --account <accountId>
+social-hub jobs create -t <team-id> -j '{"socialAccountId":"...","action":"engage","subreddit":"...","runAt":"..."}'
+social-hub jobs retry -t <team-id> -i <jobId>
+social-hub jobs cancel -t <team-id> -i <jobId>
 ```
 
-遗留：`jobs agent-status` 仍可更新状态，但 OpenClaw 推荐：
+OpenClaw / Agent 运行时优先：
 
 ```bash
-social-hub ops claim-next -t "$T" --agent "<agentId>"
-social-hub ops complete|fail|skip ...
+social-hub ops claim-next -t <team-id> --agent <agentId>
+social-hub ops heartbeat|complete|fail|skip ...
 ```
+
+见 `social-hub-ops-runtime`。遗留 `jobs agent-status` 仅在未接 ops 链路时使用。

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

@@ -1,363 +1,235 @@
 ---
 name: social-hub-cli
 description: >-
-  Social Ops Hub 命令行 social-hub：账号、事件、日历、调度任务、Reddit 帖、报告、API Key、OpenClaw 回填等。
+  Social Ops Hub 命令行 social-hub：账号、事件、日历、调度任务、Reddit 帖、报告、OpenClaw 回填等。
   只要用户提到 social-hub、Social Ops Hub、Hub 写数据、查账号、发帖计划、permalink 回填、openclaw、
-  调度任务、团队 API Key、互动事件，或要在 Hub 里查/改运营数据，就应使用本 skill（即使用户没说 CLI）。
-  先读本 skill 做路由，再打开对应领域 skill（ops-runtime、openclaw-context 等）。
+  调度任务、互动事件，或要在 Hub 里查/改运营数据，就应使用本 skill（即使用户没说 CLI）。
+  先读本 skill 做路由；执行任何命令前必须先读 social-hub-shared 完成 auth login 与 context。
 metadata:
-  cliVersion: ">=0.0.4"
-  homepage: https://github.com/your-org/social-ops-hub/tree/main/skills
+  cliVersion: ">=0.0.6"
+  homepage: https://github.com/geoly-ai/geoly-reddit/tree/main/social-ops-hub/skills
 ---
 
 # Social Hub CLI
 
-`social-hub` 封装 Social Ops Hub REST API，供人工与 Agent 使用。配套领域 skill 与本目录同级（`skills/social-hub-*`）。
+`social-hub` 封装 Social Ops Hub REST API，供人工与 Agent 使用。
 
-## 安装 Skill
+> **前置条件：** 执行 Hub 命令前 MUST 先读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 完成 `social-hub auth login`（Device Code）并 `social-hub context use <team-id>`。
+> 日常**不要**使用 `SOCIAL_HUB_API_KEY` / `SOCIAL_HUB_API_URL` 环境变量。
 
-- **推荐（CLI）**：`social-hub skills tui` 或 `social-hub skills install --agent cursor --global --yes`
+## 快速开始（生产）
+
+```bash
+social-hub auth login --api-url https://reddit.eclick-geo.com/api
+social-hub auth whoami
+social-hub context use <team-uuid>
+social-hub doctor
+social-hub health
+```
+
+生产 API 基址：**`https://reddit.eclick-geo.com/api`**。下文示例中 `<team-id>` 指当前 context 的 team UUID。
+
+## 安装 CLI 与 Skill
+
+```bash
+npm install -g @geoly-ai/social-hub-cli@latest
+social-hub version
+```
+
+安装 Agent Skills：
+
+- **推荐**：`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`）
+- **更新**：`social-hub skills update --all --yes`
+- **检查**：`social-hub skills doctor`
+- **同仓开发**：`pnpm skills:install`（目标目录可用 `SKILLS_INSTALL_DIR=~/.cursor/skills`）
 
-## 领域 Skill 路由（先读子 skill）
+## 领域 Skill 路由
 
 | 场景 | Skill |
 |------|--------|
-| 配置 / doctor / auth | `social-hub-shared` |
+| 鉴权 / config / doctor / context | **`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` |
+| settings / invites / 成员 | `social-hub-admin` |
 | 情报 | `social-hub-intelligence` |
 | 导入导出 replay | `social-hub-migration` |
 
-`social-hub` 是 Social Ops Hub 的命令行工具，封装了全部 REST API。
+命中上表场景时，打开对应领域 skill，**不要**只在总览里硬写命令而跳过子 skill。
 
-## 配置（环境变量）
+## 同仓开发 Build
 
-使用前需设置以下环境变量：
+在 **social-ops-hub  monorepo** 内改 CLI/SDK 后：
 
 ```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
 ```
 
----
-
-## 初始化工作流（新环境冷启动）
+## 本地 API 冷启动（仅开发）
 
-### 步骤 0：部署前置
+部署/seed 细节见仓库文档；CLI 侧只需改 API 地址并重新 login：
 
 ```bash
-# 1. 复制并填写环境变量
-cp .env.example .env
-# 至少填写：DATABASE_URL、REDIS_URL、API_KEY_PEPPER、JWT_SECRET
-
-# 2. 执行数据库迁移
+cp .env.example .env   # 填写 DATABASE_URL、REDIS_URL 等
 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 是否正常
+pnpm dev
+social-hub auth login --api-url http://localhost:3000
+social-hub context use <seed 输出的 team uuid>
 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"}'
+创建新 team、用户等业务初始化：在 **已 auth login 且 role 足够** 的前提下执行下方「团队与用户管理」命令；**不要**再 export API Key。
 
-# 为新团队创建 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
+# 创建品牌 → campaign → 账号 → 计划（<team-id> 来自 context current）
+BRAND_ID=$(social-hub brands create -t <team-id> -j '{"name":"My Brand","slug":"my-brand"}' | jq -r '.id')
+CAMP_ID=$(social-hub campaigns create -t <team-id> -j "{\"brandId\":\"$BRAND_ID\",\"name\":\"2026 Q3 Launch\"}" | jq -r '.id')
+ACCOUNT_ID=$(social-hub accounts create -t <team-id> -j '{"platform":"reddit","handle":"u/my_ops_account","credentialsRef":"vault:javis/main"}' | jq -r '.id')
+DRAFT_ID=$(social-hub drafts create -t <team-id> -j "{\"campaignId\":\"$CAMP_ID\",\"title\":\"Launch Post\",\"body\":\"...\"}" | jq -r '.id')
+social-hub plans create -t <team-id> -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 <team-id> --status scheduled
+social-hub jobs list -t <team-id> --status scheduled
 ```
 
 ---
 
 ## 命令速查表
 
+以下 `-t <team-id>` 可换为 `social-hub context current` 中的 `currentTeamId`。
+
 ### health & dashboard
 
 ```bash
 social-hub health
-social-hub dashboard summary -t $T
-social-hub dashboard summary -t $T  # 支持 campaignId 过滤（通过 API 传参）
+social-hub dashboard summary -t <team-id>
 ```
 
 ### 互动事件
 
 ```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
+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>
+social-hub events export-csv -t <team-id> > events.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://..."}'
+social-hub calendar list -t <team-id> --status scheduled
+social-hub calendar list-full -t <team-id> --account <accountId> --status scheduled
+social-hub calendar patch -t <team-id> -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>
+social-hub jobs list -t <team-id> --status scheduled
+social-hub jobs create -t <team-id> -j '{"socialAccountId":"<uuid>","action":"engage","subreddit":"LocalLLaMA","runAt":"2026-05-07T09:00:00Z"}'
+social-hub jobs retry -t <team-id> -i <jobId>
+social-hub jobs cancel -t <team-id> -i <jobId>
 ```
 
-### 内容草稿
-
-```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"}'
-```
+OpenClaw 执行态优先 `social-hub ops *`（见 `social-hub-ops-runtime`）；`jobs agent-status` 为遗留路径。
 
-### 账号管理
+### 发布计划 / 草稿 / 报告
 
 ```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":"..."}'
+social-hub plans list -t <team-id>
+social-hub plans create -t <team-id> -j '{"campaignId":"<uuid>","name":"Q3 Week1","entries":[...]}'
+social-hub drafts list -t <team-id> -n 20
+social-hub reports list -t <team-id> -n 20
 ```
 
-### 品牌与 Campaign
+### 账号 / 品牌 / 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"}'
+social-hub accounts list -t <team-id> --status active
+social-hub accounts get -t <team-id> --account <uuid>
+social-hub brands list -t <team-id>
+social-hub campaigns list -t <team-id> --brand <brandId>
 ```
 
 ### 板块情报
 
 ```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
+social-hub intelligence hot-posts -t <team-id> --subreddit LocalLLaMA --sort score -n 50
+social-hub intelligence dispatch -t <team-id> -j '{"hotPostId":"<uuid>","socialAccountId":"<uuid>","action":"engage"}'
+social-hub intelligence watchlists-list -t <team-id>
 ```
 
 ### 团队与用户管理
 
 ```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"}'
+social-hub agent-teams create --slug javis --name "Javis Agent Team"   # admin only
+social-hub users list -t <team-id>
+social-hub users create -t <team-id> -j '{"email":"ops@example.com","password":"...","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>
+social-hub notification-channels list -t <team-id>
+social-hub notification-channels create -t <team-id> -j '{"provider":"feishu","externalId":"https://..."}'
 ```
 
-### API Key 管理
+### API Key 管理（管理员资源，非 CLI 登录方式）
 
 ```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>
+social-hub api-keys list -t <team-id>
+social-hub api-keys create -t <team-id> -j '{"name":"integration","role":"manager"}'
 ```
 
 ---
 
 ## 典型工作流
 
-### 工作流 1：Agent 执行完成后回填 Hub
+### Agent 执行完成后回填
 
-```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\"}"
+优先 `social-hub ops complete --permalink ...`（见 `social-hub-ops-runtime`）。手动 patch 示例：
 
-# 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
+```bash
+social-hub calendar patch -t <team-id> -e <entryId> \
+  --body '{"status":"succeeded","permalink":"https://www.reddit.com/r/.../..."}'
+social-hub events append -t <team-id> --type post.published \
+  --payload '{"permalink":"...","calendarEntryId":"<entryId>"}'
 ```
 
-### 工作流 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
+social-hub accounts get -t <team-id> --account <accountId>
+social-hub events list-full -t <team-id> --account <accountId> -n 20
+social-hub jobs list-full -t <team-id> --account <accountId> --status scheduled
+social-hub compliance risk-get -t <team-id> -a <accountId>
 ```
 
-### 工作流 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
+social-hub intelligence hot-posts -t <team-id> --sort score -n 10
+social-hub accounts list -t <team-id> --status active
+social-hub intelligence dispatch -t <team-id> -j '{"hotPostId":"...","socialAccountId":"...","action":"engage","runAt":"..."}'
+social-hub jobs list -t <team-id> --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
-
+- 命令输出多为 **JSON**，可管道 `jq`。
+- `DELETE` / cancel 成功时可能返回 204，CLI 打印 `OK`。
+- `events export-csv`、`intelligence hot-posts-export` 输出 CSV 到 stdout。
+- 团队管理（`agent-teams create` 等）需要 **admin** role 的 CLI token。
+- CLI 凭证来自 **Device Code**（`auth login`），不是 Web Session Cookie，也不是日常手动创建的 API Key。

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

@@ -3,20 +3,20 @@
   "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 结果",
+      "prompt": "我要连生产 Social Ops Hub（https://reddit.eclick-geo.com/api），用 social-hub 登录并确认当前身份和 team，然后在 Hub 里注册一个新团队 javis（slug 也是 javis），给这个团队添加管理员用户 ops@javis.local，密码 Javis2026!，最后确认团队列表里有 javis。不要用 SOCIAL_HUB_API_KEY 环境变量。",
+      "expected_output": "先读 social-hub-shared：auth login --api-url 生产地址、auth whoami、context use；再读 social-hub-cli/admin：agent-teams create、users create、agent-teams list；全程 Device Code 凭证，不 export API key",
       "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，输出每步的命令和结果",
+      "prompt": "Reddit 账号 u/example_user 刚在 r/LocalLLaMA 发帖，permalink 是 https://www.reddit.com/r/LocalLLaMA/comments/abc123/test_post/，日历条目 def456-uuid。我已在生产 Hub auth login 并 context use 了 team。帮我把日历标 succeeded、写 post.published 事件，并查该账号最近事件。优先 ops complete，若需手动则 calendar patch + events append。",
+      "expected_output": "确认已 auth/context；执行 ops complete 或 calendar patch + events append + events list-full；不要求设置 SOCIAL_HUB_API_KEY",
       "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 确认，输出各步命令和结果",
+      "prompt": "查生产 Hub 里 r/Entrepreneur 按 score 前 5 热帖，给账号 ghi789-uuid 派发 engage 任务，runAt 2026-05-07T01:00:00Z，并确认 jobs 列表有新任务。我已 social-hub auth login 到 reddit.eclick-geo.com。",
+      "expected_output": "路由 social-hub-intelligence：hot-posts、dispatch；social-hub-calendar-jobs：jobs list；使用 -t team-id 来自 context，不用 localhost 或 API key env",
       "assertions": []
     }
   ]

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

@@ -4,22 +4,27 @@ description: >-
   板块情报：watchlists、hot posts、KOL intents、industry-pools、dispatch 等 social-hub intelligence 子命令。
   用户要盯 subreddit、拉热帖、行业池、情报派发时用本 skill。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-intelligence
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 auth login 并 `context use <team-id>`。
+
 ```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
+social-hub intelligence industry-pools-list -t <team-id>
+social-hub intelligence watchlists-list -t <team-id>
+social-hub intelligence hot-posts -t <team-id> --subreddit technology --sort score -n 50
+social-hub intelligence kol-intents -t <team-id> -n 20
+social-hub intelligence dispatch -t <team-id> -j '{ ... }'   # 写操作：确认 payload 与 --apply（若命令支持）
 ```
 
-账号可发帖板块优先用：
+账号可发帖板块优先用 Hub DB 查询，不要猜 subreddit：
 
 ```bash
-social-hub query account-pools -t "$T" --account <ref>
+social-hub query account-pools -t <team-id> --account <ref>
+social-hub query subreddit-candidates -t <team-id> --account <ref> --action publish_post
 ```
 
 WebSocket `runs/ws` 为 watch 能力，不适合普通 CLI 批处理。

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

@@ -4,23 +4,26 @@ description: >-
   Hub 数据批量：export events-jsonl、export agent-context、runbook replay、openclaw-ingest。
   用户要导出 JSONL、回放事件、迁移/对账时用本 skill；不包含工作区 shared 目录批量 sync（需人工决策）。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-migration
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 auth login；导出/回放目标 team 用 `-t <team-id>`。
+
 ## 导出
 
 ```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
+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
 ```
 
 ## Runbook 回放
 
 ```bash
-social-hub runbook replay -t "$T" -f events.jsonl --dry-run
-social-hub runbook replay -t "$T" -f events.jsonl          # 实际 append events
+social-hub runbook replay -t <team-id> -f events.jsonl --dry-run
+social-hub runbook replay -t <team-id> -f events.jsonl          # 实际 append events
 ```
 
 JSONL 每行：`{"type":"comment","payload":{...}}`

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

@@ -5,15 +5,18 @@ description: >-
   export agent-context。用户问账号能发哪些版、任务上下文、板块池、guardrails、数据是否过期时，
   必须用 Hub DB 聚合接口，不要解析 Javis/Moss/Panda 工作区里的 shared/*.md。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-openclaw-context
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 auth login。所有 `-t <team-id>` 与授权 team 一致。
+
 ## 账号上下文
 
 ```bash
-social-hub context account -t "$T" --account A1 \
+social-hub context account -t <team-id> --account A1 \
   --expand pools,jobs,persona,risk,env,guardrails
 ```
 
@@ -22,24 +25,24 @@ social-hub context account -t "$T" --account A1 \
 ## 任务上下文
 
 ```bash
-social-hub context job -t "$T" --job "<scheduledJobId>"
+social-hub context job -t <team-id> --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
+social-hub query account-pools -t <team-id> --account A1 --limit 50
+social-hub query subreddit-candidates -t <team-id> --account A1 --action publish_post
 ```
 
-## 导出（给人看或离线审计）
+## 导出（审计 / 离线查看）
 
 ```bash
-social-hub export agent-context -t "$T" --account "<uuid>" -o /tmp/ctx.json
+social-hub export agent-context -t <team-id> --account <uuid> -o /tmp/ctx.json
 ```
 
 ## freshness
 
-响应中的 `freshness.needsRefresh === true` 时，应先刷新账号指标或情报，再执行发帖/评论。
+响应中 `freshness.needsRefresh === true` 时，应先刷新账号指标或情报，再执行发帖/评论。
 
 执行任务前配合 `social-hub-ops-runtime`；执行后 `ops complete` 回填 permalink。

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

@@ -4,31 +4,33 @@ description: >-
   OpenClaw / Agent 任务运行时：social-hub ops claim-next、claim、heartbeat、complete、fail、skip。
   用户要领任务、续租、心跳、回填 permalink、任务失败/跳过、避免改本地 Markdown 状态时必须用本 skill。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-ops-runtime
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 auth login 并 `context use <team-id>`。不要用环境变量传 team 或 API key。
+
 Hub DB 是执行状态的真源；不要用 `shared/reddit-account-status.md` 等文件记录任务结果。
 
 ## 推荐流程
 
 ```bash
-export T="$SOCIAL_HUB_TEAM_ID"
-export AGENT="javis"   # 或 moss / 你的 agentId
+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"
+social-hub ops claim-next -t <team-id> --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）
-social-hub ops complete -t "$T" --job "<jobId>" --agent "$AGENT" --permalink "https://reddit.com/..."
+social-hub ops complete -t <team-id> --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
+social-hub ops fail -t <team-id> --job <jobId> --agent "$AGENT" --reason rule_blocked --message "..."
+social-hub ops skip -t <team-id> --job <jobId> --agent "$AGENT" --reason manual_intervention_required
 ```
 
 ## `--reason` 枚举（仅允许下列值）

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

@@ -4,17 +4,20 @@ description: >-
   Reddit 帖快照与数据：social-hub reddit list/stats/refresh/refresh-all/import-feishu 等。
   用户要查帖表现、刷新 score、导入飞书表、permalink 对应快照时用本 skill（命令组名为 reddit）。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-posts
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 auth login 并选定 team。
+
 ```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 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-all -t <team-id>
+social-hub reddit import-feishu -t <team-id> -j '{ ... }'
 ```
 
-发帖成功后应通过 `social-hub ops complete --permalink ...` 写回任务链路（见 `social-hub-publishing`）。
+发帖成功后应通过 `social-hub ops complete --permalink ...` 写回任务链路（见 `social-hub-publishing` / `social-hub-ops-runtime`）。

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

@@ -4,11 +4,14 @@ description: >-
   内容发布闭环：campaign → plan → draft → calendar → scheduled_job → events → reddit snapshot → report。
   用户要从草稿到排期、执行任务、permalink 回填、避免 job 成功但 calendar 未更新时用本 skill。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-publishing
 
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 auth login 并 `context use <team-id>`。
+
 ## 事实源
 
 - **计划**：`calendar_entries`
@@ -28,4 +31,4 @@ campaign → publishing_plan → content_draft → calendar_entry → scheduled_
 2. `social-hub ops claim-next` → 执行 → `social-hub ops complete --permalink <url>`
 3. `complete` 原子更新 job + calendar（+ 可选 snapshot id）
 
-失败时 `ops fail` / `ops skip`，并写标准 `reason` 枚举。
+失败时 `ops fail` / `ops skip`，并使用标准 `reason` 枚举（见 `social-hub-ops-runtime`）。

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

@@ -1,41 +1,143 @@
 ---
 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。
+  social-hub 共享基础：config、auth login（Device Code）、context use/current、doctor、
+  permissions、权限排障与安全规则。用户首次配置、登录授权、连不上 API、team 不对、
+  权限不足、或任何 Hub CLI 写操作前必须先读本 skill。Agent 日常凭证只用 auth login，
+  不要用 SOCIAL_HUB_API_KEY 环境变量。
 metadata:
-  cliVersion: ">=0.0.1"
+  cliVersion: ">=0.0.6"
 ---
 
 # social-hub-shared
 
-## 环境变量
+本 skill 是 Social Hub CLI 的**唯一详细鉴权与配置文档**。领域 skill（accounts、ops-runtime 等）开头会要求先读本文件；不要在各领域 skill 里重复展开鉴权流程。
 
-```bash
-export SOCIAL_HUB_API_URL="http://localhost:3000"
-export SOCIAL_HUB_API_KEY="soh_..."
-export SOCIAL_HUB_TEAM_ID="<team-uuid>"   # 或用 context use 持久化
-```
+## 凭证与配置真源
+
+| 项 | 推荐来源 | 说明 |
+|---|---|---|
+| API 地址 | `~/.config/social-hub/config.json` → `apiUrl` | 生产默认 `https://reddit.eclick-geo.com/api` |
+| 凭证 | 同上 → `authToken`（Device Code 登录后写入） | CLI 内部以 Bearer 发送；**不要用环境变量传 key** |
+| 默认 team | `context.json` 的 `currentTeamId` 或 config 的 `teamId` | 用 `social-hub context use` 持久化 |
 
-## 常用命令
+配置文件路径：`~/.config/social-hub/config.json`（权限 `600`）。
+
+## 快速开始（生产）
 
 ```bash
-social-hub config init --api-url http://localhost:3000 --team $T
-social-hub auth login --api-key "$SOCIAL_HUB_API_KEY"
+# 1. 浏览器 Device Code 授权（推荐，唯一日常路径）
+social-hub auth login --api-url https://reddit.eclick-geo.com/api
+
+# 2. 确认身份与 team
 social-hub auth whoami
+social-hub context list
+
+# 3. 选定当前操作的 team（只需做一次，或切换 team 时再做）
+social-hub context use <team-uuid>
+
+# 4. 健康与鉴权自检
 social-hub doctor
-social-hub version --json
-social-hub context use "$T"
+social-hub health
+```
+
+`health` 不需要登录；其他写读 Hub 数据的命令需要先完成 `auth login`。
+
+## 认证
+
+### 推荐：Device Code（`auth login`）
+
+Agent 帮用户授权时，执行 `social-hub auth login` 并在终端输出 verification URL / user code，引导用户在浏览器完成审批：
+
+```bash
+social-hub auth login --api-url https://reddit.eclick-geo.com/api
+# 可选：登录时指定默认 team
+social-hub auth login --api-url https://reddit.eclick-geo.com/api --team <team-uuid>
+# 可选：CLI token 时长（需 Web 审批账号有相应权限）
+social-hub auth login --duration short   # 默认
+social-hub auth login --duration long
+```
+
+成功后凭证写入 `config.json` 的 `authToken`，无需再 export 任何变量。
+
+### 查看 / 退出
+
+```bash
+social-hub auth whoami      # 同 auth status；含 role、teamId、visibleTeamIds
+social-hub auth status
+social-hub auth explain     # 当前 role 可用命令
+social-hub auth logout
+social-hub auth logout --revoke   # 同时撤销服务端 CLI token
+```
+
+### Team 上下文
+
+多数命令需要 `-t <team-uuid>`。先持久化当前 team，示例里可直接引用：
+
+```bash
+social-hub context use <team-uuid> [--label "moss"]
 social-hub context current
-social-hub permissions matrix
-social-hub auth explain
+social-hub context list     # 含 authTeamId、visibleTeamIds
+```
+
+### 配置命令
+
+```bash
+social-hub config show
+social-hub config init --api-url https://reddit.eclick-geo.com/api [--team <uuid>]
+social-hub config set apiUrl https://reddit.eclick-geo.com/api
+social-hub config set teamId <team-uuid>
+```
+
+## 本地开发（仅调试 API 时用）
+
+本地 monorepo 跑 API 时，API 地址改为 `http://localhost:3000`：
+
+```bash
+pnpm dev   # 在 social-ops-hub 根目录
+social-hub auth login --api-url http://localhost:3000
 ```
 
-## 排障顺序
+本地 seed（`pnpm run db:seed:minimal-admin`）会打印 admin 账号；**仍应通过 Web 登录 + Device Code 授权 CLI**，不要把 seed 输出的 key 写进 skill 示例或环境变量。
+
+## Legacy：静态 API Key（管理员资源，非 Agent 日常凭证）
+
+CLI 仍兼容 `social-hub auth login --api-key sk_live_…` 与 `SOCIAL_HUB_API_KEY` 环境变量，但**仅用于**：
+
+- 服务端自动化 / CI（若团队明确允许）
+- 管理员在 Hub Web 创建、轮换的 **API Key 资源**（`social-hub api-keys *`）
+
+**Agent 与人工日常操作一律用 Device Code，不要**：
+
+- `export SOCIAL_HUB_API_KEY=...`
+- 在 skill 示例里把 API Key 当默认登录方式
+- 把「创建 api-key」和「CLI 登录」混为一谈
+
+## 权限不足处理
+
+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 是否允许该命令
+5. 403 / permission denied — 换有权限的 Web 账号重新 `auth login`，或请 admin 调整成员角色
+
+admin 专属操作（如 `agent-teams create`）需要 **admin** role 的 CLI token，不是「随便创建一个 API Key」就能替代。
+
+## 安全规则
+
+- **禁止**在对话或日志中输出完整 token / API Key（`config show` 已脱敏）。
+- **写入 / 删除**前确认用户意图；admin skill 中高风险操作用 `--dry-run` / `--apply`。
+- **不要**用 `SOCIAL_HUB_CONFIG_DIR` 绕开标准配置路径，除非用户明确要求隔离环境。
+- Session Cookie 认证不在 CLI 支持范围内；CLI 使用 Bearer token（Device Code 或 legacy API Key）。
+
+## 排障顺序（简表）
 
-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` 查看当前角色允许的命令
+| 现象 | 检查 |
+|------|------|
+| Not logged in | `social-hub auth login` |
+| API unreachable | `config show` 的 apiUrl；生产应为 `https://reddit.eclick-geo.com/api` |
+| Missing team id | `context use <uuid>` 或命令加 `-t` |
+| team 不一致 warning | `auth whoami` 的 teamId vs `context current` |
+| 401 / auth failed | 重新 `auth login`；过期则 `auth logout` 后重登 |
 
-更完整命令表见同包的 `social-hub-cli` skill。
+更完整命令速查见同包 `social-hub-cli` skill。