Back to Details

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

选择操作界面

  1. Usar ferramentas 
    clickupfy_*
    quando o servidor MCP estiver disponível.
  2. Usar 
    clickupfy
    pelo terminal quando as ferramentas MCP não estiverem disponíveis.
  3. Executar primeiro 
    clickupfy_mcp_context
    para conhecer o destino fixado pelo MCP do projeto.
  4. Usar 
    clickupfy account list
    quando o MCP não estiver disponível.
  5. 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
de 
~/clickupfy/config.json
. Não incluir credenciais em comandos, logs, commits ou respostas.
  1. 当MCP服务器可用时，使用
    clickupfy_*
    工具。
  2. 当MCP工具不可用时，通过终端使用
    clickupfy
    。
  3. 先执行
    clickupfy_mcp_context
    ，了解项目MCP设定的目标。
  4. 当MCP不可用时，使用
    clickupfy account list
    。
  5. 仅为单次查询时，可指定
    --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>
em 
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
e 
clickupfy_sprint_tasks
. Uma Sprint é uma List com 
start_date
e 
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
e 
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

变更前先读取

  1. Obter a tarefa completa com 
    clickupfy task get <id> --json
    ou 
    clickupfy_task_get
    .
  2. Ler 
    execution.summary
    e percorrer 
    execution.items
    na ordem retornada.
  3. Tratar cada 
    key
    pendente como uma unidade individual de trabalho, preservando 
    parentKey
    e 
    depth
    .
  4. Ler os comentários com 
    clickupfy comment list --task <id> --json
    ou 
    clickupfy_comments_list
    .
  5. Conferir status, descrição, responsáveis, datas, subtarefas e dependências relevantes.
  6. 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
e 
clickupfy_checklist_item_create
. Manter cada item aberto durante a criação.
  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>
作为检查项的标识。
当代理需要将完整任务作为单一文本上下文时，使用
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
e 
clickupfy_comment_create
. Usar 
markdownContent
, 
parent
, 
startDate
e 
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
ou 
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
e 
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:
  1. Ler novamente a tarefa ou o recurso alterado.
  2. Comparar o valor persistido com o valor solicitado.
  3. Informar o ID, a mudança confirmada e qualquer pendência real.
  4. Nunca declarar sucesso usando apenas a ausência de erro do comando.
每次写入操作后：
  1. 重新读取已变更的任务或资源。
  2. 比较持久化的值与请求的值。
  3. 告知ID、已确认的变更以及任何实际存在的待处理项。
  4. 不要仅通过命令无错误就声明操作成功。