markdown-ai-rewriter

面向 Markdown 长文与文档 的 AI 改写工具：在 保留标题层级、代码块、表格、图片等结构 的前提下，对正文进行润色、降重或换表述，适合博客、技术文档、公众号稿、新闻稿整理等场景。

核心特点与优势

| 维度 | 说明 | |------|------| | 结构优先 | 不是简单「全文扔给模型」，而是按文档结构处理，减少标题错乱、代码被改写、版式被打乱的风险。 | | 双模式可切换 | 章节模式（默认）按标题切块并行，成本与连贯性平衡好；全文模式整篇一次生成，语气最连贯，适合短文或强叙事。 | | 多模型 | 支持 OpenAI、Anthropic、Azure OpenAI、Gemini、DeepSeek、OpenRouter、Qwen、GLM、豆包、文心、MiniMax，也可接入 自定义 Provider。 | | 风格可控 | 内置 casual / formal / technical / creative / custom，并支持温度、长度倾向、--prompt 自定义指令。 | | 工程化友好 | 提供 CLI（markdown-ai-rewrite / md-rewrite）与 TypeScript API，可嵌入脚本、CI 或内容流水线。 | | 并发可配 | 章节模式下可配置并发请求数，在长文档场景下兼顾速度与 API 限流。 |

一句话：把「能改的部分」交给模型，把「必须稳的结构」留在本地解析与重组逻辑里，更适合严肃内容生产，而不是聊天式随意生成。

两种改写模式

| 模式 | CLI | 适用场景 | 优势 | |------|-----|----------|------| | 章节 section | --mode section（默认） | 中长篇、多小节、技术文档 | 按标题分章改写，可带上下文章摘要，调用次数可预期、成本更可控。 | | 全文 full | --mode full | 短文、强叙事、整篇语气统一 | 一次请求覆盖全文，连贯性通常最好；全文模式会先用占位符保护图片再还原。 |

章节模式可通过 --section-level 1|2|3 指定按几级标题切分（默认 1 级 #）。

安装

npm install markdown-ai-rewriter

按需安装官方 SDK（至少其一）：

npm install openai
# Azure OpenAI / Gemini / DeepSeek / OpenRouter / Qwen / GLM / 豆包 / 文心 / MiniMax
# 均可通过 OpenAI SDK（兼容接口）使用，见下文
# 或
npm install @anthropic-ai/sdk

快速开始

命令行

Provider 使用说明（中文）

下面是每个 Provider 对应的环境变量（--provider 和 API Key 一一对应）：

| Provider | 环境变量 | 说明 | |---|---|---| | openai | OPENAI_API_KEY | OpenAI 官方 | | anthropic | ANTHROPIC_API_KEY | Claude 官方 | | azure-openai | AZURE_OPENAI_API_KEY | 需同时提供 Azure endpoint（AZURE_OPENAI_ENDPOINT 或 --base-url） | | gemini | GEMINI_API_KEY | 使用 OpenAI 兼容接口 | | deepseek | DEEPSEEK_API_KEY | 使用 OpenAI 兼容接口 | | openrouter | OPENROUTER_API_KEY | 使用 OpenAI 兼容接口 | | qwen | QWEN_API_KEY | 阿里百炼（DashScope）兼容接口 | | glm | GLM_API_KEY | 智谱 BigModel 兼容接口 | | doubao | DOUBAO_API_KEY | 火山引擎 Ark 兼容接口 | | wenxin | WENXIN_API_KEY | 百度千帆兼容接口 | | minimax | MINIMAX_API_KEY | MiniMax 兼容接口 |

说明：

• --model 不传时，会使用各 Provider 内置默认模型。
• --base-url 可覆盖 OpenAI 兼容 Provider 的默认 endpoint。
• azure-openai 的 --model 对应 Azure 的 deployment 名称。

每个平台一条可复制命令

# OpenAI
export OPENAI_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-openai.md -p openai --style casual

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-anthropic.md -p anthropic --style formal

# Azure OpenAI
export AZURE_OPENAI_API_KEY="your-api-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
md-rewrite rewrite -i article.md -o out-azure.md -p azure-openai -m gpt-4o-mini

# Gemini（OpenAI-compatible）
export GEMINI_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-gemini.md -p gemini

# DeepSeek
export DEEPSEEK_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-deepseek.md -p deepseek

# OpenRouter
export OPENROUTER_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-openrouter.md -p openrouter -m openai/gpt-4o-mini

# Qwen
export QWEN_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-qwen.md -p qwen

# GLM
export GLM_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-glm.md -p glm

# 豆包
export DOUBAO_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-doubao.md -p doubao

# 文心
export WENXIN_API_KEY="your-api-key"
md-rewrite rewrite -i article.md -o out-wenxin.md -p wenxin

# MiniMax（需已安装 openai；密钥在 MiniMax 开放平台创建）
export MINIMAX_API_KEY="your-minimax-api-key"
# 可选：如需覆盖默认 endpoint（默认 https://api.minimaxi.com/v1）
md-rewrite rewrite -i article.md -o out-minimax.md -p minimax -m MiniMax-M2.1 --style casual

# 全文模式示例
md-rewrite rewrite -i article.md -o out-full.md -p openai --mode full -v

在代码中使用

import { MarkdownRewriter } from 'markdown-ai-rewriter';

const rewriter = new MarkdownRewriter({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini',
  mode: 'section',       // 或 'full'
  sectionLevel: 1,
  verbose: true,
  concurrency: 3,
  options: {
    style: 'casual',
    temperature: 0.7,
    maxTokens: 2000,     // 未传时 Provider 侧有默认值；CLI 默认常为 4000，以实际调用为准
  },
});

const result = await rewriter.rewrite(markdown);
console.log(result.rewritten);

常用 CLI 参数

| 参数 | 含义 | |------|------| | -i, --input | 输入 Markdown 文件（必填） | | -o, --output | 输出 Markdown 文件（必填） | | -p, --provider | openai、anthropic、azure-openai、gemini、deepseek、openrouter、qwen、glm、doubao、wenxin、minimax（必填） | | -k, --api-key | API Key；也可使用对应 provider 的环境变量（如 OPENAI_API_KEY、GEMINI_API_KEY 等） | | -m, --model | 模型名 / 部署名（按 provider 默认值可选） | | --base-url | 通用 Base URL 覆盖（OpenAI 兼容 provider），azure-openai 下可作为 endpoint 覆盖 | | --minimax-base-url | MiniMax 兼容旧参数，等价于 --base-url | | -s, --style | casual | formal | technical | creative | custom | | --prompt | 自定义系统提示补充（常与 custom 风格配合） | | -t, --temperature | 采样温度 0～1，默认约 0.7 | | --max-tokens | 单次回复上限（CLI 默认 4000） | | --preserve-length | 尽量保持与原文相近篇幅 | | -c, --concurrency | 并发数，默认 3（主要影响章节模式） | | -v, --verbose | 打印详细日志 | | --mode | section（默认）或 full | | --section-level | 章节模式下的标题级别 1～3，默认 1 |

完整说明可执行：markdown-ai-rewrite rewrite --help。

写作风格（--style）

• casual：轻松、口语化
• formal：正式、商务或书面语
• technical：偏术语与准确性
• creative：更有表现力
• custom：配合 --prompt 自行描述要求

改写时大致会发生什么

• 章节 / 全文 两种模式都会在「尊重结构」的前提下改写正文；标题、代码块、表格等会按实现策略尽量保留或由占位符保护（全文模式下的图片采用占位符机制）。
• 具体列表、引用等是否逐条保留，与模型输出有关；若你需要强保留列表结构，可在 --prompt 中明确要求。

示例

casual 风格（片段）

输入：

# Product Launch

The new product will be released next month. It features advanced technology.

- High performance
- Low cost
- Easy to use

输出（示意）：

# Product Launch

Hey, exciting news! Our new product drops next month and it's packed with some seriously cool tech.

- Lightning-fast performance
- Won't break the bank
- Super simple to get started

formal 风格（引用块）

输入： > This is an important announcement.

输出（示意）： > We wish to inform you of a significant development that requires your attention.

与内容流水线配合（示例）

可与抓取、转换工具串联，例如先得到 Markdown，再改写，最后发布：

convert-url --url "https://news.com/article" --output article.md

markdown-ai-rewrite rewrite \
  --input article.md \
  --output article-rewritten.md \
  --provider openai \
  --style casual

自定义 AI 后端

实现 BaseProvider，即可对接自有网关或其它兼容接口：

import { MarkdownRewriter, BaseProvider, RewriteOptions } from 'markdown-ai-rewriter';

class MyCustomProvider extends BaseProvider {
  name = 'my-provider';

  async rewrite(text: string, options: RewriteOptions): Promise<string> {
    // 调用你的模型 API，返回改写后的纯文本
    return rewrittenText;
  }
}

const rewriter = new MarkdownRewriter({
  provider: 'custom',
  customProvider: new MyCustomProvider(),
});

API 摘要

MarkdownRewriter

constructor(config: RewriterConfig)
async rewrite(markdown: string): Promise<RewriteResult>

RewriterConfig（节选）

interface RewriterConfig {
  provider:
    | 'openai' | 'anthropic' | 'azure-openai' | 'gemini' | 'deepseek'
    | 'openrouter' | 'qwen' | 'glm' | 'doubao' | 'wenxin'
    | 'minimax' | 'custom';
  apiKey?: string;
  model?: string;
  baseUrl?: string;
  minimaxBaseUrl?: string;
  options?: RewriteOptions;
  customProvider?: AIProvider;
  verbose?: boolean;
  concurrency?: number;
  mode?: 'section' | 'full';
  sectionLevel?: 1 | 2 | 3;
}

RewriteResult

interface RewriteResult {
  original: string;
  rewritten: string;
  blocksProcessed: number;
  blocksRewritten: number;
  tokensUsed?: number;
  cost?: number;
}

环境变量

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export GEMINI_API_KEY="..."
export DEEPSEEK_API_KEY="..."
export OPENROUTER_API_KEY="..."
export QWEN_API_KEY="..."
export GLM_API_KEY="..."
export DOUBAO_API_KEY="..."
export WENXIN_API_KEY="..."
export MINIMAX_API_KEY="..."
# export MINIMAX_BASE_URL="https://api.minimaxi.com/v1"

费用参考（量级）

以约 1000 英文单词 的文章为量级（实际随结构、--mode、模型与并发变化）：

• OpenAI GPT-4o-mini：约 $0.01～0.02
• Anthropic Claude 3.5 一类模型：约 $0.05～0.10
• MiniMax：以 MiniMax 定价说明 为准

请以各厂商定价与实测为准。

许可证

MIT

作者

Ping Si [email protected]