atlassian：唯讀 Jira + Confluence
使用時機
- 使用者提到一個票號（
PROJ-123）且你需要其即時狀態、指派者、連結或最近評論。 - 新的票券資料夾需要其 XML：
data/changes/<票券小寫>/<TICKET>.xml。 - 在編輯一份也存在於 Confluence 的文件之前：先比對差異。
工具
位於專案儲存庫中的 data/changes/tools/atlassian/atl.py（課程副本：ejemplos/metodologia/tools/atlassian/）。
需要 Python 3.10+，僅使用標準函式庫（無需 pip 安裝）。從儲存庫根目錄執行。在 macOS、Linux 或 WSL 上使用 python3；在 Windows 上使用 py 或 python。
python3 data/changes/tools/atlassian/atl.py jira issue PROJ-123 # 類型、狀態、摘要、指派者、連結
python3 data/changes/tools/atlassian/atl.py jira search 'project = PROJ AND assignee = currentUser() AND statusCategory != Done'
python3 data/changes/tools/atlassian/atl.py jira links PROJ-123
python3 data/changes/tools/atlassian/atl.py jira comments PROJ-123 --last 3
python3 data/changes/tools/atlassian/atl.py jira xml PROJ-123 --out data/changes/proj-123/
python3 data/changes/tools/atlassian/atl.py confluence search 'title ~ "authoring" AND type = page'
python3 data/changes/tools/atlassian/atl.py confluence page <PAGE_ID> --body
python3 data/changes/tools/atlassian/atl.py confluence diff <local .md/.html> <PAGE_ID>
結束代碼：
| 代碼 | 意義 |
|---|---|
| 0 | 成功 |
| 2 | 憑證遺失或無效（請參閱設定） |
| 3 | HTTP 錯誤 |
| 4 | 找不到 |
--json 回傳原始 JSON。僅在腳本內使用；在對話中使用預設的緊湊格式以節省上下文。
設定（每台機器僅需執行一次，由操作者進行）
建立 ~/.config/<org>/jira.env（Windows：%USERPROFILE%\.config\<org>\jira.env；ATLASSIAN_ENV_FILE 可覆蓋路徑），內容包含三行：
JIRA_BASE_URL=https://<your-site>.atlassian.net
JIRA_EMAIL=<你的 Atlassian 登入信箱>
JIRA_API_TOKEN=<來自 id.atlassian.com → Security → API tokens 的 token>
將權限限制為僅供你的使用者使用（在 macOS/Linux 上使用 chmod 600）。請在你的終端機中撰寫此檔案——絕不要將 token 貼到對話或 data/ 下的檔案中。同一個 token 也可讀取 Confluence。使用 … atl.py jira issue PROJ-123 驗證：回傳代碼 0 表示正常運作，代碼 2 表示檔案遺失或內容錯誤。
嚴格規則
- 唯讀。
atl.py僅發送 GET 請求（一個網路函式；測試會確認這點）。- 建立、編輯、轉移或對 Jira 問題留言是使用者的工作。AI 可以起草文字，然後由使用者發佈。
- 更新現有的 Confluence 頁面請使用
confluence_write.py：pull→plan（備份 + 可見文字差異 + 確認 token）→ 使用者閱讀差異並確認該頁面 →apply --confirm <token>。僅在使用者明確要求更新該頁面時才執行。如果 token、內容檔案或即時頁面版本在 plan 之後發生變更，Apply 會拒絕執行，並重新讀取頁面。
- 絕不列印、貼上或紀錄 token，也不得洩漏
jira.env的內容。 - 使用票號引用問題。 對外文字應引用 case 標籤與票號，絕不使用本機檔案路徑。