Trello 集成技能

---
name: trello-integration-skill
description: 此技能允许您与 Trello 账户交互，自动列出看板、查看列表和创建卡片。
---

# Trello 集成技能

Trello 集成技能在 AI 代理和用户的 Trello 账户之间提供了无缝连接。它使代理能够根据用户提示自主获取现有看板和列表，并在特定看板上创建新的任务卡片。

## 功能
- **获取看板**：检索用户有权访问的所有 Trello 看板列表，包括它们的名称、ID 和 URL。
- **获取列表**：检索属于特定看板的所有列表（例如“待办”、“进行中”、“已完成”等列）。
- **创建卡片**：在指定列表中自动创建带有标题和描述的新卡片。

---

## 设置与先决条件

要在本地使用此技能，您需要提供您的 Trello 开发者 API 凭据。

1. 在 [Trello 开发者门户 (Power-Ups Admin)](https://trello.com/app-key) 生成您的凭据。
2. 创建一个 API 密钥。
3. 生成一个秘密令牌（读/写访问权限）。
4. 将这些凭据添加到项目的根目录 `.env` 文件中：

```env
# Trello 集成
TRELLO_API_KEY=your_api_key_here
TRELLO_TOKEN=your_token_here
```

---

## 用法与架构

此技能利用位于 `.agent/skills/trello_skill/scripts/` 目录中的独立 Node.js 脚本。

### 1. 列出所有看板
获取已认证用户的所有看板，以确定正确的 `boardId`。

**执行：**
```bash
node .agent/skills/trello_skill/scripts/list_boards.js
```

### 2. 列出看板中的列（列表）
获取特定看板内的列表，以找到确切的 `listId`（例如，检索“待办”列的 ID）。

**执行：**
```bash
node .agent/skills/trello_skill/scripts/list_lists.js <boardId>
```

### 3. 创建新卡片
将新卡片推送到指定的列表。

**执行：**
```bash
node .agent/skills/trello_skill/scripts/create_card.js <listId> "<卡片标题>" "<可选描述>"
```
*（始终将卡片标题和描述用双引号括起来，以防止 bash 参数拆分）。*

---

## AI 代理工作流程

当用户请求管理或向 Trello 添加任务时，请自主遵循以下步骤：
1. **识别目标**：如果 `listId` 未知，首先运行 `list_boards.js` 以识别正确的 `boardId`，然后执行 `list_lists.js <boardId>` 以检索相应的 `listId`（例如，针对“待办”）。
2. **执行命令**：运行 `create_card.js <listId> "任务标题" "任务描述"` 脚本。
3. **报告结果**：向用户确认成功创建，并提供新创建的 Trello 卡片的直接 URL。
FILE:create_card.js
const path = require('path');
require('dotenv').config({ path: path.join(__dirname, '../../../../.env') });

const API_KEY = process.env.TRELLO_API_KEY;
const TOKEN = process.env.TRELLO_TOKEN;

if (!API_KEY || !TOKEN) {
    console.error("错误：.env 文件中缺少 TRELLO_API_KEY 或 TRELLO_TOKEN。");
    process.exit(1);
}

const listId = process.argv[2];
const cardName = process.argv[3];
const cardDesc = process.argv[4] || "";

if (!listId || !cardName) {
    console.error(`用法：node create_card.js <listId> "${card_name}" ["${card_description}"]`);
    process.exit(1);
}

async function createCard() {
    const url = `https://api.trello.com/1/cards?idList=${listId}&key=${API_KEY}&token=${TOKEN}`;

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                name: cardName,
                desc: cardDesc,
                pos: 'top'
            })
        });

        if (!response.ok) {
            const errText = await response.text();
            throw new Error(`HTTP 错误！状态：${response.status}，消息：${errText}`);
        }
        const card = await response.json();
        console.log(`成功创建卡片！`);
        console.log(`名称：${card.name}`);
        console.log(`ID：${card.id}`);
        console.log(`URL：${card.url}`);
    } catch (error) {
        console.error("创建卡片失败：", error.message);
    }
}

createCard();
FILE:list_board.js
const path = require('path');
require('dotenv').config({ path: path.join(__dirname, '../../../../.env') });

const API_KEY = process.env.TRELLO_API_KEY;
const TOKEN = process.env.TRELLO_TOKEN;

if (!API_KEY || !TOKEN) {
    console.error("错误：.env 文件中缺少 TRELLO_API_KEY 或 TRELLO_TOKEN。");
    process.exit(1);
}

async function listBoards() {
    const url = `https://api.trello.com/1/members/me/boards?key=${API_KEY}&token=${TOKEN}&fields=name,url`;
    try {
        const response = await fetch(url);
        if (!response.ok) throw new Error(`HTTP 错误！状态：${response.status}`);
        const boards = await response.json();
        console.log("--- 您的 Trello 看板 ---");
        boards.forEach(b => console.log(`名称：${b.name}\nID：${b.id}\nURL：${b.url}\n`));
    } catch (error) {
        console.error("获取看板失败：", error.message);
    }
}

listBoards();
FILE:list_lists.js
const path = require('path');
require('dotenv').config({ path: path.join(__dirname, '../../../../.env') });

const API_KEY = process.env.TRELLO_API_KEY;
const TOKEN = process.env.TRELLO_TOKEN;

if (!API_KEY || !TOKEN) {
    console.error("错误：.env 文件中缺少 TRELLO_API_KEY 或 TRELLO_TOKEN。");
    process.exit(1);
}

const boardId = process.argv[2];
if (!boardId) {
    console.error("用法：node list_lists.js <boardId>");
    process.exit(1);
}

async function listLists() {
    const url = `https://api.trello.com/1/boards/${boardId}/lists?key=${API_KEY}&token=${TOKEN}&fields=name`;
    try {
        const response = await fetch(url);
        if (!response.ok) throw new Error(`HTTP 错误！状态：${response.status}`);
        const lists = await response.json();
        console.log(`--- 看板 ${boardId} 中的列表 ---`);
        lists.forEach(l => console.log(`名称："${l.name}"\nID：${l.id}\n`));
    } catch (error) {
        console.error("获取列表失败：", error.message);
    }
}

listLists();