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.mjs、node watch.mjs、node listen.mjs三个入口与 ClickUp 深度集成,实现「写代码时不离开终端、任务状态一变自动唤醒 Agent」的闭环开发模式。
一、技能包整体构成
ClickUp 技能包位于仓库的 .claude/skills/clickup 目录,由三部分组成:
| 组成 | 文件 | 作用 |
|---|---|---|
| 入口说明 | SKILL.md | 技能的前置说明:安装依赖、配置账号、全部命令速查 |
| 深度参考 | reference.md | 本文主体:输出格式样例、技术要点、测试、监控、批量建任务、团队工作流 |
| 实现源码 | query.mjs、listen.mjs、watch.mjs、api/*.mjs、lib/*.mjs、test/smoke-test.mjs | CLI 入口与底层 API 封装 |
依赖极轻量,package.json 中仅声明了两个运行时依赖:remark-parse与unified(版本 11.x),用于解析 Markdown。API 层则直接使用 Node.js 内置的fetch,无需额外 HTTP 库。
二、安装与账号配置
2.1 安装依赖(一次性)
cd .claude/skills/clickup && npm install这一步必须执行。lib/markdown.mjs在启动时通过lib/format.mjs被query.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_TOKEN→apiToken、CLICKUP_TEAM_ID→teamId等 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>、me、create、my-tasks、search(需--list/--folder/--me/--assignee/--status/--all之一限定范围)、find-list、assign、due、priority、subtask、move、link、checklist、delete-comment、watch/unwatch、tag/remove-tag、description、start、schedule、rename、depends/blocks、task-link、update-comment、resolve-comment、archive/unarchive、claim(写入 Session ID 自定义字段实现可恢复性)。
列表命令:list、create-list、update-list、delete-list、lists、space-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 Details(get):
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 List(tasks/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)Comments(comments):
[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 Details(doc):
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 Content(page):
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 版本 | 内容格式 |
|---|---|---|
| 评论 Comments | v2 | 专有 JSON 数组(需经markdownToClickUp()转换) |
| 任务描述 Task descriptions | v2 | 原生 Markdown(markdown_description字段) |
| 文档/页面 Docs/Pages | v3 | 原生 Markdown(无需转换) |
Docs API(v3)直接收发 Markdown,零转换成本;而任务评论使用的是专有 JSON 数组格式,必须依赖 lib/markdown.mjs 的转换工具。底层由remark-parse+unified解析 Markdown 语法树后重组为 ClickUp 的富文本结构。
5.2 @Mention 两阶段解析
lib/mentions.mjs 实现了 @Mention 的完整流水线:
- 阶段一(显式):用正则
/@\[([^\]]+)\]/g提取@[identifier]模式,通过模糊匹配解析用户; - 阶段二(裸提及):检测剩余文本中的
@Name模式(/@(?!\[)\w/),与工作区成员用户名匹配; - 转换:将 Markdown 转为 ClickUp 的 JSON 数组格式(
markdownToClickUp()); - 注入:把 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.mjs的fetchAllPages(),通过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/cli(whcli)做实时转发: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 --allapi/webhooks.mjs 的createWebhook()支持按taskId、listId、folderId、spaceId四种作用域订阅,未指定作用域则订阅工作区全部事件;本地 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 wait7.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 --all7.6 默认订阅事件
| 命令 | 默认事件 |
|---|---|
| watch-task | taskStatusUpdated, taskCommentPosted, taskUpdated, taskAssigneeUpdated, taskDueDateUpdated |
| watch-list | taskCreated, taskStatusUpdated, taskCommentPosted, taskUpdated, taskDeleted |
| watch-space | taskCreated, 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 可用事件类型
任务类:taskCreated、taskUpdated、taskDeleted、taskPriorityUpdated、taskStatusUpdated、taskAssigneeUpdated、taskDueDateUpdated、taskTagUpdated、taskMoved、taskCommentPosted、taskCommentUpdated、taskTimeEstimateUpdated、taskTimeTrackedUpdated、taskAttachmentUploaded、taskCustomFieldUpdated。
列表/文件夹/空间类:listCreated、listUpdated、listDeleted、folderCreated、folderUpdated、folderDeleted、spaceCreated、spaceUpdated、spaceDeleted。
八、轮询式任务监视器 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 justin8.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 --json9.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 计划字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
ref | string | 本地引用 ID,用于在任务间接线依赖 |
name | string | 任务标题(必填) |
description | string | Markdown 描述 |
assignee | string | 姓名、邮箱或用户 ID |
priority | string | urgent, high, normal, low, none |
status | string | 状态名(必须匹配列表的可用状态) |
dueDate | string | 绝对日期或相对日期(+3d, +1w, tomorrow) |
startDate | string | 与 dueDate 格式相同 |
tags | string[] | 要应用的标签名 |
listId | string | 为本任务覆盖默认 listId |
dependsOn | string[] | 必须先完成的任务的 ref |
blocks | string[] | 本任务阻塞的任务的 ref |
subtasks | object[] | { name, description, assignee, status }数组 |
9.4 依赖如何工作
用ref作为本地标识,再在dependsOn或blocks中引用:
{ "tasks": [ { "ref": "a", "name": "Task A", "blocks": ["b"] }, { "ref": "b", "name": "Task B", "dependsOn": ["a"] } ] }blocks与dependsOn创建的是同一种 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-123或DEV-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-doc、create-page、edit-page、comment、description、create-list、update-list; - 任务开工即 claim:
claim会把当前会话 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),仅供参考