使用说明

Kortex：自主接口层

版权所有©2025 Pundarikaksh N Tripathi
该项目根据CC BY-NC-ND 4.0许可证获得许可。请参阅许可证文件以获取详细信息。

📖 引言

Kortex 是一种本地优先、跨平台的代理协议，旨在将意图与动作解耦。建立在 谷歌双子座3 Pro 和那个 **Google Go代理开发工具包（ADK）**Kortex充当用户和网络之间的智能层，能够自主导航、理解和执行复杂的任务。

想象一下，一个浏览器不仅显示页面理解他们。Kortex使用先进的视觉注入和可访问性树分析来与网络内容进行交互，就像人类一样，但以机器速度进行。

📑 目录

📖 引言
💡 解决方案及其工作原理
🏗️ 建筑
🛠️ 技术栈和工程决策
📂 目录结构
🚀 快速开始
🎨 桌面应用程序功能
🐳 Docker部署（Web版）
📚 核心组件
❓ 故障排除
🤝 贡献
📄 许可证

💡 解决方案及其工作原理

现代网络是复杂的。自动化它需要的不仅仅是脚本；它需要机构Kortex提供了一种强大的解决方案，弥合了人类意图和机器执行之间的差距。

运作原理

意图理解：键入目标（例如，“查找飞往东京的最便宜航班”）。Kortex使用 双子座3 Pro 理解语义并将其分解为逻辑步骤。
推理循环（重演）：Kortex进入“理性行为”循环。它查看浏览器的当前状态，决定下一步做什么（例如，“在搜索框中键入'Tokyo'”），并执行该操作。
视觉感知：与查看原始HTML的传统抓取器不同，Kortex构建了一个简化的 可访问性树这使它能够像屏幕阅读器或人类一样“看到”页面结构（按钮、输入、链接），使其对布局变化具有高度的弹性。
动作执行：使用 剧作家，Kortex与页面进行物理交互——点击、打字和滚动。它甚至在视觉上突出显示元素，以便您可以跟随。
记忆与语境：每个交互都存储在本地 SQLite矢量数据库这使得Kortex能够记住过去的搜索和偏好，在不将数据发送到云端的情况下提供个性化体验。

🏗️ 建筑

Kortex紧随其后 六边形架构（端口和适配器） 图案。这确保了我们的核心逻辑（“大脑”）与外部工具（“手”和“眼睛”）隔离开来，使系统模块化、可测试且易于扩展。

graph TD
    %% Styling
    classDef core fill:#ff9a9e,stroke:#333,stroke-width:2px,color:black;
    classDef infra fill:#a18cd1,stroke:#333,stroke-width:2px,color:black;
    classDef app fill:#fad0c4,stroke:#333,stroke-width:2px,color:black;
    classDef external fill:#84fab0,stroke:#333,stroke-width:2px,color:black;

    subgraph Application_Layer [Application Layer]
        direction TB
        Desktop[Desktop App\nWails v2 + React]:::app
        WebServer[Web Server\nFiber + WebSocket]:::app
    end

    subgraph Core_Domain [Core Domain (The Brain)]
        direction TB
        Logic[Business Logic\nReAct Loop]:::core
        Ports[Ports Interfaces\n(Abstractions)]:::core
    end

    subgraph Infrastructure_Layer [Infrastructure (Adapters)]
        direction TB
        AgentAdapter[Agent Adapter\nGoogle ADK + Gemini]:::infra
        BrowserAdapter[Browser Adapter\nPlaywright]:::infra
        VectorDB[Vector Store\nSQLite + Embeddings]:::infra
        FlightRecorder[Flight Recorder\nStructured Logger]:::infra
    end

    subgraph External_World [External World]
        User((User)):::external
        Web((Internet)):::external
        LLM((Gemini API)):::external
    end

    %% Connections
    User <-->|UI Events| Desktop
    User <-->|WebSocket| WebServer
    
    Desktop -->|Calls| AgentAdapter
    WebServer -->|Calls| AgentAdapter

    AgentAdapter -->|Implements| Ports
    BrowserAdapter -->|Implements| Ports
    VectorDB -->|Implements| Ports
    FlightRecorder -->|Implements| Ports

    Logic -->|Uses| Ports
    
    AgentAdapter <-->|API| LLM
    BrowserAdapter <-->|Navigates| Web

🛠️ 技术栈和工程决策

我们选择这个堆栈来平衡演出, 开发者体验，以及能力.

组件	技术	推理
语言	Go（高朗）	Go提供了卓越的并发性（goroutines），这对于同时处理多个浏览器上下文和代理线程至关重要。它是严格类型的，编译成一个二进制文件，并拥有一个庞大的生态系统。
桌面	腰围v2	与将整个Chrome浏览器捆绑在一起的Electron不同（RAM使用量很大），Wails使用操作系统的原生网络视图（Windows上的WebView2，macOS上的WebKit）。这导致二进制文件很小（~15MB对~100MB），内存占用很低
前端	React+Vite	React提供了一个易于管理的基于组件的UI。Vite提供闪电般快速的HMR（热模块更换），以获得出色的开发体验。
AI模型	双子座3 Pro	Gemini的大上下文窗口和多模式功能使其成为理解复杂网页和推理导航步骤的理想选择。
代理	谷歌ADK	Agent Development Kit提供了一种标准化的方法来构建代理、管理工具调用和状态转换可靠性。
浏览器	剧作家	Playwright比Selenium更快、更可靠。它支持现代网络功能，轻松处理动态内容（SPA），并允许轻松无头执行。
数据库	SQLite+Vec	我们使用SQLite作为本地优先的方法。这 `sqlite-vec` 扩展允许我们直接在用户的机器上执行向量相似性搜索，保持数据的私密性和快速性。

📂 目录结构

以下是项目结构的详细分解，以帮助您浏览代码库。

Kortex/
├── app.go                  # Wails Bridge: Connects Go backend to React frontend.
├── main.go                 # Desktop Entry Point: Initializes Wails application.
├── cmd/
│   └── web/
│       └── main.go         # Web Server Entry Point: Runs Kortex as a Docker/Web service.
├── frontend/               # User Interface (React)
│   ├── src/
│   │   ├── App.tsx         # Main Layout: Dual-pane interface (Chat + Terminal).
│   │   ├── components/     # UI Components (FlightRecorder, ChatBox, etc.).
│   │   └── wailsjs/        # Generated Bindings: Go functions callable from JS.
├── internal/               # Private Application Code
│   ├── core/
│   │   ├── domain/         # Data Models: Defines Session, Message, Memory structs.
│   │   └── ports/          # Interfaces: Defines contracts for Adapters (Hexagonal Arch).
│   ├── adapters/
│   │   └── agent/          # The Brain: Implements the ReAct loop and Gemini integration.
│   └── infra/
│       ├── browser/        # The Hands: Playwright implementation for browser control.
│       ├── logger/         # The Black Box: Structured logging for the Flight Recorder.
│       └── sqlite/         # The Memory: Vector database implementation.
├── build/                  # Build Artifacts: Icons, manifests, and compiled binaries.
├── Dockerfile              # Container Config: For running Kortex in Docker.
├── .env.example            # Config Template: API keys and environment settings.
└── go.mod                  # Dependencies: Go module definitions.

🚀 快速开始

先决条件

转到1.23+ 安装
Node.js 18+ 已安装npm

Wails CLI v2 安装：

go install github.com/wailsapp/wails/v2/cmd/wails@latest

剧作家浏览器 安装：

go run github.com/playwright-community/playwright-go/cmd/playwright@latest install --with-deps

Google Gemini API密钥 从谷歌人工智能工作室

安装

克隆存储库:

git clone https://github.com/PundarikakshNTripathi/Kortex.git
cd Kortex

安装Go依赖项:
```
go mod download
```
安装前端依赖项:
```
cd frontend
npm install
cd ..
```
设置环境变量:
```
cp .env.example .env
```
编辑 .env 并添加您的API密钥：
```
GOOGLE_API_KEY=your-actual-api-key-here
```

运行桌面应用程序

开发模式 （热重新加载）：

wails dev

生产建设:

wails build
.\build\bin\Kortex.exe  # Windows
./build/bin/Kortex      # macOS/Linux

运行测试

要验证核心功能：

go test -v ./...

测试运行时，您应该会看到一个Chromium窗口短暂弹出！

🎨 桌面应用程序功能

赛博朋克UI主题

深色模式：深空蓝色背景（#0a0e27）
霓虹色调：电青色（#00d9ff）和紫色（#a855f7）
玻璃态：具有模糊效果的半透明面板
平滑动画：淡入、滑入和脉冲效果
矩阵终端：任务控制中的扫描线效应

双窗格布局

┌─────────────────────────────────────────────────────────┐
│  ⚡ KORTEX - Autonomous Interface Layer                 │
├──────────────────────────┬──────────────────────────────┤
│                          │  ⚙ MISSION CONTROL           │
│  Chat Interface (60%)    │                              │
│                          │  Terminal View (40%)         │
│  - User messages         │  - Real-time logs            │
│  - Agent responses       │  - Color-coded levels        │
│  - Input field           │  - Auto-scroll               │
│  - Loading states        │  - Timestamps                │
│                          │                              │
└──────────────────────────┴──────────────────────────────┘

任务控制日志颜色

日志级别	颜色	图标	描述
NAVIGATE	青色	🔵	浏览器导航
单击	绿色	🟢	元素点击
类型	黄色	🟡	文本输入
高亮	洋红色	🟣	视觉反馈
GET_SNAPSHOT	蓝色	🔷	页面分析
规划	紫色	🟪	代理推理
INIT	青色	⚙️	初始化
用户	白色	📝	用户输入
错误	红色	❌	错误
完成	绿色	✅	任务完成

🐳 Docker部署（Web版）

Kortex也可以作为 web服务器 在Docker容器中，无需任何桌面设置即可通过WebSocket访问。

先决条件

码头工人 安装
Google Gemini API密钥 从谷歌人工智能工作室

构建Docker镜像

docker build -t kortex-web .

运行容器

基本用法：

docker run -p 8080:8080 \
  -e GOOGLE_API_KEY=your-api-key-here \
  -e HEADLESS=true \
  kortex-web

使用持久数据库：

docker run -p 8080:8080 \
  -e GOOGLE_API_KEY=your-api-key-here \
  -e HEADLESS=true \
  -v $(pwd)/data:/app/data \
  kortex-web

连接到WebSocket

端点： ws://localhost:8080/ws/chat

消息格式：

{
  "goal": "Navigate to google.com and search for AI news"
}

📚 核心组件

“大脑”：代理适配器(`internal/adapters/agent`)

Agent Adapter是Kortex的情报中心。它连接了以下推理能力 双子座 （通过ADK）具有 浏览器适配器.

重新激活循环：实现一个Reason Act循环，其中代理观察状态，考虑下一步，并执行一个工具。
谷歌ADK：用途 google.golang.org/adk 管理代理的生命周期、会话状态和工具执行。
工具:
- Navigate(url)：去一个网站。
- Click(selector)：与元素互动。
- Type(selector, text)：输入数据。
- Highlight(selector, message)：以视觉方式向用户传达意图。
- GetSnapshot()：阅读页面的可访问性树。
飞行记录器：记录每个工具的执行情况，以便调试和回放。

“手”：浏览器适配器(`internal/infra/browser`)

浏览器适配器是Kortex与世界互动的主要方式。使用 剧作家，它允许Kortex：

导航：打开和浏览网页。
看：生成一个简化的 辅助功能快照 将原始HTML转换为AI可以理解的角色和名称的结构化JSON树。
触摸：突出显示页面上的元素，向用户显示它正在看什么或做什么。

主要特点

视觉注射：Kortex注入自定义JavaScript，在元素周围绘制“青色/电蓝色”轮廓，并显示浮动工具提示。
```
// Example: Highlight the search bar with a message
browser.Highlight("#search-input", "I am typing here...")
```
韧性：内置的超时和错误处理可确保Kortex在未立即找到选择器时不会崩溃。
可见模式：跑步 Headless: false 默认模式下，您可以观看Kortex的工作。

“记忆”：核心和矢量存储(`internal/core`)

领域模型: Session, Message，以及 MemoryFragment 定义Kortex如何思考和记忆。
矢量存储器：使用余弦相似性搜索从过去的交互中检索相关上下文，赋予Kortex长期记忆。

❓ 故障排除

Q：桌面应用程序无法启动。

A.：确保已安装Wails CLI： go install github.com/wailsapp/wails/v2/cmd/wails@latest
跑 wails doctor 检查您的环境

Q：浏览器无法打开。

A.：确保您已运行Playwright install命令： go run github.com/playwright-community/playwright-go/cmd/playwright@latest install --with-deps

Q： “GOOGLE_API_KEY未设置”错误。

A.：创建一个 .env 根目录中带有API密钥的文件：
```
GOOGLE_API_KEY=your-api-key-here
```
从以下位置获取密钥谷歌人工智能工作室

Q：前端构建错误。

A.：删除 frontend/node_modules 然后跑 npm install 再次
确保你使用的是Node.js 18+

Q： “不支持矢量搜索”错误。

A.：当前实现使用纯Go SQLite驱动程序。要获得完整的矢量搜索功能，请确保 sqlite-vec 扩展已正确加载到您的环境中（或使用提供的mock/fallback进行基本测试）。

🤝 贡献

该项目遵循六边形架构模式。添加功能时：

在中定义接口 internal/core/ports/
在中实施适配器 internal/adapters/ 或 internal/infra/
更新Wails桥 app.go 如有需要
在中添加UI组件 frontend/src/components/

📄 许可证

该项目分布在 知识共享署名非商业性无衍生产品4.0国际版 许可证。

这意味着：

✅ 您可以查看和使用此代码进行学习
✅ 您可以分享此项目并注明出处
❌ 你不能在商业上使用它
❌ 您无法创建修改后的版本

看许可证查看完整的法律文本。

内置于❤️ 使用Wails v2、React、Go和Google Gemini

使用说明

Kortex：自主接口层

📖 引言

📑 目录

💡 解决方案及其工作原理

运作原理

🏗️ 建筑

🛠️ 技术栈和工程决策

📂 目录结构

🚀 快速开始

先决条件

安装

运行桌面应用程序

运行测试

🎨 桌面应用程序功能

赛博朋克UI主题

双窗格布局

任务控制日志颜色

🐳 Docker部署（Web版）

先决条件

构建Docker镜像

运行容器

连接到WebSocket

📚 核心组件

“大脑”：代理适配器(internal/adapters/agent)

“手”：浏览器适配器(internal/infra/browser)

主要特点

“记忆”：核心和矢量存储(internal/core)

❓ 故障排除

🤝 贡献

📄 许可证

相关 MCP

AI持久记忆服务器

Playwright服务器工具

文档转Markdown MCP服务器

文件转 Markdown 转换器

智能代理编排平台

AI模型网关

“大脑”：代理适配器(`internal/adapters/agent`)

“手”：浏览器适配器(`internal/infra/browser`)

“记忆”：核心和矢量存储(`internal/core`)