---
name: query-user-behavior-path
description: 从 loghubods 视频、广告、播放、简单事件和用户活跃日志中查询、合并并解释单个用户的完整离线或明确指定的实时行为时间线。用于按 mid 或 machinecode 检查完整行为路径、生成按时间排序的 Excel、补充 businesstype 和 pagesource 中文定义，或诊断用户旅程。
---

# 查询用户完整行为路径

将 `SKILL_DIR` 解析为当前 `SKILL.md` 所在的安装目录。所有命令都通过该目录调用随 Skill 分发的脚本；不得假定作者的工作区路径。

## 运行环境

依赖 `pyodps`、`pandas` 和 `openpyxl`。随 Skill 分发的 ODPS 客户端读取 `ODPS_ACCESS_ID`、`ODPS_ACCESS_SECRET`、`ODPS_PROJECT` 和 `ODPS_ENDPOINT`。不得把凭证复制到 Skill、查询输出或回复中。

## 必要输入

- 用户标识：视频/播放日志使用 `mid`，广告/简单事件/用户活跃日志使用 `machinecode`，值相同。
- 日期：`yyyyMMdd`。
- 可选 `apptype`，默认 `0`。
- 输出目录，默认当前目录。

## 离线流程

1. 阅读 [logs-and-definitions.md](references/logs-and-definitions.md)。
2. 运行：

   `python3 "$SKILL_DIR/scripts/user_timeline.py" <mid_or_machinecode> <yyyyMMdd> [apptype] --output-dir <目录>`

3. 报告输出路径、总行数、各来源行数以及行数为零的来源。
4. 校验时间顺序、Excel 时间格式、技术事件排除和中文行为定义。
5. 仅当用户明确要求上传飞书时，使用 `$feishu-data-publisher` 发布最终 Excel；未明确要求时只保留本地结果。

## 实时流程

只有用户明确要求实时数据时才运行：

`python3 "$SKILL_DIR/scripts/user_timeline_realtime.py" <mid_or_machinecode> [yyyyMMdd] [apptype] --output-dir <目录>`

必须说明结果只是当前可用实时数据。`simpleevent_log_flow` 保留周期短，不能代替完整离线日回灌。

## 批量实时流程

输入 CSV 必须包含 `用户标识`，可以包含 `命中策略`。运行：

`python3 "$SKILL_DIR/scripts/user_timeline_realtime_batch.py" <用户清单.csv> [yyyyMMdd] [apptype] --output-dir <目录>`

输出包含可筛选的 `实时行为路径` 工作表和 `用户摘要` 工作表；摘要必须保留当前事件数为零的输入用户。

## 安全与校验

- 除非用户明确要求实时数据，否则只使用离线表。
- 每张表都必须按日期、`apptype`、用户标识和非空 `clienttimestamp` 过滤。
- 各表事件使用 `UNION ALL` 保留，不得跨表去重。
- 先按原始时间戳稳定排序，再转换为北京时间。
- 不向终端打印完整用户事件表。
- 只有参考资料或已确认源码支持时才补充中文行为定义。
- 执行前运行 `python3 -m py_compile "$SKILL_DIR"/scripts/*.py`。