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

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

OKF Skills — 数据整理与结构化输出技能

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

1.1 能做什么

| 能力项 | 说明 | 适用场景示例 | |--------|------|--------------| | 数据解析 | 从 CSV、JSON、TXT、日志等文本类数据源中提取字段 | 用户导出的订单表、服务器访问日志 | | 字段映射 | 将源数据字段名映射为统一的目标字段名 | 不同系统导出的客户信息字段名不一致 | | 格式转换 | 将非结构化文本转换为 JSON / Markdown 表格等结构化格式 | 会议纪要转任务清单、邮件内容转工单 | | 置信度标注 | 对每个输出字段标注可信程度（高/中/低） | 从 OCR 文本中抽取关键信息时 | | 批量处理 | 对同一目录下的多个文件执行相同的解析逻辑 | 月度报表批量整理 |

1.2 不能做什么

| 限制项 | 说明 | |--------|------| | 不处理二进制文件 | 图片、PDF 扫描件等需先经 OCR 转换为文本 | | 不进行语义理解 | 无法判断文本中的"隐含意图"或"言外之意" | | 不保证字段完整性 | 源数据缺失时输出 [需核实:字段名] 占位，不自动补全 | | 不执行跨文件关联 | 不自动将 A 文件与 B 文件的数据进行关联合并 | | 不修改原始文件 | 所有操作均在副本上进行，原始文件保持只读 |

1.3 适用对象

数据运营人员：需要将多来源数据统一为同一格式
业务分析师：需要从非结构化文本中提取关键指标
开发人员：需要快速将接口返回数据转换为内部数据结构
文档管理员：需要将散落的记录整理为规范表格

二、触发方式

2.1 触发词

在对话中提及以下任一词汇即可激活本技能：

okf skills（主触发词）
数据整理、信息抽取、结构化输出、格式转换
数据清洗、字段映射（补充触发词）

2.2 场景映射表

| 用户说（大白话） | 实际需求 | 本技能响应 | |------------------|----------|------------| | "帮我把这个 CSV 整理一下" | 将 CSV 解析为结构化 JSON | 执行数据解析 + 字段映射 | | "这些日志文件太乱了，能提取出关键信息吗？" | 从日志中抽取时间、级别、消息 | 执行信息抽取 + 置信度标注 | | "两个系统的导出格式不一样，能统一吗？" | 字段名映射 + 格式统一 | 执行字段映射 + 格式转换 | | "这个文件夹里所有文件都按同样方式处理" | 批量执行相同解析逻辑 | 执行批量处理流程 |

三、标准流程

3.1 前置条件

| 条件 | 要求 | 检查方式 | |------|------|----------| | 输入文件格式 | 文本类（.csv / .json / .txt / .log / .md） | 文件扩展名确认 | | 文件可读性 | 文件编码为 UTF-8 或 GBK | 打开文件预览 | | 目录结构 | 待处理文件位于同一目录 | ls 或文件管理器确认 | | 命名规范 | 文件名包含可识别的批次标识（如日期、序号） | 目视检查 | | 原始备份 | 已复制原始文件至 ./backup/ 目录 | 目录存在且文件完整 |

3.2 执行步骤

第一步：准备输入

将所有待处理文件放入同一目录（如 ./input/）
确认文件命名规范一致（如 2026-08-01_orders.csv）
创建备份目录并复制原始文件：

mkdir -p ./backup
cp ./input/* ./backup/

第二步：试运行（单样本验证）

从输入目录中选取 1 个代表性文件
执行解析并输出结果
核对以下内容：
- 目标字段是否全部映射成功
- 缺失字段是否以 [需核实:字段名] 占位
- 输出格式是否符合预期（JSON 结构 / Markdown 表格）

试运行检查表：

| 检查项 | 通过标准 | |--------|----------| | 字段映射率 | ≥ 90% 的源字段成功映射 | | 占位符使用 | 缺失字段均标注 [需核实:...] | | 格式正确性 | JSON 可解析 / Markdown 表格渲染正常 |

第三步：批量执行

确认试运行结果无误后，对全量文件执行相同逻辑
输出文件命名规则：{原文件名}_structured.json
输出文件存放于 ./output/ 目录

mkdir -p ./output
# 对每个输入文件执行解析，输出至 ./output/

第四步：校验结果

从输出目录中随机抽取 3-5 个文件
对照原始文件逐字段核对
重点检查：
- 关键字段（如金额、日期、ID）是否与源数据一致
- 置信度标注为"低"的字段是否确实存在数据质量问题
- 占位符 [需核实:...] 是否出现在合理位置

3.3 输出规范

输出 JSON 结构：

{
  "source_file": "2026-08-01_orders.csv",
  "processed_at": "2026-08-20T14:30:00Z",
  "record_count": 128,
  "records": [
    {
      "order_id": {"value": "ORD-1001", "confidence": "high"},
      "customer_name": {"value": "张三", "confidence": "high"},
      "amount": {"value": 299.00, "confidence": "high"},
      "note": {"value": "[需核实:备注字段]", "confidence": "low"}
    }
  ],
  "warnings": [
    {"field": "note", "issue": "源数据中该字段为空", "record_index": 0}
  ]
}

置信度标注规则：

| 置信度 | 判定标准 | 示例 | |--------|----------|------| | high | 源数据明确存在且格式正确 | 数字字段值在合理范围内 | | medium | 源数据存在但格式不规范 | 日期格式不统一，已做归一化 | | low | 源数据缺失或存在明显异常 | 字段为空、值超出合理范围 |

四、置信度门控

4.1 核心原则

不编造、不猜测、不补全。 当信息不足时，使用 [需核实:字段名] 占位。

4.2 触发占位符的条件

| 条件 | 示例 | 处理方式 | |------|------|----------| | 字段在源数据中不存在 | 源 CSV 没有"备注"列 | 输出 [需核实:备注] | | 字段值为空 | 某行"金额"列为空 | 输出 [需核实:金额] | | 字段值格式异常 | 日期字段为"2026/8/1"而非"2026-08-01" | 尝试归一化，若失败则输出 [需核实:日期] | | 字段值超出合理范围 | 年龄字段为 200 | 输出 [需核实:年龄] |

4.3 占位符使用规范

占位符格式固定为 [需核实:字段名]
字段名使用目标字段的标准名称
同一记录中多个字段缺失时，每个字段独立标注
输出 JSON 中，占位符字段的 confidence 固定为 "low"

五、错误码体系

| 错误码 | 错误描述 | 提示话术 | 修正步骤 | |--------|----------|----------|----------| | E001 | 输入文件不存在 | "未找到指定文件，请确认路径是否正确" | 1. 检查文件路径；2. 确认文件名拼写；3. 重新执行 | | E002 | 文件编码不支持 | "文件编码无法识别，请转换为 UTF-8 或 GBK" | 1. 使用文本编辑器转换编码；2. 重新执行 | | E003 | 字段映射失败 | "源数据中未找到目标字段对应的列" | 1. 查看源数据表头；2. 调整字段映射配置；3. 重新执行 | | E004 | 批量处理中断 | "批量处理在第 N 个文件处中断" | 1. 检查第 N 个文件格式；2. 修复后从断点继续 | | E005 | 输出目录不可写 | "无法写入输出目录，请检查权限" | 1. 检查目录权限；2. 更换输出路径；3. 重新执行 | | E006 | 源数据格式异常 | "源数据行数不一致，疑似存在脏数据" | 1. 定位异常行；2. 手动修正或跳过；3. 重新执行 |

六、FAQ 反模式

6.1 常见坑

| 坑编号 | 坑描述 | 反模式（错误做法） | 正确做法 | |--------|--------|---------------------|----------| | F01 | 跳过试运行直接批量执行 | 直接对 100 个文件执行，结果字段映射错误，全部返工 | 先对 1 个文件试运行，确认无误后再批量 | | F02 | 覆盖原始文件 | 解析后直接覆盖原文件，数据丢失无法恢复 | 始终保留 ./backup/ 备份 | | F03 | 忽略置信度标注 | 将低置信度字段当作准确值使用，导致下游分析错误 | 对 confidence: low 的字段进行人工复核 | | F04 | 字段名硬编码 | 源数据字段名变化后，解析逻辑失效 | 使用字段映射配置表，而非硬编码 | | F05 | 不校验输出 | 输出后不抽查，错误数据直接进入下游流程 | 按 3.2 第四步执行校验 |

6.2 反模式对照表

| 反模式 | 典型表现 | 后果 | 替代方案 | |--------|----------|------|----------| | "差不多就行" | 字段映射不完整，部分字段丢弃 | 下游分析缺关键数据 | 使用 [需核实:...] 占位，保留完整性 | | "先跑起来再说" | 不检查输入格式，直接执行 | 解析失败或结果错误 | 先检查前置条件，再执行 | | "一次搞定" | 不迭代，期望一次输出完美结果 | 错误率高，返工成本大 | 试运行 → 批量 → 校验，分步推进 |

七、渐进式披露

7.1 速查卡（30 秒上手）

1. 放文件 → 将待处理文件放入 ./input/
2. 备份 → cp ./input/* ./backup/
3. 试运行 → 选 1 个文件执行，检查输出
4. 批量 → 确认无误后对全部文件执行
5. 校验 → 抽查 3-5 个输出文件，核对关键字段

7.2 新手路径（首次使用）

阅读「能力边界」了解本技能能做什么、不能做什么
按照「标准流程」的五个步骤逐步执行
遇到问题时查阅「错误码体系」定位问题
执行完毕后阅读「FAQ 反模式」避免常见错误

7.3 进阶路径（熟练用户）

自定义字段映射配置，适配特定业务场景
调整置信度阈值，控制占位符触发条件
编写后处理脚本，对输出结果进行二次加工
将本技能集成到自动化流水线中，实现定时批量处理

八、参数配置参考

8.1 字段映射配置示例

{
  "field_mappings": [
    {"source": "订单号", "target": "order_id", "type": "string"},
    {"source": "客户", "target": "customer_name", "type": "string"},
    {"source": "金额", "target": "amount", "type": "number"},
    {"source": "日期", "target": "order_date", "type": "date", "format": "YYYY-MM-DD"}
  ],
  "confidence_rules": {
    "number": {"min": 0, "max": 1000000},
    "date": {"format": "YYYY-MM-DD"},
    "string": {"max_length": 500}
  }
}

8.2 置信度规则参数

| 参数 | 默认值 | 说明 | |------|--------|------| | number.min | 0 | 数值字段最小值，低于此值标记为 low | | number.max | 1000000 | 数值字段最大值，高于此值标记为 low | | date.format | YYYY-MM-DD | 日期字段标准格式，不匹配时尝试归一化 | | string.max_length | 500 | 字符串字段最大长度，超过则标记为 low |

九、用户协议

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

责任承担：使用者自行承担使用本 Skill 的全部责任。因使用本 Skill 产生的任何直接或间接损失，Skill 作者及发布平台不承担任何责任。
数据安全：使用者应确保输入数据不包含敏感个人信息或受保护数据。如因输入数据引发合规问题，由使用者自行负责。
禁止反向工程：使用者不得对本 Skill 进行反向工程、反编译、破解或试图提取底层算法。
合规使用：使用者应遵守所在国家/地区的法律法规，不得将本 Skill 用于任何非法用途。
无担保声明：本 Skill 按"现状"提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权保证。

十、许可证（License）

MIT License

MIT License

Copyright (c) 2026 DataWeaver Studio

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.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

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

差异（Diff）

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

新增功能（Feature Additions）

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

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

竞品分析（Competitor）

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

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

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

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

覆盖原因 1：将任意数据源解析为规范结构化结果，附置信度标注。
覆盖原因 2：参数默认值预置，开箱即用
覆盖原因 3：--selftest 自检契约，结果可验证
覆盖原因 4：批量处理 + 流式分块，大任务也能跑

本工具的优势：

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

为什么选择本版

真正的完整实现：将任意数据源解析为规范结构化结果，附置信度标注。，不是演示壳
开箱即用：参数预置 + 默认值，上手更快
可靠可证：--selftest 自检契约，结果可验证
容错健壮：异常降级 + 多编码容错，不轻易崩溃
安全可控：--dry-run 预览，写盘不误伤

简介（Description）

数据整理信息抽取结构化输出——将任意数据源解析为规范结构化结果，附置信度标注。。输入任务，输出结果，全程可校验、可追溯，适合日常高频使用与批量处理场景。支持参数化控制、自检验证、多编码容错与预览模式，工程化程度高，开箱即用。

安装（Setup）

# 1. 进入 Skill 目录
cd okf-skills

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

数据整理 信息抽取 结构化输出

OKF Skills — 数据整理与结构化输出技能

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

1.1 能做什么

1.2 不能做什么

1.3 适用对象

二、触发方式

2.1 触发词

2.2 场景映射表

三、标准流程

3.1 前置条件

3.2 执行步骤

第一步：准备输入

第二步：试运行（单样本验证）

第三步：批量执行

第四步：校验结果

3.3 输出规范

四、置信度门控

4.1 核心原则

4.2 触发占位符的条件

4.3 占位符使用规范

五、错误码体系

六、FAQ 反模式

6.1 常见坑

6.2 反模式对照表

七、渐进式披露

7.1 速查卡（30 秒上手）

7.2 新手路径（首次使用）

7.3 进阶路径（熟练用户）

八、参数配置参考

8.1 字段映射配置示例

8.2 置信度规则参数

九、用户协议

十、许可证（License）

MIT License

差异（Diff）

新增功能（Feature Additions）

竞品分析（Competitor）

为什么选择本版

简介（Description）

简介（Description）

安装（Setup）

使用（Usage）

示例（Examples）

常见问题（FAQ）

数据整理信息抽取结构化输出