bkywksj 与 Gemini CLI 协同开发
通过 Python 桥接脚本调用 Gemini CLI，获取前端原型和 UI 设计建议。
快速开始
# 相对路径（推荐，在项目根目录执行）
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py --cd . --PROMPT "Your task"
输出: JSON 格式，包含 success、SESSION_ID、agent_messages 和可选的 error。
参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
--PROMPT |
str | ✅ | - | 发送给 Gemini 的任务指令（使用英语） |
--cd |
Path | ✅ | - | 工作目录根路径 |
--sandbox |
bool | ❌ | True |
沙箱模式（只读），默认开启 |
--no-sandbox |
bool | ❌ | False |
禁用沙箱（允许 Gemini 执行工具） |
--SESSION_ID |
str | ❌ | "" |
会话索引号或 latest（继续之前的对话） |
--return-all-messages |
bool | ❌ | False |
返回完整推理信息（含工具调用和推理过程） |
--model |
str | ❌ | None |
指定模型（仅用户明确要求时使用） |
--yolo |
bool | ❌ | False |
跳过所有审批（覆盖 --approval-mode，危险） |
--include-directories |
List[Path] | ❌ | [] |
额外工作区目录（跨项目引用） |
使用模式
1. 基础调用（默认只读模式）
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Design a responsive card component for product display"
2. 多轮会话
始终保存 SESSION_ID 用于后续对话：
# 第一轮：设计 UI
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Design a mobile-first login page with form validation"
# 后续轮次：使用返回的 SESSION_ID（索引号）继续
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--SESSION_ID "latest" \
--PROMPT "Add dark mode support to the login page design"
3. 获取 Unified Diff 补丁
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Generate a unified diff to improve the CSS layout. OUTPUT: Unified Diff Patch ONLY."
4. 调试模式（返回完整信息）
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Debug this styling issue: elements overflow on mobile" \
--return-all-messages
5. 引用项目文件（@file 语法）
Gemini CLI 支持 @file 语法直接引用文件内容：
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Review the component in @src/components/MyComponent.vue and suggest improvements for accessibility. OUTPUT: Unified Diff Patch ONLY."
6. 跨目录工作区
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--include-directories "../shared-lib" \
--PROMPT "Analyze how shared-lib types are used in this project"
返回值结构
成功时：
{
"success": true,
"SESSION_ID": "5",
"agent_messages": "模型回复内容..."
}
失败时：
{
"success": false,
"error": "错误信息描述"
}
安全模式说明
| 模式 | 参数 | 说明 | 适用场景 |
|---|---|---|---|
| 沙箱（默认） | 默认或 --sandbox |
只读模式，Gemini 不修改文件 | 代码审查、设计讨论、原型建议 |
| 非沙箱 | --no-sandbox |
允许 Gemini 执行工具（每次需确认） | 需要 Gemini 直接操作文件 |
| YOLO | --yolo |
自动批准所有工具（危险） | 快速原型（仅限信任环境） |
推荐：始终使用默认的沙箱模式。将 Gemini 的输出视为"脏原型"，由 Claude 重构为生产代码。
协作工作流
推荐场景
| 场景 | 说明 |
|---|---|
| 前端/UI/UX | Gemini 擅长 CSS、样式和视觉设计 |
| 组件设计 | React/Vue 组件的原型设计 |
| 响应式布局 | 移动端适配和布局优化 |
| 样式审查 | CSS 代码质量和最佳实践 |
| 文件引用分析 | 利用 @file 语法让 Gemini 直接读取项目文件 |
重要约束
- 默认只读: 默认
--approval-mode plan，Gemini 不会修改任何文件 - 英语交互: 与 Gemini 交互时使用英语，获得更好效果
- Diff 输出: 在 PROMPT 中明确要求
OUTPUT: Unified Diff Patch ONLY - 后端逻辑: Gemini 对后端逻辑理解有缺陷，后端任务优先使用 Codex
- 重构代码: 将 Gemini 的输出视为"脏原型"，由 Claude 重构为生产代码
- 后台运行: 对于长时间任务，使用
Run in the background
与本项目的集成
典型用例：组件设计
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Design a React/Vue component for @src/components/MyComponent.vue. Focus on clean layout with dark mode support. OUTPUT: Complete component code."
典型用例：样式审查
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Review the CSS in @src/styles/main.css for consistency, unused rules, and best practices."
典型用例：UI 原型
python .claude/skills/collaborating-with-gemini/scripts/gemini_bridge.py \
--cd . \
--PROMPT "Design a file browser panel UI with tree navigation, search, and context menu. Use the project's existing UI framework. OUTPUT: Complete component code."
安装前置
# 安装 Gemini CLI
npm install -g @google/gemini-cli
# 配置 API Key（方式一：环境变量）
# 设置 GEMINI_API_KEY 环境变量
# 配置 API Key（方式二：CLI 登录）
gemini auth login
故障排除
| 问题 | 解决方案 |
|---|---|
gemini: command not found |
npm install -g @google/gemini-cli 并确保在 PATH 中 |
GEMINI_API_KEY 未设置 |
设置环境变量或执行 gemini auth login |
SESSION_ID 获取失败 |
检查网络连接和 API Key |
| 输出被截断 | 使用 --return-all-messages 获取完整信息 |
| 脚本超时无响应 | 检查是否因无 result 事件导致，用 --return-all-messages 调试 |
| Windows 路径问题 | 使用正斜杠 / 或双反斜杠 \\ |
| 会话恢复失败 | 使用 --SESSION_ID latest 或具体索引号（非 UUID） |
Gemini vs Codex 选择指南
| 任务类型 | 推荐模型 | 原因 |
|---|---|---|
| 前端 UI/CSS | Gemini | 视觉设计能力强 |
| 后端逻辑 | Codex | 算法和逻辑分析强 |
| 组件样式 | Gemini | CSS 和布局专长 |
| API 设计 | Codex | 接口设计和架构 |
| 代码审查 | 两者皆可 | 双模型交叉验证更好 |
| 文件引用分析 | Gemini | @file 语法直接读文件 |