LakshyaBadjatya/Friday

## ✨ 它是什么 FRIDAY 是一个**本地优先、提供商抽象的个人 AI 操作系统**，运行在 你自己的机器上。它刻意*不*是一个聊天机器人套壳：一个确定性的 orchestrator 会对每一轮对话进行分类，将其交给一个**具名专家 operator 组合**，并通过一个**故障关闭的安全 broker** 路由 每一个副作用，该 broker 负责注入密钥、强制执行 权限，并写入一个**哈希链式、防篡改的审计账本**。 - 🏠 **本地优先** — 在你的机器上运行；除非你故意将其指向真实的 provider，否则不会有任何数据外传。 - 🔌 **100% 提供商抽象** — 语言模型位于一个干净的接口之后。内置的 `FakeLLM` 让整个系统（及其 **1779 项测试**）在零网络和无密钥状态下保持绿色通过；当你想要真实回复时，可以切换到 NVIDIA NIM 或 Gemini。 - 🧱 **默认受 flag 控制** — 每一项非核心功能都位于 `FRIDAY_ENABLE_*` flag 之后，**默认关闭**。核心系统启动时体积极小且依赖极轻；你可以根据需要 逐步开启各项功能。 - 🧾 **架构上的诚实** — 没有捏造的数据。当后端不可达时，FRIDAY 会直接告诉你，而不是编造答案。 ## 🧠 大脑 一个确定性的路由器会在*任何模型调用之前*，将每一轮对话分类为一种会话**模式**（`CONVERSATION`、 `RESEARCH`、`AUTOMATION`、`DEVICE_CONTROL`、`ALERTING`、`SECURITY_LOCKDOWN`、`CLARIFY` 等） — 因此即使在语言后端宕机时，路由配置也已就绪。 然后 orchestrator 会将任务委托给一个由最小权限专家组成的 **8 角色组合**， 每个专家都拥有独特的工具切片及其专属的 memory namespace。 | Operator | 头衔 | 负责领域 | |---|---|---| | 🛰️ **FRIDAY** *(主)* | 主 Operator | 所有专家能力的广泛联合 — 负责委派或充当其中任何一个的替身 | | 🛡️ **EDITH** | 安全与锁定 | 面向所有者的防御性锁定、安全审计、通知 | | ⏱️ **ORACLE** | 自动化与调度 | 调度器、协议、提醒 | | 📈 **GECKO** | 金融与市场 | 市场数据、网络研究 | | ✉️ **KAREN** | 通讯 | 通知、邮件、agent 外联 | | ✍️ **VERONICA** | 内容与外联 | 网络研究、agent 外联 | | 📚 **JOCASTA** | 记忆与知识 | 知识库、RAG、知识图谱 | | 🔭 **VISION** | 研究与分析 | 分析、网络搜索、agent 外联 | | 🔧 **FORGE** | 开发与系统 | 运行命令、查找文件、打开应用、家庭/设备控制 | 各个角色都是**纯数据** — 包含一个头衔、一个冻结的工具允许列表、一个 memory namespace，以及一个 系统 prompt — 因此主 Operator 的范围是作为专家联合*计算*出来的，并且永远不会 失去同步。使用 `friday roster` 检查实时的角色列表。 ## 🔒 安全 FRIDAY 采取的每一个操作 — 无论是只读还是产生副作用 — 都会流经 **Broker**，这是一个 单一的故障关闭网关。任何内容如果不通过以下 pipeline，就无法到达工具： ``` raw intent │ ▼ 1. VALIDATE ── coerce args through the tool's typed model · reject bad args before any effect 2. CLASSIFY ── derive reversibility (side-effecting & not idempotent ⇒ irreversible) 3. GATE ── deny-by-default · unknown tool ⇒ denied · irreversible & unconfirmed ⇒ needs_confirmation 4. INJECT ── replace {{secret:NAME}} markers with real secrets at call time (never returned, never logged) 5. EXECUTE ── run via the injected tool registry 6. AUDIT ── append ONE hash-chained record (redacted args, decision, outcome, actor, channel) │ ▼ tamper-evident ledger ``` - **故障关闭网关** — 默认拒绝。不在允许列表中的工具将被拒绝；没有明确 `confirmed=true` 的 不可逆操作将被挂起以待确认。在这两种路径下，工具都 永远不会运行。 - **密钥注入** — 确切格式为 `{{secret:NAME}}` 的参数会在*调用时*从 vault 中解析。解析后的值会传递给工具，但**绝不**会在 结果中返回，也**绝不**会被写入审计 — 账本只记录标记，不记录密钥。 - **哈希链审计** — 每个账本条目的哈希值为 `sha256(prev_hash + canonical_json(record))`， 将其与前一个条目绑定。`verify` 会遍历链条并准确定位第一个被篡改、 删除或伪造的链接。敏感 key 会在哈希*之前*被脱敏。随时可以通过 `friday audit verify` 或 `GET /admin/audit/verify` 进行验证。 - **OS 密钥环密钥** — 密钥位于带有 `KeyringVault` 后端 （你的 OS keychain）的 vault 协议之后，并有 `EnvVault` / `FileVault` (0600) / `MemoryVault` 作为后备。Secret 字段的类型为 `SecretStr`，并在日志中进行脱敏。 - **SDK 隔离** — agent 层不导入任何提供商的 SDK（由 grep 强制执行），并且 出站的 `agent-reach` CLI 作为独立的子进程运行，带有明确的安装提示，并且在失败时没有 捏造的输出。 ## 🧩 功能 大约 50 项功能，几乎每一项都位于 `FRIDAY_ENABLE_*` flag 之后（**默认关闭**）， 按领域分组。核心的 chat/route/memory/broker 循环 — 以及只读的可观测性 视图 — 始终保持开启。

📖 点击展开完整功能表

### 🧱 核心 | 功能 | 作用 | Flag | |---|---|---| | Action Broker | 故障关闭的 验证 → 分类 → 网关 → 注入 → 执行 → 审计 pipeline | `FRIDAY_ENABLE_BROKER` | | Agent reach | 通过隔离的出站 CLI 子进程连接其他 agent | `FRIDAY_ENABLE_AGENT_REACH` | | Extra tools | 核心注册表之外的可选扩展工具面 | `FRIDAY_ENABLE_EXTRA_TOOLS` | | Plugins | 加载即插即用的功能插件 | `FRIDAY_ENABLE_PLUGINS` | | Offline mode | 强制使用完全离线的路径（fake provider，无网络） | `FRIDAY_ENABLE_OFFLINE_MODE` | | Self-critique | 对响应进行反思性的自我批评过程 | `FRIDAY_ENABLE_SELF_CRITIQUE` | ### 🧠 记忆 | 功能 | 作用 | Flag | |---|---|---| | Knowledge graph | 将实体/关系提取到可遍历的图中 | `FRIDAY_ENABLE_KNOWLEDGE_GRAPH` | | RAG | 摄取文档并基于其内容生成有依据的回答 | `FRIDAY_ENABLE_RAG` | | Journal | 构建和查询个人日志 | `FRIDAY_ENABLE_JOURNAL` | | Study | 间隔重复卡片、复习会话 | `FRIDAY_ENABLE_STUDY` | | Postgres | 使用 Postgres 而非 SQLite 进行持久化存储 | `FRIDAY_ENABLE_POSTGRES` | ### 🎙️ 语音 | 功能 | 作用 | Flag | |---|---|---| | Voice pipeline | 唤醒词 → Whisper STT → orchestrator → TTS，支持打断 | `FRIDAY_ENABLE_VOICE` | | Wake & summon | "Hey FRIDAY" 唤出 HUD 并向你问候；"summon <operator>" 切换 operator，每个都有独特的声音 | `FRIDAY_ENABLE_WAKEWORD` | | Voiceprint | 语音路径上的说话人验证 | `FRIDAY_ENABLE_VOICEPRINT` | ### 🖼️ 多模态 | 功能 | 作用 | Flag | |---|---|---| | Sentiment | 基于离线词典对文本进行情绪评分，支持否定处理 (`POST /sentiment`) | `FRIDAY_ENABLE_SENTIMENT` | | Diarization | 用于会议记录的“谁在何时说话”说话人分段（延迟加载 `pyannote`） | `FRIDAY_ENABLE_DIARIZATION` | | Image generation | 文本生成图像 (`POST /imagegen`) — 离线时使用 SVG 占位符，安装后使用 `diffusers` | `FRIDAY_ENABLE_IMAGEGEN` | | PDF layout | 具备布局感知能力的 PDF → 文本块页面 (`POST /pdf/layout`，延迟加载 PyMuPDF) | `FRIDAY_ENABLE_PDF_LAYOUT` | ### 🧊 3D 工作室 | 功能 | 作用 | Flag | |---|---|---| | 3D Studio | 通过文本/语音描述模型，通过手势和语音进行探索，导出 GLB/STL/OBJ | `FRIDAY_ENABLE_STUDIO` | ### 👁️ 视觉 | 功能 | 作用 | Flag | |---|---|---| | Perception | YOLO 检测、OCR、剪贴板、屏幕截图 → `describe_screen()` *(重度涉及隐私)* | `FRIDAY_ENABLE_PERCEPTION` | ### 📡 主动功能 | 功能 | 作用 | Flag | |---|---|---| | Proactive | FRIDAY 主动发起任务而无需提示 | `FRIDAY_ENABLE_PROACTIVE` | | Scheduler | 基于时间的任务调度 | `FRIDAY_ENABLE_SCHEDULER` | | Protocols | 多步骤的命名协议/例程 | `FRIDAY_ENABLE_PROTOCOLS` | | Reminders | 创建、列出、完成提醒 | `FRIDAY_ENABLE_REMINDERS` | | Briefing | 生成汇总的简报 | `FRIDAY_ENABLE_BRIEFING` | | Presence | 基于 MAC 的在线状态/已知设备检测 | `FRIDAY_ENABLE_PRESENCE` | | Meetings | 捕获并总结会议内容 | `FRIDAY_ENABLE_MEETINGS` | ### 🔌 集成 | 功能 | 作用 | Flag | |---|---|---| | Maps | Google Maps 路线/地点/地理编码 | `FRIDAY_ENABLE_MAPS` | | Market data | 通过 Dhan broker API 获取实时报价和持仓 | `FRIDAY_ENABLE_MARKET_DATA` | | Calendar | Google Calendar 活动 | `FRIDAY_ENABLE_CALENDAR` | | Email | Gmail 读取/发送 | `FRIDAY_ENABLE_EMAIL` | | Comms | 通过 Twilio 发送 SMS/WhatsApp | `FRIDAY_ENABLE_COMMS` | | n8n | 在确认步骤之后草拟并启动 n8n 工作流 | `FRIDAY_ENABLE_N8N` | | Family sharing | 可选择加入、可撤销的家庭分享 | `FRIDAY_ENABLE_FAMILY_SHARING` | | Home | 家庭/设备控制 | `FRIDAY_ENABLE_HOME` | | Media control | 控制媒体播放 | `FRIDAY_ENABLE_MEDIA_CONTROL` | | Downloads butler | 整理和组织下载文件夹 | `FRIDAY_ENABLE_DOWNLOADS_BUTLER` | ### 🛠️ 运维 | 功能 | 作用 | Flag | |---|---|---| | HUD | Command Centre 平视显示界面 — 主题、⌘K 调色板、快捷询问 | `FRIDAY_ENABLE_HUD` | | Desktop | 桌面自动化界面 | `FRIDAY_ENABLE_DESKTOP` | | System tray | 用于打开 HUD/通知的系统托盘图标（通过 `friday tray` 启动） | `FRIDAY_ENABLE_TRAY` | | System automation | 驱动系统级自动化 | `FRIDAY_ENABLE_SYSTEM_AUTOMATION` | | System monitor | 实时系统统计和健康检查 | `FRIDAY_ENABLE_SYSTEM_MONITOR` | | Secret self-check | 启动时扫描明文密钥 | `FRIDAY_ENABLE_SECRET_SELF_CHECK` | | OpenTelemetry | 将完成的 trace 导出到 OTLP collector（延迟加载 SDK） | `FRIDAY_ENABLE_OTEL` | ### 📊 可观测性 *(始终开启)* | 功能 | 作用 | |---|---| | Cost dashboard | 每个模型的 token/美元使用账本 — `GET /admin/usage` | | Turn replay | 最近的对话记录，用于检查和重播 — `GET /adminturns` | | Metrics / traces / audit | 请求计数器、每轮对话的 span trace、脱敏的工具调用日志 — `GET /admin/{metrics,traces,audit}` | | Doctor & eval | 一次性健康自检 (`friday doctor`) 和离线 prompt-eval 测试套件 (`friday eval`) | | Encrypted backup | 经过身份验证的本地备份/恢复 memory DB + 审计账本 (`friday backup`) |

## 🚀 快速开始 **要求：** Python **3.12+** 和 [uv](https://docs.astral.sh/uv/)。 ``` make install # uv sync --all-groups — venv + everything core cp .env.example .env # then edit: pick a provider, set keys you want make run # uv run uvicorn friday.app:create_app --factory --reload ``` 这会在 `http://127.0.0.1:8000` 上提供服务。对其进行健全性检查（不调用 LLM）： ``` curl -s http://127.0.0.1:8000/health # {"status":"ok","llm_provider":"fake","model":null} ``` 向其发送一轮对话： ``` curl -s -X POST http://127.0.0.1:8000/chat \ -H 'content-type: application/json' \ -d '{"session_id":"s1","text":"hello"}' ``` ### `friday` CLI ``` friday serve # run the ASGI app via uvicorn friday tui # in-process terminal cockpit (REPL over the core loop) friday doctor # one-shot health self-test; non-zero exit if unhealthy friday eval cases.json # run an offline prompt-eval suite; gate on a pass-rate friday backup create OUT # encrypted backup of the memory DB + audit ledger (restore too) friday tray # launch the desktop tray icon friday audit verify # walk the hash-chained ledger; non-zero exit on tamper friday secrets set NAME VAL # store a secret in the configured vault friday secrets get NAME # read it back friday roster # print the persona roster friday version # print the package version ``` ## 🗺️ 界面 FRIDAY 在一个核心之上提供了许多界面。受 flag 控制的界面在启用之前会返回 `404`。 | 界面 | 路径 | 介绍 | |---|---|---| | 💬 Chat | `POST /chat` | 文本对话循环 — 操作系统的心脏 | | 🛰️ HUD | `GET /hud` | Command Centre 平视显示器（主题、⌘K 调色板、快捷询问） | | 🖥️ TUI | `friday tui` | 基于相同核心循环的进程内终端控制台 | | 🧊 Studio | `GET /studio` | 3D 工作室（Three.js + MediaPipe，无需 Node 构建步骤） | | 🗺️ Maps | `GET /maps` | 交互式地图界面 | | 🛠️ Admin | `/admin/*` | 状态、审计、trace、指标、**用量（成本）**、**对话重播**、flag | | 🖼️ Multimodal | `POST /sentiment`, `/imagegen`, `/pdf/layout` | 情感分析、文本生成图像、布局感知 PDF | | 📱 PWA | `GET /` | 可安装的渐进式 Web 应用（manifest、service worker、离线页面） | | 🧩 Browser ext | `browser_ext/` | 用于本地 FRIDAY 的 Manifest V3 快捷询问弹窗 | | 📊 Dashboard | Streamlit | 一个读取管理界面的独立 operator 控制台 | | 🎙️ Voice | `POST /voice`, `WS /ws/voice`, `WS /ws/wake` | 单次语音对话 / 流式传输 + 打断 / 唤醒 + 召唤 | **Streamlit dashboard** 是一个*独立的 UI 进程* — 绝不会被包或 测试套件导入，其依赖项也被排除在 lock 之外： ``` make install-dashboard make run # API in one shell make dashboard # uv run streamlit run dashboard/app.py in another ``` ## 🛠️ Make 目标 | 目标 | 作用 | |---|---| | `make install` | `uv sync --all-groups` — 核心 venv + 依赖 | | `make install-voice` | 安装可选的语音后端 | | `make install-perception` | 安装可选的视觉后端 | | `make install-dashboard` | 安装 Streamlit dashboard 依赖 | | `make run` | 使用 `--reload` 运行 API | | `make dashboard` | 启动 Streamlit operator 控制台 | | `make test` | `uv run pytest -q` | | `make lint` | `uv run ruff check src tests` | | `make fmt` | `uv run ruff format src tests` | | `make type` | `uv run mypy` (严格模式) | | `make docker-build` / `docker-up` / `docker-down` | 构建并运行容器 | ## 🧪 质量 - ✅ **1779 项测试通过** — 整个测试套件在离线状态下针对 `FakeLLM` 运行：零网络、 零密钥。 - ✅ 跨包执行 **`mypy --strict`**，并使用 **`ruff`** 进行 lint 和格式化。 - ✅ **所有功能均受 flag 控制，默认关闭** — 核心系统最小化启动；在选择性开启之前，界面均返回 `404`。 - ✅ **没有捏造的数据，诚实的失败** — 当后端不可达时，FRIDAY 会如实相告 而不是编造答案。 - ✅ **Provider-clean agent** — agent 层通过 grep 强制保证不包含 LLM SDK。 ``` make lint && make type && make test ``` ## 📡 正式上线 以下所有内容**默认关闭**。设置 flag *并* 提供相应的密钥/服务即可 开启每一项。Secret 类型的值为 `SecretStr` — 在日志中被脱敏，仅在相关的出站调用中发送。

🔑 点击展开 flag → 服务映射表

| 要启用 | 设置 flag | 并提供 | |---|---|---| | 真实 LLM 回复 | `FRIDAY_LLM_PROVIDER=nvidia` | `NVIDIA_API_KEY`, `NVIDIA_MODEL` | | LLM 备选 | `FRIDAY_LLM_FALLBACK_PROVIDER=gemini` | `GEMINI_API_KEY`, `GEMINI_MODEL` | | Maps | `FRIDAY_ENABLE_MAPS=true` | `FRIDAY_GOOGLE_MAPS_API_KEY` | | Market data | `FRIDAY_ENABLE_MARKET_DATA=true` | `FRIDAY_DHAN_CLIENT_ID`, `FRIDAY_DHAN_ACCESS_TOKEN` | | Calendar | `FRIDAY_ENABLE_CALENDAR=true` | `FRIDAY_GOOGLE_OAUTH_TOKEN` | | Email | `FRIDAY_ENABLE_EMAIL=true` | `FRIDAY_GMAIL_OAUTH_TOKEN` | | Comms (SMS/WhatsApp) | `FRIDAY_ENABLE_COMMS=true` | `FRIDAY_TWILIO_ACCOUNT_SID`, `FRIDAY_TWILIO_AUTH_TOKEN`, `FRIDAY_TWILIO_FROM_NUMBER` | | n8n workflows | `FRIDAY_ENABLE_N8N=true` | 运行中的 n8n (Docker) + 其 REST API 密钥 | | Postgres memory | `FRIDAY_ENABLE_POSTGRES=true` | `FRIDAY_POSTGRES_DSN` | | Voice | `FRIDAY_ENABLE_VOICE=true` | `make install-voice` + 可用的**麦克风** | | Wake word ("Hey FRIDAY") | `FRIDAY_ENABLE_WAKEWORD=true` | 已训练的 `hey_friday.onnx` (Colab notebook) + **麦克风** | | Image generation | `FRIDAY_ENABLE_IMAGEGEN=true` | 可选的 `diffusers`（否则使用确定性的 SVG 占位符） | | PDF layout | `FRIDAY_ENABLE_PDF_LAYOUT=true` | 可选的 PyMuPDF（否则使用纯文本后备） | | Diarization | `FRIDAY_ENABLE_DIARIZATION=true` | 可选的 `pyannote.audio`（否则使用确定性的假数据） | | OpenTelemetry export | `FRIDAY_ENABLE_OTEL=true` | 位于 `FRIDAY_OTEL_ENDPOINT` 的 OTLP/HTTP collector | | Perception | `FRIDAY_ENABLE_PERCEPTION=true` | `make install-perception` + `tesseract` 二进制文件 + **网络摄像头** | | Presence | `FRIDAY_ENABLE_PRESENCE=true` | `FRIDAY_PRESENCE_KNOWN_DEVICES` | | Remote access | *(部署)* | 一个 **Tailscale** tailnet，用于在局域网外安全访问你的机器 |

🧭 架构一览

``` ┌──────────────────────────────────────────────────────────────┐ │ CHANNELS chat · voice · HUD · studio · maps · PWA · admin │ └──────────────────────────────┬───────────────────────────────┘ │ ┌─────────────▼─────────────┐ │ ORCHESTRATOR + ROUTER │ deterministic mode │ (mode classified first) │ before any model call └─────────────┬─────────────┘ │ delegate ┌───────────────────────▼────────────────────────┐ │ ROSTER FRIDAY ▸ EDITH ORACLE GECKO KAREN │ │ VERONICA JOCASTA VISION FORGE │ least-privilege └───────────────────────┬────────────────────────┘ │ every action ┌─────────────▼─────────────┐ │ BROKER │ validate → classify → │ fail-closed · deny-default │ gate → inject → execute └──────┬──────────────┬──────┘ │ │ ┌─────────────▼───┐ ┌─────▼──────────────────┐ │ TOOLS / MEMORY │ │ HASH-CHAINED AUDIT │ tamper-evident │ (registry, KV, │ │ sha256(prev + record) │ ledger │ RAG, graph) │ └────────────────────────┘ └─────────────────┘ LLM PROVIDER SEAM ── fake │ nvidia │ gemini ── injected, never imported by the orchestrator or agent layer ```

⚙️ 常用环境变量

``` # Provider FRIDAY_LLM_PROVIDER=fake # fake | nvidia NVIDIA_API_KEY= NVIDIA_MODEL=meta/llama-3.3-70b-instruct FRIDAY_LLM_TIMEOUT_SECONDS=120 FRIDAY_LLM_FALLBACK_PROVIDER=none # none | gemini GEMINI_API_KEY= GEMINI_MODEL=gemini-2.0-flash # 语音 FRIDAY_ENABLE_VOICE=false FRIDAY_TTS_PROVIDER=piper # piper | elevenlabs | fake # Gateway FRIDAY_BIND_HOST=127.0.0.1 FRIDAY_API_KEYS= # …每个能力都有一个 FRIDAY_ENABLE_* flag — 请参阅 .env.example 获取完整的、 # 已记录的列表（包含每个变量，无真实值）。 ``` `.env` 已被 gitignored，是唯一存放真实密钥的地方；`.env.example` 记录了每一个 变量，但不包含真实值。

标签：AI助手, Python, RAG, 人工智能, 内核驱动漏洞利用, 操作系统, 无后门, 本地部署, 测试用例, 用户模式Hook绕过, 网络调试, 自动化