confluence

使用 orbit CLI 管理 Confluence

使用 orbit CLI 管理 Confluence 页面、发布 Markdown 文档并控制页面布局。通过 REST API 支持 Confluence Cloud 和 Server/Data Center，支持多配置文件和 1Password 密钥解析。

前提条件

1. 已安装 orbit CLI — 如果 which orbit 执行失败，请通过以下方式安装：
   • macOS/Linux（Homebrew）： brew install jorgemuza/tap/orbit
   • macOS/Linux（脚本）： curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh
   • Windows（Scoop）： scoop bucket add jorgemuza https://github.com/jorgemuza/scoop-bucket && scoop install orbit
2. 在 ~/.config/orbit/config.yaml 中配置了 confluence-cloud 或 confluence-server 服务的配置文件
3. 有效的凭据（Cloud 使用 API 令牌，Server 使用 PAT）——可存储为 1Password（op://）或 Infisical（infisical://）引用
4. 对于 Cloud：身份验证类型为 basic，用户名为电子邮件地址，密码为 API 令牌

快速参考

所有命令均遵循以下格式：orbit -p <profile> confluence <command> [flags]

完整的命令详情和标志请参见 references/commands.md。 Confluence 存储格式（XHTML）的详情请参见 references/storage-format.md。

核心工作流

查看页面

# View page details
orbit -p myprofile confluence page 473676972036

# View as JSON (includes body content)
orbit -p myprofile confluence page 473676972036 -o json

# List child pages
orbit -p myprofile confluence children 473676972036

# Show full page hierarchy (ancestors + descendants tree)
orbit -p myprofile confluence hierarchy 473676972036

# Deeper tree (default depth is 2)
orbit -p myprofile confluence hierarchy 473676972036 --depth 5

# JSON tree output
orbit -p myprofile confluence hierarchy 473676972036 -o json

审阅页面（评论）

直接通过 CLI 在页面上添加审阅评论——无需打开浏览器，即可为已发布的文档提供反馈。

# List all comments on a page (footer + inline, including replies)
orbit -p myprofile confluence comment list 473676972036
orbit -p myprofile confluence comment list 473676972036 -o json

# Add a comment (body is Markdown by default)
orbit -p myprofile confluence comment add 473676972036 --body "LGTM, but the sandbox URL is stale."

# Add a multi-line/Markdown review from a file
orbit -p myprofile confluence comment add 473676972036 --from-file review.md

# Reply to an existing comment (thread)
orbit -p myprofile confluence comment add 473676972036 --body "Fixed in v0.60.2" --reply-to 67890

# Anchor an inline comment to specific page text (Confluence Cloud; best-effort)
orbit -p myprofile confluence comment add 473676972036 \
  --body "This line is inaccurate — deploys are on-demand, not nightly." \
  --inline-text "deploys run nightly"

# Delete a comment (prompts in a terminal; use --yes in scripts/CI)
orbit -p myprofile confluence comment delete 67890 --yes

行内锚定尽力而为，且仅适用于 Cloud。 --inline-text 必须与页面文本完全一致，否则服务器会拒绝；如有疑问，请省略此选项，并在评论正文中引用相应行——在 Server 和 Cloud 上，页脚评论都能 100% 可靠地添加。

搜索页面

# Search by space
orbit -p myprofile confluence search --space FO

# Search by title (fuzzy match)
orbit -p myprofile confluence search --space FO --title "Architecture"

# Search by label
orbit -p myprofile confluence search --space FO --label design

# Full-text search
orbit -p myprofile confluence search --space FO --text "deployment pipeline"

# Raw CQL query
orbit -p myprofile confluence search --cql 'space=FO AND label=design AND type=page'

# Increase result limit (default 25)
orbit -p myprofile confluence search --space ISMS --limit 100

从 Markdown 创建页面

从 Markdown 文件创建页面时，CLI 会自动将其转换为 Confluence 存储格式（XHTML）。转换器可处理标题、列表、表格、代码块、引用块、行内格式和图片。

# Create page from markdown file
orbit -p myprofile confluence create --space FO --parent 473677299713 \
  --title "My New Page" --file docs/overview.md

# Create page with inline body (storage format XHTML)
orbit -p myprofile confluence create --space FO --parent 473677299713 \
  --title "Quick Page" --body "<p>Hello world</p>"

页面会自动以宽幅（全宽布局）创建。

更新现有页面

提供 --file 时，update 命令会自动从 frontmatter 读取标题、同步 confluence_labels 中的标签、在页面开头添加 confluence_properties 中的页面属性，并设置全宽布局——与 publish 命令的行为一致。使用 --title 可覆盖 frontmatter 中的标题。

# Update page from markdown (title, labels, properties auto-synced)
orbit -p myprofile confluence update 473676972036 --file docs/overview.md

# Override title explicitly
orbit -p myprofile confluence update 473676972036 \
  --title "Custom Title" --file docs/overview.md

# Update with inline storage format
orbit -p myprofile confluence update 473676972036 --body "<p>New content</p>"

发布包含 Markdown 文件的目录

publish 命令会递归地将整个 Markdown 文件目录转换为 Confluence 页面，并保留文件夹层级：

• INDEX.md 文件会成为其所在目录的父页面
• 其他 .md 文件会成为该目录父页面下的子页面
• 子目录会递归处理
• 页面标题取自 frontmatter 中的 title:、首个 # heading 或文件名
• confluence_ignore: true 的文件会被跳过；如果之前已发布，对应的 Confluence 页面会被删除。忽略 INDEX.md 时，整个子目录都会被跳过。
• 插入或更新行为：如果页面的 frontmatter 中没有 confluence_page_id，orbit 会先按标题搜索。如果因标题冲突（例如标题中的 & 等特殊字符）导致创建失败，则会改为列出父页面的子页面并更新匹配页面。成功后，confluence_page_id 会写入 frontmatter，供后续运行使用。
• 每次创建和更新时，所有页面都会设为全宽布局。

# Publish entire docs directory
orbit -p myprofile confluence publish ./docs --space FO --parent 473677299713

# Preview what would be created (no API calls)
orbit -p myprofile confluence publish ./docs --space FO --parent 473677299713 --dry-run

图表渲染

带有图表语言标记的围栏代码块会自动通过 Kroki 渲染为图片——无需安装 Confluence 插件。除非配置了其他实例（请参见下文的选择 Kroki 渲染服务），否则会通过公共 https://kroki.io 进行渲染。支持的语言：mermaid、plantuml、graphviz、dot、d2、ditaa、erd、nomnoml、svgbob、vega、vegalite、wavedrom、pikchr、structurizr、excalidraw、c4plantuml。

```mermaid
graph LR
    A-->B
    A-->C
```

这会渲染为 PNG 图片（最大宽度 600px、高度 800px——自动缩放），并附带指向原始分辨率图片的可点击链接。常规代码块（python、go、bash 等）不受影响。如果 Kroki 拒绝某个图表（语法错误），则会回退为带语法高亮的代码块。

选择图表的渲染方式。 --diagrams 为整个运行过程选择三种策略之一；文件 frontmatter 中的 confluence_diagrams 为该文件选择一种策略；Confluence 服务上的 options.diagrams 则为该实例选择一种策略。每次只能选择一种，优先采用最具体位置的设置：命令调用，其次是文件，再次是实例，最后是默认值。

策略	作用
kroki	使用 Kroki 实例将每个图表渲染为 PNG。默认策略。
markdown-macro	将 mermaid 包装在 Confluence markdown 宏中，由应用在读者的浏览器中渲染——图表在 Confluence 中保持动态、矢量且可编辑。绝不会联系 Kroki，无论 Kroki 位于何处：其他图表语言会保留为代码块，而不会发送出去，因为在运行中的实例上，只有 .language-mermaid 会触发应用的 mermaid.init；将其他内容发送给渲染器会违背选择此策略的初衷。如果希望渲染这些图表，请按文件或按运行过程指定 kroki。
code-block	将每个图表保留为预格式化文本（ASCII），不调用任何服务。

markdown-macro 永远不会是默认策略：该宏由一个并非每个 Confluence 实例都安装的应用提供，如果页面包含实例不支持的宏，图表所在位置就会显示错误。只有当实例确实安装了该应用时，才应在服务上设置 options.diagrams: markdown-macro，因为这是 Confluence 实例的属性，而非某次发布的属性。使用此策略时，图表源代码会原样传递——以下清理仅适用于 Kroki 路径。

--no-kroki 和 confluence_disable_kroki: true 仍然有效，且都表示使用 code-block。同一位置的两个选项名称如果设置不一致——例如 --no-kroki 与 --diagrams，或 confluence_disable_kroki 与 confluence_diagrams——会报错，而不会静默选用其中一个；无法识别的策略名称也会报错。不同层级之间互相覆盖不属于冲突，这正是设置层级的用途。以上规则同样适用于嵌套在 <details> 块中的图表。

选择 Kroki 渲染器。 除非某次运行指定其他实例，否则图表会发送到 https://kroki.io。按优先级从高到低：

1. publish、create 或 update 命令中的 --kroki-url <url>——普通 URL，仅对本次运行生效。
2. Confluence 服务上的 options.kroki_service: <name>——同一配置文件中的 type: kroki 连接，适用于需要身份验证、代理或此计算机不信任的证书（tls_skip_verify）的实例。其 http_timeout 是每个图表的处理时限（默认 30s），options.concurrency 是同时渲染的数量（默认 4）。
3. Confluence 服务上的 options.kroki_url: <url>——普通 URL，无需身份验证，且证书有效。
4. https://kroki.io。

在同一服务上同时指定 kroki_service 和 kroki_url 会报错，而不是按优先级排序：它们是同一设置的两种名称。没有用于指定实例的 frontmatter 键——哪些渲染器可访问取决于环境，而非文档。orbit service ping <name> 可像检查其他服务一样检查 kroki 连接。完整参考请见：docs/confluence.md。

Mermaid 图表会在渲染前自动清理，以修复常见的 Kroki 兼容性问题：

• 移除 <br/> 标签（替换为 . ）
• 转换参与者别名中括号内的后缀：Worker (queue) → Worker - queue
• 移除参与者名称末尾的 ()
• 移除冒号后的端口号：API:8000 → API
• 翻转反向箭头：Client<<--API: msg → API-->>Client: msg 为 Confluence 发布编写 Mermaid 图表时，请避免：
• 在参与者名称或备注中使用 HTML 标签（<br/>）
• 在参与者别名文本中使用冒号（例如，API:8000）
• 在参与者别名中使用括号（例如，Worker(queue)）
• 在别名中使用函数调用语法（例如，dispatch()）
• 使用反向箭头（<<--）——Mermaid 仅支持从左到右的箭头
• 使用 ASCII 框线字符——请改用正确的 Mermaid 语法
• 在边标签 |...| 中使用未加引号的 [ ] ( )——Mermaid 解析器会将其解释为形状起始符并报错，提示 Expecting 'SQE' / 'PE'。请用双引号括起整个标签：A -->|"secrets[].valueFrom"| B 和 A -->|"on_end (already shaped)"| B。自动清理器无法修复此问题。

Kroki 渲染失败时，请先定位出问题的图表块，再进行排查。 orbit CLI 会输出 Kroki failed to render mermaid diagram，但不会指出是哪一个图表块。要找到问题所在，请将每个图表块直接 POST 到 Kroki，并查看实际的解析错误——错误消息中的行号指的是图表正文中的行，而非 Markdown 文件中的行。请向发布所用的实例发送请求（下方 URL 是公共实例；如果配置文件中指定了其他实例，请替换为该实例，因为不同实例的渲染器版本可能不同）：

python3 - <<'PY'
import re, json, subprocess
text = open("path/to/doc.md").read()
for m in re.finditer(r"```mermaid\n(.*?)```", text, re.DOTALL):
    ln = text[:m.start()].count("\n") + 1
    payload = json.dumps({"diagram_source": m.group(1), "diagram_type": "mermaid", "output_format": "svg"})
    r = subprocess.run(["curl","-sS","-w","\n%{http_code}","-H","Content-Type: application/json",
                        "--data-binary", payload, "https://kroki.io/"],
                       capture_output=True, text=True, timeout=30)
    body, code = r.stdout.rsplit("\n", 1)
    print(f"L{ln}: {'OK' if code=='200' else 'FAIL '+code+' '+body[:300]}")
PY

注意：不要使用 Python 的 urllib 访问公共 kroki.io——Cloudflare 会因默认 UA 而拦截请求，并返回 error code: 1010。请使用 curl（如上所示），或设置浏览器的 User-Agent 标头。可自托管的实例通常没有此限制。

导出页面

# Export page as markdown (default)
orbit -p myprofile confluence export 12345

# Export to a directory
orbit -p myprofile confluence export 12345 --format markdown --output docs/

# Export raw storage format
orbit -p myprofile confluence export 12345 --format storage --output backup/

移动／更改页面父级

当仓库布局发生变化，Markdown 文件移至新目录时，已发布的 Confluence 页面仍会保留在原父级下，直到你更改其父级。使用 move 更新父级，而不修改页面正文或标题。

# Move page 895422142 under a new parent
orbit -p myprofile confluence move 895422142 --parent 878970411

新父级必须位于同一空间。Confluence 会拒绝跨空间移动和循环移动（将页面移至其某个后代页面之下）。

设置页面宽度

# Set single page to wide
orbit -p myprofile confluence set-width 473676972036

# Set page and all children to wide
orbit -p myprofile confluence set-width 473676972036 --recursive

# Set to fixed width
orbit -p myprofile confluence set-width 473676972036 --width fixed

Markdown Frontmatter 跟踪

在为 Confluence 发布或转换 Markdown 文件时，请使用 YAML frontmatter 跟踪本地文件与 Confluence 页面之间的映射。创建或更新页面后，请在源 Markdown 文件的 frontmatter 中更新：

---
title: "My Page Title"
confluence_ignore: false
confluence_page_id: "473676972036"
confluence_url: "https://mysite.atlassian.net/wiki/spaces/FO/pages/473676972036/My+Page+Title"
---

这样可以：

• 无需查找页面 ID，即可重新运行更新
• 跟踪已发布的文件
• 构建将本地更改同步到 Confluence 的脚本
• 使用 confluence_ignore: true 将文件排除在 Confluence 之外（删除先前发布的页面）

当用户要求将 Markdown 文件发布或同步到 Confluence 时：

1. 运行 orbit 命令来创建／更新页面
2. 从输出中获取页面 ID 和 URL
3. 在 Markdown 文件的 frontmatter 中更新 confluence_page_id 和 confluence_url
4. 如果 frontmatter 不存在，请在文件顶部添加

同步文件的工作流示例：

# If confluence_page_id exists in frontmatter, update (title auto-read from frontmatter):
orbit -p myprofile confluence update 473676972036 --file docs/overview.md

# If no confluence_page_id, create new:
orbit -p myprofile confluence create --space FO --parent 473677299713 \
  --title "Overview" --file docs/overview.md
# Then update the frontmatter with the returned page ID and URL

页面属性和标签

publish 命令支持通过 frontmatter 设置 Confluence 页面属性宏和标签，从而支持动态页面属性报告表（例如 ISMS Policies 页面模式）。

标签

在 frontmatter 中添加 confluence_labels，为页面添加标签。在 publish 期间，每次创建或更新页面后都会应用标签。

---
title: "My Policy"
confluence_labels:
  - ai-process
  - foundation
---

页面属性（details 宏）

在 frontmatter 中添加 confluence_properties，即可在页面顶部生成 Confluence 页面属性宏。这会创建一个结构化元数据块，供其他页面上的页面属性报告宏查询。

---
title: "Compounding Engineering & System Evolution"
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
    Approved on: 2026-03-06
---

• id -- 设置宏 ID（供 detailssummary 报告定位特定属性块）
• fields -- 按顺序排列的键值对，在宏内以两列表格形式呈现
• 与 {status:Color|Text} 匹配的值会转换为状态徽章宏（也支持 :green_circle: Green 等 emoji 短代码）
• 与 YYYY-MM-DD 匹配的值会转换为 Confluence <time> 日期宏
• 其他值会以纯文本形式呈现

页面属性报告（detailssummary 宏）

在 Markdown 中添加指令，即可生成一个动态表格，从带标签的页面中提取页面属性。支持两种格式：

HTML 注释格式（完全控制）：

简写格式：

{properties-report: label="ai-process", columns="Status, Classification, Reviewed on"}

参数：

• cql -- 用于查找页面的 CQL 查询（例如，label = "policy" and space = currentSpace()）
• label -- CQL 的简写形式：生成 label = "value" and space = currentSpace()
• firstcolumn -- 第一列的名称（默认为 "Title"）
• columns / headings -- 要显示为列的属性名称列表，以逗号分隔
• sortBy -- 可选的排序列

完整示例

子页面（例如，overview.md）：

---
title: Overview & Philosophy
confluence_labels:
  - ai-process
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
---

索引页面（例如，INDEX.md）：

---
title: AI Development Process
confluence_labels:
  - ai-process
---

# AI Development Process





| Document | Version | Summary |
|----------|---------|---------|
| [Overview & Philosophy](./overview.md) | v2.0 | Core principles, four layers |

在 Confluence 上，仅呈现属性报告宏（静态表格会被忽略）。在 Markdown 查看器（GitHub、本地）中，静态表格会与 HTML 注释指令一同显示（注释不可见）。

Markdown 到 Confluence 的转换

转换器会执行以下转换：

Markdown	Confluence 存储格式
# Heading（第一个）	跳过——Confluence 会显示页面标题
## Heading 到 ###### Heading	<h2> 到 <h6>
**bold**	<strong>
`code`	<code>
~~strike~~	<del>
- bullet / * bullet	<ul><li>
1. numbered	<ol><li>
> blockquote	信息面板宏
```lang 代码块	带语言的代码宏
| table | rows |	带 <thead> 的 <table>
	<ac:image>
[text](url)	<a href>（相对 .md 链接会解析为 Confluence 页面链接）
--- 水平分隔线	<hr />
YAML frontmatter	移除
**Key**: Value 元数据行	两列表格（灰色标签列）
``	TOC 部分替换为 Confluence toc 宏
confluence_properties frontmatter	Page Properties（details）宏
``	Page Properties Report（detailssummary）宏
{properties-report: ...}	Page Properties Report（detailssummary）宏
``	跳过标记之间的内容（不会发送到 Confluence）

需要向用户说明的关键行为：

• 始终跳过第一个 # heading，因为 Confluence 已经会显示页面标题
• 发布目录时（使用 publish 命令），相对 Markdown 链接（.md、./）会解析为 Confluence 内部页面链接。链接映射会将相对路径映射到页面标题，并生成 <ac:link> 宏。单独转换文件且没有链接映射时，相对链接会退回为纯文本
• 用 / 指令包裹的 TOC 部分会替换为 Confluence 内置的 TOC 宏。支持以下参数：maxLevel、minLevel、style、outline、printable（例如 ``）。默认情况下，节编号（outline）为 false，以避免 Markdown TOC 已使用编号列表时出现重复编号
• 代码块和表格使用全宽布局
• frontmatter 后紧接的文档元数据行（**Key**: Value）会转换为带样式的两列表格，标签为灰色
• 带语言提示的代码块会通过代码宏启用语法高亮
• frontmatter 中的 confluence_labels 会在 publish 期间为页面添加标签
• frontmatter 中的 confluence_properties 会生成 Page Properties 宏，并将其置于页面内容前
• Properties Report 指令会生成动态表格，用于查询带标签的页面
• 转换期间会移除 / 块——其中的内容会被完全跳过。这适用于 INDEX 页面：这类页面需要静态 Markdown 表格供 GitHub/本地渲染，同时需要动态 Properties Report 宏供 Confluence 使用。代码块内的 Ignore 指令会被视为字面文本，不会进行处理

重要说明

• 默认使用宽版布局——通过 orbit 创建的所有页面都会自动设为全宽布局。使用 set-width --width fixed 可恢复为固定宽度。
• Cloud 与 Server——Atlassian Cloud 使用服务类型 confluence-cloud（API 路径需要 /wiki/ 前缀，系统会自动处理）。Data Center 使用 confluence-server。
• Cloud 身份验证——使用基本身份验证，用户名为你的邮箱，密码字段填写 API 令牌（而不是你的密码）。
• 密钥引用——配置中的凭据可以使用 1Password（op://vault/item/field）或 Infisical（infisical://<env>/<path>/<KEY>）引用，并在运行时解析。运行一次 orbit auth 可解析并缓存所有密钥（使用 1Password 时只需进行一次生物识别验证）。使用 orbit auth clear 可清除缓存。请参阅 密钥。
• 发布前先试运行——发布目录时，始终先使用 --dry-run 预览页面层级，再调用 API。