网页重复操作录一遍以后自动跑

--- name: skill-forge slug: forge displayName: 网页重复操作录一遍以后自动跑 description: 每天在网页上重复点的活：录制一遍，以后一条命令自动跑完，还能封装成可安装的技能。自动探网页接口，能走接口的转纯后台更稳更快。适合运营、投放、数据搬运。触发词：重复操作自动化、录制网页操作、浏览器自动化、网页脚本。 display_name: 网页重复操作录一遍以后自动跑 display_name_en: Web Task Recorder description_zh: 把网页上重复操作录一遍，变成可复用的自动化技能；能探到接口就转纯后台跑。 description_en: Record repetitive web tasks once and replay them automatically. examples_zh: - "这个网页操作每天都要做帮我录下来" - "把这个流程变成自动化脚本" - "录一遍以后帮我自动跑" examples_en: - "Record this daily web chore" - "Turn this flow into a script" - "Record once, run it for me daily" version: 2.2.0 build: "20261114160000" updated: "2026-11-14" author: "yysws5566" source: "独立原创（无第三方代码、无外部素材）" license: "MIT（思路借鉴来源见 references/合规与法律边界.md 附录 A）" risk-level: "🟡 中等（WARNING）：读取你已登录浏览器里的后台数据、可操作生产后台；默认只读，写操作必须先问人" allowed-tools: - terminal - read_file - write_file - clarify permissions: terminal: commands: - "node <技能目录>/scripts/record.mjs" - "node <技能目录>/scripts/evidence.mjs" - "node <技能目录>/scripts/probe.mjs" - "node <技能目录>/scripts/diffrec.mjs" - "node <技能目录>/scripts/infer_params.mjs" - "node <技能目录>/scripts/interview.mjs" - "node <技能目录>/scripts/build_skill.mjs" - "node <技能目录>/scripts/api_run.mjs" - "node <技能目录>/scripts/run.mjs" - "node <技能目录>/scripts/login.mjs" - "node <技能目录>/scripts/manage.mjs" - "node <技能目录>/scripts/diagnose.mjs" - "python <技能目录>/scripts/localview.py" - "python <技能目录>/scripts/analyze.py" - "python <技能目录>/scripts/pack_check.py" - "powershell -NoProfile -ExecutionPolicy Bypass -Command <固定模板：只按调试端口关本技能自己开的 Chrome，不跑别的命令>" scripts-whitelist: [analyze.py, localview.py, pack_check.py] node-scripts-whitelist: [record.mjs, evidence.mjs, probe.mjs, diffrec.mjs, infer_params.mjs, interview.mjs, build_skill.mjs, api_run.mjs, run.mjs, login.mjs, manage.mjs, diagnose.mjs] scope: "python 只跑本技能 scripts/ 下 3 个脚本；node 只跑本技能 scripts/ 下 12 个脚本（都按文件名匹配，改名即失效）；powershell 只有一条固定模板（按端口关自己开的浏览器），不接收任意命令拼接" why: "录制、探查、判参、问需求、生成子包、跑子包、看下载文件都要调本地脚本；powershell 仅一条固定模板——按 remote-debugging-port=<端口> 关掉本技能自己开的那台 Chrome，不接收任意命令拼接、不跑别的命令" log: "logs/失败台账.log（只记链路名、退出码、归因码，不记入参里的业务数据）" audit: "logs/写操作确认.log 为追加写（append-only），每次写接口执行前记 时间/方法/URL/--ack 原文；由使用者保管，供事后审计；技能自身不删除、不上传该文件" network: 无外网（脚本不连任何外部域名；只开本机回环 127.0.0.1 的 CDP 调试口与本机浏览器农场总管口，见 local-cdp） local-cdp: hosts: [127.0.0.1, localhost, "::1"] ports: [18802, 18899, 9300, "9331-9399"] ports-note: "只走本机回环；18802 工厂默认调试口、18899 登录测试临时口（18801-18899 内只开自己登记的那个）；9300/9331-9399=本机浏览器农场（browser-farm）——9300 总管只读档位表+写前快照，9331+ 档位调试口只连不关（档位归农场管）" endpoints: - "GET http://127.0.0.1:<port>/json/version" - "GET http://127.0.0.1:<port>/json/list" - "PUT http://127.0.0.1:<port>/json/new?<url>" - "WS ws://127.0.0.1:<port>/devtools/page/<id>" - "GET http://127.0.0.1:9300/health" - "GET http://127.0.0.1:9300/slots" - "POST http://127.0.0.1:9300/slot/<id>/snapshot" degrade: "调试口连不上就提示先手动启动 Chrome 加 --remote-debugging-port；农场口（9300）连不上=农场没跑，按非农场流程照常工作；业务站点本身不可访问则让用户自己贴数据，不编造" why: "只通过 CDP 控制本机 Chrome；业务站点流量由你已登录的 Chrome 发起，脚本本身不直连外网、不上传任何数据；连农场只为识别档位（收尾不误杀常驻登录档）和写前快照（回滚保险）" read_file: paths: - "<技能目录>/recordings · evidence · produced · references · templates · scripts · assets" - "<用户显式指定的源表 / 录制文件 / 下载目录>" why: "读录制产物做 diff 与证据；读用户给的源表做列映射；localview 读用户下载的文件" write_file: paths: - "<技能目录>/recordings · evidence · produced · zip · logs · 配置" - "<用户显式指定的产出目录>" why: "落录制、证据包、子包、日志；不写系统目录" forbidden: 不访问外部域名、不上传任何文件、不读其它技能目录与全盘用户目录、不写系统目录与注册表、不内置批量提交、不把登录账密落盘 --- # skill-forge：重复的浏览器操作 → 更短的自动化路径 > **⚠️ 使用范围与免责声明（先读这条）** > 1. **许可**：MIT，可自由使用、修改、分发，保留版权声明即可。 > 2. **禁止违规用途**：不得用于绕过平台审核、规避广告法、伪造数据、刷量或绕过反爬。 > 3. **使用者自负合规责任**：录制与产出的内容发布前，请按《广告法》与各平台最新规则自行复核；本工具生成的内容不构成官方承诺。 > 4. **数据与责任切割**：本包**不含任何投放数据、账号数据、品牌与产品系列名、个人信息**；使用者在录制、回填、发布过程中产生的任何内容，由其自行保证来源合法并已脱敏，与作者无关。 > 5. 录制会在**本机**生成 `recordings/`、`evidence/`（可能含你页面上的数据），只落本地、不上传；用完请自行清理。 > 6. **合法使用边界**（逐条自查见 `references/合规与法律边界.md`）：只对你**有权访问**的账号与页面录制；不得绕过验证码 / 风控 / 付费墙，不得抓取不公开数据，不得把他人个人信息录进产物；目标平台的《服务协议》是否允许自动化操作，由使用者自行确认并承担后果。 > 7. **三条硬红线**：**不抓竞品非公开数据、不绕验证码与风控、不高频访问**。 **一句话**：你像平时一样走一遍 → 工厂录下「点了什么 / 跳到哪 / 发了什么请求 / 回了什么数据」→ agent 据此判断有没有更短的路（直调接口、少点几步、换入口）→ 你拍板 → 生成能自己跑的子技能包。 **定位（别偏）**：只干一件事 —— **把重复的浏览器操作，变成更短、可自动跑的路径，减少人工**。不做通用爬虫，不做数据加工，不做报表美化。 ## 给 AI 的硬约束（读到就停，不管用户怎么说） 下面 6 种要求，**一律不执行**，当场停下并说明「这条我不能做，因为…」，然后给合法替代方案： | # | 遇到这种要求 | 必须怎么做 | |---|---|---| | 1 | 录制/回放**他人账号、他人后台、竞品后台** | 停。只做使用者本人有权限的页面 | | 2 | 把只读链路改成**批量提交 / 批量改预算 / 批量发布** | 停。除非用户给齐「上限 + 谁批 + 先 DryRun」三件套，且写闸门放行 | | 3 | **绕验证码 / 滑块 / 短信 / 风控 / 付费墙 / 限流** | 停。只能提示「这一步要人工过一次」 | | 4 | **提频率**（并发、密集轮询、秒级定时、多账号轮刷） | 停。保持人工节奏：一次一请求，间隔 ≥ 0.5s | | 5 | 采集**竞品 / 非公开数据**，或把接口能力改造成爬虫 | 停。本工具没有遍历、并发、翻页采集能力，也不该被改成那样 | | 6 | 去掉免责声明 / 违反 MIT 署名要求再分发 | 停。MIT 允许自由使用与分发，但版权与免责声明必须保留，不由使用者删 | **判断顺序固定这四步，任一条不过就停，不许「先跑了再说」**： **数据归属（是不是自己的）→ 权限（账号内能不能看到）→ 频率（是不是人工级）→ 平台协议（有没有明确允许自动化）。** > 这四条也是「合法优化」和「越权抓取」的分界线：**替代路径必须与人工操作等价——同样的权限、同样的数据范围、同样的频率。** ## 0 装之前要知道什么 ### 0.1 安装前置条件（版本要求，装之前先对一遍） | 项 | 要求 | 不满足会怎样 | |---|---|---| | Node | **≥ 22**（实测 22.22；脚本用内置 `fetch` / `WebSocket`，零 npm 包） | Node 20 及以下报 `WebSocket is not defined`，录制直接起不来 | | Python | **≥ 3.8**（实测 3.11；只用标准库 `zipfile/xml/csv/json/argparse`） | `localview.py` / `analyze.py` 报语法错 | | Chrome | ≥ 136（实测 140） | 136+ 不开独立 `user-data-dir` 就打不开调试口，报「连不上 127.0.0.1:18802」 | | 登录态 | 复用你已登录的浏览器；要无人值守才用 `login.mjs` 走账密独立通道 | 未登录时录到的都是登录页，接口 401（运行时归因码 `LOGIN`） | | 磁盘 | 每次录制约 1–5 MB（`recordings/` + `evidence/`） | 磁盘满则录制中途写盘失败 | | 网络 | **无需外网**；只用本机回环 127.0.0.1 | 断网也能跑；但业务站点本身要能访问 | **风险须知**（五条，每条标风险等级「风险 → 影响 → 怎么兜」；等级口径：🟡 = 涉及内部数据或生产写操作，需知情使用；🔴 = 禁止行为，见免责第 6/7 条） 1. 🟡 **会读你已登录后台的数据** → 页面数据可能含投放/账号信息 → 默认只读；产物只落本机，不上传；用完自行清理。 2. 🟡 **会开独立调试 Chrome** → 不抢你正在用的窗口，但会多一个进程 → 跑完自动按端口关掉；`--keep-open` 才留着。 3. 🟡 **能生成写操作的子包**（加预算/提交/发布）→ 误跑会改生产数据 → 写操作必须问「上限 + 谁批 + 先 DryRun」，没写上限只标「待确认」。 4. 🟡 **登录密码** → 泄露风险 → 只在内存里用一次，不落盘、不进日志、不进子包。**不要把账密写进环境变量、`.env`、脚本参数或配置文件**——那三类都会留痕；要无人值守就用 `SF_USER`/`SF_PASS` 当次会话传入（用完关终端），别写进任何文件。 5. 🟡 **会记录你「复制」的页面文本**（最多 8000 字，含表格区域）→ 这是「复制表格→粘贴到别处」这类链路的必需数据，但复制内容可能带账号/金额/客户名 → 加 `--no-copy-text` 只记行数/列数/字数、不留原文；`recordings/*.rec.json` 的 `meta.copyText` 会标明本次是 recorded 还是 redacted。 **部署前人工审批**：① 我知道它会读什么（哪个后台的登录态）；② 我同意它只连 127.0.0.1 的调试口，不连外网；③ 那个浏览器/账号是我自己的。**任一不确定就别装**，改用只读模式（只做录制与证据包，不生成可执行子包）。 **人工审批建议（有流程、有记录，别口头一句「你跑吧」）** | 环节 | 谁 | 记在哪 | |---|---|---| | ① 授权范围 | 使用者 + 有权限批准的人（主管/账号管理员） | 审批单/邮件：允许访问哪个后台、哪个账号、只读还是含写 | | ② 写操作批准 | 数值/预算类由业务负责人批 | `--ack "上限=…｜批准=…"`，自动写进 `logs/写操作确认.log` | | ③ 上线记录 | 使用者 | 功能台账一行：链路名、版本、MD5、批准人、日期 | | ④ 事后复盘 | 使用者 | 失败/自愈记录：`logs/失败台账.log`、`logs/自愈.log` | > 四种记录凑齐，才算「知情 + 授权 + 可追溯」。缺哪一条，出事后都解释不清。 **运行前二次确认（已落成代码，不是口头承诺）** - **读接口**（GET/HEAD/OPTIONS）：直接跑，不拦。 - **写接口**（POST/PUT/PATCH/DELETE）：三道关，缺一条就拒跑 —— ① 默认 `--dry`：只打印将要发的 URL 和 BODY，不发请求； ② `--allow-write`：声明「我知道这是写接口」； ③ `--ack "上限=…｜批准=…"`：说清「改多少、谁批的」，缺或写不清 → `exit 5`，不执行； 通过后确认原文写进 `logs/写操作确认.log`，出事能查。 - **AI 侧**：「给 AI 的硬约束」第 2 条要求集齐「上限 + 谁批 + 先 DryRun」，否则不许把只读链路改成批量写。 **首次使用要你一句确认**：AI 第一次跑之前，必须把上面 5 条风险念给你听，等你明确回一句「知道风险，继续」才开工；你没确认，它只能做只读录制与证据包。 ### 0.3 工具权限与调用位置（评审要的「用途证据」） | 工具 | 用在哪 | 边界 | |---|---|---| | `terminal` | 跑本技能 15 个脚本（node / python）+ 一条固定 powershell | 按文件名白名单匹配；不跑 `-c`/任意命令；powershell 只按端口关自己开的浏览器 | | `read_file` | 读录制产物、你给的源表、你下载的文件 | 只读技能目录与用户显式指定的路径 | | `write_file` | 落录制、证据、子包、日志 | 只写技能目录与用户指定产出目录；不写系统目录 | | `clarify` | 第 ④ 步问需求、写操作前确认 | 只问不替用户答；答不上来记「待确认」 | | `network`（**不声明工具**） | 无 | 脚本不直连外网；仅本机 CDP 回环，故 `allowed-tools` 里不列 `network` | **为什么必须读登录态、必须能生成写操作子包（必要性说明）** | 能力 | 为什么非它不可 | 少了会怎样 | 边界 | |---|---|---|---| | 读登录态页面 | 「录制」本身就等于用你的身份走一遍流程：没有登录态，录到的全是登录页，接口返回 401，整个工具没有输入 | 工具只剩空壳 | 只读**你当次打开的那个页面**；不遍历、不后台翻页、不落密码 | | 生成写操作子包 | 很多重复工作本身就是「写」（提交报备、加预算、发内容）。只做只读，等于只覆盖一半场景 | 一半的重复劳动还得手动做 | 默认 `--dry`；`--allow-write` + `--ack` 双确认；确认原文写 `logs/写操作确认.log` | | 调 CDP 调试口 | Chrome 只对 `--remote-debugging-port` 开放自动化接口，没有别的官方通道 | 无法驱动任何浏览器 | 只连 `127.0.0.1`；跑完按端口关掉自己那台 | > 一句话：**这三项是「录制→分析→回放」这条主链的技术前提，不是顺手多拿的权限。** 每一项都有对应的收口（只读默认 / 写操作双确认 / 本地回环）。 **`terminal` 到底能跑什么（逐条，可核验）** - ✅ 只跑**包内脚本**：`node scripts/xxx.mjs`（12 个）、`python scripts/xxx.py`（3 个）；参数只走 `--key value`，不接受命令字符串。 - ✅ 只跑**一条固定 powershell**：按 `remote-debugging-port=<端口>` 精确关掉自己开的那台 Chrome（不按进程名全杀）。 - ❌ **不执行任意用户命令**：全库无 `eval` / `new Function`；子进程调用只有两处——关浏览器（端口号来自 CLI 参数，模板写死）和跑同包的 `diffrec.mjs`（`process.execPath`），没有任何一条会把用户输入拼成命令交给 shell。 - ❌ 不 `curl` / 不 `wget` / 不装包 / 不改系统设置 / 不碰注册表。 > 复核方式：`grep -rn "child_process\|eval(" scripts/` 只应命中 `lib-cdp.mjs`（关浏览器）与 `record.mjs`（跑同包 diffrec）。 **`scripts/` 允许执行的脚本清单（共 15 个，逐个列，白名单之外一律不跑）** | # | 脚本 | 作用 | |---|---|---| | 1 | `record.mjs` | 起独立 Chrome + 注入浮标，录点击/跳转/接口/备注（多标签整链录） | | 2 | `evidence.mjs` | 录制 → 证据包（时间线 + 接口候选打分） | | 3 | `probe.mjs` | 探查接口（构造请求、看响应、出配置草稿） | | 4 | `diffrec.mjs` | 两遍录制对比，判出真正的变量 | | 5 | `infer_params.mjs` | 单遍录制判参（提示，不是定论） | | 6 | `interview.mjs` | 录完问需求（什么时候跑/参数哪来/给谁），写 `触发.json` | | 7 | `build_skill.mjs` | 生成子技能包（接口版 / UI 版 + 说明书） | | 8 | `run.mjs` | 回放子包（默认预览，`--go` 才真跑） | | 9 | `api_run.mjs` | 直调接口（写方法要 `--allow-write` + `--ack`） | | 10 | `login.mjs` | 独立登录通道（账密只进内存，不落盘） | | 11 | `manage.mjs` | 子包台账：列表 / 误点剔除 / 清理 / 失败归因 / 自愈记录 | | 12 | `diagnose.mjs` | 失败归因（9 条规则，出人话结论） | | 13 | `analyze.py` | 解析录制的 XML/JSON，出结构 | | 14 | `localview.py` | 零依赖读 xlsx/csv（看下载的表格） | | 15 | `pack_check.py` | 出包验收（语法/脱敏/死文件/无运行产物） | > 另有 `scripts/lib-*.mjs`（`lib-cdp` / `lib-diagnose` / `lib-heal` / `lib-infer` / `lib-manual` / `lib-tableread` / `lib-trigger` / `lib-guard` / `lib-zip` / `lib-farm`）为内部模块，只被上面 15 个脚本 import，不单独执行。 ### 0.4 依赖与供应链 > **结论先说：零外部 npm / pip 包依赖。** 全部脚本只用 Node.js 内置模块（`fs`/`path`/`http`/`crypto`/`zlib`/`child_process`）与 Python 标准库（`zipfile`/`xml.etree`/`csv`/`json`/`argparse`/`hashlib`）；包里**没有** `package.json`、**没有** `requirements.txt`、**没有** `node_modules/`、**没有**外网下载步骤、**没有**镜像源配置。供应链攻击面 = 0。 | 依赖 | 必需? | 版本 | 用途 | 来源 | |---|---|---|---|---| | Node.js | 必需 | **≥ 22**（实测 22.22） | 全部 `.mjs` 脚本（CDP、录制、生成子包） | 官网或包管理器安装 | | npm 第三方包 | **无** | — | `scripts/` 下没有任何 `require` / 包导入，全用内置模块 | — | | Python | 可选（只 UI 版映射、出包自检、看下载文件） | ≥ 3.8（实测 3.11） | `analyze.py` / `pack_check.py` / `localview.py` | 系统或包管理器安装 | | pip 第三方包 | **无** | — | 只用标准库（`zipfile`、`xml.etree`、`csv`、`json`、`argparse`、`hashlib`、`subprocess`） | — | | Chrome | 必需 | ≥ 136（实测 140） | 被 CDP 驱动的浏览器 | 本机安装 | | 装完 30 秒自检 | — | — | `node -v`（须 ≥22）→ `node scripts/manage.mjs list` → `python scripts/pack_check.py --help` | — | **供应链控制**：零第三方包（无 npm/pip 安装，无镜像依赖）；Chrome 用本机已装的；脚本全部随包分发、可逐行审阅；没有外网下载步骤。 **代码来源**：独立实现，**未复制任何外部代码/注释/文案/界面**；思路借鉴的公开来源逐条列在 `references/合规与法律边界.md` 附录 A（仅说明来源，不构成合作或背书）。 ### 0.4.1 数据管理（使用中必须守的 5 条） > 这一节讲的是「跑起来之后，数据怎么不出事」。技能会读登录态页面，产物可能含业务敏感信息，**这部分责任在使用者**。 | # | 规则 | 具体怎么做 | |---|---|---| | 1 | **产物默认视为敏感** | `recordings/*.rec.json`、`evidence/*` 里可能有投放数据、账号名、订单号；**当敏感资料管理**，不进聊天群、不进个人网盘、不发外部 | | 2 | **不长期留** | 一次任务做完就清：`rm -rf recordings/<链路名>* evidence/<链路名>*`；要复用得留，就归档并标有效期（默认 7 天，`manage.mjs clean --days 7` 清超期产物） | | 3 | **要留就加密** | Windows 用 BitLocker / EFS，或打包加密：`7z a -p -mhe=on 链路包.7z evidence\ recordings\`；**密码不进同一目录、不进聊天记录** | | 4 | **换人/换机先清** | 转岗、借电脑、重装前跑一次 `manage.mjs clean --all --yes`（不可恢复，所以要 `--yes` 再确认一次），别把带数据的目录留在别人机器上 | | 5 | **出包必过门禁** | 上传/外发只发 `pack_check.py` 出的 zip（包内不含 recordings / evidence / logs / 真实台账）；手工打包必然带数据，**不要手工打** | ### 0.5 安装前确认清单（人工逐项打勾，缺一项别装） > 这不是免责声明，是**你自己要能回答**的问题。答不上来的那一项，就是还没准备好。 | # | 必须确认的事 | 怎么确认 | 不确认的后果 | |---|---|---|---| | 1 | **数据读取范围**：允许它读哪个后台、哪个账号的登录态 | 写下后台名 + 账号（如「<后台名>·账户 A001」） | 读到你没授权的数据，责任在你 | | 2 | **子包写操作**：是否允许生成「会改生产数据」的子包？上限多少、谁批 | 写下「允许/禁止」「上限=…」「批准人=…」 | 误跑改预算/提交，事后无法解释 | | 3 | **合规自查 4 问**：数据归属 / 权限 / 频率 / 平台协议 | 逐条答「是/否」，有「否」就停 | 从「优化」滑向「越权获取」 | | 4 | **连接范围**：只连本机 127.0.0.1 的调试口，不连外网 | 看 `allowed-tools` 里没有 `network` 工具 | ——（本技能已固化，仅供核对） | | 5 | **产物落点**：`recordings/`、`evidence/` 落在哪台机、谁负责清 | 写目录 + 清理责任人 + 清理周期 | 页面数据长期躺在磁盘上 | | 6 | **平台协议**：目标后台的《服务协议》是否允许自动化访问 | 查协议或问平台对接人；不确定就只做「证据包」不做回放 | 账号被限权/封禁 | | 7 | **免责 7 条已读**：特别是第 6（合法使用边界）、第 7（三条硬红线） | 本文件开头，一眼可见 | 出了事没有「我已尽责」的证据链 | | 8 | **写操作话术已备**：`--ack "上限=…｜批准=…"` 由谁填 | 提前跟批准人约好 | 到现场随口编，等于没确认 | **8 项全打勾 → 可以装。任一没答上来 → 先别装**，或退一步只用「只读模式」（只录制 + 出证据包，不生成可执行子包）。 ## 四步（第 ④ 步问需求不能跳：不问 = 产物只是「重复路径」，不是自动化） | 步 | 命令 | 产出 | |---|---|---| | ① 录 | `node scripts/record.mjs --url <起始页，可 about:blank> --name <链路名> [--port 18802]`<br>页面右上角自动出现**浮标**：状态（录制中/已暂停）+ 实时计数 + 操作流水 + **「说一句」备注框** + 暂停 / 结束按钮 | `recordings/*.rec.json`：点击 6 级定位 + **元素快照（outerHTML 前 300 字 + tag/role/name）** + 跳转 + XHR/Fetch 的 URL/入参/状态/耗时/响应字段/行数 + **口述备注 notes** | | ② 证 + 探 | `node scripts/evidence.mjs --recording X.rec.json`<br>`node scripts/probe.mjs --recording X.rec.json --index N [--minimize]` | `证据包.md/html`（时间线 + 接口候选打分）<br>`探查报告.md` + `接口配置草稿.json` | | ②.5 判参 | **首选**：同一操作再录一遍，`node scripts/diffrec.mjs --a 第二遍.rec.json --b 第一遍.rec.json`（`record.mjs` 发现同名上一份录制会**自动**跑这步；录完也会自动按端口关浏览器）<br>**只有一遍时**：`node scripts/infer_params.mjs --rec X.rec.json [--out 参数判定.csv]` 先出变量提示（日期/单号/金额/接口带出的值）——**是提示，不是定论**，关键链路仍要两遍 diff | `evidence/diff_*/对比报告.md` + `参数判定.json`<br>`参数判定.csv`（单遍提示） | | ④ 问 | `node scripts/interview.mjs --link <名> [--rec X.rec.json] [--type api\|ui]`<br>人在场就一条条问；agent 已问过就用 `--answers answers.json`；**录制时浮标里说的原话会自动带出来**，不用再问一遍<br>问：什么时候跑（cron/阈值/手动/一次性）· 参数哪来 · **产出形态（本地文件/在线表格/接口回填/页面回读/只给人看，可多选）** · 给谁 · 怎么算成功 · 失败找谁 · 写操作上限<br>**答不上来不拦你**：记成「待确认」写进子技能，回头补；要强制问全再加 `--strict` | `配置/触发.json` + 打印「## 什么时候跑」段（欠什么也一起列出来） | | ⑤ 固 | `node scripts/build_skill.mjs --link <名> --config <探查目录> --type api --verdict-from <参数判定.json> --require-trigger`<br>或 `--type ui` | `produced/<链路>/` 自包含包（SKILL.md 已含「什么时候跑」）+ **`说明书.md`（人看的：干什么/何时跑/给什么/怎么算成功/改版怎么办）** + `zip/` + 台账一行 | > 录制可 `--url about:blank` 起步，用户自己粘地址。同 tab 整页跳转靠重注入，新开 tab 靠 `followNewTab()`（只跟 http(s)）。 > **开工先查站点经验**：在 `references/` 里找 `site-<host>.md`，有先读；真跑通后回写 3–5 条（入口/登录/数据从哪来/坑/校验），只写验证过的。 ## 本机有浏览器农场（browser-farm）时：直接挂档位，登录态白捡 农场每账号一个常驻 Chrome 档（固定调试口，总管 9300）。本机装了农场，录制/回放**优先挂档位跑**，不用另开浏览器重新登录： 1. `GET http://127.0.0.1:9300/slots` 找目标账号的档（`note` 是账号名），拿它的 `port`；档死了先 `POST /slot/ID/start`。**录制要在看得见的窗口里点**：先把档切有窗（`POST /slot/ID/start {"mode":"headful"}`）。 2. forge 全部脚本照常加 `--port <档位口>`：`record.mjs` / `api_run.mjs` / `run.mjs` 都行——`ensureChrome` 发现端口活着就直接挂上，不再另开 Chrome。 3. **收尾自动识别**：档位口是农场的，收尾**不关浏览器**（关了毁「登录一次永久保持」），打 `[农场] port=… 是常驻档…不关`；识别失败按非农场照旧关（宁可误关可重起，不误留）。农场总管口可用 `SF_FARM_PORT` 覆盖（默认 9300）。 4. **写接口加一道回滚保险**：`api_run --allow-write` 跑在农场档位上时，发请求前先自动打整档快照（`POST /slot/ID/snapshot`，名「写前快照…」），出事整档回滚；快照打不上默认不写（exit 4），确认不需要回滚加 `--no-snap`。 5. **触发.json 的「什么时候跑」由农场兑现**：UI 版 `build_skill` 对纯点击链路顺手产 `农场脚本.json`（多级定位直译成 farm 的 `locs`，farm v0.1.22 起认）——交农场 `POST /script/new` 就变成挂机脚本，登录态/自动开页/重连全归农场管。链路里有填值/粘贴步就不出（农场只会点，半截脚本会点错），打日志说明。 ## 判据：走接口还是走 UI | 探查结果 | 结论 | 下一步 | |---|---|---| | 2xx + 字段对得上 + 行数 > 0 | **能接口化** | `--type api` | | 2xx 但没数据 / 字段空 | 接口在，但不是这条数据 | 换参数再探；仍不行走 UI | | 401 / 403 | 需要额外鉴权 | 写清缺什么（token？单点登录？），别猜 | | 录制里根本没有 XHR | 只能 UI | `--type ui`（见 `references/UI版-表格搬运.md`） | 候选打分：2xx +2｜有返回字段 +3｜有行数 +3｜含 date/page 参数 +2｜URL 像取数 +1｜静态资源 −4。**≥6 分才值得探。** ## 四条防「静默少数据」的硬规矩（都已落成代码） 1. **请求体模板替换**：模板必须来自录制原文，只换 `{{变量}}`；拿不到原文模板 → `build_skill` 拒绝生成。 2. **字段数校验**：`校验.fieldCount` = 探查到的响应字段数；`api_run` 对不上就非 0 退出（`--allow-fields` 才放行）。 3. **独立账密通道**：`login.mjs` 开专属 `user-data-dir` 登一次，之后 `api_run --profile … --bg` 脱人跑；密码只从 `SF_USER`/`SF_PASS` 读，不落盘。 4. **按域名建站点经验库**：`references/site-<host>.md`；一站点一份，别重复踩坑。 ## 六条「少踩坑」的机制（都已落成代码 + 有断言） | 机制 | 解决什么 | 怎么用 | 边界 | |---|---|---|---| | **失败自愈** | 网站小改版（换个 class、多包一层）→ 以前直接报错要整条重录 | 回放时按 `best定位 → L1_id → L2_testid → L3_role → L4_text → L5_css → L6_nth_path` 逐级重试；命中打印 `[自愈] 第N步：用 L4_text 点到` | 默认**只报告不动库**；加 `--heal` 才把新定位回写 `定位库.csv` 并记 `配置/自愈记录.csv`、`logs/自愈.log`。六级别全找不到才算真改版 | | **元素快照** | 改版后没人记得「当时那个按钮长什么样」，靠回忆重录 | `rec.json` 每个动作带 `locator.snapshot`：`html`（outerHTML 前 300 字）+ `tag/role/name/attrs/rect` | 只存特征不存整页；不含账号数据；300 字封顶防录制文件膨胀 | | **子包说明书** | 子包只有脚本，换人接手看不懂为什么这么点 | `build_skill` 自动生成 `说明书.md`：干什么 / 何时跑 / 逐步（和定位库同序号）/ 每次给什么 / 落哪给谁 / 怎么算成功 / 改版怎么办 / 出问题怎么办 / 你录制时说的原话 | 只写录制 + 访谈里真实存在的；缺的写「待确认」，不编 | | **单遍判参** | 只有「录两遍比 diff」才知道哪个是变量，成本翻倍 | `node scripts/infer_params.mjs --rec X.rec.json [--out 参数判定.csv]`：日期 / 长单号 / 金额 / URL 带出 / 接口响应里出现 → 判变量并给理由 | **提示，不是定论**；关键链路仍以两遍 diff 为硬口径 | | **口述备注** | 「不知道什么时候加预算」这类意图，录完就想不起来了 | 录制时浮标备注框写一句 → 有动作时挂到**当前那一步**（`action.note`，这步干什么 / 什么规则），没动作时进 `rec.json.notes` 当全局规则；点浮标日志某一行可把备注挂到**指定步**；`record.mjs` 收尾打步骤清单，`evidence` 时间线出「这步干什么/规则」列，`interview.mjs --rec` 自动带出来 | 备注不算操作、不进定位库；跟答案冲突时以访谈答案为准 | | **写接口闸门** | 回放/接口脚本可能带着 POST（建计划、改预算、提交表单），误跑就动真实数据 | 非 GET（POST/PUT/PATCH/DELETE）**必须显式加 `--allow-write`**，否则直接拒跑并打印「先 `--dry` 核对」三步提示；还要 `--ack "上限=…｜批准=…"` 说清改多少、谁批的（原文落 `logs/写操作确认.log` 留痕）；GET 不受影响 | 只管「要不要放行」，不管参数对不对——URL/BODY 仍需 `--dry` 核对 | ## 子包两种形态 - **接口版**：`配置/接口.json` + `scripts/api_run.mjs`。`api_run.mjs --config 配置 [--param k=v] [--out x.csv] [--go] [--dry] [--bg] [--profile <dir>]`。走「已登录浏览器页面内 fetch」，同源带 cookie；`--dry` 只渲染 URL/body 不碰浏览器。 - **UI 版**：`run.mjs` 回放定位库 → 组装数据 → 贴到路由表位置 → 回读复核。表格搬运走这条，详见 `references/UI版-表格搬运.md`。 两种都不改代码改配置：换账户/换日期只加 `--param` 或改配置行。 ## 什么算「问明白了」（这一步决定它是不是自动化） > 用户判定标准（2026-11-06 原话）：「只有加的动作，不知道什么时候加，这样子没有动作的规则，做出来最多是一个重复的路径而已。」 > 但别拿模板卡人 —— 只问、不固化：答不上来记「待确认」，回头补。 - 有 `触发.json`，且里面能回答：**什么时候跑 / 参数哪来 / 跑完去哪给谁 / 怎么算成功 / 失败找谁**； - **答不上来不算错**：写成「待确认」列出来，子技能里也会带着这份欠账，谁接手都知道边界在哪（拿模板硬卡人反而是帮倒忙）； - 产出形态按实的写：本地文件、粘贴在线表格（映射由列头自动对，不用人手写）、接口回填、页面回读、只给人看——可多选； - 写操作（加预算、提交、发布）要写**上限 + 谁批 + 先 DryRun**；没写就当「待确认」，别让它自动跑； - 事件触发要看住**检查频率 + 单次/日累计上限**——没有上限就是无限自动执行； - 只有路径没有这些 → `build_skill --require-trigger` 直接拒绝（不加该参数时在子技能顶部插「还没问过需求」待办）。 ## 什么算「跑通」（别自己放宽） - 接口版：状态 2xx、字段能对上、行数 ≥ 下限、**字段数一致**，四项全过； - UI 版：预览列头与值对得上；真跑后每行唯一键都能在目标页回读见到，差一行 = 失败； - 失败就 `manage.mjs fail`，不许默默跳过； - 坏在哪儿别让人猜：`manage.mjs fail --http 401 --exit 3 …` 会自动归因，输出「现象 / 人话 / 哪坏了 / 下一步 / 要不要重录」；单独问用 `scripts/diagnose.mjs`。 ## 收尾：跑完必须关浏览器（全局规则） 生成子包时 `child.SKILL.md` / `child.api.SKILL.md` 必须带 `## 收尾` 段，缺了算没写完（子包模板已内置；交付前先查这一段）： - **终点**：数据落盘 / 回填完成 / 提交有回执 = 做完；录制线点浮标「结束」即终点（存盘 + 关浏览器） - **关谁**：按调试端口只关本技能自己开的那台 Chrome（`cdp.mjs` 内置 `closeChromeByPort`，只匹配 `--remote-debugging-port=<端口>` 的进程；禁止按进程名全杀）。**唯一例外**：端口识别为浏览器农场档位（`closeChromeSmart` 查 9300 `/slots`）→ 不关，档位归农场总管管 - **逃生**：`--keep-open` / `KEEP_BROWSER=1`，默认关 - **日志**：`关闭浏览器 port=... remaining=0`（证明真关了） 判据：**录完/跑完还把 Chrome 挂着 = 这条链路没做完。** ## 改完必过的三道门（交付/发布前） 1. **跑全部测试**：`node test/run_node_test.mjs` + `node test/run_forge_v2_test.mjs` + `node test/run_hud_test.mjs` + `node test/run_multitab_test.mjs` + `python -I test/run_offline_test.py`，全过才算改完。 2. **脱敏扫描复查**：公司/品牌名、内部项目名、个人账号、本机绝对路径、手机号/邮箱——0 命中才能分发；分发只发 zip，包内不得带 `recordings/` `evidence/` `produced/` `logs/` 和真实 `台账.csv`。 3. **改了任何文件（哪怕只是文档）→ 全量重验**：重新打包 + 重新解压复跑测试；MD5 与文件数变了就重新交付，别复用上一轮结果。 ## 边界（别越界） - **只要一份照着点的人工手册、不想自动化** → 证据包的时间线本身就是操作手册，不必生成子包。 - **要批量提交 / 建计划 / 发消息** → 本技能能录出来，但**真提交前必须问用户**，且先 `-DryRun`。 - **要出复盘报告 / 日报** → 用对应业务技能，工厂只管「取数路径」。 - **要看下载下来的本地文件** → `python scripts/localview.py --file <路径> [--open]`（读行数/列名/样例行，或调系统程序打开）。CDP 读不了别家程序的窗口，只能读文件。 ## 细节去哪找（按需读，别通读） | 要查什么 | 看哪个 | |---|---| | 录完怎么问需求、失败怎么用人话解释 | `references/需求访谈与失败归因.md` | | 改版自愈、子包说明书、单遍判参、口述备注 | `references/自愈_说明书_判参_备注.md` | | 合法边界、要不要担责、平台条款怎么自查 | `references/合规与法律边界.md` | | 坑点、症状→根因 | `references/Pitfalls.md` | | 页面浮标怎么画、怎么和驱动接线 | `references/页面浮标规范.md` | | UI 版表格搬运全链路 | `references/UI版-表格搬运.md` | | 失败记账 / 3 次重录 / 旧包 7 天 | `references/生命周期与升级.md` | | 打包、测试、脱敏纪律 | SKILL.md「改完必过的三道门」一节 | | 出包一条龙、上传平台硬约束（平铺/≤3 段/纯文本）、脱敏假命中坑 | `references/打包与验收.md` | | 哪些真验过、哪些待联调 | `references/实测状态.md` | | 浏览器外看结果（读下载的 xlsx/csv、调程序打开） | `references/本地文件读取.md` | | 某站点踩过的坑 | `references/site-<host>.md` | | 各能力口径与入口 | `功能台账.md` |

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本