clickup

ClickUp

通过 API 与 ClickUp 任务和文档交互。获取任务信息、查看评论、创建任务、管理分配、发布更新，以及创建和编辑文档。

创建任务前，请阅读 docs/dev/filing-follow-ups.md： 每个任务都需要明确的完成条件；由 Agent 生成的后续事项应放在 Agent Follow-ups，而不是 Synced Team 中。

设置

请先安装依赖——每个检出版本只需安装一次：

cd .claude/skills/clickup && npm install

lib/markdown.mjs 使用 remark 解析 Markdown，而 query.mjs 在启动时通过 lib/format.mjs 调用它。在运行此命令之前，所有命令（不只是评论相关命令）都会因 ERR_MODULE_NOT_FOUND 而退出。

然后在此技能目录中创建 accounts.json，并填入 API 令牌：

{
  "defaultAccount": "bot",
  "accounts": {
    "bot": {
      "apiToken": "pk_your_token_here"
    }
  }
}

令牌生成位置：ClickUp Settings > Apps > API Token

也可以使用 CLI 添加账户：

node query.mjs add-account bot --token pk_your_token_here

Team ID、User ID 和其他字段会在首次使用时自动检测并缓存。

从 .env 迁移：如果已有 .env 文件，凭据会在首次运行时自动迁移到 accounts.json。.env 文件会保留；准备就绪后可将其删除。

默认列表（可选）

在账户中设置 defaultListId，即可创建任务时不指定列表：

{
  "defaultAccount": "bot",
  "accounts": {
    "bot": {
      "apiToken": "pk_...",
      "defaultListId": "901111220963"
    }
  }
}

多账户

支持多个命名账户（例如，用于自动化的 "bot" 和供个人使用的 "jane"）：

{
  "defaultAccount": "bot",
  "accounts": {
    "bot": {
      "apiToken": "pk_...",
      "teamId": "8459928",
      "userId": "75386805",
      "defaultListId": "901111220963"
    },
    "jane": {
      "apiToken": "pk_...",
      "teamId": "8459928",
      "userId": "12345678"
    }
  }
}

每个账户只需提供 apiToken。其他字段会自动检测并缓存。

使用任何命令时，都可以通过 --account <name> 指定目标账户：

node query.mjs me --account jane
node query.mjs my-tasks --account bot

账户管理命令：

node query.mjs accounts                          # List all accounts
node query.mjs switch-account jane               # Change default
node query.mjs add-account jane --token pk_...   # Add account
node query.mjs remove-account old-account        # Remove account

运行命令

node query.mjs <command> [options]

任务命令

命令	描述
get <url|id>	获取任务详情（名称、描述、状态、受指派者等）
comments <url|id>	列出任务评论（使用 --threads 可在行内展开回复）
thread <comment_id>	查看特定评论的线程回复
reply <comment_id> "message"	在线程中回复评论
comment <url|id> "message"	为任务发表评论（支持 Markdown）
status <url|id> [status]	更新任务状态（或列出可用状态）
tasks <list_id>	列出清单中的任务
me	显示当前用户信息
create [list_id] "title"	创建新任务（如果已设置默认清单，list_id 可选）
my-tasks	列出工作区中分配给你的所有任务
search [query]	搜索任务——需要指定范围：--list、--folder、--me、--assignee、--status 或 --all
find-list "name"	按名称查找清单或文件夹（快速遍历结构，不获取任务）
assign <task> <user>	将任务分配给用户（按姓名、邮箱或 ID）
due <task> "date"	设置截止日期（例如："tomorrow"、"friday"、"+3d"）
priority <task> <level>	设置优先级（urgent、high、normal、low、none）
subtask <task> "title"	创建子任务
parent <task> <parent_task>	将现有任务设为另一任务的子任务
milestone <task> <on|off>	将任务设为里程碑，或恢复为普通任务
move <task> <list_id>	将任务移动到其他清单
link <task> <url> ["desc"]	添加外部链接引用（作为评论）
checklist <task> "item"	向任务添加清单项
delete-comment <comment_id>	删除评论
watch <task> <user>	将用户添加为任务的关注者
tag <task> "tag_name"	为任务添加标签
description <task> "text"	更新任务描述（支持 Markdown）
start <task> "date"	设置开始日期（日期格式与截止日期相同）
schedule <task> "start" "due"	同时设置开始日期和截止日期
rename <task> "new name"	重命名任务
depends <task> <other>	将任务设为等待另一任务完成
blocks <task> <other>	将任务设为阻塞另一任务
task-link <task> <other>	在任务之间创建双向链接
update-comment <id> "text"	更新评论内容
resolve-comment <id>	解决/关闭评论
remove-tag <task> "tag"	移除任务标签
unwatch <task> <user>	移除任务关注者
archive <task>	归档任务（从活动视图中移除）
unarchive <task>	恢复已归档的任务
claim <task>	将你的会话关联到此任务（设置 Session ID 自定义字段，以便恢复会话）

清单命令

命令	描述
list <list_id>	获取清单详情（名称、状态、任务数量）
create-list <space> "name"	在空间中创建新清单
update-list <list_id>	更新清单属性（--name、--content）
delete-list <list_id>	删除清单
lists <folder_id>	列出文件夹中的所有清单
space-lists <space_id>	列出空间中不属于文件夹的清单

文档命令

命令	描述
docs ["query"]	搜索/列出工作区中的文档（可选搜索查询）
doc <doc_id>	获取文档详情和页面列表
create-doc "title"	创建新文档（使用 --content 指定初始内容）
page <doc_id> <page_id>	获取页面内容（Markdown 格式）
create-page <doc_id> "title"	在文档中添加新页面（使用 --parent 添加子页面）
edit-page <doc_id> <page_id>	编辑页面内容或名称

附件命令

命令	描述
attach <url|id>	将文件附件上传到任务（使用 --attach path，可重复指定）
fetch-image <url>	将 ClickUp 附件下载到本地临时文件（使用 --output path 指定自定义位置）

选项

标志	描述
--json	输出原始 JSON 响应
--threads、-t	列出评论时，在行内展开线程回复
--subtasks	获取任务详情时包含子任务
--me	筛选分配给我的任务（用于 tasks 命令）
--content、-c	行内内容字符串（markdown）。仅用于简短文本。
--file、-f	从文件路径读取内容。超过一个句子的内容建议使用此选项。
--cleanup	成功执行后删除 --file 指定的文件
--name、-n	edit-page 的新页面名称
--parent、-p	create-page 的父页面 ID（创建为子页面）
--space、-s	create-doc 的空间 ID（将文档放入该空间）
--assignee、-a	创建任务时指定负责人
--due、-d	创建任务时指定截止日期
--description、--desc	创建任务时填写描述（markdown）
--attach	要上传为附件的文件路径（可重复；用于 attach 和 comment 命令）
--output	fetch-image 的自定义输出路径（默认为临时目录）
--account	使用指定名称的账户（来自 accounts.json）

示例

获取任务详情

# Using full URL
node query.mjs get "https://app.clickup.com/t/86a1b2c3d"

# Using task ID directly
node query.mjs get 86a1b2c3d

# Include subtasks
node query.mjs get 86a1b2c3d --subtasks

创建任务

# With explicit list ID
node query.mjs create 901111220963 "New feature: dark mode"

# Using default list (if CLICKUP_DEFAULT_LIST_ID is set)
node query.mjs create "Quick task"

列出我的任务

# All tasks assigned to you across the workspace
node query.mjs my-tasks

搜索任务

ClickUp 的 v2 API 不支持原生跨任务文本搜索，因此 search 需要指定一个 范围，以限制工作区遍历的范围。请选择合适的范围：

# Scope to a specific list (fastest, recommended)
node query.mjs search "authentication" --list 901111220963

# All tasks assigned to you with a particular status
node query.mjs search --me --status "in progress"

# Scope to a folder ("project") — scans every list in that folder
node query.mjs search "oauth" --folder 90111122009

# Filter by assignee + text
node query.mjs search "migration" --assignee jane

# Multiple statuses (comma-separated)
node query.mjs search --me --status "in progress,review"

# Unscoped full-workspace scan — slow, fetches every task. Use sparingly.
node query.mjs search "dark mode" --all

如果未指定范围标志（且未使用 --all），search 会给出清晰的错误提示并退出， 而不是悄悄地向 API 发起大量请求。

按名称查找列表或文件夹

如果你知道列表名称（“Red Launch”、“Triage”、“Sprint 12”），但没有 ID， 请使用 find-list——它只通过元数据端点遍历工作区结构（空间 → 文件夹 → 列表）。 速度快，无需获取任务。

node query.mjs find-list "Red Launch"
node query.mjs find-list "triage" --json

匹配结果按以下顺序排列：完全匹配 > 前缀匹配 > 包含匹配，且不区分大小写。结果会同时返回 列表匹配项和文件夹匹配项（并内嵌该文件夹中的列表），因此即使你查找的是文件夹， 也能看到你可能需要的列表。

更新任务状态

# List available statuses for a task
node query.mjs status 86a1b2c3d

# Update status (case-insensitive, partial match)
node query.mjs status 86a1b2c3d "in progress"
node query.mjs status 86a1b2c3d "complete"

分配任务

# Assign by username
node query.mjs assign 86a1b2c3d jane

# Assign by email
node query.mjs assign 86a1b2c3d [email protected]

设置截止日期

node query.mjs due 86a1b2c3d "tomorrow"
node query.mjs due 86a1b2c3d "next friday"
node query.mjs due 86a1b2c3d "+3d"
node query.mjs due 86a1b2c3d "2024-01-15"

设置优先级

node query.mjs priority 86a1b2c3d urgent
node query.mjs priority 86a1b2c3d high
node query.mjs priority 86a1b2c3d none  # Clear priority

创建子任务

node query.mjs subtask 86a1b2c3d "Write unit tests"
node query.mjs subtask 86a1b2c3d "Update documentation"

更改现有任务的父级

subtask 会创建新任务。parent 则会将现有任务归入另一个任务：

node query.mjs parent 86a1b2c3d 86a9z8y7x   # 86a1b2c3d becomes a subtask of 86a9z8y7x

该命令不会将任务设为自己的父级，也不会执行会将任务移至其后代任务之下的操作；此外，它会报告 之后从服务端读取到的父级，而不是你指定的父级。

使用前请注意以下两点：

• 无法解除父子关系。 ClickUp 的 UpdateTask 文档指出：“无法通过将 parent 设为 null，将子任务转换为任务。”要撤销父级变更，需使用 ClickUp UI。
• 跨列表更改父级会将任务移至父任务所在的列表。 将“Agent Follow-ups”中的任务移至“Synced Team”中的某个父任务下，会将该任务移至“Synced Team”；发生这种情况时，命令会显示 List moved: ... -> ...。

里程碑

node query.mjs milestone 86a1b2c3d on    # mark as milestone
node query.mjs milestone 86a1b2c3d off   # back to an ordinary task

里程碑是一种任务类型，而非状态。类型 ID 因工作区而异，因此会按名称解析，而不是硬编码。与更改父级不同，此操作可以撤销。

必须指定模式。如果 milestone <task> 未指定 on/off，命令会报错，而不会采用默认值，因为默认操作会导致一个名称看起来像查询的命令执行写入操作。

移动任务

node query.mjs move 86a1b2c3d 901111220964

添加链接

# Add link with description
node query.mjs link 86a1b2c3d "https://github.com/..." "PR #123"

# Add link without description
node query.mjs link 86a1b2c3d "https://docs.example.com/guide"

添加清单项

node query.mjs checklist 86a1b2c3d "Review code"
node query.mjs checklist 86a1b2c3d "Run tests"
node query.mjs checklist 86a1b2c3d "Deploy to staging"

列出列表中的任务

# All tasks in a list
node query.mjs tasks 901111220963

# Only tasks assigned to me
node query.mjs tasks 901111220963 --me

查看评论

node query.mjs comments "https://app.clickup.com/t/86a1b2c3d"

# Expand all threaded replies inline
node query.mjs comments 86a1b2c3d --threads

# View replies on a specific comment thread
node query.mjs thread 90110200841741

# Reply to a comment thread
node query.mjs reply 90110200841741 "Sounds good, I'll take care of it."

发布评论

node query.mjs comment 86a1b2c3d "Starting work on this task"

# Multi-line comment
node query.mjs comment 86a1b2c3d "Status update:
- Completed initial review
- Found 3 issues to address
- Will submit PR by EOD"

在评论中 @提及用户

该技能支持两种提及语法：

1. 显式（首选）： @[identifier] — 使用方括号语法，可按姓名、邮箱或用户 ID 模糊匹配
2. 裸提及（自动检测）： @Name 或 @First Last — 自动与工作区成员匹配

裸提及是后备方式，即使 Agent 忘记使用方括号语法，也能正常提及。两种方式都会生成相同的 ClickUp 提及属性。

# Explicit bracket syntax (preferred)
node query.mjs comment 86a1b2c3d "Hey @[jane], can you review this?"

# Bare mention (auto-detected against workspace members)
node query.mjs comment 86a1b2c3d "Hey @Jane Doe, can you review this?"

# Both work the same — these are equivalent:
node query.mjs comment 86a1b2c3d "@[jane] please review"
node query.mjs comment 86a1b2c3d "@Jane please review"

# Mention by numeric user ID (bracket syntax only)
node query.mjs comment 86a1b2c3d "@[12345678] please take a look"

# Mention by email (bracket syntax only)
node query.mjs comment 86a1b2c3d "Assigned to @[[email protected]]"

# Multiple mentions in one comment
node query.mjs comment 86a1b2c3d "@[jane] and @[john] - need your input on this"


**Bracket syntax**: Fuzzy matches partial names, emails, or numeric IDs. `@[jane]` matches "Jane Doe". Unknown users throw an error.

**Bare syntax**: Matches `@Name` against workspace member usernames (case-insensitive). Tries full name first (`@Jane Doe`), then first name (`@Jane`). Unmatched bare mentions are left as plain text (no error).

### Show Current User

```bash
node query.mjs me

删除评论

# Get comment IDs from the comments command (shown in --json output)
node query.mjs delete-comment 90110200841741

添加/移除关注者

# Add user as watcher on a task
node query.mjs watch 86a1b2c3d john

# Remove watcher
node query.mjs unwatch 86a1b2c3d john

添加标签

# Add a tag to a task
node query.mjs tag 86a1b2c3d "DevOps"
node query.mjs tag 86a1b2c3d "bug"

更新描述

# Update task description with markdown
node query.mjs description 86a1b2c3d "## Summary
This is a **bold** statement.

- Item 1
- Item 2

See [documentation](https://example.com) for more info."

归档/恢复任务

# Archive a task (removes from active views)
node query.mjs archive 86a1b2c3d

# Restore an archived task
node query.mjs unarchive 86a1b2c3d

认领任务（会话关联）

开始处理 ClickUp 任务时，立即认领任务，以便之后恢复会话。此操作会将 Claude Code 会话 ID 写入任务的“Session ID”自定义字段，让你可以从上次中断处继续工作。

# Claim a task as soon as you begin working on it
node query.mjs claim 86a1b2c3d

# Works with URLs too
node query.mjs claim "https://app.clickup.com/t/86a1b2c3d"

要求：

• 任务所在的列表必须有一个名称中包含“Session”的文本自定义字段（例如“Session ID”）
• 会话 ID 的解析顺序：$CLAUDE_SESSION_ID → 修改时间最新的 ~/.claude/projects/*/*.jsonl（60 秒内）。此后备方案适用于未公开该环境变量的运行环境。

何时认领： 开始处理 ClickUp 任务时立即认领。如果之后需要继续处理同一任务，就可以从上次中断处继续工作。

获取列表详情

# Get list info including statuses
node query.mjs list 901111220963

创建列表

# Create a list in a space using space ID
node query.mjs create-list 20128955 "New List"

# Create a list using space URL
node query.mjs create-list "https://app.clickup.com/8459928/v/s/20128955" "Sprint Backlog"

# Create a list with description
node query.mjs create-list 20128955 "Bug Tracker" --content "Track all bugs here"

删除列表

node query.mjs delete-list 901111220963

列出/搜索文档

# List all docs in workspace
node query.mjs docs

# Search docs by name
node query.mjs docs "API"

获取文档详情

# Get doc info and page listing
node query.mjs doc abc123def

# Using a doc URL
node query.mjs doc "https://app.clickup.com/12345/v/dc/abc123def"

创建文档

# Create an empty doc
node query.mjs create-doc "Project Notes"

# Create a doc with initial content (populates the first page)
node query.mjs create-doc "API Documentation" --content "# API Documentation

This document covers the API endpoints and usage.

## Overview
..."

获取页面内容

# Get a specific page's content
node query.mjs page abc123def page456

创建页面

# Create a page with just a title
node query.mjs create-page abc123def "New Section"

# Create a page with content
node query.mjs create-page abc123def "Getting Started" --content "# Welcome

This is the getting started guide.

## Prerequisites
- Node.js 18+
- npm or yarn"

编辑页面

# Update page content
node query.mjs edit-page abc123def page456 --content "Updated content here"

# Rename a page
node query.mjs edit-page abc123def page456 --name "New Page Name"

# Update both content and name
node query.mjs edit-page abc123def page456 --content "New content" --name "New Name"

上传附件

# Upload a single file to a task
node query.mjs attach 86a1b2c3d --attach ./screenshot.png

# Upload multiple files
node query.mjs attach 86a1b2c3d --attach ./screenshot1.png --attach ./report.pdf

# Post a comment with file attachments (comment first, then files are attached)
node query.mjs comment 86a1b2c3d "Here are the screenshots" --attach ./screenshot.png

# Comment with multiple attachments
node query.mjs comment 86a1b2c3d "Design review assets" --attach ./mockup.png --attach ./spec.pdf

支持的文件类型：图片（PNG、JPG、GIF、WebP、SVG）、文档（PDF、DOCX、XLSX）、压缩文件（ZIP），以及 ClickUp 接受的任何其他文件类型。

注意：ClickUp API 会将文件附加到任务本身（显示在任务的附件列表中）。在 comment 命令中使用 --attach 时，系统会先发布评论，然后将文件上传为任务附件。附件会显示在任务中，但不会内嵌在评论文本里。

在评论中查看附件

包含图片或文件附件的评论会在纯文本输出中内嵌显示：

[Feb 11, 2026, 04:55 PM] Jane Doe (id: 90110200000001):
  [Attachment: image.png](https://t8459928.p.clickup-attachments.com/...)
  If you look at the component, you'll see that...

若要查看实际图片，请使用 fetch-image 将其下载到本地：

# Download attachment from URL shown in comment output
node query.mjs fetch-image "https://t8459928.p.clickup-attachments.com/t8459928/.../image.png"
# → Downloaded: /tmp/clickup-attachments/image.png

# Save to a specific path
node query.mjs fetch-image "https://..." --output ./screenshot.png

下载后，使用文件查看器或 Read 工具查看图片。

基于文件的内容（推荐）

对于任何长于一句话的内容，请先写入 Markdown 文件，然后使用 --file 而非 --content。这样可以避免 shell 转义问题，并支持正确处理多行 Markdown。

工作流

1. 将内容写入临时 Markdown 文件
2. 使用 --file path/to/file.md 传入文件
3. 可选添加 --cleanup，在成功后自动删除文件

示例

# Create a doc from a prepared markdown file
node query.mjs create-doc "Architecture Spec" --file ./docs/spec.md --space 90114072520

# Update a page from a file, then auto-delete the temp file
node query.mjs edit-page abc123 page456 --file /tmp/updated-content.md --cleanup

# Post a detailed comment from a file
node query.mjs comment 86a1b2c3d --file ./review-notes.md

# Set task description from a file
node query.mjs description 86a1b2c3d --file ./task-brief.md

如何选择

方式	适用场景
--content "short text"	单行文本、简单状态更新
--file path.md	多行内容、带格式的 Markdown、规格说明、文档
--file path.md --cleanup	临时内容（Agent 写入文件、推送到 ClickUp，然后删除文件）

--file 适用于：create-doc、create-page、edit-page、comment、description、create-list、update-list

任务/列表/空间/文档 URL 格式

该技能可识别以下 ClickUp URL 格式：

任务：

• https://app.clickup.com/t/{task_id}
• https://app.clickup.com/{team_id}/v/li/{list_id}?p={task_id}
• 自定义任务 ID：#DEV-123 或 DEV-123
• 直接任务 ID：86a1b2c3d

列表：

• https://app.clickup.com/{team_id}/v/li/{list_id}
• 直接列表 ID：901111220963

空间：

• https://app.clickup.com/{team_id}/v/s/{space_id}
• 直接空间 ID：20128955

文档：

• https://app.clickup.com/{team_id}/v/dc/{doc_id}
• https://app.clickup.com/{team_id}/docs/{doc_id}
• 直接文档 ID：abc123def

适用场景

任务：

• 了解上下文：开始工作前获取任务详情
• 快速创建任务：无需离开终端即可创建任务
• 每日站会：使用 my-tasks 查看分配给你的任务
• 状态更新：工作期间发布进度评论
• 任务管理：分配任务、设置优先级和截止日期
• 协作：查看近期评论以了解上下文，并添加关注者
• 任务整理：添加标签以对任务分类
• 任务关联：在提交信息中引用任务 ID
• 会话跟踪：使用 claim 认领任务，以便之后继续工作

文档：

• 文档编写：创建和维护项目文档
• 知识库：构建参考指南和维基
• 会议记录：保存会议记录和决策
• 规范：编写和更新技术规范
• 快速编辑：无需离开终端即可更新文档内容
• 文档协作：阅读并回复文档评论，以便进行内联评审

评论线程最佳实践

回复任务讨论时，务必先检查线程上下文：

1. 发布评论前，运行 comments <task> --threads 查看现有对话。
2. 如果用户的消息或上下文提到了特定评论线程（例如，用户在某个线程中回复，或你正在继续先前的对话），使用 reply <comment_id> "text" 在该线程中发布回复——不要使用 comment <task> "text"。
3. 仅在确实属于新话题且不适合现有线程时，才使用 comment（顶层评论）。
4. 经验法则：如果你之前发布的评论有人在线程中回复，那么你接下来应使用 reply 在同一线程中回复。

提示

• 团队 ID、用户 ID 和其他字段会自动缓存到 accounts.json
• 在账户中设置 defaultListId，创建任务时即可省略 list_id
• 使用 my-tasks 快速查看分配给你的任务
• 使用自然语言日期：“tomorrow”、“next friday”、“+3d”
• 发布评论，让相关人员了解进度
• 在提交信息中包含任务 ID，以便追踪
• 使用 --json 进行脚本处理，或将输出传递给其他工具
• 文档内容的输入和输出均采用 Markdown 格式
• Docs API 使用 v3 端点（基于工作区，而非基于团队）
• 支持自定义任务 ID：#DEV-123 或 DEV-123
• 所有任务和评论查询都会自动翻页（无需手动处理页面）
• 自动处理速率限制，并在重试时采用退避策略

参考

不常用的内容位于 reference.md 中——需要时请查阅：

• 输出格式 — 任务、列表、评论、文档和页面的输出示例
• 技术说明 — 各功能的 Markdown 处理、@提及解析、文档页面结构、分页
• 测试 — 冒烟测试套件
• Webhook 监视器 — 通过 webhook.site + listen.mjs 实时监控事件
• 任务监视器（轮询） — 通过 watch.mjs 监视单个任务或列表，无需依赖项
• 批量创建任务 — batch-create JSON 计划架构和依赖关系配置
• 团队工作流模式 — 负责人/执行者/QA/文档维护者和阶段门控模式