Ticketron (tix)

Ticketron（tix）

由大模型驱动的 JIRA 智能命令行助手。

简介

Ticketron（tix）让你可以直接从命令行轻松使用 JIRA。它通过 jira-mcp-server 和 OpenAI 利用大语言模型（LLM）的能力，让你使用自然语言或简洁命令创建和搜索 JIRA 工单。它的主要目标是通过自动添加相关上下文来简化工作流，让工单管理更快捷、更直观。

功能

• 使用自然语言创建 JIRA 问题（tix create ...）
• 使用 JQL 搜索 JIRA 问题（tix search ...）
• 通过 LLM 生成包含上下文的工单（使用 OpenAI）
• 配置管理（tix config init|show|locate|set-key）
• 安全存储 API 密钥（OS Keychain 或环境变量）
• LLM 上下文管理（tix context show|edit|add）
• 支持 Shell 补全（Bash、Zsh、Fish、PowerShell）
• 结构化输出格式（JSON、YAML、TSV）
• 结构化日志，方便调试

安装

先决条件

• Go： 版本 1.23.8 或更高。
• jira-mcp-server： 需要能够访问正在运行的 jira-mcp-server 实例（用于与 JIRA 通信）。
• OpenAI API Key： LLM 功能所需。
• Make： 开发任务所需（构建、测试、代码检查）。

安装命令

go install github.com/karolswdev/ticketron/cmd/tix@latest

确保 $GOPATH/bin 或 $HOME/go/bin 已加入 PATH。

Shell 补全

tix 支持为 Bash、Zsh、Fish 和 PowerShell 生成 Shell 补全脚本。

使用 completion 命令为你的 Shell 生成脚本：

# For Bash
tix completion bash

# For Zsh
tix completion zsh

# For Fish
tix completion fish

# For PowerShell
tix completion powershell

按照命令输出的说明，将补全加载到当前会话，或配置为自动加载。

Bash 示例（添加到 ~/.bashrc 或 ~/.bash_profile）：

source <(tix completion bash)

Zsh 示例（添加到 ~/.zshrc）：

# Ensure compinit is loaded
autoload -U compinit; compinit

# Load completions
source <(tix completion zsh)

请参阅 tix completion [your-shell] 的输出，以获取适用于你环境的最准确配置说明。

快速开始

1. 安装 tix：

   go install github.com/karolswdev/ticketron/cmd/tix@latest
   

   （确保 $GOPATH/bin 或 $HOME/go/bin 已加入 PATH）

2. 初始化配置：

   tix config init
   

   （创建包含默认文件的 ~/.ticketron/。编辑 ~/.ticketron/config.yaml 以设置 mcp_server.url。）

3. 设置 OpenAI API Key：

   # 推荐：使用 OS Keychain
   tix config set-key <your-openai-api-key>
   
   # 备选：使用环境变量
   # export TICKETRON_LLM_API_KEY="<your-openai-api-key>"
   

4. 创建你的第一个工单：

   # 示例：创建错误报告（提供描述时会使用 LLM）
   tix create bug "Login button unresponsive" --description "When clicking the login button on the main page, nothing happens. Check console logs."
   

配置

Ticketron 需要将配置文件存储在 ~/.ticketron/ 中。你可以使用以下命令初始化默认配置目录和模板文件：

tix config init

如果 ~/.ticketron/ 目录不存在，此命令会创建该目录，并填入默认模板文件（config.yaml、links.yaml、system_prompt.txt、context.md）。它不会处理 API 密钥设置。

OpenAI API Key

LLM 功能需要 OpenAI API key，出于安全考虑，必须单独配置。你有两种选择：

1. 推荐：使用操作系统密钥链：

   tix config set-key <your-openai-api-key>
   

   此命令会将密钥安全地存储在操作系统的密钥链中。ticketron 会自动从中读取密钥。

2. 替代方案：环境变量： 设置 TICKETRON_LLM_API_KEY 环境变量：

   export TICKETRON_LLM_API_KEY="<your-openai-api-key>"
   

   如果在密钥链中找不到密钥，应用会使用此变量。

配置文件

~/.ticketron/ 中的主要配置文件：

• config.yaml：主配置文件。
  • mcp_server.url：正在运行的 jira-mcp-server 的 URL。
  • 其他设置，如默认项目、问题类型、日志级别。
  • 注意：openai.api_key 不再存储于此。
• links.yaml：将项目简称映射到完整的 JIRA 项目键和默认问题类型。
  • 示例：

    links:
      - name: WEB
        key: WEBPROJECT
        default_issue_type: Story
      - name: API
        key: BACKENDAPI
        default_issue_type: Task
      - name: DS
        key: DATASCIENCE
        default_issue_type: Bug
    

• system_prompt.txt：包含在创建工单时用于指示 LLM 的系统提示词。修改此文件可调整 LLM 的行为。
• context.md：为 LLM 提供有关项目、团队或常见工单模式的持久上下文。

使用 tix config show 查看当前配置（不包括 API key），使用 tix config locate 查找配置目录。

基本用法

使用 tix --version 显示应用版本。

创建工单

# Create a bug with a simple title
tix create bug "Login fails on checkout page"

# Create a story for a specific project (using alias from links.yaml)
tix create --type Story --project WEB "Implement new user profile page design"

# Create a task with more detail (will be processed by LLM)
tix create task "Refactor auth module to use JWT" --description "The current session management is outdated. We need to switch to JWT for better security and scalability. Update login, logout, and token refresh endpoints."

# Create a ticket interactively (prompts for confirmation before sending)
tix create -i bug "UI glitch on settings page"

# Create a ticket and output the result as JSON
tix create task "Setup CI pipeline" -o json

搜索工单

# Search using natural language (processed by LLM to generate JQL)
tix search "my open bugs in the WEB project"

# Search using explicit JQL
tix search --jql "project = WEB AND status = 'In Progress' ORDER BY created DESC"

# Search for unresolved tickets assigned to you
tix search --jql "assignee = currentUser() AND resolution = Unresolved"

# Search for tickets and output results as JSON
tix search "my open tasks" -o json
# Search and output specific fields as JSON
tix search "status = Done" -o json -f key,fields.summary,fields.status.name

# Search and output results as YAML
tix search "my open tasks" -o yaml

# Search and output results as TSV (Tab-Separated Values)
tix search "project = API" -o tsv

# Search and output specific fields as TSV
tix search "project = API" -o tsv -f key,fields.issuetype.name,fields.summary

管理配置

# Initialize configuration files
tix config init

# Show current configuration values
tix config show

# Show the location of the configuration directory
tix config locate

# Securely set the OpenAI API key in the OS keychain
tix config set-key <your-openai-api-key>

管理 LLM 上下文

context.md 文件为 LLM 提供持久上下文。你可以使用 tix context 命令管理此文件：

# Show the current content of the context file
tix context show

# Open the context file in your default editor ($EDITOR)
tix context edit

# Add a new line of text to the context file
tix context add "Remember to always include the component name in bug reports."

开发

此项目使用 Makefile 简化常见开发任务。请确保已安装 make。

• 构建： 编译 tix 二进制文件。

  make build
  

• 测试： 运行单元测试和集成测试。

  make test
  

• 代码检查： 运行 Go 代码检查工具（golangci-lint）。

  make lint
  

• 格式化： 使用 gofmt 格式化 Go 源代码。

  make fmt
  

• 全部检查： 运行格式化、代码检查和测试目标。

  make check
  

请参阅 Makefile，了解其他可用目标。

贡献

请注意，此项目遵循 贡献者行为准则 发布。参与此项目即表示你同意遵守其中条款。

有关如何贡献的详情，请参阅 CONTRIBUTING.md。

许可证

此项目基于 MIT 许可证授权。详情请参阅 LICENSE 文件。