diff --git a/README.en.md b/README.en.md index 639a7bbd..e8d4b49c 100644 --- a/README.en.md +++ b/README.en.md @@ -1,431 +1,174 @@ -# LingXiao 剑域 +# LingXiao · 凌霄剑域

- LingXiao + LingXiao logo

-

- One sword cleaves the sky. Build what you envision. -

- -

- LingXiao WebUI Command Center -

- -

LingXiao WebUI — Tasks · Blackboard · Terminal · Git · Agents · Memory · Plugins

- ---- - -> You give a goal. The Leader decomposes, plans, builds a DAG, assembles experts, dispatches, supervises, and delivers. Worker experts execute research, frontend, backend, testing, review, documentation, and Git in parallel. WebUI / TUI / backend share the same runtime state — observable, recoverable, auditable. - -`v1.0.0` · Node.js 24+ · Linux / macOS / Windows - -[中文 README](./README.zh-CN.md) · [Bilingual](./README.md) · [Docs](https://hexian2001.github.io/lingxiao_website/) +> One sword cleaves the sky. Build what you envision. ---- +[中文](./README.md) | [English](./README.en.md) -## Table of Contents +![LingXiao WebUI Command Center](./docs/images/homepage.png) -- [What It Is](#what-it-is) -- [Install](#install) -- [Quick Start](#quick-start) -- [Core Features](#core-features) - - [Expert Team Runtime](#expert-team-runtime) - - [Task DAG Orchestration](#task-dag-orchestration) - - [Unified Runtime-State Sync](#unified-runtime-state-sync) - - [WebUI Command Center](#webui-command-center) - - [Real Tool Kernel](#real-tool-kernel) - - [Orchestration & Verification](#orchestration--verification) - - [MCP Forge & Skills](#mcp-forge--skills) - - [Persistent Memory](#persistent-memory) - - [Eternal Autonomous Mode](#eternal-autonomous-mode) - - [Local LLM Gateway](#local-llm-gateway) -- [Architecture](#architecture) -- [Configuration](#configuration) -- [Development](#development) -- [Security](#security) -- [Tech Stack](#tech-stack) -- [License](#license) +## Preface ---- +There are plenty of AI coding tools out there, each with its own strengths. Through long-term use and practice, we've always had a small wish: could an AI tool act more like a seasoned tech lead — breaking down requirements, driving parallel execution, and keeping the entire process traceable? -## What It Is +**LingXiao** was born from that wish. It's an open-source multi-agent collaboration system — use it as a drop-in replacement for or supplement to existing tools, especially for medium-to-large projects. -LingXiao turns "chatting with a model" into "commanding an AI expert team." +Here's an overview of what it can do, how it works, and what the experience is like. Feedback, suggestions, and ideas are all welcome — let's learn and improve together. -| Traditional Chat | LingXiao | -|:---|:---| -| Single assistant, single thread | Leader + Worker expert team | -| Flat conversation history | Dependency-aware task DAG | -| No real tool execution | File I/O, shell, Git, browser, terminal, MCP | -| State lost on refresh | SQLite-backed, recoverable sessions | -| Black-box decisions | Full audit trail: tasks, tools, evidence, verdicts | -| No parallelism | Independent tasks dispatched in parallel | +[Product Site](https://hexian2001.github.io/lingxiao_website/) | [Repository](https://github.com/hexian2001/lingxiao-coding) -You state a goal. The Leader understands it, decomposes it into a task graph, assembles the right expert workers, dispatches work, supervises progress, and closes the loop with evidence. Every Worker has independent identity, context, toolchain, and runtime state — not UI decoration, but real execution entities in the scheduling model. - ---- - -## Install - -### Option 1: One-Line Install (Recommended) - -**macOS / Linux / WSL:** - -```bash -curl -fsSL https://raw.githubusercontent.com/hexian2001/lingxiao-coding/main/scripts/install.sh | sh -``` - -**Windows (CMD / PowerShell):** - -```powershell -powershell -c "irm https://raw.githubusercontent.com/hexian2001/lingxiao-coding/main/scripts/install.ps1 | iex" -``` +## Elevator Pitch -> ℹ️ No Node.js required. The script auto-detects platform and architecture, downloads the matching portable binary, and installs it to `~/.lingxiao/bin`. +**LingXiao upgrades "chatting with AI" into "commanding an army of AI experts" — you set the goal, they do the work.** -### Option 2: Build from Source +How it works: the Leader Agent breaks down requirements, designs the plan, assembles an expert team, and delegates tasks. Worker experts run in parallel on frontend, backend, testing, documentation, Git operations, and more. The entire process is visible in real time through WebUI or TUI — every task's progress, tool invocation, and decision rationale is transparent and auditable, and you can intervene at any time. -```bash -git clone https://github.com/hexian2001/lingxiao-coding.git -cd lingxiao-coding -npm install -npm run build -npm link -``` +## Interface at a Glance -### Upgrade + + + + + + + + + + + + + + + + + +
WebUI Task BoardWebUI Agent Panel
Task BoardAgent Panel
TUI Terminal InterfaceWebUI Chat & Blackboard
TUI TerminalChat Interface
-```bash -lingxiao upgrade # Check and upgrade to latest -lingxiao upgrade --check # Check only, no upgrade -``` +## Project Overview -### First-Time Setup +### Project Structure -```bash -lingxiao init # Initialize config at ~/.lingxiao/settings.json -lingxiao doctor # Environment diagnostics ``` - ---- - -## Quick Start - -```bash -lingxiao # Start TUI + WebUI -lingxiao --session # Resume a session -lingxiao list # List all sessions +lingxiao-coding/ +├── src/ # Backend source (TypeScript) +├── web/ # WebUI frontend (React + Vite) +├── scripts/ # Build / tooling scripts +├── skills/ # Skill packs +├── docs/ # Documentation & screenshots +├── assets/ # Static assets +├── package.json +└── LICENSE ``` -The terminal prints the WebUI URL. Port metadata is written to `~/.lingxiao/port`. - -
-📋 Typical Workflow - -1. **Start**: Run `lingxiao` — TUI launches, WebUI URL printed. -2. **Give a goal**: Type your engineering goal in chat. -3. **Leader plans**: Leader decomposes into a task DAG, may ask for confirmation. -4. **Workers execute**: Expert workers are dispatched, each with tools and context. -5. **Monitor**: Watch task progress, agent panels, tool calls in real-time. -6. **Review**: Leader presents results with evidence and file changes. -7. **Iterate**: Resume sessions, run `lingxiao upgrade` for updates. +### Tech Stack -
- ---- +- **Backend**: Node.js 24+, TypeScript, Fastify +- **Frontend**: React 19, Vite, Ink (TUI) +- **AI SDK**: OpenAI / Anthropic / Google / Amazon Bedrock +- **Toolchain**: Playwright, Sharp, Tesseract.js, MCP SDK ## Core Features -### Expert Team Runtime - -LingXiao's basic unit is not "an assistant" — it's a **Leader + Worker expert team**: - -| Role | Responsibility | -|:-----|:---------------| -| **Leader** | Goal understanding, task decomposition, DAG planning, expert dispatch, user confirmation, delivery | -| **Architect** | Architecture design, interface boundaries, module splitting, risk control | -| **Backend** | Backend implementation, state machines, APIs, databases, task scheduling | -| **Frontend** | WebUI/TUI interaction, state projection, visualization workbench | -| **Researcher** | Research, comparison, external verification | -| **QA/Reviewer** | Testing, regression, code review, acceptance evidence | -| **Custom** | Extend through role registration, skill system, and tool permissions | - -Every Worker has: -- **Identity**: agent ID, role, name, display in WebUI/TUI -- **Ownership**: bound task, write scope, tool permissions -- **Context**: independent conversation history, injected skills, system prompt -- **Runtime state**: running / paused / waiting / completed / failed -- **Audit trail**: tool calls, logs, work notes, completion reports - -### Task DAG Orchestration - -Complex goals become dependency-aware task graphs: - -```text -T-1 Requirements Analysis - ├─ T-2 Architecture Design - │ ├─ T-3 Backend Implementation - │ └─ T-4 Frontend Implementation - ├─ T-5 Integration Verification - └─ T-6 Documentation & Release -``` +### A Team of Experts, Not a Single-Agent Monologue -| Feature | Description | -|:--------|:------------| -| Parallel dispatch | Independent tasks run simultaneously (write-scope orthogonal) | -| Dependency ordering | `blocked_by` ensures correct sequencing | -| Evidence preservation | Every task stores results, artifacts, and verification | -| Recovery | Interrupted sessions resume from last state | -| Contract loop | `contract → implement → evaluate → repair → reset` | +- **Leader**: Commander-in-chief — understands objectives, breaks down tasks, builds the DAG, schedules experts, oversees completion. +- **Architect**: Architecture design, interface boundaries, module decomposition, risk management. +- **Backend**: Backend implementation — state machines, APIs, databases, task scheduling. +- **Frontend**: WebUI/TUI interaction, state projection, visualization workbench. +- **Researcher**: Research, solution comparison, external validation. +- **QA/Reviewer**: Testing, regression, code review, acceptance evidence. +- **Custom Roles**: Extend expert capabilities through role registration, the skill system, and tool permissions. -### Unified Runtime-State Sync +### Task DAG -WebUI, TUI, and backend **do not infer state from event streams**. They share one calibration source: +Complex goals are decomposed by the Leader into a dependency graph of tasks. When each task is declared, the system automatically computes reverse edges to form a complete Directed Acyclic Graph. Three gates determine whether a task can execute: the Candidate Gate (task status is `dispatchable` with no blocking reasons), the Dependency Gate (all predecessor tasks are completed), and the Contract Gate (architecture contracts are ready). When a predecessor completes, blocked successor tasks are automatically unlocked to `dispatchable` — no manual scheduling required. The WebUI task panel visualizes the entire DAG: completed, running, blocked, and dependency lines — all at a glance. -```text -SessionManager - → session:runtime_state - → SseBridge - → ACP session/update: session_runtime_state - → Web sessionStore / TUI event bridge -``` - -The runtime snapshot covers: - -- Session status (active / idle / waiting / completed) -- Leader state (busy / waiting / review / asking user) -- Pending user input and permission requests -- Running workers (agent ID, task, progress) -- Dispatchable tasks (ready, blocked, terminal) -- Turn classification (user turn / leader turn / worker turn) - -Text streams, thinking, tool-call deltas, and tool results remain fine-grained incremental events. **Snapshots calibrate; streams deliver the live experience.** - -### WebUI Command Center - -The WebUI is an **Agent Command Center**, not just a chat window: - -| Panel | Purpose | -|:------|:--------| -| **Chat** | Main control — thinking, tool calls, streaming output, user interaction | -| **Tasks** | Task DAG visualization — status, dependencies, results, evidence | -| **Agents** | Worker panels — roles, runtime state, task binding, context | -| **Review** | Change evidence — file diffs, acceptance trails, verdict history | -| **Git** | Version control — status, diff, branch, commit, push/pull, stash | -| **Blackboard** | Team memory — facts, intent, graph relationships | -| **Terminal** | In-browser shell — full terminal access from the WebUI | -| **Settings** | Configuration — models, permissions, tools, plugins, modes | - -### Real Tool Kernel - -LingXiao agents don't just talk. They use **real tools** under permission control: - -| Category | Tools | -|:---------|:------| -| File I/O | Read, create, structured patch, directory listing | -| Search | Code search (ripgrep), glob, AST query (TypeScript) | -| Execution | Shell, Python, Node.js REPL, terminal control | -| Version Control | Git workbench — status, diff, commit, branch, push/pull, MR/PR | -| Browser | Navigation, click, fill, screenshot, eval JS, OCR | -| Web | Fetch, search, HTTP request | -| Office | PPTX, DOCX, XLSX, PDF generation and editing | -| Canvas | Workflow canvas, execution engine | -| Team | Messages, work notes, blackboard graph | -| External | Unified MCP entrypoint for external systems | +### Full State Machine Synchronization -### Orchestration & Verification +WebUI, TUI, and the backend runtime share a single EventEmitter as the event hub. SseBridge subscribes to 43 session-level events and 11 Agent-level events, routing them precisely to the correct frontend connection via `agentId→sessionId` mapping. `session:runtime_state` serves as the unified state snapshot for calibration — when the frontend reconnects or switches back, it restores from the snapshot directly rather than replaying events. Streaming events deliver real-time experience; state snapshots guarantee eventual consistency. -LingXiao doesn't just dispatch tasks — it runs **structured verification** on every completed task: +### Automatic Acceptance Loop -
-🔧 Verification Subsystems +After each `implement` task completes, the system **automatically** creates an Evaluator verification task to assess the results across multiple dimensions (functional correctness, code quality, visual design, product depth). If verification fails, a Repair task is automatically generated; the Worker fixes the issues and the loop repeats until the task passes or hits the repair limit. This isn't a "remember to check" line in a prompt — it's a quality gate baked into the execution pipeline. -| Subsystem | Description | -|:----------|:------------| -| **Orchestration Runtime** | Task lifecycle events auto-trigger verdict extraction (PASS / FAIL / BLOCKED) | -| **Speculative Execution** | Parallel implementation branches with `first_green` / `fewest_changes` / `fastest_tests` selection | -| **Adversarial Verification** | Command-level breaker strategies with exit-code assertions + stdout/stderr evidence | -| **Adaptive Orchestration** | Difficulty-signal-driven routing: cross-module deps, hotspot overlap, prior failures, impact ratio | -| **Contract Loop** | `contract → implement → evaluate → repair → reset` with blackboard materialization | -| **Bug Hunting** | Bughunt DAG scheduler + evidence capture/pack + finding ledger, isolated worktree execution | -| **Assumption Tracking** | Agents declare verifiable assumptions (type_check / file_content / test_execution / ast_query), auto-validated on code changes | +### Blackboard Knowledge Graph -
+Structured consensus among agents goes beyond simple chat history. Workers write facts, intents, design documents, contracts, review conclusions, and 8 other node types into a shared knowledge graph. The Leader reads and analyzes the graph every round, perceiving global progress and cognitive alignment. Agents don't pass messages — they align cognition through a structured graph. -### MCP Forge & Skills +### External Agent Driver -| System | Description | -|:-------|:------------| -| **MCP Forge** | Template-driven MCP Server generation engine — requirements → template → generate → sandbox → inspect → register | -| **Skills** | 4-tier priority (project > plugin > global > bundled), YAML frontmatter definition, auto-injected into worker prompts by role and task | +LingXiao ships with a Claude Code Driver and a Codex Driver that can launch the `claude` CLI or `codex` CLI as Worker subprocesses — injecting LingXiao Worker identity, parsing output as a stream, and collecting completion reports. This means you can use LingXiao as the commander and Claude Code or Codex CLI as the experts doing the actual work. -### Persistent Memory +### Tool Plugins & MCP Ecosystem -Two-layer memory architecture: +A complete plugin system (plugin.json manifest, discovery, installation, contribution enumeration) supports injecting skills, MCP Servers, custom tools, and hooks (before/after intercepting and modifying tool calls). 80+ built-in tools cover file I/O, code search, AST queries, shell execution, browser automation, Git operations, HTTP requests, MCP integration, Office document generation, and more. Supports the skill system and MCP protocol extensions. -| Layer | Description | -|:------|:------------| -| **Long-term** | FTS5 + BM25 full-text search · 4 memory types (user / feedback / project / reference) · auto-distillation · associative recall · maintenance pipeline | -| **Short-term** | Skill injection at worker dispatch — execution knowledge complementing long-term memory | - -### Eternal Autonomous Mode +## Quick Start -Leader self-patrol state machine: +### Prerequisites -```text -IDLE → CHECK → PATROL → THINK → WAIT → IDLE ``` - -- 30s base interval with exponential backoff -- Budget circuit breaker at 8 consecutive failures -- EternalSupervisor: 3-layer health check (PID + watchdog + HTTP) + auto-restart - -### Local LLM Gateway - -LingXiao can act as an **OpenAI / Anthropic dual-format LLM proxy**: - -- Virtual key management -- Per-key RPM / TPM / daily token budget -- Request trace logging -- Default port: `62000` - ---- - -## Architecture - -```mermaid -flowchart LR - User["User"] - TUI["TUI / CLI"] - Web["WebUI Command Center"] - ACP["ACP JSON-RPC + SSE"] - SM["SessionManager"] - RT["SessionRuntime"] - L["LeaderAgent"] - DAG["TaskBoard / DAG"] - Pool["AgentPool"] - Workers["Worker Experts"] - Tools["ToolRegistry"] - DB["SQLite"] - Git["Git / Workbench"] - - User --> TUI - User --> Web - TUI --> SM - Web --> ACP - ACP --> SM - SM --> RT - RT --> L - L --> DAG - L --> Pool - Pool --> Workers - L --> Tools - Workers --> Tools - Tools --> Git - SM --> DB - DAG --> DB - Workers --> DB +- [Node.js](https://nodejs.org/) >= 24.0.0 +- npm or a compatible package manager ``` ---- - -## Configuration - -Config file: `~/.lingxiao/settings.json` - -| Variable | Description | Default | -|:---------|:------------|:--------| -| `LINGXIAO_LLM_PROVIDER` | LLM provider: `auto` / `openai` / `anthropic` | `auto` | -| `LINGXIAO_OPENAI_API_KEY` | OpenAI or compatible API key | — | -| `LINGXIAO_OPENAI_BASE_URL` | OpenAI-compatible endpoint | — | -| `LINGXIAO_ANTHROPIC_API_KEY` | Anthropic API key | — | -| `LINGXIAO_LEADER_MODEL` | Leader model name | — | -| `LINGXIAO_AGENT_MODEL` | Worker model name | — | -| `LINGXIAO_WEB_PORT` | Web server port | `0` (auto) | - -> ℹ️ Supports OpenAI, Anthropic, DeepSeek, Qwen, Moonshot/Kimi, Gemini-compatible, Groq, SiliconFlow, and other OpenAI-format services. - ---- - -## Development +### Install from Source ```bash -# Install dependencies +git clone https://github.com/hexian2001/lingxiao-coding.git +cd lingxiao-coding npm install - -# Build (TypeScript + Web + Server) npm run build - -# Development -npm run cli # Run CLI directly -cd web && npm run dev # Web dev server - -# Testing -npm run test:architecture # Architecture invariant tests -npm run test:scripts # Script invariant tests -npm test # Full test suite - -# Type checking -npx tsc -p tsconfig.cli.json --noEmit -npx tsc -p web/tsconfig.json --noEmit +npm link ``` -
-📚 Documentation Index - -| Document | Description | -|:---------|:------------| -| [Engineering Docs](./docs/README.md) | Engineering documentation index | -| [Architecture](./docs/architecture.md) | System architecture overview | -| [Runtime State Sync](./docs/runtime-state-sync.md) | State synchronization design | -| [ACP Contract](./docs/contracts/acp.md) | Agent Communication Protocol | -| [Session Events](./docs/contracts/session-events.md) | Session event contract | -| [Session State](./docs/contracts/session-state.md) | Session state contract | -| [Agents & Tools](./docs/contracts/agents-tools.md) | Agent and tool contract | -| [Testing](./docs/testing.md) | Testing and quality gates | -| [Release Guide](./docs/repository-release.md) | Repository release process | +After installation, run directly in the terminal: -
+```bash +lingxiao +``` ---- +The first run will guide you through configuring your model and API key. Choose TUI mode or WebUI mode, set your goal, and LingXiao gets to work. -## Security +> Note: If the initial model and API key configuration fails, you can check and update them at `/root/.lingxiao/settings.json` (on Windows, it's `./lingxiao` under your user directory). -> ⚠️ LingXiao has **real host capabilities**: file read/write, shell execution, browser automation, Git operations, terminal access, workflow execution, external model calls, and worker task execution. +![LingXiao Usage](./docs/images/use.png) -| Rule | Detail | -|:-----|:-------| -| **Token protection** | The Web server token is local machine control. Do not expose an unprotected server. | -| **No secrets in Git** | Never commit `.env`, API keys, Git tokens, SQLite session databases, or token-bearing remote URLs. | -| **Permission modes** | Strict → Dev → Networked → Yolo. Workers operate under the session's permission level. | -| **Sandbox** | Shell commands run in app-guard / bubblewrap sandbox with network isolation options. | +For detailed documentation, visit the [docs](https://hexian2001.github.io/lingxiao_website/getting-started/introduction/). ---- +### Upgrade -## Tech Stack +```bash +lingxiao upgrade +``` -| Layer | Technology | -|:------|:-----------| -| Runtime | Node.js 24+ · TypeScript · Fastify | -| Storage | SQLite (sessions, tasks, messages, agents, tools, workflows) | -| Web UI | React · Ink (TUI) | -| Browser | Playwright | -| LLM | OpenAI SDK · Anthropic SDK | -| Docs | Astro (Starlight) | +Or manually: ---- +```bash +cd lingxiao-coding +git pull +npm install +npm run build +``` -## License +## License & Contributing -AGPL-3.0-only. See [LICENSE](./LICENSE). +This project uses an **AGPL v3 + Commercial Dual License** model: free for personal/open-source use, modifications must be open-sourced; if offered as a SaaS/API service, source code must be made available to users; for commercial closed-source use, please contact us for a commercial license (see [LICENSE](./LICENSE) for details). ---- +Issues and PRs are welcome (please ensure your code passes `npm run build`, does not introduce hardcoded credentials or sensitive information, and follows the existing code style). -
+Commercial licensing inquiries: hexian2001@github.com -**LingXiao** — One Sword Cleaves the Sky +## Connect & Community -Proprietary software · Unauthorized copying, modification, or distribution prohibited +- **GitHub**: [hexian2001/lingxiao-coding](https://github.com/hexian2001/lingxiao-coding) +- **Issues**: [Submit bugs or feature requests](https://github.com/hexian2001/lingxiao-coding/issues) +- **Community**: Recognized and endorsed by the [LINUX DO Community](https://linux.do) -
+

+ QQ Group QR CodeWeChat Group QR Code
+ Scan to join QQ/WeChat groups for latest updates, help, and developer discussions +

diff --git a/README.md b/README.md index 6d636038..983444e1 100644 --- a/README.md +++ b/README.md @@ -6,35 +6,27 @@ > One sword cleaves the sky. Build what you envision. -[中文](#中文) | [English](#english) +[中文](./README.md) | [English](./README.en.md) ![LingXiao WebUI 指挥中心](./docs/images/homepage.png) ---- +## 前言 -## License / 许可协议 +AI 编程工具已经不少了，各有各的擅长。我们在长期使用和实践中，一直有一个小愿望： AI 工具能不能更像一个有经验的技术总监那样，帮我们拆解任务、并行推进、全程可追溯？ -本项目采用 **AGPL v3 + 商业双授权** 模式： +**凌霄剑域 · LingXiao** 应运而生。这是一个开源的多智能体协作系统，你可以把它当作现有工具的平替或补充，尤其适合中大型项目。 -- **开源协议**：GNU AGPL v3 — 免费、修改和分发均允许，但修改版本必须同样开源 -- **网络服务条款**：将凌霄作为网络服务（SaaS/API）对外提供时，必须向用户开放完整源代码 -- **商业授权**：如需在商业产品中使用且不想开源，请联系购买商业授权 +接下来，我将为大家介绍一下我们的产品：它到底能做什么、怎么做到的，以及实际使用体验。当然，如果有优化建议、使用反馈，都欢迎交流讨论，一起学习进步。 -详见 [LICENSE](./LICENSE)。商用授权联系：hexian2001@github.com +[产品网站](https://hexian2001.github.io/lingxiao_website/) | [仓库地址](https://github.com/hexian2001/lingxiao-coding) ---- +## 一句话介绍 - +**凌霄剑域把和AI聊天升级成了指挥一支AI专家军团——你定目标，它来干活。** -## 中文 +具体来说：Leader Agent 负责拆解需求、制定方案、组建专家团队、派发任务；各个 Worker 专家并行推进前端、后端、测试、文档、Git 操作等具体工作。整个过程在 WebUI 或 TUI 上实时可见，所有任务进度、工具调用、决策依据都清晰可查，你随时可以介入调整。 -### 一句话 - -凌霄把"和模型聊天"升级成"指挥一个可观测、可恢复、可审查的 AI 专家团队"。 - -你给目标，Leader 负责判断、拆解、规划、建 DAG、组专家团、派发任务；Worker 专家并行执行研究、前端、后端、测试、审查、文档、Git 操作等工作；WebUI/TUI 实时同步完整运行态，所有任务、工具、权限、证据和会话状态都进入同一个工程内核。 - -### 界面一览 +## 界面一览 @@ -55,49 +47,32 @@
-### 安装 - -#### 前置要求 - -- [Node.js](https://nodejs.org/) >= 24.0.0 -- npm 或兼容包管理器 - -#### 从源码安装 +## 项目介绍 -```bash -git clone https://github.com/hexian2001/lingxiao-coding.git -cd lingxiao-coding -npm install -npm run build -npm link -``` - -安装完成后，终端直接运行： +### 项目结构 -```bash -lingxiao ``` - -首次运行会引导你配置模型和 API Key。 - -#### 升级 - -```bash -lingxiao upgrade +lingxiao-coding/ +├── src/ # 后端源码（TypeScript） +├── web/ # WebUI 前端（React + Vite） +├── scripts/ # 构建/工具脚本 +├── skills/ # 技能包 +├── docs/ # 文档与截图 +├── assets/ # 静态资源 +├── package.json +└── LICENSE ``` -或手动执行： +### 技术栈 -```bash -cd lingxiao-coding -git pull -npm install -npm run build -``` +- **后端**：Node.js 24+、TypeScript、Fastify +- **前端**：React 19、Vite、Ink (TUI) +- **AI SDK**：OpenAI / Anthropic / Google / Amazon Bedrock +- **工具链**：Playwright、Sharp、Tesseract.js、MCP SDK -### 核心特色 +## 核心特色 -#### 专家团，不是单 Agent 独白 +### 专家团，不是单 Agent 独白 - **Leader**：总指挥，理解目标、拆任务、建 DAG、调度专家、监督收尾。 - **Architect**：架构设计、接口边界、模块拆分、风险控制。 @@ -107,104 +82,40 @@ npm run build - **QA/Reviewer**：测试、回归、代码审查、验收证据。 - **自定义角色**：通过角色注册、技能系统和工具权限扩展专家能力。 -#### 任务 DAG，让复杂工程可调度 +### 任务 DAG -复杂目标会被拆成带依赖关系的任务图，可并行任务并行跑，有依赖任务按顺序解锁，每个任务拥有 owner、状态、阻塞关系、结果和证据。 +复杂目标会被 Leader 拆成一张带依赖关系的任务图。每个任务声明后，系统自动计算反向边，形成完整的有向无环图。三个闸门决定一个任务能否执行：候选闸（任务状态为 dispatchable且无阻塞原因）、依赖闸（所有前置任务已完成）、合约闸（架构合约就绪）。前置任务完成后，被阻塞的后续任务自动解锁为 dispatchable，不需要人工逐个排期。WebUI 的任务面板以可视化图谱呈现整张 DAG，哪些完成了、哪些在跑、哪些被阻塞、依赖线怎么走——一目了然。 -#### 全状态机同步 +### 全状态机同步 -WebUI、TUI 和后端运行时收拢到统一状态链路，`session:runtime_state` 统一快照负责校准，流式事件负责体验。 +WebUI、TUI 和后端运行时共享同一个 EventEmitter 作为事件中枢。SseBridge 订阅 43 种会话级事件和 11 种 Agent 级事件，通过 agentId→sessionId 映射精准路由到对应前端连接。session:runtime_state 作为统一状态快照负责校准——前端重连或切屏回来时，直接从快照恢复完整状态，不走事件重放。流式事件负责实时体验，状态快照负责最终一致性。 -#### 工具系统 +### 自动验收回路 -内置 80+ 工具覆盖文件读写、代码搜索、AST 查询、Shell 执行、浏览器自动化、Git 操作、HTTP 请求、MCP 集成、Office 文档生成等。支持技能系统和 MCP 协议扩展。 +每个 `implement` 任务完成后，系统**自动**创建 Evaluator 验证任务，对实现结果进行多维度评估（功能正确性、代码质量、视觉设计、产品深度）。验证不通过时自动生成 Repair 修复任务，Worker 修复后再次验收，直到通过或达到修复上限。这不是 prompt 里说一句"记得检查"——是写死在执行流程里的质量闸门。 -### 快速开始 +### 黑板知识图谱 -1. 安装完成后运行 `lingxiao` -2. 首次启动引导配置模型 provider 和 API Key -3. 选择 TUI 模式或 WebUI 模式 -4. 给出目标，凌霄开始工作 +Agent 之间的结构化共识不是简单的聊天记录。Worker 将事实、意图、设计文档、合约、评审结论等 10 种节点类型写入共享知识图谱。Leader 每轮读取图谱分析，感知全局进展和认知对齐状态。Agent 之间不靠聊天传话，靠结构化图谱对齐认知。 -### 技术栈 +### 外部 Agent 驱动 -- **后端**：Node.js 24+、TypeScript、Fastify -- **前端**：React 19、Vite、Ink (TUI) -- **AI SDK**：OpenAI / Anthropic / Google / Amazon Bedrock -- **工具链**：Playwright、Sharp、Tesseract.js、MCP SDK +LingXiao 内置了 Claude Code Driver 和 Codex Driver，可以把 `claude` CLI 或 `codex` CLI 启动为 Worker 子进程——注入 LingXiao Worker 身份、流式解析输出、收集完成报告。这意味着你可以用 LingXiao 当总指挥，把 Claude Code 或 Codex CLI 当作具体干活的专家来调度。 -### 项目结构 +### 工具插件 & MCP 生态 -``` -lingxiao-coding/ -├── src/ # 后端源码（TypeScript） -├── web/ # WebUI 前端（React + Vite） -├── scripts/ # 构建/工具脚本 -├── skills/ # 技能包 -├── docs/ # 文档与截图 -├── assets/ # 静态资源 -├── package.json -└── LICENSE -``` - -### 开发 +完整的插件系统（plugin.json 清单、发现、安装、贡献枚举），支持注入 skills、MCP Server、自定义工具和 hooks（before/after 拦截修改工具调用）。内置 80+ 工具覆盖文件读写、代码搜索、AST 查询、Shell 执行、浏览器自动化、Git 操作、HTTP 请求、MCP 集成、Office 文档生成等。支持技能系统和 MCP 协议扩展。 -```bash -# 安装依赖 -npm install -npm install --prefix web +## 快速开始 -# 构建 -npm run build # 后端+前端 -npm run build:server # 仅后端 -npm run build:web # 仅前端 +### 前置要求 -# 运行 -npm start # 启动凌霄 -npm run dev:test-llm-request # 测试 LLM 连接 ``` - ---- - - - -## English - -### In One Sentence - -LingXiao upgrades "chatting with a model" into "commanding an observable, recoverable, auditable team of AI specialists." - -You provide the goal. The Leader breaks it down, builds a DAG, assembles a specialist team, and dispatches tasks. Workers execute in parallel — research, frontend, backend, testing, review, documentation, Git operations. WebUI/TUI sync the full runtime state in real time. - -### Screenshots - - - - - - - - - - - - - - - - - - -
WebUI Task PanelWebUI Agent Panel
Task panelAgent panel
TUI TerminalWebUI Chat & Blackboard
TUI terminalChat interface
- -### Installation - -#### Prerequisites - - [Node.js](https://nodejs.org/) >= 24.0.0 -- npm or compatible package manager +- npm 或兼容包管理器 +``` -#### Install from Source +### 源码安装 ```bash git clone https://github.com/hexian2001/lingxiao-coding.git @@ -214,21 +125,27 @@ npm run build npm link ``` -Then run: +安装完成后，终端直接运行： ```bash lingxiao ``` -First launch guides you through model and API key setup. +首次运行会引导你配置模型和 API Key，选择 TUI 模式或 WebUI 模式给出目标，凌霄开始工作。 + +> 注：如果初始化的模型和 API Key配置失败可以去/root/.lingxiao/settings.json查看更新，Windows是用户下的./lingxiao + +![LingXiao 使用界面](./docs/images/use.png) -#### Upgrade +详细文档可以访问[文档](https://hexian2001.github.io/lingxiao_website/getting-started/introduction/)查看。 + +### 升级 ```bash lingxiao upgrade ``` -Or manually: +或手动执行： ```bash cd lingxiao-coding @@ -237,63 +154,22 @@ npm install npm run build ``` -### Key Features - -- **Specialist Team**: Leader + Workers architecture, not a single agent -- **Task DAG**: Complex goals decomposed into dependency-aware task graphs -- **Full State Sync**: WebUI, TUI, and runtime share unified state -- **80+ Built-in Tools**: File I/O, code search, AST query, shell, browser automation, Git, HTTP, MCP, Office docs -- **Skill System**: Extensible knowledge and workflow injection -- **MCP Protocol**: Connect external systems via Model Context Protocol - -### Tech Stack - -- **Backend**: Node.js 24+, TypeScript, Fastify -- **Frontend**: React 19, Vite, Ink (TUI) -- **AI SDK**: OpenAI / Anthropic / Google / Amazon Bedrock -- **Toolchain**: Playwright, Sharp, Tesseract.js, MCP SDK - -### Development - -```bash -npm install -npm install --prefix web -npm run build -npm start -``` - ---- - -## Contributing - -欢迎提交 Issue 和 Pull Request。请确保： +## 许可 & 参与 -1. 代码通过 `npm run build` 构建 -2. 不引入新的硬编码密钥或敏感信息 -3. 遵循现有代码风格 +本项目采用 **AGPL v3 + 商业双授权** 模式：个人/开源使用免费，修改需开源；若作为 SaaS/API 对外提供服务，须向用户开放源码；商用闭源请联系购买商业授权（详见 [LICENSE](./LICENSE)）。 -## Links +欢迎提交 Issue 和 PR 参与共建（提交前请确保代码通过 `npm run build` 构建，且不引入硬编码密钥或敏感信息，遵循现有代码风格）。 -- **GitHub**: [hexian2001/lingxiao-coding](https://github.com/hexian2001/lingxiao-coding) -- **Issues**: [Report a bug or request a feature](https://github.com/hexian2001/lingxiao-coding/issues) -- **Commercial License**: hexian2001@github.com +商用授权联系：hexian2001@github.com ---- -## Community +## 连接 & 社区 -本开源项目已链接并认可 [LINUX DO 社区](https://linux.do)。 - -## 交流群 / QQ Group - -

- QQ群二维码 -

- -

- 扫码加入 QQ 交流群，获取最新动态、使用帮助和开发者交流。 -

+- **GitHub**：[hexian2001/lingxiao-coding](https://github.com/hexian2001/lingxiao-coding) +- **Issues**：[提交 Bug 或功能建议](https://github.com/hexian2001/lingxiao-coding/issues) +- **社区**：已链接并认可 [LINUX DO 社区](https://linux.do)

- Scan to join our QQ group for updates, support, and developer discussions. + QQ群二维码微信群二维码
+ 扫码加入 QQ/微信 交流群，获取最新动态、使用帮助和开发者交流

diff --git a/docs/images/QQ.jpg b/docs/images/QQ.jpg index 85b096c4..8cd37ed6 100644 Binary files a/docs/images/QQ.jpg and b/docs/images/QQ.jpg differ diff --git a/docs/images/TUI.png b/docs/images/TUI.png index c2a94a44..e85bb3bb 100644 Binary files a/docs/images/TUI.png and b/docs/images/TUI.png differ diff --git a/docs/images/use.png b/docs/images/use.png new file mode 100644 index 00000000..8b4d7be2 Binary files /dev/null and b/docs/images/use.png differ diff --git a/docs/images/weixin.jpg b/docs/images/weixin.jpg new file mode 100644 index 00000000..4a26f4c4 Binary files /dev/null and b/docs/images/weixin.jpg differ