@webywz/vibe-commit 0.1.13 → 0.1.15

package/README.md

@@ -17,7 +17,7 @@
 </p>
 
 Companion spirit to [diff-vibe](https://github.com/webywz/diff-vibe): commits here, pull requests there.
-Pair walkthrough (EN/中文) and a copy-pasteable helper: [`examples/pair-workflow.md`](./examples/pair-workflow.md) · [`examples/commit-msg.sh`](./examples/commit-msg.sh) (ship in the npm tarball).
+Pair walkthrough (EN/中文), helper script, and CI sample: [`examples/pair-workflow.md`](./examples/pair-workflow.md) · [`examples/commit-msg.sh`](./examples/commit-msg.sh) · [`examples/github-actions.yml`](./examples/github-actions.yml) (ship in the npm tarball).
 
 与 [diff-vibe](https://github.com/webywz/diff-vibe) 成对：这边写 commit，那边写 PR。
 成对流程与可复制脚本见 [`examples/`](./examples/)（随 npm 包发布）。
@@ -45,6 +45,7 @@ vibe-commit                         # propose from staged diff
 vibe-commit --vibe playful --commit # write the commit
 vibe-commit --breaking --dry-run    # force ! + BREAKING CHANGE footer
 vibe-commit --dry-run               # print only (default; wins over --commit)
+vibe-commit --github --quiet --no-ai  # Actions annotations (CI)
 git commit -m "$(vibe-commit --dry-run)"
 vibe-commit install                 # optional prepare-commit-msg hook
 ```
@@ -56,9 +57,13 @@ vibe-commit install                 # optional prepare-commit-msg hook
 | `--type <type>` | Force `feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `test` / `build` / `ci` / `chore` |
 | `--scope <scope>` | Override inferred scope · 覆盖推断出的 scope |
 | `--vibe <style>` | `playful` \| `pro` \| `terse` (default: `pro`) |
+| `--locale <locale>` | `en` \| `zh` (default: `en`) · 提交信息主题语言 |
 | `--no-ai` | Skip the API even if `OPENAI_API_KEY` is set · 即使有 Key 也不走 AI |
 | `--breaking` | Force breaking (`!` + `BREAKING CHANGE:` footer = **subject**) · 强制破坏性变更（`!` + footer 文本即 **subject**） |
 | `--json` | Machine-readable proposal · 机器可读提案 |
+| `--github` | Emit GitHub Actions `::notice` / `::warning` / `::error` annotations; write `GITHUB_OUTPUT` + `GITHUB_STEP_SUMMARY` when set · 输出 Actions 注解，并在环境变量存在时写 Job 输出与 Summary |
+| `--quiet` | Suppress the pretty terminal report; `--json` / `--github` still emit · 抑制漂亮终端报告 |
+| `--max-annotations <n>` | Cap `--github` annotation lines (default: 20; invalid → UsageError) · 限制注解条数 |
 | `install [--path]` | Install the prepare-commit-msg hook · 安装钩子 |
 | `uninstall [--path]` | Remove the managed hook · 卸载钩子 |
 | `-h` / `-v` | Help / version · 帮助 / 版本 |
@@ -75,7 +80,7 @@ npx --yes @webywz/vibe-commit --commit
 npx --yes @webywz/diff-vibe@^0.1.8 --base main --create
 ```
 
-Commits here · PRs there. Full walkthrough (EN/中文) and `commit-msg.sh` live in [`examples/pair-workflow.md`](./examples/pair-workflow.md) and [`examples/commit-msg.sh`](./examples/commit-msg.sh). Companion-side snippets: [diff-vibe examples](https://github.com/webywz/diff-vibe/tree/main/examples).
+Commits here · PRs there. Full walkthrough (EN/中文), `commit-msg.sh`, and Actions sample live in [`examples/`](./examples/). Companion-side snippets: [diff-vibe examples](https://github.com/webywz/diff-vibe/tree/main/examples).
 
 这边写 commit，那边写 PR。完整成对流程与脚本见 [`examples/`](./examples/)。成对仓库示例：[diff-vibe examples](https://github.com/webywz/diff-vibe/tree/main/examples)。
 
@@ -121,6 +126,45 @@ Hook stays **offline by default** (`VIBE_COMMIT_HOOK_AI=1` to allow AI). Unique
 
 钩子默认离线；设 `VIBE_COMMIT_HOOK_AI=1` 才允许 AI。用标记块保证干净卸载。已有外来钩子会备份并链式调用。
 
+### Locale support · 语言支持
+
+vibe-commit supports English (`en`, default) and Chinese (`zh`) commit subjects:
+
+vibe-commit 支持英文（`en`，默认）和中文（`zh`）提交信息主题：
+
+```bash
+vibe-commit --locale zh --dry-run        # Chinese subject: 添加/修复/更新...
+vibe-commit --locale en --dry-run        # English subject: add/fix/update...
+```
+
+**Configuration precedence** · 配置优先级：
+1. CLI flag `--locale`
+2. Environment variable `VIBE_COMMIT_LOCALE`
+3. Project config (`.vibe-commit.json` or `package.json#vibeCommit`)
+4. Default `en`
+
+```json
+// .vibe-commit.json
+{
+  "locale": "zh",
+  "vibe": "pro"
+}
+```
+
+```json
+// package.json
+{
+  "vibeCommit": {
+    "locale": "zh",
+    "vibe": "terse"
+  }
+}
+```
+
+Both heuristic and AI engines respect the locale setting. The `--json` output includes a `locale` field.
+
+启发式引擎和 AI 引擎都会遵循 locale 设置。`--json` 输出包含 `locale` 字段。
+
 ### AI (optional) · AI（可选）
 
 ```bash
@@ -128,6 +172,7 @@ export OPENAI_API_KEY=sk-...
 export OPENAI_MODEL=gpt-4o-mini          # optional
 export OPENAI_BASE_URL=https://api.openai.com/v1
 export VIBE_COMMIT_VIBE=pro              # or VIBE
+export VIBE_COMMIT_LOCALE=zh             # or en (default)
 ```
 
 OpenAI-compatible Chat Completions. Missing key, timeout, or 4xx/5xx → silent fallback to the offline heuristic. See [`.env.example`](.env.example). Unstaged files are never sent; huge diffs are truncated.
@@ -164,6 +209,8 @@ console.log(formatCommit(message));
    **破坏性变更**：删公开 `export`、主版本升级、diff 里已有 footer，或传 `--breaking`。强制 `--breaking` 时 footer 用 **subject**；启发式仍可用更具体的双语原因。干跑说明原因；`--json` 可带 `breakingReason`。
 5. Managed `prepare-commit-msg` hook via `install` / `uninstall`.
    通过 `install` / `uninstall` 管理 `prepare-commit-msg` 钩子。
+6. **GitHub Actions** mode: `--github` emits Checks annotations; optional `--quiet` / `--max-annotations`; writes job outputs + step summary when `GITHUB_OUTPUT` / `GITHUB_STEP_SUMMARY` are set. See [`examples/github-actions.yml`](./examples/github-actions.yml).
+   **GitHub Actions** 模式：`--github` 输出 Checks 注解；可选 `--quiet` / `--max-annotations`；环境变量存在时写 Job 输出与 Summary。示例见 [`examples/github-actions.yml`](./examples/github-actions.yml)。
 
 ---
 
@@ -173,6 +220,7 @@ console.log(formatCommit(message));
 - Source · [github.com/webywz/vibe-commit](https://github.com/webywz/vibe-commit)
 - Related · [diff-vibe](https://github.com/webywz/diff-vibe) · [prompt-diff](https://github.com/webywz/prompt-diff)
 - Pair workflow · [examples/pair-workflow.md](./examples/pair-workflow.md)
+- GitHub Actions · [examples/github-actions.yml](./examples/github-actions.yml)
 - License · [MIT](./LICENSE)
 
 ```bash

package/dist/ai.d.ts

@@ -1,8 +1,9 @@
-import type { ProposedMessage, StagedDiff, Vibe } from "./types.ts";
+import type { Locale, ProposedMessage, StagedDiff, Vibe } from "./types.ts";
 import type { CommitType } from "./types.ts";
 export interface AiContext {
     diff: StagedDiff;
     vibe: Vibe;
+    locale: Locale;
     type?: CommitType;
     scope?: string;
 }

package/dist/ai.js

@@ -17,7 +17,7 @@ export async function proposeWithAi(context, env = process.env) {
                 model,
                 temperature: context.vibe === "playful" ? 0.7 : 0.2,
                 messages: [
-                    { role: "system", content: systemPrompt(context.vibe) },
+                    { role: "system", content: systemPrompt(context.vibe, context.locale) },
                     { role: "user", content: userPrompt(context) },
                 ],
             }),
@@ -35,24 +35,29 @@ export async function proposeWithAi(context, env = process.env) {
             parsed.type = context.type;
         if (context.scope)
             parsed.scope = context.scope;
+        parsed.locale = context.locale;
         return parsed;
     }
     catch {
         return null;
     }
 }
-function systemPrompt(vibe) {
+function systemPrompt(vibe, locale) {
     const vibeLine = vibe === "playful"
         ? "Tone: witty, still professional; no memes, no emoji, no slang that would embarrass a code review."
         : vibe === "terse"
             ? "Tone: as short as possible. Headline only, no body."
             : "Tone: clear, professional, imperative mood.";
+    const langLine = locale === "zh"
+        ? "Subject language: Chinese (中文). Use Chinese verbs like 添加/修复/更新/重构/优化/删除/格式化 etc."
+        : "Subject language: English.";
     return `You write conventional commit messages.
 Return only the commit message, no quotes, no markdown fences.
 Format: type(scope): subject
 Optional body after a blank line.
 Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
 Subject: lowercase, imperative, no trailing period, <= 72 chars.
+${langLine}
 ${vibeLine}`;
 }
 function userPrompt(context) {

package/dist/cli.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import pc from "picocolors";
 import { formatCommit } from "./format.js";
 import { commitWithMessage, GitError, inspectStaged } from "./git.js";
+import { appendGitHubJobOutput, appendGitHubStepSummary, formatGitHubAnnotations, } from "./github.js";
 import { installHook, uninstallHook, runPrepareCommitMsg } from "./hook.js";
 import { helpText, parseArgs, UsageError } from "./parse-args.js";
 import { proposeMessage } from "./propose.js";
@@ -45,23 +46,54 @@ export async function main(argv = process.argv.slice(2)) {
             type: options.type,
             scope: options.scope,
             vibe: options.vibe,
+            locale: options.locale,
             preferAi: !options.noAi,
             breaking: options.breaking,
         });
         const formatted = formatCommit(message);
         const shouldCommit = options.commit && !options.dryRun;
+        if (options.github) {
+            const ann = formatGitHubAnnotations(message, diff, {
+                maxAnnotations: options.maxAnnotations,
+            });
+            // Keep --json stdout machine-parseable; annotations ride on stderr.
+            if (options.json)
+                process.stderr.write(ann);
+            else
+                process.stdout.write(ann);
+            try {
+                appendGitHubJobOutput(message, diff);
+            }
+            catch (err) {
+                process.stderr.write(`vibe-commit: GITHUB_OUTPUT skipped (${err instanceof Error ? err.message : err})\n`);
+            }
+            try {
+                appendGitHubStepSummary(message, diff);
+            }
+            catch (err) {
+                process.stderr.write(`vibe-commit: GITHUB_STEP_SUMMARY skipped (${err instanceof Error ? err.message : err})\n`);
+            }
+        }
         if (options.json) {
             process.stdout.write(`${JSON.stringify({ ...message, formatted }, null, 2)}\n`);
         }
-        else if (piped) {
-            process.stdout.write(`${formatted}\n`);
-        }
-        else {
-            process.stdout.write(renderProposal(diff, message));
+        else if (!options.quiet) {
+            if (options.github) {
+                process.stdout.write("::group::vibe-commit report\n");
+            }
+            if (piped) {
+                process.stdout.write(`${formatted}\n`);
+            }
+            else {
+                process.stdout.write(renderProposal(diff, message));
+            }
+            if (options.github) {
+                process.stdout.write("::endgroup::\n");
+            }
         }
         if (shouldCommit) {
             commitWithMessage(formatted);
-            if (!piped && !options.json) {
+            if (!piped && !options.json && !options.quiet) {
                 process.stdout.write(`  ${pc.green("committed")}\n\n`);
             }
         }

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { Locale, Vibe } from "./types.ts";
+export interface ProjectConfig {
+    locale?: Locale;
+    vibe?: Vibe;
+}
+export declare function loadProjectConfig(cwd?: string): ProjectConfig | undefined;

package/dist/config.js

@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { LOCALES, VIBES } from "./types.js";
+export function loadProjectConfig(cwd = process.cwd()) {
+    const vibeCommitPath = join(cwd, ".vibe-commit.json");
+    if (existsSync(vibeCommitPath)) {
+        try {
+            const raw = readFileSync(vibeCommitPath, "utf8");
+            const parsed = JSON.parse(raw);
+            return normalizeConfig(parsed);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const raw = readFileSync(pkgPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.vibeCommit &&
+                typeof parsed.vibeCommit === "object" &&
+                !Array.isArray(parsed.vibeCommit)) {
+                return normalizeConfig(parsed.vibeCommit);
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function normalizeConfig(raw) {
+    const config = {};
+    if (typeof raw.locale === "string") {
+        const locale = raw.locale.trim().toLowerCase();
+        if (LOCALES.includes(locale)) {
+            config.locale = locale;
+        }
+    }
+    if (typeof raw.vibe === "string") {
+        const vibe = raw.vibe.trim().toLowerCase();
+        if (VIBES.includes(vibe)) {
+            config.vibe = vibe;
+        }
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/format.js

@@ -61,6 +61,7 @@ export function parseCommit(text, engine = "heuristic") {
         body: rest || undefined,
         breaking,
         engine,
+        locale: "en",
     };
 }
 export function stripFences(text) {

package/dist/github.d.ts

@@ -0,0 +1,32 @@
+import type { ProposedMessage, StagedDiff } from "./types.ts";
+export interface GitHubFormatOptions {
+    /** Soft cap for PR annotation noise. Default 20. */
+    maxAnnotations?: number;
+}
+type AnnotationType = "error" | "warning" | "notice";
+/** Escape payload text for workflow command messages. */
+export declare function escapeData(value: string): string;
+/** Escape workflow command property values (file, title, …). */
+export declare function escapeProperty(value: string): string;
+export declare function annotation(type: AnnotationType, message: string, props?: {
+    file?: string;
+    line?: number;
+    title?: string;
+}): string;
+/** Heuristic risk tier → annotation level (breaking / fix weigh heavier). */
+export declare function proposalAnnotationType(proposal: ProposedMessage): AnnotationType;
+/**
+ * Emit GitHub Actions workflow commands so PR Checks show the proposed commit.
+ * Offline / local-safe: pure string formatting, no network.
+ */
+export declare function formatGitHubAnnotations(proposal: ProposedMessage, diff: StagedDiff, options?: GitHubFormatOptions): string;
+/** Append job outputs when running inside Actions (`GITHUB_OUTPUT`). */
+export declare function appendGitHubJobOutput(proposal: ProposedMessage, diff: StagedDiff): void;
+/** Build a short Markdown Job Summary for Actions (no env I/O). */
+export declare function formatGitHubStepSummary(proposal: ProposedMessage, diff: StagedDiff): string;
+/**
+ * Append a concise Job Summary when running inside Actions (`GITHUB_STEP_SUMMARY`).
+ * No-op when the env var is unset.
+ */
+export declare function appendGitHubStepSummary(proposal: ProposedMessage, diff: StagedDiff): void;
+export {};

package/dist/github.js

@@ -0,0 +1,162 @@
+import { appendFileSync } from "node:fs";
+import { formatCommit } from "./format.js";
+/** Escape payload text for workflow command messages. */
+export function escapeData(value) {
+    return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+/** Escape workflow command property values (file, title, …). */
+export function escapeProperty(value) {
+    return escapeData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+export function annotation(type, message, props = {}) {
+    const parts = [];
+    if (props.file)
+        parts.push(`file=${escapeProperty(props.file)}`);
+    if (props.line !== undefined && Number.isFinite(props.line)) {
+        parts.push(`line=${Math.max(1, Math.trunc(props.line))}`);
+    }
+    if (props.title)
+        parts.push(`title=${escapeProperty(props.title)}`);
+    const meta = parts.length > 0 ? ` ${parts.join(",")}` : "";
+    return `::${type}${meta}::${escapeData(message)}`;
+}
+/** Heuristic risk tier → annotation level (breaking / fix weigh heavier). */
+export function proposalAnnotationType(proposal) {
+    if (proposal.breaking)
+        return "error";
+    switch (proposal.type) {
+        case "fix":
+            return "warning";
+        case "feat":
+        case "perf":
+        case "refactor":
+            return "notice";
+        default:
+            return "notice";
+    }
+}
+function oneLine(value, max = 200) {
+    const flat = value.replace(/\s+/g, " ").trim();
+    if (flat.length <= max)
+        return flat;
+    return `${flat.slice(0, max - 1)}…`;
+}
+function headerLine(proposal) {
+    return formatCommit({ ...proposal, body: undefined }).split("\n")[0] ?? "";
+}
+/**
+ * Emit GitHub Actions workflow commands so PR Checks show the proposed commit.
+ * Offline / local-safe: pure string formatting, no network.
+ */
+export function formatGitHubAnnotations(proposal, diff, options = {}) {
+    const max = options.maxAnnotations ?? 20;
+    const lines = [];
+    const push = (line) => {
+        if (lines.length < max)
+            lines.push(line);
+    };
+    const primary = diff.files[0]?.path;
+    const title = headerLine(proposal);
+    push(annotation(proposalAnnotationType(proposal), title, {
+        file: primary,
+        title: "vibe-commit · title",
+    }));
+    if (proposal.breaking) {
+        const reason = proposal.breakingReason?.trim() ||
+            "Breaking change detected in staged diff.";
+        push(annotation("error", oneLine(reason), {
+            file: primary,
+            title: "vibe-commit · breaking",
+        }));
+    }
+    if (proposal.body?.trim()) {
+        push(annotation("notice", oneLine(proposal.body), {
+            file: primary,
+            title: "vibe-commit · body",
+        }));
+    }
+    for (const file of diff.files) {
+        const status = file.status === "A"
+            ? "add"
+            : file.status === "D"
+                ? "delete"
+                : file.status === "R"
+                    ? "rename"
+                    : "update";
+        push(annotation("notice", `${status} \`${file.path}\` (+${file.additions} −${file.deletions})`, {
+            file: file.path,
+            title: "vibe-commit · file",
+        }));
+    }
+    const totals = diff.files.reduce((acc, file) => {
+        acc.add += file.additions;
+        acc.del += file.deletions;
+        return acc;
+    }, { add: 0, del: 0 });
+    push(annotation("notice", `${diff.files.length} files · +${totals.add} / −${totals.del} · engine ${proposal.engine}`, { title: "vibe-commit · meta" }));
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+/** Append job outputs when running inside Actions (`GITHUB_OUTPUT`). */
+export function appendGitHubJobOutput(proposal, diff) {
+    const path = process.env.GITHUB_OUTPUT;
+    if (!path)
+        return;
+    const body = [
+        `title=${oneLine(headerLine(proposal), 256)}`,
+        `subject=${oneLine(proposal.subject, 200)}`,
+        `type=${proposal.type}`,
+        `scope=${proposal.scope ?? ""}`,
+        `breaking=${proposal.breaking}`,
+        `engine=${proposal.engine}`,
+        `findings=${diff.files.length}`,
+    ].join("\n");
+    appendFileSync(path, `${body}\n`, "utf8");
+}
+/** Build a short Markdown Job Summary for Actions (no env I/O). */
+export function formatGitHubStepSummary(proposal, diff) {
+    const totals = diff.files.reduce((acc, file) => {
+        acc.add += file.additions;
+        acc.del += file.deletions;
+        return acc;
+    }, { add: 0, del: 0 });
+    const lines = [
+        "## vibe-commit",
+        "",
+        `| | |`,
+        `| --- | --- |`,
+        `| **Title** | ${headerLine(proposal)} |`,
+        `| **Type** | \`${proposal.type}\`${proposal.scope ? ` (\`${proposal.scope}\`)` : ""} |`,
+        `| **Breaking** | ${proposal.breaking} |`,
+        `| **Engine** | ${proposal.engine} |`,
+        `| **Files** | ${diff.files.length} (+${totals.add} / −${totals.del}) staged |`,
+        "",
+    ];
+    if (proposal.breakingReason?.trim()) {
+        lines.push(`**Breaking:** _${oneLine(proposal.breakingReason, 280)}_`, "");
+    }
+    else if (proposal.body?.trim()) {
+        lines.push(`_${oneLine(proposal.body, 280)}_`, "");
+    }
+    const findings = [];
+    for (const file of diff.files.slice(0, 8)) {
+        findings.push(`- \`${file.path}\` (${file.status}, +${file.additions} −${file.deletions})`);
+    }
+    if (findings.length > 0) {
+        lines.push("### Staged files", "", ...findings, "");
+    }
+    else {
+        lines.push("_No staged files._", "");
+    }
+    return lines.join("\n");
+}
+/**
+ * Append a concise Job Summary when running inside Actions (`GITHUB_STEP_SUMMARY`).
+ * No-op when the env var is unset.
+ */
+export function appendGitHubStepSummary(proposal, diff) {
+    const path = process.env.GITHUB_STEP_SUMMARY;
+    if (!path)
+        return;
+    appendFileSync(path, `${formatGitHubStepSummary(proposal, diff)}\n`, "utf8");
+}
+//# sourceMappingURL=github.js.map

package/dist/heuristic.d.ts

@@ -1,9 +1,10 @@
-import type { CommitType, DiffHunk, ProposedMessage, StagedDiff, StagedFile, Vibe } from "./types.ts";
+import type { CommitType, DiffHunk, Locale, ProposedMessage, StagedDiff, StagedFile, Vibe } from "./types.ts";
 export interface HeuristicInput {
     diff: StagedDiff;
     type?: CommitType;
     scope?: string;
     vibe: Vibe;
+    locale: Locale;
     /** Force breaking: true (ORs with inferBreaking). */
     breaking?: boolean;
 }
@@ -12,7 +13,7 @@ export declare function inferType(diff: StagedDiff): CommitType;
 export declare function primaryRole(path: string): CommitType;
 export declare function classifyPath(path: string): CommitType[];
 export declare function inferScope(files: StagedFile[]): string | undefined;
-export declare function inferSubject(diff: StagedDiff, type: CommitType, scope?: string): string;
+export declare function inferSubject(diff: StagedDiff, type: CommitType, scope: string | undefined, locale: Locale): string;
 export type BreakingKind = "export-removed" | "major-bump" | "footer" | "forced";
 export declare function inferBreaking(diff: StagedDiff): boolean;
 /** Why breaking was set — heuristic signal first, then --breaking. */

package/dist/heuristic.js

@@ -23,10 +23,10 @@ const FEAT_WORD_RE = /\b(add|added|feat|feature|implement|introduce|support|enab
 const REFACTOR_WORD_RE = /\b(refactor|rename|move|extract|simplify|cleanup|clean up|restructure)\b/i;
 const PERF_WORD_RE = /\b(perf|performance|optimiz|cache|faster|speed)\b/i;
 export function proposeHeuristic(input) {
-    const { diff, vibe } = input;
+    const { diff, vibe, locale } = input;
     const type = input.type ?? inferType(diff);
     const scope = input.scope ?? inferScope(diff.files);
-    const subject = inferSubject(diff, type, scope);
+    const subject = inferSubject(diff, type, scope, locale);
     const body = inferBody(diff, type);
     const forced = Boolean(input.breaking);
     const kind = detectBreakingKind(diff, forced);
@@ -35,6 +35,7 @@ export function proposeHeuristic(input) {
     const message = {
         ...styled,
         engine: "heuristic",
+        locale,
         breakingReason: kind ? formatBreakingReason(kind) : undefined,
     };
     // Forced --breaking: prefer subject in the footer (not bilingual default).
@@ -144,10 +145,11 @@ export function inferScope(files) {
         return undefined;
     return name.slice(0, 32);
 }
-export function inferSubject(diff, type, scope) {
+export function inferSubject(diff, type, scope, locale) {
     const files = diff.files;
-    if (files.length === 0)
-        return "update project files";
+    if (files.length === 0) {
+        return normalizeSubject(locale === "zh" ? "更新项目文件" : "update project files");
+    }
     const added = files.filter((file) => file.status === "A");
     const deleted = files.filter((file) => file.status === "D");
     const renamed = files.filter((file) => file.status === "R");
@@ -156,31 +158,67 @@ export function inferSubject(diff, type, scope) {
         added.length >= files.length - 1 &&
         !scope &&
         type === "feat") {
-        return normalizeSubject("add initial implementation");
+        return normalizeSubject(locale === "zh" ? "添加初始实现" : "add initial implementation");
     }
     if (renamed.length === 1 && files.length === 1) {
         const file = renamed[0];
-        return normalizeSubject(`rename ${stem(file.fromPath ?? file.path)} to ${stem(file.path)}`);
+        const fromName = stem(file.fromPath ?? file.path);
+        const toName = stem(file.path);
+        return normalizeSubject(locale === "zh"
+            ? `重命名 ${fromName} 为 ${toName}`
+            : `rename ${fromName} to ${toName}`);
     }
     if (deleted.length === files.length) {
-        return normalizeSubject(`remove ${joinNames(deleted.map((file) => stem(file.path)))}`);
+        const names = joinNames(deleted.map((file) => stem(file.path)));
+        return normalizeSubject(locale === "zh" ? `删除 ${names}` : `remove ${names}`);
     }
     if (idents.length > 0 && (type === "feat" || type === "fix")) {
-        const verb = type === "fix" ? "fix" : "add";
+        const verb = type === "fix" ? (locale === "zh" ? "修复" : "fix") : (locale === "zh" ? "添加" : "add");
         return normalizeSubject(`${verb} ${joinNames(idents.map(humanizeIdent))}`);
     }
     if (added.length === 1 && files.length === 1) {
-        return normalizeSubject(`add ${stem(added[0].path)}`);
+        const name = stem(added[0].path);
+        return normalizeSubject(locale === "zh" ? `添加 ${name}` : `add ${name}`);
     }
     if (added.length > 1 && added.length === files.length) {
-        return normalizeSubject(`add ${summarizeFiles(added, scope)}`);
+        const summary = summarizeFiles(added, scope);
+        return normalizeSubject(locale === "zh" ? `添加 ${summary}` : `add ${summary}`);
     }
     const focus = files.length === 1 ? stem(files[0].path) : summarizeFiles(files, scope);
-    return normalizeSubject(verbFor(type, focus, files));
+    return normalizeSubject(verbFor(type, focus, files, locale));
 }
-function verbFor(type, focus, files) {
+function verbFor(type, focus, files, locale) {
     const mostlyAdd = files.reduce((sum, file) => sum + file.additions, 0) >
         files.reduce((sum, file) => sum + file.deletions, 0) * 1.4;
+    if (locale === "zh") {
+        switch (type) {
+            case "feat":
+                return mostlyAdd ? `添加 ${focus}` : `更新 ${focus}`;
+            case "fix":
+                return `修复 ${focus}`;
+            case "docs":
+                return files.some((file) => /readme/i.test(file.path))
+                    ? "更新 readme"
+                    : `更新 ${focus}`;
+            case "test":
+                return mostlyAdd ? `添加 ${focus} 测试` : `更新 ${focus} 测试`;
+            case "refactor":
+                return `重构 ${focus}`;
+            case "perf":
+                return `优化 ${focus} 性能`;
+            case "style":
+                return `格式化 ${focus}`;
+            case "ci":
+                return `更新 ${focus} 工作流`;
+            case "build":
+                return `更新 ${focus} 构建`;
+            case "chore":
+                if (files.some((file) => /package(-lock)?\.json|pnpm-lock|yarn\.lock/.test(file.path))) {
+                    return "更新依赖";
+                }
+                return `更新 ${focus}`;
+        }
+    }
     switch (type) {
         case "feat":
             return mostlyAdd ? `add ${focus}` : `update ${focus}`;

package/dist/hook.js

@@ -4,8 +4,9 @@ import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { formatCommit } from "./format.js";
 import { assertRepo, GitError, inspectStaged } from "./git.js";
-import { defaultVibeFromEnv } from "./parse-args.js";
+import { defaultLocaleFromEnv, defaultVibeFromEnv } from "./parse-args.js";
 import { proposeMessage } from "./propose.js";
+import { loadProjectConfig } from "./config.js";
 export const HOOK_BEGIN = "# BEGIN VIBE-COMMIT";
 export const HOOK_END = "# END VIBE-COMMIT";
 export const HOOK_NAME = "prepare-commit-msg";
@@ -42,8 +43,10 @@ export async function runPrepareCommitMsg(messageFile, source, cwd = process.cwd
         const diff = inspectStaged(cwd);
         // Avoid hanging `git commit` on network — hooks stay offline unless opted in.
         const useAi = env.VIBE_COMMIT_HOOK_AI === "1";
+        const projectConfig = loadProjectConfig(cwd);
         const message = await proposeMessage(diff, {
-            vibe: defaultVibeFromEnv(env),
+            vibe: projectConfig?.vibe ?? defaultVibeFromEnv(env),
+            locale: projectConfig?.locale ?? defaultLocaleFromEnv(env),
             preferAi: useAi,
         }, env);
         const formatted = formatCommit(message);

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { inspectStaged, commitWithMessage, GitError } from "./git.ts";
 export { proposeHeuristic, inferType, inferScope, inferSubject, inferBreaking, detectBreakingKind, formatBreakingReason, breakingFooterDetail, DEFAULT_BREAKING_FOOTER_DETAIL, ensureBreakingFooter, classifyPath, } from "./heuristic.ts";
 export type { BreakingKind } from "./heuristic.ts";
 export { parseArgs, helpText, UsageError } from "./parse-args.ts";
+export { annotation, appendGitHubJobOutput, appendGitHubStepSummary, escapeData, escapeProperty, formatGitHubAnnotations, formatGitHubStepSummary, proposalAnnotationType, } from "./github.ts";
 export { assembleDiff, parseUnifiedDiff } from "./parse-diff.ts";
 export { installHook, uninstallHook, runPrepareCommitMsg, shouldSkipPrepareCommitMsg, hasNonCommentContent, HOOK_BEGIN, HOOK_END, } from "./hook.ts";
 export { proposeMessage } from "./propose.ts";

package/dist/index.js

@@ -3,6 +3,7 @@ export { formatCommit, parseCommit, normalizeSubject } from "./format.js";
 export { inspectStaged, commitWithMessage, GitError } from "./git.js";
 export { proposeHeuristic, inferType, inferScope, inferSubject, inferBreaking, detectBreakingKind, formatBreakingReason, breakingFooterDetail, DEFAULT_BREAKING_FOOTER_DETAIL, ensureBreakingFooter, classifyPath, } from "./heuristic.js";
 export { parseArgs, helpText, UsageError } from "./parse-args.js";
+export { annotation, appendGitHubJobOutput, appendGitHubStepSummary, escapeData, escapeProperty, formatGitHubAnnotations, formatGitHubStepSummary, proposalAnnotationType, } from "./github.js";
 export { assembleDiff, parseUnifiedDiff } from "./parse-diff.js";
 export { installHook, uninstallHook, runPrepareCommitMsg, shouldSkipPrepareCommitMsg, hasNonCommentContent, HOOK_BEGIN, HOOK_END, } from "./hook.js";
 export { proposeMessage } from "./propose.js";

package/dist/parse-args.d.ts

@@ -1,8 +1,11 @@
-import { type CliOptions, type CommitType, type Vibe } from "./types.ts";
+import { type CliOptions, type CommitType, type Locale, type Vibe } from "./types.ts";
 export declare function defaultVibeFromEnv(env?: NodeJS.ProcessEnv): Vibe;
-export declare function parseArgs(argv: string[], env?: NodeJS.ProcessEnv): CliOptions;
+export declare function defaultLocaleFromEnv(env?: NodeJS.ProcessEnv): Locale;
+export declare function parseArgs(argv: string[], env?: NodeJS.ProcessEnv, cwd?: string): CliOptions;
+export declare function parseMaxAnnotations(value: string | undefined): number;
 export declare function parseType(value: string | undefined): CommitType;
 export declare function parseVibe(value: string | undefined): Vibe;
+export declare function parseLocale(value: string | undefined): Locale;
 export declare function sanitizeScope(value: string): string;
 export declare class UsageError extends Error {
     constructor(message: string);

package/dist/parse-args.js

@@ -1,24 +1,32 @@
-import { COMMIT_TYPES, VIBES, } from "./types.js";
+import { COMMIT_TYPES, LOCALES, VIBES, } from "./types.js";
+import { loadProjectConfig } from "./config.js";
 const HELP = `vibe-commit — stylish conventional commits, offline-first
+有品味的 Conventional Commits（离线优先）
 
-Usage
+Usage · 用法
   vibe-commit [options]
   vibe-commit install [--path <repo>]
   vibe-commit uninstall [--path <repo>]
 
-Commands
+Commands · 命令
   install             Install a prepare-commit-msg hook in the repo
   uninstall           Remove the managed prepare-commit-msg hook
 
-Options
+Options · 参数
   --commit            Create the commit with the proposed message
   --dry-run           Print the message only (default)
   --type <type>       feat | fix | docs | style | refactor | perf | test | build | ci | chore
   --scope <scope>     Override inferred scope
   --vibe <style>      playful | pro | terse          (default: pro)
+  --locale <locale>   en | zh                        (default: en)
   --no-ai             Skip AI even if OPENAI_API_KEY is set
   --breaking          Force ! + BREAKING CHANGE footer (text = subject)
   --json              Print a machine-readable proposal
+  --github            Emit GitHub Actions annotations (::notice/warning/error)
+                      输出 Actions 注解；有 GITHUB_OUTPUT / GITHUB_STEP_SUMMARY 时写输出与 Job Summary
+  --quiet             Suppress the pretty terminal report (--json / --github still emit)
+                      抑制漂亮终端报告；--json / --github 仍照常
+  --max-annotations <n>  Cap GitHub annotation lines (default: 20) · 限制注解条数
   --path <repo>       Repo root for install/uninstall (default: cwd)
   -h, --help          Show help
   -v, --version       Show version
@@ -27,19 +35,38 @@ Env
   OPENAI_API_KEY      Optional. When set, draft with an OpenAI-compatible API
   OPENAI_MODEL        Default: gpt-4o-mini
   OPENAI_BASE_URL     Default: https://api.openai.com/v1
-  VIBE / VIBE_COMMIT_VIBE   Default vibe when --vibe is omitted
+  VIBE / VIBE_COMMIT_VIBE     Default vibe when --vibe is omitted
+  VIBE_COMMIT_LOCALE          Default locale when --locale is omitted
   VIBE_COMMIT_HOOK_AI Set to 1 to allow AI inside the git hook (off by default)
 
+With --github, annotations go to stdout (or stderr when combined with --json) so
+PR Checks can surface the proposed commit title / body / staged files. Job outputs
+title/subject/type/scope/breaking/engine/findings are written when GITHUB_OUTPUT
+is set (findings = staged file count). A short Markdown job summary is appended when
+GITHUB_STEP_SUMMARY is set. --quiet hides the pretty report only.
+
+配合 --github 时注解走 stdout（与 --json 联用则走 stderr，保持 JSON 干净）。
+有 GITHUB_OUTPUT 时写入 title/subject 等字段；有 GITHUB_STEP_SUMMARY 时追加 Job Summary。
+--quiet 只隐藏漂亮终端报告。
+
 Git hook
   After \`vibe-commit install\`, plain \`git commit\` (no -m) fills an empty /
   comment-only message file with a vibe-commit proposal. Skips merge, squash,
   amend (source=commit), and any message that already has non-comment text.
 
-Examples
+Project config
+  .vibe-commit.json or package.json#vibeCommit
+    { "locale": "zh", "vibe": "pro" }
+  Precedence: CLI > env > project config > default
+
+Examples · 示例
   git add -p
   vibe-commit
   vibe-commit --vibe playful --commit
+  vibe-commit --locale zh --dry-run
   vibe-commit --breaking --dry-run
+  vibe-commit --github --quiet --no-ai
+  vibe-commit --github --json --max-annotations 10
   git commit -m "$(vibe-commit --dry-run)"
   vibe-commit install
   vibe-commit uninstall --path ~/projects/app
@@ -48,14 +75,23 @@ export function defaultVibeFromEnv(env = process.env) {
     const raw = (env.VIBE_COMMIT_VIBE ?? env.VIBE ?? "pro").trim().toLowerCase();
     return VIBES.includes(raw) ? raw : "pro";
 }
-export function parseArgs(argv, env = process.env) {
+export function defaultLocaleFromEnv(env = process.env) {
+    const raw = (env.VIBE_COMMIT_LOCALE ?? "en").trim().toLowerCase();
+    return LOCALES.includes(raw) ? raw : "en";
+}
+export function parseArgs(argv, env = process.env, cwd = process.cwd()) {
+    const projectConfig = loadProjectConfig(cwd);
     const options = {
         command: "propose",
         commit: false,
         dryRun: false,
-        vibe: defaultVibeFromEnv(env),
+        vibe: projectConfig?.vibe ?? defaultVibeFromEnv(env),
+        locale: projectConfig?.locale ?? defaultLocaleFromEnv(env),
         noAi: false,
         json: false,
+        github: false,
+        quiet: false,
+        maxAnnotations: 20,
         help: false,
         version: false,
         breaking: false,
@@ -96,6 +132,21 @@ export function parseArgs(argv, env = process.env) {
             options.json = true;
             continue;
         }
+        if (arg === "--github") {
+            options.github = true;
+            continue;
+        }
+        if (arg === "--quiet") {
+            options.quiet = true;
+            continue;
+        }
+        if (arg === "--max-annotations" || arg.startsWith("--max-annotations=")) {
+            const value = arg.includes("=")
+                ? arg.slice("--max-annotations=".length)
+                : argv[++i];
+            options.maxAnnotations = parseMaxAnnotations(value);
+            continue;
+        }
         if (arg === "--breaking") {
             options.breaking = true;
             continue;
@@ -117,6 +168,11 @@ export function parseArgs(argv, env = process.env) {
             options.vibe = parseVibe(value);
             continue;
         }
+        if (arg === "--locale" || arg.startsWith("--locale=")) {
+            const value = arg.includes("=") ? arg.slice("--locale=".length) : argv[++i];
+            options.locale = parseLocale(value);
+            continue;
+        }
         if (arg === "--path" || arg.startsWith("--path=")) {
             const value = arg.includes("=") ? arg.slice("--path=".length) : argv[++i];
             if (!value)
@@ -160,6 +216,16 @@ function parseCommand(value) {
             return null;
     }
 }
+export function parseMaxAnnotations(value) {
+    const raw = value?.trim();
+    if (!raw)
+        throw new UsageError("Missing value for --max-annotations");
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new UsageError("--max-annotations must be a positive integer");
+    }
+    return n;
+}
 export function parseType(value) {
     const raw = value?.trim().toLowerCase();
     if (!raw)
@@ -178,6 +244,15 @@ export function parseVibe(value) {
     }
     return raw;
 }
+export function parseLocale(value) {
+    const raw = value?.trim().toLowerCase();
+    if (!raw)
+        throw new UsageError("Missing value for --locale");
+    if (!LOCALES.includes(raw)) {
+        throw new UsageError(`Invalid --locale "${value}". Use: ${LOCALES.join(", ")}`);
+    }
+    return raw;
+}
 export function sanitizeScope(value) {
     const scope = value.trim().replace(/^[\s(/]+|[\s)/]+$/g, "");
     if (!scope)

package/dist/propose.js

@@ -6,6 +6,7 @@ export async function proposeMessage(diff, options, env = process.env) {
         type: options.type,
         scope: options.scope,
         vibe: options.vibe,
+        locale: options.locale,
         breaking: options.breaking,
     });
     let message = heuristic;
@@ -15,6 +16,7 @@ export async function proposeMessage(diff, options, env = process.env) {
             const ai = await proposeWithAi({
                 diff,
                 vibe: options.vibe,
+                locale: options.locale,
                 type: options.type,
                 scope: options.scope,
             }, env);

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 export declare const VIBES: readonly ["playful", "pro", "terse"];
 export type Vibe = (typeof VIBES)[number];
+export declare const LOCALES: readonly ["en", "zh"];
+export type Locale = (typeof LOCALES)[number];
 export declare const COMMIT_TYPES: readonly ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore"];
 export type CommitType = (typeof COMMIT_TYPES)[number];
 export type FileStatus = "A" | "M" | "D" | "R" | "C" | "T" | "U";
@@ -30,11 +32,13 @@ export interface ProposedMessage {
     /** Short cause when breaking (export removed / major bump / --breaking / footer). */
     breakingReason?: string;
     engine: Engine;
+    locale: Locale;
 }
 export interface ProposeOptions {
     type?: CommitType;
     scope?: string;
     vibe: Vibe;
+    locale: Locale;
     preferAi?: boolean;
     /** Force a breaking change (! + BREAKING CHANGE footer). */
     breaking?: boolean;
@@ -47,8 +51,15 @@ export interface CliOptions {
     type?: CommitType;
     scope?: string;
     vibe: Vibe;
+    locale: Locale;
     noAi: boolean;
     json: boolean;
+    /** Emit GitHub Actions annotations / job outputs / step summary. */
+    github: boolean;
+    /** Suppress the pretty terminal report (--json / --github still emit). */
+    quiet: boolean;
+    /** Soft cap for --github annotation lines (default 20). */
+    maxAnnotations: number;
     help: boolean;
     version: boolean;
     /** Force breaking change marker and footer. */

package/dist/types.js

@@ -1,4 +1,5 @@
 export const VIBES = ["playful", "pro", "terse"];
+export const LOCALES = ["en", "zh"];
 export const COMMIT_TYPES = [
     "feat",
     "fix",

package/examples/github-actions.yml

@@ -0,0 +1,49 @@
+# Example: surface a proposed commit message as Actions annotations + job summary.
+# Copy into your app repo as .github/workflows/vibe-commit.yml
+# (typically on pull_request so Checks show the draft commit).
+#
+# 示例：把拟写的 commit message 做成 Actions 注解 + Job Summary。
+# 复制到业务仓的 .github/workflows/vibe-commit.yml（通常挂在 pull_request 上）。
+#
+# Note: vibe-commit reads *staged* changes. Stage intentionally in CI, or
+# `git add -A` / `git add -u` before the step if you want the working tree.
+
+name: Vibe commit
+
+on:
+  pull_request:
+
+jobs:
+  vibe-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Stage working tree (demo)
+        run: git add -A
+
+      - name: Propose commit (annotations + summary)
+        id: vibe
+        run: |
+          npx --yes @webywz/vibe-commit@^0.1.14 \
+            --github \
+            --quiet \
+            --max-annotations 20 \
+            --no-ai
+        # --github           → ::notice / ::warning / ::error on the PR Checks UI
+        # --quiet            → suppress the pretty terminal report (annotations / summary / outputs still emit)
+        # --max-annotations  → soft-cap annotation noise (default 20)
+        # When GITHUB_OUTPUT is set, also writes: title, subject, type, scope, breaking, engine, findings
+        #   findings = staged file count
+        # When GITHUB_STEP_SUMMARY is set, appends a short Markdown job summary
+
+      # Optional: use job outputs from a later step
+      # - name: Echo title
+      #   run: echo "proposed ${{ steps.vibe.outputs.title }} (findings=${{ steps.vibe.outputs.findings }})"
+
+      # Optional: Job Summary is written automatically when GITHUB_STEP_SUMMARY is set
+      # (Actions injects it). No extra step required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webywz/vibe-commit",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Stylish conventional commit messages with personality. Offline-first, AI-optional.",
   "keywords": [
     "git",