从 CHANGELOG 看 Pathway 的演进：连接器生态、数据持久化与 LLM RAG 能力全景解析

Pathway 是面向流处理、实时分析与 LLM/RAG 管线的 Python 增量计算框架。仓库根目录的 CHANGELOG.md 完整记录了该项目从 0.2.0（2023-07-20）到 0.32.1（2026-07-29）及 [Unreleased] 区间的全部版本变更，遵循语义化版本（SemVer）。本文以这份变更日志为主体，按“近期变更、连接器生态、持久化与投递保证、LLM/RAG 能力、破坏性变更迁移”五条主线重新组织内容，并结合仓库源码与 pyproject.toml 依赖清单做交叉印证，帮助你在选型、升级与故障排查时快速判断每个版本带来了什么、改了什么、需要注意什么。

一、变更日志的组织约定：先理解再阅读

CHANGELOG.md 的开头声明：“All notable changes to this project will be documented in this file”，并注明项目遵循语义化版本规范。其条目组织有如下固定结构：

• 顶层小节：每个版本以 ## [版本号] - 日期 标注，最新的未发布变更集中在 ## [Unreleased] 一节中，先于所有已发布版本出现；
• 二级分类：每个版本内部按 ### Added（新增）、### Changed（变更）、### Fixed（修复）、### Removed（移除）分类；
• 破坏性变更标记：所有不向后兼容的条目一律以 BREAKING 前缀显式标出，并在条目内给出具体的迁移方式（如参数改名前后的对应写法）。

掌握这一约定后，升级 Pathway 时的正确姿势是：先扫 [Unreleased] 与目标版本的 BREAKING 条目，再确认自己用到的连接器（pw.io.*）、持久化（pw.persistence）、LLM xpack（pw.xpacks.llm）相关的 Added/Changed 条目。

二、最新变更：[Unreleased] 区间的核心内容

[Unreleased] 小节是距离发布最近的一批变更，技术密度最高，涉及持久化投递保证的破坏性修正、新连接器、Python 3.14 支持与依赖刷新。

2.1 MQTT 持久化要求稳定 client_id（破坏性变更）

• BREAKING：pw.io.mqtt.read 在启用 persistence 且 qos 为 1 或 2 时，连接 URI 中必须携带稳定的 client_id，否则构造管线时直接报错；此前这类管线能启动，但重启时静默丢消息。
• 启用持久化后，MQTT broker 必须能为每个客户端缓冲“未确认 + 排队”的检查点窗口消息；以 Mosquitto 为例需要关注 max_inflight_messages 与 max_queued_messages，默认的 broker 限制可能压低吞吐。

对应的行为修复是：启用持久化后，qos 1/2 的消息只有在持久化检查点已覆盖它之后才会向 broker 确认，且 broker 会话可跨重启存活。因此崩溃前刚收到的消息、以及管线宕机期间发布的消息都会被重投（至少一次语义）。仓库中 MQTT 连接器 的文档字符串已把 client_id 写入所有使用示例（如 mqtt://localhost:1883/?client_id=test），并在说明中明确“启用持久化时连接 URI 必须携带稳定 client_id”，与 CHANGELOG 描述一致。

2.2 NATS JetStream 消费者的检查点延迟确认

pw.io.nats.read 在启用持久化时自动创建的 JetStream pull 消费者，现在会配置为检查点延迟确认：max_ack_pending 设为无上限、ack_wait 拉长，使消息只有在检查点覆盖后才确认，重启后由服务端重投（至少一次）。需要注意：服务端已存在的同名消费者会保留旧配置，必须重建才能生效。NATS 连接器 的文档中同样解释了 ack_wait 需大于检查点间隔的前提。

2.3 新增 Apache Pulsar 输入/输出连接器

pw.io.pulsar.read 与 pw.io.pulsar.write 进入 [Unreleased]：支持 Token 与 OAuth2 认证、TLS 加密连接、static 与 streaming 两种读取、动态输出 topic，以及启用持久化时的至少一次投递。该连接器属于 Pathway Scale 与 Enterprise 许可层。源码中 Pulsar 连接器模块 已存在，与变更日志相互印证。

2.4 Python 3.14 支持

• 发布的 wheel 覆盖 CPython 3.10–3.14，测试套件在最低版本（3.10）与最高版本（3.14）上同时运行。
• 唯一例外：PaddleOCR 文档解析在 3.14 上不可用，因为 paddlepaddle 尚未发布对应 wheel——xpack-llm-docs 额外依赖在 3.14 下会跳过 paddle 包，使用 paddle 解析器时会得到明确报错。
• Airbyte 连接器的 venv 模式改用机器上找到的最新受支持 CPython（3.10–3.13）创建虚拟环境（连接器包尚不支持 3.14）；若机器上没有对应版本，会给出建议 enforce_method="docker" 的明确错误。

pyproject.toml 中 requires-python = ">=3.10" 与该声明吻合；可选依赖定义 中 xpack-llm 对 3.14 专门放宽为 litellm == 1.83.0，xpack-llm-docs 中 paddleocr 带 python_version < '3.14' 标记，均为上述说明的落地证据。

2.5 依赖版本刷新与管线构建提速

[Unreleased] 中对“影响面最大的依赖”做了刷新，且明确Pathway 自身的用户可见 API 不变：

依赖	变更	仓库证据
deltalake	0.17 线 → 1.6+（写路径大量正确性与性能改进）	pyproject.toml deltalake >= 1.6.0, < 2.0.0
pdfminer.six	固定到 20260107 发布	pyproject.toml
litellm	要求 1.84+（3.14 上为 1.83.0），连带 OpenAI SDK 2.x	pyproject.toml
llama-index-core	要求 0.13+	pyproject.toml
transformers	上限从 4.49 提升到最新 4.x	pyproject.toml
google-cloud-bigquery / google-api-core	接受整个当前主版本线（重试、超时、正确性改进）	pyproject.toml、pyproject.toml
pyarrow / cohere / beartype	允许 25 / 7.x / 提升上限，下限不变	pyproject.toml
tests extra	pytest 9	pyproject.toml

另一项重要性能改进：构建管线的速度显著提升。附加在每个表达式与算子上的位置信息（用于错误信息中 “Occurred here” 部分）现在不再物化完整堆栈轨迹来收集；对“构建大量小管线”的场景（典型如单测套件），图构建耗时最多可快约 6 倍，错误信息本身保持不变。

2.6 numpy 2.5 兼容与网络等待有界化

• npt.NDArray[...] 注解在 UDF 签名与 schema 中兼容 numpy 2.5+（该版本将 NDArray 改为惰性类型别名，此前会抛 TypeError: Unsupported type NDArray[...]）；同时修复了 2.1–2.4 中 npt.NDArray[X] 被误当作二维数组处理的问题，现在在所有 numpy 版本上统一表示“维度数不定的数组”。
• pw.io.mysql.read/write 现在为所有网络等待（建连、socket 读写、TCP keepalive 探测）设置上限：此前已建立的连接“静默死亡”（如网络中断后的半开连接）会让管线无限期停摆且无任何日志；现在会在有界时间内检测到停顿、记录日志并自动重连续传。同一保护还覆盖了此前缺失的连接器：pw.io.mssql.read/write 自动重连；pw.io.elasticsearch.read/write、pw.io.weaviate.write、pw.io.chroma.write 与 Iceberg REST catalog 客户端对每个请求设时长上限；pw.io.postgres 额外约束建连耗时（此前静默不可达的主机可能阻塞两分钟以上）；pw.io.questdb.write 配置 tcp:: 传输时会告警（其等待无法有界），默认推荐的 http:: 传输不受影响。

三、版本时间线总览（0.2.0 → 0.32.1）

CHANGELOG.md 覆盖的版本跨度大、节奏快，以下按里程碑重新索引，便于快速定位你关心的能力出现在哪个版本：

版本	日期	里程碑（节选）
0.32.1	2026-07-29	Chroma/Qdrant/DuckDB/Weaviate/Pinecone 写入连接器；udf_cache_directory；only_metadata 读模式扩展；pathway[twelvelabs] 原生 Video RAG
0.31.1	2026-06-12	Elasticsearch 读、ClickHouse 写、MySQL 读（binlog CDC）；Iceberg 全类型解码与 struct 支持
0.31.0	2026-05-25	SQLite 写连接器；Delta decimal/date 支持
0.30.1	2026-04-23	RabbitMQ Streams 读写、SQL Server 读写、Milvus 写；pathway spawn --addresses 多机部署；pw.iterate 算子持久化
0.30.0	2026-03-24	MongoDB 读、PostgreSQL 读（解析 WAL）；Airbyte dependency_overrides
0.29.1 / 0.29.0	2026-02 / 2026-01	Worker 自动伸缩；Web Dashboard；Kafka OAUTHBEARER；Bedrock 集成
0.28.0	2026-01-08	连接器组空闲时长、源优先级；连接器组可用于多进程运行
0.27.x	2025-11/12	Table.filter_out_results_of_forgetting；NATS JetStream；Iceberg Glue catalog
0.26.x	2025-08/10	forget/buffer/ignore_late；max_backlog_size 反压；Kinesis 读写；PaddleOCR 解析器
0.25.x	2025-07	MCP 服务器、DynamoDB 写、to_stream/from_streams
0.24.x	2025-06	MQTT 读写；Confluent Schema Registry
0.23.0	2025-06-12	TableOptimizer 运行时优化 Delta 输出
0.22.0	2025-06-05	Azure Blob 持久化后端；UDF 批处理（max_batch_size）；表达式批量求值（BREAKING）
0.21.x	2025-03/05	输入同步组；CSV 全类型序列化；运行时错误报告增强
0.20.x / 0.19.0	2025-02	DoclingParser 结构化分块；fully_async_executor 与 Future 类型
0.18.0	2025-02-07	JSON 全类型序列化；py.typed 标记
0.17.0	2025-01-30	pw.io.iceberg.read；连接器 name 参数；大规模弃用 API 清理
0.15.0	2024-09-12	DocumentStore（实验性 RAG 索引）
0.11.0	2024-05-10	索引体系：LSH/USearch 的 k-NN、Tantivy BM25、DataIndex 查询
0.7.10	2024-01-26	OpenAI 封装、VectorStore（向量索引管线雏形）
0.3.0	2023-08-07	要求 Python ≥ 3.10，类型检查更严格
0.2.0	2023-07-20	变更日志起点

四、连接器生态：输入、输出与数据湖

Pathway 连接器演进的主线是“先补齐输入侧快照+增量双模式，再在输出侧统一快照/变更流两种语义”。以下按类别梳理变更日志中的关键事实。

4.1 数据库连接器

• PostgreSQL：0.30.0 引入 pw.io.postgres.read，直接解析 WAL 获取变更；0.29.0 起连接默认配置约 5 分钟死对端检测的 TCP keepalive（keepalives_idle=300、tcp_user_timeout=300000 等），使被 SIGKILL 的进程在数分钟内释放临时复制槽；0.29.1 起连接以 application_name=pathway[:<name>] 标注，便于在 pg_stat_activity 中识别。0.31.1 中读写连接器都增加了大量预检校验（不支持的类型、数组元素类型不匹配、可空性不匹配、非 append-only 流表上的 REPLICA IDENTITY NOTHING 等），把误配置暴露为清晰的启动期错误。写入侧 0.32.1 改为通过二进制 COPY 协议流式写入，批量吞吐最高提升约 100 倍：stream_of_changes 模式直接 COPY 到目标表，snapshot 模式先落临时表再单次集合级 upsert/delete。
• MySQL：0.31.1 引入 pw.io.mysql.read，流式模式通过二进制日志做 CDC（要求 log_bin 开启、binlog_format=ROW、binlog_row_image=FULL 及复制权限）；与 PostgreSQL 逻辑复制不同，它不在服务端留下状态，没有会堆积日志的复制槽；启用持久化时保存 binlog 坐标并在重启时恢复，所需 binlog 已被服务端过期清除时会报清晰错误。0.26.4 起有 pw.io.mysql.write；0.32.1 起写入改为批量：启动时探测服务端能力，允许 LOAD DATA LOCAL INFILE 时走该通道，否则回退分块多行 INSERT，两条路径结果一致。
• SQL Server：0.30.1 引入 pw.io.mssql.read（先全量快照，再用 CDC 跟踪增量）与 pw.io.mssql.write（MERGE/DELETE）；0.31.1 起对配置与 schema 做构造期校验（primary_key 非法、与自动追加的 time/diff 列冲突、目标列缺失或类型不符等）；0.32.1 写入改用原生 INSERT BULK 批量加载协议，批量吞吐约提升 25 倍。
• SQLite / ClickHouse / QuestDB / DynamoDB：分别由 0.31.0（pw.io.sqlite.write，INSERT ... ON CONFLICT DO UPDATE 维持快照）、0.31.1（pw.io.clickhouse.write，支持 stream_of_changes 与 ReplacingMergeTree 快照两种输出）、0.25.0（pw.io.questdb.write）与 0.25.1（pw.io.dynamodb.write）引入；0.32.1 又新增了基于原生进程内连接器的 pw.io.duckdb.write，numpy 数组/list[float] 向量列会落到原生 DOUBLE[] 列表列，可直接用 DuckDB 向量距离函数做 RAG 检索，且 detach_between_batches 允许每批提交后释放文件锁、供独立查询进程短连接读取。
• MongoDB：0.15.3 起有 pw.io.mongodb.write；0.30.0 引入 pw.io.mongodb.read（快照 + change stream 增量）。0.29.1 起写入支持 output_table_type="snapshot"；0.31.0 起 stream_of_changes 模式正确产出更新时的撤销+插入两个事件，并拒绝 schema 中含 _id（任意模式）或 diff/time（流模式）列的表，避免静默丢值或运行期报错。

4.2 消息队列与流

• Kafka / Redpanda：0.4.1 起支持 zstd 压缩消息；0.24.1 支持 Confluent Schema Registry；0.29.1 支持 OAUTHBEARER；0.21.4 起 pw.io.kafka.read 支持 static 模式；0.31.1 起所有 Kafka 连接器在构造期校验参数（空 topic、缺 bootstrap.servers、非正的 max_backlog_size 等），pw.io.kafka.write 拒绝会静默丢数据或产生畸形消息的配置（重复 header、与保留头 pathway_time/pathway_diff 冲突等），并修复了 static 模式间歇性读不到数据的问题（改为显式分配分区并读到启动时捕获的 end offset，彻底摆脱 consumer-group 依赖）。
• NATS：0.15.4 引入读写连接器；0.27.0 支持 JetStream；0.32.1 的 [Unreleased] 修复了多 worker 写入 JetStream 时因“全批次无等待发布”压垮服务端导致的 429 与丢消息问题——写入端现在限制在途未确认发布数量（背压）并指数退避重试瞬态失败。
• MQTT：0.24.0 引入；0.32.1 修复了大于 10 KB 载荷默认被拒、broker 瞬断后停摆、发布主题未校验等问题（详见 [Unreleased] Fixed 与下文 2.1）。
• RabbitMQ Streams：0.30.1 引入，支持 JSON/明文/raw、流式与静态、偏移恢复、动态 topic、TLS，要求 Scale/Enterprise 许可。
• Kinesis / PubSub / Pulsar：分别由 0.26.2（AWS Kinesis 读写）、0.9.0（Google PubSub 写）、[Unreleased]（Apache Pulsar 读写，Scale/Enterprise）引入。

4.3 数据湖与对象存储

• Delta Lake：0.13.1 引入 pw.io.deltalake.read，0.13.0 起写入支持 S3，0.21.0 起建表时把 Pathway 元数据存入 Delta 表自身（读表可免 schema 参数），0.23.0 起可用 TableOptimizer 定义运行时输出表优化（compact 频率、保留期等），0.31.0 起读支持 decimal(p, s)（声明 float 有损、声明 str 无损）与 date/timestamp_millis 列。0.26.4 起 start_from_timestamp_ms 支持非 append-only 表按版本重放历史变更。
• Iceberg：0.17.0 读、0.16.3 写，0.19.0 起支持 S3 数据后端与 Glue catalog，0.27.0 的 BREAKING 变更把 catalog 参数改为必填（RestCatalog 或 GlueCatalog）。0.31.1 是类型能力的集中补齐：读侧解码全部 Iceberg 原始类型（date→DateTimeNaive 零点、time→Duration、uuid→规范 8-4-4-4-12 十六进制串或原始 bytes、fixed(N)→bytes、decimal 有损 float 或无损 str）；写侧与目标表既有 schema 对账，把 Pathway 宽类型收窄写入窄列（如 int→32 位 int 带溢出检测、str→decimal/uuid、Duration→time）；struct<…> 通过位置式 tuple[…] 绑定，写外部建表时自动采用目标字段名。
• S3 / MinIO / 文件系统：0.16.1 起 S3 读监控删除与修改，0.26.2/0.32.1 起 pw.io.fs.read、pw.io.s3.read、MinIO、pyfilesystem、SharePoint 等连接器统一支持 format="only_metadata" 模式——只跟踪对象的增删改、不下载内容，表里仅有 _metadata 列，适合监控大桶变更而不付出流量代价；S3/MinIO 的该模式在引擎层面直接跳过下载。0.26.0 起输入连接器普遍支持 max_backlog_size 反压，应对“初始大批量 + 后续小增量”的源。

4.4 向量数据库写入：面向 RAG 的输出层

0.32.1 一次性补齐了五大向量库的同步式写入连接器，共同语义是“把 Pathway 表作为单一事实源，增/改/删事件同步到目标集合”：

• pw.io.chroma.write：显式列映射——primary_key→记录 id（缺省用 Pathway 内部键）、embedding→向量、document→存储文本、metadata_columns→元数据；目标 collection 必须已存在。
• pw.io.qdrant.write：每次新增 upsert 一个 point、每次删除移除对应 point（更新即替换而非重复）；预建 collection 的 schema 驱动写入——每个命名向量槽绑定同名表列（稠密槽对 list[float]/一维 ndarray，稀疏槽对 (index, weight) 对列表），单点全部向量在一次 upsert 中原子写入，从而支持原生混合（dense + BM25）检索；缺失集合或槽/列不匹配时快速失败；batch_size 限制单请求点数，api_key 面向 Qdrant Cloud。
• pw.io.weaviate.write：以由必需 primary_key 派生的 UUID 为键做 upsert/删除，跨 worker 并行写（pathway spawn -n），batch_size/concurrency 调节吞吐。
• pw.io.pinecone.write：默认用表内部行键作 id（并行写），传 primary_key 则用自定义 id（必须唯一，冲突报错且退化为单 worker）；vector 列可为稠密（list[float]/一维 ndarray）或稀疏（(index, weight) 对），混合检索即同一张表两次 write() 喂两个索引、以相同记录 id 客户端融合。
• 上述连接器均要求目标集合/索引预先存在（DuckDB 除外，其写入文件级数据库），维度不匹配等错误在启动期即报出。

4.5 输出端 output_table_type 语义的普及

变更日志显示，stream_of_changes（追加所有事件并附 time/diff 元数据列）与 snapshot（用 primary_key 维护当前状态）这一对输出语义从 PostgreSQL（0.26.4 起 pw.io.postgres.write_snapshot 废弃并入 output_table_type）逐步推广到 MongoDB（0.29.1）、MySQL（0.26.4）、SQLite（0.31.0）与 ClickHouse（0.31.1），形成了跨数据库的一致心智模型，这也是阅读各版本条目时识别输出连接器能力的关键参数。

五、数据持久化与投递保证：变更日志中反复出现的主线

持久化（persistence）相关的条目在 CHANGELOG.md 中分布最广，反映其是 Pathway 的持续加固方向：

1. 持久化后端扩展：0.15.2 起元数据与流存储统一为单后端（pw.persistence.Config 取代 simple_config），0.22.0 增加 Azure Blob 后端，0.23.0 起所有云后端操作自动重试，0.26.2 起对 S3/Azure 后端把后台算子快照压缩频率限制在 snapshot_interval 与 30 分钟中的较大者，避免高频调用昂贵操作。
2. 恢复正确性修复：[Unreleased] 与 0.31.1 集中修复了一批“重启后丢输入”的边界——pw.iterate 内部快照曾写在无输出依赖的分支上，导致检查点可能先于写入提交而丢失最近输入；快速连续重启时检查点逻辑时间可能落回上一个被杀运行的区间，现在被钳制在当前运行自身的时间范围内；重启后各输入源恢复时统一到一个共享时间戳进入计算（显式 autocommit_duration_ms=None 时保留旧的按源行为）；OPERATOR_PERSISTING 模式下左键保持型 join（含 join_left）不再把重启后的行更新误报为重复键。
3. 至少一次语义闭环：[Unreleased] 的 MQTT/NATS 条目（见第二节）把“确认时机”与检查点对齐，是投递保证从“读侧不丢”扩展到“写侧确认不超前”的标志。
4. 资源侧配套：0.29.1 起 worker 可按负载自动伸缩（需启用持久化，经 worker_scaling_enabled 与 workload_tracking_window_ms 配置）；0.32.1 新增的 udf_cache_directory（见 pw.run 参数定义 与 engine.pyi）把非确定性 UDF 的记忆化缓存落盘到 SQLite 文件，内存占用不再随缓存结果数量增长——变更日志特别提示 /tmp 常是内存盘（tmpfs），应指向真实磁盘，且该缓存是运行时工作集而非持久化机制（重启后重建、关停时清理，持久化快照仍是事实源）。相关测试 覆盖了陈旧文件忽略、清理、多 worker 与多进程场景。

六、LLM 与 RAG xpack 的演进脉络

pw.xpacks.llm 的能力在变更日志中呈清晰的累积轨迹：

• 2024-01/02（0.7.10–0.8.3）：OpenAI Chat/Embedding 封装、LiteLLM/HuggingFace 聊天与 SentenceTransformers 嵌入封装、初代 VectorStore 向量索引管线（query_as_of_now 支持无限查询流下恒定内存）；0.8.3 为 pw.UDF 增加 return_type、deterministic、executor、cache_strategy 参数，并引入 LlamaIndex/LangChain 集成。
• 2024-05（0.11.0）：索引体系成型——pathway.stdlib.indexing 下提供 LSH 与 USearch 两种 k-NN、Tantivy BM25 全文索引、DataIndex 统一查询接口（返回 JoinResult 与 _pw_index_reply_score 评分列），以及 reranker 模块。
• 2024-09 起（0.15.0–0.16.x）：DocumentStore 取代 VectorStore 成为文档处理与索引主体（0.21.6 起 VectorStoreServer/Client 废弃并改为 DocumentStore/DocumentStoreClient），配套 QARestServer、SlidesDocumentStore、DeckRetriever。
• 2025-02（0.20.x–0.19.0）：DoclingParser（表格与图像解析、image_parsing_strategy、结构感知分块）、fully_async_executor + Future 数据类型 + Table.await_futures（结果可在未来处理时间返回的全异步 UDF）、sort_by 输出排序、pw.io.kafka/nats.write 支持按列动态指定 topic。
• 2025-06–07（0.24.1–0.25.1）：PathwayMcp 把 DocumentStore 与问答端点以 MCP（Model Context Protocol）工具形式对外提供。
• 2026-01（0.29.0）：Web Dashboard 上线（交互式图、延迟/内存指标）；原生 AWS Bedrock 集成（BedrockChat 走 Converse API，BedrockEmbedder 支持 Titan/Cohere）。
• 2026-04/07（0.30.1–0.32.1）：AudioParser（Whisper 转写）；TwelveLabsVideoParser 与 MarengoEmbedder 从 Video RAG 示例模板提升为原生 xpack 组件（pip install pathway[twelvelabs] 即可构建 Video RAG；解析器异步并发、支持 on_error="skip"、上传前拒绝超限视频，且要求具备 advanced-parser 权限的 license key）。
• 0.32.1 的 KNN 工厂修复值得注意：用 OpenAIEmbedder 构造 BruteForceKnnFactory/UsearchKnnFactory/LshKnnFactory 时不再向 OpenAI API 发探测请求（此前为学向量维度会嵌入 "."，导致建图需要网络且瞬时故障会中断整条管线）——已知模型维度取自查找表，未知模型才查询 embedder。

pyproject.toml 的 xpack-llm 额外依赖（OpenAI 2.x、LiteLLM、Cohere、LangChain、llama-index-core、fastmcp 等）与上述能力一一对应，可据此判断各 RAG 组件的最小依赖面。

七、破坏性变更（BREAKING）与迁移指引

变更日志中所有不兼容变更都带 BREAKING 标记并附迁移说明，以下按主题归集对升级者影响最大的一组（完整清单以 CHANGELOG.md 为准）：

API 重构类

• 0.4.0：ix/ix_ref 变为 pw.Table 上的独立变换，join/groupby 内部使用时可能需要显式上下文；
• 0.17.0：一次性移除大量弃用 API（pw.indexing 排序族、unsafe_promise_*、UDFSync/UDFAsync、连接器旧参数 value_columns/types 等），排序统一用 pw.Table.sort；
• 0.20.0：DoclingParser 的 parse_images 改为 image_parsing_strategy；
• 0.27.0：Iceberg 连接器 catalog 参数改为必填。

参数改名类

• [Unreleased]：pw.io.airbyte.read 的 refresh_interval_ms（毫秒）被 refresh_interval（秒数或 timedelta/pw.Duration，默认 60 秒）取代，传旧参数会报错并附换算值——迁移写法即 refresh_interval_ms=60000 → refresh_interval=60。同一节还把各连接器/xpack 的时长参数统一为“秒数或 timedelta”，新公共别名 pw.io.DurationLike 命名该类型，非法时长在调用期即报错；
• 0.13.0：pw.io.deltalake.write 的 path 改名为 uri；
• 0.17.0：连接器 persistent_id 改名为 name（日志与监控面板可见）。

行为/数据表示类

• 0.22.0：DateTimeUtc/DateTimeNaive 构造对时区信息的约束互斥化；表达式改为批量求值（更快但中间状态大时内存占用可能上升）；
• 0.25.0：pw.io.fs.read 移除 format="raw"（改用 binary/plaintext_by_file/plaintext），pw.io.s3_csv.read 移除（改用 pw.io.s3.read + format="csv"）；Elasticsearch 与 BigQuery 连接器移至 Scale 许可层；
• 0.26.0：多项持久化状态优化（小对象、大输入快照）被明确标注为需要重算持久化状态的破坏性变更；
• 0.30.0：MongoDB 连接器对 np.ndarray 改存保持形状的嵌套 BSON 数组（一维表示不变，多维不再扁平化）；
• 0.31.0：写 Glue catalog 不再接受 DateTimeUtc（Glue 元仓无时区感知时间戳，此前静默丢时区）——需转 DateTimeNaive（UTC 值）或改走 REST catalog；
• 0.21.0：CSV 序列化表示变更（Bytes 用 base64、Duration 用纳秒数、tuple/ndarray 用 JSON 表示）。

性能类（无破坏但值得知晓）：0.32.1 的 PostgreSQL 二进制 COPY、SQL Server INSERT BULK、MySQL 批量写入分别带来约 100 倍、25 倍量级的批量吞吐提升；0.32.1 [Unreleased] 的图构建提速（约 6 倍，小管线场景）不改变任何错误信息。

八、如何把这份 CHANGELOG 用进日常工作

1. 升级决策：先定位目标版本的 BREAKING 条目，与自己的连接器列表（pw.io.*）、持久化配置（pw.persistence）与 LLM 依赖（xpack-llm 系列 extra）交叉比对；0.26.0 与 0.22.0 的持久化状态重算类变更意味着需要丢弃旧状态重跑 backfill。
2. 故障排查：大量 Fixed 条目给出了“症状 → 版本”的倒查索引，例如“Elasticsearch _bulk 413/429”（0.32.1 起启动期读取集群 http.max_content_length 与 indexing_pressure.memory.limit 并自动拆分）、“Kafka static 模式读不到数据”（0.32.1）、“重启后 key missing/duplicate key”（0.31.1 持久化时间戳钳制）、“Airbyte venv 安装卡死”（0.32.1 起每次 pip 安装带超时重试且只装一次）。
3. 许可层核对：RabbitMQ Streams、Milvus 写、SharePoint、[Unreleased] 的 Pulsar 等均标注需要 Scale 或 Enterprise 许可层；Elasticsearch/BigQuery 自 0.25.0 起属 Scale 层——阅读条目时应把许可标注与自身部署形态对照。
4. 源码印证：变更日志条目与仓库实现一一对应，例如 MQTT 的 client_id 要求见 python/pathway/io/mqtt/init.py，NATS 的 ack_wait/max_ack_pending 说明见 python/pathway/io/nats/init.py，Pulsar 连接器见 python/pathway/io/pulsar/init.py，udf_cache_directory 的运行参数透传链见 python/pathway/internals/run.py。

九、小结

CHANGELOG.md 呈现的 Pathway 演进有三条清晰主线：其一，连接器从“能读”走向“读得全、写得快、停得稳”——输入侧统一快照+CDC/偏移恢复的增量模型，输出侧统一 stream_of_changes/snapshot 双语义，并以有界网络等待、批量写入协议、构造期参数校验系统性消除静默失败；其二，持久化与投递保证的持续收敛——检查点与确认时机对齐、重启恢复的边界情形逐一修复、缓存与伸缩的资源侧配套；其三，LLM/RAG xpack 从模型封装走向端到端——索引、文档解析（Docling/PaddleOCR/视频）、MCP 服务化与 Web Dashboard 构成完整闭环。对使用者而言，这份日志既是最可靠的升级检查单，也是最细粒度的故障倒查索引。