仓库总览¶

面向新成员的仓库介绍，帮助你快速了解每个 repo 的作用和技术栈。最后更新：2026 年 3 月

架构概览¶

我们的产品是一个 AI 驱动的通话分析平台，核心流程：

RingCentral 电话系统
  → Webhook 事件接收（ringcentralSubscriptionService）
  → 录音下载 + 语音转文字 + AI 分析（callytics-infrastructure）
  → 结构化数据存储（DynamoDB + S3）
  → 前端展示和管理（studio-website-monorepo）

主要服务客户：健身连锁品牌（如 Orangetheory Fitness），提供通话质量分析、员工 coaching、Lead 追踪、收入归因等功能。

核心产品¶

studio-website-monorepo¶

主仓库 — Turborepo monorepo，包含后端 API 和前端应用

由原 studio-api 重命名而来，并合并了原 studio-web 独立前端仓库（已 archived）。

属性	详情
类型	Turborepo monorepo
后端	Hono + AWS Lambda + API Gateway
前端	Vue 3 + Vite + Tailwind CSS + shadcn-vue
数据库	DynamoDB(10 张表,门店/电话/权限等配置数据)+ Neon Postgres(通话/联系人/消息/任务等业务数据,通过 callytics-common schema)
认证	AWS Cognito (JWT)
前端部署	Cloudflare Pages
后端部署	AWS CDK（Lambda + API Gateway）
运行时	Bun (开发) / Node.js (Lambda 生产)
API 文档 (SoT)	`apps/api/docs/api-technical-reference.md`(完整端点参考) · `apps/api/docs/frontend-api-guide.md`(前端使用示例)

Monorepo 结构：

studio-website-monorepo/
├── apps/
│   ├── api/              # 后端 API — Hono 路由 + Lambda handler
│   │   ├── src/          # Routes → Services → Repositories 三层架构
│   │   └── infra/        # AWS CDK 部署配置
│   └── web/              # 前端 — Vue 3 SPA
│       └── src/pages/    # 基于文件系统的路由
├── packages/
│   └── common/           # @callytics/common — 共享工具库
└── turbo.json

DynamoDB 表（CDK Stack: OrangeTheoryStack-{env}）：

表名模式	说明
`orangetheory-UserConnections-{env}`	RC OAuth 连接（含加密 token）
`orangetheory-PhoneNumbers-{env}`	RC 电话线路与分机
`orangetheory-PhoneStoreAssignments-{env}`	电话 → 门店映射
`orangetheory-StoresV2-{env}`	门店信息
`orangetheory-UserStore-{env}`	用户-门店权限
`orangetheory-SubAccounts-{env}`	子账号关系
`orangetheory-OAuthStates-{env}`	OAuth 瞬态（TTL）
`studio-Cache-{env}`	通用缓存（TTL）
`studio-BlackoutPeriods-{env}`	禁呼时段
`studio-OperatingHours-{env}`	营业时间

注意：新表使用 studio- 前缀，不要使用 orangetheory- 前缀。

核心功能： - RingCentral OAuth 集成与 token 加密管理 - 通话记录查询、录音回放、转录查看 - Lead Tracker（潜在客户追踪） - 短信/语音信箱消息管理 - 门店管理（多租户、共享访问 OWNER/EDITOR/VIEWER） - 14 天分析 Dashboard（ECharts 可视化） - 运营时间和 blackout 管理 - v3 API(2026-04-28 起):Calls / Contacts / Conversations / Leads / Tasks 5 个列表页基于 Neon Postgres,统一 WHERE store_id = $1 隔离,无限滚动 + URL state 持久化。详见 apps/api/docs/api-technical-reference.md v3 章节 - Staff Amend(2026-04-30 起):PUT /v3/calls/:id/staff 修正通话员工归属,DDB + Neon 双写,审计历史存 calls.amendment_history (jsonb)

CI/CD： - PR Validation：Lint、Typecheck、Unit Tests、Build Check（全部 required） - Deploy to Test：push 到 main 时自动触发，根据 git diff 检测变更的包（apps/web、apps/api、packages/）按需部署 - Deploy to Production：手动触发（workflow_dispatch），需输入 prod 确认

三个环境： - test（us-west-2）— 测试环境 - pre（us-east-2）— 预发布环境 - prod（us-east-1）— 生产环境

lead-tracking¶

自动化 Lead 邮件采集 pipeline — 2-Lambda 架构(2026-04-25 PR #94 起)

属性	详情
类型	2 个 AWS Lambda + EventBridge + SQS
触发	EventBridge 每 5 分钟(Poller)
数据源	IMAP 邮箱(Lark Suite)
存储	DynamoDB(`LeadTracking-v2-{region}`,去重)+ Neon Postgres(`leads` / `contacts` / `tasks` / `contact_timeline` 4 张表)
部署	AWS CDK(`LeadTrackingStack`)

2-Lambda 架构:

Poller (EventBridge 每 5 min)
  ├─ IMAP 拉邮件 → 解析 → 去重(DynamoDB)
  ├─ Neon: leads-only UPSERT(只写 leads 表)
  └─ EventBridge.putEvents("LeadCreated")
                ↓
         SQS Queue (+DLQ)
                ↓
    lead-processor Lambda
       └─ Neon: contacts UPSERT + tasks INSERT + contact_timeline INSERT (3 表 db.batch())

Prod 写完 fire-and-forget 再 dual-write 到 test Neon(给 dashboard live data)

为什么 2-Lambda: 旧版 Poller 单 Lambda 4 表原子 batch,downstream 失败 → 邮件不 SEEN → 阻塞整个 pipeline。新版 leads 写入成功就 SEEN,downstream 失败进 DLQ 单条重试。

关键文件: - src/poller.ts — IMAP + leads 写入 + EventBridge 发事件 - src/lead-processor.ts — SQS consumer(downstream 3 表写入) - src/store-mapping.ts — 从 StoresV2 DDB 解析 storeId(隔离键) - lib/leadtracking-stack.ts — CDK(EventBridge rule + SQS + DLQ + 2 Lambda)

基础设施¶

callytics-infrastructure¶

AWS CDK 基础设施 + AI 通话分析 pipeline + 消息持久化 — 整个平台的"大脑"

属性	详情
IaC	AWS CDK (TypeScript) — 模块化 Stack
AI	Kimi K2 / Claude（LLM 通话分析，Bedrock 备选）
语音转文字	Deepgram（主，AWS Transcribe 备选）
存储	DynamoDB（5 张表）+ S3
队列	SQS（含 DLQ）
Lambda	TypeScript + Python

DynamoDB 表（CDK Stack: CallAnalytics-{Env}-Storage + MessageSystem）：

表名模式	说明
`call-analytics-{env}-call-analysis-{region}`	AI 分析结果（最大表，11 GSIs）
`call-analytics-{env}-call-events-{region}`	原始通话事件（2 GSIs）
`call-analytics-{env}-call-analysis-config-{region}`	每客户分析配置
`MessageStore-{region}`	SMS/VoiceMail/Fax 消息存储（5 GSIs）
`Conversations-{region}`	会话聚合视图（2 GSIs）

核心 Pipeline：

通话: Webhook 接收 → 录音下载到 S3 → Deepgram 转文字 → Kimi K2/Claude AI 分析 → 结果存入 DynamoDB
消息: ringcentralSubscriptionService 路由 → SQS → message-processor Lambda → DynamoDB + S3

重要目录 — config/schemas/：

这里存放 AI 分析的 prompt 和配置，按租户组织，可以在不重新部署的情况下更新：

config/schemas/
└── orangeTheory/
    ├── prompts/
    │   ├── standard-v1.0.0.txt     # 主分析 prompt（~1,248 行）
    │   └── voicemail-v1.0.0.txt    # 语音信箱分析 prompt
    ├── ai-mappings/
    │   └── ai-mapping-v1.0.0.json  # AI 输出字段 → DynamoDB 字段映射
    └── provider-mappings/
        └── provider-mapping-v1.0.0.json  # RingCentral 事件 → 分析表字段映射

standard prompt 指导 AI 分析通话内容：员工识别、客户类型、通话主题分类、收入优先级、coaching 建议、跟进需求等
voicemail prompt 是简化版，处理语音信箱场景
Prompt 中有占位符（如 {STAFF_LIST_WILL_BE_INJECTED_HERE}），运行时由 Lambda 注入实际数据

message-infra ⚠️ 已废弃¶

~~SMS/消息持久化 pipeline~~ — 原型仓库，从未部署到生产环境

属性	详情
状态	已废弃 — 2026-02-14/15 的原型实现，仅 2 天提交历史
替代方案	消息处理已整合进 `callytics-infrastructure`（`lambda/message-processor/`）
Webhook 接收	已由 `ringcentralSubscriptionService` 统一处理

注意：消息持久化的 DynamoDB 表（MessageStore、Conversations）和 S3 附件存储现在由 callytics-infrastructure CDK 管理。详见上方 callytics-infrastructure 章节。

ringcentralSubscriptionService¶

RingCentral Webhook 订阅管理微服务

属性	详情
类型	AWS Lambda 微服务（3 个 Lambda）
部署	AWS CDK
核心功能	接收 RingCentral webhook → 按事件类型路由到 callytics SQS（telephony）或 message SQS（message-store）
存储	DynamoDB（2 张表：`rc-subscription-{env}-webhook-subscriptions` + `rc-subscription-{env}-idempotency`，CDK Stack: `RCSubscription-{env}-Storage`）

三个 Lambda： 1. WebhookReceiver — 接收 RingCentral webhook 事件，添加租户信息（_user_id、_client_id、_account_id），按事件类型路由：message-store → message SQS；telephony → callytics SQS 2. SubscriptionManager — 管理 webhook 订阅的 CRUD 3. SubscriptionRenewer — EventBridge 定时任务，每天 3AM UTC 续订

callytics-common¶

共享工具库 — 被多个服务引用

属性	详情
包名	`@retaintive/common`
语言	TypeScript（直接消费 .ts，无编译步骤）

提供的模块：

子路径	功能
`/errors`	统一错误类（AppError、ValidationError、NotFoundError 等）
`/aws`	DynamoDB / Lambda 客户端工厂
`/logger`	AWS Lambda Powertools Logger 封装
`/utils`	重试（指数退避）、计时、懒加载客户端
`/types`	OAuth token 类型定义
`/discord`	Discord webhook 错误通知
`/lark`	Lark webhook 错误通知（带 HMAC 签名）
`/db`	Drizzle ORM schema（Neon PostgreSQL） — `calls`/`contacts`/`messages` 表定义，是 Neon schema 的 source of truth
`/rc`	RingCentral Webhook & Message 事件的 Zod schema（不含在默认 re-export 中）

内部工具¶

rcConnectionChecker¶

RingCentral 连接监控面板

属性	详情
前端	Vue 3 + Tailwind CSS + shadcn-vue
后端	Cloudflare Worker (Hono)
认证	Lark SSO
部署	Cloudflare Pages（`ringcentral.retaintive.ai`）

功能： 跨三个 AWS 环境浏览 RingCentral 账户数据（通话、消息、用户、设备、订阅、分析），支持 DynamoDB 原始数据浏览。

cloudflare-github-webhook-rerouter¶

Cloudflare Worker — GitHub Webhook → Lark 多频道路由通知

属性	详情
类型	Cloudflare Worker
语言	TypeScript
部署	Cloudflare Workers（push to main 自动部署）
测试	Vitest + @cloudflare/vitest-pool-workers

功能： 接收 GitHub org-level webhook 事件，按内容类型路由到 4 个独立的 Lark 群组：

频道	事件	用途
PR	PR opened/merged/closed/reopened, review approved/changes_requested	PR 生命周期 + Code Review
Issue	Issue opened/closed	Issue 跟踪
Alert	workflowrun failure/timedout, deployment_status failure/error	CI/CD 失败告警
Deploy	deployment_status success（需要 GitHub Environments）	部署成功审计日志

路由规则： - 只处理上述事件，其他事件（push、star、fork、label 等）静默丢弃 - Deploy 频道仅接收 deployment_status success 事件（需要 workflow 中声明 environment:） - 自动过滤自身部署通知（避免 meta-notification） - 所有请求通过 HMAC-SHA256 签名验证

安全机制： - GitHub webhook secret 验证（X-Hub-Signature-256） - Lark webhook HMAC 签名（每个频道独立 secret） - 所有 secrets 存储在 Cloudflare Workers Secrets 中（非代码/非环境变量）

环境变量（Cloudflare Secrets）：

变量	说明
`GITHUB_WEBHOOK_SECRET`	GitHub webhook 签名验证
`LARK_WEBHOOK_URL` / `LARK_WEBHOOK_SECRET`	Alert 频道（CI/部署失败）
`LARK_WEBHOOK_URL_PR` / `LARK_WEBHOOK_SECRET_PR`	PR 频道
`LARK_WEBHOOK_URL_ISSUE` / `LARK_WEBHOOK_SECRET_ISSUE`	Issue 频道
`LARK_WEBHOOK_URL_DEPLOY` / `LARK_WEBHOOK_SECRET_DEPLOY`	Deploy 审计日志频道

lark-dm-bot¶

GitHub + Sentry webhook → 飞书私信推送（Cloudflare Worker）

与 cloudflare-github-webhook-rerouter 互补：后者发群消息（channels），本服务发私信（DM），精准触达相关人。

属性	详情
类型	Cloudflare Worker
语言	TypeScript
部署	Cloudflare Workers（push to main 自动部署）

GitHub 通知（6 种事件）：

事件	通知谁
Review 请求	被请求的 reviewer
PR 更新（新 commit）	所有待 review 的人
CI / Workflow 失败	推代码的人
PR Review（approved / changes_requested）	PR 作者
PR 评论	PR 作者 + 被 @的人

Sentry 通知： - 新错误 / 已解决、告警规则触发 → 广播给 KV 订阅者 - UTC 16:00 自动推送每日 Sentry 汇总（Prod / Test 分段，含 Top 3 高频错误） - 用户通过飞书卡片按钮订阅 / 退订

附带工具： /dashboard 实时 HTML 状态页；scripts/sentry-ops.sh Sentry 日常巡检脚本。

prompt-eval¶

AI Prompt 评测工具 — Contacts 分析 prompt 的测试数据、运行结果和版本对比，供 AI 工程师迭代 prompt 时参考。

属性	详情
类型	离线评测工具（非线上服务）
语言	Python
关联	`callytics-infrastructure` 的 `config/schemas/` 存放生产 prompt；本 repo 存放评测 harness + 测试集

内容组织： - prompts/ — 待评测的 prompt 版本（从 callytics-infrastructure 迁移） - test-data/ — 真实通话转录样本（脱敏） - results/ — 各版本 prompt 的输出结果 + 人工评分

注意： 此 repo 不部署到任何环境，纯离线工具。生产 prompt 仍以 callytics-infrastructure/config/schemas/ 为准。

trigger.dev.callytics¶

基于 Trigger.dev 的通话处理 pipeline（实验性/备选方案）

属性	详情
任务编排	Trigger.dev SDK v4
语音转文字	Deepgram（与 callytics-infrastructure 相同，主用 Deepgram）
AI 分析	AWS Bedrock
存储	AWS S3 + Cloudflare D1

Pipeline： RingCentral 通话记录 → 下载录音 → Deepgram 转录 → Bedrock AI 分析 → 存储

网站¶

landingPage¶

新版 Landing Page

属性	详情
框架	Next.js 16 + React 19
UI	shadcn/ui + Tailwind CSS v4
部署	Cloudflare Pages（`landing-page`）

文档¶

docs¶

组织内部文档

github-admin-guide.md — GitHub 组织管理指南（Admin 用）
member-guide.md — 成员工作流指南
repo-overview.md — 本文档
cloudaudioai-design/ — 历史设计文档（从 cloudaudioai-backend-design 迁移）

lark¶

文档仓库（无代码）

Lark MCP 集成指南（如何用 Claude Code 连接 Lark）
Studio 产品闭环方案（产品策略文档）

AI 开发工具¶

claude-plugins¶

团队共享的 Claude Code 技能和 Agent — org plugin marketplace

属性	详情
类型	Claude Code Plugin Marketplace（私有）
内容	19 个 skills + 6 个 domain agents
安装	Clone 任何 retaintive repo → trust → 自动提示安装

Skills 分类：

分类	Skills
Investigation	`deep-research`, `expert-panel`
Git/PR	`pr`, `reviewing-pull-requests`, `pr-comment-handler`, `hotfix`, `teammate-review`
Deployment	`deploy-preflight`
AWS Debug	`aws-lambda-debugger`, `dynamodb-troubleshooter`
Documentation	`doc-architect`, `doc-design-review`, `doc-style`, `lark-publish`, `mermaid-ascii`
Factory/Ops	`factory-audit`, `rules-writer`, `new-repo-setup`
API	`api-pagination-handler`

Agents（6 个 domain 专家）：

Agent	领域
`architecture-schema-reviewer`	DB schema、数据模型、migration 安全
`data-discovery-analyst`	数据模式、质量、预测建模
`data-instrumentation-architect`	事件埋点、指标设计、KPI
`gym-business-expert`	健身行业运营、CRM 漏斗
`parathinker-reasoning`	复杂推理、多路径分析
`saas-architect-reviewer`	SaaS 运维、CI/CD、AWS 成本

配置机制： 每个活跃 repo 的 .claude/settings.json 声明 extraKnownMarketplaces 指向此 repo，新成员 trust 项目时自动提示安装。

维护： 添加 skill/agent 后 bump 版本号 → push to main → 团队成员 /plugin marketplace update 即可获取。

GitHub Actions 配置¶

跨 Repo 访问级别（`access_level`）¶

GitHub Actions 的 access_level 控制本 repo 的 reusable workflow 能否被 org 内其他 repo 调用。

值	含义
`none`（默认）	仅本 repo 内部可用
`organization`	org 内所有 repo 均可调用本 repo 的 reusable workflow

当前配置：

Repo	access_level	说明
`docs`	organization	`factory-audit-reusable.yml` 开放给全 org，其他 repo 的 `factory-audit.yml` 只需 5 行即可调用
其余所有 repo	`none`	默认值，无需跨 repo 调用

修改方式（需要 repo admin 权限）：

gh api --method PUT repos/retaintive/<repo>/actions/permissions/access \
  --field access_level=organization

注意： docs repo 是 private，但 access_level=organization 使得 org 内其他 private repo 可以直接引用其 reusable workflow，无需将 repo 改为 internal。

已归档仓库¶

以下仓库已 archived，保留历史参考但不再活跃开发：

Repo	说明
studio-web	独立前端仓库（已合并进 studio-website-monorepo）
retaintive.ai.landingpage	旧版官网（Next.js 14 + React 18），已由 `landingPage` 取代
callytics-platform	Cloudflare Workers 版通话分析平台（暂停后归档）
cloudaudioai-backend-design	早期后端设计文档（已迁移到 docs repo）
retaintive.ai.spec	产品规格文档
ringcentralService	旧版 RingCentral 服务
RingcentralAnalysisPortal	旧版分析门户
callytics-dashboard	旧版客户 Dashboard (Vue.js)
callytics-docs	旧版 API 文档
callytics-sdk	旧版 TypeScript SDK
rc-analyze-cloudflare-worker	早期 Cloudflare Worker 实验
rc-analysis-golang	早期 Go 语言实验
eino-call-analysis	早期通话分析实验
remote-mcp-server-authless	MCP server 实验
deprecated-*	各种废弃的 monorepo 和 pipeline

技术栈总览¶

层级	技术
前端框架	Vue 3（主产品）/ Next.js（Landing Page）
UI 组件	shadcn-vue / shadcn-ui + Tailwind CSS
后端框架	Hono
运行时	Bun (开发) / Node.js (Lambda)
云平台	AWS（计算、存储、AI）+ Cloudflare（前端托管、Workers）
IaC	AWS CDK (TypeScript)
数据库	DynamoDB
对象存储	AWS S3
AI/ML	Kimi K2 / Claude（通话分析，Bedrock 备选）/ Deepgram（语音转文字，AWS Transcribe 备选）
认证	AWS Cognito / Lark SSO
监控	Sentry（`lark-dm-bot` 私信告警 + 每日报告）+ GitHub 事件 Lark 群通知（`cloudflare-github-webhook-rerouter`）
CI/CD	GitHub Actions（self-hosted runner）
包管理	Bun (主产品) / pnpm (Landing Page)
Linting	oxlint (Rust-based，非 ESLint)
测试	Vitest / Jest

环境与域名¶

环境	API 域名	前端域名	AWS Region
test	`studio-api-test.retaintive.ai`	test 环境 Cloudflare Pages	us-west-2
pre	`studio-api-pre.retaintive.ai`	pre 环境 Cloudflare Pages	us-east-2
prod	`studio-api.retaintive.ai`	`studio.retaintive.ai`	us-east-1

内部工具： - RingCentral Monitor: ringcentral.retaintive.ai