Skip to content

07-skill-package-spec.md

Latest commit

 

History

History
224 lines (186 loc) · 10.2 KB

07-skill-package-spec.md

File metadata and controls

224 lines (186 loc) · 10.2 KB
Raw

07 · 技能包规范（实现契约）

技能包是 Agent-RPA 的核心可复用产物与实现契约：它必须同时可被 0 Token 回放、可自愈、可被 Agent 当 Skill 发现。 本篇给出结构规范与 JSON 示例；它与 02 生命周期、05 存储模型、06 接口 对齐。

1. 包结构总览

flowchart TD
    PKG["Skill Package"] --> MAN["manifest 清单<br/>(发现/描述/版本/信任)"]
    PKG --> IO["io 变量层<br/>(输入/输出 schema/机密引用/步间数据流)"]
    PKG --> GRAPH["action_graph 动作图<br/>(节点=语义动作)"]
    GRAPH --> NODE["每个节点"]
    NODE --> LOC["locators 多模态定位器束(≥2,含 rank)"]
    NODE --> ASR["assertions 断言(成功判据)"]
    NODE --> BEH["behavior_hint 行为提示(可选)"]
    PKG --> META["provenance 溯源<br/>(探索模型/时间/站点指纹/自愈历史)"]
Loading

分层理由（呼应不变量）：

  • action_graph 只描述"做什么"，不含任何时序/轨迹（I-2：怎么做在回放时重合成）。
  • 机密只在 io 层以 %vault:...% 出现（I-5）。
  • locators 每节点 ≥2 种并带 rank，支撑自愈与韧性排序（03/02）。

2. 顶层 JSON 示例（search-and-compare@ecom-x）

{
  "manifest": {
    "skill_ref": "search-and-compare@ecom-x",
    "version": "1.0.1",                 // 语义化版本；patch 位由自愈回写驱动
    "site": "ecom-x.example",
    "name": "电商搜索与比价",
    "description": "在 ecom-x 搜索关键词，抓取前 N 条商品的标题/价格/评分并结构化返回",
    "when_to_use": "需要在 ecom-x 做商品检索与横向比较时",
    "status": "published",              // draft | trialing | published | deprecated
    "trust_score": 0.94,                // 见 02 §7
    "default_tier": "T2",               // 该站记忆的最优隐身档(见 03/05 SiteMemory)
    "default_identity_policy": "sticky" // sticky(固定身份) | rotate(轮换,见 T3)
  },

  "io": {
    "inputs": {
      "query":  { "type": "string", "required": true,  "desc": "搜索关键词" },
      "topN":   { "type": "int",    "required": false, "default": 10 }
    },
    "secrets": [],                       // 本技能无需登录；如需则 ["%vault:ecom-x.login%"]
    "output_schema": {
      "items": [{ "title": "string", "price": "number", "rating": "number", "url": "string" }]
    }
  },

  "action_graph": {
    "entry": "n1",
    "nodes": {
      "n1": {
        "type": "navigate",
        "intent": "打开站点首页",
        "args": { "url": "https://ecom-x.example/" },
        "assertions": [{ "kind": "url_matches", "expr": "^https://ecom-x\\.example/" }],
        "next": "n2"
      },
      "n2": {
        "type": "type",
        "intent": "在搜索框输入关键词",
        "target_locators": [
          { "kind": "ax", "value": "role=combobox,name~=搜索", "rank": 0.9 },
          { "kind": "css", "value": "input#search", "rank": 0.6 },
          { "kind": "visual", "value": "anchor:magnifier-left-input", "rank": 0.3 }
        ],
        "args": { "text": "${inputs.query}" },       // 变量绑定
        "assertions": [{ "kind": "value_equals", "expr": "${inputs.query}" }],
        "next": "n3"
      },
      "n3": {
        "type": "click",
        "intent": "提交搜索",
        "target_locators": [
          { "kind": "ax", "value": "role=button,name~=搜索", "rank": 0.9 },
          { "kind": "css", "value": "button[type=submit]", "rank": 0.5 }
        ],
        "behavior_hint": { "importance": "normal" },
        "assertions": [{ "kind": "element_appears", "expr": "role=list,name~=结果" }],
        "next": "n4"
      },
      "n4": {
        "type": "loop",
        "intent": "遍历前 topN 条结果卡片",
        "over": { "kind": "ax", "value": "role=listitem in role=list[结果]", "limit": "${inputs.topN}" },
        "as": "card",
        "body_entry": "n5",
        "collect_into": "output.items",
        "next": "done"
      },
      "n5": {
        "type": "extract",
        "intent": "从结果卡片抽取字段",
        "scope": "${card}",
        "schema": {
          "title":  { "locator": { "kind": "ax", "value": "role=heading" }, "type": "string" },
          "price":  { "locator": { "kind": "css", "value": ".price" }, "type": "number", "regex": "[0-9]+(\\.[0-9]+)?" },
          "rating": { "locator": { "kind": "ax", "value": "role=img,name~=评分" }, "type": "number" },
          "url":    { "locator": { "kind": "ax", "value": "role=link" }, "attr": "href", "type": "string" }
        },
        "next": "loop_back"
      }
    }
  },

  "provenance": {
    "explored_by": { "model": "fable-5", "at": "2026-07-10T13:20:00Z" },
    "page_fingerprint": { "n2_container_ax_hash": "b3f1...", "n4_list_ax_hash": "9ac2..." },
    "heal_history": [
      { "at": "2026-07-11T09:00:00Z", "step": "n2", "level": "L1",
        "change": "promote ax locator above css", "version": "1.0.0 -> 1.0.1" }
    ]
  }
}

上例刻意展示：变量绑定 ${inputs.query}、多模态定位器带 rank、loop 控制流 + collect_into、extract 的字段级定位/正则/类型、provenance 记录探索模型与自愈历史。

3. 动作节点类型（原语库，对应 RPA Activities）

type 语义 关键字段 断言常用
navigate 导航 url, wait_policy url_matches
click 拟人点击 target_locators, behavior_hint element_appears/url_matches
type 拟人输入 target_locators, text(可变量/secret) value_equals
select 下拉选择 target_locators, option value_equals
scroll 滚动 `target delta`
wait 等待条件 condition, timeout 条件即断言
extract 抽取 scope?, schema nonempty
assert 显式断言 assertion —
loop 遍历列表 over, as, body_entry, collect_into, limit 每轮子断言
branch 条件分支 cond, then, else —
http(可选) 走浏览器自身请求已知端点(提速) request status_ok
human(升级) 交人处理(硬挑战/审批) reason 人确认
  • 只暴露拟人交互原语（click/type/scroll 均经行为合成器，见 04 §4）——从数据模型层杜绝机器人式瞬时操作。
  • http 节点谨慎使用：只对探索期已验证的、走浏览器自身的请求提速；不引入旁路 TLS 层（避免 03 的 JA4 泄漏）。

4. 定位器（Locator）规范

{
  "kind": "ax | css | xpath | attr | visual | text",
  "value": "定位表达式",     // ax: "role=button,name~=搜索"；visual: 锚点描述/模板
  "rank": 0.0,               // 0–1，回放优先级，由自愈命中率自学习(02 §5 / 03 §6)
  "scope": "${card}"         // 可选：相对某容器定位(loop 内常用)
}

定位器 kind 的韧性梯度（回放优先级默认序）： ax(语义,抗样式漂移) ≥ attr(data-testid/aria) > css/xpath(快但脆) > visual/text(兜底)。 每节点 target_locators 是一个有序束，回放按 rank 依次尝试；命中即用，全 miss 触发自愈。

5. 断言（Assertion）规范

{ "kind": "url_matches|element_appears|element_visible|value_equals|text_contains|nonempty|count_gte|custom",
  "expr": "判据表达式(可含 ${变量})",
  "on_fail": "heal | skip | fail" }   // 默认 heal：进入分级自愈
  • 断言是自愈触发器：on_fail=heal 时失败进入 L1→L2→L3（02 §5）。
  • 断言是默会知识的显式化：探索期强制生成，把"我知道它成功了"变成机器可判（02 §2 锚点）。

6. 变量与数据流

// 绑定语法
"${inputs.query}"        // 输入变量
"${card.title}"          // loop 迭代项字段
"${steps.n5.out.url}"    // 步间数据流：引用某步输出(02 §6)
"%vault:ecom-x.login%"   // 机密引用(仅解引用到运行内存, I-5)
  • 输入变量在发布前可被人审校（哪些该参数化是默会判断，见 02 §6）。
  • 步间数据流支持"上一步抽取 → 下一步输入"（如取详情页链接再进入抽价）。

7. 版本、diff 与兼容

  • major：动作图不兼容重构（入/出 schema 变化）→ 需重新 Trialing。
  • minor：新增可选能力/节点，向后兼容。
  • patch：自愈回写（定位器重排/替换、断言微调）——自动发生，附 heal_history。
  • diff 格式：节点级 add/remove/modify + 定位器/断言变化列表，供 06 diff_skill 与人类回滚。

8. 影子回放自测（Trialing 门禁）

技能从 draft→published 前，必须通过影子回放：用探索期输入做一次纯确定性回放，全部断言通过才发布。

flowchart LR
    DRAFT["draft(结晶产物)"] --> SHADOW["影子回放：确定性执行探索输入"]
    SHADOW -->|断言全过| PUB["published"]
    SHADOW -->|失败| BACK["回结晶：补采定位器/断言 或 重探索"]
Loading
  • 这是 SC2/SC7 的可验证门禁："能探索成功" ≠ "能确定性复现"，必须用回放本身验证回放能力。

验收检查表（本篇）

  • 包分层：manifest / io / action_graph / provenance；机密只在 io 且为占位（I-5）。（pkg/skillpkg schema 四分层必填 + I-5 白名单/启发式，change skill-package-schema）
  • 动作图不含时序轨迹（I-2）；仅暴露拟人交互原语。（封闭 schema + I-2 黑名单扫描；节点原语与 BrowserNode 契约对齐，select 映射见 change design Follow-ups）
  • 每节点 ≥2 定位器且带 rank；断言默认 on_fail=heal。（语义校验 + Normalize 缺省语义）
  • 变量、步间数据流、输出 schema、loop/branch 控制流齐备。（${inputs.*}/${steps.*.out.*}/loop 作用域绑定校验）
  • 版本/ diff / heal_history 支持自愈回写与人类回滚。（节点级 diff + semver D4 规则 + registry 持久化，deprecated 保留可查）
  • Trialing 影子回放作为发布门禁（SC2/SC7）。（registry 状态机：trialing→published 必须携带影子回放通过凭据）