Markdown 工具箱专业版

面向团队的多文件Markdown站点生成与文档规范治理工具，支持目录生成、Lint校验、死链检测及多格式导出。

核心功能: 本技能提供中文交互、提升工作效率、化工作流场景等能力。

概述

专业版面向团队与企业，在免费版单文件生成基础上，扩展多文件站点与目录生成、文档规范 lint 与团队规则集、链接校验与死链检测、多格式导出。规则与免费版兼容，已有校验可直接纳入规则集.

核心能力

能力	说明	专业版增强
多文件站点	目录结构与 TOC 生成	站点级
文档 lint	规则集与豁免治理	CI 集成
链接校验	死链检测与锚点校验	全站扫描
多格式导出	HTML/PDF/DocBook	一键转换
技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置.

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：面向团队的多文件、目录生成与文档规、范治理工具、Markdown、站点与文档规范治、理专业工具、多文件站点与目录、自动生成、文档规范、与团队规则集、链接校验与死链检等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一：多文件站点与目录

bash

# 生成站点目录与 TOC（专业版）
{baseDir}/（请参考skill目录中的脚本文件） build --src docs/ --toc

text

站点结构:
  docs/
    index.md          # 首页（唯一 H1）
    guide/
      getting-started.md
      advanced.md
    _toc.yml          # 自动生成目录

场景二：文档规范 lint

yaml

# .markdownlint.json 团队规则集
{
  "default": true,
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD041": false
}

bash

# CI 校验
markdownlint docs/**/*.md --config .markdownlint.json

场景三：死链检测与导出

bash

# 死链检测
{baseDir}/（请参考skill目录中的脚本文件） check-links docs/
# ...
# 多格式导出
{baseDir}/（请参考skill目录中的脚本文件） export --to pdf --src docs/ --out build/

不适用场景

以下场景Markdown 工具箱专业版不适合处理：

• 加密文件破解
• 损坏文件修复
• 物理介质数据恢复

触发条件

需要文件处理、文档转换、格式互转、内容提取时使用。不适用于非本工具能力范围的需求.

快速开始

1. 将免费版规则纳入团队 lint 规则集.
2. 组织多文件目录结构.
3. 接入 CI lint 与死链检测.
4. 配置多格式导出.

示例

站点配置（md-site.json）：

json

{
  "src": "docs/",
  "toc": true,
  "lint": {"config": ".markdownlint.json", "block_on_error": true},
  "link_check": {"internal": true, "external": false},
  "export": ["html", "pdf"]
}

优选实践

• 目录先规划：多文件站点先定目录结构，再写内容.
• lint 入 CI：文档变更跑 lint，违规阻断合并.
• 死链定期扫：每周扫描内部链接，修复死链.
• TOC 自动生：别手维护目录，用脚本生成避免漏.
• 导出按需：PDF 用于归档，HTML 用于在线浏览.

免费版兼容性

项目	免费版	专业版
规则	相同	相同（纳入规则集）
范围	单文件	多文件站点
校验	基础	lint + 死链
导出	不支持	多格式

常见问题

Q1：多文件站点怎么组织？ A：按主题分目录，每文件单一 H1，TOC 用脚本生成. Q2：lint 规则怎么协同？ A：规则集 JSON 版本化管理，团队评审后合并. Q3：死链检测要联网吗？ A：内部链接不需联网，外部链接可选检测. Q4：导出 PDF 质量如何？ A：通过 pandoc/wkhtmltopdf 转换，样式可定制模板. Q5：专业版有优先支持吗？ A：有。专业版享文档站点设计与规范咨询.

进阶用法

多文件站点结构

text

docs/
  index.md              # 首页（唯一 H1）
  guide/
    getting-started.md  # 入门
    advanced.md         # 进阶
  reference/
    api.md              # API 参考
    config.md           # 配置
  _toc.yml              # 自动生成目录
  _meta.yml             # 元信息

TOC 自动生成

yaml

# _toc.yml（自动生成，勿手改）
toc:
  - title: 指南
    items:
      - title: 入门
        path: guide/getting-started.md
      - title: 进阶
        path: guide/advanced.md
  - title: 参考
    items:
      - title: API
        path: reference/api.md

bash

# 从目录结构生成 TOC
{baseDir}/（请参考skill目录中的脚本文件） toc --src docs/ --out _toc.yml

死链检测

bash

# 内部链接检测
{baseDir}/（请参考skill目录中的脚本文件） check-links docs/ --internal
# ...
# 锚点检测
{baseDir}/（请参考skill目录中的脚本文件） check-links docs/ --anchors
# ...
# 输出报告
{baseDir}/（请参考skill目录中的脚本文件） check-links docs/ --report broken.json

text

死链报告示例:
  docs/guide/advanced.md:
    - [无效链接](./missing.md) → 文件不存在
    - [无效锚点](#不存在的章节) → 锚点缺失

多格式导出

bash

# 导出 PDF（pandoc + LaTeX）
pandoc docs/*.md -o build/manual.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Noto Sans CJK SC"
# ...
# 导出 HTML 站点
{baseDir}/（请参考skill目录中的脚本文件） export --to html --src docs/ --out build/
# ...
# 导出 DocBook
pandoc docs/*.md -o build/manual.xml -t docbook

文档规范 lint 规则

规则	说明	严重级
MD041	首行应为 H1	block
MD024	标题不重复	warn
MD012	去除多余空行	warn
MD040	代码块标语言	block
MD009	去除行尾空格	warn

站点治理

• 目录先规划：先定目录结构，再写内容，避免后期重构.
• TOC 自动生：别手维护目录，脚本生成避免漏.
• 导出按需：PDF 归档，HTML 在线，按需导出.

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统: Windows / macOS / Linux
• Node.js: 18+（lint 工具）

依赖详情

依赖项	类型	是否必需	获取方式
markdownlint-cli	lint 工具	必需	npm install -g markdownlint-cli
pandoc	格式转换	导出时必需	pandoc.org
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

• 本工具为纯 Markdown 指令，无需额外 API Key

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 命令行执行）
• 说明: 通过自然语言指令驱动 Agent 完成多文件站点与文档治理

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

• 需LLM支持,无LLM环境不可用
• 复杂业务场景建议结合人工经验判断
• 执行效率受模型能力与网络环境影响

输出格式

json

{
  "success": true,
  "data": {
    "result": "Markdown 工具箱专业版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "markdownkit pro"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

安全注意事项

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
网络通信安全	使用HTTPS协议，验证SSL证书有效性
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。