PING SI

---
name: all-to-markdown
version: 0.1.0
description: 将任意文件（PDF、Word、Excel、PPT、图片、音频、网页等）转换为 Markdown
author: Ping Si <[email protected]>
tags: [markdown, convert, pdf, docx, pptx, xlsx, html, ocr, youtube]
requiredEnvVars: []
---

# All to Markdown

基于 [Microsoft MarkItDown](https://github.com/microsoft/markitdown)，将任意格式的文件或 URL 转换为 Markdown，便于 LLM 分析和处理。

## 支持格式

| 类型 | 格式 |
|------|------|
| 文档 | PDF、DOCX、PPTX、XLSX、XLS、EPUB、MSG |
| 数据 | CSV、JSON、XML |
| 图片 | JPG、PNG 等（含 EXIF 元数据，可选 OCR）|
| 音频 | WAV、MP3（含语音转录，需 OpenAI Key）|
| 网页 | HTML、YouTube URL（含字幕提取）|
| 压缩 | ZIP（逐文件转换）|

## 前置要求

安装 markitdown：

```bash
pip install 'markitdown[all]'
```

## 给 AI 的使用说明

当用户需要将文件或 URL 转换为 Markdown 时，使用以下命令：

```bash
scripts/run.sh <文件路径或URL>
```

可选标志：
- `-o <输出文件>` — 保存到文件
- `--use-plugins` — 启用插件（如 markitdown-ocr）

**重要原则**：
- 转换结果直接输出到 stdout，可供 AI 直接读取分析
- 文件路径使用用户提供的实际路径，不要假设
- 转换大型文件时提前告知用户可能需要较长时间

## 使用示例

### 示例 1：转换 PDF

> 用户：帮我把这个 PDF 转成 Markdown，以便我分析内容

AI 执行：
```bash
scripts/run.sh /path/to/document.pdf
```

### 示例 2：转换并保存

> 用户：把这个 Excel 转成 Markdown 文件保存

AI 执行：
```bash
scripts/run.sh /path/to/data.xlsx -o output.md
```

### 示例 3：转换网页

> 用户：把这篇文章转成 Markdown

AI 执行：
```bash
scripts/run.sh https://example.com/article.html
```

### 示例 4：提取 YouTube 字幕

> 用户：把这个 YouTube 视频的内容提取出来

AI 执行：
```bash
scripts/run.sh https://www.youtube.com/watch?v=xxx
```

## 可选 AI 增强功能

设置 `OPENAI_API_KEY` 后，markitdown 可对图片生成 AI 描述：

```bash
OPENAI_API_KEY=sk-xxx scripts/run.sh image.jpg
```

## 安全说明

- 仅在本地执行文件转换，不发送文件内容到远程服务
- 转换 URL 时会访问对应网络地址
- 启用 LLM 功能时，图片内容会发送到 OpenAI API

FILE:config.json
{
  "name": "all-to-markdown",
  "version": "0.1.0",
  "requiredEnvVars": [],
  "requires": {
    "runtime": {
      "python": ">=3.10"
    },
    "binaries": ["markitdown"],
    "packages": {
      "pip": ["markitdown[all]"]
    }
  },
  "skill": {
    "name": "all-to-markdown",
    "enabled": true,
    "autoInvoke": false
  },
  "commands": {
    "convert": {
      "script": "./scripts/run.sh",
      "args": [],
      "description": "将文件或 URL 转换为 Markdown"
    },
    "help": {
      "script": "./scripts/run.sh",
      "args": ["--help"],
      "description": "显示使用帮助"
    }
  },
  "environment": {
    "required": [],
    "optional": [
      {
        "name": "OPENAI_API_KEY",
        "description": "用于图片 AI 描述和 OCR 增强功能（可选）"
      }
    ]
  },
  "install": {
    "type": "pip",
    "autoInstall": false,
    "riskLevel": "low",
    "riskReason": "仅安装 markitdown Python 包，在本地执行文件转换，不发送数据到远程服务（除非启用 LLM 功能）。",
    "requiresApproval": true,
    "installCommand": "pip install 'markitdown[all]'"
  },
  "dependencies": {
    "pip": ["markitdown[all]"],
    "binaries": [],
    "note": "Requires markitdown CLI. Install with: pip install 'markitdown[all]'"
  },
  "permissions": {
    "filesystem": {
      "read": ["<input file path provided by user>"],
      "write": ["<output file path if -o flag is used>"]
    },
    "network": {
      "domains": ["<URL provided by user (if converting a URL)>"],
      "note": "Network access only when converting remote URLs or YouTube links"
    }
  },
  "capabilities": {
    "sensitive": []
  }
}

FILE:scripts/run.sh
#!/usr/bin/env bash
# all-to-markdown skill — convert any file or URL to Markdown via markitdown

set -euo pipefail

INPUT="-"

show_help() {
  cat <<'EOF'
all-to-markdown v0.1.0 — 将任意文件或 URL 转换为 Markdown

用法:
  scripts/run.sh <file-or-url> [选项]

支持格式:
  文档:   PDF, DOCX, PPTX, XLSX, XLS, EPUB, MSG
  数据:   CSV, JSON, XML
  媒体:   图片（含 EXIF/OCR）、音频（含语音转录）
  网页:   HTML、YouTube URL
  压缩:   ZIP（逐文件转换）

选项:
  -o <file>         输出到文件（默认输出到 stdout）
  --use-plugins     启用已安装的第三方插件
  --llm-model <m>   用于图片描述的 LLM 模型（需配合 LLM 客户端）
  -h, --help        显示此帮助

示例:
  scripts/run.sh report.pdf
  scripts/run.sh slide.pptx -o slide.md
  scripts/run.sh https://www.youtube.com/watch?v=xxx
  scripts/run.sh https://example.com/article.html
  scripts/run.sh data.xlsx

环境变量（可选，用于 AI 增强功能）:
  OPENAI_API_KEY    启用图片 AI 描述 / OCR 功能
EOF
}

if [[ -z "$INPUT" || "$INPUT" == "-h" || "$INPUT" == "--help" ]]; then
  show_help
  exit 0
fi

# Check if markitdown is installed
if ! command -v markitdown &>/dev/null; then
  echo >&2 "错误: markitdown 未安装。请运行: pip install 'markitdown[all]'"
  exit 1
fi

# Pass all remaining args through to markitdown
shift
exec markitdown "$INPUT" "$@"

---
name: web-publisher
version: 0.3.5
description: 输入文章 URL，自动提取正文并发布到微信公众号。支持头条、微信、知乎、36kr、CSDN、小红书等平台提取。可配合 browser-web-search skill 先搜索拿到 URL 再批量发布。
author: Ping Si <[email protected]>
tags: [publish, wechat, article, content]
requiredEnvVars:
  - WEB_PUBLISHER_API_URL
  - WEB_PUBLISHER_USER_ID
  - WEB_PUBLISHER_API_KEY
---

# Web Publisher

将任意网页文章自动提取、处理并发布到微信公众号。

## 功能

- **文章提取**: 从 URL 自动提取文章内容、标题、作者、封面图
- **图片处理**: 自动下载文章图片，上传到微信
- **AI 改写**: 可选的 AI 内容改写（Minimax）
- **平台发布**: 创建草稿或直接发布到微信公众号

## 前置要求

### 1. 注册并获取凭证

在 [tools.siping.me](https://tools.siping.me) 注册账号，获取用户 ID 和 API Key。

### 2. 微信公众号 IP 白名单

在微信公众平台 → 设置与开发 → 基本配置 → IP白名单 中，添加服务器 IP（在 [tools.siping.me](https://tools.siping.me) 中查看）。

### 3. 安装本地依赖

`scripts/run.js` 通过 `require('news-to-markdown')` 调用正文提取库，必须全局安装：

```bash
npm install -g news-to-markdown@^3.2.0
```

**可选**：如果需要"搜索关键词 → 批量发布"功能，还需安装 `browser-web-search`（同时需要 OpenClaw）：

```bash
npm install -g browser-web-search@^0.3.9
```

### 4. 配置环境变量

在 ClawHub 的 Skill 设置中配置以下环境变量：

| 变量 | 说明 |
|------|------|
| `WEB_PUBLISHER_API_URL` | API 服务地址（在 tools.siping.me 中查看） |
| `WEB_PUBLISHER_USER_ID` | 用户 ID |
| `WEB_PUBLISHER_API_KEY` | API Key |

## 给 AI 的使用说明

### 🔗 与其他 Skill 配合的完整流水线

当用户想"搜索 + 发布"时，需要两个 Skill 协作：

```
browser-web-search  →  (URL 列表)  →  web-publisher
      搜索                               提取 + 发布
```

**典型例子**：用户说"帮我把今日头条最新 3 篇关于 AI Search 的文章发布到公众号"

```bash
# Step 1：用 browser-web-search 搜索，拿到 URL 列表
bws toutiao/search "ai search" --count 3 --sort time
# 返回: [{ title, url }, { title, url }, { title, url }]

# Step 2：对每个 url 调用 web-publisher 发布
scripts/run.js draft <url1>
scripts/run.js draft <url2>
scripts/run.js draft <url3>
```

**注意**：如果用户只给了关键词（没有 URL），必须先调用 `browser-web-search` 获取 URL，再调用本 Skill。如果用户直接给了 URL，跳过第一步。

---

### 单篇发布

当用户要求将网页文章发布或保存到微信公众号时，使用以下命令：

- 创建草稿: `scripts/run.js draft <url>`
- 直接发布: `scripts/run.js publish <url>`
- 可选参数: `--theme blackink`, `--rewrite`, `--style casual`

**注意**：
- 默认创建草稿，不会自动发布。用户明确说「发布」时才使用 publish 命令。
- 本地提取内容可能需要 30-60 秒，属正常现象。
- 若提示未安装依赖，请提醒用户运行 `npm install -g news-to-markdown@^3.2.0`。

## 使用示例

### 示例 1：知乎/头条文章存为草稿

> 用户：把这篇知乎文章存到公众号草稿 https://zhuanlan.zhihu.com/p/xxx

```bash
scripts/run.js draft https://zhuanlan.zhihu.com/p/xxx
```

### 示例 2：微信文章存草稿

> 用户：帮我把这篇微信文章存到公众号草稿 https://mp.weixin.qq.com/s/xxxxx

```bash
scripts/run.js draft https://mp.weixin.qq.com/s/xxxxx
```

### 示例 3：改写后存草稿

> 用户：把这篇文章改写成轻松的风格，存到草稿 https://36kr.com/p/xxx

```bash
scripts/run.js draft https://36kr.com/p/xxx --rewrite --style casual
```

### 示例 4：搜索后批量发布（配合 browser-web-search）

> 用户：帮我把今日头条最新 3 篇关于「AI Search」的文章发布到公众号草稿

```bash
# Step 1：搜索（调用 browser-web-search skill）
bws toutiao/search "AI Search" --count 3 --sort time

# Step 2：对每个 url 创建草稿（调用本 skill）
scripts/run.js draft https://www.toutiao.com/article/111
scripts/run.js draft https://www.toutiao.com/article/222
scripts/run.js draft https://www.toutiao.com/article/333
```

### 示例 5：直接发布

> 用户：把这篇文章直接发布到公众号 https://example.com/article

```bash
scripts/run.js publish https://example.com/article
```

### 示例 6：查询任务状态

> 用户：上次那个发布任务完成了吗？

```bash
scripts/run.js status job_abc123
```

### 可用选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--theme <name>` | 发布主题 | blackink |
| `--rewrite` | 启用 AI 改写 | 关闭 |
| `--style <style>` | 改写风格 | casual |
| `--prompt <text>` | 自定义改写提示 | - |

**可用主题**（`--theme` 参数值）：

| 主题 ID | 名称 | 风格 |
|---------|------|------|
| `blackink` | Black Ink | 深色模式，靛蓝点缀（默认） |
| `default` | 默认主题 | 简洁清爽，适合各类文章 |
| `orangesun` | Orange Sun | 温暖明亮，橙色系 |
| `redruby` | Red Ruby | 优雅大气，宝石红 |
| `greenmint` | Green Mint | 清新薄荷绿 |
| `purplerain` | Purple Rain | 梦幻紫色渐变 |

## 支持平台

**发布目标**（内容发布到哪里）：

| 平台 | 状态 | 说明 |
|------|------|------|
| 微信公众号 | ✅ 支持 | 创建草稿或直接发布 |
| 更多平台 | 🚧 规划中 | - |

**内容来源**（文章从哪里提取）：

内容提取由本地安装的 `news-to-markdown` 完成，支持以下平台：

| 平台 | 提取 | 可配合搜索 |
|------|------|-----------|
| 今日头条 | ✅ | ✅ |
| 微信公众号 | ✅ | ✅ |
| 知乎 | ✅ | ✅ |
| 36kr | ✅ | ✅ |
| CSDN | ✅ | ✅ |
| 小红书 | ✅ | ✅（部分内容需登录） |
| 人人都是产品经理 | ✅ | - |
| 任意网页 | ✅（通用模式） | - |

配合 `browser-web-search` 搜索时，可直接使用对应命令获取 URL 列表：

```
bws toutiao/search <关键词>
bws weixin/search  <关键词>
bws zhihu/search   <关键词>
bws 36kr/search    <关键词>
bws csdn/search    <关键词>
bws xiaohongshu/search <关键词>
```

## 工作原理

**单篇模式**（直接给 URL）：
```
URL → 本地 news-to-markdown（提取 Markdown）
    → 服务器 markdown-ai-rewriter（可选，AI 改写）
    → wechat-md-publisher（上传图片 + 发布）
```

**搜索发布模式**（配合 browser-web-search）：
```
关键词 → browser-web-search（搜索，产出 URL 列表）
       → 本地 news-to-markdown（提取正文）
       → 服务器 markdown-ai-rewriter（可选，AI 改写）
       → wechat-md-publisher（上传图片 + 发布）
```

## 安全与信任说明

### 数据流

1. **本地**：`news-to-markdown` 从目标网页提取 Markdown 文本
2. **发送到服务器**：原始 URL + 提取的 Markdown 内容 + 你的 API Key
3. **服务器端**：从 Markdown 中的图片 URL 下载图片，上传到微信，最终调用微信 API 创建草稿或发布

> ⚠️ 服务器会收到原始 URL 和全文内容，并在发布时从原图片地址下载图片。

### API 凭证与授权

- `WEB_PUBLISHER_API_KEY` 允许远程服务以你的身份向微信公众号发布内容——这是高权限操作
- IP 白名单（第 2 步）授权远程服务器 IP 直接调用微信 API，请确认你信任该 IP 归属方
- 服务提供方为 [tools.siping.me](https://tools.siping.me)，源码可在 [github.com/sipingme/web-publisher-skill](https://github.com/sipingme/web-publisher-skill) 查看

### 其他

- API Key 通过环境变量传递，不硬编码在代码中
- 默认使用 `draft` 模式，不会自动发布；`publish` 模式需用户明确指定
- 所有操作记录可在 tools.siping.me 个人页面查看

FILE:config.json
{
  "name": "web-publisher",
  "version": "0.3.5",
  "requiredEnvVars": [
    "WEB_PUBLISHER_API_URL",
    "WEB_PUBLISHER_USER_ID",
    "WEB_PUBLISHER_API_KEY"
  ],
  "requires": {
    "runtime": {
      "node": ">=18.0.0"
    },
    "binaries": [],
    "packages": {}
  },
  "skill": {
    "name": "web-publisher",
    "version": "0.3.5",
    "enabled": true,
    "autoInvoke": false
  },
  "commands": {
    "publish": {
      "script": "./scripts/run.js",
      "args": ["publish"],
      "description": "将网页文章提取并发布到平台（默认创建草稿）"
    },
    "draft": {
      "script": "./scripts/run.js",
      "args": ["draft"],
      "description": "将网页文章提取并创建草稿"
    },
    "status": {
      "script": "./scripts/run.js",
      "args": ["status"],
      "description": "查询任务状态"
    },
    "help": {
      "script": "./scripts/run.js",
      "args": ["help"],
      "description": "显示使用帮助"
    }
  },
  "environment": {
    "required": [
      "WEB_PUBLISHER_API_URL",
      "WEB_PUBLISHER_USER_ID",
      "WEB_PUBLISHER_API_KEY"
    ],
    "optional": []
  },
  "install": {
    "type": "config-only",
    "autoInstall": true,
    "riskLevel": "low",
    "riskReason": "此 Skill 仅通过 HTTP API 调用远程服务，不安装任何第三方包，不执行本地命令。",
    "requiresApproval": false
  },
  "dependencies": {
    "npm": [],
    "binaries": [],
    "note": "Optional: npm install -g news-to-markdown for local extraction of Zhihu articles blocked on server."
  },
  "permissions": {
    "filesystem": {
      "read": [],
      "write": []
    },
    "network": {
      "domains": [
        "<WEB_PUBLISHER_API_URL>"
      ],
      "note": "Calls the user-configured remote Web Publisher API for article extraction and publishing"
    }
  },
  "capabilities": {
    "sensitive": [
      {
        "type": "api-credential-usage",
        "riskLevel": "medium",
        "description": "使用用户的 API Key 调用远程发布服务",
        "risks": [
          "API Key 泄露可能导致未授权发布",
          "发布操作不可撤回（publish 模式）"
        ],
        "mitigations": [
          "默认使用 draft 模式，不自动发布",
          "API Key 通过环境变量传递，不硬编码",
          "所有操作可在 tools.siping.me 审计"
        ]
      }
    ]
  }
}

FILE:README.md
# Web Publisher Skill

将任意网页文章自动提取、处理并发布到内容平台的 OpenClaw Skill。

## 功能

- **文章提取**: 从 URL 自动提取文章内容、标题、作者、封面图
- **图片处理**: 自动下载文章图片，上传到目标平台
- **AI 改写**: 可选的 AI 内容改写（Minimax）
- **平台发布**: 发布到微信公众号（更多平台即将支持）

## 快速开始

### 1. 注册并获取凭证

在 [tools.siping.me](https://tools.siping.me) 注册账号，获取用户 ID 和 API Key。

### 2. 微信公众号 IP 白名单

在微信公众平台 → 设置与开发 → 基本配置 → IP白名单 中，添加服务器 IP（在 [tools.siping.me](https://tools.siping.me) 中查看）。

### 3. 配置环境变量

在 ClawHub 的 Skill 设置中配置以下环境变量：

| 变量 | 说明 |
|------|------|
| `WEB_PUBLISHER_API_URL` | API 服务地址（在 tools.siping.me 中查看） |
| `WEB_PUBLISHER_USER_ID` | 用户 ID |
| `WEB_PUBLISHER_API_KEY` | API Key |

## 使用示例

在 OpenClaw 中与 AI 对话：

> 帮我把这篇文章存到公众号草稿 https://mp.weixin.qq.com/s/xxxxx

> 把这篇文章改写成轻松的风格，存到草稿 https://example.com/article

> 把这篇文章直接发布到公众号 https://example.com/article

## 可用选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--theme <name>` | 发布主题 | blackink |
| `--rewrite` | 启用 AI 改写 | 关闭 |
| `--style <style>` | 改写风格 | casual |
| `--prompt <text>` | 自定义改写提示 | - |

**可用主题**：`blackink`（默认）、`default`、`orangesun`、`redruby`、`greenmint`、`purplerain`

## 支持平台

| 平台 | 提取 | 发布 | 状态 |
|------|------|------|------|
| 微信公众号 | ✅ | ✅ | 已支持 |
| 今日头条 | ✅ | - | 计划中 |
| 小红书 | ✅ | - | 计划中 |

## 工作原理

```
URL → news-to-markdown（提取+下载图片）
    → markdown-ai-rewriter（可选，AI 改写）
    → wechat-md-publisher（上传图片+发布）
```

## License

MIT

FILE:scripts/run.js
#!/usr/bin/env node

// 将全局 node_modules 注入 NODE_PATH，解决运行环境（如 ClawHub）未设置 NODE_PATH 的问题
// 必须在任何 require() 之前执行
;(function initGlobalModulePaths() {
  const path = require('path');
  const Module = require('module');
  const globalModules = path.join(path.dirname(process.execPath), '..', 'lib', 'node_modules');
  const existing = (process.env.NODE_PATH || '').split(':').filter(Boolean);
  if (!existing.includes(globalModules)) {
    process.env.NODE_PATH = [globalModules, ...existing].join(':');
    Module._initPaths(); // 重新初始化 require 搜索路径
  }
})();

const POLL_INTERVAL_MS = 5000;
const MAX_POLL_ATTEMPTS = 120; // 最长等待 10 分钟，避免假超时导致 AI 重试产生重复草稿

function loadNewsToMarkdown() {
  try {
    return require('news-to-markdown');
  } catch {
    throw new Error('news-to-markdown 未安装。请运行: npm install -g news-to-markdown');
  }
}

async function extractMarkdownLocally(url) {
  const { NewsToMarkdownConverter } = loadNewsToMarkdown();
  const conv = new NewsToMarkdownConverter();

  // 显示计时进度（本地提取可能需要 30-60 秒）
  let elapsed = 0;
  const timer = setInterval(() => {
    elapsed += 3;
    process.stderr.write(`\r[local] 正在提取... elapseds`);
  }, 3000);

  try {
    const r = await conv.convert({ url, timeout: 60000, includeMetadata: true });
    clearInterval(timer);
    process.stderr.write('\r');
    if (!r.markdown || r.markdown.length < 100) throw new Error('提取内容为空');
    return r.markdown;
  } catch (e) {
    clearInterval(timer);
    process.stderr.write('\r');
    throw new Error('本地提取失败: ' + e.message);
  }
}

const API_URL = process.env.WEB_PUBLISHER_API_URL;
const USER_ID = process.env.WEB_PUBLISHER_USER_ID;
const API_KEY = process.env.WEB_PUBLISHER_API_KEY;

const command = process.argv[2];
const args = process.argv.slice(3);

if (!command) {
  showHelp();
  process.exit(0);
}

function checkEnv() {
  const missing = [];
  if (!API_URL) missing.push('WEB_PUBLISHER_API_URL');
  if (!USER_ID) missing.push('WEB_PUBLISHER_USER_ID');
  if (!API_KEY) missing.push('WEB_PUBLISHER_API_KEY');
  if (missing.length > 0) {
    console.error(JSON.stringify({
      success: false,
      error: `Missing environment variables: missing.join(', ')`,
    }));
    process.exit(1);
  }
}

function parseArgs(argList) {
  const opts = {};
  for (let i = 0; i < argList.length; i++) {
    if (argList[i] === '--theme' && argList[i + 1]) {
      opts.theme = argList[++i];
    } else if (argList[i] === '--rewrite') {
      opts.rewrite = true;
    } else if (argList[i] === '--style' && argList[i + 1]) {
      opts.style = argList[++i];
    } else if (argList[i] === '--prompt' && argList[i + 1]) {
      opts.prompt = argList[++i];
    } else if (!argList[i].startsWith('--')) {
      opts.url = opts.url || argList[i];
    }
  }
  return opts;
}

async function apiRequest(method, path, body) {
  const url = `API_URLpath`;
  const options = {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-User-Id': USER_ID,
      'X-Api-Key': API_KEY,
    },
  };
  if (body) {
    options.body = JSON.stringify(body);
  }
  const res = await fetch(url, options);
  const data = await res.json();
  if (!res.ok && !data.jobId) {
    throw new Error(data.error || `API error: res.status`);
  }
  return data;
}

async function pollJob(jobId) {
  for (let i = 0; i < MAX_POLL_ATTEMPTS; i++) {
    await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
    const job = await apiRequest('GET', `/jobs/jobId`);
    if (job.status === 'completed') return job;
    if (job.status === 'failed') throw new Error(job.error || 'Job failed');
    const progress = job.progress || 0;
    const step = job.currentStep || '';
    process.stderr.write(`\r[progress%] step...`);
  }
  throw new Error('Job timed out');
}

async function runPublish(action) {
  checkEnv();

  const opts = parseArgs(args);
  if (!opts.url) {
    console.error(JSON.stringify({ success: false, error: 'Missing argument: url' }));
    process.exit(1);
  }

  const body = {
    url: opts.url,
    action,
    theme: opts.theme || 'blackink',
  };

  if (opts.rewrite) {
    body.rewrite = true;
    body.rewriteOptions = {};
    if (opts.style) body.rewriteOptions.style = opts.style;
    if (opts.prompt) body.rewriteOptions.prompt = opts.prompt;
  }

  try {
    process.stderr.write(`[local] 本地提取内容: opts.url\n`);
    body.markdown = await extractMarkdownLocally(opts.url);
    process.stderr.write(`[local] 提取成功，提交任务...\n`);
    process.stderr.write(`[0%] 提交任务...\n`);
    const response = await apiRequest('POST', '/pipeline', body);
    process.stderr.write(`任务已创建: response.jobId\n`);
    const result = await pollJob(response.jobId);
    process.stderr.write('\n');

    console.log(JSON.stringify({
      success: true,
      action: result.result?.action || action,
      title: result.result?.title || '',
      mediaId: result.result?.mediaId || undefined,
      publishId: result.result?.publishId || undefined,
      theme: result.result?.theme || body.theme,
    }, null, 2));
  } catch (err) {
    process.stderr.write('\n');
    console.error(JSON.stringify({ success: false, error: err.message }));
    process.exit(1);
  }
}

async function runStatus() {
  checkEnv();

  const jobId = args[0];
  if (!jobId) {
    console.error(JSON.stringify({ success: false, error: 'Missing argument: jobId' }));
    process.exit(1);
  }

  try {
    const job = await apiRequest('GET', `/jobs/jobId`);
    console.log(JSON.stringify(job, null, 2));
  } catch (err) {
    console.error(JSON.stringify({ success: false, error: err.message }));
    process.exit(1);
  }
}

function showHelp() {
  console.log(`
web-publisher-skill v0.3.4 — 将网页文章发布到微信公众号

用法:
  scripts/run.js <command> <url> [选项]

命令:
  draft   <url>     保存为草稿
  publish <url>     直接发布
  status  <jobId>   查询任务状态

选项:
  --theme <name>    主题（默认: blackink）
  --rewrite         启用 AI 改写
  --style <style>   改写风格: casual / formal / technical / creative
  --prompt <text>   自定义改写提示

示例:
  scripts/run.js draft https://m.toutiao.com/is/xxx/
  scripts/run.js publish https://mp.weixin.qq.com/s/xxx --theme blackink
  scripts/run.js draft https://example.com/article --rewrite --style casual
  scripts/run.js status job_abc123

环境变量（在 tools.siping.me 个人资料页获取）:
  WEB_PUBLISHER_API_URL   API 服务地址
  WEB_PUBLISHER_USER_ID   用户 ID
  WEB_PUBLISHER_API_KEY   API Key
`);
}

switch (command) {
  case 'publish':
    runPublish('publish');
    break;
  case 'draft':
    runPublish('draft');
    break;
  case 'status':
    runStatus();
    break;
  case 'help':
    showHelp();
    break;
  default:
    console.error(JSON.stringify({ success: false, error: `Unknown command: command` }));
    process.exit(1);
}

---
name: browser-web-search
description: 一行命令搜遍全网 — 55 个平台 91+ 个命令，头条、知乎、豆瓣、YouTube、GitHub、Reddit、Hacker News 等。专为 OpenClaw 设计，复用浏览器登录态，返回结构化 JSON，天然适配 AI Agent 工具调用。
version: 0.4.3
author: Ping Si <[email protected]>
type: cli
requires:
  runtime:
    - name: node
      version: ">=18.0.0"
      description: Node.js 运行时
    - name: npm
      description: Node.js 包管理器（随 Node.js 安装）
  packages:
    - npm: browser-web-search
      global: false
  binaries:
    - name: openclaw
      description: OpenClaw CLI，用于浏览器自动化
install:
  command: npm install -g [email protected]
  riskLevel: medium
  riskReason: 通过 npm 全局安装第三方包，该包会在浏览器页面上下文中执行 JavaScript。安装前请审计源码。
  requiresApproval: true
  source:
    registry: npmjs.com
    package: browser-web-search
    repository: https://github.com/sipingme/browser-web-search
    npm: https://www.npmjs.com/package/browser-web-search
  verification:
    - 安装前请审查 GitHub 仓库代码
    - 检查 npm 包的下载量和维护状态
    - 对比 npm 发布版本与 GitHub 源码是否一致
  note: 用户需先通过 npm install -g 全局安装 browser-web-search，运行时调用本地已安装的 bws 命令
capabilities:
  sensitive:
    - type: browser-session-access
      riskLevel: high
      description: 通过 OpenClaw 在已认证的浏览器标签页中执行 JavaScript
      scope: 按 adapter 域名隔离（如 zhihu.com, xiaohongshu.com）
      access:
        - 当前页面 DOM
        - 当前页面 Session（继承，非提取）
        - 站点认证数据（登录态下的 API 响应）
        - 账户保护页面内容（如私信、收藏、个人资料）
      noAccess:
        - 浏览器 Cookie 文件（不直接读取）
        - 其他域名数据
        - 用户配置目录
      risks:
        - 第三方 npm 包（browser-web-search）在页面上下文中执行，可访问站点认证数据
        - 恶意代码可能窃取 cookies 或页面内容
        - 包代码不包含在此 Skill 中，需独立审计
      mitigations:
        - adapter 脚本开源可审计
        - 按域名隔离，无法跨站访问
        - 不持久化存储任何凭证
  privacyNotice:
    summary: 此 Skill 自动复用浏览器登录态，可读取您已登录站点的任何可见数据
    details:
      - 零配置意味着 CLI 自动获得您在 OpenClaw 浏览器中的登录会话访问权
      - 可读取账户保护的页面（私信、收藏、个人资料、订单等）
      - 访问范围取决于您在目标站点的登录权限
      - 建议仅在信任 browser-web-search 包代码后使用
configPaths:
  - path: ~/.bws/
    required: false
tags:
  - browser
  - web-search
  - scraping
  - automation
  - ai-agent
repository: https://github.com/sipingme/browser-web-search-skill
package: https://github.com/sipingme/browser-web-search
npm: https://www.npmjs.com/package/browser-web-search
---

# Browser Web Search (BWS) Skill

> **一行命令，搜遍全网** — 为 AI Agent 而生的多平台内容搜索工具

把 **55 个主流平台**的搜索接口封装成统一命令行 API，让 AI Agent 直接拿到结构化 JSON，无需 API Key，无需额外配置。

## 🏗️ 架构说明

```
OpenClaw/AI Agent
    ↓ (读取 Skill 配置)
browser-web-search-skill
    ↓ (调用 CLI)
bws 命令
    ↓ (OpenClaw Browser)
目标网站（55 个平台）
```

## 🎯 核心特点

- 🔍 **跨平台搜索** — 今日头条、知乎、豆瓣、YouTube、GitHub、Reddit、Hacker News… 一套语法搞定
- 🔑 **无需 API Key** — 复用浏览器登录态，开箱即用
- 🤖 **AI Agent 友好** — 结构化 JSON 输出，支持 `--jq` 过滤，天然适配 LLM 工具调用
- ⚡ **零配置** — 无需 Chrome Extension，无需后台 Daemon

## 📋 安装

```bash
npm install -g [email protected]
```

### 验证安装

```bash
bws --version
bws site list
```

## 🚀 快速开始

```bash
# 搜索今日头条关于 "ai search" 的最新文章
bws site toutiao/search "ai search"

# 搜索知乎，返回 5 条
bws site zhihu/search "ai agent" --count 5

# Hacker News 最新讨论（按时间）
bws site hn/search "llm" --sort date

# GitHub 热门仓库（按 Star 数）
bws site github/search "ai search" --sort stars

# Reddit 最新帖子
bws site reddit/search "ai search" --sort new

# YouTube 视频搜索
bws site youtube/search "ai agent tutorial"

# 查看所有可用命令
bws site list
```

## 📊 内置平台（55 个）

> 🔓 无需登录 · 🔐 需登录该站账号 · 🔀 依具体命令而定

### 🇨🇳 国内平台（30 个）

| 平台 | 说明 | 登录 | 命令 |
|-----|------|:----:|-----|
| **今日头条** | 新闻资讯 | 🔀 | `toutiao/search`, `toutiao/hot`, `toutiao/feed` |
| **澎湃新闻** | 权威新闻 | 🔓 | `thepaper/search`, `thepaper/hot` |
| **腾讯新闻** | 热点新闻 | 🔓 | `qqnews/search`, `qqnews/hot` |
| **网易新闻** | 热点新闻 | 🔓 | `netease/search`, `netease/hot` |
| **新浪新闻** | 门户新闻 | 🔓 | `sina/search`, `sina/hot` |
| **36kr** | 科技创投 | 🔓 | `36kr/search`, `36kr/newsflash`, `36kr/article` |
| **虎嗅** | 科技商业媒体 | 🔓 | `huxiu/search` |
| **华尔街见闻** | 财经资讯 | 🔓 | `wallstreetcn/search` |
| **东方财富** | 股票行情 & 财经新闻 | 🔓 | `eastmoney/stock`, `eastmoney/news` |
| **掘金** | 技术社区 | 🔓 | `juejin/search` |
| **CSDN** | 开发者社区 | 🔓 | `csdn/search` |
| **博客园** | 技术博客 | 🔓 | `cnblogs/search` |
| **V2EX** | 技术社区 | 🔓 | `v2ex/search` |
| **Baidu** | 百度搜索 | 🔓 | `baidu/search` |
| **虎扑** | 体育社区 | 🔓 | `hupu/search` |
| **有道翻译** | 中英词典/翻译 | 🔓 | `youdao/translate` |
| **什么值得买** | 好价/优惠聚合 | 🔓 | `smzdm/search` |
| **InfoQ** | 技术媒体 | 🔓 | `infoq/search` |
| **微信公众号** | 公众号文章 | 🔐 | `weixin/search`, `weixin/article` |
| **小红书** | 生活分享 | 🔐 | `xiaohongshu/search`, `xiaohongshu/note`, `xiaohongshu/comments`, `xiaohongshu/user_posts`, `xiaohongshu/me`, `xiaohongshu/feed` |
| **知乎** | 问答社区 | 🔀 | `zhihu/search`, `zhihu/hot`, `zhihu/question`, `zhihu/me` |
| **微博** | 社交热搜 | 🔐 | `weibo/search`, `weibo/hot` |
| **Bilibili** | 视频弹幕 | 🔀 | `bilibili/search`, `bilibili/popular`, `bilibili/trending`, `bilibili/ranking`, `bilibili/video`, `bilibili/comments`, `bilibili/history`, `bilibili/me`, `bilibili/feed` |
| **雪球** | 股票社区 | 🔐 | `xueqiu/search` |
| **BOSS直聘** | 招聘平台 | 🔀 | `boss/search`, `boss/detail` |
| **即刻** | 兴趣社区 | 🔐 | `jike/search` |
| **豆瓣** | 影视/书籍评分社区 | 🔐 | `douban/search`, `douban/movie`, `douban/movie-hot`, `douban/top250`, `douban/comments` |
| **起点中文网** | 网络小说 | 🔐 | `qidian/search` |
| **携程** | 旅行/酒店/景点 | 🔐 | `ctrip/search` |

### 🌏 国际平台（25 个）

| 平台 | 说明 | 登录 | 命令 |
|-----|------|:----:|-----|
| **Google** | 谷歌搜索 | 🔓 | `google/search` |
| **Bing** | 必应搜索 | 🔓 | `bing/search` |
| **DuckDuckGo** | 隐私优先搜索 | 🔓 | `duckduckgo/search` |
| **GitHub** | 代码托管 | 🔓 | `github/search` |
| **Hacker News** | 科技社区 (YC) | 🔓 | `hn/search` |
| **Reddit** | 英文社区 | 🔓 | `reddit/search` |
| **BBC** | 国际新闻 | 🔓 | `bbc/news` |
| **Reuters** | 路透社新闻 | 🔓 | `reuters/search` |
| **The Verge** | 科技媒体 | 🔓 | `verge/search` |
| **Ars Technica** | 深度科技媒体 | 🔓 | `ars/search` |
| **Engadget** | 科技消费媒体 | 🔓 | `engadget/search` |
| **Stack Overflow** | 开发者问答 | 🔓 | `stackoverflow/search` |
| **Dev.to** | 开发者社区 | 🔓 | `devto/search` |
| **npm** | Node.js 包 | 🔓 | `npm/search` |
| **PyPI** | Python 包 | 🔓 | `pypi/search` |
| **arXiv** | 学术论文 | 🔓 | `arxiv/search` |
| **IMDb** | 全球最大影视数据库 | 🔓 | `imdb/search`, `imdb/movie`, `imdb/top250` |
| **Genius** | 歌词/歌曲数据库 | 🔓 | `genius/search` |
| **Wikipedia** | 百科全书 | 🔓 | `wikipedia/search`, `wikipedia/summary` |
| **Open Library** | 图书数据库 | 🔓 | `openlibrary/search` |
| **Yahoo Finance** | 美股/港股行情 | 🔓 | `yahoo-finance/quote` |
| **GSMArena** | 手机规格数据库 | 🔓 | `gsmarena/search` |
| **Product Hunt** | 科技产品发现 | 🔓 | `producthunt/today` |
| **X (Twitter)** | 社交媒体 | 🔐 | `x/search` |
| **LinkedIn** | 职业社交 | 🔐 | `linkedin/search` |
| **YouTube** | 视频 & 字幕 & 评论 | 🔀 | `youtube/search`, `youtube/video`, `youtube/transcript`, `youtube/transcript-by-id`, `youtube/comments`, `youtube/channel`, `youtube/feed` |

## 🔧 命令参考

```bash
bws site list                        # 列出所有 adapter
bws site info <name>                 # 查看 adapter 参数说明
bws site <name> [args...]            # 运行 adapter
bws site <name> --count 5           # 限制返回数量
bws site <name> --json               # 输出原始 JSON
bws site <name> --jq '.items[].url' # jq 过滤提取字段
```

## 📋 标准操作流程 (SOP)

### 操作 1：跨平台搜索

**场景**：用户想搜索多个平台关于某话题的最新内容

```bash
# 国内平台
bws site toutiao/search "ai agent" --count 5
bws site zhihu/search "ai agent" --count 5
bws site huxiu/search "ai agent" --count 5

# 国际平台
bws site hn/search "ai agent" --sort date --count 5
bws site reddit/search "ai agent" --sort new --count 5
bws site github/search "ai agent" --sort stars --count 5
```

---

### 操作 2：获取热点资讯

```bash
bws site zhihu/hot        # 知乎热榜
bws site weibo/hot        # 微博热搜
bws site toutiao/hot      # 今日头条热榜
bws site thepaper/hot     # 澎湃新闻热点
bws site bilibili/trending  # B 站热搜词
bws site bilibili/popular   # B 站全站热门
```

---

### 操作 3：使用 jq 过滤数据

```bash
# 只提取标题
bws site zhihu/search "大模型" --jq '[.items[].title]'

# 只提取 URL 列表
bws site hn/search "llm" --jq '[.items[].url]'

# 提取标题+日期
bws site toutiao/search "ai" --jq '[.items[] | {title, date}]'
```

---

### 操作 4：影视 / 娱乐内容

```bash
# 豆瓣搜索影视
bws site douban/search "三体"
bws site douban/movie-hot

# IMDb 搜索
bws site imdb/search "Inception"
bws site imdb/top250 --count 10

# YouTube 视频与字幕
bws site youtube/search "ai tutorial"
bws site youtube/transcript-by-id --id dQw4w9WgXcQ
```

---

### 操作 5：开发者资源搜索

```bash
# 搜索 npm 包
bws site npm/search "langchain"

# 搜索 PyPI 包
bws site pypi/search "openai"

# arXiv 论文
bws site arxiv/search "retrieval augmented generation" --count 5

# Stack Overflow
bws site stackoverflow/search "python async await"
```

---

### 操作 6：登录态管理

需要登录的站点（微信公众号、小红书、微博、X、豆瓣等）：

```bash
# 在 OpenClaw 浏览器中登录
openclaw browser open https://weixin.qq.com
openclaw browser open https://x.com
openclaw browser open https://www.xiaohongshu.com
openclaw browser open https://www.douban.com

# 登录完成后重试
bws site weixin/search "ai"
bws site douban/search "三体"
```

---

## 🔧 技术架构：如何访问登录态

```
bws 命令
    ↓ 调用
openclaw browser evaluate <script>
    ↓ 在已打开的标签页中执行 JavaScript
目标网站（使用该标签页的登录态）
```

| 访问内容 | 是否访问 | 说明 |
|---------|---------|------|
| 浏览器 Cookie 文件 | ❌ 否 | 不直接读取 `~/.config/chromium/Cookies` 等文件 |
| 用户配置目录 | ❌ 否 | 不访问 `~/.bws/` 以外的配置 |
| 其他网站数据 | ❌ 否 | 只能访问 adapter 指定的域名 |
| 当前页面 DOM | ✅ 是 | adapter 脚本在页面中执行 |
| 当前页面 Session | ✅ 是 | 继承页面的登录状态 |

## 🔒 安全性说明

- ✅ 所有操作在本地执行
- ✅ 按域名隔离，无法跨站访问
- ❌ 不会收集用户信息
- ❌ 不会上传到第三方服务器

## 🎓 示例对话

**用户**：搜索头条最新 3 篇关于 AI Agent 的文章

```bash
bws site toutiao/search "AI Agent" --count 3
```

---

**用户**：看看 Hacker News 上关于 LLM 的最新讨论

```bash
bws site hn/search "llm" --sort date --count 5
```

---

**用户**：GitHub 上 ai search 相关的热门项目

```bash
bws site github/search "ai search" --sort stars --count 5
```

---

**用户**：豆瓣电影 Top 10

```bash
bws site douban/top250 --count 10
```

---

**用户**：YouTube 搜索 AI 教程

```bash
bws site youtube/search "ai agent tutorial" --count 10
```

---

## 📚 参考资料

- [项目 GitHub](https://github.com/sipingme/browser-web-search-skill)
- [browser-web-search 核心库](https://github.com/sipingme/browser-web-search)
- [npm 包](https://www.npmjs.com/package/browser-web-search)

---

## 📝 维护说明

- **版本**: 0.4.3
- **最后更新**: 2026-04-26
- **维护者**: Ping Si <[email protected]>
- **许可证**: MIT

---

## ✅ 首次成功检查清单

- [ ] 安装工具：`npm install -g [email protected]`
- [ ] 验证版本：`bws --version`
- [ ] 查看命令：`bws site list`
- [ ] 测试搜索：`bws site zhihu/search "ai" --count 3`
- [ ] 看到 JSON 输出

FILE:config.json
{
  "name": "browser-web-search",
  "version": "0.4.3",
  "requiredEnvVars": [],
  "requires": {
    "runtime": {
      "node": ">=18.0.0"
    },
    "binaries": ["openclaw", "bws"],
    "packages": {
      "npm": "[email protected]"
    }
  },
  "skill": {
    "name": "browser-web-search",
    "version": "0.4.3",
    "enabled": true,
    "autoInvoke": false
  },
  "commands": {
    "list": {
      "script": "./scripts/run.js",
      "args": ["list"],
      "description": "列出所有可用 adapter"
    },
    "search": {
      "script": "./scripts/run.js",
      "args": ["search"],
      "description": "搜索 adapter"
    },
    "info": {
      "script": "./scripts/run.js",
      "args": ["info"],
      "description": "查看 adapter 详情"
    },
    "run": {
      "script": "./scripts/run.js",
      "args": ["run"],
      "description": "运行 adapter"
    },
    "help": {
      "script": "./scripts/postinstall.js",
      "args": [],
      "description": "显示使用帮助"
    }
  },
  "environment": {
    "required": [
      "NODE_VERSION>=18.0.0"
    ],
    "optional": []
  },
  "install": {
    "type": "npm-global",
    "package": "browser-web-search",
    "version": "0.4.3",
    "command": "npm install -g [email protected]",
    "binary": "bws",
    "global": true,
    "autoInstall": false,
    "autoUpdate": false,
    "riskLevel": "medium",
    "riskReason": "通过 npm 全局安装第三方包，该包会在浏览器页面上下文中执行 JavaScript。安装前请审计源码。",
    "requiresApproval": true,
    "source": {
      "type": "npm",
      "registry": "https://registry.npmjs.org",
      "package": "browser-web-search",
      "repository": "https://github.com/sipingme/browser-web-search",
      "license": "MIT",
      "audit": "https://github.com/sipingme/browser-web-search/blob/main/src/index.ts"
    },
    "verification": {
      "command": "bws --version",
      "expectedOutput": "0.4.3"
    }
  },
  "dependencies": {
    "npm": [
      "[email protected]"
    ],
    "binaries": [
      "openclaw"
    ],
    "note": "Package is installed globally via npm. Requires OpenClaw CLI for browser automation."
  },
  "permissions": {
    "filesystem": {
      "read": [],
      "write": ["~/.bws/"]
    },
    "network": {
      "domains": [
        "registry.npmjs.org",
        "*.npmjs.com",
        "*.zhihu.com",
        "*.xiaohongshu.com",
        "*.bilibili.com",
        "*.thepaper.cn",
        "*.qq.com",
        "*.163.com",
        "*.sina.com.cn",
        "*.weibo.com",
        "*.sogou.com",
        "*.weixin.qq.com",
        "*.toutiao.com",
        "*.36kr.com",
        "*.baidu.com",
        "*.bing.com",
        "*.google.com",
        "*.csdn.net",
        "*.cnblogs.com",
        "*.zhipin.com",
        "*.juejin.cn",
        "*.v2ex.com",
        "*.infoq.cn",
        "*.huxiu.com",
        "api-search.huxiu.com",
        "*.wallstreetcn.com",
        "api-one-wscn.awtmt.com",
        "*.xueqiu.com",
        "*.x.com",
        "*.twitter.com",
        "*.reddit.com",
        "*.ycombinator.com",
        "hn.algolia.com",
        "*.github.com",
        "api.github.com",
        "*.theverge.com",
        "*.arstechnica.com",
        "*.engadget.com",
        "*.douban.com",
        "*.eastmoney.com",
        "*.jike.ruguoapp.com",
        "*.hupu.com",
        "*.linkedin.com",
        "*.youtube.com",
        "*.googleapis.com",
        "*.arxiv.org",
        "*.bbc.com",
        "*.bbc.co.uk",
        "*.reuters.com",
        "*.dev.to",
        "*.stackoverflow.com",
        "*.pypi.org",
        "*.imdb.com",
        "*.genius.com",
        "*.gsmarena.com",
        "*.producthunt.com",
        "*.wikipedia.org",
        "*.openlibrary.org",
        "*.yahoo.com",
        "*.youdao.com",
        "*.smzdm.com",
        "*.qidian.com",
        "*.duckduckgo.com",
        "*.ctrip.com",
        "*.thehackernews.com",
        "*.duckduckgo.com"
      ],
      "note": "访问支持的平台域名，通过 OpenClaw 浏览器执行"
    },
    "browser": {
      "type": "openclaw",
      "access": [
        "当前页面 DOM",
        "当前页面 Session（继承登录态）",
        "站点 API 响应"
      ],
      "scope": "按 adapter 域名隔离"
    }
  },
  "capabilities": {
    "sensitive": [
      {
        "type": "browser-session-access",
        "riskLevel": "high",
        "description": "通过 OpenClaw 在已认证的浏览器标签页中执行 JavaScript",
        "scope": "按 adapter 域名隔离",
        "risks": [
          "第三方 npm 包在页面上下文中执行，可访问站点认证数据",
          "恶意代码可能窃取 cookies 或页面内容",
          "包代码不包含在此 Skill 中，需独立审计"
        ],
        "mitigations": [
          "adapter 脚本开源可审计",
          "按域名隔离，无法跨站访问",
          "不持久化存储任何凭证"
        ]
      }
    ],
    "privacyNotice": {
      "summary": "此 Skill 自动复用浏览器登录态，可读取您已登录站点的任何可见数据",
      "details": [
        "零配置意味着 CLI 自动获得您在 OpenClaw 浏览器中的登录会话访问权",
        "可读取账户保护的页面（私信、收藏、个人资料等）",
        "访问范围取决于您在目标站点的登录权限"
      ]
    }
  }
}

FILE:README.md
# Browser Web Search Skill

> **一行命令，搜遍全网** — 55 个平台 91+ 个命令，专为 OpenClaw 与 AI Agent 设计

## 快速开始

```bash
# 安装
npm install -g [email protected]

# 查看所有命令
bws site list

# 搜索示例
bws site toutiao/search "ai search"              # 今日头条
bws site zhihu/search "ai agent" --count 5      # 知乎
bws site hn/search "llm" --sort date            # Hacker News
bws site github/search "ai search" --sort stars # GitHub
bws site youtube/search "ai agent"              # YouTube

# jq 过滤
bws site zhihu/search "ai" --jq '[.items[].url]'
```

## 内置平台（55 个）

### 🇨🇳 国内平台（30 个）

| 平台 | 命令 |
|-----|------|
| **今日头条** | `toutiao/search`, `toutiao/hot`, `toutiao/feed` |
| **微信公众号** | `weixin/search`, `weixin/article` |
| **小红书** | `xiaohongshu/search`, `xiaohongshu/note`, `xiaohongshu/comments`, `xiaohongshu/user_posts`, `xiaohongshu/me`, `xiaohongshu/feed` |
| **知乎** | `zhihu/search`, `zhihu/hot`, `zhihu/question`, `zhihu/me` |
| **微博** | `weibo/search`, `weibo/hot` |
| **Bilibili** | `bilibili/search`, `bilibili/popular`, `bilibili/trending`, `bilibili/ranking`, `bilibili/video`, `bilibili/comments`, `bilibili/history`, `bilibili/me`, `bilibili/feed` |
| **澎湃新闻** | `thepaper/search`, `thepaper/hot` |
| **腾讯新闻** | `qqnews/search`, `qqnews/hot` |
| **网易新闻** | `netease/search`, `netease/hot` |
| **新浪新闻** | `sina/search`, `sina/hot` |
| **36kr** | `36kr/search`, `36kr/newsflash`, `36kr/article` |
| **虎嗅** | `huxiu/search` |
| **华尔街见闻** | `wallstreetcn/search` |
| **东方财富** | `eastmoney/stock`, `eastmoney/news` |
| **雪球** | `xueqiu/search` |
| **掘金** | `juejin/search` |
| **CSDN** | `csdn/search` |
| **博客园** | `cnblogs/search` |
| **V2EX** | `v2ex/search` |
| **BOSS直聘** | `boss/search`, `boss/detail` |
| **Baidu** | `baidu/search` |
| **即刻** | `jike/search` |
| **虎扑** | `hupu/search` |
| **豆瓣** | `douban/search`, `douban/movie`, `douban/movie-hot`, `douban/top250`, `douban/comments` |
| **什么值得买** | `smzdm/search` |
| **起点中文网** | `qidian/search` |
| **有道翻译** | `youdao/translate` |
| **携程** | `ctrip/search` |
| **InfoQ** | `infoq/search` |

### 🌏 国际平台（25 个）

| 平台 | 命令 |
|-----|------|
| **Google** | `google/search` |
| **Bing** | `bing/search` |
| **DuckDuckGo** | `duckduckgo/search` |
| **GitHub** | `github/search` |
| **Hacker News** | `hn/search` |
| **Reddit** | `reddit/search` |
| **X (Twitter)** | `x/search` |
| **The Verge** | `verge/search` |
| **Ars Technica** | `ars/search` |
| **Engadget** | `engadget/search` |
| **LinkedIn** | `linkedin/search` |
| **BBC** | `bbc/news` |
| **Reuters** | `reuters/search` |
| **Stack Overflow** | `stackoverflow/search` |
| **Dev.to** | `devto/search` |
| **npm** | `npm/search` |
| **PyPI** | `pypi/search` |
| **arXiv** | `arxiv/search` |
| **YouTube** | `youtube/search`, `youtube/video`, `youtube/transcript`, `youtube/transcript-by-id`, `youtube/comments`, `youtube/channel`, `youtube/feed` |
| **IMDb** | `imdb/search`, `imdb/movie`, `imdb/top250` |
| **Genius** | `genius/search` |
| **GSMArena** | `gsmarena/search` |
| **Product Hunt** | `producthunt/today` |
| **Wikipedia** | `wikipedia/search`, `wikipedia/summary` |
| **Open Library** | `openlibrary/search` |
| **Yahoo Finance** | `yahoo-finance/quote` |

## 环境要求

- Node.js >= 18.0.0
- OpenClaw 环境

## 文档

详细使用说明：[SKILL.md](./SKILL.md)

## 链接

- [GitHub](https://github.com/sipingme/browser-web-search)
- [npm](https://www.npmjs.com/package/browser-web-search)

## License

MIT

FILE:scripts/postinstall.js
#!/usr/bin/env node

/**
 * browser-web-search-skill postinstall / help script
 * 显示安装后的使用说明
 */

const REQUIRED_VERSION = '0.3.8';

console.log(`
╔══════════════════════════════════════════════════════════════════╗
║           Browser Web Search Skill 安装完成                       ║
╚══════════════════════════════════════════════════════════════════╝

把任何网站变成命令行 API，专为 OpenClaw 设计，复用浏览器登录态。

📦 内置平台 (17 平台，37 命令):
   知乎、小红书、B站、今日头条、36kr、澎湃、腾讯、网易、
   新浪、微博、微信公众号、百度、Bing、Google、CSDN、博客园、BOSS直聘

� 安装:
   npm install -g browser-web-search@REQUIRED_VERSION

🚀 快速开始:

   # 查看所有可用命令
   bws site list

   # 运行 adapter
   bws zhihu/hot
   bws xiaohongshu/search "旅行"
   bws bilibili/popular

   # JSON 输出 + jq 过滤
   bws zhihu/hot --json
   bws zhihu/hot --jq '.[].title'

⚠️  前提条件:
   - Node.js >= 18.0.0
   - OpenClaw 环境（openclaw 命令可用）
   - 如需登录态，请先在 OpenClaw 浏览器中登录目标网站

🔐 登录态管理:
   如果命令返回 401/403 错误，请在 OpenClaw 浏览器中登录：
   openclaw browser open https://xiaohongshu.com

📖 详细文档: 查看 SKILL.md

⚡ 安全提示:
   browser-web-search 会在浏览器页面上下文中执行 JavaScript，可访问站点认证数据。
   使用前请审计源码: https://github.com/sipingme/browser-web-search
`);

FILE:scripts/run.js
#!/usr/bin/env node

const { spawnSync } = require('node:child_process');

// 所需版本（与 config.json 中 dependencies.npm 保持一致）
const REQUIRED_VERSION = '0.3.8';

const command = process.argv[2];
const args = process.argv.slice(3);

if (!command) {
  showHelp();
  process.exit(0);
}

const run = (cmd, cmdArgs) => {
  const result = spawnSync(cmd, cmdArgs, { stdio: 'inherit' });
  if (result.error) {
    console.error(JSON.stringify({ success: false, error: result.error.message }));
    process.exit(1);
  }
  process.exit(result.status ?? 1);
};

/**
 * 使用全局安装的 bws CLI 执行命令
 */
const runBws = (cliArgs) => {
  run('bws', cliArgs);
};

function showHelp() {
  console.log(`
browser-web-search-skill vREQUIRED_VERSION
把任何网站变成命令行 API，专为 OpenClaw 设计

用法: 
  通过 scripts/run.js <command> [选项]
  或直接: bws [选项]

命令:
  list                列出所有可用 adapter
  search <query>      搜索 adapter
  info <name>         查看 adapter 详情
  run <name> [args]   运行 adapter
  help                显示帮助信息

安装:
  npm install -g browser-web-search@REQUIRED_VERSION

示例:
  bws site list
  bws zhihu/hot
  bws xiaohongshu/search "旅行"
  bws bilibili/popular --json

选项:
  --json              JSON 格式输出
  --jq <expr>         对 JSON 输出应用 jq 过滤

内置平台:
  知乎、小红书、B站、今日头条、36kr、澎湃、腾讯、网易、
  新浪、微博、微信公众号、百度、Bing、Google、CSDN、博客园、BOSS直聘

前提条件:
  需要 OpenClaw 环境运行（openclaw 命令可用）
`);
}

switch (command) {
  case 'list':
    runBws(['site', 'list', ...args]);
    break;
  case 'search':
    if (!args[0]) {
      console.error(JSON.stringify({ success: false, error: 'Missing argument: query' }));
      process.exit(1);
    }
    runBws(['site', 'search', ...args]);
    break;
  case 'info':
    if (!args[0]) {
      console.error(JSON.stringify({ success: false, error: 'Missing argument: name' }));
      process.exit(1);
    }
    runBws(['site', 'info', ...args]);
    break;
  case 'run':
    if (!args[0]) {
      console.error(JSON.stringify({ success: false, error: 'Missing argument: adapter name' }));
      process.exit(1);
    }
    runBws(['site', ...args]);
    break;
  case 'help':
    showHelp();
    break;
  default:
    // 如果命令包含 /，当作 adapter 名称直接运行
    if (command.includes('/')) {
      runBws([command, ...args]);
    } else {
      console.error(JSON.stringify({ success: false, error: `Unknown command: command` }));
      process.exit(1);
    }
}

---
name: markdown-ai-rewriter
description: 基于 markdown-ai-rewriter 的 Markdown AI 改写 Skill（保留结构、章节/全文模式、多模型、图片生成、视频生成、音乐生成）
version: 1.2.3
author: Ping Si <[email protected]>
user-invocable: true
requires:
  - node: ">=18.0.0"
  - npm: ">=8.0.0"
  - env:
      OPENAI_API_KEY: "OpenAI API Key（与 --provider openai 对应）"
      ANTHROPIC_API_KEY: "Anthropic API Key（与 --provider anthropic 对应）"
      AZURE_OPENAI_API_KEY: "Azure OpenAI API Key（与 --provider azure-openai 对应）"
      AZURE_OPENAI_ENDPOINT: "Azure OpenAI Endpoint（可选；或使用 --base-url）"
      GEMINI_API_KEY: "Gemini API Key（与 --provider gemini 对应）"
      DEEPSEEK_API_KEY: "DeepSeek API Key（与 --provider deepseek 对应）"
      OPENROUTER_API_KEY: "OpenRouter API Key（与 --provider openrouter 对应）"
      QWEN_API_KEY: "Qwen API Key（与 --provider qwen 对应）"
      GLM_API_KEY: "GLM API Key（与 --provider glm 对应）"
      DOUBAO_API_KEY: "豆包 API Key（与 --provider doubao 对应；视频生成使用 Seedance）"
      WENXIN_API_KEY: "文心 API Key（与 --provider wenxin 对应）"
      MINIMAX_API_KEY: "MiniMax API Key（与 --provider minimax 对应；视频生成使用 Hailuo）"
      KLING_API_KEY: "可灵 API Key（视频生成 --video-provider kling）"
      RUNWAY_API_KEY: "Runway API Key（视频生成 --video-provider runway）"
      SHARED_OPENAI_KEY: "可选：内置共享 OpenAI Key 场景使用，见下文"
      MINIMAX_BASE_URL: "可选：MiniMax API Base URL，默认 https://api.minimaxi.com/v1"
tags:
  - markdown
  - ai
  - rewriter
  - content
  - openai
  - anthropic
  - azure-openai
  - gemini
  - deepseek
  - openrouter
  - qwen
  - glm
  - doubao
  - wenxin
  - minimax
  - video
  - image
  - music
repository: https://github.com/sipingme/markdown-ai-rewriter
---

# Markdown AI Rewriter Skill

本 Skill 对应 npm 包 **[markdown-ai-rewriter](https://www.npmjs.com/package/markdown-ai-rewriter)**（当前对齐 **v1.2.3**）：在 **尽量保留标题、代码块、表格、图片等结构** 的前提下，用大模型改写正文（润色、降重、换风格等），并支持 **图片生成**（图生图）、**视频生成**（文生视频）和 **音乐生成**（文生音乐）。

## 🚀 安装后快速开始

安装完成后，运行以下命令查看可用功能：

```bash
md-rewrite rewrite -i article.md -o out.md -p openai -v
```

输出示例：
```
📋 功能状态：
   ⬚ 文章改写 (--rewrite)
   ⬚ 图片生成 (--process-images)
   ⬚ 视频生成 (--generate-video)

⚠️  未启用任何功能。请使用以下选项启用：
   --rewrite         启用文章改写
   --process-images  启用图片生成
   --generate-video  启用视频生成
```

**重要**：v0.5.2 起，默认不启用任何功能，需要显式指定要启用的功能。

## 核心特点（先看这个）

**一句话定位**：这是一个面向生产场景的 Markdown 改写 Skill，重点是"**改写质量** + **结构稳定** + **成本可控**"。

- **结构稳定优先**：尽量保留标题层级、代码块、表格、图片位置，减少"改完排版坏掉"。
- **双模式可切换**：`section` 适合中长文批量与控成本，`full` 适合短文叙事连贯。
- **多模型一套命令**：同一 CLI 只换 `-p` 和环境变量，就能切换 11 个 Provider。
- **图片生成**：支持 MiniMax、OpenAI、Gemini、豆包等图片生成。
- **视频生成**：支持 MiniMax Hailuo、豆包 Seedance、可灵、Runway 等视频生成。
- **音乐生成**：支持 MiniMax Music 2.5+ 音乐生成（纯音乐/带歌词）。
- **可落地到流水线**：适合接在抓取、清洗、发布前的"内容标准化"环节。

## 最适合的使用场景

- 你已经有 Markdown 初稿，要做润色/降重/统一风格；
- 你在做批量内容处理，希望速度和费用可控；
- 你需要兼顾国内外多个模型平台，在可用性和成本之间灵活切换；
- 你需要为文章自动生成配图、视频或背景音乐。

---

## 与旧版差异（务必知晓）

| 项目 | 当前版本 (v0.5.2) |
|------|----------|
| **默认行为** | **默认不启用任何功能**，需显式使用 `--rewrite`、`--process-images`、`--generate-video` 启用。 |
| 改写模式 | 仅 **`section`（章节，默认）** 与 **`full`（全文）**；已移除「按块/段落」模式。 |
| 模型 | **OpenAI**、**Anthropic**、**Azure OpenAI**、**Gemini**、**DeepSeek**、**OpenRouter**、**Qwen**、**GLM**、**豆包**、**文心**、**MiniMax**。 |
| 图片生成 | 支持 MiniMax、OpenAI、Gemini、豆包、Nano-Banana 等。 |
| 视频生成 | 支持 MiniMax Hailuo、豆包 Seedance 2.0/1.5/1.0、可灵、Runway Gen-4.5。 |
| 音乐生成 | 支持 MiniMax Music 2.5+（纯音乐/带歌词/自动歌词）。 |
| 章节模式 | 按标题分章并行改写；**`-c / --concurrency` 对章节模式生效**。 |
| CLI 版本号 | 从安装的包的 `package.json` 读取，与 npm 版本一致。 |

---

## 安装

全局或项目内安装均可：

```bash
npm install -g markdown-ai-rewriter
# 或
npm install markdown-ai-rewriter
```

使用 **OpenAI** 或 **MiniMax** 时，需安装 peer 依赖 **`openai`**：

```bash
npm install openai
```

使用 **Anthropic** 时：

```bash
npm install @anthropic-ai/sdk
```

可执行命令：`markdown-ai-rewrite` 或 `md-rewrite`。

---

## 环境变量

| 变量 | 用途 |
|------|------|
| `OPENAI_API_KEY` | `--provider openai` |
| `ANTHROPIC_API_KEY` | `--provider anthropic` |
| `AZURE_OPENAI_API_KEY` | `--provider azure-openai` |
| `GEMINI_API_KEY` | `--provider gemini` |
| `DEEPSEEK_API_KEY` | `--provider deepseek` |
| `OPENROUTER_API_KEY` | `--provider openrouter` |
| `QWEN_API_KEY` | `--provider qwen` |
| `GLM_API_KEY` | `--provider glm` |
| `DOUBAO_API_KEY` | `--provider doubao` |
| `WENXIN_API_KEY` | `--provider wenxin` |
| `MINIMAX_API_KEY` | `--provider minimax`（文本改写）；`--video-provider minimax`（视频生成） |
| `KLING_API_KEY` | `--video-provider kling`（可灵视频生成） |
| `RUNWAY_API_KEY` | `--video-provider runway`（Runway 视频生成） |
| `AZURE_OPENAI_ENDPOINT` | `azure-openai` 可选 endpoint（也可用 `--base-url`） |
| `MINIMAX_BASE_URL` | 可选；默认 `https://api.minimaxi.com/v1`，可按 MiniMax 文档覆盖 |
| `SHARED_OPENAI_KEY` | 可选；仅在 **未传 `apiKey`** 且代码里允许使用共享 Key 时由库内部使用（需配合 `QuotaManager` 等逻辑，见包内 README）；**常规 CLI 用法请直接设置上述各厂商 Key。** |

---

## 何时使用本 Skill

**适合触发**：

- 用户要「改写 / 润色 / 降重 / 换风格」**已有 Markdown**，且希望 **保留文档结构**；
- 提到「章节改写」「全文改写」「技术文档 / 博客 / 公众号稿」等；
- 需要指定 **casual / formal / technical / creative / custom** 风格。

**不适合**：

- 从零「写一篇新文章」且输入不是 Markdown 改写流程；
- 纯格式转换（如 MD→HTML）；
- 仅分析结构、不做改写。

**触发关键词示例**：「重写这篇 md」「改成正式一点」「全文连贯改写」「按章节改」「用 MiniMax / OpenAI / Claude」。

---

## 两种改写模式（CLI：`--mode`）

| 模式 | 说明 | 典型场景 |
|------|------|----------|
| `section`（默认） | 按指定级别标题切分，分章调用模型；可带上下文章摘要；成本与速度较可控。 | 中长文档、多章节技术文 |
| `full` | 整篇一次请求（全文模式会对图片做占位符保护再还原）；语气通常最连贯。 | 短文、强叙事、整篇语气统一 |

- `--section-level 1|2|3`：仅章节模式有效，表示按几级标题切分（默认 1 级 `#`）。
- `--mode full` 时 token 消耗可能更大，适合长文时谨慎使用。

---

## 标准 CLI 示例

### 文章改写

```bash
# 章节模式 + OpenAI（注意：需要 --rewrite 显式启用改写）
export OPENAI_API_KEY="sk-..."
md-rewrite rewrite \
  -i input.md \
  -o output.md \
  -p openai \
  --rewrite \
  -s casual \
  -c 3 \
  -v

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

# 二级标题分章
md-rewrite rewrite -i input.md -o out.md -p openai --rewrite --section-level 2

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
md-rewrite rewrite -i input.md -o out.md -p anthropic --rewrite -s formal

# DeepSeek
export DEEPSEEK_API_KEY="..."
md-rewrite rewrite -i input.md -o out.md -p deepseek --rewrite

# MiniMax（需 npm install openai）
export MINIMAX_API_KEY="..."
md-rewrite rewrite -i input.md -o out.md -p minimax --rewrite -m MiniMax-M2.1 -s casual
```

### 图片生成

```bash
# 只生成图片（不改写文章）
export MINIMAX_API_KEY="..."
md-rewrite rewrite -i input.md -o out.md -p minimax --process-images -v

# 改写 + 图片生成
md-rewrite rewrite -i input.md -o out.md -p openai --rewrite --process-images -v

# 指定图片 Provider
md-rewrite rewrite -i input.md -o out.md -p openai --process-images --image-provider doubao
```

### 视频生成

```bash
# 只生成视频（不改写文章）
export MINIMAX_API_KEY="..."
md-rewrite rewrite -i input.md -o out.md -p minimax --generate-video -v

# 改写 + 视频生成
md-rewrite rewrite -i input.md -o out.md -p openai --rewrite --generate-video -v

# 指定视频 Provider（豆包 Seedance）
export DOUBAO_API_KEY="..."
md-rewrite rewrite -i input.md -o out.md -p openai --generate-video --video-provider doubao

# 可灵视频
export KLING_API_KEY="..."
md-rewrite rewrite -i input.md -o out.md -p openai --generate-video --video-provider kling

# Runway 视频
export RUNWAY_API_KEY="..."
md-rewrite rewrite -i input.md -o out.md -p openai --generate-video --video-provider runway
```

### 音乐生成

```bash
# 纯音乐（无人声）- 从 prompt 生成
export MINIMAX_API_KEY="..."
md-rewrite music --prompt "Indie folk, melancholic, introspective" --instrumental -o bgm.mp3

# 带歌词的歌曲
md-rewrite music --prompt "Pop, upbeat, energetic" --lyrics "[verse]\nHello world\n[chorus]\nLa la la" -o song.mp3

# 从文件读取歌词
md-rewrite music --prompt "Rock, powerful" --lyrics-file lyrics.txt -o song.mp3

# 自动生成歌词（从 prompt 自动生成）
md-rewrite music --prompt "Jazz, smooth, romantic" --auto-lyrics -o song.mp3

# 从 Markdown 生成背景音乐
md-rewrite music -i article.md --instrumental -o bgm.mp3 -v
```

### 组合使用

```bash
# 改写 + 图片 + 视频（全功能）
md-rewrite rewrite -i input.md -o out.md -p openai \
  --rewrite \
  --process-images \
  --generate-video \
  -v
```

常用参数速查：`-i/-o` 输入输出，`-p` 厂商，`-k` 显式传 Key（也可全靠环境变量），`-m` 模型，`--base-url`（通用 endpoint 覆盖），`-s` 风格，`-t` 温度，`--max-tokens`，`--preserve-length`，`-c` 并发，`--mode`，`--section-level`，`--rewrite`，`--process-images`，`--generate-video`，`--video-provider`，`--image-provider`。完整列表以 `md-rewrite rewrite --help` 为准。

---

## 编程 API（TypeScript）

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

const rewriter = new MarkdownRewriter({
  provider: 'openai', // 'anthropic' | 'azure-openai' | 'gemini' | 'deepseek' | 'openrouter' | 'qwen' | 'glm' | 'doubao' | 'wenxin' | 'minimax' | 'custom'
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini',
  mode: 'section',       // 或 'full'
  sectionLevel: 1,
  concurrency: 3,
  verbose: true,
  enableRewrite: true,   // v0.5.2 起需要显式启用改写
  minimaxBaseUrl: process.env.MINIMAX_BASE_URL, // 仅 minimax 时可选
  options: {
    style: 'casual',
    temperature: 0.7,
    maxTokens: 2000,
  },
  // 图片生成配置（可选）
  imageProcessing: {
    provider: 'minimax',
    apiKey: process.env.MINIMAX_API_KEY,
  },
  // 视频生成配置（可选）
  videoProcessing: {
    provider: 'minimax', // 'minimax' | 'doubao' | 'kling' | 'runway'
    apiKey: process.env.MINIMAX_API_KEY,
    duration: 6,
  },
});

const result = await rewriter.rewrite(markdownString);
// result.rewritten, result.blocksProcessed, result.blocksRewritten
// result.imageProcessing, result.videoProcessing
```

`custom` 提供方可使用 `customProvider` 注入，详见 npm 包 README。

---

## 输出与行为说明

- **章节 / 全文** 均基于当前实现的解析与重组逻辑；**标题、代码块、表格**等会尽量保留；**图片**在全文模式下通过占位符机制处理。
- 列表、引用等是否逐条保留，与模型输出有关；若强约束，请在 `--prompt` 中明确要求。
- 统计字段 `blocksProcessed` / `blocksRewritten` 在章节模式下对应**章节单元**等粒度，与旧版「按段落块计数」的日志**不完全相同**。

---

## 常见问题

**1. 提示缺少 API Key**  
请设置与 `-p` 一致的环境变量，或使用 `-k` 传入。

**2. MiniMax 报错找不到模块**  
执行 `npm install openai`（MiniMax 使用 OpenAI 兼容客户端）。

**3. 改写后结构不满意**  
尝试切换 `--mode section` / `full`、调整 `--section-level`、缩小 `--max-tokens`、或在 `--prompt` 中强调「保留所有 Markdown 列表与表格结构」。

**4. 费用**  
以各云厂商定价为准；OpenAI 小模型、MiniMax 与 Anthropic 价差较大，README 中有量级参考。

---

## 与其他工具串联（示例）

```bash
convert-url --url "https://example.com/article" --output article.md

markdown-ai-rewrite rewrite -i article.md -o article-rewritten.md -p openai -s casual
```

发布等步骤按你的流水线工具执行即可。

---

## 维护说明

| 项目 | 值 |
|------|-----|
| 对齐包版本 | 1.2.3 |
| 仓库 | https://github.com/sipingme/markdown-ai-rewriter |
| npm | https://www.npmjs.com/package/markdown-ai-rewriter |
| 许可证 | MIT |
| 维护者 | Ping Si <[email protected]> |

---

## 相关项目

- [news-to-markdown](https://github.com/sipingme/news-to-markdown) — 网页/新闻转 Markdown  
- [wechat-md-publisher](https://github.com/sipingme/wechat-md-publisher) — Markdown 发布到微信  

FILE:config.json
{
  "skill": {
    "name": "markdown-ai-rewriter",
    "version": "1.2.3",
    "enabled": true,
    "autoInvoke": true
  },
  "commands": {
    "rewrite": {
      "script": "./scripts/run.js",
      "args": ["rewrite"],
      "description": "重写 Markdown 文件"
    },
    "check-quota": {
      "script": "./scripts/run.js",
      "args": ["check-quota"],
      "description": "检查剩余配额"
    },
    "help": {
      "script": "./scripts/postinstall.js",
      "args": [],
      "description": "显示使用帮助和 API 配置方式"
    }
  },
  "environment": {
    "required": [
      "NODE_VERSION>=18.0.0"
    ],
    "optional": [
      "OPENAI_API_KEY",
      "ANTHROPIC_API_KEY",
      "AZURE_OPENAI_API_KEY",
      "AZURE_OPENAI_ENDPOINT",
      "GEMINI_API_KEY",
      "DEEPSEEK_API_KEY",
      "OPENROUTER_API_KEY",
      "QWEN_API_KEY",
      "GLM_API_KEY",
      "DOUBAO_API_KEY",
      "WENXIN_API_KEY",
      "MINIMAX_API_KEY",
      "KLING_API_KEY",
      "RUNWAY_API_KEY"
    ]
  },
  "install": {
    "type": "npm-global",
    "package": "markdown-ai-rewriter",
    "version": "1.2.3",
    "command": "npm install -g [email protected]",
    "binary": "md-rewrite",
    "global": true,
    "autoInstall": false,
    "autoUpdate": false,
    "riskLevel": "low",
    "riskReason": "通过 npm 全局安装第三方包。安装前请审计源码。",
    "requiresApproval": true,
    "source": {
      "type": "npm",
      "registry": "https://registry.npmjs.org",
      "package": "markdown-ai-rewriter",
      "repository": "https://github.com/sipingme/markdown-ai-rewriter",
      "license": "MIT",
      "audit": "https://github.com/sipingme/markdown-ai-rewriter/blob/main/src/index.ts"
    },
    "verification": {
      "command": "md-rewrite --version",
      "expectedOutput": "1.2.3"
    }
  },
  "dependencies": {
    "npm": [
      "[email protected]"
    ],
    "note": "Package is installed globally via npm. Binary: md-rewrite"
  },
  "permissions": {
    "filesystem": {
      "read": ["*.md"],
      "write": ["~/.markdown-ai-rewriter/"]
    },
    "network": {
      "domains": [
        "registry.npmjs.org",
        "api.openai.com",
        "api.anthropic.com",
        "*.openai.azure.com",
        "generativelanguage.googleapis.com",
        "api.deepseek.com",
        "openrouter.ai",
        "dashscope.aliyuncs.com",
        "open.bigmodel.cn",
        "ark.cn-beijing.volces.com",
        "qianfan.baidubce.com",
        "api.minimax.io",
        "api.minimaxi.com"
      ]
    }
  }
}

FILE:README.md
# Markdown AI Rewriter Skill

面向 **Claw Hub** 等环境的 Skill 封装，底层使用 npm 包 **[markdown-ai-rewriter](https://www.npmjs.com/package/markdown-ai-rewriter)**（当前对齐 **v1.2.3**）：在 **尽量保留标题、代码块、表格、图片等结构** 的前提下，对 Markdown 正文做润色、降重或换表述，并支持图片、视频、音乐生成。

## 为什么用这个 Skill

- **结构保真优先**：不是“整篇丢给模型”，而是围绕 Markdown 结构做改写，减少标题错位、代码块损坏、表格变形。
- **长文可控**：默认章节模式，支持并发与分级标题切分，速度、成本、稳定性更可控。
- **连贯文风可选**：支持全文模式，适合短文/叙事类内容一次性改写。
- **模型覆盖广**：OpenAI、Anthropic、Azure OpenAI、Gemini、DeepSeek、OpenRouter、Qwen、GLM、豆包、文心、MiniMax。
- **可直接集成流水线**：命令行与脚本友好，适合接在抓取、清洗、发布流程中。

- **npm 包源码与发版**：[github.com/sipingme/markdown-ai-rewriter](https://github.com/sipingme/markdown-ai-rewriter)  
- **本 Skill 文档**（模式、参数、排错）：请读本仓库 **[SKILL.md](./SKILL.md)**

### Git 克隆

| 仓库 | HTTPS | SSH（示例） |
|------|--------|-------------|
| **本仓库**（Skill、`SKILL.md` / `README.md`） | `https://github.com/sipingme/markdown-ai-rewriter-skill.git` | `[email protected]:sipingme/markdown-ai-rewriter-skill.git` |
| **markdown-ai-rewriter**（npm 包、CLI 与 TypeScript 源码） | `https://github.com/sipingme/markdown-ai-rewriter.git` | `[email protected]:sipingme/markdown-ai-rewriter.git` |

```bash
# 克隆本 Skill 仓库
git clone https://github.com/sipingme/markdown-ai-rewriter-skill.git
cd markdown-ai-rewriter-skill

# 克隆底层 npm 包（如需改代码或本地联调）
git clone https://github.com/sipingme/markdown-ai-rewriter.git
```

版本与发版以各仓库 **`main`** 分支及 npm 上 **`markdown-ai-rewriter`** 的版本号为准。

---

## 能力概览

| 维度 | 说明 |
|------|------|
| **改写模式** | **`section`（章节，默认）**：按标题分章并行；**`full`（全文）**：整篇一次，语气更连贯。已移除旧的「按段落块」模式。 |
| **模型提供商** | **OpenAI**、**Anthropic**、**Azure OpenAI**、**Gemini**、**DeepSeek**、**OpenRouter**、**Qwen**、**GLM**、**豆包**、**文心**、**MiniMax**。 |
| **多媒体生成** | 图片生成、视频生成、音乐生成（MiniMax Music 2.5+）。 |
| **风格** | `casual` / `formal` / `technical` / `creative` / `custom`（`custom` 常配合自定义 `--prompt`）。 |
| **结构** | 解析与重组逻辑尽量保留版式；全文模式下对图片有占位符保护机制（详见包文档）。 |
| **并发** | 章节模式下 **`--concurrency`（`-c`）** 控制并行请求数。 |

## 3 步上手

1. 安装 CLI：`npm install -g markdown-ai-rewriter`
2. 配置你要用的 Provider API Key（例如 `OPENAI_API_KEY` / `DEEPSEEK_API_KEY`）
3. 运行命令：`md-rewrite rewrite -i input.md -o output.md -p openai`

---

## 前置条件

- **Node.js** ≥ 18，**npm** ≥ 8（与 [SKILL.md](./SKILL.md) 一致）。
- **API Key**（按实际选用的 `-p` 提供商配置其一或多项）：

| 用途 | 环境变量 |
|------|----------|
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Azure OpenAI | `AZURE_OPENAI_API_KEY`（可选 `AZURE_OPENAI_ENDPOINT`） |
| Gemini | `GEMINI_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Qwen | `QWEN_API_KEY` |
| GLM | `GLM_API_KEY` |
| 豆包 | `DOUBAO_API_KEY` |
| 文心 | `WENXIN_API_KEY` |
| MiniMax | `MINIMAX_API_KEY`（可选 `MINIMAX_BASE_URL`，默认 `https://api.minimaxi.com/v1`） |

在 **Claw Hub** 中配置一次后，各 Skill 可共享同一环境变量。

安装各厂商 SDK（与包 `peerDependencies` 一致）：

```bash
npm install openai                    # OpenAI 与 MiniMax 共用
npm install @anthropic-ai/sdk         # 仅 Anthropic
```

---

## 安装 CLI

```bash
npm install -g markdown-ai-rewriter
```

全局安装后可使用命令 **`markdown-ai-rewrite`** 或 **`md-rewrite`**。

---

## 最小示例（命令行）

```bash
# 章节模式（默认）+ OpenAI + 轻松风格
export OPENAI_API_KEY="sk-..."
markdown-ai-rewrite rewrite -i input.md -o output.md -p openai -s casual -v

# 全文模式（短文、强叙事）
markdown-ai-rewrite rewrite -i input.md -o out.md -p openai --mode full

# 按二级标题分章
markdown-ai-rewrite rewrite -i input.md -o out.md -p openai --section-level 2

# MiniMax
export MINIMAX_API_KEY="..."
markdown-ai-rewrite rewrite -i input.md -o out.md -p minimax -m MiniMax-M2.1 -s casual

# DeepSeek
export DEEPSEEK_API_KEY="..."
markdown-ai-rewrite rewrite -i input.md -o out.md -p deepseek

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

更多参数（`-t`、`--max-tokens`、`--preserve-length`、`-c`、`--minimax-base-url` 等）见 **`markdown-ai-rewrite rewrite --help`** 与 [SKILL.md](./SKILL.md)。

---

## 与 AI 对话时怎么说（Claw Hub）

可直接描述意图，由助手按需调用本 Skill 相关能力，例如：

- 「把这篇 `article.md` 改成正式商务风格，结构别乱。」
- 「按章节改写，并发别太高。」
- 「全文一口气改写，保持叙事连贯。」
- 「用 MiniMax / OpenAI / Claude 其中之一改写。」

不涉及「从零写长文」「只做 MD↔HTML 转换」等场景时，更适合用本 Skill；若需完整触发条件与反例，见 [SKILL.md](./SKILL.md)。

---

## 仓库结构（本 Git 仓库）

| 文件 | 作用 |
|------|------|
| [SKILL.md](./SKILL.md) | Skill 完整规范：模式、环境变量、API、FAQ、维护信息 |
| [README.md](./README.md) | 本页：快速了解能力与安装入口 |

---

## 许可证

MIT

## 作者

Ping Si <[email protected]>

FILE:scripts/postinstall.js
#!/usr/bin/env node

/**
 * 安装后提示脚本
 * 显示可用功能和 API 配置方式
 */

const CYAN = '\x1b[36m';
const GREEN = '\x1b[32m';
const YELLOW = '\x1b[33m';
const RESET = '\x1b[0m';
const BOLD = '\x1b[1m';

console.log(`
BOLDGREEN✅ [email protected] 安装成功！RESET

BOLD📋 可用功能：RESET
   CYAN--rewriteRESET         启用文章改写（润色、降重、换风格）
   CYAN--process-imagesRESET  启用图片生成（图生图）
   CYAN--generate-videoRESET  启用视频生成（文生视频）

BOLD⚙️  API 配置（设置环境变量）：RESET

   YELLOW文本改写 Provider：RESET
   export OPENAI_API_KEY="sk-..."        # OpenAI
   export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic
   export DEEPSEEK_API_KEY="..."         # DeepSeek
   export MINIMAX_API_KEY="..."          # MiniMax
   export DOUBAO_API_KEY="..."           # 豆包
   export QWEN_API_KEY="..."             # 通义千问
   export GLM_API_KEY="..."              # 智谱 GLM
   export GEMINI_API_KEY="..."           # Google Gemini

   YELLOW视频生成 Provider：RESET
   export MINIMAX_API_KEY="..."          # MiniMax Hailuo
   export DOUBAO_API_KEY="..."           # 豆包 Seedance
   export KLING_API_KEY="..."            # 可灵
   export RUNWAY_API_KEY="..."           # Runway

BOLD🚀 快速开始：RESET

   # 查看功能状态
   md-rewrite rewrite -i article.md -o out.md -p openai -v

   # 文章改写
   md-rewrite rewrite -i article.md -o out.md -p openai --rewrite -v

   # 图片生成
   md-rewrite rewrite -i article.md -o out.md -p minimax --process-images -v

   # 视频生成
   md-rewrite rewrite -i article.md -o out.md -p minimax --generate-video -v

   # 全部功能
   md-rewrite rewrite -i article.md -o out.md -p openai \\
     --rewrite --process-images --generate-video -v

BOLD📖 更多信息：RESET
   md-rewrite rewrite --help
   https://github.com/sipingme/markdown-ai-rewriter
`);

FILE:scripts/run.js
#!/usr/bin/env node

const { spawnSync } = require('node:child_process');

// 所需版本（与 config.json 中 dependencies.npm 保持一致）
const REQUIRED_VERSION = '1.2.3';

const command = process.argv[2];
const args = process.argv.slice(3);

if (!command) {
  console.error(JSON.stringify({ success: false, error: 'Missing command. Use: rewrite or check-quota' }));
  process.exit(1);
}

const run = (cmd, cmdArgs) => {
  const result = spawnSync(cmd, cmdArgs, { stdio: 'inherit' });
  if (result.error) {
    console.error(JSON.stringify({ success: false, error: result.error.message }));
    process.exit(1);
  }
  process.exit(result.status ?? 1);
};

switch (command) {
  case 'rewrite':
    // 使用全局安装的 md-rewrite 命令执行
    run('md-rewrite', ['rewrite', ...args]);
    break;
  case 'check-quota':
    console.log(JSON.stringify({
      success: true,
      message: 'check-quota is not provided by markdown-ai-rewriter CLI in this version. Please monitor quota in your provider console.'
    }));
    break;
  default:
    console.error(JSON.stringify({ success: false, error: `Unknown command: command` }));
    process.exit(1);
}

---
name: news-to-markdown-skill
description: 输入文章 URL，输出干净的 Markdown 正文。支持17个平台专项优化（头条、微信公众号、知乎、36kr、虎嗅、华尔街见闻、澎湃、InfoQ 等），双引擎提取、图片本地化、三层抓取策略。常与 browser-web-search skill 配合：先用 bws 搜索拿到 url 列表，再逐篇调用本 skill 读取正文。
version: 3.3.0
author: Ping Si <[email protected]>
user-invocable: true
requires:
  runtime:
    - name: node
      version: ">=18.0.0"
    - name: npm
      version: ">=8.0.0"
install:
  type: npx
  package: news-to-markdown
  version: "^3.3.0"
  execution: "npx --yes news-to-markdown@^3.3.0"
  riskLevel: moderate
  riskReason: "通过 npx 动态拉取并执行第三方 npm 包，存在供应链风险。使用前请审计源码。"
  source:
    registry: https://registry.npmjs.org
    repository: https://github.com/sipingme/news-to-markdown
    license: MIT
    audit: https://github.com/sipingme/news-to-markdown/blob/main/src/index.ts
tags:
  - news
  - markdown
  - converter
  - extractor
  - web-scraping
  - toutiao
  - wechat
  - 36kr
  - bilibili
  - csdn
repository: https://github.com/sipingme/news-to-markdown-skill
core-library: https://github.com/sipingme/news-to-markdown
---

# news-to-markdown Skill

> 输入文章 URL，输出干净的 Markdown 正文。17 个平台专项优化，为 AI Agent 而生。

## 🎯 核心特点

- 📰 **17 个平台专项适配** — 头条、微信、知乎、36kr、虎嗅、华尔街见闻、澎湃、InfoQ 等
- 🔄 **三层抓取策略** — curl → wget → Playwright 自动回退，静态/动态页面均支持
- 🧠 **双引擎提取** — Mozilla Readability + news-extractor-node 智能取优
- 🖼️ **图片本地化** — 可选将远程图片下载到本地，防止 URL 过期
- 📦 **零安装** — 通过 `npx` 按需拉取，无需全局安装

---

## 🚀 快速开始

```bash
# 基本转换，输出到终端
npx --yes news-to-markdown@^3.3.0 --url "https://www.toutiao.com/article/123"

# 保存到文件
npx --yes news-to-markdown@^3.3.0 --url "https://mp.weixin.qq.com/s/xxx" --output article.md

# 下载图片到本地（推荐，防止图片 URL 过期）
npx --yes news-to-markdown@^3.3.0 --url "https://www.toutiao.com/article/123" \
  --download-images --output-dir ./article

# 只要正文
npx --yes news-to-markdown@^3.3.0 --url "https://www.zhihu.com/p/xxx" --no-metadata
```

---

## 🔗 与 browser-web-search 配合使用

最常见的 AI Agent 编排模式：

```
browser-web-search  →  搜索，产出 URL 列表
news-to-markdown    →  读取正文，产出 Markdown
```

```bash
# Step 1：用 bws 搜索，拿到文章 URL 列表
bws site toutiao/search "ai agent" --count 3

# Step 2：对每个 URL 提取正文
npx --yes news-to-markdown@^3.3.0 --url "https://www.toutiao.com/article/111"
npx --yes news-to-markdown@^3.3.0 --url "https://www.toutiao.com/article/222"
npx --yes news-to-markdown@^3.3.0 --url "https://www.toutiao.com/article/333"
```

**适用搜索命令**（browser-web-search 0.4.2，30 个平台）：

- 🇨🇳 国内文章类：`toutiao/search`、`weixin/search`、`zhihu/search`、`36kr/search`、`xiaohongshu/search`、`huxiu/search`、`wallstreetcn/search`、`thepaper/search`、`qqnews/search`、`netease/search`、`sina/search`、`juejin/search`、`csdn/search`、`cnblogs/search`、`infoq/search`
- 🌏 国际文章类：`verge/search`、`ars/search`、`engadget/search`、`hn/search`（外链文章）

> **注意**：`github/search`、`reddit/search`、`x/search`、`weibo/search` 等平台的 bws 结果本身是结构化数据，无需再用本工具提取正文。

---

## 📋 支持平台

### 专项优化平台（17 个）

| 平台 | 域名 | 专项说明 |
|-----|------|------|
| **今日头条** | toutiao.com | 标题规范化、`data-src` 图片、列表修复 |
| **微信公众号** | mp.weixin.qq.com | `#js_content` 提取、移动端 UA 回退 |
| **小红书** | xiaohongshu.com | `.note-content` 提取、懒加载图片 |
| **知乎** | zhihu.com | 真实 Chrome 绕过 zse-ck 反爬 |
| **36kr** | 36kr.com | 自动转移动端 URL 绕过反爬 |
| **虎嗅** | huxiu.com | 正文区域提取、懒加载图片修复 |
| **华尔街见闻** | wallstreetcn.com | 财经正文提取、去高亮 `<em>` 标签 |
| **澎湃新闻** | thepaper.cn | `.news_txt` 正文区域提取 |
| **InfoQ** | infoq.cn / infoq.com | 技术文章正文提取 |
| **Bilibili 专栏** | bilibili.com | `/read/` 路径文章提取 |
| **掘金** | juejin.cn | 代码块与正文提取 |
| **CSDN** | csdn.net | 去广告侧边栏、`#content_views` 提取 |
| **博客园** | cnblogs.com | 技术博客正文提取 |
| **简书** | jianshu.com | 文章正文提取 |
| **SegmentFault** | segmentfault.com | 技术问答正文提取 |
| **开源中国** | oschina.net | 资讯正文提取 |
| **人人都是产品经理** | woshipm.com | 产品文章正文提取 |

其余平台（The Verge、Ars Technica、Engadget 等英文站）走通用 Readability 算法。

---

## 🔧 命令参数

```bash
npx --yes news-to-markdown@^3.3.0 --url <URL> [选项]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--url` | string | 文章 URL（必填） |
| `--output` | string | 输出文件路径（默认输出到终端） |
| `--download-images` | flag | 下载图片到本地（推荐）|
| `--output-dir` | string | 图片输出目录（`--download-images` 时使用） |
| `--no-metadata` | flag | 只要正文，不含标题/作者/时间 |
| `--selector` | string | 自定义内容区域 CSS 选择器 |
| `--noise` | string | 移除元素的选择器，逗号分隔 |
| `--verbose` | flag | 详细日志（调试用） |

---

## 📋 标准操作流程 (SOP)

### 操作 1：基础文章转换

**场景**：用户提供一个文章 URL，要求转换为 Markdown

```bash
npx --yes news-to-markdown@^3.3.0 \
  --url "https://www.toutiao.com/article/123" \
  --output article.md
```

---

### 操作 2：转换并下载图片（推荐）

**场景**：需要保留图片，或后续要发布到微信公众号

```bash
npx --yes news-to-markdown@^3.3.0 \
  --url "https://www.toutiao.com/article/123" \
  --download-images \
  --output-dir ./article
# 输出：./article/article.md + ./article/images/*.jpg
```

> 头条、微信等平台的图片 URL 包含签名，数小时后失效。下载到本地可避免此问题。

---

### 操作 3：只提取正文

**场景**：用户说"只要文章内容，不要标题作者等信息"

```bash
npx --yes news-to-markdown@^3.3.0 \
  --url "https://36kr.com/p/xxx" \
  --no-metadata
```

---

### 操作 4：批量处理多篇文章

**场景**：配合 bws 搜索结果批量提取

```bash
# 先搜索
bws site zhihu/search "大模型" --count 5 --jq '[.items[].url]'

# 再逐篇提取
for url in "urls[@]"; do
  npx --yes news-to-markdown@^3.3.0 --url "$url" --output "articles/$(echo $url | md5sum | cut -c1-8).md"
done
```

---

### 操作 5：自定义提取（去噪 / 指定区域）

**场景**：提取结果不准，用户要求去掉广告或指定正文区域

```bash
# 去掉广告和评论
npx --yes news-to-markdown@^3.3.0 \
  --url "https://example.com/article" \
  --noise ".ad,.sidebar,.comments"

# 指定内容区域
npx --yes news-to-markdown@^3.3.0 \
  --url "https://example.com/article" \
  --selector "article.main-content"
```

---

### 操作 6：调试失败页面

**场景**：抓取或提取失败，需要排查

```bash
npx --yes news-to-markdown@^3.3.0 \
  --url "https://example.com/article" \
  --verbose
```

**常见原因与解决方案**：

| 问题 | 原因 | 解决方案 |
|------|------|------|
| 抓取失败 | 需要 JS 渲染 | 自动使用 Playwright（需提前安装） |
| 内容为空 | 选择器不匹配 | 使用 `--selector` 指定内容区域 |
| 图片显示不了 | URL 过期 | 使用 `--download-images` |
| 反爬拦截 | 无头浏览器被检测 | 知乎已内置 Chrome UA，其他平台视情况处理 |

可选安装 Playwright 浏览器（动态页面支持）：

```bash
npx playwright install chromium
```

---

## 🎓 示例对话

**用户**：帮我把这篇虎嗅文章转成 Markdown，图片也要保存

```bash
npx --yes news-to-markdown@^3.3.0 \
  --url "https://www.huxiu.com/article/xxx.html" \
  --download-images \
  --output-dir ./huxiu-article
```

---

**用户**：搜索头条最新 3 篇关于 AI Agent 的文章，并获取每篇正文

```bash
# Step 1: 搜索
bws site toutiao/search "AI Agent" --count 3

# Step 2: 逐篇提取（对每个 url 执行）
npx --yes news-to-markdown@^3.3.0 --url "<url>" --output "<title>.md"
```

---

**用户**：只要这篇知乎文章的正文，不要其他信息

```bash
npx --yes news-to-markdown@^3.3.0 \
  --url "https://www.zhihu.com/p/xxx" \
  --no-metadata
```

---

## ⚠️ 安全与版权

**供应链风险**：本 Skill 通过 `npx` 动态拉取并执行第三方 npm 包，使用前请审计源码：
- 源码：https://github.com/sipingme/news-to-markdown
- 入口：https://github.com/sipingme/news-to-markdown/blob/main/src/index.ts

**版权提示**：本工具默认用于个人学习和内容归档。对外发布时，请保留来源链接和作者信息，并确认来源站点的版权声明与转载政策。

---

## 📝 维护说明

- **版本**: 3.3.0
- **最后更新**: 2026-04-24
- **维护者**: Ping Si <[email protected]>
- **许可证**: MIT

---

## 📚 参考资料

- [news-to-markdown GitHub](https://github.com/sipingme/news-to-markdown)
- [npm 包](https://www.npmjs.com/package/news-to-markdown)
- [browser-web-search Skill](https://github.com/sipingme/browser-web-search-skill)

FILE:config.json
{
  "name": "news-to-markdown",
  "version": "3.3.0",
  "requiredEnvVars": [],
  "skill": {
    "name": "news-to-markdown",
    "version": "3.3.0",
    "enabled": true,
    "autoInvoke": false
  },
  "commands": {
    "convert": {
      "script": "./scripts/run.js",
      "args": ["convert"],
      "description": "将新闻文章转换为 Markdown"
    }
  },
  "environment": {
    "required": [
      "NODE_VERSION>=18.0.0"
    ],
    "optional": []
  },
  "install": {
    "type": "npx",
    "package": "news-to-markdown",
    "version": "^3.3.0",
    "execution": "npx --yes news-to-markdown@^3.3.0",
    "global": false,
    "autoInstall": false,
    "autoUpdate": false,
    "riskLevel": "moderate",
    "riskReason": "通过 npx 动态拉取并执行第三方 npm 包，存在供应链风险。使用前请审计源码。",
    "requiresApproval": true,
    "source": {
      "type": "npm",
      "registry": "https://registry.npmjs.org",
      "package": "news-to-markdown",
      "repository": "https://github.com/sipingme/news-to-markdown",
      "license": "MIT",
      "audit": "https://github.com/sipingme/news-to-markdown/blob/main/src/index.ts"
    },
    "verification": {
      "command": "npx --yes news-to-markdown@^3.3.0 --version",
      "expectedOutput": "3.3"
    }
  },
  "dependencies": {
    "npm": [
      "news-to-markdown@^3.3.0"
    ],
    "note": "Package is executed via npx at runtime, no global installation required"
  },
  "permissions": {
    "filesystem": {
      "read": ["*.html", "*.htm", "*.md", "./images/", "./output/"],
      "write": ["*.md", "./images/"]
    },
    "network": {
      "domains": [
        "registry.npmjs.org",
        "*.toutiao.com",
        "*.toutiaoimg.com",
        "*.weixin.qq.com",
        "*.xiaohongshu.com",
        "*.xhscdn.com",
        "*.36kr.com",
        "*.zhihu.com"
      ],
      "note": "仅访问支持的新闻平台域名"
    }
  }
}

FILE:README.md
# news-to-markdown Skill

> 输入文章 URL，输出干净的 Markdown 正文 — 17 个平台专项优化，专为 AI Agent 设计

## 快速开始

```bash
# 基本转换
npx --yes news-to-markdown@^3.3.0 --url "https://www.toutiao.com/article/123"

# 保存到文件
npx --yes news-to-markdown@^3.3.0 --url "https://mp.weixin.qq.com/s/xxx" --output article.md

# 下载图片到本地（生成离线包）
npx --yes news-to-markdown@^3.3.0 --url "https://36kr.com/p/xxx" \
  --download-images --output-dir ./article

# 与 browser-web-search 配合：搜索 → 提取正文
bws site toutiao/search "ai agent" --count 3
npx --yes news-to-markdown@^3.3.0 --url "https://www.toutiao.com/article/111"
```

## 专项优化平台（17 个）

| 平台 | 域名 |
|-----|------|
| **今日头条** | toutiao.com |
| **微信公众号** | mp.weixin.qq.com |
| **小红书** | xiaohongshu.com |
| **知乎** | zhihu.com |
| **36kr** | 36kr.com |
| **虎嗅** | huxiu.com |
| **华尔街见闻** | wallstreetcn.com |
| **澎湃新闻** | thepaper.cn |
| **InfoQ** | infoq.cn / infoq.com |
| **Bilibili 专栏** | bilibili.com |
| **掘金** | juejin.cn |
| **CSDN** | csdn.net |
| **博客园** | cnblogs.com |
| **简书** | jianshu.com |
| **SegmentFault** | segmentfault.com |
| **开源中国** | oschina.net |
| **人人都是产品经理** | woshipm.com |

其余平台走通用算法（Mozilla Readability），大多数文章均可正常提取。

## 参数速查

| 参数 | 说明 |
|-----|------|
| `--url` | 文章 URL（必填） |
| `--output` | 输出文件路径 |
| `--download-images` | 下载图片到本地 |
| `--output-dir` | 图片输出目录 |
| `--no-metadata` | 只要正文，不含标题/作者/时间 |
| `--selector` | 自定义内容区域 CSS 选择器 |
| `--noise` | 移除指定元素（逗号分隔） |
| `--verbose` | 详细日志 |

## 环境要求

- Node.js >= 18.0.0
- 可选：`npx playwright install chromium`（动态页面支持）

## 文档

详细使用说明：[SKILL.md](./SKILL.md)

## 链接

- [news-to-markdown GitHub](https://github.com/sipingme/news-to-markdown)
- [npm 包](https://www.npmjs.com/package/news-to-markdown)

## License

MIT

FILE:scripts/run.js
#!/usr/bin/env node

const { spawnSync } = require('node:child_process');

// 所需版本（与 config.json 中 dependencies.npm 保持一致）
const REQUIRED_VERSION = '3.1.3';

const command = process.argv[2];
const args = process.argv.slice(3);

if (!command) {
  showHelp();
  process.exit(0);
}

const run = (cmd, cmdArgs) => {
  const result = spawnSync(cmd, cmdArgs, { stdio: 'inherit' });
  if (result.error) {
    console.error(JSON.stringify({ success: false, error: result.error.message }));
    process.exit(1);
  }
  process.exit(result.status ?? 1);
};

/**
 * 使用 npx 执行 news-to-markdown CLI
 */
const runNewsToMarkdown = (cliArgs) => {
  run('npx', ['--yes', `news-to-markdown@^REQUIRED_VERSION`, ...cliArgs]);
};

function showHelp() {
  console.log(`
news-to-markdown-skill v2.3.30
ClawHub skill for converting news to markdown

用法: 
  通过 scripts/convert.js convert [选项]
  或直接: npx --yes news-to-markdown@^REQUIRED_VERSION [选项]

命令:
  convert    将新闻文章转换为 Markdown
  help       显示帮助信息

选项:
  --url, -u <URL>        新闻文章的 URL（必需）
  --output, -o <文件>    输出 Markdown 文件路径（默认: stdout）
  --output-dir, -d <目录> 输出目录（用于图片下载）
  --download-images      下载图片到本地（默认开启）
  --no-download-images   不下载图片
  --platform, -p <平台>  指定平台 (toutiao, wechat, xiaohongshu, 36kr, ...)
  --selector, -s <选择器> CSS 选择器，指定内容区域
  --noise, -n <选择器>   要移除的元素（逗号分隔）
  --no-metadata          不包含元数据（标题、作者、时间）
  --verbose, -v          显示详细日志
  --help, -h             显示帮助信息

支持的平台:
  toutiao, wechat, xiaohongshu, 36kr, zhihu, juejin, jianshu,
  csdn, woshipm, oschina, bilibili, segmentfault, cnblogs

示例:
  npx --yes news-to-markdown@^REQUIRED_VERSION --url "https://www.toutiao.com/article/123" --output article.md
  npx --yes news-to-markdown@^REQUIRED_VERSION --url "https://36kr.com/p/123" --download-images --output-dir ./article
  npx --yes news-to-markdown@^REQUIRED_VERSION --url "https://mp.weixin.qq.com/s/xxx" --platform wechat
`);
}

switch (command) {
  case 'convert':
    runNewsToMarkdown(args);
    break;
  case 'help':
    showHelp();
    break;
  default:
    console.error(JSON.stringify({ success: false, error: `Unknown command: command` }));
    process.exit(1);
}

---
name: html-to-markdown
description: 将 HTML 内容转换为 Markdown 格式，支持字符串、文件和 URL 转换
version: 1.0.0
author: Ping Si <[email protected]>
type: npm-package
requires:
  - npm: "@siping/html-to-markdown-node@^1.0.1"
  - node: ">=18.0.0"
tags:
  - html
  - markdown
  - converter
  - utility
repository: https://github.com/sipingme/html-to-markdown-skill
npmPackage: https://www.npmjs.com/package/@siping/html-to-markdown-node
---

# HTML to Markdown Skill

将 HTML 内容转换为 Markdown 格式的 ClawHub Skill。

## 🏗️ 架构说明

本 Skill 是一个 npm 包集成配置，实际功能由 [@siping/html-to-markdown-node](https://www.npmjs.com/package/@siping/html-to-markdown-node) npm 包提供。

```
OpenClaw/AI Agent
    ↓ (读取 Skill 配置)
html-to-markdown-skill
    ↓ (调用 npm 包)
@siping/html-to-markdown-node
    ↓ (转换 HTML)
Markdown 输出
```

## 🎯 何时使用此 Skill

当用户需要将 HTML 内容转换为 Markdown 格式时，AI 会自动调用相应的命令：

### HTML 字符串转换
- 将 HTML 代码片段转换为 Markdown
- 处理富文本编辑器内容
- 转换邮件 HTML 内容

### HTML 文件转换
- 批量转换 HTML 文件
- 将网页保存为 Markdown
- 文档格式迁移

### URL 内容抓取
- 抓取网页并转换为 Markdown
- 提取特定区域内容（CSS 选择器）
- 保存网页文章为 Markdown

**触发关键词**：
- "转换 HTML 为 Markdown"、"HTML 转 Markdown"
- "抓取网页内容"、"保存网页为 Markdown"
- "转换 HTML 文件"、"批量转换 HTML"

## 📋 前置要求

### 1. 安装依赖

```bash
# 安装 npm 包
npm install -g @siping/html-to-markdown-node

# 或在项目中安装
npm install @siping/html-to-markdown-node
```

### 2. 安装 Skill 文档

```bash
# 克隆 Skill 配置和文档
git clone https://github.com/sipingme/html-to-markdown-skill.git
cp -r html-to-markdown-skill ~/.openclaw/skills/html-to-markdown/
```

## 🚀 标准操作流程 (SOP)

### 操作 1：转换 HTML 字符串

**场景**：用户提供 HTML 代码片段，需要转换为 Markdown

**命令**：`convert`

**步骤**：

1. 接收用户提供的 HTML 内容
2. 可选：询问是否需要指定 domain（用于解析相对 URL）
3. 调用转换命令

**示例**：

```bash
html2md convert \
  --html '<strong>Bold Text</strong>' \
  --domain 'https://example.com'
```

**输出示例**：
```json
{
  "success": true,
  "markdown": "**Bold Text**",
  "length": 13
}
```

**异常处理**：
- HTML 为空：提示用户提供内容
- 转换失败：显示错误信息

---

### 操作 2：转换 HTML 文件

**场景**：用户有 HTML 文件需要转换为 Markdown 文件

**命令**：`convert-file`

**步骤**：

1. 确认输入文件路径
2. 询问输出文件路径（可选，默认输出到控制台）
3. 可选：询问是否需要指定 domain
4. 执行转换

**示例**：

```bash
html2md convert-file \
  --input /path/to/input.html \
  --output /path/to/output.md \
  --domain 'https://example.com'
```

**输出示例**：
```json
{
  "success": true,
  "message": "转换成功: /path/to/output.md",
  "inputFile": "/path/to/input.html",
  "outputFile": "/path/to/output.md",
  "length": 1234
}
```

**异常处理**：
- 文件不存在：提示用户检查路径
- 无写入权限：提示权限问题
- 转换失败：显示错误信息

---

### 操作 3：抓取 URL 并转换

**场景**：用户想抓取网页内容并转换为 Markdown

**命令**：`convert-url`

**步骤**：

1. 确认目标 URL
2. 可选：询问是否需要使用 CSS 选择器提取特定内容
3. 执行抓取和转换

**示例**：

```bash
# 转换整个页面
html2md convert-url \
  --url 'https://example.com/article'

# 只提取特定区域
html2md convert-url \
  --url 'https://example.com/article' \
  --selector 'article.content'
```

**输出示例**：
```json
{
  "success": true,
  "markdown": "# Article Title\n\nContent...",
  "url": "https://example.com/article",
  "length": 5678
}
```

**异常处理**：
- URL 无法访问：提示网络错误
- 选择器未找到：提示选择器错误
- 转换失败：显示错误信息

---

## 📊 输入输出规范

### 命令行输出格式

所有命令统一使用 JSON 格式输出：

**成功响应**：
```json
{
  "success": true,
  "markdown": "转换后的 Markdown 内容",
  "length": 1234
}
```

**错误响应**：
```json
{
  "success": false,
  "error": "错误信息"
}
```

### 转换选项

#### domain（可选）
- **类型**：字符串
- **说明**：用于解析相对 URL 为绝对 URL
- **示例**：`https://example.com`

#### escapeMode（可选）
- **类型**：字符串
- **可选值**：`smart`（默认）、`disabled`
- **说明**：
  - `smart`：智能转义特殊字符
  - `disabled`：禁用转义

#### selector（仅 URL 转换）
- **类型**：字符串
- **说明**：CSS 选择器，用于提取页面特定区域
- **示例**：`article.content`、`#main`、`.post-body`

---

## 🎓 示例对话

### 示例 1：转换 HTML 字符串

**用户**：帮我把这段 HTML 转换为 Markdown：`<h1>Title</h1><p>Content</p>`

**AI**：好的，我来帮你转换。

[执行命令]
```bash
html2md convert --html '<h1>Title</h1><p>Content</p>'
```

**AI**：✅ 转换完成！

```markdown
# Title

Content
```

---

### 示例 2：抓取网页

**用户**：帮我把这个网页保存为 Markdown：https://example.com/blog/post

**AI**：好的，我来抓取并转换这个网页。

[执行命令]
```bash
html2md convert-url --url 'https://example.com/blog/post'
```

**AI**：✅ 网页已转换为 Markdown！

---

### 示例 3：批量转换文件

**用户**：把 docs 文件夹下的所有 HTML 文件转换为 Markdown

**AI**：好的，我来批量转换。

[执行命令]
```bash
for file in docs/*.html; do
  html2md convert-file \
    --input "$file" \
    --output "file%.html.md"
done
```

**AI**：✅ 已转换 5 个文件！

---

## ⚠️ 常见问题和解决方案

### 问题 1：相对 URL 未正确转换

**症状**：图片或链接显示为相对路径

**解决**：
```bash
html2md convert --html '...' --domain 'https://example.com'
```

### 问题 2：特殊字符被过度转义

**症状**：输出的 Markdown 中有很多反斜杠

**解决**：
```bash
html2md convert --html '...' --escape-mode disabled
```

### 问题 3：网页抓取失败

**症状**：提示"Failed to fetch URL"

**原因**：
- 网络连接问题
- URL 需要认证
- 防爬虫限制

**解决**：
- 检查网络连接
- 手动下载 HTML 后使用 `convert-file`

### 问题 4：选择器未找到内容

**症状**：提示"Selector not found"

**解决**：
- 在浏览器中检查选择器是否正确
- 使用更通用的选择器
- 不使用选择器，转换整个页面

---

## 🔧 支持的 HTML 元素

### 文本格式
- **粗体**：`<strong>`, `<b>` → `**text**`
- **斜体**：`<em>`, `<i>` → `*text*`
- **删除线**：`<del>`, `<s>` → `~~text~~`
- **代码**：`<code>` → `` `code` ``

### 标题
- `<h1>` → `# Heading 1`
- `<h2>` → `## Heading 2`
- `<h3>` → `### Heading 3`
- `<h4>` → `#### Heading 4`
- `<h5>` → `##### Heading 5`
- `<h6>` → `###### Heading 6`

### 列表
- **无序列表**：`<ul>`, `<li>` → `- item`
- **有序列表**：`<ol>`, `<li>` → `1. item`
- **嵌套列表**：支持多层嵌套

### 链接和图片
- **链接**：`<a href="url">text</a>` → `[text](url)`
- **图片**：`<img src="url" alt="text">` → `![text](url)`

### 引用和代码块
- **引用**：`<blockquote>` → `> quote`
- **代码块**：`<pre><code>` → ` ```code``` `

### 表格
- `<table>`, `<tr>`, `<td>`, `<th>` → Markdown 表格

### 其他
- **水平线**：`<hr>` → `---`
- **换行**：`<br>` → 换行

---

## 📚 参考资料

- [项目 GitHub](https://github.com/sipingme/html-to-markdown-skill)
- [npm 包](https://www.npmjs.com/package/@siping/html-to-markdown-node)
- [快速开始指南](./references/quick-start.md)
- [API 文档](./references/api.md)

---

## 📝 维护说明

- **版本**: 1.0.0
- **最后更新**: 2026-03-22
- **维护者**: Ping Si <[email protected]>
- **许可证**: MIT

---

## ✅ 首次成功检查清单

新用户应该能在 2 分钟内完成：

- [ ] 安装包：`npm install -g @siping/html-to-markdown-node`
- [ ] 检查安装：`html2md --version`
- [ ] 测试转换：`html2md convert --html '<strong>Test</strong>'`
- [ ] 看到输出：`**Test**`

如果以上步骤都能顺利完成，说明 Skill 已正确配置！

FILE:references/api.md
# API 文档

## 命令行接口

### convert

转换 HTML 字符串为 Markdown。

**语法**：
```bash
bash scripts/convert.sh convert --html <html> [--domain <domain>] [--escape-mode <mode>]
```

**参数**：
- `--html` (必需): HTML 内容
- `--domain` (可选): 基础域名，用于解析相对 URL
- `--escape-mode` (可选): 转义模式，`smart` 或 `disabled`，默认 `smart`

**示例**：
```bash
bash scripts/convert.sh convert --html '<strong>Bold</strong>'
```

**输出**：
```json
{
  "success": true,
  "markdown": "**Bold**",
  "length": 8
}
```

---

### convert-file

转换 HTML 文件为 Markdown 文件。

**语法**：
```bash
bash scripts/convert.sh convert-file --input <file> [--output <file>] [--domain <domain>]
```

**参数**：
- `--input` (必需): 输入 HTML 文件路径
- `--output` (可选): 输出 Markdown 文件路径
- `--domain` (可选): 基础域名

**示例**：
```bash
bash scripts/convert.sh convert-file \
  --input input.html \
  --output output.md
```

**输出**：
```json
{
  "success": true,
  "message": "Converted successfully: output.md",
  "inputFile": "input.html",
  "outputFile": "output.md",
  "length": 1234
}
```

---

### convert-url

抓取 URL 并转换为 Markdown。

**语法**：
```bash
bash scripts/convert.sh convert-url --url <url> [--selector <selector>]
```

**参数**：
- `--url` (必需): 要抓取的 URL
- `--selector` (可选): CSS 选择器，用于提取特定内容

**示例**：
```bash
bash scripts/convert.sh convert-url \
  --url 'https://example.com/article' \
  --selector 'article.content'
```

**输出**：
```json
{
  "success": true,
  "markdown": "# Article Title\n\nContent...",
  "url": "https://example.com/article",
  "length": 5678
}
```

---

## 错误处理

所有命令在失败时返回以下格式：

```json
{
  "success": false,
  "error": "错误描述"
}
```

常见错误：
- `HTML content is required`: 未提供 HTML 内容
- `Input file is required`: 未提供输入文件
- `File not found: <path>`: 文件不存在
- `URL is required`: 未提供 URL
- `Failed to fetch URL: <code>`: URL 抓取失败
- `Selector not found: <selector>`: CSS 选择器未找到

---

## Node.js API

如果你想在 Node.js 代码中使用：

```javascript
const { convertString } = require('@siping/html-to-markdown-node');

const html = '<h1>Title</h1><p>Content</p>';
const markdown = convertString(html, {
  domain: 'https://example.com',
  escapeMode: 'smart'
});

console.log(markdown);
// # Title
//
// Content
```

详细 API 文档请参考：
https://www.npmjs.com/package/@siping/html-to-markdown-node

FILE:references/quick-start.md
# 快速开始指南

## 安装

### 1. 安装 npm 包

```bash
npm install -g @siping/html-to-markdown-node
```

### 2. 克隆 Skill 配置

```bash
git clone https://github.com/sipingme/html-to-markdown-skill.git
cd html-to-markdown-skill
npm install
```

## 基本使用

### 转换 HTML 字符串

```bash
bash scripts/convert.sh convert --html '<h1>Hello</h1><p>World</p>'
```

输出：
```json
{
  "success": true,
  "markdown": "# Hello\n\nWorld",
  "length": 13
}
```

### 转换 HTML 文件

```bash
bash scripts/convert.sh convert-file \
  --input example.html \
  --output example.md
```

### 抓取网页

```bash
bash scripts/convert.sh convert-url \
  --url 'https://example.com'
```

## 高级选项

### 指定域名（解析相对 URL）

```bash
bash scripts/convert.sh convert \
  --html '<img src="/logo.png">' \
  --domain 'https://example.com'
```

输出：`![](https://example.com/logo.png)`

### 使用 CSS 选择器

```bash
bash scripts/convert.sh convert-url \
  --url 'https://example.com/article' \
  --selector 'article.content'
```

## 在 ClawHub 中使用

安装 Skill 后，AI 会自动识别以下场景：

- "把这段 HTML 转换为 Markdown"
- "抓取这个网页并保存为 Markdown"
- "转换 HTML 文件"

AI 会自动调用相应的命令完成转换。

---
name: toutiao-mcp
description: 通过 MCP 协议操作今日头条平台，支持内容发布、账号管理等功能
version: 1.0.0
author: Ping Si <[email protected]>
type: mcp-server
requires:
  - mcpServer: toutiao-mcp
  - node: ">=18.0.0"
  - browser: chromium
tags:
  - toutiao
  - mcp
  - content-publishing
  - automation
repository: https://github.com/sipingme/toutiao-mcp-skill
mcpServer: https://github.com/sipingme/toutiao-mcp
---

# 今日头条 MCP Skill

通过 Model Context Protocol 让 AI 能够操作今日头条平台。

## 🏗️ 架构说明

本 Skill 是一个 MCP Server 集成配置，实际功能由 [toutiao-mcp](https://github.com/sipingme/toutiao-mcp) MCP Server 提供。

```
OpenClaw/AI Agent
    ↓ (读取 Skill 配置)
toutiao-mcp-skill
    ↓ (启动 MCP Server)
toutiao-mcp
    ↓ (MCP Protocol - 6 Tools)
今日头条平台
```

## 🎯 何时使用此 Skill

当用户需要操作今日头条平台时，AI 会自动调用相应的 MCP 工具：

### 账号管理
- ✅ 登录今日头条账号
- ✅ 检查登录状态
- ✅ 登出账号

### 内容发布
- ✅ 发布图文文章（支持多图、标签）
- ✅ 发布微头条（短内容快速分享）
- ✅ 批量发布小红书数据到今日头条

### 典型使用场景

1. **内容创作者**：将创作的文章、教程发布到今日头条
2. **知识分享者**：分享学习笔记、技术心得
3. **多平台运营**：将小红书内容同步到今日头条
4. **自媒体工作者**：批量管理和发布内容

**触发关键词**：
- "发布到今日头条"、"今日头条发布"、"头条发文"
- "发布文章到头条"、"在头条发表文章"
- "发布微头条"、"发微头条"、"头条动态"
- "把小红书数据发到头条"、"同步到今日头条"
- "批量发布到头条"、"头条批量发文"

## 📋 前置要求

### 1. 安装 toutiao-mcp MCP Server

```bash
# 方式 1：从 npm 安装（推荐）
npm install -g toutiao-mcp

# 安装浏览器
npx playwright install chromium

# 方式 2：从源码构建
git clone https://github.com/sipingme/toutiao-mcp.git
cd toutiao-mcp
npm install
npx playwright install chromium
npm run build
```

### 2. 配置 OpenClaw

在 OpenClaw 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "toutiao": {
      "command": "node",
      "args": ["/path/to/toutiao-mcp/dist/index.js"],
      "env": {
        "PLAYWRIGHT_HEADLESS": "true",
        "COOKIES_FILE": "/path/to/data/cookies.json",
        "DATA_DIR": "/path/to/data"
      }
    }
  }
}
```

### 3. 安装 Skill 文档

```bash
# 克隆 Skill 配置和文档
git clone https://github.com/sipingme/toutiao-mcp-skill.git
cp -r toutiao-mcp-skill ~/.openclaw/skills/toutiao/
```

## 🚀 标准操作流程 (SOP)

### 操作 1：检查登录状态

**场景**：在执行任何操作前，先确认登录状态

**MCP 工具**：`check_login_status`

**步骤**：

1. AI 调用 `check_login_status` 工具
2. 解析返回结果
3. 如果未登录，引导用户登录

**输出示例**：
```json
{
  "isLoggedIn": true,
  "message": "已登录"
}
```

**异常处理**：
- 如果 `isLoggedIn: false`，执行操作 2（登录流程）
- 如果 Cookie 过期，提示用户重新登录

---

### 操作 2：登录今日头条

**场景**：首次使用或 Cookie 过期

**MCP 工具**：`login_with_credentials`

**步骤**：

1. AI 调用 `login_with_credentials` 工具
2. 系统会打开浏览器窗口
3. 用户在浏览器中完成登录（扫码或账号密码）
4. 登录成功后，Cookie 自动保存

**输入参数**：
```json
{
  "headless": false
}
```

**输出示例**：
```json
{
  "success": true,
  "message": "登录成功"
}
```

**异常处理**：
- 登录超时：重新调用工具
- 登录失败：检查网络连接或账号状态

---

### 操作 3：发布图文文章

**场景**：用户提供标题、正文和图片，发布到今日头条

**MCP 工具**：`publish_article`

**前置条件**：
- ✅ 用户已登录
- ✅ 标题符合规范（2-30字）
- ✅ 正文内容充实（建议300字以上）
- ✅ 图片格式正确（可选）

**步骤**：

1. **验证登录状态**
   ```
   调用 check_login_status
   如果未登录 → 执行操作 2（登录流程）
   ```

2. **收集发布信息**
   - 标题（必需，2-30字）
   - 正文内容（必需，建议300字以上）
   - 图片路径列表（可选，支持本地路径和 URL）
   - 标签（可选，建议3-5个）

3. **验证内容格式**
   - 检查标题长度
   - 验证图片路径（如果有）
   - 确认正文不为空

4. **调用发布工具**

```json
{
  "title": "Node.js 开发技巧分享",
  "content": "本文分享几个实用的 Node.js 开发技巧...\n\n## 1. 使用 async/await\n\n异步编程是 Node.js 的核心...\n\n## 2. 错误处理最佳实践\n\n正确的错误处理能提高应用稳定性...\n\n## 3. 性能优化技巧\n\n...",
  "images": ["/path/to/image1.jpg", "/path/to/image2.jpg"],
  "tags": ["Node.js", "编程", "技术分享"]
}
```

5. **等待发布完成**
   - 预计时间：30-60秒
   - 显示进度提示
   - 处理可能的错误

6. **向用户报告结果**

**输出示例**：
```json
{
  "success": true,
  "articleId": "7123456789",
  "url": "https://www.toutiao.com/article/7123456789/",
  "message": "文章发布成功"
}
```

**成功标准**：
- ✅ 返回 `success: true`
- ✅ 获得文章 ID
- ✅ 可以在今日头条查看文章

**异常处理**：

| 错误类型 | 症状 | 解决方案 |
|---------|------|----------|
| 未登录 | `isLoggedIn: false` | 执行操作 2（登录流程） |
| 标题超长 | "标题长度不符" | 缩短标题到30字以内 |
| 标题过短 | "标题太短" | 扩充标题到2字以上 |
| 图片路径错误 | "图片不存在" | 检查路径，使用绝对路径 |
| 图片格式错误 | "不支持的格式" | 转换为 JPG/PNG/GIF/WEBP |
| 网络超时 | "请求超时" | 重试或检查网络连接 |
| 内容违规 | "内容审核失败" | 修改内容后重新发布 |

**最佳实践**：
- 📝 标题简洁有力，突出核心价值
- 📝 正文结构清晰，使用标题分段
- 📝 添加相关标签，提高曝光率
- 📝 配图质量高，与内容相关
- 📝 发布前预览，确保格式正确

---

### 操作 4：发布微头条

**场景**：用户想发布短内容到微头条（类似微博）

**MCP 工具**：`publish_micro_post`

**适用场景**：
- 💬 日常想法、心得分享
- 💬 学习笔记、技术片段
- 💬 快速资讯、动态更新
- 💬 图片配文、截图分享

**前置条件**：
- ✅ 用户已登录
- ✅ 内容不为空
- ✅ 内容长度适中（建议2000字以内）

**步骤**：

1. **验证登录状态**
   ```
   调用 check_login_status
   ```

2. **收集发布信息**
   - 内容（必需，建议2000字以内）
   - 图片（可选，最多9张）
   - 话题标签（可选，使用 #话题 格式）

3. **调用发布工具**

```json
{
  "content": "今天学习了 TypeScript 的高级类型，收获满满！\n\n主要学习了：\n• 条件类型\n• 映射类型\n• 工具类型\n\n#TypeScript #学习笔记 #前端开发",
  "images": ["/path/to/screenshot1.jpg", "/path/to/screenshot2.jpg"]
}
```

4. **等待发布完成**（通常10-20秒）

5. **向用户报告结果**

**输出示例**：
```json
{
  "success": true,
  "postId": "7123456789",
  "url": "https://www.toutiao.com/w/7123456789/",
  "message": "微头条发布成功"
}
```

**微头条 vs 文章对比**：

| 特性 | 微头条 | 文章 |
|------|--------|------|
| 内容长度 | 短（建议2000字内） | 长（建议300字以上） |
| 发布速度 | 快（10-20秒） | 慢（30-60秒） |
| 适用场景 | 碎片化分享 | 深度内容 |
| 标题要求 | 无标题 | 必需标题 |
| 话题标签 | 支持 #话题 | 支持标签 |

**内容建议**：
- 💡 使用话题标签增加曝光（#话题）
- 💡 配图提高吸引力
- 💡 内容简洁明了，突出重点
- 💡 适当使用 emoji 增加趣味性
- 💡 互动性强的内容更容易传播

**异常处理**：
- 未登录：执行登录流程
- 内容为空：提示用户输入内容
- 图片过多：限制在9张以内
- 内容过长：建议发布为文章

---

### 操作 5：批量发布小红书数据

**场景**：用户有小红书格式的数据，想批量发布到今日头条

**MCP 工具**：`publish_xiaohongshu_data`

**步骤**：

1. 验证用户已登录
2. 准备小红书数据（JSON 数组格式）
3. 指定下载目录（用于保存图片）

4. 调用 `publish_xiaohongshu_data` 工具：

```json
{
  "data": [
    {
      "小红书标题": "TypeScript 开发技巧",
      "仿写小红书文案": "分享几个 TypeScript 实用技巧...",
      "配图": "https://example.com/image1.jpg"
    },
    {
      "小红书标题": "React 性能优化",
      "仿写小红书文案": "React 性能优化的几个要点...",
      "配图": "https://example.com/image2.jpg"
    }
  ],
  "downloadDir": "/path/to/downloads"
}
```

**输出示例**：
```json
{
  "success": true,
  "total": 2,
  "succeeded": 2,
  "failed": 0,
  "results": [
    {
      "title": "TypeScript 开发技巧",
      "success": true,
      "articleId": "7123456789"
    },
    {
      "title": "React 性能优化",
      "success": true,
      "articleId": "7123456790"
    }
  ],
  "message": "批量发布完成，成功 2 条"
}
```

**数据格式要求**：
- `小红书标题`：文章标题
- `仿写小红书文案`：文章正文
- `配图`：图片 URL（自动下载）

**异常处理**：
- 部分失败：继续处理其他数据，最后汇总结果
- 图片下载失败：跳过该图片或整条数据
- 网络问题：重试机制

---

### 操作 6：登出账号

**场景**：用户想退出登录

**MCP 工具**：`logout`

**步骤**：

```json
{}
```

**输出示例**：
```json
{
  "success": true,
  "message": "已登出"
}
```

---

## 📊 输入输出规范

### MCP 工具输出格式

所有工具统一使用 JSON 格式输出：

**成功响应**：
```json
{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": "7123456789",
    "url": "https://www.toutiao.com/..."
  }
}
```

**错误响应**：
```json
{
  "success": false,
  "error": "错误信息",
  "code": "ERROR_CODE"
}
```

### 内容规范

#### 文章标题
- **长度限制**：2-30个字
- **计算规则**：
  - 中文字符：1个字
  - 英文字母/数字：0.5个字
  - 标点符号：1个字
- **建议**：
  - ✅ 简洁有力，突出核心
  - ✅ 包含关键词，便于搜索
  - ❌ 避免标题党
  - ❌ 避免特殊符号过多

**标题示例**：
```
✅ 好标题：
- "Node.js 性能优化实战指南"
- "TypeScript 高级类型详解"
- "前端开发必备的10个工具"

❌ 差标题：
- "震惊！！！这个技巧让我..."（标题党）
- "a"（太短）
- "这是一篇关于 Node.js 性能优化的非常详细的实战指南文章"（太长）
```

#### 图片要求

| 项目 | 要求 | 说明 |
|------|------|------|
| **格式** | JPG, PNG, GIF, WEBP | 推荐 JPG（体积小） |
| **大小** | 单张 ≤ 10MB | 建议压缩到 2MB 以内 |
| **尺寸** | 建议 1920x1080 | 保持清晰度 |
| **数量** | 文章：不限；微头条：≤9张 | 建议3-5张 |
| **来源** | 本地路径或 URL | URL 会自动下载 |

**图片路径示例**：
```json
{
  "images": [
    "/Users/username/Pictures/image1.jpg",
    "https://example.com/image2.jpg",
    "./relative/path/image3.png"
  ]
}
```

#### 内容要求

| 内容类型 | 长度建议 | 质量要求 |
|---------|---------|----------|
| **文章正文** | ≥ 300字 | 结构清晰，内容充实 |
| **微头条** | ≤ 2000字 | 简洁明了，重点突出 |
| **标签** | 3-5个 | 相关性强，覆盖主题 |

**内容格式建议**：
```markdown
# 使用 Markdown 格式

## 二级标题

正文内容...

- 列表项 1
- 列表项 2

**加粗重点**

> 引用内容
```

#### 标签规范

- **数量**：建议 3-5 个
- **选择原则**：
  - ✅ 与内容高度相关
  - ✅ 热门标签优先
  - ✅ 覆盖不同维度
- **示例**：
  ```json
  {
    "tags": ["Node.js", "性能优化", "后端开发", "技术分享"]
  }
  ```

---

## ⚠️ 常见问题和解决方案

### 问题 1：未登录或 Cookie 过期

**症状**：提示"未登录"或操作失败

**解决**：
调用 `login_with_credentials` 工具重新登录

### 问题 2：标题长度不符合要求

**症状**：提示"标题长度不符合要求"

**解决**：
- 检查标题长度（2-30字）
- 修改标题使其符合要求

### 问题 3：图片上传失败

**症状**：提示"图片上传失败"

**原因**：
- 图片路径错误
- 图片格式不支持
- 图片大小超限
- 网络问题

**解决**：
- 检查图片路径是否正确
- 确认图片格式（JPG/PNG/GIF/WEBP）
- 压缩图片到合适大小
- 检查网络连接

### 问题 4：浏览器自动化失败

**症状**：提示"页面元素未找到"

**原因**：今日头条页面结构变化

**解决**：
- 更新 toutiao-mcp 到最新版本
- 报告问题到 GitHub Issues

### 问题 5：批量发布部分失败

**症状**：批量发布时部分数据失败

**解决**：
- 查看详细错误信息
- 检查失败数据的格式
- 单独重试失败的数据

---

## 🔒 安全性说明

### 敏感信息处理

- Cookie 存储在本地文件中（默认 `./data/cookies.json`）
- 不会上传任何数据到第三方服务器
- 所有通信仅限于今日头条官方网站

### 权限要求

- 读取本地文件（图片、文本）
- 网络访问（今日头条网站）
- 写入 Cookie 文件
- 浏览器控制（Playwright）

### 数据隐私

- ❌ 不会收集用户信息
- ❌ 不会上传到第三方服务器
- ✅ 所有操作仅在本地执行
- ✅ Cookie 仅存储在本地

---

## 🎓 示例对话

### 场景 1：发布文章

**用户**：帮我把这篇文章发布到今日头条

**AI**：好的，我来帮你发布。请提供以下信息：
1. 文章标题（2-30字）
2. 文章正文
3. 配图（可选）
4. 标签（可选）

**用户**：
标题：Node.js 性能优化实战
正文：[提供详细内容]
图片：/Users/me/article-cover.jpg
标签：Node.js、性能优化、后端开发

**AI**：收到！我将为你发布到今日头条。

[内部流程]
1. 检查登录状态 ✓
2. 验证标题长度 ✓
3. 处理图片 ✓
4. 调用 publish_article

```json
{
  "title": "Node.js 性能优化实战",
  "content": "...",
  "images": ["/Users/me/article-cover.jpg"],
  "tags": ["Node.js", "性能优化", "后端开发"]
}
```

**AI**：✅ 文章已成功发布到今日头条！

📊 发布详情：
- 标题：Node.js 性能优化实战
- 文章ID：7123456789
- 链接：https://www.toutiao.com/article/7123456789/
- 状态：✅ 发布成功
- 用时：45秒

你可以在今日头条 App 或网站查看文章。

---

### 场景 2：发布微头条

**用户**：发布一条微头条："今天学习了 TypeScript 的高级类型，终于搞懂了条件类型和映射类型的区别！#TypeScript #学习笔记"

**AI**：好的，我来帮你发布微头条。

[调用 publish_micro_post]

```json
{
  "content": "今天学习了 TypeScript 的高级类型，终于搞懂了条件类型和映射类型的区别！#TypeScript #学习笔记"
}
```

**AI**：✅ 微头条发布成功！

📊 发布详情：
- 动态ID：7123456790
- 链接：https://www.toutiao.com/w/7123456790/
- 话题：#TypeScript #学习笔记
- 用时：12秒

---

### 场景 3：批量发布小红书数据

**用户**：把这些小红书数据批量发布到今日头条

**AI**：好的，我来批量发布。请提供小红书数据文件或数据内容。

**用户**：[提供包含5条数据的 JSON 文件]

**AI**：收到 5 条数据，开始批量发布...

[内部流程]
1. 检查登录状态 ✓
2. 验证数据格式 ✓
3. 下载图片 ✓
4. 逐条发布...

进度：
- [1/5] TypeScript 开发技巧 ✅
- [2/5] React 性能优化 ✅
- [3/5] 前端工程化实践 ✅
- [4/5] Vue3 新特性解析 ✅
- [5/5] Webpack 配置指南 ✅

**AI**：✅ 批量发布完成！

📊 发布统计：
- 总数：5 条
- 成功：5 条 ✅
- 失败：0 条
- 总用时：3分45秒

📝 发布详情：
1. TypeScript 开发技巧 - ID: 7123456791
2. React 性能优化 - ID: 7123456792
3. 前端工程化实践 - ID: 7123456793
4. Vue3 新特性解析 - ID: 7123456794
5. Webpack 配置指南 - ID: 7123456795

所有文章已成功发布到今日头条！

---

### 场景 4：处理错误情况

**用户**：发布文章，标题：这是一篇非常非常非常详细的关于 Node.js 性能优化的完整实战指南

**AI**：抱歉，标题长度超出限制。

❌ 错误：标题长度为 35 字，超过最大限制 30 字

💡 建议修改为：
- "Node.js 性能优化完整实战指南"（14字）✅
- "Node.js 性能优化实战"（11字）✅

请提供修改后的标题。

**用户**：好的，用第一个

**AI**：收到！使用标题"Node.js 性能优化完整实战指南"继续发布...

[继续发布流程]

---

## 📚 参考资料

- [项目 GitHub](https://github.com/sipingme/toutiao-mcp-skill)
- [toutiao-mcp 核心库](https://github.com/sipingme/toutiao-mcp)
- [快速开始指南](./references/quick-start.md)
- [常见问题 FAQ](./references/faq.md)

---

## 📝 维护说明

- **版本**: 1.0.0
- **最后更新**: 2026-03-20
- **维护者**: Ping Si <[email protected]>
- **许可证**: Apache-2.0

---

## ✅ 首次成功检查清单

新用户应该能在 5 分钟内完成：

- [ ] 安装工具：`npm install -g toutiao-mcp`
- [ ] 安装浏览器：`npx playwright install chromium`
- [ ] 配置 OpenClaw MCP Server
- [ ] 登录账号：调用 `login_with_credentials`
- [ ] 检查登录：调用 `check_login_status`
- [ ] 测试发布：准备内容，调用 `publish_article` 或 `publish_micro_post`
- [ ] 在今日头条网站或 App 中看到发布的内容

如果以上步骤都能顺利完成，说明 Skill 已正确配置！

FILE:references/faq.md
# 常见问题 (FAQ)

## 安装相关

### Q: 如何安装 toutiao-mcp？

A: 使用 npm 全局安装：
```bash
npm install -g toutiao-mcp
npx playwright install chromium
```

### Q: 支持哪些 Node.js 版本？

A: Node.js >= 18.0.0

### Q: 需要安装哪些浏览器？

A: 只需要 Chromium：
```bash
npx playwright install chromium
```

## 登录相关

### Q: 如何登录今日头条？

A: 在 OpenClaw 中说"帮我登录今日头条"，AI 会调用 `login_with_credentials` 工具打开浏览器，你在浏览器中完成登录即可。

### Q: Cookie 保存在哪里？

A: 默认保存在 `COOKIES_FILE` 环境变量指定的位置，通常是 `~/.openclaw/data/toutiao-cookies.json`

### Q: Cookie 会过期吗？

A: 会的。如果提示未登录，重新调用登录工具即可。

### Q: 可以使用账号密码自动登录吗？

A: 目前需要手动在浏览器中完成登录，这样更安全。

## 发布相关

### Q: 文章标题有什么限制？

A: 标题长度为 2-30 个字。

### Q: 支持哪些图片格式？

A: JPG, PNG, GIF, WEBP

### Q: 图片大小有限制吗？

A: 建议单张图片不超过 10MB。

### Q: 可以发布视频吗？

A: 目前不支持视频发布，只支持图文文章和微头条。

### Q: 微头条和文章有什么区别？

A: 
- 文章：长内容，有标题和正文，适合深度内容
- 微头条：短内容，类似微博，适合快速分享

### Q: 如何批量发布小红书数据？

A: 使用 `publish_xiaohongshu_data` 工具，提供 JSON 格式的数据数组：
```json
[
  {
    "小红书标题": "标题",
    "仿写小红书文案": "正文",
    "配图": "https://example.com/image.jpg"
  }
]
```

## 错误处理

### Q: 提示"未登录"怎么办？

A: 调用 `login_with_credentials` 重新登录。

### Q: 发布失败怎么办？

A: 
1. 检查是否已登录
2. 检查内容格式是否符合要求
3. 查看详细错误信息
4. 如果问题持续，提交 GitHub Issue

### Q: 图片上传失败怎么办？

A: 
1. 检查图片路径是否正确
2. 确认图片格式是否支持
3. 检查图片大小是否超限
4. 检查网络连接

### Q: 浏览器自动化失败怎么办？

A: 
1. 更新 toutiao-mcp 到最新版本
2. 重新安装浏览器：`npx playwright install chromium`
3. 如果问题持续，报告到 GitHub Issues

## 配置相关

### Q: 如何配置无头模式？

A: 在 MCP 配置中设置环境变量：
```json
{
  "env": {
    "PLAYWRIGHT_HEADLESS": "true"
  }
}
```

### Q: 如何查看详细日志？

A: 设置日志级别：
```json
{
  "env": {
    "LOG_LEVEL": "debug"
  }
}
```

### Q: 数据保存在哪里？

A: 保存在 `DATA_DIR` 环境变量指定的目录，默认是 `~/.openclaw/data`

## 性能相关

### Q: 发布一篇文章需要多长时间？

A: 通常 30-60 秒，取决于网络速度和图片数量。

### Q: 可以并发发布吗？

A: 不建议并发，建议按顺序发布以避免被平台限制。

### Q: 批量发布会被限制吗？

A: 建议控制发布频率，避免短时间内大量发布。

## 其他问题

### Q: 支持哪些平台？

A: macOS, Linux, Windows（需要 WSL）

### Q: 是否开源？

A: 是的，Apache-2.0 许可证。

### Q: 如何贡献代码？

A: 欢迎提交 Pull Request 到 GitHub 仓库。

### Q: 如何报告 Bug？

A: 在 GitHub 提交 Issue，请包含：
- 错误信息
- 操作步骤
- 环境信息（Node.js 版本、操作系统等）

### Q: 数据安全吗？

A: 
- ✅ Cookie 仅存储在本地
- ✅ 不上传数据到第三方
- ✅ 所有通信仅限今日头条官方网站
- ✅ 开源代码，可审计

## 获取更多帮助

- GitHub: https://github.com/sipingme/toutiao-mcp-skill
- Email: [email protected]
- 文档: [SKILL.md](../SKILL.md)

FILE:references/quick-start.md
# 快速开始

本指南帮助你在 5 分钟内开始使用 toutiao-mcp-skill。

## 前置条件

- Node.js >= 18.0.0
- OpenClaw 已安装并配置

## 安装步骤

### 1. 安装 MCP Server

```bash
npm install -g toutiao-mcp
npx playwright install chromium
```

### 2. 配置 OpenClaw

编辑 OpenClaw 的 MCP 配置文件，添加：

```json
{
  "mcpServers": {
    "toutiao": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/toutiao-mcp/dist/index.js"],
      "env": {
        "PLAYWRIGHT_HEADLESS": "true",
        "COOKIES_FILE": "~/.openclaw/data/toutiao-cookies.json",
        "DATA_DIR": "~/.openclaw/data"
      }
    }
  }
}
```

### 3. 首次登录

在 OpenClaw 对话中：

```
你: 帮我登录今日头条

AI: [调用 login_with_credentials]
    浏览器窗口已打开，请完成登录
```

在打开的浏览器中完成登录（扫码或账号密码）。

### 4. 验证登录

```
你: 检查今日头条登录状态

AI: [调用 check_login_status]
    ✅ 已登录
```

### 5. 发布第一篇文章

```
你: 帮我发布一篇今日头条文章
    标题：我的第一篇文章
    内容：这是我使用 toutiao-mcp 发布的第一篇文章！

AI: [调用 publish_article]
    ✅ 文章发布成功！
    文章ID: 7123456789
```

## 下一步

- 查看 [SKILL.md](../SKILL.md) 了解所有功能
- 查看 [FAQ](./faq.md) 了解常见问题
- 查看 [troubleshooting.md](./troubleshooting.md) 解决问题

## 常用命令

```bash
# 检查登录
你: 检查今日头条登录状态

# 发布文章
你: 发布文章到今日头条，标题是"xxx"，内容是"xxx"

# 发布微头条
你: 发布微头条："今天学习了 TypeScript"

# 批量发布
你: 把这些小红书数据发布到今日头条
```

## 获取帮助

- GitHub Issues: https://github.com/sipingme/toutiao-mcp-skill/issues
- Email: [email protected]

FILE:references/troubleshooting.md
# 故障排查指南

本指南帮助你解决使用 toutiao-mcp-skill 时遇到的常见问题。

## 安装问题

### 问题：npm install 失败

**症状**：
```
npm ERR! code EACCES
npm ERR! syscall access
```

**解决方案**：
```bash
# 使用 sudo（不推荐）
sudo npm install -g toutiao-mcp

# 或者配置 npm 全局目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g toutiao-mcp
```

### 问题：Playwright 浏览器安装失败

**症状**：
```
Error: browserType.launch: Executable doesn't exist
```

**解决方案**：
```bash
# 重新安装浏览器
npx playwright install chromium

# 如果还是失败，尝试手动指定浏览器路径
export PLAYWRIGHT_BROWSERS_PATH=/path/to/browsers
npx playwright install chromium
```

## 登录问题

### 问题：登录超时

**症状**：浏览器打开后长时间无响应

**解决方案**：
1. 检查网络连接
2. 关闭浏览器重新登录
3. 尝试使用非无头模式：
```json
{
  "env": {
    "PLAYWRIGHT_HEADLESS": "false"
  }
}
```

### 问题：Cookie 保存失败

**症状**：登录成功但下次还是未登录

**解决方案**：
1. 检查 `COOKIES_FILE` 路径是否有写入权限
2. 确保目录存在：
```bash
mkdir -p ~/.openclaw/data
chmod 755 ~/.openclaw/data
```

### 问题：提示"未登录"

**症状**：明明已经登录，但还是提示未登录

**解决方案**：
1. Cookie 可能已过期，重新登录
2. 检查 Cookie 文件是否存在且有效
3. 删除 Cookie 文件重新登录：
```bash
rm ~/.openclaw/data/toutiao-cookies.json
```

## 发布问题

### 问题：标题验证失败

**症状**：
```
Error: 标题长度必须在 2-30 字之间
```

**解决方案**：
- 检查标题长度（2-30个字）
- 修改标题使其符合要求

### 问题：图片上传失败

**症状**：
```
Error: 图片上传失败
```

**可能原因及解决方案**：

1. **图片路径错误**
   ```bash
   # 检查文件是否存在
   ls -la /path/to/image.jpg
   
   # 使用绝对路径
   /Users/username/Pictures/image.jpg
   ```

2. **图片格式不支持**
   ```bash
   # 检查图片格式
   file /path/to/image.jpg
   
   # 转换格式
   convert image.png image.jpg
   ```

3. **图片太大**
   ```bash
   # 检查文件大小
   ls -lh /path/to/image.jpg
   
   # 压缩图片
   convert image.jpg -quality 85 -resize 1920x1920\> compressed.jpg
   ```

4. **网络问题**
   - 检查网络连接
   - 重试上传

### 问题：内容发布失败

**症状**：
```
Error: 发布失败
```

**解决方案**：
1. 确认已登录：调用 `check_login_status`
2. 检查内容格式是否符合要求
3. 查看详细错误日志
4. 重试发布

### 问题：批量发布部分失败

**症状**：批量发布时部分数据失败

**解决方案**：
1. 查看返回的详细错误信息
2. 检查失败数据的格式
3. 单独重试失败的数据
4. 检查是否触发平台限制

## 浏览器自动化问题

### 问题：页面元素未找到

**症状**：
```
Error: Timeout waiting for selector
```

**解决方案**：
1. 今日头条页面可能已更新，更新 toutiao-mcp：
```bash
npm update -g toutiao-mcp
```

2. 如果问题持续，报告到 GitHub Issues

### 问题：浏览器崩溃

**症状**：
```
Error: Browser closed unexpectedly
```

**解决方案**：
1. 重启系统
2. 重新安装浏览器：
```bash
npx playwright install chromium --force
```
3. 检查系统资源（内存、CPU）

## 性能问题

### 问题：发布速度很慢

**可能原因及解决方案**：

1. **网络慢**
   - 检查网络速度
   - 使用更快的网络

2. **图片太大**
   - 压缩图片
   - 减少图片数量

3. **系统资源不足**
   - 关闭其他程序
   - 增加系统内存

### 问题：内存占用高

**解决方案**：
1. 使用无头模式
2. 发布完成后关闭浏览器
3. 批量发布时分批处理

## 配置问题

### 问题：环境变量不生效

**症状**：配置的环境变量没有生效

**解决方案**：
1. 检查 MCP 配置文件格式是否正确
2. 重启 OpenClaw
3. 使用绝对路径而不是 `~`

### 问题：找不到 MCP Server

**症状**：
```
Error: Cannot find module
```

**解决方案**：
1. 检查 `command` 和 `args` 路径是否正确
2. 使用绝对路径：
```bash
which node  # 获取 node 路径
npm list -g toutiao-mcp  # 获取 toutiao-mcp 路径
```

## 日志和调试

### 启用详细日志

在 MCP 配置中添加：
```json
{
  "env": {
    "LOG_LEVEL": "debug"
  }
}
```

### 查看日志文件

日志通常输出到：
- OpenClaw 控制台
- 系统日志（取决于 OpenClaw 配置）

### 调试模式

使用非无头模式查看浏览器操作：
```json
{
  "env": {
    "PLAYWRIGHT_HEADLESS": "false"
  }
}
```

## 获取帮助

如果以上方法都无法解决问题：

1. **收集信息**：
   - 错误信息（完整的错误堆栈）
   - 操作步骤（如何复现问题）
   - 环境信息：
     ```bash
     node --version
     npm list -g toutiao-mcp
     uname -a  # macOS/Linux
     ```

2. **提交 Issue**：
   - GitHub: https://github.com/sipingme/toutiao-mcp-skill/issues
   - 包含上述收集的信息

3. **联系维护者**：
   - Email: [email protected]

## 常用诊断命令

```bash
# 检查 Node.js 版本
node --version

# 检查 toutiao-mcp 安装
npm list -g toutiao-mcp

# 检查 Playwright 浏览器
npx playwright install --dry-run chromium

# 测试网络连接
ping www.toutiao.com

# 检查文件权限
ls -la ~/.openclaw/data/

# 查看进程
ps aux | grep node
```

## 预防措施

1. **定期更新**：
```bash
npm update -g toutiao-mcp
```

2. **备份 Cookie**：
```bash
cp ~/.openclaw/data/toutiao-cookies.json ~/.openclaw/data/toutiao-cookies.json.bak
```

3. **监控日志**：定期查看日志，及早发现问题

4. **控制发布频率**：避免触发平台限制

---
name: xiaohongshu-mcp-node
description: 通过 MCP 协议操作小红书平台，支持内容发布、搜索、互动等完整功能
version: 1.0.0
author: Ping Si <[email protected]>
type: mcp-server
requires:
  - mcpServer: xiaohongshu-mcp-node
  - node: ">=20.0.0"
  - browser: chromium
tags:
  - xiaohongshu
  - mcp
  - social-media
  - automation
repository: https://github.com/sipingme/xiaohongshu-mcp-node-skill
mcpServer: https://github.com/sipingme/xiaohongshu-mcp-node
---

# 小红书 MCP Skill

通过 Model Context Protocol 让 AI 能够操作小红书平台。

## 🏗️ 架构说明

本 Skill 是一个 MCP Server 集成配置，实际功能由 [xiaohongshu-mcp-node](https://github.com/sipingme/xiaohongshu-mcp-node) MCP Server 提供。

```
OpenClaw/AI Agent
    ↓ (读取 Skill 配置)
xiaohongshu-mcp-node-skill
    ↓ (启动 MCP Server)
xiaohongshu-mcp-node
    ↓ (MCP Protocol - 13 Tools)
小红书平台
```

## 🎯 何时使用此 Skill

当用户需要操作小红书平台时，AI 会自动调用相应的 MCP 工具：

### 账号管理
- 登录小红书账号
- 检查登录状态

### 内容发布
- 发布图文笔记（标题、正文、图片、标签）
- 发布视频内容

### 内容搜索
- 搜索小红书内容
- 获取推荐列表
- 查看内容详情

### 互动功能
- 发表评论
- 点赞/取消点赞
- 收藏/取消收藏
- 获取评论列表

**触发关键词**：
- "发布到小红书"、"小红书发布"
- "搜索小红书"、"在小红书上搜索"
- "小红书评论"、"评论这条小红书"
- "点赞小红书"、"收藏小红书内容"

## 📋 前置要求

### 1. 安装 xiaohongshu-mcp-node MCP Server

```bash
# 克隆并构建 MCP Server
git clone https://github.com/sipingme/xiaohongshu-mcp-node.git
cd xiaohongshu-mcp-node

# 安装依赖
npm install

# 安装浏览器
npx playwright install chromium

# 构建项目
npm run build

# 首次登录（获取 Cookie）
npm run login
```

### 2. 配置 OpenClaw

在 OpenClaw 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "xiaohongshu": {
      "command": "node",
      "args": ["/path/to/xiaohongshu-mcp-node/dist/index.js"],
      "env": {
        "HEADLESS": "true",
        "COOKIES_PATH": "/path/to/cookies.json"
      }
    }
  }
}
```

### 3. 安装 Skill 文档

```bash
# 克隆 Skill 配置和文档
git clone https://github.com/sipingme/xiaohongshu-mcp-node-skill.git
cp -r xiaohongshu-mcp-node-skill ~/.openclaw/skills/xiaohongshu/
```

## 🚀 标准操作流程 (SOP)

### 操作 1：检查登录状态

**场景**：在执行任何操作前，先确认登录状态

**MCP 工具**：`xhs_check_login`

**步骤**：

1. AI 调用 `xhs_check_login` 工具
2. 解析返回结果
3. 如果未登录，引导用户登录

**输出示例**：
```json
{
  "isLoggedIn": true,
  "username": "用户名"
}
```

**异常处理**：
- 如果 `isLoggedIn: false`，执行操作 2（登录流程）
- 如果 Cookie 过期，提示用户重新登录

---

### 操作 2：登录小红书

**场景**：首次使用或 Cookie 过期

**MCP 工具**：`xhs_get_qrcode`

**步骤**：

1. AI 调用 `xhs_get_qrcode` 工具获取二维码
2. 向用户展示二维码（Base64 图片）
3. 提示用户使用小红书 App 扫码
4. 扫码成功后，Cookie 自动保存

**输出示例**：
```json
{
  "image": "data:image/png;base64,iVBORw0KG...",
  "timeout": "4m"
}
```

**异常处理**：
- 二维码过期：重新调用工具
- 扫码失败：检查网络连接

---

### 操作 3：发布图文内容

**场景**：用户提供标题、正文和图片，发布到小红书

**MCP 工具**：`xhs_publish_note`

**步骤**：

1. 验证用户已登录（调用 `xhs_check_login`）
2. 收集发布信息：
   - 标题（必需，最多20字）
   - 正文内容（必需）
   - 图片路径列表（必需，至少1张，最多9张）
   - 标签（可选，最多10个）
   - 是否原创（可选）
   - 可见范围（可选：public/private/friends）

3. 调用 `xhs_publish_note` 工具：

```json
{
  "title": "文章标题",
  "content": "文章正文内容...",
  "imagePaths": ["/path/to/image1.jpg", "/path/to/image2.jpg"],
  "tags": ["标签1", "标签2"],
  "isOriginal": true,
  "visibility": "public"
}
```

4. 等待发布完成（可能需要30-60秒）

5. 向用户报告结果

**输出示例**：
```json
{
  "success": true,
  "noteId": "abc123",
  "message": "发布成功"
}
```

**异常处理**：
- 标题超过20字：提示用户修改
- 图片不存在：提示用户检查路径
- 未登录：先执行登录流程
- 网络错误：重试或提示用户

---

### 操作 3：发布视频内容

**场景**：用户提供标题、正文和视频文件

**步骤**：

```bash
xhs-cli publish-video \
  --title-file /tmp/title.txt \
  --content-file /tmp/content.txt \
  --video /path/to/video.mp4 \
  --tags "视频" "教程"
```

**参数说明**：
- `--title` 或 `--title-file`：标题（必需）
- `--content` 或 `--content-file`：正文内容（必需）
- `--video`：视频文件路径（必需）
- `--tags`：标签列表（可选）
- `--visibility`：可见范围（可选）

**注意事项**：
- 视频上传时间较长（5-10分钟）
- 视频大小限制：通常不超过 1GB
- 支持格式：MP4, MOV 等

---

### 操作 4：搜索内容

**场景**：用户想搜索小红书上的内容

**步骤**：

```bash
xhs-cli search \
  --keyword "Node.js" \
  --sort-by "综合" \
  --note-type "图文"
```

**参数说明**：
- `--keyword`：搜索关键词（必需）
- `--sort-by`：排序方式（可选）
- `--note-type`：笔记类型（可选）
- `--publish-time`：发布时间（可选）

**输出示例**：
```json
{
  "success": true,
  "count": 20,
  "feeds": [
    {
      "id": "abc123",
      "xsecToken": "xyz789",
      "title": "Node.js 开发技巧",
      "user": {
        "userId": "user123",
        "nickname": "技术博主",
        "avatar": "https://..."
      },
      "cover": "https://...",
      "likeCount": "1.2k",
      "commentCount": "89"
    }
  ],
  "message": "找到 20 条结果"
}
```

---

### 操作 5：获取内容详情

**场景**：用户想查看某条内容的详细信息

**步骤**：

```bash
xhs-cli get-detail \
  --feed-id "abc123" \
  --xsec-token "xyz789" \
  --load-all-comments
```

**参数说明**：
- `--feed-id`：内容ID（必需，从搜索结果中获取）
- `--xsec-token`：安全令牌（必需，从搜索结果中获取）
- `--load-all-comments`：加载所有评论（可选）

**输出包含**：
- 完整标题和正文
- 所有图片URL
- 用户信息
- 点赞数、评论数
- 评论列表

---

### 操作 6：发表评论

**场景**：用户想对某条内容发表评论

**步骤**：

```bash
cat > /tmp/comment.txt << 'EOF'
很棒的分享！学到了很多。
EOF

xhs-cli comment \
  --feed-id "abc123" \
  --xsec-token "xyz789" \
  --content-file /tmp/comment.txt
```

**参数说明**：
- `--feed-id`：内容ID（必需）
- `--xsec-token`：安全令牌（必需）
- `--content` 或 `--content-file`：评论内容（必需）

---

### 操作 7：点赞内容

**场景**：用户想点赞某条内容

**步骤**：

```bash
# 点赞
xhs-cli like \
  --feed-id "abc123" \
  --xsec-token "xyz789"

# 取消点赞
xhs-cli like \
  --feed-id "abc123" \
  --xsec-token "xyz789" \
  --unlike
```

---

### 操作 8：收藏内容

**场景**：用户想收藏某条内容

**步骤**：

```bash
# 收藏
xhs-cli favorite \
  --feed-id "abc123" \
  --xsec-token "xyz789"

# 取消收藏
xhs-cli favorite \
  --feed-id "abc123" \
  --xsec-token "xyz789" \
  --unfavorite
```

---

### 操作 9：获取推荐列表

**场景**：用户想查看推荐内容

**步骤**：

```bash
xhs-cli list-feeds
```

**输出**：返回20条推荐内容，格式同搜索结果

---

## 📊 输入输出规范

### 命令行输出格式

所有命令统一使用 JSON 格式输出：

**成功响应**：
```json
{
  "success": true,
  "message": "操作成功",
  "data": { ... }
}
```

**错误响应**：
```json
{
  "success": false,
  "error": "错误信息"
}
```

### 标题长度限制

小红书标题最多 **20个字**，计算规则：
- 中文字符、全角字符：每个计 1 个字
- 英文字母、数字、半角字符：每个计 0.5 个字

如果超长，需要提示用户修改或自动截断。

### 图片要求

- **格式**：JPG, PNG, GIF, WEBP
- **数量**：图文发布至少 1 张，最多 9 张
- **大小**：单张不超过 10MB
- **来源**：支持本地路径和 URL（自动下载）

### 视频要求

- **格式**：MP4, MOV
- **大小**：不超过 1GB
- **时长**：建议 15秒 - 5分钟

---

## ⚠️ 常见问题和解决方案

### 问题 1：未登录或 Cookie 过期

**症状**：提示"未登录"或操作失败

**解决**：
```bash
xhs-cli login
```
扫码重新登录

### 问题 2：标题超过长度限制

**症状**：提示"标题验证失败"

**解决**：
- 检查标题长度（中文20字，英文40字符）
- 修改标题或使用更简洁的表达

### 问题 3：图片上传失败

**症状**：提示"图片上传失败"

**原因**：
- 图片路径错误
- 图片格式不支持
- 图片大小超限
- 网络问题

**解决**：
- 检查图片路径是否正确
- 确认图片格式（JPG/PNG/GIF）
- 压缩图片到 10MB 以下
- 检查网络连接

### 问题 4：浏览器自动化失败

**症状**：提示"页面元素未找到"

**原因**：小红书页面结构变化

**解决**：
- 更新 xiaohongshu-mcp-node 到最新版本
- 报告问题到 GitHub Issues

### 问题 5：找不到命令

**症状**：`xhs-cli: command not found`

**解决**：
```bash
# 确认安装
npm list -g xiaohongshu-mcp-node-skill

# 重新安装
npm install -g xiaohongshu-mcp-node-skill

# 检查 PATH
which xhs-cli
```

---

## 🔒 安全性说明

### 敏感信息处理

- Cookie 存储在本地文件中（默认 `./cookies.json`）
- 不会上传任何数据到第三方服务器
- 所有通信仅限于小红书官方网站

### 权限要求

- 读取本地文件（图片、视频、文本）
- 网络访问（小红书网站）
- 写入 Cookie 文件
- 浏览器控制（Playwright）

### 数据隐私

- ❌ 不会收集用户信息
- ❌ 不会上传到第三方服务器
- ✅ 所有操作仅在本地执行
- ✅ Cookie 仅存储在本地

---

## 🎓 示例对话

**用户**：帮我把这篇文章发布到小红书

**AI**：好的，我来帮你发布。请提供以下信息：
1. 文章标题（最多20字）
2. 文章正文
3. 配图（至少1张）
4. 标签（可选）

**用户**：[提供内容和图片]

**AI**：收到！我将为你发布到小红书。

[执行命令]

```bash
xhs-cli publish \
  --title "Node.js 开发技巧分享" \
  --content "..." \
  --images /tmp/img1.jpg /tmp/img2.jpg \
  --tags "Node.js" "编程" "技术分享" \
  --original
```

**AI**：✅ 文章已成功发布到小红书！
- 标题：Node.js 开发技巧分享
- 图片：2 张
- 状态：发布完成

---

## 📚 参考资料

- [项目 GitHub](https://github.com/sipingme/xiaohongshu-mcp-node-skill)
- [xiaohongshu-mcp-node 核心库](https://github.com/sipingme/xiaohongshu-mcp-node)
- [快速开始指南](./references/quick-start.md)
- [常见问题 FAQ](./references/faq.md)

---

## 📝 维护说明

- **版本**: 1.0.0
- **最后更新**: 2026-03-20
- **维护者**: Ping Si <[email protected]>
- **许可证**: Apache-2.0

---

## ✅ 首次成功检查清单

新用户应该能在 5 分钟内完成：

- [ ] 安装工具：`npm install -g xiaohongshu-mcp-node xiaohongshu-mcp-node-skill`
- [ ] 检查安装：`xhs-cli --version`
- [ ] 登录账号：`xhs-cli login`（扫码）
- [ ] 检查登录：`xhs-cli check-login`
- [ ] 测试发布：准备图片和内容，执行发布命令
- [ ] 在小红书 App 中看到发布的内容

如果以上步骤都能顺利完成，说明 Skill 已正确配置！

FILE:references/faq.md
# ❓ 常见问题解答 (FAQ)

## 安装相关

### Q1: 如何检查是否安装成功？

```bash
xhs-cli --version
xhs-cli check-login
```

如果能正常输出版本号和登录状态，说明安装成功。

### Q2: 提示 "command not found: xhs-cli"

**原因**：
1. npm 全局安装路径未加入 PATH
2. 或者使用的是本地安装（未全局安装）

**解决**：

```bash
# 方案 1：全局安装
npm install -g xiaohongshu-mcp-node-skill

# 方案 2：使用本地安装
cd xiaohongshu-mcp-node-skill
node scripts/xhs-cli.js --help

# 方案 3：添加 npm 路径到 PATH（macOS/Linux）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

### Q3: Node.js 版本不符合要求

**要求**：Node.js >= 20.0.0

**解决**：

```bash
# 使用 nvm 安装最新版本
nvm install 20
nvm use 20

# 或从官网下载：https://nodejs.org/
```

## 登录相关

### Q4: 二维码无法显示

**原因**：终端不支持图片显示

**解决**：

1. 输出中包含 Base64 编码的二维码
2. 将 `qrcode` 字段的内容保存为图片
3. 或使用支持图片的终端（如 iTerm2）

### Q5: 扫码后提示登录失败

**可能原因**：
- 二维码已过期（4分钟有效期）
- 网络连接问题
- 小红书服务器问题

**解决**：
```bash
# 重新获取二维码
xhs-cli login
```

### Q6: Cookie 文件在哪里？

**默认位置**：`./cookies.json`

**自定义位置**：
```bash
export COOKIES_PATH="/path/to/cookies.json"
```

## 发布相关

### Q7: 标题超过长度限制

**限制**：20个字（中文字符计1个，英文字符计0.5个）

**解决**：
- 缩短标题
- 使用更简洁的表达

### Q8: 图片上传失败

**检查清单**：
- ✅ 图片路径是否正确
- ✅ 图片格式是否支持（JPG/PNG/GIF）
- ✅ 图片大小是否超限（单张 < 10MB）
- ✅ 网络连接是否正常

**解决**：
```bash
# 检查图片
file /path/to/image.jpg
ls -lh /path/to/image.jpg

# 压缩图片（如果过大）
# macOS
sips -Z 1920 /path/to/image.jpg

# Linux
convert /path/to/image.jpg -resize 1920x1920 /path/to/image-compressed.jpg
```

### Q9: 视频上传很慢

**正常现象**：视频上传通常需要 5-10 分钟

**建议**：
- 使用较小的视频文件（< 500MB）
- 确保网络连接稳定
- 耐心等待上传完成

### Q10: 发布后在小红书看不到

**可能原因**：
- 内容正在审核中
- 内容违反社区规范被拒绝
- 设置为"仅自己可见"

**检查**：
1. 在小红书 App 中查看"我的"页面
2. 检查是否有审核通知
3. 确认可见范围设置

## 搜索和互动

### Q11: 搜索结果为空

**可能原因**：
- 关键词太具体
- 小红书上确实没有相关内容

**建议**：
- 使用更通用的关键词
- 尝试不同的搜索词

### Q12: 评论/点赞失败

**可能原因**：
- 未登录或 Cookie 过期
- feed-id 或 xsec-token 错误
- 网络问题

**解决**：
```bash
# 1. 检查登录状态
xhs-cli check-login

# 2. 如果未登录，重新登录
xhs-cli login

# 3. 确认 feed-id 和 xsec-token 正确
# 这两个参数从搜索结果中获取
```

## 性能和稳定性

### Q13: 命令执行很慢

**正常现象**：浏览器自动化需要时间

**预期时间**：
- 登录检查：5-10秒
- 搜索：10-15秒
- 发布图文：30-60秒
- 发布视频：5-10分钟

### Q14: 浏览器自动化失败

**可能原因**：
- 小红书页面结构变化
- Playwright 版本过旧
- 系统资源不足

**解决**：
```bash
# 更新到最新版本
npm update -g xiaohongshu-mcp-node xiaohongshu-mcp-node-skill

# 重新安装浏览器
npx playwright install chromium
```

### Q15: 内存占用过高

**原因**：Chromium 浏览器占用内存

**解决**：
- 使用无头模式（默认已启用）
- 操作完成后浏览器会自动关闭
- 如果持续占用，重启系统

## OpenClaw 集成

### Q16: OpenClaw 无法识别 Skill

**解决**：
```bash
# 刷新 Skill 列表
openclaw skills refresh

# 检查 Skill 状态
openclaw skills info xiaohongshu-mcp-node

# 查看日志
openclaw logs
```

### Q17: AI 不会自动调用 Skill

**可能原因**：
- Skill 未启用
- 触发关键词不匹配
- OpenClaw 配置问题

**解决**：
1. 确认 Skill 已启用：`openclaw skills list --enabled`
2. 使用明确的触发词："发布到小红书"、"搜索小红书"
3. 检查 OpenClaw 配置文件

## 安全和隐私

### Q18: Cookie 文件安全吗？

**安全措施**：
- Cookie 仅存储在本地
- 不会上传到任何服务器
- 建议设置文件权限：`chmod 600 cookies.json`

### Q19: 会不会被小红书封号？

**风险**：
- 正常使用不会被封号
- 过于频繁的操作可能触发风控

**建议**：
- 合理控制操作频率
- 不要批量发布相似内容
- 遵守小红书社区规范

### Q20: 数据会被收集吗？

**承诺**：
- ❌ 不会收集任何用户数据
- ❌ 不会上传到第三方服务器
- ✅ 所有操作仅在本地执行
- ✅ 开源代码，可审计

## 获取帮助

### 还有其他问题？

1. 📖 查看 [SKILL.md](../SKILL.md) 完整文档
2. 🐛 [提交 Issue](https://github.com/sipingme/xiaohongshu-mcp-node-skill/issues)
3. 💬 [参与讨论](https://github.com/sipingme/xiaohongshu-mcp-node-skill/discussions)
4. 📧 联系作者：[email protected]

---

**问题解决了吗？如果没有，欢迎提交 Issue！** 🤝

FILE:references/quick-start.md
# 🚀 快速开始指南

5 分钟快速上手 xiaohongshu-mcp-node-skill

## 第一步：安装

### 自动安装（推荐）

```bash
curl -fsSL https://raw.githubusercontent.com/sipingme/xiaohongshu-mcp-node-skill/main/install.sh | bash
```

### 手动安装

```bash
# 1. 克隆项目
git clone https://github.com/sipingme/xiaohongshu-mcp-node-skill.git
cd xiaohongshu-mcp-node-skill

# 2. 安装依赖（会自动安装 xiaohongshu-mcp-node）
npm install

# 3. 安装浏览器
npx playwright install chromium
```

## 第二步：登录

```bash
xhs-cli login
```

会生成一个二维码，使用**小红书 App** 扫码登录。

## 第三步：测试

### 检查登录状态

```bash
xhs-cli check-login
```

预期输出：
```json
{
  "success": true,
  "isLoggedIn": true,
  "message": "已登录"
}
```

### 搜索内容

```bash
xhs-cli search --keyword "Node.js"
```

### 发布测试内容

```bash
# 准备内容
echo "测试标题" > /tmp/title.txt
echo "这是测试内容" > /tmp/content.txt

# 发布（需要提供图片）
xhs-cli publish \
  --title-file /tmp/title.txt \
  --content-file /tmp/content.txt \
  --images /path/to/test-image.jpg
```

## 第四步：在 OpenClaw 中使用

### 配置 OpenClaw

确保 Skill 已安装到 OpenClaw：

```bash
openclaw skills list --eligible
```

应该能看到 `xiaohongshu-mcp-node` 在列表中。

### 对话示例

```
你: 帮我搜索小红书上关于 TypeScript 的内容

AI: 正在搜索...
[调用 xhs-cli search --keyword "TypeScript"]
找到 20 条相关内容...
```

## 常用命令速查

| 操作 | 命令 |
|------|------|
| 登录 | `xhs-cli login` |
| 检查登录 | `xhs-cli check-login` |
| 发布图文 | `xhs-cli publish --title "标题" --content "内容" --images img.jpg` |
| 搜索 | `xhs-cli search --keyword "关键词"` |
| 点赞 | `xhs-cli like --feed-id xxx --xsec-token yyy` |
| 评论 | `xhs-cli comment --feed-id xxx --xsec-token yyy --content "评论"` |

## 下一步

- 📖 阅读 [SKILL.md](../SKILL.md) 了解完整功能
- ❓ 查看 [FAQ](./faq.md) 解决常见问题
- 🐛 遇到问题？[提交 Issue](https://github.com/sipingme/xiaohongshu-mcp-node-skill/issues)

---

**5 分钟上手完成！开始使用吧！** 🎉

---
name: wechat-md-publisher
description: 发布 Markdown 文章到微信公众号，支持草稿管理、多主题、智能图片处理、自动封面图。推荐与 news-to-markdown-skill 配合使用实现一键转载（支持本地图片）。
version: 1.0.6
author: Ping Si <[email protected]>
user-invocable: true
requires:
  runtime:
    - name: node
      version: ">=18.0.0"
    - name: npm
      version: ">=8.0.0"
install:
  type: npx
  package: wechat-md-publisher
  version: "^1.0.6"
  execution: "npx --yes wechat-md-publisher@^1.0.6"
  riskLevel: moderate
  riskReason: "通过 npx 动态拉取并执行第三方 npm 包，存在供应链风险。使用前请审计源码。"
  source:
    registry: https://registry.npmjs.org
    repository: https://github.com/sipingme/wechat-md-publisher
    license: Apache-2.0
    audit: https://github.com/sipingme/wechat-md-publisher/blob/main/src/index.ts
env:
  optional:
    - name: WECHAT_APP_ID
      description: 微信公众号 AppID
      sensitive: false
    - name: WECHAT_APP_SECRET
      description: 微信公众号 AppSecret
      sensitive: true
  note: |
    凭证可通过两种方式提供（二选一）：
    1. 环境变量（推荐，避免凭证暴露在进程列表中）
    2. CLI 命令：`account add --app-id xxx --app-secret xxx`
configPaths:
  - path: ~/.config/wechat-md-publisher-nodejs/
    description: 账号配置和缓存目录
    contains:
      - credentials: true
      - encryption: AES-256
permissions:
  filesystem:
    read:
      - "*.md": "读取用户指定的 Markdown 文件"
      - "*.jpg,*.png,*.gif": "读取文章中引用的本地图片"
    write:
      - "~/.config/wechat-md-publisher-nodejs/": "存储账号配置和缓存（凭证使用 AES-256 加密）"
  network:
    required:
      - "api.weixin.qq.com": "微信公众号 API（发布、草稿、素材管理）"
      - "mp.weixin.qq.com": "微信公众号素材上传"
    optional:
      - "remote-theme-api": "仅当用户使用 theme add-remote 命令时才会访问（⚠️ 需用户明确配置并信任该端点）"
credentials:
  - name: WECHAT_APP_SECRET
    type: api-secret
    storage:
      location: ~/.config/wechat-md-publisher-nodejs/
      encryption: AES-256
      handler: wechat-md-publisher npm 包
      handlerRepo: https://github.com/sipingme/wechat-md-publisher
    consent: 需要用户明确提供，不会自动收集
    securityNote: |
      本 skill 不直接处理凭证加密，安全性依赖上游 npm 包的实现。
      建议在提供凭证前审查 wechat-md-publisher 包的加密实现：
      https://github.com/sipingme/wechat-md-publisher/blob/main/src/services/account.ts
tags:
  - wechat
  - publishing
  - markdown
  - content-management
repository: https://github.com/sipingme/wechat-md-publisher
---

# WeChat Publisher Skill

全功能微信公众号 Markdown 发布工具 - 让 AI 能够直接将内容发布到微信公众号。

## ⚠️ 重要提示

**推荐使用方式**：
- ✅ **最佳实践**：与 `news-to-markdown-skill` 配合使用，实现一键转载新闻到微信公众号
- 🌐 **固定公网 IP**：必须有固定公网 IP 并配置到微信公众平台的 IP 白名单
- 🔑 **必需凭证**：必须配置 `WECHAT_APP_ID` 和 `WECHAT_APP_SECRET` 环境变量或通过命令行配置

**关键要求**：
1. **固定公网 IP**：微信 API 要求服务器 IP 在白名单中，动态 IP 无法使用
2. **微信公众号凭证**：需要从微信公众平台获取 AppID 和 AppSecret
3. **IP 白名单配置**：在微信公众平台「设置与开发」→「基本配置」→「IP 白名单」中添加你的公网 IP

## ⚡ 快速开始

### ⚠️ 安全风险提示

**供应链风险**：本 Skill 通过 `npx` 动态拉取并执行第三方 npm 包 `wechat-md-publisher`。使用前请审计源码：
- **源码仓库**: https://github.com/sipingme/wechat-md-publisher
- **审计入口**: https://github.com/sipingme/wechat-md-publisher/blob/main/src/index.ts

**凭证存储**：账号凭证存储在 `~/.config/wechat-md-publisher-nodejs/`，使用 AES-256 加密。

**远程主题风险**：如果使用 `theme add-remote` 添加远程主题，第三方端点可能接收文章内容。请只使用可信任的主题源。

### 配置账号

**推荐方式（使用环境变量，避免命令行暴露凭证）**：

```bash
# 设置环境变量（不会出现在进程列表中）
export WECHAT_APP_ID="wx_your_app_id"
export WECHAT_APP_SECRET="your_app_secret"

# 添加账号
npx --yes wechat-md-publisher@^1.0.6 account add \
  --name "我的公众号" \
  --default
```

**备选方式（命令行传参，注意：可能暴露在进程列表中）**：

```bash
# ⚠️ 警告：--app-secret 会出现在 ps 进程列表中
npx --yes wechat-md-publisher@^1.0.6 account add \
  --name "我的公众号" \
  --app-id "wx_your_app_id" \
  --app-secret "your_app_secret" \
  --default
```

### 发布文章

```bash
npx --yes wechat-md-publisher@^1.0.6 publish create \
  --file article.md \
  --theme orangesun
```

### 与 news-to-markdown 配合使用

```bash
# 一键转载新闻到微信公众号（推荐：下载图片到本地）
# news-to-markdown 会自动下载图片到本地，避免远程 URL 过期问题
convert-url --url "https://www.toutiao.com/article/123" \
  --output /tmp/article.md \
  --download-images \
  --output-dir /tmp/article

# wechat-md-publisher 会自动读取本地图片并上传
npx --yes wechat-md-publisher@^1.0.6 publish create --file /tmp/article/article.md --theme orangesun
```

**图片处理最佳实践**（v0.8.3+）：
- ✅ **推荐**：使用 `--download-images` 下载图片到本地
  - 避免远程 URL 签名过期（如头条图片）
  - 避免防盗链问题
  - 提高发布成功率
- news-to-markdown 自动提取封面图（og:image > twitter:image > 第一张图片）
- 图片保存到 `./images/` 目录，Markdown 使用相对路径
- wechat-md-publisher 自动上传本地图片到微信素材库
- 完全自动化，无需手动处理

---

## 🎯 何时使用此 Skill

当用户需要以下操作时，应触发此 Skill：

- ✅ 发布文章到微信公众号
- ✅ 创建微信公众号草稿
- ✅ 管理微信公众号账号
- ✅ 查看已发布的文章列表
- ✅ 删除草稿或已发布文章
- ✅ 使用不同主题渲染 Markdown
- ✅ 在文章开头/结尾添加固定图文（Wrapper 功能）
- ✅ 查看或回滚 Wrapper 历史版本

**触发关键词**：
- "发布到微信公众号"
- "创建微信草稿"
- "配置微信公众号"
- "查看微信文章"
- "使用 [主题名] 主题发布"
- "文章开头结尾固定内容"
- "Wrapper"

## 📋 前置要求

### 1. 系统要求
- Node.js >= 18.0.0
- npm 或 pnpm 包管理器
- 网络连接（访问微信 API）

### 2. 微信公众号配置
用户必须拥有微信公众号并获取：
- **AppID**：开发者 ID
- **AppSecret**：开发者密码
- **IP 白名单**：必须配置（重要！）

获取方式：
1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
2. 进入「设置与开发」→「基本配置」
3. 获取「开发者ID(AppID)」和「开发者密码(AppSecret)」
4. **配置 IP 白名单**（必须！）：
   - 获取当前 IP：`curl ifconfig.me`
   - 在「IP白名单」中添加该 IP
   - 详细指南：[IP 白名单配置指南](./references/ip-whitelist-guide.md)

### 3. 使用方式

本 Skill 通过 `npx` 动态执行，无需全局安装：

```bash
# 查看帮助
npx --yes wechat-md-publisher@^1.0.6 --help
```

## 🚀 标准操作流程 (SOP)

### 操作 1：配置微信公众号账号

**场景**：首次使用或添加新账号

**步骤**：

1. 收集用户提供的账号信息（AppID 和 AppSecret）
2. 执行命令添加账号：

```bash
npx --yes wechat-md-publisher@^1.0.6 account add \
  --name "账号名称" \
  --app-id "wx_your_app_id" \
  --app-secret "your_app_secret" \
  --default
```

3. 验证账号添加成功：

```bash
npx --yes wechat-md-publisher@^1.0.6 account list
```

**输出示例**：
```
┌────────────┬──────────────┬────────────────┬─────────┐
│ ID         │ 名称         │ AppID          │ 默认    │
├────────────┼──────────────┼────────────────┼─────────┤
│ acc_xxx    │ 我的公众号   │ wx123456       │ ✓       │
└────────────┴──────────────┴────────────────┴─────────┘
```

**异常处理**：
- 如果 AppID/AppSecret 错误，会提示"认证失败"
- 如果网络问题，会提示"无法连接到微信服务器"
- 解决方案：检查凭证是否正确，确认 IP 在白名单中

---

### 操作 2：创建并发布文章（一步到位）

**场景**：用户提供 Markdown 内容，直接发布到公众号

**步骤**：

1. 将用户的 Markdown 内容保存到临时文件：

```bash
cat > /tmp/article.md << 'EOF'
---
title: 文章标题
author: 作者名
---

# 文章内容

这里是正文...
EOF
```

2. 执行发布命令：

```bash
npx --yes wechat-md-publisher@^1.0.6 publish create \
  --file /tmp/article.md \
  --theme orangesun
```

3. 解析输出，提取 `publish_id`

**输出示例**：
```
✓ 渲染完成
✓ 图片处理完成
✓ 创建草稿成功
✓ 发布成功

发布 ID: 2247483647_1
```

4. 向用户报告成功，并提供发布 ID

**可用主题**：
- `default` - 默认主题（简洁清爽）
- `orangesun` - Orange Sun（温暖明亮）
- `redruby` - Red Ruby（优雅醒目）
- `greenmint` - Green Mint（清新舒适）
- `purplerain` - Purple Rain（梦幻柔和）
- `blackink` - Black Ink（深色模式）

**异常处理**：
- 图片上传失败：检查图片路径和网络
- Token 过期：自动刷新，无需手动处理
- 内容违规：微信会返回错误码，提示用户修改内容

---

### 操作 3：创建草稿（不立即发布）

**场景**：用户想先创建草稿，稍后再发布

**步骤**：

1. 保存 Markdown 内容到文件
2. 执行草稿创建命令：

```bash
npx --yes wechat-md-publisher@^1.0.6 draft create \
  --file /tmp/article.md \
  --theme default
```

3. 记录返回的 `media_id`

**输出示例**：
```
✓ 草稿创建成功

Media ID: 3_abcdefghijk123456
```

4. 告知用户草稿已创建，可以在微信公众平台查看

**后续操作**：
- 用户可以在微信公众平台编辑草稿
- 需要发布时，使用 `npx --yes wechat-md-publisher@^1.0.6 publish submit <media-id>`

---

### 操作 4：查看草稿列表

**场景**：用户想查看所有草稿

**命令**：

```bash
npx --yes wechat-md-publisher@^1.0.6 draft list --page 1 --size 10
```

**输出示例**：
```
共 15 个草稿

┌──────────────────┬────────────────┬────────────────┐
│ Media ID         │ 标题           │ 更新时间       │
├──────────────────┼────────────────┼────────────────┤
│ 3_abc123         │ 测试文章       │ 2026-03-19     │
│ 3_def456         │ 产品介绍       │ 2026-03-18     │
└──────────────────┴────────────────┴────────────────┘
```

---

### 操作 5：查看已发布文章

**场景**：用户想查看已发布的文章

**命令**：

```bash
npx --yes wechat-md-publisher@^1.0.6 publish list --page 1 --size 10
```

**输出示例**：
```
共 8 篇已发布文章

┌──────────────┬────────────────┬────────────────┬──────────────────┐
│ Article ID   │ 标题           │ 发布时间       │ URL              │
├──────────────┼────────────────┼────────────────┼──────────────────┤
│ 2247483647_1 │ 最新文章       │ 2026-03-19     │ https://mp.we... │
└──────────────┴────────────────┴────────────────┴──────────────────┘
```

---

### 操作 6：删除草稿或文章

**删除草稿**：

```bash
npx --yes wechat-md-publisher@^1.0.6 draft delete <media-id>
```

**删除已发布文章**：

```bash
npx --yes wechat-md-publisher@^1.0.6 publish delete <article-id>
```

---

### 操作 7：查看可用主题

**命令**：

```bash
npx --yes wechat-md-publisher@^1.0.6 theme list
```

**输出示例**：
```
可用主题：

┌─────────────┬──────────────┬────────────────────┐
│ ID          │ 名称         │ 描述               │
├─────────────┼──────────────┼────────────────────┤
│ default     │ 默认主题     │ 简洁清爽风格       │
│ orangesun   │ Orange Sun   │ 温暖明亮风格       │
│ redruby     │ Red Ruby     │ 优雅醒目风格       │
│ greenmint   │ Green Mint   │ 清新舒适风格       │
│ purplerain  │ Purple Rain  │ 梦幻柔和风格       │
│ blackink    │ Black Ink    │ 深色模式风格       │
└─────────────┴──────────────┴────────────────────┘
```


---

## 🔧 高级用法

### Wrapper 功能：文章开头/结尾固定图文

在发布文章时自动在开头和结尾添加固定的图文内容（如关注引导、底部二维码等）。

**开启功能**：
```bash
npx --yes wechat-md-publisher@^1.0.6 wrapper on
```

**设置内容**：
```bash
npx --yes wechat-md-publisher@^1.0.6 wrapper set \
  --header "<div>欢迎关注我们的公众号</div>" \
  --footer "<div>觉得有帮助请点赞+收藏</div>"
```

**查看状态**：
```bash
npx --yes wechat-md-publisher@^1.0.6 wrapper status
```

**查看历史版本**：
```bash
npx --yes wechat-md-publisher@^1.0.6 wrapper history
```

**回滚到指定版本**：
```bash
npx --yes wechat-md-publisher@^1.0.6 wrapper rollback 1
```

**关闭功能**：
```bash
npx --yes wechat-md-publisher@^1.0.6 wrapper off
```

**注意事项**：
- 功能默认关闭，需要手动开启
- 每次 `set` 会创建新版本，支持历史回滚
- 图片处理：目前直接存储原始 HTML，需要公网可访问的图片 URL
- 数据库文件：`data/wmp.db`

---

### 使用编程 API

如果需要在代码中集成：

```javascript
const { container } = require('wechat-md-publisher');

async function publishArticle(markdown, theme) {
  await container.initialize();
  
  const publishService = await container.getPublishService();
  const result = await publishService.createAndPublish({
    markdown: markdown,
    theme: theme || 'default',
  });
  
  return result.publish_id;
}
```

### 批量发布

```bash
# 批量创建草稿
for file in articles/*.md; do
    npx --yes wechat-md-publisher@^1.0.6 draft create --file "$file" --theme default
done
```

---

## 📊 输入输出规范

### 输入格式

**Markdown 文件格式**：

```markdown
---
title: 文章标题（必需）
author: 作者名（可选）
cover: ./cover.jpg（可选，封面图路径）
---

# 正文标题

正文内容...

![图片描述](./image.jpg)
```

**支持的图片格式**：
- 本地图片：相对路径或绝对路径
- 网络图片：HTTP/HTTPS URL
- 微信图片：微信 CDN URL（自动识别）

### 输出格式

**成功响应**：
```json
{
  "success": true,
  "publish_id": "2247483647_1",
  "message": "发布成功"
}
```

**错误响应**：
```json
{
  "success": false,
  "error": "错误信息",
  "code": "ERROR_CODE"
}
```

---

## ⚠️ 常见问题和解决方案

### 问题 1：Token 过期

**症状**：提示"access_token 无效"

**解决**：Token 会自动刷新，如果仍有问题，重新配置账号

### 问题 2：图片上传失败

**症状**：提示"图片上传失败"

**原因**：
- 图片路径错误
- 图片大小超限（微信限制 10MB）
- 服务器 IP 不在白名单

**解决**：
- 检查图片路径
- 压缩图片
- 在微信公众平台添加 IP 到白名单

### 问题 3：找不到主题

**症状**：提示"主题不存在"

**解决**：使用 `npx --yes wechat-md-publisher@^1.0.6 theme list` 查看可用主题

### 问题 4：权限不足

**症状**：提示"没有权限"

**原因**：AppID/AppSecret 错误或权限不足

**解决**：
- 确认凭证正确
- 确认公众号类型支持该功能（服务号 vs 订阅号）

---

## 🔒 安全性说明

### 敏感信息处理

- AppID 和 AppSecret 存储在本地配置文件中
- 配置文件位置：
  - macOS: `~/Library/Preferences/wechat-md-publisher-nodejs/config.json`
  - Linux: `~/.config/wechat-md-publisher-nodejs/config.json`
  - Windows: `%APPDATA%\wechat-md-publisher-nodejs\Config\config.json`

### 权限要求

- 读取本地文件（Markdown 和图片）
- 网络访问（微信 API）
- 写入配置文件

### 数据隐私

- 不会上传任何数据到第三方服务器
- 所有通信仅限于微信官方 API
- 图片缓存仅在本地

---

## 📚 参考资料

- [项目 GitHub](https://github.com/sipingme/wechat-md-publisher)
- [微信公众平台文档](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html)
- [完整 API 文档](https://github.com/sipingme/wechat-md-publisher/blob/main/docs/API.md)

---

## 🎓 示例对话

**用户**：帮我把这篇文章发布到微信公众号

**AI**：好的，我来帮你发布。请提供文章的 Markdown 内容。

**用户**：[提供内容]

**AI**：收到！我将使用 orangesun 主题发布。正在处理...

[执行命令]

**AI**：✅ 文章已成功发布到微信公众号！
- 发布 ID: 2247483647_1
- 你可以在微信公众平台查看和管理这篇文章

---

## 📝 维护说明

- **版本**: 1.0.6
- **最后更新**: 2026-04-06
- **更新内容**: 
  - 优化主题样式：添加 text-align: left 到标题和 strong 元素
  - 移除 code 背景色以提高微信兼容性
  - 更新 wrapper header 为居中对齐
  - 应用于所有主题：default, greenmint, orangesun, purplerain, redruby, blackink
- **维护者**: Ping Si <[email protected]>
- **许可证**: Apache-2.0

---

## ✅ 首次成功检查清单

新用户应该能在 5 分钟内完成：

- [ ] 验证工具可用：`npx --yes wechat-md-publisher@^1.0.6 --version`
- [ ] 配置账号：`npx --yes wechat-md-publisher@^1.0.6 account add ...`
- [ ] 创建测试文章
- [ ] 发布成功：`npx --yes wechat-md-publisher@^1.0.6 publish create --file test.md --theme default`
- [ ] 在微信公众平台看到文章

如果以上步骤都能顺利完成，说明 Skill 已正确配置！

---

## 🔗 与其他 Skills 配合使用

### 与 news-to-markdown-skill 组合使用

**推荐组合**：`news-to-markdown-skill` + `wechat-md-publisher-skill` = 一键转载新闻到微信公众号

#### 使用场景

将网络上的新闻文章快速转载到微信公众号，实现内容聚合和分发。

#### 完整工作流

**场景 1：转载单篇新闻（推荐方式）**

```bash
# 步骤 1: 使用 news-to-markdown 提取新闻并下载图片
convert-url --url "https://www.toutiao.com/article/123" \
  --output /tmp/article/article.md \
  --download-images \
  --output-dir /tmp/article \
  --verbose

# 步骤 2: 使用 wechat-md-publisher 发布到微信
npx --yes wechat-md-publisher@^1.0.6 publish create \
  --file /tmp/article/article.md \
  --theme orangesun
```

**为什么要下载图片到本地？**
- 头条图片 URL 包含签名和过期时间，几小时后会失效
- 本地图片更可靠，不受网络波动影响
- 避免防盗链导致的图片加载失败

**场景 2：批量转载新闻**

```bash
# 新闻 URL 列表
urls=(
  "https://www.toutiao.com/article/123"
  "https://mp.weixin.qq.com/s/abc"
  "https://www.xiaohongshu.com/explore/xyz"
)

# 批量处理
for i in "!urls[@]"; do
  url="urls[$i]"
  output_dir="/tmp/article-$i"
  
  # 提取新闻并下载图片
  convert-url --url "$url" \
    --output "$output_dir/article.md" \
    --download-images \
    --output-dir "$output_dir"
  
  # 发布到微信（创建草稿）
  npx --yes wechat-md-publisher@^1.0.6 draft create \
    --file "$output_dir/article.md" \
    --theme default
  
  echo "✓ 已处理: $url"
done
```

**场景 3：AI 自动化工作流**

用户对 AI 说：
> "帮我把这篇头条文章转载到我的微信公众号"

AI 执行流程：
1. 使用 `news-to-markdown-skill` 提取文章内容
2. 自动检测平台（头条/微信/小红书）
3. 使用 `wechat-md-publisher-skill` 发布到微信
4. 返回发布结果和链接

#### 优势

✅ **智能内容提取**
- 自动识别新闻正文，过滤广告和噪音
- 保留文章结构和格式
- 提取标题、作者、发布时间等元数据

✅ **多平台支持**
- 头条：优化标题层级、列表、代码块
- 微信：提取 `#js_content` 区域
- 小红书：处理 `.note-content` 内容

✅ **三层抓取策略**
- curl → wget → Playwright
- 确保动态页面也能正确抓取

✅ **精美主题渲染**
- 8+ 精选主题可选
- 自动处理图片上传
- 保持排版美观

#### 最佳实践

**1. 内容审核**
```bash
# 先创建草稿，人工审核后再发布
convert-url --url "$news_url" --output /tmp/article.md
npx --yes wechat-md-publisher@^1.0.6 draft create --file /tmp/article.md --theme default

# 审核通过后发布
npx --yes wechat-md-publisher@^1.0.6 publish submit <media-id>
```

**2. 添加来源声明**
```bash
# 提取时保留元数据
convert-url --url "$news_url" --output /tmp/article.md

# 元数据会自动包含在 Markdown 中：
# ---
# title: 文章标题
# author: 原作者
# 来源: https://...
# ---
```

**3. 选择合适主题**
- 科技类文章：`default`（简洁蓝调）、`greenmint`（绿薄荷）
- 情感类文章：`orangesun`（橙色阳光）、`purplerain`（紫色雨）
- 教程类文章：`default`（简洁蓝调）、`greenmint`（绿薄荷）
- 正式商务：`redruby`（红宝石）、`purplerain`（紫色雨）
- 夜间阅读：`blackink`（黑墨水深色模式）

#### 示例对话

**用户**：把这篇头条文章转到我的微信公众号
https://www.toutiao.com/article/7000000000000000000/

**AI**：好的，我来帮你处理：

1. 正在提取文章内容...
   ```
   [INFO] 开始抓取: https://www.toutiao.com/article/...
   [INFO] 检测到平台: toutiao
   [INFO] 提取成功
   ```

2. 正在发布到微信公众号...
   ```
   ✓ 渲染完成
   ✓ 图片处理完成
   ✓ 创建草稿成功
   ✓ 发布成功
   ```

✅ **完成！**
- 文章标题：《xxx》
- 发布 ID: 2247483647_1
- 使用主题: orangesun
- 你可以在微信公众平台查看

#### 相关资源

- **news-to-markdown-skill**: https://github.com/sipingme/news-to-markdown-skill
- **news-to-markdown 核心库**: https://github.com/sipingme/news-to-markdown
- **npm 包**: `npm install -g news-to-markdown`

#### 技术栈

```
新闻网站
    ↓
news-to-markdown (提取 + 转换)
    ↓
Markdown 文件
    ↓
wechat-md-publisher (渲染 + 发布)
    ↓
微信公众号
```

---

## 💡 更多组合可能

### 与内容管理工具配合
- 配合 Git 进行版本管理
- 配合 CI/CD 实现自动发布
- 配合数据库存储发布记录

### 与 AI 工具配合
- AI 生成内容 → wechat-md-publisher 发布
- AI 润色文章 → wechat-md-publisher 发布
- AI 翻译文章 → wechat-md-publisher 发布

FILE:README.md
# WeChat MD Publisher - OpenClaw Skill

> 全功能微信公众号 Markdown 发布工具 - OpenClaw Skill 版本

## 🚀 快速安装

### 方法 1：从 ClawHub 安装（推荐）

```bash
openclaw skills install wechat-md-publisher
```

### 方法 2：从 GitHub 安装

```bash
openclaw skills install https://github.com/sipingme/wechat-md-publisher-skill
```

### 方法 3：手动安装

1. 克隆仓库：
```bash
git clone https://github.com/sipingme/wechat-md-publisher-skill.git
cd wechat-md-publisher-skill
```

2. 复制到 OpenClaw skills 目录：
```bash
cp -r . ~/.openclaw/skills/wechat-md-publisher/
```

3. 验证工具可用：
```bash
npx --yes wechat-md-publisher@^1.0.6 --version
```

## ✅ 验证安装

```bash
# 检查 Skill 是否可用
openclaw skills list --eligible

# 查看 Skill 详情
openclaw skills info wechat-md-publisher

# 测试命令
npx --yes wechat-md-publisher@^1.0.6 --version
```

## 📋 首次配置

### 1. 获取微信公众号凭证

1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
2. 进入「设置与开发」→「基本配置」
3. 获取「开发者ID(AppID)」和「开发者密码(AppSecret)」
4. 将服务器 IP 添加到「IP白名单」

### 2. 配置账号

```bash
# 推荐：使用环境变量（避免命令行暴露凭证）
export WECHAT_APP_ID="wx_your_app_id"
export WECHAT_APP_SECRET="your_app_secret"

npx --yes wechat-md-publisher@^1.0.6 account add \
  --name "我的公众号" \
  --default
```

### 3. 测试发布

```bash
# 创建测试文章
cat > test.md << 'EOF'
---
title: 测试文章
---
# Hello World
这是一篇测试文章。
EOF

# 发布
npx --yes wechat-md-publisher@^1.0.6 publish create --file test.md --theme default
```

## 🎯 使用方式

### 在 OpenClaw 对话中使用

**示例 1：发布文章**

```
用户: 帮我把这篇文章发布到微信公众号

[提供 Markdown 内容]

AI: 好的，我来帮你发布。正在使用 orangeheart 主题...
✓ 文章已成功发布！发布 ID: 2247483647_1
```

**示例 2：创建草稿**

```
用户: 先创建一个草稿，不要立即发布

AI: 明白，我会先创建草稿。
✓ 草稿创建成功，Media ID: 3_abc123
你可以在微信公众平台查看和编辑。
```

**示例 3：查看文章列表**

```
用户: 查看我已发布的微信文章

AI: 正在获取列表...
共 8 篇已发布文章：
1. 最新文章 (2026-03-19)
2. 产品介绍 (2026-03-18)
...
```

### 手动调用 Skill

```bash
# 使用 OpenClaw 命令
openclaw run wechat-md-publisher publish article.md orangeheart

# 或直接使用工具
npx --yes wechat-md-publisher@^1.0.6 publish create --file article.md --theme orangeheart
```

## � 与 news-to-markdown-skill 组合使用

**推荐组合**：一键转载新闻到微信公众号

### 快速示例

```bash
# 1. 提取新闻文章
convert-url --url "https://www.toutiao.com/article/123" \
  --output /tmp/article.md \
  --platform toutiao

# 2. 发布到微信公众号
npx --yes wechat-md-publisher@^1.0.6 publish create \
  --file /tmp/article.md \
  --theme orangeheart
```

### AI 自动化工作流

用户说：
> "帮我把这篇头条文章转载到我的微信公众号"

AI 自动执行：
1. 使用 `news-to-markdown-skill` 提取文章
2. 使用 `wechat-md-publisher-skill` 发布到微信
3. 返回发布结果

### 优势

✅ **智能提取** - 自动识别正文，过滤广告  
✅ **多平台支持** - 头条、微信、小红书  
✅ **精美渲染** - 8+ 主题可选  
✅ **一键发布** - 无需手动复制粘贴

详见 [SKILL.md](./SKILL.md) 中的完整集成指南。

---

## �📚 文档

- **[SKILL.md](./SKILL.md)** - 完整的 SOP 和使用指南（含 news-to-markdown 集成）
- **[quick-start.md](./references/quick-start.md)** - 5 分钟快速上手
- **[themes.md](./references/themes.md)** - 主题使用指南
- **[ip-whitelist-guide.md](./references/ip-whitelist-guide.md)** - IP 白名单配置指南 ⚠️ 重要

## 🎨 可用主题

- `default` - 简洁经典
- `orangeheart` - 温暖优雅 ⭐ 推荐
- `rainbow` - 活泼清爽
- `lapis` - 清新极简 ⭐ 推荐
- `pie` - 现代锐利
- `maize` - 柔和舒适
- `purple` - 简约文艺
- `phycat` - 薄荷清新
- `sport` - 运动风 🏃 活力动感

## 🔧 高级配置

### 环境变量（可选）

```bash
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export WECHAT_APP_ID="wx_your_app_id"
export WECHAT_APP_SECRET="your_app_secret"
```

### 自定义主题

```bash
# 添加本地主题（推荐）
npx --yes wechat-md-publisher@^1.0.6 theme add-local --name my-theme --path ./my-theme.css

# 添加远程主题 API（⚠️ 见下方安全警告）
npx --yes wechat-md-publisher@^1.0.6 theme add-remote --name md2wechat --url https://api.md2wechat.cn --key xxx
```

> ⚠️ **远程主题安全警告**：使用 `theme add-remote` 会向第三方服务器发送请求。请仅使用您信任的远程主题 API。远程主题端点不在本 skill 的默认网络权限范围内，需要用户明确配置并承担相应风险。

## ⚠️ 常见问题

### 问题 1：Skill 未被识别

**解决**：
```bash
openclaw skills refresh
openclaw skills info wechat-md-publisher
```

### 问题 2：权限错误

**解决**：
```bash
chmod +x ~/.openclaw/skills/wechat-md-publisher/scripts/publish.js
```

### 问题 3：找不到命令

**解决**：
```bash
# 本 Skill 使用 npx 动态执行，无需全局安装
npx --yes wechat-md-publisher@^1.0.6 --version
```

### 问题 4：Token 过期

Token 会自动刷新，如仍有问题：
```bash
npx --yes wechat-md-publisher@^1.0.6 account remove <account-id>
npx --yes wechat-md-publisher@^1.0.6 account add --name "新账号" --default
```

### 问题 5：更新 Skill 后依赖未更新

本 Skill 使用 `npx` 动态执行，会自动拉取指定版本的包。如需清除缓存：

```bash
# 清除 npx 缓存
npm cache clean --force

# 验证版本
npx --yes wechat-md-publisher@^1.0.6 --version
```

## 🔒 安全性

### 权限要求

- ✅ 读取本地 Markdown 和图片文件
- ✅ 网络访问（微信官方 API）
- ✅ 写入配置文件到 `~/.config/wechat-md-publisher-nodejs/`
- ⚠️ 可选：远程主题 API（仅当用户使用 `theme add-remote` 时）

### 数据隐私

- ✅ 默认情况下，所有通信仅限于微信官方 API
- ✅ 配置文件仅存储在本地（凭证加密由 [wechat-md-publisher](https://github.com/sipingme/wechat-md-publisher) npm 包处理）
- ❌ 不会自动收集用户信息
- ⚠️ **例外**：如果用户配置了远程主题（`theme add-remote`），会向该第三方端点发送请求

### 安全检查

```bash
# 使用 skill-vetter 检查（如果可用）
openclaw skills vet wechat-md-publisher
```

## 📊 Skill 评分

根据 OpenClaw 社区标准：

- ✅ **规范清晰度**: 5/5 - SKILL.md 结构完整
- ✅ **首次成功时间**: 5/5 - 5 分钟内可完成
- ✅ **实用性**: 5/5 - 解决实际发布需求
- ✅ **安全性**: 5/5 - 权限合理，无恶意代码

## 🤝 贡献

欢迎贡献！

- 报告问题：[GitHub Issues](https://github.com/sipingme/wechat-md-publisher/issues)
- 提交改进：[Pull Requests](https://github.com/sipingme/wechat-md-publisher/pulls)
- 讨论交流：[GitHub Discussions](https://github.com/sipingme/wechat-md-publisher/discussions)

## 📜 许可证

Apache-2.0 License

## 👤 作者

**Ping Si** <[email protected]>

- GitHub: [@sipingme](https://github.com/sipingme)
- 项目主页: [wechat-md-publisher](https://github.com/sipingme/wechat-md-publisher)

## 🙏 致谢

- [@wenyan-md/core](https://github.com/caol64/wenyan-core) - 提供精美主题和渲染引擎
- OpenClaw 社区 - 提供优秀的 AI Agent 框架

---

**让 AI 能够直接发布内容到微信公众号！** 🚀

FILE:config.json
{
  "name": "wechat-md-publisher",
  "version": "1.0.6",
  "requiredEnvVars": [],
  "optionalEnvVars": ["WECHAT_APP_ID", "WECHAT_APP_SECRET"],
  "skill": {
    "name": "wechat-md-publisher",
    "version": "1.0.6",
    "enabled": true,
    "autoInvoke": false
  },
  "commands": {
    "publish": {
      "script": "./scripts/run.js",
      "args": ["publish"],
      "description": "发布文章到微信公众号"
    },
    "draft": {
      "script": "./scripts/run.js",
      "args": ["draft"],
      "description": "创建微信公众号草稿"
    },
    "wrapper": {
      "script": "./scripts/run.js",
      "args": ["wrapper"],
      "description": "Wrapper 功能管理（文章开头/结尾固定图文）"
    },
    "list-drafts": {
      "script": "./scripts/run.js",
      "args": ["list-drafts"],
      "description": "列出所有草稿"
    },
    "list-published": {
      "script": "./scripts/run.js",
      "args": ["list-published"],
      "description": "列出已发布文章"
    },
    "themes": {
      "script": "./scripts/run.js",
      "args": ["themes"],
      "description": "列出可用主题"
    },
    "help": {
      "script": "./scripts/postinstall.js",
      "args": [],
      "description": "显示使用帮助"
    }
  },
  "environment": {
    "required": [
      "NODE_VERSION>=18.0.0"
    ],
    "optional": [
      "WECHAT_APP_ID",
      "WECHAT_APP_SECRET"
    ],
    "note": "凭证可通过环境变量或 CLI 命令 (account add --app-id xxx --app-secret xxx) 提供"
  },
  "install": {
    "type": "npx",
    "package": "wechat-md-publisher",
    "version": "^1.0.6",
    "execution": "npx --yes wechat-md-publisher@^1.0.6",
    "global": false,
    "autoInstall": false,
    "autoUpdate": false,
    "riskLevel": "moderate",
    "riskReason": "通过 npx 动态拉取并执行第三方 npm 包，存在供应链风险。使用前请审计源码。",
    "requiresApproval": true,
    "source": {
      "type": "npm",
      "registry": "https://registry.npmjs.org",
      "package": "wechat-md-publisher",
      "repository": "https://github.com/sipingme/wechat-md-publisher",
      "license": "Apache-2.0",
      "audit": "https://github.com/sipingme/wechat-md-publisher/blob/main/src/index.ts"
    },
    "verification": {
      "command": "npx --yes wechat-md-publisher@^1.0.6 --version",
      "expectedOutput": "1.0"
    }
  },
  "dependencies": {
    "npm": [
      "wechat-md-publisher@^1.0.6"
    ],
    "note": "Dependencies (jsdom, form-data-encoder, formdata-node) are bundled in wechat-md-publisher"
  },
  "credentials": {
    "required": [],
    "optional": ["WECHAT_APP_ID", "WECHAT_APP_SECRET"],
    "note": "凭证可通过环境变量或 CLI 命令提供（二选一）",
    "storage": {
      "location": "~/.config/wechat-md-publisher-nodejs/",
      "encryption": "AES-256",
      "handler": "wechat-md-publisher npm 包",
      "handlerRepo": "https://github.com/sipingme/wechat-md-publisher",
      "auditFile": "src/services/account.ts"
    },
    "securityNote": "凭证加密由上游 npm 包处理。使用前请审计 https://github.com/sipingme/wechat-md-publisher/blob/main/src/services/account.ts"
  },
  "permissions": {
    "filesystem": {
      "read": ["*.md", "*.jpg", "*.png", "*.gif"],
      "write": ["~/.config/wechat-md-publisher-nodejs/"]
    },
    "network": {
      "domains": ["registry.npmjs.org", "api.weixin.qq.com", "mp.weixin.qq.com"]
    }
  }
}

FILE:references/ip-whitelist-guide.md
# 微信公众号 IP 白名单配置指南

## 什么是 IP 白名单？

微信公众号为了安全，要求所有调用 API 的服务器 IP 必须在白名单中。如果 IP 不在白名单，API 调用会失败。

## 为什么需要配置？

当你使用 `wechat-md-publisher` 发布文章时，工具会从你的电脑/服务器向微信 API 发送请求。微信会检查请求来源的 IP 地址，只有在白名单中的 IP 才能成功调用。

## 如何获取你的 IP 地址？

### 方法 1：使用命令行（推荐）

```bash
# macOS/Linux
curl ifconfig.me

# 或
curl icanhazip.com

# 或
curl ipinfo.io/ip
```

### 方法 2：访问网站

访问以下任一网站查看你的公网 IP：
- https://www.ip.cn/
- https://ipinfo.io/
- https://ifconfig.me/

### 方法 3：在微信公众平台查看

登录微信公众平台后，在 IP 白名单设置页面，微信会显示你当前的 IP 地址。

## 如何配置 IP 白名单？

### 步骤 1：登录微信公众平台

访问 https://mp.weixin.qq.com/ 并登录

### 步骤 2：进入 IP 白名单设置

1. 点击左侧菜单「设置与开发」
2. 点击「基本配置」
3. 找到「IP白名单」部分
4. 点击「修改」或「查看」

### 步骤 3：添加 IP 地址

1. 点击「添加」按钮
2. 输入你的公网 IP 地址
3. 点击「确定」

**示例**：
```
123.456.789.012
```

### 步骤 4：验证配置

添加后，等待 1-2 分钟生效，然后测试：

```bash
wechat-pub account list
```

如果能正常显示账号列表，说明配置成功。

## 常见场景

### 场景 1：在家里使用

**问题**：家庭宽带的 IP 地址可能会变化

**解决方案**：
1. **短期方案**：每次 IP 变化后重新添加
2. **长期方案**：
   - 联系运营商申请固定 IP（可能需要付费）
   - 使用云服务器部署（推荐）

### 场景 2：在公司使用

**问题**：公司可能使用固定 IP 或代理

**解决方案**：
1. 询问 IT 部门获取公司的公网出口 IP
2. 将公司 IP 添加到白名单
3. 如果公司使用代理，需要添加代理服务器的 IP

### 场景 3：在云服务器使用

**推荐方案**：
1. 购买云服务器（阿里云、腾讯云、AWS 等）
2. 云服务器通常有固定的公网 IP
3. 将云服务器 IP 添加到白名单
4. 在云服务器上安装和使用 `wechat-md-publisher`

**优点**：
- ✅ IP 固定，不会变化
- ✅ 24/7 在线
- ✅ 可以设置定时任务自动发布
- ✅ 网络稳定

### 场景 4：使用 VPN 或代理

**问题**：VPN 会改变你的出口 IP

**解决方案**：
1. 关闭 VPN 后获取真实 IP
2. 将真实 IP 添加到白名单
3. 使用工具时关闭 VPN

或者：
1. 获取 VPN 的出口 IP
2. 将 VPN IP 添加到白名单
3. 使用工具时保持 VPN 连接

## 多 IP 配置

微信公众号支持添加多个 IP 地址（通常最多 10-20 个）。

**适用场景**：
- 在多个地点使用（家里、公司、咖啡厅）
- 团队协作（多人使用）
- 备用 IP（防止主 IP 失效）

**配置方法**：
在 IP 白名单页面，点击「添加」，逐个添加所有需要的 IP。

## 安全建议

### ✅ 推荐做法

1. **只添加必要的 IP**
   - 不要添加不信任的 IP
   - 定期检查和清理不再使用的 IP

2. **使用固定 IP**
   - 云服务器（推荐）
   - 固定宽带 IP

3. **定期更新**
   - IP 变化后及时更新白名单
   - 删除不再使用的 IP

### ❌ 不推荐做法

1. **不要使用公共 WiFi**
   - 公共 WiFi 的 IP 可能被多人共享
   - 存在安全风险

2. **不要添加 0.0.0.0 或通配符**
   - 微信不支持通配符
   - 必须添加具体的 IP 地址

3. **不要分享你的 AppSecret**
   - 即使 IP 在白名单中，也要保护好 AppSecret
   - 不要将 AppSecret 提交到 Git 仓库

## 故障排查

### 错误：IP 不在白名单

**症状**：
```
错误码: 40164
错误信息: invalid ip xxx.xxx.xxx.xxx, not in whitelist
```

**解决步骤**：

1. **确认当前 IP**：
   ```bash
   curl ifconfig.me
   ```

2. **检查白名单**：
   - 登录微信公众平台
   - 查看 IP 白名单列表
   - 确认当前 IP 是否在列表中

3. **添加 IP**：
   - 如果不在，添加当前 IP
   - 等待 1-2 分钟生效

4. **重试**：
   ```bash
   wechat-pub account list
   ```

### 错误：IP 频繁变化

**症状**：今天能用，明天就不能用了

**原因**：家庭宽带 IP 动态分配

**解决方案**：

**方案 1：使用云服务器（推荐）**
```bash
# 1. 购买云服务器（最低配置即可）
# 2. 在云服务器上安装工具
ssh user@your-server-ip
npm install -g wechat-md-publisher

# 3. 配置账号
wechat-pub account add --name "公众号" --app-id xxx --app-secret xxx

# 4. 使用
wechat-pub publish create --file article.md --theme default
```

**方案 2：申请固定 IP**
- 联系宽带运营商
- 申请固定公网 IP（可能需要额外费用）

**方案 3：使用 DDNS**
- 配置动态 DNS
- 使用脚本自动更新白名单（需要开发）

## 自动化脚本

### 检查 IP 是否变化

```bash
#!/bin/bash
# check-ip.sh

CURRENT_IP=$(curl -s ifconfig.me)
SAVED_IP=$(cat ~/.wechat-pub-ip 2>/dev/null)

if [ "$CURRENT_IP" != "$SAVED_IP" ]; then
    echo "⚠️  IP 已变化！"
    echo "旧 IP: $SAVED_IP"
    echo "新 IP: $CURRENT_IP"
    echo "请更新微信公众平台的 IP 白名单"
    echo "$CURRENT_IP" > ~/.wechat-pub-ip
else
    echo "✓ IP 未变化: $CURRENT_IP"
fi
```

使用：
```bash
chmod +x check-ip.sh
./check-ip.sh
```

## 推荐配置

### 个人用户

**推荐方案**：使用云服务器
- 成本：约 10-30 元/月
- 优点：IP 固定、稳定可靠
- 推荐服务商：阿里云、腾讯云、华为云

### 企业用户

**推荐方案**：公司服务器 + 固定 IP
- 在公司内网服务器部署
- 配置公司出口 IP 到白名单
- 设置定时任务自动发布

### 团队协作

**推荐方案**：共享云服务器
- 团队共用一台云服务器
- 所有成员通过 SSH 访问
- 统一的 IP 地址

## 总结

1. ✅ **必须配置 IP 白名单**才能使用微信公众号 API
2. ✅ 使用 `curl ifconfig.me` 获取当前 IP
3. ✅ 在微信公众平台添加 IP 到白名单
4. ✅ 推荐使用云服务器获得固定 IP
5. ✅ 定期检查和更新 IP 白名单

## 相关链接

- [微信公众平台](https://mp.weixin.qq.com/)
- [微信公众号开发文档](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Getting_Started_Guide.html)
- [IP 白名单说明](https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_access_token.html)

---

如有问题，请查看 [SKILL.md](../SKILL.md) 或提交 [Issue](https://github.com/sipingme/wechat-md-publisher/issues)。

FILE:references/quick-start.md
# WeChat Publisher - 快速开始指南

## 5 分钟快速上手

### 步骤 1：安装工具（1 分钟）

```bash
npm install -g wechat-md-publisher
```

### 步骤 2：配置账号（2 分钟）

1. 获取微信公众号凭证：
   - 登录 https://mp.weixin.qq.com/
   - 进入「设置与开发」→「基本配置」
   - 复制 AppID 和 AppSecret

2. 添加账号：

```bash
wechat-pub account add \
  --name "我的公众号" \
  --app-id "wx_your_app_id" \
  --app-secret "your_app_secret" \
  --default
```

### 步骤 3：创建测试文章（1 分钟）

```bash
cat > test-article.md << 'EOF'
---
title: 测试文章
author: 测试作者
---

# 欢迎使用 WeChat Publisher

这是一篇测试文章。

## 主要特性

- 完整的草稿管理
- 8 个精美主题
- 智能图片处理
EOF
```

### 步骤 4：发布文章（1 分钟）

```bash
wechat-pub publish create --file test-article.md --theme orangeheart
```

### 验证成功

如果看到以下输出，说明配置成功：

```
✓ 渲染完成
✓ 图片处理完成
✓ 创建草稿成功
✓ 发布成功

发布 ID: 2247483647_1
```

现在可以在微信公众平台查看你的文章了！

## 常用命令速查

```bash
# 查看所有主题
wechat-pub theme list

# 创建草稿
wechat-pub draft create --file article.md --theme lapis

# 查看草稿列表
wechat-pub draft list

# 查看已发布文章
wechat-pub publish list

# 删除草稿
wechat-pub draft delete <media-id>
```

## 下一步

- 阅读完整文档：[SKILL.md](../SKILL.md)
- 查看主题示例：[themes.md](./themes.md)
- 了解 API 用法：https://github.com/sipingme/wechat-md-publisher

FILE:references/themes.md
# WeChat Publisher - 主题使用指南

## 8 个内置主题

所有主题来自 [@wenyan-md/core](https://github.com/caol64/wenyan-core)，专为微信公众号优化。

### 1. default - 默认主题

**风格**：简洁经典，适合正式文章

**适用场景**：
- 企业公告
- 正式通知
- 技术文档
- 学术文章

**使用**：
```bash
wechat-pub publish create --file article.md --theme default
```

---

### 2. orangeheart - Orange Heart

**风格**：温暖优雅，橙色调

**适用场景**：
- 情感类文章
- 生活分享
- 品牌故事
- 温馨内容

**使用**：
```bash
wechat-pub publish create --file article.md --theme orangeheart
```

---

### 3. rainbow - Rainbow

**风格**：活泼清爽，多彩

**适用场景**：
- 轻松趣味内容
- 儿童教育
- 创意分享
- 娱乐资讯

**使用**：
```bash
wechat-pub publish create --file article.md --theme rainbow
```

---

### 4. lapis - Lapis

**风格**：清新极简，蓝色调

**适用场景**：
- 技术文章
- 专业内容
- 产品介绍
- 数据分析

**使用**：
```bash
wechat-pub publish create --file article.md --theme lapis
```

---

### 5. pie - Pie

**风格**：现代锐利，灵感来自 sspai.com

**适用场景**：
- 产品评测
- 设计分享
- 效率工具
- 科技资讯

**使用**：
```bash
wechat-pub publish create --file article.md --theme pie
```

---

### 6. maize - Maize

**风格**：柔和舒适，米黄色调

**适用场景**：
- 教育内容
- 知识分享
- 读书笔记
- 文化艺术

**使用**：
```bash
wechat-pub publish create --file article.md --theme maize
```

---

### 7. purple - Purple

**风格**：简约文艺，紫色调

**适用场景**：
- 个人博客
- 文艺创作
- 摄影作品
- 艺术展示

**使用**：
```bash
wechat-pub publish create --file article.md --theme purple
```

---

### 8. phycat - 物理猫-薄荷

**风格**：薄荷绿，结构清晰

**适用场景**：
- 科普文章
- 教程指南
- 步骤说明
- 知识讲解

**使用**：
```bash
wechat-pub publish create --file article.md --theme phycat
```

---

## 主题选择建议

### 按内容类型选择

| 内容类型 | 推荐主题 | 备选主题 |
|---------|---------|---------|
| 技术文章 | lapis | default, pie |
| 生活分享 | orangeheart | maize, rainbow |
| 产品介绍 | pie | lapis, default |
| 教育内容 | maize | phycat, default |
| 情感文章 | orangeheart | purple, maize |
| 科普教程 | phycat | lapis, maize |
| 创意内容 | rainbow | purple, orangeheart |
| 正式公告 | default | lapis |

### 按品牌调性选择

- **专业严谨**：default, lapis
- **温暖亲切**：orangeheart, maize
- **年轻活力**：rainbow, pie
- **文艺清新**：purple, phycat

---

## 测试所有主题

想要对比不同主题的效果？可以批量测试：

```bash
# 创建测试文章
cat > test.md << 'EOF'
---
title: 主题测试
---

# 标题一

这是正文内容。

## 标题二

- 列表项 1
- 列表项 2

**粗体文本** 和 *斜体文本*
EOF

# 测试所有主题
for theme in default orangeheart rainbow lapis pie maize purple phycat; do
    echo "测试主题: $theme"
    wechat-pub draft create --file test.md --theme $theme
done
```

然后在微信公众平台查看对比效果。

---

## 自定义主题

如果内置主题不满足需求，可以创建自定义主题：

### 1. 创建 CSS 文件

```css
/* my-theme.css */
:root {
    --primary-color: #ff6b6b;
    --text-color: #2c3e50;
}

#wenyan {
    font-size: 16px;
    line-height: 1.8;
}

#wenyan h1 {
    color: var(--primary-color);
    border-bottom: 3px solid var(--primary-color);
}
```

### 2. 添加主题

```bash
wechat-pub theme add-local --name my-theme --path ./my-theme.css
```

### 3. 使用主题

```bash
wechat-pub publish create --file article.md --theme my-theme
```

---

## 主题预览

想要在发布前预览主题效果？

1. 先创建草稿：
```bash
wechat-pub draft create --file article.md --theme orangeheart
```

2. 在微信公众平台查看草稿预览

3. 满意后再发布：
```bash
wechat-pub publish submit <media-id>
```

---

## 常见问题

### Q: 如何查看所有可用主题？

```bash
wechat-pub theme list
```

### Q: 主题可以修改吗？

内置主题不可修改，但可以：
- 创建自定义主题
- 基于内置主题修改后另存为新主题

### Q: 发布后可以更换主题吗？

不可以。已发布的文章主题无法更改，需要：
1. 删除原文章
2. 用新主题重新发布

### Q: 哪个主题最受欢迎？

根据社区反馈：
1. **orangeheart** - 温暖优雅，适用范围广
2. **lapis** - 专业清爽，技术文章首选
3. **pie** - 现代时尚，年轻用户喜爱

建议根据自己的内容风格和受众选择。

FILE:scripts/postinstall.js
#!/usr/bin/env node

/**
 * 安装后提示脚本
 * 显示可用功能和使用方式
 */

const CYAN = '\x1b[36m';
const GREEN = '\x1b[32m';
const YELLOW = '\x1b[33m';
const RESET = '\x1b[0m';
const BOLD = '\x1b[1m';

console.log(`
BOLDGREEN✅ wechat-md-publisher SkillRESET

BOLD📋 功能说明：RESET
   发布 Markdown 文章到微信公众号，支持：
   - 草稿管理（创建、列表、删除）
   - 多主题样式（8+ 内置主题）
   - 智能图片处理（自动上传）
   - 自动封面图
   - Wrapper 功能（文章开头/结尾固定图文）

BOLD⚙️  环境变量配置（必需）：RESET
   YELLOW# 推荐：使用环境变量（避免命令行暴露凭证）RESET
   export WECHAT_APP_ID="wx_your_app_id"
   export WECHAT_APP_SECRET="your_app_secret"

BOLD🚀 快速开始：RESET

   YELLOW# 1. 配置账号RESET
   npx --yes wechat-md-publisher@^1.0.0 account add \\
     --name "我的公众号" \\
     --default

   YELLOW# 2. 发布文章RESET
   npx --yes wechat-md-publisher@^1.0.0 publish create \\
     --file article.md \\
     --theme orangesun

   YELLOW# 3. 创建草稿（不立即发布）RESET
   npx --yes wechat-md-publisher@^1.0.0 draft create \\
     --file article.md \\
     --theme default

   YELLOW# 4. 查看可用主题RESET
   npx --yes wechat-md-publisher@^1.0.0 theme list

BOLD🎨 可用主题：RESET
   CYANdefaultRESET      简洁经典
   CYANorangesunRESET    温暖优雅 ⭐ 推荐
   CYANgreenmintRESET    清新薄荷
   CYANpurplerainRESET   优雅紫色
   CYANredrubyRESET      热情红宝石
   CYANblackinkRESET     简约水墨

BOLD⚙️  常用命令：RESET
   CYANaccount addRESET      添加公众号账号
   CYANaccount listRESET     列出所有账号
   CYANpublish createRESET   发布文章
   CYANdraft createRESET     创建草稿
   CYANdraft listRESET       列出草稿
   CYANtheme listRESET       列出可用主题
   CYANwrapper on/offRESET   开启/关闭 Wrapper

BOLD⚠️  安全提示：RESET
   - 凭证存储在 ~/.config/wechat-md-publisher-nodejs/（AES-256 加密）
   - 推荐使用环境变量传递凭证，避免命令行暴露
   - 远程主题端点可能接收文章内容，请只使用可信任的主题源

BOLD📖 更多信息：RESET
   npx --yes wechat-md-publisher@^1.0.0 --help
   https://github.com/sipingme/wechat-md-publisher
`);

FILE:scripts/run.js
#!/usr/bin/env node

const { spawnSync } = require('node:child_process');

// 所需版本（与 config.json 中 dependencies.npm 保持一致）
const REQUIRED_VERSION = '1.0.6';

const action = process.argv[2];
const args = process.argv.slice(3);

if (!action) {
  showHelp();
  process.exit(0);
}

const run = (cmd, cmdArgs) => {
  const result = spawnSync(cmd, cmdArgs, { stdio: 'inherit' });
  if (result.error) {
    console.error(JSON.stringify({ success: false, error: result.error.message }));
    process.exit(1);
  }
  process.exit(result.status ?? 1);
};

/**
 * 使用 npx 执行 wechat-pub 命令
 */
const runWechatPub = (pubArgs) => {
  // 使用 npx 强制指定版本执行，自动从 registry 拉取（如有缓存则使用缓存）
  run('npx', ['--yes', `wechat-md-publisher@^REQUIRED_VERSION`, ...pubArgs]);
};

function showHelp() {
  console.log(`WeChat Publisher - 使用说明

用法:
  publish <file> [theme]     - 发布文章
  draft <file> [theme]       - 创建草稿
  list-drafts                - 列出草稿
  list-published             - 列出已发布文章
  themes                     - 列出可用主题
  help                       - 显示帮助

示例:
  publish article.md orangeheart
  draft article.md lapis
`);
}

switch (action) {
  case 'publish': {
    const file = args[0];
    const theme = args[1] || 'default';
    if (!file) {
      console.error('错误: 请提供文件路径');
      console.error('用法: publish <file> [theme]');
      process.exit(1);
    }
    console.log('正在发布文章...');
    runWechatPub(['publish', 'create', '--file', file, '--theme', theme]);
    break;
  }

  case 'draft': {
    const file = args[0];
    const theme = args[1] || 'default';
    if (!file) {
      console.error('错误: 请提供文件路径');
      console.error('用法: draft <file> [theme]');
      process.exit(1);
    }
    console.log('正在创建草稿...');
    runWechatPub(['draft', 'create', '--file', file, '--theme', theme]);
    break;
  }

  case 'wrapper': {
    // 透传所有参数给 wrapper 命令
    runWechatPub(['wrapper', ...args]);
    break;
  }

  case 'list-drafts':
    console.log('草稿列表:');
    runWechatPub(['draft', 'list']);
    break;

  case 'list-published':
    console.log('已发布文章:');
    runWechatPub(['publish', 'list']);
    break;

  case 'themes':
    console.log('可用主题:');
    runWechatPub(['theme', 'list']);
    break;

  case 'help':
  default:
    showHelp();
    break;
}