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

数据转换 插件速配 结构化输出

将任意数据、文件或URL转换为结构化结果，并标注置信度。

person作者: user_a10ab3adhubcommunity
download下载资源包

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

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

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

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

fastagent-plugins 技能手册

一、能力边界：一页纸速查卡

1.1 能做什么

| 能力项 | 说明 | 适用场景示例 | |--------|------|--------------| | 文件转结构化 | 将 CSV、JSON、TXT、Markdown 等文件解析为统一结构 | 日志转表格、配置转 JSON Schema | | URL 内容提取 | 抓取网页正文、API 返回内容并结构化 | 新闻列表转条目、接口调试输出规范化 | | 字段置信度标注 | 对每个输出字段附加置信度评分（0-1） | 数据清洗时标记可疑值、OCR 结果筛选 | | 批量一致性处理 | 对同目录下多文件按同一规则转换 | 月度报表合并、多来源数据统一格式 | | 试运行校验 | 先跑单样本核对结构，再全量执行 | 新数据源接入时的安全验证 |

1.2 不能做什么

  • 不能理解语义：仅做格式转换，不做情感分析、意图判断或内容生成。
  • 不能保证数据正确性：源数据本身的错误会原样传递，仅通过置信度提示风险。
  • 不能处理加密或二进制专有格式：如 .docx 内部 XML、.xlsx 二进制需先导出为 CSV。
  • 不能跨网络访问内网资源：URL 仅限公网可访问地址。

1.3 适用对象

  • 需要快速将散乱数据整理为统一格式的运营人员。
  • 需要批量处理导入数据的开发人员。
  • 需要定期将外部数据源同步到内部系统的数据工程师。

二、触发方式：场景映射表

| 用户说（大白话） | 触发词命中 | 实际执行动作 | |------------------|------------|--------------| | "帮我把这个 CSV 转成标准格式" | 数据转换 | 解析 CSV → 输出结构化 JSON + 置信度 | | "这个文件夹里的文件都处理一下" | 批量处理 | 遍历目录 → 逐文件转换 → 汇总结果 | | "看看这个网页里有什么数据" | 结构化输出 | 抓取 URL → 提取正文 → 输出条目列表 | | "这个数据靠谱吗？" | 插件速配 | 检查字段置信度 → 标注低置信度项 | | "先跑一个试试" | 试运行 | 单样本执行 → 输出结构预览 |

三、标准流程

3.1 前置条件

| 条件 | 要求 | 检查方式 | |------|------|----------| | 文件目录 | 待处理文件已放入同一目录 | ls 确认文件存在 | | 命名规范 | 文件名前缀一致（如 data_2024_*.csv） | ls | grep 前缀 | | 网络权限 | URL 可公网访问 | curl -I <url> 返回 200 | | 依赖环境 | Python 3.8+，已安装 requests、pandas | python --version |

3.2 执行步骤（分步编号）

  1. 输入确认：明确输入类型（文件/URL/原始数据），记录源路径。
  2. 单样本试运行： 
    python fastagent_plugins.py --input sample.csv --output preview.json
    检查输出字段是否完整，置信度是否合理。
  3. 批量执行： 
    python fastagent_plugins.py --input ./data_dir/ --output ./results/ --batch
    保留原始文件备份（自动在 ./backup/ 下复制）。
  4. 结果校验：随机抽取 5% 输出条目，与源数据逐字段比对。
  5. 输出交付：生成 summary.json（含处理统计）和 converted/ 目录。

3.3 输出规范

{
  "schema_version": "1.0",
  "processed_at": "2026-08-20T14:30:00Z",
  "items": [
    {
      "id": "001",
      "fields": {
        "name": {"value": "张三", "confidence": 0.98},
        "age": {"value": 28, "confidence": 0.85},
        "email": {"value": "[需核实:email]", "confidence": 0.0}
      },
      "source": "data_2024_01.csv"
    }
  ],
  "stats": {"total": 100, "low_confidence": 3, "failed": 0}
}

四、置信度门控

4.1 置信度评分规则

| 置信度 | 含义 | 触发条件 | |--------|------|----------| | 0.9 - 1.0 | 高可信 | 字段类型匹配、值在预期范围内、无缺失 | | 0.6 - 0.89 | 中可信 | 类型正确但值异常（如年龄 200）、格式不规范 | | 0.0 - 0.59 | 低可信 | 字段缺失、类型不匹配、解析失败 |

4.2 信息不足处理

当源数据缺失或无法解析时，禁止编造。输出占位符 [需核实:字段名]，置信度置 0。

示例：

{"phone": {"value": "[需核实:phone]", "confidence": 0.0}}

4.3 置信度调整参数

| 参数 | 默认值 | 说明 | |------|--------|------| | --min-confidence | 0.6 | 低于此值的字段标记为警告 | | --strict-mode | false | 开启后低置信度条目直接跳过 | | --confidence-threshold | 0.8 | 批量处理时高置信度条目的判定线 |

五、错误码体系

| 错误码 | 含义 | 提示话术 | 修正步骤 | |--------|------|----------|----------| | E001 | 文件不存在 | "未找到指定文件，请检查路径" | 确认路径正确，ls 验证 | | E002 | 文件格式不支持 | "仅支持 CSV/JSON/TXT/Markdown" | 转换格式或导出为 CSV | | E003 | URL 无法访问 | "URL 返回 404 或超时" | 检查 URL 拼写，确认网络连通 | | E004 | 字段解析失败 | "第 X 行第 Y 列无法解析" | 查看源数据，修复格式错误 | | E005 | 批量处理中断 | "第 X 个文件处理失败，已跳过" | 单独处理失败文件，查看错误日志 | | E006 | 输出目录无权限 | "无法写入输出目录" | 修改目录权限或更换路径 |

六、FAQ 反模式

常见坑 1：直接全量处理

  • 反模式：跳过试运行，直接对 1000 个文件执行批量。
  • 后果：格式错误被放大，产出大量无效数据。
  • 正确做法：先跑 1 个样本，确认结构后再全量。

常见坑 2：忽略置信度

  • 反模式：不检查置信度，直接使用所有字段值。
  • 后果：低质量数据混入下游流程。
  • 正确做法：设置 --min-confidence 0.6，对警告字段人工复核。

常见坑 3：覆盖原始文件

  • 反模式：输出直接覆盖源文件。
  • 后果：转换失败后原始数据丢失。
  • 正确做法：输出到独立目录，保留备份。

常见坑 4：URL 不加超时

  • 反模式：抓取 URL 时不设置超时。
  • 后果：网络卡死导致进程挂起。
  • 正确做法：设置 --timeout 10（秒）。

常见坑 5：批量中断不记录

  • 反模式：批量失败后不查看错误日志。
  • 后果：部分文件未处理却误以为全部完成。
  • 正确做法：检查 error.log，对失败项重跑。

七、渐进式披露

7.1 速查卡（新手必读）

1. 放文件 → 2. 跑样本 → 3. 看输出 → 4. 跑批量 → 5. 查日志
命令模板：
  python fastagent_plugins.py --input <文件> --output <目录> [--batch]
关键参数：
  --min-confidence 0.6   # 低置信度警告线
  --strict-mode          # 跳过低置信度条目
  --timeout 10           # URL 超时秒数

7.2 进阶路径（有经验用户）

  • 自定义字段映射：通过 --field-map 指定源字段到目标字段的映射关系。
  • 多级置信度策略：不同字段使用不同置信度阈值（--field-threshold name=0.9,age=0.7）。
  • 增量处理：使用 --incremental 只处理新增文件（基于文件修改时间）。
  • 插件扩展：在 plugins/ 目录下添加自定义解析器，实现特殊格式支持。

八、用户协议

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

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

  1. 责任承担：使用者自行承担因使用本 Skill 产生的全部责任。包括但不限于数据准确性、合规性、业务影响等。本 Skill 提供的是工具和指导，不构成任何形式的保证。

  2. 禁止反向工程：不得对本 Skill 的代码、逻辑、算法进行反向工程、反编译、破解或试图提取源代码（除非适用法律允许）。

  3. 数据安全：使用者需自行确保输入数据的合法性、隐私性和安全性。本 Skill 不承担数据泄露或违规处理的责任。

  4. 修改与分发：允许在遵守 MIT 许可证的前提下修改和分发，但需保留原始版权声明。

  5. 免责声明：本 Skill 按"原样"提供，不附带任何明示或暗示的担保。

九、许可证（License）

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

MIT License

Copyright (c) 2026 LingDataWorks

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）

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

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

竞品分析（Competitor）

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

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

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

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

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

本工具的优势：

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

为什么选择本版

  1. 真正的完整实现：将任意数据、文件或URL转换为结构化结果，并标注置信度。，不是演示壳
  2. 开箱即用：参数预置 + 默认值，上手更快
  3. 可靠可证：--selftest 自检契约，结果可验证
  4. 容错健壮：异常降级 + 多编码容错，不轻易崩溃
  5. 安全可控：--dry-run 预览，写盘不误伤

简介（Description）

简介（Description）

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

安装（Setup）

# 1. 进入 Skill 目录
cd fastagent-plugins

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

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

使用（Usage）

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

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