@optima-chat/dev-skills 0.16.3 → 0.16.5

package/docs/superpowers/plans/2026-08-31-yzsgo-e2e.md

@@ -0,0 +1,969 @@
+# yzsgo-e2e 通用端到端测试 skill — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在 optima-dev-skills 里新增 `yzsgo-e2e` skill：Claude Code 用 playwright attach 调试端口 Chrome 驱动 www.yzsgo.com 完成一段对话，拉 gateway wire，复用 conversation-iq 语义管线判定前后端一致性与网关缺陷，confirmed 自动提 issue。
+
+**Architecture:** 方案 A（自包含 vendor）。从 optima-store-skills 拷 `chat_driver.py`/`pull_wire.py`，从 optima-gateway conversation-iq 改编 `prep_conversation.py`/`judge_workflow.js`，全部随包进 `.claude/skills/yzsgo-e2e/` 并镜像到 `.codex/`。新写的可判定逻辑（对话定位、浏览器证据合并、三态裁决、报告渲染、preflight 汇总、漂移比对）抽成纯函数并 TDD。
+
+**Tech Stack:** Python 3.11（随包脚本，测试用标准库 `unittest`，无第三方依赖）；playwright（仅驱动脚本运行时需要，纯函数测试不需要）；JavaScript ESM（`judge_workflow.js` 走 Workflow，`judge_outcome.js` 纯函数用 `node --test`）；`gh` CLI 提 issue；`sshpass`+buildbox 拉 wire。
+
+**Spec:** `docs/superpowers/specs/2026-08-31-yzsgo-e2e-design.md`
+
+## Global Constraints
+
+以下为项目级约束，每个任务的要求都隐含包含本节（值逐字取自 spec）：
+
+- **skill 名固定 `yzsgo-e2e`**；`.claude/skills/yzsgo-e2e/` 与 `.codex/skills/yzsgo-e2e/` **同名镜像**，内容一致。
+- **随包脚本纯 Python/JS，放 skill 目录内，不进 `bin/`、不进 TS/dist 体系**（对齐 read-code / generate-test-token 的纯随包路线）。
+- **用户不敲 CLI**：脚本参数由 Claude 内部填；SKILL.md 教 Claude 把用户自然语言映射成驱动动作。
+- **三态命名固定**：`confirmed` / `needs_review` / `rejected`。
+- **提 issue 规则**：`confirmed` 直接用 `gh` 提到 **Optima-Chat/optima-gateway**（不给草稿、不设人工门）；`needs_review` **不自动提**、进报告待人工；环境类（积分/超时/桌面没连/session 泄漏）**不提**、报告标 `blocked`。
+- **定位本次对话禁用 `ls -t`**：只按 `(started_ts, first_message)` 匹配（沿用 store-skills 血泪纪律）。
+- **vendored 文件钉明上游信源**：`SYNC.md` 记每个 vendored 文件的上游 repo 路径 + commit hash + 同步日期。
+- **两环境**：`--env cn-prod|cn-stage`，**先把 cn-prod 全链路打通**，cn-stage 未验证部分明确标注、不假装支持。
+- **Python 纯函数测试用标准库 `unittest`**（`python3 -m unittest`），测试文件放仓库根 `tests/yzsgo-e2e/`（不进 `.claude`，不随包发布）；测试内用 `sys.path.insert` 指到 skill 目录 import 被测脚本。
+- **时间戳统一 UTC ISO8601**（`datetime.now(timezone.utc).isoformat()`），与 wire records 的 `ts` 字段可字符串比较。
+
+---
+
+## File Structure
+
+**新建（随包，`.claude/skills/yzsgo-e2e/`，同名镜像到 `.codex/skills/yzsgo-e2e/`）：**
+- `SKILL.md` — 何时用 / 用户说人话如何映射 / 四段流程 / 诚实边界 / vendor 纪律 / 两环境
+- `preflight.py` — 环境自检（探测 + `summarize_preflight` 纯函数汇总）
+- `chat_driver.py` — [vendored ← store-skills] playwright attach 9222 驱动
+- `pull_wire.py` — [vendored ← store-skills] 拉 wire + seq 切分 + 渲染；本 skill 增 `emit_conversation_index` + `locate_conversation`
+- `prep_conversation.py` — [改编 ← conversation-iq/prep_session.py] 备料 + `merge_browser_evidence`
+- `judge_outcome.js` — 纯函数 `decideOutcome`（从 conversation-iq 三态逻辑抽出，可 `node --test`）
+- `judge_workflow.js` — [改编 ← conversation-iq/workflow.js] Workflow 编排，import `judge_outcome.js`
+- `run_e2e.py` — 编排入口（驱动→拉 wire→定位→备料→出备料稿+元数据）+ `render_report`
+- `verify_drift.py` — 可选漂移比对（`plan_drift_checks` 纯函数 + 探测）
+- `SYNC.md` — vendored 上游 commit 台账
+
+**新建（测试，仓库根 `tests/yzsgo-e2e/`，不随包）：**
+- `test_locate.py` / `test_merge_evidence.py` / `test_render_report.py` / `test_preflight.py` / `test_verify_drift.py`
+- `tests/yzsgo-e2e-outcome.test.js`（node --test）
+
+**修改：**
+- `README.md` — skill 清单加 `yzsgo-e2e`
+- `tests/service-matrix-alignment.test.js` — 若校验清单则纳入 `yzsgo-e2e`（Task 7 先读它再决定）
+
+---
+
+## Task 1: skill 骨架 + preflight 汇总纯函数
+
+**Files:**
+- Create: `.claude/skills/yzsgo-e2e/SKILL.md`（骨架 frontmatter，正文 Task 7 补全）
+- Create: `.claude/skills/yzsgo-e2e/preflight.py`
+- Create: `.claude/skills/yzsgo-e2e/SYNC.md`（空台账，Task 2 起填）
+- Test: `tests/yzsgo-e2e/test_preflight.py`
+
+**Interfaces:**
+- Produces: `summarize_preflight(checks: list[dict]) -> dict`，`checks` 每项 `{"name": str, "ok": bool, "hint": str}`，返回 `{"ok": bool, "missing": list[str], "report": str}`。`ok = all(c["ok"])`；`missing = [c["name"] for c in checks if not c["ok"]]`；`report` 为多行文本，每行 `✅/❌ <name>`，`❌` 行附 `hint`。
+
+- [ ] **Step 1: 写失败测试**
+
+```python
+# tests/yzsgo-e2e/test_preflight.py
+import os, sys, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".claude", "skills", "yzsgo-e2e"))
+from preflight import summarize_preflight
+
+class TestPreflight(unittest.TestCase):
+    def test_all_ok(self):
+        r = summarize_preflight([{"name": "chrome-9222", "ok": True, "hint": "x"}])
+        self.assertTrue(r["ok"]); self.assertEqual(r["missing"], [])
+        self.assertIn("✅ chrome-9222", r["report"])
+
+    def test_missing_lists_and_hints(self):
+        r = summarize_preflight([
+            {"name": "chrome-9222", "ok": True, "hint": "x"},
+            {"name": "buildbox-pw", "ok": False, "hint": "创建 ~/.buildbox_pw"},
+        ])
+        self.assertFalse(r["ok"]); self.assertEqual(r["missing"], ["buildbox-pw"])
+        self.assertIn("❌ buildbox-pw", r["report"]); self.assertIn("创建 ~/.buildbox_pw", r["report"])
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `python3 -m unittest tests.yzsgo-e2e.test_preflight -v`（在仓库根，或 `python3 tests/yzsgo-e2e/test_preflight.py`）
+Expected: FAIL — `ModuleNotFoundError: No module named 'preflight'`
+
+- [ ] **Step 3: 写 preflight.py**
+
+```python
+#!/usr/bin/env python3
+"""yzsgo-e2e 环境自检。探测函数有副作用（读端口/文件），汇总用纯函数 summarize_preflight。
+缺项只指路（不替用户做一次性登录/充值），准备步骤见 store-skills 的 setting-up-yzsgo-test-env。"""
+import os, shutil, socket, sys
+
+def _port_open(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(1.0)
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+def probe(env: str = "cn-prod") -> list[dict]:
+    return [
+        {"name": "chrome-9222", "ok": _port_open(9222),
+         "hint": '起调试端口 Chrome：open -na "Google Chrome" --args --remote-debugging-port=9222 '
+                 '--user-data-dir=/tmp/yzsgo-chrome https://www.yzsgo.com（手动登测试账号）'},
+        {"name": "buildbox-pw", "ok": os.path.exists(os.path.expanduser("~/.buildbox_pw")),
+         "hint": "拉 wire 需 buildbox 口令文件 ~/.buildbox_pw（见 setting-up-yzsgo-test-env）"},
+        {"name": "sshpass", "ok": shutil.which("sshpass") is not None,
+         "hint": "brew install hudochenkov/sshpass/sshpass"},
+        {"name": "playwright", "ok": _has_playwright(),
+         "hint": "pip install playwright && playwright install chromium"},
+    ]
+
+def _has_playwright() -> bool:
+    try:
+        import playwright  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+def summarize_preflight(checks: list) -> dict:
+    ok = all(c["ok"] for c in checks)
+    missing = [c["name"] for c in checks if not c["ok"]]
+    rows = []
+    for c in checks:
+        mark = "✅" if c["ok"] else "❌"
+        rows.append(f"{mark} {c['name']}" + ("" if c["ok"] else f"\n    → {c['hint']}"))
+    return {"ok": ok, "missing": missing, "report": "\n".join(rows)}
+
+if __name__ == "__main__":
+    env = sys.argv[1] if len(sys.argv) > 1 else "cn-prod"
+    r = summarize_preflight(probe(env))
+    print(r["report"])
+    sys.exit(0 if r["ok"] else 1)
+```
+
+同时建 `SKILL.md` 骨架（正文 Task 7 补）：
+
+```markdown
+---
+name: "yzsgo-e2e"
+description: "当用户请求端到端测试鸭嘴兽、e2e 测 yzsgo 对话、用浏览器真机测鸭嘴兽整个流程、驱动对话再拉 wire 核对前后端、测网关/agent 端到端有没有问题时，使用此技能。playwright attach 调试端口 Chrome 驱 www.yzsgo.com 对话 → 拉 gateway wire → conversation-iq 语义管线判定 → confirmed 自动提 issue。"
+allowed-tools: ["Bash", "Read", "Write", "Agent", "Workflow"]
+---
+
+<!-- 正文见 Task 7 -->
+```
+
+建空 `SYNC.md`：
+
+```markdown
+# vendored 文件上游台账
+
+| 本文件 | 上游 repo · 路径 | commit | 同步日期 |
+|---|---|---|---|
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `python3 tests/yzsgo-e2e/test_preflight.py`
+Expected: PASS（2 tests）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add .claude/skills/yzsgo-e2e/{SKILL.md,preflight.py,SYNC.md} tests/yzsgo-e2e/test_preflight.py
+git commit -m "feat(yzsgo-e2e): skill 骨架 + preflight 环境自检"
+```
+
+---
+
+## Task 2: vendor chat_driver.py + pull_wire.py + SYNC 台账
+
+**Files:**
+- Create: `.claude/skills/yzsgo-e2e/chat_driver.py`（拷贝）
+- Create: `.claude/skills/yzsgo-e2e/pull_wire.py`（拷贝）
+- Modify: `.claude/skills/yzsgo-e2e/SYNC.md`
+- Test: `tests/yzsgo-e2e/test_imports.py`
+
+**Interfaces:**
+- Produces: `chat_driver.ChatDriver`（含 `attach/new_conversation/send/wait_reply/send_and_wait/answer_question/ensure_idle/preflight` 方法，签名同上游）；`pull_wire.segment/render_conversation/first_user_text/make_deref/pull/render_all`（同上游）。
+
+- [ ] **Step 1: 写失败测试（import smoke）**
+
+```python
+# tests/yzsgo-e2e/test_imports.py
+import os, sys, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".claude", "skills", "yzsgo-e2e"))
+
+class TestImports(unittest.TestCase):
+    def test_pull_wire_symbols(self):
+        import pull_wire
+        for fn in ("segment", "render_conversation", "first_user_text", "make_deref"):
+            self.assertTrue(hasattr(pull_wire, fn), fn)
+
+    def test_chat_driver_class(self):
+        import chat_driver  # 需环境已装 playwright
+        self.assertTrue(hasattr(chat_driver, "ChatDriver"))
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `python3 tests/yzsgo-e2e/test_imports.py`
+Expected: FAIL — `ModuleNotFoundError: No module named 'pull_wire'`
+
+- [ ] **Step 3: 拷贝上游文件并记台账**
+
+```bash
+SS=~/optima-store-skills/.claude/skills
+cp "$SS/operating-yzsgo-chat/chat_driver.py"      .claude/skills/yzsgo-e2e/chat_driver.py
+cp "$SS/pulling-yzsgo-session-wire/pull_wire.py"  .claude/skills/yzsgo-e2e/pull_wire.py
+# 记录上游 commit
+git -C ~/optima-store-skills rev-parse --short HEAD
+```
+
+把上一行输出的 commit 填入 `SYNC.md`（示例，实际填真实 hash 与当日日期）：
+
+```markdown
+| chat_driver.py | optima-store-skills · .claude/skills/operating-yzsgo-chat/chat_driver.py | <hash> | 2026-08-31 |
+| pull_wire.py | optima-store-skills · .claude/skills/pulling-yzsgo-session-wire/pull_wire.py | <hash> | 2026-08-31 |
+```
+
+> 注：原样 vendored，不裁 `ensure_installed` 等 marketplace 方法（保持 diff 干净、漂移比对简单；裁剪列为后续可选）。
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `.venv/bin/python tests/yzsgo-e2e/test_imports.py`（venv 需先 `pip install playwright`；若无 playwright，`test_chat_driver_class` 会 skip 不了则先只验 `test_pull_wire_symbols`）
+Expected: `test_pull_wire_symbols` PASS；playwright 在场时 `test_chat_driver_class` PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add .claude/skills/yzsgo-e2e/{chat_driver.py,pull_wire.py,SYNC.md} tests/yzsgo-e2e/test_imports.py
+git commit -m "feat(yzsgo-e2e): vendor chat_driver + pull_wire（记 SYNC 台账）"
+```
+
+---
+
+## Task 3: 对话索引 emit + locate_conversation 定位纯函数
+
+**Files:**
+- Modify: `.claude/skills/yzsgo-e2e/pull_wire.py`（追加 `emit_conversation_index` + `locate_conversation`）
+- Test: `tests/yzsgo-e2e/test_locate.py`
+
+**Interfaces:**
+- Consumes: `pull_wire.segment`, `pull_wire.first_user_text`, `pull_wire.make_deref`（Task 2）。
+- Produces:
+  - `emit_conversation_index(wire_root: str) -> list[dict]`，每项 `{"gidx": int, "sid": str, "ts": str, "prompt": str}`（gidx 从 1 递增，跨 session 连续，与 `render_all` 编号一致；ts = 对话首 req 的 `ts`；prompt = `first_user_text`）。
+  - `locate_conversation(index: list[dict], started_ts: str, first_message: str) -> dict | None`：在 `index` 里找本次对话。匹配规则：① 候选 = `first_message.strip()[:40]` 与 `item["prompt"]` 互相包含（任一方 startswith 另一方前 40 字）；② 候选按 `ts` 升序，取第一个 `ts >= started_ts` 的；③ 无 ts 满足则取候选里 ts 最大的；④ 无候选返回 `None`。
+
+- [ ] **Step 1: 写失败测试**
+
+```python
+# tests/yzsgo-e2e/test_locate.py
+import os, sys, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".claude", "skills", "yzsgo-e2e"))
+from pull_wire import locate_conversation
+
+IDX = [
+    {"gidx": 1, "sid": "s1", "ts": "2026-08-31T10:00:00Z", "prompt": "我想做电商帮我看看"},
+    {"gidx": 2, "sid": "s1", "ts": "2026-08-31T14:03:10Z", "prompt": "我想做电商帮我看看行情"},
+    {"gidx": 3, "sid": "s1", "ts": "2026-08-31T14:05:00Z", "prompt": "换个话题聊聊物流"},
+]
+
+class TestLocate(unittest.TestCase):
+    def test_picks_first_after_started_among_matches(self):
+        r = locate_conversation(IDX, "2026-08-31T14:00:00Z", "我想做电商帮我看看")
+        self.assertEqual(r["gidx"], 2)  # gidx1 在 started 之前，被排除
+
+    def test_no_match_returns_none(self):
+        self.assertIsNone(locate_conversation(IDX, "2026-08-31T14:00:00Z", "完全不相干的话"))
+
+    def test_fallback_latest_when_none_after_started(self):
+        r = locate_conversation(IDX, "2026-08-31T23:00:00Z", "我想做电商帮我看看")
+        self.assertEqual(r["gidx"], 2)  # 无 ts>=started 的候选 → 候选里 ts 最大
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `python3 tests/yzsgo-e2e/test_locate.py`
+Expected: FAIL — `ImportError: cannot import name 'locate_conversation'`
+
+- [ ] **Step 3: 追加实现到 pull_wire.py 末尾**
+
+```python
+# ── yzsgo-e2e 增补：结构化对话索引 + 本次对话定位 ──
+
+def emit_conversation_index(wire_root):
+    """遍历 wire_root 下各 session，切分对话，产出与 render_all 同序的结构化索引。"""
+    import os as _os
+    out = []
+    gidx = 0
+    sessions = sorted(d for d in _os.listdir(wire_root)
+                      if _os.path.isdir(_os.path.join(wire_root, d)))
+    for sid in sessions:
+        sdir = _os.path.join(wire_root, sid)
+        recf = _os.path.join(sdir, "records.jsonl")
+        if not _os.path.exists(recf):
+            continue
+        deref = make_deref(sdir)
+        recs = [json.loads(l) for l in open(recf, encoding="utf-8") if l.strip()]
+        reqs = [r for r in recs if r.get("kind") == "request"]
+        for conv in segment(reqs, deref):
+            gidx += 1
+            out.append({"gidx": gidx, "sid": sid,
+                        "ts": conv[0].get("ts", ""),
+                        "prompt": first_user_text(conv[0], deref)})
+    return out
+
+
+def locate_conversation(index, started_ts, first_message):
+    """按 (started_ts, first_message) 定位本次对话；禁用 ls -t。规则见 plan Task 3 Interfaces。"""
+    key = (first_message or "").strip()[:40]
+    cands = []
+    for it in index:
+        p = (it.get("prompt") or "").strip()
+        if not key:
+            continue
+        if p[:40].startswith(key) or key.startswith(p[:40]):
+            cands.append(it)
+    if not cands:
+        return None
+    cands.sort(key=lambda x: x.get("ts", ""))
+    after = [c for c in cands if c.get("ts", "") >= started_ts]
+    if after:
+        return after[0]
+    return cands[-1]
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `python3 tests/yzsgo-e2e/test_locate.py`
+Expected: PASS（3 tests）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add .claude/skills/yzsgo-e2e/pull_wire.py tests/yzsgo-e2e/test_locate.py
+git commit -m "feat(yzsgo-e2e): 对话索引 emit + 按时间戳/prompt 定位本次对话"
+```
+
+---
+
+## Task 4: prep_conversation.py（改编备料 + 浏览器证据合并）
+
+**Files:**
+- Create: `.claude/skills/yzsgo-e2e/prep_conversation.py`
+- Modify: `.claude/skills/yzsgo-e2e/SYNC.md`（登记改编来源）
+- Test: `tests/yzsgo-e2e/test_merge_evidence.py`
+
+**Interfaces:**
+- Consumes: `pull_wire.render_conversation`（用其渲染 wire 侧备料稿）。
+- Produces: `merge_browser_evidence(wire_md: str, browser_turns: list[dict]) -> str`。`browser_turns` 每项 `{"sent": str, "state": str, "transcript": str, "tool_trace": Any, "timed_out": bool}`（`transcript`/`state` 来自 `chat_driver.wait_reply`）。返回 = `wire_md` + 追加一节 `## 前端所见（浏览器侧证据；与上面 wire 对照）`，逐轮列出 `sent/state/timed_out/transcript`，并在节首写一行提示要求判定者核对前后端一致性。
+
+- [ ] **Step 1: 写失败测试**
+
+```python
+# tests/yzsgo-e2e/test_merge_evidence.py
+import os, sys, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".claude", "skills", "yzsgo-e2e"))
+from prep_conversation import merge_browser_evidence
+
+class TestMerge(unittest.TestCase):
+    def test_appends_browser_section_with_turns(self):
+        wire = "# 对话 #2\n## 事实卡\n- LLM 轮数 3\n"
+        turns = [
+            {"sent": "你好", "state": "done", "transcript": "你好！我是鸭嘴兽…", "tool_trace": [], "timed_out": False},
+            {"sent": "看看行情", "state": "service_error", "transcript": "", "tool_trace": [], "timed_out": False},
+        ]
+        out = merge_browser_evidence(wire, turns)
+        self.assertIn("# 对话 #2", out)                    # 保留 wire 原文
+        self.assertIn("## 前端所见", out)                   # 追加浏览器节
+        self.assertIn("你好！我是鸭嘴兽", out)              # 前端渲染内容进证据
+        self.assertIn("service_error", out)                 # 前端异常态可见
+        self.assertIn("对照", out)                          # 有前后端对照提示
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `python3 tests/yzsgo-e2e/test_merge_evidence.py`
+Expected: FAIL — `ModuleNotFoundError: No module named 'prep_conversation'`
+
+- [ ] **Step 3: 写 prep_conversation.py**
+
+```python
+#!/usr/bin/env python3
+"""yzsgo-e2e 备料层：wire 侧备料稿（复用 pull_wire.render_conversation）+ 合并浏览器侧证据。
+改编自 optima-gateway conversation-iq/prep_session.py（备料思路）与 pull_wire（渲染）。见 SYNC.md。"""
+import json
+
+def merge_browser_evidence(wire_md: str, browser_turns: list) -> str:
+    lines = [wire_md.rstrip(), "",
+             "## 前端所见（浏览器侧证据；与上面 wire 对照）",
+             "> 判定要求：逐轮核对**前端渲染的**与**wire 里 agent 真实产出的**是否一致——"
+             "前端丢内容/半截/报错但 wire 成功（或反之）即为缺陷。", ""]
+    for i, t in enumerate(browser_turns):
+        lines.append(f"### 轮 #{i}  发送: {t.get('sent','')!r}")
+        lines.append(f"- state: {t.get('state','')}  timed_out: {t.get('timed_out', False)}")
+        tt = t.get("tool_trace")
+        if tt:
+            lines.append(f"- tool_trace: {json.dumps(tt, ensure_ascii=False)[:1500]}")
+        lines.append("- 前端整轮渲染:")
+        lines.append("```")
+        lines.append((t.get("transcript") or "(空)")[:6000])
+        lines.append("```")
+    return "\n".join(lines)
+```
+
+在 `SYNC.md` 追加：
+
+```markdown
+| prep_conversation.py | optima-gateway · .claude/skills/conversation-iq/prep_session.py（改编：+浏览器证据合并） | <hash> | 2026-08-31 |
+```
+
+（`<hash>` 用 `git -C ~/optima-gateway rev-parse --short HEAD` 的输出。）
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `python3 tests/yzsgo-e2e/test_merge_evidence.py`
+Expected: PASS（1 test）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add .claude/skills/yzsgo-e2e/prep_conversation.py .claude/skills/yzsgo-e2e/SYNC.md tests/yzsgo-e2e/test_merge_evidence.py
+git commit -m "feat(yzsgo-e2e): 备料层——合并浏览器侧证据做前后端对照"
+```
+
+---
+
+## Task 5: judge_outcome.js 三态裁决纯函数 + judge_workflow.js
+
+**Files:**
+- Create: `.claude/skills/yzsgo-e2e/judge_outcome.js`
+- Create: `.claude/skills/yzsgo-e2e/judge_workflow.js`
+- Modify: `.claude/skills/yzsgo-e2e/SYNC.md`
+- Test: `tests/yzsgo-e2e-outcome.test.js`
+
+**Interfaces:**
+- Produces: `judge_outcome.js` 导出 `decideOutcome(votes)`，`votes` 为数组，元素 `{refuted: boolean}` 或 `null`（agent 失败）。逻辑（同 conversation-iq）：`good = votes.filter(Boolean)`；`n = good.length`；`refuted = good.filter(v => v.refuted).length`；`n===0 → 'needs_review'`；`refuted===n → 'rejected'`；`refuted > n/2 → 'needs_review'`；否则 `'confirmed'`。
+- `judge_workflow.js` 是 Workflow 脚本（`export const meta` + `agent/parallel/pipeline` 全局），import `decideOutcome`；judge prompt 增「前端所见 vs wire 一致性」维度；`args.knownIssues` 由 Claude 运行时用 `gh` 拉入。
+
+- [ ] **Step 1: 写失败测试**
+
+```javascript
+// tests/yzsgo-e2e-outcome.test.js
+import { test } from "node:test";
+import assert from "node:assert";
+import { decideOutcome } from "../.claude/skills/yzsgo-e2e/judge_outcome.js";
+
+test("多数不反驳 → confirmed", () => {
+  assert.equal(decideOutcome([{refuted:false},{refuted:false},{refuted:true}]), "confirmed");
+});
+test("全票反驳 → rejected", () => {
+  assert.equal(decideOutcome([{refuted:true},{refuted:true},{refuted:true}]), "rejected");
+});
+test("过半但非全票反驳 → needs_review (split-vote)", () => {
+  assert.equal(decideOutcome([{refuted:true},{refuted:true},{refuted:false}]), "needs_review");
+});
+test("全员失败(null) → needs_review", () => {
+  assert.equal(decideOutcome([null,null,null]), "needs_review");
+});
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `node --test tests/yzsgo-e2e-outcome.test.js`
+Expected: FAIL — 无法 import `judge_outcome.js`
+
+- [ ] **Step 3: 写 judge_outcome.js + judge_workflow.js**
+
+```javascript
+// .claude/skills/yzsgo-e2e/judge_outcome.js
+export function decideOutcome(votes) {
+  const good = (votes || []).filter(Boolean);
+  const n = good.length;
+  const refuted = good.filter((v) => v.refuted).length;
+  if (n === 0) return "needs_review";
+  if (refuted === n) return "rejected";
+  if (refuted > n / 2) return "needs_review";
+  return "confirmed";
+}
+```
+
+```javascript
+// .claude/skills/yzsgo-e2e/judge_workflow.js
+// 改编自 optima-gateway conversation-iq/workflow.js（见 SYNC.md）。
+// 输入 args: { base, sids, knownIssues }（备料稿目录 / 待判对话文件名列表 / gh 实时拉的开着 issue 文本）。
+import { decideOutcome } from "./judge_outcome.js";
+
+export const meta = {
+  name: "yzsgo-e2e-judge",
+  description: "读 e2e 备料稿（wire + 前端证据）逐对话判缺陷，对抗验证出三态",
+  phases: [
+    { title: "Judge", detail: "每对话一个 agent 读备料稿判缺陷（含前后端一致性）" },
+    { title: "Verify", detail: "每条 novel finding 3 个 skeptic 读 runtime 源码反驳，三态裁决" },
+  ],
+};
+
+const A = typeof args === "string" ? JSON.parse(args) : args || {};
+
+const STABLE_NORMAL = `## 正常现象（不是缺陷，别报）：
+- compaction 摘要调用、abort、max_tokens 截断本身；
+- 前端 new_conversation 后主区只有本轮（预期）。`;
+
+const JUDGE_SCHEMA = {
+  type: "object",
+  properties: {
+    impression: { type: "string" },
+    findings: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          what: { type: "string" },
+          evidence: { type: "string" },
+          knownIssue: { type: "string" },
+        },
+        required: ["what", "evidence"],
+      },
+    },
+  },
+  required: ["impression", "findings"],
+};
+
+const VERDICT_SCHEMA = {
+  type: "object",
+  properties: { refuted: { type: "boolean" }, reason: { type: "string" } },
+  required: ["refuted", "reason"],
+};
+
+function judgePrompt(path) {
+  return `读备料稿 ${path}（含 wire transcript + 「前端所见」证据）。判这次端到端对话有没有网关/agent 缺陷。
+重点核对：① wire 里 agent 真实产出 vs 前端渲染是否一致（丢内容/半截/前端报错但 wire 成功、或反之）；
+② 悬空 tool_use / max_tokens 截断 / error / abort 是否造成用户可感问题；③ 回答是否编数据/答非所问/活没干完。
+${STABLE_NORMAL}
+已知开着的 issue（命中就在 knownIssue 里标 #号，仅打标签、不要因此不报）：
+${A.knownIssues || "(无)"}
+默认健康：证据不足别硬报。输出 impression + findings。`;
+}
+
+function verifyPrompt(f, path) {
+  return `有人在 ${path} 报了缺陷：「${f.what}」，证据：${f.evidence}。
+你是 skeptic：读**真实 runtime 源码**（optima-gateway / agent-runtime）核对机制，尽力反驳。默认判假（refuted=true），
+只有确凿证明该缺陷真实存在才 refuted=false。输出 refuted + reason。`;
+}
+
+const results = await pipeline(
+  A.sids,
+  (sid) =>
+    agent(judgePrompt(`${A.base}/${sid}.md`), {
+      label: `judge:${sid}`,
+      phase: "Judge",
+      schema: JUDGE_SCHEMA,
+    }).then((judge) => ({ sid, judge })),
+  async (prev) => {
+    if (!prev || !prev.judge) return { sid: prev?.sid, confirmed: [], needsReview: [], rejected: [] };
+    const path = `${A.base}/${prev.sid}.md`;
+    const novel = prev.judge.findings || [];
+    if (novel.length === 0)
+      return { sid: prev.sid, impression: prev.judge.impression, confirmed: [], needsReview: [], rejected: [] };
+    const verified = await parallel(
+      novel.map((f) => async () => {
+        const votes = await parallel(
+          [0, 1, 2].map(() => () => agent(verifyPrompt(f, path), { label: `verify:${prev.sid}`, phase: "Verify", schema: VERDICT_SCHEMA }))
+        );
+        return { finding: f, outcome: decideOutcome(votes) };
+      })
+    );
+    const by = (o) => verified.filter(Boolean).filter((v) => v.outcome === o);
+    return { sid: prev.sid, impression: prev.judge.impression, confirmed: by("confirmed"), needsReview: by("needs_review"), rejected: by("rejected") };
+  }
+);
+
+return { results: results.filter(Boolean) };
+```
+
+`SYNC.md` 追加：
+
+```markdown
+| judge_workflow.js | optima-gateway · .claude/skills/conversation-iq/workflow.js（改编：+前后端一致性维度） | <hash> | 2026-08-31 |
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `node --test tests/yzsgo-e2e-outcome.test.js`
+Expected: PASS（4 tests）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add .claude/skills/yzsgo-e2e/judge_outcome.js .claude/skills/yzsgo-e2e/judge_workflow.js .claude/skills/yzsgo-e2e/SYNC.md tests/yzsgo-e2e-outcome.test.js
+git commit -m "feat(yzsgo-e2e): judge 三态裁决纯函数 + Workflow 编排（前后端一致性维度）"
+```
+
+---
+
+## Task 6: run_e2e.py 编排入口 + render_report 纯函数
+
+**Files:**
+- Create: `.claude/skills/yzsgo-e2e/run_e2e.py`
+- Test: `tests/yzsgo-e2e/test_render_report.py`
+
+**Interfaces:**
+- Consumes: `preflight.{probe,summarize_preflight}`、`chat_driver.ChatDriver`、`pull_wire.{pull,emit_conversation_index,locate_conversation,render_conversation}`、`prep_conversation.merge_browser_evidence`。
+- Produces:
+  - `render_report(result: dict) -> str`：`result = {"env","started_ts","first_message","confirmed":[...],"needs_review":[...],"blocked": str|None,"coverage": str}`；`confirmed`/`needs_review` 每项 `{"what","evidence"}`。输出 markdown：标题 + 「本次端到端问题」表（confirmed 标 `confirmed`、needs_review 标 `needs_review`）+ `## 覆盖边界` + `## 判断修正`；`blocked` 非空时顶部标 `> ⚠️ blocked: <原因>（环境问题，非缺陷，未提 issue）`。
+  - `main()`：argparse `--env/--message(可多次)/--answer(可多次 k=v)/--expect/--out/--issue-repo`（默认 `Optima-Chat/optima-gateway`）；串起四段，落备料稿 + 元数据 JSON（含 `started_ts/first_message/located_gidx`）到 `--out`，打印备料稿路径供 Claude 跑 `judge_workflow.js`。**run_e2e 不在脚本里跑 LLM**（judge 由 Claude 用 Workflow 跑）；提 issue 由 Claude 依 SKILL.md 规则用 `gh` 做。
+
+- [ ] **Step 1: 写失败测试**
+
+```python
+# tests/yzsgo-e2e/test_render_report.py
+import os, sys, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".claude", "skills", "yzsgo-e2e"))
+from run_e2e import render_report
+
+class TestReport(unittest.TestCase):
+    def test_confirmed_and_needs_review_rows(self):
+        md = render_report({
+            "env": "cn-prod", "started_ts": "2026-08-31T14:00:00Z", "first_message": "你好",
+            "confirmed": [{"what": "前端丢了工具卡", "evidence": "wire 有 tool_result，前端未渲染"}],
+            "needs_review": [{"what": "疑似截断", "evidence": "max_tokens=1"}],
+            "blocked": None, "coverage": "单次对话；skeptic 读源码",
+        })
+        self.assertIn("前端丢了工具卡", md)
+        self.assertIn("confirmed", md); self.assertIn("needs_review", md)
+        self.assertIn("## 覆盖边界", md); self.assertIn("## 判断修正", md)
+        self.assertNotIn("blocked:", md)
+
+    def test_blocked_banner(self):
+        md = render_report({"env": "cn-prod", "started_ts": "t", "first_message": "x",
+                            "confirmed": [], "needs_review": [], "blocked": "积分不足", "coverage": "-"})
+        self.assertIn("blocked: 积分不足", md)
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `python3 tests/yzsgo-e2e/test_render_report.py`
+Expected: FAIL — `ModuleNotFoundError: No module named 'run_e2e'`
+
+- [ ] **Step 3: 写 run_e2e.py**
+
+```python
+#!/usr/bin/env python3
+"""yzsgo-e2e 编排：驱动对话 → 拉 wire → 定位本次对话 → 备料（含浏览器证据）→ 出备料稿+元数据。
+judge 由 Claude 用 judge_workflow.js 跑；提 issue 由 Claude 依 SKILL.md 用 gh 做。用户不敲本脚本。"""
+import argparse, json, os, sys
+from datetime import datetime, timezone
+
+def render_report(result: dict) -> str:
+    L = [f"# yzsgo-e2e 报告 · {result['env']} · {result['started_ts']}", ""]
+    if result.get("blocked"):
+        L.append(f"> ⚠️ blocked: {result['blocked']}（环境问题，非缺陷，未提 issue）")
+        L.append("")
+    L += ["## 本次端到端问题（按严重度）", "", "| 状态 | 问题 | 证据 |", "|---|---|---|"]
+    for f in result.get("confirmed", []):
+        L.append(f"| confirmed | {f['what']} | {f['evidence']} |")
+    for f in result.get("needs_review", []):
+        L.append(f"| needs_review | {f['what']} | {f['evidence']} |")
+    if not result.get("confirmed") and not result.get("needs_review"):
+        L.append("| — | 无 confirmed/needs_review | — |")
+    L += ["", "## 覆盖边界", result.get("coverage", "-"),
+          "", "## 判断修正", "（如判定过程中修正过结论，如实记此；无则写'无'）"]
+    return "\n".join(L)
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+def _parse_answers(pairs):
+    out = []
+    for p in pairs or []:
+        if "=" in p:
+            k, v = p.split("=", 1)
+            out.append({"match": k, "answer": v})
+    return out
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--env", default="cn-prod", choices=["cn-prod", "cn-stage"])
+    ap.add_argument("--message", action="append", required=True, help="逐轮发送的消息（可多次）")
+    ap.add_argument("--answer", action="append", help="反问预设答案 关键词=答案（可多次）")
+    ap.add_argument("--expect", default="", help="关注点，喂给判定层")
+    ap.add_argument("--user", required=True, help="测试账号 userId（拉 wire 用）")
+    ap.add_argument("--out", default="e2e-out")
+    ap.add_argument("--issue-repo", default="Optima-Chat/optima-gateway")
+    args = ap.parse_args()
+
+    if args.env == "cn-stage":
+        print("[warn] cn-stage 的 wire 取法未验证（spec §8 待核实）；仅 cn-prod 全链路已打通。", file=sys.stderr)
+
+    os.makedirs(args.out, exist_ok=True)
+    import preflight, chat_driver, pull_wire, prep_conversation
+    pf = preflight.summarize_preflight(preflight.probe(args.env))
+    if not pf["ok"]:
+        print(pf["report"]); print("\n[preflight 未通过，先按提示准备环境]"); sys.exit(2)
+
+    started_ts = _utc_now()
+    answers = _parse_answers(args.answer)
+    d = chat_driver.ChatDriver().attach()
+    d.new_conversation()
+    turns = []
+    for msg in args.message:
+        r = d.send_and_wait(msg, answers=answers)
+        turns.append({"sent": msg, "state": r.get("state"), "transcript": r.get("transcript", ""),
+                      "tool_trace": r.get("tool_trace"), "timed_out": r.get("timed_out", False)})
+    d.close()
+
+    wire_root = pull_wire.pull(args.user, since_days=1, out=args.out)
+    meta = {"env": args.env, "started_ts": started_ts, "first_message": args.message[0],
+            "expect": args.expect, "issue_repo": args.issue_repo, "turns": turns}
+    if wire_root:
+        index = pull_wire.emit_conversation_index(wire_root)
+        hit = pull_wire.locate_conversation(index, started_ts, args.message[0])
+        meta["located"] = hit
+        if hit:
+            sdir = os.path.join(wire_root, hit["sid"])
+            deref = pull_wire.make_deref(sdir)
+            recs = [json.loads(l) for l in open(os.path.join(sdir, "records.jsonl"), encoding="utf-8") if l.strip()]
+            reqs = [x for x in recs if x.get("kind") == "request"]
+            resps = {x.get("callId"): x for x in recs if x.get("kind") in ("response", "error")}
+            convs = pull_wire.segment(reqs, deref)
+            conv = convs[hit["gidx"] - 1] if hit["gidx"] - 1 < len(convs) else convs[-1]
+            _, _, _, _, wire_md = pull_wire.render_conversation(conv, resps, deref, hit["gidx"])
+            prepped = prep_conversation.merge_browser_evidence(wire_md, turns)
+            open(os.path.join(args.out, "prepped.md"), "w", encoding="utf-8").write(prepped)
+    open(os.path.join(args.out, "meta.json"), "w", encoding="utf-8").write(json.dumps(meta, ensure_ascii=False, indent=2))
+    print(f"[done] 备料稿 → {args.out}/prepped.md  元数据 → {args.out}/meta.json")
+    print("下一步：Claude 用 judge_workflow.js 判定，confirmed 提 issue 到", args.issue_repo)
+
+if __name__ == "__main__":
+    main()
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `python3 tests/yzsgo-e2e/test_render_report.py`
+Expected: PASS（2 tests）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add .claude/skills/yzsgo-e2e/run_e2e.py tests/yzsgo-e2e/test_render_report.py
+git commit -m "feat(yzsgo-e2e): run_e2e 编排入口 + 报告渲染"
+```
+
+---
+
+## Task 7: SKILL.md 正文 + README/service-matrix 对齐 + .codex 镜像
+
+**Files:**
+- Modify: `.claude/skills/yzsgo-e2e/SKILL.md`（补正文）
+- Modify: `README.md`（skill 清单加 yzsgo-e2e）
+- Read then maybe Modify: `tests/service-matrix-alignment.test.js`
+- Create: `.codex/skills/yzsgo-e2e/`（镜像整个目录）
+- Test: `node --test tests/service-matrix-alignment.test.js`（及既有 `npm test`）
+
+**Interfaces:**
+- Produces: 完整可触发的 skill；双端镜像一致。
+
+- [ ] **Step 1: 先读校验测试，确认它校验什么**
+
+Run: `sed -n '1,60p' tests/service-matrix-alignment.test.js`
+判断它是否校验「README 清单 ⇄ `.claude/skills/` 目录 ⇄ `.codex/skills/`」一致。这决定 Step 3 要同步哪些清单。若它是失败测试（新增 skill 未登记会红），本步即「确认失败」。
+
+- [ ] **Step 2: 写 SKILL.md 正文**
+
+在 frontmatter 下补正文，含这些必备节（照 spec §4–§9）：
+
+```markdown
+# yzsgo-e2e — 鸭嘴兽通用端到端测试
+
+用浏览器真机驱动鸭嘴兽完成一段对话，同时拿浏览器侧结果 + 拉 gateway wire，判前后端一致性与网关缺陷，confirmed 自动提 issue。
+
+## 何时用
+- 「端到端测一下鸭嘴兽」「e2e 测这段对话」「用浏览器真机测整个流程有没有问题」
+
+## 用户说人话 → 我怎么映射（用户不敲 CLI）
+- 用户给的对话内容 → 逐轮 `--message`（按序）。
+- 用户提到「遇到它问 X 就答 Y / 测某个反问」→ `--answer "X=Y"`。
+- 用户说「重点看有没有 Z」→ `--expect "Z"`。
+
+## 四段流程
+1. **preflight**：`python3 preflight.py <env>`；缺项按提示准备（一次性登录/充值见 store-skills `setting-up-yzsgo-test-env`，我不替做）。
+2. **驱动 + 拉 wire + 备料**：`python3 run_e2e.py --env <env> --user <测试账号userId> --message ... [--answer k=v] [--expect ...] --out <dir>` → 出 `prepped.md` + `meta.json`。
+3. **判定**：`gh issue list --repo Optima-Chat/optima-gateway --state open --json number,title` 拉已知 issue 文本，`Workflow({scriptPath:"<skill>/judge_workflow.js", args:{base:"<dir>", sids:["prepped"], knownIssues:"<文本>"}})`。
+4. **报告 + 提 issue**：出报告（`render_report`）。**confirmed 直接 `gh issue create --repo Optima-Chat/optima-gateway --label needs-triage`**（证据=前端输出+wire transcript+repro 对话），提错可改可删；**needs_review 不自动提**，报告单列待人工；**环境类标 blocked 不提**。
+
+## 诚实边界（照搬 conversation-iq）
+- 「0 confirmed」≠「没问题」；needs_review 绝不静默毙。
+- 对抗验证必须让 skeptic 读**真实 runtime 源码**，默认判假。
+- 报告固定含「覆盖边界」+「判断修正」两节。
+
+## 前后端对照（本 skill 独有）
+判定要核对**前端渲染的** vs **wire 里 agent 真实产出的**：前端丢内容/半截/报错但 wire 成功（或反之）= 缺陷。
+
+## vendor 同步纪律
+`chat_driver.py`/`pull_wire.py` 上游权威 = optima-store-skills；`prep_conversation.py`/`judge_workflow.js` 改编自 optima-gateway conversation-iq。见 `SYNC.md`。驱动异常先怀疑前端 DOM 漂移 → 去上游同步。可跑 `python3 verify_drift.py` 比对。
+
+## 两环境
+`--env cn-prod`（已打通）/ `cn-stage`（wire 取法待核实，脚本会告警）。
+```
+
+- [ ] **Step 3: README 加清单 + 镜像 .codex**
+
+在 `README.md` 的 skill 列表（`## 📋 任务场景` 段）按字母序插入一行：
+
+```markdown
+- **yzsgo-e2e** - 鸭嘴兽通用端到端测试：浏览器真机驱对话 + 拉 wire + 语义判定 + 提 issue（cn-prod；cn-stage 待核实）
+```
+
+镜像目录：
+
+```bash
+rm -rf .codex/skills/yzsgo-e2e
+cp -R .claude/skills/yzsgo-e2e .codex/skills/yzsgo-e2e
+```
+
+若 Step 1 发现 `service-matrix-alignment.test.js` 另有清单来源（如某个 matrix 常量/文件），按其规则补登 `yzsgo-e2e`。
+
+- [ ] **Step 4: 跑校验测试通过**
+
+Run: `npm test`（含 `node --test tests/*.test.js`，覆盖 service-matrix 与 outcome 测试）
+Expected: PASS（service-matrix 不再因缺 yzsgo-e2e 而红；outcome 测试通过）
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add .claude/skills/yzsgo-e2e/SKILL.md README.md .codex/skills/yzsgo-e2e tests/service-matrix-alignment.test.js
+git commit -m "feat(yzsgo-e2e): SKILL.md 正文 + README/service-matrix 对齐 + .codex 镜像"
+```
+
+---
+
+## Task 8: verify_drift.py 漂移比对 + 真机 smoke 文档
+
+**Files:**
+- Create: `.claude/skills/yzsgo-e2e/verify_drift.py`
+- Modify: `.claude/skills/yzsgo-e2e/SKILL.md`（补 smoke 步骤）
+- Modify: `.codex/skills/yzsgo-e2e/`（同步）
+- Test: `tests/yzsgo-e2e/test_verify_drift.py`
+
+**Interfaces:**
+- Produces: `plan_drift_checks(present: dict) -> list[dict]`。`present` = `{"store-skills": bool, "gateway": bool}`。返回每个 vendored 文件一项 `{"file","upstream","checkable": bool}`：上游 repo 在场→`checkable=True`，不在场→`checkable=False`（跳过，不报错）。
+
+- [ ] **Step 1: 写失败测试**
+
+```python
+# tests/yzsgo-e2e/test_verify_drift.py
+import os, sys, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", ".claude", "skills", "yzsgo-e2e"))
+from verify_drift import plan_drift_checks
+
+class TestDrift(unittest.TestCase):
+    def test_absent_repo_skipped(self):
+        checks = plan_drift_checks({"store-skills": False, "gateway": False})
+        self.assertTrue(all(not c["checkable"] for c in checks))
+
+    def test_present_repo_checkable(self):
+        checks = plan_drift_checks({"store-skills": True, "gateway": True})
+        files = {c["file"] for c in checks if c["checkable"]}
+        self.assertIn("chat_driver.py", files)   # 来自 store-skills
+        self.assertIn("judge_workflow.js", files) # 来自 gateway
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `python3 tests/yzsgo-e2e/test_verify_drift.py`
+Expected: FAIL — `ModuleNotFoundError: No module named 'verify_drift'`
+
+- [ ] **Step 3: 写 verify_drift.py**
+
+```python
+#!/usr/bin/env python3
+"""比对 vendored 文件与上游是否漂移。上游 repo 不在本机则跳过（不破坏自包含）。"""
+import os, subprocess, sys
+
+VENDORED = [
+    {"file": "chat_driver.py", "repo": "store-skills",
+     "upstream": "~/optima-store-skills/.claude/skills/operating-yzsgo-chat/chat_driver.py"},
+    {"file": "pull_wire.py", "repo": "store-skills",
+     "upstream": "~/optima-store-skills/.claude/skills/pulling-yzsgo-session-wire/pull_wire.py"},
+    {"file": "prep_conversation.py", "repo": "gateway",
+     "upstream": "~/optima-gateway/.claude/skills/conversation-iq/prep_session.py"},
+    {"file": "judge_workflow.js", "repo": "gateway",
+     "upstream": "~/optima-gateway/.claude/skills/conversation-iq/workflow.js"},
+]
+
+def plan_drift_checks(present: dict) -> list:
+    out = []
+    for v in VENDORED:
+        out.append({"file": v["file"], "upstream": v["upstream"],
+                    "checkable": bool(present.get(v["repo"], False))})
+    return out
+
+def _present() -> dict:
+    return {"store-skills": os.path.isdir(os.path.expanduser("~/optima-store-skills")),
+            "gateway": os.path.isdir(os.path.expanduser("~/optima-gateway"))}
+
+if __name__ == "__main__":
+    here = os.path.dirname(os.path.abspath(__file__))
+    for c in plan_drift_checks(_present()):
+        if not c["checkable"]:
+            print(f"⏭  {c['file']}：上游不在本机，跳过"); continue
+        up = os.path.expanduser(c["upstream"])
+        r = subprocess.run(["diff", "-q", os.path.join(here, c["file"]), up], capture_output=True, text=True)
+        print(("✅ " if r.returncode == 0 else "⚠️  漂移 ") + f"{c['file']} vs {c['upstream']}")
+```
+
+> 注：`prep_conversation.py`/`judge_workflow.js` 是**改编**（非全等），`diff` 必然有差异——`⚠️` 对它们是「提醒去看上游有没有新变更」而非「必须一致」。SKILL.md 里说明这一点。
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `python3 tests/yzsgo-e2e/test_verify_drift.py`
+Expected: PASS（2 tests）
+
+- [ ] **Step 5: 补 SKILL.md smoke 步骤，同步 .codex，提交**
+
+在 SKILL.md 末尾加：
+
+```markdown
+## 真机 smoke（改完先跑这个验管道通）
+python3 run_e2e.py --env cn-prod --user <测试账号userId> --message "你好" --out /tmp/yzsgo-smoke
+# 期望：/tmp/yzsgo-smoke/prepped.md 含「前端所见」节 + wire transcript；meta.json 的 located 命中本次对话。
+# 只验四段接线通，不追判定质量。
+```
+
+同步镜像并提交：
+
+```bash
+cp -R .claude/skills/yzsgo-e2e/. .codex/skills/yzsgo-e2e/
+git add .claude/skills/yzsgo-e2e/verify_drift.py .claude/skills/yzsgo-e2e/SKILL.md .codex/skills/yzsgo-e2e tests/yzsgo-e2e/test_verify_drift.py
+git commit -m "feat(yzsgo-e2e): 漂移比对 + 真机 smoke 文档"
+```
+
+---
+
+## Self-Review（作者自查，已随计划完成）
+
+**Spec 覆盖：** §3 目录结构→Task1-8 全建；§4 输入映射→Task6 argparse + Task7 SKILL.md；§5 四段→Task2/3/4/6（驱动/拉wire/定位/备料）+Task5（判定）；§6 前后端对照→Task4 merge + Task5 judgePrompt；§7 报告/提issue→Task6 render_report + Task7 SKILL.md 规则；§8 两环境→Task6 `--env` + cn-stage 告警；§9 vendor 纪律→Task2 SYNC + Task8 verify_drift；§10 双端/测试→Task7 镜像+校验、各任务 TDD。
+
+**Placeholder 扫描：** 无 TBD/TODO；每个新函数含真实测试+实现；vendored 用 cp 明确动作；`<hash>` 处标明用 `git rev-parse` 取真实值（非 placeholder，是运行期取值）。
+
+**类型一致：** `wait_reply` 返回键（state/transcript/tool_trace/timed_out）在 Task6 turns 与 Task4 merge 输入一致；`decideOutcome` 输入 `{refuted}` 与 workflow votes 一致；`locate_conversation` 返回 `{gidx,sid,ts,prompt}` 与 Task6 `hit["sid"]/hit["gidx"]` 用法一致；`render_report` 字段与 test 一致。
+
+**开放项（执行期处理，非阻塞）：** cn-stage wire 取法（Task6 已告警占位）；前端是否暴露 sessionId（暴露则可替代时间戳定位，Task3 可增强）；chat_driver 是否裁 marketplace 方法（Task2 注为后续可选）。