VIVATLAS

VIVATLAS

您收集各种工具：Claude 技能、Agent、MCP 服务、半夜点了星标的网页抓取工具、某人在 Reddit 上分享的设计套件。它们散落在 GitHub 星标、自托管的 Gitea、浏览器书签和笔记应用中——三个月后，您只记得“有个东西能做这个”，却怎么也找不到。

VIVATLAS 就是您的收藏架。把您的仓库和收藏的链接交给它，它会将每项内容整理成一张卡片：名称、写给人而不是编译器看的描述、图片和标签。然后将它们放在一个地方，让您可以按含义而不仅仅是名称搜索。向它询问“能审查网站无障碍性的工具”，它就会给您三个候选项，并说明推荐理由。

它运行在您自己的设备上——NAS、备用主机或笔记本电脑都可以；它支持多人使用，而且只会读取内容。只读取公开仓库，绝不会向 Git 写入任何内容。

试用在线演示

安装前先试用。 demo1.bobpanil.com 是一个公开的 VIVATLAS 演示站点。在登录页面点击 试用，即可创建自己的私人账户，然后浏览目录、进行搜索并添加链接或笔记。账户及您添加的所有内容都会在 24 小时后删除。演示站点不使用 AI，因此您添加的卡片内容比较简单，搜索按词语匹配，而非按含义匹配。它始终运行最新版本。

它能为您做什么

每张卡片都有自己的样子

没人愿意浏览一整面灰色方块。VIVATLAS 会找到每个项目自己的图片——README 顶部的横幅、仓库中的标志，或 GitHub 为它生成的卡片图——并剔除那些看起来像图片的内容：构建状态徽章、赞助商标志、“请我喝咖啡”按钮和所有者头像。如果一个项目有多个合适的图片候选项，负责撰写描述的 AI 会将它们并排查看，然后挑出真正展示该项目的那张。

如果项目完全没有图片，VIVATLAS 就会自行绘制封面——将名称以专属字体排版在彩色图案背景上，颜色和图案由名称生成，因此每张封面都独一无二，同时整体风格统一。不用模型、不花成本，绝不会是灰色。

近距离查看卡片

打开卡片，您就能以三种形式了解同一个项目：一句话简介、写给普通读者的段落，以及帮助您判断是否要使用它的技术说明。还可以查看带置信度的标签、用途、来源和上次更改时间，并使用重新扫描、归档或复制链接按钮。描述由您配置的 AI 根据仓库自己的 README 撰写。

像询问同事一样搜索

全文索引和向量索引协同工作：前者查找词语，后者理解含义。用俄语输入，也能找到英语工具。描述任务，而不必说出工具名称，推荐器就会返回三个选项，并分别用一句话说明推荐理由；如果没有合适的结果，它也会坦诚地说“这里没有合适的内容”——这在软件领域本不该如此罕见。

随处收藏

• 浏览器扩展（Chrome、Edge、Brave、Firefox）：一键将当前页面或粘贴的链接添加到你的目录，可设为公开或私有。→ extension/README.md

  

• Android 应用：在任意应用中选择“分享”→ VIVATLAS。弹出的简洁面板会显示你要保存的内容，并让你在保存前选择设为私有还是公开。扫描已登录浏览器中的二维码即可登录，无需在手机键盘上输入长密码。→ android/README.md

• 网页表单：链接、网站、截图或短视频 → 带星级的候选项 → 选择 → 添加到你的目录中。

**安装 Android 应用：**从 F-Droid 获取 ，它会为应用保持更新。也可以从最新版本下载 vivatlas-android-<version>.apk，或者将此仓库添加到 Obtainium，由它自动更新。应用在整个生命周期内都使用同一个密钥签名，因此每个版本都能覆盖安装在前一个版本之上。

你的、他们的、所有人的

每个人都有自己的登录账号、私有卡片和个人文件夹。共享目录对所有人开放，由管理该空间的人负责整理。卡片可以在两者之间移动——由所有者决定。你还可以保存收藏、查看变更动态，并了解哪些卡片的上游内容已过时。

向 AI 助手提问

VIVATLAS 是一个 MCP 服务。将它连接到 ChatGPT、Claude 或任何支持 MCP 的工具，就能从你的目录中获得“我有哪些工具可以做 X？”的答案。此外还提供简单的 REST API。→ docs/MCP.md

其他功能，简要介绍

支持三种语言（英语、俄语、希伯来语，并妥善处理从右向左的排版）。提供浅色、深色、OLED 和跟随系统主题。支持带备用代码的两步登录。可通过链接或电子邮件发送邀请，也可按需开放注册。支持 Gitea 和 GitHub 作为来源，每天重新扫描。管理面板可管理用户、文件夹、电子邮件和 AI 密钥——所有设置都可在不重启的情况下更改。还有 upstream / update，可将卡片与其来源进行比较，并且只在你尚未修改的文件中导入新版本。

五分钟内试用

最快的方式是使用容器：

docker run -d --name vivatlas -p 8710:8710 -v vivatlas_data:/data ghcr.io/bobpanil/vivatlas:latest

打开 http://localhost:8710，第一个访问 /setup 的人将成为所有者。然后前往 Admin → Sources：添加 GitHub 账号或 Gitea 地址，点击 Scan now，就能看到卡片陆续出现。

也可以直接从源码运行：

python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"        # Windows: .venv\Scripts\python.exe
cp .env.example .env                               # set SECRET_KEY; everything else is optional

.venv/bin/python -m vivatlas.cli init-db           # create or update the database
.venv/bin/python -m vivatlas.cli scan              # fetch repositories
.venv/bin/python -m vivatlas.cli serve --host 0.0.0.0 --port 8710

--host 0.0.0.0 可让同一 Wi-Fi 网络中的手机访问。更新代码后，请再次运行 init-db——serve 不会自行迁移数据库（容器会在每次启动时执行迁移）。

如果要在家中正式部署，请参阅 docs/DEPLOY-TRUENAS.md 中关于 TrueNAS SCALE 的操作指南——其中也介绍了 VIVATLAS 部署在代理或隧道之后时需要注意的两项设置。

你可能真正想要的设置

所有可选设置都放在 .env（或容器的环境变量）中；.env.example 对它们都有注释。大家常问的是这些：

它遵循的规则

VIVATLAS 是查看器，不是所有者。 它读取公开的 Git 仓库，帮助你查找和查看其中的工具。它不拥有、也不主张对其收录或链接的任何仓库、代码、名称或商标享有权利。这些均归其作者所有，并受各自许可证约束。

它不会向 Git 写入任何内容，也不会扫描私有仓库。 这是规则，不是设置：任何地方都没有相关开关。

许可证： 服务端——src/ 下的所有内容——采用 Business Source License 1.1：可免费使用、部署和修改，包括用于商业用途；但不得将 VIVATLAS 本身作为产品或托管服务出售或转售。该许可证将于 2030-07-21 转为 Apache-2.0。Android 应用（android/）也可以使用 Apache-2.0，因此可通过 F-Droid 构建和分发。浏览器扩展（extension/）同样采用 Apache-2.0。

测试

.venv/bin/python -m pytest
.venv/bin/python -m ruff check src tests

src/vivatlas/
  config.py            settings from .env
  runtime_settings.py  overrides from the database on top of .env (edited from the admin panel)
  db.py                connection to SQLite
  models.py            tables
  migrate.py           init-db: add missing columns/indexes, rebuild search
  security.py          passwords, secret encryption, secret key
  twofactor.py         two-step sign-in (TOTP + backup codes)
  auth.py, auth_web.py sign-in, registration, invitations, password reset
  qrlogin.py           sign a phone in by a one-time QR shown on a signed-in browser
  admin_web.py         admin panel (people, access, email, integrations)
  settings_web.py      personal settings, avatars, sources, folders
  web.py               catalogue, cards, adding
  api.py               app assembly, REST, background loops, static
  filters.py           visibility: own + shared
  categories.py        folder permissions (shared/personal)
  i18n.py, translations*.py   translations (en/ru/he), RTL
  mailer.py            emails (password reset, invitations)
  avatars.py           uploaded photo → square WebP
  previews.py          the picture on a card: find it, fetch it, fit it — or draw a cover
  ai/                  the models: google.py (text, vision, images), ollama.py, pollinations.py
  usericons.py         default avatar set (static/usericons)
  scanner.py, indexer.py  scanning + the private-repo rule, index
  mcp_server.py        MCP server for AI assistants
  cli.py               terminal commands (init-db, scan, serve, previews, embed, upstream…)
  providers/
    base.py            common interface to a Git host (the "socket")
    gitea.py           Gitea
    github.py          GitHub (an account's public repositories)
  ext_api.py           JSON API for the browser extension and the Android app (/api/ext)
  templates/, static/  pages and styles (hand-written CSS, no build step)

extension/             browser extension for Firefox and Chromium (Manifest V3)
android/               Kotlin WebView shell: share target, QR sign-in