Compare commits
6 Commits
66341e96a2
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
9ad2c1f1bb | ||
|
|
4f44976214 | ||
|
|
ab48c8532c | ||
|
|
878918ba58 | ||
|
|
38e17d621d | ||
|
|
a8b11912df |
133
.claude
Normal file
133
.claude
Normal file
@@ -0,0 +1,133 @@
|
||||
# New-API 项目配置 - Claude Code
|
||||
|
||||
## 🏗️ 项目架构
|
||||
|
||||
这是一个基于 Go + React 的 AI API 网关项目,用于代理和管理多种 AI 模型服务。
|
||||
|
||||
### 核心组件
|
||||
- **后端**: Go (Gin框架) - API网关和转发逻辑
|
||||
- **前端**: React (Vite) - 管理界面
|
||||
- **数据库**: SQLite/MySQL - 配置和日志存储
|
||||
- **部署**: Docker + Docker Compose
|
||||
|
||||
## 📂 重要目录结构
|
||||
|
||||
```
|
||||
new-api/
|
||||
├── relay/ # 核心转发逻辑
|
||||
│ ├── channel/ # 各厂商适配器
|
||||
│ │ ├── claude/ # Claude 适配器 (重点关注)
|
||||
│ │ ├── openai/ # OpenAI 适配器
|
||||
│ │ └── ... # 其他厂商
|
||||
│ ├── common/ # 通用转发组件
|
||||
│ └── helper/ # 辅助工具
|
||||
├── middleware/ # 中间件 (认证、限流、分发)
|
||||
├── model/ # 数据模型
|
||||
├── controller/ # API控制器
|
||||
├── service/ # 业务服务
|
||||
├── web/ # React前端
|
||||
└── temp/ # 工作文档和脚本
|
||||
└── git-workflow.md # Git工作流程指南
|
||||
```
|
||||
|
||||
## 🎯 当前定制功能
|
||||
|
||||
### 1. Claude 智能请求头管理系统 (已实现)
|
||||
**位置**: `relay/channel/claude/adaptor.go`
|
||||
**功能**:
|
||||
- 支持渠道级透传设置
|
||||
- 智能检测客户端类型 (Claude Code、killcode、其他)
|
||||
- 动态请求头策略 (透传 vs 伪装)
|
||||
- 防止显示 Go-http-client User-Agent
|
||||
|
||||
### 2. 渠道透传增强 (已修复)
|
||||
**问题**: Claude 适配器不支持渠道级透传设置
|
||||
**解决**: 添加 `info.ChannelSetting.PassThroughBodyEnabled` 检查
|
||||
|
||||
## 🔧 开发指南
|
||||
|
||||
### 添加新的 AI 厂商适配器
|
||||
1. 在 `relay/channel/` 创建新目录
|
||||
2. 实现 `Adaptor` 接口的所有方法
|
||||
3. 在 `relay/relay_adaptor.go` 注册适配器
|
||||
4. 添加常量定义到 `constant/` 目录
|
||||
|
||||
### 修改请求头处理逻辑
|
||||
**关键文件**: `relay/channel/claude/adaptor.go:SetupRequestHeader()`
|
||||
**注意事项**:
|
||||
- 保持与其他适配器的一致性
|
||||
- 考虑全局透传和渠道透传两种模式
|
||||
- 确保 User-Agent 不被 Go HTTP 客户端覆盖
|
||||
|
||||
### 前端界面修改
|
||||
**位置**: `web/src/components/table/channels/modals/EditChannelModal.jsx`
|
||||
**渠道设置**: `ChannelSettings` 结构体对应前端表单
|
||||
|
||||
## 🚀 Git 工作流程
|
||||
|
||||
详细流程请查看: `temp/git-workflow.md`
|
||||
|
||||
### 分支策略
|
||||
- `main`: 生产稳定版本
|
||||
- `develop`: 日常开发分支
|
||||
- `upstream-sync`: 上游官方同步
|
||||
- `hotfix/*`: 紧急修复分支
|
||||
|
||||
### 远程仓库
|
||||
- `origin`: https://git.586vip.cn/oadmin/new-api.git (私有仓库)
|
||||
- `upstream`: https://github.com/QuantumNous/new-api.git (上游仓库)
|
||||
|
||||
## 🐳 部署方案
|
||||
|
||||
### Docker Compose 部署
|
||||
```bash
|
||||
# 构建并启动服务
|
||||
docker-compose -f docker-compose-custom.yml up --build -d
|
||||
|
||||
# 查看日志
|
||||
docker-compose -f docker-compose-custom.yml logs -f new-api-custom
|
||||
```
|
||||
|
||||
### 环境配置
|
||||
- **端口**: 3099 (外部访问)
|
||||
- **数据目录**: `./data`
|
||||
- **日志目录**: `./logs-custom`
|
||||
- **网络**: `new-api_default`
|
||||
|
||||
## ⚠️ 重要注意事项
|
||||
|
||||
### 代码修改原则
|
||||
1. **不要随意修改 go.mod 版本**: 本地和服务器环境可能不同
|
||||
2. **保持向后兼容**: 修改时考虑现有配置的兼容性
|
||||
3. **完整测试**: 每次修改都要测试多种客户端兼容性
|
||||
4. **文档同步**: 重要修改及时更新此配置文件
|
||||
|
||||
### 常见问题排查
|
||||
1. **透传不生效**: 检查全局设置和渠道设置
|
||||
2. **User-Agent 显示为 Go-http-client**: 检查请求头设置逻辑
|
||||
3. **Docker 构建失败**: 检查 Dockerfile 和依赖版本
|
||||
|
||||
## 📚 参考资料
|
||||
|
||||
- 官方文档: https://github.com/songquanpeng/one-api
|
||||
- API 规范: `docs/api/` 目录
|
||||
- 部署指南: `docs/installation/` 目录
|
||||
|
||||
## 🔍 开发技巧
|
||||
|
||||
### 调试 HTTP 请求
|
||||
```go
|
||||
if common.DebugEnabled {
|
||||
println("Request Headers:", req.Header)
|
||||
println("Request URL:", fullRequestURL)
|
||||
}
|
||||
```
|
||||
|
||||
### 测试客户端兼容性
|
||||
- Claude Code: User-Agent 包含 "claude-cli"
|
||||
- killcode: User-Agent 包含 "B2/JS" 或存在 "X-Stainless" 头部
|
||||
- 其他客户端: 自动伪装成 killcode 格式
|
||||
|
||||
---
|
||||
*配置文件最后更新: 2025-01-26*
|
||||
*对应代码版本: commit 878918ba (恢复原始 Go 版本设置)*
|
||||
@@ -60,16 +60,29 @@ func (a *Adaptor) GetRequestURL(info *relaycommon.RelayInfo) (string, error) {
|
||||
}
|
||||
|
||||
func (a *Adaptor) SetupRequestHeader(c *gin.Context, req *http.Header, info *relaycommon.RelayInfo) error {
|
||||
if model_setting.GetGlobalSettings().PassThroughRequestEnabled {
|
||||
// 穿透模式:直接复制原始请求头,但跳过系统级头信息
|
||||
for key, values := range c.Request.Header {
|
||||
keyLower := strings.ToLower(key)
|
||||
if keyLower == "host" || keyLower == "content-length" || keyLower == "connection" {
|
||||
continue
|
||||
}
|
||||
for _, value := range values {
|
||||
req.Add(key, value)
|
||||
if model_setting.GetGlobalSettings().PassThroughRequestEnabled || info.ChannelSetting.PassThroughBodyEnabled {
|
||||
userAgent := c.Request.Header.Get("User-Agent")
|
||||
|
||||
// 智能请求头策略:检测客户端类型并决定处理方式
|
||||
if isClaudeCode(userAgent) || isKillcode(userAgent) {
|
||||
// Claude Code 和 killcode: 完全透传原始请求头 (除了压缩头)
|
||||
for key, values := range c.Request.Header {
|
||||
keyLower := strings.ToLower(key)
|
||||
if keyLower == "host" || keyLower == "content-length" || keyLower == "connection" || keyLower == "accept-encoding" {
|
||||
continue
|
||||
}
|
||||
for _, value := range values {
|
||||
req.Add(key, value)
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// 其他客户端: 伪装成 killcode 格式以绕过上游限制
|
||||
setupKillcodeHeaders(c, req)
|
||||
}
|
||||
|
||||
// 保险:确保 User-Agent 一定存在,避免显示 Go-http-client/2.0
|
||||
if req.Get("User-Agent") == "" {
|
||||
req.Set("User-Agent", "B2/JS 0.51.0")
|
||||
}
|
||||
} else {
|
||||
// 非穿透模式:使用通用设置
|
||||
@@ -79,7 +92,7 @@ func (a *Adaptor) SetupRequestHeader(c *gin.Context, req *http.Header, info *rel
|
||||
// 无论哪种模式都需要设置正确的API密钥
|
||||
req.Set("x-api-key", info.ApiKey)
|
||||
|
||||
if !model_setting.GetGlobalSettings().PassThroughRequestEnabled {
|
||||
if !model_setting.GetGlobalSettings().PassThroughRequestEnabled && !info.ChannelSetting.PassThroughBodyEnabled {
|
||||
// 非穿透模式才强制设置这些头
|
||||
anthropicVersion := c.Request.Header.Get("anthropic-version")
|
||||
if anthropicVersion == "" {
|
||||
@@ -91,6 +104,52 @@ func (a *Adaptor) SetupRequestHeader(c *gin.Context, req *http.Header, info *rel
|
||||
return nil
|
||||
}
|
||||
|
||||
// isClaudeCode 检测是否为 Claude Code 客户端
|
||||
func isClaudeCode(userAgent string) bool {
|
||||
return strings.Contains(userAgent, "claude-cli")
|
||||
}
|
||||
|
||||
// isKillcode 检测是否为 killcode 客户端
|
||||
func isKillcode(userAgent string) bool {
|
||||
return strings.Contains(userAgent, "B2/JS") || strings.Contains(userAgent, "X-Stainless")
|
||||
}
|
||||
|
||||
// setupKillcodeHeaders 设置 killcode 风格的请求头,用于伪装其他客户端
|
||||
func setupKillcodeHeaders(c *gin.Context, req *http.Header) {
|
||||
// 基础头部
|
||||
req.Set("User-Agent", "B2/JS 0.51.0")
|
||||
req.Set("Connection", "keep-alive")
|
||||
req.Set("Accept", "application/json")
|
||||
// 移除压缩请求头,避免 gzip 解析问题
|
||||
// req.Set("Accept-Encoding", "br, gzip, deflate")
|
||||
req.Set("Content-Type", "application/json")
|
||||
|
||||
// Stainless SDK 特有头部
|
||||
req.Set("X-Stainless-Retry-Count", "0")
|
||||
req.Set("X-Stainless-Timeout", "600")
|
||||
req.Set("X-Stainless-Lang", "js")
|
||||
req.Set("X-Stainless-Package-Version", "0.51.0")
|
||||
req.Set("X-Stainless-OS", "Windows")
|
||||
req.Set("X-Stainless-Arch", "x64")
|
||||
req.Set("X-Stainless-Runtime", "node")
|
||||
req.Set("X-Stainless-Runtime-Version", "v20.19.1")
|
||||
|
||||
// 保留重要的原始头部
|
||||
if anthropicVersion := c.Request.Header.Get("anthropic-version"); anthropicVersion != "" {
|
||||
req.Set("anthropic-version", anthropicVersion)
|
||||
} else {
|
||||
req.Set("anthropic-version", "2023-06-01")
|
||||
}
|
||||
|
||||
if anthropicBeta := c.Request.Header.Get("anthropic-beta"); anthropicBeta != "" {
|
||||
req.Set("anthropic-beta", anthropicBeta)
|
||||
}
|
||||
|
||||
// 其他辅助头部 (移除可能导致问题的头部)
|
||||
req.Set("accept-language", "*")
|
||||
// req.Set("sec-fetch-mode", "cors") // 移除浏览器特有头部
|
||||
}
|
||||
|
||||
func (a *Adaptor) ConvertOpenAIRequest(c *gin.Context, info *relaycommon.RelayInfo, request *dto.GeneralOpenAIRequest) (any, error) {
|
||||
if request == nil {
|
||||
return nil, errors.New("request is nil")
|
||||
|
||||
217
temp/git-workflow.md
Normal file
217
temp/git-workflow.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# New-API Git 工作流程指南
|
||||
|
||||
## 🎯 分支架构
|
||||
|
||||
```
|
||||
main (生产稳定)
|
||||
├── develop (日常开发)
|
||||
├── upstream-sync (上游同步)
|
||||
└── hotfix/* (紧急修复)
|
||||
```
|
||||
|
||||
## 📋 分支职责
|
||||
|
||||
### 🔒 main (生产分支)
|
||||
- **用途**: 生产环境部署
|
||||
- **特点**: 只接受经过完整测试的代码
|
||||
- **保护**: 禁止直接推送,只能通过 PR/MR 合并
|
||||
|
||||
### 🚧 develop (开发分支)
|
||||
- **用途**: 日常自定义功能开发
|
||||
- **特点**: 基于 main 分支,包含所有自定义修改
|
||||
- **流程**: 功能完成后合并回 main
|
||||
|
||||
### 🔄 upstream-sync (同步分支)
|
||||
- **用途**: 跟踪官方 new-api 更新
|
||||
- **特点**: 保持与上游仓库同步,不包含自定义修改
|
||||
- **流程**: 定期同步,选择性合并到 develop
|
||||
|
||||
### 🚨 hotfix/* (修复分支)
|
||||
- **用途**: 生产环境紧急问题修复
|
||||
- **特点**: 基于 main 分支,修复后直接合并回 main 和 develop
|
||||
|
||||
## 🔄 标准工作流程
|
||||
|
||||
### 1. 日常功能开发
|
||||
|
||||
```bash
|
||||
# 1. 确保在最新的 develop 分支
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
|
||||
# 2. 创建功能分支 (可选,小改动可直接在 develop)
|
||||
git checkout -b feature/智能请求头优化
|
||||
|
||||
# 3. 开发和测试
|
||||
# ... 编码 ...
|
||||
git add .
|
||||
git commit -m "feat: 实现新功能"
|
||||
|
||||
# 4. 推送到远程
|
||||
git push origin feature/智能请求头优化
|
||||
|
||||
# 5. 测试通过后合并到 develop
|
||||
git checkout develop
|
||||
git merge feature/智能请求头优化
|
||||
git push origin develop
|
||||
|
||||
# 6. 部署测试无问题后合并到 main
|
||||
git checkout main
|
||||
git merge develop
|
||||
git push origin main
|
||||
|
||||
# 7. 清理功能分支
|
||||
git branch -d feature/智能请求头优化
|
||||
git push origin --delete feature/智能请求头优化
|
||||
```
|
||||
|
||||
### 2. 上游同步更新
|
||||
|
||||
```bash
|
||||
# 1. 切换到同步分支
|
||||
git checkout upstream-sync
|
||||
|
||||
# 2. 拉取上游最新更新
|
||||
git fetch upstream
|
||||
git merge upstream/main
|
||||
|
||||
# 3. 推送同步结果
|
||||
git push origin upstream-sync
|
||||
|
||||
# 4. 检查更新内容,选择性合并到 develop
|
||||
git checkout develop
|
||||
git log upstream-sync --oneline -10 # 查看新提交
|
||||
|
||||
# 5. 选择需要的提交合并 (谨慎操作)
|
||||
git cherry-pick <commit-hash> # 只合并需要的提交
|
||||
|
||||
# 6. 或者创建合并请求进行 code review
|
||||
```
|
||||
|
||||
### 3. 生产环境紧急修复
|
||||
|
||||
```bash
|
||||
# 1. 基于 main 创建修复分支
|
||||
git checkout main
|
||||
git checkout -b hotfix/修复Claude透传问题
|
||||
|
||||
# 2. 修复问题
|
||||
# ... 编码修复 ...
|
||||
git add .
|
||||
git commit -m "hotfix: 修复 Claude 透传问题"
|
||||
|
||||
# 3. 测试修复效果
|
||||
# ... 测试 ...
|
||||
|
||||
# 4. 合并到 main (生产部署)
|
||||
git checkout main
|
||||
git merge hotfix/修复Claude透传问题
|
||||
git push origin main
|
||||
|
||||
# 5. 同步修复到 develop
|
||||
git checkout develop
|
||||
git merge hotfix/修复Claude透传问题
|
||||
git push origin develop
|
||||
|
||||
# 6. 清理修复分支
|
||||
git branch -d hotfix/修复Claude透传问题
|
||||
```
|
||||
|
||||
## 🛡️ 安全检查清单
|
||||
|
||||
### 合并前检查
|
||||
- [ ] 代码编译通过
|
||||
- [ ] Docker 构建成功
|
||||
- [ ] 功能测试完成
|
||||
- [ ] 没有遗留 TODO 或 debug 代码
|
||||
- [ ] 提交信息清晰明确
|
||||
|
||||
### 部署前检查
|
||||
- [ ] 备份当前生产版本
|
||||
- [ ] 数据库迁移脚本准备就绪
|
||||
- [ ] 回滚方案确定
|
||||
- [ ] 监控告警已配置
|
||||
|
||||
## 📁 目录结构说明
|
||||
|
||||
```
|
||||
new-api/
|
||||
├── temp/
|
||||
│ ├── git-workflow.md # 本文档
|
||||
│ ├── deployment-checklist.md # 部署检查清单
|
||||
│ └── troubleshooting.md # 问题排查指南
|
||||
├── .claude # Claude Code 项目配置
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 🚀 自动化建议
|
||||
|
||||
### Git Hooks
|
||||
```bash
|
||||
# pre-commit: 提交前检查
|
||||
#!/bin/sh
|
||||
echo "运行代码格式化..."
|
||||
go fmt ./...
|
||||
|
||||
echo "运行静态检查..."
|
||||
go vet ./...
|
||||
```
|
||||
|
||||
### CI/CD 流程
|
||||
```yaml
|
||||
# GitHub Actions 示例
|
||||
name: CI/CD Pipeline
|
||||
on:
|
||||
push:
|
||||
branches: [ main, develop ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Build and Test
|
||||
run: |
|
||||
go build ./...
|
||||
docker build -t new-api-test .
|
||||
```
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
1. **小步快跑**: 频繁小提交,避免大批量修改
|
||||
2. **描述清晰**: 提交信息使用约定式提交格式
|
||||
3. **测试先行**: 每个功能都要有对应测试
|
||||
4. **文档同步**: 重要修改及时更新文档
|
||||
5. **备份习惯**: 重要操作前先创建备份分支
|
||||
|
||||
## 📞 故障处理
|
||||
|
||||
### 紧急回滚
|
||||
```bash
|
||||
# 1. 快速回滚到上一个稳定版本
|
||||
git checkout main
|
||||
git reset --hard HEAD~1
|
||||
git push --force-with-lease origin main
|
||||
|
||||
# 2. 或回滚到指定版本
|
||||
git reset --hard <stable-commit-hash>
|
||||
git push --force-with-lease origin main
|
||||
```
|
||||
|
||||
### 冲突解决
|
||||
```bash
|
||||
# 1. 查看冲突文件
|
||||
git status
|
||||
|
||||
# 2. 手动解决冲突
|
||||
# 编辑冲突文件,删除 <<<<<<< ======= >>>>>>> 标记
|
||||
|
||||
# 3. 标记冲突已解决
|
||||
git add <resolved-file>
|
||||
git commit
|
||||
```
|
||||
|
||||
---
|
||||
*本文档由 Claude Code 生成,请根据实际情况调整*
|
||||
347
项目管理计划.md
347
项目管理计划.md
@@ -1,347 +0,0 @@
|
||||
# 开源项目定制化管理与自动合并方案
|
||||
|
||||
## 项目概述
|
||||
|
||||
本文档描述了如何管理一个基于开源项目的定制化版本,在保持自定义功能的同时,能够顺利合并官方的持续更新。通过结构化的Git工作流和Claude AI的辅助,实现高效的版本管理。
|
||||
|
||||
## 1. 项目架构设计
|
||||
|
||||
### 1.1 仓库结构
|
||||
```
|
||||
your-project/
|
||||
├── upstream/ # 官方代码镜像(只读)
|
||||
├── custom/ # 自定义代码和配置
|
||||
├── merged/ # 合并后的最终版本
|
||||
├── docs/ # 项目文档
|
||||
├── scripts/ # 自动化脚本
|
||||
└── .gitignore
|
||||
```
|
||||
|
||||
### 1.2 分支策略
|
||||
- `main` - 跟踪官方最新版本
|
||||
- `custom-stable` - 稳定的自定义版本
|
||||
- `custom-dev` - 开发中的自定义功能
|
||||
- `integration` - 合并测试分支
|
||||
|
||||
## 2. 初始化设置
|
||||
|
||||
### 2.1 克隆和远程源配置
|
||||
```bash
|
||||
# 克隆你的自建Git仓库
|
||||
git clone https://your-git-server/your-project.git
|
||||
cd your-project
|
||||
|
||||
# 添加官方源
|
||||
git remote add upstream https://github.com/official/project.git
|
||||
|
||||
# 验证远程源
|
||||
git remote -v
|
||||
# origin https://your-git-server/your-project.git (fetch)
|
||||
# origin https://your-git-server/your-project.git (push)
|
||||
# upstream https://github.com/official/project.git (fetch)
|
||||
# upstream https://github.com/official/project.git (push)
|
||||
```
|
||||
|
||||
### 2.2 创建基础分支
|
||||
```bash
|
||||
# 创建跟踪官方的主分支
|
||||
git checkout -b main
|
||||
git fetch upstream
|
||||
git merge upstream/main
|
||||
git push origin main
|
||||
|
||||
# 创建自定义开发分支
|
||||
git checkout -b custom-dev
|
||||
git push origin custom-dev
|
||||
|
||||
# 创建稳定自定义分支
|
||||
git checkout -b custom-stable
|
||||
git push origin custom-stable
|
||||
```
|
||||
|
||||
## 3. 日常开发流程
|
||||
|
||||
### 3.1 自定义功能开发
|
||||
```bash
|
||||
# 在custom-dev分支开发
|
||||
git checkout custom-dev
|
||||
git pull origin custom-dev
|
||||
|
||||
# 创建功能分支
|
||||
git checkout -b feature/新功能名称
|
||||
|
||||
# 开发完成后
|
||||
git add .
|
||||
git commit -m "feat: 添加新功能 - 详细描述"
|
||||
git push origin feature/新功能名称
|
||||
|
||||
# 合并到custom-dev
|
||||
git checkout custom-dev
|
||||
git merge feature/新功能名称
|
||||
git push origin custom-dev
|
||||
```
|
||||
|
||||
### 3.2 定期同步官方更新
|
||||
```bash
|
||||
# 获取官方最新版本
|
||||
git fetch upstream
|
||||
|
||||
# 更新main分支
|
||||
git checkout main
|
||||
git merge upstream/main
|
||||
git push origin main
|
||||
|
||||
# 检查更新日志
|
||||
git log --oneline main..upstream/main
|
||||
```
|
||||
|
||||
## 4. Claude AI 辅助合并流程
|
||||
|
||||
### 4.1 准备合并信息包
|
||||
创建合并信息收集脚本:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/prepare_merge_info.sh
|
||||
|
||||
echo "=== 官方更新信息 ==="
|
||||
git log --oneline --graph main..upstream/main
|
||||
|
||||
echo -e "\n=== 冲突文件预检 ==="
|
||||
git merge-tree $(git merge-base main upstream/main) main upstream/main | grep -E "^@@|^\+\+\+|^---"
|
||||
|
||||
echo -e "\n=== 自定义修改文件列表 ==="
|
||||
git diff --name-only main custom-stable
|
||||
|
||||
echo -e "\n=== 项目关键配置文件 ==="
|
||||
find . -name "*.config.*" -o -name "package.json" -o -name "*.env*" | head -10
|
||||
```
|
||||
|
||||
### 4.2 Claude AI 合并请求模板
|
||||
|
||||
**合并请求信息格式:**
|
||||
```markdown
|
||||
## 项目背景
|
||||
- 项目名称: [项目名]
|
||||
- 官方仓库: [GitHub链接]
|
||||
- 当前版本: [版本号]
|
||||
- 目标版本: [版本号]
|
||||
|
||||
## 更新内容
|
||||
[粘贴官方更新日志]
|
||||
|
||||
## 自定义修改点
|
||||
- 文件1: [修改内容描述]
|
||||
- 文件2: [修改内容描述]
|
||||
|
||||
## 预期冲突点
|
||||
[运行prepare_merge_info.sh的输出]
|
||||
|
||||
## 合并需求
|
||||
请帮我分析潜在冲突并给出合并策略。需要保持以下自定义功能:
|
||||
1. [功能1]
|
||||
2. [功能2]
|
||||
```
|
||||
|
||||
### 4.3 Claude 辅助合并步骤
|
||||
|
||||
1. **分析阶段**
|
||||
```
|
||||
请Claude分析:
|
||||
- 官方改动影响范围
|
||||
- 与自定义代码的冲突点
|
||||
- 推荐的合并策略
|
||||
- 风险评估
|
||||
```
|
||||
|
||||
2. **执行阶段**
|
||||
```bash
|
||||
# 创建合并分支
|
||||
git checkout -b merge/v版本号-$(date +%Y%m%d)
|
||||
|
||||
# 开始合并
|
||||
git merge upstream/main
|
||||
```
|
||||
|
||||
3. **冲突解决**
|
||||
- 将冲突文件内容发送给Claude
|
||||
- 获取解决方案
|
||||
- 应用建议的解决方案
|
||||
|
||||
## 5. 冲突解决标准流程
|
||||
|
||||
### 5.1 冲突分类处理
|
||||
|
||||
**配置文件冲突:**
|
||||
```bash
|
||||
# 优先保持自定义配置,选择性合并官方新增项
|
||||
# 使用工具辅助:
|
||||
git checkout --ours config/app.json # 保持我们的版本
|
||||
git checkout --theirs config/new.json # 使用官方新文件
|
||||
```
|
||||
|
||||
**核心代码冲突:**
|
||||
```bash
|
||||
# 手动合并,保持功能完整性
|
||||
git status # 查看冲突文件
|
||||
# 编辑每个冲突文件,保持自定义功能同时采纳官方改进
|
||||
```
|
||||
|
||||
**依赖和构建文件:**
|
||||
```bash
|
||||
# 通常采用官方版本,后续调整
|
||||
git checkout --theirs package.json
|
||||
npm install # 重新安装依赖
|
||||
```
|
||||
|
||||
### 5.2 合并后验证清单
|
||||
|
||||
- [ ] 代码编译无错误
|
||||
- [ ] 核心功能正常运行
|
||||
- [ ] 自定义功能保持完整
|
||||
- [ ] 单元测试通过
|
||||
- [ ] 集成测试验证
|
||||
- [ ] 性能基准对比
|
||||
|
||||
## 6. 自动化脚本工具
|
||||
|
||||
### 6.1 一键更新脚本
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/auto_update.sh
|
||||
|
||||
set -e
|
||||
|
||||
echo "🚀 开始官方版本更新流程..."
|
||||
|
||||
# 获取最新版本
|
||||
git fetch upstream
|
||||
LATEST_TAG=$(git describe --tags --abbrev=0 upstream/main)
|
||||
|
||||
echo "📦 发现新版本: $LATEST_TAG"
|
||||
|
||||
# 创建合并分支
|
||||
MERGE_BRANCH="merge/$LATEST_TAG-$(date +%Y%m%d)"
|
||||
git checkout -b $MERGE_BRANCH
|
||||
|
||||
# 生成合并信息
|
||||
./scripts/prepare_merge_info.sh > merge_info_$LATEST_TAG.txt
|
||||
|
||||
echo "📄 合并信息已生成: merge_info_$LATEST_TAG.txt"
|
||||
echo "📋 请将此文件内容发送给Claude AI获取合并建议"
|
||||
echo "⏸️ 执行 'git merge upstream/main' 开始合并"
|
||||
```
|
||||
|
||||
### 6.2 冲突报告生成器
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/conflict_reporter.sh
|
||||
|
||||
if git diff --check; then
|
||||
echo "✅ 没有发现冲突"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "⚠️ 发现合并冲突,生成报告..."
|
||||
|
||||
git status --porcelain | grep "^UU" | while read -r line; do
|
||||
file=$(echo $line | cut -d' ' -f2)
|
||||
echo "文件: $file"
|
||||
echo "冲突内容:"
|
||||
git show :1:$file > /tmp/base_$file 2>/dev/null || true
|
||||
git show :2:$file > /tmp/ours_$file 2>/dev/null || true
|
||||
git show :3:$file > /tmp/theirs_$file 2>/dev/null || true
|
||||
|
||||
echo "我们的版本 vs 官方版本差异:"
|
||||
diff -u /tmp/ours_$file /tmp/theirs_$file || true
|
||||
echo "---"
|
||||
done
|
||||
```
|
||||
|
||||
## 7. 最佳实践建议
|
||||
|
||||
### 7.1 代码组织
|
||||
- **模块化设计**: 将自定义功能封装成独立模块
|
||||
- **配置外置**: 通过配置文件控制行为差异
|
||||
- **接口抽象**: 通过接口层减少对核心代码的直接修改
|
||||
- **插件机制**: 利用官方提供的扩展点
|
||||
|
||||
### 7.2 文档维护
|
||||
- 记录每次自定义修改的原因和方法
|
||||
- 维护自定义功能清单
|
||||
- 记录与官方版本的兼容性信息
|
||||
- 保持合并历史的详细注释
|
||||
|
||||
### 7.3 测试策略
|
||||
- 为自定义功能编写独立测试
|
||||
- 保持与官方测试的兼容性
|
||||
- 建立回归测试防止功能退化
|
||||
- 设置持续集成验证合并结果
|
||||
|
||||
## 8. 应急预案
|
||||
|
||||
### 8.1 合并失败回滚
|
||||
```bash
|
||||
# 放弃当前合并
|
||||
git merge --abort
|
||||
|
||||
# 回到稳定版本
|
||||
git checkout custom-stable
|
||||
|
||||
# 创建热修复分支
|
||||
git checkout -b hotfix/emergency-fix
|
||||
```
|
||||
|
||||
### 8.2 紧急补丁
|
||||
```bash
|
||||
# 仅合并安全补丁
|
||||
git cherry-pick <安全补丁commit-hash>
|
||||
|
||||
# 跳过有问题的更新
|
||||
git merge upstream/main -X ours # 遇到冲突时优先使用我们的版本
|
||||
```
|
||||
|
||||
## 9. 长期维护策略
|
||||
|
||||
### 9.1 版本发布节奏
|
||||
- **跟随官方稳定版**: 不追求最新,等待稳定版本
|
||||
- **定期批量更新**: 每月或每季度统一更新
|
||||
- **安全补丁优先**: 安全相关更新立即处理
|
||||
|
||||
### 9.2 技术债务管理
|
||||
- 定期评估自定义修改的必要性
|
||||
- 寻找机会将功能贡献回官方项目
|
||||
- 重构过时的自定义实现
|
||||
- 监控官方新特性,替换自定义实现
|
||||
|
||||
## 10. Claude AI 交互优化
|
||||
|
||||
### 10.1 信息准备清单
|
||||
向Claude寻求帮助时,请准备:
|
||||
- [ ] 项目基本信息(语言、框架、版本)
|
||||
- [ ] 官方更新内容摘要
|
||||
- [ ] 自定义修改点列表
|
||||
- [ ] 冲突文件完整内容
|
||||
- [ ] 预期功能要求
|
||||
- [ ] 时间和风险约束
|
||||
|
||||
### 10.2 有效提问模式
|
||||
```
|
||||
背景:我正在维护一个基于[项目名]的定制版本
|
||||
情况:官方从v1.0更新到v1.1,主要变更是[具体内容]
|
||||
问题:在文件[文件名]出现冲突,我的修改是[具体修改]
|
||||
需求:请帮我分析最佳合并策略,确保[关键功能]不受影响
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
通过这套完整的项目管理方案,您可以:
|
||||
- 🎯 结构化管理自定义版本
|
||||
- 🤖 借助Claude AI智能处理复杂合并
|
||||
- 🔄 建立可重复的更新流程
|
||||
- 📊 实现风险可控的版本维护
|
||||
- 🚀 保持与开源社区的同步发展
|
||||
|
||||
记住:好的工具链是成功的一半,但理解业务需求和技术债务管理同样重要。
|
||||
Reference in New Issue
Block a user