clickupfy-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ClickUpfy para Desenvolvimento

面向软件开发的ClickUpfy使用指南

Usar o ClickUpfy da Promovaweb ou suas ferramentas MCP para consultar e atualizar trabalho de engenharia. Manter as respostas compactas e preservar a rastreabilidade das mudanças.

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

Documentação contínua

持续文档更新

Quando o trabalho alterar o ClickUpfy, confira

docs/user/

ebook/README.md

docs/user/reading-order.txt

README.md

e os testes documentais. Cada comando novo, flag, argumento, ferramenta MCP, formato de saída, limitação da API ou mudança de comportamento precisa receber explicação, parâmetros, efeitos, limites e cinco exemplos distintos de uso no capítulo de referência adequado.

Inclua também o comando ou a ferramenta no percurso indicado pelo caso de uso, sem substituir a referência detalhada por um link. Atualize a versão do ebook, regenere PDF e EPUB e execute a verificação do ebook quando a documentação mudar. Não afirme que uma interface está documentada apenas porque aparece no texto de ajuda ou em uma tabela de nomes.

当操作变更ClickUpfy内容时，请检查

docs/user/

、

ebook/README.md

、

docs/user/reading-order.txt

、

README.md

以及文档测试。任何新命令、标记、参数、MCP工具、输出格式、API限制或行为变更，都需要在对应参考章节中说明其参数、效果、限制，并提供5个不同的使用示例。

同时，需将命令或工具纳入用例指定的流程中，不要用链接替代详细参考内容。当文档变更时，更新电子书版本，重新生成PDF和EPUB格式，并执行电子书校验。不要仅因界面出现在帮助文本或名称表格中，就断言该界面已完成文档记录。

Escolher a interface

选择操作界面

Usar ferramentas
```
clickupfy_*
```
quando o servidor MCP estiver disponível.
Usar
```
clickupfy
```
pelo terminal quando as ferramentas MCP não estiverem disponíveis.
Executar primeiro
```
clickupfy_mcp_context
```
para conhecer o destino fixado pelo MCP do projeto.
Usar
```
clickupfy account list
```
quando o MCP não estiver disponível.
Informar
```
--account <perfil>
```
ou o argumento
```
account
```
sem trocar o perfil ativo apenas para uma consulta pontual.

Nunca ler, imprimir, comentar ou copiar o campo

apiKey

~/clickupfy/config.json

. Não incluir credenciais em comandos, logs, commits ou respostas.

当MCP服务器可用时，使用
```
clickupfy_*
```
工具。
当MCP工具不可用时，通过终端使用
```
clickupfy
```
。
先执行
```
clickupfy_mcp_context
```
，了解项目MCP设定的目标。
当MCP不可用时，使用
```
clickupfy account list
```
。
仅为单次查询时，可指定
```
--account <perfil>
```
或
```
account
```
参数，但不要切换活跃配置文件。

禁止读取、打印、评论或复制

~/clickupfy/config.json

中的

apiKey

字段。不要在命令、日志、提交记录或回复中包含凭证信息。

Preservar o isolamento dos projetos

保持项目隔离

Tratar o

.mcp.json

da pasta de trabalho como o destino do agente. Ele fixa o perfil, workspace, Space, Folder e a List obrigatória nos argumentos de

clickupfy mcp serve

, sem armazenar a API key. O Sprint Folder só aparece quando o projeto usa Sprints.

Não executar

account use

para alternar entre projetos paralelos. Cada projeto deve manter seu próprio servidor. Conferir

clickupfy_mcp_context

antes da primeira escrita e omitir IDs já fixados. O servidor rejeita perfil ou hierarquia diferentes dos argumentos recebidos na inicialização.

O CLI não lê o

.mcp.json

. Quando o MCP não estiver disponível, informar o perfil e os IDs explicitamente:

bash

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

将工作目录下的

.mcp.json

视为代理目标。它会在

clickupfy mcp serve

的参数中固定配置文件、工作区、Space、Folder和必填List，但不会存储API密钥。只有当项目使用Sprint时，Sprint Folder才会显示。

不要执行

account use

来在并行项目间切换。每个项目应维护自己的服务器。在首次写入前检查

clickupfy_mcp_context

，并省略已固定的ID。服务器会拒绝与初始化时接收的参数不符的配置文件或层级结构。

CLI不会读取

.mcp.json

。当MCP不可用时，需明确指定配置文件和ID：

bash

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

Navegar pelo trabalho

工作内容导航

Quando houver um nome ou trecho da descrição, buscar no workspace:

bash

clickupfy task search --query "<texto>"

No MCP, usar

clickupfy_tasks_search

. Se a busca retornar mais de uma tarefa plausível, mostrar as opções e pedir uma escolha antes de escrever no ClickUp.

Descobrir IDs pela hierarquia quando a busca não for suficiente:

bash

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>

Usar

--space <space-id>

list list

quando a list não pertencer a um folder. Acrescentar

--json

quando os campos compactos não forem suficientes.

No MCP, seguir a mesma ordem com:

```
clickupfy_workspaces_list
```
;
```
clickupfy_spaces_list
```
;
```
clickupfy_folders_list
```
;
```
clickupfy_lists_list
```
;
```
clickupfy_list_get
```
;
```
clickupfy_tasks_list
```
.

Não adivinhar IDs de workspace, space, folder, list, tarefa ou usuário.

当有任务名称或描述片段时，在工作区内搜索：

bash

clickupfy task search --query "<texto>"

在MCP中，使用

clickupfy_tasks_search

。如果搜索返回多个合理的任务选项，需先展示选项并请求选择，再在ClickUp中进行写入操作。

当搜索不足以定位时，通过层级结构查找ID：

bash

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。

Planejar com Sprints

Sprint规划

Aplicar esta seção somente quando

clickupfy_mcp_context

informar um Sprint Folder ou quando o usuário fornecer uma Sprint no escopo.

Localizar o Sprint Folder pela hierarquia e consultar a Sprint ativa antes de alterar o planejamento:

bash

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

No MCP, usar

clickupfy_sprints_list

clickupfy_sprint_current

clickupfy_sprint_get

clickupfy_sprint_tasks

. Uma Sprint é uma List com

start_date

due_date

; não tratar uma List comum do Sprint Folder como Sprint. O CLI não cria Sprints porque a API pública do ClickUp não oferece essa operação.

Associar ou remover uma tarefa somente quando o usuário tiver incluído o planejamento da Sprint no escopo:

bash

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

No MCP, as operações equivalentes são

clickupfy_sprint_add_task

clickupfy_sprint_remove_task

clickupfy_sprint_set_points

. Reler a Sprint e a tarefa depois de cada alteração.

仅当

clickupfy_mcp_context

显示Sprint Folder，或用户在范围内指定Sprint时，才应用本节内容。

在变更规划前，先通过层级结构定位Sprint Folder并查询当前活跃的Sprint：

bash

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。CLI无法创建Sprint，因为ClickUp的公开API不提供此操作。

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

bash

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和任务信息。

Ler antes de alterar

变更前先读取

Obter a tarefa completa com

clickupfy task get <id> --json

clickupfy_task_get

Ler
```
execution.summary
```
e percorrer
```
execution.items
```
na ordem retornada.
Tratar cada
```
key
```
pendente como uma unidade individual de trabalho, preservando
```
parentKey
```
e
```
depth
```
.

Ler os comentários com

clickupfy comment list --task <id> --json

clickupfy_comments_list

Conferir status, descrição, responsáveis, datas, subtarefas e dependências relevantes.
Confirmar que a tarefa e o perfil pertencem ao escopo solicitado.

clickupfy_task_get

já reúne a tarefa principal, subtarefas aninhadas e itens de checklist. Não reconstruir essa hierarquia por nome. Usar a chave

task:<id>

para tarefas e

checklist:<checklist-id>:<item-id>

para checklist items.

Quando o agente precisar da tarefa inteira como um único contexto textual, usar

clickupfy task get <id> --markdown

ou chamar

clickupfy_task_get

com

markdown: true

. Usar a resposta JSON sem essa opção quando a fila estruturada for necessária para selecionar e atualizar itens.

Depois de concluir um checklist item, executar a ação

complete

fornecida no próprio item. Para marcar ou reabrir manualmente:

bash

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

No MCP, usar

clickupfy_checklist_item_set

. A ferramenta relê a tarefa depois da escrita e só retorna o item quando

done

corresponde ao estado solicitado.

Para criar checklists e seus itens:

bash

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

No MCP, usar

clickupfy_checklist_create

clickupfy_checklist_item_create

. Manter cada item aberto durante a criação.

使用

clickupfy task get <id> --json

或

clickupfy_task_get

获取完整任务信息。

读取
```
execution.summary
```
并按返回顺序遍历
```
execution.items
```
。
将每个待处理的
```
key
```
视为独立工作单元，保留
```
parentKey
```
和
```
depth
```
。

使用

clickupfy comment list --task <id> --json

或

clickupfy_comments_list

读取评论。

检查相关的状态、描述、负责人、日期、子任务和依赖关系。
确认任务和配置文件属于请求的范围。

clickupfy_task_get

已整合主任务、嵌套子任务和检查项。不要通过名称重建此层级结构。使用

task:<id>

作为任务的标识，

checklist:<checklist-id>:<item-id>

作为检查项的标识。

当代理需要将完整任务作为单一文本上下文时，使用

clickupfy task get <id> --markdown

或调用带有

markdown: true

参数的

clickupfy_task_get

。当需要结构化队列来选择和更新项目时，使用不带此选项的JSON响应。

完成检查项后，执行该项目提供的

complete

操作。如需手动标记完成或重新打开：

bash

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

状态与请求状态匹配时才返回该项目。

如需创建检查清单及其项目：

bash

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

在MCP中，使用

clickupfy_checklist_create

和

clickupfy_checklist_item_create

。创建时保持每个项目为打开状态。

Atualizar tarefas

更新任务

Usar apenas os campos autorizados pelo pedido:

bash

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>"

No MCP, usar

clickupfy_task_create

clickupfy_task_update

clickupfy_comment_create

. Usar

markdownContent

parent

startDate

dueDate

para os campos equivalentes. Status são nomes configurados pela List; ler

clickupfy_list_get

e usar a grafia real.

Antes de

task delete

clickupfy_task_delete

, obter autorização explícita e confirmar o ID. A ferramenta MCP exige

confirm: true

; o CLI exige

--yes

仅使用请求中授权的字段：

bash

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

参数。

Registrar tempo

记录工时

Consultar primeiro se já existe um time entry:

bash

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

Usar

clickupfy_time_current

clickupfy_time_start

clickupfy_time_stop

no MCP. Não iniciar outro time entry quando houver um em execução sem confirmar o que deve acontecer com o registro atual. Essa conferência é obrigatória quando processos paralelos usam o mesmo perfil e workspace.

先查询是否已有工时记录：

bash

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

在MCP中，使用

clickupfy_time_current

、

clickupfy_time_start

和

clickupfy_time_stop

。当已有正在进行的工时记录时，未确认当前记录的处理方式前，不要启动新的工时记录。当并行流程使用同一配置文件和工作区时，此检查是强制性的。

Validar mudanças

验证变更

Depois de cada escrita:

Ler novamente a tarefa ou o recurso alterado.
Comparar o valor persistido com o valor solicitado.
Informar o ID, a mudança confirmada e qualquer pendência real.
Nunca declarar sucesso usando apenas a ausência de erro do comando.

每次写入操作后：

重新读取已变更的任务或资源。
比较持久化的值与请求的值。
告知ID、已确认的变更以及任何实际存在的待处理项。
不要仅通过命令无错误就声明操作成功。