Initial commit
This commit is contained in:
Zhongwei Li
259
codex-mcp/HANDOFF_CHECKLIST.md
Normal file
259
codex-mcp/HANDOFF_CHECKLIST.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Codex 任务交接检查清单
|
||||
|
||||
使用此检查清单确保向 Codex 提供所有必要信息。
|
||||
|
||||
## 任务评估
|
||||
|
||||
**复杂度**: ⬜ 简单 ⬜ 中等 ⬜ 复杂 ⬜ 非常复杂
|
||||
**核心逻辑行数**: ________
|
||||
**主要目标**: ⬜ 算法设计 ⬜ 架构评审 ⬜ 性能优化 ⬜ 代码审查
|
||||
**紧急度**: ⬜ 低 ⬜ 中等 ⬜ 高 ⬜ 关键
|
||||
|
||||
---
|
||||
|
||||
## 核心检查清单
|
||||
|
||||
### 1. 问题定义 ✓
|
||||
- [ ] 清晰的问题陈述
|
||||
- [ ] 定义成功标准
|
||||
- [ ] 建立范围边界
|
||||
- [ ] 记录已知限制
|
||||
|
||||
### 2. 上下文信息 ✓
|
||||
- [ ] 提供项目概览
|
||||
- [ ] 共享相关背景
|
||||
- [ ] 识别相关系统/组件
|
||||
- [ ] 提供历史背景
|
||||
|
||||
```markdown
|
||||
**项目**: [名称和用途]
|
||||
**组件**: [正在处理的部分]
|
||||
**用户**: [谁使用此功能/规模]
|
||||
**历史**: [当前实现存在的原因]
|
||||
```
|
||||
|
||||
### 3. 技术约束 ✓
|
||||
- [ ] 性能要求（延迟、吞吐量）
|
||||
- [ ] 资源限制（内存、CPU、存储）
|
||||
- [ ] 兼容性要求（版本、平台）
|
||||
- [ ] 依赖约束
|
||||
|
||||
```markdown
|
||||
⬜ 时间复杂度: 最大 O(?)
|
||||
⬜ 空间复杂度: 最大 O(?)
|
||||
⬜ 延迟目标: __ms
|
||||
⬜ 吞吐量目标: __req/sec
|
||||
⬜ 内存限制: __MB/GB
|
||||
⬜ 平台: [Linux/Windows/macOS/跨平台]
|
||||
⬜ 语言版本: [例如：Rust 1.70+, Python 3.11+]
|
||||
```
|
||||
|
||||
### 4. 代码上下文 ✓
|
||||
- [ ] 共享相关现有代码
|
||||
- [ ] 记录代码风格/约定
|
||||
- [ ] 提供依赖列表
|
||||
- [ ] 包含项目结构概览
|
||||
|
||||
### 5. 数据上下文 ✓
|
||||
- [ ] 指定输入数据格式
|
||||
- [ ] 提供输入大小/规模
|
||||
- [ ] 定义预期输出格式
|
||||
- [ ] 识别边界情况
|
||||
|
||||
```markdown
|
||||
**输入**:
|
||||
- 格式: [JSON/CSV/Binary/其他]
|
||||
- 大小: [典型和最大]
|
||||
- 模式: [结构定义]
|
||||
- 示例: [示例数据]
|
||||
|
||||
**输出**:
|
||||
- 格式: [预期结构]
|
||||
- 约束: [验证规则]
|
||||
```
|
||||
|
||||
### 6. 测试用例 ✓
|
||||
- [ ] 提供正常情况（3-5 个示例）
|
||||
- [ ] 识别边界情况
|
||||
- [ ] 指定错误情况
|
||||
- [ ] 性能基准（如果适用）
|
||||
|
||||
```markdown
|
||||
**正常情况**:
|
||||
1. 输入: [...] → 期望: [...]
|
||||
2. 输入: [...] → 期望: [...]
|
||||
|
||||
**边界情况**:
|
||||
1. 空输入 → 期望: [...]
|
||||
2. 单元素 → 期望: [...]
|
||||
3. 最大大小 → 期望: [...]
|
||||
|
||||
**错误情况**:
|
||||
1. 无效格式 → 期望: [错误处理]
|
||||
2. 空值 → 期望: [错误处理]
|
||||
```
|
||||
|
||||
### 7. 性能基线 ✓
|
||||
（适用于优化任务）
|
||||
- [ ] 当前性能指标
|
||||
- [ ] 包含分析数据
|
||||
- [ ] 识别瓶颈
|
||||
- [ ] 指定目标改进
|
||||
|
||||
```markdown
|
||||
**当前性能**:
|
||||
- 延迟: p50: __ms, p95: __ms, p99: __ms
|
||||
- 吞吐量: __ops/sec
|
||||
- 内存: __MB 峰值
|
||||
- CPU: __%
|
||||
|
||||
**瓶颈** (来自分析):
|
||||
1. 函数 X: __% 时间
|
||||
2. 函数 Y: __% 时间
|
||||
|
||||
**目标**:
|
||||
- 延迟减少 __%
|
||||
- 吞吐量增加到 __ops/sec
|
||||
```
|
||||
|
||||
### 8. 安全考虑 ✓
|
||||
- [ ] 敏感数据处理要求
|
||||
- [ ] 认证/授权需求
|
||||
- [ ] 合规要求（GDPR、HIPAA 等）
|
||||
- [ ] 已知安全关注点
|
||||
|
||||
### 9. 具体问题 ✓
|
||||
- [ ] 准备至少 2 个具体问题
|
||||
- [ ] 问题集中且可回答
|
||||
- [ ] 如果有多个问题则优先排序
|
||||
|
||||
### 10. 预期交付物 ✓
|
||||
- [ ] 明确界定您需要 Codex 做什么
|
||||
- [ ] 指定格式（伪代码、完整代码、设计文档）
|
||||
- [ ] 指示详细程度
|
||||
|
||||
```markdown
|
||||
⬜ 高级架构图
|
||||
⬜ 详细设计文档
|
||||
⬜ 伪代码/算法
|
||||
⬜ 实现代码
|
||||
⬜ 测试用例
|
||||
⬜ 性能分析
|
||||
⬜ 权衡比较
|
||||
⬜ 迁移策略
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 任务特定检查清单
|
||||
|
||||
### 算法设计任务
|
||||
- [ ] 问题约束形式化
|
||||
- [ ] 提供输入/输出示例
|
||||
- [ ] 量化性能要求
|
||||
- [ ] 定义正确性标准
|
||||
- [ ] 列举边界情况
|
||||
|
||||
### 架构评审任务
|
||||
- [ ] 包含系统图
|
||||
- [ ] 记录组件交互
|
||||
- [ ] 列出当前痛点
|
||||
- [ ] 指定扩展要求
|
||||
- [ ] 记录技术栈
|
||||
|
||||
### 性能优化任务
|
||||
- [ ] 附加分析数据
|
||||
- [ ] 识别瓶颈
|
||||
- [ ] 提供当前指标
|
||||
- [ ] 定义目标指标
|
||||
- [ ] 记录约束
|
||||
|
||||
### 代码审查任务
|
||||
- [ ] 提供完整代码上下文
|
||||
- [ ] 指定审查关注领域
|
||||
- [ ] 识别关键路径
|
||||
- [ ] 列出已知问题
|
||||
- [ ] 定义审查标准
|
||||
|
||||
---
|
||||
|
||||
## MCP 工具检查清单
|
||||
|
||||
- [ ] MCP 服务器运行并可访问
|
||||
- [ ] 所需工具可用（验证 `tools/list`）
|
||||
- [ ] 配置工具权限
|
||||
- [ ] 审查 inputSchema 要求
|
||||
- [ ] 了解工具超时限制
|
||||
- [ ] 准备错误处理策略
|
||||
- [ ] 记录安全约束
|
||||
|
||||
---
|
||||
|
||||
## 发送前验证
|
||||
|
||||
发送前询问自己：
|
||||
|
||||
1. **Codex 能否在不澄清的情况下理解问题？**
|
||||
- [ ] 是 → 继续
|
||||
- [ ] 否 → 添加缺失的上下文
|
||||
|
||||
2. **约束是否完整且具体？**
|
||||
- [ ] 是 → 继续
|
||||
- [ ] 否 → 定义约束
|
||||
|
||||
3. **成功能否客观衡量？**
|
||||
- [ ] 是 → 继续
|
||||
- [ ] 否 → 添加成功标准
|
||||
|
||||
4. **范围对于一次交互是否合理？**
|
||||
- [ ] 是 → 继续
|
||||
- [ ] 否 → 拆分为更小的任务
|
||||
|
||||
5. **是否包含了示例？**
|
||||
- [ ] 是 → 继续
|
||||
- [ ] 否 → 添加示例
|
||||
|
||||
---
|
||||
|
||||
## 快速模板
|
||||
|
||||
### 快速算法请求
|
||||
```markdown
|
||||
**问题**: [一行描述]
|
||||
**输入**: [格式和约束]
|
||||
**输出**: [预期结果]
|
||||
**约束**: 时间: O(?), 空间: O(?)
|
||||
**测试用例**: [一个示例]
|
||||
```
|
||||
|
||||
### 快速性能评审
|
||||
```markdown
|
||||
**函数**: [名称]
|
||||
**当前**: [延迟/吞吐量]
|
||||
**目标**: [目标]
|
||||
**分析**: [热点]
|
||||
**代码**: [实现]
|
||||
```
|
||||
|
||||
### 快速架构问题
|
||||
```markdown
|
||||
**系统**: [描述]
|
||||
**规模**: [当前和目标]
|
||||
**挑战**: [具体问题]
|
||||
**问题**: [集中问题]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 交接质量评分
|
||||
|
||||
**总评分**: ___/25
|
||||
|
||||
- **20-25**: 优秀 - 准备交接
|
||||
- **15-19**: 良好 - 考虑添加更多细节
|
||||
- **10-14**: 需要改进 - 填补关键空白
|
||||
- **<10**: 未准备 - 缺少主要信息
|
||||
|
||||
---
|
||||
|
||||
返回 [SKILL.md](SKILL.md) 获取主要文档。
|
||||
168
codex-mcp/README.md
Normal file
168
codex-mcp/README.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Codex MCP Skill
|
||||
|
||||
一个通过标准 MCP 工具调用接口，协作 Codex 处理复杂技术任务的 Claude Code 技能。
|
||||
|
||||
## 快速入门
|
||||
|
||||
### 何时使用
|
||||
当您遇到以下场景时，此技能会自动激活：
|
||||
|
||||
| 场景 | 示例触发词 |
|
||||
|------|-----------|
|
||||
| **复杂算法设计** | "设计一个并发数据处理算法..." |
|
||||
| **性能优化** | "优化这个状态机，p99 延迟需要 < 100ms" |
|
||||
| **架构评审** | "分析系统架构，支持 10x 扩展" |
|
||||
| **代码审查** | "审查这段代码的线程安全问题" |
|
||||
|
||||
### 核心触发词
|
||||
- "深度分析"、"复杂逻辑"、"算法设计"
|
||||
- ">10行核心代码"、"状态机"
|
||||
- "架构优化"、"性能瓶颈"
|
||||
|
||||
### 典型示例
|
||||
|
||||
#### 算法设计
|
||||
```markdown
|
||||
我需要设计一个限流算法：
|
||||
- 处理 10K requests/sec
|
||||
- 每用户限制：100 req/min
|
||||
- 全局限制：10K req/sec
|
||||
- 延迟：<1ms 开销
|
||||
当前滑动窗口方案在大规模下太慢。
|
||||
推荐什么算法？
|
||||
```
|
||||
|
||||
#### 架构评审
|
||||
```markdown
|
||||
请评审我们的微服务架构，从 1K 扩展到 10K req/sec：
|
||||
|
||||
当前：API Gateway → 5个服务 → PostgreSQL + Redis
|
||||
|
||||
挑战：
|
||||
- 数据库在 p99 成为瓶颈
|
||||
- 服务紧耦合
|
||||
- 缺乏明确的缓存策略
|
||||
|
||||
建议哪些改进？
|
||||
```
|
||||
|
||||
#### 代码审查
|
||||
```markdown
|
||||
审查这个并发数据处理器，关注：
|
||||
- 线程安全问题
|
||||
- 性能瓶颈
|
||||
- 内存泄漏
|
||||
- 更好的设计模式
|
||||
|
||||
[代码]
|
||||
|
||||
担心热路径中的互斥锁使用。
|
||||
```
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 1. 描述您的任务
|
||||
直接用自然语言描述复杂技术问题，包含：
|
||||
- 问题的背景和上下文
|
||||
- 具体的约束（性能、规模、安全等）
|
||||
- 您已经尝试过的方法
|
||||
|
||||
### 2. 提供必要信息
|
||||
确保包含：
|
||||
- **约束条件**：时间/空间复杂度、性能要求
|
||||
- **测试用例**：边界情况、预期行为
|
||||
- **现有代码**：相关实现（如果有）
|
||||
- **上下文**：使用场景、依赖关系
|
||||
|
||||
### 3. 接收 Codex 分析
|
||||
Claude 会将您的请求格式化并传递给 Codex，Codex 将提供：
|
||||
- 设计文档或伪代码
|
||||
- 实现策略和最佳实践
|
||||
- 测试用例建议
|
||||
- 性能分析和优化建议
|
||||
|
||||
### 4. 验证和实施
|
||||
使用 [REFERENCE.md](REFERENCE.md) 中的集成指南验证建议：
|
||||
- 检查逻辑正确性
|
||||
- 验证性能声明
|
||||
- 测试与现有代码的兼容性
|
||||
|
||||
## 关键特性
|
||||
|
||||
### ✅ MCP 工具调用
|
||||
- **工具名称**：
|
||||
- 开启会话：`mcp__codex-mcp-tool__codex`
|
||||
- 继续对话：`mcp__codex-mcp-tool__codex-reply`
|
||||
- **会话管理**：返回的 `conversationId` 用于后续对话
|
||||
- **灵活配置**：支持模型选择、沙盒模式、审批策略等参数
|
||||
- **详细说明**：查看 [SKILL.md](SKILL.md) 获取完整的工具调用示例
|
||||
|
||||
### ✅ 协作模板
|
||||
内置标准模板：
|
||||
- 标准任务交接
|
||||
- 算法设计请求
|
||||
- 架构评审请求
|
||||
|
||||
### ✅ 最佳实践指导
|
||||
- 完整的上下文准备
|
||||
- 有效的问题提问
|
||||
- 安全的集成策略
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
codex-mcp/
|
||||
├── SKILL.md # 主要技能定义
|
||||
├── README.md # 快速入门（本文件）
|
||||
├── REFERENCE.md # 完整参考指南
|
||||
└── HANDOFF_CHECKLIST.md # 交接检查清单
|
||||
```
|
||||
|
||||
## 成功技巧
|
||||
|
||||
### 快速激活
|
||||
使用明确的触发词：
|
||||
- "需要深度分析..."
|
||||
- "设计复杂算法..."
|
||||
- "审查这段代码..."
|
||||
- "架构优化建议..."
|
||||
|
||||
### 提供上下文
|
||||
- ✅ 具体约束（"p99 < 100ms"）
|
||||
- ✅ 现有代码示例
|
||||
- ✅ 测试用例
|
||||
- ❌ 模糊描述（"代码很慢"）
|
||||
|
||||
### 有效提问
|
||||
- 问具体问题，避免"怎么优化？"这类宽泛问题
|
||||
- 提供成功标准（"如何达到 <500ms？"）
|
||||
- 说明优先级（"准确性 > 性能"）
|
||||
|
||||
## 故障排除
|
||||
|
||||
**技能未激活？**
|
||||
- 添加触发词："深度分析"、"算法设计"
|
||||
- 明确规模：">10 行逻辑"、"复杂状态机"
|
||||
- 直接说明："我需要 Codex 的帮助..."
|
||||
|
||||
**响应不适用？**
|
||||
- 检查是否传达了所有约束
|
||||
- 验证上下文假设
|
||||
- 请求替代方案或澄清
|
||||
|
||||
**集成问题？**
|
||||
- 遵循 REFERENCE.md 中的集成指南
|
||||
- 先在隔离环境测试
|
||||
- 准备回滚计划
|
||||
|
||||
## 版本历史
|
||||
|
||||
- **v2.0** (2025-11-05): 精简重构
|
||||
- 大幅减少文档冗余
|
||||
- 明确 MCP 工具调用方法
|
||||
- 优化使用体验
|
||||
- **v1.0** (2025-11-05): 初始发布
|
||||
|
||||
## 许可证
|
||||
|
||||
CCode 技能插件的一部分。
|
||||
584
codex-mcp/REFERENCE.md
Normal file
584
codex-mcp/REFERENCE.md
Normal file
@@ -0,0 +1,584 @@
|
||||
# Codex MCP 参考指南
|
||||
|
||||
完整的技术参考文档，包含集成指南、协作模式和 MCP 工具规范。
|
||||
|
||||
---
|
||||
|
||||
## 第一部分：集成指南
|
||||
|
||||
### 集成流程
|
||||
|
||||
```
|
||||
接收建议 → 验证逻辑 → 计划集成 → 分阶段实施 → 测试验证 → 监控测量
|
||||
```
|
||||
|
||||
### 阶段 1: 验证
|
||||
|
||||
#### 1.1 逻辑验证
|
||||
检查清单：
|
||||
- [ ] 算法正确性已验证（手动追踪或证明）
|
||||
- [ ] 覆盖边界情况
|
||||
- [ ] 确认复杂度分析
|
||||
- [ ] 记录所有假设
|
||||
|
||||
#### 1.2 兼容性检查
|
||||
- [ ] 语言版本兼容性
|
||||
- [ ] 库依赖可用性
|
||||
- [ ] 平台兼容性（OS、架构）
|
||||
- [ ] 识别现有代码集成点
|
||||
- [ ] 评估破坏性变更
|
||||
|
||||
兼容性矩阵：
|
||||
| 方面 | Codex 假设 | 你的环境 | 兼容？ | 所需操作 |
|
||||
|------|-----------|----------|--------|----------|
|
||||
| 语言 | Rust 1.75 | Rust 1.70 | ✗ | 升级或适配 |
|
||||
| 库 | tokio 1.35 | tokio 1.28 | ⚠️ | 测试兼容性 |
|
||||
| 平台 | Unix | 跨平台 | ✗ | 添加 Windows 支持 |
|
||||
|
||||
#### 1.3 性能验证
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod codex_validation {
|
||||
use super::*;
|
||||
use std::time::Instant;
|
||||
|
||||
#[test]
|
||||
fn validate_codex_performance() {
|
||||
let input = generate_test_data(10_000);
|
||||
let start = Instant::now();
|
||||
let result = codex_suggested_function(&input);
|
||||
let duration = start.elapsed();
|
||||
|
||||
// 验证声称的性能
|
||||
assert!(duration.as_millis() < 100, "应 <100ms 完成");
|
||||
assert!(result.is_correct(), "结果必须正确");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 阶段 2: 集成策略
|
||||
|
||||
#### 风险评估
|
||||
| 风险级别 | 标准 | 缓解策略 |
|
||||
|----------|------|----------|
|
||||
| **低** | 非关键代码，易回滚 | 直接实施 |
|
||||
| **中** | 影响多个组件 | 功能标志 + 分阶段推出 |
|
||||
| **高** | 关键路径，难回滚 | 影子模式 + 广泛测试 |
|
||||
| **关键** | 财务/安全影响 | 完全审计 + 渐进迁移 |
|
||||
|
||||
#### 策略选择
|
||||
|
||||
**直接集成**（低风险）：
|
||||
```rust
|
||||
fn old_implementation() -> Result<Output> {
|
||||
// Codex 的改进实现
|
||||
new_implementation()
|
||||
}
|
||||
```
|
||||
|
||||
**并行实现**（中等风险）：
|
||||
```rust
|
||||
fn process_data(input: &Input) -> Result<Output> {
|
||||
if feature_flag_enabled() {
|
||||
new_implementation(input)
|
||||
} else {
|
||||
old_implementation(input)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**影子模式**（高风险）：
|
||||
```rust
|
||||
fn process_data(input: &Input) -> Result<Output> {
|
||||
let result = old_implementation(input);
|
||||
|
||||
tokio::spawn(async move {
|
||||
match new_implementation(input).await {
|
||||
Ok(shadow_result) => {
|
||||
if result != shadow_result {
|
||||
log::warn!("影子实现不同: {:?}", shadow_result);
|
||||
}
|
||||
metrics::record_shadow_latency();
|
||||
}
|
||||
Err(e) => {
|
||||
log::error!("影子实现失败: {}", e);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
result
|
||||
}
|
||||
```
|
||||
|
||||
### 阶段 3: 测试策略
|
||||
|
||||
**测试金字塔**：
|
||||
```
|
||||
┌─────────────┐
|
||||
│ 手动 │ ← 复杂场景
|
||||
│ 测试 │
|
||||
├─────────────┤
|
||||
│ 集成 │ ← API/组件测试
|
||||
│ 测试 │
|
||||
├─────────────┤
|
||||
│ 单元 │ ← 算法正确性
|
||||
│ 测试 │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
**必须测试**：
|
||||
- [ ] 单元测试（所有绿色）
|
||||
- [ ] 集成测试
|
||||
- [ ] 性能基准（满足目标）
|
||||
- [ ] 延迟改进 __%
|
||||
- [ ] 吞吐量增加 __%
|
||||
- [ ] 内存使用在限制内
|
||||
- [ ] 负载测试（30+ 分钟）
|
||||
- [ ] 错误处理验证
|
||||
|
||||
### 阶段 4: 监控
|
||||
|
||||
**关键指标**：
|
||||
```markdown
|
||||
- **延迟**: p50, p95, p99, max
|
||||
- **吞吐量**: requests/second
|
||||
- **错误率**: errors/total requests
|
||||
- **资源使用**: CPU, memory, disk I/O
|
||||
```
|
||||
|
||||
**警报配置**：
|
||||
```yaml
|
||||
alerts:
|
||||
- name: LatencyIncrease
|
||||
condition: p99_latency > baseline * 1.5
|
||||
action: notify_team
|
||||
|
||||
- name: ErrorRateSpike
|
||||
condition: error_rate > baseline * 2
|
||||
action: auto_rollback
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第二部分：协作模式
|
||||
|
||||
### 常用模式速查
|
||||
|
||||
| 任务类型 | 最佳模式 | 关键成功因素 |
|
||||
|----------|----------|--------------|
|
||||
| 新算法 | 迭代优化 | 明确约束 |
|
||||
| 系统扩展 | 扩展规划 | 当前指标 |
|
||||
| 性能问题 | 度量-分析-优化 | 分析数据 |
|
||||
| 代码审查 | 重构提案 | 质量目标 |
|
||||
| 架构选择 | 权衡矩阵 | 评估标准 |
|
||||
|
||||
### 核心模式
|
||||
|
||||
#### 1. 迭代优化
|
||||
**场景**：设计多约束的复杂算法
|
||||
```markdown
|
||||
阶段1: "这里是朴素解决方案。请分析其复杂度。"
|
||||
阶段2: "O(n²) 太慢，建议 O(n log n) 的优化。"
|
||||
阶段3: "能否将空间复杂度从 O(n) 降至 O(1)？"
|
||||
```
|
||||
|
||||
#### 2. 瓶颈分析
|
||||
**场景**：系统性能在负载下退化
|
||||
```markdown
|
||||
**当前架构**: [图表]
|
||||
**指标**:
|
||||
- 95th 百分位延迟: 2s
|
||||
- CPU 利用率: 80%
|
||||
- 内存: 4GB/8GB
|
||||
|
||||
**问题**: 瓶颈在哪里？如何优化？
|
||||
```
|
||||
|
||||
#### 3. 权衡矩阵
|
||||
**场景**：存在多种架构选项
|
||||
```markdown
|
||||
**选项**:
|
||||
1. 微服务
|
||||
2. 模块化单体
|
||||
3. 事件驱动
|
||||
|
||||
**标准**: 性能、可维护性、团队规模、时间线
|
||||
|
||||
**问题**: 为我们的约束创建权衡矩阵。
|
||||
```
|
||||
|
||||
### 反模式
|
||||
|
||||
❌ **模糊问题陈述**
|
||||
```markdown
|
||||
错误: "我的代码很慢。怎么修复？"
|
||||
|
||||
正确: "processData() 函数处理 10K 记录需要 5s。
|
||||
分析显示 80% 时间在嵌套循环中。
|
||||
目标: <500ms。这是代码..."
|
||||
```
|
||||
|
||||
❌ **缺少上下文**
|
||||
```markdown
|
||||
错误: "审查这个函数的 bug。" [仅函数代码]
|
||||
|
||||
正确: "审查这个认证函数：
|
||||
- 用于公共 API
|
||||
- 处理 1K req/min
|
||||
- 对安全性至关重要
|
||||
- 必须使用 JWT 令牌"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第三部分：MCP 工具规范
|
||||
|
||||
### Codex MCP 工具
|
||||
|
||||
#### 开启 Codex 会话
|
||||
|
||||
**工具名称**：`mcp__codex-mcp-tool__codex`
|
||||
|
||||
**完整调用示例**：
|
||||
```json
|
||||
{
|
||||
"name": "mcp__codex-mcp-tool__codex",
|
||||
"parameters": {
|
||||
"model": "gpt-5.1-codex",
|
||||
"sandbox": "danger-full-access",
|
||||
"approval-policy": "on-failure",
|
||||
"prompt": "<任务描述>",
|
||||
"cwd": "<可选：工作目录>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**：
|
||||
- `model`（必需）：模型选择，推荐 `"gpt-5.1-codex"` 或 `"gpt-5.1"`
|
||||
- `sandbox`（必需）：沙盒模式
|
||||
- `"read-only"` - 仅读取
|
||||
- `"workspace-write"` - 可写入工作区
|
||||
- `"danger-full-access"` - 完全访问
|
||||
- `approval-policy`（必需）：审批策略
|
||||
- `"untrusted"` - 无需审批
|
||||
- `"on-failure"` - 失败时审批
|
||||
- `"on-request"` - 按需审批
|
||||
- `"never"` - 从不审批
|
||||
- `prompt`（必需）：任务描述
|
||||
- `cwd`（可选）：工作目录路径
|
||||
|
||||
**返回值**：
|
||||
```json
|
||||
{
|
||||
"conversationId": "<字符串>",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
⚠️ **重要**：保存返回的 `conversationId` 用于后续对话。
|
||||
|
||||
#### 继续 Codex 会话
|
||||
|
||||
**工具名称**：`mcp__codex-mcp-tool__codex-reply`
|
||||
|
||||
**完整调用示例**：
|
||||
```json
|
||||
{
|
||||
"name": "mcp__codex-mcp-tool__codex-reply",
|
||||
"parameters": {
|
||||
"conversationId": "<上步返回的 conversationId>",
|
||||
"prompt": "<补充问题或新指令>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**：
|
||||
- `conversationId`（必需）：会话标识符
|
||||
- `prompt`（必需）：新的提示或问题
|
||||
|
||||
---
|
||||
|
||||
### MCP 标准结构
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "tool_name",
|
||||
"description": "此工具的功能和使用时机",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"param1": {
|
||||
"type": "string",
|
||||
"description": "参数描述"
|
||||
}
|
||||
},
|
||||
"required": ["param1"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 字段要求
|
||||
|
||||
**name**（必需）：
|
||||
- 格式：snake_case 或 kebab-case
|
||||
- 在服务器内必须唯一
|
||||
- 示例：`"analyze_code"`, `"run-benchmark"`
|
||||
|
||||
**description**（推荐）：
|
||||
- 包括：功能、时机、返回值
|
||||
- 示例：`"在分析指标时使用。执行 SQL 查询。返回 JSON。"`
|
||||
|
||||
**inputSchema**（必需）：
|
||||
- JSON Schema（Draft 7+）
|
||||
- 必须指定：type、properties、required 字段
|
||||
|
||||
### 端点
|
||||
|
||||
#### 1. 列出工具 (`tools/list`)
|
||||
```json
|
||||
请求: {"method": "tools/list"}
|
||||
|
||||
响应:
|
||||
{
|
||||
"tools": [
|
||||
{"name": "tool1", "description": "...", "inputSchema": {...}},
|
||||
{"name": "tool2", "description": "...", "inputSchema": {...}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 调用工具 (`tools/call`)
|
||||
```json
|
||||
请求:
|
||||
{
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "tool_name",
|
||||
"arguments": {"param1": "value1"}
|
||||
}
|
||||
}
|
||||
|
||||
响应:
|
||||
{
|
||||
"content": [{"type": "text", "text": "结果..."}],
|
||||
"isError": false
|
||||
}
|
||||
```
|
||||
|
||||
### 工具类别
|
||||
|
||||
#### 代码分析
|
||||
```json
|
||||
{
|
||||
"name": "analyze_code",
|
||||
"description": "执行静态分析。识别 bug、性能问题、安全漏洞。",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {"type": "string"},
|
||||
"language": {"type": "string", "enum": ["rust", "python"]},
|
||||
"checks": {"type": "array", "items": {"type": "string"}}
|
||||
},
|
||||
"required": ["code", "language"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 性能测试
|
||||
```json
|
||||
{
|
||||
"name": "run_benchmark",
|
||||
"description": "执行性能基准测试。Codex 建议优化时使用。",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"function_name": {"type": "string"},
|
||||
"iterations": {"type": "integer", "minimum": 1}
|
||||
},
|
||||
"required": ["function_name", "iterations"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 测试执行
|
||||
```json
|
||||
{
|
||||
"name": "run_tests",
|
||||
"description": "执行测试套件。验证实现时使用。",
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"test_path": {"type": "string"},
|
||||
"coverage": {"type": "boolean"}
|
||||
},
|
||||
"required": ["test_path"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 最佳实践
|
||||
|
||||
#### 1. 工具发现
|
||||
当 Codex 推荐工具时：
|
||||
1. 列出可用工具：`tools/list`
|
||||
2. 验证工具存在
|
||||
3. 检查 inputSchema 要求
|
||||
4. 准备参数
|
||||
|
||||
#### 2. 参数准备
|
||||
**错误**：缺少必需参数
|
||||
```json
|
||||
{"name": "analyze_code", "arguments": {"code": "..."}}
|
||||
```
|
||||
|
||||
**正确**：所有必需参数
|
||||
```json
|
||||
{
|
||||
"name": "analyze_code",
|
||||
"arguments": {
|
||||
"code": "fn main() {...}",
|
||||
"language": "rust"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 错误处理
|
||||
```rust
|
||||
match call_mcp_tool("analyze_code", args) {
|
||||
Ok(result) => send_to_codex(result),
|
||||
Err(e) if e.is_invalid_args() => {
|
||||
let fixed = fix_arguments(args);
|
||||
call_mcp_tool("analyze_code", fixed)?
|
||||
}
|
||||
Err(e) => report_tool_failure(e)
|
||||
}
|
||||
```
|
||||
|
||||
### 安全与权限
|
||||
|
||||
#### 权限配置
|
||||
在交接中指定允许的工具：
|
||||
|
||||
```markdown
|
||||
## 可用 MCP 工具
|
||||
|
||||
**允许**:
|
||||
- code_analyzer: 是（只读）
|
||||
- run_benchmark: 是（安全测试）
|
||||
|
||||
**不允许**:
|
||||
- execute_query: 否（不需要数据访问）
|
||||
- system_command: 否（安全限制）
|
||||
```
|
||||
|
||||
#### 安全约束
|
||||
```json
|
||||
{
|
||||
"tool_constraints": {
|
||||
"code_analyzer": {
|
||||
"max_code_size": 10000,
|
||||
"allowed_languages": ["rust", "python"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
### MCP 工具调用检查表
|
||||
```
|
||||
□ 工具存在 (tools/list)
|
||||
□ inputSchema 已审查
|
||||
□ 必需参数已准备
|
||||
□ 权限已确认
|
||||
□ 错误处理已就绪
|
||||
□ 结果解释计划
|
||||
```
|
||||
|
||||
### 集成检查清单
|
||||
```
|
||||
验证:
|
||||
□ 算法正确性
|
||||
□ 兼容性
|
||||
□ 性能声明
|
||||
|
||||
规划:
|
||||
□ 风险评估
|
||||
□ 集成策略
|
||||
□ 回滚计划
|
||||
|
||||
实施:
|
||||
□ 功能分支
|
||||
□ 隔离测试
|
||||
□ 分阶段集成
|
||||
□ 文档更新
|
||||
```
|
||||
|
||||
### 常用模板
|
||||
|
||||
#### 标准任务交接
|
||||
```markdown
|
||||
## 任务给 Codex
|
||||
|
||||
**背景**: [项目/系统简要描述]
|
||||
**目标**: [清晰的目标陈述]
|
||||
**约束**: [性能/安全/兼容性要求]
|
||||
**当前状态**: [现有实现或尝试]
|
||||
|
||||
### 具体问题:
|
||||
1. [第一个问题]
|
||||
2. [第二个问题]
|
||||
|
||||
### 期望交付:
|
||||
- [ ] 设计文档/伪代码
|
||||
- [ ] 实现策略
|
||||
- [ ] 测试用例
|
||||
- [ ] 性能分析
|
||||
```
|
||||
|
||||
#### 算法设计
|
||||
```markdown
|
||||
**问题陈述**: [描述问题]
|
||||
**输入格式**: [数据结构与约束]
|
||||
**输出要求**: [期望结果格式]
|
||||
**性能约束**:
|
||||
- 时间复杂度: O(?)
|
||||
- 空间复杂度: O(?)
|
||||
**测试用例**:
|
||||
1. 输入: [...] → 期望: [...]
|
||||
2. 边界情况: [...] → 期望: [...]
|
||||
```
|
||||
|
||||
#### 架构评审
|
||||
```markdown
|
||||
**系统概览**: [高层描述]
|
||||
**组件**:
|
||||
- 组件 A: [用途和交互]
|
||||
- 组件 B: [用途和交互]
|
||||
**当前挑战**:
|
||||
1. [挑战 1]
|
||||
2. [挑战 2]
|
||||
**扩展要求**:
|
||||
- 当前负载: [指标]
|
||||
- 预期增长: [预测]
|
||||
**分析问题**:
|
||||
1. [具体架构关注点]
|
||||
2. [性能优化机会]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 版本信息
|
||||
|
||||
**版本**: 2.0 | **更新**: 2025-11-05
|
||||
|
||||
合并了以下文档：
|
||||
- INTEGRATION_GUIDE.md (v1.0)
|
||||
- CODEX_PATTERNS.md (v1.0)
|
||||
- MCP_TOOLS_SPEC.md (v1.0)
|
||||
|
||||
---
|
||||
|
||||
返回 [SKILL.md](SKILL.md) 以获取主要文档。
|
||||
190
codex-mcp/SKILL.md
Normal file
190
codex-mcp/SKILL.md
Normal file
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: codex-mcp
|
||||
description: 调用 Codex 进行深度分析、复杂逻辑设计和代码审查。使用场景：>10行核心逻辑、架构设计、性能优化、关键代码审查。提供标准的 MCP 工具调用接口和协作模板。
|
||||
---
|
||||
|
||||
# Codex MCP 协作
|
||||
|
||||
本技能通过标准 MCP（Model Context Protocol）工具调用接口，协作 Codex 处理复杂技术任务。
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 触发条件
|
||||
满足以下任一条件时激活：
|
||||
- 需要设计或优化 >10 行核心逻辑的算法
|
||||
- 请求架构评审、性能优化或安全审计
|
||||
- 涉及数学证明、复杂问题求解
|
||||
- 描述包含 "深度分析"、"复杂逻辑"、"算法设计"、"架构审查" 等关键词
|
||||
|
||||
### 典型应用
|
||||
```markdown
|
||||
"设计一个并发数据处理算法处理 1000 events/sec"
|
||||
"优化这个状态机实现，需要代码审查"
|
||||
"请分析系统架构，支持从 1K 扩展到 10K req/sec"
|
||||
```
|
||||
|
||||
## MCP 工具调用方法
|
||||
|
||||
### 工具初始化
|
||||
|
||||
**MCP 工具名称**：`mcp__codex-mcp-tool__codex`
|
||||
|
||||
**开启会话**（必须设置固定参数）：
|
||||
|
||||
#### 默认模型：gpt-5.1-codex
|
||||
适用于大多数复杂技术任务和分析工作：
|
||||
|
||||
**完整工具调用示例**：
|
||||
```json
|
||||
{
|
||||
"name": "mcp__codex-mcp-tool__codex",
|
||||
"parameters": {
|
||||
"model": "gpt-5.1-codex",
|
||||
"sandbox": "danger-full-access",
|
||||
"approval-policy": "on-failure",
|
||||
"prompt": "<需求描述或任务说明>",
|
||||
"cwd": "<可选：工程路径>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 高级模型：gpt-5.1
|
||||
适用于特别复杂的任务或特殊指定场景：
|
||||
|
||||
**完整工具调用示例**：
|
||||
```json
|
||||
{
|
||||
"name": "mcp__codex-mcp-tool__codex",
|
||||
"parameters": {
|
||||
"model": "gpt-5.1",
|
||||
"sandbox": "danger-full-access",
|
||||
"approval-policy": "on-failure",
|
||||
"prompt": "<需求描述或任务说明>",
|
||||
"cwd": "<可选：工程路径>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回值**：`{ conversationId: "<string>", ... }`
|
||||
|
||||
### 工具调用参数
|
||||
|
||||
#### 必选参数
|
||||
- `model`: 模型选择，支持以下选项：
|
||||
- **"gpt-5.1-codex"**（默认）- 适用于大多数复杂技术任务、算法设计、架构分析
|
||||
- **"gpt-5.1"** - 适用于特别复杂的任务或用户特殊指定，需要更强的推理能力
|
||||
- `prompt`: 任务描述，支持中英文
|
||||
|
||||
**模型选择指南**：
|
||||
- 使用 **gpt-5.1-codex**：>90% 的协作场景（默认推荐）
|
||||
- 使用 **gpt-5.1**：遇到高度复杂的多约束优化、超大规模系统设计、或用户明确指定时
|
||||
- `sandbox`: 沙盒模式
|
||||
- `"read-only"` - 仅读取权限
|
||||
- `"workspace-write"` - 可写入工作区
|
||||
- `"danger-full-access"` - 完全访问权限
|
||||
- `approval-policy`: 命令审批策略
|
||||
- `"untrusted"` - 无需审批
|
||||
- `"on-failure"` - 失败时审批
|
||||
- `"on-request"` - 按需审批
|
||||
- `"never"` - 从不审批
|
||||
|
||||
#### 可选参数
|
||||
- `cwd`: 工作目录
|
||||
- `base-instructions`: 基础指令
|
||||
- `compact-prompt`: 紧凑提示模式
|
||||
- `developer-instructions`: 开发者指令
|
||||
- `config`: 配置对象覆盖
|
||||
|
||||
### 继续对话
|
||||
|
||||
**MCP 工具名称**：`mcp__codex-mcp-tool__codex-reply`
|
||||
|
||||
**完整工具调用示例**：
|
||||
```json
|
||||
{
|
||||
"name": "mcp__codex-mcp-tool__codex-reply",
|
||||
"parameters": {
|
||||
"conversationId": "<上步返回的 conversationId>",
|
||||
"prompt": "<补充问题或新指令>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
⚠️ **会话管理**：保存返回的 `conversationId`，会话失效时需重新初始化。
|
||||
|
||||
## 协作模板
|
||||
|
||||
### 标准任务模板
|
||||
|
||||
```markdown
|
||||
## 任务给 Codex
|
||||
|
||||
**背景**: [项目/系统简要描述]
|
||||
**目标**: [清晰的目标陈述]
|
||||
**约束**: [性能/安全/兼容性要求]
|
||||
**当前状态**: [现有实现或尝试]
|
||||
|
||||
### 具体问题:
|
||||
1. [第一个问题]
|
||||
2. [第二个问题]
|
||||
|
||||
### 期望交付:
|
||||
- [ ] 设计文档/伪代码
|
||||
- [ ] 实现策略
|
||||
- [ ] 测试用例
|
||||
- [ ] 性能分析
|
||||
```
|
||||
|
||||
### 算法设计请求
|
||||
```markdown
|
||||
## 算法设计
|
||||
|
||||
**问题描述**: [问题陈述]
|
||||
**输入格式**: [数据结构与约束]
|
||||
**输出要求**: [期望结果格式]
|
||||
**性能约束**:
|
||||
- 时间复杂度: O(?)
|
||||
- 空间复杂度: O(?)
|
||||
**测试用例**:
|
||||
1. 输入: [...] → 期望: [...]
|
||||
2. 边界情况: [...] → 期望: [...]
|
||||
```
|
||||
|
||||
### 架构评审请求
|
||||
```markdown
|
||||
## 架构评审
|
||||
|
||||
**系统概览**: [高层描述]
|
||||
**组件**:
|
||||
- 组件A: [用途和交互]
|
||||
- 组件B: [用途和交互]
|
||||
**当前挑战**:
|
||||
1. [挑战1]
|
||||
2. [挑战2]
|
||||
**扩展要求**:
|
||||
- 当前负载: [指标]
|
||||
- 预期增长: [预测]
|
||||
**分析问题**:
|
||||
1. [具体架构关注点]
|
||||
2. [性能优化机会]
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### ✅ 推荐做法
|
||||
- 提供完整的上下文（包括约束和边界情况）
|
||||
- 共享现有代码模式和约定
|
||||
- 明确性能要求
|
||||
- 询问具体、有针对性的问题
|
||||
- 在实施前验证 Codex 的建议
|
||||
|
||||
### ❌ 避免事项
|
||||
- 假设 Codex 了解你的项目结构
|
||||
- 跳过测试 Codex 提出的解决方案
|
||||
- 不理解推理过程就实施
|
||||
- 忘记检查与现有系统的兼容性
|
||||
|
||||
## 参考文档
|
||||
|
||||
- [REFERENCE.md](REFERENCE.md) - 完整集成指南、模式速查和 MCP 工具规范
|
||||
- [HANDOFF_CHECKLIST.md](HANDOFF_CHECKLIST.md) - 任务交接检查清单
|
||||
Reference in New Issue
Block a user