重复的浏览器任务变skill

概述

skill-forge：重复的浏览器操作 → 更短的自动化路径

⚠️ 使用范围与免责声明（先读这条）

1. 许可：MIT，可自由使用、修改、分发，保留版权声明即可。
2. 禁止违规用途：不得用于绕过平台审核、规避广告法、伪造数据、刷量或绕过反爬。
3. 使用者自负合规责任：录制与产出的内容发布前，请按《广告法》与各平台最新规则自行复核；本工具生成的内容不构成官方承诺。
4. 数据与责任切割：本包不含任何投放数据、账号数据、品牌与产品系列名、个人信息；使用者在录制、回填、发布过程中产生的任何内容，由其自行保证来源合法并已脱敏，与作者无关。
5. 录制会在本机生成 recordings/、evidence/（可能含你页面上的数据），只落本地、不上传；用完请自行清理。
6. 合法使用边界（逐条自查见 references/合规与法律边界.md）：只对你有权访问的账号与页面录制；不得绕过验证码 / 风控 / 付费墙，不得抓取不公开数据，不得把他人个人信息录进产物；目标平台的《服务协议》是否允许自动化操作，由使用者自行确认并承担后果。
7. 三条硬红线：不抓竞品非公开数据、不绕验证码与风控、不高频访问。

一句话：你像平时一样走一遍 → 工厂录下「点了什么 / 跳到哪 / 发了什么请求 / 回了什么数据」→ agent 据此判断有没有更短的路（直调接口、少点几步、换入口）→ 你拍板 → 生成能自己跑的子技能包。

定位（别偏）：只干一件事 —— 把重复的浏览器操作，变成更短、可自动跑的路径，减少人工。不做通用爬虫，不做数据加工，不做报表美化。

0 装之前要知道什么

风险须知（四条，都是「风险 → 影响 → 怎么兜」）：

1. 会读你已登录后台的数据 → 页面数据可能含投放/账号信息 → 默认只读；产物只落本机，不上传；用完自行清理。
2. 会开独立调试 Chrome → 不抢你正在用的窗口，但会多一个进程 → 跑完自动按端口关掉；--keep-open 才留着。
3. 能生成写操作的子包（加预算/提交/发布）→ 误跑会改生产数据 → 写操作必须问「上限 + 谁批 + 先 DryRun」，没写上限只标「待确认」。
4. 登录密码 → 泄露风险 → 只在内存里用一次，不落盘、不进日志、不进子包。

部署前人工审批：① 我知道它会读什么（哪个后台的登录态）；② 我同意它只连 127.0.0.1 的调试口，不连外网；③ 那个浏览器/账号是我自己的。任一不确定就别装，改用只读模式（只做录制与证据包，不生成可执行子包）。

0.3 工具权限与调用位置（评审要的「用途证据」）

0.4 依赖与供应链

供应链控制：零第三方包（无 npm/pip 安装，无镜像依赖）；Chrome 用本机已装的；脚本全部随包分发、可逐行审阅；没有外网下载步骤。代码来源：独立实现，未复制任何外部代码/注释/文案/界面；思路借鉴的公开来源逐条列在 references/合规与法律边界.md 附录 A（仅说明来源，不构成合作或背书）。

四步（第 ④ 步问需求不能跳：不问 = 产物只是「重复路径」，不是自动化）

录制可 --url about:blank 起步，用户自己粘地址。同 tab 整页跳转靠重注入，新开 tab 靠 followNewTab()（只跟 http(s)）。

开工先查站点经验：在 references/ 里找 site-<host>.md，有先读；真跑通后回写 3–5 条（入口/登录/数据从哪来/坑/校验），只写验证过的。

判据：走接口还是走 UI

候选打分：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；一站点一份，别重复踩坑。

五条「少踩坑」的机制（都已落成代码 + 有断言）

子包两种形态

• 接口版：配置/接口.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=<端口> 的进程；禁止按进程名全杀）
• 逃生：--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 + 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 读不了别家程序的窗口，只能读文件。

细节去哪找（按需读，别通读）