1. 项目概述与核心价值
如果你是一名开发者或项目经理，每天在Jira和Confluence之间来回切换，手动创建工单、更新状态、搜索文档，那么你肯定想过：能不能让我的AI助手帮我干这些活？今天要聊的这个开源项目atlassian-skill，就是专门为解决这个痛点而生的。简单来说，它是一个桥梁，让你能通过命令行，或者更酷的是，直接让你正在用的AI编程助手（比如Claude Code、Cursor）去操作你公司的Jira和Confluence。想象一下，你只需要在编辑器里对AI说一句“帮我把DEV-123这个bug的状态改成‘修复中’”，或者“在Confluence的‘开发文档’空间里新建一个页面，标题是‘新部署流程’”，它就能自动帮你完成，这能省下多少机械操作的时间。
这个项目的核心价值在于“集成”与“自动化”。它不是一个简单的API封装，而是深度适配了当前主流的AI辅助编程生态。通过支持MCP（Model Context Protocol），它能让AI助手理解Jira的工单、Confluence的页面，并像调用本地函数一样去操作它们。更贴心的是，它提供了双认证支持：既推荐使用更安全、无需管理令牌的OAuth 2.1流程，也保留了传统的API令牌方式作为备选，确保了在各种环境下的可用性。对于日常需要与Atlassian全家桶打交道的团队来说，这相当于给你的工作流装上了一台自动变速箱。
2. 核心架构与认证机制深度解析
2.1 技能（Skill）与MCP协议：AI的“手”和“眼”
要理解这个项目，首先得弄明白两个概念：Skill（技能）和MCP（Model Context Protocol）。你可以把Skill想象成给AI安装的一个“插件”或“小程序”。在没有Skill之前，AI可能知道Jira是什么，但它不知道如何连接到你公司的具体Jira实例，更不知道如何执行“搜索状态为‘打开’的bug”这样的具体操作。Skill就是赋予AI这种具体能力的模块。
而MCP，则是一种通信协议，它定义了AI模型（如Claude、Gemini）与外部工具（如这个Jira/Confluence技能）之间如何安全、结构化地交换信息。简单类比，AI是大脑，MCP是神经系统，Skill就是连接在神经末梢上的手和工具。这个项目实现了MCP服务器，因此任何兼容MCP的AI客户端都能直接“调用”它提供的Jira搜索、创建工单、读写Confluence页面等功能，就像调用一个本地函数一样自然。
2.2 双认证方案：OAuth 2.1与API令牌的抉择
认证是任何与企业系统集成工具的核心。atlassian-skill提供了两套方案，其设计考量非常值得深究。
方案一：OAuth 2.1 via MCP Server（强烈推荐）这是项目的首选方案，也是现代应用集成的趋势。它的工作流程是这样的：
- 用户在命令行运行
python scripts/auth.py login --oauth。 - 脚本会启动一个本地HTTP服务器，并打开你的默认浏览器，跳转到Atlassian的官方授权页面。
- 你登录自己的Atlassian账号，并勾选同意授权该技能访问Jira、Confluence等资源（范围可自选）。
- 授权成功后，Atlassian会将一个授权码回调到本地服务器。
- 技能后台用这个授权码，加上PKCE（Proof Key for Code Exchange）机制，去交换访问令牌（Access Token）和刷新令牌（Refresh Token）。
为什么推荐OAuth 2.1？安全性是首要原因。PKCE机制能有效防止授权码被拦截冒用。更重要的是，用户完全不需要接触或保管API令牌。令牌被安全地存储在操作系统的密钥管理器中（如macOS的Keychain、Windows的Credential Locker），并且刷新令牌机制可以实现无感续期，避免了令牌过期导致服务中断。对于需要频繁使用该技能的开发者来说，这是一劳永逸的配置。
方案二：API Token（备用方案）这种方式比较传统，适用于一些无法进行浏览器交互的环境，比如某些CI/CD流水线、无头服务器或网络受限的场景。
- 用户需要手动前往Atlassian账户安全设置页面，生成一个API令牌。
- 运行
python scripts/auth.py login，根据提示输入你的Atlassian账户邮箱和刚才生成的令牌。 - 这些凭证同样会被加密存储于系统密钥链中。
注意：API令牌的局限性API令牌本质上是一个长期有效的密码。虽然项目将其存储在密钥链中，但一旦生成，它就拥有了你账户对应的权限，直到被手动撤销。这意味着如果令牌不慎泄露（虽然概率低），风险相对较高。此外，它没有OAuth那样的细粒度权限控制和便捷的吊销方式。因此，除非环境限制，否则OAuth是更优解。
项目巧妙地实现了自动检测后端。当使用OAuth登录后，技能内部会通过MCP协议与AI客户端通信；而当使用API令牌时，它会直接调用Atlassian的REST API。这种设计对用户是透明的，你只需要关心认证方式，而不需要关心底层调用路径。
3. 环境准备与详细安装配置指南
3.1 基础环境与依赖安装
在开始使用前，你需要确保本地环境就绪。这个项目基于Python，所以Python 3.7+是必须的。建议使用虚拟环境来管理依赖，避免污染全局环境。
# 1. 克隆项目代码到本地 git clone https://github.com/sanjay3290/atlassian-skill.git cd atlassian-skill # 2. （推荐）创建并激活Python虚拟环境 python -m venv venv # 在 macOS/Linux 上： source venv/bin/activate # 在 Windows 上： venv\Scripts\activate # 3. 安装项目依赖 pip install -r requirements.txtrequirements.txt文件里通常包含了核心的HTTP客户端（如httpx或requests）、用于OAuth流的authlib、用于安全存储的keyring库，以及用于构建命令行工具的typer或click。安装过程一般很顺利。
3.2 针对不同AI客户端的技能安装
这是项目最精彩的部分之一：它提供了多种安装方式，以适应不同的AI编程助手。你需要根据自己主要使用的工具来选择。
对于 Claude Code 用户：Claude Code（或Claude Desktop）内置了技能市场。安装最为简单，几乎是一键完成。
/plugin marketplace add sanjay3290/atlassian-skill执行后，Claude Code会自动从市场拉取并配置该技能。之后，当你在聊天框中提及Jira或Confluence时，Claude就能自动建议调用相关技能。
对于 Gemini CLI、Cursor、Codex、Goose 等用户：这些工具通常通过一个名为skills的CLI工具来管理技能。安装命令同样简洁。
npx skills add sanjay3290/atlassian-skill这条命令会利用npm的npx工具，下载并运行技能管理器，将atlassian-skill添加到你的全局技能列表中。之后，在你的AI助手会话中，它就能识别出这些新能力。
实操心得：环境变量与网络问题在某些企业的网络环境下，直接使用
npx或访问GitHub可能会受限。如果安装失败，可以尝试：
- 设置npm镜像：
npm config set registry https://registry.npmmirror.com- 通过
git clone本地安装后，手动链接技能。具体方法需要参考你所使用的AI客户端的官方文档，它们通常支持从本地路径加载技能。
3.3 首次认证与连接配置
无论选择哪种安装方式，首次使用前都必须完成认证，将技能与你的Atlassian实例绑定。
执行OAuth认证（推荐）：
python scripts/auth.py login --oauth这时，你的默认浏览器会打开，并跳转到类似https://auth.atlassian.com/authorize?...的URL。请使用你拥有相应Jira/Confluence访问权限的Atlassian账号登录。在授权页面，你会看到请求的权限列表（例如：读取Jira工单、写入Confluence页面等）。仔细核对后，点击“允许”。
授权成功的关键确认：授权完成后，浏览器页面通常会显示“授权成功，你可以关闭此窗口”之类的提示。切勿在浏览器中手动关闭标签页后立即关闭命令行窗口。脚本需要一点时间来接收回调信息并完成令牌的存储。等待命令行提示“Login successful!”或类似信息后再进行下一步操作。
验证认证状态：认证完成后，强烈建议运行以下命令检查一切是否正常：
python scripts/auth.py status这个命令会从密钥链中读取存储的凭证信息并验证其有效性。如果看到你的邮箱和有效的令牌信息，说明配置成功。
备用方案：API令牌认证：如果OAuth流程失败（例如在无图形界面的服务器上），则回退到API令牌方式：
python scripts/auth.py login # 随后根据提示输入你的 Atlassian 账户邮箱和 API 令牌4. Jira技能实战：从查询到工单生命周期管理
4.1 精准搜索：掌握JQL的强大威力
搜索是使用频率最高的功能。项目将Jira强大的JQL（Jira Query Language）能力直接暴露给了命令行和AI。
基础搜索示例：
# 查找某个项目下所有未解决的Bug python scripts/jira.py search "project = DEV AND issuetype = Bug AND status != Done" # 查找指派给我自己、且优先级为高的任务 python scripts/jira.py search "assignee = currentUser() AND priority = High ORDER BY created DESC" --limit 5这里的--limit参数非常实用，可以防止一次返回过多结果，影响查看效率。
高级搜索与结果处理：JQL支持非常复杂的查询。例如，你想查找过去一周内被修改过、且包含特定标签的问题：
python scripts/jira.py search "updated >= -7d AND labels in (backend, refactor) AND text ~ \"performance\""搜索结果默认以易于阅读的表格形式输出。但如果你需要将结果导入其他工具（如脚本、监控系统），--json标志就派上用场了：
python scripts/jira.py search "project = DEV" --limit 2 --json这会输出结构化的JSON数据，包含了工单键值、摘要、状态、指派人等所有字段，便于程序化处理。
4.2 工单操作：创建、更新与流转
创建新工单：创建工单是核心的写操作。最基本的命令需要指定项目、问题类型和摘要。
python scripts/jira.py create --project WEB --summary "首页加载速度优化" --type "Task"但这只是开始。一个完整的工单通常包含更多信息：
python scripts/jira.py create \ --project DEV \ --summary "用户登录失败率异常升高" \ --type Bug \ --description "## 问题描述\n自今日上午10点起，监控显示登录接口失败率从0.1%上升至5%。\n## 影响范围\n所有移动端用户。\n## 日志片段\n`AuthenticationService: Invalid token signature...`" \ --priority Critical \ --assignee "zhangsan@company.com" \ --labels "urgent, authentication, backend"通过--description支持Markdown格式，可以直接将排查思路、错误日志写进去，创建出来的工单信息量十足。
更新工单与状态流转：工单创建后，随着处理进展，需要更新信息或改变状态。
# 更新工单描述或添加标签 python scripts/jira.py update DEV-456 --description "已定位到原因，是证书过期。" --add-labels "root-cause-found" # 将工单状态从 '待办' 流转到 '进行中' python scripts/jira.py transition DEV-456 "In Progress"注意事项：状态流转的“陷阱”
transition命令中的状态名称必须完全匹配你Jira项目中为该问题类型所定义的状态名称。大小写和空格都要一致。一个常见的错误是直接写中文状态名或英文的通用名（如“Doing”），而实际项目里可能叫“开发中”。为了避免失败，可以先使用python scripts/jira.py list-statuses WEB命令列出指定项目所有可用的状态，确认后再进行流转操作。
4.3 项目管理与信息获取
在自动化脚本中，你常常需要动态获取项目信息。
# 列出你有权限访问的所有Jira项目 python scripts/jira.py list-projects # 获取某个项目的详细信息，包括键、名称、项目类型等 python scripts/jira.py list-projects --json | jq '.[] | select(.key=="DEV")'list-projects的输出对于编写通用脚本非常有用。例如，你可以写一个脚本，定期扫描所有项目中的高优先级缺陷。
5. Confluence技能实战：知识库的自动化管理
5.1 空间与页面导航
Confluence以空间（Space）为单位组织内容。开始操作前，最好先了解整体的内容结构。
# 列出所有你有权限访问的空间 python scripts/confluence.py list-spaces # 获取某个特定空间的详细信息，如空间ID（后续操作的关键） python scripts/confluence.py get-space <space_key>list-spaces命令返回的信息中，key是空间的标识符（如DEV），而id是一个数字，在后续通过API操作页面时，经常需要用到这个id。
5.2 智能搜索：CQL与全文检索
Confluence提供了强大的CQL（Confluence Query Language）进行搜索，技能也完整支持。
使用CQL进行精确搜索：
# 搜索在‘DEV’空间中，类型为页面（非博客），且标题包含‘API’的页面 python scripts/confluence.py search "space = DEV and type = page and title ~ \"API\"" # 搜索最近一周内被修改过的页面 python scripts/confluence.py search "lastModified >= -7d order by lastModified desc"简单的全文关键词搜索：如果你记不住复杂的CQL语法，也可以直接进行关键词全文搜索，这对于快速查找非常方便。
python scripts/confluence.py search "Kubernetes部署配置"技能会在页面标题和正文内容中进行匹配，返回相关结果列表。
5.3 页面内容的读写与编排
读取页面内容：
python scripts/confluence.py read <page_id>这会获取页面的原始存储格式（通常是storage格式的HTML）。对于只是想查看内容的用户，Confluence的Web界面可能更友好。但这个功能的真正威力在于自动化。你可以编写脚本，定期读取某个状态页面，解析其中的HTML表格数据，用于生成报告或触发告警。
创建新页面：创建页面需要指定所属空间和标题，内容支持HTML。
# 在空间根目录下创建一个简单页面 python scripts/confluence.py create --title "项目复盘会议纪要-2024-Q1" --space-id 123456 --body "<h1>会议纪要</h1><p>本次会议讨论了...</p>" # 在某个现有页面下创建子页面（建立层级结构） python scripts/confluence.py create --title "详细设计方案" --space-id 123456 --body "<p>这里是设计细节...</p>" --parent-id 987654使用--parent-id参数可以很好地维护Confluence的页面树状结构，让知识库井井有条。
更新现有页面：更新操作会覆盖页面的标题和/或正文。这是一个需要谨慎对待的操作，因为它会直接替换原有内容。
python scripts/confluence.py update 987654 --title "更新后的标题" --body "<p>这是全新的内容，旧内容已消失。</p>"重要警告：更新操作的破坏性
update命令是完全替换，而非追加。如果你只是想添加内容，正确的做法是先read获取当前内容，在本地拼接好新的完整内容后，再执行update。对于重要的文档，建议在更新前通过Confluence Web界面手动创建一份副本作为备份。
查看页面层级：
# 获取某个页面的所有直接子页面 python scripts/confluence.py get-children <parent_page_id>这个功能在编写文档巡检脚本时很有用，可以递归遍历某个知识库下的所有页面。
6. 与AI助手深度集成：提升日常开发效率
6.1 在Claude Code/Cursor中直接操作
安装并配置好技能后，AI助手就从“知道概念”变成了“能办实事”。以下是一些真实的使用场景对话：
场景一：快速处理每日站会任务
- 你：“Claude，查看一下指派给我、状态是‘待办’的Jira任务，按优先级排序。”
- Claude：（调用
jira.py search技能） “找到5个任务。优先级最高的是DEV-789：‘修复支付回调超时’，需要我帮你将其状态改为‘进行中’吗？” - 你：“好的，改为进行中，并添加一条评论‘开始调查’。”
- Claude：（依次调用
transition和comment技能） “已完成。”
场景二：编写技术方案并归档
- 你：“我正在设计新的缓存策略，帮我在Confluence的‘技术架构’空间下，创建一个标题为‘Redis分布式缓存设计方案’的页面，父页面是‘缓存体系’。内容大纲先用Markdown写好给我看看。”
- Claude：（生成Markdown内容后，调用
confluence.py create技能） “页面已创建成功，这是访问链接。”
场景三：基于现有文档进行Q&A
- 你：“我们项目的部署流程文档在哪里？把关键步骤找出来。”
- Claude：（调用
confluence.py search查找“部署流程”，然后read相关页面） “找到文档‘生产环境部署指南’。关键步骤包括：1. 代码合并至main分支后触发CI；2. 通过Jenkins构建Docker镜像；3. 使用Ansible剧本更新K8s配置...”
6.2 技能组合与自动化脚本
atlassian-skill的强大之处还在于它可以与其他技能（如Git技能、数据库技能）结合，或者被封装到Shell/Python脚本中，实现更复杂的自动化。
示例脚本：自动创建Bug并关联Git提交假设你有一个脚本，在CI中检测到自动化测试失败时运行：
#!/bin/bash # ci_failure_handler.sh FAILURE_LOG="$1" COMMIT_HASH="$2" # 使用技能创建Jira Bug ISSUE_KEY=$(python scripts/jira.py create --project CI --summary "自动化测试失败于提交 $COMMIT_HASH" --type Bug --description "失败日志见附件或链接" --priority High --json | jq -r '.key') # 将失败日志作为附件（此处需调用Jira附加文件的API，技能可能需扩展，或使用curl补充） # echo "Issue $ISSUE_KEY created." # 在Git提交中评论，引用创建的Jira单（此处需调用Git技能或Git命令） # git commit --amend -m "Fix test. Ref: $ISSUE_KEY" # 示例这个脚本将运维事件（测试失败）自动转化为开发任务（Jira Bug），形成了闭环。
7. 常见问题排查与运维技巧
7.1 认证与连接问题
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
Login failed或Invalid credentials | 1. API令牌错误或已失效。 2. OAuth令牌过期且刷新失败。 3. 网络代理导致连接Atlassian API失败。 | 1.验证令牌：运行python scripts/auth.py status检查令牌状态。如果无效，重新登录login。2.检查网络：尝试 curl -v https://api.atlassian.com测试网络连通性。如有代理，需在系统中或通过HTTP_PROXY环境变量正确配置。3.查看详细日志：尝试在命令后添加 --verbose标志（如果技能支持），或查看AI客户端的调试日志。 |
| OAuth流程中浏览器授权后，命令行无响应 | 1. 本地回调端口被占用或防火墙阻止。 2. 浏览器阻止了回调。 3. 脚本的回调处理逻辑有误。 | 1.检查端口：默认通常使用http://localhost:xxxx。确保没有其他程序占用该端口。2.手动复制授权码：如果浏览器页面显示授权码，可以尝试手动复制，然后在命令行中通过特定参数传入（需查阅技能是否支持此模式）。 3.使用备用方案：临时切换到API令牌方式完成工作。 |
执行命令时报SSL相关错误 | 系统Python的SSL证书库不完整或过期。 | 1.更新证书：pip install --upgrade certifi2.使用系统包管理器重新安装Python。 3. （临时）添加环境变量 PYTHONHTTPSVERIFY=0（不推荐，仅用于紧急测试）。 |
7.2 命令执行与数据问题
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| JQL/CQL查询语法错误 | 查询语句不符合Jira/Confluence的查询语言规范。 | 1.简化查询：先在Jira/Confluence的Web界面高级搜索中测试你的JQL/CQL，确保语法正确。 2.转义特殊字符：在命令行中，如果查询包含引号、空格，需要用引号将整个查询括起来，如 search \"project = DEV AND summary ~ \\\"bug\\\"\"。3.查看API错误信息：技能返回的错误信息通常会包含Atlassian API的具体错误原因，这是最好的调试线索。 |
| 创建或更新工单/页面时返回权限错误 | 当前认证的账户对目标项目或空间没有相应的写入权限。 | 1.确认权限：登录Atlassian网站，确认你的账户在目标项目（Jira）或空间（Confluence）中是否有创建、编辑内容的权限。 2.检查项目/空间键：确认 --project或--space-id参数的值是否正确无误。3.尝试只读操作：先执行 list-projects或list-spaces，确认你能看到目标资源，这至少证明读取权限和连接是正常的。 |
--json输出格式解析错误 | 用于解析JSON的工具（如jq）版本不兼容，或JSON中包含意外字符。 | 1.直接查看原始输出：先不加--json运行命令，看人类可读的输出是否正常。2.使用Python内置模块解析： python -c \"import sys, json; print(json.load(sys.stdin))\"3.检查 jq版本：jq --version，确保版本较新。 |
7.3 安全与最佳实践建议
- 权限最小化原则：在通过OAuth授权时，Atlassian会列出请求的权限范围。请仔细审查，只授予该技能完成其功能所必需的最小权限。例如，如果只用于查询Jira，就不要授予“写入”权限。
- 凭证存储安全：该项目使用操作系统密钥链存储令牌，相对安全。但请确保你的个人电脑有登录密码，并且在不使用时锁屏。对于服务器环境，评估使用API令牌并结合严格的访问控制是否更合适。
- 审计日志：对于重要的写操作（如创建工单、更新Confluence页面），建议在自动化脚本中添加日志记录，记录操作内容、执行时间和执行结果，便于事后追溯。
- 错误处理：在将技能集成到自动化脚本中时，务必添加完善的错误处理（try-catch）。例如，网络超时、API限流（Rate Limit）等情况都应被捕获并妥善处理，可能是重试、告警或优雅降级。
- 版本关注：关注该GitHub项目的Release版本。像Atlassian API、MCP协议这类依赖项可能会更新，及时升级技能可以避免因接口变更导致的功能失效。
这个项目将日常工作中繁琐、重复的Atlassian系统操作变成了可编程、可对话的指令。无论是通过AI助手交互式地管理任务，还是将其作为自动化流水线中的一环，它都显著提升了工具链的智能水平和开发者的工作效率。从我个人的使用体验来看，最大的收获不是少点了几次鼠标，而是将任务跟踪和知识管理无缝地嵌入了开发流，让上下文切换更加平滑。刚开始配置时可能会遇到一两个小坎，主要是网络或权限问题，但一旦打通，你会发现它带来的流畅感是回不去的。
