docs: add comprehensive component documentation and index
Co-authored-by: jcarvajalantigua <54653531+jcarvajalantigua@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
parent
87241dbb7a
commit
901b45b3ea
883
docs/COMPONENTS.md
Normal file
883
docs/COMPONENTS.md
Normal file
@ -0,0 +1,883 @@
|
||||
# Components Documentation
|
||||
|
||||
## Table of Contents
|
||||
1. [Overview](#overview)
|
||||
2. [Gateway Components](#gateway-components)
|
||||
3. [Agent Runtime Components](#agent-runtime-components)
|
||||
4. [Channel Components](#channel-components)
|
||||
5. [Tool Components](#tool-components)
|
||||
6. [Plugin System Components](#plugin-system-components)
|
||||
7. [Configuration Components](#configuration-components)
|
||||
8. [Storage Components](#storage-components)
|
||||
9. [Utility Components](#utility-components)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides detailed information about each component in the Jarvis system. Components are organized by layer and functionality.
|
||||
|
||||
---
|
||||
|
||||
## Gateway Components
|
||||
|
||||
### Server (`src/gateway/server.ts`)
|
||||
|
||||
**Purpose**: Main WebSocket server that handles all client connections and orchestration.
|
||||
|
||||
**Responsibilities**:
|
||||
- Accept WebSocket connections from clients
|
||||
- Route messages to appropriate handlers
|
||||
- Manage active chat sessions
|
||||
- Coordinate tool execution
|
||||
- Handle cron jobs and webhooks
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class GatewayServer {
|
||||
constructor(config: GatewayConfig);
|
||||
|
||||
async start(): Promise<void>;
|
||||
async stop(): Promise<void>;
|
||||
|
||||
registerChat(chat: ChatSession): void;
|
||||
unregisterChat(chatId: string): void;
|
||||
|
||||
async routeMessage(message: InboundMessage): Promise<void>;
|
||||
|
||||
getModelCatalog(): ModelCatalog;
|
||||
getBrowserTool(): BrowserTool;
|
||||
getDiscoveryService(): DiscoveryService;
|
||||
}
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
```yaml
|
||||
gateway:
|
||||
mode: local # 'local' or 'remote'
|
||||
port: 18789
|
||||
bind: loopback # 'loopback' or 'all'
|
||||
verbose: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Chat Registry (`src/gateway/chat-registry.ts`)
|
||||
|
||||
**Purpose**: Maintains registry of all active chat sessions.
|
||||
|
||||
**Responsibilities**:
|
||||
- Register new chat sessions
|
||||
- Track active sessions
|
||||
- Clean up inactive sessions
|
||||
- Provide session lookup
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class ChatRegistry {
|
||||
register(chat: ChatSession): void;
|
||||
unregister(chatId: string): void;
|
||||
|
||||
get(chatId: string): ChatSession | undefined;
|
||||
getAll(): ChatSession[];
|
||||
|
||||
findByChannel(channel: string): ChatSession[];
|
||||
findByUser(userId: string): ChatSession[];
|
||||
|
||||
cleanup(): void;
|
||||
}
|
||||
```
|
||||
|
||||
**Data Structure**:
|
||||
```typescript
|
||||
interface ChatSession {
|
||||
id: string;
|
||||
channel: string;
|
||||
userId: string;
|
||||
groupId?: string;
|
||||
|
||||
agent: AgentSession;
|
||||
context: SessionContext;
|
||||
|
||||
createdAt: number;
|
||||
lastActivityAt: number;
|
||||
|
||||
metadata: Record<string, unknown>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Model Catalog (`src/gateway/model-catalog.ts`)
|
||||
|
||||
**Purpose**: Maintains catalog of available AI models and their configurations.
|
||||
|
||||
**Responsibilities**:
|
||||
- List available models
|
||||
- Provide model configurations
|
||||
- Handle model authentication
|
||||
- Track model usage and costs
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class ModelCatalog {
|
||||
getAvailableModels(): ModelInfo[];
|
||||
getModel(modelId: string): ModelInfo | undefined;
|
||||
|
||||
getAuthProfile(modelId: string): AuthProfile;
|
||||
setAuthProfile(modelId: string, profile: AuthProfile): void;
|
||||
|
||||
getUsageStats(modelId: string): UsageStats;
|
||||
}
|
||||
```
|
||||
|
||||
**Model Info Structure**:
|
||||
```typescript
|
||||
interface ModelInfo {
|
||||
id: string;
|
||||
name: string;
|
||||
provider: 'anthropic' | 'openai' | 'google' | 'bedrock' | 'ollama';
|
||||
|
||||
capabilities: {
|
||||
vision: boolean;
|
||||
tools: boolean;
|
||||
streaming: boolean;
|
||||
};
|
||||
|
||||
limits: {
|
||||
maxTokens: number;
|
||||
contextWindow: number;
|
||||
rateLimit: RateLimit;
|
||||
};
|
||||
|
||||
pricing: {
|
||||
inputCostPer1k: number;
|
||||
outputCostPer1k: number;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Browser Tool (`src/gateway/browser-tool.ts`)
|
||||
|
||||
**Purpose**: Shared browser automation tool using Playwright.
|
||||
|
||||
**Responsibilities**:
|
||||
- Launch and manage browser instances
|
||||
- Execute browser automation tasks
|
||||
- Capture screenshots and PDFs
|
||||
- Handle browser profiles and cookies
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class BrowserTool {
|
||||
async launch(options: LaunchOptions): Promise<BrowserInstance>;
|
||||
async close(instanceId: string): Promise<void>;
|
||||
|
||||
async navigate(instanceId: string, url: string): Promise<void>;
|
||||
async screenshot(instanceId: string, options: ScreenshotOptions): Promise<Buffer>;
|
||||
async pdf(instanceId: string, options: PDFOptions): Promise<Buffer>;
|
||||
|
||||
async click(instanceId: string, selector: string): Promise<void>;
|
||||
async type(instanceId: string, selector: string, text: string): Promise<void>;
|
||||
async fill(instanceId: string, selector: string, value: string): Promise<void>;
|
||||
|
||||
async evaluate(instanceId: string, script: string): Promise<unknown>;
|
||||
async snapshot(instanceId: string): Promise<PageSnapshot>;
|
||||
}
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
```yaml
|
||||
tools:
|
||||
browser:
|
||||
enabled: true
|
||||
headless: true
|
||||
timeout: 30000
|
||||
viewport:
|
||||
width: 1280
|
||||
height: 720
|
||||
profiles:
|
||||
- name: default
|
||||
cookies: []
|
||||
localStorage: {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Discovery Service (`src/gateway/discovery.ts`)
|
||||
|
||||
**Purpose**: Service discovery using mDNS for local network.
|
||||
|
||||
**Responsibilities**:
|
||||
- Advertise gateway service
|
||||
- Discover other gateways
|
||||
- Handle service announcements
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class DiscoveryService {
|
||||
async advertise(service: ServiceInfo): Promise<void>;
|
||||
async stopAdvertise(): Promise<void>;
|
||||
|
||||
async discover(serviceType: string): Promise<ServiceInfo[]>;
|
||||
watch(serviceType: string, handler: ServiceHandler): void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Runtime Components
|
||||
|
||||
### Pi Agent Runner (`src/agents/pi-embedded-runner.ts`)
|
||||
|
||||
**Purpose**: Execute AI models in RPC mode with tool streaming.
|
||||
|
||||
**Responsibilities**:
|
||||
- Execute model requests
|
||||
- Stream tool calls and results
|
||||
- Handle model authentication
|
||||
- Manage failover on errors
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class PiAgentRunner {
|
||||
constructor(config: AgentConfig);
|
||||
|
||||
async* execute(
|
||||
session: SessionContext,
|
||||
message: string
|
||||
): AsyncGenerator<AgentEvent>;
|
||||
|
||||
async executeTools(
|
||||
session: SessionContext,
|
||||
tools: ToolCall[]
|
||||
): Promise<ToolResult[]>;
|
||||
|
||||
async streamResponse(
|
||||
session: SessionContext
|
||||
): AsyncGenerator<ResponseChunk>;
|
||||
}
|
||||
```
|
||||
|
||||
**Event Types**:
|
||||
```typescript
|
||||
type AgentEvent =
|
||||
| { type: 'tool_call', data: ToolCall }
|
||||
| { type: 'tool_result', data: ToolResult }
|
||||
| { type: 'text_chunk', data: string }
|
||||
| { type: 'thinking', data: string }
|
||||
| { type: 'error', data: Error };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Session Manager (`src/agents/session-manager.ts`)
|
||||
|
||||
**Purpose**: Manage agent session lifecycle and context.
|
||||
|
||||
**Responsibilities**:
|
||||
- Create and destroy sessions
|
||||
- Load and save session context
|
||||
- Manage message history
|
||||
- Handle session isolation
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class SessionManager {
|
||||
createSession(config: SessionConfig): AgentSession;
|
||||
destroySession(sessionId: string): void;
|
||||
|
||||
getSession(sessionId: string): AgentSession | undefined;
|
||||
getAllSessions(): AgentSession[];
|
||||
|
||||
async loadContext(sessionId: string): Promise<SessionContext>;
|
||||
async saveContext(sessionId: string, context: SessionContext): Promise<void>;
|
||||
|
||||
async addMessage(sessionId: string, message: Message): Promise<void>;
|
||||
async getMessages(sessionId: string, limit: number): Promise<Message[]>;
|
||||
}
|
||||
```
|
||||
|
||||
**Session Context**:
|
||||
```typescript
|
||||
interface SessionContext {
|
||||
sessionId: string;
|
||||
chatId: string;
|
||||
channel: string;
|
||||
|
||||
messages: Message[];
|
||||
maxTokens: number;
|
||||
|
||||
model: string;
|
||||
temperature: number;
|
||||
thinkingMode: 'low' | 'high' | 'always';
|
||||
|
||||
availableTools: Tool[];
|
||||
toolResults: ToolResult[];
|
||||
|
||||
memory: MemoryStore;
|
||||
skills: Skill[];
|
||||
|
||||
metadata: Record<string, unknown>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Tool Registry (`src/agents/tool-registry.ts`)
|
||||
|
||||
**Purpose**: Registry of available tools for agents.
|
||||
|
||||
**Responsibilities**:
|
||||
- Register tools
|
||||
- Validate tool schemas
|
||||
- Execute tool calls
|
||||
- Track tool usage
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class ToolRegistry {
|
||||
register(tool: Tool): void;
|
||||
unregister(toolName: string): void;
|
||||
|
||||
get(toolName: string): Tool | undefined;
|
||||
getAll(): Tool[];
|
||||
|
||||
async execute(
|
||||
toolName: string,
|
||||
params: unknown,
|
||||
context: ToolContext
|
||||
): Promise<ToolResult>;
|
||||
|
||||
validateParams(toolName: string, params: unknown): boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**Tool Interface**:
|
||||
```typescript
|
||||
interface Tool {
|
||||
name: string;
|
||||
description: string;
|
||||
schema: JSONSchema;
|
||||
|
||||
execute(params: unknown, context: ToolContext): Promise<ToolResult>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Model Auth (`src/agents/model-auth.ts`)
|
||||
|
||||
**Purpose**: Handle model authentication and token management.
|
||||
|
||||
**Responsibilities**:
|
||||
- Store API keys and OAuth tokens
|
||||
- Refresh expired tokens
|
||||
- Rotate auth profiles on failure
|
||||
- Secure credential storage
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class ModelAuth {
|
||||
async getAuthProfile(modelId: string): Promise<AuthProfile>;
|
||||
async setAuthProfile(modelId: string, profile: AuthProfile): Promise<void>;
|
||||
|
||||
async refreshToken(modelId: string): Promise<void>;
|
||||
async rotateProfile(modelId: string): Promise<void>;
|
||||
|
||||
async validateCredentials(modelId: string): Promise<boolean>;
|
||||
}
|
||||
```
|
||||
|
||||
**Auth Profile**:
|
||||
```typescript
|
||||
interface AuthProfile {
|
||||
type: 'api_key' | 'oauth';
|
||||
|
||||
// For API keys
|
||||
apiKey?: string;
|
||||
|
||||
// For OAuth
|
||||
accessToken?: string;
|
||||
refreshToken?: string;
|
||||
expiresAt?: number;
|
||||
|
||||
metadata: Record<string, unknown>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Channel Components
|
||||
|
||||
### Base Channel Interface (`src/channels/base.ts`)
|
||||
|
||||
**Purpose**: Common interface for all channel implementations.
|
||||
|
||||
**Responsibilities**:
|
||||
- Define channel lifecycle
|
||||
- Normalize messages
|
||||
- Handle errors gracefully
|
||||
|
||||
**Interface**:
|
||||
```typescript
|
||||
interface Channel {
|
||||
name: string;
|
||||
type: ChannelType;
|
||||
|
||||
// Lifecycle
|
||||
init(config: ChannelConfig): Promise<void>;
|
||||
start(): Promise<void>;
|
||||
stop(): Promise<void>;
|
||||
|
||||
// Messaging
|
||||
send(message: OutboundMessage): Promise<void>;
|
||||
receive(handler: MessageHandler): void;
|
||||
|
||||
// Status
|
||||
getStatus(): ChannelStatus;
|
||||
getConnections(): Connection[];
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### WhatsApp Channel (`src/whatsapp/`)
|
||||
|
||||
**Purpose**: WhatsApp integration using Baileys library.
|
||||
|
||||
**Key Files**:
|
||||
- `bot.ts` - Main bot implementation
|
||||
- `send.ts` - Message sending
|
||||
- `markdown.ts` - Markdown to WhatsApp formatting
|
||||
- `qr.ts` - QR code pairing
|
||||
|
||||
**Configuration**:
|
||||
```yaml
|
||||
channels:
|
||||
whatsapp:
|
||||
enabled: true
|
||||
pairing: code
|
||||
allowlist:
|
||||
- "+1234567890"
|
||||
session: main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Telegram Channel (`src/telegram/`)
|
||||
|
||||
**Purpose**: Telegram integration using grammY library.
|
||||
|
||||
**Key Files**:
|
||||
- `bot.ts` - Main bot implementation
|
||||
- `handlers.ts` - Message handlers
|
||||
- `markdown.ts` - Markdown to Telegram formatting
|
||||
- `keyboard.ts` - Inline keyboard support
|
||||
|
||||
**Configuration**:
|
||||
```yaml
|
||||
channels:
|
||||
telegram:
|
||||
enabled: true
|
||||
bot_token: "${TELEGRAM_BOT_TOKEN}"
|
||||
allowlist:
|
||||
- "username1"
|
||||
- "username2"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Signal Channel (`src/signal/`)
|
||||
|
||||
**Purpose**: Signal integration using signal-cli.
|
||||
|
||||
**Key Files**:
|
||||
- `bot.ts` - Main bot implementation
|
||||
- `cli.ts` - signal-cli wrapper
|
||||
- `send.ts` - Message sending
|
||||
|
||||
**Configuration**:
|
||||
```yaml
|
||||
channels:
|
||||
signal:
|
||||
enabled: true
|
||||
phone: "+1234567890"
|
||||
allowlist:
|
||||
- "+0987654321"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Discord Channel (`src/discord/`)
|
||||
|
||||
**Purpose**: Discord integration using discord.js.
|
||||
|
||||
**Key Files**:
|
||||
- `bot.ts` - Main bot implementation
|
||||
- `handlers.ts` - Event handlers
|
||||
- `markdown.ts` - Markdown to Discord formatting
|
||||
- `embeds.ts` - Rich embed support
|
||||
|
||||
**Configuration**:
|
||||
```yaml
|
||||
channels:
|
||||
discord:
|
||||
enabled: true
|
||||
bot_token: "${DISCORD_BOT_TOKEN}"
|
||||
dm:
|
||||
policy: pairing
|
||||
allowFrom: []
|
||||
guilds:
|
||||
- guild_id: "123456789"
|
||||
channels: ["general", "bot-commands"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Slack Channel (`src/slack/`)
|
||||
|
||||
**Purpose**: Slack integration using Bolt framework.
|
||||
|
||||
**Key Files**:
|
||||
- `bot.ts` - Main bot implementation
|
||||
- `handlers.ts` - Event handlers
|
||||
- `blocks.ts` - Block Kit formatting
|
||||
|
||||
**Configuration**:
|
||||
```yaml
|
||||
channels:
|
||||
slack:
|
||||
enabled: true
|
||||
bot_token: "${SLACK_BOT_TOKEN}"
|
||||
signing_secret: "${SLACK_SIGNING_SECRET}"
|
||||
dm:
|
||||
policy: pairing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Components
|
||||
|
||||
### Browser Tool (`src/browser/`)
|
||||
|
||||
**Purpose**: Web automation using Playwright.
|
||||
|
||||
**Key Files**:
|
||||
- `browser-tool.ts` - Main tool implementation
|
||||
- `playwright-bridge.ts` - Playwright wrapper
|
||||
- `snapshot.ts` - Page snapshot generation
|
||||
- `profiles.ts` - Browser profile management
|
||||
|
||||
**Tool Schema**:
|
||||
```typescript
|
||||
{
|
||||
name: "browser",
|
||||
description: "Automate web browsing",
|
||||
schema: {
|
||||
action: "navigate" | "click" | "type" | "screenshot",
|
||||
url?: string,
|
||||
selector?: string,
|
||||
text?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Canvas Tool (`src/canvas-host/`)
|
||||
|
||||
**Purpose**: Visual workspace with A2UI framework.
|
||||
|
||||
**Key Files**:
|
||||
- `index.ts` - Main canvas implementation
|
||||
- `a2ui/` - A2UI framework bundles
|
||||
- `renderer.ts` - DOM rendering
|
||||
- `websocket.ts` - Real-time updates
|
||||
|
||||
**Tool Schema**:
|
||||
```typescript
|
||||
{
|
||||
name: "canvas",
|
||||
description: "Create visual workspace",
|
||||
schema: {
|
||||
action: "create" | "update" | "render",
|
||||
content?: string,
|
||||
layout?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Bash Tool (`src/process/`)
|
||||
|
||||
**Purpose**: Execute shell commands safely.
|
||||
|
||||
**Key Files**:
|
||||
- `exec.ts` - Command execution
|
||||
- `spawn-utils.ts` - Process spawning utilities
|
||||
- `command-queue.ts` - Command queuing
|
||||
|
||||
**Tool Schema**:
|
||||
```typescript
|
||||
{
|
||||
name: "bash",
|
||||
description: "Execute shell commands",
|
||||
schema: {
|
||||
command: string,
|
||||
timeout?: number,
|
||||
cwd?: string,
|
||||
env?: Record<string, string>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Memory Tool (`src/memory/`)
|
||||
|
||||
**Purpose**: Store and retrieve contextual information.
|
||||
|
||||
**Key Files**:
|
||||
- `index.ts` - Main memory implementation
|
||||
- `vector-store.ts` - Vector embeddings
|
||||
- `cache.ts` - Caching layer
|
||||
|
||||
**Tool Schema**:
|
||||
```typescript
|
||||
{
|
||||
name: "memory",
|
||||
description: "Store and recall information",
|
||||
schema: {
|
||||
action: "store" | "recall" | "search",
|
||||
key?: string,
|
||||
value?: unknown,
|
||||
query?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plugin System Components
|
||||
|
||||
### Plugin Discovery (`src/plugins/discovery.ts`)
|
||||
|
||||
**Purpose**: Auto-detect and validate plugins.
|
||||
|
||||
**Responsibilities**:
|
||||
- Scan plugin directories
|
||||
- Validate manifests
|
||||
- Check dependencies
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class PluginDiscovery {
|
||||
async discoverPlugins(): Promise<PluginManifest[]>;
|
||||
async validateManifest(manifest: PluginManifest): Promise<boolean>;
|
||||
async checkDependencies(manifest: PluginManifest): Promise<boolean>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Plugin Loader (`src/plugins/loader.ts`)
|
||||
|
||||
**Purpose**: Load and initialize plugins.
|
||||
|
||||
**Responsibilities**:
|
||||
- Load plugin modules
|
||||
- Initialize plugins
|
||||
- Register hooks
|
||||
- Inject services
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class PluginLoader {
|
||||
async load(manifest: PluginManifest): Promise<Plugin>;
|
||||
async init(plugin: Plugin): Promise<void>;
|
||||
async start(plugin: Plugin): Promise<void>;
|
||||
async stop(plugin: Plugin): Promise<void>;
|
||||
|
||||
registerHooks(plugin: Plugin): void;
|
||||
injectServices(plugin: Plugin, services: PluginServices): void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Plugin Services (`src/plugins/services.ts`)
|
||||
|
||||
**Purpose**: Provide services to plugins.
|
||||
|
||||
**Services**:
|
||||
```typescript
|
||||
interface PluginServices {
|
||||
gateway: GatewayClient;
|
||||
config: ConfigProvider;
|
||||
logger: Logger;
|
||||
http: HttpClient;
|
||||
storage: StorageProvider;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Components
|
||||
|
||||
### Config Loader (`src/config/index.ts`)
|
||||
|
||||
**Purpose**: Load and validate configuration.
|
||||
|
||||
**Responsibilities**:
|
||||
- Load YAML configuration
|
||||
- Validate with Zod schemas
|
||||
- Merge environment variables
|
||||
- Handle migrations
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class ConfigLoader {
|
||||
async load(path: string): Promise<Config>;
|
||||
async validate(config: unknown): Promise<Config>;
|
||||
async save(path: string, config: Config): Promise<void>;
|
||||
|
||||
merge(configs: Partial<Config>[]): Config;
|
||||
migrate(oldConfig: unknown): Config;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Config Schema (`src/config/schema.ts`)
|
||||
|
||||
**Purpose**: Zod schemas for configuration validation.
|
||||
|
||||
**Schemas**:
|
||||
```typescript
|
||||
const ConfigSchema = z.object({
|
||||
gateway: GatewayConfigSchema,
|
||||
agents: AgentsConfigSchema,
|
||||
channels: ChannelsConfigSchema,
|
||||
tools: ToolsConfigSchema,
|
||||
sandbox: SandboxConfigSchema,
|
||||
plugins: PluginsConfigSchema,
|
||||
skills: SkillsConfigSchema,
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Path Manager (`src/config/paths.ts`)
|
||||
|
||||
**Purpose**: Manage system paths.
|
||||
|
||||
**Paths**:
|
||||
```typescript
|
||||
class PathManager {
|
||||
getConfigDir(): string;
|
||||
getCredentialsDir(): string;
|
||||
getSessionsDir(): string;
|
||||
getMediaDir(): string;
|
||||
getMemoryDir(): string;
|
||||
getLogsDir(): string;
|
||||
|
||||
resolve(relativePath: string): string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Storage Components
|
||||
|
||||
### Session Store (`src/sessions/`)
|
||||
|
||||
**Purpose**: Persist session data.
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class SessionStore {
|
||||
async create(session: SessionContext): Promise<void>;
|
||||
async read(sessionId: string): Promise<SessionContext>;
|
||||
async update(session: SessionContext): Promise<void>;
|
||||
async delete(sessionId: string): Promise<void>;
|
||||
|
||||
async addMessage(sessionId: string, message: Message): Promise<void>;
|
||||
async getMessages(sessionId: string, limit: number): Promise<Message[]>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Memory Store (`src/memory/`)
|
||||
|
||||
**Purpose**: Vector storage for contextual memory.
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class MemoryStore {
|
||||
async addEmbedding(key: string, embedding: number[]): Promise<void>;
|
||||
async searchEmbeddings(query: number[], k: number): Promise<SearchResult[]>;
|
||||
|
||||
async set(key: string, value: unknown): Promise<void>;
|
||||
async get(key: string): Promise<unknown>;
|
||||
async delete(key: string): Promise<void>;
|
||||
|
||||
async recall(query: string): Promise<MemoryResult[]>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Utility Components
|
||||
|
||||
### Logger (`src/logger.ts`)
|
||||
|
||||
**Purpose**: Structured logging with tslog.
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class Logger {
|
||||
debug(message: string, ...args: unknown[]): void;
|
||||
info(message: string, ...args: unknown[]): void;
|
||||
warn(message: string, ...args: unknown[]): void;
|
||||
error(message: string, ...args: unknown[]): void;
|
||||
|
||||
child(name: string): Logger;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Terminal Utils (`src/terminal/`)
|
||||
|
||||
**Purpose**: Terminal UI utilities.
|
||||
|
||||
**Key Files**:
|
||||
- `palette.ts` - Color palette
|
||||
- `table.ts` - Table formatting
|
||||
- `progress.ts` - Progress bars
|
||||
|
||||
---
|
||||
|
||||
### Markdown Utils (`src/markdown/`)
|
||||
|
||||
**Purpose**: Markdown parsing and rendering.
|
||||
|
||||
**Key APIs**:
|
||||
```typescript
|
||||
class MarkdownUtils {
|
||||
parse(markdown: string): MarkdownNode[];
|
||||
render(nodes: MarkdownNode[]): string;
|
||||
|
||||
toHTML(markdown: string): string;
|
||||
toPlainText(markdown: string): string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**End of Components Documentation**
|
||||
356
docs/INDEX.md
Normal file
356
docs/INDEX.md
Normal file
@ -0,0 +1,356 @@
|
||||
# Índice de Documentación de Jarvis
|
||||
|
||||
## 📚 Documentación Completa del Proyecto
|
||||
|
||||
Este directorio contiene toda la documentación del proyecto Jarvis, un asistente personal de IA que se ejecuta en tus propios dispositivos.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Documentos Principales
|
||||
|
||||
### [README-ES.md](README-ES.md)
|
||||
**Documentación completa en español**
|
||||
|
||||
Incluye:
|
||||
- Visión general del proyecto
|
||||
- ¿Qué es Jarvis?
|
||||
- Arquitectura del sistema
|
||||
- Componentes principales
|
||||
- Canales de mensajería soportados
|
||||
- Tecnologías utilizadas
|
||||
- Sistema de plugins
|
||||
- Configuración y despliegue
|
||||
- Desarrollo
|
||||
- Estructura de directorios
|
||||
|
||||
📖 **Recomendado como punto de partida** para entender todo el proyecto.
|
||||
|
||||
---
|
||||
|
||||
### [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
**Documentación técnica de arquitectura**
|
||||
|
||||
Incluye:
|
||||
- Arquitectura de alto nivel
|
||||
- Componentes del sistema
|
||||
- Flujo de datos
|
||||
- Enrutamiento de mensajes
|
||||
- Modelo de ejecución de agentes
|
||||
- Arquitectura de plugins
|
||||
- Modelo de seguridad
|
||||
- Almacenamiento y persistencia
|
||||
- Arquitectura de red
|
||||
|
||||
📖 **Recomendado para desarrolladores** que necesitan entender la arquitectura técnica.
|
||||
|
||||
---
|
||||
|
||||
### [COMPONENTS.md](COMPONENTS.md)
|
||||
**Documentación de componentes individuales**
|
||||
|
||||
Incluye:
|
||||
- Componentes del Gateway
|
||||
- Componentes del Runtime de Agente
|
||||
- Componentes de Canales
|
||||
- Componentes de Herramientas
|
||||
- Componentes del Sistema de Plugins
|
||||
- Componentes de Configuración
|
||||
- Componentes de Almacenamiento
|
||||
- Componentes de Utilidades
|
||||
|
||||
📖 **Recomendado para desarrolladores** que trabajan en componentes específicos.
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentación por Categoría
|
||||
|
||||
### 🎯 Inicio Rápido
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [start/](start/) | Guías de inicio rápido y tutoriales |
|
||||
| [install/](install/) | Guías de instalación paso a paso |
|
||||
| [Getting Started](start/) | Guía para principiantes |
|
||||
|
||||
### ⚙️ Configuración
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [README-ES.md#configuración-y-despliegue](README-ES.md#configuración-y-despliegue) | Guía completa de configuración |
|
||||
| [gateway/](gateway/) | Configuración del Gateway |
|
||||
| [environment.md](environment.md) | Variables de entorno |
|
||||
|
||||
### 💬 Canales
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [channels/](channels/) | Documentación de todos los canales |
|
||||
| [README-ES.md#canales-de-mensajería](README-ES.md#canales-de-mensajería) | Lista de canales soportados |
|
||||
|
||||
### 🔐 Seguridad
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [security/](security/) | Guías de seguridad |
|
||||
| [ARCHITECTURE.md#security-model](ARCHITECTURE.md#security-model) | Modelo de seguridad |
|
||||
|
||||
### 🛠️ Desarrollo
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [README-ES.md#desarrollo](README-ES.md#desarrollo) | Guía de desarrollo |
|
||||
| [testing.md](testing.md) | Guías de testing |
|
||||
| [debugging.md](debugging.md) | Guías de depuración |
|
||||
|
||||
### 🔌 Plugins
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [plugins/](plugins/) | Documentación de plugins |
|
||||
| [ARCHITECTURE.md#plugin-architecture](ARCHITECTURE.md#plugin-architecture) | Arquitectura de plugins |
|
||||
|
||||
### 🤖 Conceptos de IA
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [concepts/](concepts/) | Conceptos fundamentales |
|
||||
| [README-ES.md#tecnologías-utilizadas](README-ES.md#tecnologías-utilizadas) | Modelos IA soportados |
|
||||
|
||||
### 🖥️ Plataformas
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [platforms/](platforms/) | Guías específicas de plataforma |
|
||||
| macOS | Documentación de macOS |
|
||||
| iOS | Documentación de iOS |
|
||||
| Android | Documentación de Android |
|
||||
|
||||
### 📚 Referencia
|
||||
|
||||
| Documento | Descripción |
|
||||
|-----------|-------------|
|
||||
| [reference/](reference/) | Documentación de referencia |
|
||||
| [cli/](cli/) | Referencia de comandos CLI |
|
||||
| [tools/](tools/) | Referencia de herramientas |
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ Mapa de Navegación
|
||||
|
||||
### Para Nuevos Usuarios
|
||||
|
||||
1. **Empezar aquí**: [README-ES.md](README-ES.md) - Visión general completa
|
||||
2. **Instalar**: [install/](install/) - Guías de instalación
|
||||
3. **Configurar**: [README-ES.md#configuración-y-despliegue](README-ES.md#configuración-y-despliegue)
|
||||
4. **Usar**: [start/](start/) - Guías de uso básico
|
||||
|
||||
### Para Desarrolladores
|
||||
|
||||
1. **Arquitectura**: [ARCHITECTURE.md](ARCHITECTURE.md) - Entender el sistema
|
||||
2. **Componentes**: [COMPONENTS.md](COMPONENTS.md) - Componentes individuales
|
||||
3. **Desarrollo**: [README-ES.md#desarrollo](README-ES.md#desarrollo) - Setup de desarrollo
|
||||
4. **Testing**: [testing.md](testing.md) - Guías de testing
|
||||
|
||||
### Para Crear Plugins
|
||||
|
||||
1. **Sistema de Plugins**: [ARCHITECTURE.md#plugin-architecture](ARCHITECTURE.md#plugin-architecture)
|
||||
2. **Ejemplos**: [extensions/](../extensions/) - Plugins existentes
|
||||
3. **Plugin SDK**: Ver código en `src/plugin-sdk/`
|
||||
|
||||
---
|
||||
|
||||
## 📝 Estructura de Documentación
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README-ES.md # 📖 Documentación completa en español
|
||||
├── ARCHITECTURE.md # 🏗️ Arquitectura técnica
|
||||
├── COMPONENTS.md # 🔧 Componentes individuales
|
||||
├── INDEX.md # 📋 Este archivo (índice)
|
||||
│
|
||||
├── start/ # 🚀 Inicio rápido
|
||||
│ ├── getting-started.md
|
||||
│ └── wizard.md
|
||||
│
|
||||
├── install/ # 📦 Instalación
|
||||
│ ├── docker.md
|
||||
│ └── updating.md
|
||||
│
|
||||
├── channels/ # 💬 Canales
|
||||
│ ├── whatsapp.md
|
||||
│ ├── telegram.md
|
||||
│ ├── discord.md
|
||||
│ └── ...
|
||||
│
|
||||
├── gateway/ # 🌐 Gateway
|
||||
│ ├── configuration.md
|
||||
│ ├── security.md
|
||||
│ └── doctor.md
|
||||
│
|
||||
├── concepts/ # 💡 Conceptos
|
||||
│ ├── models.md
|
||||
│ ├── session.md
|
||||
│ ├── groups.md
|
||||
│ └── agent.md
|
||||
│
|
||||
├── cli/ # 💻 CLI
|
||||
│ └── commands.md
|
||||
│
|
||||
├── tools/ # 🛠️ Herramientas
|
||||
│ ├── browser.md
|
||||
│ ├── canvas.md
|
||||
│ └── skills.md
|
||||
│
|
||||
├── plugins/ # 🔌 Plugins
|
||||
│ └── development.md
|
||||
│
|
||||
├── security/ # 🔐 Seguridad
|
||||
│ └── best-practices.md
|
||||
│
|
||||
├── platforms/ # 🖥️ Plataformas
|
||||
│ ├── macos/
|
||||
│ ├── ios/
|
||||
│ ├── android/
|
||||
│ └── linux/
|
||||
│
|
||||
├── reference/ # 📚 Referencia
|
||||
│ └── RELEASING.md
|
||||
│
|
||||
├── automation/ # 🤖 Automatización
|
||||
├── debug/ # 🐛 Depuración
|
||||
├── diagnostics/ # 🔍 Diagnósticos
|
||||
├── nodes/ # 📡 Nodos
|
||||
├── providers/ # 🏢 Proveedores
|
||||
├── web/ # 🌐 Web UI
|
||||
│
|
||||
├── assets/ # 🎨 Assets
|
||||
├── images/ # 🖼️ Imágenes
|
||||
└── _layouts/ # 📄 Layouts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Búsqueda por Tema
|
||||
|
||||
### Instalación y Configuración
|
||||
- [Instalación](install/)
|
||||
- [Configuración](README-ES.md#configuración-y-despliegue)
|
||||
- [Variables de entorno](environment.md)
|
||||
- [Docker](install/docker.md)
|
||||
|
||||
### Canales de Mensajería
|
||||
- [Todos los canales](channels/)
|
||||
- [WhatsApp](channels/whatsapp.md)
|
||||
- [Telegram](channels/telegram.md)
|
||||
- [Discord](channels/discord.md)
|
||||
- [Signal](channels/signal.md)
|
||||
- [Slack](channels/slack.md)
|
||||
|
||||
### Desarrollo
|
||||
- [Setup de desarrollo](README-ES.md#desarrollo)
|
||||
- [Arquitectura](ARCHITECTURE.md)
|
||||
- [Componentes](COMPONENTS.md)
|
||||
- [Testing](testing.md)
|
||||
- [Debugging](debugging.md)
|
||||
|
||||
### Plugins y Extensiones
|
||||
- [Sistema de plugins](ARCHITECTURE.md#plugin-architecture)
|
||||
- [Desarrollo de plugins](plugins/)
|
||||
- [Plugins existentes](../extensions/)
|
||||
|
||||
### Herramientas
|
||||
- [Browser Tool](tools/browser.md)
|
||||
- [Canvas Tool](tools/canvas.md)
|
||||
- [Skills](tools/skills.md)
|
||||
|
||||
### Seguridad
|
||||
- [Modelo de seguridad](ARCHITECTURE.md#security-model)
|
||||
- [Mejores prácticas](security/best-practices.md)
|
||||
- [Gateway security](gateway/security.md)
|
||||
|
||||
### Plataformas
|
||||
- [macOS](platforms/macos/)
|
||||
- [iOS](platforms/ios/)
|
||||
- [Android](platforms/android/)
|
||||
- [Linux](platforms/linux/)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Diagramas
|
||||
|
||||
Los documentos incluyen varios diagramas ASCII para visualizar:
|
||||
|
||||
- **Arquitectura del Sistema**: [ARCHITECTURE.md](ARCHITECTURE.md#high-level-architecture)
|
||||
- **Flujo de Datos**: [ARCHITECTURE.md](ARCHITECTURE.md#data-flow)
|
||||
- **Flujo de Mensajes**: [README-ES.md](README-ES.md#arquitectura-del-sistema)
|
||||
- **Diagrama de Uso**: Ver README mejorado en raíz del proyecto
|
||||
- **Diagrama de Configuración**: Ver README mejorado en raíz del proyecto
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Enlaces Útiles
|
||||
|
||||
### Repositorio
|
||||
- **Código fuente**: https://github.com/jeturing/Jarvis
|
||||
- **Issues**: https://github.com/jeturing/Jarvis/issues
|
||||
- **Pull Requests**: https://github.com/jeturing/Jarvis/pulls
|
||||
- **Discussions**: https://github.com/jeturing/Jarvis/discussions
|
||||
|
||||
### Comunidad
|
||||
- **Discord**: (Añadir enlace si existe)
|
||||
- **Foro**: (Añadir enlace si existe)
|
||||
|
||||
### Recursos Externos
|
||||
- **Anthropic Claude**: https://www.anthropic.com/
|
||||
- **OpenAI GPT**: https://openai.com/
|
||||
- **Playwright**: https://playwright.dev/
|
||||
- **grammY (Telegram)**: https://grammy.dev/
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contribuir a la Documentación
|
||||
|
||||
¿Encontraste un error o quieres mejorar la documentación?
|
||||
|
||||
1. **Reporta issues**: [GitHub Issues](https://github.com/jeturing/Jarvis/issues)
|
||||
2. **Envía PRs**: Sigue las guías en [CONTRIBUTING.md](../CONTRIBUTING.md)
|
||||
3. **Discute mejoras**: [GitHub Discussions](https://github.com/jeturing/Jarvis/discussions)
|
||||
|
||||
### Guías para Contribuir
|
||||
|
||||
- Mantén un tono claro y profesional
|
||||
- Incluye ejemplos de código cuando sea posible
|
||||
- Añade diagramas ASCII para conceptos complejos
|
||||
- Actualiza el índice cuando añadas nuevos documentos
|
||||
- Verifica que todos los enlaces funcionen
|
||||
|
||||
---
|
||||
|
||||
## 📄 Licencia
|
||||
|
||||
La documentación está licenciada bajo la misma licencia MIT que el proyecto principal. Ver [LICENSE](../LICENSE).
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Actualizaciones Recientes
|
||||
|
||||
- **2024-01**: Creación de documentación completa en español
|
||||
- **2024-01**: Añadida documentación de arquitectura técnica
|
||||
- **2024-01**: Añadida documentación de componentes
|
||||
- **2024-01**: Creado índice de navegación
|
||||
|
||||
---
|
||||
|
||||
## 📧 Contacto
|
||||
|
||||
¿Necesitas más ayuda?
|
||||
|
||||
- **Email**: (Añadir email de contacto)
|
||||
- **Discord**: (Añadir enlace de Discord)
|
||||
- **Twitter**: (Añadir handle de Twitter)
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<strong>¡Feliz aprendizaje y desarrollo con Jarvis! 🤖</strong>
|
||||
</p>
|
||||
Loading…
Reference in New Issue
Block a user