[Task][T20] 实现 v2 规则契约、版本化阶段钩子与设备能力协商 #22

Closed
opened 2026-08-15 14:44:17 +08:00 by ila · 3 comments
Owner

基本信息

  • 上级 Epic: [Epic] PDD 商品采集最小闭环 (#1)
  • 设计依赖: #21(T19,已验收)
  • 任务编号: T20
  • 是否可并行: 否,T21/T22 依赖本单契约。
  • 子项目影响: docs/、server/、android/。

原始需求摘要

采用 v2 类型化、版本化高层采集器方案;页面适配变化(例如规格面板打开后在规格容器向上滑动两次)应在 Agent 已支持原语时仅更新规则,不升级 Agent。

方案

  • 定义 schemaVersion: 2、collectorId 和版本化阶段钩子。
  • 钩子只允许固定阶段、语义目标、方向、有限次数和等待,不接受坐标、任意脚本或任意正则。
  • 设备注册/心跳上报能力;服务端创建、领取任务时校验规则所需能力。
  • 保持 v1 快照继续执行。

验收

  • v1 向后兼容;v2 非法阶段、动作、目标、方向、次数、超时被拒绝。
  • 规则可表达 afterSpecPanelOpen 对 specPanel 的两次 swipeUp。
  • 旧 Agent 不能领取 v2 任务并返回稳定兼容性错误。
  • 更新共享 API、业务规则和架构文档;测试真实通过。

非目标与风险

不实现采集算法、管理端模板、真机验收或采购流程;本单不加入创建订单动作。Agent 架构允许未来通过独立采购规则和版本化能力增加创建订单,采集规则不可调用;付款、任意坐标和远程脚本不开放。数据库/API 变化需兼容迁移。

## 基本信息 - 上级 Epic: #1 - 设计依赖: #21(T19,已验收) - 任务编号: T20 - 是否可并行: 否,T21/T22 依赖本单契约。 - 子项目影响: `docs/`、`server/`、`android/`。 ## 原始需求摘要 采用 v2 类型化、版本化高层采集器方案;页面适配变化(例如规格面板打开后在规格容器向上滑动两次)应在 Agent 已支持原语时仅更新规则,不升级 Agent。 ## 方案 - 定义 `schemaVersion: 2`、`collectorId` 和版本化阶段钩子。 - 钩子只允许固定阶段、语义目标、方向、有限次数和等待,不接受坐标、任意脚本或任意正则。 - 设备注册/心跳上报能力;服务端创建、领取任务时校验规则所需能力。 - 保持 v1 快照继续执行。 ## 验收 - v1 向后兼容;v2 非法阶段、动作、目标、方向、次数、超时被拒绝。 - 规则可表达 `afterSpecPanelOpen` 对 `specPanel` 的两次 `swipeUp`。 - 旧 Agent 不能领取 v2 任务并返回稳定兼容性错误。 - 更新共享 API、业务规则和架构文档;测试真实通过。 ## 非目标与风险 不实现采集算法、管理端模板、真机验收或采购流程;本单不加入创建订单动作。Agent 架构允许未来通过独立采购规则和版本化能力增加创建订单,采集规则不可调用;付款、任意坐标和远程脚本不开放。数据库/API 变化需兼容迁移。
Author
Owner

开始实施。根据用户补充,Agent 采用可扩展的类型化动作注册表;采集规则不能创建订单,未来采购规则可以调用专用创建订单动作,付款始终硬禁止。本单只实现 v2 契约、安全阶段钩子和能力协商,不实现采购。

开始实施。根据用户补充,Agent 采用可扩展的类型化动作注册表;采集规则不能创建订单,未来采购规则可以调用专用创建订单动作,付款始终硬禁止。本单只实现 v2 契约、安全阶段钩子和能力协商,不实现采购。
ila changed title from [Task][T20] 实现 v2 规则契约、受限阶段钩子与设备能力协商 to [Task][T20] ?? v2 ??????????????????? 2026-08-15 15:01:40 +08:00
Author
Owner

实现与验证

  • 已实现 v1/v2 双版本规则校验、类型化阶段钩子和两次向上滑动表达。
  • 设备注册/心跳上报版本化能力;指定设备、领取与开始任务均校验规则能力。旧 Agent 保持执行 v1,不能误领 v2。
  • 新增兼容数据库迁移和 API/架构/业务规则文档。
  • Agent 不是采集能力封闭实现:未来可在独立采购规则中增加创建订单能力;采集规则不能下单,付款保持硬禁止。
  • 验证:server go test ./...、go build ./...;Android testDebugUnitTest、assembleDebug;规则示例 JSON 解析与 git diff --check,均通过。
  • 提交:9d4a0b9

当前状态:待用户验收,工单保持开启。

## 实现与验证 - 已实现 v1/v2 双版本规则校验、类型化阶段钩子和两次向上滑动表达。 - 设备注册/心跳上报版本化能力;指定设备、领取与开始任务均校验规则能力。旧 Agent 保持执行 v1,不能误领 v2。 - 新增兼容数据库迁移和 API/架构/业务规则文档。 - Agent 不是采集能力封闭实现:未来可在独立采购规则中增加创建订单能力;采集规则不能下单,付款保持硬禁止。 - 验证:`server go test ./...`、`go build ./...`;Android `testDebugUnitTest`、`assembleDebug`;规则示例 JSON 解析与 `git diff --check`,均通过。 - 提交:`9d4a0b9` 当前状态:待用户验收,工单保持开启。
ila changed title from [Task][T20] ?? v2 ??????????????????? to [Task][T20] 实现 v2 规则契约、版本化阶段钩子与设备能力协商 2026-08-15 15:03:17 +08:00
Author
Owner

用户已于 2026-08-15 明确验收通过。T20 完成,提交:9d4a0b9。

用户已于 2026-08-15 明确验收通过。T20 完成,提交:`9d4a0b9`。
ila closed this issue 2026-08-15 15:04:56 +08:00
Sign in to join this conversation.
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/goauto#22