Jira Flow Skill（免费版）

面向个人开发者与小型团队的 Jira 任务管理工具，通过命令行脚本完成日常任务流转、工时记录与检索查询。

概述

Jira Flow Skill 将 Jira Cloud REST API 封装为简洁的命令行调用，让开发者在终端即可完成"查任务、改状态、记工时、看汇总"的完整闭环。免费版覆盖个人开发者 90% 的日常 Jira 操作，无需切换浏览器即可保持工作流连续。

核心价值

• 命令行即工作流：单条命令完成一个完整操作，无需多步点击
• 状态流转校验：自动拉取服务端允许的流转列表，杜绝无效状态变更
• 工时 JSON 输出：工时统计结果直接输出 JSON，可被其他脚本消费
• 零侵入集成：基于环境变量配置，不修改 Jira 项目配置

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Jira、Cloud、REST、API、管理任务、状态流转与工时记、适合个人开发者日、常追踪、Flow、Skill、是面向个人开发者、与小型团队的、任务管理辅助工具、通过命令行脚本驱、完成日常事务流转、核心能力、任务检索与详情查、状态流转与分配、工时记录与统计、评论与创建任务、覆盖一名开发者日、常所需的、Use、when、需要项目管理、任务规划、进度跟踪、团队协作时使用、不适用于实际人员、绩效评估等。

使用场景

场景一：每日站会前快速查看自己未完成的任务

开发者每天站会前需要回顾自己当前的待办。执行 my 命令即可列出所有分配给自己且未关闭的任务，包括键值、摘要与状态，10 秒内完成站会准备。

场景二：修复缺陷后记录工时并更新状态

完成一个缺陷修复后，需要同时记录工时与更新状态。两条命令串联即可：

1. log BUG-456 2.5 记录 2.5 小时工时（默认今天）
2. status BUG-456 "Done" 更新状态为完成（自动校验流转合法性）

场景三：周报工时汇总

每周五需要汇总本周工时投入分布。执行 hours 2025-01-06 2025-01-12 即可获得本周按任务分组的工时 JSON，可直接喂给周报生成脚本。

场景四：模糊检索历史任务

只记得任务摘要里的关键词，想快速定位任务键值。执行 search "支付超时" 即可模糊匹配包含该关键词的任务。

快速开始

前置准备（约 60 秒）

1. 访问 Atlassian API Token 管理页：https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击"Create API Token"生成令牌
3. 配置环境变量：

export JIRA_EMAIL="you@example.com"
export JIRA_API_TOKEN="你的API令牌"
export JIRA_URL="https://your-domain.atlassian.net"
# 可选：限定项目范围（逗号分隔），留空则搜索全部项目
export JIRA_BOARD="ABC"

依赖详情

执行以下命令，能正常返回任务列表即代表配置成功：

bash {baseDir}/（请参考skill目录中的脚本文件） my 5

运行环境要求

• 命令行工具：curl、jq、bc、python3
• 操作系统：Windows（需 WSL 或 Git Bash）/ macOS / Linux
• 网络：可访问 atlassian.net 域名

示例

环境变量配置表

常用命令速查

# 检索任务
bash {baseDir}/（请参考skill目录中的脚本文件） search "登录超时" 10
# ...
# 查看任务详情
bash {baseDir}/（请参考skill目录中的脚本文件） issue ABC-123
# ...
# 更新状态（自动校验流转）
bash {baseDir}/（请参考skill目录中的脚本文件） status ABC-123 "In Progress"
# ...
# 分配给自己
bash {baseDir}/（请参考skill目录中的脚本文件） assign-me ABC-123
# ...
# 添加评论
bash {baseDir}/（请参考skill目录中的脚本文件） comment ABC-123 "已修复并部署到预发"
# ...
# 创建任务
bash {baseDir}/（请参考skill目录中的脚本文件） create "修复登录超时" "用户登录5分钟后被登出"
# ...
# 记录工时
bash {baseDir}/（请参考skill目录中的脚本文件） log ABC-123 2.5 2025-01-18
# ...
# 工时统计（按时间区间）
bash {baseDir}/（请参考skill目录中的脚本文件） hours 2025-01-01 2025-01-07

最佳实践

1. 使用 JIRA_BOARD 限定项目范围

不设置 JIRA_BOARD 时，检索会扫描所有可见项目，结果可能包含大量噪音。建议根据当前工作重点设置项目范围，例如 JIRA_BOARD="ABC,XYZ"。

2. 状态变更前先查 transitions

不同工作流下允许的流转路径不同。在批量更新状态前，先用 transitions ABC-123 确认可用的目标状态，避免脚本因校验失败中断。

3. 工时记录使用 ISO 日期

log 命令的日期参数推荐使用 YYYY-MM-DD 格式（ISO 8601），避免与本地日期格式冲突。不传日期时默认使用当天 UTC。

4. hours 命令输出 JSON 便于二次加工

hours 系列命令输出 JSON 格式，可直接通过管道传递给 jq 或其他脚本进一步处理，例如生成 Markdown 周报。

5. 大型项目工时查询需耐心等待

Worklog 命令使用 Jira 的 worklog/updated + worklog/list 组合接口，在大型项目上可能需要数秒。建议在非高峰时段执行批量工时统计。

常见问题

Q1：执行命令报 401 未授权怎么办？

检查三项：JIRA_EMAIL 是否与登录邮箱一致、JIRA_API_TOKEN 是否完整复制（不含空格）、JIRA_URL 是否包含 https:// 前缀。

Q2：状态更新失败提示"无可用流转"？

说明当前状态不允许直接流转到目标状态。先用 transitions <ISSUE_KEY> 查看允许的目标状态列表，再选择合法的目标。

Q3：search 搜不到我确定存在的任务？

检查 JIRA_BOARD 是否限定了错误的项目范围。留空时会搜索全部可见项目；如果设置过窄，会过滤掉其他项目的任务。

Q4：hours-day 与 hours 的区别？

hours 只统计 JIRA_EMAIL 对应用户的工时；hours-day 返回当天所有用户的工时，并按用户与任务分组汇总，适合团队视角查看。

Q5：在 Windows 上无法运行脚本？

脚本依赖 bash 环境，Windows 原生 cmd 不支持。请使用 WSL、Git Bash 或 Windows Terminal 中的 bash 子系统。

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows（需 WSL 或 Git Bash）/ macOS / Linux
• Shell：bash 4.0+

第三方依赖

API Key 配置

• JIRA_EMAIL：通过环境变量配置，存储于 Shell 配置文件（如 ~/.bashrc）
• JIRA_API_TOKEN：通过环境变量配置，禁止明文写入脚本或提交到版本库
• JIRA_URL：通过环境变量配置
• JIRA_BOARD：可选，通过环境变量配置

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，功能需要 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 调用脚本完成任务

已知限制

本免费体验版限制以下高级功能：

• 批量任务操作（一次处理超过 10 条任务）
• 多项目并行工时统计与对比
• 自定义工时报表模板与导出格式
• 团队成员工时聚合视图
• Webhook 集成与自动化触发

解锁全部功能请使用专业版：jira-flow-skill-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

License 与版权声明

本 skill 基于原始作品 Jira Flow Skill 改进，保留原始版权声明：

• 原始作品：Jira Flow Skill
• 原始 license：MIT
• 改进作品：Jira Flow Skill（免费版）
• 改进 license：MIT

本改进作品在原始作品基础上进行了深度差异化改造，包括但不限于：

• 完全重写中文化文档与使用指南
• 新增场景化最佳实践与故障排查
• 完善依赖说明与配置示例
• 增加免费版/专业版分层策略

错误处理