@vdfor/confluence-sync 0.1.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @vdfor/confluence-sync
 
-Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。
+Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。支持 Mermaid 图表自动渲染为图片。
 
 ## 安装
 
@@ -20,7 +20,7 @@ yarn global add @vdfor/confluence-sync
 ### 方式1：环境变量
 
 ```bash
-# 必填：Confluence 服务地址
+# Confluence 服务地址
 export CONFLUENCE_BASE_URL="https://your-confluence-instance.com"
 
 # 认证方式（二选一）
@@ -35,23 +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 \
   --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 - 上传附件
@@ -60,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 - 列出页面附件
@@ -80,28 +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 服务地址 |
-| `--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
@@ -109,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
@@ -119,6 +135,26 @@ confluence-sync get-content --page-id 123456
 confluence-sync get-content --page-id 123456 --markdown
 ```
 
+## Skill 集成
+
+本项目包含 Trae Skill，安装后可被智能体调用。
+
+### 安装
+
+```bash
+pnpm add -g @vdfor/confluence-sync
+```
+
+### 使用
+
+安装后，智能体可直接调用 `confluence-sync` 命令：
+
+```bash
+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
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vdfor/confluence-sync",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "author": "vdfor",
   "license": "MIT",
   "private": false,
@@ -20,7 +20,8 @@
   },
   "files": [
     "upload.mjs",
-    "src/"
+    "src/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18"
@@ -28,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

@@ -0,0 +1,97 @@
+---
+name: "confluence-sync"
+description: "Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式，支持 Mermaid 图表自动渲染。当用户需要上传、更新、获取 Confluence 页面内容或管理附件时调用。"
+---
+
+# Confluence Sync
+
+Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。支持 Mermaid 图表自动渲染为图片。
+
+## 功能特性
+
+- 上传 Markdown 文件为 Confluence 页面（已存在同名页面则自动更新）
+- 更新已有页面内容
+- 上传文件作为页面附件
+- 列出 parent 下的子页面
+- 列出页面附件
+- 获取页面内容（支持转换为 Markdown 格式）
+- Mermaid 图表自动渲染为 PNG 图片
+
+## 配置要求
+
+使用前需要配置以下环境变量或 CLI 参数：
+
+- `CONFLUENCE_BASE_URL`: Confluence 服务地址
+- 认证方式（二选一）：
+  - `CONFLUENCE_PAT`: Personal Access Token（推荐）
+  - `CONFLUENCE_USERNAME` + `CONFLUENCE_API_TOKEN`: Basic Auth 认证
+
+## 命令列表
+
+### upload - 上传 Markdown 为新页面（已存在同名页面则自动更新）
+
+```bash
+confluence-sync upload --file <path> --parent <页面ID> [--title <标题>] [--dry-run] [--no-mermaid-to-img]
+```
+
+### update - 更新已有页面
+
+```bash
+confluence-sync update --file <path> --page-id <ID> [--minor-edit] [--no-mermaid-to-img]
+```
+
+### upload-file - 上传附件
+
+```bash
+confluence-sync upload-file --page-id <ID> --file <path> [--name <文件名>]
+```
+
+### list-pages - 列出 parent 下的子页面
+
+```bash
+confluence-sync list-pages --parent <页面ID>
+```
+
+### list-files - 列出页面附件
+
+```bash
+confluence-sync list-files --page-id <ID>
+```
+
+### get-content - 获取页面内容
+
+```bash
+confluence-sync get-content --page-id <ID> [--markdown]
+```
+
+使用 `--markdown` 参数可将 Confluence 内容转换为 Markdown 格式输出。
+
+## Mermaid 支持
+
+Markdown 中的 ```` ```mermaid ```` 代码块自动通过 sebastianjs 渲染为 PNG 图片（本地离线渲染，无需外网、无需浏览器），作为附件上传。默认开启，使用 `--no-mermaid-to-img` 可禁用。渲染失败时保留原始代码块，不阻塞上传。
+
+## 使用示例
+
+```bash
+# 上传（--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 get-content --page-id 123456 --markdown
+```
+
+## 注意事项
+
+1. 使用前请确保已正确配置认证信息
+2. Personal Access Token 需要在 Confluence 个人设置中生成
+3. 上传附件时，如果附件已存在会自动更新
+4. 使用 `--dry-run` 参数可以预览转换结果而不实际上传

package/src/confluence.mjs

@@ -1,12 +1,74 @@
 import axios from 'axios';
 import { marked } from 'marked';
-import { readFileSync } from 'node:fs';
 import { extname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { writeFile, unlink } from 'node:fs/promises';
 
-// ── 配置 ──────────────────────────────────────────────────────────────────────
-const config = JSON.parse(readFileSync(new URL('../config.json', import.meta.url), 'utf-8'));
-const { spaceKey: defaultSpaceKey } = config;
+// ── Mermaid 处理 ─────────────────────────────────────────────────────────────
+
+let sebastianRenderer = null;
+async function getSebastianRenderer() {
+  if (!sebastianRenderer) {
+    const sebastian = await import('sebastianjs');
+    sebastianRenderer = { renderPng: sebastian.renderPng, dispose: sebastian.dispose };
+  }
+  return sebastianRenderer;
+}
+
+/**
+ * 检测并替换 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 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' });
+      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 pat = process.env.CONFLUENCE_PAT;
 let username = process.env.CONFLUENCE_USERNAME;
@@ -62,44 +124,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;
 }
@@ -118,19 +159,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;
@@ -449,95 +487,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 = defaultSpaceKey, parentId: parentRaw, dryRun = false } = opts;
+  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: ${spaceKey}`);
+    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, spaceKey);
+  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(spaceKey, 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(spaceKey, 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 = defaultSpaceKey, minorEdit = false } = opts;
+  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(spaceKey, searchTitle);
-    if (!page) throw new Error(`未找到页面「${searchTitle}」（space: ${spaceKey}）`);
-  } 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 { defaultSpaceKey };
 export function getBaseUrl() { return baseUrl; }

package/upload.mjs

@@ -2,37 +2,36 @@
 /**
  * Confluence 文档同步 CLI
  *
- * 环境变量（或通过 CLI 参数配置）：
- *   必填：             CONFLUENCE_BASE_URL   - Confluence 服务地址
- * 认证方式（二选一）：
- *   方式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 服务地址
- *   --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,
-  defaultSpaceKey,
   getBaseUrl,
   configure,
 } from './src/confluence.mjs';
@@ -71,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（必填）
@@ -95,32 +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 服务地址
-  --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_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
 
 `);
 }
@@ -155,9 +147,9 @@ async function main() {
         const result = await uploadMarkdown({
           filePath: args.file,
           title: args.title,
-          spaceKey: args.space || defaultSpaceKey,
           parentId: args.parent,
           dryRun: args['dry-run'] === true,
+          mermaid: args['no-mermaid-to-img'] !== true,
         });
         if (result) {
           console.log('\n页面信息：');
@@ -174,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 || defaultSpaceKey,
           minorEdit: args['minor-edit'] === true,
+          mermaid: args['no-mermaid-to-img'] !== true,
         });
         console.log('\n页面信息：');
         console.log(`  ID:      ${result.id}`);
@@ -210,18 +201,22 @@ async function main() {
       }
 
       case 'list-pages': {
-        const space = args.space || defaultSpaceKey;
-        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;
       }