clawt 2.12.0 → 2.13.0

package/README.md

@@ -19,22 +19,19 @@ npm i -g clawt
 ```bash
 # 1. 在项目根目录（包含 .git 的目录）下执行
 # 2. 并行执行 3 个任务，每个任务在独立的 worktree 中运行
-clawt run -b feature-auth \
-  --tasks "实现用户登录功能" \
-  --tasks "实现用户注册功能" \
-  --tasks "实现密码重置功能"
+clawt run -b <branch-1>
+clawt run -b <branch-2>
+clawt run -b <branch-3>
 
 # 3. 查看所有 worktree 状态
 clawt status
 
 # 4. 验证某个分支的变更（在主 worktree 中测试）
-clawt validate -b feature-auth-1
+clawt validate -b branch-1
 
 # 5. 确认无误后合并到主分支
-clawt merge -b feature-auth-1 -m "feat: 实现用户登录功能"
+clawt merge -b branch-1 -m "feat: 实现xxx功能"
 
-# 6. 清理不需要的 worktree
-clawt remove -b feature-auth
 ```
 
 ## 命令一览
@@ -153,6 +150,33 @@ clawt config          # 查看当前配置
 clawt config reset    # 恢复默认配置
 ```
 
+### `clawt alias` — 管理命令别名
+
+```bash
+clawt alias                          # 列出所有命令别名
+clawt alias list                     # 列出所有命令别名
+clawt alias set <alias> <command>    # 设置命令别名
+clawt alias remove <alias>           # 移除命令别名
+```
+
+**使用示例：**
+
+```bash
+# 设置别名
+clawt alias set l list
+clawt alias set r run
+clawt alias set v validate
+
+# 使用别名（等同于对应的完整命令）
+clawt l          # 等同于 clawt list
+clawt r task.md  # 等同于 clawt run task.md
+
+# 移除别名
+clawt alias remove l
+```
+
+> **约束：** 别名不能覆盖内置命令名，目标必须是已注册的内置命令。别名的选项和参数会完全透传给目标命令。
+
 ## 配置
 
 配置文件位于 `~/.clawt/config.json`，安装后自动生成：
@@ -165,6 +189,7 @@ clawt config reset    # 恢复默认配置
 | `confirmDestructiveOps` | `true` | 破坏性操作前确认 |
 | `maxConcurrency` | `0` | run 命令最大并发数，`0` 为不限制 |
 | `terminalApp` | `"auto"` | 批量 resume 使用的终端：`auto` / `iterm2` / `terminal` |
+| `aliases` | `{}` | 命令别名映射（如 `{"l": "list", "r": "run"}`） |
 
 ## 全局选项
 

package/dist/index.js

@@ -119,7 +119,7 @@ var MERGE_MESSAGES = {
   /** merge 后清理 worktree 和分支成功 */
   WORKTREE_CLEANED: (branch) => `\u2713 \u5DF2\u6E05\u7406 worktree \u548C\u5206\u652F: ${branch}`,
   /** 目标 worktree 有未提交修改但未指定 -m */
-  TARGET_WORKTREE_DIRTY_NO_MESSAGE: "\u76EE\u6807 worktree \u6709\u672A\u63D0\u4EA4\u7684\u4FEE\u6539\uFF0C\u8BF7\u901A\u8FC7 -m \u53C2\u6570\u63D0\u4F9B\u63D0\u4EA4\u4FE1\u606F",
+  TARGET_WORKTREE_DIRTY_NO_MESSAGE: (worktreePath) => `${worktreePath} \u6709\u672A\u63D0\u4EA4\u7684\u4FEE\u6539\uFF0C\u8BF7\u901A\u8FC7 -m \u53C2\u6570\u63D0\u4F9B\u63D0\u4EA4\u4FE1\u606F`,
   /** 目标 worktree 既干净又无本地提交 */
   TARGET_WORKTREE_NO_CHANGES: "\u76EE\u6807 worktree \u6CA1\u6709\u4EFB\u4F55\u53EF\u5408\u5E76\u7684\u53D8\u66F4\uFF08\u5DE5\u4F5C\u533A\u5E72\u51C0\u4E14\u65E0\u672C\u5730\u63D0\u4EA4\uFF09",
   /** merge 命令检测到 validate 状态的提示 */
@@ -280,6 +280,24 @@ var STATUS_MESSAGES = {
   STATUS_SNAPSHOT_ORPHANED: "(\u5BF9\u5E94 worktree \u5DF2\u4E0D\u5B58\u5728)"
 };
 
+// src/constants/messages/alias.ts
+var ALIAS_MESSAGES = {
+  /** 别名列表为空 */
+  ALIAS_LIST_EMPTY: "(\u65E0\u522B\u540D)",
+  /** 别名设置成功 */
+  ALIAS_SET_SUCCESS: (alias, command) => `\u2713 \u5DF2\u8BBE\u7F6E\u522B\u540D: ${alias} \u2192 ${command}`,
+  /** 别名移除成功 */
+  ALIAS_REMOVE_SUCCESS: (alias) => `\u2713 \u5DF2\u79FB\u9664\u522B\u540D: ${alias}`,
+  /** 别名不存在 */
+  ALIAS_NOT_FOUND: (alias) => `\u522B\u540D "${alias}" \u4E0D\u5B58\u5728`,
+  /** 别名与内置命令冲突 */
+  ALIAS_CONFLICTS_BUILTIN: (alias) => `\u522B\u540D "${alias}" \u4E0E\u5185\u7F6E\u547D\u4EE4\u51B2\u7A81\uFF0C\u4E0D\u5141\u8BB8\u8986\u76D6\u5185\u7F6E\u547D\u4EE4`,
+  /** 目标命令不存在 */
+  ALIAS_TARGET_NOT_FOUND: (command) => `\u76EE\u6807\u547D\u4EE4 "${command}" \u4E0D\u5B58\u5728\uFF0C\u8BF7\u6307\u5B9A\u5DF2\u6CE8\u518C\u7684\u5185\u7F6E\u547D\u4EE4\u540D`,
+  /** 别名列表标题 */
+  ALIAS_LIST_TITLE: "\u5F53\u524D\u522B\u540D\u5217\u8868\uFF1A"
+};
+
 // src/constants/messages/index.ts
 var MESSAGES = {
   ...COMMON_MESSAGES,
@@ -292,7 +310,8 @@ var MESSAGES = {
   ...REMOVE_MESSAGES,
   ...RESET_MESSAGES,
   ...CONFIG_CMD_MESSAGES,
-  ...STATUS_MESSAGES
+  ...STATUS_MESSAGES,
+  ...ALIAS_MESSAGES
 };
 
 // src/constants/exitCodes.ts
@@ -335,6 +354,10 @@ var CONFIG_DEFINITIONS = {
   terminalApp: {
     defaultValue: "auto",
     description: "\u6279\u91CF resume \u4F7F\u7528\u7684\u7EC8\u7AEF\u5E94\u7528\uFF1Aauto\uFF08\u81EA\u52A8\u68C0\u6D4B\uFF09\u3001iterm2\u3001terminal\uFF08macOS\uFF09"
+  },
+  aliases: {
+    defaultValue: {},
+    description: "\u547D\u4EE4\u522B\u540D\u6620\u5C04\uFF08\u901A\u8FC7 clawt alias \u547D\u4EE4\u7BA1\u7406\uFF09"
   }
 };
 function deriveDefaultConfig(definitions) {
@@ -907,12 +930,15 @@ function loadConfig() {
     return { ...DEFAULT_CONFIG };
   }
 }
+function writeConfig(config2) {
+  writeFileSync(CONFIG_PATH, JSON.stringify(config2, null, 2), "utf-8");
+}
 function writeDefaultConfig() {
-  writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2), "utf-8");
+  writeConfig(DEFAULT_CONFIG);
 }
 function getConfigValue(key) {
-  const config = loadConfig();
-  return config[key];
+  const config2 = loadConfig();
+  return config2[key];
 }
 function ensureClawtDirs() {
   ensureDir(CLAWT_HOME);
@@ -1692,6 +1718,19 @@ async function executeBatchTasks(worktrees, tasks, concurrency) {
   printTaskSummary(summary);
 }
 
+// src/utils/alias.ts
+function applyAliases(program2, aliases) {
+  for (const [alias, commandName] of Object.entries(aliases)) {
+    const targetCmd = program2.commands.find((cmd) => cmd.name() === commandName);
+    if (targetCmd) {
+      targetCmd.alias(alias);
+      logger.debug(`\u5DF2\u6CE8\u518C\u522B\u540D: ${alias} \u2192 ${commandName}`);
+    } else {
+      logger.warn(`\u522B\u540D "${alias}" \u7684\u76EE\u6807\u547D\u4EE4 "${commandName}" \u4E0D\u5B58\u5728\uFF0C\u5DF2\u8DF3\u8FC7`);
+    }
+  }
+}
+
 // src/commands/list.ts
 import chalk4 from "chalk";
 function registerListCommand(program2) {
@@ -2205,7 +2244,7 @@ async function handleMerge(options) {
   const targetClean = isWorkingDirClean(targetWorktreePath);
   if (!targetClean) {
     if (!options.message) {
-      throw new ClawtError(MESSAGES.TARGET_WORKTREE_DIRTY_NO_MESSAGE);
+      throw new ClawtError(MESSAGES.TARGET_WORKTREE_DIRTY_NO_MESSAGE(targetWorktreePath));
     }
     gitAddAll(targetWorktreePath);
     gitCommit(options.message, targetWorktreePath);
@@ -2270,7 +2309,7 @@ function registerConfigCommand(program2) {
   });
 }
 function handleConfig() {
-  const config = loadConfig();
+  const config2 = loadConfig();
   logger.info("config \u547D\u4EE4\u6267\u884C\uFF0C\u5C55\u793A\u5168\u5C40\u914D\u7F6E");
   printInfo(`
 ${chalk5.dim("\u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84:")} ${CONFIG_PATH}
@@ -2279,7 +2318,7 @@ ${chalk5.dim("\u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84:")} ${CONFIG_PATH}
   const keys = Object.keys(DEFAULT_CONFIG);
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
-    const value = config[key];
+    const value = config2[key];
     const description = CONFIG_DESCRIPTIONS[key];
     const formattedValue = formatConfigValue(value);
     if (i === 0) printInfo("");
@@ -2306,6 +2345,14 @@ function formatConfigValue(value) {
   if (typeof value === "boolean") {
     return value ? chalk5.green("true") : chalk5.yellow("false");
   }
+  if (typeof value === "object" && value !== null) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+      return chalk5.dim("(\u65E0)");
+    }
+    const lines = entries.map(([k, v]) => `    ${chalk5.cyan(k)} \u2192 ${chalk5.cyan(String(v))}`);
+    return "\n" + lines.join("\n");
+  }
   return chalk5.cyan(String(value));
 }
 
@@ -2571,6 +2618,74 @@ function printSnapshotsSection(snapshots) {
   printInfo("");
 }
 
+// src/commands/alias.ts
+import chalk7 from "chalk";
+function getRegisteredCommandNames(program2) {
+  return program2.commands.map((cmd) => cmd.name());
+}
+function isBuiltinCommand(program2, alias) {
+  return getRegisteredCommandNames(program2).includes(alias);
+}
+function handleAliasList() {
+  const config2 = loadConfig();
+  const { aliases } = config2;
+  const entries = Object.entries(aliases);
+  logger.debug("alias list \u547D\u4EE4\u6267\u884C\uFF0C\u5C55\u793A\u522B\u540D\u5217\u8868");
+  if (entries.length === 0) {
+    printInfo(MESSAGES.ALIAS_LIST_EMPTY);
+    return;
+  }
+  printInfo(`
+${MESSAGES.ALIAS_LIST_TITLE}
+`);
+  printSeparator();
+  for (const [alias, command] of entries) {
+    printInfo(`  ${chalk7.bold(alias)} \u2192 ${chalk7.cyan(command)}`);
+  }
+  printInfo("");
+  printSeparator();
+}
+function handleAliasSet(program2, alias, command) {
+  logger.debug(`alias set \u547D\u4EE4\u6267\u884C\uFF0C\u522B\u540D: ${alias}\uFF0C\u76EE\u6807: ${command}`);
+  if (isBuiltinCommand(program2, alias)) {
+    printError(MESSAGES.ALIAS_CONFLICTS_BUILTIN(alias));
+    return;
+  }
+  if (!isBuiltinCommand(program2, command)) {
+    printError(MESSAGES.ALIAS_TARGET_NOT_FOUND(command));
+    return;
+  }
+  const config2 = loadConfig();
+  config2.aliases[alias] = command;
+  writeConfig(config2);
+  printSuccess(MESSAGES.ALIAS_SET_SUCCESS(alias, command));
+}
+function handleAliasRemove(alias) {
+  logger.debug(`alias remove \u547D\u4EE4\u6267\u884C\uFF0C\u522B\u540D: ${alias}`);
+  const config2 = loadConfig();
+  if (!(alias in config2.aliases)) {
+    printError(MESSAGES.ALIAS_NOT_FOUND(alias));
+    return;
+  }
+  delete config2.aliases[alias];
+  writeConfig(config2);
+  printSuccess(MESSAGES.ALIAS_REMOVE_SUCCESS(alias));
+}
+function registerAliasCommand(program2) {
+  const aliasCmd = program2.command("alias").description("\u7BA1\u7406\u547D\u4EE4\u522B\u540D").action(() => {
+    handleAliasList();
+  });
+  aliasCmd.command("list").description("\u5217\u51FA\u6240\u6709\u522B\u540D").action(() => {
+    handleAliasList();
+  });
+  aliasCmd.command("set <alias> <command>").description("\u8BBE\u7F6E\u547D\u4EE4\u522B\u540D").action((alias, command) => {
+    handleAliasSet(program2, alias, command);
+  });
+  aliasCmd.command("remove <alias>").description("\u79FB\u9664\u547D\u4EE4\u522B\u540D").action((alias) => {
+    handleAliasRemove(alias);
+  });
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -2593,6 +2708,9 @@ registerConfigCommand(program);
 registerSyncCommand(program);
 registerResetCommand(program);
 registerStatusCommand(program);
+registerAliasCommand(program);
+var config = loadConfig();
+applyAliases(program, config.aliases);
 process.on("uncaughtException", (error) => {
   if (error instanceof ClawtError) {
     printError(error.message);

package/dist/postinstall.js

@@ -111,7 +111,7 @@ var MERGE_MESSAGES = {
   /** merge 后清理 worktree 和分支成功 */
   WORKTREE_CLEANED: (branch) => `\u2713 \u5DF2\u6E05\u7406 worktree \u548C\u5206\u652F: ${branch}`,
   /** 目标 worktree 有未提交修改但未指定 -m */
-  TARGET_WORKTREE_DIRTY_NO_MESSAGE: "\u76EE\u6807 worktree \u6709\u672A\u63D0\u4EA4\u7684\u4FEE\u6539\uFF0C\u8BF7\u901A\u8FC7 -m \u53C2\u6570\u63D0\u4F9B\u63D0\u4EA4\u4FE1\u606F",
+  TARGET_WORKTREE_DIRTY_NO_MESSAGE: (worktreePath) => `${worktreePath} \u6709\u672A\u63D0\u4EA4\u7684\u4FEE\u6539\uFF0C\u8BF7\u901A\u8FC7 -m \u53C2\u6570\u63D0\u4F9B\u63D0\u4EA4\u4FE1\u606F`,
   /** 目标 worktree 既干净又无本地提交 */
   TARGET_WORKTREE_NO_CHANGES: "\u76EE\u6807 worktree \u6CA1\u6709\u4EFB\u4F55\u53EF\u5408\u5E76\u7684\u53D8\u66F4\uFF08\u5DE5\u4F5C\u533A\u5E72\u51C0\u4E14\u65E0\u672C\u5730\u63D0\u4EA4\uFF09",
   /** merge 命令检测到 validate 状态的提示 */
@@ -272,6 +272,24 @@ var STATUS_MESSAGES = {
   STATUS_SNAPSHOT_ORPHANED: "(\u5BF9\u5E94 worktree \u5DF2\u4E0D\u5B58\u5728)"
 };
 
+// src/constants/messages/alias.ts
+var ALIAS_MESSAGES = {
+  /** 别名列表为空 */
+  ALIAS_LIST_EMPTY: "(\u65E0\u522B\u540D)",
+  /** 别名设置成功 */
+  ALIAS_SET_SUCCESS: (alias, command) => `\u2713 \u5DF2\u8BBE\u7F6E\u522B\u540D: ${alias} \u2192 ${command}`,
+  /** 别名移除成功 */
+  ALIAS_REMOVE_SUCCESS: (alias) => `\u2713 \u5DF2\u79FB\u9664\u522B\u540D: ${alias}`,
+  /** 别名不存在 */
+  ALIAS_NOT_FOUND: (alias) => `\u522B\u540D "${alias}" \u4E0D\u5B58\u5728`,
+  /** 别名与内置命令冲突 */
+  ALIAS_CONFLICTS_BUILTIN: (alias) => `\u522B\u540D "${alias}" \u4E0E\u5185\u7F6E\u547D\u4EE4\u51B2\u7A81\uFF0C\u4E0D\u5141\u8BB8\u8986\u76D6\u5185\u7F6E\u547D\u4EE4`,
+  /** 目标命令不存在 */
+  ALIAS_TARGET_NOT_FOUND: (command) => `\u76EE\u6807\u547D\u4EE4 "${command}" \u4E0D\u5B58\u5728\uFF0C\u8BF7\u6307\u5B9A\u5DF2\u6CE8\u518C\u7684\u5185\u7F6E\u547D\u4EE4\u540D`,
+  /** 别名列表标题 */
+  ALIAS_LIST_TITLE: "\u5F53\u524D\u522B\u540D\u5217\u8868\uFF1A"
+};
+
 // src/constants/messages/index.ts
 var MESSAGES = {
   ...COMMON_MESSAGES,
@@ -284,7 +302,8 @@ var MESSAGES = {
   ...REMOVE_MESSAGES,
   ...RESET_MESSAGES,
   ...CONFIG_CMD_MESSAGES,
-  ...STATUS_MESSAGES
+  ...STATUS_MESSAGES,
+  ...ALIAS_MESSAGES
 };
 
 // src/constants/config.ts
@@ -312,6 +331,10 @@ var CONFIG_DEFINITIONS = {
   terminalApp: {
     defaultValue: "auto",
     description: "\u6279\u91CF resume \u4F7F\u7528\u7684\u7EC8\u7AEF\u5E94\u7528\uFF1Aauto\uFF08\u81EA\u52A8\u68C0\u6D4B\uFF09\u3001iterm2\u3001terminal\uFF08macOS\uFF09"
+  },
+  aliases: {
+    defaultValue: {},
+    description: "\u547D\u4EE4\u522B\u540D\u6620\u5C04\uFF08\u901A\u8FC7 clawt alias \u547D\u4EE4\u7BA1\u7406\uFF09"
   }
 };
 function deriveDefaultConfig(definitions) {

package/docs/spec.md

@@ -26,6 +26,7 @@
   - [5.12 将主分支代码同步到目标 Worktree](#512-将主分支代码同步到目标-worktree)
   - [5.13 重置主 Worktree 工作区和暂存区](#513-重置主-worktree-工作区和暂存区)
   - [5.14 项目全局状态总览](#514-项目全局状态总览)
+  - [5.15 命令别名管理](#515-命令别名管理)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
   - [7.1 性能](#71-性能)
@@ -179,6 +180,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
 | `clawt reset`         | 重置主 worktree 工作区和暂存区                       | 5.13     |
 | `clawt status`        | 显示项目全局状态总览（支持 `--json` 格式输出）          | 5.14     |
+| `clawt alias`         | 管理命令别名（列出 / 设置 / 移除）                       | 5.15     |
 
 **全局选项：**
 
@@ -751,7 +753,7 @@ clawt merge [-m <commitMessage>]
 5. **根据目标 worktree 状态决定是否需要提交**
    - 检测目标 worktree 工作区是否干净（`git status --porcelain`）
    - **工作区有未提交修改**：
-     - 如果用户未提供 `-m`，提示 `目标 worktree 有未提交的修改，请通过 -m 参数提供提交信息`，退出
+     - 如果用户未提供 `-m`，提示 `<worktreePath> 有未提交的修改，请通过 -m 参数提供提交信息`（其中 `<worktreePath>` 为目标 worktree 的完整路径），退出
      - 提供了 `-m` → 执行提交：
        ```bash
        cd ~/.clawt/worktrees/<project>/<branchName>
@@ -842,7 +844,8 @@ clawt merge [-m <commitMessage>]
   "autoPullPush": false,
   "confirmDestructiveOps": true,
   "maxConcurrency": 0,
-  "terminalApp": "auto"
+  "terminalApp": "auto",
+  "aliases": {}
 }
 ```
 
@@ -856,6 +859,7 @@ clawt merge [-m <commitMessage>]
 | `confirmDestructiveOps` | `boolean` | `true` | 执行破坏性操作（reset、validate --clean、config reset）前是否提示确认 |
 | `maxConcurrency` | `number` | `0` | run 命令默认最大并发数，`0` 表示不限制 |
 | `terminalApp` | `string` | `"auto"` | 批量 resume 使用的终端应用：`auto`（自动检测）、`iterm2`、`terminal`（macOS） |
+| `aliases` | `Record<string, string>` | `{}` | 命令别名映射，键为别名，值为目标内置命令名 |
 
 ---
 
@@ -1350,6 +1354,112 @@ clawt status [--json]
 
 ---
 
+### 5.15 命令别名管理
+
+**命令：**
+
+```bash
+# 列出所有命令别名
+clawt alias
+clawt alias list
+
+# 设置命令别名
+clawt alias set <alias> <command>
+
+# 移除命令别名
+clawt alias remove <alias>
+```
+
+**子命令：**
+
+| 子命令 | 说明 |
+| ------ | ---- |
+| `clawt alias` / `clawt alias list` | 列出所有已配置的命令别名 |
+| `clawt alias set <alias> <command>` | 设置命令别名，将 `<alias>` 映射到 `<command>` |
+| `clawt alias remove <alias>` | 移除指定的命令别名 |
+
+**参数：**
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `<alias>` | 是（set / remove） | 别名名称 |
+| `<command>` | 是（set） | 目标内置命令名 |
+
+**约束规则：**
+
+1. **别名不能覆盖内置命令名**：别名不能与已注册的内置命令同名（`list`、`create`、`remove`、`run`、`resume`、`validate`、`merge`、`config`、`sync`、`reset`、`status`、`alias`）。如果用户尝试设置与内置命令同名的别名，报错退出
+2. **目标必须是内置命令**：别名的目标（`<command>`）必须是已注册的内置命令名。如果指定了不存在的目标命令，报错退出
+3. **参数透传**：通过别名调用时，所有选项和参数会完全透传给目标命令，行为与直接调用目标命令完全一致
+
+**持久化：**
+
+别名配置存储在 `~/.clawt/config.json` 的 `aliases` 字段中（类型 `Record<string, string>`，默认 `{}`）。
+
+**运行流程：**
+
+#### `alias list`（默认）
+
+1. 读取配置文件中的 `aliases` 字段
+2. 如果没有配置任何别名，输出提示 `当前没有配置任何命令别名`
+3. 如果有别名，逐行输出所有别名映射
+
+**输出格式：**
+
+```
+命令别名列表：
+
+  l → list
+  r → run
+  v → validate
+```
+
+#### `alias set <alias> <command>`
+
+1. **校验别名不与内置命令冲突**：检查 `<alias>` 是否为内置命令名，是则报错退出
+2. **校验目标命令存在**：检查 `<command>` 是否为已注册的内置命令名，不是则报错退出
+3. 将别名写入配置文件的 `aliases` 字段（如果别名已存在，覆盖旧值）
+4. 输出成功提示
+
+**输出格式：**
+
+```
+✓ 已设置别名: l → list
+```
+
+#### `alias remove <alias>`
+
+1. 读取配置文件中的 `aliases` 字段
+2. 检查指定的别名是否存在，不存在则报错退出
+3. 从 `aliases` 中删除该别名并写入配置文件
+4. 输出成功提示
+
+**输出格式：**
+
+```
+✓ 已移除别名: l
+```
+
+**别名使用示例：**
+
+```bash
+# 设置别名
+clawt alias set l list
+clawt alias set r run
+clawt alias set v validate
+
+# 使用别名（等同于对应的完整命令）
+clawt l          # 等同于 clawt list
+clawt r task.md  # 等同于 clawt run task.md
+
+# 查看所有别名
+clawt alias list
+
+# 移除别名
+clawt alias remove l
+```
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/alias.ts

@@ -0,0 +1,132 @@
+import type { Command } from 'commander';
+import chalk from 'chalk';
+import { MESSAGES } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import { loadConfig, writeConfig, printInfo, printSuccess, printError, printSeparator } from '../utils/index.js';
+
+/**
+ * 从 Commander 实例动态获取所有已注册的命令名
+ * @param {Command} program - Commander 实例
+ * @returns {string[]} 已注册的命令名列表
+ */
+function getRegisteredCommandNames(program: Command): string[] {
+  return program.commands.map((cmd) => cmd.name());
+}
+
+/**
+ * 校验别名名称是否与已注册命令冲突
+ * @param {Command} program - Commander 实例
+ * @param {string} alias - 别名
+ * @returns {boolean} 是否冲突
+ */
+function isBuiltinCommand(program: Command, alias: string): boolean {
+  return getRegisteredCommandNames(program).includes(alias);
+}
+
+/**
+ * 列出所有已配置的别名
+ */
+function handleAliasList(): void {
+  const config = loadConfig();
+  const { aliases } = config;
+  const entries = Object.entries(aliases);
+
+  logger.debug('alias list 命令执行，展示别名列表');
+
+  if (entries.length === 0) {
+    printInfo(MESSAGES.ALIAS_LIST_EMPTY);
+    return;
+  }
+
+  printInfo(`\n${MESSAGES.ALIAS_LIST_TITLE}\n`);
+  printSeparator();
+
+  for (const [alias, command] of entries) {
+    printInfo(`  ${chalk.bold(alias)} → ${chalk.cyan(command)}`);
+  }
+
+  printInfo('');
+  printSeparator();
+}
+
+/**
+ * 设置命令别名
+ * @param {Command} program - Commander 实例
+ * @param {string} alias - 别名
+ * @param {string} command - 目标命令名
+ */
+function handleAliasSet(program: Command, alias: string, command: string): void {
+  logger.debug(`alias set 命令执行，别名: ${alias}，目标: ${command}`);
+
+  // 校验别名不能与内置命令冲突
+  if (isBuiltinCommand(program, alias)) {
+    printError(MESSAGES.ALIAS_CONFLICTS_BUILTIN(alias));
+    return;
+  }
+
+  // 校验目标命令必须是已注册的内置命令
+  if (!isBuiltinCommand(program, command)) {
+    printError(MESSAGES.ALIAS_TARGET_NOT_FOUND(command));
+    return;
+  }
+
+  const config = loadConfig();
+  config.aliases[alias] = command;
+  writeConfig(config);
+
+  printSuccess(MESSAGES.ALIAS_SET_SUCCESS(alias, command));
+}
+
+/**
+ * 移除命令别名
+ * @param {string} alias - 要移除的别名
+ */
+function handleAliasRemove(alias: string): void {
+  logger.debug(`alias remove 命令执行，别名: ${alias}`);
+
+  const config = loadConfig();
+
+  if (!(alias in config.aliases)) {
+    printError(MESSAGES.ALIAS_NOT_FOUND(alias));
+    return;
+  }
+
+  delete config.aliases[alias];
+  writeConfig(config);
+
+  printSuccess(MESSAGES.ALIAS_REMOVE_SUCCESS(alias));
+}
+
+/**
+ * 注册 alias 命令组：管理命令别名
+ * @param {Command} program - Commander 实例
+ */
+export function registerAliasCommand(program: Command): void {
+  const aliasCmd = program
+    .command('alias')
+    .description('管理命令别名')
+    .action(() => {
+      handleAliasList();
+    });
+
+  aliasCmd
+    .command('list')
+    .description('列出所有别名')
+    .action(() => {
+      handleAliasList();
+    });
+
+  aliasCmd
+    .command('set <alias> <command>')
+    .description('设置命令别名')
+    .action((alias: string, command: string) => {
+      handleAliasSet(program, alias, command);
+    });
+
+  aliasCmd
+    .command('remove <alias>')
+    .description('移除命令别名')
+    .action((alias: string) => {
+      handleAliasRemove(alias);
+    });
+}

package/src/commands/config.ts

@@ -84,5 +84,14 @@ function formatConfigValue(value: ClawtConfig[keyof ClawtConfig]): string {
   if (typeof value === 'boolean') {
     return value ? chalk.green('true') : chalk.yellow('false');
   }
+  // 对象类型（如 aliases）按键值对逐行展示
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+      return chalk.dim('(无)');
+    }
+    const lines = entries.map(([k, v]) => `    ${chalk.cyan(k)} → ${chalk.cyan(String(v))}`);
+    return '\n' + lines.join('\n');
+  }
   return chalk.cyan(String(value));
 }

package/src/commands/merge.ts

@@ -165,7 +165,7 @@ async function handleMerge(options: MergeOptions): Promise<void> {
   if (!targetClean) {
     // 目标 worktree 有未提交修改，必须提供 -m
     if (!options.message) {
-      throw new ClawtError(MESSAGES.TARGET_WORKTREE_DIRTY_NO_MESSAGE);
+      throw new ClawtError(MESSAGES.TARGET_WORKTREE_DIRTY_NO_MESSAGE(targetWorktreePath));
     }
     gitAddAll(targetWorktreePath);
     gitCommit(options.message, targetWorktreePath);

package/src/constants/config.ts

@@ -33,6 +33,10 @@ export const CONFIG_DEFINITIONS: ConfigDefinitions = {
     defaultValue: 'auto',
     description: '批量 resume 使用的终端应用：auto（自动检测）、iterm2、terminal（macOS）',
   },
+  aliases: {
+    defaultValue: {} as Record<string, string>,
+    description: '命令别名映射（通过 clawt alias 命令管理）',
+  },
 };
 
 /**

package/src/constants/messages/alias.ts

@@ -0,0 +1,22 @@
+/** alias 命令专属提示消息 */
+export const ALIAS_MESSAGES = {
+  /** 别名列表为空 */
+  ALIAS_LIST_EMPTY: '(无别名)',
+  /** 别名设置成功 */
+  ALIAS_SET_SUCCESS: (alias: string, command: string) =>
+    `✓ 已设置别名: ${alias} → ${command}`,
+  /** 别名移除成功 */
+  ALIAS_REMOVE_SUCCESS: (alias: string) =>
+    `✓ 已移除别名: ${alias}`,
+  /** 别名不存在 */
+  ALIAS_NOT_FOUND: (alias: string) =>
+    `别名 "${alias}" 不存在`,
+  /** 别名与内置命令冲突 */
+  ALIAS_CONFLICTS_BUILTIN: (alias: string) =>
+    `别名 "${alias}" 与内置命令冲突，不允许覆盖内置命令`,
+  /** 目标命令不存在 */
+  ALIAS_TARGET_NOT_FOUND: (command: string) =>
+    `目标命令 "${command}" 不存在，请指定已注册的内置命令名`,
+  /** 别名列表标题 */
+  ALIAS_LIST_TITLE: '当前别名列表：',
+} as const;

package/src/constants/messages/index.ts

@@ -9,6 +9,7 @@ import { REMOVE_MESSAGES } from './remove.js';
 import { RESET_MESSAGES } from './reset.js';
 import { CONFIG_CMD_MESSAGES } from './config.js';
 import { STATUS_MESSAGES } from './status.js';
+import { ALIAS_MESSAGES } from './alias.js';
 
 /**
  * 提示消息模板
@@ -26,4 +27,5 @@ export const MESSAGES = {
   ...RESET_MESSAGES,
   ...CONFIG_CMD_MESSAGES,
   ...STATUS_MESSAGES,
+  ...ALIAS_MESSAGES,
 } as const;

package/src/constants/messages/merge.ts

@@ -11,7 +11,8 @@ export const MERGE_MESSAGES = {
   /** merge 后清理 worktree 和分支成功 */
   WORKTREE_CLEANED: (branch: string) => `✓ 已清理 worktree 和分支: ${branch}`,
   /** 目标 worktree 有未提交修改但未指定 -m */
-  TARGET_WORKTREE_DIRTY_NO_MESSAGE: '目标 worktree 有未提交的修改，请通过 -m 参数提供提交信息',
+  TARGET_WORKTREE_DIRTY_NO_MESSAGE: (worktreePath: string) =>
+    `${worktreePath} 有未提交的修改，请通过 -m 参数提供提交信息`,
   /** 目标 worktree 既干净又无本地提交 */
   TARGET_WORKTREE_NO_CHANGES: '目标 worktree 没有任何可合并的变更（工作区干净且无本地提交）',
   /** merge 命令检测到 validate 状态的提示 */

package/src/constants/messages.ts

@@ -45,7 +45,8 @@ export const MESSAGES = {
   /** 请提供提交信息 */
   COMMIT_MESSAGE_REQUIRED: '请提供提交信息（-m 参数）',
   /** 目标 worktree 有未提交修改但未指定 -m */
-  TARGET_WORKTREE_DIRTY_NO_MESSAGE: '目标 worktree 有未提交的修改，请通过 -m 参数提供提交信息',
+  TARGET_WORKTREE_DIRTY_NO_MESSAGE: (worktreePath: string) =>
+    `${worktreePath} 有未提交的修改，请通过 -m 参数提供提交信息`,
   /** 目标 worktree 既干净又无本地提交 */
   TARGET_WORKTREE_NO_CHANGES: '目标 worktree 没有任何可合并的变更（工作区干净且无本地提交）',
   /** 检测到用户中断 */

package/src/index.ts

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import { ClawtError } from './errors/index.js';
 import { logger, enableConsoleTransport } from './logger/index.js';
 import { EXIT_CODES } from './constants/index.js';
-import { printError, ensureClawtDirs } from './utils/index.js';
+import { printError, ensureClawtDirs, loadConfig, applyAliases } from './utils/index.js';
 import { registerListCommand } from './commands/list.js';
 import { registerCreateCommand } from './commands/create.js';
 import { registerRemoveCommand } from './commands/remove.js';
@@ -15,6 +15,7 @@ import { registerConfigCommand } from './commands/config.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerResetCommand } from './commands/reset.js';
 import { registerStatusCommand } from './commands/status.js';
+import { registerAliasCommand } from './commands/alias.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -50,6 +51,11 @@ registerConfigCommand(program);
 registerSyncCommand(program);
 registerResetCommand(program);
 registerStatusCommand(program);
+registerAliasCommand(program);
+
+// 加载配置并应用命令别名
+const config = loadConfig();
+applyAliases(program, config.aliases);
 
 // 全局未捕获异常处理
 process.on('uncaughtException', (error) => {

package/src/types/config.ts

@@ -12,6 +12,8 @@ export interface ClawtConfig {
   maxConcurrency: number;
   /** 批量 resume 使用的终端应用：'auto'（自动检测）、'iterm2'、'terminal'（macOS） */
   terminalApp: string;
+  /** 命令别名映射，键为别名，值为目标内置命令名 */
+  aliases: Record<string, string>;
 }
 
 /** 单个配置项的完整定义（默认值 + 描述） */

package/src/utils/alias.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+import type { ClawtConfig } from '../types/index.js';
+import { logger } from '../logger/index.js';
+
+/**
+ * 根据配置中的别名映射，为已注册的命令添加 Commander.js 别名
+ * @param {Command} program - Commander 实例
+ * @param {ClawtConfig['aliases']} aliases - 别名映射
+ */
+export function applyAliases(program: Command, aliases: ClawtConfig['aliases']): void {
+  for (const [alias, commandName] of Object.entries(aliases)) {
+    const targetCmd = program.commands.find((cmd) => cmd.name() === commandName);
+    if (targetCmd) {
+      targetCmd.alias(alias);
+      logger.debug(`已注册别名: ${alias} → ${commandName}`);
+    } else {
+      logger.warn(`别名 "${alias}" 的目标命令 "${commandName}" 不存在，已跳过`);
+    }
+  }
+}

package/src/utils/config.ts

@@ -24,11 +24,19 @@ export function loadConfig(): ClawtConfig {
   }
 }
 
+/**
+ * 将指定配置对象写入配置文件
+ * @param {ClawtConfig} config - 要写入的完整配置对象
+ */
+export function writeConfig(config: ClawtConfig): void {
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+}
+
 /**
  * 将默认配置写入配置文件
  */
 export function writeDefaultConfig(): void {
-  writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2), 'utf-8');
+  writeConfig(DEFAULT_CONFIG);
 }
 
 /**

package/src/utils/index.ts

@@ -48,7 +48,7 @@ export {
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
 export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees, getWorktreeStatus, createWorktreesByBranches } from './worktree.js';
-export { loadConfig, writeDefaultConfig, getConfigValue, ensureClawtDirs } from './config.js';
+export { loadConfig, writeDefaultConfig, writeConfig, getConfigValue, ensureClawtDirs } from './config.js';
 export { printSuccess, printError, printWarning, printInfo, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration } from './formatter.js';
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
@@ -60,4 +60,5 @@ export { ProgressRenderer } from './progress.js';
 export { parseTaskFile, loadTaskFile } from './task-file.js';
 export { executeBatchTasks } from './task-executor.js';
 export { detectTerminalApp, openCommandInNewTerminalTab } from './terminal.js';
+export { applyAliases } from './alias.js';
 

package/tests/unit/commands/alias.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Command } from 'commander';
+
+// mock 依赖模块
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock('../../../src/utils/index.js', () => ({
+  loadConfig: vi.fn(),
+  writeConfig: vi.fn(),
+  printInfo: vi.fn(),
+  printSuccess: vi.fn(),
+  printError: vi.fn(),
+  printSeparator: vi.fn(),
+}));
+
+vi.mock('../../../src/constants/index.js', () => ({
+  MESSAGES: {
+    ALIAS_LIST_EMPTY: '(无别名)',
+    ALIAS_LIST_TITLE: '当前别名列表：',
+    ALIAS_SET_SUCCESS: (a: string, c: string) => `✓ 已设置别名: ${a} → ${c}`,
+    ALIAS_REMOVE_SUCCESS: (a: string) => `✓ 已移除别名: ${a}`,
+    ALIAS_NOT_FOUND: (a: string) => `别名 "${a}" 不存在`,
+    ALIAS_CONFLICTS_BUILTIN: (a: string) => `别名 "${a}" 与内置命令冲突，不允许覆盖内置命令`,
+    ALIAS_TARGET_NOT_FOUND: (c: string) => `目标命令 "${c}" 不存在，请指定已注册的内置命令名`,
+  },
+}));
+
+import { registerAliasCommand } from '../../../src/commands/alias.js';
+import { loadConfig, writeConfig, printInfo, printSuccess, printError } from '../../../src/utils/index.js';
+
+const mockedLoadConfig = vi.mocked(loadConfig);
+const mockedWriteConfig = vi.mocked(writeConfig);
+const mockedPrintInfo = vi.mocked(printInfo);
+const mockedPrintSuccess = vi.mocked(printSuccess);
+const mockedPrintError = vi.mocked(printError);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+/** 构造默认配置 mock 数据 */
+function mockDefaultConfig(aliases: Record<string, string> = {}) {
+  return {
+    autoDeleteBranch: false,
+    claudeCodeCommand: 'claude',
+    autoPullPush: false,
+    confirmDestructiveOps: true,
+    maxConcurrency: 0,
+    terminalApp: 'auto',
+    aliases,
+  };
+}
+
+describe('registerAliasCommand', () => {
+  it('注册 alias 命令及 list/set/remove 子命令', () => {
+    const program = new Command();
+    registerAliasCommand(program);
+    const aliasCmd = program.commands.find((c) => c.name() === 'alias');
+    expect(aliasCmd).toBeDefined();
+    expect(aliasCmd!.commands.find((c) => c.name() === 'list')).toBeDefined();
+    expect(aliasCmd!.commands.find((c) => c.name() === 'set')).toBeDefined();
+    expect(aliasCmd!.commands.find((c) => c.name() === 'remove')).toBeDefined();
+  });
+});
+
+describe('alias list（通过 action 间接测试）', () => {
+  it('无别名时展示空提示', () => {
+    mockedLoadConfig.mockReturnValue(mockDefaultConfig());
+
+    const program = new Command();
+    program.exitOverride();
+    registerAliasCommand(program);
+    program.parse(['alias'], { from: 'user' });
+
+    expect(mockedPrintInfo).toHaveBeenCalledWith('(无别名)');
+  });
+
+  it('通过 alias list 子命令展示别名列表', () => {
+    mockedLoadConfig.mockReturnValue(mockDefaultConfig({ ls: 'list', rm: 'remove' }));
+
+    const program = new Command();
+    program.exitOverride();
+    registerAliasCommand(program);
+    program.parse(['alias', 'list'], { from: 'user' });
+
+    // 应展示列表标题
+    expect(mockedPrintInfo).toHaveBeenCalled();
+    const calls = mockedPrintInfo.mock.calls.map((c) => c[0]);
+    // 至少有一个调用包含别名信息
+    expect(calls.some((c) => typeof c === 'string' && c.includes('ls'))).toBe(true);
+  });
+});
+
+describe('alias set（通过 action 间接测试）', () => {
+  it('别名与内置命令冲突时报错', () => {
+    const program = new Command();
+    program.exitOverride();
+    program.command('list').action(() => {});
+    registerAliasCommand(program);
+    program.parse(['alias', 'set', 'list', 'create'], { from: 'user' });
+
+    expect(mockedPrintError).toHaveBeenCalled();
+    expect(mockedWriteConfig).not.toHaveBeenCalled();
+  });
+
+  it('目标命令不存在时报错', () => {
+    mockedLoadConfig.mockReturnValue(mockDefaultConfig());
+
+    const program = new Command();
+    program.exitOverride();
+    registerAliasCommand(program);
+    program.parse(['alias', 'set', 'ls', 'nonexistent'], { from: 'user' });
+
+    expect(mockedPrintError).toHaveBeenCalled();
+    expect(mockedWriteConfig).not.toHaveBeenCalled();
+  });
+
+  it('正常设置别名', () => {
+    mockedLoadConfig.mockReturnValue(mockDefaultConfig());
+
+    const program = new Command();
+    program.exitOverride();
+    program.command('list').action(() => {});
+    registerAliasCommand(program);
+    program.parse(['alias', 'set', 'ls', 'list'], { from: 'user' });
+
+    expect(mockedWriteConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aliases: { ls: 'list' },
+      }),
+    );
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+
+  it('覆盖已有别名', () => {
+    mockedLoadConfig.mockReturnValue(mockDefaultConfig({ ls: 'list' }));
+
+    const program = new Command();
+    program.exitOverride();
+    program.command('list').action(() => {});
+    program.command('status').action(() => {});
+    registerAliasCommand(program);
+    program.parse(['alias', 'set', 'ls', 'status'], { from: 'user' });
+
+    expect(mockedWriteConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aliases: { ls: 'status' },
+      }),
+    );
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+});
+
+describe('alias remove（通过 action 间接测试）', () => {
+  it('别名不存在时报错', () => {
+    mockedLoadConfig.mockReturnValue(mockDefaultConfig());
+
+    const program = new Command();
+    program.exitOverride();
+    registerAliasCommand(program);
+    program.parse(['alias', 'remove', 'nonexistent'], { from: 'user' });
+
+    expect(mockedPrintError).toHaveBeenCalled();
+    expect(mockedWriteConfig).not.toHaveBeenCalled();
+  });
+
+  it('正常移除别名', () => {
+    mockedLoadConfig.mockReturnValue(mockDefaultConfig({ ls: 'list' }));
+
+    const program = new Command();
+    program.exitOverride();
+    registerAliasCommand(program);
+    program.parse(['alias', 'remove', 'ls'], { from: 'user' });
+
+    expect(mockedWriteConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aliases: {},
+      }),
+    );
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+});

package/tests/unit/commands/merge.test.ts

@@ -26,7 +26,8 @@ vi.mock('../../../src/constants/index.js', () => ({
     MERGE_SQUASH_PENDING: (path: string, branch: string) => `请手动提交: ${path}`,
     MERGE_VALIDATE_STATE_HINT: (branch: string) => `分支 ${branch} 存在 validate 状态`,
     MAIN_WORKTREE_DIRTY: '主 worktree 有未提交的更改',
-    TARGET_WORKTREE_DIRTY_NO_MESSAGE: '目标 worktree 有未提交修改，请提供 -m 参数',
+    TARGET_WORKTREE_DIRTY_NO_MESSAGE: (worktreePath: string) =>
+      `${worktreePath} 有未提交修改，请提供 -m 参数`,
     TARGET_WORKTREE_NO_CHANGES: '没有可合并的变更',
     MERGE_CONFLICT: '合并冲突',
     PULL_CONFLICT: 'pull 冲突',

package/tests/unit/constants/config.test.ts

@@ -31,6 +31,7 @@ describe('DEFAULT_CONFIG', () => {
     expect(DEFAULT_CONFIG.autoPullPush).toBe(false);
     expect(DEFAULT_CONFIG.confirmDestructiveOps).toBe(true);
     expect(DEFAULT_CONFIG.maxConcurrency).toBe(0);
+    expect(DEFAULT_CONFIG.aliases).toEqual({});
   });
 });
 

package/tests/unit/constants/messages.test.ts

@@ -37,6 +37,8 @@ describe('MESSAGES', () => {
       'SYNC_SELECT_BRANCH',
       'PULL_CONFLICT',
       'PUSH_FAILED',
+      'ALIAS_LIST_EMPTY',
+      'ALIAS_LIST_TITLE',
     ] as const;
 
     it.each(stringKeys)('%s 是非空字符串', (key) => {
@@ -236,5 +238,31 @@ describe('MESSAGES', () => {
       const result = MESSAGES.SYNC_MULTIPLE_MATCHES('feat');
       expect(result).toContain('feat');
     });
+
+    it('ALIAS_SET_SUCCESS 包含别名和命令', () => {
+      const result = MESSAGES.ALIAS_SET_SUCCESS('ls', 'list');
+      expect(result).toContain('ls');
+      expect(result).toContain('list');
+    });
+
+    it('ALIAS_REMOVE_SUCCESS 包含别名', () => {
+      const result = MESSAGES.ALIAS_REMOVE_SUCCESS('ls');
+      expect(result).toContain('ls');
+    });
+
+    it('ALIAS_NOT_FOUND 包含别名', () => {
+      const result = MESSAGES.ALIAS_NOT_FOUND('xxx');
+      expect(result).toContain('xxx');
+    });
+
+    it('ALIAS_CONFLICTS_BUILTIN 包含别名', () => {
+      const result = MESSAGES.ALIAS_CONFLICTS_BUILTIN('list');
+      expect(result).toContain('list');
+    });
+
+    it('ALIAS_TARGET_NOT_FOUND 包含命令名', () => {
+      const result = MESSAGES.ALIAS_TARGET_NOT_FOUND('xxx');
+      expect(result).toContain('xxx');
+    });
   });
 });

package/tests/unit/utils/alias.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Command } from 'commander';
+
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { applyAliases } from '../../../src/utils/alias.js';
+
+describe('applyAliases', () => {
+  it('为已注册命令添加别名', () => {
+    const program = new Command();
+    const listCmd = program.command('list').action(() => {});
+
+    applyAliases(program, { ls: 'list' });
+
+    expect(listCmd.aliases()).toContain('ls');
+  });
+
+  it('目标命令不存在时静默跳过', () => {
+    const program = new Command();
+    program.command('list').action(() => {});
+
+    // 不应抛出异常
+    applyAliases(program, { xx: 'nonexistent' });
+
+    const listCmd = program.commands.find((c) => c.name() === 'list');
+    expect(listCmd!.aliases()).not.toContain('xx');
+  });
+
+  it('空别名映射时不做任何操作', () => {
+    const program = new Command();
+    program.command('list').action(() => {});
+
+    applyAliases(program, {});
+
+    const listCmd = program.commands.find((c) => c.name() === 'list');
+    expect(listCmd!.aliases()).toEqual([]);
+  });
+
+  it('支持多个别名映射到不同命令', () => {
+    const program = new Command();
+    const listCmd = program.command('list').action(() => {});
+    const removeCmd = program.command('remove').action(() => {});
+
+    applyAliases(program, { ls: 'list', rm: 'remove' });
+
+    expect(listCmd.aliases()).toContain('ls');
+    expect(removeCmd.aliases()).toContain('rm');
+  });
+});

package/tests/unit/utils/config.test.ts

@@ -18,7 +18,7 @@ vi.mock('../../../src/utils/fs.js', () => ({
 }));
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { loadConfig, getConfigValue, writeDefaultConfig, ensureClawtDirs } from '../../../src/utils/config.js';
+import { loadConfig, getConfigValue, writeDefaultConfig, writeConfig, ensureClawtDirs } from '../../../src/utils/config.js';
 import { DEFAULT_CONFIG } from '../../../src/constants/index.js';
 import { ensureDir } from '../../../src/utils/fs.js';
 
@@ -77,6 +77,18 @@ describe('writeDefaultConfig', () => {
   });
 });
 
+describe('writeConfig', () => {
+  it('将指定配置写入配置文件', () => {
+    const customConfig = { ...DEFAULT_CONFIG, aliases: { ls: 'list' } };
+    writeConfig(customConfig);
+    expect(mockedWriteFileSync).toHaveBeenCalledWith(
+      expect.any(String),
+      JSON.stringify(customConfig, null, 2),
+      'utf-8',
+    );
+  });
+});
+
 describe('ensureClawtDirs', () => {
   it('确保三个全局目录存在', () => {
     ensureClawtDirs();