aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/agents/warehouse/contracts.py

@@ -0,0 +1,26 @@
+"""Small, dependency-free input helpers for read-only warehouse agents."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def records(payload: Mapping[str, Any] | None, key: str) -> list[Mapping[str, Any]]:
+    """Return only mapping records from an optional ERP response payload."""
+    value = payload.get(key, []) if isinstance(payload, Mapping) else []
+    return [item for item in value if isinstance(item, Mapping)] if isinstance(value, list) else []
+
+
+def number(value: Any, default: float = 0.0) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def integer(value: Any, default: int = 0) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default

aria_code/agents/warehouse/dashboard.py

@@ -0,0 +1,155 @@
+"""海外仓 ERP 分析结果 → 本地 HTML 仪表盘。
+
+完全本地渲染（内嵌 CSS，不发任何网络请求），不依赖 Canva/Figma 之类的
+第三方设计工具——跟 report_generator.py 给财务报告用的是同一条"本地渲染
++ 本地引擎导出 PDF"路线，PDF 导出直接复用它的 html_string_to_pdf()，
+不重新写一套 Chrome/WebKit/weasyprint 兜底链。
+"""
+
+from __future__ import annotations
+
+import html as _html
+import webbrowser
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict
+
+from aria_code.agents.team import TeamResult
+
+_SIGNAL_COLOR = {
+    "GOOD":    "#2ea043",
+    "WATCH":   "#9a9a9a",
+    "CONCERN": "#d29922",
+    "SEVERE":  "#f85149",
+}
+
+_REPORTS_DIR = Path.home() / ".aria-code" / "reports" / "warehouse"
+
+
+def _e(text: Any) -> str:
+    return _html.escape(str(text if text is not None else ""))
+
+
+def _signal_badge(signal: str) -> str:
+    color = _SIGNAL_COLOR.get(signal, "#9a9a9a")
+    return f'<span class="badge" style="background:{color}22;color:{color};border:1px solid {color}55">{_e(signal)}</span>'
+
+
+def _agent_card(agent_name: str, result: Any) -> str:
+    key_points = "".join(f"<li>{_e(p)}</li>" for p in (getattr(result, "key_points", None) or []))
+    key_points_html = f'<ul class="points">{key_points}</ul>' if key_points else ""
+    return f"""
+    <div class="card">
+      <div class="card-head">
+        <span class="agent-name">{_e(agent_name)}</span>
+        {_signal_badge(getattr(result, "signal", "WATCH"))}
+        <span class="confidence">置信度 {getattr(result, "confidence", 0):.0%}</span>
+      </div>
+      <p class="analysis">{_e(getattr(result, "analysis", ""))}</p>
+      {key_points_html}
+    </div>"""
+
+
+def _snapshot_summary(snapshot: Dict[str, Any]) -> str:
+    counts = {
+        "SKU":   len(snapshot.get("skus", []) or []),
+        "库位":  len(snapshot.get("locations", []) or []),
+        "货代":  len(snapshot.get("connectors", []) or []),
+        "入库单": len(snapshot.get("inbounds", []) or []),
+    }
+    tiles = "".join(
+        f'<div class="tile"><div class="tile-value">{v}</div><div class="tile-label">{_e(k)}</div></div>'
+        for k, v in counts.items()
+    )
+    return f'<div class="tiles">{tiles}</div>'
+
+
+def render_html(warehouse_id: str, snapshot: Dict[str, Any], team_result: TeamResult) -> str:
+    generated_at = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    cards = "".join(
+        _agent_card(r.agent, r) for r in team_result.results
+    )
+    synthesis_html = (
+        f'<div class="synthesis"><h2>综合结论</h2><p>{_e(team_result.synthesis)}</p></div>'
+        if team_result.synthesis else ""
+    )
+    return f"""<!doctype html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<title>海外仓 ERP 分析 · {_e(warehouse_id)}</title>
+<style>
+  :root {{ color-scheme: dark; }}
+  * {{ box-sizing: border-box; }}
+  body {{
+    margin: 0; padding: 32px; background: #0d1117; color: #e6edf3;
+    font-family: -apple-system, "PingFang SC", "Segoe UI", sans-serif;
+  }}
+  .header {{ display:flex; justify-content:space-between; align-items:baseline; margin-bottom: 24px; }}
+  h1 {{ font-size: 22px; margin: 0; }}
+  .meta {{ color: #8b949e; font-size: 13px; }}
+  .final-signal {{ display:flex; align-items:center; gap: 12px; margin-bottom: 20px; }}
+  .badge {{ padding: 3px 10px; border-radius: 6px; font-size: 12px; font-weight: 600; }}
+  .tiles {{ display:flex; gap: 12px; margin-bottom: 28px; }}
+  .tile {{ background:#161b22; border:1px solid #30363d; border-radius:8px; padding:14px 20px; text-align:center; min-width:90px; }}
+  .tile-value {{ font-size: 22px; font-weight: 700; }}
+  .tile-label {{ font-size: 12px; color:#8b949e; margin-top:4px; }}
+  .synthesis {{ background:#161b22; border:1px solid #30363d; border-radius:10px; padding:18px 20px; margin-bottom:24px; }}
+  .synthesis h2 {{ font-size: 15px; margin: 0 0 8px; color:#8b949e; }}
+  .grid {{ display:grid; grid-template-columns: repeat(auto-fill, minmax(340px, 1fr)); gap: 16px; }}
+  .card {{ background:#161b22; border:1px solid #30363d; border-radius:10px; padding:16px 18px; }}
+  .card-head {{ display:flex; align-items:center; gap:10px; margin-bottom:10px; flex-wrap: wrap; }}
+  .agent-name {{ font-weight:600; font-size: 14px; }}
+  .confidence {{ margin-left:auto; font-size:12px; color:#8b949e; }}
+  .analysis {{ font-size: 13px; line-height:1.6; color:#c9d1d9; margin: 0 0 8px; }}
+  .points {{ margin:0; padding-left:18px; font-size:12px; color:#8b949e; }}
+  .points li {{ margin-bottom: 3px; }}
+  footer {{ margin-top: 32px; color:#484f58; font-size:11px; }}
+</style>
+</head>
+<body>
+  <div class="header">
+    <h1>海外仓 ERP 分析 · {_e(warehouse_id)}</h1>
+    <div class="meta">生成时间 {_e(generated_at)} · 本地渲染，无外部依赖</div>
+  </div>
+  <div class="final-signal">
+    综合信号 {_signal_badge(team_result.final_signal)}
+    <span class="confidence">团队置信度 {team_result.confidence:.0%} · 耗时 {team_result.elapsed_sec:.1f}s</span>
+  </div>
+  {_snapshot_summary(snapshot)}
+  {synthesis_html}
+  <div class="grid">
+    {cards}
+  </div>
+  <footer>aria-code · agents/warehouse · 数据来源: 本地文件（非真实 ERP 接口）</footer>
+</body>
+</html>"""
+
+
+def save_report(
+    warehouse_id: str,
+    snapshot: Dict[str, Any],
+    team_result: TeamResult,
+    *,
+    open_browser: bool = False,
+    also_pdf: bool = False,
+) -> Path:
+    """渲染 + 落盘到 ~/.aria-code/reports/warehouse/，按需打开浏览器 / 导出 PDF。"""
+    _REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    safe_id = "".join(c if c.isalnum() or c in "-_" else "_" for c in str(warehouse_id or "local"))
+    html_path = _REPORTS_DIR / f"warehouse_{safe_id}_{stamp}.html"
+    html_path.write_text(render_html(warehouse_id, snapshot, team_result), encoding="utf-8")
+
+    if also_pdf:
+        try:
+            from report_generator import html_string_to_pdf
+            pdf_path = html_path.with_suffix(".pdf")
+            html_string_to_pdf(html_path.read_text(encoding="utf-8"), pdf_path)
+        except Exception as exc:  # PDF 导出失败不该挡住 HTML 报告本身
+            print(f"  ⚠ PDF 导出失败（HTML 报告仍然生成好了）: {exc}")
+
+    if open_browser:
+        webbrowser.open(f"file://{html_path.resolve()}")
+
+    return html_path

aria_code/agents/warehouse/fulfillment_leadtime.py

@@ -0,0 +1,95 @@
+"""
+agents/warehouse/fulfillment_leadtime.py — Fulfillment Lead-Time & SLA Agent
+===========================================================================
+Monitors fulfillment velocity, SLA compliance rates, and identifies choke points
+across Order-to-Pack, Inbound Dock-to-Stock, Trunkline Transit, and Last-Mile Delivery.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
+from ..base import BaseAgent, AgentResult
+
+logger = logging.getLogger(__name__)
+
+
+class FulfillmentLeadTimeAgent(BaseAgent):
+    name = "warehouse_fulfillment_leadtime"
+    description = "供应链履约时效智能体 — 负责全链路时效分析、OTD 准时交付率与环节瓶颈定位"
+
+    def __init__(
+        self,
+        llm_provider=None,
+        data_router=None,
+        on_token: Optional[Callable[[str], None]] = None,
+        on_thought: Optional[Callable[[str], None]] = None,
+        on_tool_start: Optional[Callable[[str, Dict], None]] = None,
+        on_tool_end: Optional[Callable[[str, Any], None]] = None,
+        lang: str = "zh",
+    ) -> None:
+        super().__init__(
+            llm_provider=llm_provider,
+            data_router=data_router,
+            on_token=on_token,
+            on_thought=on_thought,
+            on_tool_start=on_tool_start,
+            on_tool_end=on_tool_end,
+            lang=lang,
+        )
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        """
+        Analyze fulfillment lead times and SLA compliance.
+        """
+        stages = data.get("fulfillment_stages", [])
+        if not stages:
+            # Default standard stages
+            stages = [
+                {"stage_name": "Order-to-Pack (订单至出库)", "avg_hours": 3.8, "sla_target_hours": 4.0, "compliance_rate": 94.2, "bottleneck": False},
+                {"stage_name": "Dock-to-Stock (入库上架)", "avg_hours": 6.8, "sla_target_hours": 6.0, "compliance_rate": 86.5, "bottleneck": True, "details": "高峰期分拣通道排队积压"},
+                {"stage_name": "Transit Line-Haul (干线运输)", "avg_hours": 36.5, "sla_target_hours": 48.0, "compliance_rate": 97.0, "bottleneck": False},
+                {"stage_name": "Last-Mile Delivery (末端派送)", "avg_hours": 14.8, "sla_target_hours": 12.0, "compliance_rate": 84.0, "bottleneck": True, "details": "郊区网点末端派送时效延迟"},
+            ]
+
+        bottlenecks = [s for s in stages if s.get("bottleneck", False) or s.get("bottleneck_detected", False)]
+        overall_compliance = sum(float(s.get("compliance_rate", 90.0)) for s in stages) / max(1, len(stages))
+
+        stage_rows = []
+        for s in stages:
+            name = s.get("stage_name", "")
+            avg_h = s.get("avg_hours", 0.0)
+            sla_h = s.get("sla_target_hours", 0.0)
+            comp = s.get("compliance_rate", 0.0)
+            status = "⚠️ 瓶颈" if (s.get("bottleneck") or s.get("bottleneck_detected")) else "✓ 正常"
+            stage_rows.append(f"| {name} | {avg_h:.1f}h | {sla_h:.1f}h | {comp:.1f}% | {status} |")
+
+        table_str = "\n".join(stage_rows)
+
+        analysis_text = (
+            f"### ⏱️ 供应链全链路履约时效诊断\n\n"
+            f"• **综合 SLA 达标率**: `{overall_compliance:.1f}%`\n"
+            f"• **识别时效瓶颈环节**: `{len(bottlenecks)}` 个\n\n"
+            f"| 履约阶段 | 实际耗时 | SLA 目标 | 达标率 | 状态 |\n"
+            f"| :--- | :--- | :--- | :--- | :--- |\n"
+            f"{table_str}\n\n"
+            f"**🛠️ 瓶颈改善措施**:\n"
+            + ("\n".join(f"- **{b.get('stage_name')}**: {b.get('details', '实际耗时超出 SLA 目标，需优化资源调配')}" for b in bottlenecks) if bottlenecks else "- 全链路各环节均在 SLA 考核范围内。")
+        )
+
+        signal = "CONCERN" if bottlenecks else "GOOD"
+
+        return AgentResult(
+            agent=self.name,
+            symbol=symbol,
+            analysis=analysis_text,
+            confidence=0.90,
+            signal=signal,
+            key_points=[
+                f"Overall SLA Compliance: {overall_compliance:.1f}%",
+                f"Active Bottlenecks: {len(bottlenecks)}",
+            ],
+            data_used={"stages": stages, "bottlenecks": bottlenecks},
+            provenance=["fulfillment-leadtime-engine", "warehouse-operations-sla"],
+        )

aria_code/agents/warehouse/inbound_exceptions.py

@@ -0,0 +1,25 @@
+"""电脑端入库异常分级 Agent。只提供建议，不修改入库或库存。"""
+from __future__ import annotations
+from typing import Any, Dict
+from ..base import BaseAgent, AgentResult
+from .contracts import integer, records
+
+class InboundExceptionAgent(BaseAgent):
+    name = "warehouse_inbound_exceptions"
+    description = "入库异常分级：识别超时、数量差异、破损和未上架货件"
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        orders = records(data, "inbounds")
+        critical = []
+        for order in orders:
+            gaps = abs(integer(order.get("expected_qty")) - integer(order.get("received_qty")))
+            damaged = integer(order.get("damaged_qty"))
+            if gaps or damaged or order.get("overdue", False):
+                reasons = []
+                if gaps: reasons.append(f"数量差异 {gaps}")
+                if damaged: reasons.append(f"破损 {damaged}")
+                if order.get("overdue", False): reasons.append("已超时")
+                critical.append(f"{order.get('id', '未知入库单')}：{', '.join(reasons)}")
+        signal = "SEVERE" if critical else "GOOD"
+        analysis = "需优先人工复核：" + "；".join(critical) if critical else "当前没有需要人工复核的入库异常。"
+        return AgentResult(agent=self.name, symbol=symbol, analysis=analysis, confidence=.92, signal=signal, key_points=critical or ["无入库异常"], data_used={"inbound_count": len(orders), "exception_count": len(critical)}, provenance=["warehouse-api", "deterministic-rules"])

aria_code/agents/warehouse/inventory_health.py

@@ -0,0 +1,24 @@
+"""库存健康度 Agent：低库存、库容与待上架积压。"""
+from __future__ import annotations
+from typing import Any, Dict
+from ..base import BaseAgent, AgentResult
+from .contracts import number, records
+
+class InventoryHealthAgent(BaseAgent):
+    name = "warehouse_inventory_health"
+    description = "库存健康度：识别低库存 SKU、库位容量风险与上架积压"
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        skus, locations = records(data, "skus"), records(data, "locations")
+        alerts = [
+            f"{sku.get('sku', '未知 SKU')} 可用库存 {sku.get('available', 0)}，低于安全库存 {sku.get('safety_stock', 0)}"
+            for sku in skus
+            if number(sku.get("available")) < number(sku.get("safety_stock"))
+        ]
+        alerts += [
+            f"库位 {loc.get('code', '未知')} 使用率 {number(loc.get('utilization')):.0%}"
+            for loc in locations
+            if number(loc.get("utilization")) >= 0.9
+        ]
+        signal = "CONCERN" if alerts else "GOOD"
+        return AgentResult(agent=self.name, symbol=symbol, analysis="；".join(alerts) if alerts else "库存与库位容量均处于健康阈值内。", confidence=.88, signal=signal, key_points=alerts or ["库存健康"], data_used={"sku_count": len(skus), "location_count": len(locations)}, provenance=["warehouse-api", "deterministic-rules"])

aria_code/agents/warehouse/local_run.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""本地跑通海外仓 ERP 分析：用户给一份本地数据文件，直接产出网页仪表盘。
+
+不需要真实 ERP 系统（那是 workflow.py 的 run_warehouse_analysis() 走的
+远程 ARIA_WAREHOUSE_ERP_URL 路径），也不需要任何第三方设计工具——数据
+加载、多 agent 分析、HTML/PDF 渲染全部在本地完成。
+
+用法::
+
+    python3 -m agents.warehouse.local_run --data snapshot.json
+    python3 -m agents.warehouse.local_run --data ./my_warehouse_csvs/ --open
+    python3 -m agents.warehouse.local_run --data snapshot.json --pdf --warehouse-id WH-042
+
+数据文件格式见 local_snapshot.py 顶部的字段约定。
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from aria_code.agents.team import AgentTeam
+from aria_code.agents.warehouse import WAREHOUSE_SCHEME, WAREHOUSE_TEAM
+from aria_code.agents.warehouse.dashboard import save_report
+from aria_code.agents.warehouse.local_snapshot import load_snapshot_from_path
+
+
+async def run(data_path: str, warehouse_id: str, *, open_browser: bool, also_pdf: bool) -> None:
+    print(f"  [1/3] 加载本地数据: {data_path}")
+    snapshot = load_snapshot_from_path(data_path, warehouse_id=warehouse_id)
+    wid = snapshot["warehouse_id"]
+    counts = {k: len(snapshot.get(k, []) or []) for k in ("connectors", "inbounds", "skus", "locations")}
+    print(f"        仓库: {wid} | " + " ".join(f"{k}={v}" for k, v in counts.items()))
+
+    print(f"  [2/3] 运行 warehouse agent team: {', '.join(WAREHOUSE_TEAM)}")
+    team = AgentTeam(signal_scheme=WAREHOUSE_SCHEME, timeout_per_agent=20)
+    result = await team.run(
+        wid,
+        agents=list(WAREHOUSE_TEAM),
+        agent_data={agent_name: snapshot for agent_name in WAREHOUSE_TEAM},
+    )
+    for r in result.results:
+        status = "✓" if r.success else f"✗ {r.error}"
+        print(f"        {status} {r.agent}: {r.signal}")
+
+    print("  [3/3] 生成本地仪表盘")
+    html_path = save_report(wid, snapshot, result, open_browser=open_browser, also_pdf=also_pdf)
+    print(f"\n  ✓ 报告已生成: {html_path}")
+    if also_pdf:
+        pdf_path = html_path.with_suffix(".pdf")
+        print(f"  ✓ PDF: {pdf_path}" if pdf_path.exists() else "  ⚠ PDF 未生成（本机没有可用的渲染引擎）")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="本地跑通海外仓 ERP agent 分析 + 生成网页仪表盘")
+    ap.add_argument("--data", required=True, help="本地数据文件(.json/.csv)或目录路径")
+    ap.add_argument("--warehouse-id", default="", help="仓库标识，缺省用文件名/目录名")
+    ap.add_argument("--open", action="store_true", help="生成后用默认浏览器打开")
+    ap.add_argument("--pdf", action="store_true", help="额外导出 PDF")
+    args = ap.parse_args()
+
+    try:
+        asyncio.run(run(args.data, args.warehouse_id, open_browser=args.open, also_pdf=args.pdf))
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"  ✗ {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

aria_code/agents/warehouse/local_snapshot.py

@@ -0,0 +1,132 @@
+"""本地快照加载 —— 没有真实 ERP 系统时的数据入口。
+
+WarehouseERPClient 只会走 ARIA_WAREHOUSE_ERP_URL 配的远程 HTTP(S) 接口，
+在还没接真实 ERP/WMS 的情况下完全用不了。这个文件是平行的本地路径：用户
+自己手上有什么数据（JSON 导出、Excel/CSV 表格），存成文件丢给
+local_run.py，走的是跟远程 ERP 一模一样的 snapshot 形状——四个记录列表
+(connectors / inbounds / skus / locations)，所以 agents/warehouse/ 下面
+那三个 agent 完全不用关心数据到底是不是来自真实 ERP。
+
+字段约定（跟三个 agent 的 records()/number()/integer() 读取对齐，非必填
+字段缺省按 0/False 处理，不会报错，只是分析不出对应的异常）：
+
+  connectors:  name, delay_minutes, failed_jobs
+  inbounds:    id, expected_qty, received_qty, damaged_qty, overdue(bool)
+  skus:        sku, available, safety_stock
+  locations:   code, utilization (0~1 的小数，如 0.92 = 92%)
+
+支持两种输入：
+  1. 单个 .json 文件 —— {"warehouse_id": "...", "connectors": [...], ...}
+     （跟远程 ERP 快照同一形状，也可以包一层 "data"）
+  2. 一个目录 —— 放 connectors.csv / inbounds.csv / skus.csv / locations.csv
+     其中任意几个文件（不需要四个都有），每个文件是该记录类型自己的表格，
+     给不会写 JSON、只会用 Excel/Numbers 导出 CSV 的人用
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+_RECORD_LISTS = ("connectors", "inbounds", "skus", "locations")
+
+_BOOL_TRUE = {"1", "true", "yes", "y", "是", "true"}
+
+
+def _coerce_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in _BOOL_TRUE
+
+
+def _normalise_records(raw: Any) -> List[Dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    return [dict(item) for item in raw if isinstance(item, dict)]
+
+
+def _load_json(path: Path, warehouse_id: str) -> Dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    root = payload.get("data", payload) if isinstance(payload, dict) else {}
+    if not isinstance(root, dict):
+        raise ValueError(f"{path} 顶层必须是 JSON 对象（可选包一层 \"data\"）")
+    snapshot: Dict[str, Any] = {"warehouse_id": str(root.get("warehouse_id") or warehouse_id or path.stem)}
+    for key in _RECORD_LISTS:
+        snapshot[key] = _normalise_records(root.get(key, []))
+    return snapshot
+
+
+def _read_csv_rows(path: Path) -> List[Dict[str, Any]]:
+    with path.open("r", encoding="utf-8-sig", newline="") as f:
+        reader = csv.DictReader(f)
+        rows = [dict(row) for row in reader]
+    # overdue 列在 CSV 里天然是字符串，其余字段留给 contracts.number()/integer() 处理，
+    # 只有这一个布尔字段需要在这里就转好，不然 "false" 这种字符串会被 Python 判成真值。
+    for row in rows:
+        if "overdue" in row:
+            row["overdue"] = _coerce_bool(row["overdue"])
+    return rows
+
+
+def _load_csv_dir(path: Path, warehouse_id: str) -> Dict[str, Any]:
+    snapshot: Dict[str, Any] = {"warehouse_id": warehouse_id or path.name}
+    found_any = False
+    for key in _RECORD_LISTS:
+        csv_path = path / f"{key}.csv"
+        if csv_path.exists():
+            snapshot[key] = _read_csv_rows(csv_path)
+            found_any = True
+        else:
+            snapshot[key] = []
+    if not found_any:
+        raise ValueError(
+            f"{path} 里没找到任何 connectors.csv / inbounds.csv / skus.csv / "
+            f"locations.csv —— 至少要有一个"
+        )
+    return snapshot
+
+
+def _load_single_csv(path: Path, warehouse_id: str) -> Dict[str, Any]:
+    """单文件 CSV：靠一列 record_type（值须是 connectors/inbounds/skus/locations 之一）
+    把每一行分发到对应的记录列表，给"就想丢一张表格"的人用。"""
+    rows = _read_csv_rows(path)
+    snapshot: Dict[str, Any] = {"warehouse_id": warehouse_id or path.stem, **{k: [] for k in _RECORD_LISTS}}
+    unknown_types = set()
+    for row in rows:
+        rtype = str(row.pop("record_type", "")).strip().lower()
+        if rtype in snapshot:
+            snapshot[rtype].append(row)
+        else:
+            unknown_types.add(rtype or "(空)")
+    if unknown_types:
+        raise ValueError(
+            f"{path} 里有行的 record_type 不认识: {sorted(unknown_types)}，"
+            f"必须是 connectors/inbounds/skus/locations 之一"
+        )
+    return snapshot
+
+
+def load_snapshot_from_path(path: str, warehouse_id: str = "") -> Dict[str, Any]:
+    """加载本地快照，返回跟 WarehouseERPClient.fetch_snapshot() 同形状的 dict。"""
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise FileNotFoundError(f"找不到数据文件/目录: {p}")
+
+    if p.is_dir():
+        return _load_csv_dir(p, warehouse_id)
+    if p.suffix.lower() == ".json":
+        return _load_json(p, warehouse_id)
+    if p.suffix.lower() == ".csv":
+        # 有 record_type 列走单文件多类型模式，否则报错提示用哪种格式
+        with p.open("r", encoding="utf-8-sig") as f:
+            header = f.readline()
+        if "record_type" in header:
+            return _load_single_csv(p, warehouse_id)
+        raise ValueError(
+            f"{p} 是单个 CSV 但没有 record_type 列——要么在表格里加一列 record_type"
+            f"（值为 connectors/inbounds/skus/locations），要么把它放进一个目录，"
+            f"文件名改成 connectors.csv / inbounds.csv / skus.csv / locations.csv"
+        )
+    raise ValueError(f"不支持的文件类型: {p.suffix}（支持 .json、.csv，或含多个 .csv 的目录）")

aria_code/agents/warehouse/logistics_cost.py

@@ -0,0 +1,84 @@
+"""Logistics cost audit backed by waybill records and traceable calculations."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from ..base import BaseAgent, AgentResult
+from ...tools.logistics_tools import tool_analyze_logistics_data
+
+
+class LogisticsCostOptimizerAgent(BaseAgent):
+    name = "warehouse_logistics_cost"
+    description = "物流运费优化智能体 — 基于运单核算费用、准时率和计费重量异常"
+
+    def __init__(
+        self,
+        llm_provider=None,
+        data_router=None,
+        on_token: Optional[Callable[[str], None]] = None,
+        on_thought: Optional[Callable[[str], None]] = None,
+        on_tool_start: Optional[Callable[[str, Dict], None]] = None,
+        on_tool_end: Optional[Callable[[str, Any], None]] = None,
+        lang: str = "zh",
+    ) -> None:
+        super().__init__(
+            llm_provider=llm_provider,
+            data_router=data_router,
+            on_token=on_token,
+            on_thought=on_thought,
+            on_tool_start=on_tool_start,
+            on_tool_end=on_tool_end,
+            lang=lang,
+        )
+
+    async def _execute_tool(self, tool_name: str, tool_args: Dict[str, Any]) -> str:
+        if tool_name != "analyze_logistics_data":
+            return await super()._execute_tool(tool_name, tool_args)
+        if self.on_tool_start:
+            self.on_tool_start(tool_name, tool_args)
+        result = str(tool_analyze_logistics_data(tool_args))
+        if self.on_tool_end:
+            self.on_tool_end(tool_name, result)
+        return result
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        params: Dict[str, Any] = {key: data[key] for key in ("waybills", "file_path") if key in data}
+        audit = tool_analyze_logistics_data(params)
+        if not audit["success"]:
+            error = audit["error"]
+            return AgentResult(
+                agent=self.name,
+                symbol=symbol,
+                analysis=f"无法完成物流成本审计：{error}",
+                confidence=0.0,
+                signal="HOLD",
+                error=error,
+                limitations=["未取得可审计的运单记录"],
+            )
+        result = audit["data"]
+        rate = result["overall_on_time_rate"]
+        rate_text = f"{rate}%" if rate is not None else "未知（没有准时状态记录）"
+        carrier_lines = [
+            f"- {item['carrier']}：{item['count']} 单，费用 ¥{item['total_spend']:,.2f}，准时率 "
+            + (f"{item['on_time_rate']}%" if item["on_time_rate"] is not None else "未知")
+            for item in result["carrier_metrics"]
+        ]
+        analysis = (
+            f"## 物流费用审计\n来源：{audit['source']}；共 {result['total_waybills']} 单。\n"
+            f"运费总支出：¥{result['total_freight_spend']:,.2f}；已知准时率：{rate_text}。\n\n"
+            "### 承运商表现\n" + "\n".join(carrier_lines) + "\n\n"
+            f"### 异常计费发现\n{len(result['billing_anomalies'])} 单计费重量高于实重 20% 以上，"
+            "需核对体积重及合同条款后才能确认多收费用。"
+        )
+        return AgentResult(
+            agent=self.name,
+            symbol=symbol,
+            analysis=analysis,
+            confidence=1.0,
+            signal="CONCERN" if result["billing_anomalies"] else "HOLD",
+            key_points=[f"运费总支出 ¥{result['total_freight_spend']:,.2f}", f"待核实重量异常 {len(result['billing_anomalies'])} 单"],
+            data_used=result,
+            provenance=[audit["source"]],
+            limitations=["重量差异仅是审计线索；无法据此推断可节省金额"],
+        )

aria_code/agents/warehouse/logistics_sync.py

@@ -0,0 +1,21 @@
+"""货代同步巡检 Agent。输入由 ERP API 注入，不直接持有货代密钥。"""
+from __future__ import annotations
+from typing import Any, Dict
+from ..base import BaseAgent, AgentResult
+from .contracts import integer, number, records
+
+class LogisticsSyncAgent(BaseAgent):
+    name = "warehouse_logistics_sync"
+    description = "货代同步巡检：识别 API 延迟、失败及缺失运输单"
+
+    async def analyze(self, symbol: str, data: Dict[str, Any]) -> AgentResult:
+        connectors = records(data, "connectors")
+        issues = []
+        for item in connectors:
+            delay = number(item.get("delay_minutes"))
+            failures = integer(item.get("failed_jobs"))
+            if failures: issues.append(f"{item.get('name', '未知货代')} 有 {failures} 个失败同步任务")
+            if delay >= 30: issues.append(f"{item.get('name', '未知货代')} 同步延迟 {delay:g} 分钟")
+        signal = "SEVERE" if any("失败" in item for item in issues) else "WATCH" if issues else "GOOD"
+        analysis = "；".join(issues) if issues else "所有已接入货代的同步任务均在健康阈值内。"
+        return AgentResult(agent=self.name, symbol=symbol, analysis=analysis, confidence=.9, signal=signal, key_points=issues or ["同步正常"], data_used={"connector_count": len(connectors)}, provenance=["warehouse-api"])