Nexus

Nexus 是一个 本地优先的 AI 桌面伙伴。

它不是普通聊天软件，也不是把聊天框套进 Electron 的多模型面板。Nexus 的目标是让 AI 以一个可见、可听、能记住你、能在你明确授权时提供轻量帮助的形象常驻在电脑里。

一句话：Nexus 是一个住在电脑里的 AI 伙伴。

当前稳定版： v0.4.7；发行说明见 RELEASE-NOTES-v0.4.7.md。正式安装包只由受保护的 tag 工作流发布到 GitHub Releases；更早历史统一放在 Releases。

这个项目是什么

Nexus 是一种“陪伴式桌面 AI”。当前公开稳定版是 v0.4.7：

• 桌宠形象：伙伴以 Live2D 或分层立绘 v4 常驻桌面，而不是只存在于聊天记录里。导入 Cubism 模型会在激活前检查资源；缺动作或表情仍可显示并说明限制。
• 自然对话：文字是默认入口；语音输入/输出可选，目录里包含 Grok STT/TTS。
• 长期记忆：本机记住偏好、事件和关系线索；夜间整理会检测矛盾并降权，不把原始桌面内容送进模型。
• 本地优先，可接 API：默认可以走 Ollama；也可以使用 DeepSeek、Qwen 3.8-max、GLM-5.3 等云端目录。密钥留在本机。
• 授权辅助：搜索、天气、提醒等只在你明确授权后工作，并且可确认、可停止、可审计。

Nexus 的重点不是堆功能，而是把“陪伴”和“辅助”合成一个统一体验：它一直在电脑旁边，安静地存在，需要时能对话，授权后能帮忙，但不会变成默认替你工作的智能体。

它不是什么

不是	因为 Nexus 更关注
普通 AI 聊天软件	常驻感、角色存在感、长期关系和桌面上下文
多模型 API 面板	本地优先的伙伴体验，而不是 provider 列表
单纯桌宠动画	角色只是入口，核心是对话、记忆和任务帮助
工作型智能体平台	辅助能力要服务于陪伴体验，并且必须可控、可授权、可停止
外部角色复刻	Nexus 有自己的形象、边界和产品体验

Nexus 的形象方向

Nexus 的形象应该服务于三个感觉：

1. 陪伴式：它像一个在旁边待着的伙伴，而不是一个只在输入框里出现的工具。
2. 常驻式：它可以长期留在桌面角落，轻量存在，不抢注意力。
3. 可托付但克制：它不是只会卖萌，也能在明确授权后帮用户处理轻量事务，但不会抢走用户的控制权。

一个住在电脑里的 AI 伙伴。

它的形象应该轻、安静、有存在感。它可以在角落里待着，可以回应用户，可以逐步学会记住和帮忙，但第一阶段不需要完整角色企划。

第一阶段只做什么

这一节是项目起点的设计约束，不是当前稳定版的功能上限。当前公开产品是 v0.4.7。

第一阶段的目标不是做完整产品，而是验证一个最小体验闭环：

用户打开电脑后，能看到一个常驻的小 AI 伙伴，并能通过本地 Ollama 或 DeepSeek API 和它简单对话。

第一阶段只做这四件事：

范围	要做到什么	先不追求什么
桌面常驻小窗口	可移动、可置顶、可关闭，稳定停在桌面上	复杂窗口管理、多屏细节、炫酷动画
轻量 Live2D 形象	内置模型全身呈现、基础表情与说话状态，先有稳定的“伙伴”视觉锚点	模型编辑器、复杂换装、场景编排
跑通文本模型	默认本地 Ollama，也支持 DeepSeek API；可配置地址、模型名和必要密钥	多 provider 体系、云模型矩阵、复杂 failover
简单文字对话	输入文本、显示回复、保留基础上下文	长期记忆、工具调用、自动任务、复杂 Agent

这个阶段的验收标准很简单：

• 打开应用后，桌面上能看到一个小伙伴窗口。
• 用户能输入一句话。
• Nexus 能把这句话发给 Ollama 或 DeepSeek API。
• Nexus 能把模型回复展示出来。
• 整个过程稳定、轻量、不打扰。

第一阶段明确不做

为了避免项目一开始就失控，第一阶段不做这些：

• 不做 Live2D 模型创作、换装和复杂演出编排系统。
• 不做复杂动作、换装、场景和表情编排。
• 不做完整 Agent 框架，也不做 Codex 式工作智能体。
• 不做复杂工具调用和自动执行任务。
• 不做完整语音系统。
• 不做长期记忆、情绪系统、关系等级或主动陪伴逻辑。
• 不做多平台复杂打包流程优先级。

这些能力都是 Nexus 的未来方向，但它们不应该进入第一阶段的最小闭环。

阶段路线

阶段	目标	结果
Phase 1	最小桌面伙伴	小窗口 + 极简头像 + Ollama / DeepSeek + 简单对话
Phase 2	形象存在感	表情状态、待机动作、拖拽交互、轻量桌宠体验
Phase 3	语音体验	语音输入、语音输出、打断、基础唤醒
Phase 4	记忆系统	用户偏好、项目记忆、可编辑记忆、隐私控制
Phase 5	授权辅助	只在明确授权后提供提醒、搜索、文件和工具调用等轻量帮助
Phase 6	完整伴侣体验	角色系统、长期关系、主动陪伴、多模型和多端扩展

每个阶段都应该先完成一个可用闭环，再进入下一个阶段。Nexus 可以很大，但不能一开始就把所有系统塞进去。

更具体的执行拆分见 Nexus 升级整合计划，可执行任务表见 EXECUTABLE_OPTIMIZATION_TASKS。

当前实现状态

v0.4.7 是当前公开稳定版。第一阶段最小闭环已经成立，默认体验建立在它上面：

• 当前稳定主题是形象兼容、分层立绘 v4 和模型目录：导入 Live2D 前检查 Moc、纹理和已声明资源；分层立绘包是默认图片路径；Grok 语音与 Qwen 3.8-max / GLM-5.3 进入默认目录。从单张图生成 sprite atlas 仍不在稳定版里。

• 桌面陪伴感知保持短期、粗粒度、可暂停和可清理；时间说法是“一会儿 / 半小时左右”，不是精确到分秒。

• 主面板以用户选择的内置 Live2D 伙伴为视觉中心，当前默认体验包含全身待机、基础表情和说话状态；模型创作与复杂换装仍属于后续能力。

• 新安装的桌宠窗口默认使用更小的常驻尺寸，适合先放在桌面角落里运行；用户仍可拖拽调整。

• 新安装默认走 Ollama 文本链路：http://127.0.0.1:11434/v1 + qwen3:8b；如果已有 DeepSeek API Key，可以直接切换到 DeepSeek + deepseek-v4-flash。

• 设置首页按外观体验、伙伴行为、记忆上下文、模型连接和维护诊断分组；模型、连接、工具、主动陪伴等仍保留独立入口，设定集以“背景与常用表达”呈现。

• 模型选择默认走主路径：DeepSeek、Ollama、OpenAI-compatible 和自定义接口；其他 provider 仍保留在更深的模型来源里。

• Onboarding 只引导文字模型和基础伙伴设置，不再把完整语音系统放进第一阶段入口。

• 默认聊天和小窗入口以文字对话为主；语音按钮只在进阶设置开启语音输入或已有语音会话时出现。

• Ollama、DeepSeek 和 OpenAI-compatible 连接测试会让当前模型执行一次最小回复，而不是只检查 /models；只有服务返回有效模型响应才会显示已就绪。缺模型、缺 API Key、模型名错误和不可达状态会分别提示；如果本机 Ollama 未启动或端口无响应，会提示启动 Ollama、检查 http://127.0.0.1:11434/v1，并在需要时运行 ollama pull qwen3:8b。

• 连接测试会先做本地预检：Ollama 会提示 http://127.0.0.1:11434/v1、qwen3:8b 和 ollama pull qwen3:8b，DeepSeek 会提示 https://api.deepseek.com 与 deepseek-v4-flash，自定义接口会提示需要完整的 OpenAI-compatible Base URL 和模型 ID。

• 首次启动向导的文本模型步骤也会复用这套本地预检，并把问题和修复建议分开显示；对于 Ollama/DeepSeek 等内置 provider，可一键填入推荐 Base URL 和模型名。填入后旧结果会立即失效，并明确要求重新做真实连接测试，不会把“已填推荐值”误显示成连接成功。修复只会改 Base URL/模型名，不会代填或改写 API Key。缺云端 API Key 仍允许先保存并体验常驻窗口，但不会遮蔽 Base URL 或模型名缺失。

• 向导最后一步会显示“5 分钟内完成首次对话”的目标状态：只有当前文本模型通过连接测试后才显示已就绪；字段完整但未测试会显示为可开始但需先测试，缺少关键字段则需要补齐。

• 连接状态按证据分级：文本必须拿到有效回复，并在协议返回模型身份时与请求目标一致；响应缺少模型身份时只显示“部分验证”，不会把请求模型名当成观察证据。语音必须拿到有效音频或本地运行时证明；旧版本结果、空响应和只有端点响应的结果不会显示绿色。成功结果超过 10 分钟会变成中性状态并要求重新检测，修改语音开关、provider、模型、音色或地址也会立即让旧结果失效。local TTS 会直接运行本地合成探测；Paraformer 与 Tencent ASR 当前明确标记为不支持独立连接测试，不会误报缺少 Base URL。

• 完成向导后，第一次直接文字/语音助手回复会在本地记录 firstConversationAt 和耗时，并在 Debug Console 留下是否达成 5 分钟目标的系统事件；不会记录消息内容或密钥。

• 设置里的基础检查会显示首次对话目标状态：未记录、等待首条回复、已达成，或超出 5 分钟。

• 基础检查可以下载本地首次运行 QA 报告，包含检查项、首次对话耗时和隐私标记；不会导出聊天内容、模型输出、API Key 或 provider secret。

• 本地开发时，Nexus 网页预览地址是 http://127.0.0.1:47821/；11434/v1 是 Ollama API，不是网页预览。

本次稳定更新 — v0.4.7

主题：形象兼容、立绘 v4 与模型目录。 导入 Cubism 模型会在激活前检查资源；分层立绘 v4、Live2D 导入提示和配件穿戴进入正式版；Qwen 3.8-max / GLM-5.3 / Grok 语音进入默认目录。详见 中文发行说明 与 English release notes。

一句话记住 0.4.7：

• 导入 Live2D 前会检查 Moc、纹理和已声明资源，缺动作/表情仍可显示并说明限制。
• 分层立绘 v4 是默认形象路径；从图片生成 sprite atlas 仍不在稳定版里。
• Grok 语音、Qwen 3.8-max 与 GLM-5.3 进入默认模型目录。

上一公开版本 — v0.4.6

主题：形象运行时可靠性。 详见 中文发行说明 与 English release notes。

一句话记住 0.4.6：

• 透明 Live2D 合成更干净，WebGL 上下文丢失会在有界预算内自动恢复。
• 图形恢复失败时显示五语言可读降级状态，不把原始技术错误直接暴露给用户。
• 三模型烟测主动验证上下文恢复后只保留一个干净画布，并覆盖打包运行时门禁。
• 稳定版不再提供从图片/Atlas制作宠物；仍支持导入现有宠物包与 Creator Kit。

更早更新 — v0.4.5

主题：记忆可信度与维护。 中文说明见 RELEASE-NOTES-v0.4.5.zh-CN.md，英文完整说明见 RELEASE-NOTES-v0.4.5.md。本版走标准 beta 流程晋升（v0.4.5-beta.1 预发布后经验证窗口关闭），发布记录见 RELEASING.md。

更早更新 — v0.4.4

主题：维护与加固（工具链升级、安全修复、代码结构整理）。 中文说明见 RELEASE-NOTES-v0.4.4.zh-CN.md，英文完整说明见 RELEASE-NOTES-v0.4.4.md。本版经维护者例外直接晋升为稳定版，例外记录见 RELEASING.md。

一句话记住 0.4.4：

• 没有新功能、没有行为变化，界面和陪伴策略与 v0.4.3 完全一致。
• 底层升级带来安全性与稳定性提升：Electron 43.2、@huggingface/transformers 4.2、pixi.js 8.19 等依赖整体更新，并修复 brace-expansion 的 CVE-2026-14257 DoS 漏洞。
• 修复 Live2D UMD 包未内联 process.env 导致的启动失败问题。
• 代码内部做了循环依赖消除、大文件拆分和 ESLint 10 新规则清零，全量 2989 测试通过。
• 签名/公证仍未做：macOS 首次启动可能需右键打开，Windows 可能出现 SmartScreen 提示。

更早更新 — v0.4.3

主题：Check-In 策略和发布门禁对齐。 中文说明见 RELEASE-NOTES-v0.4.3.zh-CN.md，英文完整说明见 RELEASE-NOTES-v0.4.3.md。

0.4.3 继续保持 v0.4 桌面陪伴感知的保守边界：温和 check-in 只先形成本地、可压制的 in-app 决策，不发送消息、不执行工具、不创建外部通知，也不把精确计时或原始桌面内容送进模型边界。

一句话记住 0.4.3：

• check-in 决策和发出分开，重复调用不会变成反复打扰。
• 正在和 Nexus 聊天、刚 dismiss、重复同类信号、过期回到 Nexus 信号都会被压住。
• in-app payload 只是本地短 TTL 数据，不调度计时器、不写持久历史、不调用工具。
• 设置 UI、发布审计和性能预算继续由 verify:pr 与预发布门禁保护。
• 这仍然不是 0.5；桌宠跟随鼠标、打字反应和窗口控制留给后续版本。

更早更新 — v0.4.1

主题：陪伴 UI、设置和可靠性加固。 中文说明见 RELEASE-NOTES-v0.4.1.zh-CN.md，英文完整说明见 RELEASE-NOTES-v0.4.1.md。

0.4.1 把 v0.4 的陪伴感知地基推进到更适合公开测试的形态：主对话面板、设置页和 Image4 伙伴场域被拆成更清楚的源码边界；设置入口继续保持懒加载；隐私、安全、UI 和性能审计进入 verify:pr，让后续迭代不容易悄悄退化。

一句话记住 0.4.1：

• 主对话面板、设置页和 Image4 伙伴场域更接近统一的陪伴式视觉系统。
• 设置抽屉样式保持懒加载，打开设置不再把大段 CSS 塞进 JS 热路径。
• 时间表达继续保持粗粒度，不允许精确到分秒的陪伴计时泄漏。
• 新增多组 source-only UI、隐私、安全和性能审计，上传前已跑完整 verify:pr。
• 这仍然不是 0.5；桌宠跟随鼠标、打字反应和窗口控制留给后续版本。

更早更新 — v0.4.0

主题：桌面陪伴感知地基。 中文说明见 RELEASE-NOTES-v0.4.0.zh-CN.md，英文完整说明见 RELEASE-NOTES-v0.4.0.md。

0.4.0 正式开始“打开 Nexus 后，它能安静理解时间流逝”的桌面陪伴感知。它会优先保持安静，只形成短期、粗粒度、可暂停和可清理的陪伴摘要；进入模型的是脱敏摘要，不是原始截图、完整剪贴板、私人消息或精确计时。

一句话记住 0.4.0：

• 打开 Nexus 后，即使你去电脑别处工作，陪伴感也不会立刻断掉。
• 时间说法是“一会儿 / 半小时左右 / 一小时左右”，不是精确到分秒。
• Memory 设置里能看到说明，并能暂停或清理近期陪伴摘要。
• 这个稳定版先打好安静观察地基，不扩展主动 check-in。
• 0.5 才做桌宠跟随鼠标、打字反应和窗口互动。

旧版本记录

README 顶部只保留当前稳定版 v0.4.7 和上一公开版本 v0.4.6 的重点。更早版本的完整历史统一放在 CHANGELOG 和 GitHub Releases，避免首页继续滚动维护旧版本号。

设计原则

• 常驻但不打扰：它可以一直在桌面上，但不能干扰用户工作。
• 本地优先：能在本机完成的能力优先在本机完成。
• 先陪伴，再自动化：没有稳定的陪伴体验，自动任务只会像外挂功能。
• 先简单，再拟真：先把轻量 Live2D、语音沟通和清晰状态做稳定，再逐步扩展复杂动作、换装与人格编排。
• 用户授权：涉及文件、系统、网络、工具和任务执行时，必须让用户明确知道它要做什么。

当前技术方向

第一阶段建议保持技术栈简单：

• Electron：桌面窗口和系统集成。
• React：界面和状态组织。
• TypeScript：主进程、渲染层和共享类型。
• Vite：开发和构建。
• Ollama / DeepSeek：第一阶段文本模型连接。

第一阶段的重点是桌面窗口、头像显示、Ollama / DeepSeek 文本对话链路和基础状态管理。其他能力先作为未来方向记录，不作为当前开发重点。

安装与更新

普通用户的安装主路径不是 npm，而是桌面安装包：

以下文件名是 v0.4.7 正式发行契约。安装包只以受保护的 tag 工作流成功发布到 GitHub Releases 后的实际资产为准；不要使用本地或第三方转载包。

• Windows x64：从官方 GitHub Releases 下载 Nexus-Setup-<版本号>.exe；同一 release 的校验清单是 SHA256SUMS-windows.txt。

• macOS arm64：下载 .dmg 或 .zip，把 Nexus.app 放进 /Applications；同一 release 的校验清单是 SHA256SUMS-macos.txt；v0.4.7 不提供 macOS x64 / universal 包。

• Linux x64：下载 .AppImage、.deb 或 .tar.gz，并使用同一 release 的 SHA256SUMS-linux.txt 校验 SHA-256。只下载其中一种格式时，可在下载目录直接运行：

  sha256sum --ignore-missing -c SHA256SUMS-linux.txt

未签名安装提示与发行边界（macOS / Windows）

当前桌面安装包还没有 Apple Developer ID、公证和 Windows 代码签名证书，所以首次启动会看到系统信任提示。这是当前发行策略，不代表系统已经信任安装包。官方 GitHub Releases 是唯一下载来源；如果你不确定文件来源，删除它并从 GitHub Releases 重新下载，不要从镜像或转载压缩包安装。

• macOS / Gatekeeper：v0.4.7 的 macOS arm64 应用采用 ad-hoc 签名。ad-hoc 只保证包内代码一致性，不等于 Apple Developer ID 信任或公证；Gatekeeper 仍可能拦截首次启动。把 Nexus.app 放进 /Applications 后，可右键点击 Nexus.app -> 打开 -> 在弹窗中确认；也可以在终端运行 xattr -dr com.apple.quarantine /Applications/Nexus.app。
• Windows / SmartScreen：v0.4.7 的 Windows x64 安装器状态为 NotSigned。运行 Nexus-Setup-<版本号>.exe 后，SmartScreen 可能显示“Windows 已保护你的电脑”；确认文件来自官方 GitHub Releases 后，点击“详细信息”，再点击“仍要运行”。

macOS unsigned auto-update limitation

macOS arm64 未签名包只会检查新版本并打开官方 release 页面；它不会静默下载、替换或重启安装。每次升级都需要用户手动下载新 .dmg / .zip、重新确认 Gatekeeper 提示并替换应用。

Windows unsigned installer limitation

Windows x64 安装器会以 NotSigned 发布，无法提供发布者身份验证或稳定的 SmartScreen 声誉。用户必须从官方 GitHub Releases 手动确认并运行安装器；不要把 SmartScreen 绕过说明理解为安全背书。

预发布版本只用于 Beta → Validation，不会把稳定版用户自动升级到 beta；完成验证后才会晋升 stable。每个平台使用独立校验清单：Windows 是 SHA256SUMS-windows.txt，macOS 是 SHA256SUMS-macos.txt，Linux 是 SHA256SUMS-linux.txt。

npm 不是普通用户的安装主路径。这个仓库的 npm 命令只给开发者使用：启动开发环境、打包安装包、运行自检和发布前检查。普通用户通过对应平台的发布路径获得后续版本；其中未签名 macOS arm64 包只检查新版本并打开官方 release 页面，升级仍需手动下载和替换应用。

已知限制与适用人群

Nexus 仍在活跃开发，更适合愿意测试本地 AI 桌面伙伴、能接受手动确认权限和反馈问题的用户。普通用户可以体验稳定入口，但不应该把当前版本当成已经完成商业签名、企业级运维和零配置交付的成熟软件。

限制	当前状态	建议
未签名安装包	Windows / macOS 首次启动会出现 SmartScreen 或 Gatekeeper 提示。	只从 GitHub Releases 下载；不确定来源时删除后重新下载。
资源占用	Electron、Live2D、语音、OCR、WASM 和本地模型会带来一定内存、包体和首次运行下载成本。	先用文本模型主路径；语音、本地识别和桌面感知按需开启。
provider 联网	Ollama 可以本地运行；DeepSeek、OpenAI-compatible 和其他云 provider 会把请求发给对应服务商。	使用前确认 provider 的数据政策；API Key 只保存在本机加密存储里。
桌面感知	v0.4.7 保持短期、粗粒度、可暂停和可清理的陪伴摘要，并继续阻止精确计时和原始桌面内容进入模型边界。	在 Memory 设置里查看说明，按需要暂停或清理近期陪伴摘要。
语音和本地模型	本地语音模型、麦克风权限和平台音频设备可能影响语音链路。	语音失败时先回到文字对话；用设置里的自检和模型向导排查。

本地开发

环境要求：

• Node.js 22+
• npm 10+
• 已安装 Ollama 并至少准备一个本地模型，或准备可用的 DeepSeek API Key

只看前端网页预览：

npm install
npm run dev

然后打开：

http://127.0.0.1:47821/

启动 Electron 桌面开发环境：

npm install
npm run electron:dev

electron:dev 会复用已经运行的 47821 Vite 服务；如果没开，它会自动先启动 Vite，再启动 Electron。

不要把 http://127.0.0.1:11434/v1 当成网页打开。它是 Ollama 的 OpenAI-compatible API 地址，只给 Nexus 调模型用；浏览器预览始终看 Vite 的 47821 端口。

快速自检：

npm run doctor

它会检查仓库依赖、electron:dev 启动路径、47821 预览服务、Ollama API 和默认 qwen3:8b 模型，并提醒 DeepSeek API 的配置入口。 如果你主要走 DeepSeek，可以运行：

npm run doctor -- --provider deepseek

这样 Ollama 未启动会降为信息提示，不会被当成主路径警告。

发布验收或问题报告需要结构化结果时，可以导出本地 JSON 自检报告：

npm run doctor -- --json

JSON 报告只记录检查结果、运行环境和推荐路径；不会写入 API Key、聊天内容、模型输出或 provider secret。离线 CI 可以加 --skip-network 跳过端口探测。

首次启动和模型修复链路的快速验收门禁：

npm run verify:first-run

它会检查 doctor JSON 隐私边界、模型配置预检、向导修复、首次对话计时、基础检查报告和 i18n 完整性；完整发布前仍需运行全量测试、构建和打包冒烟。

常用命令：

npm run build
npm run lint
npm test
npm run verify:first-run
npm run distribution:audit

贡献方向

当前最有价值的贡献不是把下一阶段提前做完，而是把已经公开的陪伴体验做扎实：

• 让桌宠窗口更稳定、更轻量。
• 让 Live2D / 立绘 v4 导入和切换更清楚，但不过度复杂。
• 让模型配置、语音和错误提示更好懂。
• 让文字对话、记忆可见性和暂停路径稳定可靠。
• 保持 README、路线图和实际开发重点一致。

想参与但不想改核心代码，也可以从社区内容开始：

• 桌宠包、头像素材和动作预览。
• 人格模板、提示词样例和对话场景。
• 本地模型配置菜谱。
• 安装教程、踩坑记录和翻译。
• v0.4 桌面陪伴感知的使用反馈：时间说法是否自然、提醒是否太频繁、暂停是否明显。

社区文档不是某个版本的小功能，而是项目长期变大的入口。社区入口见 COMMUNITY.md，0.4 系列方向见 v0.4 Desktop Companion Awareness， 0.4 当前稳定版说明见 RELEASE-NOTES-v0.4.7.md， 发布加固清单见 RELEASE-CANDIDATE-v0.4-HARDENING.md。 提交人格、提示词或桌宠素材前，请先看 Nexus Companion Prompt Baseline； 它定义了 Nexus 的稳定身份、边界和社区投稿格式。新人格可以从 Persona Contribution Template 开始填。

项目边界

Nexus 的长期想象空间很大，但当前最重要的是把已经公开的产品和下一阶段分开：

Nexus 是一个住在电脑里的 AI 伙伴。

v0.4.7 已经能常驻桌面、对话、记住重要的事，并在授权后提供轻量帮助。0.5 才做桌宠跟随鼠标、打字反应和窗口互动；签名安装包也还不是当前发行策略。

License

Released under the MIT License.

Bundled Live2D sample characters are subject to Live2D's separate terms. See THIRD_PARTY_NOTICES.md before redistributing Nexus.