@wenyan-md/cli 1.0.11 → 2.0.0

package/README.docker.md

@@ -125,6 +125,37 @@ WECHAT_APP_SECRET=yyy
 -   Runtime: Node.js (bundled)
 -   Architecture: `linux/amd64`, `linux/arm64`
 
+## Server Mode
+
+Deploy on a cloud server with fixed IP to solve WeChat API whitelist requirements:
+
+```bash
+docker run -d --name wenyan-server \
+  -p 3000:3000 \
+  --env-file .env \
+  caol64/wenyan-cli \
+  serve --port 3000
+```
+
+Then call the REST API from your local machine:
+
+```bash
+# Health check
+curl http://your-server-ip:3000/health
+
+# Render
+curl -X POST http://your-server-ip:3000/render \
+  -H "Content-Type: application/json" \
+  -d '{"content": "# Hello World", "theme": "default"}'
+
+# Publish
+curl -X POST http://your-server-ip:3000/publish \
+  -H "Content-Type: application/json" \
+  -d '{"file": "/mnt/host-downloads/article.md"}'
+```
+
+> **Note:** Add your server's public IP to WeChat Official Account whitelist once, and it works permanently.
+
 ## License
 
 Apache License Version 2.0

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-    <img alt = "logo" src="https://raw.githubusercontent.com/caol64/wenyan/main/Data/256-mac.png" />
+    <img alt="logo" src="https://raw.githubusercontent.com/caol64/wenyan/main/Data/256-mac.png" width="128" />
 </div>
 
 # 文颜 CLI
@@ -27,214 +27,121 @@
 
 -   [macOS App Store 版](https://github.com/caol64/wenyan) - MAC 桌面应用
 -   [跨平台桌面版](https://github.com/caol64/wenyan-pc) - Windows/Linux
--   👉 [CLI 版本](https://github.com/caol64/wenyan-cli) - 本项目
+-   👉[CLI 版本](https://github.com/caol64/wenyan-cli) - 本项目
 -   [MCP 版本](https://github.com/caol64/wenyan-mcp) - AI 自动发文
+-   [UI 库](https://github.com/caol64/wenyan-ui) - 桌面应用和 Web App 共用的 UI 层封装
 -   [核心库](https://github.com/caol64/wenyan-core) - 嵌入 Node / Web 项目
 
-## 安装方式
+## 特性
 
-### 方式一：npm（推荐）
+- 一键发布 Markdown 到微信公众号草稿箱
+- 自动上传本地图片与封面
+- 支持远程 Server 发布（绕过 IP 白名单限制）
+- 内置多套精美排版主题
+- 支持自定义主题
+- 支持 Docker 和 npm
+- 可作为 CI/CD 自动发文工具
+- 可集成 AI Agent 自动发布
 
-```bash
-npm install -g @wenyan-md/cli
-```
+## 本地模式和远程客户端模式
 
-安装完成后即可使用：
+文颜 CLI 支持两种运行模式：**本地模式（Local Mode）** 和 **远程客户端模式（Client–Server Mode）**。两种模式运行效果完全一致，你可以根据运行环境和网络条件选择最合适的方式。
 
-```bash
-wenyan --help
-```
-
-### 方式二：Docker（无需 Node 环境）
+### 本地模式（Local Mode）
 
-如果你不想在本地安装 Node.js，也可以直接使用 Docker。
+在本地模式下，CLI 直接调用微信公众号 API 完成图片上传和草稿发布。
 
-**拉取镜像**
-
-```bash
-docker pull caol64/wenyan-cli
-```
-
-**查看帮助**
-
-```bash
-docker run --rm caol64/wenyan-cli
-```
-
-**发布文章示例**
-
-```bash
-docker run --rm \
-  --env-file .env.test \
-  -e HOST_FILE_PATH=$(pwd) \
-  -v $(pwd):/mnt/host-downloads \
-  caol64/wenyan-cli \
-  publish -f ./test/publish.md -t phycat
+```mermaid
+flowchart LR
+    CLI[Wenyan CLI] --> Wechat[公众号 API]
 ```
 
-> 说明：
->
-> -   使用 `-e` 传入环境变量
-> -   使用 `-v` 挂载本地 Markdown 文件
-> -   容器启动即执行 `wenyan` 命令
-
-## 基本用法
-
-CLI 主命令：
-
-```bash
-wenyan <command> [options]
-```
-
-目前支持的子命令有
-- `publish` 排版并发布到公众号草稿箱
-- `render` 仅排版，用做测试
-- `theme` 主题管理
-
-## 子命令
-
-### `publish`
-
-将 Markdown 转换为适配微信公众号的富文本 HTML，并上传到草稿箱。
-
-#### 参数
-
--   `<input-content>`
-
-    Markdown 内容，可以：
-
-    -   直接作为参数传入
-    -   通过 stdin 管道输入
-
-#### 常用选项
+**优点：**
 
--   `-t <theme-id>`：主题id（默认 `default`），可以是内置主题，也可以是通过`theme --add`添加的自定义主题
-    -   [内置主题](https://github.com/caol64/wenyan-core/tree/main/src/assets/themes)
--   `-h <highlight-theme-id>`：代码高亮主题（默认 `solarized-light`）
-    -   atom-one-dark / atom-one-light / dracula / github-dark / github / monokai / solarized-dark / solarized-light / xcode
--   `--no-mac-style`：关闭代码块 Mac 风格
--   `--no-footnote`：关闭链接转脚注
--   `-f <path>`：指定本地 Markdown 文件路径
--   `-c <path>`：指定临时自定义主题路径，优先级大于`-t`
+* 无需额外服务器
+* 架构简单，部署成本低
+* 适合个人开发者和本地使用
 
-#### 使用示例
+**限制：**
 
-直接传入内容：
+> ⚠️ 微信公众号 API 要求调用方 IP 必须在白名单内。如果没有固定 IP，需要频繁添加白名单。
 
-```bash
-wenyan publish "# Hello, Wenyan" -t lapis -h solarized-light
-```
+### 远程客户端模式（Client–Server Mode）
 
-从管道读取：
+在此模式下，CLI 作为客户端，将发布请求发送到部署在云服务器上的 Wenyan Server，由 Server 完成微信公众号 API 调用。
 
-```bash
-cat example.md | wenyan publish -t lapis -h solarized-light --no-mac-style
-```
+```mermaid
+flowchart LR
 
-从文件读取：
+    Client[Wenyan CLI Client]
+    Server[Wenyan Server]
+    Wechat[公众号 API]
 
-```bash
-wenyan publish -f "./example.md" -t lapis -h solarized-light --no-mac-style
+    Client -->|Markdown + Images| Server
+    Server -->|Upload Media| Wechat
+    Server -->|Create Draft| Wechat
+    Server -->|Result| Client
 ```
 
-### `theme`
+**优点：**
 
-主题管理，浏览内置主题、添加/删除自定义主题。
+* 无需本地固定 IP
+* 完美绕过微信 IP 白名单限制
+* 支持动态 IP 环境
+* 支持团队协作
+* 支持 CI/CD 自动发布
+* 支持 AI Agent 自动发布
 
-#### 参数
+### Server 模式部署
 
-无。
+[文档](docs/server.md)。
 
-#### 常用选项
+## 安装说明
 
--   `-l`：列出所有可用主题
--   `--add`：添加自定义主题（永久）
-    -   `--name <name>`：主题名称
-    -   `--path <path>`：主题路径（本地或网络）
--   `--rm <name>`：删除自定义主题
-
-#### 使用示例
-
-列出可用主题：
+### npm 安装（推荐）
 
 ```bash
-wenyan theme -l
-```
-
-安装自定义主题
-
-```bash
-wenyan theme --add --name new-theme --path https://wenyan.yuzhi.tech/manhua.css
+npm install -g @wenyan-md/cli
 ```
 
-删除自定义主题
+运行：
 
 ```bash
-wenyan theme --rm new-theme
+wenyan --help
 ```
 
-## 使用自定义主题
+### docker 安装
 
-你可以通过两种途径使用自定义主题：
-
-- 不安装直接使用
-
-```bash
-wenyan publish -f "./example.md" -c "/path/to/theme" -h solarized-light --no-mac-style
-```
+[文档](docs/docker.md)。
 
-- 先安装再使用：
+## 命令概览
 
 ```bash
-wenyan theme --add --name new-theme --path https://wenyan.yuzhi.tech/manhua.css
-wenyan publish -f "./example.md" -t new-theme -h solarized-light --no-mac-style
+wenyan <command> [options]
 ```
 
-区别在于，安装后的主题永久有效。
+| 命令      | 说明        |
+| ------- | --------- |
+| [publish](docs/publish.md) | 发布文章      |
+| render  | 渲染 HTML   |
+| [theme](docs/theme.md)   | 管理主题      |
+| [serve](docs/server.md)   | 启动 Server |
 
-## 关于图片自动上传
+## 关于图片与封面自动上传
 
-支持以下图片来源：
+无论是本地模式还是远程客户端模式，文颜 CLI 都提供**极度智能**的图片处理机制：
 
--   本地路径（如：`/Users/xxx/image.jpg`）
--   网络路径（如：`https://example.com/image.jpg`）
+- 识别并支持本地硬盘绝对路径（如：`/Users/xxx/image.jpg`）
+- 识别并支持当前目录的相对路径（如：`./assets/image.png`）
+- 识别并支持网络路径（如：`https://example.com/image.jpg`）
 
 ## 环境变量配置
 
-部分功能（如发布微信公众号）需要配置以下环境变量：
+在实际向微信公众号发文的环境（你的本地或部署 `serve` 的服务器）中，必须配置以下环境变量：
 
 -   `WECHAT_APP_ID`
 -   `WECHAT_APP_SECRET`
 
-### macOS / Linux
-
-临时使用：
-
-```bash
-WECHAT_APP_ID=xxx WECHAT_APP_SECRET=yyy wenyan publish "your markdown"
-```
-
-永久配置（推荐）：
-
-```bash
-export WECHAT_APP_ID=xxx
-export WECHAT_APP_SECRET=yyy
-```
-
-### Windows (PowerShell)
-
-临时使用：
-
-```powershell
-$env:WECHAT_APP_ID="xxx"
-$env:WECHAT_APP_SECRET="yyy"
-wenyan publish example.md
-```
-
-永久设置（在环境变量里添加）：
-
-控制面板 → 系统和安全 → 系统 → 高级系统设置 → 环境变量 → 添加 `WECHAT_APP_ID` 和 `WECHAT_APP_SECRET`。
-
 ## 微信公众号 IP 白名单
 
 > [!IMPORTANT]

package/dist/cli.js

@@ -1,4 +1,132 @@
 #!/usr/bin/env node
-import { createProgram } from "./index.js";
+import { Command } from "commander";
+import { publishCommand } from "./commands/publish.js";
+import { prepareRenderContext } from "./commands/render.js";
+import pkg from "../package.json" with { type: "json" };
+import { addTheme, listThemes, removeTheme } from "./commands/theme.js";
+function createProgram(version = pkg.version) {
+    const program = new Command();
+    program
+        .name("wenyan")
+        .description("A CLI for WenYan Markdown Render.")
+        .version(version, "-v, --version", "output the current version")
+        .action(() => {
+        program.outputHelp();
+    });
+    const addCommonOptions = (cmd) => {
+        return cmd
+            .argument("[input-content]", "markdown content (string input)")
+            .option("-f, --file <path>", "read markdown content from local file")
+            .option("-t, --theme <theme-id>", "ID of the theme to use", "default")
+            .option("-h, --highlight <highlight-theme-id>", "ID of the code highlight theme to use", "solarized-light")
+            .option("-c, --custom-theme <path>", "path to custom theme CSS file")
+            .option("--mac-style", "display codeblock with mac style", true)
+            .option("--no-mac-style", "disable mac style")
+            .option("--footnote", "convert link to footnote", true)
+            .option("--no-footnote", "disable footnote");
+    };
+    const pubCmd = program
+        .command("publish")
+        .description("Render a markdown file to styled HTML and publish to wechat GZH");
+    // 先添加公共选项，再追加 publish 专属选项
+    addCommonOptions(pubCmd)
+        .option("--server <url>", "Server URL to publish through (e.g. https://api.yourdomain.com)")
+        .option("--api-key <apiKey>", "API key for the remote server")
+        .action(async (inputContent, options) => {
+        await runCommandWrapper(async () => {
+            // 如果传入了 --server，则走客户端（远程）模式
+            if (options.server) {
+                options.clientVersion = version; // 将 CLI 版本传递给服务器，便于调试和兼容性处理
+                const { publishClient } = await import("./commands/client.js");
+                const mediaId = await publishClient(inputContent, options);
+                console.log(`发布成功，Media ID: ${mediaId}`);
+            }
+            else {
+                // 走原有的本地直接发布模式
+                const mediaId = await publishCommand(inputContent, options);
+                console.log(`发布成功，Media ID: ${mediaId}`);
+            }
+        });
+    });
+    const renderCmd = program.command("render").description("Render a markdown file to styled HTML");
+    addCommonOptions(renderCmd).action(async (inputContent, options) => {
+        await runCommandWrapper(async () => {
+            const { gzhContent } = await prepareRenderContext(inputContent, options);
+            console.log(gzhContent.content);
+        });
+    });
+    program
+        .command("theme")
+        .description("Manage themes")
+        .option("-l, --list", "List all available themes")
+        .option("--add", "Add a new custom theme")
+        .option("--name <name>", "Name of the new custom theme")
+        .option("--path <path>", "Path to the new custom theme CSS file")
+        .option("--rm <name>", "Name of the custom theme to remove")
+        .action(async (options) => {
+        await runCommandWrapper(async () => {
+            const { list, add, name, path, rm } = options;
+            if (list) {
+                const themes = listThemes();
+                console.log("内置主题：");
+                themes
+                    .filter((theme) => theme.isBuiltin)
+                    .forEach((theme) => {
+                    console.log(`- ${theme.id}: ${theme.description ?? ""}`);
+                });
+                const customThemes = themes.filter((theme) => !theme.isBuiltin);
+                if (customThemes.length > 0) {
+                    console.log("\n自定义主题：");
+                    customThemes.forEach((theme) => {
+                        console.log(`- ${theme.id}: ${theme.description ?? ""}`);
+                    });
+                }
+                console.log("");
+                return;
+            }
+            if (add) {
+                await addTheme(name, path);
+                console.log(`主题 "${name}" 已添加\n`);
+                return;
+            }
+            if (rm) {
+                await removeTheme(rm);
+                console.log(`主题 "${rm}" 已删除\n`);
+            }
+        });
+    });
+    program
+        .command("serve")
+        .description("Start a server to provide HTTP API for rendering and publishing")
+        .option("-p, --port <port>", "Port to listen on (default: 3000)", "3000")
+        .option("--api-key <apiKey>", "API key for authentication")
+        .action(async (options) => {
+        try {
+            const { serveCommand } = await import("./commands/serve.js");
+            const port = options.port ? parseInt(options.port, 10) : 3000;
+            await serveCommand({ port, version, apiKey: options.apiKey });
+        }
+        catch (error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+    });
+    return program;
+}
+// --- 统一的错误处理包装器 ---
+async function runCommandWrapper(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(error.message);
+        }
+        else {
+            console.error("An unexpected error occurred:", error);
+        }
+        process.exit(1);
+    }
+}
 const program = createProgram();
 program.parse(process.argv);

package/dist/commands/client.js

@@ -0,0 +1,208 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { FormData, File } from "formdata-node";
+import { FormDataEncoder } from "form-data-encoder";
+import { AppError } from "../types.js";
+import { prepareRenderContext } from "./render.js";
+import { JSDOM } from "jsdom";
+export async function publishClient(inputContent, options) {
+    const { theme, customTheme, highlight, macStyle, footnote, apiKey, clientVersion, server } = options;
+    const serverUrl = server.replace(/\/$/, ""); // 移除末尾的斜杠
+    const headers = {};
+    if (clientVersion) {
+        headers["x-client-version"] = clientVersion;
+    }
+    if (apiKey) {
+        headers["x-api-key"] = apiKey;
+    }
+    // ==========================================
+    // 0. 连通性与鉴权测试 (Health & Auth Check)
+    // ==========================================
+    console.log(`[Client] Checking server connection at ${serverUrl} ...`);
+    try {
+        // 1. 物理连通性与服务指纹验证
+        const healthRes = await fetch(`${serverUrl}/health`, { method: "GET" });
+        if (!healthRes.ok) {
+            throw new Error(`HTTP Error: ${healthRes.status} ${healthRes.statusText}`);
+        }
+        const healthData = await healthRes.json();
+        if (healthData.status !== "ok" || healthData.service !== "wenyan-cli") {
+            throw new Error(`Invalid server response. Make sure the server URL is correct.`);
+        }
+        console.log(`[Client] Server connected successfully (version: ${healthData.version})`);
+        // 2. 鉴权探针测试
+        console.log(`[Client] Verifying authorization...`);
+        const verifyRes = await fetch(`${serverUrl}/verify`, {
+            method: "GET",
+            headers, // 携带 x-api-key 和 x-client-version
+        });
+        if (verifyRes.status === 401) {
+            throw new Error("鉴权失败 (401)：Server 拒绝访问，请检查传入的 --api-key 是否正确。");
+        }
+        if (!verifyRes.ok) {
+            throw new Error(`Verify Error: ${verifyRes.status} ${verifyRes.statusText}`);
+        }
+        console.log(`[Client] Authorization passed.`);
+    }
+    catch (error) {
+        if (error.message.includes("鉴权失败")) {
+            throw error;
+        }
+        throw new Error(`Failed to connect to server (${serverUrl}). \nPlease check if the server is running and the network is accessible. \nDetails: ${error.message}`);
+    }
+    // ==========================================
+    // 1. 读取 markdown 文件，获取其所在目录（用于解析相对图片路径），并渲染成 HTML 格式
+    // ==========================================
+    const { gzhContent, absoluteDirPath } = await prepareRenderContext(inputContent, options);
+    if (!gzhContent.title)
+        throw new AppError("未能找到文章标题");
+    if (!gzhContent.cover)
+        throw new AppError("未能找到文章封面");
+    // ==========================================
+    // [内部辅助函数] 提取公共的本地图片上传逻辑
+    // ==========================================
+    const uploadLocalImage = async (originalUrl) => {
+        let imagePath = originalUrl;
+        if (!path.isAbsolute(imagePath)) {
+            // 如果是相对路径，以 markdown 文件所在目录为基准进行拼接
+            imagePath = path.resolve(absoluteDirPath || process.cwd(), imagePath);
+        }
+        if (!fs.existsSync(imagePath)) {
+            console.warn(`[Client] Warning: Local image not found: ${imagePath}`);
+            return null;
+        }
+        try {
+            const fileBuffer = fs.readFileSync(imagePath);
+            const filename = path.basename(imagePath);
+            // 推断 Content-Type
+            const ext = path.extname(filename).toLowerCase();
+            const mimeTypes = {
+                ".jpg": "image/jpeg",
+                ".jpeg": "image/jpeg",
+                ".png": "image/png",
+                ".gif": "image/gif",
+                ".webp": "image/webp",
+                ".svg": "image/svg+xml",
+            };
+            const type = mimeTypes[ext] || "application/octet-stream";
+            // 构建图片上传表单
+            const form = new FormData();
+            form.append("file", new File([fileBuffer], filename, { type }));
+            const encoder = new FormDataEncoder(form);
+            console.log(`[Client] Uploading local image: ${filename} ...`);
+            const uploadRes = await fetch(`${serverUrl}/upload`, {
+                method: "POST",
+                headers: { ...headers, ...encoder.headers },
+                body: Readable.from(encoder),
+                duplex: "half",
+            });
+            if (uploadRes.status === 401) {
+                throw new Error("鉴权失败 (401)：Server 拒绝访问，请检查传入的 --api-key 是否正确。");
+            }
+            const uploadData = await uploadRes.json();
+            if (uploadRes.ok && uploadData.success) {
+                // 返回可供 Server 直接使用的协议路径
+                return `asset://${uploadData.data.fileId}`;
+            }
+            else {
+                console.warn(`[Client] Warning: Failed to upload ${filename}: ${uploadData.error || uploadData.desc}`);
+                return null;
+            }
+        }
+        catch (error) {
+            if (error.message.includes("鉴权失败") || error.message.includes("401")) {
+                throw error;
+            }
+            console.warn(`[Client] Warning: Error uploading ${imagePath} - ${error.message}`);
+            return null;
+        }
+    };
+    // ==========================================
+    // 2. 解析 HTML 中的所有本地图片上传并替换为服务器可访问的 URL
+    // ==========================================
+    let modifiedContent = gzhContent.content;
+    if (modifiedContent.includes("<img")) {
+        const dom = new JSDOM(modifiedContent);
+        const document = dom.window.document;
+        const images = Array.from(document.querySelectorAll("img"));
+        // 并发上传所有插图
+        const uploadPromises = images.map(async (element) => {
+            const dataSrc = element.getAttribute("src");
+            if (dataSrc && needUpload(dataSrc)) {
+                const newUrl = await uploadLocalImage(dataSrc);
+                if (newUrl) {
+                    element.setAttribute("src", newUrl); // 替换 DOM 中的属性
+                }
+            }
+        });
+        await Promise.all(uploadPromises);
+        modifiedContent = document.body.innerHTML;
+        gzhContent.content = modifiedContent;
+    }
+    // ==========================================
+    // 3. 处理封面图片
+    // ==========================================
+    const cover = gzhContent.cover;
+    if (cover && needUpload(cover)) {
+        console.log(`[Client] Processing cover image...`);
+        const newCoverUrl = await uploadLocalImage(cover);
+        if (newCoverUrl) {
+            gzhContent.cover = newCoverUrl; // 将封面路径替换为 asset://fileId
+        }
+    }
+    // ==========================================
+    // 4. 将替换后的 content 保存成临时文件/流，并上传
+    // ==========================================
+    const mdFilename = "publish_target.json"; // 这个文件名对服务器来说没有实际意义，只是一个标识
+    const mdForm = new FormData();
+    mdForm.append("file", new File([Buffer.from(JSON.stringify(gzhContent), "utf-8")], mdFilename, { type: "application/json" }));
+    const mdEncoder = new FormDataEncoder(mdForm);
+    console.log(`[Client] Uploading compiled document ...`);
+    const mdUploadRes = await fetch(`${serverUrl}/upload`, {
+        method: "POST",
+        headers: { ...headers, ...mdEncoder.headers },
+        body: Readable.from(mdEncoder),
+        duplex: "half",
+    });
+    if (mdUploadRes.status === 401) {
+        throw new Error("鉴权失败 (401)：Server 拒绝访问，请检查传入的 --api-key 是否正确。");
+    }
+    const mdUploadData = await mdUploadRes.json();
+    if (!mdUploadRes.ok || !mdUploadData.success) {
+        throw new Error(`Upload Document Failed: ${mdUploadData.error || mdUploadData.desc || mdUploadRes.statusText}`);
+    }
+    const mdFileId = mdUploadData.data.fileId;
+    console.log(`[Client] Document uploaded, ID: ${mdFileId}`);
+    // ==========================================
+    // 5. 调用 /publish 接口，触发 Server 端发布
+    // ==========================================
+    console.log(`[Client] Requesting remote Server to publish ...`);
+    const publishRes = await fetch(`${serverUrl}/publish`, {
+        method: "POST",
+        headers: {
+            ...headers,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            fileId: mdFileId,
+            theme,
+            highlight,
+            customTheme,
+            macStyle,
+            footnote,
+        }),
+    });
+    if (publishRes.status === 401) {
+        throw new Error("鉴权失败 (401)：Server 拒绝访问，请检查传入的 --api-key 是否正确。");
+    }
+    const publishData = await publishRes.json();
+    if (!publishRes.ok || publishData.code === -1) {
+        throw new Error(`Remote Publish Failed: ${publishData.desc || publishRes.statusText}`);
+    }
+    return publishData.media_id;
+}
+function needUpload(url) {
+    // 需要上传的图片链接通常是相对路径，且不以 http/https、data:、asset:// 等协议开头
+    return !/^(https?:\/\/|data:|asset:\/\/)/i.test(url);
+}