@starlink-awaken/agentmesh 1.0.2 → 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.2",
+  "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": {