it235/multica-best-practices/multica-platform-confluence

Platform · Confluence

Platform 协作

本 skill 为 platform 层；供 artifact / T1 fetch 等按名调用。读：fetch_page.py、fetch_page_by_url.py；写：publish_design.py、PRD HTML。

Purpose

Confluence 读 + 写能力：拉取已有页面供 Agent 消费，把 PRD / 设计等产物落地并回传稳定页面链接。与 multica-platform-jira 解耦。

跨平台：优先 python scripts/*.py（Windows / macOS / Linux）；confluence.sh 为 Unix 便利封装，非必需。

Issue Hub 父页面模型

Issue 创建时已绑定 JIRA 编号；JIRA 描述里的 Confluence 需求页 是该需求的文档根（PRD Hub）。

解析父 pageId：multica-platform-jira → jira_cli.py get-confluence-url / resolve-parent-page-id。

Files

multica-platform-confluence/
├── SKILL.md
├── config.yaml
├── spaces.json
├── .env.example
└── scripts/
    ├── confluence.sh          # Unix 便利封装（可选）
    ├── fetch_page.py          # Confluence pageId → local Markdown
    ├── fetch_page_by_url.py   # URL → Markdown + rich JSON + images（Tester fetch_all）
    ├── publish_design.py      # Markdown 设计 upsert（推荐，跨平台）
    ├── lib/md_to_confluence.py
    ├── lib/html_to_md.py
    ├── requirements.txt
    └── templates/
        ├── prd-template.md
        ├── design-template.md
        ├── backend-api-template.md
        └── frontend-impl-template.md

Read

pip install -r scripts/requirements.txt
python scripts/fetch_page.py <page_id> [output_dir] [jira_key]
 
# 按 URL 拉取（含图片、子页面）— Tester fetch_all 使用
python scripts/fetch_page_by_url.py --url "<confluence-url>" \
  --output out.md --json out.json --image-dir ./images

Unix 可选：bash scripts/confluence.sh fetch-page <page_id> ...

典型链路：JIRA Issue → multica-platform-jira get-confluence-url → 本 skill fetch_page.py 拉 PRD / 设计正文。

Write · 技术设计（Markdown → Confluence）

1. @Architect 写本地 docs/design/<ISSUE-KEY>/design.md（基线见 scripts/templates/design-template.md）。
2. 发布（默认父页面 = JIRA 需求 Confluence 页，并回写 JIRA）：

pip install -r scripts/requirements.txt
python scripts/publish_design.py <ISSUE-KEY> docs/design/<ISSUE-KEY>/design.md \
  --append-jira --json

Upsert 规则：同 space + 同 title 则更新版本；title 自动加 [AI] 后缀。

Write · PRD 页面（HTML）

Unix：bash scripts/confluence.sh create-page ... 或由 multica-pm-artifact-publish 编排调用。

与产物 / 阶段 skill 的关系

完整矩阵见 `docs/platform-collaboration.md`。

Agent Compatibility

• 凭据见 frontmatter；禁止打印密码。
• 外部写入前确认 space、父 pageId、标题。
• 优先 python scripts/，不要裸调 REST。
• 与 JIRA 联调时确保 multica-platform-jira 可解析（MULTICA_SKILLS_ROOT 或同级 templates/skills/）。

Adapting To A New Team

1. 改 config.yaml：confluence.url、default_space、回退 design_parent_page_id。
2. 正常流程靠 JIRA 描述中的 Confluence 需求链接定父页面，无需每需求改 pageId。
3. 新项目追加 projects.<JIRA-PREFIX>.confluence_space。

为什么有效

父页面跟 Issue 走，文档天然聚在需求树下；Python CLI 跨平台；platform skill 集中能力，artifact skill 保持薄层。