@optima-chat/dev-skills 0.16.3 → 0.16.5

package/.claude/skills/yzsgo-e2e/verify_drift.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""比对 vendored 文件与上游是否漂移。上游 repo 不在本机则跳过（不破坏自包含）。"""
+import os, subprocess
+
+# adapted=True 的文件在上游基础上有本地改动/追加，diff 必然 ≠0 → ⚠️ 是「去看上游有无新变更」而非缺陷；
+# adapted=False 是逐字 vendored，应与上游一致，⚠️ 才是真漂移。
+VENDORED = [
+    {"file": "chat_driver.py", "repo": "store-skills", "adapted": False,
+     "upstream": "~/optima-store-skills/.claude/skills/operating-yzsgo-chat/chat_driver.py"},
+    {"file": "pull_wire.py", "repo": "store-skills", "adapted": True,   # 追加了 emit_conversation_index/locate_conversation
+     "upstream": "~/optima-store-skills/.claude/skills/pulling-yzsgo-session-wire/pull_wire.py"},
+    {"file": "prep_conversation.py", "repo": "gateway", "adapted": True,
+     "upstream": "~/optima-gateway/.claude/skills/conversation-iq/prep_session.py"},
+    {"file": "judge_workflow.js", "repo": "gateway", "adapted": True,
+     "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"],
+                    "adapted": v.get("adapted", False),
+                    "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)
+        if r.returncode == 0:
+            print(f"✅ {c['file']} 与上游一致")
+        elif c.get("adapted"):
+            print(f"⚠️(改编·预期) {c['file']}：与上游有差异属正常，去看上游有无值得同步的新变更")
+        else:
+            print(f"⚠️ 漂移 {c['file']} vs {c['upstream']}（逐字 vendored，应一致 → 去同步）")

package/.codex/skills/yzsgo-e2e/SKILL.md

@@ -0,0 +1,63 @@
+---
+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"]
+---
+
+# yzsgo-e2e — 鸭嘴兽通用端到端测试
+
+用浏览器真机驱动鸭嘴兽完成一段对话，同时拿浏览器侧结果 + 拉 gateway wire，判前后端一致性与网关缺陷，confirmed 自动提 issue。
+
+## 何时用
+- 「端到端测一下鸭嘴兽」「e2e 测这段对话」「用浏览器真机测整个流程有没有问题」
+
+## 用户说人话 → 我怎么映射（用户不敲 CLI）
+- 用户给的对话内容 → 逐轮 `--message`（按序）。
+- 用户提到「遇到它问 X 就答 Y / 测某个反问」→ `--answer "X=Y"`。
+- 用户说「重点看有没有 Z」→ `--expect "Z"`。
+
+## 环境自举（第一步，自包含——别外链别的仓库）
+脚本都在本 skill 目录（记为 `$S`，就是本 SKILL.md 所在目录）。托管 venv = `~/.cache/yzsgo-e2e/venv`（记 `$VENV`），不碰系统 python。
+
+1. **体检**：`python3 $S/preflight.py <env>`。缺项分两类：
+   - 🅰️ **auto（能自动装）**：`venv+playwright`、`sshpass`。
+   - ✋ **manual（凭据/登录，装不了）**：`chrome-9222`（登了测试账号的调试 Chrome）、`buildbox-pw`、`test-user-id`。
+2. **逐个补缺**（🔴 全绿才往下；不绿就停下、别硬跑半残）：
+   - 每个 🅰️ 缺项：**先问用户「要我装 `<name>` 吗？」，用户同意了**再跑 `python3 $S/bootstrap.py setup`（装 venv+playwright）或 `python3 $S/bootstrap.py install-sshpass`。别不问就装。
+   - 每个 ✋ 缺项：引导用户——`chrome-9222`：`python3 $S/bootstrap.py launch-chrome` 起窗口、让用户**手动登测试账号**（登一次长期免登）；`buildbox-pw`：让用户把口令放 `~/.buildbox_pw`（内部拉 wire 用，向团队要）；`test-user-id`：让用户登录 Optima（run_e2e 自动从 `~/.optima/token.json` 读 userId）。
+   - 补完 `python3 $S/preflight.py <env>` 复检，直到全 ✅ 才进四段。
+
+## 四段流程
+1. **preflight + 自举**：见上「环境自举」，**全绿**才继续。
+2. **驱动 + 拉 wire + 备料**：`$VENV/bin/python $S/run_e2e.py --env <env> --message ... [--answer k=v] [--expect ...] --out <dir>` → 出 `prepped.md` + `meta.json`。🔑 用 **venv 的 python**（playwright 在那儿）；`--user` 不给则自动读 `~/.optima/token.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**：
+   判定跑完后，先把 judge_workflow 输出 + meta.json 组装成 render_report 的入参（两者字段形状不同，别直接传）：
+   - `confirmed` = 各 sid 的 `confirmed` 里取 `finding` → `{what, evidence}`，跨 sid 合并
+   - `needs_review` = 各 sid 的 `needsReview` 里取 `finding` → `{what, evidence}`
+   - `env` / `started_ts` / `first_message` 从 `<out>/meta.json` 读
+   - `blocked` = 环境类阻断原因（浏览器 state=service_error / 积分不足 / 桌面没连…），否则 None
+   - `coverage` = 本次覆盖边界（单次对话 / skeptic 读源码 / 去重挡已知 等，如实写）
+   再调 `run_e2e.render_report(result)` 出报告。**confirmed 直接 `gh issue create --repo Optima-Chat/optima-gateway --label needs-triage`**（证据=前端输出+wire transcript+repro 对话），提错可改可删；判定为纯前端缺陷（前端渲染问题、非 agent/网关逻辑）→ 提到对应前端 repo（而非 gateway）；拿不准就默认 gateway。**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` 比对。只有 `chat_driver.py` 是逐字 vendored、应与上游一致；`pull_wire.py`（在上游基础上追加了 emit_conversation_index/locate_conversation）、`prep_conversation.py`、`judge_workflow.js` 都是改编，`verify_drift.py` 对它们标「⚠️(改编·预期)」是提醒去看上游有无新变更，非「必须一致」。
+
+## 两环境
+`--env cn-prod`（已打通）/ `cn-stage`（wire 取法待核实，脚本会告警）。
+
+## 真机 smoke（改完先跑这个验管道通）
+```bash
+python3 $S/preflight.py cn-prod          # 先体检，缺项按「环境自举」补齐到全绿
+$VENV/bin/python $S/run_e2e.py --env cn-prod --message "你好" --out /tmp/yzsgo-smoke
+# 期望：/tmp/yzsgo-smoke/prepped.md 含「前端所见」节 + wire transcript；meta.json 的 located 命中本次对话。
+# 只验四段接线通，不追判定质量。（--user 自动读 token.json）
+```

package/.codex/skills/yzsgo-e2e/SYNC.md

@@ -0,0 +1,10 @@
+# vendored 文件上游台账
+
+| 本文件 | 上游 repo · 路径 | commit | 同步日期 |
+|---|---|---|---|
+| chat_driver.py | optima-store-skills · .claude/skills/operating-yzsgo-chat/chat_driver.py | 7a1685a | 2026-08-31 |
+| pull_wire.py | optima-store-skills · .claude/skills/pulling-yzsgo-session-wire/pull_wire.py | 7a1685a | 2026-08-31 |
+| prep_conversation.py | optima-gateway · .claude/skills/conversation-iq/prep_session.py（改编：+浏览器证据合并） | b75f575c | 2026-08-31 |
+| judge_workflow.js | optima-gateway · .claude/skills/conversation-iq/workflow.js（改编：+前后端一致性维度） | b75f575c | 2026-08-31 |
+
+> 注：judge_workflow.js 内联的 decideOutcome 是 judge_outcome.js（有 node 单测）的副本，改逻辑需同步两处。

package/.codex/skills/yzsgo-e2e/bootstrap.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""yzsgo-e2e 自举：把「能装的」依赖装好。**征得用户同意由 SKILL.md/Claude 负责问**，
+本脚本只在被调用时执行对应动作。托管 venv 放 ~/.cache/yzsgo-e2e/venv——不碰系统 python
+（macOS/发行版的系统 python 常是外部管理，pip install 会被拒），最稳、可复现、不污染。"""
+import os, subprocess, sys
+
+VENV = os.path.expanduser("~/.cache/yzsgo-e2e/venv")
+
+
+def venv_python(base: str = VENV) -> str:
+    return os.path.join(base, "bin", "python")
+
+
+def plan_actions(missing_names: list, base: str = VENV) -> list:
+    """纯函数：把缺项名映射成要执行的命令序列。供单测 + 让 Claude/用户预知会跑什么。
+    返回 [(动作名, [[argv...], ...]), ...]。只覆盖 auto 类缺项（manual 类装不了，不在此）。"""
+    plan = []
+    for n in missing_names:
+        if n == "venv+playwright":
+            plan.append(("setup", [
+                [sys.executable, "-m", "venv", base],
+                [venv_python(base), "-m", "pip", "install", "-q", "playwright"],
+                [venv_python(base), "-m", "playwright", "install", "chromium"],
+            ]))
+        elif n == "sshpass":
+            plan.append(("install-sshpass", [["brew", "install", "hudochenkov/sshpass/sshpass"]]))
+        elif n == "chrome-9222":
+            plan.append(("launch-chrome", [[
+                "open", "-na", "Google Chrome", "--args",
+                "--remote-debugging-port=9222", "--user-data-dir=/tmp/yzsgo-chrome",
+                "https://www.yzsgo.com"]]))
+    return plan
+
+
+def _run(cmds: list) -> bool:
+    for c in cmds:
+        print("+", " ".join(c))
+        if subprocess.run(c).returncode != 0:
+            print(f"[bootstrap] 命令失败：{' '.join(c)}", file=sys.stderr)
+            return False
+    return True
+
+
+def _do(name: str) -> bool:
+    plan = plan_actions([name])
+    if not plan:
+        print(f"[bootstrap] 无法自动处理 {name}（可能是 manual 类，需人工准备）", file=sys.stderr)
+        return False
+    return _run([c for _, cmds in plan for c in cmds])
+
+
+# 动作名 → 触发它的缺项名
+_CMD_TO_MISSING = {"setup": "venv+playwright", "install-sshpass": "sshpass", "launch-chrome": "chrome-9222"}
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "setup"
+    miss = _CMD_TO_MISSING.get(cmd)
+    if not miss:
+        print(f"未知命令 {cmd}；可用：{' / '.join(_CMD_TO_MISSING)}", file=sys.stderr)
+        sys.exit(2)
+    ok = _do(miss)
+    if cmd == "launch-chrome" and ok:
+        print("已起调试端口 Chrome；请在弹出的窗口里手动登录测试账号（登一次即长期免登）。")
+    sys.exit(0 if ok else 1)