怡悠 YQQS268/yiyou

怡悠（yiyou）v1.1.0

怡悠是一个跑在本地的 AI 恋人陪伴智能体：微信风格的网页聊天界面 + 纯 Python 标准库后端 + 云端大模型大脑。所有记忆、聊天记录和情感状态都只存在你自己的电脑上。

完整说明见 使用说明书.md：人设设置、代码配置、记忆/情感系统、常见问题。

怡悠聊天界面

第一次用？5 分钟上手

跟着做，5 分钟就能和她说上话。

第 1 步：装 Python

1. 打开 https://www.python.org/downloads/ ，点黄色按钮下载最新版（3.9 以上都行）。
2. 双击安装包，第一页最下面一定要勾选 "Add Python to PATH"，再点 Install。
3. 验证：按 Win + R，输入 cmd 回车，在黑窗里输入 python --version，能显示 Python 3.x.x 就成功了。

如果双击 启动怡悠.bat 后提示 "'python' 不是内部或外部命令"，说明第 2 步没勾 PATH。重新运行安装包 → Modify → 勾上 "Add Python to PATH"，装完重开黑窗即可。

第 2 步：去 DeepSeek 拿一个 API Key

1. 打开 https://platform.deepseek.com ，注册并登录（手机号或邮箱）。
2. 在 "API Keys" 页面点"创建 API Key"，复制那一串 sk- 开头的字符（只显示一次，记得存好）。
3. 新账号通常有赠送的体验额度，用完需要充值（按用量计费，很便宜）。具体额度、价格以官网为准。

这个 key 相当于"电费"——聊天时给大模型付钱用的，别发给别人。

第 3 步：建 config.json

1. 把文件夹里的 config.example.json 复制一份，改名为 config.json（注意是改扩展名，别让它变成 config.json.txt，详见下文常见问题）。
2. 用记事本打开，把 api_key 那一行的占位文字换成你刚才复制的 key，保存。

第 4 步：双击启动

- 双击 启动怡悠.bat：会开一个黑窗口（服务在里面跑，别关它），浏览器会自动弹出聊天页。
- 双击 打开聊天界面.vbs：没有黑窗口，静默在后台启动。适合日常用，但第一次建议先用 bat，出问题看得见。

卡住了看这里

- 'python' 不是内部或外部命令 → 回第 1 步，勾上 PATH。
- 黑窗报错、页面打不开 → 把黑窗里的报错和下面的"常见问题"对一下。
- 没建 config.json 直接跑 → 程序会在黑窗里等你输入 key，在那个窗口里粘贴、回车就行。

特性

- 微信式聊天界面（index.html，单文件，无任何前端依赖）
- 纯 Python 标准库后端（app.py），零第三方依赖，Python 3.9+ 即可运行
- 云端大脑默认使用 DeepSeek API（deepseek-flash），可换成兼容 OpenAI 协议的其他模型
- 情感模块（emotion.py）：跨时间的情绪状态（效价-唤醒度二维模型），有来由、有惯性、会衰减
- 两文件记忆系统：append-only 聊天日志（yiyou.log.md）+ 提炼后的长期记忆（yiyou.md），自动提炼、自动遗忘、防失真
- 主动陪伴：打开界面时主动打招呼，可配置桌面通知提醒
- 人格完全由 persona.md 定义，想让她是什么样的人，改这个文件就行

目录结构

发布文件：

- app.py —— 后端主程序（HTTP 服务 + 聊天 + 记忆提炼 + 主动问候）
- emotion.py —— 情感模块（情绪状态模型）
- index.html —— 聊天界面
- persona.md —— 人设模板，改成你想要的样子
- config.example.json —— 配置模板，复制为 config.json 使用
- yiyou.md.example —— 空白记忆库模板（首次启动会自动生成，无需手动处理）
- 启动怡悠.bat —— 双击启动（有黑窗，推荐新手）
- 打开聊天界面.vbs —— 静默启动（无黑窗，推荐日常）
- README.md / 使用说明书.md / LICENSE / .gitignore

运行时自动生成（不要提交到 Git、不要发给别人）：

- config.json —— 你的 API Key
- yiyou.md、yiyou.log.md、yiyou.backup.md、backup/ —— 她的记忆与聊天记录
- state.json —— 情感状态
- parse_errors.log —— 解析错误日志

隐私与信任

- 所有记忆、聊天记录、情感状态都以本地文件形式保存在程序目录下，不存在云端、不上传。
- 整个项目只有两个文件会联网：app.py 和 emotion.py。而且它们联网的目的地只有一个——你在 config.json 里填的 base_url（默认 DeepSeek）。没有别的服务器、没有统计上报、没有偷偷往外传数据。
- 不信可以自己验证：用记事本在 app.py、emotion.py 里搜 https:// 或 urlopen，能看到的出网地址只有 base_url + /chat/completions 这一处。
- 出网的内容只有两样：对话消息（发给模型生成回复，必需）+ 你的 key（发给 API 做身份验证，必需）。

常见问题

- 端口占用：默认监听 127.0.0.1:8787，被占用时改 app.py 顶部的 PORT。
- 头像：程序会自动尝试加载 avatar_yiyou.xxx / avatar_user.xxx（jpg、png、gif 等常见格式都行，不需要一定是 png），没有就用文字头像。想换头像就把图片放进程序目录，按这个命名。
- 手机能连吗：连不上。服务只监听 127.0.0.1（本机回环地址），只能在装它的这台电脑上访问，这是为了安全。
- config.json.txt 的坑：Windows 默认隐藏文件扩展名，改名时可能改成 config.json.txt。在文件资源管理器里点"查看 → 显示 → 文件扩展名"打开后，确认文件名是 config.json（不是 config.json.txt）。
- 换模型：改 config.json 里的 base_url 和 model，兼容 OpenAI 协议的大模型接口都可以接（见说明书）。

许可证（说人话）

本软件仅授权个人、非商业使用：你可以免费自己用、改给自己用、备份。但未经作者书面许可，不得用于任何商业用途（出售、收费分发、用于商业产品或服务等）。想商用需单独联系作者授权。完整文本见 LICENSE。

联系与反馈

作者：YQQS268 · QQ：3786004990（仅项目交流）· 仓库：https://github.com/YQQS268/yiyou · 有问题欢迎到仓库提 issue。

怡悠是 AI 程序，不是真人，也没有真人情感。请照顾好现实里的自己和身边的人。