From ccd8f9dbfb371dadec5cf812f201f27cb39f87fc Mon Sep 17 00:00:00 2001 From: empty Date: Sun, 11 Jan 2026 17:17:53 +0800 Subject: [PATCH] Add codex-collab skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex 协作框架 - 让 Claude Code 和 Codex CLI 高效协作 功能特性: - 智能任务分类（简单/中等/复杂） - 标准化协作流程 - 4个专业模板（代码审查、需求分析、方案设计、调试分析） - 会话管理最佳实践 - 安全规范内置 Co-Authored-By: Claude --- codex-collab/QUICK_REF.md | 161 +++++++++ codex-collab/README.md | 223 ++++++++++++ codex-collab/examples/complete-session.md | 326 ++++++++++++++++++ codex-collab/skill.md | 178 ++++++++++ codex-collab/templates/code-review.md | 96 ++++++ codex-collab/templates/debug-analysis.md | 128 +++++++ codex-collab/templates/design-proposal.md | 155 +++++++++ .../templates/requirement-analysis.md | 102 ++++++ 8 files changed, 1369 insertions(+) create mode 100644 codex-collab/QUICK_REF.md create mode 100644 codex-collab/README.md create mode 100644 codex-collab/examples/complete-session.md create mode 100644 codex-collab/skill.md create mode 100644 codex-collab/templates/code-review.md create mode 100644 codex-collab/templates/debug-analysis.md create mode 100644 codex-collab/templates/design-proposal.md create mode 100644 codex-collab/templates/requirement-analysis.md diff --git a/codex-collab/QUICK_REF.md b/codex-collab/QUICK_REF.md new file mode 100644 index 0000000..36a5eff --- /dev/null +++ b/codex-collab/QUICK_REF.md @@ -0,0 +1,161 @@ +# Codex Collaboration Skill - 快速参考卡 + +## 快速决策流程 + +``` + ┌─────────────────┐ + │ 用户需求 │ + └────────┬────────┘ + │ + ▼ + ┌─────────────────┐ + │ 是查找/定位？ │ + └────────┬────────┘ + 是/ │ \否 + / │ \ + ▼ │ ▼ + ┌──────────┐ │ ┌──────────────┐ + │ 调 Codex │ │ │ 评估复杂度 │ + │ 搜索定位 │ │ └──────┬───────┘ + └──────────┘ │ │ + │ ┌─────┴─────┐ + │ ▼ ▼ + │ 简单 中等/复杂 + │ │ │ + │ ▼ ▼ + │ 直接执行 ┌─────────┐ + │ │ 调 Codex│ + │ │ 分析方案│ + │ └─────────┘ + │ +``` + +## 常用命令 + +### 1. 代码搜索/定位 +```python +codex( + PROMPT="搜索与【功能描述】相关的代码", + cd="/project", + sandbox="read-only" +) +``` + +### 2. 需求分析 +```python +codex( + PROMPT="分析需求：{用户需求}", + cd="/project", + sandbox="read-only" +) +# 保存 SESSION_ID +``` + +### 3. 继续讨论 +```python +codex( + PROMPT="关于你的方案，{疑问/讨论点}", + cd="/project", + SESSION_ID="上次的SESSION_ID", + sandbox="read-only" +) +``` + +### 4. 请求代码原型 +```python +codex( + PROMPT="提供代码原型（unified diff patch）：{功能说明}", + cd="/project", + SESSION_ID="上次的SESSION_ID", + sandbox="read-only" +) +``` + +### 5. 代码审查 +```python +codex( + PROMPT="审查代码：{改动说明}", + cd="/project", + SESSION_ID="之前的SESSION_ID" +) +``` + +## 参数速查表 + +| 参数 | 常用值 | 说明 | +|------|--------|------| +| `cd` | 项目路径 | **必选**，必须指向存在的目录 | +| `sandbox` | "read-only" | **推荐**，最安全 | +| `SESSION_ID` | 之前的ID | 多轮对话必传 | +| `return_all_messages` | True/False | 是否需要详细推理过程 | + +## 安全检查清单 + +调用 Codex 前检查： +- [ ] `cd` 参数是否正确 +- [ ] 是否需要使用 `SESSION_ID` 继续 +- [ ] `sandbox` 是否设置为 "read-only" +- [ ] 是否明确要求 unified diff patch + +调用 Codex 后检查： +- [ ] 是否保存了返回的 `SESSION_ID` +- [ ] `success` 字段是否为 `true` +- [ ] 是否需要验证 Codex 的建议 + +## 常见场景 + +| 场景 | 调用 Codex | Claude Code | +|------|-----------|-------------| +| 查找代码 | ✅ 搜索定位 | - | +| 理解代码 | ✅ 分析解释 | - | +| Bug定位 | ✅ 调试分析 | - | +| 需求分析 | ✅ 分析方案 | - | +| 功能设计 | ✅ 设计方案 | 讨论完善 | +| 代码实现 | ❌ 不用 | ✅ 编写代码 | +| 代码审查 | ✅ 审查代码 | 根据意见调整 | + +## 最佳实践 + +### DO ✅ +- 始终追踪 `SESSION_ID` +- 使用 `sandbox="read-only"` +- 保持批判性思维 +- 完成编码后立即审查 +- 明确要求 unified diff + +### DON'T ❌ +- 盲目接受建议 +- 让 Codex 直接改代码 +- 忘记保存 SESSION_ID +- 跳过审查环节 +- 使用 danger-full-access + +## 会话状态跟踪 + +```python +# 建议在会话开始时创建变量 +codex_session = { + "session_id": None, + "stage": "init", # init | analysis | design | review + "context": {} +} + +# 每次调用后更新 +def update_session(result): + codex_session["session_id"] = result.get("SESSION_ID") + # ... +``` + +## 错误处理 + +```python +result = codex(...) + +if not result.get("success"): + # 处理错误 + print(f"Error: {result.get('error')}") + # 可能的恢复策略： + # 1. 检查 cd 路径 + # 2. 检查 Codex 是否安装 + # 3. 尝试不传 SESSION_ID 重新开始 +``` diff --git a/codex-collab/README.md b/codex-collab/README.md new file mode 100644 index 0000000..8dbf58c --- /dev/null +++ b/codex-collab/README.md @@ -0,0 +1,223 @@ +# Codex Collaboration Skill + +**智能协作框架 - 让 Claude Code 和 Codex CLI 高效协作** + +## 概述 + +Codex Collaboration Skill 是一个专为 Claude Code 设计的协作框架，封装了与 Codex CLI 进行高效、安全协作的最佳实践。通过 CodexMCP 协议，实现两个 AI 编程助手的优势互补。 + +### 核心价值 + +- **智能任务分类**：自动判断任务复杂度，选择最优协作策略 +- **标准化流程**：封装经过验证的协作模式 +- **会话管理**：简化多轮对话和上下文管理 +- **安全规范**：内置最佳实践和安全准则 + +## 快速开始 + +### 安装 + +1. 确保已安装 CodexMCP： +```bash +claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp +``` + +2. 将此 skill 添加到 Claude Code skills 目录： +```bash +# 默认 skills 目录：~/.claude/skills/ +cp -r codex-collaboration-skill ~/.claude/skills/ +``` + +### 基本使用 + +当用户需求涉及以下场景时，Claude Code 会自动启用此 skill： + +- 代码查找和定位 +- 需求分析和方案设计 +- 代码审查 +- Bug 诊断 +- 架构优化 + +## 工作流程 + +### 任务复杂度评估 + +``` +简单任务 → 直接执行 + ↓ +中等任务 → [Codex]查找定位 → [Codex]逻辑梳理 → [Codex]方案设计 + → [Claude]代码实现 → [Codex]代码审查 + ↓ +复杂任务 → [Codex]深度分析 → [Claude+Codex]并行设计审查 + → [Codex]多轮方案迭代 → [Claude]分阶段实现 → [Codex]严格审查 +``` + +### 关键原则 + +1. **批判性思维**：Codex 是协作伙伴，不是唯一真理来源 +2. **独立判断**：对所有建议保持审视 +3. **辩论求真**：通过讨论达成最优方案 +4. **安全第一**：默认使用 sandbox="read-only" +5. **会话管理**：始终追踪 SESSION_ID + +## 文件结构 + +``` +codex-collaboration-skill/ +├── skill.md # 核心技能文档 +├── README.md # 本文件 +├── templates/ # 工作流模板 +│ ├── code-review.md # 代码审查模板 +│ ├── requirement-analysis.md # 需求分析模板 +│ ├── design-proposal.md # 方案设计模板 +│ └── debug-analysis.md # 调试分析模板 +└── examples/ # 使用示例（待添加） +``` + +## 模板说明 + +### 1. Code Review Template +用于代码审查，包含： +- 正确性检查 +- 代码质量评估 +- 性能分析 +- 安全检查 +- 测试覆盖验证 +- 文档完整性 + +### 2. Requirement Analysis Template +用于需求分析，包含： +- 需求理解 +- 技术可行性评估 +- 影响范围分析 +- 实施方案建议 +- 风险识别 +- 测试策略 + +### 3. Design Proposal Template +用于方案设计，包含： +- 整体设计 +- 接口设计 +- 数据模型设计 +- 核心逻辑设计 +- 技术选型 +- 安全设计 +- 性能考虑 +- 实施计划 +- 测试策略 +- 部署和运维 + +### 4. Debug Analysis Template +用于调试分析，包含： +- 问题定位 +- 影响范围分析 +- 解决方案 +- 预防措施 +- 验证方法 + +## 使用示例 + +### 示例 1：代码审查 + +```python +# 完成编码后，调用代码审查模板 +codex( + PROMPT=code_review_template.format( + modified_files="- src/auth/login.py: 添加用户登录验证", + change_description="实现了基于JWT的用户认证", + requirement="实现用户登录功能" + ), + cd="/project", + SESSION_ID=previous_session +) +``` + +### 示例 2：需求分析 + +```python +# 新功能需求分析 +codex( + PROMPT=requirement_analysis_template.format( + user_requirement="实现实时通知系统", + context="SaaS平台，使用Python+FastAPI", + constraints="需要向后兼容" + ), + cd="/project", + sandbox="read-only" +) +``` + +### 示例 3：调试分析 + +```python +# Bug 定位和分析 +codex( + PROMPT=debug_analysis_template.format( + error_message="AssertionError: User should be authenticated", + reproduction_steps="1. 登录 2. 等待30分钟 3. 创建订单", + context="订单创建接口需要用户认证", + recent_changes="昨天修改了JWT解码逻辑" + ), + cd="/project", + sandbox="read-only" +) +``` + +## Codex Tool 参数 + +### 必选参数 +- `PROMPT` (str): 任务指令 +- `cd` (Path): 工作目录根路径 + +### 可选参数 +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `sandbox` | str | "read-only" | 沙箱策略 | +| `SESSION_ID` | UUID | None | 会话ID | +| `return_all_messages` | bool | False | 返回完整推理 | +| `model` | str | None | 指定模型 | + +### 返回值 +```json +{ + "success": true, + "SESSION_ID": "uuid-string", + "agent_messages": "Codex响应内容" +} +``` + +## 最佳实践 + +### DO - 推荐做法 + +- ✅ 使用 sandbox="read-only" 进行方案设计和审查 +- ✅ 要求 Codex 仅提供 unified diff patch +- ✅ 保持批判性思维，质疑不合理的建议 +- ✅ 使用 SESSION_ID 进行多轮对话 +- ✅ 完成编码后立即让 Codex 审查 + +### DON'T - 避免做法 + +- ❌ 盲目接受 Codex 的所有建议 +- ❌ 让 Codex 直接修改代码 +- ❌ 忽略 SESSION_ID 管理 +- ❌ 跳过代码审查环节 +- ❌ 使用 danger-full-access 除非绝对必要 + +## 相关资源 + +- [CodexMCP 项目](https://github.com/GuDaStudio/codexmcp) +- [Claude Code 文档](https://docs.claude.com/docs/claude-code) +- [Codex CLI 文档](https://developers.openai.com/codex) + +## 贡献 + +欢迎贡献改进建议和新的模板！ + +## 许可证 + +MIT License + +--- + +**Made with ❤️ for better AI-assisted programming** diff --git a/codex-collab/examples/complete-session.md b/codex-collab/examples/complete-session.md new file mode 100644 index 0000000..6496688 --- /dev/null +++ b/codex-collab/examples/complete-session.md @@ -0,0 +1,326 @@ +# 完整协作会话示例 + +## 场景：实现用户认证功能 + +### 阶段 1：需求分析 + +**用户需求**： +``` +我需要为我的 FastAPI 应用添加用户认证功能，包括： +1. 用户注册（邮箱+密码） +2. 用户登录（返回JWT token） +3. Token验证中间件 +4. 密码重置功能 +``` + +**Claude Code 调用 Codex**： +```python +# 第一阶段：需求分析 +codex( + PROMPT=""" + 请分析以下用户认证需求，并提供： + 1. 需求理解和目标拆解 + 2. 技术方案建议 + 3. 风险点和注意事项 + 4. 实施建议 + + 需求： + - 用户注册（邮箱+密码） + - 用户登录（返回JWT token） + - Token验证中间件 + - 密码重置功能 + + 项目背景： + - FastAPI 应用 + - PostgreSQL 数据库 + - 已有用户表（id, email, created_at） + """, + cd="/project", + sandbox="read-only", + return_all_messages=False +) +``` + +**Codex 返回**： +```json +{ + "success": true, + "SESSION_ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "agent_messages": "## 需求分析结果\n\n### 1. 需求理解\n核心需求是实现完整的用户认证系统...\n\n### 2. 技术方案建议\n- 使用 passlib 进行密码哈希\n- 使用 python-jose 处理 JWT\n- 使用 FastAPI Depends 实现中间件\n\n### 3. 风险点\n- 密码安全：必须使用 bcrypt 且 salt rounds >= 12\n- Token 安全：使用 RS256 签名，设置合理过期时间\n- 密码重置：需要安全的 token 生成机制\n\n### 4. 实施建议\n按以下顺序实现：\n1. 密码哈希工具\n2. JWT 工具\n3. 注册端点\n4. 登录端点\n5. 认证中间件\n6. 密码重置" +} +``` + +--- + +### 阶段 2：方案讨论 + +**Claude Code 继续讨论**： +```python +# 使用同一 SESSION_ID 继续对话 +codex( + PROMPT=""" + 关于你的方案，我有几个疑问： + + 1. 关于密码重置，你建议使用什么机制生成重置 token？ + 2. JWT 的过期时间建议设置为多长？ + 3. 是否需要实现 refresh token 机制？ + 4. 数据库是否需要新增字段？ + + 请详细说明。 + """, + cd="/project", + SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890", + sandbox="read-only" +) +``` + +**Codex 返回详细解答**... + +--- + +### 阶段 3：请求代码原型 + +**Claude Code 请求原型**： +```python +# 请求代码原型（仅 unified diff patch） +codex( + PROMPT=""" + 基于我们讨论的方案，请提供代码实现原型。 + + **重要要求**： + - 仅提供 unified diff patch 格式 + - 不要实际修改任何代码 + - 包含完整的类型注解 + - 关键逻辑添加注释说明 + + 需要实现的模块： + 1. src/auth/password.py - 密码哈希工具 + 2. src/auth/jwt.py - JWT 工具 + 3. src/api/endpoints/auth.py - 认证端点 + 4. src/auth/dependencies.py - FastAPI 依赖 + + 请按文件分别提供 diff。 + """, + cd="/project", + SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890", + sandbox="read-only" +) +``` + +--- + +### 阶段 4：Claude Code 实现 + +**Claude Code 基于 Codex 的原型，重新编写生产级代码**： +```python +# Claude Code 使用 Edit 工具编写实际代码 + +# 1. 创建密码哈希模块 +# src/auth/password.py +from passlib.context import CryptContext + +pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto") + +def verify_password(plain_password: str, hashed_password: str) -> bool: + """验证密码""" + return pwd_context.verify(plain_password, hashed_password) + +def get_password_hash(password: str) -> str: + """生成密码哈希""" + return pwd_context.hash(password) + +# 2. 创建 JWT 工具模块 +# src/auth/jwt.py +from datetime import datetime, timedelta +from jose import JWTError, jwt +from typing import Optional + +SECRET_KEY = "your-secret-key-here" +ALGORITHM = "HS256" + +def create_access_token(data: dict, expires_delta: Optional[timedelta] = None): + """创建访问令牌""" + to_encode = data.copy() + expire = datetime.utcnow() + (expires_delta or timedelta(minutes=15)) + to_encode.update({"exp": expire}) + return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM) + +# 3. 创建认证端点 +# src/api/endpoints/auth.py +from fastapi import APIRouter, HTTPException, Depends +from pydantic import BaseModel + +router = APIRouter() + +class LoginRequest(BaseModel): + email: str + password: str + +@router.post("/login") +async def login(req: LoginRequest): + # 实现登录逻辑 + pass + +# 4. 创建认证依赖 +# src/auth/dependencies.py +from fastapi import Depends, HTTPException, status +from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials + +security = HTTPBearer() + +async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)): + """获取当前用户""" + # 实现 token 验证逻辑 + pass +``` + +--- + +### 阶段 5：代码审查 + +**Claude Code 完成编码后，立即请求审查**： +```python +# 请求 Codex 审查代码 +codex( + PROMPT=f""" + 请审查以下代码改动： + + ## 改动文件列表 + - src/auth/password.py（新建）：密码哈希工具 + - src/auth/jwt.py（新建）：JWT 工具 + - src/api/endpoints/auth.py（新建）：认证端点 + - src/auth/dependencies.py（新建）：认证依赖 + + ## 改动说明 + 实现了完整的用户认证系统： + 1. 使用 bcrypt 进行密码哈希（salt rounds=12） + 2. 使用 HS256 算法生成 JWT，默认15分钟过期 + 3. 提供 /login 和 /register 端点 + 4. 实现 get_current_user 依赖用于保护路由 + + ## 原始需求 + 实现用户注册、登录、Token验证和密码重置功能 + + 请按以下维度审查： + 1. 正确性 - 是否正确实现需求 + 2. 代码质量 - 可读性和可维护性 + 3. 安全性 - 密码和 token 安全 + 4. 边界情况 - 异常处理 + 5. 测试覆盖 - 是否需要测试 + + 请提供： + 1. 总体评价 + 2. 必须修复的问题（如有） + 3. 建议改进的地方 + """, + cd="/project", + SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890" +) +``` + +**Codex 审查结果**： +```json +{ + "success": true, + "agent_messages": "## 审查结果\n\n### 总体评价：良好\n\n### 必须修复的问题：\n1. SECRET_KEY 硬编码在代码中，应该从环境变量读取\n2. 缺少密码强度验证\n3. jwt.decode() 没有异常处理\n\n### 建议改进：\n1. 建议添加 refresh token 机制\n2. 密码重置功能还未实现\n3. 建议添加速率限制防止暴力破解\n4. 建议添加日志记录" +} +``` + +--- + +### 阶段 6：根据审查调整 + +**Claude Code 根据审查意见进行调整**： +```python +# 修复必须修复的问题 + +# 1. 修改 jwt.py，从环境变量读取 SECRET_KEY +import os +from dotenv import load_dotenv + +load_dotenv() +SECRET_KEY = os.getenv("JWT_SECRET_KEY") +if not SECRET_KEY: + raise ValueError("JWT_SECRET_KEY environment variable is not set") + +# 2. 添加密码强度验证 +# src/auth/validators.py +import re + +def validate_password_strength(password: str) -> bool: + """验证密码强度""" + if len(password) < 8: + return False + if not re.search(r"[A-Z]", password): + return False + if not re.search(r"[a-z]", password): + return False + if not re.search(r"\d", password): + return False + return True + +# 3. 添加 JWT 异常处理 +# src/auth/jwt.py +def decode_token(token: str): + """解码 JWT token""" + try: + payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM]) + return payload + except JWTError as e: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail=f"Invalid token: {str(e)}" + ) +``` + +--- + +### 阶段 7：最终审查 + +**Claude Code 再次请求审查**： +```python +codex( + PROMPT=""" + 我已根据你的审查意见进行了修复： + 1. SECRET_KEY 从环境变量读取 + 2. 添加了密码强度验证 + 3. 添加了 JWT 异常处理 + + 请再次审查，确认是否还有问题。 + """, + cd="/project", + SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890" +) +``` + +--- + +## 协作流程总结 + +``` +用户需求 + ↓ +[阶段1] Codex 需求分析 → 获得 SESSION_ID + ↓ +[阶段2] 多轮讨论完善方案 → 使用同一 SESSION_ID + ↓ +[阶段3] 请求代码原型（unified diff）→ 使用同一 SESSION_ID + ↓ +[阶段4] Claude Code 重写生产级代码 + ↓ +[阶段5] Codex 代码审查 → 使用同一 SESSION_ID + ↓ +[阶段6] 根据审查调整代码 + ↓ +[阶段7] 最终审查确认 → 使用同一 SESSION_ID + ↓ +完成 +``` + +## 关键要点 + +1. **始终使用同一 SESSION_ID**：保持上下文连贯 +2. **批判性思维**：对 Codex 的建议保持审视 +3. **安全优先**：使用 sandbox="read-only" +4. **重写代码**：基于原型编写生产级代码 +5. **即时审查**：完成后立即让 Codex review diff --git a/codex-collab/skill.md b/codex-collab/skill.md new file mode 100644 index 0000000..fd9c063 --- /dev/null +++ b/codex-collab/skill.md @@ -0,0 +1,178 @@ +# Codex Collaboration Skill + +## Description + +**Codex Collaboration Skill** 是一个专为 Claude Code 设计的协作框架，用于与 Codex CLI 进行高效、安全的智能协作。通过 CodexMCP 协议，实现两个 AI 编程助手的优势互补： + +- **Claude Code**: 擅长架构设计、需求分析、代码重构 +- **Codex**: 擅长代码生成、精确定位、细节优化 + +## When to Use This Skill + +当用户需求涉及以下场景时，应主动使用此 skill： + +1. **代码查找和定位**：搜索代码、定位功能、查找引用 +2. **需求分析和方案设计**：理解业务需求、设计实施方案 +3. **代码审查**：检查代码质量、发现潜在问题 +4. **Bug 诊断**：分析错误原因、定位问题代码 +5. **架构优化**：评估设计方案、提出改进建议 + +## Task Complexity Assessment + +在开始任务前，必须先进行复杂度评估： + +### Simple Tasks (直接执行) +满足**所有**以下条件： +- ✅ 无生产影响（如文档、注释、简单查询） +- ✅ 无需新增基础设施或外部依赖 +- ✅ 不涉及多个子系统协调 + +**示例**：查询数据、添加日志、修改文案、简单重命名 + +### Medium Tasks (Codex协作) +满足**至少一个**以下条件： +- 📊 有限生产影响（需要测试验证） +- 📊 需要小规模配置调整或库引入 +- 📊 需要理解模块间调用关系 + +**示例**：功能增强、Bug修复、接口调整、业务逻辑优化 + +### Complex Tasks (深度Codex协作) +满足**至少两个**以下条件： +- 🔥 高生产影响（安全、性能、数据一致性） +- 🔥 架构变更、新基础设施、核心依赖升级 +- 🔥 需要多agent协调或跨团队对齐 + +**示例**：新模块开发、架构重构、性能优化、安全加固 + +## Workflow Templates + +### 简单任务工作流 +``` +用户需求 → 快速分析 → 直接实现 → 简单自检 → 完成 +``` + +### 中等任务工作流 +``` +用户需求 → [Codex]查找定位 → [Codex]逻辑梳理 + → [Codex]方案设计 → [Claude]代码实现 → [Codex]代码审查 → 完成 +``` + +### 复杂任务工作流 +``` +用户需求 → [Codex]深度分析 → [Claude+Codex]并行设计审查 + → [Codex]多轮方案迭代 → [Claude]分阶段实现 → [Codex]严格审查 → 完成 +``` + +## Codex Tool Reference + +### Required Parameters +- `PROMPT` (str): 任务指令 +- `cd` (Path): 工作目录根路径 + +### Optional Parameters +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `sandbox` | str | "read-only" | 沙箱策略：read-only / workspace-write / danger-full-access | +| `SESSION_ID` | UUID \| None | None | 会话ID（None表示新会话） | +| `skip_git_repo_check` | bool | False | 是否允许在非Git仓库运行 | +| `return_all_messages` | bool | False | 是否返回完整推理信息 | +| `image` | List[Path] \| None | None | 附加图片文件 | +| `model` | str \| None | None | 指定使用的模型 | +| `yolo` | bool | False | 跳过所有审批和沙箱 | +| `profile` | str \| None | None | 配置文件名 | + +### Return Value +```json +{ + "success": true, + "SESSION_ID": "uuid-string", + "agent_messages": "Codex响应内容", + "all_messages": [...] // 仅当return_all_messages=True时 +} +``` + +## Critical Principles + +1. **批判性思维**：Codex是协作伙伴，不是唯一真理来源 +2. **独立判断**：对所有建议保持审视，主动提出质疑 +3. **辩论求真**：通过讨论达成最优方案 +4. **安全第一**：默认使用 sandbox="read-only" +5. **会话管理**：始终追踪 SESSION_ID + +## Session Management + +### Starting a New Session +不传 `SESSION_ID` 参数，工具会返回新的 SESSION_ID + +### Continuing a Session +使用之前返回的 `SESSION_ID` 参数，保留上下文 + +## Safety Guidelines + +1. **禁止实际修改**：要求 Codex 仅提供 unified diff patch +2. **仅作参考**：Codex 的代码原型只能作为逻辑参考 +3. **重写代码**：由 Claude Code 重新编写为生产级代码 +4. **即时审查**：完成编码后立即调用 Codex 进行 review + +## Prompt Templates + +### 需求分析模板 +``` +请分析以下需求，并提供： +1. 需求理解和目标拆解 +2. 技术方案建议 +3. 风险点和注意事项 +4. 实施建议 + +需求：{user_requirement} +``` + +### 代码审查模板 +``` +请审查以下代码改动，检查： +1. 代码质量和可读性 +2. 潜在的bug和边界情况 +3. 性能和安全问题 +4. 与需求的匹配度 + +改动文件：{modified_files} +改动说明：{change_description} +``` + +### 方案设计模板 +``` +请设计以下功能的实现方案： +1. 整体架构设计 +2. 模块划分和接口定义 +3. 关键技术点 +4. 实施步骤 + +功能需求：{feature_requirement} +``` + +## Examples + +### Example 1: 代码定位和Bug修复 +``` +# 1. 调用 Codex 定位问题 +codex(PROMPT="搜索项目中处理用户认证的相关代码", cd="/project") + +# 2. 基于 Codex 的定位结果，Claude Code 分析问题 +# 3. Claude Code 编写修复代码 +# 4. 调用 Codex 审查修复 +codex(PROMPT="审查以下代码改动...", SESSION_ID=previous_session) +``` + +### Example 2: 新功能开发 +``` +# 1. 调用 Codex 进行需求分析 +codex(PROMPT="分析以下需求并设计实施方案...", cd="/project") + +# 2. 多轮讨论完善方案 +codex(PROMPT="关于你的方案，我有以下疑问...", SESSION_ID=session_1) + +# 3. Claude Code 基于方案编写代码 +# 4. Codex 审查代码 +codex(PROMPT="请审查已完成的代码实现", SESSION_ID=session_1) +``` diff --git a/codex-collab/templates/code-review.md b/codex-collab/templates/code-review.md new file mode 100644 index 0000000..a4a7473 --- /dev/null +++ b/codex-collab/templates/code-review.md @@ -0,0 +1,96 @@ +# Code Review Template + +## Template Variables +- `{modified_files}`: List of modified files +- `{change_description}`: Description of changes made +- `{requirement}`: Original requirement/user story + +## Prompt Template + +``` +请作为资深代码审查专家，审查以下代码改动： + +## 改动文件列表 +{modified_files} + +## 改动说明 +{change_description} + +## 原始需求 +{requirement} + +## 审查检查清单 + +请按以下维度进行审查： + +### 1. 正确性 (Correctness) +- [ ] 代码逻辑是否正确实现了需求 +- [ ] 是否有明显的bug或逻辑错误 +- [ ] 边界条件和异常情况是否处理 +- [ ] 数据验证是否充分 + +### 2. 代码质量 (Code Quality) +- [ ] 代码可读性和可维护性 +- [ ] 命名是否清晰准确 +- [ ] 是否有重复代码 +- [ ] 函数和类的职责是否单一 + +### 3. 性能 (Performance) +- [ ] 是否有明显的性能问题 +- [ ] 资源使用是否合理 +- [ ] 是否有不必要的计算或IO操作 +- [ ] 算法复杂度是否合理 + +### 4. 安全性 (Security) +- [ ] 是否有安全漏洞 +- [ ] 输入验证是否充分 +- [ ] 敏感信息是否正确处理 +- [ ] 权限检查是否完善 + +### 5. 测试覆盖 (Testing) +- [ ] 关键逻辑是否有测试覆盖 +- [ ] 测试用例是否充分 +- [ ] 边界条件是否测试 + +### 6. 文档 (Documentation) +- [ ] 复杂逻辑是否有注释 +- [ ] API文档是否完整 +- [ ] 变更日志是否更新 + +## 审查结论 + +请提供： +1. 总体评价（优秀/良好/需改进/不合格） +2. 主要优点（1-3点） +3. 必须修复的问题（如有） +4. 建议改进的地方（如有） +5. 其他意见 +``` + +## Usage Example + +```python +# After completing code changes +modified_files = """ +- src/auth/login.py: 添加用户登录验证 +- src/auth/jwt.py: 实现JWT token生成和验证 +- tests/test_login.py: 添加登录测试用例 +""" + +change_description = """ +实现了基于JWT的用户认证系统： +1. 用户登录验证（用户名+密码） +2. JWT token生成和验证 +3. token过期处理 +4. 单元测试覆盖 +""" + +requirement = "实现用户登录功能，支持JWT token认证" + +# Call Codex for review +codex( + PROMPT=f"", + cd="/project", + SESSION_ID=previous_session +) +``` diff --git a/codex-collab/templates/debug-analysis.md b/codex-collab/templates/debug-analysis.md new file mode 100644 index 0000000..53c8a58 --- /dev/null +++ b/codex-collab/templates/debug-analysis.md @@ -0,0 +1,128 @@ +# Debug Analysis Template + +## Template Variables +- `{error_message}`: Error message or stack trace +- `{reproduction_steps}`: Steps to reproduce the issue +- `{context}`: What was happening when the error occurred +- `{recent_changes}`: Recent code changes that might be related + +## Prompt Template + +``` +请作为调试专家，帮助分析和定位以下问题： + +## 错误信息 +``` +{error_message} +``` + +## 复现步骤 +{reproduction_steps} + +## 问题背景 +{context} + +## 最近改动 +{recent_changes} + +## 分析要求 + +请提供： + +### 1. 问题定位 +- 定位到具体的代码位置（文件:行号） +- 说明问题发生的直接原因 +- 分析问题的根本原因 + +### 2. 影响范围 +- 影响哪些功能模块 +- 影响的用户场景 +- 问题的严重程度评估 + +### 3. 可能的解决方案 +- 推荐的修复方案（优先级排序） +- 每个方案的优缺点 +- 推荐方案的实现要点 + +### 4. 预防措施 +- 如何避免类似问题 +- 需要添加的测试 +- 需要改进的地方 + +### 5. 验证方法 +- 如何验证问题已修复 +- 需要测试的场景 +- 回归测试建议 + +## 输出格式 + +1. **问题诊断**（一句话总结） +2. **根本原因分析**（详细说明） +3. **修复方案**（推荐方案+实现建议） +4. **验证清单** + +## 搜索指令 + +请先搜索相关代码： +1. 搜索错误信息中的关键函数或类 +2. 搜索相关的模块和文件 +3. 查找最近的代码变更 +4. 分析调用栈 +``` + +## Usage Example + +```python +# When encountering a bug +error_message = """ +AssertionError: User should be authenticated +Traceback: + File "/app/src/api/endpoints/orders.py", line 45, in create_order + assert current_user.is_authenticated, "User should be authenticated" + File "/app/src/auth/deps.py", line 23, in get_current_user + user = decode_token(token) + File "/app/src/auth/jwt.py", line 67, in decode_token + raise ExpiredTokenError() +""" + +reproduction_steps = """ +1. 用户登录后获取 token +2. 等待 30 分钟 +3. 使用该 token 创建订单 +4. 收到认证错误 +""" + +context = """ +订单创建接口需要用户认证，使用 JWT token。 +token 有效期设置为 1 小时。 +问题：用户在 token 有效期内但仍然收到认证失败错误。 +""" + +recent_changes = """ +昨天修改了 JWT 解码逻辑，优化了 token 验证流程。 +""" + +# Call Codex for debug analysis +codex( + PROMPT=f""" + + + 请先搜索以下内容： + 1. src/auth/jwt.py 中的 decode_token 函数 + 2. src/api/endpoints/orders.py 中的 create_order 函数 + 3. src/auth/deps.py 中的 get_current_user 函数 + 4. 查找最近对 jwt.py 的修改 + """, + cd="/project", + sandbox="read-only" +) +``` + +## Follow-up Actions + +After receiving debug analysis: +1. Verify Codex's diagnosis by examining the code +2. Discuss the proposed solution if needed +3. Implement the fix +4. Ask Codex to review the fix +5. Add tests to prevent regression diff --git a/codex-collab/templates/design-proposal.md b/codex-collab/templates/design-proposal.md new file mode 100644 index 0000000..bfff9f0 --- /dev/null +++ b/codex-collab/templates/design-proposal.md @@ -0,0 +1,155 @@ +# Design Proposal Template + +## Template Variables +- `{feature_requirement}`: Feature requirement description +- `{analysis_result}`: Results from requirement analysis +- `{current_architecture}`: Current system architecture +- `{tech_stack}`: Current technology stack + +## Prompt Template + +``` +请作为系统架构师，设计以下功能的详细实现方案： + +## 功能需求 +{feature_requirement} + +## 需求分析结果 +{analysis_result} + +## 当前架构 +{current_architecture} + +## 技术栈 +{tech_stack} + +## 设计要求 + +请提供以下内容： + +### 1. 整体设计 +- 系统架构图（文字描述） +- 模块划分和职责 +- 模块间的交互关系 +- 数据流设计 + +### 2. 接口设计 +- API接口定义 +- 请求/响应格式 +- 错误码定义 +- 接口调用流程 + +### 3. 数据模型设计 +- 数据库表结构 +- 字段定义和类型 +- 索引设计 +- 数据关系 + +### 4. 核心逻辑设计 +- 关键算法或逻辑流程 +- 状态机设计（如适用） +- 并发控制 +- 异常处理策略 + +### 5. 技术选型 +- 使用的技术和框架 +- 第三方库选择 +- 技术选择的理由 +- 潜在的替代方案 + +### 6. 安全设计 +- 认证和授权 +- 数据加密 +- 输入验证 +- 防护措施 + +### 7. 性能考虑 +- 性能目标 +- 优化策略 +- 缓存设计 +- 扩展性考虑 + +### 8. 实施计划 +- 开发阶段划分 +- 每个阶段的交付物 +- 依赖关系 +- 里程碑 + +### 9. 测试策略 +- 单元测试策略 +- 集成测试策略 +- 性能测试策略 +- 测试数据准备 + +### 10. 部署和运维 +- 部署方案 +- 配置管理 +- 监控指标 +- 回滚方案 + +## 输出要求 + +请提供： +1. **设计摘要**（高层概览，200字以内） +2. **详细设计**（按上述10个维度） +3. **实施检查清单**（按优先级排序） +4. **风险和缓解措施** + +## 代码原型要求 + +如需提供代码原型： +- 仅提供 unified diff patch 格式 +- 不要实际修改代码 +- 代码需要包含完整的类型注解 +- 关键逻辑需要添加注释说明 +``` + +## Usage Example + +```python +# After requirement analysis is complete +feature_requirement = """ +实现一个基于WebSocket的实时消息推送系统 +""" + +analysis_result = """ +从需求分析中得出的关键发现： +- 需要支持10万+并发连接 +- 消息延迟需控制在100ms以内 +- 需要支持消息持久化 +- 需要支持离线消息 +""" + +current_architecture = """ +微服务架构，使用： +- API Gateway +- 用户服务 +- 消息服务 +- 推送服务（待实现） +""" + +tech_stack = """ +- 后端：Python 3.11 + FastAPI +- 数据库：PostgreSQL 15 +- 缓存：Redis 7 +- 消息队列：RabbitMQ +- 容器：Docker + Kubernetes +""" + +# Call Codex for design +codex( + PROMPT=f"", + cd="/project", + SESSION_ID=analysis_session, # Continue from analysis + sandbox="read-only" +) +``` + +## Follow-up Actions + +After receiving design proposal: +1. Review the design critically +2. Ask questions about unclear parts +3. Discuss alternative approaches +4. Iterate on the design +5. Once approved, proceed to implementation diff --git a/codex-collab/templates/requirement-analysis.md b/codex-collab/templates/requirement-analysis.md new file mode 100644 index 0000000..18855b2 --- /dev/null +++ b/codex-collab/templates/requirement-analysis.md @@ -0,0 +1,102 @@ +# Requirement Analysis Template + +## Template Variables +- `{user_requirement}`: User's original requirement +- `{context}`: Project context and background +- `{constraints}`: Known constraints or limitations + +## Prompt Template + +``` +请作为技术架构专家，深入分析以下需求： + +## 用户需求 +{user_requirement} + +## 项目背景 +{context} + +## 已知约束 +{constraints} + +## 分析要求 + +请提供以下维度的分析： + +### 1. 需求理解 +- 需求的核心目标是什么 +- 涉及哪些功能模块 +- 用户期望达到什么效果 +- 需求的优先级和紧急程度 + +### 2. 技术可行性 +- 现有技术栈能否支持 +- 是否需要引入新技术或依赖 +- 技术难点在哪里 +- 预估的技术风险 + +### 3. 影响范围评估 +- 涉及哪些模块和组件 +- 是否有现有功能需要调整 +- 是否影响现有数据和API +- 兼容性考虑 + +### 4. 实施方案建议 +- 推荐的技术方案 +- 实施步骤拆解 +- 关键技术点和注意事项 +- 潜在的替代方案 + +### 5. 风险识别 +- 技术风险 +- 业务风险 +- 兼容性风险 +- 性能风险 + +### 6. 测试策略 +- 需要测试的场景 +- 测试类型建议 +- 关键测试点 + +## 输出格式 + +请以结构化的方式输出，包括： +1. 需求摘要（1-2句话） +2. 详细分析（按上述维度） +3. 推荐方案（优先推荐1个方案，可附带备选） +4. 行动检查清单 +``` + +## Usage Example + +```python +# When user provides a new requirement +user_requirement = """ +实现一个实时通知系统，支持： +1. 用户可以订阅不同类型的通知 +2. 支持多种通知渠道（邮件、短信、推送） +3. 通知可以延迟发送 +4. 用户可以自定义通知规则 +""" + +context = """ +当前系统是一个SaaS平台，使用： +- 后端：Python + FastAPI +- 前端：React + TypeScript +- 数据库：PostgreSQL + Redis +- 消息队列：RabbitMQ +""" + +constraints = """ +- 需要保持向后兼容 +- 通知发送不能阻塞主流程 +- 成本控制在合理范围内 +""" + +# Call Codex for analysis +codex( + PROMPT=f"", + cd="/project", + sandbox="read-only" +) +```