内容
VIVATLAS
一个来自您的仓库的技能、代理和工具目录。多用户：每个人都有自己的自己的文件夹和来源；共享目录对所有人都是通用的。
VIVATLAS 是一个查看器，而不是所有者。** 它读取* Git 仓库，并帮助您找到和查看其中的工具。它 **不** 拥有 — 也不声称拥有 — 它编目或链接到的任何仓库、代码、名称或商标。这些属于它们的作者，并受其自己的许可协议管辖。
**许可证：** [商业源代码许可证 1.1](LICENSE) — 免费使用、部署和修改，包括商业用途；您 **不能** 出售或转售 VIVATLAS 本身（作为托管服务）。在 -07-21 Apache-2.0。
从 AI 助手（MCP）访问：[docs/MCP.md](CP.md)。在 True部署：[docs/DEPLOY-TRUENAS.md](docs-TRUENAS.md)。
## 已实现功能
- **卡片目录。** 一个仓库 → 一张卡片：名称、三级简短 / 正常 /预览、标签（自动，和置信度 + 手动，手动优先）。
- **搜索词语（SQLite FTS含义（向量），双语 — 俄语查询可找到英文工具。
- **推荐** — 任务的三个选项，附有解释，或诚实的“没有匹配”。
- **文件夹** — 共享（由管理员运行）和个人（每个人都有自己的）；卡片可以拖入文件夹。Git 在此过程中未被触及。
- **区域** — 卡片是私有的还是共享的（在目录中）；收藏、草稿、变更动态和“过时”动态。
- **人员。** 通过密码登录，第一个登录的人成为所有者。通过链接/电子邮件邀请，开放注册（切换），两步登录（TOTP + 备份代码），通过电子邮件重置密码。
- **账户。** 更改电子邮件/密码、删除、个人资料照片（→ WebP）或从现成的集合（经典胸像）中选择头像，个人文件夹和来源。
- **管理员面板。** 人员、访问和邀请、共享文件夹、电子邮件（SMTP）、集成（地址/令牌/模型基于 `.env`，无需重启即可应用）。
- **界面。** 服务器上的自定义渲染，无需构建步骤。语言：英语（默认）、俄语、希伯来语（RTL）。主题：浅色 / 深色 / OLED / 系统。也可以从手机访问。
- **来源。** Gitea（共享和个人）和 GitHub（帐户或组织的公共仓库），每天扫描和按需扫描。失败的 AI 摘要将自动重试。
- **添加。** 一个入口：链接、网站、截图或视频 → 带有星级的候选 → 计划 → 导入。模型命名的地址始终与主机一起验证。
- **浏览器扩展。** Chrome/Chromium 扩展（`extension/`）将当前页面或粘贴的链接剪辑到您的目录中，公共或私有，来自任何选项卡。参见 [extension/README.md](extension/README.md)。
- **上游。** 卡片记得它的来源；`upstream` 比较，`update` 只在您未触及文件时安装新版本。
- **外部。** 用于 AI 助手（MCP）的 REST API 和 MCP 服务器。
主要规则保持不变：**程序不会向 Git 写入任何内容，也不会扫描私有仓库。** 只读取公共仓库。
## 运行
```bash
python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[dev]" # Windows
# .venv/bin/python -m pip install -e ".[dev]" # Linux
cp .env.example .env # SECRET_KEY 是必需的；Gitea 地址和密钥是可选的（可以从管理员面板设置）
.venv/Scripts/python.exe -m vivatlas.cli # 创建/更新数据库
.venv/Scripts/python.exe -m vivatlas.cli scan # 获取仓库
.venv/Scripts/python.exe -m vivatlas.cli serve --host 0.0.0 --port 8710
```
在 `http://127.0.1:8710` 打开（使用 `--host 0.0.0` — 也可以从同一网络上的）。第一个通过 `/setup` 的人成为所有者。
> **更新代码后，运行 `init-db`** — 它会向数据库添加新列。`serve` 不会运行迁移：使用旧数据库启动新代码，缺少字段的页面将损坏。
## 测试
```bash
.venv/Scripts/python.exe -m pytest
.venv/Scripts/python.exe -m ruff check src tests
```
## 布局
```
src/vivatlas/
config.py 来自 .env 的设置
runtime_settings.py 在 .env 之上的数据库覆盖（从管理员面板编辑）
db.py 连接到 SQLite
models.py 表
migrate.py init-db：添加缺失的列/索引，重新构建搜索
security.py 密码，秘密加密，秘密密钥
twofactor.py 两步登录（TOTP + 备份代码）
auth.py, auth_web.py 登录，注册，邀请，密码重置
admin_web.py 管理员面板（人员，访问，电子邮件，集成）
settings_web.py 个人设置，头像，来源，文件夹
web.py 目录，卡片，添加
api.py 应用程序组REST，/avatar，静态
filters.py 可见性：自己的 + 共享的
categories.py 文件夹权限（共享/个人）
i18n.py, translations*.py 翻译（en/ru/he），RTL
mailer.py 电子邮件（密码重置，邀请）
avatars.py 上传照片 → 正方形 WebP
usericons.py 默认头像集（静态/usericons）
scanner.py, indexer.py 扫描 + 私有仓库规则，索引
mcp_server.py 用于 AI 助手的 MCP 服务器
cli.py 终端命令（init-db，scan，serve，embed，upstream...）
providers/
base.py 主机的公共接口（“套接字”）
gitea.py Gitea
github.py GitHub（帐户仓库）
ext 浏览器扩展的 JSON API（/api/ext）
templates/, static/ 页面和样式（自定义 app.css，无构建步骤）
extension/romium 扩展（Manifest）— 将页面剪辑到 VIVATLAS
另一个主机：在新的提供者中实现 `providers/base.py` `providers/__init
