#!/usr/bin/env python3
"""协作工具 —— 统一命令行入口 (实验 4-4)

《深入理解 AI Agent》第 4 章 实验 4-4「协作工具 MCP 服务器」的命令行界面。
在不启动 MCP 服务器的前提下，直接列出、单独调用各协作工具，并运行端到端演示。

协作工具分三类（对应书中"协作工具"一节）：
  1. 子 Agent 管理：spawn_subagent / send_message_to_subagent / cancel_subagent
     （支持同步/异步两种模式，以及 minimal / llm_generated 两种上下文传递策略）
  2. 人类协作（HITL）：request_admin_approval / request_admin_input（含超时与默认行为）
  3. 多渠道通知：email / slack / telegram / discord

示例：
  python main.py list                     # 列出全部协作工具
  python main.py demo                      # 运行离线端到端协作演示（无需 API Key）
  python main.py subagent compare          # 对比两种上下文传递策略
  python main.py subagent spawn --task "查询订单 A12345 状态" --strategy minimal
  python main.py hitl approve --message "删除 1000 条记录？" --timeout 5 --auto-approve
  python main.py notify slack --message "部署完成 ✅"

说明：
  - 子 Agent 的执行、以及 llm_generated 上下文策略需要 OPENAI_API_KEY；
    未配置时自动退回到确定性的离线模拟（结果会明确标注"未调用 LLM"）。
  - 真实发送通知 / 邮件需要在 .env 中配置对应渠道的凭据；未配置时工具会
    返回"未配置"的说明，命令本身仍可正常解析与运行。
"""

import argparse
import asyncio
import json
import os
import sys

# src/ 下的模块使用裸导入（与 quickstart.py / subagent_comparison.py 一致）
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))

import subagent_tools as sa  # noqa: E402
import hitl_tools as hitl  # noqa: E402
import notification_tools as notify  # noqa: E402


def _print(obj) -> None:
    """统一以带缩进的 JSON 打印工具返回结果。"""
    print(json.dumps(obj, ensure_ascii=False, indent=2, default=str))


def _parse_json_arg(value):
    """尝试按 JSON 解析；不是合法 JSON 时按原始字符串返回（供子 Agent 直接使用）。"""
    if value is None:
        return None
    try:
        return json.loads(value)
    except json.JSONDecodeError:
        return value


# ---------------------------------------------------------------------------
# 工具清单
# ---------------------------------------------------------------------------

COLLAB_TOOLS = {
    "子 Agent 管理": [
        ("spawn_subagent", "创建子 Agent（同步/异步，minimal/llm_generated 上下文策略）"),
        ("send_message_to_subagent", "向子 Agent 发送后续消息并获取回复"),
        ("cancel_subagent", "取消子 Agent（异步任务会中止后台协程）"),
        ("get_subagent_status", "查询子 Agent 状态与结果（用于异步）"),
    ],
    "人类协作 (HITL)": [
        ("request_admin_approval", "关键决策前请求管理员批准（支持超时与默认行为）"),
        ("request_admin_input", "向管理员请求补充输入"),
        ("respond_to_request", "管理员对待处理请求作出批准/拒绝"),
        ("list_pending_requests", "列出全部待处理的审批请求"),
    ],
    "多渠道通知": [
        ("send_email", "发送邮件通知（SMTP / SendGrid）"),
        ("send_slack_message", "通过 Webhook 发送 Slack 消息"),
        ("send_telegram_message", "发送 Telegram 消息"),
        ("send_discord_message", "通过 Webhook 发送 Discord 消息"),
    ],
}


def cmd_list(args) -> None:
    print("协作工具清单（实验 4-4）\n" + "=" * 60)
    for category, tools in COLLAB_TOOLS.items():
        print(f"\n【{category}】")
        for name, desc in tools:
            print(f"  - {name:<28} {desc}")
    print("\n提示：`python main.py <子命令> -h` 查看每个工具的参数。")


# ---------------------------------------------------------------------------
# 子 Agent 子命令
# ---------------------------------------------------------------------------

async def _subagent_dispatch(args) -> None:
    if args.sub_action == "spawn":
        res = await sa.spawn_subagent(
            task=args.task,
            context_strategy=args.strategy,
            mode=args.mode,
            parent_context=_parse_json_arg(args.parent_context),
            role=args.role,
            minimal_slice=_parse_json_arg(args.minimal_slice),
            business_rules=args.business_rules,
        )
        _print(res)
    elif args.sub_action == "send":
        _print(await sa.send_message_to_subagent(args.id, args.message))
    elif args.sub_action == "cancel":
        _print(await sa.cancel_subagent(args.id))
    elif args.sub_action == "status":
        _print(await sa.get_subagent_status(args.id))
    elif args.sub_action == "compare":
        await sa.run_context_strategy_comparison(task=args.task)


def cmd_subagent(args) -> None:
    asyncio.run(_subagent_dispatch(args))


# ---------------------------------------------------------------------------
# HITL 子命令
# ---------------------------------------------------------------------------

async def _auto_responder(approve: bool, notes: str, delay: float = 1.0) -> None:
    """模拟管理员：轮询待处理请求并作答，用于离线演示 HITL 闭环。"""
    await asyncio.sleep(delay)
    pending = await hitl.list_pending_requests()
    for req in pending.get("requests", []):
        await hitl.respond_to_request(req["request_id"], approve, notes)


async def _hitl_dispatch(args) -> None:
    if args.hitl_action == "approve":
        coro = hitl.request_admin_approval(
            request_message=args.message,
            timeout_seconds=args.timeout,
            urgent=args.urgent,
        )
        if args.auto_approve or args.auto_reject:
            responder = _auto_responder(
                approve=not args.auto_reject,
                notes=args.notes or ("自动模拟批准" if not args.auto_reject else "自动模拟拒绝"),
            )
            res, _ = await asyncio.gather(coro, responder)
        else:
            res = await coro
        _print(res)
    elif args.hitl_action == "input":
        coro = hitl.request_admin_input(prompt=args.prompt, timeout_seconds=args.timeout)
        if args.auto_answer is not None:
            responder = _auto_responder(approve=True, notes=args.auto_answer)
            res, _ = await asyncio.gather(coro, responder)
        else:
            res = await coro
        _print(res)
    elif args.hitl_action == "respond":
        _print(await hitl.respond_to_request(args.id, args.approve, args.notes))
    elif args.hitl_action == "list":
        _print(await hitl.list_pending_requests())


def cmd_hitl(args) -> None:
    asyncio.run(_hitl_dispatch(args))


# ---------------------------------------------------------------------------
# 通知子命令
# ---------------------------------------------------------------------------

async def _notify_dispatch(args) -> None:
    if args.channel == "email":
        _print(await notify.send_email(args.to, args.subject, args.body))
    elif args.channel == "slack":
        _print(await notify.send_slack_message(args.message, webhook_url=args.webhook))
    elif args.channel == "telegram":
        _print(await notify.send_telegram_message(args.message, chat_id=args.chat_id))
    elif args.channel == "discord":
        _print(await notify.send_discord_message(args.message, webhook_url=args.webhook))


def cmd_notify(args) -> None:
    asyncio.run(_notify_dispatch(args))


# ---------------------------------------------------------------------------
# 端到端演示：客服协调 Agent 处理一笔退款
# ---------------------------------------------------------------------------

def _neutralize_network_creds() -> None:
    """演示前清空 .env 中的占位凭据，避免离线演示尝试真实网络请求而阻塞。"""
    from config import config

    config.email.smtp_username = None
    config.email.smtp_password = None
    config.email.sendgrid_api_key = None
    config.im.telegram_bot_token = None
    config.im.slack_webhook_url = None
    config.im.discord_webhook_url = None
    config.hitl.webhook_url = None
    config.hitl.admin_email = None


async def _demo() -> None:
    _neutralize_network_creds()
    online = bool(os.getenv("OPENAI_API_KEY"))

    print("=" * 74)
    print("端到端协作演示：客服协调 Agent 处理一笔退款")
    print(f"（子 Agent 执行模式：{'在线 LLM' if online else '离线模拟（未配置 OPENAI_API_KEY）'}）")
    print("=" * 74)

    print("\n[步骤 1/3] 委派子 Agent 审批退款，并对比两种上下文传递策略")
    print("-" * 74)
    if not online:
        print("（提示：未配置 OPENAI_API_KEY，子 Agent 的执行与 llm_generated 策略")
        print("  会返回错误，仅用于展示接口与上下文构建；配置 Key 后可看到真实结果。）")
    await sa.run_context_strategy_comparison()

    print("\n[步骤 2/3] 大额操作触发 HITL：向管理员请求批准（含超时与默认行为）")
    print("-" * 74)
    print("→ 场景 A：管理员在超时前批准（后台模拟应答）")
    approval, _ = await asyncio.gather(
        hitl.request_admin_approval(
            request_message="退款金额 8888 元，超过自动批准阈值，请人工确认。",
            timeout_seconds=10,
            urgent=True,
        ),
        _auto_responder(approve=True, notes="核对无误，同意退款", delay=1.0),
    )
    _print(approval)

    print("\n→ 场景 B：管理员未及时响应，触发超时与保守默认（不批准）")
    timeout_res = await hitl.request_admin_approval(
        request_message="退款金额 8888 元，请人工确认。",
        timeout_seconds=2,
    )
    _print(timeout_res)

    print("\n[步骤 3/3] 多渠道通知协作者处理结果")
    print("-" * 74)
    summary = "退款工单 A12345：子 Agent 审批通过，管理员已确认，已放款。"
    for channel, coro in (
        ("email", notify.send_email("admin@example.com", "退款处理完成", summary)),
        ("slack", notify.send_slack_message(summary)),
        ("telegram", notify.send_telegram_message(summary)),
    ):
        res = await coro
        status = "已发送" if res.get("success") else f"未发送（{res.get('error')}）"
        print(f"  [{channel:<8}] {status}：{summary}")

    print("\n" + "=" * 74)
    print("演示结束。真实发送通知/邮件需在 .env 配置对应渠道凭据；")
    print("子 Agent 的真实 LLM 执行与 llm_generated 策略需配置 OPENAI_API_KEY。")
    print("=" * 74)


def cmd_demo(args) -> None:
    asyncio.run(_demo())


# ---------------------------------------------------------------------------
# argparse
# ---------------------------------------------------------------------------

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="main.py",
        description="协作工具命令行入口（实验 4-4）：子 Agent 管理 / 人类协作 / 多渠道通知",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "示例：\n"
            "  python main.py list\n"
            "  python main.py demo\n"
            "  python main.py subagent compare\n"
            "  python main.py subagent spawn --task '查询订单 A12345 状态' --strategy minimal\n"
            "  python main.py hitl approve --message '删除 1000 条记录？' --timeout 5 --auto-approve\n"
            "  python main.py notify slack --message '部署完成'\n"
        ),
    )
    sub = parser.add_subparsers(dest="command", required=True, metavar="<命令>")

    sub.add_parser("list", help="列出全部协作工具").set_defaults(func=cmd_list)

    p_demo = sub.add_parser("demo", help="运行离线端到端协作演示（无需 API Key）")
    p_demo.set_defaults(func=cmd_demo)

    # subagent
    p_sa = sub.add_parser("subagent", help="子 Agent 管理工具")
    sa_sub = p_sa.add_subparsers(dest="sub_action", required=True, metavar="<动作>")

    p_spawn = sa_sub.add_parser("spawn", help="创建子 Agent")
    p_spawn.add_argument("--task", required=True, help="委派给子 Agent 的子任务")
    p_spawn.add_argument("--strategy", default="minimal",
                         choices=["minimal", "llm_generated"], help="上下文传递策略")
    p_spawn.add_argument("--mode", default="sync", choices=["sync", "async"],
                         help="sync 同步等待结果；async 返回 task_id")
    p_spawn.add_argument("--role", default=None, help="子 Agent 的角色（用于系统提示词）")
    p_spawn.add_argument("--parent-context", default=None,
                         help="主 Agent 轨迹/状态（JSON 字符串）")
    p_spawn.add_argument("--minimal-slice", default=None,
                         help="minimal 策略下手动挑选的信息（字符串或 JSON）")
    p_spawn.add_argument("--business-rules", default=None,
                         help="llm_generated 策略下的隐私/压缩规则")

    p_send = sa_sub.add_parser("send", help="向子 Agent 发送后续消息")
    p_send.add_argument("--id", required=True, help="子 Agent ID")
    p_send.add_argument("--message", required=True, help="消息内容")

    p_cancel = sa_sub.add_parser("cancel", help="取消子 Agent")
    p_cancel.add_argument("--id", required=True, help="子 Agent ID")

    p_status = sa_sub.add_parser("status", help="查询子 Agent 状态/结果")
    p_status.add_argument("--id", required=True, help="子 Agent ID")

    p_cmp = sa_sub.add_parser("compare", help="对比 minimal 与 llm_generated 两种策略")
    p_cmp.add_argument("--task", default=None, help="用于对比的共同子任务")
    p_sa.set_defaults(func=cmd_subagent)

    # hitl
    p_hitl = sub.add_parser("hitl", help="人类协作（HITL）工具")
    hitl_sub = p_hitl.add_subparsers(dest="hitl_action", required=True, metavar="<动作>")

    p_appr = hitl_sub.add_parser("approve", help="请求管理员批准")
    p_appr.add_argument("--message", required=True, help="需要批准的内容")
    p_appr.add_argument("--timeout", type=int, default=None, help="等待秒数（超时后按默认行为）")
    p_appr.add_argument("--urgent", action="store_true", help="标记为紧急")
    p_appr.add_argument("--auto-approve", action="store_true", help="后台模拟管理员批准（离线演示用）")
    p_appr.add_argument("--auto-reject", action="store_true", help="后台模拟管理员拒绝（离线演示用）")
    p_appr.add_argument("--notes", default=None, help="管理员备注")

    p_inp = hitl_sub.add_parser("input", help="向管理员请求输入")
    p_inp.add_argument("--prompt", required=True, help="问题/提示")
    p_inp.add_argument("--timeout", type=int, default=None, help="等待秒数")
    p_inp.add_argument("--auto-answer", default=None, help="后台模拟管理员回答（离线演示用）")

    p_resp = hitl_sub.add_parser("respond", help="管理员对请求作答")
    p_resp.add_argument("--id", required=True, help="请求 ID")
    grp = p_resp.add_mutually_exclusive_group(required=True)
    grp.add_argument("--approve", dest="approve", action="store_true", help="批准")
    grp.add_argument("--reject", dest="approve", action="store_false", help="拒绝")
    p_resp.add_argument("--notes", default=None, help="备注")

    hitl_sub.add_parser("list", help="列出待处理请求")
    p_hitl.set_defaults(func=cmd_hitl)

    # notify
    p_notify = sub.add_parser("notify", help="多渠道通知工具")
    notify_sub = p_notify.add_subparsers(dest="channel", required=True, metavar="<渠道>")

    p_email = notify_sub.add_parser("email", help="发送邮件")
    p_email.add_argument("--to", required=True, help="收件人")
    p_email.add_argument("--subject", required=True, help="主题")
    p_email.add_argument("--body", required=True, help="正文")

    p_slack = notify_sub.add_parser("slack", help="发送 Slack 消息")
    p_slack.add_argument("--message", required=True, help="消息内容")
    p_slack.add_argument("--webhook", default=None, help="Slack Webhook URL（默认取 .env）")

    p_tg = notify_sub.add_parser("telegram", help="发送 Telegram 消息")
    p_tg.add_argument("--message", required=True, help="消息内容")
    p_tg.add_argument("--chat-id", default=None, help="Telegram chat id（默认取 .env）")

    p_dc = notify_sub.add_parser("discord", help="发送 Discord 消息")
    p_dc.add_argument("--message", required=True, help="消息内容")
    p_dc.add_argument("--webhook", default=None, help="Discord Webhook URL（默认取 .env）")
    p_notify.set_defaults(func=cmd_notify)

    return parser


def main() -> None:
    parser = build_parser()
    args = parser.parse_args()
    args.func(args)


if __name__ == "__main__":
    main()