@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/multi-plan.md

@@ -0,0 +1,278 @@
+# 计划 - 多模型协同规划
+
+多模型协同规划 - 上下文检索 + 双模型分析 → 生成分步实施计划。
+
+$ARGUMENTS
+
+***
+
+## 核心协议
+
+* **语言协议**：与工具/模型交互时使用 **英语**，与用户沟通时使用其语言
+* **强制并行**：Codex/Gemini 调用 **必须** 使用 `run_in_background: true`（包括单模型调用，以避免阻塞主线程）
+* **代码主权**：外部模型 **零文件系统写入权限**，所有修改由 Claude 执行
+* **止损机制**：在当前阶段输出验证完成前，不进入下一阶段
+* **仅限规划**：此命令允许读取上下文并写入 `.claude/plan/*` 计划文件，但 **绝不修改生产代码**
+
+***
+
+## 多模型调用规范
+
+**调用语法**（并行：使用 `run_in_background: true`）：
+
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
+ROLE_FILE: <role prompt path>
+<TASK>
+Requirement: <enhanced requirement>
+Context: <retrieved project context>
+</TASK>
+OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
+EOF",
+  run_in_background: true,
+  timeout: 3600000,
+  description: "Brief description"
+})
+```
+
+**模型参数说明**：
+
+* `{{GEMINI_MODEL_FLAG}}`: 当使用 `--backend gemini` 时，替换为 `--gemini-model gemini-3-pro-preview`（注意尾随空格）；对于 codex 使用空字符串
+
+**角色提示**：
+
+| 阶段 | Codex | Gemini |
+|-------|-------|--------|
+| 分析 | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
+| 规划 | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
+
+**会话复用**：每次调用返回 `SESSION_ID: xxx`（通常由包装器输出），**必须保存** 供后续 `/ccg:execute` 使用。
+
+**等待后台任务**（最大超时 600000ms = 10 分钟）：
+
+```
+TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
+```
+
+**重要提示**：
+
+* 必须指定 `timeout: 600000`，否则默认 30 秒会导致过早超时
+* 如果 10 分钟后仍未完成，继续使用 `TaskOutput` 轮询，**绝不终止进程**
+* 如果因超时而跳过等待，**必须调用 `AskUserQuestion` 询问用户是继续等待还是终止任务**
+
+***
+
+## 执行流程
+
+**规划任务**：$ARGUMENTS
+
+### 阶段 1：完整上下文检索
+
+`[Mode: Research]`
+
+#### 1.1 提示增强（必须先执行）
+
+**如果 ace-tool MCP 可用**，调用 `mcp__ace-tool__enhance_prompt` 工具：
+
+```
+mcp__ace-tool__enhance_prompt({
+  prompt: "$ARGUMENTS",
+  conversation_history: "<last 5-10 conversation turns>",
+  project_root_path: "$PWD"
+})
+```
+
+等待增强后的提示，**将所有后续阶段的原始 $ARGUMENTS 替换为增强结果**。
+
+**如果 ace-tool MCP 不可用**：跳过此步骤，并在所有后续阶段直接使用原始的 `$ARGUMENTS`。
+
+#### 1.2 上下文检索
+
+**如果 ace-tool MCP 可用**，调用 `mcp__ace-tool__search_context` 工具：
+
+```
+mcp__ace-tool__search_context({
+  query: "<基于增强需求的语义查询>",
+  project_root_path: "$PWD"
+})
+```
+
+* 使用自然语言构建语义查询（在哪里/是什么/怎么样）
+* **切勿基于假设回答**
+
+**如果 ace-tool MCP 不可用**，使用 Claude Code 内置工具作为备用方案：
+
+1. **Glob**：通过模式查找相关文件（例如，`Glob("**/*.ts")`、`Glob("src/**/*.py")`）
+2. **Grep**：搜索关键符号、函数名、类定义（例如，`Grep("className|functionName")`）
+3. **Read**：读取发现的文件以收集完整的上下文
+4. **Task (Explore agent)**：要进行更深入的探索，使用 `Task` 并配合 `subagent_type: "Explore"` 来搜索整个代码库
+
+#### 1.3 完整性检查
+
+* 必须获取相关类、函数、变量的 **完整定义和签名**
+* 如果上下文不足，触发 **递归检索**
+* 输出优先级：入口文件 + 行号 + 关键符号名称；仅在必要时添加最小代码片段以消除歧义
+
+#### 1.4 需求对齐
+
+* 如果需求仍有歧义，**必须** 输出引导性问题给用户
+* 直到需求边界清晰（无遗漏，无冗余）
+
+### 阶段 2：多模型协同分析
+
+`[Mode: Analysis]`
+
+#### 2.1 分发输入
+
+**并行调用** Codex 和 Gemini（`run_in_background: true`）：
+
+将 **原始需求**（不预设观点）分发给两个模型：
+
+1. **Codex 后端分析**：
+   * ROLE\_FILE：`~/.claude/.ccg/prompts/codex/analyzer.md`
+   * 重点：技术可行性、架构影响、性能考虑、潜在风险
+   * 输出：多视角解决方案 + 优缺点分析
+
+2. **Gemini 前端分析**：
+   * ROLE\_FILE：`~/.claude/.ccg/prompts/gemini/analyzer.md`
+   * 重点：UI/UX 影响、用户体验、视觉设计
+   * 输出：多视角解决方案 + 优缺点分析
+
+使用 `TaskOutput` 等待两个模型的完整结果。**保存 SESSION\_ID**（`CODEX_SESSION` 和 `GEMINI_SESSION`）。
+
+#### 2.2 交叉验证
+
+整合视角并迭代优化：
+
+1. **识别共识**（强信号）
+2. **识别分歧**（需要权衡）
+3. **互补优势**：后端逻辑遵循 Codex，前端设计遵循 Gemini
+4. **逻辑推理**：消除解决方案中的逻辑漏洞
+
+#### 2.3（可选但推荐）双模型计划草案
+
+为减少 Claude 综合计划中的遗漏风险，可以并行让两个模型输出“计划草案”（仍然 **不允许** 修改文件）：
+
+1. **Codex 计划草案**（后端权威）：
+   * ROLE\_FILE：`~/.claude/.ccg/prompts/codex/architect.md`
+   * 输出：分步计划 + 伪代码（重点：数据流/边缘情况/错误处理/测试策略）
+
+2. **Gemini 计划草案**（前端权威）：
+   * ROLE\_FILE：`~/.claude/.ccg/prompts/gemini/architect.md`
+   * 输出：分步计划 + 伪代码（重点：信息架构/交互/可访问性/视觉一致性）
+
+使用 `TaskOutput` 等待两个模型的完整结果，记录它们建议的关键差异。
+
+#### 2.4 生成实施计划（Claude 最终版本）
+
+综合两个分析，生成 **分步实施计划**：
+
+```markdown
+## 实施计划：<任务名称>
+
+### 任务类型
+- [ ] 前端 (→ Gemini)
+- [ ] 后端 (→ Codex)
+- [ ] 全栈 (→ 并行)
+
+### 技术解决方案
+<基于 Codex + Gemini 分析得出的最优解决方案>
+
+### 实施步骤
+1. <步骤 1> - 预期交付物
+2. <步骤 2> - 预期交付物
+...
+
+### 关键文件
+| 文件 | 操作 | 描述 |
+|------|-----------|-------------|
+| path/to/file.ts:L10-L50 | 修改 | 描述 |
+
+### 风险与缓解措施
+| 风险 | 缓解措施 |
+|------|------------|
+
+### SESSION_ID (供 /ccg:execute 使用)
+- CODEX_SESSION: <session_id>
+- GEMINI_SESSION: <session_id>
+
+```
+
+### 阶段 2 结束：计划交付（非执行）
+
+**`/ccg:plan` 的职责到此结束，必须执行以下操作**：
+
+1. 向用户呈现完整的实施计划（包括伪代码）
+
+2. 将计划保存到 `.claude/plan/<feature-name>.md`（从需求中提取功能名称，例如 `user-auth`，`payment-module`）
+
+3. 以 **粗体文本** 输出提示（必须使用实际保存的文件路径）：
+
+***
+
+**计划已生成并保存至 `.claude/plan/actual-feature-name.md`**
+
+**请审阅以上计划。您可以：**
+
+* **修改计划**：告诉我需要调整的内容，我会更新计划
+* **执行计划**：复制以下命令到新会话
+
+   ```
+   /ccg:execute .claude/plan/actual-feature-name.md
+   ```
+
+***
+
+**注意**：上面的 `actual-feature-name.md` 必须替换为实际保存的文件名！
+
+4. **立即终止当前响应**（在此停止。不再进行工具调用。）
+
+**绝对禁止**：
+
+* 询问用户“是/否”然后自动执行（执行是 `/ccg:execute` 的职责）
+* 任何对生产代码的写入操作
+* 自动调用 `/ccg:execute` 或任何实施操作
+* 当用户未明确请求修改时继续触发模型调用
+
+***
+
+## 计划保存
+
+规划完成后，将计划保存至：
+
+* **首次规划**：`.claude/plan/<feature-name>.md`
+* **迭代版本**：`.claude/plan/<feature-name>-v2.md`，`.claude/plan/<feature-name>-v3.md`...
+
+计划文件写入应在向用户呈现计划前完成。
+
+***
+
+## 计划修改流程
+
+如果用户请求修改计划：
+
+1. 根据用户反馈调整计划内容
+2. 更新 `.claude/plan/<feature-name>.md` 文件
+3. 重新呈现修改后的计划
+4. 提示用户再次审阅或执行
+
+***
+
+## 后续步骤
+
+用户批准后，**手动** 执行：
+
+```bash
+/ccg:execute .claude/plan/<feature-name>.md
+```
+
+***
+
+## 关键规则
+
+1. **仅规划，不实施** – 此命令不执行任何代码更改
+2. **无是/否提示** – 仅呈现计划，让用户决定后续步骤
+3. **信任规则** – 后端遵循 Codex，前端遵循 Gemini
+4. 外部模型 **零文件系统写入权限**
+5. **SESSION\_ID 交接** – 计划末尾必须包含 `CODEX_SESSION` / `GEMINI_SESSION`（供 `/ccg:execute resume <SESSION_ID>` 使用）

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/plan.md

@@ -0,0 +1,118 @@
+---
+description: 重新阐述需求、评估风险并创建分步实施计划。在接触任何代码之前，等待用户确认。
+---
+
+# 计划命令
+
+此命令调用 **planner** 代理，在编写任何代码之前创建一个全面的实施计划。
+
+## 此命令的作用
+
+1. **重新阐述需求** - 明确需要构建什么
+2. **识别风险** - 揭示潜在问题和阻碍
+3. **创建分步计划** - 将实施分解为多个阶段
+4. **等待确认** - 必须获得用户批准才能继续
+
+## 何时使用
+
+在以下情况下使用 `/plan`：
+
+* 开始新功能时
+* 进行重大架构变更时
+* 处理复杂重构时
+* 多个文件/组件将受到影响时
+* 需求不明确或存在歧义时
+
+## 工作原理
+
+planner 代理将：
+
+1. **分析请求** 并用清晰的术语重新阐述需求
+2. **分解为多个阶段**，每个阶段包含具体、可操作的步骤
+3. **识别组件之间的依赖关系**
+4. **评估风险和潜在阻碍**
+5. **估算复杂度**（高/中/低）
+6. **展示计划**并等待您明确的确认
+
+## 使用示例
+
+```
+User: /plan 我需要为市场结算时添加实时通知功能
+
+Agent (planner):
+# 实施计划：实时市场结算通知
+
+## 需求重述
+- 当用户关注的市场结算时，向用户发送通知
+- 支持多种通知渠道（应用内、电子邮件、Webhook）
+- 确保通知可靠送达
+- 包含市场结果和用户持仓结果
+
+## 实施阶段
+
+### 第一阶段：数据库架构
+- 添加 notifications 表，包含列：id, user_id, market_id, type, status, created_at
+- 添加 user_notification_preferences 表用于存储渠道偏好设置
+- 在 user_id 和 market_id 上创建索引以提升性能
+
+### 第二阶段：通知服务
+- 在 lib/notifications.ts 中创建通知服务
+- 使用 BullMQ/Redis 实现通知队列
+- 为发送失败的情况添加重试逻辑
+- 创建通知模板
+
+### 第三阶段：集成点
+- 接入市场结算逻辑（当状态变为 "resolved" 时）
+- 查询在市场中有持仓的所有用户
+- 为每个用户将通知加入队列
+
+### 第四阶段：前端组件
+- 在头部创建 NotificationBell 组件
+- 添加 NotificationList 模态框
+- 通过 Supabase 订阅实现实时更新
+- 添加通知偏好设置页面
+
+## 依赖项
+- Redis（用于队列）
+- 电子邮件服务（SendGrid/Resend）
+- Supabase 实时订阅
+
+## 风险
+- 高：电子邮件送达率（需要配置 SPF/DKIM）
+- 中：市场用户超过 1000+ 时的性能问题
+- 中：市场频繁结算可能导致通知泛滥
+- 低：实时订阅开销
+
+## 预估复杂度：中
+- 后端：4-6 小时
+- 前端：3-4 小时
+- 测试：2-3 小时
+- 总计：9-13 小时
+
+**等待确认**：是否按此计划进行？（是/否/修改）
+```
+
+## 重要说明
+
+**关键**：planner 代理在您明确用“是”、“继续”或类似的肯定性答复确认计划之前，**不会**编写任何代码。
+
+如果您希望修改，请回复：
+
+* "修改：\[您的修改内容]"
+* "不同方法：\[替代方案]"
+* "跳过阶段 2，先执行阶段 3"
+
+## 与其他命令的集成
+
+计划之后：
+
+* 使用 `/tdd` 通过测试驱动开发来实现
+* 如果出现构建错误，请使用 `/build-fix`
+* 使用 `/code-review` 来审查已完成的实现
+
+## 相关代理
+
+此命令调用由 ECC 提供的 `planner` 代理。
+
+对于手动安装，源文件位于：
+`agents/planner.md`

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/pm2.md

@@ -0,0 +1,283 @@
+# PM2 初始化
+
+自动分析项目并生成 PM2 服务命令。
+
+**命令**: `$ARGUMENTS`
+
+***
+
+## 工作流程
+
+1. 检查 PM2（如果缺失，通过 `npm install -g pm2` 安装）
+2. 扫描项目以识别服务（前端/后端/数据库）
+3. 生成配置文件和各命令文件
+
+***
+
+## 服务检测
+
+| 类型 | 检测方式 | 默认端口 |
+|------|-----------|--------------|
+| Vite | vite.config.\* | 5173 |
+| Next.js | next.config.\* | 3000 |
+| Nuxt | nuxt.config.\* | 3000 |
+| CRA | package.json 中的 react-scripts | 3000 |
+| Express/Node | server/backend/api 目录 + package.json | 3000 |
+| FastAPI/Flask | requirements.txt / pyproject.toml | 8000 |
+| Go | go.mod / main.go | 8080 |
+
+**端口检测优先级**: 用户指定 > .env 文件 > 配置文件 > 脚本参数 > 默认端口
+
+***
+
+## 生成的文件
+
+```
+project/
+├── ecosystem.config.cjs              # PM2 配置文件
+├── {backend}/start.cjs               # Python 包装器（如适用）
+└── .claude/
+    ├── commands/
+    │   ├── pm2-all.md                # 启动所有 + 监控
+    │   ├── pm2-all-stop.md           # 停止所有
+    │   ├── pm2-all-restart.md        # 重启所有
+    │   ├── pm2-{port}.md             # 启动单个 + 日志
+    │   ├── pm2-{port}-stop.md        # 停止单个
+    │   ├── pm2-{port}-restart.md     # 重启单个
+    │   ├── pm2-logs.md               # 查看所有日志
+    │   └── pm2-status.md             # 查看状态
+    └── scripts/
+        ├── pm2-logs-{port}.ps1       # 单个服务日志
+        └── pm2-monit.ps1             # PM2 监控器
+```
+
+***
+
+## Windows 配置（重要）
+
+### ecosystem.config.cjs
+
+**必须使用 `.cjs` 扩展名**
+
+```javascript
+module.exports = {
+  apps: [
+    // Node.js (Vite/Next/Nuxt)
+    {
+      name: 'project-3000',
+      cwd: './packages/web',
+      script: 'node_modules/vite/bin/vite.js',
+      args: '--port 3000',
+      interpreter: 'C:/Program Files/nodejs/node.exe',
+      env: { NODE_ENV: 'development' }
+    },
+    // Python
+    {
+      name: 'project-8000',
+      cwd: './backend',
+      script: 'start.cjs',
+      interpreter: 'C:/Program Files/nodejs/node.exe',
+      env: { PYTHONUNBUFFERED: '1' }
+    }
+  ]
+}
+```
+
+**框架脚本路径:**
+
+| 框架 | script | args |
+|-----------|--------|------|
+| Vite | `node_modules/vite/bin/vite.js` | `--port {port}` |
+| Next.js | `node_modules/next/dist/bin/next` | `dev -p {port}` |
+| Nuxt | `node_modules/nuxt/bin/nuxt.mjs` | `dev --port {port}` |
+| Express | `src/index.js` 或 `server.js` | - |
+
+### Python 包装脚本 (start.cjs)
+
+```javascript
+const { spawn } = require('child_process');
+const proc = spawn('python', ['-m', 'uvicorn', 'app.main:app', '--host', '0.0.0.0', '--port', '8000', '--reload'], {
+  cwd: __dirname, stdio: 'inherit', windowsHide: true
+});
+proc.on('close', (code) => process.exit(code));
+```
+
+***
+
+## 命令文件模板（最简内容）
+
+### pm2-all.md (启动所有 + 监控)
+
+````markdown
+启动所有服务并打开 PM2 监控器。
+```bash
+cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 monit"
+```
+````
+
+### pm2-all-stop.md
+
+````markdown
+停止所有服务。
+```bash
+cd "{PROJECT_ROOT}" && pm2 stop all
+```
+````
+
+### pm2-all-restart.md
+
+````markdown
+重启所有服务。
+```bash
+cd "{PROJECT_ROOT}" && pm2 restart all
+```
+````
+
+### pm2-{port}.md (启动单个 + 日志)
+
+````markdown
+启动 {name} ({port}) 并打开日志。
+```bash
+cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs --only {name} && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 logs {name}"
+```
+````
+
+### pm2-{port}-stop.md
+
+````markdown
+停止 {name} ({port})。
+```bash
+cd "{PROJECT_ROOT}" && pm2 stop {name}
+```
+````
+
+### pm2-{port}-restart.md
+
+````markdown
+重启 {name} ({port})。
+```bash
+cd "{PROJECT_ROOT}" && pm2 restart {name}
+```
+````
+
+### pm2-logs.md
+
+````markdown
+查看所有 PM2 日志。
+```bash
+cd "{PROJECT_ROOT}" && pm2 logs
+```
+````
+
+### pm2-status.md
+
+````markdown
+查看 PM2 状态。
+```bash
+cd "{PROJECT_ROOT}" && pm2 status
+```
+````
+
+### PowerShell 脚本 (pm2-logs-{port}.ps1)
+
+```powershell
+Set-Location "{PROJECT_ROOT}"
+pm2 logs {name}
+```
+
+### PowerShell 脚本 (pm2-monit.ps1)
+
+```powershell
+Set-Location "{PROJECT_ROOT}"
+pm2 monit
+```
+
+***
+
+## 关键规则
+
+1. **配置文件**: `ecosystem.config.cjs` (不是 .js)
+2. **Node.js**: 直接指定 bin 路径 + 解释器
+3. **Python**: Node.js 包装脚本 + `windowsHide: true`
+4. **打开新窗口**: `start wt.exe -d "{path}" pwsh -NoExit -c "command"`
+5. **最简内容**: 每个命令文件只有 1-2 行描述 + bash 代码块
+6. **直接执行**: 无需 AI 解析，直接运行 bash 命令
+
+***
+
+## 执行
+
+基于 `$ARGUMENTS`，执行初始化：
+
+1. 扫描项目服务
+2. 生成 `ecosystem.config.cjs`
+3. 为 Python 服务生成 `{backend}/start.cjs`（如果适用）
+4. 在 `.claude/commands/` 中生成命令文件
+5. 在 `.claude/scripts/` 中生成脚本文件
+6. **更新项目 CLAUDE.md**，添加 PM2 信息（见下文）
+7. **显示完成摘要**，包含终端命令
+
+***
+
+## 初始化后：更新 CLAUDE.md
+
+生成文件后，将 PM2 部分追加到项目的 `CLAUDE.md`（如果不存在则创建）：
+
+````markdown
+## PM2 服务
+
+| 端口 | 名称 | 类型 |
+|------|------|------|
+| {port} | {name} | {type} |
+
+**终端命令：**
+```bash
+pm2 start ecosystem.config.cjs   # First time
+pm2 start all                    # After first time
+pm2 stop all / pm2 restart all
+pm2 start {name} / pm2 stop {name}
+pm2 logs / pm2 status / pm2 monit
+pm2 save                         # Save process list
+pm2 resurrect                    # Restore saved list
+```
+````
+
+**更新 CLAUDE.md 的规则：**
+
+* 如果存在 PM2 部分，替换它
+* 如果不存在，追加到末尾
+* 保持内容精简且必要
+
+***
+
+## 初始化后：显示摘要
+
+所有文件生成后，输出：
+
+```
+## PM2 初始化完成
+
+**服务列表：**
+
+| 端口 | 名称 | 类型 |
+|------|------|------|
+| {port} | {name} | {type} |
+
+**Claude 指令：** /pm2-all, /pm2-all-stop, /pm2-{port}, /pm2-{port}-stop, /pm2-logs, /pm2-status
+
+**终端命令：**
+## 首次运行（使用配置文件）
+pm2 start ecosystem.config.cjs && pm2 save
+
+## 首次之后（简化命令）
+pm2 start all          # 启动全部
+pm2 stop all           # 停止全部
+pm2 restart all        # 重启全部
+pm2 start {name}       # 启动单个
+pm2 stop {name}        # 停止单个
+pm2 logs               # 查看日志
+pm2 monit              # 监控面板
+pm2 resurrect          # 恢复已保存进程
+
+**提示：** 首次启动后运行 `pm2 save` 以启用简化命令。
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/projects.md

@@ -0,0 +1,39 @@
+---
+name: projects
+description: 列出已知项目及其本能统计数据
+command: true
+---
+
+# 项目命令
+
+列出项目注册条目以及每个项目的本能/观察计数，适用于 continuous-learning-v2。
+
+## 实现
+
+使用插件根路径运行本能 CLI：
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
+```
+
+或者如果 `CLAUDE_PLUGIN_ROOT` 未设置（手动安装）：
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
+```
+
+## 用法
+
+```bash
+/projects
+```
+
+## 操作步骤
+
+1. 读取 `~/.claude/homunculus/projects.json`
+2. 对于每个项目，显示：
+   * 项目名称、ID、根目录、远程地址
+   * 个人和继承的本能计数
+   * 观察事件计数
+   * 最后看到的时间戳
+3. 同时显示全局本能总数