From fa5fb34c524c22a1582178d1c78f31f4c124d7c5 Mon Sep 17 00:00:00 2001 From: matevip Date: Fri, 10 Apr 2026 18:30:20 +0800 Subject: [PATCH] docs: redesign README with architecture diagrams and streamlined content --- README.md | 325 ++++++++----------------------- README_zh.md | 327 ++++++++------------------------ assets/architecture-biz-en.svg | 103 ++++++++++ assets/architecture-biz-zh.svg | 111 +++++++++++ assets/architecture-tech-en.svg | 197 +++++++++++++++++++ assets/architecture-tech-zh.svg | 201 ++++++++++++++++++++ 6 files changed, 767 insertions(+), 497 deletions(-) create mode 100644 assets/architecture-biz-en.svg create mode 100644 assets/architecture-biz-zh.svg create mode 100644 assets/architecture-tech-en.svg create mode 100644 assets/architecture-tech-zh.svg diff --git a/README.md b/README.md index 50a25c0b..4272fdc6 100644 --- a/README.md +++ b/README.md @@ -22,94 +22,32 @@ -MateClaw is a personal AI operating system built with **Java + Vue 3** and powered by [Spring AI Alibaba](https://github.com/alibaba/spring-ai-alibaba). +--- -It is not just a chat box. It is a system for building AI workers that can reason, use tools, remember context, search the live web, digest knowledge into structured Wiki pages, generate media, and show up across the channels where work actually happens. +MateClaw is a personal AI operating system built with **Java + Vue 3**, powered by [Spring AI Alibaba](https://github.com/alibaba/spring-ai-alibaba). -The idea is simple: +Not another chatbox. A complete system where AI agents reason, use tools, build memory, digest knowledge into Wiki pages, create multimodal content, and show up across every channel where work happens. -- Give each agent a clear role -- Give it the right tools and guardrails -- Let it keep memory instead of starting from zero -- Let it work across chat, channels, documents, and media -- Keep the whole system deployable by one team without turning into infrastructure theater +Three things make it different: + +1. **Agents do work, not just talk** — ReAct loops and Plan-and-Execute for real task completion +2. **Knowledge is shaped, not just stored** — An LLM-powered Wiki that digests raw material into structured, linked pages +3. **The whole widget** — One team, one deployment, hardware-to-software vertical integration from desktop app to IM channels --- -## What MateClaw Is +## Architecture -MateClaw sits at the intersection of four product ideas: +

+ Business Architecture +

-1. **An AI console** for direct interaction -2. **An agent runtime** for structured reasoning and tool use -3. **A knowledge system** that turns raw information into reusable memory and Wiki pages -4. **A deployment surface** that spans web, desktop, and external channels - -Most products do one of these. MateClaw is designed to make them work as one system. - ---- - -## Product Principles - -### 1. Agents should do work, not just talk - -MateClaw supports ReAct and Plan-and-Execute agents so the model can break work down, call tools, observe results, and continue instead of stopping at a polished paragraph. - -### 2. Knowledge should be digested, not endlessly re-read - -Raw files are useful, but structured knowledge is better. MateClaw includes an LLM Wiki knowledge base that converts source materials into linked Wiki pages with summaries, backlinks, and on-demand retrieval. - -### 3. Memory should compound - -Conversations should not disappear. MateClaw combines short-term context management, post-conversation extraction, workspace memory files, and scheduled consolidation so agents can build continuity over time. - -### 4. Tools need control, not chaos - -Powerful tools without boundaries are a liability. MateClaw includes tool guard rules, approval flows, file-path protection, and runtime filtering so capability does not become recklessness. - -### 5. AI should live where work already happens - -A useful assistant cannot be trapped in one web page. MateClaw connects to desktop, browser, and external messaging/work channels so the agent can meet users where decisions are being made. - ---- - -## What You Can Build With It - -### Personal AI Workspace - -- A persistent assistant with memory, tools, and workspace files -- A desktop app with bundled backend and auto-update -- A web console for direct chat, planning, and configuration - -### Team Knowledge Assistant - -- Ingest notes, documents, PDFs, and DOCX files -- Turn source materials into structured Wiki pages -- Let agents search, summarize, and read knowledge on demand - -### Tool-Using AI Workers - -- Agents that search the web, read files, use MCP tools, and execute workflows -- Role-specific skill packages with `SKILL.md` -- Approval and security controls for sensitive actions - -### Multimodal Content Workflows - -- Text-to-speech -- Speech-to-text -- Music generation -- Image generation -- Video generation - -### Multi-Channel AI Presence - -- Web console -- DingTalk -- Feishu -- WeChat Work -- Telegram -- Discord -- QQ +
+Technical Architecture +

+ Technical Architecture +

+
--- @@ -117,77 +55,38 @@ A useful assistant cannot be trapped in one web page. MateClaw connects to deskt ### Agent Runtime -- **ReAct agents** for thought → action → observation loops -- **Plan-and-Execute agents** for decomposing complex work into ordered steps -- **Dynamic agent configuration** loaded at runtime -- **Multi-agent setup** with separate prompts, personalities, and tool scopes -- **Runtime resilience** including context pruning, smart truncation, stale stream cleanup, and recovery for longer tasks +- **ReAct agents** — Think, act, observe, repeat. Iterative reasoning that gets things done +- **Plan-and-Execute** — Decompose complex work into ordered steps, then execute each one +- **Dynamic configuration** — Load agent personality, tools, and constraints from the database at runtime +- **Runtime resilience** — Context pruning, smart truncation, stale stream cleanup, and recovery -### Knowledge and Memory +### Knowledge & Memory -- **LLM Wiki knowledge base** for structured, linked, AI-digested knowledge -- **Workspace memory files** such as `AGENTS.md`, `SOUL.md`, `PROFILE.md`, `MEMORY.md`, and daily notes -- **Post-conversation extraction** to preserve useful information automatically -- **Scheduled consolidation** so memory quality improves instead of just growing -- **Dreaming and emergence workflows** for longer-horizon memory refinement +- **LLM Wiki** — AI-powered knowledge base that digests raw materials into structured, linked pages with summaries +- **Workspace memory** — `AGENTS.md`, `SOUL.md`, `PROFILE.md`, `MEMORY.md`, daily notes +- **Memory lifecycle** — Post-conversation extraction, scheduled consolidation, dreaming workflows +- **Compound memory** — Understanding improves over time instead of resetting every query -### Tools, Skills, and Search +### Tools, Skills & MCP -- **Built-in tools** for web search, file operations, memory access, date/time, and more -- **Advanced web search** with provider chaining, fallback strategies, and live information support -- **MCP integration** across stdio, SSE, and Streamable HTTP transports -- **Skill system** with installable `SKILL.md` packages -- **ClawHub marketplace** for discovering and installing skills -- **Tool guard and approval** for sensitive operations +- **Built-in tools** — Web search, file ops, memory access, date/time, and more +- **MCP integration** — stdio, SSE, and Streamable HTTP transports +- **Skill system** — Installable `SKILL.md` packages with ClawHub marketplace +- **Tool guard** — Approval flows, file-path protection, runtime filtering ### Multimodal Creation -- **Text-to-speech** for read-aloud and voice output -- **Speech-to-text** for audio transcription -- **Music generation** -- **Image generation** with multiple providers -- **Video generation** with async task handling +Text-to-speech · Speech-to-text · Image generation · Music generation · Video generation ### Model Flexibility -Configure models in the web UI. MateClaw supports cloud and local model providers including: - -- DashScope -- OpenAI -- Anthropic -- Google Gemini -- DeepSeek -- Kimi -- MiniMax -- Zhipu AI -- Volcano Engine -- OpenRouter -- Ollama -- LM Studio -- llama.cpp -- MLX +14+ providers including DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, MLX, and more. Configure everything in the web UI. ### Surfaces -- **Web app** for chat, agent management, MCP, models, tools, channels, and security -- **Desktop app** with bundled JRE 21 and backend -- **External channels** for production-facing assistant workflows - ---- - -## Why The Wiki Matters - -Most AI systems treat knowledge like a warehouse of raw fragments. - -MateClaw adds another layer: a structured Wiki that AI can build and maintain. Instead of retrieving arbitrary chunks from source files every time, the system can pre-digest information into clean pages with summaries and links. - -That changes the product in three ways: - -- Agents waste less context on raw material -- Knowledge becomes easier to inspect and edit by humans -- Understanding improves over time instead of resetting on every query - -This is the difference between storing information and shaping it. +- **Web console** — Chat, agents, tools, skills, knowledge, models, security, settings +- **Desktop app** — Electron with bundled JRE 21, no Java installation needed +- **Channels** — DingTalk, Feishu, WeChat Work, Telegram, Discord, QQ --- @@ -195,86 +94,32 @@ This is the difference between storing information and shaping it. ### Prerequisites -- Java 17+ -- Node.js 18+ and pnpm -- Maven 3.9+ (or use `mvnw`) -- At least one LLM API key such as [DashScope](https://dashscope.aliyun.com/) +- Java 17+ · Node.js 18+ · pnpm · Maven 3.9+ -### Option 1: Local Development - -**Backend** +### Local Development ```bash +# Backend cd mateclaw-server -export DASHSCOPE_API_KEY=your-key-here -mvn spring-boot:run -``` +mvn spring-boot:run # http://localhost:18088 -Backend: - -- App: `http://localhost:18088` -- H2 Console: `http://localhost:18088/h2-console` -- Swagger UI: `http://localhost:18088/swagger-ui.html` - -**Frontend** - -```bash +# Frontend cd mateclaw-ui -pnpm install -pnpm dev +pnpm install && pnpm dev # http://localhost:5173 ``` -Frontend: +Login: `admin` / `admin123` -- App: `http://localhost:5173` - -**Login** - -- Username: `admin` -- Password: `admin123` - -### Option 2: Docker +### Docker ```bash cp .env.example .env -docker compose up -d +docker compose up -d # http://localhost:18080 ``` -Default service: +### Desktop App -- `http://localhost:18080` - -### Option 3: Desktop App - -Download installers from [GitHub Releases](https://github.com/matevip/mateclaw/releases). - -The desktop app bundles **JRE 21 + the Spring Boot backend**, so users do not need to install Java separately. - -> macOS: if the app is blocked on first launch, use right-click → Open, or allow it in Privacy & Security. - ---- - -## Architecture - -```text -mateclaw/ -├── mateclaw-server/ Spring Boot backend -├── mateclaw-ui/ Vue 3 SPA frontend -├── mateclaw-desktop/ Electron desktop app -├── docs/ VitePress documentation -├── docker-compose.yml -└── .env.example -``` - -Backend domains include: - -- `agent/` for runtime and orchestration -- `tool/` for built-in tools and MCP integration -- `skill/` for skill installation and execution -- `memory/` for extraction, consolidation, and dreaming -- `wiki/` for knowledge base and structured Wiki processing -- `channel/` for external platform adapters -- `workspace/` for files, messages, and conversations +Download from [GitHub Releases](https://github.com/matevip/mateclaw/releases). Bundles JRE 21 — no Java needed. --- @@ -282,81 +127,65 @@ Backend domains include: | Layer | Technology | |-------|------------| -| Backend | Spring Boot 3.5 + Spring AI Alibaba 1.1 | -| Agent Runtime | StateGraph | +| Backend | Spring Boot 3.5 · Spring AI Alibaba 1.1 | +| Agent | StateGraph Runtime | | Database | H2 (dev) / MySQL 8.0+ (prod) | | ORM | MyBatis Plus 3.5 | | Auth | Spring Security + JWT | -| Frontend | Vue 3 + TypeScript + Vite | -| State | Pinia | -| UI | Element Plus | -| Styling | TailwindCSS 4 | -| Desktop | Electron + electron-updater | -| Docs | VitePress | +| Frontend | Vue 3 · TypeScript · Vite | +| UI | Element Plus · TailwindCSS 4 | +| Desktop | Electron · electron-updater | + +--- + +## Project Structure + +``` +mateclaw/ +├── mateclaw-server/ Spring Boot backend +├── mateclaw-ui/ Vue 3 SPA frontend +├── mateclaw-desktop/ Electron desktop app +├── docker-compose.yml +└── .env.example +``` --- ## Documentation -| Topic | Description | -|-------|-------------| -| [Introduction](https://mateclaw.mate.vip/en/intro) | Product overview and core concepts | -| [Quick Start](https://mateclaw.mate.vip/en/quickstart) | Local, Docker, and desktop setup | -| [Console](https://mateclaw.mate.vip/en/console) | Web console and day-to-day usage | -| [Agents](https://mateclaw.mate.vip/en/agents) | ReAct, Plan-and-Execute, and runtime design | -| [Models](https://mateclaw.mate.vip/en/models) | Model provider setup | -| [Tools](https://mateclaw.mate.vip/en/tools) | Built-in tools and extension model | -| [Skills](https://mateclaw.mate.vip/en/skills) | Skill packages and marketplace | -| [MCP](https://mateclaw.mate.vip/en/mcp) | Model Context Protocol integration | -| [Memory](https://mateclaw.mate.vip/en/memory) | Memory architecture | -| [Channels](https://mateclaw.mate.vip/en/channels) | External channel integration | -| [Security](https://mateclaw.mate.vip/en/security) | Guardrails and approval | -| [Desktop](https://mateclaw.mate.vip/en/desktop) | Desktop application guide | -| [API Reference](https://mateclaw.mate.vip/en/api) | REST API | -| [FAQ](https://mateclaw.mate.vip/en/faq) | Troubleshooting | +Full docs at **[claw.mate.vip/docs](https://claw.mate.vip/docs)** --- ## Roadmap -Current focus areas include: - -- richer multi-agent collaboration -- deeper multimodal understanding -- smarter model routing -- stronger long-term memory -- richer ClawHub ecosystem -- more channels and desktop coverage +- Richer multi-agent collaboration +- Smarter model routing +- Deeper multimodal understanding +- Stronger long-term memory +- Richer ClawHub ecosystem --- ## Contributing -MateClaw is open to product, code, docs, and integration contributions. - ```bash git clone https://github.com/matevip/mateclaw.git cd mateclaw - -cd mateclaw-server -mvn clean compile - -cd ../mateclaw-ui -pnpm install -pnpm dev +cd mateclaw-server && mvn clean compile +cd ../mateclaw-ui && pnpm install && pnpm dev ``` --- ## Why The Name -**Mate** means companion. -**Claw** means capability. +**Mate** is companion. **Claw** is capability. -The product is meant to feel like both: a system that stays with you, and a system that can actually grab work and move it. +A system that stays with you, and a system that grabs work and moves it. --- ## License -MateClaw is released under the [Apache License 2.0](LICENSE). +[Apache License 2.0](LICENSE) diff --git a/README_zh.md b/README_zh.md index 11c575f6..e8d2dd45 100644 --- a/README_zh.md +++ b/README_zh.md @@ -22,259 +22,104 @@ +--- + MateClaw 是一个基于 **Java + Vue 3** 构建的个人 AI 操作系统，由 [Spring AI Alibaba](https://github.com/alibaba/spring-ai-alibaba) 驱动。 -它不是另一个聊天框，而是一整套 AI 工作系统：能推理、能调工具、能记住上下文、能联网、能把原始资料消化成 Wiki、能生成多模态内容，也能出现在真正发生工作的渠道里。 +不是又一个聊天框。这是一个完整的 AI 工作系统——智能体能推理、用工具、构建记忆、把原始资料消化成 Wiki、创作多模态内容，还能出现在每一个真正发生工作的渠道里。 -这个产品的核心想法很简单： +三件事让它与众不同： -- 给每个 Agent 清晰的角色 -- 给它真正可用的工具和边界 -- 让它拥有记忆，而不是每次从零开始 -- 让它跨聊天、文档、知识、媒体和渠道协同工作 -- 保持整套系统能被一个团队部署、理解和持续迭代 +1. **智能体做事，不只聊天** — ReAct 循环推理 + 计划执行，完成真正的任务 +2. **知识被塑造，而非仅仅被存储** — LLM 驱动的 Wiki 把原始资料消化成结构化的链接页面 +3. **端到端整合** — 一个团队、一次部署，从桌面端到 IM 渠道的完整体验控制 --- -## MateClaw 到底是什么 +## 架构全景 -MateClaw 不是单点产品，而是 4 个产品层合成的一个系统： +

+ 业务架构 +

-1. **AI 控制台**：人直接和 AI 交互 -2. **Agent 运行时**：让模型分步推理、调用工具、执行任务 -3. **知识系统**：把原始信息沉淀成记忆和结构化 Wiki -4. **交付面**：覆盖 Web、桌面和外部渠道 - -大多数产品只做其中一层。MateClaw 的目标，是把这四层做成一个完整工作系统。 - ---- - -## 产品思路 - -### 1. Agent 不该只会聊天，应该会干活 - -MateClaw 支持 ReAct 和 Plan-and-Execute。模型不只是生成回答，而是能拆解任务、调用工具、观察结果，再继续推进。 - -### 2. 知识不该反复原样读取，而应该被消化 - -原始文档很重要，但结构化知识更重要。MateClaw 内置 LLM Wiki 知识库，把文本、PDF、DOCX 等材料消化成可链接、可搜索、可编辑的 Wiki 页面。 - -### 3. 记忆应该越用越值钱 - -会话结束不该等于遗忘。MateClaw 把短期上下文、对话后提取、工作空间记忆文件和定时整合放进同一套体系，让 Agent 能积累连续性。 - -### 4. 工具要强，但不能失控 - -没有边界的工具系统不是能力，是事故源。MateClaw 提供工具防护、审批、路径校验和运行时过滤，让强能力能被放心使用。 - -### 5. AI 必须出现在真实工作的地方 - -真正有用的 AI 不能只困在一个网页里。MateClaw 连接桌面、Web 和外部消息渠道，让 Agent 出现在任务发生的地方。 - ---- - -## 你可以拿它做什么 - -### 个人 AI 工作台 - -- 一个有记忆、有工具、有工作空间文件的长期助手 -- 一个开箱即用的桌面应用 -- 一个用于聊天、规划和配置的 Web 控制台 - -### 团队知识助手 - -- 导入笔记、文档、PDF、DOCX -- 把原始材料转成结构化 Wiki 页面 -- 让 Agent 按需搜索、总结、阅读知识，而不是反复扫描原文 - -### 会用工具的 AI Worker - -- 能联网搜索、读文件、接 MCP 工具、执行工作流的 Agent -- 按角色安装技能包 -- 对敏感动作进行审批和防护 - -### 多模态内容生产系统 - -- 文字转语音 -- 语音转文字 -- 音乐生成 -- 图片生成 -- 视频生成 - -### 多渠道 AI 存在 - -- Web 控制台 -- 钉钉 -- 飞书 -- 企业微信 -- Telegram -- Discord -- QQ +
+技术架构 +

+ 技术架构 +

+
--- ## 核心能力 -### Agent 运行时 +### 智能体引擎 -- **ReAct Agent**：支持思考 → 行动 → 观察循环 -- **Plan-and-Execute Agent**：适合拆解复杂任务并按步骤执行 -- **动态 Agent 配置**：运行时加载，不需要把配置写死 -- **多 Agent 体系**：每个 Agent 有自己的提示词、人格、工具范围 -- **更稳定的长任务执行**：支持上下文裁剪、智能截断、陈旧流清理、恢复机制 +- **ReAct 智能体** — 思考、行动、观察、循环。迭代推理直到完成任务 +- **计划-执行智能体** — 将复杂工作分解为有序步骤，逐一执行 +- **动态配置** — 运行时从数据库加载智能体的人格、工具和约束 +- **运行时韧性** — 上下文裁剪、智能截断、僵死流清理、异常恢复 ### 知识与记忆 -- **LLM Wiki 知识库**：把原始材料转成结构化、可链接的 Wiki -- **工作空间记忆文件**：如 `AGENTS.md`、`SOUL.md`、`PROFILE.md`、`MEMORY.md`、daily notes -- **对话后自动提取**：把有价值的信息沉淀下来 -- **定时整合**：不是一味堆积，而是持续整理 -- **Dreaming / Emergence 记忆机制**：用于更长时间尺度上的记忆优化 +- **LLM Wiki 知识库** — AI 驱动的知识库，将原始资料消化为结构化、有链接的页面 +- **工作区记忆** — `AGENTS.md`、`SOUL.md`、`PROFILE.md`、`MEMORY.md`、每日笔记 +- **记忆生命周期** — 对话后自动提取、定时整理、记忆涌现工作流 +- **记忆应该积累** — 理解随时间加深，而非每次查询都从零开始 -### 工具、技能与搜索 +### 工具、技能与 MCP -- **内置工具**：搜索、文件、记忆、时间等能力 -- **更强的联网搜索**：支持多 Provider、回退链和实时信息获取 -- **MCP 集成**：支持 stdio、SSE、Streamable HTTP -- **技能系统**：通过 `SKILL.md` 安装和组织技能 -- **ClawHub 市场**：发现和安装技能 -- **工具防护与审批**：保障高权限操作的可控性 +- **内置工具** — 联网搜索、文件操作、记忆访问、日期时间等 +- **MCP 集成** — 支持 stdio、SSE、Streamable HTTP 三种传输 +- **技能系统** — 可安装的 `SKILL.md` 技能包 + ClawHub 市场 +- **工具防护** — 审批流、文件路径保护、运行时过滤 ### 多模态创作 -- **文字转语音** -- **语音转文字** -- **音乐生成** -- **图片生成** -- **视频生成** +语音合成 · 语音识别 · 图片生成 · 音乐生成 · 视频生成 ### 模型灵活性 -可在 Web 界面中配置云端与本地模型，支持： +14+ 供应商支持，包括 DashScope、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、Ollama、LM Studio、MLX 等。在 Web 界面中配置一切。 -- DashScope -- OpenAI -- Anthropic -- Google Gemini -- DeepSeek -- Kimi -- MiniMax -- 智谱 AI -- 火山引擎 -- OpenRouter -- Ollama -- LM Studio -- llama.cpp -- MLX +### 用户触点 -### 使用入口 - -- **Web 应用**：聊天、Agent、MCP、模型、工具、渠道、安全配置 -- **桌面应用**：内置 JRE 21 和后端 -- **外部渠道**：适合真正面向业务场景的接入 - ---- - -## 为什么 Wiki 很重要 - -多数 AI 系统把知识当成“原始碎片仓库”。 - -MateClaw 多做了一层：让 AI 把知识整理成结构化 Wiki。不是每次临时从原始文档里切几段，而是先把知识变成清晰页面，再按需读取。 - -这会带来三个变化： - -- Agent 不再把大量上下文浪费在原始材料上 -- 人可以直接检查、编辑、维护知识结构 -- 知识会随着使用而变得更清晰，而不是每次查询都重新理解 - -这就是“存信息”和“塑造知识”的区别。 +- **Web 控制台** — 对话、智能体、工具、技能、知识、模型、安全、设置 +- **桌面端** — Electron + 内嵌 JRE 21，无需安装 Java +- **多渠道** — 钉钉、飞书、企业微信、Telegram、Discord、QQ --- ## 快速开始 -### 前置条件 +### 环境要求 -- Java 17+ -- Node.js 18+ 和 pnpm -- Maven 3.9+（或使用 `mvnw`） -- 至少一个 LLM API Key，例如 [DashScope](https://dashscope.aliyun.com/) +- Java 17+ · Node.js 18+ · pnpm · Maven 3.9+ -### 方式一：本地开发 - -**启动后端** +### 本地开发 ```bash +# 后端 cd mateclaw-server -export DASHSCOPE_API_KEY=your-key-here -mvn spring-boot:run -``` +mvn spring-boot:run # http://localhost:18088 -后端地址： - -- 应用：`http://localhost:18088` -- H2 Console：`http://localhost:18088/h2-console` -- Swagger UI：`http://localhost:18088/swagger-ui.html` - -**启动前端** - -```bash +# 前端 cd mateclaw-ui -pnpm install -pnpm dev +pnpm install && pnpm dev # http://localhost:5173 ``` -前端地址： +默认登录：`admin` / `admin123` -- 应用：`http://localhost:5173` - -**登录** - -- 用户名：`admin` -- 密码：`admin123` - -### 方式二：Docker +### Docker 部署 ```bash cp .env.example .env -docker compose up -d +docker compose up -d # http://localhost:18080 ``` -默认服务地址： +### 桌面端 -- `http://localhost:18080` - -### 方式三：桌面应用 - -从 [GitHub Releases](https://github.com/matevip/mateclaw/releases) 下载桌面安装包。 - -桌面应用内置 **JRE 21 + Spring Boot 后端**，无需额外安装 Java。 - -> macOS：如果首次打开被系统拦截，使用右键 → 打开，或在隐私与安全性中手动允许。 - ---- - -## 架构 - -```text -mateclaw/ -├── mateclaw-server/ Spring Boot 后端 -├── mateclaw-ui/ Vue 3 SPA 前端 -├── mateclaw-desktop/ Electron 桌面端 -├── docs/ VitePress 文档 -├── docker-compose.yml -└── .env.example -``` - -后端核心领域包括： - -- `agent/`：Agent 运行时与编排 -- `tool/`：内置工具与 MCP 集成 -- `skill/`：技能安装与执行 -- `memory/`：提取、整合、dreaming -- `wiki/`：知识库与结构化 Wiki 处理 -- `channel/`：外部渠道适配 -- `workspace/`：文件、消息、会话 +从 [GitHub Releases](https://github.com/matevip/mateclaw/releases) 下载安装包。内嵌 JRE 21，无需额外安装 Java。 --- @@ -282,81 +127,65 @@ mateclaw/ | 层次 | 技术 | |------|------| -| 后端 | Spring Boot 3.5 + Spring AI Alibaba 1.1 | -| Agent Runtime | StateGraph | -| 数据库 | H2（开发）/ MySQL 8.0+（生产） | +| 后端 | Spring Boot 3.5 · Spring AI Alibaba 1.1 | +| 智能体 | StateGraph 运行时 | +| 数据库 | H2（开发）/ MySQL 8.0+（生产）| | ORM | MyBatis Plus 3.5 | | 认证 | Spring Security + JWT | -| 前端 | Vue 3 + TypeScript + Vite | -| 状态管理 | Pinia | -| UI | Element Plus | -| 样式 | TailwindCSS 4 | -| 桌面端 | Electron + electron-updater | -| 文档 | VitePress | +| 前端 | Vue 3 · TypeScript · Vite | +| UI | Element Plus · TailwindCSS 4 | +| 桌面端 | Electron · electron-updater | + +--- + +## 项目结构 + +``` +mateclaw/ +├── mateclaw-server/ Spring Boot 后端 +├── mateclaw-ui/ Vue 3 SPA 前端 +├── mateclaw-desktop/ Electron 桌面端 +├── docker-compose.yml +└── .env.example +``` --- ## 文档 -| 主题 | 说明 | -|------|------| -| [项目介绍](https://mateclaw.mate.vip/zh/intro) | 产品定位与核心概念 | -| [快速开始](https://mateclaw.mate.vip/zh/quickstart) | 本地、Docker、桌面启动 | -| [控制台](https://mateclaw.mate.vip/zh/console) | Web 控制台日常使用 | -| [Agents](https://mateclaw.mate.vip/zh/agents) | ReAct、Plan-and-Execute 与运行时设计 | -| [模型配置](https://mateclaw.mate.vip/zh/models) | 模型 Provider 配置 | -| [工具系统](https://mateclaw.mate.vip/zh/tools) | 内置工具与扩展能力 | -| [技能系统](https://mateclaw.mate.vip/zh/skills) | 技能包与市场 | -| [MCP](https://mateclaw.mate.vip/zh/mcp) | Model Context Protocol 集成 | -| [记忆系统](https://mateclaw.mate.vip/zh/memory) | 记忆架构 | -| [渠道接入](https://mateclaw.mate.vip/zh/channels) | 外部渠道适配 | -| [安全机制](https://mateclaw.mate.vip/zh/security) | 防护与审批 | -| [桌面应用](https://mateclaw.mate.vip/zh/desktop) | 桌面端使用指南 | -| [API 参考](https://mateclaw.mate.vip/zh/api) | REST API | -| [常见问题](https://mateclaw.mate.vip/zh/faq) | 排障与说明 | +完整文档请访问 **[claw.mate.vip/docs](https://claw.mate.vip/docs)** --- ## 路线图 -当前重点方向包括： - -- 更强的多 Agent 协作 -- 更深的多模态理解 -- 更聪明的模型路由 +- 更丰富的多智能体协作 +- 更智能的模型路由 +- 更深度的多模态理解 - 更强的长期记忆 - 更丰富的 ClawHub 生态 -- 更多渠道与桌面端覆盖 --- ## 参与贡献 -MateClaw 欢迎产品、代码、文档、集成四类贡献。 - ```bash git clone https://github.com/matevip/mateclaw.git cd mateclaw - -cd mateclaw-server -mvn clean compile - -cd ../mateclaw-ui -pnpm install -pnpm dev +cd mateclaw-server && mvn clean compile +cd ../mateclaw-ui && pnpm install && pnpm dev ``` --- -## 为什么叫 MateClaw +## 为什么叫这个名字 -**Mate** 是伙伴。 -**Claw** 是能力。 +**Mate** 是陪伴。**Claw** 是能力。 -这个产品想给人的感受，就是两者同时成立：它不是只陪你说话，也能真正抓住任务，把事情往前推进。 +一个陪在你身边的系统，一个能真正抓住工作、推动它前进的系统。 --- ## 许可证 -MateClaw 基于 [Apache License 2.0](LICENSE) 发布。 +[Apache License 2.0](LICENSE) diff --git a/assets/architecture-biz-en.svg b/assets/architecture-biz-en.svg new file mode 100644 index 00000000..071c9a32 --- /dev/null +++ b/assets/architecture-biz-en.svg @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MateClaw Business Architecture + AN AI OPERATING SYSTEM — THE COMPLETE PICTURE + + + + + Agent + Reason · Plan · Execute + ReAct + Plan-Execute + + + + + User Surfaces + Web Console + Desktop + IM Channels + API + + + + + + + Knowledge + LLM Wiki KB + Structured Digestion + Memory Extraction + Workspace Context + Shape it, don't just store it + + + + + + + Tools & Skills + Built-in Tool Suite + MCP Protocol + Skill Packages + Hub + Guard + Approval + Capability needs boundaries + + + + + + + Memory + Short-term Context + Extraction + Consolidation + Memory should compound + + + + + + + Multimodal + TTS · STT · Voice + Image · Music · Video + AI beyond text + + + + + + Model Layer + Cloud + Local · 14+ Providers + + + + + Mate is companion. Claw is capability. + diff --git a/assets/architecture-biz-zh.svg b/assets/architecture-biz-zh.svg new file mode 100644 index 00000000..e2af219d --- /dev/null +++ b/assets/architecture-biz-zh.svg @@ -0,0 +1,111 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MateClaw 业务架构 + BUSINESS ARCHITECTURE — AI 工作系统全景 + + + + + 智能体 + 推理 · 规划 · 执行 + ReAct + Plan-Execute + + + + + 用户触点 + Web 控制台 + 桌面端 + IM 渠道 + API + + + + + + + + 知识系统 + Wiki 知识库 + 结构化消化 + 链接 + 记忆提取与整理 + 工作区上下文文件 + 知识不是存储，是塑造 + + + + + + + + 工具与技能 + 内置工具集 + MCP 协议扩展 + 技能包 + ClawHub + 安全审批与防护 + 能力需要边界 + + + + + + + + 记忆层 + 短期上下文管理 + 长期提取 + 定时整理 + 记忆应该积累而非消散 + + + + + + + + 多模态创作 + 语音合成 · 语音识别 + 图片 · 音乐 · 视频生成 + AI 不只是文字 + + + + + + + 模型供应 + 云端 + 本地 · 14+ 供应商 + + + + + + + Mate 是陪伴，Claw 是能力 + diff --git a/assets/architecture-tech-en.svg b/assets/architecture-tech-en.svg new file mode 100644 index 00000000..1428d099 --- /dev/null +++ b/assets/architecture-tech-en.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MateClaw Technical Architecture + THE WHOLE WIDGET + + + + + PRESENTATION + + + + Vue 3 SPA + Element Plus + Tailwind + + + + Electron Desktop + Bundled JRE 21 + + + + SSE Streaming + Real-time Chat + Tools + + + + REST API + SpringDoc OpenAPI + + + + Channel Adapters + DingTalk / Feishu / WeCom + + + + Webhooks + Telegram / Discord / QQ + + + + + + AGENT ENGINE + + + + ReAct Agent + Think → Act → Observe + Iterative Reasoning Loop + + + + Plan-Execute + Decompose → Step Execute + Complex Task Orchestration + + + + Tool System + Built-in + MCP + Skills + Approval + Guard Rules + + + + Memory System + Short-term + Extraction + Consolidation + Dreaming + + + + Wiki KB + Knowledge + Digestion + + + + + + CORE SERVICES + + + + Spring Boot 3.5 + App Framework + Spring MVC + SSE + + + + Spring Security + Auth Layer + JWT + RBAC + + + + MyBatis Plus + Persistence + Logical Delete + Mapping + + + + + + MODEL PROVIDERS + + + + Spring AI + Unified Abstraction + Chat + Embedding + + + + Cloud Models + DashScope · OpenAI + Anthropic · Gemini · More + + + + Local Models + Ollama · LM Studio + MLX · llama.cpp + + + + + + DATA & INFRASTRUCTURE + + + + H2 / MySQL 8 + Relational Storage + + + + File System + Memory + Wiki + Files + + + + MCP Protocol + stdio / SSE / HTTP + + + + Docker Compose + One-click Deploy + + + + Cron Scheduler + Task Automation + + + + Multimodal + TTS / STT / Img / Music / Vid + + + + + + + + + Java 17+ · Spring Boot 3.5 · Spring AI Alibaba · Vue 3 · TypeScript · Vite · Electron + + claw.mate.vip + diff --git a/assets/architecture-tech-zh.svg b/assets/architecture-tech-zh.svg new file mode 100644 index 00000000..822f0b14 --- /dev/null +++ b/assets/architecture-tech-zh.svg @@ -0,0 +1,201 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MateClaw 技术架构 + TECHNICAL ARCHITECTURE + + + + + 表现层 + + + + + Vue 3 SPA + Element Plus + Tailwind + + + + Electron 桌面端 + JRE 21 内嵌 + + + + SSE 流式传输 + 实时对话 + 工具流 + + + + REST API + SpringDoc OpenAPI + + + + 多渠道适配器 + 钉钉 / 飞书 / 企微 / TG + + + + Webhook + Discord / QQ + + + + + + 智能体引擎 + + + + ReAct Agent + 思考 → 行动 → 观察 + 循环推理引擎 + + + + Plan-Execute + 计划分解 → 逐步执行 + 复杂任务编排 + + + + 工具系统 + 内置 + MCP + 技能包 + 安全审批 + 防护规则 + + + + 记忆系统 + 短期上下文 + 长期提取 + 定时整理 + 记忆涌现 + + + + Wiki KB + 知识消化 + 结构化页面 + + + + + + 核心服务层 + + + + Spring Boot 3.5 + 应用框架 + Spring MVC + SSE + + + + Spring Security + 认证授权 + JWT + RBAC + + + + MyBatis Plus + 数据持久层 + 逻辑删除 + 自动映射 + + + + + + 模型供应层 + + + + Spring AI + 统一模型抽象 + Chat + Embedding + + + + 云端模型 + DashScope · OpenAI + Anthropic · Gemini · 更多 + + + + 本地模型 + Ollama · LM Studio + MLX · llama.cpp + + + + + + 数据与基础设施 + + + + H2 / MySQL 8 + 关系型存储 + + + + 文件系统 + 记忆 + Wiki + 附件 + + + + MCP 协议 + stdio / SSE / HTTP + + + + Docker Compose + 一键部署 + + + + 定时任务 + Cron 调度引擎 + + + + 多模态引擎 + TTS / STT / 图 / 音 / 视 + + + + + + + + + + Java 17+ · Spring Boot 3.5 · Spring AI Alibaba · Vue 3 · TypeScript · Vite · Electron + + claw.mate.vip +