@optima-chat/dev-skills 0.16.2 → 0.16.4

package/.codex/skills/cn-deploy/SKILL.md

@@ -30,7 +30,7 @@ optima-cn-deploy --list                       # 列出全部可发服务
 7. **build-only 服务（`agent-runtime`）**：非 SAE 常驻（gateway-core 按 session 拉起的镜像）。成功标准不是 SAE ImageUrl，而是流水线绿即可——release 段自动把 ACR digest 回写 Infisical `/services/gateway-core/ALIYUN_AGENT_RUNTIME_IMAGE`(#807) 并滚动重启 gateway-core（任一步失败即 exit 非 0）。工具最后一行为 `✓ 流水线 SUCCESS(build-only)…` —— CLI 以流水线终态为准，未独立校验 Infisical/gateway-core（digest 与重启变更单见 run『发版』段日志）。
 
 
-## cn-prod vtag 发版（⚠️ 待 svenyang 首次验证通过后再日常使用）
+## cn-prod vtag 发版（通路已跑通；清单外的服务仍算首发）
 
 ```bash
 optima-cn-deploy <service> --vtag cn-v1.2.3               # 先 stage 同 tag 验证
@@ -38,9 +38,11 @@ optima-cn-deploy <service> --env prod --vtag cn-v1.2.3    # prod 发版
 ```
 
 - prod 是 vtag 制：必须先 `git tag cn-vX.Y.Z && git push`，工具拒绝无 vtag / 裸 v* / 带 --branch 的 prod 请求
-- prod 流水线构建后**停在人工卡点**（xbfool/svenyang 在云效控制台审批），之后 DB 迁移 + digest 钉死部署自动走完
+- 🔴 prod 流水线**没有人工卡点**：构建 → DB 迁移 → digest 钉死部署一路自动走完，不会停下来等谁审批。**敲下命令那一刻就是最终决策点**；触发后要中止只能去云效 run 页面手动取消（实测 2026-08-09，见 #89）
 - 成功标准：prod SAE ImageUrl 为 `@sha256:` digest 寻址（工具最后一行校验）
+- ⚠️ **老路径会盖掉 digest**：云效 prod 钉的是 `@sha256:` digest，buildbox `cn-deploy.sh` 发的是 `:<sha>` tag，后发的覆盖先发的。发版后隔天复查一次 SAE ImageUrl：已从 digest 变回 tag 形态即为被老路径覆盖，需重跑云效 prod 流水线（2026-07-31 一天内见 3 例，`cn-deploy.sh` 下线前一直存在）
 - 用户请求发 cn-prod 时：确认已有 stage 验证过的 cn-v tag；没有则先引导走 stage
+- **已发过 prod 的服务**（2026-07-14 起，截至 2026-07-31）：`commerce-backend`、`optima-scout`、`optima-generation`、`optima-generation-worker`、`browser-backend`（最近一次 2026-07-30 browser-backend cn-v1.0.0 全绿）。**不在此列的一律当首发处理**：避开业务高峰、**触发之前**找 xbfool/svenyang 人工确认（没有卡点可以事后补，见上条）、发完立刻校验 ImageUrl
 
 ## 前置依赖
 
@@ -49,5 +51,5 @@ optima-cn-deploy <service> --env prod --vtag cn-v1.2.3    # prod 发版
 
 ## 边界
 
-- cn-prod 仅走 vtag 制（见上），且有人工卡点闸门；日常无 vtag 的构建只发 cn-stage。
+- cn-prod 仅走 vtag 制（见上）；**没有人工卡点闸门** —— 工具侧那道 vtag 校验（拒绝无 vtag / 裸 `v*` / 带 `--branch` 的 prod 请求）就是最后一道闸。日常无 vtag 的构建只发 cn-stage。
 - 服务注册表是 optima-terraform `alicloud/stacks/cn-prod-buildbox/yunxiao/` 的快照；新增服务先在那边 gen-pipelines 建好流水线，再同步本工具的 SERVICES 表。

package/.codex/skills/reset-onboarding/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: "reset-onboarding"
+description: "当用户请求重置某账号的 onboarding 资格、让账号重新体验新手引导/问卷、再触发一次 onboarding、重开引导运行（guided run）、重置 guided_run_grant 时，使用此技能。支持 cn-prod、cn-stage 两个环境；标识符支持手机号/邮箱/userId。"
+allowed-tools: ["Bash"]
+---
+
+# 重置 onboarding 资格（让账号重新触发新手引导问卷）
+
+让某账号「进入页面再次自动弹出 onboarding 问卷」。cn-prod 与 cn-stage 机制相同，只换环境参数与前端域名（cn-prod = `https://app.yzsgo.com`，cn-stage = `https://app.stage.optima.chat`）。
+
+## 门控机制（缺一不弹）
+
+前端 `useShowOnboardingTree`（agentic-chat）要求**全部**满足：
+
+1. 服务端资格：billing 库 `guided_run_grant` 判出 `sponsorshipAvailable === true`，公式 `(granted - used) > 0 && spent_credits < cap_credits`（cap 默认 2000）
+
+2. 有 userId
+3. **当前打开的会话无 user 消息**——开个新会话即满足，无需删旧会话
+4. 客户端浏览器 localStorage 无「已提交/已跳过」锁
+
+> ### ⏳ optima-gateway#1998 换档中——本文所有 SQL 有两版，按现网是否已建列选
+>
+> `optima-gateway#1998` 给 billing 加了两列装 **LLM 花费**：`guided_run_grant.spent_credits_llm`、`sponsored_window.window_spent_credits_llm`。**列建好之后**，cap 判据口径变成两列相加，本 skill 的 SQL 全部要跟着改，否则会看到 `spent_credits=0` 以为重置成功、而资格依旧开不出来。
+>
+> **先判断现网建列了没**（一条命令，两个环境各跑各的）：
+> ```bash
+> optima-query-db billing "SELECT COUNT(*) FROM information_schema.columns WHERE column_name='spent_credits_llm'" <env>
+> ```
+> - 返回 **0** → 用本文正文里的 SQL（当前状态，2026-08-07 两环境均为 0）
+> - 返回 **1** → 每条 SQL 都按其下方的「🆕 建列后版本」替换
+>
+> ⚠️ 列建好后 cap 默认值也会从 **2000** 换成 **8000**（配一条把存量 `cap_credits=2000` 抬上去的 migration）。**以查出来的 `cap_credits` 实际值为准**，别照记默认数。
+
+所以重置分**两层**：服务端 SQL（我方执行）+ 客户端 localStorage（只能操作浏览器的人自清）。
+
+## 执行步骤（服务端）
+
+全程用 `optima-query-db`，`<env>` 取 `cn-stage` / `cn-prod`，作为第 3 个位置参数（如 `optima-query-db billing "..." cn-stage`）。
+
+**凭证按 `query-db` skill 的方式准备即可，本技能不需要额外 `source` / `export`**：本机若有 `~/.infisical_cn_creds` 和 `~/.buildbox_pw`，工具会自己读取（`bin/helpers/db-utils.ts` 的 `loadCredsFileIntoEnv()` / `readBuildboxPwFile()`，文件不存在即无操作）；没有则从 1Password 取 `INFISICAL_CN_EMAIL`、`INFISICAL_CN_PASSWORD`、`OPTIMA_CN_BUILDBOX_PASSWORD` 三个值 `export` 到当前 session（推荐，不落盘）。缺哪个命令会自己报错并提示来源。
+
+**① 标识符 → uid，同时拿到可供人工核对的身份**（手机号/邮箱查 user-auth）。注意 cn-prod 与 cn-stage 是独立库，同一手机号两边 uid 不同：
+
+```bash
+optima-query-db user-auth "SELECT id, phone, email FROM users WHERE phone='<手机号>'" <env>
+```
+
+> **用户直接给了 uid 也不要跳过 ①**，改成按 uid 反查、把手机号/邮箱拿到手——②（`guided_run_grant`）的回显只有 `user_id`，自己证明不了自己是谁：
+>
+> ```bash
+> optima-query-db user-auth "SELECT id, phone, email FROM users WHERE id='<uid>'" <env>
+> ```
+
+**② 查 grant 现状**（确认目标账号，防止重置错人）：
+
+```bash
+optima-query-db billing "SELECT user_id, granted, used, cap_credits, spent_credits, updated_at FROM guided_run_grant WHERE user_id='<uid>'" <env>
+# 🆕 建列后版本：把选择列表换成 ..., spent_credits, spent_credits_llm, updated_at ...
+```
+
+> 回显里同时确认 `granted > 0`——若 `granted=0`，重置本身就是无效的（资格公式 `(granted-used)>0` 仍不成立），③ 的 `AND granted > 0` 会让 UPDATE 影响 0 行。若查不到行或 `granted=0`：该账号从未被授予引导资格，不属「重置」范畴——发放 grant 走 billing 侧逻辑，找 billing owner 确认。
+
+**③ 重置——`used` 和 `spent_credits` 都要清、缺一不可**（只清 `used`、若 `spent_credits` 已烧到 cap 则资格仍是 false）。
+> 🔴 **建列后要清三个**：`optima-gateway#1998` 的 `spent_credits_llm` **终身累计、无任何自动 reset 点**，而反复重跑的 QA/回归号正是最容易把它烧满的一批。漏清它 = 你会看到 `spent_credits=0` 以为成功、而资格依然开不出来——与上面这句告警一模一样，只是换了个列名。
+
+> 🔴 **跑这条 UPDATE 前必须完成的两条硬性前置**（写操作不可撤销，`cn-prod` 是生产库尤其如此；cn-stage 一样照做，别把下面两条当 cn-prod 专属）：
+>
+> 1. 已跑 ① 拿到该 uid 的手机号/邮箱，**并念给用户、拿到明确确认「就是这个账号」**——用户直接给 uid 时同样要做。
+> 2. 已跑 ② 看到该 uid 确有行且 `granted > 0`。
+>
+> 缺任何一条就停下来问，不要先跑 UPDATE。
+
+```bash
+optima-query-db billing "UPDATE guided_run_grant SET used=0, spent_credits=0, updated_at=now() WHERE user_id='<uid>' AND granted > 0 RETURNING user_id, granted, used, cap_credits, spent_credits" <env>
+# 🆕 建列后版本（缺了 spent_credits_llm=0 就等于没重置干净）：
+# optima-query-db billing "UPDATE guided_run_grant SET used=0, spent_credits=0, spent_credits_llm=0, updated_at=now() WHERE user_id='<uid>' AND granted > 0 RETURNING user_id, granted, used, cap_credits, spent_credits, spent_credits_llm" <env>
+```
+
+> `AND granted > 0` 是机械自保：打到从未被授予引导资格的账号时影响 0 行，而不是静默写一个无效重置。
+>
+> ⚠️ **护栏触发时回显是完全空白**——`optima-query-db` 走 `psql -t -A --quiet`，0 行既没有 tuple、也不会打 `UPDATE 0` 标签（实测输出长度为 0）。**空回显 = 重置没有发生，不是成功**：回到 ①/② 核对 uid 是否贴错，然后重新走前置，**绝不要把 `AND granted > 0` 去掉重跑**——那正好绕过这道自保。成功时一定有一行形如 `<uid>|1|0|2000|0` 的回显。
+>
+> **已知不足**：它挡不住「uid 打错、恰好打到另一个真有 grant 的账号」——那种情况唯一的防线是上面第 1 条的人工核对，没有第二道。本技能不包 CLI 反查确认（对比 `optima-account ban` 的 `🎯 目标账号` 回显 + `--yes`），要补属另一个 issue 的量级。
+
+**④ 复核 `sponsored_window`**：`CLOSED_*` 状态无需处理（下次进 onboarding 时 lazy-open 自动新开）；仅异常残留的 `OPEN` 窗需要关注——等 reaper 约 30 分钟自动收即可，别手动改它的 status（未验证过的写路径）。该表**无 `created_at` 列**，按 `opened_at` 排序：
+
+```bash
+optima-query-db billing "SELECT id, status, window_spent_credits, opened_at, closed_at FROM sponsored_window WHERE user_id='<uid>' ORDER BY opened_at DESC LIMIT 5" <env>
+```
+
+## 客户端一层（服务端做不了，转告操作浏览器的人）
+
+把 ① 查到的 uid 一并告知对方（拼下面的键名要用），然后：
+
+1. 清 localStorage 锁——在对应环境前端域名下删三个键（DevTools → Application → Local Storage），或直接用**无痕窗口/换浏览器**登录（天然无锁）：
+   - `onboarding_intake_submitted:<uid>`
+   - `onboarding_intake_dismissed:<uid>`
+   - `onboarding_intake_draft:<uid>`
+2. 登录后点「开始新对话」落到空会话，问卷即自动弹出。
+
+## 别白清的东西（不是 gate）
+
+- gateway 库 `user_configs.intake_dismissed`：「我是老手跳过整树」的持久化，不是"已体验过"标记。
+- agentic-chat 库 `onboarding_results` / `user_preferences.onboardingCompletedAt`：cn 环境无写入方，查了是空。
+
+## 安全提醒
+
+1. `cn-prod` 是生产库写操作，真正的护栏写在 **③ 正文的两条硬性前置**里（人工核对身份 + `granted > 0`），不在本节——别只扫这节就动手。
+2. 清 `spent_credits`（建列后还有 `spent_credits_llm`）**不会退回真实花费**——真扣费永久留在 `usage_records`（`metadata->>'actorUserId'` = uid）与 CLOSED 窗的 `window_spent_credits`，清零只是把 lifetime 计数器归零、重开满 cap 预算。
+3. onboarding 门控在高频演进（COO epic 等）：若按本流程重置后仍不弹，先对 agentic-chat `origin/main` 的 `useShowOnboardingTree` / `intakeLocal` 重验门控是否有变，再排查。
+
+## 相关命令
+
+- `optima-query-db` - 本技能全部查询/更新的载体
+- `optima-grant-credits` / `optima-grant-subscription` - 积分/订阅发放（与 onboarding 赞助额度是两回事）
+- `optima-account` - 账号状态查询

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