clickupfy-dev

面向开发的 ClickUpfy

使用 Promovaweb 的 ClickUpfy 或其 MCP 工具查询和更新工程工作。保持回复简洁，并保留变更的可追溯性。

持续文档维护

当工作会改变 ClickUpfy 时，请检查 docs/user/、ebook/README.md、docs/user/reading-order.txt、README.md 和文档测试。每个新命令、标志、参数、MCP 工具、输出格式、API 限制或行为变更，都需要在适当的参考章节中说明其参数、效果、限制，并提供五个不同的使用示例。

还要根据使用场景将命令或工具加入相应的操作流程，不要用链接替代详细参考。文档发生变更时，更新 ebook 版本、重新生成 PDF 和 EPUB，并运行 ebook 检查。不要仅因为某个接口出现在帮助文本或名称表中，就声称它已有文档说明。

选择接口

1. MCP 服务可用时，使用 clickupfy_* 工具。
2. MCP 工具不可用时，通过终端使用 clickupfy。
3. 先运行 clickupfy_mcp_context，了解项目 MCP 固定的目标位置。
4. MCP 不可用时，使用 clickupfy account list。
5. 对于单次查询，传入 --account <perfil> 或 account 参数，不要仅为此切换活动配置。

绝不读取、打印、评论或复制 ~/clickupfy/config.json 中的 apiKey 字段。不要在命令、日志、提交或回复中包含凭据。

保持项目隔离

将工作目录中的 .mcp.json 视为 Agent 的目标位置。它会在 clickupfy mcp serve 的参数中固定配置、workspace、Space、Folder 和必填 List，但不会存储 API key。仅当项目使用 Sprints 时才会出现 Sprint Folder。

不要使用 account use 在并行项目之间切换。每个项目都应保留自己的服务。在首次写入之前检查 clickupfy_mcp_context，并省略已固定的 ID。服务会拒绝与启动参数中的配置或层级不同的请求。

CLI 不会读取 .mcp.json。MCP 不可用时，请明确传入配置和 ID：

clickupfy --account <perfil> task list --list <list-id>

浏览工作项

有名称或描述片段时，在 workspace 中搜索：

clickupfy task search --query "<texto>"

使用 MCP 时，调用 clickupfy_tasks_search。如果搜索返回多个可能匹配的任务，请展示选项，并在写入 ClickUp 之前请用户选择。

搜索结果不足时，按层级查找 ID：

clickupfy workspace list
clickupfy space list
clickupfy folder list --space <space-id>
clickupfy list list --folder <folder-id>
clickupfy list get <list-id>
clickupfy task list --list <list-id>

如果 list 不属于某个 folder，在 list list 中使用 --space <space-id>。紧凑字段不足以满足需求时，添加 --json。

使用 MCP 时，按相同顺序调用：

• clickupfy_workspaces_list；
• clickupfy_spaces_list；
• clickupfy_folders_list；
• clickupfy_lists_list；
• clickupfy_list_get；
• clickupfy_tasks_list。

不要猜测 workspace、space、folder、list、任务或用户的 ID。

使用 Sprints 进行规划

仅当 clickupfy_mcp_context 提供 Sprint Folder，或用户明确指定 Sprint 范围时，才应用本节。

按层级找到 Sprint Folder，并在更改计划之前查询当前 Sprint：

clickupfy sprint list --folder <sprint-folder-id>
clickupfy sprint current --folder <sprint-folder-id>
clickupfy sprint get <sprint-id>
clickupfy sprint tasks <sprint-id> --open-only

使用 MCP 时，调用 clickupfy_sprints_list、clickupfy_sprint_current、clickupfy_sprint_get 和 clickupfy_sprint_tasks。Sprint 是带有 start_date 和 due_date 的 List；不要把 Sprint Folder 中的普通 List 当作 Sprint。由于 ClickUp 公共 API 不提供此操作，CLI 不会创建 Sprints。

仅当用户将 Sprint 计划纳入范围时，才关联或移除任务：

clickupfy sprint add-task <sprint-id> <task-id>
clickupfy sprint remove-task <sprint-id> <task-id>
clickupfy sprint set-points <task-id> <points>

使用 MCP 时，对应的操作是 clickupfy_sprint_add_task、clickupfy_sprint_remove_task 和 clickupfy_sprint_set_points。每次变更后，重新读取 Sprint 和任务。

修改前先阅读

1. 使用 clickupfy task get <id> --json 或 clickupfy_task_get 获取完整任务。
2. 阅读 execution.summary，并按返回顺序遍历 execution.items。
3. 将每个待处理的 key 视为独立工作单元， 保留 parentKey 和 depth。
4. 使用 clickupfy comment list --task <id> --json 或 clickupfy_comments_list 阅读评论。
5. 核对相关的状态、描述、负责人、日期、子任务和依赖项。
6. 确认任务和配置文件属于请求范围。

clickupfy_task_get 已汇总主任务、嵌套子任务和检查清单项目。不要按名称 重建此层级。任务使用键 task:<id>，检查清单项目使用 checklist:<checklist-id>:<item-id>。

当 Agent 需要将整个任务作为单一文本上下文时，使用 clickupfy task get <id> --markdown，或调用 clickupfy_task_get 并设置 markdown: true。需要结构化队列来选择和更新项目时，使用未启用此选项的 JSON 响应。

完成检查清单项目后，执行该项目本身提供的 complete 操作。要手动标记完成或重新打开：

clickupfy checklist set <task-id> <checklist-id> <item-id> --resolved
clickupfy checklist set <task-id> <checklist-id> <item-id> --open

在 MCP 中，使用 clickupfy_checklist_item_set。该工具会在写入后重新读取任务，并且只有当 done 与请求的状态一致时才会返回该项目。

要创建检查清单及其项目：

clickupfy checklist create <task-id> --name "Testes"
clickupfy checklist item-create <checklist-id> --name "<teste>"

在 MCP 中，使用 clickupfy_checklist_create 和 clickupfy_checklist_item_create。创建期间保持每个项目处于未完成状态。

更新任务

仅使用请求授权的字段：

clickupfy task create \
  --list <list-id> \
  --name "<nome>" \
  --markdown-content "<markdown>" \
  --parent "<task-id>" \
  --start-date <AAAA-MM-DD> \
  --due-date <AAAA-MM-DD>

clickupfy task update <task-id> --status "<status exato>"
clickupfy task update <task-id> --start-date <AAAA-MM-DD>
clickupfy task update <task-id> --priority 2
clickupfy task update <task-id> --points 5
clickupfy comment create --task <task-id> --text "<progresso>"

在 MCP 中，使用 clickupfy_task_create、clickupfy_task_update 和 clickupfy_comment_create。对应字段使用 markdownContent、parent、startDate 和 dueDate。状态是由 List 配置的名称；读取 clickupfy_list_get，并使用实际拼写。

在执行 task delete 或 clickupfy_task_delete 之前，获取明确授权并确认 ID。MCP 工具要求 confirm: true；CLI 要求 --yes。

记录时间

先检查是否已有时间记录：

clickupfy time current
clickupfy time start --task <task-id> --description "<atividade>"
clickupfy time stop

在 MCP 中使用 clickupfy_time_current、clickupfy_time_start 和 clickupfy_time_stop。 如果已有正在运行的时间记录，在确认当前记录应如何处理之前，不要启动另一条时间记录。 当并行进程使用相同的配置文件和工作区时，此检查为必需步骤。

验证更改

每次写入后：

1. 重新读取任务或已更改的资源。
2. 将持久化的值与请求的值进行比较。
3. 报告 ID、已确认的更改以及任何实际待处理事项。
4. 绝不能仅凭命令未报错就宣称成功。