@cloudglab/confluence-cli 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.0.4 - 2026-06-17
+
+### 修复
+
+- Mermaid 渲染器从 `@mermaid-js/mermaid-cli` 全量替换为 `coolamit/mermaid-cli` 的原生二进制 `mmd-cli`，不再保留 `mmdc` / Puppeteer 兼容路径。
+- `install` / `update` 链路会自动执行上游 `mmd-cli` 安装脚本，避免 npm 安装阶段拉取 Chrome 失败。
+- `uninstall` 链路会一并清理 `~/.local/bin/mmd-cli` 和 `/usr/local/bin/mmd-cli`。
+- `uploadMarkdown` 的 Mermaid 附件匹配逻辑改为优先按预期文件名命中，减少多附件场景下图片宏指向错误的问题。
+
+### 测试
+
+- `tests/install.test.ts` 新增 `mmd-cli` 安装步骤断言，覆盖 install / update 流程。
+- `tests/tools/transfer.test.ts` 新增 Mermaid 渲染调用测试，校验 `mmd-cli` 的输入、输出、背景和缩放参数。
+
+### 说明
+
+- `mmd-cli` 运行时仍要求系统已有 Chrome/Chromium；如果目标机器没有浏览器，可在上传时传 `--mermaid none`，保留 Mermaid 代码块。
+
 ## 0.0.3 - 2026-06-16
 
 ### Fixed

package/README.md

@@ -21,6 +21,10 @@ 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` 二进制。
+
+`mmd-cli` 运行时仍需要系统已有 Chrome/Chromium；如果机器完全没有浏览器，可在上传时传 `--mermaid none`，保留 Mermaid 代码块。
+
 安装/更新入口：
 
 ```bash
@@ -132,7 +136,7 @@ CONFLUENCE_SKIP_UPDATE_CHECK=true
 - Confluence 7.13.7 全量 REST API 端点注册与通用调用
 - MCP 页面/子页/评论/标签能力的语义化 CLI 命令
 - Markdown 转 Confluence Wiki Markup
-- Markdown/HTML 上传时默认用 `mermaid-cli` 将 Mermaid 渲染为 PNG 附件并以内置图片宏展示，必要时可用 `--mermaid none` 保留原代码块
+- Markdown/HTML 上传时默认用 `mmd-cli` 将 Mermaid 渲染为 PNG 附件并以内置图片宏展示，必要时可用 `--mermaid none` 保留原代码块
 - mark 风格 metadata 生成
 - Markdown 上传预览、确认写入和附件上传
 - 页面下载为带 frontmatter 的 Markdown，并可下载附件和一层子页
@@ -143,7 +147,7 @@ CONFLUENCE_SKIP_UPDATE_CHECK=true
 
 `.opencode/opencode.json` 提供了两个项目级 OpenCode 命令：
 
-- `release`：复刻 zentao-cli 的 `/release` 流程，按 12 步固定顺序准备发布；默认手动发包，**未经再次授权不会执行 `npm publish`、`git push`、打 tag 或创建 GitHub Release**。
+- `release`：复刻 zentao-cli 的 `/release` 流程，按 14 步固定顺序准备发布；默认手动发包，**未经再次授权不会执行 `npm publish`、`git push`、打 tag 或创建 GitHub Release**。
 - `smoke`：检查当前 CLI 的烟测与验证入口（`pnpm release:smoke-query --dry-run`、`pnpm typecheck`、`pnpm build` 等）。
 
 修改 `.opencode/opencode.json` 后，需要退出并重启 OpenCode 才能生效。

package/dist/install.js

@@ -7,6 +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";
 export async function runInstallCommand(args = []) {
     const options = parseInstallOptions(args);
     await installPackageAndSkill("安装", options);
@@ -56,6 +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 渲染器
   CONFLUENCE_DISABLE_WRITE=true           禁用真实写操作
 
 写操作提示：真实写入仍需显式传 confirm=true。
@@ -158,7 +160,7 @@ function parseUninstallOptions(args) {
 function printUninstallPreview(options) {
     const steps = [
         ...(!options.cliOnly ? ["卸载 confluence skill（项目级和全局级）"] : []),
-        ...(!options.skillOnly ? ["卸载全局 CLI 包并清理 npm 残留目录"] : []),
+        ...(!options.skillOnly ? ["卸载全局 CLI 包、清理 npm 残留目录，并删除 mmd-cli 二进制"] : []),
         ...(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`);
@@ -222,6 +224,7 @@ async function installPackageAndSkill(action, options) {
     if (!options.skillOnly) {
         await cleanupGlobalPackageResidues();
         await installGlobalCli(action);
+        await installMmdCli(action);
     }
     if (!options.cliOnly) {
         await installSkill(action, options);
@@ -242,6 +245,9 @@ 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`]);
+}
 function isNpmDirectoryNotEmptyError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.includes("ENOTEMPTY") || message.toLowerCase().includes("directory not empty");
@@ -311,6 +317,11 @@ async function uninstallSkill() {
 async function uninstallPackage() {
     await runStep("卸载 Confluence CLI", "npm", ["uninstall", "-g", PACKAGE_NAME]);
     await cleanupGlobalPackageResidues();
+    await removeMmdCliBinary();
+}
+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 cleanupGlobalPackageResidues() {
     const globalNodeModules = (await runCommandOutput("npm", ["root", "-g"])).trim();
@@ -370,7 +381,7 @@ async function runStep(title, command, args) {
 }
 function runCommand(command, args) {
     return new Promise((resolve, reject) => {
-        const child = spawn(command, args, { shell: process.platform === "win32" });
+        const child = spawn(command, args, { shell: process.platform === "win32", env: createInstallEnv() });
         let stderr = "";
         child.stdout?.pipe(process.stdout);
         child.stderr?.on("data", (chunk) => {
@@ -389,7 +400,7 @@ function runCommand(command, args) {
 }
 function runCommandOutput(command, args) {
     return new Promise((resolve, reject) => {
-        const child = spawn(command, args, { shell: process.platform === "win32" });
+        const child = spawn(command, args, { shell: process.platform === "win32", env: createInstallEnv() });
         let stdout = "";
         let stderr = "";
         child.stdout?.on("data", (chunk) => { stdout += chunk.toString("utf8"); });
@@ -404,6 +415,12 @@ function runCommandOutput(command, args) {
         });
     });
 }
+function createInstallEnv() {
+    return {
+        ...process.env,
+        CI: process.env.CI ?? "true",
+    };
+}
 function renderBanner() {
     return [
         "   ___       ___       ___       ___       ___       ___       ___       ___       ___       ___   ",

package/dist/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.3",
+  "version": "0.0.4",
   "commands": [
     "addComment",
     "addLabels",

package/dist/tools/transfer.js

@@ -171,10 +171,9 @@ function applyMermaidImageMacros(body, generatedFiles, uploadedAttachments) {
     for (let index = 0; index < generatedFiles.length; index += 1) {
         const generated = generatedFiles[index];
         const uploaded = uploadedAttachments[index];
-        const attachment = readUploadedAttachment(uploaded?.result);
-        if (!attachment)
-            continue;
-        const macro = buildImageMacro(attachment.title ?? generated.attachmentName);
+        const attachment = readUploadedAttachment(uploaded?.result, generated.attachmentName);
+        const filename = attachment?.title ?? generated.attachmentName;
+        const macro = buildImageMacro(filename);
         output = output.replaceAll(`<p>${generated.marker}</p>`, macro).replaceAll(generated.marker, macro);
     }
     return output;
@@ -182,11 +181,17 @@ function applyMermaidImageMacros(body, generatedFiles, uploadedAttachments) {
 function buildImageMacro(filename) {
     return `<ac:image><ri:attachment ri:filename="${escapeXml(filename)}" /></ac:image>`;
 }
-function readUploadedAttachment(value) {
+function readUploadedAttachment(value, expectedTitle) {
     if (typeof value !== "object" || value === null)
         return undefined;
     if ("results" in value && Array.isArray(value.results)) {
-        return value.results?.[0];
+        const list = value.results ?? [];
+        if (expectedTitle) {
+            const matched = list.find((entry) => entry?.title === expectedTitle);
+            if (matched)
+                return matched;
+        }
+        return list[0];
     }
     if ("id" in value)
         return value;
@@ -377,29 +382,29 @@ 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 mmdc = resolveMmdcBin();
+    const mmdCli = resolveMmdCliBin();
     const args = ["-i", inputFile, "-o", outputFile, "-b", "transparent"];
     if (renderKind === "png") {
-        args.push("--scale", "3");
+        args.push("-s", "3");
     }
     try {
-        execFileSync(mmdc, args, { stdio: "pipe" });
+        execFileSync(mmdCli, args, { stdio: "pipe" });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to render Mermaid as ${renderKind} with mermaid-cli: ${message}`);
+        throw new Error(`Failed to render Mermaid as ${renderKind} with mmd-cli: ${message}`);
     }
 }
-function resolveMmdcBin() {
-    const extension = process.platform === "win32" ? ".cmd" : "";
+function resolveMmdCliBin() {
+    const extension = process.platform === "win32" ? ".exe" : "";
     const candidates = [
-        join(process.cwd(), "node_modules", ".bin", `mmdc${extension}`),
-        join(dirname(process.argv[1] ?? process.cwd()), "..", "node_modules", ".bin", `mmdc${extension}`),
+        join(process.env.HOME ?? "", ".local", "bin", `mmd-cli${extension}`),
+        "/usr/local/bin/mmd-cli",
     ];
     const found = candidates.find((candidate) => existsSync(candidate));
     if (found)
         return found;
-    return `mmdc${extension}`;
+    return `mmd-cli${extension}`;
 }
 function safeFileName(value) {
     return value.replace(/[\\/:*?"<>|]/g, "_");

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglab/confluence-cli",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Confluence REST CLI for agents and local automation",
   "repository": {
     "type": "git",
@@ -38,7 +38,6 @@
     "prepare": "node scripts/prepare.mjs"
   },
   "dependencies": {
-    "@mermaid-js/mermaid-cli": "^11.15.0",
     "@whitebite/diagram-converter": "^0.2.0",
     "axios": "^1.7.9",
     "marked": "^18.0.5",

package/skills/confluence-cli/SKILL.md

@@ -1,63 +0,0 @@
----
-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

@@ -1,36 +0,0 @@
-# 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

@@ -1,41 +0,0 @@
-# 命令速查
-
-## 基础
-
-```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

@@ -1,23 +0,0 @@
-# 内容操作
-
-## 查询页面
-
-```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

@@ -1,23 +0,0 @@
-# 总览
-
-## 这个 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

@@ -1,19 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
-# 发布与下载
-
-## 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
-```