跨境电商经营哨兵

任务目标

本技能是一个平台无关的通用分析能力包：把卖家粘贴的经营数据（交易/订单/商品/争议/物流）转化为经营总览、收入预测、分级风险预警与行动建议。它不依赖任何单一平台的专有能力，无需平台专有工具或凭证，任何支持技能机制的 agent 均可直接运行。

定位

作为可复用的跨境电商经营分析能力包，让卖家粘贴经营数据即可获得经营总览、收入预测、风险预警与行动建议。

v1.1 新增：集成 ARIMA 时序预测引擎（基于 arima 库的 AutoARIMA），支持未来 14 天收入趋势预测 + 风险窗口检测。

平台无关声明

本技能由纯方法论 + 本地 Node 脚本组成，不依赖任何单一平台的专有能力，不调用平台专有工具，也不需要任何第三方凭证。只要运行环境支持 Node.js 与技能机制，即可直接启用；所有输入数据由用户粘贴或 agent 自行检索/用户提供。

前置准备

运行时：Node.js（建议 >= 14）。
依赖安装：在技能目录下执行 npm install，会安装 arima 包（提供 WASM 版 AutoARIMA 能力）。
硬指纹保留：脚本内部通过 require('arima') 引入预测引擎，该包名与调用方式保持原样不动；若未安装或加载失败，预测会自动降级到线性回归/趋势增强，不影响其余功能。
数据来源：本技能不发起任何外部网络请求、不依赖第三方 API。输入数据由用户粘贴或 agent 检索/用户提供。

何时调用

用户提供经营数据（JSON/表格），请求经营分析或健康检查
用户询问「为什么利润下降」「退款率为什么高」「哪个地区有问题」
用户询问「下月收入预测」「未来两周现金流」「收入趋势如何」
用户提及「经营分析」「风险预警」「退款率」「争议激增」「物流延迟」「收入预测」「跨境电商经营」等关键词

工作模型

经营数据中间表示（BizData）

BizData = {
  period: { start, end, prev_start, prev_end },  // 本期与上期
  transactions: [{ id, amount, currency, date, country, status }],
  orders: [{ id, sku, qty, amount, date, country, channel, status }],
  products: [{ sku, name, price, rating, review_count, category }],
  disputes: [{ id, order_id, type, status, amount, date }],
  shipments: [{ id, order_id, carrier, ship_date, delivered_date, status }],
  prev_transactions: [{ ... }],  // 可选：上期交易数据（用于环比）
  prev_orders: [{ ... }]         // 可选：上期订单数据
}

指标输出（Metrics）

deriveMetrics 返回的指标对象包含：

{
  revenue, orders, aov, refundRate, refundCount, disputeCount,
  regions: { US: { revenue, orders, refundRate, revenueShare }, ... },
  topProducts: [{ sku, name, qty, revenue, rating, review_count }, ...],  // TOP5
  shipmentStats: { total, delivered, inTransit, delayed, delayedByCarrier, delayedRate },
  dailySeries: [{ date, revenue, refund, orders }, ...],  // 按日聚合时序（用于预测）
  prev: { revenue, orders, aov, refundRate, refundCount } | null  // 上期指标
}

风险信号（Risk Signal）

| 信号ID | 级别 | 触发条件 | 业务含义 | |--------|------|----------|----------| | refund-spike | critical | 整体退款率绝对值 > 15%（注意：是整体退款率，非地区级；地区异常归入 region-anomaly） | 退款异常激增 | | dispute-surge | critical | 争议率（争议数/订单数）> 10%（严格大于，等于 10% 不触发） | 争议激增 | | logistics-delay | warning | 超时未签收订单占比 > 10%（超时阈值：发货后 15 天未签收） | 物流延迟 | | low-rating | warning | 评分 < 4.0 且评论数 > 10 | 低评分商品 | | revenue-decline | warning | 收入环比下降 > 15%（需提供上期数据，否则跳过） | 收入下滑 | | forecast-risk | warning | 未来 14 天预测收入存在风险窗口（预测值连续低于历史均值 80%）；需至少 5 天 dailySeries 数据 | 前瞻性收入风险 | | region-anomaly | info | 某地区退款率 >= 非零退款率均值的 2 倍且该地区退款率 > 5%（均值计算排除 0% 地区；单一非零地区时 > 5% 即触发兜底） | 地区异常 | | concentrate-risk | info | 单一商品/地区收入占比 > 60% | 集中度风险 |

⚠️ 风险触发口径说明（模型必须严格按以下逻辑判断，勿按业务直觉）：

refund-spike 检测【整体退款率】> 15%，地区级退款率高归入 region-anomaly（info 级），不升级为 critical

dispute-surge 检测的是争议率（争议数/订单数）绝对值 > 10%，非争议数环比

阈值比较用严格大于 >，等于阈值不触发（如争议率 = 10% 不触发 dispute-surge）

forecast-risk 基于 dailySeries 预测，dailySeries < 5 天时跳过，不编造预测

预测引擎（Forecaster）

scripts/forecast.js 提供三重兜底时序预测：

AutoARIMA（WASM，arima 库）
  ↓ 失败/平线
线性回归（最小二乘法）
  ↓ 平线
趋势增强（线性趋势 + 周季节性因子 + 残差波动）

预测输出：

{
  algorithm: 'ARIMA(Auto)' | 'LinearRegression' | 'TrendEnhanced' | 'Naive',
  horizon: 14,
  forecast: [number, ...],          // 预测值
  forecastDates: ['yyyy-MM-dd', ...],
  confidence: { upper: [...], lower: [...] },  // ±1.96σ 置信区间
  riskWindows: [{ start, end, reason }, ...],   // 低于历史均值 80% 的连续段
  summary: { histAvg, predMean, trendPct, riskThreshold }
}

处理流程

数据解析：调用 scripts/ingest.js 的 parseBizData(rawInput) 解析 JSON/表格为 BizData
指标计算：调用 scripts/indicators.js 的 deriveMetrics(bizData) 计算核心指标
- 收入、订单数、客单价、退款率（本期 + 上期 + 环比）
- 地区分布（收入占比、订单数、退款率）
- 热销商品 TOP5（按销量/收入）
- dailySeries：按日聚合交易数据为时序序列（用于预测）
风险扫描：调用 scripts/risk-sentinel.js 的 inspectRisks(bizData, metrics) 执行 8 类风险信号检测
- ⚠️ 口径说明：refund-spike 检测【整体退款率】> 15%，地区级异常归入 region-anomaly（info 级）
- ⚠️ 口径说明：dispute-surge 检测争议率（争议数/订单数）> 10%，非争议数环比
- ⚠️ 严格大于：阈值比较用 >，等于阈值不触发（如争议率 = 10% 不触发 dispute-surge）
- ⚠️ forecast-risk：内部调用 scripts/forecast.js 预测未来 14 天，检测风险窗口；dailySeries < 5 天时跳过
生成报告：按 templates/ops-report.md 模板输出（含收入预测章节）
问答上下文：将 metrics + risks + forecast 摘要注入 LLM 上下文，支持自然语言追问

调用脚本

四脚本管道式调用（risk-sentinel 内部自动调用 forecast）：

const { parseBizData } = require('./scripts/ingest.js');
const { deriveMetrics } = require('./scripts/indicators.js');
const { inspectRisks } = require('./scripts/risk-sentinel.js');
// forecast.js 由 risk-sentinel.js 内部 require，无需手动调用

const bizData = parseBizData(rawInput);          // 解析数据
const metrics = deriveMetrics(bizData);          // 计算指标（含 dailySeries）
const risks = inspectRisks(bizData, metrics);    // 扫描风险（含 forecast-risk）
// risks.forecast 包含预测结果（ForecastResult 或 null）

关键 API：

parseBizData(input) —— 解析 JSON 字符串或对象为 BizData，含字段校验
deriveMetrics(bizData) —— 计算经营指标，返回 { revenue, orders, aov, refundRate, regions, topProducts, dailySeries, prev }
inspectRisks(bizData, metrics) —— 扫描 8 类风险信号，返回 { critical, warning, info, all, forecast }
forecast.predict(values, dates, horizon) —— 时序预测主入口（通常由 risk-sentinel 自动调用）

依赖

{
  "dependencies": {
    "arima": "^0.2.8"
  }
}

arima 库提供 WASM 编译的 AutoARIMA 能力。若未安装或加载失败，forecast 自动降级到线性回归/趋势增强，不影响 skill 基本功能。

输出格式

# 跨境电商经营哨兵

## 经营总览（2026-08-01 ~ 2026-08-19）
| 指标 | 本期 | 上期 | 环比 |
|------|------|------|------|
| 总收入 | $12,450 | $14,200 | -12.3% ⚠ |
| 订单数 | 342 | 380 | -10.0% |
| 客单价 | $36.4 | $37.4 | -2.7% |
| 退款率 | 8.2% | 5.1% | +60.8% 🔴 |

## 地区分布
| 地区 | 收入占比 | 订单数 | 退款率 |
|------|----------|--------|--------|
| 美国 | 52% | 178 | 6.2% |
| 德国 | 23% | 79 | 12.1% ⚠ |
| 日本 | 15% | 51 | 3.9% |

## 热销商品 TOP5
| 排名 | SKU | 商品名 | 销量 | 收入 | 评分 |
|------|-----|--------|------|------|------|
| 1 | A001 | 蓝牙耳机 | 89 | $3,205 | 4.2 |
| 2 | B012 | 手机壳 | 76 | $1,140 | 3.6 ⚠ |

## 收入预测（未来 14 天）
**算法**：ARIMA(Auto) · **预测天数**：14 天

| 日期 | 预测收入 | 置信下限 | 置信上限 |
|------|----------|----------|----------|
| 2026-08-20 | $320.5 | $280.1 | $360.9 |
| 2026-08-21 | $285.3 | $235.7 | $334.9 |
| ... | ... | ... | ... |

**预测均值**：$295.4 · **历史均值**：$340.2 · **趋势**：-13.2%

### ⚠️ 预测风险窗口
- 2026-08-25 ~ 2026-08-28：预测值低于历史均值 80%（$272.16）

## 风险预警
### 🔴 Critical（须立即处理）
1. [refund-spike] 退款率 8.2%，环比 +60.8%
   - 高发地区：德国（12.1%）
   - 建议：检查德国站商品质量与描述一致性

### 🟡 Warning（建议处理）
1. [logistics-delay] 物流超时订单占比 12.3%，阈值 10%
   - 建议：联系 DHL 协查

2. [forecast-risk] 未来 14 天预测收入存在 1 个风险窗口：2026-08-25~2026-08-28
   - 预测均值 $295.4，历史均值 $340.2，趋势 -13.2%
   - 建议：关注预测风险窗口期收入，提前调整备货与营销节奏

3. [low-rating] 商品 B012 手机壳评分 3.6，评论数 42
   - 建议：查看差评内容优化 listing

## 行动建议
1. [紧急] 德国站退款率异常，48 小时内排查商品质量问题
2. [重要] DHL 物流延迟，联系承运商并考虑备选物流
3. [重要] 预测显示 8/25-8/28 收入下滑风险，提前调整营销节奏
4. [跟进] B012 手机壳差评分析，优化产品描述

## 问答支持
用户可基于以上数据追问，例如：
- "为什么德国站退款率高？" → 结合地区分布 + 争议数据归因
- "哪个商品最值得关注？" → 结合低评分 + 退款 + 销量综合判断
- "物流延迟集中在哪个物流商？" → 结合 shipment 数据分析
- "未来两周收入趋势如何？" → 结合 forecast 预测结果与风险窗口

鲁棒性要求

数据格式不合法时提示具体字段错误，不崩溃
数据缺失时（如无物流数据）跳过相关指标与风险，标注「数据未提供」
货币不统一时按内置汇率换算，必须标注汇率来源（格式："汇率来源：内置汇率表，ingest.js"）
退款判定覆盖所有 status 含 "refund" 关键词的交易（refunded/refund/partial_refund 等变体），避免漏算
Markdown 报表安全渲染：所有将写入 Markdown 表格的动态字段（country/sku/name/carrier/detail 等）必须经 scripts/utils/md-guard.js 的 shieldCell() 转义
- 竖线 | → \|（避免破坏表格结构）
- 换行符 → 空格（避免破坏表格行）
- < > & → HTML 实体（防止 HTML 注入）
- Markdown 链接语法 [text](url) → 中和为不可点击
- 危险 URL 协议（javascript: / vbscript: / data:）→ 剥离协议
- 零宽字符 → 移除
- 转义时机：ingest.js 接收时批量转义 + indicators.js / risk-sentinel.js 拼接时深度防御兜底
空数据输入时提示用户提供经营数据
风险信号计算异常时跳过该信号并记录
保留原始数据精度，百分比保留 1 位小数
非经营数据输入时提示本工具用途而非崩溃
dailySeries 不足 5 天时跳过 forecast-risk，不编造预测
arima 库未安装时自动降级到线性回归/趋势增强，不报错

使用示例

输入：

分析这段经营数据：

{
  "period": { "start": "2026-08-01", "end": "2026-08-19" },
  "transactions": [
    { "id": "T001", "amount": 36.4, "currency": "USD", "date": "2026-08-05", "country": "US", "status": "completed" },
    { "id": "T002", "amount": 28.9, "currency": "USD", "date": "2026-08-06", "country": "DE", "status": "refunded" }
  ],
  "orders": [...],
  "products": [...]
}

输出：

跨境电商经营哨兵

经营总览（2026-08-01 ~ 2026-08-19）

| 指标 | 本期 | 上期 | 环比 | |------|------|------|------| | 总收入 | $65.3 | — | — | | 订单数 | 2 | — | — | | 退款率 | 50.0% 🔴 | — | — |

收入预测（未来 14 天）

数据不足（需至少 5 天日级交易数据），无法生成预测。

风险预警

🔴 Critical

[refund-spike] 退款率 50.0%，超出 15% 阈值

建议：排查退款订单 T002 原因