GeoChat Desktop

本地优先的 AI 数学可视化工作台。输入题目，GeoChat 自动构造、作图并解释。

English · 官网 · 下载 · 预览 · 快速开始 · 功能 · Star History

当前稳定版：v0.5.0 · 官网：https://geochat.ivory.cafe

预览

截图

视频

演示视频 1

无法播放时打开视频文件

演示视频 2

无法播放时打开视频文件

项目介绍

GeoChat Desktop 是一个本地优先的 AI 数学可视化工作台，核心是内嵌的 GeoGebra 画板。它把 Tauri 2 桌面外壳、React 渲染层、本地 Bun 后端 sidecar、SQLite 持久化，以及 @geochat-ai/app 中的共享 Agent 协议组合在 一起。

这个仓库面向可本地运行的桌面版本。你可以使用自己的模型供应商密钥运行本地 工作区，不需要在线校验才能使用核心桌面功能。

功能

能力	说明
数学画板	本地 2D/3D 数学可视化画布，适合构造、验证和讲解几何关系。
AI 作图流程	输入题目后生成构造步骤、写入画板，并解释关键关系。
自带模型密钥	用户在本机配置模型供应商 API key，不需要在线校验才能使用核心桌面功能。
本地持久化	使用 SQLite 保存本地对话、黑板和 Agent 运行记录。
题库工具	包含本地题库数据模型、导入工具和回归测试。
桌面调试	内置桌面调试 MCP 工具，便于本地检查和 smoke testing。
Tauri 打包	桌面外壳集成 Bun runtime sidecar 和可替换 app-bundle 资源。

仓库内容

backend/          本地 Bun 后端、HTTP 路由、SQLite 仓库和服务。
packages/app/     共享 schema、Agent 协议、策略和 GeoGebra 辅助逻辑。
src/renderer-react/ React 桌面工作台 UI。
src/shared/       渲染层和后端共享的 TypeScript 工具。
src-tauri/        Tauri 外壳、Rust 命令桥、打包和 sidecar 控制。
tests/            合同测试和回归测试。
tools/            本地数据导入、smoke 和桌面调试工具。
vendor/geogebra/  桌面应用使用的 GeoGebra runtime 资源。
docs/             架构、产品和开发说明。
scripts/          本地构建、bundle 和验证脚本。

环境要求

• Bun 1.3.11 或兼容版本。
• Rust stable toolchain。
• Tauri 2 所需的平台构建工具。
  • macOS: Xcode Command Line Tools。
  • Windows: Microsoft C++ Build Tools 和 WebView2 runtime。
  • Linux: Tauri 所需的 WebKitGTK 和原生构建包。

本项目使用 Bun 作为包管理器，并用 Bun 运行本地后端。

快速开始

bun install
bun run dev

bun run dev 会启动 Tauri 桌面应用。开发模式下，除非 GEOCHAT_DESKTOP_BACKEND_URL 指向已有后端，否则桌面外壳会自动启动本地 Bun 后端。

默认 SQLite 数据库路径：

./data/geochat-desktop.sqlite

需要时可以覆盖：

GEOCHAT_DESKTOP_DB_PATH=./data/dev.sqlite bun run dev

模型配置

打开应用设置，只配置并保存各模型供应商的 API key。密钥会保存在当前设备的桌面配置中。

在对话页面选择供应商和具体模型；配置页不负责选择模型。共享模型注册表会根据 已保存的供应商 key 提供可用选项。

常用命令

bun run dev                 # 启动 Tauri 桌面开发应用。
bun run backend:dev         # 只启动本地后端。
bun run typecheck           # 检查共享、Node 和渲染层 TypeScript。
bun test tests              # 运行 Bun 测试套件。
bun run tauri:check         # 对 Tauri 外壳运行 cargo check。
bun run tauri:prepare       # 构建后端、渲染层、vendor、runtime 和 manifest。
bun run build               # 类型检查并准备 app bundle。
bun run dist                # 构建本地 Tauri 应用包。

桌面 MCP 批量测试需要两个进程使用同一个本地 token：

GEOCHAT_DESKTOP_LOCAL_AUTH_TOKEN=dev-batch-token bun run dev
GEOCHAT_DESKTOP_LOCAL_AUTH_TOKEN=dev-batch-token bun tools/run-desktop-problem-batch.ts

App Bundle 边界

打包后的桌面应用是围绕 app-bundle 资源运行的 Tauri 外壳。外壳负责原生命令、 窗口生命周期、固定 Bun runtime sidecar 和打包流程。app bundle 负责已编译 的后端代码、已编译的渲染层文件和 vendor 资源。

bun run tauri:prepare 会生成：

dist/backend/backend.bundle.js
dist/renderer/index.html
dist/vendor/**
dist/runtime/bun
dist/app-bundle-manifest.json

app-bundle manifest 只列出 backend、renderer 和 vendor 资源，不应包含 dist/runtime；Bun 是固定的 runtime sidecar。

常用本地检查：

bun run tauri:prepare
bun run bundle:smoke
bun run package:backend-smoke

开发说明

• GeoGebra runtime 资源从 vendor/geogebra 本地提供。
• 本地后端提供桌面健康检查、资源、对话、题库、供应商代理和 Agent 运行路由。
• 用户应在运行时提供模型 API key。不要提交本地凭据、.env、.dev.vars、 SQLite 数据库或生成产物。
• 公开仓库边界见 docs/open-source-boundary.md。
• GeoGebra 集成说明见 docs/geogebra-applet.md。
• Agent runner 架构见 docs/agent-harness-roadmap.md。
• Tauri 外壳说明见 docs/tauri2-shell-migration-plan.md。

发布前验证

推送发布分支或公开镜像前运行：

bun run oss:check
bun run typecheck
bun run tauri:prepare
bun run tauri:check
bun test tests

发布桌面版

使用根目录的发布脚本统一更新 package.json、src-tauri/Cargo.toml、 src-tauri/Cargo.lock、src-tauri/tauri.conf.json 和官网的 fallback 版本。默认只修改本地文件并执行检查， 不会创建提交、tag 或推送远程：

bun run release -- --version 0.5.1

确认版本和检查结果后，可以分步提交和打 tag：

bun run release -- --version 0.5.1 --commit --tag
git push origin master
git push origin v0.5.1

也可以在确认工作区干净且当前分支为 master 后一次完成推送：

bun run release -- --version 0.5.1 --commit --tag --push

--push 会触发 .github/workflows/tauri-package.yml：它先运行验证，随后构建 Windows/macOS 安装包、创建 GitHub Release，并在配置了 R2 时上传安装包和 latest.json；同一个发布提交还会触发 website.yml 构建并部署 Cloudflare Pages。 脚本会等待并检查 Actions、Release、R2 manifest、Pages 部署，以及官网首页和 下载页的版本同步。使用 --no-watch 可跳过远程等待，--dry-run 可预览动作， --skip-checks 仅适用于明确知道风险的本地调试场景。R2 和官网检查分别使用 GEOCHAT_DOWNLOADS_BASE_URL、GEOCHAT_SITE_URL 环境变量。

当前 v0.5.0 发布已验证 Windows/macOS 安装包、GitHub Release、Cloudflare R2 镜像和 Cloudflare Pages 部署链路。官网自定义域名需要在 Cloudflare Pages 中将 geochat.ivory.cafe 绑定到 geochat-7l8.pages.dev。

发布到新的公开远程仓库前，建议再运行一次外部历史敏感信息扫描。普通本地模式 扫描有帮助，但不能替代完整历史扫描。

版权和作者

• Copyright (c) 2026 Ivory.
• Author: Ivory contact@ivory.cafe
• GeoChat 自有源代码和文档使用 Apache License, Version 2.0。见 LICENSE 和 NOTICE。
• 本仓库也包含使用各自许可证的第三方组件。尤其是 vendor/geogebra/ 不会被 重新授权为 GeoChat 自有的 Apache-2.0 代码。重新分发包含 GeoGebra runtime 的构建前，请阅读 THIRD_PARTY_NOTICES.md 和 GeoGebra 许可证条款。

贡献

保持改动聚焦且可验证：

• 优先沿用现有项目模式。
• 行为变化需要新增或更新测试。
• 运行上面列出的相关检查。
• 不要提交凭据、本地数据库或生成产物。

安全相关报告不要在 issue 文本、日志、截图或复现数据中包含真实凭据。

Star History

如果这个项目对你有帮助，欢迎给一个 Star。它能帮助我们判断哪些方向值得继续投入。