clawt 2.17.1 → 2.19.0

package/dist/postinstall.js

@@ -10,6 +10,7 @@ var LOGS_DIR = join(CLAWT_HOME, "logs");
 var WORKTREES_DIR = join(CLAWT_HOME, "worktrees");
 var VALIDATE_SNAPSHOTS_DIR = join(CLAWT_HOME, "validate-snapshots");
 var CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+var UPDATE_CHECK_PATH = join(CLAWT_HOME, "update-check.json");
 
 // src/constants/messages/common.ts
 var COMMON_MESSAGES = {
@@ -363,6 +364,32 @@ var ALIAS_MESSAGES = {
   ALIAS_LIST_TITLE: "\u5F53\u524D\u522B\u540D\u5217\u8868\uFF1A"
 };
 
+// src/constants/messages/projects.ts
+var PROJECTS_MESSAGES = {
+  /** projects 命令全局概览标题 */
+  PROJECTS_OVERVIEW_TITLE: "\u9879\u76EE\u6982\u89C8",
+  /** projects 命令指定项目详情标题 */
+  PROJECTS_DETAIL_TITLE: (projectName) => `\u9879\u76EE\u8BE6\u60C5: ${projectName}`,
+  /** 无项目提示 */
+  PROJECTS_NO_PROJECTS: "(\u6682\u65E0\u9879\u76EE\uFF0Cworktrees \u76EE\u5F55\u4E3A\u7A7A)",
+  /** 项目不存在提示 */
+  PROJECTS_NOT_FOUND: (name) => `\u9879\u76EE ${name} \u4E0D\u5B58\u5728`,
+  /** worktree 数量标签 */
+  PROJECTS_WORKTREE_COUNT: (count) => `${count} \u4E2A worktree`,
+  /** 最近活跃时间标签 */
+  PROJECTS_LAST_ACTIVE: (relativeTime) => `\u6700\u8FD1\u6D3B\u8DC3: ${relativeTime}`,
+  /** 磁盘占用标签 */
+  PROJECTS_DISK_USAGE: (size) => `\u78C1\u76D8\u5360\u7528: ${size}`,
+  /** 总磁盘占用标签 */
+  PROJECTS_TOTAL_DISK_USAGE: (size) => `\u603B\u5360\u7528: ${size}`,
+  /** projects 详情无 worktree */
+  PROJECTS_DETAIL_NO_WORKTREES: "(\u8BE5\u9879\u76EE\u4E0B\u65E0 worktree)",
+  /** 路径标签 */
+  PROJECTS_PATH: (path) => `\u8DEF\u5F84: ${path}`,
+  /** 最后修改时间标签 */
+  PROJECTS_LAST_MODIFIED: (relativeTime) => `\u6700\u540E\u4FEE\u6539: ${relativeTime}`
+};
+
 // src/constants/messages/completion.ts
 var COMPLETION_MESSAGES = {
   /** completion 命令的主描述 */
@@ -399,6 +426,7 @@ var MESSAGES = {
   ...CONFIG_CMD_MESSAGES,
   ...STATUS_MESSAGES,
   ...ALIAS_MESSAGES,
+  ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES
 };
 
@@ -435,6 +463,10 @@ var CONFIG_DEFINITIONS = {
   aliases: {
     defaultValue: {},
     description: "\u547D\u4EE4\u522B\u540D\u6620\u5C04"
+  },
+  autoUpdate: {
+    defaultValue: true,
+    description: "\u662F\u5426\u542F\u7528\u81EA\u52A8\u66F4\u65B0\u68C0\u67E5\uFF08\u6BCF 24 \u5C0F\u65F6\u68C0\u67E5\u4E00\u6B21 npm registry\uFF09"
   }
 };
 function deriveDefaultConfig(definitions) {
@@ -452,6 +484,9 @@ function deriveConfigDescriptions(definitions) {
 var DEFAULT_CONFIG = deriveDefaultConfig(CONFIG_DEFINITIONS);
 var CONFIG_DESCRIPTIONS = deriveConfigDescriptions(CONFIG_DEFINITIONS);
 
+// src/constants/update.ts
+var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+
 // scripts/postinstall.ts
 function ensureDirectory(dirPath) {
   if (!existsSync(dirPath)) {

package/docs/spec.md

@@ -28,6 +28,8 @@
   - [5.14 项目全局状态总览](#514-项目全局状态总览)
   - [5.15 命令别名管理](#515-命令别名管理)
   - [5.16 Shell 自动补全](#516-clawt-completion-命令)
+  - [5.17 自动更新检查](#517-自动更新检查)
+  - [5.18 跨项目 Worktree 概览](#518-跨项目-worktree-概览)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
   - [7.1 性能](#71-性能)
@@ -146,6 +148,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 ```
 ~/.clawt/
 ├── config.json                          # 全局配置文件
+├── update-check.json                    # 更新检查缓存文件（自动生成）
 ├── logs/                                # 日志目录
 │   ├── clawt-2025-02-06.log
 │   └── ...
@@ -186,6 +189,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt status`        | 显示项目全局状态总览（支持 `--json` 格式输出）          | 5.14     |
 | `clawt alias`         | 管理命令别名（列出 / 设置 / 移除）                       | 5.15     |
 | `clawt completion`    | 为终端提供 shell 自动补全功能（bash/zsh）              | 5.16     |
+| `clawt projects`      | 展示所有项目的 worktree 概览，或查看指定项目的 worktree 详情 | 5.17     |
 
 **全局选项：**
 
@@ -1067,7 +1071,8 @@ clawt merge [-m <commitMessage>]
   "confirmDestructiveOps": true,
   "maxConcurrency": 0,
   "terminalApp": "auto",
-  "aliases": {}
+  "aliases": {},
+  "autoUpdate": true
 }
 ```
 
@@ -1082,6 +1087,7 @@ clawt merge [-m <commitMessage>]
 | `maxConcurrency` | `number` | `0` | run 命令默认最大并发数，`0` 表示不限制 |
 | `terminalApp` | `string` | `"auto"` | 批量 resume 使用的终端应用：`auto`（自动检测）、`iterm2`、`terminal`（macOS） |
 | `aliases` | `Record<string, string>` | `{}` | 命令别名映射，键为别名，值为目标内置命令名 |
+| `autoUpdate` | `boolean` | `true` | 是否启用自动更新检查（每 24 小时通过 npm registry 检查一次新版本） |
 
 ---
 
@@ -1651,6 +1657,9 @@ clawt status [--json]
 - `formatRelativeTime()` 是新增的格式化函数（在 `src/utils/formatter.ts`），将 ISO 8601 日期字符串转换为中文相对时间描述（如"3 天前"、"2 小时前"、"刚刚"），无效日期时返回 null
 - `getCommitCountBehind()` 是新增的工具函数（在 `src/utils/git.ts`），通过 `git rev-list --count <branch>..HEAD` 计算落后提交数
 - `getProjectSnapshotBranches()` 是新增的工具函数（在 `src/utils/validate-snapshot.ts`），通过扫描快照目录下的 `.tree` 文件提取分支名列表
+- `formatDiskSize()` 是新增的格式化函数（在 `src/utils/formatter.ts`），将字节数格式化为带单位的磁盘大小字符串（如 `"1.5 GB"`、`"256.0 MB"`、`"10.2 KB"`、`"512 B"`）
+- `formatLocalISOString()` 是新增的格式化函数（在 `src/utils/formatter.ts`），将 Date 对象格式化为本机时区的 ISO 8601 字符串（输出格式: `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`），替代 `Date.toISOString()` 的 UTC 时区输出
+- `calculateDirSize()` 是新增的文件系统工具函数（在 `src/utils/fs.ts`），递归计算目录占用的磁盘大小（字节），遇到无法访问的文件或目录时静默跳过
 
 ---
 
@@ -1816,6 +1825,238 @@ clawt completion install
 
 ---
 
+### 5.17 自动更新检查
+
+CLI 在每次命令执行完毕后，根据配置项 `autoUpdate` 决定是否检查 npm registry 上的最新版本。当发现新版本时，以带边框的提示框在终端输出版本更新信息和升级命令。
+
+#### 触发条件
+
+- 配置项 `autoUpdate` 为 `true`（默认启用）
+- 命令正常执行完毕后触发（在 `program.parseAsync()` 之后）
+
+#### 检查流程
+
+1. 读取缓存文件 `~/.clawt/update-check.json`
+2. 判断缓存是否有效：
+   - 缓存不存在或解析失败 → 视为过期
+   - 缓存中的 `currentVersion` 与本地版本不一致 → 视为过期
+   - 距离上次检查超过 24 小时 → 视为过期
+3. **缓存有效**：直接使用缓存中的 `latestVersion` 与本地版本比较，有新版本则打印提示
+4. **缓存过期**：向 npm registry 发起 HTTPS 请求获取最新版本号（5 秒超时），更新缓存文件后判断并打印提示
+
+#### 缓存文件
+
+**路径：** `~/.clawt/update-check.json`
+
+**结构：**
+
+```json
+{
+  "lastCheck": 1709000000000,
+  "latestVersion": "2.18.0",
+  "currentVersion": "2.17.1"
+}
+```
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `lastCheck` | `number` | 上次检查时间戳（毫秒） |
+| `latestVersion` | `string` | 从 registry 获取的最新版本号 |
+| `currentVersion` | `string` | 检查时的本地版本号 |
+
+#### 版本比较
+
+使用简易 semver 比较（不引入额外依赖），逐级比较 `major.minor.patch`：
+
+- `latest > current` → 提示更新
+- `latest <= current` → 不提示
+
+#### 包管理器检测
+
+更新提示中会显示与用户安装方式匹配的升级命令。检测逻辑依次尝试：
+
+1. `pnpm list -g --depth=0 clawt` → 匹配则提示 `pnpm add -g clawt`
+2. `yarn global list --depth=0` → 输出含 `clawt` 则提示 `yarn global add clawt`
+3. 以上均未匹配 → 默认提示 `npm i -g clawt`
+
+#### 提示框格式
+
+当检测到新版本时，输出带 Unicode 圆角边框的居中提示框：
+
+```
+╭──────────────────────────────────────────────╮
+│                                              │
+│   clawt 有新版本可用: 2.17.1 → 2.18.0       │
+│   执行 npm i -g clawt 进行更新               │
+│                                              │
+╰──────────────────────────────────────────────╯
+```
+
+版本号和命令使用 chalk 着色：当前版本红色、最新版本绿色、更新命令青色。
+
+#### 容错设计
+
+所有异常静默处理，不影响 CLI 正常功能：
+
+- 网络请求失败或超时（5 秒） → 静默忽略
+- registry 返回无效 JSON 或缺少 `version` 字段 → 静默忽略
+- 缓存文件读写失败 → 静默忽略
+- `checkForUpdates()` 入口函数的最外层 `try/catch` 确保任何未预期异常都不会中断 CLI
+
+#### 常量定义
+
+| 常量 | 值 | 位置 |
+| ---- | -- | ---- |
+| `UPDATE_CHECK_INTERVAL_MS` | `86400000`（24 小时） | `src/constants/update.ts` |
+| `NPM_REGISTRY_URL` | `https://registry.npmjs.org/clawt/latest` | `src/constants/update.ts` |
+| `NPM_REGISTRY_TIMEOUT_MS` | `5000` | `src/constants/update.ts` |
+| `PACKAGE_NAME` | `clawt` | `src/constants/update.ts` |
+| `UPDATE_CHECK_PATH` | `~/.clawt/update-check.json` | `src/constants/paths.ts` |
+
+#### 实现说明
+
+- 入口函数：`checkForUpdates()`（在 `src/utils/update-checker.ts`）
+- 消息常量：`UPDATE_MESSAGES`、`UPDATE_COMMANDS`（在 `src/constants/messages/update.ts`）
+- 入口调用点：`src/index.ts` 的 `main()` 异步函数中，`program.parseAsync()` 之后根据 `config.autoUpdate` 条件调用
+
+---
+
+### 5.18 跨项目 Worktree 概览
+
+**命令：**
+
+```bash
+clawt projects [name] [--json]
+```
+
+**参数：**
+
+| 参数     | 必填 | 说明                                           |
+| -------- | ---- | ---------------------------------------------- |
+| `[name]` | 否   | 指定项目名，查看该项目的 worktree 详情           |
+| `--json` | 否   | 以 JSON 格式输出完整数据                        |
+
+**使用场景：**
+
+当使用 clawt 管理多个不同项目时，快速了解所有项目的 worktree 数量、磁盘占用和最近活跃时间。也可以指定项目名查看该项目下每个 worktree 的分支、路径、最后修改时间和磁盘占用。
+
+**注意：** `projects` 命令不需要在主 worktree 中执行（与其他命令不同），它直接扫描 `~/.clawt/worktrees/` 目录。
+
+**运行流程：**
+
+#### 无参数模式（项目概览）
+
+1. 扫描 `~/.clawt/worktrees/` 目录，列出所有项目子目录
+2. 对每个项目收集以下信息：
+   - **项目名**（目录名即项目名）
+   - **worktree 数量**（项目目录下的子目录数）
+   - **最近活跃时间**（取项目目录自身和所有 worktree 目录 mtime 的最大值，通过 `formatLocalISOString()` 格式化为本机时区的 ISO 8601 字符串）
+   - **磁盘占用**（通过 `calculateDirSize()` 递归计算整个项目目录的总大小）
+3. 按最近活跃时间降序排序
+4. 输出概览信息（文本或 JSON）
+
+#### 指定项目模式（worktree 详情）
+
+1. 检查 `~/.clawt/worktrees/<name>/` 是否存在，不存在则报错退出
+2. 扫描项目目录，对每个 worktree 子目录收集：
+   - **分支名**（目录名即分支名）
+   - **worktree 路径**
+   - **最后修改时间**（目录 mtime，通过 `formatLocalISOString()` 格式化）
+   - **磁盘占用**（通过 `calculateDirSize()` 递归计算）
+3. 按最后修改时间降序排序
+4. 输出详情信息（文本或 JSON）
+
+**文本输出格式（概览模式）：**
+
+```
+════════════════════════════════════════
+  项目概览
+════════════════════════════════════════
+
+  ● my-project
+    3 个 worktree   最近活跃: 2 小时前   磁盘占用: 1.5 GB
+
+  ● another-project
+    1 个 worktree   最近活跃: 3 天前   磁盘占用: 256.0 MB
+
+────────────────────────────────────────
+
+  共 2 个项目   总占用: 1.8 GB
+
+════════════════════════════════════════
+```
+
+**文本输出格式（详情模式）：**
+
+```
+════════════════════════════════════════
+  项目详情: my-project
+════════════════════════════════════════
+
+  ◆ 路径: ~/.clawt/worktrees/my-project
+    总占用: 1.5 GB
+
+────────────────────────────────────────
+
+  ● feature-login
+    ~/.clawt/worktrees/my-project/feature-login
+    最后修改: 2 小时前   磁盘占用: 800.0 MB
+
+  ● feature-signup
+    ~/.clawt/worktrees/my-project/feature-signup
+    最后修改: 1 天前   磁盘占用: 700.0 MB
+
+════════════════════════════════════════
+```
+
+**JSON 输出格式（概览模式，`--json`）：**
+
+```json
+{
+  "projects": [
+    {
+      "name": "my-project",
+      "worktreeCount": 3,
+      "lastActiveTime": "2025-06-15T18:30:00.000+08:00",
+      "diskUsage": 1610612736
+    }
+  ],
+  "totalProjects": 1,
+  "totalDiskUsage": 1610612736
+}
+```
+
+**JSON 输出格式（详情模式，`--json`）：**
+
+```json
+{
+  "name": "my-project",
+  "projectDir": "~/.clawt/worktrees/my-project",
+  "worktrees": [
+    {
+      "branch": "feature-login",
+      "path": "~/.clawt/worktrees/my-project/feature-login",
+      "lastModifiedTime": "2025-06-15T18:30:00.000+08:00",
+      "diskUsage": 838860800
+    }
+  ],
+  "totalDiskUsage": 838860800
+}
+```
+
+**实现要点：**
+
+- 命令注册函数：`registerProjectsCommand()`（在 `src/commands/projects.ts`）
+- 类型定义在 `src/types/project.ts`：`ProjectOverview`、`ProjectWorktreeDetail`、`ProjectDetailResult`、`ProjectsOverviewResult`
+- 命令选项类型：`ProjectsOptions`（在 `src/types/command.ts`）
+- 消息常量在 `PROJECTS_MESSAGES`（在 `src/constants/messages/projects.ts`）
+- 时间格式化使用 `formatLocalISOString()`（在 `src/utils/formatter.ts`），输出本机时区的 ISO 8601 字符串（替代 `Date.toISOString()` 的 UTC 输出）
+- 磁盘大小展示使用 `formatDiskSize()`（在 `src/utils/formatter.ts`），将字节数格式化为带单位的可读字符串
+- 目录大小计算使用 `calculateDirSize()`（在 `src/utils/fs.ts`），递归遍历目录计算总字节数
+- 时间的相对展示使用 `formatRelativeTime()`（在 `src/utils/formatter.ts`），将 ISO 8601 日期转换为中文相对时间（如"2 小时前"）
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

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

package/src/commands/projects.ts

@@ -0,0 +1,324 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import chalk from 'chalk';
+import { MESSAGES, WORKTREES_DIR } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import type {
+  ProjectsOptions,
+  ProjectOverview,
+  ProjectWorktreeDetail,
+  ProjectDetailResult,
+  ProjectsOverviewResult,
+} from '../types/index.js';
+import {
+  formatRelativeTime,
+  formatDiskSize,
+  formatLocalISOString,
+  calculateDirSize,
+  printInfo,
+  printDoubleSeparator,
+  printSeparator,
+  printError,
+} from '../utils/index.js';
+
+/**
+ * 注册 projects 命令：统一管理多个项目的 worktree 状态
+ * @param {Command} program - Commander 实例
+ */
+export function registerProjectsCommand(program: Command): void {
+  program
+    .command('projects [name]')
+    .description('展示所有项目的 worktree 概览，或查看指定项目的 worktree 详情')
+    .option('--json', '以 JSON 格式输出')
+    .action((name: string | undefined, options: { json?: boolean }) => {
+      handleProjects({ name, json: options.json });
+    });
+}
+
+/**
+ * 执行 projects 命令的核心逻辑
+ * @param {ProjectsOptions} options - 命令选项
+ */
+function handleProjects(options: ProjectsOptions): void {
+  if (options.name) {
+    handleProjectDetail(options.name, options.json);
+  } else {
+    handleProjectsOverview(options.json);
+  }
+}
+
+/**
+ * 处理项目概览展示：列出所有项目
+ * @param {boolean} [json] - 是否以 JSON 格式输出
+ */
+function handleProjectsOverview(json?: boolean): void {
+  const result = collectProjectsOverview();
+
+  logger.info(`projects 命令执行，共 ${result.totalProjects} 个项目`);
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  printProjectsOverviewAsText(result);
+}
+
+/**
+ * 处理指定项目的 worktree 详情展示
+ * @param {string} name - 项目名
+ * @param {boolean} [json] - 是否以 JSON 格式输出
+ */
+function handleProjectDetail(name: string, json?: boolean): void {
+  const projectDir = join(WORKTREES_DIR, name);
+
+  if (!existsSync(projectDir)) {
+    printError(MESSAGES.PROJECTS_NOT_FOUND(name));
+    process.exit(1);
+  }
+
+  const result = collectProjectDetail(name, projectDir);
+
+  logger.info(`projects 命令执行，项目: ${name}，共 ${result.worktrees.length} 个 worktree`);
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  printProjectDetailAsText(result);
+}
+
+// ─── 数据收集函数 ─────────────────────────────────
+
+/**
+ * 收集所有项目的概览信息
+ * @returns {ProjectsOverviewResult} 所有项目概览结果
+ */
+function collectProjectsOverview(): ProjectsOverviewResult {
+  if (!existsSync(WORKTREES_DIR)) {
+    return { projects: [], totalProjects: 0, totalDiskUsage: 0 };
+  }
+
+  const entries = readdirSync(WORKTREES_DIR, { withFileTypes: true });
+  const projects: ProjectOverview[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const projectDir = join(WORKTREES_DIR, entry.name);
+    const overview = collectSingleProjectOverview(entry.name, projectDir);
+    projects.push(overview);
+  }
+
+  // 按最近活跃时间降序排序
+  sortByLastActiveTimeDesc(projects);
+
+  const totalDiskUsage = projects.reduce((sum, p) => sum + p.diskUsage, 0);
+
+  return {
+    projects,
+    totalProjects: projects.length,
+    totalDiskUsage,
+  };
+}
+
+/**
+ * 收集单个项目的概览信息
+ * @param {string} name - 项目名
+ * @param {string} projectDir - 项目目录路径
+ * @returns {ProjectOverview} 项目概览
+ */
+function collectSingleProjectOverview(name: string, projectDir: string): ProjectOverview {
+  const subEntries = readdirSync(projectDir, { withFileTypes: true });
+  const worktreeDirs = subEntries.filter((e) => e.isDirectory());
+
+  const worktreeCount = worktreeDirs.length;
+  const diskUsage = calculateDirSize(projectDir);
+  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join(projectDir, e.name)));
+
+  return {
+    name,
+    worktreeCount,
+    lastActiveTime,
+    diskUsage,
+  };
+}
+
+/**
+ * 收集指定项目的 worktree 详情
+ * @param {string} name - 项目名
+ * @param {string} projectDir - 项目目录路径
+ * @returns {ProjectDetailResult} 项目详情结果
+ */
+function collectProjectDetail(name: string, projectDir: string): ProjectDetailResult {
+  const subEntries = readdirSync(projectDir, { withFileTypes: true });
+  const worktrees: ProjectWorktreeDetail[] = [];
+
+  for (const entry of subEntries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const wtPath = join(projectDir, entry.name);
+    const detail = collectSingleWorktreeDetail(entry.name, wtPath);
+    worktrees.push(detail);
+  }
+
+  // 按最近修改时间降序排序
+  worktrees.sort((a, b) => new Date(b.lastModifiedTime).getTime() - new Date(a.lastModifiedTime).getTime());
+
+  const totalDiskUsage = worktrees.reduce((sum, wt) => sum + wt.diskUsage, 0);
+
+  return {
+    name,
+    projectDir,
+    worktrees,
+    totalDiskUsage,
+  };
+}
+
+/**
+ * 收集单个 worktree 的详情信息
+ * @param {string} branch - 分支名（目录名即分支名）
+ * @param {string} wtPath - worktree 路径
+ * @returns {ProjectWorktreeDetail} worktree 详情
+ */
+function collectSingleWorktreeDetail(branch: string, wtPath: string): ProjectWorktreeDetail {
+  const stat = statSync(wtPath);
+  const diskUsage = calculateDirSize(wtPath);
+
+  return {
+    branch,
+    path: wtPath,
+    lastModifiedTime: formatLocalISOString(stat.mtime),
+    diskUsage,
+  };
+}
+
+// ─── 工具函数 ─────────────────────────────────────
+
+/**
+ * 确定项目的最近活跃时间
+ * 取项目目录自身和所有子 worktree 目录修改时间的最大值
+ * @param {string} projectDir - 项目目录路径
+ * @param {string[]} worktreePaths - worktree 路径列表
+ * @returns {string} ISO 8601 格式的最近活跃时间
+ */
+function resolveProjectLastActiveTime(projectDir: string, worktreePaths: string[]): string {
+  let latestTime = statSync(projectDir).mtime;
+
+  for (const wtPath of worktreePaths) {
+    try {
+      const wtStat = statSync(wtPath);
+      if (wtStat.mtime > latestTime) {
+        latestTime = wtStat.mtime;
+      }
+    } catch {
+      // 忽略无法访问的目录
+    }
+  }
+
+  return formatLocalISOString(latestTime);
+}
+
+/**
+ * 按最近活跃时间降序排序项目概览列表（原地排序）
+ * @param {ProjectOverview[]} projects - 项目概览列表
+ */
+function sortByLastActiveTimeDesc(projects: ProjectOverview[]): void {
+  projects.sort((a, b) => new Date(b.lastActiveTime).getTime() - new Date(a.lastActiveTime).getTime());
+}
+
+// ─── 文本输出函数 ─────────────────────────────────
+
+/**
+ * 以文本格式输出所有项目概览
+ * @param {ProjectsOverviewResult} result - 项目概览结果
+ */
+function printProjectsOverviewAsText(result: ProjectsOverviewResult): void {
+  printDoubleSeparator();
+  printInfo(`  ${chalk.bold.cyan(MESSAGES.PROJECTS_OVERVIEW_TITLE)}`);
+  printDoubleSeparator();
+  printInfo('');
+
+  if (result.projects.length === 0) {
+    printInfo(`  ${MESSAGES.PROJECTS_NO_PROJECTS}`);
+    printInfo('');
+    printDoubleSeparator();
+    return;
+  }
+
+  for (const project of result.projects) {
+    printProjectOverviewItem(project);
+  }
+
+  printSeparator();
+  printInfo('');
+  printInfo(`  共 ${chalk.bold(String(result.totalProjects))} 个项目   ${chalk.gray(MESSAGES.PROJECTS_TOTAL_DISK_USAGE(formatDiskSize(result.totalDiskUsage)))}`);
+  printInfo('');
+  printDoubleSeparator();
+}
+
+/**
+ * 输出单个项目概览项
+ * @param {ProjectOverview} project - 项目概览
+ */
+function printProjectOverviewItem(project: ProjectOverview): void {
+  const relativeTime = formatRelativeTime(project.lastActiveTime);
+  const activeLabel = relativeTime ? MESSAGES.PROJECTS_LAST_ACTIVE(relativeTime) : '';
+  const diskLabel = MESSAGES.PROJECTS_DISK_USAGE(formatDiskSize(project.diskUsage));
+
+  printInfo(`  ${chalk.bold('●')} ${chalk.bold(project.name)}`);
+  printInfo(`    ${MESSAGES.PROJECTS_WORKTREE_COUNT(project.worktreeCount)}   ${chalk.gray(activeLabel)}   ${chalk.gray(diskLabel)}`);
+  printInfo('');
+}
+
+/**
+ * 以文本格式输出指定项目的 worktree 详情
+ * @param {ProjectDetailResult} result - 项目详情结果
+ */
+function printProjectDetailAsText(result: ProjectDetailResult): void {
+  printDoubleSeparator();
+  printInfo(`  ${chalk.bold.cyan(MESSAGES.PROJECTS_DETAIL_TITLE(result.name))}`);
+  printDoubleSeparator();
+  printInfo('');
+
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.PROJECTS_PATH(result.projectDir))}`);
+  printInfo(`    ${MESSAGES.PROJECTS_TOTAL_DISK_USAGE(formatDiskSize(result.totalDiskUsage))}`);
+  printInfo('');
+
+  printSeparator();
+  printInfo('');
+
+  if (result.worktrees.length === 0) {
+    printInfo(`  ${MESSAGES.PROJECTS_DETAIL_NO_WORKTREES}`);
+    printInfo('');
+    printDoubleSeparator();
+    return;
+  }
+
+  for (const wt of result.worktrees) {
+    printWorktreeDetailItem(wt);
+  }
+
+  printDoubleSeparator();
+}
+
+/**
+ * 输出单个 worktree 详情项
+ * @param {ProjectWorktreeDetail} wt - worktree 详情
+ */
+function printWorktreeDetailItem(wt: ProjectWorktreeDetail): void {
+  const relativeTime = formatRelativeTime(wt.lastModifiedTime);
+  const modifiedLabel = relativeTime ? MESSAGES.PROJECTS_LAST_MODIFIED(relativeTime) : '';
+  const diskLabel = MESSAGES.PROJECTS_DISK_USAGE(formatDiskSize(wt.diskUsage));
+
+  printInfo(`  ${chalk.bold('●')} ${chalk.bold(wt.branch)}`);
+  printInfo(`    ${wt.path}`);
+  printInfo(`    ${chalk.gray(modifiedLabel)}   ${chalk.gray(diskLabel)}`);
+  printInfo('');
+}