@ranger1/dx 0.1.48 → 0.1.49

package/@opencode/agents/test_pr_review_aggregate.py

@@ -8,21 +8,47 @@ Tests cover:
 3. Edge cases: empty input, malformed data, cross-reviewer matching
 """
 
-import pytest
-from unittest.mock import patch, MagicMock
-import sys
+import importlib.util
+import json
+import subprocess
+from collections.abc import Mapping, Sequence
 from pathlib import Path
+from types import SimpleNamespace
+from typing import Callable, cast
+
+import pytest
+
+
+def _load_pr_review_aggregate_module():
+    module_path = Path(__file__).with_name("pr_review_aggregate.py")
+    spec = importlib.util.spec_from_file_location("pr_review_aggregate", 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
 
-# Add parent directory to path for importing pr_review_aggregate
-sys.path.insert(0, str(Path(__file__).parent))
 
-# Import functions under test
-from pr_review_aggregate import (
-    _parse_decision_log,
-    _filter_by_decision_log,
-    _parse_escalation_groups_json,
-    _parse_escalation_groups_b64,
+_pr_review_aggregate = _load_pr_review_aggregate_module()
+
+_parse_decision_log = cast(Callable[[str], list[dict[str, object]]], getattr(_pr_review_aggregate, "_parse_decision_log"))
+_filter_by_decision_log = cast(
+    Callable[[Sequence[Mapping[str, object]], Sequence[Mapping[str, object]], list[list[str]]], list[dict[str, object]]],
+    getattr(_pr_review_aggregate, "_filter_by_decision_log"),
+)
+_parse_escalation_groups_json = cast(
+    Callable[[str], list[list[str]]],
+    getattr(_pr_review_aggregate, "_parse_escalation_groups_json"),
+)
+_parse_escalation_groups_b64 = cast(
+    Callable[[str], list[list[str]]],
+    getattr(_pr_review_aggregate, "_parse_escalation_groups_b64"),
+)
+_check_existing_comment = cast(
+    Callable[[int, str, int, str], bool],
+    getattr(_pr_review_aggregate, "_check_existing_comment"),
 )
+_MARKER = cast(str, getattr(_pr_review_aggregate, "MARKER"))
 
 
 # ============================================================
@@ -30,13 +56,13 @@ from pr_review_aggregate import (
 # ============================================================
 
 @pytest.fixture
-def empty_decision_log():
+def empty_decision_log() -> str:
     """Empty decision log markdown."""
     return ""
 
 
 @pytest.fixture
-def valid_decision_log():
+def valid_decision_log() -> str:
     """Valid decision log with Fixed and Rejected entries."""
     return """# Decision Log
 
@@ -46,20 +72,24 @@ PR: 123
 
 ### Fixed
 - id: CDX-001
+  file: apps/backend/src/api.ts
   commit: abc123
   essence: JSON.parse 未捕获异常
 
 - id: GMN-002
+  file: apps/front/src/ErrorBoundary.tsx
   commit: def456
   essence: 缺少错误边界处理
 
 ### Rejected
 - id: GMN-004
+  file: apps/front/src/Component.tsx
   priority: P2
   reason: 需要产品决策，超出 PR 范围
   essence: 组件拆分建议
 
 - id: CLD-003
+  file: apps/backend/src/db.ts
   priority: P3
   reason: 性能优化非当前优先级
   essence: 批量查询优化
@@ -67,7 +97,38 @@ PR: 123
 
 
 @pytest.fixture
-def malformed_decision_log():
+def valid_decision_log_legacy_no_file() -> str:
+    """Legacy decision log fixture without the file: field (backward compat)."""
+    return """# Decision Log
+
+PR: 123
+
+## Round 1
+
+### Fixed
+- id: CDX-001
+  commit: abc123
+  essence: JSON.parse 未捕获异常
+
+- id: GMN-002
+  commit: def456
+  essence: 缺少错误边界处理
+
+### Rejected
+- id: GMN-004
+  priority: P2
+  reason: 需要产品决策，超出 PR 范围
+  essence: 组件拆分建议
+
+- id: CLD-003
+  priority: P3
+  reason: 性能优化非当前优先级
+  essence: 批量查询优化
+"""
+
+
+@pytest.fixture
+def malformed_decision_log() -> str:
     """Malformed decision log with missing fields and bad formatting."""
     return """# Decision Log
 
@@ -90,7 +151,7 @@ Some random text that should be ignored
 
 
 @pytest.fixture
-def sample_findings():
+def sample_findings() -> list[dict[str, object]]:
     """Sample findings list for filter tests."""
     return [
         {
@@ -137,7 +198,7 @@ def sample_findings():
 
 
 @pytest.fixture
-def prior_decisions():
+def prior_decisions() -> list[dict[str, object]]:
     """Sample prior decisions from _parse_decision_log."""
     return [
         {
@@ -160,7 +221,7 @@ def prior_decisions():
 # Test: _parse_decision_log() - Empty Input
 # ============================================================
 
-def test_parse_decision_log_empty(empty_decision_log):
+def test_parse_decision_log_empty(empty_decision_log: str) -> None:
     """
     Test that empty decision log returns empty list.
     
@@ -177,7 +238,7 @@ def test_parse_decision_log_empty(empty_decision_log):
 # Test: _parse_decision_log() - Valid Input
 # ============================================================
 
-def test_parse_decision_log_valid(valid_decision_log):
+def test_parse_decision_log_valid(valid_decision_log: str) -> None:
     """
     Test that valid decision log is parsed into structured data.
     
@@ -194,6 +255,7 @@ def test_parse_decision_log_valid(valid_decision_log):
     fixed_1 = result[0]
     assert fixed_1["id"] == "CDX-001"
     assert fixed_1["status"] == "fixed"
+    assert fixed_1["file"] == "apps/backend/src/api.ts"
     assert fixed_1["commit"] == "abc123"
     assert fixed_1["essence"] == "JSON.parse 未捕获异常"
     
@@ -201,6 +263,7 @@ def test_parse_decision_log_valid(valid_decision_log):
     fixed_2 = result[1]
     assert fixed_2["id"] == "GMN-002"
     assert fixed_2["status"] == "fixed"
+    assert fixed_2["file"] == "apps/front/src/ErrorBoundary.tsx"
     assert fixed_2["commit"] == "def456"
     assert fixed_2["essence"] == "缺少错误边界处理"
     
@@ -208,6 +271,7 @@ def test_parse_decision_log_valid(valid_decision_log):
     rejected_1 = result[2]
     assert rejected_1["id"] == "GMN-004"
     assert rejected_1["status"] == "rejected"
+    assert rejected_1["file"] == "apps/front/src/Component.tsx"
     assert rejected_1["priority"] == "P2"
     assert rejected_1["reason"] == "需要产品决策，超出 PR 范围"
     assert rejected_1["essence"] == "组件拆分建议"
@@ -216,14 +280,31 @@ def test_parse_decision_log_valid(valid_decision_log):
     rejected_2 = result[3]
     assert rejected_2["id"] == "CLD-003"
     assert rejected_2["status"] == "rejected"
+    assert rejected_2["file"] == "apps/backend/src/db.ts"
     assert rejected_2["priority"] == "P3"
 
 
+def test_parse_decision_log_legacy_without_file(valid_decision_log_legacy_no_file: str) -> None:
+    """Decision log entries without file: should still parse (backward compat)."""
+    result = _parse_decision_log(valid_decision_log_legacy_no_file)
+
+    # Should have 4 entries (2 Fixed, 2 Rejected)
+    assert len(result) == 4
+
+    # Basic shape should still be present
+    for entry in result:
+        assert "id" in entry
+        assert "status" in entry
+
+    # And file should be optional
+    assert all(("file" not in e) or (e["file"] in (None, "")) for e in result)
+
+
 # ============================================================
 # Test: _parse_decision_log() - Malformed Input
 # ============================================================
 
-def test_parse_decision_log_malformed(malformed_decision_log):
+def test_parse_decision_log_malformed(malformed_decision_log: str) -> None:
     """
     Test that malformed decision log degrades gracefully.
     
@@ -247,7 +328,7 @@ def test_parse_decision_log_malformed(malformed_decision_log):
 # Test: _filter_by_decision_log() - Fixed Issues
 # ============================================================
 
-def test_filter_fixed_issues(sample_findings, prior_decisions):
+def test_filter_fixed_issues(sample_findings: list[dict[str, object]], prior_decisions: list[dict[str, object]]) -> None:
     """
     Test that findings matching Fixed decisions are filtered out.
     
@@ -255,7 +336,7 @@ def test_filter_fixed_issues(sample_findings, prior_decisions):
     When: _filter_by_decision_log() is called with empty escalation_groups
     Then: CDX-001 is filtered out
     """
-    escalation_groups = []
+    escalation_groups: list[list[str]] = []
     
     result = _filter_by_decision_log(sample_findings, prior_decisions, escalation_groups)
     
@@ -271,7 +352,7 @@ def test_filter_fixed_issues(sample_findings, prior_decisions):
 # Test: _filter_by_decision_log() - Rejected Without Escalation
 # ============================================================
 
-def test_filter_rejected_without_escalation(sample_findings, prior_decisions):
+def test_filter_rejected_without_escalation(sample_findings: list[dict[str, object]], prior_decisions: list[dict[str, object]]) -> None:
     """
     Test that findings matching Rejected decisions are filtered out when NOT in escalation_groups.
     
@@ -280,7 +361,7 @@ def test_filter_rejected_without_escalation(sample_findings, prior_decisions):
     When: _filter_by_decision_log() is called
     Then: GMN-004 is filtered out
     """
-    escalation_groups = []
+    escalation_groups: list[list[str]] = []
     
     result = _filter_by_decision_log(sample_findings, prior_decisions, escalation_groups)
     
@@ -296,7 +377,7 @@ def test_filter_rejected_without_escalation(sample_findings, prior_decisions):
 # Test: _filter_by_decision_log() - Rejected With Escalation
 # ============================================================
 
-def test_filter_rejected_with_escalation(sample_findings, prior_decisions):
+def test_filter_rejected_with_escalation(sample_findings: list[dict[str, object]], prior_decisions: list[dict[str, object]]) -> None:
     """
     Test that findings matching Rejected decisions are kept when in escalation_groups.
     
@@ -322,7 +403,7 @@ def test_filter_rejected_with_escalation(sample_findings, prior_decisions):
 # Test: _filter_by_decision_log() - Cross-Reviewer Match
 # ============================================================
 
-def test_filter_cross_reviewer_match():
+def test_filter_cross_reviewer_match() -> None:
     """
     Test that findings with different reviewer IDs but same essence are filtered.
     
@@ -381,7 +462,7 @@ def test_filter_cross_reviewer_match():
 # Test: _parse_escalation_groups_json()
 # ============================================================
 
-def test_parse_escalation_groups_json_valid():
+def test_parse_escalation_groups_json_valid() -> None:
     """Test parsing valid escalation groups JSON."""
     json_str = '{"escalationGroups": [["GMN-004", "CLD-007"], ["CDX-001", "GMN-005"]]}'
     result = _parse_escalation_groups_json(json_str)
@@ -391,13 +472,13 @@ def test_parse_escalation_groups_json_valid():
     assert ["CDX-001", "GMN-005"] in result
 
 
-def test_parse_escalation_groups_json_empty():
+def test_parse_escalation_groups_json_empty() -> None:
     """Test parsing empty escalation groups JSON."""
     result = _parse_escalation_groups_json("")
     assert result == []
 
 
-def test_parse_escalation_groups_json_malformed():
+def test_parse_escalation_groups_json_malformed() -> None:
     """Test parsing malformed JSON returns empty list."""
     result = _parse_escalation_groups_json("not valid json {{{")
     assert result == []
@@ -407,7 +488,7 @@ def test_parse_escalation_groups_json_malformed():
 # Test: _parse_escalation_groups_b64()
 # ============================================================
 
-def test_parse_escalation_groups_b64_valid():
+def test_parse_escalation_groups_b64_valid() -> None:
     """Test parsing valid base64-encoded escalation groups."""
     import base64
     json_str = '{"escalationGroups": [["GMN-004", "CLD-007"]]}'
@@ -419,13 +500,13 @@ def test_parse_escalation_groups_b64_valid():
     assert ["GMN-004", "CLD-007"] in result
 
 
-def test_parse_escalation_groups_b64_empty():
+def test_parse_escalation_groups_b64_empty() -> None:
     """Test parsing empty base64 string."""
     result = _parse_escalation_groups_b64("")
     assert result == []
 
 
-def test_parse_escalation_groups_b64_invalid():
+def test_parse_escalation_groups_b64_invalid() -> None:
     """Test parsing invalid base64 returns empty list."""
     result = _parse_escalation_groups_b64("not-valid-base64!!!")
     assert result == []
@@ -435,7 +516,7 @@ def test_parse_escalation_groups_b64_invalid():
 # Test: Integration - Full Workflow
 # ============================================================
 
-def test_integration_full_filter_workflow():
+def test_integration_full_filter_workflow() -> None:
     """
     Integration test: parse decision log and filter findings.
     
@@ -496,5 +577,125 @@ PR: 456
     assert len(result) == 2
 
 
+# ============================================================
+# Test: _check_existing_comment() - PR comment idempotency
+# ============================================================
+
+
+def _patch_subprocess_run_for_gh_comments(monkeypatch: pytest.MonkeyPatch, comments: list[dict[str, object]], returncode: int = 0) -> None:
+    stdout = json.dumps(comments, ensure_ascii=True)
+
+    def _fake_run(*_args: object, **_kwargs: object) -> SimpleNamespace:
+        return SimpleNamespace(returncode=returncode, stdout=stdout)
+
+    monkeypatch.setattr(subprocess, "run", _fake_run)
+
+
+@pytest.mark.parametrize(
+    "comment_type,round_num,expected_header",
+    [
+        ("review-summary", 2, "## Review Summary (Round 2)"),
+        ("fix-report", 2, "## Fix Report (Round 2)"),
+        ("final-report", 2, "## Final Report"),
+    ],
+)
+def test_check_existing_comment_true_when_marker_header_and_runid_match(
+    monkeypatch: pytest.MonkeyPatch, comment_type: str, round_num: int, expected_header: str
+) -> None:
+    pr_number = 123
+    run_id = "run-abc"
+    body = "\n".join([_MARKER, "", expected_header, "", f"RunId: {run_id}"])
+    _patch_subprocess_run_for_gh_comments(monkeypatch, [{"body": body}])
+
+    assert _check_existing_comment(pr_number, run_id, round_num, comment_type) is True
+
+
+@pytest.mark.parametrize(
+    "comment_type,round_num,expected_header",
+    [
+        ("review-summary", 3, "## Review Summary (Round 3)"),
+        ("fix-report", 3, "## Fix Report (Round 3)"),
+        ("final-report", 3, "## Final Report"),
+    ],
+)
+def test_check_existing_comment_false_when_marker_missing(
+    monkeypatch: pytest.MonkeyPatch, comment_type: str, round_num: int, expected_header: str
+) -> None:
+    pr_number = 456
+    run_id = "run-xyz"
+    body = "\n".join(["", expected_header, "", f"RunId: {run_id}"])
+    _patch_subprocess_run_for_gh_comments(monkeypatch, [{"body": body}])
+
+    assert _check_existing_comment(pr_number, run_id, round_num, comment_type) is False
+
+
+@pytest.mark.parametrize(
+    "comment_type,round_num,expected_header,wrong_header",
+    [
+        (
+            "review-summary",
+            2,
+            "## Review Summary (Round 2)",
+            "## Fix Report (Round 2)",
+        ),
+        (
+            "fix-report",
+            2,
+            "## Fix Report (Round 2)",
+            "## Review Summary (Round 2)",
+        ),
+        (
+            "final-report",
+            2,
+            "## Final Report",
+            "## Review Summary (Round 2)",
+        ),
+    ],
+)
+def test_check_existing_comment_false_when_header_mismatched(
+    monkeypatch: pytest.MonkeyPatch, comment_type: str, round_num: int, expected_header: str, wrong_header: str
+) -> None:
+    pr_number = 789
+    run_id = "run-123"
+
+    body = "\n".join([_MARKER, "", wrong_header, "", f"RunId: {run_id}"])
+    _patch_subprocess_run_for_gh_comments(monkeypatch, [{"body": body}])
+
+    assert expected_header not in body
+    assert _check_existing_comment(pr_number, run_id, round_num, comment_type) is False
+
+
+@pytest.mark.parametrize(
+    "comment_type,round_num,expected_header",
+    [
+        ("review-summary", 1, "## Review Summary (Round 1)"),
+        ("fix-report", 1, "## Fix Report (Round 1)"),
+        ("final-report", 1, "## Final Report"),
+    ],
+)
+def test_check_existing_comment_false_when_runid_mismatched(
+    monkeypatch: pytest.MonkeyPatch, comment_type: str, round_num: int, expected_header: str
+) -> None:
+    pr_number = 101
+    run_id = "run-a"
+    other_run_id = "run-b"
+
+    body = "\n".join([_MARKER, "", expected_header, "", f"RunId: {other_run_id}"])
+    _patch_subprocess_run_for_gh_comments(monkeypatch, [{"body": body}])
+
+    assert _check_existing_comment(pr_number, run_id, round_num, comment_type) is False
+
+
+def test_check_existing_comment_false_when_subprocess_run_nonzero(monkeypatch: pytest.MonkeyPatch) -> None:
+    pr_number = 999
+    run_id = "run-nonzero"
+    round_num = 2
+    comment_type = "review-summary"
+    body = "\n".join([_MARKER, "", "## Review Summary (Round 2)", "", f"RunId: {run_id}"])
+
+    _patch_subprocess_run_for_gh_comments(monkeypatch, [{"body": body}], returncode=1)
+    assert _check_existing_comment(pr_number, run_id, round_num, comment_type) is False
+
+
 if __name__ == "__main__":
-    pytest.main([__file__, "-v"])
+    _ = pytest.main([__file__, "-v"])

package/@opencode/commands/pr-review-loop.md

@@ -15,6 +15,19 @@ agent: sisyphus
 ## 输入
 
 - `{{PR_NUMBER}}`
+- `round`（默认 1，由调用者/循环控制）
+
+## 唯一标识 runId（强制）
+
+- 全局唯一标识 `runId` 格式：`<PR>-<ROUND>-<HEAD_SHORT>`
+- 其中：
+  - `<PR>`：PR 编号
+  - `<ROUND>`：当前轮次
+  - `<HEAD_SHORT>`：`headOid` 的前 7 位（git rev-parse --short HEAD）
+- 生成者：
+  - 第 1 步 `pr-context` 负责计算并返回 `runId`（基于当前 checkout 的 headOid）
+  - 后续所有步骤（reviewers, aggregate, fix）必须透传并使用该 `runId`
+  - 禁止任何下游步骤自行生成或篡改 `runId`
 
 ## Cache 约定（强制）
 
@@ -26,6 +39,7 @@ agent: sisyphus
 - `pr-precheck`
 - `pr-context`
 - `codex-reviewer`
+
 - `claude-reviewer`
 - `gemini-reviewer`
 - `gh-thread-reviewer`
@@ -37,14 +51,15 @@ agent: sisyphus
 
 0. Task: `pr-precheck`（强制 gate：编译/预检必须先通过）
 
-- prompt 必须包含：`PR #{{PR_NUMBER}}`
-- 若返回 `{"error":"..."}`：立即终止本轮并回传错误（不再调用 reviewers）
+- prompt 必须包含：`PR #{{PR_NUMBER}}`、`round: <ROUND>`（precheck 需计算并返回 runId，格式同 context）
+- 若返回 `{"error":"..."}`：立即终止本轮并回传错误
 - 若返回 `{"ok":false,"fixFile":"..."}`：
+  - 预检阶段 runId 同样基于 `headOid` 生成（`<PR>-<ROUND>-<HEAD_SHORT>`），可直接传给 fix。
   - 最多修复 2 次（防止无限循环）：
-    - 第 1 次：Task `pr-fix`（使用该 fixFile）→ 再 Task `pr-precheck`
+    - 第 1 次：Task `pr-fix`（传入 `fixFile`, `runId`, `round`）→ 再 Task `pr-precheck`
     - 若仍返回 `{"ok":false,"fixFile":"..."}`：第 2 次 Task `pr-fix` → 再 Task `pr-precheck`
   - 若仍不是 `{"ok":true}`：终止并回传错误（建议：`{"error":"PRECHECK_NOT_CLEAN_AFTER_FIX"}`）
-
+- 注意：预检失败产生的修复也应记录在 Decision Log 中（essence: `__precheck__` 或具体错误信息，file: `__precheck__`），以便后续追踪。
 
 ## 循环（最多 3 轮）
 
@@ -61,7 +76,8 @@ agent: sisyphus
 
 - prompt 必须包含：`PR #{{PR_NUMBER}}`、`round: <ROUND>`
 - 若返回 `{"error":"..."}`：立即终止本轮并回传错误（不再调用 reviewers）
-- 取出：`contextFile`、`runId`、`headOid`（如有）
+- 取出：`contextFile`、`runId`、`headOid`
+- **runId 校验**：确认返回的 `runId` 符合 `<PR>-<ROUND>-<HEAD_SHORT>` 格式
 - **CRITICAL**: 必须等待此 Task 成功完成并获取到 `contextFile` 后，才能进入 Step 2
 
 **检查 Decision Log**：
@@ -77,14 +93,14 @@ agent: sisyphus
   - `round: <ROUND>`
   - `runId: <RUN_ID>`（来自 Step 1 的输出，必须透传，禁止自行生成）
   - `contextFile: ./.cache/<file>.md`（来自 Step 1 的输出）
-  - `decisionLogFile: ./.cache/decision-log-pr{{PR_NUMBER}}.md`（如存在，来自检查后得出）
+  - `decisionLogFile: ./.cache/decision-log-pr{{PR_NUMBER}}.md`（如存在）
 - reviewer 默认读 `contextFile`；如果 `decisionLogFile` 存在，reviewer 应在 prompt 中提供该文件路径以参考前轮决策；必要时允许用 `git/gh` 只读命令拿 diff
 - 忽略问题：1.格式化代码引起的噪音 2.已经lint检查以外的格式问题 3.忽略单元测试不足的问题
 - 特别关注: 逻辑、安全、性能、可维护性
-- 同时要注意 pr 前面轮次的 修复和讨论，对于已经拒绝、已修复的问题不要反复的提出
-- 同时也要注意fix的过程中有没有引入新的问题。
-
-备注：fixFile 分为 `IssuesToFix`（P0/P1，必须修）与 `OptionalIssues`（P2/P3，pr-fix 自主裁决）。
+- 遵守 Decision Log：
+  - 已修复（Fixed）：不再提
+  - 已拒绝（Rejected）：除非优先级升级（P_new - P_old >= 2），否则不再提
+  - 任何新发现必须基于当前 `runId` 对应的代码状态
 - 每个 reviewer 输出：`reviewFile: ./.cache/<file>.md`（Markdown）
 
 3. Task: `pr-review-aggregate`
@@ -93,6 +109,10 @@ agent: sisyphus
 - 输出：`{"stop":true}` 或 `{"stop":false,"fixFile":"..."}`
 - 若 `stop=true`：本轮结束并退出循环
 - **唯一性约束**: 每轮只能发布一次 Review Summary；脚本内置幂等检查，重复调用不会重复发布
+- 智能聚合：
+  - 使用 LLM 对比 decision-log 中的 `essence` 与新 finding
+  - 仅当问题本质相同且优先级 delta < 2 时，自动归为 Repeated/Ignored
+  - 否则视为 New Issue 或 Escalation
 
 4. Task: `pr-fix`
 
@@ -102,9 +122,13 @@ agent: sisyphus
   - `runId: <RUN_ID>`（来自 Step 1 的输出，必须透传，禁止自行生成）
   - `fixFile: ./.cache/<file>.md`
 - 约定：`pr-fix` 对每个 findingId 单独 commit + push（一个 findingId 一个 commit），结束后再 `git push` 兜底
-
+- 决策记录：
+  - 修复成功：追加 Fixed 记录（含 `essence`）到 Decision Log
+  - 拒绝/无法修复：追加 Rejected 记录（含 `reason`, `essence`）到 Decision Log
+  - 范围限制：essence 匹配必须在 **同一个文件** 内（不支持跨文件/重命名追踪）
 - pr-fix 输出：`fixReportFile: ./.cache/<file>.md`（Markdown）
 
+
 5. Task: `pr-review-aggregate`（发布修复评论）
 
 - prompt 必须包含：`PR #{{PR_NUMBER}}`、`round: <ROUND>`、`runId: <RUN_ID>`、`fixReportFile: ./.cache/<file>.md`
@@ -119,6 +143,32 @@ agent: sisyphus
 
 - 回到 1（进入下一轮 reviewers）
 
+## 本地验证（脚本直跑）
+
+```bash
+# 0) 先确保 gh 已认证（host 从 git remote origin 推断；必要时用 --hostname）
+gh auth status
+
+# 1) precheck（round 1）
+python3 "./@opencode/agents/pr_precheck.py" --pr <PR_NUMBER> --round 1
+
+# 2) context（round 1）
+python3 "./@opencode/agents/pr_context.py" --pr <PR_NUMBER> --round 1
+
+# 3) 校验：两者都必须输出单行 JSON，且 runId 必须一致
+python3 "./@opencode/agents/pr_precheck.py" --pr <PR_NUMBER> --round 1 > ./.cache/_precheck.json
+python3 "./@opencode/agents/pr_context.py" --pr <PR_NUMBER> --round 1 > ./.cache/_context.json
+python3 - <<'PY'
+import json
+p=json.load(open('./.cache/_precheck.json'))
+c=json.load(open('./.cache/_context.json'))
+assert p.get('runId') == c.get('runId'), (p.get('runId'), c.get('runId'))
+print('OK', p.get('runId'))
+PY
+
+# 4) 运行脚本相关测试（注意：pytest 把 @ 当作 argfile；必须加 ./ 并加引号）
+python3 -m pytest -q "./@opencode/agents/test_pr_review_aggregate.py"
+```
 
 ## 终止与收尾（强制）
 

package/package.json

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