MACA — Multi-Agent Collaborative Architect

A multi-agent collaborative development system built from scratch — no LangChain, no LangGraph, just pure architecture.

从零搭建的多智能体协同开发系统。不依赖 LangChain/LangGraph，纯手工架构。

---

What It Does

You say "Build me a user management API" — four AI agents automatically collaborate to deliver:

One sentence requirement
        ↓
  📋 Planner     →  Decomposes into modules, features, interfaces, steps
        ↓
  🔨 Developer   →  Generates production-ready TypeScript code
        ↓
  🧪 Tester      →  Six-dimension review (syntax/logic/security/boundary/performance/practice)
        ↓
  📝 Documenter  →  Outputs README + API docs + retrospective report

All automatic. Zero human intervention. Code and docs land in maca_output/.

---

Architecture

                    ┌─────────────┐
   User Input ────→ │ Orchestrator│ ← State machine (PLAN→DEVELOP→TEST⇄FIX→DOC)
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │     MessageBus          │ ← Custom async messaging
              │  (EventEmitter+Promise) │    (point-to-point / broadcast / RPC)
              └────────────┬────────────┘
                           │
     ┌─────────┬───────────┼───────────┬──────────┐
     ↓         ↓           ↓           ↓          ↓
  Planner  Developer   Tester     Documenter

Each agent is independent — they communicate only through the MessageBus. Add a new agent by implementing one method: processMessage().

---

Enterprise Features

Feature	Description
💾 Checkpointing	Auto-saves after each task. Crash? Resume from where you left off.
🔧 Tool Calling	Agents can read/write files, run commands. Not just text generation.
🔍 RAG Retrieval	BM25 keyword + embedding semantic search. Developer checks existing code before writing.
📡 Streaming Progress	Real-time progress bar via EventEmitter. No more black-box waiting.
🛡️ Approval Gate	Security risks auto-suspend for human approval. 30s timeout auto-skip.

---

Quick Start

git clone https://github.com/yourname/maca.git
cd maca
npm install

Option 1: Enterprise TUI (recommended)

npx tsx tui-pro.ts

Interactive console with progress bar, RAG status, approval handling.

Option 2: One-shot demo

npx tsx examples/demo.ts

Option 3: Command line

npx tsx use.ts "Build a file upload service with resume support"

Configure LLM

Copy .env.example to .env and add your API key:

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL=deepseek-chat

Works without API key too (falls back to rule engine).

---

Project Structure

maca/
├── src/
│   ├── agents/              # 4 core agents
│   │   ├── planner.ts       # Requirement → WBS task tree
│   │   ├── developer.ts     # Code generation + RAG context
│   │   ├── tester.ts        # 6-dimension review (15+ regex rules)
│   │   └── documenter.ts    # README / API / Module / Retrospective
│   │
│   ├── orchestrator.ts           # v1: hardcoded pipeline
│   ├── enterprise-orchestrator.ts # v3: with checkpoint/tool/RAG/approval
│   ├── langgraph.ts              # v2: declarative graph engine (120 lines)
│   │
│   └── services/
│       ├── checkpoint.ts    # Snapshot persistence
│       ├── tools.ts         # 4 built-in tools with safety filters
│       ├── rag.ts           # BM25 + embedding retrieval
│       └── progress.ts      # Streaming + approval gate
│
├── tui.ts            # v1 TUI
├── tui-pro.ts        # v3 Enterprise TUI
├── use.ts            # One-command runner
└── examples/
    ├── demo.ts       # End-to-end demo
    └── graph_demo.ts # LangGraph-style orchestration

---

Key Design Decisions

• No framework dependency — Message bus, state machine, graph engine all hand-rolled
• LLM + rule engine dual mode — Works offline with regex fallback
• JSON Schema constrained outputs — All LLM calls return parseable JSON, no markdown wrapping
• Temperature gradient — Planning/review 0.3, generation 0.5, fixing 0.2
• Template Method pattern — BaseAgent defines lifecycle; subclasses override processMessage()
• ESM + strict TypeScript — Zero compile errors, full type safety

---

Tech Stack

TypeScript Python Node.js OpenAI SDK DeepSeek API Zod Pydantic Vitest pytest Commander.js Click Prompt Engineering RAG BM25 EventEmitter

---

Why This Project

This project answers one question: "What does LangGraph actually do under the hood?"

Instead of installing LangChain and calling graph.add_node(), I built the entire thing from scratch — the message bus, the state machine, the graph compiler, the tool executor, the RAG index. Understanding comes from building, not from importing.

---

License

MIT