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

package/skills/social-hub-post-review/SKILL.md

@@ -41,30 +41,56 @@ social-hub content post-review -t <team-id> -j '{
 
 ## 两种审核模式
 
-| 模式 | 请求 | 结论边界 |
-| --- | --- | --- |
-| `ContentOnly` | 省略 `accountId` | 响应为 `reviewContext.accountMode=persona_less`；可审核标题正文、软广、AI 结构、规则证据和发帖动机，但不能声称账号人设适配已完成 |
-| `AccountBound` | 传真实 `accountId` | 在内容审核外验证账号 persona/style 与品牌适配；最终发布前使用 |
+| 模式           | 请求               | 结论边界                                                                                                                         |
+| -------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `ContentOnly`  | 省略 `accountId`   | 响应为 `reviewContext.accountMode=persona_less`；可审核标题正文、软广、AI 结构、规则证据和发帖动机，但不能声称账号人设适配已完成 |
+| `AccountBound` | 传真实 `accountId` | 在内容审核外验证账号 persona/style 与品牌适配；最终发布前使用                                                                    |
 
 ContentOnly 的 `completed/pass` 是内容结论，不是最终发布资格。应标记
 `AccountBindingStatus: Pending`、`ReadyForDelivery: No`；
 `accountCandidateFeedback` 只做账号候选建议，不阻断内容审核。
 `stage` 仅在值来自有效账号上下文时传；不确定就省略。
 
+### brandContext（可选品牌上下文）
+
+请求可带 `brandContext`（可省略），三种入口任选其一：
+
+| 键           | 语义                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------- |
+| `brandKey`   | registry canonical key 或 alias                                                                               |
+| `campaignId` | legacy 归因入口：Hub 解 campaignId→campaign.brandId→registry brandKey                                         |
+| `brandId`    | **系统级 brand `brands.id`（来自 `brands system-list`，不是 `brand_registry.id`）**，与 publishing 新流程对齐 |
+
+`brandId` 是新流程入口（与 social-hub-publishing「新流程用系统级 brandId、campaignId 仅
+legacy 归因」一致），**persona-less 与账号路径都支持**。生命周期语义按路径不同：persona-less
+active 优先、否则回退最新 retired；**账号路径 active-only**（无 active 映射 → 422
+`BRAND_REGISTRY_METADATA_MISSING`）。账号路径品牌上下文**仅账号已绑 persona 时才解析**，未绑
+persona 则三入口一律静默忽略。多个入口解析到不同 canonical registry → 409 冲突。
+
+```bash
+# persona-less（无 accountId）用系统级 brandId：
+social-hub content post-review -t <team-id> -j '{
+  "title": "<帖子标题>",
+  "body": "<帖子正文>",
+  "subreddit": "buildapc",
+  "brandContext": { "brandId": "<brands.id from `brands system-list`>" }
+}'
+```
+
 Reddit matrix 的发布闸门比本通用 skill 更严格：`degraded` 或 Hub
 不可用只能诊断，不能替代 Hub pass。
 
 ## 七维口径(0-100,服务端计分,模型自报分仅对照)
 
-| 维度                        | 判什么                                                                                  |
-| --------------------------- | --------------------------------------------------------------------------------------- |
-| `title_body_fit`            | 标题承诺 vs 正文兑现(bait-and-switch 低分)                                              |
-| `clickbait_or_manipulation` | 标题党/情绪操纵/虚假紧迫(<35 单维红线 block)                                            |
-| `promotion_risk`            | 软广/导流/品牌推销痕迹(<40 单维红线 block)                                              |
-| `subreddit_rule_fit`        | 只按提供的版规快照判;**没传版规 → 该维标 insufficient_context 并被剔除权重,不伪造结论** |
-| `ai_structural_tone`        | 小标题排比/总分总/清单腔等 AI 结构感                                                    |
+| 维度                        | 判什么                                                                                            |
+| --------------------------- | ------------------------------------------------------------------------------------------------- |
+| `title_body_fit`            | 标题承诺 vs 正文兑现(bait-and-switch 低分)                                                        |
+| `clickbait_or_manipulation` | 标题党/情绪操纵/虚假紧迫(<35 单维红线 block)                                                      |
+| `promotion_risk`            | 软广/导流/品牌推销痕迹(<40 单维红线 block)                                                        |
+| `subreddit_rule_fit`        | 只按提供的版规快照判;**没传版规 → 该维标 insufficient_context 并被剔除权重,不伪造结论**           |
+| `ai_structural_tone`        | 小标题排比/总分总/清单腔等 AI 结构感                                                              |
 | `persona_consistency`       | AccountBound 时判断账号人设；ContentOnly/persona_less 时只能标 NotAssessed/弱验证，不得声称已验证 |
-| `natural_post_intent`       | 真人为何发这帖(无动机的"分享产品体验"低分)                                              |
+| `natural_post_intent`       | 真人为何发这帖(无动机的"分享产品体验"低分)                                                        |
 
 ## 判定规则
 

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）。