介绍
# Asana (Clawdbot skill)
此技能专为 **个人仅限本地使用** 的 Asana 集成而设计，使用 **OAuth** 配合 **带外/手动代码粘贴** 流程。
## 此技能提供的功能 - 一个小型的 Node CLI 工具，用于： - 生成 Asana 授权 URL - 将授权代码交换为访问令牌/刷新令牌 - 自动刷新访问令牌 - 发起基本的 API 调用（例如 `/users/me`、`/workspaces`、任务）
## 设置 (OAuth, OOB/手动代码)
### 0) 创建一个 Asana 应用 在 Asana Developer Console (My apps) 中： - 创建应用 - 启用您将需要的权限（通常为：`tasks:read`、`tasks:write`、`projects:read`） - 将重定向 URI 设置为 OOB 值（手动代码）： - `urn:ietf:wg:oauth:2.0:oob`
### 1) 提供凭据（两种选项）
**选项 A (推荐用于 Clawdbot)：** 保存到本地凭据文件： ```bash node scripts/configure.mjs --client-id "..." --client-secret "..." ``` 这会写入 `~/.clawdbot/asana/credentials.json`。
**选项 B：** 设置环境变量（shell/session）： - `ASANA_CLIENT_ID` - `ASANA_CLIENT_SECRET`
### 2) 运行 OAuth 从代码库根目录：
1) 打印授权 URL： ```bash node scripts/oauth_oob.mjs authorize ``` 2) 打开打印出的 URL，点击 **Allow (允许)**，复制代码。 3) 交换代码并在本地保存令牌： ```bash node scripts/oauth_oob.mjs token --code "PASTE_CODE_HERE" ```
令牌存储在： - `~/.clawdbot/asana/token.json`
## 聊天使用 (支持显式 + 自然语言)
您可以使用以下任一方式： - **显式命令**：以 `/asana ...` 开头发送消息 - **自然语言**：例如“列出分配给我的任务”
对于 Clawdbot，请通过将用户请求转换为相应的 `asana_api.mjs` 命令来实现映射。
示例： - `/asana tasks-assigned` → `tasks-assigned --assignee me` - “列出分配给我的任务” → `tasks-assigned --assignee me` - “列出 <project> 中的所有任务” → 将 `<project>` 解析为项目 GID，然后执行 `tasks-in-project --project <gid>` - “列出截止日期从 2026-01-01 到 2026-01-15 的任务” → `search-tasks --assignee me --due_on.after 2026-01-01 --due_on.before 2026-01-15`
(可选助手) `scripts/asana_chat.mjs` 可以将常用短语映射为命令骨架。
## 使用 API 助手
完整性检查（我是谁）： ```bash node scripts/asana_api.mjs me ```
列出工作区： ```bash node scripts/asana_api.mjs workspaces ```
设置默认工作区（可选）： ```bash node scripts/asana_api.mjs set-default-workspace --workspace <workspace_gid> ``` 在此之后，对于支持该参数的命令，您可以省略 `--workspace`。
列出工作区中的项目（显式）： ```bash node scripts/asana_api.mjs projects --workspace <workspace_gid> ``` 使用默认工作区列出项目： ```bash node scripts/asana_api.mjs projects ```
列出项目中的任务： ```bash node scripts/asana_api.mjs tasks-in-project --project <project_gid> ```
列出分配给我的任务（Asana 要求工作区）： ```bash node scripts/asana_api.mjs tasks-assigned --workspace <workspace_gid> --assignee me ``` 或使用默认工作区： ```bash node scripts/asana_api.mjs tasks-assigned --assignee me ```
搜索任务（高级搜索）： ```bash node scripts/asana_api.mjs search-tasks --workspace <workspace_gid> --text "release" --assignee me # also supports convenience: --project <project_gid> ```
查看任务： ```bash node scripts/asana_api.mjs task <task_gid> ```
将任务标记为完成： ```bash node scripts/asana_api.mjs complete-task <task_gid> ```
更新任务： ```bash node scripts/asana_api.mjs update-task <task_gid> --name "New title" --due_on 2026-02-01 ```
对任务添加评论： ```bash node scripts/asana_api.mjs comment <task_gid> --text "Update: shipped" ```
创建任务： ```bash node scripts/asana_api.mjs create-task --workspace <workspace_gid> --name "Test task" --notes "from clawdbot" --projects <project_gid> ```
## 注意事项 / 常见陷阱 - OAuth 访问令牌会过期；刷新令牌用于获取新的访问令牌。 - 如果您以后想要多用户支持，请将 OOB 替换为真实的重定向/回调地址。 - 请勿打印日志记录令牌。