@vdfor/confluence-sync 0.0.1 → 0.3.0

package/README.md

@@ -0,0 +1,148 @@
+# @vdfor/confluence-sync
+
+Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。
+
+## 安装
+
+```bash
+# pnpm
+pnpm add -g @vdfor/confluence-sync
+
+# npm
+npm install -g @vdfor/confluence-sync
+
+# yarn
+yarn global add @vdfor/confluence-sync
+```
+
+## 配置
+
+### 方式1：环境变量
+
+```bash
+# 必填：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"
+
+# 方式2：Basic Auth
+export CONFLUENCE_USERNAME="your-username"
+export CONFLUENCE_API_TOKEN="your-api-token"
+```
+
+### 方式2：CLI 参数（优先于环境变量）
+
+```bash
+confluence-sync upload --file test.md \
+  --base-url https://your-confluence-instance.com \
+  --space-key YOUR_SPACE_KEY \
+  --pat your-token
+```
+
+## 命令
+
+### upload - 上传 Markdown 为新页面
+
+```bash
+confluence-sync upload --file <path> [--title <标题>] [--space <key>] [--parent <ID或标题>] [--dry-run]
+```
+
+### update - 更新已有页面
+
+```bash
+confluence-sync update --file <path> (--page-id <ID> | --title <标题>) [--space <key>] [--minor-edit]
+```
+
+### upload-file - 上传附件
+
+```bash
+confluence-sync upload-file --page-id <ID> --file <path> [--name <文件名>]
+```
+
+### list-pages - 列出空间页面
+
+```bash
+confluence-sync list-pages [--space <key>]
+```
+
+### list-files - 列出页面附件
+
+```bash
+confluence-sync list-files --page-id <ID>
+```
+
+### get-content - 获取页面内容
+
+```bash
+confluence-sync get-content --page-id <ID> [--markdown]
+```
+
+使用 `--markdown` 参数可将 Confluence 内容转换为 Markdown 格式输出。
+
+## 配置参数
+
+| 参数 | 说明 |
+|------|------|
+| `--base-url` | Confluence 服务地址 |
+| `--space-key` | Space Key |
+| `--pat` | Personal Access Token |
+| `--username` | Confluence 登录名 |
+| `--api-token` | API Token 或密码 |
+| `--space` | Space Key（覆盖默认值） |
+| `--file` | 本地文件路径 |
+| `--title` | 页面标题 |
+| `--page-id` | 页面 ID |
+| `--parent` | 父页面 ID 或标题 |
+| `--dry-run` | 仅打印转换结果，不实际上传 |
+| `--minor-edit` | 标记为小修改（不通知关注者） |
+| `--markdown` | get-content 时输出为 Markdown 格式 |
+
+## 示例
+
+```bash
+# 上传 Markdown 文件
+confluence-sync upload --file README.md --title "项目文档" --space MYSPACE
+
+# 更新已有页面
+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
+
+# 获取页面内容
+confluence-sync get-content --page-id 123456
+
+# 获取页面内容并转换为 Markdown
+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 "项目文档" --space MYSPACE
+confluence-sync get-content --page-id 123456 --markdown
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vdfor/confluence-sync",
-  "version": "0.0.1",
+  "version": "0.3.0",
   "author": "vdfor",
   "license": "MIT",
   "private": false,
@@ -20,7 +20,8 @@
   },
   "files": [
     "upload.mjs",
-    "src/"
+    "src/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18"
@@ -37,9 +38,9 @@
     "upload": "node upload.mjs upload",
     "update": "node upload.mjs update",
     "help": "node upload.mjs help",
-    "release:beta": "read -p '请输入版本号 (例如: patch, minor, major 或具体版本号): ' v && pnpm version $v && pnpm publish --registry https://registry.npmjs.org/ --access public --tag beta --no-git-checks",
-    "release": "read -p '请输入版本号 (例如: patch, minor, major 或具体版本号): ' v && pnpm version $v && pnpm publish --registry https://registry.npmjs.org/ --access public --no-git-checks",
-    "v": "read -p '请输入版本号 (例如: patch, minor, major 或具体版本号): ' v && pnpm version $v",
+    "release:beta": "read -p '请输入版本号 (例如: patch, minor, major 或具体版本号): ' v && NPM_CONFIG_GIT_CHECKS=false pnpm version $v --no-git-tag-version --no-git-checks && pnpm publish --tag beta --access public --no-git-checks",
+    "release": "read -p '请输入版本号 (例如: patch, minor, major 或具体版本号): ' v && NPM_CONFIG_GIT_CHECKS=false pnpm version $v --no-git-tag-version --no-git-checks && pnpm publish --access public --no-git-checks",
+    "v": "read -p '请输入版本号 (例如: patch, minor, major 或具体版本号): ' v && pnpm version $v --no-git-tag-version --no-git-checks",
     "clean": "rimraf dist node_modules"
   }
 }

package/skills/confluence-sync.md

@@ -0,0 +1,101 @@
+---
+name: "confluence-sync"
+description: "Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。当用户需要上传、更新、获取 Confluence 页面内容或管理附件时调用。"
+---
+
+# Confluence Sync
+
+Confluence 文档同步 CLI 工具，支持将本地 Markdown 文件上传至 Confluence 并自动转换为 Confluence 页面格式。
+
+## 功能特性
+
+- 上传 Markdown 文件为 Confluence 页面
+- 更新已有页面内容
+- 上传文件作为页面附件
+- 列出空间页面和页面附件
+- 获取页面内容（支持转换为 Markdown 格式）
+
+## 配置要求
+
+使用前需要配置以下环境变量或 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 为新页面
+
+```bash
+confluence-sync upload --file <path> [--title <标题>] [--space <key>] [--parent <ID或标题>] [--dry-run]
+```
+
+### update - 更新已有页面
+
+```bash
+confluence-sync update --file <path> (--page-id <ID> | --title <标题>) [--space <key>] [--minor-edit]
+```
+
+### upload-file - 上传附件
+
+```bash
+confluence-sync upload-file --page-id <ID> --file <path> [--name <文件名>]
+```
+
+### list-pages - 列出空间页面
+
+```bash
+confluence-sync list-pages [--space <key>]
+```
+
+### list-files - 列出页面附件
+
+```bash
+confluence-sync list-files --page-id <ID>
+```
+
+### get-content - 获取页面内容
+
+```bash
+confluence-sync get-content --page-id <ID> [--markdown]
+```
+
+使用 `--markdown` 参数可将 Confluence 内容转换为 Markdown 格式输出。
+
+## 使用示例
+
+```bash
+# 上传 Markdown 文件
+confluence-sync upload --file README.md --title "项目文档" --space MYSPACE
+
+# 更新已有页面
+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
+
+# 获取页面内容
+confluence-sync get-content --page-id 123456
+
+# 获取页面内容并转换为 Markdown
+confluence-sync get-content --page-id 123456 --markdown
+```
+
+## 注意事项
+
+1. 使用前请确保已正确配置认证信息
+2. Personal Access Token 需要在 Confluence 个人设置中生成
+3. 上传附件时，如果附件已存在会自动更新
+4. 使用 `--dry-run` 参数可以预览转换结果而不实际上传

package/src/confluence.mjs

@@ -1,13 +1,10 @@
 import axios from 'axios';
 import { marked } from 'marked';
-import { readFileSync } from 'node:fs';
 import { extname } from 'node:path';
 
 // ── 配置 ──────────────────────────────────────────────────────────────────────
-const config = JSON.parse(readFileSync(new URL('../config.json', import.meta.url), 'utf-8'));
-const { spaceKey: defaultSpaceKey } = config;
-
 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;
@@ -17,12 +14,14 @@ 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;
@@ -271,6 +270,104 @@ export function mdToConfluence(md) {
   return renderTokens(tokens);
 }
 
+// ── Confluence Storage Format → Markdown ─────────────────────────────────────
+
+/**
+ * 将 Confluence storage format（XHTML）转换为 Markdown
+ * @param {string} html - Confluence storage format HTML
+ * @returns {string} Markdown 文本
+ */
+export function confluenceToMd(html) {
+  if (!html) return '';
+
+  let md = html;
+
+  // 代码块：<ac:structured-macro ac:name="code">
+  md = md.replace(/<ac:structured-macro\s+ac:name="code">[\s\S]*?<ac:parameter\s+ac:name="language">([\s\S]*?)<\/ac:parameter>[\s\S]*?<ac:plain-text-body><!\[CDATA\[([\s\S]*?)\]\]><\/ac:plain-text-body>[\s\S]*?<\/ac:structured-macro>/g,
+    (_, lang, code) => `\n\`\`\`${lang}\n${code}\n\`\`\`\n`);
+
+  // 标题
+  md = md.replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, '\n# $1\n');
+  md = md.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, '\n## $1\n');
+  md = md.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, '\n### $1\n');
+  md = md.replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, '\n#### $1\n');
+  md = md.replace(/<h5[^>]*>([\s\S]*?)<\/h5>/gi, '\n##### $1\n');
+  md = md.replace(/<h6[^>]*>([\s\S]*?)<\/h6>/gi, '\n###### $1\n');
+
+  // 粗体、斜体、删除线、行内代码
+  md = md.replace(/<strong>([\s\S]*?)<\/strong>/gi, '**$1**');
+  md = md.replace(/<b>([\s\S]*?)<\/b>/gi, '**$1**');
+  md = md.replace(/<em>([\s\S]*?)<\/em>/gi, '*$1*');
+  md = md.replace(/<i>([\s\S]*?)<\/i>/gi, '*$1*');
+  md = md.replace(/<s>([\s\S]*?)<\/s>/gi, '~~$1~~');
+  md = md.replace(/<del>([\s\S]*?)<\/del>/gi, '~~$1~~');
+  md = md.replace(/<code>([\s\S]*?)<\/code>/gi, '`$1`');
+
+  // 链接
+  md = md.replace(/<a\s+href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, '[$2]($1)');
+
+  // 图片：<ac:image><ri:attachment ri:filename="xxx" /></ac:image>
+  md = md.replace(/<ac:image>[\s\S]*?<ri:attachment\s+ri:filename="([^"]*)"[\s\S]*?\/>[\s\S]*?<\/ac:image>/gi, '![]($1)');
+
+  // 普通图片
+  md = md.replace(/<img\s+[^>]*src="([^"]*)"[^>]*\/?>/gi, '![]($1)');
+
+  // 水平线
+  md = md.replace(/<hr\s*\/?>/gi, '\n---\n');
+
+  // 换行
+  md = md.replace(/<br\s*\/?>/gi, '\n');
+
+  // 段落
+  md = md.replace(/<p>([\s\S]*?)<\/p>/gi, '\n$1\n');
+
+  // 引用块
+  md = md.replace(/<blockquote>([\s\S]*?)<\/blockquote>/gi, (_, content) => {
+    return content.split('\n').map(line => `> ${line}`).join('\n');
+  });
+
+  // 无序列表
+  md = md.replace(/<ul>([\s\S]*?)<\/ul>/gi, (_, content) => {
+    return content.replace(/<li>([\s\S]*?)<\/li>/gi, '- $1\n');
+  });
+
+  // 有序列表
+  md = md.replace(/<ol>([\s\S]*?)<\/ol>/gi, (_, content) => {
+    let i = 0;
+    return content.replace(/<li>([\s\S]*?)<\/li>/gi, () => `${++i}. $1\n`);
+  });
+
+  // 表格
+  md = md.replace(/<table>([\s\S]*?)<\/table>/gi, (_, tableContent) => {
+    let rows = [];
+    // 表头
+    const headerMatch = tableContent.match(/<thead>([\s\S]*?)<\/thead>/i);
+    if (headerMatch) {
+      const cells = headerMatch[1].match(/<th[^>]*>([\s\S]*?)<\/th>/gi) || [];
+      rows.push(cells.map(c => c.replace(/<th[^>]*>([\s\S]*?)<\/th>/i, '$1').trim()));
+      rows.push(rows[0].map(() => '---'));
+    }
+    // 表体
+    const bodyMatch = tableContent.match(/<tbody>([\s\S]*?)<\/tbody>/i);
+    if (bodyMatch) {
+      const trMatches = bodyMatch[1].match(/<tr>([\s\S]*?)<\/tr>/gi) || [];
+      for (const tr of trMatches) {
+        const cells = tr.match(/<td[^>]*>([\s\S]*?)<\/td>/gi) || [];
+        rows.push(cells.map(c => c.replace(/<td[^>]*>([\s\S]*?)<\/td>/i, '$1').trim()));
+      }
+    }
+    return '\n' + rows.map(r => '| ' + r.join(' | ') + ' |').join('\n') + '\n';
+  });
+
+  // 移除剩余 HTML 标签
+  md = md.replace(/<[^>]+>/g, '');
+
+  // 清理多余空行
+  md = md.replace(/\n{3,}/g, '\n\n');
+
+  return md.trim();
+}
+
 // ── 文件上传（附件）────────────────────────────────────────────────────────────
 
 /**
@@ -381,7 +478,8 @@ async function resolveParentId(parentIdentifier, spaceKey) {
  * @param {boolean} [opts.dryRun] - 仅打印转换结果
  */
 export async function uploadMarkdown(opts) {
-  const { filePath, title: optTitle, spaceKey = defaultSpaceKey, parentId: parentRaw, dryRun = false } = opts;
+  const { filePath, title: optTitle, spaceKey: spaceKeyOpt, parentId: parentRaw, dryRun = false } = opts;
+  const effectiveSpaceKey = spaceKeyOpt || spaceKey;
   const fs = await import('node:fs');
   const path = await import('node:path');
 
@@ -392,16 +490,16 @@ export async function uploadMarkdown(opts) {
   if (dryRun) {
     console.log('── 转换结果（dry-run）────────────────────────');
     console.log(`  标题: ${title}`);
-    console.log(`  Space: ${spaceKey}`);
+    console.log(`  Space: ${effectiveSpaceKey}`);
     console.log('  Body:\n' + bodyHtml);
     return null;
   }
 
   // 查找父页面
-  const parentId = await resolveParentId(parentRaw, spaceKey);
+  const parentId = await resolveParentId(parentRaw, effectiveSpaceKey);
 
   // 检查是否已存在同名页面
-  const existing = await getPageByTitle(spaceKey, title);
+  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);
@@ -409,7 +507,7 @@ export async function uploadMarkdown(opts) {
     return updated;
   }
 
-  const page = await createPage(spaceKey, title, bodyHtml, parentId);
+  const page = await createPage(effectiveSpaceKey, title, bodyHtml, parentId);
   console.log(`  ✅ 创建完成 → ${baseUrl}/pages/viewpage.action?pageId=${page.id}`);
   return page;
 }
@@ -418,7 +516,8 @@ export async function uploadMarkdown(opts) {
  * 更新指定页面（通过 ID 或 space+title 查找）
  */
 export async function updateMarkdown(opts) {
-  const { pageId, title: searchTitle, filePath, spaceKey = defaultSpaceKey, minorEdit = false } = opts;
+  const { pageId, title: searchTitle, filePath, spaceKey: spaceKeyOpt, minorEdit = false } = opts;
+  const effectiveSpaceKey = spaceKeyOpt || spaceKey;
   const fs = await import('node:fs');
 
   const md = fs.readFileSync(filePath, 'utf-8');
@@ -428,8 +527,8 @@ export async function updateMarkdown(opts) {
   if (pageId) {
     page = await getPageById(pageId);
   } else if (searchTitle) {
-    page = await getPageByTitle(spaceKey, searchTitle);
-    if (!page) throw new Error(`未找到页面「${searchTitle}」（space: ${spaceKey}）`);
+    page = await getPageByTitle(effectiveSpaceKey, searchTitle);
+    if (!page) throw new Error(`未找到页面「${searchTitle}」（space: ${effectiveSpaceKey}）`);
   } else {
     throw new Error('必须指定 --page-id 或 --title 来定位目标页面');
   }
@@ -441,5 +540,5 @@ export async function updateMarkdown(opts) {
 }
 
 // ── 导出配置 ──────────────────────────────────────────────────────────────────
-export { defaultSpaceKey };
 export function getBaseUrl() { return baseUrl; }
+export function getSpaceKey() { return spaceKey; }

package/upload.mjs

@@ -4,6 +4,7 @@
  *
  * 环境变量（或通过 CLI 参数配置）：
  *   必填：             CONFLUENCE_BASE_URL   - Confluence 服务地址
+ *                      CONFLUENCE_SPACE_KEY  - Space Key
  * 认证方式（二选一）：
  *   方式1 PAT：        CONFLUENCE_PAT       - Personal Access Token
  * 方式2 Basic Auth： CONFLUENCE_USERNAME   - Confluence 登录名（工号）
@@ -15,10 +16,11 @@
  *   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 get-content --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 或密码
@@ -31,8 +33,9 @@ import {
   listPages,
   listAttachments,
   getPageContent,
-  defaultSpaceKey,
+  confluenceToMd,
   getBaseUrl,
+  getSpaceKey,
   configure,
 } from './src/confluence.mjs';
 
@@ -101,9 +104,11 @@ list-files 选项:
 
 get-content 选项:
   --page-id     页面 ID（必填）
+  --markdown    输出为 Markdown 格式（默认输出 Storage HTML）
 
 配置参数（优先于环境变量）:
   --base-url        Confluence 服务地址
+  --space-key       Space Key
   --pat             Personal Access Token
   --username        Confluence 登录名
   --api-token       API Token 或密码
@@ -111,6 +116,7 @@ get-content 选项:
 环境变量:
   必填:
     CONFLUENCE_BASE_URL   Confluence 服务地址
+    CONFLUENCE_SPACE_KEY  Space Key
 
   认证方式（二选一）:
     方式1 - Personal Access Token:
@@ -137,11 +143,13 @@ 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) {
@@ -153,7 +161,7 @@ async function main() {
         const result = await uploadMarkdown({
           filePath: args.file,
           title: args.title,
-          spaceKey: args.space || defaultSpaceKey,
+          spaceKey: args.space || spaceKey,
           parentId: args.parent,
           dryRun: args['dry-run'] === true,
         });
@@ -180,7 +188,7 @@ async function main() {
           pageId: args['page-id'],
           title: args.title,
           filePath: args.file,
-          spaceKey: args.space || defaultSpaceKey,
+          spaceKey: args.space || spaceKey,
           minorEdit: args['minor-edit'] === true,
         });
         console.log('\n页面信息：');
@@ -208,7 +216,7 @@ async function main() {
       }
 
       case 'list-pages': {
-        const space = args.space || defaultSpaceKey;
+        const space = args.space || spaceKey;
         console.log(`Space: ${space}\n`);
         const pages = await listPages(space);
         if (!pages.length) {
@@ -252,8 +260,13 @@ async function main() {
         console.log(`标题:    ${page.title}`);
         console.log(`Space:   ${page.space?.key}`);
         console.log(`版本:    ${page.version?.number}`);
-        console.log(`\n── Storage HTML ──────────────────────────────\n`);
-        console.log(page.body.storage.value);
+        if (args.markdown) {
+          console.log(`\n── Markdown ──────────────────────────────\n`);
+          console.log(confluenceToMd(page.body.storage.value));
+        } else {
+          console.log(`\n── Storage HTML ──────────────────────────────\n`);
+          console.log(page.body.storage.value);
+        }
         break;
       }