@hifullmoon/aicommit 2.2.3 → 2.4.0

package/.aicommit.config.example.json

@@ -10,7 +10,10 @@
       "models": {
         "default": {
           "modelId": "MiniMax-M3",
-          "reasoning": { "mode": "on", "effort": "medium" }
+          "reasoning": {
+            "mode": "on",
+            "effort": "medium"
+          }
         }
       }
     },
@@ -22,7 +25,10 @@
       "models": {
         "chat": {
           "modelId": "deepseek-v4-flash",
-          "reasoning": { "mode": "on", "effort": "high" }
+          "reasoning": {
+            "mode": "on",
+            "effort": "high"
+          }
         }
       }
     },
@@ -32,8 +38,12 @@
       "apiKeyEnv": "OPENROUTER_API_KEY",
       "defaultModel": "fast",
       "models": {
-        "fast": { "modelId": "openai/gpt-4o-mini" },
-        "quality": { "modelId": "openai/gpt-4o" }
+        "fast": {
+          "modelId": "openai/gpt-4o-mini"
+        },
+        "quality": {
+          "modelId": "openai/gpt-4o"
+        }
       }
     },
     "kimi-code": {
@@ -42,7 +52,9 @@
       "apiKeyEnv": "KIMI_API_KEY",
       "defaultModel": "default",
       "models": {
-        "default": { "modelId": "kimi-for-coding" }
+        "default": {
+          "modelId": "kimi-for-coding"
+        }
       }
     },
     "ollama": {
@@ -50,8 +62,12 @@
       "apiUrl": "http://127.0.0.1:11434/api/chat",
       "defaultModel": "qwen",
       "models": {
-        "qwen": { "modelId": "qwen3:8b" },
-        "deepseek": { "modelId": "deepseek-r1:14b" }
+        "qwen": {
+          "modelId": "qwen3:8b"
+        },
+        "deepseek": {
+          "modelId": "deepseek-r1:14b"
+        }
       }
     }
   },
@@ -122,5 +138,12 @@
     "maxTokens": 4096,
     "maxDisplayChars": 12000
   },
-  "stripFiles": ["*.min.js", "*.map", "*.snap"]
+  "stripFiles": ["*.min.js", "*.map", "*.snap"],
+  "largeChange": {
+    "strategy": "auto",
+    "chunkInputTokens": 12000,
+    "maxTotalTokens": 200000,
+    "concurrency": 2,
+    "timeoutMs": 180000
+  }
 }

package/CHANGELOG.md

@@ -4,6 +4,28 @@ This file lists notable user-facing changes. Internal refactors, test-only chang
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-09-09
+
+### Changed
+
+- Large changes now default to a local inventory, repeated-edit deduplication, and bounded representative excerpts, typically using one model request. Exhaustive model analysis is available through personal `largeChange.strategy: "deep"`.
+- Large split plans must fit a complete local candidate inventory in one request by default; oversized plans stop before spending tokens. Coverage distinguishes sampled content from complete analysis.
+- Temporary diff and untracked-file snapshots open descriptors only while reading or writing, preventing large file sets from exhausting the process descriptor limit.
+
+- Moved model requests and streamed response decoding to Pi AI, using its bundled model metadata for reasoning capabilities while retaining existing Provider/Model configuration, custom endpoints, and native Ollama compatibility.
+- Raised the minimum Node.js version to 22.19.0 for Pi AI; startup now reports unsupported runtimes before loading the model SDK.
+- Streamed responses require an explicit provider finish reason. Token-limit aliases remain recoverable, mixed reasoning fields retain their text, and endpoints that only support complete JSON can use `extraBody.stream: false` without streaming-only parameters.
+
+## [2.3.0] - 2026-09-05
+
+### Added
+
+- Added `aicommit update` for verified self-updates of regular npm-global installations, with exact-version installation, JSON output, and safeguards against updating source links or the wrong Node.js environment.
+
+### Changed
+
+- Moved the cancel action to the end of sensitive-data confirmation menus to keep send choices together.
+
 ## [2.2.3] - 2026-09-01
 
 ### Fixed
@@ -178,7 +200,9 @@ 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.2.3...HEAD
+[Unreleased]: https://github.com/hi-fullmoon/AICommit/compare/v2.4.0...HEAD
+[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
 [2.2.3]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.2.3
 [2.2.2]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.2.2
 [2.2.1]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.2.1

package/README.md

@@ -30,7 +30,15 @@ These screenshots were captured from real interactive terminal sessions in this
 npm install --global @hifullmoon/aicommit
 ```
 
-Requires Node.js >= 18.
+Requires Node.js >= 22.19.0.
+
+Update an npm-global installation from the configured registry:
+
+```bash
+aicommit update
+```
+
+The command resolves npm's `latest` dist-tag, installs that exact version, and verifies the installed manifest. It refuses to modify a source checkout, an `npm link`, or a package owned by a different active Node.js/npm environment; use the manual upgrade command from the distribution guide in those cases.
 
 See the bilingual [installation, upgrade, signature-verification, and rollback guide](docs/distribution.md). The npm package has an automated installation smoke test.
 
@@ -185,10 +193,10 @@ This is the only supported user-config shape. Earlier flat or provider-level `mo
 | `timeoutMs`          | Per-request timeout in milliseconds (default: `120000`)                                                                                                                                                                      |
 | `retry`              | Transient retry limits: `maxAttempts`, `baseDelayMs`, and `maxDelayMs` (defaults: `3`, `500`, and `5000`)                                                                                                                    |
 | `credentialHelper`   | Opt in to `git credential fill` with `enabled` and `username` (defaults: `false` and `aicommit`)                                                                                                                             |
-| `maxDiffChars`       | Diff chars sent to the model per call; oversized diffs become a `--stat` summary + truncated hunks (default: `30000`)                                                                                                        |
-| `maxFileDiffChars`   | Cap on a single file's diff section; bigger sections are truncated to their leading hunks so one huge file can't crowd out the rest (default: `3000`)                                                                        |
-| `splitMaxDiffChars`  | Diff chars sent to the split-planning call; split mode needs less hunk detail than final message generation (default: `16000`)                                                                                               |
-| `splitMaxPlanFiles`  | Number of changed files shown to the split planner before extra files are swept into a catch-all commit (default: `100`)                                                                                                     |
+| `maxDiffChars`       | Per-analysis diff character budget; larger changes use chunked summaries (default: `30000`)                                                                                                                                  |
+| `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`)                                                                                                                    |
 | `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                                                       |
@@ -287,6 +295,7 @@ Project-level configuration is treated as untrusted: it cannot change the endpoi
 
 ```bash
 aicommit setup           # interactive configuration wizard
+aicommit update          # update the global npm installation to latest
 aicommit doctor          # diagnose runtime, config, credentials, and connectivity
 aicommit config show     # show the effective config with secrets redacted
 aicommit config validate # validate config without resolving credentials
@@ -376,7 +385,7 @@ Verify the registration with `whence -w _aicommit`; it should print `_aicommit:
 
 ### Machine-readable output
 
-Use `--output=json` for scripts and CI. Commit and split flows also require `--yes`, preventing a machine consumer from hanging on an interactive prompt. stdout contains exactly one JSON object; progress, debug details, and diagnostics go to stderr. `doctor --output=json` does not require `--yes`.
+Use `--output=json` for scripts and CI. Commit and split flows also require `--yes`, preventing a machine consumer from hanging on an interactive prompt. stdout contains exactly one JSON object; progress, debug details, and diagnostics go to stderr. `doctor --output=json` and `update --output=json` do not require `--yes`.
 
 ```json
 {
@@ -462,3 +471,29 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for local development and pull-request ch
 ## License
 
 [MIT](LICENSE)
+
+### Automatic large-change analysis
+
+The default `largeChange.strategy: "auto"` inventories every file locally, groups identical textual edits within a module, and selects representative excerpts under a fixed input budget. Lockfiles, generated files (such as `dist/`, `build/`, `*.map`, and `*.snap`), and `stripFiles` matches contribute metadata only. Complete content still undergoes local secret scanning; these selection rules do not change which files Git commits.
+
+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.
+
+For exhaustive chunk-by-chunk model analysis, opt in through personal configuration:
+
+```json
+{
+  "largeChange": {
+    "strategy": "deep",
+    "chunkInputTokens": 12000,
+    "maxTotalTokens": 200000,
+    "concurrency": 2,
+    "timeoutMs": 180000
+  }
+}
+```
+
+`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.
+
+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.

package/README.zh-CN.md

@@ -32,7 +32,15 @@ AI 驱动的 Git 提交信息生成器：读取 diff，请 AI 模型生成符合
 npm install --global @hifullmoon/aicommit
 ```
 
-需要 Node.js >= 18。
+需要 Node.js >= 22.19.0。
+
+从当前配置的 registry 更新 npm 全局安装：
+
+```bash
+aicommit update
+```
+
+该命令会解析 npm 的 `latest` dist-tag，安装对应的精确版本，并校验安装后的 manifest。源码检出、`npm link`，或属于另一个 Node.js/npm 环境的安装会被拒绝；这些情况请使用分发指南中的手动升级命令。
 
 安装、升级、签名校验与回滚请参阅双语[分发指南](docs/distribution.md)。npm package 带有自动化安装冒烟测试。
 
@@ -187,10 +195,10 @@ aicommit -p deepseek -m reasoner
 | `timeoutMs`          | 单次请求超时，单位为毫秒（默认：`120000`）                                                                                            |
 | `retry`              | 瞬时错误重试限制：`maxAttempts`、`baseDelayMs`、`maxDelayMs`（默认：`3`、`500`、`5000`）                                              |
 | `credentialHelper`   | 通过 `enabled` 和 `username` 选择性启用 `git credential fill`（默认：`false`、`aicommit`）                                            |
-| `maxDiffChars`       | 单次发送给模型的 diff 字符数；超限后改为 `--stat` 摘要和截断的 hunk（默认：`30000`）                                                  |
-| `maxFileDiffChars`   | 单文件 diff 上限；超限文件只保留前部 hunk，避免一个大文件挤占全部上下文（默认：`3000`）                                               |
-| `splitMaxDiffChars`  | 拆分规划请求的 diff 字符数；规划阶段需要的 hunk 细节少于最终信息生成（默认：`16000`）                                                 |
-| `splitMaxPlanFiles`  | 交给拆分规划器的最大变更文件数；超出部分归入兜底提交（默认：`100`）                                                                   |
+| `maxDiffChars`       | 每次分析的 diff 字符预算；超限自动分块汇总（默认：`30000`）                                                                           |
+| `maxFileDiffChars`   | 单文件正文分块参考大小；剩余内容继续分析（默认：`3000`）                                                                              |
+| `splitMaxDiffChars`  | 每次批次规划的上下文字符预算（默认：`16000`）                                                                                         |
+| `splitMaxPlanFiles`  | 每次规划的文件或候选组数量上限；超限分层规划（默认：`100`）                                                                           |
 | `diffContextLines`   | 每个 diff hunk 周围的上下文行数（`git diff --unified=<n>`）；越小越节省 token（默认：`1`）                                            |
 | `stripFiles`         | 额外替换为占位的文件，按 basename 使用 `*` / `?` 通配，如 `["*.min.js", "*.map", "*.snap"]`（默认：`[]`；项目项与用户项合并而非覆盖） |
 | `regenerateWithDiff` | `true` 表示每次重写都重发完整 diff，以获得更多变化；`false`（默认）只要求模型改写上一条消息，成本更低                                 |
@@ -289,6 +297,7 @@ AICommit 不会主动发送无关的仓库文件、历史提交正文、环境
 
 ```bash
 aicommit setup           # 交互式配置向导
+aicommit update          # 将 npm 全局安装更新到最新版
 aicommit doctor          # 诊断运行时、配置、凭据和连接
 aicommit config show     # 显示脱敏后的有效配置
 aicommit config validate # 校验配置，但不解析凭据
@@ -378,7 +387,7 @@ exec zsh
 
 ### 机器可读输出
 
-脚本和 CI 请使用 `--output=json`。提交和 split 流程还必须使用 `--yes`，避免机器消费者卡在交互提示上。stdout 只包含一个 JSON 对象；进度、调试信息和诊断输出会写入 stderr。`doctor --output=json` 不要求 `--yes`。
+脚本和 CI 请使用 `--output=json`。提交和 split 流程还必须使用 `--yes`，避免机器消费者卡在交互提示上。stdout 只包含一个 JSON 对象；进度、调试信息和诊断输出会写入 stderr。`doctor --output=json` 和 `update --output=json` 不要求 `--yes`。
 
 ```json
 {
@@ -464,3 +473,29 @@ exec zsh
 ## 许可证
 
 [MIT](LICENSE)
+
+### 大变更自动分析
+
+默认 `largeChange.strategy: "auto"` 在本地统计所有文件，按模块聚合相同文本修改，并选取固定预算内的代表性片段。lockfile、生成文件（如 `dist/`、`build/`、`*.map`、`*.snap`）和 `stripFiles` 匹配项只提供元数据。所有内容仍在本地接受敏感信息扫描；这些规则不会改变实际提交的文件。
+
+普通提交通常只需要一次模型请求，不会为每个文件调用 AI，也不会递归调用模型汇总。摘要最多包含 16 个代表组，并受 UTF-8 字节预算约束；优先覆盖代码、配置和测试等不同类别。摘要明确说明抽样范围，界面和 JSON 分别报告全文分析、代表片段和仅元数据的文件数，不把抽样视为完整理解。提供方重试、响应恢复、格式修正和用户重新生成仍可能增加请求。
+
+批次提交先在本地建立候选组，再用一次模型请求规划。只有完整候选清单能放入 `splitMaxPlanFiles` 和输入预算时才请求模型；否则在请求前停止，提示暂存更小的逻辑变更或显式选择深度分析。所有文件的归属仍进行完整性校验，不会因数量过多生成兜底提交。小变更保持原有请求路径。
+
+确实需要逐块 AI 分析时，在个人配置中设置：
+
+```json
+{
+  "largeChange": {
+    "strategy": "deep",
+    "chunkInputTokens": 12000,
+    "maxTotalTokens": 200000,
+    "concurrency": 2,
+    "timeoutMs": 180000
+  }
+}
+```
+
+`deep` 会增加请求和 token 消耗，最多 256 次请求。仓库配置不能切换这项个人策略或提高费用预算。两种策略均使用保守 token 估算，未知 usage 按预留额度计入；重试、汇总、规划和消息生成共用预算。超限或无效分组会停止，不自动提交不完整结果。
+
+完整补丁及较大未跟踪文本暂存到本地临时文件，只在读写时打开文件句柄，正常结束或取消时清理；异常崩溃可能遗留临时文件。正文读取有界。单行超过 1 MiB、无法在预算内合并的独立分组，以及大变更的实验性 hunk 规划会明确报错。

package/bin/aicommit.js

@@ -2,7 +2,7 @@
 
 import chalk from 'chalk';
 
-import { main } from '../src/main.js';
+import { nodeSupported, MIN_NODE_VERSION } from '../src/runtime.js';
 import { sanitizeTerminalText } from '../src/utils.js';
 import { classifyError } from '../src/errors.js';
 import { errorOutput, isJsonOutputRequested, successOutput } from '../src/output.js';
@@ -15,6 +15,11 @@ if (jsonOutput) {
 }
 
 try {
+  if (!nodeSupported())
+    throw new Error(
+      `AICommit requires Node.js >=${MIN_NODE_VERSION}; current version is ${process.versions.node}.`,
+    );
+  const { main } = await import('../src/main.js');
   const result = await main();
   if (jsonOutput) process.stdout.write(`${JSON.stringify(successOutput(result))}\n`);
 } catch (err) {

package/docs/distribution.md

@@ -11,6 +11,9 @@ AICommit is distributed exclusively through npm.
 npm install --global @hifullmoon/aicommit
 
 # upgrade / 升级
+aicommit update
+
+# manual upgrade / 手动升级
 npm install --global @hifullmoon/aicommit@latest
 
 # pin or roll back / 固定或回滚
@@ -19,6 +22,10 @@ npm install --global @hifullmoon/aicommit@1.4.0
 aicommit --version
 ```
 
+`aicommit update` 使用当前 `PATH` 中的 npm 和它配置的 registry，解析 `latest` dist-tag 后安装精确版本，并校验安装后的 package manifest。它仅更新当前 npm 全局根目录中的普通安装；源码检出、`npm link`、`npx` 缓存和其他 Node.js/npm 环境中的安装会被拒绝，以免更新错误的可执行文件。此时请切换到安装 AICommit 的 Node.js 环境，或使用上面的手动命令。
+
+`aicommit update` uses the npm on the current `PATH` and its configured registry. It resolves the `latest` dist-tag, installs that exact version, and verifies the installed package manifest. It only updates a regular installation in the active npm global root; source checkouts, `npm link`, `npx` caches, and installations owned by another Node.js/npm environment are rejected to avoid updating the wrong executable. Switch to the Node.js environment that installed AICommit, or use the manual command above.
+
 发布工作流使用 npm Trusted Publishing，不保存长期 `NPM_TOKEN`。来自公开 GitHub 仓库的 OIDC 发布会自动携带 npm provenance。可使用当前 npm CLI 检查 registry signature 与 provenance：
 
 The release workflow uses npm Trusted Publishing without a long-lived `NPM_TOKEN`. OIDC publishing from the public GitHub repository automatically includes npm provenance. Verify registry signatures and provenance with a current npm CLI:
@@ -26,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.2.3
+npm install --package-lock-only @hifullmoon/aicommit@2.4.0
 npm audit signatures
 ```
 

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

@@ -0,0 +1,193 @@
+# 大变更分析实施计划
+
+状态：核心链路已实施（2026-09-07）。原始清单保留为设计追踪，交付范围、验证结果及设计调整见文末。
+
+## 目标与边界
+
+保留现有“单次提交 / 批次提交”选择，自动根据输入预算决定一次分析或分块分析。单次模式始终生成一个 commit；批次模式按逻辑变更生成多个 commit。分析块不等于提交组。
+
+小变更保持一次生成请求。大变更不再仅依靠截断正文或把超过 100 个文件的部分归入兜底提交。完整文件归属由本地程序维护，模型只接收受预算约束的内容。
+
+第一版不增加第三种用户模式，不引入磁盘摘要缓存、不自动提交不完整批次计划、不更改现有 split 事务恢复协议。现有实验性 hunk 拆分须保持兼容；无法支持的组合应在请求前明确报错，不静默退化。
+
+## 当前接入点
+
+| 模块            | 当前行为与待调整点                                                                                           |
+| --------------- | ------------------------------------------------------------------------------------------------------------ |
+| `src/git.js`    | `readGit` 使用 64 MiB 缓冲；staged diff 和二进制指纹补丁完整读入。大内容需改为流式处理。                     |
+| `src/main.js`   | 多次获取 staged diff，调用 `condenseDiff` 后生成消息；需在所有早期读取位置消除全量正文读取。                 |
+| `src/split.js`  | `generateSplitPlan` 接收受限上下文，`condenseFileList` 默认仅展示 100 个文件；需接入统一分析及完整归属校验。 |
+| `src/api.js`    | 复用消息生成、响应恢复、usage 统计能力，并支持结构化分析输入。                                               |
+| `src/config.js` | 兼容现有字符限制配置，增加总分析预算。                                                                       |
+| `src/output.js` | 已有 `data` 扩展字段，可承载分析覆盖和预算元数据；需同步 schema 与错误输出。                                 |
+
+## 核心约束
+
+1. 先固定分析范围和快照，再建立全量清单。staged / all 的范围语义保持不变。
+2. 每个文件都有稳定 ID；重命名保留旧、新路径。ID 仅在同一快照内稳定。
+3. 文件清单覆盖、正文覆盖、摘要质量是不同指标，不将“模型返回了结果”描述成“完整理解”。
+4. 默认省略正文的文件仍参与归属、快照校验及现有敏感内容检查。
+5. 原始 diff、路径、预览和模型中间摘要均作为不可信数据，继续应用现有信任边界。
+6. 任何请求，包括恢复请求、重试、递归汇总和最终生成，都受共享总预算、截止时间和取消信号约束。
+7. 分组必须无未知 ID、无遗漏、无重复；文件级和 hunk 级归属不能冲突。
+8. 提交前重新校验快照。并发修改、未完成分析或非法分组不能导致静默自动提交。
+
+## 阶段 1：数据契约、配置与基线
+
+- [ ] 定义 `ChangeManifest`：快照标识、范围、文件 ID、路径映射、状态、增删统计、内容类型和正文策略。
+- [ ] 定义 `AnalysisChunk`：文件 / 片段 ID、顺序、输入估算及来源指纹。
+- [ ] 定义 `AnalysisResult`：有来源引用的事实摘要、关联建议、不确定项、覆盖记录及累计 usage。
+- [ ] 定义覆盖状态：`analyzed`、`metadataOnly`、`partial`、`failed`；记录省略或失败原因。
+- [ ] 明确“完整”要求：所有需正文分析的片段有有效结果，允许策略指定的 `metadataOnly`，不允许把失败标为策略省略。
+- [ ] 增加配置校验、配置展示及示例；制定旧配置迁移说明。
+- [ ] 建立小提交请求次数、延迟和模型输入基线。
+
+建议初始配置，最终默认值由阶段 7 的测量确定：
+
+```json
+{
+  "largeChange": {
+    "strategy": "auto",
+    "chunkInputTokens": 12000,
+    "maxTotalTokens": 200000,
+    "concurrency": 2,
+    "timeoutMs": 180000
+  }
+}
+```
+
+`strategy` 首版仅支持 `auto`。每次输入还必须服从模型窗口和现有字符上限中更保守的有效限制，并为指令、包装及响应预留空间。旧 `maxFileDiffChars` 用作分块线索，不再直接丢弃剩余正文；`splitMaxPlanFiles` 用作每次规划的文件数量上限，不再决定全局可处理文件数。文档明确这些语义变化。
+
+验收：非法配置在 Git 写操作和 Provider 请求前失败；旧配置可加载；契约能表示重命名、二进制和单文件多片段。
+
+## 阶段 2：有界 Git 读取与快照
+
+依赖：阶段 1。
+
+- [ ] 全量清单优先读取 NUL 分隔的路径、状态和 numstat，正确关联重命名、Unicode、制表符及换行路径。
+- [ ] 新增流式内容读取接口，处理子进程错误、背压、取消和退出状态；禁止巨型字符串持续拼接。
+- [ ] 流式计算 staged 二进制补丁指纹，保持原有指纹语义；如果确需更改算法，必须显式处理版本兼容。
+- [ ] 审计 main、split、快照捕获和验证链路，消除压缩前的全量正文读取，包括未跟踪大文件和二进制变化。
+- [ ] 大量路径使用受限批量参数或 Git 支持的路径输入方式，避免 Windows 命令行长度限制；路径按字面值处理。
+- [ ] 优先复用现有 split 快照与未跟踪文件保护逻辑，检测读取前后的状态变化。
+
+验收：原始补丁超过 64 MiB 仍能完成读取与指纹计算；正文内存不随补丁总字节数线性增长；空变更和 Git 失败可区分；取消后无遗留子进程；并发修改导致中止。
+
+## 阶段 3：分块调度与分层摘要
+
+依赖：阶段 1、2。建议新增 `src/change-analysis.js`，按复杂度再拆分预算与分块模块。
+
+- [ ] 先省略按策略无需正文的内容，再判断是否适合一次请求；全量清单在本地保留。
+- [ ] 优先保持完整文件，超大文件按 hunk 分块，超大 hunk 按行切分；超长单行也必须有界，并记录无法完整分析的情况。
+- [ ] 以目录、实现与测试关联改善分块，但不将分块边界固化为提交边界。
+- [ ] 使用有界任务队列、背压和共享预算，限制同时驻留的正文与请求数量。
+- [ ] 验证模型响应结构及引用 ID；要求每个输入片段有结果或明确不确定状态。
+- [ ] 摘要超预算时递归汇总，并设置最大层级 / 请求数量保护，防止不收敛。
+- [ ] 保留本地来源映射，父级用候选组 ID 引用子级；禁止在最后一次请求重新发送全部路径。
+- [ ] 优先使用可用的模型窗口 / token 计数；未知模型采用保守估算，遇上下文超限缩小失败块后重试。
+- [ ] 预留最终生成预算；请求发出前预占预算，并按实际 usage 结算；usage 缺失时保守记账。
+- [ ] 接入现有重试与响应恢复，避免外层和内层重试相乘；将退避计入截止时间。
+- [ ] 仅在本次运行内缓存已完成块；缓存键包含快照、内容、模型、保护策略和 prompt 版本。
+
+验收：每次请求输入受限；失败只重试对应块；所有调用都被计费记录；预算耗尽后不再发请求；摘要树不遗漏来源；小变更不额外增加一次分析调用。
+
+## 阶段 4：接入单次提交
+
+依赖：阶段 3。
+
+- [ ] 在 `src/main.js` 接入统一分析入口；小变更走直接生成路径，大变更用事实摘要生成一个提交说明。
+- [ ] 复用现有语言、commit policy、repository context、敏感内容选择及审阅流程。
+- [ ] 重新措辞复用摘要；配置要求重新分析时也服从总预算。
+- [ ] 不完整分析仅产生带覆盖提示的草稿，交互审阅后方可提交；非交互模式返回结构化错误，不自动提交。
+- [ ] 保留提交前指纹校验与 index 事务语义。
+
+验收：大变更最终仍只有一个 commit；生成内容来源可追溯；分析中断不改写真实 index；快照变化阻止提交；普通小提交请求次数不变。
+
+## 阶段 5：接入批次提交
+
+依赖：阶段 3、4。
+
+- [ ] 用摘要和短 ID 生成局部候选组，再汇总跨块关联；规划请求同样受预算限制。
+- [ ] 对存在歧义的跨组关联，允许受预算约束地补充相关摘要或片段。
+- [ ] 本地展开组 ID 到文件路径，校验完整覆盖、唯一归属及合法引用，替换超额文件兜底提交。
+- [ ] 为最终分组生成消息，复用已有分析；大量分组的消息生成也纳入总预算。
+- [ ] 未解决归属显示为待处理项，允许在现有审阅中调整；未解决前不执行、不导出可执行计划。
+- [ ] 非交互模式遇不完整分析或非法分组，在自动暂存前失败。
+- [ ] 继续生成现有 split plan 工件，由已有 apply / checkpoint / resume 流程执行；内部分析 ID 不改变外部路径语义。
+- [ ] 验证实验性 hunk 归属和跨块片段映射；无法处理时给出明确错误。
+
+验收：超过 100 个文件不产生由数量上限导致的兜底组；每个路径或 hunk 完整且唯一分配；跨目录的同一逻辑变更可以合并；plan/apply、hook 失败、resume 和 abort 行为保持兼容。
+
+## 阶段 6：进度、机器输出与文档
+
+依赖：阶段 4、5。
+
+- [ ] 展示总文件数、正文分析 / 仅统计数量、当前阶段及已完成块数；块动态细分时更新分母。
+- [ ] 并发分析使用聚合进度，避免多个请求的流式内容交错输出。
+- [ ] 在 JSON `data.analysis` 中增加覆盖数、失败数、降级原因和预算元数据，同步 schema；不包含 diff 和中间摘要。
+- [ ] 顶层 usage / latency 汇总完整调用链；stdout 保持单个 JSON，进度进入 stderr。
+- [ ] 更新双语 README、配置示例、privacy、troubleshooting，解释新旧限制语义、成本和失败恢复方式。
+
+验收：终端与 JSON 覆盖数字一致；`metadataOnly` 不被显示为正文已分析；机器输出兼容已有消费方式且通过 schema 校验。
+
+## 阶段 7：回归、规模验证与交付
+
+依赖：阶段 2—6。
+
+使用临时仓库和模拟 Provider 构造测试，不把巨型 fixture 提交到仓库。确定性测试验证边界和完整性，语义评估单独记录，不用字符串快照冒充摘要质量验证。
+
+| 场景                                  | 必须验证                                   |
+| ------------------------------------- | ------------------------------------------ |
+| 普通小提交                            | 一次生成请求，已有消息策略和交互保持兼容   |
+| 10,000 个小文件                       | 全量清单完整，请求有界；预算不足时正确停止 |
+| 超过 64 MiB 的源码补丁                | 流式读取、指纹校验与内存规模符合预期       |
+| 巨型 hunk、超长单行                   | 不导致超限请求或无界内存，覆盖状态诚实     |
+| 二进制、lock、生成文件、批量重命名    | 正文策略正确，路径仍完整纳入提交           |
+| 跨目录实现与测试                      | 可形成同一逻辑组，分块不强制分组           |
+| 敏感文件、未跟踪符号链接              | 保持现有保护行为，不因分块绕过             |
+| 429、响应截断、错误 ID、usage 缺失    | 重试有界、校验拒绝非法响应、预算保守记账   |
+| 超时、Ctrl+C、Git 失败、并发修改      | 清理资源、不误提交、不破坏真实 index       |
+| split 导出、apply、hook 失败与 resume | 原有工件和事务恢复兼容                     |
+
+- [ ] 记录峰值 RSS、总耗时、请求数、输入 / 输出 token 及覆盖情况；至少比较两个补丁体量，确认正文内存有界。
+- [ ] 记录小提交相对基线的额外耗时，测量后确定可接受阈值及最终预算默认值。
+- [ ] 执行相关单元 / 集成测试，再运行 `npm run ci` 和 `npm run test:package`。
+- [ ] 扩充 `eval` 的大变更样例，评估事实准确性、关键变更遗漏及逻辑分组质量。
+- [ ] 真实 Provider 验证可作为单独的受预算冒烟测试，不作为离线回归的必需依赖。
+
+交付标准：两个原有模式都能消费统一分析结果；大变更不存在无提示的正文丢弃或文件兜底归组；输入、内存、请求数及时间均有边界；失败不会绕过现有提交保护。
+
+## 建议实施顺序与提交拆分
+
+1. 契约、配置与基线（阶段 1）。
+2. Git 流式读取、指纹及路径边界测试（阶段 2）。
+3. 分块、预算和摘要核心（阶段 3）。
+4. 单次模式集成与保护回归（阶段 4）。
+5. 批次分层规划与工件兼容（阶段 5）。
+6. UI、输出 schema、文档及规模验证（阶段 6、7）。
+
+各阶段完成相关验收后再进入依赖阶段。本文勾选项在对应实现和验证完成后更新；建立计划本身不触发业务代码修改或发布。
+
+## 本次交付与验证记录（2026-09-07）
+
+已交付：私有临时补丁快照及有界读取、流式指纹计算、完整文件 ID 清单、分块事实分析、运行内成功片段缓存、受限并发、共享 token / 请求数 / 时间预算、分层摘要与批次规划、严格 ID 校验、完整未跟踪文本捕获、单次和批次集成、JSON 覆盖信息、Windows 大量路径输入和批量 index 更新。
+
+### 设计调整
+
+- Git 内容使用直接写临时文件的方式捕获，Node 按 64 KiB 读取，避免同步 stdout 缓冲上限；没有引入长期运行的异步 Git 子进程。临时文件空间取决于变更大小，Git 捕获有 120 秒命令超时。
+- token 计数采用保守估算并结合 Provider 模型窗口。Provider 上下文超限明确失败，尚未实现 tokenizer 精确计数和 Provider 报错后的自动缩块。
+- 分析不完整时统一停止，不生成可直接接受的部分草稿。完整分析结果的改写继续使用现有审阅流程。
+- 批次分层规划允许合并候选组；无法收敛时要求缩小范围，不把未解决文件自动塞入兜底组。大变更不支持实验性 hunk 规划，单行超过 1 MiB 明确拒绝。
+- 未新增真实 Provider 的语义质量基准；本次验证使用模拟 Provider，不能据此保证任意模型的摘要和分组质量。
+
+### 验证结果
+
+- 新增分析测试 12 项通过，涵盖未知 / 重复 / 遗漏 ID、完整未跟踪快照、后段私钥材料、重试计费、超过 64 MiB 的补丁和 10,000 个生成文件。
+- 111 个文件的单次和批次 CLI 实际提交测试通过：覆盖完整、token 汇总一致、暂存区最终干净；单次仍创建一个 commit。
+- 最终缓存调整后，分析、预算和两个 CLI 模式的 4 项针对性回归通过。
+- `npm run lint`、`npm run eval`、`npm run test:package` 通过。
+- 全量 coverage 运行：298 项通过、3 项跳过、3 项因 Windows 创建符号链接返回 EPERM 失败；失败发生在 fixture 创建阶段。后续新增的万文件测试已单独通过。
+- `npm run ci` 在格式检查阶段停止：88 个未修改文件包含当前 Prettier 不接受的格式 / 换行。未为了本功能重排无关文件。
+- 独立进程 Git 读取及指纹基准：32 MiB 输入耗时 2,202 ms、峰值 RSS 56 MiB；96 MiB 输入耗时 5,005 ms、峰值 RSS 58 MiB。这是本机一次测量，未包含 Provider 分析和全流程延迟。可运行 `node scripts/benchmark-large-change.mjs` 复现。
+
+未执行真实 Provider 请求、仓库提交或发布。

package/docs/privacy.md

@@ -54,3 +54,9 @@ Provider 自行决定服务端保留与训练策略，AICommit 无法强制控
 Use `aicommit config show` to inspect effective local state without revealing credentials.
 
 使用 `aicommit config show` 可在不显示凭据的情况下检查本地状态。
+
+## 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.
+
+默认大变更分析向已配置 Provider 发送受限本地清单和选定的保护后片段，不逐文件调用模型。明确选择 `deep` 时才发送分块片段和中间事实摘要。本地清单和模型摘要均视为不可信输入。完整 Git 补丁和较大未跟踪文本保存在本地私有临时文件中，按块读取；正常结束及 Ctrl+C 会清理，异常崩溃可能在系统临时目录留下快照。摘要仅在本次运行中复用，不加入 JSON 输出或 split checkpoint。