项目生命周期命令（下） - 和平哥的学习笔记

这是「GSD 全景代码解析」专题的第 8 篇。在上一篇（第 07 篇）中，我们详细剖析了 /gsd-new-project、/gsd-resume 和 /gsd-status 三个项目生命周期命令，理解了 GSD 如何从零初始化一个项目、如何在多 Session 间保持状态连续性，以及如何快速获取项目全景。本篇将继续深入剩余四个项目生命周期命令——/gsd-import、/gsd-map-codebase、/gsd-cleanup 和 /gsd-manager——它们共同构成了 GSD 项目管理的完整闭环。

一、`/gsd-import`：导入现有项目

在真实的开发场景中，我们很少有机会从零开始一个项目。更多的时候，你面对的是一个已经运行数月甚至数年的代码库：它可能有混乱的目录结构、缺失的文档、隐晦的业务逻辑，以及一堆「只有原作者才懂」的祖传代码。/gsd-import 命令的设计目标，就是让这些已有项目也能享受到 GSD 的上下文管理能力。

1.1 导入流程与 `new-project` 的差异

/gsd-new-project 面对的是一张白纸：它创建目录、初始化 .planning/、写入模板文件，一切都在可控的预期之内。而 /gsd-import 面对的是一片丛林：它需要在不破坏现有代码的前提下，为项目「嫁接」上 GSD 的管理层。

两者的核心差异可以用下表概括：

维度	`/gsd-new-project`	`/gsd-import`
目标项目	不存在或为空目录	已存在且有代码
`.planning/` 初始化	全新创建，写入模板	增量创建，探测现有结构
`PROJECT.md` 生成	基于用户输入和模板	基于代码库反推
Git 处理	可选初始化新仓库	保留现有仓库历史
风险评估	低（全新环境）	中（需避免覆盖）

1.2 导入流程详解

/gsd-import 的执行流程分为四个阶段：

flowchart TD
    A[启动 /gsd-import] --> B{检查 .planning/ 是否存在}
    B -->|已存在| C[提示用户选择覆盖/合并/跳过]
    B -->|不存在| D[创建 .planning/ 目录]
    C --> D
    D --> E[扫描项目结构]
    E --> F[检测技术栈]
    F --> G[生成 PROJECT.md]
    G --> H[生成 REQUIREMENTS.md 初稿]
    H --> I[生成 config.json]
    I --> J[生成或更新 .gitignore]
    J --> K[完成导入]

阶段一：安全检查

命令首先检测目标目录是否已存在 .planning/。如果存在，说明该项目可能曾被 GSD 管理过，此时会提示用户选择三种策略：

覆盖（overwrite）：完全重建 .planning/，适合旧版本 GSD 的升级场景
合并（merge）：保留现有文件，仅补充缺失项，适合中断后重新导入
跳过（skip）：直接退出，由用户手动处理

阶段二：项目探测

GSD 会对现有代码库进行一次「轻量级 CT 扫描」：

# 探测的维度示例
1. 目录结构深度和模块划分
2. package.json / Cargo.toml / go.mod / pyproject.toml 等 manifest 文件
3. 入口文件（main, index, app 等）
4. 测试目录和覆盖率配置
5. CI/CD 配置文件
6. 文档文件（README, CHANGELOG, docs/）

探测结果会用于生成更贴近现实的 PROJECT.md 和 REQUIREMENTS.md，而不是套用一个空模板。

阶段三：文件生成

基于探测结果，/gsd-import 会生成以下核心文件：

.planning/
├── PROJECT.md          # 反推的项目描述、技术栈、架构概述
├── REQUIREMENTS.md     # 从现有代码和文档中提取的功能列表
├── config.json         # 导入专用配置，技术栈检测自动填充
└── ROADMAP.md          # 基于现有提交历史和 TODO 注释生成的路线图初稿

注意：ROADMAP.md 在导入场景下只是一个起点。它不会假设项目需要做什么，而是尝试从已有的 Git 提交历史、Issue 模板、TODO/FIXME 注释中推断出「接下来可能要做什么」。

阶段四：适配与收尾

最后，/gsd-import 会检查并更新 .gitignore，确保 .planning/ 不会被意外提交（除非用户显式配置 includePlanningInGit: true）。同时，它会在 PROJECT.md 顶部添加一个「导入标记」：

<!-- GSD-IMPORTED: 2026-04-23 -->
<!-- 本项目由 /gsd-import 导入生成，部分信息基于代码库反推，建议人工复核 -->

1.3 现有代码库的适配建议

导入只是第一步。要让 GSD 真正管理好一个遗留项目，建议你后续执行以下操作：

人工复核 PROJECT.md：自动生成的项目描述可能遗漏关键业务背景
精简 REQUIREMENTS.md：反推的需求列表往往过于冗长，需要按优先级筛选
运行 /gsd-map-codebase：为复杂项目生成代码库映射（详见下一节）
建立第一个 Session：通过 /gsd-session 开始用 GSD 的方式管理后续开发

二、`/gsd-map-codebase`：代码库映射

大型项目有一个共同的问题：即使有了 .planning/ 中的高层文档，AI Agent 在具体编码时仍然缺乏对代码结构的细致理解。/gsd-map-codebase 的作用，就是为 AI 生成一份代码库地形图，让它在修改任何文件之前，都知道「这个文件在哪里、做什么、和谁有关联」。

2.1 代码库分析的目的

人类开发者打开一个陌生项目时，会本能地做几件事：看目录结构、找入口文件、追踪依赖关系、理解模块边界。/gsd-map-codebase 就是为 AI 做同样的事，只不过输出格式是结构化的 Markdown，便于被后续 prompt 引用。

代码库映射解决三个核心问题：

定位问题：「用户说要改登录逻辑，登录相关的代码分散在哪些文件里？」
依赖问题：「修改这个接口会不会破坏下游的消费者？」
上下文窗口问题：「代码库有 10 万行，如何只把最相关的部分塞进 prompt？」

2.2 生成的 `codebase/*.md` 文件

执行 /gsd-map-codebase 后，GSD 会在 .planning/codebase/ 目录下生成一组映射文件：

.planning/
└── codebase/
    ├── OVERVIEW.md           # 代码库总览：目录结构、技术栈、架构模式
    ├── MODULES.md            # 模块清单：每个模块的职责、入口、关键文件
    ├── DEPENDENCIES.md       # 依赖关系图：模块间调用关系、数据流向
    ├── INTERFACES.md         # 接口清单：公共 API、类型定义、协议规范
    └── ENTRYPOINTS.md        # 入口点清单：CLI 命令、HTTP 路由、事件处理器

OVERVIEW.md 示例结构：

# 代码库总览

## 目录结构

src/
├── core/ # 核心业务逻辑
├── adapters/ # 外部系统适配器
├── api/ # HTTP 接口层
├── cli/ # 命令行入口
└── utils/ # 通用工具


## 技术栈

- Runtime: Node.js 20
- Framework: Express.js
- Database: PostgreSQL (via Prisma)
- Testing: Vitest
- Build: esbuild

## 架构模式

采用 Hexagonal Architecture（端口与适配器模式）。
`core/` 不依赖任何外部框架，`adapters/` 负责将外部调用转换为领域操作。

MODULES.md 会进一步细化每个模块：

## core/auth

- **职责**: 用户认证与授权
- **入口**: `src/core/auth/index.ts`
- **关键文件**:
  - `authenticate.ts` - JWT 验证逻辑
  - `authorize.ts` - 权限检查逻辑
  - `types.ts` - 用户、角色类型定义
- **依赖模块**: `core/users`, `adapters/jwt`
- **被依赖模块**: `api/routes`, `cli/commands`

2.3 代码库映射与 `.planning/` 的关系

.planning/ 中的文档和 codebase/*.md 形成了分层上下文结构：

flowchart TB
    subgraph "战略层"
        P[PROJECT.md]
        R[REQUIREMENTS.md]
        RO[ROADMAP.md]
    end

    subgraph "战术层"
        S[sessions/*.md]
    end

    subgraph "地形层"
        C[codebase/*.md]
    end

    P --> S
    R --> S
    RO --> S
    C --> S
    S -.->|反馈更新| C

战略层（PROJECT.md、REQUIREMENTS.md、ROADMAP.md）：回答「我们在做什么、为什么做」
地形层（codebase/*.md）：回答「代码长什么样、在哪里」
战术层（sessions/*.md）：回答「现在具体要改什么、怎么改」

在每次 /gsd-session 执行时，GSD 会根据当前任务智能选择引用哪些映射文件。例如，一个只涉及前端 UI 调整的任务，可能只需要 OVERVIEW.md + MODULES.md 中的 frontend 部分，而不需要加载整个 DEPENDENCIES.md。

2.4 增量更新机制

代码库是动态演化的，映射文件也需要同步更新。/gsd-map-codebase 支持两种模式：

全量映射（默认）：重新扫描整个代码库，适合首次执行或大规模重构后
增量映射（--incremental）：仅扫描自上次映射以来变更的文件和受影响模块，适合日常开发

增量模式通过对比 Git 状态实现：

# 内部逻辑示意
CHANGED_FILES=$(git diff --name-only HEAD~5..HEAD)
gsd-map-codebase --incremental --files "$CHANGED_FILES"

三、`/gsd-cleanup`：清理与维护

任何长期运行的系统都会产生「状态债务」：过期的 Session 记录、废弃的临时文件、失去意义的 TODO 注释。.planning/ 目录也不例外。如果不定期维护，它会从一个「上下文管理中心」退化成「数字垃圾堆」。/gsd-cleanup 就是 GSD 的「保洁员」。

3.1 清理过期状态

/gsd-cleanup 首先扫描 .planning/ 中各文件的状态时间戳，识别以下几类「过期内容」：

过期类型	判断标准	处理方式
废弃 Session	状态为 `abandoned` 且超过 7 天	移动到 `.planning/archive/sessions/`
过时需求	`REQUIREMENTS.md` 中标记为 `deprecated`	归档到 `archive/requirements/` 并添加时间戳
孤儿映射	`codebase/*.md` 引用的文件已不存在	标记为 `[STALE]` 或直接删除
空目录	`.planning/` 中的空子目录	安全删除

清理操作默认是非破坏性的：它不会真正删除任何内容，而是移动到 archive/ 子目录。如果你确定不需要回溯，可以加上 --purge 参数执行彻底清理：

# 预览将要清理的内容（ dry-run 模式）
/gsd-cleanup --dry-run

# 安全归档（默认）
/gsd-cleanup

# 彻底删除（不可恢复）
/gsd-cleanup --purge

3.2 归档已完成的工作

对于已经完成的 Session 和 Phase，/gsd-cleanup 提供了结构化的归档能力：

flowchart LR
    A[已完成 Session] --> B{是否保留详细记录}
    B -->|是| C[归档到 archive/sessions/]
    B -->|否| D[压缩为摘要存入 archive/summaries/]
    C --> E[更新 PROJECT.md 历史记录]
    D --> E

归档后的 Session 文件会被重命名为 YYYY-MM-DD_session-name.md 的格式，并追加归档元数据：

---
archived_at: 2026-04-23
original_path: sessions/phase-02/003-api-refactor.md
status: completed
contributions:
  - 重构了用户认证中间件
  - 添加了 12 个单元测试
  - 更新了 API 文档
---

这种设计让 PROJECT.md 可以保留一份「成就列表」，而无需把完整的 Session 日志一直放在活跃目录中。

3.3 维护 `.planning/` 目录的健康

除了具体的文件操作，/gsd-cleanup 还会输出一份「健康报告」：

$ /gsd-cleanup

GSD Cleanup Report
==================
✓ Sessions: 3 active, 2 archived, 1 abandoned (moved to archive)
✓ Requirements: 12 active, 0 deprecated
⚠ Codebase map: 3 stale references found in MODULES.md
  - src/core/auth/jwt.ts → file moved to src/adapters/jwt/
  - src/utils/helpers.ts → file deleted
  - src/api/routes/legacy.ts → file deleted
✓ Config: valid
✓ Git: .planning/ properly ignored

Recommendations:
1. Run `/gsd-map-codebase --incremental` to refresh stale references.
2. Review archived sessions at `.planning/archive/sessions/`.

健康报告不仅告诉你做了什么，还会建议你下一步该做什么——这是 GSD「主动管理」哲学的体现。

四、`/gsd-manager`：项目管理器

如果说前面的命令都是围绕单个项目的操作，那么 /gsd-manager 则是站在更高维度的指挥中心。它让你能够同时管理多个 GSD 项目，在不同项目间切换，以及执行跨项目的管理操作。

4.1 项目状态总览

执行 /gsd-manager 不带参数时，它会展示一个仪表盘式的总览：

$ /gsd-manager

┌─────────────────────────────────────────────────────────────┐
│ GSD Project Manager                                         │
├──────────────┬──────────┬─────────────┬─────────────────────┤
│ Project      │ Status   │ Last Active │ Next Action         │
├──────────────┼──────────┼─────────────┼─────────────────────┤
│ my-blog      │ active   │ 2h ago      │ /gsd-session write  │
│ api-gateway  │ paused   │ 3d ago      │ /gsd-resume         │
│ data-pipeline│ archived │ 2w ago      │ —                   │
│ mobile-app   │ error    │ 1d ago      │ check config.json   │
└──────────────┴──────────┴─────────────┴─────────────────────┘

Total: 4 projects | Active: 1 | Paused: 1 | Archived: 1 | Error: 1

状态含义：

active：近期有 Session 活动，.planning/ 健康
paused：用户显式暂停，或超过配置天数无活动
archived：已执行过归档，不再出现在默认视图中
error：配置损坏、Git 冲突或 .planning/ 结构异常

4.2 多项目切换

/gsd-manager 提供了快捷的项目切换能力：

# 列出所有项目
/gsd-manager --list

# 切换到指定项目（更新当前工作目录或 Shell 上下文）
/gsd-manager --switch api-gateway

# 快速恢复上一个活跃项目
/gsd-manager --switch -

切换操作不仅仅是 cd 到另一个目录。GSD 会：

保存当前项目的 Session 上下文（如有未完成的思考链）
加载目标项目的 .planning/config.json
根据目标项目的技术栈调整 AI Agent 的行为模式
输出目标项目的最新状态摘要

4.3 管理操作：删除、归档、备份

/gsd-manager 支持对项目执行几种管理操作：

归档项目（archive）

/gsd-manager --archive data-pipeline

归档会将整个 .planning/ 目录压缩为 .planning.tar.gz，连同项目路径记录到 GSD 全局的 ~/.gsd/archived-projects.json 中。原项目的 .planning/ 可以选择保留（默认）或删除（--remove-local）。

删除项目（remove）

/gsd-manager --remove mobile-app

删除是逻辑删除：它从 GSD 的管理列表中移除该项目，但不会删除项目源码。如果你也想清理源码，需要手动执行 rm -rf。

备份项目（backup）

# 备份到默认路径（~/.gsd/backups/）
/gsd-manager --backup my-blog

# 备份到指定路径
/gsd-manager --backup my-blog --to /mnt/nas/gsd-backups/

备份包含两部分：.planning/ 的完整快照，以及项目当前的 Git 提交哈希。这让你可以在任意时间点重建「代码 + 计划」的完整上下文。

恢复项目（restore）

# 从备份恢复
/gsd-manager --restore my-blog --from /mnt/nas/gsd-backups/my-blog-20260423.tar.gz

4.4 全局配置管理

/gsd-manager 还可以查看和修改 GSD 的全局配置：

# 查看全局配置
/gsd-manager --config

# 设置默认编辑器
/gsd-manager --config set editor cursor

# 设置项目自动归档天数
/gsd-manager --config set autoArchiveDays 30

全局配置存储在 ~/.gsd/config.json 中，所有项目共享。项目级配置（.planning/config.json）优先级高于全局配置。

五、项目生命周期命令的完整闭环

现在，让我们把第 07 篇和本篇介绍的所有项目生命周期命令串联起来，看看 GSD 如何覆盖一个项目从诞生到归档的完整生命周期：

flowchart TD
    subgraph "创建阶段"
        N[/gsd-new-project]
        I[/gsd-import]
    end

    subgraph "理解阶段"
        M[/gsd-map-codebase]
    end

    subgraph "执行阶段"
        S[/gsd-session]
        R[/gsd-resume]
    end

    subgraph "监控阶段"
        ST[/gsd-status]
        MN[/gsd-manager]
    end

    subgraph "维护阶段"
        C[/gsd-cleanup]
    end

    subgraph "归档阶段"
        A[/gsd-manager --archive]
    end

    N --> M
    I --> M
    M --> ST
    ST --> S
    S --> R
    R --> ST
    ST --> C
    C --> MN
    MN --> S
    MN --> A
    A -.->|可选恢复| MN

这个闭环体现了 GSD 的核心设计思想：每个项目阶段都有对应的命令，每个命令都有明确的输入和输出，命令之间通过 .planning/ 目录形成状态流转。

创建阶段：new-project 和 import 是入口，决定项目如何进入 GSD 体系
理解阶段：map-codebase 为 AI 建立代码库认知，是高质量编码的前提
执行阶段：session 和 resume 构成日常开发的主循环
监控阶段：status 和 manager 让你始终知道「现在在哪里、全局状况如何」
维护阶段：cleanup 防止技术债务蔓延到计划层
归档阶段：manager --archive 为项目画上句号，同时保留完整上下文以备回溯

六、小结

本篇我们深入解析了四个项目生命周期命令：

/gsd-import：让已有项目平滑接入 GSD，通过项目探测、反推文档和安全检查，避免「从零开始」的偏见
/gsd-map-codebase：为 AI 生成代码库地形图，建立战略层（.planning/）与代码层之间的桥梁
/gsd-cleanup：定期维护 .planning/ 健康，通过归档、清理和健康报告防止状态债务累积
/gsd-manager：多项目指挥中心，提供总览、切换、归档、备份、恢复等跨项目管理能力

这四个命令与第 07 篇介绍的 new-project、resume、status 一起，构成了 GSD 项目生命周期的完整拼图。到此为止，我们已经掌握了 GSD 中所有与项目本身打交道的命令。

但项目的骨架搭好了，还需要血肉的填充。在 GSD 的命令体系中，还有一类更为高频的命令——规划类命令。它们负责把 `REQUIREMENTS.md` 中的需求转化为可执行的 Session，把模糊的「要做什么」变成清晰的「第一步做什么、第二步做什么」。

下一篇预告： 第 09 篇《规划类命令详解》

我们将深入剖析 /gsd-plan-phase、/gsd-plan-task、/gsd-breakdown 等规划类命令的设计与使用，理解 GSD 如何将高层需求逐层拆解为可执行的 Session 序列。敬请期待。

一、/gsd-import：导入现有项目

1.1 导入流程与 new-project 的差异