Eidolon-SC

Eidolon-SC 让你以 283 事务所制作人的身份，和原作中的偶像打字聊天或者直接打电话。她用日语原声回答，附上中文字幕；能回忆自己在原作里经历过的剧情；还会记住你说过的事，并在偶像之间「传开」。

原作八个组合的 28 位偶像和事务员七草はづき都已经配好，可以直接对话。部署到公网后，任何人都能用 Google 或 GitHub 登录使用。

[!IMPORTANT] 本项目是非官方的粉丝作品，与万代南梦宫及《偶像大师》系列的版权方无关，角色由 AI 扮演。剧情数据不随仓库分发，需要自行准备（ADR-0003）；角色会通过回复间接地把剧情内容提供给登录的用户，这一风险见 ADR-0006。

📸 预览

✨ 特性

和她说话

• 🎙️ 实时语音通话：基于 WebRTC 的全双工通话，中文、日语都能说，随时可以插话打断她。
• 🇯🇵 日语原声 + 中文字幕：她用日语回答，保留口癖，每句附中文字幕（ADR-0001）；专有名词按读音表念对。
• 🎭 会动的立绘：通话时叠上原作的 Spine 立绘，会呼吸、眨眼、动嘴，随情绪换表情。原作出了新卡，每周同步一次就能穿。
• 📷 她发照片：你开口要，她按自己的样子和当时的情境拍一张发来，只有全年龄的内容（配置指南）。
• 💗 好感度和礼物：你说的话会让她亲近或疏远你，冒犯多了她会挂断电话、结束这段对话。每天在玩法里抽奖得到礼物送给她，她会回应；解锁成就能多得抽奖次数。
• 📅 日历：角色和制作人的生日、日本的节假日，她当天也知道。
• 🗓️ 日程：每周发布的工作，你排进她的一周，她知道并以此说话；做完的工作让她更亲近你（配置指南）。
• 🌙 周期：她也有经期，经前、经期这几天会不舒服，体贴她有回报；你凭她的言行把经期记在周期页，页面替你推算下一次，并讲清怎么算（配置指南）。
• 🍸 VA-283：她来酒吧光顾，你照她的点单调饮品。每天第一次玩完的光顾给一次抽奖，她也会更亲近你；第一次进店有はづき 教你调。画面和调法致敬《VA-11 HALL-A》。
• 💌 搭话：你一阵子没来，她会在对话里先说几句；越亲近来得越早（配置指南）。
• ✉️ 信：在特别的日子，比如更亲近的那天、你的生日、相识纪念，她给你写一封信，用她的声音念给你听（配置指南）。
• 🌅 朋友圈：和你聊过的角色在你的朋友圈里发动态，常带配图，写着地名和东京的天气，其他偶像来赞和评论；你也能赞、能评论，她会回你（配置指南）。
• 🌦️ 天气：她知道东京这会儿的天气；你在档案里设了所在城市，她也知道你那边的天气和预警，隔了一阵或天气不寻常时会关心一句（配置指南）。

她记得什么

• 📖 回忆原作剧情：导入剧情库后，她只回忆自己出场过的正式经历。
• 🔄 与原作同步：一条命令同步粉丝汉化和日语原文，新卡、新活动一周内就能回忆；歌曲和演出也写进她的世界设定。
• 🧠 跨角色共享记忆：对灯織说过的事，恋鐘也会知道，并以「听灯織说……」的口吻提起（ADR-0002）。她记住的事你都能查看和删除。
• 🗂️ 历史对话：随时开新对话，旧的留着翻看，不要了可以删。
• 🪪 制作人档案：称呼、性别、时区和生日都能在设置里改；生日当天她会祝你生日快乐。
• 📊 统计：看你和她们聊了多少回合、通了多久电话、送了多少礼物，可以导出一张分享图。
• ⚡ 按需检索：先判断这句话要不要查资料，寒暄闲聊没有额外延迟。

部署和运营

• 👥 对公众开放：Google 或 GitHub 登录，也可以只让拿到邀请链接的人注册；按用户限流，记忆互相隔离；用户可以彻底删除自己的数据，数据库每天加密备份到异地。
• 📦 数据包：对话、照片、记忆和制作人档案导出成一个 zip，在别的部署导入后接着用；好感度、礼物、日程和酒吧的光顾记录不随行（ADR-0025）。
• 🔑 自带密钥：用户可以填自己的 LLM、语音合成、语音识别和生图密钥，用自己的额度，满足条件时不占限额（配置指南）。密钥只存在浏览器里（ADR-0017）。
• 🛠️ 后台：看用量、花费和进行中的通话，改模型和限额不用重启，封禁用户、发公告；看不到任何人的对话和记忆。
• 🚦 服务状态：用户在对话列表就能看到各项服务正不正常。
• 🔌 服务可以替换：模型支持 OpenAI Chat Completions、Responses 和 Anthropic Messages 三种接口；语音识别、向量化各有两家可选，判断模型有三家；每项服务都可以单独走网络代理。
• 🚀 一键部署：Docker Compose 生产配置，自带 Caddy（自动 HTTPS）和 coturn（TURN 中继）；CI 构建镜像并发布到 GHCR。

🚀 快速开始

让 Agent 帮你部署

不熟悉 Docker 和各种 API key 也没关系：把下面这段话发给你用的编程 Agent（Claude Code、Codex、Cursor 等都行），它会照仓库里的部署说明一步步带你做，碰到报错也会帮你查。

帮我部署 Eidolon-SC（https://github.com/Sallyn0225/eidolon-sc）。先把仓库克隆下来，
再照仓库里 docs/agents/deploying.md 带我一步步做。要我注册账号、申请 key 的地方告诉我怎么做；
key 我自己填进 .env，不贴给你。

[!NOTE] 为什么部署好了没有剧情、通话里也没有立绘？ 剧情文本和立绘素材的版权不属于本项目，不随仓库分发，仓库里只有同步工具。部署后自己同步一次就有了，Agent 会带你做（见部署说明的「剧情库」「立绘」）。同步之前，角色只凭人设回复，通话里只显示背景图。

自己动手

需要 Docker 与 Docker Compose，以及一个支持流式输出和工具调用的对话模型。不想装 Docker（比如在 Windows 上），也可以用 uv 和 Node.js 直接跑前后端，见下面的「开发」和部署说明的「三种跑法」。

git clone https://github.com/Sallyn0225/eidolon-sc.git && cd eidolon-sc
cp .env.example .env    # 填写 CHAT_LLM_BASE_URL、CHAT_LLM_API_KEY、CHAT_LLM_MODEL，再加一行 EIDOLON_DEV_LOGIN=1
docker compose up --build

打开 http://localhost:3000 是落地页。点右上角的「登录」，在登录面板里选「开发登录」，随便填一个名字，同意隐私政策和使用条款、声明年满 13 岁后就进入对话列表，点一位偶像开始对话。

只填对话模型时能文字聊天。按需再补上其他服务的密钥，逐步开启语音通话、剧情回忆、记忆和立绘：

每项怎么配、配了以后有什么效果，见 配置指南；所有环境变量的说明见 .env.example。

配好以后运行 docker compose run --rm backend eidolon doctor（直接跑时在 backend/ 下 uv run --env-file=../.env eidolon doctor），它会逐项试一次各项服务，说明哪一项连不上、key 不对或者要走代理。

🧩 架构

flowchart LR
    subgraph Browser["浏览器 · Next.js"]
        Landing["落地页"]
        UI["对话列表 · 对话 · 通话层"]
        Admin["后台"]
    end

    subgraph Backend["后端 · FastAPI + Pipecat"]
        API["HTTP API"]
        Call["通话管线"]
        Engine["对话引擎"]
        Retrieval["检索"]
        Memory["记忆"]
        DB[("SQLite<br/>对话 · 照片 · 记忆 · 剧情库")]
    end

    Bucket[("对象存储<br/>立绘 · 招呼 · 酒吧音乐")]

    UI -- "文字回合 /api/*" --> API
    Admin --> API
    UI <-- "WebRTC 语音 + 字幕" --> Call
    Landing & UI -. "立绘、招呼和酒吧的音频" .-> Bucket
    API --> Engine
    Call -- "语音识别<br/>Soniox 或阿里云百炼" --> Engine
    Engine -- "Fish Audio 语音合成<br/>（带读音表）" --> Call
    Engine --> Retrieval
    Engine --> Memory
    Retrieval --> DB
    Memory --> DB
    Engine <--> ChatLLM["对话模型"]
    Retrieval <--> Judge["判断模型<br/>Jev、Clef 或阿里云百炼"]
    Retrieval <--> Emb["向量化<br/>Qwen3-Embedding 或 Gemini"]
    Retrieval <--> SF["硅基流动<br/>Qwen3-Reranker"]
    Memory <--> BgLLM["后台模型"]
    Engine <--> Image["生图<br/>NovelAI"]

• 打字和说话走同一个对话引擎，写进同一条对话记录；通话只是在引擎外面包了一层语音识别和语音合成。
• 对话模型以 <ja>…</ja><zh>…</zh> 的分段格式流式输出，日语一到就送去合成，不用等整段回复结束。

📚 文档

🌐 部署

生产配置 docker-compose.prod.yml 包含 caddy（HTTPS 入口）、frontend、backend 和 coturn（TURN 中继）四个服务，前后端镜像由 CI 发布到 GHCR：

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

数据库由 deploy/db-backup.sh 每天加密备份到私有存储桶，默认保留 30 天。完整步骤见 部署指南。

💻 开发

后端（Python 3.11+，backend/，用 uv）：

cd backend
uv sync
uv run pytest && uv run pyright && uv run ruff check
uv run --env-file=../.env eidolon serve   # 启动在 :8000，读取 ../characters/characters.toml

前端（Next.js 16 + shadcn/ui + Tailwind CSS v4，frontend/）：

cd frontend
npm install
npm run typecheck && npm test && sh scripts/check-discipline.sh
npm run build && BACKEND_URL=http://localhost:8000 npm run start   # 启动在 :3000，/api/* 转发给后端

• 界面：克制的 LINE 风格，属于她的地方用她的印象色；落地页自成一个永远深色的视觉世界（ADR-0016）。视觉规范见 DESIGN.md，组件写法的约定见 frontend/AGENTS.md。
• 立绘：要看立绘时，前端也要带上和 .env 一样的 EIDOLON_STAND_ASSETS_URL。
• README 的截图：前后端都跑起来后，在 frontend/ 下运行 npm run readme-media，会重新拍下 docs/images/ 里的截图和动图。
• CI：每个 PR 和 main 上的推送都由 GitHub Actions 跑上面这些检查和 shellcheck，再构建两个镜像；推送到 main 或 v* 标签时发布到 GHCR。Dependabot 每周一提依赖更新。

📁 项目结构

eidolon-sc/
├── backend/          # Python 后端：FastAPI + Pipecat；对话引擎、通话、检索、记忆、同步与命令行（eidolon）
│   ├── src/eidolon/
│   ├── eval/         #   重排、判断模型和记忆的评测集（只含问题与标注，不含剧情原文）
│   └── tests/
├── frontend/         # Next.js 前端：落地页、对话、通话层、设置、后台
├── characters/       # 角色配置、人设、资料、头像、读音表、世界设定
├── corpus/           # 剧情数据和镜像缓存（不进仓库）
├── deploy/           # Caddyfile、剧情库与立绘的同步脚本、数据库备份脚本
├── scripts/          # 配置 OAuth 应用的向导（setup-oauth.sh）
├── docs/             # 配置指南、部署指南、架构决策记录、README 的图片
├── docker-compose.yml          # 本地开发
└── docker-compose.prod.yml     # 生产部署

📄 许可证

本项目的代码以 GNU Affero General Public License v3.0（AGPL-3.0）或（由你选择）任何更高版本发布。如果你修改了本项目并通过网络向他人提供服务，需要向这些用户公开修改后的源代码。

许可证只覆盖仓库里的代码和文档，下面这些不在范围内：

• 原作的内容：剧情数据、角色音色、立绘素材不在仓库中，使用时须遵守各自来源的条款（ADR-0003）。仓库里的人设、角色资料、头像和 README 的截图里，角色与设定属于原作版权方。
• Spine Runtimes：通话层立绘用的 frontend/public/vendor/spine-3.6/ 原样收录，适用它自己的 Spine Runtimes 许可证（ADR-0009）。LICENSING.md 里有一条 AGPL 第 7 节的附加许可，允许两者组合分发。
• VA-11 HALL-A 的素材：酒吧用的原版图片（frontend/public/bar/img/，含配方卡上的官方中文）、外框上的「VA-283」标志和原版的配乐、音效，版权归 Sukeban Games，见 LICENSING.md。配乐和音效不在仓库里，部署时传进存储桶。
• 字体和音效：落地页的字体子集和酒吧的像素字体「缝合像素」适用 SIL Open Font License（见 frontend/src/app/(landing)/fonts/、frontend/public/bar/fonts/）；通话音效的来源和许可见 CREDITS.md。

🙏 致谢

• LAPLACE Eidolon：为虚拟主播明前奶绿打造的实时语音 AI 分身，本项目的架构参考（未复用其代码）
• LAPLACE Cycles：周期页推算算法的参考，感谢它公开了做法（未复用其代码）
• SCTranslationData：剧情文本与中文翻译
• ShinyColorsDB：原文剧情的镜像与立绘素材
• Pipecat：实时语音管线与 WebRTC 传输
• Fish Audio：语音合成
• Soniox、阿里云百炼：语音识别
• 硅基流动：Qwen3 Embedding 与 Reranker
• Google Gemini API：Gemini Embedding（可选的向量化服务）
• TypeSafe Jev、OpenRouter、Cloudflare Workers AI、阿里云百炼：判断模型
• Spine Runtimes：立绘的播放（spine-ts 3.6）
• VA-11 HALL-A（Sukeban Games）：酒吧的画面、调法和点唱机致敬原作，用了原版的图片、配乐和音效
• 缝合像素：酒吧的像素字体
• im@sparql、Lantis、ふじわらはじめ、imas-db、wikiwiki：世界设定里的偶像、唱片和演出资料
• OpenStreetMap 贡献者（ODbL）、Wikidata：朋友圈里地点的名字和坐标
• Open-Meteo（CC BY 4.0）：朋友圈和对话里东京的天气
• 和风天气：制作人所在的城市，那边的天气和气象预警
• LINUX DO：从技术选型、开发到部署运维，许多经验来自这里的分享

《偶像大师 闪耀色彩》及其角色的版权归 ©Bandai Namco Entertainment Inc. 所有。本项目为非官方粉丝作品，与版权方无关，角色由 AI 扮演。《VA-11 HALL-A》及其图片、配乐和音效的版权归 ©Sukeban Games 所有。