Agent 工具工程：权限、幂等、超时和副作用控制

from dataclasses import dataclass
from uuid import uuid4


@dataclass(frozen=True)
class RuntimeContext:
    user_id: str
    scopes: frozenset[str]


DEVICES = {"AX-3": {"team": "team-a", "status": "offline"}}
WORK_ORDERS: dict[str, dict] = {}


def get_device(device_id: str, context: RuntimeContext) -> dict:
    device = DEVICES.get(device_id)
    if not device:
        return {"ok": False, "error": "not_found"}
    if device["team"] not in context.scopes:
        return {"ok": False, "error": "forbidden"}
    return {"ok": True, "device_id": device_id, "status": device["status"]}


def create_work_order(
    device_id: str,
    reason: str,
    idempotency_key: str,
    confirmation: str | None,
    context: RuntimeContext,
) -> dict:
    if confirmation != "approved":
        return {"ok": False, "error": "approval_required"}
    if idempotency_key in WORK_ORDERS:
        return {"ok": True, "replayed": True, **WORK_ORDERS[idempotency_key]}
    device = get_device(device_id, context)
    if not device["ok"]:
        return device
    order = {"work_order_id": f"WO-{uuid4().hex[:8]}", "device_id": device_id, "reason": reason[:120]}
    WORK_ORDERS[idempotency_key] = order
    return {"ok": True, "replayed": False, **order}


context = RuntimeContext("u-17", frozenset({"team-a"}))
print(get_device("AX-3", context))
print(create_work_order("AX-3", "设备离线", "task-88:create", None, context))
print(create_work_order("AX-3", "设备离线", "task-88:create", "approved", context))
print(create_work_order("AX-3", "设备离线", "task-88:create", "approved", context))