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

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

goreporter 技能文档

一、能力边界与适用对象（速查卡）

1.1 核心能力清单

| 能力项 | 说明 | 支持程度 | |--------|------|----------| | 数据解析 | 从用户提供的文本、CSV、Excel、JSON、URL 中提取结构化信息 | ✅ 完整支持 | | 字段识别 | 自动识别表头、日期、数值、类别等关键字段 | ✅ 完整支持 | | 格式转换 | 将非标准格式转换为约定输出结构 | ✅ 完整支持 | | 批量处理 | 支持多文件、多批次数据的连续处理 | ✅ 完整支持 | | 置信度标注 | 对不确定字段输出 [需核实:字段名] 占位符 | ✅ 完整支持 | | 自定义模板 | 根据用户指定字段结构生成输出 | ✅ 支持（需提供模板） | | 实时数据抓取 | 从动态网页获取数据 | ⚠️ 有限支持（仅静态页面） | | 图表渲染 | 生成可视化图表文件 | ❌ 不支持（仅输出结构化数据） | | 数据清洗 | 自动修正格式错误、缺失值填充 | ❌ 不支持（需用户预处理） |

1.2 适用对象

适合：需要将报表数据标准化、结构化存储、批量转换格式的个人或团队
不适合：需要实时数据监控、复杂图表绘制、数据清洗服务的场景

1.3 输入输出规格

| 项目 | 规格 | |------|------| | 输入格式 | .csv / .xlsx / .json / .txt / URL（静态页面） | | 输出格式 | JSON（默认）/ CSV / Markdown 表格 | | 最大文件大小 | 单文件 ≤ 10MB | | 批量处理上限 | 单次 ≤ 50 个文件 | | 字段数量上限 | 单条记录 ≤ 100 个字段 |

二、触发方式与场景映射

2.1 触发词

核心触发词：报表、数据可视化、goreporter、数据报告、结构化输出、图表生成

补充触发词：数据整理、表格转换、批量导出、数据标准化

2.2 场景映射表

| 用户说（大白话） | 实际需求 | 触发动作 | |------------------|----------|----------| | "帮我把这个 Excel 转成 JSON" | 格式转换 | 解析 → 结构化 → 输出 JSON | | "这个报表里的数据帮我整理一下" | 数据标准化 | 解析 → 字段识别 → 规范化输出 | | "我有 20 个 CSV 文件要合并处理" | 批量处理 | 批量解析 → 合并 → 统一输出 | | "这个网页上的表格能提取吗" | URL 数据提取 | 抓取 → 解析 → 结构化输出 | | "帮我看看这份数据里有哪些关键信息" | 信息提取 | 解析 → 关键字段标注 → 摘要输出 |

三、标准处理流程

3.1 前置条件

文件准备：待处理文件与工作目录分离，文件名遵循 [项目名]_[日期].[格式] 规范
环境确认：确认输入文件格式在支持列表中，且大小未超限
模板确认（可选）：如需要自定义输出结构，提前提供字段模板

3.2 执行步骤

步骤 1：输入解析

输入 → 格式检测 → 编码识别 → 内容提取

格式检测：根据文件扩展名和内容特征判断类型
编码识别：自动检测 UTF-8 / GBK / Latin-1 等编码
内容提取：读取表头、数据行、元数据

步骤 2：字段识别与映射

| 字段类型 | 识别规则 | 示例 | |----------|----------|------| | 日期 | 匹配 YYYY-MM-DD / YYYY/MM/DD 等模式 | 2026-08-20 | | 数值 | 纯数字或带单位数字 | 1,234.56 / 85% | | 类别 | 文本型字段，重复值较多 | 华东区 / 华南区 | | 标识符 | 唯一值字段（ID、编号） | ORD-2026-001 |

步骤 3：结构化处理

按识别出的字段结构重组数据
对缺失字段填充 null 或 [需核实:字段名]
对格式不一致的数值统一格式（千分位、小数位）

步骤 4：置信度标注

| 置信度等级 | 判定标准 | 输出标记 | |------------|----------|----------| | 高（≥90%） | 字段完整、格式规范、无歧义 | 无标记 | | 中（70-89%） | 字段存在但格式不统一 | [需核实:字段名] | | 低（<70%） | 字段缺失或内容模糊 | [需核实:字段名] + 说明 |

步骤 5：输出生成

{
  "meta": {
    "source": "文件名或URL",
    "processed_at": "2026-08-20T14:30:00Z",
    "record_count": 128,
    "confidence": "high"
  },
  "data": [
    {
      "id": "ORD-2026-001",
      "date": "2026-08-01",
      "amount": 12500.00,
      "region": "华东区"
    }
  ]
}

3.3 输出规范

| 输出格式 | 适用场景 | 文件后缀 | |----------|----------|----------| | JSON | 程序化处理、API 对接 | .json | | CSV | 表格软件打开、数据库导入 | .csv | | Markdown | 文档嵌入、快速预览 | .md |

四、置信度门控机制

4.1 信息不足处理原则

核心原则：不编造、不猜测、明确标注

| 场景 | 处理方式 | 示例 | |------|----------|------| | 字段缺失 | 输出 [需核实:字段名] | "region": "[需核实:region]" | | 格式冲突 | 保留原始值 + 标注 | "amount": "[需核实:amount] 12,500.00" | | 编码异常 | 跳过该行 + 记录日志 | "skipped_rows": [3, 7, 12] | | 数据矛盾 | 输出全部值 + 标注 | "date": "[需核实:date] 2026-08-01 / 2026-08-02" |

4.2 二次确认触发条件

当出现以下情况时，主动向用户确认：

超过 30% 的字段需要标注 [需核实]
存在多个可能的表头行
数据量超过 10,000 条且结构不一致
用户提供的模板与数据实际结构不匹配

五、错误码体系

| 错误码 | 错误描述 | 提示话术 | 修正步骤 | |--------|----------|----------|----------| | GR-001 | 文件格式不支持 | "暂不支持该文件格式，请转换为 CSV/Excel/JSON 后重试" | 1. 转换格式 2. 重新上传 | | GR-002 | 文件大小超限 | "文件超过 10MB 限制，请拆分后处理" | 1. 拆分文件 2. 分批处理 | | GR-003 | 编码识别失败 | "无法识别文件编码，请指定编码格式" | 1. 确认编码 2. 重新提交 | | GR-004 | 字段结构不一致 | "检测到多行字段结构不一致，请检查源数据" | 1. 检查源文件 2. 统一格式 | | GR-005 | 数据量超限 | "单次处理上限为 50 个文件，请分批执行" | 1. 分批处理 2. 合并结果 | | GR-006 | URL 无法访问 | "无法访问该链接，请确认 URL 有效性" | 1. 检查链接 2. 更换数据源 | | GR-007 | 模板不匹配 | "提供的模板与数据实际结构不匹配" | 1. 调整模板 2. 使用自动识别 |

六、FAQ 反模式对照

常见坑 1：忽略数据预处理

反模式：直接处理包含大量空行、重复表头、合并单元格的原始文件

正确做法：先进行基础清洗（删除空行、合并表头、拆分合并单元格），再提交处理

常见坑 2：混淆字段类型

反模式：将日期字段当作文本处理，导致排序和筛选异常

正确做法：明确指定字段类型，或在输出后检查类型标注

常见坑 3：批量处理前未试运行

反模式：直接对 50 个文件执行批量处理，结果发现格式错误需要全部重来

正确做法：先用 1-2 个样本文件试运行，确认输出无误后再执行全量

常见坑 4：忽略置信度标注

反模式：直接使用输出结果，未检查 [需核实] 标记的字段

正确做法：处理完成后，先筛选所有带标记的字段，人工核实后再使用

常见坑 5：URL 数据源不稳定

反模式：依赖动态加载的网页数据，导致抓取结果不完整

正确做法：优先使用静态页面或 API 接口，或先下载为本地文件再处理

七、渐进式阅读路径

7.1 新手快速上手（5 分钟）

阅读「一、能力边界」了解能做什么
阅读「二、触发方式」了解如何发起请求
按「三、标准处理流程」的步骤 1-3 执行一次简单转换

7.2 进阶用户（15 分钟）

完整阅读「三、标准处理流程」所有细节
熟悉「四、置信度门控」的标注规则
掌握「五、错误码体系」的常见问题处理
了解「六、FAQ 反模式」避免常见错误

7.3 高级用户（30 分钟）

深入理解字段识别规则，自定义映射逻辑
设计自定义输出模板，对接下游系统
结合批量处理能力，构建自动化数据管道

八、使用示例

示例 1：单文件转换

用户输入：

将 sales_2026_q2.csv 转换为 JSON 格式

处理过程：

解析 CSV，识别字段：日期、区域、销售额、订单数
检测到日期格式不统一（部分为 2026-04-01，部分为 2026/04/01）
统一日期格式，标注 2 条记录需核实
输出 JSON 文件

输出摘要：

{
  "meta": {
    "source": "sales_2026_q2.csv",
    "record_count": 89,
    "confidence": "medium",
    "needs_review": 2
  }
}

示例 2：批量处理

用户输入：

处理 reports/ 目录下所有 2026 年的月度报表

处理过程：

识别 12 个 CSV 文件
试运行 1 个文件确认格式
批量执行全部文件
合并为单一 JSON 输出

输出摘要：

{
  "meta": {
    "source": "reports/2026_*.csv",
    "file_count": 12,
    "record_count": 1043,
    "confidence": "high"
  }
}

九、用户协议

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

责任承担：使用者自行承担因使用本 Skill 产生的全部责任。本 Skill 提供的数据处理结果仅供参考，不构成任何形式的专业建议或保证。
数据安全：使用者应确保提交的数据不包含敏感信息（如个人隐私、商业机密、国家秘密等）。因数据泄露或误用产生的后果由使用者自行承担。
禁止反向工程：使用者不得对本 Skill 进行反向工程、反编译、破解或试图提取源代码、算法、逻辑等底层实现。
合规使用：使用者应遵守所在地法律法规，不得将本 Skill 用于任何非法用途，包括但不限于数据造假、欺诈、侵犯他人权益等行为。
免责声明：本 Skill 按"现状"提供，不附带任何明示或暗示的保证。因使用本 Skill 产生的任何直接或间接损失，作者不承担责任。

十、许可证（License）

MIT License

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

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

文档版本：1.0.0 | 最后更新：2026-08-20 | 生成方式：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 goreporter

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

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

使用（Usage）

python run.py <命令> [参数]    # 执行核心功能
python run.py --selftest      # 运行自检
python run.py --dry-run       # 预览模式
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，全部通过即核心功能正常。

报表数据 可视化 结构化处理

goreporter 技能文档

一、能力边界与适用对象（速查卡）

1.1 核心能力清单

1.2 适用对象

1.3 输入输出规格

二、触发方式与场景映射

2.1 触发词

2.2 场景映射表

三、标准处理流程

3.1 前置条件

3.2 执行步骤

步骤 1：输入解析

步骤 2：字段识别与映射

步骤 3：结构化处理

步骤 4：置信度标注

步骤 5：输出生成

3.3 输出规范

四、置信度门控机制

4.1 信息不足处理原则

4.2 二次确认触发条件

五、错误码体系

六、FAQ 反模式对照

常见坑 1：忽略数据预处理

常见坑 2：混淆字段类型

常见坑 3：批量处理前未试运行

常见坑 4：忽略置信度标注

常见坑 5：URL 数据源不稳定

七、渐进式阅读路径

7.1 新手快速上手（5 分钟）

7.2 进阶用户（15 分钟）

7.3 高级用户（30 分钟）

八、使用示例

示例 1：单文件转换

示例 2：批量处理

九、用户协议

十、许可证（License）

MIT License

差异（Diff）

新增功能（Feature Additions）

竞品分析（Competitor）

为什么选择本版

简介（Description）

简介（Description）

安装（Setup）

使用（Usage）

示例（Examples）

常见问题（FAQ）

报表数据可视化结构化处理