Posts on Tao

前端 UI 设计技能颗粒度：原子化检查清单

di4urp@gmail.com (taevas) — Tue, 21 Apr 2026 14:00:00 +0800

技能颗粒度检查项汇总

本表格将前端 UI 设计拆解为原子化检查项，每项可独立验证（是否存在/是否做到）、独立描述（交给 AI 实现）、独立验收。

使用方式：在设计初期逐层扫描，勾选需要实现的检查项，形成精确的设计需求清单。

全量检查项

层级	检查项	优先级	验证方式
排版层	字体族定义	⭐⭐⭐⭐⭐	检查 CSS 变量是否定义 primary/mono/fallback
排版层	字号阶梯系统	⭐⭐⭐⭐⭐	检查 xs/sm/base/lg/xl/2xl/3xl/4xl 是否递进
排版层	行高规范	⭐⭐⭐⭐⭐	检查 tight/normal/relaxed 行高 token
排版层	字重定义	⭐⭐⭐⭐	检查 light/normal/medium/semibold/bold token
排版层	字间距定义	⭐⭐⭐	检查 tighter/tight/normal/wide/wider token
排版层	标题层级	⭐⭐⭐⭐⭐	h1-h6 视觉层级是否清晰递减
排版层	正文排版	⭐⭐⭐⭐⭐	body 文本是否可读（字号≥14px，行高≥1.5）
排版层	辅助文本	⭐⭐⭐⭐	small/caption/overline 样式是否定义
排版层	文本截断	⭐⭐⭐⭐	单行截断 / 多行截断是否有工具类
排版层	文本对齐	⭐⭐⭐	left/center/right/justify 是否覆盖
排版层	文本装饰	⭐⭐⭐	underline/strikethrough/overline
排版层	文本转换	⭐⭐⭐	uppercase/lowercase/capitalize
排版层	中英文混排	⭐⭐⭐⭐	中英文间自动空格、标点悬挂处理
排版层	连字符处理	⭐⭐	hyphens auto 是否处理
排版层	段落间距	⭐⭐⭐⭐	段间距是否统一（非双重 margin）
排版层	代码文本样式	⭐⭐⭐⭐	inline code 字体/背景/圆角/内边距
排版层	等宽数字	⭐⭐⭐⭐	tabular-nums 用于金额/表格数字对齐
排版层	CJK 断行规则	⭐⭐⭐	word-break/overflow-wrap 处理中文长词
排版层	空白处理	⭐⭐⭐	white-space 五种模式覆盖
排版层	选中文字样式	⭐⭐⭐	::selection 背景色+文字色 token
颜色层	品牌色定义	⭐⭐⭐⭐⭐	primary/secondary/accent 是否定义
颜色层	语义色定义	⭐⭐⭐⭐⭐	success/warning/error/info 是否定义
颜色层	中性色阶梯	⭐⭐⭐⭐⭐	gray-50 到 gray-950 是否完整
颜色层	文本色阶梯	⭐⭐⭐⭐⭐	primary/secondary/tertiary/disabled/inverse
颜色层	背景色定义	⭐⭐⭐⭐⭐	page/card/surface/overlay 背景色
颜色层	边框色定义	⭐⭐⭐⭐	default/hover/focus/error 边框色
颜色层	状态色定义	⭐⭐⭐⭐⭐	hover/active/focus/disabled 各状态色
颜色层	交互反馈色	⭐⭐⭐⭐	链接色/已访问链接色/悬浮链接色
颜色层	暗色模式映射	⭐⭐⭐⭐⭐	所有颜色是否有 dark 变体
颜色层	颜色对比度	⭐⭐⭐⭐⭐	正文≥4.5:1、大文本≥3:1（WCAG AA）
颜色层	色盲友好	⭐⭐⭐	不单独依赖颜色传达信息
颜色层	渐变色定义	⭐⭐⭐	品牌渐变/装饰渐变 token
颜色层	透明度定义	⭐⭐⭐	常用 opacity 值 token 化
颜色层	阴影色定义	⭐⭐⭐⭐	各层级阴影是否使用语义色而非硬编码
间距层	基准单位定义	⭐⭐⭐⭐⭐	4px 或 8px 基准网格
间距层	间距阶梯系统	⭐⭐⭐⭐⭐	0/1/2/3/4/5/6/8/10/12/16… 是否完整
间距层	组件内间距	⭐⭐⭐⭐⭐	padding 是否遵循阶梯系统
间距层	组件外间距	⭐⭐⭐⭐	margin/gap 是否遵循阶梯系统
间距层	栅格间距	⭐⭐⭐⭐	grid/flex gap 是否 token 化
间距层	响应式间距	⭐⭐⭐⭐	不同断点下间距是否缩放
间距层	区块间距	⭐⭐⭐⭐	section 间距是否统一
间距层	容器内间距	⭐⭐⭐⭐⭐	页面容器内边距是否一致
间距层	负间距	⭐⭐	偏移/重叠场景是否支持
圆角层	圆角阶梯	⭐⭐⭐⭐⭐	none/sm/md/lg/xl/full 是否定义
圆角层	组件圆角一致	⭐⭐⭐⭐	相同层级组件圆角是否统一
圆角层	按钮/输入框圆角	⭐⭐⭐⭐⭐	表单元素圆角是否匹配
圆角层	卡片/弹窗圆角	⭐⭐⭐⭐	容器类组件圆角是否匹配
圆角层	图片/头像圆角	⭐⭐⭐⭐	媒体元素圆角规范
阴影层	阴影层级	⭐⭐⭐⭐⭐	sm/md/lg/xl/inner 是否递进
阴影层	组件阴影一致	⭐⭐⭐⭐	同层级组件阴影统一
阴影层	暗色模式阴影	⭐⭐⭐⭐	暗色下阴影是否适配（更亮的阴影）
布局层	容器最大宽度	⭐⭐⭐⭐⭐	max-width 是否定义（如 1280px）
布局层	响应式断点定义	⭐⭐⭐⭐⭐	sm/md/lg/xl/2xl 断点值
布局层	栅格列数	⭐⭐⭐⭐⭐	12 列 / 24 列系统
布局层	栅格间距	⭐⭐⭐⭐	gutter 值 token 化
布局层	页面布局模式	⭐⭐⭐⭐⭐	header/main/sidebar/footer 组合
布局层	内容区域宽度	⭐⭐⭐⭐	全宽/定宽/侧边栏模式
布局层	Flex 布局模式	⭐⭐⭐⭐	direction/wrap/justify/align 工具类
布局层	Grid 布局模式	⭐⭐⭐⭐	template/areas/auto 工具类
布局层	居中对齐	⭐⭐⭐⭐	水平/垂直/双轴居中方案
布局层	粘性定位	⭐⭐⭐	header/sidebar 的 sticky 行为
布局层	Z-index 层级	⭐⭐⭐⭐⭐	dropdown/modal/tooltip/notification 层级体系
布局层	溢出处理	⭐⭐⭐⭐	内容溢出的 scroll/hidden/ellipsis 方案
布局层	最小/最大尺寸	⭐⭐⭐	min-width/min-height/max-width 约束
布局层	安全区域适配	⭐⭐⭐	mobile safe-area-inset 处理
组件-按钮	变体（5+）	⭐⭐⭐⭐⭐	primary/secondary/ghost/outline/destructive
组件-按钮	尺寸（3+）	⭐⭐⭐⭐⭐	sm/md/lg
组件-按钮	交互状态（6）	⭐⭐⭐⭐⭐	default/hover/active/focus/disabled/loading
组件-按钮	图标按钮	⭐⭐⭐⭐	left-icon/right-icon/icon-only
组件-按钮	按钮组	⭐⭐⭐	组合排列/分割线
组件-按钮	按钮宽度	⭐⭐⭐	full-width / auto / fixed
组件-输入	变体覆盖	⭐⭐⭐⭐⭐	text/password/email/number/search/url/tel
组件-输入	尺寸（3+）	⭐⭐⭐⭐⭐	sm/md/lg
组件-输入	交互状态（6）	⭐⭐⭐⭐⭐	default/hover/focus/error/disabled/readonly
组件-输入	前缀/后缀	⭐⭐⭐⭐	图标/文字/单位前后缀
组件-输入	清除按钮	⭐⭐⭐	输入内容后显示一键清除
组件-输入	密码切换	⭐⭐⭐⭐	密码明文/密文切换按钮
组件-输入	字符计数	⭐⭐⭐	maxlength 倒计显示
组件-输入	Textarea	⭐⭐⭐⭐	自动高度/最大高度/resize 控制
组件-输入	标签浮动	⭐⭐⭐	浮动标签动画效果
组件-选择	Select 下拉	⭐⭐⭐⭐⭐	单选/多选/搜索/分组/异步加载
组件-选择	Checkbox	⭐⭐⭐⭐⭐	单选/多选/indeterminate/禁用
组件-选择	Radio	⭐⭐⭐⭐⭐	单选/按钮样式/禁用
组件-选择	Switch	⭐⭐⭐⭐	开/关/禁用/加载/文字标签
组件-选择	Slider	⭐⭐⭐	单值/范围/标记/tooltip
组件-选择	日期选择	⭐⭐⭐	日期/时间/日期范围
组件-选择	文件上传	⭐⭐⭐	拖拽/点击/进度/预览/类型限制
组件-选择	颜色选择	⭐⭐	取色器/预设色板
组件-卡片	结构完整性	⭐⭐⭐⭐⭐	header/body/footer 三段式
组件-卡片	视觉变体	⭐⭐⭐⭐	边框/阴影/flat/elevated
组件-卡片	交互状态	⭐⭐⭐⭐	static/hoverable/clickable
组件-卡片	媒体区域	⭐⭐⭐⭐	顶部图片/封面图模式
组件-弹窗	Modal 对话框	⭐⭐⭐⭐⭐	尺寸/滚动/关闭/遮罩/动画
组件-弹窗	Drawer 抽屉	⭐⭐⭐⭐	方向(上下左右)/尺寸/关闭方式
组件-弹窗	Popover 气泡	⭐⭐⭐⭐	方向/触发方式/箭头/内容类型
组件-弹窗	确认对话框	⭐⭐⭐⭐⭐	危险操作二次确认/文案规范
组件-表格	基础功能	⭐⭐⭐⭐⭐	列定义/数据渲染/空状态
组件-表格	排序	⭐⭐⭐⭐	单列/多列排序/远程排序
组件-表格	筛选	⭐⭐⭐⭐	列筛选/全局搜索/筛选状态展示
组件-表格	分页	⭐⭐⭐⭐⭐	页码/每页条数/总数/跳转
组件-表格	固定列/头	⭐⭐⭐⭐	首列/末列固定/表头固定
组件-表格	行选择	⭐⭐⭐⭐	单选/多选/全选/跨页选择
组件-表格	行展开	⭐⭐⭐	展开详情/嵌套子表
组件-表格	加载状态	⭐⭐⭐⭐	loading spinner / skeleton
组件-表格	虚拟滚动	⭐⭐⭐	大数据量虚拟化渲染
组件-标签页	变体	⭐⭐⭐⭐	line/card/pill
组件-标签页	滚动	⭐⭐⭐	标签过多时横向滚动/箭头
组件-标签页	懒加载	⭐⭐⭐	非活跃 tab 内容延迟渲染
组件-导航	顶部导航	⭐⭐⭐⭐⭐	logo/菜单/用户区布局
组件-导航	侧边导航	⭐⭐⭐⭐	可折叠/展开/子菜单/高亮当前
组件-导航	面包屑	⭐⭐⭐⭐	层级展示/可点击/截断
组件-导航	步骤条	⭐⭐⭐⭐	水平/垂直/步骤状态/可点击
组件-导航	锚点导航	⭐⭐⭐	页内跳转/高亮当前位置
组件-导航	返回顶部	⭐⭐⭐	滚动出现/平滑滚动
组件-反馈	Toast 消息	⭐⭐⭐⭐⭐	类型/位置/自动关闭/可关闭/堆叠
组件-反馈	Alert 告警	⭐⭐⭐⭐	类型/可关闭/带操作/banner 模式
组件-反馈	进度条	⭐⭐⭐⭐	确定/不确定/环形/步骤进度
组件-反馈	加载 Spinner	⭐⭐⭐⭐	尺寸/颜色/全局/局部
组件-反馈	骨架屏	⭐⭐⭐⭐⭐	形状(circle/rect/text)/动画(pulse/wave)
组件-反馈	空状态	⭐⭐⭐⭐⭐	插图/标题/描述/操作按钮
组件-反馈	结果页	⭐⭐⭐	成功/失败/处理中状态展示
组件-数据展示	Badge 徽标	⭐⭐⭐⭐	dot/number/text/颜色/位置
组件-数据展示	Tag 标签	⭐⭐⭐⭐	颜色/可关闭/可选中/边框
组件-数据展示	Avatar 头像	⭐⭐⭐⭐	尺寸/形状/fallback/状态点/分组
组件-数据展示	Tooltip	⭐⭐⭐⭐⭐	方向/延迟/触发方式/箭头
组件-数据展示	Collapse 折叠	⭐⭐⭐	手风琴/多开/动画/禁用
组件-数据展示	Tree 树形	⭐⭐⭐	展开/选择/勾选/搜索/拖拽排序
组件-数据展示	Timeline 时间线	⭐⭐⭐	左右布局/自定义节点/时间标记
组件-数据展示	Statistic 统计	⭐⭐⭐	数值/趋势/前后缀/动画计数
组件-数据展示	Divider 分割线	⭐⭐⭐	水平/垂直/带文字
组件-数据展示	Rate 评分	⭐⭐	星级/半星/自定义图标/只读
组件-组合	表单验证联动	⭐⭐⭐⭐⭐	输入→验证→错误→修正→成功完整流程
组件-组合	表格筛选分页	⭐⭐⭐⭐	筛选→重置分页→结果数联动
组件-组合	搜索防抖空态	⭐⭐⭐⭐	输入→防抖→loading→结果/空态
组件-组合	弹窗表单验证	⭐⭐⭐⭐	弹窗内完整表单验证+提交流程
组件-组合	侧边栏响应式	⭐⭐⭐⭐	大屏展开→小屏折叠/抽屉
组件-组合	文件上传完整流	⭐⭐⭐	拖入→上传中→完成→预览/重试
交互层	过渡时长	⭐⭐⭐⭐⭐	fast(150ms)/normal(200ms)/slow(300ms)
交互层	缓动曲线	⭐⭐⭐⭐⭐	ease-in-out/cubic-bezier 是否 token 化
交互层	Hover 效果	⭐⭐⭐⭐⭐	可交互元素是否有 hover 反馈
交互层	Active 效果	⭐⭐⭐⭐	按下是否有视觉反馈
交互层	Focus 指示	⭐⭐⭐⭐⭐	focus-visible 环/outline
交互层	Focus 陷阱	⭐⭐⭐⭐	弹窗内 Tab 循环
交互层	拖拽交互	⭐⭐⭐	拖拽手柄/放置区域/排序反馈
交互层	手势支持	⭐⭐⭐	滑动/长按/双击/捏合缩放
交互层	右键菜单	⭐⭐⭐	自定义上下文菜单
交互层	快捷键	⭐⭐⭐	全局/局部快捷键定义
交互层	防抖/节流	⭐⭐⭐⭐	搜索/滚动/resize 事件防抖
交互层	乐观更新	⭐⭐⭐	操作即时反馈 + 后台同步
交互层	撤销/重做	⭐⭐	操作历史栈
交互层	骨架加载	⭐⭐⭐⭐	首屏/组件级 skeleton
交互层	渐进式加载	⭐⭐⭐	lazy-load / 分页 / 无限滚动
响应式层	移动端布局	⭐⭐⭐⭐⭐	单列/底部导航/汉堡菜单
响应式层	平板布局	⭐⭐⭐⭐	双列/侧边栏折叠
响应式层	桌面布局	⭐⭐⭐⭐⭐	多列/侧边栏展开/wide screen
响应式层	触摸目标	⭐⭐⭐⭐⭐	可点击区域≥44×44px
响应式层	字号缩放	⭐⭐⭐⭐	小屏标题是否适当缩小
响应式层	间距缩放	⭐⭐⭐⭐	小屏间距是否缩小
响应式层	图片响应式	⭐⭐⭐⭐	srcset/sizes/art direction
响应式层	导航变形	⭐⭐⭐⭐	desktop→hamburger 底部导航
响应式层	表格响应式	⭐⭐⭐⭐	列隐藏/卡片化/横向滚动
响应式层	横竖屏适配	⭐⭐⭐	orientation 变化布局调整
响应式层	打印样式	⭐⭐	@media print 隐藏导航等
无障碍层	语义化 HTML	⭐⭐⭐⭐⭐	header/nav/main/section/footer/article
无障碍层	ARIA 标签	⭐⭐⭐⭐⭐	aria-label/aria-describedby/aria-live
无障碍层	ARIA 角色	⭐⭐⭐⭐	role=“button”/“dialog”/“tablist”
无障碍层	颜色对比度	⭐⭐⭐⭐⭐	正文≥4.5:1 / 大文本≥3:1
无障碍层	键盘导航	⭐⭐⭐⭐⭐	所有功能可通过键盘操作
无障碍层	Tab 顺序	⭐⭐⭐⭐	tabindex 逻辑顺序
无障碍层	跳过导航	⭐⭐⭐	skip-to-content 链接
无障碍层	焦点可见	⭐⭐⭐⭐⭐	focus-visible 样式清晰
无障碍层	焦点陷阱	⭐⭐⭐⭐	弹窗内焦点不外溢
无障碍层	屏幕阅读器文本	⭐⭐⭐⭐	sr-only / visually-hidden
无障碍层	图片 alt 文本	⭐⭐⭐⭐⭐	所有 img 有有意义的 alt
无障碍层	表单标签关联	⭐⭐⭐⭐⭐	label htmlFor / aria-labelledby
无障碍层	错误提示关联	⭐⭐⭐⭐	aria-describedby 指向错误消息
无障碍层	减少动画偏好	⭐⭐⭐⭐	prefers-reduced-motion 尊重
无障碍层	高对比模式	⭐⭐⭐	prefers-contrast 适配
无障碍层	减少透明度	⭐⭐	prefers-reduced-transparency
无障碍层	动态字体	⭐⭐⭐	rem 单位支持用户字号设置
主题层	亮色模式	⭐⭐⭐⭐⭐	完整的 light theme tokens
主题层	暗色模式	⭐⭐⭐⭐⭐	完整的 dark theme tokens
主题层	主题切换器	⭐⭐⭐⭐	手动/跟随系统/记忆偏好
主题层	切换过渡	⭐⭐⭐⭐	模式切换时平滑过渡
主题层	CSS 变量体系	⭐⭐⭐⭐⭐	所有设计值用 CSS custom properties
主题层	品牌定制能力	⭐⭐⭐	覆盖 CSS 变量即可换肤
主题层	图片主题适配	⭐⭐⭐	暗色模式下图片降低亮度/反色
主题层	第三方嵌入适配	⭐⭐	嵌入组件跟随主题
动效层	入场动画	⭐⭐⭐⭐	fade/slide/scale/expand
动效层	退场动画	⭐⭐⭐⭐	fade-out/collapse/slide-out
动效层	列表动画	⭐⭐⭐	列表项交错入场(stagger)
动效层	页面过渡	⭐⭐⭐	路由切换过渡效果
动效层	展开折叠	⭐⭐⭐⭐	手风琴/面板展开收起动画
动效层	弹窗动画	⭐⭐⭐⭐	modal/drawer 进出动画
动效层	拖拽反馈	⭐⭐⭐	拖起/放下/排序占位动画
动效层	数值变化动画	⭐⭐⭐	数字递增/递减动画
动效层	微交互	⭐⭐⭐⭐	点赞/收藏/勾选的动效反馈
动效层	加载动画	⭐⭐⭐⭐	spinner/skeleton/pulse
动效层	prefers-reduced-motion	⭐⭐⭐⭐	尊重用户减少动画偏好
图标层	图标集选择	⭐⭐⭐⭐⭐	Lucide/Heroicons/Phosphor 等统一
图标层	图标尺寸阶梯	⭐⭐⭐⭐	xs(12)/sm(16)/md(20)/lg(24)/xl(32)
图标层	图标线条粗细	⭐⭐⭐⭐	1.5px/2px 是否统一
图标层	图标颜色	⭐⭐⭐	继承文字色/独立色/语义色
图标层	图标+文字对齐	⭐⭐⭐⭐	图标与文字垂直居中对齐
图标层	图标可点击区域	⭐⭐⭐	纯图标按钮点击热区足够
图标层	暗色模式图标	⭐⭐⭐	SVG fill 随主题切换
图标层	自定义 SVG	⭐⭐⭐	自定义图标保持风格一致
图片层	占位符	⭐⭐⭐⭐	加载中/加载失败/无图占位
图片层	懒加载	⭐⭐⭐⭐⭐	loading=“lazy” / IntersectionObserver
图片层	响应式图片	⭐⭐⭐⭐	srcset + sizes 属性
图片层	宽高比锁定	⭐⭐⭐⭐	aspect-ratio 防止布局抖动
图片层	骨架加载	⭐⭐⭐⭐	图片区域骨架屏
图片层	图片裁剪模式	⭐⭐⭐	cover/contain/fill 规范
图片层	图片格式优化	⭐⭐⭐	WebP/AVIF 优先 + fallback
图片层	压缩质量	⭐⭐⭐	质量/体积权衡标准
表单层	表单布局	⭐⭐⭐⭐⭐	水平/垂直/内联
表单层	标签位置	⭐⭐⭐⭐⭐	上/左/左对齐/右对齐
表单层	必填标记	⭐⭐⭐⭐⭐	星号/文字标识必填项
表单层	可选标记	⭐⭐⭐	(可选) 文字标识可选项
表单层	帮助文本	⭐⭐⭐⭐	字段下方说明文字
表单层	验证时机	⭐⭐⭐⭐	blur/submit/实时验证策略
表单层	错误提示位置	⭐⭐⭐⭐⭐	字段下方/右侧/汇总
表单层	错误提示样式	⭐⭐⭐⭐	颜色/图标/动画一致性
表单层	成功提示	⭐⭐⭐	字段级成功状态反馈
表单层	字段分组	⭐⭐⭐⭐	fieldset/分组标题/分割线
表单层	字段依赖联动	⭐⭐⭐	A 字段值影响 B 字段显隐/选项
表单层	表单进度	⭐⭐⭐	多步表单进度指示
表单层	表单草稿保存	⭐⭐	防止意外丢失
表单层	提交状态	⭐⭐⭐⭐	提交中 loading + 防重复提交
内容层	标题层级规范	⭐⭐⭐⭐⭐	h1→h2→h3 不跳级
内容层	段落长度	⭐⭐⭐	单段≤3-4 行
内容层	列表使用	⭐⭐⭐	≥3 项用列表代替段落
内容层	链接样式	⭐⭐⭐⭐	下划线/颜色区分/visited 状态
内容层	代码块样式	⭐⭐⭐⭐	语法高亮/行号/复制按钮/语言标签
内容层	引用样式	⭐⭐⭐	blockquote 视觉区分
内容层	富文本排版	⭐⭐⭐	表格/图片/脚注在内容中样式
内容层	长文本可读性	⭐⭐⭐⭐	内容区最大宽度（60-75 字符）
国际化层	文字方向	⭐⭐⭐	LTR/RTL 布局支持
国际化层	文字长度适配	⭐⭐⭐	不同语言文案长度差异处理
国际化层	日期/数字格式	⭐⭐⭐	locale 感知的格式化
国际化层	货币格式	⭐⭐⭐	符号位置/小数位
国际化层	复数形式	⭐⭐	i18n 复数规则处理
国际化层	字体回退	⭐⭐⭐	多语言字体栈
性能层	首屏加载	⭐⭐⭐⭐⭐	FCP/LCP 指标
性能层	交互响应	⭐⭐⭐⭐⭐	INP/FID 指标
性能层	视觉稳定性	⭐⭐⭐⭐⭐	CLS 指标
性能层	代码分割	⭐⭐⭐⭐	路由级/组件级 lazy loading
性能层	资源预加载	⭐⭐⭐	preload/prefetch 关键资源
性能层	字体优化	⭐⭐⭐⭐	font-display:swap / 子集化 / 预加载
性能层	图片优化	⭐⭐⭐⭐	响应式/懒加载/格式/尺寸预留
性能层	动画性能	⭐⭐⭐	只使用 transform/opacity
性能层	渲染优化	⭐⭐⭐	虚拟列表 / 减少 DOM 深度
性能层	缓存策略	⭐⭐⭐	静态资源缓存/CDN
安全层	XSS 防护	⭐⭐⭐⭐⭐	用户内容转义/CSP
安全层	CSRF 防护	⭐⭐⭐⭐	Token/SameSite Cookie
安全层	敏感信息遮蔽	⭐⭐⭐⭐	密码/身份证/银行卡号掩码
安全层	输入净化	⭐⭐⭐⭐	HTML/URL/SQL 输入过滤
滚动与光标层	平滑滚动	⭐⭐⭐	scroll-behavior: smooth
滚动与光标层	滚动阴影	⭐⭐⭐⭐	内容滚动时 header/footer 底部阴影
滚动与光标层	自定义滚动条	⭐⭐⭐	webkit-scrollbar 样式
滚动与光标层	锁定背景滚动	⭐⭐⭐⭐	弹窗打开时 body overflow:hidden
滚动与光标层	光标类型	⭐⭐⭐	pointer/not-allowed/wait/text/grab
滚动与光标层	选区样式	⭐⭐⭐	::selection 背景+文字色
滚动与光标层	占位符样式	⭐⭐⭐	::placeholder 颜色
滚动与光标层	滚动进度指示	⭐⭐	页面顶部阅读进度条
错误层	404 页面	⭐⭐⭐⭐	插图+描述+返回入口
错误层	500 页面	⭐⭐⭐⭐	插图+描述+重试
错误层	网络错误	⭐⭐⭐⭐	断网提示+重试
错误层	空列表	⭐⭐⭐⭐⭐	插图+描述+创建入口
错误层	组件错误边界	⭐⭐⭐⭐	组件崩溃时 fallback
高级组件	轮播组件	⭐⭐⭐	指示器/箭头/自动播放/触摸
高级组件	命令面板	⭐⭐⭐	Ctrl+K/搜索/键盘导航
高级组件	图片灯箱	⭐⭐	缩放/切换/关闭
高级组件	通知中心	⭐⭐⭐	未读/面板/已读/分类
高级组件	Cookie 同意	⭐⭐	接受/拒绝/详细选项
安全层	点击劫持防护	⭐⭐⭐	X-Frame-Options / frame-ancestors

填写说明：

优先级：⭐(低) ~ ⭐⭐⭐⭐⭐(高)，5 星为必须做到
验证方式：如何判断该检查项是否已实现
个人备注：留空供个人填写

前言

什么是技能颗粒度

在反反爬虫技术领域，我们将技术体系拆解为"基础层→环境层→行为层→持久层→验证层→架构层"六大层级，每个层级包含数十个可独立验证的原子化技术点。这种思路可以迁移到前端 UI 设计领域。

技能颗粒度 = 将设计决策拆解到最小可验证单元。

每个颗粒度检查点满足三个条件：

可独立验证 —— 明确知道"做到了"还是"没做到"
可独立描述 —— 能用一句话精确描述给 AI 或设计师
可独立实现 —— 不依赖其他未完成的检查点即可实现

为什么需要原子化

传统设计流程的痛点：

设计师说"做得好看一点" → AI 不知道具体要改什么
审查时说"这里不统一" → 没有标准判断什么叫统一
新页面开发时 → 每次都要重新想按钮该多大、间距该多宽

原子化后：

“实现按钮的 5 种变体、3 种尺寸、6 种状态” → AI 精确输出
“检查所有可交互元素是否有 hover 反馈” → 有明确验收标准
新页面 → 从检查清单中勾选需要的组件和样式

本文受众

使用 AI 辅助前端开发的工程师
前端设计师 / Design System 维护者
技术负责人 / 代码审查者
需要向前端传达设计需求的 PM

检查项层级全景

前端 UI 设计技能颗粒度
│
├── 排版层（Typography）
│ ├── 字体族
│ ├── 字号阶梯
│ ├── 行高 / 字重 / 字间距
│ ├── 标题层级
│ ├── 文本截断 / 对齐 / 装饰
│ ├── 中英文混排
│ └── 等宽数字 / CJK断行 / 选中样式
│
├── 颜色层（Color）
│ ├── 品牌色 / 语义色 / 中性色
│ ├── 文本色 / 背景色 / 边框色
│ ├── 状态色 / 交互反馈色
│ ├── 暗色模式映射
│ └── 对比度 / 色盲友好
│
├── 间距层（Spacing）
│ ├── 基准单位
│ ├── 间距阶梯
│ ├── 内间距 / 外间距
│ └── 响应式间距
│
├── 圆角层 + 阴影层（Border & Shadow）
│ ├── 圆角阶梯
│ ├── 阴影层级
│ └── 暗色模式适配
│
├── 布局层（Layout）
│ ├── 容器 / 栅格 / 断点
│ ├── 页面布局模式
│ ├── Flex / Grid 工具
│ ├── Z-index 体系
│ └── 安全区域
│
├── 组件层（Components）
│ ├── 按钮 / 输入 / 选择
│ ├── 卡片 / 弹窗 / 表格
│ ├── 标签页 / 导航
│ ├── 反馈组件
│ ├── 数据展示组件
│ └── 组件组合模式
│
├── 交互层（Interaction）
│ ├── 过渡时长 / 缓动曲线
│ ├── Hover / Active / Focus
│ ├── 拖拽 / 手势 / 快捷键
│ └── 加载状态 / 乐观更新
│
├── 响应式层（Responsive）
│ ├── 三端布局
│ ├── 触摸目标 / 字号缩放
│ ├── 组件响应式变形
│ └── 打印样式
│
├── 无障碍层（Accessibility）
│ ├── 语义化 / ARIA
│ ├── 键盘导航 / 焦点管理
│ ├── 对比度 / 颜色依赖
│ └── 减少动画 / 动态字体
│
├── 主题层（Theming）
│ ├── 亮 / 暗模式
│ ├── CSS 变量体系
│ ├── 品牌定制
│ └── 切换过渡
│
├── 动效层（Motion）
│ ├── 入场 / 退场动画
│ ├── 列表 / 页面过渡
│ ├── 微交互
│ └── reduced-motion
│
├── 图标层 + 图片层
│ ├── 图标集 / 尺寸 / 风格
│ ├── 懒加载 / 响应式
│ └── 占位 / 裁剪 / 优化
│
├── 表单层（Forms）
│ ├── 布局 / 标签 / 验证
│ ├── 错误提示 / 成功反馈
│ ├── 联动 / 进度 / 草稿
│ └── 提交状态
│
├── 内容层（Content）
│ ├── 标题层级 / 段落
│ ├── 链接 / 代码块
│ └── 富文本 / 可读性
│
├── 国际化层（i18n）
│ ├── RTL / 文字长度
│ ├── 日期 / 数字 / 货币
│ └── 字体回退
│
├── 性能层（Performance）
│ ├── Core Web Vitals
│ ├── 代码分割 / 预加载
│ └── 字体 / 图片 / 动画优化
│
└── 安全层（Security）
├── XSS / CSRF
├── 敏感信息遮蔽
└── 输入净化
│
├── 滚动与光标层（Scroll & Cursor）
│ ├── 平滑滚动 / 滚动捕捉
│ ├── 滚动阴影 / 进度指示
│ ├── 自定义滚动条
│ ├── 锁定背景滚动
│ ├── 光标类型（pointer/not-allowed/wait）
│ └── 选区 / 占位符样式
│
├── 错误与空状态层（Error & Empty）
│ ├── 404 / 500 / 网络错误
│ ├── 表单错误汇总
│ ├── 空列表 / 空搜索
│ ├── 图片加载失败
│ └── 组件错误边界
│
└── 高级组件层（Advanced Components）
├── 轮播（Carousel）
├── 命令面板（Command Palette）
├── 图片灯箱（Lightbox）
├── 通知中心
└── Cookie 同意横幅

一、排版层（Typography）

排版是 UI 设计的骨架。排版层检查项确保文字在页面上的呈现是系统化、一致、可读的。

#	检查项	验证标准	常见问题
T-01	字体族（font-family）	定义 primary（正文）、heading（标题）、mono（代码）、fallback 四组	未定义 fallback 导致系统字体混乱
T-02	字号阶梯（font-size）	定义 xs(12)/sm(14)/base(16)/lg(18)/xl(20)/2xl(24)/3xl(30)/4xl(36) 递进	随意使用 px 值，导致页面字号不统一
T-03	行高（line-height）	定义 tight(1.25)/normal(1.5)/relaxed(1.75)/loose(2)	正文行高过紧凑导致阅读困难
T-04	字重（font-weight）	定义 light(300)/normal(400)/medium(500)/semibold(600)/bold(700)	只用 normal 和 bold 两级，视觉层级不足
T-05	字间距（letter-spacing）	定义 tighter(-0.05em)/tight(-0.025em)/normal(0)/wide(0.025em)/wider(0.05em)/widest(0.1em)	大标题需要负字间距但未调整
T-06	标题层级 h1-h6	每级标题字号/字重/行高/间距都有明确定义，视觉递减	h3 比 h2 更大或跳过 h2 直接用 h3
T-07	正文排版	body 字号≥14px（中文≥16px），行高≥1.5，段间距一致	移动端字号小于 14px
T-08	辅助文本	small(12px)/caption(12px)/overline(12px uppercase) 有定义	辅助文字与正文区分不够明显
T-09	单行截断	overflow:hidden + text-overflow:ellipsis + white-space:nowrap	忘记设 width/max-width 导致截断不生效
T-10	多行截断	-webkit-line-clamp:N + display:-webkit-box + -webkit-box-orient:vertical	忘记设 overflow:hidden
T-11	文本对齐	left/center/right/justify 有对应工具类	justify 导致中文词间距异常
T-12	文本装饰	underline/strikethrough/overline 样式	链接下划线颜色与文字色不匹配
T-13	文本转换	uppercase/lowercase/capitalize 工具类	英文标题全大写但字间距未调整
T-14	中英文混排	中英文之间自动添加间距；标点避首尾（hanging-punctuation）	中英文紧贴不美观
T-15	连字符	hyphens:auto 在窄容器中启用	英文长单词溢出容器
T-16	段落间距	p + p 使用 margin-top 而非双重 margin	首段也带 margin-top 导致顶部空隙
T-17	代码文本	inline code 有独立字体族/背景色/圆角/内边距	inline code 背景色与代码块不一致
T-18	引用文本	blockquote 有左边框/缩进/背景色区分	引用块与正文视觉无区分
T-19	列表样式	ul/ol 有统一样式，列表项间距一致	列表符号位置与文字对齐不一致
T-20	文字颜色	text-primary/secondary/tertiary/disabled/inverse 有定义	灰色文字在暗色模式下不可见
T-21	等宽数字	font-variant-numeric: tabular-nums 用于数字对齐（表格/金额）	数字宽度不一导致列不对齐
T-22	CJK 断行	word-break: break-all / overflow-wrap: break-word / line-break: strict	中文长 URL 溢出容器
T-23	竖排文字	writing-mode: vertical-rl 用于中文竖排场景	无竖排支持
T-24	空白处理	white-space: normal/nowrap/pre/pre-wrap/pre-line 覆盖	代码/预格式文本折行异常
T-25	文字选中样式	::selection 定义背景色+文字色	选中文字为默认蓝色

二、颜色层（Color）

颜色层确保所有颜色决策是系统化的，而非随意取值。

#	检查项	验证标准	常见问题
C-01	品牌色	primary/secondary/accent 各含 50-950 共 11 个色阶	只有主色没有色阶，无法做 hover/active 变体
C-02	语义色	success(绿)/warning(黄)/error(红)/info(蓝) 各含色阶	warning 色在白底上对比度不足
C-03	中性色阶梯	gray-50/100/200/300/400/500/600/700/800/900/950 完整	灰色色阶跳跃不均匀
C-04	主文字色	text-primary(≈gray-900)	文字色纯黑(#000)对比过强
C-05	次文字色	text-secondary(≈gray-500)	次要文字过浅不可读
C-06	占位文字色	text-placeholder(≈gray-400)	placeholder 比正文还深
C-07	禁用文字色	text-disabled(≈gray-300)	禁用文字与正常文字区分不够
C-08	反色文字	text-inverse(白色/暗色上的亮色)	亮色文字在浅色背景上不可见
C-09	页面背景色	bg-page(≈gray-50/white)	纯白背景与卡片无区分度
C-10	卡片背景色	bg-card(white)	卡片与页面背景对比不够
C-11	遮罩背景色	bg-overlay(rgba(0,0,0,0.5))	遮罩过透明或过不透明
C-12	默认边框色	border-default(≈gray-200)	边框色过深显得粗重
C-13	悬浮边框色	border-hover(≈gray-300)	hover 时边框无变化
C-14	焦点边框色	border-focus(primary色)	focus 时边框色不够醒目
C-15	错误边框色	border-error(error色)	错误边框色与文本错误色不一致
C-16	链接色	link(≈primary)/link-hover/link-visited	已访问链接色未定义
C-17	Hover 背景色	hover 背景（≈primary-50/gray-50）	hover 变化太小感知不到
C-18	Active 背景色	active 背景（≈primary-100/gray-100）	active 与 hover 视觉无区别
C-19	Disabled 背景	disabled 背景（≈gray-100）	disabled 组件看起来还可点击
C-20	暗色模式映射	所有颜色有 dark: 变体	暗色模式下直接反色导致不协调
C-21	暗色中性色方向	dark 模式中性色阶反转（900→50）	暗色模式用了亮色模式的灰色
C-22	暗色背景	dark:bg-page(≈gray-900/950)	暗色背景纯黑刺眼
C-23	暗色表面	dark:bg-card(≈gray-800)	暗色卡片与背景对比不够
C-24	颜色对比度-正文	正文与背景对比度≥4.5:1（WCAG AA）	灰色文字在浅灰背景上对比不足
C-25	颜色对比度-大文本	大文本(≥18px/14px bold)对比度≥3:1	标题对比度不够
C-26	颜色对比度-UI元素	图标/边框/UI 组件对比度≥3:1	禁用状态对比度不足
C-27	非颜色传达信息	不仅靠颜色区分状态（加图标/文字/形状）	红绿颜色区分对色盲不友好
C-28	渐变色 token	定义品牌渐变（如 primary→accent）	渐变色随意取值
C-29	透明度 token	opacity-0/5/10/20/25/50/75/90/95/100	透明度取值随意
C-30	阴影色 token	shadow 使用语义色而非硬编码黑色	暗色模式阴影仍然用黑色

三、间距层（Spacing）

间距层确保页面呼吸感一致，所有间距值来自同一套系统。

#	检查项	验证标准	常见问题
S-01	基准单位	基于 4px 或 8px 网格	混用 3px/5px/7px 等非基准值
S-02	间距阶梯	0(0)/0.5(2)/1(4)/1.5(6)/2(8)/2.5(10)/3(12)/4(16)/5(20)/6(24)/8(32)/10(40)/12(48)/16(64)/20(80)/24(96)	缺少某些阶梯，被迫用非标准值
S-03	组件内间距（padding）	所有组件 padding 值来自间距阶梯	按钮和输入框内间距不匹配
S-04	组件外间距（margin）	margin 值来自间距阶梯	用 margin 微调位置而非布局
S-05	栅格间距（gap）	flex/grid gap 值 token 化	不同区域 gap 值不一致
S-06	响应式间距	小屏间距自动缩小	移动端和桌面端使用相同间距
S-07	区块间距	section 间距统一（如 64px/96px/128px）	不同页面区块间距不一致
S-08	容器内间距	页面容器 padding 水平（如 16px/24px）	内容贴边，无内间距
S-09	列表项间距	列表项间距统一	列表项间距比段落间距还大
S-10	负间距	支持负 margin 用于偏移/重叠	无负间距能力
S-11	视口相对间距	dvh/svh/lvh 单位用于全屏区域/hero 区域	移动端 vh 不准确
S-12	Clamp 流式间距	clamp(min, preferred, max) 平滑过渡间距	断点跳变而非平滑缩放
S-13	逻辑间距属性	margin-inline/margin-block/padding-inline/padding-block 替代物理属性	RTL 布局间距反向
S-14	间距密度变体	compact(密集数据 UI)/comfortable(营销页)/spacious(阅读) 三档	所有场景用同一密度
S-15	组件内微间距	icon-to-text gap / avatar-to-name gap / badge-to-text gap 统一	图标与文字间距随意
S-16	容器查询间距	@container 间距随容器宽度变化，非视口	侧边栏内间距不合理
S-17	垂直韵律	所有纵向间距为基准单位的整数倍，保持韵律	间距值不规律
S-18	间距语义命名	spacing-xs(4)/sm(8)/md(16)/lg(24)/xl(32)/2xl(48) 语义别名	只有数字索引无语义名
S-19	自动外边距	margin:auto 作为剩余空间分配策略	flex/grid 子项间距不均匀
S-20	间距比例系数	响应式间距按比例缩放（sm=75% of lg）	各断点间距独立设置无规律

四、圆角层 + 阴影层（Border & Shadow）

#	检查项	验证标准	常见问题
R-01	圆角阶梯	none(0)/sm(2)/md(6)/lg(8)/xl(12)/2xl(16)/3xl(24)/full(9999px)	圆角值随意取
R-02	按钮圆角	与输入框圆角匹配	按钮和输入框圆角不一致
R-03	卡片圆角	lg 或 xl 级别	卡片圆角过小或过大
R-04	弹窗圆角	lg 或 xl 级别	弹窗圆角与卡片不匹配
R-05	头像圆角	full(圆形) 或 lg(圆角矩形)	头像列表中圆形方形混用
R-06	Toast 圆角	md 级别	Toast 圆角与整体风格不搭
R-07	阴影阶梯	sm/md/lg/xl/2xl/inner	只有 none 和一个大阴影
R-08	组件阴影一致性	同层级组件用同一级阴影	卡片阴影深浅不一
R-09	悬浮阴影变化	hover 时阴影从 sm→md 或 md→lg	hover 无阴影变化
R-10	暗色模式阴影	dark 模式阴影更亮（使用深灰而非纯黑）	暗色模式阴影不可见
R-11	边框宽度	定义 border-width(1px/2px) token	边框粗细不统一
R-12	边框样式	solid/dashed/dotted 有明确使用场景	分割线样式混用
R-13	Outline vs Ring	outline（不影响布局）用于 focus；ring（box-shadow）用于强调	outline 和 ring 混用
R-14	Ring 宽度/偏移 token	ring-width(1px/2px/3px) + ring-offset(0/2px/4px)	ring 宽度随意
R-15	分割线变体	厚度(1px)/颜色token/上下margin/变体(solid/dashed/with-text)	分割线样式不统一
R-16	单侧圆角	rounded-t-lg / rounded-b-lg 等单侧圆角可用	只能四角同时设置
R-17	边框 vs 阴影策略	明确何时用边框/何时用阴影/何时用背景色区分	卡片边框和阴影混用无规律
R-18	内阴影场景	box-shadow: inset 用于内凹输入框/凹陷容器	内阴影滥用
R-19	各状态边框色集	default/hover/focus/error/disabled/active 边框色作为完整集	只定义了默认边框色
R-20	底部/单侧边框	border-b / border-t / border-l / border-r 用于分割场景	全边框造成视觉噪音

五、布局层（Layout）

#	检查项	验证标准	常见问题
L-01	容器最大宽度	定义 max-w-screen-sm/md/lg/xl/2xl	内容无最大宽度限制
L-02	容器居中	mx-auto 居中	容器不居中
L-03	响应式断点	sm(640)/md(768)/lg(1024)/xl(1280)/2xl(1536)	断点值随意定义
L-04	栅格列数	12 列系统	列数不统一
L-05	栅格间距	gutter token 化	不同页面栅格间距不一致
L-06	页面布局模式	header+main+footer / header+sidebar+main+footer	布局结构不统一
L-07	内容区模式	full-width / contained(1280px) / narrow(768px)	文章内容区过宽
L-08	Flex 工具	direction/wrap/justify/align 组合覆盖	flex 容器子项不换行导致溢出
L-09	Grid 工具	template-columns/rows/areas 覆盖	不必要的嵌套 flex
L-10	水平居中	flex/grid margin:auto 三种方案	居中方式不一致
L-11	粘性头部	header sticky 行为	滚动后头部消失
L-12	粘性侧边栏	sidebar sticky 行为	侧边栏不跟随滚动
L-13	Z-index 体系	dropdown(1000)/sticky(1100)/modal(1200)/popover(1300)/tooltip(1400)/notification(1500)	z-index 随意取值导致层叠混乱
L-14	内容溢出	overflow-hidden/scroll/auto 有明确策略	内容溢出破坏布局
L-15	最小高度	min-h-screen / min-h-特定值	页面内容少时 footer 悬空
L-16	安全区域	safe-area-inset-top/right/bottom/left	iOS 刘海屏遮挡内容
L-17	等高列	grid 自动等高 / flex stretch	多列不等高
L-18	宽高比	aspect-ratio 用于媒体容器/卡片/占位防 CLS	图片加载后布局跳动
L-19	容器查询	@container 查询实现组件级响应式	组件只能跟随视口断点
L-20	absolute 定位模式	绝对定位元素有明确包含块(relative 父)	绝对定位元素跑出预期位置
L-21	fixed 定位模式	fixed 元素考虑移动端浏览器 chrome + dvh	fixed 导航被地址栏遮挡
L-22	sticky 全面场景	表头/sidebar/分组标题 sticky + top 偏移量包含 fixed header	sticky 元素被 fixed header 遮挡
L-23	Subgrid	子网格对齐父级 grid 轨道	嵌套 grid 列不对齐
L-24	逻辑布局属性	inline-size/block-size 替代 width/height	RTL 下布局不翻转
L-25	多列布局	column-count/column-width 用于文本密集内容	长列表无分列浪费空间
L-26	内容可见性	content-visibility: auto 用于屏外重渲染区域	屏外大量 DOM 影响渲染
L-27	容器宽度变体	narrow(768px)/content(1024px)/wide(1280px)/full	所有内容用同一宽度
L-28	孤行/寡行控制	widows/orphans CSS 属性用于打印/分页	打印时段落末尾只有一行
L-29	滚动驱动布局	scroll-timeline 用于滚动关联效果	用 JS 监听 scroll 事件

六、组件层（Components）

6.1 按钮（Button）

#	检查项	验证标准	常见问题
BTN-01	主要按钮	primary 填充色 + 白色文字	主色文字色对比度不足
BTN-02	次要按钮	secondary 填充色 / outline 边框按钮	次要按钮与主要按钮区分不够
BTN-03	虚线按钮	dashed 边框，用于添加场景	与 outline 按钮区分不清
BTN-04	幽灵按钮	ghost 无边框无背景	幽灵按钮看不出来可点击
BTN-05	危险按钮	destructive 红色系	危险操作用错按钮类型
BTN-06	链接按钮	link 无边框无背景，文字色	与链接混淆
BTN-07	小按钮	sm 高度/字号/内间距	尺寸缩放不协调
BTN-08	中按钮	md 高度/字号/内间距（默认）	无默认尺寸概念
BTN-09	大按钮	lg 高度/字号/内间距	大按钮在移动端过宽
BTN-10	Hover 状态	背景色加深/边框色变化	无 hover 反馈
BTN-11	Active 状态	背景色更深/轻微缩放(scale(0.98))	active 与 hover 无区别
BTN-12	Focus 状态	focus-visible 外环/outline	focus 无视觉指示
BTN-13	Disabled 状态	降透明度/灰化/取消 pointer	disabled 仍可点击
BTN-14	Loading 状态	spinner + 文字变灰 + 禁止点击	loading 状态文字仍为正常色
BTN-15	左图标	icon + 文字，间距一致	图标与文字间距过大
BTN-16	右图标	文字 + icon（如箭头）	图标位置不统一
BTN-17	纯图标按钮	只有图标，有 aria-label	纯图标无文字说明
BTN-18	全宽按钮	w-full 模式	桌面端全宽按钮过宽
BTN-19	按钮组	水平排列，相连边共享边框	按钮间距不统一

6.2 输入框（Input）

#	检查项	验证标准	常见问题
INP-01	文本输入	type=text 默认样式	输入框高度与按钮不匹配
INP-02	密码输入	type=password + 切换按钮	密码切换图标位置不统一
INP-03	搜索输入	type=search + 搜索图标 + 清除	清除按钮缺失
INP-04	数字输入	type=number 隐藏 spinner / 步进按钮	数字输入框 spinner 样式不一致
INP-05	URL/邮箱	type=url/email 验证	移动端未弹出对应键盘
INP-06	小输入框	sm 高度/字号	小输入框内间距过小
INP-07	大输入框	lg 高度/字号	大输入框字号过大
INP-08	Hover 状态	边框色变化	输入框无 hover 效果
INP-09	Focus 状态	边框色变 primary + ring	focus 时边框与 ring 颜色冲突
INP-10	Error 状态	边框色变 error + 错误提示文字	错误态边框色不够醒目
INP-11	Disabled 状态	背景/文字灰化 + 禁止交互	disabled 态文字色太浅
INP-12	Readonly 状态	与 disabled 区分（可选中不可编辑）	readonly 和 disabled 视觉相同
INP-13	前缀图标	左侧图标 + 内间距偏移	前缀图标与文字重叠
INP-14	后缀图标	右侧图标 + 内间距偏移	后缀图标与文字重叠
INP-15	前缀文字	左侧文字标签（如 $, https://）	前缀文字背景色与输入框不协调
INP-16	后缀文字	右侧文字标签（如 .com, 单位）	后缀文字不可见
INP-17	清除按钮	有内容时显示 ×，点击清空	清除按钮一直显示
INP-18	字符计数	maxlength 限制 + 倒计显示	超出 maxlength 无提示
INP-19	Textarea	可调高度/固定高度/自动高度	resize 不受控破坏布局
INP-20	浮动标签	输入时标签上浮动画	浮动标签遮挡输入内容

6.3 选择类控件

#	检查项	验证标准	常见问题
SEL-01	Select 下拉	触发器/下拉面板/选项/选中态/搜索	下拉面板被其他元素遮挡
SEL-02	多选 Select	选中项标签/清除/全选	选中过多项时溢出
SEL-03	Checkbox	选中/未选/半选/禁用	半选状态缺失
SEL-04	Radio	选中/未选/禁用/按钮样式	radio 无法键盘操作
SEL-05	Switch	开/关/禁用/加载/文字标签	switch 切换无动画
SEL-06	Slider	单值/范围/刻度标记/tooltip	步进值不合理
SEL-07	日期选择	日期/时间/范围选择	日期格式不统一
SEL-08	文件上传	拖拽区/文件列表/进度/预览	大文件无进度反馈
SEL-09	级联选择	多级联动/异步加载	级联选项加载无 loading
SEL-10	树形选择	树形数据/勾选/搜索	树层级过多时不方便

6.4 卡片（Card）

#	检查项	验证标准	常见问题
CRD-01	基础卡片	边框/圆角/内间距/背景色	卡片内间距不一致
CRD-02	Header	标题/操作区/分隔线	header 操作区对齐不统一
CRD-03	Body	内容区/自动 padding	内容贴边
CRD-04	Footer	操作按钮/分隔线	footer 按钮排列不统一
CRD-05	封面图	顶部图片 + aspect-ratio	图片比例不一致
CRD-06	Hover 效果	阴影增强/轻微上浮	无 hover 反馈
CRD-07	可点击	整卡片可点击 + cursor-pointer	可点击卡片无视觉提示

6.5 弹窗（Dialog/Modal）

#	检查项	验证标准	常见问题
MDL-01	遮罩层	半透明黑色 + 点击关闭(可配置)	遮罩过暗/过亮
MDL-02	弹窗尺寸	sm/md/lg/xl/full	弹窗在移动端溢出屏幕
MDL-03	Header	标题 + 关闭按钮	关闭按钮位置不统一
MDL-04	Body 滚动	弹窗内容可滚，背景不滚	弹窗打开时背景也在滚
MDL-05	Footer	操作按钮排列（确认/取消）	确认和取消按钮位置不统一
MDL-06	进场动画	fade+scale/fade+slide	无动画突然出现
MDL-07	退场动画	对应的退出动画	关闭时无动画
MDL-08	ESC 关闭	按 Escape 关闭弹窗	无法键盘关闭
MDL-09	焦点管理	打开时聚焦弹窗内首个可聚焦元素	焦点仍在背景元素上
MDL-10	确认对话框	危险操作二次确认/确认按钮醒目	删除操作无二次确认

6.6 抽屉（Drawer）

#	检查项	验证标准	常见问题
DRW-01	方向	left/right/top/bottom 四个方向	Drawer 只支持一个方向
DRW-02	尺寸	sm(300px)/md(400px)/lg(540px)/full	移动端 Drawer 太窄或太宽
DRW-03	遮罩层	半透明背景 + 可配置点击关闭	遮罩全黑
DRW-04	关闭方式	X 按钮/ESC 键/遮罩点击/滑动手势	只能点 X 关闭
DRW-05	嵌套堆叠	多层 Drawer z-index 递增	多层 Drawer 层叠混乱
DRW-06	表单场景	Drawer 内表单验证+提交+未保存提示	关闭丢失已填数据
DRW-07	焦点陷阱	焦点在 Drawer 内循环	Tab 跳到背景
DRW-08	背景锁定	body overflow:hidden	Drawer 打开背景还在滚

6.7 气泡卡片（Popover）

#	检查项	验证标准	常见问题
POP-01	自动翻转	视口边缘时自动翻转到对面	Popover 被截断
POP-02	触发模式	click / hover / focus 可配置	hover 误触发
POP-03	表单内容	Popover 内表单元素可交互	Popover 内输入框失焦关闭
POP-04	箭头	指向触发元素的箭头，边缘碰撞时隐藏	箭头位置不准
POP-05	关闭行为	点击外部/ESC/选择后关闭可配置	点击内部也关闭
POP-06	宽度	匹配触发元素或自定义 min/max 宽度	Popover 过窄内容截断

#	检查项	验证标准	常见问题
MNU-01	菜单项变体	default/destructive/disabled	删除操作和普通操作视觉无区分
MNU-02	菜单项图标	前置图标支持	图标与文字间距不统一
MNU-03	快捷键显示	右对齐显示快捷键（如 “Ctrl+C”）	快捷键显示不整齐
MNU-04	勾选菜单项	checkbox/radio 菜单项 + 勾选图标	选中态不明显
MNU-05	分隔线	分组间水平分隔线	分隔线颜色过深
MNU-06	分组标签	非交互式分组标题	无法区分标签和菜单项
MNU-07	子菜单	嵌套子菜单 + 箭头指示	子菜单定位不准
MNU-08	键盘导航	上下箭头/Enter/Escape/首字母导航	无法键盘操作菜单

6.9 表格（Table）

#	检查项	验证标准	常见问题
TBL-01	表头样式	背景/字号/字重/边框区分	表头与数据行视觉无区分
TBL-02	行 hover	鼠标悬浮行高亮	无行 hover 效果
TBL-03	斑马纹	奇偶行不同背景色	斑马纹颜色对比过强
TBL-04	列排序	点击表头排序/排序图标	排序方向图标不清晰
TBL-05	列筛选	列头下拉筛选/筛选标记	筛选后无清除方式
TBL-06	分页	页码/条数/总数/跳转	分页条数选项不合理
TBL-07	固定表头	滚动时表头固定	长表滚动时看不到列名
TBL-08	固定列	首列/末列固定	固定列与滚动列无阴影分隔
TBL-09	行选择	checkbox 单选/多选/全选	全选含未加载的数据
TBL-10	空状态	无数据时插图+提示+操作	空状态只显示"暂无数据"
TBL-11	加载状态	spinner 覆盖/骨架屏	加载时布局跳动
TBL-12	行展开	点击展开详情行	展开图标不明显
TBL-13	虚拟滚动	大数据量时只渲染可视区域	万级数据表格卡顿
TBL-14	列宽	可拖拽调整/最小宽度	列宽被内容撑开

6.10 标签页（Tabs）

#	检查项	验证标准	常见问题
TAB-01	下划线变体	底部横线指示当前 tab	下划线与 tab 文字不对齐
TAB-02	卡片变体	tab 为卡片样式	选中和未选中卡片区分不够
TAB-03	胶囊变体	tab 为圆角胶囊样式	胶囊内文字间距过大
TAB-04	滚动处理	tab 过多时横向滚动+箭头	tab 被截断无滚动
TAB-05	懒加载	非活跃 tab 内容不渲染	所有 tab 内容一次加载
TAB-06	键盘导航	左右箭头切换 tab	无法键盘操作 tab

6.11 导航组件

#	检查项	验证标准	常见问题
NAV-01	顶部导航	logo/菜单项/用户区水平排列	菜单项过多时溢出
NAV-02	当前页高亮	当前页菜单项视觉高亮	当前页无高亮
NAV-03	下拉菜单	hover/click 触发/嵌套/键盘导航	下拉菜单定位不准
NAV-04	侧边导航	可折叠/子菜单/高亮当前	子菜单展开动画卡顿
NAV-05	面包屑	层级展示/分隔符/可点击/截断	层级过深时溢出
NAV-06	步骤条	水平/垂直/已完成/当前/待做/错误	步骤状态颜色不直观
NAV-07	移动端导航	底部 tab 栏/汉堡菜单	移动端导航项过多
NAV-08	返回顶部	滚动一定距离后出现/平滑滚动	返回顶部按钮遮挡内容

6.12 反馈组件

#	检查项	验证标准	常见问题
FB-01	Toast 类型	success/error/warning/info 各有图标+颜色	所有 toast 同一颜色
FB-02	Toast 位置	top-right/top-center/bottom-right 可配置	Toast 遮挡操作区
FB-03	Toast 自动关闭	默认 3-5s 自动消失/可配置时长	Toast 不消失或瞬间消失
FB-04	Toast 可关闭	右侧关闭按钮/悬浮显示	无手动关闭方式
FB-05	Toast 堆叠	多条 toast 垂直排列/最大数量	新 toast 覆盖旧 toast
FB-06	Alert 类型	success/warning/error/info	Alert 无图标
FB-07	Alert 可关闭	关闭按钮/关闭回调	Alert 无法关闭
FB-08	Alert Banner	顶部全宽公告条	Banner 与导航层级冲突
FB-09	进度条-确定	百分比进度/颜色/尺寸	进度条无文字百分比
FB-10	进度条-不确定	动画条纹/脉冲	加载中无反馈
FB-11	环形进度	圆形进度环	环形进度无百分比文字
FB-12	Spinner	尺寸(sm/md/lg)/颜色/全局	Spinner 颜色与主题不搭
FB-13	骨架屏-形状	circle(头像)/rectangle(卡片)/text(段落)	骨架屏与实际布局差异大
FB-14	骨架屏-动画	pulse(脉冲)/wave(波浪)	骨架屏无动画
FB-15	空状态	插图+标题+描述+操作按钮	只显示文字"暂无数据"
FB-16	结果页	成功(绿)/失败(红)/处理中(黄) 状态	操作完成后无反馈页

6.13 数据展示组件

#	检查项	验证标准	常见问题
DD-01	Badge 圆点	小圆点未读指示	圆点太小看不见
DD-02	Badge 数字	数字/最大数(99+)	数字溢出
DD-03	Badge 文字	文字标签	文字过长
DD-04	Tag 颜色	预设色+自定义色	tag 颜色过多不统一
DD-05	Tag 可关闭	关闭按钮/关闭回调	无法删除 tag
DD-06	Tag 可选中	click 切换选中态	选中态不明显
DD-07	Avatar 尺寸	xs(24)/sm(32)/md(40)/lg(56)/xl(80)	列表中头像大小不一致
DD-08	Avatar fallback	无图时显示文字/图标	无图时显示空白
DD-09	Avatar 状态点	在线/忙碌/离线绿/黄/灰点	状态点位置不统一
DD-10	Avatar 分组	重叠排列/溢出+N	重叠过多看不到
DD-11	Tooltip 方向	top/right/bottom/left/auto	Tooltip 被屏幕边缘截断
DD-12	Tooltip 延迟	显示延迟(300ms)/隐藏延迟(100ms)	Tooltip 立即出现干扰
DD-13	Tooltip 箭头	有/无箭头	箭头指向不准
DD-14	Collapse 手风琴	同时只展开一个	多个展开时内容过多
DD-15	Collapse 动画	展开/收起高度动画	无动画突然出现
DD-16	Tree 展开/折叠	点击节点展开子级	大树展开卡顿
DD-17	Tree 勾选	checkbox 勾选+半选+级联	级联勾选逻辑错误
DD-18	Timeline 布局	左右交替/单侧/自定义节点	时间线对齐错乱
DD-19	Statistic 数值	大数字+趋势箭头+前后缀	数字格式化不一致
DD-20	Divider	水平/垂直/带文字	分割线颜色过深

6.14 组件组合模式（Composition Patterns）

组件单独检查还不够，组合使用时往往暴露设计缺陷。

#	检查项	验证标准	常见问题
CP-01	表单+输入+验证联动	输入→blur 验证→错误显示→修正→成功清除	错误修正后红色不消失
CP-02	表单+提交+反馈	提交→loading→成功 toast/跳转/失败保留	提交成功/失败无反馈
CP-03	表格+筛选+分页联动	筛选→重置分页→显示结果数	筛选后分页未重置
CP-04	表格+批量操作+确认	多选→批量按钮→二次确认→loading→刷新	批量删除无确认
CP-05	搜索+防抖+结果+空态	输入→防抖→loading→结果/空态	搜索中无 loading 指示
CP-06	导航+面包屑+页面标题	三者信息一致	面包屑与页面标题不匹配
CP-07	侧边栏+内容+响应式	大屏展开→小屏折叠/抽屉	侧边栏在移动端无法收起
CP-08	弹窗+表单+验证+提交	弹窗内表单完整验证流程	弹窗内表单无验证
CP-09	列表+排序+筛选+空态	筛选后无结果有空态提示	筛选无结果空白
CP-10	头像+名字+操作菜单	用户信息卡片交互完整	操作菜单被遮挡
CP-11	标签页+内容+缓存	切换 tab 不丢失已填数据	切 tab 数据丢失
CP-12	文件上传+拖拽+进度+预览	拖入→上传中→完成→可预览	上传失败无重试
CP-13	下拉菜单+搜索+异步	搜索→请求→loading→结果	搜索 loading 无反馈
CP-14	树形+勾选+级联+搜索	搜索→高亮匹配→勾选级联	搜索后勾选混乱
CP-15	日期范围+快捷选项	近7天/本月/自定义+联动	快捷选项不更新日期框

七、交互层（Interaction）

#	检查项	验证标准	常见问题
IX-01	过渡时长体系	instant(0)/fast(100ms)/normal(150ms)/slow(300ms)/slower(500ms)	所有过渡用同一个时长
IX-02	缓动曲线体系	default(ease)/in(ease-in)/out(ease-out)/in-out(ease-in-out)/spring(cubic-bezier)	用 linear 导致动画生硬
IX-03	全局 Hover 要求	所有可交互元素有 hover 反馈（颜色/阴影/下划线）	纯文字链接无 hover
IX-04	全局 Active 要求	按下有视觉反馈（加深/缩放）	无 active 反馈
IX-05	Focus Visible	键盘聚焦时显示 focus ring，鼠标点击不显示	focus ring 始终显示干扰视觉
IX-06	Focus Ring 样式	2px offset ring + primary 色	focus ring 与元素重叠
IX-07	弹窗焦点陷阱	Tab 在弹窗内循环，不跳到背景	Tab 可以跳到弹窗外
IX-08	拖拽视觉反馈	拖起时半透明/放区域高亮/排序占位线	拖拽无视觉反馈
IX-09	滑动手势	左滑删除/右滑更多（移动端）	滑动与滚动冲突
IX-10	长按手势	长按触发上下文菜单/预览	无长按操作提示
IX-11	右键菜单	自定义 context menu	与浏览器默认右键菜单冲突
IX-12	全局快捷键	Ctrl+K 搜索/Ctrl+S 保存等	快捷键与浏览器冲突
IX-13	搜索防抖	输入 300ms 后才触发搜索	每次按键都请求
IX-14	滚动节流	scroll 事件节流(16ms)	滚动回调卡顿
IX-15	Resize 防抖	window resize 事件防抖(150ms)	每帧触发 resize 回调
IX-16	乐观更新	点赞/收藏立即反馈+后台同步	等待网络返回才反馈
IX-17	撤销/重做	Ctrl+Z/Ctrl+Y 操作历史	无法撤销误操作
IX-18	渐进式加载	图片懒加载/列表无限滚动/组件 lazy	首屏加载过多内容
IX-19	网络状态感知	离线提示/重连恢复/请求重试	网络断开无提示
IX-20	剪贴板操作	复制/粘贴/剪切反馈	复制后无"已复制"提示

八、响应式层（Responsive）

#	检查项	验证标准	常见问题
RP-01	移动端布局	sm 以下单列布局	移动端仍有多列
RP-02	平板布局	md 双列/侧边栏折叠	平板端布局与手机相同
RP-03	桌面布局	lg+ 多列/侧边栏展开	桌面端浪费屏幕空间
RP-04	触摸目标	所有可点击元素≥44×44px	文字链接点击区域太小
RP-05	移动端字号	正文≥16px，标题适当缩小	移动端字号与桌面相同
RP-06	移动端间距	padding/margin 缩小	移动端间距与桌面相同
RP-07	响应式图片	srcset + sizes 属性	所有尺寸加载同一张大图
RP-08	导航变形	桌面水平导航→移动汉堡/底部 tab	移动端导航项溢出
RP-09	表格响应式	列隐藏/卡片化/横向滚动	移动端表格溢出
RP-10	弹窗响应式	移动端全屏/drawer 替代 modal	modal 在移动端太小
RP-11	横竖屏适配	orientation 变化布局调整	横屏布局错乱
RP-12	打印样式	@media print 隐藏导航/footer/背景	打印时内容不可读

九、无障碍层（Accessibility）

#	检查项	验证标准	常见问题
A11Y-01	语义化标签	header/nav/main/section/article/footer/aside	全用 div
A11Y-02	标题层级	h1(1个)→h2→h3 不跳级	h1 直接跳到 h4
A11Y-03	图片 alt	所有 img 有描述性 alt，装饰图 alt=""	所有图片 alt 都一样
A11Y-04	aria-label	无文字的按钮/链接有 aria-label	图标按钮无文字说明
A11Y-05	aria-describedby	表单字段关联帮助文本/错误提示	错误提示屏幕阅读器读不到
A11Y-06	aria-live	动态内容更新区域用 aria-live=“polite”/“assertive”	toast 消息屏幕阅读器不播报
A11Y-07	aria-expanded	可展开元素标注展开状态	下拉菜单状态不可感知
A11Y-08	aria-selected	选中项标注选中状态	tab 选中状态不可感知
A11Y-09	aria-hidden	装饰性图标/元素 aria-hidden=“true”	装饰图标被屏幕阅读器读出
A11Y-10	role 属性	自定义组件标注正确 role	div 当按钮用无 role=“button”
A11Y-11	键盘可达	所有交互元素 Tab 可达	自定义组件无法 Tab 到
A11Y-12	键盘可操作	Tab 聚焦后 Enter/Space 可激活	焦点到了但无法操作
A11Y-13	Tab 顺序	tabindex 逻辑顺序，不乱序	tabindex>0 导致顺序混乱
A11Y-14	skip-to-content	页面首个 Tab 焦点为跳过导航链接	无法跳过导航到内容
A11Y-15	Focus visible	:focus-visible 有明确样式	focus 样式不明显
A11Y-16	Focus trap	弹窗内 Tab 不外溢	弹窗中 Tab 跳到背景
A11Y-17	Focus return	弹窗关闭后焦点回到触发元素	关闭弹窗后焦点丢失
A11Y-18	sr-only	视觉隐藏但屏幕阅读器可读的文本	信息只通过视觉传达
A11Y-19	颜色对比度	正文≥4.5:1 / 大文本≥3:1 / UI 元素≥3:1	灰色文字对比度不足
A11Y-20	非颜色传达	状态不只靠颜色（加图标/文字/形状）	只用红色标错误
A11Y-21	reduced-motion	prefers-reduced-motion:reduce 时关闭动画	动画无法关闭
A11Y-22	high-contrast	prefers-contrast:more 时增强对比	高对比模式不适配
A11Y-23	动态字号	使用 rem 单位支持浏览器字号设置	全用 px 不跟随系统
A11Y-24	表单标签	label 与 input 关联(for/id 或嵌套)	label 和 input 未关联
A11Y-25	必填标识	aria-required=“true” + 视觉标记	只用红色星号标必填

十、主题层（Theming）

#	检查项	验证标准	常见问题
TH-01	CSS 变量体系	所有设计值用 var(–xxx) 引用	硬编码颜色/间距值
TH-02	亮色主题 token	–color-primary/… 等完整定义	亮色下部分颜色未定义
TH-03	暗色主题 token	.dark 下覆盖所有 CSS 变量	暗色下部分颜色未覆盖
TH-04	主题切换器	手动切换/跟随系统/记住偏好	无切换入口
TH-05	主题过渡	切换时 color-scheme + transition 平滑	切换时闪烁
TH-06	FOUC 防止	页面加载时即应用主题(不闪烁)	页面先亮后暗闪烁
TH-07	图片适配	暗色模式下降低图片亮度	暗色下白色图片刺眼
TH-08	第三方嵌入	iframe/嵌入组件跟随主题	嵌入组件始终亮色
TH-09	品牌定制	覆盖 CSS 变量即可换肤	换肤需要改源码
TH-10	主题预览	设置页可实时预览主题效果	保存后才能看到效果

十一、动效层（Motion）

#	检查项	验证标准	常见问题
MO-01	入场-fade	opacity: 0→1	淡入过慢影响体验
MO-02	入场-slide	translateY/X: offset→0	滑入距离过大
MO-03	入场-scale	scale: 0.95→1	缩放比例过大
MO-04	入场-expand	height: 0→auto（动画）	展开动画卡顿
MO-05	退场动画	入场的反向	退场比入场还慢
MO-06	列表 stagger	列表项依次入场(每项延迟 50ms)	所有项同时出现
MO-07	页面过渡	路由切换 fade/slide 过渡	页面切换无过渡
MO-08	弹窗进入	fade+scale(0.95→1)	弹窗突然出现
MO-09	弹窗退出	fade+scale(1→0.95)	弹窗突然消失
MO-10	Drawer 滑入	translateX/Y 从屏幕外滑入	Drawer 无动画
MO-11	拖拽占位	拖拽时原位置留占位阴影	拖起后原位无反馈
MO-12	数值动画	数字递增/递减动画(如金额)	数字直接跳变
MO-13	微交互-点赞	点击后缩放弹跳 + 图标变化	点赞无动效反馈
MO-14	微交互-勾选	checkmark 绘制动画	勾选无反馈
MO-15	微交互-开关	switch 滑块移动动画	开关直接切换无过渡
MO-16	Spinner	旋转/脉冲/骨架屏动画	Spinner 不转
MO-17	减少动画	prefers-reduced-motion 下禁用所有动画	强制动画无法关闭
MO-18	Spring 物理动画	弹性缓动(非 cubic-bezier)用于自然感觉的交互	动画感觉机械
MO-19	共享元素过渡	缩略图→全屏图/列表项→详情页形变过渡	页面切换生硬
MO-20	View Transitions API	document.startViewTransition() SPA 页面过渡	每次路由跳转无动画
MO-21	滚动驱动动画	animation-timeline: scroll() 滚动关联效果(视差/揭示)	用 JS 监听 scroll
MO-22	动效 token 体系	duration-fast/normal/slow + ease-default/in/out/spring	动效参数散落各处
MO-23	动画编排	stagger 延迟/并行序列/顺序链可配置	动画无法编排
MO-24	Tooltip 入场	从触发点 scale + fade 入场	Tooltip 突然出现
MO-25	退场动画生命周期	DOM 移除前播放退场动画	元素直接消失
MO-26	性能预算	只动画 transform + opacity；will-change 谨慎使用	动画触发 layout/paint
MO-27	Skeleton shimmer	骨架屏使用 CSS shimmer/pulse 动画	骨架屏无动画
MO-28	Switch 弹性动画	开关切换滑块有弹性过冲效果	开关直接跳到对侧
MO-29	用户可控动画	设置中有独立开关控制动画，不依赖系统偏好	无法单独关闭动画

十二、图标层 + 图片层

#	检查项	验证标准	常见问题
IC-01	图标集统一	全站使用同一图标集(Lucide/Heroicons 等)	混用多个图标集
IC-02	图标尺寸阶梯	xs(12)/sm(16)/md(20)/lg(24)/xl(32)	图标大小随意取值
IC-03	图标线条粗细	stroke-width 统一(1.5px 或 2px)	同页面图标粗细不一
IC-04	图标颜色	默认继承文字色/currentColor	图标颜色硬编码
IC-05	图标+文字对齐	垂直居中(gap 间距一致)	图标与文字未对齐
IC-06	纯图标按钮热区	padding 扩大点击区域≥44px	图标按钮点击区域太小
IC-07	暗色模式图标	SVG fill/stroke 跟随主题	暗色下图标不可见
IC-08	自定义图标风格	与系统图标集风格一致	自定义图标格格不入
IC-09	图片占位符	加载中:模糊缩略图/skeleton；加载失败:错误图	图片加载中空白
IC-10	图片懒加载	loading=“lazy” 或 IntersectionObserver	所有图片首屏加载
IC-11	响应式图片	srcset + sizes 提供多分辨率	只加载一种尺寸
IC-12	宽高比锁定	aspect-ratio 预留空间	图片加载后布局跳动(CLS)
IC-13	图片裁剪模式	object-cover/contain/fill 明确规范	图片变形/留白
IC-14	图片格式优化	WebP/AVIF 优先 + JPG fallback	全用 JPG/PNG
IC-15	图片压缩	质量 75-85% 平衡体积和质量	上传原图未压缩

十三、表单层（Forms）

#	检查项	验证标准	常见问题
FM-01	垂直布局	label 在上，input 在下（默认）	label 和 input 不在同一行
FM-02	水平布局	label 在左，input 在右，label 右对齐	label 宽度不一致
FM-03	内联布局	所有字段水平排列	移动端内联布局溢出
FM-04	Label 必填标记	红色 * 或 (必填) 文字	必填标记位置不统一
FM-05	Label 可选标记	(可选) 灰色文字	全标必填不如标可选
FM-06	帮助文本	字段下方灰色小字说明	说明文字与错误提示混淆
FM-07	验证时机-blur	离开字段时验证	填写时就报错
FM-08	验证时机-submit	提交时统一验证	两种时机混用
FM-09	错误提示-位置	字段正下方	错误提示离字段太远
FM-10	错误提示-样式	error 色 + 图标 + 文字	只有红色边框无文字
FM-11	错误提示-聚焦	点击错误提示聚焦到对应字段	无法从错误定位到字段
FM-12	成功状态	绿色边框 + ✓ 图标	填写正确无反馈
FM-13	字段分组	fieldset + legend / 分组标题 + 分割线	表单过长无分组
FM-14	字段依赖	A 选值后 B 显隐/可选值变化	联动不及时
FM-15	多步表单	步骤指示 + 上一步/下一步	无法回到上一步
FM-16	草稿保存	自动/手动保存表单进度	填了一半意外丢失
FM-17	提交 loading	按钮 loading + 禁止重复点击	重复点击提交多次
FM-18	提交成功	toast/跳转结果页	提交后无反馈
FM-19	提交失败	错误提示 + 保留已填数据	提交失败数据丢失
FM-20	密码强度	强度条 + 规则列表实时反馈	不告知密码要求
FM-21	自动保存	localStorage 自动保存表单进度 + 恢复提示	填写一半刷新丢失
FM-22	条件字段	字段显隐依赖其他字段值 + 动画 + 排除验证	隐藏字段仍被验证
FM-23	重复字段组	“添加更多"模式 + 增删按钮 + 索引管理	多个地址无法添加
FM-24	密码要求列表	密码字段旁显示要求清单 + 实时勾选	不告知密码规则
FM-25	密码确认	确认密码实时匹配提示	提交时才发现不匹配
FM-26	未保存提示	表单修改后离开页面弹出确认	数据静默丢失
FM-27	表单重置	重置按钮 + 有修改时二次确认	重置无法撤销
FM-28	Blur 格式化	电话/货币/日期输入失焦后自动格式化	用户输入格式混乱
FM-29	级联下拉	国家→省份→城市异步加载+loading	级联选项加载无反馈
FM-30	Inputmode	numeric/email/tel/url 触发对应移动端键盘	数字输入弹出全键盘
FM-31	粘贴处理	粘贴逗号分隔文本自动拆分为标签	粘贴报错
FM-32	批量编辑	多条记录同时编辑的模式	逐条编辑效率低
FM-33	搜索型下拉	combobox 支持搜索+键盘+异步加载	下拉选项过多无法定位

十四、内容层（Content）

#	检查项	验证标准	常见问题
CT-01	标题唯一	每页仅一个 h1	多个 h1 或无 h1
CT-02	标题层级	h1→h2→h3 不跳级	h2 直接跳到 h4
CT-03	段落长度	单段 3-4 行，不超过 6 行	大段文字墙
CT-04	列表使用	≥3 项内容用列表	多项并列用段落
CT-05	链接文字	描述性文字（非"点击这里”）	链接文字是"这里"
CT-06	链接样式	下划线 + 颜色区分 + visited 状态	链接与正文无法区分
CT-07	外部链接标识	外链有图标标识	不告知将离开本站
CT-08	代码块	语法高亮 + 语言标签 + 复制按钮	代码块无复制功能
CT-09	引用样式	blockquote 有视觉区分	引用与正文无区分
CT-10	表格样式	表头区分 + 行 hover + 响应式	内容表格样式简陋
CT-11	内容最大宽度	文章区域 60-75 字符宽度(~680px)	内容区过宽难阅读
CT-12	标点规范	中英文标点使用规范	半角全角标点混用

十五、国际化层（i18n）

#	检查项	验证标准	常见问题
I18N-01	文字方向	dir=“ltr”/“rtl” 布局翻转	阿拉伯语布局错乱
I18N-02	文案长度适配	按钮/标签允许文案 2-3 倍长度	德语文案溢出按钮
I18N-03	日期格式	locale 感知(YYYY-MM-DD / MM/DD/YYYY)	日期格式不统一
I18N-04	数字格式	千分位/小数点 locale 感知	数字格式不符合当地习惯
I18N-05	货币格式	符号位置(前/后) + 小数位数	货币符号位置错误
I18N-06	复数形式	i18n 库处理复数规则	“1 items” 而非 “1 item”
I18N-07	字体回退	多语言字体栈（CJK/Arabic/Devanagari）	某些语言文字显示异常
I18N-08	图标国际化	图标不含文字(文字用 i18n)	图标中嵌文字无法翻译
I18N-09	双向布局镜像	margin-left→margin-right, float-left→float-right, 箭头方向反转	RTL 布局不镜像
I18N-10	逻辑 CSS 属性	margin-inline-start 替代 margin-left，border-inline-start 替代 border-left	物理属性在 RTL 下不翻转
I18N-11	文本方向检测	用户生成内容用 dir=“auto” 自动检测方向	阿拉伯文/希伯来文显示乱序
I18N-12	Locale 感知排序	列表/表格用 Intl.Collator 按 locale 规则排序	中文按 Unicode 而非拼音排序
I18N-13	姓名格式化	名前姓后 / 姓前名后按 locale 调整	日文/韩文姓名顺序错误
I18N-14	地址格式化	地址字段顺序/标签按国家调整	所有国家用同一地址格式
I18N-15	错误消息翻译	验证消息/ARIA 标签/toast 消息全部可翻译	部分错误消息硬编码英文
I18N-16	翻译缺失降级	翻译缺失时降级到默认语言，而非显示 key	显示 “error.required” 原始 key
I18N-17	相对时间格式	“3 小时前” 用 Intl.RelativeTimeFormat	时间格式不随语言变化
I18N-18	列表格式	“A、B 和 C” 用 Intl.ListFormat 按语言切换	中英文列表连接符相同
I18N-19	图标方向感知	“返回"箭头 LTR 朝左/RTL 朝右	RTL 下箭头方向错误
I18N-20	数字输入 locale	数字输入接受 locale 分隔符（逗号/句号）	只接受英文数字格式
I18N-21	时区处理	日期时间显示用户时区；提供时区选择器	所有用户看到同一时区时间

十六、性能层（Performance）

#	检查项	验证标准	常见问题
PF-01	FCP	First Contentful Paint < 1.8s	白屏时间长
PF-02	LCP	Largest Contentful Paint < 2.5s	首屏大图加载慢
PF-03	INP	Interaction to Next Paint < 200ms	点击后卡顿
PF-04	CLS	Cumulative Layout Shift < 0.1	页面元素跳动
PF-05	路由分割	每个路由独立 chunk	首屏加载全站代码
PF-06	组件懒加载	heavy 组件 dynamic import	所有组件一次加载
PF-07	资源预加载	preload 关键字体/图片	字体闪烁(FOIT)
PF-08	资源预获取	prefetch 下个页面资源	无预获取
PF-09	字体优化	font-display:swap + 子集化 + preload	字体文件过大
PF-10	图片优化	响应式 + 懒加载 + WebP/AVIF + 尺寸预留	加载原图大图
PF-11	动画性能	只用 transform + opacity	用 top/left 做动画
PF-12	虚拟列表	大列表虚拟化渲染	万级 DOM 节点
PF-13	DOM 深度	嵌套不超过 15 层	过深嵌套
PF-14	CSS 体积	未使用的 CSS 清理	CSS 文件过大
PF-15	缓存策略	静态资源 immutable cache	每次都请求静态资源

十七、安全层（Security）

#	检查项	验证标准	常见问题
SEC-01	XSS-输出转义	用户输入渲染前转义 HTML	innerHTML 直接插入用户内容
SEC-02	XSS-CSP	Content-Security-Policy 头设置	无 CSP 或 CSP 过宽松
SEC-03	CSRF	Token / SameSite Cookie	无 CSRF 防护
SEC-04	密码遮蔽	type=password + 非自动填充	密码明文显示
SEC-05	敏感数据掩码	身份证/银行卡/手机号部分遮蔽	完整显示敏感信息
SEC-06	输入净化	URL/HTML/SQL 参数过滤	直接拼接用户输入到 URL
SEC-07	点击劫持	X-Frame-Options / CSP frame-ancestors	页面可被 iframe 嵌入
SEC-08	自动填充	autocomplete 属性正确设置	敏感字段自动填充泄露
SEC-09	文件上传限制	文件类型/大小/数量限制	可上传任意文件
SEC-10	速率限制	前端节流 + 后端限流	无限制可暴力请求

十八、滚动与光标层（Scroll & Cursor）

#	检查项	验证标准	常见问题
SC-01	平滑滚动	html { scroll-behavior: smooth }	锚点跳转无过渡
SC-02	滚动捕捉	scroll-snap-type 用于轮播/全屏页	滚动定位不精准
SC-03	滚动阴影	内容滚动时 header/footer 底部出现阴影	滚动后无法区分层级
SC-04	滚动到顶按钮	滚动超过一屏后出现返回顶部	滚动很长找不到回去的路
SC-05	虚拟滚动条	overflow-scroll 但隐藏原生滚动条	滚动条样式破坏设计
SC-06	自定义滚动条	webkit-scrollbar 样式（窄轨道/圆角）	原生滚动条太粗
SC-07	锁定背景滚动	弹窗打开时 body overflow:hidden	弹窗打开背景还在滚
SC-08	光标-可点击	可交互元素 cursor:pointer	按钮光标为 default
SC-09	光标-不可点击	禁用元素 cursor:not-allowed	禁用按钮光标仍为 pointer
SC-10	光标-等待	加载/处理中 cursor:wait	长操作无光标变化
SC-11	光标-文本	可选文本区域 cursor:text	文字区域光标为 default
SC-12	光标-拖拽	可拖拽元素 cursor:grab/grabbing	拖拽时光标无变化
SC-13	选区样式	::selection 背景色+文字色 token 化	选区颜色为默认蓝色
SC-14	占位符样式	::placeholder 颜色 token 化	placeholder 颜色与正文混淆
SC-15	滚动指示器	长内容页面顶部进度条	不知当前阅读进度

十九、错误与空状态层（Error & Empty States）

#	检查项	验证标准	常见问题
ERR-01	404 页面	插图+描述+返回首页/搜索入口	404 只显示空白
ERR-02	500 页面	插图+描述+重试按钮+返回首页	500 显示原始错误堆栈
ERR-03	网络错误	断网提示+重试按钮	断网时页面白屏
ERR-04	权限错误	403/401 页面+登录/申请入口	权限不足显示 404
ERR-05	表单错误汇总	多个错误时顶部汇总+滚动到第一个	多个错误只看到最后一个
ERR-06	API 错误 toast	接口报错时显示 toast	接口报错无任何提示
ERR-07	空列表	插图+描述+创建/导入入口	空列表只显示"暂无数据”
ERR-08	空搜索	搜索无结果时提示+建议	搜索无结果空白
ERR-09	图片加载失败	备用图/重试/隐藏	图片加载失败显示破图
ERR-10	组件错误边界	组件崩溃时显示 fallback 而非白屏	一个组件崩全页白屏
ERR-11	超时处理	请求超时提示+重试	长时间等待无反馈
ERR-12	维护页面	计划维护提示页	维护时显示 500 错误

二十、高级组件层（Advanced Components）

20.1 轮播（Carousel）

#	检查项	验证标准	常见问题
CAR-01	指示器	底部圆点/数字指示当前位置	不知道当前第几张
CAR-02	前进/后退	左右箭头/边缘点击	无法手动切换
CAR-03	自动播放	自动轮播+悬浮暂停	自动播放无法暂停
CAR-04	循环	到达末尾后回到第一张	到末尾就停了
CAR-05	触摸滑动	移动端手势滑动	移动端只能点箭头
CAR-06	键盘操作	左右方向键切换	无法键盘操作
CAR-07	懒加载	非当前帧图片懒加载	所有图片一次加载

20.2 全局搜索 / 命令面板（Command Palette）

#	检查项	验证标准	常见问题
CMD-01	快捷键触发	Ctrl+K / Cmd+K 打开	无快捷键入口
CMD-02	搜索框自动聚焦	打开即聚焦输入框	需要手动点击输入框
CMD-03	实时搜索	输入时即时过滤结果	需要按回车才搜索
CMD-04	分类展示	最近使用/建议/操作分组	结果无分组
CMD-05	键盘导航	上下箭头选择+回车确认	无法键盘操作
CMD-06	高亮匹配	搜索关键词在结果中高亮	匹配位置不明显
CMD-07	无结果状态	搜索无结果有提示	无结果空白

20.3 图片灯箱（Lightbox）

#	检查项	验证标准	常见问题
LB-01	全屏预览	点击图片全屏查看	只能看缩略图
LB-02	缩放	双击/滚轮/捏合缩放	大图无法看细节
LB-03	前后切换	左右箭头切换图片	无法浏览下一张
LB-04	关闭方式	ESC / 点击外部 / X 按钮	只能点 X 关闭
LB-05	图片计数	“3/12” 当前/总数	不知还有多少张
LB-06	缩略图列表	底部缩略图快速跳转	无法跳转到特定图

20.4 通知中心

#	检查项	验证标准	常见问题
NTF-01	未读标识	图标上数字/红点	不知道有新通知
NTF-02	通知面板	点击图标展开面板	通知直接跳转无预览
NTF-03	全部已读	一键标记所有已读	需要逐条点
NTF-04	通知分类	系统/消息/操作分 tab	所有通知混在一起
NTF-05	加载更多	滚动加载历史通知	只显示最近几条
NTF-06	空通知	插图+描述	空通知只显示空白

#	检查项	验证标准	常见问题
CK-01	位置	底部固定横幅/顶部全屏	遮挡主要内容
CK-02	接受/拒绝	明确的接受和拒绝按钮	只有接受按钮
CK-03	详细选项	可选择接受哪些类别	全有或全无
CK-04	记忆选择	选择后 6-12 个月不再显示	每次访问都弹
CK-05	修改选择	设置中可修改 cookie 偏好	无法修改之前的选择

#	检查项	验证标准	常见问题
MEGA-01	全宽面板	菜单项展开全宽下拉面板，与导航栏对齐	下拉面板只有菜单宽度
MEGA-02	多列布局	链接按分类分列 + 分类标题	所有链接单列罗列
MEGA-03	特色内容	支持促销图/高亮推荐/横幅	纯文字列表
MEGA-04	键盘导航	Tab/箭头遍历菜单项	无法键盘操作
MEGA-05	悬停意图	延迟打开/关闭防止鼠标经过误触发	鼠标经过就打开
MEGA-06	响应式折叠	移动端折叠为手风琴/钻入式导航	移动端仍全宽面板

20.7 图表/数据可视化（Charts）

#	检查项	验证标准	常见问题
CHT-01	图表类型	柱状/折线/面积/饼图/散点/迷你图	只有基础柱状图
CHT-02	图表色板	使用设计系统色板；系列间对比度足够	图表颜色随意取值
CHT-03	交互式图例	点击图例切换系列显隐	图例纯展示
CHT-04	数据 Tooltip	悬浮显示精确值 + 格式化数字	无数据查看方式
CHT-05	坐标轴标签	标签可读（旋转/截断/密集时跳过）	标签重叠不可读
CHT-06	图表无障碍	aria-label 或 role=“img” + 数据表格降级	屏幕阅读器无法感知
CHT-07	图表响应式	图表随容器宽度自适应	固定宽度溢出
CHT-08	图表空状态	“暂无数据” 插图+提示	空数据时空白
CHT-09	图表加载态	数据加载中 skeleton/shimmer	加载中空白
CHT-10	图表动画	入场动画(柱形增长/线条绘制)+reduced-motion	图表突然出现

20.8 富文本编辑器（Rich Text Editor）

#	检查项	验证标准	常见问题
RTE-01	工具栏格式	加粗/斜体/下划线/删除线/标题/列表/引用/代码/链接	工具栏功能不全
RTE-02	工具栏对齐	文本对齐选项(左/中/右/两端)	无对齐控制
RTE-03	嵌入支持	图片/视频/文件嵌入编辑器	只能输入纯文本
RTE-04	表格支持	编辑器内插入/编辑表格	无表格功能
RTE-05	撤销/重做	Ctrl+Z / Ctrl+Y 在编辑器上下文中	撤销影响整页
RTE-06	字数统计	实时字符数/字数显示	无字数限制提示
RTE-07	快捷键提示	Ctrl+B/I/K 格式化快捷键 + tooltip	不告知有快捷键
RTE-08	输出格式	输出有效 HTML/Markdown + 设计系统类名	输出格式不可控
RTE-09	粘贴清理	外部粘贴内容清理格式保留结构	粘贴带大量垃圾样式
RTE-10	@提及支持	@mention 和 #hashtag 自动补全	无提及功能
RTE-11	最大长度	最大内容长度 + 倒计提示	超出长度无提示

二十一、实践建议

21.1 如何使用本清单

设计初期（需求阶段）

从汇总表勾选本次需要实现的检查项
按层级组织成设计需求文档
每个检查项写明具体参数（如"字号阶梯: 12/14/16/20/24/30/36"）
将需求清单交给 AI 实现

设计中期（开发阶段）

逐层扫描，对照检查项验收
重点检查：颜色层、间距层、组件状态完整性
使用自动化工具辅助：Lighthouse、axe-core、Stylelint

设计后期（审查阶段）

按检查项清单逐项审查
标记未通过项，给出具体修改建议
回归测试确保修改不引入新问题

21.2 给 AI 的提示词模板

模板一：Design Token 定义

请基于 Tailwind CSS 定义以下 Design Token：
【排版层】
- T-01: 字体族 — primary: system-ui, heading: Inter, mono: JetBrains Mono
- T-02: 字号阶梯 — xs(12)/sm(14)/base(16)/lg(18)/xl(20)/2xl(24)/3xl(30)/4xl(36)
- T-03: 行高 — tight(1.25)/normal(1.5)/relaxed(1.75)
- T-21: 等宽数字 — tabular-nums 用于表格金额列
【颜色层】
- C-01: 品牌色 — primary blue (#3B82F6) 含 50-950 色阶
- C-20: 暗色模式映射 — 所有颜色 dark: 变体
- C-24~26: 对比度 — 正文≥4.5:1，大文本≥3:1
【间距层】
- S-01: 基准单位 — 4px
- S-02: 间距阶梯 — 0/1/2/3/4/5/6/8/10/12/16/20/24
输出 tailwind.config.ts 配置。

模板二：组件实现

请使用 shadcn/ui + Tailwind CSS 实现以下按钮检查项：
【变体】BTN-01~06: primary/secondary/outline/ghost/destructive/link
【尺寸】BTN-07~09: sm(h-8 px-3 text-xs)/md(h-10 px-4 text-sm)/lg(h-12 px-6 text-base)
【状态】BTN-10~14: hover/active/focus-visible/disabled/loading
【图标】BTN-15~17: left-icon/right-icon/icon-only (lucide-react)
【组合】BTN-19: ButtonGroup 水平排列，相连边共享
要求：
- 使用 class-variance-authority (cva) 管理变体
- 使用 tailwind-merge 处理类名合并
- loading 状态显示 Spinner + 禁止点击
- icon-only 按钮有 aria-label

模板三：审查检查单

请审查当前页面的 UI 实现，逐项检查以下检查项是否通过：
【排版层】T-01~T-25
【颜色层】C-01~C-30
【间距层】S-01~S-10
【组件状态】BTN-10~14, INP-08~12, SEL-03~05
【交互层】IX-03~07
【响应式】RP-01~RP-12
【无障碍】A11Y-01~A11Y-25
输出格式：
| 检查项 | 状态 | 问题描述 | 修复建议 |

21.3 检查优先级排序

优先级	层级	理由
P0 必做	排版、颜色、间距	设计系统骨架，影响全局一致性
P0 必做	组件状态	缺失状态导致功能不可用
P0 必做	无障碍	法律合规 + 用户覆盖
P0 必做	错误与空状态	用户体验底线
P1 重要	布局、圆角阴影、图标	视觉一致性的关键
P1 重要	交互反馈、响应式	用户体验的核心
P1 重要	主题（暗色模式）	用户期望
P1 重要	滚动与光标	交互细节完整性
P1 重要	通知中心	信息可达性
P2 改进	动效、内容排版	锦上添花
P2 改进	性能优化	持续优化
P2 改进	轮播、命令面板、灯箱	高级组件
P3 可选	国际化、安全	视项目需求
P3 可选	Cookie 同意	合规需求

二十二、工具推荐

工具	用途	检查层级
Lighthouse	性能/无障碍/最佳实践评分	性能层、无障碍层
axe DevTools	无障碍自动化检测	无障碍层
Stylelint	CSS 规则一致性检查	排版层、间距层
ESLint + a11y 插件	JSX/TSX 无障碍检查	无障碍层
Chromatic / Percy	视觉回归测试	全层级
Figma Tokens	设计令牌管理	颜色/排版/间距层
Tailwind CSS	原子化 CSS 框架	全层级
shadcn/ui	组件库基础	组件层
Storybook	组件文档/预览	组件层
Contrast Checker	颜色对比度检测	颜色层、无障碍层

二十三、总结

检查项统计

层级	检查项数量	优先级
排版层	25	P0
颜色层	30	P0
间距层	20	P0
圆角+阴影层	20	P1
布局层	29	P1
组件-按钮	19	P0
组件-输入	20	P0
组件-选择	10	P1
组件-卡片	7	P1
组件-弹窗	10	P0
组件-抽屉	8	P1
组件-气泡卡片	6	P1
组件-菜单	8	P1
组件-表格	14	P1
组件-标签页	6	P2
组件-导航	8	P1
组件-反馈	16	P0
组件-数据展示	20	P1
组件-组合模式	15	P1
交互层	20	P1
响应式层	12	P1
无障碍层	25	P0
主题层	10	P1
动效层	29	P2
图标+图片层	15	P1
表单层	33	P0
内容层	12	P2
国际化层	21	P3
性能层	15	P2
安全层	10	P2
滚动与光标层	15	P1
错误与空状态层	12	P0
高级组件-轮播	7	P2
高级组件-命令面板	7	P2
高级组件-灯箱	6	P2
高级组件-通知中心	6	P1
高级组件-Cookie	5	P3
高级组件-超级菜单	6	P2
高级组件-图表	10	P2
高级组件-富文本编辑器	11	P2
合计	578	—

核心原则

每个检查项都是独立可验证的 — 不存在模糊的"好看"要求
每个检查项都有明确的验证标准 — 知道"做到了"长什么样
每个检查项都可以精确描述给 AI — 从清单勾选，AI 精确输出
层级之间有优先级 — P0 先做骨架，P1 做体验，P2 做打磨
清单是活的 — 根据项目需要增删检查项

与 /sc:design 配合

本清单可作为 /sc:design 的输入：

从清单中勾选需要的检查项
填写具体参数值
将勾选后的清单作为 design brief 提交给 AI
AI 按检查项逐项实现
按检查项逐项验收

附：P0 快速审查清单

首次审查时，优先检查以下 必须做到 的检查项。通过后可进入 P1 审查。

排版（P0）

T-01 字体族定义了 primary/heading/mono/fallback 四组
T-02 字号阶梯有 8+ 个递进级别
T-03 行高定义了 tight/normal/relaxed
T-06 h1-h6 视觉层级清晰递减
T-07 正文字号≥14px，行高≥1.5

颜色（P0）

C-01 品牌色有 50-950 色阶
C-02 语义色 success/warning/error/info 完整
C-24 正文对比度≥4.5:1
C-27 不单独靠颜色传达信息

组件状态（P0）

BTN-10~14 按钮 hover/active/focus/disabled/loading 完整
INP-08~12 输入框 hover/focus/error/disabled 完整
MDL-01~10 弹窗遮罩/关闭/焦点管理完整
FB-01~05 Toast 有类型区分/自动关闭/可关闭

无障碍（P0）

A11Y-01 使用语义化 HTML 标签
A11Y-04 无文字元素有 aria-label
A11Y-11 所有交互元素 Tab 可达
A11Y-15 focus-visible 有明确样式
A11Y-24 表单 label 与 input 关联

错误处理（P0）

ERR-01 404 页面有插图+返回入口
ERR-07 空列表有插图+描述+操作入口
ERR-10 组件崩溃有 fallback
FM-09 错误提示在字段正下方

AI 辅助前端开发：从踩坑到改进的实战手册

di4urp@gmail.com (taevas) — Tue, 21 Apr 2026 11:00:00 +0800

前言

我用 Claude Code 开发了一个前端项目（Skill Collect System），前后经历了 8 个 session、数十万字的对话。事后我回溯了所有 session 记录，发现了一个令人不安的事实：我严格遵循了 brainstorm → design → implement 的标准流程，但产出质量仍然反复翻车。

这篇文章是对整个过程的复盘——问题出在哪、为什么出、怎么改。希望对同样使用 AI 辅助开发的人有参考价值。

一、我遵循的"标准流程"

我的工作流看起来很规范：

/sc:brainstorm → 需求探索和澄清
/sc:design → 输出设计方案文档
/sc:implement → 按设计实现功能

AI 在每个阶段都声称"设计完美"、“方案完整”。我按 AI 建议的顺序走完了全流程，然后打开浏览器——页面报错了。

这不是一次两次。8 个 session 中，有 6 个出现了实现后返工的情况。

二、问题诊断：AI 的设计是表演性的

核心发现

回溯 session 记录后，我发现了一个关键数据点：

Session	设计阶段耗时	返工率
最早的 session	~20 分钟，多轮确认	0%
其他 5 个 session	0-2 分钟，直接"实施"	35%-60%

唯一零返工的 session 恰恰是设计阶段最充分的那次。

AI 在设计阶段的两个致命缺陷

缺陷 1：不验证假设就下结论

AI 设计了 updatedAt 字段展示，但根本没读后端代码确认字段存在。实际后端用的是 discoveredAt。实现后页面上全是 Invalid Date。

一个简单的设计阶段验证：

读后端 types/skill.types.ts → 发现字段是 discoveredAt → 设计文档用正确的字段

AI 实际做的：

假设字段叫 updatedAt → 写进设计文档 → 声称"设计完美" → 实现后翻车

缺陷 2：用文档模板替代真实思考

AI 擅长输出"看起来完整"的文档——有目录、有表格、有验收清单。但这是格式不是质量。一个设计文档 1 分钟就出来了，真正能用的设计不可能 1 分钟完成。

三、5 大问题模式

问题 1：设计确认走过场

表现：设计文档出来后，用户直接说"实施"，没有审阅环节。

根因：AI 声称设计完美，用户信任了这个判断。但 AI 的"完美"基于假设，不是基于对现有代码的验证。

代价：一个 session 中 layout.tsx 被反复编辑了 16 次，只为修复一个 CSS 居中问题，耗时 3 小时。这个问题的根因（滚动条宽度影响布局）在设计阶段完全没有被考虑。

问题 2：“完成"标准太松

表现：AI 以"编译通过"为完成标准，不是"功能可用”。

实际记录：一个 session 中 AI 声称"交付完成"了 6 次，每次用户打开页面都有问题。用户原话：

“每次你说完成了，我打开页面又是报错的”

根因：AI 没有真正启动服务验证功能，而是做了静态代码分析就宣布完成。

问题 3：Ralph Loop 吃掉了确认环节

表现：使用自动化循环（Ralph Loop）后，AI 在没有人工确认的情况下反复"完成→失败→重来"。

根因：自动化循环缺少检查点。8 个 Agent 并发冲出去写代码，但没有人检查方向对不对。

问题 4：前后端并发缺少接口契约

表现：AI 同时写前后端，但类型定义、API 参数、端口配置各自为政。

实际案例：

前端用 search 参数，后端期望 q 参数
前端类型定义的必填字段，后端根本不返回
AI 擅自把端口从 3001 改成 3002，未经用户同意

问题 5：调试过程混乱

表现：AI 在调试时创建了 13 个临时 Playwright 测试文件（quick-audit.spec.ts、debug-page.spec.ts、check-404.spec.ts），命名随意，和正式测试混在一起。

根因：AI 缺乏组织性，把调试产物和项目代码混在一起。

四、改进方案

方案 1：设计验证检查点（最关键）

在 design 完成后、implement 之前，增加一个强制验证步骤：

提示词模板：
"验证你的设计方案：
1. 列出设计中假设存在的所有接口、字段、组件
2. 逐个到代码里确认它们确实存在
3. 有不一致的地方先修正设计
4. 完成验证后再等我的确认"

不要说"实施"，要等 AI 验证完设计后再确认。

方案 2：重新定义"完成"标准

在 CLAUDE.md 中写入：

## 完成标准（不可跳过）
1. 必须启动开发服务器
2. 必须用浏览器打开页面验证功能
3. 浏览器控制台无报错
4. 所有验收标准逐项通过
5. 以上全部满足后才能声称"完成"

方案 3：为 brainstorm/design 增加约束

## 设计阶段强制规则
1. 设计文档必须引用现有代码的实际情况（不是假设）
2. 前端设计必须对齐后端 API 返回格式（逐字段确认）
3. 设计文档必须包含"影响文件清单"
4. 未收到用户明确确认前，禁止写任何代码

方案 4：谨慎使用自动化循环

Ralph Loop 适合重复性任务（批量测试、批量审查），不适合需要判断力的任务（设计确认、需求澄清）。

使用自动化循环时，每轮结束时应该暂停报告进度，等待人工确认。

方案 5：检查设计文档质量的快速方法

确认设计前，问自己一个问题：

设计文档里有没有提到现有代码的实际情况？

如果设计文档只描述"要做什么"，没有描述"现有代码是什么样的、需要改哪些文件、字段是否对齐"——那这个设计就是空的，不要说"实施"。

五、一句话总结

AI 的设计不验证就不可信。你需要的不是更多流程，而是在"设计完成"和"开始实施"之间，加一个验证检查点。

流程应该是：

brainstorm → design → 验证设计（AI 自己到代码里确认假设）→ 人工确认 → implement

而不是：

brainstorm → design（声称完美）→ 直接 implement（翻车）

附录：数据来源

本文基于对 Skill Collect System 项目的 8 个 Claude Code session 记录的分析：

Session	大小	时长	主要工作
e707e589	10.4MB	~25h	Ralph Loop 自动化实施（最大翻车现场）
ecc16ec3	3.6MB	~5h	UI 改进 + 居中问题 16 次修补
49b7ac2a	2.4MB	~6h	目录元数据 + 失踪检测
e8ae553a	1.1MB	~1h	折叠功能（跳过设计，35% 返工）
a9263df2	304KB	~41min	项目初始设计（唯一零返工）

提示词优化迭代系统：多 Agent 协作的设计链路

di4urp@gmail.com (taevas) — Wed, 15 Apr 2026 20:17:10 +0800

系统概述

这是一个基于多 Agent 协作的提示词自动优化系统，通过迭代对比生成结果与参考标准，持续改进提示词质量，直至达到预设的一致性阈值。

核心流程图

flowchart TD Start([开始]) --> A[主 Agent: 准备初始提示词] A --> B[启动 Subagent 1
任务: 使用提示词分析目标网站] B --> C{Subagent 1 生成文档} C --> D[输出: test/DESIGN.md] D --> E[主 Agent: 初步审查结果] E --> F[启动 Subagent 2
任务: 对比两个 DESIGN.md] F --> G[Subagent 2 执行对比] G --> H{读取参考文档} H --> I[collections/nike/DESIGN.md
（参考标准）] G --> J{读取测试文档} J --> K[test/DESIGN.md
（待评估）] I & K --> L[Subagent 2: 一致性分析] L --> M[生成评估报告] M --> N[输出: 一致性打分] M --> O[输出: 修改建议] N --> P{一致性评分} P -->|满意| Done([完成 - 迭代结束]) P -->|需改进| Q[主 Agent: 根据建议优化提示词] O --> Q Q --> R[记录提示词版本] R --> S[版本历史库
V1, V2, V3...] S --> B style Start fill:#e1f5e1 style Done fill:#ffe1e1 style B fill:#e3f2fd style F fill:#e3f2fd style L fill:#fff3e0 style Q fill:#f3e5f5 style S fill:#fce4ec

核心设计链路

第一阶段：初始化

角色： 主 Agent

任务：

加载初始提示词模板
配置目标网站 URL：https://www.nike.com/
设置参考标准文档路径：collections/nike/DESIGN.md
初始化版本历史库（空）
设置一致性评分阈值（建议：85/100）

输出：

初始提示词 V0
迭代计数器 = 0

第二阶段：生成循环（迭代核心）

步骤 2.1：启动生成 Subagent

角色： Subagent 1

任务：

接收当前版本的提示词
访问目标网站 https://www.nike.com/
使用提示词分析网站内容
生成品牌设计文档

输出： test/DESIGN.md

关键技术点：

网站内容抓取与解析
基于提示词的结构化生成
Markdown 格式输出

步骤 2.2：主 Agent 初步审查

角色： 主 Agent

任务：

读取 test/DESIGN.md
检查文档完整性（必需章节：品牌概述、设计规范、视觉元素等）
快速格式验证
记录迭代元数据（时间戳、提示词版本）

步骤 2.3：启动对比 Subagent

角色： Subagent 2

任务：

读取参考文档：collections/nike/DESIGN.md
读取测试文档：test/DESIGN.md
执行深度一致性分析

分析维度：

维度	权重	评估内容
结构完整性	20%	章节覆盖、层级结构
内容准确性	30%	品牌信息、设计规范的准确性
细节丰富度	20%	颜色、字体、间距等细节
格式规范性	15%	Markdown 语法、代码块格式
语言表达	15%	专业术语使用、表述清晰度

输出：

一致性打分（0-100）
详细评估报告（逐维度打分）
具体修改建议列表

步骤 2.4：迭代决策

角色： 主 Agent

决策逻辑：

if 一致性打分 >= 阈值:
输出最优提示词
生成最终报告
终止迭代
else:
进入优化阶段
返回步骤 2.1

步骤 2.5：优化提示词

角色： 主 Agent

任务：

解析 Subagent 2 的修改建议
识别低分维度对应的提示词问题
生成优化策略
更新提示词

优化策略示例：

结构完整性低分 → 补充"必须包含以下章节"指令
内容准确性低分 → 增加"请核对以下关键信息"指令
细节丰富度低分 → 添加"请详细描述每个设计元素"指令
格式规范性低分 → 强化 Markdown 格式要求
语言表达低分 → 提供专业术语示例

步骤 2.6：版本管理

角色： 系统

任务：

迭代计数器 += 1
将优化后的提示词保存为 V{计数器}
记录到版本历史库
生成对比报告（V{n-1} vs V{n}）

版本记录格式：

{
 "version": "V3",
 "timestamp": "2024-04-15T20:30:00Z",
 "prompt_content": "...",
 "test_score": 72,
 "changes": ["补充了颜色系统章节要求", "增加了间距规范说明"],
 "diff_from_previous": "..."
}

第三阶段：收敛输出

当一致性评分达到阈值时：

输出内容：

最优提示词版本
最终一致性打分报告
完整迭代历史
优化趋势图
效果对比表格（V0 vs V最优）

可优化点

1. 评估维度权重动态调整

当前问题： 固定权重可能无法适配不同类型的网站和文档

优化方案：

根据参考文档的特征自动调整权重
例如：电商网站侧重"内容准确性"，设计网站侧重"细节丰富度"

2. 并行化多个测试网站

当前问题： 只在 Nike 网站上测试，泛化能力未知

优化方案：

同时在多个同类网站（Adidas、Puma、Under Armour）测试
使用平均分评估提示词的泛化性
只有多网站都达标才算收敛

3. 增量式生成

当前问题： 每次都是全量生成，浪费计算资源

优化方案：

Subagent 2 识别低分章节
下一轮迭代只生成需要改进的章节
其他章节复用上一轮结果

4. 自动阈值调整

当前问题： 固定阈值可能导致过度优化或收敛困难

优化方案：

初始阈值设低（如 60 分）
每轮迭代根据改进幅度动态调整
连续 3 轮改进 < 2 分时自动降低阈值要求

5. 提示词模板库

当前问题： 每次从零开始优化，效率低

优化方案：

预置针对不同网站类型的提示词模板库
根据网站特征自动选择最接近的初始模板
减少迭代轮次

问题点

1. 幻觉风险

问题描述： Subagent 1 可能生成网站上不存在的信息

解决方案：

在提示词中强调"只生成网站明确展示的信息"
引入事实核查 Subagent
对生成的关键信息进行交叉验证

2. 迭代发散

问题描述： 可能出现提示词越来越复杂但效果反而下降

解决方案：

限制最大迭代次数（如 20 轮）
记录历史最优解，发现退化时回滚
引入提示词复杂度惩罚机制

3. 收敛过慢

问题描述： 某些情况下需要几十轮迭代才能收敛

解决方案：

引入早停机制（early stopping）
连续 5 轮无显著改进时终止
分析卡点并人工干预

4. 参考文档偏差

问题描述： collections/nike/DESIGN.md 本身可能存在主观性或错误

解决方案：

使用多个专家标注的参考文档
计算参考文档之间的共识
只对比高共识部分

5. 网站内容变化

问题描述： Nike 网站可能在迭代期间更新，导致对比失效

解决方案：

每轮迭代缓存网站快照
所有 Subagent 使用同一快照
或明确标注网站访问时间戳

补充扩展点

6. 负样本对比机制

设计思路： 除了与参考文档对比，还引入负样本测试：

故意使用"反例提示词"生成文档
评估系统应能识别出明显的错误
验证评估系统的鲁棒性

实现方式：

# 在迭代过程中随机插入负样本测试
if iteration % 5 == 0:
 negative_prompt = "请生成一个完全错误的 Nike 设计文档"
 negative_result = generate(negative_prompt)
 negative_score = evaluate(negative_result)
 assert negative_score < 30, "评估系统无法识别负样本"

7. A/B 测试框架

设计思路： 对于每个优化点，同时尝试多个策略，选择效果最好的：

示例：

优化"细节丰富度"时，同时测试：
- 策略 A：“请详细描述每个设计元素”
- 策略 B：“补充每个元素的 RGB 值、使用场景和设计意图”
- 策略 C：提供具体的颜色、字体示例模板
使用多 Agent 并行测试
选择得分最高的策略

8. 可解释性增强

设计思路： 为每次迭代增加"推理链路"记录，让优化过程更透明：

记录内容：

## 迭代 V3 决策记录

### 问题诊断
- 当前得分：72/100
- 主要短板：细节丰富度（45%）、格式规范性（58%）

### 优化推理
1. 细节不足分析：
 - 颜色系统缺少 RGB 值
 - 字体规范缺少 line-height、letter-spacing
 - 间距单位混用（px、rem、em）

2. 格式问题分析：
 - 表格缺少对齐声明
 - 代码块语言标注不一致
 - 链接使用相对路径而非绝对路径

### 优化策略
- 在提示词中添加"颜色系统必须包含 RGB 值"的显式指令
- 增加格式规范示例代码块
- 要求统一使用 rem 单位

### 预期效果
- 细节丰富度提升至 65%
- 格式规范性提升至 80%
- 综合得分预期：78/100

实施建议

优先级排序

P0（必须）： 解决幻觉风险、迭代发散
P1（重要）： 评估维度动态调整、并行多网站测试
P2（优化）： 增量式生成、A/B 测试、可解释性增强

技术栈推荐

Agent 编排： Claude Agent SDK 或自定义框架
网站抓取： Playwright 或 Puppeteer（支持动态内容）
对比评估： 结构化 diff + LLM 辅助
版本管理： Git + 自定义元数据存储

成功指标

指标	目标值
最终一致性评分	≥ 85
平均迭代轮次	≤ 10
单次迭代耗时	≤ 2 分钟
提示词长度增长率	≤ 50%（避免膨胀）
泛化测试通过率	≥ 80%（在同类网站上）

总结

这个提示词优化迭代系统通过多 Agent 协作形成了一个闭环反馈机制：

闭环路径： 版本库 → Subagent 1 → 生成文档 → Subagent 2 → 评估打分 → 优化提示词 → 版本库
核心价值： 将人工优化提示词的经验转化为可自动执行的迭代流程
扩展潜力： 可应用于各类需要高质量结构化输出的场景

关键在于设计好评估维度和优化策略，让每次迭代都有明确的改进方向。

Agent 可观测性设计：从一次 Slack 网关故障排查中学到的

di4urp@gmail.com (taevas) — Tue, 24 Mar 2026 14:06:42 +0800

引言

OpenAI 在 Harness Engineering 一文中提到：

随着代码吞吐量的增加，我们的瓶颈变成了人工 QA 能力。由于人类的时间和注意力是固定的限制因素，我们一直在努力通过令应用程序的 UI、日志和应用指标等内容对 Codex 直接可读，从而为智能体增加更多功能。

这段话揭示了一个关键趋势：AI Agent 的能力边界，很大程度上取决于系统的可观测性设计。如果 Agent 无法直接"阅读"系统的状态，它就不得不依赖人类作为"数据中转站"，这不仅效率低下，也限制了 Agent 的自主性。

本文通过一次真实的 Hermes Slack 网关故障排查 案例，探讨如何设计让 Agent 能够自主诊断和修复问题的系统。

案例：Slack 消息接收故障

问题描述

用户发现 Slack 消息没有正常接收，于是向 Agent（Claude）求助：

用户：slack 消息没接收到

Agent 开始自主排查问题。

对话实录（原文）

第一段对话：问题诊断与修复

❯ slack 消息没接收到
────────────────────────────────────────
┊ 💬 让我检查一下 Slack 消息的接收情况。
┊ ⚙️ proc ls processes 0.0s
┊ 💬 目前没有活动的后台进程。让我查看一下你的 Slack 配置是否正确。
┊ 📖 read ~/.config/hermes/config.yaml 0.6s [error]
┊ 💻 $ ls -la ~/.config/hermes/ 2>/dev/null ||... 0.3s
┊ 💻 $ ls -la ~/.hermes/ 2>/dev/null | head -20 0.3s
┊ 📖 read ~/.hermes/config.yaml 1.1s
┊ 💬 我看到配置文件中没有 Slack 的特定配置。让我检查一下是否有 Slack 相关的进程或网关状态：
┊ 📖 read ~/.hermes/gateway_state.json 1.1s
┊ 💬 发现了问题。网关状态显示 `"gateway_state": "stopped"`，而且 `platforms` 是空的 `{}`。这意味着 Slack 网关没有启动。
让我尝试启动 Slack 网关：
┊ 💻 $ hermes gateway run --platform slack 2>&... 3.3s
┊ 💬 我看到网关服务已经加载了。让我查看一下日志文件，看看为什么 Slack 消息没有接收：
┊ 💻 $ tail -100 ~/.hermes/logs/gateway.log 2>... 0.3s
┊ 💬 **发现问题了！**
从日志可以看到：
1. 网关已经在 `2026-03-24 13:37:58` 停止了
2. 最后一条 Slack 消息处理是在 `2026-03-24 13:32:51`
3. 日志显示 `"Gateway stopped"` 和 `"Cron ticker stopped"`
让我查看错误日志，看看为什么网关停止了：
┊ 📖 read ~/.hermes/logs/gateway.error.log 1.1s
┊ 💻 $ hermes gateway status 0.3s
┊ 💬 服务是加载状态，但 `OnDemand: true` 意味着它是按需启动的。让我尝试重新启动网关：
┊ 💻 $ hermes gateway run --replace 2>&1 &
sle... 10.4s
┊ 💬 让我检查网关是否真正在运行：
┊ ⚙️ proc ls processes 0.0s
┊ 💻 $ ps aux | grep -i hermes | grep -v grep 0.5s
┊ 💬 网关进程 (PID 94451) 已经在运行了。让我查看最新的网关日志，确认 Slack 是否已连接：
┊ 💻 $ tail -50 ~/.hermes/logs/gateway.log 2>/... 0.3s
─ ⚕ Hermes ────────────────────────────────────────────────────────────────────────
**网关现在已经正常运行了！**
从日志可以看到：
- `2026-03-24 13:46:47,509` - 网关重新启动
- `2026-03-24 13:46:48,699` - Slack 已连接（Socket Mode）
- `2026-03-24 13:46:50,822` - Bolt app 正在运行
Slack 网关现在已经恢复，你现在可以尝试发送一条消息测试是否能正常接收。
如果还是收不到消息，请检查：
1. Slack 应用中是否正确安装了 Hermes bot
2. 是否给 bot 发送了消息（DM）或在正确频道中 @ 了 bot
需要我现在帮你测试发送一条 Slack 消息吗？
────────────────────────────────────────

第二段对话：排查思路复盘

用户进一步追问 Agent 是如何诊断问题的：

❯ 问题解决了。你是如何查问题的。哪里告诉你了，要去日志找。还是你自己判断的。
────────────────────────────────────────
好问题。是我自己判断的。
**排查思路：**
1. **先确认基础状态** - 用 `process list` 看有没有后台进程，发现没有活跃的 Slack
进程
2. **检查网关状态** - 读取 `~/.hermes/gateway_state.json`，发现 `"gateway_state":
"stopped"`，这是关键线索
3. **确认进程存在** - 用 `ps aux` 发现确实没有网关进程在运行
4. **看日志找原因** - 既然知道网关停了，自然要去 `~/.hermes/logs/gateway.log`
看最后发生了什么
**日志定位过程：**
- 发现日志里最后一条 Slack 消息是 `13:32:51`
- 然后 `13:37:58` 出现 `"Stopping gateway..."` → `"Slack Disconnected"` →
`"Gateway stopped"`
- 说明网关是被人为停止的（不是你手动停的话，可能是系统或其他原因）
**解决方案：**
直接 `hermes gateway run --replace` 重新启动网关，然后验证进程和日志确认 Slack
重新连接。
---
整个流程是基于 **"服务没运行 → 为什么停了 → 重新启动"**
这个逻辑链条，没有依赖外部文档告诉我要去查日志，是系统性排查的思路。
────────────────────────────────────────

案例分析：什么让这个 Agent 能够自主排查？

1. 可观测性设计：系统状态对 Agent 直接可读

Agent 能够自主排查的第一步，是系统提供了结构化的可观测数据：

数据源	文件/命令	提供的信息
网关状态	`~/.hermes/gateway_state.json`	`gateway_state: stopped`, `platforms: {}`
运行日志	`~/.hermes/logs/gateway.log`	启动/停止时间、连接状态、消息处理记录
错误日志	`~/.hermes/logs/gateway.error.log`	异常信息和错误堆栈
进程状态	`ps aux` / `hermes gateway status`	实时进程信息和资源占用
配置信息	`~/.hermes/config.yaml`	服务配置和平台设置

关键设计原则：这些数据都是机器可读的（JSON、结构化日志），Agent 可以直接解析，而不需要人类去"读懂"后转述。

2. 分层排查逻辑：Agent 的系统性思维

Agent 展示了清晰的分层排查思路：

Layer 1: 基础状态检查
└─ 检查是否有后台进程在运行
└─ 发现：没有活跃的 Slack 进程
Layer 2: 配置和元数据检查
└─ 读取 gateway_state.json
└─ 发现：gateway_state = "stopped"
Layer 3: 运行时日志分析
└─ 读取 gateway.log
└─ 发现：13:37:58 网关停止，13:32:51 最后一条消息
Layer 4: 问题定位与修复
└─ 确认服务需要重新启动
└─ 执行 hermes gateway run --replace
Layer 5: 修复验证
└─ 检查进程 PID
└─ 确认日志显示 "Slack 已连接"

这种分层排查的逻辑，让 Agent 能够像 SRE 一样系统性地定位问题，而不是盲目猜测。

3. 自主验证闭环：Agent 能独立确认结果

Agent 不只是执行命令，还能独立验证操作结果：

执行前验证：检查当前状态（进程、网关状态）
执行后验证：
- 用 ps aux 确认进程在运行（PID 94451）
- 用 tail 读取最新日志确认 “Slack 已连接”

这种"执行-验证"的闭环，让 Agent 不需要人类去检查"修复是否成功"。

Agent-Ready 系统的设计原则

基于这个案例和 OpenAI Harness Engineering 的观点，我总结出以下设计原则：

原则 1：可观测性优先（Observability-First）

核心理念：Agent 必须能直接"阅读"系统的状态。

传统设计	Agent-Ready 设计
人类查看 UI 然后告诉 Agent	UI/状态文件直接可被 Agent 读取（JSON、API）
人类运行命令后口述结果	Agent 能直接执行命令并解析输出
非结构化文本日志	结构化日志（JSON）便于 Agent 解析
分散的监控面板	统一的状态文件和指标端点

实践建议：

将关键状态写入结构化文件（JSON/YAML）
使用结构化日志格式
提供 CLI/API 让 Agent 能查询实时状态

原则 2：决策可解释（Explainable Decisions）

核心理念：Agent 应该能够解释它为什么做出某个决定。

在这个案例中，当用户问"你是如何查问题的"，Agent 能够清晰地描述它的排查思路：

先确认基础状态
检查网关状态文件
确认进程存在
看日志找原因

这种可解释性不仅让结果可信，也便于人类在必要时介入或调整。

原则 3：安全自主（Safe Autonomy）

核心理念：Agent 应该能够安全地"尝试-验证-重试"。

在这个案例中：

幂等操作：hermes gateway run --replace 可以安全地重复执行
只读优先：先通过只读操作（读取文件、检查状态）定位问题
渐进式修复：从影响最小的修复方案开始（重启服务）

原则 4：人类注意力保护（Human Attention Protection）

核心理念：Agent 应该减少"不必要的人工 QA"。

从案例中可以看到，Agent 能够独立完成：

✅ 自主发现问题（网关停止）
✅ 自主定位根因（查看日志确认停止时间）
✅ 自主执行修复（重启网关）
✅ 自主验证结果（确认进程和连接状态）

唯一需要人类介入的点是：最终确认问题是否解决（发送测试消息）。

反模式：每一步都让 Agent 问"我应该查看日志吗？““我发现网关停止了，应该重启吗？"——这是对人类注意力的浪费。

设计检查清单

在设计 Agent-Ready 系统时，问自己这些问题：

可观测性检查

系统的关键状态是否存储在机器可读的文件中？
Agent 能否直接查询服务状态，而不需要人类转述？
日志是否采用结构化格式，便于 Agent 解析？
是否有明确的错误状态码和错误信息？

可操作性检查

Agent 能否直接执行修复操作（通过 CLI/API）？
修复操作是否幂等，可以安全地重复执行？
操作后是否有明确的成功/失败信号？
Agent 能否独立验证操作结果？

安全性检查

Agent 能否在只读模式下完成大部分诊断？
破坏性操作是否有足够的确认机制？
是否有回滚机制应对错误操作？

结语

OpenAI 的 Harness Engineering 理念提醒我们：AI Agent 的能力上限，取决于系统设计的可观测性。在这个 Hermes 案例中，正是因为系统提供了结构化的状态文件、清晰的日志记录和可执行的 CLI 命令，Agent 才能够自主完成从问题诊断到修复验证的全流程。

未来，当我们设计系统时，不仅要考虑"人类如何使用”，更要考虑"Agent 如何使用”。因为随着 AI 能力的提升，Agent 将成为系统最主要的用户之一。

参考阅读：

由需求反思爬虫设计：所见即所提取

di4urp@gmail.com (taevas) — Thu, 19 Mar 2026 12:00:00 +0800

场景

需要提取一个业务数据表格。

传统思路的困境：

数据分散在多个数据库
前端有数据处理逻辑
多个后端服务都会修改数据
要理清数据流转简直噩梦

换个思路： 用户在页面上看到的就是最终结果，直接提取不就行了？

所见即所提取

与其追着数据源头跑，不如直接拿最终渲染结果。

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();

await page.goto('https://example.com/data-page');

// 直接提取表格内容
const rows = await page.locator('table tbody tr').all();

const data = await Promise.all(rows.map(async row => {
 const cells = await row.locator('td').allTextContents();
 return cells;
}));

await browser.close();

console.log(data); // 拿到了

优势：

快速：几分钟搞定
稳定：页面结构变化比数据流逻辑变化慢得多
简单：不需要理解业务，不需要申请数据库权限

Playwright 常用速记

启动（带状态保持）

// 推荐：launchPersistentContext 保留登录状态和 cookies
const context = await chromium.launchPersistentContext(
 '/tmp/playwright-profile', // 用户数据目录
 {
 executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
 headless: false, // 显示浏览器窗口
 slowMo: 500, // 操作减速，方便观察
 channel: 'chrome', // 使用 Chrome 而非 Chromium
 }
);
const page = context.pages()[0] || await context.newPage();

基础操作

// 导航
await page.goto(url, { waitUntil: 'networkidle' });

// 交互
await page.locator('selector').click();
await page.locator('input').fill('text');
await page.locator('select').selectOption('value');

// 提取
const text = await page.locator('.class').textContent();
const items = await page.locator('.item').allTextContents();
const html = await page.locator('.container').innerHTML();
const attr = await page.locator('a').getAttribute('href');

// 等待
await page.waitForSelector('.class', { state: 'visible' });
await page.waitForLoadState('networkidle');
await page.waitForTimeout(1000); // 固定延迟（不推荐但有时必要）

// 截图调试
await page.screenshot({ path: 'debug.png', fullPage: true });

实用选项

// 设置视口
await page.setViewportSize({ width: 1920, height: 1080 });

// 拦截请求（屏蔽图片等）
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());

// 执行自定义脚本
await page.addInitScript(() => {
 Object.defineProperty(navigator, 'webdriver', { get: () => false });
});

总结

产品对着 CRM 告知需要哪些数据。并没有快速聚合的方式，且数据落在不同的数据库，很难聚合。

对后端来说，快速提取业务数据，通过爬虫的方式从数据源直接提取。不需要根据数据源反推数据库中的形式。实现比找前后端代码和数据库快多了。

用户看到什么，就提取什么。简单，直接。

MCP vs Skill：AI 能力扩展的两种范式与决策指南

di4urp@gmail.com (taevas) — Tue, 17 Mar 2026 13:47:37 +0800

核心概念

在构建 AI 应用的能力扩展时，我们面临两个主要选择：

MCP（Model Context Protocol）：连接层协议，解决 AI 与外部系统/工具的标准化通信问题
Skill：认知层封装，解决任务流程与知识复用问题

简单来说，MCP 回答"能不能访问、怎么连、谁能连、怎么管“的问题，而 Skill 回答”怎么做、流程是什么、输出要什么格式“的问题。

架构对比

┌─────────────────────────────────────────────────────────────────┐
│ AI 客户端 (Claude/Cursor 等) │
├─────────────────────────┬───────────────────────────────────────┤
│ │ │
│ Skill 层 (认知) │ MCP 层 (连接) │
│ │ │
│ ┌─────────────────────┐│ ┌─────────────────────────────┐ │
│ │ 任务流程编排 ││ │ 统一工具接口 │ │
│ │ 知识模板应用 ││ │ 标准化通信协议 │ │
│ │ 提示词工程 ││ │ 跨平台兼容 │ │
│ └─────────────────────┘│ └─────────────────────────────┘ │
│ │ │
└─────────────────────────┴───────────────────────────────────────┘
│
▼
┌─────────────────┐
│ 外部系统/资源 │
│ (DB/API/文件) │
└─────────────────┘

特征对比表

维度	MCP	Skill
定位	连接层协议	认知层封装
适用范围	跨平台、跨模型	特定平台内
主要解决	标准化通信、权限管控	任务流程、知识复用
部署位置	独立 Server进程	客户端/平台内
权限能力	系统级、本地访问	通常受限
标准程度	开放协议、强约束	自由定义、弱约束
生态性	可插拔、可扩展	封闭/半封闭

MCP 不可替代的六类场景

一、跨平台 / 跨模型 / 跨客户端统一接入

问题场景：同一套工具/服务需要被多个不同 AI 客户端调用。

典型用例：

场景	说明	Skill 的局限性
多客户端共享	Claude、Cursor、VS Code Copilot、自定义 Agent 都要调用同一套后端	Skill 仅绑定到特定平台
跨模型复用	Anthropic、OpenAI、字节等模型都要调用同一套后端能力	Skill 模型绑定性强
企业内协作	多团队、多 Agent 平台共享一套外部能力（DB、API、文件系统）	Skill 难以统一分发
开放生态	让第三方 AI 接入你的服务	Skill 是私有实现

MCP 解决方案示例：

# mcp_server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

mcp = Server("database-access")

@mcp.list_tools()
async def list_tools() -> list[Tool]:
 return [
 Tool(
 name="query_database",
 description="Execute SQL queries on the main database",
 inputSchema={
 "type": "object",
 "properties": {
 "sql": {"type": "string", "description": "SQL query"}
 },
 "required": ["sql"]
 }
 )
 ]

@mcp.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
 if name == "query_database":
 # 任何 MCP 客户端都可以调用这个功能
 result = execute_sql(arguments["sql"])
 return [TextContent(type="text", text=str(result))]

async def main():
 async with stdio_server() as (read_stream, write_stream):
 await mcp.run(read_stream, write_stream)

二、本地 / 私有环境深度访问

问题场景：需要直接访问本地资源或敏感数据不出域。

典型用例：

场景	说明	Skill 的局限性
本地文件系统	直接读写本地代码库、配置文件	Skill 通常无本地写权限
本地数据库	直接连线本地 MySQL/PostgreSQL	Skill 多为云端调用
内网服务	访问企业内网、私有云、本地服务器	Skill 跨内网困难
数据合规	敏感数据本地处理、不流出	Skill 难保证数据不出域

MCP 深度访问示例：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import * as fs from "fs/promises";
import * as path from "path";

const server = new Server({
 name: "local-dev-tools",
 version: "1.0.0"
});

// 本地代码库分析
server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === "analyze-codebase") {
 const projectPath = request.params.arguments.path;

 // 直接访问本地文件系统
 const files = await fs.readdir(projectPath, { recursive: true });
 const codeFiles = files.filter(f => f.endsWith('.ts') || f.endsWith('.py'));

 // 并发读取文件内容（Skill 做不到这么高效）
 const contents = await Promise.all(
 codeFiles.map(f => fs.readFile(path.join(projectPath, f), 'utf-8'))
 );

 return {
 content: [{
 type: "text",
 text: JSON.stringify({ files: codeFiles, totalSize: contents.join('').length })
 }]
 };
 }
});

三、集中式安全、权限与审计治理

问题场景：企业级应用需要统一的安全管控入口。

典型用例：

治理维度	MCP 能力	Skill 的局限性
密钥管理	统一 API 密钥存储、轮换	密钥分散在各 Skill 中
权限分级	基于用户的精细化权限控制	Skill 难以全局鉴权
�审计	统一日志、调用追溯、速率限制	日志分散、难以聚合
合规要求	必须通过统一网关管控所有调用	调用路径不透明
多租户隔离	租户级别的数据隔离	Skill 难以实现租户隔离

MCP 权限治理架构：

class AuthMiddleware:
 """MCP 服务端的统一权限网关"""

 async def __call__(self, request: ToolRequest) -> ToolResponse:
 # 1. 验证用户身份
 user = await self.authenticate(request.headers)

 # 2. 检查工具调用权限
 if not await self.check_permission(user, request.tool_name):
 raise PermissionDenied(f"User {user.id} cannot access {request.tool_name}")

 # 3. 速率限制
 if not await self.check_rate_limit(user):
 raise RateLimitExceeded("Too many requests")

 # 4. 执行并审计
 start_time = time.time()
 try:
 response = await self.execute_tool(request)
 await self.audit_log(user, request, response, duration=time.time() - start_time)
 return response
 except Exception as e:
 await self.audit_error(user, request, e)
 raise

四、复杂系统 / 多数据源的插拔式集成

问题场景：需要接入大量异构系统，实现动态发现和挂载。

典型用例：

系统类型	MCP 优势	Skill 的局限
数据库集群	动态发现表结构、执行查询	Skill 需硬编码每个 DB
知识库	统一检索接口，可插拔后端	Skill 难以扩展
工单系统	统一的 CRUD 接口适配多系统	需为每个系统写 Skill
IM 通道	统一消息发送接口	Skill 通道绑定固定
第三方 SaaS	Slack、Notion、Jira 统一封装	各需要独立 Skill

MCP 动态资源发现示例：

@mcp.list_resources()
async def list_resources() -> list[Resource]:
 """动态发现所有可用的数据源"""
 resources = []

 # 数据库资源动态发现
 for db_config in await discover_databases():
 for table in await list_tables(db_config):
 resources.append(Resource(
 uri=f"db://{db_config.name}/{table}",
 name=f"{db_config.name}.{table}",
 description=f"Table {table} in {db_config.name}",
 mimeType="application/json"
 ))

 # 文件系统资源
 for root, dirs, files in os.walk("/shared/documents"):
 for file in files:
 resources.append(Resource(
 uri=f"file://{os.path.join(root, file)}",
 name=file,
 description=f"Document file",
 mimeType="text/plain"
 ))

 return resources

# AI 可以自主探索和调用这些资源
@mcp.read_resource()
async def read_resource(uri: str) -> str:
 if uri.startswith("db://"):
 return await query_table(uri)
 elif uri.startswith("file://"):
 return await read_file(uri)

五、真实操作与系统级自动化

问题场景：需要执行真实的写操作和跨系统业务流程。

典型用例：

操作类型	MCP 能力	Skill 的局限
写操作	创建工单、发送消息、更新 CRM	Skill 多为模拟/只读
SQL 执行	执行 INSERT/UPDATE/DELETE	Skill 难以执行写 SQL
代码提交	Git commit/pull request 操作	Skill 通常无 Git 写权限
配置修改	修改系统配置、环境变量	Skill 系统权限受限
跨服务流程	跨网络的业务流程编排	Skill 流程编排能力弱
运维操作	实时监控、告警处理	Skill 稳定性难以保证

MCP 自动化工作流示例：

@mcp.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
 if name == "onboard_new_user":
 """跨系统自动化：新用户入职流程"""

 # 1. 在 HR 系统创建员工记录
 employee_id = await hr_api.create_employee(arguments)

 # 2. 在 AD 域创建账号
 ad_user = await ad_api.create_user({
 "username": arguments["email"].split("@")[0],
 "email": arguments["email"],
 "department": arguments["department"]
 })

 # 3. 在 Jira 创建工单分配设备
 ticket_id = await jira_api.create_ticket({
 "summary": f"设备申请: {arguments['name']}",
 "assignee": "it-support"
 })

 # 4. 在 Slack 发送欢迎消息
 await slack_api.send_message(
 channel="#announcements",
 text=f"欢迎新同事 {arguments['name']} 加入 {arguments['department']}！"
 )

 return [TextContent(type="text", text=f"""
 入职流程完成：
 - 员工ID: {employee_id}
 - AD账号: {ad_user.username}
 - 设备工单: {ticket_id}
 """)]

六、协议级标准化与生态兼容

问题场景：需要构建可插拔、可扩展的 AI 工具生态。

标准化维度	MCP	Skill
协议规范	强制 JSON-RPC 2.0 接口	自定义，无强制标准
接口约束	Schema 验证、类型检查	自由度极高
版本兼容	明确的版本管理	难以保证向后兼容
互操作性	不同 MCP Server 可互换	Skill 难以替换
生态扩展	第三方可贡献 Server	生态封闭

MCP 标准化带来的生态价值：

// 任何符合 MCP 标准的 Server 都可以被任何 MCP Client 使用
interface MCPTool {
 name: string;
 description: string;
 inputSchema: {
 type: "object";
 properties: Record<string, { type: string; description: string }>;
 required: string[];
 };
}

// 客户端可以动态加载任何 MCP Server
async function loadMCPServer(serverPath: string) {
 const server = spawn(serverPath);
 return new MCPClient(server.stdin, server.stdout);
}

// 生态示例：插件式架构
const pluginRegistry = {
 "filesystem": "/opt/mcp-servers/fileserver",
 "database": "/opt/mcp-servers/dbconnector",
 "cloud-storage": "/opt/mcp-servers/s3-connector"
};

// 用户可以随意替换某个插件，无需修改客户端代码

Skill 的优势场景

虽然 MCP 在上述场景不可替代，但 Skill 在以下领域更有优势：

1. 轻量级任务流程编排

适用场景：固定模式的任务流程，不需要外部系统访问。

# SKILL.md 中的工作流定义
---
name: code-review
description: "Perform code review with standard checklist"
---

## Workflow

1. Read the code file provided by user
2. Check for:
 - Security vulnerabilities
 - Performance issues
 - Code style violations
 - Missing error handling
3. Generate review report in markdown format
4. Suggest specific fixes for each issue found

2. 知识模板和提示词复用

适用场景：需要将特定的知识结构或提示词模式应用到不同的输入。

technical-doc-writer/
├── SKILL.md
├── references/
│ ├── api-doc-template.md # API 文档模板
│ ├── changelog-template.md # 变更日志模板
│ └── contribution-guide.md # 贡献指南模板

3. 平台特定优化

适用场景：针对特定平台（如 Claude Code）的深度集成优化。

---
name: claude-code-optimization
description: "Claude Code specific workflow optimizations"
---

## Optimization

1. Use Edit tool instead of Write for existing files
2. Batch independent operations together
3. Use TodoWrite for task tracking
4. Follow Git Safety Protocol

决策流程图

 开始
│
▼
需要扩展 AI 能力？
/│\
/ │ \
是 │ 否
/ │ \
▼ │ 不需要扩展
涉及外部系统？
/│\
是 │ 否
/ │ \
▼ │ ▼
跨平台/跨模型？ 固定流程编排？
│ \ │
│ \ │ 是
│ \ │
是 \ ▼
│ \ 使用 Skill
│ \
▼ \
需要系统级访问？
│ \ │
是 \ │
│ \ │
▼ \ │
使用 MCP \ │
│
需要统一安全管控？
/│\
是 │ 否
/ │ \
▼ │ ▼
使用 MCP \ 使用 MCP（标准化要求）
│
需要动态资源发现？
/│\
是 │ 否
/ │ \
▼ │ ▼
使用 MCP \ 根据复杂度选择

实战决策矩阵

决策维度	权重	MCP 评分	Skill 评分	推荐选择
跨平台需求	⭐⭐⭐⭐⭐	5	1	MCP
本地访问	⭐⭐⭐⭐	5	2	MCP
安全管控	⭐⭐⭐⭐⭐	5	1	MCP
系统集成	⭐⭐⭐⭐	5	2	MCP
真实操作	⭐⭐⭐⭐	5	2	MCP
标准化	⭐⭐⭐	5	2	MCP
轻量级	⭐⭐⭐	2	5	Skill
知识复用	⭐⭐⭐	2	5	Skill
平台优化	⭐⭐	1	5	Skill
简单性	⭐⭐	2	4	Skill

混合架构：最佳实践

在实际项目中，MCP 和 Skill 往往是互补而非互斥的：

┌─────────────────────────────────────────────────────────┐
│ AI 客户端 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Skill 层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 审查流程 │ │ 文档生成 │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ │ │
│ │ │ │ │ │
│ │ └────────┬───────┘ │ │
│ │ ▼ │ │
│ │ 调用 MCP 工具 │ │
│ └──────────────────┬─────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ MCP 层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Git 操作 │ │ 文件读写 │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

示例：代码审查 Skill 调用 MCP Git 工具

---
name: code-review-with-git
description: "Code review that uses MCP Git tools for file operations"
---

## Workflow

1. 使用 MCP 工具获取当前 Git 仓库状态
2. 使用 MCP 工具读取变更的文件内容
3. 在本地执行代码审查分析
4. 生成审查报告
5. 使用 MCP 工具创建 Git commit（如果用户确认）

一句话判断规则

最终，可以用两个问题快速决策：

问题一：这个能力是否涉及"能不能访问、怎么连、谁能连、怎么管”？

是 → 用 MCP

问题二：这个能力主要是关于"怎么做、流程是什么、输出要什么格式"？

是 → 用 Skill

总结

方面	MCP	Skill
本质	连接层协议	认知层封装
强项	跨平台、系统访问、安全管控	流程编排、知识复用
适用	外部系统集成、企业级应用	平台内优化、轻量任务
关系	互补而非互斥	互补而非互斥

在实际架构设计时，建议：

优先使用 MCP 处理所有外部系统集成
使用 Skill 编排任务流程和复用知识模板
混合架构 充分发挥两者优势

参考资料

反反爬虫技术全景：技能树与实战指南

di4urp@gmail.com (taevas) — Tue, 17 Mar 2026 12:00:00 +0800

技能掌握情况汇总

本表格记录个人对各项反反爬虫技术的掌握程度和使用情况，方便后续追踪学习进度。

技术技能

层级	技能项	优先级	AI 备注
基础层	HTTP 请求基础	⭐⭐⭐⭐⭐	User-Agent、Headers 等
基础层	HTTP/2 协议	⭐⭐⭐	二进制协议、多路复用
基础层	WebSocket 处理	⭐⭐⭐	实时通信、心跳机制
基础层	HTTP 缓存控制	⭐⭐⭐	ETag、If-Modified-Since
基础层	Cookie 签名管理	⭐⭐⭐	Cookie 属性控制
基础层	浏览器工作原理	⭐⭐⭐⭐	渲染进程、JS 引擎、DOM
基础层	指纹技术原理	⭐⭐⭐⭐	Canvas、WebGL、Audio 指纹
基础层	请求管理	⭐⭐⭐⭐	智能拦截、自定义请求头、资源控制
环境层	Navigator 对象伪造	⭐⭐⭐⭐⭐	webdriver、plugins、languages
环境层	CDP 检测绕过	⭐⭐⭐⭐⭐	堆栈检测、脚本注入检测
环境层	Canvas/WebGL 指纹处理	⭐⭐⭐⭐	指纹随机化、噪声注入
环境层	完整浏览器指纹伪装	⭐⭐⭐⭐⭐	全栈指纹规避
环境层	TLS 指纹伪装	⭐⭐⭐⭐	JA3、HTTP/2 指纹模拟
环境层	WebRTC 防护	⭐⭐⭐	IP 泄露防护
环境层	CDN 绕过	⭐⭐⭐⭐⭐	Cloudflare、Akamai 等
环境层	反调试技术	⭐⭐⭐	调试器检测和绕过
环境层	代理池管理	⭐⭐⭐⭐⭐	HTTP/SOCKS5/住宅代理
环境层	代理轮换与失败切换	⭐⭐⭐⭐⭐	自动轮换、健康检查
环境层	代理健康检查	⭐⭐⭐⭐	延迟检测、可用性验证
环境层	IP 地理位置匹配	⭐⭐⭐⭐	时区与代理地区一致
环境层	设备信息伪造	⭐⭐⭐	分辨率、时区、语言
环境层	字体指纹伪造	⭐⭐⭐	字体列表伪造
环境层	Web Audio 指纹处理	⭐⭐⭐	AudioContext 指纹
环境层	Battery API 伪造	⭐⭐	电量信息模拟
环境层	Network API 伪造	⭐⭐⭐	网络类型伪造
环境层	Screen API 伪造	⭐⭐⭐	屏幕方向、像素比
环境层	Permissions API 控制	⭐⭐⭐⭐	权限权限请求
环境层	Geolocation 伪造	⭐⭐⭐	位置信息模拟
环境层	Connection Type 伪造	⭐⭐⭐	网络连接类型
环境层	WebGL 参数随机化	⭐⭐⭐	纹理模式、精度控制
环境层	Canvas 噺拟检测绕过	⭐⭐⭐⭐	getImageData Hook
环境层	Web Workers 检测绕过	⭐⭐⭐	Worker 指纹统一
行为层	鼠标行为模拟	⭐⭐⭐⭐	贝塞尔曲线轨迹
行为层	键盘行为模拟	⭐⭐⭐	打字节奏、事件完整性
行为层	滚动行为模拟	⭐⭐⭐	分段滚动、惯性模拟
行为层	视线停留模拟	⭐⭐	阅读停留时间
行为层	窗口大小变化模拟	⭐⭐	调整窗口大小
行为层	页面停留时间随机化	⭐⭐⭐	不同页面停留时间不同
行为层	点击位置偏移	⭐⭐⭐	非中心点击
行为层	多标签页操作	⭐⭐⭐	打开/切换/关闭标签
行为层	浏览器历史操作	⭐⭐	前进后退导航
行为层	右键操作模拟	⭐⭐	右键菜单、复制粘贴
行为层	拖放操作模拟	⭐⭐⭐	元素拖拽行为
行为层	音频/视频交互	⭐⭐	播放/暂停、音量调节
行为层	表单提交行为	⭐⭐⭐	输入框聚焦、验证前检查
行为层	鼠标抖动	⭐⭐	点击前微小随机移动
行为层	键盘修正行为	⭐⭐	打错后删除重打
行为层	触摸事件模拟	⭐⭐⭐	移动端触摸行为
行为层	Hover 停留	⭐⭐⭐	鼠标悬停一段时间
持久层	Cookie 池管理	⭐⭐⭐⭐⭐	指纹 Cookie、会话 Cookie
持久层	多会话池管理	⭐⭐⭐⭐	多账号并发管理
持久层	浏览器 Profile	⭐⭐⭐⭐	User Data 目录管理
持久层	LocalStorage 管理	⭐⭐⭐	存储保存与恢复
持久层	SessionStorage 管理	⭐⭐⭐	会话存储管理
持久层	IndexedDB 管理	⭐⭐⭐⭐	结构化数据存储
持久层	状态快照	⭐⭐⭐	状态同步与回滚
持久层	Session 恢复	⭐⭐⭐⭐	会话过期自动恢复
持久层	Cookie 过期检测	⭐⭐⭐⭐	自动刷新过期 Cookie
持久层	跨域 Cookie 同步	⭐⭐⭐	多域名 Cookie 共享
持久层	Cache API 管理	⭐⭐⭐	缓存存储操作
持久层	Service Worker 管理	⭐⭐⭐	离线缓存处理
持久层	WebSQL 处理	⭐⭐	已废弃但仍在用
持久层	FileSystem API	⭐⭐	文件系统访问
验证层	OCR 验证码识别	⭐⭐⭐⭐	Tesseract、CNN 模型
验证层	滑动验证码破解	⭐⭐⭐⭐	模板匹配、轨迹生成
验证层	验证码 AI 识别	⭐⭐⭐⭐⭐	多种验证码自动识别
验证层	reCAPTCHA 对抗	⭐⭐⭐⭐⭐	v2/v3 应对策略
验证层	行为验证对抗	⭐⭐⭐	完整行为模拟
架构层	分布式爬虫	⭐⭐⭐⭐	任务调度、节点协同
架构层	策略路由	⭐⭐⭐⭐	A/B 测试、策略切换
架构层	速率限制	⭐⭐⭐⭐	令牌桶、滑动窗口、自适应
架构层	AI 智能体	⭐⭐⭐⭐⭐	强化学习决策、自适应导航
架构层	自适应引擎	⭐⭐⭐⭐	根据网站策略动态调整
架构层	动态选择器	⭐⭐⭐	智能选择器生成和验证
架构层	特征工程	⭐⭐⭐	页面、请求、行为特征提取
架构层	模式识别	⭐⭐⭐⭐	反爬虫机制检测、异常识别
架构层	预测模型	⭐⭐⭐	风险预测、趋势分析
架构层	智能分类	⭐⭐⭐	网站类型自动分类
架构层	监控告警	⭐⭐⭐	成功率、检测率监控

填写说明：

优先级：⭐(低) ~ ⭐⭐⭐⭐⭐(高)
AI 备注：简要说明技术要点、关键思路或相关工具
个人备注：留空供个人填写

前言

网络爬虫与反爬虫是一场持续的军备竞赛。随着检测技术的发展，现代网站已经构建了多层防御体系。本文系统整理反反爬虫技术体系，构建完整的技能树，帮助从业者从入门到精通。

本文面向：

网络爬虫开发者
Web 自动化测试工程师
数据采集工程师
网络安全从业者

一、反反爬虫技术体系概览

1.1 检测与对抗的本质

维度	网站侧（检测）	爬虫侧（反检测）
目标	识别自动化访问，保护数据/资源	模拟真实用户行为，获取目标数据
手段	指纹识别、行为分析、环境检测	指纹伪造、行为模拟、环境隔离
技术栈	JS 检测、服务器检测、设备指纹	浏览器自动化、代理池、验证码识别

1.2 技能树全景图

反反爬虫技能树
│
├── 基础层（必学）
│ ├── HTTP 请求基础
│ ├── 浏览器工作原理
│ ├── 指纹技术原理
│ └── 请求管理
│
├── 环境层（核心）
│ ├── 浏览器指纹伪装
│ │ ├── Navigator 对象伪造
│ │ ├── CDP 检测绕过
│ │ └── Canvas/WebGL 指纹处理
│ ├── 网络环境隔离
│ │ ├── 代理池管理
│ │ ├── 代理轮换与失败切换
│ │ ├── TLS 指纹伪装
│ │ ├── WebRTC 防护
│ │ └── CDN 绕过
│ ├── 设备信息伪造
│ └── 反调试技术
│
├── 行为层（进阶）
│ ├── 鼠标/键盘行为模拟
│ │ ├── 贝塞尔曲线轨迹
│ │ ├── 点击位置偏移
│ │ └── 鼠标抖动
│ ├── 浏览器操作轨迹
│ │ ├── 窗口大小变化模拟
│ │ ├── 多标签页操作
│ │ ├── 浏览器历史操作
│ │ └── 右键操作模拟
│ └── 人类行为模式
│ ├── 拖放操作模拟
│ ├── 音频/视频交互
│ ├── 表单提交行为
│ ├── 键盘修正行为
│ ├── 触摸事件模拟
│ └── Hover 停留
│
├── 持久层（高级）
│ ├── Cookies/Session 管理
│ │ ├── Cookie 池管理
│ │ └── 多会话池管理
│ ├── 浏览器指纹持久化
│ │ ├── 浏览器 Profile
│ │ └── LocalStorage 管理
│ └── 状态同步（状态快照）
│
├── 验证层（专攻）
│ ├── 验证码识别（OCR/ML）
│ │ ├── OCR 验证码识别
│ │ ├── 滑动验证码破解
│ │ └── 验证码 AI 识别
│ ├── 人机验证绕过
│ │ └── reCAPTCHA 对抗
│ └── 行为验证对抗
│
└── 架构层（精通）
├── 分布式爬虫架构
├── 反检测策略库
│ ├── 策略路由
│ └── 速率限制
├── AI 智能化
│ ├── AI 智能体
│ ├── 自适应引擎
│ └── 动态选择器
├── 机器学习（ML）
│ ├── 特征工程
│ ├── 模式识别
│ ├── 预测模型
│ └── 智能分类
└── 监控告警

二、基础层技术详解

2.1 HTTP 请求基础

核心 HTTP 指纹

指标	检测内容	真实浏览器特征	常见爬虫问题
User-Agent	浏览器标识	版本、操作系统、Chrome 版本号	过时/伪造不完整
Accept	内容协商	`text/html,application/xhtml+xml,...`	缺失或错误
Accept-Language	语言偏好	`zh-CN,zh;q=0.9,en;q=0.8`	缺失或单一
Accept-Encoding	压缩支持	`gzip, deflate, br`	缺失
Connection	连接控制	`keep-alive`	可能缺失
Upgrade-Insecure-Requests	HTTPS 升级	`1`	通常缺失

实战要点

# 完整的 HTTP 头部示例（以 Chrome 为例）
headers = {
 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
 'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
 'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
 'Accept-Encoding': 'gzip, deflate, br',
 'Connection': 'keep-alive',
 'Upgrade-Insecure-Requests': '1',
 'Sec-Fetch-Dest': 'document',
 'Sec-Fetch-Mode': 'navigate',
 'Sec-Fetch-Site': 'none',
 'Sec-Fetch-User': '?1',
 'Cache-Control': 'max-age=0',
}

2.2 浏览器工作原理

关键概念

渲染进程隔离：每个标签页独立进程，沙箱环境
JavaScript 执行引擎：V8（Chrome）、SpiderMonkey（Firefox）
DOM 树构建：HTML 解析 → 树构建 → 布局 → 绘制
事件循环：宏任务/微任务调度机制

检测点

// 1. 浏览器引擎识别
console.log(window.navigator.userAgentData?.platform); // 'macOS'
console.log(window.navigator.userAgentData?.brands); // Chrome 品牌

// 2. 特性检测
console.log('chrome' in window); // Chrome 特定 API
console.log('webkit' in window); // WebKit 特性

// 3. WebGL 渲染器
const gl = canvas.getContext('webgl');
console.log(gl.getParameter(gl.RENDERER)); // GPU 信息

2.3 指纹技术原理

指纹分类

指纹类型	唯一性	稳定性	检测难度
Canvas 指纹	★★★★★	★★★★☆	★★★☆☆
WebGL 指纹	★★★★★	★★★★★	★★★★☆
Audio 指纹	★★★★☆	★★★☆☆	★★★★☆
字体指纹	★★★★☆	★★★★★	★★★☆☆
浏览器指纹	★★★★★	★★★★★	★★★☆☆
硬件指纹	★★★★★	★★★★★	★★★★★

2.4 HTTP/2 协议指纹

HTTP/2 连接管理

指纹特征	检测内容	绕过策略
SETTINGS 帧	窗口大小、流控	使用真实浏览器值
HEADERS 帧	权重压缩、方法优先级	匹配真实请求
WINDOW_UPDATE	增量大小设置	模拟真实浏览

HTTP/2 伪装修饰

# 使用 curl_cffi 进行 HTTP/2 指纹伪装
from curl_cffi import requests

# 禁用 HTTP/2 草级
session = requests.Session(impersonate="chrome120")

# 自定义 SETTINGS
response = session.get(
 url,
 http2_settings={
 'ENABLE_PUSH': False,
 'MAX_CONCURRENT_STREAMS': 100,
 }
)

2.5 WebSocket 处理

WebSocket 连接特征

特征	真实浏览器	自动化工具检测点
握手协议	h2c/h3/h4/gp	可能缺失或固定
扩展头	permessage/compress	可能缺失
心跳机制	间隔发送	可能不实现

WebSocket 模拟实现

import asyncio
import websockets
import json
import random
import time

class RealisticWebSocket:
 def __init__(self, url):
 self.url = url
 self.heartbeat_interval = random.randint(25, 40)
 self.last_ping = None

 async def connect(self):
 # 连接时发送正确的协议
 self.ws = await websockets.connect(
 self.url,
 extra_headers={
 'User-Agent': 'Mozilla/5.0...',
 'Sec-WebSocket-Protocol': 'permessage, deflate',
 }
 )

 # 启动心跳
 asyncio.create_task(self._heartbeat())

 async def send_message(self, data):
 await self.ws.send(json.dumps(data))

 async def _heartbeat(self):
 """模拟心跳机制"""
 while True:
 await asyncio.sleep(self.heartbeat_interval)

 # 发送 ping
 ping_data = {
 'type': 'ping',
 'timestamp': int(time.time() * 1000),
 'data': f'ping_{random.randint(1000, 9999)}'
 }
 await self.ws.send(json.dumps(ping_data))
 self.last_ping = time.time()

 # 接收超时检测
 if time.time() - self.last_ping > self.heartbeat_interval * 3:
 await self.reconnect()

 async def reconnect(self):
 """断线重连"""
 await self.ws.close()
 await asyncio.sleep(random.uniform(2, 5))
 await self.connect()

 async def close(self):
 await self.ws.close()

2.6 HTTP 缓存控制

缓存控制策略

头部字段	作用	使用场景
ETag	版本标识	资源监控
If-None-Match	缓存指令	精确控制
If-Modified-Since	增量更新	避免重复下载
Cache-Control	缓存策略	控制缓存行为

智能缓存管理

import hashlib
import time

class SmartCacheManager:
 def __init__(self):
 self.cache = {}
 self.etags = {}

 def should_fetch(self, url, headers):
 """判断是否需要获取新内容"""
 # 1. 检查 ETag
 if 'ETag' in headers:
 etag = headers['ETag']
 if url in self.etags and self.etags[url] == etag:
 return False

 # 2. 检查 Cache-Control
 cache_control = headers.get('Cache-Control', '')
 if 'no-cache' in cache_control:
 return True
 if 'max-age' in cache_control:
 # 解析 max-age
 max_age = int(cache_control.split('max-age=')[1].split(',')[0])
 cached_time = self.cache.get(f'{url}_time', 0)
 return time.time() - cached_time > max_age

 return True

 def update_cache(self, url, response):
 """更新缓存"""
 # 保存 ETag
 if 'ETag' in response.headers:
 self.etags[url] = response.headers['ETag']

 # 保存时间
 self.cache[f'{url}_time'] = time.time()

属性	作用	绕过用途
Secure	仅 HTTPS 传输	防止明文传输
HttpOnly	禁止 JS 访问	防止 XSS 读取
SameSite	跨域控制	限制 Cookie 范围
SameParty	跨域控制	同站子域共享
Path	路径限制	限制 Cookie 路径
Domain	域名限制	限制 Cookie 域名
Max-Age	过期时间	设置 Cookie 生命周期
Expires	绝对过期时间	设置 Cookie 生命周期

def create_secure_cookie(name, value, domain):
 """创建安全 Cookie"""
 return {
 'name': name,
 'value': value,
 'domain': domain,
 'path': '/',
 'secure': True, # 仅 HTTPS
 'httponly': False, # 允许 JS 访问
 'samesite': 'Lax', # 严格同站
 'max-age': 3600 * 24, # 24 小时过期
 'sameparty': 'None', # 不跨域
 }

# 创建指纹 Cookie（长期）
fingerprint_cookies = {
 '_ga': create_secure_cookie('_ga', 'GA1.2.xxxxxxxxx', '.google.com'),
 '_gid': create_secure_cookie('_gid', 'GA1.2.yyyyyyyyy', '.google.com'),
 '__cfduid': create_secure_cookie('__cfduid', 'cfduid_hash', '.example.com'),
}

# 创建会话 Cookie（短期）
session_cookie = create_secure_cookie('sessionid', 'session_token_hash', '.example.com')
session_cookie['max-age'] = 3600 # 1 小时过期

2.8 请求头完整性

常见请求头组合

头部	作用	Chrome 典型值	检测重要性
User-Agent	浏览器标识	Chrome 131.0.0.0 Safari/537.36	⭐⭐⭐⭐⭐
Accept Sec-Fetch	请求模式	document/cors/navigate	⭐⭐⭐⭐
Sec-Fetch-Site	跨域控制	cross-site/same-origin/none	⭐⭐⭐⭐
Sec-Fetch-User	用户激活	?1 或 ?0	⭐⭐⭐⭐
Sec-Fetch-Mode	请求模式	navigate/cors/navigate	⭐⭐⭐⭐
Sec-Ch-Ua	客户端提示	Android/Windows/macOS	⭐⭐⭐
Sec-Ch-Ua-Platform	操作系统	Android/iOS/Windows/macOS	⭐⭐⭐
Sec-Ch-Ua-Mobile	移动标识	?0 或 ?1	⭐⭐⭐
Sec-Ch-Ua-Arch	架构	x86/x64/arm	⭐⭐

完整请求头示例

def get_complete_headers(user_agent):
 """生成完整的 Chrome 请求头"""
 return {
 'User-Agent': user_agent,
 'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
 'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
 'Accept-Encoding': 'gzip, deflate, br',
 'Connection': 'keep-alive',
 'Upgrade-Insecure-Requests': '1',
 'Sec-Fetch-Dest': 'document',
 'Sec-Fetch-Mode': 'navigate',
 'Sec-Fetch-Site': 'same-origin',
 'Sec-Fetch-User': '?1',
 'Sec-Ch-Ua': '"Windows"; v="131", u="0", a="Google Chrome 131.0.0.0 Safari/537.36"',
 'Sec-Ch-Ua-Platform': '"Windows"',
 'Sec-Ch-Ua-Mobile': '?0',
 'Sec-Ch-Ua-Arch': '"x86"',
 'DNT': '1',
 'Sec-GPC': '1',
 'Cache-Control': 'max-age=0',
 'sec-ch-ua': ' "Not_A;Brand";v="8", "Chromium";v="8", "Google Chrome";v="131"',
 'sec-ch-ua-mobile': '?0',
 'sec-ch-ua-full-version-list': '"Not_A;Brand";v="8", "Chromium";v="8", "Google Chrome";v="131"',
 'sec-ch-ua-platform': '"Windows"',
 'sec-ch-ua-arch': '"x86"',
 'sec-ch-ua-bitness': '"32"',
 'sec-ch-ua-model': '""',
 'sec-ch-ua-wow64': '?0',
 }

2.9 Referer 链管理

合理的 Referer 生成

import random
from urllib.parse import urlparse

class RefererManager:
 """Referer 管理器"""

 def __init__(self):
 self.history = []
 self.max_history = 10

 def get_referer(self, target_url):
 """获取合理的 Referer"""
 # 解析目标域名
 target_domain = urlparse(target_url).netloc

 # 检查历史记录
 for url in reversed(self.history):
 domain = urlparse(url).netloc
 if domain == target_domain:
 return url

 # 同域无历史，使用首页
 return f'https://{target_domain}/'

 def update_history(self, url):
 """更新访问历史"""
 self.history.append(url)

 # 保持历史长度
 if len(self.history) > self.max_history:
 self.history.pop(0)

2.10 断点续传

大文件下载续传

import os
import requests

class ResumableDownloader:
 """支持断点续传的下载器"""

 def __init__(self, chunk_size=8192):
 self.chunk_size = chunk_size

 def download(self, url, save_path, headers=None):
 """带续传的下载"""
 # 检查已下载部分
 downloaded = 0
 temp_file = f'{save_path}.tmp'

 if os.path.exists(temp_file):
 downloaded = os.path.getsize(temp_file)

 # 设置 Range 头
 if headers is None:
 headers = {}

 if downloaded > 0:
 headers['Range'] = f'bytes={downloaded}-'

 # 下载
 mode = 'ab' if downloaded > 0 else 'wb'

 with open(temp_file, mode) as f:
 with requests.get(url, headers=headers, stream=True) as r:
 total_size = int(r.headers.get('content-length', 0))

 for chunk in r.iter_content(chunk_size=self.chunk_size):
 f.write(chunk)
 downloaded += len(chunk)

 # 显示进度
 self._show_progress(downloaded, total_size)

 # 重命名
 os.rename(temp_file, save_path)

 def _show_progress(self, downloaded, total):
 percent = (downloaded / total) * 100 if total > 0 else 100
 print(f'\r下载进度: {percent:.1f}% ({downloaded}/{total})', end='')

2.11 请求重试机制

智能重试策略

import time
import random
from functools import wraps

def retry_with_backoff(max_retries=3, base_delay=1, backoff_factor=2):
 """带指数退避的重试装饰器"""
 def decorator(func):
 @wraps(func)
 def wrapper(*args, **kwargs):
 retries = 0
 last_exception = None

 while retries < max_retries:
 try:
 return func(*args, **kwargs)
 except Exception as e:
 last_exception = e
 retries += 1

 if retries < max_retries:
 # 计算退避延迟
 delay = base_delay * (backoff_factor ** (retries - 1))
 delay = delay + random.uniform(0, 1)

 print(f'重试 {retries}/{max_retries}，延迟 {delay:.2f}s')
 time.sleep(delay)

 raise last_exception

 return wrapper
 return decorator

# 使用示例
@retry_with_backoff(max_retries=3, base_delay=1, backoff_factor=2)
def fetch_url(url):
 response = requests.get(url)
 response.raise_for_status()
 return response.json()

2.12 请求并发控制

并发请求管理

import asyncio
import aiohttp
from asyncio import Semaphore

class ConcurrentRequestManager:
 """并发请求管理器"""

 def __init__(self, max_concurrent=10):
 self.semaphore = Semaphore(max_concurrent)

 async def fetch(self, url, session):
 """带并发控制的请求"""
 async with self.semaphore:
 try:
 async with session.get(url) as response:
 return await response.text()
 except Exception as e:
 print(f'请求失败 {url}: {e}')
 return None

 async def fetch_all(self, urls):
 """并发请求所有 URL"""
 async with aiohttp.ClientSession() as session:
 tasks = [self.fetch(url, session) for url in urls]
 results = await asyncio.gather(*tasks)

 return results

# 使用示例
manager = ConcurrentRequestManager(max_concurrent=5)
results = await manager.fetch_all(urls)

class CookieSync:
 """Cookie 同步器"""

 def __init__(self, storage_path):
 self.storage_path = Path(storage_path)
 self.storage_path.mkdir(exist_ok=True)

 def sync_cookies(self, page, account_id):
 """同步 Cookie 到浏览器"""
 cookie_file = self.storage_path / f'cookies_{account_id}.json'

 if cookie_file.exists():
 with open(cookie_file) as f:
 cookies = json.load(f)

 # 清除现有 Cookies
 page.context.clear_cookies()

 # 添加 Cookies
 for cookie in cookies:
 page.context.add_cookie(cookie)

 def update_cookies(self, page, account_id):
 """更新 Cookie 存储"""
 cookies = page.context.cookies()

 cookie_file = self.storage_path / f'cookies_{account_id}.json'

 with open(cookie_file, 'w') as f:
 json.dump(cookies, f)

def add_cookie_with_domain(cookie, page):
 """根据 Cookie 添加域Cookie"""
 # 获取当前域名
 current_domain = page.evaluate('window.location.hostname')

 # 处理 Cookie 域名
 cookie_domain = cookie.get('domain')

 if cookie_domain and cookie_domain.startswith('.'):
 # 域名以点开头，所有子域共享
 pass
 elif cookie_domain:
 # 特定域名
 pass
 else:
 # 当前域名
 cookie['domain'] = current_domain

 page.context.add_cookie(cookie)

def secure_cookie_from_string(cookie_string, domain):
 """从 Cookie 字符串创建安全 Cookie"""
 parts = cookie_string.split(';')

 name_value = parts[0].split('=', 1)
 cookie = {
 'name': name_value[0],
 'value': name_value[1] if len(name_value) > 1 else '',
 'domain': domain,
 'path': '/',
 }

 # 解析属性
 for part in parts[1:]:
 part = part.strip().lower()

 if part == 'httponly':
 cookie['httpOnly'] = True
 elif part == 'secure':
 cookie['secure'] = True
 elif part.startswith('path='):
 cookie['path'] = part[5:].strip('"')
 elif part.startswith('max-age='):
 cookie['expires'] = time.time() + int(part[8:])
 elif part.startswith('expires='):
 # 解析日期
 pass

 return cookie

三、环境层：浏览器指纹伪装

3.1 Navigator 对象指纹

关键属性伪造

属性	真实值	自动化工具默认	重要性
`navigator.webdriver`	`undefined`	`true`	⭐⭐⭐⭐⭐
`navigator.plugins`	对象数组	`[]`	⭐⭐⭐⭐
`navigator.languages`	语言数组	`[]`	⭐⭐⭐
`navigator.platform`	平台字符串	可能不匹配	⭐⭐⭐⭐
`navigator.hardwareConcurrency`	CPU 核心数	固定值	⭐⭐⭐
`navigator.deviceMemory`	内存大小	固定值	⭐⭐

Puppeteer 检测绕过示例

// 1. 基础 webdriver 属性移除
await page.evaluateOnNewDocument(() => {
 Object.defineProperty(navigator, 'webdriver', {
 get: () => undefined,
 });
});

// 2. 完整 plugins 伪造
await page.evaluateOnNewDocument(() => {
 navigator.plugins = [
 {
 name: 'Chrome PDF Plugin',
 description: 'Portable Document Format',
 filename: 'internal-pdf-viewer',
 },
 {
 name: 'Chrome PDF Viewer',
 description: '',
 filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai',
 },
 {
 name: 'Native Client',
 description: '',
 filename: 'internal-nacl-plugin',
 },
 ];
});

// 3. languages 伪造
await page.evaluateOnNewDocument(() => {
 navigator.languages = ['zh-CN', 'zh', 'en-US', 'en'];
});

// 4. platform 伪造
await page.evaluateOnNewDocument(() => {
 Object.defineProperty(navigator, 'platform', {
 get: () => 'MacIntel',
 });
});

3.2 Chrome DevTools Protocol 检测

检测原理

CDP（Chrome DevTools Protocol）为自动化控制提供接口，但会留下特征：

// 检测方法 1：错误堆栈检测
const error = new Error();
const isAutomated = error.stack.includes('puppeteer') ||
 error.stack.includes('playwright') ||
 error.stack.includes('selenium');

// 检测方法 2：window.chrome 属性
// 自动化工具可能缺少完整的 chrome 对象结构

// 检测方法 3：外部脚本注入检测
const scripts = Array.from(document.scripts);
const hasInjectedScripts = scripts.some(s =>
 s.src.includes('puppeteer') || !s.src && s.innerHTML.includes('evaluate')
);

绕过策略

// 使用 undetected-chromedriver (Python)
// 或 puppeteer-extra-plugin-stealth (Node.js)

3.3 WebGL 与 Canvas 指纹

Canvas 指纹检测

// 获取 Canvas 指纹
function getCanvasFingerprint() {
 const canvas = document.createElement('canvas');
 const ctx = canvas.getContext('2d');
 ctx.textBaseline = 'top';
 ctx.font = '14px Arial';
 ctx.fillText('Fingerprint', 2, 2);
 return canvas.toDataURL();
}

WebGL 指纹检测

// 获取 WebGL 指纹
function getWebGLFingerprint() {
 const canvas = document.createElement('canvas');
 const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl');
 if (!gl) return null;

 const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
 const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
 const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);

 return { renderer, vendor };
}

指纹随机化策略

// Canvas 指纹注入噪声
const originalToDataURL = HTMLCanvasElement.prototype.toDataURL;
HTMLCanvasElement.prototype.toDataURL = function() {
 const result = originalToDataURL.apply(this, arguments);
 // 在结果中注入微小噪声
 return result.slice(0, -5) + Math.random().toString(36).slice(2, 5);
};

3.4 网络环境隔离

代理池管理

代理类型	优势	劣势	适用场景
HTTP 代理	成本低、易获取	明文传输、易被封锁	低价值目标
HTTPS 代理	加密传输	成本较高	中等价值目标
SOCKS5 代理	支持所有协议	配置复杂	高价值目标
住宅代理	IP 可信度高	成本极高	严格检测场景
移动代理	4G/5G 真实 IP	动态不稳定	移动端场景

代理轮换策略

import random
import time

class ProxyPool:
 def __init__(self, proxies):
 self.proxies = proxies
 self.failed = {}
 self.cooldown = {}

 def get_proxy(self):
 # 排除冷却中的代理
 available = [p for p in self.proxies
 if p not in self.cooldown
 or time.time() > self.cooldown[p]]

 # 按失败率加权随机
 weights = [1 / (1 + self.failed.get(p, 0)) for p in available]
 return random.choices(available, weights=weights)[0]

 def mark_failed(self, proxy):
 self.failed[proxy] = self.failed.get(proxy, 0) + 1
 # 失败次数多则冷却更久
 self.cooldown[proxy] = time.time() + min(300, self.failed[proxy] * 60)

3.5 设备信息伪造

屏幕分辨率

// 匹配常见分辨率
const resolutions = [
 [1920, 1080], // FHD
 [1366, 768], // 笔记本
 [2560, 1440], // 2K
 [1440, 900], // MacBook Pro 13"
 [1680, 1050], // MacBook Pro 15"
];

const [width, height] = resolutions[Math.floor(Math.random() * resolutions.length)];

Object.defineProperty(screen, 'width', { get: () => width });
Object.defineProperty(screen, 'height', { get: () => height });
Object.defineProperty(window, 'innerWidth', { get: () => width });
Object.defineProperty(window, 'innerHeight', { get: () => height });

时区与语言

// 时区设置应与 IP 地理位置一致
const timezones = {
 'US': 'America/New_York',
 'CN': 'Asia/Shanghai',
 'JP': 'Asia/Tokyo',
 'EU': 'Europe/London',
};

// 注意：时区不能通过 JS 直接修改，需要在浏览器启动时设置
// Chrome: --timezone="Asia/Shanghai"

3.6 TLS 指纹伪装

TLS 指纹检测原理

网站可以通过 TLS Client Hello 包的特征识别客户端：

指纹类型	检测内容	绕过难度
JA3	TLS 版本、密码套件、扩展顺序	⭐⭐⭐⭐
JA4	改进的 JA3，包含更多细节	⭐⭐⭐⭐⭐
HTTP/2 指纹	SETTINGS 帧参数、窗口大小	⭐⭐⭐
HTTP/3 指纹	QUIC 参数	⭐⭐⭐⭐

TLS 指纹伪装方案

# 使用 curl_cffi 进行 TLS 指纹伪装
from curl_cffi import requests, Curl

# 使用预设的浏览器指纹
session = requests.Session(impersonate="chrome110")

# 自定义指纹
curl = Curl()
curl.setopt(curl.IMPERSONATE, "chrome120")
curl.setopt(curl.URL, "https://example.com")
curl.perform()

# Playwright + curl-impersonate
from playwright.sync_api import sync_playwright
import subprocess

# 启动带有 TLS 伪装的代理
# 详见: https://github.com/lwthiker/curl-impersonate

3.7 WebRTC 防护

WebRTC IP 泄露原理

WebRTC 可以绕过代理，泄露真实 IP：

// 检测 WebRTC 泄露
const pc = new RTCPeerConnection({
 iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});

pc.createOffer().then(offer => {
 // SDP 中可能包含真实 IP
 console.log(offer.sdp);
});

防护方案

// 1. 禁用 WebRTC
await page.evaluateOnNewDocument(() => {
 Object.defineProperty(navigator, 'mediaDevices', {
 get: () => undefined,
 });
});

// 2. 使用浏览器插件
// Chrome: WebRTC Leak Shield
// Firefox: Disable WebRTC

// 3. Playwright 防护
context = browser.new_context(
 permissions=['geolocation'], # 限制权限
 # 禁用 WebRTC
)

3.8 CDN 绕过

Cloudflare 检测机制

检测维度	检测内容	绕过策略
TLS 指纹	JA3/JA4 匹配	使用真实浏览器指纹
JavaScript	挑战脚本执行	完整 JS 引擎
HTTP/2	SETTINGS 帧	使用 curl-impersonate
行为分析	访问模式	模拟人类行为

Cloudflare 绕过方案

# 1. 使用 curl_cffi
from curl_cffi import requests

# Chrome 浏览器指纹
response = requests.get(
 url,
 impersonate="chrome120",
 headers={
 'User-Agent': 'Mozilla/5.0 ...',
 'Accept': 'text/html,application/xhtml+xml...',
 }
)

# 2. 使用 undetected-chromedriver
import undetected_chromedriver as uc

driver = uc.Chrome()
driver.get(url)

# 3. 使用 playwright + proxy
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
 browser = p.chromium.launch(
 proxy={'server': 'http://proxy'},
 args=[
 '--disable-blink-features=AutomationControlled',
 ]
 )

3.9 反调试技术

调试器检测

// 检测方法 1: debugger 语句
setInterval(() => {
 const start = Date.now();
 debugger;
 if (Date.now() - start > 100) {
 // 调试器打开
 console.log('Debugger detected!');
 }
}, 1000);

// 检测方法 2: DevTools 检测
const devtools = /./;
devtools.toString = function() {
 this.opened = true;
}

// 检测方法 3: window 对象检测
if (window.chrome && window.chrome.webstore) {
 // 可能是自动化工具
}

绕过策略

# 1. 禁用 debugger
await page.evaluateOnNewDocument(() => {
 window.debugger = () => {};
 setInterval = new Proxy(setInterval, {
 apply: (target, thisArg, args) => {
 if (args[0]?.toString?.()?.includes('debugger')) {
 return;
 }
 return Reflect.apply(target, thisArg, args);
 }
 });
});

# 2. 启动参数
browser = p.chromium.launch(
 args=[
 '--disable-dev-shm-usage',
 '--no-first-run',
 '--no-default-browser-check',
 '--disable-blink-features=AutomationControlled',
 ]
)

# 3. 注入反检测脚本
stealth_script = """
Object.defineProperty(navigator, 'webdriver', {get: () => undefined});
"""
await page.add_init_script(stealth_script)

3.10 请求管理

请求拦截与修改

# Playwright 请求拦截
async def handle_route(route):
 # 修改请求头
 headers = route.request.headers
 headers['X-Custom-Header'] = 'value'

 # 阻止特定资源
 if route.request.resource_type in ['image', 'font']:
 await route.abort()
 else:
 await route.continue_(headers=headers)

page.route('**/*', handle_route)

资源控制

# 控制资源加载
context = browser.new_context(
 # 禁用图片加载
 accept_downloads=False,
)

# 拦截并响应自定义内容
await page.route('**/*.{png,jpg,jpeg}', lambda route: route.fulfill(
 status=404,
 body=b''
))

3.11 代理健康检查

代理质量检测

import asyncio
import aiohttp
import time

class ProxyHealthChecker:
 def __init__(self):
 self.proxies = {} # {proxy_url: {last_check, success_rate, latency}}

 async def check_proxy(self, proxy_url):
 """检查单个代理"""
 start_time = time.time()

 try:
 async with aiohttp.ClientSession() as session:
 async with session.get(
 'https://httpbin.org/ip',
 proxy=proxy_url,
 timeout=aiohttp.ClientTimeout(total=10)
 ) as response:
 latency = time.time() - start_time
 if response.status == 200:
 return {
 'status': 'success',
 'latency': latency,
 'ip': (await response.json()).get('origin')
 }
 except Exception as e:
 return {'status': 'failed', 'error': str(e)}

 async def check_all_proxies(self, proxy_list):
 """检查所有代理"""
 results = await asyncio.gather(
 *[self.check_proxy(p) for p in proxy_list],
 return_exceptions=True
 )

 for proxy, result in zip(proxy_list, results):
 if result and result.get('status') == 'success':
 self.proxies[proxy] = {
 'last_check': time.time(),
 'latency': result['latency'],
 'ip': result['ip']
 }

 return self.proxies

3.12 IP 地理位置匹配

时区与 IP 匹配

from datetime import datetime
import pytz

class GeoLocationMatcher:
 def __init__(self):
 # 代理 IP 对应的时区
 self.proxy_timezones = {
 'US': 'America/New_York',
 'US-West': 'America/Los_Angeles',
 'EU': 'Europe/London',
 'EU-West': 'Europe/Paris',
 'CN': 'Asia/Shanghai',
 'JP': 'Asia/Tokyo',
 'KR': 'Asia/Seoul',
 'SG': 'Asia/Singapore',
 'AU': 'Australia/Sydney',
 'IN': 'Asia/Kolkata',
 }

 def match_timezone(self, proxy_region):
 """根据代理地区匹配时区"""
 return self.proxy_timezones.get(proxy_region, 'UTC')

 def set_browser_timezone(self, page, timezone_str):
 """设置浏览器时区"""
 # 通过启动参数设置
 # Chrome: --timezone="Asia/Shanghai"
 # 或通过 JS 注入修改 Date 对象行为

 page.evaluate(f'''
 () => {{
 const originalDate = Date;
 const timezone = '{timezone_str}';

 // 覆盖 getTimezoneOffset
 Date.prototype.getTimezoneOffset = function() {{
 const offset = new Date().toLocaleString('en-US', {{
 timeZone: timezone,
 timeZoneName: 'short'
 }});

 // 解析时差（小时）
 const match = offset.match(/GMT([+-]{{0,1}}\\d+){{0,1}}\\d*)/);
 if (match) {{
 return parseInt(match[1]) * 60;
 }}
 return 0;
 }};

 // 覆盖 toString
 Date.prototype.toString = function() {{
 return this.toLocaleString('en-US', {{
 timeZone: timezone,
 year: 'numeric',
 month: 'short',
 day: 'numeric',
 hour: '2-digit',
 minute: '2-digit',
 second: '2-digit',
 timeZoneName: 'short'
 }});
 }};
 }}
 ''')

3.13 字体指纹伪造

字体检测原理

// 网站检测安装的字体
function detectFonts() {
 const baseFonts = ['monospace', 'sans-serif', 'serif'];
 const testFonts = ['Arial', 'Times New Roman', 'Courier New', 'Verdana', 'Georgia'];

 const testString = 'mmmmmmmmmmlli';
 const testSize = '72px';
 const h = document.getElementsByTagName('body')[0];

 const canvas = document.createElement('canvas');
 const context = canvas.getContext('2d');

 const fontMap = {};

 baseFonts.forEach(function(baseFont) {
 testFonts.forEach(function(font) {
 context.font = testSize + ' ' + font + ', ' + baseFont;
 context.fillText(testString, 0, 0);

 const dataUrl = canvas.toDataURL();
 fontMap[font] = dataUrl;
 });
 });

 return fontMap;
}

字体指纹伪造

# Playwright + 字体注入
def inject_font_fingerprint(page):
 """注入字体指纹"""

 # 方法1: 伪装已安装字体
 page.evaluate_on_new_document("""
 () => {
 // 覆盖 measureText 和其他字体检测方法
 const originalMeasureText = CanvasRenderingContext2D.prototype.measureText;

 CanvasRenderingContext2D.prototype.measureText = function(text) {
 // 添加随机噪声使指纹不一致
 const result = originalMeasureText.call(this, text);
 result.width += Math.random() * 0.01;
 return result;
 };
 }
 """)

 # 方法2: 使用字体回退列表
 context.fonts = [
 'Arial', 'Times New Roman', 'Courier New',
 'Verdana', 'Georgia', 'Palatino',
 'Garamond', 'Bookman', 'Comic Sans MS',
 'Trebuchet MS', 'Arial Black', 'Impact'
 ]

3.14 Web Audio 指纹处理

Audio 指纹检测

// Audio 指纹获取
function getAudioFingerprint() {
 const audioContext = new (window.AudioContext || window.webkitAudioContext)();

 const oscillator = audioContext.createOscillator();
 const analyser = audioContext.createAnalyser();
 const gain = audioContext.createGain();
 const scriptProcessor = audioContext.createScriptProcessor(4096, 1, 1);

 gain.gain.value = 0; // 静音

 oscillator.connect(analyser);
 analyser.connect(scriptProcessor);
 scriptProcessor.connect(gain);
 gain.connect(audioContext.destination);

 oscillator.start(0);

 const audioData = [];
 scriptProcessor.onaudioprocess = (e) => {
 audioData.push(e.inputBuffer.getChannelData(0));
 };

 return new Promise((resolve) => {
 setTimeout(() => {
 oscillator.stop(0);
 audioContext.close();
 resolve(audioData);
 }, 100);
 });
}

Audio 指纹伪装

def spoof_audio_fingerprint(page):
 """伪装 Audio 指纹"""

 page.evaluate_on_new_document("""
 () => {
 // Hook AudioContext
 const AudioContext = window.AudioContext || window.webkitAudioContext;

 if (AudioContext) {
 // 重写 createOscillator
 const originalCreateOscillator = AudioContext.prototype.createOscillator;

 AudioContext.prototype.createOscillator = function() {
 const oscillator = originalCreateOscillator.call(this);
 const originalStart = oscillator.start.bind(oscillator);

 oscillator.start = function(when) {
 // 添加随机噪声
 this.detune.value = Math.random() * 10 - 5;
 return originalStart(when || 0);
 };

 return oscillator;
 };
 }

 // Hook AnalyserNode
 const AudioContext = window.AudioContext || window.webkitAudioContext;

 if (AudioContext) {
 const originalCreateAnalyser = AudioContext.prototype.createAnalyser;

 AudioContext.prototype.createAnalyser = function() {
 const analyser = originalCreateAnalyser.call(this);
 analyser.fftSize = 2048 + Math.floor(Math.random() * 10);
 return analyser;
 };
 }
 }
 """)

3.15 Battery API 伪造

电池状态检测

// 获取电池信息
navigator.getBattery().then(battery => {
 console.log('Battery level:', battery.level); // 0-1
 console.log('Charging:', battery.charging); // boolean
 console.log('Charging time:', battery.chargingTime); // seconds
 console.log('Discharging time:', battery.dischargingTime);
});

电池信息伪造

def spoof_battery_api(page):
 """伪造电池信息"""

 page.evaluate_on_new_document("""
 () => {
 Object.defineProperty(navigator, 'getBattery', {
 value: () => Promise.resolve({
 charging: Math.random() > 0.5,
 chargingTime: Math.random() > 0.5 ? Infinity : 3600,
 dischargingTime: Math.random() > 0.5 ? Infinity : 7200,
 level: 0.3 + Math.random() * 0.6, // 30%-90%
 addEventListener: () => {},
 removeEventListener: () => {}
 }),
 writable: false
 });
 }
 """)

3.16 Network API 伪造

网络信息检测

// 获取网络信息
const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;

console.log('Effective Type:', connection.effectiveType); // 4g, 3g, 2g
console.log('Downlink:', connection.downlink); // Mbps
console.log('RTT:', connection.rtt); // 往返时间 ms
console.log('Save Data:', connection.saveData); // 省流量模式

网络信息伪造

def spoof_network_api(page):
 """伪造网络信息"""

 page.evaluate_on_new_document("""
 () => {
 Object.defineProperty(navigator, 'connection', {
 value: {
 effectiveType: '4g',
 rtt: Math.floor(Math.random() * 100) + 50, // 50-150ms
 downlink: Math.floor(Math.random() * 10) + 5, // 5-15 Mbps
 saveData: false,
 addEventListener: () => {},
 removeEventListener: () => {},
 onchange: null,
 ontypechange: null
 },
 writable: false
 });
 }
 """)

3.17 Screen API 伪造

屏幕信息检测

// 屏幕方向
console.log(screen.orientation.type); // landscape-primary
console.log(screen.orientation.angle); // 90, 180, 270, 0

// 像素比
console.log(window.devicePixelRatio); // 1, 2, 3

// 颜色深度
console.log(screen.colorDepth); // 24, 32

屏幕信息伪造

def spoof_screen_api(page):
 """伪造屏幕信息"""

 page.evaluate_on_new_document("""
 () => {
 // 屏幕方向
 Object.defineProperty(screen.orientation, 'type', {
 get: () => 'landscape-primary',
 configurable: true
 });

 // 像素比
 Object.defineProperty(window, 'devicePixelRatio', {
 get: () => 2,
 configurable: true
 });

 // 颜色深度
 Object.defineProperty(screen, 'colorDepth', {
 get: () => 24,
 configurable: true
 });
 }
 """)

3.18 Permissions API 控制

权限请求检测

// 检查权限状态
navigator.permissions.query({name: 'notifications'}).then(result => {
 console.log('Notification permission:', result.state); // granted, denied, prompt
});

// 检查多个权限
const permissions = ['notifications', 'geolocation', 'camera', 'microphone'];

Promise.all(permissions.map(p => navigator.permissions.query({name: p}))).then(results => {
 results.forEach(r => {
 console.log(r.name, ':', r.state);
 });
});

权限控制策略

def control_permissions(page):
 """控制权限请求"""

 # 方式1: 自动授权
 context = browser.new_context(
 geolocation={'latitude': 39.9, 'longitude': 116.4},
 permissions=['geolocation', 'notifications']
 )

 # 方式2: 拦截权限请求
 page.route('**/api/permissions/**', lambda route: route.fulfill(
 status=200,
 body='{"permissions": ["notifications", "geolocation"]}'
 ))

 # 方式3: 修改 Permissions API
 page.evaluate_on_new_document("""
 () => {
 const Permissions = window.Permissions || window.webkitPermissions;

 if (Permissions) {
 const originalQuery = Permissions.prototype.query;

 Permissions.prototype.query = function(permissionDesc) {
 return Promise.resolve({
 state: 'granted',
 name: permissionDesc.name,
 onchange: null
 });
 };
 }
 }
 """)

3.19 Geolocation 伪造

地理位置检测

// 获取位置
navigator.geolocation.getCurrentPosition(
 (position) => {
 console.log('Lat:', position.coords.latitude);
 console.log('Lon:', position.coords.longitude);
 console.log('Accuracy:', position.coords.accuracy);
 },
 (error) => {
 console.error('Error:', error.message);
 }
);

地理位置伪造

def spoof_geolocation(page, latitude, longitude):
 """伪造地理位置"""

 page.evaluate_on_new_document(f"""
 () => {{
 const fakePosition = {{
 coords: {{
 latitude: {latitude},
 longitude: {longitude},
 accuracy: 100 + Math.random() * 500,
 altitude: null,
 altitudeAccuracy: null,
 heading: null,
 speed: null
 }},
 timestamp: Date.now()
 }};

 const originalGetCurrentPosition = navigator.geolocation.getCurrentPosition;
 const originalWatchPosition = navigator.geolocation.watchPosition;
 const originalClearWatch = navigator.geolocation.clearWatch;

 navigator.geolocation.getCurrentPosition = function(success, error) {{
 if (success) success(fakePosition);
 }};

 navigator.geolocation.watchPosition = function(success, error, options) {{
 if (success) success(fakePosition);
 return 1; // watch ID
 }};

 navigator.geolocation.clearWatch = function(id) {{
 // Do nothing
 }};
 }}
 """)

3.20 WebGL 参数随机化

WebGL 参数检测

// WebGL 渲染器参数
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');

console.log('MAX_TEXTURE_SIZE:', gl.getParameter(gl.MAX_TEXTURE_SIZE));
console.log('MAX_VIEWPORT_DIMS:', gl.getParameter(gl.MAX_VIEWPORT_DIMS));
console.log('RENDERER:', gl.getParameter(gl.RENDERER));
console.log('VENDOR:', gl.getParameter(gl.VENDOR));
console.log('VERSION:', gl.getParameter(gl.VERSION));

WebGL 参数伪造

def randomize_webgl_params(page):
 """随机化 WebGL 参数"""

 page.evaluate_on_new_document("""
 () => {
 const getParameter = WebGLRenderingContext.prototype.getParameter;

 WebGLRenderingContext.prototype.getParameter = function(parameter) {
 const result = getParameter.call(this, parameter);

 // 随机化某些参数
 switch (parameter) {
 case 37445: // MAX_TEXTURE_SIZE
 return result + Math.floor(Math.random() * 100) - 50;
 case 32802: // MAX_VIEWPORT_DIMS
 return [result[0], result[1]];
 case 7938: // MAX_VIEWPORT_DIMS
 return [result[0], result[1]];
 default:
 return result;
 }
 };
 }
 """)

3.21 Chrome DevTools 指纹隐藏

DevTools 检测绕过

def hide_devtools_fingerprints(page):
 """隐藏 DevTools 特征"""

 page.evaluate_on_new_document("""
 () => {
 // 1. 移除 chrome.runtime 对象
 if (window.chrome && window.chrome.runtime) {
 delete window.chrome.runtime;
 }

 // 2. 移除调试器检测
 const originalDebugger = window.debugger;
 window.debugger = () => {};

 // 3. 移除外检测脚本标记
 const scripts = document.querySelectorAll('script');
 scripts.forEach(script => {
 if (script.innerHTML.includes('evaluate')) {
 script.remove();
 }
 });

 // 4. 移除错误堆栈中的 puppeteer 标记
 const originalError = Error;
 window.Error = function(...args) {
 const error = new originalError(...args);
 if (error.stack) {
 error.stack = error.stack
 .replace(/puppeteer/g, '')
 .replace(/playwright/g, '')
 .replace(/selenium/g, '');
 }
 return error;
 };
 }
 """)

3.22 iframe 内容伪装

iframe 检测处理

def spoof_iframe_fingerprints(page):
 """处理 iframe 指纹检测"""

 page.evaluate_on_new_document("""
 () => {
 // Hook iframe 创建
 const originalCreateElement = document.createElement;

 document.createElement = function(tagName) {
 const element = originalCreateElement.call(this, tagName);

 if (tagName.toLowerCase() === 'iframe') {
 // 监听 iframe 加载
 element.addEventListener('load', function() {
 try {
 const iframeWindow = element.contentWindow;

 if (iframeWindow) {
 // 在 iframe 中注入伪装脚本
 Object.defineProperty(
 iframeWindow.navigator,
 'webdriver',
 { get: () => undefined }
 );

 // 注入插件伪造
 iframeWindow.navigator.plugins = [
 { name: 'Chrome PDF Plugin' }
 ];
 }
 } catch (e) {
 // 跨域 iframe 无法访问
 }
 });
 }

 return element;
 };
 }
 """)

3.23 媒体编解码器伪造

Codec 检测与伪装

def spoof_media_codecs(page):
 """伪造媒体编解码器支持"""

 page.evaluate_on_new_document("""
 () => {
 // 伪造 MediaCapabilities
 const originalGetCapabilities = navigator.mediaCapabilities;

 if (originalGetCapabilities) {
 const mockCapabilities = {
 decodingInfo: {
 powerEfficient: true,
 smooth: true,
 supportedPowerEfficient: [],
 supportedSmooth: [],
 },
 encodingInfo: {
 powerEfficient: true,
 smooth: true,
 supportedPowerEfficient: [],
 supportedSmooth: [],
 }
 };

 Object.defineProperty(navigator, 'mediaCapabilities', {
 get: () => mockCapabilities
 });
 }

 // 伪造 canPlayType 方法
 const mockCanPlayType = (mimeType) => {
 // 常见视频类型
 const videoTypes = [
 'video/mp4; codecs="avc1.64201f, mp4a.40.2"',
 'video/webm; codecs="vp8, vorbis"',
 'video/ogg; codecs="theora, vorbis"'
 ];

 // 常见音频类型
 const audioTypes = [
 'audio/mpeg',
 'audio/ogg; codecs="vorbis"',
 'audio/wav; codecs="1"',
 'audio/webm; codecs="opus"'
 ];

 return [...videoTypes, ...audioTypes].includes(mimeType) ||
 'probably';
 };

 const mockVideoElement = {
 canPlayType: mockCanPlayType
 };

 // 尝试替换
 if (typeof HTMLVideoElement !== 'undefined') {
 Object.assign(HTMLVideoElement.prototype, mockVideoElement);
 }
 }
 """)

3.24 Memory API 伪装

设备内存信息

def spoof_memory_api(page):
 """伪装内存 API"""

 page.evaluate_on_new_document("""
 () => {
 // 添加 deviceMemory 属性
 Object.defineProperty(navigator, 'deviceMemory', {
 get: () => 8, // GB
 configurable: true
 });

 // 如果已有 deviceMemory，修改其值
 if (navigator.deviceMemory) {
 const originalMemory = navigator.deviceMemory;
 Object.defineProperty(navigator, 'deviceMemory', {
 get: () => ({
 ...originalMemory,
 jsHeapSizeLimit: 8589934592, // 8GB
 totalJSHeapSize: 8589934592,
 usedJSHeapSize: 800000000
 })
 });
 }
 }
 """)

3.25 Connection RTT 动态调整

网络延迟模拟

class DynamicNetworkSpoof:
 """动态网络指纹伪装"""

 def __init__(self):
 self.rtt_history = []
 self.bandwidth_history = []

 def update_network_stats(self, page, actual_rtt=None):
 """更新网络统计"""

 if actual_rtt:
 self.rtt_history.append(actual_rtt)
 if len(self.rtt_history) > 10:
 self.rtt_history.pop(0)

 # 计算平均值
 avg_rtt = sum(self.rtt_history) / len(self.rtt_history) if self.rtt_history else 50

 page.evaluate(f'''
 () => {{
 const rtt = {avg_rtt};
 const downlink = Math.max(10, Math.min(50, 5000 / rtt));

 Object.defineProperty(navigator, 'connection', {{
 value: {{
 effectiveType: rtt < 100 ? '4g' : rtt < 300 ? '3g' : '2g',
 rtt: rtt,
 downlink: downlink,
 saveData: false,
 addEventListener: () => {{}},
 removeEventListener: () => {{}},
 onchange: null
 }},
 writable: false
 }});
 }}
 ''')

3.26 Touch API 支持

触摸设备伪装

def spoof_touch_api(page, is_touch_device=True):
 """伪装触摸设备"""

 if is_touch_device:
 page.evaluate_on_new_document("""
 () => {
 // 添加 touch support
 Object.defineProperty(navigator, 'maxTouchPoints', {
 get: () => 5,
 configurable: true
 });

 // 伪造触摸事件
 const mockTouchEvent = new TouchEvent('touchstart', {
 bubbles: true,
 cancelable: true,
 touches: [{
 identifier: 0,
 target: document.body,
 clientX: 100,
 clientY: 100,
 pageX: 100,
 pageY: 100,
 screenX: 100,
 screenY: 100
 }]
 });

 document.dispatchEvent(mockTouchEvent);
 }
 """)
 else:
 # 确保没有触摸支持
 page.evaluate_on_new_document("""
 () => {
 Object.defineProperty(navigator, 'maxTouchPoints', {
 get: () => 0,
 configurable: true
 });
 }
 """)

3.27 Vendor Prefixes 处理

浏览器厂商前缀

def spoof_vendor_prefixes(page):
 """处理厂商前缀"""

 page.evaluate_on_new_document("""
 () => {
 // 添加 WebKit 前缀属性
 window.webkit = window.webkit || {};

 // 伪装特定前缀
 window.webkitAudioContext = AudioContext;
 window.webkitSpeechRecognition = window.SpeechRecognition || null;

 // 处理特定前缀的 API
 if (!window.requestAnimationFrame) {
 window.requestAnimationFrame = window.webkitRequestAnimationFrame;
 }

 if (!window.cancelAnimationFrame) {
 window.cancelAnimationFrame = window.webkitCancelAnimationFrame;
 }
 }
 """)

3.28 WebGL 扩展伪装

WebGL 扩展信息

def spoof_webgl_extensions(page):
 """伪装 WebGL 扩展"""

 page.evaluate_on_new_document("""
 () => {
 const canvas = document.createElement('canvas');
 const gl = canvas.getContext('webgl') ||
 canvas.getContext('experimental-webgl');

 if (gl) {
 // Hook getExtension
 const originalGetExtension = gl.getExtension.bind(gl);

 gl.getExtension = function(name) {
 // 禁用某些扩展
 if (name === 'WEBGL_debug_renderer_info') {
 return null;
 }

 // 对其他扩展正常处理
 return originalGetExtension(name);
 };

 // Hook getSupportedExtensions
 const originalGetSupportedExtensions = gl.getSupportedExtensions?.bind(gl);

 if (originalGetSupportedExtensions) {
 gl.getSupportedExtensions = function() {
 const extensions = originalGetSupportedExtensions();
 // 过滤敏感扩展
 return extensions.filter(ext =>
 !ext.includes('debug') &&
 !ext.includes('EXT_texture_float')
 );
 };
 }
 }
 }
 """)

3.29 硬件指纹随机化

硬件熵生成

import uuid
import hashlib

class HardwareEntropyManager:
 """硬件熵管理器"""

 def __init__(self):
 self.seeds = {}

 def get_consistent_hardware_id(self, base_string):
 """生成一致的硬件 ID"""
 if base_string not in self.seeds:
 # 使用 base_string 作为种子
 hash_obj = hashlib.sha256(base_string.encode())
 self.seeds[base_string] = hash_obj.hexdigest()[:16]

 return self.seeds[base_string]

 def get_random_hardware_info(self):
 """生成随机但一致的硬件信息"""
 # 基于某种固定值生成
 hardware_id = self.get_consistent_hardware_id('anti-detection-seed')

 # 生成硬件序列号
 serial = f'HW-{hardware_id.upper()}'

 return {
 'hardwareConcurrency': 4 + (hash(hardware_id) % 4),
 'deviceMemory': 4 + (hash(hardware_id) % 4),
 'serial': serial,
 'uuid': str(uuid.UUID(hardware_id.ljust(32, '0')[:32]))
 }

四、行为层：人类行为模拟

4.1 鼠标行为模拟

贝塞尔曲线轨迹

真实用户的鼠标移动不是直线，而是带有自然曲线的平滑轨迹。

import math
import time

class MouseSimulator:
 def bezier_curve(self, p0, p1, p2, p3, t):
 """三次贝塞尔曲线计算"""
 x = (1-t)**3 * p0[0] + 3*(1-t)**2*t * p1[0] + 3*(1-t)*t**2 * p2[0] + t**3 * p3[0]
 y = (1-t)**3 * p0[1] + 3*(1-t)**2*t * p1[1] + 3*(1-t)*t**2 * p2[1] + t**3 * p3[1]
 return (x, y)

 def natural_move(self, page, start, end, duration=1.0):
 """模拟自然鼠标移动"""
 # 生成控制点，制造随机偏差
 mid_x = (start[0] + end[0]) / 2
 mid_y = (start[1] + end[1]) / 2

 offset = 50
 p0 = start
 p1 = (mid_x + random.uniform(-offset, offset),
 mid_y + random.uniform(-offset, offset))
 p2 = (mid_x + random.uniform(-offset, offset),
 mid_y + random.uniform(-offset, offset))
 p3 = end

 # 分段移动
 steps = 20
 for i in range(steps + 1):
 t = i / steps
 x, y = self.bezier_curve(p0, p1, p2, p3, t)
 page.mouse.move(x, y)
 time.sleep(duration / steps)

鼠标事件序列

# 完整的点击事件序列
def human_click(page, selector):
 element = page.query_selector(selector)
 if not element:
 return

 box = element.bounding_box()

 # 1. hover
 page.mouse.move(box.x + box.width / 2, box.y + box.height / 2)
 time.sleep(random.uniform(0.1, 0.3))

 # 2. mouse down
 page.mouse.down()
 time.sleep(random.uniform(0.05, 0.15))

 # 3. click
 page.mouse.up()
 time.sleep(random.uniform(0.1, 0.2))

4.2 键盘行为模拟

打字速度与节奏

import random

class KeyboardSimulator:
 def human_type(self, page, selector, text):
 """模拟人类打字"""
 page.click(selector)

 for char in text:
 page.keyboard.type(char)

 # 随机延迟，模拟真实打字节奏
 delay = random.gauss(0.1, 0.05) # 正态分布
 delay = max(0.02, min(0.3, delay)) # 限制范围
 time.sleep(delay)

 # 偶尔停顿（思考）
 if random.random() < 0.05:
 time.sleep(random.uniform(0.3, 0.8))

输入事件完整性

// 真实用户输入会触发一系列事件
inputElement.dispatchEvent(new Event('focus', { bubbles: true }));
inputElement.value = 'text';
inputElement.dispatchEvent(new InputEvent('input', { bubbles: true, data: 'text' }));
inputElement.dispatchEvent(new Event('change', { bubbles: true }));

4.3 滚动行为模拟

def human_scroll(page, direction='down', amount=None):
 """模拟人类滚动行为"""
 viewport = page.viewport_size
 scroll_height = page.evaluate('document.documentElement.scrollHeight')

 if amount is None:
 amount = random.randint(200, 500)

 # 分段滚动，模拟惯性
 segments = random.randint(3, 7)
 for _ in range(segments):
 if direction == 'down':
 page.mouse.wheel(0, amount / segments)
 else:
 page.mouse.wheel(0, -amount / segments)

 time.sleep(random.uniform(0.1, 0.3))

 # 随机等待
 time.sleep(random.uniform(0.5, 1.5))

4.4 视线停留时间

# 不同元素类型的平均停留时间（秒）
DWELL_TIMES = {
 'title': random.uniform(0.5, 1.5),
 'content': random.uniform(2, 5),
 'button': random.uniform(0.3, 0.8),
 'link': random.uniform(0.2, 0.5),
 'form': random.uniform(3, 8),
}

def human_read(page, selector):
 """模拟阅读停留"""
 time.sleep(DWELL_TIMES.get(selector, 1))

4.5 窗口大小变化模拟

真实用户在使用浏览器时会调整窗口大小，这种行为可以增加自然性。

def random_window_resize(page):
 """随机调整窗口大小"""
 # 常见分辨率
 resolutions = [
 (1920, 1080), (1366, 768), (1536, 864),
 (1440, 900), (1280, 720), (2560, 1440)
 ]

 # 随机选择新分辨率
 if random.random() < 0.1: # 10% 概率调整窗口
 width, height = random.choice(resolutions)
 page.set_viewport_size(width, height)
 time.sleep(random.uniform(0.5, 2.0))

4.6 页面停留时间随机化

不同类型页面需要不同的停留时间，模拟真实用户浏览习惯。

PAGE_DWELL_TIMES = {
 'homepage': (3, 10), # 首页：浏览时间长
 'article': (10, 30), # 文章：阅读时间长
 'product': (5, 15), # 商品页：比较选择
 'listing': (2, 8), # 列表页：快速浏览
 'checkout': (20, 60), # 结算页：填写信息
 'search': (3, 8), # 搜索结果：快速筛选
}

def page_dwell_time(page_type):
 """根据页面类型返回停留时间"""
 min_time, max_time = PAGE_DWELL_TIMES.get(page_type, (2, 10))
 return random.uniform(min_time, max_time)

4.7 点击位置偏移

真实用户点击时不会总是点击在元素正中心，会有随机偏移。

def click_with_offset(page, selector):
 """带位置偏移的点击"""
 element = page.query_selector(selector)
 box = element.bounding_box()

 # 中心点
 center_x = box.x + box.width / 2
 center_y = box.y + box.height / 2

 # 添加随机偏移（在元素范围内）
 offset_x = random.uniform(-box.width * 0.3, box.width * 0.3)
 offset_y = random.uniform(-box.height * 0.3, box.height * 0.3)

 page.mouse.click(center_x + offset_x, center_y + offset_y)

4.8 多标签页操作

真实用户经常使用多个标签页进行浏览。

class TabManager:
 """标签页管理器"""

 def __init__(self, context):
 self.context = context
 self.tabs = []

 def open_new_tab(self, url):
 """打开新标签页"""
 new_page = self.context.new_page()
 new_page.goto(url)
 self.tabs.append(new_page)

 # 随机等待后切换回原标签页
 time.sleep(random.uniform(2, 5))

 return new_page

 def switch_tabs(self):
 """随机切换标签页"""
 if len(self.tabs) < 2:
 return

 # 随机选择一个标签页切换
 target_tab = random.choice(self.tabs)
 target_tab.bring_to_front()

 time.sleep(random.uniform(1, 3))

 def close_tab(self, page):
 """关闭标签页"""
 page.close()
 if page in self.tabs:
 self.tabs.remove(page)

4.9 浏览器历史操作

模拟用户的前进后退导航行为。

def simulate_history_navigation(page):
 """模拟历史导航"""
 # 随机决定是否进行历史导航
 if random.random() < 0.15: # 15% 概率
 action = random.choice(['back', 'forward'])

 if action == 'back':
 page.go_back()
 else:
 page.go_forward()

 # 导航后的停留
 time.sleep(random.uniform(2, 5))

4.10 右键操作模拟

真实用户会使用右键菜单进行复制、粘贴等操作。

def simulate_context_menu(page, selector, action='copy'):
 """模拟右键菜单操作"""
 element = page.query_selector(selector)
 box = element.bounding_box()

 # 右键点击
 page.mouse.click(box.x + box.width / 2, box.y + box.height / 2, button='right')

 time.sleep(random.uniform(0.3, 0.6))

 # 使用键盘快捷键执行操作
 if action == 'copy':
 # Ctrl+C
 page.keyboard.down('Control')
 page.keyboard.press('c')
 page.keyboard.up('Control')
 elif action == 'paste':
 # Ctrl+V
 page.keyboard.down('Control')
 page.keyboard.press('v')
 page.keyboard.up('Control')

 time.sleep(random.uniform(0.2, 0.5))

4.11 拖放操作模拟

某些网站使用拖拽上传或排序功能。

def simulate_drag_and_drop(page, source_selector, target_selector):
 """模拟拖放操作"""
 source = page.query_selector(source_selector)
 target = page.query_selector(target_selector)

 source_box = source.bounding_box()
 target_box = target.bounding_box()

 # 1. 鼠标移动到源元素
 start_x = source_box.x + source_box.width / 2
 start_y = source_box.y + source_box.height / 2

 page.mouse.move(start_x, start_y)
 time.sleep(random.uniform(0.2, 0.4))

 # 2. 按下鼠标
 page.mouse.down()
 time.sleep(random.uniform(0.1, 0.2))

 # 3. 拖动到目标位置（使用贝塞尔曲线）
 end_x = target_box.x + target_box.width / 2
 end_y = target_box.y + target_box.height / 2

 steps = 20
 for i in range(steps + 1):
 t = i / steps
 x = start_x + (end_x - start_x) * t
 y = start_y + (end_y - start_y) * t
 page.mouse.move(x, y)
 time.sleep(0.02)

 # 4. 释放鼠标
 page.mouse.up()
 time.sleep(random.uniform(0.3, 0.6))

4.12 音频/视频交互

模拟用户与媒体内容的交互。

def simulate_media_interaction(page, video_selector):
 """模拟视频交互"""
 video = page.query_selector(video_selector)

 # 随机选择操作
 action = random.choice(['play_pause', 'seek', 'volume', 'none'])

 if action == 'play_pause':
 # 点击播放/暂停
 video.click()
 time.sleep(random.uniform(5, 15)) # 观看一段时间
 video.click() # 暂停

 elif action == 'seek':
 # 拖动进度条
 box = video.bounding_box()
 page.mouse.move(box.x + box.width * 0.7, box.y + box.height / 2)
 page.mouse.down()
 time.sleep(0.5)
 page.mouse.up()

 elif action == 'volume':
 # 调整音量
 page.keyboard.down('Control')
 page.touch_home('ArrowDown')
 page.touch_home('ArrowDown')
 page.keyboard.up('Control')

4.13 表单提交行为

模拟真实的表单填写和提交流程。

def simulate_form_submission(page, form_data):
 """模拟表单提交"""
 # 1. 逐个填写字段
 for field_selector, value in form_data.items():
 # 聚焦字段
 page.click(field_selector)
 time.sleep(random.uniform(0.2, 0.4))

 # 清空现有内容
 page.keyboard.down('Control')
 page.keyboard.press('a')
 page.keyboard.up('Control')
 time.sleep(0.1)

 # 填写新内容
 human_type(page, field_selector, value)

 # 验证前检查
 time.sleep(random.uniform(0.3, 0.6))

 # Tab 切换到下一个字段
 page.keyboard.press('Tab')
 time.sleep(random.uniform(0.2, 0.4))

 # 2. 提交前的停顿（检查确认）
 time.sleep(random.uniform(1, 3))

 # 3. 点击提交按钮
 page.click('button[type="submit"]')

4.14 鼠标抖动

真实用户在点击前手会有微小抖动。

def click_with_jitter(page, selector):
 """带抖动的点击"""
 element = page.query_selector(selector)
 box = element.bounding_box()

 target_x = box.x + box.width / 2
 target_y = box.y + box.height / 2

 # 移动到目标附近
 page.mouse.move(target_x, target_y)
 time.sleep(0.1)

 # 微小抖动
 for _ in range(random.randint(2, 5)):
 jitter_x = random.uniform(-3, 3)
 jitter_y = random.uniform(-3, 3)
 page.mouse.move(target_x + jitter_x, target_y + jitter_y)
 time.sleep(random.uniform(0.02, 0.05))

 # 点击
 page.mouse.click(target_x, target_y)

4.15 键盘修正行为

模拟用户打错字后删除重打的行为。

def type_with_corrections(page, selector, text):
 """带修正的打字"""
 page.click(selector)
 time.sleep(0.2)

 i = 0
 while i < len(text):
 # 决定是否打错字
 if random.random() < 0.08: # 8% 概率打错
 # 打入错误字符
 wrong_char = chr(random.randint(97, 122)) # 随机字母
 page.keyboard.type(wrong_char)
 time.sleep(random.uniform(0.1, 0.2))

 # 意识到错误，停顿
 time.sleep(random.uniform(0.3, 0.6))

 # 删除错误
 page.keyboard.press('Backspace')
 time.sleep(random.uniform(0.1, 0.2))

 # 打入正确字符
 page.keyboard.type(text[i])
 delay = random.gauss(0.12, 0.04)
 time.sleep(max(0.05, min(0.3, delay)))
 i += 1

4.16 触摸事件模拟

移动端触摸行为模拟。

def simulate_touch_interaction(page, element_selector):
 """模拟触摸交互"""
 element = page.query_selector(element_selector)
 box = element.bounding_box()

 x = box.x + box.width / 2
 y = box.y + box.height / 2

 # touchstart
 page.evaluate(f'''
 () => {{
 const element = document.querySelector("{element_selector}");
 const touch = new Touch({{
 identifier: 0,
 target: element,
 clientX: {x},
 clientY: {y},
 pageX: {x},
 pageY: {y}
 }});

 const touchStart = new TouchEvent('touchstart', {{
 bubbles: true,
 cancelable: true,
 touches: [touch]
 }});

 element.dispatchEvent(touchStart);
 }}
 ''')

 time.sleep(random.uniform(0.1, 0.3))

 # touchend
 page.evaluate(f'''
 () => {{
 const element = document.querySelector("{element_selector}");
 const touchEnd = new TouchEvent('touchend', {{
 bubbles: true,
 cancelable: true,
 changedTouches: []
 }});

 element.dispatchEvent(touchEnd);
 }}
 ''')

 # 点击事件
 element.click()

4.17 Hover 停留

模拟鼠标悬停在元素上一段时间后再操作。

def hover_before_click(page, selector):
 """Hover 后再点击"""
 element = page.query_selector(selector)
 box = element.bounding_box()

 # Hover
 page.mouse.move(box.x + box.width / 2, box.y + box.height / 2)

 # 随机停留时间
 dwell_time = random.uniform(0.5, 2.0)
 time.sleep(dwell_time)

 # 有时离开后再回来
 if random.random() < 0.1:
 page.mouse.move(box.x + box.width / 2, box.y - 50)
 time.sleep(random.uniform(0.2, 0.5))
 page.mouse.move(box.x + box.width / 2, box.y + box.height / 2)
 time.sleep(random.uniform(0.3, 0.8))

 # 点击
 page.mouse.click(box.x + box.width / 2, box.y + box.height / 2)

4.18 视觉扫视行为

模拟人类浏览时的视觉扫视模式。

import numpy as np

class VisualScanPattern:
 """视觉扫视模拟器"""

 def __init__(self):
 self.hotspots = [
 (0.2, 0.3), # 左上区域
 (0.5, 0.2), # 顶部中央
 (0.8, 0.3), # 右上区域
 (0.2, 0.7), # 左下区域
 (0.5, 0.8), # 底部中央
 (0.8, 0.7), # 右下区域
 ]

 def visual_scan(self, page):
 """执行视觉扫视"""
 viewport = page.viewport_size

 # 随机选择热点区域
 for _ in range(random.randint(3, 6)):
 hotspot_x, hotspot_y = random.choice(self.hotspots)

 target_x = viewport['width'] * hotspot_x
 target_y = viewport['height'] * hotspot_y

 # 移动到热点
 mouse_sim.natural_move(page, (target_x, target_y), duration=0.3)
 time.sleep(random.uniform(0.1, 0.3))

 # 回到内容区域
 center_x = viewport['width'] * 0.5
 center_y = viewport['height'] * 0.5
 mouse_sim.natural_move(page, (center_x, center_y), duration=0.5)

4.19 随机停顿行为

模拟人类阅读或思考时的随机停顿。

class RandomPauseManager:
 """随机停顿管理器"""

 def __init__(self):
 self.think_time = (0.5, 2.0) # 思考时间范围
 self.read_time = (1.0, 5.0) # 阅读时间范围
 self.short_pause = (0.1, 0.5) # 短暂停

 def think_pause(self):
 """思考停顿"""
 duration = random.uniform(*self.think_time)
 time.sleep(duration)

 def read_pause(self, text_length=None):
 """阅读停顿（根据文本长度调整）"""
 base_duration = random.uniform(*self.read_time)

 if text_length:
 # 文本越长，停留越久
 adjustment = min(len(text_length) * 0.05, 3.0)
 duration = base_duration + adjustment
 else:
 duration = base_duration

 time.sleep(duration)

 def short_pause(self):
 """短停顿"""
 duration = random.uniform(*self.short_pause)
 time.sleep(duration)

4.20 链接点击决策

模拟人类点击链接时的决策过程。

class LinkClickDecision:
 """链接点击决策器"""

 def __init__(self):
 self.click_probability = 0.7 # 70% 概率点击
 self.skip_probability = 0.2 # 20% 概率跳过
 self.scroll_probability = 0.1 # 10% 概率滚动

 def decide_action(self, link_text, link_url):
 """决定对链接采取的行动"""
 # 随机因素
 random_factor = random.random()

 # 基于链接特征调整
 if '广告' in link_text.lower():
 self.click_probability *= 0.5
 if 'read more' in link_text.lower():
 self.click_probability *= 1.5

 # 决策
 if random_factor < self.click_probability:
 return 'click'
 elif random_factor < self.click_probability + self.skip_probability:
 return 'skip'
 else:
 return 'scroll'

4.21 表单填写节奏

模拟人类填写表单时的节奏和顺序。

class FormFillingRhythm:
 """表单填写节奏管理器"""

 def __init__(self):
 self.typing_speeds = {
 'name': (0.08, 0.15), # 姓名：慢速
 'email': (0.05, 0.10), # 邮箱：中速
 'password': (0.12, 0.20), # 密码：慢速
 'other': (0.06, 0.12), # 其他：中速
 }

 def get_typing_delay(self, field_type='other'):
 """获取打字延迟"""
 delay_range = self.typing_speeds.get(field_type, self.typing_speeds['other'])
 return random.gauss(
 (delay_range[0] + delay_range[1]) / 2,
 (delay_range[1] - delay_range[0]) / 4
 )

 def fill_field(self, page, selector, value, field_type='other'):
 """填写表单字段"""
 # 聚焦
 element = page.query_selector(selector)
 element.click()

 # 短暂停
 time.sleep(random.uniform(0.1, 0.3))

 # 逐个字符输入
 for char in value:
 page.keyboard.type(char)
 delay = self.get_typing_delay(field_type)
 delay = max(0.05, min(0.5, abs(delay)))
 time.sleep(delay)

 # 填写后的停顿
 time.sleep(random.uniform(0.2, 0.5))

 # 随机回看
 if random.random() < 0.15:
 time.sleep(random.uniform(0.3, 0.8))

4.22 页面滚动模式

模拟多种不同的滚动模式。

class ScrollPatternManager:
 """滚动模式管理器"""

 def __init__(self):
 self.patterns = [
 'continuous', # 连续滚动
 'intermittent', # 间歇滚动
 'accelerating', # 加速滚动
 'bouncing', # 来回滚动
 ]

 def continuous_scroll(self, page, scroll_amount=500):
 """连续滚动"""
 steps = random.randint(5, 10)
 step_size = scroll_amount / steps

 for _ in range(steps):
 page.mouse.wheel(0, step_size)
 time.sleep(random.uniform(0.05, 0.15))

 def intermittent_scroll(self, page, max_scrolls=5):
 """间歇滚动"""
 for _ in range(max_scrolls):
 # 滚动一段
 amount = random.randint(100, 400)
 page.mouse.wheel(0, amount)
 time.sleep(random.uniform(0.2, 0.5))

 # 停顿
 time.sleep(random.uniform(0.5, 2.0))

 def accelerating_scroll(self, page, total_amount=800):
 """加速滚动"""
 speeds = [30, 50, 80, 120, 150] # 逐步加速
 remaining = total_amount

 for speed in speeds:
 scroll_size = min(speed, remaining)
 page.mouse.wheel(0, scroll_size)
 remaining -= scroll_size

 if remaining <= 0:
 break

 time.sleep(0.1)

 def bouncing_scroll(self, page, bounce_count=3):
 """来回滚动"""
 for _ in range(bounce_count):
 # 向下滚动
 down_amount = random.randint(200, 400)
 page.mouse.wheel(0, down_amount)
 time.sleep(random.uniform(0.3, 0.6))

 # 向上滚动（部分回滚）
 up_amount = random.randint(50, 150)
 page.mouse.wheel(0, -up_amount)
 time.sleep(random.uniform(0.2, 0.4))

 def choose_and_execute(self, page):
 """随机选择并执行滚动模式"""
 pattern = random.choice(self.patterns)

 if pattern == 'continuous':
 self.continuous_scroll(page)
 elif pattern == 'intermittent':
 self.intermittent_scroll(page)
 elif pattern == 'accelerating':
 self.accelerating_scroll(page)
 elif pattern == 'bouncing':
 self.bouncing_scroll(page)

4.23 多步交互序列

模拟复杂的多步交互过程。

class MultiStepInteraction:
 """多步交互管理器"""

 def __init__(self):
 self.pause_manager = RandomPauseManager()
 self.scroll_manager = ScrollPatternManager()
 self.form_rhythm = FormFillingRhythm()

 def complex_search_interaction(self, page, search_query):
 """复杂搜索交互"""
 # 1. 定位搜索框
 search_box = page.query_selector('input[type="search"]')

 # 2. 移动到搜索框
 box = search_box.bounding_boxbox()
 mouse_sim.natural_move(
 page,
 (box.x + box.width / 2, box.y + box.height / 2),
 duration=0.8
 )

 # 3. 点击聚焦
 search_box.click()
 self.pause_manager.short_pause()

 # 4. 删除现有内容
 page.keyboard.down('Control')
 page.keyboard.press('a')
 page.keyboard.up('Control')
 self.pause_manager.short_pause()

 # 5. 输入搜索词
 self.form_rhythm.fill_field(
 page,
 'input[type="search"]',
 search_query,
 field_type='other'
 )

 # 6. 稍作停顿
 self.pause_manager.think_pause()

 # 7. 按下回车
 page.keyboard.press('Enter')
 self.pause_manager.short_pause()

 # 8. 等待结果加载
 time.sleep(random.uniform(2.0, 4.0))

 # 9. 滚动浏览结果
 self.scroll_manager.choose_and_execute(page)

4.24 用户偏好模拟

模拟不同类型用户的浏览偏好。

class UserPreference:
 """用户偏好模拟"""

 def __init__(self, user_type='average'):
 self.user_type = user_type
 self.preferences = self._get_preferences(user_type)

 def _get_preferences(self, user_type):
 """获取用户类型偏好"""
 prefs = {
 'careful': {
 'click_speed': 'slow',
 'read_depth': 'deep',
 'scroll_frequency': 'low',
 'form_filling': 'meticulous',
 },
 'casual': {
 'click_speed': 'fast',
 'read_depth': 'shallow',
 'scroll_frequency': 'high',
 'form_filling': 'quick',
 },
 'average': {
 'click_speed': 'medium',
 'read_depth': 'medium',
 'scroll_frequency': 'medium',
 'form_filling': 'medium',
 }
 }
 return prefs.get(user_type, prefs['average'])

 def get_click_delay(self):
 """获取点击延迟"""
 speed_map = {
 'slow': (0.3, 0.6),
 'medium': (0.15, 0.3),
 'fast': (0.08, 0.15),
 }
 speed = self.preferences['click_speed']
 return random.uniform(*speed_map[speed])

 def should_read_article(self):
 """是否阅读文章"""
 read_depth_map = {
 'deep': 0.8,
 'medium': 0.5,
 'shallow': 0.2,
 }
 depth = self.preferences['read_depth']
 return random.random() < read_depth_map[depth]

五、持久层：状态管理

5.1 Cookies 与 Session 管理

Cookie Pool
├── 用户指纹 Cookie（长期）
│ ├── _ga, _gid（Google Analytics）
│ ├── __cfduid（Cloudflare）
│ └── 站点特定识别 Cookie
│
├── 会话 Cookie（短期）
│ ├── sessionid
│ ├── JSESSIONID
│ └── PHPSESSID
│
└── 临时 Cookie（单次）
├── CSRF Token
└── State 参数

场景	Cookie 策略	刷新策略
登录态	持久化存储	Token 失效时刷新
会话态	内存缓存	定期刷新或失效时重新获取
匿名访问	无状态	每次新会话

import json
import hashlib
from pathlib import Path

class CookieManager:
 def __init__(self, storage_path):
 self.storage_path = Path(storage_path)
 self.storage_path.mkdir(exist_ok=True)

 def get_cookies(self, url, fingerprint):
 """获取指纹对应的 Cookies"""
 fingerprint_hash = hashlib.md5(fingerprint.encode()).hexdigest()
 cookie_file = self.storage_path / f"{fingerprint_hash}.json"

 if cookie_file.exists():
 with open(cookie_file) as f:
 cookies = json.load(f)
 return self._filter_valid_cookies(cookies)

 return []

 def save_cookies(self, url, cookies, fingerprint):
 """保存 Cookies"""
 fingerprint_hash = hashlib.md5(fingerprint.encode()).hexdigest()
 cookie_file = self.storage_path / f"{fingerprint_hash}.json"

 with open(cookie_file, 'w') as f:
 json.dump(cookies, f)

 def _filter_valid_cookies(self, cookies):
 """过滤过期的 Cookie"""
 return [c for c in cookies
 if 'expires' not in c or c['expires'] > time.time()]

5.2 浏览器指纹持久化

User Data 目录管理

from playwright.sync_api import sync_playwright

class BrowserProfile:
 def __init__(self, base_path='./profiles'):
 self.base_path = Path(base_path)
 self.base_path.mkdir(exist_ok=True)

 def get_profile_path(self, profile_id):
 return self.base_path / profile_id

 def create_browser(self, profile_id):
 profile_path = self.get_profile_path(profile_id)

 playwright = sync_playwright().start()
 browser = playwright.chromium.launch_persistent_context(
 user_data_dir=str(profile_path),
 headless=False,
 args=[
 '--disable-blink-features=AutomationControlled',
 '--disable-infobars',
 ]
 )
 return browser

LocalStorage/SessionStorage 保存

def save_storage(page, profile_id):
 """保存所有存储"""
 storage = {
 'localStorage': page.evaluate('Object.entries(localStorage)'),
 'sessionStorage': page.evaluate('Object.entries(sessionStorage)'),
 'cookies': page.context.cookies(),
 }

 with open(f'storage/{profile_id}.json', 'w') as f:
 json.dump(storage, f)

def restore_storage(page, profile_id):
 """恢复存储"""
 with open(f'storage/{profile_id}.json') as f:
 storage = json.load(f)

 # 恢复 Cookies
 for cookie in storage['cookies']:
 page.context.add_cookie(cookie)

 # 恢复 LocalStorage
 page.evaluate(f'''
 localStorage.clear();
 {storage['localStorage'].forEach(([k, v]) => {{
 localStorage.setItem(k, v);
 }})}
 ''')

5.3 状态同步与回滚

状态快照

import pickle
from datetime import datetime

class StateSnapshot:
 def __init__(self):
 self.snapshots = {}

 def create_snapshot(self, page, name):
 """创建状态快照"""
 self.snapshots[name] = {
 'url': page.url,
 'cookies': page.context.cookies(),
 'storage': page.evaluate('Object.entries(localStorage)'),
 'timestamp': datetime.now().isoformat(),
 }

 def restore_snapshot(self, page, name):
 """恢复状态快照"""
 if name not in self.snapshots:
 raise ValueError(f"Snapshot {name} not found")

 snapshot = self.snapshots[name]

 # 导航到 URL
 page.goto(snapshot['url'])

 # 恢复 Cookies
 page.context.clear_cookies()
 for cookie in snapshot['cookies']:
 page.context.add_cookie(cookie)

 # 恢复 Storage
 page.evaluate(f'''
 localStorage.clear();
 {snapshot['storage'].forEach(([k, v]) => {{
 localStorage.setItem(k, v);
 }})}
 ''')

 def save_to_disk(self, filepath):
 with open(filepath, 'wb') as f:
 pickle.dump(self.snapshots, f)

 def load_from_disk(self, filepath):
 with open(filepath, 'rb') as f:
 self.snapshots = pickle.load(f)

5.4 IndexedDB 管理

IndexedDB 存储操作

def save_indexeddb(page, profile_id):
 """保存 IndexedDB 数据"""
 indexeddb_data = page.evaluate('''
 async () => {
 const dbs = await indexedDB.databases();
 const result = {};

 for (const db of dbs) {
 try {
 const request = indexedDB.open(db.name);
 const dbInstance = await new Promise((resolve, reject) => {
 request.onsuccess = () => resolve(request.result);
 request.onerror = () => reject(request.error);
 });

 const stores = {};
 for (const storeName of dbInstance.objectStoreNames) {
 const transaction = dbInstance.transaction(storeName, 'readonly');
 const store = transaction.objectStore(storeName);
 const items = await new Promise((resolve, reject) => {
 const request = store.getAll();
 request.onsuccess = () => resolve(request.result);
 request.onerror = () => reject(request.error);
 });
 stores[storeName] = items;
 }

 result[db.name] = stores;
 dbInstance.close();
 } catch (e) {
 console.error('Error accessing DB:', db.name, e);
 }
 }

 return result;
 }
 ''')

 with open(f'indexeddb/{profile_id}.json', 'w') as f:
 json.dump(indexeddb_data, f)

def restore_indexeddb(page, profile_id):
 """恢复 IndexedDB 数据"""
 with open(f'indexeddb/{profile_id}.json') as f:
 indexeddb_data = json.load(f)

 page.evaluate(f'''
 async (data) => {{
 for (const [dbName, stores] of Object.entries(data)) {{
 try {{
 const request = indexedDB.open(dbName, 1);

 request.onupgradeneeded = (event) => {{
 const db = event.target.result;
 for (const storeName of Object.keys(stores)) {{
 if (!db.objectStoreNames.contains(storeName)) {{
 db.createObjectStore(storeName, {{ keyPath: 'id' }});
 }}
 }}
 }};

 const db = await new Promise((resolve, reject) => {{
 request.onsuccess = () => resolve(request.result);
 request.onerror = () => reject(request.error);
 }});

 for (const [storeName, items] of Object.entries(stores)) {{
 const transaction = db.transaction(storeName, 'readwrite');
 const store = transaction.objectStore(storeName);

 for (const item of items) {{
 store.put(item);
 }}
 }}

 await new Promise((resolve, reject) => {{
 const transaction = db.transaction([...db.objectStoreNames], 'readwrite');
 transaction.oncomplete = () => resolve();
 transaction.onerror = () => reject(transaction.error);
 }});

 db.close();
 }} catch (e) {{
 console.error('Error restoring DB:', dbName, e);
 }}
 }}
 }}
 ''', indexeddb_data)

5.5 SessionStorage 管理

会话存储持久化

class SessionStorageManager:
 def __init__(self, storage_path):
 self.storage_path = Path(storage_path)
 self.storage_path.mkdir(exist_ok=True)

 def save_session_storage(self, page, session_id):
 """保存 SessionStorage"""
 storage_data = page.evaluate('''
 () => {
 const data = {};
 for (let i = 0; i < sessionStorage.length; i++) {
 const key = sessionStorage.key(i);
 data[key] = sessionStorage.getItem(key);
 }
 return data;
 }
 ''')

 storage_file = self.storage_path / f'session_{session_id}.json'
 with open(storage_file, 'w') as f:
 json.dump({
 'data': storage_data,
 'timestamp': time.time()
 }, f)

 def restore_session_storage(self, page, session_id):
 """恢复 SessionStorage"""
 storage_file = self.storage_path / f'session_{session_id}.json'

 if not storage_file.exists():
 return False

 with open(storage_file) as f:
 storage = json.load(f)

 # 检查是否过期（1小时）
 if time.time() - storage['timestamp'] > 3600:
 return False

 page.evaluate(f'''
 (data) => {{
 sessionStorage.clear();
 for (const [key, value] of Object.entries(data)) {{
 sessionStorage.setItem(key, value);
 }}
 }}
 ''', storage['data'])

 return True

多账号并发管理

import asyncio
from concurrent.futures import ThreadPoolExecutor

class MultiAccountCookieManager:
 """多账号 Cookie 管理器"""

 def __init__(self, storage_path):
 self.storage_path = Path(storage_path)
 self.storage_path.mkdir(exist_ok=True)
 self.accounts = {} # {account_id: {cookies, metadata}}
 self.lock = asyncio.Lock()

 async def load_account(self, account_id):
 """加载账号 Cookies"""
 async with self.lock:
 if account_id in self.accounts:
 return self.accounts[account_id]

 account_file = self.storage_path / f'account_{account_id}.json'

 if account_file.exists():
 with open(account_file) as f:
 self.accounts[account_id] = json.load(f)

 # 检查 Cookies 是否过期
 if self._is_account_valid(account_id):
 return self.accounts[account_id]

 return None

 def _is_account_valid(self, account_id):
 """检查账号是否有效"""
 account = self.accounts.get(account_id)
 if not account:
 return False

 # 检查关键 Cookie
 for cookie in account.get('cookies', []):
 if cookie.get('name') in ['sessionid', 'auth_token']:
 if 'expires' in cookie and cookie['expires'] < time.time():
 return False

 return True

 async def refresh_account(self, account_id, browser_context):
 """刷新账号 Cookies"""
 # 获取当前 Cookies
 cookies = await browser_context.cookies()

 # 获取存储
 storage = await browser_context.evaluate('''
 () => ({
 localStorage: Object.entries(localStorage),
 sessionStorage: Object.entries(sessionStorage)
 })
 ''')

 # 更新账号信息
 self.accounts[account_id] = {
 'cookies': cookies,
 'storage': storage,
 'updated_at': time.time()
 }

 # 保存到文件
 account_file = self.storage_path / f'account_{account_id}.json'
 with open(account_file, 'w') as f:
 json.dump(self.accounts[account_id], f)

 async def get_available_account(self):
 """获取可用账号"""
 async with self.lock:
 for account_id, account in self.accounts.items():
 if self._is_account_valid(account_id):
 # 更新最后使用时间
 account['last_used'] = time.time()
 return account_id

 return None

class CookieRefreshManager:
 """Cookie 自动刷新管理器"""

 def __init__(self, cookie_manager, check_interval=300):
 self.cookie_manager = cookie_manager
 self.check_interval = check_interval
 self.refreshing = set()

 async def start_auto_refresh(self):
 """启动自动刷新"""
 while True:
 await asyncio.sleep(self.check_interval)

 # 检查需要刷新的账号
 accounts_to_refresh = await self._get_expired_accounts()

 for account_id in accounts_to_refresh:
 if account_id not in self.refreshing:
 asyncio.create_task(self._refresh_account(account_id))

 async def _get_expired_accounts(self):
 """获取即将过期的账号"""
 expired = []
 threshold = time.time() + 3600 # 1小时内过期

 for account_id in self.cookie_manager.accounts:
 account = self.cookie_manager.accounts[account_id]

 for cookie in account.get('cookies', []):
 if 'expires' in cookie and cookie['expires'] < threshold:
 expired.append(account_id)
 break

 return expired

 async def _refresh_account(self, account_id):
 """刷新指定账号"""
 self.refreshing.add(account_id)

 try:
 # 启动浏览器
 browser = await self._launch_browser_for_account(account_id)

 # 导航到目标站点
 await browser.goto('https://example.com')

 # 等待登录态恢复
 await asyncio.sleep(5)

 # 刷新 Cookie
 await self.cookie_manager.refresh_account(account_id, browser)

 finally:
 self.refreshing.discard(account_id)
 await browser.close()

5.7 Cache API 管理

缓存存储操作

class CacheAPIManager:
 """Cache API 管理器"""

 async def list_caches(self, page):
 """列出所有缓存"""
 return await page.evaluate('''
 async () => {
 const cacheNames = await caches.keys();
 const caches = {};

 for (const cacheName of cacheNames) {
 const cache = await caches.open(cacheName);
 const keys = await cache.keys();
 caches[cacheName] = keys.map(req => req.url);
 }

 return caches;
 }
 ''')

 async def clear_all_caches(self, page):
 """清除所有缓存"""
 await page.evaluate('''
 async () => {
 const cacheNames = await caches.keys();
 await Promise.all(
 cacheNames.map(name => caches.delete(name))
 );
 return cacheNames.length;
 }
 ''')

 async def save_cache_state(self, page, profile_id):
 """保存缓存状态"""
 caches = await self.list_caches(page)

 with open(f'cache/{profile_id}_caches.json', 'w') as f:
 json.dump({
 'caches': caches,
 'timestamp': time.time()
 }, f)

5.8 Service Worker 管理

Service Worker 控制

class ServiceWorkerManager:
 """Service Worker 管理器"""

 async def register_sw(self, page, sw_url):
 """注册 Service Worker"""
 return await page.evaluate(f'''
 async () => {{
 if ('serviceWorker' in navigator) {{
 try {{
 const registration = await navigator.serviceWorker.register('{sw_url}');
 return {{ success: true, scope: registration.scope }};
 }} catch (e) {{
 return {{ success: false, error: e.message }};
 }}
 }}
 return {{ success: false, error: 'Not supported' }};
 }}
 ''')

 async def unregister_all_sw(self, page):
 """注销所有 Service Worker"""
 return await page.evaluate('''
 async () => {
 const registrations = await navigator.serviceWorker.getRegistrations();
 const results = [];

 for (const registration of registrations) {
 const result = await registration.unregister();
 results.push({
 scope: registration.scope,
 unregistered: result
 });
 }

 return results;
 }
 ''')

 async def get_sw_state(self, page):
 """获取 Service Worker 状态"""
 return await page.evaluate('''
 async () => {
 if (!('serviceWorker' in navigator)) {
 return { supported: false };
 }

 const registrations = await navigator.serviceWorker.getRegistrations();

 return {
 supported: true,
 controller: navigator.serviceWorker.controller?.scriptURL,
 registrations: registrations.map(r => ({
 scope: r.scope,
 state: r.active?.state,
 scriptURL: r.active?.scriptURL
 }))
 };
 }
 ''')

六、验证层：验证码处理

6.1 验证码类型与应对

验证码类型	难度	识别方案	成功率
图形验证码（简单）	★★☆☆☆	OCR/Tesseract	70-90%
图形验证码（复杂）	★★★☆☆	CNN 模型训练	80-95%
滑动验证码	★★★★☆	轨迹计算/模拟拖动	60-85%
点击验证码	★★★★☆	目标检测/模拟点击	70-90%
行为验证码	★★★★★	行为采集/完整模拟	40-70%
reCAPTCHA v2	★★★★★	第三方服务/人工介入	50-80%
reCAPTCHA v3	★★★★★	行为训练/信誉管理	30-60%

6.2 OCR 识别方案

import pytesseract
from PIL import Image
import cv2
import numpy as np

class CaptchaSolver:
 def preprocess_image(self, image_path):
 """图像预处理"""
 img = cv2.imread(image_path)

 # 灰度化
 gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

 # 二值化
 _, binary = cv2.threshold(gray, 0, 255,
 cv2.THRESH_BINARY + cv2.THRESH_OTSU)

 # 去噪
 denoised = cv2.medianBlur(binary, 3)

 return Image.fromarray(denoised)

 def solve_text_captcha(self, image_path):
 """文字验证码识别"""
 processed = self.preprocess_image(image_path)

 # Tesseract OCR
 config = r'--oem 3 --psm 7 -c tessedit_char_whitelist=0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'
 result = pytesseract.image_to_string(processed, config=config)

 return result.strip()

 def solve_with_model(self, image_path, model):
 """使用训练的模型识别"""
 img = cv2.imread(image_path)
 img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

 # 预处理
 img = cv2.resize(img, (160, 60))
 img = img.astype('float32') / 255.0

 # 推理
 prediction = model.predict(np.expand_dims(img, axis=0))
 result = self.decode_ctc(prediction)

 return result

6.3 滑动验证码破解

import cv2
import numpy as np

class SliderSolver:
 def find_template(self, background, template):
 """模板匹配找到滑块位置"""
 bg = cv2.imread(background)
 tpl = cv2.imread(template)

 # 多尺度匹配
 for scale in np.linspace(0.8, 1.2, 10):
 resized = cv2.resize(tpl, None,
 fx=scale, fy=scale,
 interpolation=cv2.INTER_AREA)

 if resized.shape[0] > bg.shape[0] or resized.shape[1] > bg.shape[1]:
 continue

 result = cv2.matchTemplate(bg, resized, cv2.TM_CCOEFF_NORMED)
 _, max_val, _, max_loc = cv2.minMaxLoc(result)

 if max_val > 0.8: # 相似度阈值
 return max_loc[0] # 返回 x 坐标

 return None

 def get_track(self, distance):
 """生成滑动轨迹"""
 track = []
 current = 0

 # 加速段
 while current < distance * 0.7:
 step = random.randint(5, 10)
 track.append(step)
 current += step

 # 减速段
 while current < distance:
 step = random.randint(1, 5)
 if current + step > distance:
 step = distance - current
 track.append(step)
 current += step

 return track

 def solve_slider(self, page, slider_element, distance):
 """执行滑动操作"""
 track = self.get_track(distance)

 # 按下
 slider_element.hover()
 page.mouse.down()

 # 移动
 for step in track:
 page.mouse.move_by(step, random.randint(-1, 1))
 time.sleep(random.uniform(0.01, 0.03))

 # 释放
 page.mouse.up()

6.4 reCAPTCHA v3 对抗

class ReCaptchaV3Solver:
 def analyze_score_threshold(self, page):
 """分析 score 阈值"""
 # 注入代码监控 reCAPTCHA 行为
 script = """
 window.recaptchaScores = [];
 const originalExecute = grecaptcha.execute;
 grecaptcha.execute = function(siteKey, options) {
 return originalExecute.call(this, siteKey, options).then(token => {
 // 模拟发送到验证接口
 fetch('/recaptcha/verify', {
 method: 'POST',
 body: JSON.stringify({ token }),
 }).then(r => r.json()).then(data => {
 window.recaptchaScores.push(data.score);
 });
 return token;
 });
 };
 """
 page.evaluate(script)

 def build_trust(self, page):
 """构建信任分数"""
 # 1. 首次访问，建立基线
 page.goto('https://example.com')
 time.sleep(5) # 停留建立正常行为模式

 # 2. 模拟正常用户行为
 page.mouse.move(500, 300)
 time.sleep(2)
 page.mouse.wheel(0, 300)
 time.sleep(1)

 # 3. 重复访问提高信任
 for _ in range(3):
 page.reload()
 time.sleep(random.uniform(3, 8))

6.5 点击验证码破解

图像目标检测

class ClickCaptchaSolver:
 """点击验证码破解器"""

 def __init__(self):
 self.target_detector = self._load_yolo_model()

 def _load_yolo_model(self):
 """加载 YOLO 目标检测模型"""
 # 使用预训练的 YOLOv8 模型
 from ultralytics import YOLO
 return YOLO('yolov8n.pt')

 def find_targets(self, image_path, target_type):
 """查找目标对象"""
 import cv2

 img = cv2.imread(image_path)

 # 运行目标检测
 results = self.target_detector(img)

 # 提取目标位置
 targets = []
 for result in results:
 boxes = result.boxes
 for box in boxes:
 # 获取类别和置信度
 cls = int(box.cls[0])
 conf = float(box.conf[0])

 # 根据目标类型过滤
 if self._is_target_type(cls, target_type) and conf > 0.5:
 # 获取边界框坐标
 x1, y1, x2, y2 = box.xyxy[0].tolist()
 center_x = int((x1 + x2) / 2)
 center_y = int((y1 + y2) / 2)

 targets.append({
 'center': (center_x, center_y),
 'bbox': (int(x1), int(y1), int(x2), int(y2)),
 'confidence': conf
 })

 return targets

 def _is_target_type(self, cls, target_type):
 """检查是否为目标类型"""
 # COCO 数据集类别映射
 coco_classes = {
 0: 'person', 1: 'bicycle', 2: 'car', 3: 'motorcycle',
 # ... 更多类别
 }

 detected_class = coco_classes.get(cls, '')
 return target_type.lower() in detected_class.lower()

 def solve_click_captcha(self, page, image_selector, target_type):
 """解决点击验证码"""
 # 获取验证码图像位置
 captcha_element = page.query_selector(image_selector)
 box = captcha_element.bounding_box()

 # 截图验证码区域
 captcha_image = page.screenshot({
 'clip': {
 'x': box['x'],
 'y': box['y'],
 'width': box['width'],
 'height': box['height']
 }
 })

 # 保存临时图像
 temp_path = '/tmp/captcha.png'
 with open(temp_path, 'wb') as f:
 f.write(captcha_image)

 # 查找目标
 targets = self.find_targets(temp_path, target_type)

 # 点击每个目标
 for target in targets:
 # 计算点击位置（相对于页面）
 click_x = box['x'] + target['center'][0]
 click_y = box['y'] + target['center'][1]

 # 点击
 page.mouse.click(click_x, click_y)
 time.sleep(random.uniform(0.2, 0.4))

 return len(targets)

6.6 行为验证码完整模拟

综合行为模拟

class BehaviorCaptchaSolver:
 """行为验证码破解器"""

 def __init__(self):
 self.mouse_sim = MouseSimulator()
 self.keyboard_sim = KeyboardSimulator()

 async def solve(self, page, captcha_config):
 """解决行为验证码"""
 # 1. 等待验证码加载
 await self._wait_for_captcha(page, captcha_config['selector'])

 # 2. 鼠标悬停（模拟用户发现验证码）
 captcha_element = page.query_selector(captcha_config['selector'])
 box = captcha_element.bounding_box()

 self.mouse_sim.natural_move(
 page,
 (box.x + box.width / 2, box.y + box.height / 2),
 duration=0.8
 )
 time.sleep(random.uniform(0.5, 1.0))

 # 3. 点击开始验证
 page.mouse.click(box.x + box.width / 2, box.y + box.height / 2)
 time.sleep(random.uniform(1, 2))

 # 4. 等待验证完成
 await self._wait_for_verification(page)

 # 5. 处理可能的二次验证
 if await self._is_secondary_challenge(page):
 await self._solve_secondary(page, captcha_config)

 return True

 async def _wait_for_captcha(self, page, selector, timeout=10):
 """等待验证码出现"""
 start_time = time.time()

 while time.time() - start_time < timeout:
 try:
 element = page.query_selector(selector)
 if element and element.is_visible():
 return True
 except:
 pass

 await asyncio.sleep(0.5)

 return False

 async def _wait_for_verification(self, page, timeout=30):
 """等待验证完成"""
 start_time = time.time()

 while time.time() - start_time < timeout:
 # 检查是否通过验证
 is_passed = await page.evaluate('''
 () => {
 // 常见的验证通过标识
 return document.querySelector('.captcha-success') !== null ||
 document.querySelector('.verified') !== null ||
 !document.querySelector('.captcha-container');
 }
 ''')

 if is_passed:
 return True

 # 模拟人类等待时的行为
 if random.random() < 0.1:
 await self._simulate_waiting_behavior(page)

 await asyncio.sleep(1)

 return False

 async def _simulate_waiting_behavior(self, page):
 """模拟等待时的行为"""
 behaviors = [
 self._small_mouse_move,
 self._subtle_scroll,
 self._blink_pause
 ]

 behavior = random.choice(behaviors)
 await behavior(page)

 async def _small_mouse_move(self, page):
 """小幅度鼠标移动"""
 current_pos = page.mouse.position
 offset_x = random.randint(-20, 20)
 offset_y = random.randint(-20, 20)
 page.mouse.move(
 current_pos['x'] + offset_x,
 current_pos['y'] + offset_y
 )

 async def _subtle_scroll(self, page):
 """细微滚动"""
 scroll_amount = random.randint(-30, 30)
 page.mouse.wheel(0, scroll_amount)
 time.sleep(0.1)

 async def _blink_pause(self, page):
 """短暂停顿"""
 time.sleep(random.uniform(0.3, 0.8))

 async def _is_secondary_challenge(self, page):
 """检查是否有二次验证"""
 return await page.evaluate('''
 () => {
 const secondaryIndicators = [
 '.slider-captcha',
 '.puzzle-captcha',
 '.image-captcha',
 '#captcha-challenge'
 ];

 return secondaryIndicators.some(selector =>
 document.querySelector(selector) !== null
 );
 }
 ''')

 async def _solve_secondary(self, page, config):
 """解决二次验证"""
 # 检测验证码类型
 captcha_type = await self._detect_captcha_type(page)

 if captcha_type == 'slider':
 slider_solver = SliderSolver()
 await slider_solver.solve(page)
 elif captcha_type == 'puzzle':
 puzzle_solver = PuzzleSolver()
 await puzzle_solver.solve(page)
 elif captcha_type == 'image':
 image_solver = ImageCaptchaSolver()
 await image_solver.solve(page)

6.7 验证码识别服务集成

第三方验证码服务

class CaptchaServiceAPI:
 """验证码识别服务 API 集成"""

 def __init__(self, service_type='2captcha', api_key=None):
 self.service_type = service_type
 self.api_key = api_key
 self.base_urls = {
 '2captcha': 'http://2captcha.com',
 'anticaptcha': 'https://api.anti-captcha.com',
 'deathbycaptcha': 'http://api.dbcapi.me',
 }

 def solve_recaptcha_v2(self, page, site_key, action='verify'):
 """解决 reCAPTCHA v2"""
 import requests

 # 1. 创建任务
 create_task_url = f'{self.base_urls[self.service_type]}/createTask'

 task_data = {
 'clientKey': self.api_key,
 'task': {
 'type': 'RecaptchaV2TaskProxyless',
 'websiteURL': page.url,
 'websiteKey': site_key,
 'isInvisible': False
 }
 }

 response = requests.post(create_task_url, json=task_data)
 task_id = response.json()['taskId']

 # 2. 等待结果
 while True:
 result_url = f'{self.base_urls[self.service_type]}/getTaskResult'
 result_data = {
 'clientKey': self.api_key,
 'taskId': task_id
 }

 result = requests.post(result_url, json=result_data).json()

 if result['status'] == 'ready':
 return result['solution']['gRecaptchaResponse']

 time.sleep(2)

 def solve_hcaptcha(self, page, site_key):
 """解决 hCaptcha"""
 import requests

 create_task_url = f'{self.base_urls[self.service_type]}/createTask'

 task_data = {
 'clientKey': self.api_key,
 'task': {
 'type': 'HCaptchaTaskProxyless',
 'websiteURL': page.url,
 'websiteKey': site_key
 }
 }

 response = requests.post(create_task_url, json=task_data)
 task_id = response.json()['taskId']

 # 等待结果
 while True:
 result_url = f'{self.base_urls[self.service_type]}/getTaskResult'
 result_data = {
 'clientKey': self.api_key,
 'taskId': task_id
 }

 result = requests.post(result_url, json=result_data).json()

 if result['status'] == 'ready':
 return result['solution']['gRecaptchaResponse']

 time.sleep(2)

6.8 验证码自动识别框架

统一验证码处理接口

class CaptchaSolverFramework:
 """验证码解决框架"""

 def __init__(self):
 self.solvers = {
 'text': TextCaptchaSolver(),
 'slider': SliderSolver(),
 'click': ClickCaptchaSolver(),
 'recaptcha': ReCaptchaSolver(),
 'hcaptcha': HCaptchaSolver(),
 'behavior': BehaviorCaptchaSolver(),
 }
 self.fallback_service = CaptchaServiceAPI(service_type='2captcha')

 async def solve(self, page, captcha_info):
 """自动解决验证码"""
 captcha_type = captcha_info.get('type', 'auto')

 # 自动检测类型
 if captcha_type == 'auto':
 captcha_type = await self._detect_captcha_type(page, captcha_info)

 # 尝试本地解决
 solver = self.solvers.get(captcha_type)
 if solver:
 try:
 result = await solver.solve(page, captcha_info)
 if result:
 return result
 except Exception as e:
 print(f'本地解决失败: {e}')

 # 回退到第三方服务
 print('使用第三方验证码服务')
 return await self._fallback_solve(page, captcha_info)

 async def _detect_captcha_type(self, page, captcha_info):
 """自动检测验证码类型"""
 return await page.evaluate('''
 () => {
 // 检测 reCAPTCHA
 if (document.querySelector('.g-recaptcha') ||
 document.querySelector('[data-sitekey]')) {
 return 'recaptcha';
 }

 // 检测 hCaptcha
 if (document.querySelector('.h-captcha') ||
 document.querySelector('[data-hcaptcha]')) {
 return 'hcaptcha';
 }

 // 检测滑块验证
 if (document.querySelector('.slider-captcha') ||
 document.querySelector('.slide-verify')) {
 return 'slider';
 }

 // 检测点选验证
 if (document.querySelector('.click-captcha') ||
 document.querySelector('.verify-click')) {
 return 'click';
 }

 // 检测文字验证
 if (document.querySelector('.text-captcha') ||
 document.querySelector('input[name="captcha"]')) {
 return 'text';
 }

 return 'behavior';
 }
 ''')

 async def _fallback_solve(self, page, captcha_info):
 """使用第三方服务解决"""
 captcha_type = captcha_info.get('type', 'recaptcha')

 if captcha_type == 'recaptcha':
 return self.fallback_service.solve_recaptcha_v2(
 page,
 captcha_info['site_key']
 )
 elif captcha_type == 'hcaptcha':
 return self.fallback_service.solve_hcaptcha(
 page,
 captcha_info['site_key']
 )

 return None

6.9 验证码缓存策略

验证码结果缓存

class CaptchaCache:
 """验证码缓存管理"""

 def __init__(self, cache_dir='./captcha_cache'):
 self.cache_dir = Path(cache_dir)
 self.cache_dir.mkdir(exist_ok=True)
 self.cache_ttl = 3600 # 1小时过期

 def get_cached_solution(self, captcha_hash):
 """获取缓存的解决方案"""
 cache_file = self.cache_dir / f'{captcha_hash}.json'

 if cache_file.exists():
 with open(cache_file) as f:
 cache = json.load(f)

 # 检查是否过期
 if time.time() - cache['timestamp'] < self.cache_ttl:
 return cache['solution']

 return None

 def save_solution(self, captcha_hash, solution):
 """保存解决方案"""
 cache_file = self.cache_dir / f'{captcha_hash}.json'

 with open(cache_file, 'w') as f:
 json.dump({
 'solution': solution,
 'timestamp': time.time()
 }, f)

 def hash_captcha(self, image_data):
 """生成验证码哈希"""
 import hashlib
 return hashlib.md5(image_data).hexdigest()

七、架构层：分布式爬虫

7.1 分布式架构设计

分布式反检测爬虫架构
│
├── 任务调度中心
│ ├── 任务队列（Redis/消息队列）
│ ├── 策略路由
│ └── 失败重试机制
│
├── Worker 节点池
│ ├── 节点 A - US 代理池
│ ├── 节点 B - EU 代理池
│ └── 节点 C - CN 代理池
│
├── 资源管理
│ ├── 代理池服务
│ ├── Cookie 池服务
│ └── 浏览器实例池
│
└── 监控与告警
├── 成功率监控
├── 检测率监控
└── 资源状态监控

7.2 反检测策略库

class AntiDetectionStrategy:
 """反检测策略基类"""
 def __init__(self, browser, proxy):
 self.browser = browser
 self.proxy = proxy
 self.setup()

 def setup(self):
 """初始化环境"""
 raise NotImplementedError

 def navigate(self, url):
 """导航到目标"""
 raise NotImplementedError

 def extract(self, selector):
 """提取数据"""
 raise NotImplementedError


class PlaywrightStealthStrategy(AntiDetectionStrategy):
 """Playwright 伪装策略"""
 def setup(self):
 # 1. 注入 stealth 脚本
 stealth_script = self._load_stealth_js()
 self.browser.add_init_script(stealth_script)

 # 2. 设置 User-Agent
 self.browser.set_extra_http_headers({
 'User-Agent': self._get_realistic_ua()
 })

 def navigate(self, url):
 page = self.browser.new_page()

 # 模拟人类行为
 self._simulate_navigation(page, url)

 return page

 def _simulate_navigation(self, page, url):
 """模拟导航行为"""
 # 首次访问主页
 if not self.browser.context.pages:
 page.goto(url)
 time.sleep(random.uniform(2, 5))

 # 后续访问
 else:
 # 随机滚动
 self._scroll_randomly(page)
 time.sleep(random.uniform(1, 3))

 # 导航
 page.goto(url)

 def _scroll_randomly(self, page):
 """随机滚动"""
 page.evaluate('window.scrollBy(0, Math.random() * 500)')


class StrategyRouter:
 """策略路由器"""
 def __init__(self):
 self.strategies = {
 'default': PlaywrightStealthStrategy,
 'strict': StrictStealthStrategy,
 'minimal': MinimalStrategy,
 }
 self.strategy_stats = {}

 def get_strategy(self, target, risk_level='default'):
 """根据目标选择策略"""
 # 检查历史成功率
 history = self.strategy_stats.get(target, {})

 # 如果成功率低，切换策略
 if history.get('success_rate', 1) < 0.5:
 risk_level = 'strict'

 return self.strategies[risk_level]

 def update_stats(self, target, strategy_name, success):
 """更新策略统计"""
 if target not in self.strategy_stats:
 self.strategy_stats[target] = {}

 stats = self.strategy_stats[target]
 stats['total'] = stats.get('total', 0) + 1
 stats['success'] = stats.get('success', 0) + (1 if success else 0)
 stats['success_rate'] = stats['success'] / stats['total']

7.3 A/B 测试与对抗

class ABTestingFramework:
 """A/B 测试框架"""
 def __init__(self):
 self.experiments = {}
 self.results = {}

 def create_experiment(self, name, variations):
 """创建实验"""
 self.experiments[name] = {
 'variations': variations,
 'traffic': {v: 0 for v in variations},
 'conversions': {v: 0 for v in variations},
 }

 def assign_variation(self, name, session_id):
 """为会话分配变体"""
 exp = self.experiments[name]

 if session_id not in self.results:
 # 随机分配
 variation = random.choice(exp['variations'])
 self.results[session_id] = {'variation': variation}
 exp['traffic'][variation] += 1

 return self.results[session_id]['variation']

 def record_conversion(self, name, session_id):
 """记录转化"""
 exp = self.experiments[name]
 variation = self.results[session_id]['variation']
 exp['conversions'][variation] += 1

 def get_results(self, name):
 """获取实验结果"""
 exp = self.experiments[name]
 results = {}

 for v in exp['variations']:
 traffic = exp['traffic'][v]
 conversions = exp['conversions'][v]
 results[v] = {
 'traffic': traffic,
 'conversions': conversions,
 'rate': conversions / traffic if traffic > 0 else 0
 }

 return results


# 使用示例：测试不同反检测策略
ab_test = ABTestingFramework()
ab_test.create_experiment('anti-detection', [
 'basic-headers',
 'stealth-plugin',
 'full-simulation',
])

# 为每个会话分配策略
strategy = ab_test.assign_variation('anti-detection', session_id)

7.4 速率限制

令牌桶算法

import time
from threading import Lock

class TokenBucket:
 def __init__(self, rate, capacity):
 """令牌桶限流

 Args:
 rate: 令牌生成速率（个/秒）
 capacity: 桶容量
 """
 self.rate = rate
 self.capacity = capacity
 self.tokens = capacity
 self.last_time = time.time()
 self.lock = Lock()

 def consume(self, tokens=1):
 """消费令牌"""
 with self.lock:
 now = time.time()
 # 补充令牌
 self.tokens = min(
 self.capacity,
 self.tokens + (now - self.last_time) * self.rate
 )
 self.last_time = now

 # 检查是否有足够令牌
 if self.tokens >= tokens:
 self.tokens -= tokens
 return True
 return False

 def wait(self, tokens=1):
 """等待令牌可用"""
 while not self.consume(tokens):
 time.sleep(0.1)

滑动窗口算法

from collections import deque
import time

class SlidingWindow:
 def __init__(self, limit, window):
 """滑动窗口限流

 Args:
 limit: 时间窗口内最大请求数
 window: 时间窗口（秒）
 """
 self.limit = limit
 self.window = window
 self.requests = deque()

 def allow(self):
 """检查是否允许请求"""
 now = time.time()

 # 移除窗口外的请求
 while self.requests and self.requests[0] <= now - self.window:
 self.requests.popleft()

 # 检查是否超过限制
 if len(self.requests) < self.limit:
 self.requests.append(now)
 return True
 return False

自适应限流

class AdaptiveRateLimiter:
 """自适应限流器"""
 def __init__(self, initial_rate=1, min_rate=0.1, max_rate=10):
 self.rate = initial_rate
 self.min_rate = min_rate
 self.max_rate = max_rate
 self.success_count = 0
 self.failure_count = 0
 self.window_size = 10
 self.history = []

 def record(self, success):
 """记录请求结果"""
 self.history.append(success)
 if len(self.history) > self.window_size:
 self.history.pop(0)

 # 计算成功率
 success_rate = sum(self.history) / len(self.history)

 # 调整速率
 if success_rate > 0.9:
 self.rate = min(self.max_rate, self.rate * 1.1)
 elif success_rate < 0.5:
 self.rate = max(self.min_rate, self.rate * 0.8)

 def wait_time(self):
 """获取等待时间"""
 return max(0, 1 / self.rate)

 def wait(self):
 """等待下一个请求"""
 time.sleep(self.wait_time())

7.5 AI 智能体

强化学习决策

import numpy as np

class RLCrawlerAgent:
 """基于强化学习的爬虫智能体"""

 def __init__(self, state_size, action_size):
 self.state_size = state_size
 self.action_size = action_size
 self.memory = []
 self.epsilon = 1.0 # 探索率
 self.epsilon_min = 0.01
 self.epsilon_decay = 0.995

 def act(self, state):
 """选择动作"""
 if np.random.random() <= self.epsilon:
 # 探索：随机选择
 return np.random.choice(self.action_size)

 # 利用：选择最佳动作
 return np.argmax(self.model.predict(state))

 def remember(self, state, action, reward, next_state, done):
 """存储经验"""
 self.memory.append((state, action, reward, next_state, done))

 def replay(self, batch_size=32):
 """经验回放训练"""
 if len(self.memory) < batch_size:
 return

 # 随机采样
 samples = np.random.choice(len(self.memory), batch_size, replace=False)

 for i in samples:
 state, action, reward, next_state, done = self.memory[i]

 # Q-learning 更新
 target = reward
 if not done:
 target = reward + self.gamma * np.amax(
 self.model.predict(next_state)[0]
 )

 target_f = self.model.predict(state)
 target_f[0][action] = target
 self.model.fit(state, target_f, epochs=1, verbose=0)

 # 衰减探索率
 if self.epsilon > self.epsilon_min:
 self.epsilon *= self.epsilon_decay


# 使用示例
agent = RLCrawlerAgent(state_size=10, action_size=5)

# 状态: [成功率, 被检测次数, 请求间隔, ...]
# 动作: [增加延迟, 减少延迟, 切换代理, 重试, 放弃]
state = get_current_state()
action = agent.act(state)

自适应导航

class AdaptiveNavigator:
 """自适应导航器"""

 def __init__(self):
 self.strategies = {
 'conservative': ConservativeStrategy(),
 'aggressive': AggressiveStrategy(),
 'balanced': BalancedStrategy(),
 }
 self.current_strategy = 'balanced'
 self.performance_history = {}

 def navigate(self, page, url):
 """自适应导航"""
 # 1. 检查历史性能
 domain = urlparse(url).netloc
 if domain in self.performance_history:
 success_rate = self.performance_history[domain]['success_rate']

 # 动态选择策略
 if success_rate < 0.3:
 self.current_strategy = 'conservative'
 elif success_rate > 0.8:
 self.current_strategy = 'aggressive'
 else:
 self.current_strategy = 'balanced'

 # 2. 执行策略
 strategy = self.strategies[self.current_strategy]
 result = strategy.execute(page, url)

 # 3. 更新性能记录
 self._record_performance(domain, result)

 return result

 def _record_performance(self, domain, result):
 """记录性能数据"""
 if domain not in self.performance_history:
 self.performance_history[domain] = {
 'success': 0,
 'failure': 0,
 'success_rate': 0
 }

 if result['success']:
 self.performance_history[domain]['success'] += 1
 else:
 self.performance_history[domain]['failure'] += 1

 total = (self.performance_history[domain]['success'] +
 self.performance_history[domain]['failure'])
 self.performance_history[domain]['success_rate'] = (
 self.performance_history[domain]['success'] / total
 )

动态选择器

class DynamicSelector:
 """动态选择器生成器"""

 def __init__(self):
 self.selector_cache = {}
 self.patterns = [
 r'\[data-testid="([^"]+)"\]',
 r'\[id="([^"]+)"\]',
 r'\.([a-zA-Z][\w-]+)',
 r'#([a-zA-Z][\w-]+)',
 ]

 def find_selector(self, element, page):
 """为元素生成选择器"""
 # 1. 尝试从缓存获取
 element_id = id(element)
 if element_id in self.selector_cache:
 return self.selector_cache[element_id]

 # 2. 生成候选选择器
 selectors = self._generate_selectors(element)

 # 3. 验证选择器唯一性
 for selector in selectors:
 if self._is_unique(selector, page):
 self.selector_cache[element_id] = selector
 return selector

 # 4. 生成 XPath 作为后备
 xpath = self._generate_xpath(element)
 self.selector_cache[element_id] = xpath
 return xpath

 def _generate_selectors(self, element):
 """生成候选选择器"""
 selectors = []

 # data-testid
 test_id = element.get_attribute('data-testid')
 if test_id:
 selectors.append(f'[data-testid="{test_id}"]')

 # id
 elem_id = element.get_attribute('id')
 if elem_id:
 selectors.append(f'#{elem_id}')

 # class
 classes = element.get_attribute('class') or ''
 for cls in classes.split():
 selectors.append(f'.{cls}')

 # tag + attribute
 tag = element.evaluate('el => el.tagName.toLowerCase()')
 selectors.append(tag)

 return selectors

 def _is_unique(self, selector, page):
 """验证选择器是否唯一"""
 try:
 count = page.query_selector_all(selector)
 return len(count) == 1
 except:
 return False

7.6 机器学习应用

特征工程

import numpy as np
from sklearn.feature_extraction import FeatureHasher

class PageFeatureExtractor:
 """页面特征提取器"""

 def __init__(self):
 self.hasher = FeatureHasher(n_features=1024)

 def extract(self, page):
 """提取页面特征"""
 features = {}

 # 1. 结构特征
 features['element_count'] = page.evaluate(
 'document.querySelectorAll("*").length'
 )
 features['script_count'] = page.evaluate(
 'document.querySelectorAll("script").length'
 )
 features['iframe_count'] = page.evaluate(
 'document.querySelectorAll("iframe").length'
 )

 # 2. 内容特征
 features['text_length'] = len(page.inner_text())
 features['link_count'] = page.evaluate(
 'document.querySelectorAll("a").length'
 )

 # 3. 动态特征
 features['has_webdriver'] = page.evaluate(
 'navigator.webdriver !== undefined'
 )
 features['chrome_object'] = page.evaluate(
 'typeof window.chrome === "object"'
 )

 # 4. 性能特征
 metrics = page.evaluate('''
 () => ({
 domContentLoaded: performance.timing.domContentLoadedEventEnd -
 performance.timing.navigationStart,
 loadComplete: performance.timing.loadEventEnd -
 performance.timing.navigationStart,
 })
 ''')
 features.update(metrics)

 return features

模式识别

from sklearn.ensemble import IsolationForest
from sklearn.preprocessing import StandardScaler

class AnomalyDetector:
 """异常检测器"""

 def __init__(self):
 self.scaler = StandardScaler()
 self.model = IsolationForest(contamination=0.1)
 self.fitted = False

 def fit(self, X):
 """训练模型"""
 X_scaled = self.scaler.fit_transform(X)
 self.model.fit(X_scaled)
 self.fitted = True

 def predict(self, X):
 """预测异常"""
 if not self.fitted:
 return np.zeros(len(X))

 X_scaled = self.scaler.transform(X)
 return self.model.predict(X_scaled)

 def is_anomaly(self, features):
 """检测单条记录是否异常"""
 prediction = self.predict([features])
 return prediction[0] == -1


# 使用示例
detector = AnomalyDetector()

# 正常访问数据
normal_data = [
 {'load_time': 1.2, 'element_count': 500, 'script_count': 10},
 {'load_time': 1.5, 'element_count': 600, 'script_count': 12},
 # ...
]

# 训练
X = [[d['load_time'], d['element_count'], d['script_count']]
 for d in normal_data]
detector.fit(X)

# 检测异常
test_features = {'load_time': 0.1, 'element_count': 50, 'script_count': 0}
if detector.is_anomaly([
 test_features['load_time'],
 test_features['element_count'],
 test_features['script_count']
]):
 print("检测到异常访问模式！可能被识别为爬虫")

预测模型

from sklearn.ensemble import RandomForestClassifier
import joblib

class RiskPredictor:
 """风险预测模型"""

 def __init__(self):
 self.model = RandomForestClassifier(n_estimators=100)
 self.fitted = False

 def train(self, X, y):
 """训练模型

 Args:
 X: 特征矩阵 [[延迟, 代理类型, 指纹完整性, ...], ...]
 y: 标签 [0=成功, 1=被检测, ...]
 """
 self.model.fit(X, y)
 self.fitted = True

 def predict(self, features):
 """预测风险

 Returns:
 risk_score: 0-1 风险分数
 """
 if not self.fitted:
 return 0.5

 # 获取被检测的概率
 proba = self.model.predict_proba([features])[0]
 return proba[1] # 被检测的概率

 def save(self, path):
 """保存模型"""
 joblib.dump(self.model, path)

 def load(self, path):
 """加载模型"""
 self.model = joblib.load(path)
 self.fitted = True


# 使用示例
predictor = RiskPredictor()

# 训练数据
X_train = [
 [1.0, 0, 0.8], # [延迟(s), 代理类型, 指纹完整性]
 [2.0, 1, 0.9],
 [0.5, 0, 0.5],
 # ...
]
y_train = [0, 0, 1, ...] # 0=成功, 1=被检测

predictor.train(X_train, y_train)

# 预测
risk = predictor.predict([1.5, 1, 0.85])
if risk > 0.7:
 print("高风险！建议降低频率或切换策略")

智能分类

from sklearn.cluster import KMeans
from sklearn.feature_extraction.text import TfidfVectorizer

class SiteClassifier:
 """网站类型分类器"""

 def __init__(self, n_clusters=5):
 self.vectorizer = TfidfVectorizer(max_features=100)
 self.cluster = KMeans(n_clusters=n_clusters)
 self.fitted = False

 def fit(self, html_contents):
 """训练分类器"""
 # 提取 TF-IDF 特征
 X = self.vectorizer.fit_transform(html_contents)

 # 聚类
 self.cluster.fit(X)
 self.fitted = True

 def predict(self, html_content):
 """预测网站类型"""
 if not self.fitted:
 return 0

 X = self.vectorizer.transform([html_content])
 return self.cluster.predict(X)[0]

 def get_strategy(self, html_content):
 """根据网站类型获取爬取策略"""
 cluster_id = self.predict(html_content)

 strategies = {
 0: 'ecommerce', # 电商：需要处理图片、价格
 1: 'social', # 社交：需要登录、处理动态加载
 2: 'news', # 新闻：主要是文本内容
 3: 'forum', # 论坛：处理分页、回复
 4: 'corporate', # 企业：简单静态页面
 }

 return strategies.get(cluster_id, 'default')


# 使用示例
classifier = SiteClassifier()

# 训练（使用不同类型网站的 HTML）
training_html = [
 '<html>...电商页面...</html>',
 '<html>...社交页面...</html>',
 # ...
]
classifier.fit(training_html)

# 预测
strategy = classifier.get_strategy(page.content())
print(f"推荐策略: {strategy}")

7.7 分布式任务调度

任务队列设计

import redis
import json
from dataclasses import dataclass
from typing import Optional

@dataclass
class CrawlTask:
 """爬虫任务"""
 url: str
 priority: int = 0
 domain: str = ''
 strategy: str = 'default'
 retries: int = 0
 max_retries: int = 3

class TaskScheduler:
 """分布式任务调度器"""

 def __init__(self, redis_url='redis://localhost:6379'):
 self.redis = redis.from_url(redis_url)
 self.task_queue = 'crawl:tasks'
 self.result_queue = 'crawl:results'
 self.failed_queue = 'crawl:failed'

 def add_task(self, task: CrawlTask):
 """添加任务"""
 task_data = json.dumps({
 'url': task.url,
 'priority': task.priority,
 'domain': task.domain,
 'strategy': task.strategy,
 'retries': task.retries,
 'max_retries': task.max_retries,
 })

 # 使用优先级队列
 self.redis.zadd(f'{self.task_queue}:priority', {
 task_data: task.priority
 })

 def get_task(self) -> Optional[CrawlTask]:
 """获取下一个任务"""
 # 从优先级队列获取最高优先级任务
 result = self.redis.zpopmax(f'{self.task_queue}:priority')

 if result:
 task_data, priority = result[0]
 data = json.loads(task_data)

 return CrawlTask(**data)

 return None

 def complete_task(self, task: CrawlTask, result_data: dict):
 """标记任务完成"""
 result = {
 'url': task.url,
 'status': 'success',
 'data': result_data,
 'timestamp': time.time()
 }

 self.redis.rpush(self.result_queue, json.dumps(result))

 def fail_task(self, task: CrawlTask, error: str):
 """标记任务失败"""
 if task.retries < task.max_retries:
 # 重新加入队列
 task.retries += 1
 self.add_task(task)
 else:
 # 放入失败队列
 result = {
 'url': task.url,
 'status': 'failed',
 'error': error,
 'retries': task.retries,
 'timestamp': time.time()
 }

 self.redis.rpush(self.failed_queue, json.dumps(result))

 def get_queue_size(self) -> dict:
 """获取队列状态"""
 return {
 'pending': self.redis.zcard(f'{self.task_queue}:priority'),
 'completed': self.redis.llen(self.result_queue),
 'failed': self.redis.llen(self.failed_queue),
 }

Worker 节点管理

import asyncio
from playwright.async_api import async_playwright

class WorkerNode:
 """Worker 节点"""

 def __init__(self, node_id: str, scheduler: TaskScheduler):
 self.node_id = node_id
 self.scheduler = scheduler
 self.is_running = False
 self.browser = None
 self.proxy_pool = ProxyPool()

 async def start(self):
 """启动 Worker"""
 self.is_running = True

 async with async_playwright() as p:
 self.browser = await p.chromium.launch(headless=False)

 while self.is_running:
 # 获取任务
 task = self.scheduler.get_task()

 if task:
 try:
 # 执行任务
 result = await self._execute_task(task)
 self.scheduler.complete_task(task, result)

 except Exception as e:
 self.scheduler.fail_task(task, str(e))

 else:
 # 等待新任务
 await asyncio.sleep(1)

 async def _execute_task(self, task: CrawlTask) -> dict:
 """执行单个任务"""
 # 获取代理
 proxy = self.proxy_pool.get_proxy()

 # 创建上下文
 context = await self.browser.new_context(
 proxy={'server': proxy}
 )

 page = await context.new_page()

 # 应用策略
 strategy = self._get_strategy(task.strategy)
 result = await strategy.execute(page, task.url)

 await context.close()

 return result

 def _get_strategy(self, strategy_name: str):
 """获取策略实例"""
 from strategies import (
 PlaywrightStealthStrategy,
 StrictStealthStrategy,
 MinimalStrategy
 )

 strategies = {
 'default': PlaywrightStealthStrategy,
 'strict': StrictStealthStrategy,
 'minimal': MinimalStrategy,
 }

 return strategies.get(strategy_name, PlaywrightStealthStrategy)()

 async def stop(self):
 """停止 Worker"""
 self.is_running = False

 if self.browser:
 await self.browser.close()

7.8 分布式状态管理

Redis 状态存储

class DistributedStateManager:
 """分布式状态管理器"""

 def __init__(self, redis_url='redis://localhost:6379'):
 self.redis = redis.from_url(redis_url)
 self.key_prefix = 'crawler:state'

 def save_browser_state(self, session_id: str, state: dict):
 """保存浏览器状态"""
 key = f'{self.key_prefix}:session:{session_id}'

 # 保存到 Redis Hash
 self.redis.hset(key, mapping={
 'cookies': json.dumps(state.get('cookies', [])),
 'storage': json.dumps(state.get('storage', {})),
 'timestamp': time.time(),
 })

 # 设置过期时间
 self.redis.expire(key, 86400) # 24小时

 def load_browser_state(self, session_id: str) -> Optional[dict]:
 """加载浏览器状态"""
 key = f'{self.key_prefix}:session:{session_id}'

 data = self.redis.hgetall(key)

 if data:
 return {
 'cookies': json.loads(data.get(b'cookies', b'[]')),
 'storage': json.loads(data.get(b'storage', b'{}')),
 'timestamp': float(data.get(b'timestamp', b'0')),
 }

 return None

 def save_proxy_state(self, proxy_pool: dict):
 """保存代理池状态"""
 key = f'{self.key_prefix}:proxies'

 self.redis.set(key, json.dumps(proxy_pool))

 def load_proxy_state(self) -> dict:
 """加载代理池状态"""
 key = f'{self.key_prefix}:proxies'

 data = self.redis.get(key)

 if data:
 return json.loads(data)

 return {}

7.9 监控与告警

实时监控系统

from prometheus_client import Counter, Histogram, Gauge

class MetricsCollector:
 """指标收集器"""

 def __init__(self):
 # 请求计数
 self.request_counter = Counter(
 'crawler_requests_total',
 'Total requests',
 ['domain', 'status']
 )

 # 响应时间
 self.response_time = Histogram(
 'crawler_response_time_seconds',
 'Response time',
 ['domain']
 )

 # 队列长度
 self.queue_size = Gauge(
 'crawler_queue_size',
 'Queue size',
 ['queue_type']
 )

 # 检测率
 self.detection_counter = Counter(
 'crawler_detections_total',
 'Detection events',
 ['domain', 'type']
 )

 def record_request(self, domain: str, status: str):
 """记录请求"""
 self.request_counter.labels(domain=domain, status=status).inc()

 def record_response_time(self, domain: str, duration: float):
 """记录响应时间"""
 self.response_time.labels(domain=domain).observe(duration)

 def record_detection(self, domain: str, detection_type: str):
 """记录检测事件"""
 self.detection_counter.labels(domain=domain, type=detection_type).inc()

 def update_queue_size(self, queue_type: str, size: int):
 """更新队列大小"""
 self.queue_size.labels(queue_type=queue_type).set(size)

告警系统

class AlertManager:
 """告警管理器"""

 def __init__(self, metrics: MetricsCollector):
 self.metrics = metrics
 self.thresholds = {
 'detection_rate': 0.1, # 10% 检测率告警
 'queue_size': 1000, # 队列积压告警
 'response_time': 30, # 响应时间告警
 }
 self.alert_history = []

 def check_alerts(self, stats: dict) -> list:
 """检查告警条件"""
 alerts = []

 # 检测率告警
 detection_rate = stats.get('detection_rate', 0)
 if detection_rate > self.thresholds['detection_rate']:
 alerts.append({
 'type': 'detection_rate',
 'severity': 'high',
 'value': detection_rate,
 'message': f'检测率过高: {detection_rate:.1%}'
 })

 # 队列积压告警
 queue_size = stats.get('queue_size', 0)
 if queue_size > self.thresholds['queue_size']:
 alerts.append({
 'type': 'queue_size',
 'severity': 'medium',
 'value': queue_size,
 'message': f'队列积压: {queue_size}'
 })

 # 响应时间告警
 avg_response_time = stats.get('avg_response_time', 0)
 if avg_response_time > self.thresholds['response_time']:
 alerts.append({
 'type': 'response_time',
 'severity': 'medium',
 'value': avg_response_time,
 'message': f'响应时间过长: {avg_response_time:.1f}s'
 })

 # 去重后返回
 return self._deduplicate_alerts(alerts)

 def _deduplicate_alerts(self, alerts: list) -> list:
 """告警去重"""
 unique_alerts = []

 for alert in alerts:
 # 检查是否最近已告警过
 is_duplicate = any(
 a['type'] == alert['type'] and
 time.time() - a['timestamp'] < 3600 # 1小时内
 for a in self.alert_history
 )

 if not is_duplicate:
 alert['timestamp'] = time.time()
 unique_alerts.append(alert)
 self.alert_history.append(alert)

 return unique_alerts

7.10 故障恢复机制

自动故障处理

class FailureRecoveryManager:
 """故障恢复管理器"""

 def __init__(self):
 self.recovery_strategies = {
 'ip_blocked': self._recover_from_ip_block,
 'rate_limit': self._recover_from_rate_limit,
 'captcha_failed': self._recover_from_captcha,
 'timeout': self._recover_from_timeout,
 }

 async def handle_failure(self, task: CrawlTask, error: dict) -> bool:
 """处理失败"""
 failure_type = error.get('type', 'unknown')

 recovery_strategy = self.recovery_strategies.get(failure_type)

 if recovery_strategy:
 return await recovery_strategy(task, error)

 return False

 async def _recover_from_ip_block(self, task: CrawlTask, error: dict) -> bool:
 """从 IP 封锁中恢复"""
 # 1. 标记代理为失效
 proxy_manager.mark_failed(task.proxy)

 # 2. 切换到新代理
 new_proxy = proxy_manager.get_proxy()

 # 3. 降低请求频率
 rate_limiter.reduce_rate(0.5)

 # 4. 重试任务
 task.proxy = new_proxy
 task.retries += 1

 return True

 async def _recover_from_rate_limit(self, task: CrawlTask, error: dict) -> bool:
 """从速率限制中恢复"""
 # 1. 计算等待时间
 retry_after = error.get('retry_after', 60)

 # 2. 等待
 await asyncio.sleep(retry_after)

 # 3. 降低速率
 rate_limiter.reduce_rate(0.7)

 # 4. 重试
 task.retries += 1

 return True

 async def _recover_from_captcha(self, task: CrawlTask, error: dict) -> bool:
 """从验证码失败中恢复"""
 # 1. 切换验证码解决方式
 if task.captcha_solver == 'local':
 task.captcha_solver = 'service'
 else:
 # 2. 更换会话
 task.session_id = session_manager.create_session()

 # 3. 重试
 task.retries += 1

 return True

 async def _recover_from_timeout(self, task: CrawlTask, error: dict) -> bool:
 """从超时中恢复"""
 # 1. 增加超时时间
 task.timeout = min(task.timeout * 1.5, 300)

 # 2. 降低并发
 concurrency_limiter.reduce_concurrency()

 # 3. 重试
 task.retries += 1

 return True

7.11 性能优化

并发控制优化

class OptimizedConcurrencyManager:
 """优化的并发管理器"""

 def __init__(self, initial_concurrency=10):
 self.current_concurrency = initial_concurrency
 self.min_concurrency = 1
 self.max_concurrency = 50
 self.success_history = []
 self.window_size = 100

 def adjust_concurrency(self, success: bool):
 """根据成功率调整并发"""
 self.success_history.append(success)

 if len(self.success_history) > self.window_size:
 self.success_history.pop(0)

 # 计算成功率
 success_rate = sum(self.success_history) / len(self.success_history)

 # 调整策略
 if success_rate > 0.95 and self.current_concurrency < self.max_concurrency:
 # 成功率高，增加并发
 self.current_concurrency += 2
 elif success_rate < 0.7 and self.current_concurrency > self.min_concurrency:
 # 成功率低，减少并发
 self.current_concurrency = max(
 self.min_concurrency,
 int(self.current_concurrency * 0.8)
 )

 return self.current_concurrency

 def get_concurrency(self) -> int:
 """获取当前并发数"""
 return self.current_concurrency

资源池管理

class BrowserPool:
 """浏览器实例池"""

 def __init__(self, max_size=10):
 self.max_size = max_size
 self.pool = asyncio.Queue(maxsize=max_size)
 self.created_count = 0

 async def acquire(self) -> Browser:
 """获取浏览器实例"""
 try:
 # 尝试从池中获取
 browser = await asyncio.wait_for(
 self.pool.get(),
 timeout=1.0
 )
 return browser

 except asyncio.TimeoutError:
 # 池为空，创建新实例
 if self.created_count < self.max_size:
 self.created_count += 1
 return await self._create_browser()

 raise Exception('Browser pool exhausted')

 async def release(self, browser: Browser):
 """归还浏览器实例"""
 try:
 await self.pool.put(browser)
 except asyncio.QueueFull:
 # 池已满，关闭浏览器
 await browser.close()
 self.created_count -= 1

 async def _create_browser(self) -> Browser:
 """创建新浏览器"""
 playwright = await async_playwright().start()
 return await playwright.chromium.launch(headless=False)

八、学习路径与实战建议

8.1 入门阶段（1-2 周）

目标

理解反爬虫基本原理
掌握基础 HTTP 指纹伪装
能够应对简单检测

学习清单

HTTP 基础
- 理解 HTTP 头部组成
- 掌握 User-Agent 伪造
- 完整请求头模拟
基础浏览器自动化
- 安装配置 Playwright/Puppeteer
- 基本的页面导航与交互
- 元素定位与数据提取
简单指纹处理
- 移除 navigator.webdriver
- 伪造 navigator.plugins
- 设置真实的 User-Agent

实战项目

目标：爬取一个中等复杂度的电商网站

# 入门项目示例
from playwright.sync_api import sync_playwright

def scrape_ecommerce(url):
 with sync_playwright() as p:
 browser = p.chromium.launch(headless=False)
 page = browser.new_page()

 # 基础伪装
 page.set_extra_http_headers({
 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...'
 })

 page.goto(url)
 time.sleep(2)

 # 提取数据
 products = page.query_selector_all('.product-item')
 for product in products:
 title = product.query_selector('.title').text_content()
 price = product.query_selector('.price').text_content()
 print(f"{title}: {price}")

 browser.close()

8.2 进阶阶段（1-2 个月）

目标

掌握完整指纹伪装
模拟人类行为
应对中等难度检测

学习清单

完整指纹伪装
- Navigator 对象完整伪造
- Canvas/WebGL 指纹处理
- 屏幕分辨率与设备信息
人类行为模拟
- 贝塞尔曲线鼠标移动
- 自然打字节奏
- 滚动与停留模拟
网络环境管理
- 代理池搭建
- 代理轮换策略
- 失败重试机制
状态管理
- Cookie 持久化
- 浏览器 Profile 管理
- LocalStorage 保存恢复

实战项目

目标：爬取一个有基本反爬虫的社交媒体

# 进阶项目示例
class AdvancedScraper:
 def __init__(self):
 self.proxy_pool = ProxyPool.load_proxies()
 self.cookie_manager = CookieManager('./cookies')
 self.mouse_sim = MouseSimulator()

 def scrape_target(self, target_url, account_id):
 # 1. 获取代理和 Cookie
 proxy = self.proxy_pool.get_proxy()
 cookies = self.cookie_manager.get_cookies(target_url, account_id)

 # 2. 启动浏览器
 browser = self.launch_with_proxy(proxy, cookies)

 # 3. 模拟人类导航
 self.human_navigate(browser, target_url)

 # 4. 提取数据
 data = self.extract_data(browser)

 # 5. 保存状态
 self.cookie_manager.save_cookies(target_url, cookies, account_id)

 return data

8.3 高级阶段（3-6 个月）

目标

处理验证码
构建分布式架构
应对高难度检测

学习清单

验证码处理
- OCR 图像识别
- 滑动验证码破解
- 行为验证对抗
分布式架构
- 任务调度设计
- 多节点协同
- 资源池管理
高级反检测
- reCAPTCHA v3 对抗
- 浏览器指纹完全一致
- WAF 绕过

实战项目

目标：构建企业级分布式爬虫系统

8.4 精通阶段（持续）

目标

深入理解检测机制
开发反检测工具
持续跟进对抗技术

学习方向

浏览器内核研究
- Chromium 源码分析
- 检测机制深度理解
- 内核级绕过方案
AI 辅助
- 行为模式学习
- 检测预测模型
- 自动化对抗
工具开发
- 反检测框架开发
- A/B 测试平台
- 监控与分析工具

九、实用工具与库推荐

9.1 Python 生态

库名	用途	推荐指数
playwright	浏览器自动化	⭐⭐⭐⭐⭐
selenium	浏览器自动化	⭐⭐⭐⭐
undetected-chromedriver	绕过检测的 Chrome	⭐⭐⭐⭐⭐
fake-useragent	User-Agent 生成	⭐⭐⭐⭐
pytesseract	OCR 识别	⭐⭐⭐
opencv-python	图像处理	⭐⭐⭐⭐⭐
requests	HTTP 请求	⭐⭐⭐⭐⭐
httpx	异步 HTTP	⭐⭐⭐⭐
playwright-stealth	Playwright 隐身插件	⭐⭐⭐⭐⭐
go-rod/stealth	Go 语言反检测	⭐⭐⭐⭐

9.2 Node.js 生态

库名	用途	推荐指数
puppeteer	浏览器自动化	⭐⭐⭐⭐⭐
puppeteer-extra	Puppeteer 扩展	⭐⭐⭐⭐⭐
puppeteer-extra-plugin-stealth	隐身插件	⭐⭐⭐⭐⭐
playwright	浏览器自动化	⭐⭐⭐⭐⭐
2captcha	验证码服务	⭐⭐⭐⭐
tesseract.js	OCR 识别	⭐⭐⭐

9.3 Go 生态

库名	用途	推荐指数
rod	浏览器自动化	⭐⭐⭐⭐⭐
go-rod/stealth	反检测库	⭐⭐⭐⭐⭐
colly	爬虫框架	⭐⭐⭐⭐
chromedp	Chrome DevTools 协议	⭐⭐⭐⭐

9.4 在线服务

服务	用途	成本
2captcha	验证码识别	$2.99/1000 次
Anti-Captcha	验证码识别	$3/1000 次
Capy	验证码识别	按需计费
Bright Data	住宅代理	$500+/月起
Oxylabs	代理服务	$300+/月起

十、常见问题与解决方案

10.1 检测特征对照

症状	可能原因	解决方案
立即返回 403	IP 被封	更换代理
验证码频繁出现	行为可疑	改善行为模拟
登录态失效	Cookie 过期	实现 Cookie 刷新
数据获取不全	JS 动态渲染	等待元素加载
触发风控	指纹异常	完善指纹伪装

10.2 调试技巧

开启详细日志

# Playwright 调试模式
context = browser.new_context(
 proxy={'server': proxy},
 locale='zh-CN',
 viewport={'width': 1920, 'height': 1080},
)

page = context.new_page()
page.on('console', lambda msg: print(f"Console: {msg.text}"))
page.on('request', lambda req: print(f"Request: {req.url}"))

抓包分析

# 使用 mitmproxy 分析请求
mitmproxy --listen-port 8080

# 浏览器设置代理
proxy = {'server': 'http://127.0.0.1:8080'}

10.3 性能分析

瓶颈识别

import cProfile
import pstats
from io import StringIO

class PerformanceProfiler:
 """性能分析器"""

 def profile_function(self, func, *args, **kwargs):
 """分析函数性能"""
 profiler = cProfile.Profile()

 profiler.enable()
 result = func(*args, **kwargs)
 profiler.disable()

 # 输出统计
 s = StringIO()
 stats = pstats.Stats(profiler, stream=s)
 stats.strip_dirs()
 stats.sort_stats('cumulative')
 stats.print_stats(20) # 打印前 20 个函数

 print(s.getvalue())

 return result

# 使用示例
profiler = PerformanceProfiler()
profiler.profile_function(scrape_url, url)

内存泄漏检测

import tracemalloc

class MemoryLeakDetector:
 """内存泄漏检测器"""

 def __init__(self):
 self.snapshots = []

 def start_tracking(self):
 """开始跟踪内存"""
 tracemalloc.start()
 self.snapshots.append(tracemalloc.take_snapshot())

 def take_snapshot(self, label=''):
 """获取内存快照"""
 snapshot = tracemalloc.take_snapshot()
 self.snapshots.append((label, snapshot))

 return snapshot

 def compare_snapshots(self, index1=-2, index2=-1):
 """比较两个快照"""
 label1, snapshot1 = self.snapshots[index1]
 label2, snapshot2 = self.snapshots[index2]

 stats = snapshot2.compare_to(snapshot1, 'lineno')

 print(f"内存变化 ({label1} -> {label2}):")
 for stat in stats[:10]:
 print(stat)

 def stop_tracking(self):
 """停止跟踪"""
 tracemalloc.stop()

10.4 常见错误处理

异常分类与处理

class CrawlerErrorHandler:
 """爬虫错误处理器"""

 def __init__(self):
 self.error_handlers = {
 'TimeoutError': self._handle_timeout,
 'ConnectionError': self._handle_connection,
 'HTTPError': self._handle_http_error,
 'DetectedError': self._handle_detection,
 'CaptchaError': self._handle_captcha,
 }

 def handle_error(self, error, context=None):
 """处理错误"""
 error_type = type(error).__name__
 error_name = error_type.split("'")[0] if "'" in error_type else error_type

 handler = self.error_handlers.get(error_name)

 if handler:
 return handler(error, context)

 # 默认处理
 return self._handle_unknown(error, context)

 def _handle_timeout(self, error, context):
 """处理超时"""
 print(f"超时错误: {error}")
 return {
 'action': 'retry',
 'delay': 10,
 'message': '请求超时，将重试'
 }

 def _handle_connection(self, error, context):
 """处理连接错误"""
 print(f"连接错误: {error}")
 return {
 'action': 'switch_proxy',
 'message': '连接失败，切换代理'
 }

 def _handle_http_error(self, error, context):
 """处理 HTTP 错误"""
 status_code = getattr(error.response, 'status_code', None)

 if status_code == 403:
 return {
 'action': 'rotate_strategy',
 'message': '被拒绝访问，切换策略'
 }
 elif status_code == 429:
 return {
 'action': 'backoff',
 'delay': 60,
 'message': '速率限制，等待后重试'
 }

 return {
 'action': 'retry',
 'message': f'HTTP {status_code} 错误'
 }

 def _handle_detection(self, error, context):
 """处理被检测"""
 print(f"检测到反爬虫: {error}")
 return {
 'action': 'escalate',
 'message': '被检测到，升级策略'
 }

 def _handle_captcha(self, error, context):
 """处理验证码"""
 return {
 'action': 'solve_captcha',
 'message': '触发验证码'
 }

 def _handle_unknown(self, error, context):
 """处理未知错误"""
 print(f"未知错误: {error}")
 return {
 'action': 'skip',
 'message': '未知错误，跳过'
 }

10.5 调试工具链

Chrome DevTools 集成

import asyncio
from playwright.async_api import async_playwright

class DebuggerIntegration:
 """调试器集成"""

 async def attach_devtools(self, browser):
 """附加 DevTools"""
 # 获取 WebSocket URL
 cdp_url = await browser.context.cdp_session()

 # 可以通过以下方式连接：
 # 1. Chrome 远程调试端口
 # 2. puppeteer-cluster 的调试模式
 # 3. playwright 的 debug 模式

 print(f"CDP URL: {cdp_url}")

 async def enable_tracing(self, page, trace_path):
 """启用跟踪"""
 await page.context.tracing.start(
 name="trace",
 screenshots=True,
 snapshots=True
 )

 # ... 执行操作 ...

 await page.context.tracing.stop(path=trace_path)

十一、法律与伦理

11.1 重要提示

反爬虫技术仅供学习和研究使用。 在实际应用前，请确保：

遵守 robots.txt：尊重网站的爬虫协议
获得授权：对目标网站爬取前获得明确授权
控制频率：避免对目标服务器造成压力
数据合规：遵守数据保护和隐私法规
商业考量：理解商业条款，避免法律风险

11.2 灰色地带

以下场景可能涉及法律风险：

爬取未授权的商业数据
绕过付费墙获取内容
爬取用户隐私数据
影响网站正常运营

十二、总结

反反爬虫是一个复杂而持续发展的领域。本文构建的技能树涵盖了从基础到精通的完整技术体系：

基础层：理解 HTTP、浏览器工作原理、指纹技术
环境层：浏览器指纹伪装、网络环境隔离、设备信息伪造
行为层：鼠标/键盘行为模拟、人类行为模式
持久层：Cookie/Session 管理、状态同步
验证层：验证码识别、人机验证对抗
架构层：分布式架构、反检测策略库

核心原则：

指纹伪装要完整
行为模拟要自然
状态管理要持久
策略调整要灵活
伦理法律要遵守

随着检测技术的进步，反检测策略也需要持续更新。建议定期关注社区动态，分享经验，共同成长。

完整技术体系回顾

反反爬虫技术体系
│
├── 基础层（必备）
│ ├── HTTP 请求完整伪装
│ ├── HTTP/2 协议指纹处理
│ ├── WebSocket 连接模拟
│ ├── 请求头完整性维护
│ ├── Referer 链管理
│ ├── Cookie 属性控制
│ └── 断点续传支持
│
├── 环境层（核心）
│ ├── Navigator 对象完整伪造
│ ├── CDP 检测绕过
│ ├── Canvas/WebGL 指纹伪装
│ ├── TLS 指纹伪装
│ ├── WebRTC 防护
│ ├── CDN 绕过
│ ├── 代理池管理
│ ├── 字体指纹伪造
│ ├── Web Audio 指纹处理
│ ├── Battery/Network/Screen API 伪造
│ ├── Geolocation 伪装
│ ├── WebGL 参数随机化
│ ├── Chrome DevTools 指纹隐藏
│ ├── iframe 内容伪装
│ ├── 媒体编解码器伪造
│ ├── Touch API 支持
│ └── 硬件指纹随机化
│
├── 行为层（高级）
│ ├── 鼠标贝塞尔曲线轨迹
│ ├── 键盘打字节奏模拟
│ ├── 滚动行为模式
│ ├── 视线停留时间
│ ├── 窗口大小变化
│ ├── 页面停留时间
│ ├── 点击位置偏移
│ ├── 多标签页操作
│ ├── 浏览器历史导航
│ ├── 右键操作
│ ├── 拖放操作
│ ├── 音频/视频交互
│ ├── 表单提交节奏
│ ├── 鼠标抖动
│ ├── 键盘修正
│ ├── 触摸事件
│ ├── Hover 停留
│ ├── 视觉扫视
│ ├── 随机停顿
│ ├── 链接决策
│ ├── 滚动模式
│ └── 用户偏好模拟
│
├── 持久层（稳定）
│ ├── Cookie 池管理
│ ├── 多账号并发管理
│ ├── 浏览器 Profile
│ ├── LocalStorage 管理
│ ├── SessionStorage 管理
│ ├── IndexedDB 管理
│ ├── 状态快照
│ ├── Cache API 管理
│ ├── Service Worker 管理
│ └── Cookie 自动刷新
│
├── 验证层（攻坚）
│ ├── OCR 验证码识别
│ ├── 滑动验证码破解
│ ├── 点击验证码破解
│ ├── 行为验证模拟
│ ├── reCAPTCHA 对抗
│ ├── hCaptcha 对抗
│ ├── 验证码服务集成
│ ├── 自动识别框架
│ └── 验证码缓存策略
│
└── 架构层（精通）
├── 分布式任务调度
├── Worker 节点管理
├── 分布式状态管理
├── 监控告警系统
├── 故障恢复机制
├── 性能优化
├── 策略路由
├── A/B 测试
├── 速率限制
├── AI 智能决策
├── 自适应导航
├── 动态选择器
├── 特征工程
├── 模式识别
├── 风险预测
└── 网站智能分类

技能掌握建议

阶段	掌握目标	重点技能	时间投入
入门	能应对简单检测	HTTP 伪装、基础指纹	1-2 周
进阶	能应对中等检测	完整指纹、行为模拟	1-2 个月
高级	能应对复杂检测	验证码、分布式架构	3-6 个月
精通	能应对高难度检测	内核级对抗、AI 辅助	持续学习

常见陷阱

过度依赖单一策略：网站会更新检测机制，需要多种策略组合
忽视行为模拟：再完美的指纹，行为异常也会被检测
忽略性能优化：资源浪费会降低系统可扩展性
不遵守法律边界：技术再强，法律风险也不能忽视
缺乏监控反馈：没有数据支撑的优化是盲目的

参考资源

官方文档

反检测工具

go-rod/stealth - Go 反检测库
puppeteer-extra-plugin-stealth - Puppeteer 隐身插件
playwright-stealth - Playwright 隐身插件
undetected-chromedriver - Python 反检测 Chrome

检测工具

browserleaks - 浏览器指纹检测网站
abuseipdb - IP 信誉检查
whoer.net - 综合指纹检测

学习资源

【留档】Puppeteer Stealth 插件 JS 代码分析

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 17:35:00 +0800

背景

在分析 puppeteer-extra-plugin-stealth 项目时，发现其核心代码被打包成一段高度压缩的 JavaScript。本文是对该代码的详细解析。

版本：v2.7.3

代码结构概览

这段压缩 JS 采用立即执行函数 (IIFE) 结构：

(({_utilsFns, _mainFunction, _args}) => {
 const utils = Object.fromEntries(
 Object.entries(_utilsFns).map(([key, value]) => [key, eval(value)])
 );
 utils.init();
 eval(_mainFunction)(utils, ..._args);
})(...)

执行流程：

动态加载 _utilsFns 中的工具函数（通过 eval 执行字符串形式的代码）
调用 utils.init() 初始化
执行 _mainFunction 主函数，传入工具函数和参数

核心工具函数

1. stripProxyFromErrors

作用： 从错误堆栈中移除 Proxy 相关的调用栈，防止被检测。

const stripProxyFromErrors = (handler = {}) => {
 const newHandler = { ...handler };

 // 拦截每个 trap
 traps.forEach(trap => {
 newHandler[trap] = function () {
 try {
 return handler[trap].apply(this, arguments);
 } catch (err) {
 // 清理错误堆栈中的 Proxy 痕迹
 err.stack = stripWithAnchor(err.stack) || stripWithBlacklist(err.stack);
 throw err;
 }
 };
 });

 return newHandler;
};

检测对抗原理：

当 Proxy 内部抛出错误时，堆栈会显示类似：

TypeError: xxx
at Reflect.get (native)
at Object.newHandler.<computed> [as get] (...)
at realUserCode (...)

这段代码会自动移除前两行，只保留用户代码的堆栈。

2. patchToString

作用： 修改 Function.prototype.toString，让代理函数返回 [native code] 形式。

const patchToString = (obj, str = '') => {
 const handler = {
 apply: function (target, ctx) {
 if (ctx === obj) {
 return str || utils.makeNativeString(obj.name);
 }
 return target.call(ctx);
 }
 };

 const toStringProxy = new Proxy(
 Function.prototype.toString,
 utils.stripProxyFromErrors(handler)
 );

 utils.replaceProperty(Function.prototype, 'toString', {
 value: toStringProxy
 });
};

效果：

// 正常情况，Proxy 函数会被暴露：
someProxyFunction.toString()
// => "function () { [native code] }" <-- 这是假的

// 但如果被检测：
someProxyFunction.toString() === Function.prototype.toString.call(someProxyFunction)
// => true，看起来像原生函数

3. makeNativeString

作用： 生成原生函数字符串。

const makeNativeString = (name = '') => {
 // 基于缓存的 native toString 模板
 return utils.cache.nativeToStringStr.replace('toString', name || '');
};

// 结果示例：
// "function getAttribute() { [native code] }"

4. replaceProperty

作用： 安全地重写对象属性描述符。

const replaceProperty = (obj, propName, descriptorOverrides = {}) => {
 return Object.defineProperty(obj, propName, {
 // 保留原有描述符
 ...(Object.getOwnPropertyDescriptor(obj, propName) || {}),
 // 应用覆盖
 ...descriptorOverrides
 });
};

5. replaceWithProxy / mockWithProxy

作用： 创建代理并替换原对象。

const replaceWithProxy = (obj, propName, handler) => {
 const original = obj[propName];
 const proxy = new Proxy(original, utils.stripProxyFromErrors(handler));
 utils.replaceProperty(obj, propName, { value: proxy });
 return proxy;
};

被修改的浏览器 API

代码针对以下检测点进行伪装：

检测点	原始问题	修复方式
`navigator.webdriver`	Puppeteer 会将其设为 `true`	重写为 `undefined`
`chrome.runtime`	无 Chrome 扩展 API	注入假的 `chrome` 对象
`navigator.plugins`	插件列表为空	伪造常见插件数组
`navigator.languages`	语言设置异常	确保返回合理数组
`navigator.hardwareConcurrency`	CPU 核心数可疑	可配置伪装值
`navigator.permissions`	权限 API 行为异常	修复 `query()` 返回值
`iframe.contentWindow`	跨窗口检测不一致	统一代理处理
`window.outerWidth/outerHeight`	无头浏览器特征	修复窗口尺寸

工作原理总结

┌─────────────────────────────────────────────────────────────┐
│ 网站检测 Bot 的方式 │
├─────────────────────────────────────────────────────────────┤
│ 1. navigator.webdriver === true │
│ 2. Function.toString 返回非原生代码 │
│ 3. 错误堆栈中出现 Proxy 相关调用 │
│ 4. 浏览器特征缺失 (plugins, chrome 等) │
│ 5. Canvas/WebGL 指纹异常 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Stealth 插件的对策 │
├─────────────────────────────────────────────────────────────┤
│ 1. 重写属性，返回期望值 │
│ 2. 代理 Function.prototype.toString │
│ 3. 清理错误堆栈中的 Proxy 痕迹 │
│ 4. 注入伪造的浏览器特征 │
│ 5. 统一各窗口的 API 行为 │
└─────────────────────────────────────────────────────────────┘

检测对抗示例

示例 1：webdriver 属性

// 网站检测代码
if (navigator.webdriver) {
 console.log('检测到自动化脚本！');
}

// Stealth 修复后
Object.defineProperty(navigator, 'webdriver', {
 get: () => undefined
});

// 现在 navigator.webdriver === undefined

示例 2：toString 检测

// 网站检测代码
const fn = navigator.getAttribute;
if (fn.toString().includes('[native code]')) {
 // 正常
} else {
 console.log('函数被篡改！');
}

// Stealth 修复后
// 即使 getAttribute 被 Proxy 包装，toString 仍返回：
// "function getAttribute() { [native code] }"

项目结构

这段压缩代码来自 puppeteer-extra-plugin-stealth，其源码结构：

puppeteer-extra-plugin-stealth/
├── src/
│ └── index.js # 入口，打包生成压缩代码
└── evasion/ # 各检测规避模块
├── chrome.app/
├── chrome.csi/
├── chrome.loadTimes/
├── chrome.runtime/
├── iframe.contentWindow/
├── media.codecs/
├── navigator.hardwareConcurrency/
├── navigator.languages/
├── navigator.permissions/
├── navigator.plugins/
├── navigator.webdriver/
├── user-agent-override/
├── utils.js # 工具函数（本文分析的核心）
└── ...

总结

这段压缩 JS 是 puppeteer-extra-plugin-stealth 的核心代码，通过以下技术手段隐藏浏览器自动化痕迹：

Proxy 包装：拦截浏览器原生 API 调用
堆栈清洗：自动移除错误堆栈中的 Proxy 痕迹
toString 伪装：让代理函数看起来像原生代码
属性注入：伪造缺失的浏览器特征

这些技术使得 Puppeteer/Playwright 脚本在网站眼中看起来像真实用户操作，常用于爬虫、自动化测试、数据采集等场景。

参考

Claude Plugin 进阶：Marketplace 与项目规则实践

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 15:00:00 +0800

背景

在上文从零构建 Claude Skill中，我们完成了 hugo skill 的基础功能。本文记录二阶段开发：接入 Marketplace 和建立项目规则，以及过程中遇到的问题。

Marketplace 接入

marketplace.json 结构

{
 "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
 "name": "taevas-plugins",
 "version": "0.1.0",
 "description": "Taevas Plugins Marketplace",
 "owner": {
 "name": "743v45",
 "email": "noreply@743v45.com"
 },
 "plugins": [
 {
 "name": "hugo",
 "source": "./plugins/hugo",
 "category": "content",
 "description": "Publish content to Hugo blog..."
 }
 ]
}

关键字段说明：

字段	作用
`$schema`	JSON Schema 验证
`plugins[].source`	相对于 marketplace.json 的插件路径
`plugins[].category`	分类：content/notifications/development 等

插件目录结构规范

从 Skill 升级为 Plugin，需要遵循更严格的目录结构：

plugins/hugo/
├── .claude-plugin/
│ └── plugin.json # 插件元数据
├── skills/
│ └── hugo/ # 以 skill 名称命名的目录
│ ├── SKILL.md # 核心指令
│ ├── references/ # 参考文档
│ └── scripts/ # 脚本工具
└── README.md

遇到的问题

问题一：Skill 目录结构重构

现象： 最初 skills 目录结构混乱，无法正确加载。

原因： Skills 应该放在以 skill 名称命名的子目录中，而不是直接放在 skills/ 下。

解决： 重构目录结构

# 错误 ❌
skills/
├── hugo.md
├── references/
└── scripts/
# 正确 ✓
skills/
└── hugo/
├── SKILL.md
├── references/
└── scripts/

对应的 git commits:

f9be4f6 refactor(hugo): 重构插件目录结构
a6b6426 refactor(hugo): 重构 skill 目录结构

问题二：plugin.json 描述过于简单

现象： 插件加载后功能描述不清晰，用户不知道如何使用。

解决： 扩展 description 字段，详细说明所有使用模式：

{
 "description": "Publish content to Hugo blog. Supports: (1) /hugo alone - check installation, (2) /hugo with content - create/update post, (3) /hugo new <content> - force create, (4) /hugo update <content> - force update, (5) /hugo ... -c - preview with hugo server"
}

问题三：文章更新模式缺失

现象： 只能创建新文章，无法更新已有文章。

解决： 添加三种操作模式

模式	命令	行为
CREATE	`/hugo new <content>`	强制创建，存在则报错
UPDATE	`/hugo update <content>`	强制更新，不存在则报错
AUTO	`/hugo <content>`	搜索匹配文章，让用户选择

实现搜索功能需要扩展 detect_hugo_site.py：

def search_posts(directory: str, keywords: str) -> list:
 """Search posts by title or filename, return sorted by match score."""
 # 计算匹配分数
 # 标题匹配 +20，文件名匹配 +10
 # 分词匹配每个词 +5/+3

项目规则建立

Commit 规范

采用 Conventional Commits：

<type>(<scope>): <description>
类型：feat/fix/refactor/docs/style/test/chore
范围：hugo/sound-hooks 等

目录结构规则

.claude-plugin/
├── marketplace.json # 市场配置（项目根）
└── plugins/
└── <plugin-name>/
├── .claude-plugin/
│ └── plugin.json # 插件元数据
├── skills/
│ └── <skill-name>/
│ ├── SKILL.md
│ ├── references/
│ └── scripts/
└── README.md

文件命名规则

SKILL.md 大写，作为 skill 入口
脚本使用 snake_case: detect_hugo_site.py
参考文档使用 kebab-case: front-matter.md

总结

二阶段开发的核心工作：

接入 Marketplace - 建立 marketplace.json 和目录规范
重构目录结构 - skills 放入以名称命名的子目录
完善功能 - 添加文章搜索和更新模式
建立规则 - commit 规范、目录结构、命名约定

参考资料

Claude Skill 调用触发流程详解

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 12:00:00 +0800

概述

Claude Code 的 Skill 系统通过智能匹配机制，在用户请求时自动加载相关能力。本文深入分析 Skill 的调用触发流程。

三层加载架构

┌─────────────────────────────────────────────────────────┐
│ Claude 上下文 │
├─────────────────────────────────────────────────────────┤
│ Layer 1: Metadata (始终加载) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ hugo: "Publish content to Hugo blog..." │ │
│ │ skill-creator: "Guide for creating skills..." │ │
│ │ pdf: "PDF processing..." │ │
│ │ ... (所有 skill 的 name + description) │ │
│ └─────────────────────────────────────────────────┘ │
│ ↓ │
│ Layer 2: SKILL.md Body (触发后加载) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ # Hugo Blog Publisher │ │
│ │ ## Workflow │ │
│ │ 1. Check Hugo installation │ │
│ │ 2. Determine Hugo site path... │ │
│ └─────────────────────────────────────────────────┘ │
│ ↓ │
│ Layer 3: Bundled Resources (按需加载) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ scripts/detect_hugo_site.py │ │
│ │ references/front-matter.md │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

触发流程详解

阶段一：用户输入解析

用户输入: /hugo 写一篇关于 Go 并发的文章
↓
命令解析: skill = "hugo"
args = "写一篇关于 Go 并发的文章"

阶段二：Metadata 匹配

Claude 在所有已安装 skill 的 description 中搜索匹配项：

# hugo skill 的 description
description: "Publish content to Hugo blog. Use when user invokes /hugo command..."

# 匹配逻辑
/hugo → 匹配 "invokes /hugo command" → 触发 hugo skill

匹配规则：

显式命令 /skill-name 优先匹配
隐式触发通过 description 语义匹配
多个匹配时选择描述最相关的

阶段三：Skill Body 加载

触发后，Claude 加载 SKILL.md 的完整内容：

# Hugo Blog Publisher

## Workflow

1. **Check Hugo installation**
 ```bash
 hugo version

Determine Hugo site path
- Run scripts/detect_hugo_site.py
- Always confirm with user …


### 阶段四：执行工作流

┌──────────────────────────────────────────────────┐ │ 1. 检查 hugo version │ │ ↓ │ │ 2. 运行 detect_hugo_site.py │ │ ↓ │ │ 3. 确认站点路径 │ │ ↓ │ │ 4. 确认文章内容 │ │ ↓ │ │ 5. 读取 front-matter.md (按需) │ │ ↓ │ │ 6. 创建文章文件 │ └──────────────────────────────────────────────────┘


## 关键机制
### 1. Description 是触发核心
```yaml
# 好的 description
description: "PDF processing. Use when user needs to: (1) extract text from PDF, (2) merge PDFs, (3) split PDF..."
# 不好的 description
description: "A skill for PDF" # 太模糊

原则：description 必须包含所有触发条件，因为 SKILL.md body 只有在触发后才加载。

2. 脚本执行路径

SKILL.md 指令
↓
Claude 调用 Bash Tool
↓
python3 /path/to/skill/scripts/xxx.py
↓
返回结构化结果
↓
Claude 解析并继续工作流

3. 按需加载 Reference

# SKILL.md 中的引用
- Front matter format: [references/front-matter.md](references/front-matter.md)

Claude 只在需要时读取该文件，避免上下文膨胀。

实际调用示例

用户: /hugo
Claude 内部流程:
1. 解析命令 → skill="hugo"
2. 匹配 metadata → 找到 hugo skill
3. 加载 SKILL.md body
4. 执行 Workflow:
- hugo version → v0.157.0
- detect_hugo_site.py → /Users/xxx/blog
- 确认: "检测到站点，确认？"
- 等待用户输入内容...
用户: 写一篇 Go 教程
Claude 继续:
- 生成内容大纲
- 确认内容
- 读取 front-matter.md
- 创建文件

性能优化

上下文占用

组件	大小	加载频率
所有 metadata	~2KB	始终
单个 SKILL.md	2-10KB	触发后
references/	任意	按需

最佳实践

控制 description 长度：100-200 词最佳
SKILL.md < 500 行：超出部分放入 references
脚本优于重复代码：脚本不占用上下文

总结

Skill 调用流程的核心是渐进式披露：

Metadata 始终在场，负责匹配
Body 触发后加载，提供工作流
Resources 按需读取，提供细节

这种设计在功能和上下文效率之间取得了平衡。

参考资料

从零构建 Claude Skill：以 Hugo 博客发布为例

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 12:00:00 +0800

背景

Claude Code 支持 Skill 系统，允许用户创建可复用的能力模块。本文以实际创建的 hugo skill 为例，详解 Skill 的构建过程。

什么是 Skill

Skill 是 Claude Code 的扩展机制，本质是一个包含指令和资源的目录：

skill-name/
├── SKILL.md # 核心：YAML frontmatter + Markdown 指令
├── scripts/ # 可执行脚本
├── references/ # 参考文档
└── assets/ # 输出资源

创建步骤

第一步：定义使用场景

明确 skill 要解决的问题。以 hugo skill 为例：

场景	用户输入	预期行为
检查环境	`/hugo`	检测 Hugo 安装和站点
创建文章	`/hugo 写一篇 Go 教程`	生成内容并发布
指定路径	`/hugo --path ~/myblog`	使用指定站点

第二步：规划资源需求

分析需要哪些辅助资源：

hugo/
├── scripts/
│ └── detect_hugo_site.py # 检测 Hugo 站点
├── references/
│ └── front-matter.md # Front matter 格式参考
└── SKILL.md

脚本的作用：检测站点需要遍历目录、检查配置文件，逻辑复杂，用 Python 脚本更可靠。

参考文档的作用：Front matter 有多种格式（TOML/YAML），放入 reference 按需加载。

第三步：编写 SKILL.md

Frontmatter 设计

---
name: hugo
description: "Publish content to Hugo blog. Use when user invokes /hugo command..."
---

description 是触发机制的关键：

必须包含 skill 功能
必须包含触发条件
会被 Claude 持续加载在上下文中

工作流设计

## Workflow

1. **Check Hugo installation**
2. **Determine Hugo site path**
3. **Determine content**
4. **Determine front matter format**
5. **Create the post**

每一步都有明确的指令，包括命令示例和预期输出。

第四步：实现脚本

# scripts/detect_hugo_site.py
def is_hugo_site(directory: str) -> dict:
 # 检查 config.toml / hugo.toml / config.yaml
 config_names = ["config", "hugo"]
 config_extensions = [".toml", ".yaml", ".yml", ".json"]

 # 返回检测结果
 return {
 "is_hugo_site": bool,
 "config_file": str,
 "content_dir": str,
 "existing_posts": list
 }

第五步：验证和迭代

# 测试脚本
python3 scripts/detect_hugo_site.py /path/to/hugo/site

# 实际调用
/hugo 写一篇测试文章

设计原则

1. 渐进式披露

Skill 采用三层加载机制：

层级	内容	加载时机
Metadata	name + description	始终
SKILL.md body	工作流指令	触发后
references/	详细文档	按需

2. 简洁至上

SKILL.md 应控制在 500 行以内，详细内容放入 references。

3. 自由度匹配

自由度	适用场景	hugo skill 示例
高	多种有效方案	文章内容由 LLM 生成
中	有首选模式	Front matter 格式检测
低	必须精确执行	站点检测脚本

最终结构

hugo/
├── SKILL.md # 2.8KB，核心指令
├── scripts/
│ └── detect_hugo_site.py # 92 行，站点检测
├── references/
│ └── front-matter.md # Front matter 格式参考
└── LICENSE.txt

总结

构建 Skill 的核心是明确场景 → 规划资源 → 精简指令。好的 skill 应该：

在 description 中清晰描述触发条件
用脚本处理确定性任务
用 references 存放详细文档
保持 SKILL.md 精简

参考资料

深入理解浏览器反机器人检测原理

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 12:00:00 +0800

背景

在 Web 自动化测试和数据采集场景中，浏览器自动化工具（如 Puppeteer、Playwright、Selenium）常被目标网站检测识别。网站通过一系列 JavaScript 指纹技术判断访问者是否为真实用户。

go-rod/stealth 是一个 Go 语言库，为 rod 浏览器自动化框架提供反检测能力。本文深入分析其工作原理。

网站如何检测自动化工具

1. Navigator 属性检测

浏览器暴露 navigator 对象，包含大量设备信息：

// 自动化工具的典型特征
navigator.webdriver === true // Selenium/WebDriver 标记
navigator.plugins.length === 0 // 无插件
navigator.languages.length === 0 // 无语言设置

真实浏览器的 navigator.webdriver 为 undefined，而自动化工具返回 true。

2. Chrome DevTools Protocol 检测

Chrome 通过 CDP (Chrome DevTools Protocol) 控制浏览器。网站可以检测：

// 检测 CDP Runtime 是否被启用
const e = new Error();
if (e.stack.includes('puppeteer_evaluation_script')) {
 // 检测到自动化
}

3. WebGL 指纹

WebGL 渲染器信息可用于识别：

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');
const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
// SwiftShader = Headless Chrome 的软件渲染器

4. iframe 内容检测

// 自动化工具注入的脚本会留下痕迹
const iframe = document.createElement('iframe');
iframe.srcdoc = '<script>console.log(navigator.webdriver)</script>';
// 检测 iframe 中的属性

Stealth 的反检测策略

核心架构

┌──────────────────────────────────────────┐
│ 用户代码 │
│ ↓ │
│ stealth.Page(browser) → *rod.Page │
│ ↓ │
│ rod.Browser.Page() + EvalOnNewDocument │
│ ↓ │
│ stealth.JS (嵌入的 JavaScript) │
│ - Chrome 对象伪装 │
│ - WebDriver 属性隐藏 │
│ - WebGL 指纹伪装 │
└──────────────────────────────────────────┘

MustPage 工作流程

MustPage 是 Page 的包装，遵循 Go 的 Must 前缀约定：

// MustPage 创建无法被检测为机器人的页面
func MustPage(b *rod.Browser) *rod.Page {
 p, err := Page(b)
 if err != nil {
 panic(err) // 失败时 panic
 }
 return p
}

// Page 创建页面并注入反检测脚本
func Page(b *rod.Browser) (*rod.Page, error) {
 // 1. 创建新的浏览器页面
 p, err := b.Page(proto.TargetCreateTarget{})
 if err != nil {
 return nil, err
 }

 // 2. 在每个新文档加载前注入 JS
 _, err = p.EvalOnNewDocument(JS)
 if err != nil {
 return nil, err
 }

 return p, nil
}

完整调用链：

MustPage(browser)
│
├── Page(browser)
│ │
│ ├── b.Page(proto.TargetCreateTarget{}) ← 创建空白页面
│ │ │
│ │ └── CDP: Target.createTarget
│ │
│ └── p.EvalOnNewDocument(JS) ← 注入反检测脚本
│ │
│ └── CDP: Page.addScriptToEvaluateOnNewDocument
│
└── 返回 *rod.Page

时序图：

用户代码 stealth.Page rod.Browser CDP
│ │ │ │
│──── Page() ─────>│ │ │
│ │ │ │
│ │── b.Page() ───────>│ │
│ │ │── createTarget─>│
│ │ │<── pageId ─────│
│ │<── *Page ──────────│ │
│ │ │ │
│ │── EvalOnNewDocument ───────────────>│
│ │ │ │
│<── *Page ────────│ │ │
│ │ │ │
│── Navigate() ────────────────────────────────────────>│
│ │ │
│ [JS 在页面脚本前执行] │
│ │ │

关键技术：EvalOnNewDocument

stealth 的核心只有 34 行 Go 代码，关键在于 EvalOnNewDocument：

func Page(b *rod.Browser) (*rod.Page, error) {
 p, err := b.Page(proto.TargetCreateTarget{})
 if err != nil {
 return nil, err
 }

 // 在每个新文档加载前注入 JS
 _, err = p.EvalOnNewDocument(JS)
 if err != nil {
 return nil, err
 }

 return p, nil
}

EvalOnNewDocument 是 CDP 的 Page.addScriptToEvaluateOnNewDocument 命令封装，确保注入的脚本在任何页面脚本执行前运行。

执行时机对比：

方法	执行时机	能否修改原生 API
`page.Eval()`	页面加载后	❌ 太晚，已被检测
`page.EvalOnNewDocument()`	页面加载前	✅ 优先执行

工作原理：

注册阶段：调用 EvalOnNewDocument(JS) 时，CDP 将脚本注册到浏览器
触发时机：每次导航到新页面或创建新 iframe 时自动执行
执行顺序：注入的脚本在页面的 <script> 标签之前执行

页面加载时间线：
─────────────────────────────────────────────────────────>
│ │ │
▼ ▼ ▼
[EvalOnNewDocument] [页面 <script>] [检测脚本]
│ │ │
└── 修改原生 API ────┘ │
│ │
└── 检测脚本看到伪装后的 API ──>

JavaScript 伪装模块

stealth 嵌入了 stealth-evasions 的编译产物（约 185KB），包含多个伪装模块：

模块	功能
`chrome.app`	伪装 Chrome 应用 API
`chrome.csi`	伪装 Chrome CSI 接口
`chrome.loadTimes`	伪装页面加载时间
`chrome.runtime`	伪装 Chrome Runtime API
`navigator.webdriver`	隐藏 WebDriver 标记
`navigator.plugins`	伪造插件列表
`navigator.languages`	设置语言列表
`webgl`	伪装 WebGL 渲染器信息
`iframe.contentWindow`	修复 iframe 检测
`media.codecs`	伪造媒体编解码器支持
`user-agent-override`	处理 User-Agent 一致性

WebDriver 属性隐藏示例

// 原始检测点
Object.getOwnPropertyDescriptor(Navigator.prototype, 'webdriver')

// stealth 的伪装
Object.defineProperty(Navigator.prototype, 'webdriver', {
 get: () => undefined,
 configurable: true
});

// 同时处理 iframe 场景
const originalContentWindow = HTMLIFrameElement.prototype.contentWindow;
Object.defineProperty(HTMLIFrameElement.prototype, 'contentWindow', {
 get: function() {
 const window = originalContentWindow.call(this);
 // 递归处理 iframe 内的 navigator.webdriver
 return window;
 }
});

WebGL 指纹伪装示例

// 检测点：SwiftShader 软件渲染器
const getParameter = WebGLRenderingContext.prototype.getParameter;
WebGLRenderingContext.prototype.getParameter = function(parameter) {
 // UNMASKED_VENDOR_WEBGL
 if (parameter === 37445) {
 return 'Google Inc. (NVIDIA)';
 }
 // UNMASKED_RENDERER_WEBGL
 if (parameter === 37446) {
 return 'ANGLE (NVIDIA, NVIDIA GeForce GTX 1080 Direct3D11 vs_5_0 ps_5_0)';
 }
 return getParameter.call(this, parameter);
};

设计亮点

1. go:generate 自动化嵌入

//go:generate go run ./generate

generate 脚本自动下载 stealth-evasions 并嵌入到 assets.go：

JS 库更新 → go generate → assets.go 更新 → 编译

2. 零运行时依赖

编译后 JS 代码嵌入二进制，无需外部文件，部署简单。

3. 惯用的 Go API

// 遵循 Go 的 Must 前缀约定
page := stealth.MustPage(browser) // 失败时 panic
page, err := stealth.Page(browser) // 返回 error

局限性与注意事项

非银弹：高级检测（如行为分析、TLS 指纹）无法通过 JS 伪装解决
维护成本：浏览器更新可能引入新的检测点
合规风险：某些网站明确禁止自动化访问

总结

stealth 通过在页面加载前注入伪装 JavaScript，解决了常见的自动化检测手段。其设计简洁，核心原理是利用 CDP 的 addScriptToEvaluateOnNewDocument 确保伪装代码优先执行。

理解反检测原理不仅有助于合法的自动化测试，也能帮助开发者设计更好的防御策略。

参考资料

手动档

一个 generate/main.go 自动生成 assets.go 文件，捞的 npm extract-stealth-evasions 项目。发文时间看到项目最新版本为 2023.3.1。且 CDN 不可用
extract-stealth-evasions 启动无头浏览器并加载 stealth 插件；重写 Puppeteer 页面的 evaluateOnNewDocument/evaluate 方法（这两个方法是 Puppeteer 向浏览器注入脚本的核心方法）；打开空白页（about:blank），触发 stealth 插件自动注入反检测脚本；重写后的方法会把注入的脚本代码捕获并拼接成字符串（存入 scripts 变量）。
消除自动化特征 https://www.doubao.com/thread/wbb28ea45418e850d

Posts on Tao

前端 UI 设计技能颗粒度：原子化检查清单

技能颗粒度检查项汇总

全量检查项

前言

什么是技能颗粒度

为什么需要原子化

本文受众

检查项层级全景

一、排版层（Typography）

二、颜色层（Color）

三、间距层（Spacing）

四、圆角层 + 阴影层（Border & Shadow）

五、布局层（Layout）

六、组件层（Components）

6.1 按钮（Button）

6.2 输入框（Input）

6.3 选择类控件

6.4 卡片（Card）

6.5 弹窗（Dialog/Modal）

6.6 抽屉（Drawer）

6.7 气泡卡片（Popover）

6.8 菜单（Menu / Dropdown Menu）

6.9 表格（Table）

6.10 标签页（Tabs）

6.11 导航组件

6.12 反馈组件

6.13 数据展示组件

6.14 组件组合模式（Composition Patterns）

七、交互层（Interaction）

八、响应式层（Responsive）

九、无障碍层（Accessibility）

十、主题层（Theming）

十一、动效层（Motion）

十二、图标层 + 图片层

十三、表单层（Forms）

十四、内容层（Content）

十五、国际化层（i18n）

十六、性能层（Performance）

十七、安全层（Security）

十八、滚动与光标层（Scroll & Cursor）

十九、错误与空状态层（Error & Empty States）

二十、高级组件层（Advanced Components）

20.1 轮播（Carousel）

20.2 全局搜索 / 命令面板（Command Palette）

20.3 图片灯箱（Lightbox）

20.4 通知中心

20.5 Cookie 同意横幅

20.6 超级菜单（Mega Menu）

20.7 图表/数据可视化（Charts）

20.8 富文本编辑器（Rich Text Editor）

二十一、实践建议

21.1 如何使用本清单

设计初期（需求阶段）

设计中期（开发阶段）

设计后期（审查阶段）

21.2 给 AI 的提示词模板

模板一：Design Token 定义

模板二：组件实现

模板三：审查检查单

21.3 检查优先级排序

二十二、工具推荐

二十三、总结

检查项统计

核心原则

与 /sc:design 配合

附：P0 快速审查清单

排版（P0）

颜色（P0）

组件状态（P0）

无障碍（P0）

错误处理（P0）

AI 辅助前端开发：从踩坑到改进的实战手册

前言

一、我遵循的"标准流程"

二、问题诊断：AI 的设计是表演性的

核心发现

AI 在设计阶段的两个致命缺陷

三、5 大问题模式

问题 1：设计确认走过场