--- name: "jira-flow-skill-free" description: "通过Jira Cloud REST API管理任务、状态流转与工时记录，适合个人开发者日常追踪。Use when 需要项目管理、任务规划、进度跟踪、团队协作时使用。不适用于实际人员绩效评估。适用于独立开发者、企业团队和自动化工作流场景。支持中文交互，无需复杂配置即开即用。输出结果可直接使用，减少二次加工成本。" license: Proprietary allowed-tools: read exec compatibility: "Requires LLM with tool-use capability" metadata: displayName: "Jira Flow 免费版" version: "1.0.0" summary: "通过Jira Cloud REST API管理任务、状态流转与工时记录，适合个人开发者日常追踪。" tags: - "集成工具" - "任务管理" - "效率提升" source: "SkillHub" converted_at: "2026-07-22T17:58:36" tools: - exec - read - write --- # Jira Flow Skill（免费版） 面向个人开发者与小型团队的 Jira 任务管理工具，通过命令行脚本完成日常任务流转、工时记录与检索查询。 ## 概述 Jira Flow Skill 将 Jira Cloud REST API 封装为简洁的命令行调用，让开发者在终端即可完成"查任务、改状态、记工时、看汇总"的完整闭环。免费版覆盖个人开发者 90% 的日常 Jira 操作，无需切换浏览器即可保持工作流连续。 ### 核心价值 - **命令行即工作流**：单条命令完成一个完整操作，无需多步点击 - **状态流转校验**：自动拉取服务端允许的流转列表，杜绝无效状态变更 - **工时 JSON 输出**：工时统计结果直接输出 JSON，可被其他脚本消费 - **零侵入集成**：基于环境变量配置，不修改 Jira 项目配置 ## 核心能力 | 能力域 | 命令族 | 说明 | |--------|--------|------| | 任务检索 | `search` / `my` | 模糊搜索任务摘要或键值，列出分配给自己的任务 | | 任务详情 | `issue` / `link` | 查看任务详情，生成浏览器跳转链接 | | 状态管理 | `status` / `transitions` | 列出可用流转、应用状态变更（带校验） | | 任务分配 | `assign` / `assign-me` | 按用户搜索分配任务，或一键指派给自己 | | 评论与创建 | `comment` / `create` | 添加评论、在指定项目内创建任务 | | 工时记录 | `log` | 按小时数与日期记录工时 | | 工时统计 | `hours` / `hours-day` / `hours-issue` | 按时间区间、按日、按任务汇总工时 | ### 核心功能执行 用`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. 配置环境变量： ```bash export JIRA_EMAIL="you@example.com" export JIRA_API_TOKEN="你的API令牌" export JIRA_URL="https://your-domain.atlassian.net" # 可选：限定项目范围（逗号分隔），留空则搜索全部项目 export JIRA_BOARD="ABC" ``` ### 依赖详情 执行以下命令，能正常返回任务列表即代表配置成功： ```bash bash {baseDir}/scripts/jira.sh my 5 ``` ### 运行环境要求 - 命令行工具：`curl`、`jq`、`bc`、`python3` - 操作系统：Windows（需 WSL 或 Git Bash）/ macOS / Linux - 网络：可访问 `atlassian.net` 域名 ## 示例 ### 环境变量配置表 | 变量名 | 必填 | 默认值 | 说明 | |--------|------|--------|------| | `JIRA_EMAIL` | 是 | 无 | 登录 Jira 的邮箱 | | `JIRA_API_TOKEN` | 是 | 无 | Atlassian API 令牌 | | `JIRA_URL` | 是 | 无 | Jira 实例地址（含 https://） | | `JIRA_BOARD` | 否 | 空 | 项目键值过滤，多个用逗号分隔 | ### 常用命令速查 ```bash # 检索任务 # 查看任务详情 # 更新状态（自动校验流转） sh status ABC-123 "In Progress" # 分配给自己 sh assign-me ABC-123 # 添加评论 sh comment ABC-123 "已修复并部署到预发" # 创建任务 sh create "修复登录超时" "用户登录5分钟后被登出" # 记录工时 sh log ABC-123 2.5 2025-01-18 # 工时统计（按时间区间） sh 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 ` 查看允许的目标状态列表，再选择合法的目标。 ### 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+ ### 第三方依赖 | 依赖项 | 类型 | 是否必需 | 获取方式 | |:-------|:-----|:---------|:---------| | curl | 命令行工具 | 必需 | 系统自带或通过包管理器安装 | | jq | JSON 处理工具 | 必需 | `apt install jq` / `brew install jq` | | bc | 数值计算工具 | 必需 | `apt install bc` / `brew install bc` | | python3 | 运行时 | 必需 | `apt install python3` / 官网下载 | | LLM API | API | 必需 | 由 Agent 内置 LLM 提供 | ### 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 本改进作品在原始作品基础上进行了深度差异化改造，包括但不限于： - 完全重写中文化文档与使用指南 - 新增场景化优选实践与故障排查 - 完善依赖说明与配置示例 - 增加免费版/专业版分层策略 ## 错误处理 | 错误场景 | 原因 | 处理方式 | |---------|------|---------| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 | ## 安全注意事项 | 风险类型 | 防范措施 | |----------|---------| | API密钥泄露 | 通过环境变量配置，禁止硬编码到代码或配置文件中 | | 命令执行风险 | 仅执行白名单命令，避免拼接用户输入到命令行参数中 | | 网络通信安全 | 使用HTTPS协议，验证SSL证书有效性 | | 敏感数据暴露 | 输出结果中不包含密钥、令牌等敏感信息 | 使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。