From 97c7cb8bc68dc4decbbd4ae695c1f01f4b6fbd97 Mon Sep 17 00:00:00 2001 From: li Date: Tue, 13 Jan 2026 14:24:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=B2=BE=E7=AE=80=E5=91=BD=E4=BB=A4?= =?UTF-8?q?=E6=A8=A1=E6=9D=BF=E5=8E=BB=E9=99=A4=E5=86=97=E4=BD=99=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E5=9D=97=20(v1.7.19)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 统一所有调用外部模型的命令模板格式 - 顶部保留完整调用规范，阶段中只引用不重复 - 添加 ⚠️ 必须调用标记确保强制执行 - 修改文件：backend/frontend/debug/optimize/review/test/analyze.md --- CHANGELOG.md | 83 ++++++++++++++++++++++++++++++++++ codeagent-wrapper/executor.go | 33 ++++++++++---- codeagent-wrapper/main.go | 2 +- package.json | 2 +- templates/commands/analyze.md | 11 +++-- templates/commands/backend.md | 20 ++++++-- templates/commands/debug.md | 11 +++-- templates/commands/frontend.md | 20 ++++++-- templates/commands/optimize.md | 11 +++-- templates/commands/review.md | 11 +++-- templates/commands/test.md | 13 ++++-- 11 files changed, 178 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4112c0..7a4ae39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- +## [1.7.19] - 2026-01-13 + +### 📝 文档优化 + +**精简命令模板，去除冗余代码块** + +所有调用外部模型的命令模板已统一格式： +- 顶部保留完整的「多模型调用规范」代码示例（只出现一次） +- 各阶段改为 `⚠️ 必须调用 xxx（参照上方调用规范）` + 参数表格 +- 避免重复教学，减少模板体积 + +**修改文件**： +- `templates/commands/backend.md` - 阶段 2、3、5 精简 +- `templates/commands/frontend.md` - 阶段 2、3、5 精简 +- `templates/commands/debug.md` - 阶段 2 精简 +- `templates/commands/optimize.md` - 阶段 2 精简 +- `templates/commands/review.md` - 阶段 2 精简 +- `templates/commands/test.md` - 阶段 2 精简 +- `templates/commands/analyze.md` - 阶段 2 添加 ⚠️ 强调标记 + +--- + +## [1.7.18] - 2026-01-13 + +### 🐛 Bug 修复 + +**修复 Windows 系统 Codex 进程无法自动终止问题** + +#### 问题背景 + +用户在 Windows 系统上使用 Codex 时遇到问题： +- Codex 任务实际已完成（Web 界面显示完成，输出了 `agent_message` 和 `turn.completed`） +- 但 codeagent-wrapper 进程一直不退出 +- 导致 Claude Code Task 工具无法获取日志，一直等待 +- 只有手动关闭进程才能继续 + +**根本原因**： +- `terminateCommand` 函数使用 `syscall.SIGTERM` 信号终止进程 +- **Windows 不支持 SIGTERM 信号**，该调用静默失败（不报错但不执行任何操作） +- 虽然有 `forceKillDelay` 后的 `Kill()` 备用逻辑，但代码在 `waitCh` 上阻塞等待进程退出 +- 导致 Kill() 的定时器无法正确触发或进程无法正常退出 + +#### 核心修复 + +1. **Windows 平台直接使用 Kill()**： + - `terminateCommand()` 函数：Windows 上直接调用 `proc.Kill()` 而非 `SIGTERM` + - `terminateProcess()` 函数：同样的修复 + - `forwardSignals()` 函数：同样的修复 + +2. **保持 Unix 兼容性**： + - Unix/Linux/macOS 仍使用 `SIGTERM` 实现优雅退出 + - 保留 `forceKillDelay` 后的强制 Kill 逻辑 + +#### 技术细节 + +修改文件：`codeagent-wrapper/executor.go` + +```go +// 修复前 +_ = proc.Signal(syscall.SIGTERM) + +// 修复后 +if isWindows() { + _ = proc.Kill() // Windows: 直接终止 +} else { + _ = proc.Signal(syscall.SIGTERM) // Unix: 优雅退出 +} +``` + +#### 影响范围 + +- ✅ **修复前**：Windows 用户 Codex 完成后进程卡住，需要手动终止 +- ✅ **修复后**：所有平台进程正确终止，Task 工具可以正常获取结果 +- ✅ **向后兼容**：Unix 平台行为不变 + +#### 相关文件 + +- `codeagent-wrapper/executor.go` - 修改 3 个函数的信号处理逻辑 +- `codeagent-wrapper/main.go` - 版本号升级至 v5.5.0 +- 重新编译所有平台二进制文件 + +--- + ## [1.7.17] - 2026-01-12 ### 🐛 Bug 修复 diff --git a/codeagent-wrapper/executor.go b/codeagent-wrapper/executor.go index 0a26deb..45c1dcc 100644 --- a/codeagent-wrapper/executor.go +++ b/codeagent-wrapper/executor.go @@ -1256,12 +1256,17 @@ func forwardSignals(ctx context.Context, cmd commandRunner, logErrorFn func(stri case sig := <-sigCh: logErrorFn(fmt.Sprintf("Received signal: %v", sig)) if proc := cmd.Process(); proc != nil { - _ = proc.Signal(syscall.SIGTERM) - time.AfterFunc(time.Duration(forceKillDelay.Load())*time.Second, func() { - if p := cmd.Process(); p != nil { - _ = p.Kill() - } - }) + // Windows does not support SIGTERM - use Kill() directly + if isWindows() { + _ = proc.Kill() + } else { + _ = proc.Signal(syscall.SIGTERM) + time.AfterFunc(time.Duration(forceKillDelay.Load())*time.Second, func() { + if p := cmd.Process(); p != nil { + _ = p.Kill() + } + }) + } } case <-ctx.Done(): } @@ -1326,7 +1331,14 @@ func terminateCommand(cmd commandRunner) *forceKillTimer { return nil } - _ = proc.Signal(syscall.SIGTERM) + // Windows does not support SIGTERM - it silently fails without terminating the process. + // This causes codeagent-wrapper to hang waiting for the process to exit. + // On Windows, we directly use Kill() which calls TerminateProcess(). + if isWindows() { + _ = proc.Kill() + } else { + _ = proc.Signal(syscall.SIGTERM) + } done := make(chan struct{}, 1) timer := time.AfterFunc(time.Duration(forceKillDelay.Load())*time.Second, func() { @@ -1348,7 +1360,12 @@ func terminateProcess(cmd commandRunner) *time.Timer { return nil } - _ = proc.Signal(syscall.SIGTERM) + // Windows does not support SIGTERM - use Kill() directly + if isWindows() { + _ = proc.Kill() + } else { + _ = proc.Signal(syscall.SIGTERM) + } return time.AfterFunc(time.Duration(forceKillDelay.Load())*time.Second, func() { if p := cmd.Process(); p != nil { diff --git a/codeagent-wrapper/main.go b/codeagent-wrapper/main.go index d619aa2..d4d8302 100644 --- a/codeagent-wrapper/main.go +++ b/codeagent-wrapper/main.go @@ -14,7 +14,7 @@ import ( ) const ( - version = "5.4.1" + version = "5.5.0" defaultWorkdir = "." defaultTimeout = 7200 // seconds (2 hours) defaultCoverageTarget = 90.0 diff --git a/package.json b/package.json index 9e0d0ed..ff1dcfe 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ccg-workflow", - "version": "1.7.17", + "version": "1.7.19", "description": "Claude-Codex-Gemini 多模型协作系统 - 智能路由多模型开发工作流", "type": "module", "packageManager": "pnpm@10.17.1", diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md index 4edb9e3..afc4033 100644 --- a/templates/commands/analyze.md +++ b/templates/commands/analyze.md @@ -73,11 +73,14 @@ EOF", `[模式：分析]` -**并行调用**（`run_in_background: true`）： -- Codex：使用分析提示词，输出技术可行性、架构影响、性能考量 -- Gemini：使用分析提示词，输出 UI/UX 影响、用户体验、视觉设计考量 +**⚠️ 必须并行调用 Codex 和 Gemini**（参照上方调用规范，使用 `run_in_background: true`）： -用 `TaskOutput` 等待两个模型的完整结果。 +| 模型 | ROLE_FILE | OUTPUT | +|------|-----------|--------| +| **Codex** | `~/.claude/.ccg/prompts/codex/analyzer.md` | 技术可行性、架构影响、性能考量 | +| **Gemini** | `~/.claude/.ccg/prompts/gemini/analyzer.md` | UI/UX 影响、用户体验、视觉设计考量 | + +用 `TaskOutput` 等待两个模型的完整结果。**必须等所有模型返回后才能进入下一阶段**。 ### 🔀 阶段 3：交叉验证 diff --git a/templates/commands/backend.md b/templates/commands/backend.md index f28828b..7367037 100644 --- a/templates/commands/backend.md +++ b/templates/commands/backend.md @@ -99,9 +99,13 @@ EOF", `[模式：构思]` - Codex 主导分析 -调用 Codex，使用分析提示词，输出技术可行性、推荐方案、风险点。 +**⚠️ 必须调用 Codex**（参照上方调用规范）： +- ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md` +- 需求：增强后的需求（如未增强则用 $ARGUMENTS） +- 上下文：阶段 1 收集的项目上下文 +- OUTPUT: 技术可行性分析、推荐方案（至少 2 个）、风险点评估 -**📌 保存 SESSION_ID**（`CODEX_SESSION`）。 +**📌 保存 SESSION_ID**（`CODEX_SESSION`）用于后续阶段复用。 输出方案（至少 2 个），等待用户选择。 @@ -109,7 +113,11 @@ EOF", `[模式：计划]` - Codex 主导规划 -调用 Codex（`resume $CODEX_SESSION`），使用规划提示词，输出文件结构、函数/类设计、依赖。 +**⚠️ 必须调用 Codex**（使用 `resume ` 复用会话）： +- ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md` +- 需求：用户选择的方案 +- 上下文：阶段 2 的分析结果 +- OUTPUT: 文件结构、函数/类设计、依赖关系 Claude 综合规划，请求用户批准后存入 `.claude/plan/任务名.md` @@ -125,7 +133,11 @@ Claude 综合规划，请求用户批准后存入 `.claude/plan/任务名.md` `[模式：优化]` - Codex 主导审查 -调用 Codex，使用审查提示词，关注安全性、性能、错误处理、API规范。 +**⚠️ 必须调用 Codex**（参照上方调用规范）： +- ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md` +- 需求：审查以下后端代码变更 +- 上下文：git diff 或代码内容 +- OUTPUT: 安全性、性能、错误处理、API 规范问题列表 整合审查意见，用户确认后执行优化。 diff --git a/templates/commands/debug.md b/templates/commands/debug.md index 6224e5f..64385cd 100644 --- a/templates/commands/debug.md +++ b/templates/commands/debug.md @@ -64,11 +64,14 @@ EOF", `[模式：诊断]` -**并行调用**（`run_in_background: true`）： -- Codex：分析逻辑错误、数据流、异常处理、API、数据库 -- Gemini：分析 UI 渲染、状态管理、事件绑定、组件生命周期 +**⚠️ 必须并行调用 Codex 和 Gemini**（参照上方调用规范，使用 `run_in_background: true`）： -用 `TaskOutput` 等待两个模型的诊断结果。 +| 模型 | 需求 | OUTPUT | +|------|------|--------| +| **Codex** | 诊断问题（$ARGUMENTS） | 诊断假设（按可能性排序），每个假设包含原因、证据、修复建议 | +| **Gemini** | 诊断问题（$ARGUMENTS） | 诊断假设（按可能性排序），每个假设包含原因、证据、修复建议 | + +用 `TaskOutput` 等待两个模型的诊断结果。**必须等所有模型返回后才能进入下一阶段**。 ### 🔀 阶段 3：假设整合 diff --git a/templates/commands/frontend.md b/templates/commands/frontend.md index 8732652..6ba8550 100644 --- a/templates/commands/frontend.md +++ b/templates/commands/frontend.md @@ -99,9 +99,13 @@ EOF", `[模式：构思]` - Gemini 主导分析 -调用 Gemini，使用分析提示词，输出 UI 可行性、推荐方案、用户体验。 +**⚠️ 必须调用 Gemini**（参照上方调用规范）： +- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md` +- 需求：增强后的需求（如未增强则用 $ARGUMENTS） +- 上下文：阶段 1 收集的项目上下文 +- OUTPUT: UI 可行性分析、推荐方案（至少 2 个）、用户体验评估 -**📌 保存 SESSION_ID**（`GEMINI_SESSION`）。 +**📌 保存 SESSION_ID**（`GEMINI_SESSION`）用于后续阶段复用。 输出方案（至少 2 个），等待用户选择。 @@ -109,7 +113,11 @@ EOF", `[模式：计划]` - Gemini 主导规划 -调用 Gemini（`resume $GEMINI_SESSION`），使用规划提示词，输出组件结构、UI流程、样式方案。 +**⚠️ 必须调用 Gemini**（使用 `resume ` 复用会话）： +- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md` +- 需求：用户选择的方案 +- 上下文：阶段 2 的分析结果 +- OUTPUT: 组件结构、UI 流程、样式方案 Claude 综合规划，请求用户批准后存入 `.claude/plan/任务名.md` @@ -125,7 +133,11 @@ Claude 综合规划，请求用户批准后存入 `.claude/plan/任务名.md` `[模式：优化]` - Gemini 主导审查 -调用 Gemini，使用审查提示词，关注可访问性、响应式、性能、设计一致性。 +**⚠️ 必须调用 Gemini**（参照上方调用规范）： +- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md` +- 需求：审查以下前端代码变更 +- 上下文：git diff 或代码内容 +- OUTPUT: 可访问性、响应式、性能、设计一致性问题列表 整合审查意见，用户确认后执行优化。 diff --git a/templates/commands/optimize.md b/templates/commands/optimize.md index d590311..1d077ab 100644 --- a/templates/commands/optimize.md +++ b/templates/commands/optimize.md @@ -70,11 +70,14 @@ EOF", `[模式：分析]` -**并行调用**（`run_in_background: true`）： -- Codex：分析后端性能问题，输出瓶颈列表、优化方案、预期收益 -- Gemini：分析前端性能问题（Core Web Vitals），输出瓶颈列表、优化方案、预期收益 +**⚠️ 必须并行调用 Codex 和 Gemini**（参照上方调用规范，使用 `run_in_background: true`）： -用 `TaskOutput` 等待两个模型的完整结果。 +| 模型 | 需求 | OUTPUT | +|------|------|--------| +| **Codex** | 分析后端性能问题（$ARGUMENTS） | 性能瓶颈列表、优化方案、预期收益 | +| **Gemini** | 分析前端性能问题（Core Web Vitals）（$ARGUMENTS） | 性能瓶颈列表、优化方案、预期收益 | + +用 `TaskOutput` 等待两个模型的完整结果。**必须等所有模型返回后才能进入下一阶段**。 ### 🔀 阶段 3：优化整合 diff --git a/templates/commands/review.md b/templates/commands/review.md index 4290b9e..34a3e39 100644 --- a/templates/commands/review.md +++ b/templates/commands/review.md @@ -56,11 +56,14 @@ EOF", `[模式：审查]` -**并行调用**（`run_in_background: true`）： -- Codex：审查安全性、性能、错误处理、可维护性 -- Gemini：审查可访问性、响应式、设计一致性、用户体验 +**⚠️ 必须并行调用 Codex 和 Gemini**（参照上方调用规范，使用 `run_in_background: true`）： -用 `TaskOutput` 等待两个模型的审查结果。 +| 模型 | 需求 | OUTPUT | +|------|------|--------| +| **Codex** | 审查代码变更（git diff 内容） | 按 Critical/Major/Minor/Suggestion 分类列出安全性、性能、错误处理问题 | +| **Gemini** | 审查代码变更（git diff 内容） | 按 Critical/Major/Minor/Suggestion 分类列出可访问性、响应式、设计一致性问题 | + +用 `TaskOutput` 等待两个模型的审查结果。**必须等所有模型返回后才能进入下一阶段**。 ### 🔀 阶段 3：综合反馈 diff --git a/templates/commands/test.md b/templates/commands/test.md index ed84cac..36fe0be 100644 --- a/templates/commands/test.md +++ b/templates/commands/test.md @@ -83,12 +83,15 @@ EOF", `[模式：生成]` -**根据代码类型路由**： -- 后端代码：调用 Codex 生成测试 -- 前端代码：调用 Gemini 生成测试 -- 全栈代码：并行调用两者（`run_in_background: true`） +**⚠️ 根据代码类型必须调用对应模型**（参照上方调用规范）： -用 `TaskOutput` 等待模型返回测试代码。 +| 代码类型 | 调用模型 | OUTPUT | +|----------|----------|--------| +| **后端** | Codex | 完整测试代码（使用项目现有测试框架，覆盖正常路径、边界条件、异常处理） | +| **前端** | Gemini | 完整测试代码（使用项目现有测试框架，覆盖正常路径、边界条件、异常处理） | +| **全栈** | 并行调用两者（`run_in_background: true`） | 后端 + 前端测试代码 | + +**必须等所有模型返回后才能进入下一阶段**。 ### 🔀 阶段 3：测试整合