feat: 小程序阅读记录与资料链路、管理端用户规则、API/VIP/推荐与运营脚本

- miniprogram: reading-records、imageUrl/mpNavigate、多页资料与 VIP 展示调整 - soul-admin: Users/Settings/UserDetailModal、dist 构建产物更新 - soul-api: user/vip/referral/ckb/db、MBTI 头像管理、user_rule_completion、迁移 SQL - .cursor: karuo-party 与飞书文档；.gitignore 忽略 .tmp_skill_bundle Made-with: Cursor
2026-03-23 18:38:23 +08:00
parent cb6e2bff56
commit fa3da12b16
82 changed files with 5621 additions and 2723 deletions
--- a/.cursor/docs/feishu_开发群与项目复盘.md
+++ b/.cursor/docs/feishu_开发群与项目复盘.md
@@ -0,0 +1,38 @@
+# 飞书「开发群」与 Soul 项目复盘约定
+
+## 绑定关系
+
+- **Soul 创业派对（永平）**、**派对 AI 相关自动化**、**卡若 AI 侧发往本项目的复盘**，默认使用**同一开发群机器人 Webhook**。
+- Webhook 与项目在配置上是**一一绑定**：换群 = 改环境变量或下方脚本中的默认 URL，并确保飞书里该群已添加对应自定义机器人。
+
+## 默认 Webhook（开发群）
+
+环境变量（推荐在本机 shell 或 `scripts/.env.feishu` 同目录的 `.env` 中导出）：
+
+| 变量名 | 用途 |
+|--------|------|
+| `FEISHU_DEV_GROUP_WEBHOOK` | **主约定**：开发群统一入口；未设置时各脚本使用内置默认值。 |
+
+当前默认 URL（与飞书群内机器人一致）：
+
+`https://open.feishu.cn/open-apis/bot/v2/hook/c558df98-e13a-419f-a3c0-7e428d15f494`
+
+## 已接此 Webhook 的脚本（代码内默认或可读此变量）
+
+| 脚本 | 说明 |
+|------|------|
+| `scripts/send_chapter_poster_to_feishu.py` | 章节摘要 + 海报图（小程序码） |
+| 卡若AI `飞书管理/脚本/send_review_to_feishu_webhook.py` | 卡若 AI 复盘（文本/卡片） |
+| 卡若AI `飞书管理/脚本/soul_party_to_feishu_sheet.py` | 派对运营表同步后的群推送 |
+
+**复盘发哪里**：与 Soul 开发相关的**日终/迭代复盘** → 发 **`FEISHU_DEV_GROUP_WEBHOOK` 对应群**。  
+彩民/运营另群如需保留，可通过各脚本 `--webhook` 或单独环境变量覆盖。
+
+## 界面截图发群说明
+
+- 飞书自定义机器人发图需先走**应用上传**得到 `image_key`（见 `send_chapter_poster_to_feishu.py` 内逻辑）。
+- 无现成截图时：在复盘文本中附 **管理端 / 小程序 / API 文档** 等**可点击链接**，与海报一并发出。
+
+## 与「SKR / 开发群」口头约定
+
+- 群内链接、机器人由**项目侧**维护；**派对 AI** 与 **卡若 AI** 推送配置统一指向本开发群，避免复盘散落多个群。
--- a/.cursor/skills/karuo-party/SKILL.md
+++ b/.cursor/skills/karuo-party/SKILL.md
@@ -112,9 +112,11 @@ python3 "$VIDEO_SCRIPT/soul_slice_pipeline.py" --video "<原视频.mp4>" --clips
 ```bash
 DIST_SCRIPT="/Users/karuo/Documents/个人/卡若AI/03_卡木（木）/木叶_视频内容/多平台分发/脚本"

-# 定时排期：第1条立即，后续 30-120min 随机间隔
+# 默认智能错峰 + 静默（不自动弹窗扫视频号）
 python3 "$DIST_SCRIPT/distribute_all.py" --video-dir "<成片目录>"

+# 旧版随机间隔：加 --legacy-schedule；需要自动扫视频号：加 --auto-channels-login
+
 # 立即全部发布
 python3 "$DIST_SCRIPT/distribute_all.py" --now
 ```
@@ -140,7 +142,7 @@ python3 "$DIST_SCRIPT/distribute_all.py" --now
 ### Phase 3：视频生产

 1. **视频切片**：转录 → 高光识别 → 批量切片 → 增强
-2. **多平台分发**：成片 → 5平台发布（定时排期）
+2. **多平台分发**：成片 → 5 平台发布（默认智能错峰定时）

 ### Phase 4：文章内容

@@ -167,7 +169,7 @@ python3 auto_log.py

 各平台 Cookie 文件位于 `credentials/cookies/` 目录。更新方式：

-1. **视频号**：浏览器登录后，使用 `cookie_manager.py` 提取
+1. **视频号**：`channels_login.py`（Cursor Simple Browser + 可选 CDP）；详见 `skills/多平台分发_SKILL.md`
 2. **B站**：使用 `bilibili-api-python` 自动获取
 3. **小红书/快手**：Playwright 自动化登录后提取

--- a/.cursor/skills/karuo-party/skills/多平台分发_SKILL.md
+++ b/.cursor/skills/karuo-party/skills/多平台分发_SKILL.md
@@ -3,18 +3,25 @@ name: 多平台分发
 description: >
  一键将视频分发到 5 个平台（抖音、B站、视频号、小红书、快手）。
  API 优先策略：视频号纯 API、B站 bilibili-api-python、抖音纯 API。
-  支持定时排期（第1条立即发，后续 30-120 分钟随机间隔）、并行分发、去重、失败自动重试。
+  支持定时排期（默认智能错峰；可选 legacy）、默认静默不弹窗登录、并行分发、去重、失败自动重试。
 triggers: 多平台分发、一键分发、全平台发布、批量分发、视频分发
 owner: 木叶
 group: 木
-version: "4.0"
-updated: "2026-03-11"
+version: "4.3"
+updated: "2026-03-23"
 ---

-# 多平台分发 Skill（v4.0）
+# 多平台分发 Skill（v4.3）

 > **核心原则**：API 发布为主，Playwright 为辅。确保确定性地分发到各平台。
-> **v4.0 变更**：视频号已切换为纯 API、统一元数据生成器、定时排期优化、简介/标签/分区自动填充。
+> **v4.3**：默认**静默**（不自动 `channels_login`）；需弹窗时 `--auto-channels-login` 或 `CHANNELS_AUTO_LOGIN=1`（独立脚本）。**v4.2**：智能排期与去重下标对齐。
+
+## 〇、执行原则（第一性原理）
+
+- **视频号两步**：先扫码落盘 Cookie 再上传；`video_channels_resume.py` **默认弹 Chromium 窗**扫码，扫完再继续传；`--silent-login` 无头。
+- **目标优先**：全平台分发 → 直接 `distribute_all.py`；视频号助手态需**事先**手动 `channels_login.py` 或显式 `--auto-channels-login`。
+- **Cookie 优先**：登录成功必须落盘；视频号双路径同步见 `cookie_manager.sync_channels_cookie_files`。
+- **默认静默**：无人值守跑命令时不弹浏览器。

 ---

@@ -32,6 +39,8 @@ updated: "2026-03-11"
 > 按《视频号与腾讯相关 API 整理》结论，微信官方目前**没有开放「短视频上传/发布」接口**；本 Skill 中的视频号发布能力，属于对 `https://channels.weixin.qq.com` 视频号助手网页协议的逆向封装（DFS 上传 + `post_create`），仅在你本机使用，需自行承担协议变更与合规风险。  
 > 官方可控能力（直播记录、橱窗、留资、罗盘数据、本地生活等）的服务端 API 入口为：`https://developers.weixin.qq.com/doc/channels/api/`，如需做直播/橱窗/留资集成，可基于该文档在单独 Skill 中扩展。

+> **「视频号 API token」与成片上传**：公众号 **`access_token`** **不能**替代视频号助手网页态；`channels_api_publish` 依赖 **`channels_storage_state.json`**。127 场静默全平台：`python3 distribute_all.py --video-dir "/Users/karuo/Movies/soul视频/第127场_20260318_output/成片"`（须各平台 Cookie 已就绪）。
+
 ---

 ## 二、一键命令
@@ -39,9 +48,12 @@ updated: "2026-03-11"
 ```bash
 cd /Users/karuo/Documents/个人/卡若AI/03_卡木（木）/木叶_视频内容/多平台分发/脚本

-# 定时排期：第1条立即，后续 30-120min 随机间隔
+# 默认智能错峰排期
 python3 distribute_all.py

+# 旧版随机间隔
+python3 distribute_all.py --legacy-schedule
+
 # 立即全部发布
 python3 distribute_all.py --now

@@ -54,24 +66,30 @@ python3 distribute_all.py --video-dir "/path/to/videos/"
 # 检查 Cookie / 重试失败
 python3 distribute_all.py --check
 python3 distribute_all.py --retry
+
+# 需要脚本自动弹窗扫视频号（默认不弹）
+python3 distribute_all.py --platforms 视频号 --auto-channels-login --video-dir "/path/to/成片"
+# 独立 channels_api_publish 允许自动登录：CHANNELS_AUTO_LOGIN=1
+# 强制永不自动登录：NO_AUTO_CHANNELS_LOGIN=1
 ```

 ---

-## 三、定时排期（v4.0 优化）
+## 三、定时排期（v4.2+）

-### 3.1 排期规则
- **第 1 条**：立即发布（`first_delay=0`）
- **第 2 条起**：前一条 + random(30, 120) 分钟
- 若总跨度 > 24h，自动按比例压缩
- 12 条视频典型跨度 ~10-14h
+### 3.1 默认（`generate_smart_schedule`）
+- 第 1 条立即；间隔与总跨度随条数自适应；本地 0–7 点尽量挪到午间（`SCHEDULE_NO_NIGHT_REFINE=1` 关闭）
+- `--legacy-schedule` + `--min-gap` / `--max-gap` / `--max-hours` 为旧逻辑
+- 去重时排期与目录列表下标对齐

-### 3.2 各平台定时实现
+### 3.2 独立 `channels_api_publish.py`：同上智能排期转 Unix
+
+### 3.3 各平台定时实现

 | 平台 | 定时方式 | 参数 |
 |------|----------|------|
 | B站 | API `meta.dtime` | Unix 时间戳（秒） |
-| 视频号 | API 暂不支持原生定时 | 描述中标注时间/手动设置 |
+| 视频号 | API `postTimingInfo.postTime`（秒级 Unix）；首条若时间过近则立即发 | `channels_api_publish._scheduled_ts_for_channels` |
 | 抖音 | API `timing_ts` | Unix 时间戳 |
 | 快手 | Playwright UI | `schedule_helper.py` |
 | 小红书 | Playwright UI | `schedule_helper.py` |
@@ -91,12 +109,12 @@ meta.description("B站")    # 标题 + 标签 + 品牌标记
 meta.tags_str("B站")       # AI工具,效率提升,Soul派对,...
 meta.bilibili_meta()       # B站投稿完整 meta（含 tid/tag/desc）
 meta.title_short()         # 小红书短标题（≤20字）
-meta.hashtags("视频号")    # #AI工具 #效率提升 ... #小程序 卡若创业派对
+meta.hashtags("视频号")    # … + #小程序卡若创业派对 #公众号卡若-4点起床的男人
 ```

 ### 4.1 内容结构
 - **标题**：手工优化标题库优先，否则从文件名智能提取
- **简介**：标题 + 换行 + 话题标签 + `#小程序 卡若创业派对`
+- **简介**：标题 + 换行 + 话题标签；**视频号**固定追加 `#小程序卡若创业派对` `#公众号卡若-4点起床的男人`（其它平台仍为 `#小程序 卡若创业派对`）
 - **标签**：基于关键词匹配（AI/创业/副业/Soul 等 12 类）+ 通用标签
 - **分区**：B站 tid=160（生活>日常）
 - **风控过滤**：`content_filter.py` 自动替换敏感词（70+ 映射，严格/宽松分级）
@@ -122,8 +140,11 @@ meta.hashtags("视频号")    # #AI工具 #效率提升 ... #小程序 卡若创
 `cookie_manager.py` 统一管理：
 - 中央存储：`多平台分发/cookies/{平台}_cookies.json`
 - 自动迁移：旧路径 → 中央存储（首次使用时）
- API 预检：5 平台各自 auth API 校验有效性
- 防重复登录：有效 Cookie 不触发重新获取
+- **视频号双路径**：预检读中央、发布读 legacy；`sync_channels_cookie_files()` 按 **mtime 新者覆盖旧者**，避免两份不一致
+- **登录后必存**：`channels_login.py` 保存 `channels_storage_state.json` 后 **立即 copy** 到 `cookies/视频号_cookies.json`
+- **登录页只在 Cursor 内**：`channels_login.py` v7 用 `cursor://vscode.simple-browser/show?url=…` 打开 **Simple Browser**，不用系统默认浏览器；**无额外 Chromium** 时需 Cursor 带 `--remote-debugging-port=9223`（或 `CHANNELS_CDP_URL`），脚本 CDP 附着后导出会话；否则 **自动回退** 本机 Chromium 仅用于写 Cookie（`--playwright-only` 强制只走 Chromium）。
+- **视频号登录**：默认不自动执行 `channels_login.py`；需要时加 `--auto-channels-login`（或事先手动登录）
+- API 预检：各平台 auth API 校验有效性

 ---