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

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

scripd — 批量数据转换与结构化提取工具

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

1.1 能做什么

| 能力项 | 说明 | 示例 | |--------|------|------| | 批量文件转换 | 将同一目录下的多个文件按统一规则转换为目标格式 | 将 100 个 CSV 文件转为 JSON | | 结构化提取 | 从非结构化文本（日志、网页、PDF 文本）中抽取关键字段 | 从日志中提取时间戳、错误码、耗时 | | URL 数据抓取 | 从指定 URL 获取数据并转换为结构化结果 | 抓取 API 返回的 JSON 并整理为表格 | | 自定义输出格式 | 支持嵌套 JSON、多表关联、自定义字段映射 | 将扁平 CSV 转为嵌套 JSON 树 | | 批量重命名与预处理 | 统一文件命名规范，清洗脏数据 | 将 report final (3).csv 改为 report_2024-01-15.csv |

1.2 不能做什么

| 限制项 | 说明 | |--------|------| | 不支持非文本文件 | 图片、音频、视频等二进制文件无法直接转换 | | 不处理加密文件 | 需要先解密才能处理 | | 不自动理解语义 | 字段映射需要人工配置规则，不进行语义推断 | | 不保证数据准确性 | 转换结果需人工抽检，工具不负责数据质量 | | 不支持实时流式处理 | 仅支持批量离线处理，不适用于实时数据管道 |

1.3 适用对象

数据分析师：需要将多源数据统一格式后进行分析
运维工程师：批量处理日志文件，提取关键指标
业务运营：将导出报表转换为系统可识别的格式
后端开发者：快速搭建数据转换流水线

二、触发方式

2.1 触发词

当你的需求包含以下关键词时，本 Skill 适用：

| 触发词 | 场景示例 | |--------|----------| | scripd | "用 scripd 把这批文件转一下" | | 数据转换 | "我需要把 Excel 转成 JSON" | | 结构化提取 | "从这些日志里提取错误码和耗时" | | 批量处理 | "这 200 个文件都要统一格式" | | 格式转换 | "CSV 转 Parquet 怎么做" | | 数据清洗 | "把这些脏数据整理成规范格式" |

2.2 场景映射表

| 你的需求（大白话） | 对应操作 | |-------------------|----------| | "我有一堆 CSV 文件，想合并成一个 JSON" | 批量转换 + 合并输出 | | "这个网页表格我想存成 Excel" | URL 抓取 + 格式转换 | | "日志里我想只保留报错的行" | 结构化提取 + 过滤规则 | | "这些文件名太乱了，帮我整理下" | 批量重命名 | | "我想每周自动跑一遍这个转换" | 固化流程 + 定时执行 |

三、标准流程

3.1 前置条件

| 条件 | 要求 | 检查方法 | |------|------|----------| | 输入目录 | 所有待处理文件放在同一目录（如 ./input/） | ls ./input/ 确认文件齐全 | | 文件命名 | 符合 前缀_日期.扩展名 规范 | 不符合的先执行重命名 | | 环境依赖 | Python 3.8+，已安装 scripd 包 | scripd --version | | 输出目录 | ./output/ 目录存在且有写权限 | mkdir -p ./output/ |

3.2 执行步骤

Step 1：准备输入文件

将所有待处理文件放入同一目录，确认命名规范：

# 规范命名示例
data_2024-01-15.csv
data_2024-01-16.csv
data_2024-01-17.csv

# 不规范命名示例（需先重命名）
final report (3).csv
data_15Jan.csv

若命名混乱，先统一重命名：

# 批量重命名示例：将任意名称改为 data_日期.csv
scripd rename --input ./input/ --pattern "data_{date}.csv"

Step 2：选取样本试运行

选取一个代表性文件作为样本，执行转换命令：

# 示例：将 CSV 转为 JSON
scripd convert --input ./input/data_2024-01-15.csv --output ./output/data_2024-01-15.json --format json

观察输出结构，核对以下内容：

| 核对项 | 检查内容 | |--------|----------| | 字段完整性 | 源文件所有字段是否都出现在输出中 | | 数据类型 | 数字、日期、字符串类型是否正确 | | 嵌套结构 | 嵌套 JSON 的层级是否符合预期 | | 空值处理 | 空字段是否按规范输出（JSON 用 null） |

Step 3：备份原始文件

批量执行前务必备份：

cp -r input/ backup/

Step 4：执行批量转换

# 批量转换所有 CSV 文件
scripd convert --input ./input/*.csv --output ./output/ --format json

# 记录执行日志
scripd convert --input ./input/*.csv --output ./output/ --format json --log ./logs/convert.log

执行日志应包含：处理文件数、成功数、失败数、失败原因。

Step 5：抽查校验结果

随机抽取 5-10 条输出记录，与源文件逐字段比对：

| 校验项 | 方法 | |--------|------| | 字段一致性 | 随机选 3 个字段，逐一比对源文件与输出 | | 关键字段 | ID、金额、日期等核心字段必须完全一致 | | 重复检查 | 确认无重复记录（按 ID 去重检查） | | 遗漏检查 | 确认源文件记录数 = 输出记录数 |

3.3 输出规范

| 项目 | 规范 | |------|------| | 编码 | UTF-8 | | 换行 | LF（Unix 风格） | | 日期格式 | YYYY-MM-DD | | 时间格式 | HH:mm:ss | | 空值（JSON） | null | | 空值（CSV） | 空字符串 | | 数字格式 | 不使用千分位分隔符 | | 文件命名 | 输出前缀_日期_批次.扩展名 |

示例输出文件命名：

converted_2024-01-15_batch01.json
converted_2024-01-15_batch02.json

四、置信度门控

4.1 信息不足时的处理

当遇到以下情况，不得编造数据，必须输出占位符：

| 场景 | 输出占位符 | 说明 | |------|-----------|------| | 源文件字段缺失 | [需核实:字段名] | 该字段在源文件中不存在 | | 数据格式不明确 | [需核实:格式] | 无法确定日期/数字的格式 | | 映射规则未定义 | [需核实:映射] | 源字段与目标字段的对应关系未配置 | | 数据超出预期范围 | [需核实:值域] | 数值超出预设的合理范围 |

4.2 置信度分级

| 置信度 | 条件 | 处理方式 | |--------|------|----------| | 高（≥95%） | 所有字段匹配，类型正确，无异常值 | 正常输出 | | 中（80-94%） | 少量字段需人工确认 | 输出 + 标注需确认字段 | | 低（<80%） | 多个字段不匹配或数据异常 | 中止转换，输出错误报告 |

五、错误码体系

| 错误码 | 含义 | 提示话术 | 修正步骤 | |--------|------|----------|----------| | E001 | 输入文件不存在 | "未找到输入文件，请检查路径" | 1. 确认文件路径正确 2. 检查文件名大小写 | | E002 | 文件格式不支持 | "不支持该文件格式，请转换为 CSV/JSON/XML" | 1. 查看支持格式列表 2. 先转换源文件格式 | | E003 | 字段映射失败 | "源字段与目标字段不匹配" | 1. 检查字段名拼写 2. 重新配置映射规则 | | E004 | 输出目录无权限 | "无法写入输出目录，请检查权限" | 1. 确认目录存在 2. 修改目录权限 | | E005 | 数据格式错误 | "日期格式不符合 YYYY-MM-DD 规范" | 1. 检查源数据格式 2. 配置格式转换规则 | | E006 | 批量处理中断 | "第 5 个文件处理失败，已停止" | 1. 查看错误日志 2. 修复问题后重试 | | E007 | 编码错误 | "文件编码不是 UTF-8，无法解析" | 1. 转换文件编码 2. 指定源文件编码 |

六、FAQ 反模式

6.1 常见坑

| 坑 | 反模式（错误做法） | 正模式（正确做法） | |----|-------------------|-------------------| | 跳过试运行 | 直接对全量文件执行转换 | 先跑 1 个文件试运行，确认无误后再批量执行 | | 忽略备份 | 直接覆盖原始文件 | 执行前备份原始文件到 backup/ 目录 | | 不校验结果 | 转换完成后不检查输出 | 随机抽取 5-10 条记录与源文件比对 | | 命名随意 | 输出文件命名无规律 | 按 输出前缀_日期_批次.扩展名 规范命名 | | 忽略日志 | 不记录执行过程 | 记录处理文件数、成功数、失败数 |

6.2 反模式对照表

反模式 1：盲目信任转换结果

❌ 错误：转换完成后直接使用，不校验
✅ 正确：随机抽检 5-10 条记录，核对关键字段

反模式 2：文件散落多处

❌ 错误：文件分散在多个目录，转换时遗漏
✅ 正确：所有待处理文件放入同一目录

反模式 3：不配置字段映射

❌ 错误：直接转换，不指定字段对应关系
✅ 正确：先配置字段映射规则（重命名、类型转换、值映射）

反模式 4：忽略异常处理

❌ 错误：遇到错误文件直接跳过，不记录
✅ 正确：记录失败原因，统一处理后重试

七、渐进式披露

7.1 速查卡（30 秒上手）

1. 文件放同一目录
2. 先跑 1 个文件试运行
3. 核对字段和格式
4. 备份原始文件
5. 批量执行
6. 抽查校验结果

7.2 分层次阅读路径

新手路径（首次使用）：

阅读「一、能力边界」了解能做什么
阅读「三、标准流程」的速查卡
按「3.2 执行步骤」操作一遍
遇到问题查「五、错误码体系」

进阶路径（熟练用户）：

阅读「3.3 输出规范」了解输出标准
阅读「四、置信度门控」理解数据质量判断
阅读「六、FAQ 反模式」避免常见错误
自定义字段映射和格式转换规则
将转换流程固化为可重复执行的模板

专家路径（深度定制）：

设计自定义输出格式（嵌套 JSON、多表关联）
配置复杂的字段映射规则（字段重命名、类型转换、值映射）
设置数据质量规则（必填字段、值域检查、格式校验）
集成到自动化流水线（定时执行、异常告警）

八、自定义配置示例

8.1 字段映射配置

{
  "field_mapping": [
    {
      "source": "customer_name",
      "target": "customer.fullName",
      "type": "string",
      "transform": "trim"
    },
    {
      "source": "order_date",
      "target": "order.date",
      "type": "date",
      "format": "YYYY-MM-DD"
    },
    {
      "source": "amount",
      "target": "order.total",
      "type": "number",
      "transform": "round(2)"
    }
  ]
}

8.2 数据质量规则

{
  "quality_rules": [
    {
      "field": "order_id",
      "required": true,
      "unique": true,
      "pattern": "^ORD-\\d{6}$"
    },
    {
      "field": "amount",
      "required": true,
      "min": 0,
      "max": 1000000
    },
    {
      "field": "order_date",
      "required": true,
      "format": "YYYY-MM-DD",
      "range": ["2020-01-01", "2025-12-31"]
    }
  ]
}

8.3 自动化流水线配置

pipeline:
  name: daily_data_conversion
  schedule: "0 2 * * *"  # 每天凌晨 2 点执行
  steps:
    - name: backup
      command: "cp -r input/ backup/"
    - name: convert
      command: "scripd convert --input ./input/*.csv --output ./output/ --format json"
    - name: validate
      command: "scripd validate --input ./output/*.json --rules ./rules.json"
    - name: notify
      command: "send_alert --status $? --log ./logs/convert.log"

九、用户协议

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

责任承担：使用者自行承担使用本 Skill 产生的全部责任。包括但不限于数据转换结果准确性、数据丢失、业务中断等风险。
数据安全：使用者应确保待处理数据不包含敏感信息，或已获得合法处理权限。本 Skill 不承担数据泄露责任。
禁止反向工程：使用者不得对本 Skill 进行反向工程、反编译、破解或试图获取源代码。
合规使用：使用者应遵守所在地法律法规，不得将本 Skill 用于非法用途。
无担保声明：本 Skill 按"现状"提供，不附带任何明示或暗示的担保。

十、许可证（License）

MIT License

特此免费授予任何获得本软件及相关文档文件（以下简称"软件"）副本的人士处理软件的权限，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向提供软件的人士授权这样做，但须满足以下条件：

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

本 Skill 由 AI 辅助生成，仅供参考。使用前请阅读相关文档。

差异（Diff）

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

新增功能（Feature Additions）

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

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

竞品分析（Competitor）

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

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

用户需要快速完成批量数据转换结构化提取格式定制，不想手动重复操作
用户需要开箱即用的工具，配置越简单越好
用户需要可靠的结果，出错能自查自证
用户需要批量处理能力，减少人工盯流程

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

覆盖原因 1：将文件、URL或数据批量转换为结构化结果，支持自定义格式。
覆盖原因 2：参数默认值预置，开箱即用
覆盖原因 3：--selftest 自检契约，结果可验证
覆盖原因 4：批量处理 + 流式分块，大任务也能跑

本工具的优势：

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

为什么选择本版

真正的完整实现：将文件、URL或数据批量转换为结构化结果，支持自定义格式。，不是演示壳
开箱即用：参数预置 + 默认值，上手更快
可靠可证：--selftest 自检契约，结果可验证
容错健壮：异常降级 + 多编码容错，不轻易崩溃
安全可控：--dry-run 预览，写盘不误伤

简介（Description）

批量数据转换结构化提取格式定制——将文件、URL或数据批量转换为结构化结果，支持自定义格式。。输入任务，输出结果，全程可校验、可追溯，适合日常高频使用与批量处理场景。支持参数化控制、自检验证、多编码容错与预览模式，工程化程度高，开箱即用。

安装（Setup）

# 1. 进入 Skill 目录
cd scripd

# 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，全部通过即核心功能正常。

批量数据转换 结构化提取 格式定制

scripd — 批量数据转换与结构化提取工具

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

1.1 能做什么

1.2 不能做什么

1.3 适用对象

二、触发方式

2.1 触发词

2.2 场景映射表

三、标准流程

3.1 前置条件

3.2 执行步骤

3.3 输出规范

四、置信度门控

4.1 信息不足时的处理

4.2 置信度分级

五、错误码体系

六、FAQ 反模式

6.1 常见坑

6.2 反模式对照表

七、渐进式披露

7.1 速查卡（30 秒上手）

7.2 分层次阅读路径

八、自定义配置示例

8.1 字段映射配置

8.2 数据质量规则

8.3 自动化流水线配置

九、用户协议

十、许可证（License）

差异（Diff）

新增功能（Feature Additions）

竞品分析（Competitor）

为什么选择本版

简介（Description）

简介（Description）

安装（Setup）

使用（Usage）

示例（Examples）

常见问题（FAQ）

批量数据转换结构化提取格式定制