From c6caa36a858a22e9c632117f7219550f6df67593 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:29:56 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 13 + README.md | 3 + codex-mcp/HANDOFF_CHECKLIST.md | 259 +++++++++++++++ codex-mcp/README.md | 168 ++++++++++ codex-mcp/REFERENCE.md | 584 +++++++++++++++++++++++++++++++++ codex-mcp/SKILL.md | 190 +++++++++++ git-commit/README.md | 196 +++++++++++ git-commit/REFERENCE.md | 321 ++++++++++++++++++ git-commit/SKILL.md | 314 ++++++++++++++++++ plugin.lock.json | 69 ++++ 10 files changed, 2117 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 codex-mcp/HANDOFF_CHECKLIST.md create mode 100644 codex-mcp/README.md create mode 100644 codex-mcp/REFERENCE.md create mode 100644 codex-mcp/SKILL.md create mode 100644 git-commit/README.md create mode 100644 git-commit/REFERENCE.md create mode 100644 git-commit/SKILL.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..be4203b --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "ccode-skills", + "description": "ccode 的skills集合", + "version": "0.0.0-2025.11.28", + "author": { + "name": "junjiangao", + "email": "junjiangao@gmail.com" + }, + "skills": [ + "./codex-mcp", + "./git-commit" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b367fdc --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# ccode-skills + +ccode 的skills集合 diff --git a/codex-mcp/HANDOFF_CHECKLIST.md b/codex-mcp/HANDOFF_CHECKLIST.md new file mode 100644 index 0000000..d166fba --- /dev/null +++ b/codex-mcp/HANDOFF_CHECKLIST.md @@ -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) 获取主要文档。 diff --git a/codex-mcp/README.md b/codex-mcp/README.md new file mode 100644 index 0000000..d20eaa0 --- /dev/null +++ b/codex-mcp/README.md @@ -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 技能插件的一部分。 diff --git a/codex-mcp/REFERENCE.md b/codex-mcp/REFERENCE.md new file mode 100644 index 0000000..a6c5dd0 --- /dev/null +++ b/codex-mcp/REFERENCE.md @@ -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 { + // Codex 的改进实现 + new_implementation() +} +``` + +**并行实现**（中等风险）： +```rust +fn process_data(input: &Input) -> Result { + if feature_flag_enabled() { + new_implementation(input) + } else { + old_implementation(input) + } +} +``` + +**影子模式**（高风险）： +```rust +fn process_data(input: &Input) -> Result { + 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) 以获取主要文档。 diff --git a/codex-mcp/SKILL.md b/codex-mcp/SKILL.md new file mode 100644 index 0000000..a1bfee1 --- /dev/null +++ b/codex-mcp/SKILL.md @@ -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: "", ... }` + +### 工具调用参数 + +#### 必选参数 +- `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) - 任务交接检查清单 diff --git a/git-commit/README.md b/git-commit/README.md new file mode 100644 index 0000000..4b53e43 --- /dev/null +++ b/git-commit/README.md @@ -0,0 +1,196 @@ +# Git Commit 技能 + +智能化的 Git 提交助手，帮助你快速完成代码审查、生成规范的提交信息并执行提交。 + +## 🚀 快速开始 + +### 基本使用 + +``` +你: "帮我提交这些代码" +``` + +技能会自动： +1. ✅ 检查暂存区状态 +2. 🔍 简单代码审查 +3. 📊 分析提交历史 +4. 📝 生成提交信息 +5. ✋ 等待你确认 +6. 🎉 执行提交 + +### 使用场景 + +#### 场景 1：暂存区已有文件 +```bash +# 你已经执行了 git add +git add src/main.rs src/config.rs + +# 直接请求提交 +你: "提交代码" +``` + +技能会直接使用暂存区的文件进行提交。 + +#### 场景 2：暂存区为空 +``` +你: "提交我的修改" +``` + +技能会： +1. 列出所有修改的文件 +2. 询问你要提交哪些文件 +3. 自动执行 `git add` +4. 继续提交流程 + +#### 场景 3：审查并提交 +``` +你: "审查代码并提交" +``` + +技能会进行简单的代码审查，检查： +- 语法错误 +- 调试代码残留 +- 敏感信息泄露 + +## 📝 提交信息格式 + +### 自动识别项目规范 + +技能会从以下来源识别项目的提交规范： +1. **Memory 中的项目规范**（优先级最高） +2. **提交历史中的风格模式** +3. **通用简洁格式**（默认） + +### 配置项目规范 + +如果你的项目有特定的提交规范，可以在 Memory 中记录： + +``` +你: "记录项目提交规范：使用 Conventional Commits 格式，type 包括 feat、fix、docs、refactor、test、chore" +``` + +技能会自动保存到 Memory，后续提交时遵循该规范。 + +## 🎯 典型工作流 + +### 完整示例 + +``` +你: "提交代码" + +技能: +📊 检查到暂存区为空，发现以下修改： + 1. src/main.rs (修改) + 2. src/config.rs (修改) + 3. tests/test_config.rs (新增) + 4. README.md (修改) + +请选择要提交的文件： + [ ] 提交所有文件 + [ ] 选择特定文件 + [ ] 取消 + +你: "提交所有文件" + +技能: +✅ 已添加 4 个文件到暂存区 + +🔍 代码审查中... +✅ 未发现明显问题 + +📊 变更摘要： + - 修改文件：4 个 + - 新增行：+127 + - 删除行：-23 + +📝 提交信息： + feat(config): 添加 TOML 配置支持 + + - 实现 TOML 配置读取 + - 添加配置文件解析 + - 更新测试用例 + - 完善文档说明 + +是否确认提交？ + +你: "确认" + +技能: +✅ 提交成功！ + commit: a1b2c3d feat(config): 添加 TOML 配置支持 +``` + +## ⚙️ 高级功能 + +### 历史分析 + +技能会分析最近 20 条提交记录，学习项目的提交风格： +- 常用的 type 类型 +- scope 的命名习惯 +- 提交信息的语言（中文/英文） +- 描述的详细程度 + +### 智能暂存区处理 + +- **暂存区非空**：直接使用，快速提交 +- **暂存区为空**：智能询问，避免误操作 + +### 提交前确认 + +每次提交前都会展示： +- 变更文件列表和统计 +- 生成的提交信息 +- 代码审查结果 + +你可以： +- 确认提交 +- 修改提交信息 +- 取消提交 + +## 🛠️ 配置示例 + +### Conventional Commits 规范 + +``` +你: "配置提交规范" + +技能: "请描述你的提交规范" + +你: "使用 Conventional Commits： +- type: feat, fix, docs, refactor, test, chore +- 格式: type(scope): subject +- subject 使用中文 +- 可选的详细正文" + +技能: "✅ 已保存到项目 Memory" +``` + +### 自定义规范 + +``` +你: "我们团队的提交格式是：[模块名] 简短描述" + +技能: "✅ 已记录，后续提交将遵循该格式" +``` + +## 💡 最佳实践 + +### ✅ 推荐做法 + +1. **原子提交**：每次只提交一个逻辑变更 +2. **及时提交**：完成功能点后立即提交 +3. **清晰描述**：让他人快速理解变更目的 +4. **遵循规范**：保持项目风格一致 + +### ❌ 避免事项 + +1. **混合变更**：不要在一次提交中包含多个不相关修改 +2. **模糊描述**：避免 "update code"、"fix bug" 等无意义信息 +3. **跳过审查**：即使小改动也应快速检查 +4. **提交敏感信息**：检查是否包含密钥、令牌 + +## 🔗 相关资源 + +- 详细工作流程：查看 `SKILL.md` +- 提交规范参考：查看 `REFERENCE.md` +- [Conventional Commits 规范](https://www.conventionalcommits.org/) diff --git a/git-commit/REFERENCE.md b/git-commit/REFERENCE.md new file mode 100644 index 0000000..bf83d3d --- /dev/null +++ b/git-commit/REFERENCE.md @@ -0,0 +1,321 @@ +# Git Commit 规范参考 + +本文档提供常见的提交信息规范、Memory 配置模板和常见问题解答。 + +## 📋 提交信息规范 + +### Conventional Commits + +最流行的提交信息规范，广泛应用于开源项目。 + +#### 格式 +``` +(): + + + +