omiki1 / YukiAI

# Yuki · 一起看剧情的朋友
一个正在开发的 Galgame 共读伙伴。用户主要在玩galgame时：一起交流感受、分析剧情和伏笔、梳理人物动机与关系；遇到其他国家文化、历史、文学典故时结合上下文讨论。默认跟随已读进度，不剧透。
## 当前进度
- 独立的透明桌面小窗，默认320×460，最小280×380；角色随窗口一起缩小。
- 操作栏位于模型头顶附近，平时隐藏；鼠标移到角色可见部分时显示，移向按钮时保留，离开后收起。可拖动“Yuki”移动窗口，键盘 Tab 也能打开操作栏。设置等面板打开期间，操作栏暂时保留在窗口顶端。
- 单条聊天气泡，短回复随文字缩窄，长回复默认最多三行，点击“展开”查看全文。
- 默认使用像素复古界面；在“设置 → 外观 → 界面主题”可切换像素、磨砂玻璃、纸本、霓虹和经典五种外观。选择会在本机记住，更新不覆盖已有主题偏好。像素字体随应用提供，标题和按钮使用点阵字，剧情正文与回复保持普通字体。
- 点“聊聊”才打开输入框，发送时收起；“···”中提供回想、新聊和收起气泡。回复不会自动抢走输入焦点。
- 中文文字聊天、逐字显示、当前对话回想和本地记录。
- 接入本地提供的 Live2D 模型，保留表情、眨眼和固定头身；默认缩小至此前的85%，可用滑杆调整60%～110%。
- 模型上方的设置中可配置聊天与语音服务；支持 OpenAI 兼容 LLM、OpenAI 兼容 TTS 及 Fish Audio。保存后立即生效。
- 语音默认关闭，可手动试听或开启自动朗读当前中文回复。没有麦克风、摄像头、读屏或游戏操作功能。
- 对话框可收起为“Yuki · 聊两句”，草稿和回复会保留。
- 剧情记录第一版：手动收录已读原文、阅读位置、书签、分支与回档；重启后恢复。共读问答使用当前路线范围内的原文与讨论，可点开原文依据。
- Hook 自动取词第一版：在小窗选择游戏进程与正文来源，预览确认后自动记录新台词；支持暂停、断开、手动 Hook 码、连续重复过滤与逐字增长合并。回档或切换共读会暂停记录。
- 当前路线会整理场景摘录和人物说辞：人物原话与旁白提及分开，回档后只保留这条线已读范围内的内容，整理本身不调用模型。建立共读时可选 Galgame 或小说。小说按章节切开，认识“某某说道”，未读章节不会进入提问。跨周目记忆和自动识别游戏存档尚未实现。
- 记忆管理：查看各次共读的原文、路线、书签、全部旧讨论数量和本机占用；可清空讨论、删除某次共读、找回或删除普通聊天，以及本机备份、恢复副本、删除备份和整理数据库空闲空间。清理会先预览范围，再明确确认。
- 接着上次读：原文页提供带原句入口的阅读回顾和最近聊过的问题；疑问、猜测和感受可以保留为共读手记，支持关联原文、修改、标记聊清楚及删除。手记随进度和分支使用，重启后保留，并进入后续共读提问。
- 故事脉络：剧情记录中的“脉络”将已读片段、人物说辞、选项、章节和玩家手记排成卡片，可按原文说话者、类型或关键词找线索，打开完整原句、留下关联想法或准备讨论草稿。回档、切线、备份和清理沿用已有记忆；整理和浏览不调用模型。
- 人物与称呼：核对原文后，明确告诉 Yuki“班长是美咲的称呼”或“这句讨论中的她指美咲”。支持修改、回档版本及删除全部版本；原文不改写，单句指代在推进后失效。
- 首次使用引导、独立的自编体验剧情，以及取词失败后直接粘贴的入口。缺少模型时使用原创纸签界面，聊天和记忆仍可使用。已加入不含私人素材的 Windows 免安装测试包构建，真实玩家安装和留存验证尚未完成。
## 此仓库的范围
这是源码仓库，**不含模型、原画、纹理、API密钥、本地配置、聊天记录、日志、截图、缓存、打包产物或旧参考项目**。Cubism Core 的运行库文件也留在本机。克隆后准备依赖并构建界面即可使用纸签界面；Live2D 素材是可选项。
必要的 Cubism Framework 源码、Core 类型声明及许可说明保留在 `app/vendor/live2d/`。应用代码不依赖旧参考项目。第三方来源见 `third_party/README.md`。
## 目录
| 路径 | 内容 |
| --- | --- |
| `app/src/` | 界面、对话和模型渲染 |
| `scripts/yuki_server.py` | 本机文字接口与静态服务 |
| `scripts/yuki_chat.py` | 文字客户端与角色设定 |
| `scripts/yuki_config.py` | 本机配置、校验及密钥隔离 |
| `scripts/yuki_speech.py` | 可选的云端语音合成 |
| `scripts/yuki_history.py` | 本地聊天记录 |
| `scripts/yuki_story.py` | SQLite 原文、进度、书签与路线范围 |
| `scripts/yuki_characters.py` | 玩家核对的称呼、单句指代及原文关联 |
| `scripts/yuki_capture.py` | 独立取词进程、文本整理与阅读范围绑定 |
| `scripts/install_textractor.py` | 校验并准备官方取词工具，二进制仅留在本机 |
| `scripts/yuki_window.py` | 透明桌面窗口 |
| `scripts/audit_upload.py` | 提交前的源码范围及敏感信息检查 |
| `docs/SYSTEM.md` | 项目结构、阅读记忆和一次提问的完整说明 |
## 本地准备
1. 源码版准备 Python 3.12+、Node.js 和 `requirements.txt` 依赖。可双击 `setup_yuki.cmd` 准备项目内 `.venv` 并构建，之后用 `start_yuki.cmd` 启动；也可用自己已准备好的 Python 直接运行 `start_yuki.py`。启动不再限定开发机路径，命令脚本也支持 `YUKI_PYTHON` 指定解释器。
2. 可选：将自行持有的模型运行文件放到 `app/public/model/`，入口为 `yuki_cutout.model3.json`；将合法取得的 Cubism Core 放到 `app/public/vendor/live2d-core/live2dcubismcore.js`。这些目录不会进入 Git。缺少素材或初始化失败时使用纸签界面，不影响文字共读。
3. 在 `app/` 执行 `npm ci --ignore-scripts`、`npm run check`、`npm run build`。
4. 正常启动后，鼠标移到模型上，在浮现的设置中填写接口。也可先复制 `.env.example` 为 `.env.local` 填写文字服务参数。
5. 使用已配置的 Python 运行 `start_yuki.py`；`--mode preview` 不调用云 API，`--headless` 只启动本机预览服务。默认监听 `127.0.0.1:12393`。
首次打开且未配置聊天