ai-proj-helper/skills/doubao-voice-plugin/GIT_GUIDE.md

Git 提交指南

📋 提交清单

✅ 应该提交的文件

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                        # 本文件

❌ 被自动忽略的文件（勿手动提交）

# .gitignore 已配置，以下文件不会被提交：
- *.mp3, *.wav, *.pcm                 # 音频文件
- .DS_Store                           # 系统文件
- setup_env.local.sh                  # 本地凭证文件
- .env, .env.local                    # 环境变量文件
- __pycache__/                        # Python缓存
- .vscode/, .idea/                    # IDE配置

---

🔐 凭证管理 (重要！)

本地使用流程

# 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 脚本

---

📝 提交步骤

# 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

---

🔍 验证清单

提交前，运行以下命令确认安全：

# 检查是否有真实凭证在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

---

使用说明（给其他用户）

在您发布插件后，其他用户应该：

# 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: 立即执行：

# 从 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！🎉