Usar o D2B a partir de um agente de código

O D2B tem dois caminhos para agentes. MCP (tool calling: Claude Code / Claude Desktop / Cursor / VS Code etc.) e a CLI (d2b: agentes por shell, sincronização com git, trabalho em lote). Ambos expõem a mesma superfície: saída JSON, erros com suggested_fix, chave de idempotência em toda mutação, sem prompts interativos.

As normas de uso vêm do servidor. Ao conectar por MCP, a resposta de inicialização traz instructions — qual ferramenta, em que ordem — e o mesmo texto pode ser lido como o recurso d2b://guide. Não cole um procedimento longo no repositório; cole apenas a conexão e a escolha do caminho (abaixo).

Setup (a parte do humano)

1. Emitir um PAT de privilégio mínimo — para um agente, um token limitado a um workbook com limite de taxa (para delegar um workspace inteiro use "resource": "workspace:<WS_ID>"; a criação também fica fixada lá. Um token pertence sempre a uma conta; omita account_id para a conta padrão):

curl -X POST $BASE/api/v1/me/tokens -H "Authorization: Bearer $JWT" \
  -d '{"name": "agent", "scopes": ["workbooks:read", "workbooks:write"],
       "resource": "workbook:<WB_ID>", "rate_limit_per_minute": 60}'

2. Conectar — por MCP, o Claude Code é um comando (outros hosts: Conectar via MCP):

claude mcp add d2b --transport http https://d2b.dev/mcp/ --header "Authorization: Bearer $PAT"

d2b init escreve o lado do repositório — adiciona a seção de AGENTS.md abaixo e imprime a entrada MCP canônica que qualquer host pode usar. Hosts conhecidos são mesclados direto no seu arquivo com --host claude-code|cursor|vscode|codex|windsurf|claude-desktop; qualquer outro via --config PATH (JSON ou TOML). O token fica como referência a variável de ambiente, nunca em um arquivo.

Para a CLI, exporte D2B_API_KEY / D2B_BASE_URL (o Claude Code não lê .env sozinho) e instale com pipx install d2b-sdk ou uvx --from d2b-sdk d2b (uv add d2b-sdk + uv run d2b como dependência do projeto).

O snippet do repositório (só conexão e escolha)

As normas vêm do servidor: não copie o procedimento aqui; uma cópia não acompanha ferramentas novas e envelhece.

## D2B
- O trabalho com dados passa pelo D2B. O servidor MCP `d2b` está conectado — seguir primeiro as normas de `d2b://guide`.
- Para gestão com git (`d2b pull` / `d2b push`) e trabalho em lote, a CLI `uvx --from d2b-sdk d2b ...` (saída JSON; auth do env D2B_API_KEY / D2B_BASE_URL).
- Destinos, como trazer arquivos e versões estão no guia. Na dúvida, perguntar ao humano.

As normas que um agente segue (entregues pelo servidor)

O essencial de instructions / d2b://guide, com o equivalente em CLI. As normas não dependem da superfície; só os nomes das ferramentas mudam.

Norma	MCP	CLI
Orientar-se primeiro	list_my_data → get_schema	d2b workbooks list → d2b tables list --workbook WB
Confirmar o destino pelo nome antes de criar	list_my_workspaces → create_workbook	d2b workspaces list → d2b workbooks create --workspace-id …
Trazer arquivos por referência (nunca pelo próprio contexto)	ingest_url / request_upload → ingest_upload / import_cloud_file	d2b upload FILE --workbook WB --wait (d2b jobs wait JOB_ID for long runs)
Planilhas bagunçadas: inspecionar a estrutura antes de materializar	ingest_file (staged) → analyze_source → update_parse_spec → materialize_source	d2b upload --mode staged → d2b sources analyze → … materialize
Derivar com transforms, não com edição de linhas	add_transform / list_transforms	d2b transforms add; d2b pull writes them to transforms/
Em 409, reler e reaplicar (nunca sobrescrever às cegas)	reler edit_version com read_table	reler edit_version com d2b tables rows NAME --workbook WB
Cortar uma versão nos marcos para poder voltar	commit_snapshot / restore_snapshot / undo_op	d2b versions commit / d2b versions revert
Conferir os números antes de relatá-los	review_table / review_workbook (modo agente: acompanhe o job com get_job)	d2b review --workbook WB [--table NAME] [--agent]
Limpar	delete_workbook	d2b workbooks delete WB

Gerenciar um workbook no git (CLI)

d2b pull --workbook $WB escreve transforms/ sheets/ charts/ + d2b.json (--data TABLE adiciona o CSV de uma tabela base). Editar → conferir com d2b push --dry-run → d2b push --commit $(git rev-parse --short HEAD) → commitar d2b.json. O push envia só o que mudou (transforms são reexecutados, data passa por merge de 3 vias); se recusado, pull, merge e push de novo. charts/ é somente leitura. Detalhes: Gerenciar um workbook no git.

Edição que preserva o original (revise = corrigir só as linhas em questão e devolver o Excel original)

“Manter o Excel original inteiro, corrigir apenas as linhas em questão e produzir um arquivo novo” cabe em 1 chamada de revise (que internamente encadeia analyze → materialize → transform → write-back). O cálculo permanece como transformação SQL no servidor (com lineage disponível), e estilos, charts, outras planilhas e fórmulas fora da área são preservados como estão.

d2b sources revise equipment.xlsx --workbook $WB \
  --transform-name merge_tokyo_sites --range A3:N8 --sheet Summary \
  --sql-file merge.sql -o output.xlsx

O merge.sql é a view {{ artifact_name }} (a tabela da área alvo é vinculada a {{ src }}). A forma correta de escrever agregações que colapsam linhas:

• Colunas aditivas (quantidade de unidades, contagens, valores): SUM.
• Razões (taxa de utilização, taxa de conclusão): não tire a média. Recalcule depois de somar: SUM(分子) / NULLIF(SUM(分母), 0).
• Médias (MTBF, MTTR etc.): média ponderada, não média simples: SUM(値 * 重み) / NULLIF(SUM(重み), 0) (o peso é uma coluna com significado, como quantidade de unidades ou de ocorrências).
• Categorias (avaliações etc.): um valor representativo: arg_max(rating, units_managed).
• Para preservar a posição das linhas, inclua MIN("__d2b_row_id") no SELECT (a linha agregada entra na posição do primeiro membro, as linhas liberadas ficam em branco no lugar e as demais não se movem).

CREATE OR REPLACE VIEW "{{ artifact_name }}" AS
SELECT
  CASE WHEN site IN ('Tokyo Site 1','Tokyo Site 2') THEN 'Tokyo' ELSE site END AS site,
  SUM(units_managed) AS units_managed,
  SUM(units_active) * 1.0 / NULLIF(SUM(units_managed), 0) AS utilization,
  SUM("MTBF(h)" * units_managed) / NULLIF(SUM(units_managed), 0) AS "MTBF(h)",
  arg_max(rating, units_managed) AS rating,
  MIN("__d2b_row_id") AS "__d2b_row_id"
FROM {{ src }}
GROUP BY 1
ORDER BY MIN("__d2b_row_id")

Mesmo que a área contenha linhas de total/subtotal (=SUM(...)), essas células de fórmula não são sobrescritas — elas são mantidas (o Excel recalcula). Edições que aumentam o número de linhas além da área do template quebram a geometria e são recusadas (409). No MCP, revise_source; no SDK, sources.revise(...) — é o mesmo caminho.

Entregar constantes como “fórmulas vivas” (formula column)

Uma coluna preenchida com constantes (ex.: taxa de utilização) pode ser substituída, no export, por fórmulas Excel linha a linha. Os valores em si não são tocados — é uma “projeção de entrega” que só anexa a forma de rederivá-los no .xlsx entregue. As referências são escritas com o placeholder {列名}, o nome da coluna entre chaves (endereços de célula A1 não são aceitos — a referência fica ancorada na identidade, para não se deslocar com sort ou filtro). O servidor resolve as coordenadas no momento do export.

# Deliver utilization = units_active / units_total as a live per-row formula
d2b tables set-formula equipment utilization "{units_active} / {units_total}" --workbook <WB>

out = client.tables.set_formula(wb, "equipment", "utilization", "{units_active} / {units_total}")
out["verification"]   # {checked, rows, matches, mismatches} — does it reproduce the current constants?

Como os valores são a fonte canônica, a escrita retorna um relatório de verificação (a fórmula reproduz os valores atuais da coluna dentro da tolerância?). Você pode confirmar a troca “constante → fórmula” antes de entregar. No MCP: set_formula_column / list_formula_columns / clear_formula_column. Hoje o alvo é o export xlsx (combinável com as transformações SQL de {{ ... }} e com o write-back de revise que preserva o original). Funções (SUM/IF etc.) passam só pela verificação estrutural — a verificação numérica é pulada. underline não é suportado.

Referência entre planilhas: com {table!column} você referencia todo o intervalo de dados de uma coluna de outra tabela (ao exportar várias tabelas em 1 arquivo, isso compila para a referência absoluta da sheet onde a coluna está, 'rates'!$B$2:$B$N). Use envolvida em uma função de agregação:

# Revenue share = this row's amount ÷ the sum of rates.weight
client.tables.set_formula(wb, "sales", "share", "{amount} / SUM({rates!weight})")
client.export.tables(wb, tables=["sales", "rates"], format="xlsx")
# → each share row compiles to =B2/SUM('rates'!$B$2:$B$N) (same-table {amount} relative, cross-refs absolute)

Se a tabela referenciada não estiver no mesmo export, a fórmula não pode ser resolvida e faz fallback para o valor. Junções por chave no estilo VLOOKUP devem ser expressas não como fórmula, mas como um transform de JOIN (add_transform) (o lineage é preservado).

Restrições e observações

• Em sandboxes na nuvem (Codex etc.), restrições de egress podem exigir configurar a liberação de acesso à API
• Para agentes com timeout de Bash curto, o fluxo em 2 etapas “upload assíncrono → jobs wait” é mais seguro do que upload --wait