elephant-ai

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

<p align="center">
  <img src="assets/banner.png" alt="elephant.ai banner" width="100%" />
</p>

<h1 align="center">elephant.ai</h1>

<p align="center">
  <strong>A leader agent for attention-heavy work.</strong><br/>
  Lives in Lark. Tracks what's moving, surfaces what matters, follows up automatically, and only pulls you in when judgment is needed.
</p>

<p align="center">
  <a href="https://github.com/cklxx/elephant.ai/actions/workflows/ci.yml"><img src="https://github.com/cklxx/elephant.ai/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
  <a href="https://goreportcard.com/report/github.com/cklxx/elephant.ai"><img src="https://goreportcard.com/badge/github.com/cklxx/elephant.ai" alt="Go Report Card"/></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"/></a>
  <a href="README.zh.md"><img src="https://img.shields.io/badge/文档-中文-blue.svg" alt="中文文档"/></a>
</p>

---

## What is elephant.ai?

A **leader agent** that lives in your Lark groups and DMs. It takes ownership of work — tracking progress, following up on tasks, surfacing what needs attention, and handling coordination. Behind the scenes it orchestrates specialist agents and tools. To you, it's one reliable operator who never drops the ball.

---

## Why a leader agent?

- **Continuous ownership** — Hand off a task and it stays tracked until done.
- **Attention gating** — Compresses noise into what matters, what's at risk, and what needs your call.
- **Proactive follow-up** — Chases status, summarizes results, escalates blockers automatically.
- **Coordination absorbed** — Handles the track/ask/remind/align overhead.
- **Persistent memory** — Remembers conversations, decisions, and context across weeks and months.
- **Approval gates** — Knows when to ask before acting. Risky operations require explicit sign-off.
- **MCP extensible** — Connect any external tool through the Model Context Protocol.
- **Lark-native** — WebSocket gateway, always present in groups and DMs.

---

## Quick Start

**Prerequisites:** Go 1.24+, Node.js 20+, a Lark bot token, and an LLM API key.

```bash
# 1. Clone and build
git clone https://github.com/cklxx/elephant.ai.git && cd elephant.ai
make build

# 2. Configure (LLM key + Lark credentials)
cp examples/config/runtime-config.yaml ~/.alex/config.yaml
export LLM_API_KEY="sk-..."
alex setup   # interactive first-run wizard

# 3. Start everything
alex dev up

# 4. Talk to it in Lark — or use the CLI directly
./alex "summarize the last 3 conversations and draft follow-up emails"
```

Full setup guide → [`docs/guides/quickstart.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/guides/quickstart.md)

---

## How It Works

```
You (Lark group or DM)
        ↓
  Chat (lightweight LLM, ~1-3s)      — instant reply, routing, ack
        │
        ├── direct reply ──────────▶ back to you immediately
        │
        └── dispatch ──▶ Worker (ReAct Agent, background, minutes)
                              ↓
                        Context Assembly · Memory · Policies
                              ↓
                        Think → Act → Observe → Tool Execution
                              ↓
                        Reply delivered to Lark (with progress updates)
```

---

## Leader Agent Features

The leader agent runs a background scheduler alongside Lark conversations. It monitors task health, generates digests, and surfaces decisions and blockers before they become problems.

| Feature | Description |
|---|---|
| **Blocker Radar** | Scans every 10 min for stale/blocked tasks. Auto-notifies with cooldown. |
| **Weekly Pulse** | Monday 9am digest: tasks completed, cycle time, token spend, success rate. |
| **Daily Summary** | End-of-day activity recap with top agents and key outcomes. |
| **1:1 Prep Brief** | Auto-generated talking points before meetings: wins, open items, blockers. |
| **Milestone Check-ins** | Hourly progress snapshots of active tasks. |
| **Attention Gate** | Per-chat message budget with urgency classification and quiet hours. |
| **Decision Memory** | Records team decisions with context. Searchable by topic, tag, date, or participant. |

Enable in `~/.alex/config.yaml`:

```yaml
proactive:
  scheduler:
    enabled: true
    blocker_radar:
      enabled: true
      channel: lark
      chat_id: oc_your_chat_id
    weekly_pulse:
      enabled: true
      channel: lark
      chat_id: oc_your_chat_id
```

---

## Delivery Surfaces

| Surface | Description |
|---|---|
| **Lark** *(primary)* | WebSocket gateway. Real-time progress, emoji reactions, approval flows. |
| **Web Console** | Next.js dashboard with SSE streaming, artifact rendering, cost tracking. |
| **CLI / TUI** | Interactive terminal with streaming output for local workflows. |

---

## Built-in Skills

Skills are markdown-driven workflows triggered by natural language:

| Skill | What it does |
|---|---|
| `deep-research` | Multi-step web research with source synthesis |
| `meeting-notes` | Structured summaries and action item extraction |
| `email-drafting` | Context-aware email composition |
| `ppt-deck` | Slide deck generation |
| `video-production` | Video script and production planning |
| `research-briefing` | Concise briefing documents |
| `best-practice-search` | Engineering best practice lookup |

---

## LLM Providers

```
OpenAI · Anthropic (Claude) · DeepSeek · ByteDance ARK (Doubao)
OpenRouter · Ollama (local) · Kimi · Qwen
```

Set `llm_provider: auto` — the runtime picks the best available provider from your environment keys.

---

## Architecture

```
Delivery      Lark · Web Console · CLI · API Server
     ↓
Application   Coordination · Context Assembly · Cost Control
     ↓
Domain        ReAct Loop · Typed Events · Approval Gates
     ↓
Infra         Multi-LLM · Memory Store · Tool Registry · Observability
```

| Layer | Key packages |
|---|---|
| Delivery | `internal/delivery/channels/lark/`, `cmd/alex-server`, `web/` |
| Agent core | `internal/{app,domain}/agent` — ReAct loop, typed events, approval gates |
| Tools | `internal/infra/tools/builtin/` — search, code, browser, files, artifacts, media |
| Memory | `internal/infra/memory/` — Postgres / file / in-memory with tokenization |
| LLM | `internal/infra/llm/` — multi-provider, auto-selection, streaming |
| MCP | `internal/infra/mcp/` — JSON-RPC servers for external integrations |
| Observability | `internal/infra/observability/` — OTel traces, Prometheus metrics, cost accounting |

---

## Documentation

| | |
|---|---|
| [Quick Start](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/guides/quickstart.md) | From clone to running in minutes |
| [Configuration Reference](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/reference/CONFIG.md) | Full config schema and precedence rules |
| [Architecture](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/reference/ARCHITECTURE.md) | Runtime layering and execution model |
| [Deployment Guide](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/operations/DEPLOYMENT.md) | Production deployment |
| [Roadmap](https://github.com/cklxx/elephant.ai/blob/HEAD/ROADMAP.md) | What's next |

---

## Contributing

Contributions are welcome. See [`CONTRIBUTING.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/CONTRIBUTING.md) for development setup, code standards, and PR workflow. First time? Look for issues labeled [`good first issue`](https://github.com/cklxx/elephant.ai/issues?q=label%3A%22good+first+issue%22).

Please read [`CODE_OF_CONDUCT.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/CODE_OF_CONDUCT.md) before participating, and report security vulnerabilities via [`SECURITY.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/SECURITY.md).

---

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=cklxx/elephant.ai&type=Date)](https://star-history.com/#cklxx/elephant.ai&Date)

---

## License

[MIT](https://github.com/cklxx/elephant.ai/tree/HEAD/LICENSE) © 2025 cklxx

elephant.ai

A leader agent for attention-heavy work.
Lives in Lark. Tracks what's moving, surfaces what matters, follows up automatically, and only pulls you in when judgment is needed.

What is elephant.ai?

A leader agent that lives in your Lark groups and DMs. It takes ownership of work — tracking progress, following up on tasks, surfacing what needs attention, and handling coordination. Behind the scenes it orchestrates specialist agents and tools. To you, it's one reliable operator who never drops the ball.

Why a leader agent?

Continuous ownership — Hand off a task and it stays tracked until done.
Attention gating — Compresses noise into what matters, what's at risk, and what needs your call.
Proactive follow-up — Chases status, summarizes results, escalates blockers automatically.
Coordination absorbed — Handles the track/ask/remind/align overhead.
Persistent memory — Remembers conversations, decisions, and context across weeks and months.
Approval gates — Knows when to ask before acting. Risky operations require explicit sign-off.
MCP extensible — Connect any external tool through the Model Context Protocol.
Lark-native — WebSocket gateway, always present in groups and DMs.

Quick Start

Prerequisites: Go 1.24+, Node.js 20+, a Lark bot token, and an LLM API key.

# 1. Clone and build
git clone https://github.com/cklxx/elephant.ai.git && cd elephant.ai
make build

# 2. Configure (LLM key + Lark credentials)
cp examples/config/runtime-config.yaml ~/.alex/config.yaml
export LLM_API_KEY="sk-..."
alex setup   # interactive first-run wizard

# 3. Start everything
alex dev up

# 4. Talk to it in Lark — or use the CLI directly
./alex "summarize the last 3 conversations and draft follow-up emails"

Full setup guide → docs/guides/quickstart.md

How It Works

You (Lark group or DM)
        ↓
  Chat (lightweight LLM, ~1-3s)      — instant reply, routing, ack
        │
        ├── direct reply ──────────▶ back to you immediately
        │
        └── dispatch ──▶ Worker (ReAct Agent, background, minutes)
                              ↓
                        Context Assembly · Memory · Policies
                              ↓
                        Think → Act → Observe → Tool Execution
                              ↓
                        Reply delivered to Lark (with progress updates)

Leader Agent Features

The leader agent runs a background scheduler alongside Lark conversations. It monitors task health, generates digests, and surfaces decisions and blockers before they become problems.

Feature	Description
Blocker Radar	Scans every 10 min for stale/blocked tasks. Auto-notifies with cooldown.
Weekly Pulse	Monday 9am digest: tasks completed, cycle time, token spend, success rate.
Daily Summary	End-of-day activity recap with top agents and key outcomes.
1:1 Prep Brief	Auto-generated talking points before meetings: wins, open items, blockers.
Milestone Check-ins	Hourly progress snapshots of active tasks.
Attention Gate	Per-chat message budget with urgency classification and quiet hours.
Decision Memory	Records team decisions with context. Searchable by topic, tag, date, or participant.

Enable in ~/.alex/config.yaml:

proactive:
  scheduler:
    enabled: true
    blocker_radar:
      enabled: true
      channel: lark
      chat_id: oc_your_chat_id
    weekly_pulse:
      enabled: true
      channel: lark
      chat_id: oc_your_chat_id

Delivery Surfaces

Surface	Description
Lark (primary)	WebSocket gateway. Real-time progress, emoji reactions, approval flows.
Web Console	Next.js dashboard with SSE streaming, artifact rendering, cost tracking.
CLI / TUI	Interactive terminal with streaming output for local workflows.

Built-in Skills

Skills are markdown-driven workflows triggered by natural language:

Skill	What it does
`deep-research`	Multi-step web research with source synthesis
`meeting-notes`	Structured summaries and action item extraction
`email-drafting`	Context-aware email composition
`ppt-deck`	Slide deck generation
`video-production`	Video script and production planning
`research-briefing`	Concise briefing documents
`best-practice-search`	Engineering best practice lookup

LLM Providers

OpenAI · Anthropic (Claude) · DeepSeek · ByteDance ARK (Doubao)
OpenRouter · Ollama (local) · Kimi · Qwen

Set llm_provider: auto — the runtime picks the best available provider from your environment keys.

Architecture

Delivery      Lark · Web Console · CLI · API Server
     ↓
Application   Coordination · Context Assembly · Cost Control
     ↓
Domain        ReAct Loop · Typed Events · Approval Gates
     ↓
Infra         Multi-LLM · Memory Store · Tool Registry · Observability

Layer	Key packages
Delivery	`internal/delivery/channels/lark/`, `cmd/alex-server`, `web/`
Agent core	`internal/{app,domain}/agent` — ReAct loop, typed events, approval gates
Tools	`internal/infra/tools/builtin/` — search, code, browser, files, artifacts, media
Memory	`internal/infra/memory/` — Postgres / file / in-memory with tokenization
LLM	`internal/infra/llm/` — multi-provider, auto-selection, streaming
MCP	`internal/infra/mcp/` — JSON-RPC servers for external integrations
Observability	`internal/infra/observability/` — OTel traces, Prometheus metrics, cost accounting

Documentation


Quick Start	From clone to running in minutes
Configuration Reference	Full config schema and precedence rules
Architecture	Runtime layering and execution model
Deployment Guide	Production deployment
Roadmap	What's next

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, code standards, and PR workflow. First time? Look for issues labeled good first issue.

Please read CODE_OF_CONDUCT.md before participating, and report security vulnerabilities via SECURITY.md.