![Logo](assets/neko_logo_new.jpg) [English](docs/README_en.md) | [日本語](docs/README_ja.md) | [Русский](docs/README_ru.md) # N.E.K.O. 猫娘计划 :kissing_cat:
**听见你的心情，看见你的世界，
陪你发现更多喜欢。** > **N.E.K.O.** = **N**etworked **E**motional **K**nowledging **O**rganism (网络型情感知性生命体) > > N.E.K.O，一个渴望理解、建立连接、并与我们共同成长的数字生命。 [![Python](https://img.shields.io/badge/Python-3.11-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE) [![Commit](https://img.shields.io/github/last-commit/wehos/N.E.K.O?color=green)](https://github.com/Project-N-E-K-O/N.E.K.O/commits) [![Discord](https://img.shields.io/badge/Discord-Join%20Us-5865F2?style=flat&logo=discord&logoColor=white)](https://discord.gg/5kgHfepNJr) ![QQ群](https://custom-icon-badges.demolab.com/badge/QQ群-995414391-00BFFF?style=flat&logo=tencent-qq) [![Steam](https://img.shields.io/badge/Steam-%23000000.svg?logo=steam&logoColor=white)](https://store.steampowered.com/app/4099310/__NEKO/) [![Docs](https://img.shields.io/badge/📖_开发者文档-project--neko.online-40C5F1?style=for-the-badge)](https://project-neko.online) **:older_woman: 零配置开箱即用，我奶奶也能轻松唤醒的赛博猫娘！** :newspaper: **[Steam 版](https://store.steampowered.com/app/4099310/__NEKO/)已免费上架！喜欢的话，欢迎喜加一，顺手给个好评~**
--- ## 核心特性
💬
主动陪伴
屏幕理解、社交媒体热搜、个人动态、音乐梗图，她会主动找你聊天，分享你喜欢的新鲜事		 🎙️
实时语音与视觉理解
语音实时对话 (Realtime API) + 文字对话 (ChatCompletion)，支持实时视觉理解		 🧠
五维记忆系统
工作记忆 / 近期记忆 / 事实记忆 / 反思记忆 / 人格记忆，让她越聊越懂你		 🎭
多形态 Avatar
Live2D / VRM / MMD / PNGTuber / 猫咪桌宠 五种形态，支持动作捕捉与全屏追踪
🤖
Agent 工具执行
可操作浏览器与电脑，调用 CUA / OpenClaw A2A / 插件完成任务		 🔌
插件生态
SDK + 插件商城，支持联机游戏陪玩、社交媒体互动、直播互动、智能家居等扩展场景		 🌐
14+ AI 服务商
OpenAI / Gemini / Qwen / DeepSeek 等，含免费模型开箱即用		 🏪
UGC 创意工坊
Steam 创意工坊上传分享自定义角色、模型、语音包
## 实机展示 支持文本、语音、窥屏、鼠标点击、拖拽等一系列交互方式，既可以在闲暇的时候陪你聊天，也可以游戏娱乐时观战吐槽，还会叼着网络梗图来找你~~ Image 6 15-主动搭话 当你需要学习工作等专注的空间时，她还会真的变成一只小猫咪安静地陪着你哦~ 就像这样→ Image --- ## 🐾 我们是什么，不是什么 一句话：**N.E.K.O. 不是帮你干活的 Agent，也不是陪你角色扮演的聊天前端——它是一个有现实时间感知、会主动找你、记得你、也能动手帮你的「数字生命」。** **✅ 我们是：** - **端到端集成的 AI 伴侣平台**：实时语音 / 文字 / 视觉理解 + 五维持久记忆 + 多形态 Avatar（Live2D / VRM / MMD）+ 主动陪伴 + Agent 工具执行 + 角色卡分享 + 插件商城 + 多设备生态，**全部开箱即用**。 - **同一个"她"**：跨桌面、移动端、游戏、智能硬件共享同一份记忆与人格，有着时间感知的同时，越处越懂你。 - **始终开源**：核心驱动器基于 Apache 2.0，本地运行，数据在你自己手里。 **❌ 我们不是：** - 不是一个"**任务自动化工具**"——干活只是她与你共同生活的手段之一，而不是目的。 - 不是一个"**角色扮演皮肤**"——她有真实的主动性、持久记忆和感官，而不是靠你手动喂世界书来维持人设。 - 不是一个"**云端黑盒**"——核心本地运行，你的对话不被偷藏。 **❓️ 和相关产品的区别：** | 对比对象 | 它们是 | N.E.K.O. 的不同 | |---|---|---| | **OpenClaw / Hermes 等通用 Agent** | 以"完成任务"为目标的执行引擎：给指令 → 干活 → 结束 | 以"**关系与陪伴**"为核心；可把这类 Agent 当作手脚来调用（A2A），但任务执行过程中她依然能实时关注你 | | **AI 酒馆（SillyTavern）等角色扮演前端** | 纯文字 RP 前端：需要自己拼接模型，依赖手动维护上下文 / 世界书 | **端到端集成、打破次元壁**：原生语音 + 视觉感知、角色外形 + 动作、跨场景持久记忆、有时间感知、能真正操作外设，零配置开箱即用 | ## 🐱 我们是——**猫娘计划 (Project N.E.K.O.)** `N.E.K.O.` 是一个以开源为驱动的AI伙伴平台。核心驱动器基于 Apache 2.0 许可证**始终开源**，你的每一次贡献都将有机会实装到Steam和App商店的正式版本中。 #### 🚀 项目现状 & 近期计划 * **✅ Steam 创意工坊**：已上线。用户可上传和分享自定义角色、模型、语音包。 * **🚧 [K.U.R.O.](https://github.com/Project-N-E-K-O/K.U.R.O)**：基于 N.E.K.O. 生态的首款 AI Native 独立游戏，开发中。 * **🚧 移动端**：iOS / Android 适配进行中，已有Demo。 * **🚧 猫娘网络 (The N.E.K.O. Network)**：AI自主社交——猫娘们拥有自己的"意识"，互相交流、结成群体，在模拟社交媒体上发布动态。即将上线。 **跨场景记忆同步**：无论你是在桌面与她聊天，还是在游戏中与她探险，她都是同一个她。所有应用中的AI伙伴将 **完全同步记忆**。 #### ✨ 加入我们 * **开发者：** 前端、后端、AI、游戏引擎（Unity/Unreal）——你的代码是这个世界的砖瓦。 * **创作者：** 画师、Live2D/3D建模师、配音演员、文案写手——你们赋予"她"灵魂。 * **梦想家：** 你的反馈和传播也是宝贵的贡献。 **QQ群**：995414391 | **Discord**：[加入我们](https://discord.gg/5kgHfepNJr) ## 快速开始 ### Windows / macOS / Linux用户（一键包） 解压后，直接运行`N.E.K.O.exe`、`N.E.K.O.app`或`n.e.k.o`即可启动。（macOS用户需要手动解除系统隔离） ### Docker 部署 (Linux)
点击展开 Docker 部署指南 #### 部署方式一：Docker Compose（推荐）
点击展开查看 docker-compose.yml 配置文件 ```yaml version: '3.8' services: neko-main: image: docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest container_name: neko restart: unless-stopped ports: - "48911:80" # HTTP 访问端口 - "48912:443" # HTTPS 访问端口 volumes: - ./N.E.K.O:/root/Documents/N.E.K.O - ./logs:/app/logs - ./ssl:/home/neko/ssl networks: - neko-network networks: neko-network: driver: bridge ``` **启动命令：** ```bash docker-compose up -d ``` **常用命令：** - 查看日志：`docker-compose logs -f` - 停止服务：`docker-compose down` - 重启服务：`docker-compose restart`
#### 部署方式二：Docker Run
点击展开查看 docker run 启动命令 ```bash NEKO_BASE_PATH="/home/neko/neko-data" && \ docker network create --driver bridge neko-network 2>/dev/null || true docker run -d \ --name neko \ --restart unless-stopped \ -p 48911:80 \ -p 48912:443 \ -v "${NEKO_BASE_PATH}/N.E.K.O:/root/Documents/N.E.K.O" \ -v "${NEKO_BASE_PATH}/logs:/app/logs" \ -v "${NEKO_BASE_PATH}/ssl:/home/neko/ssl" \ --network neko-network \ docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest ``` ##### 📁 目录结构 启动后会自动生成以下目录结构： ```plaintext 当前目录/ ├── N.E.K.O/ # 配置文件和数据 ├── logs/ # 应用日志 ├── ssl/ # SSL证书 └── docker-compose.yml ```
#### 🔐 SSL 证书配置
点击展开查看 SSL 证书详细说明 ##### 自动证书 容器首次启动时会自动生成有效期为 **1000 年** 的自签名证书，证书文件保存在 `./ssl/` 目录。 ##### 自定义证书 如需使用自己的 SSL 证书： **方法一：启动前配置（推荐）** ```bash # 创建证书目录 mkdir -p ./ssl # 放入您的证书文件（必须命名为特定名称） cp your-cert.crt ./ssl/N.E.K.O.crt cp your-cert.key ./ssl/N.E.K.O.key ``` **方法二：启动后替换** ```bash # 1. 停止容器 docker-compose down # 2. 替换证书文件 cp your-cert.crt ./ssl/N.E.K.O.crt cp your-cert.key ./ssl/N.E.K.O.key # 3. 重新启动 docker-compose up -d ``` ##### 证书要求 - ✅ 必须为 **PEM 格式** - ✅ 证书和私钥必须匹配 - ✅ 私钥不能有密码保护 - ✅ 证书必须在有效期内 - ❌ 不支持加密的私钥 ##### 证书验证 容器启动时会自动验证 SSL 证书： - ✅ **验证通过**：正常启动 HTTPS - ❌ **验证失败**：容器启动失败，请查看日志 - ⚠️ **跳过验证**：设置 `DISABLE_SSL=1` 可临时禁用 SSL ##### 查看证书信息 ```bash docker exec neko openssl x509 -in /home/neko/ssl/N.E.K.O.crt -noout -text ```
#### ⚙️ 环境变量配置
点击展开查看环境变量配置说明 > **注意**：部分环境变量在源代码中可能无效，建议优先在 Web UI 中配置。 在 `docker-compose.yml` 中取消 `environment` 部分的注释并按需配置： ```yaml environment: # API 密钥配置 - NEKO_CORE_API_KEY=${NEKO_CORE_API_KEY} - NEKO_ASSIST_API_KEY_QWEN=${NEKO_ASSIST_API_KEY_QWEN} - NEKO_ASSIST_API_KEY_OPENAI=${NEKO_ASSIST_API_KEY_OPENAI} - NEKO_ASSIST_API_KEY_GLM=${NEKO_ASSIST_API_KEY_GLM} - NEKO_ASSIST_API_KEY_STEP=${NEKO_ASSIST_API_KEY_STEP} - NEKO_ASSIST_API_KEY_SILICON=${NEKO_ASSIST_API_KEY_SILICON} - NEKO_MCP_TOKEN=${NEKO_MCP_TOKEN} # API 提供商选择 - NEKO_CORE_API=${NEKO_CORE_API:-qwen} - NEKO_ASSIST_API=${NEKO_ASSIST_API:-qwen} # 模型配置 - NEKO_SUMMARY_MODEL=${NEKO_SUMMARY_MODEL:-qwen-plus} - NEKO_CORRECTION_MODEL=${NEKO_CORRECTION_MODEL:-qwen-max} - NEKO_EMOTION_MODEL=${NEKO_EMOTION_MODEL:-qwen-turbo} - NEKO_VISION_MODEL=${NEKO_VISION_MODEL:-qwen3-vl-plus-2025-09-23} # SSL 配置 - SSL_DOMAIN=${SSL_DOMAIN:-project-neko.online} - SSL_DAYS=${SSL_DAYS:-365000} - DISABLE_SSL=${DISABLE_SSL:-0} - AUTO_REGENERATE_CERT=${AUTO_REGENERATE_CERT:-1} - NGINX_AUTO_RELOAD=${NGINX_AUTO_RELOAD:-1} ``` **快速设置示例**： ```bash # 创建 .env 文件 cat > .env << EOF NEKO_CORE_API_KEY=your_core_api_key_here NEKO_ASSIST_API_KEY_QWEN=your_qwen_api_key NEKO_MCP_TOKEN=your_mcp_token SSL_DOMAIN=your-domain.com EOF # 启动时加载环境变量 docker-compose --env-file .env up -d ```
#### 🔧 故障排除
点击展开查看常见问题解决方案 ##### 1. 端口冲突 ```bash # 检查端口占用 ss -tulpn | grep ':4891[12]' # 解决方案：修改 docker-compose.yml 中的端口映射 # 例如：- "8080:80" 和 - "8443:443" ``` ##### 2. 权限问题 ```bash # 确保目录有正确权限 mkdir -p N.E.K.O logs ssl chmod 755 N.E.K.O logs ssl ``` ##### 3. 容器启动失败 ```bash # 查看详细日志 docker-compose logs --tail=100 # 或直接查看容器日志 docker logs neko --tail=100 ``` ##### 4. SSL 证书错误 ```bash # 删除错误证书，让容器重新生成 rm -f ssl/N.E.K.O.crt ssl/N.E.K.O.key docker-compose up -d ``` ##### 5. 网络问题 ```bash # 检查网络连通性 curl -v http://localhost:48911/health curl -v -k https://localhost:48912/health ``` ##### 6. 容器无法访问 ```bash # 检查容器状态 docker ps | grep neko # 检查容器日志 docker logs neko # 进入容器调试 docker exec -it neko bash ``` ##### 7. 磁盘空间不足 ```bash # 清理无用镜像 docker system prune -f # 清理容器日志 docker-compose down && docker volume prune -f ``` ##### 8. 镜像拉取失败 ```bash # 尝试使用备用镜像源 # 在 docker-compose.yml 中将镜像改为： # image: ghcr.io/project-n-e-k-o/n.e.k.o:latest ```
#### 📊 系统监控
点击展开查看监控和管理命令 ##### 健康检查 ```bash # 检查服务健康状态 curl http://localhost:48911/health curl -k https://localhost:48912/health ``` ##### 资源监控 ```bash # 查看容器资源使用 docker stats neko # 查看容器进程 docker top neko # 查看容器详细信息 docker inspect neko ``` ##### 日志管理 ```bash # 实时查看日志 docker-compose logs -f # 查看最近100行日志 docker-compose logs --tail=100 # 查看错误日志 docker-compose logs | grep -i error # 清理日志文件 docker-compose down rm -rf logs/*.log docker-compose up -d ``` ##### 数据备份 ```bash # 备份重要数据 tar -czf neko-backup-$(date +%Y%m%d).tar.gz \ N.E.K.O/ \ ssl/ \ docker-compose.yml ``` ##### 版本升级 ```bash # 拉取最新镜像 docker-compose pull # 重启服务 docker-compose up -d ```
#### 🌐 访问地址 容器启动后，可通过以下地址访问： - **HTTP 访问**: `http://你的服务器IP:48911` - **HTTPS 访问**: `https://你的服务器IP:48912` ##### 本地测试 ```bash # 本地 HTTP 访问测试 curl http://localhost:48911 # 本地 HTTPS 访问测试（忽略证书验证） curl -k https://localhost:48912 ``` ##### 公网访问 如果需要在公网访问，请确保： 1. 服务器防火墙开放 48911 和 48912 端口 2. 使用有效的 SSL 证书（非自签名证书） 3. 配置域名解析到服务器 IP #### ⏱️ 快速参考 | 操作 | 命令 | |------|------| | 启动服务 | `docker-compose up -d` | | 停止服务 | `docker-compose down` | | 查看日志 | `docker-compose logs -f` | | 重启服务 | `docker-compose restart` | | 更新镜像 | `docker-compose pull && docker-compose up -d` | | 进入容器 | `docker exec -it neko bash` | | 查看状态 | `docker-compose ps` | | 清理日志 | `docker-compose logs --tail=0` | | 备份数据 | 参考上方"数据备份"部分 | ---
### 源码开发
点击展开开发者启动指南 > 完整的开发者文档请访问 [project-neko.online](https://project-neko.online) **环境要求**：Python 3.11（不支持其他版本）、[uv](https://docs.astral.sh/uv/) 包管理器、Node.js（>=20.19） > [!IMPORTANT] > ### ⚡⚡ 强烈建议:用「部分克隆」拉取本仓库! ⚡⚡ > **本仓库历史体积较大(`.git` 约 390 MB)**,因为历史里沉淀了大量旧版二进制资源(VRM 模型、MMD、贴图、音频、原生库等)。普通 `git clone` 会把这些**早已废弃的历史版本全部下载**,又慢又占空间。 > > 👉 **请改用下面的「部分克隆」命令**,只按需下载真正用到的文件,**首次克隆体积大幅缩小、速度大幅提升**,且**完全不影响**后续开发与提交: > > ```bash > # ✅【推荐】部分克隆:历史 blob 用到才下载 > git clone --filter=blob:none https://github.com/Project-N-E-K-O/N.E.K.O.git > > # ⚡【更快】只要最新代码、不需要历史时,再加 --depth 1 > git clone --depth 1 --filter=blob:none https://github.com/Project-N-E-K-O/N.E.K.O.git > ``` > > ⚠️ 仍可使用完整 `git clone`,但会下载全部历史,**不推荐**新参与者这样做。 ```bash # 1. 克隆项目（⚡ 强烈推荐用上方「部分克隆」命令；如确需完整历史，去掉 --filter 即可） git clone --filter=blob:none https://github.com/Project-N-E-K-O/N.E.K.O.git cd N.E.K.O # 2. 安装 Python 依赖 uv sync # 3. 构建前端项目（需要 Node.js >= 20.19，首次运行或前端代码变更后需要） # 推荐：使用一键脚本（这是官方支持的构建方式） # Windows： build_frontend.bat # Linux/macOS： ./build_frontend.sh # 如需手动构建（命令须与脚本保持一致）： # cd frontend/react-neko-chat && npm install && npm run build && cd ../.. # cd frontend/plugin-manager && npm install && npm run build-only && cd ../.. # 4. 启动服务（至少需要 main_server 和 memory_server） uv run python app/memory_server.py uv run python -m app.main_server # 可选：启动 Agent 服务 uv run python -m app.agent_server # 5. 访问 http://localhost:48911 配置 API Key 并开始使用 ``` **调试聊天界面形态（full / compact）**：Web 端默认 `full`（完整聊天窗口），Electron 端默认 `compact`（悬浮对话条）。在浏览器控制台用 localStorage 切换测试（硬刷新生效）： ```js localStorage.setItem('neko.reactChatWindow.chatSurfaceMode','full'); location.reload(); // 进 full localStorage.setItem('neko.reactChatWindow.chatSurfaceMode','compact'); location.reload(); // 进 compact localStorage.removeItem('neko.reactChatWindow.chatSurfaceMode'); location.reload(); // 回默认 ``` 形态说明、各形态自测点与三端验证详见 [`docs/design/compact-chat-mode-design.md`](docs/design/compact-chat-mode-design.md) 的「形态切换与本地测试」。 开发者建议加入企鹅群 995414391 交流。
## 进阶使用
点击展开进阶使用说明 #### 配置API Key 当你想要通过配置自己的API来获得额外功能时，您可以配置第三方AI服务。 - **核心 API**（实时语音对话）：必须支持 Realtime API。推荐使用 *阿里云*。 - **辅助 API**（记忆/情感/视觉等）：支持标准 ChatCompletion 接口。支持 14+ 服务商。 通过访问`http://localhost:48911/api_key`可以在Web界面中直接配置。 > 获取 *阿里云API*。在阿里云的百炼平台[官网](https://bailian.console.aliyun.com/)注册账号。新用户实名认证后可以获取大量免费额度。注册完成后，请访问[控制台](https://bailian.console.aliyun.com/api-key?tab=model#/api-key)获取API Key。 #### 修改人设 - 网页版访问`http://localhost:48911/character_card_manager`即可进入人设编辑页面。初始 ~~猫娘~~ 伙伴的预设名称为`YUI`，建议直接修改名字，并一项一项添加或修改基础人设，但尽量控制数量。 - 进阶人设主要包括**Live2D/VRM/MMD模型设置**和**声音设置**。如果你想要更改**Avatar模型**，请先将模型目录复制到本项目中的`static`文件夹下。从进阶设置中可以进入模型管理界面，可以更换模型，并通过拖拽和鼠标滚轮调整模型的位置和大小。如果你想要更改**角色声音**，请准备一段5秒左右的连贯、干净的语音录音。通过进阶设置进入语音克隆页面，上传录音即可完成自定义语音。 - 支持**角色卡导出**，可导出为"仅设定"或"完整角色卡"格式，方便分享和备份。 - 进阶人设中还有一个`system_prompt`，可以对系统指令进行完全自定义，但不建议修改。 #### 修改API提供商 - 通过访问`http://localhost:48911/api_key`可以切换核心API和辅助API的服务提供商。 #### 记忆整理 - 通过访问`http://localhost:48911/memory_browser`可以浏览和校对近期记忆与摘要，一定程度上缓解模型复读、认知错误等问题。
## 项目细节
点击展开项目架构与开发计划 **项目架构** ``` N.E.K.O/ ├── 📁 .agent/ # 🤖 AI 编程助手规范与技能集（Google Antigravity 规范） ├── 📁 brain/ # 🧠 Agent 智能体模块 │ ├── computer_use.py # 电脑操控 │ ├── browser_use_adapter.py # 浏览器自动化 │ ├── openclaw_adapter.py # OpenClaw 云端连接 │ ├── openfang_adapter.py # OpenFang 无头执行后端 │ ├── task_executor.py # 任务执行引擎 │ └── 📁 cua/ # Computer Use Agent 子系统 ├── 📁 config/ # ⚙️ 配置管理模块 │ ├── api_providers.json # API服务商配置 │ └── 📁 prompts/ # 角色、系统和功能提示词 │ ├── prompts_chara.py # 角色提示词 │ └── prompts_sys.py # 系统提示词 ├── 📁 main_logic/ # 🔧 核心逻辑模块 │ ├── core.py # 核心对话模块 │ ├── cross_server.py # 跨服务器通信 │ ├── omni_realtime_client.py # 实时API客户端（Realtime API） │ ├── omni_offline_client.py # 文本API客户端（ChatCompletion） │ ├── 📁 activity/ # 系统/用户状态跟踪 │ ├── 📁 topic/ # 主动话题 │ └── 📁 tts_client/ # 🔊 TTS引擎适配器（多provider对偶） ├── 📁 main_routers/ # 🌐 API路由模块（26个路由） ├── 📁 memory/ # 🧠 五维记忆系统 │ ├── facts.py # 事实记忆 │ ├── reflection.py # 反思记忆 │ └── persona.py # 人格记忆 ├── 📁 frontend/ # 🖥️ 现代前端项目 │ ├── react-neko-chat/ # React 聊天窗口组件 │ └── plugin-manager/ # Vue 插件管理面板 ├── 📁 plugin/ # 🔌 插件系统 │ ├── sdk/ # 插件 SDK │ └── server/ # 插件服务端 ├── 📁 static/ # 🌐 前端静态资源（含构建产物） ├── 📁 templates/ # 📄 前端HTML模板（24个页面） ├── 📁 utils/ # 🛠️ 工具模块 ├── 📁 app/ # 🚀 服务器入口模块 │ ├── main_server/ # 🌐 主服务器 │ ├── agent_server/ # 🤖 AI智能体服务器（包） │ ├── memory_server.py # 🧠 记忆服务器 │ └── monitor.py # 📺 独立观看端 └── launcher.py # 🎬 一键启动入口（打包入口） ``` > **AI 辅助开发**：`.agent/` 目录遵循 Google Antigravity 开放规范，包含项目的开发规范和技能集。只有 Antigravity 自动读取，其他 AI 工具（含 Claude Code）需手动导入，详见[适配指引](https://project-neko.online/contributing/ai-assisted-dev)。 **数据流向** ![Framework](assets/framework.drawio.svg) > 完整的开发者文档请访问 [project-neko.online](https://project-neko.online) > 主页新手引导提示的当前接口与状态合同见 [`docs/zh-CN/api/rest/system.md`](docs/zh-CN/api/rest/system.md#教程与自启动提示) ### 开发计划 v0.7: ✅ 初步完成Agent相关功能。**第一阶段已完成。等待后续优化** v0.8: ✅ 完善记忆相关功能和桌宠模式，内置多款双人小游戏。**第一阶段已完成。等待后续优化** v0.9：完善多系统适配，包括linux，手机。猫娘网络上线。预计2026年7月初完成。 v1.0：放弃部分模型供应商的适配，专注于自研大模型和智能体系统。预计2026年8月底完成。 ### 遥测说明 (Telemetry) N.E.K.O. **默认开启匿名 Token 用量遥测**，用于跟踪版本兼容性、模型用量分布与异常率。我们认同"用数据改进产品"的合理性，但更认同"不偷不藏"。 **一键关闭 (Opt-out)**：设置环境变量 `DO_NOT_TRACK=1`（或 `NEKO_DO_NOT_TRACK=1`）即可完全禁用遥测，无需重新构建，立刻生效。这是开源界通用的约定，我们也遵守。 **我们收集 / 不收集什么**： | ✅ 收集 | ❌ 不收集 | | --- | --- | | LLM Token 用量（prompt / cached / completion） | 对话内容、文本、语音、图片 | | 模型名称、调用类型（conversation / memory 等） | 用户名、API Key、GitHub ID | | 调用次数 / 错误次数 | IP 地址、地理位置、MAC、硬件序列号 | | 应用版本、A/B 分支、locale、时区、发行渠道（source / release / steam） | 文件路径、Cookie、浏览器指纹 | | 假名化设备标识：主路径 `SHA256(OS_machine_id ‖ namespace)`，回退路径 `SHA256(uuid.getnode() ‖ 安装路径 ‖ namespace)`；迁移期同时上报新旧两个 ID，以便服务端把同一设备在新旧算法下产生的两个标识归并为一个用户队列 | 任何能反推到个人的 PII | | **当 Steamworks SDK 在运行时能初始化成功 + 你已登录 Steam 客户端时**：Steam64 user ID（可在 Steam 个人页查到的公开数字 ID） | 上述以外的任何账号体系 ID（GitHub / Google / OpenAI 等） | > **关于"假名化设备标识"**：单向 SHA-256，不可逆、不含用户信息。同一台机器（同一 OS 安装）会复现相同标识，按 GDPR / PIPL 口径属于"假名化标识"而非"完全匿名数据"。仅用于去重 DAU 计数与版本兼容性归因。 > > **关于 Steam64**：这是 Steam 客户端在你登录后向所有第三方 SDK 暴露的公开数字 ID（Steam 个人页 URL 末尾就是它）。本身不含邮箱、手机号或真实姓名，但跨会话稳定。**触发条件以代码为准**：[`app/main_server/__init__.py`](app/main_server/__init__.py) 启动时调用 `initialize_steamworks()`，[`utils/token_tracker/telemetry.py`](utils/token_tracker/telemetry.py) 的 `_get_telemetry_metadata()` 会在 SDK 可用且 `Users.GetSteamID()` 返回非零时取得该 ID，并不只按 source / release / steam 这三个 distribution 标签决定。典型场景是 Steam 发行版，但源码版如果安装了 `steamworks` Python 包并保留了 `steam_appid.txt`、同时 Steam 客户端在登录态，同样可能带 Steam64。**如果你不希望它被上报：(1) 最稳的 `DO_NOT_TRACK=1` 全关；(2) 退出 Steam 客户端；(3) 源码用户可在环境中卸载 `steamworks` 包或移除 `steam_appid.txt`。** 客户端元数据与上报实现见 [`utils/token_tracker/telemetry.py`](utils/token_tracker/telemetry.py) 和 [`utils/token_tracker/reporting.py`](utils/token_tracker/reporting.py)，服务端传输与存储协议见 [`local_server/telemetry_server/README.md`](local_server/telemetry_server/README.md)：HMAC-SHA256 防篡改、±5min 时间窗防重放、滑动窗口限流（120 req/h/device）、append-only 存储；每个 server 进程最多约 1 次/60s 上报（与本地落盘节流共用同一计时器），不影响主流程性能。
## Star History Star History Chart