@optima-chat/dev-skills 0.16.3 → 0.16.4

package/.claude/skills/gateway-admin/SKILL.md

@@ -7,6 +7,21 @@ description: 当用户请求操作 gateway 管理面时使用——COO kill/软
 
 当用户要求「杀掉某用户的 COO / 软杀容器 / drain warm pool / 查 gateway 配置 / 调 llm 费率 / 管理 provider key」等 gateway 管理面操作时，使用 `optima-gateway-admin` CLI。
 
+## 🔴🔴 warm-pool `drain?mode=hard` = 掐正在服务的用户会话（禁止用于发布验证）
+
+`POST /admin/warm-pool/drain?mode=hard` 退的**不是**空闲 pod，是**连 ready + assigned + active 一起退**——即**正在服务用户的会话容器**。active 容器不在 60s 自退 → OrphanDetector `cleanup retire-stuck` → `deleteContainerGroup` 强删 → **在飞 turn 当场 abort（含 HITL 提问被打断）**，用户侧表现为「agent 停了」。
+- 实证（gw#2357）：2026-08-31 cn-prod 6 次 hard drain 每次掐 **7–12 个真实用户会话**；另 07:26/07:28Z 的网关重启抖动亦冲掉真实在飞会话（本 skill 作者用 conversation-IQ 实锤，gw#1842/#1227）。
+- ⇒ **hard drain 仅事故止血用，日常与发布验证一律禁用。** 真要 drain 也先 `mode=soft`（只退空闲、不碰在跑会话）。cn-prod 上 hard drain 前必须先 `GET /admin/warm-pool/tasks` 数一眼有多少 active（带 sessionId 的即真实会话），确认要掐几个用户再决定。
+
+## ✅ 发布 skill 后如何验证「最新版已生效」——**不要 recycle / drain warm pool**
+
+🔴 **skill 不是 warm pod 的属性**：marketplace skill 在会话 **claim 之后**（`task_connected`）由 gateway 现算 desired 下发，agent 按用户 NAS 里的 `.plugin-version` 比对、不同才重下；ready 状态的 warm pod 里**没有任何用户 skill**。
+⇒ **publish 后下一次新建会话就会拉到新版，drain/recycle 完全无关**（且会误伤在跑用户）。验证走这三个只读入口：
+- 镜像（烘死的 builtin pack）换代：`optima-gateway-admin GET /admin/runtime/images --env cn-prod`（看 `rotationComplete` / `@sha256`）
+- 某会话实际派了哪版 skill：`optima-logs gateway-core --env cn-prod --grep "Skill sync dispatched"`（看 `plugins:[...]` 版本）
+- 最直接：**新开一个会话**、load 目标 skill，看拿到的版本号。
+- 长寿会话内热换代靠 `SKILL_SYNC_REFRESH_TTL_MS`（默认 0=关），不是靠 drain。
+
 ## 用法
 
 ```bash

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

@@ -0,0 +1,51 @@
+---
+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"`。
+
+## 四段流程
+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**：
+   判定跑完后，先把 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 run_e2e.py --env cn-prod --user <测试账号userId> --message "你好" --out /tmp/yzsgo-smoke
+# 期望：/tmp/yzsgo-smoke/prepped.md 含「前端所见」节 + wire transcript；meta.json 的 located 命中本次对话。
+# 只验四段接线通，不追判定质量。
+```

package/.claude/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 单测）的副本，改逻辑需同步两处。