atlassian-rest-ops

atlassian-rest-ops

概述

此技能让 Agent 能够通过直接使用 curl 调用 REST API，执行 Confluence Cloud (v2) 或 Jira Cloud (v3) 的任何操作——无需 SDK，也不依赖 pip。REST API 涵盖完整的 API 功能，包括创建 Confluence 页面等写入操作。Agent 使用调用方注入的凭据，通过端点索引 + $ref 解析器从随附的 OpenAPI 规范中查找端点，构造 curl 请求并解析 JSON。Confluence 和 Jira 在多个方面存在差异（基础 URL、分页、错误、富文本），因此此技能为每种 API提供各自的模式，而非采用一种通用形式。

何时启用

• ✅ 执行 Confluence Cloud v2 操作（创建／获取／更新／搜索页面、空间、附件，……）。
• ✅ 执行 Jira Cloud v3 操作（创建／搜索／转换问题、评论，……）。
• ✅ 需要以编程方式对 Atlassian REST API 执行写入或其他操作（例如创建 Confluence 页面）。

以下情况请勿启用：

• 目标是 Atlassian Server / Data Center（此技能仅适用于 Cloud + API 令牌）。
• 只需要设置凭据——凭据由调用方提供；此技能不会配置或解析凭据（参见 references/credentials.md 中的约定）。

工作流

步骤 1 — 接收注入的凭据

调用方已解析账户并注入此操作所需的内容——请直接使用，不要自行查找记录。从上下文中接收：

• base_url 和 email（以及账户所使用的能力）——作为上下文值提供，而不是从文件中读取。
• 令牌，按有序加载规则获取：上下文会提供变量的名称。按以下规则解析该名称：如果项目级 .env 文件存在且定义了该变量，则使用其中的值；否则使用同名的环境变量——优先尝试项目 .env（因此项目 .env 可以覆盖全局环境变量）。上下文说明中不会包含令牌的值，只包含变量名称；curl 会从环境中读取该值。上下文会提供项目根目录；不要执行任何范围解析或目录遍历来查找 .env。这里指的是项目 .env，而不是 .envrc。

然后将这些值映射到示例脚本中固定使用的变量 ATLASSIAN_EMAIL / ATLASSIAN_BASE_URL / ATLASSIAN_API_TOKEN（与之前相同的映射方式；现在只有输入来自上下文）。完整约定和映射方式见：references/credentials.md。

步骤 2 — 查找端点

扫描 assets/endpoint-index.md（每个操作占一行，格式为：METHOD path — summary (operationId)），查找所需操作。不要将完整规范加载到上下文中——它们有数 MB 大小。

步骤 3 — 解析调用形式

运行解析器：python3 scripts/endpoint.py <confluence|jira> <operationId>。它会从随附的 OpenAPI 规范中解析该操作（解析 $ref），并输出方法、路径、参数、请求／响应架构和 curl 骨架。（scripts/endpoint.py 及其验证是在扩充过程中添加的；参见渐进式披露。）

步骤 4 — 构造并运行 curl

应用 references/patterns.md 中针对每种 API的模式：

• 身份验证（两者相同）：curl -u "$email:$<token_env>"（HTTP Basic）。
• 基础 URL： Confluence → <base_url>/wiki/api/v2/<path>；Jira → <base_url>/<path>（路径已包含 /rest/api/3/…）。
• 富文本正文（容易出错的部分）——参见 references/rich-text.md：Jira 使用原始 JSON 对象形式的 ADF；Confluence 使用 {representation, value}，其中 atlas_doc_format 表示 ADF JSON 字符串化后的内容，storage 表示 XHTML 字符串。如果源内容是 Markdown（例如格式化评论），请使用 python3 scripts/md_to_adf.py < body.md 将其转换为 ADF，而不是发送原始 Markdown（否则 ##／**／| 会按字面内容呈现）。
• 发送／接受 application/json。

步骤 5 — 处理响应

• 分页： Confluence → cursor + 跟进 _links.next；Jira → startAt/maxResults（以及 total/isLast），或在较新的端点使用 nextPageToken。参见 references/patterns.md。
• 错误： Jira 返回 ErrorCollection {errorMessages, errors, status}；Confluence 返回内联错误 JSON。遇到 HTTP 429（Jira）时，延迟后重试。

规则

硬性规则（绝不违反）：

• 不使用 SDK，不使用 pip。 API 调用使用 curl；唯一的辅助工具是 scripts/endpoint.py（仅使用 python3 标准库）。
• 绝不读取或打印令牌值。 仅在 curl -u 参数中以 $<token_env> 的形式引用；子进程会从环境中读取它。令牌仅存放在 .env 中（已加入 gitignore）。
• 先解析，再构造。 根据 $ref 解析后的架构（步骤 3）或已验证的富文本格式构造请求正文/参数，绝不要根据猜测或记忆中的字段集构造。
• 按 API 区分，不通用处理。 正确应用 Confluence 与 Jira 各自的模式（基础 URL、分页、富文本、错误）——两者有所不同。
• 富文本： Jira ADF = 原始对象；Confluence atlas_doc_format = value 中字符串化的 ADF。不要混用。
• 此技能绝不写入凭据。 凭据由调用方提供；此技能绝不配置或解析凭据。

偏好（可覆盖）：

• 优先使用较新的 Jira 问题搜索接口 GET /rest/api/3/search/jql（nextPageToken），而不是旧版 /search（startAt）。
• 只请求所需字段（Jira 使用 fields=，Confluence 使用 body-format=），以减少响应大小。

注意事项

• 富文本格式不匹配。 将原始 ADF 对象发送到 Confluence atlas_doc_format（而不是字符串化的对象），或将字符串化内容发送到 Jira（而不是原始对象），是最常见的失败原因。Confluence 的 value 始终是字符串。
• 基础 URL 不同。 Confluence 路径相对于 …/wiki/api/v2；Jira 路径已包含 /rest/api/3。不要重复添加前缀，也不要漏掉 /wiki。
• $ref 链。 请求正文在规范中很少是内联定义的——它会通过 $ref 引用架构（而该架构也可能继续通过 $ref 引用其他架构）。使用解析器（步骤 3）；直接对规范执行 grep 无法获得完整结构。
• Jira 搜索的旧版与新版接口。 GET /rest/api/3/search 正逐步弃用，改用 GET /rest/api/3/search/jql；分页方式不同（startAt 与 nextPageToken）。
• 速率限制。 Jira 返回带有 Retry-After 的 HTTP 429；请遵照该值处理。请求正文过大时，Confluence 可能返回 413。
• Confluence 删除分两步进行（已在线验证，适用于页面、博客文章及其他内容）。DELETE /pages/{id}（或 /blogposts/{id}）只会将其移至回收站（返回 204，但 GET 仍会返回该内容，且状态为 status: trashed）。要永久删除，请调用 DELETE /<type>/{id}?purge=true——该操作仅在内容已移至回收站后才有效（未先移入回收站直接清除则不会执行任何操作）。普通删除并不等于彻底移除。
• Jira /search/jql 会拒绝无范围限制的 JQL（已在线验证）。仅包含排序条件或为空的 JQL → 400 ErrorCollection（“此处不允许无范围限制的 JQL 查询”）。请始终添加搜索限制（例如 project = X、created >= -30d）。

反模式

• 猜测请求正文。 不要凭对“Jira 问题是什么样”的记忆手写请求正文——请解析架构；字段要求会因项目/屏幕而异。
• 回显令牌。 绝不要执行 echo $TOKEN，绝不要将令牌粘贴到你打印的命令中，也绝不要将其值写入任何文件。仅在 curl 中引用环境变量。
• 加载整个规范。 不要将数 MB 的 OpenAPI JSON 用 cat 读取到上下文中——扫描索引，只解析一个操作。
• 一刀切。 不要将 Jira 的分页、错误处理或 ADF 用于 Confluence，反之亦然。
• 引入 SDK。 不要使用 atlassian-python-api 或 pip install——curl 加解析器即可覆盖所有端点。

输出

此技能会产生API 副作用（执行所请求的 Confluence/Jira 操作），并将解析后的 JSON 响应返回给调用它的 Agent。它不会写入任何文件（只会使用调用方注入的凭据）。对于写操作，它会报告已创建/更新的资源（id、key、URL）；对于读取操作，它会返回结果集，并按需进行分页。抽象的使用方是需要执行该操作的调用方 Agent（或子 Agent）；机密信息不会进入输出。

相关内容

• references/credentials.md — 此技能使用的凭据约定（调用方注入的字段 + 有序的令牌加载规则 + 到固定变量的桥接）。
• REST 直连 + 捆绑 OpenAPI 规范这一模式也适用于其他 API 提供方。

渐进式披露

较多的内容存放在子文件夹中，仅在需要时加载：

• references/patterns.md — 各 API 的模式：身份验证、基础 URL、分页（Confluence 游标与 Jira 偏移量/令牌）、响应封装、错误、速率限制、expand。在步骤 4–5 加载。
• references/rich-text.md — ADF（Jira，原始对象）和 Confluence 正文表示（storage / atlas_doc_format，值为字符串），包含示例和跨 API 易错点。构建请求正文时加载。
• references/credentials.md — 此技能使用的凭据约定：调用方注入的字段、有序的令牌加载规则、到固定变量的桥接，以及如实处理机密信息的规则。在步骤 1 加载。
• references/sources.md — 来源信息（Atlassian 官方文档 + 捆绑的规范版本）。

增强阶段（Phase 2.C）新增，见上文：

• assets/confluence-v2.json、assets/jira-v3.json — 捆绑的 OpenAPI 规范（权威来源；按需查询，绝不整体加载）。
• assets/endpoint-index.md — 每个操作一行，用于发现（步骤 2）。
• scripts/endpoint.py + scripts/endpoint.py.validation.md — 用于解析 $ref 的 python3 工具（步骤 3）。
• scripts/<op>.sh + .validation.md — 四个经过验证的 curl 示例（创建 Confluence 页面、列出 Confluence 内容、创建 Jira 工单、搜索 Jira）。
• scripts/md_to_adf.py + .validation.md — 一个基于标准库的 Markdown -> ADF 转换器。将 Markdown 注释/描述通过管道传入，即可将其作为原生 ADF 发布（标题、粗体、代码、链接、列表和 GFM 表格会正常呈现，而不是显示原始的 ##/|）：python3 scripts/md_to_adf.py < comment.md -> Jira {"body": ...} 对应的 ADF 对象。

独立使用（可选，非必需）

这是为手动运行此技能的人类用户提供的便利方式，适用于 Agent 工作流之外；它不是此技能的依赖项。此技能的规范约定是由调用方注入凭据（步骤 1）；本附录仅用于手动操作。

要手动运行，请从 .service-accounts.yaml 记录及其 .env 令牌中自行填入三个固定变量，然后运行脚本。记录示例：

accounts:
  - name: atlassian-work
    provider: atlassian
    base_url: https://workco.atlassian.net
    email: [email protected]
    token_env: ATLASSIAN_WORK_API_TOKEN     # the var holding the token value; value lives in .env (gitignored)

set -a; source .env; set +a                 # loads $ATLASSIAN_WORK_API_TOKEN, never prints it
export ATLASSIAN_EMAIL="[email protected]"
export ATLASSIAN_BASE_URL="https://workco.atlassian.net"
export ATLASSIAN_API_TOKEN="$ATLASSIAN_WORK_API_TOKEN"
bash scripts/create-confluence-page.sh <space-id> "<title>"

在 id.atlassian.com → Security → "Create API token" 中获取 API 令牌。这里只引用令牌值的名称，绝不打印令牌值。

正文大小限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个令牌 — 每轮都会保留在上下文中；各 API 的详细信息存放在 references/ 中。
• assets/*.json 文件很大（在磁盘上按需查询，绝不加载到上下文中）。