acli-jira

用途

当你需要与 Jira 交互时使用此技能：读取工单、创建新的工作项、更新现有工作项、使用 JQL 搜索、转换状态、分配经办人、发表评论或浏览项目。acli jira 可通过命令行全面管理 Jira Cloud。

何时使用什么

• acli jira workitem view：按键查看特定工单。用于读取工单详情、描述、状态、经办人等。
• acli jira workitem search：使用 JQL 查询查找工单。用于任何工作项搜索、筛选或列表操作。
• acli jira workitem create：创建新工单。用于用户希望提交错误、任务、故事或史诗的情况。
• acli jira workitem edit：修改现有工单的摘要、描述、标签、类型或经办人。
• acli jira workitem transition：将工单转换为新状态（例如，“进行中”“已完成”）。
• acli jira workitem assign：更改或移除工单的经办人。
• acli jira workitem comment create：为工单添加评论。
• acli jira workitem comment list：读取工单评论。
• acli jira project list：列出可用项目。用于查找项目键。
• acli jira project view：查看特定项目的详情。
• acli jira sprint list-workitems：列出冲刺中的工单（需要 --sprint 和 --board ID）。
• acli jira board search：按名称或关键词查找看板。

核心概念

• 读取命令（view、search、comment list、project list 等）始终使用 --json，以获取机器可读的输出。
• 修改命令（edit、transition、assign）始终使用 --yes，跳过交互式确认提示，避免在非交互式 shell 中卡住。
• 搜索使用 JQL（Jira 查询语言）。通过 --jql "..." 传入。
• @me 是已通过身份验证的用户的简写（可用于 --assignee）。
• 标签以逗号分隔：--label "bug,backend,urgent"。
• 工作项类型使用 Jira 的问题类型：Task、Bug、Story、Epic、Sub-task 等。通过 --type 传入。
• 键是带项目代号前缀的 ID，例如 PROJ-123。多个键以逗号分隔：--key "PROJ-1,PROJ-2"。

推荐工作流

1. 查找项目：运行 acli jira project list --json，查找可用的项目键。
2. 搜索工单：运行 acli jira workitem search --jql "project = PROJ AND ..." --json，查找相关工作项。
3. 查看工单：运行 acli jira workitem view PROJ-123 --json，读取完整详情。
4. 根据需要使用以下命令创建、编辑或转换状态。

常见 JQL 模式

# All open tickets in a project
--jql "project = PROJ AND status != Done"

# Tickets assigned to me
--jql "assignee = currentUser()"

# Bugs created this week
--jql "project = PROJ AND type = Bug AND created >= startOfWeek()"

# Tickets with a specific label
--jql "project = PROJ AND labels = backend"

# Search by summary text
--jql "project = PROJ AND summary ~ \"search term\""

# High priority open items
--jql "project = PROJ AND priority in (High, Highest) AND status != Done"

# Recently updated
--jql "project = PROJ AND updated >= -7d ORDER BY updated DESC"

示例

查看工单

acli jira workitem view PROJ-123 --json

# View specific fields only
acli jira workitem view PROJ-123 --fields "summary,status,assignee,labels,comment" --json

搜索工单

# Search with JQL, get JSON output
acli jira workitem search --jql "project = PROJ AND status = 'In Progress'" --json

# Search with specific fields and a result limit
acli jira workitem search --jql "project = PROJ AND assignee = currentUser()" \
  --fields "key,summary,status,priority,labels" --limit 20 --json

# Get count of matching tickets
acli jira workitem search --jql "project = PROJ AND type = Bug" --count

创建工单

# Basic creation
acli jira workitem create \
  --project "PROJ" \
  --type "Task" \
  --summary "Implement feature X" \
  --description "Detailed description here" \
  --label "backend,feature" \
  --assignee "@me" \
  --json

# Create a bug with a parent (sub-task)
acli jira workitem create \
  --project "PROJ" \
  --type "Bug" \
  --summary "Fix login timeout" \
  --description "Users report timeout after 30s on the login page" \
  --label "bug,auth" \
  --parent "PROJ-100" \
  --json

# Create with description from a file
acli jira workitem create \
  --project "PROJ" \
  --type "Story" \
  --summary "User onboarding flow" \
  --description-file description.txt \
  --json

编辑工单

# Edit summary and labels
acli jira workitem edit --key "PROJ-123" \
  --summary "Updated summary" \
  --labels "backend,urgent" \
  --yes --json

# Change assignee
acli jira workitem edit --key "PROJ-123" \
  --assignee "[email protected]" \
  --yes --json

# Remove labels
acli jira workitem edit --key "PROJ-123" \
  --remove-labels "stale" \
  --yes --json

转换工单状态

# Move to In Progress
acli jira workitem transition --key "PROJ-123" --status "In Progress" --yes --json

# Mark as Done
acli jira workitem transition --key "PROJ-123" --status "Done" --yes --json

# Transition multiple tickets
acli jira workitem transition --key "PROJ-1,PROJ-2,PROJ-3" --status "Done" --yes --json

分配工单

# Assign to self
acli jira workitem assign --key "PROJ-123" --assignee "@me" --yes --json

# Assign to someone else
acli jira workitem assign --key "PROJ-123" --assignee "[email protected]" --yes --json

# Remove assignee
acli jira workitem assign --key "PROJ-123" --remove-assignee --yes --json

评论

# Add a comment
acli jira workitem comment create --key "PROJ-123" --body "This is ready for review"

# List comments
acli jira workitem comment list --key "PROJ-123" --json

项目

# List all projects
acli jira project list --json

# View a specific project
acli jira project view --key "PROJ" --json

# List recently viewed projects
acli jira project list --recent --json

冲刺和看板

# Find a board
acli jira board search --name "My Team" --json

# List sprints on a board
acli jira board list-sprints --id 42 --json

# List tickets in a sprint
acli jira sprint list-workitems --sprint 101 --board 42 --json

重要提示

• 创建工单时，如果尚未确定，请务必向用户询问项目键。运行 acli jira project list --json 可查找可用项目。
• 创建工单时，根据上下文推断合适的标签（例如代码库所属区域、工作类型）。标签有助于发现工单。
• 所有读取操作优先使用 --json 输出，以便解析结果并向用户总结。
• 所有写入操作都使用 --yes，避免出现交互式提示。
• 对于大量结果，使用 --limit 限制结果数量，或使用 --paginate 获取全部结果。
• 状态名称因项目而异。如果状态转换失败，错误消息会列出有效状态。
• 要设置自定义字段（CLI 标志未提供的字段），请使用带有 additionalAttributes 的 --from-json。使用 acli jira workitem create --generate-json 生成模板。

看板特定约定

如需了解项目特定的看板约定（必填字段、自定义字段映射、标签、模板），请阅读文件 ~/.config/opencode/skills/acli-jira/boards.md（如果存在）。其中包含在已知看板上创建或管理工单前所需的看板特定约定。

这样可以将看板约定保留为私有内容（不提交到版本控制），同时让核心技能保持公开。