@zjex/git-workflow 0.2.20 → 0.2.22

package/CODE_DOCUMENTATION.md

@@ -0,0 +1,169 @@
+# 代码文档说明
+
+## 已添加详细注释的文件
+
+### ✅ src/commands/commit.ts
+
+**功能**: 交互式提交命令，支持 AI 自动生成和手动编写
+
+**注释内容**:
+
+- 模块级注释：说明 Conventional Commits 和 Gitmoji 规范
+- 函数注释：每个函数都有 JSDoc 注释
+- 步骤标记：用 `==========` 分隔不同的处理步骤
+- 行内注释：关键逻辑都有说明
+
+**关键函数**:
+
+- `commit()`: 主函数，处理整个提交流程
+- `buildManualCommitMessage()`: 手动构建 commit message
+- `parseGitStatus()`: 解析 git 状态
+- `formatFileStatus()`: 格式化文件状态显示
+
+### ✅ src/index.ts
+
+**功能**: 主入口文件，CLI 应用初始化和命令注册
+
+**注释内容**:
+
+- 模块级注释：说明文件职责
+- 全局错误处理：Ctrl+C、未捕获异常、Promise 拒绝
+- 版本信息：构建时注入
+- 交互式主菜单：ASCII Logo 和命令选择
+- CLI 命令注册：所有命令的注册和配置
+
+## 其他文件状态
+
+### ✅ 无错误的文件（已通过 TypeScript 检查）
+
+- src/ai-service.ts
+- src/config.ts
+- src/utils.ts
+- src/update-notifier.ts
+- src/commands/branch.ts
+- src/commands/help.ts
+- src/commands/init.ts
+- src/commands/release.ts
+- src/commands/stash.ts
+- src/commands/tag.ts
+- src/commands/update.ts
+
+## 代码质量改进
+
+### 1. 类型安全
+
+- 所有函数都有明确的返回类型
+- 使用 TypeScript 的类型推导
+- 接口定义清晰（如 `FileStatus`）
+
+### 2. 错误处理
+
+- 全局错误捕获
+- 优雅的 Ctrl+C 处理
+- 详细的错误提示信息
+- 提供手动执行命令
+
+### 3. 用户体验
+
+- 提交前检查暂存文件
+- 清晰的步骤分隔
+- 彩色输出和 emoji
+- 交互式选择界面
+
+### 4. 代码组织
+
+- 模块化设计
+- 单一职责原则
+- 清晰的函数命名
+- 详细的注释说明
+
+## 关键改进点
+
+### commit.ts
+
+1. **修复了 `message` 变量未初始化问题**
+
+   - 初始化为空字符串
+   - 确保所有代码路径都会赋值
+
+2. **添加提交前检查**
+
+   - 再次验证是否有暂存文件
+   - 避免空提交
+
+3. **改进错误提示**
+
+   - 显示完整错误信息
+   - 提供手动执行命令
+
+4. **修复 refactor 对齐问题**
+   - 针对 ♻️ emoji 特殊处理
+   - 动态调整间距
+
+### index.ts
+
+1. **完善错误处理**
+
+   - 捕获所有类型的错误
+   - 优雅退出
+
+2. **添加模块说明**
+   - 清晰的文件职责
+   - 详细的功能说明
+
+## 建议
+
+如果需要给其他文件添加详细注释，可以按照以下优先级：
+
+1. **高优先级**（核心业务逻辑）:
+
+   - src/ai-service.ts - AI commit 生成
+   - src/config.ts - 配置管理
+   - src/commands/tag.ts - Tag 管理
+
+2. **中优先级**（常用功能）:
+
+   - src/commands/branch.ts - 分支管理
+   - src/commands/stash.ts - Stash 管理
+   - src/update-notifier.ts - 更新检查
+
+3. **低优先级**（辅助功能）:
+   - src/utils.ts - 工具函数
+   - src/commands/help.ts - 帮助信息
+   - src/commands/init.ts - 初始化配置
+
+## 注释规范
+
+### JSDoc 注释格式
+
+```typescript
+/**
+ * 函数简短描述
+ *
+ * 详细说明（可选）
+ *
+ * @param paramName 参数说明
+ * @returns 返回值说明
+ */
+```
+
+### 行内注释
+
+```typescript
+// 简短说明当前代码的作用
+const result = doSomething();
+```
+
+### 步骤标记
+
+```typescript
+// ========== 步骤 1: 处理输入 ==========
+// ========== 步骤 2: 验证数据 ==========
+```
+
+## 总结
+
+✅ 核心文件已添加详细注释
+✅ 所有文件通过 TypeScript 检查
+✅ 代码质量和可维护性显著提升
+✅ 用户体验得到改善

package/dist/index.js

@@ -145,6 +145,14 @@ function backgroundCheck(currentVersion, packageName) {
     }
   });
 }
+function isUsingVolta() {
+  try {
+    const whichGw = execSync6("which gw", { encoding: "utf-8" }).trim();
+    return whichGw.includes(".volta");
+  } catch {
+    return false;
+  }
+}
 async function getLatestVersion(packageName) {
   try {
     const result = execSync6(`npm view ${packageName} version`, {
@@ -192,6 +200,8 @@ async function showUpdateMessage(current, latest, packageName) {
       width: 40
     })
   );
+  const usingVolta = isUsingVolta();
+  const updateCommand = usingVolta ? `volta install ${packageName}@latest` : `npm install -g ${packageName}@latest`;
   try {
     const action = await select7({
       message: "\u4F60\u60F3\u505A\u4EC0\u4E48\uFF1F",
@@ -199,7 +209,7 @@ async function showUpdateMessage(current, latest, packageName) {
         {
           name: "\u{1F680} \u7ACB\u5373\u66F4\u65B0",
           value: "update",
-          description: `\u8FD0\u884C npm install -g ${packageName}`
+          description: `\u8FD0\u884C ${updateCommand}`
         },
         {
           name: "\u23ED\uFE0F  \u7A0D\u540E\u66F4\u65B0\uFF0C\u7EE7\u7EED\u4F7F\u7528",
@@ -221,12 +231,14 @@ async function showUpdateMessage(current, latest, packageName) {
 }
 async function performUpdate(packageName) {
   console.log("");
+  const usingVolta = isUsingVolta();
+  const updateCommand = usingVolta ? `volta install ${packageName}@latest` : `npm install -g ${packageName}@latest`;
   const spinner = ora5({
     text: "\u6B63\u5728\u66F4\u65B0...",
     spinner: "dots"
   }).start();
   try {
-    execSync6(`npm install -g ${packageName}@latest`, {
+    execSync6(updateCommand, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -238,15 +250,18 @@ async function performUpdate(packageName) {
         [
           colors.green(colors.bold("\u2728 \u66F4\u65B0\u5B8C\u6210\uFF01")),
           "",
-          colors.dim("\u8BF7\u91CD\u65B0\u6253\u5F00\u7EC8\u7AEF\u4F7F\u7528\u65B0\u7248\u672C")
+          colors.dim("\u8BF7\u6267\u884C\u4EE5\u4E0B\u547D\u4EE4\u9A8C\u8BC1:"),
+          colors.cyan("  hash -r && gw --version"),
+          "",
+          colors.dim("\u6216\u91CD\u65B0\u6253\u5F00\u7EC8\u7AEF")
         ].join("\n"),
         {
-          padding: { top: 1, bottom: 1, left: 3, right: 3 },
+          padding: { top: 1, bottom: 1, left: 2, right: 2 },
           margin: { top: 0, bottom: 1, left: 2, right: 2 },
           borderStyle: "round",
           borderColor: "green",
-          align: "center",
-          width: 40
+          align: "left",
+          width: 50
         }
       )
     );
@@ -255,7 +270,7 @@ async function performUpdate(packageName) {
     spinner.fail(colors.red("\u66F4\u65B0\u5931\u8D25"));
     console.log("");
     console.log(colors.dim("  \u4F60\u53EF\u4EE5\u624B\u52A8\u8FD0\u884C\u4EE5\u4E0B\u547D\u4EE4\u66F4\u65B0:"));
-    console.log(colors.cyan(`  npm install -g ${packageName}@latest`));
+    console.log(colors.cyan(`  ${updateCommand}`));
     console.log("");
   }
 }
@@ -978,38 +993,55 @@ async function updateTag() {
   divider();
   const choices = tags.map((tag) => ({ name: tag, value: tag }));
   choices.push({ name: "\u53D6\u6D88", value: "__cancel__" });
-  const tagToUpdate = await select2({
-    message: "\u9009\u62E9\u8981\u4FEE\u6539\u7684 tag:",
+  const oldTag = await select2({
+    message: "\u9009\u62E9\u8981\u91CD\u547D\u540D\u7684 tag:",
     choices,
     theme
   });
-  if (tagToUpdate === "__cancel__") {
+  if (oldTag === "__cancel__") {
     console.log(colors.yellow("\u5DF2\u53D6\u6D88"));
     return;
   }
-  const newMessage = await input2({
-    message: "\u8F93\u5165\u65B0\u7684 tag \u6D88\u606F:",
-    default: `Release ${tagToUpdate}`,
+  console.log("");
+  console.log(colors.dim(`\u5F53\u524D tag: ${oldTag}`));
+  console.log("");
+  const newTag = await input2({
+    message: "\u8F93\u5165\u65B0\u7684 tag \u540D\u79F0:",
+    default: oldTag,
     theme
   });
-  if (!newMessage) {
+  if (!newTag || newTag === oldTag) {
     console.log(colors.yellow("\u5DF2\u53D6\u6D88"));
     return;
   }
+  const existingTags = execOutput("git tag -l").split("\n").filter(Boolean);
+  if (existingTags.includes(newTag)) {
+    console.log(colors.red(`Tag ${newTag} \u5DF2\u5B58\u5728\uFF0C\u65E0\u6CD5\u91CD\u547D\u540D`));
+    return;
+  }
   divider();
-  const spinner = ora2(`\u6B63\u5728\u66F4\u65B0 tag: ${tagToUpdate}`).start();
+  const spinner = ora2(`\u6B63\u5728\u91CD\u547D\u540D tag: ${oldTag} \u2192 ${newTag}`).start();
   try {
-    execSync3(`git tag -d "${tagToUpdate}"`, { stdio: "pipe" });
-    execSync3(`git tag -a "${tagToUpdate}" -m "${newMessage}"`, {
-      stdio: "pipe"
-    });
-    spinner.succeed(`Tag \u5DF2\u66F4\u65B0: ${tagToUpdate}`);
-  } catch {
-    spinner.fail("tag \u66F4\u65B0\u5931\u8D25");
+    const commit2 = execOutput(`git rev-list -n 1 "${oldTag}"`).trim();
+    const message = execOutput(
+      `git tag -l --format='%(contents)' "${oldTag}"`
+    ).trim();
+    if (message) {
+      execSync3(`git tag -a "${newTag}" "${commit2}" -m "${message}"`, {
+        stdio: "pipe"
+      });
+    } else {
+      execSync3(`git tag "${newTag}" "${commit2}"`, { stdio: "pipe" });
+    }
+    execSync3(`git tag -d "${oldTag}"`, { stdio: "pipe" });
+    spinner.succeed(`Tag \u5DF2\u91CD\u547D\u540D: ${oldTag} \u2192 ${newTag}`);
+  } catch (error) {
+    spinner.fail("tag \u91CD\u547D\u540D\u5931\u8D25");
+    console.log(colors.red(String(error)));
     return;
   }
   const pushRemote = await select2({
-    message: "\u662F\u5426\u63A8\u9001\u5230\u8FDC\u7A0B\uFF08\u4F1A\u5F3A\u5236\u8986\u76D6\uFF09?",
+    message: "\u662F\u5426\u540C\u6B65\u5230\u8FDC\u7A0B?",
     choices: [
       { name: "\u662F", value: true },
       { name: "\u5426", value: false }
@@ -1017,13 +1049,16 @@ async function updateTag() {
     theme
   });
   if (pushRemote) {
-    const pushSpinner = ora2("\u6B63\u5728\u63A8\u9001\u5230\u8FDC\u7A0B...").start();
+    const pushSpinner = ora2("\u6B63\u5728\u540C\u6B65\u5230\u8FDC\u7A0B...").start();
     try {
-      execSync3(`git push origin "${tagToUpdate}" --force`, { stdio: "pipe" });
-      pushSpinner.succeed(`Tag \u5DF2\u63A8\u9001: ${tagToUpdate}`);
+      execSync3(`git push origin "${newTag}"`, { stdio: "pipe" });
+      execSync3(`git push origin --delete "${oldTag}"`, { stdio: "pipe" });
+      pushSpinner.succeed(`\u8FDC\u7A0B tag \u5DF2\u540C\u6B65: ${oldTag} \u2192 ${newTag}`);
     } catch {
       pushSpinner.warn(
-        `\u8FDC\u7A0B\u63A8\u9001\u5931\u8D25\uFF0C\u53EF\u7A0D\u540E\u624B\u52A8\u6267\u884C: git push origin ${tagToUpdate} --force`
+        `\u8FDC\u7A0B\u540C\u6B65\u5931\u8D25\uFF0C\u53EF\u7A0D\u540E\u624B\u52A8\u6267\u884C:
+  git push origin ${newTag}
+  git push origin --delete ${oldTag}`
       );
     }
   }
@@ -1882,8 +1917,7 @@ var DEFAULT_COMMIT_TYPES = [
   { type: "test", emoji: "\u2705", description: "\u6D4B\u8BD5\u76F8\u5173" },
   { type: "build", emoji: "\u{1F4E6}", description: "\u6784\u5EFA/\u4F9D\u8D56\u76F8\u5173" },
   { type: "ci", emoji: "\u{1F477}", description: "CI/CD \u76F8\u5173" },
-  { type: "chore", emoji: "\u{1F527}", description: "\u5176\u4ED6\u6742\u9879" },
-  { type: "revert", emoji: "\u23EA", description: "\u56DE\u9000\u63D0\u4EA4" }
+  { type: "chore", emoji: "\u{1F527}", description: "\u5176\u4ED6\u6742\u9879" }
 ];
 function getCommitTypes(config2) {
   const customEmojis = config2.commitEmojis || {};
@@ -1915,11 +1949,17 @@ function parseGitStatus() {
 function formatFileStatus(status) {
   const statusMap = {
     M: colors.yellow("M"),
+    // 修改
     A: colors.green("A"),
+    // 新增
     D: colors.red("D"),
+    // 删除
     R: colors.yellow("R"),
+    // 重命名
     C: colors.yellow("C"),
+    // 复制
     "?": colors.green("?")
+    // 未跟踪
   };
   return statusMap[status] || status;
 }
@@ -1994,7 +2034,7 @@ async function commit() {
       theme
     });
   }
-  let message;
+  let message = "";
   if (commitMode === "ai") {
     const spinner2 = ora4("AI \u6B63\u5728\u5206\u6790\u4EE3\u7801\u53D8\u66F4...").start();
     try {
@@ -2049,6 +2089,17 @@ async function commit() {
   }
   const spinner = ora4("\u6B63\u5728\u63D0\u4EA4...").start();
   try {
+    const finalStatus = parseGitStatus();
+    if (finalStatus.staged.length === 0) {
+      spinner.fail("\u6CA1\u6709\u6682\u5B58\u7684\u6587\u4EF6\u53EF\u4EE5\u63D0\u4EA4");
+      console.log("");
+      console.log(colors.yellow("\u8BF7\u5148\u6682\u5B58\u6587\u4EF6:"));
+      console.log(colors.cyan("  git add <file>"));
+      console.log(colors.dim("  \u6216"));
+      console.log(colors.cyan("  git add -A"));
+      console.log("");
+      return;
+    }
     const escapedMessage = message.replace(/"/g, '\\"');
     execSync5(`git commit -m "${escapedMessage}"`, { stdio: "pipe" });
     spinner.succeed("\u63D0\u4EA4\u6210\u529F");
@@ -2056,19 +2107,31 @@ async function commit() {
     console.log(colors.dim(`commit: ${commitHash}`));
   } catch (error) {
     spinner.fail("\u63D0\u4EA4\u5931\u8D25");
+    console.log("");
     if (error instanceof Error) {
-      console.log(colors.red(error.message));
+      console.log(colors.red("\u9519\u8BEF\u4FE1\u606F:"));
+      console.log(colors.dim(`  ${error.message}`));
     }
+    console.log("");
+    console.log(colors.yellow("\u4F60\u53EF\u4EE5\u624B\u52A8\u6267\u884C\u4EE5\u4E0B\u547D\u4EE4:"));
+    console.log(colors.cyan(`  git commit -m "${message}"`));
+    console.log("");
   }
 }
 async function buildManualCommitMessage(config2) {
   const commitTypes = getCommitTypes(config2);
   const typeChoice = await select6({
     message: "\u9009\u62E9\u63D0\u4EA4\u7C7B\u578B:",
-    choices: commitTypes.map((t) => ({
-      name: `${t.emoji}  ${t.type.padEnd(10)} ${colors.dim(t.description)}`,
-      value: t
-    })),
+    choices: commitTypes.map((t) => {
+      const typeText = t.type.padEnd(10);
+      const spacing = t.type === "refactor" ? "   " : "  ";
+      return {
+        name: `${t.emoji}${spacing}${typeText} ${colors.dim(t.description)}`,
+        value: t
+      };
+    }),
+    pageSize: commitTypes.length,
+    // 显示所有选项，不滚动
     theme
   });
   const scope = await input5({
@@ -2161,7 +2224,7 @@ Tag \u547D\u4EE4:
   gw tag:delete                   \u5220\u9664 tag
   gw td                           \u540C\u4E0A (\u522B\u540D)
 
-  gw tag:update                   \u4FEE\u6539 tag \u6D88\u606F
+  gw tag:update                   \u91CD\u547D\u540D tag
   gw tu                           \u540C\u4E0A (\u522B\u540D)
 
 \u53D1\u5E03\u547D\u4EE4:
@@ -2245,8 +2308,17 @@ async function getLatestVersion2(packageName) {
     return null;
   }
 }
+function isUsingVolta2() {
+  try {
+    const whichGw = execSync7("which gw", { encoding: "utf-8" }).trim();
+    return whichGw.includes(".volta");
+  } catch {
+    return false;
+  }
+}
 async function update(currentVersion) {
   const packageName = "@zjex/git-workflow";
+  const usingVolta = isUsingVolta2();
   console.log("");
   console.log(colors.bold("\u{1F50D} \u68C0\u67E5\u66F4\u65B0..."));
   console.log("");
@@ -2279,12 +2351,6 @@ async function update(currentVersion) {
       return;
     }
     const versionText = `${currentVersion}  \u2192  ${latestVersion}`;
-    const maxWidth = Math.max(
-      "\u{1F389} \u53D1\u73B0\u65B0\u7248\u672C\uFF01".length,
-      versionText.length,
-      "\u2728 \u66F4\u65B0\u5B8C\u6210\uFF01".length,
-      "\u8BF7\u91CD\u65B0\u6253\u5F00\u7EC8\u7AEF\u4F7F\u7528\u65B0\u7248\u672C".length
-    );
     console.log(
       boxen2(
         [
@@ -2305,7 +2371,8 @@ async function update(currentVersion) {
       )
     );
     const updateSpinner = ora6("\u6B63\u5728\u66F4\u65B0...").start();
-    execSync7(`npm install -g ${packageName}@latest`, {
+    const updateCommand = usingVolta ? `volta install ${packageName}@latest` : `npm install -g ${packageName}@latest`;
+    execSync7(updateCommand, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     });
@@ -2317,15 +2384,20 @@ async function update(currentVersion) {
         [
           colors.green(colors.bold("\u2728 \u66F4\u65B0\u5B8C\u6210\uFF01")),
           "",
-          colors.dim("\u8BF7\u91CD\u65B0\u6253\u5F00\u7EC8\u7AEF\u4F7F\u7528\u65B0\u7248\u672C")
+          `\u65B0\u7248\u672C: ${colors.green(colors.bold(latestVersion))}`,
+          "",
+          colors.dim("\u8BF7\u6267\u884C\u4EE5\u4E0B\u547D\u4EE4\u9A8C\u8BC1:"),
+          colors.cyan("  hash -r && gw --version"),
+          "",
+          colors.dim("\u6216\u91CD\u65B0\u6253\u5F00\u7EC8\u7AEF")
         ].join("\n"),
         {
-          padding: { top: 1, bottom: 1, left: 3, right: 3 },
+          padding: { top: 1, bottom: 1, left: 2, right: 2 },
           margin: { top: 0, bottom: 1, left: 2, right: 2 },
           borderStyle: "round",
           borderColor: "green",
-          align: "center",
-          width: 40
+          align: "left",
+          width: 50
         }
       )
     );
@@ -2334,7 +2406,8 @@ async function update(currentVersion) {
     spinner.fail(colors.red("\u66F4\u65B0\u5931\u8D25"));
     console.log("");
     console.log(colors.dim("  \u4F60\u53EF\u4EE5\u624B\u52A8\u8FD0\u884C\u4EE5\u4E0B\u547D\u4EE4\u66F4\u65B0:"));
-    console.log(colors.cyan(`  npm install -g ${packageName}@latest`));
+    const updateCommand = usingVolta ? `volta install ${packageName}@latest` : `npm install -g ${packageName}@latest`;
+    console.log(colors.cyan(`  ${updateCommand}`));
     console.log("");
     process.exit(1);
   }
@@ -2365,7 +2438,7 @@ process.on("SIGTERM", () => {
   console.log("");
   process.exit(0);
 });
-var version = true ? "0.2.20" : "0.0.0-dev";
+var version = true ? "0.2.22" : "0.0.0-dev";
 async function mainMenu() {
   console.log(
     colors.green(`
@@ -2407,7 +2480,7 @@ async function mainMenu() {
         value: "tag-delete"
       },
       {
-        name: `[7] \u270F\uFE0F  \u4FEE\u6539 tag               ${colors.dim("gw tu")}`,
+        name: `[7] \u270F\uFE0F  \u91CD\u547D\u540D tag               ${colors.dim("gw tu")}`,
         value: "tag-update"
       },
       {
@@ -2517,7 +2590,7 @@ cli.command("tag:delete", "\u5220\u9664 tag").alias("td").action(async () => {
   checkGitRepo();
   return deleteTag();
 });
-cli.command("tag:update", "\u4FEE\u6539 tag \u6D88\u606F").alias("tu").action(async () => {
+cli.command("tag:update", "\u91CD\u547D\u540D tag").alias("tu").action(async () => {
   await checkForUpdates(version, "@zjex/git-workflow");
   checkGitRepo();
   return updateTag();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zjex/git-workflow",
-	"version": "0.2.20",
+	"version": "0.2.22",
 	"description": "🚀 极简的 Git 工作流 CLI 工具，让分支管理和版本发布变得轻松愉快",
 	"type": "module",
 	"bin": {

package/src/commands/commit.ts

@@ -5,7 +5,11 @@ import { colors, theme, execOutput, divider } from "../utils.js";
 import { getConfig } from "../config.js";
 import { generateAICommitMessage, isAICommitAvailable } from "../ai-service.js";
 
-// Conventional Commits 类型 + Gitmoji
+/**
+ * Conventional Commits 类型定义 + Gitmoji
+ * 遵循 https://www.conventionalcommits.org/ 规范
+ * 使用 https://gitmoji.dev/ emoji
+ */
 const DEFAULT_COMMIT_TYPES = [
   { type: "feat", emoji: "✨", description: "新功能" },
   { type: "fix", emoji: "🐛", description: "修复 Bug" },
@@ -17,11 +21,15 @@ const DEFAULT_COMMIT_TYPES = [
   { type: "build", emoji: "📦", description: "构建/依赖相关" },
   { type: "ci", emoji: "👷", description: "CI/CD 相关" },
   { type: "chore", emoji: "🔧", description: "其他杂项" },
-  { type: "revert", emoji: "⏪", description: "回退提交" },
 ] as const;
 
 type CommitType = (typeof DEFAULT_COMMIT_TYPES)[number]["type"];
 
+/**
+ * 获取提交类型列表（支持自定义 emoji）
+ * @param config 用户配置
+ * @returns 提交类型列表
+ */
 function getCommitTypes(config: ReturnType<typeof getConfig>) {
   const customEmojis = config.commitEmojis || {};
   return DEFAULT_COMMIT_TYPES.map((item) => ({
@@ -30,11 +38,18 @@ function getCommitTypes(config: ReturnType<typeof getConfig>) {
   }));
 }
 
+/**
+ * 文件状态接口
+ */
 interface FileStatus {
-  status: string;
-  file: string;
+  status: string; // M=修改, A=新增, D=删除, ?=未跟踪
+  file: string; // 文件路径
 }
 
+/**
+ * 解析 git status 输出
+ * @returns 已暂存和未暂存的文件列表
+ */
 function parseGitStatus(): { staged: FileStatus[]; unstaged: FileStatus[] } {
   const output = execOutput("git status --porcelain");
   if (!output) return { staged: [], unstaged: [] };
@@ -44,9 +59,9 @@ function parseGitStatus(): { staged: FileStatus[]; unstaged: FileStatus[] } {
 
   for (const line of output.split("\n")) {
     if (!line) continue;
-    const indexStatus = line[0];
-    const workTreeStatus = line[1];
-    const file = line.slice(3);
+    const indexStatus = line[0]; // 暂存区状态
+    const workTreeStatus = line[1]; // 工作区状态
+    const file = line.slice(3); // 文件路径
 
     // 已暂存的更改 (index 有状态)
     if (indexStatus !== " " && indexStatus !== "?") {
@@ -63,23 +78,33 @@ function parseGitStatus(): { staged: FileStatus[]; unstaged: FileStatus[] } {
   return { staged, unstaged };
 }
 
+/**
+ * 格式化文件状态显示（带颜色）
+ * @param status 文件状态
+ * @returns 带颜色的状态字符串
+ */
 function formatFileStatus(status: string): string {
   const statusMap: Record<string, string> = {
-    M: colors.yellow("M"),
-    A: colors.green("A"),
-    D: colors.red("D"),
-    R: colors.yellow("R"),
-    C: colors.yellow("C"),
-    "?": colors.green("?"),
+    M: colors.yellow("M"), // 修改
+    A: colors.green("A"), // 新增
+    D: colors.red("D"), // 删除
+    R: colors.yellow("R"), // 重命名
+    C: colors.yellow("C"), // 复制
+    "?": colors.green("?"), // 未跟踪
   };
   return statusMap[status] || status;
 }
 
+/**
+ * 交互式提交命令
+ * 支持 AI 自动生成和手动编写两种模式
+ * 遵循 Conventional Commits 规范
+ */
 export async function commit(): Promise<void> {
   const config = getConfig();
   let { staged, unstaged } = parseGitStatus();
 
-  // 如果有未暂存的更改，根据配置决定是否自动暂存
+  // ========== 步骤 1: 处理未暂存的文件 ==========
   if (unstaged.length > 0) {
     const autoStage = config.autoStage ?? true;
 
@@ -131,7 +156,7 @@ export async function commit(): Promise<void> {
     }
   }
 
-  // 没有暂存的更改
+  // ========== 步骤 2: 检查是否有文件可提交 ==========
   if (staged.length === 0) {
     console.log(colors.yellow("工作区干净，没有需要提交的更改"));
     return;
@@ -144,7 +169,7 @@ export async function commit(): Promise<void> {
   }
   divider();
 
-  // 询问用户选择手动还是 AI 生成
+  // ========== 步骤 3: 选择提交方式（AI 或手动）==========
   const aiAvailable = isAICommitAvailable(config);
   let commitMode: "ai" | "manual" = "manual";
 
@@ -167,10 +192,12 @@ export async function commit(): Promise<void> {
     });
   }
 
-  let message: string;
+  // 初始化 commit message 变量
+  let message: string = "";
 
+  // ========== 步骤 4: 生成 commit message ==========
+  // AI 生成模式
   if (commitMode === "ai") {
-    // AI 生成模式
     const spinner = ora("AI 正在分析代码变更...").start();
 
     try {
@@ -208,11 +235,12 @@ export async function commit(): Promise<void> {
     }
   }
 
+  // 手动输入模式
   if (commitMode === "manual") {
-    // 手动输入模式（原有逻辑）
     message = await buildManualCommitMessage(config);
   }
 
+  // ========== 步骤 5: 预览并确认提交 ==========
   divider();
   console.log("提交信息预览:");
   console.log(colors.green(message));
@@ -232,9 +260,23 @@ export async function commit(): Promise<void> {
     return;
   }
 
+  // ========== 步骤 6: 执行提交 ==========
   const spinner = ora("正在提交...").start();
 
   try {
+    // 提交前再次检查是否有暂存的文件
+    const finalStatus = parseGitStatus();
+    if (finalStatus.staged.length === 0) {
+      spinner.fail("没有暂存的文件可以提交");
+      console.log("");
+      console.log(colors.yellow("请先暂存文件:"));
+      console.log(colors.cyan("  git add <file>"));
+      console.log(colors.dim("  或"));
+      console.log(colors.cyan("  git add -A"));
+      console.log("");
+      return;
+    }
+
     // 使用 -m 参数，需要转义引号
     const escapedMessage = message.replace(/"/g, '\\"');
     execSync(`git commit -m "${escapedMessage}"`, { stdio: "pipe" });
@@ -245,14 +287,26 @@ export async function commit(): Promise<void> {
     console.log(colors.dim(`commit: ${commitHash}`));
   } catch (error) {
     spinner.fail("提交失败");
+    console.log("");
+
+    // 显示详细错误信息
     if (error instanceof Error) {
-      console.log(colors.red(error.message));
+      console.log(colors.red("错误信息:"));
+      console.log(colors.dim(`  ${error.message}`));
     }
+
+    console.log("");
+    console.log(colors.yellow("你可以手动执行以下命令:"));
+    console.log(colors.cyan(`  git commit -m "${message}"`));
+    console.log("");
   }
 }
 
 /**
  * 手动构建 commit message
+ * 通过交互式问答收集信息，构建符合 Conventional Commits 规范的提交信息
+ * @param config 用户配置
+ * @returns 完整的 commit message
  */
 async function buildManualCommitMessage(
   config: ReturnType<typeof getConfig>
@@ -260,23 +314,30 @@ async function buildManualCommitMessage(
   // 获取提交类型（支持自定义 emoji）
   const commitTypes = getCommitTypes(config);
 
-  // 选择提交类型
+  // ========== 1. 选择提交类型 ==========
   const typeChoice = await select({
     message: "选择提交类型:",
-    choices: commitTypes.map((t) => ({
-      name: `${t.emoji}  ${t.type.padEnd(10)} ${colors.dim(t.description)}`,
-      value: t,
-    })),
+    choices: commitTypes.map((t) => {
+      // 使用固定宽度格式化，不依赖 emoji 宽度
+      const typeText = t.type.padEnd(10);
+      // 针对 refactor 特殊处理，因为 ♻️ emoji 在不同终端宽度不一致
+      const spacing = t.type === "refactor" ? "   " : "  ";
+      return {
+        name: `${t.emoji}${spacing}${typeText} ${colors.dim(t.description)}`,
+        value: t,
+      };
+    }),
+    pageSize: commitTypes.length, // 显示所有选项，不滚动
     theme,
   });
 
-  // 输入 scope (可选)
+  // ========== 2. 输入 scope (可选) ==========
   const scope = await input({
     message: "输入影响范围 scope (可跳过):",
     theme,
   });
 
-  // 输入简短描述
+  // ========== 3. 输入简短描述 (必填) ==========
   const subject = await input({
     message: "输入简短描述:",
     validate: (value) => {
@@ -287,13 +348,13 @@ async function buildManualCommitMessage(
     theme,
   });
 
-  // 输入详细描述 (可选)
+  // ========== 4. 输入详细描述 (可选) ==========
   const body = await input({
     message: "输入详细描述 (可跳过):",
     theme,
   });
 
-  // 是否有破坏性变更
+  // ========== 5. 是否有破坏性变更 ==========
   const hasBreaking = await select({
     message: "是否包含破坏性变更 (BREAKING CHANGE)?",
     choices: [
@@ -312,13 +373,13 @@ async function buildManualCommitMessage(
     });
   }
 
-  // 关联 Issue (可选)
+  // ========== 6. 关联 Issue (可选) ==========
   const issues = await input({
     message: "关联 Issue (如 #123, 可跳过):",
     theme,
   });
 
-  // 构建 commit message
+  // ========== 7. 构建 commit message ==========
   const { type, emoji } = typeChoice;
   const scopePart = scope ? `(${scope})` : "";
   const breakingMark = hasBreaking ? "!" : "";
@@ -330,7 +391,7 @@ async function buildManualCommitMessage(
   // Header: [emoji] type(scope)!: subject
   let message = `${emojiPrefix}${type}${scopePart}${breakingMark}: ${subject}`;
 
-  // Body
+  // Body (可选)
   if (body || hasBreaking || issues) {
     message += "\n";
 

package/src/commands/help.ts

@@ -25,7 +25,7 @@ Tag 命令:
   gw tag:delete                   删除 tag
   gw td                           同上 (别名)
 
-  gw tag:update                   修改 tag 消息
+  gw tag:update                   重命名 tag
   gw tu                           同上 (别名)
 
 发布命令:

package/src/commands/tag.ts

@@ -417,7 +417,7 @@ export async function deleteTag(): Promise<void> {
 }
 
 /**
- * 修改 tag（重新打标签）
+ * 修改 tag 名称（重命名 tag）
  */
 export async function updateTag(): Promise<void> {
   const fetchSpinner = ora("正在获取 tags...").start();
@@ -438,47 +438,71 @@ export async function updateTag(): Promise<void> {
   const choices = tags.map((tag) => ({ name: tag, value: tag }));
   choices.push({ name: "取消", value: "__cancel__" });
 
-  const tagToUpdate = await select({
-    message: "选择要修改的 tag:",
+  const oldTag = await select({
+    message: "选择要重命名的 tag:",
     choices,
     theme,
   });
 
-  if (tagToUpdate === "__cancel__") {
+  if (oldTag === "__cancel__") {
     console.log(colors.yellow("已取消"));
     return;
   }
 
-  const newMessage = await input({
-    message: "输入新的 tag 消息:",
-    default: `Release ${tagToUpdate}`,
+  console.log("");
+  console.log(colors.dim(`当前 tag: ${oldTag}`));
+  console.log("");
+
+  const newTag = await input({
+    message: "输入新的 tag 名称:",
+    default: oldTag,
     theme,
   });
 
-  if (!newMessage) {
+  if (!newTag || newTag === oldTag) {
     console.log(colors.yellow("已取消"));
     return;
   }
 
+  // 检查新 tag 是否已存在
+  const existingTags = execOutput("git tag -l").split("\n").filter(Boolean);
+  if (existingTags.includes(newTag)) {
+    console.log(colors.red(`Tag ${newTag} 已存在，无法重命名`));
+    return;
+  }
+
   divider();
 
-  const spinner = ora(`正在更新 tag: ${tagToUpdate}`).start();
+  const spinner = ora(`正在重命名 tag: ${oldTag} → ${newTag}`).start();
 
   try {
+    // 获取旧 tag 的 commit 和消息
+    const commit = execOutput(`git rev-list -n 1 "${oldTag}"`).trim();
+    const message = execOutput(
+      `git tag -l --format='%(contents)' "${oldTag}"`
+    ).trim();
+
+    // 创建新 tag（指向同一个 commit）
+    if (message) {
+      execSync(`git tag -a "${newTag}" "${commit}" -m "${message}"`, {
+        stdio: "pipe",
+      });
+    } else {
+      execSync(`git tag "${newTag}" "${commit}"`, { stdio: "pipe" });
+    }
+
     // 删除旧 tag
-    execSync(`git tag -d "${tagToUpdate}"`, { stdio: "pipe" });
-    // 创建新 tag（在同一个 commit 上）
-    execSync(`git tag -a "${tagToUpdate}" -m "${newMessage}"`, {
-      stdio: "pipe",
-    });
-    spinner.succeed(`Tag 已更新: ${tagToUpdate}`);
-  } catch {
-    spinner.fail("tag 更新失败");
+    execSync(`git tag -d "${oldTag}"`, { stdio: "pipe" });
+
+    spinner.succeed(`Tag 已重命名: ${oldTag} → ${newTag}`);
+  } catch (error) {
+    spinner.fail("tag 重命名失败");
+    console.log(colors.red(String(error)));
     return;
   }
 
   const pushRemote = await select({
-    message: "是否推送到远程（会强制覆盖）?",
+    message: "是否同步到远程?",
     choices: [
       { name: "是", value: true },
       { name: "否", value: false },
@@ -487,13 +511,16 @@ export async function updateTag(): Promise<void> {
   });
 
   if (pushRemote) {
-    const pushSpinner = ora("正在推送到远程...").start();
+    const pushSpinner = ora("正在同步到远程...").start();
     try {
-      execSync(`git push origin "${tagToUpdate}" --force`, { stdio: "pipe" });
-      pushSpinner.succeed(`Tag 已推送: ${tagToUpdate}`);
+      // 推送新 tag
+      execSync(`git push origin "${newTag}"`, { stdio: "pipe" });
+      // 删除远程旧 tag
+      execSync(`git push origin --delete "${oldTag}"`, { stdio: "pipe" });
+      pushSpinner.succeed(`远程 tag 已同步: ${oldTag} → ${newTag}`);
     } catch {
       pushSpinner.warn(
-        `远程推送失败，可稍后手动执行: git push origin ${tagToUpdate} --force`
+        `远程同步失败，可稍后手动执行:\n  git push origin ${newTag}\n  git push origin --delete ${oldTag}`
       );
     }
   }

package/src/commands/update.ts

@@ -39,11 +39,24 @@ async function getLatestVersion(packageName: string): Promise<string | null> {
   }
 }
 
+/**
+ * 检测是否使用 Volta
+ */
+function isUsingVolta(): boolean {
+  try {
+    const whichGw = execSync("which gw", { encoding: "utf-8" }).trim();
+    return whichGw.includes(".volta");
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 手动更新命令
  */
 export async function update(currentVersion: string): Promise<void> {
   const packageName = "@zjex/git-workflow";
+  const usingVolta = isUsingVolta();
 
   console.log("");
   console.log(colors.bold("🔍 检查更新..."));
@@ -85,12 +98,6 @@ export async function update(currentVersion: string): Promise<void> {
 
     // 有新版本
     const versionText = `${currentVersion}  →  ${latestVersion}`;
-    const maxWidth = Math.max(
-      "🎉 发现新版本！".length,
-      versionText.length,
-      "✨ 更新完成！".length,
-      "请重新打开终端使用新版本".length
-    );
 
     console.log(
       boxen(
@@ -115,7 +122,12 @@ export async function update(currentVersion: string): Promise<void> {
     // 开始更新
     const updateSpinner = ora("正在更新...").start();
 
-    execSync(`npm install -g ${packageName}@latest`, {
+    // 根据包管理器选择更新命令
+    const updateCommand = usingVolta
+      ? `volta install ${packageName}@latest`
+      : `npm install -g ${packageName}@latest`;
+
+    execSync(updateCommand, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
     });
@@ -131,15 +143,20 @@ export async function update(currentVersion: string): Promise<void> {
         [
           colors.green(colors.bold("✨ 更新完成！")),
           "",
-          colors.dim("请重新打开终端使用新版本"),
+          `新版本: ${colors.green(colors.bold(latestVersion))}`,
+          "",
+          colors.dim("请执行以下命令验证:"),
+          colors.cyan("  hash -r && gw --version"),
+          "",
+          colors.dim("或重新打开终端"),
         ].join("\n"),
         {
-          padding: { top: 1, bottom: 1, left: 3, right: 3 },
+          padding: { top: 1, bottom: 1, left: 2, right: 2 },
           margin: { top: 0, bottom: 1, left: 2, right: 2 },
           borderStyle: "round",
           borderColor: "green",
-          align: "center",
-          width: 40,
+          align: "left",
+          width: 50,
         }
       )
     );
@@ -150,7 +167,10 @@ export async function update(currentVersion: string): Promise<void> {
     spinner.fail(colors.red("更新失败"));
     console.log("");
     console.log(colors.dim("  你可以手动运行以下命令更新:"));
-    console.log(colors.cyan(`  npm install -g ${packageName}@latest`));
+    const updateCommand = usingVolta
+      ? `volta install ${packageName}@latest`
+      : `npm install -g ${packageName}@latest`;
+    console.log(colors.cyan(`  ${updateCommand}`));
     console.log("");
     process.exit(1);
   }

package/src/index.ts

@@ -1,3 +1,13 @@
+/**
+ * @zjex/git-workflow - Git 工作流 CLI 工具
+ *
+ * 主入口文件，负责：
+ * 1. 初始化 CLI 应用
+ * 2. 注册所有命令
+ * 3. 处理全局错误和信号
+ * 4. 显示交互式主菜单
+ */
+
 // @ts-nocheck shebang handled by tsup banner
 
 import { cac } from "cac";
@@ -14,7 +24,12 @@ import { showHelp } from "./commands/help.js";
 import { checkForUpdates } from "./update-notifier.js";
 import { update } from "./commands/update.js";
 
-// 捕获 Ctrl+C 退出，静默处理
+// ========== 全局错误处理 ==========
+
+/**
+ * 捕获未捕获的异常
+ * 主要用于优雅处理用户按 Ctrl+C 退出的情况
+ */
 process.on("uncaughtException", (err) => {
   if (err instanceof ExitPromptError) {
     console.log(""); // 输出空行，让界面更整洁
@@ -24,7 +39,9 @@ process.on("uncaughtException", (err) => {
   process.exit(1);
 });
 
-// 捕获未处理的 Promise 拒绝
+/**
+ * 捕获未处理的 Promise 拒绝
+ */
 process.on("unhandledRejection", (reason) => {
   if (reason instanceof ExitPromptError) {
     console.log("");
@@ -34,29 +51,50 @@ process.on("unhandledRejection", (reason) => {
   process.exit(1);
 });
 
-// 捕获 SIGINT 信号 (Ctrl+C)
+/**
+ * 捕获 SIGINT 信号 (Ctrl+C)
+ * 确保用户按 Ctrl+C 时能优雅退出
+ */
 process.on("SIGINT", () => {
   console.log("");
   process.exit(0);
 });
 
-// 捕获 SIGTERM 信号
+/**
+ * 捕获 SIGTERM 信号
+ * 处理进程终止信号
+ */
 process.on("SIGTERM", () => {
   console.log("");
   process.exit(0);
 });
 
+// ========== 版本信息 ==========
+
+/**
+ * 版本号由构建工具注入
+ * 开发环境下使用 0.0.0-dev
+ */
 declare const __VERSION__: string | undefined;
 
-// 开发环境下从 package.json 读取版本号
+/**
+ * 当前版本号
+ * 生产环境：从构建时注入的 __VERSION__ 获取
+ * 开发环境：使用 0.0.0-dev
+ */
 const version: string =
   typeof __VERSION__ !== "undefined" && __VERSION__ !== ""
     ? __VERSION__
     : "0.0.0-dev";
 
-// 交互式主菜单
+// ========== 交互式主菜单 ==========
+
+/**
+ * 显示交互式主菜单
+ * 提供所有可用命令的可视化选择界面
+ */
 async function mainMenu(): Promise<void> {
-  // ASCII Art Logo
+  // 显示 ASCII Art Logo
   console.log(
     colors.green(`
  ███████╗     ██╗███████╗██╗  ██╗
@@ -97,7 +135,7 @@ async function mainMenu(): Promise<void> {
         value: "tag-delete",
       },
       {
-        name: `[7] ✏️  修改 tag               ${colors.dim("gw tu")}`,
+        name: `[7] ✏️  重命名 tag               ${colors.dim("gw tu")}`,
         value: "tag-update",
       },
       {
@@ -174,9 +212,20 @@ async function mainMenu(): Promise<void> {
   }
 }
 
+// ========== CLI 应用初始化 ==========
+
+/**
+ * 创建 CLI 应用实例
+ * 使用 cac (Command And Conquer) 库
+ */
 const cli = cac("gw");
 
-// 默认命令 - 显示交互式菜单
+// ========== 命令注册 ==========
+
+/**
+ * 默认命令 - 显示交互式菜单
+ * 运行 `gw` 时触发，会检查更新（交互式模式）
+ */
 cli.command("", "显示交互式菜单").action(async () => {
   await checkForUpdates(version, "@zjex/git-workflow", true);
   return mainMenu();
@@ -242,7 +291,7 @@ cli
   });
 
 cli
-  .command("tag:update", "修改 tag 消息")
+  .command("tag:update", "重命名 tag")
   .alias("tu")
   .action(async () => {
     await checkForUpdates(version, "@zjex/git-workflow");

package/src/update-notifier.ts

@@ -107,6 +107,18 @@ function backgroundCheck(currentVersion: string, packageName: string): void {
   });
 }
 
+/**
+ * 检测是否使用 Volta
+ */
+function isUsingVolta(): boolean {
+  try {
+    const whichGw = execSync("which gw", { encoding: "utf-8" }).trim();
+    return whichGw.includes(".volta");
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 获取 npm 上的最新版本
  */
@@ -172,6 +184,11 @@ async function showUpdateMessage(
     })
   );
 
+  const usingVolta = isUsingVolta();
+  const updateCommand = usingVolta
+    ? `volta install ${packageName}@latest`
+    : `npm install -g ${packageName}@latest`;
+
   try {
     const action = await select({
       message: "你想做什么？",
@@ -179,7 +196,7 @@ async function showUpdateMessage(
         {
           name: "🚀 立即更新",
           value: "update",
-          description: `运行 npm install -g ${packageName}`,
+          description: `运行 ${updateCommand}`,
         },
         {
           name: "⏭️  稍后更新，继续使用",
@@ -208,14 +225,19 @@ async function showUpdateMessage(
 async function performUpdate(packageName: string): Promise<void> {
   console.log("");
 
+  const usingVolta = isUsingVolta();
+  const updateCommand = usingVolta
+    ? `volta install ${packageName}@latest`
+    : `npm install -g ${packageName}@latest`;
+
   const spinner = ora({
     text: "正在更新...",
     spinner: "dots",
   }).start();
 
   try {
-    // 直接安装最新版本（npm 会自动覆盖旧版本）
-    execSync(`npm install -g ${packageName}@latest`, {
+    // 根据包管理器选择更新命令
+    execSync(updateCommand, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
     });
@@ -231,15 +253,18 @@ async function performUpdate(packageName: string): Promise<void> {
         [
           colors.green(colors.bold("✨ 更新完成！")),
           "",
-          colors.dim("请重新打开终端使用新版本"),
+          colors.dim("请执行以下命令验证:"),
+          colors.cyan("  hash -r && gw --version"),
+          "",
+          colors.dim("或重新打开终端"),
         ].join("\n"),
         {
-          padding: { top: 1, bottom: 1, left: 3, right: 3 },
+          padding: { top: 1, bottom: 1, left: 2, right: 2 },
           margin: { top: 0, bottom: 1, left: 2, right: 2 },
           borderStyle: "round",
           borderColor: "green",
-          align: "center",
-          width: 40,
+          align: "left",
+          width: 50,
         }
       )
     );
@@ -250,7 +275,7 @@ async function performUpdate(packageName: string): Promise<void> {
     spinner.fail(colors.red("更新失败"));
     console.log("");
     console.log(colors.dim("  你可以手动运行以下命令更新:"));
-    console.log(colors.cyan(`  npm install -g ${packageName}@latest`));
+    console.log(colors.cyan(`  ${updateCommand}`));
     console.log("");
   }
 }