Guaardvark

为什么选择 Guaardvark

• 在你的设备上运行。 语言模型、检索、Agent 和所有生成器都通过 Ollama、ComfyUI 和 Guaardvark 自有的 GPU 服务，在你的硬件上运行。无需云端 API 密钥，没有按 token 或按分钟计费，也不会向外发送任何信息。网络访问、发布及所有其他出站通道在你启用或启动之前都会保持关闭，并且都在一个文件 egress.json 中声明。
• 一次安装，获得完整工作室。 聊天和 RAG、屏幕 Agent、编码 Agent 集群以及完整的媒体流水线，通过单一编排器共享一块 GPU，因此视频渲染和语言模型会轮流使用 GPU，而不是争抢显存。
• 编码 Agent 可以操控它。 内置的 MCP 服务、十五种 Agent 技能和 Claude Code 插件，让 Claude Code、Cursor、Codex、Gemini CLI 及其他 Agent 能运行所有工作流：“用这首歌制作音乐视频”“拍摄这份脚本”“训练这个角色的 LoRA”“让 Agent 集群重构这段代码”。
• 重要操作由你批准。 未经你明确同意，不会发布任何内容，也不会克隆任何语音；Guaardvark 为自身代码编写的修复也会等待你审查。除非你将桌面、Shell 和浏览器工具加入许可名单，否则 MCP 服务不会显示这些工具。

快速开始

配备 NVIDIA GPU 的 Linux（视频需要 16 GB，Wan 2.2 5B 需要 12 GB；聊天、RAG 和 Agent 所需配置更低，请参阅硬件配置档）。全新安装的 Ubuntu 桌面没有 curl 或 git；请先运行 sudo apt install -y curl git。

curl -fsSL https://guaardvark.com/install.sh | bash

然后打开 **http://localhost:5173**。脚本是此仓库中的 install.sh：它会克隆到 ~/guaardvark 并运行 ./start.sh，首次运行时会安装所有内容。若要在运行前查看脚本，请先下载（curl -fsSL https://guaardvark.com/install.sh -o install.sh，阅读后再运行 bash install.sh），或手动安装。

添加到 Claude Code（两行命令，无需克隆）：

/plugin marketplace add guaardvark/guaardvark
/plugin install guaardvark@guaardvark

其他安装方式：Docker · Apple Silicon 上的 macOS · 从 PyPI 安装 CLI · 完整安装指南。当前版本见 VERSION 文件。

功能

• 与自己的文件聊天。 基于 pgvector 的本地 RAG：每次查询融合关键词搜索与向量搜索，使用交叉编码器重排，提供来源引用，并在检索中显示答案背后的文本块和分数。自动研究会在夜间优化检索。▶ 第 3 集
• 在真实桌面上运行 Agent。 屏幕 Agent 拥有自己的 Ubuntu 桌面，使用视觉模型观察桌面，通过闭环定位进行点击，并在真实浏览器中工作，你可以从任意页面旁观。▶ 第 4 集
• 并行编码 Agent。 多个编码 Agent 各自在独立的 git worktree 中工作，再按依赖顺序合并。可使用 Claude Code，也可通过 Ollama 完全本地运行。
• 双向支持 MCP。 MCP 服务只需一条命令即可接入 Claude Code、Cursor、Codex、Gemini CLI、Zed 等；此外还提供 MCP 客户端，让聊天可以使用其他服务提供的工具。▶ 第 21 集 · ▶ 第 16 集
• 视频生成。 支持五个系列的 13 种本地视频模型（Wan 2.2、LTX、HunyuanVideo、CogVideoX，以及自带配乐的 MiniMax H3）、视频 LoRA、批量队列、帧插值，以及一键接入 ComfyUI。▶ 第 6 集
• LoRA 训练与角色一致性。 使用少量参考照片，在自己的 GPU 上训练角色、环境和道具 LoRA；导入在其他地方训练的 LoRA；并在图像、视频、音乐视频和 Film Crew 制作中保持同一角色。详情
• 图像。 支持生成 Z-Image、FLUX.1、Krea 2、SDXL 和 Sana Sprint 图像（即使使用 8 GB 显卡，也能在几秒内生成 1024 分辨率静态图）；支持通过指令编辑照片、图像修复与扩展，以及 4K/8K 放大。▶ 第 5 集
• 音乐与语音。 支持生成带人声的完整歌曲和音效，提供三种神经网络文本转语音引擎、需经同意的语音克隆，以及免提语音聊天。▶ 第 7 集
• 导演工具。 提供与节拍同步的音乐视频导演、可将故事梗概制作成完整视频的五人 Film Crew，以及内置视频编辑器。▶ 第 8 集 · ▶ 第 9 集
• 自我改进。 Guaardvark 会自我测试、拟定修复方案，并在代码库锁保护下暂存更改供你审核；System Map 根据实际导入关系绘制整个代码库。▶ 第 11 集 · ▶ 第 14 集
• 指挥中心。 提供 GPU 编排器、带实时 VRAM 预算的插件管理器、作业与调度、感知架构的备份，以及多机 Interconnector。▶ 第 12 集
• 终端与 API。 提供带交互式 REPL 的 guaardvark CLI，以及 REST 和 Socket.IO。▶ 第 20 集

完整列出的模型、工具、插件和页面清单见 CAPABILITIES.md。

与自己的文件聊天（本地 RAG）

上传文档，为每个项目构建知识库，然后提问。回答以你的文件为依据，并注明出处。

• **混合检索。**结合 Postgres 全文关键词搜索和向量搜索，并按查询动态调整权重：标识符类查询偏重关键词，散文类查询偏重语义。
• **交叉编码器重排。**重排器（在 Settings 中安装一个）会同时读取查询和段落，并重新排列候选结果。系统会根据可用 VRAM 决定是否启用；如果显存不足，则改用 CPU，以免与图像或视频生成争抢资源。
• **感知布局的解析。**解析 PDF、DOCX 和 PPTX 时会保留阅读顺序和章节标题，PDF 段落还会记录来源页码。（扫描文档需要 OCR，默认未安装；系统会明确提示，而不会将其作为空内容编入索引。）
• **有依据的引用。**每个块都带有源文件和章节路径（PDF 还会记录页码），这些信息也会写入嵌入文本，因此即使段落摘自文档中间，也能标明出处。
• **智能分块。**代码会根据 AST 生成分块，让函数保持在同一个块中；散文则会按语义切分。
• **由 Postgres 支持的向量存储。**嵌入向量保存在 pgvector 中，与其他数据放在一起，并配有 ANN 索引和持久化全文索引，统一纳入同一套备份。
• **展示检索过程。**实时检索测试会展示答案背后的实际文本块和分数（第 3 集）；每次查询还可返回检索链路轨迹，显示运行了哪些检索环节，从而区分答案质量下降和检索错误。
• **更多功能：**索引配置（以多种方式处理同一批文档）、用于总结“这些内容有哪些主题”的语料库级摘要、从 300M 到 4B+ 的多种嵌入模型、实体提取，以及按项目隔离。

**Autoresearch 在你睡觉时优化检索。**夜间循环会提出分块和检索设置的变更，通过 LLM-as-judge 测试框架为其评分，保留有效改进并回退退步项，同时受运行时限、运行台账和熔断器约束。早晨报告会说明变更内容及原因。

**一个聊天框，三种速度。**每条消息都会经过三级路由器，选择最快的路径来获取合适的回答（第 2 集）：

只有在 Agent 屏幕处于活动状态时，模型才会获得桌面和视觉工具。

使用真实桌面和浏览器的 Agent

Guaardvark 的 Agent 控制的是一个真实的 Ubuntu 桌面（显示器 :99 上运行着 Xvfb 和 XFCE）：你通过 VNC 连接到这台机器时，会看到同样的「应用程序」菜单、桌面图标和任务栏。它们通过视觉模型查看屏幕、移动鼠标、点击、输入、浏览，并检查自己的操作结果。该桌面与你的桌面相互隔离：它有自己的 XDG_DESKTOP_DIR 和 XDG_CONFIG_HOME，因此 Agent 的文件和设置不会与你的会话冲突。

• 一个视觉大脑。 Gemma4 在一次推理调用中查看屏幕、决定下一步操作并返回点击坐标。
• 闭环定位。 伺服系统移动鼠标，检查光标实际落点，并持续校正，直到光标位于目标上；如果模型实际上看不到目标，则会拒绝定位。
• 实时推理。 每一步（操作、目标、推理，以及循环卡住时的调整）都会实时流式显示在聊天中，并保留在历史记录里，方便审查任何一次运行。
• 确定性配方。 常见浏览器操作（导航、标签页、前进和后退、查找、缩放、书签、YouTube 搜索）会通过配方库即时执行，而不经过视觉循环；每个配方加载前都会经过安全边界检查。
• 完成就要有凭据。 只有能在屏幕上展示证据时，Agent 才会宣称任务已完成。
• 查看执行过程。 可在任意页面查看 Agent 桌面的画面，查看器支持拖动和调整大小，还可弹出为独立窗口。

并行编码 Agent（Swarm）

同时启动多个编码 Agent，让每个 Agent 在独立分支上的隔离 Git worktree 中工作。结果合并时会按依赖顺序检测冲突，并支持可选的测试验证和实时仪表板。

• 后端： Claude Code，或在 Ollama 模型上完全本地运行的 Cline/OpenClaw。
• 飞行模式让 Swarm 保持离线：任务仅通过本地后端运行。
• Git worktree 隔离： 每项任务都有自己的分支和工作目录，但共享同一个 .git 目录。
• 依赖感知合并： 通过拓扑排序优先合并基础性更改；正式合并前会进行冲突试运行检查，集成前会运行测试。
• 模板涵盖 REST API 脚手架、重构与提取、扩展测试覆盖率等场景。
• 实时仪表板： 显示状态、每项任务的日志、成本、已用时间和磁盘占用量。默认同时运行 5 个 Agent；仪表板最多支持 20 个。

Film Crew 使用同一编排器运行（参见 导演）。

MCP 服务、Agent 技能和 Claude Code 插件

Guaardvark 双向支持 Model Context Protocol：它会向任何 MCP 客户端提供工具，也可以调用其他 MCP 服务上的工具。第 21 期展示了 5 个编码 Agent（本地模型上的 opencode、Codex、Cursor、Grok 和 Antigravity）如何通过它生成图片、视频片段、歌曲和语音。

• 一条命令即可设置。 python -m backend.mcp install 会查找你机器上的 Agent 客户端（Claude Code、Codex、Cursor、Grok、Antigravity、opencode、Claude Desktop、Zed、Gemini CLI），并将 guaardvark 服务条目写入其配置，同时备份现有文件并保留其他条目。python -m backend.mcp doctor 会通过服务自检、实际的 stdio 握手以及过期客户端配置扫描，诊断损坏的设置。
• Claude Code 插件。 运行 /plugin marketplace add guaardvark/guaardvark，然后运行 /plugin install guaardvark@guaardvark。插件会询问你的 Guaardvark 检出目录路径，从该目录启动 MCP 服务，并将每项技能加载为 /guaardvark:<skill>。
• Agent 技能。 .agents/skills/ 按每种工作流提供一项技能（图像、视频、音乐视频、Film Crew、语音、音乐、升采样、Cast 和 LoRA 训练、Hugging Face 模型接入、swarm、知识、代码、推广、运维、设置），采用 Agent Skills 格式，让 Claude Code、Cursor、Codex 和 OpenClaw 知道每项任务应调用哪个工具。python -m backend.mcp install --skills 会将这些技能链接到 ~/.claude/skills。
• 作为服务运行： python -m backend.mcp（stdio），或 python -m backend.mcp http（在 127.0.0.1:8788/mcp 上运行可流式传输的 HTTP，默认仅限环回接口）。python -m backend.mcp list-tools 会输出实时工具列表。生成工具默认会将任务加入队列，并返回供 get_generation_status 使用的批次 ID；每次调用都会受到强制超时限制。
• 默认拒绝策略（backend/mcp/config.py）：桌面控制、Agent 控制、系统和 shell、浏览器自动化、测试执行以及 MCP 元工具默认不可见，除非你将它们加入允许列表；需要审批的工具也不可见。默认会提供 50 多种工具（RAG、文件、生成、记忆、代码搜索、Web），以及只读的 guaardvark://outputs/ 资源。
• 作为客户端： 提供 mcp_connect 和 mcp_execute，并维护实时清单，让聊天模型可以按名称查找并使用其他 MCP 服务上的工具。内置审计日志、超时和熔断器。

更多信息请参阅 docs/mcp.md。

本地视频、图像、音乐和语音生成

所有生成任务都在你的 GPU 上运行。无需云 API，也没有按分钟计费。

视频生成

MiniMax H3 还提供未剪枝的 Int8 和 BF16 版本，适用于 24 GB 和 48 GB 显卡，因此视频模型总数为 13 个。

• **分辨率：**512、576、720、1280 和 1920 px（1080p），按模型适配。
• **质量档位：**快速（10 步）、标准（30 步）、高（40 步）、最高（50 步）。每个模型都会声明其能良好渲染的最低步数；若预设低于该下限，则会自动提高至该值（Wan 和 MiniMax H3 为 20 步）。MiniMax H3 还通过蒸馏 LoRA 提供 8 步和 4 步的加速配置。
• 使用 RIFE 帧插值（1 倍原始、2 倍帧率、2 倍帧率并放大）、提示词增强风格（电影感、写实、艺术、动漫或原始），为 Wan 和 CogVideoX 提供低显存模式，并支持对提示词列表进行批量排队。
• **ComfyUI 集成：**一键进入节点编辑器，创建自定义工作流。Wan 和 LTX 通过 ComfyUI 运行。LTX-2.5 需要 ComfyUI ≥ 0.32.0，并需在 Lightricks/LTX-2.5 接受一次许可协议（在 .env 中设置 HF_TOKEN）；下载完成后，生成过程始终在本地进行。
• MiniMax H3 可在一次处理中同时生成画面和声音。Guaardvark 会将提示词编译为模型所需的结构化格式（带剪切时间的编号镜头、说话人 ID、带标签的对话），Film Crew 则将每个场景渲染为其中一个口播片段。该模型采用 MiniMax H3 Community License 许可协议，其中列出的需填写 MiniMax 申请表的地区包括欧盟、英国、韩国和美国；Video Models 对话框会显示许可协议和链接，包含 H3 片段的帖子会添加“Generated with MiniMax H3”一行。
• 视频生成需要 16 GB 级别的显卡，Wan 2.2 5B 除外，该模型最低可在 11 GB 显卡上使用；详见 docs/HARDWARE.md。

LoRA 训练与角色一致性

在自己的 GPU 上训练 LoRA，让 Guaardvark 创作的所有内容中，同一角色、地点或物体始终保持一致。

• 用几张照片训练角色、环境和道具 LoRA。 在 Cast Library 中添加参考照片，审核生成的样片，然后开始训练。LoRA Trainer 默认使用 Z-Image Turbo 作为基础模型（旧版配置使用 SDXL），并以 bf16 训练。使用 5 张 512 px 照片训练 400 步（rank 16）的角色 LoRA，大小约为 33 MB。
• 角色保持一致。 在 Images、Video Generator 或 Music Video 页面选择 Cast 成员，或让 Film Crew 的 Casting 角色自动分配。静帧和关键帧使用该角色的 LoRA 渲染，视频模型再为这些关键帧制作动画，因此每个镜头都从由同一角色 LoRA 生成的画面开始。
• 导入在其他工具中训练的 LoRA。 将 Ostris AI-Toolkit、kohya 或 diffusers/PEFT 训练的 .safetensors LoRA 关联到 Cast 成员；支持 Z-Image Turbo 和 FLUX.1 Dev 的布局，并会在保存前检查关键布局。
• 视频 LoRA。 根据训练所用模型，通过 Hugging Face URL 添加视频 LoRA，并在 Video Generator 中选择；它会载入 ComfyUI 中的 Wan 2.2、LTX、HunyuanVideo 或 MiniMax H3 工作流。目录中提供加速 LoRA：适用于 MiniMax H3 的 8 步和 4 步 turbo 配置，以及适用于 Wan 2.2 14B 的实验性 4 步 Lightning 配置。
• 图像 LoRA 的添加方式相同：从 Hugging Face 添加，并且只会用于兼容的模型。

图像与放大

• 图像生成支持 Z-Image、FLUX.1、Krea 2、SDXL 和 Stable Diffusion 1.5 微调模型，可根据提示词列表或 CSV 批量生成，并提供人体结构控制。
• 照片编辑支持通过指令进行编辑（Qwen-Image-Edit、FLUX.1 Kontext）、局部重绘、扩图和背景移除，可从 Images 页面或直接在聊天中使用。
• 添加任意 Hugging Face 模型（检查点或 LoRA），只需提供其 URL。
• 在 GPU 上将图像放大至 4K 和 8K，支持九种模型，从追求最高质量修复的 HAT-L 到针对动漫优化的 Real-ESRGAN 变体；提供双遍模式、FP16/BF16 和可选的 torch.compile、逐帧视频放大，以及可选的监视文件夹。模型列表见 CAPABILITIES.md。

音乐、声音与语音

Audio Foundry 插件运行三个音频后端，并通过共享的 GPU 调度机制避免它们相互争抢，也不会与 Ollama 争用 VRAM。

• 音乐： ACE-Step v1 (3.5B) 可创作包含人声的完整歌曲或纯音乐。可选择流派、情绪和乐器标签；还可选用 LLM“润色”环节，将普通英语转为 ACE-Step 的标签词汇，并生成配套的负面提示词。ACE-Step 1.5 可选安装。
• FX Lab： Stable Audio Open 用于生成音效和短篇环境音。
• 神经语音： Chatterbox 作为主要的文本转语音引擎，Kokoro 作为快速备用方案，Piper 用于旁白。可用于聊天旁白、视频配音和语音聊天。
• 语音克隆： 默认关闭，创建或使用克隆语音前必须先明确同意。参考音频由你掌控，不会从无意录下的音频中克隆语音。
• 语音聊天： 本地 Whisper 语音转文本，整个应用共用一个麦克风，支持免提对话，并且每条聊天回复都有朗读按钮。
• 生成的音频可在应用内播放器中打开。

导演：电影剧组、音乐视频与剪辑

电影剧组通过五个角色，将一句话创意变成完整视频，并在选角和分镜环节设置人工检查点（第 9 集）：

跟着节拍剪辑的音乐视频（第 8 集）。提供一首歌曲、一段风格提示词和一个简短故事。Guaardvark 会分析速度和节拍，为每个剪切点撰写独特的提示词，为每个剪切点渲染一张分镜静帧（可选使用角色 LoRA 保持角色形象一致），并在消耗任何 GPU 资源生成视频前暂停，等待你批准。随后，它会使用图生视频模型为每张静帧制作动画，并将片段剪辑在一起，使其与节拍吻合，同时通过 RIFE 帧插值实现流畅运动。剪辑使用 Shotcut 中的 melt（设置方法见 plugins/video_editor/README.md）。

视频编辑器。 将片段拖入素材箱，选择歌曲，然后按下 Plan：艺术指导会编排剪辑，你可以通过导演备注进行调整，Render 会生成 MLT 项目和 MP4，并支持撤销和键盘快捷键。另有一个独立的文字叠加工具，可使用 ffmpeg drawtext 在九个位置放置字幕。

自我改进、系统地图与代码智能

• 自我改进。 Guaardvark 会运行自己的测试，派遣编码 Agent 阅读失败信息和源代码、拟定修复方案并验证，然后将其作为待处理修复提交给你审阅；除非你主动开启，否则不会自行应用修复。提供三种模式：定时（每六小时一次）、响应式（服务器反复报错后）和指派式（执行你交给它的任务）。代码库锁会阻止所有更改；它学到的内容还可以通过 Interconnector 与你的其他机器共享（第 11 集）。
• 系统地图。 根据代码库的实际导入关系计算生成实时的力导向星图，包含生命周期标签（活跃、休眠、自动加载、测试、脚本、配置）和排名后的发现结果，你可以将其交给自我改进 Agent；发现的问题若有机械化修复方案，会以精确提案的形式提交审阅（第 14 集）。
• 代码智能。 Monaco 代码编辑器配有标签页和助手面板，还提供代码仓库地图、依赖关系图和支持 AST 的搜索（get_repository_map、read_ast_node、search_code，也可通过 MCP 使用）。所有 AI 代码写入都会经过代码库锁保护下的单一验证式精确替换关卡。

隐私与安全

• 默认在本地运行。 除非你选择发送，否则你的数据、模型、LoRA 和生成的媒体文件都会保留在你的机器上。所有对外发送路径都在 scripts/inbound_guard/egress.json 中声明，并且默认关闭，只有在你更改设置或手动启用后才会开启：安装模型或首次使用尚未下载到磁盘的模型时会下载模型；网页访问则是设置中的开关，默认关闭。
• 支持离线运行。 下载模型后，聊天、RAG、Agent 和内容生成都可以在没有互联网的情况下运行，Swarm 还设有专用的飞行模式。
• 审批。 发布内容、外联草稿和暂存的代码更改都会等待你在“审批”页面审核，每项内容都在各自的标签页中。
• MCP 默认拒绝。 除非你将桌面、Agent 控制、shell、浏览器和测试工具加入允许列表，否则 MCP 客户端无法使用这些工具。
• 入站防护。 scripts/check_inbound.py 会在代码进入项目之前读取代码，包括拉取请求中和产品内部的代码；在强制模式下，它会暂存有风险的更改，等待人工审阅。
• Uncle Claude 是一个可选的第二意见提供者和代码审查者，会调用 Anthropic 的 API。如果环境中没有 ANTHROPIC_API_KEY，它不会发送任何内容。设置密钥后，只有在你启动它时才会运行，除非你更改以下两项设置之一：
  • 启动时： 在聊天中输入 /claude … 会发送该消息和最近 10 条消息；“测试连接”会发送一条固定的测试消息；你请求的建议会发送你的 GPU 内存数据；Agent 按你的请求进行代码更改时，会将文件摘录（最多 3,000 个字符）和差异发送以供审查。
  • 升级：始终（“设置”中默认关闭）：每条聊天消息和最近 10 轮对话都会发送给 Anthropic，Claude 的回答会替代本地回答。
  • 定时发送（“设置” → “Uncle Claude”中默认关闭）：每天两次发送建议（时间、节点 ID、GPU 名称和内存），并审查自我改进循环自主进行的更改（源代码摘录和差异）。
  • 审查永远不会应用任何更改；暂存的修复仍需等待你处理。用量会计入每月令牌预算。

如需报告漏洞，请参阅 SECURITY.md。

更多内置功能

• 受监管的主动联络。 为 Reddit、YouTube、Discord 和 Facebook 上的讨论串起草回复，内容以你自己索引的文档为依据，并在进入队列前评估相关性；未经你批准，绝不发布。你可以在观看 Agent Screen 时，让 Reddit、YouTube 和 Facebook 帖子逐条发布。提供紧急停止开关、各平台的频率限制和 JSONL 审计记录。
• 文件和项目。 桌面风格的文件管理器（文件夹以窗口形式显示，支持拖放和右键菜单），将客户、项目、网站和笔记相互关联并递归索引。文件会流式传输到浏览器自带的播放器和查看器，因此视频无需编解码器包即可播放，PDF 也会在下载完成前开始渲染。
• 规则、提示词、经验和记忆。 可移植的规则包、从良好运行中学习并教会 Agent 的经验，以及可在不同聊天间延续的“记住……”笔记。
• Discord 机器人插件，支持聊天、/imagine 图像生成，以及搜索你自己的安装内容。
• WordPress（可选启用）：从你的网站拉取页面和文章、批量生成内容，并推送回网站。
• 多机互联器。 主节点和客户端节点，支持审批关卡、代码和数据同步，以及共享学习成果。
• 运维。 任务和调度（Celery beat）、感知架构的备份与恢复、GPU 和 CPU 实时监控，以及 11 个自有插件，提供健康检查和 GPU 内存协调器。

Guaardvark 的对比优势

本地 AI 生态在各个领域都有出色的工具：聊天界面、RAG 工作区、节点图媒体管线、编码 Agent、助手网关。Guaardvark 选择了不同的方向：只需在一台 GPU 上安装一次，就能获得完整的工作室，并由一个 GPU 协调器统一调度所有功能。

各列描述的是每个类别的典型情况，并不代表任何单个项目；有些项目在某些方面超越了所属类别。

如果你只需要其中一项，请使用出色的专业工具：Open WebUI 这样的聊天界面、ComfyUI 这样的节点图（Guaardvark 只需单击一下即可将任务交给它），或 AnythingLLM 这样的 RAG 工作区。Guaardvark 适合想在一台机器上拥有完整工作室的用户。

“—”表示该项目自己的文档未列出此项。所有单元格内容均可在所链接的代码库或网站上核实；欢迎通过 issue 提交更正。

真实系统执行真实任务的短屏幕录制，由系统自身的本地语音引擎配音。观看完整播放列表。

节拍同步音乐视频（观看短片）：输入一个风格提示词和一段简短叙事，即可开始。Guaardvark 为每个镜头编写提示词、生成分镜、渲染片段，并按照它检测到的歌曲节拍进行剪辑。（故障效果是在 Shotcut 中后期添加的，歌曲则由 Suno 制作。）

更多截图请访问 guaardvark.com。

需求

你的机器属于哪个档位？ docs/HARDWARE.md 介绍了哪些功能可仅用 CPU 运行、哪些适用于 8–12 GB、16 GB 设计目标，以及拥有 24 GB+ 余量的情况。

* Wan 2.2 5B 声明的显存下限为 11 GB：11 GB 显存的显卡可以手动选择它，达到 12 GB 后自动选择也会选中它。目前尚未确认在 12 GB 显存上能否完整渲染。其他所有视频系列都需要 16 GB 级别的显卡；请参阅 docs/HARDWARE.md。

平台。 主要目标平台是配备一张 NVIDIA 显卡的 Linux。支持 Apple Silicon，GPU 功能通过 Metal 提供（当前可用功能见 INSTALL.md）。Windows 下的 WSL2 支持仍在验证中。

运行 Guaardvark

手动安装

git clone https://github.com/guaardvark/guaardvark.git
cd guaardvark
./start.sh

单行安装程序也会执行相同操作，并克隆到 ~/guaardvark（可通过 GUAARDVARK_HOME=/path 覆盖）；再次运行会更新现有安装。首次运行会处理所有事项：Python 3.12、虚拟环境、Node 依赖项、PostgreSQL、Redis、Ollama、Whisper.cpp、数据库迁移、前端构建以及所有服务。设置 PostgreSQL 时会要求你输入一次系统密码（在全新 Linux 安装中，还会询问是否安装 apt 软件包）。

./start.sh                    # Full startup with health checks
./start.sh --fast             # Reuse venv + node_modules as they are: no installs, no frontend build, no preflight
./start.sh --test             # Health diagnostics
./start.sh --plugins          # Start all enabled plugins
./start.sh --external-ollama  # You run Ollama yourself; never started or stopped by these scripts
./stop.sh                     # Stop Guaardvark (and only the Ollama that start.sh launched)
./stop.sh --keep-ollama       # Stop Guaardvark, leave Ollama running whoever started it
./stop.sh --all               # Also stop your own `ollama serve` and the systemd service

如果在运行 ./start.sh 前 Ollama 已经在运行，程序会沿用该实例，而不会重启；运行 ./stop.sh 时也不会将其关闭。要永久启用任一策略，请在 Settings → Product Profile → Ollama 中切换选项，或在 .env 中设置 GUAARDVARK_OLLAMA_KEEP_RUNNING=1 / GUAARDVARK_OLLAMA_EXTERNAL=1。

选择配置

首次启动时，系统会询问 Guaardvark 在此处的用途。Creator 会显示媒体工作流（图像、视频、音频、Film Crew、LoRA、放大），并将 Agent、知识索引、外联和自动化功能安装好但暂不显示；Workstation 则包含所有功能。两者都是起点，而非上限：可在 Settings → Product Profile 中切换，或运行 ./start.sh --profile creator。详情见 backend/profiles/README.md；构建自己的发行版，请参阅 docs/EXTENSIONS.md。

熟悉界面

界面中的许多操作只需右键单击、拖动或按键即可完成：仪表板卡片和大多数列表上的菜单、可移动和调整大小的卡片、直接拖入 Files 的文件或拖入聊天的图像、能识别当前页面的浮动聊天、免手操作语音，以及用于查看键盘快捷键的 ?。docs/interface.md 详细介绍了所有这些功能。

提升速度

聊天和 Agent 的延迟取决于几项设置，除非另有说明，都在 Settings 中。默认值侧重于让你了解系统运行情况；熟悉之后，可以调整这些设置：

• 关闭思考模式。 扩展推理（/thinking，或 Settings 中的默认聊天思考设置）会在每轮对话中增加一段耗时较长的推理过程。关闭后，简单问题通常一两秒就能得到回答。
• 关闭开发者开关。 RAG Debug、Verbose Logging 和 LLM Debug 都会增加每次请求的处理开销。
• 选一个可靠的模型并保持使用。 每次切换模型都会将权重从 GPU 上卸载并重新加载。一个常驻显存的中等大小模型，胜过一个频繁加载、卸载的大模型。
• 留意占用 VRAM 的其他服务。 渲染需要等待显卡空闲，但占用 VRAM 的空闲服务（语音模型、图像处理流水线）会拖慢所有任务的接入。Plugins 页面会显示各服务占用的资源。

CLI

pip install guaardvark

该软件包提供 guaardvark 命令，使用 Typer、Rich 和 prompt_toolkit 构建（第 20 集对此进行了介绍）。它会连接到配置端口上运行的后端；如果找到代码检出目录，则会通过其中的 start.sh 启动后端。它会在 GUAARDVARK_ROOT 指定的位置或当前目录中查找代码检出目录；如果找不到，则会显示 "Guaardvark installation not found" 并退出。MCP 客户端可以通过 pip 安装和代码检出目录中的 guaardvark mcp serve 启动服务。

guaardvark                              # Interactive REPL
guaardvark status                       # System dashboard
guaardvark chat "explain this codebase" # Chat with RAG context
guaardvark search "query"               # Semantic search
guaardvark files upload report.pdf      # Upload and index
guaardvark plugins list                 # ComfyUI / Ollama / …
guaardvark gpu status                   # VRAM and owner lock
guaardvark mcp install --client cursor  # Wire Guaardvark into Cursor
guaardvark completion zsh               # Shell completion script

/imagine <prompt>       Generate an image (inline preview in Kitty/iTerm)
/video <prompt>         Generate a video from text
/voice <text>           Text-to-speech (plays locally)
/agent [on|off|shot]    Screen-agent mode; shot = desktop screenshot
/web [images|chat]      Open the web UI on the real frontend port
/ingest <path>          Index files or directories for RAG
/plugins list|start     GPU / service plugins
/gpu status|release     VRAM and owner lock
/audio tts|music|sfx    Audio Foundry
/swarm run <prompt>     Parallel agents in worktrees
/lessons begin|end      Lesson pearls
/skills                 List SKILL.md files
/help [query]           Full command reference, or one command

架构

Browser / CLI (PyPI: guaardvark) / MCP Client (Claude Desktop, Cursor, etc.)
    | HTTP + WebSocket / stdio MCP
    v
Flask (about 96 API modules, auto-discovered) + Socket.IO
    |
    +-- AgentBrain (3-tier routing: Reflex → Instinct → Deliberation)
    |
Service Layer (many modules; plugin sidecars for heavy GPU work)
|-- Agent Executor (ReACT + 100+ registered tools + BrainState)
|-- Screen Control (See-Think-Act-Verify + live reasoning stream)
|-- RAG + Autoresearch + Entity extraction
|-- Self-Improvement (detect/fix/verify/broadcast + guardian)
|-- Generation (image/video/audio/voice/content)
|-- Swarm + Film Crew (isolated worktrees + 5-role pipeline)
|-- Servo + Vision Pipeline
|-- System Mapper / Repo intelligence (AST dependency graphs)
|-- GPU Memory Orchestrator + Plugin runner (CUDA sidecar safety)
\-- Interconnector (multi-machine sync + cluster)
    |
+---+---+---+---+---+
v   v   v   v   v   v
PostgreSQL  Redis  Ollama  Agent Display (:99, on-demand)  ComfyUI / Audio Foundry (plugins)
            Celery

路线图

近期

• 为视频编辑器添加可手动编辑的时间线：拖动以调整顺序，为每个剪辑添加转场，并在计划中添加文字叠加。
• 让每条流水线都能启动自己的服务（音乐视频、Film Crew、图像、音频），如同视频渲染已经会启动 ComfyUI 一样。
• 根据模型调整记忆和上下文预算，并通过嵌入实现语义记忆召回。
• 实现 X 平台发布，并完成端到端验证。
• 将 Audio Studio 中的歌曲直接发送到 Music Video 页面。

长期

• 为多机器部署提供集群仪表板：集群、路由和节点实时状态。
• 为 JavaScript 和 TypeScript 提供 AST 级代码工具。
• 在获得同意并添加水印的前提下克隆歌声。

不在路线图中： 默认上云或以 SaaS 托管作为主要使用方式。产品以本地优先为原则。

常见问题

Guaardvark 会把我的数据发送到别处吗？ 不会，除非你开启了某项功能。模型在本地运行，所有外发路径（模型下载、网页搜索、发布内容、Discord 机器人、远程 Ollama）都在 egress.json 中声明，并且在某项设置或人员启动之前始终处于关闭状态。

它能离线运行吗？ 可以，只要你所用的模型已下载。只有按设计需要连接其他服务的功能（例如网页搜索、发布内容和 Discord 机器人）才需要网络连接。

我需要什么硬件？ 需要配备一块 NVIDIA GPU 的 Linux 系统。聊天、RAG、语音和编码蜂群可仅使用 CPU 运行；8–12 GB 显存可运行向量 RAG、屏幕 Agent、图像、升频和音乐功能；视频生成需要 16 GB 级别的显卡。详情请见 docs/HARDWARE.md。

它能在 macOS 或 Windows 上运行吗？ 支持 Apple Silicon，GPU 功能将通过 Metal 提供；请参见 INSTALL.md。通过 WSL2 运行的 Windows 支持仍在验证中。

我能通过 Claude Code、Cursor 或 Codex 使用它吗？ 可以。按照快速开始中的两行命令安装 Claude Code 插件，或者运行 python -m backend.mcp install，将 MCP 服务接入它找到的所有 Agent 客户端。请参见 MCP 服务、Agent 技能和 Claude Code 插件。

它与 ComfyUI 或 Open WebUI 有何不同？ 它们各自在某一领域都很出色。Guaardvark 通过一次安装，将聊天、RAG、Agent、编码蜂群和整套媒体流水线整合在一起，共享一块 GPU；如果你想使用节点图，还可以一键切换到 ComfyUI。请参见 Guaardvark 的对比。

它免费吗？ 是的。Guaardvark 基于 MIT License 开源，运行它除了你自己的硬件和电费之外不产生任何费用。

参与其中

Guaardvark 基于 MIT License 开源，并在公开环境中开发。无论你想试用机器人、提交一个小型 PR，还是报告它在你的机器上出了什么问题，以下都是最便捷的参与方式。

1. 加入社区

2. 运行它

使用单行命令快速开始，或手动安装：Web UI → http://localhost:5173 · API → http://localhost:5000（macOS：5055）。
详情：INSTALL.md · Agent 心智模型 · 完整功能列表：CAPABILITIES.md

3. 选择一个合适的入门任务

入门任务带有 good first issue 标签，每个任务都包含验收标准和清晰的不在范围内列表。如果当前没有开放的入门任务，以下安全区域是最好的起点。

我们力争在 24–48 小时内审核认真提交的 PR。

4. 安全与高风险贡献区域

Agent 配方、规则和经验包、技能及 Agent 指令文件均由维护者编写；如需新增行为，请提交 issue 进行说明。完整的设置、风格和 PR 要求，请参阅 CONTRIBUTING.md。

使用 Guaardvark 的编码 Agent 请从 AGENTS.md 及其操作规范 AGENT_GUIDE.md 开始。贡献者（无论是人还是 Agent）都应遵循 CONTRIBUTING.md；在产品内部，每次 AI 代码写入都必须经过一个经过验证的关卡：guarded_code_service.py::apply_exact_replacement。

5. 其他帮助方式（无需编写代码）

• 为仓库点星，并分享简短演示（屏幕 Agent、Film Crew 或 Discord /imagine）
• 报告安装过程中的问题，并附上 GPU 型号和 logs/ 中的日志（提交 issue，或发送邮件至 [email protected]）
• 提出你希望开箱即用的工作流

支持项目

如果 Guaardvark 对你有用，可以支持其开发：

• Ko-fi（零手续费！）
• GitHub Sponsors
• PayPal

如果你觉得这个仓库有趣，请为它点星；这有助于其他人发现它。

如有问题、安装困难或反馈，请联系：[email protected]。媒体、合作及商务事宜，请联系：[email protected]。

许可证

MIT License — Copyright (c) 2025-2026 Albenze, Inc.

“Guaardvark”™ 和 Guaardvark 徽标是 Albenze, Inc. 的商标。MIT License 仅涵盖代码，不涵盖名称；有关无需征求许可即可如何使用该名称，请参阅 TRADEMARK.md。