RavenAI

English | 中文

RavenAI is an AI-powered platform for development and testing workflows. It connects engineering commits, release package management, intelligent package retrieval, natural-language device operation, test log submission, and agentic log analysis into one closed loop.

RavenAI is domain-agnostic by design. Although it was originally conceived for the satellite communications domain, it has evolved into a general-purpose platform meant to carry the development and testing workflow of any project — and, through customization, it can even host agents for non-developer roles.

This repository is the top-level workspace for two major subprojects:

• RavenClient: an Electron-based desktop client built on Cherry Studio, providing MCP device operations, package creation, and AI workflows for developers and testers.
• RavenAIService: backend services for log staging, device-link orchestration, AI chat, asynchronous log processing, package management, and intelligent package search.

What RavenAI Solves

RavenAI is designed around the real R&D testing loop:

1. Developers submit code and evolve versions through Git.
2. A lightweight Release Note Agent reads Git history and automatically drafts release notes for package-management refactors.
3. Reconstructed package management supports package creation, upload, metadata extraction, search, and distribution.
4. Testers use natural language to operate test devices through RavenClient, ChatAgent, Device Link, MCP Server, device tools, and Python automation.
5. After testing, logs are submitted to RavenAIService and analyzed by LogAnalysisAgent to produce evidence, issue clues, and feedback for development.

R&D Testing Flow Comparison

Without Agent participation, the R&D testing flow relies on manual handoffs, manual package lookup, manual device operations, and manual log inspection:

%%{init: {"theme": "base", "flowchart": {"htmlLabels": true, "nodeSpacing": 24, "rankSpacing": 24, "curve": "basis"}, "themeVariables": {"fontFamily": "Arial, Microsoft YaHei", "primaryTextColor": "#0F172A", "lineColor": "#64748B"}}}%%

flowchart LR

A["Code Commit"] --> B["Manual Notes"]
B --> C["Package Handoff"]
C --> D["Package Search"]
D --> E["Device Ops"]
E --> F["Scattered Logs"]
F --> G["Manual Debug"]
G --> H["Fix"]

P1["Handoff Loops"] -.-> B
P2["Version Drift"] -.-> C
P3["High Barrier"] -.-> E
P4["Slow Debug"] -.-> G

classDef normal fill:#F8FAFC,stroke:#64748B,stroke-width:1.3px,color:#0F172A;
classDef manual fill:#FEF2F2,stroke:#DC2626,stroke-width:1.5px,color:#7F1D1D;
classDef pain fill:#FFF7ED,stroke:#EA580C,stroke-width:1.3px,color:#7C2D12;

class A,H normal;
class B,C,D,E,F,G manual;
class P1,P2,P3,P4 pain;

Loading

With RavenAI, Agents sit in the key friction points: release notes, package management, package retrieval, device control, and log analysis:

%%{init: {"theme": "base", "flowchart": {"htmlLabels": true, "nodeSpacing": 24, "rankSpacing": 24, "curve": "basis"}, "themeVariables": {"fontFamily": "Arial, Microsoft YaHei", "primaryTextColor": "#0F172A", "lineColor": "#475569"}}}%%

flowchart LR

A["Code Commit"] --> B["Agent Notes"]
B --> C["Agent Packages"]
C --> D["Agent Search"]
D --> E["Agent Device"]
E --> F["Log Staging"]
F --> G["Agent Analysis"]
G --> H["Fix"]

V1["Less Handoff"] -.-> B
V2["Lower Delivery"] -.-> C
V3["Lower Barrier"] -.-> E
V4["Faster Diagnosis"] -.-> G

classDef normal fill:#F8FAFC,stroke:#64748B,stroke-width:1.3px,color:#0F172A;
classDef agent fill:#F5F3FF,stroke:#7C3AED,stroke-width:1.7px,color:#1E1B4B;
classDef value fill:#ECFDF5,stroke:#059669,stroke-width:1.3px,color:#064E3B;
classDef repair fill:#FFF7ED,stroke:#EA580C,stroke-width:1.5px,color:#7C2D12;

class A,F normal;
class B,C,D,E,G agent;
class V1,V2,V3,V4 value;
class H repair;

Loading

Architecture Overview

Open Docs/raven-architecture.html and Docs/raven-agent-context.html in a browser for the interactive version with dark/light theme toggle and export.

System Technology Structure

• Client layer: RavenClient, Electron, React, MCP Client, package tools, DeviceLinkClient.
• AI orchestration layer: ChatAgent and LogAnalysisAgent built with the Claude Agent SDK and OpenAI-compatible LLM access.
• Service layer: FastAPI services in RavenAIService, Express-based package-server, and the Electron update-server.
• Communication and tasks: REST APIs, WebSocket Device Link, Celery, and Redis.
• Data and knowledge layer: uploaded packages, package metadata, log archives, database records, and FAISS vector indexes.
• Device tool layer: MCP Server, device-interface wrappers, and Python automation scripts for device operation and testing.

Key architectural highlights:

• Prompt layering: Agent-level base prompts (prompts_config.yaml) merged with Project-level appended prompts (data/project_prompts/<project_code>/system_prompt.md) before each run; edits take effect immediately.
• Skill layering (Claude Agent SDK): Agent-level skills (data/agent_skills/<agent>/store) and Project-level skills (data/project_skills/<project_code>/store) are materialized to .claude/skills/ before each run.
• Service ↔ Client reverse tunnel: Client connects outbound via WebSocket to Service:8085/ws/device-link; heartbeat ping/pong with exponential-backoff reconnect; no inbound port required on the device side.
• Secure repository access: LogAnalysis / BugFix / ProjectExpert Agents connect to repositories via SSH Key / Token with credential isolation; repositories are cloned as read-only copies.

Agent Context Layers and Assembly

Context for each Agent run is assembled from two layers before the Agent starts:

• Agent level (base layer): Keyed by agent name; shared across all projects. Prompts from prompts_config.yaml (claude_agent_<name>, zh/en locale). Skills from data/agent_skills/<agent>/store controlled by _registry.json.
• Project level (append layer): Isolated by project_code; activated when the user selects a project. Prompts from project_prompts/<code>/system_prompt.md (edit takes effect immediately). Skills from project_skills/<code>/store; same name overrides the Agent-level skill.
• Pre-run assembly: Final system prompt = base + project append + reply-language instruction. Skills are materialized to .claude/skills/ (Agent Skills first; project-level overrides same name). Repository is git cloned to <workspace>/repo/ (reused if .git already exists).
• Workspace <workspace>/: Contains the synthesized system_prompt, .claude/skills/<name>/, repo/ (read-only: Read/Grep/Glob/Bash/git), and task.json + logs/.

Repository Layout

RavenAI/
├── RavenClient/                 # Desktop client, package tooling, MCP and device workflows
├── RavenAIService/              # Backend services, log staging, AI analysis, package server
│   ├── app/                     # FastAPI application, agents, services, tasks
│   ├── frontend/                # Web frontend for service-side UI
│   └── package-server/          # Express package management and RAG search service
├── Docs/                        # Project documentation and feature notes
├── .gitmodules                  # Submodule definitions
└── README.md                    # This document

Quick Start

Clone the repository with submodules:

git clone --recurse-submodules <repo-url>
cd RavenAI

If the repository was cloned without submodules:

git submodule update --init --recursive

Start the backend log staging service:

cd RavenAIService
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8085 --reload

Start the package server:

cd RavenAIService/package-server
npm install
npm run dev

Start the desktop client:

cd RavenClient
yarn install
yarn dev

Key Services

• RavenAIService API: http://localhost:8085
• Package server: http://localhost:8083/raven
• Update server: RavenClient/update-server
• Desktop client: launched through Electron during yarn dev

Notes

The Release Note Agent mentioned in the workflow is part of the project process: it reads Git commit history and drafts release notes for the package-management refactor. It is included in the architecture description because it completes the R&D testing workflow, even though it is not represented as a full standalone module in this codebase.