atlassian-rest

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Atlassian REST API Skill

Atlassian REST API 技能

Portable Jira & Confluence integration via REST APIs. Works in any agent environment with Node.js 18+ — zero dependencies, no MCP server required.

通过REST API实现可移植的Jira与Confluence集成。可在任何安装了Node.js 18+的Agent环境中运行，零依赖，无需MCP服务器。

First-Use Setup

首次使用设置

<skill-path>

throughout this document refers to the directory where this skill is installed. Resolve it from the skill invocation context (e.g., the path shown by

claude plugin list

or the skill's directory in

.claude/plugins/

Before any operation, verify the user has credentials configured. Run:

bash

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

If it fails, guide the user through the setup — the script prints step-by-step instructions.

本文档中所有的

<skill-path>

指代该技能的安装目录，可从技能调用上下文中获取（例如

claude plugin list

显示的路径，或是

.claude/plugins/

下的技能目录）。

执行任何操作前，请先验证用户已配置凭证，运行以下命令：

bash

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

如果运行失败，引导用户完成设置：该脚本会输出 step-by-step 的操作指引。

Required Environment Variables

所需环境变量

Variable	Description	Example
`ATLASSIAN_API_TOKEN`	API token	(generated at Atlassian)
`ATLASSIAN_EMAIL`	Account email	`user@company.com`
`ATLASSIAN_DOMAIN`	Atlassian site domain	`company.atlassian.net`

变量	说明	示例
`ATLASSIAN_API_TOKEN`	API令牌	(在Atlassian平台生成)
`ATLASSIAN_EMAIL`	账号邮箱	`user@company.com`
`ATLASSIAN_DOMAIN`	Atlassian站点域名	`company.atlassian.net`

How to Use This Skill

如何使用该技能

When the user asks you to do something with Jira or Confluence, follow these principles:

Resolve ambiguity first. If the user says "create a ticket" but hasn't specified a project, run
```
node <skill-path>/scripts/jira.mjs projects
```
to list available projects, then ask which one. Same for issue types — run
```
node <skill-path>/scripts/jira.mjs issue-types <projectKey>
```
if unsure.
Confirm before mutating. Before creating issues, transitioning tickets, or publishing Confluence pages, show the user what you're about to do and get confirmation. Read operations (search, get, list) don't need confirmation.
Never delete. This skill does not support delete operations (issues, pages, attachments, boards, projects, accounts, etc.). If the user asks to delete something, direct them to the Atlassian web UI. This restriction is intentional and must not be bypassed.
Compose operations naturally. Many user requests require multiple script calls. For example, "assign PROJ-123 to Sarah" requires: (a)
```
lookup-user "Sarah"
```
to get the account ID, then (b)
```
edit PROJ-123 --assignee <accountId>
```
.
Prefer sync.mjs for document-based operations. When creating Jira issues from a local markdown file (story docs, specs, epics), use
```
sync.mjs
```
instead of raw
```
jira.mjs create
```
— it handles field mapping, link tracking, and sync state automatically. See the Document Sync Operations section below for details. Only use
```
jira.mjs create
```
for ad-hoc issues not backed by a local document.
Use workflows for complex tasks. If the user's request matches one of the workflows below, read the corresponding file and follow its step-by-step process.
Read reference docs when needed. Before writing JQL/CQL queries, consult
```
references/query-languages.md
```
. Before creating tickets, consult
```
references/ticket-writing-guide.md
```
. The reference docs exist to help you produce high-quality output — use them.

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

先消除歧义。如果用户说「创建一个工单」但未指定项目，运行
```
node <skill-path>/scripts/jira.mjs projects
```
列出可用项目，再询问用户选择哪个。如果不清楚工单类型，运行
```
node <skill-path>/scripts/jira.mjs issue-types <projectKey>
```
查询。
变更操作前先确认。在创建issue、流转工单状态或是发布Confluence页面之前，先向用户展示你即将执行的操作并获取确认。读取类操作（搜索、查询、列表）不需要确认。
绝不执行删除操作。该技能不支持删除操作（issue、页面、附件、看板、项目、账号等）。如果用户要求删除内容，引导他们前往Atlassian网页端操作。这是有意设置的限制，不得绕过。
自然组合操作。很多用户需求需要多次调用脚本，例如「把PROJ-123分配给Sarah」需要：(a) 运行
```
lookup-user "Sarah"
```
获取账号ID，然后(b) 运行
```
edit PROJ-123 --assignee <accountId>
```
。
文档类操作优先使用sync.mjs。从本地markdown文件（用户故事文档、需求规范、史诗）创建Jira issue时，使用
```
sync.mjs
```
而非原始的
```
jira.mjs create
```
：它会自动处理字段映射、链接追踪和同步状态。详情见下文的文档同步操作章节。仅当创建没有本地文档支撑的临时issue时使用
```
jira.mjs create
```
。
复杂任务使用工作流。如果用户的需求匹配下方的某个工作流，读取对应文件并遵循分步流程操作。
必要时查阅参考文档。编写JQL/CQL查询前，参考
```
references/query-languages.md
```
。创建工单前，参考
```
references/ticket-writing-guide.md
```
。参考文档可以帮助你输出高质量结果，请合理使用。

Passing Long Content to Scripts

向脚本传递长内容

For descriptions, comments, or page bodies longer than ~200 characters or containing special characters (backticks, quotes,

, newlines), write the content to a temp file and use the file-based flag:

Inline Flag	File Flag	Commands
`--description "text"`	`--description-file /tmp/desc.md`	jira create, jira edit
`<body>` (positional)	`--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

Write plain markdown to the file — scripts handle conversion to ADF (Jira) or storage format (Confluence) automatically. Prefer file-based input to avoid shell escaping issues.

如果描述、评论或页面正文超过~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 Operations

Jira操作

Script:

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

执行脚本：

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

Search Issues

搜索Issue

bash

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

bash

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

Get Issue Details

获取Issue详情

bash

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

bash

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

Create Issue

创建Issue

bash

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

bash

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

When creating child stories under an Epic, include `--priority Medium` unless the user specifies a different priority.

jira.mjs create --project PROJ --type Task --summary "Feature X"
--description-file /tmp/desc.md --priority High

在史诗下创建子用户故事时，除非用户指定其他优先级，默认设置`--priority Medium`。

Edit Issue

编辑Issue

bash

jira.mjs edit PROJ-123 --summary "Updated title" --priority Medium
jira.mjs edit PROJ-123 --labels "backend,v2" --components "API"

bash

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

undefined

jira.mjs edit PROJ-123 --description-file /tmp/desc.md

undefined

Comments

bash

jira.mjs comment PROJ-123 "Fixed in PR #456"

bash

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

undefined

jira.mjs comment PROJ-123 --body-file /tmp/comment.md

undefined

Transitions (move ticket status)

状态流转（修改工单状态）

bash

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

Always list transitions first to get the correct ID — don't guess.

bash

jira.mjs transitions PROJ-123          # 先列出可用的流转选项
jira.mjs transition PROJ-123 31        # 再通过ID执行流转

务必先列出流转选项获取正确ID，不要猜测。

Projects & Issue Types

项目与Issue类型

bash

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

bash

jira.mjs projects                      # 列出所有可见项目
jira.mjs issue-types PROJ              # 列出指定项目的Issue类型

Issue Links

Issue关联

bash

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

bash

jira.mjs link-types                    # 先列出可用的关联类型
jira.mjs link PROJ-1 PROJ-2 --type "relates to"

User Lookup

用户查询

bash

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

bash

jira.mjs lookup-user "john"            # 返回--assignee所需的账号ID

Worklog

工时记录

bash

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

bash

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

Document Sync Operations

文档同步操作

Script:

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

When creating Jira/Confluence items from local markdown documents, prefer sync.mjs over raw jira.mjs/confluence.mjs — it auto-updates the source document with links and maintains sync state.

执行脚本：

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

从本地markdown文档创建Jira/Confluence内容时，优先使用sync.mjs而非原生的jira.mjs/confluence.mjs：它会自动用链接更新源文档并维护同步状态。

Setup Field Mapping (first time per doc type)

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

bash

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

Field mappings are stored in

<skill-path>/memory/

and define how markdown sections map to Jira fields. See

references/sync-mapping-guide.md

for the full schema.

bash

sync.mjs setup-mapping --type story --sample PROJ-200   # 从现有工单自动检测字段
sync.mjs setup-mapping --type epic --sample PROJ-100    # 生成memory/jira-epic-field-mapping.json

字段映射存储在

<skill-path>/memory/

目录下，定义了markdown章节与Jira字段的对应关系。完整schema请参考

references/sync-mapping-guide.md

。

Link & Create from Document

关联文档与创建内容

bash

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

bash

sync.mjs link <file> --type story --project PROJ --create    # 创建Jira issue + 更新文档
sync.mjs link <file> --type epic --project PROJ --create     # 创建史诗 + 子用户故事
sync.mjs link <file> --type story --ticket PROJ-123          # 关联到已有工单

Push/Pull Changes

推送/拉取变更

bash

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

When

push

reports orphaned subtasks (sections removed from local doc), ask the user if they want to delete them, then run with

--delete-orphans

. Only

Sub-*

issue types can be deleted — parent issues are skipped.

bash

sync.mjs push <file>                    # 把本地变更推送到Jira/Confluence
sync.mjs push <file> --delete-orphans   # 推送 + 提示删除孤立的Sub-*子任务
sync.mjs pull <file>                    # 把远程变更拉取到本地
sync.mjs diff <file>                    # 展示按章节拆分的差异
sync.mjs status <file>                  # 展示同步状态

当

push

报告存在孤儿子任务（本地文档中已删除的章节）时，询问用户是否要删除它们，再添加

--delete-orphans

参数运行。仅

Sub-*

类型的issue可以被删除，父级issue会被跳过。

Custom Instructions in Mapping Config

映射配置中的自定义指令

The field mapping JSON (

memory/jira-<docType>-field-mapping.json

) supports an

instructions

field for additional agent guidance:

json

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

When present, instructions are printed to stdout during

push

and

link

operations so the calling agent can follow them.

字段映射JSON（

memory/jira-<docType>-field-mapping.json

）支持

instructions

字段，用于提供额外的Agent指引：

json

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

该字段存在时，

push

和

link

操作会将指令输出到stdout，调用的Agent可以遵循这些指令执行。

Batch Operations

批量操作

bash

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

bash

sync.mjs batch                # 扫描所有关联的文档并报告状态

Confluence Operations

Confluence操作

Script:

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

执行脚本：

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

Search Pages

搜索页面

bash

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

bash

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

Get Page

获取页面

bash

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

bash

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

Create Page

创建页面

bash

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

The

--body

flag accepts markdown (recommended), plain text, or raw HTML storage format (if it starts with

). The script automatically converts markdown to Confluence storage format — headings, lists, tables, and code blocks (converted to

ac:structured-macro ac:name="code"

with language detection) are all handled. Prefer writing markdown and letting the script handle conversion rather than manually constructing storage format XHTML. Use

--body-file

for long documents that would exceed shell argument limits.

bash

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。长文档请使用

--body-file

避免超出shell参数长度限制。

Update Page

更新页面

bash

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

Version is auto-incremented — no need to track it manually. Use

--body-file

for large page updates.

bash

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

。

Comments

bash

confluence.mjs comment 12345 "Reviewed and approved"

bash

confluence.mjs comment 12345 "Reviewed and approved"

For long comments, use a file:

长评论请使用文件：

confluence.mjs comment 12345 --body-file /tmp/comment.md

undefined

confluence.mjs comment 12345 --body-file /tmp/comment.md

undefined

Attachments

附件

bash

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

Use

attach

to upload local files (images, PDFs, etc.) to a page. After uploading, embed images in the page body using

<ac:image><ri:attachment ri:filename="screenshot.png" /></ac:image>

— see

references/confluence-formatting.md

for sizing guidelines.

bash

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

。

Sync Confluence Space to Local Markdown

同步Confluence空间到本地markdown

bash

undefined

bash

undefined

Download an entire page tree to local markdown with attachments

将整个页面树下载到本地markdown，包含附件

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)

跳过附件下载（速度更快，仅下载markdown）

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

Downloads an entire Confluence page tree to local markdown files with hierarchy, images, and linked titles. Rewrites both image references and file attachment links to point to local assets. See `workflows/sync-confluence-space.md` for full details and customization options.

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

将整个Confluence页面树下载到本地markdown文件，保留层级结构、图片和链接标题。自动重写图片引用和文件附件链接指向本地资源。完整详情和自定义选项见`workflows/sync-confluence-space.md`。

Spaces & Navigation

空间与导航

bash

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

bash

confluence.mjs spaces --max 20
confluence.mjs descendants 12345       # 获取子页面

Format Conversion Utilities

格式转换工具

Script:

<skill-path>/scripts/confluence-format.mjs

This module provides bidirectional markdown ↔ Confluence storage format conversion. It's used internally by

confluence.mjs

but can also be imported directly for custom sync scripts.

执行脚本：

<skill-path>/scripts/confluence-format.mjs

该模块提供markdown ↔ Confluence存储格式的双向转换功能。

confluence.mjs

内部已使用该模块，你也可以直接导入用于自定义同步脚本。

Exported Functions

导出的函数

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

Function	Direction	Use case
`markdownToStorage(md)`	Markdown → XHTML	Publishing to Confluence (auto-used by `confluence.mjs --body-file` )
`storageToMarkdown(html)`	XHTML → Markdown	Downloading/syncing Confluence pages to local markdown files
`htmlInlineToMarkdown(html)`	Inline HTML → Markdown	Converting snippets (table cells, list items) that may contain `<strong>` , `<em>` , `<a>` , `<code>`

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>` 的片段（表格单元格、列表项）

What

storageToMarkdown

Handles

storageToMarkdown

支持的转换能力

The converter handles real-world Confluence storage format patterns including:

Structured macros: code blocks (with/without language), panels (info/tip/warning/note → GitHub alerts), expand →
```
<details><summary>
```
collapsible sections, jira references, view-file → attachment links, toc/children (stripped)
Unknown macros: Any unrecognized
```
ac:structured-macro
```
types have their body content preserved (not silently dropped)
Tables:
```
<colgroup>
```
,
```
<tbody>
```
,
```
<thead>
```
wrappers stripped; attributes on
```
<table>
```
,
```
<tr>
```
,
```
<th>
```
,
```
<td>
```
handled
Task lists:
```
<ac:task-list>
```
with
```
<ac:task-id>
```
→ markdown checkboxes
Images: URL and attachment images →
```
![alt](url)
```
with filename as fallback alt text; parentheses and spaces in filenames URL-encoded
Code blocks: Protected from HTML tag stripping via placeholder system — generic types like
```
Array<string>
```
preserved inside fenced blocks
Expand/collapsible bodies: Full content support inside expand macros — code blocks, images, tables, panels, task lists, and nested macros all convert correctly
Entities: Full HTML entity decoding (
```
&rsquo;
```
,
```
&ldquo;
```
,
```
&rarr;
```
,
```
&nbsp;
```
, numeric
```
&#123;
```
)
Block separation:
```
\n\n
```
around headings, images, lists,
```
<hr>
```
, tables, code blocks
Attribute tolerance: All HTML tag regexes accept optional attributes (handles Confluence's
```
local-id
```
,
```
data-layout
```
,
```
breakoutWidth
```
, etc.)
Bold/italic cleanup: Trailing spaces inside markers fixed (
```
**text **
```
→
```
**text**
```
)
Stray angle brackets: Escaped outside code blocks to prevent markdown renderer confusion

转换器支持真实场景下的Confluence存储格式模式，包括：

结构化宏：代码块（带/不带语言）、面板（信息/提示/警告/备注 → GitHub警示框）、折叠块 →
```
<details><summary>
```
可折叠章节、Jira引用、文件预览 → 附件链接、目录/子页面列表（自动移除）
未知宏：任何未识别的
```
ac:structured-macro
```
类型都会保留其主体内容（不会静默丢弃）
表格：自动移除
```
<colgroup>
```
、
```
<tbody>
```
、
```
<thead>
```
包装器；支持
```
<table>
```
、
```
<tr>
```
、
```
<th>
```
、
```
<td>
```
上的属性
任务列表：
```
<ac:task-list>
```
带
```
<ac:task-id>
```
→ markdown复选框
图片：URL和附件图片 →
```
![alt](url)
```
，文件名作为备用alt文本；文件名中的括号和空格会自动URL编码
代码块：通过占位符系统避免HTML标签剥离， fenced块内的泛型类型如
```
Array<string>
```
会完整保留
折叠/可展开正文：完全支持折叠宏内的所有内容——代码块、图片、表格、面板、任务列表和嵌套宏都可以正确转换
实体字符：完整的HTML实体解码（
```
&rsquo;
```
、
```
&ldquo;
```
、
```
&rarr;
```
、
```
&nbsp;
```
、数值型
```
&#123;
```
）
块分隔：标题、图片、列表、
```
<hr>
```
、表格、代码块前后自动添加
```
\n\n
```
属性兼容：所有HTML标签正则都支持可选属性（适配Confluence的
```
local-id
```
、
```
data-layout
```
、
```
breakoutWidth
```
等属性）
粗体/斜体清理：修复标记内的 trailing 空格（
```
**text **
```
→
```
**text**
```
）
** stray 尖括号**：代码块外的尖括号会自动转义，避免markdown渲染器解析错误

Syncing a Confluence Space

同步Confluence空间

For most use cases, use the built-in sync script directly:

bash

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

For custom sync scripts, import

storageToMarkdown

and follow this pattern:

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}`;

Key gotchas discovered in production use:

The v2 API
```
_links.webui
```
is a relative path (e.g.,
```
/spaces/BTH/pages/123/Title
```
). Combine with
```
_links.base
```
(e.g.,
```
https://company.atlassian.net/wiki
```
) for the full URL — do NOT use
```
env.domain
```
+
```
_links.webui
```
directly (missing
```
/wiki
```
prefix).
Attachment filenames with spaces and parentheses must be URL-encoded in markdown links:
```
![alt](Screenshot%202025-11-05%20at%2016.50.02.png)
```
.
When writing a hierarchical sync, use
```
getChildrenTree()
```
(recursive children API) to build the tree, then decide per-node: pages with children →
```
directory/index.md
```
, leaf pages → flat
```
PageName.md
```
.
Keep attachments in a shared
```
assets/imgs/
```
and
```
assets/pdfs/
```
directory. Use depth-aware relative paths (
```
../assets/imgs/
```
at depth 1,
```
../../assets/imgs/
```
at depth 2, etc.).
The sync script must rewrite both image references (
```
![alt](filename)
```
) and file attachment links (
```
[filename](filename)
```
) to local paths — Confluence
```
view-file
```
macros produce regular links, not image references.
Confluence adds attributes (
```
local-id
```
,
```
breakoutWidth
```
,
```
data-layout
```
) to most HTML tags. Any regex matching tags must use
```
[^>]*
```
for optional attributes.
Expand macro bodies can contain any content (code blocks, images, tables). The inner HTML converter must handle the same set of elements as the main converter.

大多数场景下直接使用内置同步脚本即可：

bash

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

如果要编写自定义同步脚本，导入

storageToMarkdown

并遵循以下模式：

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

// 通过Confluence v2 API获取页面
const page = await apiGet(`/wiki/api/v2/pages/${pageId}`, { 'body-format': 'storage' });
const html = page.body.storage.value;

// 转换为markdown
let markdown = storageToMarkdown(html);

// 使用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
```
），任何匹配标签的正则都要使用
```
[^>]*
```
匹配可选属性。
折叠宏的主体可以包含任何内容（代码块、图片、表格），内部HTML转换器需要支持和主转换器相同的元素集。

Running Tests

运行测试

bash

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

100+ tests covering forward conversion, reverse conversion, round-trip preservation, block element spacing, code block protection, image URL encoding, entity decoding, expand macros with nested content, view-file macros, unknown macro catch-all, and attribute tolerance on HTML tags.

bash

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

包含100+测试用例，覆盖正向转换、反向转换、往返保留、块元素间距、代码块保护、图片URL编码、实体解码、带嵌套内容的折叠宏、文件预览宏、未知宏兜底、HTML标签属性兼容等场景。

Workflows

工作流

For complex multi-step operations that require user interaction across several turns, read the corresponding workflow file and follow its step-by-step process. For simple one-shot commands, use the operations sections above directly.

Workflow	When to use	File
Capture Tasks from Meeting Notes	User provides meeting notes and wants Jira tasks created from action items	`workflows/capture-tasks-from-meeting-notes.md`
Generate Status Report	User wants a project status report, sprint summary, or weekly update	`workflows/generate-status-report.md`
Search Company Knowledge	User wants to find information across Confluence pages and Jira issues	`workflows/search-company-knowledge.md`
Spec to Backlog	User has a Confluence spec and wants it broken into an Epic + child tickets	`workflows/spec-to-backlog.md`
Triage Issue	User reports a bug and wants duplicate checking before filing	`workflows/triage-issue.md`
Create Confluence Document	User wants a professional Confluence page with macros, images, and structured formatting	`workflows/create-confluence-document.md`
Sync BMAD Documents	User wants to sync local BMAD docs (epics, tech specs, PRDs, architecture) with Jira or Confluence, or link a document to a ticket/page	`workflows/sync-bmad-documents.md`
Sync Confluence Space	User wants to download an entire Confluence space to local markdown files with hierarchy, images, and linked titles	`workflows/sync-confluence-space.md`

对于需要多轮用户交互的复杂多步操作，请读取对应的工作流文件并遵循分步流程执行。简单的单步命令直接使用上方的操作章节即可。

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

Error Handling

错误处理

Error	Likely Cause	Resolution
`401 Unauthorized`	Bad or expired API token	Regenerate at Atlassian security settings
`403 Forbidden`	Insufficient permissions	Check project/space permissions for the user's account
`404 Not Found`	Wrong issue key, page ID, or domain	Verify the resource exists and `ATLASSIAN_DOMAIN` is correct
`429 Too Many Requests`	Rate limited	Wait briefly and retry; reduce batch sizes
Missing env vars	Not configured	Run `node <skill-path>/scripts/setup.mjs`

错误	可能原因	解决方案
`401 Unauthorized`	API令牌错误或过期	在Atlassian安全设置中重新生成
`403 Forbidden`	权限不足	检查用户账号的项目/空间权限
`404 Not Found`	Issue key、页面ID或域名错误	验证资源是否存在，确认 `ATLASSIAN_DOMAIN` 配置正确
`429 Too Many Requests`	触发限流	稍等后重试，减小批量操作的大小
缺少环境变量	未完成配置	运行 `node <skill-path>/scripts/setup.mjs`

Reference Documentation

参考文档

Load these as needed — don't read them all upfront:

Reference	When to consult
`references/jira-api.md`	Need details on Jira API endpoints or request shapes
`references/confluence-api.md`	Need details on Confluence API endpoints or storage format
`references/confluence-formatting.md`	Building professional pages with macros, layouts, images, and document templates
`references/query-languages.md`	Writing JQL or CQL queries
`references/jql-patterns.md`	Need common JQL patterns for reports, searches, filters
`references/action-item-patterns.md`	Parsing meeting notes for action items
`references/report-templates.md`	Generating status reports
`references/bug-report-templates.md`	Creating well-structured bug reports
`references/search-patterns.md`	Multi-source search strategies
`references/epic-templates.md`	Writing epic descriptions
`references/ticket-writing-guide.md`	Writing clear ticket summaries and descriptions
`references/breakdown-examples.md`	Breaking specs into stories and tasks
`references/sync-mapping-guide.md`	Before first document sync, when mapping fields fail, or configuring custom field mappings

按需加载即可，不需要提前全部阅读：

参考文档	查阅场景
`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`	编写史诗描述
`references/ticket-writing-guide.md`	编写清晰的工单标题和描述
`references/breakdown-examples.md`	将需求规范拆分为用户故事和任务
`references/sync-mapping-guide.md`	首次文档同步前、字段映射失败时，或是配置自定义字段映射时