go-module-renamer

name	go-module-renamer
description	Go 模块重命名自动化工具。用于新 git clone 的项目进行 Go 模块重命名，支持全量/部分重命名智能识别，文本替换优先策略，完善的验证和回滚机制。 Use when this capability is needed.
metadata	{"author":"fsyyft-go"}

Go 模块重命名器

概述

自动化 Go 项目模块重命名，支持智能识别重命名类型（全量/部分），使用文本替换策略快速更新模块引用，提供浅层和深层双重验证，确保重命名安全可靠。

使用场景

• 新克隆的项目重命名 - Git clone 后快速重命名模块到自己的仓库
• 项目迁移 - 将项目从一个组织迁移到另一个组织
• 项目重命名 - 仅更改项目名称而保持组织结构
• 模块重构 - 重组项目结构并更新模块路径

快速开始

一键重命名（推荐）

对于全新克隆的项目：

# 1. 检测当前模块名
.claude/skills/go-module-renamer/scripts/detect_module.sh

# 2. 分析重命名类型
python3 .claude/skills/go-module-renamer/scripts/analyze_rename_type.py \
  <旧模块名> <新模块名>

# 3. 执行重命名
python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  <旧模块名> <新模块名>

# 4. 浅层验证
.claude/skills/go-module-renamer/scripts/validate_quick.sh

# 5. 深层验证
python3 .claude/skills/go-module-renamer/scripts/validate_deep.py <旧模块名>

试运行模式

在实际重命名前先查看影响范围：

python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  <旧模块名> <新模块名> --dry-run

工作流程

场景 1：全量重命名

适用情况：域名或用户名变更

github.com/fsyyft-go/kratos-layout → github.com/new-org/new-project

工作流程：

开始
  ↓
1. 检测当前模块名
   [detect_module.sh]
   输出：模块名结构（域名、用户名、项目名）
  ↓
2. 分析重命名类型
   [analyze_rename_type.py]
   判断：全量重命名（前两部分不同）
  ↓
3. 执行重命名
   [perform_rename.py]
   ├─ 创建备份（.backup/）
   ├─ 替换完整模块路径
   │  ├─ go.mod 模块声明
   │  ├─ .go 文件导入路径
   │  ├─ .proto 文件 go_package
   │  └─ 文档中的代码示例
   ├─ 替换项目名
   │  ├─ Makefile 变量
   │  ├─ 配置文件
   │  └─ 文档标题
   └─ 清理模板注释
  ↓
4. 浅层验证
   [validate_quick.sh]
   ├─ go fmt
   ├─ go mod tidy
   ├─ make lint
   └─ make build
  ↓
5. 深层验证
   [validate_deep.py]
   ├─ 搜索代码文件残留
   ├─ 检查配置文件
   └─ 审查文档引用
  ↓
完成

---

场景 2：部分重命名

适用情况：仅项目名变更

github.com/fsyyft-go/kratos-layout → github.com/fsyyft-go/new-project

工作流程：

开始
  ↓
1. 检测当前模块名
   [detect_module.sh]
  ↓
2. 分析重命名类型
   [analyze_rename_type.py]
   判断：部分重命名（仅最后部分不同）
  ↓
3. 执行重命名
   [perform_rename.py]
   ├─ 创建备份（.backup/）
   └─ 替换项目名
      ├─ Makefile 变量
      ├─ Docker 镜像名
      ├─ 配置文件
      └─ 文档标题
  ↓
4. 验证（同上）
  ↓
完成

---

脚本说明

detect_module.sh - 模块名检测器

功能：

• 从 go.mod 读取当前模块名
• 解析模块名结构（域名、用户名、项目名）
• 输出 JSON 格式信息

用法：

.claude/skills/go-module-renamer/scripts/detect_module.sh

输出示例：

{
  "full_path": "github.com/fsyyft-go/kratos-layout",
  "domain": "github.com",
  "username": "fsyyft-go",
  "project": "kratos-layout"
}

返回值：

• 0 - 成功
• 1 - go.mod 不存在
• 2 - 无法解析模块名

自动化程度：100% 脚本自动化，无需大模型介入

---

analyze_rename_type.py - 重命名类型分析器

功能：

• 比较新旧模块名
• 判断全量或部分重命名
• 生成替换规则列表

用法：

python3 .claude/skills/go-module-renamer/scripts/analyze_rename_type.py \
  <旧模块名> <新模块名>

示例：

python3 .claude/skills/go-module-renamer/scripts/analyze_rename_type.py \
  github.com/fsyyft-go/kratos-layout \
  github.com/new-org/new-project

输出示例：

{
  "type": "full",
  "old_module": "github.com/fsyyft-go/kratos-layout",
  "new_module": "github.com/new-org/new-project",
  "old_project": "kratos-layout",
  "new_project": "new-project",
  "replacements": {
    "full_replace": [...],
    "partial_replace": [...]
  }
}

自动化程度：100% 脚本自动化，无需大模型介入

---

perform_rename.py - 重命名执行器（核心）

功能：

• 创建备份
• 执行文本替换（根据类型选择策略）
• 清理模板注释
• 生成操作报告

用法：

# 基本用法
python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  <旧模块名> <新模块名>

# 指定重命名类型
python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  <旧模块名> <新模块名> --type=full

# 试运行模式（不实际修改文件）
python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  <旧模块名> <新模块名> --dry-run

参数说明：

• old_module - 旧模块名（必需）
• new_module - 新模块名（必需）
• --type - 重命名类型：auto（默认）、full、partial
• --dry-run - 试运行模式，不实际修改文件

Python 环境管理：

• 自动检测 .venv 虚拟环境
• 如果虚拟环境存在，优先使用
• 如果不存在，提示使用 python-venv-manager 创建

自动化程度：

• 脚本自动化：90%
• 大模型介入：10%（处理特殊情况、环境管理）

---

validate_quick.sh - 浅层验证脚本

功能：

• 执行快速验证命令
• 收集验证结果
• 返回通过/失败状态

用法：

# 完整验证
.claude/skills/go-module-renamer/scripts/validate_quick.sh

# 跳过 lint 检查
.claude/skills/go-module-renamer/scripts/validate_quick.sh --skip-lint

# 跳过编译验证
.claude/skills/go-module-renamer/scripts/validate_quick.sh --skip-build

验证命令序列：

1. go fmt ./... - 代码格式化
2. go mod tidy - 依赖管理
3. make lint - Lint 检查（可选）
4. make build - 编译验证（可选）

输出示例：

======================================
步骤 1: 代码格式化 (go fmt)
======================================
✓ 通过: 代码格式化完成

======================================
步骤 2: 依赖管理 (go mod tidy)
======================================
✓ 通过: 依赖管理完成

...
======================================
验证总结
======================================
总步骤数: 4
通过: 4
失败: 0

✅ 浅层验证全部通过！

返回值：

• 0 - 全部通过
• 1 - 有失败

自动化程度：100% 脚本自动化，无需大模型介入

---

validate_deep.py - 深层验证脚本

功能：

• 搜索所有包含旧模块名的文件
• 分类文件类型（代码/配置/文档）
• 对不同类型采取不同策略

用法：

# 基本用法
python3 .claude/skills/go-module-renamer/scripts/validate_deep.py <旧模块名>

# 指定旧项目名
python3 .claude/skills/go-module-renamer/scripts/validate_deep.py \
  <旧模块名> --old-project=<旧项目名>

分类规则：

文件类型	残留引用处理	理由
.go、.proto	❌ 报告错误	代码文件不应该有残留
Makefile、config.yaml	⚠️ 警告	可能需要手动检查
README.md	✅ 自动替换	明显的文档引用
.github/*.md	✅ 自动替换	GitHub 文档
注释、文档	ℹ️ 信息提示	可能是历史说明

输出示例：

🔍 深层验证：搜索残留引用
   搜索模式：
   - github.com/fsyyft-go/kratos-layout
   - kratos-layout

📂 搜索代码文件...
📂 搜索配置文件...
📂 搜索文档文件...

==================================================
📊 深层验证结果
==================================================

❌ 代码文件中的残留（2 个文件）：
   - internal/server/server.go
     行 10: import "github.com/fsyyft-go/kratos-layout/internal/conf"
   - api/helloworld/v1/greeter.proto
     行 5: option go_package = "github.com/fsyyft-go/kratos-layout/api"

⚠️  配置文件中的残留（1 个文件）：
   - Makefile
     行 5: IMAGE_NAME := fsyyft/kratos-layout

ℹ️  文档文件中的残留（3 个文件）：
   - README.md
   - docs/api.md
   - .github/CONTRIBUTING.md

返回值：

• 0 - 无残留或仅有文档残留
• 1 - 代码文件中有残留
• 2 - 配置文件中有残留

自动化程度：

• 脚本自动化：70%
• 大模型介入：30%（分析文档上下文）

---

验证策略

浅层验证（快速验证）

目标：快速发现明显的编译和语法错误

时间：1-3 分钟

验证内容：

• ✅ 代码格式化
• ✅ 依赖管理
• ✅ Lint 检查（可选）
• ✅ 编译验证（可选）

通过标准：

• 所有命令返回码为 0
• 无编译错误
• 无关键 Lint 错误

---

深层验证（全面检查）

目标：发现所有残留的旧模块名引用

时间：3-5 分钟

验证内容：

• ✅ 代码文件无残留
• ⚠️ 配置文件检查
• ℹ️ 文档文件审查

通过标准：

• 代码文件中无残留引用
• 配置文件残留已审查
• 文档残留已记录

---

故障排除

常见问题

问题 1：编译失败

症状：

cannot find package "github.com/old/module/path"

解决方案：

1. 检查导入路径是否正确
2. 运行 go mod tidy
3. 检查 go.mod 中的模块名

---

问题 2：残留引用未清理

症状： 深层验证发现代码文件中有残留引用

解决方案：

1. 使用 grep 定位所有残留
2. 手动修复或使用批量替换
3. 重新运行验证

示例：

grep -rn "旧模块名" --include="*.go" .
sed -i '' 's|旧模块名|新模块名|g' file.go

---

问题 3：验证失败，是否回滚？

判断依据：

• 应该回滚：编译失败、大量测试失败、无法快速修复
• 可以继续：仅文档残留、配置文件警告

回滚方法：

# 自动回滚（使用备份）
cp -r .backup/* .

# 或使用 Git
git checkout .

---

问题 4：Python 环境问题

症状：

ModuleNotFoundError: No module named 'yaml'

解决方案：

1. 检查虚拟环境是否存在
2. 安装依赖：pip install pyyaml
3. 或使用 python-venv-manager 创建虚拟环境

---

回滚操作

触发条件：

• 编译失败且无法快速修复
• 大量测试失败
• 关键功能异常

回滚步骤：

1. 停止当前操作
2. 恢复备份文件
3. 验证恢复结果
4. 分析失败原因
5. 修复问题后重新尝试

---

最佳实践

重命名前准备

1. 备份代码

   • 创建 Git 分支
   • 推送到远程仓库

2. 通知团队

   • 告知团队成员重命名计划
   • 协调重命名时间

3. 准备环境

   • 确保依赖工具已安装
   • 检查 Python 虚拟环境

4. 规划验证

   • 准备测试用例
   • 确定验证标准

---

重命名过程

1. 使用试运行模式

   • 先执行 --dry-run 查看影响范围
   • 审查替换规则是否正确

2. 创建备份

   • 脚本会自动创建 .backup 目录
   • 保留备份直到验证完成

3. 分步执行

   • 按顺序执行每个步骤
   • 每步执行后检查结果

4. 验证结果

   • 先运行浅层验证
   • 再运行深层验证
   • 最后运行功能测试

---

重命名后处理

1. 提交更改

   • 创建清晰的 commit message
   • 推送到远程仓库

2. 更新文档

   • 更新 README.md
   • 更新 API 文档
   • 更新贡献指南

3. 通知相关人员

   • 通知团队成员
   • 更新相关系统
   • 更新 CI/CD 配置

---

自动化程度

总体自动化程度：80% 脚本 + 20% 大模型辅助

大模型介入点

介入点	触发条件	大模型职责	介入程度
Python 环境检测	脚本启动时	检查虚拟环境，决定是否创建	10%
类型分析确认	分析完成	显示结果，让用户确认	5%
未知文件类型	遇到新类型文件	判断如何处理	5%
特殊情况处理	发现复杂情况	提供处理建议	10%
文档引用分析	深层验证	判断是否需要更新	20%
验证失败诊断	lint/build 失败	分析错误，提供解决方案	30%
用户指导	用户询问	解释操作，提供后续步骤	按需

---

资源

scripts/

包含 5 个可执行脚本：

1. detect_module.sh - 模块名检测器（约 70 行）
2. analyze_rename_type.py - 重命名类型分析器（约 250 行）
3. perform_rename.py - 重命名执行器（约 450 行）
4. validate_quick.sh - 浅层验证脚本（约 180 行）
5. validate_deep.py - 深层验证脚本（约 350 行）

所有脚本：

• 使用 Python 3.8+ 和 Bash
• 包含完整的中文注释
• 提供详细的错误处理
• 跨平台支持（Windows/macOS/Linux）
• 可以独立执行或在大模型指导下执行

---

references/

包含详细的参考资料：

1. file_patterns.md

   • Go 项目标准文件类型
   • 每种文件类型的替换模式
   • 全量 vs 部分替换的判断规则
   • 特殊文件的处理方法

2. validation_rules.md

   • 验证命令的执行顺序
   • 每个命令的预期结果
   • 常见错误和解决方案
   • 回滚触发条件

---

assets/

包含报告模板和示例文件（待补充）。

---

示例用法

示例 1：新克隆项目快速启动

# 克隆项目
git clone https://github.com/fsyyft-go/kratos-layout.git my-project
cd my-project

# 1. 检测当前模块名
.claude/skills/go-module-renamer/scripts/detect_module.sh
# 输出：github.com/fsyyft-go/kratos-layout

# 2. 试运行查看影响
python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  github.com/fsyyft-go/kratos-layout \
  github.com/myorg/my-project \
  --dry-run

# 3. 执行重命名
python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  github.com/fsyyft-go/kratos-layout \
  github.com/myorg/my-project

# 4. 验证
.claude/skills/go-module-renamer/scripts/validate_quick.sh
python3 .claude/skills/go-module-renamer/scripts/validate_deep.py \
  github.com/fsyyft-go/kratos-layout

# 5. 提交
git add .
git commit -m "feat: 重命名模块为 github.com/myorg/my-project"

---

示例 2：检测到残留引用

当 validate_deep.py 发现代码文件中有残留时：

$ python3 validate_deep.py github.com/fsyyft-go/kratos-layout

❌ 代码文件中的残留（1 个文件）：
   - internal/server/server.go
     行 15: import "github.com/fsyyft-go/kratos-layout/internal/conf"

⚠️  发现代码文件中的残留引用，这可能导致编译或运行时错误。
   建议：手动检查并修复这些文件

修复方法：

# 方法 1：使用 sed
sed -i '' 's|github.com/fsyyft-go/kratos-layout|github.com/myorg/my-project|g' \
  internal/server/server.go

# 方法 2：使用编辑器批量替换
# 在 VSCode 中：Cmd+Shift+H，查找旧模块名，替换为新模块名

# 方法 3：重新运行 perform_rename.py
python3 .claude/skills/go-module-renamer/scripts/perform_rename.py \
  github.com/fsyyft-go/kratos-layout \
  github.com/myorg/my-project

---

示例 3：浅层验证失败

当 validate_quick.sh 执行失败时：

$ validate_quick.sh

======================================
步骤 3: Lint 检查 (make lint)
======================================
✗ 失败: Lint 检查失败

level=error msg="internal/server/server.go:15:2: import shadowing: \
  conf \"github.com/myorg/my-project/internal/conf\""

大模型分析：

• 识别错误类型：import shadowing（包名冲突）
• 提供解决方案：使用别名避免冲突
• 生成修复代码：

// 修复前
import "github.com/myorg/my-project/internal/conf"

// 修复后（使用别名）
import serverconf "github.com/myorg/my-project/internal/conf"

---

技术规格

• Go 版本：1.16+（Go modules）
• Python 版本：3.8+（脚本执行）
• 虚拟环境：.venv（推荐使用 python-venv-manager）
• 跨平台：Windows, macOS, Linux
• 备份位置：.backup/ 在项目根目录
• 替换策略：文本替换优先（更快，无需工具链）

---

注意事项

1. Git 远程仓库

   • 重命名前更新 Git 远程仓库 URL
   • 确保新模块路径在远程仓库中存在

2. 依赖包

   • 如果有私有依赖包，更新 import 路径
   • 检查 go.work 文件（如果使用 Go workspaces）

3. CI/CD

   • 更新 GitHub Actions / GitLab CI 配置
   • 更新 Docker 镜像名称

4. 文档

   • 更新 README.md 中的克隆命令
   • 更新 API 文档中的包路径示例
   • 更新贡献指南

5. 团队协作

   • 重命名前通知团队成员
   • 协调重命名时间
   • 提供迁移指南

---

相关资源

• Go Modules Reference
• Protocol Buffers Style Guide
• Kratos Framework Documentation
• Go Module Mirror and Checksum Database

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.