# MemClaw 核心API示例
from memclaw import GovernedMemory, Scope, Policy

mem = GovernedMemory(
    backend="postgres",  # 或 redis, qdrant
    scopes=[
        Scope("user:preferences", read=["*"], write=["ui_agent", "profile_agent"]),
        Scope("team:decisions", read=["*"], write=["lead_agent"]),
        Scope("agent:scratch", read=["owner"], write=["owner"]),
    ],
    conflict_policy=Policy.SEMANTIC_MERGE  # 或 Policy.LAST_WRITER_WINS, Policy.VOTE
)

# Agent写入记忆时自动触发治理检查
mem.write(
    key="user_theme_preference",
    value="dark mode",
    scope="user:preferences",
    author="ui_agent",
    confidence=0.92
)

# Agent读取时自动合并同一scope下的相关记忆
context = mem.read("user_theme_preference", scope="user:preferences")
# 返回: {"value": "dark mode", "sources": ["ui_agent", "profile_agent"], "merged": true}

论点攻击图示例:

  Agent_A: "用PostgreSQL" ──攻击──→ Agent_B: "用MongoDB"
       ↑                              |
       |                              ↓
  Agent_C: "PG支持JSON"     Agent_D: "Mongo更灵活"
       |                              |
       └─────攻击──────────────────────┘

  可接受扩展: {Agent_A的论点, Agent_C的论点}
  → 决策: 使用PostgreSQL

# ArgRE 核心论证逻辑伪代码
class ArgumentationFramework:
    def __init__(self):
        self.arguments = {}  # arg_id -> {agent, claim, supports}
        self.attacks = []    # [(attacker_id, target_id)]

    def add_argument(self, agent, claim, supports=None):
        arg_id = f"arg_{len(self.arguments)}"
        self.arguments[arg_id] = {"agent": agent, "claim": claim, "supports": supports}
        return arg_id

    def add_attack(self, attacker_id, target_id, reason):
        self.attacks.append((attacker_id, target_id, reason))

    def compute_grounded_extension(self):
        """计算基础扩展——不被任何论点攻击的论点集合"""
        attacked = {target for _, target, _ in self.attacks}
        grounded = {aid for aid in self.arguments if aid not in attacked}
        changed = True
        while changed:
            changed = False
            for aid in list(grounded):
                defenders = {att for att, tgt, _ in self.attacks if tgt == aid}
                if any(d in grounded for d in defenders):
                    # 检查攻击者是否被击败
                    pass  # 简化，实际需要完整的基础语义计算
        return grounded

# Meta-Debate 动态角色分配伪代码
class MetaDebateOrchestrator:
    def __init__(self, agents, roles):
        self.agents = agents
        self.roles = roles  # ["proposer", "opponent", "judge", "fact_checker"]

    def assign_roles(self, topic):
        scores = {}
        for agent in self.agents:
            for role in self.roles:
                # Agent自述适配度
                statement = agent.generate(
                    f"Topic: {topic}\nRole: {role}\nWhy are you fit?"
                )
                # 元评审团打分
                score = self.meta_judge.evaluate(statement, role)
                scores[(agent.id, role)] = score

        # 匈牙利算法做最优匹配
        assignments = self.hungarian_algorithm(scores)
        return assignments

{
  "name": "DataAnalystAgent",
  "description": "擅长数据分析和可视化",
  "url": "https://agent.example.com/a2a",
  "capabilities": ["data_analysis", "chart_generation", "statistical_testing"],
  "inputSchema": {
    "type": "object",
    "properties": {
      "dataset_url": {"type": "string"},
      "analysis_type": {"type": "string", "enum": ["descriptive", "inferential", "predictive"]}
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "report_url": {"type": "string"},
      "charts": {"type": "array", "items": {"type": "string"}}
    }
  },
  "authentication": {"schemes": ["bearer_token"]}
}

创建Task → Agent接受/拒绝 → 执行中(可推送状态更新) → 完成/失败
                                                    ↓
                                            返回Artifact(结果)

# MoA 多层聚合核心逻辑
class MixtureOfAgents:
    def __init__(self, models_per_layer, num_layers=4):
        self.layers = []
        for i in range(num_layers):
            self.layers.append(models_per_layer[i] if i < len(models_per_layer) 
                             else models_per_layer[-1])

    def generate(self, prompt):
        current_inputs = [prompt]

        for layer_idx, models in enumerate(self.layers):
            layer_outputs = []
            for model in models:
                # 每个模型接收上一层所有输出 + 原始prompt
                augmented_input = self._build_input(prompt, current_inputs)
                output = model.generate(augmented_input)
                layer_outputs.append(output)
            current_inputs = layer_outputs

        # 最后一层取聚合结果
        return current_inputs[0] if len(current_inputs) == 1 else self._aggregate(current_inputs)

    def _build_input(self, original_prompt, previous_outputs):
        context = f"Original question: {original_prompt}\n\n"
        context += "Consider these perspectives:\n"
        for i, output in enumerate(previous_outputs):
            context += f"Perspective {i+1}: {output}\n"
        context += "\nSynthesize the best answer based on all perspectives."
        return context

graph TB
    subgraph "Multi-Agent协作原语栈"
        direction TB
        A[应用层: 任务编排] --> B[原语层: 六大协作原语]
        B --> C[通信层: A2A / MCP]
        C --> D[模型层: LLM推理引擎]

        subgraph "原语层详解"
            B1[共享治理记忆<br/>Caura/MemClaw]
            B2[正式论证消解<br/>ArgRE]
            B3[RL协商<br/>Dialogue Diplomats]
            B4[动态角色自组织<br/>Meta-Debate]
            B5[协作推理聚合<br/>MoA]
            B6[Agent间通信<br/>A2A Protocol]
        end

        B --> B1
        B --> B2
        B --> B3
        B --> B4
        B --> B5
        B --> B6

        B1 -.->|记忆读写| B2
        B2 -.->|消解结果| B5
        B4 -.->|角色分配| B1
        B6 -.->|通信通道| B2
        B6 -.->|通信通道| B4
    end

    style B1 fill:#4A90D9,color:#fff
    style B2 fill:#D94A4A,color:#fff
    style B3 fill:#D9A84A,color:#fff
    style B4 fill:#4AD97A,color:#fff
    style B5 fill:#9B4AD9,color:#fff
    style B6 fill:#4AD9D9,color:#fff

flowchart TD
    Start[Multi-Agent协作需求] --> Q1{Agent是否跨框架?}
    Q1 -->|是| A2A[使用A2A协议<br/>建立通信基础]
    Q1 -->|否| Q2{核心痛点是什么?}

    A2A --> Q2

    Q2 -->|记忆不一致| GovMem[共享治理记忆<br/>MemClaw]
    Q2 -->|决策有冲突| Q3{需要可审计吗?}
    Q2 -->|角色不匹配| DynRole[动态角色自组织<br/>Meta-Debate]
    Q2 -->|输出质量不够| MoA[协作推理聚合<br/>MoA]
    Q2 -->|需要复杂协商| RLNeg[RL协商<br/>Dialogue Diplomats]

    Q3 -->|是,合规要求高| ArgRE[正式论证消解<br/>ArgRE]
    Q3 -->|否,速度优先| Vote[简单投票/加权评分]

    GovMem --> Combine[组合使用]
    ArgRE --> Combine
    DynRole --> Combine
    MoA --> Combine
    RLNeg --> Combine

    Combine --> Deploy[生产部署]

    style A2A fill:#4AD9D9,color:#000
    style GovMem fill:#4A90D9,color:#fff
    style ArgRE fill:#D94A4A,color:#fff
    style DynRole fill:#4AD97A,color:#fff
    style MoA fill:#9B4AD9,color:#fff
    style RLNeg fill:#D9A84A,color:#fff