OpenNexus
OpenNexus 是一款本地优先的 AI 笔记与知识中枢。它将 Markdown Vault、全文与向量检索、知识库问答、可审计 Agent、扩展系统和多设备同步整合在一个桌面应用中。笔记与索引由用户掌控；需要模型或同步服务时，再按需连接本地或远程服务。
当前发布版本为 0.3.1-alpha.2，主要支持 Windows x64。Alpha 版本仍处于快速迭代阶段，升级前请备份 Vault。
主要能力
- 本地知识库：管理多个 Vault，编辑 Markdown，索引文件与附件，并保留可迁移的数据目录。
- 检索与问答：结合 FTS5、sqlite-vec、RRF 和轻量精排，回答中可定位引用来源。
- AI 与 Agent：支持 OpenAI、Anthropic、Ollama 及兼容接口；Agent 提供权限确认、执行轨迹、任务恢复和工具调用。
- 工具与扩展：内置知识库、文件、导出、函数绘图等工具，可安装 Skill、Plugin，并连接 MCP 服务。
- 内容呈现：支持 Mermaid、LaTeX、函数图像、多语言代码、主题和中英文界面。
- 桌面安全边界：Tauri/Rust Host 负责本地能力，凭据由 Stronghold 管理，Core 通过受控进程和认证通道访问。
- 同步服务：Sync v1 提供账户、设备、增量同步、冲突处理、对象存储和 Vue 3 管理控制台。
- 运行诊断：记录脱敏运行日志、Agent Trace、模型用量和错误关联信息。
系统结构
flowchart LR
UI[Vue 3 桌面界面] --> HOST[Tauri / Rust Host]
HOST --> VAULT[本地 Vault]
HOST --> CORE[FastAPI AI Core]
CORE --> INDEX[(SQLite / FTS5 / sqlite-vec)]
CORE --> MODEL[本地或远程模型]
CORE --> EXT[Skill / Plugin / MCP]
HOST <--> SYNC[OpenNexus Sync Server]
SYNC --> PG[(PostgreSQL)]
SYNC --> OBJ[对象存储]
桌面端默认在本机运行。Sync Server 是可选组件，只有启用同步时才需要部署。
使用发布包
本版提供 Windows x64 便携包和独立的 Server Sync 包，下载入口见 v0.3.1-alpha.2 发布页。发布页同时附带 SHA256.json，用于核对文件完整性。
便携包是干净的首次安装环境，不包含任何 Vault 或用户数据，也不预装已下载的社区主题、本地模型权重、CUDA 与 PyTorch 运行时。相关功能仍完整保留；需要时可在客户端内按需安装主题、选择模型或配置 CUDA 环境。程序自带的基础界面样式属于客户端资源，不视为社区主题。
- 下载 Windows x64 软件包，并核对发布页中的 SHA-256。
- 将便携版完整解压到可写目录，不要单独移动可执行文件。
- 启动
OpenNexus.exe，选择已有 Vault 或创建新 Vault。 - 在“设置 → 模型提供商”中配置本地模型或远程模型凭据。
- 如需多设备同步，在同步设置中填写管理员提供的 Sync Server 地址并登录。
凭据不会写入前端 localStorage。首次试用建议复制一份现有笔记目录，再用副本验证索引和同步行为。
工作区图片存储
在源码或所见即所得编辑器中粘贴、拖入或选择 PNG、JPEG、GIF、WebP 图片后，OpenNexus 会按内容哈希保存到当前 Vault 的 attachments/<哈希前两位>/<SHA-256>.<扩展名>。Markdown 使用相对路径引用图片，因此笔记目录整体复制、导出或同步后仍可定位原图；单张图片上限为 5 MiB，相同内容只保存一份。
图片二进制不写入 SQLite。数据库中的 workspace_assets 保存路径、SHA-256、媒体类型、大小和原始文件名，workspace_asset_links 保存图片与笔记的引用关系。另一台设备收到 Vault 文件后，会在首次显示图片时校验路径哈希并重建本机元数据。
开发环境
| 工具 | 版本 |
|---|---|
| Node.js | 22 或更高版本 |
| pnpm | 10.28.0 |
| Python | 3.12 或更高版本 |
| uv | 0.9.24 |
| Rust | stable，桌面构建需要 |
安装依赖：
cd backend
uv sync --frozen
cd ../frontend
corepack enable
corepack prepare pnpm@10.28.0 --activate
pnpm install --frozen-lockfile
启动 Web 开发环境：
# 终端一：AI Core
cd backend
uv run python scripts/dev-server.py
# 终端二：前端
cd frontend
pnpm dev
前端默认地址为 http://127.0.0.1:5173，开发代理将 /api 和 /health 转发到 http://127.0.0.1:8000。后端接口文档位于 http://127.0.0.1:8000/docs。
启动和构建桌面应用：
cd frontend
pnpm desktop:dev
pnpm desktop:build
运行测试
# 后端
cd backend
uv run pytest
# 前端
cd ../frontend
pnpm test
pnpm type-check
pnpm build
# Rust Host
cd src-tauri
cargo fmt --check
cargo test --all-targets --features desktop
cargo clippy --all-targets --features desktop -- -D warnings
# Sync Server（从仓库根目录进入）
cd "../../server sync"
uv sync --frozen
uv run pytest
Gitea Actions 会在推送和合并请求时执行文档检查、后端测试、Sync 与社区服务测试、前端测试和 Rust Core 检查。签名 Windows 安装包由受控 Windows Runner 生成；签名材料只通过仓库 Secret 注入。
部署 Sync Server
开发或内网验证可直接运行：
cd "server sync"
uv sync --frozen
uv run uvicorn sync_server.main:app --host 0.0.0.0 --port 18080
管理控制台构建后由 Sync Server 一并提供。正式环境应使用 PostgreSQL、S3 兼容对象存储、独立密钥、TLS 终止、进程守护和定期备份；完整变量与部署方式见 server sync/README.md。
新建 Sync 实例首次启动时会生成仅对本次启动有效的随机管理员密码。管理员首次登录后必须修改账户和密码；修改成功后凭据写入数据库，后续重启不再随机更换。升级已有实例会保留已固定的凭据、Vault、设备和修订记录。
仓库结构
OpenNexus/
├── frontend/ Vue 3 前端与 Tauri/Rust 桌面宿主
├── backend/ FastAPI AI Core、检索、Agent 与模型运行
├── server sync/ Sync v1 服务及 Vue 管理控制台
├── community-server/ 扩展社区服务
├── scripts/ 构建、验收和发布脚本
├── docs/ 架构、接口契约、开发与验收记录
└── .gitea/workflows/ 持续集成与签名发布流水线
文档入口
安全与发布
OpenNexus 将 Vault 内容、模型凭据和扩展权限视为敏感数据。请只安装可信来源的 Skill、Plugin 与主题包，并在授权前检查其权限。服务端部署不得使用示例密钥或开发数据库。
正式发行物通过 Git 标签追踪，并在发布页提供校验和。Windows 安装包的生产门禁还会验证 Authenticode 和 Core 清单签名。本版提供的便携包尚未进行 Authenticode 签名，Windows 可能显示未知发布者提示。
参与开发
提交前请保持前后端契约、类型和文档同步，使用 pnpm、uv 与锁文件安装依赖，并确保相关测试通过。提交信息采用 Conventional Commits，类型标识保留英文，说明使用中文，例如：
feat(sync): 增加设备撤销接口
fix(agent): 修复任务恢复时的重复事件
docs: 更新部署说明
项目仍处于 Alpha 阶段。问题报告应包含版本、操作系统、复现步骤和脱敏后的关联 ID，避免附带 Vault 正文、访问令牌或服务密钥。