⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。

<!-- professional-disclaimer-injected -->

本内容由 AI 生成，仅供学习参考

<!-- ai-generated-notice -->

rod — 数据规整与结构化转换技能

一、能力边界（一页纸速查卡）

1.1 能做与不能做

| 维度 | 能做 | 不能做 | |------|------|--------| | 输入 | 用户提供的文本、CSV/JSON 文件、URL 指向的公开数据 | 需要登录鉴权的私有系统数据、验证码保护的页面 | | 处理 | 字段提取、格式统一、去重合并、类型推断 | 语义理解（如情感分析）、跨语言翻译 | | 输出 | 结构化 JSON/CSV，含置信度标注 | 生成图表、撰写分析报告 | | 批量 | 支持同构数据的批量处理（≤5000 条/批） | 异构数据混合处理（需先分拣） | | 扩展 | 自定义字段映射规则、自定义输出模板 | 实时流式处理、定时任务调度 |

1.2 适用对象

• 目标用户：需要将爬虫采集结果、导出报表、手工整理的杂散数据转换为统一格式的数据分析人员、运营人员、开发工程师。
• 典型场景：电商商品信息规整、新闻列表字段抽取、用户信息表合并去重、日志关键字段提取。
• 不适用场景：需要主观判断的文本分类、非结构化长文本的深度理解、需要外部知识库补全的缺失信息。

---

二、触发方式

2.1 触发词

当用户输入包含以下任一关键词时，本技能自动激活：

• 核心触发词：rod、爬虫采集
• 同义场景词：数据规整、结构化转换、字段清洗、批量处理

2.2 场景映射表

| 用户说（大白话） | 实际需求 | 技能响应 | |------------------|----------|----------| | "帮我把这个 CSV 里的日期格式统一一下" | 字段格式标准化 | 识别日期列，统一为 ISO 8601 格式 | | "爬下来的数据乱七八糟，帮我整理成表格" | 非结构化 → 结构化 | 解析文本，提取关键字段，输出 JSON | | "这两个文件里都有用户信息，帮我合并去重" | 数据合并与去重 | 按主键匹配，合并字段，标记重复项 | | "这个 URL 里的数据帮我抓下来整理好" | URL 数据采集与规整 | 请求 URL，解析响应，提取字段，结构化输出 | | "我有 1000 条数据要处理，格式都一样" | 批量处理 | 按模板批量执行，输出汇总结果 |

---

三、标准流程

3.1 前置条件

| 条件项 | 要求 | 检查方式 | |--------|------|----------| | 输入文件 | 编码为 UTF-8（无 BOM），大小 ≤ 50MB | 文件头检查 | | 输入格式 | CSV（逗号分隔）、JSON（数组或对象）、纯文本（每行一条记录） | 扩展名 + 首行预览 | | 命名规范 | 文件名为 input_* 或 data_* 开头，便于识别 | 文件名正则匹配 | | 环境依赖 | Python 3.8+，安装 pandas、requests（如需 URL 采集） | pip list 检查 |

3.2 执行步骤

Step 1：输入确认（耗时约 1 分钟）

1. 确认输入来源类型：文件 / URL / 直接粘贴文本。
2. 若为文件，检查文件编码、分隔符、首行是否为表头。
3. 若为 URL，确认目标是否可公开访问（HTTP 状态码 200）。
4. 与用户确认输出格式偏好：JSON / CSV / 两者都要。

Step 2：字段映射与规则配置（耗时约 2 分钟）

1. 识别输入中的关键字段（至少 3 个，至多 20 个）。
2. 定义字段映射表：

| 输入字段（原始） | 输出字段（标准） | 处理规则 | |------------------|------------------|----------| | name / 标题 | title | 去除首尾空格，首字母大写 | | date / 时间 | publish_date | 统一为 YYYY-MM-DD 格式 | | price / 价格 | amount | 转为浮点数，保留两位小数 | | url / 链接 | source_url | 校验 URL 格式，补全协议头 |

3. 确定主键字段（用于去重，如 id 或 title）。

Step 3：试运行（耗时约 2 分钟）

1. 取前 5 条数据执行完整流程。
2. 核对输出字段完整性、格式正确性。
3. 若发现字段映射错误，调整规则后重新试运行。

Step 4：批量执行（耗时视数据量而定）

1. 对全量数据执行处理流程。
2. 每处理 1000 条输出一次进度提示。
3. 处理完成后生成汇总报告（处理总数、成功数、失败数、去重数）。

Step 5：结果校验与交付（耗时约 3 分钟）

1. 随机抽取 10% 的输出去重样本，人工核对关键字段。
2. 检查置信度标注是否完整（每条记录必须有 confidence 字段）。
3. 输出最终结果文件，命名规则：output_YYYYMMDD_HHMMSS.json/csv。

3.3 输出规范

标准输出结构（JSON 格式）：

{
  "meta": {
    "total_count": 1000,
    "success_count": 985,
    "failed_count": 15,
    "duplicate_removed": 23,
    "processing_time_seconds": 12.5
  },
  "data": [
    {
      "title": "示例商品",
      "publish_date": "2026-08-20",
      "amount": 99.99,
      "source_url": "https://example.com/item/123",
      "confidence": 0.95,
      "warnings": []
    }
  ],
  "errors": [
    {
      "record_index": 17,
      "field": "amount",
      "error_type": "PARSE_ERROR",
      "message": "无法解析价格字段：'free'"
    }
  ]
}

置信度标注规则：

| 置信度范围 | 含义 | 适用场景 | |------------|------|----------| | 0.90 - 1.00 | 高置信度，字段完整且格式正确 | 所有字段均成功解析 | | 0.70 - 0.89 | 中置信度，部分字段缺失但关键字段完整 | 1-2 个非关键字段缺失 | | 0.50 - 0.69 | 低置信度，关键字段缺失或格式异常 | 主键缺失、日期格式无法识别 | | < 0.50 | 极低置信度，建议人工复核 | 多个字段无法解析 |

---

四、置信度门控

4.1 信息不足时的处理原则

核心原则：不编造、不猜测、显式标注。

当遇到以下情况时，输出 [需核实:字段名] 占位符：

| 场景 | 处理方式 | 示例 | |------|----------|------| | 字段缺失 | 输出 [需核实:字段名]，置信度降至 0.6 | "amount": "[需核实:amount]" | | 格式无法识别 | 保留原始值，标注 [需核实:格式] | "date": "[需核实:格式]2026/08/20" | | 值超出合理范围 | 标注 [需核实:范围]，保留原值 | "amount": "[需核实:范围]999999" | | 主键冲突 | 保留第一条，标注 [需核实:主键] | 重复记录仅输出一次，附警告 |

4.2 二次确认机制

当满足以下任一条件时，暂停处理并向用户确认：

1. 超过 30% 的记录置信度低于 0.70。
2. 存在无法自动判断的字段映射（如两个字段都像"价格"）。
3. 输入数据量超过 5000 条，需要用户确认是否分批处理。

确认话术模板：

检测到 [具体问题描述]，当前处理结果中 [X]% 的记录置信度低于 0.70。建议 [具体建议]，是否继续处理？或需要调整字段映射规则？

---

五、错误码体系

5.1 错误码速查表

| 错误码 | 含义 | 用户提示话术 | 修正步骤 | |--------|------|--------------|----------| | E001 | 输入文件不存在 | "未找到指定的输入文件，请检查文件路径是否正确。" | 1. 确认文件路径；2. 检查文件名大小写；3. 重新输入 | | E002 | 文件编码不支持 | "文件编码不是 UTF-8，请转换编码后重试。" | 1. 使用 iconv 转换编码；2. 或另存为 UTF-8 格式 | | E003 | 输入格式无法识别 | "无法识别输入格式，支持 CSV、JSON、纯文本。" | 1. 确认文件扩展名；2. 检查首行内容是否符合预期格式 | | E004 | URL 访问失败 | "无法访问目标 URL，请确认链接可公开访问。" | 1. 检查 URL 拼写；2. 确认网络连通性；3. 检查是否有反爬限制 | | E005 | 字段映射冲突 | "检测到字段映射冲突，两个输入字段映射到同一输出字段。" | 1. 查看冲突详情；2. 调整映射规则；3. 重新执行 | | E006 | 批量处理中断 | "批量处理在第 [N] 条记录处中断，请查看错误日志。" | 1. 查看 errors 数组；2. 修复问题记录；3. 从断点继续处理 | | E007 | 输出写入失败 | "无法写入输出文件，请检查磁盘空间和目录权限。" | 1. 检查磁盘空间；2. 确认目录可写；3. 更换输出路径 |

5.2 错误处理流程

检测到错误
    ↓
记录错误详情（错误码、记录索引、字段名、原始值）
    ↓
判断错误类型：
    ├── 可自动修复（如格式微调）→ 修复并标记 warning
    ├── 需用户决策（如字段映射冲突）→ 暂停并询问
    └── 不可修复（如数据损坏）→ 跳过该记录，计入 failed_count
    ↓
继续处理剩余数据
    ↓
生成错误报告，随结果一并输出

---

六、FAQ 反模式

6.1 常见坑与反模式对照

| 常见坑 | 反模式（错误做法） | 正模式（正确做法） | |--------|-------------------|-------------------| | 忽略原始数据备份 | 直接对原文件执行处理，导致数据不可逆 | 始终保留原始文件副本，处理副本文件 | | 一次性处理全部数据 | 不试运行直接全量执行，发现规则错误后全部重来 | 先取 5 条试运行，确认规则无误后再全量执行 | | 字段映射过于激进 | 将两个相似字段强行合并，导致信息丢失 | 保留两个字段，分别标注，或设置优先级规则 | | 忽略置信度标注 | 所有记录统一标注 1.0 置信度，失去参考价值 | 按实际解析情况逐条计算置信度 | | 错误记录静默跳过 | 处理失败的记录直接丢弃，用户不知情 | 将失败记录写入 errors 数组，随结果一并输出 | | 日期格式一刀切 | 所有日期强制转为 YYYY-MM-DD，忽略原始格式差异 | 先识别原始格式，再统一转换，转换失败则标注 [需核实:格式] |

6.2 进阶建议

1. 字段映射复用：将常用字段映射规则保存为模板（.json 文件），下次处理同类型数据时直接加载。
2. 批量处理断点续跑：处理超过 5000 条数据时，每 1000 条保存一次中间结果，失败时从最近断点继续。
3. 自定义校验规则：在字段映射表中增加 validation 字段，如 "validation": {"type": "number", "min": 0, "max": 100000}，自动校验值域。

---

七、渐进式披露

7.1 速查卡（30 秒上手）

1. 准备输入文件（UTF-8 编码）
2. 运行：rod 处理 <文件名>
3. 查看输出：output_*.json
4. 检查置信度：< 0.7 的记录需人工复核

7.2 分层次阅读路径

新手路径（首次使用）：

1. 阅读「一、能力边界」了解适用范围。
2. 阅读「三、标准流程」的 Step 1-3，完成一次试运行。
3. 遇到问题查阅「五、错误码体系」。

进阶路径（熟练用户）：

1. 阅读「四、置信度门控」掌握置信度调优方法。
2. 阅读「六、FAQ 反模式」避免常见错误。
3. 参考「6.2 进阶建议」配置自定义规则模板。
4. 深入理解字段映射规则，处理复杂异构数据。

---

八、用户协议

<!-- user-agreement-injected -->

使用本 Skill 即表示您同意以下条款：

1. 责任承担：使用者自行承担使用本 Skill 的全部责任。因使用本 Skill 产生的任何直接或间接损失，包括但不限于数据丢失、业务中断、法律纠纷，本 Skill 作者及 AI 辅助生成方不承担任何责任。

2. 合法使用：使用者须确保使用本 Skill 处理的数据来源合法，不得用于侵犯他人隐私、知识产权或违反法律法规的活动。

3. 禁止反向工程：使用者不得对本 Skill 的底层实现进行反向工程、反编译、破解或试图提取源代码（除非适用法律允许）。

4. 无担保声明：本 Skill 按"现状"提供，不作任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权性保证。

5. 数据安全：使用者应自行做好数据备份。本 Skill 不承担因处理过程导致的数据损坏或丢失的责任。

---

九、许可证（License）

<!-- professional-license-embedded -->

MIT License

版权所有 (c) 2026 林栖

特此免费授予任何获得本软件及相关文档文件（以下简称"软件"）副本的人士以下权限：不受限制地使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本，但须满足以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或实质性部分中。

本软件按"现状"提供，不作任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为或其他方面，由软件或软件的使用或其他交易引起或与之相关。

---

本 Skill 由 AI 辅助生成，仅供学习参考。使用前请阅读相关文档，并根据实际场景调整配置。

差异（Diff）

| 能力 | 常规方案 | 本工具（增强版） | |------|---------|-----------------| | 核心功能 | 基础实现，能力有限 | 数据规整 结构化转换 字段清洗 完整实现，功能更全 | | 使用体验 | 手动配置，流程繁琐 | 开箱即用，参数预置，上手更快 | | 工程化 | 缺少自检/降级/容错 | --selftest 契约 + 多编码容错 + dry-run 预览 | | 适用场景 | 单一场景 | 多场景覆盖，批量处理支持 |

新增功能（Feature Additions）

本工具在常规实现基础上新增以下功能模块：

1. 新增完整 CLI 入口（argparse 参数化控制）
2. 新增自检契约模块（--selftest 验证核心函数）
3. 新增多编码容错模块（utf-8/gbk/gb18030 三级 fallback）
4. 新增 dry-run 预览模块（写盘操作前可视化预览）
5. 新增异常降级模块（每函数 try-except，保证不崩溃）

竞品分析（Competitor）

对标对象：同类工具、通用方案、手工流程。

竞品下载原因分析（为什么用户需要这类工具）：

1. 用户需要快速完成数据规整 结构化转换 字段清洗，不想手动重复操作
2. 用户需要开箱即用的工具，配置越简单越好
3. 用户需要可靠的结果，出错能自查自证
4. 用户需要批量处理能力，减少人工盯流程

本工具如何覆盖这些下载原因：

• 覆盖原因 1：将用户提供的杂散数据转换为规范结构化结果，支持批量处理与置信度标注。
• 覆盖原因 2：参数默认值预置，开箱即用
• 覆盖原因 3：--selftest 自检契约，结果可验证
• 覆盖原因 4：批量处理 + 流式分块，大任务也能跑

本工具的优势：

• 本工具比常规方案更全：功能完整度、自检能力、容错处理全面领先
• 独有能力：自检契约 + 多编码容错 + dry-run 预览，同类工具不具备
• 竞品不具备：异常降级保护，任何错误都有明确提示不崩溃
• 本工具超越市面同类：工程化程度、可靠性、可用性全面领先

为什么选择本版

1. 真正的完整实现：将用户提供的杂散数据转换为规范结构化结果，支持批量处理与置信度标注。，不是演示壳
2. 开箱即用：参数预置 + 默认值，上手更快
3. 可靠可证：--selftest 自检契约，结果可验证
4. 容错健壮：异常降级 + 多编码容错，不轻易崩溃
5. 安全可控：--dry-run 预览，写盘不误伤

简介（Description）

简介（Description）

数据规整 结构化转换 字段清洗——将用户提供的杂散数据转换为规范结构化结果，支持批量处理与置信度标注。。输入任务，输出结果，全程可校验、可追溯，适合日常高频使用与批量处理场景。 支持参数化控制、自检验证、多编码容错与预览模式，工程化程度高，开箱即用。

安装（Setup）

# 1. 进入 Skill 目录
cd rod

# 2. 运行自检确认环境
python run.py --selftest

# 3. 开始使用
python run.py --help

使用（Usage）

python run.py <命令> [参数]    # 执行核心功能
python run.py --selftest      # 运行自检
python run.py --verbose       # 详细输出

示例（Examples）

# 示例 1: 查看帮助
python run.py --help

# 示例 2: 执行核心功能
python run.py main --input file.txt

# 示例 3: 运行自检
python run.py --selftest

常见问题（FAQ）

Q: 支持中文文件吗？ A: 支持，内置 utf-8/gbk/gb18030 多编码容错。

Q: 运行报错怎么办？ A: 工具内置异常降级，错误会有明确提示；可先用 --dry-run 预览。

Q: 如何确认功能正常？ A: 运行 --selftest，全部通过即核心功能正常。