Contributing

Thank you for your interest in contributing to MateClaw. This guide covers the development setup, coding conventions, and pull request workflow.

Getting Started

1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/mateclaw.git
cd mateclaw

2. Set Up the Backend

cd mateclaw-server
export DASHSCOPE_API_KEY=your-key
mvn spring-boot:run

3. Set Up the Frontend

cd mateclaw-ui
pnpm install
pnpm dev

4. Verify

Open http://localhost:5173, log in with admin / admin123, and send a test message.

Development Workflow

1. Create a feature branch from main:

git checkout -b feat/your-feature-name

2. Make your changes with clear, incremental commits
3. Test your changes (see Testing section below)
4. Push and open a pull request

Branch Naming

Prefix	Purpose	Example
feat/	New feature	feat/voice-input
fix/	Bug fix	fix/sse-reconnect
docs/	Documentation	docs/api-reference
refactor/	Code refactoring	refactor/agent-state
chore/	Build, deps, tooling	chore/upgrade-spring-boot

Commit Messages

Follow the Conventional Commits format:

type(scope): brief description

Optional longer description explaining the change.

Examples:

feat(agent): add max iteration limit to ReAct loop
fix(channel): handle DingTalk message encoding correctly
docs(tools): add examples for WebSearchTool
chore(deps): upgrade Spring Boot to 3.5.1

Backend Conventions

Package Structure

Place new code in the appropriate vip.mate.* package:

You are adding...	Package
A new tool	vip.mate.tool
A new channel adapter	vip.mate.channel
A new agent type	vip.mate.agent
Utility code	vip.mate.common

Code Style

• Java 17+ features are encouraged (records, sealed classes, text blocks, pattern matching)
• Use constructor injection (not field injection) for Spring beans
• Follow existing naming: XxxService, XxxController, XxxMapper
• All database tables use the mate_ prefix
• Use MyBatis Plus for data access (not JPA)

Adding a New Tool

1. Create a class in vip.mate.tool:

@Component
public class MyNewTool {

    @Tool(description = "Description for the LLM")
    public String myMethod(
            @ToolParam(description = "Parameter description") String input) {
        // Implementation
        return "result";
    }
}

2. If the tool is dangerous, add it to the ToolGuard list in application.yml
3. Add a test class

Adding a New Channel

1. Create a class in vip.mate.channel implementing ChannelAdapter
2. Register the webhook endpoint in a controller
3. Add configuration properties
4. Update the documentation

Frontend Conventions

Code Style

• Use the Composition API with <script setup> for all new components
• TypeScript is required -- no any types unless absolutely necessary
• Use Pinia stores for shared state, local ref/reactive for component state
• Prefer Element Plus components over custom implementations
• Use TailwindCSS utilities; avoid inline styles
• Use the @ path alias for imports

Adding a New Page

1. Create the view component in views/
2. Add a route in router/
3. Add translations in i18n/zh-CN.ts and i18n/en-US.ts
4. If the page has shared state, create a Pinia store in stores/

Component Structure

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { useAgentStore } from '@/stores/agent';

const agentStore = useAgentStore();
const loading = ref(false);

onMounted(async () => {
  loading.value = true;
  await agentStore.fetchAgents();
  loading.value = false;
});
</script>

<template>
  <div class="p-4">
    <el-table :data="agentStore.agents" v-loading="loading">
      <!-- columns -->
    </el-table>
  </div>
</template>

Testing

Backend Tests

cd mateclaw-server
mvn test                               # All tests
mvn test -Dtest=ReActAgentTest         # Single class
mvn test -Dtest=ReActAgentTest#testChat # Single method

Frontend Linting

cd mateclaw-ui
pnpm lint

Manual Testing Checklist

Before submitting a PR, verify:

• [ ] Backend starts without errors
• [ ] Frontend builds without type errors (pnpm build)
• [ ] Login works with default credentials
• [ ] Chat with the default agent produces a response
• [ ] New feature works as described in the PR
• [ ] No console errors in the browser

Pull Request Process

1. Title: Use the conventional commit format (feat(scope): description)
2. Description: Explain what the PR does and why
3. Screenshots: Include screenshots for UI changes
4. Testing: Describe how you tested the changes
5. Breaking changes: Clearly note any breaking changes

PR Template

## What

Brief description of the change.

## Why

Why this change is needed.

## How

Technical approach taken.

## Testing

How this was tested.

## Screenshots (if UI changes)

Before / After screenshots.

Reporting Issues

When filing a bug report, include:

• MateClaw version (or commit hash)
• Java version and OS
• Steps to reproduce
• Expected vs. actual behavior
• Relevant log output

Next Steps

• Quick Start -- Development setup
• Architecture -- Project structure overview
• Roadmap -- Planned features to work on