@vdfor/confluence-sync 0.1.0 → 0.3.0

package/README.md

@@ -23,6 +23,9 @@ yarn global add @vdfor/confluence-sync
 # 必填：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"
@@ -37,6 +40,7 @@ export CONFLUENCE_API_TOKEN="your-api-token"
 ```bash
 confluence-sync upload --file test.md \
   --base-url https://your-confluence-instance.com \
+  --space-key YOUR_SPACE_KEY \
   --pat your-token
 ```
 
@@ -85,10 +89,11 @@ 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 或密码 |
-| `--space` | Space Key |
+| `--space` | Space Key（覆盖默认值） |
 | `--file` | 本地文件路径 |
 | `--title` | 页面标题 |
 | `--page-id` | 页面 ID |
@@ -119,6 +124,25 @@ 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 "项目文档" --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.1.0",
+  "version": "0.3.0",
   "author": "vdfor",
   "license": "MIT",
   "private": false,
@@ -20,7 +20,8 @@
   },
   "files": [
     "upload.mjs",
-    "src/"
+    "src/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18"

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;
@@ -479,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');
 
@@ -490,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);
@@ -507,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;
 }
@@ -516,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');
@@ -526,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 来定位目标页面');
   }
@@ -539,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 登录名（工号）
@@ -19,6 +20,7 @@
  *
  * 可选配置参数（优先于环境变量）：
  *   --base-url        Confluence 服务地址
+ *   --space-key       Space Key
  *   --pat             Personal Access Token
  *   --username        Confluence 登录名
  *   --api-token       API Token 或密码
@@ -32,8 +34,8 @@ import {
   listAttachments,
   getPageContent,
   confluenceToMd,
-  defaultSpaceKey,
   getBaseUrl,
+  getSpaceKey,
   configure,
 } from './src/confluence.mjs';
 
@@ -106,6 +108,7 @@ get-content 选项:
 
 配置参数（优先于环境变量）:
   --base-url        Confluence 服务地址
+  --space-key       Space Key
   --pat             Personal Access Token
   --username        Confluence 登录名
   --api-token       API Token 或密码
@@ -113,6 +116,7 @@ get-content 选项:
 环境变量:
   必填:
     CONFLUENCE_BASE_URL   Confluence 服务地址
+    CONFLUENCE_SPACE_KEY  Space Key
 
   认证方式（二选一）:
     方式1 - Personal Access Token:
@@ -139,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) {
@@ -155,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,
         });
@@ -182,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页面信息：');
@@ -210,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) {