Agent Skill

文档转写 结构化整理 可信标注

知识管理·skill训练营·来自 skill_hub·skillhub.cn ↗
skillhub install @org-k6bcf2fv/markdown-converter
1 Stars·6.5万 综合热度·5,605 字文档·源站更新 2026-11-22

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 处理规则

  1. 不编造:无法确认的信息一律标注,不猜测填充
  2. 保留原文:占位符替换原文,不删除原始内容
  3. 集中标注:多个不确定字段在文末统一列出

4.3 示例

输入:

该产品发布于2023年,用户量突破5000万,主要竞品为Notion。

输出:

该产品发布于2023年[需核实:发布年份],用户量突破5000万[需核实:用户数],主要竞品为Notion[需核实:竞品名称]。

五、错误码体系

错误码含义提示话术修正步骤
E001输入文件不存在"未找到指定文件,请检查路径"确认文件路径,使用绝对路径
E002URL 无法访问"网页抓取失败,请检查网络或链接"验证 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 分钟)

  1. 阅读"能力边界"了解适用范围
  2. 使用"标准流程"完成一次基础转换
  3. 查看输出文件,对照"输出规范"检查格式
  4. 遇到不确定信息时,参考"置信度门控"

7.3 进阶路径(15 分钟)

  1. 学习"错误码体系",掌握问题定位方法
  2. 编写 shell 脚本批量处理多个文件:
for f in *.txt; do
  python run.py --selftest "$f" --output "${f%.txt}.md" --skip-error
done
  1. 自定义输出模板:修改 run.py 中的 format_markdown 函数,调整标题样式或列表格式
  2. 结合 --confidence 参数控制置信度标注的严格程度

7.4 参数速查表

参数类型默认值说明
--inputstring无输入文件路径
--outputstringstdout输出文件路径
--urlstring无网页链接
--encodingstringutf-8输入文件编码
--confidencebooltrue是否启用置信度标注
--skip-errorboolfalse批量处理时跳过错误文件
--selftestboolfalse运行自检
--versionboolfalse显示版本号

八、用户协议

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

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

  1. 责任承担:使用者自行承担因使用本 Skill 产生的全部责任。包括但不限于因转换结果不准确、信息遗漏、格式错误等造成的直接或间接损失。
  2. 禁止反向工程:不得对本 Skill 的源代码进行反向工程、反编译、破解或试图提取底层算法。
  3. 合法使用:不得使用本 Skill 处理违法内容、侵犯他人知识产权的内容或违反适用法律的内容。
  4. 无担保:本 Skill 按"原样"提供,不附带任何明示或暗示的担保,包括但不限于适销性、特定用途适用性和非侵权保证。
  5. 服务变更:作者保留随时修改、更新或终止本 Skill 的权利,恕不另行通知。

九、许可证(License)

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

MIT License

版权所有 (c) 2024 墨规工作室

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

上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

本软件按"原样"提供,不附带任何明示或暗示的担保,包括但不限于适销性、特定用途适用性和非侵权保证。在任何情况下,作者或版权持有人均不对任何索赔、损害或其他责任负责,无论是在合同诉讼、侵权或其他方面,由本软件或本软件的使用或其他交易引起、产生或与之相关。


本 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:将文本、文件或网页链接转为结构化Markdown,保留要点并标注可信度。
  • 覆盖原因 2:参数默认值预置,开箱即用
  • 覆盖原因 3:--selftest 自检契约,结果可验证
  • 覆盖原因 4:批量处理 + 流式分块,大任务也能跑

本工具的优势:

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

为什么选择本版

  1. 真正的完整实现:将文本、文件或网页链接转为结构化Markdown,保留要点并标注可信度。,不是演示壳
  2. 开箱即用:参数预置 + 默认值,上手更快
  3. 可靠可证:--selftest 自检契约,结果可验证
  4. 容错健壮:异常降级 + 多编码容错,不轻易崩溃
  5. 安全可控:--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,全部通过即核心功能正常。

同分类其他技能

查看全部 ›