ui-gen-record

O que ui-gen-record faz?

Arquive os metadados de "solicitações de geração de páginas UI" (custo, modelo, número de modificações, artefatos) em uma única tabela do Feishu Bitable.

Cenários de ativação

Essencial: .config.json sempre representa "a tabela atualmente ativa". "Criar / Vincular" apenas troca esse ponteiro, sem afetar os dados das tabelas existentes.

Cenário	O que o usuário diz	Ação
Primeiro uso + apenas "arquivar"	"Arquivar na tabela / Registrar na tabela multidimensional / Registrar esta demanda"	Executar bootstrap.sh para criar uma nova tabela e depois anexar
Primeiro uso + forneceu link da tabela Feishu	"Arquivar nesta tabela https://xxx.feishu.cn/base/..."	Executar link.sh <url> para vincular a tabela existente e depois anexar
Já configurado + apenas "arquivar"	"Arquivar na tabela"	Anexar diretamente na tabela apontada pelo .config.json atual
Já configurado + disse "criar nova"	"Criar uma nova tabela / Quero criar uma nova"	Executar bootstrap.sh --force para criar uma nova e mudar o ponteiro
Já configurado + forneceu novo link	"Mudar para esta tabela https://..."	Executar link.sh --force <url> para mudar para a nova tabela

Somente quando a URL base do Feishu for explicitamente fornecida é que o fluxo de vinculação é executado; caso contrário, o padrão é criar uma nova tabela ou anexar diretamente.

Dependências

• lark-cli (o login lark-cli auth login já foi concluído)
• O usuário operacional já possui uma conta no Feishu e o open_id pode ser obtido via lark-cli auth list

Criar / Vincular tabela: Inicializar .config.json

Existem duas maneiras de apontar o skill para uma tabela do Feishu Bitable, escolha uma:

Modo A: Criar uma nova tabela (recomendado para novos usuários)

bash ~/.cursor/skills/ui-gen-record/scripts/bootstrap.sh
# Se já existir .config.json, para forçar a criação de uma nova e sobrescrever o ponteiro:
bash ~/.cursor/skills/ui-gen-record/scripts/bootstrap.sh --force

Modo B: Vincular a uma tabela existente

Quando o usuário fornecer um link do Feishu Base (ex.: https://xxx.feishu.cn/base/<base_token>?table=<table_id>):

bash ~/.cursor/skills/ui-gen-record/scripts/link.sh <base_url>
# Se já existir .config.json, para mudar para o novo link:
bash ~/.cursor/skills/ui-gen-record/scripts/link.sh --force <base_url>

link.sh irá:

1. Extrair base_token (e opcionalmente table_id / view_id) da URL
2. Escanear a lista de campos através do lark-cli e reverter para obter todos os field_ids pelo nome
3. Verificar se os 10 campos obrigatórios ("Nome da demanda / Data da demanda / Link de pré-visualização / Link do design / Modelo usado / Arquivo / Número de modificações / Consumo de tokens / Custo em dólar / Mês") estão presentes; qualquer ausência resultará em erro e saída
4. Escrever no .config.json, e a partir de então o append.sh adicionará registros automaticamente a esta tabela, sem necessidade de fornecer o link novamente

Nota: Para que link.sh seja bem-sucedido, os nomes dos campos da tabela de destino devem ser exatamente iguais aos definidos neste skill (os tipos também devem coincidir, especialmente Consumo de tokens=number com separador de milhar, Custo em dólar=number moeda USD, Mês=formula). A maneira mais segura é que esta tabela tenha sido criada pelo bootstrap.sh deste skill.

O que bootstrap.sh faz especificamente:

1. Obter o open_id do usuário atual via lark-cli auth list
2. Criar um Base como bot, com a tabela chamada Registros de geração de UI
3. Criar os campos padrão + 3 campos de fórmula auxiliar (veja tabela abaixo)
4. Agrupar a visualização por Mês em ordem decrescente
5. Criar o dashboard Estatísticas em tempo real de geração UI e preencher com 6 blocos (veja abaixo)
6. Adicionar o usuário atual como full_access e transferir o proprietário para ele
7. Escrever base_token / table_id / view_id / dashboard_id / field_ids / owner_open_id no .config.json
8. Exibir no final do stdout dois ajustes manuais únicos (ocultar a coluna "Mês", definir cores do gráfico), que não são suportados pela Open API e exigem que o usuário clique no navegador

A URL do Base criada será exibida no stdout e deve ser reportada ao usuário.

Estrutura da tabela

Campo	Tipo	Descrição
Nome da demanda	text	Nome da página ou breve descrição da demanda
Data da demanda	datetime	YYYY-MM-DD HH:mm:ss, padrão para "hora atual"
Link de pré-visualização	text (url)	Endereço de pré-visualização local, ex.: http://localhost:5173/xxx
Link do design	text (url)	Link do Figma / Motiff / Pencil
Modelo usado	select (com etiqueta de cor)	Opções: Claude Opus 4.7(roxo) / Claude Sonnet 4.6(azul) / GPT-5.4(verde) / Gemini 3 Pro(laranja) / Gemini 3.1 Pro(vermelho), extensível
Arquivo	attachment	Código-fonte .tsx + exportação .zip (múltiplos permitidos)
Número de modificações	text	Todos os pequenos pontos de alteração propostos pelo usuário (incluindo repetições), alinhado à esquerda
Consumo de tokens	number(plain)	precision=0, thousands_separator=true, exibido como 1.000.000; SUM direto no dashboard
Custo em dólar	number(currency)	currency_code=USD, precision=2, exibido como $25,00; SUM direto no dashboard
Mês	formula(text)	TEXT([Data da demanda], "YYYY-MM"), usado para agrupamento na visualização. A API do Bitable agrupa datetime por padrão por dia, este campo de texto é necessário para agrupar por mês

Os parâmetros externos do append.sh permanecem compatíveis: ainda podem ser passados --token-usage "1.000.000" e --usd-cost "$25,00"; o script internamente remove vírgulas / cifrão e grava como número nos campos Consumo de tokens / Custo em dólar.

A visualização padrão agrupa por Mês em ordem decrescente (2026-05 / 2026-04 cada um em seu grupo). Nenhuma coluna precisa ser ocultada.

Dashboard

O bootstrap criará um dashboard chamado Estatísticas em tempo real de geração UI, contendo 6 blocos:

Estatísticas gerais

• Modelo mais usado (gráfico de pizza): contagem pelo campo Modelo usado, ordem decrescente
• Consumo total de tokens / Custo total em dólar (cartão de indicador): SUM(Consumo de tokens) / SUM(Custo em dólar)

Estatísticas mensais

• Modelo mais usado por mês (gráfico de barras empilhadas): x=Mês cor=Modelo usado y=count_all
• Consumo total de tokens por mês (gráfico de barras): x=Mês y=SUM(Consumo de tokens)
• Custo total em dólar por mês (gráfico de barras): x=Mês y=SUM(Custo em dólar)

Após cada execução do append.sh, ao atualizar o dashboard, os novos dados aparecerão.

Ajuste fino de cores dos gráficos (manual, uma única vez)

A Open API do Bitable não expõe a configuração de cores das séries dos gráficos. Para que as cores dos modelos nos gráficos correspondam às etiquetas de cor do seletor na tabela, o usuário precisa ajustar manualmente no navegador uma vez (o ajuste é persistente). O bootstrap exibirá esta tabela de referência ao final:

Modelo	Cor	Aproximação hex
Claude Opus 4.7	Roxo	#B66CFF
Claude Sonnet 4.6	Azul	#5B9FFF
GPT-5.4	Verde	#67D474
Gemini 3 Pro	Laranja	#FF9944
Gemini 3.1 Pro	Vermelho	#FF6B6B

Caminho: Canto superior direito do gráfico Editar → Estilo à direita → Cores do gráfico → Por categoria → Ajustar cada cor → Salvar. Apenas os gráficos "Modelo mais usado" e "Modelo mais usado por mês", que envolvem a dimensão de modelo, precisam ser ajustados.

Uso posterior: Adicionar um registro

Quando o usuário disser "Arquivar na tabela" ou instruções similares:

Etapa 1: Coletar dados

Inferir do contexto da conversa atual ou perguntar ao usuário para obter as seguintes informações; se não estiver claro, permitir string vazia "":

• REQ_NAME: Nome da demanda (obrigatório, geralmente o caminho da página ou nome da página em chinês)
• REQ_DATE: Data da demanda (padrão para hora atual $(date +'%Y-%m-%d %H:%M:%S'); para arquivar arquivos históricos, usar stat -f '%Sm')
• PREVIEW_URL: Link de pré-visualização (geralmente http://localhost:5173/<slug>)
• DESIGN_URL: Link do design (Figma / Motiff / Pencil)
• MODEL: Modelo usado (deve corresponder a uma opção do select; caso contrário, primeiro expandir as opções com lark-cli base +field-update)
• MOD_COUNT: Número de modificações (string inteira)
• TOKEN_USAGE: Consumo de tokens (string com separador de milhar, ex.: 1.000.000)
• USD_COST: Custo em dólar (string começando com $, ex.: $25,00)
• ATTACHMENT_PATHS: Array de caminhos absolutos para anexos locais

Etapa 1.5: Coleta automática de anexos

Os anexos são compostos por duas partes, o agente não precisa perguntar ao usuário, seguindo o fluxo fixo abaixo:

1) Código-fonte (obrigatório)

O código-fonte da página que o usuário já possui. O mais comum é .tsx, mas também pode ser .html ou qualquer arquivo que represente o artefato atual. O caminho é inferido do REQ_NAME ou perguntado diretamente ao usuário.

2) Exportação zip (opcional, incluir se disponível, ignorar se não)

O servidor de desenvolvimento deste projeto possui uma interface POST /__api/export-html (o botão "Exportar" no painel de navegação também a chama). O skill fornece um helper silencioso:

ZIP_PATH="$(bash ~/.cursor/skills/ui-gen-record/scripts/try-export.sh "<pageName>")"
# Descrição:
# - pageName = caminho relativo em src/pages/ sem extensão, ex.: "transicao-tarefa-versao-final" ou "landing/index"
# - Sucesso: ZIP_PATH é /tmp/<basename>.zip
# - Falha (dev server offline / interface 404 / nome de página não existe / resposta não-zip): ZIP_PATH é vazio
# - Em ambos os casos, exit 0, não interrompe o fluxo do agente

Em seguida, montar o argumento --attachment com base no resultado:

ATTACH_ARGS=(--attachment "/caminho/abs/para/source.tsx")
if [[ -n "$ZIP_PATH" ]]; then
  ATTACH_ARGS+=(--attachment "$ZIP_PATH")
fi
bash ~/.cursor/skills/ui-gen-record/scripts/append.sh ... "${ATTACH_ARGS[@]}"

Princípio: Colegas internos (com o servidor de desenvolvimento rodando) incluirão automaticamente o zip; usuários externos (sem servidor de desenvolvimento ou que não são deste projeto) pularão silenciosamente o zip, mantendo apenas o código-fonte e outros arquivos que o usuário já possui. Sob nenhuma circunstância pergunte ao usuário sobre como lidar com o zip.

Etapa 2: Chamar o script append

bash ~/.cursor/skills/ui-gen-record/scripts/append.sh \
  --req-name "<Nome da demanda/página>" \
  --req-date "2026-01-01 12:00:00" \
  --preview-url "http://localhost:5173/<caminho da página>" \
  --design-url "https://<Link do design>" \
  --model "Claude Opus 4.7" \
  --mod-count "10" \
  --token-usage "500.000" \
  --usd-cost "\$12,50" \
  --attachment "/caminho/absoluto/para/export.zip" \
  --attachment "/caminho/absoluto/para/source.tsx"

O script retorna o ID do novo registro e a URL do Base; informe a URL do Base ao usuário.

Regras de estimativa (obrigatório, não permitir vazio)

O agente deve coletar MOD_COUNT / TOKEN_USAGE / USD_COST seguindo estas diretrizes. Mesmo que a transcrição esteja faltando, valores estimados devem ser fornecidos, estes três campos são estritamente proibidos de ficar em branco:

• Número de modificações: A contagem de cada pequena demanda independente e executável proposta pelo usuário nesta conversa, incluindo repetições. A "geração da página" inicial também conta como 1.
  • Se estiver arquivando um arquivo histórico (transcrição não visível), preencher no mínimo com 1
• Consumo de tokens (string com separador de milhar, ex.: 160.000):
  • Quando a sessão atual é visível: estimar com base em "caracteres da sessão + idas e vindas de ferramentas + número de leituras/gravações de arquivos grandes"
  • Apenas arquivando arquivo histórico: inferir a partir do tamanho do arquivo gerado. Valor empírico: cada 1KB de código-fonte ≈ 15K tokens totais (incluindo o contexto do projeto injetado por padrão pelo Cursor)
  • Chinês ≈ 1,3 tokens/char; sessões Opus geralmente estão na faixa de 500 mil a 3 milhões de tokens
• Custo em dólar (prefixo $, ex.: $0,42): Estimar com base nos preços oficiais atuais do modelo
  • Fórmula: custo = tokens_input × taxa_input + tokens_output × taxa_output
  • Proporção típica: input : output ≈ 15 : 1 (para sessões do agente Cursor)

Tabela de preços dos modelos (referência 2026)

Modelo	Input ($/M)	Output ($/M)
Claude Opus 4.7	15	75
Claude Sonnet 4.6	3	15
GPT-5.4	10	30
Gemini 3 Pro / 3.1 Pro	2	12

Valores estimados podem ter desvios; o usuário pode sobrescrever manualmente na tabela após receber a fatura precisa.

Tratamento de erros

• config.json não existe
  • Usuário não forneceu link → Executar bootstrap.sh para criar nova
  • Usuário forneceu link → Executar link.sh <url> para vincular
• link.sh reporta "A tabela não possui os campos obrigatórios" → A tabela de destino não foi criada por este skill, o schema não corresponde. Sugerir ao usuário que adicione manualmente os campos ou use bootstrap.sh para criar uma tabela padronizada.
• base_token invalid → O usuário pode ter excluído a tabela ou não tem permissão; sugerir executar novamente bootstrap ou link para outra tabela.
• OpenAPIUpdateField limitado (limitação de taxa) → Tentar novamente após sleep 2.
• Anexo não encontrado → Verificar se o caminho existe; se for um arquivo com URL-encoded em ~/Downloads, copiar primeiro para /tmp e depois enviar (lark-cli exige caminho relativo).
• Modelo não está nas opções do select → Primeiro confirmar com o usuário se deve adicionar a nova opção; atualizar as opções com lark-cli base +field-update.

Arquivos relacionados

• scripts/bootstrap.sh — Criar uma nova tabela padronizada e transferir a propriedade para o usuário atualmente logado no CLI. --force pode forçar a criação de uma nova e sobrescrever o ponteiro mesmo se .config.json já existir
• scripts/link.sh — Apontar o skill para uma tabela Feishu Bitable existente (parâmetro de URL), --force pode sobrescrever o ponteiro atual
• scripts/append.sh — Adicionar um registro, suporta múltiplos anexos
• scripts/try-export.sh — Tentar silenciosamente exportar um zip através do servidor de desenvolvimento deste projeto; se bem-sucedido, imprime o caminho no stdout; caso contrário, imprime uma string vazia, permitindo que a lógica de append trate sem ramificação os casos de "colega interno com zip / usuário externo sem zip"
• .config.json (gerado em tempo de execução) — Armazena base_token / table_id / field_ids / owner_open_id / base_url / linked (linked=true indica que foi vinculado a uma tabela existente via link.sh; padrão indica que foi criado pelo bootstrap.sh)