@cloudglab/confluence-cli 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+## 0.0.6 - 2026-06-17
+
+### 变更
+
+- Mermaid 图片渲染从 `mmd-cli` 切换为 `beautiful-mermaid-cli` 的 `bm render`，默认 PNG/SVG 渲染不再依赖本机 Chrome、Chromium、Puppeteer 或原生编译工具链。
+- `install` / `update` 改为通过 `npm install -g beautiful-mermaid-cli@latest` 安装 Mermaid 渲染器，不再执行 `raw.githubusercontent.com` 上的 `curl | sh` 安装脚本。
+- 项目运行要求从 Node.js 18+ 提升到 Node.js 20+，与 `beautiful-mermaid-cli` 的运行时要求保持一致。
+- 对齐 `zentao-cli` 的通用账号命令，新增 `whoami`、`who-am-i`，并支持 `confluence who am i` 口语化输入，均复用 `getCurrentUser` 查询当前 Confluence 账号。
+
+### 测试
+
+- `tests/install.test.ts` 同步断言新的 `beautiful-mermaid-cli` 安装链路，并保留安装失败不阻断主流程的回归覆盖。
+- `tests/tools/transfer.test.ts` 同步校验 `bm render <file> -o <png> --json --scale 3` 调用参数。
+- `tests/cli.test.ts` 和 `tests/tools/spaces.test.ts` 覆盖 `whoami` / `who-am-i` 注册、命令列表展示和 `who am i` 归一化。
+
+## 0.0.5 - 2026-06-17
+
+### 修复
+
+- `install` / `update` 链路：把仓库内 `skills/confluence-cli` 从指向 `.agents/skills/confluence-cli` 的符号链接替换为真实目录副本，避免 npm tarball 中 `skills/confluence-cli` 路径在用户机器上不可用导致“未找到已安装包内的 Confluence skill”错误。
+- `install` / `update` 链路：`installMmdCli` 不再因 `curl -fsSL ... | sh` 网络失败而中断整个安装，改为捕获异常并输出 `已跳过 mmd-cli 安装：<原因>` 与后续 `--mermaid none` 退路提示。
+- `install` / `update` 链路：`installSkillFromInstalledPackage` 在 `access` 失败时不再直接抛错，自动回退到 `installSkillFromNpmPackage`（`npm pack` + `tar -xzf` + `npx -y skills add`），覆盖包内 skill 缺失场景。
+
+### 测试
+
+- `tests/install.test.ts` 新增回归用例 `本地 skill 缺失时自动回退到 npm 包解压安装，mmd-cli 失败不阻断安装`：mock `curl` 退出码 35、stderr 含 `curl: (35) LibreSSL SSL_connect...`，断言安装链路按 `npm install -g` → 跳过 `mmd-cli` → `npm pack` → `tar` → `npx -y skills add` 顺序完成，并校验 stdout 中包含“已跳过 mmd-cli 安装”与“正在自动回退到 npm 包解压安装”两行提示。
+
+### 说明
+
+- 本次热修不改变 `mmd-cli` 运行时仍需系统 Chrome/Chromium 的前提；网络环境下无法自动安装 `mmd-cli` 时，建议用户改用 `--mermaid none` 保留代码块。
+- 验证结果：`pnpm test -- tests/install.test.ts tests/skill.test.ts tests/tools/transfer.test.ts` 全部通过（3 个文件、10 个测试）。
+
 ## 0.0.4 - 2026-06-17
 
 ### 修复

package/README.md

@@ -21,9 +21,16 @@ pnpm test
 pnpm release:smoke-query --dry-run
 ```
 
-从 `0.0.4` 起，Mermaid 渲染不再依赖 `@mermaid-js/mermaid-cli`。CLI 安装/更新时会自动安装 `coolamit/mermaid-cli` 提供的原生二进制 `mmd-cli`，避开 Puppeteer/Chrome 下载链路，并在卸载时清理常见安装位置下的 `mmd-cli` 二进制。
+Mermaid 渲染默认使用 `beautiful-mermaid-cli` 的 `bm` 命令。它通过纯 JS + WASM 渲染 SVG/PNG，不依赖 Chrome、Chromium、Puppeteer 或原生编译工具链；安装/更新时会自动执行 `npm install -g beautiful-mermaid-cli@latest`。
 
-`mmd-cli` 运行时仍需要系统已有 Chrome/Chromium；如果机器完全没有浏览器，可在上传时传 `--mermaid none`，保留 Mermaid 代码块。
+由于 `beautiful-mermaid-cli` 要求 Node.js 20+，本项目运行要求也同步提升到 Node.js 20+。如果自动安装失败，上传时仍可传 `--mermaid none` 保留 Mermaid 代码块。
+
+当前版本还补齐了 `zentao-cli` 风格的账号快捷命令：`confluence whoami`、`confluence who-am-i`，以及口语化输入 `confluence who am i`。
+
+`install` / `update` 在以下情况会**继续完成安装**而不是中断：
+
+- `beautiful-mermaid-cli` 安装失败时，会打印 `已跳过 beautiful-mermaid-cli 安装：<原因>` 与 `后续如需 Mermaid 图片渲染，可稍后重试安装，或在上传时传 --mermaid none 保留代码块。`。
+- 全局包内 `skills/confluence-cli` 缺失时，会打印 `未找到已安装包内的 Confluence skill：<path>，正在自动回退到 npm 包解压安装...` 并自动用 `npm pack` + `tar` + `npx -y skills add` 完成 skill 安装，无需手动切换 `--skill-source npm`。
 
 安装/更新入口：
 
@@ -66,6 +73,7 @@ CLI 会按顺序查找：显式 `envFile`、环境变量、当前/父目录 `.en
 
 ```bash
 confluence list
+confluence whoami
 confluence searchContent --cql 'space = "DEV" AND text ~ "API"'
 confluence getContent --id 123456
 confluence listRestApis --group content
@@ -136,7 +144,7 @@ CONFLUENCE_SKIP_UPDATE_CHECK=true
 - Confluence 7.13.7 全量 REST API 端点注册与通用调用
 - MCP 页面/子页/评论/标签能力的语义化 CLI 命令
 - Markdown 转 Confluence Wiki Markup
-- Markdown/HTML 上传时默认用 `mmd-cli` 将 Mermaid 渲染为 PNG 附件并以内置图片宏展示，必要时可用 `--mermaid none` 保留原代码块
+- Markdown/HTML 上传时默认用 `beautiful-mermaid-cli` 将 Mermaid 渲染为 PNG 附件并以内置图片宏展示，必要时可用 `--mermaid none` 保留原代码块
 - mark 风格 metadata 生成
 - Markdown 上传预览、确认写入和附件上传
 - 页面下载为带 frontmatter 的 Markdown，并可下载附件和一层子页

package/dist/cli.js

@@ -149,6 +149,17 @@ function parseCli(argv) {
         role = value;
         args.splice(roleIndex, 2);
     }
-    return { command: args[0], commandArgs: args.slice(1), role };
+    const normalized = normalizeCommandAlias(args[0], args.slice(1));
+    return {
+        command: normalized.command,
+        commandArgs: args.slice(1 + normalized.consumedArgs),
+        role,
+    };
+}
+function normalizeCommandAlias(command, args) {
+    if (command === "who" && args[0] === "am" && args[1] === "i") {
+        return { command: "whoami", consumedArgs: 2 };
+    }
+    return { command, consumedArgs: 0 };
 }
 //# sourceMappingURL=cli.js.map

package/dist/core/cli-output.js

@@ -23,6 +23,9 @@ const COMMAND_DESCRIPTIONS = {
     searchSpace: "搜索 Confluence 空间",
     listSpaces: "列出 Confluence 空间",
     getSpace: "获取空间详情",
+    getCurrentUser: "输出当前账号原始资料",
+    whoami: "查看当前 Confluence 账号",
+    "who-am-i": "whoami 的别名",
     searchContent: "使用 CQL 搜索内容",
     getContent: "获取页面或博客内容",
     createContent: "创建 Confluence 内容",
@@ -46,7 +49,7 @@ export function printHelp(role, commandNames) {
         "",
         `当前 role: ${role}`,
         "适配版本：Confluence Data Center / Server REST API。",
-        "运行要求：Node.js >= 18",
+        "运行要求：Node.js >= 20",
         "",
         "用法：",
         "  confluence [--role full|reader|writer] <command> [--key value]",
@@ -56,6 +59,7 @@ export function printHelp(role, commandNames) {
         "快速开始：",
         "  confluence list                 查看全部可用命令（推荐）",
         "  confluence help <command>       查看命令参数",
+        "  confluence whoami               校验当前账号",
         "  confluence initConfluence       初始化或校验连接配置",
         "  confluence version              查看版本",
         "  confluence changelog            查看最近更新",
@@ -99,7 +103,7 @@ export function printCommandList(role, commandNames, builtinCommandNames = BUILT
         }
         lines.push("");
     }
-    lines.push("下一步：", "  - 查看参数：confluence help <command>，例如 confluence help searchContent", "  - 初始化配置：confluence initConfluence", "  - 查看脚本友好命令名：confluence list --raw", "  - 切换角色命令集：confluence --role reader list 或 confluence --role writer list", "");
+    lines.push("下一步：", "  - 查看参数：confluence help <command>，例如 confluence help searchContent", "  - 快速校验账号：confluence whoami", "  - 初始化配置：confluence initConfluence", "  - 查看脚本友好命令名：confluence list --raw", "  - 切换角色命令集：confluence --role reader list 或 confluence --role writer list", "");
     process.stdout.write(lines.join("\n"));
 }
 export function getBuiltinCommandHelp(commandName) {
@@ -210,7 +214,7 @@ export function renderCommandHelp(registry, name) {
 }
 function buildCommandGroups(commandNames) {
     const groups = [
-        { title: "开始使用", match: (name) => ["changelog", "help", "list", "version", "install", "update", "upgrade", "uninstall", "remove", "initConfluence"].includes(name), commands: [] },
+        { title: "开始使用", match: (name) => ["changelog", "help", "list", "version", "install", "update", "upgrade", "uninstall", "remove", "initConfluence", "whoami", "who-am-i", "getCurrentUser"].includes(name), commands: [] },
         { title: "内容检索 / 页面", match: (name) => /Content|Page|searchContent|getContent/.test(name), commands: [] },
         { title: "上传 / 下载 / 附件", match: (name) => /Upload|Download|Attachment|upload|download/.test(name), commands: [] },
         { title: "空间 / 标签", match: (name) => /Space|Label/.test(name), commands: [] },
@@ -226,6 +230,7 @@ function buildCommandGroups(commandNames) {
 }
 function getRecommendedCommands(commandNames) {
     const candidates = [
+        { name: "whoami", description: "校验当前账号" },
         { name: "initConfluence", description: "初始化或校验连接配置" },
         { name: "searchContent", description: "使用 CQL 搜索页面/博客" },
         { name: "getContent", description: "读取 Confluence 内容" },

package/dist/core/command-groups.generated.js

@@ -14,6 +14,8 @@ export const commandToGroup = {
     "getCurrentUser": "space",
     "getSpace": "space",
     "listSpaces": "space",
+    "who-am-i": "space",
+    "whoami": "space",
     "addComment": "content",
     "deleteContent": "content",
     "findContent": "content",
@@ -57,7 +59,9 @@ export const groupCommands = {
         "convertContentBody",
         "getCurrentUser",
         "getSpace",
-        "listSpaces"
+        "listSpaces",
+        "who-am-i",
+        "whoami"
     ],
     "content": [
         "addComment",

package/dist/install.js

@@ -7,7 +7,7 @@ import { loadConfluenceConfig, normalizeConfig, saveConfig } from "./core/config
 import { writeUpdateCacheAfterInstall } from "./update-probe.js";
 const PACKAGE_NAME = "@cloudglab/confluence-cli";
 const GIT_SKILL_SOURCE = "cloudglab/confluence-cli";
-const MMD_CLI_INSTALL_URL = "https://raw.githubusercontent.com/coolamit/mermaid-cli/master/install.sh";
+const MERMAID_RENDERER_PACKAGE = "beautiful-mermaid-cli";
 export async function runInstallCommand(args = []) {
     const options = parseInstallOptions(args);
     await installPackageAndSkill("安装", options);
@@ -57,7 +57,7 @@ function printSuccessGuide(action, status) {
   confluence update                       更新 CLI 和 Skill
   confluence install --skip-config-check  仅安装，跳过配置校验
   confluence install --skill-global       把 skill 装到 user-level 全局目录
-  mmd-cli --version                       检查 Mermaid 渲染器
+  bm doctor --json                       检查 Mermaid 渲染器
   CONFLUENCE_DISABLE_WRITE=true           禁用真实写操作
 
 写操作提示：真实写入仍需显式传 confirm=true。
@@ -160,7 +160,7 @@ function parseUninstallOptions(args) {
 function printUninstallPreview(options) {
     const steps = [
         ...(!options.cliOnly ? ["卸载 confluence skill（项目级和全局级）"] : []),
-        ...(!options.skillOnly ? ["卸载全局 CLI 包、清理 npm 残留目录，并删除 mmd-cli 二进制"] : []),
+        ...(!options.skillOnly ? ["卸载全局 CLI 包、清理 npm 残留目录，并卸载 Mermaid 渲染器"] : []),
         ...(shouldRemoveConfig(options) ? ["删除 ~/.confluence/config.json"] : ["保留 ~/.confluence/config.json"]),
     ];
     process.stdout.write(`卸载预览：\n${steps.map((step) => `  - ${step}`).join("\n")}\n\n真实执行请运行：\n  confluence uninstall --confirm true\n  npx -y ${PACKAGE_NAME}@latest uninstall --confirm true\n\n可选参数：\n  --keep-config true   保留 Confluence 配置\n  --cli-only true      只卸载 CLI\n  --skill-only true    只卸载 skill\n`);
@@ -224,7 +224,7 @@ async function installPackageAndSkill(action, options) {
     if (!options.skillOnly) {
         await cleanupGlobalPackageResidues();
         await installGlobalCli(action);
-        await installMmdCli(action);
+        await installMermaidRenderer(action);
     }
     if (!options.cliOnly) {
         await installSkill(action, options);
@@ -245,8 +245,15 @@ async function installGlobalCli(action) {
         await runStep(`${action} Confluence CLI`, "npm", args);
     }
 }
-async function installMmdCli(action) {
-    await runStep(`${action} Mermaid 原生渲染器 mmd-cli`, "sh", ["-c", `curl -fsSL ${MMD_CLI_INSTALL_URL} | sh`]);
+async function installMermaidRenderer(action) {
+    try {
+        await runStep(`${action} Mermaid 免浏览器渲染器 beautiful-mermaid-cli`, "npm", ["install", "-g", `${MERMAID_RENDERER_PACKAGE}@latest`]);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(`已跳过 beautiful-mermaid-cli 安装：${message}\n`);
+        process.stdout.write("后续如需 Mermaid 图片渲染，可稍后重试安装，或在上传时传 --mermaid none 保留代码块。\n");
+    }
 }
 function isNpmDirectoryNotEmptyError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -286,7 +293,9 @@ async function installSkillFromInstalledPackage(action, skillGlobal) {
         await access(skillPath);
     }
     catch {
-        throw new Error(`未找到已安装包内的 Confluence skill：${skillPath}。可重试 --skill-source npm 或 --skill-source git。`);
+        process.stdout.write(`未找到已安装包内的 Confluence skill：${skillPath}，正在自动回退到 npm 包解压安装...\n`);
+        await installSkillFromNpmPackage(action, skillGlobal);
+        return;
     }
     await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(skillPath, skillGlobal));
 }
@@ -317,11 +326,16 @@ async function uninstallSkill() {
 async function uninstallPackage() {
     await runStep("卸载 Confluence CLI", "npm", ["uninstall", "-g", PACKAGE_NAME]);
     await cleanupGlobalPackageResidues();
-    await removeMmdCliBinary();
+    await uninstallMermaidRenderer();
 }
-async function removeMmdCliBinary() {
-    await rm(path.join(os.homedir(), ".local", "bin", "mmd-cli"), { force: true });
-    await rm("/usr/local/bin/mmd-cli", { force: true });
+async function uninstallMermaidRenderer() {
+    try {
+        await runStep("卸载 Mermaid 免浏览器渲染器 beautiful-mermaid-cli", "npm", ["uninstall", "-g", MERMAID_RENDERER_PACKAGE]);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(`已跳过 beautiful-mermaid-cli 卸载：${message}\n`);
+    }
 }
 async function cleanupGlobalPackageResidues() {
     const globalNodeModules = (await runCommandOutput("npm", ["root", "-g"])).trim();

package/dist/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.4",
+  "version": "0.0.6",
   "commands": [
     "addComment",
     "addLabels",
@@ -31,7 +31,9 @@
     "updateAttachment",
     "uploadAttachment",
     "uploadHtml",
-    "uploadMarkdown"
+    "uploadMarkdown",
+    "who-am-i",
+    "whoami"
   ],
   "groups": {
     "init": [
@@ -58,7 +60,9 @@
       "convertContentBody",
       "getCurrentUser",
       "getSpace",
-      "listSpaces"
+      "listSpaces",
+      "who-am-i",
+      "whoami"
     ],
     "content": [
       "addComment",
@@ -101,6 +105,8 @@
     "getCurrentUser": "space",
     "getSpace": "space",
     "listSpaces": "space",
+    "who-am-i": "space",
+    "whoami": "space",
     "addComment": "content",
     "deleteContent": "content",
     "findContent": "content",

package/dist/tools/spaces.js

@@ -2,15 +2,18 @@ import { z } from "zod";
 import { getApi } from "../core/api-provider.js";
 import { jsonResult } from "../utils/result.js";
 export function registerSpaceTools(registry) {
+    const getCurrentUser = async () => {
+        return jsonResult(await getApi().getCurrentUser());
+    };
     registry.tool("listSpaces", z.object({ limit: z.number().int().positive().max(100).default(25) }), async ({ limit }) => {
         return jsonResult(await getApi().listSpaces(limit));
     }, "List Confluence spaces");
     registry.tool("getSpace", z.object({ spaceKey: z.string() }), async ({ spaceKey }) => {
         return jsonResult(await getApi().getSpace(spaceKey));
     }, "Get one Confluence space by key");
-    registry.tool("getCurrentUser", z.object({}), async () => {
-        return jsonResult(await getApi().getCurrentUser());
-    }, "Get current authenticated Confluence user");
+    registry.tool("getCurrentUser", z.object({}), getCurrentUser, "Get current authenticated Confluence user");
+    registry.tool("whoami", z.object({}), getCurrentUser, "Show current authenticated Confluence user");
+    registry.tool("who-am-i", z.object({}), getCurrentUser, "Alias of whoami");
     registry.tool("convertContentBody", z.object({ to: z.enum(["storage", "view", "export_view", "styled_view"]), value: z.string(), representation: z.enum(["wiki", "storage", "view"]).default("wiki") }), async ({ to, value, representation }) => {
         return jsonResult(await getApi().convertBody(to, { value, representation: representation ?? "wiki" }));
     }, "Convert Confluence content body representation");

package/dist/tools/transfer.js

@@ -382,29 +382,30 @@ function createMermaidFile(mermaidSource, pageTitle, sourceFile, idx, renderKind
 function renderMermaidFile(mermaidSource, outputFile, renderKind) {
     const inputFile = join(dirname(outputFile), `${basename(outputFile, extname(outputFile))}.mmd`);
     writeFileSync(inputFile, mermaidSource, "utf8");
-    const mmdCli = resolveMmdCliBin();
-    const args = ["-i", inputFile, "-o", outputFile, "-b", "transparent"];
+    const renderer = resolveBeautifulMermaidBin();
+    const args = ["render", inputFile, "-o", outputFile, "--json"];
     if (renderKind === "png") {
-        args.push("-s", "3");
+        args.push("--scale", "3");
     }
     try {
-        execFileSync(mmdCli, args, { stdio: "pipe" });
+        execFileSync(renderer, args, { stdio: "pipe" });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to render Mermaid as ${renderKind} with mmd-cli: ${message}`);
+        throw new Error(`Failed to render Mermaid as ${renderKind} with beautiful-mermaid-cli: ${message}`);
     }
 }
-function resolveMmdCliBin() {
-    const extension = process.platform === "win32" ? ".exe" : "";
+function resolveBeautifulMermaidBin() {
+    const extension = process.platform === "win32" ? ".cmd" : "";
     const candidates = [
-        join(process.env.HOME ?? "", ".local", "bin", `mmd-cli${extension}`),
-        "/usr/local/bin/mmd-cli",
+        join(process.env.HOME ?? "", ".npm-global", "bin", `bm${extension}`),
+        join(process.env.HOME ?? "", ".local", "bin", `bm${extension}`),
+        `/usr/local/bin/bm${extension}`,
     ];
     const found = candidates.find((candidate) => existsSync(candidate));
     if (found)
         return found;
-    return `mmd-cli${extension}`;
+    return `bm${extension}`;
 }
 function safeFileName(value) {
     return value.replace(/[\\/:*?"<>|]/g, "_");

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.4";
+export declare const VERSION = "0.0.6";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.0.4";
+export const VERSION = "0.0.6";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglab/confluence-cli",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Confluence REST CLI for agents and local automation",
   "repository": {
     "type": "git",
@@ -53,7 +53,7 @@
     "vitest": "^4.1.8"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"

package/skills/confluence-cli/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: confluence-cli
+description: Use this CLI for Confluence REST operations from a terminal or agent workflow. Triggers on Confluence page search, read, upload (Markdown/HTML with Mermaid + TOC), download, labels, attachments, comments, and Confluence 7.13.7 REST pass-through.
+---
+
+# Confluence CLI Skill
+
+Use this CLI when a task needs Confluence REST operations from a terminal or agent workflow.
+
+Start with these references when you need details:
+
+- `reference/overview.md`：整体工作流与安全原则
+- `reference/commands.md`：命令速查
+- `reference/cli.md`：安装、更新、角色入口和环境变量
+- `reference/content.md`：页面查询、读取、子页、评论、标签
+- `reference/transfer.md`：Markdown/HTML 发布、下载、附件、Mermaid/TOC
+- `reference/rest.md`：Confluence 7.13.7 REST 端点透传
+- `../../docs/release.md`：发布前检查与 npm 发布流程
+
+## Decision Matrix
+
+- Read/search small content: `confluence searchContent` or `confluence getContent`.
+- Convert Markdown locally: `confluence convertMarkdownToWiki`.
+- Generate mark metadata: `confluence generateMarkMetadata`.
+- Upload large Markdown through REST: `confluence uploadMarkdown --toc --confirm true`.
+- Upload raw HTML through REST: `confluence uploadHtml --toc --confirm true`.
+- For full page publishes or republish flows, include `--toc` by default; only omit it when the user explicitly says no TOC.
+- Upload Markdown with attachments: `confluence uploadMarkdown --attachments '["a.png"]' --toc --confirm true`.
+- Dry-run uploads first: omit `--confirm true`.
+- Render Mermaid on the fly: any ```mermaid fence in Markdown/HTML auto-generates PNG attachments by default.
+- Download editable backup: `confluence downloadPage`.
+- Download page with attachments/children: `confluence downloadPage --downloadAttachments true --downloadChildren true`.
+- Use MCP-style page tools: `getPageChildren`, `getComments`, `addComment`, `getLabels`, `addLabels`.
+- Use attachment tools: `listAttachments`, `uploadAttachment`, `updateAttachment`, `downloadAttachment`.
+- Check PAT identity: `confluence getCurrentUser`.
+
+## Safety
+
+All writes must pass `--confirm true`. Without confirmation, upload, delete, label, comment and attachment write commands return a dry-run preview.
+
+## CQL Examples
+
+```bash
+confluence searchContent --cql 'space = "DEV" AND text ~ "API"'
+confluence searchContent --cql 'type = page AND title ~ "Runbook"'
+```
+
+## Upload Patterns
+
+```bash
+# Markdown → Confluence，自动 Mermaid → PNG 附件图片，默认注入双 TOC 宏
+confluence uploadMarkdown --file doc.md --id 142552620 --toc --tocMaxLevel 3 --confirm true
+
+# 保持原代码块不渲染
+confluence uploadMarkdown --file doc.md --id 142552620 --mermaid none --toc --confirm true
+
+# HTML → Confluence，同样支持Mermaid和TOC
+confluence uploadHtml --file page.html --space DEV --toc --confirm true
+
+# 只预览（dry-run）
+confluence uploadMarkdown --file doc.md --id 142552620 --toc
+confluence uploadHtml --file page.html --space DEV --toc
+```

package/skills/confluence-cli/reference/cli.md

@@ -0,0 +1,36 @@
+# CLI
+
+## 安装与更新
+
+```bash
+confluence install --skip-config-check true
+confluence update --skip-config-check true
+```
+
+可选参数：
+
+- `--skill-source local|git|npm`
+- `--skill-local-path <dir>`
+- `--cli-only true|false`
+- `--skill-only true|false`
+- `--skip-config-check true|false`
+
+## 角色入口
+
+```bash
+confluence list
+confluence-reader list
+confluence-writer list
+```
+
+- `confluence`：完整入口。
+- `confluence-reader`：不注册发布上传类 transfer 命令。
+- `confluence-writer`：注册写入和发布命令，但仍需要 `--confirm true`。
+
+## 环境变量
+
+- `CONFLUENCE_URL`
+- `CONFLUENCE_PAT` 或 `CONFLUENCE_PERSONAL_TOKEN`
+- `CONFLUENCE_USERNAME` + `CONFLUENCE_PASSWORD`
+- `CONFLUENCE_DISABLE_WRITE=true`
+- `CONFLUENCE_SKIP_UPDATE_CHECK=true`

package/skills/confluence-cli/reference/commands.md

@@ -0,0 +1,41 @@
+# 命令速查
+
+## 基础
+
+```bash
+confluence help
+confluence list
+confluence version
+confluence help searchContent
+```
+
+## 配置
+
+```bash
+confluence initConfluence --url https://confluence.example.com --pat TOKEN --save true
+```
+
+## 查询
+
+```bash
+confluence searchContent --cql 'space = "DEV" AND text ~ "API"'
+confluence getContent --id 123456
+confluence findContent --space DEV --title "API Guide"
+confluence getPageChildren --id 123456 --type page
+```
+
+## 发布与下载
+
+```bash
+confluence uploadMarkdown --file docs/page.md --space DEV --toc --confirm false
+confluence uploadMarkdown --file docs/page.md --id 123456 --attachments '["docs/a.png"]' --toc --confirm true
+confluence uploadHtml --file docs/page.html --space DEV --toc --confirm true
+confluence downloadPage --id 123456 --outputDir exports --downloadAttachments true --downloadChildren true
+```
+
+## REST 透传
+
+```bash
+confluence listRestApis --group content --limit 20
+confluence callRestApi --method GET --path '/content/{id}' --pathParams '{"id":"123456"}' --query '{"expand":"body.storage,version"}'
+```

package/skills/confluence-cli/reference/content.md

@@ -0,0 +1,23 @@
+# 内容操作
+
+## 查询页面
+
+```bash
+confluence searchContent --cql 'type = page AND title ~ "Runbook"'
+confluence findContent --space DEV --title "Runbook"
+confluence getContent --id 123456
+```
+
+## 子页、评论、标签
+
+```bash
+confluence getPageChildren --id 123456 --type page
+confluence getComments --id 123456
+confluence addComment --id 123456 --text "LGTM" --confirm true
+confluence getLabels --id 123456
+confluence addLabels --id 123456 --labels '["api","docs"]' --confirm true
+```
+
+## 安全原则
+
+所有删除、评论、标签等写命令都必须显式 `--confirm true`；不传确认时只返回 preview。

package/skills/confluence-cli/reference/overview.md

@@ -0,0 +1,23 @@
+# 总览
+
+## 这个 skill 做什么
+
+- 用命令行方式操作 Confluence Server/Data Center REST API。
+- 默认写操作只 preview，真实写入必须显式 `--confirm true`。
+- 支持页面搜索、读取、评论、标签、附件、Markdown/HTML 发布、页面下载和 REST 端点透传。
+
+## 推荐工作流
+
+1. 先确认本机是否安装 `confluence`。
+2. 如果没有，优先运行 `confluence install --skip-config-check true`。
+3. 对命令参数不确定时，先运行 `confluence help <command>` 校对。
+4. 查询类任务优先用 `searchContent`、`getContent`、`findContent`。
+5. 发布类任务优先 dry-run，再加 `--confirm true`。
+6. Markdown/HTML 全量发布默认加 `--toc`，除非用户明确不要目录。
+7. 自动化环境可设置 `CONFLUENCE_DISABLE_WRITE=true` 彻底禁用真实写入。
+
+## 适合谁
+
+- 需要命令行操作 Confluence 的人。
+- 需要把 Confluence 接入智能体的人。
+- 需要在 Confluence 7.13.7 环境下稳定自动化的人。

package/skills/confluence-cli/reference/rest.md

@@ -0,0 +1,19 @@
+# REST 透传
+
+`listRestApis` 和 `callRestApi` 用于覆盖 Confluence 7.13.7 官方 REST 端点。
+
+## 查看端点
+
+```bash
+confluence listRestApis --limit 20
+confluence listRestApis --group content --limit 20
+confluence listRestApis --method GET --write false --limit 20
+```
+
+## 调用端点
+
+```bash
+confluence callRestApi --method GET --path '/content/{id}' --pathParams '{"id":"123456"}' --query '{"expand":"body.storage,version"}'
+```
+
+写 REST 端点仍受 `--confirm true` 和 `CONFLUENCE_DISABLE_WRITE=true` 保护。

package/skills/confluence-cli/reference/transfer.md

@@ -0,0 +1,27 @@
+# 发布与下载
+
+## Markdown 发布
+
+```bash
+confluence uploadMarkdown --file docs/page.md --space DEV --toc --confirm false
+confluence uploadMarkdown --file docs/page.md --id 123456 --toc --confirm true
+```
+
+## HTML 发布
+
+```bash
+confluence uploadHtml --file docs/page.html --space DEV --toc --confirm false
+confluence uploadHtml --file docs/page.html --id 123456 --toc --confirm true
+```
+
+## Mermaid 与附件
+
+- 默认将 Markdown/HTML 中的 Mermaid 渲染为 PNG 附件并插入图片宏。
+- 如需保留原代码块，使用 `--mermaid none`。
+- 附件用 JSON 数组传入：`--attachments '["docs/a.png"]'`。
+
+## 下载
+
+```bash
+confluence downloadPage --id 123456 --outputDir exports --downloadAttachments true --downloadChildren true
+```