clawt 2.9.1 → 2.10.0

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

@@ -4,13 +4,14 @@
 
 ### docs/spec.md
 - 完整的软件规格说明，包含 7 大章节
-- 命令流程在 `5. 需求场景详细设计` 下，每个命令一个子章节（5.1-5.13）
+- 命令流程在 `5. 需求场景详细设计` 下，每个命令一个子章节（5.1-5.14）
 - run 命令对应 `5.2 批量创建 Worktree + 执行 Claude Code 任务`，流程按步骤编号描述
 - merge 命令对应 `5.6 合并验证过的分支`，-b 可选，支持模糊匹配（与 resume/validate 共享匹配逻辑），流程按步骤编号描述
 - config 命令对应 `5.10 查看和管理全局配置`，包含查看配置和 config reset 子命令两部分（使用 `####` 子标题区分）
 - resume 命令对应 `5.11 在已有 Worktree 中恢复会话`，支持模糊匹配和交互式分支选择（-b 可选）
 - validate 命令对应 `5.4 在主 Worktree 验证其他分支`，-b 可选，支持模糊匹配（与 resume 共享匹配逻辑）
 - sync 命令对应 `5.12 将主分支代码同步到目标 Worktree`，-b 可选，支持模糊匹配（与 resume/validate/merge 共享匹配逻辑）
+- status 命令对应 `5.14 项目全局状态总览`，支持 `--json` 格式输出，展示主 worktree 状态、各 worktree 详细状态、未清理快照
 - 配置项说明在 `5.7 默认配置文件` 章节的表格中
 - 更新模式：新增步骤时追加编号，配置项影响范围变化时更新说明列
 
@@ -36,7 +37,7 @@
 - cleanupWorktrees 是 merge 和 run 共用的公共清理函数（在 src/utils/worktree.ts）
 - `launchInteractiveClaude` 是 run（交互式模式）和 resume 共用的公共函数（在 src/utils/claude.ts）
 - killAllChildProcesses 是 run 专用的子进程终止函数（在 src/utils/shell.ts）
-- validate 快照管理函数在 `src/utils/validate-snapshot.ts`，被 validate、merge 和 remove 三个命令使用
+- validate 快照管理函数在 `src/utils/validate-snapshot.ts`，被 validate、merge、remove 和 status 四个命令使用
 - `confirmDestructiveAction` 在 `src/utils/formatter.ts`，被 reset、validate --clean 和 config reset 使用
 - sanitizeBranchName 清理后为空串时抛出 BRANCH_NAME_EMPTY 错误
 
@@ -61,9 +62,9 @@ run 命令有两种模式（自 claudeCodeCommand 特性后）：
 - 不传 `--tasks`：交互式界面模式（单 worktree + `launchInteractiveClaude` + spawnSync）
 - 传 `--tasks`：并行任务模式（多 worktree + `executeClaudeTask` + spawnProcess）
 
-## 命令清单（10 个）
+## 命令清单（11 个）
 
-`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`、`sync`、`reset`
+`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`、`sync`、`reset`、`status`
 
 Notes:
 - resume 和 run（交互式模式）共用 `launchInteractiveClaude()`，该函数从 run.ts 提取到 src/utils/claude.ts
@@ -71,7 +72,7 @@ Notes:
 - reset 命令与 validate --clean 的区别：reset 不删除快照文件，validate --clean 会删除快照
 - `resolveTargetWorktree()` 是 resume、validate、merge 和 sync 共用的分支匹配函数（在 src/utils/worktree-matcher.ts）
 - `WorktreeResolveMessages` 接口实现命令间消息解耦，每个命令传入各自的提示文案
-- resume 的消息常量在 `MESSAGES.RESUME_*`，validate 的消息常量在 `MESSAGES.VALIDATE_*`，merge 的消息常量在 `MESSAGES.MERGE_*`，sync 的消息常量在 `MESSAGES.SYNC_*`
+- resume 的消息常量在 `MESSAGES.RESUME_*`，validate 的消息常量在 `MESSAGES.VALIDATE_*`，merge 的消息常量在 `MESSAGES.MERGE_*`，sync 的消息常量在 `MESSAGES.SYNC_*`，status 的消息常量在 `MESSAGES.STATUS_*`
 - resume、validate、merge 和 sync 的 `-b` 参数均为可选，匹配策略一致：精确→模糊（子串，大小写不敏感）→交互选择
 - validate 的交互式选择和 resume 使用同一个 `promptSelectBranch()`（Enquirer.Select）
 

package/README.md

@@ -273,6 +273,28 @@ clawt list
 clawt list --json
 ```
 
+### `clawt status` — 显示项目全局状态总览
+
+```bash
+clawt status [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `--json` | 否 | 以 JSON 格式输出完整状态数据 |
+
+显示项目全局状态总览，包括：主 worktree 当前分支及干净状态、所有 worktree 的变更状态（已提交/未提交/合并冲突/无变更）、与主分支的差异（领先/落后提交数、行数变更）、未清理的 validate 快照检测（标识孤立快照）。
+
+文本模式下输出分为三个区块：主 Worktree 状态、Worktree 列表（含变更状态标签和差异统计）、未清理的 Validate 快照。指定 `--json` 时以 JSON 格式输出完整状态数据，便于脚本解析。
+
+```bash
+# 文本格式输出（默认）
+clawt status
+
+# JSON 格式输出
+clawt status --json
+```
+
 ### `clawt reset` — 重置主 worktree 工作区和暂存区
 
 ```bash

package/dist/index.js

@@ -167,6 +167,28 @@ ${branches.map((b) => `    - ${b}`).join("\n")}`,
   SYNC_SELECT_BRANCH: "\u8BF7\u9009\u62E9\u8981\u540C\u6B65\u7684\u5206\u652F",
   /** sync 模糊匹配到多个结果提示 */
   SYNC_MULTIPLE_MATCHES: (name) => `"${name}" \u5339\u914D\u5230\u591A\u4E2A\u5206\u652F\uFF0C\u8BF7\u9009\u62E9\uFF1A`,
+  /** status 命令标题 */
+  STATUS_TITLE: (projectName) => `\u9879\u76EE\u72B6\u6001\u603B\u89C8: ${projectName}`,
+  /** status 主 worktree 区块标题 */
+  STATUS_MAIN_SECTION: "\u4E3B Worktree",
+  /** status worktrees 区块标题 */
+  STATUS_WORKTREES_SECTION: "Worktree \u5217\u8868",
+  /** status 快照区块标题 */
+  STATUS_SNAPSHOTS_SECTION: "\u672A\u6E05\u7406\u7684 Validate \u5FEB\u7167",
+  /** status 无 worktree */
+  STATUS_NO_WORKTREES: "(\u65E0\u6D3B\u8DC3 worktree)",
+  /** status 无未清理快照 */
+  STATUS_NO_SNAPSHOTS: "(\u65E0\u672A\u6E05\u7406\u7684\u5FEB\u7167)",
+  /** status 变更状态：已提交 */
+  STATUS_CHANGE_COMMITTED: "\u5DF2\u63D0\u4EA4",
+  /** status 变更状态：未提交修改 */
+  STATUS_CHANGE_UNCOMMITTED: "\u672A\u63D0\u4EA4\u4FEE\u6539",
+  /** status 变更状态：合并冲突 */
+  STATUS_CHANGE_CONFLICT: "\u5408\u5E76\u51B2\u7A81",
+  /** status 变更状态：无变更 */
+  STATUS_CHANGE_CLEAN: "\u65E0\u53D8\u66F4",
+  /** status 快照对应 worktree 已不存在 */
+  STATUS_SNAPSHOT_ORPHANED: "(\u5BF9\u5E94 worktree \u5DF2\u4E0D\u5B58\u5728)",
   /** merge 后 pull 冲突 */
   PULL_CONFLICT: "\u81EA\u52A8 pull \u65F6\u53D1\u751F\u51B2\u7A81\uFF0Cmerge \u5DF2\u5B8C\u6210\u4F46\u8FDC\u7A0B\u540C\u6B65\u5931\u8D25\n  \u8BF7\u624B\u52A8\u89E3\u51B3\u51B2\u7A81\uFF1A\n  \u89E3\u51B3\u51B2\u7A81\u540E\u6267\u884C git add . && git commit\n  \u7136\u540E\u6267\u884C git push \u63A8\u9001\u5230\u8FDC\u7A0B",
   /** push 失败 */
@@ -420,6 +442,14 @@ function getCommitCountAhead(branchName, cwd) {
   const output = execCommand(`git rev-list --count HEAD..${branchName}`, { cwd });
   return parseInt(output, 10) || 0;
 }
+function getCommitCountBehind(branchName, cwd) {
+  try {
+    const output = execCommand(`git rev-list --count ${branchName}..HEAD`, { cwd });
+    return parseInt(output, 10) || 0;
+  } catch {
+    return 0;
+  }
+}
 function parseShortStat(output) {
   let insertions = 0;
   let deletions = 0;
@@ -798,6 +828,14 @@ function removeSnapshot(projectName, branchName) {
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${headPath}`);
   }
 }
+function getProjectSnapshotBranches(projectName) {
+  const projectDir = join3(VALIDATE_SNAPSHOTS_DIR, projectName);
+  if (!existsSync5(projectDir)) {
+    return [];
+  }
+  const files = readdirSync3(projectDir);
+  return files.filter((f) => f.endsWith(".tree")).map((f) => f.replace(/\.tree$/, ""));
+}
 function removeProjectSnapshots(projectName) {
   const projectDir = join3(VALIDATE_SNAPSHOTS_DIR, projectName);
   if (!existsSync5(projectDir)) {
@@ -1632,6 +1670,185 @@ async function handleReset() {
   }
 }
 
+// src/commands/status.ts
+import chalk5 from "chalk";
+function registerStatusCommand(program2) {
+  program2.command("status").description("\u663E\u793A\u9879\u76EE\u5168\u5C40\u72B6\u6001\u603B\u89C8").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((options) => {
+    handleStatus(options);
+  });
+}
+function handleStatus(options) {
+  validateMainWorktree();
+  const statusResult = collectStatus();
+  logger.info(`status \u547D\u4EE4\u6267\u884C\uFF0C\u9879\u76EE: ${statusResult.main.projectName}\uFF0C\u5171 ${statusResult.totalWorktrees} \u4E2A worktree`);
+  if (options.json) {
+    printStatusAsJson(statusResult);
+    return;
+  }
+  printStatusAsText(statusResult);
+}
+function collectStatus() {
+  const projectName = getProjectName();
+  const currentBranch = getCurrentBranch();
+  const isClean = isWorkingDirClean();
+  const main = {
+    branch: currentBranch,
+    isClean,
+    projectName
+  };
+  const worktrees = getProjectWorktrees();
+  const worktreeStatuses = worktrees.map((wt) => collectWorktreeDetailedStatus(wt, projectName));
+  const snapshots = collectSnapshots(projectName, worktrees);
+  return {
+    main,
+    worktrees: worktreeStatuses,
+    snapshots,
+    totalWorktrees: worktrees.length
+  };
+}
+function collectWorktreeDetailedStatus(worktree, projectName) {
+  const changeStatus = detectChangeStatus(worktree);
+  const { commitsAhead, commitsBehind } = countCommitDivergence(worktree.branch);
+  const { insertions, deletions } = countDiffStat(worktree.path);
+  return {
+    path: worktree.path,
+    branch: worktree.branch,
+    changeStatus,
+    commitsAhead,
+    commitsBehind,
+    hasSnapshot: hasSnapshot(projectName, worktree.branch),
+    insertions,
+    deletions
+  };
+}
+function detectChangeStatus(worktree) {
+  try {
+    if (hasMergeConflict(worktree.path)) {
+      return "conflict";
+    }
+    if (!isWorkingDirClean(worktree.path)) {
+      return "uncommitted";
+    }
+    if (hasLocalCommits(worktree.branch)) {
+      return "committed";
+    }
+    return "clean";
+  } catch {
+    return "clean";
+  }
+}
+function countCommitDivergence(branchName) {
+  try {
+    return {
+      commitsAhead: getCommitCountAhead(branchName),
+      commitsBehind: getCommitCountBehind(branchName)
+    };
+  } catch {
+    return { commitsAhead: 0, commitsBehind: 0 };
+  }
+}
+function countDiffStat(worktreePath) {
+  try {
+    return getDiffStat(worktreePath);
+  } catch {
+    return { insertions: 0, deletions: 0 };
+  }
+}
+function collectSnapshots(projectName, worktrees) {
+  const snapshotBranches = getProjectSnapshotBranches(projectName);
+  const worktreeBranchSet = new Set(worktrees.map((wt) => wt.branch));
+  return snapshotBranches.map((branch) => ({
+    branch,
+    worktreeExists: worktreeBranchSet.has(branch)
+  }));
+}
+function printStatusAsJson(result) {
+  console.log(JSON.stringify(result, null, 2));
+}
+function printStatusAsText(result) {
+  printDoubleSeparator();
+  printInfo(`  ${chalk5.bold.cyan(MESSAGES.STATUS_TITLE(result.main.projectName))}`);
+  printDoubleSeparator();
+  printInfo("");
+  printMainSection(result.main);
+  printSeparator();
+  printInfo("");
+  printWorktreesSection(result.worktrees, result.totalWorktrees);
+  printSeparator();
+  printInfo("");
+  printSnapshotsSection(result.snapshots);
+  printDoubleSeparator();
+}
+function printMainSection(main) {
+  printInfo(`  ${chalk5.bold("\u25C6")} ${chalk5.bold(MESSAGES.STATUS_MAIN_SECTION)}`);
+  printInfo(`    \u5206\u652F: ${chalk5.bold(main.branch)}`);
+  if (main.isClean) {
+    printInfo(`    \u72B6\u6001: ${chalk5.green("\u2713 \u5E72\u51C0")}`);
+  } else {
+    printInfo(`    \u72B6\u6001: ${chalk5.yellow("\u2717 \u6709\u672A\u63D0\u4EA4\u4FEE\u6539")}`);
+  }
+  printInfo("");
+}
+function printWorktreesSection(worktrees, total) {
+  printInfo(`  ${chalk5.bold("\u25C6")} ${chalk5.bold(MESSAGES.STATUS_WORKTREES_SECTION)} (${total} \u4E2A)`);
+  printInfo("");
+  if (worktrees.length === 0) {
+    printInfo(`    ${MESSAGES.STATUS_NO_WORKTREES}`);
+    return;
+  }
+  for (const wt of worktrees) {
+    printWorktreeItem(wt);
+  }
+}
+function printWorktreeItem(wt) {
+  const statusLabel = formatChangeStatusLabel(wt.changeStatus);
+  printInfo(`  ${chalk5.bold("\u25CF")} ${chalk5.bold(wt.branch)}   [${statusLabel}]`);
+  const parts = [];
+  if (wt.insertions > 0 || wt.deletions > 0) {
+    parts.push(`${chalk5.green(`+${wt.insertions}`)} ${chalk5.red(`-${wt.deletions}`)}`);
+  }
+  if (wt.commitsAhead > 0) {
+    parts.push(chalk5.yellow(`${wt.commitsAhead} \u4E2A\u672C\u5730\u63D0\u4EA4`));
+  }
+  if (wt.commitsBehind > 0) {
+    parts.push(chalk5.yellow(`\u843D\u540E\u4E3B\u5206\u652F ${wt.commitsBehind} \u4E2A\u63D0\u4EA4`));
+  } else {
+    parts.push(chalk5.green("\u4E0E\u4E3B\u5206\u652F\u540C\u6B65"));
+  }
+  printInfo(`    ${parts.join("   ")}`);
+  if (wt.hasSnapshot) {
+    printInfo(`    ${chalk5.blue("\u6709 validate \u5FEB\u7167")}`);
+  }
+  printInfo("");
+}
+function formatChangeStatusLabel(status) {
+  switch (status) {
+    case "committed":
+      return chalk5.green(MESSAGES.STATUS_CHANGE_COMMITTED);
+    case "uncommitted":
+      return chalk5.yellow(MESSAGES.STATUS_CHANGE_UNCOMMITTED);
+    case "conflict":
+      return chalk5.red(MESSAGES.STATUS_CHANGE_CONFLICT);
+    case "clean":
+      return chalk5.gray(MESSAGES.STATUS_CHANGE_CLEAN);
+  }
+}
+function printSnapshotsSection(snapshots) {
+  printInfo(`  ${chalk5.bold("\u25C6")} ${chalk5.bold(MESSAGES.STATUS_SNAPSHOTS_SECTION)} (${snapshots.length} \u4E2A)`);
+  printInfo("");
+  if (snapshots.length === 0) {
+    printInfo(`    ${MESSAGES.STATUS_NO_SNAPSHOTS}`);
+    printInfo("");
+    return;
+  }
+  for (const snap of snapshots) {
+    const orphanLabel = snap.worktreeExists ? "" : `  ${chalk5.yellow(MESSAGES.STATUS_SNAPSHOT_ORPHANED)}`;
+    const icon = snap.worktreeExists ? chalk5.blue("\u25CF") : chalk5.yellow("\u26A0");
+    printInfo(`  ${icon} ${snap.branch}${orphanLabel}`);
+  }
+  printInfo("");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1653,6 +1870,7 @@ registerMergeCommand(program);
 registerConfigCommand(program);
 registerSyncCommand(program);
 registerResetCommand(program);
+registerStatusCommand(program);
 process.on("uncaughtException", (error) => {
   if (error instanceof ClawtError) {
     printError(error.message);

package/docs/spec.md

@@ -25,6 +25,7 @@
   - [5.11 在已有 Worktree 中恢复会话](#511-在已有-worktree-中恢复会话)
   - [5.12 将主分支代码同步到目标 Worktree](#512-将主分支代码同步到目标-worktree)
   - [5.13 重置主 Worktree 工作区和暂存区](#513-重置主-worktree-工作区和暂存区)
+  - [5.14 项目全局状态总览](#514-项目全局状态总览)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
   - [7.1 性能](#71-性能)
@@ -177,6 +178,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt resume`        | 在已有 worktree 中恢复 Claude Code 交互式会话      | 5.11     |
 | `clawt sync`          | 将主分支最新代码同步到目标 worktree                  | 5.12     |
 | `clawt reset`         | 重置主 worktree 工作区和暂存区                       | 5.13     |
+| `clawt status`        | 显示项目全局状态总览（支持 `--json` 格式输出）          | 5.14     |
 
 **全局选项：**
 
@@ -1122,6 +1124,139 @@ clawt reset
 
 ---
 
+### 5.14 项目全局状态总览
+
+**命令：**
+
+```bash
+clawt status [--json]
+```
+
+**参数：**
+
+| 参数     | 必填 | 说明                                     |
+| -------- | ---- | ---------------------------------------- |
+| `--json` | 否   | 以 JSON 格式输出完整状态数据              |
+
+**使用场景：**
+
+在管理多个 worktree 时，快速了解项目全局状态：主 worktree 当前分支及干净状态、所有 worktree 的变更情况和与主分支的同步状态、未清理的 validate 快照。
+
+**运行流程：**
+
+1. **主 worktree 校验** (2.1)
+2. **收集主 worktree 状态**：
+   - 获取当前分支名（`getCurrentBranch()`）
+   - 检测工作区是否干净（`isWorkingDirClean()`）
+   - 获取项目名（`getProjectName()`）
+3. **收集各 worktree 详细状态**：
+   - 获取项目所有 worktree（`getProjectWorktrees()`）
+   - 对每个 worktree 收集以下信息：
+     - **变更状态**（优先级：合并冲突 > 未提交修改 > 已提交 > 无变更）
+     - **行数差异**（新增/删除行数，通过 `getDiffStat()` 获取）
+     - **提交差异**（相对于主分支的领先提交数 `getCommitCountAhead()` 和落后提交数 `getCommitCountBehind()`）
+     - **快照状态**（是否存在 validate 快照）
+4. **收集未清理的 validate 快照**：
+   - 通过 `getProjectSnapshotBranches()` 扫描快照目录下的 `.tree` 文件获取所有存在快照的分支名
+   - 对比现有 worktree 分支列表，标识孤立快照（对应 worktree 已不存在的快照）
+5. **输出状态信息**：
+   - 指定 `--json` → 以 JSON 格式输出完整状态数据（`JSON.stringify`）
+   - 未指定 → 以文本格式输出
+
+**文本输出格式（默认）：**
+
+输出分为三个区块：主 Worktree、Worktree 列表、未清理的 Validate 快照。
+
+```
+════════════════════════════════════════
+  项目状态总览: main-project
+════════════════════════════════════════
+
+  ◆ 主 Worktree
+    分支: main
+    状态: ✓ 干净
+
+────────────────────────────────────────
+
+  ◆ Worktree 列表 (2 个)
+
+  ● feature-login   [已提交]
+    +120 -30   3 个本地提交   与主分支同步
+    有 validate 快照
+
+  ● feature-signup   [未提交修改]
+    +45 -10   1 个本地提交   落后主分支 2 个提交
+
+────────────────────────────────────────
+
+  ◆ 未清理的 Validate 快照 (1 个)
+
+  ⚠ old-feature   (对应 worktree 已不存在)
+
+════════════════════════════════════════
+```
+
+**变更状态标签：**
+
+| 状态        | 标签           | 颜色   | 说明                          |
+| ----------- | -------------- | ------ | ----------------------------- |
+| `committed` | 已提交         | 绿色   | 有已提交内容，工作区干净       |
+| `uncommitted` | 未提交修改   | 黄色   | 有未提交的修改                 |
+| `conflict`  | 合并冲突       | 红色   | 存在合并冲突                   |
+| `clean`     | 无变更         | 灰色   | 工作区干净且无本地提交          |
+
+**差异统计行展示规则：**
+
+- 行数变更（`+N -N`）仅在有变更时展示
+- 本地提交数（`N 个本地提交`）仅在有提交时展示
+- 与主分支同步状态始终展示（落后时显示黄色，同步时显示绿色）
+
+**快照区块：**
+
+- 每个快照显示对应的分支名
+- 如果对应的 worktree 仍存在，显示蓝色圆点图标
+- 如果对应的 worktree 已不存在（孤立快照），显示黄色警告图标并标注 `(对应 worktree 已不存在)`
+
+**JSON 输出格式（`--json`）：**
+
+```json
+{
+  "main": {
+    "branch": "main",
+    "isClean": true,
+    "projectName": "main-project"
+  },
+  "worktrees": [
+    {
+      "path": "~/.clawt/worktrees/main-project/feature-login",
+      "branch": "feature-login",
+      "changeStatus": "committed",
+      "commitsAhead": 3,
+      "commitsBehind": 0,
+      "hasSnapshot": true,
+      "insertions": 120,
+      "deletions": 30
+    }
+  ],
+  "snapshots": [
+    {
+      "branch": "old-feature",
+      "worktreeExists": false
+    }
+  ],
+  "totalWorktrees": 1
+}
+```
+
+**实现要点：**
+
+- 类型定义在 `src/types/status.ts`：`WorktreeDetailedStatus`、`MainWorktreeStatus`、`SnapshotInfo`、`StatusResult`
+- 消息常量在 `MESSAGES.STATUS_*` 系列
+- `getCommitCountBehind()` 是新增的工具函数（在 `src/utils/git.ts`），通过 `git rev-list --count <branch>..HEAD` 计算落后提交数
+- `getProjectSnapshotBranches()` 是新增的工具函数（在 `src/utils/validate-snapshot.ts`），通过扫描快照目录下的 `.tree` 文件提取分支名列表
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

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

package/src/commands/status.ts

@@ -0,0 +1,327 @@
+import type { Command } from 'commander';
+import chalk from 'chalk';
+import { MESSAGES } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import type { StatusOptions, WorktreeDetailedStatus, MainWorktreeStatus, SnapshotInfo, StatusResult, WorktreeInfo } from '../types/index.js';
+import {
+  validateMainWorktree,
+  getProjectName,
+  getCurrentBranch,
+  isWorkingDirClean,
+  getProjectWorktrees,
+  getCommitCountAhead,
+  getCommitCountBehind,
+  getDiffStat,
+  hasMergeConflict,
+  hasLocalCommits,
+  hasSnapshot,
+  getProjectSnapshotBranches,
+  printInfo,
+  printDoubleSeparator,
+  printSeparator,
+} from '../utils/index.js';
+
+/**
+ * 注册 status 命令：显示项目全局状态总览
+ * @param {Command} program - Commander 实例
+ */
+export function registerStatusCommand(program: Command): void {
+  program
+    .command('status')
+    .description('显示项目全局状态总览')
+    .option('--json', '以 JSON 格式输出')
+    .action((options: StatusOptions) => {
+      handleStatus(options);
+    });
+}
+
+/**
+ * 执行 status 命令的核心逻辑
+ * @param {StatusOptions} options - 命令选项
+ */
+function handleStatus(options: StatusOptions): void {
+  validateMainWorktree();
+
+  const statusResult = collectStatus();
+
+  logger.info(`status 命令执行，项目: ${statusResult.main.projectName}，共 ${statusResult.totalWorktrees} 个 worktree`);
+
+  if (options.json) {
+    printStatusAsJson(statusResult);
+    return;
+  }
+
+  printStatusAsText(statusResult);
+}
+
+/**
+ * 收集项目全局状态信息
+ * @returns {StatusResult} 完整的状态数据
+ */
+function collectStatus(): StatusResult {
+  const projectName = getProjectName();
+  const currentBranch = getCurrentBranch();
+  const isClean = isWorkingDirClean();
+
+  // 主 worktree 状态
+  const main: MainWorktreeStatus = {
+    branch: currentBranch,
+    isClean,
+    projectName,
+  };
+
+  // 各 worktree 详细状态
+  const worktrees = getProjectWorktrees();
+  const worktreeStatuses = worktrees.map((wt) => collectWorktreeDetailedStatus(wt, projectName));
+
+  // 未清理的 validate 快照
+  const snapshots = collectSnapshots(projectName, worktrees);
+
+  return {
+    main,
+    worktrees: worktreeStatuses,
+    snapshots,
+    totalWorktrees: worktrees.length,
+  };
+}
+
+/**
+ * 收集单个 worktree 的详细状态
+ * 变更状态判断优先级：冲突 > 未提交 > 已提交 > 干净
+ * @param {WorktreeInfo} worktree - worktree 信息
+ * @param {string} projectName - 项目名
+ * @returns {WorktreeDetailedStatus} 详细状态
+ */
+function collectWorktreeDetailedStatus(worktree: WorktreeInfo, projectName: string): WorktreeDetailedStatus {
+  const changeStatus = detectChangeStatus(worktree);
+  const { commitsAhead, commitsBehind } = countCommitDivergence(worktree.branch);
+  const { insertions, deletions } = countDiffStat(worktree.path);
+
+  return {
+    path: worktree.path,
+    branch: worktree.branch,
+    changeStatus,
+    commitsAhead,
+    commitsBehind,
+    hasSnapshot: hasSnapshot(projectName, worktree.branch),
+    insertions,
+    deletions,
+  };
+}
+
+/**
+ * 检测 worktree 的变更状态
+ * 优先级：冲突 > 未提交 > 已提交 > 干净
+ * @param {WorktreeInfo} worktree - worktree 信息
+ * @returns {WorktreeDetailedStatus['changeStatus']} 变更状态
+ */
+function detectChangeStatus(worktree: WorktreeInfo): WorktreeDetailedStatus['changeStatus'] {
+  try {
+    if (hasMergeConflict(worktree.path)) {
+      return 'conflict';
+    }
+    if (!isWorkingDirClean(worktree.path)) {
+      return 'uncommitted';
+    }
+    if (hasLocalCommits(worktree.branch)) {
+      return 'committed';
+    }
+    return 'clean';
+  } catch {
+    return 'clean';
+  }
+}
+
+/**
+ * 统计分支与主分支的提交差异（领先/落后数）
+ * @param {string} branchName - 分支名
+ * @returns {{ commitsAhead: number; commitsBehind: number }} 领先和落后的提交数
+ */
+function countCommitDivergence(branchName: string): { commitsAhead: number; commitsBehind: number } {
+  try {
+    return {
+      commitsAhead: getCommitCountAhead(branchName),
+      commitsBehind: getCommitCountBehind(branchName),
+    };
+  } catch {
+    return { commitsAhead: 0, commitsBehind: 0 };
+  }
+}
+
+/**
+ * 统计 worktree 的差异行数
+ * @param {string} worktreePath - worktree 路径
+ * @returns {{ insertions: number; deletions: number }} 新增和删除行数
+ */
+function countDiffStat(worktreePath: string): { insertions: number; deletions: number } {
+  try {
+    return getDiffStat(worktreePath);
+  } catch {
+    return { insertions: 0, deletions: 0 };
+  }
+}
+
+/**
+ * 收集未清理的 validate 快照信息
+ * 对比快照分支与现有 worktree 分支，标识孤立快照
+ * @param {string} projectName - 项目名
+ * @param {WorktreeInfo[]} worktrees - 当前有效的 worktree 列表
+ * @returns {SnapshotInfo[]} 快照信息列表
+ */
+function collectSnapshots(projectName: string, worktrees: WorktreeInfo[]): SnapshotInfo[] {
+  const snapshotBranches = getProjectSnapshotBranches(projectName);
+  const worktreeBranchSet = new Set(worktrees.map((wt) => wt.branch));
+
+  return snapshotBranches.map((branch) => ({
+    branch,
+    worktreeExists: worktreeBranchSet.has(branch),
+  }));
+}
+
+/**
+ * 以 JSON 格式输出状态信息
+ * @param {StatusResult} result - 状态数据
+ */
+function printStatusAsJson(result: StatusResult): void {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+/**
+ * 以文本格式输出状态信息
+ * @param {StatusResult} result - 状态数据
+ */
+function printStatusAsText(result: StatusResult): void {
+  // 标题区域
+  printDoubleSeparator();
+  printInfo(`  ${chalk.bold.cyan(MESSAGES.STATUS_TITLE(result.main.projectName))}`);
+  printDoubleSeparator();
+  printInfo('');
+
+  // 主 Worktree 区块
+  printMainSection(result.main);
+  printSeparator();
+  printInfo('');
+
+  // Worktree 列表区块
+  printWorktreesSection(result.worktrees, result.totalWorktrees);
+  printSeparator();
+  printInfo('');
+
+  // 未清理快照区块
+  printSnapshotsSection(result.snapshots);
+
+  printDoubleSeparator();
+}
+
+/**
+ * 输出主 Worktree 区块
+ * @param {MainWorktreeStatus} main - 主 worktree 状态
+ */
+function printMainSection(main: MainWorktreeStatus): void {
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.STATUS_MAIN_SECTION)}`);
+  printInfo(`    分支: ${chalk.bold(main.branch)}`);
+  if (main.isClean) {
+    printInfo(`    状态: ${chalk.green('✓ 干净')}`);
+  } else {
+    printInfo(`    状态: ${chalk.yellow('✗ 有未提交修改')}`);
+  }
+  printInfo('');
+}
+
+/**
+ * 输出 Worktree 列表区块
+ * @param {WorktreeDetailedStatus[]} worktrees - worktree 详细状态列表
+ * @param {number} total - worktree 总数
+ */
+function printWorktreesSection(worktrees: WorktreeDetailedStatus[], total: number): void {
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.STATUS_WORKTREES_SECTION)} (${total} 个)`);
+  printInfo('');
+
+  if (worktrees.length === 0) {
+    printInfo(`    ${MESSAGES.STATUS_NO_WORKTREES}`);
+    return;
+  }
+
+  for (const wt of worktrees) {
+    printWorktreeItem(wt);
+  }
+}
+
+/**
+ * 输出单个 worktree 状态项
+ * @param {WorktreeDetailedStatus} wt - worktree 详细状态
+ */
+function printWorktreeItem(wt: WorktreeDetailedStatus): void {
+  // 分支名 + 变更状态标签
+  const statusLabel = formatChangeStatusLabel(wt.changeStatus);
+  printInfo(`  ${chalk.bold('●')} ${chalk.bold(wt.branch)}   [${statusLabel}]`);
+
+  // 差异统计行
+  const parts: string[] = [];
+
+  // 行数变更（仅在有变更时展示）
+  if (wt.insertions > 0 || wt.deletions > 0) {
+    parts.push(`${chalk.green(`+${wt.insertions}`)} ${chalk.red(`-${wt.deletions}`)}`);
+  }
+
+  // 本地提交数
+  if (wt.commitsAhead > 0) {
+    parts.push(chalk.yellow(`${wt.commitsAhead} 个本地提交`));
+  }
+
+  // 与主分支的同步状态
+  if (wt.commitsBehind > 0) {
+    parts.push(chalk.yellow(`落后主分支 ${wt.commitsBehind} 个提交`));
+  } else {
+    parts.push(chalk.green('与主分支同步'));
+  }
+
+  printInfo(`    ${parts.join('   ')}`);
+
+  // 快照状态
+  if (wt.hasSnapshot) {
+    printInfo(`    ${chalk.blue('有 validate 快照')}`);
+  }
+
+  printInfo('');
+}
+
+/**
+ * 将变更状态枚举格式化为带颜色的标签文本
+ * @param {WorktreeDetailedStatus['changeStatus']} status - 变更状态
+ * @returns {string} 格式化后的标签
+ */
+function formatChangeStatusLabel(status: WorktreeDetailedStatus['changeStatus']): string {
+  switch (status) {
+    case 'committed':
+      return chalk.green(MESSAGES.STATUS_CHANGE_COMMITTED);
+    case 'uncommitted':
+      return chalk.yellow(MESSAGES.STATUS_CHANGE_UNCOMMITTED);
+    case 'conflict':
+      return chalk.red(MESSAGES.STATUS_CHANGE_CONFLICT);
+    case 'clean':
+      return chalk.gray(MESSAGES.STATUS_CHANGE_CLEAN);
+  }
+}
+
+/**
+ * 输出未清理快照区块
+ * @param {SnapshotInfo[]} snapshots - 快照信息列表
+ */
+function printSnapshotsSection(snapshots: SnapshotInfo[]): void {
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.STATUS_SNAPSHOTS_SECTION)} (${snapshots.length} 个)`);
+  printInfo('');
+
+  if (snapshots.length === 0) {
+    printInfo(`    ${MESSAGES.STATUS_NO_SNAPSHOTS}`);
+    printInfo('');
+    return;
+  }
+
+  for (const snap of snapshots) {
+    const orphanLabel = snap.worktreeExists ? '' : `  ${chalk.yellow(MESSAGES.STATUS_SNAPSHOT_ORPHANED)}`;
+    const icon = snap.worktreeExists ? chalk.blue('●') : chalk.yellow('⚠');
+    printInfo(`  ${icon} ${snap.branch}${orphanLabel}`);
+  }
+  printInfo('');
+}

package/src/constants/messages.ts

@@ -148,6 +148,28 @@ export const MESSAGES = {
   SYNC_SELECT_BRANCH: '请选择要同步的分支',
   /** sync 模糊匹配到多个结果提示 */
   SYNC_MULTIPLE_MATCHES: (name: string) => `"${name}" 匹配到多个分支，请选择：`,
+  /** status 命令标题 */
+  STATUS_TITLE: (projectName: string) => `项目状态总览: ${projectName}`,
+  /** status 主 worktree 区块标题 */
+  STATUS_MAIN_SECTION: '主 Worktree',
+  /** status worktrees 区块标题 */
+  STATUS_WORKTREES_SECTION: 'Worktree 列表',
+  /** status 快照区块标题 */
+  STATUS_SNAPSHOTS_SECTION: '未清理的 Validate 快照',
+  /** status 无 worktree */
+  STATUS_NO_WORKTREES: '(无活跃 worktree)',
+  /** status 无未清理快照 */
+  STATUS_NO_SNAPSHOTS: '(无未清理的快照)',
+  /** status 变更状态：已提交 */
+  STATUS_CHANGE_COMMITTED: '已提交',
+  /** status 变更状态：未提交修改 */
+  STATUS_CHANGE_UNCOMMITTED: '未提交修改',
+  /** status 变更状态：合并冲突 */
+  STATUS_CHANGE_CONFLICT: '合并冲突',
+  /** status 变更状态：无变更 */
+  STATUS_CHANGE_CLEAN: '无变更',
+  /** status 快照对应 worktree 已不存在 */
+  STATUS_SNAPSHOT_ORPHANED: '(对应 worktree 已不存在)',
   /** merge 后 pull 冲突 */
   PULL_CONFLICT:
     '自动 pull 时发生冲突，merge 已完成但远程同步失败\n  请手动解决冲突：\n  解决冲突后执行 git add . && git commit\n  然后执行 git push 推送到远程',

package/src/index.ts

@@ -14,6 +14,7 @@ import { registerMergeCommand } from './commands/merge.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerResetCommand } from './commands/reset.js';
+import { registerStatusCommand } from './commands/status.js';
 
 // 从 package.json 读取版本号，避免硬编码
 const require = createRequire(import.meta.url);
@@ -48,6 +49,7 @@ registerMergeCommand(program);
 registerConfigCommand(program);
 registerSyncCommand(program);
 registerResetCommand(program);
+registerStatusCommand(program);
 
 // 全局未捕获异常处理
 process.on('uncaughtException', (error) => {

package/src/types/command.ts

@@ -55,3 +55,9 @@ export interface ListOptions {
   /** 以 JSON 格式输出 */
   json?: boolean;
 }
+
+/** status 命令选项 */
+export interface StatusOptions {
+  /** 以 JSON 格式输出 */
+  json?: boolean;
+}

package/src/types/index.ts

@@ -1,5 +1,6 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions } from './command.js';
 export type { WorktreeInfo, WorktreeStatus } from './worktree.js';
 export type { ClaudeCodeResult } from './claudeCode.js';
 export type { TaskResult, TaskSummary } from './taskResult.js';
+export type { WorktreeDetailedStatus, MainWorktreeStatus, SnapshotInfo, StatusResult } from './status.js';

package/src/types/status.ts

@@ -0,0 +1,49 @@
+/** 单个 worktree 的详细状态信息 */
+export interface WorktreeDetailedStatus {
+  /** worktree 路径 */
+  path: string;
+  /** 分支名 */
+  branch: string;
+  /** 变更状态: committed(有已提交内容) / uncommitted(有未提交修改) / conflict(存在合并冲突) / clean(无变更) */
+  changeStatus: 'committed' | 'uncommitted' | 'conflict' | 'clean';
+  /** 相对于主分支的新增提交数（领先） */
+  commitsAhead: number;
+  /** 落后于主分支的提交数 */
+  commitsBehind: number;
+  /** 是否存在 validate 快照 */
+  hasSnapshot: boolean;
+  /** 工作区和暂存区的新增行数 */
+  insertions: number;
+  /** 工作区和暂存区的删除行数 */
+  deletions: number;
+}
+
+/** 主 worktree 状态信息 */
+export interface MainWorktreeStatus {
+  /** 当前分支名 */
+  branch: string;
+  /** 工作区是否干净 */
+  isClean: boolean;
+  /** 项目名 */
+  projectName: string;
+}
+
+/** validate 快照信息 */
+export interface SnapshotInfo {
+  /** 分支名 */
+  branch: string;
+  /** 是否对应的 worktree 仍然存在 */
+  worktreeExists: boolean;
+}
+
+/** status 命令的完整输出结构 */
+export interface StatusResult {
+  /** 主 worktree 状态 */
+  main: MainWorktreeStatus;
+  /** 各 worktree 的详细状态 */
+  worktrees: WorktreeDetailedStatus[];
+  /** 未清理的 validate 快照列表 */
+  snapshots: SnapshotInfo[];
+  /** worktree 总数 */
+  totalWorktrees: number;
+}

package/src/utils/git.ts

@@ -263,6 +263,22 @@ export function getCommitCountAhead(branchName: string, cwd?: string): number {
   return parseInt(output, 10) || 0;
 }
 
+/**
+ * 获取目标分支落后于当前分支的提交数
+ * 即当前分支有多少提交是目标分支没有的
+ * @param {string} branchName - 目标分支名
+ * @param {string} [cwd] - 工作目录
+ * @returns {number} 落后的提交数
+ */
+export function getCommitCountBehind(branchName: string, cwd?: string): number {
+  try {
+    const output = execCommand(`git rev-list --count ${branchName}..HEAD`, { cwd });
+    return parseInt(output, 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * 解析 git diff --shortstat 输出，提取新增行数和删除行数
  * @param {string} output - shortstat 输出字符串

package/src/utils/index.ts

@@ -27,6 +27,7 @@ export {
   gitWorktreePrune,
   hasLocalCommits,
   getCommitCountAhead,
+  getCommitCountBehind,
   getDiffStat,
   gitDiffCachedBinary,
   gitApplyCachedFromStdin,
@@ -52,6 +53,6 @@ export { printSuccess, printError, printWarning, printInfo, printSeparator, prin
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude } from './claude.js';
-export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.js';
+export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, getProjectSnapshotBranches } from './validate-snapshot.js';
 export { findExactMatch, findFuzzyMatches, promptSelectBranch, resolveTargetWorktree } from './worktree-matcher.js';
 export type { WorktreeResolveMessages } from './worktree-matcher.js';

package/src/utils/validate-snapshot.ts

@@ -98,6 +98,23 @@ export function removeSnapshot(projectName: string, branchName: string): void {
   }
 }
 
+/**
+ * 获取指定项目所有存在 validate 快照的分支名列表
+ * 通过扫描快照目录下的 .tree 文件名提取
+ * @param {string} projectName - 项目名
+ * @returns {string[]} 存在快照的分支名列表
+ */
+export function getProjectSnapshotBranches(projectName: string): string[] {
+  const projectDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
+  if (!existsSync(projectDir)) {
+    return [];
+  }
+  const files = readdirSync(projectDir);
+  return files
+    .filter((f: string) => f.endsWith('.tree'))
+    .map((f: string) => f.replace(/\.tree$/, ''));
+}
+
 /**
  * 删除指定项目的所有 validate 快照
  * @param {string} projectName - 项目名