npm package: @fleetsnowfluff/confluence-cli
Description: An Agent-Native Confluence CLI designed for AI Agents
Author: fleetsnowfluff
Latest version: 1.2.16

<p align="center">
  <strong>@fleetsnowfluff/confluence-cli</strong><br>
  专为 AI Agent 设计的 Confluence 命令行工具 — AI 优先，人类可用
</p>

<p align="center">
  <code>npm i -g @fleetsnowfluff/confluence-cli</code>
</p>

---

## 为什么造这个轮子

大多数 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

---

## 安装

### 交互式安装（推荐）

```bash
npx @fleetsnowfluff/confluence-cli@latest
```

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

### 手动安装

```bash
npm install -g @fleetsnowfluff/confluence-cli
```

提供两个可执行命令：
- `confluence` — 短命令
- `confluence-cli` — 完整命令

### 卸载

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

---

## 配置

### 交互式（推荐）

```bash
confluence init
```

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

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

```bash
confluence init \
  --domain "company.atlassian.net" \
  --api-path "/wiki/rest/api" \
  --auth-type "basic" \
  --email "user@example.com" \
  --token "YOUR_API_TOKEN"
```

### 环境变量

```bash
export CONFLUENCE_DOMAIN="company.atlassian.net"
export CONFLUENCE_API_TOKEN="YOUR_API_TOKEN"
export CONFLUENCE_EMAIL="user@example.com"
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 `![]()` 双向转换，完整保真：

```bash
# 读取 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` | **否** | **否** | **否** | **否** |

```bash
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 进行高级搜索：
   ```bash
   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](./CHANGELOG.md)。

---

## 开发

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

---

## 许可证

[MIT](./LICENSE)