it235 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）。
| 产物 | 父页面 | 说明 |
|---|---|---|
| PRD / 需求正文 | 团队默认目录或已有需求页 | PM 落地时创建或更新 |
| 技术设计等后续文档 | JIRA 解析到的 Confluence 需求页 | 作为子页面 upsert |
| 回退 | config.yaml → design_parent_page_id |
JIRA 无 Confluence 链接时 |
解析父 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）
- @Architect 写本地
docs/design/<ISSUE-KEY>/design.md（基线见scripts/templates/design-template.md）。 - 发布（默认父页面 = 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
| 参数 | 作用 |
|---|---|
--append-jira |
发布后调用 multica-platform-jira 追加设计链接到 Issue 描述 |
--parent <pageId> |
显式指定父页面（覆盖 JIRA 解析） |
--no-parent-from-jira |
不从 JIRA 解析；仅用 config 回退父页面 |
--space / --title |
覆盖 space / 标题 |
Upsert 规则：同 space + 同 title 则更新版本；title 自动加 [AI] 后缀。
Write · PRD 页面（HTML）
Unix：bash scripts/confluence.sh create-page ...
或由 multica-pm-artifact-publish 编排调用。
与产物 / 阶段 skill 的关系
| 调用方 | 实际调用 |
|---|---|
multica-pm-artifact-publish |
PRD HTML create-page |
multica-artifact-architect / -backend / -frontend |
publish_design.py |
multica-test-t1-design |
fetch_page_by_url.py（fetch_all 编排） |
完整矩阵见 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
- 改
config.yaml：confluence.url、default_space、回退design_parent_page_id。 - 正常流程靠 JIRA 描述中的 Confluence 需求链接定父页面，无需每需求改 pageId。
- 新项目追加
projects.<JIRA-PREFIX>.confluence_space。
为什么有效
父页面跟 Issue 走，文档天然聚在需求树下；Python CLI 跨平台；platform skill 集中能力，artifact skill 保持薄层。