plan(OPS101+B201): modelo canônico deepseek-flash (Related #944, #945)

2026-11-13 15:13:07 +00:00 · 2026-09-12 01:30:03 -03:00 · 2026-09-12 01:30:03 -03:00 · b066e32b16
commit b066e32b16
parent 581cb933a8
2 changed files with 163 additions and 0 deletions
--- a/docs/plans/sollinha-modelo-canonico-deepseek-flash.md
+++ b/docs/plans/sollinha-modelo-canonico-deepseek-flash.md
@ -0,0 +1,78 @@
+# Sollinha no nome canônico `deepseek-flash` (DeepSeek V4.1 Flash)
+
+Status: rascunho
+Atualizado em: 2026-09-12
+Issue: #945
+Priority: P2
+Impeccable: A — N/A sem UI
+Rascunho UI: N/A — sem UI
+Appetite: ~0,5 dia eng — troca de literal + verificação
+Responsável: —
+
+## Intenção
+
+O DeepSeek lançou o V4.1 Flash em 2026-09-10 e o nome canônico na API passou a ser `deepseek-flash` (model version DeepSeek-V4.1-Flash). Os nomes legados `deepseek-v4-flash` e `deepseek-v4-flash-vision-exp` continuam aceitos, mas os modelos foram aposentados: requisições no nome legado são servidas pelo V4.1-Flash ao preço Flash (fonte oficial: https://api-docs.deepseek.com/quick_start/pricing, verificada em 2026-09-12). O humano quer o Sollinha no modelo novo do DeepSeek. Como o alias já entrega o V4.1-Flash, o ganho aqui é ficar no nome canônico antes que o legado suma — não é mudança de comportamento nem economia.
+
+## Persona e fluxo
+
+- **Persona / contexto:** equipe de campanha (coordenação, assessoria, candidato) usando o Sollinha no `/campanha`; em paralelo, o gerador automático de título de demanda.
+- **Job principal:** continuar conversando com o Sollinha sem se preocupar com qual nome de modelo está por baixo.
+- **Fluxo desejado:** abrir o chat → perguntar → receber a mesma resposta de sempre; internamente o servidor passa a chamar o nome canônico. Nada visível muda.
+- **Anti-goals de produto:** não habilitar imagem/visão no chat; não mexer em prompt, tools, rate limit ou sessão; não trocar de provider; não mexer no default do worktree.
+
+## Objetivo e aceite
+
+- O chat do Sollinha passa a chamar `deepSeek('deepseek-flash')` (nome canônico) no lugar do literal legado.
+- O gerador de título de demanda acompanha a mesma troca.
+- Comportamento visível do chat idêntico: gate de papel (leader lockdown), tools, prompt e sessão intocados.
+- Nenhuma capacidade nova exposta: visão do V4.1 continua desligada no chat; provider segue `api.deepseek.com`.
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — troca de literal de modelo em código server-side, sem superfície para o usuário.
+- **Decisões desbloqueadas:** N/A.
+- **Forma:** N/A.
+
+## Dados da decisão (literais)
+
+- `deepseek-flash` — nome canônico novo (model version `DeepSeek-V4.1-Flash`): 1M contexto, 384K output, thinking mode default, tool calls, JSON, visão (imagem disponível, não habilitada aqui).
+- `deepseek-v4-flash` — nome legado ainda aceito; modelo aposentado, requisições servidas pelo V4.1-Flash ao preço Flash.
+- Trocar `deepSeek('deepseek-v4-flash')` → `deepSeek('deepseek-flash')` em `src/app/(campaign)/campanha/api/ai-chat/route.ts:62` (chat do Sollinha).
+- Trocar `deepSeek('deepseek-v4-flash')` → `deepSeek('deepseek-flash')` em `src/utilities/ai/campaignDemandTitle.ts:31` (título de demanda).
+- SDK `@ai-sdk/deepseek` 3.0.19 (package.json) e chave `DEEPSEEK_API_KEY` server-side — nenhum dos dois muda.
+- Preço inalterado: tabela Flash (input cache-hit US$0,003/M off-peak e US$0,006/M peak; cache-miss US$0,15/M off-peak e US$0,3/M peak; output US$0,6/M off-peak e US$1,2/M peak; peak = 01:00–04:00 e 06:00–10:00 UTC, seg–sex).
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `src/app/(campaign)/campanha/api/ai-chat/route.ts` e `src/utilities/ai/campaignDemandTitle.ts`.
+- **Precedente a olhar:** nenhum específico — troca de string em call site já existente; SDK e fluxo ficam como estão.
+- **Risco de acoplamento:** o chat é 100% server-side e o modelo entra só como string; não tocar em gate de papel, tools, prompt ou sessão.
+- **Testes:** nenhum teste pina a string do modelo (e2e mockam a rota HTTP; unit/int cobrem só o fallback sem `DEEPSEEK_API_KEY`) — a troca não deve quebrar a suíte.
+
+## Dependências
+
+- Nenhuma.
+
+## Fora de escopo
+
+- Habilitar envio/aceitação de imagem (visão do V4.1) — feature nova, outro item.
+- Qualquer mudança em prompt, tools, rate limit ou sessão do Sollinha.
+- Troca de provider ou de SDK; default de modelo do worktree (OPS101).
+- Editar planos históricos congelados de IA.
+
+## Rabbit holes de produto
+
+- **"O V4.1 tem visão, então já dá para mandar foto".** Se alguém “só completar”: upload, storage, moderação, UI e custo viram um item inteiro. **Corte neste item:** visão continua desligada; só o literal muda.
+- **"Modelo novo pede prompt/tools novos".** Se alguém “só completar”: reescrever system prompt e catálogo de tools sem pedido. **Corte neste item:** prompt e tools intocados.
+- **"Já que está mexendo, atualiza a SDK".** Se alguém “só completar”: bump de dependência com risco próprio. **Corte neste item:** SDK fica em 3.0.19.
+
+## Questões em aberto (produto)
+
+- Nenhuma — a única pergunta (incluir também o `campaignDemandTitle.ts`?) foi decidida no gate de 2026-09-12: **opção A (sim, os dois call sites)**.
+
+## Referências
+
+- GitHub Issue #945 (B201, após `pnpm agent:register`)
+- Rascunho UI (gate): N/A
+- Fonte oficial do modelo/preço: https://api-docs.deepseek.com/quick_start/pricing (verificada em 2026-09-12)
+- `src/app/(campaign)/campanha/api/ai-chat/route.ts:62` e `src/utilities/ai/campaignDemandTitle.ts:31` — call sites vivos do nome legado.
--- a/docs/plans/worktree-modelo-canonico-deepseek-flash.md
+++ b/docs/plans/worktree-modelo-canonico-deepseek-flash.md
@ -0,0 +1,85 @@
+# Modelo padrão do worktree → DeepSeek V4.1 Flash (`deepseek/deepseek-flash`)
+
+Status: rascunho
+Atualizado em: 2026-09-12
+Issue: #944
+Priority: P2
+Impeccable: A — N/A sem UI
+Rascunho UI: N/A — sem UI
+Appetite: ~0,5 dia eng — config-only + textos + pins
+Responsável: —
+
+## Intenção
+
+O DeepSeek lançou o V4.1 Flash em 2026-09-10 e o nome canônico do modelo na API passou a ser `deepseek-flash` (DeepSeek-V4.1-Flash). Os nomes legados `deepseek-v4-flash` e `deepseek-v4-flash-vision-exp` seguem aceitos, mas os modelos correspondentes foram aposentados: as requisições já são servidas pelo V4.1-Flash ao preço Flash (fonte oficial: https://api-docs.deepseek.com/quick_start/pricing, verificada em 2026-09-12). Hoje o fluxo `pnpm worktree next/plan/new/fix` sem flag abre o TUI com `--model deepseek/deepseek-v4-flash`, e os comandos `/work-issue`, `/plan-issue`, `/bug-fix`, `/testing-audit` pinam o nome legado no frontmatter — que sobrescreve o modelo default da sessão (docs oficiais do opencode). O humano quer o fluxo de worktree no nome canônico novo por padrão.
+
+Isto é **future-proofing de nome canônico**, não economia: o alias legado já é cobrado ao preço Flash. O nome legado pode sumir sem aviso.
+
+## Persona e fluxo
+
+- **Persona / contexto:** o próprio mantenedor/agente operando o fluxo de worktrees no terminal; sem tela, sem interface.
+- **Job principal:** disparar o worktree sem flag e a sessão opencode nascer já no modelo canônico `deepseek/deepseek-flash`, sem depender de flag ou config global.
+- **Fluxo desejado:** o humano roda `pnpm worktree next` (ou `plan`/`new`/`fix`); o TUI abre com `/work-issue` (ou o comando do propósito) já no modelo novo; quem quiser outro modelo continua usando as flags existentes ou o override `OPENCODE_WORKTREE_MODEL`.
+- **Anti-goals de produto:** não é "mais barato"; não é redesenhar o menu de flags; não é mudar comportamento dos comandos além do nome do modelo; não é mexer na config global da máquina.
+
+## Objetivo e aceite
+
+- O preset do fluxo de worktree (sem flag) passa a apontar para `deepseek/deepseek-flash`.
+- Os quatro comandos do fluxo deixam de pinar o nome legado no frontmatter.
+- Textos, help e docblocks que citam o preset refletem o nome novo; nada além do nome do modelo muda.
+- O override `OPENCODE_WORKTREE_MODEL` e as 7 flags (`--cheap/--pro/--zen/--go/--alibaba/--glm/--free`) seguem intactos.
+- A suíte unitária que pina o preset e o frontmatter passa com os literais novos.
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não.
+- **Decisões desbloqueadas:** N/A — decisão única de configuração, sem ator/consumidor de dado.
+- **Forma:** N/A — item config-only, sem superfície de dados.
+
+## Dados da decisão (literais)
+
+- Modelo canônico novo: `deepseek/deepseek-flash` (DeepSeek-V4.1-Flash).
+- Modelo legado hoje no preset: `deepseek/deepseek-v4-flash`; variante legada também aposentada: `deepseek-v4-flash-vision-exp`.
+- Frontmatter hoje nos 4 comandos: `model: deepseek/deepseek-v4-flash`.
+- Fallback do preset: `process.env.OPENCODE_WORKTREE_MODEL || 'deepseek/deepseek-v4-flash'`.
+- Regex que pina o frontmatter: `/^model: deepseek\/deepseek-v4-flash$/m`.
+- Capacidades do canônico: 1M contexto, 384K output, thinking mode default, tool calls, JSON, visão (imagem).
+- Preço Flash (referência, **não** ganho): cache-hit $0.003/M off-peak e $0.006/M peak; cache-miss $0.15/M off-peak e $0.3/M peak; output $0.6/M off-peak e $1.2/M peak (peak = 01:00–04:00 e 06:00–10:00 UTC, seg–sex).
+- `opencode models` local lista `deepseek/deepseek-flash` (2026-09-12); models.dev descreve com reasoning options low/high/max.
+- Superfícies com o literal (levantadas em 2026-09-12): `scripts/lib/worktree.mjs:36-37` (fonte única) e docblocks :43/:64/:74/:214; `scripts/worktree.mjs:29-30` e help :877; `.agents/shell/worktree.sh:22`; `.agents/skills/worktree-next-issue/SKILL.md:34`; `.opencode/commands/work-issue.md:3`, `plan-issue.md:3`, `bug-fix.md:3`, `testing-audit.md:3`; `tests/unit/worktree.unit.spec.ts:46` e :245; `tests/unit/opencodeCommands.unit.spec.ts:37`.
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `scripts/lib/worktree.mjs` (constante do preset e docblocks), os 4 `.opencode/commands/*.md` (frontmatter), textos de `scripts/worktree.mjs`, `.agents/shell/worktree.sh`, `.agents/skills/worktree-next-issue/SKILL.md` e os dois specs unitários.
+- **Precedente a olhar:** OPS93 (menu de flags), OPS95 (removeu `--variant`), OPS100 (`--glm`/`--free`) — mesmo fluxo, mesmas superfícies.
+- **Risco de acoplamento:** o preset é a única fonte do fallback; flags, override e aliases legados de outros providers (`cheapestinference/deepseek-v4-flash`, `alibaba-token-plan/deepseek-v4-flash`) ficam intocados.
+
+## Dependências
+
+- Nenhuma.
+
+## Fora de escopo
+
+- Menu de flags (`WORKTREE_MODEL_MAP`), o override `OPENCODE_WORKTREE_MODEL` e aliases legados de outros providers.
+- Config global da máquina, `opencode.json` do repo, variantes/Ctrl+T, `--variant` na diretiva (OPS95).
+- Sollinha (B201) e pool/Cursor.
+- Docs históricos/congelados (`docs/plans/*`, `docs/changelog/*`, HISTORY).
+
+## Rabbit holes de produto
+
+- **Trocar o "cardápio" inteiro de modelos.** Se alguém "só completar": revisar preço/capacidade de todas as flags e reescrever o mapa. **Corte neste item:** só o preset sem flag + o pin dos 4 comandos.
+- **Adicionar variante/thinking config ao preset.** Se alguém "só completar": emitir `--variant` (proibido pelo OPS95) ou mexer no config global. **Corte neste item:** sem flag nova, sem variante.
+- **Vender economia.** Se alguém "só completar": justificar a troca como redução de custo — falso, o alias legado já é servido pelo V4.1-Flash ao preço Flash. **Corte neste item:** registrar como nome canônico/future-proofing.
+
+## Questões em aberto (produto)
+
+- Nenhuma — a única pergunta (incluir o frontmatter dos 4 comandos + o pin do `opencodeCommands.unit.spec.ts`?) foi decidida no gate de 2026-09-12: **opção A (sim, todos)**.
+
+## Referências
+
+- GitHub Issue #944 (OPS101, após `pnpm agent:register`)
+- Rascunho UI (gate): N/A
+- `scripts/lib/worktree.mjs` — preset e mapa de flags (fonte única do fallback)
+- `tests/unit/worktree.unit.spec.ts` e `tests/unit/opencodeCommands.unit.spec.ts` — pins que o executor atualiza
+- `docs/AGENT-OPS.md` — operação do paradigma de agentes paralelos
+- https://api-docs.deepseek.com/quick_start/pricing — nomes canônicos e preço (verificada em 2026-09-12)