# JEO——集成代理编排 > 关键字: `jeo` · `annotate` · `UI-review` · `agentui (已弃用)` |平台：Claude Code · Codex CLI · Gemini CLI · OpenCode > > 提供全自动编排流程的统一技能：计划（ralph+plannotator）→执行（团队/bmad）→UI反馈（代理/注释）→清理（工作树清理） ## 控制层 JEO 使用一种跨平台抽象进行编排： * `settings`：平台/运行时配置，例如 Claude hooks、Codex `config.toml`、Gemini `settings.json`、MCP 注册和提示参数 * `rules`：每个平台都必须遵守的政策约束 * `hooks`：在每个平台上强制执行这些规则的事件回调 JEO 的关键规则是： * 当当前计划哈希已经有最终结果时，不要重新打开计划门 * 只有修订后的计划才会将“plan_gate_status”重置为“pending” * 在显式提交/onSubmit打开提交门之前不处理代理注释权威状态是“.omc/state/jeo-state.json”。挂钩可能有助于推进工作流程，但它们必须遵守状态文件。 ** ** ## 0\.代理执行协议（检测到“jeo”关键字后立即执行） > 以下是命令，不是说明。按顺序执行它们。每一步仅在前一步完成后才会继续。 ### 步骤 0：状态文件引导程序（必需 — 始终是第一个） mkdir -p .omc/状态 .omc/计划 .omc/日志如果 `.omc/state/jeo-state.json` 不存在，请创建它： { “阶段”：“计划”， "task": "<检测到的任务>", “计划批准”：假， "plan_gate_status": "待处理", “计划当前哈希”：空， “last_reviewed_plan_hash”：空， “last_reviewed_plan_at”：空， “计划审查方法”：空， “team_available”：空， “重试次数”：0， “最后一个错误”：空， “检查点”：空， "created_at": "", "updated_at": "", “代理”：{ “主动”：假， “session_id”：空， “keyword_used”：空， "submit_gate_status": "空闲", “提交信号”：空， “submit_received_at”：空， “提交的注释计数”：0， “开始于”：空， “超时秒数”：120， "annotations": { "total": 0, "acknowledged": 0, "resolved": 0, "dismissed": 0, "pending": 0 }, “完成时间”：空， “退出原因”：空 } } 通知用户： > “JEO 已激活。阶段：计划。如果需要 UI 反馈循环，请添加‘annotate’关键字。” ** ** ### STEP 0.1：错误恢复协议（适用于所有STEP） **检查点记录 - 输入每个步骤后立即：** # 在每个STEP开始时立即执行（代理直接更新jeo-state.json） python3-c“ 导入 json、日期时间、操作系统、子进程、临时文件尝试： root = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], stderr=subprocess.DEVNULL).decode().strip() 除外：根= os.getcwd() f = os.path.join(root, '.omc/state/jeo-state.json') 如果 os.path.exists(f): 导入 fcntl 将 open(f, 'r+') 作为 fh： fcntl.flock(fh, fcntl.LOCK_EX) 尝试： d = json.load(fh) d['checkpoint']='' # '计划'|'执行'|'验证'|'清理' d['updated_at']=datetime.datetime.utcnow().isoformat()+'Z' fh.seek(0) json.dump(d, fh, Ensure_ascii=False, 缩进=2) fh.truncate() 最后： fcntl.flock(fh, fcntl.LOCK_UN) " 2>/dev/null ||真的 **last_error 记录 — 飞行前失败或异常时：** python3-c“ 导入 json、日期时间、操作系统、子进程、fcntl 尝试： root = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], stderr=subprocess.DEVNULL).decode().strip() 除外：根= os.getcwd() f = os.path.join(root, '.omc/state/jeo-state.json') 如果 os.path.exists(f): 将 open(f, 'r+') 作为 fh： fcntl.flock(fh, fcntl.LOCK_EX) 尝试： d = json.load(fh) d['last_error']='<错误消息>' d['重试次数']=d.get('重试次数',0)+1 d['updated_at']=datetime.datetime.utcnow().isoformat()+'Z' fh.seek(0) json.dump(d, fh, Ensure_ascii=False, 缩进=2) fh.truncate() 最后： fcntl.flock(fh, fcntl.LOCK_UN) " 2>/dev/null ||真实 **重新启动时基于检查点的恢复：** # 如果jeo-state.json已经存在，则从检查点恢复 python3-c“ 导入 json、操作系统、子进程尝试： root = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], stderr=subprocess.DEVNULL).decode().strip() 除外：根= os.getcwd() f = os.path.join(root, '.omc/state/jeo-state.json') 如果 os.path.exists(f): d=json.load(打开(f)) cp=d.get('检查点') err=d.get('最后一个错误') if err: print(f'上一个错误：{err}') if cp: print(f'从：{cp}'恢复') " 2>/dev/null ||真实 > **规则** ：在飞行前的“exit 1”之前，始终更新“last_error”并增加“retry_count”。如果`retry_count >= 3`，询问用户是否中止。 ** ** ### 第 1 步：计划（切勿跳过） **飞行前（进入前需要）：** # 记录检查点 python3-c“ 导入 json、日期时间、操作系统、子进程、fcntl、临时文件尝试： root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() 除外： root=os.getcwd() f=os.path.join(root,'.omc/state/jeo-state.json') 如果 os.path.exists(f): 将 open(f,'r+') 作为 fh： fcntl.flock(fh,fcntl.LOCK_EX) 尝试： d=json.load(fh) d.update({'checkpoint':'plan','updated_at':datetime.datetime.utcnow().isoformat()+'Z'}) fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() 最后： fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null ||真实 # 注意：Claude Code — 跳过整个 bash 块。 # plannotator 是一个仅钩子的二进制文件；直接调用总是失败。 # 对于 Claude 代码：调用 EnterPlanMode → 编写计划 → 调用 ExitPlanMode。 # ExitPlanMode PermissionRequest 挂钩会自动触发 plannotator。 # 以下脚本仅适用于 Codex / Gemini / OpenCode。 # GUARD：通过计划哈希强制执行无重复计划审查。 # 相同的哈希 + 终端门状态 => 跳过重新打开计划门 # 修改后的 plan.md 内容 => 将 gateway 重置为待处理并再次审核 PLAN_GATE_STATUS=$(python3 -c " 导入json，操作系统尝试： s = json.load(open('.omc/state/jeo-state.json')) print(s.get('plan_gate_status', '待处理')) 除了例外：打印（'待处理'） " 2>/dev/null || echo "待处理") HASH_MATCH=$(python3 -c " 导入 hashlib、json、操作系统尝试： s = json.load(open('.omc/state/jeo-state.json')) 如果不是 os.path.exists('plan.md'): print('不匹配') 其他： current_hash = hashlib.sha256(open('plan.md', 'rb').read()).hexdigest() print('match' if current_hash == (s.get('last_reviewed_plan_hash') or '') else 'no-match') 除了例外： print('不匹配') " 2>/dev/null || echo "不匹配") if [[ "$HASH_MATCH" == "匹配" && "$PLAN_GATE_STATUS" =~ ^(approved|manual_approved|feedback_required|infrastruction_blocked)$ ]];然后 echo "✅ 当前计划哈希已经有门结果：$PLAN_GATE_STATUS。不要重新打开 plannotator。" 出口0 菲 # plannotator 对于 PLAN 步骤是必需的 (Codex/Gemini/OpenCode)。 # 如果丢失，JEO 会在打开 PLAN 门之前自动安装它。 # 解析 JEO 脚本目录（适用于任何 CWD） _JEO_SCRIPTS="" 对于 \ 中的 _candidate “${JEO_SKILL_DIR:-}/脚本”\ “$HOME/.agent-skills/jeo/scripts”\ “$HOME/.codex/skills/jeo/scripts”\ “$(pwd)/.agent-skills/jeo/scripts”\ “脚本”\ ;做 if [ -f "${_candidate}/plannotator-plan-loop.sh" ];然后 _JEO_SCRIPTS="$_candidate" 打破菲完成如果[-z“$_JEO_SCRIPTS”];然后 echo“❌未找到JEO脚本。重新运行：bash setup-codex.sh（或setup-gemini.sh）” 1号出口菲如果！ bash "${_JEO_SCRIPTS}/ensure-plannotator.sh";然后 echo“❌ plannotator 自动安装失败：无法继续执行计划步骤。” echo "重试：bash ${_JEO_SCRIPTS}/../scripts/install.sh --with-plannotator" 1号出口菲 # 所需的计划门（Codex / Gemini / OpenCode）： # - 必须等到收到批准/反馈 # - 会话退出时自动重新启动（最多 3 次） # - 3退出后询问用户是否结束PLAN FEEDBACK_DIR=$(python3 -c "import hashlib,os; h=hashlib.md5(os.getcwd().encode()).hexdigest()[:8]; d=f'/tmp/jeo-{h}'; os.makedirs(d,exist_ok=True); print(d)" 2>/dev/null || echo '/tmp') FEEDBACK_FILE="${FEEDBACK_DIR}/plannotator_feedback.txt" bash "${_JEO_SCRIPTS}/plannotator-plan-loop.sh" plan.md "$FEEDBACK_FILE" 3 计划_RC = $？如果[“$PLAN_RC”-eq 0];然后 echo "✅ 计划已获批准" elif [“$PLAN_RC”-eq 10];然后 echo“❌计划未获批准 - 应用反馈，修改 plan.md，然后重试” 1号出口 elif [“$PLAN_RC”-eq 32];然后 echo“⚠️ plannotator UI 不可用（沙盒/CI）。进入对话批准模式：” echo " 1. 在对话中向用户输出 plan.md 内容" echo " 2.询问用户：'批准'以继续或提供反馈" echo " 3. 在用户明确批准之前不要继续执行" 32号出口 elif [“$PLAN_RC”-eq 30] || [“$PLAN_RC”-eq 31];然后 echo“⛔计划退出决定（或等待确认）。在重试之前与用户确认。” 1号出口否则 echo "❌ plannotator PLAN 门失败 (code=$PLAN_RC)" 1号出口菲 mkdir -p .omc/计划 .omc/日志 1. 编写`plan.md`（包括目标、步骤、风险和完成标准） 2. **调用 plannotator**（每个平台）： * **Claude Code（挂钩模式 - 仅受支持的方法）**：`plannotator` 是仅挂钩的二进制文件。不能通过 MCP 工具或 CLI 直接调用。调用`EnterPlanMode`，在计划模式下写入计划内容，然后调用`ExitPlanMode`。 `ExitPlanMode` PermissionRequest 挂钩会自动触发 JEO Claude plan-gate 包装器。当当前计划哈希已经具有最终审查结果时，该包装器必须跳过重新输入。等待挂钩返回，然后再继续 - 批准或反馈将通过挂钩结果到达。 * **Codex / Gemini / OpenCode** ：运行阻塞 CLI（切勿使用 `&`）： # _JEO_SCRIPTS 必须首先通过上面预飞行中的动态路径发现块来解析 bash "${_JEO_SCRIPTS}/plannotator-plan-loop.sh" plan.md /tmp/plannotator_feedback.txt 3 如果缺少 `plannotator`，JEO 必须首先自动运行 `bash "${_JEO_SCRIPTS}/ensure-plannotator.sh"`，并仅在 CLI 可用后继续。 3. 检查结果： * `approved: true` (Claude Code: hook 返回approved) → 将 `jeo-state.json` `phase` 更新为 `"execute"` 并将 `plan_approved` 更新为 `true` → **进入第 2 步** * 未批准（克劳德代码：hook返回反馈；其他：`exit 10`）→阅读反馈，修改`plan.md`→重复步骤2 * 基础设施被阻止（`exit 32`）→ 本地主机绑定不可用（例如，沙箱/CI）。在 TTY 中使用手动门；与用户确认并在非 TTY 中的沙箱外重试 * 会话退出 3 次 (`exit 30/31`) → 询问用户是否结束 PLAN 并决定中止或恢复 **从不：在没有“approved: true”的情况下输入 EXECUTE。从不：以“&”背景运行。** **从不：在“approved”、“manual_approved”、“feedback_required”或“infrastruction_blocked”后重新打开相同的未更改计划。** ** ** ### 第 2 步：执行 **飞行前（自动检测团队可用性）：** # 记录检查点 python3-c“ 导入 json、日期时间、操作系统、子进程、fcntl 尝试： root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() 除外： root=os.getcwd() f=os.path.join(root,'.omc/state/jeo-state.json') 如果 os.path.exists(f): 将 open(f,'r+') 作为 fh： fcntl.flock(fh,fcntl.LOCK_EX) 尝试： d=json.load(fh) d.update({'checkpoint':'执行','updated_at':datetime.datetime.utcnow().isoformat()+'Z'}) fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() 最后： fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null ||真实 TEAM_AVAILABLE=假 if [[ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}" =~ ^(1|true|True|yes|YES)$ ]];然后 TEAM_AVAILABLE=true elif python3 -c“ 导入 json、操作系统、系统尝试： s = json.load(open(os.path.expanduser('~/.claude/settings.json'))) val = s.get('env', {}).get('CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS', '') sys.exit(0 if str(val) in ('1', 'true', 'True', 'yes') else 1) 除了例外：系统退出(1) " 2>/dev/null;然后 TEAM_AVAILABLE=true 菲导出 TEAM_AVAILABLE_BOOL="$TEAM_AVAILABLE" python3-c“ 导入 json、os、子进程、fcntl 尝试： root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() 除外： root=os.getcwd() f=os.path.join(root,'.omc/state/jeo-state.json') 如果 os.path.exists(f): 将 open(f,'r+') 作为 fh： fcntl.flock(fh,fcntl.LOCK_EX) 尝试： d=json.load(fh) d['team_available']=os.environ.get('TEAM_AVAILABLE_BOOL','false').lower()=='true' fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() 最后： fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null ||真实 1. 将 `jeo-state.json` `phase` 更新为 `"execute"` 2. **可用团队（Claude Code + omc）**： /omc:团队 3:执行者“<任务>” 3. **克劳德·代码但没有团队**： echo "❌ JEO需要Claude Code团队模式。重新运行bash脚本/setup-claude.sh，重新启动Claude Code，并确认CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。" 1号出口永远不要退回到 Claude Code 中的单代理执行。 4. **无 omc（BMAD 后备 — 仅 Codex/Gemini/OpenCode）**： /workflow-init # 初始化 BMAD /workflow-status # 检查当前步骤 ** ** ### 第 3 步：验证 1. 将 `jeo-state.json` `phase` 更新为 `"verify"` 2. **使用代理浏览器进行基本验证**（当存在浏览器 UI 时）：代理浏览器快照 http://localhost:3000 3. 检测到“注释”关键字 → **进入步骤 3.1** 4. 否则 → **进入第 4 步** ** ** ### 步骤 3.1：VERIFY_UI（仅当检测到“annotate”关键字时） 1. 飞行前检查（入境前需要）： # 自动启动服务器、自动安装包、自动注入组件（完整脚本请参见§3.3.1） bash 脚本/ensure-agentation.sh --project-dir "${PROJECT_DIR:-$PWD}" --endpoint "http://localhost:4747" ||真实 # 如果在预检后代理-mcp 服务器仍然不健康 → 优雅地跳到步骤 4 如果！ curl -sf --connect-timeout 2 http://localhost:4747/health >/dev/null 2>&1;然后 python3-c“ 导入 json,os,subprocess,fcntl,time 尝试： root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() except: root=os.getcwd() f=os.path.join(root,'.omc/state/jeo-state.json') if os.path.exists(f): with open(f,'r+') as fh: fcntl.flock(fh,fcntl.LOCK_EX) try: d=json.load(fh) d['last_error']='agentation-mcp not running; VERIFY_UI 已跳过 ' d['updated_at']=time.strftime('%Y-%m-%dT%H:%M:%SZ',time.gmtime()) fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() 最后： fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null || true # 继续执行第 4 步清理（无退出 1 — 优雅跳过） fi 2. 更新 `jeo-state.json`: `phase = "verify_ui"`, `agentation.active = true`, `agentation.submit_gate_status = "waiting_for_submit"` 3. 等待明确的人类提交： - **Claude Code**：在用户按下 **Send Annotations** / `onSubmit` 后等待 `UserPromptSubmit` - **Codex / Gemini / OpenCode**：等到人类确认提交并且代理发出“ANNOTATE_READY”（或兼容性别名“AGENTUI_READY”） 4. 在提交信号到达之前，不要读取 `/pending`，不要确认注释，也不要启动修复循环 5、submit到达后，切换`agentation.submit_gate_status = "subscribed"`，记录`submit_signal`、`submit_received_at`、`subscribed_annotation_count` 6. **Claude Code (MCP)**：阻止调用 `agentation_watch_annotations` (`batchWindowSeconds:10`, `timeoutSeconds:120`) 7. **Codex / Gemini / OpenCode (HTTP)**：通过 `GET http://localhost:4747/pending` 进行轮询循环 8. 处理每个注释： `acknowledge` → 通过 `elementPath` 导航代码 → 应用修复 → `resolve` 9. `count=0` 或超时 → 重置提交门或完成子阶段 → **进入 STEP 4** **从不：在提交/onSubmit 之前处理草稿注释。** --- ### 第 4 步：清理 **飞行前（进入前检查）：** ````bash # 记录检查点 python3-c“ 导入 json、日期时间、操作系统、子进程、fcntl 尝试： root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() 除外： root=os.getcwd() f=os.path.join(root,'.omc/state/jeo-state.json') 如果 os.path.exists(f): 将 open(f,'r+') 作为 fh： fcntl.flock(fh,fcntl.LOCK_EX) 尝试： d=json.load(fh) d.update({'checkpoint':'cleanup','updated_at':datetime.datetime.utcnow().isoformat()+'Z'}) fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() 最后： fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null || true 如果！ git rev-parse --is-inside-work-tree >/dev/null 2>&1;那么 echo "⚠️ 不是 git 存储库 — 跳过工作树清理" 否则 UNCOMMITTED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') [[ "$UNCOMMITTED" -gt 0 ]] && echo "⚠️ ${UNCOMMITTED} 未提交的更改 — 建议在清理之前提交/存储" 菲 1. 将 `jeo-state.json` `phase` 更新为 `"cleanup"` 2.工作树清理： bash 脚本/worktree-cleanup.sh || git worktree 修剪 3. 将 `jeo-state.json` `phase` 更新为 `"done"` ** ** ## 1\.快速入门 > **事实来源**：`https://github.com/supercent-io/skills-template` 像`~/.claude/skills/jeo/` 这样的本地路径是通过`npx Skills add` 安装的副本。要更新到最新版本，请使用以下命令重新安装。 # 安装 JEO（npx 技能添加 — 推荐） npx 技能添加 https://github.com/supercent-io/skills-template --skill jeo # 完整安装（所有 AI 工具 + 所有组件） bash 脚本/install.sh --all # 检查状态 bash 脚本/check-status.sh # 单独的 AI 工具设置 bash script/setup-claude.sh # Claude 代码插件 + 钩子 bash 脚本/setup-codex.sh # Codex CLI 开发者指令 bash 脚本/setup-gemini.sh # Gemini CLI 挂钩 + GEMINI.md bash script/setup-opencode.sh # OpenCode 插件注册 ** ** ## 2\.安装的组件 JEO安装和配置的工具：工具|描述 |安装命令 ---|---|--- **omc**（哦我的克劳德代码）| Claude Code 多代理编排 | `/plugin 市场添加 https://github.com/Yeachan-Heo/oh-my-claudecode` **omx** | OpenCode 的多代理编排 | `bunx oh-my-opencode 设置` **欧姆** | Gemini CLI 的多代理框架 | `bunx oh-my-ag` **bmad** | BMAD 工作流程编排 |包含在技能中 **拉尔夫** |自参照完成循环 |包含在 omc 中或单独安装 **规划师** |视觉计划/差异审查|在计划期间通过 `bash script/ensure-plannotator.sh` 自动安装（或使用 `bash script/install.sh --with-plannotator` 预安装） **代理** | UI注释→代理代码修复集成（“annotate”关键字，“agentui”兼容性保持）| `bash 脚本/install.sh --with-agentation` **代理浏览器** |用于 AI 代理的无头浏览器 — **浏览器行为验证的主要工具** | `npm install -g 代理浏览器` **编剧** |基于剧作家的浏览器自动化（可选）| `npm install -g playwriter` ** ** ## 3\. JEO工作流程 ### 全流程 jeo“<任务>” │ ▼ [1] PLAN（拉尔夫+规划者）与 ralph 一起起草计划 → 与 plannotator 进行目视审查 → 批准/反馈 │ ▼ [2] 执行 ├─ 有团队吗？ → /omc:team N:执行者“<任务>” │ 分阶段管道：计划→prd→执行→验证→修复 └─ 没有团队？ → /bmad /workflow-init → 运行 BMAD 步骤 │ ▼ [3] VERIFY（代理浏览器 — 默认行为）使用代理浏览器验证浏览器行为 → 捕获快照 → 确认 UI/功能正常工作 │ ├─ 带注释关键字 → [3.3.1] VERIFY_UI（代理监视循环） │ agentation_watch_annotations阻塞→注释确认→修复→解决循环 │ ▼ [4] 清理所有工作完成后→bash脚本/worktree-cleanup.sh git worktree 修剪 ### 3.1 计划步骤（ralph + plannotator） > **平台说明** : `/ralph` 斜杠命令仅在 Claude Code (omc) 中可用。对于 Codex/Gemini/OpenCode，请使用下面的“替代方法”。 **克劳德代码（omc）：** /ralph "jeo-plan: <任务>" --completion-promise="PLAN_APPROVED" --max-iterations=5 **Codex / Gemini / OpenCode（替代）：** # 会话隔离的反馈目录（防止并发运行冲突） FEEDBACK_DIR=$(python3 -c "import hashlib,os; h=hashlib.md5(os.getcwd().encode()).hexdigest()[:8]; d=f'/tmp/jeo-{h}'; os.makedirs(d,exist_ok=True); print(d)" 2>/dev/null || echo '/tmp') FEEDBACK_FILE="${FEEDBACK_DIR}/plannotator_feedback.txt" # 1.直接写plan.md，然后用plannotator审核（阻塞——无&） PLANNOTATOR_RUNTIME_HOME="${FEEDBACK_DIR}/.plannotator" mkdir -p“$PLANNOTATOR_RUNTIME_HOME” touch /tmp/jeo-plannotator-direct.lock && python3 -c " 导入 json print(json.dumps({'tool_input': {'plan': open('plan.md').read(), 'permission_mode': 'acceptEdits'}})) ” | env HOME="$PLANNOTATOR_RUNTIME_HOME" PLANNOTATOR_HOME="$PLANNOTATOR_RUNTIME_HOME" 规划器 > "$FEEDBACK_FILE" 2>&1 # ↑ 不带 & 运行：等待用户在浏览器中单击“批准/发送反馈” # 2. 检查结果和分支如果 python3 -c " 导入 json、系统尝试： d = json.load(打开('$FEEDBACK_FILE')) sys.exit(0 if d.get('approved') 为 True else 1) 除了例外：系统退出(1) " 2>/dev/null;然后 echo "PLAN_APPROVED" # → 进入 EXECUTE 步骤否则 echo "PLAN_FEEDBACK" # → 读取\"$FEEDBACK_FILE\"，重新计划，重复上面菲 > **重要**：不要使用`&`（背景）运行。必须运行阻塞才能接收用户反馈。常见流程： * 生成计划文档(`plan.md`) * 运行 plannotator 阻塞 → 浏览器 UI 自动打开 * 在浏览器中查看计划 → 批准或发送反馈 * 批准 (`"approved":true`) → 进入 [2] EXECUTE 步骤 * 反馈 → 阅读 `/tmp/plannotator_feedback.txt` 注释并重新计划（循环） * **出口 32（沙盒/CI — 对话批准模式）**： 1. 向用户输出完整的`plan.md`内容 2. 询问：“⚠️ plannotator UI 不可用。回复‘批准’以继续或提供反馈。” 3. **等待用户响应 - 不要继续执行** 4. 批准后 → 更新 `jeo-state.json` `plan_approved=true, plan_gate_status="manual_approved"` → 执行 5.根据反馈→修改`plan.md`，重试循环，重复 **克劳德代码手动运行：** Shift+Tab×2 → 进入计划模式 → 计划完成后自动运行 plannotator ### 3.2 执行步骤 **当团队可用时（Claude Code + omc）：** /omc:team 3:executor "jeo-exec: <基于批准计划的任务>" * 分阶段管道：团队计划→团队PRD→团队执行→团队验证→团队修复 * 通过并行代理执行最大限度地提高速度 **当 Claude Code 团队模式不可用时：** echo "❌ JEO 需要 Claude Code 中的 /omc:team。运行 bash script/setup-claude.sh，重新启动 Claude Code，然后重试。" 1号出口 * 不要降级为单代理模式 **当团队不可用时（BMAD 后备 — Codex / Gemini / OpenCode）：** /workflow-init # 初始化 BMAD 工作流程 /workflow-status # 检查当前步骤 * 按顺序进行：分析→规划→解决方案→实施 * 每个步骤完成后使用 plannotator 查看文档 ### 3.3 验证步骤（代理浏览器 — 默认行为）当存在基于浏览器的功能时，请使用“代理浏览器”验证行为。 # 从应用程序运行的 URL 捕获快照代理浏览器快照 http://localhost:3000 # 检查特定元素（可访问性树引用方法）代理浏览器快照 http://localhost:3000 -i # → 使用@eN ref 编号检查元素状态 # 保存截图代理浏览器屏幕截图 http://localhost:3000 -o verify.png > **默认行为** ：当浏览器相关工作完成时，自动运行代理浏览器验证步骤。没有浏览器 UI 的后端/CLI 任务会跳过此步骤。 ### 3.3.1 VERIFY_UI 步骤（注释 — 代理监视循环）当检测到“annotate”关键字时运行代理监视循环。（为了向后兼容，还支持 `agentui` 关键字。）这遵循与在 `planui` / `ExitPlanMode` 中操作的 plannotator 相同的模式。 **先决条件（由飞行前自动解决）：** 1. `npx agentation-mcp server` (HTTP :4747) 正在运行 — **如果未运行则自动启动** 2. 项目中安装的 `agentation` npm 包 — **如果不存在则自动安装** 3. `` 安装在应用程序中 — **如果不存在则自动注入到入口点** **飞行前检查（进入前需要 - 所有平台通用）：** # ── 第 1 步：如果未运行则自动启动 agentation-mcp 服务器 ────────────────── JEO_AGENTATION_ENDPOINT="${JEO_AGENTATION_ENDPOINT:-http://localhost:4747}" JEO_AGENTATION_PORT="${JEO_AGENTATION_PORT:-4747}" 如果！ curl -sf --connect-timeout 2 "${JEO_AGENTATION_ENDPOINT}/health" >/dev/null 2>&1;然后 echo "[JEO][注释] agentation-mcp 未运行 — 尝试在端口 ${JEO_AGENTATION_PORT} 上自动启动..." if 命令 -v npx >/dev/null 2>&1;然后 npx -y 代理-mcp 服务器 --port "${JEO_AGENTATION_PORT}" >/tmp/agentation-mcp.log 2>&1 & AGENTATION_MCP_PID=$！ echo "[JEO][ANNOTATE] 已启动代理-mcp (PID ${AGENTATION_MCP_PID})" # 等待最多 8 秒让服务器恢复正常对于 $(seq 1 8) 中的 i；做睡觉 1 如果curl -sf --connect-timeout 1 "${JEO_AGENTATION_ENDPOINT}/health" >/dev/null 2>&1;然后 echo "[JEO][注释] ✅ 代理-mcp 服务器准备就绪" 打破菲完成如果！ curl -sf --connect-timeout 2 "${JEO_AGENTATION_ENDPOINT}/health" >/dev/null 2>&1;然后 echo "[JEO][注释] ⚠️ agentation-mcp 启动失败 — 跳过 VERIFY_UI" python3-c“ 导入 json、操作系统、子进程、fcntl、时间尝试： root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() 除外： root=os.getcwd() f=os.path.join(root,'.omc/state/jeo-state.json') 如果 os.path.exists(f): 将 open(f,'r+') 作为 fh： fcntl.flock(fh,fcntl.LOCK_EX) 尝试： d=json.load(fh) d['last_error']='agentation-mcp 启动失败； VERIFY_UI 已跳过' d['updated_at']=time.strftime('%Y-%m-%dT%H:%M:%SZ',time.gmtime()) fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() 最后： fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null ||真实 # 继续执行第 4 步清理（无出口 1 — 优雅跳过）菲否则 echo "[JEO][注释] ⚠️ 未找到 npx — 无法自动启动 agentation-mcp。正在跳过 VERIFY_UI。" python3-c“ 导入 json、操作系统、子进程、fcntl、时间尝试： root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() 除外： root=os.getcwd() f=os.path.join(root,'.omc/state/jeo-state.json') 如果 os.path.exists(f): 将 open(f,'r+') 作为 fh： fcntl.flock(fh,fcntl.LOCK_EX) 尝试： d=json.load(fh) d['last_error']='npx 未找到；跳过代理-mcp 自动启动； VERIFY_UI 已跳过' d['updated_at']=time.strftime('%Y-%m-%dT%H:%M:%SZ',time.gmtime()) fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() 最后： fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null ||真实 # 继续执行第 4 步清理（无出口 1 — 优雅跳过）菲菲 # ── 步骤2：自动安装代理包 + 如果需要注入 ── # 仅当服务器确认健康时运行如果curl -sf --connect-timeout 2“${JEO_AGENTATION_ENDPOINT}/health”>/dev/null 2>&1;然后 SESSIONS=$(curl -sf "${JEO_AGENTATION_ENDPOINT}/sessions" 2>/dev/null || echo "[]") S_COUNT=$(echo "$SESSIONS" | python3 -c "import sys,json; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0) 如果[“$S_COUNT”-eq 0];然后 echo“[JEO][注释]没有活动会话 - 运行 Ensure-agentation.sh 来安装包并注入组件...” # 找到ensure-agentation.sh（尝试常见的安装路径） ENSURE_SCRIPT="" 对于 \ 中的候选人 "$(dirname "${BASH_SOURCE[0]:-$0}")/ensure-agentation.sh" \ “$HOME/.claude/skills/jeo/scripts/ensure-agentation.sh”\ “$HOME/.agent-skills/jeo/scripts/ensure-agentation.sh”\ “$HOME/.codex/skills/jeo/scripts/ensure-agentation.sh”；做 if [[ -f "$candidate" ]];然后 ENSURE_SCRIPT="$候选人" 打破菲完成如果 [[ -n "$ENSURE_SCRIPT" ]];然后 ENSURE_EXIT=0 bash“$ENSURE_SCRIPT”\ --project-dir "${PROJECT_DIR:-$PWD}" \ --端点“${JEO_AGENTATION_ENDPOINT}”|| ENSURE_EXIT=$? 如果[“$ENSURE_EXIT”-eq 0];然后 echo "[JEO][注释] 确保代理已完成 — 等待浏览器重新连接最多 15 秒..." # 等待开发服务器热重载和浏览器重新连接对于 $(seq 1 15) 中的 i；做睡觉 1 NEW_S_COUNT=$(curl -sf "${JEO_AGENTATION_ENDPOINT}/sessions" 2>/dev/null | \ python3 -c "导入 sys,json; print(len(json.load(sys.stdin)))" 2>/dev/null ||回声 0) 如果[“$NEW_S_COUNT”-gt 0];然后 echo "[JEO][注释] ✅ 已建立浏览器会话（${NEW_S_COUNT} 个会话）" S_COUNT=$NEW_S_COUNT 打破菲完成如果[“$S_COUNT”-eq 0];然后 echo“[JEO][注释]⚠️组件已注入，但还没有浏览器会话。” echo " → 在您的应用程序 URL 处刷新浏览器，然后重新运行注释。" 菲 elif [“$ENSURE_EXIT”-eq 2];然后 echo "[JEO][ANNOTATE] ℹ️ 不是 Node.js 项目 — 手动挂载。" 否则 echo "[JEO][注释] ⚠️ Ensure-agentation.sh 失败（退出 $ENSURE_EXIT） — 手动挂载。" 菲否则 echo "[JEO][注释] ⚠️ Ensure-agentation.sh 未找到 — 手动挂载。" 菲菲 echo "[JEO][注释] ✅ 代理就绪 — 服务器正常，${S_COUNT} 个会话" 菲 > 通过预检（`else` 分支）后，将 jeo-state.json `phase` 更新为 `"verify_ui"`，将 `agentation.active` 设置为 `true`，并将 `agentation.submit_gate_status` 设置为 `"waiting_for_submit"`。暂时不要调用`/pending`。在用户明确提交之前，草稿注释不可操作。 **克劳德代码（直接MCP工具调用）：** # 注释检测到的关键字（或agentui - 向后兼容） # 1.用户点击Send Annotations / onSubmit后等待UserPromptSubmit # 2. JEO 提交门钩子记录submit_gate_status =“已提交” # 3. 然后才运行阻塞代理监视循环 # # batchWindowSeconds:10 — 以 10 秒为一个批次接收注释 # timeoutSeconds:120 — 120 秒后自动退出，无注释 # # 每个注释处理循环： # 1. agentation_acknowledge_annotation({id}) — 在 UI 中显示“处理” # 2.通过annotation.elementPath（CSS选择器）导航代码→应用修复 # 3. agentation_resolve_annotation({id, Summary}) — 标记“完成”+保存摘要 # # 当注释计数=0或超时时循环结束 > **重要**：`agentation_watch_annotations` 是一个阻塞调用。不要以“&”背景运行。与 plannotator 的 `approved:true` 循环相同：注释计数 = 0 或超时 = 完成信号。 “annotate”是主要关键字。 `agentui` 是一个向后兼容的别名，并且行为相同。 **Codex / Gemini / OpenCode（HTTP REST API 后备）：** START_TIME=$(日期 +%s) 超时_秒=120 # 必需的门：在用户单击“发送注释”之前不要进入循环 # 并且平台已开启agentation.submit_gate_status="subscribed"。虽然真实；做 # 超时检查现在=$(日期+%s) 已逝=$((现在 - START_TIME)) 如果 [ $ELAPSED -ge $TIMEOUT_SECONDS ];然后 echo "[JEO] 代理轮询超时 (${TIMEOUT_SECONDS}s) — 某些注释可能仍未解决" 打破菲 SUBMIT_GATE=$(python3 -c " 导入 json 尝试： print(json.load(open('.omc/state/jeo-state.json')).get('代理', {}).get('submit_gate_status', '空闲')) 除了例外：打印（'空闲'） " 2>/dev/null || echo "空闲") if [ "$SUBMIT_GATE" != "已提交" ];然后睡觉2 继续菲 COUNT=$(curl -sf --connect-timeout 3 --max-time 5 http://localhost:4747/pending 2>/dev/null | python3 -c "import sys,json; data=sys.stdin.read(); d=json.loads(data) if data.strip() else {}; print(d.get('count', len(d.get('annotations', [])) if isinstance(d, dict) else 0))" 2>/dev/null || echo 0) [ "$COUNT" -eq 0 ] && 中断 # 处理每个注释： # a) 确认（显示为进行中）卷曲 -X 补丁 http://localhost:4747/annotations/ \ -H '内容类型：application/json' \ -d '{"状态": "已确认"}' # b) 通过 elementPath（CSS 选择器）导航代码 → 应用修复 # c) 解决（标记为完成 + 修复摘要）卷曲 -X 补丁 http://localhost:4747/annotations/ \ -H '内容类型：application/json' \ -d '{"status": "resolved", "resolved": "<修复摘要>"}' 睡觉 3 完成 ### 3.4 CLEANUP 步骤（自动工作树清理） # 所有工作完成后自动运行 bash 脚本/worktree-cleanup.sh # 单独的命令 git worktree list # 列出当前工作树 git worktree prune # 清理工作树中已删除的分支 bash script/worktree-cleanup.sh --force # 强制清理，包括脏工作树 > 默认运行仅删除干净的额外工作树；发生更改的工作树会留下警告。仅在审核后使用“--force”。 ** ** ## 4\.平台插件配置 ### 4.1 克劳德代码 # 自动设置 bash 脚本/setup-claude.sh # 或者手动： /插件市场添加 https://github.com/Yeachan-Heo/oh-my-claudecode /插件安装 oh-my-claudecode /omc:omc-设置 # 添加规划器钩子 bash .agent-skills/plannotator/scripts/setup-hook.sh **配置文件** : `~/.claude/settings.json` { “钩子”：{ “权限请求”：[{ "matcher": "退出计划模式", “钩子”：[{ “类型”：“命令”， “命令”：“python3 ~/.claude/skills/jeo/scripts/claude-plan-gate.py”， “超时”：1800 }] }] } } **代理 MCP 配置**（`~/.claude/settings.json` 或 `.claude/mcp.json`）： { “mcp服务器”：{ “代理”：{ “命令”：“npx”， “args”：[“-y”，“代理-mcp”，“服务器”] } }, “钩子”：{ “用户提示提交”：[{ “匹配器”：“*”， “钩子”：[{ “类型”：“命令”， “命令”：“python3 ~/.claude/skills/jeo/scripts/claude-agentation-submit-hook.py”， “超时”：300 }] }] } } ### 4.2 Codex CLI # 自动设置 bash 脚本/setup-codex.sh # 配置了什么： # - 开发人员说明：~/.codex/config.toml # - 提示文件：~/.codex/prompts/jeo.md # - 通知钩子：~/.codex/hooks/jeo-notify.py # - [tui] 通知：代理完成 **代理 MCP 配置** (`~/.codex/config.toml`)： [mcp_servers.代理] 命令=“npx” args = [“-y”，“代理-mcp”，“服务器”] **通知钩子** (`~/.codex/hooks/jeo-notify.py`): * 当代理轮流完成时，在“last-assistant-message”中检测“PLAN_READY”信号 * 确认“plan.md”存在，将当前哈希与“last_reviewed_plan_hash”进行比较，并在计划已被审核时跳过该门 * 将结果保存到 `/tmp/plannotator_feedback.txt` * 仅在“verify_ui”中检测“ANNOTATE_READY”信号（或向后兼容的“AGENTUI_READY”） * 首先打开 `agentation.submit_gate_status="subscribed"`，然后轮询 `http://localhost:4747/pending` **`~/.codex/config.toml`** 配置：开发者说明 = """ # JEO 编排工作流程 # ... ”“” 通知 = ["python3", "~/.codex/hooks/jeo-notify.py"] [图] 通知= [“代理完成”] notification_method =“osc9” > `developer_instructions` 必须是**顶级字符串**。将其写入“[developer_instructions]”表可能会导致 Codex 在启动时失败，并显示“无效类型：映射，需要字符串”。还必须正确设置“notify”和“[tui].notifications”，以便 PLAN/ANNOTATE 后续循环实际工作。在法典中使用： /prompts:jeo # 激活 JEO 工作流程 # Agent写入plan.md并输出“PLAN_READY” → 通知钩子自动运行 ### 4.3 Gemini CLI # 自动设置 bash 脚本/setup-gemini.sh # 配置了什么： # - AfterAgent 备份挂钩：~/.gemini/hooks/jeo-plannotator.sh # - 说明（强制循环）：~/.gemini/GEMINI.md **关键原则**：代理必须**直接以阻塞模式**调用plannotator才能在同一轮中接收反馈。 AfterAgent 钩子仅用作安全网（在回合结束后运行 → 在下一回合注入）。 **AfterAgent 备份挂钩** (`~/.gemini/settings.json`)： { “钩子”：{ “后代理”：[{ “匹配器”：“”， “钩子”：[{ "name": "plannotator-review", “类型”：“命令”， “命令”：“bash ~/.gemini/hooks/jeo-plannotator.sh”， "description": "检测到 plan.md 时运行 plannotator (AfterAgent 备份)" }] }] } } **PLAN 指令添加到 GEMINI.md（强制循环）**： 1.编写plan.md 2. 运行 plannotator 阻塞（无 &） → /tmp/plannotator_feedback.txt 3.已批准=true→执行/未批准→修改并重复步骤2 切勿在没有approved=true 的情况下继续执行。 **代理 MCP 配置** (`~/.gemini/settings.json`)： { “mcp服务器”：{ “代理”：{ “命令”：“npx”， “args”：[“-y”，“代理-mcp”，“服务器”] } } } > **注意**：Gemini CLI 挂钩事件使用 `BeforeTool` 和 `AfterAgent`。 `ExitPlanMode` 是一个仅限 Claude 代码的钩子。 > [Hooks 官方指南]() ### 4.4 开放代码 # 自动设置 bash 脚本/setup-opencode.sh # 添加到 opencode.json: #“@plannotator/opencode@latest”插件 # “@oh-my-opencode/opencode@latest”插件 (omx) OpenCode 斜线命令： * `/jeo-plan` — 与 ralph + plannotator 一起制定计划 * `/jeo-exec` — 使用 team/bmad 执行 * `/jeo-annotate` — 启动代理监视循环（注释；`/jeo-agentui` 是一个已弃用的别名） * `/jeo-cleanup` — 工作树清理 **规划器集成**（强制阻塞循环）： # 编写 plan.md 然后运行 PLAN 门（无 &）——同时接收反馈 bash脚本/plannotator-plan-loop.sh plan.md /tmp/plannotator_feedback.txt 3 # - 必须等到收到批准/反馈 # - 会话退出时自动重新启动（最多 3 次） # - 3次退出后，与用户确认是否中止或恢复 # - 如果 localhost 绑定不可用，则退出 32（用 TTY 中的手动门替换） # 根据结果进行分支 # 已批准=true → 输入 EXECUTE # 未批准 → 应用反馈，修改 plan.md → 重复上述 **代理 MCP 配置** (`opencode.json`)： { “MCP”：{ “代理”：{ “类型”：“本地”， “命令”：[“npx”，“-y”，“代理-mcp”，“服务器”] } } } ** ** ## 5\.内存与状态 JEO 将状态存储在以下路径中： {worktree}/.omc/state/jeo-state.json # JEO执行状态 {worktree}/.omc/plans/jeo-plan.md # 批准的计划 {worktree}/.omc/logs/jeo-*.log # 执行日志 **状态文件结构：** { “模式”：“杰奥”， "phase": "计划|执行|验证|verify_ui|清理|完成", "session_id": "", "task": "当前任务描述", “plan_approved”：正确， "plan_gate_status": "待处理|已批准|feedback_required|infrastruction_blocked|manual_approved", "plan_current_hash": "", "last_reviewed_plan_hash": "", "last_reviewed_plan_at": "2026-02-24T00:00:00Z", "plan_review_method": "计划者|手册|空", “team_available”：正确， “重试次数”：0， “最后一个错误”：空， "checkpoint": "计划|执行|验证|verify_ui|清理", “创建时间”：“2026-02-24T00:00:00Z”， “updated_at”：“2026-02-24T00:00:00Z”， “代理”：{ “主动”：假， “session_id”：空， “keyword_used”：空， "submit_gate_status": "空闲|waiting_for_submit|已提交", "submit_signal": "claude-user-prompt-submit|codex-notify|gemini-manual|null", "submit_received_at": "2026-02-24T00:00:00Z", “提交的注释计数”：0， “开始于”：空， “超时秒数”：120， “注释”：{ “总计”: 0、“已确认”: 0、“已解决”: 0、“驳回”: 0、“待处理”: 0 }, “完成时间”：空， “退出原因”：空 } } > **代理字段**：`active` - 监视循环是否正在运行（用作钩子保护），`session_id` - 用于恢复，`submit_gate_status` - 阻止在提交/onSubmit 之前处理草稿注释，`submit_signal` - 哪个平台打开了门，`submit_received_at` / `subscribed_annotation_count` - 已提交批次的审计跟踪，`exit_reason` - `"all_resolved"` | `“超时”` | `"user_cancelled"` | `“错误”` > > **解除注释** ：当用户在代理 UI 中解除注释（状态变为“已解除”）时，代理应跳过该注释的代码更改，增加“annotations.dismissed”，并继续处理下一个待处理注释。忽略的注释会被计算在内，但不会被执行。当“pending == 0”时，监视循环正常退出（已解决+已解雇涵盖所有）。 > > **`plan_review_method`** ：通过 UI 批准时设置为“plannotator”，通过 TTY 后备门批准时设置为“manual”。 > > **`cleanup_completed`** ：成功修剪工作树后，通过 `worktree-cleanup.sh` 设置为 `true`。 > **错误恢复字段** : > > * `retry_count` — 发生错误后的重试次数。每次飞行前失败都会增加 +1。要求用户确认是否`>= 3`。 > * `last_error` — 最近的错误消息。用于确定重新启动时的原因。 > * `checkpoint` — 启动的最后一个阶段。重新启动时从该阶段恢复（“计划|执行|验证|清理”）。 > **基于检查点的恢复流程：** # 重启时检查检查点 python3-c“ 导入 json、操作系统、子进程尝试： root = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], stderr=subprocess.DEVNULL).decode().strip() 除外：根= os.getcwd() f = os.path.join(root, '.omc/state/jeo-state.json') 如果 os.path.exists(f): d=json.load(打开(f)) cp=d.get('检查点') err=d.get('最后一个错误') rc=d.get('重试次数',0) print(f'恢复自: {cp 或 \"beginning\"}') if err: print(f'前一个错误 ({rc} 时间(s)): {err}') if rc >= 3: print('⚠️ 重试次数超过 3 — 需要用户确认') ” 重启后恢复： # 检查状态并恢复 bash 脚本/check-status.sh --resume ** ** ## 6\.推荐工作流程 # 第 1 步：安装（一次） bash 脚本/install.sh --all bash 脚本/check-status.sh # 第二步：开始工作 jeo "<任务描述>" # 使用关键字激活 # 或者在 Claude 中：Shift+Tab×2 → 计划模式 # 第 3 步：使用 plannotator 审查计划 # 在浏览器 UI 中批准或发送反馈 # 第四步：自动执行 # 团队或 bmad 处理工作 #第五步：完成后清理 bash 脚本/worktree-cleanup.sh ** ** ## 7\.最佳实践 1. **首先计划**：在执行之前始终使用 ralph+plannotator 审查计划（及早发现错误的方法） 2. **团队优先**：omc团队模式在Claude Code中效率最高 3. **bmad后备** ：在没有团队的环境中使用BMAD（Codex，Gemini） 4. **Worktree cleanup** ：工作完成后立即运行`worktree-cleanup.sh`（防止分支污染） 5. **状态持久化** ：使用`.omc/state/jeo-state.json`来维护跨会话的状态 6. **annotate** ：使用“annotate”关键字运行复杂 UI 更改的代理监视循环（通过 CSS 选择器进行精确的代码更改）。 `agentui` 是一个向后兼容的别名。 ** ** ## 8\.故障排除问题 |解决方案 ---|--- plannotator 未运行 | JEO 首先自动运行 `bash script/ensure-plannotator.sh`；如果仍然失败，请运行“bash .agent-skills/plannotator/scripts/check-status.sh” plannotator 无法在克劳德代码中打开 | plannotator 仅是钩子。不要通过 MCP 或 CLI 调用它。使用 `EnterPlanMode` → 编写计划 → `ExitPlanMode`；钩子会自动触发。验证挂钩已设置：`cat ~/.claude/settings.json | python3 -c "导入 sys,json;h=json.load(sys.stdin).get('hooks',{});print(h.get('PermissionRequest','missing'))"` 未收到规划者反馈 |删除`&`后台执行→运行阻塞，然后检查`/tmp/plannotator_feedback.txt`（仅限Codex/Gemini/OpenCode）同一计划在法典中反复重新审查 |将 `jeo-state.json` 中的 `last_reviewed_plan_hash` 与当前的 `plan.md` 哈希值进行比较。如果它们匹配并且“plan_gate_status”为终端，则不要重新运行 Codex 启动失败（“无效类型：映射，需要字符串”）|重新运行`bash脚本/setup-codex.sh`并确认`~/.codex/config.toml`中的`developer_instructions`是顶级字符串双子座反馈回路缺失|在`~/.gemini/GEMINI.md`中添加阻塞直接调用指令工作树冲突 | `git worktree 修剪 && git worktree 列表` 团队模式不起作用 | JEO 需要克劳德代码中的团队模式。运行“bash脚本/setup-claude.sh”，重新启动Claude Code，并在重试之前验证“CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1” omc 安装失败 |运行“/omc:omc-doctor” 代理浏览器错误 |检查“代理浏览器--版本” 注释（代理）未打开 |检查 `curl http://localhost:4747/health` 和 `curl http://localhost:4747/sessions`。 JEO 在轮询“/pending”之前等待显式提交/onSubmit 注释未反映在代码中 |调用“agentation_resolve_annotation”时确认“summary”字段存在 `agentui` 关键字未激活 |使用“annotate”关键字（新）。 `agentui` 是一个已弃用的别名，但仍然有效。 MCP 工具未注册 (Codex/Gemini) |重新运行`bash脚本/setup-codex.sh`/`setup-gemini.sh` ** ** ## 9\.参考文献 * [oh-my-claudecode]() — 克劳德代码多代理 * [plannotator]() — 视觉计划/差异审查 * [BMAD Method]() — 结构化人工智能开发工作流程 * [Agent Skills Spec]() — 技能格式规范 * [agentation]() — UI 注释 → 代理代码修复集成（`annotate`; `agentui` 向后兼容）

吃

包含技能