jira-axi

jira-axi

基于 Atlassian 的 acli 构建、符合 Agent 使用习惯的 Jira 命令行工具，提供节省令牌的 TOON 输出和自包含身份验证（无需额外设置凭据）。

无需安装 jira-axi——使用 npx -y jira-axi@latest <command> 即可调用，这是默认方式。 固定使用 @latest 可确保始终运行最新发布版本。 如果 jira-axi 的输出显示后续命令以 jira-axi 开头，请改为运行 npx -y jira-axi@latest ...；如果 PATH 中已能解析裸命令 jira-axi，则直接运行。

全局安装（npm i -g jira-axi）是次要选项，适用于 Agent SessionStart 钩子功能；setup hooks 需要全局安装。 该钩子为每个会话添加的内容：acli: installed（显示是否具备必需的 acli 前置条件）、my_open_workitems[N]{key,summary,status}（你自己的未完成工作项），以及一行 help[N]，列出可用命令。 以下每条命令无论采用哪种方式，行为都相同。

适用场景

只要任务涉及 Jira，就使用 jira-axi：查看、创建或编辑工作项；将工单转换为其他状态；分配或重新分配工单；读取或添加评论；使用 JQL 搜索，或按项目、经办人或状态筛选；列出或检查项目；管理看板及其冲刺和项目；创建、更新或关闭冲刺；列出和更新已保存的筛选器；列出仪表板；或创建、更新、删除或恢复自定义字段。

状态

仪表板、由 acli 支持的 Jira 命令（workitem、project、board、sprint、filter、dashboard、field）、setup hooks 和继承的 update 命令目前均可使用。 jira-axi 会调用 Atlassian 的 acli——请先安装（brew install acli），然后使用 acli jira auth login 登录。 无需单独设置凭据：身份验证完全交由 acli 自身的登录流程处理。

命令

commands[9]:
  (none)=dashboard, workitem, project, board, sprint, filter, dashboard, field, setup
workitem:
  list, view <KEY> [--fields <a,b,c>], create, edit <KEY>, transition <KEY> --to <status>, assign <KEY> --assignee <user>, comment <KEY> --body <text>, search "<JQL>"
project:
  list, view <KEY>
board:
  list, view <ID>, list-sprints <ID>, list-projects <ID>
sprint:
  view <ID>, list-workitems <ID> --board <ID>, create --board <ID> --name <text>, update <ID>
filter:
  list, search, view <ID>, update <ID>
dashboard:
  list
field:
  create --name <text> --type <key>, update <ID>, delete <ID>, restore <ID>

运行 jira-axi --help 查看全局标志，或运行 jira-axi <command> --help 查看各命令的用法。 运行 jira-axi setup hooks 安装 SessionStart 环境上下文（需要全局安装）。

提示

• 标志放在命令之后：jira-axi workitem list --project TEAM，不要放在命令之前。
• 输出采用 TOON 编码，节省令牌。
• 修改操作具有幂等性，并会报告变更内容；重新运行失败的修改操作是安全的（转换为当前状态会作为无操作成功处理）。
• filter list 只会列出该账户拥有的筛选器，因此 count: 0 并不能证明没有筛选器；使用 filter list --favourite 或 filter search --name <substring> 查找其余筛选器。
• view <KEY> --full 显示完整正文；--comments 包含评论（计数行显示实际总数；使用 --limit <n> 增加显示的行数）；--fields <a,b,c> 仅渲染指定字段（适用于 list/search/view）。
• 较长的自由文本会被截断，并附带大小标记和 --full 完整显示选项：适用于 workitem view 的正文/评论，以及 filter view 和 project view 的描述。
• workitem list 会根据 --project/--assignee/--status 构建 JQL；传入 --jql，或使用 search 执行原始 JQL。
• workitem create/edit --body 和 comment --body 接受 Markdown（标题、列表、行内/块级代码、粗体/斜体、链接），并将其存储为真正的 Jira ADF；原始 ADF JSON 会原样传递。
• 看板/冲刺/筛选器通过 ID 寻址：使用 board list 查找看板 ID，使用 board list-sprints <BOARD_ID> 查找冲刺 ID。
• sprint list-workitems 需要同时提供冲刺 ID 和 --board（这是 Jira 敏捷 API 的要求）。
• sprint update <ID> --state closed 会关闭冲刺（已关闭时作为无操作成功处理）；acli 不支持字段列表/查看，因此 field 仅涵盖自定义字段的创建/更新/删除/恢复。