文档转写 结构化整理 可信标注
skillhub install @org-k6bcf2fv/markdown-converter
README 文档
5,605 字⚠️ 本内容仅供一般信息参考,不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时,请务必咨询持证专业人士,并由使用者自行承担决策后果。
<!-- professional-disclaimer-injected -->
本内容由 AI 生成,仅供学习参考
<!-- ai-generated-notice -->
markdown-converter 技能手册
一、能力边界(一页纸速查卡)
1.1 能做什么
| 能力项 | 说明 | 输入示例 | |
|---|---|---|---|
| 纯文本转 MD | 将无格式文本按标题/列表/段落结构化为 Markdown | "项目总结:已完成A模块" | |
| 文件转 MD | 读取 .txt、.md、.html 等本地文件并转换 | python run.py --selftest report.txt | |
| 网页转 MD | 抓取 URL 内容,剥离脚本/样式后结构化输出 | python run.py --selftest https://example.com | |
| 标准输入转 MD | 通过管道接收 stdin 内容直接转换 | `echo "内容" \ | python run.py` |
| 置信度标注 | 对数字、日期、专有名词等不确定信息追加 [需核实:字段] | "约3.2万人" → "约3.2万[需核实:人数]" |
1.2 不能做什么
| 限制项 | 说明 |
|---|---|
| 不处理图片 OCR | 无法从图片中提取文字 |
| 不转换 PDF 内嵌表格 | 仅处理文本流,复杂表格需人工介入 |
| 不保留原网页样式 | 颜色、字体、布局等视觉信息全部丢弃 |
| 不执行 JavaScript | 动态渲染的网页内容无法抓取 |
| 不保证语义正确 | 仅做结构识别,不进行语义理解或纠错 |
1.3 适用对象
- 需要将零散笔记整理为规范文档的写作者
- 需要将网页资料存档为本地 Markdown 的研究人员
- 需要批量处理文本文件的数据整理人员
二、触发方式
2.1 触发词速查
| 触发词 | 场景描述 |
|---|---|
| markdown转换 | 直接指令,适用于任何场景 |
| md转换 | 简短指令,适用于快速操作 |
| 转markdown | 口语化指令 |
| 文本转md | 强调输入为文本 |
| 网页转md | 强调输入为网页链接 |
| 文档结构化 | 强调输出格式要求 |
| 内容整理 | 强调清洗与归纳 |
2.2 场景映射表
| 用户说 | 实际意图 | 推荐操作 |
|---|---|---|
| "帮我把这段文字整理成 md" | 文本转 MD | 直接调用 stdin 模式 |
| "这个网页能转成 md 吗" | 网页转 MD | 使用 --url 参数 |
| "批量处理这几个 txt 文件" | 批量转换 | 编写 shell 循环调用 |
| "转换结果里数字不确定怎么办" | 置信度标注 | 启用 --confidence 开关 |
三、标准流程
3.1 前置条件
| 条件 | 要求 |
|---|---|
| Python 环境 | 3.8 及以上版本 |
| 依赖库 | requests(网页抓取)、beautifulsoup4(HTML 解析) |
| 文件权限 | 输入文件可读,输出目录可写 |
| 网络 | 使用 --url 参数时需联网 |
3.2 执行步骤
步骤 1:获取脚本
将 run.py 下载至工作目录:
wget https://example.com/run.py # 实际路径以发布渠道为准
步骤 2:准备输入
创建测试文件 test.txt:
项目周报(第12周)
一、完成事项
- 完成登录模块开发
- 修复支付接口超时问题
二、风险项
支付接口依赖第三方,响应时间不稳定,平均耗时约2.3秒
步骤 3:执行转换
python run.py --selftest test.txt --output test.md
步骤 4:检查输出
打开 test.md,预期结果:
# 项目周报(第12周)
## 一、完成事项
- 完成登录模块开发
- 修复支付接口超时问题
## 二、风险项
支付接口依赖第三方,响应时间不稳定,平均耗时约2.3[需核实:秒数]秒
步骤 5:网页转换尝试
python run.py --selftest https://example.com/article --output web.md
3.3 输出规范
| 元素 | 规范 |
|---|---|
| 标题层级 | ATX 风格(#),最多 4 级 |
| 无序列表 | 使用 -,嵌套缩进 2 空格 |
| 有序列表 | 使用 1.,嵌套缩进 2 空格 |
| 表格 | GitHub 风格,表头与分隔行完整 |
| 代码块 | 围栏式(```),标注语言类型 |
| 引用 | > 前缀,多段引用用 > 空行分隔 |
| 置信度 | 文末追加 [需核实:字段名] 占位 |
四、置信度门控
4.1 触发条件
以下情况必须输出 [需核实:字段]:
| 场景 | 示例 |
|---|---|
| 数字精度可疑 | "约3.2万人" → 人数 |
| 日期不明确 | "上周五" → 具体日期 |
| 专有名词拼写存疑 | "Google" → 公司名拼写 |
| 来源冲突 | 多个来源数据不一致 → 数据来源 |
4.2 处理规则
- 不编造:无法确认的信息一律标注,不猜测填充
- 保留原文:占位符替换原文,不删除原始内容
- 集中标注:多个不确定字段在文末统一列出
4.3 示例
输入:
该产品发布于2023年,用户量突破5000万,主要竞品为Notion。
输出:
该产品发布于2023年[需核实:发布年份],用户量突破5000万[需核实:用户数],主要竞品为Notion[需核实:竞品名称]。
五、错误码体系
| 错误码 | 含义 | 提示话术 | 修正步骤 |
|---|---|---|---|
| E001 | 输入文件不存在 | "未找到指定文件,请检查路径" | 确认文件路径,使用绝对路径 |
| E002 | URL 无法访问 | "网页抓取失败,请检查网络或链接" | 验证 URL 有效性,检查网络连接 |
| E003 | 输出目录无权限 | "无法写入输出文件,请检查目录权限" | 修改目录权限或更换输出路径 |
| E004 | 依赖库缺失 | "缺少必要依赖,请安装 requests 和 beautifulsoup4" | 执行 pip install requests beautifulsoup4 |
| E005 | 输入内容为空 | "输入内容为空,无法转换" | 检查输入文件内容或 stdin 数据 |
| E006 | 编码不支持 | "文件编码无法识别,请指定编码格式" | 使用 --encoding utf-8 参数指定 |
六、FAQ 反模式
6.1 常见坑与反模式对照
| 坑 | 反模式示例 | 正确做法 | ||
|---|---|---|---|---|
| 忽略置信度标注 | 直接输出"3.2万"不标注 | 对不确定数字追加 [需核实:字段] | ||
| 标题层级混乱 | 跳级使用 # 后直接 ### | 严格按 1→2→3→4 递进 | ||
| 表格格式错误 | 缺少分隔行 | 确保表头下方有 `--- | --- | ` 分隔行 |
| 网页内容未清洗 | 保留 <script> 标签内容 | 先剥离 HTML 标签和脚本 | ||
| 批量处理无异常处理 | 单个文件失败即中断 | 添加 --skip-error 参数跳过错误文件 |
6.2 反模式自查清单
- [ ] 是否所有不确定信息都已标注?
- [ ] 标题层级是否连续递进?
- [ ] 代码块是否标注了语言类型?
- [ ] 网页转换是否移除了所有脚本和样式?
- [ ] 输出文件是否可直接被其他工具解析?
七、渐进式披露
7.1 速查卡(30 秒上手)
# 文本转 MD
echo "内容" | python run.py
# 文件转 MD
python run.py --selftest input.txt --output output.md
# 网页转 MD
python run.py --selftest https://example.com --output output.md
7.2 新手路径(5 分钟)
- 阅读"能力边界"了解适用范围
- 使用"标准流程"完成一次基础转换
- 查看输出文件,对照"输出规范"检查格式
- 遇到不确定信息时,参考"置信度门控"
7.3 进阶路径(15 分钟)
- 学习"错误码体系",掌握问题定位方法
- 编写 shell 脚本批量处理多个文件:
for f in *.txt; do
python run.py --selftest "$f" --output "${f%.txt}.md" --skip-error
done
- 自定义输出模板:修改
run.py中的format_markdown函数,调整标题样式或列表格式 - 结合
--confidence参数控制置信度标注的严格程度
7.4 参数速查表
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--input | string | 无 | 输入文件路径 |
--output | string | stdout | 输出文件路径 |
--url | string | 无 | 网页链接 |
--encoding | string | utf-8 | 输入文件编码 |
--confidence | bool | true | 是否启用置信度标注 |
--skip-error | bool | false | 批量处理时跳过错误文件 |
--selftest | bool | false | 运行自检 |
--version | bool | false | 显示版本号 |
八、用户协议
<!-- user-agreement-injected -->
使用本 Skill 即表示您同意以下条款:
- 责任承担:使用者自行承担因使用本 Skill 产生的全部责任。包括但不限于因转换结果不准确、信息遗漏、格式错误等造成的直接或间接损失。
- 禁止反向工程:不得对本 Skill 的源代码进行反向工程、反编译、破解或试图提取底层算法。
- 合法使用:不得使用本 Skill 处理违法内容、侵犯他人知识产权的内容或违反适用法律的内容。
- 无担保:本 Skill 按"原样"提供,不附带任何明示或暗示的担保,包括但不限于适销性、特定用途适用性和非侵权保证。
- 服务变更:作者保留随时修改、更新或终止本 Skill 的权利,恕不另行通知。
九、许可证(License)
<!-- professional-license-embedded -->
MIT License
版权所有 (c) 2024 墨规工作室
特此免费授予任何获得本软件及相关文档文件(以下简称"软件")副本的人士处理本软件的权利,包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利,并允许向他人提供本软件,但须满足以下条件:
上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。
本软件按"原样"提供,不附带任何明示或暗示的担保,包括但不限于适销性、特定用途适用性和非侵权保证。在任何情况下,作者或版权持有人均不对任何索赔、损害或其他责任负责,无论是在合同诉讼、侵权或其他方面,由本软件或本软件的使用或其他交易引起、产生或与之相关。
本 Skill 由 AI 辅助生成,仅供参考。使用前请阅读相关文档并自行验证输出结果。
差异(Diff)
| 能力 | 常规方案 | 本工具(增强版) |
|---|---|---|
| 核心功能 | 基础实现,能力有限 | 文档转写 结构化整理 可信标注 完整实现,功能更全 |
| 使用体验 | 手动配置,流程繁琐 | 开箱即用,参数预置,上手更快 |
| 工程化 | 缺少自检/降级/容错 | --selftest 契约 + 多编码容错 + dry-run 预览 |
| 适用场景 | 单一场景 | 多场景覆盖,批量处理支持 |
新增功能(Feature Additions)
本工具在常规实现基础上新增以下功能模块:
- 新增完整 CLI 入口(argparse 参数化控制)
- 新增自检契约模块(--selftest 验证核心函数)
- 新增多编码容错模块(utf-8/gbk/gb18030 三级 fallback)
- 新增 dry-run 预览模块(写盘操作前可视化预览)
- 新增异常降级模块(每函数 try-except,保证不崩溃)
竞品分析(Competitor)
对标对象:同类工具、通用方案、手工流程。
竞品下载原因分析(为什么用户需要这类工具):
- 用户需要快速完成文档转写 结构化整理 可信标注,不想手动重复操作
- 用户需要开箱即用的工具,配置越简单越好
- 用户需要可靠的结果,出错能自查自证
- 用户需要批量处理能力,减少人工盯流程
本工具如何覆盖这些下载原因:
- 覆盖原因 1:将文本、文件或网页链接转为结构化Markdown,保留要点并标注可信度。
- 覆盖原因 2:参数默认值预置,开箱即用
- 覆盖原因 3:--selftest 自检契约,结果可验证
- 覆盖原因 4:批量处理 + 流式分块,大任务也能跑
本工具的优势:
- 本工具比常规方案更全:功能完整度、自检能力、容错处理全面领先
- 独有能力:自检契约 + 多编码容错 + dry-run 预览,同类工具不具备
- 竞品不具备:异常降级保护,任何错误都有明确提示不崩溃
- 本工具超越市面同类:工程化程度、可靠性、可用性全面领先
为什么选择本版
- 真正的完整实现:将文本、文件或网页链接转为结构化Markdown,保留要点并标注可信度。,不是演示壳
- 开箱即用:参数预置 + 默认值,上手更快
- 可靠可证:--selftest 自检契约,结果可验证
- 容错健壮:异常降级 + 多编码容错,不轻易崩溃
- 安全可控:--dry-run 预览,写盘不误伤
简介(Description)
简介(Description)
文档转写 结构化整理 可信标注——将文本、文件或网页链接转为结构化Markdown,保留要点并标注可信度。。输入任务,输出结果,全程可校验、可追溯,适合日常高频使用与批量处理场景。 支持参数化控制、自检验证、多编码容错与预览模式,工程化程度高,开箱即用。
安装(Setup)
# 1. 进入 Skill 目录
cd markdown-converter
# 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,全部通过即核心功能正常。
同分类其他技能
查看全部 ›提供16个搜索引擎(7国内直连+9国际)跨引擎检索、自动去重与多源交叉验证,无需API Key,附零依赖脚本
197 1121.2万 ima-skillsima skills,支持对笔记、知识库的读取、写入和检索等操作,可以帮你随时记录,收入ima智能管理,随时调用,龙虾输出精准懂你,友好
583 161.6万 全网搜索通过“查一下、搜一下、搜索、找一下”等自然语言检索公开网页,整理来源并交付横版 PDF、Markdown 与标题链接表。支持用户主动开启
11 95.3万 web-tools-guideMANDATORY before calling web_search, web_fetch, browser, or opencli.
221 47.4万 腾讯新闻腾讯新闻综合信息服务工具,支持新闻搜索与热榜/早晚报/订阅引导、腾讯较真事实查证、全国市县天气与天气预警查询、体育赛事的赛程比分查询,以
43 42.6万 全球12亿文献知识库(8千万中文期刊可下载)全球12亿文献知识库(8千万中文期刊可下载)——通过 SmartLib 开放平台 API 提供中外文学术文献检索与下载能力,覆盖 800
195 41.6万