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% 脚本自动化，无需大模型介入

analyzerenametype.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

验证命令序列：

go fmt ./... - 代码格式化
go mod tidy - 依赖管理
make lint - Lint 检查（可选）
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"

解决方案：

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

问题 2：残留引用未清理

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

解决方案：

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

示例：

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

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

判断依据：

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

回滚方法：

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

# 或使用 Git
git checkout .

问题 4：Python 环境问题

症状：

ModuleNotFoundError: No module named 'yaml'

解决方案：

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

回滚操作

触发条件：

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

回滚步骤：

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

最佳实践

重命名前准备

备份代码

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

通知团队

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

准备环境

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

规划验证

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

重命名过程

使用试运行模式

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

创建备份

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

分步执行

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

验证结果

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

重命名后处理

提交更改

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

更新文档

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

通知相关人员

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

自动化程度

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

大模型介入点

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

资源

scripts/

包含 5 个可执行脚本：

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

所有脚本：

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

references/

包含详细的参考资料：

file_patterns.md

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

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/ 在项目根目录
替换策略：文本替换优先（更快，无需工具链）

注意事项

Git 远程仓库

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

依赖包

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

CI/CD

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

文档

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

团队协作

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

go-module-renamer

Installation

Also in this package

Agent compatibility

Skill metadata

Package contents

History

SKILL.md

Go 模块重命名器

概述

使用场景

快速开始

一键重命名（推荐）

试运行模式

工作流程

场景 1：全量重命名

场景 2：部分重命名

脚本说明

detect_module.sh - 模块名检测器

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

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

validate_quick.sh - 浅层验证脚本

validate_deep.py - 深层验证脚本

验证策略

浅层验证（快速验证）

深层验证（全面检查）

故障排除

常见问题

问题 1：编译失败

问题 2：残留引用未清理

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

问题 4：Python 环境问题

回滚操作

最佳实践

重命名前准备

重命名过程

重命名后处理

自动化程度

大模型介入点

资源

scripts/

references/

assets/

示例用法

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

示例 2：检测到残留引用

示例 3：浅层验证失败

技术规格

注意事项

相关资源