Octopus 技术栈分析

基于代码库真实依赖、导入链路和运行时配置的全面技术栈梳理。

1. 语言与运行时

Python（核心引擎）

Octopus 的 kernel、server、CLI、TUI、base 五层均采用 Python 实现，要求 python3（非 python）。

代码证据：

  • kernel/pyproject.toml — requires-python = ">=3.11"
  • server/shared/pyproject.toml — requires-python = ">=3.11"
  • kernel/ops/gates.py — 入口 python3 -m ops.gates all

TypeScript / JavaScript（前端产品）

  • Web 控制台：React + TypeScript
  • Desktop 壳层：Tauri + TypeScript
  • Mobile 应用：React Native + TypeScript (Expo)

代码证据：

  • products/web/package.json — "react": "^18.3.1", "typescript": "~5.6.2"
  • products/mobile/package.json — "expo": "~53.0.0", "react-native": "0.79.2"
  • products/desktop/package.json — "@tauri-apps/api": "^2.1.0"

Rust（Desktop 原生层）

Tauri 2.x 底层由 Rust 编译为原生二进制，提供窗口管理、系统托盘、文件对话框等 OS 级能力。

代码证据：

  • products/desktop/src-tauri/ — Tauri Rust 源码目录

2. Web 框架与 HTTP

FastAPI（服务端 REST）

服务端 HTTP 层基于 FastAPI 构建，28 个路由模块，约 546 个端点。

代码证据：

  • server/shared/pyproject.toml — "fastapi>=0.110", "uvicorn>=0.27"
  • server/shared/adapters/http/routes_core.py — 组装所有 _routes_*.py 子路由器
  • server/shared/shared.py — FastAPI app 工厂函数

Uvicorn（ASGI 服务器）

生产部署使用 uvicorn 作为 ASGI 服务器。

代码证据：

  • server/shared/pyproject.toml — "uvicorn>=0.27"
  • server/main.py — uvicorn.run() 入口

httpx（HTTP 客户端）

所有 HTTP 出站调用统一使用 httpx，包括 API 调用、LLM 请求、外部服务连接。

代码证据：

  • server/shared/pyproject.toml — "httpx>=0.27"
  • server/shared/ports_impl/dispatch_router.py — API 传输通道使用 httpx
  • server/shared/ports_impl/_httpx_resilient.py — 弹性 HTTP 客户端（重试/退避）
  • products/cli/client.py — OctopusClient 使用 httpx 同步客户端
  • products/tui/client.py — AsyncOctopusClient 使用 httpx.AsyncClient

Vite（前端构建）

Web 控制台使用 Vite 5.x 作为开发和构建工具。

代码证据：

  • products/web/vite.config.ts — @vitejs/plugin-react
  • products/web/package.json — "vite": "^5.4.10"

3. UI 框架

React 18（Web 控制台）

SPA 架构，React Router v6 管理 9 个页面路由。

代码证据：

  • products/web/src/main.tsx — React Router 定义 /, /dashboard, /organization, /tasks, /roles, /memory, /history, /settings 等路由
  • products/web/src/App.tsx — Auth 检查、Desktop 集成、全局键盘快捷键

Textual（TUI 终端界面）

Python 终端 UI 框架，提供富文本、面板、异步刷新。

代码证据：

  • products/tui/__main__.py — from textual.app import App
  • products/tui/app.py — OctopusTUI(App) 类，CSS 样式 styles/app.tcss
  • products/tui/screens/ — Dashboard、Chat、Tickets、Capabilities、Logs 五屏

React Native + Expo（Mobile）

跨平台移动应用，支持 iOS/Android，响应式布局适配手机和平板。

代码证据：

  • products/mobile/App.tsx — 7 个 Tab 屏（Chat、Plans、Execution、Graph、KPI、Learning、Settings）
  • 平板断点：768px，横屏 Sidebar + Content 布局

Tauri 2.x（Desktop 壳层）

将 Web 控制台包装为原生桌面应用，提供 OS 集成能力。

代码证据：

  • products/desktop/package.json — "@tauri-apps/api": "^2.1.0"
  • products/web/src/lib/desktop.ts — isDesktop() 检测 Tauri 环境，窗口状态持久化

4. 数据存储

SQLite（主要持久化）

轻量嵌入式数据库，用于所有本地状态存储。

代码证据：

  • server/shared/ports_impl/secret_vault_sqlite.py — 凭据存储
  • server/shared/ports_impl/knowledge_store_sqlite.py — 知识库
  • server/shared/ports_impl/memory_sqlite.py — 记忆/情景存储
  • server/shared/ports_impl/flywheel_store_sqlite.py — 指标/反馈存储
  • server/shared/ports_impl/profile_store_sqlite.py — 用户/Agent 配置
  • state/os_store_*.sqlite3 — 每个 app 的 OS 状态快照

Redis（任务队列）

生产节点使用 Redis 作为 Agent 循环的任务队列。

代码证据：

  • 节点配置：redis (:6379)，凭据见部署文档
  • kernel/runtime/queue_engine.py — 队列引擎抽象

FAISS（向量检索）

本地向量存储，用于语义搜索和知识检索。

代码证据：

  • server/shared/pyproject.toml — "faiss-cpu>=1.8"
  • server/shared/ports_impl/vector_store_faiss.py — FAISS 向量存储实现

Qdrant（可选向量数据库）

外部向量数据库，作为 FAISS 的替代方案。

代码证据：

  • server/shared/pyproject.toml — "qdrant-client>=1.9"（可选依赖）
  • server/shared/ports_impl/vector_store_qdrant.py — Qdrant 客户端实现

5. AI / LLM

OpenAI SDK（LLM 推理）

LLM 调用统一通过 OpenAI SDK，支持 OpenAI 和本地模型（Ollama）。

代码证据：

  • server/shared/pyproject.toml — "openai>=1.0"
  • server/shared/ports_impl/llm_provider.py — LLM 提供者抽象
  • 环境变量配置：OCTOPUS_LLM_MODE=openai|local, OCTOPUS_LLM_LOCAL_BASE_URL

sentence-transformers（嵌入生成）

本地嵌入模型，用于文档向量化和语义匹配。

代码证据：

  • server/shared/pyproject.toml — "sentence-transformers>=3.0"
  • server/shared/ports_impl/embedding_local.py — 本地 SentenceTransformers 嵌入

tiktoken（Token 计数）

OpenAI 的分词器，用于 Token 预算控制。

代码证据：

  • server/shared/pyproject.toml — "tiktoken>=0.7"

6. 浏览器与 GUI 自动化

Playwright（浏览器自动化）

Web 端 Screen 感知和操作，通过 Accessibility Tree 映射 UI 节点。

代码证据：

  • server/shared/ports_impl/screen_playwright.py — 40+ ARIA 角色映射到 28 种 NodeRole
  • kernel/contracts/screen_os.py — UINode, ScreenSnapshot, ActionCommand 等 46 个冻结类

pyautogui / UIA（桌面自动化）

桌面 GUI 操作，macOS 和 Windows 分别适配。

代码证据：

  • server/shared/ports_impl/screen_desktop/ — 桌面适配器目录
  • 测试文件：test_screen_desktop_mac_p3.py, test_screen_desktop_win_uia.py

Appium（移动自动化）

移动端 GUI 操作，Android 通过 UiAutomator2。

代码证据：

  • server/shared/ports_impl/screen_mobile/ — 移动适配器目录
  • 测试文件：test_screen_mobile_android_uia2.py

7. 文档与办公处理

库用途代码证据
python-docx>=1.1.0Word 文档读写server/shared/pyproject.toml
openpyxl>=3.1.2Excel 电子表格server/shared/pyproject.toml
python-pptx>=0.6.23PowerPoint 演示文稿server/shared/pyproject.toml
pdfplumber>=0.10.0PDF 文本提取server/shared/pyproject.toml
reportlab>=4.1.0PDF 生成server/shared/pyproject.toml
pytesseractOCR 文字识别server/shared/pyproject.toml（可选）
Jinja2>=3.1.2模板引擎server/shared/pyproject.toml

8. 数据科学与可视化

库用途代码证据
numpy>=1.26数值计算基础server/shared/pyproject.toml
matplotlib>=3.8图表渲染server/shared/pyproject.toml
yfinance>=0.2.33金融数据获取server/shared/pyproject.toml
datasketch>=1.6概率数据结构（MinHash/LSH）server/shared/pyproject.toml

9. 监控与运维

技术用途代码证据
Prometheus指标采集节点 :9090，mcp_tool_discovery/
Grafana指标仪表盘节点 :3000，凭据见部署文档
node-exporter主机指标节点 :9100
Sentry错误追踪sentry-sdk[fastapi]>=2.20
systemd服务管理9 个 systemd 服务单元
journald日志管理systemd 日志后端

10. DevOps 与基础设施

技术用途代码证据
Docker容器化运行58 个 MCP 服务器，部分为 Docker 镜像
Caddy反向代理 + HTTPS节点 :80/:443
Tailscale安全网络隧道节点网络层
GitPythonGit 操作server/shared/pyproject.toml — "GitPython>=3.1.40"
rsync + fswatch开发同步scripts/dev-sync.sh
nvmNode.js 版本管理主机工具链

11. 测试框架

框架层代码证据
pytest ≥8.0Python 全层kernel/pyproject.toml, server/shared/pyproject.toml
VitestWeb 前端products/web/package.json — "vitest"
React Testing Library组件测试products/web/package.json — "@testing-library/react"
jest + jest-expoMobileproducts/mobile/package.json
52 个 Gate ChecksKernel 质量门禁kernel/ops/gates.py

12. MCP 生态（Model Context Protocol）

Octopus 集成了 58 个 MCP 服务器，覆盖 6 大类：

类别数量示例
Core6filesystem, memory, git, fetch, time, brave-search
AWS26awslabs.* 命名空间（API、IAM、S3、EKS 等）
DevTools7github, playwright, terraform, cloudflare
Database4mongodb, mariadb, redis, redis-cloud
Communication5slack, notion, twilio, line-bot, mailgun
Business8sentry, stripe, paypal, hubspot, xero

治理三文件体系：

  • mcp-catalog.yaml — 发现目录
  • registry.yaml v2.0 — 策略（58 服务器，风险分级 LOW:6 / MEDIUM:14 / HIGH:27 / CRITICAL:11）
  • mcp-servers.json — 运行时执行配置

技术栈全景图

┌─────────────────────────────────────────────────────────┐
│                    Products Layer                        │
│  CLI(Python/argparse)  TUI(Textual)  Web(React/Vite)    │
│  Desktop(Tauri/Rust)   Mobile(Expo/React Native)        │
├─────────────────────────────────────────────────────────┤
│                    Server Layer                          │
│  FastAPI + Uvicorn │ httpx │ Pydantic │ SSE Streaming   │
│  28 route modules  │ 546 endpoints │ Bearer Auth        │
├─────────────────────────────────────────────────────────┤
│                    Shared Layer                           │
│  61 Capability Packages │ Dispatch Router │ Gate Valid.  │
│  SQLite │ FAISS │ Qdrant │ OpenAI │ sentence-transformers│
├─────────────────────────────────────────────────────────┤
│                    Kernel Layer                           │
│  Pure Python │ No I/O │ 552 Frozen Dataclasses          │
│  45+ Domains │ 34 Ports │ 52 Gates │ 12 Mixins         │
├─────────────────────────────────────────────────────────┤
│                    Infrastructure                        │
│  Redis │ Prometheus │ Grafana │ Caddy │ Docker │ systemd│
│  58 MCP Servers │ Tailscale │ NVIDIA GPU                │
└─────────────────────────────────────────────────────────┘
OctopusOS
How can we help?
Powered by OctopusOS