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

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。