JIRA 工具

调用方式：

kdev jira <命令> [参数]

所有输出均为 JSON，解读后用中文回复用户，不要把原始 JSON 直接展示。

鉴权

所有命令（auth 除外）在配置缺失时返回：

{"error": "...", "code": "config"}

收到 code: "config" 或 code: "auth" 时，告知用户：

需要先在终端手动执行一次鉴权：kdev jira auth

agent 不触发 auth，引导用户自行执行后再继续。

命令列表

当前用户上下文

JQL 查询：直接使用 currentUser()，无需额外调用：

kdev jira search "assignee = currentUser() AND ..."

创建/更新工单时填 assignee：需要实际 username，调 whoami 取 .name：

kdev jira whoami   # → {"name": "zhangsan", "displayName": "张三", ...}
# 用 .name 字段填 assignee

团队查询：调 team-members 获取成员列表，拼入 JQL：

kdev jira team-members  # → [{username, displayName}, ...]

不要硬编码用户名。

查询场景参考

以下为常见场景的 JQL 策略，按用户意图灵活调整，不是硬规则：

关键规则：有时间限定就不加 resolution = Unresolved

用户说"今天"、"本周"、"昨天"等时间词时，查询的是"这段时间内有变动的工单"，不区分是否已完成。今天刚关掉的工单也是今天的工作成果，必须包含在内。

resolution = Unresolved 只用于没有时间语境的"我的待办"场景。

updated 涵盖状态变更、工时录入、评论、字段修改等所有操作，工单创建时间无关。

使用原则

修改状态

必须两步走，不做名称模糊匹配：

# 1. 获取可用流转列表
kdev jira transitions <key>
# 返回 [{id: "31", name: "待测试"}, ...]

# 2. 按 id 执行
kdev jira transition <key> <id>

状态名因项目而异，同名可能有多条，由 AI 根据用户意图匹配 id，歧义时向用户确认。

创建工单

# 1. 查询必填字段
kdev jira create-fields <projectKey> [issueType]

# 2. 创建
kdev jira create '{"project":{"key":"PROJ"},"summary":"...","issuetype":{"name":"任务"},"assignee":{"name":"username"}}'

• 用户未提供项目 key 时，先调 projects 按名称匹配，多个候选时列出让用户确认
• 用户未提供受理人时，询问是否分配给自己（调 whoami 取 .name 字段作为 username）
• 创建子任务需加 "parent":{"key":"PROJ-123"}，issuetype 为 子任务

查询我的工单

# 待办（默认过滤陈年工单）
kdev jira search "assignee = currentUser() AND resolution = Unresolved AND updated >= -30d ORDER BY updated DESC"

查询团队工单（按人分组）

# 1. 获取团队成员列表
kdev jira team-members
# → [{username: "lisi", ...}, {username: "wangwu", ...}]

# 2. 拼接 JQL（currentUser() 代表自己，无需单独调 me）
kdev jira search "assignee in (currentUser(), lisi, wangwu) AND resolution = Unresolved ORDER BY assignee, updated DESC" --max 200

在输出时按 assignee 字段分组展示。

团队进度汇总（今天/昨天/本周/指定日期）

# 先取团队成员，再拼 JQL（自己用 currentUser()）
kdev jira team-members
kdev jira search "assignee in (currentUser(), lisi, wangwu) AND updated >= startOfDay() ORDER BY assignee, updated DESC" --max 200

日期范围由 skill 计算，结果按人分组展示，包含工单状态和工时。

搜索工单

• 用户提供关键词：text ~ "关键词" 做全文搜索（标题、描述、评论）
• 用户提供模糊项目名：先调 projects 匹配，加 project = KEY 条件
• 复杂过滤直接拼 JQL

删除 vs 完成

• 用户说"删掉"→ delete（永久不可恢复，需权限）
• 用户说"关闭/完成/结束"→ 调 transitions 找终态，执行 transition
• 模糊时优先建议流转到终态，说明删除不可恢复

错误处理

安装说明

依赖：需先全局安装 @kmfe/devflow（或本地 alias 指向构建产物）。 配置存储在 ~/.config/devflow/，运行 kdev jira auth 完成初始化。