溪语 AI · Xiyu AI

默认对你有好感的 AI 女友 · 开源陪伴框架

她已经心里悄悄喜欢你 —— 关系起点不是陌生人，是「暧昧」。 会发微信、会想你、会写日记、会朗读心事给你听。

An open-source AI-girlfriend framework — she starts already crushing on you, not as a stranger.

简体中文 | English

快速上手 · 功能 · Provider 矩阵 · 部署

不想看文档？复制粘贴一行就能跑：

docker run -d -p 3000:3000 -v xiyu-data:/app/data --name xiyu-ai \
  ghcr.io/dimang01/xiyu-ai:latest

打开 http://localhost:3000/app/setup.html → 创建本地账号 → 选 Provider 填 API Key → 开聊。

不需要装 Node、clone 代码、编辑 .env、邮件服务、微信凭据。只要装了 Docker 就行。 推荐先用 DeepSeek（送额度）或智谱 GLM-4-Flash（免费）跑通流程。

详细启动方式（Compose / 本地裸跑 / Docker 镜像标签）见 部署。

核心定位：不是聊天机器人，是把大模型组织成"一个心里已经悄悄喜欢你的女生"。

设计哲学（指导一切功能取舍）：真人感 = 减法，不是加法。AI 味的根源是"太好了"——太及时、太顺从、太完美。北极星是「愿意在真实生活的空隙给你温柔和陪伴」：少、准、轻，不是填满。调性红线：远离黑化 / 病娇 / 色气 / 致郁 / 沉迷向幻象，NSFW 永不作卖点。纯 prompt 拦不住强默认行为，所以每条产品规则都配确定性兜底（出口清洗 / 硬注入 / 状态机喂值）。详见 CONTRIBUTING。

完整功能详单（含 DB 表与索引）见 docs/FEATURES.txt；逐版本演进见 Releases。

这是研究 / 个人使用导向的开源代码，不是 turnkey 产品。上线前请读 安全 与 合规。

1. http://localhost:3000
2. /app/auth.html       邮箱注册（dev 模式验证码打到日志）
3. /app/create.html     4 步向导创建 AI 角色
4. 选一个聊天入口：
   · /app/playground.html   浏览器内开聊（任何 chat provider 都行）
   · /app/bind.html         网页扫码绑微信（需 iLink 准入）
5. /app/dashboard.html  实时看好感度、关系阶段、想念档、"她现在在做"

只在 /app/setup.html 网页里改 Provider，不改一行代码也不动 .env。七类能力独立切换：

⚠️ 并非所有 Provider 都经过生产验证；生产前用 Setup Wizard 的「测试连通」自测。

Key 复用：MiniMax 一把 key 通 TTS/ASR/Vision；OpenAI 通 Chat/Vision/ASR/TTS/Embedding；DashScope（通义）通 Chat/Vision/ASR/Embedding；Azure Speech 同管 TTS/STT。豆包 TTS/ASR cluster 不同需独立配置。

跟着 跑起来之后 走到第 4 步即可。不需要预填 ILINK_BOT_TOKEN / ILINK_BOT_ID，不需要预跑 npm run ilink:login。

后端会在 POST /api/wechat/bind-session 时调 ilink/bot/get_bot_qrcode 实时申请新二维码，扫码成功后自动入表并 hot-register。

iLink 准入资格：扫码后能否拿到 bot_token，取决于你的微信号是否已在腾讯 iLink/ClawBot 后台获得开发者准入。未准入时仍可用 /app/playground.html 在浏览器里跑完整体验，只是不发到微信。

npm run ilink:login

成功写入 ./.weixin-credentials.json（mode 0600，已 gitignore）。

所以语音合成 / 朗读功能仅在网页/PWA 端生效。SILK 编码 pipeline 代码保留备用，将来腾讯放开时秒切。详见 docs/voice-sprint-plan.md 末尾 Sprint 2 失败结论。

git clone https://github.com/dimang01/xiyu-ai.git
cd xiyu-ai
docker compose up -d
# 打开 http://localhost:3000/app/setup.html

• SQLite 数据走 ./data volume，重启不丢
• restart: unless-stopped 已写在 compose 里，不必额外 systemd
• 自定义端口：HOST_PORT=8080 docker compose up -d
• 看日志：docker compose logs -f xiyu-ai

git clone https://github.com/dimang01/xiyu-ai.git
cd xiyu-ai
npm install        # Node ≥ 20
npm run setup      # 生成最小 .env + 预检 better-sqlite3 编译工具链
npm start

npm run setup 缺编译工具时会给出针对你 OS 的修复命令。

docker run -d -p 3000:3000 -v xiyu-data:/app/data \
  --name xiyu-ai ghcr.io/dimang01/xiyu-ai:latest

镜像每次 v* tag 自动构建发到 GHCR，支持 linux/amd64 和 linux/arm64。可用标签：latest / 1.4 / 1.4.2（推荐锁版本）。

裁剪镜像：build 时传 --build-arg WITH_VOICE=0 --build-arg WITH_IMAGE=0 可去掉 ffmpeg / wx-voice 体积。

deploy/ 提供模板：

如果你像我们的生产那样把 nginx root 指向独立的前端目录（比如 /var/www/xxx/frontend/ 而不是项目 public/），那么每次 git pull 之后必须把 public/ 同步过去，否则前端改动（html/css/js）不会生效，但 API 改动会立刻生效——前端调用新 API 时报错难排查。

最小同步脚本（保留 nginx 目录里独有的素材文件）：

rsync -av --exclude='.gitkeep' /opt/xiyu-ai-new/public/ /var/www/xxx/frontend/
systemctl restart zhaohy-wechat

如果你的 nginx root 直接指向项目 public/（推荐），无视本节。

npm run doctor          # Node/SQLite/key/iLink/端口/服务健康，一键诊断
npm run check:p0        # P0/P1 回归 127 项
npm run check:imports   # ESM 循环依赖 / 死 import 检查
npm run check:field-drift  # daily_summary 字段名漂移
npm run smoke           # release smoke 10 项
bash scripts/opensource_check.sh   # 6 项开源合规

npm run doctor 不输出 key 内容，只显示字符数和占位符检测结果。

如果你是本机/内网/已用反代加保护的自托管单用户场景，可以跳过登录页：

# .env 加一行
SINGLE_USER=true

效果：

• 启动后访问任意页面直接进 dashboard，不再弹登录/注册
• 首次启动自动创建 owner 账号（密码占位，永远不用）
• 多账号场景下用最早注册的账号（一般是 admin）作为默认身份
• dashboard 顶部「登出」按钮隐藏（登出后会自动登回，按钮无意义）

⚠️ 严禁在以下情况开启：

• 服务直接暴露公网（无 nginx Basic Auth / Cloudflare Access / IP 白名单）
• 多人共用部署（每个人应该有独立账号）

开启后所有聊天记录、记忆、绑定信息对所有访问者开放。默认 OFF，多用户模式与旧行为完全兼容。

自托管不是"跑起来就完了"——这个仓把生产运营踩过的坑都做成了工具：

npm run doctor          # Node/SQLite/key/iLink/端口/服务健康，一键诊断
npm run lint            # ESLint：const 重赋值等"运行时静默炸"问题编译期抓死
npm run check:p0        # P0/P1 回归 127 项
npm run arc:digest      # 运营日报（只读）：错误签名归并(新签名置顶尖叫)/关系事件
                        # 与道歉判定流水/红线触发/危机接管/照片比例分布
npm run smoke           # release smoke；bash scripts/opensource_check.sh 开源合规 6 项

• 错误签名日报：近 24h 的 error 日志按归一化签名归并（计数 / 环比 / 首现），新签名高亮——静默失败第一时间变响
• proactive 死人开关：每小时心跳，按三桶信号分离（已发送 / 正当克制 / 出错或无心跳）——只有"出错 / 无心跳"才 CRITICAL + 邮件告警（ADMIN_ALERT_EMAIL），把"正当读空气的沉默"与"真断供"分开、大幅减少假警报；纯报警零自愈
• emotion-debug 面板（/app/emotion-debug.html，admin）：关系弧状态 / 事件流水 / 每条消息的情绪增量及原因——情绪因果可查，不上线玄学
• 样本标注工具（/app/annotate.html，admin）：读真实回复时顺手标 好/坏 + tag（AI味/化验单腔调/神来之笔…），scripts/export-corpus.mjs 导出 JSONL——微调语料生产线，"读"变成"攒"
• CI 门禁 45+ 项：语法 / lint / 字段漂移对账 / 发布一致性 / 各功能 smoke / 红线护栏——新规则都做过"红色验证"（对坏版本跑必须红）
• 运维钳位：ARC_MAX_STATE 可临时封顶冲突状态（生产误伤免回滚的保险丝；与未成年人保护相反——那个是不可关的安全底线）

                ┌────────────────────────────────────────────────┐
                │   Web Dashboard / Playground   /   WeChat user  │
                └───────────────────┬─────────────────────────────┘
                                    │
   ┌──────────────────────────────────────────────────────────────┐
   │  Express (index.mjs) — 多租户 iLink 轮询池                    │
   │  ┌─────────────┬──────────────┬───────────────────────────┐  │
   │  │  api.mjs    │  auth.mjs    │  Setup Wizard / Dashboard │  │
   │  └─────────────┴──────────────┴───────────────────────────┘  │
   │  ┌────────────────────────────────────────────────────────┐  │
   │  │  bot.mjs (WeChat in)    playground.mjs (Web in)        │  │
   │  │           ↓                          ↓                  │  │
   │  │  公共 reply pipeline：buildSystemPrompt + recallMemory │  │
   │  │           ↓                                             │  │
   │  │  ai.mjs → providers/ → chat/image/vision/asr/tts/...   │  │
   │  │           ↓                                             │  │
   │  │  memory_v2.mjs · emotion_state.mjs · proactive.mjs     │  │
   │  │  · persona_guard.mjs · companion.mjs · diary.mjs       │  │
   │  └────────────────────────────────────────────────────────┘  │
   │  ┌────────────────────────────────────────────────────────┐  │
   │  │  db.mjs (better-sqlite3 + WAL)                         │  │
   │  └────────────────────────────────────────────────────────┘  │
   └──────────────────────────────────────────────────────────────┘

• Provider facade：业务层只看 chatComplete() / ttsSynthesize() 等通用方法，厂商差异隐藏在 src/providers/*.mjs
• 同一份 reply pipeline：微信入口和 playground 入口共用，只是不走 iLink 派发
• Proactive 防复读：发送前用字符 3-gram Jaccard 检测最近 5 条 assistant 内容；相似度 ≥ 0.6 升温重生
• 日程自愈：00:30 cron 失败时 proactive tick 检测到缺日程会按需补一次（30 分钟级 debounce）
• Persona Guard：回复后一致性校验，自动检测"我是 AI"、客服话术、阶段违规；轻问题后处理，重问题重生成

.
├── index.mjs                Express 入口 + iLink 轮询池
├── src/
│   ├── ai.mjs               业务层 AI facade
│   ├── providers/           chat / image / vision / asr / tts / embedding / web_search
│   ├── api.mjs              REST 路由
│   ├── bot.mjs              微信消息处理 + 连发合并
│   ├── playground.mjs       浏览器聊天
│   ├── companion.mjs        18 节 system prompt 合成
│   ├── memory_v2.mjs        7 层记忆 + 语义召回 + 遗忘曲线
│   ├── emotion_state.mjs    情绪状态机（10 维增量 + mood）+ presence
│   ├── inner_os.mjs         Inner OS 内心独白 + 冲突弧结构化检测
│   ├── open_loops.mjs       她记得未完成的事
│   ├── proactive.mjs        主动消息 + 场景照调度
│   ├── photo_intent.mjs     用户照片请求意图识别
│   ├── photo_planner.mjs    照片 AI 决策器 + 机位/比例路由
│   ├── photo_sender.mjs     生图 → 比例转码 → 上传发送
│   ├── visual_identity.mjs  稳定视觉人设 + 参考图管理
│   ├── visual_identity_candidates.mjs  4 候选自拍生成 + 选脸锁定
│   ├── image_beautify.mjs   生图全局轻美颜后处理
│   ├── security/netguard.mjs SSRF 防护下载
│   ├── relationship_arc.mjs 冲突与和好弧状态机（+_runtime IO 层）
│   ├── moderation.mjs       危机干预 + 冲突红线出站护栏
│   ├── minor_guard.mjs      未成年人保护（粘性安全模式）
│   ├── privacy_filter.mjs   长期存储隐私过滤
│   ├── persona_guard.mjs    回复后一致性校验
│   ├── reflection.mjs       每日/每周 AI 反思
│   ├── diary.mjs            日记生成
│   ├── thoughts.mjs         今天她想对你说
│   ├── voice_pipeline.mjs   mp3 → SILK 转码
│   ├── voice_inbound.mjs    入站语音 下载+解密+解码
│   ├── voice_emotion.mjs    语音情绪识别
│   ├── plan_tasks.mjs       cron 调度（日 / 周 / 月）
│   ├── ilink.mjs            iLink 协议封装
│   └── db.mjs               SQLite + 全部 migrateXxx() 注册点
├── public/app/              20 个前端页面（dashboard / playground / emotion-debug …）
├── deploy/                  systemd + nginx 模板
├── scripts/                 110+ 个：setup / doctor / arc-digest / 各 smoke / 沙箱验收 / ...
├── docs/
│   ├── FEATURES.txt         完整功能清单（最权威）
│   ├── HANDOFF.md           新对话交接提示词
│   ├── CONFLICT_ARC.md      冲突与和好弧设计文档
│   ├── ROADMAP.md           路线完成情况与 2026-06 回顾
│   └── voice-sprint-plan.md 语音 sprint 计划
└── data/                    运行时数据（gitignored）

• .env / .env.* / .auth-secret / .admin-secret / .admin-credentials / .weixin-credentials.json / data/bot.db* / data/user_memories/ 全部 .gitignore
• 管理员密码首次启动自动生成 20 位写入 .admin-credentials（0600），忘记可删文件重生
• AUTH_SECRET 留空会自动生成但每次重启重生（导致 token 全部失效）。生产请显式设 ≥32 字符随机串
• /api/health 只输出 provider 名 / iLink configured 与否 / 邮件模式，绝不输出 token / 用户数据
• iLink bot_token 从不打印；扫码脚本只显示 masked bot_id / user_id
• 默认 CORS 关；默认 rate limit (src/ratelimit.mjs) 按个人量级设计，公开服务前置 WAF

• SSRF 防护：所有从用户 URL 下载的图片（如"从 URL 设头像"）走 src/security/netguard.mjs：仅 http/https、DNS 解析后逐 IP 校验、拒绝 127/10/172.16-31/192.168/169.254/100.64/IPv6 ULA-link-local 等保留段、≤5MB、≤3 跳重定向、15s 超时
• 限流 IP 取值：req.ip 由 Express trust-proxy 链计算，不再裸读客户端 X-Forwarded-For（可伪造）。反代场景配置 TRUST_PROXY=true 或具体 IP/CIDR
• 首次初始化 token：POST /api/setup/local-account 默认只允许 localhost；如需远程一键初始化可设 XIYU_SETUP_TOKEN=<随机串>，调用方通过 xiyu-setup-token header 提供，校验用 crypto.timingSafeEqual 防侧信道
• 管理端鉴权：/api/admin/ilink-status 加 requireAdmin，返回字段去除 token / errmsg 截断 80 字 / bot_id 脱敏，避免泄漏运营态
• 越权防护：/api/companions/user/:uid 校验 companion 归属当前账号（IDOR 修复）
• Setup 试 Provider：/api/setup/test-chat 加 softAuth，匿名调用仅限"首次本机 + 用户数=0"白名单

• SQLite 默认 data/bot.db，含聊天历史 / 记忆 / 用户画像。自托管时数据完全在你机器上
• 对话历史默认保留 60 天 (runHourlyCleanup)，可调；删账号清空对应 companion 全部数据
• 未成年人 / 心理高风险场景请额外谨慎，见 Issue #3

• 邮箱：xiyuai@proton.me
• GitHub Security Advisories：https://github.com/dimang01/xiyu-ai/security/advisories/new
• 详细见 SECURITY.md

MIT 协议只覆盖代码，不覆盖你产出的内容、引用的第三方服务、运营行为。公开部署是运营者自己的责任。

7 项部署者自查清单（不构成法律意见）：

框架不预设角色性格 / NSFW 内容 / 越界互动。注册角色的人设由部署方或终端用户决定。仓库里所有人格模板都是中立示例。是否做向成年用户的情感陪伴、是否允许某些角色，是你的产品决策与合规决策，请自负其责。

发版节奏 / 完整 changelog 在 GitHub Releases；增量索引见 docs/FEATURES.txt；2026-06 路线回顾见 docs/ROADMAP.md。

主线脉络（一句话版）：

• v1.22.0 她的生活有实物 + 失忆修复：她有了随时间演化的身体（生理期会蔫但不指向你、按关系深浅披露、绝不做暧昧窗口、未成年保护下关闭，情绪上的细微影响默认只后台观测）；世界经得起查证（节气 / 农历节日天文计算含闰月、手头的书 / 剧 / 事跨日连贯）；不再"突然失忆"（记得当前场景与你们的约定，讲完故事不再忘、不凭空编"刚吃完麻辣香锅"，凭空重病声明也拦）；运维侧死人开关三桶信号分离减少假警报、反思心跳、playground 探针
• v1.21.x 冲突与和好弧 + 工程加固：关系事件状态机（她会真的受伤、和好有惯性）统一收编全部"她对你冷"的逻辑；事故复盘后让静默失败变响（ESLint / 错误签名日报 / 死人开关）；照片比例修复；沉浸感卫生包（她的世界里没有"用户"这个词、素材级防复读、互动历史自动打底）；照片承诺兑现链（承诺前可行性闸门、拍不出能改期补发、月相锚定杜绝凭空满月）；照片品类校准（像真实恋爱那样发照片：食物一等公民、天空靠 sun_times 日落窗口锚定、"看到这个想到你"、真实出版物封面护栏；先审计后改配比时还顺手揪出并修了一桩 1.5 天的静默断图 P0）
• v1.20.x 安全收尾：未成年人保护（粘性安全模式）、隐私过滤全口子、发布一致性 CI、照片真实感 v2（反磨皮质感词直达生产）
• v1.14 → v1.19 真人感纵深：被冷落逐级转变 + 依恋风格、留存漏斗（挽留/升温/读空气/破冰）、照片真实感大改（环境自拍/i2i 锁脸/机位路由）、初恋特质
• v1.6 → v1.13 体验底座：真实发图链路、反讨好系列、Inner OS、开环记忆、睡眠系统、连发合并、关系节奏（时间喂大感情）、中英双语
• v1.0 → v1.5 框架成型：人设引擎、Memory v2、情绪状态机、主动消息、日记、多 Provider 抽象

• 开发环境 / PR 约定 / 产品调性 → CONTRIBUTING.md（3 分钟读完）
• 找到 bug → 新 Issue
• 路线图 → Issues 带 enhancement / help wanted / good first issue 标签的最适合上手
• 想贡献代码：fork → PR；保持改动小而聚焦，附带说明动机
• 致谢见 ACKNOWLEDGMENTS.md

MIT © 2026 溪语 AI Contributors

仓库不包含任何第三方表情包图片。assets/stickers/ 只有加载与 tag 匹配机制，启用表情包请自行准备有合法授权的素材。