atlassian-rest

Atlassian REST API 技能

通过 REST API 便携式集成 Jira 和 Confluence。可在任何装有 Node.js 18+ 的 Agent 环境中运行——零依赖，无需 MCP 服务。

首次使用设置

本文档中的 <skill-path> 指此技能的安装目录。请从技能调用上下文中解析该路径（例如，claude plugin list 显示的路径，或 .claude/plugins/ 中技能所在的目录）。

执行任何操作前，请确认用户已配置凭据。运行：

node <skill-path>/scripts/setup.mjs

如果失败，请指导用户完成设置——脚本会打印逐步说明。

必需的环境变量

变量	说明	示例
ATLASSIAN_API_TOKEN	API 令牌	（在 Atlassian 生成）
ATLASSIAN_EMAIL	账户邮箱	[email protected]
ATLASSIAN_DOMAIN	Atlassian 站点域名	company.atlassian.net

---

如何使用此技能

用户要求你对 Jira 或 Confluence 执行操作时，请遵循以下原则：

1. 先解决歧义。 如果用户说“创建工单”，但未指定项目，请运行 node <skill-path>/scripts/jira.mjs projects 列出可用项目，然后询问用户要选哪个。工单类型也一样——不确定时，运行 node <skill-path>/scripts/jira.mjs issue-types <projectKey>。

2. 修改前先确认。 创建工单、转换工单状态或发布 Confluence 页面之前，向用户说明你准备执行的操作并征得确认。读取操作（搜索、获取、列出）无需确认。

3. 绝不删除。 此技能不支持删除操作（工单、页面、附件、看板、项目、账户等）。如果用户要求删除内容，请引导他们使用 Atlassian 网页界面。此限制是有意设置的，不得绕过。

4. 自然地组合操作。 许多用户请求需要多次调用脚本。例如，“将 PROJ-123 指派给 Sarah”需要：(a) 运行 lookup-user "Sarah" 获取账户 ID，然后 (b) 运行 edit PROJ-123 --assignee <accountId>。

5. 基于文档的操作优先使用 sync.mjs。 根据本地 Markdown 文件（用户故事文档、规格说明、史诗）创建 Jira 工单时，使用 sync.mjs，而不是直接使用 jira.mjs create——它会自动处理字段映射、链接跟踪和同步状态。详情请参阅下方的“文档同步操作”部分。仅对没有关联本地文档的临时工单使用 jira.mjs create。

6. 复杂任务使用工作流。 如果用户的请求符合以下某个工作流，请阅读对应文件并遵循其分步流程。

7. 按需阅读参考文档。 编写 JQL/CQL 查询前，请查阅 references/query-languages.md。创建工单前，请查阅 references/ticket-writing-guide.md。参考文档有助于你生成高质量内容——请善加利用。

向脚本传递较长内容

对于超过约 200 个字符或包含特殊字符（反引号、引号、$、换行符）的描述、评论或页面正文，请将内容写入临时文件，并使用基于文件的标志：

行内标志	文件标志	命令
--description "text"	--description-file /tmp/desc.md	jira create、jira edit
<body>（位置参数）	--body-file /tmp/body.md	jira comment、confluence comment
--body "text"	--body-file /tmp/body.md	confluence create-page、update-page
--comment "text"	--comment-file /tmp/comment.md	jira worklog

将纯 Markdown写入文件——脚本会自动将其转换为 ADF（Jira）或存储格式（Confluence）。优先使用基于文件的输入，以避免 Shell 转义问题。

---

Jira 操作

脚本：node <skill-path>/scripts/jira.mjs <command> [args]

搜索工单

jira.mjs search 'project = PROJ AND status = "In Progress"' --max 20

获取工单详情

jira.mjs get PROJ-123
jira.mjs get PROJ-123 --fields summary,status,assignee

创建 Issue

jira.mjs create --project PROJ --type Task --summary "Implement feature X" \
  --description "Details here" --priority High --assignee <accountId> \
  --labels "backend,urgent" --components "API,Auth"
jira.mjs create --project PROJ --type Story --summary "User login" --parent PROJ-100
# For long descriptions, use a file:
jira.mjs create --project PROJ --type Task --summary "Feature X" \
  --description-file /tmp/desc.md --priority High

在 Epic 下创建子故事时，除非用户指定了其他优先级，否则请添加 --priority Medium。

编辑 Issue

jira.mjs edit PROJ-123 --summary "Updated title" --priority Medium
jira.mjs edit PROJ-123 --labels "backend,v2" --components "API"
# For long descriptions, use a file:
jira.mjs edit PROJ-123 --description-file /tmp/desc.md

评论

jira.mjs comment PROJ-123 "Fixed in PR #456"
# For long comments, use a file:
jira.mjs comment PROJ-123 --body-file /tmp/comment.md

状态转换（移动工单状态）

jira.mjs transitions PROJ-123          # List available transitions first
jira.mjs transition PROJ-123 31        # Then transition by ID

务必先列出状态转换，以获取正确的 ID — 不要猜测。

项目与 Issue 类型

jira.mjs projects                      # List all visible projects
jira.mjs issue-types PROJ              # List issue types for a project

Issue 链接

jira.mjs link-types                    # List available link types first
jira.mjs link PROJ-1 PROJ-2 --type "relates to"

用户查找

jira.mjs lookup-user "john"            # Returns account ID needed for --assignee

工时记录

jira.mjs worklog PROJ-123 --time 2h --comment "Code review"

---

文档同步操作

脚本：node <skill-path>/scripts/sync.mjs <command> [args]

从本地 Markdown 文档创建 Jira/Confluence 条目时，优先使用 sync.mjs，而不是直接调用 jira.mjs/confluence.mjs — 它会自动在源文档中更新链接并维护同步状态。

设置字段映射（每种文档类型首次设置）

sync.mjs setup-mapping --type story --sample PROJ-200   # Auto-detect fields from existing ticket
sync.mjs setup-mapping --type epic --sample PROJ-100    # Creates memory/jira-epic-field-mapping.json

字段映射存储在 <skill-path>/memory/ 中，用于定义 Markdown 章节如何映射到 Jira 字段。完整架构请参阅 references/sync-mapping-guide.md。

从文档链接并创建

sync.mjs link <file> --type story --project PROJ --create    # Create Jira issue + update doc
sync.mjs link <file> --type epic --project PROJ --create     # Create epic + child stories
sync.mjs link <file> --type story --ticket PROJ-123          # Link to existing ticket

推送/拉取更改

sync.mjs push <file>                    # Push local changes to Jira/Confluence
sync.mjs push <file> --delete-orphans   # Push + prompt to delete orphaned Sub-* subtasks
sync.mjs pull <file>                    # Pull remote changes to local
sync.mjs diff <file>                    # Show per-section diff
sync.mjs status <file>                  # Show sync status

当 push 报告存在孤立的子任务（本地文档中已删除的章节）时，询问用户是否要删除这些子任务，然后使用 --delete-orphans 运行。只能删除 Sub-* Issue 类型 — 将跳过父 Issue。

###映射配置中的自定义说明 字段映射 JSON（memory/jira-<docType>-field-mapping.json）支持 instructions 字段，用于提供额外的 Agent 指引：

{
  "instructions": "Always set priority to High. Add label 'team-alpha'. Use Sub-Imp type for child items."
}

如果存在此字段，push 和 link 操作期间会将说明打印到 stdout，供调用方 Agent 遵循。

批量操作

sync.mjs batch                # Scan all linked docs and report status

---

Confluence 操作

脚本：node <skill-path>/scripts/confluence.mjs <command> [args]

搜索页面

confluence.mjs search 'type = page AND text ~ "architecture"' --max 10

获取页面

confluence.mjs get-page 12345
confluence.mjs get-page 12345 --format view

创建页面

confluence.mjs create-page --space TEAM --title "Sprint Report" --body "Report content"
confluence.mjs create-page --space TEAM --title "Sub Page" \
  --body "<h2>Heading</h2><p>Content</p>" --parent 12345
confluence.mjs create-page --space TEAM --title "Full Doc" --body-file /tmp/body.md

--body 标志接受 Markdown（推荐）、纯文本或原始 HTML 存储格式（如果内容以 < 开头）。脚本会自动将 Markdown 转换为 Confluence 存储格式 — 标题、列表、表格和代码块（会转换为 ac:structured-macro ac:name="code"，并自动检测语言）均可处理。建议编写 Markdown 并由脚本处理转换，而不是手动构造存储格式 XHTML。对于超出 shell 参数长度限制的长文档，请使用 --body-file。

更新页面

confluence.mjs update-page 12345 --title "Updated Title" --body "New content"
confluence.mjs update-page 12345 --title "Updated Title" --body-file /tmp/body.md

版本会自动递增，无需手动跟踪。大型页面更新请使用 --body-file。

评论

confluence.mjs comment 12345 "Reviewed and approved"
# For long comments, use a file:
confluence.mjs comment 12345 --body-file /tmp/comment.md

附件

confluence.mjs attach 12345 ./screenshot.png --comment "Architecture diagram"
confluence.mjs list-attachments 12345 --max 10

使用 attach 将本地文件（图片、PDF 等）上传到页面。上传后，在页面正文中使用 <ac:image><ri:attachment ri:filename="screenshot.png" /></ac:image> 嵌入图片 — 尺寸指南请参阅 references/confluence-formatting.md。

将 Confluence 空间同步到本地 Markdown

# Download an entire page tree to local markdown with attachments
node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs

# Preview without writing files
node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs --dry-run

# Skip attachment downloads (faster, markdown only)
node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs --skip-attachments

将整个 Confluence 页面树下载为本地 Markdown 文件，并保留层级、图片和链接标题。重写图片引用和文件附件链接，使其指向本地资源。完整详情和自定义选项请参阅 workflows/sync-confluence-space.md。

空间与导航

confluence.mjs spaces --max 20
confluence.mjs descendants 12345       # Get child pages

---

格式转换工具

脚本：<skill-path>/scripts/confluence-format.mjs

此模块提供 Markdown ↔ Confluence 存储格式的双向转换。它由 confluence.mjs 在内部使用，也可直接导入自定义同步脚本。

导出函数

import { markdownToStorage, storageToMarkdown, htmlInlineToMarkdown } from '<skill-path>/scripts/confluence-format.mjs';

函数	方向	用途
markdownToStorage(md)	Markdown → XHTML	发布到 Confluence（confluence.mjs --body-file 会自动使用）
storageToMarkdown(html)	XHTML → Markdown	将 Confluence 页面下载/同步到本地 Markdown 文件
htmlInlineToMarkdown(html)	行内 HTML → Markdown	转换可能包含 <strong>、<em>、<a>、<code> 的片段（表格单元格、列表项）

storageToMarkdown 处理的内容

该转换器支持实际 Confluence 存储格式中的常见模式，包括：

• 结构化宏：代码块（有或没有语言）、面板（info/tip/warning/note → GitHub 警示）、expand → <details><summary> 可折叠区域、Jira 引用、view-file → 附件链接、toc/children（剥离）
• 未知宏：任何无法识别的 ac:structured-macro 类型都会保留其正文内容（不会被悄然丢弃）
• 表格：剥离 <colgroup>、<tbody>、<thead> 包装标签；处理 <table>、<tr>、<th>、<td> 上的属性
• 任务列表：将带有 <ac:task-id> 的 <ac:task-list> 转换为 Markdown 复选框
• 图片：URL 和附件图片 → ![alt](url)，并在缺少替代文本时使用文件名作为后备替代文本；对文件名中的括号和空格进行 URL 编码
• 代码块：通过占位符机制避免 HTML 标签剥离；代码围栏内的 Array<string> 等泛型类型会保留
• Expand/可折叠正文：完整支持 expand 宏内的内容，包括代码块、图片、表格、面板、任务列表和嵌套宏，均可正确转换
• 实体：完整解码 HTML 实体（’、“、→、 、数字实体 {）
• 块级元素分隔：在标题、图片、列表、<hr>、表格和代码块周围添加 \n\n
• 属性容错：所有 HTML 标签正则表达式均接受可选属性（可处理 Confluence 的 local-id、data-layout、breakoutWidth 等）
• 粗体/斜体清理：修复标记内的尾随空格（**text ** → **text**）
• 多余尖括号：在代码块之外进行转义，避免 Markdown 渲染器产生歧义

同步 Confluence 空间

对于大多数使用场景，可直接使用内置同步脚本：

node <skill-path>/scripts/sync-confluence-space.mjs --root <pageId> --output ./docs

对于自定义同步脚本，请导入 storageToMarkdown 并遵循以下模式：

import { storageToMarkdown } from '<skill-path>/scripts/confluence-format.mjs';

// Fetch page via Confluence v2 API
const page = await apiGet(`/wiki/api/v2/pages/${pageId}`, { 'body-format': 'storage' });
const html = page.body.storage.value;

// Convert to markdown
let markdown = storageToMarkdown(html);

// Add linked title using page._links.base + page._links.webui
const pageUrl = `${page._links.base}${page._links.webui}`;
markdown = `# [${page.title}](${pageUrl})\n\n${markdown}`;

生产环境中发现的关键注意事项：

• v2 API 的 _links.webui 是相对路径（例如 /spaces/BTH/pages/123/Title）。请与 _links.base（例如 https://company.atlassian.net/wiki）组合以获取完整 URL；不要直接使用 env.domain + _links.webui（会缺少 /wiki 前缀）。
• 文件名中包含空格和括号的附件必须在 Markdown 链接中进行 URL 编码：![alt](Screenshot%202025-11-05%20at%2016.50.02.png)。
• 编写分层同步脚本时，请使用 getChildrenTree()（递归子项 API）构建树，然后按节点决定处理方式：有子项的页面 → directory/index.md，叶子页面 → 扁平的 PageName.md。
• 将附件放在共享的 assets/imgs/ 和 assets/pdfs/ 目录中。使用考虑目录深度的相对路径（深度为 1 时用 ../assets/imgs/，深度为 2 时用 ../../assets/imgs/，依此类推）。
• 同步脚本必须将图片引用（![alt](filename)）和文件附件链接（[filename](filename)）都重写为本地路径 — Confluence 的 view-file 宏会生成普通链接，而不是图片引用。
• Confluence 会为大多数 HTML 标签添加属性（local-id、breakoutWidth、data-layout）。任何用于匹配标签的正则表达式都必须使用 [^>]* 来处理可选属性。
• Expand 宏正文可以包含任意内容（代码块、图片、表格）。内部 HTML 转换器必须能处理与主转换器相同的一组元素。

运行测试

node <skill-path>/scripts/test-format.mjs

100 多项测试涵盖正向转换、反向转换、往返保留、块级元素间距、代码块保护、图片 URL 编码、实体解码、包含嵌套内容的 expand 宏、view-file 宏、未知宏兜底处理，以及对 HTML 标签属性的容错处理。

---

工作流

对于需要跨多个回合与用户交互的复杂多步骤操作，请阅读相应的工作流文件，并按其中的步骤操作。对于简单的一次性命令，请直接使用上面的操作部分。

工作流	使用场景	文件
从会议记录中提取任务	用户提供会议记录，并希望根据行动项创建 Jira 任务	workflows/capture-tasks-from-meeting-notes.md
生成状态报告	用户需要项目状态报告、冲刺总结或每周更新	workflows/generate-status-report.md
搜索公司知识	用户希望跨 Confluence 页面和 Jira 问题查找信息	workflows/search-company-knowledge.md
从规范创建待办事项	用户有一份 Confluence 规范，并希望将其拆分为一个 Epic 和子任务	workflows/spec-to-backlog.md
问题分类	用户报告了一个 Bug，并希望在提交前检查是否重复	workflows/triage-issue.md
创建 Confluence 文档	用户希望创建包含宏、图片和结构化格式的专业 Confluence 页面	workflows/create-confluence-document.md
同步 BMAD 文档	用户希望将本地 BMAD 文档（epic、技术规范、PRD、架构）与 Jira 或 Confluence 同步，或将文档关联到工单/页面	workflows/sync-bmad-documents.md
同步 Confluence 空间	用户希望将整个 Confluence 空间下载为本地 Markdown 文件，并保留层级、图片和关联标题	workflows/sync-confluence-space.md

---

错误处理

错误	可能原因	解决方法
401 Unauthorized	API 令牌无效或已过期	在 Atlassian 安全设置中重新生成令牌
403 Forbidden	权限不足	检查用户账户对项目/空间的权限
404 Not Found	问题键、页面 ID 或域名错误	确认资源存在且 ATLASSIAN_DOMAIN 设置正确
429 Too Many Requests	请求频率受限	稍等片刻后重试；减小批处理大小
缺少环境变量	尚未配置	运行 node <skill-path>/scripts/setup.mjs

---

参考文档

按需加载以下文档——不要一开始就全部阅读：

参考文档	何时查阅
references/jira-api.md	需要了解 Jira API 端点或请求格式时
references/confluence-api.md	需要了解 Confluence API 端点或存储格式时
references/confluence-formatting.md	使用宏、布局、图片和文档模板构建专业页面时
references/query-languages.md	编写 JQL 或 CQL 查询时
references/jql-patterns.md	需要用于报告、搜索和筛选的常见 JQL 模式时
references/action-item-patterns.md	从会议记录中提取行动项时
references/report-templates.md	生成状态报告时
references/bug-report-templates.md	创建结构清晰的 Bug 报告时
references/search-patterns.md	制定多来源搜索策略时
references/epic-templates.md	编写 epic 描述时
references/ticket-writing-guide.md	编写清晰的工单摘要和描述时
references/breakdown-examples.md	将规范拆分为用户故事和任务时
references/sync-mapping-guide.md	首次同步文档前、字段映射失败时，或配置自定义字段映射时