@agent-native/core 0.100.2 → 0.101.3

package/docs/content/locales/pt-BR/pr-visual-recap.mdx

@@ -102,13 +102,13 @@ explicitamente a qualquer momento:
 npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-Isso instala a habilidade `visual-plan` (que inclui a habilidade `visual-recap` que a ação executa) e grava `.github/workflows/pr-visual-recap.yml` em seu repositório. O fluxo de trabalho chama **subcomandos CLI publicados** por meio de `npx @agent-native/core@latest recap <subcommand>` — incluindo `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check` e `usage` – portanto, nada é copiado em seu repositório como scripts auxiliares. `setup` e `doctor` são os auxiliares interativos que você executa localmente; `gate` é a etapa de segurança que o fluxo de trabalho executa antes de cada recapitulação.
+Isso instala a habilidade `visual-plan` (que inclui a habilidade `visual-recap` que a ação executa) e grava `.github/workflows/pr-visual-recap.yml` em seu repositório. O fluxo de trabalho chama **subcomandos CLI publicados** por meio de `npx @agent-native/recap-cli@latest recap <subcommand>` — incluindo `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check` e `usage` – portanto, nada é copiado em seu repositório como scripts auxiliares. `setup` e `doctor` são os auxiliares interativos que você executa localmente; `gate` é a etapa de segurança que o fluxo de trabalho executa antes de cada recapitulação.
 
 Em seguida, execute o assistente de configuração guiada:
 
 ```bash
-npx @agent-native/core@latest recap setup
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 `recap setup` atualiza o fluxo de trabalho, usa `gh` para definir GitHub Actions
@@ -118,7 +118,7 @@ conjunto. Os valores secretos são enviados para `gh` por meio de stdin, não po
 o arquivo de fluxo de trabalho gerado e abra um PR para vê-lo ser executado.
 
 Por padrão, o fluxo de trabalho cria seu prompt de agente a partir do pacote mais recente
-Orientação `visual-recap` em `@agent-native/core@latest`, incluindo qualquer irmão
+Orientação `visual-recap` em `@agent-native/recap-cli@latest`, incluindo qualquer irmão
 arquivos de referência que acompanham a habilidade. Se o seu repositório for personalizado intencionalmente e
 fixa sua pasta `visual-recap` comprometida, defina a variável do repositório
 `VISUAL_RECAP_SKILL_SOURCE=repo`.
@@ -135,8 +135,8 @@ Por padrão, o fluxo de trabalho é executado em executores `ubuntu-latest` hosp
 As aspas JSON são obrigatórias. Esse valor seleciona o executor do trabalho completo `recap`. Para configurá-lo durante a instalação guiada, passe o mesmo valor JSON para `--runs-on` e depois valide o fluxo de trabalho e a disponibilidade do executor com `doctor`:
 
 ```bash
-npx @agent-native/core@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 O gate leve usa `ubuntu-latest` separadamente. Repositórios sem executores hospedados pelo GitHub podem definir `VISUAL_RECAP_GATE_RUNS_ON` como um único rótulo de texto simples, sem JSON, ou usar `--gate-runs-on visual-recap-gate`. O rótulo personalizado só vale para autores `OWNER`, `MEMBER` ou `COLLABORATOR` do mesmo repositório; forks e outros autores são forçados para `ubuntu-latest` e podem ficar sem agendamento se os executores hospedados estiverem desativados. Use um executor dedicado e, de preferência, efêmero: o gate padrão não baixa a árvore do PR e avalia a lógica do fluxo de trabalho e os metadados do PR.
@@ -160,12 +160,30 @@ Se a variável não estiver definida, a ação usará `claude`.
 
 Além do back-end, duas variáveis de repositório ajustam _como_ o agente é executado:
 
-- **`VISUAL_RECAP_MODEL`** fixa o modelo passado para CLI (`--model`) — por exemplo, `gpt-5.6-sol` para Codex ou um ID de modelo Claude. Deixe-o desativado para usar o modelo padrão do próprio CLI.
+- **`VISUAL_RECAP_MODEL`** fixa o modelo passado para CLI (`--model`) — por exemplo, `gpt-5.6-luna` para Codex, um ID de modelo Claude, ou `deepseek-chat` para DeepSeek. É obrigatória para `openai-compatible`. Para o back-end **Claude**, se a variável não estiver definida, o padrão agora é `claude-sonnet-5`; defina-a explicitamente para usar um modelo Claude diferente, como o mais barato `claude-haiku-4-5`. Para o back-end **Codex**, se não estiver definida, é usado o modelo padrão do próprio CLI do Codex.
 - **`VISUAL_RECAP_REASONING`** define a profundidade do raciocínio: `none`, `minimal`, `low`, `medium`, `high` ou `xhigh`. Aplica-se ao backend Codex; O raciocínio de Claude é baseado em modelo, então esta variável é ignorada lá.
 - **`VISUAL_RECAP_SKILL_SOURCE`** controla a atualização do prompt: `auto`/unset usa o pacote de orientação de habilidades mais recente, enquanto `repo` fixa-se à pasta de habilidades `visual-recap` do repositório local confirmado.
 
 Por exemplo, para executar a recapitulação em Codex com GPT-5.6 Sol com raciocínio alto, defina as variáveis de repositório `VISUAL_RECAP_AGENT=codex`, `VISUAL_RECAP_MODEL=gpt-5.6-sol` e `VISUAL_RECAP_REASONING=high`.
 
+## Custo
+
+Cada execução de recapitulação é uma sessão completa de agente de codificação lendo um diff real, não um resumo barato baseado em modelo, então seu custo acompanha a escolha do modelo e a frequência com que é executada:
+
+- **Uma sessão completa por push no PR.** O gatilho padrão dispara em `synchronize`, então um PR que recebe dez pushes executa o agente dez vezes.
+- **O PR inteiro a cada vez**, não apenas os commits desde a última execução — o custo escala com o tamanho total do PR, não com o tamanho incremental do diff.
+- **Entrada do diff limitada a ~600KB.** Isso limita o pior caso por execução, mas diffs grandes ainda custam significativamente mais do que os pequenos.
+- **Uma nova tentativa automática em caso de falha**, o que pode aproximadamente dobrar o custo de uma execução que falha de forma transitória.
+
+Para reduzir o custo:
+
+- **Fixe um modelo mais barato.** Para Claude, defina `VISUAL_RECAP_MODEL=claude-haiku-4-5` para repositórios simples ou pequenos — é o nível Claude mais barato; `claude-sonnet-5` (o padrão) é o nível equilibrado.
+- **Mude para Codex com um modelo mais barato.** Defina `VISUAL_RECAP_AGENT=codex` com `VISUAL_RECAP_MODEL=gpt-5.6-luna` (o nível GPT-5.6 mais barato) ou `gpt-5.6-terra` (nível intermediário), e defina `VISUAL_RECAP_REASONING=low` para reduzir ainda mais o gasto com tokens de raciocínio. A profundidade de raciocínio só se aplica ao Codex.
+- **Aponte para um provedor mais barato compatível com OpenAI.** Defina `VISUAL_RECAP_AGENT=openai-compatible` com `VISUAL_RECAP_BASE_URL`/`VISUAL_RECAP_MODEL`/`VISUAL_RECAP_API_KEY` direcionados ao DeepSeek, Kimi ou qualquer outro endpoint compatível com OpenAI.
+- **Recapitule com menos frequência.** Edite o `on.pull_request.types` do fluxo de trabalho instalado de `[opened, synchronize, reopened, ready_for_review, closed]` para `[opened, ready_for_review, closed]` para que ele só recapitule quando um PR é aberto e quando é mesclado, em vez de a cada push.
+
+Cada execução registra o que realmente foi gasto: a etapa `recap usage` do fluxo de trabalho anexa o uso de tokens e custo ao plano publicado, para que você possa ver o gasto real por execução em vez de adivinhar.
+
 ## Segredos e variáveis
 
 Defina-os em **Configurações → Segredos e variáveis → Actions** do seu repositório.
@@ -196,11 +214,11 @@ Aplicativo Planos.
 
 **Solo: um token pessoal ainda funciona.** Crie-o com `npx @agent-native/core@latest connect`
 em seu aplicativo Planos. Para o aplicativo hospedado, isso também grava um local
-arquivo de token de publicação que `npx @agent-native/core@latest recap setup` pode ler:
+arquivo de token de publicação que `npx @agent-native/recap-cli@latest recap setup` pode ler:
 
 ```bash
 npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
-npx @agent-native/core@latest recap setup
+npx @agent-native/recap-cli@latest recap setup
 ```
 
 Se preferir a configuração manual, cole o token no segredo GitHub. Utilize um
@@ -209,16 +227,16 @@ token real.
 
 ### Opcional (somente se você alterar os padrões)
 
-| Segredo/variável         | Padrão                          | Quando você precisar                                                                                                                                                |
-| ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OPENAI_API_KEY`         | —                               | Segredo. Defina junto com `VISUAL_RECAP_AGENT=codex` para executar a recapitulação com Codex.                                                                       |
-| `VISUAL_RECAP_AGENT`     | `claude`                        | Variável. Seleciona o back-end do agente de codificação (`claude` ou `codex`).                                                                                      |
-| `VISUAL_RECAP_MODEL`     | padrão de cada CLI              | Variável. Fixa o modelo - por ex. `gpt-5.6-sol` para Codex ou um ID de modelo Claude. Unset usa o próprio padrão do CLI.                                            |
-| `VISUAL_RECAP_REASONING` | padrão de cada modelo           | Variável. Profundidade de raciocínio: `none`, `minimal`, `low`, `medium`, `high` ou `xhigh`. Aplica-se ao back-end Codex.                                           |
-| `RECAP_CLI_VERSION`      | `latest`                        | Variável. Fixa a versão `@agent-native/core` CLI que o fluxo de trabalho instala - por exemplo. `1.5.0`. Consulte [Version pinning](#version-pinning-copy-variant). |
-| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | Segredo. Somente ao auto-hospedar o aplicativo Planos em uma origem diferente.                                                                                      |
+| Segredo/variável         | Padrão                                                                | Quando você precisar                                                                                                                                                                                                                                                                                                    |
+| ------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                                                                     | Segredo. Defina junto com `VISUAL_RECAP_AGENT=codex` para executar a recapitulação com Codex.                                                                                                                                                                                                                           |
+| `VISUAL_RECAP_AGENT`     | `claude`                                                              | Variável. Seleciona o back-end do agente de codificação (`claude` ou `codex`).                                                                                                                                                                                                                                          |
+| `VISUAL_RECAP_MODEL`     | `claude-sonnet-5` para Claude; obrigatório para o back-end compatível | Variável. ID do modelo do provedor para back-ends compatíveis com OpenAI (obrigatório nesse caso). Para Claude, se não definida, o padrão agora é `claude-sonnet-5` — defina-a para substituir, por ex. `claude-haiku-4-5` para o nível mais barato. Para Codex, se não definida, usa o próprio padrão do CLI do Codex. |
+| `VISUAL_RECAP_REASONING` | padrão de cada modelo                                                 | Variável. Profundidade de raciocínio: `none`, `minimal`, `low`, `medium`, `high` ou `xhigh`. Aplica-se ao back-end Codex.                                                                                                                                                                                               |
+| `RECAP_CLI_VERSION`      | `latest`                                                              | Variável. Fixa a versão `@agent-native/recap-cli` CLI que o fluxo de trabalho instala - por exemplo. `1.5.0`. Consulte [Version pinning](#version-pinning-copy-variant).                                                                                                                                                |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com`                                       | Segredo. Somente ao auto-hospedar o aplicativo Planos em uma origem diferente.                                                                                                                                                                                                                                          |
 
-O fluxo de trabalho detecta automaticamente como invocar seu auxiliar CLI (fonte local dentro deste monorepo, o `@agent-native/core` publicado em outro lugar), portanto, não há variável `RECAP_CLI` a ser definida.
+O fluxo de trabalho detecta automaticamente como invocar seu auxiliar CLI (fonte local dentro deste monorepo, o `@agent-native/recap-cli` publicado em outro lugar), portanto, não há variável `RECAP_CLI` a ser definida.
 
 ## Captura de tela embutida no comentário
 
@@ -359,9 +377,9 @@ recapitular sem enviar conteúdo de recapitulação para o banco de dados do Pla
 mesmo fluxo auxiliar localmente no modo de arquivos locais:
 
 ```bash
-npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
-npx @agent-native/core@latest recap scan --diff recap.diff
-npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+npx @agent-native/recap-cli@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/recap-cli@latest recap scan --diff recap.diff
+npx @agent-native/recap-cli@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
 ```
 
 Entregue o `recap-prompt.md` gerado ao seu agente de codificação. No modo de arquivos locais
@@ -391,7 +409,7 @@ A recapitulação é um auxílio de revisão que se sobrepõe ao fluxo normal de
 
 ## Fixação de versão (variante de cópia) {#version-pinning-copy-variant}
 
-Por padrão, o fluxo de trabalho da variante de cópia instala o `@agent-native/core@latest` em tempo de execução para que cada execução de recapitulação selecione automaticamente o CLI mais recente. Se seu CI precisar de ferramentas reproduzíveis, defina a variável de repositório **`RECAP_CLI_VERSION`** para fixar a versão instalada:
+Por padrão, o fluxo de trabalho da variante de cópia instala o `@agent-native/recap-cli@latest` em tempo de execução para que cada execução de recapitulação selecione automaticamente o CLI mais recente. Se seu CI precisar de ferramentas reproduzíveis, defina a variável de repositório **`RECAP_CLI_VERSION`** para fixar a versão instalada:
 
 1. Vá para **Configurações → Segredos e variáveis → Actions → Variáveis** do seu repositório.
 2. Crie uma variável chamada `RECAP_CLI_VERSION` com um valor como `1.5.0`.
@@ -402,7 +420,7 @@ Para a variante do chamador reutilizável, use a entrada `cli-version` (consulte
 
 ## Lista de permissões de verificação secreta
 
-Antes de publicar uma recapitulação, o fluxo de trabalho executa `npx @agent-native/core@latest recap scan` para detectar prováveis segredos na comparação. Qualquer PR cuja comparação corresponda a um padrão de segredo conhecido é bloqueado com um comentário explicativo — a recapitulação não é publicada e nenhum conteúdo de comparação é enviado ao agente de codificação.
+Antes de publicar uma recapitulação, o fluxo de trabalho executa `npx @agent-native/recap-cli@latest recap scan` para detectar prováveis segredos na comparação. Qualquer PR cuja comparação corresponda a um padrão de segredo conhecido é bloqueado com um comentário explicativo — a recapitulação não é publicada e nenhum conteúdo de comparação é enviado ao agente de codificação.
 
 Em casos raros, um repositório possui acessórios de teste intencionais ou strings não secretas que se assemelham superficialmente a padrões secretos (por exemplo, uma chave de acessório em um arquivo de teste). Para suprimir um falso positivo, crie `.github/recap-scan-allowlist` na raiz do seu repositório.
 
@@ -436,7 +454,7 @@ A lista de permissões só é consultada pelo portão de varredura secreta. Isso
 
 ### Por que usar a variante reutilizável?
 
-O instalador padrão copia o fluxo de trabalho completo de aproximadamente 360 linhas YAML em seu repositório (a opção **copiar**). Esta é a escolha certa para repositórios isolados ou repositórios que precisam auditar cada linha do que é executado. A desvantagem é que as correções de bugs e melhorias nunca chegam até você – você precisa executar novamente o `npx @agent-native/core@latest recap setup` manualmente após cada lançamento.
+O instalador padrão copia o fluxo de trabalho completo de aproximadamente 360 linhas YAML em seu repositório (a opção **copiar**). Esta é a escolha certa para repositórios isolados ou repositórios que precisam auditar cada linha do que é executado. A desvantagem é que as correções de bugs e melhorias nunca chegam até você – você precisa executar novamente o `npx @agent-native/recap-cli@latest recap setup` manualmente após cada lançamento.
 
 A opção **reutilizável** grava um chamador fino de aproximadamente 20 linhas. Delega para `BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml` via `uses:`. Cada chamador seleciona automaticamente a lógica mais recente quando o fluxo de trabalho é executado, sem necessidade de atualização local.
 
@@ -449,7 +467,7 @@ A opção **reutilizável** grava um chamador fino de aproximadamente 20 linhas.
 
 ### Snippet do autor da chamada
 
-Isso é o que `npx @agent-native/core@latest recap setup --reusable` escreve (ou você pode colá-lo manualmente):
+Isso é o que `npx @agent-native/recap-cli@latest recap setup --reusable` escreve (ou você pode colá-lo manualmente):
 
 ```yaml
 name: PR Visual Recap
@@ -484,7 +502,7 @@ jobs:
       skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
       runs-on: ${{ vars.VISUAL_RECAP_RUNS_ON || '"ubuntu-latest"' }}
       gate-runs-on: ${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}
-      # cli-version: "latest"  # pin to a specific @agent-native/core version
+      # cli-version: "latest"  # pin to a specific @agent-native/recap-cli version
 ```
 
 Aplicam-se os mesmos segredos e variáveis descritos em [Secrets and variables](#secrets-and-variables). O chamador reutilizável encaminha `VISUAL_RECAP_RUNS_ON` como `runs-on` para o trabalho completo e `VISUAL_RECAP_GATE_RUNS_ON` como o rótulo simples `gate-runs-on` para o gate. Ambos usam `ubuntu-latest` quando omitidos.
@@ -493,15 +511,15 @@ Aplicam-se os mesmos segredos e variáveis descritos em [Secrets and variables](
 
 ```bash
 # Escreva o chamador thin em vez da cópia completa:
-npx @agent-native/core@latest recap setup --reusable
+npx @agent-native/recap-cli@latest recap setup --reusable
 
 # Ou com uma referência fixada para reprodutibilidade:
-npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+npx @agent-native/recap-cli@latest recap setup --reusable --ref v1.2.3
 ```
 
 Ambas as variantes gravam o fluxo de trabalho em `.github/workflows/pr-visual-recap.yml`. Se um fluxo de trabalho existente já existir e for diferente, o comando recusará e solicitará que você passe `--force` para substituição.
 
-Depois de escrever, execute `npx @agent-native/core@latest recap doctor` normalmente para confirmar se os segredos estão configurados.
+Depois de escrever, execute `npx @agent-native/recap-cli@latest recap doctor` normalmente para confirmar se os segredos estão configurados.
 
 ### Fixação de versão
 
@@ -511,7 +529,7 @@ Por padrão, o chamador faz referência a `@main`, que sempre usa a versão publ
 uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
 ```
 
-A entrada `cli-version` controla qual versão do `@agent-native/core` CLI é executada dentro do fluxo de trabalho. Deixe-a em `"latest"` para rastrear a versão mais recente ou fixe-a em uma string de versão (por exemplo, `"1.5.0"`) para reprodutibilidade total.
+A entrada `cli-version` controla qual versão do `@agent-native/recap-cli` CLI é executada dentro do fluxo de trabalho. Deixe-a em `"latest"` para rastrear a versão mais recente ou fixe-a em uma string de versão (por exemplo, `"1.5.0"`) para reprodutibilidade total.
 
 ### contexto do evento workflow_call
 

package/docs/content/locales/pt-BR/template-plan.mdx

@@ -214,6 +214,20 @@ Se a primeira passagem ainda tiver decisões responsáveis, o agente pode fazer
 **Formulário de perguntas abertas** na parte inferior do mesmo plano. Respondendo e enviando
 o agente inicia uma revisão do plano existente.
 
+## Custo e escolha do modelo
+
+Gerar um plano ou uma recapitulação executa uma sessão completa de agente contra
+o LLM do seu agente de codificação, não um preenchimento leve de modelo, então o
+custo escala com o tamanho do diff ou do plano e o modelo que você escolher.
+
+- O modelo de chat padrão do próprio aplicativo é o Sonnet 5; altere-o a qualquer
+  momento em **Configurações**. Haiku é a opção Claude mais barata, e Luna é a
+  opção mais barata da família GPT-5.6.
+- As recapitulações automáticas de PR da GitHub Action são executadas
+  separadamente do aplicativo interativo e têm seus próprios controles de
+  modelo e custo — veja [PR Visual Recap](/docs/pr-visual-recap) para
+  `VISUAL_RECAP_MODEL`, `VISUAL_RECAP_AGENT` e `VISUAL_RECAP_REASONING`.
+
 ## O que você pode fazer com isso
 
 - **Revisão antes da implementação.** React para diagramas, wireframes, guias de opções,

package/docs/content/locales/zh-CN/pr-visual-recap.mdx

@@ -102,13 +102,13 @@ PR Visual Recap 是一个 GitHub 操作，它将每个拉取请求转变为**可
 npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-这将安装 `visual-plan` 技能（其中包括操作运行的 `visual-recap` 技能）并将 `.github/workflows/pr-visual-recap.yml` 写入您的存储库。工作流程通过 `npx @agent-native/core@latest recap <subcommand>` 调用**发布的 CLI 子命令** — 包括 `gate`、`collect-diff`、`block-reference`、`scan`、`build-prompt`、`publish`、`shot`、`comment`、`check` 和`usage` - 因此没有任何内容作为帮助程序脚本复制到您的存储库中。 `setup`和`doctor`是您本地运行的交互式助手； `gate` 是工作流程在每次回顾之前运行的安全门步骤。
+这将安装 `visual-plan` 技能（其中包括操作运行的 `visual-recap` 技能）并将 `.github/workflows/pr-visual-recap.yml` 写入您的存储库。工作流程通过 `npx @agent-native/recap-cli@latest recap <subcommand>` 调用**发布的 CLI 子命令** — 包括 `gate`、`collect-diff`、`block-reference`、`scan`、`build-prompt`、`publish`、`shot`、`comment`、`check` 和`usage` - 因此没有任何内容作为帮助程序脚本复制到您的存储库中。 `setup`和`doctor`是您本地运行的交互式助手； `gate` 是工作流程在每次回顾之前运行的安全门步骤。
 
 然后运行引导设置帮助程序：
 
 ```bash
-npx @agent-native/core@latest recap setup
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 `recap setup`刷新工作流程，使用`gh`设置GitHub Actions
@@ -118,7 +118,7 @@ npx @agent-native/core@latest recap doctor
 生成的工作流程文件并打开 PR 以查看其运行。
 
 默认情况下，工作流程根据最新捆绑的内容构建其代理提示
-`@agent-native/core@latest` 中的 `visual-recap` 指导，包括任何同级
+`@agent-native/recap-cli@latest` 中的 `visual-recap` 指导，包括任何同级
 技能附带的参考文件。如果您的存储库有意定制并且
 固定其提交的`visual-recap`文件夹，设置存储库变量
 `VISUAL_RECAP_SKILL_SOURCE=repo`.
@@ -135,8 +135,8 @@ npx @agent-native/core@latest recap doctor
 JSON 引号是必需的。此值选择完整 `recap` 作业的运行器。若要在引导设置期间进行配置，请将相同的 JSON 值传给 `--runs-on`，然后使用 `doctor` 验证工作流程和运行器可用性：
 
 ```bash
-npx @agent-native/core@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 轻量级门禁单独使用 `ubuntu-latest`。禁用 GitHub 托管运行器的存储库可以将 `VISUAL_RECAP_GATE_RUNS_ON` 设置为一个不含 JSON 的纯文本标签，或使用 `--gate-runs-on visual-recap-gate`。自定义标签仅用于同一存储库中身份为 `OWNER`、`MEMBER` 或 `COLLABORATOR` 的作者；分支及其他作者会被强制使用 `ubuntu-latest`，在禁用 GitHub 托管运行器时可能一直无法调度。请使用专用且最好是临时的运行器；标准门禁不会检出 PR 树，只评估工作流逻辑和 PR 元数据。
@@ -160,12 +160,30 @@ npx @agent-native/core@latest recap doctor
 
 除了后端之外，两个存储库变量还可以调整代理的运行方式：
 
-- **`VISUAL_RECAP_MODEL`** 固定传递给 CLI (`--model`) 的模型 — 例如 `gpt-5.6-sol` 用于 Codex，或 Claude 模型 ID。保留其未设置以使用 CLI 自己的默认模型。
+- **`VISUAL_RECAP_MODEL`** 固定传递给 CLI (`--model`) 的模型 — 例如 Codex 使用 `gpt-5.6-luna`、Claude 模型 ID，或 DeepSeek 使用 `deepseek-chat`。对于 `openai-compatible` 是必需的。对于 **Claude** 后端，保留未设置现在默认使用 `claude-sonnet-5`；要使用其他 Claude 模型（例如更便宜的 `claude-haiku-4-5`），请显式设置该变量。对于 **Codex** 后端，保留未设置将使用 Codex CLI 自身的默认模型。
 - **`VISUAL_RECAP_REASONING`** 设置推理深度：`none`、`minimal`、`low`、`medium`、`high` 或 `xhigh`。适用于Codex后端； Claude 的推理是模型驱动的，因此该变量被忽略。
 - **`VISUAL_RECAP_SKILL_SOURCE`** 控制提示新鲜度：`auto`/unset 使用最新的捆绑技能指南，而 `repo` 固定到已提交的存储库本地 `visual-recap` 技能文件夹。
 
 例如，要在 Codex 和 GPT-5.6 Sol 上以高推理运行回顾，请设置存储库变量 `VISUAL_RECAP_AGENT=codex`、`VISUAL_RECAP_MODEL=gpt-5.6-sol` 和 `VISUAL_RECAP_REASONING=high`。
 
+## 成本
+
+每次回顾运行都是一次完整的代理式编码代理会话，读取真实的 diff，而不是廉价的模板化摘要，因此其成本取决于模型选择和运行频率：
+
+- **每次 PR 推送都会运行完整会话。** 默认触发器在 `synchronize` 时触发，因此被推送十次的 PR 会运行代理十次。
+- **每次都是整个 PR**，而不仅仅是自上次运行以来的提交 — 成本随 PR 总大小而不是增量差异大小扩展。
+- **差异输入上限约为 600KB。** 这限制了每次运行的最坏情况，但大差异的成本仍然明显高于小差异。
+- **失败时自动重试一次**，这可能会使一次瞬时失败的运行成本大约翻倍。
+
+要降低成本：
+
+- **固定使用更便宜的模型。** 对于 Claude，为简单或小型仓库设置 `VISUAL_RECAP_MODEL=claude-haiku-4-5` — 这是最便宜的 Claude 层级；`claude-sonnet-5`（默认值）是均衡层级。
+- **切换到使用更便宜模型的 Codex。** 设置 `VISUAL_RECAP_AGENT=codex` 并配合 `VISUAL_RECAP_MODEL=gpt-5.6-luna`（最便宜的 GPT-5.6 层级）或 `gpt-5.6-terra`（中间层级），并设置 `VISUAL_RECAP_REASONING=low` 以进一步减少推理 token 花费。推理深度仅适用于 Codex。
+- **指向更便宜的 OpenAI 兼容提供商。** 设置 `VISUAL_RECAP_AGENT=openai-compatible`，并配合指向 DeepSeek、Kimi 或任何其他 OpenAI 兼容端点的 `VISUAL_RECAP_BASE_URL`/`VISUAL_RECAP_MODEL`/`VISUAL_RECAP_API_KEY`。
+- **减少回顾频率。** 将已安装工作流的 `on.pull_request.types` 从 `[opened, synchronize, reopened, ready_for_review, closed]` 编辑为 `[opened, ready_for_review, closed]`，使其仅在 PR 打开和合并时回顾，而不是每次推送都回顾。
+
+每次运行都会记录实际花费：工作流的 `recap usage` 步骤会将 token 和成本使用情况附加到已发布的计划中，因此你可以查看每次运行的实际花费，而不是靠猜测。
+
 ## 秘密和变量
 
 在存储库的 **设置 → 秘密和变量 → Actions** 中设置这些内容。
@@ -196,11 +214,11 @@ npx @agent-native/core@latest connect https://plan.agent-native.com --service-to
 
 **Solo：个人代币仍然有效。**用 `npx @agent-native/core@latest connect` 铸造它
 针对您的计划应用程序。对于托管应用程序，这还会写入本地
-`npx @agent-native/core@latest recap setup`可以读取的发布令牌文件：
+`npx @agent-native/recap-cli@latest recap setup`可以读取的发布令牌文件：
 
 ```bash
 npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
-npx @agent-native/core@latest recap setup
+npx @agent-native/recap-cli@latest recap setup
 ```
 
 如果您更喜欢手动设置，请将令牌粘贴到 GitHub 密钥中。使用
@@ -209,16 +227,16 @@ npx @agent-native/core@latest recap setup
 
 ### 可选（仅当您更改默认值时）
 
-| 秘密/变量                | 默认                            | 当你需要的时候                                                                                                               |
-| ------------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `OPENAI_API_KEY`         | —                               | 秘密。与 `VISUAL_RECAP_AGENT=codex` 一起设置以使用 Codex 运行回顾。                                                          |
-| `VISUAL_RECAP_AGENT`     | `claude`                        | 变量。选择编码代理后端（`claude` 或 `codex`）。                                                                              |
-| `VISUAL_RECAP_MODEL`     | 每个CLI的默认值                 | 变量。固定模型 - 例如`gpt-5.6-sol` 表示 Codex，或 Claude 型号 ID。取消设置使用 CLI 自己的默认值。                            |
-| `VISUAL_RECAP_REASONING` | 每个模型的默认值                | 变量。推理深度：`none`、`minimal`、`low`、`medium`、`high` 或 `xhigh`。适用于Codex后端。                                     |
-| `RECAP_CLI_VERSION`      | `latest`                        | 变量。固定工作流程安装的 `@agent-native/core` CLI 版本 - 例如`1.5.0`。参见[Version pinning](#version-pinning-copy-variant)。 |
-| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | 秘密。仅当在不同来源自行托管计划应用时。                                                                                     |
+| 秘密/变量                | 默认                                        | 当你需要的时候                                                                                                                                                                                                       |
+| ------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                                           | 秘密。与 `VISUAL_RECAP_AGENT=codex` 一起设置以使用 Codex 运行回顾。                                                                                                                                                  |
+| `VISUAL_RECAP_AGENT`     | `claude`                                    | 变量。选择编码代理后端（`claude` 或 `codex`）。                                                                                                                                                                      |
+| `VISUAL_RECAP_MODEL`     | Claude 使用 `claude-sonnet-5`；兼容后端必需 | 变量。OpenAI 兼容后端的提供商模型 ID（在该后端为必需）。对于 Claude，未设置时现在默认使用 `claude-sonnet-5` — 设置以覆盖，例如使用最便宜层级的 `claude-haiku-4-5`。对于 Codex，未设置时使用 Codex CLI 自身的默认值。 |
+| `VISUAL_RECAP_REASONING` | 每个模型的默认值                            | 变量。推理深度：`none`、`minimal`、`low`、`medium`、`high` 或 `xhigh`。适用于Codex后端。                                                                                                                             |
+| `RECAP_CLI_VERSION`      | `latest`                                    | 变量。固定工作流程安装的 `@agent-native/recap-cli` CLI 版本 - 例如`1.5.0`。参见[Version pinning](#version-pinning-copy-variant)。                                                                                    |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com`             | 秘密。仅当在不同来源自行托管计划应用时。                                                                                                                                                                             |
 
-工作流自动检测如何调用其助手 CLI（此 monorepo 内的本地源，在其他地方发布的 `@agent-native/core`），因此无需设置 `RECAP_CLI` 变量。
+工作流自动检测如何调用其助手 CLI（此 monorepo 内的本地源，在其他地方发布的 `@agent-native/recap-cli`），因此无需设置 `RECAP_CLI` 变量。
 
 ## 评论内嵌截图
 
@@ -357,9 +375,9 @@ GitHub 操作专为托管、可共享的 PR 审核而设计。如果你想要一
 相同的帮助程序在本地文件模式下本地流动：
 
 ```bash
-npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
-npx @agent-native/core@latest recap scan --diff recap.diff
-npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+npx @agent-native/recap-cli@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/recap-cli@latest recap scan --diff recap.diff
+npx @agent-native/recap-cli@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
 ```
 
 将生成的 `recap-prompt.md` 交给您的编码代理。在本地文件模式
@@ -389,7 +407,7 @@ npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap -
 
 ## 版本固定（复制变体） {#version-pinning-copy-variant}
 
-默认情况下，复制变体工作流程在运行时安装 `@agent-native/core@latest`，因此每次回顾运行都会自动选择最新的 CLI。如果您的 CI 需要可重现的工具，请设置 **`RECAP_CLI_VERSION`** 存储库变量来固定已安装的版本：
+默认情况下，复制变体工作流程在运行时安装 `@agent-native/recap-cli@latest`，因此每次回顾运行都会自动选择最新的 CLI。如果您的 CI 需要可重现的工具，请设置 **`RECAP_CLI_VERSION`** 存储库变量来固定已安装的版本：
 
 1. 转到您的存储库的**设置 → 秘密和变量 → Actions → 变量**。
 2. 创建一个名为 `RECAP_CLI_VERSION` 的变量，其值类似于 `1.5.0`。
@@ -400,7 +418,7 @@ npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap -
 
 ## 秘密扫描白名单
 
-在发布回顾之前，工作流程运行 `npx @agent-native/core@latest recap scan` 以检测差异中可能的秘密。任何其 diff 与已知秘密模式匹配的 PR 都会被阻止并带有解释性注释 - 不会发布摘要，并且不会将 diff 内容发送到编码代理。
+在发布回顾之前，工作流程运行 `npx @agent-native/recap-cli@latest recap scan` 以检测差异中可能的秘密。任何其 diff 与已知秘密模式匹配的 PR 都会被阻止并带有解释性注释 - 不会发布摘要，并且不会将 diff 内容发送到编码代理。
 
 在极少数情况下，存储库具有故意的测试装置或表面上类似于秘密模式的非秘密字符串（例如，测试文件中的装置密钥）。要抑制误报，请在存储库的根目录中创建 `.github/recap-scan-allowlist`。
 
@@ -434,7 +452,7 @@ EXAMPLE_API_KEY=placeholder-value
 
 ### 为什么使用可重用变体？
 
-默认安装程序将完整的约 360 行工作流程 YAML 复制到您的存储库中（**复制**选项）。对于气隙存储库或需要审核每一行运行内容的存储库来说，这是正确的选择。缺点是错误修复和改进永远不会到达您的手中 - 您需要在每次发布后手动重新运行 `npx @agent-native/core@latest recap setup`。
+默认安装程序将完整的约 360 行工作流程 YAML 复制到您的存储库中（**复制**选项）。对于气隙存储库或需要审核每一行运行内容的存储库来说，这是正确的选择。缺点是错误修复和改进永远不会到达您的手中 - 您需要在每次发布后手动重新运行 `npx @agent-native/recap-cli@latest recap setup`。
 
 **可重用**选项改为编写一个精简的约 20 行调用程序。它通过`uses:`委托给`BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml`。当工作流程运行时，每个调用者都会自动获取最新逻辑，无需本地更新。
 
@@ -447,7 +465,7 @@ EXAMPLE_API_KEY=placeholder-value
 
 ### 调用者片段
 
-这是`npx @agent-native/core@latest recap setup --reusable`写的（或者你可以手动粘贴）：
+这是`npx @agent-native/recap-cli@latest recap setup --reusable`写的（或者你可以手动粘贴）：
 
 ```yaml
 name: PR Visual Recap
@@ -482,7 +500,7 @@ jobs:
       skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
       runs-on: ${{ vars.VISUAL_RECAP_RUNS_ON || '"ubuntu-latest"' }}
       gate-runs-on: ${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}
-      # cli-version: "latest"  # pin to a specific @agent-native/core version
+      # cli-version: "latest"  # pin to a specific @agent-native/recap-cli version
 ```
 
 适用 [Secrets and variables](#secrets-and-variables) 中描述的相同秘密和变量。可复用调用方将完整作业的 `VISUAL_RECAP_RUNS_ON` 转发为 `runs-on`，并将门禁的 `VISUAL_RECAP_GATE_RUNS_ON` 转发为单标签 `gate-runs-on`。省略时两者都使用 `ubuntu-latest`。
@@ -491,15 +509,15 @@ jobs:
 
 ```bash
 # 编写瘦调用者而不是完整副本：
-npx @agent-native/core@latest recap setup --reusable
+npx @agent-native/recap-cli@latest recap setup --reusable
 
 # 或者使用固定参考来实现可重复性：
-npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+npx @agent-native/recap-cli@latest recap setup --reusable --ref v1.2.3
 ```
 
 两种变体都将工作流程写入 `.github/workflows/pr-visual-recap.yml`。如果现有工作流程已存在且有所不同，则该命令会拒绝并告诉您传递 `--force` 进行覆盖。
 
-写入后，照常运行 `npx @agent-native/core@latest recap doctor` 以确认机密已配置。
+写入后，照常运行 `npx @agent-native/recap-cli@latest recap doctor` 以确认机密已配置。
 
 ### 版本固定
 
@@ -509,7 +527,7 @@ npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
 uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
 ```
 
-`cli-version` 输入控制工作流程中运行的 `@agent-native/core` CLI 版本 - 将其保留在 `"latest"` 以跟踪最新版本，或将其固定到版本字符串（例如 `"1.5.0"`）以实现完全可重复性。
+`cli-version` 输入控制工作流程中运行的 `@agent-native/recap-cli` CLI 版本 - 将其保留在 `"latest"` 以跟踪最新版本，或将其固定到版本字符串（例如 `"1.5.0"`）以实现完全可重复性。
 
 ### workflow_call事件上下文
 

package/docs/content/locales/zh-CN/template-plan.mdx

@@ -208,6 +208,13 @@ vscode://builder.agent-native/open?url=<encoded-plan-url>
 **开放式问题**表格位于同一计划的底部。接听并发送
 它向代理启动针对现有计划的修订。
 
+## 成本和模型选择
+
+生成计划或回顾会对你的编码代理的 LLM 运行一次完整的代理式会话，而不是轻量级的模板填充，因此成本会随 diff 或计划的大小以及你选择的模型而变化。
+
+- 应用自身的默认聊天模型是 Sonnet 5；你可以随时在 **设置** 中更改它。Haiku 是更便宜的 Claude 选项，Luna 是 GPT-5.6 系列中更便宜的选项。
+- 来自 GitHub Action 的自动化 PR 回顾与交互式应用分开运行，拥有自己的模型和成本调节项 — 关于 `VISUAL_RECAP_MODEL`、`VISUAL_RECAP_AGENT` 和 `VISUAL_RECAP_REASONING`，请参见[PR Visual Recap](/docs/pr-visual-recap)。
+
 ## 你可以用它做什么
 
 - **实施前审查。** React 到图表、线框图、选项选项卡，