@cloudglab/confluence-cli 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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

@@ -25,6 +25,11 @@ pnpm release:smoke-query --dry-run
 
 `mmd-cli` 运行时仍需要系统已有 Chrome/Chromium；如果机器完全没有浏览器，可在上传时传 `--mermaid none`，保留 Mermaid 代码块。
 
+从 `0.0.5` 起，`install` / `update` 在以下两种情况会**继续完成安装**而不是中断：
+
+- `mmd-cli` 官方安装脚本因网络问题失败时，会打印 `已跳过 mmd-cli 安装：<原因>` 与 `后续如需 Mermaid 图片渲染，可稍后重试安装，或在上传时传 --mermaid none 保留代码块。`。
+- 全局包内 `skills/confluence-cli` 缺失时，会打印 `未找到已安装包内的 Confluence skill：<path>，正在自动回退到 npm 包解压安装...` 并自动用 `npm pack` + `tar` + `npx -y skills add` 完成 skill 安装，无需手动切换 `--skill-source npm`。
+
 安装/更新入口：
 
 ```bash

package/dist/install.js

@@ -246,7 +246,14 @@ async function installGlobalCli(action) {
     }
 }
 async function installMmdCli(action) {
-    await runStep(`${action} Mermaid 原生渲染器 mmd-cli`, "sh", ["-c", `curl -fsSL ${MMD_CLI_INSTALL_URL} | sh`]);
+    try {
+        await runStep(`${action} Mermaid 原生渲染器 mmd-cli`, "sh", ["-c", `curl -fsSL ${MMD_CLI_INSTALL_URL} | sh`]);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(`已跳过 mmd-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));
 }

package/dist/manifest.json

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

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglab/confluence-cli",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Confluence REST CLI for agents and local automation",
   "repository": {
     "type": "git",

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
+```