@ranger1/dx 0.1.88 → 0.1.90

package/codex/agents/reviewer.toml

@@ -34,9 +34,19 @@ developer_instructions = '''
    - `# Review (<ROLE_CODE>)`
    - `PR: <PR_NUMBER>`
    - `Round: <ROUND>`
-   - `## Summary`，含 `P0/P1/P2/P3` 四行计数
-   - `## Findings`，每条 finding 包含：
+   - `RunId: <RUN_ID>`
+   - `## Findings`
+   - 若无问题，`## Findings` 段内容必须仅为 `None`
+   - 若有问题，每条 finding 必须使用固定 key-value 块，字段为：
      `id / priority / category / file / line / title / description / suggestion`
-10. 最终响应只输出一行：`reviewFile: ./.cache/<file>.md`。
+   - 禁止输出 `## Summary`、表格、额外总结 prose、代码块或嵌套列表。
+10. 输出前必须自检：
+   - `PR / Round / RunId` 与输入完全一致。
+   - 每个 finding 字段齐全且非空。
+   - `priority` 只能是 `P0 / P1 / P2 / P3`。
+   - `line` 必须是单个数字；未知时写 `null`。
+   - `id` 前缀与 `<ROLE_CODE>-` 一致。
+11. 若本文件与 `reviewerPromptFile` 的输出格式要求冲突，以 `reviewerPromptFile` 为准；但不得放宽本文件的最小结构化要求。
+12. 最终响应只输出一行：`reviewFile: ./.cache/<file>.md`。
 
 '''

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

@@ -22,7 +22,7 @@ description: pr 审查
 - 子代理说明：`${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`。
+
 
 ## 输入
 
@@ -101,6 +101,16 @@ reviewer 配置检测由 `pr-precheck` 执行，并且必须在其他预检动
 --prompt： `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/references/agents/pr-review-aggregate.md`
 --others： `contextFile + 1..n reviewFile + runId (+ decisionLogFile) + 模式 A`。
 
+执行约束：
+
+- `spark` 必须先读取 `contextFile` 与全部 `reviewFile`，由模型完成最终语义裁决。
+- `spark` 必须自行判定：
+  - 是否 `stop`
+  - 哪些 finding 进入 `mustFixFindings`
+  - 哪些 finding 进入 `optionalFindings`
+- `spark` 必须把上述裁决编码为结构化聚合结果，再交给脚本发布评论与生成 `fixFile`。
+- 脚本在此步**不得**再根据 reviewer 原文自行推断“有没有问题”或 `stop`。
+
 - 输出 `{"stop":true}`：进入 Step 7 本轮结束退出循环。
 - 输出 `{"stop":false,"fixFile":"..."}`：进入 Step 4。
 - 输出 `{"error":"GH_PR_COMMENT_FAILED"}`：按可重试错误处理，优先重试本步骤（脚本幂等，重复调用安全）。
@@ -194,5 +204,6 @@ final-report 由 `aggregator` 调用脚本发布，且幂等。
 
 执行原则：
 - 优先调用 `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/*.py` 作为确定性真值源。
-- 不在编排层做“聪明猜测”来替代脚本返回。
+- 但“是否有问题 / 是否 stop / finding 分级”属于模型语义裁决，不得再由脚本根据 reviewer 原文二次猜测。
+- reviewer 或 aggregate 产物若缺少关键字段，必须失败并显式报错；禁止静默降级为“无问题”。
 - 对外输出只保留关键状态、产物路径与下一步动作。

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

@@ -20,6 +20,9 @@
 - 项目根目录必须存在 `./reviewer/` 目录。
 - `./reviewer/` 下必须至少有一个 `*-reviewer.md` 文件。
 - 每个 `*-reviewer.md` 文件都必须包含 `ROLE_CODE = <CODE>`（例如 `ROLE_CODE = STY`）。
+- 必须执行：
+- `python3 "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/validate_reviewer_prompts.py" ./reviewer/*-reviewer.md`
+- 若脚本返回非零或输出 `ok != true`，视为 reviewer 输出契约不合法。
 - 若上述任一条件不满足，立即终止并返回：`{"error":"REVIEWER_CONFIG_INVALID","detail":"..."}`。
 
 2. 参数校验

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

@@ -45,26 +45,78 @@ runId: 123-1-a1b2c3d
 
 ## 执行方式（强制）
 
-所有确定性工作（解析/聚合/发评论/生成 fixFile/输出 JSON）都由 `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_aggregate.py` 完成。
+所有确定性工作（发评论/生成 fixFile/输出 JSON）都由 `${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_aggregate.py` 完成。
 
-你只做两件事：
+你只做三件事：
 
-1) 在模式 A 里用大模型判断哪些 finding 是重复的，并把重复分组作为参数传给脚本（不落盘）。
-2) 调用脚本后，把脚本 stdout 的 JSON **原样返回**给调用者（不做解释/分析）。
+1) 在模式 A 里读取 `contextFile`、所有 `reviewFile`，由大模型做最终语义裁决。
+2) 产出一份**结构化聚合结果 JSON**，再把它作为参数传给脚本（不落盘）。
+3) 调用脚本后，把脚本 stdout 的 JSON **原样返回**给调用者（不做解释/分析）。
 
-## 重复分组（仅作为脚本入参）
+## 最终裁决边界（强制）
 
-你需要基于所有 `reviewFile` 内容判断重复 finding 分组，生成**一行 JSON**（不要代码块、不要解释文字、不要换行）。
+- “是否存在问题”“哪些问题必须修”“是否可以 stop” 都由你基于 `reviewFile` 语义判断。
+- 脚本**不再**根据 reviewer 文本自行推断 `P0/P1`、`stop` 或“有没有问题”。
+- 如果 reviewer 文本里缺少关键信息，导致你无法可靠裁决，必须返回错误；禁止把不确定性伪装成 `stop=true`。
 
-注意：这行 JSON **不是你的最终输出**，它只用于生成 `--duplicate-groups-b64` 传给脚本。
+## 聚合结果 JSON（模式 A 必须生成）
+
+你需要基于 `contextFile`、所有 `reviewFile`，先完成这些判断：
+
+- 去重：本质相同的问题只保留一条
+- decision-log 过滤：已 fixed 的问题过滤；已 rejected 的问题仅在满足升级质疑条件时保留
+- 分级：把保留的问题分成 `mustFixFindings` 和 `optionalFindings`
+- 终止判断：仅当你确认没有 `mustFixFindings` 时，才可令 `stop=true`
+
+然后输出一行 JSON，结构固定如下：
 
 ```json
-{"duplicateGroups":[["PERF-001","BIZ-003"],["MAINT-002","BIZ-005","SEC-004"]]}
+{
+  "stop": false,
+  "mustFixFindings": [
+    {
+      "id": "SEC-001",
+      "priority": "P1",
+      "category": "bug",
+      "file": "apps/api/src/service.ts",
+      "line": "10",
+      "title": "标题",
+      "description": "描述",
+      "suggestion": "建议"
+    }
+  ],
+  "optionalFindings": [
+    {
+      "id": "STY-002",
+      "priority": "P3",
+      "category": "quality",
+      "file": "apps/web/src/page.tsx",
+      "line": "22",
+      "title": "标题",
+      "description": "描述",
+      "suggestion": "建议"
+    }
+  ]
+}
 ```
 
+强约束：
+
+- 必须是一行 JSON，不要代码块，不要解释。
+- `stop=true` 时，`mustFixFindings` 必须为空数组。
+- `stop=false` 时，`mustFixFindings` 必须至少有一条。
+- 每个 finding 必须包含这些字段且非空：`id`、`priority`、`category`、`file`、`line`、`title`、`description`、`suggestion`
+- `priority` 只能是 `P0` / `P1` / `P2` / `P3`
+- `mustFixFindings` 只允许 `P0` / `P1`
+- `optionalFindings` 只允许 `P2` / `P3`
+
+## 重复分组与 decision-log（仅作为你的思考步骤）
+
+你仍然需要基于所有 `reviewFile` 内容判断重复问题和 decision-log 匹配，但这些中间结果**不再**单独传给脚本；它们只体现在最终的聚合结果 JSON 里。
+
 ## 智能匹配（仅在模式 A + decision-log 存在时）
 
-如果 decision-log（`./.cache/decision-log-pr<PR_NUMBER>.md`）存在，你需要基于 LLM 判断每个新 finding 与已决策问题的本质是否相同，从而生成 **escalation_groups** 参数。
+如果 decision-log（`./.cache/decision-log-pr<PR_NUMBER>.md`）存在，你需要基于 LLM 判断每个新 finding 与已决策问题的本质是否相同，并把判断结果体现在最终聚合结果里。
 
 **匹配原则**：
 - **Essence 匹配**：对比 `essence` 字段与新 finding 的问题本质。
@@ -84,23 +136,11 @@ runId: 123-1-a1b2c3d
    - 例如：已 rejected P3 but finding 为 P1 → 可升级质疑
    - 例如：已 rejected P2 but finding 为 P0 → 可升级质疑
    - 例如：已 rejected P2 but finding 为 P1 → 不升级（仅差 1 级）
-5. 生成**一行 JSON**（不要代码块、不要解释文字、不要换行），结构如下：
-
-```json
-{"escalationGroups":[["SEC-001"],["MAINT-002","BIZ-005"]]}
-```
-
-其中每个组表示「可以作为已 rejected 问题的升级质疑」的 finding ID 集合。若无可升级问题，输出空数组：
-
-```json
-{"escalationGroups":[]}
-```
-
-注意：escalation_groups JSON **不是你的最终输出**，它只用于生成 `--escalation-groups-b64` 传给脚本。
+5. 只把满足条件的升级问题保留到最终 `mustFixFindings` 或 `optionalFindings`；其余继续按 rejected 过滤。
 
 ## 调用脚本（强制）
 
-模式 A（带 reviewFile + 重复分组 + 智能匹配）：
+模式 A（带 reviewFile + 聚合结果）：
 
 ```bash
 python3 "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_aggregate.py" \
@@ -111,16 +151,12 @@ python3 "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_agg
   --review-file <REVIEW_FILE_1> \
   --review-file <REVIEW_FILE_2> \
   --review-file <REVIEW_FILE_3> \
-  --duplicate-groups-b64 <BASE64_JSON> \
-  --decision-log-file ./.cache/decision-log-pr<PR_NUMBER>.md \
-  --escalation-groups-b64 <BASE64_JSON>
+  --aggregate-result-b64 <BASE64_JSON>
 ```
 
 **参数说明**：
 
-- `--duplicate-groups-b64`：base64 编码的 JSON，格式同上，例如 `eyJkdXBsaWNhdGVHcm91cHMiOltbIkNEWC0wMDEiLCJDTEQtMDAzIl1dfQ==`
-- `--decision-log-file`：decision-log 文件路径（可选；若不存在则跳过智能匹配逻辑）
-- `--escalation-groups-b64`：base64 编码的 escalation groups JSON，格式如上，例如 `eyJlc2NhbGF0aW9uR3JvdXBzIjpbWyJDRFgtMDAxIl1dfQ==`
+- `--aggregate-result-b64`：base64 编码的聚合结果 JSON
 
 模式 B（带 fixReportFile）：
 
@@ -146,7 +182,7 @@ python3 "${CODEX_HOME:-$HOME/.codex}/skills/pr-review-loop/scripts/pr_review_agg
 
 ## fixFile 结构（补充说明）
 
-脚本在模式 A 下生成的 fixFile 分为两段：
+脚本在模式 A 下根据你提供的聚合结果生成 fixFile，分为两段：
 
 - `## IssuesToFix`：只包含 P0/P1（必须修）
 - `## OptionalIssues`：包含 P2/P3（由 fixer 自主决定是否修复，或拒绝并说明原因）

package/codex/skills/pr-review-loop/scripts/pr_review_aggregate.py

@@ -2,16 +2,18 @@
 # Deterministic PR review aggregation (script owns all rules).
 #
 # Workflow:
-# - Mode A: read contextFile + reviewFile(s) from project cache: ./.cache/, parse findings, merge duplicates,
+# - Mode A: read contextFile + reviewFile(s) from project cache: ./.cache/, consume an LLM-produced aggregate result,
 #   post a single PR comment, and generate a fixFile for fixer.
 # - Mode B: read fixReportFile from cache and post it as a PR comment.
 #
 # Input rules:
 # - Callers should pass repo-relative paths (e.g. ./.cache/foo.md). For backward-compat, basenames are also accepted.
-# - Duplicate groups come from LLM but are passed as an argument (NOT written to disk).
-#   - Prefer: --duplicate-groups-b64 <base64(json)>
-#   - Also supported: --duplicate-groups-json '<json>'
-#   - Invalid/missing duplicate groups => treated as no dedupe (do not fail).
+# - Aggregate result comes from LLM and is passed as an argument (NOT written to disk).
+#   - Prefer: --aggregate-result-b64 <base64(json)>
+#   - Also supported: --aggregate-result-json '<json>'
+#   - Missing/invalid aggregate result => fail closed.
+# - Duplicate groups / escalation groups may still be passed for backward-compatible tooling,
+#   but they are no longer used by this script to decide findings or stop.
 #
 # Output rules:
 # - Stdout must print exactly ONE JSON object and nothing else.
@@ -459,6 +461,101 @@ def _parse_review_findings(md_text):
     return normalized
 
 
+def _normalize_aggregate_finding(it):
+    if not isinstance(it, dict):
+        return None
+
+    required_fields = [
+        "id",
+        "priority",
+        "category",
+        "file",
+        "line",
+        "title",
+        "description",
+        "suggestion",
+    ]
+    for field in required_fields:
+        val = it.get(field)
+        if not isinstance(val, str) or not val.strip():
+            return None
+
+    priority = it.get("priority", "").strip().upper()
+    if priority not in {"P0", "P1", "P2", "P3"}:
+        return None
+
+    return {
+        "id": it["id"].strip(),
+        "priority": priority,
+        "category": it["category"].strip(),
+        "file": it["file"].strip(),
+        "line": it["line"].strip(),
+        "title": it["title"].strip(),
+        "description": it["description"].strip(),
+        "suggestion": it["suggestion"].strip(),
+    }
+
+
+def _normalize_aggregate_findings(items):
+    if not isinstance(items, list):
+        return None
+
+    out = []
+    for it in items:
+        normalized = _normalize_aggregate_finding(it)
+        if not normalized:
+            return None
+        out.append(normalized)
+    return out
+
+
+def _parse_aggregate_result_json(s):
+    if not s:
+        return None
+    try:
+        data = json.loads(s)
+    except Exception:
+        return None
+
+    if not isinstance(data, dict):
+        return None
+
+    stop = data.get("stop")
+    if not isinstance(stop, bool):
+        return None
+
+    must_fix = _normalize_aggregate_findings(data.get("mustFixFindings"))
+    optional = _normalize_aggregate_findings(data.get("optionalFindings"))
+    if must_fix is None or optional is None:
+        return None
+
+    if any(_priority_rank(f.get("priority")) > 1 for f in must_fix):
+        return None
+    if any(_priority_rank(f.get("priority")) < 2 for f in optional):
+        return None
+
+    if stop and must_fix:
+        return None
+    if (not stop) and (not must_fix):
+        return None
+
+    return {
+        "stop": stop,
+        "mustFixFindings": must_fix,
+        "optionalFindings": optional,
+    }
+
+
+def _parse_aggregate_result_b64(s):
+    if not s:
+        return None
+    try:
+        raw = base64.b64decode(s.encode("ascii"), validate=True)
+        return _parse_aggregate_result_json(raw.decode("utf-8", errors="replace"))
+    except Exception:
+        return None
+
+
 def _merge_duplicates(findings, duplicate_groups):
     by_id = {f["id"]: dict(f) for f in findings}
     merged_map = {}
@@ -685,6 +782,8 @@ def main(argv):
     parser.add_argument("--review-file", action="append", default=[])
     parser.add_argument("--fix-report-file")
     parser.add_argument("--final-report")
+    parser.add_argument("--aggregate-result-json")
+    parser.add_argument("--aggregate-result-b64")
     parser.add_argument("--duplicate-groups-json")
     parser.add_argument("--duplicate-groups-b64")
     parser.add_argument("--decision-log-file")
@@ -759,36 +858,22 @@ def main(argv):
         return 1
 
     raw_reviews = []
-    all_findings = []
     for rf in review_files:
         md = _read_cache_text(rf)
         raw_reviews.append((rf, md))
-        all_findings.extend(_parse_review_findings(md))
+    aggregate_result = _parse_aggregate_result_json(args.aggregate_result_json or "")
+    if not aggregate_result:
+        aggregate_result = _parse_aggregate_result_b64(args.aggregate_result_b64 or "")
+    if not aggregate_result:
+        _json_out({"error": "INVALID_AGGREGATE_RESULT"})
+        return 1
 
-    duplicate_groups = _parse_duplicate_groups_json(args.duplicate_groups_json or "")
-    if not duplicate_groups:
-        duplicate_groups = _parse_duplicate_groups_b64(args.duplicate_groups_b64 or "")
-    merged_findings, merged_map = _merge_duplicates(all_findings, duplicate_groups)
-    
-    decision_log_file = (args.decision_log_file or "").strip() or None
-    prior_decisions = []
-    if decision_log_file:
-        try:
-            decision_log_md = _read_cache_text(decision_log_file)
-            prior_decisions = _parse_decision_log(decision_log_md)
-        except Exception:
-            pass
-    
-    escalation_groups = _parse_escalation_groups_b64(args.escalation_groups_b64 or "")
-    
-    if prior_decisions:
-        merged_findings = _filter_by_decision_log(merged_findings, prior_decisions, escalation_groups)
-    
+    must_fix = list(aggregate_result["mustFixFindings"])
+    optional = list(aggregate_result["optionalFindings"])
+    merged_findings = must_fix + optional
+    merged_map = {}
     counts = _counts(merged_findings)
-
-    must_fix = [f for f in merged_findings if _priority_rank(f.get("priority")) <= 1]
-    optional = [f for f in merged_findings if _priority_rank(f.get("priority")) >= 2]
-    stop = len(must_fix) == 0
+    stop = bool(aggregate_result["stop"])
 
     body = _render_mode_a_comment(pr_number, round_num, run_id, counts, must_fix, merged_map, raw_reviews)
     body_basename = f"review-aggregate-comment-pr{pr_number}-r{round_num}-{run_id}.md"

package/codex/skills/pr-review-loop/scripts/test_pr_review_aggregate.py

@@ -48,6 +48,10 @@ _parse_review_findings = cast(
     Callable[[str], list[dict[str, object]]],
     getattr(_pr_review_aggregate, "_parse_review_findings"),
 )
+_parse_aggregate_result_json = cast(
+    Callable[[str], dict[str, object] | None],
+    getattr(_pr_review_aggregate, "_parse_aggregate_result_json"),
+)
 _check_existing_comment = cast(
     Callable[[int, str, int, str], bool],
     getattr(_pr_review_aggregate, "_check_existing_comment"),
@@ -562,6 +566,127 @@ def test_parse_review_findings_keeps_legacy_list_format() -> None:
     assert result[0]["priority"] == "P1"
 
 
+# ============================================================
+# Test: _parse_aggregate_result_json()
+# ============================================================
+
+def test_parse_aggregate_result_json_valid() -> None:
+    """模型给出的聚合结果应被脚本按结构化数据接收。"""
+    raw = json.dumps(
+        {
+            "stop": False,
+            "mustFixFindings": [
+                {
+                    "id": "SEC-001",
+                    "priority": "P1",
+                    "category": "bug",
+                    "file": "apps/api/src/service.ts",
+                    "line": "10",
+                    "title": "标题",
+                    "description": "描述",
+                    "suggestion": "建议",
+                }
+            ],
+            "optionalFindings": [
+                {
+                    "id": "STY-002",
+                    "priority": "P3",
+                    "category": "quality",
+                    "file": "apps/web/src/page.tsx",
+                    "line": "22",
+                    "title": "样式建议",
+                    "description": "描述",
+                    "suggestion": "建议",
+                }
+            ],
+        },
+        ensure_ascii=True,
+    )
+
+    result = _parse_aggregate_result_json(raw)
+
+    assert result is not None
+    assert result["stop"] is False
+    assert len(cast(list[dict[str, object]], result["mustFixFindings"])) == 1
+    assert len(cast(list[dict[str, object]], result["optionalFindings"])) == 1
+
+
+def test_parse_aggregate_result_json_rejects_missing_required_fields() -> None:
+    """缺关键字段时必须失败，不能静默降级成 stop=true。"""
+    raw = json.dumps(
+        {
+            "stop": False,
+            "mustFixFindings": [
+                {
+                    "id": "SEC-001",
+                    "file": "apps/api/src/service.ts",
+                    "line": "10",
+                    "title": "标题",
+                    "description": "描述",
+                    "suggestion": "建议",
+                }
+            ],
+            "optionalFindings": [],
+        },
+        ensure_ascii=True,
+    )
+
+    result = _parse_aggregate_result_json(raw)
+    assert result is None
+
+
+def test_parse_aggregate_result_json_rejects_stop_true_with_must_fix() -> None:
+    """stop=true 时不允许同时带 must-fix，避免协议自相矛盾。"""
+    raw = json.dumps(
+        {
+            "stop": True,
+            "mustFixFindings": [
+                {
+                    "id": "SEC-009",
+                    "priority": "P0",
+                    "category": "bug",
+                    "file": "apps/api/src/service.ts",
+                    "line": "99",
+                    "title": "标题",
+                    "description": "描述",
+                    "suggestion": "建议",
+                }
+            ],
+            "optionalFindings": [],
+        },
+        ensure_ascii=True,
+    )
+
+    result = _parse_aggregate_result_json(raw)
+    assert result is None
+
+
+def test_parse_aggregate_result_json_rejects_wrong_bucket_priority() -> None:
+    """must-fix 与 optional 的优先级分桶必须严格一致。"""
+    raw = json.dumps(
+        {
+            "stop": False,
+            "mustFixFindings": [
+                {
+                    "id": "STY-010",
+                    "priority": "P2",
+                    "category": "quality",
+                    "file": "apps/api/src/service.ts",
+                    "line": "12",
+                    "title": "标题",
+                    "description": "描述",
+                    "suggestion": "建议",
+                }
+            ],
+            "optionalFindings": [],
+        },
+        ensure_ascii=True,
+    )
+
+    result = _parse_aggregate_result_json(raw)
+    assert result is None
+
+
 # ============================================================
 # Test: Integration - Full Workflow
 # ============================================================

package/codex/skills/pr-review-loop/scripts/test_validate_reviewer_prompts.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+Unit tests for validate_reviewer_prompts.py.
+"""
+
+import importlib.util
+from pathlib import Path
+from typing import Callable, cast
+
+
+def _load_module():
+    module_path = Path(__file__).with_name("validate_reviewer_prompts.py")
+    spec = importlib.util.spec_from_file_location("validate_reviewer_prompts", module_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Failed to load module spec: {module_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_module = _load_module()
+_validate_prompt_text = cast(Callable[[str], list[str]], getattr(_module, "_validate_prompt_text"))
+
+
+def test_validate_prompt_text_accepts_complete_contract() -> None:
+    text = """
+# PR Reviewer (Security)
+
+## 角色码（强制）
+
+- `ROLE_CODE = SEC`
+- `reviewFile`: `./.cache/review-SEC-pr<PR_NUMBER>-r<ROUND>-<RUN_ID>.md`
+- findings id 前缀：`SEC-`
+
+## 输出格式（强制）
+
+- 必须写入 `reviewFile`，禁止只在 stdout 输出审查结果。
+- 若无问题，文件内容必须严格为以下模板：
+
+```md
+# Review (SEC)
+PR: 123
+Round: 1
+RunId: 123-1-abcdef0
+
+## Findings
+None
+```
+
+- 若有问题，每个 finding 必须使用如下块格式，字段名必须逐字一致：
+
+```md
+# Review (SEC)
+PR: 123
+Round: 1
+RunId: 123-1-abcdef0
+
+## Findings
+id: SEC-001
+priority: P1
+category: bug
+file: apps/api/src/service.ts
+line: 10
+title: 标题
+description: 描述
+suggestion: 建议
+```
+
+- `priority` 只能是 `P0`、`P1`、`P2`、`P3`。
+- `category` 只允许使用英文小写单词或短语。
+- `line` 必须是单个行号数字；未知时写 `null`。
+- 多个 finding 之间必须空一行；禁止额外嵌套列表、表格、代码块或总结性 prose。
+- 输出前必须自检：字段齐全、非空、前缀与 `ROLE_CODE` 一致。
+"""
+
+    assert _validate_prompt_text(text) == []
+
+
+def test_validate_prompt_text_reports_missing_contract_sections() -> None:
+    text = """
+# PR Reviewer (Style)
+
+## 角色码（强制）
+
+- `ROLE_CODE = STY`
+- `reviewFile`: `./.cache/review-STY-pr<PR_NUMBER>-r<ROUND>-<RUN_ID>.md`
+"""
+
+    errors = _validate_prompt_text(text)
+    assert any("输出格式（强制）" in err for err in errors)
+    assert any("None" in err for err in errors)
+    assert any("priority" in err for err in errors)

package/codex/skills/pr-review-loop/scripts/validate_reviewer_prompts.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""
+Validate reviewer prompt files contain the required output contract.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+REQUIRED_SNIPPETS = [
+    "## 输出格式（强制）",
+    "## Findings",
+    "None",
+    "id:",
+    "priority:",
+    "category:",
+    "file:",
+    "line:",
+    "title:",
+    "description:",
+    "suggestion:",
+]
+
+
+def _validate_prompt_text(text: str) -> list[str]:
+    errors: list[str] = []
+    for snippet in REQUIRED_SNIPPETS:
+        if snippet not in text:
+            errors.append(f"缺少必需片段: {snippet}")
+
+    role_match = re.search(r"ROLE_CODE\s*=\s*([A-Z0-9]+)", text)
+    if not role_match:
+        errors.append("缺少 ROLE_CODE = <CODE>")
+        return errors
+
+    role_code = role_match.group(1)
+    if f"id: {role_code}-001" not in text:
+        errors.append(f"缺少与 ROLE_CODE 匹配的 finding id 示例: id: {role_code}-001")
+
+    review_file_pattern = rf"review-{role_code}-pr<PR_NUMBER>-r<ROUND>-<RUN_ID>\.md"
+    if not re.search(review_file_pattern, text):
+        errors.append(f"reviewFile 模板未与 ROLE_CODE 对齐: {role_code}")
+
+    return errors
+
+
+def _validate_file(path: Path) -> list[str]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception as exc:
+        return [f"文件不可读: {exc}"]
+    return _validate_prompt_text(text)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("paths", nargs="+")
+    args = parser.parse_args(argv)
+
+    invalid: dict[str, list[str]] = {}
+    checked: list[str] = []
+    for raw in args.paths:
+        path = Path(raw)
+        checked.append(str(path))
+        errors = _validate_file(path)
+        if errors:
+            invalid[str(path)] = errors
+
+    if invalid:
+        sys.stdout.write(
+            json.dumps(
+                {"ok": False, "checked": checked, "invalid": invalid},
+                ensure_ascii=False,
+            )
+            + "\n"
+        )
+        return 1
+
+    sys.stdout.write(json.dumps({"ok": True, "checked": checked}, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/lib/cli/commands/stack.js

@@ -38,6 +38,8 @@ class PM2StackManager {
       ? options.services.map(item => String(item).trim()).filter(Boolean)
       : [...DEFAULT_SERVICES]
 
+    this.urls = options.urls && typeof options.urls === 'object' ? options.urls : {}
+
     const incomingPreflight = options.preflight && typeof options.preflight === 'object'
       ? options.preflight
       : {}
@@ -211,6 +213,19 @@ class PM2StackManager {
       logger.warn(stderr)
     }
     logger.success('服务启动成功')
+    this.printServiceUrls()
+  }
+
+  printServiceUrls() {
+    const entries = Object.entries(this.urls)
+    if (entries.length === 0) return
+
+    console.log('')
+    logger.info('服务访问链接:')
+    for (const [service, url] of entries) {
+      console.log(`  ${service.padEnd(12)} → ${url}`)
+    }
+    console.log('')
   }
 
   async showStatus() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranger1/dx",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "type": "module",
   "license": "MIT",
   "repository": {