samonti86/jarvis

# Jarvis [](https://github.com/samonti86/jarvis/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/) 一款专为 Windows 打造的常驻型语音助手。只需说“Hey Jarvis,”提出问题，即可获得 语音回复 —— 其背后拥有一个包含 36 个工具的 Agentic 层，能够搜索网页、在 沙盒中运行代码、读取日历、监控家庭实验室，甚至通过摄像头进行视觉感知。 唤醒词检测和语音转文本均在**本地**运行。只有转录后的文本 会离开本机 —— 唯一的例外是可选择开启的[后台 agent](docs/ENV_VARS.md#long-horizon-background-agents-m91)， 该功能默认关闭。 ``` mic ──► openWakeWord ──► faster-whisper ──► Claude ──► edge-tts ──► speakers (local) (local) (agentic (streamed) tool loop) ``` 包含约 29,000 行 Python 代码，分布在 70 个模块中。完整的工程记录 —— 包括设计 权衡、事后复盘，以及那些后来被证明是错误的结论 —— 均记录在 [docs/MILESTONES.md](docs/MILESTONES.md) 中；如果你只想挑选阅读， 其中的 [**从这里开始**](docs/MILESTONES.md#start-here) 章节为你精选了六篇最值得一读的 内容。 ## 值得一读的部分 **是 Agentic 工具循环，而不是聊天机器人。** Claude 被赋予了 36 个工具，并自主决定 调用哪一个，在多次迭代中将它们串联起来。比如询问“我的 Plex 媒体库中播放次数最多的电影是什么？”，它会组合调用四次独立的 MCP 才能得出 结果 —— 系统中完全没有针对该问题的手写代码路径。 **延迟是核心设计约束。** 模型的回复以流式传输，并被分块 切分为句子，*在模型仍在生成时*就合成为语音，因此 第一个单词大约在一秒后就会发出，而无需等待整个响应生成完毕。系统 prompt 经过 prompt 缓存处理；每轮对话的上下文（说话人身份、当前时间）搭载在另一个 刻意**不缓存**的块中，因此该部分的修改只需消耗约 20 个 新 token，而不会使整个已缓存的 prefix 失效。 **最小权限原则，在代码中强制执行。** 并非每个调用者都能使用所有工具。来自 手机客户端或 Discord 桥接的请求将被提供一个*受限的*工具 界面 —— 没有shell、没有文件系统、没有代码执行、没有自我更新。该边界 在服务端的两个独立关卡强制执行：工具列表在 模型看到之前就已经被过滤，*并且*如果某个被拒绝的工具通过某种方式被 触达，执行器也会按名称拒绝执行。该原则绝对不通过在 prompt 中 委婉要求模型来执行。变更性操作 受到确认门控的限制，并且该门控会携带评估该操作所需的信息 —— 无法让你评估的确认门控只是形式主义，而非真正的安全。 **任意代码获得的是边界限制，而非白名单。** `run_code` 在 临时的 Podman 容器中执行由 Claude 编写的 Python 代码：无网络、无主机挂载、 设有 CPU/内存/PID 限制，并在 30 秒后强制终止。你无法为 任意代码设立白名单，因此只能转而对其进行隔离。 **所有组件采用平滑降级。** 任何单一子系统 —— TTS、Plex 桥接器、GPU 转录服务器、日历源 —— 均可发生故障而不会导致监听 循环崩溃。优雅降级并记录日志；绝对不让与用户正在 交流的系统崩溃。 **设立回归测试关卡，因为本该由测试拦截的 bug 必须要有对应的测试。** `scripts/run_all_tests.py` 会运行 49 个关卡 —— 包括语法、模块连接、一项 JS 结构 检查，以及总计包含约 1,100 项断言的 46 个测试套件 —— 且在 任何代码发布前必须全部通过。CI 会在每次推送时运行*相同的* 命令；其中五个需要原生 ML 工具链或 Windows SAPI 的关卡会按名称被明确 跳过，绝不悄无声息地混入通过的数量中。 ## 功能 | 领域 | | | --- | --- | | **语音** | 唤醒词、回复中途打断、后续对话窗口（无需重复唤醒）、解放双手的对话模式、实时双向同声传译模式 | | **知识库** | 网络搜索与抓取、私有 RAG 语料库（SQLite FTS5 + 本地 embedding，使用 Reciprocal Rank Fusion 融合）、过往对话的全文检索 | | **感知** | 网络摄像头视觉、屏幕捕捉、环境声音分类（PANNs）、基于语音 embedding 的说话人识别 | | **主动服务** | 极端天气警报、日历事件前提醒、家庭实验室运行/宕机监控、跨领域信息综合、早间简报与晚间总结 | | **长周期任务** | 派发在托管沙盒中运行长达一小时并反馈结果的研究任务 —— 完成时通过语音播报，如果在夜间完成则并入早间简报（可选择开启） | | **系统** | 只读诊断 shell（包含 18 个动词的白名单）、需确认门控的服务控制、沙盒代码执行、自我更新、崩溃看门狗 | | **客户端** | 桌面控制台、系统托盘、通过 WSS 进行按键说话的 iOS PWA、Discord 机器人桥接 | | **数据源** | 天气、体育、新闻、影视、游戏、WolframAlpha、Plex（通过 MCP） | 设计上支持多语言：系统会逐轮检测语言，并以相应的语音返回 该语言的回复。 ## 技术栈 Python 3.12 · [openWakeWord](https://github.com/dscripka/openWakeWord) · [faster-whisper](https://github.com/SYSTRAN/faster-whisper) · Anthropic SDK（流式传输、 prompt 缓存、工具使用） · [edge-tts](https://github.com/rany2/edge-tts) 并提供 `pyttsx3` 离线回退方案 · `sounddevice` · YOLOv8n · Resemblyzer · Podman · `websockets` · MCP 特意选择原生支持 Windows 而非 WSL：因为 WSL2 的音频桥接对于 常驻型实时音频捕获而言，其稳定性还不够。 ## 快速开始 ``` git clone https://github.com/samonti86/jarvis.git && cd jarvis python -m venv venv .\venv\Scripts\Activate.ps1 pip install -r requirements.txt Copy-Item .env.example .env # then set ANTHROPIC_API_KEY python scripts\doctor.py # verifies deps, config, audio devices python main.py # or: pythonw jarvis.pyw (silent, no console) ``` 然后说 **“Hey Jarvis.”** `doctor.py` 是只读的，并且会准确地告诉你缺少了什么 —— 它是解答 “为什么无法启动？”的最快途径。Anthropic API 密钥是**唯一**的硬性 要求；其他所有集成为可选项，默认关闭，并在未配置时 平滑降级提示“未配置”，而不会导致报错崩溃。 - **[docs/SETUP.md](docs/SETUP.md)** —— 详细的配置指南，包括如何获取各个 API 密钥 - **[docs/ENV_VARS.md](docs/ENV_VARS.md)** —— 所有配置项、其默认值以及读取来源 使用 `python scripts/run_all_tests.py` 运行测试关卡。 ## 布局 ``` main.py composition root: load config, build subsystems, start threads src/listen_loop.py voice path — wake word, barge-in, follow-up/conversation modes src/turn_runner.py one turn end-to-end: history, streaming, tool loop, TTS src/bootstrap.py subsystem assembly (Plex, announcer, remote console, shutdown) src/llm.py Anthropic client, streaming, tool loop, per-origin tool boundary src/wake_word.py openWakeWord src/speech_to_text.py faster-whisper (local, or offloaded to a GPU host) src/text_to_speech.py edge-tts + fallback, sentence-chunked streaming src/security.py vision security mode (person detection, challenge/response) src/*.py the tool and subsystem modules (70 in total) tests/*_test.py the regression suites — everything here runs in the gate scripts/ operational entry points + hand-run probes; never collected docs/SETUP.md deployment walkthrough docs/MILESTONES.md engineering log — index + "start here" docs/milestones/ the log itself, 107 entries across 5 parts ``` ## 许可证 个人项目，作为作品集展示发布。

标签：AI智能体, 人工智能, 文本转语音, 本地语音识别, 用户模式Hook绕过, 语音助手, 逆向工具