服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- 10 月 12 日公告确认手动运行入口；任务覆盖整个 zone，不是只学习点击的单个操作。
- 学习使用此前 7 天返回 2xx 的请求：每个操作的字段学习需 1000 次，边界学习需 10000 次。
- API Security 客户已有相关能力；没有 API Security 的 Enterprise 客户仅限受邀封闭测试，不能由免费方案的上传额度推定资格。
- 运行完成要查看各操作的结果并审阅模式；检测、导出与实际阻断是不同步骤。
可以现在运行，但先确认自己有资格
Cloudflare 在 2026 年 10 月 12 日宣布 API Shield 支持手动模式学习。模式是从已有 API 请求中提炼出的字段、类型与约束；手动入口让团队在准备好代表性流量后启动学习，省去等待每周任务的时间。公告只有日期，没有准确上线时刻。
方案说明将通过学习与验证使用模式配置的能力提供给 API Security 客户。没有 API Security 的 Enterprise 客户需要受邀参加封闭测试，可联系账户团队。不能因为 Free 或 Pro 有上传模式额度，就推定能使用学习功能。
是否已有入口，以当前账户方案、功能资格与权限为准。官方没有在本次公告中公布手动运行的单次价格，也没有列出一份新的国家开放清单；不要把按钮出现当成免费或全球全账户开放。
1000 次学习字段，10000 次学习边界
模式学习使用此前 7 天的合格请求，官方说明只纳入返回 2xx 响应的请求。每个操作的字段学习门槛为 1000 次，边界学习门槛为 10000 次。手动运行沿用这些门槛，不会自动为一个流量不足的操作补出模式。
先对需要学习的操作启用配置学习，再准备真实有代表性的请求。字段学习回答“请求包含哪些字段与类型”；边界学习还要积累更多数据以确定约束。不要把两种门槛解释成所有 API 统一只需 1000 次。
假设一个已选操作有 999 次合格的 2xx 请求，另有 500 次 4xx 错误；这只是说明计数的例子，未实际执行。总请求数看起来超过 1000，字段学习仍未达到门槛。修复错误并检查合格流量，比反复点击运行更有用。
从 Operations 启动，运行范围是整个 zone
第一步，在 Cloudflare 控制台打开 Web Assets → Operations。从目标操作的溢出菜单选择 Learn profile，启用配置学习；已启用时确认状态。只查看到了某条路径，不代表它已经被纳入学习。
第二步，在操作表的 More options 菜单选择 Ad-hoc learn schema，打开 Schema learning 对话框，再选择 Run learning。这里的 zone 指该站点区域；运行会处理该 zone 中参与学习的操作，不能理解为只运行刚才点击的那一行。
第三步，在同一对话框查看任务状态与该 zone 的 Last completed run。手动学习处理已经观察到的流量，本身不会生成测试请求。需要准备流量时，应使用自己有权操作的测试环境与代表性请求，不把生产压测当作启用功能的前置步骤。
Running、Waiting to retry 与无结果怎么区分
Running 包含排队与处理阶段，不表示所有操作已经完成。Idle 表示没有活动任务；Waiting to retry 表示现有任务等待重试。运行或等待重试期间，按钮不可用时应查看现有任务，而不是连续创建新的学习任务。
如果界面显示 Retry in 等等待时间，这是请求限制的倒计时，不是整次学习必定完成的时间。所需时间取决于流量等因素，部分操作可能在整个 zone 任务结束前已有结果。
再打开操作的 View details → Security overview → Schema validation → View → Learned schema，查看该操作结果。Schema learned、No usable traffic、Learning failed 与暂时没有结果含义不同；无可用流量时先检查是否启用学习及合格流量，不把空结果当成成功。
学到模式后，先审阅再决定是否阻断
模式学习完成后，先检查字段、类型与约束是否符合正常请求。已观察到的流量是学习材料，不能替代你的接口约定；代表性不足时，直接用结果约束业务可能造成误判。
官方说明，学到配置后会进行持续检测，但检测本身不会缓解或阻断请求。要实际阻断，需要另外配置 Custom Rules。运行学习、查看违规检测和启用阻断应分开确认，不能向团队承诺“点一次学习就已经防护完成”。
建议先由接口负责人审阅结果，再按现有变更流程决定是否建立阻断规则。这是操作建议，不是本次公告新增的自动发布步骤；学习任务成功也不证明你的真实业务请求已经通过验收。
导出是当前快照，下一步取决于结果
满足方案条件时，可以将学到的配置导出为 OpenAPI 3.0.0 JSON。导出代表当时的结果快照，不会改动现有学习配置，也不等于新的请求已通过验证。导出能力要按自己的方案核对，不能仅凭学习按钮推定可用。
如果得到可用模式，下一步是审阅正常请求与约束；如果显示无可用流量，下一步是检查选中操作及 7 天内的合格请求；如果显示失败或权限不足，则保留当前状态并通过账户团队或官方支持确认原因。按结果选择下一步，比一律等待下周或一律重试更明确。
资料来源
常见问题
只有只读权限，为什么可以看状态却不能运行？
官方说明只读用户可从 Schema learning 菜单查看任务状态，不能触发学习。具体自定义角色名称未在这次说明中列出；需要运行时让有相应权限的负责人确认，不因状态可见就推定拥有运行权限。
修改某个接口后，能只学习这一个操作吗？
本次手动运行覆盖整个 zone 中参与学习的操作。可以逐个查看各操作的结果，但查看范围和任务范围不是一回事；官方未将此入口描述为单操作运行。
每周学习要等多久，手动功能解决了哪部分等待？
官方说明，达到流量门槛后，首次通过每周任务产生配置可能仍需等最多 7 天。手动入口让符合条件的现有流量不必等到每周任务启动；它不取消门槛，也不保证即时完成。