Shortcut 看板集成

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

先决条件

• 通过以下任一方式配置 Shortcut API 令牌：
  • 环境变量：SHORTCUT_API_TOKEN
  • 文件：~/.config/shortcut/api-token
• 访问具有适当权限的 Shortcut 工作区

设置

1. 从 Shortcut.com 获取您的 API 令牌（设置 → API 令牌）
2. 将其存储于：
   • 作为环境变量：export SHORTCUT_API_TOKEN="your-token"
   • 在文件中：echo "your-token" > ~/.config/shortcut/api-token && chmod 600 ~/.config/shortcut/api-token
3. 初始化您工作区的工作流状态：

   scripts/shortcut-init-workflow.sh
   

   这将创建~/.config/shortcut/workflow-states包含您工作区的实际状态 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 <story-id>

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

• 故事名称和状态
• 描述（如果存在）
• 包含完成状态的检查清单项目

创建故事

scripts/shortcut-create-story.sh "Story name" [--description "text"] [--type feature|bug|chore]

故事类型：

• feature（默认）- 新功能
• bug- 错误修复
• 杂务- 维护任务

更新故事

scripts/shortcut-update-story.sh <story-id> [--complete|--todo|--in-progress] [--description "new text"]

工作流状态：脚本使用来自~/.config/shortcut/workflow-states（由shortcut-init-workflow.sh创建）的状态ID。如果未配置，则回退到常见默认值：

• 待办事项：500000006
• 待处理：500000007
• 进行中：500000008
• 评审中：500000009
• 已完成：500000010

注意：不同的Shortcut工作空间可能使用不同的状态ID。请始终运行shortcut-init-workflow.sh来配置您工作空间的实际ID。

管理清单任务

创建一个任务：

scripts/shortcut-create-task.sh <story-id> "task description"

更新任务完成状态：

scripts/shortcut-update-task.sh <story-id> <task-id> [--complete|--incomplete]

编辑任务描述：

scripts/shortcut-edit-task.sh <story-id> <task-id> "new description"

删除一个任务：

scripts/shortcut-delete-task.sh <story-id> <task-id>

使用shortcut-show-story.sh来查看任务ID。

管理评论

添加评论：

scripts/shortcut-add-comment.sh <story-id> "comment text"

更新评论：

scripts/shortcut-update-comment.sh <story-id> <comment-id> "new text"

删除评论：

scripts/shortcut-delete-comment.sh <story-id> <comment-id>

使用shortcut-show-story.sh来查看评论ID。

工作流程

1. 列出现有故事以了解当前看板状态
2. 创建具有描述性名称和适当类型的新故事
3. 随着工作进展更新故事状态

注意事项

• 脚本使用SHORTCUT_API_TOKEN环境变量或回退到~/.config/shortcut/api-token
• 故事默认创建为"未开始"状态（工作流状态ID：500000006）
• 如果工作空间使用不同的工作流状态ID，可能需要调整脚本
• 令牌必须具有要管理工作空间的权限