confluence

Confluence

与 Confluence 交互，搜索和查看内容，并管理空间。

创建/更新内容？ 有关使用 Markdown 创建和更新页面，请参阅 references/creating-content.md。

网络访问

Confluence API 命令需要通过 HTTPS 访问已配置的 Confluence 主机。远程操作需要出站网络访问。如果 Agent 环境对此有限制，请在执行第一个远程命令前，通过该环境的审批或网络控制获取访问权限，并重复使用已授予的授权。本地帮助和文件处理不需要网络访问。技能说明不会授予网络权限。请将 DNS、连接和超时故障报告为网络错误；不要通过重置凭据来解决这些问题。如果获批的访问仍然失败，请停止操作并报告问题。身份验证和权限错误需要用户处理。

解析脚本路径

示例中的 SKILL_DIR 是当前加载的 SKILL.md 所在目录。 运行命令前，将其设为该目录的绝对路径；不要假定 Agent 会设置此 shell 变量。如果脚本路径包含空格，请将其括起来。

安装

依赖项：pip install --user requests keyring pyyaml

设置验证

安装后，运行以下命令验证技能配置：

$SKILL_DIR/scripts/confluence.py check

此命令将检查：

• Python 依赖项（requests、keyring、pyyaml）
• 身份验证配置
• 与 Confluence 的连接

如果有任何缺失，检查命令会提供设置说明。

身份验证

使用以下任一方法配置 Confluence 身份验证：

选项 1：环境变量（推荐）

export CONFLUENCE_URL="https://yourcompany.atlassian.net/wiki"
export CONFLUENCE_EMAIL="[email protected]"
export CONFLUENCE_API_TOKEN="your-token"

将这些内容添加到 ~/.bashrc 或 ~/.zshrc，以便持久保存。

选项 2：配置文件

创建 ~/.config/agent-skills/confluence.yaml：

url: https://yourcompany.atlassian.net/wiki
email: [email protected]
token: your-token

必需凭据

• URL：你的 Confluence Cloud URL（例如 https://yourcompany.atlassian.net/wiki）
• 电子邮件：你的 Atlassian 账户电子邮件
• API 令牌：在 https://id.atlassian.com/manage-profile/security/api-tokens 创建

配置默认值

可选：在 ~/.config/agent-skills/confluence.yaml 中配置默认值：

url: https://yourcompany.atlassian.net/wiki
email: [email protected]
token: your-token
defaults:
  cql_scope: "space = DEMO"
  max_results: 25
  default_space: "DEMO"

查看配置：$SKILL_DIR/scripts/confluence.py config show

命令

有关每个命令的读/写分类，请参阅 permissions.md。

check

有关依赖项、身份验证和连接检查，请参阅设置验证。

search

使用 CQL（Confluence 查询语言）搜索内容。

# Basic search
$SKILL_DIR/scripts/confluence.py search "type=page AND space = DEMO"
$SKILL_DIR/scripts/confluence.py search "title~login" --space DEMO

# Filter by type
$SKILL_DIR/scripts/confluence.py search "space = DEMO" --type page

# Limit results
$SKILL_DIR/scripts/confluence.py search "type=page" --max-results 10

参数：

• cql：CQL 查询字符串（必需）
• --max-results：结果数量上限（默认值：50）
• --type：内容类型筛选条件（page、blogpost、comment）
• --space：限定在特定空间中搜索

另请参阅：CQL 参考，了解查询语法

page get

按 ID 或标题获取页面内容。

# Get by title (returns Markdown by default)
$SKILL_DIR/scripts/confluence.py page get "My Page Title"

# Get by ID
$SKILL_DIR/scripts/confluence.py page get 123456

# Get without body content
$SKILL_DIR/scripts/confluence.py page get "My Page" --no-body

# Get in original format (not Markdown)
$SKILL_DIR/scripts/confluence.py page get "My Page" --raw

# Save to file with images downloaded to sibling directory
$SKILL_DIR/scripts/confluence.py page get "My Page" -o my-page.md

# Export with YAML frontmatter (for round-tripping)
$SKILL_DIR/scripts/confluence.py page get 123456 --frontmatter -o page.md

输出：页面元数据和 Markdown 格式的内容。使用 --output/-o 时，图片会下载到同级目录。

参数：

• page_identifier：页面 ID 或标题（必需）
• --markdown：以 Markdown 格式输出正文（默认值）
• --raw：以原始格式输出
• --no-body：不包含正文内容
• --frontmatter：以带有 YAML frontmatter（标题、空间、标签、父页面）的 Markdown 格式输出，以便与 page create/page update 配合进行往返处理
• --output/-o：将输出写入文件；图片会下载到同级目录，该目录以文件名（不含扩展名）命名

page history

显示页面的版本历史记录。

# By title
$SKILL_DIR/scripts/confluence.py page history "My Page Title"

# By ID, limit results
$SKILL_DIR/scripts/confluence.py page history 123456 --max-results 10

参数：

• page_identifier：页面 ID 或标题（必需）
• --max-results：返回的版本数量上限（默认值：25）

page create / update

创建或更新页面时，请阅读 references/creating-content.md，了解 Markdown、图片、frontmatter、目录和内部链接。

$SKILL_DIR/scripts/confluence.py page create --space DEMO --title "Documentation" \
  --body-file README.md
$SKILL_DIR/scripts/confluence.py page update 123456 --body-file updated.md

page move

将页面移至新的父页面下，或移至空间根目录。

# Move under a new parent
$SKILL_DIR/scripts/confluence.py page move 123456 --parent 789012

# Move to space root (no parent)
$SKILL_DIR/scripts/confluence.py page move 123456

page delete

按 ID 删除页面（在 Cloud 上会移至回收站）。

$SKILL_DIR/scripts/confluence.py page delete 123456

space

管理空间。

# List all spaces
$SKILL_DIR/scripts/confluence.py space list

# List with limit
$SKILL_DIR/scripts/confluence.py space list --max-results 10

# Filter by type
$SKILL_DIR/scripts/confluence.py space list --type global

# Get space details
$SKILL_DIR/scripts/confluence.py space get DEMO

参数：

• list：列出空间
  • --type：按类型筛选（global、personal）
  • --max-results：最大结果数
• get <space-key>：获取空间详情

有关创建空间的信息，请参阅 references/creating-content.md。

space permissions

查看、添加和移除空间权限。

# List all permissions for a space
$SKILL_DIR/scripts/confluence.py space permissions list DEMO

# Filter by subject type
$SKILL_DIR/scripts/confluence.py space permissions list DEMO --subject-type group

# Add a permission
$SKILL_DIR/scripts/confluence.py space permissions add DEMO \
  --subject-type user --subject "5a1234abc" --operation read --target space

# Remove a permission by ID
$SKILL_DIR/scripts/confluence.py space permissions remove DEMO --id 2154

参数：

• list <space-key>：列出权限
  • --subject-type：按用户或组筛选
• add <space-key>：添加权限
  • --subject-type：user 或 group（必填）
  • --subject：用户账户 ID 或组名称/ID（必填）
  • --operation：read、create、delete、export、administer、archive、restrict_content（必填）
  • --target：space、page、blogpost、comment、attachment（必填）
• remove <space-key>：移除权限
  • --id：权限 ID（必填）

config

显示配置和默认值。

# Show all configuration
$SKILL_DIR/scripts/confluence.py config show

# Show space-specific defaults
$SKILL_DIR/scripts/confluence.py config show --space DEMO

此处会显示：

• 身份验证设置（令牌已遮蔽）
• 默认 CQL 范围、最大结果数和默认空间
• 特定空间的父页面和标签默认值

CQL 参考

完整的 CQL 语法请参阅 Confluence CQL 文档。

常见模式：type=page、space=KEY、title~text、text~keyword、created >= now("-7d")、label=name。

使用 AND、OR 和 ORDER BY 组合：

$SKILL_DIR/scripts/confluence.py search "type=page AND space=DEMO ORDER BY created DESC"

示例

常见读取操作请参阅 search、page get 和 space 下的示例。有关页面创建、更新和批量工作流，请参阅 创建内容。

模型指南

此技能会调用需要结构化输入/输出的 API。建议使用具备标准能力的模型。