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

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

jsawesome 技能文档

一、能力边界（速查卡）

1.1 能做与不能做

| 维度 | 能做 ✅ | 不能做 ❌ | |------|--------|----------| | 输入处理 | 用户提供的数据文件、URL、文本片段 | 无法主动抓取未授权的网络资源 | | 信息提取 | 识别关键字段、实体、结构化要素 | 不进行语义猜测或主观推断 | | 输出生成 | 按约定格式输出 JSON/CSV/Markdown 表格 | 不输出未经验证的结论性内容 | | 批量处理 | 支持多文件、多条目批量转换 | 不处理超过 1000 条的单批数据（性能边界） | | 自定义格式 | 支持字段映射与格式模板定制 | 不支持动态代码生成或脚本注入 | | 置信度标注 | 对每个输出字段标注置信度等级 | 不隐瞒低置信度或缺失信息 |

1.2 适用对象

数据分析师：需要将杂乱的日志、报表转换为统一结构
运营人员：批量整理用户反馈、工单信息
开发者：需要快速将外部数据接入自有系统
研究者：对文献、问卷数据进行结构化整理

1.3 输入输出规格

| 项目 | 规格 | |------|------| | 输入来源 | 本地文件（.txt/.csv/.json/.xlsx）、URL、剪贴板文本 | | 输出格式 | JSON（默认）、CSV、Markdown 表格 | | 字段结构 | { "id": string, "content": string, "fields": {...}, "confidence": number, "source": string } | | 置信度范围 | 0.0 ~ 1.0，低于 0.6 时自动标记 [需核实] |

二、触发方式

2.1 触发词

核心触发词：jsawesome
同义场景词：数据转换、结构化输出、批量处理、数据解析

2.2 场景映射表

| 用户说（大白话） | 实际触发动作 | |-----------------|-------------| | "帮我把这些数据整理一下" | 解析输入 → 识别字段 → 结构化输出 | | "这个文件里的信息提取出来" | 读取文件 → 关键信息抽取 → 格式化输出 | | "批量处理一下这些记录" | 遍历多条输入 → 逐条转换 → 汇总输出 | | "转成 JSON 格式给我" | 按 JSON 模板重组字段 → 输出 | | "这个数据靠谱吗？" | 输出时附带置信度评估与说明 |

三、标准处理流程

3.1 前置条件

输入文件与工作目录在同一路径下，文件名不含特殊字符
确认输入编码为 UTF-8（非 UTF-8 需提前转码）
明确输出格式需求（默认 JSON）
单批数据量 ≤ 1000 条

3.2 执行步骤

步骤 1：输入接收与解析

接收用户提供的文件路径 / URL / 文本内容
检测输入类型与编码格式
提取原始内容，去除无效字符（如 BOM 头、多余空白）

步骤 2：关键信息识别

根据预设字段规则（或用户自定义字段映射）扫描内容
识别实体、数值、日期、标识符等要素
对每个识别结果记录来源位置（行号/偏移量）

步骤 3：结构化转换

将识别结果映射到输出模板
字段缺失时留空并标记 [需核实:字段名]
字段类型自动检测（字符串/数字/布尔/日期）

步骤 4：置信度评估

每个字段独立计算置信度：
- 直接匹配（正则/精确匹配）：0.9 ~ 1.0
- 模糊匹配（包含/近似）：0.7 ~ 0.89
- 推断值（上下文推导）：0.5 ~ 0.69
- 无法确认：< 0.5，输出 [需核实]
整体置信度 = 各字段置信度的加权平均

步骤 5：输出与自查

按约定格式生成输出文件
自查清单：
- [ ] 所有必填字段是否已覆盖
- [ ] 格式是否符合模板（JSON 合法性 / CSV 列对齐）
- [ ] 置信度标注是否完整
- [ ] 是否存在 [需核实] 标记且已向用户说明

步骤 6：二次确认

若存在以下情况，主动向用户确认：
- 输入内容存在歧义（同一字段多种解读）
- 置信度低于 0.6 的字段超过 30%
- 用户未指定输出格式但数据量较大

3.3 输出规范

{
  "meta": {
    "total": 2,
    "processed_at": "2026-01-15T10:30:00Z",
    "version": "1.0.0"
  },
  "results": [
    {
      "id": "001",
      "content": "原始内容摘要...",
      "fields": {
        "name": { "value": "张三", "confidence": 0.98 },
        "date": { "value": "2025-12-01", "confidence": 0.95 },
        "amount": { "value": null, "confidence": 0.0, "note": "[需核实:amount]" }
      },
      "source": "input_file.txt:line12"
    }
  ]
}

四、置信度门控机制

4.1 基本原则

不编造：信息不足时输出 [需核实:字段名] 占位符，绝不虚构值
不隐瞒：低置信度字段必须显式标注，不得静默通过
可追溯：每个字段标注来源位置，便于用户回溯验证

4.2 置信度阈值表

| 置信度区间 | 标记 | 处理方式 | |-----------|------|---------| | 0.9 ~ 1.0 | 无 | 直接输出，视为可靠 | | 0.7 ~ 0.89 | 无 | 正常输出，可在备注中说明匹配方式 | | 0.5 ~ 0.69 | [需核实] | 输出值 + 提示用户确认 | | < 0.5 | [需核实] + 空值 | 不输出推测值，等待用户补充 |

4.3 信息不足时的处理路径

检测到缺失字段 → 标记 [需核实:字段名]
尝试从上下文推导（仅限明确逻辑关系）
推导置信度 < 0.5 时放弃推导，保留占位符
输出完成后汇总所有占位符，向用户列出待确认清单

五、错误码体系

| 错误码 | 含义 | 提示话术 | 修正步骤 | |--------|------|---------|---------| | E001 | 输入文件不存在 | "未找到指定文件，请确认路径是否正确" | 检查路径 → 确认文件名 → 重试 | | E002 | 输入格式不支持 | "当前格式不在支持范围内（支持：txt/csv/json/xlsx/url）" | 转换格式 → 或提供文本内容 | | E003 | 编码异常 | "文件编码非 UTF-8，已尝试自动检测" | 手动转码 → 或指定编码类型 | | E004 | 字段映射冲突 | "同一字段存在多种解读，请指定优先级" | 提供字段映射规则 → 重试 | | E005 | 批量处理超限 | "单批处理上限为 1000 条，请分批执行" | 拆分数据 → 分批处理 | | E006 | 输出格式错误 | "输出模板不合法，请检查字段定义" | 修正模板 → 重新生成 | | E007 | 置信度过低 | "超过 30% 的字段置信度低于 0.6，建议人工复核" | 补充信息 → 或接受低置信度输出 |

六、FAQ 反模式对照

6.1 常见坑与正确做法

| 常见错误（反模式） | 问题说明 | 正确做法 | |-------------------|---------|---------| | 直接跳过缺失字段 | 输出不完整，用户无法感知数据缺口 | 用 [需核实] 显式标记 | | 对模糊信息强行赋值 | 编造数据，误导后续分析 | 保留空值 + 标注低置信度 | | 忽略编码问题 | 中文乱码，数据不可用 | 前置检测编码，异常时提示转码 | | 一次性处理超大文件 | 内存溢出或超时 | 分批处理，每批 ≤ 1000 条 | | 不保留原始文件 | 出错后无法回溯 | 处理前自动备份原始输入 |

6.2 反模式对照表

反模式 1：猜测填充

❌ 错误：日期字段缺失时，自动填入当前日期
✅ 正确：输出 [需核实:date]，提示用户补充

反模式 2：静默截断

❌ 错误：长文本超出字段限制时直接截断，不告知用户
✅ 正确：截断处添加 ... 标记，并在备注中说明

反模式 3：格式混用

❌ 错误：同一批次中部分输出 JSON、部分输出 CSV
✅ 正确：统一格式，或在 meta 中声明混合格式及原因

反模式 4：忽略用户自定义规则

❌ 错误：用户指定了字段映射，仍按默认规则处理
✅ 正确：优先应用用户自定义映射，冲突时提示确认

七、渐进式阅读路径

7.1 速查卡（30 秒上手）

1. 准备输入文件（UTF-8 编码）
2. 调用：jsawesome <输入文件> [--format json|csv|md]
3. 获取输出：结构化结果 + 置信度标注
4. 检查 [需核实] 标记，补充缺失信息
5. 完成

7.2 新手路径（首次使用）

阅读「能力边界」了解适用范围
使用单个样本文件试运行
核对输出字段与原始数据的对应关系
熟悉置信度标记的含义
逐步扩展到批量处理

7.3 进阶路径（深度使用）

自定义字段映射规则（通过配置文件）
使用 --template 参数指定输出模板
结合 --batch 模式处理多文件
利用 --confidence-threshold 调整置信度过滤阈值
接入自动化流水线（通过 CLI 接口）

八、CLI 接口参考

# 版本信息
jsawesome --version

# 自检（验证环境配置）
jsawesome --selftest

# 基本用法
jsawesome <input_path> [--format json|csv|md] [--output <path>]

# 批量处理
jsawesome --batch <input_dir> --format json

# 自定义模板
jsawesome <input_path> --template <template_file.json>

# 置信度阈值
jsawesome <input_path> --confidence-threshold 0.7

九、用户协议

使用须知

本技能仅供学习与参考用途，使用者应自行承担使用过程中产生的全部责任。
使用者不得将本技能用于任何违反法律法规、侵犯他人权益的场景。
本技能输出的结果仅供参考，不构成任何专业建议或决策依据。
使用者应对输入数据的合法性、合规性负责，不得输入涉及国家秘密、商业秘密或个人隐私的敏感信息。
禁止对本技能进行反向工程、反编译、破解或试图获取底层实现逻辑。

十、许可证（License）

MIT License

MIT License

Copyright (c) 2026 林默

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 jsawesome

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

数据解析 结构化转换 批处理

jsawesome 技能文档

一、能力边界（速查卡）

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 进阶路径（深度使用）

八、CLI 接口参考

九、用户协议

十、许可证（License）

差异（Diff）

新增功能（Feature Additions）

竞品分析（Competitor）

为什么选择本版

简介（Description）

简介（Description）

安装（Setup）

使用（Usage）

示例（Examples）

常见问题（FAQ）

数据解析结构化转换批处理