tasklite-engine 2.2.1__tar.gz → 3.0.0.dev0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tasklite_engine-3.0.0.dev0/PKG-INFO +307 -0
- tasklite_engine-3.0.0.dev0/README.md +276 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/pyproject.toml +1 -1
- tasklite_engine-3.0.0.dev0/tasklite/__init__.py +53 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/backend/__init__.py +2 -5
- tasklite_engine-3.0.0.dev0/tasklite/backend/base.py +363 -0
- tasklite_engine-3.0.0.dev0/tasklite/backend/memory.py +689 -0
- tasklite_engine-3.0.0.dev0/tasklite/backend/sqlite_backend.py +1154 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/engine/__init__.py +2 -2
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/engine/admission.py +77 -39
- tasklite_engine-3.0.0.dev0/tasklite/engine/channel.py +1021 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/completion.py +760 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/config.py +77 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/dispatch.py +701 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/execution_access.py +39 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/files.py +52 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/engine/governor.py +40 -203
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/engine/in_flight.py +15 -13
- tasklite_engine-3.0.0.dev0/tasklite/engine/ops.py +25 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/recovery.py +147 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/resource.py +523 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/runtime.py +917 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/engine/scheduler.py +99 -90
- tasklite_engine-3.0.0.dev0/tasklite/engine/selection.py +186 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/session.py +96 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/store.py +975 -0
- tasklite_engine-3.0.0.dev0/tasklite/engine/types.py +144 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/engine/wait.py +30 -16
- tasklite_engine-3.0.0.dev0/tasklite/exceptions.py +21 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/hooks.py +3 -23
- tasklite_engine-3.0.0.dev0/tasklite/models/__init__.py +26 -0
- tasklite_engine-3.0.0.dev0/tasklite/models/artifact.py +419 -0
- tasklite_engine-3.0.0.dev0/tasklite/models/context.py +230 -0
- tasklite_engine-3.0.0.dev0/tasklite/models/job.py +266 -0
- tasklite_engine-3.0.0.dev0/tasklite/models/result.py +246 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/models/state.py +97 -17
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/models/task.py +52 -105
- tasklite_engine-3.0.0.dev0/tasklite/pipeline.py +454 -0
- tasklite_engine-3.0.0.dev0/tasklite/resource.py +12 -0
- tasklite_engine-3.0.0.dev0/tasklite/selection.py +28 -0
- tasklite_engine-3.0.0.dev0/tasklite/snapshot.py +639 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/testing.py +32 -34
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/triggers.py +5 -4
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/utils/artifact.py +85 -17
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/utils/clock.py +3 -3
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/utils/encoding.py +113 -18
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/utils/ipc.py +240 -242
- tasklite_engine-3.0.0.dev0/tasklite/utils/lockfile.py +96 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/wrappers/__init__.py +1 -1
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/wrappers/discovery.py +154 -157
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/wrappers/http.py +68 -481
- tasklite_engine-3.0.0.dev0/tasklite_engine.egg-info/PKG-INFO +307 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite_engine.egg-info/SOURCES.txt +8 -2
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite_engine.egg-info/requires.txt +3 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tests/test_encoding.py +149 -47
- tasklite_engine-3.0.0.dev0/tests/test_exception_contract.py +155 -0
- tasklite_engine-3.0.0.dev0/tests/test_exceptions.py +86 -0
- tasklite_engine-3.0.0.dev0/tests/test_hooks.py +67 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tests/test_package_surface.py +158 -23
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tests/test_packaging.py +6 -4
- tasklite_engine-3.0.0.dev0/tests/test_payload_intake.py +81 -0
- tasklite_engine-3.0.0.dev0/tests/test_pipeline.py +1186 -0
- tasklite_engine-3.0.0.dev0/tests/test_result_metadata.py +87 -0
- tasklite_engine-3.0.0.dev0/tests/test_testing.py +217 -0
- tasklite_engine-3.0.0.dev0/tests/test_trigger_contract.py +316 -0
- tasklite_engine-2.2.1/PKG-INFO +0 -370
- tasklite_engine-2.2.1/README.md +0 -340
- tasklite_engine-2.2.1/tasklite/__init__.py +0 -219
- tasklite_engine-2.2.1/tasklite/backend/base.py +0 -391
- tasklite_engine-2.2.1/tasklite/backend/memory.py +0 -452
- tasklite_engine-2.2.1/tasklite/backend/sqlite_backend.py +0 -882
- tasklite_engine-2.2.1/tasklite/engine/channel.py +0 -913
- tasklite_engine-2.2.1/tasklite/engine/completion.py +0 -473
- tasklite_engine-2.2.1/tasklite/engine/config.py +0 -201
- tasklite_engine-2.2.1/tasklite/engine/dispatch.py +0 -612
- tasklite_engine-2.2.1/tasklite/engine/errorclass.py +0 -971
- tasklite_engine-2.2.1/tasklite/engine/ops.py +0 -363
- tasklite_engine-2.2.1/tasklite/engine/recovery.py +0 -347
- tasklite_engine-2.2.1/tasklite/engine/resource.py +0 -656
- tasklite_engine-2.2.1/tasklite/engine/runtime.py +0 -626
- tasklite_engine-2.2.1/tasklite/engine/selection.py +0 -244
- tasklite_engine-2.2.1/tasklite/engine/session.py +0 -124
- tasklite_engine-2.2.1/tasklite/engine/store.py +0 -944
- tasklite_engine-2.2.1/tasklite/engine/types.py +0 -149
- tasklite_engine-2.2.1/tasklite/exceptions.py +0 -74
- tasklite_engine-2.2.1/tasklite/models/__init__.py +0 -11
- tasklite_engine-2.2.1/tasklite/models/artifact.py +0 -80
- tasklite_engine-2.2.1/tasklite/models/attempt.py +0 -141
- tasklite_engine-2.2.1/tasklite/models/context.py +0 -261
- tasklite_engine-2.2.1/tasklite/models/job.py +0 -417
- tasklite_engine-2.2.1/tasklite/pipeline.py +0 -709
- tasklite_engine-2.2.1/tasklite/selection.py +0 -116
- tasklite_engine-2.2.1/tasklite/utils/lockfile.py +0 -121
- tasklite_engine-2.2.1/tasklite_engine.egg-info/PKG-INFO +0 -370
- tasklite_engine-2.2.1/tests/test_exceptions.py +0 -99
- tasklite_engine-2.2.1/tests/test_hooks.py +0 -118
- tasklite_engine-2.2.1/tests/test_pipeline.py +0 -956
- tasklite_engine-2.2.1/tests/test_testing.py +0 -189
- tasklite_engine-2.2.1/tests/test_trigger_contract.py +0 -298
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/LICENSE +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/setup.cfg +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/contrib/__init__.py +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/models/trigger.py +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/py.typed +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/utils/__init__.py +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite/utils/jsonutil.py +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite_engine.egg-info/dependency_links.txt +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tasklite_engine.egg-info/top_level.txt +0 -0
- {tasklite_engine-2.2.1 → tasklite_engine-3.0.0.dev0}/tests/test_jsonutil.py +0 -0
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: tasklite-engine
|
|
3
|
+
Version: 3.0.0.dev0
|
|
4
|
+
Summary: A lightweight task orchestration engine with zero external dependencies, process isolation, and ACID persistence
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/CaptainLi321/tasklite
|
|
7
|
+
Project-URL: Repository, https://github.com/CaptainLi321/tasklite
|
|
8
|
+
Keywords: task-queue,task-orchestration,background-jobs,subprocess,process-isolation,acid,workflow
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Typing :: Typed
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: pytest; extra == "dev"
|
|
23
|
+
Requires-Dist: hypothesis>=6.0; extra == "dev"
|
|
24
|
+
Requires-Dist: mutmut>=3.0; extra == "dev"
|
|
25
|
+
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest-cov>=4.0; extra == "dev"
|
|
27
|
+
Requires-Dist: requests>=2.28; extra == "dev"
|
|
28
|
+
Requires-Dist: mypy>=1.0; extra == "dev"
|
|
29
|
+
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# ⚡ TaskLite — 零依赖、进程隔离的轻量任务编排引擎
|
|
33
|
+
|
|
34
|
+
> **A Lightweight Task Orchestration Engine for Agent & Batch Pipelines.**
|
|
35
|
+
> 专为 **AI Agent 批量处理**、数据同步与采集、音视频转码、离线 ETL 与后台批处理任务打造。
|
|
36
|
+
> 核心解决「单线程处理耗时长」、「中途失败需全量重跑」、「子任务卡死拖垮主流程」等工程痛点。采用主控守护与物理子进程隔离架构,内置 SQLite WAL 事务持久化:已提交终态跨进程保留;异常退出遗留的 `running` 下次启动按失败收敛,未派发的 `pending` 留队,不自动接续旧执行。
|
|
37
|
+
|
|
38
|
+
[](https://www.python.org/)
|
|
39
|
+
[](LICENSE)
|
|
40
|
+
[](https://github.com/CaptainLi321/tasklite/actions/workflows/ci.yml)
|
|
41
|
+
|
|
42
|
+
当前开发版本为 **3.0.0.dev0**,公开接口与兼容性说明见 [API 参考手册](docs/API.md)。
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 💡 为什么选择 TaskLite?
|
|
47
|
+
|
|
48
|
+
TaskLite 面向 AI Agent 批量调用、大模型推理批处理、多媒体文件处理与离线数据流转,提供**零依赖的单机任务编排能力**,通过 `pip install tasklite-engine` 即可安装。
|
|
49
|
+
|
|
50
|
+
1. **多 Worker 并发执行**:以独立子进程并行处理任务,支持配置并发数量与资源容量;
|
|
51
|
+
2. **持久状态防重跑**:以 SQLite WAL 事务表记录状态,已提交成功由后续 Trigger 判断是否跳过;handler 显式请求重试时按本次 Run 的预算重入队,预算耗尽后进入失败档案,减少个别失败导致的全量重跑;
|
|
52
|
+
3. **进程隔离与超时守护**:业务逻辑在独立子进程中运行,超时后终止执行并回收资源;已提交状态由 SQLite 持久保存,异常退出后的遗留执行按恢复规则收敛。
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 🏗️ 核心架构与设计哲学
|
|
57
|
+
|
|
58
|
+
```mermaid
|
|
59
|
+
flowchart TD
|
|
60
|
+
subgraph Host ["主调度进程 (Master Scheduler) - 永不运行业务 Handler"]
|
|
61
|
+
State[("SQLite WAL 状态机\n(Schema 6: successes / queue / failed / attempts)")]
|
|
62
|
+
Scheduler["JobScheduler (资源调度 / 拓扑依赖)"]
|
|
63
|
+
Watchdog["进程看门狗 (超时 SIGKILL / 单库级锁防护)"]
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
subgraph Workers ["独立 Worker 子进程 (Isolated Subprocesses)"]
|
|
67
|
+
W1["Worker 1 (Handler)"]
|
|
68
|
+
W2["Worker 2 (Handler)"]
|
|
69
|
+
WN["Worker N (Handler)"]
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
Scheduler -->|"1. 检查资源 & 拓扑依赖"| State
|
|
73
|
+
Scheduler -->|"2. Spawn 独立子进程 (隔离)"| Workers
|
|
74
|
+
Workers -.->|"3. 独立单向 Pipe 传递声明与 TaskResult"| State
|
|
75
|
+
Watchdog -->|"4. 轮询超时 SIGKILL 强杀"| Workers
|
|
76
|
+
State -->|"5. BEGIN IMMEDIATE 原子收尾"| State
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 三层可靠性边界
|
|
80
|
+
1. **执行代标识与通道绑定 (Generation Fencing)**:每 worker 绑定独立单向 `Pipe` 与执行代标识,校验 `job_uid` 与 `execution_id`,旧执行与伪造消息无法污染状态机;
|
|
81
|
+
2. **已结算状态事务持久化**:IPC 仅负责本次运行的瞬时通信;已提交成功、失败与 `attempts` 由 SQLite 强事务持久化。异常退出遗留的 `running` 下次按失败收敛,`pending` 留队,不自动接续旧执行;
|
|
82
|
+
3. **单库级文件锁防护 (Library Lock Fencing)**:通过 `__tasklite__.lock` 互斥保护,同一状态库同时只允许一个活动调度实例或管理写操作,避免并发写入破坏。
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 🌟 核心特性
|
|
87
|
+
|
|
88
|
+
### 1. 🛡️ 进程隔离与守护 (Process Isolation)
|
|
89
|
+
- 主进程作为总控调度器,不执行具体的业务代码;
|
|
90
|
+
- 每一个任务均在独立的 `spawn` 子进程中隔离执行;
|
|
91
|
+
- 当子进程发生死循环或超时,看门狗将在指定超时后发送 `SIGKILL` 强杀子进程并自动回收资源;
|
|
92
|
+
- 子进程发生异常退出或被操作系统终止时,不影响主调度进程的稳定运行。
|
|
93
|
+
|
|
94
|
+
### 2. ⚡ SQLite WAL 状态持久化 (ACID)
|
|
95
|
+
- 基于 SQLite WAL + `synchronous=FULL` 模式;
|
|
96
|
+
- 状态机(`successes` 成功档案 / `queue` 待办 / `failed` 失败档案 / `attempts` 轨迹)在单次事务中原子转移;
|
|
97
|
+
- 已提交终态不会因之后异常退出被改写;遗留 `running` 以“上次执行未完成结算,实际结果未知”登记失败,不根据残留产物或迟到结果补造成功。
|
|
98
|
+
|
|
99
|
+
### 3. 🔍 函数式增量探索 (Functional Discovery)
|
|
100
|
+
- 针对数据同步、采集与拉取场景的无游标 (Cursor-less) 增量扫描;
|
|
101
|
+
- 直接复用成功档案 (`successes`) 即时判定已见内容,整页命中自动刹车,天然免疫上游记录删除、插入导致的游标漂移。
|
|
102
|
+
|
|
103
|
+
### 4. ⏸️ 内置容量与限速控制 (Resource Control)
|
|
104
|
+
- 内置 `IntervalResource`(调用间隔限速)与 `CapacityResource`(并发量限制);
|
|
105
|
+
- 核心零调度计算,调度器以事件驱动等待与主动通知推进,避免轮询忙旋。
|
|
106
|
+
|
|
107
|
+
### 5. 🔗 DAG 拓扑依赖与级联熔断
|
|
108
|
+
- 任务通过 `depends_on` 声明依赖列表;
|
|
109
|
+
- 上游失败进入失败档案时,受影响下游按依赖规则级联失败;未执行的下游不生成 Attempt,避免无效计算。
|
|
110
|
+
|
|
111
|
+
### 6. 📦 统一文件声明与主进程清理授权
|
|
112
|
+
- `FileSpec` 明确文件角色(`output` / `input` / `cache`)与清理权限(`delete_existing` / `delete_on_failure` / `delete_on_success`);
|
|
113
|
+
- 主进程持有排他文件授权与清理职责,收尾时先执行授权清理后提交事务。
|
|
114
|
+
|
|
115
|
+
### 7. 🎛️ 运行排除与重试节奏
|
|
116
|
+
- 内置候选访问序与重入队机制;其内部策略接缝不属于本版稳定公开扩展面;
|
|
117
|
+
- `pipeline.run(exclude=Exclude(task_type="..."))` 支持按任务类型将作业安全留队至下次运行。
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 🚀 快速上手 (Quickstart)
|
|
122
|
+
|
|
123
|
+
### 安装
|
|
124
|
+
|
|
125
|
+
要求 **Python ≥ 3.10**,零外部依赖:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
pip install tasklite-engine
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
> **三方命名对照**:仓库名 `tasklite`,PyPI 包名 `tasklite-engine`(PyPI 的 `tasklite` 名已被无关项目占用),Python 导入名 `tasklite`——安装 `tasklite-engine`、`import tasklite`。
|
|
132
|
+
|
|
133
|
+
### 最小示例
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from tasklite import Job, StateSnapshot, TaskLite, TaskResult
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def greet(job, ctx):
|
|
140
|
+
return TaskResult.success(metadata={"message": f"你好,{job.payload['name']}"})
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
if __name__ == "__main__":
|
|
144
|
+
with TaskLite(backend="memory") as pipeline:
|
|
145
|
+
pipeline.register_task("greet", greet)
|
|
146
|
+
pipeline.enqueue(Job("greet", "one", payload={"name": "TaskLite"}))
|
|
147
|
+
pipeline.run()
|
|
148
|
+
pipeline.stop()
|
|
149
|
+
with StateSnapshot.open(pipeline) as state:
|
|
150
|
+
print(state.get_job("greet::one"))
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
> 引擎采用 **Task(静态规格) / Job(逻辑实例) / Attempt(物理轨迹)** 三层模型,完整 API 签名、只读快照(`StateSnapshot`)、文件授权、状态管理与运维接口请查阅 **[`docs/GUIDE.md`](docs/GUIDE.md)**(使用手册)。
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 🍳 常见场景速览 (Recipes)
|
|
158
|
+
|
|
159
|
+
### Recipe 1: 增量分页扫描器 (Discovery)
|
|
160
|
+
|
|
161
|
+
无需游标,增量同步时只要发现整页内容已全部处理过,自动刹车停止扫描:
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
from tasklite import TaskResult
|
|
165
|
+
from tasklite.wrappers.discovery import register_discovery
|
|
166
|
+
|
|
167
|
+
def fetch_page(job, ctx, page: int):
|
|
168
|
+
return api.get_author_posts(author_id=job.payload["author_id"], page=page)
|
|
169
|
+
|
|
170
|
+
def item_id(post) -> str:
|
|
171
|
+
return str(post["id"])
|
|
172
|
+
|
|
173
|
+
def process_item(job, ctx, post, content_id: str):
|
|
174
|
+
ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
|
|
175
|
+
|
|
176
|
+
register_discovery(
|
|
177
|
+
pipeline,
|
|
178
|
+
task_type="discover_author",
|
|
179
|
+
fetch_func=fetch_page,
|
|
180
|
+
id_func=item_id,
|
|
181
|
+
process_item_func=process_item,
|
|
182
|
+
process_task_type="download",
|
|
183
|
+
resources={"api": 1.0},
|
|
184
|
+
)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Recipe 2: DAG 依赖级联与产物传递
|
|
188
|
+
|
|
189
|
+
通过 `depends_on` 声明拓扑依赖,上游成功后再执行下游,上游失败则下游自动级联阻断(完整可运行示例见 [`examples/trigger_chain.py`](examples/trigger_chain.py)):
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
download_job = Job("download", "video_101", payload={"url": "https://example.com/v.mp4"})
|
|
193
|
+
transcode_job = Job(
|
|
194
|
+
"transcode",
|
|
195
|
+
"video_101",
|
|
196
|
+
payload={"preset": "1080p"},
|
|
197
|
+
depends_on=[download_job.uid], # 声明上游依赖
|
|
198
|
+
)
|
|
199
|
+
|
|
200
|
+
pipeline.enqueue(download_job)
|
|
201
|
+
pipeline.enqueue(transcode_job)
|
|
202
|
+
pipeline.run()
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Recipe 3: 周期限速调用与重试
|
|
206
|
+
|
|
207
|
+
```python
|
|
208
|
+
from tasklite import TaskResult
|
|
209
|
+
|
|
210
|
+
def fetch_handler(job, ctx):
|
|
211
|
+
resp = requests.get(job.payload["url"])
|
|
212
|
+
if resp.status_code == 429:
|
|
213
|
+
# 请求重试并指明重试原因
|
|
214
|
+
return TaskResult.retry(message="Rate limited (429), retry later")
|
|
215
|
+
if resp.status_code != 200:
|
|
216
|
+
return TaskResult.failure(message=f"HTTP status {resp.status_code}")
|
|
217
|
+
return TaskResult.success(metadata=resp.json())
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### Recipe 4: AI Agent / 大模型批量任务持久化
|
|
221
|
+
|
|
222
|
+
```python
|
|
223
|
+
import json
|
|
224
|
+
from pathlib import Path
|
|
225
|
+
from tasklite import TaskLite, Task, Job, TaskResult, FileSpec
|
|
226
|
+
from tasklite.resource import IntervalResource
|
|
227
|
+
|
|
228
|
+
def agent_worker(job: Job, ctx) -> TaskResult:
|
|
229
|
+
result = call_llm(job.payload["prompt"])
|
|
230
|
+
out_file = ctx.declare_file(
|
|
231
|
+
"res",
|
|
232
|
+
FileSpec(f"results/{job.job_id}.json", role="output", delete_existing=True),
|
|
233
|
+
)
|
|
234
|
+
out_file.write_text(json.dumps(result, ensure_ascii=False), encoding="utf-8")
|
|
235
|
+
return TaskResult.success(metadata={"tokens": result.get("usage", 0)})
|
|
236
|
+
|
|
237
|
+
pipeline = TaskLite(backend="sqlite", state_path="./agent_state.db", max_workers=8)
|
|
238
|
+
pipeline.authorizer = lambda p, t: True
|
|
239
|
+
pipeline.register_resource(IntervalResource("llm_rpm", interval_seconds=0.1))
|
|
240
|
+
pipeline.register_task(Task("analyze", agent_worker, resources={"llm_rpm": 1.0}))
|
|
241
|
+
|
|
242
|
+
for i in range(100):
|
|
243
|
+
pipeline.enqueue(Job("analyze", f"doc_{i}", payload={"prompt": f"分析文本 {i}"}))
|
|
244
|
+
|
|
245
|
+
pipeline.run()
|
|
246
|
+
pipeline.stop()
|
|
247
|
+
pipeline.close()
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## 📚 文档导航与职责划分
|
|
253
|
+
|
|
254
|
+
仓库内各文档按受众与职责严格正交划分,避免重复维护:
|
|
255
|
+
|
|
256
|
+
| 文档 | 定位与职责 |
|
|
257
|
+
| :--- | :--- |
|
|
258
|
+
| **[`README.md`](README.md)** | **项目门户与快速上手**:解决痛点、架构概览、安装与最小示例、常见场景 Recipes 速览、目录结构 |
|
|
259
|
+
| **[`docs/GUIDE.md`](docs/GUIDE.md)** | **使用手册**:公开导入面、三层模型与 Schema 6、`JobContext` 与统一文件声明授权、失败档案与运维 API、调度扩展接缝 |
|
|
260
|
+
| **[`docs/API.md`](docs/API.md)** | **公开 API 权威参考手册**:全公开类、方法、属性签名、严格 JSON 规则、返回结构与异常契约速查 |
|
|
261
|
+
| **[`CONTEXT.md`](CONTEXT.md)** | **领域通用语言词典**:核心领域模型与引擎内部组件的标准术语定义及禁用词表 |
|
|
262
|
+
| **[`docs/adr/`](docs/adr/)** | **架构决策记录(ADR)**:关键架构演进、设计取舍与边界裁决依据 |
|
|
263
|
+
| **[`docs/ROADMAP.md`](docs/ROADMAP.md)** | **未来演进路线图**:已分析但尚未立项实施的储备方向(实施前须立项 ADR) |
|
|
264
|
+
| **[`AGENTS.md`](AGENTS.md)** | **研发红线与工作流规范**:测试门槛、原子提交纪律、分层依赖红线与注释规范 |
|
|
265
|
+
| **[`CHANGELOG.md`](CHANGELOG.md)** | **版本变更日志**:各发布版本的显著特性与破坏性变更记录 |
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## 📁 目录结构
|
|
270
|
+
|
|
271
|
+
```
|
|
272
|
+
tasklite/
|
|
273
|
+
├── pipeline.py # TaskLite 核心门面与装配
|
|
274
|
+
├── selection.py # 执行选择规则值对象 Exclude(候选准入 seam)
|
|
275
|
+
├── resource.py # 内置资源公共导出门面 (CapacityResource, IntervalResource)
|
|
276
|
+
├── snapshot.py # StateSnapshot:只读一致状态快照与标准 JSON 查询
|
|
277
|
+
├── exceptions.py # 异常族 (TaskLiteError)
|
|
278
|
+
├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造辅助
|
|
279
|
+
├── engine/ # 核心调度与执行引擎群
|
|
280
|
+
│ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
|
|
281
|
+
│ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
|
|
282
|
+
│ ├── session.py # RunSession 单次 run 生命周期状态
|
|
283
|
+
│ ├── wait.py # 事件泵等待/空闲决策纯函数
|
|
284
|
+
│ ├── types.py # 引擎公共值对象单一真相源
|
|
285
|
+
│ ├── store.py # 状态事务与失败写入隔离 (StateStore)
|
|
286
|
+
│ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
|
|
287
|
+
│ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
|
|
288
|
+
│ ├── completion.py # 任务完成与提交单一收口 (CompletionMachine)
|
|
289
|
+
│ ├── recovery.py # 遗留 running 收敛与在途中止编排 (RecoveryOrchestrator)
|
|
290
|
+
│ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel)
|
|
291
|
+
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy 排序 seam)
|
|
292
|
+
│ ├── admission.py # 重入队节奏 (RequeuePolicy seam)
|
|
293
|
+
│ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
|
|
294
|
+
│ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
|
|
295
|
+
│ └── resource.py # 内置资源实现
|
|
296
|
+
├── backend/ # SQLite WAL 强一致事务持久化后端与内存后端
|
|
297
|
+
├── models/ # Task / Job / Attempt / JobContext / TaskResult / FileSpec 数据模型
|
|
298
|
+
├── wrappers/ # 可选工具:discovery.py(增量扫描)/ http.py(网络守卫与快照)
|
|
299
|
+
├── contrib/ # 生态扩展套件与参考实现(核心不反向依赖)
|
|
300
|
+
└── utils/ # 单射编码 (%XX 转义) / 瞬时 Pipe 通道 / 文件锁 / 时钟 / JSON 校验
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
## 📄 开源许可证
|
|
306
|
+
|
|
307
|
+
本项目基于 [MIT License](LICENSE) 开源。
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
# ⚡ TaskLite — 零依赖、进程隔离的轻量任务编排引擎
|
|
2
|
+
|
|
3
|
+
> **A Lightweight Task Orchestration Engine for Agent & Batch Pipelines.**
|
|
4
|
+
> 专为 **AI Agent 批量处理**、数据同步与采集、音视频转码、离线 ETL 与后台批处理任务打造。
|
|
5
|
+
> 核心解决「单线程处理耗时长」、「中途失败需全量重跑」、「子任务卡死拖垮主流程」等工程痛点。采用主控守护与物理子进程隔离架构,内置 SQLite WAL 事务持久化:已提交终态跨进程保留;异常退出遗留的 `running` 下次启动按失败收敛,未派发的 `pending` 留队,不自动接续旧执行。
|
|
6
|
+
|
|
7
|
+
[](https://www.python.org/)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](https://github.com/CaptainLi321/tasklite/actions/workflows/ci.yml)
|
|
10
|
+
|
|
11
|
+
当前开发版本为 **3.0.0.dev0**,公开接口与兼容性说明见 [API 参考手册](docs/API.md)。
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 💡 为什么选择 TaskLite?
|
|
16
|
+
|
|
17
|
+
TaskLite 面向 AI Agent 批量调用、大模型推理批处理、多媒体文件处理与离线数据流转,提供**零依赖的单机任务编排能力**,通过 `pip install tasklite-engine` 即可安装。
|
|
18
|
+
|
|
19
|
+
1. **多 Worker 并发执行**:以独立子进程并行处理任务,支持配置并发数量与资源容量;
|
|
20
|
+
2. **持久状态防重跑**:以 SQLite WAL 事务表记录状态,已提交成功由后续 Trigger 判断是否跳过;handler 显式请求重试时按本次 Run 的预算重入队,预算耗尽后进入失败档案,减少个别失败导致的全量重跑;
|
|
21
|
+
3. **进程隔离与超时守护**:业务逻辑在独立子进程中运行,超时后终止执行并回收资源;已提交状态由 SQLite 持久保存,异常退出后的遗留执行按恢复规则收敛。
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 🏗️ 核心架构与设计哲学
|
|
26
|
+
|
|
27
|
+
```mermaid
|
|
28
|
+
flowchart TD
|
|
29
|
+
subgraph Host ["主调度进程 (Master Scheduler) - 永不运行业务 Handler"]
|
|
30
|
+
State[("SQLite WAL 状态机\n(Schema 6: successes / queue / failed / attempts)")]
|
|
31
|
+
Scheduler["JobScheduler (资源调度 / 拓扑依赖)"]
|
|
32
|
+
Watchdog["进程看门狗 (超时 SIGKILL / 单库级锁防护)"]
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
subgraph Workers ["独立 Worker 子进程 (Isolated Subprocesses)"]
|
|
36
|
+
W1["Worker 1 (Handler)"]
|
|
37
|
+
W2["Worker 2 (Handler)"]
|
|
38
|
+
WN["Worker N (Handler)"]
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
Scheduler -->|"1. 检查资源 & 拓扑依赖"| State
|
|
42
|
+
Scheduler -->|"2. Spawn 独立子进程 (隔离)"| Workers
|
|
43
|
+
Workers -.->|"3. 独立单向 Pipe 传递声明与 TaskResult"| State
|
|
44
|
+
Watchdog -->|"4. 轮询超时 SIGKILL 强杀"| Workers
|
|
45
|
+
State -->|"5. BEGIN IMMEDIATE 原子收尾"| State
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### 三层可靠性边界
|
|
49
|
+
1. **执行代标识与通道绑定 (Generation Fencing)**:每 worker 绑定独立单向 `Pipe` 与执行代标识,校验 `job_uid` 与 `execution_id`,旧执行与伪造消息无法污染状态机;
|
|
50
|
+
2. **已结算状态事务持久化**:IPC 仅负责本次运行的瞬时通信;已提交成功、失败与 `attempts` 由 SQLite 强事务持久化。异常退出遗留的 `running` 下次按失败收敛,`pending` 留队,不自动接续旧执行;
|
|
51
|
+
3. **单库级文件锁防护 (Library Lock Fencing)**:通过 `__tasklite__.lock` 互斥保护,同一状态库同时只允许一个活动调度实例或管理写操作,避免并发写入破坏。
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 🌟 核心特性
|
|
56
|
+
|
|
57
|
+
### 1. 🛡️ 进程隔离与守护 (Process Isolation)
|
|
58
|
+
- 主进程作为总控调度器,不执行具体的业务代码;
|
|
59
|
+
- 每一个任务均在独立的 `spawn` 子进程中隔离执行;
|
|
60
|
+
- 当子进程发生死循环或超时,看门狗将在指定超时后发送 `SIGKILL` 强杀子进程并自动回收资源;
|
|
61
|
+
- 子进程发生异常退出或被操作系统终止时,不影响主调度进程的稳定运行。
|
|
62
|
+
|
|
63
|
+
### 2. ⚡ SQLite WAL 状态持久化 (ACID)
|
|
64
|
+
- 基于 SQLite WAL + `synchronous=FULL` 模式;
|
|
65
|
+
- 状态机(`successes` 成功档案 / `queue` 待办 / `failed` 失败档案 / `attempts` 轨迹)在单次事务中原子转移;
|
|
66
|
+
- 已提交终态不会因之后异常退出被改写;遗留 `running` 以“上次执行未完成结算,实际结果未知”登记失败,不根据残留产物或迟到结果补造成功。
|
|
67
|
+
|
|
68
|
+
### 3. 🔍 函数式增量探索 (Functional Discovery)
|
|
69
|
+
- 针对数据同步、采集与拉取场景的无游标 (Cursor-less) 增量扫描;
|
|
70
|
+
- 直接复用成功档案 (`successes`) 即时判定已见内容,整页命中自动刹车,天然免疫上游记录删除、插入导致的游标漂移。
|
|
71
|
+
|
|
72
|
+
### 4. ⏸️ 内置容量与限速控制 (Resource Control)
|
|
73
|
+
- 内置 `IntervalResource`(调用间隔限速)与 `CapacityResource`(并发量限制);
|
|
74
|
+
- 核心零调度计算,调度器以事件驱动等待与主动通知推进,避免轮询忙旋。
|
|
75
|
+
|
|
76
|
+
### 5. 🔗 DAG 拓扑依赖与级联熔断
|
|
77
|
+
- 任务通过 `depends_on` 声明依赖列表;
|
|
78
|
+
- 上游失败进入失败档案时,受影响下游按依赖规则级联失败;未执行的下游不生成 Attempt,避免无效计算。
|
|
79
|
+
|
|
80
|
+
### 6. 📦 统一文件声明与主进程清理授权
|
|
81
|
+
- `FileSpec` 明确文件角色(`output` / `input` / `cache`)与清理权限(`delete_existing` / `delete_on_failure` / `delete_on_success`);
|
|
82
|
+
- 主进程持有排他文件授权与清理职责,收尾时先执行授权清理后提交事务。
|
|
83
|
+
|
|
84
|
+
### 7. 🎛️ 运行排除与重试节奏
|
|
85
|
+
- 内置候选访问序与重入队机制;其内部策略接缝不属于本版稳定公开扩展面;
|
|
86
|
+
- `pipeline.run(exclude=Exclude(task_type="..."))` 支持按任务类型将作业安全留队至下次运行。
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 🚀 快速上手 (Quickstart)
|
|
91
|
+
|
|
92
|
+
### 安装
|
|
93
|
+
|
|
94
|
+
要求 **Python ≥ 3.10**,零外部依赖:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
pip install tasklite-engine
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
> **三方命名对照**:仓库名 `tasklite`,PyPI 包名 `tasklite-engine`(PyPI 的 `tasklite` 名已被无关项目占用),Python 导入名 `tasklite`——安装 `tasklite-engine`、`import tasklite`。
|
|
101
|
+
|
|
102
|
+
### 最小示例
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from tasklite import Job, StateSnapshot, TaskLite, TaskResult
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def greet(job, ctx):
|
|
109
|
+
return TaskResult.success(metadata={"message": f"你好,{job.payload['name']}"})
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
if __name__ == "__main__":
|
|
113
|
+
with TaskLite(backend="memory") as pipeline:
|
|
114
|
+
pipeline.register_task("greet", greet)
|
|
115
|
+
pipeline.enqueue(Job("greet", "one", payload={"name": "TaskLite"}))
|
|
116
|
+
pipeline.run()
|
|
117
|
+
pipeline.stop()
|
|
118
|
+
with StateSnapshot.open(pipeline) as state:
|
|
119
|
+
print(state.get_job("greet::one"))
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
> 引擎采用 **Task(静态规格) / Job(逻辑实例) / Attempt(物理轨迹)** 三层模型,完整 API 签名、只读快照(`StateSnapshot`)、文件授权、状态管理与运维接口请查阅 **[`docs/GUIDE.md`](docs/GUIDE.md)**(使用手册)。
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 🍳 常见场景速览 (Recipes)
|
|
127
|
+
|
|
128
|
+
### Recipe 1: 增量分页扫描器 (Discovery)
|
|
129
|
+
|
|
130
|
+
无需游标,增量同步时只要发现整页内容已全部处理过,自动刹车停止扫描:
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
from tasklite import TaskResult
|
|
134
|
+
from tasklite.wrappers.discovery import register_discovery
|
|
135
|
+
|
|
136
|
+
def fetch_page(job, ctx, page: int):
|
|
137
|
+
return api.get_author_posts(author_id=job.payload["author_id"], page=page)
|
|
138
|
+
|
|
139
|
+
def item_id(post) -> str:
|
|
140
|
+
return str(post["id"])
|
|
141
|
+
|
|
142
|
+
def process_item(job, ctx, post, content_id: str):
|
|
143
|
+
ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
|
|
144
|
+
|
|
145
|
+
register_discovery(
|
|
146
|
+
pipeline,
|
|
147
|
+
task_type="discover_author",
|
|
148
|
+
fetch_func=fetch_page,
|
|
149
|
+
id_func=item_id,
|
|
150
|
+
process_item_func=process_item,
|
|
151
|
+
process_task_type="download",
|
|
152
|
+
resources={"api": 1.0},
|
|
153
|
+
)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Recipe 2: DAG 依赖级联与产物传递
|
|
157
|
+
|
|
158
|
+
通过 `depends_on` 声明拓扑依赖,上游成功后再执行下游,上游失败则下游自动级联阻断(完整可运行示例见 [`examples/trigger_chain.py`](examples/trigger_chain.py)):
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
download_job = Job("download", "video_101", payload={"url": "https://example.com/v.mp4"})
|
|
162
|
+
transcode_job = Job(
|
|
163
|
+
"transcode",
|
|
164
|
+
"video_101",
|
|
165
|
+
payload={"preset": "1080p"},
|
|
166
|
+
depends_on=[download_job.uid], # 声明上游依赖
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
pipeline.enqueue(download_job)
|
|
170
|
+
pipeline.enqueue(transcode_job)
|
|
171
|
+
pipeline.run()
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Recipe 3: 周期限速调用与重试
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
from tasklite import TaskResult
|
|
178
|
+
|
|
179
|
+
def fetch_handler(job, ctx):
|
|
180
|
+
resp = requests.get(job.payload["url"])
|
|
181
|
+
if resp.status_code == 429:
|
|
182
|
+
# 请求重试并指明重试原因
|
|
183
|
+
return TaskResult.retry(message="Rate limited (429), retry later")
|
|
184
|
+
if resp.status_code != 200:
|
|
185
|
+
return TaskResult.failure(message=f"HTTP status {resp.status_code}")
|
|
186
|
+
return TaskResult.success(metadata=resp.json())
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Recipe 4: AI Agent / 大模型批量任务持久化
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
import json
|
|
193
|
+
from pathlib import Path
|
|
194
|
+
from tasklite import TaskLite, Task, Job, TaskResult, FileSpec
|
|
195
|
+
from tasklite.resource import IntervalResource
|
|
196
|
+
|
|
197
|
+
def agent_worker(job: Job, ctx) -> TaskResult:
|
|
198
|
+
result = call_llm(job.payload["prompt"])
|
|
199
|
+
out_file = ctx.declare_file(
|
|
200
|
+
"res",
|
|
201
|
+
FileSpec(f"results/{job.job_id}.json", role="output", delete_existing=True),
|
|
202
|
+
)
|
|
203
|
+
out_file.write_text(json.dumps(result, ensure_ascii=False), encoding="utf-8")
|
|
204
|
+
return TaskResult.success(metadata={"tokens": result.get("usage", 0)})
|
|
205
|
+
|
|
206
|
+
pipeline = TaskLite(backend="sqlite", state_path="./agent_state.db", max_workers=8)
|
|
207
|
+
pipeline.authorizer = lambda p, t: True
|
|
208
|
+
pipeline.register_resource(IntervalResource("llm_rpm", interval_seconds=0.1))
|
|
209
|
+
pipeline.register_task(Task("analyze", agent_worker, resources={"llm_rpm": 1.0}))
|
|
210
|
+
|
|
211
|
+
for i in range(100):
|
|
212
|
+
pipeline.enqueue(Job("analyze", f"doc_{i}", payload={"prompt": f"分析文本 {i}"}))
|
|
213
|
+
|
|
214
|
+
pipeline.run()
|
|
215
|
+
pipeline.stop()
|
|
216
|
+
pipeline.close()
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## 📚 文档导航与职责划分
|
|
222
|
+
|
|
223
|
+
仓库内各文档按受众与职责严格正交划分,避免重复维护:
|
|
224
|
+
|
|
225
|
+
| 文档 | 定位与职责 |
|
|
226
|
+
| :--- | :--- |
|
|
227
|
+
| **[`README.md`](README.md)** | **项目门户与快速上手**:解决痛点、架构概览、安装与最小示例、常见场景 Recipes 速览、目录结构 |
|
|
228
|
+
| **[`docs/GUIDE.md`](docs/GUIDE.md)** | **使用手册**:公开导入面、三层模型与 Schema 6、`JobContext` 与统一文件声明授权、失败档案与运维 API、调度扩展接缝 |
|
|
229
|
+
| **[`docs/API.md`](docs/API.md)** | **公开 API 权威参考手册**:全公开类、方法、属性签名、严格 JSON 规则、返回结构与异常契约速查 |
|
|
230
|
+
| **[`CONTEXT.md`](CONTEXT.md)** | **领域通用语言词典**:核心领域模型与引擎内部组件的标准术语定义及禁用词表 |
|
|
231
|
+
| **[`docs/adr/`](docs/adr/)** | **架构决策记录(ADR)**:关键架构演进、设计取舍与边界裁决依据 |
|
|
232
|
+
| **[`docs/ROADMAP.md`](docs/ROADMAP.md)** | **未来演进路线图**:已分析但尚未立项实施的储备方向(实施前须立项 ADR) |
|
|
233
|
+
| **[`AGENTS.md`](AGENTS.md)** | **研发红线与工作流规范**:测试门槛、原子提交纪律、分层依赖红线与注释规范 |
|
|
234
|
+
| **[`CHANGELOG.md`](CHANGELOG.md)** | **版本变更日志**:各发布版本的显著特性与破坏性变更记录 |
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## 📁 目录结构
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
tasklite/
|
|
242
|
+
├── pipeline.py # TaskLite 核心门面与装配
|
|
243
|
+
├── selection.py # 执行选择规则值对象 Exclude(候选准入 seam)
|
|
244
|
+
├── resource.py # 内置资源公共导出门面 (CapacityResource, IntervalResource)
|
|
245
|
+
├── snapshot.py # StateSnapshot:只读一致状态快照与标准 JSON 查询
|
|
246
|
+
├── exceptions.py # 异常族 (TaskLiteError)
|
|
247
|
+
├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造辅助
|
|
248
|
+
├── engine/ # 核心调度与执行引擎群
|
|
249
|
+
│ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
|
|
250
|
+
│ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
|
|
251
|
+
│ ├── session.py # RunSession 单次 run 生命周期状态
|
|
252
|
+
│ ├── wait.py # 事件泵等待/空闲决策纯函数
|
|
253
|
+
│ ├── types.py # 引擎公共值对象单一真相源
|
|
254
|
+
│ ├── store.py # 状态事务与失败写入隔离 (StateStore)
|
|
255
|
+
│ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
|
|
256
|
+
│ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
|
|
257
|
+
│ ├── completion.py # 任务完成与提交单一收口 (CompletionMachine)
|
|
258
|
+
│ ├── recovery.py # 遗留 running 收敛与在途中止编排 (RecoveryOrchestrator)
|
|
259
|
+
│ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel)
|
|
260
|
+
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy 排序 seam)
|
|
261
|
+
│ ├── admission.py # 重入队节奏 (RequeuePolicy seam)
|
|
262
|
+
│ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
|
|
263
|
+
│ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
|
|
264
|
+
│ └── resource.py # 内置资源实现
|
|
265
|
+
├── backend/ # SQLite WAL 强一致事务持久化后端与内存后端
|
|
266
|
+
├── models/ # Task / Job / Attempt / JobContext / TaskResult / FileSpec 数据模型
|
|
267
|
+
├── wrappers/ # 可选工具:discovery.py(增量扫描)/ http.py(网络守卫与快照)
|
|
268
|
+
├── contrib/ # 生态扩展套件与参考实现(核心不反向依赖)
|
|
269
|
+
└── utils/ # 单射编码 (%XX 转义) / 瞬时 Pipe 通道 / 文件锁 / 时钟 / JSON 校验
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## 📄 开源许可证
|
|
275
|
+
|
|
276
|
+
本项目基于 [MIT License](LICENSE) 开源。
|
|
@@ -30,7 +30,7 @@ Homepage = "https://github.com/CaptainLi321/tasklite"
|
|
|
30
30
|
Repository = "https://github.com/CaptainLi321/tasklite"
|
|
31
31
|
|
|
32
32
|
[project.optional-dependencies]
|
|
33
|
-
dev = ["pytest", "hypothesis>=6.0", "mutmut>=3.0", "pytest-timeout>=2.0", "pytest-cov>=4.0", "requests>=2.28", "mypy>=1.0"]
|
|
33
|
+
dev = ["pytest", "hypothesis>=6.0", "mutmut>=3.0", "pytest-timeout>=2.0", "pytest-cov>=4.0", "requests>=2.28", "mypy>=1.0", "tomli>=2.0; python_version < '3.11'"]
|
|
34
34
|
|
|
35
35
|
[tool.setuptools.packages.find]
|
|
36
36
|
include = ["tasklite", "tasklite.*"]
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""TaskLite:Task/Job/Attempt 三层模型的任务编排引擎(ADR-0004 / ADR-0005 / ADR-0011)。
|
|
2
|
+
|
|
3
|
+
模型:Task 为进程内注册的静态规格模板;Job 为具有稳定身份的逻辑实例
|
|
4
|
+
(uid = task_type::job_id);TaskResult 为 handler 唯一合法返回类型;
|
|
5
|
+
Attempt 为 append-only 的执行轨迹。
|
|
6
|
+
|
|
7
|
+
公开面:根包仅导出 ADR-0011 契约已定的核心 10 个名称:
|
|
8
|
+
TaskLite, Task, Job, JobContext, TaskResult, FileSpec,
|
|
9
|
+
StateSnapshot, TaskLiteError, make_job_uid, parse_job_uid。
|
|
10
|
+
内置资源从 tasklite.resource 导入(CapacityResource, IntervalResource);
|
|
11
|
+
运行排除规则从 tasklite.selection 导入(Exclude)。
|
|
12
|
+
不在根包重复导出。``__version__`` 为版本单一事实源(pyproject 动态读取点)。
|
|
13
|
+
|
|
14
|
+
分层单向依赖红线:``tasklite/models/`` 严禁 import
|
|
15
|
+
``tasklite/engine/``(IPC 声明读写一律下沉 ``tasklite/utils/ipc.py``),
|
|
16
|
+
``tasklite/utils/`` 严禁 import ``tasklite/wrappers/``,核心层
|
|
17
|
+
(engine/backend/models/utils)严禁依赖 ``tasklite/contrib/``。
|
|
18
|
+
"""
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
__version__ = "3.0.0.dev0"
|
|
22
|
+
|
|
23
|
+
# ── 门面与执行核心 ────────────────────────────────────────────────────
|
|
24
|
+
from .pipeline import TaskLite
|
|
25
|
+
|
|
26
|
+
# ── 模型层:规格 / 实例 / 结果 / 上下文 / 文件 ────────────────────────
|
|
27
|
+
from .models.task import Task
|
|
28
|
+
from .models.job import Job
|
|
29
|
+
from .models.context import JobContext
|
|
30
|
+
from .models.result import TaskResult
|
|
31
|
+
from .models.artifact import FileSpec
|
|
32
|
+
|
|
33
|
+
# ── 只读观察快照 ───────────────────────────────────────────────────────
|
|
34
|
+
from .snapshot import StateSnapshot
|
|
35
|
+
|
|
36
|
+
# ── 异常族 ───────────────────────────────────────────────────────────
|
|
37
|
+
from .exceptions import TaskLiteError
|
|
38
|
+
|
|
39
|
+
# ── 身份工具 ─────────────────────────────────────────────────────────
|
|
40
|
+
from .utils.encoding import make_job_uid, parse_job_uid
|
|
41
|
+
|
|
42
|
+
__all__ = [
|
|
43
|
+
"TaskLite",
|
|
44
|
+
"Task",
|
|
45
|
+
"Job",
|
|
46
|
+
"JobContext",
|
|
47
|
+
"TaskResult",
|
|
48
|
+
"FileSpec",
|
|
49
|
+
"StateSnapshot",
|
|
50
|
+
"TaskLiteError",
|
|
51
|
+
"make_job_uid",
|
|
52
|
+
"parse_job_uid",
|
|
53
|
+
]
|
|
@@ -6,18 +6,15 @@
|
|
|
6
6
|
"""
|
|
7
7
|
from .base import (
|
|
8
8
|
AbstractStateBackend,
|
|
9
|
-
validate_attempt_dispatch,
|
|
10
|
-
validate_attempt_finish,
|
|
11
9
|
validate_queue_replacement,
|
|
12
10
|
)
|
|
13
11
|
from .memory import InMemoryStateBackend
|
|
14
|
-
from .sqlite_backend import SQLiteStateBackend
|
|
12
|
+
from .sqlite_backend import SQLiteStateBackend, TARGET_SCHEMA_VERSION
|
|
15
13
|
|
|
16
14
|
__all__ = [
|
|
17
15
|
"AbstractStateBackend",
|
|
18
16
|
"InMemoryStateBackend",
|
|
19
17
|
"SQLiteStateBackend",
|
|
20
|
-
"
|
|
21
|
-
"validate_attempt_finish",
|
|
18
|
+
"TARGET_SCHEMA_VERSION",
|
|
22
19
|
"validate_queue_replacement",
|
|
23
20
|
]
|