@vdfor/confluence-sync 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @vdfor/confluence-sync
 
-Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。
+Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。支持 Mermaid 图表自动渲染为图片。
 
 ## 安装
 
@@ -20,12 +20,9 @@ yarn global add @vdfor/confluence-sync
 ### 方式1：环境变量
 
 ```bash
-# 必填：Confluence 服务地址
+# Confluence 服务地址
 export CONFLUENCE_BASE_URL="https://your-confluence-instance.com"
 
-# 必填：Space Key
-export CONFLUENCE_SPACE_KEY="YOUR_SPACE_KEY"
-
 # 认证方式（二选一）
 # 方式1（推荐）：Personal Access Token
 export CONFLUENCE_PAT="your-personal-access-token"
@@ -38,24 +35,23 @@ export CONFLUENCE_API_TOKEN="your-api-token"
 ### 方式2：CLI 参数（优先于环境变量）
 
 ```bash
-confluence-sync upload --file test.md \
+confluence-sync upload --file test.md --parent 123456 \
   --base-url https://your-confluence-instance.com \
-  --space-key YOUR_SPACE_KEY \
   --pat your-token
 ```
 
 ## 命令
 
-### upload - 上传 Markdown 为新页面
+### upload - 上传 Markdown 为新页面（已存在同名页面则自动更新）
 
 ```bash
-confluence-sync upload --file <path> [--title <标题>] [--space <key>] [--parent <ID或标题>] [--dry-run]
+confluence-sync upload --file <path> --parent <页面ID> [--title <标题>] [--dry-run] [--no-mermaid-to-img]
 ```
 
 ### update - 更新已有页面
 
 ```bash
-confluence-sync update --file <path> (--page-id <ID> | --title <标题>) [--space <key>] [--minor-edit]
+confluence-sync update --file <path> --page-id <ID> [--minor-edit] [--no-mermaid-to-img]
 ```
 
 ### upload-file - 上传附件
@@ -64,10 +60,10 @@ confluence-sync update --file <path> (--page-id <ID> | --title <标题>) [--spac
 confluence-sync upload-file --page-id <ID> --file <path> [--name <文件名>]
 ```
 
-### list-pages - 列出空间页面
+### list-pages - 列出 parent 下的子页面
 
 ```bash
-confluence-sync list-pages [--space <key>]
+confluence-sync list-pages --parent <页面ID>
 ```
 
 ### list-files - 列出页面附件
@@ -84,29 +80,44 @@ confluence-sync get-content --page-id <ID> [--markdown]
 
 使用 `--markdown` 参数可将 Confluence 内容转换为 Markdown 格式输出。
 
+## Mermaid 图表支持
+
+Markdown 中的 ```` ```mermaid ```` 代码块会自动通过 [sebastianjs](https://github.com/creadri/sebastianjs) 渲染为 PNG 图片（本地离线渲染，无需外网、无需浏览器），上传后页面中显示为图片附件。
+
+- 默认自动检测并转换，无 Mermaid 块时不影响正常流程
+- Mermaid 渲染失败时保留原始代码块（降级处理，不阻塞上传）
+- 使用 `--no-mermaid-to-img` 可禁用自动渲染
+
+```bash
+# 自动处理 mermaid（默认开启）
+confluence-sync upload --file README.md --parent 27263539
+
+# 禁用 mermaid 渲染
+confluence-sync upload --file README.md --parent 27263539 --no-mermaid-to-img
+```
+
 ## 配置参数
 
 | 参数 | 说明 |
 |------|------|
-| `--base-url` | Confluence 服务地址 |
-| `--space-key` | Space Key |
-| `--pat` | Personal Access Token |
-| `--username` | Confluence 登录名 |
-| `--api-token` | API Token 或密码 |
-| `--space` | Space Key（覆盖默认值） |
+| `--base-url` | Confluence 服务地址（覆盖环境变量） |
+| `--pat` | Personal Access Token（覆盖环境变量） |
+| `--username` | Confluence 登录名（覆盖环境变量） |
+| `--api-token` | API Token 或密码（覆盖环境变量） |
 | `--file` | 本地文件路径 |
-| `--title` | 页面标题 |
-| `--page-id` | 页面 ID |
-| `--parent` | 父页面 ID 或标题 |
+| `--title` | 页面标题（upload 时可选，默认取文件名） |
+| `--parent` | 父页面 ID（数字，upload / list-pages 必填） |
+| `--page-id` | 页面 ID（update / upload-file / list-files / get-content 必填） |
 | `--dry-run` | 仅打印转换结果，不实际上传 |
 | `--minor-edit` | 标记为小修改（不通知关注者） |
 | `--markdown` | get-content 时输出为 Markdown 格式 |
+| `--no-mermaid-to-img` | 禁用 Mermaid 图表自动渲染 |
 
 ## 示例
 
 ```bash
-# 上传 Markdown 文件
-confluence-sync upload --file README.md --title "项目文档" --space MYSPACE
+# 上传 Markdown 文件（自动按 title 匹配 parent 下已有页面则更新）
+confluence-sync upload --file README.md --title "项目文档" --parent 27263539
 
 # 更新已有页面
 confluence-sync update --file README.md --page-id 123456
@@ -114,8 +125,8 @@ confluence-sync update --file README.md --page-id 123456
 # 上传附件
 confluence-sync upload-file --page-id 123456 --file image.png
 
-# 列出空间所有页面
-confluence-sync list-pages --space MYSPACE
+# 列出 parent 下的子页面
+confluence-sync list-pages --parent 27263539
 
 # 获取页面内容
 confluence-sync get-content --page-id 123456
@@ -139,7 +150,8 @@ pnpm add -g @vdfor/confluence-sync
 安装后，智能体可直接调用 `confluence-sync` 命令：
 
 ```bash
-confluence-sync upload --file README.md --title "项目文档" --space MYSPACE
+confluence-sync upload --file README.md --title "项目文档" --parent 27263539
+confluence-sync update --file README.md --page-id 123456
 confluence-sync get-content --page-id 123456 --markdown
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vdfor/confluence-sync",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "author": "vdfor",
   "license": "MIT",
   "private": false,
@@ -29,7 +29,8 @@
   "dependencies": {
     "axios": "^1.7.0",
     "form-data": "^4.0.0",
-    "marked": "^15.0.0"
+    "marked": "^15.0.0",
+    "sebastianjs": "^0.4.0"
   },
   "devDependencies": {
     "rimraf": "^6.1.3"

package/skills/confluence-sync.md

@@ -1,48 +1,43 @@
 ---
 name: "confluence-sync"
-description: "Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。当用户需要上传、更新、获取 Confluence 页面内容或管理附件时调用。"
+description: "Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式，支持 Mermaid 图表自动渲染。当用户需要上传、更新、获取 Confluence 页面内容或管理附件时调用。"
 ---
 
 # Confluence Sync
 
-Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。
+Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。支持 Mermaid 图表自动渲染为图片。
 
 ## 功能特性
 
-- 上传 Markdown 文件为 Confluence 页面
+- 上传 Markdown 文件为 Confluence 页面（已存在同名页面则自动更新）
 - 更新已有页面内容
 - 上传文件作为页面附件
-- 列出空间页面和页面附件
+- 列出 parent 下的子页面
+- 列出页面附件
 - 获取页面内容（支持转换为 Markdown 格式）
+- Mermaid 图表自动渲染为 PNG 图片
 
 ## 配置要求
 
 使用前需要配置以下环境变量或 CLI 参数：
 
-### 必填配置
-
 - `CONFLUENCE_BASE_URL`: Confluence 服务地址
-- `CONFLUENCE_SPACE_KEY`: Space Key
 - 认证方式（二选一）：
   - `CONFLUENCE_PAT`: Personal Access Token（推荐）
   - `CONFLUENCE_USERNAME` + `CONFLUENCE_API_TOKEN`: Basic Auth 认证
 
-### 可选配置
-
-- `--space`: Space Key（覆盖默认值）
-
 ## 命令列表
 
-### upload - 上传 Markdown 为新页面
+### upload - 上传 Markdown 为新页面（已存在同名页面则自动更新）
 
 ```bash
-confluence-sync upload --file <path> [--title <标题>] [--space <key>] [--parent <ID或标题>] [--dry-run]
+confluence-sync upload --file <path> --parent <页面ID> [--title <标题>] [--dry-run] [--no-mermaid-to-img]
 ```
 
 ### update - 更新已有页面
 
 ```bash
-confluence-sync update --file <path> (--page-id <ID> | --title <标题>) [--space <key>] [--minor-edit]
+confluence-sync update --file <path> --page-id <ID> [--minor-edit] [--no-mermaid-to-img]
 ```
 
 ### upload-file - 上传附件
@@ -51,10 +46,10 @@ confluence-sync update --file <path> (--page-id <ID> | --title <标题>) [--spac
 confluence-sync upload-file --page-id <ID> --file <path> [--name <文件名>]
 ```
 
-### list-pages - 列出空间页面
+### list-pages - 列出 parent 下的子页面
 
 ```bash
-confluence-sync list-pages [--space <key>]
+confluence-sync list-pages --parent <页面ID>
 ```
 
 ### list-files - 列出页面附件
@@ -71,25 +66,26 @@ confluence-sync get-content --page-id <ID> [--markdown]
 
 使用 `--markdown` 参数可将 Confluence 内容转换为 Markdown 格式输出。
 
+## Mermaid 支持
+
+Markdown 中的 ```` ```mermaid ```` 代码块自动通过 sebastianjs 渲染为 PNG 图片（本地离线渲染，无需外网、无需浏览器），作为附件上传。默认开启，使用 `--no-mermaid-to-img` 可禁用。渲染失败时保留原始代码块，不阻塞上传。
+
 ## 使用示例
 
 ```bash
-# 上传 Markdown 文件
-confluence-sync upload --file README.md --title "项目文档" --space MYSPACE
+# 上传（--parent 必填，已存在同名子页面则自动更新）
+confluence-sync upload --file README.md --title "项目文档" --parent 27263539
 
-# 更新已有页面
+# 更新（--page-id 必填）
 confluence-sync update --file README.md --page-id 123456
 
+# 列出 parent 下的子页面
+confluence-sync list-pages --parent 27263539
+
 # 上传附件
 confluence-sync upload-file --page-id 123456 --file image.png
 
-# 列出空间所有页面
-confluence-sync list-pages --space MYSPACE
-
 # 获取页面内容
-confluence-sync get-content --page-id 123456
-
-# 获取页面内容并转换为 Markdown
 confluence-sync get-content --page-id 123456 --markdown
 ```
 

package/src/confluence.mjs

@@ -1,10 +1,113 @@
 import axios from 'axios';
 import { marked } from 'marked';
-import { extname } from 'node:path';
+import { extname, dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { writeFile, unlink } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+// ── Mermaid 处理 ─────────────────────────────────────────────────────────────
+
+let sebastianRenderer = null;
+let cjkFontRegistry = null;
+
+/** 项目内置 CJK 字体（思源黑体可变） */
+const PROJECT_FONT_DIR = join(dirname(fileURLToPath(import.meta.url)), 'fonts');
+const CJK_FONT_FILE = join(PROJECT_FONT_DIR, 'SourceHanSansSC-VF.ttf');
+
+async function getSebastianRenderer() {
+  if (!sebastianRenderer) {
+    const sebastian = await import('sebastianjs');
+    sebastianRenderer = { renderPng: sebastian.renderPng, dispose: sebastian.dispose };
+  }
+  return sebastianRenderer;
+}
+
+/**
+ * 创建注册了项目内置 CJK 字体的 FontRegistry
+ * mermaid 节点标题默认用 bold，所以需要同时覆盖 regular + bold + italic
+ */
+async function getCjkFontRegistry() {
+  if (cjkFontRegistry) return cjkFontRegistry;
+
+  const { FontRegistry } = await import('sebastianjs/src/geometry/fonts.js');
+  const registry = new FontRegistry();
+
+  // 注册思源黑体 SC 可变字体，覆盖所有字重（variable font 可以自己插值不同 weight）
+  // 家族名用常见别名，CSS font-family 匹配时能命中
+  registry.registerFont(CJK_FONT_FILE, { family: 'Source Han Sans SC', weight: 400 });
+  registry.registerFont(CJK_FONT_FILE, { family: 'Source Han Sans SC', weight: 700 });
+  registry.registerFont(CJK_FONT_FILE, { family: 'Source Han Sans SC', weight: 400, italic: true });
+  registry.registerFont(CJK_FONT_FILE, { family: 'Source Han Sans SC', weight: 700, italic: true });
+
+  // 也注册成 generic 别名（mermaid 默认字体栈里有 sans-serif）
+  registry.registerFont(CJK_FONT_FILE, { family: 'sans-serif', weight: 400 });
+  registry.registerFont(CJK_FONT_FILE, { family: 'sans-serif', weight: 700 });
+
+  registry.setDefaultFamily('Source Han Sans SC');
+  cjkFontRegistry = registry;
+  return registry;
+}
+
+/**
+ * 检测并替换 markdown 中的 ```mermaid 代码块为图片占位符
+ * 使用 sebastianjs（本地、零浏览器、零外网依赖）渲染为 PNG
+ *
+ * @param {string} md - 原始 markdown
+ * @returns {{ md: string, images: { file: string, name: string }[], hasMermaid: boolean }}
+ */
+export async function preprocessMermaid(md) {
+  const mermaidRe = /```mermaid\s*\n([\s\S]*?)```/gi;
+  const matches = [...md.matchAll(mermaidRe)];
+  if (!matches.length) return { md, images: [], hasMermaid: false };
+
+  const { renderPng } = await getSebastianRenderer();
+  const fontRegistry = await getCjkFontRegistry();
+  const images = [];
+  let result = md;
+  let offset = 0;
+
+  for (let i = 0; i < matches.length; i++) {
+    const block = matches[i];
+    const code = block[1];
+    const name = `mermaid-${i + 1}.png`;
+    const file = `${tmpdir()}/${name}`;
+
+    try {
+      const t0 = Date.now();
+      const { data: pngBuffer } = await renderPng(code, {
+        background: 'white',
+        fontFamily: 'Source Han Sans SC',
+        fontRegistry,
+      });
+      const t1 = Date.now();
+      await writeFile(file, pngBuffer);
+      images.push({ file, name });
+
+      const replacement = `![${name}](${name})`;
+      const start = block.index + offset;
+      const end = start + block[0].length;
+      result = result.slice(0, start) + replacement + result.slice(end);
+      offset += replacement.length - block[0].length;
+      console.log(`  📐 Mermaid 图表 ${i + 1} 渲染完成 → ${name} (${pngBuffer.length}B, ${t1 - t0}ms)`);
+    } catch (err) {
+      console.warn(`  ⚠️  Mermaid 图表 ${i + 1} 渲染失败：${err.message}，保留原始代码块`);
+    }
+  }
+
+  return { md: result, images, hasMermaid: images.length > 0 };
+}
+
+/**
+ * 清理临时图片文件
+ */
+async function cleanupMermaidImages(images) {
+  for (const img of images) {
+    try { await unlink(img.file); } catch {}
+  }
+}
 
 // ── 配置 ──────────────────────────────────────────────────────────────────────
 let baseUrl = process.env.CONFLUENCE_BASE_URL;
-let spaceKey = process.env.CONFLUENCE_SPACE_KEY;
 let pat = process.env.CONFLUENCE_PAT;
 let username = process.env.CONFLUENCE_USERNAME;
 let apiToken = process.env.CONFLUENCE_API_TOKEN;
@@ -14,14 +117,12 @@ let api;
  * 用 CLI 参数覆盖环境变量配置，需在其他函数调用前执行
  * @param {object} [opts]
  * @param {string} [opts.baseUrl]
- * @param {string} [opts.spaceKey]
  * @param {string} [opts.pat]
  * @param {string} [opts.username]
  * @param {string} [opts.apiToken]
  */
 export function configure(opts = {}) {
   if (opts.baseUrl) baseUrl = opts.baseUrl;
-  if (opts.spaceKey) spaceKey = opts.spaceKey;
   if (opts.pat) pat = opts.pat;
   if (opts.username) username = opts.username;
   if (opts.apiToken) apiToken = opts.apiToken;
@@ -61,44 +162,23 @@ function logAxiosError(err) {
 // ── 页面查询 ──────────────────────────────────────────────────────────────────
 
 /**
- * 按 ID 获取页面元信息（含版本号）
+ * 按 ID 获取页面元信息（含版本号、space）
  */
 export async function getPageById(id) {
   ensureApi();
   const { data } = await api.get(`/content/${id}`, {
-    params: { expand: 'version,ancestors' },
+    params: { expand: 'version,ancestors,space' },
   });
   return data;
 }
 
 /**
- * 按 spaceKey + title 获取页面（仅返回第一个匹配）
+ * 列出指定 parent 下的子页面
  */
-export async function getPageByTitle(spaceKey, title) {
+export async function listChildPages(parentId, limit = 50) {
   ensureApi();
-  const { data } = await api.get('/content', {
-    params: {
-      spaceKey,
-      title,
-      expand: 'version',
-      limit: 1,
-    },
-  });
-  return data.results?.[0] || null;
-}
-
-/**
- * 列出 space 下所有页面（分页）
- */
-export async function listPages(spaceKey, limit = 25) {
-  ensureApi();
-  const { data } = await api.get('/content', {
-    params: {
-      spaceKey,
-      type: 'page',
-      expand: 'version',
-      limit,
-    },
+  const { data } = await api.get(`/content/${parentId}/child/page`, {
+    params: { limit, expand: 'version' },
   });
   return data.results;
 }
@@ -117,19 +197,16 @@ export async function getPageContent(id) {
 // ── 页面创建 / 更新 ───────────────────────────────────────────────────────────
 
 /**
- * 创建新页面
+ * 创建新页面（有 parentId 即可，Confluence 自动推断 space）
  */
-export async function createPage(spaceKey, title, bodyHtml, parentId) {
+export async function createPage(parentId, title, bodyHtml) {
   ensureApi();
   const payload = {
     type: 'page',
     title,
-    space: { key: spaceKey },
     body: { storage: { value: bodyHtml, representation: 'storage' } },
+    ancestors: parentId ? [{ id: parentId }] : undefined,
   };
-  if (parentId) {
-    payload.ancestors = [{ id: parentId }];
-  }
   try {
     const { data } = await api.post('/content', payload);
     return data;
@@ -162,6 +239,16 @@ export async function updatePage(id, title, bodyHtml, currentVersion, minorEdit
   }
 }
 
+// ── HTML 转义 ────────────────────────────────────────────────────────────────
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
 // ── Markdown → Confluence Storage Format ───────────────────────────────────────
 
 /**
@@ -222,7 +309,7 @@ export function mdToConfluence(md) {
           break;
         default:
           if (tok.tokens) out += renderTokens(tok.tokens, listDepth);
-          else if (tok.text) out += tok.text;
+          else if (tok.text) out += escapeHtml(tok.text);
       }
     }
     return out;
@@ -234,7 +321,7 @@ export function mdToConfluence(md) {
     for (const tok of toks) {
       switch (tok.type) {
         case 'text':
-          out += tok.tokens ? renderInline(tok.tokens) : tok.text;
+          out += tok.tokens ? renderInline(tok.tokens) : escapeHtml(tok.text);
           break;
         case 'strong':
           out += `<strong>${renderInline(tok.tokens)}</strong>`;
@@ -243,16 +330,16 @@ export function mdToConfluence(md) {
           out += `<em>${renderInline(tok.tokens)}</em>`;
           break;
         case 'codespan':
-          out += `<code>${tok.text}</code>`;
+          out += `<code>${escapeHtml(tok.text)}</code>`;
           break;
         case 'del':
           out += `<s>${renderInline(tok.tokens)}</s>`;
           break;
         case 'link':
-          out += `<a href="${tok.href}">${renderInline(tok.tokens)}</a>`;
+          out += `<a href="${escapeHtml(tok.href)}">${renderInline(tok.tokens)}</a>`;
           break;
         case 'image':
-          out += `<ac:image><ri:attachment ri:filename="${tok.href}" /></ac:image>`;
+          out += `<ac:image><ri:attachment ri:filename="${escapeHtml(tok.href)}" /></ac:image>`;
           break;
         case 'br':
           out += '<br/>';
@@ -260,6 +347,11 @@ export function mdToConfluence(md) {
         case 'escape':
           out += tok.text;
           break;
+        case 'html':
+          // marked 识别的 inline HTML（如 <div>foo</div>、<即实际未使用>）
+          // 我们不支持用户写原生 HTML → 一律转义
+          out += escapeHtml(tok.text);
+          break;
         default:
           out += tok.text || '';
       }
@@ -448,97 +540,122 @@ export async function listAttachments(pageId) {
 
 // ── 高级业务流程 ──────────────────────────────────────────────────────────────
 
-/**
- * 查找父页面 ID（支持按 title 或直接 ID）
- */
-async function resolveParentId(parentIdentifier, spaceKey) {
-  if (!parentIdentifier) return null;
-  // 如果是纯数字，当作 ID
-  if (/^\d+$/.test(parentIdentifier)) {
-    const page = await getPageById(parentIdentifier);
-    console.log(`  父页面：${page.title} (ID: ${page.id})`);
-    return page.id;
-  }
-  // 否则按 title 查找
-  const page = await getPageByTitle(spaceKey, parentIdentifier);
-  if (!page) {
-    throw new Error(`未找到父页面「${parentIdentifier}」（space: ${spaceKey}）`);
-  }
-  console.log(`  父页面：${page.title} (ID: ${page.id})`);
-  return page.id;
-}
-
 /**
  * 上传 Markdown 文件到 Confluence
  * @param {object} opts
  * @param {string} opts.filePath - 本地 .md 文件路径
  * @param {string} [opts.title] - 页面标题（默认取文件名）
- * @param {string} [opts.spaceKey] - space key
- * @param {string} [opts.parentId] - 父页面 ID 或标题
+ * @param {string} opts.parentId - 父页面 ID（数字）
  * @param {boolean} [opts.dryRun] - 仅打印转换结果
  */
 export async function uploadMarkdown(opts) {
-  const { filePath, title: optTitle, spaceKey: spaceKeyOpt, parentId: parentRaw, dryRun = false } = opts;
-  const effectiveSpaceKey = spaceKeyOpt || spaceKey;
+  const { filePath, title: optTitle, parentId: parentRaw, dryRun = false, mermaid = true } = opts;
   const fs = await import('node:fs');
   const path = await import('node:path');
 
-  const md = fs.readFileSync(filePath, 'utf-8');
+  let md = fs.readFileSync(filePath, 'utf-8');
   const title = optTitle || path.basename(filePath, extname(filePath));
+
+  // 必须有 parentId
+  if (!parentRaw || !/^\d+$/.test(parentRaw)) {
+    throw new Error('upload 需要 --parent <数字页面ID> 作为父页面');
+  }
+
+  const parentPage = await getPageById(parentRaw);
+  console.log(`  父页面：${parentPage.title} (ID: ${parentPage.id}, Space: ${parentPage.space?.key})`);
+
+  // Mermaid 预处理
+  let mermaidImages = [];
+  if (mermaid) {
+    const result = await preprocessMermaid(md);
+    md = result.md;
+    mermaidImages = result.images;
+  }
+
   const bodyHtml = mdToConfluence(md);
 
   if (dryRun) {
     console.log('── 转换结果（dry-run）────────────────────────');
     console.log(`  标题: ${title}`);
-    console.log(`  Space: ${effectiveSpaceKey}`);
+    console.log(`  父页面: ${parentPage.title} (ID: ${parentPage.id})`);
+    if (mermaidImages.length) console.log(`  Mermaid 图片: ${mermaidImages.length} 张`);
     console.log('  Body:\n' + bodyHtml);
     return null;
   }
 
-  // 查找父页面
-  const parentId = await resolveParentId(parentRaw, effectiveSpaceKey);
+  try {
+    // 检查 parent 下是否已有同名子页面
+    const children = await listChildPages(parentPage.id, 500);
+    const existing = children.find(c => c.title === title);
+
+    let page;
+    if (existing) {
+      console.log(`  父页面下已存在同名页面「${title}」(ID: ${existing.id})，将更新…`);
+      page = await updatePage(existing.id, title, bodyHtml, existing.version.number);
+    } else {
+      page = await createPage(parentPage.id, title, bodyHtml);
+    }
 
-  // 检查是否已存在同名页面
-  const existing = await getPageByTitle(effectiveSpaceKey, title);
-  if (existing) {
-    console.log(`  页面「${title}」已存在 (ID: ${existing.id})，将更新…`);
-    const updated = await updatePage(existing.id, title, bodyHtml, existing.version.number);
-    console.log(`  ✅ 更新完成 → ${baseUrl}/pages/viewpage.action?pageId=${updated.id}`);
-    return updated;
-  }
+    // 上传 mermaid 图片作为附件
+    if (mermaidImages.length) {
+      console.log('  📎 上传 Mermaid 图片附件…');
+      for (const img of mermaidImages) {
+        await uploadAttachment(page.id, img.file, img.name);
+        console.log(`    ✅ ${img.name}`);
+      }
+    }
 
-  const page = await createPage(effectiveSpaceKey, title, bodyHtml, parentId);
-  console.log(`  ✅ 创建完成 → ${baseUrl}/pages/viewpage.action?pageId=${page.id}`);
-  return page;
+    console.log(`  ✅ ${existing ? '更新' : '创建'}完成 → ${baseUrl}/pages/viewpage.action?pageId=${page.id}`);
+    return page;
+  } finally {
+    await cleanupMermaidImages(mermaidImages);
+  }
 }
 
 /**
- * 更新指定页面（通过 ID 或 space+title 查找）
+ * 更新指定页面（通过 page-id 定位）
  */
 export async function updateMarkdown(opts) {
-  const { pageId, title: searchTitle, filePath, spaceKey: spaceKeyOpt, minorEdit = false } = opts;
-  const effectiveSpaceKey = spaceKeyOpt || spaceKey;
+  const { pageId, filePath, minorEdit = false, mermaid = true } = opts;
   const fs = await import('node:fs');
 
-  const md = fs.readFileSync(filePath, 'utf-8');
-  const bodyHtml = mdToConfluence(md);
+  if (!pageId || !/^\d+$/.test(pageId)) {
+    throw new Error('update 需要 --page-id <数字页面ID>');
+  }
+
+  let md = fs.readFileSync(filePath, 'utf-8');
 
-  let page;
-  if (pageId) {
-    page = await getPageById(pageId);
-  } else if (searchTitle) {
-    page = await getPageByTitle(effectiveSpaceKey, searchTitle);
-    if (!page) throw new Error(`未找到页面「${searchTitle}」（space: ${effectiveSpaceKey}）`);
-  } else {
-    throw new Error('必须指定 --page-id 或 --title 来定位目标页面');
+  // Mermaid 预处理
+  let mermaidImages = [];
+  if (mermaid) {
+    const result = await preprocessMermaid(md);
+    md = result.md;
+    mermaidImages = result.images;
   }
 
-  console.log(`  目标页面：${page.title} (ID: ${page.id}, 当前版本: ${page.version.number})`);
-  const updated = await updatePage(page.id, page.title, bodyHtml, page.version.number, minorEdit);
-  console.log(`  ✅ 更新完成 → ${baseUrl}/pages/viewpage.action?pageId=${updated.id}`);
-  return updated;
+  const bodyHtml = mdToConfluence(md);
+
+  const page = await getPageById(pageId);
+
+  try {
+    console.log(`  目标页面：${page.title} (ID: ${page.id}, Space: ${page.space?.key}, 当前版本: ${page.version.number})`);
+    const updated = await updatePage(page.id, page.title, bodyHtml, page.version.number, minorEdit);
+
+    // 上传 mermaid 图片作为附件
+    if (mermaidImages.length) {
+      console.log('  📎 上传 Mermaid 图片附件…');
+      for (const img of mermaidImages) {
+        await uploadAttachment(page.id, img.file, img.name);
+        console.log(`    ✅ ${img.name}`);
+      }
+    }
+
+    console.log(`  ✅ 更新完成 → ${baseUrl}/pages/viewpage.action?pageId=${updated.id}`);
+    return updated;
+  } finally {
+    await cleanupMermaidImages(mermaidImages);
+  }
 }
 
 // ── 导出配置 ──────────────────────────────────────────────────────────────────
 export function getBaseUrl() { return baseUrl; }
-export function getSpaceKey() { return spaceKey; }

package/upload.mjs

@@ -2,40 +2,37 @@
 /**
  * Confluence 文档同步 CLI
  *
- * 环境变量（或通过 CLI 参数配置）：
- *   必填：             CONFLUENCE_BASE_URL   - Confluence 服务地址
- *                      CONFLUENCE_SPACE_KEY  - Space Key
- * 认证方式（二选一）：
- *   方式1 PAT：        CONFLUENCE_PAT       - Personal Access Token
- * 方式2 Basic Auth： CONFLUENCE_USERNAME   - Confluence 登录名（工号）
- *                      CONFLUENCE_API_TOKEN  - API Token 或密码
+ * 环境变量：
+ *   CONFLUENCE_BASE_URL           - Confluence 服务地址
+ *   认证方式（二选一）：
+ *     方式1 PAT： CONFLUENCE_PAT  - Personal Access Token
+ *     方式2 Auth： CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN
  *
  * 用法：
- *   confluence-sync upload   --file <path> [--title <标题>] [--space <key>] [--parent <ID或标题>] [--dry-run]
- *   confluence-sync update   --file <path> (--page-id <ID> | --title <标题>) [--space <key>] [--minor-edit]
+ *   confluence-sync upload      --file <path> --parent <页面ID> [--title <标题>] [--dry-run] [--no-mermaid-to-img]
+ *   confluence-sync update      --file <path> --page-id <ID> [--minor-edit] [--no-mermaid-to-img]
  *   confluence-sync upload-file --page-id <ID> --file <path> [--name <文件名>]
- *   confluence-sync list-pages [--space <key>]
- *   confluence-sync list-files --page-id <ID>
+ *   confluence-sync list-pages  --parent <页面ID>
+ *   confluence-sync list-files  --page-id <ID>
  *   confluence-sync get-content --page-id <ID> [--markdown]
  *
  * 可选配置参数（优先于环境变量）：
- *   --base-url        Confluence 服务地址
- *   --space-key       Space Key
- *   --pat             Personal Access Token
- *   --username        Confluence 登录名
- *   --api-token       API Token 或密码
+ *   --base-url    Confluence 服务地址
+ *   --pat         Personal Access Token
+ *   --username    Confluence 登录名
+ *   --api-token   API Token 或密码
  */
 
 import {
   uploadMarkdown,
   updateMarkdown,
   uploadAttachment,
-  listPages,
+  listChildPages,
   listAttachments,
+  getPageById,
   getPageContent,
   confluenceToMd,
   getBaseUrl,
-  getSpaceKey,
   configure,
 } from './src/confluence.mjs';
 
@@ -73,23 +70,22 @@ Confluence 文档同步工具
   upload        上传 Markdown 文件为新页面（已存在则更新）
   update        更新已有页面内容
   upload-file   上传文件作为页面附件
-  list-pages    列出 space 下所有页面
+  list-pages    列出 parent 页面下的子页面
   list-files    列出页面的所有附件
   get-content   获取页面的 HTML 内容
 
 upload 选项:
   --file        本地 .md 文件路径（必填）
+  --parent      父页面 ID（数字，必填）
   --title       页面标题（默认取文件名）
-  --space       Space Key（默认读 config.json）
-  --parent      父页面 ID 或标题
   --dry-run     仅打印转换结果，不实际上传
+  --no-mermaid-to-img  禁用 Mermaid 图表自动渲染
 
 update 选项:
   --file        本地 .md 文件路径（必填）
-  --page-id     目标页面 ID
-  --title       按标题查找目标页面（与 --page-id 二选一）
-  --space       Space Key（默认读 config.json）
+  --page-id     目标页面 ID（数字，必填）
   --minor-edit  标记为小修改（不通知关注者）
+  --no-mermaid-to-img  禁用 Mermaid 图表自动渲染
 
 upload-file 选项:
   --page-id     目标页面 ID（必填）
@@ -97,34 +93,26 @@ upload-file 选项:
   --name        覆盖文件名
 
 list-pages 选项:
-  --space       Space Key（默认读 config.json）
+  --parent      父页面 ID（数字，必填）
 
 list-files 选项:
   --page-id     页面 ID（必填）
 
 get-content 选项:
   --page-id     页面 ID（必填）
-  --markdown    输出为 Markdown 格式（默认输出 Storage HTML）
+  --markdown    输出为 Markdown 格式
 
 配置参数（优先于环境变量）:
-  --base-url        Confluence 服务地址
-  --space-key       Space Key
-  --pat             Personal Access Token
-  --username        Confluence 登录名
-  --api-token       API Token 或密码
+  --base-url    Confluence 服务地址
+  --pat         Personal Access Token
+  --username    Confluence 登录名
+  --api-token   API Token 或密码
 
 环境变量:
-  必填:
-    CONFLUENCE_BASE_URL   Confluence 服务地址
-    CONFLUENCE_SPACE_KEY  Space Key
-
+  CONFLUENCE_BASE_URL   Confluence 服务地址
   认证方式（二选一）:
-    方式1 - Personal Access Token:
-      CONFLUENCE_PAT        个人访问令牌
-
-    方式2 - Basic Auth:
-      CONFLUENCE_USERNAME   Confluence 登录名（工号）
-      CONFLUENCE_API_TOKEN  API Token 或密码
+    CONFLUENCE_PAT              Personal Access Token
+    CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN  Basic Auth
 
 `);
 }
@@ -143,13 +131,11 @@ async function main() {
   // 用 CLI 参数覆盖环境变量配置
   configure({
     baseUrl: args['base-url'],
-    spaceKey: args['space-key'],
     pat: args['pat'],
     username: args['username'],
     apiToken: args['api-token'],
   });
   const baseUrl = getBaseUrl();
-  const spaceKey = getSpaceKey();
 
   try {
     switch (command) {
@@ -161,9 +147,9 @@ async function main() {
         const result = await uploadMarkdown({
           filePath: args.file,
           title: args.title,
-          spaceKey: args.space || spaceKey,
           parentId: args.parent,
           dryRun: args['dry-run'] === true,
+          mermaid: args['no-mermaid-to-img'] !== true,
         });
         if (result) {
           console.log('\n页面信息：');
@@ -180,16 +166,15 @@ async function main() {
           console.error('错误：--file 必填');
           process.exit(1);
         }
-        if (!args['page-id'] && !args.title) {
-          console.error('错误：必须指定 --page-id 或 --title');
+        if (!args['page-id']) {
+          console.error('错误：--page-id 必填');
           process.exit(1);
         }
         const result = await updateMarkdown({
           pageId: args['page-id'],
-          title: args.title,
           filePath: args.file,
-          spaceKey: args.space || spaceKey,
           minorEdit: args['minor-edit'] === true,
+          mermaid: args['no-mermaid-to-img'] !== true,
         });
         console.log('\n页面信息：');
         console.log(`  ID:      ${result.id}`);
@@ -216,18 +201,22 @@ async function main() {
       }
 
       case 'list-pages': {
-        const space = args.space || spaceKey;
-        console.log(`Space: ${space}\n`);
-        const pages = await listPages(space);
+        if (!args.parent || !/^\d+$/.test(args.parent)) {
+          console.error('错误：--parent <数字页面ID> 必填');
+          process.exit(1);
+        }
+        const parentPage = await getPageById(args.parent);
+        console.log(`父页面：${parentPage.title} (ID: ${parentPage.id}, Space: ${parentPage.space?.key})\n`);
+        const pages = await listChildPages(parentPage.id);
         if (!pages.length) {
-          console.log('  （无页面）');
+          console.log('  （无子页面）');
         } else {
           const maxId = Math.max(...pages.map(p => String(p.id).length));
           for (const p of pages) {
             const id = String(p.id).padEnd(maxId);
             console.log(`  ${id}  v${p.version?.number ?? '?'}  ${p.title}`);
           }
-          console.log(`\n共 ${pages.length} 个页面`);
+          console.log(`\n共 ${pages.length} 个子页面`);
         }
         break;
       }