release: prepare OpenNexus 0.5.2-alpha1
This commit is contained in:
OpenNexus Release Bot
@@ -1,192 +1,178 @@
|
||||
# OpenNexus
|
||||
|
||||
OpenNexus 是一款本地优先的 AI 笔记与知识中枢。它将 Markdown Vault、全文与向量检索、知识库问答、可审计 Agent、扩展系统和多设备同步整合在一个桌面应用中。笔记与索引由用户掌控；需要模型或同步服务时，再按需连接本地或远程服务。
|
||||
[简体中文](README.zh-CN.md) | **English**
|
||||
|
||||
当前发布版本为 **0.5.0**，主要支持 Windows x64。升级前请备份 Vault。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 主要能力
|
||||
OpenNexus is a local-first AI notebook and knowledge workspace. It combines Markdown vaults, hybrid retrieval, grounded chat, auditable agents, media-to-notes workflows, extensions, and optional multi-device synchronization in one desktop application.
|
||||
|
||||
- **本地知识库**：管理多个 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、模型用量和错误关联信息。
|
||||
> Current release: **0.5.2-alpha1**. Back up important vaults before upgrading an alpha build.
|
||||
|
||||
## 系统结构
|
||||
## Highlights
|
||||
|
||||
- **Course recordings to structured notes** — transcribe real audio or video, review timestamped text, and generate knowledge-point notes with code blocks, Mermaid diagrams, formulas, and function plots when appropriate.
|
||||
- **Personal planning agents** — create goal-oriented agents, generate plans and tasks, control tool permissions, and inspect execution traces.
|
||||
- **Local-first knowledge base** — edit Markdown, manage attachments, and combine SQLite FTS5, vector retrieval, reciprocal-rank fusion, and reranking.
|
||||
- **Provider choice** — connect OpenAI, Anthropic, Ollama, DeepSeek, and OpenAI-compatible endpoints without storing credentials in the WebView.
|
||||
- **Extensible workspace** — install Skills, Plugins, themes, and MCP integrations with explicit permissions and trust review.
|
||||
- **Portable output** — export notes to PDF, HTML, and DOCX; workspace images use content-addressed relative paths.
|
||||
- **Optional synchronization** — sync notes and attachments between devices with conflict preview, revision history, and device revocation.
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
UI[Vue 3 桌面界面] --> HOST[Tauri / Rust Host]
|
||||
HOST --> VAULT[本地 Vault]
|
||||
UI[Vue 3 desktop UI] --> HOST[Tauri / Rust host]
|
||||
HOST --> VAULT[Local Markdown 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[对象存储]
|
||||
CORE --> MODEL[Local or remote models]
|
||||
CORE --> EXT[Skills / Plugins / MCP]
|
||||
HOST <--> SYNC[Optional Sync Server]
|
||||
SYNC --> DB[(PostgreSQL)]
|
||||
SYNC --> OBJ[S3-compatible storage]
|
||||
COMMUNITY[Community prototype] --> EXT
|
||||
```
|
||||
|
||||
桌面端默认在本机运行。Sync Server 是可选组件，只有启用同步时才需要部署。
|
||||
The desktop host owns local filesystem access, credentials, process supervision, and privileged extension operations. The AI Core runs as a separately supervised process over an authenticated local channel. The Sync Server and community prototype are optional components. The Gitea release mirror keeps all components in one monorepo; the public GitHub projects are maintained separately.
|
||||
|
||||
## 使用发布包
|
||||
## Repository layout
|
||||
|
||||
本版提供 Windows x64 EXE 安装包和独立的 Server Sync 包，下载入口见 [v0.5.0 发布页](https://gitea.kronecker.cc/Kronecker/NotesAgentic/releases/tag/v0.5.0)。发布页同时附带 `SHA256.json`，用于核对文件完整性。
|
||||
|
||||
安装包不包含任何 Vault 或用户数据，也不预装已下载的社区主题、本地模型权重、CUDA 与 PyTorch 运行时。相关功能仍完整保留；需要时可在客户端内按需安装主题、选择模型或配置 CUDA 环境。程序自带的基础界面样式属于客户端资源，不视为社区主题。同一 Windows 用户下升级安装会继续使用 `%APPDATA%\cc.kronecker.notesagent` 中的既有配置和索引，以及用户此前选择的外部 Vault。
|
||||
|
||||
1. 下载 Windows x64 EXE 安装包，并核对发布页中的 SHA-256。
|
||||
2. 运行安装程序，按向导完成当前用户安装；未签名的 Alpha 包可能触发 Windows 未知发布者提示。
|
||||
3. 从开始菜单启动 OpenNexus，选择已有 Vault 或创建新 Vault。
|
||||
4. 在“设置 → 模型提供商”中配置本地模型或远程模型凭据。
|
||||
5. 如需多设备同步，在同步设置中填写管理员提供的 Sync Server 地址并登录。
|
||||
|
||||
凭据不会写入前端 `localStorage`。首次试用建议复制一份现有笔记目录，再用副本验证索引和同步行为。
|
||||
|
||||
### 工作区图片存储
|
||||
|
||||
在源码或所见即所得编辑器中粘贴、拖入或选择 PNG、JPEG、GIF、WebP 图片后，OpenNexus 会按内容哈希保存到当前 Vault 的 `attachments/<哈希前两位>/<SHA-256>.<扩展名>`。Markdown 使用相对路径引用图片，因此笔记目录整体复制、导出或同步后仍可定位原图；单张图片上限为 5 MiB，相同内容只保存一份。
|
||||
|
||||
图片二进制不写入 SQLite。数据库中的 `workspace_assets` 保存路径、SHA-256、媒体类型、大小和原始文件名，`workspace_asset_links` 保存图片与笔记的引用关系。另一台设备收到 Vault 文件后，会在首次显示图片时校验路径哈希并重建本机元数据。
|
||||
|
||||
## 开发环境
|
||||
|
||||
| 工具 | 版本 |
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| Node.js | 22 或更高版本 |
|
||||
| pnpm | 10.28.0 |
|
||||
| Python | 3.12 或更高版本 |
|
||||
| uv | 0.9.24 |
|
||||
| Rust | stable，桌面构建需要 |
|
||||
| `frontend/` | Vue 3 UI and Tauri/Rust desktop host |
|
||||
| `backend/` | FastAPI AI Core, retrieval, agents, media processing, and export |
|
||||
| `server sync/` | Sync v1 server and its Vue management console |
|
||||
| `community-server/` | Community catalog and moderation prototype |
|
||||
| `scripts/` | Build, acceptance, and release automation |
|
||||
| `tools/` | Local development and packaging utilities |
|
||||
|
||||
安装依赖：
|
||||
## Public repositories
|
||||
|
||||
| Component | GitHub repository |
|
||||
| --- | --- |
|
||||
| Desktop application and AI Core | [KiriAky107/OpenNexus](https://github.com/KiriAky107/OpenNexus) |
|
||||
| Sync Server | [KiriAky107/Sync-for-OpenNexus](https://github.com/KiriAky107/Sync-for-OpenNexus) |
|
||||
| Community prototype | [KiriAky107/Community-for-OpenNexus](https://github.com/KiriAky107/Community-for-OpenNexus) |
|
||||
|
||||
The Gitea distribution repository remains a monorepo so a release can be built and demonstrated from one revision. GitHub keeps the three independently deployable components in separate repositories.
|
||||
|
||||
## Install the desktop app
|
||||
|
||||
1. Download `OpenNexus_0.5.2-alpha1_x64-setup.exe` from the [v0.5.2-alpha1 release](https://gitea.kronecker.cc/Kronecker/NotesAgentic/releases/tag/v0.5.2-alpha1).
|
||||
2. Verify the published SHA-256 checksum.
|
||||
3. Run the installer and start OpenNexus from the Start menu.
|
||||
4. Select or create a Markdown vault.
|
||||
5. Configure a local or remote model under **Settings → Model providers**.
|
||||
|
||||
The installer contains no user vault, downloaded model weights, CUDA runtime, or preinstalled community package. Existing configuration and indexes remain under `%APPDATA%\cc.kronecker.notesagent` during an in-place upgrade.
|
||||
|
||||
## Development
|
||||
|
||||
### Requirements
|
||||
|
||||
| Tool | Version |
|
||||
| --- | --- |
|
||||
| Node.js | 22+ |
|
||||
| pnpm | 10.28.0 |
|
||||
| Python | 3.12+ |
|
||||
| uv | 0.9.24 |
|
||||
| Rust | stable |
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
uv sync --frozen
|
||||
|
||||
cd ../frontend
|
||||
corepack enable
|
||||
corepack prepare pnpm@10.28.0 --activate
|
||||
pnpm install --frozen-lockfile
|
||||
```
|
||||
|
||||
启动 Web 开发环境：
|
||||
Run the web development stack:
|
||||
|
||||
```powershell
|
||||
# 终端一：AI Core
|
||||
# Terminal 1: AI Core
|
||||
cd backend
|
||||
uv run python scripts/dev-server.py
|
||||
|
||||
# 终端二：前端
|
||||
# Terminal 2: frontend
|
||||
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>。
|
||||
|
||||
启动和构建桌面应用：
|
||||
Build the Windows desktop application:
|
||||
|
||||
```powershell
|
||||
cd frontend
|
||||
pnpm desktop:dev
|
||||
pnpm desktop:build
|
||||
```
|
||||
|
||||
## 运行测试
|
||||
## Tests
|
||||
|
||||
```powershell
|
||||
# 后端
|
||||
# Backend
|
||||
cd backend
|
||||
uv run pytest
|
||||
|
||||
# 前端
|
||||
# Frontend
|
||||
cd ../frontend
|
||||
pnpm test
|
||||
pnpm type-check
|
||||
pnpm build
|
||||
|
||||
# Rust Host
|
||||
# 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"
|
||||
# Sync Server
|
||||
cd "../../../server sync"
|
||||
uv sync --frozen
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
Gitea Actions 会在推送和合并请求时执行文档检查、后端测试、Sync 与社区服务测试、前端测试和 Rust Core 检查。签名 Windows 安装包由受控 Windows Runner 生成；签名材料只通过仓库 Secret 注入。
|
||||
## Run the Sync Server
|
||||
|
||||
## 部署 Sync Server
|
||||
|
||||
推荐使用 Docker Compose 启动 PostgreSQL、MinIO 和 Sync：
|
||||
The recommended deployment uses Docker Compose with PostgreSQL and S3-compatible object storage:
|
||||
|
||||
```powershell
|
||||
cd "server sync"
|
||||
Copy-Item .env.example .env
|
||||
# 编辑 .env 并生成各项独立密钥
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
隔离测试阶段如需直接开放 `18080` 明文端口，可使用 Docker Compose 2.24.4 或更高版本加载测试覆盖文件：
|
||||
Use independent production secrets, TLS termination, process supervision, and regular backups. Plain HTTP options are intended only for isolated demonstrations and local testing.
|
||||
|
||||
```powershell
|
||||
docker compose -f compose.yaml -f compose.test.yaml up -d --build
|
||||
```
|
||||
## Security and privacy
|
||||
|
||||
不使用容器的开发联调也可直接运行：
|
||||
- Vault content stays local unless the user explicitly enables a remote model, synchronization, or another network integration.
|
||||
- Provider credentials are stored by the desktop credential vault and are not persisted in frontend `localStorage`.
|
||||
- Extension permissions, network access, and privileged tool calls are reviewed before authorization.
|
||||
- Logs and bug reports must not contain vault text, access tokens, provider keys, or personal information.
|
||||
- Only install Skills, Plugins, themes, and MCP servers from sources you trust.
|
||||
|
||||
```powershell
|
||||
cd "server sync"
|
||||
uv sync --frozen
|
||||
uv run uvicorn sync_server.main:app --host 0.0.0.0 --port 18080
|
||||
```
|
||||
Please report security issues privately to the repository maintainers instead of opening a public issue with sensitive details.
|
||||
|
||||
管理控制台构建后由 Sync Server 一并提供。正式环境应使用 PostgreSQL、S3 兼容对象存储、独立密钥、TLS 终止、进程守护和定期备份；完整变量与部署方式见 [`server sync/README.md`](server%20sync/README.md)。
|
||||
## Contributing
|
||||
|
||||
新建 Sync 实例首次启动时会生成仅对本次启动有效的随机管理员密码。管理员首次登录后必须修改账户和密码；修改成功后凭据写入数据库，后续重启不再随机更换。升级已有实例会保留已固定的凭据、Vault、设备和修订记录。
|
||||
|
||||
## 仓库结构
|
||||
Use locked dependencies, keep frontend/backend contracts synchronized, and run the relevant test suites before submitting a change. Commit messages follow Conventional Commits, for example:
|
||||
|
||||
```text
|
||||
OpenNexus/
|
||||
├── frontend/ Vue 3 前端与 Tauri/Rust 桌面宿主
|
||||
├── backend/ FastAPI AI Core、检索、Agent 与模型运行
|
||||
├── server sync/ Sync v1 服务及 Vue 管理控制台
|
||||
├── community-server/ 扩展社区服务
|
||||
├── scripts/ 构建、验收和发布脚本
|
||||
├── docs/ 架构、接口契约、开发与验收记录
|
||||
└── .gitea/workflows/ 持续集成与签名发布流水线
|
||||
feat(sync): add device revocation
|
||||
fix(export): restore PDF rendering in packaged builds
|
||||
test(agent): cover interrupted task recovery
|
||||
```
|
||||
|
||||
## 文档入口
|
||||
OpenNexus is currently an alpha project. Issues should include the application version, operating system, reproduction steps, and redacted correlation IDs.
|
||||
|
||||
- [文档索引](docs/README.md)
|
||||
- [前端开发说明](frontend/README.md)
|
||||
- [后端开发说明](backend/README.md)
|
||||
- [Sync Server 说明](server%20sync/README.md)
|
||||
- [第三阶段实施与验收记录](docs/development/第三阶段实施与验收记录.md)
|
||||
- [后端接口契约](docs/contracts/后端接口契约-开发版.md)
|
||||
## License
|
||||
|
||||
## 安全与发布
|
||||
|
||||
OpenNexus 将 Vault 内容、模型凭据和扩展权限视为敏感数据。请只安装可信来源的 Skill、Plugin 与主题包，并在授权前检查其权限。服务端部署不得使用示例密钥或开发数据库。
|
||||
|
||||
正式发行物通过 Git 标签追踪，并在发布页提供校验和。Windows 安装包的生产门禁还会验证 Authenticode 和 Core 清单签名。本版 EXE 安装包尚未进行 Authenticode 签名，Windows 可能显示未知发布者提示。
|
||||
|
||||
## 参与开发
|
||||
|
||||
提交前请保持前后端契约、类型和文档同步，使用 pnpm、uv 与锁文件安装依赖，并确保相关测试通过。提交信息采用 Conventional Commits，类型标识保留英文，说明使用中文，例如：
|
||||
|
||||
```text
|
||||
feat(sync): 增加设备撤销接口
|
||||
fix(agent): 修复任务恢复时的重复事件
|
||||
docs: 更新部署说明
|
||||
```
|
||||
|
||||
项目仍处于 Alpha 阶段。问题报告应包含版本、操作系统、复现步骤和脱敏后的关联 ID，避免附带 Vault 正文、访问令牌或服务密钥。
|
||||
OpenNexus project code is licensed under the [MIT License](LICENSE). Bundled models, libraries, fonts, icons, and other third-party components remain subject to their own licenses and notices; the project MIT License does not replace those terms.
|
||||
|
||||
Reference in New Issue
Block a user