atlassian-readonly-skills

Atlassian 只读技能

用于集成 Jira、Confluence 和 Bitbucket 的只读 Python 工具，支持 Cloud 和 Data Center 部署。

注意：这是一个只读版本，不包含任何写入操作（创建、更新、删除）。如需使用包括写入操作在内的完整功能，请使用 atlassian-skills。

配置

支持两种配置模式：

模式 1：环境变量（传统方式）

根据部署类型设置环境变量。当未向技能函数提供 credentials 参数时，将使用此模式。

Cloud（API 令牌）

# Jira Cloud
JIRA_URL=https://your-company.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token

# Confluence Cloud
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
[email protected]
CONFLUENCE_API_TOKEN=your_api_token

在此生成 API 令牌：https://id.atlassian.com/manage-profile/security/api-tokens

Data Center / Server（PAT 令牌）

# Jira Data Center
JIRA_URL=https://jira.your-company.com
JIRA_PAT_TOKEN=your_pat_token

# Confluence Data Center
CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PAT_TOKEN=your_pat_token

# Bitbucket Server/Data Center
BITBUCKET_URL=https://bitbucket.your-company.com
BITBUCKET_PAT_TOKEN=your_pat_token

注意：如果同时提供 PAT 令牌和 API 令牌，则优先使用 PAT 令牌。

模式 2：基于参数（Agent 环境）

在无法使用环境变量的 Agent 环境中部署技能时，可使用 AtlassianCredentials 对象直接向技能函数传递凭据。

from scripts._common import AtlassianCredentials, check_available_skills
from scripts.jira_issues import jira_get_issue

# Create credentials object
credentials = AtlassianCredentials(
    # Jira configuration
    jira_url="https://your-company.atlassian.net",
    jira_username="[email protected]",
    jira_api_token="your_api_token",
    
    # Confluence configuration (optional)
    confluence_url="https://your-company.atlassian.net/wiki",
    confluence_username="[email protected]",
    confluence_api_token="your_api_token",
    
    # Bitbucket configuration (optional)
    # bitbucket_url="https://bitbucket.your-company.com",
    # bitbucket_pat_token="your_pat_token"
)

# Check which services are available
availability = check_available_skills(credentials)
print(availability["available_services"])  # ["jira", "confluence"]
print(availability["unavailable_services"])  # {"bitbucket": "Missing bitbucket_url"}

# Use skills with credentials parameter
result = jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials  # Pass credentials here
)

部分服务配置

你可以只配置所需的服务。凭据不完整的服务将不可用：

# Only configure Jira
credentials = AtlassianCredentials(
    jira_url="https://your-company.atlassian.net",
    jira_username="[email protected]",
    jira_api_token="your_api_token"
)

# Jira skills will work
jira_get_issue("PROJ-123", credentials=credentials)  # ✓ Works

# Confluence/Bitbucket skills will fail with ConfigurationError
confluence_get_page("Page Title", "SPACE", credentials=credentials)  # ✗ Fails

有关凭据对象字段和身份验证选项，请参阅 atlassian-skills 中的完整文档。

核心工作流

使用环境变量

from scripts.jira_issues import jira_get_issue
from scripts.jira_search import jira_search
from scripts.confluence_pages import confluence_get_page
import json

# 1. Get a Jira issue
result = jira_get_issue(issue_key="PROJ-123")
issue = json.loads(result)
print(f"Issue: {issue['key']} - {issue['summary']}")

# 2. Search for issues
result = jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50
)
issues = json.loads(result)

# 3. Get a Confluence page
result = confluence_get_page(title="Feature Documentation", space_key="DEV")
page = json.loads(result)
print(f"Page: {page['title']}")

使用凭据参数（Agent 模式）

from scripts._common import AtlassianCredentials
from scripts.jira_issues import jira_get_issue
from scripts.jira_search import jira_search
from scripts.confluence_pages import confluence_get_page
import json

# Create credentials
credentials = AtlassianCredentials(
    jira_url="https://company.atlassian.net",
    jira_username="[email protected]",
    jira_api_token="token123",
    confluence_url="https://company.atlassian.net/wiki",
    confluence_username="[email protected]",
    confluence_api_token="token123"
)

# 1. Get a Jira issue with credentials
result = jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials
)
issue = json.loads(result)

# 2. Search for issues with credentials
result = jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50,
    credentials=credentials
)

# 3. Get a Confluence page with credentials
result = confluence_get_page(
    title="Feature Documentation",
    space_key="DEV",
    credentials=credentials
)

可用工具

Jira 工单管理（scripts.jira_issues）

from scripts.jira_issues import jira_get_issue

# Get issue by key
jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials  # Optional
)

Jira 搜索（scripts.jira_search）

from scripts.jira_search import jira_search, jira_search_fields

# Search with JQL
jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50
)

# Find field definitions
jira_search_fields(keyword="custom")

Jira 工作流（scripts.jira_workflow）

from scripts.jira_workflow import jira_get_transitions

# Get available transitions for an issue
jira_get_transitions(issue_key="PROJ-123")

Jira 敏捷开发（scripts.jira_agile）

from scripts.jira_agile import (
    jira_get_agile_boards,
    jira_get_board_issues,
    jira_get_sprints_from_board,
    jira_get_sprint_issues
)

# Get boards
jira_get_agile_boards(project_key="PROJ")

# Get issues on a board
jira_get_board_issues(board_id=1, jql="status = 'In Progress'")

# Get sprints from a board
jira_get_sprints_from_board(board_id=1, state="active")

# Get issues in a sprint
jira_get_sprint_issues(sprint_id=42)

Jira 链接（scripts.jira_links）

from scripts.jira_links import jira_get_link_types

# Get available link types
jira_get_link_types()

Jira 工时记录（scripts.jira_worklog）

from scripts.jira_worklog import jira_get_worklog

# Get worklog entries for an issue
jira_get_worklog(issue_key="PROJ-123")

Jira 项目（scripts.jira_projects）

from scripts.jira_projects import (
    jira_get_all_projects,
    jira_get_project_issues,
    jira_get_project_versions
)

# Get all projects
jira_get_all_projects()

# Get issues in a project
jira_get_project_issues(project_key="PROJ", limit=100)

# Get project versions
jira_get_project_versions(project_key="PROJ")

Jira 用户（scripts.jira_users）

from scripts.jira_users import jira_get_user_profile

# Get user profile
jira_get_user_profile(user_identifier="[email protected]")

Confluence 页面（scripts.confluence_pages）

from scripts.confluence_pages import confluence_get_page

# Get page by title
confluence_get_page(title="Meeting Notes", space_key="TEAM")

# Get page by ID
confluence_get_page(page_id="12345")

Confluence 搜索（scripts.confluence_search）

from scripts.confluence_search import confluence_search

# Search with CQL
confluence_search(
    query="space = DEV AND type = page AND text ~ 'API'",
    limit=25
)

Confluence 评论（scripts.confluence_comments）

from scripts.confluence_comments import confluence_get_comments

# Get comments on a page
confluence_get_comments(page_id="12345")

Confluence 标签（scripts.confluence_labels）

from scripts.confluence_labels import confluence_get_labels

# Get labels on a page
confluence_get_labels(page_id="12345")

Bitbucket 项目（scripts.bitbucket_projects）

from scripts.bitbucket_projects import (
    bitbucket_list_projects,
    bitbucket_list_repositories
)

# List all projects
bitbucket_list_projects(limit=25)

# List repositories in a project
bitbucket_list_repositories(project_key="PROJ", limit=50)

Bitbucket 拉取请求（scripts.bitbucket_pull_requests）

from scripts.bitbucket_pull_requests import (
    bitbucket_get_pull_request,
    bitbucket_get_pr_diff
)

# Get PR details
bitbucket_get_pull_request(
    project_key="PROJ",
    repository_slug="my-repo",
    pr_id=123
)

# Get PR diff
bitbucket_get_pr_diff(
    project_key="PROJ",
    repository_slug="my-repo",
    pr_id=123
)

Bitbucket 文件与搜索（scripts.bitbucket_files）

from scripts.bitbucket_files import (
    bitbucket_get_file_content,
    bitbucket_search
)

# Get file content
bitbucket_get_file_content(
    project_key="PROJ",
    repository_slug="my-repo",
    file_path="src/main.py",
    branch="develop"
)

# Search code
bitbucket_search(
    query="def authenticate",
    project_key="PROJ",
    search_type="code",
    limit=25
)

Bitbucket 提交（scripts.bitbucket_commits）

from scripts.bitbucket_commits import (
    bitbucket_get_commits,
    bitbucket_get_commit
)

# Get recent commits from a branch
bitbucket_get_commits(
    project_key="PROJ",
    repository_slug="my-repo",
    branch="master",
    limit=10
)

# Get details of a specific commit
bitbucket_get_commit(
    project_key="PROJ",
    repository_slug="my-repo",
    commit_id="1da11eaec25aed8b251de24841885c91493b3173"
)

响应数据结构

所有函数均返回包含扁平化数据结构的 JSON 字符串（而非嵌套的 API 响应）。

Jira 工单结构

{
  "key": "PROJ-123",
  "id": "10001",
  "summary": "Issue title",
  "description": "Issue description",
  "status": "In Progress",
  "issue_type": "Task",
  "priority": "High",
  "assignee": "[email protected]",
  "reporter": "[email protected]",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-16T14:20:00.000+0000",
  "labels": ["backend", "urgent"],
  "components": ["API", "Auth"],
  "custom_fields": {}
}

Confluence 页面结构

{
  "id": "12345",
  "title": "Page Title",
  "space_key": "DEV",
  "status": "current",
  "created": "2024-01-15T10:30:00.000Z",
  "updated": "2024-01-16T14:20:00.000Z",
  "author": "[email protected]",
  "version": 3,
  "url": "https://company.atlassian.net/wiki/spaces/DEV/pages/12345"
}

注意：这些是简化后的结构。原始 Jira API 会返回嵌套数据，例如 {"key": "...", "fields": {"summary": "...", "status": {"name": "..."}}}，而此技能会将其扁平化，以便于使用。

错误处理

所有函数均返回 JSON 字符串。请检查是否存在错误：

import json

result = jira_get_issue(issue_key="PROJ-999")
data = json.loads(result)

if not data.get("success", True):
    print(f"Error: {data['error']}")
    print(f"Type: {data['error_type']}")
else:
    print(f"Issue: {data['key']}")

错误类型

• ConfigurationError - 缺少环境变量
• AuthenticationError - 凭据无效
• ValidationError - 输入参数无效
• NotFoundError - 未找到资源
• APIError - Atlassian API 错误
• NetworkError - 连接问题

设计理念

此技能提供：

• 只读访问：查询和检索数据，不进行修改
• 令牌效率：通过排除写入操作，减少上下文大小
• 安全性：防止意外修改数据
• 灵活性：支持 Cloud 和 Data Center 部署
• 一致性：统一的错误处理和响应格式

此技能不提供：

• 写入操作（创建、更新、删除）
• 直接 API 访问（请改用提供的函数）
• Webhook 处理或事件处理
• 批量导入/导出操作

最佳实践：

• 始终检查返回值中是否存在错误
• 使用 JQL/CQL 进行高效搜索
• 如需执行写入操作，请使用完整的 atlassian-skills 包

依赖项

pip install requests python-dotenv

或者使用 requirements 文件：

pip install -r requirements.txt