Jira Server / Data Center CLI

Purpose

为任意 Jira Server / Data Center 实例提供可迁移、可审计、无环境隐私的命令行管理方案。优先使用 Jira 官方 REST API 与运行时元数据发现，绝不把单个组织的配置写进本 Skill。产出是可复现的命令 序列与结构化 JSON 结果，而不是绑定某个实例的一次性脚本。

When to Use

• 用户要求通过脚本或 CLI 管理 Jira Server / Data Center。
• 实例使用 PAT、2FA、SSO、Cookie、Basic Auth、内部 CA 或自签证书。
• 任务涉及项目、issue、JQL、transition、评论、工时、附件、链接、watcher、权限或字段元数据。
• 触发词：Jira Server CLI、Jira Data Center 脚本、Jira PAT、jira_cli、Jira 自托管 REST。

When NOT to Use

• Jira Cloud — API token、accountId、REST v3 与 Atlassian Document Format 语义不同，本 Skill 的 payload 与鉴权假设不成立。
• 用户只要 Jira Web 页面操作、不需要 REST 或 CLI。
• 目标接口属于第三方 Jira 插件，且尚未核对插件文档与版本。

Workflow

1. 确认产品与版本。先确认目标是 Server / DC 而非 Cloud，再调用 python3 scripts/jira_cli.py server-info。记录但不持久化：Jira 版本与 build number、Base URL 是否含 context path（如 /jira）、是否安装 Jira Software / Service Management、REST 版本与目标 endpoint 是否存在。不要用 /login.jsp 作为 Server/DC 的唯一识别依据。
2. 选择鉴权。按 ## Decision Rules 的优先级选定鉴权方式；用户一旦提供 PAT 立即持久化，后续 直接读取配置，不再重复索取。
3. 配置 TLS。默认走系统信任链，其次指定组织 CA PEM，--insecure 仅限临时诊断。
4. 先探测，再写入。至少执行 whoami、server-info、projects、 permissions --project PROJ 四个只读命令，确认身份、实例与权限后再考虑写入。
5. 发现运行时元数据。构造 create / update / transition payload 前，先按 references/field-metadata.md 发现 issue type、字段、transition 的 ID 与可用字段集合。禁止使用 跨实例固定回退 ID。
6. 处理分页与输出。所有列表与 JQL 搜索都要处理 startAt、maxResults、total，不能假设一次 返回全部结果。默认输出 JSON，便于 jq、脚本与 Agent 做确定性解析；不要把面向人的表格文本当作 程序输入。
7. 写操作先 dry-run 或读后写。创建、更新、transition 都支持 --dry-run，例如 create PROJ Bug "Example" --dry-run、update PROJ-123 --summary "Updated" --dry-run、 transition PROJ-123 "In Progress" --dry-run。真实写入前逐项确认：当前用户身份、项目与 issue 是否正确、权限是否满足、字段是否在 create metadata 或 edit metadata 中、transition 是否在当前 issue 的可用列表中、destructive 操作是否得到用户明确确认。
8. 交付前自检。执行 ## Verification 的命令，并复述实际访问的实例类型与只读/写入范围。

Decision Rules

• 目标判定为 Cloud -> 停止并说明本 Skill 不适用，不要尝试用 Server/DC 假设绕过。
• 鉴权优先级：OAuth 2.0 > PAT Bearer > Basic Auth > 浏览器 Cookie（Cookie 仅为临时排障兜底）。 PAT 通过 Authorization: Bearer <token> 发送，不附加用户名；新实例先用 whoami 验证。
• whoami 返回 401 / 403 -> 按 references/auth-and-tls.md 的五步顺序排查，不要直接断言被 SSO 接管。
• 需要 TLS 定制、context path、反向代理或 2FA/SSO 细节 -> 读 references/auth-and-tls.md。
• 需要字段 / issue type / transition 的 ID 发现、名称本地化与歧义处理 -> 读 references/field-metadata.md。
• 需要判断 API 根路径、create metadata 版本行为、用户字段或描述格式差异 -> 读 references/version-differences.md。
• 收到非 2xx 状态码、需要判断是否重试 -> 读 references/troubleshooting.md。
• 目标能力没有专用子命令（agile、Service Management、插件端点、管理类接口）-> 用 request 发起受控 REST 调用，并在执行前核对目标版本文档。
• 需要具体命令、参数与配置字段 -> 读 references/command-reference.md。

Constraints

• 绝不硬编码实例域名、IP、用户名、邮箱、项目 Key、issue Key、PAT、Cookie、自定义字段 ID、 issue type ID、transition ID 或内部目录——无论出现在 Skill、脚本、示例、测试还是日志中。
• 示例只使用 jira.example.com、PROJ、PROJ-123、alice、customfield_12345 等明确占位值。
• 不主动要求用户把 PAT 发到聊天中；优先让用户通过 JIRA_PAT、权限 0600 的配置文件或 secret manager 注入。若用户已在对话中提供 PAT，立即持久化到本地配置，后续直接读取；不得把 PAT 写入 Skill 文件、脚本、日志、命令行参数或输出。
• 不输出请求头、Cookie、PAT 或包含凭证的配置全文；报错与 debug 输出必须脱敏。
• 不把实例探测结果写回 Skill，实例元数据只用于当前执行。
• destructive 命令必须显式确认：附带 CLI 对 issue、评论、工时、附件、链接删除以及所有 raw POST / PUT / DELETE 使用 --yes 门禁。
• 字段优先用 ID 提交，但 ID 必须来自当前实例的运行时发现；名称匹配只用于交互便利。

Priority

规则冲突时按此顺序取舍，序号越小越具约束力：

1. 隐私与安全约束 高于任务完成。任何需要写入真实域名、凭证或内部标识才能继续的方案，改为 报错并向用户说明。
2. 只读探测 高于写入。未确认身份、权限与字段可用性之前，不得执行写入。
3. 运行时发现的元数据 高于任何默认值或历史记忆中的 ID。
4. destructive 显式确认 高于用户的进度诉求，未确认不得凭 --yes 之外的隐含授权执行。

Stop Conditions

• 鉴权按 references/auth-and-tls.md 的排查顺序走完仍为 401 / 403 -> 停止，把排查结论交回用户， 不要循环重试或猜测凭证。
• 目标实为 Jira Cloud，或必需能力依赖未核对文档的第三方插件 -> 停止并说明缺口。
• 需要 destructive 操作但用户未明确确认 -> 停止，等待确认。
• 同一写操作在 409 / 429 / 5xx 后仍无法确认服务端状态 -> 停止，不要重复提交非幂等写入。

Verification

交付或修改 Jira CLI 后必须完成：

python3 -c "import ast,pathlib; ast.parse(pathlib.Path('scripts/jira_cli.py').read_text())"
python3 scripts/jira_cli.py --help
python3 scripts/jira_cli.py create --help
python3 scripts/jira_cli.py request --help
python3 -m unittest scripts/test_jira_cli.py

• 所有命令可运行，帮助信息完整。
• 离线契约测试通过。
• 无真实域名、凭证、项目 Key 或内部字段 ID 出现在任何改动文件中。
• 工作区未留下 __pycache__ 等字节码缓存（py_compile 会在 scripts/ 下生成，改用上面的 ast.parse 检查即可避免）。

有可用测试实例时，再做只读 smoke test：server-info、whoami、projects。真实写入测试必须使用 专用测试项目与无敏感内容的临时 issue，完成后按用户确认清理测试数据，不把真实结果写回 Skill。

Output

• Outcome：一组可复现的 jira_cli.py 命令及其 JSON 结果，或对目标实例能力的明确结论。
• Done when：命令已实际运行、结果以 JSON 形式返回并解释、## Verification 清单全绿、未落盘任何 实例私有信息。
• Evidence：命令与参数（脱敏后）、返回状态与关键字段、只读/写入范围说明。

References

按需加载，不要预先全读：

• references/command-reference.md — 需要具体子命令、参数、配置文件字段或环境变量清单时读；查 版本相关能力分组与官方依据时也读这里。
• references/auth-and-tls.md — 实例自托管、启用 2FA/SSO、位于反向代理后、使用内部 CA/自签证书， 或 whoami 返回 401/403 时读。
• references/field-metadata.md — 构造 create/update/transition payload 前读，用于发现字段与 issue type ID 并处理本地化与同名歧义。
• references/version-differences.md — 选择 API 根路径、create metadata 行为异常、用户字段或描述 格式在版本间不一致时读。
• references/troubleshooting.md — 收到非 2xx 响应、需要决定是否重试时读。

Scripts

• scripts/jira_cli.py — 无第三方依赖的 REST CLI。用 python3 scripts/jira_cli.py <command> --help 查看子命令，返回 JSON 到 stdout；非零退出码表示失败。断言实例信息、构造 payload、执行 CRUD 前 以它为准。
• scripts/test_jira_cli.py — 离线契约测试，用内置 HTTP stub 验证分页、issue type 解析、transition 名称解析、destructive --yes 门禁与配置加载。改动 jira_cli.py 后运行它，不需要真实实例。