# fuse-intermodal-od-skill **Repository Path**: maerio/fuse-intermodal-od-skill ## Basic Information - **Project Name**: fuse-intermodal-od-skill - **Description**: Codex Skill for inter-zonal and inter-hub OD data fusion - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-07-22 - **Last Updated**: 2026-07-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Fuse Intermodal OD Skill [English](README_EN.md) 如果你从业务平台下载了两类 OD 文件——一类是区县、网格、Geohash 或坐标级的细粒度移动 OD,另一类是机场到机场、车站到车站的粗粒度枢纽票务 OD——这个 Skill 可以把它们整理到同一条处理链里。 它会先检查字段,再用 Python 做清洗和规则计算,用 SQLite/SQL 做暂存、去重和排序,最后生成轨迹、联程候选、异常记录和审计文件。每个结果都能回到原文件和原行,方便排查,也方便业务验收。 整个流程默认在本地运行。仓库不保存、展示或上传任何真实 OD 数据。 ## 1. 它具体做什么 两类平台 OD 文件通常不能直接合并。字段名可能不同,时间格式可能混在一起,同一用户的记录还可能出现重复、倒序、断档或空间跳跃。 这个 Skill 处理五件事: 1. 检查两类 CSV 的字段是否齐全,字段映射是否正确; 2. 自动区分细粒度移动 OD 和枢纽票务 OD,再把不同时间结构整理成统一格式; 3. 按匿名用户和时间顺序重构连续出行链; 4. 根据中转时间、枢纽位置和接入/接出距离筛选联程候选; 5. 保存拒绝原因、切链原因、实际参数和处理数量,保证结果可追溯。 输出的是一份可以继续核验的业务候选清单,不是已经确认的票务订单或真实联程关系。正式使用前,仍要结合订单、票务、运营记录或人工抽查。 ## 2. 适合什么数据 当前业务流程按“平台下载后保存为 CSV”设计,适合: - 区县、网格或其他空间单元之间的 Inter-zonal OD; - 机场到机场、车站到车站等只精确到枢纽级的用户票务 OD; - 两类文件都能使用同一套匿名用户编号; - 每一行是一段用户 OD,而不是汇总后的 OD 流量矩阵; - 移动 OD 有四个驻留/到离时间,票务 OD 至少有出发和到达时间; - 起点和终点至少有空间单元编号、Geohash 或经纬度中的一种空间信息。 以下数据不能直接使用: - 只有起点、终点和总流量,没有用户编号的汇总表; - 只有零散定位点、尚未生成 OD 段的原始定位记录; - 用户编号在两类文件中无法对应; - 时间字段含义不清,无法区分到达、离开和驻留时间; - 需要直接用于计费、结算、客户触达或运营考核,但尚未经过业务复核的数据。 这里的“粗粒度”指空间位置只精确到枢纽,不是只有枢纽对和人数的汇总表。票务数据要进入个人轨迹融合,仍然必须是一人一条票务段,并且能通过合规的匿名用户编号与移动 OD 对应。只有枢纽对、时段和客流量的汇总数据可以单独做总量校验,但不能还原成个人轨迹。 ## 3. Python、SQL 和审计文件怎样配合 ### 3.1 工作流 ```text 业务平台下载两类 CSV ↓ 受控目录保存原始文件,只读保留 ↓ Python 检查表头、编码、分隔符和字段映射 ↓ Python + pandas 解析时间、空间字段并标记异常 ↓ SQLite/SQL 暂存、唯一键去重、按用户和时间排序 ↓ Python 判断相邻记录是否可以连接,并记录切链原因 ↓ Python 重构节点、识别内部枢纽并筛选联程候选 ↓ CSV + JSON + YAML + Markdown 保存结果和审计信息 ↓ Python 校验输出数量和候选完整性 ``` ### 3.2 每个工具负责什么 | 工具 | 在流程中的职责 | 留下的可追溯信息 | |---|---|---| | 业务平台 | 导出区县 OD 和枢纽 OD | 下载批次、文件名称和平台侧导出记录应由业务方登记 | | Python | 编排整个流程,读取 CSV,检查字段,解析时间和空间信息,计算距离、速度及候选规则 | 处理器版本、异常代码、连接诊断和输出计数 | | pandas | 分块读取 CSV,统一字段类型,处理时间和数值字段 | 规范化后的记录字段与拒绝原因 | | SQLite/SQL | 暂存接受的记录,使用唯一键去重,建立排序索引,再按用户和时间顺序读取 | 唯一记录、重复数量、稳定排序顺序 | | YAML | 保存字段映射和业务参数 | `resolved_config.yaml` 记录本次实际使用的完整配置 | | JSON | 保存机器可读的运行审计 | `fusion_audit.json` 记录输入、接受、拒绝、重复、切链和候选数量 | | CSV | 保存轨迹、节点、候选和拒绝记录 | 可以从结果追到轨迹、原文件和原行 | | Markdown | 生成人能直接阅读的业务报告 | `fusion_report.md` 汇总本次处理情况和预警 | SQLite 由 Python 自动创建和调用,不需要另外部署数据库服务器。CSV 默认每 200,000 行分块读取,再写入 SQLite 暂存库,因此大文件不需要一次全部放进内存。 ### 3.3 一条记录怎样追溯 处理后的记录会保留以下信息: - `dataset`:来自区县 OD 还是枢纽 OD; - `input_file`:来自哪个原始文件; - `input_row`:在原始文件中的行号; - `record_id`:由数据集、文件路径标识和原行号组成的记录编号; - `trajectory_id`:记录被分配到哪条重构轨迹; - `sequence`:记录在轨迹中的顺序; - `link_reason`:为什么与上一段连接; - `reject_reason`:为什么被拒绝; - `candidate_reason`:为什么进入或没有进入联程候选。 这样排查问题时,不需要猜某条结果从哪里来,可以沿着“候选轨迹 → 轨迹节点 → OD 段 → 原文件和原行”逐级检查。 ## 4. 数据保密要求 真实 OD 数据属于敏感业务数据。建议把下面这些要求作为固定流程,而不是临时注意事项: 1. 原始 CSV 放在仓库外的受控目录中,不要复制到项目目录; 2. 不要把原始 CSV、处理结果、数据库或截图提交到 GitHub、Gitee、工单、聊天工具和公开网盘; 3. 两类文件只使用匿名用户编号,不在文件中保留姓名、手机号、证件号等直接身份信息; 4. 原始文件保持只读,所有结果写入单独的输出目录; 5. 输出文件仍包含匿名用户编号、原始文件路径和原行号,也要按敏感数据管理; 6. 默认不要使用 `--keep-staging`。SQLite 暂存库在正常运行结束后会自动删除;只有排查问题时才临时保留; 7. 对外分享审计报告前,检查并移除内部目录、文件名、用户编号和其他可识别信息; 8. 按所在单位的权限、留存时间、加密和销毁制度管理原始文件与结果。 仓库中的 `.gitignore` 已默认忽略 CSV、TSV、Excel、Parquet、数据库和常见输出目录,但它只是最后一道保护。最稳妥的做法仍然是让真实数据始终留在仓库外。 当前版本通过原文件路径和原行号追溯记录,但不会自动生成原文件内容哈希。如果单位要求严格的文件级交接审计,应在下载登记或受控文件系统中另外保存下载时间、文件大小和校验值。 ## 5. 输入字段 ### 5.1 两种记录类型 | `record_type` | 数据含义 | 时间要求 | 使用方式 | |---|---|---|---| | `mobility_od` | 一名匿名用户的一段细粒度移动 OD | `o_start`、`o_end`、`d_start`、`d_end` | 默认用于 `zonal` 输入 | | `ticket_od` | 一名匿名用户的一段枢纽到枢纽票务 OD | `depart`、`arrive` | 可由 `hub` 输入自动识别或在配置中明确指定 | | `auto` | 让处理器根据表头选择上述类型 | 优先检查四时间结构,再检查出发/到达结构 | 默认用于 `hub` 输入 | 原始定位点必须先在受控环境中转成一行一段的移动 OD。聚合票务客流没有共享匿名用户编号,不能作为 `ticket_od` 使用。 ### 5.2 必需字段和可选字段 配置文件使用“规范字段”表示程序内部含义,再把它映射到平台 CSV 中的真实字段名。移动 OD 和票务 OD 可以分别配置,不要求两类文件的表头完全一样。 | 规范字段 | 默认 CSV 字段名 | 要求 | 含义 | |---|---|---|---| | `uid` | `uidnumber` | 两类记录都必需 | 匿名用户编号,两类 OD 必须使用同一编码体系 | | `o_start` | `o_start_dt` | `mobility_od` 必需 | 起点驻留开始时间 | | `o_end` | `o_end_dt` | `mobility_od` 必需 | 起点驻留结束或离开时间 | | `d_start` | `d_start_dt` | `mobility_od` 必需 | 终点驻留开始或到达时间 | | `d_end` | `d_end_dt` | `mobility_od` 必需 | 终点驻留结束时间 | | `depart` | `departure_dt` | `ticket_od` 必需 | 票务段从起点枢纽出发的时间 | | `arrive` | `arrival_dt` | `ticket_od` 必需 | 票务段到达终点枢纽的时间 | | `o_zone` | `o_zone_id` | 条件必需 | 起点区县、网格、空间单元或枢纽编号 | | `d_zone` | `d_zone_id` | 条件必需 | 终点区县、网格、空间单元或枢纽编号 | | `o_geohash` | `o_geohash_id` | 条件必需 | 起点 Geohash | | `d_geohash` | `d_geohash_id` | 条件必需 | 终点 Geohash | | `o_lat` | `o_lat` | 可选,建议提供 | 起点纬度,与起点经度成对使用 | | `o_lon` | `o_lon` | 可选,建议提供 | 起点经度,与起点纬度成对使用 | | `d_lat` | `d_lat` | 可选,建议提供 | 终点纬度,与终点经度成对使用 | | `d_lon` | `d_lon` | 可选,建议提供 | 终点经度,与终点纬度成对使用 | | `o_name` | `o_name` | 枢纽 OD 建议提供 | 起点名称,用于辅助识别交通枢纽 | | `d_name` | `d_name` | 枢纽 OD 建议提供 | 终点名称,用于辅助识别交通枢纽 | | `source` | `Source` | 枢纽 OD 建议提供 | 交通方式或枢纽类型 | | `ticket_id` | `ticket_id` | 票务 OD 可选 | 票务记录标识,用于回查和去重 | | `service_id` | `service_id` | 票务 OD 可选 | 航班、车次或其他班次标识 | | `date` | `date_dt` | 可选 | 平台保留的记录日期 | | `journey_purpose` | `journey_purpose` | 可选 | 已有的出行目的分类,只随结果保留 | | `age` | `Age` | 可选 | 年龄或年龄分组,只随结果保留 | | `gender` | `Gender` | 可选 | 性别分类,只随结果保留 | “条件必需”是指每个端点至少要有一种空间证据:空间单元/枢纽编号、Geohash,或者完整的经纬度对。 ### 5.3 时间字段怎么理解 细粒度移动 OD 的时间顺序应当是: ```text 起点驻留开始 → 起点离开 → 终点到达 → 终点驻留结束 ``` 枢纽票务 OD 只需要出发和到达时间。处理器会统一转换为: ```text o_start = o_end = depart d_start = d_end = arrive ``` 票务段与相邻移动段在同一枢纽合并后,节点停留时间才由移动记录和票务时刻共同确定。如果平台同时提供计划时刻和实际时刻,一个批次必须统一采用同一口径,并在配置审批中记录。 推荐平台导出时统一为 `YYYY-MM-DD HH:MM:SS`。两类 CSV 必须采用同一时区,当前程序不会自动判断或转换时区。 以下情况会被拒绝并写入 `record_rejections.csv`: - 对应记录类型所需的任一时间无法解析; - 移动 OD 的起点或终点驻留开始时间晚于结束时间; - 起点离开晚于终点到达; - 已知距离下计算出的段内速度超过上限。 ### 5.4 空间字段怎么使用 - 经纬度优先用于距离计算,建议使用 WGS 84 十进制度; - 经纬度缺失时,程序会尝试把标准 Geohash 解码为格网中心点; - 只有空间单元或枢纽编号时,可以通过编号相同确认衔接,但不能计算实际距离; - 三类空间信息都不足时,默认切断轨迹,不会只凭时间强行拼接。 移动 OD 和票务 OD 使用不同空间编码时,应先在受控环境中补齐共同的枢纽代码或坐标。枢纽名称可以帮助识别枢纽类型,但不会被单独用来强行合并位置。 程序计算的是球面直线距离,只用于数据一致性检查和候选筛选,不代表道路、铁路或实际运行距离。 ### 5.5 枢纽怎么识别 枢纽识别主要看两个字段: - `source` 是否属于配置中的机场或铁路类型; - `o_name` / `d_name` 是否包含配置中的枢纽关键词。 当整个票务文件都是同一种交通类型且经过确认时,可以在配置中使用 `default_source`。混合航空和铁路记录不能共用一个默认来源。 程序不会因为一条记录放在枢纽 OD 文件里,就自动把每个端点都当作枢纽。首次接入新的平台或城市时,应先检查 `hub_sources` 和 `hub_name_patterns`,避免漏识别或误识别。 ## 6. 默认业务规则 一条轨迹进入联程候选,需要至少有一个内部节点同时满足: ```text 节点位于整条轨迹中部 AND 节点被识别为机场或重点铁路枢纽 AND 0.5 小时 <= 节点停留时间 <= 8 小时 AND max(接入位移, 接出位移) > 50 km ``` 几个容易混淆的地方: - 只出现在整条链起点或终点的枢纽,不算内部中转节点; - 50 km 是严格大于,等于 50 km 不通过; - 默认 `qualifying_hub_policy: any`,一条轨迹中至少一个内部枢纽通过即可; - 候选只是规则初筛结果,必须经过业务核验后才能用于后续工作。 轨迹重构还使用以下参数: | 参数 | 默认值 | 用途 | |---|---:|---| | `max_chain_gap_hours` | 8 小时 | 相邻记录间隔过长时切链 | | `max_overlap_minutes` | 30 分钟 | 时间负重叠过大时切链 | | `spatial_tolerance_km` | 20 km | 控制上一段终点与下一段起点的最大衔接距离 | | `node_merge_tolerance_km` | 1 km | 判断相邻边界端点能否合并成一个节点 | | `max_speed_kmh` | 1000 km/h | 排查段内或桥接速度异常 | | `unresolved_spatial_policy` | `split` | 空间证据不足时默认切链 | 这些值会受平台采样频率、空间尺度、定位误差和交通方式影响。正式上线前,应由数据负责人和业务负责人共同确认;调整后必须保留实际配置,不能只修改结果说明。 ## 7. 安装 ### 7.1 获取代码 GitHub: ```powershell git clone https://github.com/liyichang038516-ui/fuse-intermodal-od-skill.git cd fuse-intermodal-od-skill ``` Gitee: ```powershell git clone https://gitee.com/maerio/fuse-intermodal-od-skill.git cd fuse-intermodal-od-skill ``` ### 7.2 安装 Python 依赖 推荐 Python 3.10 或更高版本: ```powershell python -m pip install pandas numpy pyyaml ``` 平台标准流程使用 CSV,不需要额外的 Excel 或 Parquet 组件。如果临时接收了其他格式,可以按需安装: ```powershell python -m pip install openpyxl pyarrow xlrd ``` ## 8. 运行 以下命令都在仓库根目录执行。尖括号内是本地受控目录中的文件或文件夹,请替换成实际路径,但不要把真实路径写入公开文档。 ### 8.1 先检查字段 ```powershell python .\skills\fuse-intermodal-od\scripts\od_fusion.py inspect ` --zonal "" ` --hub "" ``` 重点检查: - `missing_required` 是否为空; - `record_type` 是否正确识别为 `mobility_od` 或 `ticket_od`; - 起点和终点是否都有空间证据; - `ready` 是否为 `true`; - 映射到的字段是否符合平台字段说明。 这个命令输出字段名、映射状态和文件路径,不输出具体 OD 行。文件路径本身也可能包含内部信息,因此不要把检查结果直接贴到公开平台。 ### 8.2 字段名不一致时修改配置 先复制默认配置: ```powershell Copy-Item ` ".\skills\fuse-intermodal-od\assets\default-config.yaml" ` ".\my-config.yaml" ``` 然后在 `my-config.yaml` 中分别修改 `inputs.zonal.columns` 和 `inputs.hub.columns`。细粒度移动数据设置为 `record_type: mobility_od`;枢纽票务数据可以设置为 `ticket_od`,也可以保留 `auto` 让程序按表头识别。只有整个文件交通类型一致时才设置 `default_source`。配置中不要写用户编号、位置、时间或任何真实记录。 ### 8.3 执行融合 ```powershell python .\skills\fuse-intermodal-od\scripts\od_fusion.py run ` --zonal "" ` --hub "" ` --out "" ` --config ".\my-config.yaml" ``` 如果字段名与默认配置完全一致,可以省略 `--config`。一个批次有多个 CSV 时,可以在 `--zonal` 或 `--hub` 后依次填写多个文件。 输出目录中已经存在受管理结果时,程序会停止,防止误覆盖。确认需要替换旧结果后再增加 `--overwrite`。 ### 8.4 验收输出 ```powershell python .\skills\fuse-intermodal-od\scripts\od_fusion.py validate ` --out "" ``` `valid` 为 `true` 时,表示主要文件齐全、文件行数与审计计数一致,而且每条候选轨迹都有合格的内部枢纽节点。 ## 9. 输出文件 | 文件 | 内容 | 主要用途 | |---|---|---| | `fused_segments.csv` | 接受的移动/票务 OD 段、记录类型、票务标识、轨迹编号、段序号和连接诊断 | 回查每段 OD 怎样进入轨迹 | | `trajectory_points.csv` | 重构节点、停留时间、枢纽标记和接入/接出距离 | 检查节点合并与枢纽判断 | | `trajectory_summary.csv` | 每条轨迹的起终点、时长、段数、距离和候选结果 | 轨迹级汇总 | | `intermodal_candidates.csv` | 通过核心业务规则的轨迹 | 人工复核和业务统计 | | `record_rejections.csv` | 被拒绝记录的原文件、原行号和原因 | 修复源数据或字段格式 | | `fusion_audit.json` | 输入、接受、拒绝、重复、切链和候选计数 | 自动审计和批次对比 | | `fusion_report.md` | 本次运行的中文摘要、参数和预警 | 业务验收和归档 | | `resolved_config.yaml` | 本次实际使用的完整配置 | 复现处理口径 | | `od_fusion_staging.sqlite` | 规范化后的暂存数据,仅在主动保留时存在 | 技术排查,不建议长期留存 | ## 10. 常见异常代码 记录被拒绝时,常见原因包括: | 代码 | 含义 | |---|---| | `missing_uid` | 匿名用户编号缺失 | | `invalid_o_start` / `invalid_o_end` | 起点时间无法解析 | | `invalid_d_start` / `invalid_d_end` | 终点时间无法解析 | | `invalid_depart` / `invalid_arrive` | 票务出发或到达时间无法解析 | | `origin_stay_reversed` | 起点驻留时间倒置 | | `destination_stay_reversed` | 终点驻留时间倒置 | | `segment_time_reversed` | 起点离开时间晚于终点到达时间 | | `segment_speed_exceeds_limit` | 段内估算速度超过上限 | 相邻记录被切开时,常见原因包括: | 代码 | 含义 | |---|---| | `time_overlap` | 时间负重叠超过允许范围 | | `time_gap` | 相邻记录间隔过长 | | `unresolved_spatial` | 空间证据不足 | | `spatial_gap` | 相邻端点距离过大 | | `bridge_speed_exceeds_limit` | 相邻端点桥接速度异常 | 完全重复的记录只保留第一条,其余记录计入审计文件中的重复数量,不会重复写入拒绝表。 ## 11. 业务验收建议 每个批次至少检查: 1. 输入总数是否等于唯一接受数、拒绝数和重复数之和; 2. 拒绝率和主要拒绝原因是否合理; 3. `unresolved_spatial`、`time_gap` 和 `spatial_gap` 的比例是否异常; 4. 轨迹汇总行数是否与审计中的轨迹数一致; 5. 每条候选是否存在 `is_internal=1` 且 `qualifying_hub=1` 的节点; 6. 抽查的候选能否回到原文件和原行; 7. `resolved_config.yaml` 是否与本批次确认的参数一致; 8. 输出目录是否按数据保密制度设置权限和留存期限。 首次接入新平台、新城市、新月份或新空间尺度时,不要直接沿用历史参数。先比较候选数量、拒绝原因和切链比例,再由数据与业务负责人确认正式口径。 ## 12. 作为 Codex Skill 使用 Skill 目录位于: ```text skills/fuse-intermodal-od/ ``` 可以把这个目录复制到个人或项目的 Codex Skill 目录。安装后,可以直接提出业务任务: ```text 使用 fuse-intermodal-od 检查两类平台 OD 的字段,并告诉我哪些字段需要重新映射。 ``` ```text 使用 fuse-intermodal-od 在本地受控目录中重构轨迹,输出候选和完整审计文件。 ``` 不要在对话提示、截图或公开任务说明中粘贴真实 OD 内容。只提供受控环境内的文件路径和必要的字段说明。 ## 13. 测试 修改脚本、配置或规则后运行: ```powershell python .\skills\fuse-intermodal-od\scripts\test_od_fusion.py ``` ## 14. 项目结构 ```text fuse-intermodal-od-skill/ ├── README.md ├── README_EN.md ├── .gitattributes ├── .gitignore └── skills/ └── fuse-intermodal-od/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── assets/ │ └── default-config.yaml ├── references/ │ ├── data-profiles.md │ └── fusion-rules.md └── scripts/ ├── od_fusion.py └── test_od_fusion.py ``` 当前处理器版本:`1.1.0`。 字段、规则或默认参数发生变化时,应同时更新配置、脚本、测试和版本号。业务流程只有在输入、配置、结果和审计文件能够一一对应时,才算真正可复现。