@hifullmoon/aicommit 2.4.1 → 2.5.0

package/.aicommit.config.example.json

@@ -144,6 +144,12 @@
     "chunkInputTokens": 12000,
     "maxTotalTokens": 200000,
     "concurrency": 2,
-    "timeoutMs": 180000
+    "timeoutMs": 180000,
+    "cache": {
+      "enabled": true,
+      "ttlMs": 86400000,
+      "maxBytes": 33554432,
+      "allowUnprotected": false
+    }
   }
 }

package/CHANGELOG.md

@@ -4,6 +4,17 @@ This file lists notable user-facing changes. Internal refactors, test-only chang
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-09-10
+
+### Added
+
+- Added short-lived, content-addressed recovery caching for validated `deep` analysis chunks so identical snapshots resume after failures without repeating completed provider requests.
+
+### Fixed
+
+- Packed `deep` analysis fragments using the configured token estimate instead of character counts, avoiding unnecessary requests and premature aggregate-budget failures for ASCII-heavy diffs.
+- Large split plans now preflight deep-analysis and downstream planning cost, batch local candidates hierarchically, and offer one complete conservative plan when the bounded budget cannot finish. Non-interactive committing requires the explicit `--allow-single-fallback` opt-in.
+
 ## [2.4.1] - 2026-09-10
 
 ### Fixed
@@ -206,7 +217,8 @@ This file lists notable user-facing changes. Internal refactors, test-only chang
 - Added file-level split planning and execution with Git-state concurrency checks.
 - Added provider presets and user/project configuration boundaries.
 
-[Unreleased]: https://github.com/hi-fullmoon/AICommit/compare/v2.4.1...HEAD
+[Unreleased]: https://github.com/hi-fullmoon/AICommit/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.5.0
 [2.4.1]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.4.1
 [2.4.0]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.4.0
 [2.3.0]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.3.0

package/README.md

@@ -197,6 +197,7 @@ This is the only supported user-config shape. Earlier flat or provider-level `mo
 | `maxFileDiffChars`   | Target per-file fragment size; remaining content is analyzed in subsequent chunks (default: `3000`)                                                                                                                          |
 | `splitMaxDiffChars`  | Context character budget for each split-planning request (default: `16000`)                                                                                                                                                  |
 | `splitMaxPlanFiles`  | Files or candidate groups per planning request; larger changes use hierarchical planning (default: `100`)                                                                                                                    |
+| `largeChange`        | Large-change strategy, budgets, and short-lived chunk recovery cache; personal config only, retaining protected summaries for 24 hours up to 32 MiB by default                                                               |
 | `diffContextLines`   | Context lines around each diff hunk (`git diff --unified=<n>`); lower values mean fewer tokens (default: `1`)                                                                                                                |
 | `stripFiles`         | Extra files to stub out of the diff like lock files, matched by basename with `*`/`?` wildcards, e.g. `["*.min.js", "*.map", "*.snap"]` (default: `[]`; project-level entries are merged with user-level ones, not replaced) |
 | `regenerateWithDiff` | `true` re-sends the full diff on every regenerate for more varied rewrites; `false` (default) only asks the model to reword its previous message, which is far cheaper                                                       |
@@ -311,6 +312,7 @@ aicommit split --dry-run # review a split plan without creating commits
 aicommit --yes           # non-interactively commit already staged changes
 aicommit --yes --dry-run # non-interactively preview all changes; restores staging
 aicommit split --scope=all --yes # non-interactively plan and commit all working-tree changes
+aicommit split --scope=all --yes --allow-single-fallback # explicitly permit a conservative fallback commit
 aicommit split plan --scope=staged --file=/tmp/split-plan.json --yes
 aicommit split apply --file=/tmp/split-plan.json --yes
 aicommit split resume --yes # resume an interrupted split transaction
@@ -324,20 +326,21 @@ aicommit --yes --output=json # emit one schema-validated JSON result on stdout
 aicommit -h              # help
 ```
 
-| Option             | Description                                                                  |
-| ------------------ | ---------------------------------------------------------------------------- |
-| `-l`, `--lang`     | Commit message language (`zh` or `en`)                                       |
-| `-p`, `--provider` | Use the named provider from `providers`                                      |
-| `-m`, `--model`    | Use a named model profile from the selected provider                         |
-| `--scope`          | `staged` or `all` scope for `aicommit split` and `aicommit split plan`       |
-| `--file`           | JSON plan path for `aicommit split plan` and `aicommit split apply`          |
-| `--dry-run`        | Generate and review a message or split plan without creating commits         |
-| `-y`, `--yes`      | Accept without prompts; normal mode requires explicitly staged changes       |
-| `--reasoning`      | Enable reasoning with `low`, `medium`, `high`, `xhigh`, or `max` effort      |
-| `--no-reasoning`   | Explicitly disable reasoning when the selected provider/model supports it    |
-| `--output`         | `text` (default) or one JSON object; commit/split JSON flows require `--yes` |
-| `-v`, `--version`  | Show version                                                                 |
-| `-h`, `--help`     | Show help                                                                    |
+| Option                    | Description                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `-l`, `--lang`            | Commit message language (`zh` or `en`)                                         |
+| `-p`, `--provider`        | Use the named provider from `providers`                                        |
+| `-m`, `--model`           | Use a named model profile from the selected provider                           |
+| `--scope`                 | `staged` or `all` scope for `aicommit split` and `aicommit split plan`         |
+| `--file`                  | JSON plan path for `aicommit split plan` and `aicommit split apply`            |
+| `--dry-run`               | Generate and review a message or split plan without creating commits           |
+| `-y`, `--yes`             | Accept without prompts; normal mode requires explicitly staged changes         |
+| `--allow-single-fallback` | Explicitly permit non-interactive split to create one complete fallback commit |
+| `--reasoning`             | Enable reasoning with `low`, `medium`, `high`, `xhigh`, or `max` effort        |
+| `--no-reasoning`          | Explicitly disable reasoning when the selected provider/model supports it      |
+| `--output`                | `text` (default) or one JSON object; commit/split JSON flows require `--yes`   |
+| `-v`, `--version`         | Show version                                                                   |
+| `-h`, `--help`            | Show help                                                                      |
 
 ### Configuration inspection
 
@@ -478,7 +481,7 @@ The default `largeChange.strategy: "auto"` inventories every file locally, group
 
 A normal commit typically needs one model request, with no per-file AI calls or recursive model reduction. The inventory contains at most 16 representative groups under a UTF-8 byte budget, prioritizing coverage across code, configuration, tests, and other categories. It explicitly describes sampling limits. Both terminal and JSON output distinguish fully analyzed files, representative excerpts, and metadata-only files. Provider retries, response recovery, policy correction, and user-requested regeneration can still add requests.
 
-Split mode builds local candidates and plans them in one model request. The complete candidate inventory must fit `splitMaxPlanFiles` and the input budget; otherwise it stops before calling the provider and suggests staging a smaller logical change or explicitly selecting deep analysis. File membership is still validated completely, with no automatic catch-all commits. Small changes keep the existing request path.
+Split mode builds local candidates and sends them in bounded batches of at most `splitMaxPlanFiles`, then merges the batch plans hierarchically. Every file remains represented even when the complete candidate inventory cannot fit one request. If `deep` analysis exhausts its aggregate budget or the hierarchy cannot converge, interactive and dry-run flows produce one conservative all-files plan with an explicit warning instead of using incomplete model output. Non-interactive committing stops unless `--allow-single-fallback` explicitly authorizes that degradation. Small changes keep the existing request path.
 
 For exhaustive chunk-by-chunk model analysis, opt in through personal configuration:
 
@@ -489,11 +492,17 @@ For exhaustive chunk-by-chunk model analysis, opt in through personal configurat
     "chunkInputTokens": 12000,
     "maxTotalTokens": 200000,
     "concurrency": 2,
-    "timeoutMs": 180000
+    "timeoutMs": 180000,
+    "cache": {
+      "enabled": true,
+      "ttlMs": 86400000,
+      "maxBytes": 33554432,
+      "allowUnprotected": false
+    }
   }
 }
 ```
 
-`deep` spends more requests and tokens, with a maximum of 256 requests. Repository configuration cannot change this personal strategy or raise the spending budget. Both strategies use conservative token estimates; missing usage retains the reservation. Retries, reduction, planning, and final generation share the budget. Budget exhaustion or invalid groups stop execution without automatically committing incomplete results.
+`deep` spends more requests and tokens, with a maximum of 256 requests. Before dispatch, a preflight estimate covers initial chunks, required reductions, and the minimum hierarchical planning tree; an impossible deep run switches to the local inventory path, and validated cache hits are excluded from that estimate. Validated initial fact chunks are stored briefly under Git metadata, reused when the same snapshot is retried after failure or interruption, and removed after complete generation succeeds. The cache does not directly store captured diffs, reasoning, credentials, or complete provider responses; it stores model summaries that may contain code-derived details. Unprotected original input is not persisted unless personal configuration explicitly enables `allowUnprotected`. Repository configuration cannot change this personal strategy, enable unprotected caching, or raise spending/cache ceilings. Both strategies use conservative token estimates; cache hits consume no request or token budget. Incomplete model output is never committed: budget/capacity fallback is a new complete plan containing every reviewed file; interactive runs show it for review, while non-interactive committing requires `--allow-single-fallback`.
 
-Complete patches and larger untracked text are captured in local temporary files, with descriptors opened only during reads and writes. Files are cleaned on normal exit or cancellation; crashes may leave them behind. Content reads are bounded. Lines exceeding 1 MiB, independent groups that cannot fit a global planning budget, and experimental hunk planning for large changes fail explicitly.
+Complete patches and larger untracked text are captured in local temporary files, with descriptors opened only during reads and writes. Files are cleaned on normal exit or cancellation; crashes may leave them behind. Content reads are bounded. Lines exceeding 1 MiB and experimental hunk planning for large changes fail explicitly; file-level planning capacity uses the complete conservative fallback.

package/README.zh-CN.md

@@ -199,6 +199,7 @@ aicommit -p deepseek -m reasoner
 | `maxFileDiffChars`   | 单文件正文分块参考大小；剩余内容继续分析（默认：`3000`）                                                                              |
 | `splitMaxDiffChars`  | 每次批次规划的上下文字符预算（默认：`16000`）                                                                                         |
 | `splitMaxPlanFiles`  | 每次规划的文件或候选组数量上限；超限分层规划（默认：`100`）                                                                           |
+| `largeChange`        | 大变更策略、预算和短期分块恢复缓存；缓存只接受个人配置，默认保留受保护摘要 24 小时、最多 32 MiB                                       |
 | `diffContextLines`   | 每个 diff hunk 周围的上下文行数（`git diff --unified=<n>`）；越小越节省 token（默认：`1`）                                            |
 | `stripFiles`         | 额外替换为占位的文件，按 basename 使用 `*` / `?` 通配，如 `["*.min.js", "*.map", "*.snap"]`（默认：`[]`；项目项与用户项合并而非覆盖） |
 | `regenerateWithDiff` | `true` 表示每次重写都重发完整 diff，以获得更多变化；`false`（默认）只要求模型改写上一条消息，成本更低                                 |
@@ -313,6 +314,7 @@ aicommit split --dry-run # 审阅拆分计划，但不创建提交
 aicommit --yes           # 非交互提交已明确暂存的变更
 aicommit --yes --dry-run # 非交互预览所有变更；退出时恢复暂存状态
 aicommit split --scope=all --yes # 非交互规划并提交所有工作区变更
+aicommit split --scope=all --yes --allow-single-fallback # 明确允许规划预算耗尽后的保守提交
 aicommit split plan --scope=staged --file=/tmp/split-plan.json --yes
 aicommit split apply --file=/tmp/split-plan.json --yes
 aicommit split resume --yes # 恢复中断的拆分事务
@@ -326,20 +328,21 @@ aicommit --yes --output=json # 向 stdout 输出一个通过 schema 校验的 JS
 aicommit -h              # 帮助
 ```
 
-| 选项               | 说明                                                                |
-| ------------------ | ------------------------------------------------------------------- |
-| `-l`, `--lang`     | 提交信息语言：`zh` 或 `en`                                          |
-| `-p`, `--provider` | 使用 `providers` 中的命名 Provider                                  |
-| `-m`, `--model`    | 使用所选 Provider 下的命名模型配置                                  |
-| `--scope`          | `aicommit split` 和 `aicommit split plan` 的范围：`staged` 或 `all` |
-| `--file`           | `aicommit split plan` 和 `aicommit split apply` 的 JSON 计划路径    |
-| `--dry-run`        | 生成并审阅消息或拆分计划，但不创建提交                              |
-| `-y`, `--yes`      | 不提示直接接受；普通模式要求变更已明确暂存                          |
-| `--reasoning`      | 启用推理，可选强度：`low`、`medium`、`high`、`xhigh` 或 `max`       |
-| `--no-reasoning`   | 所选 Provider / 模型支持时显式关闭推理                              |
-| `--output`         | `text`（默认）或单个 JSON 对象；提交 / 拆分的 JSON 流程要求 `--yes` |
-| `-v`, `--version`  | 显示版本                                                            |
-| `-h`, `--help`     | 显示帮助                                                            |
+| 选项                      | 说明                                                                |
+| ------------------------- | ------------------------------------------------------------------- |
+| `-l`, `--lang`            | 提交信息语言：`zh` 或 `en`                                          |
+| `-p`, `--provider`        | 使用 `providers` 中的命名 Provider                                  |
+| `-m`, `--model`           | 使用所选 Provider 下的命名模型配置                                  |
+| `--scope`                 | `aicommit split` 和 `aicommit split plan` 的范围：`staged` 或 `all` |
+| `--file`                  | `aicommit split plan` 和 `aicommit split apply` 的 JSON 计划路径    |
+| `--dry-run`               | 生成并审阅消息或拆分计划，但不创建提交                              |
+| `-y`, `--yes`             | 不提示直接接受；普通模式要求变更已明确暂存                          |
+| `--allow-single-fallback` | 明确允许非交互拆分创建一个覆盖完整变更的保守提交                    |
+| `--reasoning`             | 启用推理，可选强度：`low`、`medium`、`high`、`xhigh` 或 `max`       |
+| `--no-reasoning`          | 所选 Provider / 模型支持时显式关闭推理                              |
+| `--output`                | `text`（默认）或单个 JSON 对象；提交 / 拆分的 JSON 流程要求 `--yes` |
+| `-v`, `--version`         | 显示版本                                                            |
+| `-h`, `--help`            | 显示帮助                                                            |
 
 ### 配置检查
 
@@ -480,7 +483,7 @@ exec zsh
 
 普通提交通常只需要一次模型请求，不会为每个文件调用 AI，也不会递归调用模型汇总。摘要最多包含 16 个代表组，并受 UTF-8 字节预算约束；优先覆盖代码、配置和测试等不同类别。摘要明确说明抽样范围，界面和 JSON 分别报告全文分析、代表片段和仅元数据的文件数，不把抽样视为完整理解。提供方重试、响应恢复、格式修正和用户重新生成仍可能增加请求。
 
-批次提交先在本地建立候选组，再用一次模型请求规划。只有完整候选清单能放入 `splitMaxPlanFiles` 和输入预算时才请求模型；否则在请求前停止，提示暂存更小的逻辑变更或显式选择深度分析。所有文件的归属仍进行完整性校验，不会因数量过多生成兜底提交。小变更保持原有请求路径。
+批次提交先在本地建立候选组，再按每批最多 `splitMaxPlanFiles` 个候选发送，并分层合并各批计划；完整候选清单放不进一次请求时，仍会保留每个文件。如果 `deep` 分析耗尽总预算，或分层规划无法收敛，交互和 dry-run 流程会明确警告并生成一个覆盖全部文件的保守计划，而不会采用不完整的模型结果；非交互提交默认停止，只有显式传入 `--allow-single-fallback` 才允许该降级。小变更保持原有请求路径。
 
 确实需要逐块 AI 分析时，在个人配置中设置：
 
@@ -491,11 +494,17 @@ exec zsh
     "chunkInputTokens": 12000,
     "maxTotalTokens": 200000,
     "concurrency": 2,
-    "timeoutMs": 180000
+    "timeoutMs": 180000,
+    "cache": {
+      "enabled": true,
+      "ttlMs": 86400000,
+      "maxBytes": 33554432,
+      "allowUnprotected": false
+    }
   }
 }
 ```
 
-`deep` 会增加请求和 token 消耗，最多 256 次请求。仓库配置不能切换这项个人策略或提高费用预算。两种策略均使用保守 token 估算，未知 usage 按预留额度计入；重试、汇总、规划和消息生成共用预算。超限或无效分组会停止，不自动提交不完整结果。
+`deep` 会增加请求和 token 消耗，最多 256 次请求。请求前会预估初始分块、必要归并和最小分层规划树的成本；确定无法装入总预算时直接切换到本地清单路径，已验证的缓存命中不计入这次预估。通过完整校验的初始事实分块会短期写入 Git 元数据目录；同一快照失败或中断后重试时直接复用，完整生成成功后清理。缓存不直接保存捕获的 diff、推理、凭据或完整 Provider 响应，只保存可能包含代码派生细节的模型摘要；选择发送未保护的原始内容时默认不落盘，只有个人配置显式设置 `allowUnprotected: true` 才允许。仓库配置不能切换策略、启用未保护缓存或提高费用与缓存上限。两种策略均使用保守 token 估算，未知 usage 按预留额度计入；缓存命中不计请求或 token。模型的不完整输出永远不会被提交：预算或容量降级会重新生成一个包含全部已审核文件的完整计划；交互模式先展示确认，非交互提交则要求 `--allow-single-fallback`。
 
-完整补丁及较大未跟踪文本暂存到本地临时文件，只在读写时打开文件句柄，正常结束或取消时清理；异常崩溃可能遗留临时文件。正文读取有界。单行超过 1 MiB、无法在预算内合并的独立分组，以及大变更的实验性 hunk 规划会明确报错。
+完整补丁及较大未跟踪文本暂存到本地临时文件，只在读写时打开文件句柄，正常结束或取消时清理；异常崩溃可能遗留临时文件。正文读取有界。单行超过 1 MiB 和大变更的实验性 hunk 规划会明确报错；文件级规划容量不足时使用覆盖完整变更的保守回退。

package/docs/distribution.md

@@ -33,7 +33,7 @@ The release workflow uses npm Trusted Publishing without a long-lived `NPM_TOKEN
 ```bash
 workdir=$(mktemp -d)
 cd "$workdir"
-npm install --package-lock-only @hifullmoon/aicommit@2.4.1
+npm install --package-lock-only @hifullmoon/aicommit@2.5.0
 npm audit signatures
 ```
 

package/docs/large-change-implementation-plan.md

@@ -112,7 +112,7 @@
 - [ ] 本地展开组 ID 到文件路径，校验完整覆盖、唯一归属及合法引用，替换超额文件兜底提交。
 - [ ] 为最终分组生成消息，复用已有分析；大量分组的消息生成也纳入总预算。
 - [ ] 未解决归属显示为待处理项，允许在现有审阅中调整；未解决前不执行、不导出可执行计划。
-- [ ] 非交互模式遇不完整分析或非法分组，在自动暂存前失败。
+- [ ] 非交互模式绝不采用不完整分析或非法模型分组；确定性的预算/容量耗尽只有在显式允许单提交降级时才使用覆盖全部文件的保守计划，其余情况在自动暂存前失败。
 - [ ] 继续生成现有 split plan 工件，由已有 apply / checkpoint / resume 流程执行；内部分析 ID 不改变外部路径语义。
 - [ ] 验证实验性 hunk 归属和跨块片段映射；无法处理时给出明确错误。
 
@@ -136,18 +136,18 @@
 
 使用临时仓库和模拟 Provider 构造测试，不把巨型 fixture 提交到仓库。确定性测试验证边界和完整性，语义评估单独记录，不用字符串快照冒充摘要质量验证。
 
-| 场景                                  | 必须验证                                   |
-| ------------------------------------- | ------------------------------------------ |
-| 普通小提交                            | 一次生成请求，已有消息策略和交互保持兼容   |
-| 10,000 个小文件                       | 全量清单完整，请求有界；预算不足时正确停止 |
-| 超过 64 MiB 的源码补丁                | 流式读取、指纹校验与内存规模符合预期       |
-| 巨型 hunk、超长单行                   | 不导致超限请求或无界内存，覆盖状态诚实     |
-| 二进制、lock、生成文件、批量重命名    | 正文策略正确，路径仍完整纳入提交           |
-| 跨目录实现与测试                      | 可形成同一逻辑组，分块不强制分组           |
-| 敏感文件、未跟踪符号链接              | 保持现有保护行为，不因分块绕过             |
-| 429、响应截断、错误 ID、usage 缺失    | 重试有界、校验拒绝非法响应、预算保守记账   |
-| 超时、Ctrl+C、Git 失败、并发修改      | 清理资源、不误提交、不破坏真实 index       |
-| split 导出、apply、hook 失败与 resume | 原有工件和事务恢复兼容                     |
+| 场景                                  | 必须验证                                                     |
+| ------------------------------------- | ------------------------------------------------------------ |
+| 普通小提交                            | 一次生成请求，已有消息策略和交互保持兼容                     |
+| 10,000 个小文件                       | 全量清单完整，请求有界；预算不足时生成明确标记的完整保守计划 |
+| 超过 64 MiB 的源码补丁                | 流式读取、指纹校验与内存规模符合预期                         |
+| 巨型 hunk、超长单行                   | 不导致超限请求或无界内存，覆盖状态诚实                       |
+| 二进制、lock、生成文件、批量重命名    | 正文策略正确，路径仍完整纳入提交                             |
+| 跨目录实现与测试                      | 可形成同一逻辑组，分块不强制分组                             |
+| 敏感文件、未跟踪符号链接              | 保持现有保护行为，不因分块绕过                               |
+| 429、响应截断、错误 ID、usage 缺失    | 重试有界、校验拒绝非法响应、预算保守记账                     |
+| 超时、Ctrl+C、Git 失败、并发修改      | 清理资源、不误提交、不破坏真实 index                         |
+| split 导出、apply、hook 失败与 resume | 原有工件和事务恢复兼容                                       |
 
 - [ ] 记录峰值 RSS、总耗时、请求数、输入 / 输出 token 及覆盖情况；至少比较两个补丁体量，确认正文内存有界。
 - [ ] 记录小提交相对基线的额外耗时，测量后确定可接受阈值及最终预算默认值。
@@ -177,7 +177,7 @@
 - Git 内容使用直接写临时文件的方式捕获，Node 按 64 KiB 读取，避免同步 stdout 缓冲上限；没有引入长期运行的异步 Git 子进程。临时文件空间取决于变更大小，Git 捕获有 120 秒命令超时。
 - token 计数采用保守估算并结合 Provider 模型窗口。Provider 上下文超限明确失败，尚未实现 tokenizer 精确计数和 Provider 报错后的自动缩块。
 - 分析不完整时统一停止，不生成可直接接受的部分草稿。完整分析结果的改写继续使用现有审阅流程。
-- 批次分层规划允许合并候选组；无法收敛时要求缩小范围，不把未解决文件自动塞入兜底组。大变更不支持实验性 hunk 规划，单行超过 1 MiB 明确拒绝。
+- 批次分层规划允许合并候选组；深度分析会先预估成本，候选清单可分批并继续分层合并。预算耗尽或规划无法收敛时，不采用半份模型结果，而是明确警告并生成覆盖全部文件的单提交保守计划。大变更不支持实验性 hunk 规划，单行超过 1 MiB 明确拒绝。
 - 未新增真实 Provider 的语义质量基准；本次验证使用模拟 Provider，不能据此保证任意模型的摘要和分组质量。
 
 ### 验证结果

package/docs/privacy.md

@@ -57,6 +57,6 @@ Use `aicommit config show` to inspect effective local state without revealing cr
 
 ## Large-change snapshots / 大变更快照
 
-Default large-change analysis sends a bounded local inventory and selected protected excerpts to the configured provider, without per-file model requests. Explicit `deep` analysis sends protected fragments and intermediate factual summaries. Both local inventories and model summaries remain untrusted input. Full Git patches and larger untracked text are captured in private local temporary files, with bounded memory reads. Normal completion and Ctrl+C clean them up; an abnormal crash can leave snapshots in the system temporary directory. Summaries are reused only within the current run and are not added to JSON output or split checkpoints.
+Default large-change analysis sends a bounded local inventory and selected protected excerpts to the configured provider, without per-file model requests. Explicit `deep` analysis sends protected fragments and intermediate factual summaries. Both local inventories and model summaries remain untrusted input. Full Git patches and larger untracked text are captured in private local temporary files, with bounded memory reads. Validated initial `deep` summaries may be stored under private Git metadata for up to 24 hours so an interrupted identical snapshot can resume; entries contain generic fragment IDs and model summaries, not the captured diff, reasoning, credentials, or complete provider responses. Because summaries are derived from repository content, they may still contain code details. Successful generation removes its cache. Unprotected original input is not persisted unless the user explicitly enables `largeChange.cache.allowUnprotected` in personal configuration. Cache entries are not added to JSON output or split checkpoints.
 
-默认大变更分析向已配置 Provider 发送受限本地清单和选定的保护后片段，不逐文件调用模型。明确选择 `deep` 时才发送分块片段和中间事实摘要。本地清单和模型摘要均视为不可信输入。完整 Git 补丁和较大未跟踪文本保存在本地私有临时文件中，按块读取；正常结束及 Ctrl+C 会清理，异常崩溃可能在系统临时目录留下快照。摘要仅在本次运行中复用，不加入 JSON 输出或 split checkpoint。
+默认大变更分析向已配置 Provider 发送受限本地清单和选定的保护后片段，不逐文件调用模型。明确选择 `deep` 时才发送分块片段和中间事实摘要。本地清单和模型摘要均视为不可信输入。完整 Git 补丁和较大未跟踪文本保存在本地私有临时文件中，按块读取。通过校验的初始 `deep` 摘要可在私有 Git 元数据目录中保留最多 24 小时，让完全相同的快照在中断后续跑；缓存只含通用片段 ID 和模型摘要，不直接保存捕获的 diff、推理、凭据或完整 Provider 响应。摘要源自仓库内容，仍可能包含代码细节。完整生成成功后会删除本次缓存。未保护原始内容仅在用户通过个人配置显式启用 `largeChange.cache.allowUnprotected` 时持久化。缓存不会加入 JSON 输出或 split checkpoint。

package/docs/troubleshooting.md

@@ -36,10 +36,14 @@ If a failure remains, capture `aicommit doctor --output=json`, Node/Git versions
 
 ## Large-change limits / 大变更限制
 
-Default `auto` analysis builds a local inventory and selects bounded excerpts without model reduction calls. If a complete split candidate inventory cannot fit one request, stage a smaller logical change or explicitly choose personal `largeChange.strategy: "deep"`. Deep analysis can reach its fixed request (256) or depth (8) limits; increasing token or time budgets does not raise those limits. Token/time limits remain configurable in personal settings. Unknown model token counts use conservative estimates; an oversized request fails before dispatch, and provider-context errors are not blindly replayed.
+Default `auto` analysis builds a local inventory and selects bounded excerpts, then batches oversized split inventories and merges their plans hierarchically. Deep analysis still has fixed request (256) and depth (8) limits. If its aggregate token/time budget is exhausted or hierarchical planning cannot converge, split mode emits an explicit warning and can fall back to one complete all-files plan; it never uses a partial model plan. Interactive and dry-run flows show that plan, while non-interactive committing requires the explicit `--allow-single-fallback` option. Token/time limits remain configurable in personal settings. Unknown model token counts use conservative estimates; an oversized request is not dispatched, and provider-context errors are not blindly replayed.
 
-默认 `auto` 在本地建立清单并选择受限片段，不调用模型递归汇总。完整拆分候选清单放不进一次请求时，请暂存更小的逻辑变更，或明确在个人配置中选择 `largeChange.strategy: "deep"`。深度分析的请求数（256）和汇总层级（8）上限固定，提高 token 或时间预算不会改变它们；token 和时间预算可在个人配置中调整。未知模型采用保守 token 估算，输入估算超限会在发送前失败；Provider 上下文超限不会盲目重试。
+默认 `auto` 在本地建立清单并选择受限片段；拆分候选过多时会分批请求，再分层合并计划。深度分析仍有固定的请求数（256）和汇总层级（8）上限。如果总 token/时间预算耗尽，或分层规划无法收敛，拆分模式会明确警告，并可降级为一个覆盖全部文件的计划，绝不会采用模型返回的半份计划。交互和 dry-run 流程会展示该计划；非交互提交必须显式传入 `--allow-single-fallback`。token 和时间预算仍可在个人配置中调整。未知模型采用保守 token 估算，单次输入超限时不会发送该请求；Provider 上下文超限不会盲目重试。
 
-Text lines over 1 MiB fail explicitly. Large-change hunk plans are unsupported; use file-level split. Metadata-only files remain in the complete plan. Invalid, duplicate, or missing IDs are response-format errors, not automatic catch-all groups.
+Validated initial `deep` chunks are cached under private Git metadata after a failed or interrupted run. A retry of the identical snapshot and model settings reports cached chunks and requests only the remainder. Any input/model/protection change causes a miss. Successful generation clears the active cache; stale entries expire after 24 hours. Unprotected input is not cached unless personal `largeChange.cache.allowUnprotected` is explicitly enabled.
+
+失败或中断后，已经通过校验的初始 `deep` 分块会缓存在私有 Git 元数据中。使用相同快照和模型设置重试时会报告缓存命中，并只请求剩余分块；输入、模型或保护模式发生任何变化都会失效。完整生成成功后清理当前缓存，遗留项 24 小时后过期。未保护内容只有在个人配置显式启用 `largeChange.cache.allowUnprotected` 时才缓存。
+
+Text lines over 1 MiB fail explicitly. Large-change hunk plans are unsupported; use file-level split. Metadata-only files remain in the complete plan. Invalid provider output remains a response-format error; only deterministic budget/capacity exhaustion activates the complete all-files fallback.
 
 单行超过 1 MiB 会明确报错。大变更暂不支持 hunk 规划，请使用文件级拆分。仅统计的文件仍纳入完整计划。无效、重复或遗漏 ID 会报响应格式错误，不会自动归入兜底组。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hifullmoon/aicommit",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Safe, local-first AI commit message generator for Git workflows",
   "type": "module",
   "bin": {

package/src/analysis-budget.js

@@ -6,6 +6,12 @@ export const DEFAULT_LARGE_CHANGE = Object.freeze({
   maxTotalTokens: 200000,
   concurrency: 2,
   timeoutMs: 180000,
+  cache: Object.freeze({
+    enabled: true,
+    ttlMs: 24 * 60 * 60 * 1000,
+    maxBytes: 32 * 1024 * 1024,
+    allowUnprotected: false,
+  }),
 });
 
 export function estimateTokens(text) {
@@ -40,21 +46,25 @@ export function createAnalysisBudget(settings = {}) {
       };
     },
     reserve(input, output) {
-      if (
-        !this.remainingMs() ||
-        charged + input + output + reserveFinal > limits.maxTotalTokens ||
-        requests >= 256
-      ) {
+      const exhausted = !this.remainingMs()
+        ? 'time'
+        : requests >= 256
+          ? 'requests'
+          : charged + input + output + reserveFinal > limits.maxTotalTokens
+            ? 'tokens'
+            : null;
+      if (exhausted) {
         throw fail(
           ERROR_CATEGORIES.PROVIDER,
-          'Large-change analysis reached its token, request, or time budget. No incomplete plan will be committed. Increase the personal largeChange budget or stage a smaller change.',
-          { data: { analysis: this.snapshot() } },
+          `Large-change analysis reached its ${exhausted} budget.`,
+          { data: { analysis: { ...this.snapshot(), exhausted } } },
         );
       }
       if (input > limits.chunkInputTokens) {
         throw fail(
           ERROR_CATEGORIES.PROVIDER,
           'Analysis request exceeds largeChange.chunkInputTokens; shorten repository context or increase the personal input budget.',
+          { data: { analysis: { ...this.snapshot(), exhausted: 'input' } } },
         );
       }
       charged += input + output;

package/src/analysis-cache.js

@@ -0,0 +1,246 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+export const ANALYSIS_CACHE_KIND = 'aicommit-analysis-cache-entry';
+export const ANALYSIS_CACHE_VERSION = 1;
+// Bump whenever the fragment-analysis prompt or summary contract changes.
+export const ANALYSIS_CONTRACT_VERSION = 1;
+const MAX_ENTRY_BYTES = 128 * 1024;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+function object(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!object(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .filter((key) => value[key] !== undefined)
+      .map((key) => [key, canonical(value[key])]),
+  );
+}
+
+function digest(value) {
+  return createHash('sha256')
+    .update(JSON.stringify(canonical(value)))
+    .digest('hex');
+}
+
+function cacheRoot(projectRoot) {
+  const raw = execFileSync(
+    'git',
+    ['rev-parse', '--git-path', `aicommit/analysis-cache/v${ANALYSIS_CACHE_VERSION}`],
+    {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    },
+  ).trim();
+  return isAbsolute(raw) ? raw : resolve(projectRoot, raw);
+}
+
+function namespaceSignature(config, protect) {
+  return digest({
+    contractVersion: ANALYSIS_CONTRACT_VERSION,
+    providerType: config.providerType || '',
+    apiUrl: config.apiUrl,
+    modelId: config.modelId,
+    reasoning: config.reasoning,
+    extraBody: config.extraBody,
+    protect,
+  });
+}
+
+function normalizeGroups(groups) {
+  if (!Array.isArray(groups) || !groups.length || groups.length > 16) {
+    throw new Error('Analysis cache groups must be a non-empty bounded array.');
+  }
+  return groups.map((group) => {
+    if (
+      !object(group) ||
+      !Array.isArray(group.ids) ||
+      !group.ids.length ||
+      group.ids.some((id) => typeof id !== 'string' || !id || id.length > 128) ||
+      typeof group.summary !== 'string' ||
+      !group.summary.trim() ||
+      group.summary.length > 2000
+    ) {
+      throw new Error('Analysis cache contains an invalid group.');
+    }
+    return { ids: [...group.ids], summary: group.summary };
+  });
+}
+
+function validateEntry(input, expectedIds) {
+  if (
+    !object(input) ||
+    Object.keys(input).some(
+      (key) => !['kind', 'version', 'createdAt', 'ids', 'groups'].includes(key),
+    ) ||
+    input.kind !== ANALYSIS_CACHE_KIND ||
+    input.version !== ANALYSIS_CACHE_VERSION ||
+    typeof input.createdAt !== 'string' ||
+    !Number.isFinite(Date.parse(input.createdAt)) ||
+    !Array.isArray(input.ids) ||
+    input.ids.length !== expectedIds.length ||
+    input.ids.some((id, index) => id !== expectedIds[index])
+  ) {
+    throw new Error('Analysis cache entry is invalid or belongs to another chunk.');
+  }
+  return normalizeGroups(input.groups);
+}
+
+function namespaceRecords(root) {
+  if (!existsSync(root)) return [];
+  const records = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const path = join(root, entry.name);
+    let bytes = 0;
+    let modified = lstatSync(path).mtimeMs;
+    for (const child of readdirSync(path, { withFileTypes: true })) {
+      if (!child.isFile() || child.isSymbolicLink()) continue;
+      const stat = statSync(join(path, child.name));
+      bytes += stat.size;
+      modified = Math.max(modified, stat.mtimeMs);
+    }
+    records.push({ path, bytes, modified });
+  }
+  return records;
+}
+
+function prune(root, settings, keep = null, now = Date.now()) {
+  try {
+    let records = namespaceRecords(root);
+    for (const record of records) {
+      if (record.path !== keep && now - record.modified > settings.ttlMs) {
+        rmSync(record.path, { recursive: true, force: true });
+      }
+    }
+    records = namespaceRecords(root).sort((left, right) => left.modified - right.modified);
+    let total = records.reduce((sum, record) => sum + record.bytes, 0);
+    for (const record of records) {
+      if (total <= settings.maxBytes) break;
+      if (record.path === keep) continue;
+      rmSync(record.path, { recursive: true, force: true });
+      total -= record.bytes;
+    }
+  } catch {
+    // A cache maintenance failure must never block commit generation.
+  }
+}
+
+export function createAnalysisCache({ projectRoot, snapshotFingerprint, config, protect = true }) {
+  const settings = config.largeChange?.cache;
+  if (
+    !settings?.enabled ||
+    config.largeChange?.strategy !== 'deep' ||
+    !SHA256_RE.test(snapshotFingerprint || '') ||
+    (!protect && !settings.allowUnprotected)
+  ) {
+    return null;
+  }
+
+  try {
+    const root = cacheRoot(projectRoot);
+    const signature = namespaceSignature(config, protect);
+    const namespace = join(root, `${snapshotFingerprint}.${signature}`);
+    prune(root, settings);
+    mkdirSync(namespace, { recursive: true, mode: 0o700 });
+
+    return {
+      keyFor(task, input) {
+        return digest({
+          contractVersion: ANALYSIS_CONTRACT_VERSION,
+          signature,
+          task,
+          input,
+        });
+      },
+      read(key, expectedIds, validate) {
+        if (!SHA256_RE.test(key)) return null;
+        const path = join(namespace, `${key}.json`);
+        try {
+          const stat = lstatSync(path);
+          if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_ENTRY_BYTES) return null;
+          const groups = validateEntry(JSON.parse(readFileSync(path, 'utf8')), expectedIds);
+          validate?.(groups);
+          const now = new Date();
+          utimesSync(namespace, now, now);
+          return groups;
+        } catch {
+          return null;
+        }
+      },
+      write(key, ids, groups) {
+        if (!SHA256_RE.test(key)) return false;
+        let entry;
+        try {
+          entry = {
+            kind: ANALYSIS_CACHE_KIND,
+            version: ANALYSIS_CACHE_VERSION,
+            createdAt: new Date().toISOString(),
+            ids: [...ids],
+            groups: normalizeGroups(groups),
+          };
+        } catch {
+          return false;
+        }
+        const path = join(namespace, `${key}.json`);
+        const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+        try {
+          const contents = JSON.stringify(entry) + '\n';
+          const bytes = Buffer.byteLength(contents);
+          const current = namespaceRecords(root).find((record) => record.path === namespace);
+          let existingBytes = 0;
+          try {
+            existingBytes = lstatSync(path).size;
+          } catch (error) {
+            if (error.code !== 'ENOENT') return false;
+          }
+          if (
+            bytes > MAX_ENTRY_BYTES ||
+            (current?.bytes || 0) - existingBytes + bytes > settings.maxBytes
+          ) {
+            return false;
+          }
+          writeFileSync(temporary, contents, { encoding: 'utf8', mode: 0o600 });
+          renameSync(temporary, path);
+          prune(root, settings, namespace);
+          return true;
+        } catch {
+          rmSync(temporary, { force: true });
+          return false;
+        }
+      },
+      clear() {
+        try {
+          rmSync(namespace, { recursive: true, force: true });
+          const parent = dirname(namespace);
+          if (existsSync(parent) && readdirSync(parent).length === 0) rmSync(parent);
+        } catch {
+          // Cache cleanup is best-effort and does not affect the completed result.
+        }
+      },
+      path: namespace,
+    };
+  } catch {
+    return null;
+  }
+}