flower-trellis 0.4.0-beta.2 → 0.4.0-beta.4

package/README.md

@@ -52,6 +52,9 @@ flower-trellis init -u <your-name> -y
 # 升级 Trellis 并按新版本重新叠加强化包
 flower-trellis update
 
+# 交互管理通用技能,并查看工作流强化包
+flower-trellis skill
+
 # 卸载:移除 Trellis 本体并清理强化包残留
 flower-trellis uninstall
 
@@ -67,6 +70,7 @@ flower-trellis -v
 |------|------|
 | `init` | 安装 Trellis 并叠加强化包(默认命令,裸跑等同 `init`) |
 | `update` | 升级 Trellis,并按新版本重新叠加强化包 |
+| `skill` | 打开交互菜单:启用或停用通用技能,只读查看工作流强化包 |
 | `uninstall` | 移除 Trellis 本体并清理强化包残留(支持 `-y` / `--dry-run`) |
 | `<其它命令>` | 原样透传给 Trellis,覆盖其现有及未来子命令 |
 | `-v` / `-h` | 打印版本 / 帮助 |

package/enhancements/MANIFEST.json

@@ -1,7 +1,25 @@
 {
-  "syncedAt": "2026-06-30T00:30:48.425Z",
-  "syncedFrom": "vendor/skill-garden/.trellis",
-  "sourceCommit": "44b5b31a0c0346f4d615ad6f3f58af860cc3983d",
+  "syncedAt": "2026-07-01T04:27:03.524Z",
+  "syncedFrom": "vendor/skill-garden",
+  "sourceCommit": "7a9b882db76500b49b38cf423be682fb06effe1a",
+  "common": {
+    "codexSkills": [
+      "craft-rpa",
+      "craft-slides",
+      "humanize-writing",
+      "open-idea",
+      "sub2api-account-json-fix",
+      "torrent-analyze"
+    ],
+    "claudeSkills": [
+      "craft-rpa",
+      "craft-slides",
+      "humanize-writing",
+      "open-idea",
+      "sub2api-account-json-fix",
+      "torrent-analyze"
+    ]
+  },
   "variants": {
     "old": {
       "claudeSkills": [],

package/enhancements/common/.common/.claude/skills/craft-rpa/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: craft-rpa
+description: "录制真实浏览器流程为按会话保存的 JSONL,并转换成 RPA 改造参考用的 markdown trace。适用于录制浏览器流程、生成 RPA 流程参考、session.jsonl 转 trace、Dashboard 反向控浏览器、craft rpa、record browser flow；不用于 CI 测试、并行录制或反爬绕过。"
+---
+
+# Craft RPA
+
+> 自包含的"录制 → 多会话留档 → 机械翻译成 markdown 流程参考"端到端工具,服务于**人工/半自动 RPA 改造**(不是自动 e2e 测试)。
+> skill 内自带 `recorder/`(launch.js / logger.js / inject.js / dashboard.html)、`scripts/run.sh`(生命周期管理)、`scripts/jsonl-to-trace.js`(转换输出)。
+
+---
+
+## 适用场景
+
+- 录制业务流程作为 RPA / 自动化脚本的**改造素材**(UiPath / Power Automate / Selenium / Playwright)
+- 复盘第三方系统的真实交互(尤其严 CSP 站点,如 oracle.com)
+- 同一目标多次录制,每次会话独立留档,便于横向对照
+- 通过 Dashboard 在另一台机器上观察 + 控制 WSL/Linux 里的录制会话
+- 抓 SPA / 复杂前端应用的真实运行轨迹
+
+## 不适用场景
+
+- 无人值守的 CI 集成测试 → 用 Playwright test runner
+- 跨机器并行录制 / 集群压测
+- 反爬绕过 / 反检测自动化
+- 仅前端 lint / 单测 / spec 验证
+- 期望"录完就能跑"的自动重放 —— trace.md 是人/AI 改造素材,不是可执行脚本
+
+---
+
+## 前置条件
+
+- Node ≥ 18(LTS 推荐)
+- 系统装 Chrome(默认),或 `npx playwright install chromium` + 把 `recorder/launch.js` 里的 `USE_SYSTEM_CHROME` 改成 `false`
+- WSL2 必须有 WSLg(`echo $DISPLAY` 应非空)
+- 端口 `7777` 未被占用(否则改三处常量,见 Hard Constraints #2)
+
+---
+
+## 首次安装
+
+skill 推荐装到用户全局,任意仓库自动可用:
+
+```bash
+cp -r <source>/.claude/skills/craft-rpa ~/.claude/skills/
+# 首次 start 时 run.sh 会自动 npm install,无需手装
+```
+
+或每个仓库装一份:
+
+```bash
+cp -r <source>/.claude/skills/craft-rpa <repo>/.claude/skills/
+```
+
+后文 `$SKILL_DIR` 统一指 `~/.claude/skills/craft-rpa` 或 `<repo>/.claude/skills/craft-rpa`。
+
+---
+
+## 自动模式(AI 代跑)
+
+想让 AI 替你跑录制 / 停止 / 转换,**不要手 cd 进 recorder/**,改用脚本封装:
+
+```bash
+bash "$SKILL_DIR/scripts/run.sh" start [URL]      # 新会话目录 + 后台起;无 URL:TTY 下 prompt,非 TTY 直接 about:blank
+bash "$SKILL_DIR/scripts/run.sh" status           # 看是否在跑 + 当前会话 + 历史数 + Dashboard URL
+bash "$SKILL_DIR/scripts/run.sh" sessions         # 列所有历史会话(* 标当前)
+bash "$SKILL_DIR/scripts/run.sh" logs [N]         # tail 最近 N 行(默认 50)
+bash "$SKILL_DIR/scripts/run.sh" stop             # SIGINT 优雅停止,3s 未退再 SIGTERM
+bash "$SKILL_DIR/scripts/run.sh" craft [--session <ts>] [OUT]
+                                                   # 转 jsonl → trace.md;--session 默认 = 当前/最新;OUT 默认 ./trace.md
+```
+
+运行时状态 / sessions / profile 全部在 `$(pwd)/.craft-rpa/`(可用 `CRAFT_RPA_HOME` env 覆盖到任意路径)。首次 `start` 自动 `npm install`(跳浏览器下载,~10s)。
+
+**AI 行为约定**(看到下列触发就跑对应子命令,不要手敲底层 cd / nohup):
+
+| 用户说 | AI 跑 |
+|--------|-------|
+| "开始录" / "录浏览器 [URL]" / "start" | `run.sh start [URL]`,把返回的会话 ts + Dashboard URL 贴给用户 |
+| "停" / "结束录制" / "stop" | `run.sh stop`,贴出本会话事件数 |
+| "转换" / "生成参考" / "craft" | `run.sh craft`(输出 trace.md),贴出输出路径 + 行数 + 会话 ts |
+| "转上一次的" / "转 <ts>" | `run.sh craft --session <ts>` |
+| "看 log" / "看日志" | `run.sh logs` |
+| "在跑吗" / "status" / "看下当前" | `run.sh status` |
+| "列会话" / "看历史" | `run.sh sessions` |
+
+**AI 不要做**:
+
+- 浏览器窗口里的鼠标 / 键盘操作 —— 这是 GUI 部分,只能由用户本人完成
+- 修改 `recorder/` 里的代码 —— 它是 skill 独立资产(仅 `REDACT_SENSITIVE` 常量允许调)
+- 跳过 `run.sh` 直接 `nohup node launch.js` —— 会绕过会话目录管理和 PID 管理
+- 自己尝试合并语义步骤 / 命名 step / 删事件 —— 这是 AI 精修阶段的事(下一段),`craft` 输出已经包含全部原始信息
+
+---
+
+## 数据位置与多会话约定
+
+录制产物与运行时状态**写入项目根**(与 skill 代码解耦),默认 `<cwd>/.craft-rpa/`,可用环境变量 `CRAFT_RPA_HOME` 覆盖。
+
+```
+<repo>/.craft-rpa/              ← 项目根,建议仓库根 .gitignore 豁免整目录
+├── sessions/
+│   ├── 2026-05-18_10-30-00/   ← 每次 start 创建时间戳目录,不覆盖历史
+│   │   ├── session.jsonl
+│   │   └── trace.md           ← 可选,craft 输出可指定到此
+│   ├── 2026-05-18_14-22-15/
+│   └── legacy-2026-05-17_...   ← 老版本遗留 / 升级时自动归档
+├── profile/                    ← Chrome 持久 profile(登录态,项目独立)
+├── .launch.pid / .launch.log   ← 进程管理 + 日志
+└── .current-session            ← 最近一次 start 的会话 ts
+
+.claude/skills/craft-rpa/recorder/   ← skill 内仅代码资产;start 时建两个软链 → 数据根:
+├── session.jsonl → <repo>/.craft-rpa/sessions/<latest>/session.jsonl
+└── profile        → <repo>/.craft-rpa/profile
+```
+
+**为什么这样**:
+- 录制 jsonl 是**项目业务数据**,跟着仓库走(每个仓库独立 session 池,不串)
+- skill 代码可装 `~/.claude/skills/craft-rpa/` 全局,所有仓库共用同一份代码
+- launch.js / logger.js 用 `__dirname` 解析 session.jsonl / profile,通过 recorder/ 内软链自动落到项目根 —— **录制器代码不用改**
+
+**关键性质**:
+
+- 每次 `run.sh start` 创建新时间戳目录,**不覆盖**历史
+- `recorder/session.jsonl` / `recorder/profile` 始终是软链,随当前会话切换目标
+- 老版本遗留的 `recorder/session.jsonl`(普通文件)在新版第一次 start 时自动归档到 `sessions/legacy-<ts>/`;`recorder/profile/`(普通目录)归档到 `.craft-rpa/profile-legacy-<ts>/`
+- `run.sh craft` 默认转最新;`--session <ts>` 可转任意历史
+- 删历史:手动 `rm -rf .craft-rpa/sessions/<ts>/`,run.sh 不管删
+
+**`CRAFT_RPA_HOME` env 用法**:
+
+```bash
+# 默认:cwd 是 oracle-register 时,数据写在 oracle-register/.craft-rpa/
+cd <your-repo> && bash $SKILL_DIR/scripts/run.sh start
+
+# 想统一集中存(比如 home 下中央位置):
+export CRAFT_RPA_HOME=~/rpa-recordings
+bash $SKILL_DIR/scripts/run.sh start
+```
+
+---
+
+## AI 精修阶段做什么(关键)
+
+`jsonl-to-trace.js` 输出是**机械翻译,不删信息**:每个事件平铺一段,字段全保留。这意味着 trace.md 里没有"业务步骤"概念,只有原始事件。
+
+**AI 拿到 trace.md 后应该做的事**(用户没明说时也要主动做):
+
+1. **识别业务步骤**:把多条相邻事件合并成"用户在做一件事"
+   例:`input(email)` + `input(password)` + `click(登录)` + `network(POST /api/login → 200)` + `pageload(/dashboard)` = "Step 1 — 用户登录"
+2. **给步骤起业务命名**:基于元素 accessibleName / URL / 上下文推断(登录 / 下单 / 创建实例 / 退订),不要叫 "Step 1 — Click button"
+3. **标注噪音但不删原文**:对明显无业务意义的事件(高频 mousemove、纯 focus / blur、统计埋点 xhr)在产出里灰显或归类到"噪音观察"段,**但 trace.md 原文不动**
+
+   ⚠ **关键警示**:trace.md 速览表中 `[BUSINESS-IN-NOISE]` 标记的事件**永远不能当噪音过滤**——它们是被埋在 fingerprint frames 噪音段里的业务 click(典型场景:支付 modal 内的 Credit Card / Close 按钮,被前后大量 ThreatMetrix fingerprint frame 包围)。AI 看到此标记必须**反向验证**该 interaction 是否对应一个业务步骤,并在 rpa-draft.md 中显式覆盖。`[NOISE?]` 仅是参考标记不是真值,但 `[BUSINESS-IN-NOISE]` 是"已经发现的反例",优先级最高。
+4. **保留选择器全集**:RPA 改造时不同工具偏好不同选择器(UiPath 喜欢 ID,Selenium 偏 XPath,Playwright 喜欢 role+name),不要只挑一个
+5. **保留敏感字段原值**:RPA 流程通常需要固定填值,直接呈现,不要替换为占位
+6. **输出 RPA 改造草案**:推荐结构
+
+```markdown
+# RPA 流程草案 - <场景名>
+
+## 整体流程
+<3-5 句业务描述>
+
+## 关键步骤
+
+### Step 1 — <业务命名>
+- 触发: <用户什么动作>
+- 元素: <accessibleName> (selector: <最稳的两三个>)
+- 输入值: <如有>
+- 触发请求: <如有>
+- 完成判定: <pageload / 元素出现 / network status>
+
+### Step 2 — ...
+
+## 噪音观察(供改造时跳过)
+- 事件 #15-#18:鼠标 hover 触发 tooltip,无业务意义
+- 事件 #34:百度统计埋点,可忽略
+
+## RPA 工具适配建议
+- UiPath:用 attribute 选 testId / id
+- Power Automate:用 role+name
+- Selenium:用 XPath 兜底
+```
+
+7. **保留可追溯性**:每个 Step 标注覆盖的原始事件 # 区间,方便用户回查
+
+### 产物落盘约定
+
+| 项 | 约定 |
+|----|------|
+| **文件名** | `rpa-draft.md`(固定,不带场景名后缀;场景名写在文档标题里) |
+| **位置** | `$CRAFT_RPA_HOME/sessions/<ts>/rpa-draft.md`,与 `trace.md` 同目录,可追溯性最强 |
+| **触发关键词** | 用户说"精修" / "RPA 草案" / "改造草案" / "draft" / "进入精修阶段" / "输出草案" 时,AI 主动生成 |
+| **不落对话** | 草案体量通常数 KB ~ 数十 KB,写文件后只给用户:**路径 + 关键发现摘要(3-5 点)**,不在对话里贴正文 |
+| **重生成** | 重新精修同一会话 → 覆盖 `rpa-draft.md`(不加时间戳后缀,会话隔离已由父目录 `<ts>/` 完成) |
+| **跨会话对照** | 不合并 jsonl;由 AI 在精修时读多个 `sessions/<ts>/trace.md`,产出独立的"对照"草案(用户显式要求时) |
+
+---
+
+## RPA 实施模板(撞 → 修循环)
+
+> 本段沉淀自 `oracle-register` 等实战任务的撞坑经验:rpa-draft.md 给出的 selector 表 **绝不是 ground truth**,实施期默认会撞 2-3 次;不内置失败回路就只能盯眼看,几小时排错变成几分钟。
+
+### rpa-draft 不是 ground truth
+
+trace.md 是机械翻译;rpa-draft.md 是 AI 基于 trace 的**推断**——它没看过真实 DOM,只看到了选择器集合 + 文本 + 祖先链。对 react-select / 自定义 radio / 隐藏 checkbox 等第三方深度定制 SPA(典型:oracle.com / cybersource 支付),selector 表只能当 **first guess**:
+
+- 真实跑起来 `getByRole('option')` 找不到、`getByLabel(/X/)` 命中错的元素、提交按钮一直 disabled —— 都是预期内的
+- 默认会撞 2-3 次,撞了不是 rpa-draft 写错,是 selector 推断本质上的不确定性
+- 撞了**不要硬猜下一个选择器**——dump DOM 看真实结构,再回头改
+
+### 必备四件套
+
+实施 RPA 脚本时必须内置(任一缺失都让排错时长 ×5):
+
+1. **dumpFailure** —— 失败时落:
+   - `screenshot.png`(fullPage)
+   - `url.txt`(失败时的 URL,SPA 单 URL 时也要)
+   - `dom.html`(主 frame `page.content()`)
+   - `frame_N_<url>.html`(所有非主 frame 的 `f.content()`)—— iframe 支付 / 跨域 widget 唯一能看到真实 DOM 的方式
+   - `error.json`(step / message / stack)
+2. **Playwright tracing** —— `ctx.tracing.start({snapshots: true, sources: true})` / `ctx.tracing.stop({path: 'trace.zip'})`,失败后用 `npx playwright show-trace trace.zip` 回放可视化排查
+3. **Atomic status machine** —— `pending → running → succeeded / dead`;
+   - 退出 hook(SIGINT / SIGTERM / uncaughtException)把 `running` 回写 `pending` 避免账户被悬挂
+   - `accounts.json.tmp` + rename 原子写,避免半成品状态
+4. **noise / business hint 参考但自验** —— 看到 trace.md 里 `[BUSINESS-IN-NOISE]` 标记的 interaction 当作 **"必须验证是否漏点"的提示**,不直接信任 AI 的噪音过滤结论。被埋在 fingerprint frame 噪音里的支付按钮(Credit Card / Close)是这个标记的典型对象
+
+### 7 类 Playwright stubborn elements 速查
+
+撞 `Timeout` / `intercepts pointer events` / `not visible` / `outside of the viewport` / `getByRole 命中错元素` / Submit 永远 disabled / 等不到 URL 跳转 时,先对照 `<repo>/.trellis/spec/guides/playwright-stubborn-elements-guide.md` 的 7 类速查表 + Click 三层 actionability 跳过参考(.click → force:true → evaluate(el => el.click))。该 guide 含 oracle-register 实战的具体修法和 selector 优先级修订版。
+
+> 注:guide 路径以 `<repo>` 占位,因为 craft-rpa skill 可装到全局 home(`~/.claude/skills/`),而 spec 通常在具体项目仓库。
+
+### 何时升级 timing 应对
+
+实施期撞到下面任一现象,**立刻升级 timing 策略**,不要硬调 selector:
+
+- onBlur validation 不触发(Continue 按钮永远 disabled)→ 字段内 `pressSequentially(value, {delay: 80-150})` + `press('Tab')` 主动 blur,而非一次性 `fill()`
+- 后端风控 ban / step 间瞬时切换被检测 → step 间加 500-2000ms `humanPause` 随机停顿
+- 字段完全无鼠标移动被 fingerprint(很少需要)→ `page.mouse.move` 加少量随机轨迹
+
+不是所有 input 都要逐字符——**只在校验逻辑挂在 onBlur 或 Continue 一直 disabled 的字段**上加。
+
+### 已知限制(写进 SKILL.md 避免反复踩)
+
+- **Shadow DOM 内 outerHTML 提取**:浏览器 API 限制,跨 shadow root 拿不到,inject.js 的 `target.contextHTML` 字段在 shadow root 元素上会缺失;只能用 selectors / accessibleName 推断
+- **跨域 iframe 元素**:同源策略限制,inject.js 在跨域 iframe 内单独运行但无法跨域访问父 frame 上下文;`target.contextHTML` 在跨域 iframe 内取自当前 frame 上下文(不含父 frame)
+
+---
+
+## 工作流
+
+### Step 1: 启动录制
+
+```bash
+bash "$SKILL_DIR/scripts/run.sh" start https://target.com
+# 或
+bash "$SKILL_DIR/scripts/run.sh" start          # 起 about:blank
+```
+
+启动成功标志:
+
+- run.sh 返回 `[craft-rpa] started (pid=..., url=...)` + 会话 ts + Dashboard URL
+- 浏览器窗口弹出(每个新页面 Console 会打 `[inject] boot at <url>`)
+- `<cwd>/.craft-rpa/sessions/<ts>/session.jsonl` 已创建(空文件,等事件)
+
+### Step 2: 用 Dashboard 实时验证
+
+打开 `http://localhost:7777/dashboard`:
+
+- 顶部 4 计数器(int / net / nav / err)随你的操作上跳
+- 没数:`run.sh logs` 看 launch / logger 报错;最常见根因是 `7777` 端口被占
+
+**快捷键**:
+
+| 键 | 动作 |
+|----|------|
+| `T` | 切主题 |
+| `Space` | 暂停 / 恢复事件流 |
+| `Ctrl/⌘ + F` | 聚焦搜索 |
+| `Esc` | 关闭详情面板 |
+
+**反向控浏览器**(走 `logger.js` 的 `/control/*` 接口):
+
+- Dashboard 顶部 URL 栏输地址回车 → 当前 tab 打开;勾"新标签"则 newTab
+- 底部 tabs 区域可点切换 / 关闭 / 刷新 / 前进后退
+
+### Step 3: 录完停止
+
+```bash
+bash "$SKILL_DIR/scripts/run.sh" stop
+# 输出: [craft-rpa] stopped (session=2026-05-18_10-30-00, 187 events)
+```
+
+或直接关浏览器窗口(launch.js 自动检测 context.on('close') 关闭 logger,run.sh 的 PID 文件会留着但 status 会发现进程已死自动清掉)。
+
+### Step 4: 生成 RPA 流程参考(trace.md)
+
+```bash
+bash "$SKILL_DIR/scripts/run.sh" craft
+# 默认 --session=最新 → 写 ./trace.md
+```
+
+**trace.md 内容结构**:
+
+1. **头部元数据**:起止时间 / 时长 / 事件总数 / URL 覆盖 / kind.type 分布 / 超长 URL 截断统计
+2. **速览表**:每事件一行(`#/jsonl#/t+s/kind.type/简述/最稳selector/value 或 URL`),方便整体把握
+3. **事件详情**:每事件一段,字段全保留(target.selectors 全集 / accessibleName / state / boundingBox / 网络字段 / 祖先链 / formFields ...)
+
+**关键性质**:
+
+- 机械翻译,**不过滤任何事件**(信息零损失)
+- **不命名业务 step**(js 不知道业务语义,留给 AI 精修)
+- **不脱敏**(`recorder/inject.js` 已默认 `REDACT_SENSITIVE=false`,value 全是原值)
+- 超长 URL(>800 chars 默认)截断 + 标注 `jsonlLine: <N>` 反查;原文取法 `sed -n '<N>p' session.jsonl | jq .url`
+
+**AI 拿到 trace.md 后**:走"AI 精修阶段做什么"段的 7 步,输出 RPA 改造草案给用户。
+
+### Step 5: 转给 RPA 工具实施
+
+把 trace.md(原始素材) + AI 精修后的草案(产出) 给到 RPA 工程师,他们对照 selector 全集 + 输入值 + 网络断言 + 业务命名,在 UiPath / Power Automate / 自研 RPA 里搭出可视化流程。
+
+---
+
+## Hard Constraints(违反破坏核心功能)
+
+1. **`bypassCSP: true` 不能关** —— 否则严 CSP 站点(如 oracle.com)的 fetch 全部被拦,inject.js 一条事件都送不出。位置:`recorder/launch.js` 的 `launchOptions`
+2. **端口 `7777` 改动必须三处同步**:`recorder/logger.js` 默认端口 / `recorder/inject.js` 的 `LOGGER` 常量 / `recorder/dashboard.html` 的所有 `/control/*` fetch
+3. **`recorder/inject.js` 保持单文件 / 无依赖 / 不抛错到业务页面** —— Playwright `addInitScript({ path })` 注入约束;一旦抛错会污染目标站
+4. **HTML 注入点必须 `escapeHtml`** —— Dashboard 渲染的事件 target 来自任意目标站,XSS 高危。位置:`recorder/dashboard.html`
+5. **CORS 必须回显 `Origin` 不能用 `*`** —— `sendBeacon` + cookie 场景要求。位置:`recorder/logger.js`
+6. **敏感字段默认 NOT 脱敏(`REDACT_SENSITIVE = false`)** —— RPA 流程参考需要原值;`target.sensitive` 标记仍保留供人工识别。**唯独**当 trace.md 产物要外传或归档时,自行评估是否手动脱敏对应 value 行。要重新启用源头脱敏,改 `recorder/inject.js` 的 `REDACT_SENSITIVE = true`(整次会话内对所有命中字段生效)
+
+---
+
+## 排错快查
+
+| 症状 | 根因 | 修复 |
+|------|------|------|
+| 浏览器拉不起 / 找不到 display | WSL2 无 WSLg / Linux 无图形 | 升 Win11 自带 WSLg / 装 X server / 或改 `headless: true`(无 GUI 重放) |
+| `Executable doesn't exist at .../chrome-linux/chrome` | `USE_SYSTEM_CHROME=false` 但没装 Chromium | `npx playwright install chromium` 或把常量改回 `true` |
+| `channel 'chrome' is not installed` | `USE_SYSTEM_CHROME=true` 但系统没装 Chrome | `apt install google-chrome-stable` 或下载 Chromium |
+| 端口 `7777` 被占 | 其他进程占用 | 改 `recorder/logger.js` 默认端口 + `recorder/inject.js` 的 `LOGGER`;或 `startLogger({ port: 8888 })` |
+| Dashboard 一直 0 事件 | inject.js 没注入 / fetch 被拦 | `run.sh logs` 看有没有 `[inject] boot at ...`;确认 `bypassCSP` 没关 |
+| 跨源 iframe 内事件丢失 | 浏览器同源策略 | 已知限制,无解;改用顶层窗口操作 |
+| `run.sh start` 报"already running" 但你没跑 | `.launch.pid` 残留 | `rm .craft-rpa/.launch.pid` 后重试 |
+| `craft` 报"no session found" | sessions 目录空 / 没录过 | 先 `run.sh start` 录一段 |
+| trace.md 速览表表格错位 | 字段含 `|` 或换行未转义 | js 已转义,如仍有问题报具体 # 事件 |
+| 整页跳转后 sessionId 变了对不上 | 这是正常的 —— 每页注入是新会话(jsonl 内的 sessionId,与 run.sh 的会话 ts 是不同概念) | 分析时按 `url` 分组,不依赖 jsonl 内 sessionId 跨页对齐 |
+| 历史 sessions 太多占空间 | 手动清理 | `ls .craft-rpa/sessions/` 看,`rm -rf .craft-rpa/sessions/<ts>/` 删 |
+
+---
+
+## 反模式
+
+### 脚本生成 / 解读层面
+
+- 让 `jsonl-to-trace.js` 做语义合并 / step 命名 / 噪音判断 —— 这些需要业务上下文,js 不知道;**留给 AI 精修阶段**
+- 在转换器里默认过滤事件 —— 信息丢失不可逆;噪音判断由 AI 在精修阶段标注(但不删原文)
+- 用 `xpath` 作为首选 selector —— xpath 是兜底,DOM 一调全断;按 testId → role+name → id → name → ariaLabel → text 顺序找
+- 把多次 `run.sh start` 的事件混在一个 trace.md 里 —— 每会话独立,跨会话对照应该是 AI 在精修阶段做,不是合并 jsonl
+
+### 工具使用层面
+
+- 在 `recorder/inject.js` 引入 npm 依赖 —— `addInitScript` 注入约束,只能用浏览器原生 API
+- 把端口 / Dashboard 暴露公网 —— logger 监听 `0.0.0.0:7777` 且无鉴权,仅本地开发
+- 并行起多个 `launch.js` 共用同一 `.craft-rpa/profile/` —— Chrome 单实例锁,会启动失败或损坏 profile
+- 改了 `inject.js` 的 `LOGGER` 端口但没改 `logger.js` / `dashboard.html` —— 三处必须同步(Hard Constraints #2)
+- 录制时 `Ctrl+C` 强杀 launch.js —— 优先 `run.sh stop`,让 SIGINT 走完优雅关闭路径,profile 才能正确落盘
+- 把 `.craft-rpa/` 提交进 git —— 该目录全是业务数据 + 运行时,装 skill 到新仓库时在仓库根 `.gitignore` 加一行 `.craft-rpa/`
+
+### Skill 使用层面
+
+- 不要为"跑一次 launch.js"创建 trellis task —— 这是工具调用,不是工程任务
+- 不要把 `trace.md` 写回 `recorder/` —— recorder 只负责录制,产出应放消费方仓库或 `.craft-rpa/sessions/<ts>/`
+- skill 内 `recorder/` 是 skill 自带的独立资产,跟项目根的 oracle-register 代码无关 —— 改 skill 内的代码不会影响项目根,反之亦然(`REDACT_SENSITIVE` 切换属 skill 内本地配置)