@starlink-awaken/agentmesh 1.0.3 → 1.2.0

package/docs/architecture.md

@@ -0,0 +1,138 @@
+# Architecture
+
+## System Overview
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Tool Consumers                         │
+│  Codex Desktop  Claude Code  Gemini CLI  Other Tools     │
+└────────────┬─────────────────────────────────────────────┘
+             │  /v1/chat/completions  /v1/responses
+             ▼
+┌──────────────────────────────────────────────────────────┐
+│                 Agent Mesh Gateway :3000                   │
+│                                                           │
+│  ┌──────────────────┐    ┌──────────────────────┐       │
+│  │  Model Gateway    │    │  Agent Orchestrator   │       │
+│  │  ┌──────────────┐ │    │  ┌──────────────────┐ │       │
+│  │  │ Quota Probe  │ │    │  │  Agent Registry  │ │       │
+│  │  │ (codexbar)   │ │    │  │  (25+ adapters)  │ │       │
+│  │  └──────┬───────┘ │    │  └────────┬─────────┘ │       │
+│  │         │         │    │           │           │       │
+│  │  ┌──────┴───────┐ │    │  ┌────────┴─────────┐ │       │
+│  │  │ Model Router │ │    │  │  Task Router     │ │       │
+│  │  │ (fallback)   │ │    │  │  (keyword match) │ │       │
+│  │  └──────┬───────┘ │    │  └────────┬─────────┘ │       │
+│  │         │         │    │           │           │       │
+│  │  ┌──────┴───────┐ │    │  ┌────────┴─────────┐ │       │
+│  │  │Provider Client│ │    │  │ Event Bus        │ │       │
+│  │  │(HTTP Stream) │ │    │  │ (Pub/Sub)        │ │       │
+│  │  └──────────────┘ │    │  └──────────────────┘ │       │
+│  └──────────────────┘    └──────────────────────┘       │
+│                                                           │
+│  ┌──────────────────────────────────────────────────┐    │
+│  │              Context Manager                       │    │
+│  │  Shared Spaces  File Cache  Vector Store (ChromaDB)│    │
+│  └──────────────────────────────────────────────────┘    │
+└──────────┬───────────────────────────────────────────────┘
+           │
+    ┌──────┼──────┬──────────┐
+    ▼      ▼      ▼          ▼
+  DeepSeek OpenAI OpenRouter Ollama
+```
+
+## Model Gateway Layer
+
+### Quota Probe (`quota.ts`)
+- Calls `codexbar usage --format json --provider all`
+- Caches results for 60 seconds
+- Parses provider-specific quota formats:
+  - codex: credits.remaining
+  - deepseek: balance in ¥ (from resetDescription)
+  - openrouter: openRouterUsage.balance
+  - ollama: always available
+
+### Model Router (`router.ts`)
+- `resolveProvider(model)`: determines which provider to use
+- Priority: model_routing config → fallback_chain → first available
+- Checks quota availability via `isProviderAvailable()`
+- Checks API key availability via env vars or config
+
+### Provider Client (`providers.ts`)
+- `callChatCompletions()`: unified OpenAI-compatible client
+- `callResponsesApi()`: converts Responses API → Chat Completions
+  - Extracts messages from `input` array
+  - Maps `input_text`/`output_text` content types
+  - Preserves tool definitions
+
+### Routes (`routes.ts`)
+- `GET /v1/models`: aggregated model list
+- `POST /v1/chat/completions`: proxy with streaming support
+- `POST /v1/responses`: Codex Desktop adapter
+- `GET /model-gateway/health`: quota-aware health check
+- `GET /model-gateway/quota`: full quota details
+
+## Agent Orchestration Layer
+
+### Agent Registry
+- Manages 25+ agent adapters
+- Capability-based agent discovery
+- Health check monitoring
+
+### Task Router
+- Keyword-based task-to-agent routing
+- Priority-based rule matching
+- Broadcast support for multi-agent tasks
+
+### Context Manager
+- Shared spaces with file persistence
+- Message history per space
+- Artifact storage
+
+## Data Flow
+
+### Chat Completions Flow
+```
+1. Client → POST /v1/chat/completions { model, messages }
+2. Router: parse model → check routing config → check quota → select provider
+3. Provider Client: POST to provider API with streaming
+4. Response: SSE stream or JSON → Client
+```
+
+### Codex Desktop Flow
+```
+1. Codex Desktop → POST /v1/responses { input: [...], model }
+2. Adapter: convert input items → messages array
+3. Router: resolve provider (same as chat completions)
+4. Provider Client: POST /v1/chat/completions to provider
+5. Adapter: convert chat response → responses format (output items)
+6. Response → Codex Desktop
+```
+
+### Quota Refresh Flow
+```
+1. First API call triggers quota probe
+2. codexbar subprocess runs (~10-30s)
+3. Results parsed and cached (60s TTL)
+4. Router uses cached data for decisions
+5. After 60s, next request triggers refresh
+```
+
+## Technology Stack
+
+- **Runtime**: Bun (>=1.0.0)
+- **Server**: Fastify 5
+- **HTTP Client**: Native Fetch API
+- **Streaming**: Server-Sent Events (SSE)
+- **WebSocket**: Fastify WebSocket plugin
+- **Vector Store**: ChromaDB (optional)
+- **Logging**: Custom structured logger + Pino
+- **Config**: YAML
+
+## Design Decisions
+
+1. **All providers via OpenAI-compatible API**: Avoids per-provider client complexity
+2. **Quota caching**: codexbar is slow, 60s cache prevents latency spikes
+3. **Streaming passthrough**: Zero-copy SSE forwarding for efficiency
+4. **No additional deps for model gateway**: Uses Bun's built-in Fetch API
+5. **codexbar as quota source**: Already aggregates 30+ providers, no duplicate logic

package/docs/configuration.md

@@ -0,0 +1,188 @@
+# Configuration Guide
+
+## Config File
+
+Default location: `config/gateway.yaml`
+
+## Full Configuration Reference
+
+```yaml
+# Server
+port: 3000
+wsPort: 3001
+host: "0.0.0.0"
+dataDir: "./data"
+logDir: "./logs"
+logLevel: "info"  # debug | info | warn | error
+
+# =============================================================================
+# Model Gateway
+# =============================================================================
+models:
+  default_model: deepseek-chat
+
+  providers:
+    deepseek:
+      base_url: https://api.deepseek.com/v1
+      api_key_env: DEEPSEEK_API_KEY     # 从环境变量读取
+      models:
+        - deepseek-chat
+        - deepseek-reasoner
+        - deepseek-v4-pro
+        - deepseek-v4-flash
+
+    openai:
+      base_url: https://api.openai.com/v1
+      api_key_env: OPENAI_API_KEY
+      models:
+        - gpt-5.1
+        - gpt-5.1-codex
+        - o4-mini
+
+    openrouter:
+      base_url: https://openrouter.ai/api/v1
+      api_key_env: OPENROUTER_API_KEY
+
+    ollama:
+      base_url: http://127.0.0.1:11434/v1
+      api_key: ollama                    # 直接指定 key
+      models:
+        - qwen3:14b
+        - codestral:22b
+
+  # Provider 优先级（从高到低）
+  fallback_chain:
+    - deepseek
+    - openrouter
+    - ollama
+
+  # 模型名匹配规则
+  model_routing:
+    "deepseek":        # 匹配包含 "deepseek" 的模型名
+      - deepseek
+    "gpt-":            # GPT 系列优先 openai，配额不够用 deepseek
+      - openai
+      - deepseek
+    "o1":              # 推理模型
+      - openai
+      - deepseek
+    "claude":          # Claude 通过 OpenRouter
+      - openrouter
+
+# =============================================================================
+# Agent Configuration
+# =============================================================================
+routing:
+  defaultAgent: "claude-code"
+  rules:
+    - name: code-generation
+      keywords: [write code, generate code, 写代码, 生成代码]
+      agent: claude-code
+      priority: 10
+
+    - name: code-review
+      keywords: [review, code review, 代码审查]
+      agent: claude-code
+      priority: 15
+
+    - name: browser-automation
+      keywords: [browser, scrape, 浏览器, 爬虫]
+      agent: openclaw
+      priority: 15
+
+    - name: multi-agent
+      keywords: [collaborate, team, 协作]
+      strategy: broadcast
+      agents: [claude-code, openclaw]
+      priority: 20
+
+agents:
+  - id: claude-code
+    name: Claude Code
+    type: claude-code
+    capabilities: [code-generation, code-review, debugging, refactoring]
+
+  - id: openclaw
+    name: OpenClaw
+    type: openclaw
+    capabilities: [browser-automation, web-scraping, ui-testing]
+```
+
+## API Key Configuration
+
+API Keys can be set in three ways:
+
+### 1. `.env` file (recommended)
+```
+DEEPSEEK_API_KEY=sk-xxx
+OPENAI_API_KEY=sk-xxx
+OPENROUTER_API_KEY=sk-xxx
+```
+
+### 2. Environment variables
+```bash
+export DEEPSEEK_API_KEY=sk-xxx
+```
+
+### 3. Inline in config (ollama only)
+```yaml
+providers:
+  ollama:
+    api_key: ollama  # local, no real key needed
+```
+
+### Key Resolution Order
+1. Inline `api_key` in config
+2. Environment variable via `api_key_env`
+3. Not found → provider skipped
+
+## Provider Configuration
+
+### Adding a new provider
+
+```yaml
+models:
+  providers:
+    my-provider:
+      base_url: https://api.my-provider.com/v1
+      api_key_env: MY_PROVIDER_API_KEY
+      models: [my-model-v1, my-model-v2]
+
+  fallback_chain:
+    - deepseek
+    - my-provider     # add to chain
+    - ollama
+
+  model_routing:
+    "my-model":       # route by model name
+      - my-provider
+```
+
+### Provider Requirements
+- Must implement OpenAI-compatible `/v1/chat/completions` endpoint
+- Must support Bearer token authentication
+- Optional: supports SSE streaming
+
+## Adding a new Agent
+
+```yaml
+agents:
+  - id: my-agent
+    name: My Custom Agent
+    type: process
+    command: my-agent-cli
+    args: ["--interactive"]
+    capabilities:
+      - my-capability-1
+      - my-capability-2
+```
+
+## Logging
+
+Logs are written to `logs/agentmesh-YYYY-MM-DD.log`.
+
+Log levels:
+- `debug` — verbose provider calls, routing decisions
+- `info` — startup, quota refresh, provider selection
+- `warn` — fallback triggered, quota probe failures
+- `error` — provider errors, crashes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlink-awaken/agentmesh",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Unified Agent Gateway - Multi-Agent Scheduler and Router",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,8 @@
     "cli": "bun run src/cli.ts",
     "build": "tsc",
     "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
   "engines": {

package/dist/cli.js

@@ -1,246 +0,0 @@
-#!/usr/bin/env bun
-const BASE_URL = process.env.AGENT_GATEWAY_URL || 'http://localhost:3000';
-async function request(path, options) {
-    const response = await fetch(`${BASE_URL}${path}`, {
-        ...options,
-        headers: {
-            'Content-Type': 'application/json',
-            ...options?.headers
-        }
-    });
-    if (!response.ok) {
-        const error = await response.json().catch(() => ({ message: 'Unknown error' }));
-        throw new Error(`HTTP ${response.status}: ${JSON.stringify(error)}`);
-    }
-    return response.json();
-}
-// 命令
-const commands = {
-    // 列出所有 Agent
-    async listAgents() {
-        const agents = await request('/agents');
-        console.log('\n📋 可用 Agent:\n');
-        agents.forEach(agent => {
-            console.log(`  ${agent.id.padEnd(15)} ${agent.name.padEnd(20)} [${agent.status}]`);
-            console.log(`    能力: ${agent.capabilities.join(', ')}\n`);
-        });
-    },
-    // 提交任务
-    async submitTask(args) {
-        const task = args.join(' ');
-        if (!task) {
-            console.error('❌ 请提供任务描述');
-            process.exit(1);
-        }
-        console.log(`\n📤 提交任务: ${task}\n`);
-        const message = {
-            type: 'request',
-            source: 'cli',
-            target: 'gateway',
-            payload: {
-                task,
-                options: {
-                    stream: false,
-                    timeout: 300
-                }
-            }
-        };
-        const result = await request('/tasks', {
-            method: 'POST',
-            body: JSON.stringify(message)
-        });
-        console.log(`✅ 任务已提交: ${result.task_id}`);
-        console.log(`   状态: ${result.status}\n`);
-        // 轮询获取结果
-        console.log('Waiting for result...\n');
-        let completed = false;
-        let attempts = 0;
-        const maxAttempts = 60;
-        while (!completed && attempts < maxAttempts) {
-            await new Promise(resolve => setTimeout(resolve, 2000));
-            const taskResult = await request(`/tasks/${result.task_id}`);
-            if (taskResult.status === 'completed') {
-                completed = true;
-                console.log('✅ 任务完成!\n');
-                console.log('📊 结果:');
-                if (typeof taskResult.result === 'object') {
-                    Object.entries(taskResult.result).forEach(([agent, res]) => {
-                        console.log(`\n--- ${agent} ---`);
-                        console.log(res);
-                    });
-                }
-                else {
-                    console.log(taskResult.result);
-                }
-            }
-            else if (taskResult.status === 'failed') {
-                completed = true;
-                console.log('❌ 任务失败!');
-                console.log('错误:', taskResult.error);
-            }
-            else {
-                attempts++;
-                process.stdout.write('.');
-            }
-        }
-        if (!completed) {
-            console.log('\n⚠️ 任务超时\n');
-        }
-    },
-    // 提交到指定 Agent
-    async submitToAgent(agentId, args) {
-        const task = args.join(' ');
-        if (!task) {
-            console.error('❌ 请提供任务描述');
-            process.exit(1);
-        }
-        console.log(`\n📤 提交任务到 ${agentId}: ${task}\n`);
-        const message = {
-            type: 'request',
-            source: 'cli',
-            target: agentId,
-            payload: {
-                task,
-                options: {
-                    stream: false,
-                    timeout: 300
-                }
-            }
-        };
-        const result = await request('/tasks', {
-            method: 'POST',
-            body: JSON.stringify(message)
-        });
-        console.log(`✅ 任务已提交: ${result.task_id}`);
-        console.log(`   状态: ${result.status}\n`);
-        // 轮询获取结果
-        console.log('⏳ 等待执行结果...\n');
-        let completed = false;
-        let attempts = 0;
-        const maxAttempts = 60;
-        while (!completed && attempts < maxAttempts) {
-            await new Promise(resolve => setTimeout(resolve, 2000));
-            const taskResult = await request(`/tasks/${result.task_id}`);
-            if (taskResult.status === 'completed') {
-                completed = true;
-                console.log('\n✅ 任务完成!\n');
-                console.log('📊 结果:');
-                console.log(taskResult.result);
-            }
-            else if (taskResult.status === 'failed') {
-                completed = true;
-                console.log('\n❌ 任务失败!');
-                console.log('错误:', taskResult.error);
-            }
-            else {
-                attempts++;
-                process.stdout.write('.');
-            }
-        }
-        if (!completed) {
-            console.log('\n⚠️ 任务超时\n');
-        }
-    },
-    // 创建共享空间
-    async createSpace() {
-        const result = await request('/spaces', {
-            method: 'POST',
-            body: JSON.stringify({ metadata: { createdBy: 'cli' } })
-        });
-        console.log(`\n✅ 共享空间已创建: ${result.space_id}\n`);
-        return result.space_id;
-    },
-    // 列出任务
-    async listTasks() {
-        const tasks = await request('/tasks');
-        console.log('\n📋 任务列表:\n');
-        if (tasks.length === 0) {
-            console.log('  (无任务)\n');
-            return;
-        }
-        tasks.forEach(task => {
-            console.log(`  ${task.id?.slice(0, 8) || 'unknown'}...  ${task.status?.padEnd(10) || 'unknown'} ${new Date(task.created_at).toLocaleString()}`);
-        });
-        console.log('');
-    },
-    // 健康检查
-    async health() {
-        const result = await request('/health');
-        console.log('\n🔍 Gateway 状态:\n');
-        console.log(`  状态: ${result.status}`);
-        console.log(`  Agent 数量: ${result.agents?.length || 0}`);
-        console.log(`  时间: ${new Date(result.timestamp).toLocaleString()}\n`);
-    }
-};
-// 主入口
-async function main() {
-    const args = process.argv.slice(2);
-    if (args.length === 0) {
-        console.log(`
-🤖 Agent Gateway CLI
-
-用法:
-  agent-gateway <command> [options]
-
-命令:
-  agents, list              列出所有可用 Agent
-  task <description>        提交通用任务（自动路由）
-  to <agent> <task>        提交任务到指定 Agent
-  space, create-space       创建共享空间
-  tasks, list-tasks         列出所有任务
-  health, status            检查 Gateway 状态
-
-示例:
-  agent-gateway agents
-  agent-gateway task 帮我写一个排序算法
-  agent-gateway to claude-code 帮我review这段代码
-  agent-gateway health
-`);
-        process.exit(0);
-    }
-    const command = args[0];
-    const commandArgs = args.slice(1);
-    try {
-        switch (command) {
-            case 'agents':
-            case 'list':
-            case 'ls':
-                await commands.listAgents();
-                break;
-            case 'task':
-                await commands.submitTask(commandArgs);
-                break;
-            case 'to':
-                if (commandArgs.length < 2) {
-                    console.error('用法: agent-gateway to <agent> <task>');
-                    process.exit(1);
-                }
-                const agentId = commandArgs[0];
-                if (agentId) {
-                    await commands.submitToAgent(agentId, commandArgs.slice(1));
-                }
-                break;
-            case 'space':
-            case 'create-space':
-                await commands.createSpace();
-                break;
-            case 'tasks':
-            case 'list-tasks':
-                await commands.listTasks();
-                break;
-            case 'health':
-            case 'status':
-                await commands.health();
-                break;
-            default:
-                console.error(`❌ 未知命令: ${command}`);
-                console.log('运行 agent-gateway 查看帮助');
-                process.exit(1);
-        }
-    }
-    catch (error) {
-        console.error(`\n❌ 错误: ${error.message}\n`);
-        process.exit(1);
-    }
-}
-main();