celestialflow 3.2.3__tar.gz → 3.2.5__tar.gz

{celestialflow-3.2.3 → celestialflow-3.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: celestialflow
-Version: 3.2.3
+Version: 3.2.5
 Summary: A flexible GRAPH-based task orchestration framework.
 Author-email: Mr-xiaotian <mingxiaomingtian@gmail.com>
 License: MIT
@@ -18,10 +18,7 @@ Requires-Dist: tqdm
 Requires-Dist: fastapi
 Requires-Dist: uvicorn
 Requires-Dist: requests
-Requires-Dist: networkx
-Requires-Dist: redis
 Requires-Dist: jinja2
-Requires-Dist: celestialtree>=0.1.3
 
 # CelestialFlow ——一个轻量级、可并行、基于图结构的 Python 任务调度框架
 
@@ -39,8 +36,8 @@ Requires-Dist: celestialtree>=0.1.3
 <p align="center">
   <img src="https://img.shields.io/badge/Task%20Graph-DAG-blueviolet">
   <img src="https://img.shields.io/badge/Workflow-Orchestrator-7c3aed">
-  <img src="https://img.shields.io/badge/IPC-Redis%20Ready-red">
-  <img src="https://img.shields.io/badge/Distributed-Worker%20Friendly-orange">
+  <img src="https://img.shields.io/badge/Event%20Tracing-CelestialTree-0ea5e9">
+  <img src="https://img.shields.io/badge/Web-Dashboard-FastAPI-ec4899">
 </p>
 
 <p align="center">
@@ -73,7 +70,7 @@ TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支
 
 在执行与调度之外，CelestialFlow 进一步引入 **CelestialTree（简称: ctree） 事件追踪系统**，为每一个任务及其衍生行为（成功、失败、重试、拆分、路由等）记录明确的因果关系。借助 ctree，可以从任意一个初始任务出发，完整还原其在 TaskGraph 中的传播路径与执行轨迹，使任务系统可以进行完整的**追溯、分析、解释**。
 
-在此基础上，CelestialFlow 支持 Web 可视化监控，并可通过 Redis 实现跨进程、跨设备协作；同时引入基于 Go 的外部 worker（通过 Redis 通信），用于承载 CPU 密集型任务，弥补 Python 在该场景下的性能瓶颈。
+在此基础上，CelestialFlow 支持 Web 可视化监控，并提供基于 Redis 的 demo 与 Go Worker 外部协作示例，用于展示按需构建跨进程、跨设备任务协作的方式。
 
 ## 项目结构（Project Structure）
 
@@ -136,6 +133,18 @@ uv pip install celestialflow
 pip install celestialflow
 ```
 
+如果你只使用 CelestialFlow 的核心调度、Web、持久化与 demo/test 之外的常规功能，上面的安装已经足够。
+
+如果你还需要启用 CelestialTree 事件追踪能力，则需要**额外安装** `celestialtree`：
+
+```bash
+# 对已发布包使用者
+uv pip install celestialtree
+
+# 如果你是 clone 仓库后的开发者/贡献者
+uv sync --group dev
+```
+
 一个简单的可运行代码:
 
 ```python
@@ -215,7 +224,7 @@ flowchart TD
 - [runtime/util_hash.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_hash.md)
 - [runtime/util_types.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_types.md)
 - [runtime/util_errors.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_errors.md)
-- [persistence/core_fail.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fail.md)
+- [persistence/core_fallback.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fallback.md)
 - [persistence/core_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_log.md)
 
 如果你更喜欢通过完整案例理解框架的运行方式，可以参考这篇利用 TaskGraph 从零开始构建项目的教程：
@@ -228,20 +237,20 @@ flowchart TD
 
 你可以继续运行更多的演示代码，这里记录了各个演示文件与其中的演示函数说明：
 
-[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/demo)
+[🎮demo/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/demo/README.md)
 
-​如果你想运行测试代码, 可以先查看如下文档内容:
+如果你想运行测试代码，可以先查看如下文档内容：
 
-[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/tests)
+[🧪tests/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/tests/README.md)
 
-如果你想查看bench内容, 这里的数据成为框架中部分设计的决策依据:
+如果你想查看 bench 内容，这些数据也是框架中部分设计取舍的依据：
 
-[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/bench)
+[⚡bench/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/bench/README.md)
 
 ## 环境要求（Requirements）
 
-**CelestialFlow** 基于 Python 3.12+，并依赖以下核心组件。
-请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
+**CelestialFlow** 基于 Python 3.12+，默认运行时依赖以下核心组件。
+其中 `celestialtree` 不再属于默认运行时依赖，而是额外安装的可选组件。
 
 | 依赖包           | 说明 |
 | ----------------- | ---- |
@@ -249,76 +258,44 @@ flowchart TD
 | **fastapi**       | Web 服务接口框架（用于任务可视化与远程控制） |
 | **uvicorn**       | FastAPI 的高性能 ASGI 服务器 |
 | **requests**      | HTTP 客户端库，用于任务状态上报与远程调用 |
-| **networkx**      | 任务图（TaskGraph）结构与依赖分析 |
 | **jinja2**        | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
 | **tqdm**          | 可选组件，进度条显示，用于任务执行可视化 |
-| **redis**         | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
-| **celestialtree** | 可选组件，用于任务状态上报与远程调用（`ctree_client`） |
+
+如需运行 `demo/demo_redis.py` 或 Go Worker 示例，请额外安装 `redis` 并准备 Redis 服务；这部分不属于默认运行时依赖。
+
+如需运行依赖 CelestialTree 的 demo / bench / 追踪查询，请额外安装 `celestialtree`，或直接在源码仓库中执行 `uv sync --group dev`。
 
 ## 文件结构（File Structure）
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Mr-xiaotian/CelestialFlow/main/img/file_structure.svg" alt="FileStructure" />
   <br/>
-  <em>celestial-flow 3.2.3</em>
+  <em>celestial-flow 3.2.5</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.3
+- 3.2.5
   - feat:
-    - **[IMPORTANT]** 前端仪表盘设置面板中新添 `节点等待使用全局估计` 开关, 开启后节点卡片中原 `等待` 量将被替换为 `全局等待`, 并在卡片中显示 `全局剩余时间`
-      - 这个功能非常有趣, 开启前后能看到数值大幅波动
-    - **[IMPORTANT]** 重写任务注入页面, 现在实用性远远高于之前版本
-      - 可以给每个节点单独配置注入任务列表, 在一起发送
-    - **[IMPORTANT]** 移除 `TaskExecutor` 中 `get_args` 与 `process_result` 两个方法, 以及 `unpack_task_args` 属性
-      - 这是为引入泛型必要的修改
-      - `process_result` 功能很简单, 对func输出的result进行再次处理, 但事实上在输入func前对齐进行包装也能达到一样的效果
-      - `get_args` 功能更为复杂, 可以直接将前一节点提供的 `result` 转为当前节点所需的 `task` 类型, 非常灵活; 但问题在于太过灵活, 导致使用心智负担很大
-      - `unpack_task_args` 就是 `get_args` 带来的一项心智负担, 默认 `get_args` 会把 `task` 进行 `(task, )` 包裹后发送给func, 开启 `unpack_task_args` 后则直接发送
-    - **[IMPORTANT]** `graph` 的init参数中添加 `name`, 以与 `executor` `stage` 一致
-      - 破坏接口破坏性更新
-      - 在日志的 `start_graph` `end_graph` 与web端的 `graph_anaylysis` 中都有显示
-    - 彻底移除前后端通信中的 `graph_summary` , 原本残余的 `全局剩余时间` 现在拆为各个节点的 `全局等待` 与 `全局剩余时间`
-      - 这里所说的 `全局` 意为根据图论关系, 由上游剩余的任务数估算下游总共能获得多少任务
-      - 例如: 图关系 `A -> B`, A已处理任务2, 未处理任务3, B已处理任务4, 未处理任务2. 这意味着A成功的2个任务为B带来总共了6个任务, 那么我们可以据此估计B总功能获取"3/2*6=9"个任务, 因此B的 `等待` 任务数量为2, 但 `全局等待` 任务数量为5
-    - 前端中添加部分提示气泡, 鼠标放上去后可以介绍相关信息, 例如本次新加入的节点 `全局等待` 的含义
-    - 移除前端中节点卡片的拖拽功能
-      - 这个功能是在最早加入web页面时添加的, 当时感觉很帅, 但现在有点玩腻了
-    - 前端错误日志页面添加 `任务注入` 按钮, 可以把选定任务直接添加到任务注入页面中节点的代注入任务列表中
-    - 在 `TaskSplitter` 中添加 `split_item` 方法, 可自由定义
-      - 原本的 `splitter` 非常依赖于 `get_args`, 现在通过 `split_item` 方法稍微弥补其缺失的灵活性
+    - 在 `Spout` 和 `Inlet` 中 添加 `counter`, 对 `queue` 中未消费任务的数量进行记录
+      - 在上版本大幅修改 `fallback` 机制后, `FallbackSpout` 中很有可能出现任务堆积, 进而导致误判
+    - 在web端错误日志页面对当前显示的错误数量可能与node_status中的error数量不一致的情况进行说明
+    - 在web端仪表盘页面添加错误分类的饼图
   - refactor:
-    - **[IMPORTANT]** 引入泛型, 同时强制性要求py版本>=3.12
-      - 泛型的引入使得代码更加类型安全, 同时也提高了代码的可读性
-      - 3.12版本对泛型的表述非常直观
-    - 移除前端代码中所有对 `localStorage` 的使用
-      - 在已经有config配置文件的情况下意义不大, 反而会带来困扰
-    - 将任务队列的drain操作从graph层移至stage层
-      - 之前不能这样做是因为节点的 `stage_mode` 可能为 `process`, 此时在主进程持有的节点非真实运行的节点
-      - 算是3.2.0版本带来的持久影响之一
-    - 优化 `TaskMetric` 中对锁的使用
-    - 移除 `TaskEnvelope` 中的 `change_id()` 方法, 现在默认envelope不可变, 同时 `emit_retry_envelope` 中不再把原有的envelope的id修改后继续提交给worker, 而是直接使用新生成的envelope
-    - 移除错误日志中的 `error` `error_repr` `task_repr` 字段
-    - 修改前后端通信中任务注入数据的格式, 以方便同时提交多个节点的任务数据
-    - 前端代码中开启strict检查
-    - 将前端中 `injection.css` 文件拆分成多个文件
-    - 修改 `config.json` 的数据格式, 现在按照生效区域进行分类
-    - 收紧前端中的数据类型
-    - 添加 `ReportTaskGraph` 类型, 专门用于给reporter做类型声明
+    - 移除对 `networkx` 的依赖, 添加 `util_graph`, 实现所有图论分析
+    - `TaskExecutor` 中将 `enable_duplicate_check` 默认改为 `False`
+      - 在duplicate机制中一直有一个内存持续增长点: `processed_set`, 这导致 `enable_duplicate_check` 在大规模的任务下会导致很大的内存压力
+    - 分离server端的 `push_task` 和 `push_termination`
   - fix:
-    - i18n本地化在部分字段上失效的问题
-    - 直接点击仪表盘中错误数字跳转到错误日志页后, 设置面板显示的还是仪表盘页面的设置
-    - 前端中为各项仪表盘请求添加 `RequestSeq`, 以避免前后发送两个请求, 但因为延迟关系, 先发送的请求的返回覆盖掉后发送请求的返回
-    - 修复前端中各项空字段需要在第一次refresh才显示的问题, 体感上会导致"加载"很慢
+    - 修复 `UnconsumedError` 在 `drain_task_queue` 中被计算两次的问题
   - chore:
-    - 将文档更新翻译为英/日两语
-      - 这项操作太耗token了
+    - `img/` 中添加全新的 `web_display.png` 图片
+    - 完善几个skill, 现在对主agent与子agent的prompt进行分离
 
 更多过往日志可看:
 
-[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md )
+[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md)
 
 ## Star 历史趋势（Star History）
 
@@ -327,7 +304,7 @@ flowchart TD
 ![Star History Chart](https://api.star-history.com/svg?repos=Mr-xiaotian/CelestialFlow&type=Date)
 
 ## 许可（License）
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/LICENSE) file for details.
 
 ## 作者（Author）
 Author: Mr-xiaotian

{celestialflow-3.2.3 → celestialflow-3.2.5}/README.md

@@ -14,8 +14,8 @@
 <p align="center">
   <img src="https://img.shields.io/badge/Task%20Graph-DAG-blueviolet">
   <img src="https://img.shields.io/badge/Workflow-Orchestrator-7c3aed">
-  <img src="https://img.shields.io/badge/IPC-Redis%20Ready-red">
-  <img src="https://img.shields.io/badge/Distributed-Worker%20Friendly-orange">
+  <img src="https://img.shields.io/badge/Event%20Tracing-CelestialTree-0ea5e9">
+  <img src="https://img.shields.io/badge/Web-Dashboard-FastAPI-ec4899">
 </p>
 
 <p align="center">
@@ -48,7 +48,7 @@ TaskGraph 能构建完整的 **有向图结构（Directed Graph）**，不仅支
 
 在执行与调度之外，CelestialFlow 进一步引入 **CelestialTree（简称: ctree） 事件追踪系统**，为每一个任务及其衍生行为（成功、失败、重试、拆分、路由等）记录明确的因果关系。借助 ctree，可以从任意一个初始任务出发，完整还原其在 TaskGraph 中的传播路径与执行轨迹，使任务系统可以进行完整的**追溯、分析、解释**。
 
-在此基础上，CelestialFlow 支持 Web 可视化监控，并可通过 Redis 实现跨进程、跨设备协作；同时引入基于 Go 的外部 worker（通过 Redis 通信），用于承载 CPU 密集型任务，弥补 Python 在该场景下的性能瓶颈。
+在此基础上，CelestialFlow 支持 Web 可视化监控，并提供基于 Redis 的 demo 与 Go Worker 外部协作示例，用于展示按需构建跨进程、跨设备任务协作的方式。
 
 ## 项目结构（Project Structure）
 
@@ -111,6 +111,18 @@ uv pip install celestialflow
 pip install celestialflow
 ```
 
+如果你只使用 CelestialFlow 的核心调度、Web、持久化与 demo/test 之外的常规功能，上面的安装已经足够。
+
+如果你还需要启用 CelestialTree 事件追踪能力，则需要**额外安装** `celestialtree`：
+
+```bash
+# 对已发布包使用者
+uv pip install celestialtree
+
+# 如果你是 clone 仓库后的开发者/贡献者
+uv sync --group dev
+```
+
 一个简单的可运行代码:
 
 ```python
@@ -190,7 +202,7 @@ flowchart TD
 - [runtime/util_hash.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_hash.md)
 - [runtime/util_types.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_types.md)
 - [runtime/util_errors.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/runtime/util_errors.md)
-- [persistence/core_fail.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fail.md)
+- [persistence/core_fallback.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_fallback.md)
 - [persistence/core_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/src/persistence/core_log.md)
 
 如果你更喜欢通过完整案例理解框架的运行方式，可以参考这篇利用 TaskGraph 从零开始构建项目的教程：
@@ -203,20 +215,20 @@ flowchart TD
 
 你可以继续运行更多的演示代码，这里记录了各个演示文件与其中的演示函数说明：
 
-[🎮demo/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/demo)
+[🎮demo/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/demo/README.md)
 
-​如果你想运行测试代码, 可以先查看如下文档内容:
+如果你想运行测试代码，可以先查看如下文档内容：
 
-[🧪tests/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/tests)
+[🧪tests/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/tests/README.md)
 
-如果你想查看bench内容, 这里的数据成为框架中部分设计的决策依据:
+如果你想查看 bench 内容，这些数据也是框架中部分设计取舍的依据：
 
-[⚡bench/](https://github.com/Mr-xiaotian/CelestialFlow/tree/main/docs/zh-CN/bench)
+[⚡bench/ 总览](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/bench/README.md)
 
 ## 环境要求（Requirements）
 
-**CelestialFlow** 基于 Python 3.12+，并依赖以下核心组件。
-请确保你的环境能够正常安装这些依赖（`pip install celestialflow` 会自动安装）。
+**CelestialFlow** 基于 Python 3.12+，默认运行时依赖以下核心组件。
+其中 `celestialtree` 不再属于默认运行时依赖，而是额外安装的可选组件。
 
 | 依赖包           | 说明 |
 | ----------------- | ---- |
@@ -224,76 +236,44 @@ flowchart TD
 | **fastapi**       | Web 服务接口框架（用于任务可视化与远程控制） |
 | **uvicorn**       | FastAPI 的高性能 ASGI 服务器 |
 | **requests**      | HTTP 客户端库，用于任务状态上报与远程调用 |
-| **networkx**      | 任务图（TaskGraph）结构与依赖分析 |
 | **jinja2**        | FastAPI 模板引擎，用于 Web 可视化界面渲染 |
 | **tqdm**          | 可选组件，进度条显示，用于任务执行可视化 |
-| **redis**         | 可选组件，用于分布式任务通信（`TaskRedis*` 系列模块） |
-| **celestialtree** | 可选组件，用于任务状态上报与远程调用（`ctree_client`） |
+
+如需运行 `demo/demo_redis.py` 或 Go Worker 示例，请额外安装 `redis` 并准备 Redis 服务；这部分不属于默认运行时依赖。
+
+如需运行依赖 CelestialTree 的 demo / bench / 追踪查询，请额外安装 `celestialtree`，或直接在源码仓库中执行 `uv sync --group dev`。
 
 ## 文件结构（File Structure）
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Mr-xiaotian/CelestialFlow/main/img/file_structure.svg" alt="FileStructure" />
   <br/>
-  <em>celestial-flow 3.2.3</em>
+  <em>celestial-flow 3.2.5</em>
 </p>
 
 (该视图由我的另一个项目[CelestialVault](https://github.com/Mr-xiaotian/CelestialVault)中inst_file.FileTree.print_tree()生成。转换为图片则借助[Carbon](https://carbon.now.sh)。)
 
 ## 版本日志（Version Log）
-- 3.2.3
+- 3.2.5
   - feat:
-    - **[IMPORTANT]** 前端仪表盘设置面板中新添 `节点等待使用全局估计` 开关, 开启后节点卡片中原 `等待` 量将被替换为 `全局等待`, 并在卡片中显示 `全局剩余时间`
-      - 这个功能非常有趣, 开启前后能看到数值大幅波动
-    - **[IMPORTANT]** 重写任务注入页面, 现在实用性远远高于之前版本
-      - 可以给每个节点单独配置注入任务列表, 在一起发送
-    - **[IMPORTANT]** 移除 `TaskExecutor` 中 `get_args` 与 `process_result` 两个方法, 以及 `unpack_task_args` 属性
-      - 这是为引入泛型必要的修改
-      - `process_result` 功能很简单, 对func输出的result进行再次处理, 但事实上在输入func前对齐进行包装也能达到一样的效果
-      - `get_args` 功能更为复杂, 可以直接将前一节点提供的 `result` 转为当前节点所需的 `task` 类型, 非常灵活; 但问题在于太过灵活, 导致使用心智负担很大
-      - `unpack_task_args` 就是 `get_args` 带来的一项心智负担, 默认 `get_args` 会把 `task` 进行 `(task, )` 包裹后发送给func, 开启 `unpack_task_args` 后则直接发送
-    - **[IMPORTANT]** `graph` 的init参数中添加 `name`, 以与 `executor` `stage` 一致
-      - 破坏接口破坏性更新
-      - 在日志的 `start_graph` `end_graph` 与web端的 `graph_anaylysis` 中都有显示
-    - 彻底移除前后端通信中的 `graph_summary` , 原本残余的 `全局剩余时间` 现在拆为各个节点的 `全局等待` 与 `全局剩余时间`
-      - 这里所说的 `全局` 意为根据图论关系, 由上游剩余的任务数估算下游总共能获得多少任务
-      - 例如: 图关系 `A -> B`, A已处理任务2, 未处理任务3, B已处理任务4, 未处理任务2. 这意味着A成功的2个任务为B带来总共了6个任务, 那么我们可以据此估计B总功能获取"3/2*6=9"个任务, 因此B的 `等待` 任务数量为2, 但 `全局等待` 任务数量为5
-    - 前端中添加部分提示气泡, 鼠标放上去后可以介绍相关信息, 例如本次新加入的节点 `全局等待` 的含义
-    - 移除前端中节点卡片的拖拽功能
-      - 这个功能是在最早加入web页面时添加的, 当时感觉很帅, 但现在有点玩腻了
-    - 前端错误日志页面添加 `任务注入` 按钮, 可以把选定任务直接添加到任务注入页面中节点的代注入任务列表中
-    - 在 `TaskSplitter` 中添加 `split_item` 方法, 可自由定义
-      - 原本的 `splitter` 非常依赖于 `get_args`, 现在通过 `split_item` 方法稍微弥补其缺失的灵活性
+    - 在 `Spout` 和 `Inlet` 中 添加 `counter`, 对 `queue` 中未消费任务的数量进行记录
+      - 在上版本大幅修改 `fallback` 机制后, `FallbackSpout` 中很有可能出现任务堆积, 进而导致误判
+    - 在web端错误日志页面对当前显示的错误数量可能与node_status中的error数量不一致的情况进行说明
+    - 在web端仪表盘页面添加错误分类的饼图
   - refactor:
-    - **[IMPORTANT]** 引入泛型, 同时强制性要求py版本>=3.12
-      - 泛型的引入使得代码更加类型安全, 同时也提高了代码的可读性
-      - 3.12版本对泛型的表述非常直观
-    - 移除前端代码中所有对 `localStorage` 的使用
-      - 在已经有config配置文件的情况下意义不大, 反而会带来困扰
-    - 将任务队列的drain操作从graph层移至stage层
-      - 之前不能这样做是因为节点的 `stage_mode` 可能为 `process`, 此时在主进程持有的节点非真实运行的节点
-      - 算是3.2.0版本带来的持久影响之一
-    - 优化 `TaskMetric` 中对锁的使用
-    - 移除 `TaskEnvelope` 中的 `change_id()` 方法, 现在默认envelope不可变, 同时 `emit_retry_envelope` 中不再把原有的envelope的id修改后继续提交给worker, 而是直接使用新生成的envelope
-    - 移除错误日志中的 `error` `error_repr` `task_repr` 字段
-    - 修改前后端通信中任务注入数据的格式, 以方便同时提交多个节点的任务数据
-    - 前端代码中开启strict检查
-    - 将前端中 `injection.css` 文件拆分成多个文件
-    - 修改 `config.json` 的数据格式, 现在按照生效区域进行分类
-    - 收紧前端中的数据类型
-    - 添加 `ReportTaskGraph` 类型, 专门用于给reporter做类型声明
+    - 移除对 `networkx` 的依赖, 添加 `util_graph`, 实现所有图论分析
+    - `TaskExecutor` 中将 `enable_duplicate_check` 默认改为 `False`
+      - 在duplicate机制中一直有一个内存持续增长点: `processed_set`, 这导致 `enable_duplicate_check` 在大规模的任务下会导致很大的内存压力
+    - 分离server端的 `push_task` 和 `push_termination`
   - fix:
-    - i18n本地化在部分字段上失效的问题
-    - 直接点击仪表盘中错误数字跳转到错误日志页后, 设置面板显示的还是仪表盘页面的设置
-    - 前端中为各项仪表盘请求添加 `RequestSeq`, 以避免前后发送两个请求, 但因为延迟关系, 先发送的请求的返回覆盖掉后发送请求的返回
-    - 修复前端中各项空字段需要在第一次refresh才显示的问题, 体感上会导致"加载"很慢
+    - 修复 `UnconsumedError` 在 `drain_task_queue` 中被计算两次的问题
   - chore:
-    - 将文档更新翻译为英/日两语
-      - 这项操作太耗token了
+    - `img/` 中添加全新的 `web_display.png` 图片
+    - 完善几个skill, 现在对主agent与子agent的prompt进行分离
 
 更多过往日志可看:
 
-[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md )
+[change_log.md](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/docs/zh-CN/change_log.md)
 
 ## Star 历史趋势（Star History）
 
@@ -302,7 +282,7 @@ flowchart TD
 ![Star History Chart](https://api.star-history.com/svg?repos=Mr-xiaotian/CelestialFlow&type=Date)
 
 ## 许可（License）
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/Mr-xiaotian/CelestialFlow/blob/main/LICENSE) file for details.
 
 ## 作者（Author）
 Author: Mr-xiaotian

{celestialflow-3.2.3 → celestialflow-3.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "celestialflow"
-version = "3.2.3"
+version = "3.2.5"
 description = "A flexible GRAPH-based task orchestration framework."
 readme = "README.md"
 license = { text = "MIT" }
@@ -17,10 +17,7 @@ dependencies = [
     "fastapi",
     "uvicorn",
     "requests",
-    "networkx",
-    "redis",
     "jinja2",
-    "celestialtree>=0.1.3",
 ]
 
 classifiers = [
@@ -72,6 +69,8 @@ dev = [
     "python-dotenv>=1.2.2",
     "ruff>=0.15.0",
     "pyright>=1.1.409",
+    "redis",
+    "celestialtree>=0.1.3",
 ]
 
 [tool.pyright]

{celestialflow-3.2.3 → celestialflow-3.2.5}/src/celestialflow/__init__.py

@@ -4,6 +4,7 @@
 提供任务图构建、执行调度、实时监控、Web 可视化和持久化等核心能力。
 """
 
+from .funnel import BaseInlet, BaseSpout
 from .graph import (
     TaskChain,
     TaskComplete,
@@ -13,19 +14,16 @@ from .graph import (
     TaskLoop,
     TaskWheel,
 )
-from .observability import BaseObserver, CallbackObserver, TaskProgress
-from .persistence.util_jsonl import (
-    load_jsonl_logs,
-    load_task_by_error,
-    load_task_by_stage,
+from .observability import BaseObserver, TaskProgress
+from .persistence.util_sqlite import (
+    load_records,
+    load_records_grouped_by_stage,
+    load_tasks_grouped_by_stage,
 )
 from .runtime.util_hash import make_hashable
 from .runtime.util_types import TerminationSignal
 from .stage import (
     TaskExecutor,
-    TaskRedisAck,
-    TaskRedisSource,
-    TaskRedisTransport,
     TaskRouter,
     TaskSplitter,
     TaskStage,
@@ -35,8 +33,9 @@ from .utils.util_format import format_table
 from .web import TaskWebServer
 
 __all__ = [
+    "BaseInlet",
     "BaseObserver",
-    "CallbackObserver",
+    "BaseSpout",
     "TaskChain",
     "TaskComplete",
     "TaskCross",
@@ -45,9 +44,6 @@ __all__ = [
     "TaskGrid",
     "TaskLoop",
     "TaskProgress",
-    "TaskRedisAck",
-    "TaskRedisSource",
-    "TaskRedisTransport",
     "TaskRouter",
     "TaskSplitter",
     "TaskStage",
@@ -57,8 +53,8 @@ __all__ = [
     "benchmark_executor",
     "benchmark_graph",
     "format_table",
-    "load_jsonl_logs",
-    "load_task_by_error",
-    "load_task_by_stage",
+    "load_records",
+    "load_records_grouped_by_stage",
+    "load_tasks_grouped_by_stage",
     "make_hashable",
 ]

celestialflow-3.2.5/src/celestialflow/funnel/core_inlet.py

@@ -0,0 +1,48 @@
+# funnel/core_inlet.py
+from __future__ import annotations
+
+from queue import Queue
+from typing import TYPE_CHECKING, Any, Self
+
+from ..runtime.util_errors import InitializationError
+from .util_count import PendingCounter
+
+if TYPE_CHECKING:
+    from .core_spout import BaseSpout
+
+
+class BaseInlet:
+    """数据收集器基类，负责将记录通过队列发送到对应的监听器。"""
+
+    _queue: Queue[Any]
+    _counter: PendingCounter
+
+    def bind_spout(self, spout: BaseSpout) -> Self:
+        """
+        将当前 inlet 绑定到给定 spout。
+
+        :param spout: 目标监听器
+        :return: 当前已绑定的 inlet 实例
+        :rtype: Self
+        """
+        self._queue = spout.get_queue()
+        self._counter = spout.get_counter()
+        return self
+
+    def _funnel(self, record: Any) -> None:
+        """
+        将记录放入队列。
+
+        :param record: 待发送的记录
+        :return: ``None``
+        """
+        if not hasattr(self, '_queue') or not hasattr(self, '_counter'):
+            raise InitializationError("inlet is not bound to spout")
+
+        # 先增加待处理数量，再入队；若入队失败则立即回滚计数。
+        self._counter.increment()
+        try:
+            self._queue.put(record)
+        except Exception:
+            self._counter.decrement()
+            raise

{celestialflow-3.2.3 → celestialflow-3.2.5}/src/celestialflow/funnel/core_spout.py

@@ -8,31 +8,19 @@ from typing import Any
 
 from ..runtime.util_errors import CelestialFlowError
 from ..runtime.util_types import TERMINATION_SIGNAL, TerminationSignal
+from .util_count import PendingCounter
 
 
 class BaseSpout:
     """数据监听器基类，在独立后台线程中消费队列记录。"""
 
     def __init__(self) -> None:
-        """初始化监听器及其内部队列和线程引用。"""
-        self.queue: Queue[Any] = Queue()
+        """初始化监听器及其内部队列、待处理计数器和线程引用。"""
+        self._queue: Queue[Any] = Queue()
+        self._counter = PendingCounter()
         self._thread: Thread | None = None
 
-    def _before_start(self) -> None:
-        """在后台线程启动前调用，子类可覆写以做初始化（如打开文件、清空缓存）。"""
-        return None
-
-    def _handle_record(self, _record: Any) -> None:
-        """
-        处理单条队列记录，子类必须覆写。
-
-        :param _record: 队列中取出的记录
-        """
-        raise CelestialFlowError("_handle_record must be implemented by subclasses")
-
-    def _after_stop(self) -> None:
-        """在后台线程停止后调用，子类可覆写以做清理（如关闭文件句柄）。"""
-        return None
+    # ==== 外部调用函数 ====
 
     def start(self) -> None:
         """启动后台监听线程（若未运行）。"""
@@ -42,30 +30,77 @@ class BaseSpout:
             self._thread.start()
 
     def _spout(self) -> None:
-        """后台线程主循环，持续从队列拉取记录并调用 _handle_record，收到终止信号时退出。"""
+        """
+        后台线程主循环。
+
+        持续从队列拉取记录并调用 ``_handle_record()``，收到终止信号时退出。
+        待处理数量在记录处理完成后递减，因此统计口径包含“已出队但仍在处理”的记录。
+        """
         while True:
             try:
-                record = self.queue.get(timeout=0.5)
-                if isinstance(record, TerminationSignal):
-                    break
-                self._handle_record(record)
+                record = self._queue.get(timeout=0.5)
             except Empty:
                 continue
+
+            if isinstance(record, TerminationSignal):
+                break
+
+            try:
+                self._handle_record(record)
             except Exception:
-                # 单条记录处理失败不致死线程
+                # 单条记录处理失败不致死线程。
                 traceback.print_exc()
-
-    def get_queue(self) -> Queue[Any]:
-        """获取监听器的输入队列。"""
-        return self.queue
+            finally:
+                self._counter.decrement()
 
     def stop(self) -> None:
         """发送终止信号并等待后台线程结束。"""
         if self._thread is None:
             return
 
-        self.queue.put(TERMINATION_SIGNAL)
+        self._queue.put(TERMINATION_SIGNAL)
         if self._thread.is_alive():
             self._thread.join(timeout=5)
+
         self._thread = None
         self._after_stop()
+
+    def get_queue(self) -> Queue[Any]:
+        """获取监听器的输入队列。"""
+        return self._queue
+
+    def get_counter(self) -> PendingCounter:
+        """
+        获取与当前监听器绑定的待处理计数器。
+
+        :return: 待处理计数器
+        :rtype: PendingCounter
+        """
+        return self._counter
+
+    def get_pending_count(self) -> int:
+        """
+        读取当前仍未处理完成的记录数量。
+
+        :return: 当前待处理数量
+        :rtype: int
+        """
+        return self._counter.get_count()
+
+    # ==== 生命周期回调 ====
+
+    def _before_start(self) -> None:
+        """在后台线程启动前调用，子类可覆写以做初始化（如打开文件、清空缓存）。"""
+        return None
+
+    def _handle_record(self, _record: Any) -> None:
+        """
+        处理单条队列记录，子类必须覆写。
+
+        :param _record: 队列中取出的记录
+        """
+        raise CelestialFlowError("_handle_record must be implemented by subclasses")
+
+    def _after_stop(self) -> None:
+        """在后台线程停止后调用，子类可覆写以做清理（如关闭文件句柄）。"""
+        return None