# confluence-skill

**Repository Path**: wufeifei_admin/confluence-skill

## Basic Information

- **Project Name**: confluence-skill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Confluence Skill

查询、创建、更新 Confluence Wiki 页面，管理表格、评论、附件和标签。

## 安装位置

**用户级安装（全局）**：
```
~/.qoder/skills/confluence-skill/          # Qoder
~/.cursor/skills/confluence-skill/         # Cursor
~/.vscode/extensions/confluence-skill/     # VS Code
```

**项目级安装**：
```
项目根目录/.qoder/skills/confluence-skill/          # Qoder
项目根目录/.cursor/skills/confluence-skill/         # Cursor
项目根目录/.vscode/extensions/confluence-skill/     # VS Code
```

## 依赖

```bash
# 基础依赖
pip install requests

# BM25 本地索引（可选，用于快速搜索）
pip install llama-index-core llama-index-retrievers-bm25
```

## 环境变量配置

### 环境变量读取优先级

1. **项目根目录的 `.env` 文件**（强烈推荐）
   - ⚠️ **只读**：如果文件不存在，**不要创建或修改它**

2. **系统环境变量**

3. **读不到就报错**

### ⚠️ 重要规则

- ❌ **禁止创建或修改 `.env` 文件**
- ✅ 只读取已存在的 `.env` 文件

#### 方式 A：系统环境变量

```bash
# Confluence Configuration
export CONFLUENCE_URL=<confluence_url>
export CONFLUENCE_USER=<username>
export CONFLUENCE_PASSWORD=<your_password>
```

⚠️ **重要提示**：
- 敏感字段（密码等）**不要**在调用 Skill 的 `params` 中传入
- 因为明文会显示在日志和输出中，不安全
- 必须在调用前设置环境变量，Skill 会自动从环境变量读取

#### 方式 B：项目级 .env

```bash
# 项目根目录/.env
CONFLUENCE_URL=<confluence_url>
CONFLUENCE_USER=<username>
CONFLUENCE_PASSWORD=<your_password>
```

#### 环境变量说明

| 变量名 | 必填 | 说明 | 示例值 |
|--------|------|------|--------|
| `CONFLUENCE_URL` | ✅ | Confluence 服务器地址 | `<confluence_url>` |
| `CONFLUENCE_USER` | ✅ | 用户名 | `<username>` |
| `CONFLUENCE_PASSWORD` | ✅ | 密码或 API Token | `<your_password>` |
| `CONFLUENCE_SKILL_GLOBAL_CONFIG` | ❌ | 全局配置文件路径 | `~/.qoder/skills/confluence-skill/config/project.json` |
| `CONFLUENCE_SKILL_PROJECT_CONFIG` | ❌ | 项目配置文件路径 | `项目/.qoder/skills/confluence-skill/config/project.json` |

#### 参数获取规则

**优先级顺序**：
1. 优先从**当前对话**获取参数值
2. 其次从**配置文件** (project.json) 读取参数定义和默认值
3. **禁止使用历史记忆**中的参数值

**重要规则**：

1. ❌ **禁止传入配置中不存在的参数**

2. ✅ **必填参数必须从对话获取**
   - 只能从当前对话中获取，不能使用默认值
   - ⚠️ **如果必填参数未提供，Skill 会报错并终止任务**

3. ✅ **非必填参数可以使用默认值**

## 功能列表

| 功能 | 说明 |
|------|------|
| `search_pages` | 搜索页面 |
| `get_page` | 获取页面详情 |
| `get_page_by_title` | 通过标题查找页面 |
| `create_page` | 创建新页面 |
| `update_page` | 更新页面内容 |
| `update_table_cell` | 更新表格单元格 |
| `add_comment` | 添加评论 |
| `get_comments` | 获取评论列表 |
| `upload_attachment` | 上传附件 |
| `get_attachments` | 获取附件列表 |
| `add_labels` | 添加标签 |
| `get_labels` | 获取标签列表 |
| `list_spaces` | 列出所有空间 |
| `delete_page` | 删除页面 |
| `get_space_pages` | 获取空间页面树结构 |
| `get_page_children` | 获取页面的子页面 |
| `get_page_ancestors` | 获取页面的祖先页面 |
| `get_space_activity` | 获取空间最近活动 |

## 使用示例

### 搜索页面

```python
import os
import sys

os.environ['CONFLUENCE_URL'] = '<confluence_url>'
os.environ['CONFLUENCE_USER'] = '<username>'
os.environ['CONFLUENCE_PASSWORD'] = '<your_password>'
os.environ['CONFLUENCE_SKILL_GLOBAL_CONFIG'] = '<user_home>/.qoder/skills/confluence-skill/config/project.json'

sys.path.insert(0, '<user_home>/.qoder/skills/confluence-skill/scripts')
import main

result = main.search_pages({
    "query": "部署流程",
    "space_key": "SDK"
})
```

### 获取页面详情

```python
result = main.get_page({
    "page_id": "123456"
})
```

### 创建新页面

```python
result = main.create_page({
    "space_key": "SDK",
    "title": "新项目文档",
    "body": "<p>内容</p>"
})
```

### 更新页面

```python
result = main.update_page({
    "page_id": "123456",
    "body": "<p>更新后的内容</p>"
})
```

### 添加评论

```python
result = main.add_comment({
    "page_id": "123456",
    "body": "这个文档需要更新"
})
```

### 上传附件

```python
result = main.upload_attachment({
    "page_id": "123456",
    "file_path": "/path/to/file.pdf"
})
```

### 添加标签

```python
result = main.add_labels({
    "page_id": "123456",
    "labels": ["周报", "计划"]
})
```

### BM25 本地索引搜索（快速搜索）

```python
# 1. 首次构建索引（索引所有空间）
result = main.build_bm25_index({})

# 2. 使用 BM25 搜索（毫秒级响应）
result = main.search_pages_bm25({
    "query": "部署流程",
    "space_key": "SDK",
    "limit": 10
})

# 3. 或者使用智能搜索（自动降级到 CQL）
result = main.search_pages_smart({
    "query": "部署流程"
})

# 4. 查看索引状态
result = main.get_index_status({})

# 5. 刷新索引（定期更新）
result = main.refresh_bm25_index({})
```