shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

数据潮汐 清洗转换 结构化整理

tidescope

person作者: u_60e83e07hubenterprise
download下载资源包

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

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

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

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

tidescope 数据潮汐 · 结构化转换工作台

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

1.1 能做什么

| 能力项 | 说明 | 典型场景 | |--------|------|----------| | 单文件转换 | 将单个 CSV/JSON/TSV 文件转换为标准化 JSON 输出 | 处理一份销售记录表 | | 批量目录处理 | 扫描整个目录，统一转换所有符合条件的数据文件 | 整理一个季度的所有报表 | | 自定义字段映射 | 通过 mapping.json 将源字段名映射为目标字段名 | 对接不同系统的数据格式 | | 可疑数据标记 | 自动检测空值、格式异常、越界值，在输出中标记 [需核实] | 发现客户年龄为 999 的异常记录 | | 警告日志输出 | 所有检测到的问题汇总到 warnings 数组，便于追踪 | 审计数据质量时逐条核对 | | 自检模式 | 运行 --selftest 验证工具安装与配置是否正确 | 首次部署或升级后验证 |

1.2 不能做什么（明确边界）

  • 不做自动修正：检测到可疑数据只做标记，不擅自改动原始值。
  • 不做数据推断：缺失字段不会用平均值、中位数等统计量填充。
  • 不做格式转换：仅输出 JSON 结构，不输出 Excel、PDF 等其他格式。
  • 不做数据可视化：不生成图表、仪表盘等可视化内容。
  • 不做跨文件关联：批量模式下每个文件独立处理，不合并、不关联。

1.3 适用对象

| 用户类型 | 使用方式 | 预期收益 | |----------|----------|----------| | 数据分析初学者 | 学习数据清洗的基本流程 | 理解结构化输出的标准形态 | | 业务运营人员 | 日常报表整理与归档 | 快速获得统一格式的数据文件 | | 数据工程师 | 作为 ETL 流程的预处理环节 | 减少手工清洗工作量 | | 质量管理人员 | 数据质量抽检与审计 | 获得完整的警告日志用于追溯 |

二、触发方式与场景映射

2.1 触发词

| 触发词 | 使用场景 | |--------|----------| | 潮汐解析 | 需要将杂乱数据整理为有序结构时 | | 数据转换 | 从一种格式转为另一种格式时 | | 结构化输出 | 需要标准 JSON 格式的结果时 | | 数据整理 | 日常数据归档、汇总前处理 | | 数据清洗 | 发现数据中有空值、异常值需要标记时 | | 数据规整 | 多源数据统一字段命名时 | | 字段映射 | 需要自定义源字段与目标字段的对应关系时 | | 批量转换 | 一个目录下有多个文件需要统一处理时 |

2.2 大白话场景映射

| 你说的话 | 工具实际做的事 | |----------|----------------| | "帮我把这个表格整理一下" | 读取 CSV 文件，输出标准 JSON 结构 | | "这个文件里有几个空值帮我标出来" | 检测空字段，在 data 中追加 [需核实] 标记，并写入 warnings | | "我有一堆文件要统一格式" | 批量模式扫描目录，逐个转换并输出 | | "这个字段名不对，我想改一下" | 通过 mapping.json 自定义字段映射 | | "帮我检查一下这个工具能不能用" | 运行 --selftest 自检 |

三、标准工作流程

3.1 前置条件

| 条件项 | 要求 | 验证方式 | |--------|------|----------| | 工具安装 | tidescope 已正确安装 | 运行 tidescope --version 能输出版本号 | | 输入文件 | CSV/JSON/TSV 格式，编码为 UTF-8 | 用文本编辑器打开确认无乱码 | | 文件大小 | 单文件建议 < 10MB，行数 < 10000 行 | 查看文件属性 | | 目录权限 | 对 input/ 和 output/ 目录有读写权限 | 尝试创建临时文件并删除 | | 映射文件（可选） | 如使用自定义映射，需准备 mapping.json | 确认 JSON 格式合法 |

3.2 执行步骤（分步编号）

步骤 1：环境自检

tidescope --selftest

预期输出：显示工具版本、依赖库状态、配置路径，全部为 OK 状态。

步骤 2：准备输入文件

将待转换的数据文件放入 input/ 目录。建议先用小文件（< 100 行）测试。

示例 input/sample.csv：

姓名,年龄,城市,注册日期
张三,28,北京,2024-01-15
李四,,上海,2024-02-20
王五,999,广州,2024-03-10

步骤 3：执行单文件转换

tidescope convert input/sample.csv -o output/sample.json

步骤 4：检查输出结构

打开 output/sample.json，对照下方"输出规范"检查结构完整性。

步骤 5：查看警告信息

在输出 JSON 中定位 warnings 数组，逐条阅读 field、row、reason 字段。

步骤 6：处理可疑数据

回到源数据核实对应单元格，确认后选择：

  • 保留：在输出文件中删除 [需核实] 标记
  • 修正：修改源数据后重新转换
  • 删除：从源数据中移除该行后重新转换

3.3 输出规范

输出文件为 JSON 格式，顶层结构如下：

{
  "meta": {
    "tool": "tidescope",
    "version": "1.0.0",
    "source_file": "input/sample.csv",
    "converted_at": "2026-08-19T10:30:00Z",
    "row_count": 3,
    "column_count": 4
  },
  "data": [
    {
      "姓名": "张三",
      "年龄": 28,
      "城市": "北京",
      "注册日期": "2024-01-15"
    },
    {
      "姓名": "李四",
      "年龄": "[需核实:年龄]",
      "城市": "上海",
      "注册日期": "2024-02-20"
    },
    {
      "姓名": "王五",
      "年龄": "[需核实:年龄]",
      "城市": "广州",
      "注册日期": "2024-03-10"
    }
  ],
  "warnings": [
    {
      "field": "年龄",
      "row": 2,
      "reason": "字段为空"
    },
    {
      "field": "年龄",
      "row": 3,
      "reason": "数值超出合理范围（0-120）"
    }
  ]
}

字段说明

| 字段 | 类型 | 说明 | |------|------|------| | meta | 对象 | 元数据，包含工具信息、源文件路径、转换时间、行列数 | | data | 数组 | 转换后的数据行，每行为一个对象 | | warnings | 数组 | 警告列表，每条包含 field（字段名）、row（行号，从 1 开始）、reason（原因描述） |

可疑数据标记规则

| 情况 | 处理方式 | 标记格式 | |------|----------|----------| | 字段为空 | 保留空值，追加标记 | "[需核实:字段名]" | | 数值越界 | 保留原始值，追加标记 | "[需核实:字段名]" | | 格式异常（如日期格式错误） | 保留原始值，追加标记 | "[需核实:字段名]" | | 类型不匹配（如字符串列中出现数字） | 保留原始值，追加标记 | "[需核实:字段名]" |

四、置信度门控机制

4.1 基本原则

不编造、不猜测、不填充。 当遇到以下情况时，输出 [需核实:字段名] 占位符，绝不自行推断：

| 场景 | 处理方式 | 示例 | |------|----------|------| | 字段值为空 | 保留空值并标记 | "年龄": "[需核实:年龄]" | | 数值超出合理范围 | 保留原值并标记 | "年龄": "[需核实:年龄]"（原值为 999） | | 日期格式无法解析 | 保留原值并标记 | "注册日期": "[需核实:注册日期]" | | 枚举值不在预期集合内 | 保留原值并标记 | "城市": "[需核实:城市]"（原值为 "未知"） |

4.2 合理范围默认值

| 字段类型 | 默认合理范围 | 可配置 | |----------|--------------|--------| | 年龄 | 0 - 120 | 是（通过 mapping.json） | | 日期 | 1900-01-01 至 当前日期 | 是 | | 百分比 | 0 - 100 | 是 | | 金额 | 0 - 10^9 | 是 |

4.3 处理流程

  1. 转换时自动检测可疑数据
  2. 在 data 中保留原始值，但追加 [需核实] 标记
  3. 在 warnings 数组中记录详细信息
  4. 由使用者人工确认后决定保留、修正或删除

五、错误码体系

5.1 错误码总表

| 错误码 | 含义 | 提示话术 | 修正步骤 | |--------|------|----------|----------| | E001 | 文件不存在 | "找不到输入文件，请检查路径是否正确" | 1. 确认文件路径；2. 检查文件名大小写；3. 确认文件是否在 input/ 目录下 | | E002 | 文件格式不支持 | "仅支持 CSV、JSON、TSV 格式" | 1. 确认文件扩展名；2. 将文件转换为支持的格式 | | E003 | 文件编码错误 | "文件编码不是 UTF-8，请转换编码" | 1. 用文本编辑器打开；2. 另存为 UTF-8 编码 | | E004 | CSV 解析失败 | "CSV 格式错误，请检查引号和分隔符" | 1. 检查是否有多余引号；2. 确认分隔符是否为逗号；3. 检查是否有未闭合的引号 | | E005 | JSON 解析失败 | "JSON 格式错误，请检查括号和逗号" | 1. 用 JSON 校验工具检查；2. 确认所有键值对格式正确 | | E006 | 输出目录不可写 | "无法写入输出目录，请检查权限" | 1. 确认 output/ 目录存在；2. 检查目录写权限 | | E007 | 映射文件格式错误 | "mapping.json 格式错误，请检查" | 1. 用 JSON 校验工具检查；2. 确认映射关系格式正确 | | E008 | 字段映射冲突 | "映射字段与已有字段冲突" | 1. 检查 mapping.json 中的目标字段名；2. 避免与源字段名重复 | | E009 | 文件过大 | "文件超过处理上限（10000 行）" | 1. 拆分文件；2. 使用批量模式分批处理 | | E010 | 未知错误 | "发生未知错误，请查看日志" | 1. 查看错误日志；2. 联系技术支持 |

5.2 错误处理流程

遇到错误
  ↓
查看错误码
  ↓
阅读提示话术
  ↓
按修正步骤操作
  ↓
重新运行命令
  ↓
若仍失败 → 查看详细日志（--debug 参数）

六、FAQ 反模式对照

6.1 常见坑与正确做法

| 常见坑（反模式） | 问题说明 | 正确做法 | |------------------|----------|----------| | 坑 1：直接修改输出文件 | 手动编辑输出 JSON 中的 [需核实] 标记，但源数据未变 | 修改源数据后重新转换，保持数据可追溯 | | 坑 2：忽略 warnings | 只看 data 部分，不看 warnings，导致异常数据未被发现 | 每次转换后先看 warnings，逐条确认 | | 坑 3：用 Excel 打开输出文件 | Excel 打开 JSON 会破坏格式，导致后续处理失败 | 用文本编辑器或代码读取 JSON 文件 | | 坑 4：批量模式不检查中间结果 | 批量处理时只关心最终输出，不检查每个文件的警告 | 批量处理后逐个检查每个输出文件的 warnings | | 坑 5：映射文件字段名写错 | mapping.json 中目标字段名与源字段名混淆 | 仔细核对映射关系，先在小文件上测试 |

6.2 反模式对照表

| 反模式 | 后果 | 正确模式 | |--------|------|----------| | 遇到空值就删行 | 数据量减少，信息丢失 | 标记后人工确认 | | 遇到异常值就改成 0 | 数据失真，误导分析 | 标记后人工确认 | | 批量处理不设断点 | 错误扩散到所有输出文件 | 先小批量测试，再全量处理 | | 自定义映射不测试 | 字段错位，数据混乱 | 先用 10 行小文件验证映射 |

七、渐进式披露：分层次阅读路径

7.1 新手速查卡（第一层）

你只需要知道这 3 步：

  1. 把文件放进 input/ 目录
  2. 运行 tidescope convert input/你的文件.csv -o output/结果.json
  3. 打开 output/结果.json，先看 warnings 部分

记住 3 个原则：

  • 工具只标记，不修改
  • 看到 [需核实] 就要人工确认
  • 修改源数据后重新转换，不要直接改输出

7.2 进阶用户路径（第二层）

你需要掌握：

  • 自定义字段映射：创建 mapping.json 文件
  • 批量模式：tidescope batch input/ -o output/
  • 警告分析：编写脚本读取 warnings 数组，建立数据质量监控流程
  • 合理范围配置：在 mapping.json 中自定义字段的合理范围

进阶示例：

创建 mapping.json：

{
  "field_mapping": {
    "客户姓名": "name",
    "年龄": "age",
    "所在城市": "city"
  },
  "range_rules": {
    "age": {"min": 0, "max": 120}
  }
}

批量模式：

tidescope batch input/ -o output/ --mapping mapping.json

脚本读取输出：

import json

with open("output/sample.json", "r", encoding="utf-8") as f:
    result = json.load(f)

for warning in result["warnings"]:
    print(f"字段: {warning['field']}, 行号: {warning['row']}, 原因: {warning['reason']}")

7.3 高级用户路径（第三层）

你需要理解：

  • 工具的内部结构：meta 元数据、data 数据体、warnings 警告数组
  • 数据质量监控流程：定期运行转换，对比 warnings 变化趋势
  • 与其他工具的集成：将输出 JSON 作为下游分析流程的输入

八、用户协议

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

  1. 责任承担：使用者应自行承担使用本工具的全部责任。因使用本工具产生的任何直接或间接损失，工具作者不承担任何责任。

  2. 数据准确性：本工具仅提供数据转换和标记功能，不对数据的准确性、完整性、可靠性作任何承诺。使用者应对数据内容自行负责。

  3. 禁止反向工程：禁止对本工具进行反向工程、反编译、破解或试图提取源代码（除非适用法律允许）。本工具的结构、算法、实现细节均受版权保护。

  4. 合规使用：使用者应遵守所在地法律法规，不得将本工具用于任何非法目的，包括但不限于：数据欺诈、身份盗窃、侵犯隐私、传播恶意内容等。

  5. 修改与分发：在遵守 MIT 许可证的前提下，您可以修改和分发本工具，但需保留原始版权声明。

  6. 免责声明：本工具按"原样"提供，不附带任何明示或暗示的保证。工具作者不对数据的准确性、完整性、可靠性作任何承诺。

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

九、许可证（License）

本工具基于 MIT 许可证开源发布。

MIT 许可证全文

MIT License


## 差异（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）

```bash
# 1. 进入 Skill 目录
cd tidescope

# 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 --selftest file.txt

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

常见问题（FAQ）

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

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

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

许可证（License）

MIT License

Copyright (c) 2026 SkillForge Lab

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
<!-- professional-license-embedded -->