为什么造这个轮子

大多数 Confluence CLI 是为人类设计的。这个是为 AI Agent 设计的 — Claude、GPT、Gemini — 以编程方式读取、写入和管理 Confluence 页面。

核心特性：

• Markdown 优先 — 用 Markdown 写，CLI 自动转成 Confluence Storage Format
• 图片双向转换 — ac:image ↔ ![]()，支持尺寸、view-file 宏、外部 URL
• 大文件转换提速 97% — 移除无操作正则；1MB 文件从 ~348ms 降到 ~9ms
• 结构化附件命令 — confluence attachment list|upload|download|delete
• 三种访问模式 — read-only / allow-edit / full 安全管控
• 双语支持 — 自动检测系统语言（zh / en），可通过 --lang 覆盖
• 多运行时注册 — 自动注册 skill 到 Claude Code、Cursor、Gemini CLI、OpenCode、Codex CLI

安装

交互式安装（推荐）

npx @fleetsnowfluff/confluence-cli@latest

引导式安装将自动：

1. 全局安装 CLI
2. 检测已安装的 AI 运行时并注册 skill
3. 引导完成 Confluence 配置（confluence init）

手动安装

npm install -g @fleetsnowfluff/confluence-cli

提供两个可执行命令：

• confluence — 短命令
• confluence-cli — 完整命令

卸载

npx @fleetsnowfluff/confluence-cli@latest --uninstall

配置

交互式（推荐）

confluence init

向导会引导你完成域名、认证和模式配置。

命令行参数（CI/CD 和 Agent 使用）

confluence init \
  --domain "company.atlassian.net" \
  --api-path "/wiki/rest/api" \
  --auth-type "basic" \
  --email "[email protected]" \
  --token "YOUR_API_TOKEN"

环境变量

export CONFLUENCE_DOMAIN="company.atlassian.net"
export CONFLUENCE_API_TOKEN="YOUR_API_TOKEN"
export CONFLUENCE_EMAIL="[email protected]"
export CONFLUENCE_MODE="allow-edit"  # full | allow-edit | read-only

命令参考

页面操作

| 命令 | 说明 | |------|------| | confluence read <id> | 读取页面内容（--format markdown\|html\|text） | | confluence info <id> | 页面元数据（标题、空间、版本、链接） | | confluence find "<title>" | 按标题查找页面（--space KEY） | | confluence search "<query>" | 全文搜索（--cql "...", --limit N） | | confluence children <id> | 子页面列表（--recursive, --format tree） | | confluence spaces | 列出所有空间 |

内容编辑

| 命令 | 说明 | |------|------| | confluence create "<title>" SPACE --content "..." --format markdown | 创建页面 | | confluence create-child "<title>" <parentId> --file ./doc.md | 创建子页面 | | confluence update <id> --file ./doc.md --format markdown | 更新页面 | | confluence move <id> <newParentId> | 移动页面 | | confluence delete <id> | 删除页面（需确认） | | confluence copy-tree <src> <dst> "Title" | 复制整个页面树 | | confluence edit <id> --output ./edit.xml | 导出用于往返编辑 |

附件

| 命令 | 说明 | |------|------| | confluence attachment list <id> | 列出附件 | | confluence attachment upload <id> --file ./img.png | 上传附件（支持多个 --file） | | confluence attachment download <id> --dest ./dl/ | 下载全部或 --pattern "*.png" | | confluence attachment delete <id> <attId> | 删除附件 |

旧命令（attachments、attachment-upload、attachment-delete）仍可用，会显示废弃警告。

其他

| 命令 | 说明 | |------|------| | confluence comments <id> | 列出评论（--location inline） | | confluence comment <id> --content "..." | 创建评论 | | confluence property-set <id> key --value '{}' | 设置内容属性 | | confluence export <id> --dest ./out/ | 导出页面 + 附件 | | confluence stats | 使用统计 | | confluence profile list\|use\|add | 多配置管理 | | confluence log list | 命令历史 | | confluence log stats | 历史统计 | | confluence log export <path> | 导出历史 |

图片转换

CLI 支持 Confluence <ac:image> ↔ Markdown ![]() 双向转换，完整保真：

# 读取 Confluence 页面 → 带正确图片语法的 Markdown
confluence read 123456 --format markdown

# 上传带图片的 Markdown → Confluence Storage Format
confluence update 123456 --file ./page.md --format markdown

支持的模式：

| Confluence | Markdown | |------------|----------| | <ac:image><ri:attachment ri:filename="img.png"/></ac:image> | ![](img.png) | | <ac:image><ri:url ri:value="https://..."/></ac:image> | ![](https://...) | | <ac:image ac:width="400" ac:height="300"> | ![](img.png) {width=400 height=300} | | <ac:structured-macro ac:name="view-file">（图片） | ![](path) |

访问模式

控制允许的操作 — 对自主运行的 AI Agent 尤为重要。

| 模式 | 创建 | 更新 | 删除 | 导出 | |------|------|------|------|------| | full | 是 | 是 | 是 | 是 | | allow-edit | 是 | 是 | 否 | 否 | | read-only | 否 | 否 | 否 | 否 |

confluence init --mode allow-edit
export CONFLUENCE_MODE=read-only

AI Agent 集成

支持的运行时

安装器自动注册 skill、agent 和 command 到以下 AI 工具：

| 运行时 | 注册路径 | |--------|----------| | Claude Code | ~/.claude/skills/confluence/、~/.claude/agents/、~/.claude/commands/confluence/ | | Cursor | ~/.cursor/skills/confluence/ | | Gemini CLI | ~/.gemini/instructions/confluence.md | | OpenCode | ~/.config/opencode/commands/confluence.md | | Codex CLI | ~/.codex/instructions/confluence.md |

Slash 命令（Claude Code）

| 命令 | 说明 | |------|------| | /confluence:init-profile | 初始化用户画像，探索空间、发现同事关系、识别周期性工作模式 | | /confluence:summary | 生成工作总结报告（支持日/周/月/季/年），输出 .md 和可选 .html |

Agent 使用要点

1. 所有创建/更新操作使用 --format markdown
2. 脚本中使用 --yes 跳过交互式确认
3. 破坏性操作（delete、attachment delete、export）需要 full 模式
4. 使用 CQL 进行高级搜索：

   confluence search --cql "type=page AND creator = '<账号>' ORDER BY created DESC"

5. 错误输出到 stderr，正常输出到 stdout — 可安全管道

双语支持

安装器自动检测系统语言并安装对应语言包：

| 语言 | 代码 | 状态 | |------|------|------| | 英文 | en | 默认，完整翻译 | | 中文 | zh | 完整翻译 |

检测优先级：

1. CONFLUENCE_LANG 环境变量（如 CONFLUENCE_LANG=zh）
2. --lang= 参数（如 npx @fleetsnowfluff/confluence-cli@latest --lang=en）
3. Intl.DateTimeFormat().resolvedOptions().locale
4. LANG / LC_ALL 环境变量
5. 默认：en

更新日志

详见 CHANGELOG.md。

开发

git clone https://github.com/pchuri/confluence-cli.git
npm install
npm test
npm start -- --help

许可证

MIT