独立 `meta.pagination` Schema 方案

1. 目标结构

业务结果与分页控制信息分层：

{
  "ok": true,
  "outcome": "success",
  "data": {
    "items": [{"id": "a"}]
  },
  "meta": {
    "pagination": {
      "endpoint_exhausted": false,
      "next_token": "cursor-2"
    }
  }
}

对应 compact/full leaf Schema：

{
  "result": {
    "outcomes": ["success", "failure"],
    "data_schema": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "description": "当前页业务记录",
          "items": {"type": "object"}
        }
      }
    }
  },
  "pagination": {
    "kind": "cursor",
    "cursor_parameter": "cursor",
    "meta_path": "meta.pagination",
    "endpoint_exhausted_path": "meta.pagination.endpoint_exhausted",
    "next_token_path": "meta.pagination.next_token"
  }
}

result 只描述 data；pagination 是与 result 同级的命令能力声明。

2. 分页状态

状态	`endpoint_exhausted`	`next_token`	Agent 行为
可续跑	`false`	必须非空	将 token 传给 `--<cursor_parameter>`
已耗尽	`true`	必须省略	停止翻页

endpoint_exhausted:true 只表示观察到 Endpoint 分页耗尽，不表示搜索索引健康、数据全量覆盖或业务对象不存在。

3. 映射规则

产品 mapper 可以读取服务端原始 hasMore/nextCursor、has_more/page_token 等字段，但统一 CLI 输出只公布 meta.pagination：

服务端表示还有下一页且 cursor 非空 → endpoint_exhausted:false + token。
服务端表示没有下一页 → endpoint_exhausted:true，不带 token。
表示还有下一页但 cursor 缺失、类型错误或证据冲突 → typed pagination_inconsistent，禁止伪装终页。
mapper 使用同一份上游响应构造 data 与 meta，不得重新请求。

原始分页控制字段不进入新的 result.data_schema。未迁移命令保持 legacy；已迁移命令按命令独立切换和回滚，不通过 Agent 参数选择协议。

4. Schema 规则

kind 当前只允许 cursor。
cursor_parameter 是真实 canonical CLI flag 名，不带 --，并必须存在于同一 leaf 的 parameters。
三个 meta path 由框架固定生成，产品不能覆盖。
compact/full leaf 同时包含相同的 result 和 pagination。
product/group 导航摘要不复制分页对象；Agent 需要时查询具体 compact leaf。
没有 pagination 表示该命令尚未发布经评审的分页能力，Agent 不得猜测。

5. 渐进接入

legacy_only：保持原输出，不公布分页声明。
dual_validate：业务执行一次；影子构造并校验 meta.pagination，外部 legacy 字节不变。
unified_active：输出独立 meta.pagination，Schema 公布同级 pagination 声明。
unified_stable：Skill、示例和 Agent 审计均只读取 meta 分页。

不增加 contract_version、--output-contract 或分页协议别名。

6. 验收

每个分页命令至少验证：

有下一页时 endpoint_exhausted:false 且 token 非空。
终页和空终页为 endpoint_exhausted:true 且无 token。
分页矛盾产生 typed failure，不 panic、不静默停止。
cursor_parameter 在 Help/Schema 中真实存在。
compact/full 的 result、pagination 分别 JSON 等价。
data_schema 不包含分页控制字段。
运行时 data 不包含迁移后的分页控制字段。
dual validate 与 active 都只消费一次上游响应。
Agent 逐命令扫描结果进入评测台账；不提交生成 Schema JSON fixture。

DevApp 首批落地

以下 8 个终结命令已发布独立 pagination Schema；运行时统一输出只在 meta.pagination 返回分页控制信息：

dev app list
dev app permission list
dev app event list
dev app version list
devapp +list
devapp +permission-list
devapp +event-list
devapp +version-list

两套既有命令前缀继续保留。原子命令的业务记录字段为 data.items；Shortcut 保留既有业务投影（例如 data.apps、data.permissions、data.events、 data.versions 以及 data.count），但两套入口都不再在业务数据中公布 hasMore/nextCursor。

7. 对齐依据

GWS 用请求参数和 response schema 描述分页事实；Lark 在统一输出层维护分页元数据。DWS 采用更明确的分层：业务 data 保真承载记录，框架 meta 承载续跑状态，Schema 用独立能力把 token 与下一次 CLI 参数连接起来。

4.6 KiB Raw Permalink Blame History Unescape Escape

独立 meta.pagination Schema 方案