基于 SecondMe 的 AI 互动社交平台。
核心目标是把「数字分身」用于剧情、辩论、创作与社交协作。
本 README 提供全仓模块说明、关键函数清单与平台能力地图。

---

• AI 剧情演绎：多人分身按模板扮演角色，自动推进剧情并沉淀结果。
• A2A 分身对谈：支持辩论、裁判、观众投票、总结，适配多人协作。
• SecondMe 原生能力：Chat、Act、Shades、SoftMemory、TTS、Agent Memory。
• 知乎联动：热榜选题、圈子发帖、评论、点赞、搜索、擂台发布。
• 积分与 API 商业化：积分余额、消费、订单、兑换码、API Key 作用域控制。
• 多模态内容生成：VibeAPI 文本/图像/视频能力统一封装。
• 资源上传与分发：COS 预签名直传、服务端压缩、CDN 访问。
• 安全与工程化：中间件鉴权、安全响应头、统一错误处理、SSE 流式规范。

---

1. 准备 Node 20+ 与 corepack pnpm。
2. 安装依赖：pnpm install。
3. 配置 .env（见下方环境变量）。
4. 启动开发：pnpm dev。
5. 运行校验：pnpm typecheck、pnpm build、pnpm lint。

• pnpm dev：开发模式
• pnpm build：生产构建
• pnpm start：启动构建产物
• pnpm typecheck：TS 类型检查（pre-commit 会自动跑）
• pnpm lint：ESLint（当前因上游 eslint-config-next JSON 类型问题会失败）
• pnpm db:generate / pnpm db:push / pnpm db:studio
• pnpm db:import-templates：导入剧情模板

---

• 站点：NEXT_PUBLIC_APP_URL
• SecondMe：SECONDME_API_BASE、SECONDME_AUTH_URL、SECONDME_CLIENT_ID、SECONDME_CLIENT_SECRET
• VibeAPI：VIBE_API_KEY
• 知乎 OpenAPI：ZHIHU_API_BASE_URL、ZHIHU_APP_KEY、ZHIHU_APP_SECRET
• COS：COS_SECRET_ID、COS_SECRET_KEY、COS_BUCKET、COS_REGION、NEXT_PUBLIC_ASSETS_DOMAIN

---

• src/app/：页面与 API 路由（Next.js App Router）
• src/lib/：核心业务库与外部服务客户端
• src/components/：UI 组件与业务组件
• src/hooks/：前端复用 Hook
• src/db/：数据库连接与 Schema
• scripts/：数据导入与迁移脚本
• docs/：领域文档与研究文档
• middleware.ts：登录保护 + 安全响应头

• API 路由统一走 withAuth / withAuthGet 或 withApiKey*。
• 客户端请求统一走 fetchWithTokenRefresh，自动处理 401 刷新。
• POST 流式场景必须使用 consumeSSE() 解析。
• 重型依赖优先动态导入；独立异步任务优先 Promise.all。
• 客户端错误使用 toast；服务端错误使用 logger.error()。

---

以下为代码级功能说明，覆盖主要目录与核心函数。
如需更深实现细节，请继续阅读 docs/modules/*.md。

模块位置

• middleware.ts
• src/lib/session.ts
• src/lib/api-handler.ts
• src/lib/fetch.ts
• src/app/api/auth/*

功能与关键函数

• getSession() / requireSession() / destroySession()：Session 生命周期。
• withAuth() / withAuthGet() / withAuthParams()：登录态保护包装器。
• withApiKey() / withApiKeyGet()：机器调用鉴权与 scope 校验。
• withAuthOrApiKeyGet()：Session 优先，API Key 兜底。
• fetchWithTokenRefresh()：401 自动刷新，减少前端重复逻辑。
• parseApiResponse() / toResponse()：统一返回格式与错误处理。

平台价值

• 形成统一权限边界。
• 让页面态、服务态、开放 API 同时可控。

模块位置

• src/lib/secondme/client.ts
• src/lib/secondme/auth.ts
• src/lib/secondme/token.ts
• src/lib/secondme/act-utils.ts
• src/lib/secondme/types.ts
• src/app/api/secondme/*

关键函数

• buildAuthUrl() / exchangeCodeForToken() / refreshAccessToken()：OAuth2 流程。
• getTokenBySecondMeUserId()：按 SecondMe 用户检索 Token。
• getUserInfo() / getUserShades() / getSoftMemory()：用户与记忆读取。
• streamChat() / streamAct()：流式会话与动作判断。
• getSessions() / getSessionMessages()：会话历史管理。
• generateTts()：语音合成。
• ingestAgentMemory()：Agent 记忆上报。
• collectAndExtractJson()：Act 结果聚合与结构化提取。

平台价值

• 所有 SecondMe 能力收敛在一个客户端边界。
• 便于统一鉴权、日志、降级与错误治理。

模块位置

• src/lib/sse.ts
• src/lib/api-handler.ts（SSE_HEADERS）

关键函数

• consumeSSE()：解析 event/data/[DONE]。
• extractDeltaContent()：抽取增量文本片段。
• SSE_HEADERS：标准 SSE 响应头。

平台价值

• 支撑 Chat、Act、A2A、裁判等长链路流式体验。
• 保证 POST 流场景在浏览器端可正确消费。

模块位置

• src/lib/scenario/*
• src/app/(main)/scenarios/*
• src/app/api/scenarios/*
• src/lib/scenario/templates/*.json

关键函数

• getAllTemplatesFromDB() / getTemplatesPaginated() / getTemplateFromDB()：模板查询。
• importTemplate() / updateTemplateStatus()：模板写入与状态管理。
• interpolate() / assignRoles() / pickRoundDirective()：剧情插值与角色分配。
• buildRoleDimensionsPrompt()：角色维度提示词组装。
• executeScenario()：剧情执行编排。

平台价值

• 把「剧本模板」转化为可运行的多人 AI 社交体验。
• 支撑从匹配、演绎到结果沉淀的完整闭环。

模块位置

• src/lib/a2a/*
• src/app/(main)/a2a/*
• src/app/api/a2a-rooms/*
• src/app/api/v1/a2a/*

关键函数/常量

• executeMultiPartyConversation()：多人对话主执行器。
• runJudge()：裁判模型评分与结论。
• runAudienceVote()：观众投票聚合。
• isDebateMode() / parseDebateSystemPrompt() / buildDebatePrompt()：辩论模式编排。
• A2A_IDEAS：观点灵感池。
• EMOTIONAL_COMPENSATION_*：情感补偿方向与策略常量。

平台价值

• 让分身从“聊天”升级到“多角色协作/对抗系统”。
• 兼具娱乐性、表达性与可复盘性。

模块位置

• src/lib/gomoku/*
• src/app/(main)/a2a/gomoku/*
• src/app/api/gomoku-games/*
• src/app/api/v1/gomoku/*

关键函数

• createGomokuGame()：创建棋局（可随机或指定对手）。
• executeGomokuGame()：棋局执行与状态推进。
• buildBoardFromMoves()：根据落子重建棋盘。
• isWinningMove() / isBoardFull()：胜负判定。
• createEmptyBoard() / isWithinBoard() / getFirstEmptyMove()：规则工具。

平台价值

• 提供结构化、可判定的 AI 对战互动场景。
• 便于扩展更多规则型多人玩法。

模块位置

• src/lib/zhihu/*
• src/app/(main)/zhihu/*
• src/app/api/zhihu/*

关键函数

• isZhihuConfigured() / zhihuFetch()：配置检测与签名请求入口。
• getBillboardList()：热榜话题获取。
• getRingDetail() / publishPin()：圈子详情与发帖。
• searchGlobal()：全局搜索。
• createComment() / deleteComment() / getCommentList()：评论管理。
• reaction() / likePin() / unlikePin() / likeComment() / unlikeComment()：互动行为。

关键约束

• 调用前需检查 isZhihuConfigured()。
• 内建限流：全局 10 QPS，搜索 1 QPS/1000 次。
• pin_id/comment_id 统一字符串，避免 int64 精度问题。

平台价值

• 把站内 AI 内容与站外热点生态打通。
• 增强话题新鲜度与内容传播能力。

模块位置

• src/lib/credits/credits.ts
• src/lib/credits/payment.ts
• src/app/api/credits/*
• src/app/api/v1/credits/*

关键函数/类

• getBalance() / addCredits() / spendCredits() / getTransactions()：余额与流水。
• listCreditProducts() / listCreditOrders()：产品与订单查询。
• redeemCreditProduct()：兑换商品。
• consumeCreditsByApiKey()：API Key 场景消费。
• upsertCreditProduct() / importCreditRedeemCodes() / listCreditRedeemCodes()：运营侧管理。
• InsufficientCreditsError、ProductNotFoundError 等：领域异常建模。

平台价值

• 支撑平台商业化、权益分发与可审计计费。

模块位置

• src/lib/api-key.ts
• src/app/api/api-keys/route.ts
• src/app/api/v1/*

关键函数/常量

• API_KEY_ALLOWED_SCOPES：作用域白名单。
• generateApiKey() / validateApiKey()：生成与校验。
• listApiKeys() / revokeApiKey()：管理生命周期。

平台价值

• 为服务端到服务端调用提供安全入口。
• 与 Session 鉴权并存，支持开放生态。

模块位置

• src/lib/cos.ts
• src/lib/assets.ts
• src/lib/image-processor.ts
• src/lib/image-compression.ts
• src/hooks/useImageUpload.ts
• src/app/api/upload/*

关键函数

• uploadToCOS() / generatePresignedUrl() / generateFileKey() / mirrorAvatarToCOS()。
• assetUrl() / assetPath()：CDN URL 与相对路径互转。
• validateAndProcessImage()：服务端图片校验与处理。
• compressImage()：客户端压缩。
• useImageUpload()：前端上传全流程编排。

平台价值

• 降低图片上传失败率与带宽成本。
• 实现「前端直传 + CDN 读取」的高性能链路。

模块位置

• src/lib/ai/vibe.ts

关键导出

• VIBE_MODELS：模型映射。
• vibeChat()：文本生成。
• vibeImage()：图像生成。
• vibeProvider()：Provider 适配。
• isVibeConfigured()：配置检查。

平台价值

• 把文本、图像、视频生成能力接入统一业务管道。

模块位置

• src/lib/logger.ts：logger 全局日志实例。
• src/lib/id.ts：createId()。
• src/lib/cn.ts：cn() 样式合并。
• src/lib/format.ts：timeAgo() 时间格式化。
• src/lib/nav-items.ts：NAV_ITEMS 导航配置。
• src/lib/footprints.ts：getUserFootprints() 用户行为聚合。

平台价值

• 统一基础能力，减少重复实现并提高可维护性。

---

• /chat：SecondMe 对话页（流式增量渲染）。
• /act：动作判断页（结构化动作输出）。
• /agent-memory：记忆上报页。
• /memory：软记忆检索与展示。
• /profile：用户画像与足迹。
• /voice：语音合成与播放。
• /scenarios、/scenarios/[id]：剧情模板、房间、详情。
• /scenarios/editor、/scenarios/editor/[id]：剧情模板编辑器。
• /admin/review：内容审核界面。
• /a2a、/a2a/room/[id]：分身对谈。
• /a2a/gomoku、/a2a/gomoku/[id]：五子棋。
• /a2a/emotional-compensation：情绪补偿场景。
• /zhihu、/zhihu/arena、/zhihu/circle、/zhihu/digest：知乎业务页。

• /login：登录入口。
• /callback：OAuth 回调承接页。
• /dev：开发环境用户切换与调试工具页。
• /：公开首页（已登录用户按逻辑跳转到业务入口）。

---

• api/auth/*：登录、回调、刷新、退出。
• api/secondme/*：SecondMe 代理能力（chat/act/tts/user/shades/memory/session）。
• api/scenarios/*：剧情模板、匹配、房间事件、详情。
• api/a2a-rooms/*：A2A 房间与结果总结。
• api/gomoku-games/*：五子棋局创建与状态。
• api/zhihu/*：擂台、圈子、热榜、搜索、评论、互动。
• api/credits/*：积分余额、商品、兑换、订单。
• api/upload/*：上传中转与预签名。
• api/users/*：用户资料、历史、足迹。
• api/api-keys：API Key 管理。
• api/v1/*：对外开放 API（API Key 作用域保护）。
• api/dev/*：开发辅助接口（本地调试）。

• 页面内接口优先 Session。
• 对外接口走 API Key + scope。
• 输出统一结构，便于前端消费与监控告警。

---

• ui/*：基础组件（Button/Input/Dialog/Select/Tooltip/Tabs 等）。
• nav-bar.tsx / command-menu.tsx：全局导航与命令检索。
• api-key-manager.tsx：API Key 可视化管理。
• credit-panel.tsx：积分状态与操作入口。
• participation-history.tsx：参与历史可视化。
• share-card.tsx：分享卡片生成。
• markdown.tsx：Markdown 渲染与代码高亮。

• useImageUpload()：文件校验、压缩、预签名、上传与状态管理。
• useDebounce()：防抖，减少频繁请求。
• useIsMobile()：移动端判断，支持响应式交互差异。

---

• src/db/schema.ts：Drizzle Schema。
  • 覆盖用户、剧情、A2A、五子棋、积分、API Key、知乎等核心表。
• src/db/index.ts：Neon PostgreSQL 连接入口。

---

• import-templates.ts：剧情模板导入数据库。
• migrate-avatars.ts：头像资源迁移。
• migrate-images-to-cos.ts：图片迁移到 COS。
• import-roundtable.mjs / migrate-priority.mjs：专题数据处理。
• check-merge-safety.sql：合并前数据安全检查。

---

• 中间件统一追加安全响应头。
• API 层统一鉴权包装，避免裸露路由。
• SSE 路由统一协议头，防止代理缓存破坏流。
• 服务端统一日志，便于追踪生产异常。
• 上传链路采用校验+压缩+白名单目录，控制风险。

---

1. docs/README.md：系统总览。
2. docs/modules/README.md：模块深度文档入口。
3. docs/modules/*.md：按领域深入阅读。
4. docs/zhihu-api.md：知乎 OpenAPI 细节。
5. docs/vercel-ai-sdk-openai-compatible-providers.md：AI SDK 兼容实践。
6. 项目完整说明文档.md：历史全量说明稿。

---

• pnpm typecheck：通过。
• pnpm build：通过（构建过程会提示 ESLint JSON 类型问题，但构建完成）。
• pnpm lint：失败，原因是 eslint-config-next JSON 类型错误（上游兼容问题）。