maThiaslI152/OwlynnV2

# Owlynn — 本地 AI 协作 Agent [](https://python.org) [](https://nodejs.org) [](scripts/ci.sh) [](frontend-v2/) [](LICENSE) 一个私有的 AI 生产力 agent，具备**云端优先的 DeepSeek V4** 路由和本地回退机制。采用 LangGraph 编排，MiniCPM5 路由器 + 可选的本地 Qwen9B 回退，用于图像的 Florence-2 视觉代理，语义记忆，以及 Electron 桌面 UI。针对 Apple Silicon (M4 Air 24GB) 进行了优化。 ## 目标 Owlynn 是一款**桌面 AI 协作者**，可将您的数据保留在本地。它能够推理复杂任务、调用工具（网页搜索、文件操作、文档生成、notebook 执行、屏幕/终端上下文）、通过向量内存在会话间保持记忆，并在人工批准后才会执行敏感操作——云增强是可选开启的（opt-in）。 **目标用户**：使用 Apple Silicon 的开发者和高级用户，期望获得一个尊重隐私的助手以进行渗透测试/研究工作流，具备可选的云端推理和可扩展的工具/技能。 ## 核心特性 | 功能 | 摘要 | |------------|---------| | **路由** | MiniCPM5 路由器 → `simple` \| `complex-default` \| `complex-cloud` | | **记忆编排** | 分离式注入（`memory_inject_lite` → 路由器 → 受控的 `memory_retrieve`），异步 8B 提取，PII 清理，渗透测试/研究场景 | | **视觉代理** | 本地 VLM → JSON OCR → 纯文本 DeepSeek 路径；延迟加载 + 空闲卸载 | | **屏幕辅助** | macOS tmux 捕获，Accessibility API，浏览器标签页，Kali SSH tmux（Python 工具） | | **HITL** | 安全代理 + 敏感工具调用的计划审查 | | **搜索** | wttr.in → SearXNG → curl_cffi → DDGS → Playwright | 完整路线图：[`docs/guides/memory-vision-screen-roadmap.md`](docs/guides/memory-vision-screen-roadmap.md) ## 入口点 ``` src/api/server.py # FastAPI (REST + WebSocket + OpenAI-compatible API) src/agent/graph.py # LangGraph builder, init_agent() frontend-v2/electron/main.ts # Electron main process frontend-v2/src/App.tsx # React shell + WebSocket lifecycle ./start.sh # Full stack launcher ``` ## 架构 ``` User Message │ ▼ memory_inject_lite ──► profile, persona, topics (no vector search) │ ▼ router ──► simple | complex-default | complex-cloud; memory gate + scenario │ ▼ memory_retrieve ──► gated Qdrant/Mem0 + scenario markdown (when needed) │ ▼ auto_summarize? ──► if tokens > 85% context window │ ├── simple ──► memory_write ──► END │ └── scope_clarify ──► complex_llm ◄──┐ │ │ │ │ [images + cloud] vision_proxy → DeepSeek (text only) │ │ │ │ plan_review / security_proxy (HITL) │ ▼ │ tool_action ─────┘ │ ▼ memory_write ──► PII scrub → Redis extraction queue → END ``` 路由：**`simple`**，**`complex-default`**（本地 Qwen），**`complex-cloud`**（DeepSeek V4）。已移除旧的 `complex-vision` / `complex-longctx` 路由。 ### 技术栈 | 层级 | 技术 | |-------|------------| | 后端 | FastAPI + LangGraph + Python 3.11+ | | 前端 | React 19 + TypeScript (Vite 8) + Zustand 5，Electron 桌面端 | | 路由 LLM | `minicpm5-1b`（分类） | | 中型 LLM | `qwen3.5-9b-uncensored-hauhaucs-aggressive@q6_k`（本地复杂任务 + 视觉代理） | | 云端 LLM | `deepseek-v4-flash` / `deepseek-v4-pro`（可选的 `complex-cloud`） | | 文件处理 | Docling v2 (PDF/DOCX → markdown) | | 记忆 | Mem0 + Qdrant + JSON STM；Redis 提取工作进程 | | 检查点 | Redis (`AsyncRedisSaver`；回退到内存) | | 搜索 | 多层级：wttr.in / SearXNG → curl_cffi / DDGS → Playwright | | 测试 | pytest + hypothesis（后端），vitest（前端） | | CI | 本地 [`scripts/ci.sh`](scripts/ci.sh)（pre-push 钩子） | ## 项目结构 ``` src/agent/ graph.py, llm.py, state.py, tool_sets.py nodes/ router.py, complex.py, simple.py, memory.py, summarize.py complex_utils/vision_proxy.py, vision_schema.py, vision_model_manager.py security_proxy.py, scope_clarify.py, plan_review.py src/memory/ long_term.py, memory_manager.py, personal_assistant.py extraction/ # async 8B atom extractor (Redis stream) scenarios.py # pentest + research L2/L3 markdown loader compression.py # cloud brief memory block src/tools/ core_tools.py, web_tools.py, doc_generator.py, notebook.py, skills.py screen_assist/ # tmux, AX, browser, Kali SSH tools scenarios/ pentest/, research/ # playbook + constraints markdown frontend-v2/ # React + Electron UI tests/ # pytest + benchmarks docs/ # architecture, guides, API reference ``` ## 配置 设置位于 `src/config/defaults.yaml`（覆盖链：YAML → 环境变量 → `user_profile.json`）。 ### 环境变量 | 变量 | 描述 | |----------|-------------| | `REDIS_URL` | LangGraph 检查点 + 记忆提取流 | | `QDRANT_HOST` / `QDRANT_PORT` | 向量记忆 | | `SEARXNG_URL` | 自托管搜索（例如 `http://localhost:8888`） | | `DEEPSEEK_API_KEY` | 可选的云端路由 (`complex-cloud`) | | `KALI_SSH_HOST` | 用于 `capture_kali_terminal` 的远程 Kali VM | | `SCREEN_ASSIST_TMUX_SESSION` | 默认的本地 tmux 会话名 | | `OPTIMIZE_FOR_M4` | M4 Air 超时和内存限制 | ### LLM 设置 | 插槽 | 默认模型 | 角色 | |------|---------------|------| | 小型 | `minicpm5-1b` | 路由器 | | 中型 | `qwen3.5-9b-...@q6_k` | 本地复杂任务 + 视觉代理 | | 云端 | `deepseek-v4-flash` | DeepSeek V4 (`complex-cloud`) | 本地模型通过端口 `1234` 上的 LM Studio 加载。 ## 测试 ``` ./scripts/ci.sh # Full suite (Python + frontend + build) ./scripts/ci.sh --quick # Skip frontend production build ./scripts/ci.sh --python-only ./scripts/ci.sh --benchmarks # Optional latency benchmarks ``` **当前测试套件（本地 CI）：** 约 884 个后端测试（pytest），107 个前端测试（vitest）。基准测试：使用 `-m benchmark` 的 60 个测试。 ``` # 自动化 memory suite（unit + smoke） ./scripts/test_memory.sh ./scripts/test_memory.sh --redis # include live Redis enqueue when Redis is up # 或直接运行 pytest PYTHONPATH=$(pwd) pytest -q \ tests/test_phase1_memory_orchestration.py \ tests/test_memory_retrieve_gate.py \ tests/test_memory_orchestration_smoke.py \ -m "not network" ``` 详见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解工作流详情。 ## 快速开始 ### 一次性设置 ``` git clone && cd OwlynnV2 ./setup.sh # containers, venv, pip, Docling models, .env ``` 在 `.env` 或设置 UI 中配置模型（参见 [`docs/guides/dev-startup.md`](docs/guides/dev-startup.md)）。 ### 启动 ``` ./start.sh ``` 启动 Podman 容器（Qdrant + Redis），提示在 `:1234` 启动 LM Studio，然后启动后端（`:8000`）+ Vite（`:5173`）。 ### 仅浏览器开发 ``` # Terminal 1 source .venv/bin/activate && uvicorn src.api.server:app --host 127.0.0.1 --port 8000 # Terminal 2 cd frontend-v2 && npx vite --host 127.0.0.1 ``` 打开 `http://127.0.0.1:5173`。安全模式和屏幕辅助**预览**需要 Electron IPC；**后端**屏幕辅助工具在 macOS 上支持无头模式（headless）运行。 ### Electron 桌面构建 ``` cd frontend-v2 && npm run build ``` 输出：`frontend-v2/dist/`（在 macOS 上为 `.app` / `.dmg`）。 ## 工具 | 类别 | 工具 | |----------|-------| | Web | `web_search`, `fetch_webpage`, `deep_research` | | 文件 | `read_workspace_file`, `write_workspace_file`, `edit_workspace_file`, `list_workspace_files`, `delete_workspace_file` | | 文档 | `create_docx`, `create_xlsx`, `create_pptx`, `create_pdf` | | 计算 | `notebook_run`, `notebook_reset` | | 记忆 | `recall_memories`, `recall_all_memories`, `forget_memory`, `search_workspace_docs` | | 屏幕辅助 | `capture_local_terminal`, `read_screen_element`, `get_active_browser_context`, `capture_kali_terminal` | | 任务 / 技能 | `todo_*`, `list_skills`, `invoke_skill` | | HITL | `ask_user` | 工具箱类别：`web_search`, `file_ops`, `data_viz`, `productivity`, `memory`, `screen_assist`, `all`。详见 [`docs/TOOLS.md`](docs/TOOLS.md)。 ## 记忆系统 | 层级 | 存储 | 角色 | |------|---------|------| | STM | `data/memories.json` | 关键词事实 | | LTM | Qdrant + Mem0 | 语义召回（每轮受控） | | L1 atoms | 通过提取器的 Qdrant | 结构化事实（JSDoc / JSON） | | L2/L3 | `scenarios/*/playbook.md` | 渗透测试 / 研究工作流 | | 个人 | 主题，兴趣，对话 | 时间衰减上下文 | **注入路径：** `memory_inject_lite` → 路由器决定 `needs_memory_retrieval` → `memory_retrieve`。 **写入路径：** PII 清理 → 加入 Redis 流 `owlynn:memory:extract` 队列 → 8B 工作进程 → Qdrant。 详细信息：[`docs/MEMORY.md`](docs/MEMORY.md) · [`docs/guides/memory-orchestration-phase1.md`](docs/guides/memory-orchestration-phase1.md) ## API | 方法 | Endpoint | 描述 | |--------|----------|-------------| | `GET` | `/api/health` | 健康 + agent 就绪状态 | | `GET`/`POST` | `/api/profile` | 用户配置 | | `GET`/`POST`/`DELETE` | `/api/memories` | 短期 JSON 记忆 | | `GET` | `/api/mem0/search` | 向量记忆搜索 | | `GET`/`POST` | `/api/projects` | 项目 CRUD | | `WS` | `/ws/chat/{thread_id}` | 流式聊天 | 完整参考：[`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) · WebSocket 契约：[`docs/CHAT_PROTOCOL.md`](docs/CHAT_PROTOCOL.md) ## 文档 **AI agent：** 从 [`AGENTS.md`](AGENTS.md) 开始 → [`docs/PROJECT_GUIDE.md`](docs/PROJECT_GUIDE.md)。 | 文档 | 主题 | |-----|-------| | [`AGENTS.md`](AGENTS.md) | Agent 入职和任务路由 | | [`docs/PROJECT_GUIDE.md`](docs/PROJECT_GUIDE.md) | 按任务划分的文件映射 | | [`docs/architecture/overview.md`](docs/architecture/overview.md) | 系统概述 | | [`docs/AGENT_FLOW.md`](docs/AGENT_FLOW.md) | LangGraph 节点和边 | | [`docs/guides/memory-vision-screen-roadmap.md`](docs/guides/memory-vision-screen-roadmap.md) | 记忆 + 视觉 + 屏幕辅助 | | [`docs/architecture/VISION_PROXY.md`](docs/architecture/VISION_PROXY.md) | 云端视觉 / OCR pipeline | | [`docs/guides/screen-assist-phase3.md`](docs/guides/screen-assist-phase3.md) | 终端 / AX / Kali 工具 | | [`docs/architecture/DEEPSEEK_V4_INTEGRATION.md`](docs/architecture/DEEPSEEK_V4_INTEGRATION.md) | 云端路由和安全性 | | [`docs/CLOUD-LLM-ARCHITECTURE.md`](docs/CLOUD-LLM-ARCHITECTURE.md) | 云端 payload 和匿名化 | | [`docs/WEB_SEARCH.md`](docs/WEB_SEARCH.md) | 搜索层级回退 | | [`docs/STATUS.md`](docs/STATUS.md) | 项目状态和已知问题 | | [`docs/INDEX.md`](docs/INDEX.md) | 完整文档清单 | ## 关键决策 | 决策 | 理由 | |----------|-----------| | 本地优先路由 | 隐私 + 延迟；仅在 `complex-cloud` 时使用云端 | | 分离式记忆注入 | 低于 300ms 的路由路径；向量搜索在分类后受控开启 | | 自定义提取（无 mem0 推理） | 受控的 atom schema + 保证在进入 LTM 前清理 PII | | 视觉作为 OCR 传感器 | DeepSeek V4 是纯文本；结构化 JSON 而非长文本 | | 屏幕辅助使用 Python | tmux/AX/browser 需要原生 macOS 支持，而不仅是 Electron | | LangGraph + Redis 检查点 | 支持跨会话恢复的有状态工具循环 | | 本地 CI | 在 pre-push 阶段执行 `scripts/ci.sh` 而非使用 GitHub Actions 配额 | ## 贡献 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。在推送前运行 `./scripts/ci.sh --quick`。 ## 许可证 [MIT](LICENSE)

标签：DLL 劫持, LangGraph, React, Syscalls, 人工智能, 人类介入审批, 大语言模型, 搜索引擎查询, 本地AI代理, 桌面应用, 特征检测, 用户模式Hook绕过