@agent-native/core 0.100.2 → 0.101.2

package/corpus/core/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/corpus/core/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 到图表、线框图、选项选项卡，

package/corpus/core/docs/content/locales/zh-TW/pr-visual-recap.mdx

@@ -102,13 +102,13 @@ PR Visual Recap 是一個 GitHub 操作，它將每個 pull request 轉變為**
 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/corpus/core/docs/content/locales/zh-TW/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 到圖表、線框圖、選項分頁，