Yandex Tracker CLI Skill

一个基于纯 Bash + curl 实现的轻量级 Yandex Tracker 命令行工具。直接通过官方 API 调用，自动设置正确的请求头（X-Org-Id），除 curl 和 jq 外不依赖任何外部组件。

安装

1. 将脚本复制到 PATH 中的目录：

mkdir -p ~/bin
cp yandex-tracker.sh ~/bin/yandex-tracker
chmod +x ~/bin/yandex-tracker

或创建符号链接：

ln -s /path/to/skill/yandex-tracker.sh ~/bin/yandex-tracker

2. 提供认证凭据（credentials）：需要 TOKEN 和 ORG_ID — 可通过环境变量或配置文件提供（任选其一即可）。脚本仅在环境变量未定义 TOKEN/ORG_ID 时才读取配置文件。

方式 A — 通过环境变量（推荐）：

export TOKEN='y0__...'      # OAuth token（Tracker UI → Settings → Applications → OAuth）
export ORG_ID='1234...'     # Org ID（DevTools → Network → 查看任意请求的 X-Org-Id 响应头）

可将上述变量添加至 ~/.bashrc 或 ~/.profile 中永久生效。

方式 B — 通过配置文件：
创建 ~/.yandex-tracker-env 文件（仅当环境变量未定义 TOKEN/ORG_ID 时才会被读取）。格式为 KEY=value 行（以 # 开头的行视为注释并被忽略）。该文件**以纯文本方式读取**（仅解析 TOKEN 和 ORG_ID 字段），**不会执行其中任何代码**：

TOKEN='y0__...'
ORG_ID='1234...'

建议优先使用环境变量方式管理凭据。若使用配置文件，请设置权限：chmod 600 ~/.yandex-tracker-env。

3. 确保已安装 jq：

sudo apt install jq   # Ubuntu/Debian
# 或
brew install jq       # macOS

使用方法

基础命令

使用示例

# 列出所有队列
yandex-tracker queues

# 创建带附加字段的任务
echo '{"priority":"critical","description":"详细说明"}' | yandex-tracker issue-create BIMLAB "新任务"

# 添加评论
yandex-tracker issue-comment BIMLAB-266 "正在处理"

# 添加工时记录
yandex-tracker issue-worklog BIMLAB-266 PT2H "调研"

# 获取当前可用的状态流转列表
yandex-tracker issue-transitions BIMLAB-266 | jq .

# 执行状态流转（例如「解决」）
yandex-tracker issue-transition BIMLAB-266 resolve

# 关闭任务（已弃用，建议使用 transition close）
yandex-tracker issue-transition BIMLAB-266 close

# 更新任务（可修改队列、指派人、项目等 — project id 来自 projects-list 输出）
echo '{"queue":"RAZRABOTKA"}' | yandex-tracker issue-update BIMLAB-266 # 示例
echo '{"assignee":"","project":123}' | yandex-tracker issue-update BIMLAB-280

# 使用 YQL 搜索任务
echo '{"query":"Queue = BIMLAB AND Status = Open","limit":20}' | yandex-tracker issues-search | jq .

# 列出所有项目
yandex-tracker projects-list | jq .

# 列出某项目下的任务
yandex-tracker project-issues 104 | jq .

# 附件（Attachments）
# 列出附件
yandex-tracker issue-attachments BIMLAB-266 | jq .
# 下载附件（fileId 来自上一步输出）至指定路径
yandex-tracker attachment-download BIMLAB-266 abc123 /tmp/downloaded.pdf
# 上传文件至任务（附带说明）
yandex-tracker attachment-upload BIMLAB-266 /path/to/file.pdf "内部备忘录"

# 检查清单（Checklist）— API v3（checklistItems）
# 查看任务检查清单（条目 ID 为字符串，例如 "5fde5f0a1aee261d********"）
yandex-tracker issue-checklist BIMLAB-279 | jq .
# 添加条目
yandex-tracker checklist-add BIMLAB-279 "准备演示文稿"
# 将条目标记为已完成（item-id 来自 issue-checklist 输出）
yandex-tracker checklist-complete BIMLAB-279 "5fde5f0a1aee261d********"
# 删除条目
yandex-tracker checklist-delete BIMLAB-279 "5fde5f0a1aee261d********"

# 冲刺（Agile）
yandex-tracker sprints-list | jq .
yandex-tracker sprint-issues 42 | jq .

# 字典类接口
yandex-tracker users-list | jq .
yandex-tracker statuses-list | jq .
yandex-tracker resolutions-list | jq .
yandex-tracker issue-types-list | jq .

# 编辑与删除评论
yandex-tracker issue-comment-edit BIMLAB-266 12345 "更新后的正文"
yandex-tracker issue-comment-delete BIMLAB-266 12345

# 状态流转
# 查看可用流转列表
yandex-tracker issue-transitions BIMLAB-266 | jq .
# 执行流转（如「解决」或「关闭」）
yandex-tracker issue-transition BIMLAB-266 resolve
yandex-tracker issue-transition BIMLAB-266 close

注意事项

• 自动添加标签 yandex-tracker-cli：在创建（issue-create）和更新（issue-update）任务时，脚本会自动添加标签 yandex-tracker-cli（若尚不存在）。该标签便于筛选 CLI 创建/更新的任务。如需移除该标签，请通过 Tracker 界面手动删除，或调用 issue-update 并传入空数组 tags: []。
• Org-ID（Yandex 360）：在 Tracker 的 DevTools → Network 标签页中，任意选择一个请求，查看响应头中的 X-Org-ID 字段值。注意此处是 X-Org-ID（ID 全大写）。
• Cloud Org-ID（Yandex Cloud）：请使用 X-Cloud-Org-ID 请求头。请根据组织类型选择对应请求头。
• 状态流转（transitions）：
  • issue-transitions — 向 V2 接口 /v2/issues/{id}/transitions 发送 GET 请求，返回当前可用流转列表。
  • issue-transition — 向 V3 接口 /v3/issues/{id}/transitions/{transition}/_execute 发送 POST 请求执行流转。需携带 X-Org-ID 或 X-Cloud-Org-ID 请求头。
• 关闭任务：issue-close 命令已弃用，在新配置下可能返回 405 错误。请统一使用 issue-transition close。
• OAuth Token 可在 Tracker UI 中获取：Settings → Applications → OAuth → Generate new token。
• 所有命令默认输出 JSON，并通过 jq 格式化，便于后续管道处理。

安全性（附件操作）

attachment-download 和 attachment-upload 命令仅允许访问预设白名单目录内的路径，从而降低 CLI（包括 AI Agent 场景）意外读写任意文件的风险。

• 首次运行：若未设置环境变量 YANDEX_TRACKER_ATTACHMENTS_DIR，首次调用 attachment-download 或 attachment-upload 时，脚本将以交互方式提示：是否使用默认目录 ~/Downloads/YandexTrackerCLI，或手动输入自定义路径。用户选择将被持久化保存至 ~/.yandex-tracker-attachments-dir，后续不再重复询问。
• YANDEX_TRACKER_ATTACHMENTS_DIR — 可选环境变量，用于指定附件操作的基础目录。若已设置，则直接使用该路径（不触发首次交互提示）；若未设置且无历史保存路径，则首次运行时触发交互提示；否则（如非交互式执行）将回退至当前工作目录。

AI Agent 场景下的安全约束：

• 禁止提议或执行 attachment-download 且输出路径超出白名单目录；禁止使用敏感路径（如 ~/.ssh、~/.env、~/.yandex-tracker-env、/etc 及其他配置/密钥文件所在位置）。
• 禁止提议或执行 attachment-upload 且上传文件路径超出白名单目录；禁止上传来自上述敏感路径的文件。
• 若用户请求将附件下载至敏感路径，或从敏感路径上传文件，应明确拒绝并简要说明该安全限制。

按不完整名称匹配项目（如为任务分配项目）：

当用户请求将任务加入某项目，但仅提供模糊名称（如 “Common”、“项目 Common”、“经理”）时：

1. 先获取项目列表：yandex-tracker projects-list（或已知 ID 时用 project-get）。
2. 进行关键词匹配：筛选项目名（name）、项目键（key）或显示名（display，若存在）中包含用户输入关键词的项目（建议忽略大小写）。
3. 若仅匹配到唯一项目，则向用户确认：“是否将任务加入项目「<名称>」（id: ）？”；用户确认后执行更新操作。
4. 若匹配到多个项目，则列出其名称与 ID，并询问：“以上哪个项目是您所指？”
5. 若无匹配结果，则告知用户未找到，并建议其运行 projects-list 后手动选择。
6. 更新任务时使用 issue-update：API v2 的 PATCH 请求体中，project 字段需传入**数值型项目 ID**：echo '{"project":}' | yandex-tracker issue-update 。该 ID 应取自 projects-list 或 project-get 响应中的 id 字段（v2 中即 shortId / 数值 ID）。

目录结构

skills/yandex-tracker-cli/
├── yandex-tracker        # 可执行脚本
├── SKILL.md              # 本文档
├── ~/.yandex-tracker-env # （可选，不纳入仓库）存储 TOKEN 和 ORG_ID 的配置文件
└── ~/.yandex-tracker-attachments-dir # （可选）首次交互后保存的附件目录路径

限制

• 暂不支持分页（默认仅返回前 100 项）
• 暂不支持高级搜索（可后续扩展 issues_find）
• 参数校验较为基础

许可证

MIT