Skill: leehoo29/ak-data-daily-timeout-report (version 1.0.0)

--- name: ak-data-daily-timeout-report description: "Unified daily timeout entry for AK Data single job type: task timeout + crawler timeout + comparison + drill-down examples with log request." --- # Skill: ak-data-daily-timeout-report > 可迁移入口脚本：`./run.sh` > > - 单天查询：`./run.sh day ...` > - 趋势查询：`./run.sh trend ...` > - 迁移说明：`./MIGRATION.md` > - 模板说明：`./TEMPLATE.md` > - 短命令包装：项目根目录 `bin/timeout` > - 打包脚本：`scripts/data/package_ak-data_daily_timeout_skill.py` 统一入口：用于查询 **AK Data 单任务类型** 在某一天的： 1. **主任务超时**（task timeout） 2. **爬虫超时**（crawler timeout） 3. **两种口径对比结论** 4. **支持继续追问具体任务例子**（自动补齐 log `ext_ssn + log_state + request`） > 这是入口 Skill，不直接替代底层统计逻辑。 > > - 主任务超时底层能力：[REDACTED_SECRET] > - 爬虫超时底层能力：[REDACTED_SECRET] > > 本 Skill 负责：**统一调度、统一输出、统一追问接口**。 --- ## 快速使用 ### 1) 单天联合超时 ```bash ./run.sh day --date-bjt 2026-04-05 --job-type AmazonListingJob ``` ### 2) 单天 + 样例追问 ```bash ./run.sh day \ --date-bjt 2026-04-05 \ --job-type AmazonListingJob \ --example-scope crawler_timeout \ --example-type overtime_total \ --example-market au \ --example-limit 5 ``` ### 3) 区间趋势 ```bash ./run.sh trend \ --start-date-bjt 2026-04-01 \ --end-date-bjt 2026-04-05 \ --job-type AmazonListingJob ``` ## 适用场景 当 LeeHoo 的问题是以下类型时，优先使用本 Skill： - “查 4.5 超时情况” - “查 4.5 主任务超时和爬虫超时对比” - “查某天 AmazonListingJob 的超时情况” - “给我几个超时例子，带 request” - “继续看 4.5 的 nl / jp / au 样例” - “导出未Deliver / 未Arrival / WAITING 样例” --- ## 口径边界（强制） ### 1) 主任务超时（task timeout） - 时间窗口：`created_at` 落在 `dateBjt` 对应自然日 - **正式超时判定基线：`break_at`** - 不得把主任务超时偷换成 `depart_at` 口径 - 不得把主任务超时简化成固定 `created_at + 12h` 口径后对外宣称“正式口径” ### 2) 爬虫超时（crawler timeout） - 时间窗口：`depart_at` 落在 `dateBjt` 对应自然日 - 超时判定： - 已到达：`arrival_at - depart_at > timeoutHours` - 未到达：`now_utc - depart_at > timeoutHours` - 若查询日是当天，可启用 `cutoffHours` 做成熟母本截断 ### 3) 追问具体任务例子 例子查询必须能区分： - `scopeType = task_timeout` - `scopeType = crawler_timeout` 不得混口径返回。 --- ## 输入契约 ```json { "tenantId": "AK Data", "jobType": "AmazonListingJob", "dateBjt": "2026-04-05", "includeTaskTimeout": true, "includeCrawlerTimeout": true, "samplePerState": 3, "needMarketSplit": true, "needLogEnrich": true, "cutoffHours": 0, "exampleQuery": { "scopeType": "crawler_timeout", "sampleType": "overtime_total", "market": "au", "status": "PENDING", "limit": 5, "includeRequest": true } } ``` ### 字段说明 - `includeTaskTimeout`：是否生成主任务超时部分 - `includeCrawlerTimeout`：是否生成爬虫超时部分 - `samplePerState`：底层脚本每类抽样条数 - `needLogEnrich`：是否自动补齐 log 字段 - `cutoffHours`：仅爬虫口径支持；用于当日成熟母本截断 - `exampleQuery`：可选，用于继续追问例子 --- ## 标准执行流程（强制） ### A. 每日总览查询 1. 如果 `includeTaskTimeout=true` - 调用 `run_created_timeout_report.py` - 读取输出 JSON 2. 如果 `includeCrawlerTimeout=true` - 调用 `run_depart_timeout_report.py` - 读取输出 JSON 3. 生成 unified report： - 总览 - market 对比 - 主任务 vs 爬虫差值 - 诊断结论 ### B. 对比诊断规则 至少输出： - 主任务超时率 - 爬虫超时率 - gap（百分点） - top market 重合情况 - 结论 #### 建议判定规则 - 若两者超时率差值 `< 1 pct` - 判定：**基本贴脸一致，问题主要由 crawler 链路传导** - 若主任务明显高于爬虫 `> 2 pct` - 判定：**deliver / 状态收口尾段可能存在额外拖后腿** - 若 top risk market 高度重合 - 判定：**风险源一致** - 若主任务新增 crawler 不明显的 market - 判定：**后链路异常需单独下钻** ### C. 追问例子（drill-down） 当用户继续问“给几个例子”时： 1. 优先复用对应 JSON 中的 `samples` 2. 若用户指定过滤维度（market/status/sampleType），则从标准化样例集合中过滤 3. 若默认样例不足，再调用底层脚本增强抽样能力或补充专用导出脚本 默认要补齐的字段： - `req_ssn` - `source_table` - `log_table` - `market` - `status` - `created_at / depart_at / arrival_at / deliver_at` - `task_hours / crawl_hours` - `ext_ssn` - `log_state` - `request` - `request_truncated` --- ## 输出契约 ```json { "scope": { "tenantId": "AK Data", "jobType": "AmazonListingJob", "dateBjt": "2026-04-05" }, "taskTimeout": { "baseline": "break_at", "generatedAtUtc": "2026-04-06 08:00:00", "total": {}, "markets": [], "samples": {} }, "crawlerTimeout": { "baseline": "depart_at", "generatedAtUtc": "2026-04-06 08:00:00", "total": {}, "markets": [], "samples": {} }, "comparison": { "taskTimeoutRate": 0.087, "crawlerTimeoutRate": 0.0854, "gapPct": 0.16, "topOverlapMarkets": ["nl", "jp", "pl"], "diagnosis": "主任务超时与爬虫超时基本贴脸一致，说明问题主要由 crawler 链路传导" }, "exampleQueryResult": { "scopeType": "crawler_timeout", "sampleType": "overtime_total", "market": "au", "status": "PENDING", "limit": 5, "rows": [] } } ``` --- ## 输出文案要求（对话） 对 LeeHoo 汇报时，建议固定结构： 1. **执行范围** 2. **总览指标** 3. **主任务 vs 爬虫差值** 4. **Top market / 高风险 market** 5. **诊断结论** 6. **如用户要求，补具体样例（带 request）** 7. **最后给出文件路径** --- ## 风险与降级 - 若某一底层报告失败： - 返回另一部分成功结果 - 明确标记 `partial=true` - 若 log 缺失： - 保留主记录 - `log_found=false` - 若 `request` 非法 JSON： - 返回原文字符串 - `request_parse_error=true` - 若 sample 不足： - 明确提示“默认样例不足，当前仅返回已有样例” --- ## 结论型经验（已沉淀） - LeeHoo 对该类问题的真实诉求不是单一口径，而是： - **某天总体超时怎样** - **主任务超时与爬虫超时是否贴脸一致** - **是否属于 crawler 传导，而不是 deliver 尾段独立炸锅** - **继续追问具体任务例子，并看 request 字段** - 因此统一入口 Skill 比两个分散 Skill 更适合作为对话层默认路由。

path: MIGRATION.md
content: # ak-data-daily-timeout-report 迁移说明

## 目的

把 AK Data 每日超时能力作为一个 **可迁移技能包** 使用。

该技能包覆盖：

- 单天主任务超时 + 爬虫超时联合查询
- 日期区间趋势汇总
- 继续追问具体任务样例（支持 log request）

---

## 先回答一个关键问题

### 迁移会不会把 Python 脚本一起带走？

**会，而且必须一起迁移。**

这个 skill 不是纯文档型 skill，它的实际执行依赖下面这些 Python 脚本：

```text
scripts/data/run_created_timeout_report.py
scripts/data/run_depart_timeout_report.py
scripts/data/run_daily_timeout_report.py
scripts/data/run_daily_timeout_trend_report.py
```

只迁移 `.pi/skills/ak-data-daily-timeout-report/` 目录是不够的，那样只剩说明书和壳，跑不起来。

如果你想一把打包走，可以使用：

```bash
python3 scripts/data/package_ak-data_daily_timeout_skill.py
```

默认输出：

```text
dist/ak-data-daily-timeout-report.bundle.tgz
```

## 最小迁移清单

迁移到新项目时，至少复制以下文件：

### Skill 层

```text
.pi/skills/ak-data-daily-timeout-report/SKILL.md
.pi/skills/ak-data-daily-timeout-report/run.sh
.pi/skills/ak-data-daily-timeout-report/MIGRATION.md
.pi/skills/ak-data-task-timeout-created-report/SKILL.md
.pi/skills/ak-data-depart-timeout-log-report/SKILL.md
```

### 执行脚本层（必须一起迁移）

```text
scripts/data/run_created_timeout_report.py
scripts/data/run_depart_timeout_report.py
scripts/data/run_daily_timeout_report.py
scripts/data/run_daily_timeout_trend_report.py
```

### 配置（推荐一起迁移）

```text
configs/skills/ak-data-daily-timeout-report.json
```

> 当前版本已经预留配置文件，但底层 Python 脚本还没有完全做到“全配置驱动”。
> 也就是说：配置文件是迁移辅助，不是魔法。目标项目表结构变了，还是要改脚本。

### 文档（推荐）

```text
docs/data/ak-data-daily-timeout-report.md
```

---

## 环境依赖

### Python

建议 Python 3.10+

### 依赖包

至少需要：

```bash
pip install pymysql
```

### 配置文件

默认配置文件：

```text
configs/skills/ak-data-daily-timeout-report.json
```

最少需要确认：

- `tenantId`
- `jobTables`
- `logTablePrefix`
- `marketExtractPaths`
- `output.rawDir`
- `output.reportDir`

### 环境变量

需要在项目 `.env` 中提供：

```env
ANKER_JOB_DB_HOST=xxx
ANKER_JOB_DB_PORT=3306
ANKER_JOB_DB_USER=xxx
ANKER_JOB_DB_PASSWORD=xxx
ANKER_JOB_DB_NAME=collector
ANKER_JOB_DB_CHARSET=utf8mb4
```

---

## 使用方式

### 0. 解压后先改配置

先修改：

```text
configs/skills/ak-data-daily-timeout-report.json
```

再确认项目根目录 `.env` 中数据库连接可用；bundle 内会附带 `.env.example` 作为填写模板。

### 1. 单天联合查询

```bash
.pi/skills/ak-data-daily-timeout-report/run.sh day \
  --date-bjt 2026-04-05 \
  --job-type AmazonListingJob
```

### 2. 单天 + 样例追问

```bash
.pi/skills/ak-data-daily-timeout-report/run.sh day \
  --date-bjt 2026-04-05 \
  --job-type AmazonListingJob \
  --example-scope crawler_timeout \
  --example-type overtime_total \
  --example-market au \
  --example-limit 5
```

### 3. 区间趋势

```bash
.pi/skills/ak-data-daily-timeout-report/run.sh trend \
  --start-date-bjt 2026-04-01 \
  --end-date-bjt 2026-04-05 \
  --job-type AmazonListingJob
```

---

## 测试方法（强制建议按顺序跑）

### 测试 1：看帮助

```bash
./bin/timeout
```

预期：输出 day / trend 两种用法说明。

### 测试 2：单天主流程

```bash
./bin/timeout day \
  --config configs/skills/ak-data-daily-timeout-report.json \
  --date-bjt 2026-04-05 \
  --job-type AmazonListingJob
```

预期：生成单天 JSON + Markdown。

### 测试 3：单天样例追问

```bash
./bin/timeout day \
  --config configs/skills/ak-data-daily-timeout-report.json \
  --date-bjt 2026-04-05 \
  --job-type AmazonListingJob \
  --example-scope crawler_timeout \
  --example-type overtime_total \
  --example-market au \
  --example-limit 3
```

预期：输出 JSON 中 `exampleQueryResult.rows` 非空或明确返回空样例，但命令能正常完成。

### 测试 4：区间趋势

```bash
./bin/timeout trend \
  --config configs/skills/ak-data-daily-timeout-report.json \
  --start-date-bjt 2026-04-01 \
  --end-date-bjt 2026-04-05 \
  --job-type AmazonListingJob
```

预期：生成趋势 JSON + Markdown。

### 测试 5：打包迁移包

```bash
python3 scripts/data/package_ak-data_daily_timeout_skill.py
```

预期：生成：

```text
dist/ak-data-daily-timeout-report.bundle.tgz
```

## 输出路径

### 单天

```text
docs/data/raw/ak-data_daily_timeout_<date>_<jobType>.json
docs/data/reports/custom/ak-data_daily_timeout_<date>_<jobType>.md
```

### 趋势

```text
docs/data/raw/ak-data_daily_timeout_trend_<start>_to_<end>_<jobType>.json
docs/data/reports/custom/ak-data_daily_timeout_trend_<start>_to_<end>_<jobType>.md
```

---

## 迁移注意事项

### 1. 主任务超时口径

- 日窗：`created_at`
- 正式判定：`break_at`

不要再退回到 `created_at + 12h` 的伪口径。

### 2. 爬虫超时口径

- 日窗：`depart_at`
- 判定：`arrival_at - depart_at`

### 3. request 字段

样例支持自动带 log `request`，但前提是：

- 对应 `log_a ~ log_d` 表存在
- `req_ssn` 能关联上

---

## 推荐迁移方式

如果目标项目目录结构兼容当前仓库，直接复制上述文件即可。

如果目录结构不同，优先修改：

- `.pi/skills/ak-data-daily-timeout-report/run.sh`

其中：

- `ROOT_DIR` 的相对路径推导可能需要调整。

这是唯一最容易因为目录层级变化而坏掉的地方。


path: TEMPLATE.md
content: # ak-data-daily-timeout-report 模板化改造说明

这个模板用于把当前技能包快速改造成其他项目可复用版本。

---

## 1. 你要替换的最小变量

### 业务侧

```text
TENANT_ID=AK Data
JOB_TYPE=AmazonListingJob
```

### 数据表侧

```text
JOB_TABLES=job_a,job_b,job_c,job_d
LOG_TABLES=log_a,log_b,log_c,log_d
```

### 输出侧

```text
RAW_DIR=docs/data/raw
REPORT_DIR=docs/data/reports/custom
```

---

## 2. 你要检查的字段映射

当前默认依赖以下字段：

### job 表字段

- `id`
- `req_ssn`
- `tenant_id`
- `type`
- `status`
- `created_at`
- `break_at`
- `depart_at`
- `arrival_at`
- `deliver_at`
- `payload`

### log 表字段

- `req_ssn`
- `ext_ssn`
- `state`
- `request`

如果目标项目字段名不一致，不要硬搬，直接改脚本 SQL。字段不对，所有统计都是假象。

---

## 3. 你要优先改的脚本点

### `run_created_timeout_report.py`

通常需要检查：

- `build_base_union()` 里的 job 分表名
- market 提取逻辑：`payload.market / payload.country`
- 索引名：`index_created_at_status`
- 主任务正式超时基线：`break_at`

### `run_depart_timeout_report.py`

通常需要检查：

- job 分表名
- depart / arrival 字段是否一致
- market 字段从哪里取

### `run_daily_timeout_report.py`

通常需要检查：

- 每日 JSON 输出路径
- comparison 诊断阈值
- 样例筛选字段命名

### `run_daily_timeout_trend_report.py`

通常需要检查：

- 趋势报告输出路径
- 最差日 / 最优日判定逻辑
- 是否需要额外增加 market 漂移分析

---

## 4. 建议的配置抽离方向

如果以后要通用化，建议把下面这些硬编码进一步抽到配置文件：

```json
{
  "tenantId": "AK Data",
  "jobTables": ["job_a", "job_b", "job_c", "job_d"],
  "logTables": ["log_a", "log_b", "log_c", "log_d"],
  "jobType": "AmazonListingJob",
  "marketExtractPaths": ["$.market", "$.country"],
  "output": {
    "rawDir": "docs/data/raw",
    "reportDir": "docs/data/reports/custom"
  }
}
```

现在没做成全配置化，是为了先保证稳定，不把事情搞成配置地狱。

---

## 5. 迁移后的最小验证清单

迁移后至少跑这三条：

### 单天主流程

```bash
.pi/skills/ak-data-daily-timeout-report/run.sh day \
  --date-bjt 2026-04-05 \
  --job-type AmazonListingJob
```

### 单天样例追问

```bash
.pi/skills/ak-data-daily-timeout-report/run.sh day \
  --date-bjt 2026-04-05 \
  --job-type AmazonListingJob \
  --example-scope crawler_timeout \
  --example-type overtime_total \
  --example-market au \
  --example-limit 3
```

### 区间趋势

```bash
.pi/skills/ak-data-daily-timeout-report/run.sh trend \
  --start-date-bjt 2026-04-01 \
  --end-date-bjt 2026-04-05 \
  --job-type AmazonListingJob
```

---

## 6. 推荐复制策略

### 只想先用

复制：

- `.pi/skills/ak-data-daily-timeout-report/`
- `scripts/data/run_*timeout*.py`
- `.env` 对应 DB 配置

### 想长期维护

再补：

- `docs/data/ak-data-daily-timeout-report.md`
- `docs/skills-catalog.md`
- `.pi/skills/_catalog.json`

---

## 7. 不建议你现在做的事

- 不要一上来就把所有表名、字段名、规则做成超复杂配置系统
- 不要为了“通用”把 AK Data 的明确口径打散
- 不要把 `break_at` 再退化回 `created_at + timeout_hours`

先能稳定迁移，再谈高度抽象。烂抽象比硬编码更恶心。


path: run.sh
content: #!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
ROOT_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"

if [ $# -lt 1 ]; then
  cat <<'EOF'
Usage:
  .pi/skills/ak-data-daily-timeout-report/run.sh day   --date-bjt YYYY-MM-DD --job-type AmazonListingJob [--config path] [extra args]
  .pi/skills/ak-data-daily-timeout-report/run.sh trend --start-date-bjt YYYY-MM-DD --end-date-bjt YYYY-MM-DD --job-type AmazonListingJob [--config path] [extra args]

Examples:
  .pi/skills/ak-data-daily-timeout-report/run.sh day --date-bjt 2026-04-05 --job-type AmazonListingJob
  .pi/skills/ak-data-daily-timeout-report/run.sh day --date-bjt 2026-04-05 --job-type AmazonListingJob --example-scope crawler_timeout --example-type overtime_total --example-market au --example-limit 5
  .pi/skills/ak-data-daily-timeout-report/run.sh trend --start-date-bjt 2026-04-01 --end-date-bjt 2026-04-05 --job-type AmazonListingJob
EOF
  exit 1
fi

MODE="$1"
shift

case "$MODE" in
  day)
    exec python3 "$ROOT_DIR/scripts/data/run_daily_timeout_report.py" "$@"
    ;;
  trend)
    exec python3 "$ROOT_DIR/scripts/data/run_daily_timeout_trend_report.py" "$@"
    ;;
  *)
    echo "Unsupported mode: $MODE" >&2
    exit 2
    ;;
esac


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)