Shortcut 看板集成

通过 API 管理 Shortcut.com 项目看板上的任务（tasks）和用户故事（stories）。

前提条件

• 已通过以下任一方式配置 Shortcut API token：
  • 环境变量：SHORTCUT_API_TOKEN
  • 文件：~/.config/shortcut/api-token
• 具备对某个 Shortcut workspace 的访问权限，并拥有相应操作权限

配置步骤

1. 在 Shortcut.com 上获取您的 API token（设置 → API Tokens）
2. 将 token 存储至以下任一位置：
   • 作为环境变量：export SHORTCUT_API_TOKEN="your-token"
   • 写入文件：echo "your-token" > ~/.config/shortcut/api-token && chmod 600 ~/.config/shortcut/api-token
3. 为您的 workspace 初始化工作流状态：

   scripts/shortcut-init-workflow.sh
   

   该命令会生成文件 ~/.config/shortcut/workflow-states，其中包含您 workspace 实际使用的状态 ID。
4. （可选）将其添加至 ~/.bashrc 以实现持久化：

   export SHORTCUT_API_TOKEN=$(cat ~/.config/shortcut/api-token 2>/dev/null | tr -d '\n')
   source ~/.config/shortcut/workflow-states
   

可用操作

列出用户故事

scripts/shortcut-list-stories.sh [--active|--completed|--all] [--json]

选项说明：

• --active — 仅显示未完成的用户故事（默认行为）
• --completed — 仅显示已完成的用户故事
• --all — 包含已归档的用户故事
• --json — 以原始 JSON 格式输出

查看用户故事详情

scripts/shortcut-show-story.sh 

显示完整的用户故事信息，包括：

• 用户故事名称与当前状态
• 描述内容（如已填写）
• 检查清单（checklist）条目及其完成状态

创建用户故事

scripts/shortcut-create-story.sh "用户故事名称" [--description "文本"] [--type feature|bug|chore]

用户故事类型说明：

• feature（默认）— 新功能开发
• bug — 缺陷修复
• chore — 维护类任务

更新用户故事

scripts/shortcut-update-story.sh  [--complete|--todo|--in-progress] [--description "新文本"]

工作流状态：脚本使用 ~/.config/shortcut/workflow-states 中定义的状态 ID（由 shortcut-init-workflow.sh 生成）。若未配置，则回退至以下通用默认值：

• Backlog（待办事项）：500000006
• To Do（待开始）：500000007
• In Progress（进行中）：500000008
• In Review（审核中）：500000009
• Done（已完成）：500000010

注意：不同 Shortcut workspace 可能使用不同的状态 ID。请务必运行 shortcut-init-workflow.sh 来配置您 workspace 对应的实际 ID。

管理检查清单任务

创建任务：

scripts/shortcut-create-task.sh  "任务描述"

更新任务完成状态：

scripts/shortcut-update-task.sh   [--complete|--incomplete]

编辑任务描述：

scripts/shortcut-edit-task.sh   "新描述"

删除任务：

scripts/shortcut-delete-task.sh  

可通过 shortcut-show-story.sh 查看任务 ID。

管理评论

添加评论：

scripts/shortcut-add-comment.sh  "评论内容"

更新评论：

scripts/shortcut-update-comment.sh   "新内容"

删除评论：

scripts/shortcut-delete-comment.sh  

可通过 shortcut-show-story.sh 查看评论 ID。

典型工作流

1. 列出已有用户故事，了解当前看板状态
2. 创建具有明确描述和合适类型的用户故事
3. 随工作进展持续更新用户故事状态

注意事项

• 脚本优先读取环境变量 SHORTCUT_API_TOKEN；若未设置，则回退至读取文件 ~/.config/shortcut/api-token
• 新建用户故事默认处于 “Unstarted”（未启动）状态（对应 workflow_state_id: 500000006）
• 若您 workspace 使用了自定义的工作流状态 ID，可能需要手动调整相关脚本
• 所用 token 必须具备目标 workspace 的管理权限