@hifullmoon/aicommit 1.4.0

package/docs/examples/extension/index.mjs

@@ -0,0 +1,32 @@
+export function contextProvider({ files }) {
+  const packages = [...new Set(files.map(({ path }) => path.split('/')[0]).filter(Boolean))];
+  return { text: `Changed top-level areas: ${packages.join(', ')}`, warnings: [] };
+}
+
+export function messageValidator({ message }) {
+  return {
+    issues: /(?:ACME|ticket)-\d+/i.test(message)
+      ? []
+      : [{ severity: 'warning', code: 'ticket', message: 'consider including a ticket id' }],
+  };
+}
+
+export function providerAdapter({ operation, config, request, response, reasoning }) {
+  if (operation === 'buildRequest') {
+    return {
+      model: config.modelId,
+      input: request.messages,
+      max_output_tokens: request.maxTokens,
+    };
+  }
+  if (operation === 'normalizeResponse') {
+    return {
+      content: response.output_text || '',
+      model: response.model,
+      usage: response.usage,
+      finishReason: response.status,
+    };
+  }
+  if (operation === 'reasoningForFollowUp') return { ...reasoning, mode: 'off' };
+  throw new Error(`Unsupported providerAdapter operation: ${operation}`);
+}

package/docs/extensions.md

@@ -0,0 +1,93 @@
+# Extensions / 扩展
+
+AICommit extension API v1 exposes three deliberately small interfaces without loading third-party code into the CLI process. Extensions are user-installed single-file ESM modules and are never enabled by repository config.
+
+AICommit 扩展 API v1 提供三个刻意保持精简的接口，第三方代码不会加载到 CLI 主进程。扩展由用户以单文件 ESM 模块安装，仓库配置无权启用扩展。
+
+## Security model / 安全模型
+
+- Every manifest must declare `"permissions": { "credentials": false }`; v1 rejects every other value.
+- The extension process receives no AICommit API key, credential-helper result, `HOME`/`USERPROFILE` value, or inherited secret environment variable.
+- On Node.js 20+, the child runs with Node's permission model and may read only the packaged runner and its own `.mjs` entry. File writes, child processes, workers, and unrelated reads are denied.
+- Node.js 18 remains supported for core AICommit. Executable extensions fail clearly instead of running without isolation; use Node.js 20+ when extensions are enabled.
+- A context provider receives bounded branch/file metadata, a validator receives the candidate and normalized policy, and an adapter receives non-secret provider settings plus the request/response value needed for its operation.
+- Extensions can observe the data passed to their selected capability and may have network access, including access to services reachable from the machine. Node's permission model is defense in depth, not a substitute for reviewing third-party code. Keep the manifest and entry in a dedicated directory; imports and multi-file packages are intentionally outside v1.
+
+- 每个清单必须声明 `"permissions": { "credentials": false }`，v1 会拒绝其他值。
+- 扩展进程不会收到 AICommit API key、credential helper 结果、`HOME`/`USERPROFILE` 值或继承的秘密环境变量。
+- 在 Node.js 20+ 上，子进程使用 Node 权限模型，只能读取随包发布的 runner 和自己的 `.mjs` 入口；文件写入、子进程、worker 与无关文件读取均被拒绝。
+- Node.js 18 仍可运行 AICommit 核心；启用扩展时会明确失败，而不会在无隔离条件下降级执行。扩展场景请使用 Node.js 20+。
+- context provider 只收到受限的分支/文件元数据，validator 收到候选消息和标准化 policy，adapter 只收到非敏感 provider 设置及当前操作需要的请求/响应值。
+- 扩展能看到其接口明确收到的数据，也可能访问网络，包括本机可达的服务。Node 权限模型是纵深防御，不能替代第三方代码审查。请把清单和入口放进独立目录；v1 有意不支持 import 和多文件扩展包。
+
+## Manifest and configuration / 清单与配置
+
+Copy the executable example in [`docs/examples/extension`](examples/extension), then add its absolute manifest path to the user config:
+
+复制 [`docs/examples/extension`](examples/extension) 中的可执行示例，再把清单绝对路径写入用户配置：
+
+```json
+{
+  "extensions": {
+    "manifests": ["/Users/me/.aicommit/extensions/team-rules/aicommit-extension.json"],
+    "timeoutMs": 3000,
+    "maxContextChars": 2000
+  }
+}
+```
+
+```json
+{
+  "kind": "aicommit-extension",
+  "apiVersion": 1,
+  "id": "team-rules",
+  "version": "1.0.0",
+  "entry": "./index.mjs",
+  "capabilities": ["contextProvider", "messageValidator", "providerAdapter"],
+  "permissions": { "credentials": false }
+}
+```
+
+Validate the config shape without resolving credentials, then exercise the installed code through a dry run or doctor:
+
+先在不解析凭据的情况下校验配置结构，再通过 dry run 或 doctor 实际加载扩展：
+
+```bash
+aicommit config validate
+aicommit --dry-run
+aicommit doctor
+```
+
+The published JSON Schema is [`schemas/aicommit-extension.schema.json`](../schemas/aicommit-extension.schema.json).
+
+## Interface contract / 接口契约
+
+All exports may be synchronous or asynchronous and must return JSON-serializable values.
+
+所有导出函数均可同步或异步执行，返回值必须可 JSON 序列化。
+
+```js
+export function contextProvider({ repository, branch, files }) {
+  return { text: 'bounded context text', warnings: [] };
+}
+
+export function messageValidator({ message, policy }) {
+  return {
+    issues: [{ severity: 'error', code: 'ticket', message: 'ticket id required' }],
+  };
+}
+
+export function providerAdapter({ operation, config, request, response, reasoning }) {
+  if (operation === 'buildRequest') return { model: config.modelId, messages: request.messages };
+  if (operation === 'normalizeResponse') return { content: response.answer };
+  if (operation === 'reasoningForFollowUp') return { ...reasoning, mode: 'off' };
+}
+```
+
+To select the adapter, set `"providerType": "extension:team-rules"`. Core code still owns endpoint validation, timeout/retry, HTTP transport, and Bearer authorization. Adapter-produced credential-like request fields are rejected. Therefore a new body dialect can be added without modifying the core Git or interaction flow, while custom credential schemes remain intentionally unsupported by extension API v1.
+
+选择 adapter 时设置 `"providerType": "extension:team-rules"`。endpoint 校验、超时/重试、HTTP 传输和 Bearer 鉴权仍由核心负责。adapter 返回的疑似凭据字段会被拒绝。因此，新的请求/响应 body 方言无需修改核心 Git 或交互流程即可加入，而自定义鉴权方案在扩展 API v1 中暂不支持。
+
+Validator errors participate in the same one-shot correction flow as built-in policy errors and fail closed if the extension crashes or returns malformed output. Context-provider failures become warnings so optional context cannot block a commit.
+
+Validator 错误与内置 policy 错误共用一次纠正流程；扩展崩溃或返回格式错误时会 fail closed。Context provider 失败只产生 warning，避免可选上下文阻断提交。

package/docs/privacy.md

@@ -0,0 +1,58 @@
+# Privacy model / 隐私模型
+
+AICommit is a local CLI, not a hosted relay. Repository data travels directly from the local process to the provider endpoint selected in the user-owned config. There is no telemetry upload implementation.
+
+AICommit 是本地 CLI，不是托管中转服务。仓库数据从本地进程直接发送到用户配置选定的 provider endpoint；项目没有遥测上传实现。
+
+## Trust boundaries / 信任边界
+
+| Boundary / 边界                                                      | Data visible there / 可见数据                                                                                                        | Default control / 默认控制                                                                                                                     |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Main CLI process / CLI 主进程                                        | Selected Git metadata/diff, effective config, resolved provider credential / 选定 Git 元数据与 diff、有效配置、provider 凭据         | User config owns connection fields; project config is filtered / 连接字段归用户配置，项目配置受过滤                                            |
+| Git subprocess / Git 子进程                                          | Requested status, diff, index/tree operations / 请求的 status、diff、index/tree 操作                                                 | Explicit arguments, temporary indexes, fingerprints and recovery checkpoints / 显式参数、临时 index、指纹与恢复 checkpoint                     |
+| Provider endpoint / Provider 端点                                    | Prompt, protected selected diff/context, model options, Bearer credential / prompt、保护后的选定 diff/context、模型选项、Bearer 凭据 | Remote HTTPS except loopback; preview/protection before send; bounded context / 远端仅 HTTPS；发送前预览/保护；上下文有预算                    |
+| Extension child / 扩展子进程                                         | Only the input for its declared interface / 仅声明接口所需输入                                                                       | Sanitized environment, no resolved credential, Node permission model, timeout/output bounds / 清理环境、不传凭据、Node 权限模型、超时/输出限制 |
+| Local metrics file / 本地指标文件                                    | Duration, token totals, bounded result, edited/rewrite flags / 延迟、token 总量、结果类别、编辑/重写标记                             | Local-only, owner permissions, retention cap, disable/clear controls / 仅本地、owner 权限、保留上限、可关闭/清除                               |
+| GitHub/npm/Homebrew during installation / 安装期 GitHub/npm/Homebrew | Package/formula download metadata / 包与 formula 下载元数据                                                                          | Signed tag, Sigstore/GitHub provenance, npm provenance, SHA-256 formula pin / 签名 tag、构建证明、npm provenance、SHA-256 固定                 |
+
+## Provider request contents / Provider 请求内容
+
+A normal generation can send the system policy, requested language, selected changed paths/statuses, staged diff, bounded repository context, and provider/model controls. Split planning can additionally send tracked diffs and bounded previews of untracked regular files. Regeneration sends the previous message by default instead of the diff. Connection check sends only a fixed `OK` prompt.
+
+普通生成可能发送 system policy、语言、选定文件路径/状态、staged diff、受限仓库上下文及 provider/model 控制。Split planning 还可能发送 tracked diff 与未跟踪普通文件的受限预览。默认重写只发送上一条消息而不重发 diff。连通性检查只发送固定 `OK` prompt。
+
+AICommit does not intentionally send unrelated files, historical commit bodies, local metric records, environment variables, its config file, Git credential-helper output, split checkpoint content, or model reasoning in machine output.
+
+AICommit 不会主动发送无关文件、历史 commit body、本地指标、环境变量、配置文件、Git credential-helper 输出、split checkpoint 内容，也不会在机器输出中包含模型 reasoning。
+
+## Data minimization and sensitive content / 数据最小化与敏感内容
+
+- Repository context and every diff category have explicit character/count ceilings and can be disabled.
+- Lock files and configured generated artifacts are stubbed; oversized diffs/files are condensed.
+- Common sensitive filenames, private keys, cloud access-key IDs, and credential-like assignments are omitted or redacted in the protected request.
+- Repository text is encoded as untrusted JSON data under an authoritative system policy.
+- Interactive users can explicitly send the original content after a warning. This is a deliberate override and should be rare.
+
+- 仓库上下文与每类 diff 都有字符/数量上限，并可关闭。
+- 锁文件与配置的生成物会被替换为占位；过大 diff/文件会被压缩。
+- 常见敏感文件名、私钥、云访问 key ID 与疑似凭据赋值会在默认保护请求中省略或脱敏。
+- 仓库文本作为不可信 JSON 数据编码，由权威 system policy 约束。
+- 交互用户可在警告后明确发送原文；这是应谨慎使用的主动覆盖。
+
+Detection, redaction, prompt boundaries, and the extension permission model are defense in depth, not proofs that arbitrary data or malicious code is safe. Extensions may access the network and can observe the candidate/context/response explicitly passed to their capability. Install only reviewed extensions and verify custom endpoints before sending private code.
+
+检测、脱敏、prompt 边界与扩展权限模型都是纵深防御，不能证明任意数据或恶意代码绝对安全。扩展可能访问网络，并能看到其 capability 明确收到的候选消息、上下文或响应。只安装已审查扩展，并在向自定义 endpoint 发送私有代码前核实其可信度。
+
+## Credentials and retention / 凭据与保留
+
+Credential resolution order is environment variable → opted-in Git credential helper → literal user config → keyless loopback. Project config and team policy cannot select a credential source. The provider credential is used only by the core transport; extension API v1 always declares `credentials: false` and never receives the resolved value.
+
+凭据解析顺序为：环境变量 → 用户启用的 Git credential helper → 用户配置明文 → 无 key 的 loopback。项目配置和团队 policy 无权选择凭据来源。Provider 凭据只由核心传输层使用；扩展 API v1 固定声明 `credentials: false`，不会收到解析后的值。
+
+Providers control their own server-side retention and training policies; AICommit cannot enforce them. Consult the selected provider's current terms. Locally, Git commits retain the accepted message, split checkpoints persist only code-free plan metadata until completion/recovery, and metrics retain at most the configured number of minimal records.
+
+Provider 自行决定服务端保留与训练策略，AICommit 无法强制控制；请查阅所选 provider 的现行条款。本地 Git commit 会保留接受的消息；split checkpoint 在完成/恢复前只保存不含代码的计划元数据；metrics 最多保留配置数量的最小记录。
+
+Use `aicommit config show`, `aicommit stats`, and `aicommit preset show` to inspect effective local state without revealing credentials. Use `aicommit stats clear` to permanently remove local metric history.
+
+使用 `aicommit config show`、`aicommit stats` 和 `aicommit preset show` 可在不显示凭据的情况下检查本地状态。使用 `aicommit stats clear` 可永久删除本地指标历史。

package/docs/provider-compatibility.md

@@ -0,0 +1,37 @@
+# Provider compatibility / Provider 兼容表
+
+Provider presets choose setup defaults; adapters own request/response dialects; the core owns Git state, user interaction, HTTPS enforcement, retry, timeout, authorization, and machine output. Adding a compatible preset or an extension adapter does not modify the core Git/interaction flow.
+
+Provider preset 只选择 setup 默认值；adapter 负责请求/响应方言；核心负责 Git 状态、用户交互、HTTPS、重试、超时、鉴权与机器输出。新增兼容 preset 或 extension adapter 无需修改核心 Git/交互流程。
+
+| Provider / adapter           | Endpoint and auth / 端点与鉴权                                                 | Streaming / 流式                                                                | Reasoning / 推理                                                                        | Token and usage mapping / token 与 usage                                           | Notes / 说明                                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| OpenAI / `openai`            | Official HTTPS Chat Completions; Bearer key / 官方 HTTPS；Bearer key           | SSE                                                                             | Native for recognized `o*`/`gpt-5*`; model-dependent otherwise / 已识别推理模型原生支持 | `max_completion_tokens` for reasoning models, otherwise `max_tokens`; OpenAI usage | Unsupported effort is rejected locally for known model generations / 已知模型不支持的 effort 会本地拒绝      |
+| OpenRouter / `openrouter`    | OpenRouter HTTPS; Bearer key; `X-Title: aicommit`                              | SSE                                                                             | `reasoning.effort`                                                                      | `max_tokens`; OpenAI-style usage                                                   | Model IDs commonly include vendor prefix / model 通常含厂商前缀                                              |
+| DeepSeek / `deepseek`        | DeepSeek HTTPS; Bearer key                                                     | SSE                                                                             | `thinking.type` plus normalized effort / thinking 与归一 effort                         | `max_tokens`; compatible usage                                                     | `medium`/`xhigh` map to supported high behavior where required / 必要时映射为 high                           |
+| MiniMax / `minimax`          | MiniMax HTTPS; Bearer key                                                      | SSE                                                                             | `reasoning_split` and thinking switch                                                   | `max_tokens`; compatible usage                                                     | Adapter removes conflicting switches before send / 发送前移除冲突开关                                        |
+| Kimi Code / `custom`         | Kimi Code OpenAI-compatible HTTPS; Bearer key / Kimi Code OpenAI 兼容 HTTPS    | SSE                                                                             | Server default; no vendor fields injected / 使用服务端默认值，不注入厂商字段            | `max_tokens`; OpenAI-style usage                                                   | Bundled preset uses `kimi-for-coding`; membership and Platform keys are distinct / 会员与开放平台 key 不通用 |
+| Ollama native / `ollama`     | Loopback `/api/chat` or `/api/generate`; normally keyless HTTP                 | Complete JSON in v1; native NDJSON streaming is not consumed / v1 使用完整 JSON | Native `think` boolean                                                                  | `options.num_predict`; `prompt_eval_count` + `eval_count`                          | OpenAI-compatible `/v1/chat/completions` uses the compatible shape instead / `/v1` 使用兼容方言              |
+| Custom compatible / `custom` | HTTPS remote or loopback HTTP; optional core Bearer key                        | SSE when endpoint supports Chat Completions events                              | No vendor fields by default; explicit `enabledBody`/`disabledBody` / 默认不注入厂商字段 | `max_tokens`; common OpenAI/Anthropic/Ollama usage fields normalized               | Validate the endpoint before trusting it with code or credentials / 发送代码前验证端点                       |
+| Extension / `extension:<id>` | Core HTTPS/loopback transport and optional Bearer only / 核心传输与可选 Bearer | Declared conservative in API v1 / v1 保守声明                                   | Adapter operation can transform non-secret reasoning config                             | Adapter maps body and normalized response                                          | No custom credential scheme or headers; credential-like body fields rejected / 不支持自定义鉴权或 header     |
+
+## Compatibility contract / 兼容契约
+
+All built-in adapters return `content`, optional `reasoning`, normalized usage, finish reason, raw response, capabilities, attempts, and latency. Retries cover 429, selected 5xx, and network/body interruption; authentication, invalid parameters, and safety failures are not retried.
+
+所有内置 adapter 返回 `content`、可选 `reasoning`、标准 usage、finish reason、raw response、capability、attempts 与 latency。仅 429、部分 5xx、网络/响应中断会重试；鉴权、参数与安全错误不会重试。
+
+Preset compatibility is declared by core version range plus `adapterContract: 1`. Run:
+
+Preset 兼容性由核心版本范围与 `adapterContract: 1` 共同声明：
+
+```bash
+aicommit preset show
+aicommit preset validate --file=provider-presets.json
+aicommit preset install --file=provider-presets.json
+aicommit doctor -p provider-name
+```
+
+Use an existing built-in adapter when only setup defaults change. Use `custom` for an OpenAI-compatible endpoint with optional body switches. Use a reviewed `providerAdapter` extension only when the JSON request/response dialect differs and core Bearer authorization is sufficient. A protocol requiring different transport, streaming parser, or credential scheme is not compatible with extension API v1 and must not be disguised as a preset.
+
+若只改变 setup 默认值，应复用内置 adapter；OpenAI-compatible endpoint 及少量 body 开关使用 `custom`；仅当 JSON 请求/响应方言不同且核心 Bearer 鉴权足够时，才使用已审查的 `providerAdapter` 扩展。若协议需要不同传输、流解析或鉴权方案，则不兼容扩展 API v1，不能伪装成 preset。

package/docs/provider-presets.md

@@ -0,0 +1,100 @@
+# Provider presets / Provider 预设
+
+Provider presets are versioned setup data, not request code. The stable adapters in `src/providers.js` own request/response behavior; `presets/provider-presets.json` only supplies a provider ID, display label, adapter ID, secure endpoint, default model, and optional bounded `extraBody` defaults. Adding another OpenAI-compatible service with the `custom` adapter does not change Git, interaction, or request orchestration code.
+
+Provider preset 是带版本的 setup 数据，不是请求代码。`src/providers.js` 中的稳定 adapter 负责请求/响应行为；`presets/provider-presets.json` 只提供 provider ID、显示名称、adapter ID、安全 endpoint、默认模型以及可选且有界的 `extraBody` 默认值。使用 `custom` adapter 新增另一个 OpenAI-compatible 服务时，不需要修改 Git、交互或请求编排代码。
+
+## Compatibility contract / 兼容契约
+
+Every manifest declares:
+
+每份清单都声明：
+
+```json
+{
+  "kind": "aicommit-provider-presets",
+  "schemaVersion": 1,
+  "version": "1.0.0",
+  "compatibility": {
+    "coreMinimum": "1.4.0",
+    "coreMaximumExclusive": "2.0.0",
+    "adapterContract": 1
+  }
+}
+```
+
+- `version` versions the independently replaceable preset data.
+- The core range is inclusive at `coreMinimum` and exclusive at `coreMaximumExclusive`.
+- Core prerelease versions and build metadata follow SemVer; build metadata is ignored for precedence.
+- `adapterContract` declares the request-adapter interface expected by every entry.
+- The runtime rejects unknown fields, duplicate/reserved IDs, unsupported adapters, remote HTTP, credentials, top-level `model`/`messages` overrides, oversized data, incompatible versions, and symlinked files.
+
+- `version` 标识可独立替换的 preset 数据版本。
+- core 范围包含 `coreMinimum`，不包含 `coreMaximumExclusive`。
+- Core 的预发布版本与构建元数据遵循 SemVer；构建元数据不参与优先级比较。
+- `adapterContract` 声明每个条目所依赖的请求 adapter 接口。
+- 运行时拒绝未知字段、重复/保留 ID、不支持的 adapter、远程 HTTP、凭据、顶层 `model`/`messages` 覆盖、超限数据、不兼容版本和符号链接文件。
+
+The published JSON Schema is [`schemas/aicommit-provider-presets.schema.json`](../schemas/aicommit-provider-presets.schema.json). Runtime validation is authoritative and adds semantic/security checks that JSON Schema alone cannot express.
+
+发布的 JSON Schema 位于 [`schemas/aicommit-provider-presets.schema.json`](../schemas/aicommit-provider-presets.schema.json)。运行时校验是最终依据，并补充 JSON Schema 无法完整表达的语义与安全检查。
+
+## Inspect and validate / 检视与校验
+
+```bash
+aicommit preset path
+aicommit preset show --output=json
+aicommit preset validate --file=provider-presets.json --output=json
+```
+
+The bundled manifest is used unless `~/.aicommit/provider-presets.json` exists. `show` reports the selected source, preset version, compatibility declaration, and provider count. These commands do not resolve provider credentials.
+
+默认使用随包发布的清单；如果存在 `~/.aicommit/provider-presets.json`，则优先使用用户清单。`show` 会报告选中来源、preset 版本、兼容声明和 provider 数量。这些命令不会解析 provider 凭据。
+
+## Independent update and rollback / 独立更新与回滚
+
+Validate before installation, install atomically, then verify setup sees the expected source/version:
+
+安装前先校验，原子安装后再确认 setup 使用了预期来源与版本：
+
+```bash
+aicommit preset validate --file=provider-presets.json
+aicommit preset install --file=provider-presets.json
+aicommit preset show --output=json
+aicommit setup
+```
+
+On a later install, AICommit writes the current valid manifest to `~/.aicommit/provider-presets.previous.json` before replacing it. Roll back without changing the core package:
+
+后续安装时，AICommit 会先把当前有效清单写入 `~/.aicommit/provider-presets.previous.json`，再执行替换。无需更改 core 包即可回滚：
+
+```bash
+aicommit preset rollback
+aicommit preset validate
+```
+
+If the active user manifest is malformed or incompatible, installation preserves its raw bytes as `provider-presets.invalid-<timestamp>.json` before repairing the active file. / 如果活动用户清单损坏或不兼容，安装会先将原始内容保存为 `provider-presets.invalid-<timestamp>.json`，再修复活动文件。
+
+There is deliberately no automatic network updater. Obtain manifests through a trusted channel, review the endpoint/model changes, and validate locally before installation.
+
+系统刻意不提供自动联网更新器。请通过可信渠道取得清单，审阅 endpoint/模型变更，并在安装前进行本地校验。
+
+## Add a compatible provider / 新增兼容 provider
+
+Add one entry to a copied manifest, bump `version`, validate, and install it:
+
+在清单副本中增加一个条目、提升 `version`，然后校验并安装：
+
+```json
+{
+  "id": "acme",
+  "label": "Acme Compatible",
+  "adapter": "custom",
+  "apiUrl": "https://api.acme.example/v1/chat/completions",
+  "modelId": "acme-chat"
+}
+```
+
+If the service speaks an existing adapter contract, no core flow changes are required. A genuinely new wire protocol belongs in a provider adapter extension, not in preset data.
+
+如果服务符合现有 adapter 契约，就不需要修改 core 流程。真正的新 wire protocol 应实现 provider adapter 扩展，而不是塞入 preset 数据。

package/docs/team-policy.md

@@ -0,0 +1,86 @@
+# Team policy / 团队策略
+
+AICommit supports a repository-owned `.aicommit.policy.json` for deterministic commit-message rules. The document is safe to commit because its strict schema accepts only a language and a complete `commitPolicy`; credentials, endpoints, provider settings, prompts, and unknown properties are rejected.
+
+AICommit 支持由仓库维护的 `.aicommit.policy.json`，用于确定性地约束提交信息。该文件采用严格 schema，只接受语言与完整的 `commitPolicy`；凭据、endpoint、provider 设置、prompt 和未知字段都会被拒绝，因此可以安全提交到仓库。
+
+## Adopt the template / 引入模板
+
+Generate the template from the same installed CLI that will validate it, review every rule, then commit it:
+
+使用将负责校验的同一份 CLI 生成模板，审阅所有规则后提交：
+
+```bash
+aicommit policy template > .aicommit.policy.json
+aicommit config validate
+git add .aicommit.policy.json
+```
+
+The template fully declares every policy field. AICommit loads it after user, project, and provider-scoped config, so personal settings cannot silently change team results. `policy check` always applies recognized commitlint constraints from the same repository with fixed local-only detection limits; generation applies the same constraints when its commitlint context source is enabled.
+
+模板完整声明全部策略字段。AICommit 在用户、项目和 provider 级配置之后加载它，因此个人设置不会悄悄改变团队校验结果。`policy check` 始终以固定的本地只读检测上限应用同仓库中识别到的 commitlint 约束；生成流程会在启用 commitlint 上下文源时应用相同约束。
+
+## Use the same check locally and in CI / 本地与 CI 使用同一校验
+
+Install the sample [`commit-msg`](examples/commit-msg) hook, or call the equivalent command from Husky/lefthook:
+
+安装示例 [`commit-msg`](examples/commit-msg) hook，或在 Husky/lefthook 中调用同一命令：
+
+```bash
+install -m 0755 docs/examples/commit-msg .git/hooks/commit-msg
+```
+
+For pull requests, use the executable [GitHub Actions example](examples/aicommit-policy.yml), which validates the exact base-to-head range:
+
+对于 pull request，可使用可执行的 [GitHub Actions 示例](examples/aicommit-policy.yml)，校验准确的 base-to-head 范围：
+
+```bash
+aicommit policy check --range=origin/main..HEAD
+```
+
+Both paths call the same validator. `--output=json` returns the effective policy, a SHA-256 policy fingerprint, result IDs, issue codes, and severity without returning commit-message contents or diagnostic text derived from them. A policy violation exits with code `2`. `policy template` and `policy check` never resolve environment credentials or invoke Git credential helpers.
+
+两条路径调用同一个校验器。`--output=json` 返回有效策略、SHA-256 策略指纹、结果 ID、问题代码和严重级别，但不回传提交信息正文或由其派生的诊断文本。策略违规以退出码 `2` 结束。`policy template` 和 `policy check` 都不会解析环境凭据，也不会调用 Git credential helper。
+
+## Migration / 迁移
+
+1. Move Conventional Commit types, scope rules, subject length, body rules, breaking-change handling, and language out of free-form `prompt` text and into `.aicommit.policy.json`.
+2. Declare every field instead of relying on personal defaults. Start with optional scopes and narrow the values only after current history has been sampled.
+3. Keep provider credentials in `~/.aicommit.config.json` or environment variables; never copy them into the repository policy.
+4. If commitlint already defines `type-enum`, `scope-enum`, `subject-max-length`, or `header-max-length`, keep that file committed. AICommit reads recognized scalar values as data and never executes the config.
+5. Run the local hook and CI example on the same known-good and known-bad messages. Their `policyFingerprint` and issue codes must match before making the gate required.
+
+中文迁移步骤：
+
+1. 将 Conventional Commit 类型、scope 规则、标题长度、正文规则、破坏性变更和语言要求从自由文本 `prompt` 迁移到 `.aicommit.policy.json`。
+2. 明确声明所有字段，不依赖个人默认值。可先保留可选 scope，再根据现有提交历史逐步收紧取值。
+3. provider 凭据继续放在 `~/.aicommit.config.json` 或环境变量中，绝不要复制到仓库策略。
+4. 如果 commitlint 已定义 `type-enum`、`scope-enum`、`subject-max-length` 或 `header-max-length`，继续提交该配置。AICommit 只按数据读取识别出的标量规则，不执行配置文件。
+5. 用同一组已知正确/错误消息分别运行本地 hook 与 CI 示例；在强制启用门禁前，确认两者的 `policyFingerprint` 和问题代码一致。
+
+## Examples / 示例
+
+Require an `api` or `cli` scope and an English subject:
+
+要求 `api` 或 `cli` scope，并使用英文标题：
+
+```json
+{
+  "kind": "aicommit-team-policy",
+  "version": 1,
+  "language": "en",
+  "commitPolicy": {
+    "version": 1,
+    "types": ["feat", "fix", "docs", "refactor", "test", "chore"],
+    "scope": { "mode": "required", "values": ["api", "cli"] },
+    "subject": { "maxLength": 72 },
+    "body": { "mode": "optional", "maxLines": 8 },
+    "breakingChange": "allow",
+    "language": "inherit"
+  }
+}
+```
+
+`feat(api): add retry budget` passes. `feat: add retry budget` fails with `scope_required`; `feat(api): 添加重试预算` fails with `language`.
+
+`feat(api): add retry budget` 会通过。`feat: add retry budget` 以 `scope_required` 失败；`feat(api): 添加重试预算` 以 `language` 失败。

package/docs/troubleshooting.md

@@ -0,0 +1,37 @@
+# Troubleshooting matrix / 故障排查矩阵
+
+Start with credential-free inspection, then run live diagnostics only when provider access is intended:
+
+先执行无凭据检查；只有确实需要访问 provider 时才运行在线诊断：
+
+```bash
+aicommit config path
+aicommit config validate --output=json
+aicommit config show --output=json
+aicommit doctor --output=json
+```
+
+JSON mode keeps one machine object on stdout and diagnostics on stderr. The `error.category` and process exit code are stable automation inputs.
+
+JSON 模式保证 stdout 只有一个机器对象，诊断进入 stderr。`error.category` 与进程退出码可稳定用于自动化。
+
+| Symptom / 症状                                                                  | Category / exit                 | Likely cause / 常见原因                                                                                                                             | Check and recovery / 检查与恢复                                                                                                                         |
+| ------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Config fails before Git/provider access / 在 Git/provider 前配置失败            | `config` / `2`                  | Malformed JSON, invalid URL, unsupported option, missing credential / JSON 损坏、URL 或选项无效、凭据缺失                                           | `aicommit config path`; `aicommit config validate`; fix only the user-owned file shown                                                                  |
+| Project settings are ignored / 项目设置被忽略                                   | warning                         | Repository config tried to set endpoint, credential, extension, reasoning, metrics, or raise a ceiling / 仓库配置尝试设置连接、凭据、扩展或提高预算 | Move trusted connection settings to `~/.aicommit.config.json`; keep team rules in `.aicommit.policy.json`                                               |
+| Not a Git repository, conflict, empty index / 非仓库、冲突或 index 为空         | `git_state` / `3`               | Wrong directory or unsafe Git state / 目录错误或 Git 状态不安全                                                                                     | `git status`; `aicommit /absolute/repo/path`; resolve conflicts before retrying                                                                         |
+| DNS, connection, or timeout / DNS、连接或超时                                   | `network` / `4`                 | Endpoint unavailable, proxy/TLS issue, budget too short / endpoint 不可达、代理/TLS、超时过短                                                       | `aicommit doctor -p NAME`; verify HTTPS URL; raise user-owned `timeoutMs` only if expected                                                              |
+| HTTP authentication/rate/parameter failure / 鉴权、限流或参数失败               | `provider` / `5`                | Wrong key/model/body; non-retryable 4xx / key、model、body 错误                                                                                     | Check `apiKeyEnv`, model and compatibility table; authentication is never retried automatically                                                         |
+| Empty or malformed model reply / 空或畸形回复                                   | `response_format` / `6`         | Unsupported response dialect, token limit, policy/extension validator failure / 响应方言、token 限制、policy/扩展校验失败                           | Raise `maxTokens`, choose the matching adapter, inspect validator issue code; one correction is already attempted                                       |
+| `split run --scope=all --yes` stops before API call / split 非交互在 API 前停止 | `sensitive_data` / `7`          | Complete untracked scan found sensitive-looking data / 完整未跟踪扫描发现疑似敏感数据                                                               | Review/stage intended files explicitly; do not bypass without checking the actual content                                                               |
+| Commit aborts after generation / 生成后提交中止                                 | `concurrent_modification` / `8` | Index/worktree changed during the protected window / 受保护窗口中 index/worktree 被修改                                                             | Review `git status`, restore the intended snapshot, and generate again                                                                                  |
+| Split stopped after one or more commits / split 部分提交后停止                  | reported Git failure            | Hook, crash, SIGINT, or concurrent pending edit / hook、崩溃、中断或待处理文件变化                                                                  | Run `aicommit split resume`; if another Git workflow already replaced the transaction, use `aicommit split abort`（只删除恢复元数据，不改提交或工作区） |
+| Preset install/rollback fails / preset 安装或回滚失败                           | `config` / `2`                  | Schema/core range/adapter contract mismatch or no valid backup / schema、核心范围、adapter contract 不匹配或无备份                                  | `aicommit preset validate --file=...`; `aicommit preset show`; follow the compatibility guide                                                           |
+| Extension requires Node 20+ / 扩展要求 Node 20+                                 | `config` / `2`                  | Node 18 intentionally has no executable-extension fallback / Node 18 有意不降级运行扩展                                                             | Upgrade Node for extensions or remove user manifest entries; core CLI still supports Node 18                                                            |
+| Extension timeout or permission error / 扩展超时或权限错误                      | warning or `response_format`    | Extension exceeded its limit or tried denied filesystem/process access / 扩展超时或访问被拒资源                                                     | Review the extension, keep it single-file, raise `extensions.timeoutMs` cautiously; validator failures are fail-closed                                  |
+| `brew install` checksum mismatch / Homebrew checksum 不一致                     | Homebrew failure                | Formula and registry tarball differ, stale tap, or tampered download / formula 与 tarball 不同、tap 过旧或下载被篡改                                | `brew update`; compare release `SHA256SUMS`; do not use `--force` to bypass integrity                                                                   |
+| npm provenance is absent or invalid / npm provenance 缺失或失败                 | npm audit failure               | Old npm CLI, non-trusted release, or wrong version / npm 过旧、非可信发布或版本错误                                                                 | Upgrade npm; run `npm audit signatures`; install only a version linked to the official workflow                                                         |
+
+If a failure remains, capture `aicommit doctor --output=json`, Node/Git versions, the error category, and redacted config sources. Never attach a diff, commit message, config file, API key, reasoning trace, extension source containing secrets, or credential-helper output to a public issue.
+
+若问题仍未解决，请记录 `aicommit doctor --output=json`、Node/Git 版本、错误分类与脱敏后的配置来源。不要在公开 issue 中附加 diff、commit message、配置文件、API key、reasoning、含秘密的扩展源码或 credential-helper 输出。

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@hifullmoon/aicommit",
+  "version": "1.4.0",
+  "description": "Safe, local-first AI commit message generator for Git workflows",
+  "type": "module",
+  "bin": {
+    "aicommit": "./bin/aicommit.js"
+  },
+  "files": [
+    ".aicommit.config.example.json",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md",
+    "bin/",
+    "docs/",
+    "presets/",
+    "schemas/",
+    "templates/",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node bin/aicommit.js",
+    "test": "node --test --test-concurrency=1",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "coverage": "c8 node --test --test-concurrency=1",
+    "eval": "node eval/run.mjs",
+    "test:package": "node scripts/package-smoke.mjs",
+    "test:homebrew": "node scripts/homebrew-smoke.mjs",
+    "release:assets": "node scripts/release-assets.mjs",
+    "release:npm:check": "node scripts/publish-npm-org.mjs",
+    "release:npm:publish": "node scripts/publish-npm-org.mjs --publish",
+    "ci": "npm run lint && npm run format:check && npm run eval && npm run coverage"
+  },
+  "c8": {
+    "all": true,
+    "include": [
+      "src/**/*.js",
+      "bin/**/*.js"
+    ],
+    "reporter": [
+      "text",
+      "lcov"
+    ],
+    "check-coverage": true,
+    "lines": 70
+  },
+  "dependencies": {
+    "@inquirer/checkbox": "^4.3.2",
+    "@inquirer/confirm": "^5.1.0",
+    "@inquirer/core": "^10.3.2",
+    "@inquirer/editor": "^4.1.0",
+    "@inquirer/input": "^4.3.1",
+    "@inquirer/password": "^4.0.23",
+    "@inquirer/select": "^4.1.0",
+    "boxen": "^8.0.1",
+    "chalk": "^5.4.0",
+    "ora": "^8.2.0",
+    "wrap-ansi": "^9.0.2"
+  },
+  "keywords": [
+    "git",
+    "commit",
+    "ai",
+    "cli",
+    "conventional-commits",
+    "openai",
+    "deepseek",
+    "openrouter",
+    "ollama"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hi-fullmoon/AICommit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hi-fullmoon/AICommit/issues"
+  },
+  "homepage": "https://github.com/hi-fullmoon/AICommit#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "overrides": {
+    "c8": {
+      "test-exclude": "7.0.1"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "c8": "10.1.3",
+    "eslint": "9.39.5",
+    "prettier": "3.9.6"
+  }
+}

package/presets/provider-presets.json

@@ -0,0 +1,60 @@
+{
+  "kind": "aicommit-provider-presets",
+  "schemaVersion": 1,
+  "version": "1.1.0",
+  "compatibility": {
+    "coreMinimum": "1.4.0",
+    "coreMaximumExclusive": "2.0.0",
+    "adapterContract": 1
+  },
+  "providers": [
+    {
+      "id": "openai",
+      "label": "OpenAI",
+      "adapter": "openai",
+      "apiUrl": "https://api.openai.com/v1/chat/completions",
+      "modelId": "gpt-4o"
+    },
+    {
+      "id": "deepseek",
+      "label": "DeepSeek",
+      "adapter": "deepseek",
+      "apiUrl": "https://api.deepseek.com/v1/chat/completions",
+      "modelId": "deepseek-v4-flash"
+    },
+    {
+      "id": "openrouter",
+      "label": "OpenRouter",
+      "adapter": "openrouter",
+      "apiUrl": "https://openrouter.ai/api/v1/chat/completions",
+      "modelId": "openai/gpt-4o-mini"
+    },
+    {
+      "id": "minimax",
+      "label": "MiniMax",
+      "adapter": "minimax",
+      "apiUrl": "https://api.minimaxi.com/v1/chat/completions",
+      "modelId": "MiniMax-M3",
+      "extraBody": {
+        "thinking": {
+          "type": "disabled"
+        },
+        "reasoning_split": true
+      }
+    },
+    {
+      "id": "kimi-code",
+      "label": "Kimi Code",
+      "adapter": "custom",
+      "apiUrl": "https://api.kimi.com/coding/v1/chat/completions",
+      "modelId": "kimi-for-coding"
+    },
+    {
+      "id": "ollama",
+      "label": "Ollama (local)",
+      "adapter": "ollama",
+      "apiUrl": "http://127.0.0.1:11434/api/chat",
+      "modelId": "qwen3:8b"
+    }
+  ]
+}