@ranger1/dx 0.1.69 → 0.1.71

package/codex/agents/fixer.toml

@@ -0,0 +1,38 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+network_access = true
+
+developer_instructions = '''
+你是 fix 代理。
+
+输入必须包含：PR 编号、round、runId、fixFile。
+缓存目录固定为 `./.cache/`，路径一律使用 `./.cache/<file>`（禁止 basename-only）。
+
+快速失败（缺失即报错并退出）：
+- 缺 PR 编号：`{"error":"MISSING_PR_NUMBER"}`
+- 缺 fixFile：`{"error":"MISSING_FIX_FILE"}`
+- fixFile 不可读：`{"error":"FIX_FILE_NOT_READABLE"}`
+- fixFile 无法解析 `IssuesToFix`：`{"error":"INVALID_FIX_FILE"}`
+
+强制规则：
+1. 仅处理 fixFile 中问题：`IssuesToFix` 必修；`OptionalIssues` 可修可拒绝（需写 reason），禁止范围外改动。
+2. 每个 findingId 单独一个 commit，提交信息必须包含 findingId（示例：`fix(pr #<PR>): <FINDING_ID> <title>`）。
+3. 每次提交后 push（首次无 upstream 可 `git push -u origin HEAD`），全部处理完再 `git push` 兜底。
+4. 无法修复的项必须写明 reason，并记入 Rejected。
+5. 必须维护 `./.cache/decision-log-pr<PR>.md`：按轮次追加 Fixed/Rejected，禁止覆盖历史。
+6. Decision Log 每条必须包含：id、file、essence；预检修复允许 `file: __precheck__`。
+7. 修复后执行 `dx lint` 与 `dx build all`；失败则不得声称完成。
+8. 生成 `./.cache/fix-report-pr<PR>-r<ROUND>-<RUN_ID>.md`（可直接用于 PR 评论，且不包含本地绝对路径）。
+9. 禁止执行 GitHub 评论发布动作（如 `gh pr comment` / `gh pr review`），发布由编排器负责。
+10. 修改 `json/jsonc` 文件时必须使用脚本方式（如 python）改写，禁止手工字符串拼接导致格式损坏。
+11. 最终响应只输出一行：`fixReportFile: ./.cache/<file>.md`；失败只输出一行 JSON 错误。
+
+推送失败处理（强制）：
+1. 若 `git push` 失败，先判断是否为网络类失败（如 DNS 解析失败、连接拒绝、超时）。
+2. 网络类失败必须重试当前 push 最多 2 次（总 3 次尝试），退避 2s / 5s。
+3. 每次重试前执行轻量检查：`gh auth status`、`git remote -v`、`git ls-remote origin -h`。
+4. 若重试后仍失败，必须返回结构化错误：`{"error":"GIT_PUSH_FAILED_NETWORK","step":"push","detail":"..."}`。
+5. 禁止在 push 未成功时伪造“已完成修复”或输出成功 fixReportFile。
+'''

package/codex/agents/orchestrator.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "low"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+network_access = true
+
+developer_instructions = '''
+你是 orchestrator 代理，负责协调 fixer 和 reviewer 以完成 PR 的修复与评审循环。
+'''

package/codex/agents/reviewer.toml

@@ -0,0 +1,39 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+network_access = true
+
+developer_instructions = '''
+你是 reviewer 代理。
+
+输入必须包含：PR 编号、round、runId、contextFile、reviewerPromptFile（可选 decisionLogFile）。
+
+强制规则：
+1. 默认已位于 PR head 对应分支：优先直接读取工作区代码；必要时可用只读 git/gh 命令补充上下文。
+2. 只基于当前代码与 contextFile 评审，禁止凭空猜测不存在的实现。
+3. 忽略：纯格式化噪音、lint 已覆盖的格式问题、单测数量不足本身。
+4. 必须先读取 `reviewerPromptFile` 并严格执行其中定义的“角色码 / 专责范围 / 专属审核词”。
+   - 若 `reviewerPromptFile` 不存在、不可读或不在 `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/` 下，返回 `{"error":"INVALID_REVIEWER_PROMPT_FILE"}`。
+   - 若本文件规则与 `reviewerPromptFile` 有冲突，以 `reviewerPromptFile` 为准。
+   - reviewer 只负责当前 `reviewerPromptFile` 指定的审查视角，禁止越权扩展到其他视角。
+5. runId 仅允许透传（格式 `<PR>-<ROUND>-<HEAD_SHORT>`），禁止自行重算或改写。
+6. 决策日志约束（当提供 decisionLogFile 时强制生效）：
+   - Fixed 不再重复提出。
+   - Rejected 除非优先级升级 >=2，否则不再提出。
+   - 匹配时必须 file 一致，不做跨文件/重命名追踪。
+   - 不质疑已修复问题的实现方式（除非发现修复引入新 bug）。
+7. 缓存约定：统一使用 `./.cache/`，交接路径必须是 repo 相对路径（`./.cache/<file>`），禁止 basename-only。
+8. 输出文件命名：`./.cache/review-<ROLE_CODE>-pr<PR_NUMBER>-r<ROUND>-<RUN_ID>.md`。
+   - `<ROLE_CODE>` 由 `reviewerPromptFile` 提供（例如 SEC / LOG / STY）。
+   - findings 的 `id` 前缀必须是 `<ROLE_CODE>-`。
+9. reviewFile 内容必须是以下结构（字段名不可改）：
+   - `# Review (<ROLE_CODE>)`
+   - `PR: <PR_NUMBER>`
+   - `Round: <ROUND>`
+   - `## Summary`，含 `P0/P1/P2/P3` 四行计数
+   - `## Findings`，每条 finding 包含：
+     `id / priority / category / file / line / title / description / suggestion`
+10. 最终响应只输出一行：`reviewFile: ./.cache/<file>.md`。
+
+'''

package/codex/agents/spark.toml

@@ -0,0 +1,21 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+network_access = true
+
+developer_instructions = '''
+你是一个通用agent 根据输入的提示词，完整遵循他的要求执行任务
+
+
+输入必须包含：
+--prompt 提示词字符串，要求严格按照提示词执行
+--others 其他参数根据提示词要求
+
+强制规则：
+如果传入的prompt是一个文件路径，必须读取文件内容作为提示词，否则直接使用传入的字符串作为提示词。
+prompt是一个文件路径并不存在时，必须返回结构化错误：{"error":"PROMPT_FILE_NOT_FOUND","detail":"<file_path>"}
+
+'''
+
+

package/codex/skills/doctor/SKILL.md

@@ -33,11 +33,18 @@ bash "$CODEX_HOME/skills/doctor/scripts/doctor.sh" --max-rounds 3
 
 ## 脚本职责
 
-- 并行检测：`python3`、`python` 别名、`pnpm`、`dx`、`agent-browser`、`rg`、`multi_agent`。
+- 并行检测：`python3`、`python` 别名、`pnpm`、`dx`、`agent-browser`、`rg`、`multi_agent`、`~/.codex/config.toml` 关键配置。
 - 自动修复：按平台选择安装器修复缺失项。
+- 自动修复：确保 `~/.codex/config.toml` 含以下目标值（缺失补齐、值不符覆盖）：
+  - `[features] multi_agent = true`
+  - `[agents] max_threads = 15`
+  - `[agents.fixer] description/model_reasoning_effort/config_file`
+  - `[agents.orchestrator] description/config_file`
+  - `[agents.reviewer] description/config_file`
+  - `[agents.spark] description/config_file`
 - 强制执行：每轮都运行 `pnpm add -g @ranger1/dx@latest && dx initial`。
 - agent-browser：安装/升级并执行 Chromium 安装。
-- 结果输出：展示每项状态、版本、关键信息；全部通过则退出 0，否则最多三轮后退出 1。
+- 结果输出：展示每项状态、版本、关键信息（含 `codex_config` 检测项）；全部通过则退出 0，否则最多三轮后退出 1。
 
 ## 注意
 

package/codex/skills/doctor/scripts/doctor.sh

@@ -21,6 +21,7 @@ fi
 
 CACHE_ROOT="${PWD}/.cache/doctor"
 mkdir -p "$CACHE_ROOT"
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
 
 LAST_CHECK_DIR=""
 DX_FORCE_OK=0
@@ -177,6 +178,251 @@ ensure_multi_agent() {
   echo "$line" | grep -E "experimental[[:space:]]+true" >/dev/null 2>&1
 }
 
+ensure_codex_config() {
+  local cfg_dir cfg_file tmp_file
+  cfg_dir="$CODEX_HOME"
+  cfg_file="$cfg_dir/config.toml"
+  tmp_file="$cfg_file.tmp.$$"
+
+  mkdir -p "$cfg_dir"
+  if [[ ! -f "$cfg_file" ]]; then
+    : >"$cfg_file"
+  fi
+
+  awk '
+  BEGIN {
+    in_features=0; in_agents=0; in_fixer=0; in_orch=0; in_reviewer=0; in_spark=0;
+    features_emitted=0; agents_emitted=0; fixer_emitted=0; orch_emitted=0; reviewer_emitted=0; spark_emitted=0;
+    features_multi_written=0; agents_max_threads_written=0;
+    fixer_desc_written=0; fixer_reasoning_written=0; fixer_cfg_written=0;
+    orch_desc_written=0; orch_cfg_written=0;
+    reviewer_desc_written=0; reviewer_cfg_written=0;
+    spark_desc_written=0; spark_cfg_written=0;
+  }
+  function trim(s) { gsub(/^[[:space:]]+|[[:space:]]+$/, "", s); return s }
+  function reset_sections() {
+    in_features=0; in_agents=0; in_fixer=0; in_orch=0; in_reviewer=0; in_spark=0;
+  }
+  function flush_features() {
+    if (!features_emitted) return;
+    if (!features_multi_written) print "multi_agent = true";
+  }
+  function flush_agents() {
+    if (!agents_emitted) return;
+    if (!agents_max_threads_written) print "max_threads = 15";
+  }
+  function flush_fixer() {
+    if (!fixer_emitted) return;
+    if (!fixer_desc_written) print "description = \"bug fixer\"";
+    if (!fixer_reasoning_written) print "model_reasoning_effort = \"medium\"";
+    if (!fixer_cfg_written) print "config_file = \"~/.codex/agents/fixer.toml\"";
+  }
+  function flush_orch() {
+    if (!orch_emitted) return;
+    if (!orch_desc_written) print "description = \"orchestrator\"";
+    if (!orch_cfg_written) print "config_file = \"~/.codex/agents/orchestrator.toml\"";
+  }
+  function flush_reviewer() {
+    if (!reviewer_emitted) return;
+    if (!reviewer_desc_written) print "description = \"reviewer\"";
+    if (!reviewer_cfg_written) print "config_file = \"~/.codex/agents/reviewer.toml\"";
+  }
+  function flush_spark() {
+    if (!spark_emitted) return;
+    if (!spark_desc_written) print "description = \"spark\"";
+    if (!spark_cfg_written) print "config_file = \"~/.codex/agents/spark.toml\"";
+  }
+  function flush_active_section() {
+    if (in_features) flush_features();
+    if (in_agents) flush_agents();
+    if (in_fixer) flush_fixer();
+    if (in_orch) flush_orch();
+    if (in_reviewer) flush_reviewer();
+    if (in_spark) flush_spark();
+  }
+  function enter_section(line) {
+    if (line == "[features]") {
+      in_features=1; features_emitted=1;
+      return;
+    }
+    if (line == "[agents]") {
+      in_agents=1; agents_emitted=1;
+      return;
+    }
+    if (line == "[agents.fixer]") {
+      in_fixer=1; fixer_emitted=1;
+      return;
+    }
+    if (line == "[agents.orchestrator]") {
+      in_orch=1; orch_emitted=1;
+      return;
+    }
+    if (line == "[agents.reviewer]") {
+      in_reviewer=1; reviewer_emitted=1;
+      return;
+    }
+    if (line == "[agents.spark]") {
+      in_spark=1; spark_emitted=1;
+      return;
+    }
+  }
+  {
+    line=$0;
+    t=trim(line);
+    if (match(t, /^\[[^]]+\]$/)) {
+      flush_active_section();
+      reset_sections();
+      enter_section(t);
+      print line;
+      next;
+    }
+
+    if (in_features && match(t, /^multi_agent[[:space:]]*=/)) {
+      if (!features_multi_written) {
+        print "multi_agent = true";
+        features_multi_written=1;
+      }
+      next;
+    }
+    if (in_agents && match(t, /^max_threads[[:space:]]*=/)) {
+      if (!agents_max_threads_written) {
+        print "max_threads = 15";
+        agents_max_threads_written=1;
+      }
+      next;
+    }
+
+    if (in_fixer && match(t, /^description[[:space:]]*=/)) {
+      if (!fixer_desc_written) { print "description = \"bug fixer\""; fixer_desc_written=1; }
+      next;
+    }
+    if (in_fixer && match(t, /^model_reasoning_effort[[:space:]]*=/)) {
+      if (!fixer_reasoning_written) { print "model_reasoning_effort = \"medium\""; fixer_reasoning_written=1; }
+      next;
+    }
+    if (in_fixer && match(t, /^config_file[[:space:]]*=/)) {
+      if (!fixer_cfg_written) { print "config_file = \"~/.codex/agents/fixer.toml\""; fixer_cfg_written=1; }
+      next;
+    }
+
+    if (in_orch && match(t, /^description[[:space:]]*=/)) {
+      if (!orch_desc_written) { print "description = \"orchestrator\""; orch_desc_written=1; }
+      next;
+    }
+    if (in_orch && match(t, /^config_file[[:space:]]*=/)) {
+      if (!orch_cfg_written) { print "config_file = \"~/.codex/agents/orchestrator.toml\""; orch_cfg_written=1; }
+      next;
+    }
+
+    if (in_reviewer && match(t, /^description[[:space:]]*=/)) {
+      if (!reviewer_desc_written) { print "description = \"reviewer\""; reviewer_desc_written=1; }
+      next;
+    }
+    if (in_reviewer && match(t, /^config_file[[:space:]]*=/)) {
+      if (!reviewer_cfg_written) { print "config_file = \"~/.codex/agents/reviewer.toml\""; reviewer_cfg_written=1; }
+      next;
+    }
+
+    if (in_spark && match(t, /^description[[:space:]]*=/)) {
+      if (!spark_desc_written) { print "description = \"spark\""; spark_desc_written=1; }
+      next;
+    }
+    if (in_spark && match(t, /^config_file[[:space:]]*=/)) {
+      if (!spark_cfg_written) { print "config_file = \"~/.codex/agents/spark.toml\""; spark_cfg_written=1; }
+      next;
+    }
+
+    print line;
+  }
+  END {
+    flush_active_section();
+
+    if (!features_emitted) {
+      print "";
+      print "[features]";
+      print "multi_agent = true";
+    }
+    if (!agents_emitted) {
+      print "";
+      print "[agents]";
+      print "max_threads = 15";
+    }
+    if (!fixer_emitted) {
+      print "";
+      print "[agents.fixer]";
+      print "description = \"bug fixer\"";
+      print "model_reasoning_effort = \"medium\"";
+      print "config_file = \"~/.codex/agents/fixer.toml\"";
+    }
+    if (!orch_emitted) {
+      print "";
+      print "[agents.orchestrator]";
+      print "description = \"orchestrator\"";
+      print "config_file = \"~/.codex/agents/orchestrator.toml\"";
+    }
+    if (!reviewer_emitted) {
+      print "";
+      print "[agents.reviewer]";
+      print "description = \"reviewer\"";
+      print "config_file = \"~/.codex/agents/reviewer.toml\"";
+    }
+    if (!spark_emitted) {
+      print "";
+      print "[agents.spark]";
+      print "description = \"spark\"";
+      print "config_file = \"~/.codex/agents/spark.toml\"";
+    }
+  }' "$cfg_file" >"$tmp_file"
+
+  mv "$tmp_file" "$cfg_file"
+}
+
+check_codex_config() {
+  local cfg_file
+  cfg_file="$CODEX_HOME/config.toml"
+  [[ -f "$cfg_file" ]] || return 1
+
+  awk '
+  BEGIN {
+    in_features=0; in_agents=0; in_fixer=0; in_orch=0; in_reviewer=0; in_spark=0;
+    ok_features=0; ok_threads=0; ok_fixer_desc=0; ok_fixer_reason=0; ok_fixer_cfg=0;
+    ok_orch_desc=0; ok_orch_cfg=0; ok_reviewer_desc=0; ok_reviewer_cfg=0; ok_spark_desc=0; ok_spark_cfg=0;
+  }
+  function trim(s) { gsub(/^[[:space:]]+|[[:space:]]+$/, "", s); return s }
+  {
+    line=trim($0);
+    sub(/[[:space:]]+#.*$/, "", line);
+    if (line ~ /^\[[^]]+\]$/) {
+      in_features=(line=="[features]");
+      in_agents=(line=="[agents]");
+      in_fixer=(line=="[agents.fixer]");
+      in_orch=(line=="[agents.orchestrator]");
+      in_reviewer=(line=="[agents.reviewer]");
+      in_spark=(line=="[agents.spark]");
+      next;
+    }
+    if (in_features && line ~ /^multi_agent[[:space:]]*=[[:space:]]*true$/) ok_features=1;
+    if (in_agents && line ~ /^max_threads[[:space:]]*=[[:space:]]*15$/) ok_threads=1;
+    if (in_fixer && line ~ /^description[[:space:]]*=[[:space:]]*"bug fixer"$/) ok_fixer_desc=1;
+    if (in_fixer && line ~ /^model_reasoning_effort[[:space:]]*=[[:space:]]*"medium"$/) ok_fixer_reason=1;
+    if (in_fixer && line ~ /^config_file[[:space:]]*=[[:space:]]*"~\/\.codex\/agents\/fixer\.toml"$/) ok_fixer_cfg=1;
+    if (in_orch && line ~ /^description[[:space:]]*=[[:space:]]*"orchestrator"$/) ok_orch_desc=1;
+    if (in_orch && line ~ /^config_file[[:space:]]*=[[:space:]]*"~\/\.codex\/agents\/orchestrator\.toml"$/) ok_orch_cfg=1;
+    if (in_reviewer && line ~ /^description[[:space:]]*=[[:space:]]*"reviewer"$/) ok_reviewer_desc=1;
+    if (in_reviewer && line ~ /^config_file[[:space:]]*=[[:space:]]*"~\/\.codex\/agents\/reviewer\.toml"$/) ok_reviewer_cfg=1;
+    if (in_spark && line ~ /^description[[:space:]]*=[[:space:]]*"spark"$/) ok_spark_desc=1;
+    if (in_spark && line ~ /^config_file[[:space:]]*=[[:space:]]*"~\/\.codex\/agents\/spark\.toml"$/) ok_spark_cfg=1;
+  }
+  END {
+    ok = ok_features && ok_threads &&
+         ok_fixer_desc && ok_fixer_reason && ok_fixer_cfg &&
+         ok_orch_desc && ok_orch_cfg &&
+         ok_reviewer_desc && ok_reviewer_cfg &&
+         ok_spark_desc && ok_spark_cfg;
+    exit(ok ? 0 : 1);
+  }' "$cfg_file"
+}
+
 force_dx() {
   if ! install_pnpm; then
     DX_FORCE_OK=0
@@ -287,12 +533,20 @@ run_parallel_checks() {
     fi
   ) &
 
+  (
+    if check_codex_config; then
+      write_check_file "codex_config" "1" "$CODEX_HOME/config.toml" "ok" "$dir/codex_config.res"
+    else
+      write_check_file "codex_config" "0" "$CODEX_HOME/config.toml" "config.toml 缺失或配置不符合要求" "$dir/codex_config.res"
+    fi
+  ) &
+
   wait
   LAST_CHECK_DIR="$dir"
 }
 
 all_good() {
-  local keys="python3 python_alias pnpm dx agent_browser rg multi_agent"
+  local keys="python3 python_alias pnpm dx agent_browser rg multi_agent codex_config"
   local k
   for k in $keys; do
     if ! check_ok "$k"; then
@@ -309,7 +563,7 @@ print_report() {
   printf '%-14s | %-4s | %-40s | %s\n' "检查项" "状态" "版本" "说明"
   printf '%-14s-+-%-4s-+-%-40s-+-%s\n' "--------------" "----" "----------------------------------------" "------------------------------"
 
-  local keys="python3 python_alias pnpm dx agent_browser rg multi_agent"
+  local keys="python3 python_alias pnpm dx agent_browser rg multi_agent codex_config"
   local k ok txt ver msg
   for k in $keys; do
     ok="$(read_field "$k" 2)"
@@ -368,6 +622,11 @@ for round in $(seq 1 "$MAX_ROUNDS"); do
     ensure_multi_agent || true
   fi
 
+  if ! check_ok "codex_config"; then
+    echo "[doctor] 修正 ~/.codex/config.toml 关键配置"
+    ensure_codex_config || true
+  fi
+
   echo "[doctor] 强制执行 dx 安装与初始化"
   force_dx || true
 

package/codex/skills/pr-review-loop/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: pr-review-loop
+description: pr 审查
+---
+
+## 输入
+
+- `PR_NUMBER`
+- `round`（默认 1，由编排器控制）
+# PR 审核闭环（技能主编排）
+
+本文件是该技能的**唯一编排真值源**。不要再依赖独立的编排 md 文件。
+
+## 适用场景
+
+- 用户要求对某个 GitHub PR 执行“审核 -> 修复 -> 再审核”的循环。
+- 需要严格执行 `runId` 透传、`./.cache` 交接、Decision Log 持久化。
+- 需要确保修复动作由专职 `fixer` 角色执行，而不是编排器直接改代码。
+
+## 目录约定
+
+- 子代理说明：`${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/*.md`
+- 确定性脚本：`${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/*.py`
+- 缓存目录：`./.cache/`
+- 网络要求：`reviewer / aggregator / fixer ` 角色应启用 `network_access = true`。
+
+## 输入
+
+- `PR_NUMBER`
+- `round`（默认 1，由编排器控制）
+
+## runId（强制）
+
+- 格式：`<PR>-<ROUND>-<HEAD_SHORT>`
+- 生成者：`pr_context.py`（或 precheck 输出中的同格式值）
+- 后续所有阶段仅允许透传，禁止重算或篡改。
+
+## 角色分工（强制）
+
+- `reviewer`：并行执行审查，产出 reviewFile。
+- `fixer`：执行修复、提交推送、维护 decision-log、产出 fixReportFile。
+- `spark`：通用agent 根据提示词执行通用任务。
+
+## 阶段 0：预检 gate（必须先通过）
+
+调用 `spark`，输入：
+--prompt： `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/pr-precheck.md`
+--others： `PR #<PR_NUMBER> - round <1>`
+
+处理规则：
+
+- 若返回 `{"ok":true}`：进入下一阶段。
+- 若返回 `{"error":"..."}`：立即终止流程，不重试；直接透传 precheck 的简短失败原因（可附带 `fixFile`）。
+
+说明：阶段 0 是强 gate，不允许修复后重跑，也不进入“错误分级与重试”。
+
+
+## Step 1: 生成上下文（串行）
+
+调用 `spark`，输入：
+--prompt： `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/pr-context.md`
+--others： `PR #<PR_NUMBER> - round <1>`
+
+- 等待 spark 返回，输出必须包含 `contextFile`、`runId`、`headOid`。
+- 检查 `./.cache/decision-log-pr<PR_NUMBER>.md` 是否存在，存在则后续传给 reviewer 以供决策过滤。
+- 若失败：按“错误分级与重试”处理。
+
+
+## 阶段 2~N：最多 3 轮循环
+### Step 2: reviewers 并行（唯一允许并行阶段）
+
+并行调用同一个 `reviewer` 角色的多个实例（提示词驱动实体），至少包含以下 3 个提示词：
+
+- `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/security-reviewer.md`
+- `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/logic-reviewer.md`
+- `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/style-reviewer.md`
+
+每个 reviewer 实例输入至少包含：
+
+- `PR #<PR_NUMBER>`
+- `round: <ROUND>`
+- `runId: <RUN_ID>` 来自 Step 1 的输出，必须透传，禁止自行生成）
+- `contextFile: ./.cache/<file>.md`
+- `reviewerPromptFile: <上述 md 之一>`
+- `reviewerPromptContent: <reviewerPromptFile 的全文>`
+- `decisionLogFile: ./.cache/decision-log-pr<PR_NUMBER>.md`（若存在）
+
+执行要求：
+
+- reviewer 必须先读取 `reviewerPromptFile`，并严格按其中规则执行。
+- 若调用框架不自动注入文件内容，orchestrator 必须显式把 `reviewerPromptContent` 一并传给 reviewer。
+- 当通用 reviewer 约束与 `reviewerPromptFile` 冲突时，以 `reviewerPromptFile` 为准。
+- `security-reviewer` 专注安全与权限边界；`logic-reviewer` 专注逻辑正确性与边界条件；`style-reviewer` 专注可维护性、可读性与工程规范；`gh-thread-reviewer` 专注外部评论采集与归一化。
+
+每个 reviewer 实例输出：
+
+- `reviewFile: ./.cache/<file>.md`
+
+### Step 3: 聚合（模式 A）
+
+调用 `spark`，输入：
+--prompt： `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/pr-review-aggregate.md`
+--others： `contextFile + 1..n reviewFile + runId (+ decisionLogFile) + 模式 A`。
+
+- 输出 `{"stop":true}`：本轮结束并退出循环。
+- 输出 `{"stop":false,"fixFile":"..."}`：进入 Step 4。
+- 输出 `{"error":"GH_PR_COMMENT_FAILED"}`：按可重试错误处理，优先重试本步骤（脚本幂等，重复调用安全）。
+- 其他 `{"error":"..."}`：按“错误分级与重试”处理。
+
+### Step 4: 修复（必须委托 fixer）
+
+**此步禁止 orchestrator 直接修复代码。**
+
+必须调用 `fixer`，输入：
+
+- `PR #<PR_NUMBER>`
+- `round: <ROUND>`
+- `runId: <RUN_ID>`
+- `fixFile: ./.cache/<file>.md`
+
+期望输出：
+
+- `fixReportFile: ./.cache/<file>.md`
+
+### Step 5: 发布修复报告（模式 B）
+
+调用 `spark`，输入：
+--prompt： `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/pr-review-aggregate.md`
+--others： `fixReportFile + runId + round` + 模式 B`。
+
+
+- 期望输出：`{"ok":true}`
+- 若返回 `{"error":"GH_PR_COMMENT_FAILED"}`：按可重试错误处理后再判定终止。
+
+### Step 6: 下一轮
+
+- 轮次 round +1，回到 Step 2。
+- 总轮次上限 3。
+
+## Step 7 收尾（强制）
+
+- 若某轮 Step 3 返回 `stop=true`：发布 final-report = `RESOLVED`。
+- 若达到 3 轮仍未 stop：发布 final-report = `MAX_ROUNDS_REACHED`。
+
+final-report 由 `aggregator` 调用脚本发布，且幂等。
+
+## 失败防护建议
+
+- 如果日志显示“编排器直接改代码而非调用 fixer”，视为流程违约。
+- 直接回滚该轮并重新执行，确保 Step 4 通过 `fixer` 完成。
+
+
+## 编排硬规则（强制）
+
+1. 除 reviewer 阶段外，其余步骤必须串行且 await 返回。
+2. 每轮最多发布一次 Review Summary / Fix Report（由脚本幂等保证）。
+3. `orchestrator` **禁止直接修改业务代码**。
+4. 当 aggregate 返回 `stop=false` 时，`orchestrator` **必须调用 `fixer` 角色**处理 `fixFile`。
+5. 如果无法调用 `fixer`，必须终止并返回 `{"error":"FIXER_NOT_INVOKED"}`（或等价错误），禁止降级为 orchestrator 自修。
+
+## 错误分级与重试（强制）
+
+默认策略不是“见 error 立刻终止”，而是先分级：
+
+1. 可重试错误：先重试再决定终止。
+2. 不可恢复错误：立即终止。
+
+例外：阶段 0（预检 gate）不适用本节重试策略；除 `ok:true` 外，其余返回（含任意 `error`）都必须立即终止。
+
+### 可重试错误（建议最多 2 次重试，合计最多 3 次尝试）
+
+- `GH_PR_COMMENT_FAILED`
+- `HARVEST_FAILED`
+- `AGGREGATE_SCRIPT_FAILED`
+- `PR_CONTEXT_SCRIPT_FAILED`
+- `GIT_PUSH_FAILED_NETWORK`
+- 其他明显网络抖动/平台瞬时错误（例如 gh API 超时）
+
+重试要求：
+
+- 使用**同一组输入**重试同一步骤（保持 `runId` 不变）。
+- 使用退避：第 1 次重试前等待 2 秒，第 2 次重试前等待 5 秒。
+- 可先做轻量自愈检查：`gh auth status`、`git remote get-url origin`、必要时重跑本步骤脚本。
+- 若是 `fixer` 推送失败，错误码统一为 `GIT_PUSH_FAILED_NETWORK`，由编排器按可重试错误处理。
+- 若重试后成功，继续流程，不得误判为终止。
+- 若重试仍失败，才终止当前轮。
+
+### 不可恢复错误（立即终止）
+
+- 参数/协议错误：`INVALID_ARGS`、`MISSING_*`
+- 环境错误：`NOT_A_GIT_REPO`、`GH_CLI_NOT_FOUND`
+- 权限/资源错误：`PR_NOT_FOUND_OR_NO_ACCESS`
+- 流程违约错误：`FIXER_NOT_INVOKED`
+
+
+执行原则：
+- 优先调用 `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/*.py` 作为确定性真值源。
+- 不在编排层做“聪明猜测”来替代脚本返回。
+- 对外输出只保留关键状态、产物路径与下一步动作。

package/codex/skills/pr-review-loop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PR 审核闭环"
+  short_description: "在当前仓库执行 precheck-context-review-fix 多轮闭环"
+  default_prompt: "使用 $pr-review-loop 在当前仓库对指定 PR 执行最多三轮审核修复循环，并严格遵守 runId 与 decision-log 约束。"

package/codex/skills/pr-review-loop/references/agents/logic-reviewer.md

@@ -0,0 +1,22 @@
+# PR Reviewer (Logic)
+
+## 角色码（强制）
+
+- `ROLE_CODE = LOG`
+- `reviewFile`: `./.cache/review-LOG-pr<PR_NUMBER>-r<ROUND>-<RUN_ID>.md`
+- findings id 前缀：`LOG-`
+
+## 专责范围（强制）
+
+- 仅关注逻辑正确性：业务分支正确性、边界条件、空值/异常路径、状态机转换、并发一致性、事务边界、幂等性、回滚与补偿
+- 非逻辑类建议（纯命名/排版/文风）默认不提
+
+## 逻辑审核词（执行清单）
+
+1. 状态迁移：状态机是否存在非法跳转、漏转移、重复转移。
+2. 分支完备性：主流程、异常流程、空值分支、极端边界是否闭合。
+3. 一致性与幂等：重复请求、重试、并发写入是否导致脏数据或重复副作用。
+4. 事务与补偿：事务边界是否正确，失败后是否可回滚或补偿。
+5. 时序与竞态：异步回调/事件驱动下是否存在先后顺序依赖漏洞。
+6. 数据约束：校验、默认值、转换规则是否与业务语义一致。
+7. 高风险优先级：会造成业务错误结论、资金/库存/配额错误的，优先判为 P0/P1。