pandaai-cli 0.1.0__py3-none-any.whl

pandaai/factor.py

@@ -0,0 +1,96 @@
+"""因子分析结果格式化"""
+
+import json
+
+# ─── 因子分析接口列表（前端 FactorAnalysisChartControl 全屏查看时调用） ───
+
+FACTOR_ANALYSIS_ENDPOINTS = [
+    "query_factor_analysis_data",
+    "query_one_group_data",
+    "query_group_return_analysis",
+    "query_last_date_top_factor",
+    "query_return_chart",
+    "query_ic_decay_chart",
+    "query_ic_density_chart",
+    "query_ic_sequence_chart",
+    "query_ic_self_correlation_chart",
+    "query_rank_ic_decay_chart",
+    "query_rank_ic_density_chart",
+    "query_rank_ic_sequence_chart",
+    "query_rank_ic_self_correlation_chart",
+    "query_factor_excess_chart",
+]
+
+
+def format_factor_analysis_results(results: dict) -> str:
+    """格式化因子分析结果为可读文本"""
+    lines = []
+    fa = results.get("factor_analysis", {})
+
+    # ── 核心绩效（query_one_group_data） ──
+    one_group = fa.get("query_one_group_data", {})
+    if isinstance(one_group, dict):
+        core_items = [
+            ("因子收益", one_group.get("return_ratio", "")),
+            ("夏普比率", one_group.get("sharpe_ratio", "")),
+            ("年化收益", one_group.get("annualized_ratio", "")),
+            ("最大回撤", one_group.get("maximum_drawdown", "")),
+        ]
+        lines.append("━━━ 核心绩效 ━━━")
+        lines.append(f"{'指标':<22} {'数值':<15}")
+        lines.append("-" * 37)
+        for label, val in core_items:
+            lines.append(f"{label:<22} {val:<15}")
+
+    # ── 因子分析指标 ──
+    indicators = fa.get("query_factor_analysis_data", [])
+    if not isinstance(indicators, list):
+        indicators = indicators.get("factor_data_analysis", []) if isinstance(indicators, dict) else []
+    if indicators:
+        lines.append("━━━ 因子分析指标 ━━━")
+        lines.append(f"{'指标':<22} {'数值':<15}")
+        lines.append("-" * 37)
+        for item in indicators:
+            if isinstance(item, dict):
+                lines.append(f"{item['indicator']:<22} {item.get('factor1', item.get('value', '')):<15}")
+
+    # ── 分组收益 ──
+    groups = fa.get("query_group_return_analysis", [])
+    if not isinstance(groups, list):
+        groups = groups.get("group_return_analysis", []) if isinstance(groups, dict) else []
+    if groups:
+        lines.append("\n━━━ 分组收益分析 ━━━")
+        header = f"{'分组':<8} {'年化收益':<12} {'超额收益':<12} {'夏普比率':<10} {'最大回撤':<10} {'月胜率':<10}"
+        lines.append(header)
+        lines.append("-" * len(header))
+        for g in groups:
+            lines.append(
+                f"{g.get('group',''):<8} "
+                f"{g.get('annualizedReturn',''):<12} "
+                f"{g.get('excessAnnualized',''):<12} "
+                f"{g.get('sharpeRatio',''):<10} "
+                f"{g.get('maxDrawdown',''):<10} "
+                f"{g.get('monthlyWinRate',''):<10}"
+            )
+
+    # ── 最新日期 Top 因子 ──
+    top_factors = fa.get("query_last_date_top_factor", [])
+    if not isinstance(top_factors, list):
+        top_factors = top_factors.get("last_date_top_factor", []) if isinstance(top_factors, dict) else []
+    if top_factors:
+        lines.append("\n━━━ 最新日期 Top 因子 ━━━")
+        lines.append(f"{'股票代码':<16} {'名称':<10} {'因子值':<10}")
+        lines.append("-" * 36)
+        for item in top_factors[:10]:
+            lines.append(f"{item.get('symbol',''):<16} {item.get('name',''):<10} {item.get('factor1',''):<10}")
+
+    # ── 图表数据 ──
+    chart_keys = [k for k in fa if k.endswith("_chart") and fa[k] is not None]
+    if chart_keys:
+        lines.append(f"\n━━━ 图表数据 ━━━")
+        for key in sorted(chart_keys):
+            chart = fa[key]
+            lines.append(f"\n  [{key}]")
+            lines.append(json.dumps(chart, ensure_ascii=False, indent=2))
+
+    return "\n".join(lines) if lines else "(无分析结果)"

pandaai/factor_core.py

@@ -0,0 +1,283 @@
+"""因子分析创建、执行、轮询"""
+
+import json
+import sys
+import time
+from typing import Optional, Dict, Any
+
+import requests
+
+from .auth import api_url, make_headers
+from .constants import STATUS_PENDING, STATUS_RUNNING, STATUS_SUCCESS, STATUS_FAILED, STATUS_BILLING_STOP
+
+
+def _fail(error_type: str, message: str) -> None:
+    from .formatting import format_failure
+    print(json.dumps(format_failure(status="ERROR", error_type=error_type, message=message), ensure_ascii=False))
+    sys.exit(1)
+
+
+def create_factor(config: dict, token: str, uid: str, factor_json: dict) -> str:
+    """保存因子分析，返回 factor_id"""
+    url = api_url(config, "/quantflow/api/workflow/save")
+    try:
+        resp = requests.post(url, json=factor_json, headers=make_headers(token=token, uid=uid), timeout=15)
+        data = resp.json()
+    except Exception as e:
+        return _fail("CREATE_FAILED", f"创建因子分析请求失败: {e}")
+
+    if resp.status_code == 402:
+        detail = data.get("detail", {})
+        if isinstance(detail, dict):
+            level = detail.get("memberLevel", "?")
+            recommend = detail.get("recommendLevelCode", "?")
+            msg = (f"因子分析数量已达上限 (已用{detail.get('currentUsage','?')}/{detail.get('quotaValue','?')}) "
+                   f"| 当前会员: {level} | 推荐升级: {recommend}")
+            return _fail("CREATE_FAILED", msg)
+        return _fail("CREATE_FAILED", f"创建因子分析失败: {resp.text[:300]}")
+    if resp.status_code >= 400:
+        return _fail("CREATE_FAILED", f"创建因子分析失败(HTTP{resp.status_code}): {resp.text[:300]}")
+    if data.get("code") != 0:
+        return _fail("CREATE_FAILED", f"创建因子分析失败: {data.get('message', data.get('detail', resp.text[:200]))}")
+
+    wf_id = data.get("data", {}).get("workflow_id")
+    if not wf_id:
+        return _fail("CREATE_FAILED", "响应中没有 workflow_id")
+
+    return wf_id
+
+
+def run_factor(config: dict, token: str, uid: str, factor_id: str):
+    """启动因子分析运行，返回 (factor_run_id, error_message)。使用默认算力 cpu=4, mem=8, gpu=4"""
+    url = api_url(config, "/quantflow/api/workflow/run_with_store")
+    body = {
+        "workflow_id": factor_id,
+        "server_cpu": 4,
+        "server_memory": 8,
+        "server_gpu": 4,
+    }
+    try:
+        resp = requests.post(url, json=body,
+                           headers=make_headers(token=token, uid=uid, extra={"quantflow-auth": "2"}), timeout=15)
+        data = resp.json()
+    except Exception as e:
+        return None, f"启动因子分析请求失败: {e}"
+
+    if resp.status_code >= 400:
+        detail = data.get("detail", data.get("message", ""))
+        if isinstance(detail, dict):
+            detail = json.dumps(detail, ensure_ascii=False)
+        return None, f"HTTP {resp.status_code}, code={data.get('code')}: {detail or resp.text[:300]}"
+
+    run_id = data.get("data", {}).get("workflow_run_id")
+    if not run_id:
+        return None, f"响应中没有 workflow_run_id: {resp.text[:300]}"
+
+    return run_id, None
+
+
+def poll_factor_run(config: dict, token: str, uid: str, run_id: str,
+                    poll_interval: int = 2, timeout: int = 600) -> Dict[str, Any]:
+    """轮询因子分析运行状态，直到完成/失败/超时"""
+    start_ts = time.time()
+    url = api_url(config, "/quantflow/api/workflow/run")
+    log_url = api_url(config, "/quantflow/api/workflow/run/log")
+
+    while True:
+        elapsed = time.time() - start_ts
+        if elapsed > timeout:
+            return {"status": "TIMEOUT", "start_time": None, "end_time": None,
+                    "failed_node_ids": [], "errors": [{"message": f"轮询超时 ({timeout}s)"}]}
+
+        try:
+            resp = requests.get(url, params={"workflow_run_id": run_id},
+                              headers=make_headers(token=token, uid=uid), timeout=10)
+            data = resp.json()
+        except Exception:
+            time.sleep(poll_interval)
+            continue
+
+        if data.get("code") != 0:
+            time.sleep(poll_interval)
+            continue
+
+        run_data = data.get("data", {})
+        status = run_data.get("status", STATUS_RUNNING)
+        failed_node_ids = run_data.get("failed_node_ids", [])
+        start_time = run_data.get("start_time")
+        end_time = run_data.get("end_time")
+
+        if status == STATUS_SUCCESS:
+            return {"status": status, "start_time": start_time, "end_time": end_time,
+                    "failed_node_ids": [], "errors": []}
+
+        if status == STATUS_FAILED:
+            errors = _fetch_factor_run_errors(config, token, uid, run_id, log_url)
+            return {"status": status, "start_time": start_time, "end_time": end_time,
+                    "failed_node_ids": failed_node_ids, "errors": errors}
+
+        if status == STATUS_BILLING_STOP:
+            return {"status": status, "start_time": start_time, "end_time": end_time,
+                    "failed_node_ids": [], "errors": [{"message": "余额不足，因子分析已被服务端终止"}]}
+
+        time.sleep(poll_interval)
+
+
+def _fetch_factor_run_errors(config: dict, token: str, uid: str, run_id: str, log_url: str) -> list:
+    """从运行日志中提取节点错误信息"""
+    try:
+        resp = requests.get(log_url, params={"workflow_run_id": run_id},
+                          headers=make_headers(token=token, uid=uid), timeout=10)
+        data = resp.json()
+        if data.get("code") != 0:
+            return [{"message": f"获取日志失败, code={data.get('code')}, raw={resp.text[:500]}"}]
+
+        log_data = data.get("data", {})
+        node_errors = []
+        nodes_log = log_data.get("nodes", log_data) if isinstance(log_data, dict) else {}
+        for node_uuid, node_info in nodes_log.items() if isinstance(nodes_log, dict) else []:
+            if isinstance(node_info, dict) and node_info.get("error"):
+                node_errors.append({
+                    "node_uuid": node_uuid,
+                    "node_title": node_info.get("title", ""),
+                    "error_message": str(node_info.get("error", "")),
+                })
+        if not node_errors:
+            return [{"message": "因子分析执行失败（无详细错误信息）", "raw_log_data": log_data}]
+        return node_errors
+    except Exception as e:
+        return [{"message": f"获取错误详情失败: {e}"}]
+
+
+def get_factor(config: dict, token: str, uid: str, factor_id: str) -> Optional[dict]:
+    """获取单个因子完整定义"""
+    url = api_url(config, "/quantflow/api/workflow/query")
+    try:
+        resp = requests.get(url, params={"workflow_id": factor_id},
+                          headers=make_headers(token=token, uid=uid), timeout=10)
+        data = resp.json()
+        # 响应直接是 workflow JSON（含 nodes、litegraph 等）
+        if isinstance(data, dict) and data.get("nodes"):
+            return data
+    except Exception:
+        pass
+    return None
+
+
+def update_factor(config: dict, token: str, uid: str, factor_id: str, factor_json: dict) -> str:
+    """更新因子（upsert），返回 factor_id"""
+    # 设置为更新模式
+    factor_json["id"] = factor_id
+
+    # 移除 save 接口不接受的元数据字段（这些是 query 返回的只读字段）
+    for key in ("owner", "create_at", "update_at", "feature_tag", "last_run_id",
+                "publish_status", "subscription_id", "_id"):
+        factor_json.pop(key, None)
+
+    url = api_url(config, "/quantflow/api/workflow/save")
+    try:
+        resp = requests.post(url, json=factor_json, headers=make_headers(token=token, uid=uid), timeout=15)
+        data = resp.json()
+    except Exception as e:
+        return _fail("UPDATE_FAILED", f"更新因子分析请求失败: {e}")
+
+    if resp.status_code >= 400:
+        return _fail("UPDATE_FAILED", f"更新因子分析失败(HTTP{resp.status_code}): {resp.text[:300]}")
+    if data.get("code") != 0:
+        return _fail("UPDATE_FAILED", f"更新因子分析失败: {data.get('message', data.get('detail', resp.text[:200]))}")
+
+    wf_id = data.get("data", {}).get("workflow_id")
+    if not wf_id:
+        return _fail("UPDATE_FAILED", "响应中没有 workflow_id")
+    return wf_id
+
+
+def extract_factor_info(factor_json: dict) -> dict:
+    """从因子完整 JSON 中提取关键信息"""
+    info = {
+        "_id": factor_json.get("_id", ""),
+        "name": factor_json.get("name", ""),
+        "create_at": factor_json.get("create_at"),
+        "last_run_id": factor_json.get("last_run_id", ""),
+        "mode": None,          # "code" or "formula"
+        "content": "",         # 代码或公式文本
+        "start_date": "",
+        "end_date": "",
+        "market": "",
+        "adjustment_cycle": "",
+        "group_number": "",
+        "factor_direction": "",
+        "stock_pool": "",
+    }
+    for node in factor_json.get("nodes", []):
+        sid = node.get("static_input_data", {})
+        ntype = node.get("name", "")
+        if ntype == "CodeControl":
+            info["content"] = sid.get("code", "")
+        elif ntype == "FormulaControl":
+            info["content"] = sid.get("formulas", "")
+            info["mode"] = "formula"
+        elif ntype == "FactorBuildProControl":
+            info["start_date"] = sid.get("start_date", "")
+            info["end_date"] = sid.get("end_date", "")
+            info["market"] = sid.get("market", "")
+            ftype = sid.get("type", "")
+            info["mode"] = "code" if ftype == "Python" else "formula"
+        elif ntype == "FactorAnalysisControl":
+            info["adjustment_cycle"] = sid.get("adjustment_cycle", "")
+            info["group_number"] = sid.get("group_number", "")
+            info["factor_direction"] = sid.get("factor_direction", "")
+            info["stock_pool"] = sid.get("stock_pool", "")
+    return info
+
+
+def apply_factor_updates(factor_json: dict, updates: dict) -> dict:
+    """将更新应用到因子 JSON 的对应节点上"""
+    for node in factor_json.get("nodes", []):
+        sid = node.get("static_input_data", {})
+        ntype = node.get("name", "")
+
+        if ntype == "CodeControl":
+            if "content" in updates:
+                sid["code"] = updates["content"]
+
+        elif ntype == "FormulaControl":
+            if "content" in updates:
+                sid["formulas"] = updates["content"]
+
+        elif ntype == "FactorBuildProControl":
+            if "start_date" in updates:
+                sid["start_date"] = updates["start_date"]
+            if "end_date" in updates:
+                sid["end_date"] = updates["end_date"]
+            if "market" in updates:
+                sid["market"] = updates["market"]
+            if "mode" in updates:
+                sid["type"] = "Python" if updates["mode"] == "code" else "公式"
+
+        elif ntype == "FactorAnalysisControl":
+            if "adjustment_cycle" in updates:
+                sid["adjustment_cycle"] = updates["adjustment_cycle"]
+            if "factor_direction" in updates:
+                sid["factor_direction"] = updates["factor_direction"]
+            # group_number 和 stock_pool 强制不变
+            sid["group_number"] = "10"
+            sid["stock_pool"] = "沪深全A"
+
+    if "name" in updates:
+        factor_json["name"] = updates["name"]
+    return factor_json
+
+
+def get_factor_output(config: dict, token: str, uid: str, factor_id: str) -> Optional[dict]:
+    """获取因子分析最后一次运行的输出"""
+    url = api_url(config, "/quantflow/api/workflow/run/output/by-last-run")
+    try:
+        resp = requests.get(url, params={"workflow_id": factor_id, "feature_tag": "factor"},
+                          headers=make_headers(token=token, uid=uid), timeout=30)
+        data = resp.json()
+        if data.get("code") == 0:
+            return data.get("data", {})
+    except Exception:
+        pass
+    return None

pandaai/factor_list.py

@@ -0,0 +1,183 @@
+"""因子列表与删除"""
+
+from typing import Optional
+
+import requests
+
+from .auth import api_url, make_headers
+
+
+def list_factors(config: dict, token: str, uid: str, limit: int = 100, offset: int = 0) -> tuple:
+    """获取用户因子列表，返回 (factors, total_count)"""
+    url = api_url(config, "/quantflow/api/workflow/all")
+    try:
+        resp = requests.get(url, headers=make_headers(token=token, uid=uid),
+                          params={"limit": limit, "offset": offset, "source": "user"}, timeout=10)
+        data = resp.json()
+        if data.get("code") == 200:
+            wf_data = data.get("data", {})
+            return wf_data.get("workflows", []), wf_data.get("total_count", 0)
+    except Exception:
+        pass
+    return None, None
+
+
+def delete_factors(config: dict, token: str, uid: str, factor_ids: list) -> tuple:
+    """批量删除因子，返回 (deleted_count, error)"""
+    url = api_url(config, "/quantflow/api/workflow/delete")
+    batch_size = 50
+    deleted = 0
+    for i in range(0, len(factor_ids), batch_size):
+        batch = factor_ids[i:i + batch_size]
+        try:
+            resp = requests.post(url, json={"workflow_id_list": batch},
+                               headers=make_headers(token=token, uid=uid), timeout=30)
+            if resp.status_code == 200:
+                deleted += len(batch)
+            else:
+                return deleted, f"HTTP {resp.status_code}: {resp.text[:200]}"
+        except Exception as e:
+            return deleted, str(e)
+    return deleted, None
+
+
+def enrich_factors_with_runs(config: dict, token: str, uid: str, factors: list) -> list:
+    """为因子列表补充最后一次运行时间和 query_factor_analysis_data 摘要"""
+    from .output import get_factor_run_detail, extract_task_id
+
+    enriched = []
+    for factor in factors:
+        entry = dict(factor)
+        entry["_last_run_time"] = ""
+        entry["_analysis_summary"] = ""
+
+        run_id = factor.get("last_run_id")
+        if run_id:
+            detail = get_factor_run_detail(config, token, uid, run_id)
+            if detail:
+                # 提取最后一次运行时间
+                end_time = detail.get("end_time")
+                if end_time:
+                    entry["_last_run_time"] = end_time
+
+                # 提取 query_factor_analysis_data 摘要
+                task_id = extract_task_id(config, token, uid, run_id)
+                if task_id:
+                    fa_data = _fetch_analysis_summary(config, token, uid, task_id)
+                    entry["_analysis_summary"] = fa_data
+
+        enriched.append(entry)
+    return enriched
+
+
+def _fetch_analysis_summary(config: dict, token: str, uid: str, task_id: str) -> str:
+    """获取 14 个指标摘要，按界面 5 行布局：
+    第1行: 因子收益  夏普比率  年化收益
+    第2行: 最大回撤  IC_mean  Rank_IC
+    第3行: IC_std    IC_IR    IR
+    第4行: P(IC<-0.02)  P(IC>0.02)  t统计量
+    第5行: p-value   单调性
+    """
+    prefix = api_url(config, "/quantflow/api/factor/")
+    indicators = {}  # name → value
+
+    # 1. query_one_group_data → 因子收益、夏普比率、年化收益、最大回撤
+    try:
+        resp = requests.get(f"{prefix}query_one_group_data",
+                          params={"task_id": task_id},
+                          headers=make_headers(token=token, uid=uid), timeout=15)
+        data = resp.json()
+        if data.get("code") in ("200", 200):
+            g = data.get("data", {}).get("one_group_data", {})
+            if isinstance(g, dict):
+                indicators["因子收益"] = g.get("return_ratio", "")
+                indicators["夏普比率"] = g.get("sharpe_ratio", "")
+                indicators["年化收益"] = g.get("annualized_ratio", "")
+                indicators["最大回撤"] = g.get("maximum_drawdown", "")
+    except Exception:
+        pass
+
+    # 2. query_factor_analysis_data → IC 系列等 10 个指标
+    try:
+        resp = requests.get(f"{prefix}query_factor_analysis_data",
+                          params={"task_id": task_id},
+                          headers=make_headers(token=token, uid=uid), timeout=15)
+        data = resp.json()
+        if data.get("code") in ("200", 200):
+            ep_data = data.get("data", {})
+            items = ep_data.get("factor_data_analysis", [])
+            if not items:
+                for k, v in ep_data.items():
+                    if k != "task_id" and isinstance(v, list):
+                        items = v
+                        break
+            if items and isinstance(items, list):
+                for item in items:
+                    if isinstance(item, dict):
+                        name = item.get("indicator", "")
+                        val = item.get("factor1", item.get("value", ""))
+                        if name:
+                            indicators[name] = val
+    except Exception:
+        pass
+
+    # 按界面布局顺序输出（14 个指标一行）
+    order = [
+        "因子收益", "夏普比率", "年化收益",
+        "最大回撤", "IC_mean", "Rank_IC",
+        "IC_std", "IC_IR", "IR",
+        "P(IC<-0.02)", "P(IC>0.02)", "t统计量",
+        "p-value", "单调性",
+    ]
+    parts = []
+    for name in order:
+        val = indicators.get(name, "")
+        parts.append(f"{name} {val}" if val else name)
+    return "  ".join(parts)
+
+
+def format_factor_list(factors: list, total_count: int = None, limit: int = None, offset: int = None) -> str:
+    """格式化因子列表为可读文本"""
+    from datetime import datetime as dt
+
+    if total_count is None:
+        total_count = len(factors)
+
+    lines = []
+    if limit and total_count > limit:
+        lines.append(f"第 {offset + 1}-{offset + len(factors)} 条 / 共 {total_count} 个因子:\n")
+    else:
+        lines.append(f"共 {total_count} 个因子:\n")
+
+    lines.append(f"{'名称':<24} {'创建时间':<22} {'最后运行时间':<22} {'Run ID':<28} {'分析摘要'}")
+    lines.append("-" * 130)
+
+    for factor in factors:
+        name = (factor.get("name") or "")[:22]
+        factor_id = factor.get("_id", "")
+
+        created = ""
+        if factor.get("create_at"):
+            try:
+                created = dt.fromtimestamp(factor["create_at"] / 1000).strftime("%Y-%m-%d %H:%M:%S")
+            except Exception:
+                created = str(factor["create_at"])
+
+        last_run_time = factor.get("_last_run_time", "")
+        if last_run_time:
+            try:
+                for fmt in ["%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S.%f"]:
+                    try:
+                        last_run_time = dt.strptime(last_run_time[:26], fmt).strftime("%Y-%m-%d %H:%M:%S")
+                        break
+                    except (ValueError, IndexError):
+                        continue
+            except Exception:
+                pass
+
+        run_id = (factor.get("last_run_id") or "")
+        summary = (factor.get("_analysis_summary") or "")
+
+        lines.append(f"{name:<24} {created:<22} {last_run_time:<22} {run_id:<28} {summary}")
+
+    return "\n".join(lines)

pandaai/formatting.py

@@ -0,0 +1,79 @@
+"""结果格式化与计费计算"""
+
+from datetime import datetime
+from typing import Optional
+
+
+def _calc_duration(start_time: str, end_time: str) -> Optional[float]:
+    """计算运行时长（秒）"""
+    if not start_time or not end_time:
+        return None
+    try:
+        for fmt in ["%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S.%f"]:
+            try:
+                st = datetime.strptime(start_time[:26], fmt)
+                et = datetime.strptime(end_time[:26], fmt)
+                return (et - st).total_seconds()
+            except (ValueError, IndexError):
+                continue
+    except Exception:
+        pass
+    return None
+
+
+def format_success(factor_id, run_id, run_result, balance_start, balance_end, output):
+    """格式化成功结果"""
+    duration = _calc_duration(run_result.get("start_time"), run_result.get("end_time"))
+    deducted = None
+    power_start = balance_start.get("computingPower") if isinstance(balance_start, dict) else None
+    power_end = balance_end.get("computingPower") if isinstance(balance_end, dict) else None
+    if power_start is not None and power_end is not None:
+        deducted = float(power_start) - float(power_end)
+    balance_val = power_end
+
+    return {
+        "success": True, "status": "SUCCESS",
+        "factor_id": factor_id, "factor_run_id": run_id,
+        "duration_seconds": duration,
+        "start_time": run_result.get("start_time"),
+        "end_time": run_result.get("end_time"),
+        "output": output,
+        "billing": {
+            "balance": balance_val,
+            "deducted": deducted if deducted else 0,
+            "status": "ok",
+        },
+    }
+
+
+def format_failure(status, error_type, message, factor_id=None, run_id=None,
+                    run_result=None, balance_start=None, balance_end=None):
+    """格式化失败结果"""
+    run_result = run_result or {}
+    duration = _calc_duration(run_result.get("start_time"), run_result.get("end_time"))
+    deducted = None
+    power_start = balance_start.get("computingPower") if isinstance(balance_start, dict) else None
+    power_end = balance_end.get("computingPower") if isinstance(balance_end, dict) else None
+    if power_start is not None and power_end is not None:
+        deducted = float(power_start) - float(power_end)
+    balance_val = power_end
+
+    error_block = {"type": error_type, "message": message}
+    if run_result.get("errors"):
+        error_block["node_errors"] = run_result["errors"]
+    if run_result.get("failed_node_ids"):
+        error_block["failed_node_ids"] = run_result["failed_node_ids"]
+
+    return {
+        "success": False, "status": status,
+        "factor_id": factor_id, "factor_run_id": run_id,
+        "duration_seconds": duration,
+        "start_time": run_result.get("start_time"),
+        "end_time": run_result.get("end_time"),
+        "error": error_block,
+        "billing": {
+            "balance": balance_val if balance_end is not None else balance_start,
+            "deducted": deducted if deducted else 0,
+            "status": "insufficient" if error_type == "INSUFFICIENT_BALANCE" else "ok",
+        },
+    }