@geoly-ai/social-hub-cli 0.2.23 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/social-hub-cli",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "type": "module",
   "description": "social-hub CLI for Social Ops Hub",
   "repository": {
@@ -22,8 +22,8 @@
   },
   "dependencies": {
     "commander": "^12.1.0",
-    "@geoly-ai/social-hub-sdk": "0.0.38",
-    "@geoly-ai/social-hub-authz": "0.0.7"
+    "@geoly-ai/social-hub-authz": "0.0.7",
+    "@geoly-ai/social-hub-sdk": "0.0.38"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/skills/README.md

@@ -126,6 +126,7 @@ pnpm skills:check
 | [social-hub-accounts](social-hub-accounts)                         | 账号 CRUD、browser-envs、personas |
 | [social-hub-posts](social-hub-posts)                               | Reddit 帖快照 CRUD、batch-upsert  |
 | [social-hub-style-curator](social-hub-style-curator)               | style-marks、curator、style-guide |
+| [social-hub-style-profiles](social-hub-style-profiles)             | 板块画像四眼、帖子标注            |
 | [social-hub-calendar-jobs](social-hub-calendar-jobs)               | 日历与任务                        |
 | [social-hub-publishing](social-hub-publishing)                     | 发布闭环                          |
 | [social-hub-events-observability](social-hub-events-observability) | events、dashboard、audit、reports |

package/skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "package": "social-ops-hub",
-  "cliVersion": "0.2.23",
+  "cliVersion": "0.2.24",
   "repository": "social-ops-hub",
   "publish": {
     "registry": "https://skill.sh",
@@ -44,6 +44,11 @@
       "path": "social-hub-style-curator",
       "description": "style-marks 审核/沉淀、curator run、accounts style-guide"
     },
+    {
+      "id": "social-hub-style-profiles",
+      "path": "social-hub-style-profiles",
+      "description": "板块画像四眼治理(style-profiles)与帖子标注(subreddit-annotations)"
+    },
     {
       "id": "social-hub-calendar-jobs",
       "path": "social-hub-calendar-jobs",

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

@@ -38,6 +38,7 @@ social-hub version --json
 | 社交账号 CRUD / browser-envs / personas           | `social-hub-accounts`             |
 | Reddit 帖快照 CRUD / batch-upsert                 | `social-hub-posts`                |
 | style-marks / curator / style-guide               | `social-hub-style-curator`        |
+| 板块画像四眼 / 帖子标注                           | `social-hub-style-profiles`       |
 | 日历 / scheduled jobs                             | `social-hub-calendar-jobs`        |
 | 发布闭环（brand→report）                          | `social-hub-publishing`           |
 | 评论发布前复审/优化（三层 gate 层③）              | `social-hub-content-review`       |

package/skills/social-hub-style-profiles/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: social-hub-style-profiles
+description: >-
+  Social Hub 板块画像/帖子标注：style-profiles list/get/active/propose/approve/reject/cancel/retire
+  （系统级四眼治理）与 subreddit-annotations list/upsert（团队维度人工标注）。
+  用户要查/审板块风格画像、处理画像提案、给 Reddit 帖打 style_fit/brand_friendliness 标注时用本 skill。
+  不用于账号级 style-marks/curator（用 social-hub-style-curator）、运营板块池 CRUD（用 social-hub-subreddit-pools）。
+metadata:
+  cliVersion: ">=0.2.24"
+---
+
+# social-hub-style-profiles
+
+> **前置条件：** 先阅读 [`../social-hub-shared/SKILL.md`](../social-hub-shared/SKILL.md)，
+> 确认已 `auth login`（Device Code 的 CLI **user token**）并 `context use <team-id>`。
+
+板块画像（`subreddit_style_profiles`）是系统级共享知识库：worker 定时从板块热帖用 LLM 起草，
+**恒以 `proposed` 入库**，必须人工四眼审批后 `approved` 才生效（供发帖/评论审核 enrich 引用）。
+帖子标注（`subreddit_post_annotations`）是 team 维度的人工研判（`style_fit` / `brand_friendliness`，1-5 分）。
+
+## 职责边界
+
+| 做                                                       | 不做                                                                   |
+| -------------------------------------------------------- | ---------------------------------------------------------------------- |
+| 画像读面 list/get/active、提案 propose、四眼审批流转     | 账号级风格资产（style-marks / curator run → social-hub-style-curator） |
+| 帖子 style_fit / brand_friendliness 人工标注 list/upsert | 运营板块池 catalog/aliases/tier rules（→ social-hub-subreddit-pools）  |
+
+## 关键约束（先读再操作）
+
+- **写操作全部 user-only**：propose/approve/reject/cancel/retire/upsert 拒绝 API Key（CLI 本地先拒，API 侧同样 403）。
+  必须用 `social-hub auth login` 拿到的 CLI token 执行。
+- **角色**：画像写只 manager/admin；标注 supervisor 及以上可写、senior/internal 只读、client 恒拒。
+- **四眼审批**：提案人本人不能 approve（409 `SELF_APPROVE`）——propose 和 approve 要换人操作。
+- **If-Match 乐观锁**：approve/reject/cancel/retire 必须带 `If-Match: <rowVersion>`。
+  CLI 缺省自动 `GET` 一次取当前 `profile.rowVersion` 带上；也可 `--row-version <token>` 显式传（接受裸 token 或带引号 ETag）。
+  自动 GET 只是便利，竞态保护在服务端锁内：409 `PROFILE_STALE` 表示已被他人变更，**重新 get 核对后再重试**（CLI 不会自动重试）。
+- **cancel 仅提案人本人**（worker/LLM 起草的画像 `proposedByUserId` 为空，不可 cancel，由 manager/admin 用 `reject`）。
+
+## 画像读面
+
+```bash
+social-hub style-profiles list [--subreddit <name>] [--scope global|brand] \
+  [--brand <uuid>] [--status proposed,approved] [-n 50] [--offset 0]
+social-hub style-profiles get --id <profile-uuid>          # 响应 profile.rowVersion = 写操作 If-Match 值
+social-hub style-profiles active --subreddit <name> [--brand <uuid>]
+```
+
+`active` 语义：传 `--brand` 优先返回该品牌的 approved override，无 override 回退 global；不传只查 global。
+**没有生效画像是正常状态**，输出 `{ "profile": null, "versionToken": null }`，退出码 0。
+
+## 画像四眼工作流
+
+```bash
+# 1) 提案人：起草新画像版本（恒 proposed 入库；profile 至少含 tone 或非空 stylePoints/taboos）
+social-hub style-profiles propose -j '{
+  "scope": "global",
+  "subreddit": "bouldering",
+  "profile": {
+    "tone": "laid-back, supportive, anti-gatekeeping",
+    "stylePoints": ["share genuine progress stories", "beta questions welcome"],
+    "taboos": ["humble-bragging", "brand shilling"]
+  },
+  "summary": "r/bouldering 新手工友好社区画像"
+}' --apply        # scope=brand 时必须带 "brandId"
+
+# 2) 另一位 manager/admin：审批（自动 GET 取 rowVersion；--dry-run 先看 status/版本/提案人）
+social-hub style-profiles approve --id <profile-uuid> --dry-run
+social-hub style-profiles approve --id <profile-uuid> --apply
+
+# 审批人驳回（仅 proposed；落 retire_reason=rejected:<reason>）
+social-hub style-profiles reject --id <profile-uuid> --reason "taboos 与实际版规不符" --apply
+
+# 提案人本人撤回（仅 proposed 且本人；worker/LLM 提案请用 reject）
+social-hub style-profiles cancel --id <profile-uuid> --reason "重新整理后再提" --apply
+
+# 停用已生效画像（仅 approved）
+social-hub style-profiles retire --id <profile-uuid> --reason "画像过时,等新版本" --apply
+```
+
+所有写命令都遵循 `--dry-run` 预览 / `--apply` 执行约定；dry-run 会展示将写入的摘要
+（流转命令含自动取得的 `rowVersion` 与当前 `status/version/proposedByUserId`）。
+
+## 帖子标注（team 维度）
+
+```bash
+social-hub subreddit-annotations list [-t <team-id>] [--subreddit <name>] \
+  [--permalink <url>] [--type style_fit|brand_friendliness] [--brand <uuid>] \
+  [--source llm|human] [-n 50] [--offset 0]
+
+social-hub subreddit-annotations upsert [-t <team-id>] \
+  --subreddit bouldering \
+  --permalink "https://www.reddit.com/r/bouldering/comments/abc123/some_title/" \
+  --type style_fit --score 4 \
+  --label "tone-match" --note "高赞评论语气与画像一致" --apply
+
+# brand_friendliness 必须带 --brand;style_fit 禁带 --brand
+social-hub subreddit-annotations upsert -t <team-id> \
+  --subreddit bouldering --permalink "https://old.reddit.com/r/bouldering/comments/xyz789/t/" \
+  --type brand_friendliness --brand <brand-uuid> --score 2 \
+  --note "对品牌提及敏感,慎用" --apply
+```
+
+- **list 返回本团队行+全局行**：响应里 `teamId=null` 是系统全局行，当前 team UUID 是团队行。
+- **upsert 是 last-write-wins**：同源（`human`）同 identity（team+subreddit+permalink+type+brand）重复提交会覆盖既有标注，
+  服务端同事务落 before/after 审计。`source` 由服务端固定 `human` 并绑定当前用户。
+- **score 方向**：1=最差/敌意 … 5=最佳/友好。
+- **permalink** 必须是 reddit.com 的 `/r/<sub>/comments/` 帖链接（https，www/old/np 等子域均可）。
+- **`--scope global`**（默认 `team`）写系统共享知识库，另需 manager/admin 的画像治理权限，危险级升 admin。
+
+## API
+
+- `GET/POST /v1/system/subreddit-style-profiles`（list / propose）
+- `GET /v1/system/subreddit-style-profiles/active`、`GET .../:id`
+- `POST /v1/system/subreddit-style-profiles/:id/approve|reject|cancel|retire`（If-Match 必填）
+- `GET/POST /v1/teams/:teamId/subreddit-post-annotations`（list / upsert 走 `.../upsert`）
+
+权限资源：`subredditStyleProfile`（画像读写 + 全局标注的第二道 gate）、`subredditPostAnnotation`（标注读写）。
+
+## 常见排障
+
+- `PROFILE_IF_MATCH_REQUIRED` / `PROFILE_IF_MATCH_INVALID`（400）：写操作没带 If-Match。CLI 会自动 GET 带上；显式 `--row-version` 时检查 token 是否完整（`ssp:<id>:<status>:<updatedAtISO>`）。
+- `PROFILE_STALE`（409）：画像已被他人变更。重新 `style-profiles get --id <id>` 核对最新 `rowVersion` 与内容后再重试。
+- `SELF_APPROVE`（409）：四眼约束，提案人本人不能 approve，换另一位 manager/admin。
+- `ILLEGAL_TRANSITION`（409）：状态机不允许（如 reject 一个已 approved 的画像；cancel/reject 只接受 proposed，retire 只接受 approved）。
+- `403 subreddit style profile management requires an authenticated user`：用了 API Key。改 `social-hub auth login` 的 CLI token。
+- 标注 upsert 403 但角色看似够：API 要求 create+update 双动作；`--scope global` 另需 `subredditStyleProfile:update`（manager/admin）。