atlassian：只读 Jira + Confluence
何时使用
- 用户提到某个问题（如
PROJ-123），需要获取其实时状态、指派人、链接或最近评论。 - 新的问题文件夹需要其 XML：
data/changes/<ticket-lowercase>/<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 → 安全 → API 令牌 获取的令牌>
限制为仅你自己可读（macOS/Linux 上执行 chmod 600）。在你自己的终端中写入——切勿将令牌粘贴到聊天或 data/ 目录下的任何文件中。同一个令牌可用于访问 Confluence。通过以下命令检查：
… atl.py jira issue PROJ-123：退出码 0 表示工作正常，退出码 2 表示文件缺失或错误。
硬性规则
- 只读。
atl.py仅发送 GET 请求（一个网络函数；测试会断言这一点）。- 创建、编辑、转换状态或评论 Jira 问题是用户的工作。AI 代理仅起草文本，由用户发布。
- 更新已有的 Confluence 页面使用
confluence_write.py：pull→plan（备份 + 可见文本差异 + 确认令牌）→ 用户阅读差异并确认该页面 →apply --confirm <token>。仅在用户明确要求更新该页面时才运行。apply会拒绝如果令牌、正文文件或页面版本自plan后发生了变化，并重新读取页面。
- 绝不要打印、粘贴或记录令牌，以及
jira.env的内容。 - 引用问题使用键。 向外发送的文本引用 case 标签和问题键，绝不引用本地文件路径。