clawt 2.7.4 → 2.8.0

package/.claude/agent-memory/docs-sync-updater/MEMORY.md

@@ -16,8 +16,10 @@
 
 ### README.md
 - 面向用户的使用文档
+- 全局选项在 `## 全局选项` 章节（位于 `## 使用前提` 和 `## 命令` 之间）
 - 每个命令一个 `###` 小节，含命令格式、参数表格、简要说明、示例
 - 配置文件说明在 `## 配置文件` 章节
+- 日志说明在 `## 日志` 章节（文档末尾）
 - 更新模式：更新命令说明段落，配置项表格
 
 ## 关键约定
@@ -90,3 +92,12 @@ Notes:
 - `removeSnapshot()` 同时清理 `.tree` 和 `.head` 文件
 - merge 成功后自动清理对应快照；merge 时主 worktree 脏 + 存在快照会输出警告提示
 - docs/spec.md 中 validate 章节（5.4）按 `--clean 模式`、`首次 validate`、`增量 validate` 三段描述
+
+## 全局选项
+
+- `--debug` 全局选项在 `src/index.ts` 通过 Commander.js `.option()` + `preAction` 钩子实现
+- `enableConsoleTransport()` 在 `src/logger/index.ts`，幂等地向 winston 添加 Console transport
+- 调试相关常量在 `src/constants/logger.ts`：`DEBUG_LOG_PREFIX`、`DEBUG_TIMESTAMP_FORMAT`
+- docs/spec.md 中 `--debug` 说明位于 `5.9 日志系统` 章节下的 `#### --debug 控制台调试输出` 子章节
+- docs/spec.md 中 `4. 命令总览` 的命令表格后有 `**全局选项：**` 表格
+- README.md 中 `## 全局选项` 章节（在 `## 使用前提` 和 `## 命令` 之间）

package/README.md

@@ -18,6 +18,19 @@ npm i -g clawt
 
 所有命令**必须在主 worktree 的仓库根目录**下执行（即包含 `.git` 目录的原始仓库）。在子 worktree 或子目录中执行会被拒绝。
 
+## 全局选项
+
+| 选项 | 说明 |
+| ---- | ---- |
+| `--debug` | 输出详细调试信息到终端，实时显示带颜色和时间戳的日志 |
+
+`--debug` 可与任意子命令组合使用：
+
+```bash
+clawt run -b feature-login --debug
+clawt validate -b scheme --debug
+```
+
 ## 命令
 
 ### `clawt create` — 批量创建 worktree
@@ -313,4 +326,4 @@ feature/a.b  →  feature-a-b
 
 ## 日志
 
-日志保存在 `~/.clawt/logs/` 目录，按日期滚动，保留 30 天。
+日志保存在 `~/.clawt/logs/` 目录，按日期滚动，保留 30 天。使用 `--debug` 全局选项可在终端实时查看调试日志。

package/dist/index.js

@@ -221,6 +221,9 @@ var CONFIG_DESCRIPTIONS = deriveConfigDescriptions(CONFIG_DEFINITIONS);
 // src/constants/git.ts
 var AUTO_SAVE_COMMIT_MESSAGE = "chore: auto-save before sync";
 
+// src/constants/logger.ts
+var DEBUG_TIMESTAMP_FORMAT = "HH:mm:ss.SSS";
+
 // src/errors/index.ts
 var ClawtError = class extends Error {
   /** 退出码 */
@@ -239,6 +242,7 @@ var ClawtError = class extends Error {
 // src/logger/index.ts
 import winston from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
+import chalk from "chalk";
 import { existsSync, mkdirSync } from "fs";
 if (!existsSync(LOGS_DIR)) {
   mkdirSync(LOGS_DIR, { recursive: true });
@@ -262,6 +266,35 @@ var logger = winston.createLogger({
   ),
   transports: [dailyRotateTransport]
 });
+var LEVEL_COLORS = {
+  error: chalk.red,
+  warn: chalk.yellow,
+  info: chalk.cyan,
+  debug: chalk.gray
+};
+function colorizeLevel(level) {
+  const colorFn = LEVEL_COLORS[level] || chalk.white;
+  return colorFn(level.toUpperCase().padEnd(5));
+}
+function enableConsoleTransport() {
+  const hasConsole = logger.transports.some(
+    (t) => t instanceof winston.transports.Console
+  );
+  if (hasConsole) {
+    return;
+  }
+  const consoleFormat = winston.format.printf(({ level, message, timestamp }) => {
+    return `${chalk.gray(timestamp)} ${colorizeLevel(level)} ${message}`;
+  });
+  const consoleTransport = new winston.transports.Console({
+    level: "debug",
+    format: winston.format.combine(
+      winston.format.timestamp({ format: DEBUG_TIMESTAMP_FORMAT }),
+      consoleFormat
+    )
+  });
+  logger.add(consoleTransport);
+}
 
 // src/utils/shell.ts
 import { execSync, execFileSync, spawn } from "child_process";
@@ -467,16 +500,16 @@ function gitApplyCachedCheck(patchContent, cwd) {
 }
 
 // src/utils/formatter.ts
-import chalk from "chalk";
+import chalk2 from "chalk";
 import { createInterface } from "readline";
 function printSuccess(message) {
-  console.log(chalk.green(message));
+  console.log(chalk2.green(message));
 }
 function printError(message) {
-  console.error(chalk.red(`\u2717 ${message}`));
+  console.error(chalk2.red(`\u2717 ${message}`));
 }
 function printWarning(message) {
-  console.log(chalk.yellow(`\u26A0 ${message}`));
+  console.log(chalk2.yellow(`\u26A0 ${message}`));
 }
 function printInfo(message) {
   console.log(message);
@@ -500,7 +533,7 @@ function confirmAction(question) {
   });
 }
 function confirmDestructiveAction(dangerousCommand, description) {
-  printWarning(`\u5373\u5C06\u6267\u884C ${chalk.red.bold(dangerousCommand)}\uFF0C${description}`);
+  printWarning(`\u5373\u5C06\u6267\u884C ${chalk2.red.bold(dangerousCommand)}\uFF0C${description}`);
   return confirmAction("\u662F\u5426\u7EE7\u7EED\uFF1F");
 }
 function isWorktreeIdle(status) {
@@ -508,17 +541,17 @@ function isWorktreeIdle(status) {
 }
 function formatWorktreeStatus(status) {
   const parts = [];
-  parts.push(chalk.yellow(`${status.commitCount} \u4E2A\u63D0\u4EA4`));
+  parts.push(chalk2.yellow(`${status.commitCount} \u4E2A\u63D0\u4EA4`));
   if (status.insertions === 0 && status.deletions === 0) {
     parts.push("\u65E0\u53D8\u66F4");
   } else {
     const diffParts = [];
-    diffParts.push(chalk.green(`+${status.insertions}`));
-    diffParts.push(chalk.red(`-${status.deletions}`));
+    diffParts.push(chalk2.green(`+${status.insertions}`));
+    diffParts.push(chalk2.red(`-${status.deletions}`));
     parts.push(diffParts.join(" "));
   }
   if (status.hasDirtyFiles) {
-    parts.push(chalk.gray("(\u672A\u63D0\u4EA4\u4FEE\u6539)"));
+    parts.push(chalk2.gray("(\u672A\u63D0\u4EA4\u4FEE\u6539)"));
   }
   return parts.join("   ");
 }
@@ -826,7 +859,7 @@ async function resolveTargetWorktree(worktrees, messages, branchName) {
 }
 
 // src/commands/list.ts
-import chalk2 from "chalk";
+import chalk3 from "chalk";
 function registerListCommand(program2) {
   program2.command("list").description("\u5217\u51FA\u5F53\u524D\u9879\u76EE\u6240\u6709 worktree").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((options) => {
     handleList(options);
@@ -863,12 +896,12 @@ function printListAsText(projectName, worktrees) {
     for (const wt of worktrees) {
       const status = getWorktreeStatus(wt);
       const isIdle = status ? isWorktreeIdle(status) : false;
-      const pathDisplay = isIdle ? chalk2.hex("#FF8C00")(wt.path) : wt.path;
+      const pathDisplay = isIdle ? chalk3.hex("#FF8C00")(wt.path) : wt.path;
       printInfo(`  ${pathDisplay}   [${wt.branch}]`);
       if (status) {
         printInfo(`    ${formatWorktreeStatus(status)}`);
       } else {
-        printInfo(`    ${chalk2.yellow(MESSAGES.WORKTREE_STATUS_UNAVAILABLE)}`);
+        printInfo(`    ${chalk3.yellow(MESSAGES.WORKTREE_STATUS_UNAVAILABLE)}`);
       }
       printInfo("");
     }
@@ -1467,7 +1500,7 @@ async function handleMerge(options) {
 }
 
 // src/commands/config.ts
-import chalk3 from "chalk";
+import chalk4 from "chalk";
 function registerConfigCommand(program2) {
   const configCmd = program2.command("config").description("\u67E5\u770B\u548C\u7BA1\u7406\u5168\u5C40\u914D\u7F6E").action(() => {
     handleConfig();
@@ -1480,7 +1513,7 @@ function handleConfig() {
   const config = loadConfig();
   logger.info("config \u547D\u4EE4\u6267\u884C\uFF0C\u5C55\u793A\u5168\u5C40\u914D\u7F6E");
   printInfo(`
-${chalk3.dim("\u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84:")} ${CONFIG_PATH}
+${chalk4.dim("\u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84:")} ${CONFIG_PATH}
 `);
   printSeparator();
   const keys = Object.keys(DEFAULT_CONFIG);
@@ -1490,8 +1523,8 @@ ${chalk3.dim("\u914D\u7F6E\u6587\u4EF6\u8DEF\u5F84:")} ${CONFIG_PATH}
     const description = CONFIG_DESCRIPTIONS[key];
     const formattedValue = formatConfigValue(value);
     if (i === 0) printInfo("");
-    printInfo(`  ${chalk3.bold(key)}: ${formattedValue}`);
-    printInfo(`  ${chalk3.dim(description)}`);
+    printInfo(`  ${chalk4.bold(key)}: ${formattedValue}`);
+    printInfo(`  ${chalk4.dim(description)}`);
     printInfo("");
   }
   printSeparator();
@@ -1511,9 +1544,9 @@ async function handleConfigReset() {
 }
 function formatConfigValue(value) {
   if (typeof value === "boolean") {
-    return value ? chalk3.green("true") : chalk3.yellow("false");
+    return value ? chalk4.green("true") : chalk4.yellow("false");
   }
-  return chalk3.cyan(String(value));
+  return chalk4.cyan(String(value));
 }
 
 // src/commands/sync.ts
@@ -1604,7 +1637,12 @@ var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 ensureClawtDirs();
 var program = new Command();
-program.name("clawt").description("\u672C\u5730\u5E76\u884C\u6267\u884C\u591A\u4E2AClaude Code Agent\u4EFB\u52A1\uFF0C\u878D\u5408 Git Worktree \u4E0E Claude Code CLI \u7684\u547D\u4EE4\u884C\u5DE5\u5177").version(version);
+program.name("clawt").description("\u672C\u5730\u5E76\u884C\u6267\u884C\u591A\u4E2AClaude Code Agent\u4EFB\u52A1\uFF0C\u878D\u5408 Git Worktree \u4E0E Claude Code CLI \u7684\u547D\u4EE4\u884C\u5DE5\u5177").version(version).option("--debug", "\u8F93\u51FA\u8BE6\u7EC6\u8C03\u8BD5\u4FE1\u606F\u5230\u7EC8\u7AEF");
+program.hook("preAction", (thisCommand) => {
+  if (thisCommand.opts().debug) {
+    enableConsoleTransport();
+  }
+});
 registerListCommand(program);
 registerCreateCommand(program);
 registerRemoveCommand(program);

package/docs/spec.md

@@ -173,6 +173,12 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
 | `clawt reset`         | 重置主 worktree 工作区和暂存区                       | 5.13     |
 
+**全局选项：**
+
+| 选项      | 说明                                     |
+| --------- | ---------------------------------------- |
+| `--debug` | 输出详细调试信息到终端（启用 Console transport） |
+
 所有命令执行前，都必须先执行**主 worktree 校验**（见 [2.1](#21-主-worktree-的定义与定位规则)）。
 
 ---
@@ -879,6 +885,42 @@ clawt list [--json]
 - 日志文件保留 30 天
 - 单个日志文件最大 10MB
 
+#### `--debug` 控制台调试输出
+
+通过全局选项 `--debug` 可将调试日志实时输出到终端，方便排查问题。
+
+**实现机制：**
+
+- 在 Commander.js 的 `preAction` 钩子中检测 `--debug` 选项，按需调用 `enableConsoleTransport()` 函数
+- `enableConsoleTransport()` 动态向 winston 实例添加 `Console` transport（level 为 `debug`），该函数幂等，多次调用不会重复添加 transport
+- 相关常量定义在 `src/constants/logger.ts`：
+  - `DEBUG_LOG_PREFIX`：控制台调试输出的日志前缀标识
+  - `DEBUG_TIMESTAMP_FORMAT`：时间戳格式（`HH:mm:ss.SSS`，精简，不含日期）
+
+**控制台日志格式：**
+
+```
+HH:mm:ss.SSS LEVEL 消息内容
+```
+
+**日志级别颜色映射：**
+
+| 级别    | 颜色   |
+| ------- | ------ |
+| `error` | 红色   |
+| `warn`  | 黄色   |
+| `info`  | 青色   |
+| `debug` | 灰色   |
+
+**使用示例：**
+
+```bash
+clawt run -b feature-login --debug
+clawt validate -b feature-scheme --debug
+```
+
+> **注意：** `--debug` 选项不影响文件日志（file transport），文件日志始终按原有策略写入。控制台输出仅在传入 `--debug` 时启用。
+
 ---
 
 ### 5.10 查看和管理全局配置

package/package.json

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

package/src/constants/index.ts

@@ -5,3 +5,4 @@ export { EXIT_CODES } from './exitCodes.js';
 export { ENABLE_BRACKETED_PASTE, DISABLE_BRACKETED_PASTE, PASTE_THRESHOLD_MS } from './terminal.js';
 export { DEFAULT_CONFIG, CONFIG_DESCRIPTIONS, APPEND_SYSTEM_PROMPT } from './config.js';
 export { AUTO_SAVE_COMMIT_MESSAGE } from './git.js';
+export { DEBUG_LOG_PREFIX, DEBUG_TIMESTAMP_FORMAT } from './logger.js';

package/src/constants/logger.ts

@@ -0,0 +1,5 @@
+/** 控制台调试输出的日志前缀标识 */
+export const DEBUG_LOG_PREFIX = '[DEBUG]';
+
+/** 控制台调试日志的时间戳格式（精简，不含日期） */
+export const DEBUG_TIMESTAMP_FORMAT = 'HH:mm:ss.SSS';

package/src/index.ts

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { ClawtError } from './errors/index.js';
-import { logger } from './logger/index.js';
+import { logger, enableConsoleTransport } from './logger/index.js';
 import { EXIT_CODES } from './constants/index.js';
 import { printError, ensureClawtDirs } from './utils/index.js';
 import { registerListCommand } from './commands/list.js';
@@ -27,7 +27,15 @@ const program = new Command();
 program
   .name('clawt')
   .description('本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具')
-  .version(version);
+  .version(version)
+  .option('--debug', '输出详细调试信息到终端');
+
+// 在子命令 action 执行前检查 --debug 选项，按需启用控制台日志
+program.hook('preAction', (thisCommand) => {
+  if (thisCommand.opts().debug) {
+    enableConsoleTransport();
+  }
+});
 
 // 注册所有命令
 registerListCommand(program);

package/src/logger/index.ts

@@ -1,6 +1,7 @@
 import winston from 'winston';
 import DailyRotateFile from 'winston-daily-rotate-file';
-import { LOGS_DIR } from '../constants/index.js';
+import chalk from 'chalk';
+import { LOGS_DIR, DEBUG_TIMESTAMP_FORMAT } from '../constants/index.js';
 import { existsSync, mkdirSync } from 'node:fs';
 
 // 确保日志目录存在
@@ -32,3 +33,51 @@ export const logger = winston.createLogger({
   ),
   transports: [dailyRotateTransport],
 });
+
+/** 日志级别颜色映射 */
+const LEVEL_COLORS: Record<string, (text: string) => string> = {
+  error: chalk.red,
+  warn: chalk.yellow,
+  info: chalk.cyan,
+  debug: chalk.gray,
+};
+
+/**
+ * 为日志级别添加对应颜色
+ * @param {string} level - 日志级别
+ * @returns {string} 带颜色的日志级别字符串
+ */
+function colorizeLevel(level: string): string {
+  const colorFn = LEVEL_COLORS[level] || chalk.white;
+  return colorFn(level.toUpperCase().padEnd(5));
+}
+
+/**
+ * 启用控制台日志输出（--debug 模式）
+ * 动态向 winston 实例添加 Console transport，输出带颜色和时间戳的调试信息
+ * 该函数幂等，多次调用不会重复添加 transport
+ */
+export function enableConsoleTransport(): void {
+  // 幂等保护：检查是否已添加过 Console transport
+  const hasConsole = logger.transports.some(
+    (t) => t instanceof winston.transports.Console,
+  );
+  if (hasConsole) {
+    return;
+  }
+
+  /** --debug 模式的控制台日志格式：精简时间戳 + 带颜色级别 + 消息 */
+  const consoleFormat = winston.format.printf(({ level, message, timestamp }) => {
+    return `${chalk.gray(timestamp)} ${colorizeLevel(level)} ${message}`;
+  });
+
+  const consoleTransport = new winston.transports.Console({
+    level: 'debug',
+    format: winston.format.combine(
+      winston.format.timestamp({ format: DEBUG_TIMESTAMP_FORMAT }),
+      consoleFormat,
+    ),
+  });
+
+  logger.add(consoleTransport);
+}