用途：streamling 中 source 是流水线的头部，负责自己的模式、按需产出 RecordBatch 并驱动检查点。本技能用于实现 SourcePlugin 这一 Rust trait。前置条件为 streamling-plugin-basics（crate 设置、注册、生命周期与错误处理）。
主要能力与约定：trait 包含 initialize、output_schema、labels（可选身份标识）、generate_batch、process_checkpoint_marker 与 process_checkpoint_finalizer，并需实现 SupportsGracefulShutdown 与 Send + Sync。构造函数由 register_plugin_source! 调用，无 schema 参数，需接收 rt、state_backend_factory、metrics_recorder、options。
输出模式：源产出带逐行操作列的变更数据，使用 streamling_plugin::api::STREAMLING_COLUMN_NAME_OP（值 "_gs_op"），取值为 "i" 插入、"u" 更新、"d" 删除；即使仅追加也要保留该列。output_schema() 在实例生命周期内必须返回同一模式。
generate_batch 为拉取契约：有待处理数据时返回非空 RecordBatch；当前无数据时返回空批次（RecordBatch::new_empty），引擎视为“未完成、仅空闲”并再次轮询；出错返回 Err 使流水线失败。不要在 generate_batch 中无限阻塞，空闲时短暂休眠后返回空批。
结构建议：非玩具级源建议拆为 Fetcher（纯异步 fetch_page(cursor)）、Buffer（有序有界队列，提供背压）、Runner（实现 SourcePlugin，连接 fetcher、buffer 与检查点状态）。可恢复分页：把游标存入 PluginStateBackend，仅在 process_checkpoint_finalizer（提交点）推进并持久化，在 initialize 恢复；游标必须单调，使用 fetch_max/max 避免回退。分页有两种：数值/高度分页（顺序源，按高度去重）与不透明游标加时间戳分页（游标源，恢复 {last_ts_ms, token}）；就地变更的目录类 API 可用内容哈希去重。
快照加尾随的混合源先完成快照、记录交接点再轮询尾随。背压可通过 register_plugin_source!("my_plugin", "api_source", ApiSource); 与 set_plugin_output_buffer!("my_plugin.api_source", 1); 设置容量。关闭时在 terminate 中将运行标志置 false，is_running 在 initialize 前保持 true。CPU 密集的行构建可用 spawn_blocking。
常见错误：在 generate_batch 中永久阻塞；在 process_batch 中持久化游标（破坏精确一次）；游标回退；缺少 _gs_op 列；模式漂移；背压下无界缓冲。