Pawcast 详细功能规格

这份文档是 Pawcast v0.1 MVP 的完整功能规格说明。每个模块的字段、状态机、数据流、技术细节都展开讲清楚，目的是让合伙人/工程团队可以拿这份文档直接开发，不需要二次确认。

00产品概览

把 4 件团播运营的核心事变成 1 个桌面 App。

目标用户

Pawcast 服务于 TikTok 团播主持人 / 公会运营 / 中型直播工作室。这类用户的典型画像：

• 同时管理 3-10 位主播，每周开播 4-7 场，每场 90-180 分钟
• 主要分布在 日韩 / 东南亚 / 北美（亚洲东京时段 / GMT-5 北美黄金时段）
• 已经在用 MCAStar 类计票器、TikTok Live Studio、OBS、自建 Excel 报表的混合工作流
• 付费意愿强（已经在为 MCA 付 ¥18,000 ~ ¥88,000 JPY/年）
• 对数据所有权敏感（不希望关键运营数据上传到第三方云）
• 对 AI 工具有兴趣但担心被风控（特别是私信场景）

范围与原则（v0.1 MVP）

包含：4 个核心模块（计票 / 探索 / 私信 / 监控）+ Dashboard + 设置中心 + 14 天试用流程。

不包含：直播开播工具（OBS / Live Studio 替代）、视频剪辑、内容素材库、薪酬计算、合同管理。

01计票器 Vote Counter

完整对标 MCAStar，5 种玩法 + 4 个直播挂件 + 单礼物绑定 + 互动投票。

1.1 五种玩法引擎

1.1.1 Sticker Dance · 贴纸舞

主打玩法。N×M 网格（默认 6×3），每格绑定一个礼物 + 一段舞名。观众送对应礼物即点亮格子。

1.1.2 Duel Dance · 攻守擂

守 vs 攻，1v1 PK，胜者连胜留场。

1.1.3 Multi-PK · 多人对战

3-5 主播同时登台，多色进度条横向并列。候补区可拖拽换人。

1.1.4 Solo Stage · Solo 舞台

单人轮换上台。自由 / 阶段两种子模式。

1.1.5 Freedom · 自由模式

传统单主播轮换，所有礼物直接计票。最简规则，适合新团首播。

1.2 礼物绑定机制

这是 Pawcast 区别于"礼物按面值直接计入"的关键机制，源自 MCAStar 首创但允许两种模式切换。

单礼物绑定（默认）

1. 每位主播预先绑定一个"代表礼物"（例如 Yoochan → 🎮 Joystick / Sian → 🍦 Ice Cream）
2. 观众首次送出某主播的代表礼物 → 自动建立 user_id → broadcaster_id 绑定
3. 之后该用户送出的任何礼物都自动归属该主播（粉丝礼物 Heart Me 也会加票）
4. 同场内不可改绑（防止刷榜）；跨场可重新绑定

多礼物绑定（兼容传统模式）

1. 每位主播可绑定多个礼物（如团 A 绑定 Rose + Bouquet + 玫瑰花束）
2. 礼物归属严格按礼物类型，不跟踪用户
3. 用户送其他礼物则进入"未分配"池，主持人手动分配

未分配礼物的处理

• 手动绑定：主持人点击具体某条记录，分给特定主播
• 全部分给守 / 全部分给攻：批量操作（仅 Duel Dance）
• 单次分配：仅本次记录归属，不建立用户绑定
• 放弃分配：保留为未分配，最终计入 unallocated 总数

1.3 互动投票（评论 + 点赞 → 票）

把非送礼互动也转化为主播票数。

1.4 挂件输出

所有挂件都是独立的 HTML 页面，由 Pawcast 主进程托管在本地端口。OBS / Live Studio 通过浏览器源加载 URL：

# 主玩法挂件
http://127.0.0.1:17777/widget/sticker_dance?preset=2&ws=main
http://127.0.0.1:17777/widget/duel_dance?preset=3&skin=mca
http://127.0.0.1:17777/widget/multi_pk?preset=4
http://127.0.0.1:17777/widget/solo_stage?preset=5
http://127.0.0.1:17777/widget/freedom?preset=6

# 共通挂件
http://127.0.0.1:17777/widget/ranking?scope=total&top=10
http://127.0.0.1:17777/widget/user_round_rank?top=5

# Extras 挂件
http://127.0.0.1:17777/widget/profile_border?id=1&skin=7&label=TOP1
http://127.0.0.1:17777/widget/voting_tool?id=1
http://127.0.0.1:17777/widget/lucky_game?config=2
http://127.0.0.1:17777/widget/lucky_fans

挂件 → 主进程通信：每个挂件页面通过 WebSocket（ws://127.0.0.1:17777/ws/widget/<type>/<preset>）订阅实时数据，主进程推送增量事件，挂件自己做动画渲染。

1.5 玩法状态机

所有玩法（除 Freedom 外）共用同一状态机：

1.6 数据导出

02探索主播 Explorer

从 TikTok 公开页面挖掘潜力主播 + AI 多维度评分 + 一键发起邀约。

2.1 采集流水线

2.2 七维度评分

综合分（0-100）= Σ(维度分 × 权重)，≥ 80 即进入"高潜池"。

2.3 主播档案字段

03私信中心 DM Center

AI 起草 + 人工审核 + 速率限制 + 模板库 + 漏斗追踪。

3.1 AI 起草流程

1. 从探索池 / 主播档案触发 → "发起邀约"按钮
2. 系统 prefill：取该主播的 7 维度分 + 风格标签 + 近期视频内容描述
3. 选择模板（首次邀约 / 跟进 / 面试 / 感谢）
4. 调用 LLM（默认 Claude Sonnet，可切 GPT-4o / Qwen Plus）：Prompt = 模板骨架 + 主播 metadata + 工作室介绍 + 风格匹配点
5. AI 在变量插槽填值（不重写模板结构）：{name} {studio} {topic} {match_point}
6. 呈现给主持人 → 编辑 / 采纳 / 跳过 / 换一个
7. 采纳后进入发送队列（不立即发，等待速率窗口）
8. 发送后跟踪：已发 → 已读 → 已回复 → 已签约 / 已拒绝
9. 未读 4h 自动触发跟进策略（再次 AI 起草跟进消息，等主持审核）

3.2 速率限制 / 风控规避

3.3 漏斗追踪

每条 DM 都有完整生命周期 timeline：

{
  "dm_id": "dm_5f8a2b",
  "to": "@mira.k_official",
  "template": "first_invite_warm",
  "timeline": [
    {"event": "drafted", "by": "ai", "at": "2026-05-02T21:20:00"},
    {"event": "approved", "by": "operator_jp", "at": "2026-05-02T21:21:30"},
    {"event": "queued", "at": "2026-05-02T21:21:30"},
    {"event": "sent", "at": "2026-05-02T21:24:12"},
    {"event": "read", "at": "2026-05-02T21:31:45"},
    {"event": "replied", "at": "2026-05-02T21:38:02"}
  ],
  "outcome": "signed"
}

04直播监控 Live Monitor

同时盯 8+ 团员直播间 · 30s 巡检 · PK 战役自动追踪 · 跨房观众分析。

4.1 巡检策略

• 30 秒巡检：每 30s 拉一次https://www.tiktok.com/@username/live，判断 LIVE / OFFLINE
• WS 长连：LIVE 房间立即建立 tiktok-live-connector WebSocket，订阅 GiftEvent / ChatEvent / LikeEvent / PKEvent
• 断线重连：指数退避 1s → 2s → 5s → 10s，最多 5 次失败则降级回到 30s 巡检
• OFFLINE 转 LIVE：检测到 LIVE 立即建 WS + 通知主持人
• LIVE 转 OFFLINE：WS 断开 + 30s 内未重连 + 巡检确认离线 → 标记 OFFLINE 并记录下播时间

4.2 PK 战役追踪

TikTok 的 PK 是直播内嵌战役，事件类型 LinkMicBattlePunishEvent / LinkMicBattleEvent。Pawcast 自动识别 + 跟踪：

4.3 事件流字段

实时事件流（Bloomberg 风格）展示在右侧栏：

[21:30:14] ⚔️  Uni 进入 PK · vs @hopecore.kr
[21:29:58] 🌌 Yoochan 收到 Galaxy ×1 (¥150) by @taro_pop
[21:29:12] ⏹️  Bubbloom 下播 · 持续 1h22m
[21:28:40] 🎉 Link8 观众破 8K
[21:28:02] 🏆 Mochi 进入 PK 胜场 · 连胜 3

事件类型：gift / chat_burst / pk_start / pk_end / pk_score / room_live / room_offline / milestone / streak / alert。

05Dashboard 总览

一眼看完今天的团播状态。

4 大数据卡 + 当前场次摘要 + 今日礼物 TOP5 + 主播在播 + 探索发现 + 系统健康。

数据来源

• 正在直播：来自 Live Monitor，每 5s 推到 Dashboard
• 当前观众：所有在播间观众数求和（去重）
• 今日礼物币：当日 0:00 至今所有礼物的金币总和
• 私信送达 / 待回：来自 DM Center 的 funnel 计数
• 当前场次：来自计票器最近 active 预设
• 礼物 TOP5：当日跨房间礼物聚合排序
• 系统健康：采集线路状态 / WS 平均延迟 / 授权剩余天数 / 缓存大小

06技术架构

Electron + Bun + React + SQLite，全栈 TypeScript。

6.1 技术栈

6.2 数据库 Schema（核心表）

-- 主播 / 团员（含探索池中的潜在主播 + 已签约主播）
CREATE TABLE broadcasters (
  id          INTEGER PRIMARY KEY,
  tt_user_id  TEXT UNIQUE NOT NULL,
  username    TEXT,
  display     TEXT,
  avatar_url  TEXT,
  status      TEXT,    -- discovered / contacted / signed / churned
  scores_json TEXT,    -- 7 维度评分
  tags_json   TEXT,
  created_at  INTEGER,
  updated_at  INTEGER
);

-- 直播会话（一次开播 = 一个 session）
CREATE TABLE live_sessions (
  id           INTEGER PRIMARY KEY,
  broadcaster_id INTEGER,
  tt_room_id   TEXT,
  start_at     INTEGER,
  end_at       INTEGER,
  preset_id    INTEGER,    -- 关联玩法预设
  total_gifts  INTEGER,
  total_coins  INTEGER,
  peak_viewers INTEGER
);

-- 礼物事件（单条记录）
CREATE TABLE gift_events (
  id           INTEGER PRIMARY KEY,
  session_id   INTEGER,
  user_id      TEXT,
  user_name    TEXT,
  gift_id      TEXT,
  gift_name    TEXT,
  count        INTEGER,
  coins        INTEGER,
  bound_to     INTEGER,    -- 绑定到哪位主播
  binding_type TEXT,    -- single_gift / multi_gift / manual / unallocated
  ts           INTEGER
);
CREATE INDEX idx_gift_session ON gift_events(session_id);
CREATE INDEX idx_gift_user ON gift_events(user_id);

-- 玩法预设
CREATE TABLE presets (
  id        INTEGER PRIMARY KEY,
  name      TEXT,
  mode      TEXT,    -- sticker_dance / duel / multi_pk / solo / freedom
  config_json TEXT,
  cast_json   TEXT,    -- 主播槽位 + 礼物绑定
  is_active   INTEGER,
  updated_at  INTEGER
);

-- DM 邀约
CREATE TABLE dms (
  id           INTEGER PRIMARY KEY,
  to_broadcaster INTEGER,
  template     TEXT,
  draft        TEXT,
  final        TEXT,
  timeline_json TEXT,
  outcome      TEXT,
  created_at   INTEGER
);

-- PK 战役
CREATE TABLE pk_battles (...);
-- 模板库
CREATE TABLE dm_templates (...);
-- 用户档案（送礼者）
CREATE TABLE tt_users (...);
-- 互动事件
CREATE TABLE chat_events (...);
CREATE TABLE like_events (...);

6.3 IPC 协议（主 ↔ 渲染 / 挂件）

3 个通道：

• Electron IPC（主进程 ↔ 渲染进程）：通过 contextBridge 暴露 window.pawcast.invoke('namespace.method', args)。命名空间：vote / explore / dm / monitor / settings
• WebSocket（主进程 ↔ 挂件页面）：ws://127.0.0.1:17777/ws/widget/<type>/<id>，事件 ND-JSON：{type: 'vote_update', preset: 2, payload: {...}}
• HTTP REST（保留给将来挂件 SDK）：GET /api/snapshot 全量状态、GET /api/preset/:id 预设配置等

6.4 AI 调用

用户在设置中心填自己的 API Key。Pawcast 不抽成、不代付费。所有 AI 调用日志本地保存，便于审计成本。

07授权 / 设备管理

单设备授权 + 设备迁移流程。

• 每个授权同时只激活 1 台 PC
• 14 天免费试用 不限设备但限 1 直播间
• 授权周期：月 / 半年 / 年（不设永久买断，避免无后续支持的孤岛版本）
• 有效期从首次激活算起
• 设备迁移：原设备生成 8 位验证码（5 分钟有效）→ 新设备输入 → 旧设备失效。需满足：剩余有效期 ≥ 22 天 + 距上次迁移 ≥ 48 小时
• 每次迁移消耗 1 天有效期作为防滥用成本
• 月度套餐每次迁移收 ¥99；半年 / 年度套餐每季度免费 1 次

08隐私 / 数据所有权

原则

• TikTok 实时数据（礼物 / 评论 / 点赞 / 用户档案）100% 本地 SQLite，不上传任何 Pawcast 服务器
• 挂件数据仅在本地 127.0.0.1:17777 服务，OBS 加载是同机内通信
• AI 调用用用户自己的 API Key，请求直达 Anthropic / OpenAI / Qwen，Pawcast 不中转
• 授权校验每 24h 一次轻量校验（仅传授权 ID），不上传业务数据
• 错误日志默认本地，需用户主动同意才上传
• 使用统计仅匿名功能使用频次，便于产品改进，可在设置中关闭

用户能做什么

• 查看 / 导出 / 删除任何数据
• 注销账号会立即清除服务器侧的授权记录
• 本地数据库文件可用 SQLite Browser 直接打开
• 所有挂件 URL 可以本地 / 局域网 / ngrok 隧道，输出位置完全自主

09对比 MCAStar

10Roadmap

v0.1 · MVP（预计 2026-Q3 发布）

• 4 大模块完整功能（计票 5 种玩法 + 探索 + 私信 + 监控）
• Dashboard + 设置中心
• 4 个 Extras 挂件（Profile Border / Voting Tool / Lucky Game / Lucky Fans）
• Windows 10/11 NSIS 打包 + 数字签名
• 14 天试用 + 月/半年/年订阅

v0.3 · 工坊化（2026-Q4）

• 挂件 CSS 注入
• 多语言扩展（日韩越泰印越）
• 团员库导入 / 导出（与现有 MCA 配置兼容）
• 更多模板 / 玩法变体（社区贡献）
• 设置中心 LLM 模型 marketplace

v0.5 · 平台化（2027-Q1）

• macOS 版本
• 挂件 SDK + 挂件市场
• 多账号工作台（同公会多个工作室）
• 云端备份 / 多设备同步（可选 / 加密）
• API 开放给第三方集成

v1.0 · 生态化（2027 下半年）

• 挂件市场（开发者 + 用户分成）
• 多平台支持（除 TikTok 外，潜在 YouTube Live / IG Live / 抖音直播）
• 团播业务 SaaS（薪酬计算 / 合同 / 财务）

11未决 / 待讨论

以下事项 v0.1 spec 暂未确定，请合伙人评议：

1. 价格定价：¥698 / ¥3,288 / ¥5,888 是否合理？是否需要按团员数 / 房间数分级？
2. 免费试用机制：14 天 vs 7 天 vs 永久免费 limited 版（≤ 3 房间）？
3. AI 模型默认：默认接 Claude / GPT-4o / 自托管？需不需要内置一个低成本兜底（如 Qwen）？
4. 设备迁移成本：月度套餐 ¥99/次太贵？太便宜（容易滥用）？
5. 挂件托管：v0.1 仅本地 127.0.0.1，是否需要支持公网通过隧道暴露（方便远程主持）？
6. 数据导入：要不要做 MCAStar 配置导入工具，降低迁移门槛？工程成本预估 1-2 周
7. 账号体系：v0.1 用激活码 + 设备绑定（无登录账号）/ 还是搞简单的 email + 密码 + 多设备同步？
8. 风控暂停后：12h 是否合适？需要主持人手动确认才能恢复？
9. 试用版限制：1 直播间 / ≤50 DM/天 / 全功能？还是某些核心模块（比如 AI 起草）也限制？
10. Windows 优先 + Mac 后做：能接受 6-9 个月内 Mac 用户得用云桌面替代吗？还是必须并行做？