内容
# Jarvis
[](CHANGELOG.md)
[](https://github.com/W17ANT/Jarvis/actions/workflows/ci.yml)
[](LICENSE)
[](https://en.wikipedia.org/wiki/Apple_silicon)
[](docs/privacy.md)
[](https://github.com/W17ANT/Jarvis/actions/workflows/ci.yml)
**一个具有仪表盘HUD的语音优先AI助手。**
*本地LLM。实时CPU/GPU温度。Kiosk模式。白标。*
>钢铁侠的界面，你的Mac的大脑。MIT。
```
╦ ╔═╗ ╦═╗ ╦ ╦ ╦ ╔═╗
║ ╠═╣ ╠╦╝ ╚╗╔╝ ║ ╚═╗
╩ ╩ ╩ ╩╚═ ╚╝ ╩ ╚═╝
```
[**快速开始 →**](https://aoneill.co.uk/arc/quickstart/) · [**白标安装 →**](docs/install-for-clients.md) · [**隐私 →**](docs/privacy.md) · [**60+ 工具 →**](docs/tool-reference.md) · [**插件编写 →**](docs/plugin-authoring.md) · [**愿景与路线图 →**](docs/vision-and-roadmap.md)
**由 [Antony O'Neill](https://www.linkedin.com/in/antonyoneilladl/) · [aoneill.co.uk](https://aoneill.co.uk) · MIT许可**
---
## 它是什么
一个完整的本地语音优先AI工作站，适用于Apple Silicon。唤醒它并使用自定义短语。它监听、思考、回应并运行工具 - 默认情况下无需云端往返。HUD类似于27"+显示器上的弧形反应堆仪表盘：通过[macmon](https://github.com/vladkens/macmon)获取实时CPU/GPU温度、实时麦克风波形中心、成对核心遥测表盘以及一个弹出每个工具的代理运行的转录抽屉。
白标设计 - 每个品牌字符串、颜色和唤醒短语都位于`config/brand.json`中。热加载插件放入`bridge/plugins/<name>/`中。60多个语音可调用的工具分为通信/生产力/创意/系统/内存。
Whisper STT → Ollama LLM → Kokoro TTS管道。默认配置：没有任何内容离开你的Mac。
---
## 它与众不同之处
有几个“适用于Mac的语音优先AI”项目。它们大多是云优先的包装器 - 你的声音 → Anthropic → 云TTS → 返回给你。它们速度快，演示友好，因为租用的智能很快。它们也不适合任何人/合同/法律不能将数据发送到Anthropic。
这个项目正好相反：
| | 云优先AI助手 | 这个Kiosk |
|---|---|---|
| 大脑 | 云LLM（Anthropic / OpenAI） | 本地Ollama（默认qwen2.5:7b） |
| STT | 云（Web Speech API） | 本地MLX Whisper |
| TTS | 云（Fish Audio / ElevenLabs） | 本地Kokoro |
| API密钥要求 | 是（~$10-50/月/操作员） | 无 |
| 工作空间范围（每上下文角色，作用域内存+审计） | 无 | 是 - 提供Workspaces v0-v4 |
| 白标 | 硬编码品牌 | `config/brand.json`重新品牌整个HUD |
| 插件脚手架 | 分叉代码库 | 语音命令→`build_plugin`→500毫秒内工作插件 |
| MCP服务器 | 无 | 是 - 每个工具通过`POST /mcp`暴露给Claude Desktop / Cursor |
| Apple Silicon遥测 | 装饰 | 通过macmon获取实时CPU/GPU温度 |
| 首次启动成本 | $0 + ~30分钟安装 | $0 + ~30分钟安装 |
| 每月成本 | $10-50（API） | $0 |
如果你想要尽可能快的语音循环，并且不关心谁看到你的数据，那么云优先项目非常优秀。如果你是律师/会计师/顾问/记者/临床医生/监管业务负责人，不能将客户数据发送到Anthropic，那么这个项目适合你。
---
## ✨ 它能做什么
| | |
|---|---|
| **语音循环** | 通过“嘿Jarvis”唤醒。句子级流式TTS - 你耳边第一音频约1秒。麦克风RMS打断取消句子中途。填充短语（“马上。”）覆盖LLM思考时间。 |
| **视觉** | Qwen 2.5-VL字幕图像，描述屏幕，OCR文档。 *"这个白板上写了什么？"* |
| **Apple Mail / 日历** | 总结未读邮件，草拟邮件（从不自动发送），添加日历事件。提醒在每个事件前15分钟和5分钟触发。 |
| **代码代理** | `code_agent_run`启动一个沙盒Claude / Qwen工作器 - 编辑文件，运行测试，提交。后台任务在HUD中显示为队列，您可以语音取消。 |
| **持久内存** | SQLite + 嵌入（nomic-embed-text）。联系人，项目，事实，会话摘要。跨会话回忆。夜间梦循环重复数据删除近似重复条目。 |
| **知识库** | 将markdown / PDF / docx放入`docs/knowledge/`。混合检索（向量+ BM25 RRF）并在每个回复中引用来源。问任何可能在文档中的问题并获取收据。 |
| **文档生成** | PDF（模板），DOCX，XLSX，PPTX。管道数据→精致交付成果。 |
| **YouTube创意** | 缩略图（1280×720），短视频（9:16），宣传包 - 视觉选择英雄帧+引擎内衬自动。 |
| **社交字幕** | 多平台字幕草稿（Instagram / LinkedIn / TikTok）带有标签研究和品牌基调验证。 |
| **MCP服务器** | 每个桥接工具通过`POST /mcp`的JSON-RPC公开。驱动同一个Kiosk从Claude Desktop，Cursor，Continue。 |
| **代理采购** | 通过macOS Keychain预付虚拟借记卡。类别分级上限。英国零售商白名单。自动/语音/输入确认层。追加审计日志。模拟模式默认。 |
| **可插拔LLM提供商** | Anthropic / OpenAI / 本地Ollama都在一个`chat()`调用后面。工作负载路由 - 默认聊天到Ollama，视觉到Claude，高风险到Claude。代理控制台中的实时令牌+成本遥测，以便永远不会惊讶的花费。 |
| **嵌入式工具路由器** | 在60种工具中，全目录对于7b选择器来说过于庞大。nomic-embed-text在启动时索引每个工具；查询分类目录过滤到前20+10始终开启。代理控制台中的实时透明度显示模型实际看到的工具。 |
| **Web使用循环** | `request_browse`驱动一个真正的Chromium与Playwright +视觉LLM - 点击，输入，滚动，读取。URL拒绝列表（银行，政府，经纪人），提示注入保护，操作允许列表。为“找到最便宜的X”，“总结此页面”，“为我填写此表单”使用。 |
| **会话历史** | 每个回合持久化到SQLite。右边缘滑出抽屉（`H`键）显示所有会话可搜索，每个行带有工具芯片。 |
| **个人助理工具** | iMessage，Apple提醒，HUD计时器，Apple Music / Spotify，Apple Notes / Bear / Obsidian，Mozilla Readability文章获取，屏幕截图，macOS Focus模式，1Password CLI查找。零API成本日常原始数据通过osascript。 |
| **视频转录** | `transcribe_video`剥离音频与ffmpeg→本地Whisper获取时间戳语音段→采样N个关键帧→视觉LLM字幕每个关键帧。返回交织叙述。 |
| **白标品牌** | 每个品牌字符串，颜色，字体和唤醒短语都位于`config/brand.json`中。设置向导重新皮肤整个HUD，无需代码更改。`.brand-lock` + `update.sh`防止无声重新品牌。 |
### 键盘快捷键
- `?` - 可搜索的命令速查表（每个工具，带有确认/始终开启标志）
- `H` - 会话历史抽屉
- `Shift+Cmd+J` - 代理控制台（LLM密钥+工作负载路由+工具路由器实时选择+LLM使用情况汇总+采购审计日志）
- `Shift+Cmd+D` - 演示/清洁模式（隐藏数字读数，REC指示器，时间戳以访客访问）
- `Shift+Cmd+M` / `+C` / `+T` - 无障碍：减少运动/高对比度/大文本
- `Esc` - 关闭任何打开的模态/抽屉；任务中途=取消活动浏览/字幕批次
---
## 🚀 安装（M系列Mac，~30分钟）
**先决条件：** macOS 14+，Apple Silicon（M1/M2/M3/M4/M5），64 GB+ RAM推荐（32 GB在较小型号上可用），Homebrew。初始Ollama模型拉取需要互联网。
```bash
git clone https://github.com/W17ANT/Jarvis.git
cd Jarvis
./install.sh
```
安装程序拉取Ollama，Qwen 2.5 + Qwen 2.5-VL模型，设置Whisper + Kokoro Python虚拟环境，并通过Homebrew固定ffmpeg / ImageMagick / exiftool。
**您必须手动运行设置向导** - Kiosk需要`config/brand.json`才能干净地启动。如果`install.sh`提供自动启动向导，请接受；否则（例如，在重新安装时，已存在`config/brand.json`），请自己运行：
```bash
node tools/setup-wizard.mjs
```
向导询问：
- 代理名称+唤醒短语+语音（Kokoro的50多种语音之一）
- 机构名称，标语，品牌颜色，徽标
- 硬件层级（自动选择适合您芯片的模型大小-所有M系列Maxes都使用qwen2.5:14b文本+qwen2.5vl:7b视觉，较小的芯片降级到7b/3b。之前的32b/32b组合崩溃了M5 Max GPU，已被淘汰）
- 可选API密钥（Frame.io的审核工作流，SerpAPI的新闻雷达，Hunter.io的推广）
- 拍摄+输出文件夹根目录（指向NAS /外部SSD如果您想要）
完成。 **启动Kiosk** （也是手动步骤-`install.sh`不会为您启动）：
```bash
./launch.sh kiosk # 全屏Kiosk模式
./launch.sh # 窗口测试
./launch.sh restart # 杀死所有服务并启动
./launch.sh stop # 停止所有服务
```
HUD在Chrome的`--app`模式下打开（无浏览器边框）。说“嘿[代理名称]”并开始工作。
---
## 🎨 创意风格指南（您的CLAUDE.md）
`config/creative-style.md`是机构的风格指南 - 编辑语气，您使用的词，避免使用的词，编辑节奏，视觉偏好。桥接器在每条消息上都会读取它，并将其应用于每个生成的草稿（电子邮件，字幕，新闻稿，视频简介）。
```bash
cp config/creative-style.example.md config/creative-style.md
open -e config/creative-style.md # 在TextEdit中编辑
```
示例模板是有偏见的 - 复制，然后修改。更改立即生效；不需要桥接器重启。HUD的设置面板还公开了一个文本区域，用于在屏幕上编辑它。
---
## 🔄 从上游更新
对存储库进行了更改？使用一个命令将它们拉到已部署的Kiosk：
```bash
./tools/update.sh # 完整更新
./tools/update.sh --check # 干燥运行 - 显示将更改的内容
```
备份`memory.db`，保留任何本地编辑，`git pull --ff-only`，`npm install`，重建原生绑定，刷新Python依赖，拉取`package.json`中声明的任何新Ollama模型，然后重启launchd代理（或警告如果它未安装）。
---
## 🆘 出现问题？发送诊断信息
```bash
./tools/diagnose.sh
```
将所有相关日志（`/tmp/jarvis-*.log`），系统快照（Mac型号，RAM，Node版本，healthz输出，端口绑定）和`config/brand.json`打包到您的桌面上的tarball中。在macOS上，它还会打开一个预填充的邮件草稿发送到**Antony@aoneill.co.uk**，并将包附加到邮件中。无秘密 - `.env`被排除。
常见问题（`docs/install-guide.html`第11-13页的完整FAQ）：
- **麦克风死？** 检查系统设置→声音→输入。如果MacBook盖子关闭并且您使用外部显示器，则内置麦克风被禁用 - 使用USB麦克风或通过Continuity Camera配对iPhone。
- **红色桥接点？** `./launch.sh restart` - 杀死所有正在运行的实例并启动它们。自动修复原生绑定不匹配（Homebrew Node升级）。
- **错误报告？** 右键单击HUD→检查→控制台选项卡→`⌘ A`→复制→粘贴到您的电子邮件中，然后附加上面的诊断包。
---
## 🧹 卸载
```bash
./tools/uninstall-wizard.sh # 交互式 - 确认每个步骤
./tools/uninstall-wizard.sh --yes # 自动yes适用于所有内容（除用户数据）
./tools/uninstall-wizard.sh --purge # 擦除所有内容，包括用户数据+Ollama模型
./tools/uninstall-wizard.sh --dry-run # 显示将发生什么，不会更改任何内容
```
---
## 🏗️ 架构
```
┌─────────────────────────────────────────┐
│ HUD（Chrome --app，香草HTML/JS） │
│ 速度计 · 小部件 · 转录 · TUNED │
└──────────────────┬──────────────────────┘
WebSocket
│
┌────────────────────┴────────────────────┐
│ 桥接器（Node 22） │
│ ─────────────────────────────────────── │
│ 60+ 工具调度 · MCP服务器 │
│ 句子级LLM流式传输 · 审计 │
│ 任务 · 撤销 · 内存 · 通知 │
└─┬──────┬──────┬──────┬──────────┘
│ │ │ │
Ollama Whisper Kokoro AppleScript
（Qwen （STT） （TTS） （邮件 · 日历
14b + · Premiere · Lightroom）
3b fast +
7b VL）
```
- **HUD** - 香草HTML/CSS/JS。无框架。17个模块：语音循环、布局网格、计划阶段、命令调色板、审计叠加层、使用情况遥测、会话历史、演示模式、配置文件、通知等。可通过`config/brand.json`进行白标。
- **桥接器** - `ws://localhost:8766`上的Node 22服务器。拥有WebSocket发布/订阅 + 工具注册。 39个模块涵盖Frame.io、Premiere、Lightroom、日历、邮件、视觉编辑、品牌包、水印、联系表、内存、机构、shotflag、自动清理、跟踪日、新闻雷达、媒体日、样式内存、路径、MCP、审计、撤销、梦循环、日常摘要、缓存修剪、容器、模型路由器、预热、通知等。
- **本地AI** - Ollama提供Qwen 2.5（文本）+ Qwen 5.5-VL（视觉）。 Whisper Python服务用于STT。Kokoro Python服务用于TTS。所有四个服务都在`localhost`运行。 Nothing离开盒子进行推理。---
## ⚡ 针对汽车内容机构设计
桥接器了解：
- **组织 `shoots/<date>-<vehicle-slug>/`** - 每个工具接受一个主题短语，因此“press car shoot”解析到正确的目录进行模糊匹配。
- **品牌输出结构** - `output/youtube/{thumbnails,shorts}`，`output/instagram/{reels,posts}`，`output/tiktok`，`output/brand-packs`，`output/pdf`，`output/watermarked`等。分类固定；工具自动进入正确的桶。
- **客户端可见写入的确认门户** - `draft_email`、`frameio_add_comment`、`frameio_set_status`、`add_calendar_event`、`apply_lightroom_preset`、`premiere_render_active_sequence`、`crop_to_portrait`。LLM无法在您确认之前发送单个电子邮件。 LLM无法在您确认之前向Frame.io添加评论。 LLM无法设置Frame.io状态。 无法添加日历事件。 无法应用Lightroom预设。 无法裁剪到肖像。 无法运行shell。 无法写入文件。 等十多个都需要显式操作员确认。 LLM无法发送电子邮件，除非您说“是”。
- **每个操作员的个人资料** - Kiosk支持多个操作员（首席摄影师，编辑，MD）。每个人都有自己的语音，品牌颜色覆盖，硬件层级和审计日志身份。
---
## ⚡ 性能
- **语音结束 → 首次音频**：目标p50 <800毫秒在M系列上（操作员感受到的感知滞后）。Sprint 11添加了一个每回合的仪表盘管道（`v.rec-end → v.audio-play`性能标记，`tools/latency-report.mjs` CLI摘要，可选的`?debug=latency` HUD叠加层），因此任何回归都会立即显现。
- **后续回合**：`keep_alive: 24h`和`OLLAMA_FLASH_ATTENTION=1`设置为24小时后，3b快速模型在聊天式查询上具有~300毫秒的首个令牌延迟，无需质量下降即可处理长表单草稿+工具调度。基于嵌入的工具过滤器缓存每个查询的嵌入，因此重复项跳过~150-400毫秒的`nomic-embed-text`往返时间。
- **具备能力的硬件上的工具路由**：短路由查询击中3b快速模型（~500毫秒）；长表单草稿+工具调度击中14b。比聊天式查询快约5倍，在写入时不会牺牲质量。
- **启动预热**：并行探测Ollama（文本+视觉），Kokoro，Whisper隐藏了2-3秒的冷启动税。 Whisper现在通过服务器启动时的背景无声剪辑进行预热。 `/diary`缓存预热通过一个扇出调用（节省了HUD加载时的~5秒）。
- **健康检查延迟**： `/healthz`服务器端缓存，1秒TTL，因此两个HUD窗口不会对Ollama/Kokoro/Whisper进行双重扇出。 `/diary`缓存具有18秒TTL +飞行中Promise去重（并发调用者共享一个AppleScript运行）。
- **可选Docker渲染环境** - `RENDER_USE_DOCKER=1`将shell命令路由到一个固定的Debian镜像，其中包含ffmpeg + ImageMagick + exiftool。可在操作员Mac上重现。
---
## 🔐 隐私与安全
- **不会有任何信息离开设备进行推断** — Ollama / Whisper / Kokoro 都在本地运行。
- **确认门槛**：每个破坏性或客户端可见的工具都需要操作员明确的 "是" / "继续" / "执行"。
- **沙盒化的 `run_shell`**：安全二进制文件的允许列表（ffmpeg / magick / exiftool / sips / find / awk / sed / grep / python3 / node / osascript / curl / jq 等），危险模式的拒绝列表（`sudo`、`rm -rf`、`eval`、`dd`、`curl | bash`），工作目录固定为项目根目录，30 秒超时，标准输出截断。可选的 Docker 容器化。
- **审计日志**：每次工具调度都会将操作员 ID + 结果 + 时长追加到 `data/audit/YYYY-MM.jsonl`。可以通过 HUD 的 `查看审计日志` 按钮查看。
- **路径穿越防护**：所有文件系统工具都通过 `paths.mjs#isWithinAllowedRoots` 解析（PROJECT_DIR / shoots / output），拒绝任何外部路径。
- **可选 Tailscale 加入**：在安装过程中用于从手机或另一台机器远程访问，而无需公开暴露服务。
- **默认本地运行**：无遥测，无分析，无远程更新服务器。桥梁仅与本地服务和通过 `.env` 选择的外部 API（Frame.io、SerpAPI、Hunter.io）通信。每个 API 都可以独立撤销。
---
## 🔌 MCP — 任意驱动
所有工具都通过 `POST http://localhost:8766/mcp` 上的模型上下文协议公开。要从 Claude Desktop / Cursor / Continue 连接：
```json
{
"mcpServers": {
"jarvis": {
"url": "http://localhost:8766/mcp"
}
}
}
```
这样，所有 60 个工具都可用。需要操作员确认的工具会通过宿主的 UI 返回其 `requires_confirmation` 有效载荷。
---
## 📂 仓库布局
```
Jarvis/
├── index.html ← HUD 入口点
├── styles.css ← 品牌样式
├── voice.js ← 语音循环，麦克风，会话状态
├── bridge-client.js ← WebSocket + 发布订阅
├── tts.js ← Kokoro 客户端 + 句子队列 + 填充池
├── speedo.js layout.js plan.js audit.js usage.js … ← HUD 模块
├── live.html live.js ← 手机作为麦克风伴侣
├── bridge/
│ ├── server.mjs ← 桥梁 HTTP + WS 调度器
│ ├── paths.mjs ← 拍摄 / 输出目录的单一真实来源
│ ├── model-router.mjs ← 快速 vs 主模型选择器
│ ├── warmup.mjs ← 冷启动隐藏
│ ├── mcp.mjs ← 模型上下文协议端点
│ ├── notifications.mjs ← 提醒 + 健康调度器
│ ├── memory.mjs ← SQLite 联系人/项目/事实 + 梦循环
│ ├── vision.mjs ← Qwen-VL 字幕，找到帧，剪辑评分
│ ├── edit.mjs ← 电影预告片管道
│ ├── brandpack.mjs 水印.mjs 联系表.mjs 自动清理.mjs
│ ├── frameio.mjs lightroom.mjs premiere.mjs calendar.mjs mail.mjs
│ ├── shotflag.mjs trackday.mjs press-radar.mjs media-days.mjs
│ ├── style-memory.mjs ← 编辑评分签名提取
│ └── … ← 39 个模块
├── remotion/ ← 品牌营销/安装/卸载/社交视频
├── docker/render/ ← 可选的容器化 ffmpeg/magick 环境
├── tools/
│ ├── setup-wizard.mjs ← 首次运行向导
│ ├── uninstall-wizard.sh ← 卸载
│ ├── install-tailscale.sh
│ ├── install-daemon.sh ← 启动代理，用于服务自动启动
│ └── adhoc/ ← 测试fixtures
├── config/
│ ├── brand.example.json ← 白标签模板
│ ├── actions.meta.json ← 工具标签 + 语音短语
│ ├── launcher.json ← 快速启动面板条目
│ └── press-radar.json ← 跟踪的制造商 + 出口
├── assets/ ← 字体，图标，Kokoro 模型，天气图标，品牌
├── install.sh launch.sh
├── README.md PLAN.md TODO.md CHANGELOG.md DEMO.md SECURITY.md
└── .gitignore
```
---
## 🎬 演示视频
营销和安装视频位于 `remotion/`（一个小型 Remotion 项目 — 对于个人或 ≤3 名员工的公司使用，无许可成本）。渲染任何一个：
```bash
cd remotion
npm install # 仅首次运行
node scripts/generate-narration.mjs # 通过 Kokoro（桥梁必须运行）合成语音
npx remotion render JarvisOverview ~/Downloads/jarvis-overview.mp4 # 完整安装 + 功能游览
npx remotion render JarvisCapabilities ~/Downloads/jarvis-capabilities.mp4 # 深入了解其功能
npx remotion render JarvisUninstall ~/Downloads/jarvis-uninstall.mp4 # 简短的卸载演练
npx remotion render JarvisTikTok ~/Downloads/jarvis-tiktok.mp4 # 9:16 社交媒体剪辑
```
---
## 🛠️ 自定义 / 白标签适用于您的代理
服务亭可通过 `config/brand.json` 和 `.env` 进行品牌配置。随时重新运行 `tools/setup-wizard.mjs` 以更改代理名称、唤醒短语、品牌颜色、语音、硬件层或文件夹。设置向导会重写 `config/brand.json` 并向正在运行的桥梁发送 `POST /brand` 请求以实时加载 — 无需重启即可进行品牌更换。对于非品牌更改（模型更换、语音更换），HUD 中的设置模态具有相同的控件。
---
## 📜 许可证
Jarvis 在 MIT 开源许可下 — fork 它，品牌化它，发布它。代码中不包含客户端商标。原始开发由私人商业部署资助；白标签分发剥离了定制汽车代理工具，以便服务亭直接与托管助手竞争，同时保持完全在设备上。参见 `LICENSE`（如果存在）。
---
## 🤝 致谢
- **Ollama** — 本地 LLM 服务
- **Qwen 2.5 + 2.5-VL**（Alibaba）— 文本 + 视觉模型
- **Whisper**（OpenAI）— 语音转文本
- **Kokoro 82M**（hexgrad / Apache 2.0）— 文本转语音
- **nomic-embed-text** — 语义内存的嵌入
- **better-sqlite3** — 内存层的同步 SQLite
- **Phosphor Icons** — UI 图标集
- **Bybas 天气图标** — 天气面板
- **Remotion** — 用于营销材料的程序化视频合成
- **ffmpeg + ImageMagick + exiftool** — 渲染管道主力
- **Oswald + Rubik + JetBrains Mono**（Google Fonts）— 字体栈
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器