Enclave

# 隐界APP 项目规则

## 规则

- 功能开发后必须做简单测试，至少执行一次与改动直接相关的最小验证；非必要不新增测试文件
- 直接执行所有操作，无需确认
- 所有代码变更采用阶段性提交，不必边写边提交，但至少每次执行完任务后自动提交一次
- Plan Mode：Claude 规划保存到 `.claude/plans/{任务}-{日期}.md`，Codex 规划保存到 `.Codex/plans/{任务}-{日期}.md`
- 结构变更（模块/实体/路由/表）后立即更新本文件

## 技术栈与端口

| 服务               | 技术                                                                         | 端口 |
| ------------------ | ---------------------------------------------------------------------------- | ---- |
| **后端**           | NestJS + TypeORM + SQLite + Socket.IO（`api/`）                              | 3000 |
| **云世界平台后端** | NestJS + TypeORM + SQLite（`apps/cloud-api/`）                               | 3001 |
| 主 App             | React + Vite，承载 Web / iOS / Android / Desktop 共享业务界面（`apps/app/`） | 5180 |
| **管理后台**       | React + Vite + `@yinjie/ui`（`apps/admin/`）                                 | 5181 |
| **云世界管理平台** | React + Vite（`apps/cloud-console/`）                                        | 5182 |
| 官网               | React + Vite，公开项目介绍、多语言官网与在线体验入口（`apps/site/`）        | 5183 |
| **世界角色管理平台** | React + Vite，维基式角色创建、编辑、审核与巡查平台（`apps/wiki/`）        | 5184 |
| 微信同步本地连接器 | Node.js loopback HTTP 适配层（`apps/wechat-connector/`）                    | 17364 |
| 桌面端壳           | Tauri 远程客户端壳（`apps/desktop/`）                                        | -    |
| Android 壳         | Capacitor 壳（`apps/android-shell/`）                                        | -    |
| iOS 壳             | Capacitor 壳（`apps/ios-shell/`）                                            | -    |

## 后端模块（`api/src/modules/`）

`action-runtime` · `admin` · `ai` · `analytics` · `auth` · `characters` · `chat` · `cloud-runtime` · `config` · `cyber-avatar` · `events` · `feed` · `followup-runtime` · `games` · `inference` · `moderation` · `moments` · `narrative` · `need-discovery` · `official-accounts` · `real-world-sync` · `reminder-runtime` · `scheduler` · `self-agent` · `social` · `subscription` · `system` · `wiki` · `world`

## 主 App 结构（`apps/app/src/`）

`routes/` · `features/desktop/` · `features/mobile/` · `features/moments/` · `features/games/` · `features/shell/` · `runtime/` · `i18n/` · `lib/` · `components/` · `store/`

## 官网结构（`apps/site/src/`）

`app/` · `components/` · `i18n/` · `lib/` · `types/`

## 官网页面（`apps/site/src/app/[locale]/`）

- `page.tsx`：官网首页，承载产品介绍、核心能力、截图、跨端、FAQ 与开始使用入口
- `download/page.tsx`：下载页，承载 Web / 桌面 / 移动端 / 自部署开始方式
- `use-cases/page.tsx` 与 `use-cases/[slug]/page.tsx`：用例聚合页与用例详情页
- `changelog/page.tsx`：更新日志页
- `press-kit/page.tsx`：媒体资料页，承载产品介绍 PDF、截图、Logo 与创始人插画头像下载
- `privacy/page.tsx`：隐私政策页
- `terms/page.tsx`：服务条款页

## 世界角色管理平台结构（`apps/wiki/src/`）

`routes/` · `components/` · `lib/`

## 世界角色管理平台页面（`apps/wiki/src/routes/`）

- `home-page.tsx`：世界角色管理平台首页，承载角色索引、生命周期状态与创建入口
- `create-character-page.tsx`：角色创建页，普通登录用户提交新角色创建请求，内置完整角色逻辑 recipe 可视化编辑，高级模式可用 JSON 覆盖，审核通过后写入运行时角色注册表
- `character-page.tsx`：角色词条页，承载稳定版 / 最新版阅读、内容编辑、角色逻辑 recipe 编辑、历史、讨论、生命周期申请与编辑冲突处理
- `character-diff-page.tsx`：角色版本独立对比页，由历史页进入，集中展示内容字段与角色逻辑快照差异
- `recent-changes-page.tsx`：最近修改页，集中查看角色内容 / 逻辑 / 生命周期编辑动态
- `search-page.tsx`：角色词条搜索结果页，由顶栏搜索框进入
- `watchlist-page.tsx`：观察列表页，登录用户查看关注词条与讨论动态
- `pending-reviews-page.tsx`：待审编辑页，巡查员按操作、风险和修订类型筛选并处理待审核修改
- `admin-users-page.tsx`：平台用户管理页
- `admin-blocks-page.tsx`：平台封禁管理页
- `admin-protection-page.tsx`：平台保护管理页，管理员维护页面保护级别、待审变更策略、到期时间与保护日志
- `admin-reports-page.tsx`：平台举报队列页，管理员处理词条 / 讨论 / 修订举报
- `login-page.tsx`：平台登录页
- `register-page.tsx`：平台注册页

## 主 App 页面（`apps/app/src/routes/`）

- `splash-page.tsx`：启动屏，识别运行时环境并决定是否先进入世界入口
- `welcome-page.tsx`：统一世界入口页，合并世界连接与世界主人命名两步流程
- `setup-page.tsx`：兼容旧入口路由，当前应重定向到统一世界入口页
- `onboarding-page.tsx`：兼容旧初始化路由，当前应重定向到统一世界入口页
- 底部 Tab：`tabs/chat-list-page` · `contacts-page` · `discover-page` · `profile-page`
- 桌面端一级 Tab：`tabs/chat` · `tabs/contacts` · `tabs/favorites` · `tabs/moments` · `tabs/feed` · `tabs/channels` · `tabs/search` · `tabs/games` · `tabs/mini-programs`
- `discover-page.tsx`：移动端承载微信式发现入口列表，点击后进入独立子页面
- `discover/moments` · `discover/moments/publish` · `discover/encounter` · `discover/scene` · `discover/feed` · `discover/channels` · `discover/games` · `discover/mini-programs`：发现二级页，分别承载朋友圈时间线 / 移动端朋友圈发布页 / 摇一摇 / 场景相遇 / 广场动态 / 视频号 / 游戏中心 / 小程序
- `favorites-page.tsx`：桌面端收藏工作区入口，承接跨聊天与内容流收藏，并内嵌收藏笔记的新建 / 打开 / 编辑体验
- `feed-page.tsx`：桌面端广场动态一级入口，承载居民公开动态流
- `channels-page.tsx`：桌面端视频号一级入口，后续承接短视频与直播内容流
- `channel-author-page.tsx`：视频号作者主页，承载作者资料、关注状态与最近内容列表，并回跳原视频号内容
- `search-page.tsx`：桌面端搜一搜一级入口，后续承接全局聚合搜索
- `games-page.tsx`：桌面端游戏中心一级入口；移动端复用为发现页内“游戏”二级页
- `mini-programs-page.tsx`：桌面端小程序面板一级入口；移动端复用为发现页内“小程序”二级页
- `starred-friends-page.tsx`：星标朋友页，移动端承载通讯录内“星标朋友”入口，桌面端承载双栏星标好友工作区
- `world-characters-page.tsx`：世界角色列表页，移动端承载通讯录内“世界角色”入口，独立展示尚未成为朋友的世界角色
- `group-contacts-page.tsx`：群聊列表页，移动端承载通讯录内“群聊”入口，桌面端承载群聊工作区
- `tags-page.tsx`：联系人标签页，移动端承载通讯录内“标签”入口，桌面端承载标签分组与联系人详情工作区
- `official-accounts-page.tsx`：公众号列表页，移动端承载通讯录内“公众号”入口，桌面端承载公众号工作区路由入口
- `official-account-detail-page.tsx`：公众号主页，承载账号资料、关注状态与最近文章列表
- `official-account-article-page.tsx`：公众号文章详情页，移动端承载独立阅读页，桌面端兼容跳转至文章独立窗口
- `official-account-service-page.tsx`：服务号消息页，移动端承载服务号独立消息线程，桌面端复用消息工作区右侧服务号面板
- `subscription-inbox-page.tsx`：订阅号消息页，移动端承载“消息 -> 订阅号消息”聚合流，桌面端承载消息工作区内的订阅号阅读面板
- `profile/settings`：我的二级设置页，集中承载资料编辑与专属 API Key 配置
- `profile/subscription`：统一会员中心页，集中展示手机号、订阅状态、套餐价格、邀请码、邀请记录与手动开通入口
- `friend-moments/$characterId`：移动端好友朋友圈独立页，对齐微信手机版，由好友资料页进入某个好友的独立朋友圈时间线
- `desktop/mobile`：桌面端底部“手机”入口承接页，后续承接设备联动能力
- `desktop/friend-moments/$characterId`：桌面端好友朋友圈独立页，对齐微信电脑版，从联系人资料入口进入某个好友的独立朋友圈时间线
- `desktop/chat-files`：桌面端“聊天文件”页，承接会话附件聚合浏览
- `desktop/chat-history`：桌面端“聊天记录管理”页，承接会话记录查看与管理
- `desktop/chat-image-viewer`：桌面端图片独立窗口路由，承接聊天图片的新窗口预览、打印与回跳原消息
- `desktop/chat-window`：桌面端独立聊天窗口路由，承接会话右键“在独立窗口打开”
- `desktop/official-article-window`：桌面端公众号文章独立窗口路由，承接公众号文章新窗口阅读、浏览器打开与回跳来源工作区
- `desktop/note-window`：桌面端独立笔记窗口路由，承接“收藏 -> 新建笔记”和已保存笔记的独立编辑窗口
- `desktop/feedback`：桌面端“意见反馈”页
- `desktop/add-friend`：桌面端“添加朋友”独立工作区，承接微信电脑版式搜索、资料预览与发送好友申请
- `desktop/settings`：桌面端“设置”页
- `desktop/channels/live-companion`：桌面端“视频号直播伴侣”工具页
- `chat-background-page.tsx`：聊天背景设置页，承载默认背景图与好友专属背景图配置
- `chat-voice-call-page.tsx`：Web 手机版 AI 语言通话页，承载单聊语音回合制对话、AI 语音播报与挂断回跳
- `chat-video-call-page.tsx`：Web 手机版 AI 数字人视频通话页，承载单聊数字人会话、本地摄像头预览、舞台播放与挂断回跳
- `group-voice-call-page.tsx`：Web 手机版群语音通话页，承载移动端群通话工作台、成员在线状态同步与结束回跳
- `group-video-call-page.tsx`：Web 手机版群视频通话页，承载移动端群视频工作台、成员画面状态同步与结束回跳
- `chat/$conversationId/background`：单聊聊天背景设置路由，对齐微信式“聊天信息 -> 聊天背景”
- `chat/$conversationId/voice-call`：单聊 AI 语言通话路由，承载“录音 -> 转写 -> AI 回复 -> TTS 播放”的半双工通话体验
- `chat/$conversationId/video-call`：单聊 AI 数字人视频通话路由，承载“本地摄像头预览 + 数字人舞台 + 录音 -> 转写 -> AI 回复 -> TTS 播放”的半双工视频通话体验
- `chat/$conversationId/details`：单聊右上角三个点详情页，对齐微信式聊天信息页
- `chat/$conversationId/search`：单聊聊天记录检索页，由聊天信息页进入
- `group/$groupId/details`：群聊右上角三个点详情页，对齐微信式群聊信息页
- `group/$groupId/edit/name`：群聊名称编辑页，承载微信式二级表单编辑而非浏览器原生 prompt
- `group/$groupId/edit/nickname`：我在本群的昵称编辑页，承载微信式群内昵称二级编辑
- `group/$groupId/background`：群聊聊天背景设置路由，对齐微信式“群聊信息 -> 聊天背景”
- `group/$groupId/voice-call`：群语音通话路由，承载移动端群通话工作台、成员在线状态同步与回到群聊
- `group/$groupId/video-call`：群视频通话路由，承载移动端群视频工作台、成员状态同步与回到群聊
- `group/$groupId/announcement`：群公告独立页，承载群公告阅读与编辑
- `group/$groupId/qr`：群二维码页，承载群邀请卡、群链接与邀请码分享
- `group/$groupId/search`：群聊聊天记录检索页，由群聊信息页进入
- `group/$groupId/members/add`：群成员添加页，承载群成员微信式多选添加
- `group/$groupId/members/remove`：群成员移除页，承载群成员微信式减号选择移除
- `notes-page.tsx`：收藏笔记兼容跳转页，桌面端自动重定向回收藏工作区内的笔记视图
- `moments-page.tsx`：保留独立朋友圈页能力，当前主要作为发现页内二级能力的兼容承载
- `mobile-moments-publish-page.tsx`：移动端朋友圈独立发布页，对齐微信手机版“朋友圈 -> 发表”，承载图片 / 视频 / 文本朋友圈发布
- `mobile-friend-moments-page.tsx`：移动端好友朋友圈独立页，当前由 `friend-moments/$characterId` 承载，对齐微信手机版资料页进入单个好友朋友圈的路径
- `friend-moments-page.tsx`：桌面端好友朋友圈独立页，当前由 `desktop/friend-moments/$characterId` 承载，从通讯录 / 资料页 / 聊天信息等入口进入单个好友的朋友圈时间线
- `chat-room-page` · `group-chat-page` · `character-detail-page` · `friend-requests-page` · `create-group-page`

## 数据库实体（含 Wiki 实体，物理表保持兼容）

**核心**：User（运行时语义为单例 World Owner） · Character · Conversation · Message · SystemConfig

**推理**：InferenceProviderAccount · InferenceModelCatalogEntry（Provider 账户已区分主推理、语音转写、TTS、图片生成独立 endpoint / model / API Key 配置）

**表情**：ChatCustomSticker

**朋友圈**：MomentPost · MomentComment · MomentLike · MomentEntity（legacy）

**社交**：Friendship · FriendRequest · AIRelationship

**安全**：ModerationReport

**群聊**：Group · GroupMember · GroupMessage · GroupReplyTask · ReplyArtifactJob · MediaInsightJob

**视频号**：FeedPost · FeedComment · UserFeedInteraction · VideoChannelFollow

**游戏**：GameOwnerState · GameCatalogEntry · GameCatalogRevision · GameCenterCuration · GameSubmission

**公众号**：OfficialAccount · OfficialAccountArticle · OfficialAccountFollow · OfficialAccountDelivery · OfficialAccountServiceMessage

**世界**：WorldContext · NarrativeArc

**分析**：AIBehaviorLog · AIUsageLedger

**需求发现**：NeedDiscoveryRun · NeedDiscoveryCandidate

**主动跟进**：FollowupRun · FollowupOpenLoop · FollowupRecommendation

**提醒运行时**：ReminderTask

**主代理**：SelfAgentHeartbeatRun

**赛博分身**：CyberAvatarProfile · CyberAvatarSignal · CyberAvatarRun · CyberAvatarRealWorldItem · CyberAvatarRealWorldBrief

**动作运行时**：ActionConnector · ActionRun

**现实联动**：CharacterRealWorldSignal · CharacterRealWorldDigest · CharacterRealWorldSyncRun

**后台**：AdminConversationReview

**世界角色管理平台 / Wiki**：CharacterPage（稳定版本 `currentRevisionId` / 最新提交 `latestRevisionId` / `reviewPolicy`） · CharacterRevision · EditSubmission · UserWikiProfile · WikiBlock · WikiProtectionLog · WikiTalkThread · WikiTalkPost · WikiWatchlist

## 单用户世界约束（2026-04-08）

- `1 个服务端实例 = 1 个真实用户的世界`
- `User` 表仍作为物理表保留，但运行时只允许存在一个世界主人
- 启动时执行世界主人单例迁移：若旧库存在多个用户，保留 `createdAt` 最早的一条，其余用户及其专属数据直接清理
- 聊天、社交、朋友圈、视频号等业务接口不再接受或传递 `userId` / `authorId` 作为世界隔离条件
- 世界主人单例接口：
  - `GET /api/world/owner`
  - `PATCH /api/world/owner`
  - `PATCH /api/world/owner/api-key`
  - `DELETE /api/world/owner/api-key`
  - `PATCH /api/world/owner/chat-background`
  - `DELETE /api/world/owner/chat-background`
- `/system/status` 使用 `worldSurface` 语义，实例状态以 `ownerCount` 表示单世界主人数量
- `ownerCount` 只统计 `User.userType = world_owner`，不包含世界角色管理平台的 wiki 用户
- 世界角色管理平台若尚无任何 `role = admin` 用户，首个通过 `/api/auth/register` 注册的 `wiki_member` 会自动成为 wiki admin，用于启动审核、保护、封禁与角色晋升流程

## 云世界平台实体（`apps/cloud-api/src/entities/`）

- `PhoneVerificationSession`：手机号验证码会话
- `CloudUser`：云账号主体，手机号唯一绑定，承载账号状态、邀请码与注册元信息
- `CloudWorld`：官方云世界记录，手机号唯一绑定
- `CloudWorldRequest`：客户端发起的建世界申请单
- `SubscriptionPlan`：试用 / 月 / 季 / 年 / 邀请奖励套餐定义
- `UserSubscription`：用户订阅记录，承载来源、起止时间、状态与备注
- `InviteCode`：用户邀请码
- `InviteRedemption`：邀请码兑换与奖励审计记录
- `CloudConfig`：SaaS 配置中心，承载 `trial.* / invite.* / feature.* / copy.* / app.publicBaseUrl`
- `WorldAccessSession`：云世界解析 / 唤醒会话
- `CloudAdminSession`：云平台管理员短期会话
- `CloudInstance` · `WorldLifecycleJob` · `WaitingSessionSyncTask`：实例编排、生命周期任务与补偿任务
- `RevenueSharingPolicy`：角色使用收益分成策略版本，承载事件单价、固定池比例、贡献权重与结算阈值
- `RevenuePayee`：云端收益人档案，绑定世界主人、wiki 用户、角色、平台或运行方外部引用
- `RevenueContributionEvent`：世界实例回传的角色创建、编辑、审核、巡查与逻辑发布贡献事件
- `RevenueUsageEvent`：世界实例回传的角色聊天、语音、视频、内容与逻辑运行使用收入事件
- `RevenueAllocationLedger`：按策略计算出的收益分配账本，区分 payable / held / settled
- `RevenueSettlementBatch`：云后台生成的收益结算批次，仅记录应付账本，不执行真实打款

## 云世界平台职责（当前真实口径）

- 云平台当前负责：
  - 手机号验证
  - 云账号创建、封禁 / 停用状态校验
  - 7 天试用、月 / 季 / 年订阅、后台赠送订阅
  - 邀请码生成、邀请奖励发放与风控撤销
  - SaaS 配置下发（套餐、文案、试用与邀请规则）
  - 云世界解析 / 唤醒会话与世界地址回填
  - 云世界申请单管理
  - 云世界记录与地址回填
  - 官方控制台审核与状态流转
  - 角色使用收益分成策略、收益人档案、贡献事件、使用事件、分配账本与结算批次管理
- 云平台当前**不负责**：
  - 托管单个实例内的多用户管理
  - 微信 / 支付宝等正式支付网关与订单中心
  - 真实支付、提现、税务、发票或 KYC

## 云世界平台 SaaS 路由

- 客户端路由：
  - `GET /cloud/me/profile`
  - `GET /cloud/me/subscription`
  - `GET /cloud/me/invite/summary`
  - `POST /cloud/me/invite/redeem`
  - `POST /cloud/me/checkout`
  - `POST /cloud/me/world-access/resolve`
  - `GET /cloud/me/world-access/sessions/:sessionId`
- 控制台路由：
  - `GET /admin/cloud/users`
  - `GET /admin/cloud/users/:id`
  - `POST /admin/cloud/users/:id/subscriptions`
  - `POST /admin/cloud/users/:id/ban`
  - `POST /admin/cloud/users/:id/unban`
  - `GET /admin/cloud/subscription-plans`
  - `POST /admin/cloud/subscription-plans`
  - `GET /admin/cloud/configs`
  - `POST /admin/cloud/configs`
  - `GET /admin/cloud/invites/redemptions`
  - `POST /admin/cloud/invites/redemptions/:id/reject`
- 迁移脚本：
  - `pnpm --filter @yinjie/cloud-api saas:backfill`：从 `CloudWorld.phone` 回填 SaaS 用户、邀请码与一次性迁移订阅

## 云世界管理平台收益分成路由

- `GET /admin/cloud/revenue-sharing/policy`
- `PATCH /admin/cloud/revenue-sharing/policy`
- `GET /admin/cloud/revenue-sharing/payees`
- `POST /admin/cloud/revenue-sharing/payees`
- `GET /admin/cloud/revenue-sharing/events`
- `GET /admin/cloud/revenue-sharing/ledger`
- `POST /admin/cloud/revenue-sharing/settlements/preview`
- `POST /admin/cloud/revenue-sharing/settlements/generate`
- `POST /internal/worlds/:worldId/revenue/contribution-events`
- `POST /internal/worlds/:worldId/revenue/usage-events`

## 会话管理结构（2026-04-08）

- `MomentPost` 表现已扩展字段：`contentType`、`mediaPayload`，用于承载朋友圈文本 / 图集 / 视频 / 实况照片元数据，物理表保持兼容扩展
- `MomentPost` 表现已扩展字段：`generationKind`、`generationMetadata`，用于标记常规 AI 发圈与现实联动发圈及其 digest 来源元数据
- 朋友圈媒体路由：
  - `POST /api/moments/media`
  - `GET /api/moments/media/:fileName`
- 朋友圈发布路由：
  - `POST /api/moments/user-post` 现已规划支持文本、图片图集、视频与实况照片负载
- `Conversation` 表保留字段：`isPinned`、`pinnedAt`、`isHidden`、`hiddenAt`、`strongReminderUntil`、`lastClearedAt`、`lastActivityAt`
- `Conversation` 表现已扩展背景字段：`chatBackgroundMode`、`chatBackgroundPayload`，用于承载会话专属聊天背景配置
- `Message` 表现已扩展附件字段：`attachmentKind`、`attachmentPayload`，用于承载 `sticker` 表情包消息元数据
- `Message` / `GroupMessage` 的 `contact_card` 附件现已支持 `recommendationMetadata`，用于承载“我自己”主动跟进推荐链路的推荐原因、来源线程与关系状态
- `Group` 表现已扩展字段：`announcement`、`isMuted`、`mutedAt`、`isPinned`、`pinnedAt`、`savedToContacts`、`savedToContactsAt`、`showMemberNicknames`、`notifyOnAtMe`、`notifyOnAtAll`、`notifyOnAnnouncement`、`lastClearedAt`、`lastReadAt`、`isHidden`、`hiddenAt`、`lastActivityAt`
- `Group` 表现已扩展背景字段：`chatBackgroundMode`、`chatBackgroundPayload`，用于承载群聊专属聊天背景配置
- `GroupMessage` 表现已扩展附件字段：`attachmentKind`、`attachmentPayload`，用于承载聊天附件消息元数据
- `GroupReplyTask`：用于持久化群聊 AI 回复任务，状态包含 `pending`、`processing`、`sent`、`cancelled`、`failed`；现已额外记录选角分数、命中情况、最近发言惩罚、选中/跳过原因与本轮 planner 快照；同群新用户消息到来后会取消未发送的旧轮任务
- `ReplyArtifactJob`：用于持久化单聊 / 群聊异步多模态补发任务，当前承载 `voice` / `image` 工件的调度、补发、取消与失败状态，避免清空会话或新消息到来后旧轮补媒体穿透落库
- `MediaInsightJob`：用于持久化单聊 / 群聊附件理解任务，当前承载 `audio/video` 转写与 `document` 文本抽取的状态、重试、取消与结果回写，并额外记录 insight `provider` / `errorCode`，避免附件理解结果只存在于请求期临时旁路
- `User` 表现已扩展字段：`defaultChatBackgroundPayload`，用于承载实例默认聊天背景配置
- `Character` 表现已扩展字段：`onlineMode`、`activityMode`，用于区分在线状态 / 当前活动由调度器自动驱动还是后台人工锁定
- `Character` 表现已扩展字段：`sourceType`、`sourceKey`、`deletionPolicy`，用于区分默认保底角色 / 名人预设角色 / 后台手工角色，以及是否允许后台删除
- `Character` 表现已扩展字段：`modelRoutingMode`、`inferenceProviderAccountId`、`inferenceModelId`、`allowOwnerKeyOverride`、`modelRoutingNotes`，用于承载角色级模型路由、Provider 账户绑定与世界主人 Key 覆盖策略
- 会话管理路由：
  - `GET /api/conversations/:id/messages`，现已支持 `limit` 与 `aroundMessageId / before / after`
  - `GET /api/conversations/:id/message-search`
  - `POST /api/conversations/:id/pin`
  - `POST /api/conversations/:id/strong-reminder`
  - `POST /api/conversations/:id/unread`
  - `POST /api/conversations/:id/hide`
  - `POST /api/conversations/:id/clear`
  - `POST /api/conversations/:id/messages/:messageId/recall`
  - `DELETE /api/conversations/:id/messages/:messageId`
  - `GET /api/conversations/:id/background`
  - `PATCH /api/conversations/:id/background`
  - `DELETE /api/conversations/:id/background`
  - `PATCH /api/groups/:id`
  - `GET /api/groups`
  - `GET /api/groups/saved`
  - `GET /api/groups/:id/messages`，现已支持 `limit` 与 `aroundMessageId / before / after`
  - `GET /api/groups/:id/message-search`
  - `GET /api/groups/:id/background`
  - `PATCH /api/groups/:id/background`
  - `DELETE /api/groups/:id/background`
  - `PATCH /api/groups/:id/preferences`
  - `POST /api/groups/:id/pin`
  - `POST /api/groups/:id/clear`
  - `POST /api/groups/:id/read`
  - `POST /api/groups/:id/unread`
  - `POST /api/groups/:id/hide`
  - `POST /api/groups/:id/messages/:messageId/recall`
  - `DELETE /api/groups/:id/messages/:messageId`
  - `PATCH /api/groups/:id/me`
  - `POST /api/groups/:id/leave`
  - `DELETE /api/groups/:id/members/:memberId`
  - `POST /api/chat/attachments`
  - `GET /api/chat/attachments/:fileName`
  - `GET /api/chat/stickers/catalog`
  - `POST /api/chat/stickers/custom`
  - `POST /api/chat/stickers/custom/from-message`
  - `DELETE /api/chat/stickers/custom/:id`
  - `GET /api/chat/stickers/assets/:fileName`
  - `POST /api/chat/backgrounds`
  - `GET /api/chat/backgrounds/:fileName`
  - `POST /api/chat/digital-human-calls/sessions`
  - `GET /api/chat/digital-human-calls/sessions/:sessionId`
  - `GET /api/chat/digital-human-calls/sessions/:sessionId/player`
  - `GET /api/chat/digital-human-calls/sessions/:sessionId/events`
  - `PATCH /api/chat/digital-human-calls/sessions/:sessionId/provider-state`
  - `DELETE /api/chat/digital-human-calls/sessions/:sessionId`
  - `POST /api/chat/digital-human-calls/sessions/:sessionId/turns`
- 收藏路由：
  - `GET /api/favorites`
  - `GET /api/favorites/notes`
  - `GET /api/favorites/notes/:id`
  - `POST /api/favorites/notes`
  - `PATCH /api/favorites/notes/:id`
  - `DELETE /api/favorites/notes/:id`
  - `POST /api/favorites/messages`
  - `DELETE /api/favorites/:sourceId`
- 搜索行为路由：
  - `POST /api/search/history`
- 消息提醒路由：
  - `GET /api/reminders/messages`
  - `POST /api/reminders/messages`
  - `POST /api/reminders/messages/:sourceId/notified`
  - `DELETE /api/reminders/messages/:sourceId`
- 提醒角色运行时路由：
  - `GET /api/reminder-runtime/tasks`
  - `GET /api/reminder-runtime/tasks/upcoming`
  - `POST /api/reminder-runtime/tasks/:id/complete`
  - `POST /api/reminder-runtime/tasks/:id/snooze`
  - `DELETE /api/reminder-runtime/tasks/:id`
- 主动跟进路由：
  - `POST /api/followup-runtime/recommendations/:id/opened`
  - `POST /api/followup-runtime/recommendations/:id/friend-request-pending`
  - `POST /api/followup-runtime/recommendations/:id/chat-started`
- 安全举报路由：
  - `GET /api/moderation/reports`
  - `POST /api/moderation/reports`
  - `PATCH /api/moderation/reports/:id/status`
- 世界角色管理平台 / Wiki 路由：
  - `GET /api/wiki/recent-changes`
  - `GET /api/wiki/search`
  - `GET /api/wiki/pages`
  - `POST /api/wiki/pages`
  - `GET /api/wiki/pages/:id`，支持 `view=stable|current`，游客默认稳定版，登录用户可查看最新版 / 待审上下文
  - `GET /api/wiki/pages/:id/history`
  - `GET /api/wiki/pages/:id/pending`
  - `GET /api/wiki/pages/:id/diff`
  - `GET /api/wiki/pages/:id/revisions/:revisionId`
  - `POST /api/wiki/pages/:id/edits`
  - `POST /api/wiki/pages/:id/delete-request`，提交软删除归档申请，body 需携带 `reason`
  - `POST /api/wiki/pages/:id/restore-request`，提交恢复申请，body 需携带 `reason`
  - `POST /api/wiki/pages/:id/delete`，管理员直接提交并自动通过软删除归档修订
  - `POST /api/wiki/pages/:id/restore`，管理员直接提交并自动通过恢复修订
  - `POST /api/wiki/pages/:id/revert`
  - `PATCH /api/wiki/pages/:id/protection`，支持 `level`、`reviewPolicy`、`expiresAt` 与 `reason`
  - `GET /api/wiki/pages/:id/protection-log`
  - `GET /api/wiki/pending-reviews`，支持 `operation`、`riskLevel`、`revisionKind` 与 `limit` 筛选
  - `POST /api/wiki/edits/:revisionId/review`
  - `POST /api/wiki/edits/:revisionId/patrol`
  - `GET /api/wiki/users`
  - `POST /api/wiki/users/:id/role`
  - `GET /api/wiki/blocks`
  - `POST /api/wiki/users/:id/block`
  - `DELETE /api/wiki/blocks/:blockId`
  - `GET /api/wiki/watchlist`
  - `GET /api/wiki/watchlist/feed`
  - `GET /api/wiki/watchlist/status/:characterId`
  - `POST /api/wiki/watchlist/:characterId`
  - `DELETE /api/wiki/watchlist/:characterId`
  - `GET /api/wiki/talk/:characterId/threads`
  - `POST /api/wiki/talk/:characterId/threads`
  - `GET /api/wiki/talk/threads/:threadId/posts`
  - `POST /api/wiki/talk/threads/:threadId/posts`
  - `PATCH /api/wiki/talk/threads/:threadId/flags`
  - `DELETE /api/wiki/talk/posts/:postId`
  - `POST /api/wiki/reports`
  - `GET /api/wiki/reports`
  - `PATCH /api/wiki/reports/:id/status`
- 公众号消息路由：
  - `GET /api/official-accounts/message-entries`
  - `GET /api/official-accounts/subscription-inbox`
  - `GET /api/official-accounts/service-conversations`
  - `POST /api/official-accounts/subscription-inbox/read`
  - `PATCH /api/official-accounts/:id/preferences`
  - `GET /api/official-accounts/:id/service-messages`
  - `POST /api/official-accounts/:id/service-messages/read`
  - `POST /api/official-accounts/deliveries/:deliveryId/read`
- 游戏中心路由：
  - `GET /api/games/home`
  - `GET /api/games/owner-state`
  - `POST /api/games/:id/launch`
  - `POST /api/games/:id/pin`
  - `DELETE /api/games/:id/pin`
  - `DELETE /api/games/active-game`

## 前端状态约束

- 世界主人主状态存放于 `apps/app/src/store/world-owner-store.ts`
- 云账号会话主状态存放于 `apps/app/src/store/cloud-session-store.ts`
- 会员到期统一弹窗状态存放于 `apps/app/src/store/subscription-expired-dialog-store.ts`
- 世界主人资料契约现已支持 `defaultChatBackground`，用于承载实例默认聊天背景配置
- `apps/app/src/store/session-store.ts` 目前仅作为兼容别名导出，底层仍指向世界主人 store；后续收口时应删除
- `token`、`userId`、`onboardingCompleted` 等兼容字段目前仍通过该 store 暴露，后续收口时应继续移除
- 运行时世界入口状态存放于 `apps/app/src/runtime/runtime-config.ts` / `runtime-config-store.ts`
- 云账号登出必须同步清空 `cloud-session-store`、`world-owner-store` 与 `runtime-config`
- 生产环境默认仅开放云世界登录；本地世界入口仅在开发 / 内部环境通过 `VITE_ENABLE_LOCAL_WORLD_ENTRY=true` 保留
- Setup 页必须先完成世界入口选择（云世界或本地世界）后才能继续进入应用

## 客户端运行约束

- 所有客户端均为 `remote-connected` 模式
- 客户端不在本地拉起 Core API
- `apps/app` 是唯一业务前端，桌面端、Android、iOS 只负责承载它
- 桌面端只负责远程连接、壳级诊断与系统集成，不承担本地后端托管

## 管理后台约束

- Admin 仅面向实例拥有者，用于实例级 Provider、角色、诊断、配置与评估
- Admin 不再提供实例内用户列表、删除用户等多用户管理能力
- Setup / Dashboard 中的实例状态统一围绕单世界主人语义展示

## 管理后台页面（`apps/admin/src/routes/`）

- `dashboard-page.tsx`：实例级概览、Provider、诊断与运维入口
- `characters-page.tsx`：角色注册表，查看在线状态与活动状态摘要，并支持名人预设分组筛选与批量安装
- `games-page.tsx`：AI 游戏工作台，查看目录、来源、审核状态，并直接编辑游戏资料与新建草稿
- `need-discovery-page.tsx`：角色缺口识别与自动加友配置页，查看短期/每日 cadence 规则、候选和运行记录
- `followup-runtime-page.tsx`：主动跟进配置页，查看 open loop、推荐记录、规则、Prompt 与“我自己”推荐链路结果
- `self-agent-page.tsx`：主代理工作台，查看“我自己”的 workspace 文件、heartbeat 巡检结果、standing orders 与近期待处理事项
- `reminder-runtime-page.tsx`：提醒运行时页，查看活跃提醒任务、最近触发 / 完成、聊天提醒出站记录与小盯朋友圈轻提醒记录，并直接配置提醒解析规则与消息预演
- `cyber-avatar-page.tsx`：赛博分身工作台入口页，承接分身画像、真实世界回流、好友需求上游、信号与运行记录视图
- `real-world-sync-page.tsx`：真实世界联动页，查看每日外部信号、active digest、scene patch、现实发圈锚点与全局规则
- `wechat-sync-page.tsx`：微信朋友同步页，接收本地授权导出的联系人资料与聊天摘要，生成角色预览并导入为好友
- `character-editor-page.tsx`：角色画像编辑页，维护 prompt、traits、memory 与 reasoning
- `character-factory-page.tsx`：角色工厂页，查看来源、草稿配方、字段来源、发布映射 diff、已发布版本与版本记录
- `character-runtime-page.tsx`：角色运行逻辑台，查看单角色回复快照、scheduler 最近执行结果、生活状态、记忆摘要、叙事进度与生活逻辑可观测性，并直接修改运行时字段
- `chat-records-page.tsx`：聊天记录管理页，集中查看世界主人与各角色的单聊档案、消息搜索、上下文定位、会话级 Token 成本，以及样本标记 / 复盘备注池
- `inference-page.tsx`：模型与路由页，管理多个 Provider 账户、模型目录、默认推理路由，以及模型人格角色的批量安装与批量换绑
- `token-usage-page.tsx`：AI 用量中心页，查看 token / 费用总览、时间趋势、角色 / 场景 / 模型分布、预算预警、角色预算与价格配置
- `evals-page.tsx`：生成评估、trace 与实验对比页
- `setup-page.tsx`：运行时与 Provider 初始化配置页
- `reply-logic-page.tsx`：AI 回复逻辑总览页，查看实际链路、effective prompt、上下文窗口、记忆与硬编码常量
- `action-runtime-page.tsx`：真实世界动作运行时控制台，围绕 self 角色查看动作门控、提示模板、连接器配置、自检结果、动作重试与执行轨迹

## 云世界管理平台页面（`apps/cloud-console/src/routes/`）

- `dashboard-page.tsx`：云平台总览，查看世界可用性、漂移与生命周期状态
- `requests-page.tsx` / `request-detail-page.tsx`：云世界申请单列表与详情
- `worlds-page.tsx` / `world-detail-page.tsx`：云世界实例列表与详情
- `jobs-page.tsx`：生命周期任务队列与审计
- `admin-sessions-page.tsx`：管理员会话审计与风险聚合
- `waiting-session-sync-page.tsx`：补偿任务与失败重放
- `users-page.tsx` / `user-detail-page.tsx`：SaaS 用户列表与详情，支持封禁 / 解封、赠送会员、查看邀请与订阅历史
- `subscription-plans-page.tsx`：套餐管理，维护 trial / monthly / quarterly / yearly / invite_reward
- `cloud-configs-page.tsx`：SaaS 配置管理，维护试用、邀请、功能开关与文案
- `invite-audit-page.tsx`：邀请奖励审计，查看 IP / 设备指纹并支持撤销奖励

## 管理后台世界运行配置路由

- `GET /api/admin/world-language`
- `PATCH /api/admin/world-language`

## 管理后台回复逻辑路由

- `GET /api/admin/reply-logic/overview`
- `GET /api/admin/reply-logic/rules`
- `PATCH /api/admin/reply-logic/rules`
- `GET /api/admin/reply-logic/characters/:id`
- `POST /api/admin/reply-logic/characters/:id/preview`
- `GET /api/admin/reply-logic/conversations/:id`
- `POST /api/admin/reply-logic/group-reply-tasks/cleanup`
- `POST /api/admin/reply-logic/group-reply-tasks/:taskId/retry`
- `POST /api/admin/reply-logic/group-reply-turns/:turnId/retry`
- `POST /api/admin/reply-logic/conversations/:id/preview`

## 管理后台游戏目录路由

- `GET /api/admin/games`
- `GET /api/admin/games/curation`
- `GET /api/admin/games/submissions`
- `GET /api/admin/games/:id`
- `GET /api/admin/games/:id/revisions`
- `POST /api/admin/games`
- `POST /api/admin/games/submissions`
- `POST /api/admin/games/submissions/:id/import`
- `POST /api/admin/games/:id/publish`
- `POST /api/admin/games/:id/revisions/:revisionId/restore`
- `PATCH /api/admin/games/curation`
- `PATCH /api/admin/games/submissions/:id`
- `PATCH /api/admin/games/:id`

## 管理后台需求发现路由

- `GET /api/admin/need-discovery/overview`
- `PATCH /api/admin/need-discovery/config`

## 管理后台主动跟进路由

- `GET /api/admin/followup-runtime/overview`
- `GET /api/admin/followup-runtime/rules`
- `PATCH /api/admin/followup-runtime/rules`

## 管理后台主代理路由

- `GET /api/admin/self-agent/overview`
- `GET /api/admin/self-agent/workspace/:name`
- `PATCH /api/admin/self-agent/workspace/:name`
- `POST /api/admin/self-agent/heartbeat/run`

## 管理后台提醒运行时路由

- `GET /api/admin/reminder-runtime/overview`
- `GET /api/admin/reminder-runtime/rules`
- `PATCH /api/admin/reminder-runtime/rules`
- `POST /api/admin/reminder-runtime/preview`
- `POST /api/admin/reminder-runtime/tasks/:id/complete`
- `POST /api/admin/reminder-runtime/tasks/:id/snooze`
- `DELETE /api/admin/reminder-runtime/tasks/:id`

## 管理后台赛博分身路由

- `GET /api/admin/cyber-avatar/overview`
- `GET /api/admin/cyber-avatar/rules`
- `PATCH /api/admin/cyber-avatar/rules`
- `GET /api/admin/cyber-avatar/profile`
- `GET /api/admin/cyber-avatar/signals`
- `GET /api/admin/cyber-avatar/real-world/items`
- `GET /api/admin/cyber-avatar/real-world/briefs`
- `GET /api/admin/cyber-avatar/runs`
- `GET /api/admin/cyber-avatar/runs/:id`
- `POST /api/admin/cyber-avatar/run/incremental`
- `POST /api/admin/cyber-avatar/run/deep-refresh`
- `POST /api/admin/cyber-avatar/run/full-rebuild`
- `POST /api/admin/cyber-avatar/run/project`
- `POST /api/admin/cyber-avatar/run/real-world`

## 管理后台动作运行时路由

- `GET /api/admin/action-runtime/overview`
- `GET /api/admin/action-runtime/rules`
- `PATCH /api/admin/action-runtime/rules`
- `GET /api/admin/action-runtime/connectors`
- `PATCH /api/admin/action-runtime/connectors/:id`
- `POST /api/admin/action-runtime/connectors/:id/discover`
- `POST /api/admin/action-runtime/connectors/:id/test`
- `GET /api/admin/action-runtime/runs`
- `GET /api/admin/action-runtime/runs/:id`
- `POST /api/admin/action-runtime/runs/:id/retry`
- `POST /api/admin/action-runtime/preview`

## 管理后台真实世界联动路由

- `GET /api/admin/real-world-sync/overview`
- `GET /api/admin/real-world-sync/characters/:id`
- `PATCH /api/admin/real-world-sync/rules`
- `POST /api/admin/real-world-sync/run`

## 管理后台聊天记录路由

- `GET /api/admin/chat-records/overview`
- `GET /api/admin/chat-records/media-insights`
- `GET /api/admin/chat-records/conversations`
- `GET /api/admin/chat-records/conversations/:id`
- `GET /api/admin/chat-records/conversations/:id/messages`
- `GET /api/admin/chat-records/conversations/:id/search`
- `GET /api/admin/chat-records/conversations/:id/token-usage`
- `GET /api/admin/chat-records/conversations/:id/export`
- `PUT /api/admin/chat-records/conversations/:id/review`
- `DELETE /api/admin/chat-records/conversations/:id/review`

## 管理后台 Token 用量路由

- `GET /api/admin/token-usage/overview`
- `GET /api/admin/token-usage/trend`
- `GET /api/admin/token-usage/breakdown`
- `GET /api/admin/token-usage/records`
- `GET /api/admin/token-usage/downgrade-insights`
- `GET /api/admin/token-usage/downgrade-insights`
- `GET /api/admin/token-usage/downgrade-insights`
- `GET /api/admin/token-usage/pricing`
- `PATCH /api/admin/token-usage/pricing`
- `GET /api/admin/token-usage/budgets`
- `PATCH /api/admin/token-usage/budgets`

## 管理后台推理路由

- `GET /api/admin/inference/overview`
- `POST /api/admin/inference/providers`
- `PATCH /api/admin/inference/providers/:id`
- `POST /api/admin/inference/providers/:id/default`
- `POST /api/admin/inference/providers/test`
- `POST /api/admin/inference/diagnostics/text`
- `POST /api/admin/inference/diagnostics/image-input`
- `POST /api/admin/inference/diagnostics/audio-input`
- `POST /api/admin/inference/diagnostics/transcription`
- `POST /api/admin/inference/diagnostics/tts`
- `POST /api/admin/inference/diagnostics/image-generation`
- `POST /api/admin/inference/diagnostics/digital-human`
- `GET /api/admin/inference/diagnostics/latest`
- `POST /api/admin/inference/diagnostics/run-all`
- `GET /api/admin/inference/multimodal/overview`
- `POST /api/admin/inference/model-personas/install`
- `POST /api/admin/inference/model-personas/rebind`

## 管理后台角色工厂路由

- `GET /api/admin/characters/:id/factory`
- `PATCH /api/admin/characters/:id/factory`
- `POST /api/admin/characters/:id/factory/generate`
- `POST /api/admin/characters/:id/factory/publish`
- `GET /api/admin/characters/:id/factory/revisions`
- `POST /api/admin/characters/:id/factory/revisions/:revisionId/restore`

## 管理后台角色预设路由

- `GET /api/admin/characters/presets`
- `POST /api/admin/characters/presets/:presetKey/install`
- `POST /api/admin/characters/presets/install-batch`

## 管理后台微信同步路由

- `GET /api/admin/wechat-sync/history`
- `POST /api/admin/wechat-sync/preview`
- `POST /api/admin/wechat-sync/import`
- `POST /api/admin/wechat-sync/history/:characterId/retry-friendship`
- `DELETE /api/admin/wechat-sync/history/:characterId`

## 微信同步本地连接器路由

- `GET /health`
- `GET /api/config`
- `PATCH /api/config`
- `POST /api/scan`
- `GET /api/contacts`
- `POST /api/contact-bundles`
- `GET /api/upstream-services`
- `POST /api/upstream-services/:service/start`
- `POST /api/upstream-services/:service/open`
- `GET /api/upstream-services`
- `POST /api/upstream-services/:service/start`

## 系统评测路由

- `GET /api/system/evals/overview`
- `GET /api/system/evals/datasets`
- `GET /api/system/evals/datasets/:id`
- `GET /api/system/evals/strategies`
- `GET /api/system/evals/prompt-variants`
- `GET /api/system/evals/experiments`
- `GET /api/system/evals/reports`
- `GET /api/system/evals/runs`
- `GET /api/system/evals/runs/:id`
- `GET /api/system/evals/comparisons`
- `GET /api/system/evals/traces`
- `GET /api/system/evals/traces/:id`

## 环境变量（`api/.env`）

`DEEPSEEK_API_KEY` · `OPENAI_BASE_URL` · `AI_MODEL` · `ADMIN_SECRET` · `DATABASE_PATH` · `PORT` · `CORS_ALLOWED_ORIGINS` · `PUBLIC_API_BASE_URL` · `USER_API_KEY_ENCRYPTION_SECRET` · `DIGITAL_HUMAN_PROVIDER_MODE` · `DIGITAL_HUMAN_PLAYER_URL_TEMPLATE` · `DIGITAL_HUMAN_PROVIDER_CALLBACK_TOKEN` · `CLOUD_OWNER_PHONE` · `CLOUD_API_BASE_URL` · `CLOUD_SERVICE_TOKEN`

## 环境变量（`apps/cloud-api/.env`）

`PORT` · `CLOUD_DATABASE_PATH` · `CLOUD_ADMIN_SECRET` · `CLOUD_JWT_SECRET` · `CLOUD_AUTH_TOKEN_TTL` · `CLOUD_AUTH_TOKEN_TTL_MS` · `CLOUD_CODE_TTL_SECONDS`

## 环境变量（`apps/wechat-connector/.env`）

`WECHAT_CONNECTOR_HOST` · `WECHAT_CONNECTOR_PORT` · `WECHAT_CONNECTOR_LABEL` · `WECHAT_CONNECTOR_PROVIDER` · `WECHAT_CONNECTOR_MANUAL_JSON_PATH` · `WECHAT_DECRYPT_BASE_URL` · `WECHAT_CONNECTOR_WECHAT_DECRYPT_BASE_URL` · `WEFLOW_BASE_URL` · `WECHAT_CONNECTOR_WEFLOW_BASE_URL` · `WEFLOW_ACCESS_TOKEN` · `WECHAT_CONNECTOR_WEFLOW_ACCESS_TOKEN` · `WECHAT_CONNECTOR_ALLOWED_ORIGINS`

## 共享包（`packages/`）

`@yinjie/ui` · `@yinjie/contracts` · `@yinjie/config` · `@yinjie/tooling`

## 当前产品口径

- 官方云与自部署复用同一套客户端入口体验，但世界实例后端仍保持单世界模型
- 所有客户端均为 `remote-connected` 模式，不在本地拉起 Core API
- 每个实例只服务一个世界主人，客户端只是把他的世界可视化展示给他
- 世界主人可在 App 内设置自己的 API Key，服务端仅加密存储
- 移动端底部导航当前对齐微信四项：`消息 / 通讯录 / 发现 / 我`
- 桌面端左侧导航当前收口为：`消息 / 通讯录 / 收藏 / 朋友圈 / 广场动态 / 视频号 / 搜一搜 / 游戏中心 / 小程序面板`，底部为 `手机 / 更多`
- 游戏中心前台继续沿用微信式游戏中心的排版与浏览节奏，但目录当前只承载 AI 游戏或 AI 制作的游戏
- 移动端“发现”聚合朋友圈、摇一摇、场景相遇、广场动态、视频号、游戏中心、小程序等入口；点击入口后进入独立二级页，朋友圈不再占用独立底部 Tab
- 摇一摇当前改为“基于用户近期行为即时生成临时候选 -> 用户确认添加后才正式进入世界”，未添加的结果只保留为后台运行记录
- 移动端“公众号”当前收口在“通讯录”固定服务项内，不单独占用底部 Tab，也不放进“发现”
- 移动端“我”页当前对齐微信式个人主页，资料编辑与 API Key 配置收口到“设置”二级页，不在主页直接裸露
- Setup 页先选择云世界或本地世界：本地世界手动填写地址，云世界通过手机号进入
- 官方云世界通过手机号索引，一个手机号只对应一个云世界
- 官方云世界创建流程为客户端提交申请、官方平台人工开通、再回填世界地址
- 管理后台仅用于实例运维，不承载实例内用户管理
- 实例现已支持多个 Provider 账户与多个模型目录项；默认路由继续兼容旧版 `system/provider`，角色可切换为继承默认或角色专属模型路由
- 云世界管理平台现包含 `Revenue Sharing` 页面，用于配置角色使用事件单价、固定收益池、贡献权重、收益人、事件流、分配账本与结算批次

## 部署

- 世界实例：`docker compose up`（当前根 `docker-compose.yml` 只包含 `api/`）
- 客户端首次启动：在 Setup 页选择云世界或本地世界
- 本地世界：手动填写实例地址，若世界主人尚未初始化则进入 Onboarding
- 云世界：手机号验证后进入已开通世界，未开通时提交建世界申请
- 管理后台：访问 `apps/admin`，输入 `ADMIN_SECRET` 鉴权
- 云世界管理平台：访问 `apps/cloud-console`，输入 `CLOUD_ADMIN_SECRET` 鉴权
- 微信同步本地连接器：`pnpm dev:wechat-connector`，仅监听 loopback，供管理后台微信同步页读取本机授权导出的联系人与聊天摘要
- 云平台当前不是自动实例编排器，如需“每用户一个独立实例”的自动化托管能力，需要额外实现

## Single-world cleanup notes (2026-04-09)

- `GET /api/moments` no longer accepts `authorId`; it always returns the current world's feed.
- `FeedPost` 表现已扩展字段：`surface`，用于区分 `feed`（广场动态）与 `channels`（视频号），物理表仍保持兼容扩展
- `FeedPost` 表现已扩展字段：`title`、`mediaPayload`、`coverUrl`、`durationMs`、`aspectRatio`、`topicTags`、`publishStatus`、`shareCount`、`favoriteCount`、`viewCount`、`watchCount`、`completeCount`、`sourceKind`、`recommendationScore`、`statsPayload`，用于承载广场动态 / 视频号的图文、视频内容元数据、状态与统计
- `FeedComment` 表现已扩展字段：`parentCommentId`、`replyToCommentId`、`replyToAuthorId`、`likeCount`、`status`，用于承载视频号评论回复链路
- `UserFeedInteraction` 表现已扩展字段：`payload`、`updatedAt`，用于承载视频号浏览进度、分享来源与评论点赞等互动元数据
- `VideoChannelFollow`：用于持久化世界主人对视频号作者的关注关系
- `GET /api/feed` 现已支持 `surface=feed|channels`
- `POST /api/feed` 现已支持纯文本、图片组图与单条视频发布；媒体资源沿用朋友圈上传契约并写入 `mediaPayload`
- `GET /api/feed/channels/home` 现已提供，用于返回视频号首页分栏、作者摘要、直播卡与推荐流聚合结果
- `GET /api/feed/channels/authors/:authorId` 现已提供，用于返回视频号作者主页摘要与最近内容
- `POST /api/feed/channels/authors/:authorId/follow`
- `DELETE /api/feed/channels/authors/:authorId/follow`
- `POST /api/feed/channels/generate` 现已提供，用于生成一条新的视频号 AI 内容
- `GET /api/feed/:id/comments`
- `POST /api/feed/:id/favorite`
- `DELETE /api/feed/:id/favorite`
- `POST /api/feed/:id/share`
- `POST /api/feed/:id/view`
- `POST /api/feed/:id/not-interested`
- `POST /api/feed/comments/:id/like`
- `POST /api/feed/comments/:id/reply`
- 聊天消息契约现已支持 `sticker` 类型；消息附件元数据由共享表情包目录解析并写入 `Message.attachment`
- 聊天附件消息现已扩展支持 `image`、`file`、`contact_card`、`location_card`、`note_card`；群聊消息同步支持附件元数据
- `POST /api/groups/:id/messages` 现已支持图片、文件、名片、位置卡片附件负载
- AI 语音转写路由已提供：
  - `POST /api/ai/transcriptions`
- AI 语音合成路由已提供：
  - `POST /api/ai/speech`
  - `GET /api/ai/speech/:fileName`
- AI 语言通话路由已提供：
  - `POST /api/chat/voice-calls/turns`
- AI 数字人 provider 现已支持：
  - `DIGITAL_HUMAN_PROVIDER_MODE=mock_stage|mock_iframe|external_iframe`
  - `DIGITAL_HUMAN_PLAYER_URL_TEMPLATE`，可通过 `{sessionId}` / `{conversationId}` / `{characterId}` / `{characterName}` / `{callbackUrl}` / `{callbackToken}` 注入外部播放器地址
  - `DIGITAL_HUMAN_PROVIDER_CALLBACK_TOKEN`，用于保护 `PATCH /api/chat/digital-human-calls/sessions/:sessionId/provider-state` 回调鉴权
- AI 数字人视频通话会话路由已提供：
  - `POST /api/chat/digital-human-calls/sessions`
  - `GET /api/chat/digital-human-calls/sessions/:sessionId`
  - `GET /api/chat/digital-human-calls/sessions/:sessionId/player`
  - `GET /api/chat/digital-human-calls/sessions/:sessionId/events`
  - `PATCH /api/chat/digital-human-calls/sessions/:sessionId/provider-state`
  - `DELETE /api/chat/digital-human-calls/sessions/:sessionId`
  - `POST /api/chat/digital-human-calls/sessions/:sessionId/turns`
- AI 数字人视频通话路由已提供：
  - `POST /api/chat/digital-human-calls/sessions`
  - `GET /api/chat/digital-human-calls/sessions/:sessionId`
  - `POST /api/chat/digital-human-calls/sessions/:sessionId/turns`
  - `DELETE /api/chat/digital-human-calls/sessions/:sessionId`
- 社交屏蔽路由已提供：
  - `GET /api/social/blocks`
  - `POST /api/social/block`
  - `POST /api/social/unblock`
- 摇一摇即时生成路由已提供：
  - `POST /api/social/shake`
  - `GET /api/social/shake/active`
  - `POST /api/social/shake/:id/keep`
  - `POST /api/social/shake/:id/dismiss`
- `Friendship` 表现已扩展字段：`isStarred`、`starredAt`，用于承载好友星标状态
- `Friendship` 表现已扩展联系人资料字段：`remarkName`、`region`、`source`、`tags`，用于承载微信式联系人备注/地区/来源/标签资料
- 社交星标路由已提供：
  - `POST /api/social/friends/:characterId/star`
- 社交联系人资料路由已提供：
  - `PATCH /api/social/friends/:characterId/profile`
- 社交删除联系人路由已提供：
  - `DELETE /api/social/friends/:characterId`
- `Friendship.status` 现已支持 `removed`，用于承载已从通讯录移除但需保留关系记录的联系人状态
- `packages/contracts/src/evals.ts` now uses `ownerId` for trace owner semantics.
- `ConversationEntity` now uses runtime field `ownerId`, while the physical database column remains `userId`.
- `FriendshipEntity`, `FriendRequestEntity`, and `NarrativeArcEntity` now use runtime field `ownerId`, while their physical columns remain `userId`.
- `UserFeedInteractionEntity` now uses runtime field `ownerId`, while the physical database column remains `userId`.
- Backend runtime code no longer uses `userId` as a world-owner semantic field; remaining `userId` usage is only for physical database column compatibility.

## Cloud World Orchestration Update (2026-04-15)

- New cloud platform entities in `apps/cloud-api/src/entities/`:
  - `CloudInstance`
  - `WorldLifecycleJob`
  - `WorldAccessSession`
- Cloud platform responsibility update:
  - phone login now resolves world access directly
  - first-time users automatically get a dedicated world instance
  - returning users wake their existing world instead of creating a new request
  - in-process mock orchestration is available in `apps/cloud-api` until the real VM provider is wired in
- New cloud client routes:
  - `POST /cloud/me/world-access/resolve`
  - `GET /cloud/me/world-access/sessions/:sessionId`
- New cloud admin routes:
  - `GET /admin/cloud/providers`
  - `GET /admin/cloud/jobs`
  - `GET /admin/cloud/jobs/:id`
  - `GET /admin/cloud/drift-summary`
  - `GET /admin/cloud/worlds/:id/instance`
  - `GET /admin/cloud/worlds/:id/bootstrap-config`
  - `GET /admin/cloud/worlds/:id/runtime-status`
  - `GET /admin/cloud/worlds/:id/alert-summary`
  - `POST /admin/cloud/worlds/:id/reconcile`
  - `POST /admin/cloud/worlds/:id/resume`
  - `POST /admin/cloud/worlds/:id/suspend`
  - `POST /admin/cloud/worlds/:id/retry`
  - `POST /admin/cloud/worlds/:id/rotate-callback-token`
- New cloud env var:
  - `CLOUD_MOCK_WORLD_API_BASE_URL`
- Runtime callback routes added in `apps/cloud-api`:
  - `POST /internal/worlds/:worldId/bootstrap`
  - `POST /internal/worlds/:worldId/heartbeat`
  - `POST /internal/worlds/:worldId/activity`
  - `POST /internal/worlds/:worldId/health`
  - `POST /internal/worlds/:worldId/fail`
- Core API now includes backend module `cloud-runtime` in `api/src/modules/cloud-runtime/`:
  - the world instance reports bootstrap, heartbeat, and latest interaction time back to the cloud platform
  - latest activity comes from runtime `Conversation.lastActivityAt` / `Group.lastActivityAt`
- `CloudWorld` now tracks `lastInteractiveAt` as the runtime activity signal used by orchestration and ops views.
- New core API env vars:
  - `CLOUD_PLATFORM_BASE_URL`
  - `CLOUD_WORLD_ID`
  - `CLOUD_WORLD_CALLBACK_TOKEN`
  - `CLOUD_WORLD_HEARTBEAT_INTERVAL_MS`
- New cloud platform env var:
  - `CLOUD_WORLD_IDLE_SUSPEND_SECONDS`
- Additional cloud platform env vars for bootstrap config generation:
  - `CLOUD_PLATFORM_PUBLIC_BASE_URL`
  - `CLOUD_WORLD_API_BASE_URL_TEMPLATE`
  - `CLOUD_WORLD_ADMIN_URL_TEMPLATE`
  - `CLOUD_DEFAULT_WORLD_HEARTBEAT_INTERVAL_MS`
  - `CLOUD_DEFAULT_PROVIDER_KEY`
  - `CLOUD_MANUAL_DOCKER_IMAGE`
  - `CLOUD_MANUAL_DOCKER_DEFAULT_REGION`
  - `CLOUD_MANUAL_DOCKER_DEFAULT_ZONE`
  - `CLOUD_MANUAL_DOCKER_DISK_SIZE_GB`
  - `CLOUD_MANUAL_DOCKER_EXECUTOR_MODE`
  - `CLOUD_MANUAL_DOCKER_REMOTE_ROOT`
  - `CLOUD_MANUAL_DOCKER_SSH_HOST`
  - `CLOUD_MANUAL_DOCKER_SSH_PORT`
  - `CLOUD_MANUAL_DOCKER_SSH_USER`
  - `CLOUD_MANUAL_DOCKER_SSH_PRIVATE_KEY_PATH`
  - `CLOUD_MANUAL_DOCKER_SSH_STRICT_HOST_KEY_CHECKING`
  - `CLOUD_WORLD_RECONCILE_STALE_HEARTBEAT_SECONDS`
  - `CLOUD_WORLD_ALERT_RETRY_THRESHOLD`
  - `CLOUD_WORLD_ALERT_CRITICAL_HEARTBEAT_STALE_SECONDS`
- Automatic idle suspend is now available behind `CLOUD_WORLD_IDLE_SUSPEND_SECONDS > 0`, and only uses runtime activity / access-session signals to decide when a world can safely sleep.
- Cloud console world detail now exposes a bootstrap package:
  - generated runtime env overlay for `api`
  - docker compose environment snippet
  - callback endpoints and callback token rotation for redeploying a world instance safely
- Cloud platform now has a provider abstraction layer in `apps/cloud-api/src/providers/`:
  - `ComputeProviderRegistryService` selects the active compute provider by `providerKey`
  - built-in providers now include `mock` and `manual-docker` (legacy `manual` keys normalize to `manual-docker`)
  - `manual-docker` prepares a per-world docker deployment package and waits for runtime bootstrap / heartbeat callbacks before promoting the world to `ready`
  - when `CLOUD_MANUAL_DOCKER_EXECUTOR_MODE=ssh`, the cloud platform can upload compose/env files to a remote Docker host and execute `docker compose up/stop` over SSH, while still relying on runtime callbacks for final readiness
- `CloudInstance` now also tracks provider resource metadata:
  - `providerVolumeId`
  - `providerSnapshotId`
  - `launchConfig`
  - `lastOperationAt`
- Cloud alert delivery now includes outbound webhook notifications in `apps/cloud-api/src/alerts/`:
  - `CloudAlertNotifierService` sends structured JSON webhooks for critical platform failures
  - current automatic events: `world_job_failed` and `world_provider_error`
  - webhook payload now includes human-friendly `title` / `summary` / `text` fields plus direct admin/api links for Feishu / WeCom style forwarding
  - webhook delivery is best-effort and does not block lifecycle processing
- Cloud console world detail now supports provider-catalog based editing for `provisionStrategy` / `providerKey` / `providerRegion` / `providerZone`, and displays instance resource metadata for future real VM providers.
- Cloud bootstrap packages are now provider-aware and include `providerLabel`, `deploymentMode`, `image`, `containerName`, `volumeName`, plus a manual-docker compose snippet that can be applied on the target host.
- Bootstrap packages for `manual-docker` now also expose `executorMode`, `projectName`, and `remoteDeployPath` so ops can see the exact remote deployment location used by the SSH executor.
- Cloud platform now exposes provider runtime observation for ops:
  - providers implement a unified runtime-status inspection surface
  - `manual-docker` can inspect the remote Docker host over SSH and report `running / starting / stopped / missing / error`
  - cloud console world detail now shows provider-observed deployment state separately from runtime heartbeat state
- World lifecycle reconcile now uses provider observation to heal drift:
  - maintenance loop inspects active worlds with no in-flight lifecycle jobs
  - if desired state is `running` but provider reports `stopped` or `missing`, the platform queues recovery automatically
  - if desired state is `sleeping` but provider still reports `running`, the platform queues suspend automatically
  - cloud console world detail exposes a manual `Reconcile` action for on-demand drift repair
  - each effective reconcile run now writes a `reconcile` lifecycle job with observed state, chosen action, and before/after status for audit
- Cloud console worlds list now includes a drift summary panel:
  - `GET /admin/cloud/drift-summary` aggregates failed worlds, stale heartbeats, provider drift, and queued recovery counts
  - the worlds page surfaces top attention items and per-world attention badges so operators can see why a world needs intervention before opening detail view
- Cloud platform alerting now supports threshold-based escalation:
  - `GET /admin/cloud/worlds/:id/alert-summary` returns the current alert snapshot, retry counters, stale-heartbeat age, and escalation thresholds for one world
  - `CLOUD_WORLD_ALERT_RETRY_THRESHOLD` upgrades repeated recovery drift into a critical alert after enough failed retries
  - `CLOUD_WORLD_ALERT_CRITICAL_HEARTBEAT_STALE_SECONDS` upgrades long-running stale heartbeat conditions into a critical alert
  - cloud console now distinguishes warning vs critical worlds and shows whether an alert has already been escalated
- Cloud alert webhook env vars:
  - `CLOUD_ALERT_WEBHOOK_URL`
  - `CLOUD_ALERT_WEBHOOK_TOKEN`
  - `CLOUD_ALERT_WEBHOOK_EVENTS`
  - `CLOUD_ALERT_WEBHOOK_TIMEOUT_MS`
- Cloud alert ops now also cover recovery and shareable views:
  - silence expiry automatically emits `alert_resurfaced`
  - manual takeover timeout automatically emits `manual_takeover_escalated`
  - cloud console worlds summary surfaces `resurfaced alerts` and `takeover escalated` counters
  - `/worlds` persists `status` and `attention` filters in the URL and can copy the current filtered view as a shareable link
  - `/jobs` persists `status` and `jobType` filters in the URL and can copy the current filtered view as a shareable link