valkryhx/google_adk_agent / skills/agent_team_to_be_update
Agent 团队协作(去中心化拉模型)
Flagged赋予 Agent 作为集群指挥官(Leader)的能力,通过去中心化任务队列将子任务派发给 Worker 节点并发执行。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.9 KB |
| decentralized_tools.py | script | 36.2 KB |
| dependency_analyzer.py | script | 10.9 KB |
| inbox_watcher.py | script | 8.5 KB |
| loop_executor.py | script | 16.4 KB |
| mailbox.py | script | 15.3 KB |
| models.py | script | 9.1 KB |
| path_guard.py | script | 13.3 KB |
| planner.py | script | 14.6 KB |
| polling_daemon.py | script | 7.7 KB |
| self_claim_loop.py | script | 20.1 KB |
| task_queue.py | script | 24.1 KB |
| team_config.py | script | 7.5 KB |
| test/__init__.py | script | 40 B |
| test/test_blog_system_develop.py | script | 12.0 KB |
| test/test_dag_create_validation.py | script | 2.7 KB |
| test/test_decentralized_arch.py | script | 36.9 KB |
| test/test_deepresearch.py | script | 14.6 KB |
| test/test_loop_dag.py | script | 17.0 KB |
| test/test_real_training.py | script | 9.2 KB |
| test/test_tdd_gate.py | script | 4.5 KB |
| tools.py | script | 85.8 KB |
| verification_hooks.py | script | 10.7 KB |
| worktree_manager.py | script | 12.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]
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |