kanban-zone

分类: 开发与编程 | 上传者: MaxGood-AI | 下载: 0 | 版本: v1.0（最新）
通过看板区域 API 与看板区域看板进行交互。当用户想要管理看板卡、查看看板、在列之间移动卡、检查 WIP 限制、链接卡、跨看板搜索或获取看板级指标时使用。支持列表板、创建/更新/移动卡片、卡片链接、自定义字段、观察者、过滤和跨板搜索。即使用户只是说“检查看板”、“正在进行什么”或提到看板卡，也可以使用此技能。
更新日志: Source: GitHub https://github.com/MaxGood-AI/kanban-zone-agent-skill
目录结构

当前层级: tree/main/
📁 references/
- 📄 api-reference.md 9.9 KB
📁 scripts/
- 📄 kanban_zone_api.py 21.9 KB
📄 .clawhubignore 30 B
📄 .gitignore 34 B
📄 AGENTS.md 3.7 KB
📄 LICENSE.txt 1.1 KB
📄 README.md 11.3 KB
📄 SKILL.md 11.3 KB
SKILL.md

---
name: kanban-zone
description: Interact with Kanban Zone kanban boards via the Kanban Zone API. Use when the user wants to manage kanban cards, view boards, move cards between columns, check WIP limits, link cards, search across boards, or get board-level metrics. Supports listing boards, creating/updating/moving cards, card links, custom fields, watchers, filtering, and cross-board search. Even if the user just says "check the board", "what's in progress", or mentions kanban cards, use this skill.
license: MIT
compatibility: Requires python3 and environment variables KANBAN_ZONE_API_KEY and KANBAN_ZONE_BOARD_ID
metadata:
  version: "2.1.0"
  openclaw:
    requires:
      env:
        - KANBAN_ZONE_API_KEY
        - KANBAN_ZONE_BOARD_ID
      bins:
        - python3
    primaryEnv: KANBAN_ZONE_API_KEY
    homepage: https://docs.kanbanzone.io
---

# Kanban Zone

Manage Kanban Zone kanban boards through the Kanban Zone Public API (v1.3).

## ⚠️ Exec Safety Rule — Multi-line Commands

**Never pass multi-line shell commands or long `--description` strings inline to `exec`.** The exec preflight will block them as "complex interpreter invocation".

**Always write to a temp file first:**

```python
# Write description to temp file
with open('/tmp/kanban-zone-desc.txt', 'w') as f:
    f.write("""Your multi-line
description here""")

# Then run the CLI via a script file
script = '''import subprocess
result = subprocess.run(
    ["python3", "skills/kanban-zone/scripts/kanban_zone_api.py",
     "update-card", "--id", "123",
     "--description", open("/tmp/kanban-zone-desc.txt").read()],
    capture_output=True, text=True
)
print(result.stdout)
print(result.stderr)
'''
with open('/tmp/kanban-zone-run.py', 'w') as f:
    f.write(script)
# Then exec: python3 /tmp/kanban-zone-run.py
```

Or simply build the whole call as a Python script in `/tmp/` and exec that file directly.

## Environment Setup

The CLI script reads two environment variables: `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID`.

The script **automatically loads** these from a `.env` file if they are not already in the environment. It searches for `.env` in the current working directory and in the skill's parent directory. No shell export or command substitution is needed — just run the Python command directly.

**Get your API key:** Settings > Organization Settings > Integrations > API Key
Direct: `https://kanbanzone.io/settings/integrations`

**Find column IDs:** Board Settings > API, or Organization Settings > Integrations > API

## Quick Start

All examples below assume a `.env` file with `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID` exists in the workspace root.

```bash
# List all boards
python3 scripts/kanban_zone_api.py boards

# Get board details with columns and WIP limits
python3 scripts/kanban_zone_api.py board --include-columns

# List cards on default board
python3 scripts/kanban_zone_api.py cards

# Filter cards by label and blocked status
python3 scripts/kanban_zone_api.py cards --label "Bug" --blocked

# Search cards by keyword
python3 scripts/kanban_zone_api.py cards --query "authentication"

# Get a specific card
python3 scripts/kanban_zone_api.py card --number 42

# Create a card with watchers and custom fields
python3 scripts/kanban_zone_api.py create-card --title "New task" --column-id abc123 \
  --owner user@example.com --watcher reviewer@example.com \
  --custom-field "Sprint=42" --custom-field "Team=Platform"

# Move a card to a column
python3 scripts/kanban_zone_api.py move-card --id 42 --column-id abc123

# Link cards together
python3 scripts/kanban_zone_api.py link-card --id 42 --card 99

# Link to an external URL
python3 scripts/kanban_zone_api.py link-card --id 42 --url "https://docs.example.com" --title "Spec"

# Remove a link
python3 scripts/kanban_zone_api.py unlink-card --id 42 --card 99

# Search cards across all boards
python3 scripts/kanban_zone_api.py search-cards --query "deploy"

# Check WIP limits
python3 scripts/kanban_zone_api.py wip-check
```

## Core Workflows

### Board Overview
1. Run `boards` to list all boards and their metrics (active/blocked/overdue counts).
2. Run `board --include-columns` on a specific board to see columns, their states, and WIP limits.
3. Use `wip-check` to compare current card counts against min/max WIP limits.

### Card Lifecycle
1. **Create**: `create-card --title "..." --column-id <backlog-col>` to add a card.
2. **Assign**: `update-card --id <num> --owner user@example.com` to assign an owner.
3. **Watch**: `update-card --id <num> --watcher watcher@example.com` to add watchers.
4. **Move**: `move-card --id <num> --column-id <target-col>` to advance through columns.
5. **Complete**: Move the card to a Done-state column.

### Card Review
1. `card --number <num>` to read card details, description, and current state.
2. `update-card --id <num> --description-file /tmp/kanban-zone-desc.txt` to update content (write file first, then run command).
3. `update-card --id <num> --blocked true --blocked-reason "Waiting on X"` to flag blockers.

### Description Updates (IMPORTANT)

**Always use `--description-file` instead of `--description` for creating or updating card descriptions.** This avoids multi-line quoting issues in shell commands.

**Always format descriptions as HTML, never Markdown.** Kanban Zone renders card descriptions as HTML. Use tags like `<h3>`, `<p>`, `<ul>/<li>`, `<strong>`, `<em>`, `<a href="...">`, and `<br>` instead of Markdown syntax (`###`, `**`, `-`, `[text](url)`, etc.).

**⚠️ NEVER use HTML tables in descriptions.** Kanban Zone **silently strips** `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>` tags — the data disappears from the rendered card without warning. For **any** tabular data, use a `<pre>` block with fixed-width ASCII columns instead (this is the HTML equivalent of Markdown triple-backtick code blocks). Example:

```html
<pre>
Field         | Value
--------------+------------
Priority      | High
Due date      | 2026-04-30
Owner         | sarah@co.com
</pre>
```

Do not attempt to "illustrate tables of data with HTML tables" — always use `<pre>` with fixed-width characters.

Workflow:
1. Write the description content to a temp file (e.g., `/tmp/kanban-zone-desc.txt`) using the Write tool.
2. Run the command with `--description-file /tmp/kanban-zone-desc.txt`.

```bash
# CORRECT — use --description-file for all description changes
python3 scripts/kanban_zone_api.py update-card --id 42 --description-file /tmp/kanban-zone-desc.txt
python3 scripts/kanban_zone_api.py create-card --title "New task" --description-file /tmp/kanban-zone-desc.txt

# AVOID — inline --description with multi-line content
python3 scripts/kanban_zone_api.py update-card --id 42 --description "line 1\nline 2\n..."
```

The `--description-file` flag reads the entire file content as the description. It overrides `--description` if both are provided.

### Card Links
1. `link-card --id <num> --card <other-num>` to create a card-to-card link (default type: `related`).
2. `link-card --id <num> --url "https://..." --title "Reference" --type external` to add an external URL link.
3. `unlink-card --id <num> --card <other-num>` to remove a card link.
4. `unlink-card --id <num> --url "https://..."` to remove a URL link.

### Custom Fields
Set custom metadata on cards during creation or update:
```bash
python3 scripts/kanban_zone_api.py create-card --title "Task" \
  --custom-field "Sprint=42" --custom-field "Team=Platform" --custom-field "Estimate=3d"
```

### Filtering & Search
Filter cards on a single board:
```bash
python3 scripts/kanban_zone_api.py cards --label "Bug" --owner "dev@example.com" --blocked
python3 scripts/kanban_zone_api.py cards --column "In Progress" --priority 1
python3 scripts/kanban_zone_api.py cards --query "login"
```

Search across all boards:
```bash
python3 scripts/kanban_zone_api.py search-cards --query "deploy" --label "Enhancement"
```

### WIP Limit Checking
Run `wip-check` to get a report comparing current card counts to each column's min/max WIP limits. Columns exceeding their max or below their min are flagged.

### Batch Operations
`create-cards --file cards.json` to create multiple cards at once. The JSON file should contain:
```json
{
  "board": "board-public-id",
  "cards": [
    {"title": "Card 1", "columnId": "col-id"},
    {"title": "Card 2", "columnId": "col-id", "watchers": ["a@b.com"], "customFields": [{"label": "Sprint", "value": "42"}]}
  ]
}
```

## Board & Column Name Resolution (Agent Cache)

To avoid unnecessary API calls when resolving board or column names to IDs, maintain a local cache file in your memory directory.

### Cache file

Store `kanbanzone-cache.json` in your persistent memory directory with this structure:

```json
{
  "boards": {
    "<board-public-id>": {
      "name": "Board Name",
      "columns": {
        "<column-id>": { "name": "Column Name", "state": "In Progress" }
      }
    }
  },
  "updated": "2026-02-25T12:00:00Z"
}
```

### Lookup flow

1. **Before** calling the API to resolve a board name to an ID or a column name to an ID, read `kanbanzone-cache.json` from your memory directory.
2. If the cache file exists and contains a matching name (case-insensitive), use the cached ID directly — **do not call the API**.
3. If the cache file is missing, or the name is not found, call the appropriate API command (`boards` or `board --include-columns`) and then **update the cache file** with the full response data before proceeding.

### Auto-populate

Whenever you run `boards` or `board --include-columns` for any reason, always update `kanbanzone-cache.json` with the returned data. This keeps the cache fresh as a side effect of normal operations.

### Cache refresh

If the user says board or column data is stale, or explicitly asks to refresh the cache, re-fetch from the API (`boards` then `board --include-columns` for each board) and overwrite `kanbanzone-cache.json`.

### Important notes

- The cache lives in **your agent memory directory**, not in the skill's directory. This keeps the skill stateless and portable.
- Column IDs change if a board is restructured — always honor a cache miss by falling back to the API.
- When writing the cache, set `"updated"` to the current ISO 8601 timestamp.

## Column States

| State | Meaning |
|-------|---------|
| `Backlog` | Pre-commitment items |
| `To Do` | Committed, ready to start |
| `Buffer` | Queue between stages |
| `In Progress` | Currently being worked on |
| `Done` | Completed |
| `Archive` | Historical items |
| `None` | No state assigned |

## Script Reference

All commands output JSON. Run `python3 scripts/kanban_zone_api.py --help` for full usage.

| Command | Description |
|---------|-------------|
| `boards` | List all boards with metrics |
| `board` | Get a specific board's details |
| `cards` | List cards (paginated, with optional filters) |
| `card` | Get a single card by number |
| `create-card` | Create one card (supports watchers, custom fields) |
| `create-cards` | Create multiple cards from JSON |
| `update-card` | Update card fields (supports watchers, custom fields) |
| `move-card` | Move card to a column |
| `link-card` | Add a card-to-card or URL link |
| `unlink-card` | Remove a card-to-card or URL link |
| `search-cards` | Search cards across all boards |
| `wip-check` | Check WIP limits across columns |

## API Reference

See [references/api-reference.md](./references/api-reference.md) for complete endpoint documentation, data models, and response schemas.
登录后下载/点赞/收藏 ❤ 5 | ★ 0
kanban-zone

目录结构

SKILL.md

举报内容

提示
