John Qiu
712063071c
skills/ → skills-dev(9), skills-req(10), skills-ops(4), skills-integration(8), skills-biz(4), skills-workflow(7) generate-marketplace.py 改为自动扫描所有 skills-* 目录。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
197 lines
5.2 KiB
Markdown
197 lines
5.2 KiB
Markdown
# Git 提交指南
|
||
|
||
## 📋 提交清单
|
||
|
||
### ✅ 应该提交的文件
|
||
|
||
```bash
|
||
git add .
|
||
git status # 确认以下文件已staged
|
||
|
||
应包含：
|
||
- .claude-plugin/plugin.json # 插件配置
|
||
- skills/SKILL.md # 技能文档
|
||
- scripts/voice_converter.py # 核心工具
|
||
- scripts/voice_converter_v2.py # 备选方案
|
||
- scripts/voice_converter_sdk.py # 备选方案
|
||
- scripts/check_credentials.py # 诊断工具
|
||
- scripts/test_services.py # 服务测试
|
||
- scripts/test_v3_debug.py # V3调试工具
|
||
- scripts/setup_env.sh # 示例脚本（占位符版本）
|
||
- scripts/setup_env.local.sh.example # 本地配置模板
|
||
- README.md # 用户文档
|
||
- STATUS.md # 开发状态
|
||
- .gitignore # Git忽略规则
|
||
- GIT_GUIDE.md # 本文件
|
||
```
|
||
|
||
### ❌ 被自动忽略的文件（勿手动提交）
|
||
|
||
```bash
|
||
# .gitignore 已配置，以下文件不会被提交：
|
||
- *.mp3, *.wav, *.pcm # 音频文件
|
||
- .DS_Store # 系统文件
|
||
- setup_env.local.sh # 本地凭证文件
|
||
- .env, .env.local # 环境变量文件
|
||
- __pycache__/ # Python缓存
|
||
- .vscode/, .idea/ # IDE配置
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 凭证管理 (重要！)
|
||
|
||
### 本地使用流程
|
||
|
||
```bash
|
||
# 1. 基于模板创建本地配置文件
|
||
cd scripts
|
||
cp setup_env.local.sh.example setup_env.local.sh
|
||
|
||
# 2. 编辑本地文件，填入您的真实凭证
|
||
nano setup_env.local.sh # 或用您喜欢的编辑器
|
||
|
||
# 3. 本地使用时，source 本地文件
|
||
source setup_env.local.sh
|
||
|
||
# 4. 验证（注意：setup_env.local.sh 在 .gitignore 中）
|
||
git status # 应该看不到 setup_env.local.sh
|
||
```
|
||
|
||
### 关键安全要点
|
||
|
||
✅ **做这些**:
|
||
- 凭证存储在本地的 `.local` 文件中
|
||
- 凭证存储在环境变量中（不硬编码）
|
||
- 公开文件只包含占位符 `your_app_id`, `your_access_token`
|
||
- 定期检查 git status 确保没有凭证被暴露
|
||
|
||
❌ **不要做这些**:
|
||
- 不要把真实凭证提交到 Git
|
||
- 不要硬编码凭证在 Python 文件中
|
||
- 不要修改 .gitignore，让敏感文件被跟踪
|
||
- 不要分享包含凭证的 shell 脚本
|
||
|
||
---
|
||
|
||
## 📝 提交步骤
|
||
|
||
```bash
|
||
# 1. 确保您创建了本地配置文件
|
||
cd /Users/junhuang/coolbuy/claude-marketplace/plugins/doubao-voice-plugin/scripts
|
||
cp setup_env.local.sh.example setup_env.local.sh
|
||
# 编辑 setup_env.local.sh，填入您的凭证
|
||
|
||
# 2. 检查状态
|
||
cd ..
|
||
git status
|
||
|
||
# 3. 提交所有应提交的文件
|
||
git add .
|
||
|
||
# 4. 验证没有凭证泄露
|
||
git diff --cached | grep -i "DOUBAO_APP_ID\|DOUBAO_ACCESS_TOKEN\|AKLT\|VOLCENGINE"
|
||
# 如果有输出，说明有凭证要被提交，请取消并修改
|
||
|
||
# 5. 提交
|
||
git commit -m "feat: Add Doubao Voice plugin with TTS/ASR support"
|
||
|
||
# 6. 再次检查
|
||
git show HEAD # 确认提交内容
|
||
|
||
# 7. 推送
|
||
git push origin main
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 验证清单
|
||
|
||
提交前，运行以下命令确认安全：
|
||
|
||
```bash
|
||
# 检查是否有真实凭证在staged文件中
|
||
git diff --cached | grep -E "2288996168|LlDjcX-_UEnn4OW87iMorpXccQUilaHX|AKLTMGQ3"
|
||
# 正常情况下应该没有输出
|
||
|
||
# 检查 setup_env.local.sh 是否被忽略
|
||
git status | grep setup_env.local.sh
|
||
# 应该看不到这个文件
|
||
|
||
# 检查 .gitignore 配置是否正确
|
||
cat .gitignore | grep "setup_env.local"
|
||
# 应该看到这一行
|
||
|
||
# 查看即将提交的文件列表
|
||
git ls-files
|
||
# 确认关键文件都在其中，但不包含 setup_env.local.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 使用说明（给其他用户）
|
||
|
||
在您发布插件后，其他用户应该：
|
||
|
||
```bash
|
||
# 1. 克隆插件
|
||
git clone <repo-url> doubao-voice-plugin
|
||
cd doubao-voice-plugin/scripts
|
||
|
||
# 2. 创建本地配置
|
||
cp setup_env.local.sh.example setup_env.local.sh
|
||
|
||
# 3. 编辑配置，填入他们自己的凭证
|
||
vim setup_env.local.sh
|
||
|
||
# 4. 配置环境变量
|
||
source setup_env.local.sh
|
||
|
||
# 5. 测试功能
|
||
python3 voice_converter.py tts "测试"
|
||
|
||
# 6. setup_env.local.sh 不会被版本控制跟踪
|
||
git status # 看不到 setup_env.local.sh ✅
|
||
```
|
||
|
||
---
|
||
|
||
## FAQ
|
||
|
||
**Q: 我不小心提交了凭证怎么办？**
|
||
|
||
A: 立即执行：
|
||
```bash
|
||
# 从 Git 历史中移除敏感文件
|
||
git rm --cached scripts/setup_env.local.sh
|
||
git commit --amend -m "Remove sensitive file"
|
||
|
||
# 更改您的火山引擎 Access Token（出于安全考虑）
|
||
# 在控制台重新生成新的 token
|
||
```
|
||
|
||
**Q: 为什么需要 setup_env.local.sh.example？**
|
||
|
||
A: 这样其他用户可以看到配置文件应该包含哪些环境变量，而不会暴露任何真实凭证。
|
||
|
||
**Q: 可以把凭证放在 ~/.bashrc 里吗？**
|
||
|
||
A: 可以，但 setup_env.local.sh 更加灵活，易于项目专用配置。
|
||
|
||
**Q: 如何在 CI/CD 中使用敏感凭证？**
|
||
|
||
A: 在 CI/CD 平台（GitHub Actions, GitLab CI等）中使用 Secrets/Variables 功能，不要在代码中硬编码。
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
✅ **已完成的安全措施**：
|
||
1. ✓ .gitignore 配置了敏感文件忽略规则
|
||
2. ✓ setup_env.sh 改为占位符版本
|
||
3. ✓ 创建了 setup_env.local.sh.example 模板
|
||
4. ✓ 所有代码文件使用环境变量读取凭证
|
||
5. ✓ 提供了清晰的本地配置说明
|
||
|
||
现在可以安全地提交到 Git！🎉
|