介绍
# Shortcut Kanban Integration
通过 API 管理 Shortcut.com 项目看板上的任务和 Story。
## 前置条件
- 通过以下方式之一配置 Shortcut API token： - 环境变量：`SHORTCUT_API_TOKEN` - 文件：`~/.config/shortcut/api-token` - 拥有适当权限的 Shortcut 工作区访问权限
### 设置
1. 从 Shortcut.com 获取你的 API token（Settings → API Tokens） 2. 按以下任一方式存储： - 作为环境变量：`export SHORTCUT_API_TOKEN="your-token"` - 在文件中：`echo "your-token" > ~/.config/shortcut/api-token && chmod 600 ~/.config/shortcut/api-token` 3. 为你的工作区初始化工作流状态： ```bash scripts/shortcut-init-workflow.sh ``` 这将创建 `~/.config/shortcut/workflow-states` 文件，其中包含你工作区的实际状态 ID。 4. （可选）将其添加到 `~/.bashrc` 以便永久生效： ```bash export SHORTCUT_API_TOKEN=$(cat ~/.config/shortcut/api-token 2>/dev/null | tr -d '\n') source ~/.config/shortcut/workflow-states ```
## 可用操作
### 列出 Story
```bash scripts/shortcut-list-stories.sh [--active|--completed|--all] [--json] ```
选项： - `--active` - 仅显示未完成的 Story（默认） - `--completed` - 仅显示已完成的 Story - `--all` - 包含已归档的 Story - `--json` - 输出原始 JSON
### 显示 Story 详情
```bash scripts/shortcut-show-story.sh <story-id> ```
显示完整的 Story 信息，包括： - Story 名称和状态 - 描述（如果有） - 带有完成状态的检查清单项目
### 创建 Story
```bash scripts/shortcut-create-story.sh "Story name" [--description "text"] [--type feature|bug|chore] ```
Story 类型： - `feature`（默认）- 新功能 - `bug` - 缺陷修复 - `chore` - 维护任务
### 更新 Story
```bash scripts/shortcut-update-story.sh <story-id> [--complete|--todo|--in-progress] [--description "new text"] ```
**工作流状态：** 脚本使用 `~/.config/shortcut/workflow-states` 中的状态 ID（由 `shortcut-init-workflow.sh` 创建）。如果未配置，则回退到通用默认值： - Backlog（待办事项）：`500000006` - To Do（计划中）：`500000007` - In Progress（进行中）：`500000008` - In Review（审核中）：`500000009` - Done（已完成）：`500000010`
**注意：** 不同的 Shortcut 工作区可能使用不同的状态 ID。请务必运行 `shortcut-init-workflow.sh` 来配置你工作区的实际 ID。
### 管理检查清单任务
**创建任务：** ```bash scripts/shortcut-create-task.sh <story-id> "task description" ```
**更新任务完成状态：** ```bash scripts/shortcut-update-task.sh <story-id> <task-id> [--complete|--incomplete] ```
**编辑任务描述：** ```bash scripts/shortcut-edit-task.sh <story-id> <task-id> "new description" ```
**删除任务：** ```bash scripts/shortcut-delete-task.sh <story-id> <task-id> ```
使用 `shortcut-show-story.sh` 查看任务 ID。
### 管理评论
**添加评论：** ```bash scripts/shortcut-add-comment.sh <story-id> "comment text" ```
**更新评论：** ```bash scripts/shortcut-update-comment.sh <story-id> <comment-id> "new text" ```
**删除评论：** ```bash scripts/shortcut-delete-comment.sh <story-id> <comment-id> ```
使用 `shortcut-show-story.sh` 查看评论 ID。
## 工作流
1. 列出现有 Story 以了解当前看板状态 2. 使用描述性名称和适当的类型创建新 Story 3. 随着工作进展更新 Story 状态
## 注意事项
- 脚本使用 `SHORTCUT_API_TOKEN` 环境变量，或回退使用 `~/.config/shortcut/api-token` - Story 默认创建于“未开始”状态（workflow_state_id：500000006） - 如果你工作区使用不同的工作流状态 ID，你可能需要调整脚本 - Token 必须拥有你要管理工作区的相应权限