clawt 2.16.5 → 2.17.0

package/README.md

@@ -238,6 +238,20 @@ clawt config set terminalApp iterm2
 clawt config get maxConcurrency
 ```
 
+### `clawt completion` — Shell 自动补全
+
+为终端提供命令、子命令、选项，甚至分支名和配置项的自动补全功能。
+
+```bash
+# 自动安装补全脚本（推荐）
+clawt completion install
+
+# 或手动将脚本添加到你的 shell 配置文件
+clawt completion bash >> ~/.bashrc
+clawt completion zsh >> ~/.zshrc
+```
+> **支持特性：** 所有子命令、选项、`-b` 参数自动补全本地 `worktree` 分支名、`-f` 参数自动补全文件路径，以及 `config set/get` 键名自动补全。
+
 ### `clawt alias` — 管理命令别名
 
 ```bash

package/dist/index.js

@@ -375,6 +375,28 @@ var ALIAS_MESSAGES = {
   ALIAS_LIST_TITLE: "\u5F53\u524D\u522B\u540D\u5217\u8868\uFF1A"
 };
 
+// src/constants/messages/completion.ts
+var COMPLETION_MESSAGES = {
+  /** completion 命令的主描述 */
+  COMPLETION_COMMAND_DESC: "\u751F\u6210\u548C\u5B89\u88C5 shell \u81EA\u52A8\u8865\u5168\u811A\u672C",
+  /** bash 子命令描述 */
+  COMPLETION_BASH_DESC: "\u8F93\u51FA bash \u81EA\u52A8\u8865\u5168\u811A\u672C",
+  /** zsh 子命令描述 */
+  COMPLETION_ZSH_DESC: "\u8F93\u51FA zsh \u81EA\u52A8\u8865\u5168\u811A\u672C",
+  /** install 子命令描述 */
+  COMPLETION_INSTALL_DESC: "\u81EA\u52A8\u5B89\u88C5\u8865\u5168\u811A\u672C\u5230\u5F53\u524D\u7528\u6237\u7684 shell \u914D\u7F6E\u6587\u4EF6",
+  /** 安装成功提示 */
+  COMPLETION_INSTALL_SUCCESS: "\u81EA\u52A8\u8865\u5168\u914D\u7F6E\u5DF2\u6210\u529F\u5199\u5165",
+  /** 安装失败或未知的 shell 提示 */
+  COMPLETION_INSTALL_UNKNOWN_SHELL: "\u672A\u77E5\u7684 Shell \u73AF\u5883\u6216\u65E0\u6CD5\u81EA\u52A8\u5B89\u88C5\uFF0C\u8BF7\u624B\u52A8\u914D\u7F6E\u3002",
+  /** 补全配置已存在提示 */
+  COMPLETION_INSTALL_EXISTS: "\u81EA\u52A8\u8865\u5168\u914D\u7F6E\u5DF2\u5B58\u5728\u4E8E\u76EE\u6807\u6587\u4EF6\u4E2D",
+  /** 提示用户重启生效 */
+  COMPLETION_INSTALL_RESTART: (filePath) => `\u8BF7\u91CD\u542F\u7EC8\u7AEF\u6216\u8FD0\u884C \`source ${filePath}\` \u4EE5\u4F7F\u8865\u5168\u751F\u6548\u3002`,
+  /** 安装写入失败提示 */
+  COMPLETION_INSTALL_WRITE_ERROR: (filePath) => `\u65E0\u6CD5\u5199\u5165\u6587\u4EF6 ${filePath}\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u6743\u9650\u6216\u624B\u52A8\u914D\u7F6E\u3002`
+};
+
 // src/constants/messages/index.ts
 var MESSAGES = {
   ...COMMON_MESSAGES,
@@ -388,7 +410,8 @@ var MESSAGES = {
   ...RESET_MESSAGES,
   ...CONFIG_CMD_MESSAGES,
   ...STATUS_MESSAGES,
-  ...ALIAS_MESSAGES
+  ...ALIAS_MESSAGES,
+  ...COMPLETION_MESSAGES
 };
 
 // src/constants/exitCodes.ts
@@ -622,7 +645,7 @@ function parseParallelCommands(commandString) {
 }
 function runParallelCommands(commands, options) {
   const promises = commands.map((command) => {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       logger.debug(`\u5E76\u884C\u542F\u52A8\u547D\u4EE4: ${command}${options?.cwd ? ` (cwd: ${options.cwd})` : ""}`);
       const child = spawn(command, {
         cwd: options?.cwd,
@@ -630,10 +653,10 @@ function runParallelCommands(commands, options) {
         shell: true
       });
       child.on("error", (err) => {
-        resolve2({ command, exitCode: 1, error: err.message });
+        resolve3({ command, exitCode: 1, error: err.message });
       });
       child.on("close", (code) => {
-        resolve2({ command, exitCode: code ?? 1 });
+        resolve3({ command, exitCode: code ?? 1 });
       });
     });
   });
@@ -851,14 +874,14 @@ function printDoubleSeparator() {
   console.log(MESSAGES.DOUBLE_SEPARATOR);
 }
 function confirmAction(question) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const rl = createInterface({
       input: process.stdin,
       output: process.stdout
     });
     rl.question(`${question} (y/N) `, (answer) => {
       rl.close();
-      resolve2(answer.toLowerCase() === "y");
+      resolve3(answer.toLowerCase() === "y");
     });
   });
 }
@@ -1835,8 +1858,8 @@ function formatActivityText(kind, toolName, input, text) {
     const filePath = input?.file_path;
     const command = input?.command;
     if (filePath) {
-      const basename2 = path.basename(filePath);
-      raw = `${toolName} ${basename2}`;
+      const basename3 = path.basename(filePath);
+      raw = `${toolName} ${basename3}`;
     } else if (command) {
       const cleaned = command.replace(/[\n\r\t]+/g, " ").trim();
       raw = `${toolName} ${cleaned}`;
@@ -1915,7 +1938,7 @@ function executeClaudeTask(worktree, task, onActivity) {
       stdio: ["ignore", "pipe", "pipe"]
     }
   );
-  const promise = new Promise((resolve2) => {
+  const promise = new Promise((resolve3) => {
     let stderr = "";
     let finalResult = null;
     const lineBuffer = createLineBuffer();
@@ -1951,7 +1974,7 @@ function executeClaudeTask(worktree, task, onActivity) {
       if (finalResult) {
         success = !finalResult.is_error;
       }
-      resolve2({
+      resolve3({
         task,
         branch: worktree.branch,
         worktreePath: worktree.path,
@@ -1961,7 +1984,7 @@ function executeClaudeTask(worktree, task, onActivity) {
       });
     });
     child.on("error", (err) => {
-      resolve2({
+      resolve3({
         task,
         branch: worktree.branch,
         worktreePath: worktree.path,
@@ -2020,7 +2043,7 @@ async function executeWithConcurrency(worktrees, tasks, concurrency, renderer, s
   const results = new Array(total);
   let nextIndex = 0;
   let completedCount = 0;
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     function launchNext() {
       if (nextIndex >= total || isInterrupted()) return;
       const index = nextIndex;
@@ -2041,7 +2064,7 @@ async function executeWithConcurrency(worktrees, tasks, concurrency, renderer, s
         }
         launchNext();
         if (completedCount === total) {
-          resolve2(results);
+          resolve3(results);
         }
       });
     }
@@ -2096,11 +2119,11 @@ async function executeBatchTasks(worktrees, tasks, concurrency) {
     printWarning(MESSAGES.INTERRUPTED);
     killAllChildProcesses(childProcesses);
     await Promise.allSettled(childProcesses.map(
-      (cp) => new Promise((resolve2) => {
+      (cp) => new Promise((resolve3) => {
         if (cp.exitCode !== null) {
-          resolve2();
+          resolve3();
         } else {
-          cp.on("close", () => resolve2());
+          cp.on("close", () => resolve3());
         }
       })
     ));
@@ -3388,6 +3411,218 @@ function registerAliasCommand(program2) {
   });
 }
 
+// src/commands/completion.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync10 } from "fs";
+import { resolve as resolve2 } from "path";
+import { homedir as homedir2 } from "os";
+
+// src/utils/completion-scripts.ts
+function getBashScript() {
+  return `
+_clawt_completion() {
+  local IFS=$'\\n'
+  local completions=$(clawt completion _complete bash "$COMP_CWORD" "\${COMP_WORDS[@]}")
+  COMPREPLY=()
+  local comp
+  while IFS= read -r comp; do
+    [ -z "$comp" ] && continue
+    COMPREPLY+=("$comp")
+  done <<< "$completions"
+  local has_dir=0
+  for comp in "\${COMPREPLY[@]}"; do
+    [[ "$comp" == */ ]] && has_dir=1 && break
+  done
+  if (( has_dir )) && type compopt &>/dev/null; then
+    compopt -o nospace
+  fi
+}
+complete -o nospace -F _clawt_completion clawt
+`;
+}
+function getZshScript() {
+  return `
+#compdef clawt
+_clawt_completion() {
+  local completions
+  local cword=$((CURRENT - 1))
+  completions=("\${(@f)$(clawt completion _complete zsh "$cword" "\${words[@]}")}")
+  if [[ -n "$completions" ]]; then
+    local comp
+    for comp in "\${completions[@]}"; do
+      [[ -z "$comp" ]] && continue
+      if [[ "$comp" == */ ]]; then
+        compadd -S '' -- "$comp"
+      else
+        compadd -S ' ' -- "$comp"
+      fi
+    done
+  fi
+}
+compdef _clawt_completion clawt
+`;
+}
+
+// src/utils/completion-engine.ts
+import { existsSync as existsSync9, readdirSync as readdirSync5, statSync as statSync2 } from "fs";
+import { join as join6, dirname, basename as basename2 } from "path";
+function completeFilePath(partial) {
+  const cwd = process.cwd();
+  const hasDir = partial.includes("/");
+  const searchDir = hasDir ? join6(cwd, dirname(partial)) : cwd;
+  const prefix = hasDir ? basename2(partial) : partial;
+  if (!existsSync9(searchDir)) {
+    return [];
+  }
+  const entries = readdirSync5(searchDir);
+  const results = [];
+  const dirPrefix = hasDir ? dirname(partial) + "/" : "";
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix)) continue;
+    if (entry.startsWith(".")) continue;
+    const fullPath = join6(searchDir, entry);
+    try {
+      const stat = statSync2(fullPath);
+      if (stat.isDirectory()) {
+        results.push(dirPrefix + entry + "/");
+      } else if (stat.isFile()) {
+        results.push(dirPrefix + entry);
+      }
+    } catch {
+    }
+  }
+  return results;
+}
+function tryCompleteSpecialArg(previousWord, currentWord, words) {
+  if (previousWord === "-b" || previousWord === "--branch") {
+    try {
+      const worktrees = getProjectWorktrees();
+      const branches = worktrees.map((wt) => wt.branch);
+      console.log(branches.filter((b) => b.startsWith(currentWord)).join("\n"));
+    } catch {
+    }
+    return true;
+  }
+  if (previousWord === "-f" || previousWord === "--file") {
+    try {
+      const candidates = completeFilePath(currentWord);
+      console.log(candidates.join("\n"));
+    } catch {
+    }
+    return true;
+  }
+  if (previousWord === "set" || previousWord === "get") {
+    if (words.includes("config")) {
+      const keys = Object.keys(CONFIG_DEFINITIONS);
+      console.log(keys.filter((k) => k.startsWith(currentWord)).join("\n"));
+      return true;
+    }
+  }
+  return false;
+}
+function completeFromCommandTree(program2, words, cword, currentWord) {
+  let currentCmd = program2;
+  for (let i = 1; i < cword; i++) {
+    const word = words[i];
+    const subCmd = currentCmd.commands.find((c) => c.name() === word || c.aliases().includes(word));
+    if (subCmd) {
+      currentCmd = subCmd;
+    }
+  }
+  const completions = [];
+  if (currentWord.startsWith("-")) {
+    currentCmd.options.forEach((opt) => {
+      if (opt.short && opt.short.startsWith(currentWord)) completions.push(opt.short);
+      if (opt.long && opt.long.startsWith(currentWord)) completions.push(opt.long);
+    });
+  } else {
+    currentCmd.commands.forEach((cmd) => {
+      const name = cmd.name();
+      if (name !== "_complete" && name.startsWith(currentWord)) {
+        completions.push(name);
+        cmd.aliases().forEach((alias) => {
+          if (alias.startsWith(currentWord)) {
+            completions.push(alias);
+          }
+        });
+      }
+    });
+    if (!currentWord) {
+      currentCmd.options.forEach((opt) => {
+        if (opt.long) completions.push(opt.long);
+        else if (opt.short) completions.push(opt.short);
+      });
+    }
+  }
+  console.log(Array.from(new Set(completions)).join("\n"));
+}
+function generateCompletions(program2, args) {
+  const cword = parseInt(args[1], 10);
+  const words = args.slice(2);
+  const currentWord = words[cword] || "";
+  const previousWord = cword > 0 ? words[cword - 1] : "";
+  if (tryCompleteSpecialArg(previousWord, currentWord, words)) {
+    return;
+  }
+  completeFromCommandTree(program2, words, cword, currentWord);
+}
+
+// src/commands/completion.ts
+function appendToFile(filePath, content) {
+  if (existsSync10(filePath)) {
+    const current = readFileSync4(filePath, "utf-8");
+    if (current.includes("clawt completion")) {
+      printInfo(MESSAGES.COMPLETION_INSTALL_EXISTS + ": " + filePath);
+      return;
+    }
+    content = current + content;
+  }
+  writeFileSync3(filePath, content, "utf-8");
+  printSuccess(MESSAGES.COMPLETION_INSTALL_SUCCESS + ": " + filePath);
+  printInfo(MESSAGES.COMPLETION_INSTALL_RESTART(filePath));
+}
+function installCompletions() {
+  const shell = process.env.SHELL || "";
+  const home = homedir2();
+  try {
+    if (shell.includes("zsh")) {
+      const rcPath = resolve2(home, ".zshrc");
+      const script = `
+# clawt completion
+source <(clawt completion zsh)
+`;
+      appendToFile(rcPath, script);
+    } else if (shell.includes("bash")) {
+      const rcPath = resolve2(home, ".bashrc");
+      const script = `
+# clawt completion
+eval "$(clawt completion bash)"
+`;
+      appendToFile(rcPath, script);
+    } else {
+      printWarning(MESSAGES.COMPLETION_INSTALL_UNKNOWN_SHELL);
+    }
+  } catch (error) {
+    const filePath = shell.includes("zsh") ? resolve2(home, ".zshrc") : resolve2(home, ".bashrc");
+    printError(MESSAGES.COMPLETION_INSTALL_WRITE_ERROR(filePath));
+  }
+}
+function registerCompletionCommand(program2) {
+  const completionCommand = program2.command("completion").description(MESSAGES.COMPLETION_COMMAND_DESC);
+  completionCommand.command("bash").description(MESSAGES.COMPLETION_BASH_DESC).action(() => {
+    console.log(getBashScript());
+  });
+  completionCommand.command("zsh").description(MESSAGES.COMPLETION_ZSH_DESC).action(() => {
+    console.log(getZshScript());
+  });
+  completionCommand.command("install").description(MESSAGES.COMPLETION_INSTALL_DESC).action(() => {
+    installCompletions();
+  });
+  completionCommand.command("_complete [args...]").allowUnknownOption().description("\u5185\u90E8\u4F7F\u7528\u7684\u52A8\u6001\u8865\u5168\u65B9\u6CD5\uFF0C\u4E0D\u5BF9\u5916\u516C\u5F00").action((args) => {
+    if (!args || args.length < 2) return;
+    generateCompletions(program2, args);
+  });
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -3411,6 +3646,7 @@ registerSyncCommand(program);
 registerResetCommand(program);
 registerStatusCommand(program);
 registerAliasCommand(program);
+registerCompletionCommand(program);
 var config = loadConfig();
 applyAliases(program, config.aliases);
 process.on("uncaughtException", (error) => {

package/dist/postinstall.js

@@ -366,6 +366,28 @@ var ALIAS_MESSAGES = {
   ALIAS_LIST_TITLE: "\u5F53\u524D\u522B\u540D\u5217\u8868\uFF1A"
 };
 
+// src/constants/messages/completion.ts
+var COMPLETION_MESSAGES = {
+  /** completion 命令的主描述 */
+  COMPLETION_COMMAND_DESC: "\u751F\u6210\u548C\u5B89\u88C5 shell \u81EA\u52A8\u8865\u5168\u811A\u672C",
+  /** bash 子命令描述 */
+  COMPLETION_BASH_DESC: "\u8F93\u51FA bash \u81EA\u52A8\u8865\u5168\u811A\u672C",
+  /** zsh 子命令描述 */
+  COMPLETION_ZSH_DESC: "\u8F93\u51FA zsh \u81EA\u52A8\u8865\u5168\u811A\u672C",
+  /** install 子命令描述 */
+  COMPLETION_INSTALL_DESC: "\u81EA\u52A8\u5B89\u88C5\u8865\u5168\u811A\u672C\u5230\u5F53\u524D\u7528\u6237\u7684 shell \u914D\u7F6E\u6587\u4EF6",
+  /** 安装成功提示 */
+  COMPLETION_INSTALL_SUCCESS: "\u81EA\u52A8\u8865\u5168\u914D\u7F6E\u5DF2\u6210\u529F\u5199\u5165",
+  /** 安装失败或未知的 shell 提示 */
+  COMPLETION_INSTALL_UNKNOWN_SHELL: "\u672A\u77E5\u7684 Shell \u73AF\u5883\u6216\u65E0\u6CD5\u81EA\u52A8\u5B89\u88C5\uFF0C\u8BF7\u624B\u52A8\u914D\u7F6E\u3002",
+  /** 补全配置已存在提示 */
+  COMPLETION_INSTALL_EXISTS: "\u81EA\u52A8\u8865\u5168\u914D\u7F6E\u5DF2\u5B58\u5728\u4E8E\u76EE\u6807\u6587\u4EF6\u4E2D",
+  /** 提示用户重启生效 */
+  COMPLETION_INSTALL_RESTART: (filePath) => `\u8BF7\u91CD\u542F\u7EC8\u7AEF\u6216\u8FD0\u884C \`source ${filePath}\` \u4EE5\u4F7F\u8865\u5168\u751F\u6548\u3002`,
+  /** 安装写入失败提示 */
+  COMPLETION_INSTALL_WRITE_ERROR: (filePath) => `\u65E0\u6CD5\u5199\u5165\u6587\u4EF6 ${filePath}\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u6743\u9650\u6216\u624B\u52A8\u914D\u7F6E\u3002`
+};
+
 // src/constants/messages/index.ts
 var MESSAGES = {
   ...COMMON_MESSAGES,
@@ -379,7 +401,8 @@ var MESSAGES = {
   ...RESET_MESSAGES,
   ...CONFIG_CMD_MESSAGES,
   ...STATUS_MESSAGES,
-  ...ALIAS_MESSAGES
+  ...ALIAS_MESSAGES,
+  ...COMPLETION_MESSAGES
 };
 
 // src/constants/terminal.ts

package/docs/spec.md

@@ -27,6 +27,7 @@
   - [5.13 重置主 Worktree 工作区和暂存区](#513-重置主-worktree-工作区和暂存区)
   - [5.14 项目全局状态总览](#514-项目全局状态总览)
   - [5.15 命令别名管理](#515-命令别名管理)
+  - [5.16 Shell 自动补全](#516-clawt-completion-命令)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
   - [7.1 性能](#71-性能)
@@ -184,6 +185,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt reset`         | 重置主 worktree 工作区和暂存区                       | 5.13     |
 | `clawt status`        | 显示项目全局状态总览（支持 `--json` 格式输出）          | 5.14     |
 | `clawt alias`         | 管理命令别名（列出 / 设置 / 移除）                       | 5.15     |
+| `clawt completion`    | 为终端提供 shell 自动补全功能（bash/zsh）              | 5.16     |
 
 **全局选项：**
 
@@ -294,7 +296,7 @@ clawt run -b <branchName>
 
 #### 任务文件格式
 
-任务文件使用 Markdown 文件中嵌入 HTML 注释标签的自定义格式，标签外的任何文本都不会被解析。
+任务文件使用嵌入 HTML 注释标签的自定义格式，不限制文件类型，标签外的任何文本都不会被解析。
 
 ```markdown
 这里可以写任何说明文字，会被忽略
@@ -1758,6 +1760,62 @@ clawt alias remove l
 
 ---
 
+### 5.16 `clawt completion` 命令
+
+为终端环境（bash/zsh）生成并安装 `clawt` 的命令、选项及参数的自动补全脚本。
+
+#### 语法
+```bash
+clawt completion bash
+clawt completion zsh
+clawt completion install
+```
+
+#### 子命令说明
+
+| 子命令    | 说明                                                                                |
+| --------- | ----------------------------------------------------------------------------------- |
+| `bash`    | 输出适用于 bash 的补全脚本（用户可重定向到 `~/.bashrc`）                                |
+| `zsh`     | 输出适用于 zsh 的补全脚本（用户可重定向到 `~/.zshrc`）                                  |
+| `install` | 自动检测当前 shell 类型，将补全脚本追加到对应的配置文件中                                  |
+
+#### `install` 子命令流程
+
+1. 通过 `process.env.SHELL` 检测当前 shell 类型
+2. 根据 shell 类型确定目标配置文件：
+   - zsh → `~/.zshrc`（追加 `source <(clawt completion zsh)`）
+   - bash → `~/.bashrc`（追加 `eval "$(clawt completion bash)"`）
+3. 检查目标文件中是否已包含 `clawt completion`，已存在则跳过并提示
+4. 追加成功后提示用户重启终端或 source 配置文件
+5. 未知 shell 类型时输出警告，提示手动配置
+
+#### 动态补全特性
+
+补全脚本通过内部子命令 `_complete` 实现动态补全，不对外公开。补全引擎基于 Commander.js 的命令树结构遍历，支持以下场景：
+
+| 场景                         | 补全行为                                                   |
+| ---------------------------- | ---------------------------------------------------------- |
+| `-b` / `--branch` 参数之后   | 动态列出当前项目所有 worktree 分支名（通过 `getProjectWorktrees`） |
+| `-f` / `--file` 参数之后     | 动态列出匹配的文件和子目录（不限制文件类型，支持子目录递归浏览）    |
+| `config set` / `config get` 之后 | 动态列出所有配置项键名（从 `CONFIG_DEFINITIONS` 获取）         |
+| 输入以 `-` 开头              | 列出当前命令层级的可用选项（short/long）                       |
+| 其他情况                     | 列出当前命令层级的可用子命令及别名                              |
+
+**文件路径补全细节：**
+- 支持子目录递归浏览（如 `tasks/` 后继续 Tab 可深入子目录）
+- 目录候选项以 `/` 结尾，补全时不自动追加空格
+- 不限制文件类型，列出所有非隐藏文件
+- 跳过隐藏文件和目录（以 `.` 开头）
+
+#### 实现说明
+
+- 补全命令注册函数：`registerCompletionCommand()`（在 `src/commands/completion.ts`）
+- 消息常量：`COMPLETION_MESSAGES`（在 `src/constants/messages/completion.ts`）
+- 核心函数：`generateCompletions()` 解析当前输入上下文并输出候选项，`completeFilePath()` 处理文件路径补全
+- shell 脚本生成：`getBashScript()`、`getZshScript()` 分别生成对应 shell 的补全脚本
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

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

package/src/commands/completion.ts

@@ -0,0 +1,98 @@
+import { Command } from 'commander';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+import { MESSAGES } from '../constants/messages/index.js';
+import { printSuccess, printInfo, printWarning, printError } from '../utils/index.js';
+import { getBashScript, getZshScript } from '../utils/completion-scripts.js';
+import { generateCompletions } from '../utils/completion-engine.js';
+
+/**
+ * 向文件中追加内容（如果不存在），或者创建新文件
+ * @param {string} filePath - 目标文件路径
+ * @param {string} content - 要写入的文本内容
+ */
+function appendToFile(filePath: string, content: string): void {
+  if (existsSync(filePath)) {
+    const current = readFileSync(filePath, 'utf-8');
+    if (current.includes('clawt completion')) {
+      printInfo(MESSAGES.COMPLETION_INSTALL_EXISTS + ': ' + filePath);
+      return;
+    }
+    content = current + content;
+  }
+  writeFileSync(filePath, content, 'utf-8');
+  printSuccess(MESSAGES.COMPLETION_INSTALL_SUCCESS + ': ' + filePath);
+  printInfo(MESSAGES.COMPLETION_INSTALL_RESTART(filePath));
+}
+
+/**
+ * 自动安装补全脚本到用户的环境变量
+ */
+function installCompletions(): void {
+  const shell = process.env.SHELL || '';
+  const home = homedir();
+
+  try {
+    if (shell.includes('zsh')) {
+      const rcPath = resolve(home, '.zshrc');
+      const script = `\n# clawt completion\nsource <(clawt completion zsh)\n`;
+      appendToFile(rcPath, script);
+    } else if (shell.includes('bash')) {
+      const rcPath = resolve(home, '.bashrc');
+      // bash 3.2（macOS 默认版本）中 source <(...) 在子 shell 执行，complete 注册无法传递回父 shell
+      // 使用 eval "$(...)" 确保在当前 shell 中执行
+      const script = `\n# clawt completion\neval "$(clawt completion bash)"\n`;
+      appendToFile(rcPath, script);
+    } else {
+      printWarning(MESSAGES.COMPLETION_INSTALL_UNKNOWN_SHELL);
+    }
+  } catch (error) {
+    const filePath = shell.includes('zsh')
+      ? resolve(home, '.zshrc')
+      : resolve(home, '.bashrc');
+    printError(MESSAGES.COMPLETION_INSTALL_WRITE_ERROR(filePath));
+  }
+}
+
+/**
+ * 注册自动补全命令
+ * @param {Command} program - 根命令实例
+ */
+export function registerCompletionCommand(program: Command): void {
+  const completionCommand = program
+    .command('completion')
+    .description(MESSAGES.COMPLETION_COMMAND_DESC);
+
+  completionCommand
+    .command('bash')
+    .description(MESSAGES.COMPLETION_BASH_DESC)
+    .action(() => {
+      console.log(getBashScript());
+    });
+
+  completionCommand
+    .command('zsh')
+    .description(MESSAGES.COMPLETION_ZSH_DESC)
+    .action(() => {
+      console.log(getZshScript());
+    });
+
+  completionCommand
+    .command('install')
+    .description(MESSAGES.COMPLETION_INSTALL_DESC)
+    .action(() => {
+      installCompletions();
+    });
+
+  completionCommand
+    .command('_complete [args...]')
+    .allowUnknownOption()
+    .description('内部使用的动态补全方法，不对外公开')
+    .action((args: string[]) => {
+      // args 中包含了: shell, cword, ...words
+      if (!args || args.length < 2) return;
+      generateCompletions(program, args);
+    });
+}

package/src/constants/messages/completion.ts

@@ -0,0 +1,23 @@
+/**
+ * 自动补全命令相关的提示消息常量
+ */
+export const COMPLETION_MESSAGES = {
+  /** completion 命令的主描述 */
+  COMPLETION_COMMAND_DESC: '生成和安装 shell 自动补全脚本',
+  /** bash 子命令描述 */
+  COMPLETION_BASH_DESC: '输出 bash 自动补全脚本',
+  /** zsh 子命令描述 */
+  COMPLETION_ZSH_DESC: '输出 zsh 自动补全脚本',
+  /** install 子命令描述 */
+  COMPLETION_INSTALL_DESC: '自动安装补全脚本到当前用户的 shell 配置文件',
+  /** 安装成功提示 */
+  COMPLETION_INSTALL_SUCCESS: '自动补全配置已成功写入',
+  /** 安装失败或未知的 shell 提示 */
+  COMPLETION_INSTALL_UNKNOWN_SHELL: '未知的 Shell 环境或无法自动安装，请手动配置。',
+  /** 补全配置已存在提示 */
+  COMPLETION_INSTALL_EXISTS: '自动补全配置已存在于目标文件中',
+  /** 提示用户重启生效 */
+  COMPLETION_INSTALL_RESTART: (filePath: string) => `请重启终端或运行 \`source ${filePath}\` 以使补全生效。`,
+  /** 安装写入失败提示 */
+  COMPLETION_INSTALL_WRITE_ERROR: (filePath: string) => `无法写入文件 ${filePath}，请检查文件权限或手动配置。`,
+} as const;

package/src/constants/messages/index.ts

@@ -12,6 +12,7 @@ import { CONFIG_CMD_MESSAGES, CONFIG_ALIAS_DISABLED_HINT } from './config.js';
 export { CONFIG_ALIAS_DISABLED_HINT };
 import { STATUS_MESSAGES } from './status.js';
 import { ALIAS_MESSAGES } from './alias.js';
+import { COMPLETION_MESSAGES } from './completion.js';
 
 /**
  * 提示消息模板
@@ -30,4 +31,5 @@ export const MESSAGES = {
   ...CONFIG_CMD_MESSAGES,
   ...STATUS_MESSAGES,
   ...ALIAS_MESSAGES,
+  ...COMPLETION_MESSAGES,
 } as const;

package/src/index.ts

@@ -16,6 +16,7 @@ import { registerSyncCommand } from './commands/sync.js';
 import { registerResetCommand } from './commands/reset.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerAliasCommand } from './commands/alias.js';
+import { registerCompletionCommand } from './commands/completion.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -52,6 +53,7 @@ registerSyncCommand(program);
 registerResetCommand(program);
 registerStatusCommand(program);
 registerAliasCommand(program);
+registerCompletionCommand(program);
 
 // 加载配置并应用命令别名
 const config = loadConfig();