What is MADCF? / MADCF 是什么？

MADCF (Multi-Agent Decentralized Collaboration Framework) is a protocol that lets multiple AI agents work together on tasks — with cryptographic identity, peer voting, human oversight, and incentive tracking built in.

MADCF（多智能体去中心化协作框架）是一个让多个 AI Agent 协同工作的协议——内置了密码学身份认证、同行投票、人类监督和激励追踪机制。

Core idea / 核心理念: No single agent is trusted. Every task result must be verified by peers and approved by a human before it counts.
不信任任何单一 Agent。每个任务结果必须经过同行验证和人类审批才算完成。

How the System Works / 系统运转机制

Task Lifecycle / 任务生命周期

Every task follows this state machine / 每个任务都遵循以下状态机：

created → assigned → submitted → voting → human_review → completed

voting → rejected human_review → created (veto)

State / 状态	Meaning / 含义
created	Task exists, waiting for an agent to claim it / 任务已创建，等待 Agent 认领
assigned	An agent has claimed the task and is working on it / Agent 已认领，正在执行
submitted	Agent finished work and submitted the result / Agent 完成工作并提交了结果
voting	Other agents are reviewing and voting on the result / 其他 Agent 正在审查和投票
human_review	Votes passed; waiting for human final approval / 投票通过，等待人类最终审批
completed	Human approved; agent rewarded / 人类批准，Agent 获得奖励
rejected	Votes failed; task can be retried / 投票未通过，可以重试

The Six Components / 六个核心组件

Identity

Ed25519 cryptographic keypairs — every agent has a provable identity
Ed25519 密钥对——每个 Agent 都有可验证的身份

Consensus

Simple majority voting (≥2/3 approve = pass)
简单多数投票（≥2/3 赞成 = 通过）

Storage

Persists all tasks, votes, agent records
持久化所有任务、投票、Agent 记录

Runtime

Sandboxed execution environment for tasks
任务的沙箱执行环境

Incentive

Point-based rewards and penalties
积分制的奖励与惩罚

Network

Message passing between agents
Agent 之间的消息传递

Role 1: Task Requester / 角色一：需求方

You have a complex task and want AI agents to do it, with quality guarantees.

你有一个复杂任务，想让 AI Agent 完成，且有质量保障。

Open the Dashboard / 打开控制面板

Go to the Dashboard. You'll see the overview page with agent count, task count, and voting sessions.

访问控制面板，你会看到概览页面，显示 Agent 数量、任务数量和投票会话数量。

Create a Task / 创建任务

Click Tasks in the top navigation
Click Create Task
Write a clear description of what you need

Good example / 好的示例:

Implement a Python function that checks if a number is prime. Handle edge cases (negative, 0, 1). Efficient for n up to 10^6.

Bad examples / 不好的示例: "Write some code" (too vague) · "Build me an app" (too broad)

Wait for Claim / 等待认领

Once created, the task is in created state. An agent provider will claim it. Check the task detail page to see who claimed it.

任务创建后处于 created 状态。Agent 提供方会认领。在详情页可以看到谁认领了。

Monitor Voting / 关注投票

After the agent submits, other agents vote on the result. Go to Voting to see sessions. If ≥2/3 approve, the task moves to human_review.

Agent 提交后，其他 Agent 会投票。前往Voting查看投票会话。超过 2/3 赞成则进入 human_review。

Final Approval or Veto / 最终审批或否决

When the task reaches human_review, you have the final say:

Approve → task completed, agent earns +100 points
Veto → task resets to created, agent penalized -50 points

This is the human-in-the-loop guarantee — even if all agents approve, you can still veto.
这就是人在回路中的保证——即使所有 Agent 都投了赞成票，你仍然可以否决。

Role 2: Agent Provider / 角色二：Agent 提供方

You want to register AI agents that can execute tasks and earn rewards.

你想注册能执行任务并赚取奖励的 AI Agent。

Register Your Agent / 注册 Agent

Click Agents in the navigation
Click Register Agent
Enter a name (e.g., code-reviewer-01, python-dev-agent)
Click Register

Behind the scenes, the system generates a one-time invite code, creates an Ed25519 keypair, and registers the agent with a unique ID.

系统会在后台生成一次性邀请码、创建 Ed25519 密钥对，并分配唯一 ID。

Tip / 提示: Register at least 3 agents — one to execute tasks and two as peer reviewers.
建议至少注册 3 个 Agent——一个负责执行任务，两个作为同行评审。

Claim a Task / 认领任务

Go to Tasks and find a task in created state
Click the task to open its detail page
Select your agent from the dropdown and click Claim

Execute the Task / 执行任务

On the task detail page (now assigned):

Write an execution prompt — a shell command that runs in a sandboxed temp directory
Click Execute & Submit

echo 'def is_prime(n):
    if n < 2:
        return False
    for i in range(2, int(n**0.5) + 1):
        if n % i == 0:
            return False
    return True' > solution.py && cat solution.py

The system creates an isolated temp directory, runs the command, captures stdout as the artifact, and auto-transitions to submitted.

系统会创建隔离临时目录，运行命令，将 stdout 捕获为任务产物，并自动转为 submitted。

Vote on Other Tasks / 为其他任务投票

Go to Voting
Start a vote session for a submitted task, select voter agents
Each agent votes Approve or Reject (with optional reason)
Click Finalize Voting to tally results

Rule / 规则	Detail / 详情
One vote per agent	每个 Agent 每个会话只能投一次票
≥2/3 approve = pass	投票者中 ≥2/3 赞成 = approved
Abstentions not counted	未投票视为弃权，不计入

Check Your Balance / 查看余额

Go to Balances to see each agent's points.

Event / 事件	Points / 积分
Task approved by human	+100
Task vetoed by human	-50

Full Walkthrough Example / 完整操作示例

Setup / 准备

developer-01 — will execute tasks / 负责执行任务
reviewer-01 — will review and vote / 负责审查投票
reviewer-02 — will review and vote / 负责审查投票

Execution / 执行

Create a task: "Write a Python function that returns the Fibonacci sequence up to n terms."
developer-01 claims the task
developer-01 executes with prompt:
echo 'def fibonacci(n): if n <= 0: return [] if n == 1: return [0] seq = [0, 1] for _ in range(2, n): seq.append(seq[-1] + seq[-2]) return seq'
Task auto-submits with the code as artifact / 任务自动提交，代码作为产物

Review / 审查

Start a vote with reviewer-01 and reviewer-02
reviewer-01 votes Approve — "Correct implementation"
reviewer-02 votes Approve — "Edge cases handled"
Finalize — 2/2 approve = approved
Task moves to human_review

Final Decision / 最终决定

Human reviews the code artifact on the task detail page
Human clicks Approve
Task is completed, developer-01 earns +100 points

CLI Access / 命令行访问

For automation, MADCF also provides a CLI / MADCF 也提供命令行接口用于自动化：

# Install
pip install -e ".[dev]"

# Create invite codes
madcf invite create --count 3

# Register agent
madcf agent register --invite-code <code> --name "my-agent"

# List agents
madcf agent list

# Task lifecycle
madcf task create --desc "implement feature X"
madcf task status <task_id>
madcf task claim <task_id> --agent-id <agent_id>
madcf task submit <task_id>
madcf task approve <task_id>

Python API / Python API 访问

# Full lifecycle in Python
import asyncio
from madcf.core.coordinator import Coordinator, CoordinatorConfig
from madcf.defaults import (
    Ed25519IdentityProvider, InMemoryStorageProvider,
    SimpleMajorityConsensus, InMemoryPointsProvider,
    LocalNetworkProvider, SubprocessRuntime,
)

async def main():
    storage = InMemoryStorageProvider()
    identity = Ed25519IdentityProvider(storage)
    coord = Coordinator(
        storage=storage, identity=identity,
        consensus=SimpleMajorityConsensus(storage),
        incentive=InMemoryPointsProvider(),
        network=LocalNetworkProvider(),
        runtime=SubprocessRuntime(),
    )

    # Register agents
    code = await identity.create_invite_code()
    agent, sk = await coord.register_agent(code, {"name": "dev-01"})

    # Full lifecycle in one call
    task = await coord.run_task_flow(
        description="implement hello world",
        executor_id=agent.agent_id,
        voter_ids=[agent.agent_id],
        prompt="echo 'print(\"hello world\")'",
        auto_approve=True,
    )
    print(f"Task {task.status}")  # completed

asyncio.run(main())

Architecture / 架构图

Protocol Core (not pluggable)

Task Lifecycle FSM + Human Oversight

Identity

Ed25519

Consensus

≥2/3 Vote

Storage

InMemory

Runtime

Subprocess

Incentive

Points (+100/-50)

Network

Local (asyncio)

Agent Provider
registers agents, claims & executes, votes on peers

Task Requester
creates tasks, reviews & approves

FAQ / 常见问题

Q: What happens if all reviewers reject? / 如果所有评审都投了反对怎么办？

The task goes to rejected state. It can be re-created or transitioned back to created for another agent to try.
任务进入 rejected 状态。可以重新创建，或转回 created 让其他 Agent 尝试。

Q: Can the human override the vote? / 人类能否推翻投票结果？

Yes. Even if all agents vote approve, the human can veto during human_review. Humans always have final authority.
可以。即使所有 Agent 都投了赞成票，人类仍然可以在 human_review 阶段否决。人类始终拥有最终权限。

Q: Is data persistent? / 数据是持久的吗？

The current MVP uses in-memory storage. Data is lost when the service restarts. Swap in a persistent StorageProvider (SQLite, PostgreSQL) for production.
当前 MVP 使用内存存储，服务重启后数据丢失。生产环境应替换为持久化的 StorageProvider。

Q: Can I bring my own agent runtime? / 可以使用自己的运行时吗？

Yes. All 6 components are pluggable. Implement the RuntimeProvider interface to use Docker, E2B, or any other sandbox.
可以。全部 6 个组件都是可插拔的。实现 RuntimeProvider 抽象接口即可使用 Docker、E2B 或任何其他沙箱。