Skip to content

valkryhx/google_adk_agent / skills/agent_team_to_be_update

Agent 团队协作(去中心化拉模型)

Flagged

赋予 Agent 作为集群指挥官(Leader)的能力,通过去中心化任务队列将子任务派发给 Worker 节点并发执行。

FileKindSize
SKILL.mdskill md17.9 KB
decentralized_tools.pyscript36.2 KB
dependency_analyzer.pyscript10.9 KB
inbox_watcher.pyscript8.5 KB
loop_executor.pyscript16.4 KB
mailbox.pyscript15.3 KB
models.pyscript9.1 KB
path_guard.pyscript13.3 KB
planner.pyscript14.6 KB
polling_daemon.pyscript7.7 KB
self_claim_loop.pyscript20.1 KB
task_queue.pyscript24.1 KB
team_config.pyscript7.5 KB
test/__init__.pyscript40 B
test/test_blog_system_develop.pyscript12.0 KB
test/test_dag_create_validation.pyscript2.7 KB
test/test_decentralized_arch.pyscript36.9 KB
test/test_deepresearch.pyscript14.6 KB
test/test_loop_dag.pyscript17.0 KB
test/test_real_training.pyscript9.2 KB
test/test_tdd_gate.pyscript4.5 KB
tools.pyscript85.8 KB
verification_hooks.pyscript10.7 KB
worktree_manager.pyscript12.8 KB

decentralized_tools.py

View on GitHub
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
r"""
Decentralized Agent Team Tools (A-ish Architecture)

基于文件 + flock 的去中心化自协调工具集。
Leader 创建 DAG 并广播任务,Worker 通过 flock 竞争认领。

工具列表:
- team_create, team_join, team_leave, team_status, team_list_workers
- task_claim, task_complete, task_status, task_list
- mailbox_send, mailbox_read, mailbox_broadcast
- worker_status, worker_idle_report

所有工具使用文件协调,通过 Mailbox/TaskQueue/TeamConfig 模块实现。
"""

import asyncio
import json
import os
import time
import uuid
from typing import List, Optional, Dict, Any

try:
    from .mailbox import Mailbox, Message
    from .task_queue import TaskQueue, Task
    from .team_config import TeamConfig, TeamMember
    from .verification_hooks import TaskCompletedHook, TeammateIdleHook
    from .path_guard import PathGuard
    from .loop_executor import LoopExecutor
except ImportError:
    from mailbox import Mailbox, Message
    from task_queue import TaskQueue, Task
    from team_config import TeamConfig, TeamMember
    from verification_hooks import TaskCompletedHook, TeammateIdleHook
    from path_guard import PathGuard
    from loop_executor import LoopExecutor

# ==========================================
# 协调目录解析
# ==========================================

def _get_coordination_dir(team_id: str) -> str:
    """获取团队的协调目录路径。

    优先级:
    1. 环境变量 ADK_COORDINATION_DIR
    2. ADK_PROJECT_ROOT/coordination/{team_id}
    3. 当前目录/coordination/{team_id}
    """
    if os.environ.get("ADK_COORDINATION_DIR"):
        return os.path.join(os.environ["ADK_COORDINATION_DIR"].strip(), team_id.strip())
    project_root = os.environ.get(
        "ADK_PROJECT_ROOT",
        os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
    )
    return os.path.join(project_root, "coordination", team_id)


def _get_current_agent_id() -> str:
    """获取当前 Agent 的完整 ID。

    格式: {node_type}_{port}@{project}
    例如: leader_8000@adk_swarm
    """
    port = os.environ.get("ADK_CURRENT_PORT", "0")
    project = os.environ.get("ADK_PROJECT_NAME", "adk_swarm")
    node_type = os.environ.get("ADK_NODE_TYPE", "agent")
    return f"{node_type}_{port}@{project}"


def _get_current_port() -> int:
    """获取当前 Agent 运行的端口号。"""
    return int(os.environ.get("ADK_CURRENT_PORT", 0))


# ==========================================
# Team Management Tools (Leader 使用)
# ==========================================

async def team_create(
    team_id: str,
    team_name: str = None,
    description: str = ""
) -> str:
    """
    【Leader 专用】创建一个新的 Agent Team。

    在协调目录中初始化 config.json,注册 Leader 自身为第一个成员。
    只需在集群启动时调用一次。

    Args:
        team_id: 团队唯一标识 (建议用项目名)
        team_name: 团队显示名称
        description: 团队描述

    Returns:
        创建结果报告
    """
    coord_dir = _get_coordination_dir(team_id)
    current_port = _get_current_port()
    agent_id = _get_current_agent_id()

    os.makedirs(coord_dir, exist_ok=True)

    config = TeamConfig(team_id=team_id, base_dir=coord_dir, team_name=team_name)

    # 注册 Leader 自身
    leader = TeamMember(
        name="leader",
        agent_id=agent_id,
        agent_type="leader",
        port=current_port,
        role="orchestrator",
        status="active",
        metadata={"description": description}
    )

    if config.register_member(leader):
        result = (
            f"[TEAM CREATED]\n"
            f"Team ID: {team_id}\n"
            f"Team Name: {team_name or team_id}\n"
            f"Description: {description}\n"
            f"Leader: {agent_id} (port {current_port})\n"
            f"Coordination Dir: {coord_dir}\n"
            f"\n"
            f"下一步: 使用 team_join() 让 Worker 节点加入团队。"
        )
    else:
        result = (
            f"[TEAM EXISTS] 团队 {team_id} 已存在,Leader 已注册。\n"
            f"Coordination Dir: {coord_dir}"
        )

    return result


async def team_join(
    team_id: str,
    worker_name: str = None,
    worker_type: str = "general-purpose",
    role: str = ""
) -> str:
    """
    【Worker 专用】加入一个已存在的 Agent Team。

    将当前 Worker 注册到团队的 config.json 中。
    Worker 启动时调用。

    Args:
        team_id: 团队唯一标识
        worker_name: Worker 名称 (默认为 worker_{port})
        worker_type: Agent 类型 (general-purpose / specialized)
        role: 角色描述

    Returns:
        加入结果报告
    """
    coord_dir = _get_coordination_dir(team_id)
    base_dir = coord_dir
    current_port = _get_current_port()
    agent_id = _get_current_agent_id()

    if worker_name is None:
        worker_name = f"worker_{current_port}"

    config = TeamConfig(team_id=team_id, base_dir=base_dir)

    member = TeamMember(
        name=worker_name,
        agent_id=agent_id,
        agent_type=worker_type,
        port=current_port,
        role=role,
        status="active",
        metadata={}
    )

    if config.register_member(member):
        result = (
            f"[TEAM JOINED]\n"
            f"Team ID: {team_id}\n"
            f"Worker Name: {worker_name}\n"
            f"Agent ID: {agent_id}\n"
            f"Port: {current_port}\n"
            f"Type: {worker_type}\n"
            f"Role: {role or 'unspecified'}\n"
            f"\n"
            f"你已成功加入团队。现在可以等待任务通知或主动认领任务。"
        )
    else:
        existing = config.get_member(worker_name)
        if existing and existing.agent_id == agent_id:
            result = f"[ALREADY JOINED] Worker {worker_name} 已注册在此团队中。"
        else:
            result = f"[JOIN FAILED] Worker 名称 {worker_name} 已被占用。"

    return result


async def team_leave(team_id: str, reason: str = "") -> str:
    """
    【通用】离开 Agent Team。

    从 config.json 中注销当前 Agent。
    Agent 关闭前调用。

    Args:
        team_id: 团队唯一标识
        reason: 离开原因

    Returns:
        离开结果报告
    """
    base_dir = _get_coordination_dir(team_id)
    agent_id = _get_current_agent_id()
    current_port = _get_current_port()

    config = TeamConfig(team_id=team_id, base_dir=base_dir)

    # 查找当前 agent 对应的 name
    member_name = None
    for m in config.get_all_members():
        if m.port == current_port:
            member_name = m.name
            break

    if member_name is None:
        return f"[NOT FOUND] 当前 Agent 未注册在团队 {team_id} 中。"

    # 更新状态为 shutdown
    config.update_member_status(member_name, "shutdown")

    return (
        f"[TEAM LEFT]\n"
        f"Team ID: {team_id}\n"
        f"Worker: {member_name}\n"
        f"Reason: {reason or 'normal shutdown'}"
    )


async def team_status(
    team_id: str,
    include_workers: bool = True
) -> str:
    """
    【通用】查询团队状态。

    获取团队成员列表和状态摘要。

    Args:
        team_id: 团队唯一标识
        include_workers: 是否列出所有 Worker 详情

    Returns:
        团队状态报告
    """
    base_dir = _get_coordination_dir(team_id)
    config = TeamConfig(team_id=team_id, base_dir=base_dir)

    all_members = config.get_all_members()
    leader = config.get_leader()
    workers = config.get_worker_members()
    active = config.get_active_members()

    lines = [
        "[TEAM STATUS]",
        f"Team ID: {team_id}",
        f"Total Members: {len(all_members)}",
        f"Active: {len(active)}",
        "",
    ]

    if leader:
        lines.append(f"Leader: {leader.name} (port {leader.port}, {leader.status})")

    if include_workers and workers:
        lines.append(f"Workers ({len(workers)}):")
        for w in workers:
            status_icon = {"active": "O", "idle": "-", "busy": "@", "shutdown": "X"}.get(w.status, "?")
            lines.append(f"  [{status_icon}] {w.name} (port {w.port}, {w.status})")

    return "\n".join(lines)


async def team_list_workers(team_id: str, status_filter: str = None) -> str:
    """
    【Leader 专用】列出团队中的 Worker 节点。

    用于任务分发前的 Worker 枚举。

    Args:
        team_id: 团队唯一标识
        status_filter: 可选,按状态过滤 (active/idle/busy/shutdown)

    Returns:
        Worker 列表报告
    """
    base_dir = _get_coordination_dir(team_id)
    config = TeamConfig(team_id=team_id, base_dir=base_dir)

    workers = config.get_worker_members()
    if status_filter:
        workers = [w for w in workers if w.status == status_filter]

    if not workers:
        return f"[NO WORKERS] 团队 {team_id} 中没有可用 Worker。"

    lines = [f"[WORKERS] team={team_id} count={len(workers)}", ""]
    for w in workers:
        lines.append(f"  - {w.name} | port={w.port} | status={w.status} | role={w.role or 'unspecified'}")

    lines.append("")
    lines.append(f"总计: {len(workers)} 个 Worker")
    return "\n".join(lines)


# ==========================================
# Task Management Tools
# ==========================================

async def task_create(
    team_id: str,
    name: str,
    description: str = "",
    blocked_by: List[str] = None,
    expected_artifacts: List[str] = None,
    writable_files: List[str] = None,
    read_only_files: List[str] = None,
    task_type: str = "regular",
    priority: str = "NORMAL"
) -> str:
    """
    【已禁用】单任务创建入口。

    为避免模型在 DAG 工作流中误用单任务入口,导致计划与执行不一致,
    强制要求仅通过 dag_create 创建任务图。

    Args:
        team_id: 团队唯一标识
        name: 任务名称
        description: 任务描述
        blocked_by: 依赖的任务 ID 列表
        expected_artifacts: 期望产出的文件路径
        writable_files: 可写文件列表
        read_only_files: 只读文件列表
        task_type: 任务类型 (regular/gate/loop)
        priority: 优先级 (LOW/NORMAL/HIGH/URGENT)

    Returns:
        禁用提示
    """
    raise RuntimeError(
        "task_create is disabled. Use dag_create(tasks=[...]) to create tasks."
    )


async def task_claim(
    team_id: str,
    task_id: str = None,
    prefer_first: bool = False
) -> str:
    """
    【Worker 专用】尝试认领一个任务。

    如果 task_id 为空,主动从 get_available_tasks() 获取第一个。
    使用 flock 文件锁实现竞争。

    Args:
        team_id: 团队唯一标识
        task_id: 指定的任务 ID (可选)
        prefer_first: True=优先认领第一个可用任务,False=认领指定 ID

    Returns:
        认领结果报告
    """
    coord_dir = _get_coordination_dir(team_id)
    agent_id = _get_current_agent_id()

    queue = TaskQueue(team_id=team_id, base_dir=coord_dir)

    target_id = task_id

    if target_id is None or prefer_first:
        available = queue.get_available_tasks()
        if not available:
            return (
                f"[NO TASKS] 当前没有可认领的任务。\n"
                f"请等待 Leader 创建新任务。"
            )
        target_id = available[0].id

    if queue.claim_task(target_id, agent_id):
        task = queue.get_task(target_id)

        # PathGuard 集成:只校验 writable_files,读取不限制
        if task and task.writable_files:
            import os as _os
            guard = PathGuard(allowed_root=_os.getcwd())
            violations = [
                f for f in task.writable_files
                if not guard.is_allowed(f)
            ]
            if violations:
                queue.fail_task(target_id)
                return (
                    f"[BLOCKED] 任务 {target_id} 包含非法写路径,认领被拒绝。\n"
                    f"违规路径:\n" + "\n".join(f"  - {v}" for v in violations)
                )

        return (
            f"[TASK CLAIMED]\n"
            f"Task ID: {target_id}\n"
            f"Name: {task.name if task else 'unknown'}\n"
            f"Owner: {agent_id}\n"
            f"\n"
            f"请开始执行任务,完成后调用 task_complete()。"
        )
    else:
        return (
            f"[CLAIM FAILED] 任务 {target_id} 被其他 Worker 抢走了。\n"
            f"flock 竞争失败,尝试认领其他任务。"
        )


async def task_complete(
    team_id: str,
    task_id: str,
    result: str = "",
    error: str = None,
    artifacts: List[str] = None
) -> str:
    """
    【Worker 专用】标记任务完成并通知 Leader。

    完成任务后,通过 Mailbox 向 Leader 发送完成通知。

    Args:
        team_id: 团队唯一标识
        task_id: 任务 ID
        result: 执行结果摘要
        error: 错误信息 (如有)
        artifacts: 产出文件列表

    Returns:
        完成结果报告
    """
    coord_dir = _get_coordination_dir(team_id)
    base_dir = coord_dir
    agent_id = _get_current_agent_id()

    queue = TaskQueue(team_id=team_id, base_dir=coord_dir)

    task = queue.get_task(task_id)
    if task is None:
        return f"[ERROR] 任务 {task_id} 不存在。"

    # VerificationHooks 集成:完成前校验产出物与质量门禁
    workdir = os.getcwd()
    hook = TaskCompletedHook(workdir)
    # 从任务字段中读取期望产出文件和验证命令(若无则跳过对应项)
    if task.expected_artifacts:
        hook.set_required_files(task.expected_artifacts)
    if task.verification_commands:
        hook.set_verification_commands(task.verification_commands)
    # git 检查默认关闭(Agent 环境不保证 git 干净)
    hook.require_git_clean = False

    vr = hook.verify()
    if not vr.allowed:
        return (
            f"[BLOCKED] 任务 {task_id} 未通过完成验证,操作被拦截。\n"
            f"原因: {vr.reason}\n"
            f"建议: {vr.action}"
        )

    queue.complete_task(task_id)

    # 通知 Leader
    mailbox = Mailbox(base_dir=coord_dir)
    config = TeamConfig(team_id=team_id, base_dir=base_dir)
    leader = config.get_leader()

    if leader:
        completion_msg = json.dumps({
            "type": "task_completed",
            "taskId": task_id,
            "taskName": task.name,
            "worker": agent_id,
            "result": result[:2000] if result else "",
            "error": error,
            "artifacts": artifacts or []
        })
        mailbox.send_message(
            from_agent=agent_id,
            to_agent=leader.agent_id,
            content=completion_msg,
            msg_type="task_completed"
        )

    return (
        f"[TASK COMPLETED]\n"
        f"Task ID: {task_id}\n"
        f"Task Name: {task.name}\n"
        f"Worker: {agent_id}\n"
        f"Result: {result[:500] if result else 'no output'}\n"
        f"{f'Error: {error}' if error else ''}\n"
        f"\n"
        f"Leader 已收到完成通知。"
    )


async def task_status(
    team_id: str,
    task_id: str = None,
    show_all: bool = False
) -> str:
    """
    【通用】查询任务状态。

    Args:
        team_id: 团队唯一标识
        task_id: 任务 ID (可选,为空则列出所有)
        show_all: 是否显示所有任务

    Returns:
        任务状态报告
    """
    coord_dir = _get_coordination_dir(team_id)
    queue = TaskQueue(team_id=team_id, base_dir=coord_dir)

    if task_id:
        task = queue.get_task(task_id)
        if task is None:
            return f"[NOT FOUND] 任务 {task_id} 不存在。"
        return (
            f"[TASK STATUS]\n"
            f"ID: {task.id}\n"
            f"Name: {task.name}\n"
            f"Status: {task.status}\n"
            f"Owner: {task.owner or 'unclaimed'}\n"
            f"Type: {task.task_type}\n"
            f"Blocked By: {task.blocked_by or 'none'}\n"
            f"Created: {task.created_at}\n"
            f"Description: {task.description or 'none'}"
        )

    all_tasks = queue.list_tasks()
    if not all_tasks:
        return f"[NO TASKS] 团队 {team_id} 没有任何任务。"

    stats = queue.get_task_stats()
    lines = [
        f"[TASK STATUS] team={team_id}",
        f"Total: {stats['total']} | Pending: {stats['pending']} | "
        f"In Progress: {stats['in_progress']} | Completed: {stats['completed']}",
        ""
    ]

    if show_all:
        for t in all_tasks:
            owner_str = t.owner or "unclaimed"
            lines.append(f"  [{t.status:12}] {t.id[:16]}... | {t.name} | owner={owner_str}")
    else:
        pending = [t for t in all_tasks if t.status == "pending"]
        for t in pending:
            lines.append(f"  [PENDING] {t.id[:16]}... | {t.name}")

    return "\n".join(lines)


async def task_list(
    team_id: str,
    status: str = None,
    limit: int = 50
) -> str:
    """
    【通用】列出任务列表。

    Args:
        team_id: 团队唯一标识
        status: 按状态过滤 (pending/in_progress/completed)
        limit: 返回数量上限

    Returns:
        任务列表报告
    """
    coord_dir = _get_coordination_dir(team_id)
    queue = TaskQueue(team_id=team_id, base_dir=coord_dir)

    tasks = queue.list_tasks(status=status)
    tasks = tasks[:limit]

    if not tasks:
        filter_str = f" (status={status})" if status else ""
        return f"[NO TASKS] 团队 {team_id} 没有符合条件的任务{filter_str}。"

    lines = [
        f"[TASK LIST] team={team_id}{f' status={status}' if status else ''} count={len(tasks)}",
        ""
    ]
    for t in tasks:
        lines.append(
            f"  [{t.status:12}] {t.id[:20]} | {t.name[:40]} | "
            f"owner={t.owner or 'none'[:20] if t.owner else 'none'}"
        )

    return "\n".join(lines)


# ==========================================
# Mailbox / Messaging Tools
# ==========================================

async def mailbox_send(
    team_id: str,
    to_agent: str,
    content: str,
    msg_type: str = "text",
    metadata: Dict[str, Any] = None
) -> str:
    """
    【通用】向指定 Agent 发送消息。

    Args:
        team_id: 团队唯一标识
        to_agent: 目标 Agent ID (或名称如 "leader")
        content: 消息内容
        msg_type: 消息类型 (text/task_broadcast/task_completed/shutdown_request)
        metadata: 附加元数据

    Returns:
        发送结果
    """
    coord_dir = _get_coordination_dir(team_id)
    base_dir = coord_dir
    agent_id = _get_current_agent_id()

    mailbox = Mailbox(base_dir=coord_dir)

    # 支持用名称查找 agent_id
    config = TeamConfig(team_id=team_id, base_dir=base_dir)
    target_id = to_agent
    if to_agent != "leader":
        member = config.get_member(to_agent)
        if member:
            target_id = member.agent_id

    msg_id = mailbox.send_message(
        from_agent=agent_id,
        to_agent=target_id,
        content=content,
        msg_type=msg_type,
        metadata=metadata or {}
    )

    return (
        f"[MESSAGE SENT]\n"
        f"Message ID: {msg_id}\n"
        f"To: {target_id}\n"
        f"Type: {msg_type}\n"
        f"Content: {content[:200]}{'...' if len(content) > 200 else ''}"
    )


async def mailbox_read(
    team_id: str,
    mark_read: bool = False,
    unread_only: bool = True
) -> str:
    """
    【通用】读取当前 Agent 的收件箱消息。

    Args:
        team_id: 团队唯一标识
        mark_read: 是否标记消息为已读
        unread_only: 是否只返回未读消息

    Returns:
        消息列表报告
    """
    coord_dir = _get_coordination_dir(team_id)
    agent_id = _get_current_agent_id()

    mailbox = Mailbox(base_dir=coord_dir)
    messages = mailbox.read_messages(
        agent_id=agent_id,
        mark_read=mark_read,
        unread_only=unread_only
    )

    if not messages:
        return "[NO MESSAGES] 收件箱为空。"

    lines = [f"[MAILBOX] {len(messages)} 条消息", ""]
    for i, msg in enumerate(messages):
        time_str = time.strftime("%H:%M:%S", time.localtime(msg.timestamp))
        content_preview = msg.content[:150].replace("\n", " ")
        lines.append(
            f"  [{i+1}] {time_str} | from={msg.from_agent[:30]} | "
            f"type={msg.msg_type} | read={msg.read}"
        )
        lines.append(f"       {content_preview}...")
        lines.append("")

    return "\n".join(lines)


async def mailbox_broadcast(
    team_id: str,
    content: str,
    msg_type: str = "broadcast",
    target_type: str = "all"  # all / workers / leader
) -> str:
    """
    【Leader 专用】广播消息给团队成员。

    Args:
        team_id: 团队唯一标识
        content: 广播内容
        msg_type: 消息类型
        target_type: 目标类型 (all/workers/leader)

    Returns:
        广播结果
    """
    coord_dir = _get_coordination_dir(team_id)
    base_dir = coord_dir
    agent_id = _get_current_agent_id()

    mailbox = Mailbox(base_dir=coord_dir)
    config = TeamConfig(team_id=team_id, base_dir=base_dir)

    targets = []
    if target_type in ("all", "workers"):
        targets.extend(config.get_worker_members())
    if target_type in ("all", "leader"):
        leader = config.get_leader()
        if leader:
            targets.append(leader)

    sent = 0
    for member in targets:
        if member.agent_id != agent_id:
            mailbox.send_message(
                from_agent=agent_id,
                to_agent=member.agent_id,
                content=content,
                msg_type=msg_type
            )
            sent += 1

    return (
        f"[BROADCAST SENT]\n"
        f"Team: {team_id}\n"
        f"Target: {target_type}\n"
        f"Recipients: {sent}\n"
        f"Content: {content[:200]}{'...' if len(content) > 200 else ''}"
    )


# ==========================================
# Worker Self-Management Tools
# ==========================================

async def worker_status(
    team_id: str,
    status: str = None,
    detail: str = ""
) -> str:
    """
    【Worker 专用】更新自身状态。

    Args:
        team_id: 团队唯一标识
        status: 新状态 (active/idle/busy/shutdown_requested)
        detail: 状态详情

    Returns:
        更新结果
    """
    base_dir = _get_coordination_dir(team_id)
    current_port = _get_current_port()

    config = TeamConfig(team_id=team_id, base_dir=base_dir)

    # 查找当前 worker 的 name
    member_name = None
    for m in config.get_all_members():
        if m.port == current_port:
            member_name = m.name
            break

    if member_name is None:
        return f"[NOT FOUND] 当前 Worker 未注册在团队 {team_id} 中。"

    config.update_member_status(member_name, status)

    return (
        f"[WORKER STATUS UPDATED]\n"
        f"Worker: {member_name}\n"
        f"Status: {status}\n"
        f"Detail: {detail or 'none'}"
    )


async def worker_idle_report(team_id: str, reason: str = "available") -> str:
    """
    【Worker 专用】向 Leader 报告自身空闲。

    当 Worker 空闲多轮后,主动通知 Leader。

    Args:
        team_id: 团队唯一标识
        reason: 空闲原因

    Returns:
        报告结果
    """
    coord_dir = _get_coordination_dir(team_id)
    base_dir = coord_dir
    agent_id = _get_current_agent_id()

    mailbox = Mailbox(base_dir=coord_dir)
    config = TeamConfig(team_id=team_id, base_dir=base_dir)
    leader = config.get_leader()

    # VerificationHooks 集成:空闲前校验产出物与验证命令
    workdir = os.getcwd()
    idle_hook = TeammateIdleHook(workdir)
    vr = idle_hook.verify()
    if not vr.allowed:
        return (
            f"[BLOCKED] Worker 空闲上报被拦截,请先完成待处理工作。\n"
            f"原因: {vr.reason}\n"
            f"建议: {vr.action}"
        )

    if leader:
        idle_msg = json.dumps({
            "type": "idle_notification",
            "from": agent_id,
            "reason": reason,
            "timestamp": time.time()
        })
        mailbox.send_message(
            from_agent=agent_id,
            to_agent=leader.agent_id,
            content=idle_msg,
            msg_type="idle_notification"
        )

    return (
        f"[IDLE REPORT SENT]\n"
        f"Team: {team_id}\n"
        f"Worker: {agent_id}\n"
        f"Reason: {reason}"
    )


# ==========================================
# Batch / DAG Creation Tool
# ==========================================

async def dag_create(
    team_id: str,
    tasks: List[Dict[str, Any]],
    broadcast: bool = True
) -> str:
    """
    【Leader 专用】批量创建 DAG 任务并可选广播。

    一次创建多个任务,自动处理依赖关系,并广播通知所有 Worker。

    Args:
        team_id: 团队唯一标识
        tasks: 任务定义列表,每个 dict 包含:
            - name: 任务名称
            - description: 任务描述 (可选)
            - blocked_by: 依赖的任务名称列表 (可选)
            - task_type: regular/gate (可选)
        broadcast: 是否广播通知 Worker

    Returns:
        创建结果报告,包含所有 task_id
    """
    coord_dir = _get_coordination_dir(team_id)
    base_dir = coord_dir
    agent_id = _get_current_agent_id()

    queue = TaskQueue(team_id=team_id, base_dir=coord_dir)
    mailbox = Mailbox(base_dir=coord_dir)
    config = TeamConfig(team_id=team_id, base_dir=base_dir)

    if not tasks:
        raise ValueError("tasks cannot be empty")

    # 先全量校验,再创建,避免中途异常导致“半创建”残留任务。
    existing_name_to_id = {t.name: t.id for t in queue.list_tasks()}
    known_names = set(existing_name_to_id.keys())
    validated_tasks: List[Dict[str, Any]] = []

    for idx, task_def in enumerate(tasks, start=1):
        if not isinstance(task_def, dict):
            raise ValueError(f"tasks[{idx}] must be an object")

        raw_name = task_def.get("name")
        if not isinstance(raw_name, str) or not raw_name.strip():
            raise ValueError(f"tasks[{idx}].name is required and must be a non-empty string")
        name = raw_name.strip()

        if any(t["name"] == name for t in validated_tasks):
            raise ValueError(f"duplicate task name in request: {name}")

        raw_blocked_by = task_def.get("blocked_by", [])
        if raw_blocked_by is None:
            raw_blocked_by = []
        if not isinstance(raw_blocked_by, list):
            raise ValueError(f"tasks[{idx}].blocked_by must be a list")

        blocked_by: List[str] = []
        for dep_name in raw_blocked_by:
            if not isinstance(dep_name, str) or not dep_name.strip():
                raise ValueError(f"tasks[{idx}].blocked_by contains invalid dependency name")
            dep_name = dep_name.strip()
            # 与当前实现保持一致:依赖必须是“已有任务”或“本次请求中已在前面声明的任务”。
            if dep_name not in known_names:
                raise ValueError(
                    f"tasks[{idx}].blocked_by references unknown or future task name: {dep_name}"
                )
            blocked_by.append(dep_name)

        validated_task = dict(task_def)
        validated_task["name"] = name
        validated_task["blocked_by"] = blocked_by
        validated_tasks.append(validated_task)
        known_names.add(name)

    # 第一遍:创建所有任务,建立 name -> id 映射
    # 必须预加载已有任务,才能处理跨多轮下发的 DAG 节点之间的依赖。
    name_to_id = dict(existing_name_to_id)
    created_tasks = []

    for task_def in validated_tasks:
        blocked_by_ids = [name_to_id[dep_name] for dep_name in task_def["blocked_by"]]

        task = queue.create_task(
            name=task_def["name"],
            description=task_def.get("description", ""),
            blocked_by=blocked_by_ids,
            expected_artifacts=task_def.get("expected_artifacts", []),
            writable_files=task_def.get("writable_files", []),
            read_only_files=task_def.get("read_only_files", []),
        )
        name_to_id[task_def["name"]] = task.id
        created_tasks.append(task)

    # 第二遍:广播通知
    if broadcast:
        workers = config.get_worker_members()
        notified = 0
        for task in created_tasks:
            broadcast_content = json.dumps({
                "type": "task_broadcast",
                "taskId": task.id,
                "taskName": task.name,
                "blockedBy": task.blocked_by,
                "description": task.description[:200] if task.description else ""
            })
            for w in workers:
                if w.status == "active":
                    mailbox.send_message(
                        from_agent=agent_id,
                        to_agent=w.agent_id,
                        content=broadcast_content,
                        msg_type="task_broadcast"
                    )
                    notified += 1

        workers_count = len(workers)
    else:
        notified = 0
        workers_count = len(config.get_worker_members())

    lines = [
        f"[DAG CREATED] team={team_id}",
        f"Tasks Created: {len(created_tasks)}",
        f"Workers Notified: {notified}",
        "",
        "Task ID Map:"
    ]
    for task in created_tasks:
        deps = ", ".join(task.blocked_by) if task.blocked_by else "none"
        lines.append(f"  {task.name}: {task.id} (blocked_by: {deps})")

    create_result_str = "\n".join(lines)

    warning_msg = (
        "\n\n======================================================\n"
        "  ⚠️ 【系统强制指令:物理集群已在后台截获任务!】\n"
        "  为了让用户界面看到实时卡片流推、并为你呈现最终验收战报:\n"
        "  接下来,你必须、没有任何借口地立刻发起新的工具调用:\n"
        "  `dag_execute(max_polls=100)` !\n"
        "  否则前台将显示无限假死,用户也将对小弟进展一无所知!\n"
        "======================================================\n"
    )
    return create_result_str + warning_msg


# ==========================================
# get_tools - 返回去中心化工具集
# ==========================================

async def dag_execute(
    team_id: str,
    max_polls: int = 100,
    _status_reporter=None,
    task_timeout: float = 600.0,
) -> str:
    """
    【Leader 专用】等待 DAG 任务队列全部由 Worker 执行完成。

    本函数为纯监控轮询:不执行任何任务,只等待 SelfClaimLoop
    后台协程(Worker/Leader 节点)将所有任务认领并完成。

    Args:
        team_id: 团队唯一标识
        max_polls: 最大轮询次数(每次间隔 3 秒,总等待上限 = max_polls × 3 秒)

    Returns:
        执行摘要报告
    """
    import re as _re

    if not callable(_status_reporter):
        _status_reporter = None

    def _report(event_type, task):
        if not _status_reporter:
            return
        # 从 owner 格式 "worker_8001@adk_swarm" 解析端口
        port_match = _re.search(r'_(\d+)@', task.owner or "")
        worker_port = int(port_match.group(1)) if port_match else 0
        _status_reporter(event_type, {
            "worker_port": worker_port,
            "worker_name": task.owner or f"worker_{worker_port}",
            "session_id": task.id,
            "task_preview": f"{task.name}: {task.description[:60]}..."
                            if len(task.description) > 60 else f"{task.name}: {task.description}",
            "error": getattr(task, "error", None) or "Unknown error"
        })

    coord_dir = _get_coordination_dir(team_id)
    queue = TaskQueue(team_id=team_id, base_dir=coord_dir)

    poll_interval = 3.0  # 秒
    wave = 0
    seen_states: dict = {}  # task_id -> last known status

    while wave < max_polls:
        wave += 1
        all_tasks = queue.list_tasks()

        if not all_tasks:
            await asyncio.sleep(poll_interval)
            continue

        # 超时检测:in_progress 任务超过 task_timeout 秒未完成则回收
        now = time.time()
        for t in all_tasks:
            if t.status == "in_progress" and t.claimed_at and (now - t.claimed_at) > task_timeout:
                print(f"[dag_execute] ⏰ 任务 {t.name} ({t.id}) 超时 ({task_timeout}s),回收为 pending")
                # 注入具有确切信息量的报错文本(仅为本地内存注入,供后面 UI 推送使用)
                t.error = f"执行超时保护触发:该 Worker 的执行已被强制切断(上限 {task_timeout}s)。可能因为发生死锁或由于模型生成逻辑极其缓慢而长时无响应。系统已将任务回收回公网重新等待接管。"
                queue.reset_task(t.id)
                if _status_reporter:
                    _report("fail", t)
                seen_states[t.id] = "pending"  # 重置跃迁记录,允许重新上报 init

        # 检测状态跃迁并上报
        for t in all_tasks:
            prev = seen_states.get(t.id)
            cur = t.status
            if cur == prev:
                continue
            seen_states[t.id] = cur
            if cur == "in_progress":
                _report("init", t)
            elif cur == "completed":
                _report("finish", t)
            elif cur == "failed":
                _report("fail", t)

        total = len(all_tasks)
        completed = [t for t in all_tasks if t.status == "completed"]
        failed = [t for t in all_tasks if t.status == "failed"]
        in_progress = [t for t in all_tasks if t.status == "in_progress"]
        pending = [t for t in all_tasks if t.status == "pending"]

        print(
            f"[dag_execute] Wave {wave} | "
            f"completed={len(completed)} failed={len(failed)} "
            f"in_progress={len(in_progress)} pending={len(pending)}"
        )

        # 全部完成(含失败算结束)
        if len(completed) + len(failed) == total:
            break

        await asyncio.sleep(poll_interval)

    all_tasks = queue.list_tasks()
    total = len(all_tasks)
    completed = sum(1 for t in all_tasks if t.status == "completed")
    failed = sum(1 for t in all_tasks if t.status == "failed")

    lines = [
        f"[DAG EXECUTED]",
        f"Team: {team_id}",
        f"Waves(polls): {wave}",
        f"Tasks: {completed}/{total} 完成" + (f", {failed} 失败" if failed else ""),
    ]
    lines.append("---")
    for t in all_tasks:
        status_icon = {"completed": "✓", "failed": "✗", "in_progress": "⋯", "pending": "○"}.get(t.status, "?")
        owner_str = t.owner or "unowned"
        lines.append(f"[TASK] {status_icon} {t.name} | owner={owner_str} | status={t.status} | id={t.id}")
    if failed:
        failed_tasks = [t for t in all_tasks if t.status == "failed"]
        lines.append("失败任务:")
        for t in failed_tasks:
            lines.append(f"  - {t.name} ({t.id})")
    return "\n".join(lines)


def get_decentralized_tools(status_reporter=None):
    """
    返回去中心化自协调工具集。
    team_id 固定为 ADK_TEAM_ID 环境变量(默认 swarm_team),LLM 无需传入。
    status_reporter: 可选,用于 dag_execute 实时上报任务状态卡片。
    """
    import functools
    import inspect

    FIXED_TEAM_ID = os.environ.get("ADK_TEAM_ID", "swarm_team")

    def bind_team(fn):
        """返回一个移除了 team_id 和 _status_reporter 参数、固定注入的 wrapper。"""
        sig = inspect.signature(fn)
        exclude = {"team_id", "_status_reporter"}
        new_params = [p for name, p in sig.parameters.items() if name not in exclude]
        new_sig = sig.replace(parameters=new_params)

        @functools.wraps(fn)
        async def wrapper(*args, **kwargs):
            kwargs["team_id"] = FIXED_TEAM_ID
            if "_status_reporter" in inspect.signature(fn).parameters:
                kwargs["_status_reporter"] = status_reporter
            return await fn(*args, **kwargs)

        wrapper.__signature__ = new_sig
        return wrapper

    raw_tools = [
        # Team Management
        team_create,
        team_join,
        team_leave,
        team_status,
        team_list_workers,
        # Task Management
        task_claim,
        task_complete,
        task_status,
        task_list,
        # Mailbox / Messaging
        mailbox_send,
        mailbox_read,
        mailbox_broadcast,
        # Worker Self-Management
        worker_status,
        worker_idle_report,
        # DAG
        dag_create,
        dag_execute,
    ]
    return [bind_team(fn) for fn in raw_tools]
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall