MateClaw

中文

English

中文

English

Appearance

贡献指南 ​

感谢你对 MateClaw 的关注！本文档介绍如何参与项目开发。

开发环境搭建 ​

前置条件 ​

工具版本说明
JDK21+推荐 Eclipse Temurin
Maven3.9+后端构建
Node.js18+前端运行时
pnpm8+前端包管理
Git2.x版本控制

快速启动 ​

bash
# 1. 克隆仓库
git clone https://github.com/mate-labs/mateclaw.git
cd mateclaw

# 2. 设置环境变量
export DASHSCOPE_API_KEY=sk-your-key

# 3. 启动后端（端口 18088，H2 数据库）
cd mateclaw-server
mvn spring-boot:run

# 4. 启动前端（端口 5173，代理到 18088）
cd mateclaw-ui
pnpm install
pnpm dev

访问 http://localhost:5173，使用 admin / admin123 登录。

IDE 推荐配置 ​

  • 后端：IntelliJ IDEA，安装 Lombok 插件
  • 前端：VS Code，安装 Volar（Vue 3）+ ESLint + Tailwind CSS IntelliSense

代码规范 ​

后端规范 ​

包结构 ​

vip.mate.
├── agent          # Agent 引擎
├── planning       # 计划编排
├── tool           # 工具系统
├── skill          # 技能系统
├── channel        # 渠道适配
├── workspace/     # 会话与消息
│   └── conversation
├── llm            # 模型配置
├── memory         # 记忆系统
├── auth           # 认证
├── user           # 用户
├── config         # Spring 配置
├── common         # 公共工具
└── exception      # 全局异常处理

MyBatis Plus 规范 ​

  • 表前缀：所有表使用 mate_ 前缀
  • 命名映射：Java 驼峰命名自动映射到数据库下划线命名
  • 逻辑删除：所有实体包含 deleted 字段，使用 @TableLogic 注解
  • 时间字段：所有表包含 create_time 和 update_time 字段
  • ID 策略：使用自增主键

实体示例：

java
@Data
@TableName("mate_agent")
public class Agent {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String name;
    private String description;
    private String systemPrompt;        // 映射到 system_prompt
    private String agentType;           // 映射到 agent_type
    @TableLogic
    private Integer deleted;
    private LocalDateTime createTime;   // 映射到 create_time
    private LocalDateTime updateTime;   // 映射到 update_time
}

API 规范 ​

  • 所有接口前缀 /api/v1/
  • 使用 RESTful 风格
  • 统一响应格式：{"code": 200, "data": {...}, "message": "success"}
  • 异常通过全局异常处理器统一返回

工具类 ​

项目使用 Hutool 工具库，优先使用 Hutool 提供的工具方法，避免重复造轮子。

前端规范 ​

组件编写 ​

  • 使用 <script setup lang="ts"> 组合式 API
  • 组件文件名使用 PascalCase
  • Props 使用 TypeScript 类型定义
vue
<script setup lang="ts">
interface Props {
  title: string
  loading?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  loading: false,
})
</script>

<template>
  <div class="p-4">
    <h2 class="text-lg font-bold dark:text-white">{{ title }}</h2>
  </div>
</template>

Pinia Store 规范 ​

  • 每个领域一个 Store
  • Store 内部管理自己的状态，外部通过 action 修改
  • 异步操作在 action 中完成
typescript
export const useExampleStore = defineStore('example', () => {
  const items = ref<Item[]>([])
  const loading = ref(false)

  async function fetchItems() {
    loading.value = true
    try {
      const res = await api.getItems()
      items.value = res.data
    } finally {
      loading.value = false
    }
  }

  return { items, loading, fetchItems }
})

样式规范 ​

  • 优先使用 TailwindCSS 工具类
  • 支持暗色模式：使用 dark: 前缀
  • Element Plus 组件保持默认样式，必要时通过 CSS 变量覆盖
  • 路径别名：@ 指向 src/ 目录

Git 工作流 ​

分支规范 ​

分支用途
main主分支，保持稳定
feature/*新功能开发
fix/*Bug 修复
refactor/*代码重构
docs/*文档更新

Commit 规范 ​

使用约定式提交（Conventional Commits）：

<type>(<scope>): <description>

[optional body]

类型（type）：

类型说明
feat新功能
fixBug 修复
refactor重构
docs文档
style代码格式
test测试
chore构建/工具链变更

示例：

feat(agent): 添加 Plan-and-Execute 编排引擎
fix(chat): 修复 SSE 连接中断后未自动重连的问题
docs(api): 更新 Agent API 文档

PR 流程 ​

  1. 从 main 创建功能分支
  2. 完成开发并通过本地测试
  3. 提交 PR，描述清楚变更内容和原因
  4. 等待代码审查
  5. 审查通过后合并到 main

测试 ​

后端测试 ​

bash
cd mateclaw-server

# 运行全部测试
mvn test

# 运行单个测试类
mvn test -Dtest=AgentServiceTest

# 运行单个测试方法
mvn test -Dtest=AgentServiceTest#testCreateAgent

前端代码检查 ​

bash
cd mateclaw-ui

# ESLint 检查并自动修复
pnpm lint

构建验证 ​

提交 PR 前请确保以下命令通过：

bash
# 后端构建
cd mateclaw-server && mvn clean package -DskipTests

# 前端构建
cd mateclaw-ui && pnpm build

数据库变更 ​

如果需要修改数据库结构：

  1. 更新 db/schema.sql（DDL 变更）
  2. 如需初始数据，更新 db/data.sql
  3. 更新对应的 MyBatis Plus 实体类
  4. 在 PR 描述中说明数据库变更内容

注意事项：

  • 新表必须使用 mate_ 前缀
  • 必须包含 id、create_time、update_time、deleted 字段
  • 使用 bigint 作为主键类型

目录结构快速索引 ​

目录说明
mateclaw-server/Spring Boot 后端
mateclaw-ui/Vue 3 前端
mateclaw-desktop/桌面应用打包
docs/项目文档
db/数据库 Schema 和种子数据
.env.example环境变量模板
docker-compose.ymlDocker 部署配置