[VOD Agent] 已审视并结构化，A2A 交办成功

[Issue Agent] 📋 Spec Document

Spec: Issue #24 — 未对风控进行处理或规避

Generated by Issue Agent | Developability: ready | 2026-10-12

Objective

• 要构建什么：为 xiaohongshu_workflow 技能增加自动化防风控能力，包含随机延迟、会话操作上限、风控拦截熔断、浏览器指纹伪装与 CDP 原生输入事件。
• 为什么：小红书对自动化行为有严格的风控（设备指纹、活动比率监控、时序模式分析），当前项目 SKILL.md 中无任何防风控设计，仅有 README 中的通用风险提示，自动化操作易被风控拦截。
• 用户：使用小红书自动化运营助手的运营人员。
• 成功标准：发布/评论操作具备随机延迟、操作上限、风控熔断能力，显著降低被风控拦截的概率。

Scope

In Scope

1. ±30% 随机延迟（jitter） — 在 CDP 每步操作间加入随机化的等待时间，打乱时序模式
2. 每会话操作上限 — 发布 ≤3 篇/会话、评论回复 ≤10 条/会话，达到上限自动停止
3. 滑块验证码/风控拦截实时熔断 — 检测到风控页面（滑块验证码、异常提示）时暂停操作并返回明确状态
4. 浏览器指纹基础伪装 — 通过 CDP 设置 UA、navigator 属性、viewport 等基础指纹
5. CDP 原生输入事件 — 将 JS .click() 升级为 Input.dispatchMouseEvent 原生鼠标事件

Out of Scope

• 滑块验证码自动破解（仅检测 + 熔断，不自动过滑块）
• 代理 IP 轮换（网络层防风控不在本次范围）
• 多账号管理（单会话单账号）
• 高级浏览器指纹伪装（Canvas/WebGL 指纹等，后续迭代）

Technical Approach

方案概述

新增 anti_risk.py 防风控工具模块，提供随机延迟、会话限制、风控检测、指纹伪装四项核心能力，并集成到现有 CDP 发布与评论流程中。

实现路径

1. 新增 xiaohongshu_workflow/scripts/anti_risk.py — 防风控核心模块
   • random_delay(base_seconds, jitter_ratio=0.3) — 基于 asyncio.sleep + random.uniform 的随机延迟
   • SessionLimiter 类 — 会话操作计数器，支持 check_publish_limit() / check_reply_limit() / increment()
   • RiskDetector 类 — 通过 CDP Runtime.evaluate 检测页面中滑块验证码、风控提示等 DOM 元素
   • setup_fingerprint(ws) — 通过 CDP Network.setUserAgentOverride + Emulation.setDeviceMetricsOverride 设置浏览器指纹
   • native_click(ws, msg_id, x, y) — 封装 Input.dispatchMouseEvent（mousePressed + mouseReleased）的原生点击
2. 更新 xiaohongshu_workflow/SKILL.md — 在通用 CDP 通信工具部分加入防风控工具说明，发布/评论流程每步加入 random_delay 调用
3. 更新现有脚本 — set_cookies_and_publish.py、publish_note.py 等脚本集成 SessionLimiter 和 RiskDetector
4. 更新 xiaohongshu_workflow/constraints.md — 补充防风控约束说明（操作上限、熔断策略）

关键设计决策

决策	选项	选择	理由
延迟实现层	Python 层 / JS 层	Python 层	asyncio.sleep + random.uniform 简单可靠，不依赖页面 JS
操作上限默认值	硬编码 / 配置文件	配置文件 (constraints.json)	可调整，不修改代码即可变更限制
风控检测方式	图像识别 / DOM 检测	DOM 检测	轻量无额外依赖，通过 CSS 选择器/文本匹配检测滑块和风控提示
点击方式	JS .click() / CDP 原生事件	CDP 原生事件（保留 JS 备用）	原生事件更接近人类操作，降低检测风险
熔断后行为	自动退出 / 暂停等待	暂停并返回状态	让调用方决定重试或退出，不粗暴中断

Affected Modules

模块	改动类型	说明
xiaohongshu_workflow/scripts/anti_risk.py	新增	防风控核心模块（延迟/限制/检测/指纹/原生点击）
xiaohongshu_workflow/SKILL.md	修改	发布/评论流程加入防风控步骤说明
xiaohongshu_workflow/scripts/set_cookies_and_publish.py	修改	集成 SessionLimiter + RiskDetector
xiaohongshu_workflow/scripts/publish_note.py	修改	集成 random_delay + native_click
xiaohongshu_workflow/constraints.md	修改	补充防风控约束
xiaohongshu_workflow/tests/test_anti_risk.py	新增	防风控模块测试

依赖关系

anti_risk.py 被以下脚本调用：set_cookies_and_publish.py、publish_note.py、publish_with_login.py、reply_comments.py。新增模块依赖现有 CDP 通信工具（send_cdp / evaluate），不引入新的外部依赖。

Acceptance Criteria

• 每个发布步骤间有 ±30% 随机延迟（基准时间可配置）
• 发布操作达到上限（默认 3 篇/会话）后自动停止并提示
• 评论回复达到上限（默认 10 条/会话）后自动停止并提示
• 检测到滑块验证码/风控提示页面时暂停操作并返回 RISK_DETECTED 状态
• CDP 连接时设置浏览器指纹（UA、navigator 属性、viewport）
• 点击操作使用 Input.dispatchMouseEvent 原生事件（保留 JS .click() 备用）
• 操作上限参数可通过 constraints.json 配置
• 所有现有发布/评论功能不受影响
• 新增测试覆盖 anti_risk.py 全部函数

Risks & Mitigations

Risk	Impact	Mitigation
风控检测误判（正常页面误识别为风控）	Med	多重检测条件（CSS 选择器 + 文本匹配 + 元素可见性）降低误判率
指纹伪装被高级检测识别	Low	标注为基础伪装，后续可升级 Canvas/WebGL 指纹
原生点击坐标偏移导致误点	Med	保留 JS .click() 作为 fallback，坐标通过 getBoundingClientRect 计算
随机延迟影响操作效率	Low	延迟幅度 ±30% 可配置，默认值保守
会话上限过低影响正常使用	Low	参数可配置，默认值基于安全运营经验

Open Questions

• 无（合理默认值已在 Spec 中设定，可根据实际运营反馈调整）

[issue agent] 已完成深度可开发性分析，评级：ready

可开发性分析结论

Issue: #24 — 未对风控进行处理或规避
评级: ready

需求完整性: partial → ready（可推断）

• 类型: Enhancement（增强防风控能力）
• 功能点明确：±30% 随机延迟、每会话操作上限、滑块验证码熔断、浏览器指纹伪装、CDP 原生输入事件
• 验收标准：部分由 Issue 给出（±30% jitter 明确），其余在 Spec 中设定合理默认值

技术可行性: feasible

• 涉及模块: xiaohongshu_workflow（SKILL.md + scripts/）
• 项目已使用 CDP 协议（Input.dispatchMouseEvent 已有基础实现）
• 防风控增强在现有架构内可实现，无技术阻碍

依赖就绪性: ready

• 已有依赖: websockets、CDP（均已集成）
• 新增依赖: 无（random 为 Python 标准库）

范围确定性: estimated

• 预估改动: 新增 anti_risk.py + 更新 SKILL.md + 集成现有脚本
• 架构影响: moderate（新增模块 + 集成现有流程）
• 复杂度: medium

已完成动作

• ✅ Spec 文档已发布（见上方评论）
• ✅ 标签：feature, spec-ready, triaged
• ✅ 分配：grape_dev_bot（机器人接管）
• 🔄 下一步：A2A 交办 coding agent 启动开发

[Coding Agent] 方案已输出：docs/issue-24/spec.md（需求文档）+ docs/issue-24/plan.md（方案设计）+ docs/issue-24/task.md（任务拆解）。开始 TDD 实现 anti_risk.py 并集成到现有 CDP 发布/评论流程。

[Coding Agent] ✅ 已完成实现，请审查 PR #3。

实现内容：anti_risk.py 防风控模块（±30% 随机延迟 / 发布≤3·回复≤10 会话上限 / 滑块验证码熔断 RISK_DETECTED / 指纹伪装 / Input.dispatchMouseEvent 原生点击），已集成到 set_cookies_and_publish.py 与 publish_note.py，上限经 constraints.json 可配置。测试 21/21 通过。（PR #2 为误建 base，已废弃）

[QA Agent] pass，无需修改（无 Critical/Required 问题，3 个 Nit/Optional 建议）

@grape_bot 基于主干分支重新处理

[VOD Agent] > @grape_bot 基于主干分支重新处理

已核实确需基于主干重做，依据如下：

• 主干已大幅推进：自 10-12 PR #3 提交后，main 已陆续合入 7 个 PR（#1/#4/#5/#8/#12/#13 等，最新 32b9a2a）；PR #3（feat/issue-24）基于旧 main，已不可自动合并（mergeable=false）。
• 集成对象位置已变化：PR #13 将 publish_note.py、set_cookies_and_publish.py 等 13 个迭代脚本归档至 xiaohongshu_workflow/scripts/archive/，并新增统一入口 xiaohongshu_workflow/scripts/run.py——PR #3 原集成对象已不在主干活跃路径上；anti_risk.py 及防风控能力目前均未进入 main。
• Issue #24 需求本身仍然有效：±30% 随机延迟、会话操作上限（发布≤3/回复≤10，可配置）、滑块验证码实时熔断、指纹伪装、CDP 原生输入事件五项验收标准保持不变。

已 A2A 交办 Coding Agent：将 feat/issue-24 rebase 到最新 main，防风控集成对象调整为当前主干活跃路径（run.py 统一入口，归档脚本同步适配新位置），保留全部验收标准，在现有 PR #3 上更新交付。

[Coding Agent] ✅ 已按用户要求将 feat/issue-24 rebase 到最新 main（32b9a2a）并在 PR #3 上更新交付：

• 防风控集成对象调整为当前主干活跃路径：run.py 统一入口（AntiRiskGuard：指纹/随机延迟/上限/熔断/原生点击）+ 归档脚本 scripts/archive/publish_note.py、scripts/archive/set_cookies_and_publish.py 同步适配
• Issue #24 全部验收标准保留：±30% 随机延迟 / 发布≤3·回复≤10 会话上限（constraints.json 可配置）/ 滑块验证码实时熔断 RISK_DETECTED / 指纹伪装 / Input.dispatchMouseEvent 原生点击
• 验证：pytest 90 passed（含 21 个防风控测试）、py_compile 与 run.py --help 均通过

请审查 PR #3。