OpenSkillIndex← back to search
claude-code

Awesome-omni-skill kanban

Code Kanban 本地任务管理系统。支持项目、任务、Worktree 的完整 CRUD 操作。私有数据不暴露到公开 GitHub。

install
source · Clone the upstream repo
git clone https://github.com/diegosouzapw/awesome-omni-skill
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/cli-automation/kanban" ~/.claude/skills/diegosouzapw-awesome-omni-skill-kanban && rm -rf "$T"
manifest: skills/cli-automation/kanban/SKILL.md
safety · automated scan (low risk)
This is a pattern-based risk scan, not a security review. Our crawler flagged:
  • makes HTTP requests (curl)
  • references .env files
Always read a skill's source content before installing. Patterns alone don't mean the skill is malicious — but they warrant attention.
source content

kanban (本地任务管理)

Code Kanban API 的完整封装，支持项目管理、任务管理、Worktree 集成。

环境配置

# 设置 API 地址 (CodeKanban 官方默认 3005，本项目使用 3007)
export KANBAN_URL="http://127.0.0.1:3007"

注意: 下文所有 

${API}
均指 
${KANBAN_URL}/api/v1

AI 使用建议

优先使用 CLI 而非直接调用 API，CLI 封装了常用操作且输出更简洁：

# 推荐：CLI 方式
node ~/.claude/skills/kanban/kanban-cli.js list --status=todo

# 不推荐：直接 curl API（输出冗长，占用上下文）
curl -s "${API}/projects/{id}/tasks" | jq ...

常用场景：

场景命令
快速查看待办
list --status=todo
查看进行中详情
list --status=in_progress -v
查看单个任务
show <短ID>
开始任务
start <id>
完成任务
done <id>
改优先级
move <id> --priority=0

命令速查

命令说明
/kanban
显示当前项目状态
/kanban list
列出所有任务 (简略)
/kanban list -v
列出所有任务 (展开详情)
/kanban list --status=todo
只看待办
/kanban list --status=in_progress
只看进行中
/kanban list --status=done
只看已完成
/kanban list --priority=0
只看 P0 紧急任务
/kanban show <id>
查看任务详情 (支持短 ID)
/kanban add <title>
创建新任务
/kanban add <title> --description=<text>
创建带描述的任务
/kanban add <title> --priority=0 --tags=t1,t2
创建带优先级和标签的任务
/kanban edit <id> --description=<text>
编辑任务描述
/kanban edit <id> --tags=t1,t2 --due=2025-01-20
编辑标签和截止日期
/kanban done <id>
标记任务完成
/kanban start <id>
开始任务 (in_progress)
/kanban move <id> --status=todo
改回待办
/kanban move <id> --priority=0
改优先级
/kanban move <id> --worktree=<wt-id>
绑定 Worktree
/kanban batch
批量并行执行
/kanban worktree <id>
为任务创建 worktree
/kanban export
导出 AI 友好的任务上下文
/kanban export --json
导出 JSON 格式

CLI 直接调用

# CLI 路径
CLI="$HOME/.claude/skills/kanban/kanban-cli.js"

# 查看状态
node "$CLI"

# 列出任务
node "$CLI" list --status=todo
node "$CLI" list --status=in_progress -v

# 查看详情 (支持短 ID)
node "$CLI" show WtS0Nofb

# 创建任务 (支持全量参数)
node "$CLI" add "新任务标题" --priority=1
node "$CLI" add "带描述任务" --priority=0 --description="任务详情\n第二行" --tags=type/feature,epic/xxx --due=2025-01-20

# 编辑任务 (更新内容)
node "$CLI" edit <id> --description="新描述"
node "$CLI" edit <id> "新标题" --priority=1 --tags=tag1,tag2

# 状态操作
node "$CLI" start <id>      # 开始
node "$CLI" done <id>       # 完成
node "$CLI" move <id> --status=todo --priority=0  # 移动

# 绑定 Worktree
node "$CLI" move <id> --worktree=<wt-id>
node "$CLI" move <id> --worktree=  # 解绑 (空字符串)

# 删除任务
node "$CLI" delete <id>

# 批量导入
node "$CLI" import tasks.json

# JSON 输出
node "$CLI" list --json
node "$CLI" show <id> --json

基础配置

# Shell 中使用
KANBAN_URL="${KANBAN_URL:-http://127.0.0.1:3007}"
API="${KANBAN_URL}/api/v1"

// JavaScript 中使用
const BASE_URL = process.env.KANBAN_URL || "http://127.0.0.1:3007";
const API = `${BASE_URL}/api/v1`;

1. 项目操作

1.1 列出项目

curl -s "${API}/projects" | jq '.items[] | {id, name, path}'

1.2 检测当前项目

# 根据当前目录匹配项目
CWD=$(pwd)
curl -s "${API}/projects" | jq --arg cwd "$CWD" '.items[] | select(.path == $cwd)'

1.3 创建项目

curl -X POST "${API}/projects/create" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "项目名称",
    "path": "/path/to/project",
    "description": "项目描述",
    "defaultBranch": "main"
  }'

1.4 更新项目

curl -X POST "${API}/projects/{projectId}/update" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "新名称",
    "description": "新描述"
  }'

2. 任务操作

2.1 列出任务

# 所有任务
curl -s "${API}/projects/{projectId}/tasks" | jq '.items'

# 按状态过滤
curl -s "${API}/projects/{projectId}/tasks" | jq '.items[] | select(.status == "todo")'

# 按优先级过滤
curl -s "${API}/projects/{projectId}/tasks" | jq '.items[] | select(.priority == 0)'

2.2 创建任务

curl -X POST "${API}/projects/{projectId}/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "任务标题",
    "description": "任务描述\n\nDepends on: [task-id]",
    "status": "todo",
    "priority": 0,
    "tags": ["type/feature", "epic/lifecycle"],
    "dueDate": null,
    "worktreeId": null
  }'

注意: 

dueDate
和 
worktreeId
为必填字段，可设为 
null

优先级定义:

  • 0
    : P0 紧急
  • 1
    : P1 高
  • 2
    : P2 中
  • 3
    : P3 低

2.3 更新任务内容

# 更新标题和描述（不支持 status）
curl -X POST "${API}/tasks/{taskId}/update" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新标题",
    "description": "新描述",
    "priority": 0,
    "tags": ["tag1", "tag2"],
    "dueDate": "2026-01-20T23:59:59+08:00"
  }'

UpdateTaskBody 支持的字段:

  • title
    - 任务标题
  • description
    - 任务描述
  • priority
    - 优先级 (0-3)
  • tags
    - 标签数组
  • dueDate
    - 截止日期 (ISO 8601)

注意: 

status
字段不在 UpdateTaskBody 中，需使用 
/move
端点。

2.4 移动任务（更新状态）

# 更新状态为 done
curl -X POST "${API}/tasks/{taskId}/move" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}'

# 更新状态为 in_progress
curl -X POST "${API}/tasks/{taskId}/move" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

# 同时更新状态和排序
curl -X POST "${API}/tasks/{taskId}/move" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "orderIndex": 1000,
    "worktreeId": "optional-worktree-id"
  }'

MoveTaskBody 支持的字段:

  • status
    - 新状态 (todo/in_progress/done/blocked)
  • orderIndex
    - 排序索引
  • worktreeId
    - 关联 Worktree

2.5 删除任务

curl -X DELETE "${API}/tasks/{taskId}/delete"

2.6 任务状态流转

todo → in_progress → done
         ↓
       blocked (可选)

3. Worktree 操作

3.1 列出 Worktrees

curl -s "${API}/projects/{projectId}/worktrees" | jq '.items'

3.2 创建 Worktree（推荐方式）

不要使用 Kanban API 创建 worktree，它会放在项目内部。使用 git 手动创建到项目同级目录：

# 推荐路径结构：项目同级平铺，命名为 {project-name}-{branch-safe}
# 例如：/mnt/f/pb/paper-burner → /mnt/f/pb/paper-burner-fix-issue-123

PROJECT_PATH="/path/to/project"
PROJECT_NAME=$(basename "$PROJECT_PATH")
BRANCH_NAME="fix/issue-123"
BRANCH_SAFE=$(echo "$BRANCH_NAME" | tr '/' '-')
WORKTREE_PATH="$(dirname "$PROJECT_PATH")/${PROJECT_NAME}-${BRANCH_SAFE}"

# 创建 worktree
git -C "$PROJECT_PATH" worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"

# 同步到 Kanban
curl -s -X POST "${API}/projects/${PROJECT_ID}/sync-worktrees"

命名惯例：

{project}-{branch-safe}
，如 
paper-burner-fix-test-assertions

3.3 删除 Worktree

# 删除 worktree 并删除分支
curl -X POST "${API}/worktrees/{worktreeId}?deleteBranch=true"

# 仅删除 worktree，保留分支
curl -X POST "${API}/worktrees/{worktreeId}?deleteBranch=false"

# 强制删除（有未提交更改时）
curl -X POST "${API}/worktrees/{worktreeId}?force=true&deleteBranch=true"

3.4 绑定任务到 Worktree

curl -X POST "${API}/tasks/{taskId}/move" \
  -H "Content-Type: application/json" \
  -d '{
    "worktreeId": "worktree-id"
  }'

3.4 Worktree 提交

curl -X POST "${API}/worktrees/{worktreeId}/commit" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "feat: implement feature X"
  }'

3.5 Worktree 合并

curl -X POST "${API}/worktrees/{worktreeId}/merge" \
  -H "Content-Type: application/json" \
  -d '{
    "targetBranch": "main"
  }'

4. 评论操作

4.1 获取任务评论

curl -s "${API}/tasks/{taskId}/comments" | jq '.items'

4.2 添加评论

curl -X POST "${API}/tasks/{taskId}/comments/create" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "评论内容"
  }'

5. AI 会话操作

5.1 获取任务关联的 AI 会话

curl -s "${API}/tasks/{taskId}/ai-sessions" | jq '.items'

5.2 关联 AI 会话到任务

curl -X POST "${API}/tasks/{taskId}/ai-sessions/link" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "ai-session-id"
  }'

6. 批量操作

6.1 批量执行

调用 

kanban-batch
skill:

node ~/.claude/skills/kanban-batch/kanban-planner.js [options]

6.2 批量创建任务

const tasks = [
  { title: "Task 1", priority: 0 },
  { title: "Task 2", priority: 1, deps: "Task 1" },
  { title: "Task 3", priority: 1 },
];

for (const task of tasks) {
  await fetch(`${API}/projects/${projectId}/tasks/create`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      title: task.title,
      description: task.deps ? `Depends on: [${task.deps}]` : "",
      status: "todo",
      priority: task.priority,
    }),
  });
}

7. 常用工作流

7.1 创建 Epic + 子任务

# 1. 创建 Epic 任务
EPIC_ID=$(curl -s -X POST "${API}/projects/${PROJECT_ID}/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "[Epic] 资源生命周期治理",
    "description": "## 目标\n统一实现 Disposable 模式",
    "status": "todo",
    "priority": 0,
    "tags": ["type/epic"]
  }' | jq -r '.item.id')

# 2. 创建子任务
curl -X POST "${API}/projects/${PROJECT_ID}/tasks/create" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"StateEngine dispose\",
    \"description\": \"Depends on: [${EPIC_ID}]\",
    \"status\": \"todo\",
    \"priority\": 0,
    \"tags\": [\"epic/lifecycle\"]
  }"

7.2 开始任务工作流

# 1. 创建 worktree（手动，不用 Kanban API）
PROJECT_PATH="/path/to/project"
PROJECT_NAME=$(basename "$PROJECT_PATH")
BRANCH_NAME="fix/task-xxx"
BRANCH_SAFE=$(echo "$BRANCH_NAME" | tr '/' '-')
WORKTREE_PATH="$(dirname "$PROJECT_PATH")/${PROJECT_NAME}-${BRANCH_SAFE}"

git -C "$PROJECT_PATH" worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"

# 2. 同步并获取 worktree ID
curl -s -X POST "${API}/projects/${PROJECT_ID}/sync-worktrees"
WORKTREE_ID=$(curl -s "${API}/projects/${PROJECT_ID}/worktrees" | node -e "
const d=JSON.parse(require('fs').readFileSync(0,'utf8'));
const wt = d.items?.find(w => w.branchName === '$BRANCH_NAME');
console.log(wt?.id || '');
")

# 3. 绑定到任务并更新状态为进行中
curl -X POST "${API}/tasks/${TASK_ID}/move" \
  -H "Content-Type: application/json" \
  -d "{\"worktreeId\": \"${WORKTREE_ID}\", \"status\": \"in_progress\"}"

7.3 完成任务工作流

# 1. 提交代码
curl -X POST "${API}/worktrees/${WORKTREE_ID}/commit" \
  -H "Content-Type: application/json" \
  -d '{"message": "fix: implement dispose"}'

# 2. 合并到主分支
curl -X POST "${API}/worktrees/${WORKTREE_ID}/merge" \
  -H "Content-Type: application/json" \
  -d '{"targetBranch": "main"}'

# 3. 标记任务完成
curl -X POST "${API}/tasks/${TASK_ID}/move" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}'

8. 查询示例

8.1 看板视图

echo "=== TODO ==="
curl -s "${API}/projects/${PROJECT_ID}/tasks" | jq -r '.items[] | select(.status == "todo") | "[\(.priority)] \(.title)"'

echo "=== IN PROGRESS ==="
curl -s "${API}/projects/${PROJECT_ID}/tasks" | jq -r '.items[] | select(.status == "in_progress") | "[\(.priority)] \(.title)"'

echo "=== DONE ==="
curl -s "${API}/projects/${PROJECT_ID}/tasks" | jq -r '.items[] | select(.status == "done") | "[\(.priority)] \(.title)"'

8.2 优先级统计

curl -s "${API}/projects/${PROJECT_ID}/tasks" | jq '
  .items | group_by(.priority) |
  map({priority: .[0].priority, count: length})
'

8.3 今日到期任务

TODAY=$(date +%Y-%m-%d)
curl -s "${API}/projects/${PROJECT_ID}/tasks" | jq --arg today "$TODAY" '
  .items[] | select(.dueDate != null and (.dueDate | startswith($today)))
'

9. 系统操作

9.1 健康检查

curl -s "${API}/health"

9.2 版本信息

curl -s "${API}/system/version"

9.3 AI 助手状态

curl -s "${API}/system/ai-assistant-status"

10. 执行指令

当用户调用 

/kanban
时:

无参数 - 显示当前项目状态

# 检测项目
PROJECT=$(curl -s "${API}/projects" | jq --arg cwd "$(pwd)" '.items[] | select(.path == $cwd)')
PROJECT_ID=$(echo $PROJECT | jq -r '.id')
PROJECT_NAME=$(echo $PROJECT | jq -r '.name')

echo "Project: $PROJECT_NAME"

# 显示任务统计
TASKS=$(curl -s "${API}/projects/${PROJECT_ID}/tasks")
TODO=$(echo $TASKS | jq '[.items[] | select(.status == "todo")] | length')
IN_PROGRESS=$(echo $TASKS | jq '[.items[] | select(.status == "in_progress")] | length')
DONE=$(echo $TASKS | jq '[.items[] | select(.status == "done")] | length')

echo "Tasks: $TODO todo, $IN_PROGRESS in progress, $DONE done"

list - 列出任务

curl -s "${API}/projects/${PROJECT_ID}/tasks" | jq -r '
  .items | sort_by(.priority) | .[] |
  "[P\(.priority)] [\(.status)] \(.title) (\(.id))"
'

add <title> - 创建任务

curl -X POST "${API}/projects/${PROJECT_ID}/tasks/create" \
  -H "Content-Type: application/json" \
  -d "{\"title\": \"$TITLE\", \"status\": \"todo\", \"priority\": 2}"

done <id> - 完成任务

curl -X POST "${API}/tasks/${TASK_ID}/move" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}'

batch - 批量执行

node ~/.claude/skills/kanban-batch/kanban-planner.js

worktree <task-id> - 创建并绑定 worktree

重要: 不使用 Kanban API 创建 worktree（会放在项目内部），而是手动用 git 创建到项目外部，然后绑定。

AI 执行流程:

  1. 检查工作区状态（前置条件）

    git -C "$PROJECT_PATH" status --porcelain
    • 如果工作区不干净（有未提交的更改），停止流程
    • 提示用户： 
      ⚠️ 工作区不干净，有未提交的更改：
[列出更改的文件]

建议：请先提交或暂存当前更改，保持工作区干净后再创建 worktree。

可选操作：
- git stash（暂存更改）
- git commit（提交更改）
- 继续（不推荐，可能导致状态混乱）
    • 等待用户处理后再继续

  2. 分析现有 worktree 位置

    git -C "$PROJECT_PATH" worktree list

    查看已有 worktree 放在哪里，推断用户偏好。

  3. 检查项目结构

    • 项目路径是什么？
    • 同级目录已有哪些 worktree？
    • 命名惯例：
      {project}-{branch-safe}
      （同级平铺）

  4. 提出建议并请求用户确认

    === Worktree 创建计划 ===
任务: [任务标题]
分支名: fix/xxx
建议路径: /path/to/project-fix-xxx

基于: [说明为什么建议这个路径，如已有 worktree 的命名惯例]

确认创建? 或指定其他路径?

  5. 用户确认后，手动创建 worktree

    git -C "$PROJECT_PATH" worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"

  6. 刷新 Kanban 并绑定任务

    # 刷新 Kanban worktree 列表
curl -s -X POST "${API}/projects/${PROJECT_ID}/sync-worktrees"

# 获取新 worktree 的 ID
WORKTREE_ID=$(curl -s "${API}/projects/${PROJECT_ID}/worktrees" | node -e "
const d=JSON.parse(require('fs').readFileSync(0,'utf8'));
const wt = d.items?.find(w => w.branchName === '$BRANCH_NAME');
console.log(wt?.id || '');
")

# 绑定到任务并开始
curl -X POST "${API}/tasks/${TASK_ID}/move" \
  -H "Content-Type: application/json" \
  -d "{\"worktreeId\": \"${WORKTREE_ID}\", \"status\": \"in_progress\"}"

  7. 输出结果

    Worktree 已创建并绑定:
  路径: $WORKTREE_PATH
  分支: $BRANCH_NAME
  任务: $TASK_TITLE

与 GitHub 对比

功能GitHubCode Kanban
Issues公开私有
Projects需创建自动
Worktree手动API 集成
AI 会话无原生追踪
终端集成无原生支持
离线使用否是

常见坑点

API 方法

所有写操作都用 POST，不用 PUT/PATCH！

操作正确错误
更新任务内容
POST /tasks/{id}/update
PUT /tasks/{id}
更新任务状态
POST /tasks/{id}/move
PUT /tasks/{id}/update
创建任务
POST /projects/{id}/tasks/create
POST /projects/{id}/tasks

UpdateTaskBody vs MoveTaskBody

  • UpdateTaskBody (
    /update
    ): title, description, priority, tags, dueDate
  • MoveTaskBody (
    /move
    ): status, orderIndex, worktreeId

status
字段只在 MoveTaskBody 中，不要在 
/update
里传！

端点路径

操作端点
获取单个任务
GET /api/v1/tasks/{id}
列出项目任务
GET /api/v1/projects/{projectId}/tasks
创建任务
POST /api/v1/projects/{projectId}/tasks/create
更新任务内容
POST /api/v1/tasks/{id}/update
更新任务状态
POST /api/v1/tasks/{id}/move

API 文档

  • 在线文档: 
    ${KANBAN_URL}/docs
  • OpenAPI 规范: 
    ${KANBAN_URL}/openapi.yaml

Node.js 替代 jq

当系统没有 jq 时，用 node 替代:

# 替代 jq '.items'
curl -s "${API}/tasks" | node -e "
const d = JSON.parse(require('fs').readFileSync(0, 'utf8'));
console.log(JSON.stringify(d.items, null, 2));
"

# 替代 jq -r '.item.id'
curl -s "${API}/tasks/${ID}" | node -e "
const d = JSON.parse(require('fs').readFileSync(0, 'utf8'));
console.log(d.item?.id);
"

Worktree 相关坑点

1. 不要用 Kanban API 创建 worktree

Kanban API 创建的 worktree 会放在项目配置的 

worktreeBasePath
（默认是项目内部 
.worktrees/
），且这个配置无法通过 API 修改（
UpdateProjectInputBody
不支持）。

正确做法：手动用 

git worktree add
创建到项目外部，然后调用 
sync-worktrees
让 Kanban 检测到它。

2. 解绑 worktreeId 用空字符串，不是 null

# ❌ 错误 - null 不生效
curl -X POST "${API}/tasks/{id}/move" -d '{"worktreeId": null}'

# ✅ 正确 - 用空字符串
curl -X POST "${API}/tasks/{id}/move" -d '{"worktreeId": ""}'

3. 删除外部 worktree 后需同步

# 删除 worktree
git worktree remove /path/to/worktree

# 同步 Kanban（否则它还认为 worktree 存在）
curl -s -X POST "${API}/projects/${PROJECT_ID}/sync-worktrees"

4. Kanban 会自动检测外部创建的 worktree

只要 worktree 属于该项目的 git 仓库，

sync-worktrees
或 
worktrees
列表接口就能发现它，无论路径在哪里。

项目配置限制

UpdateProjectInputBody
只支持以下字段：

  • name
    - 项目名称
  • description
    - 项目描述
  • hidePath
    - 是否隐藏路径

不支持修改：

worktreeBasePath
、
defaultBranch
、
path
等。这些只能在创建项目时设置。