jira-read

Jira 读取 — 执行规则

从本地缓存快速读取已下载的 Jira 数据，无需访问网络。

配置

使用前设置缓存目录环境变量（建议添加到 .zshrc / .bashrc）：

export JIRA_CACHE_DIR="$HOME/.cache/jira"

如果未设置，默认使用 ~/.cache/jira/。

触发条件与参数

主要触发方式：jira-read [JIRA-ID] — 不区分大小写（会自动转换为大写）

用法	行为	输出模式
jira-read {ID}	读取本地缓存；若缺失则自动从 API 获取	摘要
jira-read {ID} --live	跳过缓存，从 API 获取并更新缓存	摘要
jira-read {ID} --force	强制从 API 获取，覆盖本地缓存	摘要
jira-read {ID} --no-download	仅读取本地；若缺失则提示	摘要
jira-read {ID} --full	与默认行为相同，输出完整内容，包括所有评论	完整
jira-read {ID} --meta	与默认行为相同，仅输出 YAML front matter	元数据
jira-read ID1 ID2 ID3	从本地缓存批量读取	摘要
jira-read --live ID1 ID2 ID3	从 API 批量获取并缓存	摘要
jira-read --force ID1 ID2 ID3	批量强制重新获取（覆盖本地缓存）	摘要
jira-read --list / -l	列出所有本地缓存条目	列表

---

存储路径

• 主文件：$JIRA_CACHE_DIR/{JIRA-ID}.md
• 字段映射缓存：$JIRA_CACHE_DIR/.field-mapping.json

首次使用时，会自动调用 jira_search_fields 来构建字段 ID 映射；后续读取将直接使用缓存。--force 会刷新映射。

---

执行流程

步骤 1：解析 Jira ID

提取 ID（正则表达式：([A-Za-z]+-\d+)）并转换为大写，构建本地文件路径。

步骤 2：检查文件是否存在

文件存在：继续步骤 3

文件不存在：

• 在进行任何 API 调用前，通过凭据链（见下文）解析 PAT
• 默认行为：调用 jira_get_issue(issue_key="{JIRA-ID}", fields="*all", comment_limit=50) → 成功后，格式化并保存，然后继续；失败时，按“错误处理”进行分类
• --no-download：仅提示，不自动下载
• --live：跳过本地检查，从 API 获取并更新缓存
• --force：从 API 获取并覆盖本地缓存

步骤 3：读取、解析并输出

读取 Markdown → 解析 YAML front matter 和正文 → 以结构化 Markdown 输出。

已解析字段：jira_id、title、priority、status、reporter、assignee、created_at、updated_at、downloaded_at、source_url；正文包含问题描述、复现步骤、预期结果／实际结果和评论历史。

附件处理：绝不将附件内容读入 Agent 上下文。如果问题包含附件（日志、截图），请在输出末尾注明。用户需要实际附件（日志）时，请按照下文“附件下载”部分操作。

各场景的输出格式示例：参见 reference.md

---

凭据解析（任何实时获取之前）

在调用 MCP/jira_get_issue、使用 --live/--force 或下载附件之前，先运行此链。mcp-atlassian 是填充第 1 步的可选方式，并非必需。

1. 环境变量 JIRA_PERSONAL_TOKEN（规范名称）
2. 否则使用环境变量 JIRA_PAT（别名；将其复制到 JIRA_PERSONAL_TOKEN，供本次会话后续使用）
3. 否则使用文件 ~/.config/jira-certs/jira-pat.txt（Windows：%USERPROFILE%\.config\jira-certs\jira-pat.txt）——读取首行，去除首尾空白；密钥必须为单行
4. 否则只向用户询问一次 PAT，并询问是否将其写入该文件。令牌存在之前不得进行实时获取。

从环境变量或文件中取得令牌后：不要将 PAT 粘贴到聊天中、命令行参数中或命令预览中；不要在回复或日志中回显；不要将文件内容 cat 到对话中。脚本会自行读取环境变量或文件。

不要教授会插入 PAT 的手动 curl 命令（不得提供“与 Authentication 表等效的 curl 命令”）。此回退方式已被禁止（取代仍未关闭的旧版附件下载差异说明）。

附件下载

始终使用技能脚本将附件下载到本地磁盘——绝不要将附件内容读入 Agent 上下文。若要检查日志内容，只用 grep/head/tail 提取相关行。

身份验证（内部 Jira）

要素	来源	说明
PAT（Bearer）	上述凭据链	规范环境变量 JIRA_PERSONAL_TOKEN；别名 JIRA_PAT；文件 jira-pat.txt
mTLS 客户端证书	JIRA_CLIENT_CERT / JIRA_CLIENT_KEY	默认值：~/.config/jira-certs/client.crt + client.key
SSL	JIRA_SSL_VERIFY=false	内部自签名证书 → curl 使用 -k / node 使用 rejectUnauthorized: false

**凭据（配置字段）：**将 PAT 作为单行内容存入 ~/.config/jira-certs/jira-pat.txt（与 mTLS 证书对位于同一目录；不得放入任何 git 仓库）。格式：单行密钥，不加引号。轮换：替换文件内容和任何已导出的环境变量，然后重试。mcp-atlassian 可能会注入 JIRA_PERSONAL_TOKEN，而非使用该文件。

附件 URL

直接使用 jira_get_issue 返回的 attachment[].url，例如： https://jira.example.com/secure/attachment/{attachmentId}/{filename}

下载脚本

先检查 curl -V。如果输出包含 Schannel（Windows 上常见），或无法使用 PEM 格式的 --cert/--key，必须使用 node sidecar。否则可以使用 bash 脚本。

# Node (Windows / Schannel curl)
node scripts/download_jira_attachments.mjs 100001 app-log-1700000000000.zip /tmp/logs/PROJ-1234.zip

# Bash + OpenSSL curl (PEM --cert/--key)
scripts/download_jira_attachments.sh 100001 app-log-1700000000000.zip /tmp/logs/PROJ-1234.zip

两种方式都会从凭据链中解析 PAT（Bearer，Basic 为回退方式）。使用 JIRA_CLIENT_CERT / JIRA_CLIENT_KEY 覆盖证书路径。设置 JIRA_URL（例如 https://jira.example.com）。绝不要将 PAT 放在命令行中。

下载与归档流程

1. 解析凭据（使用上述链），然后调用 jira_get_issue(issue_key=..., fields="summary,description,attachment,status,priority") 获取 attachment[].id / filename / url
2. 使用选定的脚本下载到临时目录——先下载 1 个文件以验证身份验证，然后批量下载
3. 使用 unzip -l 预览 zip 结构；确认结构是平铺的，然后再解压
4. 将文件归档到项目中的 issues/{type}/jira-bug/{JIRA-ID}-app-log/，并写入 {JIRA-ID}.md，记录工单信息和附件列表

下载结果报告格式：参见 reference.md § 7

---

缓存时效提示

缓存时长	提示
< 1 小时	无
1–24 小时	“缓存于 X 小时前”
1–7 天	“缓存于 X 天前，建议更新”
> 7 天	“缓存已过期（X 天前），强烈建议更新”

---

错误处理

错误场景	处理方式
Jira ID 格式无效	提示正确的格式
未找到文件	自动从 API 获取（仅在使用 --no-download 时提示）
凭据链为空（env + alias + file）	询问并持久化（不要视为 401）
mcp-atlassian 不可用	缺少可选注入器：仍使用凭据链；如果需要 issue JSON，在解析 PAT 后尝试使用缓存 / jira-read --live；不要仅因 MCP 缺失而中止
使用已解析的令牌时出现 HTTP 401 / 403	令牌无效或已撤销——轮换令牌并更新 jira-pat.txt（如果设置了 env，也要更新）
TLS 握手 / 客户端证书	检查 client.crt / client.key 和 TLS 1.3；在 Windows 上不要使用 Schannel curl 进行 PEM mTLS——请使用 node sidecar
未找到 issue	提示 Jira ID 可能不正确
文件解析失败	输出原始文件内容