modlink-agent 1.1.0__py3-none-any.whl

modlink_agent/__init__.py

@@ -0,0 +1,58 @@
+# 文件名: __init__.py
+# 作 者: AI自动生成
+# 创建时间: 2026-10-06
+# 功能描述: 模联 Agent 工具包入口——对外暴露配置、客户端与主要方法
+# 作用域: modlink-agent SDK
+# 依赖关系: requests
+#
+# 中文注释：本包解决 Agent 调用模联的三个核心问题
+#   ① **二进制不进上下文**：ASR 要传音频、TTS/图像返回音频与图片。
+#      Agent 的上下文按 token 计费，一张 1024×1024 图 base64 约 1.4MB token，
+#      直接塞进工具返回会把上下文撑爆。本包统一「落盘 + 只回传路径」。
+#   ② **长任务不超时**：图像生成实测数十秒到数分钟，MCP 客户端默认超时常 30~60 秒。
+#      本包统一走「异步任务 + 轮询」或「长超时 + 明确提示」。
+#   ③ **429 自动退避**：图像模型互斥（同卡放不下两个 20B 模型），
+#      Agent 并发发起必然吃 429。本包统一读 Retry-After 并指数退避，
+#      重试耗尽后返回**中文可执行的提示**，而不是把 429 原样抛出去让 Agent 自己猜。
+#
+# 中文注释：按「族」而不是按「模型」组织工具
+#   平台有 20+ 个模型，一模型一工具会让 Agent 选择困难（工具列表过长、
+#   描述互相干扰）。因此对外只暴露 6 个族级方法，模型作为参数传入。
+#
+# 中文注释：为什么**不**封装 LLM 对话模型
+#   平台只有对话模型（qwen3-coder-next）同时具备「接受任意提示词」与
+#   「能调用工具」两个特性——其余模型都是「输入固定格式、输出固定格式」。
+#   把它做成 Agent 可调用的工具，等于把 Agent 的控制面交给不可信输入，
+#   提示词注入的后果是任意的（诱导读文件/跑命令/组合越权调用链）。
+#   详见 ModLinkClient 类内「族 5」处的完整说明。
+
+"""模联 Agent 工具包。"""
+
+from .version import __version__
+from .config import ModLinkConfig, load_config
+from .client import (
+    ModLinkClient,
+    ModLinkError,
+    AuthenticationError,
+    ForbiddenError,
+    InsufficientCredits,
+    RateLimitError,
+    ModelNotFound,
+    UpstreamError,
+    NetworkError,
+)
+
+__all__ = [
+    "ModLinkConfig",
+    "load_config",
+    "ModLinkClient",
+    "ModLinkError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "InsufficientCredits",
+    "RateLimitError",
+    "ModelNotFound",
+    "UpstreamError",
+    "NetworkError",
+    "__version__",
+]

modlink_agent/cli.py

@@ -0,0 +1,287 @@
+# 文件名: cli.py
+# 作 者: AI自动生成
+# 创建时间: 2026-10-06
+# 功能描述: 模联 Agent 工具包的命令行入口——按族聚合的子命令，管道友好
+# 作用域: modlink-agent SDK
+# 依赖关系: argparse；依赖本包的 client.py / config.py
+#
+# 中文注释：为什么 CLI 也是一等公民而不是「调试用的小玩意」
+#   ① 它是 MCP 的**兜底通道**——部分 Agent 宿主挂载 MCP 不稳，
+#      但只要能执行 shell，CLI 就能用。
+#   ② 排障效率差一个量级：MCP 出错时你看到的是「工具调用失败」，
+#      CLI 出错时你看到的是完整的 HTTP 状态与平台提示。
+#   ③ 二进制落盘路径、429 等待、异步轮询这些行为在 CLI 里**完全一致**——
+#      因为两者共用同一个 client.py，不存在「两边行为不同」的坑。
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from .client import ModLinkClient, ModLinkError
+from .config import ConfigError, load_config
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """中文注释：全局参数放在子命令之前（argparse 的 parent 机制），
+       但用 `--key` 这类名字刻意避免与子命令参数冲突。"""
+    parser = argparse.ArgumentParser(
+        prog="modlink",
+        description="模联 ModLink 命令行工具——把平台模型暴露给脚本与 AI Agent",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""环境变量：
+  MODLINK_API_KEY   API Key（推荐方式，等价于 --key 但不进 shell history）
+  MODLINK_BASE_URL  网关地址，默认 https://asr.syncmeet.tech:9443
+  MODLINK_WORK_DIR  音频/图片落盘目录，默认 ./modlink-out
+
+示例：
+  export MODLINK_API_KEY=ml_live_xxxxxxxx
+  modlink models
+  modlink translate "你好" --to 英语
+  modlink chat "用 Python 写一个快排"
+  modlink synthesize "欢迎使用模联" --model cosyvoice
+  modlink embed "模联平台" --dimensions 1024
+""",
+    )
+    # 中文注释：--key 优先级低于同名环境变量，见 config.load_config 的说明
+    parser.add_argument("--key", help="API Key（优先级低于环境变量 MODLINK_API_KEY）")
+    parser.add_argument("--base-url", help="网关地址")
+    parser.add_argument("--work-dir", help="二进制落盘目录")
+    parser.add_argument("--json", action="store_true",
+                        help="以 JSON 输出结果（供 Agent 解析）")
+
+    sub = parser.add_subparsers(dest="command", metavar="<命令>")
+
+    # ---- 能力自查 ----
+    sub.add_parser("models", help="列出当前 Key 可调用的模型")
+    sub.add_parser("health", help="检查平台与引擎可达性")
+
+    # ---- 族 1：转写 ----
+    p_asr = sub.add_parser("transcribe", help="语音转写")
+    p_asr.add_argument("audio", help="音频文件路径")
+    p_asr.add_argument("--model", default="funasr",
+                        help="funasr / sensevoice / paraformer-bilingual / zipformer-bilingual")
+    p_asr.add_argument("--language", help="语言代码，如 zh / en，留空自动识别")
+    p_asr.add_argument("--diarization", action="store_true", help="开启说话人分离（仅 funasr）")
+    p_asr.add_argument("--speaker-count", type=int, help="预估说话人数")
+    p_asr.add_argument("--hotwords", help="自定义热词，换行或空格分隔")
+    p_asr.add_argument("--async", dest="async_mode", action="store_true",
+                       help="强制走异步任务（长音频推荐）")
+
+    # ---- 族 2：合成 ----
+    p_tts = sub.add_parser("synthesize", help="语音合成")
+    p_tts.add_argument("text", help="要合成的文本")
+    p_tts.add_argument("--model", default="cosyvoice", help="cosyvoice / indextts")
+    p_tts.add_argument("--voice", help="音色")
+    p_tts.add_argument("--speed", type=float, help="语速")
+    p_tts.add_argument("--lang", help="合成语言，如 ZH / EN")
+    p_tts.add_argument("--prompt-audio", help="参考音频路径（提供则走音色克隆）")
+    p_tts.add_argument("--prompt-text", help="参考音频对应文本，提升克隆相似度")
+    p_tts.add_argument("--output", help="输出文件路径（默认自动命名落盘）")
+
+    # ---- 族 3：翻译 ----
+    p_tr = sub.add_parser("translate", help="文本翻译（38 语种）")
+    p_tr.add_argument("text", help="待译文本（多行按行批量）")
+    p_tr.add_argument("--to", dest="target_lang", default="英语", help="目标语言名，如 英语")
+    p_tr.add_argument("--from", dest="source_lang", help="源语言，留空自动识别")
+    p_tr.add_argument("--style", help="风格要求，如「正式书面语」")
+    p_tr.add_argument("--terminology", help="术语表，换行分隔「源文=译文」")
+    p_tr.add_argument("--summary", action="store_true", help="只输出摘要")
+
+    # ---- 族 4：向量化 ----
+    p_emb = sub.add_parser("embed", help="文本向量化")
+    p_emb.add_argument("texts", nargs="+", help="一个或多个文本")
+    p_emb.add_argument("--model", default="qwen3-embedding")
+    p_emb.add_argument("--dimensions", type=int, help="向量维度（32~2560，留空为原生维度）")
+
+    # ---- 族 5：LLM 对话（刻意不提供，见下方说明） ----
+    # 中文注释：这里**刻意没有** chat 子命令。
+    #   平台只有对话模型接受任意提示词且能调用工具，
+    #   把它做成 Agent 可调用的命令等于把 Agent 控制面交给不可信输入——
+    #   提示词注入的后果是任意的（诱导读文件、跑命令、组合越权链）。
+    #   需要用对话模型请直接调平台的 /v1/chat/completions。
+
+    # ---- 族 6：图像 ----
+    p_img = sub.add_parser("image", help="图像处理")
+    p_img.add_argument("image", help="输入图片路径")
+    p_img.add_argument("--task", default="remove_background",
+                       help="remove_background / erase / upscale / face_restore / face_swap")
+    p_img.add_argument("--model", help="模型标识，留空按任务推断")
+    p_img.add_argument("--mask", help="掩膜图路径（erase 任务必填）")
+    p_img.add_argument("--source-image", help="人脸来源图路径（face_swap 任务必填）")
+    p_img.add_argument("--options", help="引擎专属参数（JSON 字符串）")
+    p_img.add_argument("--output", help="输出图片路径")
+
+    p_gen = sub.add_parser("generate", help="图像生成 / 图生图")
+    p_gen.add_argument("prompt", help="提示词")
+    p_gen.add_argument("--model", default="flux2-generate", help="flux2-generate / qwen-image-2.1")
+    p_gen.add_argument("--width", type=int, default=1024)
+    p_gen.add_argument("--height", type=int, default=1024)
+    p_gen.add_argument("--steps", type=int, help="采样步数")
+    p_gen.add_argument("--seed", type=int, help="随机种子（固定值可复现）")
+    p_gen.add_argument("--negative-prompt", help="负向提示词")
+    p_gen.add_argument("--image", help="输入图片路径（提供则走图生图/指令编辑）")
+    p_gen.add_argument("--output", help="输出图片路径")
+
+    return parser
+
+
+def _emit(args: argparse.Namespace, payload, human_text: str) -> None:
+    """中文注释：双输出模式——`--json` 给 Agent 解析，人读时给可读文本。
+
+    为什么不做成只有一种：Agent 需要结构化输出做后续决策，
+    人需要可读输出判断结果对不对。强制二选一会让其中一边难受。
+    """
+    if getattr(args, "json", False):
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(human_text)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """CLI 入口
+
+    中文注释：返回退出码而不是 sys.exit——便于被其他程序当函数调用，
+       也便于单测直接断言返回值。
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    try:
+        # 中文注释：CLI 允许交互式输入 Key（首次使用友好），
+        #   MCP server 侧则不传 interactive=True（见 mcp_server.py）。
+        config = load_config(
+            api_key=args.key,
+            base_url=args.base_url,
+            work_dir=args.work_dir,
+            interactive=True,
+        )
+        client = ModLinkClient(config=config)
+    except ConfigError as exc:
+        print(f"配置错误：{exc}", file=sys.stderr)
+        return 2
+
+    try:
+        return _dispatch(args, client)
+    except ModLinkError as exc:
+        # 中文注释：错误打 stderr 且退出码非 0——
+        #   Agent 通过 shell 调 CLI 时能靠退出码判断成败，不只看 stdout。
+        print(f"调用失败：{exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("已中断", file=sys.stderr)
+        return 130
+
+
+def _dispatch(args: argparse.Namespace, client: ModLinkClient) -> int:
+    """按子命令分发"""
+    command = args.command
+
+    # ---- 能力自查 ----
+    if command == "models":
+        models = client.list_models()
+        if args.json:
+            _emit(args, models, "")
+        else:
+            print(f"当前 Key 可调用 {len(models)} 个模型：")
+            for item in models:
+                flag = "就绪" if item.get("ready") else "未就绪"
+                caps = ",".join(item.get("capabilities") or [])
+                print(f"  {item['id']:<26} {flag:<6} {caps}")
+        return 0
+
+    if command == "health":
+        ok = client.health()
+        _emit(args, {"healthy": ok}, "平台可达" if ok else "平台不可达")
+        return 0 if ok else 1
+
+    # ---- 族 1：转写 ----
+    if command == "transcribe":
+        # 中文注释：按音频大小启发式决定是否走异步——
+        #   经验阈值 20MB（约 30 分钟以上的 wav/mp3）。
+        #   调用方可用 --async 强制覆盖。
+        import os
+
+        size_mb = os.path.getsize(args.audio) / 1024 / 1024
+        async_mode = args.async_mode or size_mb > 20
+        result = client.transcribe(
+            args.audio, model=args.model, language=args.language,
+            diarization=args.diarization, speaker_count=args.speaker_count,
+            hotwords=args.hotwords, async_mode=async_mode,
+        )
+        _emit(args, result, result.get("text", ""))
+        return 0
+
+    # ---- 族 2：合成 ----
+    if command == "synthesize":
+        result = client.synthesize(
+            args.text, model=args.model, voice=args.voice, speed=args.speed,
+            lang=args.lang, prompt_audio=args.prompt_audio,
+            prompt_text=args.prompt_text, output_path=args.output,
+        )
+        _emit(args, {"path": str(result.path), "size_bytes": result.size_bytes,
+                     "meta": result.meta},
+              result.describe())
+        return 0
+
+    # ---- 族 3：翻译 ----
+    if command == "translate":
+        terminology = None
+        if args.terminology:
+            terminology = [line.strip() for line in args.terminology.split("\n") if line.strip()]
+        results = client.translate(
+            args.text, target_lang=args.target_lang, source_lang=args.source_lang,
+            terminology=terminology, style=args.style, summary=args.summary,
+        )
+        _emit(args, {"translations": results}, "\n".join(results))
+        return 0
+
+    # ---- 族 4：向量化 ----
+    if command == "embed":
+        vectors = client.embed(args.texts, model=args.model, dimensions=args.dimensions)
+        # 中文注释：默认**不**打印向量本身——2560 维浮点数会把终端刷满，
+        #   对 Agent 也没有意义（它要用这个向量去做检索，不是读数字）。
+        #   需要原始向量时用 --json。
+        if args.json:
+            _emit(args, {"vectors": vectors, "count": len(vectors)}, "")
+        else:
+            dims = len(vectors[0]) if vectors else 0
+            print(f"已生成 {len(vectors)} 个向量，维度 {dims}")
+            if dims:
+                preview = [round(v, 4) for v in vectors[0][:5]]
+                print(f"  首个向量前 5 维：{preview} ...")
+        return 0
+
+    # ---- 族 6：图像 ----
+    if command == "image":
+        options = json.loads(args.options) if args.options else None
+        result = client.process_image(
+            args.image, task_type=args.task, model=args.model,
+            mask=args.mask, source_image=args.source_image,
+            options=options, output_path=args.output,
+        )
+        _emit(args, {"path": str(result.path), "size_bytes": result.size_bytes},
+              result.describe())
+        return 0
+
+    if command == "generate":
+        result = client.generate_image(
+            args.prompt, model=args.model, width=args.width, height=args.height,
+            steps=args.steps, seed=args.seed, negative_prompt=args.negative_prompt,
+            image=args.image, output_path=args.output,
+        )
+        _emit(args, {"path": str(result.path), "size_bytes": result.size_bytes,
+                     "meta": result.meta},
+              result.describe())
+        return 0
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())