civitai 仓库 ClickUp 自动化技能实战:CLI 任务管理、批量建任务与事件监控参考手册
2026/9/17 3:26:00 网站建设 项目流程

civitai 仓库 ClickUp 自动化技能实战:CLI 任务管理、批量建任务与事件监控参考手册

【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai

导读

本文围绕 civitai 仓库中.claude/skills/clickup技能包展开,系统讲解其核心参考文档 reference.md 与 SKILL.md 中定义的 ClickUp 自动化能力:任务/评论/文档的查询与操作、@Mention 两阶段解析、分页与限流策略、Webhook 实时事件监控、轮询式任务监视器、批量建任务以及五种团队协作工作流。读完本文,你将掌握如何让 AI Agent 通过node query.mjsnode watch.mjsnode listen.mjs三个入口与 ClickUp 深度集成,实现「写代码时不离开终端、任务状态一变自动唤醒 Agent」的闭环开发模式。

一、技能包整体构成

ClickUp 技能包位于仓库的 .claude/skills/clickup 目录,由三部分组成:

组成文件作用
入口说明SKILL.md技能的前置说明:安装依赖、配置账号、全部命令速查
深度参考reference.md本文主体:输出格式样例、技术要点、测试、监控、批量建任务、团队工作流
实现源码query.mjslisten.mjswatch.mjsapi/*.mjslib/*.mjstest/smoke-test.mjsCLI 入口与底层 API 封装

依赖极轻量,package.json 中仅声明了两个运行时依赖:remark-parseunified(版本 11.x),用于解析 Markdown。API 层则直接使用 Node.js 内置的fetch,无需额外 HTTP 库。

二、安装与账号配置

2.1 安装依赖(一次性)

cd .claude/skills/clickup && npm install

这一步必须执行lib/markdown.mjs在启动时通过lib/format.mjsquery.mjs加载——如果未安装依赖,每一条命令(不只是评论命令)都会以ERR_MODULE_NOT_FOUND退出。

2.2 配置 accounts.json

在技能目录下创建accounts.json,写入 API Token(在 ClickUp 的 Settings > Apps > API Token 生成,通常以pk_开头):

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

也可以直接用 CLI 添加账号:

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

从源码看,lib/accounts.mjs 的saveAccountConfig()在写入时会尝试将文件权限收紧为0o600,以保护凭证。Team ID、User ID 等字段会在首次使用时自动探测并缓存回accounts.json

从 .env 迁移:若存在旧的.env文件,migrateFromEnv()会在首次运行时自动将其迁移为accounts.json格式(CLICKUP_API_TOKENapiTokenCLICKUP_TEAM_IDteamId等 8 个字段的映射定义在ENV_KEY_MAP中)。原.env会被保留,确认无误后再手动删除。

2.3 默认列表与多账号

在账号内设置defaultListId后,创建任务时可以省略列表 ID:

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

多账号场景下,每个账号只需apiToken必填,其余自动探测缓存:

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

任何命令都可加--account <name>指定账号:

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

账号管理命令:accounts(列出全部)、switch-account <name>(切换默认)、add-account <name> --token pk_...(添加)、remove-account <name>(移除)。api/client.mjs 的initClient(accountId)负责按账号加载凭证,并回填到process.env中以兼容仍读取环境变量的旧模块。

三、命令总览

统一入口为node query.mjs <command> [options],支持任务、列表、文档、附件四类操作:

任务命令get(查详情)、comments(列评论,--threads内联展开回复)、thread(查看评论线程)、reply(在线程内回复)、comment(发评论,支持 Markdown)、status(改状态/列状态)、tasks <list_id>mecreatemy-taskssearch(需--list/--folder/--me/--assignee/--status/--all之一限定范围)、find-listassigndueprioritysubtaskmovelinkchecklistdelete-commentwatch/unwatchtag/remove-tagdescriptionstartschedulerenamedepends/blockstask-linkupdate-commentresolve-commentarchive/unarchiveclaim(写入 Session ID 自定义字段实现可恢复性)。

列表命令listcreate-listupdate-listdelete-listlistsspace-lists

文档命令docs ["query"]doc <doc_id>create-doc "title"(用--content填充首屏)、page <doc_id> <page_id>create-page <doc_id> "title"--parent建子页)、edit-page

附件命令attach <url|id> --attach <path>(可重复)、fetch-image <url>(下载到本地临时目录,--output自定义路径)。

通用选项--json(原始 JSON 输出)、--threads/-t--subtasks--content/-c(短文本)、--file/-f(长内容推荐)、--cleanup(成功后删除临时文件)、--name/-n--parent/-p--space/-s--assignee/-a--due/-d--description--attach--output--account

search有一个值得注意的设计:ClickUp v2 API 没有跨任务的原生文本搜索,所以search必须带范围参数(--list--folder--me--assignee--status--all),否则直接报错退出而不是默默打爆 API。--all是全工作区扫描,会拉取每个任务,仅在必要时使用。

四、输出格式参考(Output Format)

reference.md 定义了各命令的稳定输出形状,方便 Agent 解析:

Task Detailsget):

Task: Implement user authentication ID: 86a1b2c3d Status: In Progress Priority: High Assignees: John Doe, Jane Smith Watchers: 2 Due: Jan 15, 2024 Start: Jan 10, 2024 Time Estimate: 4h Created: Jan 10, 2024 URL: https://app.clickup.com/t/86a1b2c3d List: Sprint Backlog Folder: Development Space: 20128955 Description: Add OAuth2 authentication with Google and GitHub providers...

Task Listtasks/search):

[to do] Fix login bug ID: 868h2cxat | Priority: high | Assignees: John Doe https://app.clickup.com/t/868h2cxat [in progress] Update API docs ID: 868g7c75u | Priority: None | Assignees: Jane Smith https://app.clickup.com/t/868g7c75u Total: 2 task(s)

Commentscomments):

[2024-01-12 14:30] John Doe: Started working on this. Will push initial commit today. [2024-01-12 16:45] Jane Smith: @John looks good! Let me know when ready for review.

Doc Detailsdoc):

Doc: API Documentation ID: abc123def Created: Jan 10, 2024, 09:30 AM Updated: Jan 15, 2024, 02:45 PM Creator: John Doe Workspace: 12345678 Pages: Introduction ID: page001 Getting Started ID: page002 API Reference ID: page003 Total: 3 page(s)

Page Contentpage):

Page: Getting Started ID: page002 Created: Jan 10, 2024, 10:00 AM Updated: Jan 14, 2024, 03:30 PM Content: --- # Getting Started Welcome to the API documentation. ## Prerequisites - Node.js 18+ - An API key ---

这些稳定格式正是 Agent 能自动解析、无需额外get请求即可行动的基础。

五、技术要点(Technical Notes)

5.1 Markdown 处理:不同功能、不同格式

ClickUp 对不同功能使用不同的内容格式,必须区分对待:

功能API 版本内容格式
评论 Commentsv2专有 JSON 数组(需经markdownToClickUp()转换)
任务描述 Task descriptionsv2原生 Markdown(markdown_description字段)
文档/页面 Docs/Pagesv3原生 Markdown(无需转换)

Docs API(v3)直接收发 Markdown,零转换成本;而任务评论使用的是专有 JSON 数组格式,必须依赖 lib/markdown.mjs 的转换工具。底层由remark-parse+unified解析 Markdown 语法树后重组为 ClickUp 的富文本结构。

5.2 @Mention 两阶段解析

lib/mentions.mjs 实现了 @Mention 的完整流水线:

  1. 阶段一(显式):用正则/@\[([^\]]+)\]/g提取@[identifier]模式,通过模糊匹配解析用户;
  2. 阶段二(裸提及):检测剩余文本中的@Name模式(/@(?!\[)\w/),与工作区成员用户名匹配;
  3. 转换:将 Markdown 转为 ClickUp 的 JSON 数组格式(markdownToClickUp());
  4. 注入:把 mention 属性写进对应文本节点——{"text": "@DisplayName", "attributes": {"mention": userId}},由injectMentions()将含 @DisplayName 的文本项按位置切分、插入 mention 属性。

显式@[identifier]支持的三种匹配方式:

  • 部分姓名@[justin]→ 模糊匹配 "Justin Maier"
  • 邮箱@[jane@co.com]→ 按邮箱匹配
  • 用户 ID@[10620972]→ 直接按数字 ID 匹配

@Name自动检测规则:

  • 对工作区成员做大小写不敏感匹配,支持@First Last@First
  • 先尝试完整用户名,再退化为仅名字(detectBareMentions()对每个成员构造两个候选模式,并优先保留更长匹配)
  • 未匹配的裸提及保留为纯文本——不报错、不浪费 API 调用
  • 它是「Agent 忘记写方括号」时的安全网

错误语义对比:显式@[identifier]匹配失败会抛错;裸提及匹配失败则静默通过textToCommentArray()串起整个过程:先resolveMentions()归一化所有提及,再markdownToClickUp()转换,最后injectMentions()注入属性。

5.3 Doc 页面结构:create-doc 与 create-page 的区别

通过 API 创建 Doc 时,ClickUp 会自动生成一个空的首个页面,这带来三个命令的定位差异:

  • create-doc:创建 Doc 并自动生成第一个页面,用--content填充该页;
  • create-page:为已有 Doc追加额外页面(第二页、第三页……);
  • edit-page:修改已有页面的内容。

最佳实践:给新 Doc 添加内容时,用create-doc "Title" --content "..."直接填充首屏,而不要「先建 Doc 再 create-page」——后者会导致第一个页面永远是空的。

5.4 分页与限流

所有列表类端点都已自动分页拉取全部结果:

  • 任务列表:基于页(每页 100 条),见api/client.mjsfetchAllPages(),通过last_page判断终止;
  • 评论:基于游标(每页 25 条);
  • Docs 搜索:基于游标,返回{ docs, nextCursor }

限流自动处理:fetchWithRetry()在遇到 HTTP 429 时最多重试 2 次,优先读取X-RateLimit-Reset响应头计算等待时间(默认兜底等待 60 秒),并对每次请求设置 30 秒超时(REQUEST_TIMEOUT_MS = 30000)。注意分页循环本身是在单次「外层调用」内完成的,而限流重试针对的是每次 HTTP 请求。

六、测试:smoke-test.mjs

冒烟测试直接针对 ClickUp 生产 API 验证所有命令:

# 完整测试套件(创建测试资源、校验、清理) node test/smoke-test.mjs # 只读测试(安全,无写入) node test/smoke-test.mjs --readonly # 详细输出(失败时展示细节) node test/smoke-test.mjs --verbose

新增功能时,必须在 test/smoke-test.mjs 中补充对应测试。

七、Webhook 事件监控(实时通道)

Webhook 监控用于订阅 ClickUp 任务、列表或空间的实时事件,借助 webhook.site 作为公共中继——无需任何额外基础设施

7.1 配置

accounts.json中加入 webhook.site token:

{ "webhookSiteToken": "your-uuid-from-webhook.site", "defaultAccount": "bot", "accounts": { ... } }

需要@webhooksite/cliwhcli)做实时转发:npm install -g @webhooksite/cli

7.2 命令

# 监控单个任务(或多个任务) node query.mjs watch-task <task_id> node query.mjs watch-task <id1>,<id2>,<id3> node query.mjs watch-task <task_id> --events taskStatusUpdated,taskCommentPosted # 监控列表或空间 node query.mjs watch-list <list_id> node query.mjs watch-space <space_id> # 列出本地注册的活动 watcher node query.mjs watchers # 列出工作区全部 webhook(来自 ClickUp API) node query.mjs webhooks # 移除指定 watcher node query.mjs unwatch-webhook <webhook_id> # 移除全部 watcher node query.mjs unwatch-webhook --all

api/webhooks.mjs 的createWebhook()支持按taskIdlistIdfolderIdspaceId四种作用域订阅,未指定作用域则订阅工作区全部事件;本地 watcher 注册表持久化在watchers.json

7.3 监听器(Listener)

监听器经 webhook.site 转发接收事件,作为后台任务运行:

# 等待模式(默认):收到一个事件、打印、退出 node listen.mjs --timeout 600 # 服务器模式:持续运行、记录全部事件 node listen.mjs --mode server # 组合选项 node listen.mjs --port 3458 --timeout 300 --mode wait

7.4 监听器过滤器

过滤器让监听器只在相关变化发生时唤醒 Agent:

# 仅当任务进入 "qa review" 状态时投递 node listen.mjs --filter-status "qa review" # 只投递评论事件(忽略状态变化等) node listen.mjs --filter-event taskCommentPosted # 只投递指定任务的事件 node listen.mjs --filter-task 868abc123 # 组合过滤 node listen.mjs --filter-status "complete,qa review" --filter-event taskStatusUpdated # 多值用逗号分隔 node listen.mjs --filter-status "in review,ready for qa"

过滤行为要点:

  • --filter-status:针对taskStatusUpdated事件,仅当新状态匹配才投递;非状态事件不受影响;
  • --filter-event:只投递指定事件类型,逗号分隔多个;
  • --filter-task:只投递指定任务 ID 的事件,逗号分隔多个;
  • 被过滤的事件仍会写入webhooks.jsonl并推进游标,只是不触发投递;
  • 对 ClickUp 始终返回 200 OK(即使被过滤),保证 webhook 健康存活。

7.5 Agent 工作流

# 1. 建立 watcher node query.mjs watch-task 868abc123 --events taskStatusUpdated,taskCommentPosted # 2. 以后台任务启动监听器(run_in_background=true) node listen.mjs --timeout 600 # 3. Agent 继续其他工作…… # 4. 事件到达时,后台任务带着事件 JSON 退出 # Agent 读取 webhook-latest.json 或解析 stdout # 5. 若预期还有更多事件,重启监听器 node listen.mjs --timeout 600 # 6. 完成后清理 node query.mjs unwatch-webhook --all

7.6 默认订阅事件

命令默认事件
watch-tasktaskStatusUpdated, taskCommentPosted, taskUpdated, taskAssigneeUpdated, taskDueDateUpdated
watch-listtaskCreated, taskStatusUpdated, taskCommentPosted, taskUpdated, taskDeleted
watch-spacetaskCreated, taskStatusUpdated, taskCommentPosted, taskUpdated, taskDeleted, listCreated, listUpdated, listDeleted

--events evt1,evt2,...覆盖默认值。

7.7 事件落盘与补漏

事件保存到三个文件:

  • webhook-latest.json— 最近一次事件(美化打印)
  • webhooks.jsonl— 全部事件的追加式日志
  • last-seen.txt— 用于追赶的时间戳游标

监听器启动时会通过 webhook.site API 检查遗漏事件,因此监听器重启间隙产生的事件会自动补齐,不会丢。

7.8 可用事件类型

任务类:taskCreatedtaskUpdatedtaskDeletedtaskPriorityUpdatedtaskStatusUpdatedtaskAssigneeUpdatedtaskDueDateUpdatedtaskTagUpdatedtaskMovedtaskCommentPostedtaskCommentUpdatedtaskTimeEstimateUpdatedtaskTimeTrackedUpdatedtaskAttachmentUploadedtaskCustomFieldUpdated

列表/文件夹/空间类:listCreatedlistUpdatedlistDeletedfolderCreatedfolderUpdatedfolderDeletedspaceCreatedspaceUpdatedspaceDeleted

八、轮询式任务监视器 watch.mjs(默认首选)

watch.mjs 是一个自包含、基于轮询的监视器:对单个任务(或列表中的全部任务)快照基线,按间隔轮询 ClickUp API,一旦检测到被监控的变化就以退出码 0 结束并打印一份简洁的 JSON 变更摘要。用run_in_background=true运行时,父 Agent 会在其退出时收到任务通知。

与 Webhook 方案(watch-task/listen.mjs)最大的区别是:不需要 webhook.site 账号、不需要whcli,任何 API Token 可用之处它都能跑。建议把它作为默认方案;只有需要亚秒级实时性或工作区级事件流时才走 Webhook 通道。

8.1 用法

# 监控单个任务(ID 或 URL),检测状态/评论/负责人变化 node watch.mjs 868kjbyvu node watch.mjs "https://app.clickup.com/t/868kjbyvu" # 监控列表中全部任务(跟踪状态/负责人变化 + 任务创建/删除) node watch.mjs --list 901111220963 # 仅当任务到达这些状态之一时唤醒 node watch.mjs 868kjbyvu --until-status "in progress,complete" # 只监听特定变更类型 node watch.mjs 868kjbyvu --on comments node watch.mjs 868kjbyvu --on status,assignee # 调整轮询节奏与寿命,并把最新变更镜像到状态文件 node watch.mjs 868kjbyvu --timeout 3600 --interval 45 --state-file ./watch-latest.json # 指定账号 node watch.mjs 868kjbyvu --account justin

8.2 全部 Flags

Flag默认值说明
<taskId\|url>位置参数。要监控的任务(ID 或任意任务 URL)。
--list <id\|url>改为监控列表中的全部任务。
--timeout <sec>3600最多监控秒数,超时以timeout结果退出。
--interval <sec>45轮询周期(最小 10,对限流友好)。
--on <types>status,comments,assignee逗号分隔的唤醒变更类型。
--until-status <list>仅当任务到达这些状态之一时唤醒(隐含--on status)。
--account <name>default使用accounts.json中的具名账号。
--state-file <path>可选。把基线与最新变更 JSON 写入该文件(对应 Webhook 方案的webhook-latest.json思路)。

8.3 能检测到什么

  • status— 任务状态变化({from, to});
  • comments— 出现新评论(最新评论 id/计数变化)。仅单任务模式;列表模式跳过逐任务评论拉取,以对 API 保持温和;
  • assignee— 负责人增减;
  • 列表模式额外报告taskCreated/taskDeleted

源码中snapshotTask()把任务规约为用于跨轮询比较的字段集合:assignees 按用户 ID 排序后比较、取最新评论作为评论游标,保证比较稳定可靠。

8.4 退出行为

  • 检测到变化→ 打印{"event":"change", ...}并退出0
  • 超时→ 打印{"event":"timeout", ...}并退出0
  • 致命配置错误(ID 无效、无认证)→ 打印ERROR:并退出1

轮询过程中的 API/网络/限流错误永远不会让循环崩溃——它们记录到 stderr 并指数退避(上限 60 秒),然后继续轮询。

8.5 Agent 工作流

# 1. 以后台任务启动 watcher(run_in_background=true) node watch.mjs 868kjbyvu --until-status "in review" --timeout 3600 # 2. Agent 继续其他工作…… # 3. 任务进入 "in review" 时,后台任务退出 0,Agent 收到通知。 # 读取打印的 JSON(或 --state-file)即可知道变化内容: # {"event":"change","changes":[{"type":"status","from":"in progress","to":"in review"}], ...} # 4. 处理完后,若预期还有变化,重新武装 watcher: node watch.mjs 868kjbyvu --until-status "complete" --timeout 3600

变更 JSON 中携带任务 URL、最新快照(状态、负责人、评论数)与elapsedSec,Agent 无需额外get即可行动。

九、批量建任务 batch-create(项目初始化)

用一个 JSON 文件即可创建整个项目的任务,支持名称、描述、负责人、优先级、子任务、标签、日期与任务间依赖。

9.1 用法

# 从 JSON 计划创建任务 node query.mjs batch-create --file plan.json # 预览而不创建(干跑) node query.mjs batch-create --file plan.json --dry-run # 供程序化使用的 JSON 输出 node query.mjs batch-create --file plan.json --json

9.2 JSON 计划 Schema

{ "listId": "901111220963", "tasks": [ { "ref": "design", "name": "Design system architecture", "description": "Create the high-level architecture document", "assignee": "justin", "priority": "high", "status": "to do", "dueDate": "+7d", "startDate": "today", "tags": ["architecture", "phase-1"], "subtasks": [ { "name": "Draft ERD", "assignee": "mark" }, { "name": "Review ERD", "assignee": "dakota" } ] }, { "ref": "implement", "name": "Implement core modules", "assignee": "mark", "priority": "normal", "dependsOn": ["design"], "subtasks": [ { "name": "Build data layer" }, { "name": "Build API endpoints" }, { "name": "Write unit tests" } ] }, { "ref": "qa", "name": "QA validation", "assignee": "dakota", "dependsOn": ["implement"], "subtasks": [ { "name": "Integration tests" }, { "name": "Performance testing" } ] } ] }

9.3 计划字段说明

字段类型说明
refstring本地引用 ID,用于在任务间接线依赖
namestring任务标题(必填)
descriptionstringMarkdown 描述
assigneestring姓名、邮箱或用户 ID
prioritystringurgent, high, normal, low, none
statusstring状态名(必须匹配列表的可用状态)
dueDatestring绝对日期或相对日期(+3d, +1w, tomorrow)
startDatestring与 dueDate 格式相同
tagsstring[]要应用的标签名
listIdstring为本任务覆盖默认 listId
dependsOnstring[]必须先完成的任务的 ref
blocksstring[]本任务阻塞的任务的 ref
subtasksobject[]{ name, description, assignee, status }数组

9.4 依赖如何工作

ref作为本地标识,再在dependsOnblocks中引用:

{ "tasks": [ { "ref": "a", "name": "Task A", "blocks": ["b"] }, { "ref": "b", "name": "Task B", "dependsOn": ["a"] } ] }

blocksdependsOn创建的是同一种 ClickUp 依赖——按读起来更自然的方式选择即可。执行顺序上,lib/batch-create.mjs 会先创建全部任务,再在第二轮接线依赖(因为依赖双方都需要先存在)。

十、团队工作流模式(Team Workflow Patterns)

模式 1:团队负责人搭建项目

负责人把整个项目计划写成 JSON,然后一次性批量创建:

# 1. 编写计划(或让 Agent 生成) # 2. 一次创建全部任务 node query.mjs batch-create --file project-plan.json # 3. 在列表上建立 watcher node query.mjs watch-list <list_id> --events taskStatusUpdated,taskCommentPosted # 4. 启动监听器监控进度 node listen.mjs --timeout 3600 --mode server

模式 2:工人 Agent 认领并完成任务

# 1. 查看分配给我的任务 node query.mjs my-tasks # 2. 认领任务(写入会话链接,支持后续恢复) node query.mjs claim <task_id> # 3. 移动为进行中 node query.mjs status <task_id> "in progress" # 4. 干活…… # 5. 完成后移入评审并留言 node query.mjs status <task_id> "in review" node query.mjs comment <task_id> "Implementation complete. Ready for review."

模式 3:QA 评审者监听评审状态

# 1. 监听列表的状态变化 node query.mjs watch-list <list_id> --events taskStatusUpdated # 2. 启动只投递 "in review" 状态的监听器 node listen.mjs --filter-status "in review" --timeout 3600 # 3. 任务进入评审时,Agent 被唤醒、读取事件 # 4. 拉取任务、评审,然后批准或打回 node query.mjs get <task_id> node query.mjs comments <task_id> # 若批准: node query.mjs status <task_id> "complete" node query.mjs comment <task_id> "QA approved." # 若需修改: node query.mjs status <task_id> "in progress" node query.mjs comment <task_id> "Needs revision: [details]" # 5. 为下一次评审重启监听器 node listen.mjs --filter-status "in review" --timeout 3600

模式 4:文档维护者在完成时收到通知

# 监控任务完成 node query.mjs watch-list <list_id> --events taskStatusUpdated node listen.mjs --filter-status "complete" --timeout 3600 # 收到通知后更新项目文档 node query.mjs get <task_id> # 读取完成了什么 # 据此更新文档……

模式 5:阶段闸门(Phase Gates)

对设计 → 实现 → QA → 部署这类顺序阶段项目:

{ "listId": "...", "tasks": [ { "ref": "phase1", "name": "Phase 1: Design", "tags": ["phase-gate"] }, { "ref": "phase2", "name": "Phase 2: Implementation", "dependsOn": ["phase1"], "tags": ["phase-gate"] }, { "ref": "phase3", "name": "Phase 3: QA", "dependsOn": ["phase2"], "tags": ["phase-gate"] }, { "ref": "phase4", "name": "Phase 4: Deploy", "dependsOn": ["phase3"], "tags": ["phase-gate"] } ] }

由「看门人」Agent 监听 phase-gate 任务完成事件,触发下一阶段工作。

十一、常用 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-123DEV-123)、直接任务 ID(86a1b2c3d)。

列表https://app.clickup.com/{team_id}/v/li/{list_id}、直接列表 ID。

空间https://app.clickup.com/{team_id}/v/s/{space_id}、直接空间 ID。

文档https://app.clickup.com/{team_id}/v/dc/{doc_id}https://app.clickup.com/{team_id}/docs/{doc_id}、直接 Doc ID。

十二、实用技巧与最佳实践

  • Team ID、User ID 等字段会自动缓存进accounts.json,无需手工维护;
  • 设置defaultListId后创建任务可省略列表 ID;
  • 日期用自然语言:"tomorrow""next friday""+3d"
  • 提交信息中包含任务 ID,便于全程可追溯;
  • 需要脚本化或管道化输出时用--json
  • Doc 内容输入输出均为 Markdown;Docs API 走 v3 端点(基于工作区而非团队);
  • 所有任务/评论查询自动分页,无需手工翻页;限流自动重试退避;
  • 评论线程最佳实践:发表评论前先comments <task> --threads查看既有对话;若上下文引用的是某个评论线程,用reply <comment_id>而不是comment <task>;只有全新话题才用顶层comment。经验法则:你之前发过评论、且有人在其中回复,你的下一条回复应通过reply进入同一线程;
  • 长内容用文件:超过一句话的内容先写入 Markdown 文件,再用--file path.md传入,避免 shell 转义问题;临时内容加--cleanup自动清理。--file适用于create-doccreate-pageedit-pagecommentdescriptioncreate-listupdate-list
  • 任务开工即 claimclaim会把当前会话 ID 写入任务的 "Session ID" 自定义字段(要求列表存在名称含 "Session" 的文本自定义字段),Session ID 的解析顺序为$CLAUDE_SESSION_ID→ 60 秒内最近修改的~/.claude/projects/*/*.jsonl,这样即使后续换了会话也能原地续接工作。

结语

从日常任务查询到项目级批量初始化,再到实时/轮询双通道事件监控,.claude/skills/clickup为 Agent 提供了一套覆盖 ClickUp 全生命周期协作的自动化工具箱。无论是单人快速建任务,还是「负责人建计划 → 工人认领执行 → QA 监听评审 → 文档维护跟进 → 阶段闸门推进」的多人多 Agent 流水线,本文梳理的命令、过滤规则、JSON Schema 与源码级实现细节都可以直接对照 reference.md 和 SKILL.md 上手实践。

【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询