host-page-automation
宿主网页自动化适配工作流。遇到 AI 表单操作、网页字段采集/填充、控制台框架探测、Vue/React/Ext/Angular 页面交互,或 Chat 驱动网页操作时使用。先只读探测,再单项脚本验证和字段映射,最后按需接入对话与确认执行;不建设万能填表引擎。
宿主页面自动化适配
目标与边界
把已验证的方法复用到新页面,不把历史页面实现直接复制到新系统,也不默认建设通用引擎。
核心判断:页面显示变了,不代表框架状态、业务模型或后台数据已经改变。
区分三件事:插件 UI 的框架、宿主页面的框架、宿主控件库。React 聊天面板可以操作 Vue、Ext 或 Angular 页面。仅凭 .ant-* 样式不能判定宿主是 React。
本 Skill 是工作方法,不是运行时、权限授予或已验证能力清单。适用于任何能够加载说明、调用浏览器工具或与用户协作的 harness/Agent,不依赖特定 Agent 产品。根据用户范围停在分析、探测、验证、实现或集成阶段;只要求分析时不要修改业务代码。
首次使用、移交给其他 Agent 或配置浏览器工具时,阅读 Agent 使用说明。浏览器工具名称和参数以当前工具 schema 为准;工具不可用时明确说明,不虚构调用。
“先识别框架,再按该框架的正常机制操作”用于降低假赋值风险,不是保证。正常 UI 交互、组件方法和业务回调均需验证;不能把直接改 DOM、props、store 或私有状态当成可靠填充。成功至少需要按目标核对显示值、组件值、业务身份/模型和关联结果,保存成功另行验证。
按需参考
工作流程
0. 明确范围和复用资源
- 确认目标域名、路径/hash、环境、iframe、操作字段及期望结果。
- 明确是采集、单项填充、多行修改、查询/选择,还是完整业务流程;不要默认包括保存、提交、审批。
- 阅读适用的 AGENTS.md。仅在需要代码适配或集成时,扫描 components、hooks、utils、api、config、types 和目标业务模块;纯页面探索不要求扫描无关仓库。
- 涉及代码实现时检查既有桥接、请求、存储、采集、控件适配器及近期提交。纯页面探索以浏览器现场证据为准;引用历史文档时指出过时内容。
- 若没有网页执行工具,提供最小控制台脚本,等待用户回传脱敏结果;不得声称已在真实页面执行。
输出:目标范围、可复用项、未知项、下一步最小验证。
1. 先只读探测
使用 Chrome DevTools MCP 或其他具备等效能力的浏览器工具时,按以下循环工作,不停留在 DOM 点击。以下工具名为 MCP 示例,不是对特定 harness 的依赖:
- 列出并确认目标页面,再选择或显式指定目标(例如
list_pages/select_page);pageId 仅为当前会话身份,不硬编码。 - 获取必要区域及当前元素引用(例如
take_snapshot),在正确 frame 的宿主 MAIN 上下文执行局部探测(例如evaluate_script)。先核实工具的上下文选择能力,无法访问目标 frame 时说明阻塞;参数严格遵循当次工具 schema,不附加未声明的记账字段。 - 从元素追踪框架实例、父链、props、表单 prop、模型、候选及事件/方法。入口失败时换已知框架线索,不立即要求用户导出 HTML。
- 只返回可序列化的白名单摘要。通过引用比较、render/绑定配置和实际前后回读建立关联;同值或相似名称不能单独证明绑定。
- 需要打开弹窗、切业务 Tab、查询或调用未知方法时,先说明目的和副作用并等待授权;用户手动操作后重新定位。
click/fill返回成功只表示工具动作完成,必须重新核对页面和运行时结果。连续无新增证据时说明阻塞,不重复试写。
只读探测检查项:
- 确认 Console 选中了目标 iframe 和网页 MAIN 上下文,而非扩展 isolated world。
- 只采必要结构:框架特征、控件类型、业务区域、标签、真实属性、可编辑状态、选项数量。
- 按证据判定 Vue 2/3、React、Ext 或 Angular;探测不到内部接口不等于页面不是该框架。
- 分开记录事实、推测、未验证内容。不要依据动态类名、扫描序号或 UI 库外观确定稳定定位。
- 不打印整页 HTML、完整组件实例、store/record、cookie、token、凭据或人员信息;必要业务值仅本地最小核对。
未确认框架和作用域前,不生成大而全的写入脚本。
2. 建立字段和动作映射
每个目标记录:
| 项 | 要求 |
|---|---|
| 业务身份 | 稳定 key、业务区域、当前行/弹窗 |
| 定位依据 | 实际存在的 name/prop、label、稳定锚点或组件 ID |
| 控件能力 | 类型、值、显示值、真实选项、required、readOnly、disabled、loading |
| 业务身份值 | label、value、编码/记录身份分别记录,不互相冒充 |
| 执行动作 | 输入事件、组件正常方法、选项点击、lookup 回调等 |
| 前置依赖 | 上游字段、挂载、Tab、权限、异步加载 |
| 验证证据 | DOM、组件、模型、关联列表分别能证明什么 |
读取状态至少区分已读取、确认为空、不可读/未采集。隐藏或未挂载字段不能当空值;未知字段不让 AI 猜填。
定位必须限制作用域并检查唯一性。多个同名候选须按编码、分组、父级路径或用户澄清消歧,不默认取第一项。
3. 单控件、单动作验证
- 只在用户允许的测试草稿和字段上验证,先说明潜在网络与业务副作用。
- 每轮只验证最小动作,记录必要的原值和预期;未知原值不得用清空来“恢复”。
- 优先宿主正常 DOM 交互/事件,再考虑已验证的组件解析、通知方法或业务回调。
- 写入后观察显示值、组件值、业务模型和关联结果,不能只看 dirty/invalid。
- 失败先诊断,不叠加多种事件、重复点击或盲目自动重试。
- 单项通过后再扩大到一组字段或一个业务步骤,不直接跳到整单自动化。
内部接口只能作为环境相关能力:检测存在、验证语义、缺失即停止。不得修改私有状态、解除 readonly/disabled 或绕过业务前置来制造成功。
每次记录实际写入路径:MCP 正常输入/点击、脚本 DOM 赋值及合成事件、组件方法,或业务回调。通过框架定位并不等于通过框架方法赋值;组件回读一致也不证明完整事件链已执行。同值 setValue 可能不触发 change,不能作为两条路径等价的充分对照,不为触发事件临时改成其他值。
4. 验证依赖与异步联动
- 先画依赖顺序,例如类型 -> 模式 -> 日期,主记录 -> 组织/付款,关联记录 -> 明细。
- 会引起联动的动作前建立观察,动作后等请求、组件、选项或模型变化趋稳;不能只 sleep 固定时间。
- 联动、切 Tab、切行、打开弹窗后重新获取组件/DOM/选项,不使用失效引用。
- 前置动作失败或超时就停止,不通过跳过错误继续写依赖字段。
- 批末回读早期字段,检查是否被后续联动覆盖。
- 多行场景写前检查页面、表格、目标行和绑定身份;显示位置、业务行号、内部 itemId 不可混用。
5. 仅在需要时产品化
把验证过的能力放入现有模块,按职责拆分:
- Collector:只读白名单快照及读取状态。
- Adapter / Page Runtime:字段和控件的已验证操作。
- Executor / Workflow:业务顺序、守卫、等待、回读、部分失败。
- Bridge:只传可序列化的白名单业务消息。
- Chat Controller:请求、会话、草稿、提案失效与确认。
- UI:消息、候选、变更预览、用户确认和执行结果。
不要为了套分层而创建大量空文件或通用框架,不扩大无关主入口。
扩展侧管理 UI、AI 配置和请求;MAIN 侧访问宿主框架和执行页面动作。Key 不进入 MAIN、快照或页面消息。复用既有后台请求通道;桥接不是鉴权边界,不开放 eval、任意脚本、任意方法调用。
6. Chat / AI 接入约束
本节仅适用于产品化后的业务 Chat/AI 执行接口,不限制开发辅助阶段的探索 Agent 使用浏览器工具生成局部探测代码。探索代码不授予业务操作权限;实际写入仍须遵守用户授权和单项验证要求。
- 默认每轮读取新鲜页面上下文,读取失败不继续生成可执行计划;既有特殊分支需明确说明,不宣称全部模块一致。
- AI 只返回业务字段/白名单操作,不返回 DOM 选择器、组件 ID、脚本或操作授权。
- 完整响应结束并通过 schema、类型、选项及白名单校验后,才生成提案;流式片段不执行。
- 提案绑定本轮快照和目标身份。等待 AI 期间页面变化、新输入或新对话,使相关旧提案失效或要求重检。
- 展示目标、修改前后值、前置动作和副作用,用户确认后重新校验页面、权限、候选和行身份。
- 使用执行锁、请求去重和失败停止;执行中禁止并发写入。重复拦截不等于成功,状态不确定不换 ID 盲目重试。
- 未提及字段保持不变,不以历史对话覆盖当前页面事实。多候选/缺数据时追问,不套用测试默认值。
- 填充默认不保存、不提交、不审批。查询、选项选择和弹窗确认仍可能有业务副作用,不能声称“完全无副作用”。
7. 交付并持续沉淀
使用验证清单记录:环境、框架证据、字段映射、单项结果、依赖、限制、未通过项和下一步。
明确区分:代码已实现、语法/类型通过、模拟测试通过、真实页面单项通过、端到端通过、后台保存成功。没有对应证据不得升级结论。
只追加可复用的规则和必要案例,不复制敏感业务快照,不把某次授权选第一项或某个测试值沉淀为业务默认。
必须停下的情况
- 目标页面/iframe、定位唯一性或行身份不确定。
- 字段隐藏、禁用、只读,或依赖未满足;日期输入框只读需先判断是否正常日历入口,不强行赋值。
- 内部接口不可用、选项加载不稳、候选不唯一或业务身份无法核对。
- 请求超时、页面变化、意外字段变化或写后模型不一致。
- 保存/提交/审批超出用户明确范围。
停止时说明已发生的修改、未执行部分、是否可能留下部分结果及人工核对方式;不承诺自动回滚。
- Downloads
- Security audit
- Pass
- Last updated
- 1w ago
- Current version
- v1.0.0
- License
- MIT-0
